@tanstack/ai 0.41.0 → 0.43.0

package/skills/ai-core/chat-experience/SKILL.md

@@ -9,13 +9,15 @@ description: >
   NOT Vercel AI SDK — uses chat() not streamText().
 type: sub-skill
 library: tanstack-ai
-library_version: '0.10.0'
+library_version: '0.42.0'
 sources:
   - 'TanStack/ai:docs/getting-started/quick-start.md'
   - 'TanStack/ai:docs/chat/streaming.md'
   - 'TanStack/ai:docs/chat/connection-adapters.md'
   - 'TanStack/ai:docs/chat/thinking-content.md'
   - 'TanStack/ai:docs/advanced/multimodal-content.md'
+  - 'TanStack/ai:docs/resumable-streams/overview.md'
+  - 'TanStack/ai:docs/persistence/client-persistence.md'
 ---
 
 # Chat Experience
@@ -41,7 +43,7 @@ export const Route = createFileRoute('/api/chat')({
         const { messages } = body
 
         const stream = chat({
-          adapter: openaiText('gpt-5.2'),
+          adapter: openaiText('gpt-5.5'),
           messages,
           systemPrompts: ['You are a helpful assistant.'],
           abortController,
@@ -148,6 +150,16 @@ const stream = chat({
 return toServerSentEventsResponse(stream, { abortController })
 ```
 
+To make the SSE response resumable (reconnect after a drop/refresh without
+re-running the provider), pass a delivery-durability adapter:
+`toServerSentEventsResponse(stream, { durability: { adapter: memoryStream(request) } })`
+(`memoryStream` from `@tanstack/ai` is process-local, for dev/tests) or
+`durableStream(request, { server })` from `@tanstack/ai-durable-stream`
+(Durable Streams protocol, production). Each SSE event gets an opaque
+adapter-owned `id:`; `fetchServerSentEvents` auto-reconnects with
+`Last-Event-ID` and exposes `joinRun(runId)` to replay a run from the start.
+See `docs/resumable-streams/overview.md`.
+
 **Client:**
 
 ```typescript
@@ -317,7 +329,7 @@ import { chat, toHttpResponse } from '@tanstack/ai'
 import { openaiText } from '@tanstack/ai-openai'
 
 const stream = chat({
-  adapter: openaiText('gpt-5.2'),
+  adapter: openaiText('gpt-5.5'),
   messages,
   abortController,
 })
@@ -338,6 +350,13 @@ const { messages, sendMessage } = useChat({
 The only difference is swapping `toServerSentEventsResponse` / `fetchServerSentEvents`
 for `toHttpResponse` / `fetchHttpStream`. Everything else stays identical.
 
+This includes resumability: pass the same `durability` adapter to
+`toHttpResponse(stream, { durability: { adapter: memoryStream(request) } })` and
+each NDJSON line becomes an `{ id, chunk }` envelope. `fetchHttpStream`
+auto-reconnects with `Last-Event-ID`, de-dupes the replayed prefix, and exposes
+`joinRun(runId)` — the same guarantees as resumable SSE. The XHR adapters
+(`xhrServerSentEvents` / `xhrHttpStream`) are resumable too.
+
 ### 6. MCP Tool Discovery via `chat({ mcp })`
 
 Pass `mcp` to let `chat()` own discovery **and** lifecycle for one or more MCP
@@ -409,6 +428,131 @@ export const Route = createFileRoute('/api/chat')({
 })
 ```
 
+### 7. Queueing Messages Sent While Streaming
+
+By default, a `sendMessage` call that arrives while a stream is in flight is
+**queued** and sent automatically once the run settles **successfully** —
+this is a behavior change: such sends used to be silently dropped. Configure
+it with the `queue` option on `useChat`:
+
+```typescript
+import { useChat, fetchServerSentEvents } from '@tanstack/ai-react'
+
+const { messages, queue, sendMessage, cancelQueued, isLoading } = useChat({
+  connection: fetchServerSentEvents('/api/chat'),
+  queue: { whenBusy: 'queue', drain: 'fifo', maxSize: 5, onOverflow: 'reject' },
+})
+```
+
+- **`whenBusy`** — `'queue'` (default) holds the message until a successful
+  settle; `'drop'` ignores the send (never appears in `queue`/`messages`);
+  `'interrupt'` aborts the current stream and sends immediately (unlike
+  `stop()`, does **not** flush already-queued items — they drain after the
+  interrupting send **succeeds**).
+- **`drain`** — `'fifo'` (default) sends queued items one at a time in
+  order; `'batch'` merges everything queued into a single send once the
+  run settles successfully.
+- **`maxSize`** / **`onOverflow`** — cap the queue length; `'reject'`
+  (default) silently ignores overflow sends (does not throw),
+  `'drop-oldest'` evicts the oldest queued item to make room.
+
+The top-level `queue` option also accepts a plain `WhenBusy` string
+shorthand (e.g. `queue: 'interrupt'`) or a `QueueStrategy` function for
+per-send action control. Strategy form always drains FIFO; actions are
+`'queue' | 'drop' | 'interrupt'`.
+
+**Drain vs flush:** queued messages auto-send only after a **successful**
+settle. They are **discarded** on stream error/abort of the active
+generation, `stop()`, `clear()`, `unsubscribe()`, and `reload()`.
+`interrupt` does not flush.
+
+`queue: Array<QueuedMessage>` (`{ id, content, createdAt }`) is separate
+from `messages` — render pending sends distinctly and cancel with
+`cancelQueued(id)`:
+
+```typescript
+{queue.map((q) => (
+  <div key={q.id}>
+    {typeof q.content === 'string' ? q.content : '[attachment]'}
+    <button onClick={() => cancelQueued(q.id)}>Cancel</button>
+  </div>
+))}
+```
+
+Override the configured policy for a single send with the second argument
+to `sendMessage`:
+
+```typescript
+sendMessage('Never mind, do this instead', { whenBusy: 'interrupt' })
+```
+
+### 8. Browser-Refresh Durability (client persistence)
+
+By default a `ChatClient` / `useChat` keeps messages in memory only, so a full
+page reload loses the conversation. The optional `persistence` option (a
+`ChatClientPersistence` adapter) fixes this from the client side: it stores one
+combined record — `{ messages, resume? }` (`ChatPersistedState`) — per chat `id`,
+so a reload restores the transcript **and** rehydrates any pending interrupt /
+rejoins a run that was still streaming. No manual `initialMessages` + `onFinish`
+boilerplate.
+
+Three storage adapters ship from `@tanstack/ai-client`:
+`localStoragePersistence` (survives reloads and browser restarts),
+`sessionStoragePersistence` (scoped to the tab), and `indexedDBPersistence`
+(async, structured-clone storage — no codec needed for `Date`/`Map`/etc.).
+Give the chat a stable `threadId` so the reload finds the same record.
+Persistence keys on `threadId`; the storage adapters are re-exported from each
+framework package, so a single import works:
+
+```typescript
+import {
+  useChat,
+  fetchServerSentEvents,
+  localStoragePersistence,
+} from '@tanstack/ai-react'
+
+// Defaults to the ChatPersistedState shape and a JSON codec, so no type
+// argument or serialize/deserialize is needed. indexedDBPersistence stores via
+// structured clone (a Date round-trips exactly).
+const persistence = localStoragePersistence()
+
+function Chat() {
+  const { messages, sendMessage } = useChat({
+    threadId: 'support-chat',
+    connection: fetchServerSentEvents('/api/chat'),
+    persistence,
+  })
+  // ...render messages, call sendMessage(text)
+}
+```
+
+**Keep large transcripts off the client.** `persistence` also accepts `true`
+(server-authoritative): the client caches nothing, and on mount it hydrates the
+thread from the server by `threadId` (transcript plus a cursor to any run still
+generating). An adapter is client-authoritative; `true` leaves history on the
+server and needs a connection with a `hydrate` handler plus a server GET
+endpoint (`reconstructChat`), since the delivery log only holds one run.
+
+**Mid-stream reload rejoin.** If the run was still streaming when the page
+reloaded, the client re-attaches instead of showing a frozen half-reply — but
+only when the connection is **resumable**: a delivery-durability-backed route
+that records the stream and exposes a GET replay handler (see
+`docs/resumable-streams/overview.md` and Pattern 1's `durability` adapter). Given
+that, `useChat` finds the persisted in-flight run on load and auto-rejoins it via
+`joinRun`, replaying from the server's log so the reply finishes where it left
+off. No extra client code beyond the resumable connection.
+
+**Every framework, no extra code.** Durability rides the existing `persistence`
+option, so it works identically in `@tanstack/ai-react`, `-solid`, `-vue`,
+`-svelte`, `-angular`, and `-preact` — pass `persistence` (and a stable
+`threadId`, which is the chat's identity) to the framework's `useChat` /
+`createChat` / `injectChat`; nothing is framework-specific.
+
+> **Client vs. server durability.** This is the client (per-browser) half.
+> The authoritative, multi-user, server-side copy is the `withPersistence`
+> middleware — see ai-core/middleware/SKILL.md. The two are independent; use
+> both for instant reload restore plus a durable record of record.
+
 ## Common Mistakes
 
 ### a. CRITICAL: Using Vercel AI SDK patterns (streamText, generateText)
@@ -417,12 +561,12 @@ export const Route = createFileRoute('/api/chat')({
 // WRONG
 import { streamText } from 'ai'
 import { openai } from '@ai-sdk/openai'
-const result = streamText({ model: openai('gpt-4o'), messages })
+const result = streamText({ model: openai('gpt-5.5'), messages })
 
 // CORRECT
 import { chat } from '@tanstack/ai'
 import { openaiText } from '@tanstack/ai-openai'
-const stream = chat({ adapter: openaiText('gpt-5.2'), messages })
+const stream = chat({ adapter: openaiText('gpt-5.5'), messages })
 ```
 
 ### b. CRITICAL: Using Vercel createOpenAI() provider pattern
@@ -431,12 +575,12 @@ const stream = chat({ adapter: openaiText('gpt-5.2'), messages })
 // WRONG
 import { createOpenAI } from '@ai-sdk/openai'
 const openai = createOpenAI({ apiKey })
-streamText({ model: openai('gpt-4o'), messages })
+streamText({ model: openai('gpt-5.5'), messages })
 
 // CORRECT
 import { openaiText } from '@tanstack/ai-openai'
 import { chat } from '@tanstack/ai'
-chat({ adapter: openaiText('gpt-5.2'), messages })
+chat({ adapter: openaiText('gpt-5.5'), messages })
 ```
 
 ### c. CRITICAL: Using monolithic openai() instead of openaiText()
@@ -444,11 +588,11 @@ chat({ adapter: openaiText('gpt-5.2'), messages })
 ```typescript
 // WRONG
 import { openai } from '@tanstack/ai-openai'
-chat({ adapter: openai(), model: 'gpt-5.2', messages })
+chat({ adapter: openai(), model: 'gpt-5.5', messages })
 
 // CORRECT
 import { openaiText } from '@tanstack/ai-openai'
-chat({ adapter: openaiText('gpt-5.2'), messages })
+chat({ adapter: openaiText('gpt-5.5'), messages })
 ```
 
 The monolithic `openai()` adapter is deprecated. Use tree-shakeable adapters:
@@ -470,10 +614,10 @@ return toServerSentEventsResponse(stream, { abortController })
 
 ```typescript
 // WRONG
-chat({ adapter: openaiText(), model: 'gpt-5.2', messages })
+chat({ adapter: openaiText(), model: 'gpt-5.5', messages })
 
 // CORRECT
-chat({ adapter: openaiText('gpt-5.2'), messages })
+chat({ adapter: openaiText('gpt-5.5'), messages })
 ```
 
 The model is passed to the adapter factory, not to `chat()`.
@@ -620,3 +764,4 @@ If not handled, the UI appears to hang with no feedback.
 - See also: **ai-core/tool-calling/SKILL.md** -- Most chats include tools
 - See also: **ai-core/adapter-configuration/SKILL.md** -- Adapter choice affects available features
 - See also: **ai-core/middleware/SKILL.md** -- Use middleware for analytics and lifecycle events
+- See also: **`@tanstack/ai-persistence` skills** (`skills/ai-persistence/SKILL.md` in that package) -- Server + client state persistence, store contracts, adapter recipes (deeper than Pattern 8)

package/skills/ai-core/client-persistence/SKILL.md

@@ -0,0 +1,277 @@
+---
+name: ai-core/client-persistence
+description: >
+  Browser chat persistence on useChat / ChatClient: localStoragePersistence,
+  sessionStoragePersistence, indexedDBPersistence. Client-authoritative
+  (adapter, full transcript) vs server-authoritative (persistence: true, no
+  client cache).
+  Reload restore, pending interrupts, mid-stream rejoin with delivery
+  durability. Use for SPA reload durability — NOT server history alone.
+  Also covers generation hooks (useGenerateImage etc.), which take only the
+  server-driven mode: persistence: true hydrates the last generation for the
+  (REQUIRED) threadId from the server on mount and repaints status/result/error,
+  nothing is cached in the browser.
+  No extra package: the adapters ship in the framework packages.
+type: sub-skill
+library: tanstack-ai
+library_version: '0.42.0'
+sources:
+  - 'TanStack/ai:docs/persistence/client-persistence.md'
+  - 'TanStack/ai:docs/persistence/overview.md'
+---
+
+# Client Persistence
+
+> Builds on ai-core, and on `ai-core/chat-experience` for `useChat` itself.
+>
+> **No extra package.** The adapters below ship in the **framework** packages
+> (`@tanstack/ai-react` and friends, re-exported from `@tanstack/ai-client`),
+> so browser persistence needs nothing installed beyond what a chat UI already
+> has. The **server** half is a separate package — see
+> `@tanstack/ai-persistence` and its `ai-persistence/server` skill.
+
+A `ChatClient` / `useChat` keeps messages in memory. The `persistence` option
+stores one record per `threadId` so a reload can repaint the transcript,
+restore a pending interrupt, and rejoin an in-flight run.
+
+Import adapters from the **framework package** (not `@tanstack/ai-client`
+unless vanilla JS):
+
+```tsx
+import {
+  useChat,
+  fetchServerSentEvents,
+  localStoragePersistence,
+  sessionStoragePersistence,
+  indexedDBPersistence,
+} from '@tanstack/ai-react'
+```
+
+## Adapters
+
+| Adapter                       | Survives                   | Notes                                                           |
+| ----------------------------- | -------------------------- | --------------------------------------------------------------- |
+| `localStoragePersistence()`   | Reloads + browser restarts | Sync hydrate; quota-bound; JSON codec default                   |
+| `sessionStoragePersistence()` | Reloads in the same tab    | Cleared when tab/session ends                                   |
+| `indexedDBPersistence()`      | Reloads + restarts         | Async open (first paint may be empty briefly); structured clone |
+
+All default to the chat persisted-state shape — no type argument or codec
+required for normal use.
+
+## Mode A — cache everything (client-authoritative)
+
+```tsx
+function Chat() {
+  const { messages, sendMessage } = useChat({
+    threadId: 'support-chat', // stable — required
+    connection: fetchServerSentEvents('/api/chat'),
+    persistence: localStoragePersistence(),
+  })
+  // ...
+}
+```
+
+Bare adapter ≡ full transcript + resume pointer. Browser owns history; server
+(if any) mirrors when you post non-empty `messages`.
+
+Best for: SPA, offline-first, single device, moderate conversation size.
+
+## Mode B — server-authoritative (`persistence: true`)
+
+```tsx
+function Chat({ threadId }: { threadId: string }) {
+  const { messages, sendMessage } = useChat({
+    threadId,
+    connection: fetchServerSentEvents('/api/chat'),
+    persistence: true,
+  })
+  // ...
+}
+```
+
+Nothing is cached client-side: no transcript, no resume pointer.
+
+On mount, `useChat` hydrates the thread from the **server** by `threadId`
+(paint + tail active run). Same path for another device. Pair with server
+`withPersistence` + a hydrate route (`reconstructChat` or equivalent).
+
+Best for: large transcripts, multi-device, compliance (no message bodies in
+browser storage).
+
+## What a reload restores
+
+1. **Finished run** — transcript from the adapter (mode A) or server (mode B).
+2. **Paused on interrupt** — approval UI restored (from the adapter in mode A,
+   the server hydrate in mode B).
+3. **Still streaming** — needs **delivery durability** on the route
+   (`toServerSentEventsResponse(stream, { durability: … })`) so the client can
+   `joinRun` and finish the reply. Persistence alone is not enough.
+
+## Stable `threadId` is the identity
+
+Persistence keys on `threadId`. The hooks have **no separate `id` option** — a
+chat's identity _is_ its `threadId`. Without a stable one, each load is a new
+chat. Generate it server-side or from a route param the user owns; do not
+randomize per mount.
+
+## Generation hooks: server-driven only
+
+The generation hooks (`useGenerateImage`, `useGenerateVideo`, `useGeneration`,
+`useSummarize`, `useTranscription`, …) take a `persistence` option too, but it is
+**boolean only** — there is no storage-adapter mode, and the browser caches
+nothing. **The hooks are transparent, mirroring `useChat`:** a reload repaints the
+hook's
+**normal** fields — `status` (`'idle'` / `'generating'` / `'success'` /
+`'error'`), `error`, and `result` — as if the run had just finished. There is
+**no** `resumeSnapshot`, `resumeState`, `pendingArtifacts`, or `resultArtifacts`
+field. The one extra field is `runId`: the id of the generation job currently
+running, or `null` when nothing is in flight. The persisted record holds run
+identity, status, error, and result metadata (ids, model, a provider video job
+id), **never the generated media bytes**.
+
+The hook return is exactly `generate` / `result` / `isLoading` / `error` /
+`status` / `stop` / `reset` / `runId`.
+
+### Turning it on (`persistence: true`)
+
+```tsx
+const image = useGenerateImage({
+  threadId, // REQUIRED — the scope the last generation is hydrated under
+  connection: fetchServerSentEvents('/api/generate/image'),
+  persistence: true,
+})
+// After a reload: image.status / image.result / image.error are the last
+// generation for `threadId`, fetched from the server — nothing was cached.
+```
+
+The server half — the same route handles the run and the hydration `GET`:
+
+```ts
+import {
+  generateImage,
+  generationParamsFromRequest,
+  toServerSentEventsResponse,
+} from '@tanstack/ai'
+import { openaiImage } from '@tanstack/ai-openai'
+import {
+  memoryPersistence,
+  reconstructGeneration,
+  withGenerationPersistence,
+} from '@tanstack/ai-persistence'
+
+// Needs `stores.generationRuns`; `memoryPersistence()` ships one.
+const persistence = memoryPersistence()
+
+export async function POST(request: Request) {
+  const { input, threadId } = await generationParamsFromRequest(
+    'image',
+    request,
+  )
+  if (typeof input.prompt !== 'string') {
+    throw new Error('This endpoint accepts text image prompts only.')
+  }
+  if (threadId === undefined) {
+    throw new Error('Generation persistence requires a `threadId`.')
+  }
+
+  return toServerSentEventsResponse(
+    generateImage({
+      adapter: openaiImage('gpt-image-2'),
+      prompt: input.prompt,
+      // The stable slot this run fills. Required by persistence: the run record
+      // is filed under it, and the client hydrates by it on mount.
+      threadId,
+      stream: true,
+      middleware: [withGenerationPersistence(persistence)],
+    }),
+  )
+}
+
+// Mount-time hydration: resolves `?runId=` (preferred) or the latest run linked
+// to `?threadId=`, and returns `{ resumeSnapshot, activeRun }`.
+export function GET(request: Request) {
+  return reconstructGeneration(persistence, request, {
+    // Multi-user routes MUST authorize: the ids come from the caller. Derive
+    // identity from server-side session state, then check ownership.
+    authorize: async (id, req) => {
+      // const user = await auth(req)
+      // return user != null && (await db.threadOwnedBy(user.id, id))
+      void id
+      void req
+      return true
+    },
+  })
+}
+```
+
+- Nothing is cached client-side. On mount the client hydrates the **last
+  generation** for its `threadId` from the server via the connection's
+  `hydrateGeneration` handler (the SSE/HTTP adapters issue a `GET` with
+  `?threadId=` to the same endpoint URL) and repaints it into the normal fields.
+- The server `GET` returns `reconstructGeneration(persistence, request)` from
+  `@tanstack/ai-persistence` — it resolves the run by `?runId=` (preferred) or
+  the latest run linked to `?threadId=`, and needs `stores.generationRuns`. Pair it with
+  `withGenerationPersistence` on the generation route. See
+  `ai-core/media-generation` and `ai-persistence`.
+- Best for multi-device / compliance (no generation metadata in browser
+  storage), exactly like chat's server-authoritative mode.
+
+### Restoring media: byte storage + `artifactUrl`
+
+`result` comes back with its media only when the **server** persists the bytes
+(`stores.artifacts` + `stores.blobs`) AND `withGenerationPersistence` is given an
+`artifactUrl` mapper:
+
+```ts
+withGenerationPersistence(persistence, {
+  artifactUrl: (ref) => `/api/generate/image/artifact?id=${ref.artifactId}`,
+})
+```
+
+`artifactUrl` stamps a durable app-origin URL onto each persisted ref and
+rewrites the live result's media to it, so live and restored results match. The
+durable refs travel on `result.artifacts`; on restore the hook rebuilds `result`
+from them, so `result.images[i].url` (or a video's `result.url`) serves from your
+own origin. `result.artifacts` is the whole artifact surface on the hook.
+Without byte storage, a reload restores `status` / `error` and `result` stays
+`null`.
+
+Also worth knowing:
+
+- `stop()` marks the record no longer resumable; `reset()` clears the in-memory
+  snapshot.
+- Nothing auto-runs from a hydrated record — `generate(...)` is always explicit.
+- Use `status` / `result` for a finished run; use `runId` to tell that a run was
+  still generating when the page closed, and to name it to your own server (to
+  cancel or poll the provider job — `stop()` only aborts the local stream).
+
+## Common mistakes
+
+### HIGH: No `threadId`
+
+Record cannot be found after reload.
+
+### HIGH: Passing `id` to `useChat`
+
+Removed — `threadId` is the identity. (`ChatClient` still accepts `id` directly
+as a lower-level escape hatch for keying storage separately from the wire
+thread; the framework hooks do not.)
+
+### HIGH: `persistence: true` without server history
+
+Empty chat after reload unless the server can reconstruct by `threadId`.
+
+### MEDIUM: Huge transcripts in `localStorage`
+
+Quota and main-thread cost. Prefer `persistence: true` + server store, or
+IndexedDB with care.
+
+### MEDIUM: Expecting multi-device sync from client storage alone
+
+`localStorage` is per-browser. Use server persistence for multi-device.
+
+## Cross-references
+
+- **ai-persistence/server** (`@tanstack/ai-persistence`) — authoritative server half
+- **ai-core/chat-experience** — `useChat`, resumable connections
+- Resumable streams docs — mid-stream rejoin

package/skills/ai-core/custom-backend-integration/SKILL.md

@@ -9,7 +9,7 @@ description: >
   not @tanstack/ai-client.
 type: composition
 library: tanstack-ai
-library_version: '0.10.0'
+library_version: '0.42.0'
 sources:
   - 'TanStack/ai:docs/chat/connection-adapters.md'
 ---

package/skills/ai-core/debug-logging/SKILL.md

@@ -9,7 +9,7 @@ description: >
   log by default even when `debug` is omitted; silence with `debug: false`.
 type: sub-skill
 library: tanstack-ai
-library_version: '0.10.0'
+library_version: '0.42.0'
 sources:
   - 'TanStack/ai:docs/advanced/debug-logging.md'
 ---