feat(ai, ai-harness): add the harness stack with 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.
+- `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-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/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/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.

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

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

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

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

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

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

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

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

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