Merge branch 'main' into fix/interleaved-text-tool-args-input

Author: season179

.changeset/artifact-persistence-options-rename.md

@@ -0,0 +1,28 @@
+---
+'@tanstack/ai-persistence': minor
+---
+
+The artifact options for `withGenerationPersistence` are now named
+`ArtifactPersistenceOptions`.
+
+They were declared as a second `export interface WithPersistenceOptions`, which
+TypeScript merged with the chat middleware's options of the same name. The merge
+was invisible but not harmless: `withPersistence(chat, …)` silently accepted
+`extractArtifacts` / `storageKey` / `allowInputUrl` / `artifactFetch`, and
+`WithGenerationPersistenceOptions` — which extends it — advertised
+`snapshotStreaming` / `snapshotIntervalMs`. Every one of those is a no-op on the
+other middleware, so autocomplete offered options that did nothing.
+
+`WithPersistenceOptions` keeps its meaning: the chat middleware's options.
+`WithGenerationPersistenceOptions` is unchanged in shape and is still what you
+pass to `withGenerationPersistence`, so only code that named the artifact
+interface directly needs an edit:
+
+```diff
+-import type { WithPersistenceOptions } from '@tanstack/ai-persistence'
+-function artifactOptions(): WithPersistenceOptions {
++import type { ArtifactPersistenceOptions } from '@tanstack/ai-persistence'
++function artifactOptions(): ArtifactPersistenceOptions {
+   return { storageKey: ({ runId, artifactId }) => `media/${runId}/${artifactId}` }
+ }
+```

.changeset/client-declined-generation-restore.md

