@tanstack/ai 0.42.0 → 0.43.0

package/skills/ai-core/media-generation/SKILL.md

@@ -2,16 +2,16 @@
 name: ai-core/media-generation
 description: >
   Image, audio, video, speech (TTS), and transcription generation using
-  activity-specific adapters: generateImage() with openaiImage/geminiImage,
+  activity-specific adapters: generateImage() with openaiImage/geminiImage/byteplusImage,
   generateAudio() with geminiAudio/falAudio, generateVideo() with async
-  polling (openaiVideo/geminiVideo/grokVideo/falVideo, per-model typed
-  durations), generateSpeech() with openaiSpeech, generateTranscription()
-  with openaiTranscription. React hooks: useGenerateImage, useGenerateAudio,
+  polling (openaiVideo/geminiVideo/grokVideo/falVideo/byteplusVideo, per-model typed
+  durations), generateSpeech() with openaiSpeech/byteplusSpeech, generateTranscription()
+  with openaiTranscription/byteplusTranscription. React hooks: useGenerateImage, useGenerateAudio,
   useGenerateSpeech, useTranscription, useGenerateVideo.
   TanStack Start server function integration with toServerSentEventsResponse.
 type: sub-skill
 library: tanstack-ai
-library_version: '0.10.0'
+library_version: '0.42.0'
 sources:
   - 'TanStack/ai:docs/media/generations.md'
   - 'TanStack/ai:docs/media/generation-hooks.md'
@@ -150,8 +150,16 @@ function ImageGenerator() {
 ### 1. Image Generation
 
 Supported adapters: `openaiImage` (dall-e-2, dall-e-3, gpt-image-1,
-gpt-image-1-mini, gpt-image-2) and `geminiImage` (gemini-3.1-flash-image-preview,
-gemini-3.1-flash-lite-image, imagen-4.0-generate-001, etc.).
+gpt-image-1-mini, gpt-image-2), `geminiImage` (gemini-3.1-flash-image-preview,
+gemini-3.1-flash-lite-image, imagen-4.0-generate-001, etc.) and `byteplusImage`
+(Seedream — `seedream-4-0-250828`, `seedream-4-5-251128`, the 5.0 family).
+
+> **Seedream quirks:** `watermark` defaults to **`true`** (pass
+> `modelOptions: { watermark: false }` for a clean image), `size` is a token
+> (`'1K'` | `'2K'` | `'4K'`) **or** explicit `'2048x2048'` pixels but never a
+> mix, and `numberOfImages` is an **upper bound** — Seedream has no `n`, so it
+> maps onto group-image mode and the model may return fewer. Reads
+> `ARK_API_KEY`.
 
 ```typescript
 import { generateImage } from '@tanstack/ai'
@@ -333,7 +341,19 @@ const { generate, result, isLoading } = useGenerateAudio({
 
 ### 3. Text-to-Speech
 
-Adapter: `openaiSpeech` (tts-1, tts-1-hd, gpt-4o-audio-preview).
+Adapters: `openaiSpeech` (tts-1, tts-1-hd, gpt-4o-audio-preview) and
+`byteplusSpeech` (`seed-audio-1.0`).
+
+> **BytePlus Seed Speech is a separate product from ModelArk** — it reads
+> **`BYTEPLUS_VOICE_API_KEY`**, not `ARK_API_KEY`, and an Ark key there fails
+> with `45000010 Invalid X-Api-Key`. Output is capped at **120 seconds**.
+> There is no top-level `speaker` field — `voice` is sent as
+> `references: [{ speaker }]`, and `modelOptions.references` **replaces** that
+> array rather than merging, so passing `references` for voice cloning silently
+> drops `voice`. Voice ids ending `_uranus_bigtts` are TTS 2.0,
+> `_mars_bigtts` / `_moon_bigtts` are TTS 1.0, and `*_emo_v2_*` are the 1.0
+> voices that accept emotion tags. Formats: `wav`, `mp3`, `pcm`, `ogg_opus`;
+> `watermark` is also available on `modelOptions`.
 
 ```typescript
 import { generateSpeech } from '@tanstack/ai'
