Merge branch 'main' into feat/billed-usage-unit

Author: season179

.changeset/client-browser-refresh-durability.md

@@ -0,0 +1,19 @@
+---
+'@tanstack/ai-client': minor
+'@tanstack/ai-react': minor
+'@tanstack/ai-solid': minor
+'@tanstack/ai-vue': minor
+'@tanstack/ai-svelte': minor
+'@tanstack/ai-angular': minor
+'@tanstack/ai-preact': minor
+---
+
+Add browser-refresh durability to the `persistence` option.
+
+The client `persistence` adapter now stores one combined record per chat id, the message transcript plus a resume snapshot, so a full page reload restores the conversation, rehydrates any pending interrupt, and rejoins a run that was still streaming (via `joinRun`, when the connection is durability-backed). A bare `UIMessage[]` from an older store is still read for backward compatibility.
+
+**If you hand-rolled a `persistence` adapter, update its write path.** `setItem` now receives the combined `{ messages, resume? }` record where it used to receive a bare `UIMessage[]`, so an adapter that assumed an array will write the new shape and then fail to parse it back — and because adapter reads are best-effort, the failure is silent: the conversation simply does not restore. Read `{ messages, resume? }` in `getItem` (a bare array is still accepted), or switch to the `localStoragePersistence` / `sessionStoragePersistence` / `indexedDBPersistence` adapters below, which handle it for you.
+
+The `persistence` option also accepts `true` for a server-authoritative chat: the client caches nothing, and on mount it hydrates the thread from the server by its `threadId` (painting the stored transcript and tailing any run still generating). Use it to keep large transcripts off the client while the server stays authoritative for history; it needs a connection with a `hydrate` handler and a server GET endpoint (`reconstructChat`). Passing an adapter is client-authoritative; omitting `persistence` (or `false`) is ephemeral, in-memory only.
+
+New web storage adapters are exported for this: `localStoragePersistence`, `sessionStoragePersistence`, and `indexedDBPersistence` (plus `StorageUnavailableError` and the `ChatPersistedState` / `ChatStorageAdapter` / `ChatPersistenceOption` types). Because durability rides the existing `persistence` option, every framework integration (`react`, `solid`, `vue`, `svelte`, `angular`, `preact`) gets it with no framework-specific code.

.changeset/define-lock.md

@@ -0,0 +1,25 @@
+---
+'@tanstack/ai': minor
+---
+
+Add `defineLock` to `@tanstack/ai/locks`: an identity typer for a `LockStore`
+implementation, matching the `define*Store` helpers in `@tanstack/ai-persistence`.
+Pass a `withLock` object and get autocomplete and contract checking inline, with
+no `: LockStore` annotation, then hand it to `withLocks`.
+
+```ts
+import { defineLock, withLocks } from '@tanstack/ai/locks'
+
+const locks = defineLock({
+  async withLock(key, fn) {
+    const { release, signal } = await acquire(key)
+    try {
+      return await fn(signal)
+    } finally {
+      release()
+    }
+  },
+})
+
+const middleware = [withLocks(locks)]
+```

.changeset/define-store-helpers.md

@@ -0,0 +1,31 @@
+---
+'@tanstack/ai-persistence': minor
+---
+
+Add per-store typer helpers: `defineMessageStore`, `defineRunStore`,
+`defineInterruptStore`, `defineMetadataStore`.
+
+Each takes a store implementation and returns it typed against the contract, so
+you get autocomplete and checking on the object literal inline — no separate
+`: MessageStore` return annotation. They compose into `defineAIPersistence`,
+which already infers **exact presence**: a store you define is a defined,
+non-optional, autocompleted key on `persistence.stores`, and accessing a store
+you did not define is a compile error.
+
+```ts
+import {
+  defineAIPersistence,
+  defineMessageStore,
+  defineRunStore,
+} from '@tanstack/ai-persistence'
+
+const persistence = defineAIPersistence({
+  stores: {
+    messages: defineMessageStore({ loadThread, saveThread }),
+    runs: defineRunStore({ createOrResume, update, get, findActiveRun }),
+  },
+})
+
+persistence.stores.runs // RunStore (defined)
+persistence.stores.interrupts // compile error — not provided
+```

.changeset/fast-fail-rejoin.md

