feat(persistence): generation run persistence (client + server)

.changeset/generation-persistence.md

@@ -0,0 +1,30 @@
+---
+'@tanstack/ai': minor
+'@tanstack/ai-utils': minor
+'@tanstack/ai-persistence': minor
+'@tanstack/ai-client': minor
+'@tanstack/ai-event-client': minor
+'@tanstack/ai-react': minor
+'@tanstack/ai-solid': minor
+'@tanstack/ai-vue': minor
+'@tanstack/ai-svelte': minor
+'@tanstack/ai-angular': minor
+---
+
+Add generation persistence, mirroring chat: media generation runs survive a reload or dropped connection, restoring transparently into the normal hook fields, with optional durable storage of the generated bytes.
+
+**Generation run store (server).** `withGenerationPersistence` records each run in a dedicated `generationRuns` (`GenerationRunStore`) store, keyed by the run's own `runId` (the same AG-UI run id the client sends), with `threadId` the run's scope — it no longer overloads the chat `RunStore`. The record holds the activity/provider/model, lifecycle status, result metadata, and (when byte storage is on) the durable artifact refs. `memoryPersistence()` ships an in-memory `generationRuns` store, and `defineGenerationRunStore` / `defineArtifactStore` / `defineBlobStore` type a custom store inline the way `defineMessageStore` / `defineRunStore` already do.
+
+**Server-side load (`reconstructGeneration`).** A new `reconstructGeneration(persistence, request, options?)` server helper — the generation parallel of `reconstructChat` — reads a `?runId=` (or `?threadId=`) from the request, authorizes it via an `authorize` callback, and returns `{ resumeSnapshot, activeRun }` JSON so a server-authoritative client restores the last run on mount. Requires the `generationRuns` store. `authorize` is optional at the type level for single-user and prototype routes, but any multi-user deployment must pass it: the run and thread ids arrive from the caller, so identity has to be derived from server-side session state and ownership checked before the helper reads persistence. The same applies to a route that serves artifact bytes by id.
+
+**Media byte storage (server).** When the backend also provides both an `artifacts` (`ArtifactStore`) and a `blobs` (`BlobStore`) store, `withGenerationPersistence` writes each generated file's bytes to the blob store (key `artifacts/<runId>/<artifactId>`), records an `ArtifactRecord`, and attaches `PersistedArtifactRef`s to the result and the run record. A new `artifactUrl` option stamps a durable app-origin serve URL onto each ref (a new `PersistedArtifactRef.url`) and rewrites the live result's media URL to it, so live and restored results both render media from your own origin instead of the provider's expiring link. Extraction is customizable via `extractArtifacts` / `nameArtifact`; `retrieveArtifact` / `retrieveBlob` (and the shared `artifactBlobKey`) serve the bytes back. Prompt media referenced by **URL** is not downloaded: the URL is caller-supplied, so fetching it server-side would be an SSRF vector, and the bytes are redundant. Opt in per-app with `allowInputUrl` (a predicate, so the check can't be skipped). Every artifact fetch is limited to `http:`/`https:`, timed out (`artifactFetchTimeoutMs`, default 30s) and size-capped (`maxArtifactBytes`, default 100 MiB); input fetches additionally block loopback/private/link-local hosts and refuse redirects. `artifactFetch` injects the `fetch` used, for routing downloads through an egress-restricted proxy. `memoryPersistence()` ships in-memory `artifacts`/`blobs` stores; the generation activities gained `threadId` / `runId` options. `@tanstack/ai-utils` adds `base64ToUint8Array`.
+
+**Client (transparent restore).** Generation hooks (`useGenerateImage`, `useGenerateVideo`, `useGenerateAudio`, `useGenerateSpeech`, `useGeneration`, `useSummarize`, `useTranscription`, and their Solid/Vue/Svelte/Angular equivalents) take the same `persistence` option chat does: `true` (server-driven — cache nothing, hydrate the last run for a stable `threadId` on mount) or a storage adapter (client-driven — write a lightweight snapshot under `generation:<threadId>` as the run streams and read it back on mount). Restore is **invisible**: it repaints the normal `result` / `status` / `error` fields as if the run had just finished, and keeps `resumeState` for the in-flight run identity — there is no `resumeSnapshot` / `pendingArtifacts` / `resultArtifacts` hook field. If a run is still generating when the connection drops or the page reloads, the client re-attaches to it and finishes it in place (via the connection's `joinRun` durability replay), exactly like `useChat`. With byte storage configured, a restored `result` is rebuilt whole, its media resolved to the durable serve URL and its refs on `result.artifacts`; without it, `status` / `error` restore and `result` stays null. The snapshot never holds the generated bytes and never restarts provider work — generation still only begins on `generate(...)`.
+
+**`threadId` is required whenever `persistence` is set**, in both modes, enforced at the type level. It is the generation's _scope_ — a stable, app-chosen name for the slot successive runs fill (`product-123-hero`, `video-9-start-frame`) — not a link to a chat conversation, so a workflow generating media outside any conversation names it just as naturally. It stays optional for ephemeral generations, so existing call sites that do not opt into persistence are unaffected. Persistence keys on it in both modes; `id` is the devtools/instance label only and never keys storage. Previously the key fell back to `id` and then to a generated id, which silently wrote a different slot on every reload — restoring nothing while orphaning the last record.
+
+**Choose where bytes land.** `withGenerationPersistence`'s new `storageKey` option maps each artifact to its blob-store key, so generated media can live in your own folder structure instead of the default `artifacts/<runId>/<artifactId>`. Server-side only — a browser-supplied key would be a path-traversal and cross-tenant-write vector. The resolved key is recorded on the new `ArtifactRecord.blobKey` (it is no longer derivable once arbitrary) and reads resolve through `resolveArtifactBlobKey`; records written before the field existed fall back to the default convention, so it is a non-breaking addition.
+
+`reconstructGeneration` now throws, rather than silently returning no run, when a `?threadId=` lookup is made against a `generationRuns` store that does not implement the optional `findLatestForThread`. A `?runId=` lookup never needs it and still works on a minimal adapter.
+
+The `persistence` option reuses the same `ChatStorageAdapter` contract as chat, so the shared `localStoragePersistence` / `sessionStoragePersistence` / `indexedDBPersistence` factories work for generations too with no type argument (a bare call is correct on either side). Untrusted snapshots are validated with the new `parseGenerationResumeSnapshot`.

docs/chat/streaming.md

@@ -88,6 +88,46 @@ TanStack AI implements the [AG-UI Protocol](https://docs.ag-ui.com/introduction)
 
 > **Tip:** Some models expose their internal reasoning as thinking content that streams before the response. See [Thinking & Reasoning](./thinking-content).
 
+### Threads and runs
+
+Two ids frame every stream, and they come from the AG-UI protocol itself — not
+from any storage layer:
+
+- A **thread** (`threadId`) is the conversation: the stable identity across
+  every exchange, reload, and device.
+- A **run** (`runId`) is one execution inside it: everything between one
+  `RUN_STARTED` and its `RUN_FINISHED` (or `RUN_ERROR`). Every start mints a
+  fresh run id, so a thread accumulates many runs over its life.
+
+A run is not limited to a single model response. Tool calls and their
+follow-up responses stream inside the same run — the whole
+[agentic cycle](./agentic-cycle), however many loops it takes, is one run:
+
+```mermaid
+flowchart LR
+    subgraph thread ["Thread — threadId (stable)"]
+        direction LR
+        subgraph r1 ["Run r1 — finished"]
+            direction TB
+            e1["RUN_STARTED → text → tool call → tool result → final text → RUN_FINISHED"]
+        end
+        subgraph r2 ["Run r2 — finished"]
+            direction TB
+            e2["RUN_STARTED → text → RUN_FINISHED"]
+        end
+        subgraph r3 ["Run r3 — running"]
+            direction TB
+            e3["RUN_STARTED → text"]
+        end
+        r1 --> r2 --> r3
+    end
+```
+
+Because run ids are ephemeral, anything long-lived anchors on the thread:
+[resumable streams](../resumable-streams/overview) log delivery per `runId`,
+while [server persistence](../persistence/chat-persistence#threads-runs-and-turns)
+stores the transcript per `threadId`.
+
 ### Type-Safe Tool Call Events
 
 When you pass typed tools (defined with `toolDefinition()` and Zod schemas) to `chat()`, the stream chunks automatically carry type information for tool call events. Prefer the AG-UI field `toolCallName` (or the deprecated `toolName` alias) — both narrow to the union of your tool name literals. The `input` field on `TOOL_CALL_END` is typed as the union of your tool input schemas (typically set on the adapter-emitted END once arguments are complete):

docs/config.json

@@ -164,7 +164,7 @@
           "label": "Streaming",
           "to": "chat/streaming",
           "addedAt": "2026-04-15",
-          "updatedAt": "2026-07-17"
+          "updatedAt": "2026-07-29"
         },
         {
           "label": "Connection Adapters",
@@ -186,7 +186,7 @@
           "label": "Overview",
           "to": "interrupts/overview",
           "addedAt": "2026-07-16",
-          "updatedAt": "2026-07-22"
+          "updatedAt": "2026-07-29"
         },
         {
           "label": "Tool Approval",
@@ -221,7 +221,7 @@
           "label": "Overview",
           "to": "resumable-streams/overview",
           "addedAt": "2026-07-17",
-          "updatedAt": "2026-07-23"
+          "updatedAt": "2026-07-29"
         },
         {
           "label": "Advanced",
@@ -242,31 +242,43 @@
           "label": "Overview",
           "to": "persistence/overview",
           "addedAt": "2026-07-22",
-          "updatedAt": "2026-07-27"
+          "updatedAt": "2026-07-29"
         },
         {
           "label": "Chat Persistence",
           "to": "persistence/chat-persistence",
           "addedAt": "2026-07-22",
-          "updatedAt": "2026-07-26"
+          "updatedAt": "2026-07-29"
         },
         {
           "label": "Client Persistence",
           "to": "persistence/client-persistence",
           "addedAt": "2026-07-22",
-          "updatedAt": "2026-07-27"
+          "updatedAt": "2026-07-28"
+        },
+        {
+          "label": "Generation Persistence",
+          "to": "persistence/generation-persistence",
+          "addedAt": "2026-07-28",
+          "updatedAt": "2026-07-29"
+        },
+        {
+          "label": "Keep Generated Files",
+          "to": "persistence/keep-generated-files",
+          "addedAt": "2026-07-28",
+          "updatedAt": "2026-07-29"
         },
         {
           "label": "Controls",
           "to": "persistence/controls",
           "addedAt": "2026-07-22",
-          "updatedAt": "2026-07-25"
+          "updatedAt": "2026-07-29"
         },
         {
           "label": "Build Your Own Adapter",
           "to": "persistence/build-your-own-adapter",
           "addedAt": "2026-07-24",
-          "updatedAt": "2026-07-28"
+          "updatedAt": "2026-07-29"
         },
         {
           "label": "Migrations",
@@ -278,7 +290,7 @@
           "label": "Internals",
           "to": "persistence/internals",
           "addedAt": "2026-07-22",
-          "updatedAt": "2026-07-25"
+          "updatedAt": "2026-07-29"
         }
       ]
     },
