feat(ai, ai-harness): add the harness stack with coding tools, durable work, replay, and adapter parity

.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) })
+```

.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`.

.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.

.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.

.changeset/anthropic-thinking-shape.md

@@ -0,0 +1,16 @@
+---
+'@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.
+
+- `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. On Anthropic's own API, `anthropicText` and `createAnthropicChat` turn it on for `claude-fable-5-1`, `claude-opus-5`, and `claude-opus-5-5` without a `reasoning` config. A custom `baseURL`, `fetch`, client, or `ANTHROPIC_BASE_URL` turns that default off.
+- `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.

.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.

.changeset/cloudflare-binding-fetch.md

@@ -0,0 +1,9 @@
+---
+'@tanstack/ai-cloudflare': minor
+---
+
+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.
+- A Cloudflare error body is rewrapped so the SDK reports its message.

.changeset/compaction-background.md

@@ -0,0 +1,11 @@
+---
+'@tanstack/ai-compaction': minor
+---
+
+Prepare a compaction summary in the background with `withCompaction({ background: { atTokens } })`.
+
+- When the count at a model call is over `atTokens` and not over `maxTokens`, the strategy runs on a copy of the messages. The model call does not wait for it.
+- The result waits in the metadata store (namespace `@tanstack/ai-compaction:background`), or in memory without one. It applies at the first model call of the next run: as a `tanstack.compaction` record on a durable host, or as the checkpoint.
+- A model call over `maxTokens` while the summary runs waits for it and applies it. It compacts inline only when the list is still over `maxTokens`.
+- A result whose kept message is gone, because a newer compaction cut further, is dropped. `compaction:ended` and `onCompact` report it with `stale: true`. A failed summary is reported with `error` and applies nothing.
+- `CompactionReason` has a new value, `'background'`. Setup throws when `atTokens` is not below `maxTokens`.

.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.

.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.

.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.

.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.

.changeset/dashboard-pair-again-and-open-thread.md

@@ -0,0 +1,10 @@
+---
+'@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.** A host that sets `allowRemoteStart` gets an "Open a thread" form in its row. The host sends the flag in its hello, and for other hosts the open route answers `403` with `remote_start_disabled`. A message sent right after the open waits for the thread.
+- **Refusals stay visible.** A refused input shows as "Refused:" with the reason, also in a view that you open later. A refused thread keeps its harness name in the sessions list.

.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.