@@ -0,0 +1,23 @@
+---
+'@tanstack/ai': minor
+'@tanstack/ai-client': patch
+---
+
+Make a reload rejoin fast, robust, and repeatable.
+
+- **`memoryStream` first-chunk deadline now defaults to 100ms** (was 30s). The
+  common from-start join is a reload rejoining a run whose producer ran in a
+  prior request: an in-flight run's log already holds chunks (it streams
+  immediately, the deadline never applies), and an empty log means the run is
+  gone — so failing fast lets the client re-enable input near-instantly instead
+  of holding a dead connection open. Raise `firstChunkDeadlineMs` for a backend
+  whose producer can legitimately start well after a joiner attaches.
+- **`ChatClient` reload rejoin hardened:** it bounds the wait for the first
+  chunk and clears a dead resume pointer (so a stale pointer can't pin the UI in
+  a loading state and can't be retried on the next load); it drops the hydrated
+  in-flight partial only when real content arrives (never on `RUN_STARTED`
+  alone), so a rejoin that connects but delivers nothing can't leave an empty
+  assistant bubble; and it no longer lets a replayed `RUN_STARTED` (which
+  carries the provider run id) overwrite the persisted resume pointer with an id
+  the durability log isn't keyed by — so a SECOND consecutive reload still
+  re-attaches and continues.

.changeset/fresh-client-tail.md

@@ -0,0 +1,41 @@
+---
+'@tanstack/ai-persistence': minor
+'@tanstack/ai-client': minor
+---
+
+Server-authoritative reconnect is now automatic and keyed on the thread, not the run.
+
+A chat's durable identity is its **thread**; run ids are ephemeral (a single turn
+can span several runs via interrupts or tool continuations), so basing reconnect
+on a client-cached run id goes stale the moment a turn rolls to a new run. This
+moves the whole reconnect story onto the stable thread id, resolved by the server.
+
+- **`RunStore.findActiveRun(threadId)`** — new optional, feature-detected store
+  method returning the most recent `'running'` run for a thread. Implemented by
+  the in-memory reference backend and covered by the conformance testkit, so any
+  adapter that provides it is held to the same invariants (most-recent-running
+  wins, thread-scoped, null when idle).
+- **`reconstructChat` now returns `{ messages, activeRun, interrupts }`** (was a
+  bare message array): the stored transcript as UI messages, a cursor to an
+  in-flight run if one exists, and any pending human-in-the-loop interrupts (tool
+  approvals / waits) plus the run they paused. It reads the active run before the
+  transcript so observing "no active run" guarantees the transcript is final
+  (closing a finish-window race).
+- **`@tanstack/ai-client` hydrates itself on mount.** In server-authoritative
+  mode (`persistence: true`) the client caches no transcript and no run
+  pointer: on mount `useChat`/`ChatClient` calls the connection's new
+  `hydrate(threadId)` (a JSON GET against the same endpoint), paints the returned
+  transcript, and — if a run is in flight — tails it via the existing `joinRun`
+  durability replay. A reload and the same thread opened on another device are the
+  identical, server-resolved path. No loader, no `initialMessages`, no
+  `initialResumeSnapshot`, no app-side fetching required.
+- **Interrupts reconstruct from the server too.** A paused approval (a tool with
+  `needsApproval`) is restored from `reconstructChat`'s `interrupts` exactly as a
+  persisted resume snapshot would be, so a reload — or another device — re-prompts
+  the same approve/reject decision and resumes the run it paused. Previously the
+  pending interrupt was only recoverable from client storage, so a fresh client
+  showed the paused tool call with no way to resolve it.
+
+Apps keep the single GET endpoint they already have (durability replay when a
+resume cursor is present, else `reconstructChat`); everything else is handled by
+the hook.

.changeset/locks-to-core.md

@@ -0,0 +1,13 @@
+---
+'@tanstack/ai': minor
+'@tanstack/ai-persistence': minor
+'@tanstack/ai-sandbox': minor
+---
+
+Move multi-instance **locks** to `@tanstack/ai` under a dedicated `@tanstack/ai/locks` subpath, and nest persistence agent skills like `ai-core`.
+
+- **`LockStore` / `InMemoryLockStore` / `LocksCapability` / `getLocks` / `provideLocks` / `withLocks`** live in `@tanstack/ai/locks` (not the main `@tanstack/ai` barrel, and not `@tanstack/ai-persistence`).
+- `@tanstack/ai-sandbox` consumes the core `LocksCapability` token (no local lock re-export).
+- The locks agent skill moves with the code: `ai-core/locks` in `@tanstack/ai`, not `ai-persistence/locks`.
+- Agent skills under `@tanstack/ai-persistence` nest as `skills/ai-persistence/{stores,server,build-*-adapter}/`.
+- Docs: locks guide under advanced middleware.

.changeset/max-tool-calls-middleware.md