@@ -377,7 +389,7 @@
           "label": "Transcription",
           "to": "media/transcription",
           "addedAt": "2026-04-15",
-          "updatedAt": "2026-07-03"
+          "updatedAt": "2026-07-28"
         },
         {
           "label": "Audio Recording",
@@ -389,25 +401,25 @@
           "label": "Audio Generation",
           "to": "media/audio-generation",
           "addedAt": "2026-04-23",
-          "updatedAt": "2026-06-08"
+          "updatedAt": "2026-07-28"
         },
         {
           "label": "Image Generation",
           "to": "media/image-generation",
           "addedAt": "2026-04-15",
-          "updatedAt": "2026-07-07"
+          "updatedAt": "2026-07-28"
         },
         {
           "label": "Video Generation",
           "to": "media/video-generation",
           "addedAt": "2026-04-15",
-          "updatedAt": "2026-07-02"
+          "updatedAt": "2026-07-28"
         },
         {
           "label": "Generation Hooks",
           "to": "media/generation-hooks",
           "addedAt": "2026-04-15",
-          "updatedAt": "2026-07-10"
+          "updatedAt": "2026-07-28"
         }
       ]
     },
@@ -618,7 +630,7 @@
           "updatedAt": "2026-07-08"
         },
         {
-          "label": "Sampling → modelOptions",
+          "label": "Sampling \u2192 modelOptions",
           "to": "migration/sampling-options-to-model-options",
           "addedAt": "2026-06-03"
         }