@@ -367,8 +387,10 @@ const { generate, result, isLoading } = useGenerateSpeech({
 
 ### 4. Audio Transcription
 
-Adapter: `openaiTranscription` (whisper-1, gpt-4o-transcribe,
-gpt-4o-mini-transcribe, gpt-4o-transcribe-diarize).
+Adapters: `openaiTranscription` (whisper-1, gpt-4o-transcribe,
+gpt-4o-mini-transcribe, gpt-4o-transcribe-diarize) and `byteplusTranscription`
+(`seed-asr` — synchronous, no polling; audio up to 2 hours / 100 MB; also reads
+**`BYTEPLUS_VOICE_API_KEY`**).
 
 > **Capturing audio in the browser:** Use `useAudioRecorder` from `@tanstack/ai-react` to record directly in the browser, then pass the recording as the `audio` input to `generate()`, or use `recording.part` as a prompt part in chat/generation calls. No transcoding or extra dependencies required — the recorder returns the native browser format (`audio/webm` or `audio/mp4`). For transcription, wrap it as a `data:` URL so the provider gets the real content type; passing raw `recording.base64` makes the adapter assume `audio/mpeg` and mislabel the webm/mp4 bytes.
 >
@@ -517,7 +539,20 @@ durations 4/8/12s, single `input_reference` image prompt part), `grokVideo(...)`
 (`grok-imagine-video` does text-to-video + image-to-video; `grok-imagine-video-1.5` is
 image-to-video only — needs an `image` prompt part as the starting frame, text-only throws;
 aspect-ratio size template like `'16:9_720p'`, integer durations 1-15s, reports
-`usage.unitsBilled` seconds and exact `usage.cost`), and `falVideo(...)` (hosted models, see cost tracking below).
+`usage.unitsBilled` seconds and exact `usage.cost`), `byteplusVideo(...)` (Seedance —
+aspect-ratio size template like `'16:9_720p'`, durations 4-15s on the 2.0 family,
+4-12s on 1.5-pro, 2-12s on the 1.0-pro models; reads `ARK_API_KEY`), and
+`falVideo(...)` (hosted models, see cost tracking below).
+
+> **Seedance option applicability is per model and enforced server-side** —
+> Ark returns a 400 for an inapplicable field rather than ignoring it.
+> `service_tier` / `camera_fixed` are Seedance 1.x only, `frames` is
+> 1-0-pro + 1-0-pro-fast only, `draft` is 1-5-pro only, `priority` is the 2.0
+> family only, and `duration: -1` works on 2.0 + 1-5-pro. There is no 2K tier
+> on any model and `4k` exists only on `dreamina-seedance-2-0-260128`.
+> **Video URLs expire 24 hours after the task completes** (task record kept 7
+> days). Seedance is also reachable via `falVideo` — `byteplusVideo` is the
+> direct-to-BytePlus path.
 
 Client hook with job tracking:
 