@@ -0,0 +1,53 @@
+---
+'@tanstack/ai': minor
+---
+
+Rework tool-call fan-out budgets as middleware hooks (unreleased #965 API).
+
+- **Remove** (never released): `maxToolCalls()` strategy and `chat({ maxToolCallsPerTurn })`
+- **Add** `onShouldContinue` middleware hook so policies can stop further agent turns without aborting
+- **Keep** `AgentLoopState.toolCallCount` / `lastTurnToolCallCount` for strategies and middleware
+- Tool-call budgets are an **app-owned middleware recipe** (docs), not a built-in export
+
+```ts
+import { chat, maxIterations, type ChatMiddleware } from '@tanstack/ai'
+
+function toolCallBudget({
+  max,
+  maxPerTurn,
+}: {
+  max?: number
+  maxPerTurn?: number
+}): ChatMiddleware {
+  let perTurn = 0
+  return {
+    onIteration: () => {
+      perTurn = 0
+    },
+    onToolPhaseComplete: () => {
+      perTurn = 0
+    },
+    onBeforeToolCall: () => {
+      if (maxPerTurn == null) return
+      if (++perTurn > maxPerTurn) {
+        return {
+          type: 'skip',
+          result: {
+            error: `Skipped: exceeded maxToolCallsPerTurn (${maxPerTurn})`,
+          },
+        }
+      }
+    },
+    onShouldContinue: (_ctx, state) =>
+      max != null && state.toolCallCount >= max ? false : undefined,
+  }
+}
+
+chat({
+  adapter,
+  messages,
+  tools,
+  agentLoopStrategy: maxIterations(20),
+  middleware: [toolCallBudget({ maxPerTurn: 10, max: 20 })],
+})
+```

.changeset/memorystream-agent-loop-delivery.md

@@ -0,0 +1,22 @@
+---
+'@tanstack/ai': patch
+---
+
+Fix `memoryStream` truncating a tool-calling (agent-loop) run at its first tool
+call.
+
+An agent-loop run emits one `RUN_STARTED`/`RUN_FINISHED` pair per iteration
+(`finishReason: "tool_calls"` for a turn that calls a tool, then `"stop"` for the
+final answer). `memoryStream` treated the _first_ terminal chunk as the end of
+the log — both marking the log complete on append and ending the reader on read —
+so a run that called a tool was delivered only up to that first `RUN_FINISHED`:
+the tool result and everything after (the model's actual answer) never reached
+the client, leaving the tool call stuck "running" and the reply missing, on the
+initial stream and on any reconnect/reload.
+
+Completion is now driven solely by the producer calling `close()` (which it does
+on every exit — the documented `StreamDurability.close` contract, honored by
+`toServerSentEventsResponse`/`resumeServerSentEventsResponse` and detached
+producers). The reader tails across per-iteration terminals and ends when the
+producer closes, so a tool-calling run is delivered in full — live, on rejoin,
+and on a server-authoritative reload.

.changeset/persistence-packages.md

@@ -0,0 +1,21 @@
+---
+'@tanstack/ai-persistence': minor
+---
+
+Add server-side persistence for `chat()`: durable thread messages, run records, and interrupts.
+
+`withPersistence(persistence)` is a chat middleware that stores the conversation transcript, tracks each run's status, and records interrupt state so a paused run (tool approval, client-tool execution, generic interrupt) survives a server restart.
+
+`@tanstack/ai-persistence` ships the **contract**, not a backend for your database:
+
+- The four store interfaces — `MessageStore`, `RunStore`, `InterruptStore`, `MetadataStore` — with the invariants the middleware depends on (full-replace `saveThread`, idempotent `createOrResume`, insert-if-absent interrupt `create`, `requestedAt`-ascending listings).
+- The `withPersistence` / `withGenerationPersistence` middleware, plus `composePersistence` to assemble stores that live in different systems.
+- `memoryPersistence()`, an in-process reference backend for dev and tests.
+- `LockStore` / `withLocks` / `InMemoryLockStore` for cross-worker coordination — deliberately **not** a state store, and not composable through `composePersistence`.
+- A shared conformance testkit at `@tanstack/ai-persistence/testkit`. `runPersistenceConformance` exercises every method of every store you provide and fails loudly on a store that is missing without being declared in `skip`.
+
+Implement the stores against whatever database you already run and hand the result to `withPersistence` — the core never inspects your tables, so the schema stays yours. The [Build Your Own Adapter](https://tanstack.com/ai/latest/docs/persistence/build-your-own-adapter) guide walks through a complete `node:sqlite` backend end to end, and the package ships Agent Skills with worked Drizzle, Prisma, and Cloudflare D1 recipes (`npx @tanstack/intent@latest install`). `examples/ts-react-chat` runs on a self-contained `node:sqlite` adapter built this way and verified by the conformance testkit.
+
+Resume reconstruction is delegated to the chat engine: persistence records interrupts and gates new input on a thread with pending interrupts, while the engine rebuilds the resume tool state from the resume batch and the interrupt bindings carried in the (server-loaded) message history.
+
+`reconstructChat(persistence, request)` is a server helper that returns a thread's stored messages as a JSON `Response`, so a server-authoritative client can hydrate its transcript on load from a one-line `GET` handler.

.changeset/rejoin-not-aborted-on-mount.md

@@ -0,0 +1,11 @@
+---
+'@tanstack/ai-react': patch
+---
+
+Fix `useChat` aborting an in-flight delivery resume on mount. When `live` was
+not enabled, the mount effect called `client.unsubscribe()` unconditionally,
+which cancelled the shared in-flight stream — including the `joinRun` rejoin the
+client had just started for a reloaded run. The result was a mid-stream reload
+that caught up to the buffered point and then froze instead of continuing.
+`useChat` now only tears down a subscription it actually started, so a reload
+rejoins and streams the run through to completion.