.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>`.

.changeset/fork-ready-g10-question-url.md

@@ -0,0 +1,8 @@
+---
+'@tanstack/ai-harness': minor
+'@tanstack/ai-mcp': minor
+---
+
+A question can now have a `url`. `ctx.session.ask({ message, url })` sends the link to clients in the question event, in `snapshot().pendingQuestions`, and in the view state. The user opens the page, then answers. The session does not open the page.
+
+`mcp()` and `mcpConnector` now ask the user when an MCP server asks for input in a tool call. A form request becomes a session question with the requested schema. A URL request becomes a question with the `url`. The answer goes back to the server. The form content is `accept`, and `{ action: 'decline' }` and `{ action: 'cancel' }` decline or cancel. The harness MCP clients now declare URL elicitation. `chat()` does not change.

.changeset/fork-ready-g11-session-search.md

@@ -0,0 +1,6 @@
+---
+'@tanstack/ai-persistence': minor
+'@tanstack/ai-harness': minor
+---
+
+Search and filter the session list. `SessionIndexListOptions` has `search` (title text, without case), `harness`, and `metadata` (exact string values). The memory store and the conformance suite support them. `GET sessions` lists only the sessions of the harness of the handler, and reads the `search` and `metadata.<key>` query parameters. `listSessions` of the client sends `search` and `metadata`.

.changeset/fork-ready-g1a-wrapfetch-core.md

@@ -0,0 +1,5 @@
+---
+'@tanstack/ai': minor
+---
+
+Add `wrapFetch` to `chat()`, to the middleware `onConfig` config, and to `TextOptions`. A wrapper gets the next fetch and gives back a new fetch, so it can change the HTTP request and response of a model call. The engine chains the `chat()` option and the middleware wrappers into one function. A middleware wrapper applies to one model call only. The new `FetchWrapper` type names the wrapper.

.changeset/fork-ready-g1b-wrapfetch-openai-base.md

@@ -0,0 +1,6 @@
+---
+'@tanstack/openai-base': minor
+'@tanstack/ai-openai': patch
+---
+
+The Chat Completions and Responses text adapters now support `wrapFetch`. When a call sets `wrapFetch`, the adapter sends its HTTP requests through the wrapper. The client of the adapter does not change for other calls. Every adapter that builds on `@tanstack/openai-base` gets this, for example OpenAI, Azure OpenAI, Grok, Groq, and Bedrock. Without `wrapFetch`, the requests do not change.

.changeset/fork-ready-g1c-wrapfetch-other-adapters.md

@@ -0,0 +1,8 @@
+---
+'@tanstack/ai-anthropic': patch
+'@tanstack/ai-mistral': patch
+'@tanstack/ai-ollama': patch
+'@tanstack/ai-openrouter': patch
+---
+
+The Anthropic, Mistral, Ollama, and OpenRouter text adapters now send each model request through the `wrapFetch` of the call. Without `wrapFetch`, the request does not change. An Anthropic or Ollama adapter with an injected client ignores `wrapFetch`, because the adapter cannot reach the fetch of that client.

.changeset/fork-ready-g2-native-compaction.md

@@ -0,0 +1,11 @@
+---
+'@tanstack/ai': minor
+'@tanstack/ai-compaction': minor
+'@tanstack/openai-base': minor
+---
+
+A text adapter can now have an optional `compact(options)` method. It sends the history to the provider's own compaction endpoint, and resolves to the history for the next calls. The options are `TextCompactOptions`: `messages`, `model`, `signal`, and `wrapFetch`.
+
+The OpenAI Responses adapters implement `compact` with `POST /responses/compact`. The encrypted `compaction` item goes back to the same model as it is on later requests.
+
+`withCompaction` has a new `native` option. Pass the adapter of the `chat()` call. When the adapter has `compact`, it runs in place of `strategy`. When `compact` fails, `strategy` runs. Without the option, nothing changes.

.changeset/fork-ready-g3-provider-coverage.md

@@ -0,0 +1,10 @@
+---
+'@tanstack/openai-base': minor
+'@tanstack/ai-openai': minor
+---
+
+The adapters now work with GitHub Copilot and with a ChatGPT plan token.
+
+- The Responses adapter streams one tool call when the item id changes on each event. GitHub Copilot sends a new item id on each event of a stateless response.
+- The OpenAI-compatible Chat Completions adapter reads the thinking that GitHub Copilot streams on `delta.reasoning_text`.
+- The OpenAI-compatible docs list more providers and show the setup for GitHub Copilot and for a ChatGPT plan.

.changeset/fork-ready-g4-revert.md

@@ -0,0 +1,7 @@
+---
+'@tanstack/ai-harness': minor
+---
+
+A session can now go back to any earlier message. `session.revert(messageId)` hides the later messages in the transcript, and `session.unrevert()` brings them back. With `snapshots()`, the files that the later tool calls changed go back too. The next prompt drops the hidden messages for good. The session saves the revert in the log, or in `stores.metadata` on a host without a log, so a restart keeps it.
+
+Clients send the new `revert` and `unrevert` inputs with `client.revert(messageId)` and `client.unrevert()`. The harness must list `'undo'` in `expose.commands`. A `harness.revert` event tells views to read the transcript again. Each `tanstack/snapshots:step` record now has the `toolCallIds` of its step.

.changeset/fork-ready-g5-live-reload.md

@@ -0,0 +1,7 @@
+---
+'@tanstack/ai-harness': minor
+---
+
+A session can now reload its plugins while it runs. `session.reload()` waits for the running turn, cleans up the session plugins, and sets them up again from `harness.plugins()`. The transcript, the log, the thread settings, and the inbox stay. Clients get a `harness.reloaded` event. If a new `setup` throws, the session keeps working with no plugins, and the promise rejects. `host.reload(harness)` reloads every open session of that harness. The `agents()` plugin reads its folders again at each reload.
+
+Plugins can now add and remove their own agents while the session runs, with `ctx.agents.set(agent)` and `ctx.agents.delete(name)`. A name that another plugin or the harness owns throws.

.changeset/fork-ready-g6-background-tool.md

@@ -0,0 +1,8 @@
+---
+'@tanstack/ai-harness': minor
+'@tanstack/ai': minor
+---
+
+A user can move a running tool call to the background. Send the `background` input or call `session.background(toolCallId?)`. The call returns at once, and the job keeps running. When the job ends, the model gets its result as a note, and an idle session wakes. `bash` and the single `subagent` tool support it. A client needs no `expose` entry for it.
+
+The tool context has a new optional `detach` field. A tool passes its work to `detach` and races the two promises to support the move.

.changeset/fork-ready-g7-continue-partial.md

@@ -0,0 +1,5 @@
+---
+'@tanstack/ai-harness': minor
+---
+
+`turn.onModelError` can answer `'continue'`. The partial text of the failed call stays in the turn result and in the transcript. The next model call gets that text and a note to continue it. `ModelErrorContext` has a new `partial` flag. `retryTransientErrors()` answers `'continue'` when the failed call streamed text, and `'retry'` otherwise. The `harness.turn.retry` event has a new `continued` field.

.changeset/fork-ready-g8-cwd-note.md

@@ -0,0 +1,5 @@
+---
+'@tanstack/ai-harness': patch
+---
+
+The model now hears when the working folder of a thread changes. When `session.configure()` sets a new `cwd`, or clears it with `null`, the transcript gets a short note before the next model call. The note names the new folder, or says that the default folder applies again. The same `cwd` again adds no note.

.changeset/fork-ready-g9-saved-permissions.md

@@ -0,0 +1,5 @@
+---
+'@tanstack/ai-harness': minor
+---
+
+`permissions()` has a `/permissions` command. It lists the saved "always" rules of the project. `/permissions forget <n>` deletes one, and the open session asks again at the next matching call. Server code can do the same with `listSavedPermissions` and `deleteSavedPermission` from `@tanstack/ai-harness/plugins`.