@@ -563,6 +598,94 @@ if (result.usage?.unitsBilled != null) {
 For video, the units arrive with the completed result: `getVideoJobStatus()`
 returns `usage` and emits a `video:usage` devtools event when fal reports it.
 
+### 7. Durable persistence (job lifecycle + artifact bytes)
+
+To make generations survive a server restart and be re-served later, add
+`withGenerationPersistence` from `@tanstack/ai-persistence` as generation
+middleware. It requires `stores.generationRuns` (a `GenerationRunStore`, keyed on
+the run's own `runId`, with a required `threadId` naming the stable slot the run
+fills — that is what a client hydrates by) and, when you also pass an `stores.artifacts` +
+`stores.blobs` **pair** (both or neither), it persists the generated media bytes
+at blob key `artifacts/<runId>/<artifactId>` with an `ArtifactRecord` per file.
+`memoryPersistence()` ships all three for dev/tests.
+
+```typescript
+import { generateImage, toServerSentEventsResponse } from '@tanstack/ai'
+import { openaiImage } from '@tanstack/ai-openai'
+import {
+  withGenerationPersistence,
+  memoryPersistence,
+  retrieveArtifact,
+  retrieveBlob,
+  reconstructGeneration,
+} from '@tanstack/ai-persistence'
+
+const persistence = memoryPersistence() // swap for your DB/object-store adapter
+
+export async function POST(req: Request) {
+  const { prompt, threadId } = await req.json()
+  return toServerSentEventsResponse(
+    generateImage({
+      adapter: openaiImage('gpt-image-1'),
+      prompt,
+      threadId, // the slot recorded on the job + artifacts
+      stream: true,
+      middleware: [
+        withGenerationPersistence(persistence, {
+          // Stamp a durable app-origin serve URL (the GET route below) onto
+          // each persisted artifact ref, and rewrite the live result's media to
+          // it. Both live and restored results then render from your origin.
+          artifactUrl: (ref) => `/api/artifacts?id=${ref.artifactId}`,
+        }),
+      ],
+    }),
+  )
+}
+
+// Serve the stored bytes back (GET /api/artifacts?id=…):
+export async function GET(req: Request) {
+  const id = new URL(req.url).searchParams.get('id') ?? ''
+  const record = await retrieveArtifact(persistence, id)
+  if (!record) return new Response('Not found', { status: 404 })
+  const blob = await retrieveBlob(persistence, record)
+  if (!blob?.body) return new Response('Not found', { status: 404 })
+  return new Response(blob.body, {
+    headers: { 'content-type': record.mimeType },
+  })
+}
+```
+
+That route is enough for images. **Video needs `Range`**: seeking a `<video>`
+is built on `206` / `Content-Range`, and Safari refuses to play a source that
+ignores `Range` at all. Resolve the header against `record.size` (`416` when it
+does not fit), pass `retrieveBlob(persistence, record, { range })`, and answer
+`206` from the returned `blob.range` plus `accept-ranges: bytes`. The full
+route is in the persistence docs under **Serve video: honour `Range`**.
+
+On the client, `persistence` is **boolean only**: `persistence: true` hydrates
+the last generation for the thread on mount, via the connection's
+`hydrateGeneration` handler backed by a `reconstructGeneration` GET route. There
+is no storage-adapter mode, so nothing about a generation is cached in the
+browser.
+
+**`persistence: true` requires a stable `threadId`**, and it is a type error to
+set one without the other. That is the generation's scope, the slot successive
+runs fill (e.g. `video-9-start-frame`), not a link to a chat. `id` is the
+devtools label only and never a persistence key.
+
+The hooks are transparent (like `useChat`): a reload repaints `status` /
+`result` / `error`, not a separate `resumeSnapshot`. Because the `artifactUrl`
+above stamps a durable URL onto each ref (carried on `result.artifacts`), the
+restored `result` rebuilds its media from those refs and serves from your own
+origin. Without byte storage, a reload restores `status` / `error` and `result`
+stays `null`.
+
+- Building the R2/D1-backed byte stores for a Cloudflare Worker:
+  **ai-persistence/build-cloudflare-artifact-store**.
+- Store contracts, `composePersistence`, and the wiring end-to-end:
+  `docs/persistence/generation-persistence.md` and the
+  `ai-core/client-persistence` sub-skill.
+
 ---
 
 ## Common Hook API
@@ -577,7 +700,16 @@ All generation hooks return the same shape:
 | `error`     | `Error \| undefined`       | Current error                                    |
 | `status`    | `GenerationClientState`    | `'idle' \| 'generating' \| 'success' \| 'error'` |
 | `stop`      | `() => void`               | Abort current generation                         |
-| `reset`     | `() => void`               | Clear state, return to idle                      |
+| `reset`     | `() => void`               | Clear state and the in-memory snapshot           |
+| `runId`     | `string \| null`           | Id of the job WHILE it runs; null when idle      |
+
+The hook is **transparent**, mirroring `useChat`: there is no `resumeSnapshot`,
+`resumeState`, `pendingArtifacts`, or `resultArtifacts` field. Hooks also accept
+`persistence: true` plus a stable `threadId`: on mount the client hydrates the
+last run for that scope from the server and repaints the **normal** `status` /
+`result` / `error` fields, so the last run survives a reload (metadata only,
+never media bytes; `result`'s media returns only with server byte storage +
+`artifactUrl`). See `ai-core/client-persistence` for details.
 
 Provide either `connection` (streaming SSE transport) or `fetcher`
 (direct async call / server function returning `Response`). Use `onResult`

package/skills/ai-core/middleware/SKILL.md

@@ -8,10 +8,11 @@ description: >
   execution order. NOT onEnd/onFinish callbacks on chat() — use middleware.
 type: sub-skill
 library: tanstack-ai
-library_version: '0.10.0'
+library_version: '0.42.0'
 sources:
   - 'TanStack/ai:docs/advanced/middleware.md'
   - 'TanStack/ai:docs/sandbox/observability.md'
+  - 'TanStack/ai:docs/persistence/overview.md'
 ---
 
 # Middleware
@@ -57,6 +58,7 @@ Every hook receives a `ChatMiddlewareContext` as its first argument, which provi
 | `onStructuredOutputConfig` | Once at the structured-output boundary (only when `chat({ outputSchema })`)                        | `StructuredOutputMiddlewareConfig` (return partial) |
 | `onStart`                  | Once after initial `onConfig`                                                                      | none                                                |
 | `onIteration`              | Start of each agent loop iteration                                                                 | `IterationInfo`                                     |
+| `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`                                 |
@@ -116,17 +118,25 @@ onStructuredOutputConfig?: (
   | void
   | null
   | Partial<StructuredOutputMiddlewareConfig>
-  | Promise<void | Partial<StructuredOutputMiddlewareConfig>>
+  | Promise<void | null | Partial<StructuredOutputMiddlewareConfig>>
 ```
 
 **`StructuredOutputMiddlewareConfig` shape:**
 
 ```ts
-interface StructuredOutputMiddlewareConfig extends ChatMiddlewareConfig {
+interface StructuredOutputMiddlewareConfig extends Omit<
+  ChatMiddlewareConfig,
+  'tools'
+> {
   outputSchema: JSONSchema // The JSON Schema being sent to the provider
 }
 ```
 
+Note the `Omit<…, 'tools'>`: there is **no `config.tools`** on this hook. The
+structured-output call is the final, tool-free call, so reading or returning
+`tools` here is a compile error, not a no-op. Transform tools in `onConfig`
+instead.
+
 **Ordering rule:**
 
 - `onStructuredOutputConfig` fires **before** `onConfig` at the structured-output boundary.
@@ -211,11 +221,18 @@ const toolGuard: ChatMiddleware = {
       return { type: 'abort', reason: 'Dangerous operation blocked' }
     }
 
-    // Enforce default arguments
-    if (hookCtx.toolName === 'search' && !hookCtx.args.limit) {
-      return {
-        type: 'transformArgs',
-        args: { ...hookCtx.args, limit: 10 },
+    // Enforce default arguments. `hookCtx.args` is `unknown` — the provider
+    // sent it — so narrow before reading it. No `as` casts.
+    if (hookCtx.toolName === 'search') {
+      const args =
+        typeof hookCtx.args === 'object' && hookCtx.args !== null
+          ? hookCtx.args
+          : {}
+      if (!('limit' in args)) {
+        return {
+          type: 'transformArgs',
+          args: { ...args, limit: 10 },
+        }
       }
     }
 
@@ -346,6 +363,52 @@ const stream = chat({
 | `onUsage`                  | Sequential                                    | All run in order                           |
 | `onFinish/onAbort/onError` | Sequential                                    | All run in order                           |
 
+## Pattern: tool-call budget (app-owned)
+
+Not a built-in. Cap fan-out with `onBeforeToolCall` skip + `onShouldContinue`.
+See `docs/chat/agentic-cycle.md` ("Tool-call budgets").
+
+```typescript
+import { chat, maxIterations, type ChatMiddleware } from '@tanstack/ai'
+
+function toolCallBudget(opts: {
+  max?: number
+  maxPerTurn?: number
+}): ChatMiddleware {
+  let perTurn = 0
+  return {
+    onIteration: () => {
+      perTurn = 0
+    },
+    onToolPhaseComplete: () => {
+      perTurn = 0
+    },
+    onBeforeToolCall: () => {
+      if (opts.maxPerTurn == null) return undefined
+      if (++perTurn > opts.maxPerTurn) {
+        return {
+          type: 'skip',
+          result: {
+            error: `Skipped: exceeded maxToolCallsPerTurn (${opts.maxPerTurn})`,
+          },
+        }
+      }
+      return undefined
+    },
+    onShouldContinue: (_ctx, state) =>
+      opts.max != null && state.toolCallCount >= opts.max ? false : undefined,
+  }
+}
+
+chat({
+  adapter,
+  messages,
+  tools: [weatherTool],
+  agentLoopStrategy: maxIterations(20),
+  middleware: [toolCallBudget({ maxPerTurn: 10, max: 20 })],
+})
+```
+
 ## Built-in: toolCacheMiddleware
 
 Caches tool call results by name + arguments. Import from `@tanstack/ai/middlewares`:
@@ -372,6 +435,148 @@ Options: `maxSize` (default 100), `ttl` (default Infinity), `toolNames` (default
 `keyFn` (custom cache key), `storage` (custom backend like Redis). See
 `docs/advanced/middleware.md` for custom storage examples.
 
+## Server State Persistence: withPersistence
+
+`withPersistence(persistence)` (from `@tanstack/ai-persistence`) is a
+`ChatMiddleware` that persists **state** for `chat()` — thread messages, run
+records (status/timing/usage/errors), and interrupt state — to a backend store.
+Add it to the `middleware` array like any other middleware. It never mutates the
+chunk stream; replaying a dropped/reloaded _stream_ is a separate transport-layer
+concern (see ai-core/chat-experience/SKILL.md resumability, not this middleware).
+
+```typescript
+import {
+  chat,
+  chatParamsFromRequest,
+  toServerSentEventsResponse,
+} from '@tanstack/ai'
+import { openaiText } from '@tanstack/ai-openai'
+import { withPersistence, memoryPersistence } from '@tanstack/ai-persistence'
+
+// memoryPersistence() is the in-process reference backend (dev/tests). For a
+// durable one, implement the store contracts against your database — see the
+// @tanstack/ai-persistence skills.
+const persistence = memoryPersistence()
+
+export async function POST(request: Request) {
+  const params = await chatParamsFromRequest(request)
+
+  const stream = chat({
+    adapter: openaiText('gpt-5.5'),
+    messages: params.messages,
+    threadId: params.threadId,
+    runId: params.runId,
+    ...(params.resume ? { resume: params.resume } : {}),
+    middleware: [withPersistence(persistence)],
+  })
+
+  return toServerSentEventsResponse(stream)
+}
+```
+
+### Authoritative-history contract
+
+The middleware treats each request's `messages` as the source of truth for the
+thread:
+
+- **Non-empty `messages`** → on a successful finish (and at an interrupt
+  boundary) the middleware **overwrites** the entire stored thread with that
+  array. Post the **complete** transcript, never just the newest message(s) — a
+  delta would replace and destroy the stored history.
+- **Empty `messages`** → the middleware **loads** the stored thread and runs the
+  turn from the server's copy. This is how you continue a conversation without
+  resending history from the client.
+
+### Backends
+
+`@tanstack/ai-persistence` ships **contracts, not a database backend**. It
+provides the four store interfaces (`messages`, `runs`, `interrupts`,
+`metadata`), the middleware that drives them, `memoryPersistence()` for
+dev/tests, and a conformance testkit. For anything durable you implement the
+stores against your own database and pass the result to `withPersistence`.
+
+Annotate your factory with a named shape (`ChatPersistence` /
+`ChatTranscriptPersistence`) — bare `AIPersistence` is the all-optional bag and
+`withPersistence` rejects it.
+
+Locks are separate from state and are **not** a `stores` key: wire a
+`LockStore` with `withLocks(lockStore)`.
+
+The `runs` store in that list is typed against `RunStore`, which ships in
+`@tanstack/ai` alongside `RunRecord`, `RunStatus`, `TerminalRunStatus`,
+`RunError`, `isTerminalRunStatus`, `defineRunStore`, and `InMemoryRunStore`. A
+`RunRecord` tracks one run: `runId`, `threadId`, `status`, `startedAt`, plus
+optional `finishedAt`, `error`, `usage`, `sandboxKey`, `detachedSince`,
+`cancelRequested`, and `driverEpoch`. A backend must round-trip **all** of
+them: `cancelRequested` is the durable out-of-band cancel channel
+(`requestRunCancel` writes it, `wasCancelRequested` reads it), and
+`driverEpoch` is the monotonic fencing token each host bumps when it claims a
+run, so a superseded host can discover it lost. Omit either and a durable
+sandboxed run loses a mechanism silently — Stop stops reaching a remote
+driver, or nothing fences a dead host's writes.
+`error` is a structured `RunError` (`{ message: string, code?: string }`), not
+a bare string: `message` is the provider's prose, `code` is the stable,
+machine-branchable classification a consumer switches on. Only
+`createOrResume`, `update`, `get`, and `findActiveRun` are required on a
+`RunStore`; `listByThread` and `listReclaimable` are optional, so a backend can
+leave either out and callers feature-detect
+(`store.listReclaimable?.(opts)`). Shape your own store with
+`defineRunStore` for autocomplete without a separate `: RunStore` annotation,
+matching `defineLock`; `defineRunStore<const T extends RunStore>(store: T): T`
+returns the argument's own type, so an optional method your store implements
+stays known-present on the result instead of collapsing to `| undefined`.
+`isTerminalRunStatus(status)` is a type predicate narrowing `RunStatus` to
+`TerminalRunStatus`, so code inside the guard can pass `status` where a
+`TerminalRunStatus` is required without a cast. When a backend omits an
+optional `RunStore` method, declare the omission when running the conformance
+testkit (`ai-persistence/stores`'s `skipMethods` option) rather than leaving it
+undeclared.
+
+### `StreamDurability.snapshot()`
+
+A `StreamDurability` (the event-log backend `memoryStream` / `durableStream`
+implement, and what `@tanstack/ai-sandbox`'s run driver resolves per run — its
+`RunDeps.durability` / `sandboxRunDriver({ durability })` is a factory
+`(runId) => StreamDurability`, because one log is bound to one run) requires a
+`snapshot()` method alongside `append`, `read`, and `close`:
+
+```ts
+snapshot: () => Promise<Array<{ offset: TOffset; chunk: StreamChunk }>>
+```
+
+It returns everything stored for a run right now, in append order, then
+resolves. Use it, not `read()`, when a caller needs to inspect a run's stored
+prefix and get an answer back: `read()` tails and only resolves once the log
+is terminalized with `close()` or the caller aborts, so it never resolves
+against a producer that crashed without calling `close()`, and its log stays
+open indefinitely. `snapshot()` resolves immediately with what is stored,
+including while the log is still open, and resolves to an empty array for a
+run with nothing stored yet.
+
+**Full guidance lives in the package's own skills** — start at
+`node_modules/@tanstack/ai-persistence/skills/ai-persistence/SKILL.md`,
+which routes to the server, client, stores, locks, and adapter-recipe
+(Drizzle / Prisma / Cloudflare) sub-skills.
+
+### Resume reconstruction is the middleware's job (server-authoritative path)
+
+When a thread has pending interrupts, the middleware **records** them and
+**gates** new input: a request that carries pending interrupts must include a
+`resume` batch that references them, or `onConfig` throws. On a valid resume
+batch the middleware also **builds `ChatResumeToolState`** (approvals /
+client-tool results) and **clears `config.resume`** so the chat engine skips
+its ephemeral reconstruction — that path needs client message history the
+persistence flow deliberately omits when the server owns the transcript.
+Resumes accepted in `onConfig` are committed (marked resolved/cancelled) only
+once the run reaches a successful boundary, so a provider failure between
+accepting a resume and finishing leaves the interrupt pending and a retry with
+the same resume succeeds.
+
+> A companion `withGenerationPersistence(persistence)` tracks run records for
+> non-chat generation activities (image, audio, TTS, video, transcription).
+
+Source: docs/persistence/overview.md
+
 ## Sandbox File-Event Hooks (`sandbox` group)
 
 Declare a `sandbox: ChatSandboxHooks` group on `defineChatMiddleware` to react
@@ -507,35 +712,38 @@ has no effect on the stream output.
 
 Source: docs/advanced/middleware.md
 
-### b. MEDIUM: Middleware exceptions breaking the stream
+### b. MEDIUM: Middleware exceptions breaking the stream — in `onChunk` / `onConfig`
+
+Know which hooks the framework already guards. **The terminal hooks
+(`onFinish`, `onAbort`, `onError`) are individually wrapped** by core's
+`runTerminalHook`: a throw there is logged on the `errors` channel and the next
+middleware's terminal hook still runs, so a failed analytics `POST` in `onFinish`
+cannot break the stream or replace the abort reason. Guarding those is about
+keeping your own bookkeeping intact, not about protecting the run.
+
+**`onChunk` and `onConfig` are NOT guarded, deliberately** — they are transforms
+on the data path, where swallowing a throw would forward a chunk or a config the
+middleware had decided to reject. A throw from either fails the whole stream. That
+is where an unhandled error actually costs you a response:
 
 ```typescript
-// WRONG -- unhandled error kills the entire streaming response
+// WRONG -- an unhandled error in onChunk kills the entire streaming response
 const fragile: ChatMiddleware = {
-  name: 'fragile-analytics',
-  onFinish: async (ctx, info) => {
-    // If this fetch fails, the stream breaks
-    await fetch('/api/analytics', {
-      method: 'POST',
-      body: JSON.stringify({ duration: info.duration }),
-    })
+  name: 'fragile-chunk-logger',
+  onChunk: (ctx, chunk) => {
+    // A logger that throws on an unexpected chunk shape takes the stream with it
+    logChunk(chunk)
+  },
+  onConfig: (ctx, config) => {
+    // Same for a config transform that reads an env var that is not set
+    return { model: requireEnv('MODEL_OVERRIDE') }
   },
 }
 
-// CORRECT -- wrap in try-catch and/or use ctx.defer()
+// CORRECT -- own the failure inside the unguarded hooks
 const resilient: ChatMiddleware = {
-  name: 'resilient-analytics',
-  onFinish: (ctx, info) => {
-    // Option 1: defer (non-blocking, errors are isolated)
-    ctx.defer(
-      fetch('/api/analytics', {
-        method: 'POST',
-        body: JSON.stringify({ duration: info.duration }),
-      }),
-    )
-  },
+  name: 'resilient-chunk-logger',
   onChunk: (ctx, chunk) => {
-    // Option 2: try-catch for synchronous/critical hooks
     try {
       logChunk(chunk)
     } catch (err) {
@@ -543,17 +751,34 @@ const resilient: ChatMiddleware = {
     }
     // Return void to pass through
   },
+  onConfig: (ctx, config) => {
+    const override = process.env.MODEL_OVERRIDE
+    // Decide, do not throw: no override means no transform.
+    return override === undefined ? undefined : { model: override }
+  },
+  onFinish: (ctx, info) => {
+    // Already guarded by core — but prefer ctx.defer() anyway, so a slow
+    // analytics call does not delay the terminal fan-out at all.
+    ctx.defer(
+      fetch('/api/analytics', {
+        method: 'POST',
+        body: JSON.stringify({ duration: info.duration }),
+      }),
+    )
+  },
 }
 ```
 
-Wrap all middleware hooks in try-catch to prevent analytics or logging failures
-from killing the chat stream. For async side effects, prefer `ctx.defer()` which
-runs after the terminal hook and isolates failures.
+Rule: put the try-catch where the framework has none — `onChunk` and `onConfig`
+(and the other transform hooks: `onStructuredOutputConfig`, `onBeforeToolCall`,
+`onAfterToolCall`). For async side effects in the terminal hooks, prefer
+`ctx.defer()`, which runs after the terminal hook and isolates failures.
 
-Source: docs/advanced/middleware.md
+Source: docs/advanced/middleware.md, `packages/ai/src/activities/chat/middleware/compose.ts`
 
 ## Cross-References
 
 - See also: **ai-core/chat-experience/SKILL.md** -- Middleware hooks into the chat lifecycle
 - See also: **ai-core/structured-outputs/SKILL.md** -- Middleware now wraps the final structured-output call; use `onStructuredOutputConfig` for JSON-Schema transforms
 - See also: **ai-core/ag-ui-protocol/SKILL.md** -- Reading the `sandbox.file` / `sandbox.file.diff` `CUSTOM` chunks the sandbox runtime emits alongside these `sandbox` hooks, via `ChatStream`'s typed `KnownCustomEvent` narrowing
+- See also: **`@tanstack/ai-persistence` skills** (`skills/ai-persistence/SKILL.md` in that package) -- Full persistence suite (`withPersistence`, client storage, store contracts, adapter recipes, locks). This file only sketches server `withPersistence`.

package/skills/ai-core/structured-outputs/SKILL.md

@@ -13,7 +13,7 @@ description: >
   part. convertSchemaToJsonSchema() for manual schema conversion.
 type: sub-skill
 library: tanstack-ai
-library_version: '0.10.0'
+library_version: '0.42.0'
 sources:
   - 'TanStack/ai:docs/structured-outputs/overview.md'
   - 'TanStack/ai:docs/structured-outputs/one-shot.md'