docs/interrupts/overview.md

@@ -30,6 +30,24 @@ picks up exactly where it left off once you answer.
 4. The client starts a fresh continuation run that carries your answers and
    continues the agent.
 
+```mermaid
+sequenceDiagram
+    participant User
+    participant Client
+    participant Server
+
+    Client->>Server: send message — run starts
+    Server-->>Client: interrupt outcome — run ends without a final answer
+    Client->>User: pending decisions surface as `interrupts`
+    User->>Client: approve / reject / submit a value
+    Client->>Server: continuation request with the answers — a fresh run
+    Server-->>Client: the agent picks up where it paused, final answer
+```
+
+Note that the pause spans **two runs**: the interrupted one ends, and the
+continuation is a new run. One user-visible turn, two run lifecycles — see
+[Threads and runs](../chat/streaming#threads-and-runs).
+
 No database is required. The browser sends the full message history back on the
 continuation request, so a stateless server can rebuild the paused step and keep
 going.

docs/media/audio-generation.md

@@ -161,6 +161,10 @@ flow. It mirrors the API of `useGenerateSpeech`, `useGenerateImage`, and
 other media hooks — see [Generation Hooks](./generation-hooks) for the full
 shape.
 
+> **Note:** For long tracks, keep the run's status and result across a reload or
+> a dropped connection — and the audio after the provider's URL expires — with
+> [Generation Persistence](../persistence/generation-persistence).
+
 ### Server (streaming SSE route)
 
 ```typescript

docs/media/generation-hooks.md

@@ -19,6 +19,11 @@ keywords:
 
 TanStack AI provides framework hooks for every generation type: image, audio, speech, transcription, summarization, and video. Each hook connects to a server endpoint and manages loading, error, and result state for you.
 
+> **Surviving reloads and dropped connections:** every generation hook takes the
+> same `persistence` option `useChat` does, so a long run's status and result
+> come back after a page reload or a dropped connection. See
+> [Generation Persistence](../persistence/generation-persistence).
+
 ## Overview
 
 Generation hooks share a consistent API across all media types:

docs/media/image-generation.md

@@ -508,6 +508,9 @@ try {
 
 TanStack AI provides React hooks and server-side streaming helpers to build full-stack image generation with minimal boilerplate.
 
+> **Note:** To keep a batch across reloads, or to keep the images after the
+> provider's URLs expire, add [Generation Persistence](../persistence/generation-persistence).
+
 ### Streaming Mode (Server Route + Client Hook)
 
 **Server** — Create an API route that wraps `generateImage` as a streaming response:

docs/media/transcription.md

@@ -397,6 +397,10 @@ export async function POST(request: Request) {
 
 TanStack AI provides React hooks and server-side streaming helpers to build full-stack audio transcription with minimal boilerplate.
 
+> **Note:** Transcribing a big file can run long — keep its status and result
+> across a reload or a dropped connection with
+> [Generation Persistence](../persistence/generation-persistence).
+
 ### Streaming Mode (Server Route + Client Hook)
 
 **Server** — Create an API route that wraps `generateTranscription` as a streaming response:

docs/media/video-generation.md

@@ -46,6 +46,15 @@ Currently supported:
 - **Grok (xAI)**: grok-imagine-video (text-to-video + image-to-video) and grok-imagine-video-1.5 (image-to-video only) models
 - **fal.ai**: MiniMax, Luma, Kling, Hunyuan, and other hosted video models
 
+> **Video runs take minutes — don't lose them to a reload.** This is the
+> strongest case for [Generation Persistence](../persistence/generation-persistence):
+> it keeps a record of each run, so after a reload the hook shows that run's last
+> known status and result instead of an empty form. A run that is still streaming
+> against a durable server-side stream is re-attached and finished in place;
+> otherwise the record is restored, not the provider work. And because provider video URLs expire,
+> [keep the finished clip](../persistence/keep-generated-files) by saving its
+> bytes to your own storage.
+
 ## Basic Usage
 
 ### Creating a Video Job