@@ -0,0 +1,20 @@
+---
+'@tanstack/ai-client': minor
+---
+
+A restored generation whose result can't be rebuilt now reports an error instead
+of repainting as a blank success.
+
+Every `reconstructResult` mapper in `generation-reconstruct.ts` (and the video
+client's built-in `reconstructVideoResult`) returns `null` when the persisted
+record lacks what it needs — most commonly an output artifact stored without a
+serve `url`, which is possible because `artifactUrl` is optional server-side.
+`repaintFromSnapshot` silently skipped `setResult` in that case, leaving
+`status: 'success'` with `result: null`: a state no consumer can render, and one
+that hides the real cause.
+
+When a mapper declines a snapshot whose status is `complete`, the restore now
+settles on `status: 'error'` with an explanatory message and fires `onError`. A
+decline on any other status is still silent — a `running` snapshot has no result
+yet by definition, and the rejoin delivers it. A client with no
+`reconstructResult` mapper at all is unaffected.

.changeset/client-generation-hydration-errors.md

@@ -0,0 +1,25 @@
+---
+'@tanstack/ai-client': minor
+---
+
+Server-driven generation hydration no longer swallows every failure.
+
+`GenerationClient` / `VideoGenerationClient` mount hydration
+(`persistence: true`) wrapped the whole `hydrateGeneration` call in a bare
+`try { … } catch { return }`, collapsing a transport error, a `403` from the
+`reconstructGeneration` authorize gate, an unparseable body, and "no record for
+this thread" into one indistinguishable silent no-op — so an app could not tell a
+broken server from a fresh thread, and had no signal to retry.
+
+- A genuine **miss** (the server reports no record) stays silent, as before.
+- A genuine **failure** now surfaces on `status` / `error` and fires `onError`,
+  with a message naming the cause. A record the client's own validator rejects
+  (unknown schema version, missing/invalid `status` or `resumeState`) counts as a
+  failure, not a miss.
+- The failure is skipped when a `generate()` took ownership of the client while
+  the hydrate request was in flight — the live run still wins.
+
+Relatedly, `fetchServerSentEvents` / `fetchHttpStream` `hydrateGeneration` now
+only treats a `200` carrying `null` as a miss. Any other non-object body (a
+string, an array) rejects instead of being reported as an empty thread, so a
+misconfigured route no longer masquerades as a fresh one.

.changeset/client-truncated-generation-stream.md

@@ -0,0 +1,27 @@
+---
+'@tanstack/ai-client': minor
+---
+
+A generation stream that ends without a terminal chunk now settles to `error`
+instead of wedging the client on `generating` forever.
+
+`GenerationClient.processStream` / `VideoGenerationClient.processStream` only
+settled the status on `RUN_FINISHED` or `RUN_ERROR`. A `for await` loop over a
+stream that simply _ends_ — a proxy/load-balancer idle timeout, a server restart
+mid-run, or a durable log whose terminal append never landed — returns normally,
+so no catch fired and the client came to rest on
+`status: 'generating'`, `isLoading: false`, `result: null`, with `onError` never
+called. Worse, the resume snapshot stayed `running`, so every subsequent mount
+rejoined the same dead run and repeated the same outcome.
+
+Both clients now throw when the stream ends with no terminal chunk seen (and the
+read wasn't aborted by `stop()` / `dispose()`), which routes the failure through
+the existing error path: `status: 'error'`, `error` set, `onError` fired, and the
+resume snapshot rewritten to a terminal `error` with a null `resumeState` so
+nothing chases it again. This applies to both the initial `generate()` path and
+the mount-time `rejoinInFlight` path. A rejoin failure now also fires `onError`,
+matching `generate()`.
+
+This is the sibling of the earlier "rejoin settles to error" fix, which covered a
+missing and a throwing `joinRun` but not a join that returns cleanly with no
+terminal chunk.

.changeset/client-typed-storage-adapter-defaults.md

@@ -0,0 +1,18 @@
+---
+'@tanstack/ai-client': minor
+---
+
+`localStoragePersistence` / `sessionStoragePersistence` / `indexedDBPersistence`
+are no longer generic. Each returns a `ChatStorageAdapter<ChatPersistedState>`,
+and `WebStoragePersistenceOptions` types its `serialize` / `deserialize` codec
+over `ChatPersistedState`.
+
+The type parameter existed so one adapter could back both the chat and the
+generation `persistence` option. Generation `persistence` is now `boolean`
+(server-driven only), so chat is the sole option that takes a storage adapter and
+the parameter had no second value to hold.
+
+A bare `localStoragePersistence()` is unchanged. A call that passed an explicit
+type argument for a standalone store, `localStoragePersistence<MyValue>()`, no
+longer compiles: build that store with your own object literal, since these
+factories are for chat state.

.changeset/conformance-generation-stores.md

@@ -0,0 +1,20 @@
+---
+'@tanstack/ai-persistence': minor
+---
+
+Extend the shared conformance testkit to the generation stores.
+
+**Migration — every existing adapter must update its conformance call.** The suite now fails loudly on a store that is absent without being declared, so a chat-only adapter that used to pass unchanged will start failing on `generationRuns` / `artifacts` / `blobs`. Declare them absent:
+
+```diff
+- runPersistenceConformance('my-adapter', () => makePersistence())
++ runPersistenceConformance('my-adapter', () => makePersistence(), {
++   skip: ['generationRuns', 'artifacts', 'blobs'],
++ })
+```
+
+Drop an entry from `skip` as you implement that store — the suite then holds it to the contract below. Declaring absence is deliberate: a silently skipped store is how an adapter ships a `generationRuns` implementation that was never exercised.
+
+`runPersistenceConformance` now exercises `generationRuns`, `artifacts`, and `blobs` alongside the four chat state stores, so a hand-rolled generation backend is held to the same gate as a chat one: `createOrResume` idempotency and `findLatestForThread` (latest by `startedAt`, thread-scoped, terminal runs included) on the run store; upsert `save`, `list(runId)` ordering, and `delete` / `deleteForRun` scoping on the artifact store; and byte/metadata round-trips, overwrite, silent absent-key `delete`, and `list` prefix + cursor paging on the blob store. Two invariants that were easy to get wrong and are now checked: `list`'s `prefix` matches **literally and case-sensitively** (a SQL backend using `LIKE` fails on both counts, since SQLite's `LIKE` is case-insensitive for ASCII and treats `%` / `_` as wildcards), and cursor paging visits every key exactly once.
+
+`examples/ts-react-chat`'s self-contained `node:sqlite` adapter implements all seven stores and runs the full suite; its server-side generation route is backed by that adapter, so generated images survive a dev-server restart.

.changeset/core-jsdoc-server-fn-example.md

@@ -0,0 +1,7 @@
+---
+'@tanstack/ai': patch
+---
+
+Fix `@tanstack/ai` breaking non-React TanStack Start builds.
+
+A JSDoc example on `replayRunStream` inlined a server-function builder chain. Comments survive into `dist`, and Start's server-fn Vite plugin decides whether a module needs compiling by regex-matching the source — so it treated this package as a server-fn module and tried to resolve the framework's `@tanstack/*-start` package, failing the build of any Solid/Vue/Svelte Start app (`could not resolve "@tanstack/solid-start"`). The example now declares the generator separately and no longer trips the match.

.changeset/core-result-transforms-required.md

@@ -0,0 +1,7 @@
+---
+'@tanstack/ai': minor
+---
+
+`GenerationMiddlewareContext.resultTransforms` is now required.
+
+Middleware registers a result transform by pushing onto the array, so an optional one let a host that builds its own context omit it and silently no-op every registration — generation persistence would then mark a run completed with neither its result nor its artifacts written, with nothing to observe but the missing data. Every context the library builds already comes from `createGenerationContext`, which always sets `[]`, so this only affects code that constructs a `GenerationMiddlewareContext` by hand: set `resultTransforms: []`.

.changeset/core-summarize-generation-middleware.md

@@ -0,0 +1,9 @@
+---
+'@tanstack/ai': minor
+---
+
+`summarize()` accepts generation middleware, so summaries can be persisted.
+
+`useSummarize({ persistence: true, threadId })` type-checked exactly like the six media hooks, but `summarize()` took no `middleware`, so no library path could ever write its run record and a reload restored nothing. It now takes `middleware` like the `generate*` activities: one `onStart`, the result transforms applied to the `SummarizationResult`, then `onFinish` / `onError`, in both streaming and non-streaming mode (a consumer that disconnects mid-summary fires `onAbort`). In streaming mode the transformed result is what is yielded, so the client and the persisted record hold the same object.
+
+`GenerationActivity` gained `'summarize'`, and `otelMiddleware` maps it to the `summarize` operation name. Summaries are text, so there are no artifacts: a persistence middleware stores the run record and its result and nothing else.

.changeset/core-video-job-run-lifecycle.md

@@ -0,0 +1,15 @@
+---
+'@tanstack/ai': minor
+---
+
+Fix non-streaming `generateVideo()` losing the generation when persistence is on.
+
+A non-streaming `generateVideo()` call only SUBMITS a job — the video does not exist until a later poll — but it fired `onFinish` as soon as the job was queued and never applied the result transforms, and it never put the caller's `threadId` on the middleware context. With `withGenerationPersistence` that meant `generateVideo({ threadId, middleware })` threw for want of a scope, and (once given one) would have stamped the run `completed` with no result, no url, and no stored bytes, while the eventual result had nowhere to land.
+
+Submitting a job now OPENS the run and `getVideoJobStatus()` closes it, with the two calls correlated by the provider's **`jobId`** — the one id a poller structurally cannot be missing, since it cannot poll without it. Nothing else has to be threaded through:
+
+- `generateVideo()` (non-streaming) passes `threadId` and the prompt inputs to middleware, files the run under an id derived from the provider + `jobId`, applies the result transforms to the submission (so the run record captures the `jobId` and stays resumable from a later request or process), and fires **no terminal hook**.
+- `getVideoJobStatus()` accepts `threadId` and `middleware`, and recomputes the same run id from `adapter` + `jobId`. On the poll that first observes a terminal job state it resumes that run, applies the result transforms — which is where persistence copies the video into the blob store and rewrites `url` to a durable one, so the returned result and the stored record carry the same urls — and fires `onFinish`, or `onError` when the job (or the url fetch) failed. Intermediate polls invoke nothing. Its result gained `jobId`, `expiresAt`, and `artifacts`; `VideoJobResult` gained `artifacts` (refs for persisted prompt INPUTS, e.g. a start frame).
+- `runId` on a non-streaming `generateVideo()` call is **ignored** (it remains the wire run id in stream mode). The run id has to be recomputable by the poll from the `jobId` alone; honoring a custom one would reintroduce the failure this avoids — a caller who set it on the submit and forgot it on the poll would silently open a second record while the first sat unfinished forever.
+
+Two consequences worth knowing. Because the job id only exists once the provider accepts the job, `onStart` now fires AFTER the submit request, so an `otelMiddleware()` span covers the run from acceptance onward rather than the submit round-trip, and a submission that FAILS (no job to key on) opens and immediately fails a run under the call's `requestId` — terminal and unresumable, but filed under the thread so a hydrating client sees the failure. And `threadId` must reach the poll: omitting it makes generation persistence throw loudly rather than file the finished video where nothing can hydrate it.