diff --git a/.changeset/persistence-v2.md b/.changeset/persistence-v2.md
new file mode 100644
index 000000000..66ccbe706
--- /dev/null
+++ b/.changeset/persistence-v2.md
@@ -0,0 +1,43 @@
+---
+'@tanstack/ai': minor
+'@tanstack/ai-client': minor
+'@tanstack/ai-durable-stream': minor
+'@tanstack/ai-persistence': minor
+'@tanstack/ai-persistence-drizzle': minor
+'@tanstack/ai-persistence-prisma': minor
+'@tanstack/ai-angular': minor
+'@tanstack/ai-preact': minor
+'@tanstack/ai-react': minor
+'@tanstack/ai-solid': minor
+'@tanstack/ai-svelte': minor
+'@tanstack/ai-vue': minor
+---
+
+Persistence v2: split state (middleware) vs delivery (transport) durability.
+
+State durability stays on the middleware layer as `withChatPersistence` /
+`withGenerationPersistence`, backed by a store contract (messages, runs,
+interrupts, metadata, locks, artifacts, blobs). The `@tanstack/ai-persistence`
+package now ships a state-only middleware, an in-core memory backend, and a
+shared conformance suite; `@tanstack/ai-persistence-drizzle` and
+`@tanstack/ai-persistence-prisma` provide state backends.
+
+Delivery durability (replay a disconnected/reloaded stream) moves to the
+transport layer via a pluggable `StreamDurability` sink — the SDK owns zero
+delivery-event storage. The new `@tanstack/ai-durable-stream` package provides a
+durable-streams-protocol `StreamDurability` adapter, and the client
+(`@tanstack/ai-client`) plus every framework binding (`@tanstack/ai-react`,
+`-solid`, `-vue`, `-svelte`, `-angular`, `-preact`) switch to resumable SSE with
+interrupt-only resume.
+
+The home-grown delivery/event-log subsystem is removed: the in-band `cursor` on
+`StreamChunk`, the `cursor` param on `chat()`, the public/internal event stores,
+the `ResumeSource` seam, cursor-replay client machinery, and the deprecated
+approval-store shim are all deleted (this feature is unreleased — no back-compat
+shims). Interrupt resume (approvals / client-tool results via
+`RunAgentInput.resume[]`) is preserved as state durability.
+
+The delivery-store / SQL-driver packages that only existed to back the removed
+event log — `@tanstack/ai-persistence-sql`, `-sqlite`, `-postgres`, and
+`-cloudflare` — are removed. They were never published (part of this same
+unreleased persistence work), so no npm tombstone release is needed.
diff --git a/docs/api/ai-angular.md b/docs/api/ai-angular.md
index 438c3bf46..12ad892a7 100644
--- a/docs/api/ai-angular.md
+++ b/docs/api/ai-angular.md
@@ -381,9 +381,12 @@ export class CustomGenerationComponent {
 }
 ```
 
-**Options:** `connection?`, `fetcher?`, `id?`, `body?` (reactive), `devtools?`, `onResult?`, `onError?`, `onProgress?`, `onChunk?`
+**Options:** `connection?`, `fetcher?`, `id?`, `body?` (reactive), `persistence?`, `autoResume?`, `initialResumeSnapshot?`, `resumeState?` (reactive), `devtools?`, `onResult?`, `onError?`, `onProgress?`, `onChunk?`
 
-**Returns:** `generate`, `result`, `isLoading`, `error`, `status`, `stop`, `reset` — all reactive state is a read-only `Signal<T>`.
+**Returns:** `generate`, `result`, `isLoading`, `error`, `status`, `stop`, `reset`, `resume`, `resumeSnapshot`, `resumeState`, `pendingArtifacts`, `resultArtifacts` — all reactive state is a read-only `Signal<T>`.
+
+For the end-to-end persistence setup, see
+[Generation Persistence](../persistence/generation-persistence).
 
 ### `injectGenerateImage(options)`
 
diff --git a/docs/api/ai-react.md b/docs/api/ai-react.md
index 0cc599357..660e5cf93 100644
--- a/docs/api/ai-react.md
+++ b/docs/api/ai-react.md
@@ -86,7 +86,7 @@ Extends `ChatClientOptions` from `@tanstack/ai-client`:
 - `initialMessages?` - Initial messages array
 - `id?` - Unique identifier for this chat instance
 - `threadId?` - Thread ID for AG-UI run correlation. Persists across sends; auto-generated if omitted
-- `forwardedProps?` - Arbitrary client-controlled JSON forwarded to the server in the AG-UI `RunAgentInput.forwardedProps` field (e.g., `{ provider: 'openai', model: 'gpt-4o' }`)
+- `forwardedProps?` - Arbitrary client-controlled JSON forwarded to the server in the AG-UI `RunAgentInput.forwardedProps` field (e.g., `{ provider: 'openai', model: 'gpt-5.5' }`)
 - `body?` - **Deprecated.** Use `forwardedProps` instead. Still works for backward compatibility; values are merged into `forwardedProps` on the wire
 - `context?` - Typed client-local runtime context passed to client tool implementations. This value is not serialized to the server
 - `onResponse?` - Callback when response is received
@@ -159,6 +159,24 @@ function that resolves per request.
 For error narrowing, import `UnsupportedResponseStreamError` and
 `StreamTruncatedError` from `@tanstack/ai-client`.
 
+## Generation Hooks
+
+React also exports `useGeneration`, `useGenerateImage`, `useGenerateAudio`,
+`useGenerateSpeech`, `useTranscription`, `useSummarize`, and
+`useGenerateVideo`.
+
+Generation hook options include `connection` or `fetcher`, `id`, `body`,
+`persistence`, `autoResume`, `initialResumeSnapshot`, `resumeState`,
+`devtools`, `onResult`, `onError`, `onProgress`, and `onChunk`.
+
+Generation hook returns include `generate`, `result`, `isLoading`, `error`,
+`status`, `stop`, `reset`, `resume`, `resumeSnapshot`, `resumeState`,
+`pendingArtifacts`, and `resultArtifacts`. Video generation also returns
+`jobId` and `videoStatus`.
+
+For the end-to-end persistence setup, see
+[Generation Persistence](../persistence/generation-persistence).
+
 ## Example: Basic Chat
 
 ```tsx
diff --git a/docs/api/ai-solid.md b/docs/api/ai-solid.md
index 855ce883e..a87426bfd 100644
--- a/docs/api/ai-solid.md
+++ b/docs/api/ai-solid.md
@@ -77,7 +77,7 @@ Extends `ChatClientOptions` from `@tanstack/ai-client`:
 - `initialMessages?` - Initial messages array
 - `id?` - Unique identifier for this chat instance
 - `threadId?` - Thread ID for AG-UI run correlation. Persists across sends; auto-generated if omitted
-- `forwardedProps?` - Arbitrary client-controlled JSON forwarded to the server in the AG-UI `RunAgentInput.forwardedProps` field (e.g., `{ provider: 'openai', model: 'gpt-4o' }`)
+- `forwardedProps?` - Arbitrary client-controlled JSON forwarded to the server in the AG-UI `RunAgentInput.forwardedProps` field (e.g., `{ provider: 'openai', model: 'gpt-5.5' }`)
 - `body?` - **Deprecated.** Use `forwardedProps` instead. Still works for backward compatibility; values are merged into `forwardedProps` on the wire
 - `context?` - Typed client-local runtime context passed to client tool implementations. This value is not serialized to the server
 - `onResponse?` - Callback when response is received
@@ -121,6 +121,25 @@ interface UseChatReturn {
 
 **Note:** Unlike React, `messages`, `isLoading`, and `error` are SolidJS `Accessor` functions, so you need to call them to get their values (e.g., `messages()` instead of just `messages`).
 
+## Generation Hooks
+
+Solid also exports `useGeneration`, `useGenerateImage`, `useGenerateAudio`,
+`useGenerateSpeech`, `useTranscription`, `useSummarize`, and
+`useGenerateVideo`.
+
+Generation hook options include `connection` or `fetcher`, `id`, `body`,
+`persistence`, `autoResume`, `initialResumeSnapshot`, `resumeState`,
+`devtools`, `onResult`, `onError`, `onProgress`, and `onChunk`.
+
+Generation hook returns include `generate`, `result`, `isLoading`, `error`,
+`status`, `stop`, `reset`, `resume`, `resumeSnapshot`, `resumeState`,
+`pendingArtifacts`, and `resultArtifacts`. Reactive values are Solid accessors,
+so read `resumeState()` and `pendingArtifacts()`. Video generation also returns
+`jobId` and `videoStatus`.
+
+For the end-to-end persistence setup, see
+[Generation Persistence](../persistence/generation-persistence).
+
 ## Connection Adapters
 
 Re-exported from `@tanstack/ai-client` for convenience:
diff --git a/docs/api/ai-svelte.md b/docs/api/ai-svelte.md
index 6f8278043..5ce2e24a3 100644
--- a/docs/api/ai-svelte.md
+++ b/docs/api/ai-svelte.md
@@ -75,7 +75,7 @@ Extends `ChatClientOptions` from `@tanstack/ai-client` (minus internal state cal
 - `initialMessages?` - Initial messages array
 - `id?` - Unique identifier for this chat instance
 - `threadId?` - Thread ID for AG-UI run correlation. Persists across sends; auto-generated if omitted
-- `forwardedProps?` - Arbitrary client-controlled JSON forwarded to the server in the AG-UI `RunAgentInput.forwardedProps` field (e.g., `{ provider: 'openai', model: 'gpt-4o' }`)
+- `forwardedProps?` - Arbitrary client-controlled JSON forwarded to the server in the AG-UI `RunAgentInput.forwardedProps` field (e.g., `{ provider: 'openai', model: 'gpt-5.5' }`)
 - `body?` - **Deprecated.** Use `forwardedProps` instead. Still works for backward compatibility; values are merged into `forwardedProps` on the wire
 - `context?` - Typed client-local runtime context passed to client tool implementations. This value is not serialized to the server
 - `live?` - Enable live subscription mode (subscribes on creation)
@@ -299,9 +299,12 @@ const gen = createGeneration({
 // gen.result, gen.isLoading, gen.error, gen.status
 ```
 
-**Options:** `connection?`, `fetcher?`, `id?`, `body?`, `onResult?`, `onError?`, `onProgress?`, `onChunk?`
+**Options:** `connection?`, `fetcher?`, `id?`, `body?`, `persistence?`, `autoResume?`, `initialResumeSnapshot?`, `resumeState?`, `onResult?`, `onError?`, `onProgress?`, `onChunk?`
 
-**Returns:** `generate`, `result`, `isLoading`, `error`, `status`, `stop`, `reset`, `updateBody` -- all state properties are reactive getters.
+**Returns:** `generate`, `result`, `isLoading`, `error`, `status`, `stop`, `reset`, `updateBody`, `dispose`, `resume`, `resumeSnapshot`, `resumeState`, `pendingArtifacts`, `resultArtifacts` -- all state properties are reactive getters.
+
+For the end-to-end persistence setup, see
+[Generation Persistence](../persistence/generation-persistence).
 
 ### `createGenerateImage(options)`
 
diff --git a/docs/api/ai-vue.md b/docs/api/ai-vue.md
index 5b9cf0707..f8c4e3a81 100644
--- a/docs/api/ai-vue.md
+++ b/docs/api/ai-vue.md
@@ -316,9 +316,12 @@ const { generate, result, isLoading, error, status, stop, reset } =
   });
 ```
 
-**Options:** `connection?`, `fetcher?`, `id?`, `body?`, `onResult?`, `onError?`, `onProgress?`, `onChunk?`
+**Options:** `connection?`, `fetcher?`, `id?`, `body?`, `persistence?`, `autoResume?`, `initialResumeSnapshot?`, `resumeState?`, `onResult?`, `onError?`, `onProgress?`, `onChunk?`
 
-**Returns:** `generate`, `result`, `isLoading`, `error`, `status`, `stop`, `reset` -- all reactive state is `DeepReadonly<ShallowRef<T>>`.
+**Returns:** `generate`, `result`, `isLoading`, `error`, `status`, `stop`, `reset`, `resume`, `resumeSnapshot`, `resumeState`, `pendingArtifacts`, `resultArtifacts` -- all reactive state is `DeepReadonly<ShallowRef<T>>`. Read refs with `.value` in `<script setup>`.
+
+For the end-to-end persistence setup, see
+[Generation Persistence](../persistence/generation-persistence).
 
 ### `useGenerateImage(options)`
 
diff --git a/docs/architecture/approval-flow-processing.md b/docs/architecture/approval-flow-processing.md
index 04632bbe6..aa42c9aa1 100644
--- a/docs/architecture/approval-flow-processing.md
+++ b/docs/architecture/approval-flow-processing.md
@@ -41,6 +41,12 @@ execution until the user explicitly approves or denies the action. This
 creates a human-in-the-loop checkpoint for sensitive operations (sending
 emails, making purchases, deleting data).
 
+The primary durable wait signal is now the AG-UI terminal event
+`RUN_FINISHED.outcome.type === 'interrupt'`. The legacy
+`CUSTOM { name: "approval-requested" }` event is kept as a compatibility
+projection for older clients and UI state updates, but new persistence and
+resume logic should treat actionable waits as interrupts.
+
 The flow spans three layers:
 
 ```mermaid
@@ -55,9 +61,9 @@ flowchart TD
 
 | Layer | Responsibility |
 |-------|----------------|
-| **Server (TextEngine)** | `chat()` detects `needsApproval` → emits CUSTOM `approval-requested` instead of executing the tool |
-| **StreamProcessor** | Receives CUSTOM chunk → `updateToolCallApproval()` → fires `onApprovalRequest` callback |
-| **ChatClient** | Exposes `addToolApprovalResponse()` → updates message state → triggers `checkForContinuation()` → sends new stream |
+| **Server (TextEngine)** | `chat()` detects `needsApproval` -> emits a `RUN_FINISHED` interrupt outcome and may project legacy `approval-requested` events |
+| **StreamProcessor** | Receives interrupt outcome / compatibility custom event -> `updateToolCallApproval()` -> fires `onApprovalRequest` callback |
+| **ChatClient** | Exposes `addToolApprovalResponse()` -> updates message state -> sends AG-UI `RunAgentInput.resume[]` entries through the next request |
 
 Framework hooks (`useChat` in React, Solid, Vue, Svelte) delegate to
 `ChatClient`, which owns all concurrency and continuation logic.
@@ -70,15 +76,23 @@ Framework hooks (`useChat` in React, Solid, Vue, Svelte) delegate to
 
 - Runs the agent loop: calls the LLM adapter, accumulates tool calls, executes
   tools, and re-invokes the adapter with results.
-- When a tool has `needsApproval: true`, the engine emits a
-  `CUSTOM { name: "approval-requested" }` event instead of executing the tool.
-- The stream ends with `RUN_FINISHED { finishReason: "tool_calls" }` so the
-  client knows tools are pending.
+- When a tool has `needsApproval: true`, the engine emits a terminal
+  `RUN_FINISHED` event with `outcome.type === 'interrupt'` instead of executing
+  the tool.
+- Compatibility `CUSTOM { name: "approval-requested" }` events may still be
+  emitted or projected so older approval UI can render the same tool-call state.
+- Persistence stores pending interrupts and validates the later
+  `RunAgentInput.resume[]` response before accepting normal new input on the
+  same thread.
 
 ### StreamProcessor (`packages/ai/src/activities/chat/stream/processor.ts`)
 
 - Single source of truth for `UIMessage[]` state.
-- On `approval-requested` custom event:
+- On `RUN_FINISHED.outcome.type === 'interrupt'`:
+  1. Persists/surfaces each interrupt as a pending user-actionable wait.
+  2. Calls `updateToolCallApproval()` for approval-shaped interrupts so legacy
+     approval UI renders as before.
+- On legacy `approval-requested` custom event:
   1. Calls `updateToolCallApproval()` to set the tool-call part's state to
      `approval-requested` and attach approval metadata.
   2. Fires `onApprovalRequest` so the ChatClient can emit devtools events.
@@ -192,24 +206,31 @@ Step-by-step flow for a single tool requiring approval:
 TOOL_CALL_START   { toolCallId: "tc-1", toolName: "send_email" }
 TOOL_CALL_ARGS    { toolCallId: "tc-1", delta: '{"to":"..."}' }
 TOOL_CALL_END     { toolCallId: "tc-1" }
-CUSTOM            { name: "approval-requested", value: {
-                      toolCallId: "tc-1",
-                      toolName: "send_email",
-                      input: { to: "..." },
-                      approval: { id: "appr-1", needsApproval: true }
+RUN_FINISHED      { outcome: {
+                      type: "interrupt",
+                      interrupts: [{
+                        id: "appr-1",
+                        reason: "approval_required",
+                        metadata: {
+                          kind: "approval",
+                          toolCallId: "tc-1",
+                          toolName: "send_email",
+                          input: { to: "..." }
+                        }
+                      }]
                   }}
-RUN_FINISHED      { finishReason: "tool_calls" }
 ```
 
-### 2. StreamProcessor processes the CUSTOM chunk
+### 2. StreamProcessor processes the interrupt outcome
 
 ```
-handleCustomEvent():
+handleRunFinished():
   1. updateToolCallApproval(messages, messageId, "tc-1", "appr-1")
      → Sets part.state = "approval-requested"
      → Sets part.approval = { id: "appr-1", needsApproval: true }
-  2. emitMessagesChange()
-  3. fires onApprovalRequest({ toolCallId, toolName, input, approvalId })
+  2. records the pending interrupt on the client
+  3. emitMessagesChange()
+  4. fires onApprovalRequest({ toolCallId, toolName, input, approvalId })
 ```
 
 ### 3. Stream ends, ChatClient processes
@@ -233,7 +254,9 @@ addToolApprovalResponse({ id: "appr-1", approved: true }):
      → updateToolCallApprovalResponse():
        part.approval.approved = true
        part.state = "approval-responded"
-  2. isLoading is false → call checkForContinuation() directly
+  2. queue a resume entry:
+     { interruptId: "appr-1", status: "resolved", payload: { approved: true } }
+  3. isLoading is false → call checkForContinuation() directly
 ```
 
 ### 5. Continuation
@@ -244,8 +267,9 @@ checkForContinuation():
   2. shouldAutoSend() → areAllToolsComplete():
      part.state === "approval-responded" → true
   3. continuationPending = true
-  4. streamResponse() → new stream to server with approval in messages
-  5. Server sees approval, executes tool, returns result + LLM response
+  4. streamResponse() → new stream to server with `resume[]`
+  5. Persistence validates `resume[]`, resolves the pending interrupt, then the
+     server executes or cancels the tool and returns result + LLM response
   6. continuationPending = false
 ```
 
@@ -388,11 +412,52 @@ Timeline (with fix):
 
 ### Approval-related AG-UI events
 
-These are `CUSTOM` events emitted by the TextEngine, not by adapters directly.
+The primary wait event is `RUN_FINISHED` with an interrupt outcome:
+
+```typescript ignore
+{
+  type: 'RUN_FINISHED',
+  outcome: {
+    type: 'interrupt',
+    interrupts: [
+      {
+        id: string,
+        reason: 'approval_required',
+        metadata: {
+          kind: 'approval',
+          toolCallId: string,
+          toolName: string,
+          input: unknown
+        }
+      }
+    ]
+  }
+}
+```
+
+Resume uses AG-UI `RunAgentInput.resume[]` on the next request:
+
+```typescript ignore
+{
+  resume: [
+    {
+      interruptId: 'appr-1',
+      status: 'resolved',
+      payload: { approved: true }
+    }
+  ]
+}
+```
+
+Pending user-actionable interrupts block normal input on the same thread by
+default. A stale cursor replay may read the public event tail, but a new
+non-resume input must resolve the pending interrupts first.
 
 #### `approval-requested`
 
-Emitted when a tool with `needsApproval: true` has its arguments finalized.
+Legacy compatibility/projection event emitted when a tool with
+`needsApproval: true` has its arguments finalized. Use this to keep older UI
+rendering paths working; do not use it as the primary durable wait signal.
 
 ```typescript ignore
 {
@@ -422,13 +487,15 @@ TOOL_CALL_START     → creates tool-call part (state: awaiting-input)
 TOOL_CALL_ARGS*     → accumulates arguments (state: input-streaming)
 TOOL_CALL_END       → finalizes arguments (state: input-complete)
 CUSTOM              → approval-requested (state: approval-requested)
-RUN_FINISHED        → finishReason: "tool_calls"
+RUN_FINISHED        → outcome.type: "interrupt"
 ```
 
 After the stream ends and the user responds, the ChatClient:
 1. Updates the tool-call part (state: `approval-responded`)
-2. Sends a new stream request with the full conversation (including approval)
-3. The server sees the approval and either executes or cancels the tool
+2. Sends a new stream request with `RunAgentInput.resume[]` entries resolving
+   the pending interrupt
+3. Persistence validates the resume entries, resolves the interrupt, and the
+   server executes or cancels the tool based on the resume payload
 
 ---
 
diff --git a/docs/chat/connection-adapters.md b/docs/chat/connection-adapters.md
index a67e17e6f..3bd48d452 100644
--- a/docs/chat/connection-adapters.md
+++ b/docs/chat/connection-adapters.md
@@ -73,7 +73,7 @@ import { useChat, fetchServerSentEvents } from "@tanstack/ai-react";
 
 const { messages } = useChat({
   connection: fetchServerSentEvents("/api/chat", {
-    body: { provider: "openai", model: "gpt-5.1" },
+    body: { provider: "openai", model: "gpt-5.5" },
   }),
 });
 ```
@@ -178,7 +178,7 @@ import { chatServerFn } from "./server/chat.server";
 
 // `chatServerFn` is an in-process server-side function that synchronously
 // returns an AsyncIterable<StreamChunk> — e.g. the result of
-// `chat({ adapter, model, messages })` on the server.
+// `chat({ adapter: openaiText("gpt-5.5"), messages })` on the server.
 const { messages } = useChat({
   connection: stream((messages, data) => chatServerFn({ messages, ...data })),
 });
@@ -197,13 +197,28 @@ When you call into your server with an **async** function — the universal case
 import { createServerFn } from "@tanstack/react-start";
 import { chat, toServerSentEventsResponse } from "@tanstack/ai";
 import { openaiText } from "@tanstack/ai-openai";
-import type { UIMessage } from "@tanstack/ai";
+import type { RunAgentResumeItem, UIMessage } from "@tanstack/ai";
+
+type ChatFnInput = {
+  messages: Array<UIMessage>;
+  threadId?: string;
+  runId?: string;
+  cursor?: string;
+  resume?: Array<RunAgentResumeItem>;
+};
 
 export const chatFn = createServerFn({ method: "POST" })
-  .inputValidator((data: { messages: Array<UIMessage> }) => data)
+  .inputValidator((data: ChatFnInput) => data)
   .handler(({ data }) =>
     toServerSentEventsResponse(
-      chat({ adapter: openaiText("gpt-5.1"), messages: data.messages }),
+      chat({
+        adapter: openaiText("gpt-5.5"),
+        messages: data.messages,
+        threadId: data.threadId,
+        runId: data.runId,
+        cursor: data.cursor,
+        resume: data.resume,
+      }),
     ),
   );
 ```
@@ -213,11 +228,14 @@ import { useChat } from "@tanstack/ai-react";
 import { chatFn } from "./server/chat.server";
 
 const { messages, sendMessage } = useChat({
-  fetcher: ({ messages }, { signal }) => chatFn({ data: { messages }, signal }),
+  fetcher: (input, { signal }) => chatFn({ data: input, signal }),
 });
 ```
 
-The fetcher receives `{ messages, data, threadId, runId }` plus an `AbortSignal` (triggered by `stop()` or when a send is superseded). Return a `Response` — whose SSE body the chat client parses for you — **or** an `AsyncIterable<StreamChunk>`, which is yielded directly. If your server function returns the stream itself (instead of wrapping it in a `Response`), the fetcher handles that too. Sync and `Promise`-wrapped returns are both accepted.
+The fetcher receives `{ messages, data, threadId, runId, cursor, resume }` plus an `AbortSignal` (triggered by `stop()` or when a send is superseded). Forward `cursor` when replaying persisted public events, and forward `resume` when responding to pending AG-UI interrupts. Return a `Response` — whose SSE body the chat client parses for you — **or** an `AsyncIterable<StreamChunk>`, which is yielded directly. If your server function returns the stream itself (instead of wrapping it in a `Response`), the fetcher handles that too. Sync and `Promise`-wrapped returns are both accepted.
+
+For the server persistence path that produces those replay cursors, see
+[Chat Persistence](../persistence/chat-persistence).
 
 > **Tip:** The choice between `fetcher` and [`stream()`](#server-functions-and-direct-async-iterables) is about **async vs sync**, not `Response`-vs-iterable — both can yield an `AsyncIterable<StreamChunk>`. `stream()`'s factory must return that iterable **synchronously**, so a server-function call (which returns a `Promise`) won't typecheck there — that's the gap `fetcher` fills ([issue #509](https://github.com/TanStack/ai/issues/509)). Use `stream()` when you can hand back an async iterable synchronously (in-process `chat()`, an RPC client, tests); use `fetcher` for anything you have to `await`. Both normalize to the same request-scoped adapter, so `stop()`/abort, error handling, and tool calls behave identically.
 
@@ -315,6 +333,7 @@ function websocketConnection(url: string): SubscribeConnectionAdapter {
         JSON.stringify({
           threadId: runContext?.threadId,
           runId: runContext?.runId,
+          resume: runContext?.resume,
           messages,
           data,
         }),
@@ -382,6 +401,7 @@ const myAdapter: ConnectConnectionAdapter = {
       body: JSON.stringify({
         threadId: runContext?.threadId,
         runId: runContext?.runId,
+        resume: runContext?.resume,
         messages,
         ...data,
       }),
@@ -415,7 +435,11 @@ const myAdapter: ConnectConnectionAdapter = {
 const { messages } = useChat({ connection: myAdapter });
 ```
 
-`runContext` carries `threadId`, `runId`, `clientTools`, and `forwardedProps`. Include them in your request payload so the server can build an AG-UI-compliant response. If your `connect` stream completes without emitting `RUN_FINISHED`, the runtime synthesizes one for you; if it throws, a `RUN_ERROR` is synthesized.
+`runContext` carries `threadId`, `runId`, `cursor`, `resume`, `clientTools`, and `forwardedProps`. Include them in your request payload so the server can build an AG-UI-compliant response, replay from `{ threadId, runId, cursor }`, and validate `RunAgentInput.resume[]` for pending interrupts. If your `connect` stream completes without emitting `RUN_FINISHED`, the runtime synthesizes one for you; if it throws, a `RUN_ERROR` is synthesized.
+
+If the request-scoped adapter talks to a persisted `chat()` endpoint, those
+fields are the durable replay identity described in
+[Chat Persistence](../persistence/chat-persistence).
 
 ## The Adapter Interface
 
@@ -423,12 +447,14 @@ A `ConnectionAdapter` is a union — provide **either** `connect`, **or** both `
 
 ```typescript
 import type { UIMessage } from "@tanstack/ai-client";
-import type { ModelMessage, StreamChunk } from "@tanstack/ai";
+import type { ModelMessage, RunAgentResumeItem, StreamChunk } from "@tanstack/ai";
 
 export interface RunAgentInputContext {
   threadId: string;
   runId: string;
   parentRunId?: string;
+  cursor?: string;
+  resume?: Array<RunAgentResumeItem>;
   clientTools?: Array<{ name: string; description: string; parameters: unknown }>;
   forwardedProps?: Record<string, unknown>;
 }
diff --git a/docs/chat/persistence.md b/docs/chat/persistence.md
index 985c8aa2d..35d52582f 100644
--- a/docs/chat/persistence.md
+++ b/docs/chat/persistence.md
@@ -17,6 +17,11 @@ By default a `ChatClient` (and every framework `useChat`/`createChat` wrapper) k
 
 This is especially useful for SPAs, Electron apps, and offline-first setups where the client is the source of truth and there's no server managing conversation state.
 
+If your server owns the transcript and you need durable event replay after a
+reconnect or reload, use server-side persistence instead. See
+[Chat Persistence](../persistence/chat-persistence) for the full
+`withChatPersistence` server/client wiring.
+
 ## The adapter interface
 
 A persistence adapter is any object with three methods — the same `getItem`/`setItem`/`removeItem` shape used elsewhere in TanStack AI. Each method may be synchronous or return a `Promise`:
@@ -46,19 +51,21 @@ import { adapter, myPersistenceAdapter } from "./chat-setup";
 const client = new ChatClient({
   id: "conversation-123",
   connection: adapter,
-  persistence: myPersistenceAdapter,
+  persistence: {
+    client: myPersistenceAdapter,
+  },
 });
 ```
 
 ## What the client does for you
 
-When a `persistence` adapter is provided, `ChatClient`:
+When a `persistence.client` adapter is provided, `ChatClient`:
 
 - **Hydrates on construction** — calls `getItem(id)`. If it returns an array, those messages populate the client (overriding `initialMessages`). Async adapters hydrate as soon as the promise resolves, unless you've already started a new conversation in the meantime.
 - **Saves on every change** — calls `setItem(id, messages)` whenever the message list changes (new user message, streamed assistant content, tool calls/results, approval responses). Writes are queued so they never overlap or land out of order.
 - **Clears on `clear()`** — calls `removeItem(id)` and discards any in-flight stream so a cleared conversation doesn't get repopulated by late chunks.
 
-When `persistence` is omitted, nothing changes — the client behaves exactly as before. The option is fully backwards compatible.
+When `persistence` is omitted, nothing changes — the client behaves exactly as before. Passing a message adapter directly as `persistence: adapter` remains supported for compatibility, but it is deprecated. Use `persistence: { client: adapter }` in new code.
 
 Persistence is **best-effort**: if an adapter method throws or rejects, the error is swallowed so storage problems never break the chat. Handle and surface errors inside your adapter if you need to react to them.
 
@@ -74,7 +81,9 @@ import { myPersistenceAdapter } from "./persistence";
 const chat = useChat({
   id: "conversation-123",
   connection: fetchServerSentEvents("/api/chat"),
-  persistence: myPersistenceAdapter,
+  persistence: {
+    client: myPersistenceAdapter,
+  },
 });
 ```
 
@@ -86,7 +95,9 @@ import { myPersistenceAdapter } from "./persistence";
 const chat = useChat({
   id: "conversation-123",
   connection: fetchServerSentEvents("/api/chat"),
-  persistence: myPersistenceAdapter,
+  persistence: {
+    client: myPersistenceAdapter,
+  },
 });
 ```
 
@@ -95,7 +106,9 @@ const chat = useChat({
 const chat = createChat({
   id: "conversation-123",
   connection: fetchServerSentEvents("/api/chat"),
-  persistence: myPersistenceAdapter,
+  persistence: {
+    client: myPersistenceAdapter,
+  },
 });
 ```
 
diff --git a/docs/config.json b/docs/config.json
index 99dd073b9..a3560bbe7 100644
--- a/docs/config.json
+++ b/docs/config.json
@@ -104,7 +104,8 @@
         {
           "label": "Tool Approval Flow",
           "to": "tools/tool-approval",
-          "addedAt": "2026-04-15"
+          "addedAt": "2026-04-15",
+          "updatedAt": "2026-07-09"
         },
         {
           "label": "Lazy Tool Discovery",
@@ -141,7 +142,7 @@
           "label": "MCP Apps",
           "to": "mcp/apps",
           "addedAt": "2026-06-24",
-          "updatedAt": "2026-06-26"
+          "updatedAt": "2026-07-03"
         }
       ]
     },
@@ -162,7 +163,8 @@
         {
           "label": "Connection Adapters",
           "to": "chat/connection-adapters",
-          "addedAt": "2026-04-15"
+          "addedAt": "2026-04-15",
+          "updatedAt": "2026-07-03"
         },
         {
           "label": "Thinking & Reasoning",
@@ -172,7 +174,8 @@
         {
           "label": "Persistence",
           "to": "chat/persistence",
-          "addedAt": "2026-06-02"
+          "addedAt": "2026-06-02",
+          "updatedAt": "2026-07-09"
         }
       ]
     },
@@ -299,7 +302,8 @@
         {
           "label": "Generation Hooks",
           "to": "media/generation-hooks",
-          "addedAt": "2026-04-15"
+          "addedAt": "2026-04-15",
+          "updatedAt": "2026-07-09"
         }
       ]
     },
@@ -332,7 +336,7 @@
           "label": "Overview",
           "to": "sandbox/overview",
           "addedAt": "2026-06-16",
-          "updatedAt": "2026-06-30"
+          "updatedAt": "2026-07-03"
         },
         {
           "label": "Quick Start",
@@ -374,7 +378,8 @@
         {
           "label": "Lifecycle & Snapshots",
           "to": "sandbox/lifecycle",
-          "addedAt": "2026-06-29"
+          "addedAt": "2026-06-29",
+          "updatedAt": "2026-07-09"
         },
         {
           "label": "Events",
@@ -395,6 +400,94 @@
         }
       ]
     },
+    {
+      "label": "Persistence",
+      "children": [
+        {
+          "label": "Overview",
+          "to": "persistence/overview",
+          "addedAt": "2026-06-18",
+          "updatedAt": "2026-07-09"
+        },
+        {
+          "label": "Delivery Durability",
+          "to": "persistence/delivery-durability",
+          "addedAt": "2026-07-09"
+        },
+        {
+          "label": "Persistence Controls",
+          "to": "persistence/controls",
+          "addedAt": "2026-07-08",
+          "updatedAt": "2026-07-09"
+        },
+        {
+          "label": "Migrations",
+          "to": "persistence/migrations",
+          "addedAt": "2026-07-08",
+          "updatedAt": "2026-07-09"
+        },
+        {
+          "label": "Chat Persistence",
+          "to": "persistence/chat-persistence",
+          "addedAt": "2026-07-03",
+          "updatedAt": "2026-07-09"
+        },
+        {
+          "label": "Sandbox Persistence",
+          "to": "persistence/sandbox-persistence",
+          "addedAt": "2026-07-03",
+          "updatedAt": "2026-07-09"
+        },
+        {
+          "label": "Generation Persistence",
+          "to": "persistence/generation-persistence",
+          "addedAt": "2026-07-07",
+          "updatedAt": "2026-07-09"
+        },
+        {
+          "label": "MCP Persistence",
+          "to": "persistence/mcp-persistence",
+          "addedAt": "2026-07-08",
+          "updatedAt": "2026-07-09"
+        },
+        {
+          "label": "Cloudflare",
+          "to": "persistence/cloudflare",
+          "addedAt": "2026-07-03",
+          "updatedAt": "2026-07-09"
+        },
+        {
+          "label": "Prisma",
+          "to": "persistence/prisma",
+          "addedAt": "2026-07-08",
+          "updatedAt": "2026-07-09"
+        },
+        {
+          "label": "Drizzle",
+          "to": "persistence/drizzle",
+          "addedAt": "2026-07-08",
+          "updatedAt": "2026-07-09"
+        },
+        {
+          "label": "SQL Backends",
+          "to": "persistence/sql-backends",
+          "addedAt": "2026-07-03",
+          "updatedAt": "2026-07-09"
+        },
+        {
+          "label": "Custom Stores",
+          "to": "persistence/custom-stores",
+          "addedAt": "2026-07-03",
+          "updatedAt": "2026-07-09"
+        },
+        {
+          "label": "Persistence Internals",
+          "to": "persistence/internals",
+          "addedAt": "2026-07-08",
+          "updatedAt": "2026-07-09"
+        }
+      ]
+    },
     {
       "label": "Advanced",
       "children": [
@@ -459,7 +552,7 @@
           "addedAt": "2026-05-16"
         },
         {
-          "label": "Sampling → modelOptions",
+          "label": "Sampling \u2192 modelOptions",
           "to": "migration/sampling-options-to-model-options",
           "addedAt": "2026-06-03"
         }
@@ -481,12 +574,14 @@
         {
           "label": "@tanstack/ai-react",
           "to": "api/ai-react",
-          "addedAt": "2026-04-15"
+          "addedAt": "2026-04-15",
+          "updatedAt": "2026-07-07"
         },
         {
           "label": "@tanstack/ai-solid",
           "to": "api/ai-solid",
-          "addedAt": "2026-04-15"
+          "addedAt": "2026-04-15",
+          "updatedAt": "2026-07-07"
         },
         {
           "label": "@tanstack/ai-preact",
@@ -496,17 +591,20 @@
         {
           "label": "@tanstack/ai-vue",
           "to": "api/ai-vue",
-          "addedAt": "2026-04-15"
+          "addedAt": "2026-04-15",
+          "updatedAt": "2026-07-07"
         },
         {
           "label": "@tanstack/ai-svelte",
           "to": "api/ai-svelte",
-          "addedAt": "2026-04-15"
+          "addedAt": "2026-04-15",
+          "updatedAt": "2026-07-07"
         },
         {
           "label": "@tanstack/ai-angular",
           "to": "api/ai-angular",
-          "addedAt": "2026-06-15"
+          "addedAt": "2026-06-15",
+          "updatedAt": "2026-07-07"
         }
       ]
     },
diff --git a/docs/mcp/apps.md b/docs/mcp/apps.md
index 80ea623b0..46496cc2b 100644
--- a/docs/mcp/apps.md
+++ b/docs/mcp/apps.md
@@ -365,6 +365,10 @@ const handler = createMcpAppCallHandler({ clients: mcp, store })
 
 > **Current limitation:** `inMemoryMcpSessionStore` is single-instance (one Node.js process). It does not survive serverless restarts or scale across replicas. The `McpSessionStore` interface is the persistence extension point — persistent backends (database, KV store) can be dropped in without any API changes.
 
+For broader app-owned persistence primitives such as metadata, public replay
+events, internal checkpoints, and custom SQL/KV stores, see
+[Custom Stores](../persistence/custom-stores).
+
 ## API Reference
 
 ### `createMcpAppCallHandler` (`@tanstack/ai-mcp/apps`)
diff --git a/docs/media/generation-hooks.md b/docs/media/generation-hooks.md
index 69cb7b7c9..d6e5e954c 100644
--- a/docs/media/generation-hooks.md
+++ b/docs/media/generation-hooks.md
@@ -33,7 +33,7 @@ Generation hooks share a consistent API across all media types:
 | `useGenerateVideo` | `VideoGenerateInput` | `VideoGenerateResult` |
 | `useGeneration` | Generic `TInput` | Generic `TResult` |
 
-Every hook returns the same core shape: `generate`, `result`, `isLoading`, `error`, `status`, `stop`, and `reset`. You provide either a `connection` (streaming transport) or a `fetcher` (direct async call).
+Every hook returns the same core shape: `generate`, `result`, `isLoading`, `error`, `status`, `stop`, and `reset`. Streaming hooks also expose a read-only generation state snapshot (`resumeSnapshot`, `resumeState`, `pendingArtifacts`, `resultArtifacts`) for observability and rendering persisted artifact refs. You provide either a `connection` (streaming transport) or a `fetcher` (direct async call).
 
 ## Server Setup
 
@@ -61,6 +61,11 @@ export async function POST(req: Request) {
 
 The same pattern applies to all generation types -- swap `generateImage` for `generateSpeech`, `generateTranscription`, `summarize`, or `generateVideo`. See the individual media guides for server-side details.
 
+For refresh-safe generation, wrap the server call with `withGenerationPersistence(...)`
+and parse hook requests with `generationParamsFromRequest(...)`. See
+[Generation Persistence](../persistence/generation-persistence) for the complete
+server and client flow.
+
 ## useGenerateImage
 
 Trigger image generation and render the results.
@@ -181,7 +186,10 @@ function Transcriber() {
     if (file) {
       const reader = new FileReader()
       reader.onload = () => {
-        generate({ audio: reader.result as string, language: 'en' })
+        const audio = reader.result
+        if (typeof audio === 'string') {
+          generate({ audio, language: 'en' })
+        }
       }
       reader.readAsDataURL(file)
     }
@@ -391,6 +399,8 @@ function EmbeddingGenerator() {
 | `fetcher` | `GenerationFetcher<TInput, TResult>` | Direct async function (no streaming protocol needed) |
 | `id` | `string` | Unique identifier for this generation instance |
 | `body` | `Record<string, any>` | Additional body parameters sent with connection requests |
+| `persistence` | `{ server?: GenerationServerPersistence }` | Stores the lightweight generation state snapshot. Generated media bytes are not stored in browser persistence. |
+| `initialResumeSnapshot` | `GenerationResumeSnapshot` | Initial lightweight snapshot restored by the app or a persistence adapter, surfaced as read-only state. |
 | `onResult` | `(result: TResult) => TOutput \| null \| void` | Transform or react to results |
 | `onError` | `(error: Error) => void` | Error callback |
 | `onProgress` | `(progress: number, message?: string) => void` | Progress updates (0-100) |
@@ -409,6 +419,20 @@ function EmbeddingGenerator() {
 | `status` | `GenerationClientState` | `'idle'` \| `'generating'` \| `'success'` \| `'error'` |
 | `stop` | `() => void` | Abort the current generation |
 | `reset` | `() => void` | Clear result, error, and return to idle |
+| `resumeSnapshot` | `GenerationResumeSnapshot \| undefined` | Read-only lightweight snapshot containing run/cursor metadata, status, errors, and artifact refs |
+| `resumeState` | `GenerationResumeState \| null` | Observed `{ threadId, runId }` metadata from the snapshot, or `null` (read-only) |
+| `pendingArtifacts` | `Array<GenerationPendingArtifact>` | Persisted artifact refs observed during generation or replay before completion |
+| `resultArtifacts` | `Array<PersistedArtifactRef>` | Persisted artifact refs attached to the final replayed result |
+
+`stop()` aborts only the current client connection. It does not durably cancel
+server-side generation work or delete persisted run state.
+
+Generation hooks do not store generated image, audio, speech, transcription, or
+video bytes in browser persistence. The client snapshot keeps only
+`{ threadId, runId, cursor }` plus lightweight artifact refs. Use server
+persistence artifacts when generated media must survive refresh:
+[Generation Persistence](../persistence/generation-persistence) shows the full
+pattern.
 
 ### Result Transforms
 
@@ -425,24 +449,82 @@ const { result } = useGenerateImage({
 // result is now string[] instead of ImageGenerationResult
 ```
 
+## Generation State Snapshot
+
+Generation hooks do **not** auto-resume or expose a `resume()` action. A
+generation run is only started by an explicit `generate(...)` call — hooks never
+re-launch a run on mount. What the hooks _do_ surface, when the server uses
+`withGenerationPersistence(...)` and returns SSE events, is a **read-only**
+snapshot of the latest observed run for observability and for rendering
+persisted artifact refs.
+
+Add `persistence.server` to store the latest snapshot under a stable `id`, or
+pass `initialResumeSnapshot` to hydrate it from your own store. The hook then
+reflects `resumeSnapshot`, `resumeState`, `pendingArtifacts`, and
+`resultArtifacts` as read-only values.
+
+```tsx
+import { localStorageAIPersistence } from '@tanstack/ai-client'
+import { fetchServerSentEvents, useGenerateVideo } from '@tanstack/ai-react'
+
+export function TrailerVideoGenerator() {
+  const video = useGenerateVideo({
+    id: 'trailer-video',
+    connection: fetchServerSentEvents('/api/generate/video'),
+    persistence: {
+      server: localStorageAIPersistence({
+        keyPrefix: 'tanstack-ai:generation-state:',
+      }),
+    },
+  })
+
+  return (
+    <div>
+      <button disabled={video.isLoading} onClick={() => video.generate({ prompt: 'A city flyover' })}>
+        Generate
+      </button>
+      {video.resumeState && <p>Last run: {video.resumeState.runId}</p>}
+      {video.pendingArtifacts.map((artifact) => (
+        <a key={artifact.artifactId} href={`/api/artifacts/${artifact.artifactId}`}>
+          {artifact.name}
+        </a>
+      ))}
+    </div>
+  )
+}
+```
+
+The snapshot lets you render persisted artifact refs and observe run status
+after a reload, but it does not reconnect to or replay a server run. Generated
+bytes live in server-side artifact/blob stores. See
+[Generation Persistence](../persistence/generation-persistence) for serving
+those durable bytes.
+
 ## Framework Variants
 
-All generation hooks are available across React, Vue, and Svelte with the same capabilities. The API shapes are identical -- only the naming convention and reactive primitives differ.
+Generation hooks are available across React, Vue, Svelte, Solid, and Angular with the same capabilities. Preact currently exposes chat hooks only, not generation hooks. The API shapes are identical -- only the naming convention and reactive primitives differ.
+
+| Generation Type | React | Vue | Svelte | Solid | Angular |
+|----------------|-------|-----|--------|-------|---------|
+| Image | `useGenerateImage` | `useGenerateImage` | `createGenerateImage` | `useGenerateImage` | `injectGenerateImage` |
+| Audio | `useGenerateAudio` | `useGenerateAudio` | `createGenerateAudio` | `useGenerateAudio` | `injectGenerateAudio` |
+| Speech | `useGenerateSpeech` | `useGenerateSpeech` | `createGenerateSpeech` | `useGenerateSpeech` | `injectGenerateSpeech` |
+| Transcription | `useTranscription` | `useTranscription` | `createTranscription` | `useTranscription` | `injectTranscription` |
+| Summarization | `useSummarize` | `useSummarize` | `createSummarize` | `useSummarize` | `injectSummarize` |
+| Video | `useGenerateVideo` | `useGenerateVideo` | `createGenerateVideo` | `useGenerateVideo` | `injectGenerateVideo` |
+| Base (generic) | `useGeneration` | `useGeneration` | `createGeneration` | `useGeneration` | `injectGeneration` |
 
-| Generation Type | React (`@tanstack/ai-react`) | Vue (`@tanstack/ai-vue`) | Svelte (`@tanstack/ai-svelte`) |
-|----------------|------------------------------|--------------------------|-------------------------------|
-| Image | `useGenerateImage` | `useGenerateImage` | `createGenerateImage` |
-| Speech | `useGenerateSpeech` | `useGenerateSpeech` | `createGenerateSpeech` |
-| Transcription | `useTranscription` | `useTranscription` | `createTranscription` |
-| Summarization | `useSummarize` | `useSummarize` | `createSummarize` |
-| Video | `useGenerateVideo` | `useGenerateVideo` | `createGenerateVideo` |
-| Base (generic) | `useGeneration` | `useGeneration` | `createGeneration` |
+All framework packages re-export `fetchServerSentEvents`, `fetchHttpStream`, and `stream` from `@tanstack/ai-client` for convenience.
 
-All three packages re-export `fetchServerSentEvents`, `fetchHttpStream`, and `stream` from `@tanstack/ai-client` for convenience.
+**React note:** Return values are plain values/functions. `resumeState` is a value and `pendingArtifacts` / `resultArtifacts` are arrays.
 
 **Vue note:** Return values are wrapped in `DeepReadonly<ShallowRef<>>` -- access them with `.value` in both `<script>` and `<template>`.
 
-**Svelte note:** Functions use the `create*` naming convention and return Svelte 5 reactive state via `$state`.
+**Svelte note:** Functions use the `create*` naming convention and return Svelte 5 reactive getters. Call `dispose()` or `stop()` during cleanup when needed.
+
+**Solid note:** Reactive return values are accessors. Read `resumeState()` and `pendingArtifacts()`.
+
+**Angular note:** Injectables return read-only Angular `Signal`s. Read `resumeState()` and `pendingArtifacts()` from the injected result.
 
 ## Next Steps
 
@@ -451,3 +533,4 @@ All three packages re-export `fetchServerSentEvents`, `fetchHttpStream`, and `st
 - [Transcription](./transcription) -- File formats, language detection, and word-level timestamps
 - [Video Generation](./video-generation) -- Job lifecycle, polling, and provider setup
 - [Generations Overview](./generations) -- Architecture and server-side streaming patterns
+- [Generation Persistence](../persistence/generation-persistence) -- Refresh-safe generation and persisted artifact refs
diff --git a/docs/media/transcription.md b/docs/media/transcription.md
index bd92c633a..325e62301 100644
--- a/docs/media/transcription.md
+++ b/docs/media/transcription.md
@@ -2,7 +2,7 @@
 title: Transcription
 id: transcription
 order: 4
-description: "Transcribe audio to text with OpenAI Whisper and GPT-4o transcription models (including speaker diarization), Groq Whisper, and fal.ai STT models via TanStack AI's generateTranscription() API."
+description: "Transcribe audio to text with OpenAI Whisper and current transcription models, Groq Whisper, and fal.ai STT models via TanStack AI's generateTranscription() API."
 keywords:
   - tanstack ai
   - transcription
@@ -17,14 +17,14 @@ keywords:
 
 # Audio Transcription
 
-TanStack AI provides support for audio transcription (speech-to-text) through dedicated transcription adapters. This guide covers how to convert spoken audio into text using OpenAI's Whisper and GPT-4o transcription models, Groq's hosted Whisper models, and fal.ai STT models.
+TanStack AI provides support for audio transcription (speech-to-text) through dedicated transcription adapters. This guide covers how to convert spoken audio into text using OpenAI's Whisper and current transcription models, Groq's hosted Whisper models, and fal.ai STT models.
 
 ## Overview
 
 Audio transcription is handled by transcription adapters that follow the same tree-shakeable architecture as other adapters in TanStack AI.
 
 Currently supported:
-- **OpenAI**: Whisper-1, GPT-4o-transcribe, GPT-4o-mini-transcribe, GPT-4o-transcribe-diarize
+- **OpenAI**: Whisper-1 and current OpenAI transcription and diarization models
 - **Groq**: whisper-large-v3-turbo, whisper-large-v3
 - **fal.ai**: Whisper, Wizper, speech-to-text turbo, ElevenLabs speech-to-text
 
@@ -139,7 +139,7 @@ for (const segment of result.segments ?? []) {
 |--------|------|-------------|
 | `audio` | `File \| string` | Audio data (File object or base64 string) - required |
 | `language` | `string` | Language code (e.g., "en", "es", "fr") |
-| `prompt` | `string` | Optional prompt to guide transcription style or terms. Not supported with `gpt-4o-transcribe-diarize`. |
+| `prompt` | `string` | Optional prompt to guide transcription style or terms. Not supported with OpenAI diarization models. |
 | `responseFormat` | `'json' \| 'text' \| 'srt' \| 'verbose_json' \| 'vtt'` | Common output format |
 
 ### Supported Languages
@@ -188,7 +188,7 @@ const result = await generateTranscription({
 | `timestamp_granularities` | `Array<'word' \| 'segment'>` | Timestamp granularity to populate (`whisper-1` only; requires top-level `responseFormat: 'verbose_json'`) |
 | `include` | `string[]` | Additional values to include in the response (e.g., `logprobs`) |
 | `response_format` | `'json' \| 'text' \| 'srt' \| 'verbose_json' \| 'vtt' \| 'diarized_json'` | Raw OpenAI response format. Use `diarized_json` here for speaker-labeled diarization output. |
-| `chunking_strategy` | `'auto' \| { type: 'server_vad', ... } \| null` | Audio chunking strategy (any model; unset transcribes the audio as a single block). Required by OpenAI for `gpt-4o-transcribe-diarize` inputs longer than 30 seconds — the adapter defaults it to `'auto'` for that model |
+| `chunking_strategy` | `'auto' \| { type: 'server_vad', ... } \| null` | Audio chunking strategy (any model; unset transcribes the audio as a single block). Required by OpenAI for long diarization inputs — the adapter defaults it to `'auto'` for supported diarization models |
 | `known_speaker_names` | `string[]` | Up to four speaker labels for diarization |
 | `known_speaker_references` | `string[]` | 2-10 second data URL audio samples matching `known_speaker_names` |
 
@@ -204,19 +204,34 @@ const result = await generateTranscription({
 | `verbose_json` | Detailed JSON with timestamps and segments |
 | `vtt` | WebVTT subtitle format |
 
-OpenAI's `gpt-4o-transcribe-diarize` also supports `modelOptions.response_format: 'diarized_json'` for speaker-labeled segments.
+OpenAI diarization-capable transcription models also support `modelOptions.response_format: 'diarized_json'` for speaker-labeled segments.
 
 ### Speaker Diarization
 
-Use `gpt-4o-transcribe-diarize` when you need speaker labels. When no response format is specified, TanStack AI defaults the request to `response_format: 'diarized_json'` and sends `chunking_strategy: 'auto'` unless you provide a chunking strategy yourself. Passing a top-level `responseFormat: 'json'` or `'text'` opts out of speaker segments.
+Use an OpenAI diarization-capable transcription model when you need speaker labels. When no response format is specified, TanStack AI defaults the request to `response_format: 'diarized_json'` and sends `chunking_strategy: 'auto'` unless you provide a chunking strategy yourself. Passing a top-level `responseFormat: 'json'` or `'text'` opts out of speaker segments.
 
 ```typescript
 import { generateTranscription } from '@tanstack/ai'
 import { openaiTranscription } from '@tanstack/ai-openai'
 import { meetingAudioFile } from './audio'
 
+const diarizationModel = process.env.OPENAI_DIARIZATION_TRANSCRIPTION_MODEL
+
+function isDiarizationTranscriptionModel(
+  model: string,
+): model is Parameters<typeof openaiTranscription>[0] {
+  return model.endsWith('-diarize')
+}
+
+if (
+  !diarizationModel ||
+  !isDiarizationTranscriptionModel(diarizationModel)
+) {
+  throw new Error('Set OPENAI_DIARIZATION_TRANSCRIPTION_MODEL to a diarization model')
+}
+
 const result = await generateTranscription({
-  adapter: openaiTranscription('gpt-4o-transcribe-diarize'),
+  adapter: openaiTranscription(diarizationModel),
   audio: meetingAudioFile,
   modelOptions: {
     known_speaker_names: ['agent', 'customer'],
@@ -312,9 +327,7 @@ await transcribeAudio('./meeting-recording.mp3')
 | Model | Description | Use Case |
 |-------|-------------|----------|
 | `whisper-1` | Whisper large-v2 | General transcription |
-| `gpt-4o-transcribe` | GPT-4o-based transcription | Higher accuracy |
-| `gpt-4o-transcribe-diarize` | With speaker diarization | Multi-speaker audio |
-| `gpt-4o-mini-transcribe` | Faster, lighter model | Cost-effective |
+| Current OpenAI transcription models | Latest dedicated speech-to-text models | Higher accuracy and model-specific capabilities |
 
 ### Supported Audio Formats
 
@@ -630,4 +643,4 @@ const adapter = createOpenaiTranscription('whisper-1', 'your-openai-api-key')
 
 6. **Timestamps**: Request `responseFormat: 'verbose_json'` and set `modelOptions.timestamp_granularities` when you need timing information for captions or synchronization.
 
-7. **Diarization**: Use `gpt-4o-transcribe-diarize` with `modelOptions.response_format: 'diarized_json'` output for multi-speaker audio. Keep `chunking_strategy: 'auto'` unless you need custom VAD tuning.
+7. **Diarization**: Use an OpenAI diarization-capable transcription model with `modelOptions.response_format: 'diarized_json'` output for multi-speaker audio. Keep `chunking_strategy: 'auto'` unless you need custom VAD tuning.
diff --git a/docs/persistence/chat-persistence.md b/docs/persistence/chat-persistence.md
new file mode 100644
index 000000000..b9d80d236
--- /dev/null
+++ b/docs/persistence/chat-persistence.md
@@ -0,0 +1,196 @@
+---
+title: Chat Persistence
+id: chat-persistence
+---
+
+Use chat persistence when the server should be authoritative for a thread. The
+client may keep local UI state, but the durable transcript, run status, and
+pending user decisions live behind `withChatPersistence(...)`. This is **state
+durability** — messages, runs, and interrupts. Delivery durability (replaying an
+in-flight stream after a disconnect) is a separate transport concern; see
+[Delivery Durability](./delivery-durability).
+
+By the end, your endpoint accepts `{ threadId, runId, resume }`, persists chat
+state at boundaries, and — paired with a delivery-durability sink — lets the
+client reconnect to an in-progress response after a disconnect or reload.
+
+## Install a backend
+
+SQLite is the simplest durable backend for a Node server. The batteries-included
+`sqlPersistence` ships Drizzle-generated migrations:
+
+```sh
+pnpm add @tanstack/ai-persistence @tanstack/ai-persistence-drizzle
+```
+
+## Create the server endpoint
+
+Build the persistence instance once and reuse it across requests.
+
+```ts
+import {
+  chat,
+  memoryStream,
+  toServerSentEventsResponse,
+} from '@tanstack/ai'
+import { anthropicText } from '@tanstack/ai-anthropic'
+import { withChatPersistence } from '@tanstack/ai-persistence'
+import { sqlPersistence } from '@tanstack/ai-persistence-drizzle'
+
+const persistence = sqlPersistence({
+  dialect: 'sqlite',
+  url: 'file:.tanstack-ai/state.sqlite',
+  migrate: true,
+})
+
+export async function POST(request: Request) {
+  const { messages, threadId, runId, resume } = await request.json()
+
+  const stream = chat({
+    threadId,
+    runId,
+    resume,
+    adapter: anthropicText('claude-sonnet-4-6'),
+    messages,
+    middleware: [withChatPersistence(persistence)],
+  })
+
+  // State persists at boundaries; the durability sink makes the delivered
+  // stream resumable (native Last-Event-ID reconnect / second-tab join).
+  return toServerSentEventsResponse(stream, {
+    durability: { adapter: memoryStream(request) },
+  })
+}
+```
+
+`withChatPersistence(...)` loads stored thread history, saves the resulting
+transcript, and records run status and interrupts at run boundaries. `resume`
+carries interrupt/approval decisions back into a paused run. Delivery resume is
+handled entirely by the transport's durability sink — see
+[Delivery Durability](./delivery-durability). For the state store contract, see
+[Persistence Internals](./internals).
+
+If the same app also uses `withGenerationPersistence`, keep **run IDs unique
+across activities** — they may share a store and `threadId`, but not a
+`runId`. See
+[Persistence Overview](./overview#run-ids-must-be-unique-across-activities).
+
+## Wire the client
+
+The chat client forwards the resume fields through its connection adapter. Keep
+a stable `threadId` per conversation so a reload returns to the same server
+thread. Use `persistence.server` to store the client's latest resume snapshot
+under that `threadId`.
+
+```tsx
+import { fetchServerSentEvents, useChat } from '@tanstack/ai-react'
+import { localStorageAIPersistence } from '@tanstack/ai-client'
+
+const threadId = 'thread-123'
+
+export function Chat() {
+  const chat = useChat({
+    id: threadId,
+    threadId,
+    connection: fetchServerSentEvents('/api/chat'),
+    persistence: {
+      client: localStorageAIPersistence({
+        keyPrefix: 'tanstack-ai:messages:',
+      }),
+      server: localStorageAIPersistence({
+        keyPrefix: 'tanstack-ai:resume:',
+      }),
+    },
+  })
+
+  return (
+    <form
+      onSubmit={(event) => {
+        event.preventDefault()
+        const form = event.currentTarget
+        const input = new FormData(form).get('message')
+        if (typeof input === 'string' && input.trim()) {
+          chat.sendMessage({ content: input })
+          form.reset()
+        }
+      }}
+    >
+      {chat.messages.map((message) => (
+        <p key={message.id}>
+          {message.parts.map((part, index) =>
+            part.type === 'text' ? <span key={index}>{part.content}</span> : null,
+          )}
+        </p>
+      ))}
+      <input name="message" />
+      <button disabled={chat.status === 'streaming'}>Send</button>
+    </form>
+  )
+}
+```
+
+Delivery resume is transparent: the resumable SSE connection reattaches to an
+in-flight run via the browser's native `Last-Event-ID` on reconnect, with no
+client cursor state. There is no `resume()`/`autoResume` on `useChat` — see
+[Delivery Durability](./delivery-durability).
+
+`chat.resumeState` contains the active interrupt-resume identity
+(`{ threadId, runId }`), or `null` when there is nothing to continue.
+`chat.pendingInterrupts` contains the client-side descriptors needed to answer
+pending user decisions, resolved with `chat.resumeInterrupts(...)`.
+`persistence.server` stores them together and hydrates them on the next client
+construction.
+
+## Choose the controls you need
+
+Use [Persistence Controls](./controls) when you want the decision table. For
+chat, these are the common combinations:
+
+| Goal | Controls |
+| --- | --- |
+| Browser-only drafts | `persistence.client` on the chat client. |
+| Server-owned transcript | `stores.messages` and `features: ['messages']`. |
+| Reconnect without re-running the model | A delivery-durability sink on the transport — see [Delivery Durability](./delivery-durability). |
+| Pending approvals or human input | `interrupts`, which also requires the `stores.runs` and `stores.interrupts` stores. |
+| Multi-worker resume safety | Add `stores.locks` when a backend supports it. |
+
+## Resume pending decisions
+
+If the server finishes with `RUN_FINISHED.outcome.type === 'interrupt'`, the
+thread has a pending user-actionable wait. Resolve those waits with
+`chat.resumeInterrupts(...)`; the client forwards them as AG-UI
+`RunAgentInput.resume[]` entries on the next request.
+
+```ts
+import type { UseChatReturn } from '@tanstack/ai-react'
+
+declare const chat: Pick<UseChatReturn, 'resumeInterrupts'>
+
+await chat.resumeInterrupts([
+  {
+    interruptId: 'interrupt-1',
+    status: 'resolved',
+    payload: { approved: true },
+  },
+])
+```
+
+Normal new input on the same thread is rejected by default while pending
+interrupts exist. That keeps the server from accidentally creating a second
+conversation branch before the existing decision has been resolved or
+cancelled.
+
+Tool approvals are the common UI shape for interrupts. A tool with
+`needsApproval: true` can pause the run, surface an approval request, and resume
+after the user approves or denies it. For basic approval rendering without
+server persistence, see [Tool Approval Flow](../tools/tool-approval).
+
+## Keep client and server persistence separate
+
+Client-side chat persistence stores rendered `UIMessage` history in
+`localStorage`, IndexedDB, or another browser-side adapter. Server persistence
+stores model messages, run records, interrupts, and replayable public events.
+You can use both with `persistence: { client, server }`, but they solve
+different problems.
+
+For a narrow client-only page, see [Chat & Streaming Persistence](../chat/persistence).
diff --git a/docs/persistence/cloudflare.md b/docs/persistence/cloudflare.md
new file mode 100644
index 000000000..c6d726fca
--- /dev/null
+++ b/docs/persistence/cloudflare.md
@@ -0,0 +1,59 @@
+---
+title: Cloudflare Persistence
+id: cloudflare
+---
+
+Run `chat()` in Workers and keep **state durability** on Cloudflare primitives.
+D1 is SQLite-compatible, so the Drizzle D1 adapter satisfies the state store
+contract directly — there is no dedicated first-party Cloudflare persistence
+package. Point [`drizzlePersistence`](./drizzle) at a Drizzle D1 database and you
+get messages, runs, interrupts, metadata, artifacts, and blobs backed by D1.
+
+Delivery durability (replaying an in-flight stream after a disconnect) is a
+separate transport concern — see [Delivery Durability](./delivery-durability).
+
+## Bind D1 with drizzlePersistence
+
+```ts ignore
+import { drizzlePersistence } from '@tanstack/ai-persistence-drizzle'
+import { drizzle } from 'drizzle-orm/d1'
+
+interface Env {
+  AI_D1: D1Database
+}
+
+export function persistence(env: Env) {
+  // D1 is SQLite-compatible; the Drizzle D1 adapter is a BaseSQLiteDatabase and
+  // is assignable to drizzlePersistence's `db`. Generate/apply migrations from
+  // the exported `schema` with drizzle-kit (see the Drizzle guide).
+  return drizzlePersistence(drizzle(env.AI_D1))
+}
+```
+
+D1 backs every state store, including `stores.artifacts` (metadata rows) and
+`stores.blobs` (byte payloads in a SQLite blob column). If you need generated
+bytes in R2 instead of D1, keep run/message/artifact-index state in D1 and
+implement an R2-backed blob store via [Custom Stores](./custom-stores).
+
+For generated media hooks backed by artifact refs, see
+[Generation Persistence](./generation-persistence). For sandbox workspace
+checkpoints, see [Sandbox Persistence](./sandbox-persistence).
+
+## Migrations
+
+`drizzlePersistence` is bring-your-own: generate migrations from the exported
+`schema` with drizzle-kit and apply them to D1 (`wrangler d1 migrations`). Unlike
+the batteries-included `sqlPersistence` (Node SQLite only), the D1 path does not
+bundle migrations — you own the D1 schema lifecycle. See the
+[Drizzle guide](./drizzle) for the schema export and the drizzle-kit flow.
+
+## Locks
+
+The state backends ship an in-memory lock as a dev default. For cross-isolate
+mutual exclusion in Workers (sandbox resume, workflow coordination), provide a
+Durable Object–backed lock store that implements the `LockStore` contract and
+pass it as `stores.locks` via [Custom Stores](./custom-stores). Bind the Durable
+Object class in your Worker config as usual.
+
+For the state store method contracts, see
+[Persistence Internals](./internals).
diff --git a/docs/persistence/controls.md b/docs/persistence/controls.md
new file mode 100644
index 000000000..a07009c95
--- /dev/null
+++ b/docs/persistence/controls.md
@@ -0,0 +1,178 @@
+---
+title: Persistence Controls
+id: controls
+---
+
+Use persistence controls to choose how much durability a run needs. Start with
+the lowest lever that satisfies the user experience, then add stores only when a
+feature would otherwise lose data.
+
+By the end, you can map a product requirement such as "resume after refresh" or
+"store generated media" to the client option, middleware feature, and
+`AIPersistence` stores it needs.
+
+## Lever 1: no persistence
+
+Use no persistence when a run can disappear after the request ends.
+
+```ts
+import { chat } from '@tanstack/ai'
+import { anthropicText } from '@tanstack/ai-anthropic'
+
+chat({
+  adapter: anthropicText('claude-sonnet-4-6'),
+  messages: [{ role: 'user', content: 'Draft a release note.' }],
+})
+```
+
+There is no server transcript and no durable run record. This is enough for
+one-shot server work, tests, or prototypes where reload recovery does not
+matter.
+
+## Lever 2: client snapshots
+
+Use client persistence when the browser should remember local UI state or the
+latest server resume identity.
+
+```tsx
+import { localStorageAIPersistence } from '@tanstack/ai-client'
+import { fetchServerSentEvents, useChat } from '@tanstack/ai-react'
+
+const chat = useChat({
+  id: 'thread-123',
+  threadId: 'thread-123',
+  connection: fetchServerSentEvents('/api/chat'),
+  persistence: {
+    client: localStorageAIPersistence({
+      keyPrefix: 'tanstack-ai:messages:',
+    }),
+    server: localStorageAIPersistence({
+      keyPrefix: 'tanstack-ai:resume:',
+    }),
+  },
+})
+```
+
+`persistence.client` stores rendered UI messages. `persistence.server` stores
+the lightweight server resume snapshot: `{ threadId, runId }`, pending interrupt
+descriptors, status, and errors. The snapshot is not the source of truth for a
+server-authoritative transcript; it only lets the client restore pending
+interrupts after a full reload.
+
+## Lever 3: server messages
+
+Use message persistence when the server owns the chat transcript instead of
+trusting the browser to send the whole history.
+
+```ts
+import { defineAIPersistence, withChatPersistence } from '@tanstack/ai-persistence'
+import type { MessageStore } from '@tanstack/ai-persistence'
+import type { ModelMessage } from '@tanstack/ai'
+
+declare const db: {
+  loadMessages: (threadId: string) => Promise<Array<ModelMessage>>
+  replaceMessages: (
+    threadId: string,
+    messages: Array<ModelMessage>,
+  ) => Promise<void>
+}
+
+const messages: MessageStore = {
+  loadThread: (threadId) => db.loadMessages(threadId),
+  saveThread: (threadId, nextMessages: Array<ModelMessage>) =>
+    db.replaceMessages(threadId, nextMessages),
+}
+
+const persistence = defineAIPersistence({
+  stores: { messages },
+})
+
+const middleware = withChatPersistence(persistence, {
+  features: ['messages'],
+})
+```
+
+`stores.messages` is enough for server-owned history. It does not make the
+delivered stream resumable after a disconnect — that is **delivery durability**,
+a transport concern handled by a durability sink on `toServerSentEvents(...)`,
+not a persistence store. See [Delivery Durability](./delivery-durability).
+
+## Lever 4: interrupts and approvals
+
+Use interrupt persistence when a run can pause for a user decision and resume
+later.
+
+```ts
+import { withChatPersistence } from '@tanstack/ai-persistence'
+import { sqlPersistence } from '@tanstack/ai-persistence-drizzle'
+
+const persistence = sqlPersistence({
+  dialect: 'sqlite',
+  url: 'file:.tanstack-ai/state.sqlite',
+  migrate: true,
+})
+
+export const middleware = withChatPersistence(persistence, {
+  features: ['interrupts'],
+})
+```
+
+The `interrupts` feature requires `stores.runs` and `stores.interrupts`. A
+pending wait is surfaced on the stream, then the client resumes the same run
+with AG-UI `resume[]` entries.
+
+```ts
+import type { UseChatReturn } from '@tanstack/ai-react'
+
+declare const chat: Pick<UseChatReturn, 'resumeInterrupts'>
+
+await chat.resumeInterrupts([
+  {
+    interruptId: 'send-email-approval',
+    status: 'resolved',
+    payload: { approved: true },
+  },
+])
+```
+
+Approval UIs are one common presentation of interrupts. New durable flows should
+treat the interrupt outcome and `resume[]` payload as the source of truth.
+
+## Lever 5: extension stores
+
+Use extension stores when persistence must support integrations beyond the
+basic message/interrupt path.
+
+| Store | Use it for |
+| --- | --- |
+| `stores.metadata` | App-owned session ids, manifests, correlation state, and pointers. |
+| `stores.locks` | Cross-worker coordination for the same thread, sandbox, or workflow. |
+| `stores.artifacts` | Named outputs tied to a run and thread. |
+| `stores.blobs` | Raw object bytes used by artifacts or app-owned indexes. |
+
+Artifacts require both `stores.artifacts` and `stores.blobs` for generated
+media and file storage. If you pass a manual feature list, include both
+`'artifacts'` and `'blobs'` so metadata and bytes stay paired.
+
+```ts
+import { withChatPersistence } from '@tanstack/ai-persistence'
+import { sqlPersistence } from '@tanstack/ai-persistence-drizzle'
+
+const persistence = sqlPersistence({
+  dialect: 'sqlite',
+  url: 'file:.tanstack-ai/state.sqlite',
+  migrate: true,
+})
+
+export const middleware = withChatPersistence(persistence, {
+  features: ['messages', 'metadata', 'locks', 'artifacts', 'blobs'],
+})
+```
+
+If `features` is omitted, `withChatPersistence(...)` and
+`withGenerationPersistence(...)` enable the features supported by the stores
+present on the `AIPersistence` object. Pass `features` when you want fail-loud
+validation for a required capability.
+
+For exact store method contracts and resume invariants behind these controls,
+see [Persistence Internals](./internals).
diff --git a/docs/persistence/custom-stores.md b/docs/persistence/custom-stores.md
new file mode 100644
index 000000000..ba30a3a82
--- /dev/null
+++ b/docs/persistence/custom-stores.md
@@ -0,0 +1,218 @@
+---
+title: Custom Stores
+id: custom-stores
+---
+
+Use custom stores when the built-in backends do not match your infrastructure,
+or when an integration needs to add durable metadata, locks, artifacts, blobs,
+or internal checkpoints without changing the public chat replay stream.
+
+This page is reference material for adapter authors. If you only need to choose
+a packaged backend, start with [SQL Backends](./sql-backends) or
+[Cloudflare](./cloudflare). If you need the end-to-end chat journey, start with
+[Chat Persistence](./chat-persistence).
+
+For production apps, this is the recommended ownership model: keep persistence
+inside your app's database, queue, object store, and retention policies, then
+expose those systems to TanStack AI through `AIPersistence` store callback
+methods. The packaged SQL and Cloudflare backends are TanStack primitives you
+can opt into when they match your stack, but the store contract is the stable
+boundary for user-owned persistence.
+
+If you are deciding how to model generated files, workspace checkpoints, object
+bytes, metadata manifests, and locks together, read
+[Generation Persistence](./generation-persistence) and
+[Sandbox Persistence](./sandbox-persistence) first. This page explains the store
+interfaces behind those patterns.
+
+## Define an `AIPersistence`
+
+`AIPersistence` is an aggregate of optional stores. Implement only the stores
+your scenario needs, then validate features with `withChatPersistence(...)` or
+`withGenerationPersistence(...)`. During
+development, `memoryPersistence()` is a useful complete baseline: replace one
+store at a time with your backend implementation while keeping the feature
+validation behavior realistic.
+
+```ts group=custom-stores-define
+import {
+  defineAIPersistence,
+  memoryPersistence,
+  withChatPersistence,
+} from '@tanstack/ai-persistence'
+import type { MetadataStore } from '@tanstack/ai-persistence'
+
+class AcmeMetadataStore implements MetadataStore {
+  private values = new Map<string, unknown>()
+
+  async get(scope: string, key: string) {
+    return this.values.get(`${scope}:${key}`) ?? null
+  }
+
+  async set(scope: string, key: string, value: unknown) {
+    this.values.set(`${scope}:${key}`, value)
+  }
+
+  async delete(scope: string, key: string) {
+    this.values.delete(`${scope}:${key}`)
+  }
+}
+
+const baseline = memoryPersistence()
+
+const persistence = defineAIPersistence({
+  stores: {
+    ...baseline.stores,
+    metadata: new AcmeMetadataStore(),
+  },
+})
+
+const middleware = withChatPersistence(persistence, {
+  features: ['messages', 'interrupts', 'metadata'],
+})
+```
+
+If any required store is missing, setup fails before the run starts.
+
+`defineAIPersistence(...)` is only an identity helper for the aggregate store
+object. There is no separate high-level callback builder: implement the store
+methods directly and pass them under `stores`.
+
+## Use your existing persistence boundary
+
+Most production apps already have repositories or service methods for threads,
+runs, event logs, user decisions, metadata, and files. Wrap those methods in the
+store callbacks instead of adding a second persistence path.
+
+```ts group=custom-stores-app-boundary
+import {
+  defineAIPersistence,
+  withChatPersistence,
+} from '@tanstack/ai-persistence'
+import type { MessageStore, RunStore } from '@tanstack/ai-persistence'
+import type { ModelMessage } from '@tanstack/ai'
+
+type AppDb = {
+  threads: {
+    loadMessages: (threadId: string) => Promise<Array<ModelMessage>>
+    replaceMessages: (
+      threadId: string,
+      messages: Array<ModelMessage>,
+    ) => Promise<void>
+  }
+  runs: {
+    createOrResume: RunStore['createOrResume']
+    update: RunStore['update']
+    get: RunStore['get']
+  }
+}
+
+function appMessageStore(db: AppDb): MessageStore {
+  return {
+    loadThread: (threadId) => db.threads.loadMessages(threadId),
+    saveThread: (threadId, messages) =>
+      db.threads.replaceMessages(threadId, messages),
+  }
+}
+
+export function appPersistence(db: AppDb) {
+  return defineAIPersistence({
+    stores: {
+      messages: appMessageStore(db),
+      runs: db.runs,
+    },
+  })
+}
+
+export function persistenceMiddleware(db: AppDb) {
+  return withChatPersistence(appPersistence(db), {
+    features: ['messages'],
+  })
+}
+```
+
+Add `interrupts` when runs pause for user action, `metadata` for app-owned
+correlation, `locks` for cross-process coordination, and `artifacts` plus
+`blobs` when runs produce durable files or media. Every persistence feature is
+supported by implementing the corresponding stores. (Delivery durability —
+replaying an in-flight stream after a disconnect — is a transport concern, not a
+store; see [Delivery Durability](./delivery-durability).)
+
+| Feature | Required stores |
+| --- | --- |
+| `messages` | `stores.messages` |
+| `interrupts` | `stores.runs`, `stores.interrupts` |
+| `metadata` | `stores.metadata` |
+| `locks` | `stores.locks` |
+| `artifacts` | `stores.artifacts` |
+| `blobs` | `stores.blobs` |
+
+## Keep public and internal events separate
+
+`PublicEventStore` is the user-visible AG-UI stream. It is what reconnecting
+clients replay after an opaque cursor. Store exactly the public `StreamChunk`
+events there.
+
+`InternalEventStore` is for package-owned or app-owned checkpoints:
+compare-and-swap coordination, workflow checkpoints, adapter internals, or
+other state that must not be replayed to the UI. Keep those events namespaced
+and separate from the public stream.
+
+## Store app metadata
+
+Use `MetadataStore` for durable key/value state associated with a thread, run,
+or integration. MCP session correlation is a good example: the base persistence
+schema records public stream replay, while app-owned metadata can map a thread
+or run to an MCP session id.
+
+```ts group=custom-stores-metadata
+import { memoryPersistence } from '@tanstack/ai-persistence'
+
+const persistence = memoryPersistence()
+
+await persistence.stores.metadata?.set(
+  'thread:weather-chat',
+  'mcp-session',
+  { serverId: 'weather', sessionId: 'session-123' },
+)
+```
+
+Use a stable scope convention such as `thread:<threadId>` or `run:<runId>` so
+multiple integrations do not collide.
+
+## Add locks, artifacts, and blobs when needed
+
+`stores.locks` provides a shared `LockStore` capability. Sandboxes and workflow
+extensions use it to prevent two processes from resuming or mutating the same
+durable resource at the same time.
+
+`stores.artifacts` stores generated artifacts by `artifactId`, `runId`, and
+`threadId`. `stores.blobs` stores raw bytes and can be shared by artifacts or
+other integrations. A backend may store artifact metadata in SQL and bytes in
+object storage, as the [Cloudflare backend](./cloudflare) does with D1 and R2.
+For concrete generated media and sandbox workspace examples, see
+[Generation Persistence](./generation-persistence) and
+[Sandbox Persistence](./sandbox-persistence).
+
+The same hybrid pattern works outside Workers: use your SQL database for runs,
+messages, events, metadata, and artifact indexes, then implement `stores.blobs`
+against R2 or another object store for large bytes. Keep the blob key or
+artifact id in your SQL-owned records so your app, not TanStack AI, controls
+garbage collection, access checks, and retention.
+
+## Extend without growing the base schema
+
+MCP and workflow packages should build on the common stores instead of adding
+new base persistence tables for every feature:
+
+- use public events for UI replay,
+- use internal events for checkpoints,
+- use metadata for app-owned correlation,
+- use locks for cross-process coordination,
+- use artifacts and blobs for durable outputs.
+
+That keeps resumable chat small for apps that only need messages and replay,
+while still giving advanced integrations durable primitives.
+
+For the complete method-by-method contract, event ordering rules, and storage
+schema map, see [Persistence Internals](./internals).
diff --git a/docs/persistence/delivery-durability.md b/docs/persistence/delivery-durability.md
new file mode 100644
index 000000000..0b849b969
--- /dev/null
+++ b/docs/persistence/delivery-durability.md
@@ -0,0 +1,157 @@
+---
+title: Delivery Durability
+id: delivery-durability
+---
+
+**Delivery durability** is the transport-layer concern of letting a client
+disconnect, reload, or open a second tab and still receive the full, ordered
+run stream **exactly once**. It is distinct from **state durability** (thread
+messages, run status, interrupts, artifacts — the middleware layer covered by
+[Chat Persistence](./chat-persistence.md) and
+[Generation Persistence](./generation-persistence.md)).
+
+You get it by handing the transport helper a `durability` sink. The sink owns
+**zero** application storage of its own — it appends the produced chunks to a
+log and replays them on resume. Two backends ship:
+
+- `memoryStream(request)` — a process-local log. Zero infrastructure; the right
+  default for local dev and tests.
+- `durableStream(request, { server })` — the
+  [durable-streams](https://durablestreams.com) protocol, for production. The
+  durable-streams server owns the bytes (its own WAL / group-commit); we store
+  nothing.
+
+## How resume works
+
+`chat()` is lazy — calling it runs no provider request until the first
+`for await`. The transport helper uses that:
+
+- **Fresh request** — the helper iterates the stream, batches the chunks,
+  `append`s each batch to the durability log, and forwards them as SSE, tagging
+  every event with `id: <runId@seq>`.
+- **Reconnect / second tab** — the helper reads the resume offset off the
+  request (the browser's native `Last-Event-ID`, or a `?offset` query param),
+  replays the log strictly after that offset, and **never iterates the input
+  stream** — so `chat()` never calls the provider again. The untouched iterator
+  is simply garbage-collected.
+
+Because each SSE event carries an `id:`, native `EventSource` resends
+`Last-Event-ID` on reconnect with zero application code. Joining an
+already-running run passes `?offset=-1`.
+
+## Server: wire a durability sink
+
+Pass `durability` to any transport helper. In development, `memoryStream` needs
+no setup:
+
+```ts
+import { chat, memoryStream, toServerSentEventsResponse } from '@tanstack/ai'
+import { openaiText } from '@tanstack/ai-openai'
+
+export async function POST(request: Request) {
+  const stream = chat({
+    adapter: openaiText('gpt-5.5'),
+    messages: [{ role: 'user', content: 'Tell me about guitars.' }],
+    stream: true,
+  })
+
+  return toServerSentEventsResponse(stream, {
+    durability: { adapter: memoryStream(request) },
+  })
+}
+```
+
+For production, swap in `durableStream` — the only change is the sink:
+
+```ts
+import { chat, toServerSentEventsResponse } from '@tanstack/ai'
+import { durableStream } from '@tanstack/ai-durable-stream'
+import { openaiText } from '@tanstack/ai-openai'
+
+export async function POST(request: Request) {
+  const stream = chat({
+    adapter: openaiText('gpt-5.5'),
+    messages: [{ role: 'user', content: 'Tell me about guitars.' }],
+    stream: true,
+  })
+
+  return toServerSentEventsResponse(stream, {
+    durability: {
+      adapter: durableStream(request, { server: process.env.DS_URL ?? '' }),
+      // Optional: how many chunks to buffer per append (default 32).
+      batch: 32,
+    },
+  })
+}
+```
+
+The same `durability` option is available on `toHttpResponse` for
+newline-delimited JSON transports (they resume via `?offset` rather than native
+`Last-Event-ID`).
+
+## Client: plain, resumable SSE
+
+The client needs **no cursor machinery**. A plain `sse` connection is
+resumable: when the server tags events with `id:` offsets, a dropped connection
+reconnects with `Last-Event-ID` automatically and de-dupes any replayed prefix.
+
+```ts
+import { useChat } from '@tanstack/ai-react'
+import { fetchServerSentEvents } from '@tanstack/ai-client'
+
+function Chat() {
+  const chat = useChat({
+    connection: fetchServerSentEvents('/api/chat'),
+  })
+  // ...render chat.messages
+}
+```
+
+### Joining an in-flight or finished run
+
+To attach a second tab (or re-attach after a full reload) to a run that is
+already streaming, `joinRun(runId)` opens the stream from the start via
+`?offset=-1`:
+
+```ts ignore
+import { fetchServerSentEvents } from '@tanstack/ai-client'
+
+const connection = fetchServerSentEvents('/api/chat')
+
+for await (const chunk of connection.joinRun(runId)) {
+  // Same ordered event stream the original tab is receiving.
+  if (chunk.type === 'TEXT_MESSAGE_CONTENT' && 'delta' in chunk) {
+    appendDelta(chunk.delta)
+  }
+}
+```
+
+## Ceiling: producer lifetime (`waitUntil`)
+
+Delivery durability replays what was **produced**. It cannot resume an LLM
+completion that never finished producing: if the **producer process** dies
+mid-run (e.g. a serverless function torn down the instant the client socket
+closes), the log holds only the partial output and cannot continue it.
+
+The fix is deployment, not code — run the producer in something that outlives
+the client socket:
+
+- a platform `waitUntil(...)` (Cloudflare Workers, Vercel) so the function keeps
+  running after the response is returned,
+- a durable object, or
+- a background queue / worker.
+
+With the producer kept alive, the log fills to completion and any reconnect or
+second tab replays the whole run exactly once.
+
+## Escape hatch: CDN fan-out
+
+The shipped default keeps your app server in the connection path — it tails the
+durability log and re-emits SSE. That is fine for hundreds to low-thousands of
+concurrent readers.
+
+For kernel-speed CDN fan-out, point the browser **directly** at the
+durable-streams server (the app server only writes; the CDN collapses many
+readers onto one origin read). That direct-to-DS wiring is an advanced,
+documented pattern, not shipped API — reach for it only when the app-server
+fan-out ceiling is the actual bottleneck.
diff --git a/docs/persistence/drizzle.md b/docs/persistence/drizzle.md
new file mode 100644
index 000000000..17657215f
--- /dev/null
+++ b/docs/persistence/drizzle.md
@@ -0,0 +1,105 @@
+---
+title: Persistence with Drizzle
+id: drizzle
+---
+
+`@tanstack/ai-persistence-drizzle` is the batteries-included SQL backend for
+TanStack AI **state** persistence. It ships a Drizzle schema, drizzle-kit
+migrations, and two entry points that both return the same `AIPersistence`
+contract consumed by `withChatPersistence(...)` and `withGenerationPersistence(...)`.
+
+- `sqlPersistence({ dialect, url, migrate })` — **batteries-included.** Give it a
+  dialect and a URL; it builds the database and applies the migrations bundled
+  in the package.
+- `drizzlePersistence(db)` — **bring your own.** Pass a Drizzle database you
+  already constructed and migrated against the exported `schema`.
+
+```sh
+pnpm add @tanstack/ai-persistence @tanstack/ai-persistence-drizzle drizzle-orm
+```
+
+## Batteries-included: `sqlPersistence`
+
+For local development and single-node deployments, `sqlPersistence` is the
+fastest path. The `sqlite` dialect is bundled with pre-generated migrations, so
+`migrate: true` creates the schema on first use.
+
+```ts
+import { sqlPersistence } from '@tanstack/ai-persistence-drizzle'
+import { withChatPersistence } from '@tanstack/ai-persistence'
+
+export const persistence = sqlPersistence({
+  dialect: 'sqlite',
+  url: 'file:./.tanstack-ai/state.sqlite',
+  migrate: true,
+})
+
+export const middleware = withChatPersistence(persistence)
+```
+
+Use `url: ':memory:'` for tests. For production, generate and review the
+migrations ahead of time (see below) and leave `migrate` unset so the schema is
+deployed by your own pipeline rather than lazily at runtime.
+
+## Bring your own: `drizzlePersistence`
+
+When Drizzle already owns your database connection and migration workflow, pass
+your `db` directly. This works with any Drizzle sqlite driver
+(`better-sqlite3`, `libsql`/Turso, D1, `node:sqlite`).
+
+```ts ignore
+import { drizzle } from 'drizzle-orm/better-sqlite3'
+import Database from 'better-sqlite3'
+import { drizzlePersistence, schema } from '@tanstack/ai-persistence-drizzle'
+import { withChatPersistence } from '@tanstack/ai-persistence'
+
+const db = drizzle(new Database('state.sqlite'), { schema })
+
+export const persistence = drizzlePersistence(db)
+export const middleware = withChatPersistence(persistence)
+```
+
+The package re-exports the `schema` (and each table) so you can compose it into
+your own Drizzle schema and drive migrations from your existing setup.
+
+## Generate migrations with drizzle-kit
+
+The schema is the single source of truth for migrations. The package ships a
+`drizzle.config.ts`; regenerate the SQL under `drizzle/` after any schema change:
+
+```sh
+pnpm --filter @tanstack/ai-persistence-drizzle db:generate
+```
+
+For a bring-your-own database, point drizzle-kit at the exported schema in your
+own `drizzle.config.ts` and run `drizzle-kit generate` / `drizzle-kit migrate`
+through your normal workflow. See [Migrations](./migrations) for the full flow.
+
+## What is persisted
+
+The schema mirrors the `AIPersistence` state records column-for-column:
+
+- `messages` — thread message history
+- `runs` — run lifecycle (status, usage, timing)
+- `interrupts` — interrupts / approvals
+- `metadata` — scoped key/value metadata
+- `artifacts` — generation artifact references
+- `blobs` — generic blob objects
+
+Delivery durability (resuming an interrupted stream) is a **transport** concern
+and is not stored here. Locks are not part of the SQL schema; an in-memory lock
+is provided as a dev default. Swap in a distributed lock for multi-process
+deployments via [Custom Stores](./custom-stores).
+
+## Use it across the guides
+
+The same Drizzle-backed `AIPersistence` object works across the topic guides:
+
+- [Chat Persistence](./chat-persistence) for server-owned transcripts.
+- [Persistence Controls](./controls) when you need to choose a feature list.
+- [Custom Stores](./custom-stores) when you want Drizzle for SQL state but a
+  separate object store for blobs.
+
+Other dialects (`postgres`, `mysql`) are bring-your-own today: construct a
+Drizzle db with your own driver and use `drizzlePersistence(db)` with migrations
+generated from the exported `schema`.
diff --git a/docs/persistence/generation-persistence.md b/docs/persistence/generation-persistence.md
new file mode 100644
index 000000000..1de8a751d
--- /dev/null
+++ b/docs/persistence/generation-persistence.md
@@ -0,0 +1,260 @@
+---
+title: Generation Persistence
+id: generation-persistence
+---
+
+Use generation persistence when the generated media from an image, audio,
+speech, transcription, or video endpoint should survive a refresh. The server
+owns the durable run through `withGenerationPersistence(...)`, which records run
+status plus artifact/blob records; the client keeps only a lightweight,
+read-only state snapshot for observability.
+
+By the end, your generation hook can display generated media from persisted
+artifact refs instead of browser-stored bytes, and observe the last run's status
+after a reload.
+
+## Install a backend with artifacts and blobs
+
+Generated media/file persistence requires both `stores.artifacts` and
+`stores.blobs`. The batteries-included SQLite backend provides both: artifact
+metadata rows and blob bytes. For a cloud object store (R2/S3) behind the blob
+side, bring your own blob store via [Custom Stores](./custom-stores).
+
+```sh
+pnpm add @tanstack/ai-persistence @tanstack/ai-persistence-drizzle
+```
+
+## Create the generation endpoint
+
+Read the hook request with `generationParamsFromRequest(...)`, pass the resume
+identity into the generation call, and add `withGenerationPersistence(persistence)`.
+Return the stream with `toServerSentEventsResponse(...)` so the client can read
+both live events and replayed events.
+
+```ts group=generation-persistence-server
+import {
+  generateImage,
+  generationParamsFromRequest,
+  toServerSentEventsResponse,
+} from '@tanstack/ai'
+import { openaiImage } from '@tanstack/ai-openai'
+import { sqlPersistence } from '@tanstack/ai-persistence-drizzle'
+import { withGenerationPersistence } from '@tanstack/ai-persistence'
+
+// State durability: run status + artifact metadata + blob bytes. The
+// batteries-included SQLite backend stores artifact bytes in a blob column;
+// for a cloud object store (R2/S3), bring your own blob store via custom stores.
+const persistence = sqlPersistence({
+  dialect: 'sqlite',
+  url: 'file:.tanstack-ai/generation.sqlite',
+  migrate: true,
+})
+
+export async function POST(request: Request) {
+  const { input, threadId, runId } =
+    await generationParamsFromRequest('image', request)
+
+  if (typeof input.prompt !== 'string') {
+    throw new Error('This endpoint accepts text image prompts only.')
+  }
+
+  const identity: { threadId?: string; runId?: string } = {}
+  if (threadId !== undefined) identity.threadId = threadId
+  if (runId !== undefined) identity.runId = runId
+
+  const stream = generateImage({
+    ...identity,
+    prompt: input.prompt,
+    adapter: openaiImage('gpt-image-2'),
+    stream: true as const,
+    middleware: [withGenerationPersistence(persistence)],
+  })
+
+  return toServerSentEventsResponse(stream)
+}
+```
+
+Use the generation kind that matches the endpoint: `'image'`, `'audio'`,
+`'tts'`, `'video'`, or `'transcription'`. If you already parsed JSON in your
+framework route, call `generationParamsFromBody(kind, body)` instead of
+`generationParamsFromRequest(kind, request)`.
+
+`forwardedProps` are app-controlled request metadata. Do not pass them directly
+to `modelOptions`; validate and whitelist any app-specific routing or provider
+options before using them on the server.
+
+When the same app also uses `withChatPersistence`, keep **run IDs unique across
+activities**. Chat and generation may share one `AIPersistence` backend and even
+the same `threadId`, but `runs` is keyed only by `runId`. Client hooks allocate
+a fresh `run-…` id per send/generate by default; only override ids deliberately.
+See [Persistence Overview](./overview#run-ids-must-be-unique-across-activities)
+and [Persistence Internals](./internals#shared-backends-unique-runid-across-chat-and-generation).
+
+## Wire the client hook
+
+Use `persistence.server` to store the latest generation state snapshot under a
+stable `id`. The snapshot contains `{ threadId, runId }`, status, errors, and
+lightweight artifact refs. It does not contain generated image, audio, or video
+bytes.
+
+```tsx group=generation-persistence-client
+import { fetchServerSentEvents, useGenerateImage } from '@tanstack/ai-react'
+import { localStorageAIPersistence } from '@tanstack/ai-client'
+
+const generationId = 'hero-image'
+
+export function HeroImageGenerator() {
+  const image = useGenerateImage({
+    id: generationId,
+    connection: fetchServerSentEvents('/api/generate/image'),
+    persistence: {
+      server: localStorageAIPersistence({
+        keyPrefix: 'tanstack-ai:generation-resume:',
+      }),
+    },
+  })
+
+  return (
+    <section>
+      <button
+        disabled={image.isLoading}
+        onClick={() => image.generate({ prompt: 'A glass cabin in a pine forest' })}
+      >
+        Generate
+      </button>
+
+      {image.resumeState && <p>Last run: {image.resumeState.runId}</p>}
+
+      {image.pendingArtifacts.map((artifact) => (
+        <a key={artifact.artifactId} href={`/api/artifacts/${artifact.artifactId}`}>
+          {artifact.name}
+        </a>
+      ))}
+    </section>
+  )
+}
+```
+
+The snapshot is **read-only**. Generation hooks never auto-start a run on mount
+and expose no `resume()` action — a run begins only when you call
+`generate(...)`. `resumeState`, `pendingArtifacts`, and `resultArtifacts` let you
+render persisted artifact refs and observe the last run's status after a reload;
+they do not reconnect to a server run. Pass `initialResumeSnapshot` to hydrate
+this state from your own store when the identity lives outside the hook
+persistence adapter.
+
+## Serve persisted artifacts
+
+Generation hooks store lightweight artifact refs. Serve the durable bytes from
+your app by looking up the artifact by `artifactId`.
+
+```ts
+import { sqlPersistence } from '@tanstack/ai-persistence-drizzle'
+
+const persistence = sqlPersistence({
+  dialect: 'sqlite',
+  url: 'file:.tanstack-ai/generation.sqlite',
+  migrate: true,
+})
+
+export async function GET(
+  request: Request,
+  context: { params: Promise<{ artifactId: string }> },
+) {
+  void request
+  const { artifactId } = await context.params
+  const { stores } = persistence
+
+  if (!stores.artifacts || !stores.blobs) {
+    throw new Error('Artifact and blob stores are required.')
+  }
+
+  const artifact = await stores.artifacts.get(artifactId)
+
+  if (!artifact) {
+    return new Response('Artifact not found', { status: 404 })
+  }
+
+  const blob = await stores.blobs.get(
+    `artifacts/${artifact.runId}/${artifact.artifactId}`,
+  )
+
+  if (!blob) {
+    return new Response('Artifact not found', { status: 404 })
+  }
+
+  return new Response(blob.body ?? (await blob.arrayBuffer()), {
+    headers: {
+      'Content-Type': artifact.mimeType,
+      'Content-Length': String(artifact.size),
+      'Content-Disposition': `inline; filename="${artifact.name}"`,
+    },
+  })
+}
+```
+
+## Customize generated artifacts
+
+Passing `withGenerationPersistence(persistence)` into a generation call enables built-in
+artifact persistence when the selected backend exposes both stores. Built-in
+extraction covers input media prompt parts, generated media outputs, generated
+video URLs, transcription input audio, and structured transcription JSON.
+
+Use `extractArtifacts` when your app needs a different artifact set than the
+built-in extractor. Providing it replaces built-in extraction for that run, so
+include every input and output artifact you want persisted.
+
+```ts
+import { generateImage } from '@tanstack/ai'
+import { openaiImage } from '@tanstack/ai-openai'
+import { sqlPersistence } from '@tanstack/ai-persistence-drizzle'
+import { withGenerationPersistence } from '@tanstack/ai-persistence'
+
+const persistence = sqlPersistence({
+  dialect: 'sqlite',
+  url: 'file:.tanstack-ai/generation.sqlite',
+  migrate: true,
+})
+
+const result = await generateImage({
+  threadId: 'thread-123',
+  runId: 'run-123',
+  adapter: openaiImage('gpt-image-2'),
+  prompt: 'A product photo on a white background',
+  middleware: [
+    withGenerationPersistence(persistence, {
+      extractArtifacts: ({ result }) => [
+        {
+          role: 'output',
+          path: 'metadata',
+          mediaType: 'json',
+          mimeType: 'application/json',
+          json: { generatedAt: new Date().toISOString(), result },
+          name: 'generation-metadata.json',
+        },
+      ],
+      nameArtifact: ({ descriptor, index }) =>
+        `${descriptor.role}-${descriptor.mediaType ?? 'artifact'}-${index}.bin`,
+    }),
+  ],
+})
+
+console.log(result.artifacts)
+```
+
+## Understand what resumes
+
+Generation hooks persist a lightweight client snapshot, not media bytes. The
+snapshot stores `resumeState`, status, pending artifact refs, completed result
+artifact refs, and lightweight error metadata.
+
+Generated bytes are persisted by the server through artifact/blob stores, and
+`withGenerationPersistence(...)` records generation run status plus artifact/blob
+records. State durability does not itself make the delivered stream resumable —
+that is a transport concern; pair the endpoint with a delivery-durability sink
+(see [Delivery Durability](./delivery-durability)). If your endpoint aborts the
+provider request when the browser disconnects, resume cannot produce a future
+result for work the server canceled. Resumable generation needs a durable
+producer that outlives the client socket, or a durable result that your endpoint
+can read when the client reconnects. For the artifact write path, see
+[Persistence Internals](./internals).
diff --git a/docs/persistence/internals.md b/docs/persistence/internals.md
new file mode 100644
index 000000000..f7df0cf8e
--- /dev/null
+++ b/docs/persistence/internals.md
@@ -0,0 +1,362 @@
+---
+title: Persistence Internals
+id: internals
+---
+
+Persistence internals are for backend builders, custom store authors,
+infrastructure owners, and integration authors who need to reason about the
+durable boundary behind `withChatPersistence(...)`.
+
+Use the journey pages first when you are wiring a product flow:
+[Chat Persistence](./chat-persistence), [Generation Persistence](./generation-persistence),
+[Sandbox Persistence](./sandbox-persistence), and [MCP Persistence](./mcp-persistence).
+This page explains the store contracts, event logs, resume semantics, and
+storage layouts those guides build on.
+
+## Boundary model
+
+`AIPersistence` is the stable persistence boundary. SQL tables, D1 rows, R2
+objects, and object-store prefixes are backend implementation details. Custom
+stores should implement the `AIPersistence.stores` methods directly and keep
+app-specific schema, queues, and retention rules behind that boundary.
+
+```mermaid
+flowchart LR
+  Client[Client snapshot\nthreadId runId cursor] --> Route[Server route]
+  Route --> Middleware[withChatPersistence]
+  Middleware --> Chat[chat or generation activity]
+  Middleware --> Stores[AIPersistence stores]
+
+  Stores --> SQL[SQL or D1\nruns messages events interrupts metadata]
+  Stores --> Objects[Blob store\nR2 or app object storage]
+  Stores --> Locks[Lock store\nDurable Object or app lock]
+  Stores --> Custom[User-owned DB/services]
+
+  Chat --> Public[Public StreamChunks]
+  Public --> Middleware
+  Middleware --> Client
+```
+
+There is no separate high-level callback builder. Implement the store methods
+and pass them under `stores`.
+
+### Shared backends: unique `runId` across chat and generation
+
+Chat and generation may share one `AIPersistence` instance. Partitioning is by
+store surface (`messages` / `publicEvents` / `interrupts` for chat;
+`artifacts` / `blobs` for generation) and by **`runId`** for the shared `runs`
+table.
+
+`RunRecord` has no activity/type field. `createOrResume({ runId })` returns an
+existing row when that id is already present, so a reused `runId` lets one
+activity overwrite another's status and can break chat replay validation.
+
+Default id generation (no app override):
+
+- **Chat client** — `ChatClient` allocates
+  `run-${Date.now()}-${random}` on each new send; resume requests reuse the
+  prior `runId` from the client snapshot.
+- **Generation client** — allocates
+  `run-${Date.now()}-${random}` when a generation run begins (devtools /
+  generation bridge).
+- **Server `chat()`** — uses the request's `runId` when provided; otherwise the
+  engine's per-request id (`chat-${Date.now()}-${random}` via `createId`).
+- **Server generation activities** — use caller `runId` when provided; run
+  persistence falls back to `requestId` when `runId` is omitted.
+
+Apps that mint their own ids must keep them unique across chat and generation.
+Sharing a `threadId` between those activities is supported and recommended when
+they belong to the same conversation.
+
+## Store contracts
+
+Implement the smallest store set your feature needs. Methods are asynchronous,
+and missing records generally return `null` or an empty collection rather than
+throwing.
+
+| Store | Methods | Expected behavior | Used by |
+| --- | --- | --- | --- |
+| `messages` | `loadThread(threadId)`, `saveThread(threadId, messages)` | Load returns the server-owned `ModelMessage[]` for the thread or `[]`. Save replaces the durable thread transcript. | Server-authoritative chat history. |
+| `runs` | `createOrResume(input)`, `update(runId, patch)`, `get(runId)` | Create returns an existing run when present, otherwise creates a run with status, thread id, and timestamps. Update patches terminal status, error, finish time, or usage. Get returns `RunRecord | null`. | Durable replay, interrupts, generation run status. |
+| `publicEvents` | `append({ runId, expectedSeq, event })`, `read(runId, opts)`, `hasRun(runId)`, `latestSeq(runId)` | Append writes the next per-run public event only when `expectedSeq` matches the latest persisted sequence and returns the persisted event plus an opaque cursor. Read yields ordered public events after an optional sequence. | Chat reconnect replay and interrupt surface events. |
+| `internalEvents` | `append({ runId, expectedSeq, namespace, type, payload })`, `read(runId, opts)`, `latestSeq(runId, namespace?)` | Append writes the next event for a run and namespace. Read can filter by namespace and sequence. Ordering is per namespace. | Private integration checkpoints, workflow state, MCP checkpoints. |
+| `interrupts` | `create`, `resolve`, `cancel`, `get`, `list`, `listPending`, `listByRun`, `listPendingByRun` | Create records a pending wait. Resolve/cancel marks the decision terminal and may store a response. List methods return thread/run scoped records. | Tool approvals, client-tool waits, human decisions. |
+| `metadata` | `get(scope, key)`, `set(scope, key, value)`, `delete(scope, key)` | Scoped durable key/value storage. Get returns `unknown | null`; value shape is owned by the app or integration. | MCP session correlation, sandbox records, workspace manifests, app-owned pointers. |
+| `locks` | `withLock(key, fn)` | Runs a critical section under a named lock and returns the callback result. In-memory locks are single-process only; distributed deployments need a durable lock. | Sandbox ensure, workspace checkpoints, cross-worker coordination. |
+| `artifacts` | `save(record)`, `get(artifactId)`, `list(runId)`, optional `delete`, optional `deleteForRun` | Stores artifact metadata keyed by artifact id and run id. `get` may hydrate bytes when the backend stores them with the artifact. | Generation outputs, sandbox workspace files, durable app files. |
+| `blobs` | `put`, `get`, `head`, `delete`, `list` | Raw byte/object storage by logical key. List may return a cursor and truncation flag. | Artifact bytes and app-owned object storage. |
+
+Feature validation maps directly to these stores:
+
+| Feature | Required stores |
+| --- | --- |
+| `messages` | `messages` |
+| `durable-replay` | `runs`, `publicEvents` |
+| `interrupts` | `runs`, `publicEvents`, `interrupts` |
+| `internal-events` | `internalEvents` |
+| `metadata` | `metadata` |
+| `locks` | `locks` |
+| `artifacts` | `artifacts` |
+| `blobs` | `blobs` |
+
+When artifact persistence is enabled for generation, `artifacts` and `blobs`
+must be present together.
+
+## Event model
+
+Public events are user-visible `StreamChunk` values. They are the AG-UI stream:
+`RUN_STARTED`, message and tool chunks, `MESSAGES_SNAPSHOT`, `CUSTOM`, terminal
+`RUN_FINISHED`, and error chunks. `withChatPersistence(...)` stamps a cursor onto
+each chat chunk before appending it to `publicEvents`.
+
+Internal events are private checkpoints. They are not replayed to the UI and
+should be namespaced by the owner, such as `mcp`, `workflow`, or an app-specific
+name. Use `latestSeq(runId, namespace)` and pass the current latest sequence as
+`expectedSeq` when appending the next internal event.
+
+```mermaid
+flowchart TB
+  Chunk[StreamChunk from chat] --> Stamp[Stamp opaque cursor]
+  Stamp --> Append[publicEvents.append]
+  Append --> Client[Yield to client]
+
+  Checkpoint[Integration checkpoint] --> Namespace[Choose namespace]
+  Namespace --> Internal[internalEvents.append]
+  Internal --> Private[Private replay or recovery only]
+```
+
+Cursors are opaque. Clients store and echo them back; they should not parse,
+sort, increment, or derive database offsets from them. Backends may encode a
+sequence internally, but the public contract is the cursor string.
+
+## Chat timeline
+
+```mermaid
+sequenceDiagram
+  participant C as Client
+  participant R as Route
+  participant P as withChatPersistence
+  participant S as Stores
+  participant A as Adapter
+
+  C->>R: POST messages, threadId
+  R->>P: chat config
+  P->>S: runs.createOrResume
+  P->>S: messages.loadThread
+  P->>A: run chat with merged messages
+  A-->>P: StreamChunk
+  P->>S: publicEvents.append
+  P-->>C: chunk with cursor
+  A-->>P: RUN_FINISHED
+  P->>S: runs.update completed or interrupted
+  P->>S: messages.saveThread
+```
+
+On the first chat run, persistence creates or resumes the run, optionally loads
+stored thread history, appends public chunks as they stream, and saves the final
+thread transcript on normal completion. If the terminal event has
+`RUN_FINISHED.outcome.type === 'interrupt'`, `withChatPersistence(...)` creates
+pending interrupt records, updates the run to `interrupted`, and saves the
+thread at the interrupt boundary.
+
+```mermaid
+sequenceDiagram
+  participant C as Client
+  participant R as Route
+  participant P as withChatPersistence
+  participant S as Stores
+  participant E as chat engine
+
+  C->>R: POST threadId, runId, cursor
+  R->>P: chat config with cursor
+  P->>S: runs.get and publicEvents.latestSeq
+  P->>S: validate cursor belongs to run and thread
+  P->>E: provide ResumeSource
+  E->>S: publicEvents.read after cursor
+  S-->>C: persisted chunks after cursor
+```
+
+Resume requires the same `threadId`, the same `runId`, and the last observed
+opaque `cursor`. `withChatPersistence(...)` validates that the run exists, that it
+belongs to the requested thread, and that the cursor references a persisted
+public event before the chat engine reads from the resume source provided during
+setup. The resume source then reads ordered public events after the validated
+cursor.
+
+## Generation timeline
+
+Generation activities use persistence differently from chat.
+
+```mermaid
+flowchart TD
+  Request[Generation request\ninput threadId runId cursor] --> Run[runs.createOrResume]
+  Run --> Provider[Provider generation]
+  Provider --> Result[Generation result]
+  Result --> Extract[Built-in or custom artifact extraction]
+  Extract --> Blob[blobs.put bytes or fetched URL body]
+  Blob --> Artifact[artifacts.save record]
+  Artifact --> Transform[Attach artifact refs to result]
+  Transform --> Finish[runs.update completed]
+```
+
+`withGenerationPersistence(...)` creates or resumes a run for generation and
+updates run status on finish, error, or abort. When artifact persistence is
+enabled, it extracts built-in artifacts or calls `extractArtifacts`, writes
+bytes through `blobs.put`, saves an `ArtifactRecord`, and attaches lightweight
+persisted refs to the result.
+
+Generation stream events are not persisted to `publicEvents` by
+`withGenerationPersistence(...)` today. A generation hook can replay what the
+server has durably produced only when your endpoint keeps enough state to
+replay or tail the producer. Durable continuation therefore needs a lightweight
+client snapshot plus durable producer/replay/result state owned by your app or
+backend. Artifact stores persist generated bytes and refs; they do not by
+themselves keep a canceled provider request running.
+
+## Sandbox timeline
+
+Sandbox persistence combines chat replay with sandbox-specific records.
+
+```mermaid
+flowchart TD
+  Chat[chat run] --> Persist[withChatPersistence provides stores]
+  Persist --> Sandbox[withSandbox ensure]
+  Sandbox --> Record[Sandbox record\nmetadata or SandboxStore]
+  Sandbox --> Lock[Optional lock\nsame sandbox key]
+  Sandbox --> Workspace{Workspace persistence?}
+  Workspace -->|yes| Manifest[metadata manifest]
+  Workspace -->|yes| Files[artifacts records]
+  Workspace -->|yes| Bytes[blobs or artifact bytes]
+```
+
+`withSandbox(...)` prefers an explicit `SandboxStore` capability. If none is
+provided and `withChatPersistence(...)` exposes `metadata`, sandbox records are
+stored under persistence metadata. The record maps the computed sandbox key to
+provider, provider sandbox id, thread id, latest run id, and optional snapshot
+id.
+
+Workspace persistence uses `metadata` for the manifest, `artifacts` for file
+records, and artifact bytes or `blobs` depending on the backend. It may use
+`locks` to serialize checkpoint updates. To resume a sandbox across processes,
+you need durable metadata records and a provider/harness that can reattach to
+the sandbox. To restore files when the filesystem is gone, you also need durable
+artifact/file storage.
+
+## MCP timeline
+
+MCP persistence has two layers:
+
+- Managed MCP tools inside `chat()` use the normal chat stores for thread
+  messages, run status, public replay, and optional internal checkpoints.
+- MCP Apps can additionally use `McpSessionStore` to resolve reconnectable MCP
+  server descriptors for widget tool calls.
+
+```mermaid
+flowchart LR
+  Chat[chat with MCP clients] --> Public[publicEvents\nUI replay]
+  Chat --> Metadata[metadata\nsession/correlation]
+  Chat --> Internal[internalEvents\nprivate checkpoints]
+  Widget[MCP App widget] --> Handler[createMcpAppCallHandler]
+  Handler --> Store[McpSessionStore optional]
+  Handler --> MCP[MCP server reconnect per call]
+```
+
+Use `metadata` for app-owned current lookup state such as server ids, session
+ids, OAuth account ids, or resource versions. Use `internalEvents` for private
+tool-call checkpoints that should not replay to the user. Use
+`McpSessionStore` when interactive MCP Apps need stateful transport resolution;
+the in-memory implementation is single-instance, and durable SQL or KV
+implementations can satisfy the same interface.
+
+## SQL schema map
+
+The shared SQL schema backs SQLite, Postgres, Prisma, Drizzle, and the D1 core
+tables used by Cloudflare persistence.
+
+| Table | Store | Key columns | Notes |
+| --- | --- | --- | --- |
+| `runs` | `runs` | `run_id` primary key, `thread_id`, `status` | Stores lifecycle timestamps, error text, and usage JSON. |
+| `messages` | `messages` | `thread_id` primary key | Stores the server-owned serialized `ModelMessage[]`. |
+| `public_events` | `publicEvents` | primary key `(run_id, seq)` | Stores serialized public `StreamChunk` values. There is no `cursor` column by design; cursors are returned by the store contract. |
+| `internal_events` | `internalEvents` | primary key `(run_id, namespace, seq)` | Stores namespaced private events. Ordering is per namespace. |
+| `interrupts` | `interrupts` | `interrupt_id` primary key | Stores pending, resolved, or cancelled human/client waits with payload and optional response. |
+| `metadata` | `metadata` | primary key `(scope, key)` | Stores scoped JSON values owned by apps and integrations. |
+| `_tanstack_ai_migrations` | migration runner | `version` primary key | Migration bookkeeping only. Plain `ddl(...)` output does not emit this table; lazy migration creates it when `migrate: true` runs. |
+
+The SQL DDL stores JSON as text for portability. `public_events` and
+`internal_events` rely on append compare-and-swap with `expectedSeq`. If another
+writer has advanced the same run or namespace, append should fail with a
+conflict rather than silently create a forked event stream.
+
+## Cloudflare storage map
+
+```mermaid
+flowchart TB
+  Worker[Worker] --> D1[D1 shared SQL\nruns messages events interrupts metadata]
+  Worker --> DO[Durable Object locks\noptional]
+  Worker --> R2Blob[R2 generic blobs\nstores.blobs]
+  Worker --> D1Artifacts[D1 artifacts table\nmetadata index]
+  D1Artifacts --> R2Artifacts[R2 artifact bytes\nartifact blob store]
+```
+
+Cloudflare persistence uses D1 for the shared SQL stores. When `r2` is passed,
+it adds a generic R2-backed `blobs` store and a D1-indexed `artifacts` store
+that can also write byte bodies to R2 for direct artifact saves. When
+`durableObjects` is passed, it adds a Durable Object-backed `locks` store.
+
+The Cloudflare artifact DDL creates:
+
+| Table or object family | Purpose |
+| --- | --- |
+| `artifacts` D1 table | Artifact metadata and run index: `artifact_id`, `run_id`, `thread_id`, `name`, `mime_type`, `size`, `external_url`, `blob_key`, `created_at`, `updated_at`. |
+| R2 artifact bytes | Byte bodies written by direct `ArtifactStore.save({ bytes })` calls and referenced by `artifacts.blob_key`. |
+| R2 generic blobs | Logical `BlobStore` objects for app-owned keys and generated artifact bytes written before saving `ArtifactRecord` metadata. |
+| Durable Object storage | One lock holder per object instance. |
+
+`artifacts.updated_at` is row bookkeeping. It is not exposed as
+`ArtifactRecord.updatedAt`; `ArtifactRecord` exposes `createdAt` plus optional
+bytes or external URL. D1/R2 artifact deletion is not atomic: deleting an
+artifact or a run deletes R2 objects and D1 rows in separate operations, so
+cleanup can be best-effort under partial failure.
+
+Generation artifact persistence writes bytes through `stores.blobs` first, then
+saves an `ArtifactRecord` without inline bytes. Generated artifact refs
+therefore point to blob records and do not depend on `artifacts.blob_key` being
+populated. Direct app calls to `stores.artifacts.save({ bytes })` can still use
+the artifact store byte path and populate `artifacts.blob_key`.
+
+Cloudflare prefix defaults are intentionally split:
+
+| Data | Prefix rule |
+| --- | --- |
+| Generic blobs (`stores.blobs`) | `r2BlobPrefix ?? r2ArtifactPrefix`, then the blob store default when neither is set. |
+| D1-indexed artifact bytes (`stores.artifacts`) | `r2ArtifactPrefix ?? DEFAULT_R2_ARTIFACT_PREFIX`. |
+
+This means an app can set one shared prefix through `r2ArtifactPrefix`, or keep
+generic blobs and artifact bytes separate by setting both prefixes.
+
+## Continue and resume requirements
+
+Use these as operational checks when designing your own backend.
+
+| Flow | Required durable state |
+| --- | --- |
+| Chat replay | `threadId`, `runId`, and opaque `cursor` from the client; run row; public events for that run; messages when the server owns transcript history. |
+| Chat after interrupt | Chat replay state plus pending interrupt records and the client `resume[]` payload that resolves or cancels each pending interrupt. |
+| Generation resume | Lightweight client snapshot plus durable app-owned replay/producer/result state. Artifact refs require artifact records and byte storage. `withGenerationPersistence(...)` updates run status and artifacts, but does not persist generation stream events to `publicEvents` today. |
+| Sandbox resume | Durable sandbox metadata record keyed by the sandbox instance key, plus a reattach-capable provider/harness. Workspace restore also needs metadata manifest records and artifact/file bytes. Multi-worker correctness needs locks. |
+| MCP Apps | Static client registry is enough for stateless per-call reconnect. Stateful or dynamic flows may need durable `McpSessionStore`, metadata, and internal checkpoints. |
+
+## Sanity checks
+
+- The shared SQL schema matches the current store contracts; treat store
+  interfaces as stable and SQL columns as backend details.
+- `public_events` has no cursor column by design.
+- `internal_events` ordering is per `(run_id, namespace)`.
+- `_tanstack_ai_migrations` is bookkeeping for lazy migrations, not part of
+  plain DDL output.
+- Cloudflare `artifacts.updated_at` is not exposed as
+  `ArtifactRecord.updatedAt`.
+- D1/R2 artifact deletion is not atomic.
+- Generation stream events are not persisted to `publicEvents` by
+  `withGenerationPersistence(...)` today.
diff --git a/docs/persistence/mcp-persistence.md b/docs/persistence/mcp-persistence.md
new file mode 100644
index 000000000..49843e5b0
--- /dev/null
+++ b/docs/persistence/mcp-persistence.md
@@ -0,0 +1,135 @@
+---
+title: MCP Persistence
+id: mcp-persistence
+---
+
+Use MCP persistence when your app needs durable MCP session metadata, tool-call
+correlation, and replay/checkpoint events around a chat run. MCP does not add a
+separate base persistence table system. It uses the same `AIPersistence` stores
+as chat, tools, and other integrations.
+
+By the end, you can keep MCP session ids and tool-call state recoverable without
+putting MCP-only schema requirements into every persisted chat app.
+
+## Persist the chat run first
+
+Managed MCP tools run inside `chat()`, so start with the same run durability you
+would use for a normal server-owned chat thread.
+
+```ts
+import {
+  chat,
+  memoryStream,
+  toServerSentEventsResponse,
+} from '@tanstack/ai'
+import { anthropicText } from '@tanstack/ai-anthropic'
+import { createMCPClient } from '@tanstack/ai-mcp'
+import { withChatPersistence } from '@tanstack/ai-persistence'
+import { sqlPersistence } from '@tanstack/ai-persistence-drizzle'
+
+const persistence = sqlPersistence({
+  dialect: 'sqlite',
+  url: 'file:.tanstack-ai/state.sqlite',
+  migrate: true,
+})
+
+const weather = await createMCPClient({
+  transport: { type: 'http', url: 'https://weather.example.com/mcp' },
+})
+
+export async function POST(request: Request) {
+  const { messages, threadId, runId } = await request.json()
+
+  const stream = chat({
+    threadId,
+    runId,
+    adapter: anthropicText('claude-sonnet-4-6'),
+    messages,
+    mcp: { clients: [weather] },
+    middleware: [
+      withChatPersistence(persistence, {
+        features: ['messages', 'metadata'],
+      }),
+    ],
+  })
+
+  return toServerSentEventsResponse(stream, {
+    durability: { adapter: memoryStream(request) },
+  })
+}
+```
+
+MCP-specific state belongs in metadata when your app needs it. Making the
+delivered stream reconnectable is a transport concern — see
+[Delivery Durability](./delivery-durability).
+
+## Store MCP session metadata
+
+Use `stores.metadata` for app-owned correlation such as MCP server ids, session
+ids, OAuth account ids, or last-seen resource versions.
+
+```ts
+import type { AIPersistence } from '@tanstack/ai-persistence'
+
+async function rememberMcpSession(input: {
+  persistence: AIPersistence
+  threadId: string
+  serverId: string
+  sessionId: string
+}) {
+  const metadata = input.persistence.stores.metadata
+
+  if (!metadata) {
+    throw new Error('MCP session persistence requires stores.metadata.')
+  }
+
+  await metadata.set(`thread:${input.threadId}`, `mcp:${input.serverId}`, {
+    sessionId: input.sessionId,
+  })
+}
+```
+
+Keep the value shape owned by your app. TanStack AI only requires the metadata
+store methods; it does not prescribe an MCP session table.
+
+## Store private MCP checkpoints
+
+Use `stores.metadata` for private tool-call or session checkpoints that should
+not surface to the UI. Metadata is app-owned key/value state scoped to a thread
+or run.
+
+```ts
+import type { AIPersistence } from '@tanstack/ai-persistence'
+
+async function recordMcpCheckpoint(input: {
+  persistence: AIPersistence
+  runId: string
+  toolCallId: string
+  serverId: string
+}) {
+  const metadata = input.persistence.stores.metadata
+
+  if (!metadata) {
+    throw new Error('MCP checkpoints require stores.metadata.')
+  }
+
+  await metadata.set(input.runId, `mcp:${input.toolCallId}`, {
+    type: 'tool-call-observed',
+    serverId: input.serverId,
+  })
+}
+```
+
+Use metadata for integration checkpoints and current lookup state.
+
+## Coordinate MCP work across workers
+
+Use `stores.locks` when more than one worker can resume or mutate the same MCP
+session state. Use `stores.blobs` and `stores.artifacts` only when an MCP flow
+produces durable files or media; generated media and file storage still require
+both stores.
+
+For backend choices, use [SQL Backends](./sql-backends), [Prisma](./prisma),
+[Drizzle](./drizzle), or [Cloudflare](./cloudflare). For the full store method
+contract and the `McpSessionStore` boundary, use
+[Persistence Internals](./internals).
diff --git a/docs/persistence/migrations.md b/docs/persistence/migrations.md
new file mode 100644
index 000000000..fa55470b9
--- /dev/null
+++ b/docs/persistence/migrations.md
@@ -0,0 +1,69 @@
+---
+title: Persistence Migrations
+id: migrations
+---
+
+The Drizzle backend owns its schema and migrations through drizzle-kit — there
+is no hand-authored DDL. The default is production-safe: the packaged backend
+does not create tables unless you opt in with `migrate: true` or apply the
+generated migrations through your own workflow.
+
+By the end, you can regenerate migrations after a schema change and know when
+lazy migration is appropriate.
+
+## Use lazy migration only for local development
+
+Pass `migrate: true` when a local or development database should apply the
+bundled migrations on first use.
+
+```ts
+import { sqlPersistence } from '@tanstack/ai-persistence-drizzle'
+
+export const persistence = sqlPersistence({
+  dialect: 'sqlite',
+  url: 'file:./.tanstack-ai/state.sqlite',
+  migrate: true,
+})
+```
+
+For production, leave `migrate` unset, apply the migrations with your own
+pipeline, and deploy them before traffic uses the persistence stores.
+
+## Regenerate the bundled migrations
+
+The schema in `src/schema.ts` is the single source of truth. After changing it,
+regenerate the SQL under `drizzle/` with drizzle-kit:
+
+```sh
+pnpm --filter @tanstack/ai-persistence-drizzle db:generate
+```
+
+This runs `drizzle-kit generate` against the package's `drizzle.config.ts`,
+diffing the schema and emitting a new migration file. Commit the generated
+`drizzle/` output alongside the schema change.
+
+## Bring-your-own migrations
+
+When you construct your own Drizzle database and use `drizzlePersistence(db)`,
+drive migrations from the exported `schema` with your own drizzle-kit config:
+
+```ts
+// drizzle.config.ts
+import { defineConfig } from 'drizzle-kit'
+
+export default defineConfig({
+  dialect: 'sqlite',
+  schema: './node_modules/@tanstack/ai-persistence-drizzle/dist/esm/schema.js',
+  out: './drizzle',
+})
+```
+
+```sh
+pnpm drizzle-kit generate
+pnpm drizzle-kit migrate
+```
+
+Compose the exported tables into your own schema file when you want TanStack AI
+state to live in the same migration history as the rest of your app. See
+[Drizzle](./drizzle) for adapter wiring and [Prisma](./prisma) for the peer
+Prisma backend.
diff --git a/docs/persistence/overview.md b/docs/persistence/overview.md
new file mode 100644
index 000000000..cbd9a80af
--- /dev/null
+++ b/docs/persistence/overview.md
@@ -0,0 +1,158 @@
+---
+title: Persistence Overview
+id: overview
+---
+
+Persistence makes server-side runs durable. TanStack AI splits durability into
+two independent concerns:
+
+- **State durability (this section)** — thread messages, run records,
+  interrupts/approvals, metadata, locks, and generation artifacts. This is a
+  store concern and lives on the **middleware** layer: add
+  `withChatPersistence(...)` to a `chat()` call, or `withGenerationPersistence(...)`
+  to `generateImage` / `generateAudio` / TTS / video / transcription.
+- **Delivery durability (transport)** — a client disconnects, reloads, or opens
+  a second tab and still receives the full ordered stream. This is a *transport*
+  concern, handled by a pluggable delivery sink on the transport helpers
+  (`toServerSentEvents*`), **not** by the persistence middleware. That half is
+  documented separately once the transport delivery layer lands.
+
+The persistence middleware persists **state only**. It never rewrites the chunk
+stream and stamps no cursor — a persisted run produces byte-identical chunks to
+a non-persisted one.
+
+By the end of this section, you can choose the smallest state store your app
+needs, wire it to your server route, and move from local development migrations
+to a production-owned schema.
+
+## How state persistence works
+
+Both middlewares are opt-in. A run without them stays in-memory. A run with
+either middleware calls the stores exposed by your `AIPersistence` object at
+boundaries (load thread on config, save thread + run status on finish, record
+interrupts on pause) — low volume, not per-token.
+
+```ts
+import { chat, toServerSentEventsResponse } from '@tanstack/ai'
+import { anthropicText } from '@tanstack/ai-anthropic'
+import { withChatPersistence } from '@tanstack/ai-persistence'
+import { sqlPersistence } from '@tanstack/ai-persistence-drizzle'
+
+const persistence = sqlPersistence({
+  dialect: 'sqlite',
+  url: 'file:./chat.db',
+  migrate: true,
+})
+
+export async function POST(request: Request) {
+  const { messages, threadId, runId, resume } = await request.json()
+
+  const stream = chat({
+    threadId,
+    runId,
+    resume,
+    adapter: anthropicText('claude-sonnet-4-6'),
+    messages,
+    middleware: [withChatPersistence(persistence)],
+  })
+
+  return toServerSentEventsResponse(stream)
+}
+```
+
+The `resume` array carries AG-UI interrupt responses (approvals, client-tool
+results) for a thread that has pending interrupts — that is state, resolved by
+`withChatPersistence`. Making the *stream itself* replayable across a disconnect
+is a separate transport-layer delivery concern.
+
+### Run IDs must be unique across activities
+
+`withChatPersistence` and `withGenerationPersistence` may share one
+`AIPersistence` backend. The `runs` store is keyed only by `runId` (there is no
+activity discriminator), so **every chat run and every generation run needs a
+distinct `runId`**. Reusing the same id across activities overwrites run status.
+
+How ids are created:
+
+| Path | Default `runId` |
+| --- | --- |
+| Client chat (`useChat` / `ChatClient`) | New `run-${Date.now()}-…` per send; interrupt resume reuses the stored id |
+| Client generation hooks | New `run-${Date.now()}-…` per generate via the generation client |
+| Server `chat({ runId })` | Caller-supplied, or falls back to a per-request `chat-…` id from the engine |
+| Server generation (`generateImage`, …) | Caller-supplied `runId`, else `requestId` for run tracking |
+
+Default client/SDK ids are unique enough for normal use. Only force a shared
+`runId` if you deliberately control identity — and never reuse one id for both
+a chat turn and a media generation. Sharing a **`threadId`** across chat and
+generation for the same conversation is fine.
+
+## What `AIPersistence` contains
+
+`AIPersistence` is an object with optional state stores. Implement only the
+stores your scenario needs, or use a packaged backend that implements them for
+you.
+
+```ts
+import { defineAIPersistence } from '@tanstack/ai-persistence'
+import type {
+  ArtifactStore,
+  BlobStore,
+  InterruptStore,
+  MessageStore,
+  MetadataStore,
+  RunStore,
+} from '@tanstack/ai-persistence'
+import type { LockStore } from '@tanstack/ai'
+
+declare const messages: MessageStore
+declare const runs: RunStore
+declare const interrupts: InterruptStore
+declare const metadata: MetadataStore
+declare const locks: LockStore
+declare const artifacts: ArtifactStore
+declare const blobs: BlobStore
+
+export const persistence = defineAIPersistence({
+  stores: {
+    messages,
+    runs,
+    interrupts,
+    metadata,
+    locks,
+    artifacts,
+    blobs,
+  },
+})
+```
+
+There is no separate high-level callback builder. Production apps usually keep
+their own database, object storage, queues, and retention policies, then expose
+those systems through `AIPersistence` store methods such as
+`messages.loadThread`, `runs.createOrResume`, or `metadata.set`.
+
+## Choose your path
+
+Start with [Persistence Controls](./controls) when you need to decide which
+stores and client options to enable.
+
+Read [Migrations](./migrations) before deploying a packaged backend. Each ORM
+owns its own migrations (drizzle-kit / prisma migrate).
+
+Use the topic pages when you know the feature you are building:
+
+- [Chat Persistence](./chat-persistence) for server-authoritative chat threads
+  and pending human decisions.
+- [Generation Persistence](./generation-persistence) for image, audio, speech,
+  transcription, and video hooks with durable artifact refs.
+- [Sandbox Persistence](./sandbox-persistence) for coding-agent sandboxes,
+  workspace checkpoints, records, and locks.
+- [MCP Persistence](./mcp-persistence) for durable MCP session metadata and
+  tool-call correlation.
+
+Use the adapter pages when you know the infrastructure you are deploying on:
+
+- [Prisma](./prisma) when Prisma owns your database access.
+- [Drizzle](./drizzle) when Drizzle owns your database access.
+- [Custom Stores](./custom-stores) when your app owns the persistence boundary
+  or you are writing an integration.
+- [Persistence Internals](./internals) when you need the exact store contracts.
diff --git a/docs/persistence/prisma.md b/docs/persistence/prisma.md
new file mode 100644
index 000000000..0068d92a9
--- /dev/null
+++ b/docs/persistence/prisma.md
@@ -0,0 +1,192 @@
+---
+title: Persistence with Prisma
+id: prisma
+---
+
+`@tanstack/ai-persistence-prisma` is the Prisma backend for TanStack AI
+**state** persistence. It is **bring-your-own-client**: you add the shipped
+model fragment to your own `schema.prisma`, run `prisma migrate` through your
+normal workflow, then hand the generated `PrismaClient` to
+`prismaPersistence(...)`. It returns the same `AIPersistence` contract consumed
+by `withChatPersistence(...)` and `withGenerationPersistence(...)`.
+
+Prefer [Drizzle](./drizzle) if you want a batteries-included `sqlPersistence`
+with bundled migrations. Reach for Prisma when Prisma already owns your database
+connection and migration workflow.
+
+```sh
+pnpm add @tanstack/ai-persistence @tanstack/ai-persistence-prisma @prisma/client
+pnpm add -D prisma
+```
+
+## Add the models to your schema
+
+Copy the models from this package's `prisma/schema.prisma` into your own Prisma
+schema (or import them if you split your schema across files). The fragment
+defines six models — `Message`, `Run`, `Interrupt`, `Metadata`, `Artifact`, and
+`Blob` — that back the `AIPersistence` state stores:
+
+```prisma
+model Message {
+  threadId     String @id @map("thread_id")
+  messagesJson String @map("messages_json")
+
+  @@map("messages")
+}
+
+model Run {
+  runId      String  @id @map("run_id")
+  threadId   String  @map("thread_id")
+  status     String
+  startedAt  BigInt  @map("started_at")
+  finishedAt BigInt? @map("finished_at")
+  error      String?
+  usageJson  String? @map("usage_json")
+
+  @@map("runs")
+}
+
+model Interrupt {
+  interruptId  String  @id @map("interrupt_id")
+  runId        String  @map("run_id")
+  threadId     String  @map("thread_id")
+  status       String
+  requestedAt  BigInt  @map("requested_at")
+  resolvedAt   BigInt? @map("resolved_at")
+  payloadJson  String  @map("payload_json")
+  responseJson String? @map("response_json")
+
+  @@map("interrupts")
+}
+
+model Metadata {
+  scope     String
+  key       String
+  valueJson String @map("value_json")
+
+  @@id([scope, key])
+  @@map("metadata")
+}
+
+model Artifact {
+  artifactId  String  @id @map("artifact_id")
+  runId       String  @map("run_id")
+  threadId    String  @map("thread_id")
+  name        String
+  mimeType    String  @map("mime_type")
+  size        BigInt
+  externalUrl String? @map("external_url")
+  createdAt   BigInt  @map("created_at")
+
+  @@map("artifacts")
+}
+
+model Blob {
+  key                String  @id
+  contentType        String? @map("content_type")
+  size               BigInt?
+  etag               String?
+  customMetadataJson String? @map("custom_metadata_json")
+  createdAt          BigInt? @map("created_at")
+  updatedAt          BigInt? @map("updated_at")
+  body               Bytes?
+
+  @@map("blobs")
+}
+```
+
+JSON-valued fields are stored in `*_json` `String` (TEXT) columns because
+Prisma's `Json` type is unavailable on SQLite; the adapter serializes and parses
+them for you. Integer columns use `BigInt` so epoch-millisecond timestamps fit
+the full 64-bit range — the adapter converts `bigint` back to `number` at the
+boundary, so the records you read are plain numbers.
+
+## Run the migration
+
+Generate and apply a migration with your normal Prisma workflow:
+
+```sh
+pnpm exec prisma migrate dev --name tanstack_ai_persistence
+```
+
+For production, generate the migration ahead of time and apply it with
+`prisma migrate deploy` from your deployment pipeline.
+
+## Create the persistence object
+
+Pass your generated `PrismaClient` to `prismaPersistence(...)`:
+
+```ts
+import { PrismaClient } from '@prisma/client'
+import { prismaPersistence } from '@tanstack/ai-persistence-prisma'
+import { withChatPersistence } from '@tanstack/ai-persistence'
+
+const prisma = new PrismaClient()
+
+export const persistence = prismaPersistence(prisma)
+export const middleware = withChatPersistence(persistence)
+```
+
+The middleware then flows into your chat handler like any other. On the server:
+
+```ts
+import { chat, toServerSentEventsResponse } from '@tanstack/ai'
+import { openaiText } from '@tanstack/ai-openai'
+import { middleware } from './persistence'
+
+export async function POST(request: Request) {
+  const body: unknown = await request.json()
+  const messages = Array.isArray(body) ? body : []
+
+  const stream = chat({
+    adapter: openaiText('gpt-5.5'),
+    messages,
+    middleware: [middleware],
+  })
+
+  return toServerSentEventsResponse(stream)
+}
+```
+
+## What is persisted
+
+The models mirror the `AIPersistence` state records:
+
+- `Message` — thread message history
+- `Run` — run lifecycle (status, usage, timing)
+- `Interrupt` — interrupts / approvals
+- `Metadata` — scoped key/value metadata
+- `Artifact` — generation artifact references
+- `Blob` — generic blob objects
+
+Delivery durability (resuming an interrupted stream) is a **transport** concern
+and is not stored here. Locks are not part of the SQL schema; an in-memory lock
+is provided as a dev default. Swap in a distributed lock for multi-process
+deployments via [Custom Stores](./custom-stores).
+
+## Keep the Drizzle and Prisma schemas in sync
+
+> **Coupling: `persistence-schema-dual-source`.** The Prisma models above and the
+> Drizzle schema in `@tanstack/ai-persistence-drizzle` describe the **same**
+> state tables and have **no** auto-converter between them. Changing one without
+> the other silently diverges the two backends.
+
+Any change to either schema requires all three of:
+
+1. the sibling schema updated to match, column-for-column;
+2. regenerated migrations for **both** ORMs (`drizzle-kit generate` and
+   `prisma migrate dev`);
+3. the shared conformance suite re-run against memory, Drizzle, and Prisma.
+
+The two schemas stay column-for-column identical: Drizzle's `integer()` columns
+and Prisma's `BigInt` columns are both 64-bit INTEGER-affinity columns in
+SQLite, so the on-disk shape matches.
+
+## Use it across the guides
+
+The same Prisma-backed `AIPersistence` object works across the topic guides:
+
+- [Chat Persistence](./chat-persistence) for server-owned transcripts.
+- [Persistence Controls](./controls) when you need to choose a feature list.
+- [Custom Stores](./custom-stores) when you want Prisma for SQL state but a
+  separate object store for blobs.
diff --git a/docs/persistence/sandbox-persistence.md b/docs/persistence/sandbox-persistence.md
new file mode 100644
index 000000000..5eab9eceb
--- /dev/null
+++ b/docs/persistence/sandbox-persistence.md
@@ -0,0 +1,189 @@
+---
+title: Sandbox Persistence
+id: sandbox-persistence
+---
+
+Use sandbox persistence when a coding-agent harness needs to resume the same
+sandbox across processes, restore workspace files, or coordinate work across
+workers. Add `withChatPersistence(...)` before `withSandbox(...)`; the sandbox
+middleware reads optional persistence capabilities directly.
+
+By the end, your sandbox run has durable records, optional locks, and optional
+workspace checkpoints backed by the same persistence stores as chat.
+
+## Install
+
+Install the sandbox package, persistence package, and the persistence backend
+you already use for durable chat runs:
+
+```sh
+pnpm add @tanstack/ai-sandbox @tanstack/ai-persistence @tanstack/ai-persistence-drizzle
+```
+
+## Persist sandbox identity
+
+Sandbox identity persistence answers "which sandbox should this run use?" It
+stores a sandbox record keyed by thread, sandbox id, provider, workspace, and
+tenant.
+
+```ts
+import { chat } from '@tanstack/ai'
+import { claudeCodeText } from '@tanstack/ai-claude-code'
+import { withChatPersistence } from '@tanstack/ai-persistence'
+import { sqlPersistence } from '@tanstack/ai-persistence-drizzle'
+import { defineSandbox, withSandbox } from '@tanstack/ai-sandbox'
+import { dockerSandbox } from '@tanstack/ai-sandbox-docker'
+import type { ModelMessage } from '@tanstack/ai'
+
+const persistence = sqlPersistence({
+  dialect: 'sqlite',
+  url: 'file:.tanstack-ai/state.sqlite',
+  migrate: true,
+})
+
+const repoSandbox = defineSandbox({
+  id: 'repo-agent',
+  provider: dockerSandbox({ image: 'node:22' }),
+})
+
+const messages: Array<ModelMessage> = [
+  { role: 'user', content: 'Resume this repository task.' },
+]
+
+chat({
+  threadId: 'thread-123',
+  runId: 'run-123',
+  adapter: claudeCodeText('claude-sonnet-4-6'),
+  messages,
+  middleware: [withChatPersistence(persistence), withSandbox(repoSandbox)],
+})
+```
+
+`withSandbox(...)` prefers an explicit sandbox store capability when one is
+provided. Otherwise, when `withChatPersistence(...)` is earlier in the middleware
+array and its backend exposes `stores.metadata`, sandbox records are stored in
+persistence metadata. If the backend exposes `stores.locks`,
+`withChatPersistence(...)` also provides the shared lock capability that sandbox
+ensure uses to serialize resume/create work.
+
+## Add locks for multi-worker resume
+
+Sandbox resume needs two shared pieces of state:
+
+- a sandbox record keyed by thread, sandbox id, provider, workspace, and tenant
+- a lock for the same key so two workers do not create competing sandboxes
+
+Without a durable lock, two workers may try to ensure the same sandbox at the
+same time. Without persistence metadata, resume only works inside the process
+that still has the in-memory sandbox record.
+
+The batteries-included backends ship an in-memory lock (dev default). For
+multi-worker deployments, provide a distributed lock store — a Durable Object
+lock on Cloudflare (see [Cloudflare persistence](./cloudflare)), or another
+backend-specific lock on Node — when more than one process can resume the same
+sandbox key.
+
+## Persist workspace files
+
+Workspace persistence answers "which files should be restored if the sandbox
+filesystem is gone?" It uses `stores.metadata` for the workspace manifest,
+`stores.artifacts` for file records, `stores.blobs` for file bytes, and usually
+`stores.locks` for multi-worker updates.
+
+```ts ignore
+import { chat } from '@tanstack/ai'
+import { claudeCodeText } from '@tanstack/ai-claude-code'
+import { drizzlePersistence } from '@tanstack/ai-persistence-drizzle'
+import { withChatPersistence } from '@tanstack/ai-persistence'
+import { drizzle } from 'drizzle-orm/d1'
+import {
+  defineSandbox,
+  defineWorkspace,
+  withSandbox,
+} from '@tanstack/ai-sandbox'
+import { cloudflareSandbox, type Sandbox } from '@tanstack/ai-sandbox-cloudflare'
+
+interface Env {
+  AI_D1: D1Database
+  Sandbox: DurableObjectNamespace<Sandbox>
+}
+
+export function runProjectBuilder(env: Env) {
+  // D1 is SQLite-compatible, so the Drizzle D1 adapter satisfies the state
+  // store contract. Run migrations from the exported schema via drizzle-kit.
+  const persistence = drizzlePersistence(drizzle(env.AI_D1))
+
+  const projectSandbox = defineSandbox({
+    id: 'project-builder',
+    provider: cloudflareSandbox({ binding: env.Sandbox }),
+    workspace: defineWorkspace({
+      source: { type: 'none' },
+      root: '/workspace',
+    }),
+    lifecycle: {
+      reuse: 'thread',
+      destroyOnComplete: false,
+    },
+    persistence: {
+      workspace: {
+        key: 'project-123',
+        root: '/workspace',
+        exclude: ['**/.turbo/**', '**/coverage/**'],
+        maxFileBytes: 10 * 1024 * 1024,
+        consistency: 'strict',
+      },
+    },
+  })
+
+  return chat({
+    threadId: 'thread-123',
+    runId: 'run-123',
+    adapter: claudeCodeText('claude-sonnet-4-6'),
+    messages: [{ role: 'user', content: 'Build the app.' }],
+    middleware: [
+      withChatPersistence(persistence, {
+        features: ['messages', 'metadata', 'artifacts', 'blobs', 'locks'],
+      }),
+      withSandbox(projectSandbox),
+    ],
+  })
+}
+```
+
+When a watched file changes, `withSandbox(...)` reads exact bytes from the
+sandbox filesystem, saves them as artifacts, and updates a workspace manifest in
+metadata. On the next run, it restores the manifest before `hooks.onReady` runs.
+
+## Choose workspace options
+
+Set `persistence.workspace` to `true` for defaults, or pass an object for
+project-specific control.
+
+| Option | Default | Purpose |
+| --- | --- | --- |
+| `key` | sandbox instance key | Stable project/workspace identity. |
+| `root` | `workspace.root` or `/workspace` | Files under this root are restored and checkpointed. |
+| `include` | all files under `root` | Optional allow-list of glob-like patterns. |
+| `exclude` | `node_modules`, `.git`, `dist`, `build`, `.cache`, `.env*` | Extra patterns to skip. |
+| `maxFileBytes` | `10 * 1024 * 1024` | Per-file safety limit. |
+| `consistency` | `'strict'` | `'strict'` fails the run on persistence errors; `'best-effort'` swallows checkpoint and restore failures. |
+
+Set workspace persistence to `false` or omit it when the provider already owns
+durable filesystem state and you do not want TanStack AI to copy workspace
+files.
+
+## Understand the boundaries
+
+Persistence replay and sandbox resume are separate pieces that work together.
+`withChatPersistence(...)` replays the public event tail for the chat client. The
+sandbox record lets `withSandbox(...)` find the same provider sandbox. A harness
+adapter that supports reattach can then reconnect to the still-running agent
+process and continue live after replay.
+
+Workspace persistence is a checkpointing layer, not a source-control system. It
+stores the latest durable contents for matching files and delete tombstones for
+removed files. If your app needs history, branching, conflict resolution, or
+garbage collection policies, store additional project metadata and artifacts
+under your own keys. For the sandbox record, workspace manifest, lock, and
+artifact-store contracts behind this flow, see
+[Persistence Internals](./internals).
diff --git a/docs/persistence/sql-backends.md b/docs/persistence/sql-backends.md
new file mode 100644
index 000000000..320444fad
--- /dev/null
+++ b/docs/persistence/sql-backends.md
@@ -0,0 +1,87 @@
+---
+title: SQL Backends
+id: sql-backends
+---
+
+Use a SQL backend when your app runs in Node or another server runtime with a
+database connection. TanStack AI ships a single, Drizzle-backed SQL backend —
+`@tanstack/ai-persistence-drizzle` — that exposes the `AIPersistence` state
+stores to `withChatPersistence(...)` and `withGenerationPersistence(...)`.
+
+There are two entry points, both returning the same contract:
+
+- `sqlPersistence({ dialect, url, migrate })` — batteries-included: builds the
+  database and applies the bundled migrations.
+- `drizzlePersistence(db)` — bring your own Drizzle database and migration
+  workflow, driven by the exported `schema`.
+
+```sh
+pnpm add @tanstack/ai-persistence @tanstack/ai-persistence-drizzle drizzle-orm
+```
+
+## Batteries-included
+
+The `sqlite` dialect ships pre-generated migrations, so a fresh database can
+create its tables on first use with `migrate: true`.
+
+```ts
+import { sqlPersistence } from '@tanstack/ai-persistence-drizzle'
+
+export const persistence = sqlPersistence({
+  dialect: 'sqlite',
+  url: 'file:./.tanstack-ai/state.sqlite',
+  migrate: true,
+})
+```
+
+Use `url: ':memory:'` for tests. For production, generate and review the
+migrations ahead of time and deploy them before traffic reaches the persistence
+stores; leave `migrate` unset so tables are not created lazily at runtime.
+
+## Bring your own Drizzle database
+
+When Drizzle already owns your database access, pass your `db`. This works with
+any Drizzle sqlite driver (`better-sqlite3`, `libsql`/Turso, D1, `node:sqlite`).
+
+```ts ignore
+import { drizzle } from 'drizzle-orm/better-sqlite3'
+import Database from 'better-sqlite3'
+import { drizzlePersistence, schema } from '@tanstack/ai-persistence-drizzle'
+
+const db = drizzle(new Database('state.sqlite'), { schema })
+
+export const persistence = drizzlePersistence(db)
+```
+
+See [Drizzle](./drizzle) for the full adapter guide and [Migrations](./migrations)
+for the drizzle-kit workflow.
+
+## Schema
+
+The schema mirrors the `AIPersistence` state records column-for-column:
+
+- `messages`
+- `runs`
+- `interrupts`
+- `metadata`
+- `artifacts`
+- `blobs`
+
+Delivery durability (replaying an interrupted stream) is a transport concern and
+is not stored in these tables. Locks are not part of the SQL schema; an
+in-memory lock is provided as a dev default — see [Custom Stores](./custom-stores)
+to plug in a distributed lock.
+
+## Other dialects
+
+`sqlPersistence` bundles the `sqlite` dialect. For `postgres` or `mysql`,
+construct a Drizzle database with your own driver and use `drizzlePersistence(db)`,
+generating migrations from the exported `schema` with drizzle-kit. Prisma users
+can use [Prisma](./prisma) as a peer backend.
+
+## Choosing a backend
+
+Use `sqlPersistence` with sqlite when one process owns the database file or for
+local development. Use `drizzlePersistence(db)` when Drizzle already owns your
+database connection — including Postgres, MySQL, libsql/Turso, or D1 — and you
+manage migrations yourself.
diff --git a/docs/sandbox/lifecycle.md b/docs/sandbox/lifecycle.md
index 4ccde4afd..d1286b7af 100644
--- a/docs/sandbox/lifecycle.md
+++ b/docs/sandbox/lifecycle.md
@@ -115,3 +115,8 @@ Providers without durable disk or snapshots (e.g. ephemeral containers)
 re-create and re-bootstrap under the same identity: the `sandboxInstanceKey`
 stays stable, but every run pays the bootstrap cost because there is nothing
 durable to resume.
+
+To make sandbox resume records and ensure-locking durable across processes,
+place `withChatPersistence(...)` before `withSandbox(...)`. The sandbox middleware
+reads persistence metadata and locks directly when those stores are configured.
+See [Sandbox Persistence](../persistence/sandbox-persistence).
diff --git a/docs/sandbox/overview.md b/docs/sandbox/overview.md
index 52adcf8ba..ca92197d5 100644
--- a/docs/sandbox/overview.md
+++ b/docs/sandbox/overview.md
@@ -116,6 +116,8 @@ sandbox on your laptop. Then dive into the piece you need:
 - **[Lifecycle & Snapshots](./lifecycle)** — reuse, snapshot-after-setup, and resume.
 - **[Events & File Hooks](./events)** — stream the agent's edits and activity to a UI.
 - **[Cloudflare (edge)](./cloudflare)** — run the agent and a live preview at the edge.
+- **[Sandbox Persistence](../persistence/sandbox-persistence)** — persist sandbox run records,
+  resume bookkeeping, and locks across processes.
 
 ## Try it
 
@@ -133,7 +135,8 @@ hands back a live preview URL, see `examples/sandbox-web` — one app with harne
 (Claude Code / Codex / OpenCode / Grok) and provider (Docker / local / Vercel /
 Daytona) pickers.
 
-> **Persistence-ready:** the sandbox layer ships with in-memory stores for
-> resume bookkeeping. A future persistence package can provide durable
-> `SandboxStore` / `LockStore` implementations (and event-log replay) by
-> supplying those optional capabilities — no changes to the sandbox layer.
+> **Durable sandbox runs:** the sandbox layer ships with in-memory stores for
+> local resume bookkeeping. Use
+> [Sandbox Persistence](../persistence/sandbox-persistence) when resume records, locks, and
+> event-log replay need to survive process restarts or run across multiple
+> workers.
diff --git a/docs/tools/tool-approval.md b/docs/tools/tool-approval.md
index 1d87a3ff8..f36b73407 100644
--- a/docs/tools/tool-approval.md
+++ b/docs/tools/tool-approval.md
@@ -23,6 +23,11 @@ The tool approval flow allows you to require user approval before executing sens
 
 After `approval-responded` the call executes (if approved). Although `complete` exists in the `ToolCallState` union, the runtime never transitions the tool-call part to it — the result surfaces as a populated `part.output` plus a sibling `tool-result` part whose own state is `complete` or `error`.
 
+For approval flows that must survive disconnects, reloads, or process restarts,
+pair approvals with server persistence. See
+[Chat Persistence](../persistence/chat-persistence) for the
+durable `withChatPersistence` path.
+
 When a tool requires approval, the typical flow is:
 
 1. Model calls the tool
diff --git a/examples/ts-react-chat/.env.example b/examples/ts-react-chat/.env.example
index 90fab331c..a230d9199 100644
--- a/examples/ts-react-chat/.env.example
+++ b/examples/ts-react-chat/.env.example
@@ -2,6 +2,15 @@
 # Get yours at: https://platform.openai.com/api-keys
 OPENAI_API_KEY=
 
+# MySQL persistence demo (/mysql-persistence)
+# Use MYSQL_URL or the individual MYSQL_* settings below.
+# MYSQL_URL=mysql://root:password@127.0.0.1:3306/tanstack_ai_chat
+MYSQL_HOST=127.0.0.1
+MYSQL_PORT=3306
+MYSQL_USER=root
+MYSQL_PASSWORD=
+MYSQL_DATABASE=tanstack_ai_chat
+
 # Anthropic API Key (chat)
 # Get yours at: https://console.anthropic.com/settings/keys
 ANTHROPIC_API_KEY=
diff --git a/examples/ts-react-chat/README.md b/examples/ts-react-chat/README.md
index 1a07c1533..17a852ed0 100644
--- a/examples/ts-react-chat/README.md
+++ b/examples/ts-react-chat/README.md
@@ -37,8 +37,26 @@ An example chat application built with TanStack Start, TanStack Store, and **Tan
 
 ```env
 OPENAI_API_KEY=your_openai_api_key
+MYSQL_URL=mysql://root:password@127.0.0.1:3306/tanstack_ai_chat
 ```
 
+## MySQL Persistence Demo
+
+The `/mysql-persistence` route demonstrates durable chat resume with MySQL.
+Create a database, set either `MYSQL_URL` or the individual `MYSQL_HOST`,
+`MYSQL_PORT`, `MYSQL_USER`, `MYSQL_PASSWORD`, and `MYSQL_DATABASE` variables,
+then run the app and open `/mysql-persistence`.
+
+```sql
+CREATE DATABASE tanstack_ai_chat;
+```
+
+The example stores messages, durable replay events, and interrupts through
+`@tanstack/ai-persistence-sql`. Refresh while a response is streaming to
+continue tailing the in-progress run from MySQL within the same dev/server
+process. Reattaching to a producer after restarting the server process is out
+of scope for this example.
+
 ## Trying Out Lazy Tool Discovery
 
 This example includes three **lazy tools** — tools that are not sent to the LLM upfront. Instead, the LLM sees a `__lazy__tool__discovery__` tool that lists their names. When the LLM needs one, it discovers it first (getting the full description and schema), then calls it normally.
@@ -78,7 +96,7 @@ The lazy tools are: `compareGuitars`, `calculateFinancing`, and `searchGuitars`.
 
 ### AI Capabilities
 
-- 🤖 Powered by **TanStack AI** with OpenAI GPT-4o
+- 🤖 Powered by **TanStack AI** with OpenAI `gpt-5.5`
 - 📝 Rich markdown formatting with syntax highlighting
 - 🎯 Customizable system prompts for tailored AI behavior
 - 🔄 Real-time streaming responses with Server-Sent Events
@@ -107,7 +125,7 @@ The lazy tools are: `compareGuitars`, `calculateFinancing`, and `searchGuitars`.
 - **Routing**: TanStack Router
 - **State Management**: TanStack Store
 - **Styling**: Tailwind CSS
-- **AI Integration**: TanStack AI with OpenAI GPT-4o
+- **AI Integration**: TanStack AI with OpenAI `gpt-5.5`
 - **Chat Client**: `@tanstack/ai-react` with connection adapters
 - **Streaming**: Server-Sent Events via `fetchServerSentEvents`
 - **Tool Execution**: Automatic loop with `ToolCallManager`
diff --git a/examples/ts-react-chat/package.json b/examples/ts-react-chat/package.json
index 67b58ad43..e13e03e6c 100644
--- a/examples/ts-react-chat/package.json
+++ b/examples/ts-react-chat/package.json
@@ -34,6 +34,8 @@
     "@tanstack/ai-openai": "workspace:*",
     "@tanstack/ai-opencode": "workspace:*",
     "@tanstack/ai-openrouter": "workspace:*",
+    "@tanstack/ai-persistence": "workspace:*",
+    "@tanstack/ai-persistence-drizzle": "workspace:*",
     "@tanstack/ai-react": "workspace:*",
     "@tanstack/ai-react-ui": "workspace:*",
     "@tanstack/ai-sandbox": "workspace:*",
diff --git a/examples/ts-react-chat/src/components/Header.tsx b/examples/ts-react-chat/src/components/Header.tsx
index e7fbc6a0a..2f4757619 100644
--- a/examples/ts-react-chat/src/components/Header.tsx
+++ b/examples/ts-react-chat/src/components/Header.tsx
@@ -5,6 +5,7 @@ import {
   Activity,
   BadgeCheck,
   Braces,
+  Database,
   FileAudio,
   FileText,
   Guitar,
@@ -231,6 +232,19 @@ export default function Header() {
             <span className="font-medium">Persistent Chats</span>
           </Link>
 
+          <Link
+            to="/mysql-persistence"
+            onClick={() => setIsOpen(false)}
+            className="flex items-center gap-3 p-3 rounded-lg hover:bg-gray-800 transition-colors mb-2"
+            activeProps={{
+              className:
+                'flex items-center gap-3 p-3 rounded-lg bg-cyan-600 hover:bg-cyan-700 transition-colors mb-2',
+            }}
+          >
+            <Database size={20} />
+            <span className="font-medium">MySQL Persistence</span>
+          </Link>
+
           <Link
             to="/example/runtime-context"
             onClick={() => setIsOpen(false)}
diff --git a/examples/ts-react-chat/src/lib/mysql-persistence.ts b/examples/ts-react-chat/src/lib/mysql-persistence.ts
new file mode 100644
index 000000000..e6f425b06
--- /dev/null
+++ b/examples/ts-react-chat/src/lib/mysql-persistence.ts
@@ -0,0 +1,23 @@
+import { sqlPersistence } from '@tanstack/ai-persistence-drizzle'
+import type { AIPersistence } from '@tanstack/ai-persistence'
+
+/**
+ * Durable **state** persistence for the persistent-chat demo.
+ *
+ * Persistence v2 ships a batteries-included SQLite backend (Drizzle + bundled
+ * migrations) via {@link sqlPersistence}. The former hand-rolled MySQL
+ * `SqlDriver` was removed — for Postgres/MySQL, construct your own Drizzle `db`
+ * and use `drizzlePersistence(db)` with migrations generated from the exported
+ * schema. Delivery durability (disconnect → reconnect → ordered resume) is a
+ * separate transport concern handled by `toServerSentEvents(stream, { durability: { adapter } })`.
+ */
+let persistence: AIPersistence | undefined
+
+export function createChatPersistence(): AIPersistence {
+  persistence ??= sqlPersistence({
+    dialect: 'sqlite',
+    url: process.env.CHAT_DB_URL ?? 'file:./chat-persistence-demo.db',
+    migrate: true,
+  })
+  return persistence
+}
diff --git a/examples/ts-react-chat/src/lib/server-fns.ts b/examples/ts-react-chat/src/lib/server-fns.ts
index 1c8109be4..4a255cc04 100644
--- a/examples/ts-react-chat/src/lib/server-fns.ts
+++ b/examples/ts-react-chat/src/lib/server-fns.ts
@@ -2,6 +2,8 @@ import { createServerFn } from '@tanstack/react-start'
 import { z } from 'zod'
 import {
   chat,
+  createImageOptions,
+  createVideoOptions,
   generateAudio,
   generateImage,
   generateSpeech,
@@ -17,7 +19,6 @@ import {
   openaiText,
   openaiVideo,
 } from '@tanstack/ai-openai'
-import type { UIMessage } from '@tanstack/ai'
 import {
   InvalidModelOverrideError,
   UnknownProviderError,
@@ -25,6 +26,8 @@ import {
   buildSpeechAdapter,
   buildTranscriptionAdapter,
 } from './server-audio-adapters'
+import type { OpenAIChatModel } from '@tanstack/ai-openai'
+import type { UIMessage } from '@tanstack/ai'
 
 /**
  * Server-fn error with a stable `code` property clients can switch on.
@@ -95,6 +98,14 @@ const AUDIO_PROVIDER_SCHEMA = z
   ])
   .optional()
 
+const OPENAI_IMAGE_SIZE_SCHEMA = z
+  .enum(['1024x1024', '1536x1024', '1024x1536', 'auto'])
+  .optional()
+
+const OPENAI_VIDEO_SIZE_SCHEMA = z
+  .enum(['1280x720', '720x1280', '1792x1024', '1024x1792'])
+  .optional()
+
 // =============================================================================
 // Direct server functions (non-streaming, return the result directly)
 // =============================================================================
@@ -104,7 +115,7 @@ export const generateImageFn = createServerFn({ method: 'POST' })
     z.object({
       prompt: z.string(),
       numberOfImages: z.number().optional(),
-      size: z.string().optional(),
+      size: OPENAI_IMAGE_SIZE_SCHEMA,
     }),
   )
   .handler(async ({ data }) => {
@@ -112,7 +123,7 @@ export const generateImageFn = createServerFn({ method: 'POST' })
       adapter: openaiImage('gpt-image-1'),
       prompt: data.prompt,
       numberOfImages: data.numberOfImages,
-      size: data.size as any,
+      size: data.size,
     })
   })
 
@@ -211,7 +222,7 @@ export const summarizeFn = createServerFn({ method: 'POST' })
   )
   .handler(async ({ data }) => {
     return summarize({
-      adapter: openaiSummarize((data.model ?? 'gpt-4o-mini') as 'gpt-4o-mini'),
+      adapter: openaiSummarize((data.model ?? 'gpt-5.5') as OpenAIChatModel),
       text: data.text,
       maxLength: data.maxLength,
       style: data.style,
@@ -222,7 +233,7 @@ export const generateVideoFn = createServerFn({ method: 'POST' })
   .inputValidator(
     z.object({
       prompt: z.string(),
-      size: z.string().optional(),
+      size: OPENAI_VIDEO_SIZE_SCHEMA,
       duration: z.number().optional(),
     }),
   )
@@ -233,7 +244,7 @@ export const generateVideoFn = createServerFn({ method: 'POST' })
     const { jobId } = await generateVideo({
       adapter,
       prompt: data.prompt,
-      size: data.size as any,
+      size: data.size,
       duration: data.duration,
     })
 
@@ -274,18 +285,20 @@ export const generateImageStreamFn = createServerFn({ method: 'POST' })
     z.object({
       prompt: z.string(),
       numberOfImages: z.number().optional(),
-      size: z.string().optional(),
+      size: OPENAI_IMAGE_SIZE_SCHEMA,
     }),
   )
   .handler(({ data }) => {
     return toServerSentEventsResponse(
-      generateImage({
-        adapter: openaiImage('gpt-image-1'),
-        prompt: data.prompt,
-        numberOfImages: data.numberOfImages,
-        size: data.size as any,
-        stream: true,
-      }),
+      generateImage<ReturnType<typeof openaiImage>, true>(
+        createImageOptions({
+          adapter: openaiImage('gpt-image-1'),
+          prompt: data.prompt,
+          numberOfImages: data.numberOfImages,
+          size: data.size,
+          stream: true,
+        }),
+      ),
     )
   })
 
@@ -364,9 +377,7 @@ export const summarizeStreamFn = createServerFn({ method: 'POST' })
   .handler(({ data }) => {
     return toServerSentEventsResponse(
       summarize({
-        adapter: openaiSummarize(
-          (data.model ?? 'gpt-4o-mini') as 'gpt-4o-mini',
-        ),
+        adapter: openaiSummarize((data.model ?? 'gpt-5.5') as OpenAIChatModel),
         text: data.text,
         maxLength: data.maxLength,
         style: data.style,
@@ -379,19 +390,21 @@ export const generateVideoStreamFn = createServerFn({ method: 'POST' })
   .inputValidator(
     z.object({
       prompt: z.string(),
-      size: z.string().optional(),
+      size: OPENAI_VIDEO_SIZE_SCHEMA,
       duration: z.number().optional(),
     }),
   )
   .handler(({ data }) => {
     return toServerSentEventsResponse(
-      generateVideo({
-        adapter: openaiVideo('sora-2'),
-        prompt: data.prompt,
-        size: data.size as any,
-        duration: data.duration,
-        stream: true,
-      }),
+      generateVideo<ReturnType<typeof openaiVideo>, true>(
+        createVideoOptions({
+          adapter: openaiVideo('sora-2'),
+          prompt: data.prompt,
+          size: data.size,
+          duration: data.duration,
+          stream: true,
+        }),
+      ),
     )
   })
 
diff --git a/examples/ts-react-chat/src/routeTree.gen.ts b/examples/ts-react-chat/src/routeTree.gen.ts
index 69a7764a2..03ad53861 100644
--- a/examples/ts-react-chat/src/routeTree.gen.ts
+++ b/examples/ts-react-chat/src/routeTree.gen.ts
@@ -13,6 +13,7 @@ import { Route as ThreadsRouteImport } from './routes/threads'
 import { Route as ServerFnChatRouteImport } from './routes/server-fn-chat'
 import { Route as SandboxesRouteImport } from './routes/sandboxes'
 import { Route as RealtimeRouteImport } from './routes/realtime'
+import { Route as MysqlPersistenceRouteImport } from './routes/mysql-persistence'
 import { Route as McpDemoRouteImport } from './routes/mcp-demo'
 import { Route as McpAppsRouteImport } from './routes/mcp-apps'
 import { Route as Issue176ToolResultRouteImport } from './routes/issue-176-tool-result'
@@ -36,6 +37,7 @@ import { Route as ApiSummarizeRouteImport } from './routes/api.summarize'
 import { Route as ApiStructuredOutputRouteImport } from './routes/api.structured-output'
 import { Route as ApiStructuredChatRouteImport } from './routes/api.structured-chat'
 import { Route as ApiSandboxTriageRouteImport } from './routes/api.sandbox-triage'
+import { Route as ApiMysqlPersistentChatRouteImport } from './routes/api.mysql-persistent-chat'
 import { Route as ApiMcpStatusRouteImport } from './routes/api.mcp-status'
 import { Route as ApiMcpPoolRouteImport } from './routes/api.mcp-pool'
 import { Route as ApiMcpManualRouteImport } from './routes/api.mcp-manual'
@@ -74,6 +76,11 @@ const RealtimeRoute = RealtimeRouteImport.update({
   path: '/realtime',
   getParentRoute: () => rootRouteImport,
 } as any)
+const MysqlPersistenceRoute = MysqlPersistenceRouteImport.update({
+  id: '/mysql-persistence',
+  path: '/mysql-persistence',
+  getParentRoute: () => rootRouteImport,
+} as any)
 const McpDemoRoute = McpDemoRouteImport.update({
   id: '/mcp-demo',
   path: '/mcp-demo',
@@ -192,6 +199,11 @@ const ApiSandboxTriageRoute = ApiSandboxTriageRouteImport.update({
   path: '/api/sandbox-triage',
   getParentRoute: () => rootRouteImport,
 } as any)
+const ApiMysqlPersistentChatRoute = ApiMysqlPersistentChatRouteImport.update({
+  id: '/api/mysql-persistent-chat',
+  path: '/api/mysql-persistent-chat',
+  getParentRoute: () => rootRouteImport,
+} as any)
 const ApiMcpStatusRoute = ApiMcpStatusRouteImport.update({
   id: '/api/mcp-status',
   path: '/api/mcp-status',
@@ -287,6 +299,7 @@ export interface FileRoutesByFullPath {
   '/issue-176-tool-result': typeof Issue176ToolResultRoute
   '/mcp-apps': typeof McpAppsRoute
   '/mcp-demo': typeof McpDemoRoute
+  '/mysql-persistence': typeof MysqlPersistenceRoute
   '/realtime': typeof RealtimeRoute
   '/sandboxes': typeof SandboxesRoute
   '/server-fn-chat': typeof ServerFnChatRoute
@@ -302,6 +315,7 @@ export interface FileRoutesByFullPath {
   '/api/mcp-manual': typeof ApiMcpManualRoute
   '/api/mcp-pool': typeof ApiMcpPoolRoute
   '/api/mcp-status': typeof ApiMcpStatusRoute
+  '/api/mysql-persistent-chat': typeof ApiMysqlPersistentChatRoute
   '/api/sandbox-triage': typeof ApiSandboxTriageRoute
   '/api/structured-chat': typeof ApiStructuredChatRoute
   '/api/structured-output': typeof ApiStructuredOutputRoute
@@ -333,6 +347,7 @@ export interface FileRoutesByTo {
   '/issue-176-tool-result': typeof Issue176ToolResultRoute
   '/mcp-apps': typeof McpAppsRoute
   '/mcp-demo': typeof McpDemoRoute
+  '/mysql-persistence': typeof MysqlPersistenceRoute
   '/realtime': typeof RealtimeRoute
   '/sandboxes': typeof SandboxesRoute
   '/server-fn-chat': typeof ServerFnChatRoute
@@ -348,6 +363,7 @@ export interface FileRoutesByTo {
   '/api/mcp-manual': typeof ApiMcpManualRoute
   '/api/mcp-pool': typeof ApiMcpPoolRoute
   '/api/mcp-status': typeof ApiMcpStatusRoute
+  '/api/mysql-persistent-chat': typeof ApiMysqlPersistentChatRoute
   '/api/sandbox-triage': typeof ApiSandboxTriageRoute
   '/api/structured-chat': typeof ApiStructuredChatRoute
   '/api/structured-output': typeof ApiStructuredOutputRoute
@@ -380,6 +396,7 @@ export interface FileRoutesById {
   '/issue-176-tool-result': typeof Issue176ToolResultRoute
   '/mcp-apps': typeof McpAppsRoute
   '/mcp-demo': typeof McpDemoRoute
+  '/mysql-persistence': typeof MysqlPersistenceRoute
   '/realtime': typeof RealtimeRoute
   '/sandboxes': typeof SandboxesRoute
   '/server-fn-chat': typeof ServerFnChatRoute
@@ -395,6 +412,7 @@ export interface FileRoutesById {
   '/api/mcp-manual': typeof ApiMcpManualRoute
   '/api/mcp-pool': typeof ApiMcpPoolRoute
   '/api/mcp-status': typeof ApiMcpStatusRoute
+  '/api/mysql-persistent-chat': typeof ApiMysqlPersistentChatRoute
   '/api/sandbox-triage': typeof ApiSandboxTriageRoute
   '/api/structured-chat': typeof ApiStructuredChatRoute
   '/api/structured-output': typeof ApiStructuredOutputRoute
@@ -428,6 +446,7 @@ export interface FileRouteTypes {
     | '/issue-176-tool-result'
     | '/mcp-apps'
     | '/mcp-demo'
+    | '/mysql-persistence'
     | '/realtime'
     | '/sandboxes'
     | '/server-fn-chat'
@@ -443,6 +462,7 @@ export interface FileRouteTypes {
     | '/api/mcp-manual'
     | '/api/mcp-pool'
     | '/api/mcp-status'
+    | '/api/mysql-persistent-chat'
     | '/api/sandbox-triage'
     | '/api/structured-chat'
     | '/api/structured-output'
@@ -474,6 +494,7 @@ export interface FileRouteTypes {
     | '/issue-176-tool-result'
     | '/mcp-apps'
     | '/mcp-demo'
+    | '/mysql-persistence'
     | '/realtime'
     | '/sandboxes'
     | '/server-fn-chat'
@@ -489,6 +510,7 @@ export interface FileRouteTypes {
     | '/api/mcp-manual'
     | '/api/mcp-pool'
     | '/api/mcp-status'
+    | '/api/mysql-persistent-chat'
     | '/api/sandbox-triage'
     | '/api/structured-chat'
     | '/api/structured-output'
@@ -520,6 +542,7 @@ export interface FileRouteTypes {
     | '/issue-176-tool-result'
     | '/mcp-apps'
     | '/mcp-demo'
+    | '/mysql-persistence'
     | '/realtime'
     | '/sandboxes'
     | '/server-fn-chat'
@@ -535,6 +558,7 @@ export interface FileRouteTypes {
     | '/api/mcp-manual'
     | '/api/mcp-pool'
     | '/api/mcp-status'
+    | '/api/mysql-persistent-chat'
     | '/api/sandbox-triage'
     | '/api/structured-chat'
     | '/api/structured-output'
@@ -567,6 +591,7 @@ export interface RootRouteChildren {
   Issue176ToolResultRoute: typeof Issue176ToolResultRoute
   McpAppsRoute: typeof McpAppsRoute
   McpDemoRoute: typeof McpDemoRoute
+  MysqlPersistenceRoute: typeof MysqlPersistenceRoute
   RealtimeRoute: typeof RealtimeRoute
   SandboxesRoute: typeof SandboxesRoute
   ServerFnChatRoute: typeof ServerFnChatRoute
@@ -582,6 +607,7 @@ export interface RootRouteChildren {
   ApiMcpManualRoute: typeof ApiMcpManualRoute
   ApiMcpPoolRoute: typeof ApiMcpPoolRoute
   ApiMcpStatusRoute: typeof ApiMcpStatusRoute
+  ApiMysqlPersistentChatRoute: typeof ApiMysqlPersistentChatRoute
   ApiSandboxTriageRoute: typeof ApiSandboxTriageRoute
   ApiStructuredChatRoute: typeof ApiStructuredChatRoute
   ApiStructuredOutputRoute: typeof ApiStructuredOutputRoute
@@ -635,6 +661,13 @@ declare module '@tanstack/react-router' {
       preLoaderRoute: typeof RealtimeRouteImport
       parentRoute: typeof rootRouteImport
     }
+    '/mysql-persistence': {
+      id: '/mysql-persistence'
+      path: '/mysql-persistence'
+      fullPath: '/mysql-persistence'
+      preLoaderRoute: typeof MysqlPersistenceRouteImport
+      parentRoute: typeof rootRouteImport
+    }
     '/mcp-demo': {
       id: '/mcp-demo'
       path: '/mcp-demo'
@@ -796,6 +829,13 @@ declare module '@tanstack/react-router' {
       preLoaderRoute: typeof ApiSandboxTriageRouteImport
       parentRoute: typeof rootRouteImport
     }
+    '/api/mysql-persistent-chat': {
+      id: '/api/mysql-persistent-chat'
+      path: '/api/mysql-persistent-chat'
+      fullPath: '/api/mysql-persistent-chat'
+      preLoaderRoute: typeof ApiMysqlPersistentChatRouteImport
+      parentRoute: typeof rootRouteImport
+    }
     '/api/mcp-status': {
       id: '/api/mcp-status'
       path: '/api/mcp-status'
@@ -927,6 +967,7 @@ const rootRouteChildren: RootRouteChildren = {
   Issue176ToolResultRoute: Issue176ToolResultRoute,
   McpAppsRoute: McpAppsRoute,
   McpDemoRoute: McpDemoRoute,
+  MysqlPersistenceRoute: MysqlPersistenceRoute,
   RealtimeRoute: RealtimeRoute,
   SandboxesRoute: SandboxesRoute,
   ServerFnChatRoute: ServerFnChatRoute,
@@ -942,6 +983,7 @@ const rootRouteChildren: RootRouteChildren = {
   ApiMcpManualRoute: ApiMcpManualRoute,
   ApiMcpPoolRoute: ApiMcpPoolRoute,
   ApiMcpStatusRoute: ApiMcpStatusRoute,
+  ApiMysqlPersistentChatRoute: ApiMysqlPersistentChatRoute,
   ApiSandboxTriageRoute: ApiSandboxTriageRoute,
   ApiStructuredChatRoute: ApiStructuredChatRoute,
   ApiStructuredOutputRoute: ApiStructuredOutputRoute,
diff --git a/examples/ts-react-chat/src/routes/api.generate.image.ts b/examples/ts-react-chat/src/routes/api.generate.image.ts
index 8ec1ed4ed..cfe501bcc 100644
--- a/examples/ts-react-chat/src/routes/api.generate.image.ts
+++ b/examples/ts-react-chat/src/routes/api.generate.image.ts
@@ -1,5 +1,9 @@
 import { createFileRoute } from '@tanstack/react-router'
-import { generateImage, toServerSentEventsResponse } from '@tanstack/ai'
+import {
+  createImageOptions,
+  generateImage,
+  toServerSentEventsResponse,
+} from '@tanstack/ai'
 import { openaiImage } from '@tanstack/ai-openai'
 
 export const Route = createFileRoute('/api/generate/image')({
@@ -9,13 +13,16 @@ export const Route = createFileRoute('/api/generate/image')({
         const body = await request.json()
         const { prompt, size, model, numberOfImages } = body.data
 
-        const stream = generateImage({
-          adapter: openaiImage(model ?? 'gpt-image-1'),
-          prompt,
-          size,
-          numberOfImages,
-          stream: true,
-        })
+        const adapter = openaiImage(model ?? 'gpt-image-1')
+        const stream = generateImage<typeof adapter, true>(
+          createImageOptions({
+            adapter,
+            prompt,
+            size,
+            numberOfImages,
+            stream: true,
+          }),
+        )
 
         return toServerSentEventsResponse(stream)
       },
diff --git a/examples/ts-react-chat/src/routes/api.generate.video.ts b/examples/ts-react-chat/src/routes/api.generate.video.ts
index 632c822b3..1409b07c7 100644
--- a/examples/ts-react-chat/src/routes/api.generate.video.ts
+++ b/examples/ts-react-chat/src/routes/api.generate.video.ts
@@ -1,5 +1,9 @@
 import { createFileRoute } from '@tanstack/react-router'
-import { generateVideo, toServerSentEventsResponse } from '@tanstack/ai'
+import {
+  createVideoOptions,
+  generateVideo,
+  toServerSentEventsResponse,
+} from '@tanstack/ai'
 import { openaiVideo } from '@tanstack/ai-openai'
 
 export const Route = createFileRoute('/api/generate/video')({
@@ -9,15 +13,18 @@ export const Route = createFileRoute('/api/generate/video')({
         const body = await request.json()
         const { prompt, size, duration, model } = body.data
 
-        const stream = generateVideo({
-          adapter: openaiVideo(model ?? 'sora-2'),
-          prompt,
-          size,
-          duration,
-          stream: true,
-          pollingInterval: 3000,
-          maxDuration: 600_000,
-        })
+        const adapter = openaiVideo(model ?? 'sora-2')
+        const stream = generateVideo<typeof adapter, true>(
+          createVideoOptions({
+            adapter,
+            prompt,
+            size,
+            duration,
+            stream: true,
+            pollingInterval: 3000,
+            maxDuration: 600_000,
+          }),
+        )
 
         return toServerSentEventsResponse(stream)
       },
diff --git a/examples/ts-react-chat/src/routes/api.mysql-persistent-chat.ts b/examples/ts-react-chat/src/routes/api.mysql-persistent-chat.ts
new file mode 100644
index 000000000..f9fa56304
--- /dev/null
+++ b/examples/ts-react-chat/src/routes/api.mysql-persistent-chat.ts
@@ -0,0 +1,67 @@
+import { createFileRoute } from '@tanstack/react-router'
+import {
+  chat,
+  chatParamsFromRequestBody,
+  maxIterations,
+  memoryStream,
+  toServerSentEventsResponse,
+} from '@tanstack/ai'
+import { openaiText } from '@tanstack/ai-openai'
+import { withChatPersistence } from '@tanstack/ai-persistence'
+import { createChatPersistence } from '@/lib/mysql-persistence'
+
+const SYSTEM_PROMPT = `You are a concise assistant in a durable chat demo.
+
+Chat state (messages, run status, interrupts) is persisted via the state
+middleware. Delivery durability — so the browser can refresh and reconnect to an
+in-progress response — is handled by the transport helper's durability sink.
+Keep answers short enough that the streaming behavior is easy to inspect.`
+
+const persistence = createChatPersistence()
+
+export const Route = createFileRoute('/api/mysql-persistent-chat')({
+  server: {
+    handlers: {
+      POST: async ({ request }) => {
+        let params
+        try {
+          params = await chatParamsFromRequestBody(await request.json())
+        } catch (error) {
+          return new Response(
+            error instanceof Error ? error.message : 'Bad request',
+            { status: 400 },
+          )
+        }
+
+        // State durability: persist messages / run status / interrupts at
+        // boundaries. This is lazy — the provider call only fires on the first
+        // `for await` inside the transport helper.
+        const stream = chat({
+          adapter: openaiText('gpt-5.5'),
+          middleware: [
+            withChatPersistence(persistence, {
+              features: ['messages', 'interrupts'],
+            }),
+          ],
+          systemPrompts: [SYSTEM_PROMPT],
+          agentLoopStrategy: maxIterations(4),
+          messages: params.messages,
+          threadId: params.threadId,
+          runId: params.runId,
+          ...(params.resume ? { resume: params.resume } : {}),
+        })
+
+        // Delivery durability: the durability sink appends each batch and tags
+        // every SSE event with an `id: runId@seq` offset, so a reconnect
+        // (native Last-Event-ID) or second-tab join replays the ordered stream
+        // exactly once without re-invoking the provider. `memoryStream` is the
+        // zero-infra dev default; swap in `durableStream(request, { server })`
+        // for horizontally-scaled deployments.
+        const durability = memoryStream(request)
+        return toServerSentEventsResponse(stream, {
+          durability: { adapter: durability, batch: 8 },
+        })
+      },
+    },
+  },
+})
diff --git a/examples/ts-react-chat/src/routes/generations.image.tsx b/examples/ts-react-chat/src/routes/generations.image.tsx
index 044570498..ddbb8e124 100644
--- a/examples/ts-react-chat/src/routes/generations.image.tsx
+++ b/examples/ts-react-chat/src/routes/generations.image.tsx
@@ -32,7 +32,10 @@ function DirectImageGeneration() {
   const hookReturn = useGenerateImage({
     fetcher: (input) =>
       generateImageFn({
-        data: { ...input, prompt: resolveMediaPrompt(input.prompt).text },
+        data: {
+          prompt: resolveMediaPrompt(input.prompt).text,
+          numberOfImages: input.numberOfImages,
+        },
       }),
   })
 
@@ -54,7 +57,10 @@ function ServerFnImageGeneration() {
   const hookReturn = useGenerateImage({
     fetcher: (input) =>
       generateImageStreamFn({
-        data: { ...input, prompt: resolveMediaPrompt(input.prompt).text },
+        data: {
+          prompt: resolveMediaPrompt(input.prompt).text,
+          numberOfImages: input.numberOfImages,
+        },
       }),
   })
 
diff --git a/examples/ts-react-chat/src/routes/generations.structured-output.tsx b/examples/ts-react-chat/src/routes/generations.structured-output.tsx
index 1568a6b83..6e3f97325 100644
--- a/examples/ts-react-chat/src/routes/generations.structured-output.tsx
+++ b/examples/ts-react-chat/src/routes/generations.structured-output.tsx
@@ -28,14 +28,14 @@ const PROVIDER_MODELS: Record<
     { value: 'gpt-5.1', label: 'GPT-5.1' },
     { value: 'gpt-5', label: 'GPT-5' },
     { value: 'gpt-5-mini', label: 'GPT-5 Mini' },
-    { value: 'gpt-4o', label: 'GPT-4o' },
+    { value: 'gpt-5.5', label: 'GPT-5.5' },
   ],
   // OpenAI Chat Completions: same model surface, older `/v1/chat/completions`
   // wire format. The reasoning-summary opt-in isn't available here, so
   // streaming reasoning won't be surfaced for gpt-5.x even though the model
   // is still doing it under the hood.
   'openai-chat': [
-    { value: 'gpt-4o', label: 'GPT-4o' },
+    { value: 'gpt-5.5', label: 'GPT-5.5' },
     { value: 'gpt-5-mini', label: 'GPT-5 Mini' },
     { value: 'gpt-5', label: 'GPT-5' },
     { value: 'gpt-5.1', label: 'GPT-5.1' },
diff --git a/examples/ts-react-chat/src/routes/generations.video.tsx b/examples/ts-react-chat/src/routes/generations.video.tsx
index d9e2683f0..af03a24da 100644
--- a/examples/ts-react-chat/src/routes/generations.video.tsx
+++ b/examples/ts-react-chat/src/routes/generations.video.tsx
@@ -24,7 +24,10 @@ function DirectVideoGeneration() {
   const hookReturn = useGenerateVideo({
     fetcher: (input) =>
       generateVideoFn({
-        data: { ...input, prompt: resolveMediaPrompt(input.prompt).text },
+        data: {
+          prompt: resolveMediaPrompt(input.prompt).text,
+          duration: input.duration,
+        },
       }),
   })
 
@@ -39,7 +42,10 @@ function ServerFnVideoGeneration() {
   const hookReturn = useGenerateVideo({
     fetcher: (input) =>
       generateVideoStreamFn({
-        data: { ...input, prompt: resolveMediaPrompt(input.prompt).text },
+        data: {
+          prompt: resolveMediaPrompt(input.prompt).text,
+          duration: input.duration,
+        },
       }),
   })
 
diff --git a/examples/ts-react-chat/src/routes/mysql-persistence.tsx b/examples/ts-react-chat/src/routes/mysql-persistence.tsx
new file mode 100644
index 000000000..bc8b52183
--- /dev/null
+++ b/examples/ts-react-chat/src/routes/mysql-persistence.tsx
@@ -0,0 +1,165 @@
+import { useState } from 'react'
+import { createFileRoute } from '@tanstack/react-router'
+import { fetchServerSentEvents, useChat } from '@tanstack/ai-react'
+import { localStorageAIPersistence } from '@tanstack/ai-client'
+import { Square } from 'lucide-react'
+import type { ChatResumeSnapshot, UIMessage } from '@tanstack/ai-client'
+
+const THREAD_ID_KEY = 'tanstack-ai:mysql-persistence:thread-id'
+const RESUME_KEY_PREFIX = 'tanstack-ai:mysql-persistence:resume:'
+const MESSAGES_KEY_PREFIX = 'tanstack-ai:mysql-persistence:messages:'
+
+function getStableThreadId(): string {
+  if (typeof window === 'undefined') return 'mysql-persistence-ssr'
+  const existing = window.localStorage.getItem(THREAD_ID_KEY)
+  if (existing) return existing
+  const id = crypto.randomUUID()
+  window.localStorage.setItem(THREAD_ID_KEY, id)
+  return id
+}
+
+const messagePersistence = localStorageAIPersistence<Array<UIMessage>>({
+  keyPrefix: MESSAGES_KEY_PREFIX,
+})
+
+const resumePersistence = localStorageAIPersistence<ChatResumeSnapshot>({
+  keyPrefix: RESUME_KEY_PREFIX,
+})
+
+function messageText(message: UIMessage): string {
+  return message.parts
+    .map((part) => {
+      if (part.type === 'text') return part.content
+      if (part.type === 'thinking') return part.content
+      if (part.type === 'tool-call') return `[tool:${part.name}]`
+      return ''
+    })
+    .filter(Boolean)
+    .join('\n')
+}
+
+function MysqlPersistenceRoute() {
+  const [threadId] = useState(getStableThreadId)
+  const [input, setInput] = useState('')
+
+  const { messages, sendMessage, isLoading, error, resumeState, stop, clear } =
+    useChat({
+      id: threadId,
+      threadId,
+      connection: fetchServerSentEvents('/api/mysql-persistent-chat'),
+      persistence: {
+        client: messagePersistence,
+        server: resumePersistence,
+      },
+    })
+
+  const handleSubmit = (event: React.FormEvent) => {
+    event.preventDefault()
+    const text = input.trim()
+    if (!text || isLoading) return
+    setInput('')
+    void sendMessage(text)
+  }
+
+  const handleReset = () => {
+    clear()
+    messagePersistence.removeItem(threadId)
+    resumePersistence.removeItem(threadId)
+    window.localStorage.removeItem(THREAD_ID_KEY)
+    window.location.reload()
+  }
+
+  return (
+    <div className="flex h-[calc(100vh-72px)] flex-col bg-gray-900 text-white">
+      <div className="border-b border-orange-500/20 bg-gray-950 px-4 py-3">
+        <div className="mx-auto flex max-w-3xl items-center justify-between gap-4">
+          <div>
+            <h1 className="text-lg font-semibold">Persistent chat</h1>
+            <p className="text-sm text-gray-400">
+              Thread {threadId.slice(0, 8)}
+              {resumeState ? ` · run ${resumeState.runId.slice(0, 8)}` : ''}
+            </p>
+          </div>
+          <button
+            type="button"
+            onClick={handleReset}
+            className="rounded-lg border border-gray-700 px-3 py-2 text-sm text-gray-300 transition-colors hover:bg-gray-800"
+          >
+            Reset
+          </button>
+        </div>
+      </div>
+
+      <div className="flex-1 overflow-y-auto px-4 py-8">
+        <div className="mx-auto max-w-3xl space-y-4">
+          {messages.length === 0 && (
+            <div className="rounded-lg border border-gray-800 bg-gray-950 p-6 text-gray-400">
+              Send a prompt, then refresh while the response is streaming. The
+              transport's delivery-durability sink replays the ordered stream on
+              reconnect (native Last-Event-ID), while chat state persists to the
+              SQLite state backend.
+            </div>
+          )}
+          {messages.map((message) => (
+            <div
+              key={message.id}
+              className={`rounded-lg px-4 py-3 ${
+                message.role === 'user'
+                  ? 'ml-auto max-w-2xl bg-orange-500/20'
+                  : 'mr-auto max-w-2xl bg-gray-800'
+              }`}
+            >
+              <div className="mb-2 text-xs font-semibold uppercase text-gray-500">
+                {message.role}
+              </div>
+              <div className="whitespace-pre-wrap text-sm leading-6">
+                {messageText(message)}
+              </div>
+            </div>
+          ))}
+          {error && (
+            <div className="rounded-lg border border-red-500/30 bg-red-500/10 px-4 py-3 text-sm text-red-300">
+              {error.message}
+            </div>
+          )}
+        </div>
+      </div>
+
+      <form
+        onSubmit={handleSubmit}
+        className="border-t border-gray-800 bg-gray-950 px-4 py-3"
+      >
+        <div className="mx-auto flex max-w-3xl gap-2">
+          <input
+            value={input}
+            onChange={(event) => setInput(event.target.value)}
+            placeholder="Ask for a detailed answer, then refresh mid-stream"
+            className="min-w-0 flex-1 rounded-lg border border-gray-700 bg-gray-900 px-4 py-2 text-white placeholder-gray-500 focus:border-orange-500/50 focus:outline-none"
+          />
+          {isLoading ? (
+            <button
+              type="button"
+              onClick={() => void stop()}
+              className="flex items-center gap-2 rounded-lg bg-gray-700 px-5 py-2 font-medium text-white transition-colors hover:bg-gray-600"
+            >
+              <Square size={16} />
+              Stop
+            </button>
+          ) : (
+            <button
+              type="submit"
+              className="rounded-lg bg-orange-500 px-5 py-2 font-medium text-white transition-colors hover:bg-orange-600 disabled:opacity-50"
+              disabled={!input.trim()}
+            >
+              Send
+            </button>
+          )}
+        </div>
+      </form>
+    </div>
+  )
+}
+
+export const Route = createFileRoute('/mysql-persistence')({
+  component: MysqlPersistenceRoute,
+})
diff --git a/knip.json b/knip.json
index c7995c1aa..f7fbcb313 100644
--- a/knip.json
+++ b/knip.json
@@ -40,7 +40,7 @@
       "ignoreDependencies": ["@standard-schema/spec"]
     },
     "packages/ai-sandbox": {
-      "ignoreDependencies": ["@ngrok/ngrok"]
+      "ignoreDependencies": ["@ngrok/ngrok", "@tanstack/ai-persistence"]
     },
     "packages/ai-sandbox-cloudflare": {
       "ignoreDependencies": ["cloudflare"]
@@ -57,6 +57,9 @@
     "packages/ai-vue-ui": {
       "ignore": ["src/use-chat-context.ts"]
     },
-    "packages/ai-bedrock": {}
+    "packages/ai-bedrock": {},
+    "packages/ai-persistence": {
+      "ignoreDependencies": ["vitest"]
+    }
   }
 }
diff --git a/packages/ai-angular/package.json b/packages/ai-angular/package.json
index b46f85212..6e435bdb4 100644
--- a/packages/ai-angular/package.json
+++ b/packages/ai-angular/package.json
@@ -50,7 +50,7 @@
     "test:lib:dev": "vitest",
     "test:types": "tsc",
     "test:build": "publint --strict",
-    "build": "ng-packagr -p ng-package.json -c tsconfig.build.json && rm -rf ./dist/package.json"
+    "build": "ng-packagr -p ng-package.json -c tsconfig.build.json && premove ./dist/package.json"
   },
   "dependencies": {
     "@tanstack/ai-client": "workspace:*",
diff --git a/packages/ai-angular/src/inject-chat.ts b/packages/ai-angular/src/inject-chat.ts
index 5c1453abe..70c961681 100644
--- a/packages/ai-angular/src/inject-chat.ts
+++ b/packages/ai-angular/src/inject-chat.ts
@@ -90,6 +90,9 @@ export function injectChat<
     ...(options.persistence !== undefined && {
       persistence: options.persistence,
     }),
+    ...(options.initialResumeSnapshot !== undefined && {
+      initialResumeSnapshot: options.initialResumeSnapshot,
+    }),
     ...(bodySource !== undefined && { body: bodySource() }),
     ...(options.threadId !== undefined && { threadId: options.threadId }),
     ...(forwardedPropsSource !== undefined && {
@@ -106,6 +109,9 @@ export function injectChat<
     onChunk: (chunk: StreamChunk) => options.onChunk?.(chunk),
     onFinish: (message) => options.onFinish?.(message),
     onError: (err) => options.onError?.(err),
+    onResumeStateChange: (resumeState, pendingInterrupts) => {
+      options.onResumeStateChange?.(resumeState, pendingInterrupts)
+    },
     tools: options.tools,
     onCustomEvent: (eventType, data, context) =>
       options.onCustomEvent?.(eventType, data, context),
@@ -156,7 +162,15 @@ export function injectChat<
     )
   }
 
-  afterNextRender(() => client.mountDevtools(), { injector })
+  afterNextRender(
+    () => {
+      client.mountDevtools()
+      // Delivery-durability resume is transparent: the resumable SSE
+      // connection adapter reattaches via the browser's native Last-Event-ID
+      // on reconnect. No client-side auto-resume wiring is needed.
+    },
+    { injector },
+  )
 
   destroyRef.onDestroy(() => {
     if (liveSource?.()) {
diff --git a/packages/ai-angular/src/inject-generate-audio.ts b/packages/ai-angular/src/inject-generate-audio.ts
index 188a032e0..fbb57607c 100644
--- a/packages/ai-angular/src/inject-generate-audio.ts
+++ b/packages/ai-angular/src/inject-generate-audio.ts
@@ -10,13 +10,22 @@ import type {
 } from '@tanstack/ai-client'
 import type { Signal } from '@angular/core'
 import type { ReactiveOption } from './internal/to-reactive'
+import type {
+  InjectGenerationOptions,
+  InjectGenerationResult,
+} from './inject-generation'
 
 /**
  * Options for the injectGenerateAudio injectable.
  *
  * @template TOutput - The output type after optional transform (defaults to AudioGenerationResult)
  */
-export interface InjectGenerateAudioOptions<TOutput = AudioGenerationResult> {
+export interface InjectGenerateAudioOptions<
+  TOutput = AudioGenerationResult,
+> extends Pick<
+  InjectGenerationOptions<AudioGenerateInput, AudioGenerationResult, TOutput>,
+  'persistence' | 'initialResumeSnapshot'
+> {
   /** Connect-based adapter for streaming transport (SSE, HTTP stream, custom) */
   connection?: ConnectConnectionAdapter
   /** Direct async function for audio generation */
@@ -48,7 +57,9 @@ export interface InjectGenerateAudioOptions<TOutput = AudioGenerationResult> {
  *
  * @template TOutput - The output type (after optional transform)
  */
-export interface InjectGenerateAudioResult<TOutput = AudioGenerationResult> {
+export interface InjectGenerateAudioResult<
+  TOutput = AudioGenerationResult,
+> extends Omit<InjectGenerationResult<TOutput>, 'generate'> {
   /** Trigger audio generation */
   generate: (input: AudioGenerateInput) => Promise<void>
   /** The generation result containing audio, or null */
@@ -59,10 +70,6 @@ export interface InjectGenerateAudioResult<TOutput = AudioGenerationResult> {
   error: Signal<Error | undefined>
   /** Current state of the generation */
   status: Signal<GenerationClientState>
-  /** Abort the current generation */
-  stop: () => void
-  /** Clear result, error, and return to idle */
-  reset: () => void
 }
 
 /**
@@ -109,19 +116,19 @@ export function injectGenerateAudio<TTransformed = void>(
     hookName: 'injectGenerateAudio',
     outputKind: 'audio' as const,
   }
-  const { generate, result, isLoading, error, status, stop, reset } =
-    injectGeneration<AudioGenerateInput, AudioGenerationResult, TTransformed>({
-      ...options,
-      devtools,
-    })
+  const generation = injectGeneration<
+    AudioGenerateInput,
+    AudioGenerationResult,
+    TTransformed
+  >({
+    ...options,
+    devtools,
+  })
 
   return {
-    generate: generate as (input: AudioGenerateInput) => Promise<void>,
-    result,
-    isLoading,
-    error,
-    status,
-    stop,
-    reset,
+    ...generation,
+    generate: generation.generate as (
+      input: AudioGenerateInput,
+    ) => Promise<void>,
   }
 }
diff --git a/packages/ai-angular/src/inject-generate-image.ts b/packages/ai-angular/src/inject-generate-image.ts
index 3c3c2e4fe..16b08e8e6 100644
--- a/packages/ai-angular/src/inject-generate-image.ts
+++ b/packages/ai-angular/src/inject-generate-image.ts
@@ -6,7 +6,10 @@ import type {
   ImageGenerateInput,
   InferGenerationOutputFromReturn,
 } from '@tanstack/ai-client'
-import type { InjectGenerationOptions } from './inject-generation'
+import type {
+  InjectGenerationOptions,
+  InjectGenerationResult,
+} from './inject-generation'
 
 export type InjectGenerateImageOptions<TOutput = ImageGenerationResult> = Omit<
   InjectGenerationOptions<ImageGenerateInput, ImageGenerationResult, TOutput>,
@@ -15,14 +18,14 @@ export type InjectGenerateImageOptions<TOutput = ImageGenerationResult> = Omit<
   onResult?: (result: ImageGenerationResult) => TOutput | null | void
 }
 
-export interface InjectGenerateImageResult<TOutput = ImageGenerationResult> {
+export interface InjectGenerateImageResult<
+  TOutput = ImageGenerationResult,
+> extends Omit<InjectGenerationResult<TOutput>, 'generate'> {
   generate: (input: ImageGenerateInput) => Promise<void>
   result: Signal<TOutput | null>
   isLoading: Signal<boolean>
   error: Signal<Error | undefined>
   status: Signal<GenerationClientState>
-  stop: () => void
-  reset: () => void
 }
 
 export function injectGenerateImage<TTransformed = void>(
@@ -38,18 +41,18 @@ export function injectGenerateImage<TTransformed = void>(
     hookName: 'injectGenerateImage',
     outputKind: 'image' as const,
   }
-  const { generate, result, isLoading, error, status, stop, reset } =
-    injectGeneration<ImageGenerateInput, ImageGenerationResult, TTransformed>({
-      ...options,
-      devtools,
-    })
+  const generation = injectGeneration<
+    ImageGenerateInput,
+    ImageGenerationResult,
+    TTransformed
+  >({
+    ...options,
+    devtools,
+  })
   return {
-    generate: generate as (input: ImageGenerateInput) => Promise<void>,
-    result,
-    isLoading,
-    error,
-    status,
-    stop,
-    reset,
+    ...generation,
+    generate: generation.generate as (
+      input: ImageGenerateInput,
+    ) => Promise<void>,
   }
 }
diff --git a/packages/ai-angular/src/inject-generate-speech.ts b/packages/ai-angular/src/inject-generate-speech.ts
index ce3e08549..d78b804ec 100644
--- a/packages/ai-angular/src/inject-generate-speech.ts
+++ b/packages/ai-angular/src/inject-generate-speech.ts
@@ -6,7 +6,10 @@ import type {
   InferGenerationOutputFromReturn,
   SpeechGenerateInput,
 } from '@tanstack/ai-client'
-import type { InjectGenerationOptions } from './inject-generation'
+import type {
+  InjectGenerationOptions,
+  InjectGenerationResult,
+} from './inject-generation'
 
 export type InjectGenerateSpeechOptions<TOutput = TTSResult> = Omit<
   InjectGenerationOptions<SpeechGenerateInput, TTSResult, TOutput>,
@@ -15,14 +18,15 @@ export type InjectGenerateSpeechOptions<TOutput = TTSResult> = Omit<
   onResult?: (result: TTSResult) => TOutput | null | void
 }
 
-export interface InjectGenerateSpeechResult<TOutput = TTSResult> {
+export interface InjectGenerateSpeechResult<TOutput = TTSResult> extends Omit<
+  InjectGenerationResult<TOutput>,
+  'generate'
+> {
   generate: (input: SpeechGenerateInput) => Promise<void>
   result: Signal<TOutput | null>
   isLoading: Signal<boolean>
   error: Signal<Error | undefined>
   status: Signal<GenerationClientState>
-  stop: () => void
-  reset: () => void
 }
 
 export function injectGenerateSpeech<TTransformed = void>(
@@ -38,18 +42,18 @@ export function injectGenerateSpeech<TTransformed = void>(
     hookName: 'injectGenerateSpeech',
     outputKind: 'audio' as const,
   }
-  const { generate, result, isLoading, error, status, stop, reset } =
-    injectGeneration<SpeechGenerateInput, TTSResult, TTransformed>({
-      ...options,
-      devtools,
-    })
+  const generation = injectGeneration<
+    SpeechGenerateInput,
+    TTSResult,
+    TTransformed
+  >({
+    ...options,
+    devtools,
+  })
   return {
-    generate: generate as (input: SpeechGenerateInput) => Promise<void>,
-    result,
-    isLoading,
-    error,
-    status,
-    stop,
-    reset,
+    ...generation,
+    generate: generation.generate as (
+      input: SpeechGenerateInput,
+    ) => Promise<void>,
   }
 }
diff --git a/packages/ai-angular/src/inject-generate-video.ts b/packages/ai-angular/src/inject-generate-video.ts
index c493e39ee..4e75df991 100644
--- a/packages/ai-angular/src/inject-generate-video.ts
+++ b/packages/ai-angular/src/inject-generate-video.ts
@@ -17,12 +17,17 @@ import type {
   ConnectConnectionAdapter,
   GenerationClientState,
   GenerationFetcher,
+  GenerationPendingArtifact,
+  GenerationPersistenceOptions,
+  GenerationResumeSnapshot,
+  GenerationResumeState,
   InferGenerationOutputFromReturn,
   VideoGenerateInput,
   VideoGenerateResult,
   VideoStatusInfo,
 } from '@tanstack/ai-client'
 import type { StreamChunk } from '@tanstack/ai'
+import type { PersistedArtifactRef } from '@tanstack/ai/client'
 
 let nextId = 0
 
@@ -32,6 +37,8 @@ export interface InjectGenerateVideoOptions<TOutput = VideoGenerateResult> {
   id?: string
   body?: ReactiveOption<Record<string, any>>
   devtools?: AIDevtoolsDisplayOptions
+  persistence?: GenerationPersistenceOptions
+  initialResumeSnapshot?: GenerationResumeSnapshot
   onResult?: (result: VideoGenerateResult) => TOutput | null | void
   onError?: (error: Error) => void
   onProgress?: (progress: number, message?: string) => void
@@ -50,6 +57,10 @@ export interface InjectGenerateVideoResult<TOutput = VideoGenerateResult> {
   status: Signal<GenerationClientState>
   stop: () => void
   reset: () => void
+  resumeSnapshot: Signal<GenerationResumeSnapshot | undefined>
+  resumeState: Signal<GenerationResumeState | null>
+  pendingArtifacts: Signal<Array<GenerationPendingArtifact>>
+  resultArtifacts: Signal<Array<PersistedArtifactRef>>
 }
 
 // `TTransformed` infers from the `onResult` return position so the callback
@@ -79,6 +90,29 @@ export function injectGenerateVideo<TTransformed = void>(
   const isLoading = signal(false)
   const error = signal<Error | undefined>(undefined)
   const status = signal<GenerationClientState>('idle')
+  const resumeSnapshot = signal<GenerationResumeSnapshot | undefined>(
+    options.initialResumeSnapshot,
+  )
+  const resumeState = signal<GenerationResumeState | null>(
+    options.initialResumeSnapshot?.resumeState ?? null,
+  )
+  const pendingArtifacts = signal<Array<GenerationPendingArtifact>>(
+    options.initialResumeSnapshot?.pendingArtifacts ?? [],
+  )
+  const resultArtifacts = signal<Array<PersistedArtifactRef>>(
+    options.initialResumeSnapshot?.result?.artifacts ?? [],
+  )
+  let disposed = false
+
+  const setResumeSnapshotState = (
+    snapshot: GenerationResumeSnapshot | undefined,
+  ) => {
+    if (disposed) return
+    resumeSnapshot.set(snapshot)
+    resumeState.set(snapshot?.resumeState ?? null)
+    pendingArtifacts.set(snapshot?.pendingArtifacts ?? [])
+    resultArtifacts.set(snapshot?.result?.artifacts ?? [])
+  }
 
   const bodySource =
     options.body !== undefined ? toReactive(options.body) : undefined
@@ -86,6 +120,12 @@ export function injectGenerateVideo<TTransformed = void>(
   const baseOptions = {
     id: clientId,
     ...(bodySource !== undefined && { body: bodySource() }),
+    ...(options.persistence !== undefined && {
+      persistence: options.persistence,
+    }),
+    ...(options.initialResumeSnapshot !== undefined && {
+      initialResumeSnapshot: options.initialResumeSnapshot,
+    }),
     devtoolsBridgeFactory: createVideoDevtoolsBridge,
     devtools: {
       ...options.devtools,
@@ -99,17 +139,40 @@ export function injectGenerateVideo<TTransformed = void>(
     onResult: ((r: VideoGenerateResult) => options.onResult?.(r)) as (
       result: VideoGenerateResult,
     ) => TOutput | null | void,
-    onError: (e: Error) => options.onError?.(e),
-    onProgress: (p: number, m?: string) => options.onProgress?.(p, m),
-    onChunk: (c: StreamChunk) => options.onChunk?.(c),
-    onJobCreated: (id: string) => options.onJobCreated?.(id),
-    onStatusUpdate: (s: VideoStatusInfo) => options.onStatusUpdate?.(s),
-    onResultChange: (r: TOutput | null) => result.set(r),
-    onLoadingChange: (l: boolean) => isLoading.set(l),
-    onErrorChange: (e: Error | undefined) => error.set(e),
-    onStatusChange: (s: GenerationClientState) => status.set(s),
-    onJobIdChange: (id: string | null) => jobId.set(id),
-    onVideoStatusChange: (s: VideoStatusInfo | null) => videoStatus.set(s),
+    onError: (e: Error) => {
+      if (!disposed) options.onError?.(e)
+    },
+    onProgress: (p: number, m?: string) => {
+      if (!disposed) options.onProgress?.(p, m)
+    },
+    onChunk: (c: StreamChunk) => {
+      if (!disposed) options.onChunk?.(c)
+    },
+    onJobCreated: (id: string) => {
+      if (!disposed) options.onJobCreated?.(id)
+    },
+    onStatusUpdate: (s: VideoStatusInfo) => {
+      if (!disposed) options.onStatusUpdate?.(s)
+    },
+    onResultChange: (r: TOutput | null) => {
+      if (!disposed) result.set(r)
+    },
+    onLoadingChange: (l: boolean) => {
+      if (!disposed) isLoading.set(l)
+    },
+    onErrorChange: (e: Error | undefined) => {
+      if (!disposed) error.set(e)
+    },
+    onStatusChange: (s: GenerationClientState) => {
+      if (!disposed) status.set(s)
+    },
+    onJobIdChange: (id: string | null) => {
+      if (!disposed) jobId.set(id)
+    },
+    onVideoStatusChange: (s: VideoStatusInfo | null) => {
+      if (!disposed) videoStatus.set(s)
+    },
+    onResumeSnapshotChange: setResumeSnapshotState,
   }
 
   let client: VideoGenerationClient<TOutput>
@@ -132,14 +195,26 @@ export function injectGenerateVideo<TTransformed = void>(
   if (bodySource) {
     effect(
       () => {
-        client.updateOptions({ body: bodySource() })
+        client.updateOptions({
+          body: bodySource(),
+        })
       },
       { injector },
     )
   }
 
-  afterNextRender(() => client.mountDevtools(), { injector })
-  destroyRef.onDestroy(() => client.dispose())
+  // Mount devtools only. Generation runs are never auto-started after render —
+  // persisted state is read-only for display.
+  afterNextRender(
+    () => {
+      client.mountDevtools()
+    },
+    { injector },
+  )
+  destroyRef.onDestroy(() => {
+    disposed = true
+    client.dispose()
+  })
 
   return {
     generate: (input: VideoGenerateInput) => client.generate(input),
@@ -151,5 +226,9 @@ export function injectGenerateVideo<TTransformed = void>(
     status: status.asReadonly(),
     stop: () => client.stop(),
     reset: () => client.reset(),
+    resumeSnapshot: resumeSnapshot.asReadonly(),
+    resumeState: resumeState.asReadonly(),
+    pendingArtifacts: pendingArtifacts.asReadonly(),
+    resultArtifacts: resultArtifacts.asReadonly(),
   }
 }
diff --git a/packages/ai-angular/src/inject-generation.ts b/packages/ai-angular/src/inject-generation.ts
index 177842e01..542f2c6e6 100644
--- a/packages/ai-angular/src/inject-generation.ts
+++ b/packages/ai-angular/src/inject-generation.ts
@@ -18,8 +18,13 @@ import type {
   GenerationClientOptions,
   GenerationClientState,
   GenerationFetcher,
+  GenerationPendingArtifact,
+  GenerationPersistenceOptions,
+  GenerationResumeSnapshot,
+  GenerationResumeState,
   InferGenerationOutputFromReturn,
 } from '@tanstack/ai-client'
+import type { PersistedArtifactRef } from '@tanstack/ai/client'
 import type { ReactiveOption } from './internal/to-reactive'
 
 let nextId = 0
@@ -35,6 +40,10 @@ export interface InjectGenerationOptions<TInput, TResult, TOutput = TResult> {
   body?: ReactiveOption<Record<string, any>>
   /** Display options for TanStack AI Devtools. */
   devtools?: AIDevtoolsDisplayOptions
+  /** Server-side lightweight generation state persistence. */
+  persistence?: GenerationPersistenceOptions
+  /** Initial lightweight resume snapshot restored by the app (read-only state). */
+  initialResumeSnapshot?: GenerationResumeSnapshot
   /**
    * Callback when a result is received. Can optionally return a transformed value.
    *
@@ -66,6 +75,14 @@ export interface InjectGenerationResult<TOutput> {
   stop: () => void
   /** Clear result, error, and return to idle */
   reset: () => void
+  /** Lightweight generation resume snapshot, if one is available */
+  resumeSnapshot: Signal<GenerationResumeSnapshot | undefined>
+  /** Observed run/cursor metadata from the snapshot (read-only state) */
+  resumeState: Signal<GenerationResumeState | null>
+  /** Pending persisted artifact references observed during generation/replay */
+  pendingArtifacts: Signal<Array<GenerationPendingArtifact>>
+  /** Final persisted artifact references observed from a replayed result */
+  resultArtifacts: Signal<Array<PersistedArtifactRef>>
 }
 
 // `TTransformed` infers from the `onResult` return position (a covariant
@@ -97,6 +114,29 @@ export function injectGeneration<
   const isLoading = signal(false)
   const error = signal<Error | undefined>(undefined)
   const status = signal<GenerationClientState>('idle')
+  const resumeSnapshot = signal<GenerationResumeSnapshot | undefined>(
+    options.initialResumeSnapshot,
+  )
+  const resumeState = signal<GenerationResumeState | null>(
+    options.initialResumeSnapshot?.resumeState ?? null,
+  )
+  const pendingArtifacts = signal<Array<GenerationPendingArtifact>>(
+    options.initialResumeSnapshot?.pendingArtifacts ?? [],
+  )
+  const resultArtifacts = signal<Array<PersistedArtifactRef>>(
+    options.initialResumeSnapshot?.result?.artifacts ?? [],
+  )
+  let disposed = false
+
+  const setResumeSnapshotState = (
+    snapshot: GenerationResumeSnapshot | undefined,
+  ) => {
+    if (disposed) return
+    resumeSnapshot.set(snapshot)
+    resumeState.set(snapshot?.resumeState ?? null)
+    pendingArtifacts.set(snapshot?.pendingArtifacts ?? [])
+    resultArtifacts.set(snapshot?.result?.artifacts ?? [])
+  }
 
   const bodySource =
     options.body !== undefined ? toReactive(options.body) : undefined
@@ -104,6 +144,12 @@ export function injectGeneration<
   const clientOptions: GenerationClientOptions<TInput, TResult, TOutput> = {
     id: clientId,
     ...(bodySource !== undefined && { body: bodySource() }),
+    ...(options.persistence !== undefined && {
+      persistence: options.persistence,
+    }),
+    ...(options.initialResumeSnapshot !== undefined && {
+      initialResumeSnapshot: options.initialResumeSnapshot,
+    }),
     devtoolsBridgeFactory: createGenerationDevtoolsBridge,
     devtools: {
       ...options.devtools,
@@ -116,13 +162,28 @@ export function injectGeneration<
     onResult: ((r: TResult) => options.onResult?.(r)) as (
       result: TResult,
     ) => TOutput | null | void,
-    onError: (e: Error) => options.onError?.(e),
-    onProgress: (p: number, m?: string) => options.onProgress?.(p, m),
-    onChunk: (c: StreamChunk) => options.onChunk?.(c),
-    onResultChange: (r: TOutput | null) => result.set(r),
-    onLoadingChange: (l: boolean) => isLoading.set(l),
-    onErrorChange: (e: Error | undefined) => error.set(e),
-    onStatusChange: (s: GenerationClientState) => status.set(s),
+    onError: (e: Error) => {
+      if (!disposed) options.onError?.(e)
+    },
+    onProgress: (p: number, m?: string) => {
+      if (!disposed) options.onProgress?.(p, m)
+    },
+    onChunk: (c: StreamChunk) => {
+      if (!disposed) options.onChunk?.(c)
+    },
+    onResultChange: (r: TOutput | null) => {
+      if (!disposed) result.set(r)
+    },
+    onLoadingChange: (l: boolean) => {
+      if (!disposed) isLoading.set(l)
+    },
+    onErrorChange: (e: Error | undefined) => {
+      if (!disposed) error.set(e)
+    },
+    onStatusChange: (s: GenerationClientState) => {
+      if (!disposed) status.set(s)
+    },
+    onResumeSnapshotChange: setResumeSnapshotState,
   }
 
   let client: GenerationClient<TInput, TResult, TOutput>
@@ -145,14 +206,26 @@ export function injectGeneration<
   if (bodySource) {
     effect(
       () => {
-        client.updateOptions({ body: bodySource() })
+        client.updateOptions({
+          body: bodySource(),
+        })
       },
       { injector },
     )
   }
 
-  afterNextRender(() => client.mountDevtools(), { injector })
-  destroyRef.onDestroy(() => client.dispose())
+  // Mount devtools only. Generation runs are never auto-started after render —
+  // persisted state is read-only for display.
+  afterNextRender(
+    () => {
+      client.mountDevtools()
+    },
+    { injector },
+  )
+  destroyRef.onDestroy(() => {
+    disposed = true
+    client.dispose()
+  })
 
   return {
     generate: ((input: TInput) => client.generate(input)) as (
@@ -164,5 +237,9 @@ export function injectGeneration<
     status: status.asReadonly(),
     stop: () => client.stop(),
     reset: () => client.reset(),
+    resumeSnapshot: resumeSnapshot.asReadonly(),
+    resumeState: resumeState.asReadonly(),
+    pendingArtifacts: pendingArtifacts.asReadonly(),
+    resultArtifacts: resultArtifacts.asReadonly(),
   }
 }
diff --git a/packages/ai-angular/src/inject-summarize.ts b/packages/ai-angular/src/inject-summarize.ts
index fa41a76fa..db6b1c6e8 100644
--- a/packages/ai-angular/src/inject-summarize.ts
+++ b/packages/ai-angular/src/inject-summarize.ts
@@ -6,7 +6,10 @@ import type {
   InferGenerationOutputFromReturn,
   SummarizeGenerateInput,
 } from '@tanstack/ai-client'
-import type { InjectGenerationOptions } from './inject-generation'
+import type {
+  InjectGenerationOptions,
+  InjectGenerationResult,
+} from './inject-generation'
 
 export type InjectSummarizeOptions<TOutput = SummarizationResult> = Omit<
   InjectGenerationOptions<SummarizeGenerateInput, SummarizationResult, TOutput>,
@@ -15,14 +18,14 @@ export type InjectSummarizeOptions<TOutput = SummarizationResult> = Omit<
   onResult?: (result: SummarizationResult) => TOutput | null | void
 }
 
-export interface InjectSummarizeResult<TOutput = SummarizationResult> {
+export interface InjectSummarizeResult<
+  TOutput = SummarizationResult,
+> extends Omit<InjectGenerationResult<TOutput>, 'generate'> {
   generate: (input: SummarizeGenerateInput) => Promise<void>
   result: Signal<TOutput | null>
   isLoading: Signal<boolean>
   error: Signal<Error | undefined>
   status: Signal<GenerationClientState>
-  stop: () => void
-  reset: () => void
 }
 
 export function injectSummarize<TTransformed = void>(
@@ -38,20 +41,18 @@ export function injectSummarize<TTransformed = void>(
     hookName: 'injectSummarize',
     outputKind: 'text' as const,
   }
-  const { generate, result, isLoading, error, status, stop, reset } =
-    injectGeneration<SummarizeGenerateInput, SummarizationResult, TTransformed>(
-      {
-        ...options,
-        devtools,
-      },
-    )
+  const generation = injectGeneration<
+    SummarizeGenerateInput,
+    SummarizationResult,
+    TTransformed
+  >({
+    ...options,
+    devtools,
+  })
   return {
-    generate: generate as (input: SummarizeGenerateInput) => Promise<void>,
-    result,
-    isLoading,
-    error,
-    status,
-    stop,
-    reset,
+    ...generation,
+    generate: generation.generate as (
+      input: SummarizeGenerateInput,
+    ) => Promise<void>,
   }
 }
diff --git a/packages/ai-angular/src/inject-transcription.ts b/packages/ai-angular/src/inject-transcription.ts
index ef2066ad2..b7bc832af 100644
--- a/packages/ai-angular/src/inject-transcription.ts
+++ b/packages/ai-angular/src/inject-transcription.ts
@@ -6,7 +6,10 @@ import type {
   InferGenerationOutputFromReturn,
   TranscriptionGenerateInput,
 } from '@tanstack/ai-client'
-import type { InjectGenerationOptions } from './inject-generation'
+import type {
+  InjectGenerationOptions,
+  InjectGenerationResult,
+} from './inject-generation'
 
 export type InjectTranscriptionOptions<TOutput = TranscriptionResult> = Omit<
   InjectGenerationOptions<
@@ -19,14 +22,14 @@ export type InjectTranscriptionOptions<TOutput = TranscriptionResult> = Omit<
   onResult?: (result: TranscriptionResult) => TOutput | null | void
 }
 
-export interface InjectTranscriptionResult<TOutput = TranscriptionResult> {
+export interface InjectTranscriptionResult<
+  TOutput = TranscriptionResult,
+> extends Omit<InjectGenerationResult<TOutput>, 'generate'> {
   generate: (input: TranscriptionGenerateInput) => Promise<void>
   result: Signal<TOutput | null>
   isLoading: Signal<boolean>
   error: Signal<Error | undefined>
   status: Signal<GenerationClientState>
-  stop: () => void
-  reset: () => void
 }
 
 export function injectTranscription<TTransformed = void>(
@@ -42,22 +45,18 @@ export function injectTranscription<TTransformed = void>(
     hookName: 'injectTranscription',
     outputKind: 'text' as const,
   }
-  const { generate, result, isLoading, error, status, stop, reset } =
-    injectGeneration<
-      TranscriptionGenerateInput,
-      TranscriptionResult,
-      TTransformed
-    >({
-      ...options,
-      devtools,
-    })
+  const generation = injectGeneration<
+    TranscriptionGenerateInput,
+    TranscriptionResult,
+    TTransformed
+  >({
+    ...options,
+    devtools,
+  })
   return {
-    generate: generate as (input: TranscriptionGenerateInput) => Promise<void>,
-    result,
-    isLoading,
-    error,
-    status,
-    stop,
-    reset,
+    ...generation,
+    generate: generation.generate as (
+      input: TranscriptionGenerateInput,
+    ) => Promise<void>,
   }
 }
diff --git a/packages/ai-angular/tests/inject-chat.test.ts b/packages/ai-angular/tests/inject-chat.test.ts
index b7d0bf710..6855074af 100644
--- a/packages/ai-angular/tests/inject-chat.test.ts
+++ b/packages/ai-angular/tests/inject-chat.test.ts
@@ -1,5 +1,6 @@
 import { describe, expect, it, vi } from 'vitest'
 import { z } from 'zod'
+import { EventType } from '@tanstack/ai/client'
 import { Component, signal } from '@angular/core'
 import { TestBed } from '@angular/core/testing'
 import { ChatClient } from '@tanstack/ai-client'
@@ -120,6 +121,55 @@ describe('injectChat — reactive options', () => {
   })
 })
 
+describe('injectChat — resume', () => {
+  it('forwards onResumeStateChange to ChatClient', async () => {
+    const onResumeStateChange = vi.fn()
+    const adapter = createMockConnectionAdapter({
+      chunks: [
+        {
+          type: EventType.RUN_STARTED,
+          runId: 'run-1',
+          threadId: 'thread-1',
+          timestamp: Date.now(),
+        },
+        {
+          type: EventType.TEXT_MESSAGE_CONTENT,
+          messageId: 'msg-1',
+          timestamp: Date.now(),
+          delta: 'Hi',
+        },
+        {
+          type: EventType.RUN_FINISHED,
+          runId: 'run-1',
+          threadId: 'thread-1',
+          timestamp: Date.now(),
+          outcome: {
+            type: 'interrupt',
+            interrupts: [{ id: 'interrupt-1', reason: 'client_tool_input' }],
+          },
+        },
+      ],
+    })
+    const { result } = renderInjectChat({
+      connection: adapter,
+      threadId: 'thread-1',
+      onResumeStateChange,
+    })
+
+    await result.sendMessage('Hi')
+
+    // A run that pauses on an interrupt forwards interrupt (state) resume —
+    // the thread/run ids to target on a follow-up. No delivery cursor.
+    expect(onResumeStateChange).toHaveBeenCalledWith(
+      expect.objectContaining({
+        threadId: 'thread-1',
+        runId: expect.any(String),
+      }),
+      expect.arrayContaining([expect.objectContaining({ id: 'interrupt-1' })]),
+    )
+  })
+})
+
 describe('injectChat — structured output', () => {
   // Mount injectChat directly so the `outputSchema` generic flows through and
   // the schema-gated `partial` / `final` signals are present on the result.
diff --git a/packages/ai-angular/tests/inject-generation.test.ts b/packages/ai-angular/tests/inject-generation.test.ts
index 1ae52833e..2ee11685c 100644
--- a/packages/ai-angular/tests/inject-generation.test.ts
+++ b/packages/ai-angular/tests/inject-generation.test.ts
@@ -6,6 +6,13 @@ import {
 } from '@angular/platform-browser-dynamic/testing'
 import { describe, expect, it, vi } from 'vitest'
 import { injectGeneration } from '../src/inject-generation'
+import { injectGenerateVideo } from '../src/inject-generate-video'
+import type { StreamChunk } from '@tanstack/ai'
+import type {
+  ConnectConnectionAdapter,
+  GenerationResumeSnapshot,
+  RunAgentInputContext,
+} from '@tanstack/ai-client'
 
 // Ensure TestBed is initialized in this module's scope, regardless of whether
 // the setup file's initialization was in a different module context (possible
@@ -34,9 +41,53 @@ function renderInjectGeneration(options: any) {
       return fixture.componentInstance.gen
     },
     flush: () => fixture.detectChanges(),
+    destroy: () => fixture.destroy(),
   }
 }
 
+function renderInjectGenerateVideo(options: any) {
+  @Component({ standalone: true, template: '' })
+  class Host {
+    gen = injectGenerateVideo(options)
+  }
+  const fixture = TestBed.createComponent(Host)
+  fixture.detectChanges()
+  return {
+    get result() {
+      return fixture.componentInstance.gen
+    },
+    flush: () => fixture.detectChanges(),
+    destroy: () => fixture.destroy(),
+  }
+}
+
+const videoResumeSnapshot: GenerationResumeSnapshot = {
+  resumeState: {
+    threadId: 'thread-resume',
+    runId: 'run-resume',
+  },
+  status: 'running',
+}
+
+function createRunContextCaptureAdapter(chunks: Array<StreamChunk>): {
+  adapter: ConnectConnectionAdapter
+  connect: ReturnType<typeof vi.fn>
+  runContexts: Array<RunAgentInputContext | undefined>
+} {
+  const runContexts: Array<RunAgentInputContext | undefined> = []
+  const connect = vi.fn()
+  const adapter: ConnectConnectionAdapter = {
+    async *connect(_messages, _data, _signal, runContext) {
+      connect(runContext)
+      runContexts.push(runContext)
+      for (const chunk of chunks) {
+        yield chunk
+      }
+    },
+  }
+  return { adapter, connect, runContexts }
+}
+
 describe('injectGeneration', () => {
   it('initializes idle with a fetcher and generates a result', async () => {
     const fetcher = vi.fn(async () => ({ value: 42 }))
@@ -68,4 +119,57 @@ describe('injectGeneration', () => {
     expect(result.result()).toEqual({ playable: true })
     expect(result.status()).toBe('success')
   })
+
+  it('does not auto-fire a generation after render from a persisted running snapshot', async () => {
+    // Regression guard for the removed generation resume surface.
+    const snapshot: GenerationResumeSnapshot = {
+      resumeState: { threadId: 'thread-resume', runId: 'run-resume' },
+      status: 'running',
+    }
+    const { adapter, connect } = createRunContextCaptureAdapter([])
+    const getItem = vi.fn(() => snapshot)
+    const { result } = renderInjectGeneration({
+      id: 'no-auto-fire',
+      connection: adapter,
+      persistence: {
+        server: { getItem, setItem: vi.fn(), removeItem: vi.fn() },
+      },
+      initialResumeSnapshot: snapshot,
+    })
+
+    await Promise.resolve()
+
+    expect(connect).not.toHaveBeenCalled()
+    expect(getItem).not.toHaveBeenCalled()
+    expect(result.isLoading()).toBe(false)
+    expect(result.status()).toBe('idle')
+    // The persisted snapshot remains exposed as read-only state.
+    expect(result.resumeState()).toEqual(snapshot.resumeState)
+  })
+})
+
+describe('injectGenerateVideo', () => {
+  it('does not auto-fire a video generation after render from a persisted running snapshot', async () => {
+    // Regression guard for the removed generation resume surface (video).
+    const { adapter, connect } = createRunContextCaptureAdapter([])
+    const getItem = vi.fn(() => videoResumeSnapshot)
+    const { result } = renderInjectGenerateVideo({
+      id: 'video-no-auto-fire',
+      connection: adapter,
+      persistence: {
+        server: { getItem, setItem: vi.fn(), removeItem: vi.fn() },
+      },
+      initialResumeSnapshot: videoResumeSnapshot,
+    })
+
+    await Promise.resolve()
+
+    expect(connect).not.toHaveBeenCalled()
+    expect(getItem).not.toHaveBeenCalled()
+    expect(result.isLoading()).toBe(false)
+    expect(result.status()).toBe('idle')
+    // The persisted snapshot remains exposed as read-only state.
+    expect(result.resumeSnapshot()).toEqual(videoResumeSnapshot)
+    expect(result.resumeState()).toEqual(videoResumeSnapshot.resumeState)
+  })
 })
diff --git a/packages/ai-client/src/chat-client.ts b/packages/ai-client/src/chat-client.ts
index d5ed91a8b..56585ce80 100644
--- a/packages/ai-client/src/chat-client.ts
+++ b/packages/ai-client/src/chat-client.ts
@@ -17,6 +17,7 @@ import type {
   AnyClientTool,
   ContentPart,
   ModelMessage,
+  RunAgentResumeItem,
   StreamChunk,
 } from '@tanstack/ai/client'
 import type {
@@ -34,8 +35,14 @@ import type {
 } from './devtools'
 import type {
   ChatClientOptions,
+  ChatClientPersistence,
   ChatClientState,
   ChatFetcher,
+  ChatPendingInterrupt,
+  ChatPersistenceOptions,
+  ChatResumeSnapshot,
+  ChatResumeState,
+  ChatServerPersistence,
   ConnectionStatus,
   MessagePart,
   MultimodalContent,
@@ -59,6 +66,10 @@ type ChatClientUpdateOptionsWithoutContext<
   onSubscriptionChange?: (isSubscribed: boolean) => void
   onConnectionStatusChange?: (status: ConnectionStatus) => void
   onSessionGeneratingChange?: (isGenerating: boolean) => void
+  onResumeStateChange?: (
+    resumeState: ChatResumeState | null,
+    pendingInterrupts: Array<ChatPendingInterrupt>,
+  ) => void
   onCustomEvent?: (
     eventType: string,
     data: unknown,
@@ -89,6 +100,21 @@ function resolveTransport(transport: {
   throw new Error('ChatClient: either `connection` or `fetcher` is required.')
 }
 
+function normalizePersistence<TTools extends ReadonlyArray<AnyClientTool>>(
+  persistence: ChatPersistenceOptions<TTools> | undefined,
+): {
+  client?: ChatClientPersistence<TTools>
+  server?: ChatServerPersistence
+} {
+  if (!persistence) {
+    return {}
+  }
+  if ('getItem' in persistence) {
+    return { client: persistence }
+  }
+  return persistence
+}
+
 export class ChatClient<
   TTools extends ReadonlyArray<AnyClientTool> = any,
   TContext = unknown,
@@ -101,7 +127,32 @@ export class ChatClient<
   // chunks after a mid-stream clear) live in ChatPersistor so this class stays
   // focused on streaming. Undefined when no `persistence` adapter is configured.
   private readonly persistor?: ChatPersistor
+  private readonly serverPersistence?: ChatServerPersistence
+  private serverPersistenceGeneration = 0
+  // Whether the consumer supplied an `onError` callback. Server-persistence is
+  // best-effort and must never break chat, but its failures should still be
+  // observable: they are routed to the consumer's `onError` when one exists,
+  // otherwise surfaced via `console.warn`.
+  private hasUserOnError = false
+  private disposed = false
   private currentRunId: string | null = null
+  // Interrupt-resume tracking: the run/thread of the most recent interrupted
+  // run, so approvals/client-tool results can be sent back. Cleared when the
+  // run terminates. This is STATE (interrupt) resume, not delivery/cursor.
+  private lastResume: ChatResumeState | null = null
+  private pendingInterrupts: Array<ChatPendingInterrupt> = []
+  private pendingInterruptRunId: string | null = null
+  private readonly pendingInterruptResumeItems = new Map<
+    string,
+    RunAgentResumeItem
+  >()
+  // When set, the next streamResponse() continues this interrupted run instead
+  // of starting a fresh run (consumed once).
+  private pendingResumeRunId: string | null = null
+  private pendingResumeThreadId: string | null = null
+  private pendingResumeItems: Array<RunAgentResumeItem> | null = null
+  private activeResumeThreadId: string | null = null
+  private activeResumeRunId: string | null = null
   // Track the legacy `body` option and the canonical `forwardedProps`
   // option as separate slots so that `updateOptions({ forwardedProps })`
   // doesn't wipe a previously-set `body` (and vice versa). They are
@@ -144,6 +195,8 @@ export class ChatClient<
   private draining = false
   private sessionGenerating = false
   private readonly activeRunIds = new Set<string>()
+  private readonly clearedRunIds = new Set<string>()
+  private clearedRunlessRunId: string | null = null
   private devtoolsMounted = false
 
   private readonly callbacksRef: {
@@ -159,6 +212,10 @@ export class ChatClient<
       onSubscriptionChange: (isSubscribed: boolean) => void
       onConnectionStatusChange: (status: ConnectionStatus) => void
       onSessionGeneratingChange: (isGenerating: boolean) => void
+      onResumeStateChange: (
+        resumeState: ChatResumeState | null,
+        pendingInterrupts: Array<ChatPendingInterrupt>,
+      ) => void
       onCustomEvent: (
         eventType: string,
         data: unknown,
@@ -170,13 +227,16 @@ export class ChatClient<
   constructor(options: ChatClientOptions<TTools, TContext>) {
     this.uniqueId = options.id || this.generateUniqueId('chat')
     this.threadId = options.threadId || this.generateUniqueId('thread')
-    if (options.persistence) {
+    const persistence = normalizePersistence(options.persistence)
+    if (persistence.client) {
       this.persistor = new ChatPersistor(
-        options.persistence,
+        persistence.client,
         this.uniqueId,
         (messages) => this.processor.setMessages(messages),
       )
     }
+    this.serverPersistence = persistence.server
+    this.hasUserOnError = typeof options.onError === 'function'
     // Both `body` (deprecated) and `forwardedProps` populate the AG-UI
     // `RunAgentInput.forwardedProps` wire field. They are stored
     // separately so `updateOptions` can replace one without touching the
@@ -215,10 +275,19 @@ export class ChatClient<
           options.onConnectionStatusChange || (() => {}),
         onSessionGeneratingChange:
           options.onSessionGeneratingChange || (() => {}),
+        onResumeStateChange: options.onResumeStateChange || (() => {}),
         onCustomEvent: options.onCustomEvent || (() => {}),
       },
     }
 
+    const storedResumeSnapshot = options.initialResumeSnapshot
+      ? undefined
+      : this.readInitialResumeSnapshot()
+    const resumeSnapshot = options.initialResumeSnapshot ?? storedResumeSnapshot
+    if (resumeSnapshot && !(resumeSnapshot instanceof Promise)) {
+      this.applyResumeSnapshot(resumeSnapshot)
+    }
+
     // Create StreamProcessor with event handlers.
     // Use conditional spreads so we don't pass `undefined` into
     // `StreamProcessorOptions` fields under `exactOptionalPropertyTypes`.
@@ -433,6 +502,74 @@ export class ChatClient<
     })
 
     this.persistor?.hydrateAsync(persistedMessages)
+    if (
+      !options.initialResumeSnapshot &&
+      storedResumeSnapshot instanceof Promise
+    ) {
+      this.hydrateResumeSnapshotAsync(storedResumeSnapshot)
+    }
+  }
+
+  /**
+   * Route a caught server-persistence error to an observable sink. Server
+   * persistence is best-effort and must never break chat, so callers still
+   * swallow the failure — but it is no longer silent: it goes to the
+   * consumer's `onError` callback when one was provided, otherwise to
+   * `console.warn`.
+   */
+  private reportServerPersistenceError(error: unknown): void {
+    const normalized = error instanceof Error ? error : new Error(String(error))
+    if (this.hasUserOnError) {
+      this.callbacksRef.current.onError(normalized)
+    } else {
+      console.warn(
+        '[TanStack AI] Server persistence adapter error (non-fatal):',
+        normalized,
+      )
+    }
+  }
+
+  private readInitialResumeSnapshot():
+    | ChatResumeSnapshot
+    | null
+    | undefined
+    | Promise<ChatResumeSnapshot | null | undefined> {
+    try {
+      return this.serverPersistence?.getItem(this.threadId)
+    } catch (error) {
+      this.reportServerPersistenceError(error)
+      return undefined
+    }
+  }
+
+  private hydrateResumeSnapshotAsync(
+    snapshot: Promise<ChatResumeSnapshot | null | undefined>,
+  ): void {
+    const generation = this.serverPersistenceGeneration
+    snapshot
+      .then((resolvedSnapshot) => {
+        if (
+          resolvedSnapshot &&
+          !this.lastResume &&
+          !this.disposed &&
+          generation === this.serverPersistenceGeneration
+        ) {
+          this.applyResumeSnapshot(resolvedSnapshot)
+          this.notifyResumeStateChange()
+        }
+      })
+      .catch((error: unknown) => {
+        // Persistence adapters are best-effort and must not break chat setup,
+        // but the failure is surfaced to an observable sink.
+        this.reportServerPersistenceError(error)
+      })
+  }
+
+  private applyResumeSnapshot(snapshot: ChatResumeSnapshot): void {
+    this.lastResume = { ...snapshot.resumeState }
+    this.pendingInterrupts = [...(snapshot.pendingInterrupts ?? [])]
+    this.pendingInterruptRunId =
+      this.pendingInterrupts.length > 0 ? this.lastResume.runId : null
   }
 
   mountDevtools(): void {
@@ -445,17 +582,40 @@ export class ChatClient<
   }
 
   /**
-   * Drain a runId-less RUN_ERROR that belongs to a cleared run the client is
-   * still tracking. The persistor owns the cleared-run bookkeeping; the client
-   * owns the active-run / session / processing state.
+   * Retire cleared-run tracking for ignored terminal chunks without processing
+   * their stale message or resume payloads.
    */
-  private drainIgnoredRunlessChunk(chunk: StreamChunk): void {
-    if (chunk.type !== 'RUN_ERROR') return
-    const runId = this.persistor?.takeRunlessRunId()
+  private retireIgnoredClearedTerminalChunk(chunk: StreamChunk): void {
+    if (chunk.type !== 'RUN_FINISHED' && chunk.type !== 'RUN_ERROR') return
+    const runId =
+      getChunkRunId(chunk) ??
+      this.persistor?.takeRunlessRunId() ??
+      this.clearedRunlessRunId
     if (!runId) return
+    this.clearedRunIds.delete(runId)
+    if (this.clearedRunlessRunId === runId) {
+      this.clearedRunlessRunId = null
+    }
     this.activeRunIds.delete(runId)
     this.setSessionGenerating(this.activeRunIds.size > 0)
-    this.resolveProcessing()
+    if (!getChunkRunId(chunk)) {
+      this.resolveProcessing()
+    }
+  }
+
+  private shouldIgnoreClearedChunk(chunk: StreamChunk): boolean {
+    if (this.persistor) {
+      return false
+    }
+    const runId = getChunkRunId(chunk)
+    if (runId && this.clearedRunIds.has(runId)) {
+      this.clearedRunlessRunId = runId
+      return true
+    }
+    if (!runId && this.clearedRunlessRunId) {
+      return true
+    }
+    return false
   }
 
   private updateRunLifecycle(
@@ -464,6 +624,11 @@ export class ChatClient<
   ): void {
     if (chunk.type === 'RUN_STARTED') {
       const chunkRunId = getChunkRunId(chunk) ?? chunk.runId
+      this.activeResumeThreadId =
+        'threadId' in chunk && typeof chunk.threadId === 'string'
+          ? chunk.threadId
+          : this.activeResumeThreadId
+      this.activeResumeRunId = chunkRunId
       this.activeRunIds.add(chunkRunId)
       this.persistor?.onRunStarted(chunkRunId)
       this.setSessionGenerating(true)
@@ -489,6 +654,91 @@ export class ChatClient<
     }
   }
 
+  /**
+   * Track interrupt state off the stream's terminal events. A RUN_FINISHED with
+   * an interrupt outcome records the pending interrupts + the run/thread to
+   * resume; any other terminal event for the tracked/current run clears that
+   * state. This is interrupt (state) resume — there is no delivery cursor.
+   */
+  private observeInterruptState(chunk: StreamChunk): void {
+    if (chunk.type !== 'RUN_FINISHED' && chunk.type !== 'RUN_ERROR') {
+      return
+    }
+    const runId = getChunkRunId(chunk)
+    const threadId =
+      'threadId' in chunk && typeof chunk.threadId === 'string'
+        ? chunk.threadId
+        : this.activeResumeThreadId
+
+    if (chunk.type === 'RUN_FINISHED' && chunk.outcome?.type === 'interrupt') {
+      // Track the REQUEST run id (what the client sent) so a resume targets the
+      // same run even when provider events carry their own run id.
+      const interruptedRunId =
+        this.currentRunId ?? runId ?? this.activeResumeRunId ?? ''
+      this.lastResume = {
+        threadId: threadId ?? this.threadId,
+        runId: interruptedRunId,
+      }
+      this.pendingInterruptRunId = interruptedRunId
+      this.pendingInterrupts = [...chunk.outcome.interrupts]
+      this.pendingInterruptResumeItems.clear()
+      this.notifyResumeStateChange()
+      return
+    }
+
+    const isRunlessSessionError = chunk.type === 'RUN_ERROR' && !runId
+    const isTrackedRunTerminal = Boolean(
+      runId && this.lastResume?.runId === runId,
+    )
+    const isPendingInterruptRunTerminal = Boolean(
+      runId && this.pendingInterruptRunId === runId,
+    )
+    const isCurrentRunTerminal = Boolean(
+      (runId && this.currentRunId === runId) ||
+      (this.currentRunId && this.lastResume?.runId === this.currentRunId),
+    )
+    const isCurrentStreamTerminal =
+      this.isLoading && chunk.type === 'RUN_FINISHED' && !runId
+    if (
+      isRunlessSessionError ||
+      isTrackedRunTerminal ||
+      isPendingInterruptRunTerminal ||
+      isCurrentRunTerminal ||
+      isCurrentStreamTerminal
+    ) {
+      this.lastResume = null
+      this.pendingInterrupts = []
+      this.pendingInterruptRunId = null
+      this.pendingInterruptResumeItems.clear()
+    }
+    this.notifyResumeStateChange()
+  }
+
+  /**
+   * The interrupt-resume state for the active/interrupted run (its run/thread
+   * ids), or null when there is nothing to resume. Apps can persist this to
+   * resume interrupts across a full reload.
+   */
+  getResumeState(): ChatResumeState | null {
+    return this.lastResume ? { ...this.lastResume } : null
+  }
+
+  getPendingInterrupts(): Array<ChatPendingInterrupt> {
+    return [...this.pendingInterrupts]
+  }
+
+  resumeInterrupts(
+    resume: Array<RunAgentResumeItem>,
+    state?: ChatResumeState,
+  ): Promise<boolean> {
+    const target = state ?? this.lastResume
+    if (!target || this.isLoading) return Promise.resolve(false)
+    this.pendingResumeThreadId = target.threadId
+    this.pendingResumeRunId = target.runId
+    this.pendingResumeItems = [...resume]
+    return this.streamResponse()
+  }
+
   private generateUniqueId(prefix: string): string {
     return `${prefix}-${Date.now()}-${Math.random().toString(36).substring(7)}`
   }
@@ -524,6 +774,82 @@ export class ChatClient<
     this.devtoolsBridge.emitSnapshot()
   }
 
+  private notifyResumeStateChange(): void {
+    const resumeState = this.getResumeState()
+    const pendingInterrupts = this.getPendingInterrupts()
+    this.persistResumeSnapshot(resumeState, pendingInterrupts)
+    this.callbacksRef.current.onResumeStateChange(
+      resumeState,
+      pendingInterrupts,
+    )
+  }
+
+  private persistResumeSnapshot(
+    resumeState: ChatResumeState | null,
+    pendingInterrupts: Array<ChatPendingInterrupt>,
+  ): void {
+    if (!this.serverPersistence) {
+      return
+    }
+
+    try {
+      const generation = ++this.serverPersistenceGeneration
+      const result = resumeState
+        ? this.serverPersistence.setItem(this.threadId, {
+            resumeState,
+            pendingInterrupts,
+          })
+        : this.serverPersistence.removeItem(this.threadId)
+      if (result instanceof Promise) {
+        result
+          .catch((error: unknown) => {
+            // Best-effort: must not break chat, but is surfaced to a sink.
+            this.reportServerPersistenceError(error)
+          })
+          .finally(() => {
+            if (generation !== this.serverPersistenceGeneration) {
+              this.reconcileStaleServerPersistenceWrite()
+            }
+          })
+      }
+    } catch (error) {
+      // Best-effort: must not break chat, but is surfaced to a sink.
+      this.reportServerPersistenceError(error)
+    }
+  }
+
+  private reconcileStaleServerPersistenceWrite(): void {
+    if (!this.serverPersistence) {
+      return
+    }
+
+    try {
+      const generation = this.serverPersistenceGeneration
+      const resumeState = this.getResumeState()
+      const result = resumeState
+        ? this.serverPersistence.setItem(this.threadId, {
+            resumeState,
+            pendingInterrupts: this.getPendingInterrupts(),
+          })
+        : this.serverPersistence.removeItem(this.threadId)
+      if (result instanceof Promise) {
+        result
+          .catch((error: unknown) => {
+            // Best-effort: must not break chat, but is surfaced to a sink.
+            this.reportServerPersistenceError(error)
+          })
+          .finally(() => {
+            if (generation !== this.serverPersistenceGeneration) {
+              this.reconcileStaleServerPersistenceWrite()
+            }
+          })
+      }
+    } catch (error) {
+      // Best-effort: must not break chat, but is surfaced to a sink.
+      this.reportServerPersistenceError(error)
+    }
+  }
+
   private resetSessionGenerating(): void {
     this.activeRunIds.clear()
     this.persistor?.resetIgnored()
@@ -675,14 +1001,15 @@ export class ChatClient<
       if (this.connectionStatus === 'connecting') {
         this.setConnectionStatus('connected')
       }
-      const shouldIgnore = this.persistor?.shouldIgnoreChunk(chunk) ?? false
+      const shouldIgnore =
+        this.shouldIgnoreClearedChunk(chunk) ||
+        (this.persistor?.shouldIgnoreChunk(chunk) ?? false)
       if (shouldIgnore) {
         if (chunk.type === 'RUN_FINISHED' || chunk.type === 'RUN_ERROR') {
           if (getChunkRunId(chunk)) {
             this.updateRunLifecycle(chunk, { resolveProcessing: false })
-          } else {
-            this.drainIgnoredRunlessChunk(chunk)
           }
+          this.retireIgnoredClearedTerminalChunk(chunk)
         }
         continue
       }
@@ -696,6 +1023,7 @@ export class ChatClient<
       // per-run error only clears that run, while a runId-less RUN_ERROR is
       // treated as a session-level error that clears every active run.
       this.updateRunLifecycle(chunk)
+      this.observeInterruptState(chunk)
       // Yield control back to event loop for UI updates
       await new Promise((resolve) => setTimeout(resolve, 0))
     }
@@ -764,7 +1092,7 @@ export class ChatClient<
    *     ],
    *     id: 'custom-message-id'
    *   },
-   *   { model: 'gpt-4-audio' }
+   *   { model: 'gpt-5.5' }
    * )
    * ```
    */
@@ -777,6 +1105,11 @@ export class ChatClient<
     if (emptyMessage || this.isLoading) {
       return
     }
+    if (this.pendingInterrupts.length > 0 && this.lastResume) {
+      throw new Error(
+        'ChatClient: cannot send normal input while pending interrupts exist. Use resumeInterrupts() instead.',
+      )
+    }
     // Normalize input to extract content, id, and validate
     const normalizedContent = this.normalizeMessageInput(content)
 
@@ -812,6 +1145,11 @@ export class ChatClient<
    */
   async append(message: UIMessage | ModelMessage): Promise<void> {
     this.mountDevtools()
+    if (this.pendingInterrupts.length > 0 && this.lastResume) {
+      throw new Error(
+        'ChatClient: cannot append normal input while pending interrupts exist. Use resumeInterrupts() instead.',
+      )
+    }
     // Normalize the message to ensure it has id and createdAt
     const normalizedMessage = normalizeToUIMessage(message, generateMessageId)
 
@@ -854,8 +1192,23 @@ export class ChatClient<
 
     // Track generation so a superseded stream's cleanup doesn't clobber the new one
     const generation = ++this.streamGeneration
-    const runId = `run-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`
+    // Resuming an interrupt reuses the original runId so the server continues
+    // that run with the resume decisions.
+    const resumeThreadId = this.pendingResumeThreadId
+    const resumeRunId = this.pendingResumeRunId
+    const resumeItems = this.pendingResumeItems
+    const isResumeRequest = Boolean(
+      resumeThreadId || resumeRunId || resumeItems,
+    )
+    this.pendingResumeThreadId = null
+    this.pendingResumeRunId = null
+    this.pendingResumeItems = null
+    const runId =
+      resumeRunId ??
+      `run-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`
     this.currentRunId = runId
+    this.activeResumeThreadId = resumeThreadId ?? this.threadId
+    this.activeResumeRunId = runId
 
     this.setIsLoading(true)
     this.setStatus('submitted')
@@ -874,7 +1227,7 @@ export class ChatClient<
 
     try {
       // Get UIMessages with parts (preserves approval state and client tool results)
-      const messages = this.processor.getMessages()
+      const messages = isResumeRequest ? [] : this.processor.getMessages()
       const clientTools = new Map(this.clientToolsRef.current)
       const runtimeContext = this.context
 
@@ -935,7 +1288,7 @@ export class ChatClient<
       // JSON Schema; sending a Standard Schema instance directly would
       // serialize to an unusable shape.
       const runContext = {
-        threadId: this.threadId,
+        threadId: resumeThreadId ?? this.threadId,
         runId,
         clientTools: Array.from(clientTools.values()).map((t) => ({
           name: t.name,
@@ -945,8 +1298,9 @@ export class ChatClient<
             : { type: 'object' },
         })),
         forwardedProps: { ...mergedBody },
+        ...(resumeItems ? { resume: resumeItems } : {}),
       }
-      this.devtoolsBridge.beginRun(runContext.runId, this.threadId)
+      this.devtoolsBridge.beginRun(runContext.runId, runContext.threadId)
       activeDevtoolsRunId = runContext.runId
       this.devtoolsBridge.emitRunLifecycle(
         'run:created',
@@ -963,6 +1317,11 @@ export class ChatClient<
       // Send through normalized connection (pushes chunks to subscription queue)
       await this.connection.send(messages, mergedBody, signal, runContext)
 
+      // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition -- mutated asynchronously during await
+      if (generation !== this.streamGeneration || signal.aborted) {
+        return false
+      }
+
       // Wait for subscription loop to finish processing all chunks
       await processingComplete
 
@@ -1164,24 +1523,40 @@ export class ChatClient<
    * Clear all messages
    */
   clear(): void {
+    const hadLocalStream = this.abortController !== null
+    for (const runId of this.activeRunIds) {
+      this.clearedRunIds.add(runId)
+    }
+    if (this.currentRunId) {
+      this.clearedRunIds.add(this.currentRunId)
+      this.clearedRunlessRunId = this.currentRunId
+    }
     if (this.persistor) {
       this.persistor.snapshotClear({
         messages: this.processor.getMessages(),
         activeRunIds: this.activeRunIds,
         currentRunId: this.currentRunId,
       })
-      if (this.isLoading) {
-        this.cancelInFlightStream({ setReadyStatus: true })
-        this.resetSessionGenerating()
-      } else if (this.activeRunIds.size > 0) {
-        this.resetSessionGenerating()
-      }
       // Suppress persisting the empty snapshot that clearMessages emits, then
       // remove the stored conversation outright.
       this.persistor.beginClear()
     }
+    if (this.isLoading || hadLocalStream) {
+      this.cancelInFlightStream({ setReadyStatus: true })
+      this.resetSessionGenerating()
+    } else if (this.activeRunIds.size > 0) {
+      this.resetSessionGenerating()
+    }
     this.processor.clearMessages()
     this.persistor?.remove()
+    this.lastResume = null
+    this.pendingInterrupts = []
+    this.pendingInterruptRunId = null
+    this.pendingInterruptResumeItems.clear()
+    this.pendingResumeThreadId = null
+    this.pendingResumeRunId = null
+    this.pendingResumeItems = null
+    this.notifyResumeStateChange()
     this.setError(undefined)
     this.events.messagesCleared()
   }
@@ -1234,6 +1609,35 @@ export class ChatClient<
         : undefined,
     )
 
+    const pendingInterrupt = this.pendingInterrupts.find(
+      (interrupt) =>
+        interrupt.toolCallId === result.toolCallId ||
+        interrupt.id === result.toolCallId,
+    )
+    if (pendingInterrupt && this.lastResume) {
+      const resumeItem: RunAgentResumeItem = {
+        interruptId: pendingInterrupt.id,
+        status: 'resolved',
+        payload:
+          result.state === 'output-error'
+            ? { error: result.errorText || 'Tool execution failed' }
+            : result.output,
+      }
+      const resumeItems = this.collectPendingInterruptResumeItems(resumeItem)
+      if (!resumeItems) {
+        return
+      }
+      if (this.isLoading) {
+        this.queuePostStreamAction(async () => {
+          await this.resumeInterrupts(resumeItems)
+        })
+        return
+      }
+
+      await this.resumeInterrupts(resumeItems)
+      return
+    }
+
     // If stream is in progress, queue continuation check for after it ends
     if (this.isLoading) {
       this.queuePostStreamAction(() => this.checkForContinuation())
@@ -1261,6 +1665,9 @@ export class ChatClient<
     id: string // approval.id, not toolCallId
     approved: boolean
   }): Promise<void> {
+    const pendingInterrupt = this.pendingInterrupts.find(
+      (interrupt) => interrupt.id === response.id,
+    )
     // Find the tool call ID from the approval ID
     const messages = this.processor.getMessages()
     let foundToolCallId: string | undefined
@@ -1288,6 +1695,25 @@ export class ChatClient<
     this.processor.addToolApprovalResponse(response.id, response.approved)
     this.devtoolsBridge.emitSnapshot()
 
+    if (pendingInterrupt && this.lastResume) {
+      const resumeItems = this.collectPendingInterruptResumeItems({
+        interruptId: response.id,
+        status: response.approved ? 'resolved' : 'cancelled',
+        payload: { approved: response.approved },
+      })
+      if (!resumeItems) {
+        return
+      }
+      if (this.isLoading) {
+        this.queuePostStreamAction(async () => {
+          await this.resumeInterrupts(resumeItems)
+        })
+        return
+      }
+      await this.resumeInterrupts(resumeItems)
+      return
+    }
+
     // If stream is in progress, queue continuation check for after it ends
     if (this.isLoading) {
       this.queuePostStreamAction(() => this.checkForContinuation())
@@ -1297,6 +1723,23 @@ export class ChatClient<
     await this.checkForContinuation()
   }
 
+  private collectPendingInterruptResumeItems(
+    resumeItem: RunAgentResumeItem,
+  ): Array<RunAgentResumeItem> | null {
+    this.pendingInterruptResumeItems.set(resumeItem.interruptId, resumeItem)
+    const resumeItems: Array<RunAgentResumeItem> = []
+    for (const interrupt of this.pendingInterrupts) {
+      const answeredInterrupt = this.pendingInterruptResumeItems.get(
+        interrupt.id,
+      )
+      if (!answeredInterrupt) {
+        return null
+      }
+      resumeItems.push(answeredInterrupt)
+    }
+    return resumeItems
+  }
+
   /**
    * Queue an action to be executed after the current stream ends
    */
@@ -1499,6 +1942,7 @@ export class ChatClient<
     }
     if (options.onError !== undefined) {
       this.callbacksRef.current.onError = options.onError
+      this.hasUserOnError = true
     }
     if (options.onSubscriptionChange !== undefined) {
       this.callbacksRef.current.onSubscriptionChange =
@@ -1512,12 +1956,19 @@ export class ChatClient<
       this.callbacksRef.current.onSessionGeneratingChange =
         options.onSessionGeneratingChange
     }
+    if (options.onResumeStateChange !== undefined) {
+      this.callbacksRef.current.onResumeStateChange =
+        options.onResumeStateChange
+    }
     if (options.onCustomEvent !== undefined) {
       this.callbacksRef.current.onCustomEvent = options.onCustomEvent
     }
   }
 
   dispose(): void {
+    this.disposed = true
+    this.serverPersistenceGeneration++
+    this.persistor?.dispose()
     this.unsubscribe()
     this.devtoolsBridge.dispose()
     this.devtoolsMounted = false
diff --git a/packages/ai-client/src/client-persistor.ts b/packages/ai-client/src/client-persistor.ts
index 517aaf0a7..d4055be0c 100644
--- a/packages/ai-client/src/client-persistor.ts
+++ b/packages/ai-client/src/client-persistor.ts
@@ -1,6 +1,47 @@
 import { getChunkRunId } from './connection-adapters'
 import type { StreamChunk } from '@tanstack/ai/client'
-import type { ChatClientPersistence, UIMessage } from './types'
+import type {
+  ChatClientPersistence,
+  ChatStorageAdapter,
+  UIMessage,
+} from './types'
+
+export interface LocalStorageAIPersistenceOptions<TValue> {
+  keyPrefix?: string
+  serialize?: (value: TValue) => string
+  deserialize?: (value: string) => TValue
+}
+
+export function localStorageAIPersistence<TValue>(
+  options: LocalStorageAIPersistenceOptions<TValue> = {},
+): ChatStorageAdapter<TValue> {
+  const {
+    keyPrefix = 'tanstack-ai:',
+    serialize = JSON.stringify,
+    deserialize = JSON.parse,
+  } = options
+
+  const getStorage = (): Storage | undefined =>
+    typeof globalThis.localStorage === 'undefined'
+      ? undefined
+      : globalThis.localStorage
+  const getKey = (id: string) => `${keyPrefix}${id}`
+
+  return {
+    getItem(id) {
+      const storage = getStorage()
+      if (!storage) return undefined
+      const item = storage.getItem(getKey(id))
+      return item === null ? null : deserialize(item)
+    },
+    setItem(id, value) {
+      getStorage()?.setItem(getKey(id), serialize(value))
+    },
+    removeItem(id) {
+      getStorage()?.removeItem(getKey(id))
+    },
+  }
+}
 
 // `StreamChunk` is a discriminated union; `toolCallId` / `messageId` /
 // `parentMessageId` exist on only some members. Narrow with `in` (matching
@@ -115,6 +156,12 @@ export class ChatPersistor {
       })
   }
 
+  /** Invalidate in-flight hydration and queued persistence operations. */
+  dispose(): void {
+    this.messagesGeneration++
+    this.generation++
+  }
+
   /**
    * Record a message-list change and queue a `setItem` write for it. Skips a
    * single write after {@link beginClear} so the clear's empty snapshot isn't
diff --git a/packages/ai-client/src/connection-adapters.ts b/packages/ai-client/src/connection-adapters.ts
index 3c4010047..5b1787fab 100644
--- a/packages/ai-client/src/connection-adapters.ts
+++ b/packages/ai-client/src/connection-adapters.ts
@@ -6,6 +6,7 @@ import {
 import { parseSseDataLine } from './sse-utils'
 import type {
   ModelMessage,
+  RunAgentResumeItem,
   RunErrorEvent,
   RunFinishedEvent,
   StreamChunk,
@@ -47,6 +48,20 @@ export class StreamTruncatedError extends Error {
   }
 }
 
+/**
+ * Thrown when a durable (id-tagged) run's stream ends with no terminal event
+ * and a reconnect makes no forward progress — the run cannot complete, so the
+ * consumer must not be left silently hanging on a stream that just stops.
+ */
+export class DurableStreamIncompleteError extends Error {
+  constructor() {
+    super(
+      'Durable run ended without a terminal event and could not resume — the run did not complete.',
+    )
+    this.name = 'DurableStreamIncompleteError'
+  }
+}
+
 function generateRunId(prefix: string): string {
   return `${prefix}-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`
 }
@@ -141,10 +156,16 @@ async function* readStreamLines(
  *
  * A JSON parse failure throws — the consumer surfaces it as an error.
  */
-async function* responseToSSEChunks(
+/**
+ * Yield StreamChunks parsed from an SSE Response body, each paired with the
+ * `id:` offset of the SSE event it arrived on (if any). Delivery durability
+ * tags every event with `id: <runId@seq>`; carrying that id up lets the
+ * resumable adapter track the last offset (for reconnect) and de-dupe replays.
+ */
+async function* responseToSSEEvents(
   response: Response,
   abortSignal?: AbortSignal,
-): AsyncGenerator<StreamChunk> {
+): AsyncGenerator<{ chunk: StreamChunk; id?: string }> {
   if (!response.ok) {
     throw new Error(
       `HTTP error! status: ${response.status} ${response.statusText}`,
@@ -154,11 +175,15 @@ async function* responseToSSEChunks(
   let lastThreadId: string | undefined
   let lastRunId: string | undefined
   let lastModel: string | undefined
+  let pendingId: string | undefined
   for await (const line of readStreamLines(reader, abortSignal)) {
+    if (line.startsWith('id:')) {
+      pendingId = line.slice(3).trim()
+      continue
+    }
     if (
       line.startsWith(':') ||
       line.startsWith('event:') ||
-      line.startsWith('id:') ||
       line.startsWith('retry:')
     ) {
       continue
@@ -173,7 +198,7 @@ async function* responseToSSEChunks(
         timestamp: Date.now(),
         finishReason: 'stop',
       }
-      yield synthetic
+      yield { chunk: synthetic }
       return
     }
     const chunk = JSON.parse(data) as StreamChunk
@@ -186,10 +211,110 @@ async function* responseToSSEChunks(
     if ('model' in chunk && typeof chunk.model === 'string') {
       lastModel = chunk.model
     }
+    const id = pendingId
+    pendingId = undefined
+    yield { chunk, ...(id !== undefined ? { id } : {}) }
+  }
+}
+
+async function* responseToSSEChunks(
+  response: Response,
+  abortSignal?: AbortSignal,
+): AsyncGenerator<StreamChunk> {
+  for await (const { chunk } of responseToSSEEvents(response, abortSignal)) {
     yield chunk
   }
 }
 
+/**
+ * Iterate an SSE endpoint with native-style resumability. Each SSE event's
+ * `id:` (a `runId@seq` delivery-durability offset) is remembered; if the
+ * connection drops or ends before a terminal event, the request is re-issued
+ * with a `Last-Event-ID` header so the server replays strictly after the last
+ * offset. Already-seen offsets are de-duped, so an overlapping replay is safe.
+ *
+ * When the server does NOT tag events (no durability), no offset is ever seen,
+ * so no reconnect happens — behaviour is identical to a plain single fetch.
+ */
+async function* resumableServerSentEvents(
+  fetchClient: typeof globalThis.fetch,
+  url: string,
+  requestInit: RequestInit,
+  abortSignal?: AbortSignal,
+): AsyncGenerator<StreamChunk> {
+  const seen = new Set<string>()
+  let lastEventId: string | undefined
+
+  for (;;) {
+    if (abortSignal?.aborted) return
+    const headers: Record<string, string> = {
+      ...(requestInit.headers as Record<string, string> | undefined),
+    }
+    if (lastEventId !== undefined) {
+      headers['Last-Event-ID'] = lastEventId
+    }
+    const response = await fetchClient(url, {
+      ...requestInit,
+      headers,
+      ...(abortSignal ? { signal: abortSignal } : {}),
+    })
+
+    let sawTerminal = false
+    let progressed = false
+    try {
+      for await (const { chunk, id } of responseToSSEEvents(
+        response,
+        abortSignal,
+      )) {
+        if (id !== undefined) {
+          if (seen.has(id)) continue
+          seen.add(id)
+          lastEventId = id
+        }
+        progressed = true
+        if (chunk.type === 'RUN_FINISHED' || chunk.type === 'RUN_ERROR') {
+          sawTerminal = true
+        }
+        yield chunk
+        if (sawTerminal) return
+      }
+    } catch (error) {
+      if (abortSignal?.aborted) return
+      // A truncated connection is resumable only if we have an offset and made
+      // forward progress; otherwise surface the failure.
+      if (
+        error instanceof StreamTruncatedError &&
+        lastEventId !== undefined &&
+        progressed
+      ) {
+        continue
+      }
+      throw error
+    }
+
+    if (abortSignal?.aborted) return
+
+    if (lastEventId !== undefined) {
+      // A durable (id-tagged) run.
+      if (progressed) {
+        // Clean end WITHOUT a terminal event but we advanced — the producer is
+        // still going (or the socket rolled over). Reconnect from the last
+        // offset.
+        continue
+      }
+      // Ended without a terminal event AND made no forward progress on this
+      // pass: the run cannot complete. Surface an error rather than returning
+      // silently, which would leave the consumer with neither a terminal event
+      // nor a failure.
+      throw new DurableStreamIncompleteError()
+    }
+
+    // A non-durable (untagged) stream that ended cleanly. Legitimate — the
+    // upper layer synthesizes a terminal event. Stop.
+    return
+  }
+}
+
 /**
  * Per-send context provided by the chat client to the connection adapter.
  * The adapter combines this with serialized messages to build a full
@@ -199,6 +324,8 @@ export interface RunAgentInputContext {
   threadId: string
   runId: string
   parentRunId?: string
+  /** AG-UI interrupt resume entries returned to the server on a follow-up run. */
+  resume?: Array<RunAgentResumeItem>
   /** Client-declared tools to advertise in the request payload. */
   clientTools?: Array<{
     name: string
@@ -221,6 +348,22 @@ export interface ConnectConnectionAdapter {
   ) => AsyncIterable<StreamChunk>
 }
 
+/**
+ * A {@link ConnectConnectionAdapter} that also supports joining an existing run
+ * (a second tab, or re-attaching after a full reload) via `joinRun`, replaying
+ * the ordered stream from the start off the server's delivery-durability sink.
+ */
+export interface ResumableConnectConnectionAdapter extends ConnectConnectionAdapter {
+  /**
+   * Join an in-flight or finished run by id, replaying from the start
+   * (`?offset=-1`). Read-only — sends no messages.
+   */
+  joinRun: (
+    runId: string,
+    abortSignal?: AbortSignal,
+  ) => AsyncIterable<StreamChunk>
+}
+
 export interface SubscribeConnectionAdapter {
   /**
    * Subscribe to stream chunks.
@@ -443,6 +586,7 @@ function buildRunAgentInputBody(
     ...(runContext?.parentRunId !== undefined && {
       parentRunId: runContext.parentRunId,
     }),
+    ...(runContext?.resume !== undefined && { resume: runContext.resume }),
     state: {},
     messages: wireMessages,
     tools: runContext?.clientTools ?? [],
@@ -482,7 +626,7 @@ function buildRunAgentInputBody(
  * const connection = fetchServerSentEvents('/api/chat', async () => ({
  *   body: {
  *     provider: 'openai',
- *     model: 'gpt-4o',
+ *     model: 'gpt-5.5',
  *   }
  * }));
  * ```
@@ -492,7 +636,7 @@ export function fetchServerSentEvents(
   options:
     | FetchConnectionOptions
     | (() => FetchConnectionOptions | Promise<FetchConnectionOptions>) = {},
-): ConnectConnectionAdapter {
+): ResumableConnectConnectionAdapter {
   return {
     async *connect(messages, data, abortSignal, runContext) {
       // Resolve URL and options if they are functions
@@ -524,15 +668,52 @@ export function fetchServerSentEvents(
       // under `exactOptionalPropertyTypes`), so spread it conditionally
       // rather than passing `undefined` explicitly.
       const signal = abortSignal || resolvedOptions.signal
-      const response = await fetchClient(resolvedUrl, {
-        method: 'POST',
-        headers: requestHeaders,
-        body: JSON.stringify(requestBody),
-        credentials: resolvedOptions.credentials || 'same-origin',
-        ...(signal ? { signal } : {}),
-      })
 
-      yield* responseToSSEChunks(response, abortSignal)
+      // Resumable SSE: if the server tags events with `id:` offsets (delivery
+      // durability), a dropped/rolled-over connection auto-reconnects with a
+      // `Last-Event-ID` header and de-dupes the replayed prefix. With no tags,
+      // this is a single plain fetch.
+      yield* resumableServerSentEvents(
+        fetchClient,
+        resolvedUrl,
+        {
+          method: 'POST',
+          headers: requestHeaders,
+          body: JSON.stringify(requestBody),
+          credentials: resolvedOptions.credentials || 'same-origin',
+        },
+        signal,
+      )
+    },
+    async *joinRun(runId, abortSignal) {
+      // Read an in-flight or finished run from the start. `?offset=-1` tells the
+      // server's delivery-durability sink to replay from the beginning; `runId`
+      // identifies which run. This is a read-only GET — no messages are sent.
+      const resolvedUrl = typeof url === 'function' ? url() : url
+      const resolvedOptions =
+        typeof options === 'function' ? await options() : options
+
+      const separator = resolvedUrl.includes('?') ? '&' : '?'
+      const joinUrl = `${resolvedUrl}${separator}offset=-1&runId=${encodeURIComponent(
+        runId,
+      )}`
+
+      const requestHeaders: Record<string, string> = {
+        ...mergeHeaders(resolvedOptions.headers),
+      }
+      const fetchClient = resolvedOptions.fetchClient ?? fetch
+      const signal = abortSignal || resolvedOptions.signal
+
+      yield* resumableServerSentEvents(
+        fetchClient,
+        joinUrl,
+        {
+          method: 'GET',
+          headers: requestHeaders,
+          credentials: resolvedOptions.credentials || 'same-origin',
+        },
+        signal,
+      )
     },
   }
 }
@@ -566,7 +747,7 @@ export function fetchServerSentEvents(
  * const connection = fetchHttpStream('/api/chat', async () => ({
  *   body: {
  *     provider: 'openai',
- *     model: 'gpt-4o',
+ *     model: 'gpt-5.5',
  *   }
  * }));
  * ```
@@ -941,13 +1122,14 @@ export function stream(
     messages: Array<UIMessage> | Array<ModelMessage>,
     data?: Record<string, any>,
     abortSignal?: AbortSignal,
+    runContext?: RunAgentInputContext,
   ) => AsyncIterable<StreamChunk>,
 ): ConnectConnectionAdapter {
   return {
-    async *connect(messages, data, abortSignal) {
+    async *connect(messages, data, abortSignal, runContext) {
       // Pass messages as-is (UIMessages with parts preserved)
       // Server-side chat() handles conversion to ModelMessages
-      yield* streamFactory(messages, data, abortSignal)
+      yield* streamFactory(messages, data, abortSignal, runContext)
     },
   }
 }
@@ -982,6 +1164,7 @@ export function fetcherToConnectionAdapter(
           data,
           threadId: runContext.threadId,
           runId: runContext.runId,
+          ...(runContext.resume !== undefined && { resume: runContext.resume }),
         },
         { signal: abortSignal },
       )
@@ -1047,13 +1230,14 @@ export function rpcStream(
     messages: Array<UIMessage> | Array<ModelMessage>,
     data?: Record<string, any>,
     abortSignal?: AbortSignal,
+    runContext?: RunAgentInputContext,
   ) => AsyncIterable<StreamChunk>,
 ): ConnectConnectionAdapter {
   return {
-    async *connect(messages, data, abortSignal) {
+    async *connect(messages, data, abortSignal, runContext) {
       // Pass messages as-is (UIMessages with parts preserved)
       // Server-side chat() handles conversion to ModelMessages
-      yield* rpcCall(messages, data, abortSignal)
+      yield* rpcCall(messages, data, abortSignal, runContext)
     },
   }
 }
diff --git a/packages/ai-client/src/generation-client.ts b/packages/ai-client/src/generation-client.ts
index 2284c0b1c..23c74675d 100644
--- a/packages/ai-client/src/generation-client.ts
+++ b/packages/ai-client/src/generation-client.ts
@@ -1,4 +1,7 @@
-import { GENERATION_EVENTS } from './generation-types'
+import {
+  GENERATION_EVENTS,
+  updateGenerationResumeSnapshot,
+} from './generation-types'
 import { createNoOpGenerationDevtoolsBridge } from './devtools-noop'
 import { parseSSEResponse } from './sse-parser'
 import type { StreamChunk } from '@tanstack/ai/client'
@@ -16,6 +19,8 @@ import type {
   GenerationClientOptions,
   GenerationClientState,
   GenerationFetcher,
+  GenerationResumeSnapshot,
+  GenerationServerPersistence,
 } from './generation-types'
 
 /**
@@ -33,6 +38,9 @@ interface GenerationCallbacks<TResult, TOutput> {
   onLoadingChange?: ((isLoading: boolean) => void) | undefined
   onErrorChange?: ((error: Error | undefined) => void) | undefined
   onStatusChange?: ((status: GenerationClientState) => void) | undefined
+  onResumeSnapshotChange?:
+    | ((snapshot: GenerationResumeSnapshot) => void)
+    | undefined
 }
 
 /**
@@ -81,6 +89,7 @@ export class GenerationClient<
   private readonly devtoolsMetadata: AIDevtoolsClientMetadata
   private readonly devtoolsBridge: GenerationDevtoolsBridge<TOutput>
   private readonly threadId: string
+  private readonly serverPersistence: GenerationServerPersistence | undefined
   private body: Record<string, any>
   private result: TOutput | null = null
   private input: TInput | null = null
@@ -88,9 +97,13 @@ export class GenerationClient<
   private isLoading = false
   private error: Error | undefined = undefined
   private status: GenerationClientState = 'idle'
+  private resumeSnapshot: GenerationResumeSnapshot | undefined
+  private resumeSnapshotPersistenceQueue: Promise<void> = Promise.resolve()
+  private resumePersistenceError: Error | undefined = undefined
   private abortController: AbortController | null = null
   private readonly callbacksRef: GenerationCallbacks<TResult, TOutput>
   private devtoolsMounted = false
+  private disposed = false
 
   constructor(
     options: GenerationClientOptions<TInput, TResult, TOutput> &
@@ -107,6 +120,8 @@ export class GenerationClient<
     this.connection = options.connection
     this.fetcher = options.fetcher
     this.body = options.body ?? {}
+    this.serverPersistence = options.persistence?.server
+    this.resumeSnapshot = options.initialResumeSnapshot
 
     this.callbacksRef = {
       onResult: options.onResult,
@@ -117,6 +132,7 @@ export class GenerationClient<
       onLoadingChange: options.onLoadingChange,
       onErrorChange: options.onErrorChange,
       onStatusChange: options.onStatusChange,
+      onResumeSnapshotChange: options.onResumeSnapshotChange,
     }
 
     this.devtoolsMetadata = this.createDevtoolsMetadata(options.devtools)
@@ -159,6 +175,7 @@ export class GenerationClient<
    */
   async generate(input: TInput): Promise<void> {
     this.mountDevtools()
+    if (this.disposed) return
     if (this.isLoading) return
 
     this.input = input
@@ -179,11 +196,16 @@ export class GenerationClient<
         if (signal.aborted) return
         if (result instanceof Response) {
           // Server function returned SSE Response — parse stream
-          await this.processStream(parseSSEResponse(result, signal), runId)
+          await this.processStream(
+            parseSSEResponse(result, signal),
+            runId,
+            signal,
+          )
         } else {
           this.devtoolsBridge.ensureRunStarted(runId)
           this.setResult(result)
           this.setStatus('success')
+          this.completePlainFetcherResumeSnapshot()
         }
       } else if (this.connection) {
         // Streaming adapter path
@@ -194,7 +216,7 @@ export class GenerationClient<
           signal,
           this.createRunContext(runId),
         )
-        await this.processStream(stream, runId)
+        await this.processStream(stream, runId, signal)
       } else {
         throw new Error(
           'GenerationClient requires either a connection or fetcher option',
@@ -225,8 +247,10 @@ export class GenerationClient<
       )
       this.callbacksRef.onError?.(error)
     } finally {
-      this.abortController = null
-      this.setIsLoading(false)
+      if (this.abortController === abortController) {
+        this.abortController = null
+        this.setIsLoading(false)
+      }
     }
   }
 
@@ -236,13 +260,15 @@ export class GenerationClient<
   private async processStream(
     source: AsyncIterable<StreamChunk>,
     fallbackRunId: string,
+    signal: AbortSignal,
   ): Promise<void> {
     let streamRunId: string | undefined
 
     for await (const chunk of source) {
-      if (this.abortController?.signal.aborted) break
+      if (signal.aborted) break
 
       this.callbacksRef.onChunk?.(chunk)
+      this.observeResumeSnapshot(chunk)
       const chunkRunId =
         'runId' in chunk && typeof chunk.runId === 'string'
           ? chunk.runId
@@ -352,6 +378,7 @@ export class GenerationClient<
   }
 
   dispose(): void {
+    this.disposed = true
     this.stop()
     this.devtoolsBridge.dispose()
     this.devtoolsMounted = false
@@ -373,10 +400,41 @@ export class GenerationClient<
     return this.error
   }
 
+  getResumePersistenceError(): Error | undefined {
+    return this.resumePersistenceError
+  }
+
   getStatus(): GenerationClientState {
     return this.status
   }
 
+  getResumeSnapshot(): GenerationResumeSnapshot | undefined {
+    return this.resumeSnapshot
+      ? {
+          ...this.resumeSnapshot,
+          ...(this.resumeSnapshot.pendingArtifacts
+            ? { pendingArtifacts: [...this.resumeSnapshot.pendingArtifacts] }
+            : {}),
+          ...(this.resumeSnapshot.result
+            ? {
+                result: {
+                  ...this.resumeSnapshot.result,
+                  ...(this.resumeSnapshot.result.artifacts
+                    ? { artifacts: [...this.resumeSnapshot.result.artifacts] }
+                    : {}),
+                },
+              }
+            : {}),
+          ...(this.resumeSnapshot.error
+            ? { error: { ...this.resumeSnapshot.error } }
+            : {}),
+          ...(this.resumeSnapshot.lastEvent
+            ? { lastEvent: { ...this.resumeSnapshot.lastEvent } }
+            : {}),
+        }
+      : undefined
+  }
+
   // ===========================
   // Private state setters
   // ===========================
@@ -466,6 +524,58 @@ export class GenerationClient<
       runId,
     }
   }
+
+  private observeResumeSnapshot(chunk: StreamChunk): void {
+    this.resumeSnapshot = updateGenerationResumeSnapshot(
+      this.resumeSnapshot,
+      chunk,
+    )
+    this.callbacksRef.onResumeSnapshotChange?.(this.resumeSnapshot)
+    void this.persistResumeSnapshot(this.resumeSnapshot)
+  }
+
+  private completePlainFetcherResumeSnapshot(): void {
+    if (!this.resumeSnapshot) {
+      return
+    }
+    this.resumeSnapshot = {
+      ...this.resumeSnapshot,
+      resumeState: null,
+      status: 'complete',
+    }
+    this.callbacksRef.onResumeSnapshotChange?.(this.resumeSnapshot)
+    void this.persistResumeSnapshot(this.resumeSnapshot)
+  }
+
+  private async persistResumeSnapshot(
+    snapshot: GenerationResumeSnapshot,
+  ): Promise<void> {
+    if (!this.serverPersistence) {
+      return
+    }
+
+    this.resumeSnapshotPersistenceQueue =
+      this.resumeSnapshotPersistenceQueue.then(
+        () => this.writeResumeSnapshot(snapshot),
+        () => this.writeResumeSnapshot(snapshot),
+      )
+    await this.resumeSnapshotPersistenceQueue
+  }
+
+  private async writeResumeSnapshot(
+    snapshot: GenerationResumeSnapshot,
+  ): Promise<void> {
+    try {
+      await this.serverPersistence?.setItem(this.threadId, snapshot)
+    } catch (error) {
+      this.resumePersistenceError =
+        error instanceof Error ? error : new Error(String(error))
+      console.warn(
+        '[TanStack AI] Failed to persist generation resume snapshot',
+        error,
+      )
+    }
+  }
 }
 
 function completeProgressValue(
diff --git a/packages/ai-client/src/generation-types.ts b/packages/ai-client/src/generation-types.ts
index b11e8ca2a..53194e3a0 100644
--- a/packages/ai-client/src/generation-types.ts
+++ b/packages/ai-client/src/generation-types.ts
@@ -1,4 +1,8 @@
-import type { MediaPrompt, StreamChunk } from '@tanstack/ai/client'
+import type {
+  MediaPrompt,
+  PersistedArtifactRef,
+  StreamChunk,
+} from '@tanstack/ai/client'
 import type { TranscriptionResponseFormat } from '@tanstack/ai'
 import type { ConnectConnectionAdapter } from './connection-adapters'
 import type { AIDevtoolsClientMetadata } from './devtools'
@@ -58,6 +62,61 @@ export type InferGenerationOutput<TResult, TFn> = TFn extends (
  */
 export type GenerationClientState = 'idle' | 'generating' | 'success' | 'error'
 
+export type GenerationResumeStatus = 'idle' | 'running' | 'complete' | 'error'
+
+export interface GenerationResumeState {
+  threadId: string
+  runId: string
+}
+
+export type GenerationPendingArtifact = PersistedArtifactRef
+
+export interface GenerationResultSnapshot {
+  id?: string
+  model?: string
+  status?: string
+  jobId?: string
+  expiresAt?: string
+  artifacts?: Array<PersistedArtifactRef>
+}
+
+export interface GenerationErrorSnapshot {
+  message: string
+  code?: string
+}
+
+export interface GenerationEventSnapshot {
+  type: StreamChunk['type']
+  name?: string
+  timestamp?: number
+}
+
+export interface GenerationResumeSnapshot {
+  resumeState: GenerationResumeState | null
+  status: GenerationResumeStatus
+  activity?: PersistedArtifactRef['source']['activity']
+  pendingArtifacts?: Array<GenerationPendingArtifact>
+  result?: GenerationResultSnapshot
+  error?: GenerationErrorSnapshot
+  lastEvent?: GenerationEventSnapshot
+}
+
+export interface GenerationServerPersistence {
+  getItem: (
+    id: string,
+  ) =>
+    | GenerationResumeSnapshot
+    | null
+    | undefined
+    | Promise<GenerationResumeSnapshot | null | undefined>
+  setItem: (id: string, value: GenerationResumeSnapshot) => void | Promise<void>
+  removeItem: (id: string) => void | Promise<void>
+}
+
+export interface GenerationPersistenceOptions {
+  server?: GenerationServerPersistence
+}
+
 // ===========================
 // Event Constants
 // ===========================
@@ -70,6 +129,8 @@ export type GenerationClientState = 'idle' | 'generating' | 'success' | 'error'
 export const GENERATION_EVENTS = {
   /** The generation result payload */
   RESULT: 'generation:result',
+  /** Persisted artifact refs for generated media */
+  ARTIFACTS: 'generation:artifacts',
   /** Progress update (0-100) with optional message */
   PROGRESS: 'generation:progress',
   /** Video job created with jobId */
@@ -135,6 +196,20 @@ export interface GenerationClientOptions<_TInput, TResult, TOutput = TResult> {
   /** Metadata used to register this generation hook with TanStack AI Devtools */
   devtools?: Partial<AIDevtoolsClientMetadata>
 
+  /**
+   * Initial lightweight resume snapshot restored by framework hooks. Contains
+   * only observed run metadata, errors, and persisted artifact refs. This is
+   * read-only state for display; it does not trigger any generation.
+   */
+  initialResumeSnapshot?: GenerationResumeSnapshot
+
+  /**
+   * Optional persistence adapters for lightweight generation state.
+   * Generation hooks only support `server` persistence; generated media bytes
+   * are never written into browser storage by this client.
+   */
+  persistence?: GenerationPersistenceOptions
+
   /**
    * Factory that constructs the devtools bridge. Default is a no-op
    * factory; the real implementation lives in `@tanstack/ai-client/devtools`.
@@ -166,6 +241,63 @@ export interface GenerationClientOptions<_TInput, TResult, TOutput = TResult> {
   onErrorChange?: (error: Error | undefined) => void
   /** @internal Called when generation status changes */
   onStatusChange?: (status: GenerationClientState) => void
+  /** @internal Called when lightweight resume snapshot changes */
+  onResumeSnapshotChange?: (snapshot: GenerationResumeSnapshot) => void
+}
+
+export function updateGenerationResumeSnapshot(
+  previous: GenerationResumeSnapshot | null | undefined,
+  chunk: StreamChunk,
+): GenerationResumeSnapshot {
+  const threadId = stringField(chunk, 'threadId')
+  const runId = stringField(chunk, 'runId')
+  const previousArtifacts = previous?.pendingArtifacts ?? []
+  const next: GenerationResumeSnapshot = {
+    resumeState: previous?.resumeState ?? null,
+    status: previous?.status ?? 'idle',
+    ...(previous?.activity ? { activity: previous.activity } : {}),
+    ...(previousArtifacts.length > 0
+      ? { pendingArtifacts: [...previousArtifacts] }
+      : {}),
+    ...(previous?.result ? { result: { ...previous.result } } : {}),
+    ...(previous?.error ? { error: { ...previous.error } } : {}),
+    lastEvent: createGenerationEventSnapshot(chunk),
+  }
+
+  if (threadId && runId) {
+    next.resumeState = { threadId, runId }
+    next.status = 'running'
+  } else if (chunk.type === 'RUN_STARTED') {
+    next.status = 'running'
+  }
+
+  if (chunk.type === 'CUSTOM') {
+    if (chunk.name === GENERATION_EVENTS.ARTIFACTS) {
+      const artifacts = collectArtifactRefs(chunk.value)
+      if (artifacts.length > 0) {
+        next.pendingArtifacts = artifacts
+        next.activity = artifacts[0]?.source.activity
+      }
+    } else if (chunk.name === GENERATION_EVENTS.RESULT) {
+      const result = createGenerationResultSnapshot(chunk.value)
+      if (result) {
+        next.result = result
+        if (result.artifacts && result.artifacts.length > 0) {
+          next.pendingArtifacts = result.artifacts
+          next.activity = result.artifacts[0]?.source.activity
+        }
+      }
+    }
+  } else if (chunk.type === 'RUN_FINISHED') {
+    next.resumeState = null
+    next.status = 'complete'
+  } else if (chunk.type === 'RUN_ERROR') {
+    next.resumeState = null
+    next.status = 'error'
+    next.error = createGenerationErrorSnapshot(chunk)
+  }
+
+  return next
 }
 
 // ===========================
@@ -200,6 +332,8 @@ export interface VideoGenerateResult {
   url: string
   /** When the URL expires, if applicable */
   expiresAt?: Date
+  /** Persisted artifact references for generated assets, when available */
+  artifacts?: Array<PersistedArtifactRef>
 }
 
 /**
@@ -328,3 +462,214 @@ export interface VideoGenerateInput {
   /** Model-specific options */
   modelOptions?: Record<string, any>
 }
+
+function createGenerationEventSnapshot(
+  chunk: StreamChunk,
+): GenerationEventSnapshot {
+  const name = stringField(chunk, 'name')
+  const timestamp = numberField(chunk, 'timestamp')
+  return {
+    type: chunk.type,
+    ...(name ? { name } : {}),
+    ...(timestamp !== undefined ? { timestamp } : {}),
+  }
+}
+
+function createGenerationResultSnapshot(
+  value: unknown,
+): GenerationResultSnapshot | undefined {
+  if (!isObject(value)) return undefined
+
+  const artifacts = collectArtifactRefs(Reflect.get(value, 'artifacts'))
+  const snapshot: GenerationResultSnapshot = {}
+  const id = stringField(value, 'id')
+  const model = stringField(value, 'model')
+  const status = stringField(value, 'status')
+  const jobId = stringField(value, 'jobId')
+  if (id) snapshot.id = id
+  if (model) snapshot.model = model
+  if (status) snapshot.status = status
+  if (jobId) snapshot.jobId = jobId
+  const expiresAt = Reflect.get(value, 'expiresAt')
+  if (typeof expiresAt === 'string') {
+    snapshot.expiresAt = expiresAt
+  } else if (expiresAt instanceof Date) {
+    snapshot.expiresAt = expiresAt.toISOString()
+  }
+  if (artifacts.length > 0) {
+    snapshot.artifacts = artifacts
+  }
+
+  return Object.keys(snapshot).length > 0 ? snapshot : undefined
+}
+
+function createGenerationErrorSnapshot(
+  chunk: StreamChunk,
+): GenerationErrorSnapshot {
+  const message =
+    stringField(chunk, 'message') ??
+    nestedStringField(chunk, 'error', 'message') ??
+    'An error occurred'
+  const code = stringField(chunk, 'code')
+  return {
+    message,
+    ...(code ? { code } : {}),
+  }
+}
+
+function collectArtifactRefs(value: unknown): Array<PersistedArtifactRef> {
+  if (!Array.isArray(value)) return []
+  const refs: Array<PersistedArtifactRef> = []
+  for (const item of value) {
+    const ref = createPersistedArtifactRefSnapshot(item)
+    if (ref) {
+      refs.push(ref)
+    }
+  }
+  return refs
+}
+
+function createPersistedArtifactRefSnapshot(
+  value: unknown,
+): PersistedArtifactRef | undefined {
+  if (!isObject(value)) return undefined
+  const source = Reflect.get(value, 'source')
+  if (!isObject(source)) return undefined
+
+  const role = persistedArtifactRoleField(value, 'role')
+  const artifactId = stringField(value, 'artifactId')
+  const threadId = stringField(value, 'threadId')
+  const runId = stringField(value, 'runId')
+  const name = stringField(value, 'name')
+  const mimeType = stringField(value, 'mimeType')
+  const size = numberField(value, 'size')
+  const createdAt = stringField(value, 'createdAt')
+  const activity = persistedArtifactActivityField(source, 'activity')
+  const path = stringField(source, 'path')
+  const provider = stringField(source, 'provider')
+  const model = stringField(source, 'model')
+  if (
+    !role ||
+    !artifactId ||
+    !threadId ||
+    !runId ||
+    !name ||
+    !mimeType ||
+    size === undefined ||
+    !createdAt ||
+    !activity ||
+    !path ||
+    !provider ||
+    !model
+  ) {
+    return undefined
+  }
+
+  const externalUrl = durableUrlField(value, 'externalUrl')
+  const mediaType = persistedArtifactMediaTypeField(source, 'mediaType')
+  const jobId = stringField(source, 'jobId')
+  const expiresAt = stringField(source, 'expiresAt')
+
+  return {
+    role,
+    artifactId,
+    threadId,
+    runId,
+    name,
+    mimeType,
+    size,
+    createdAt,
+    ...(externalUrl ? { externalUrl } : {}),
+    source: {
+      activity,
+      path,
+      provider,
+      model,
+      ...(mediaType ? { mediaType } : {}),
+      ...(jobId ? { jobId } : {}),
+      ...(expiresAt ? { expiresAt } : {}),
+    },
+  }
+}
+
+function durableUrlField(value: object, key: string): string | undefined {
+  const field = stringField(value, key)
+  if (!field || field.length > 2048) return undefined
+  try {
+    const url = new URL(field)
+    return url.protocol === 'http:' || url.protocol === 'https:'
+      ? field
+      : undefined
+  } catch {
+    return undefined
+  }
+}
+
+function persistedArtifactRoleField(
+  value: object,
+  key: string,
+): PersistedArtifactRef['role'] | undefined {
+  const field = stringField(value, key)
+  return field === 'input' || field === 'output' ? field : undefined
+}
+
+function persistedArtifactActivityField(
+  value: object,
+  key: string,
+): PersistedArtifactRef['source']['activity'] | undefined {
+  const field = stringField(value, key)
+  if (field === undefined) return undefined
+
+  switch (field) {
+    case 'image':
+    case 'audio':
+    case 'tts':
+    case 'video':
+    case 'transcription':
+      return field
+    default:
+      return undefined
+  }
+}
+
+function persistedArtifactMediaTypeField(
+  value: object,
+  key: string,
+): PersistedArtifactRef['source']['mediaType'] | undefined {
+  const field = stringField(value, key)
+  if (field === undefined) return undefined
+
+  switch (field) {
+    case 'image':
+    case 'audio':
+    case 'video':
+    case 'document':
+    case 'json':
+      return field
+    default:
+      return undefined
+  }
+}
+
+function nestedStringField(
+  value: object,
+  key: string,
+  nestedKey: string,
+): string | undefined {
+  const nested = Reflect.get(value, key)
+  return isObject(nested) ? stringField(nested, nestedKey) : undefined
+}
+
+function stringField(value: object, key: string): string | undefined {
+  const field = Reflect.get(value, key)
+  return typeof field === 'string' ? field : undefined
+}
+
+function numberField(value: object, key: string): number | undefined {
+  const field = Reflect.get(value, key)
+  return typeof field === 'number' ? field : undefined
+}
+
+function isObject(value: unknown): value is object {
+  return typeof value === 'object' && value !== null
+}
diff --git a/packages/ai-client/src/index.ts b/packages/ai-client/src/index.ts
index bd9270ff6..53fefb69e 100644
--- a/packages/ai-client/src/index.ts
+++ b/packages/ai-client/src/index.ts
@@ -21,9 +21,15 @@ export type {
   ThinkingPart,
   StructuredOutputPart,
   // Client configuration types
+  ChatStorageAdapter,
   ChatClientPersistence,
+  ChatServerPersistence,
+  ChatPersistenceOptions,
   ChatClientOptions,
+  ChatPendingInterrupt,
   ClientContextOptionFromTools,
+  ChatResumeState,
+  ChatResumeSnapshot,
   ChatRequestBody,
   InferChatMessages,
   InferredClientContext,
@@ -36,11 +42,22 @@ export type {
   DistributedOmit,
   MultimodalContent,
 } from './types'
+export { localStorageAIPersistence } from './client-persistor'
+export type { LocalStorageAIPersistenceOptions } from './client-persistor'
 // Generation client types
 export type {
   InferGenerationOutput,
   InferGenerationOutputFromReturn,
   GenerationClientState,
+  GenerationResumeState,
+  GenerationResumeStatus,
+  GenerationResumeSnapshot,
+  GenerationPendingArtifact,
+  GenerationResultSnapshot,
+  GenerationErrorSnapshot,
+  GenerationEventSnapshot,
+  GenerationServerPersistence,
+  GenerationPersistenceOptions,
   GenerationClientOptions,
   GenerationFetcher,
   GenerationFetcherOptions,
@@ -55,7 +72,10 @@ export type {
   SummarizeGenerateInput,
   VideoGenerateInput,
 } from './generation-types'
-export { GENERATION_EVENTS } from './generation-types'
+export {
+  GENERATION_EVENTS,
+  updateGenerationResumeSnapshot,
+} from './generation-types'
 export { UnsupportedResponseStreamError } from './response-stream'
 export { clientTools, createChatClientOptions } from './types'
 export {
@@ -72,7 +92,15 @@ export type {
   ExtractToolInput,
   ExtractToolOutput,
 } from './tool-types'
-export type { AnyClientTool } from '@tanstack/ai/client'
+export type {
+  AnyClientTool,
+  Interrupt,
+  PersistedArtifactActivity,
+  PersistedArtifactRef,
+  PersistedArtifactRole,
+  RunAgentResumeItem,
+  RunFinishedOutcome,
+} from '@tanstack/ai/client'
 export type {
   RealtimeAdapter,
   RealtimeConnection,
@@ -88,9 +116,11 @@ export {
   stream,
   rpcStream,
   StreamTruncatedError,
+  DurableStreamIncompleteError,
   type ConnectConnectionAdapter,
   type ConnectionAdapter,
   type FetchConnectionOptions,
+  type ResumableConnectConnectionAdapter,
   type RunAgentInputContext,
   type SubscribeConnectionAdapter,
   type XhrConnectionOptions,
diff --git a/packages/ai-client/src/types.ts b/packages/ai-client/src/types.ts
index 25e07c42b..52ee48fbb 100644
--- a/packages/ai-client/src/types.ts
+++ b/packages/ai-client/src/types.ts
@@ -7,7 +7,9 @@ import type {
   ImagePart,
   InferToolInput,
   InferToolOutput,
+  Interrupt,
   ModelMessage,
+  RunAgentResumeItem,
   StreamChunk,
   StructuredOutputPart,
   UIResourcePart,
@@ -17,7 +19,19 @@ import type { ConnectionAdapter } from './connection-adapters'
 import type { AIDevtoolsClientMetadata } from './devtools'
 import type { ChatDevtoolsBridgeFactory } from './devtools-noop'
 
-export type { StructuredOutputPart } from '@tanstack/ai/client'
+export type { StructuredOutputPart }
+
+export interface ChatResumeState {
+  threadId: string
+  runId: string
+}
+
+export type ChatPendingInterrupt = Interrupt
+
+export interface ChatResumeSnapshot {
+  resumeState: ChatResumeState
+  pendingInterrupts?: Array<ChatPendingInterrupt>
+}
 
 /**
  * `messages` is the full UIMessage history (not a delta). `data` is the
@@ -31,6 +45,7 @@ export interface ChatFetcherInput {
   data?: Record<string, unknown>
   threadId: string
   runId: string
+  resume?: Array<RunAgentResumeItem>
 }
 
 export interface ChatFetcherOptions {
@@ -269,23 +284,38 @@ export interface UIMessage<
   createdAt?: Date
 }
 
-export interface ChatClientPersistence<
-  TTools extends ReadonlyArray<AnyClientTool> = any,
-> {
+export interface ChatStorageAdapter<TValue> {
   getItem: (
     id: string,
-  ) =>
-    | Array<UIMessage<TTools>>
-    | null
-    | undefined
-    | Promise<Array<UIMessage<TTools>> | null | undefined>
-  setItem: (
-    id: string,
-    messages: Array<UIMessage<TTools>>,
-  ) => void | Promise<void>
+  ) => TValue | null | undefined | Promise<TValue | null | undefined>
+  setItem: (id: string, value: TValue) => void | Promise<void>
   removeItem: (id: string) => void | Promise<void>
 }
 
+export type ChatClientPersistence<
+  TTools extends ReadonlyArray<AnyClientTool> = any,
+> = ChatStorageAdapter<Array<UIMessage<TTools>>>
+
+export type ChatServerPersistence = ChatStorageAdapter<ChatResumeSnapshot>
+
+/**
+ * @deprecated Passing a message adapter directly as `persistence: adapter`
+ * remains supported for compatibility. Use `persistence: { client: adapter }`
+ * instead.
+ */
+export type LegacyChatPersistenceOptions<
+  TTools extends ReadonlyArray<AnyClientTool> = any,
+> = ChatClientPersistence<TTools>
+
+export type ChatPersistenceOptions<
+  TTools extends ReadonlyArray<AnyClientTool> = any,
+> =
+  | LegacyChatPersistenceOptions<TTools>
+  | {
+      client?: ChatClientPersistence<TTools>
+      server?: ChatServerPersistence
+    }
+
 type IsUnknown<T> = unknown extends T
   ? [T] extends [unknown]
     ? true
@@ -377,9 +407,13 @@ export interface ChatClientBaseOptions<
   initialMessages?: Array<UIMessage<TTools>>
 
   /**
-   * Optional persistence adapter for chat messages.
+   * Optional persistence adapters for chat state.
+   *
+   * Prefer `persistence: { client, server }`. `client` stores client-rendered
+   * `UIMessage[]` using this chat's `id`; `server` stores the resume snapshot
+   * `{ resumeState, pendingInterrupts }` using this chat's `threadId`.
    */
-  persistence?: ChatClientPersistence<TTools>
+  persistence?: ChatPersistenceOptions<TTools>
 
   /**
    * Unique identifier for this chat instance
@@ -393,6 +427,13 @@ export interface ChatClientBaseOptions<
    */
   threadId?: string
 
+  /**
+   * Initial resumable run state, useful when rehydrating a persisted client
+   * after a full page reload. This restores the client-side interrupt
+   * descriptors needed to send AG-UI resume entries.
+   */
+  initialResumeSnapshot?: ChatResumeSnapshot
+
   /**
    * Arbitrary client-controlled JSON forwarded to the server in the
    * AG-UI `RunAgentInput.forwardedProps` field. Use this for per-session
@@ -480,6 +521,14 @@ export interface ChatClientBaseOptions<
    */
   onSessionGeneratingChange?: (isGenerating: boolean) => void
 
+  /**
+   * Callback when resumable run state or pending interrupts change.
+   */
+  onResumeStateChange?: (
+    resumeState: ChatResumeState | null,
+    pendingInterrupts: Array<ChatPendingInterrupt>,
+  ) => void
+
   /**
    * Callback when a custom event is received from a server-side tool.
    * Custom events are emitted by tools using `context.emitCustomEvent()` during execution.
diff --git a/packages/ai-client/src/video-generation-client.ts b/packages/ai-client/src/video-generation-client.ts
index 4cf2673a8..30624519f 100644
--- a/packages/ai-client/src/video-generation-client.ts
+++ b/packages/ai-client/src/video-generation-client.ts
@@ -1,4 +1,7 @@
-import { GENERATION_EVENTS } from './generation-types'
+import {
+  GENERATION_EVENTS,
+  updateGenerationResumeSnapshot,
+} from './generation-types'
 import { createNoOpVideoDevtoolsBridge } from './devtools-noop'
 import { parseSSEResponse } from './sse-parser'
 import type { StreamChunk } from '@tanstack/ai/client'
@@ -15,6 +18,8 @@ import type {
 import type {
   GenerationClientState,
   GenerationFetcher,
+  GenerationResumeSnapshot,
+  GenerationServerPersistence,
   VideoGenerateInput,
   VideoGenerateResult,
   VideoGenerationClientOptions,
@@ -42,6 +47,9 @@ interface VideoCallbacks<TOutput> {
   onStatusChange?: ((status: GenerationClientState) => void) | undefined
   onJobIdChange?: ((jobId: string | null) => void) | undefined
   onVideoStatusChange?: ((status: VideoStatusInfo | null) => void) | undefined
+  onResumeSnapshotChange?:
+    | ((snapshot: GenerationResumeSnapshot) => void)
+    | undefined
 }
 
 /**
@@ -88,6 +96,7 @@ export class VideoGenerationClient<TOutput = VideoGenerateResult> {
   private readonly devtoolsMetadata: AIDevtoolsClientMetadata
   private readonly devtoolsBridge: VideoDevtoolsBridge<TOutput>
   private readonly threadId: string
+  private readonly serverPersistence: GenerationServerPersistence | undefined
   private body: Record<string, any>
 
   private result: TOutput | null = null
@@ -98,9 +107,13 @@ export class VideoGenerationClient<TOutput = VideoGenerateResult> {
   private isLoading = false
   private error: Error | undefined = undefined
   private status: GenerationClientState = 'idle'
+  private resumeSnapshot: GenerationResumeSnapshot | undefined
+  private resumeSnapshotPersistenceQueue: Promise<void> = Promise.resolve()
+  private resumePersistenceError: Error | undefined = undefined
   private abortController: AbortController | null = null
   private readonly callbacksRef: VideoCallbacks<TOutput>
   private devtoolsMounted = false
+  private disposed = false
 
   constructor(
     options: VideoGenerationClientOptions<TOutput> &
@@ -117,6 +130,8 @@ export class VideoGenerationClient<TOutput = VideoGenerateResult> {
     this.connection = options.connection
     this.fetcher = options.fetcher
     this.body = options.body ?? {}
+    this.serverPersistence = options.persistence?.server
+    this.resumeSnapshot = options.initialResumeSnapshot
 
     this.callbacksRef = {
       onResult: options.onResult,
@@ -131,6 +146,7 @@ export class VideoGenerationClient<TOutput = VideoGenerateResult> {
       onStatusChange: options.onStatusChange,
       onJobIdChange: options.onJobIdChange,
       onVideoStatusChange: options.onVideoStatusChange,
+      onResumeSnapshotChange: options.onResumeSnapshotChange,
     }
 
     this.devtoolsMetadata = this.createDevtoolsMetadata(options.devtools)
@@ -174,6 +190,7 @@ export class VideoGenerationClient<TOutput = VideoGenerateResult> {
    */
   async generate(input: VideoGenerateInput): Promise<void> {
     this.mountDevtools()
+    if (this.disposed) return
     if (this.isLoading) return
 
     this.input = input
@@ -200,7 +217,7 @@ export class VideoGenerationClient<TOutput = VideoGenerateResult> {
           signal,
           this.createRunContext(runId),
         )
-        await this.processStream(stream, runId)
+        await this.processStream(stream, runId, signal)
       } else {
         throw new Error(
           'VideoGenerationClient requires either a connection or fetcher option',
@@ -226,8 +243,10 @@ export class VideoGenerationClient<TOutput = VideoGenerateResult> {
       )
       this.callbacksRef.onError?.(error)
     } finally {
-      this.abortController = null
-      this.setIsLoading(false)
+      if (this.abortController === abortController) {
+        this.abortController = null
+        this.setIsLoading(false)
+      }
     }
   }
 
@@ -247,11 +266,12 @@ export class VideoGenerationClient<TOutput = VideoGenerateResult> {
 
     if (result instanceof Response) {
       // Server function returned SSE Response — parse stream
-      await this.processStream(parseSSEResponse(result, signal), runId)
+      await this.processStream(parseSSEResponse(result, signal), runId, signal)
     } else {
       this.devtoolsBridge.ensureRunStarted(runId)
       this.setResult(result)
       this.setStatus('success')
+      this.completePlainFetcherResumeSnapshot()
     }
   }
 
@@ -262,13 +282,15 @@ export class VideoGenerationClient<TOutput = VideoGenerateResult> {
   private async processStream(
     source: AsyncIterable<StreamChunk>,
     fallbackRunId: string,
+    signal: AbortSignal,
   ): Promise<void> {
     let streamRunId: string | undefined
 
     for await (const chunk of source) {
-      if (this.abortController?.signal.aborted) break
+      if (signal.aborted) break
 
       this.callbacksRef.onChunk?.(chunk)
+      this.observeResumeSnapshot(chunk)
       const chunkRunId =
         'runId' in chunk && typeof chunk.runId === 'string'
           ? chunk.runId
@@ -403,6 +425,7 @@ export class VideoGenerationClient<TOutput = VideoGenerateResult> {
   }
 
   dispose(): void {
+    this.disposed = true
     this.stop()
     this.devtoolsBridge.dispose()
     this.devtoolsMounted = false
@@ -432,10 +455,41 @@ export class VideoGenerationClient<TOutput = VideoGenerateResult> {
     return this.error
   }
 
+  getResumePersistenceError(): Error | undefined {
+    return this.resumePersistenceError
+  }
+
   getStatus(): GenerationClientState {
     return this.status
   }
 
+  getResumeSnapshot(): GenerationResumeSnapshot | undefined {
+    return this.resumeSnapshot
+      ? {
+          ...this.resumeSnapshot,
+          ...(this.resumeSnapshot.pendingArtifacts
+            ? { pendingArtifacts: [...this.resumeSnapshot.pendingArtifacts] }
+            : {}),
+          ...(this.resumeSnapshot.result
+            ? {
+                result: {
+                  ...this.resumeSnapshot.result,
+                  ...(this.resumeSnapshot.result.artifacts
+                    ? { artifacts: [...this.resumeSnapshot.result.artifacts] }
+                    : {}),
+                },
+              }
+            : {}),
+          ...(this.resumeSnapshot.error
+            ? { error: { ...this.resumeSnapshot.error } }
+            : {}),
+          ...(this.resumeSnapshot.lastEvent
+            ? { lastEvent: { ...this.resumeSnapshot.lastEvent } }
+            : {}),
+        }
+      : undefined
+  }
+
   // ===========================
   // Private state setters
   // ===========================
@@ -556,4 +610,56 @@ export class VideoGenerationClient<TOutput = VideoGenerateResult> {
       runId,
     }
   }
+
+  private observeResumeSnapshot(chunk: StreamChunk): void {
+    this.resumeSnapshot = updateGenerationResumeSnapshot(
+      this.resumeSnapshot,
+      chunk,
+    )
+    this.callbacksRef.onResumeSnapshotChange?.(this.resumeSnapshot)
+    void this.persistResumeSnapshot(this.resumeSnapshot)
+  }
+
+  private completePlainFetcherResumeSnapshot(): void {
+    if (!this.resumeSnapshot) {
+      return
+    }
+    this.resumeSnapshot = {
+      ...this.resumeSnapshot,
+      resumeState: null,
+      status: 'complete',
+    }
+    this.callbacksRef.onResumeSnapshotChange?.(this.resumeSnapshot)
+    void this.persistResumeSnapshot(this.resumeSnapshot)
+  }
+
+  private async persistResumeSnapshot(
+    snapshot: GenerationResumeSnapshot,
+  ): Promise<void> {
+    if (!this.serverPersistence) {
+      return
+    }
+
+    this.resumeSnapshotPersistenceQueue =
+      this.resumeSnapshotPersistenceQueue.then(
+        () => this.writeResumeSnapshot(snapshot),
+        () => this.writeResumeSnapshot(snapshot),
+      )
+    await this.resumeSnapshotPersistenceQueue
+  }
+
+  private async writeResumeSnapshot(
+    snapshot: GenerationResumeSnapshot,
+  ): Promise<void> {
+    try {
+      await this.serverPersistence?.setItem(this.threadId, snapshot)
+    } catch (error) {
+      this.resumePersistenceError =
+        error instanceof Error ? error : new Error(String(error))
+      console.warn(
+        '[TanStack AI] Failed to persist generation resume snapshot',
+        error,
+      )
+    }
+  }
 }
diff --git a/packages/ai-client/tests/chat-client-resume.test.ts b/packages/ai-client/tests/chat-client-resume.test.ts
new file mode 100644
index 000000000..f2e7e4839
--- /dev/null
+++ b/packages/ai-client/tests/chat-client-resume.test.ts
@@ -0,0 +1,1396 @@
+import { describe, expect, it, vi } from 'vitest'
+import { EventType } from '@tanstack/ai/client'
+import { ChatClient } from '../src/chat-client'
+import type {
+  ConnectConnectionAdapter,
+  RunAgentInputContext,
+} from '../src/connection-adapters'
+import type { RunAgentResumeItem, StreamChunk } from '@tanstack/ai/client'
+import type { ChatResumeSnapshot, ChatServerPersistence } from '../src/types'
+
+/**
+ * Adapter that records each connect's runContext and yields scripted chunks.
+ * A script can be a function of the live `runContext` (so a test can emit a
+ * RUN_FINISHED carrying the same runId the client generated and passed in).
+ */
+type Script =
+  | Array<StreamChunk>
+  | ((ctx: RunAgentInputContext | undefined) => Array<StreamChunk>)
+
+function recordingAdapter(scripts: Array<Script>) {
+  const contexts: Array<RunAgentInputContext | undefined> = []
+  const sentMessages: Array<Array<unknown>> = []
+  let i = 0
+  const adapter: ConnectConnectionAdapter = {
+    // eslint-disable-next-line @typescript-eslint/require-await
+    async *connect(messages, _data, _signal, runContext) {
+      sentMessages.push(messages)
+      contexts.push(runContext)
+      const script = scripts[i]
+      i++
+      const chunks =
+        typeof script === 'function' ? script(runContext) : (script ?? [])
+      for (const c of chunks) yield c
+    },
+  }
+  return { adapter, contexts, sentMessages }
+}
+
+const text = (delta: string): StreamChunk => ({
+  type: EventType.TEXT_MESSAGE_CONTENT,
+  messageId: 'm1',
+  timestamp: Date.now(),
+  delta,
+})
+const runStarted: StreamChunk = {
+  type: EventType.RUN_STARTED,
+  runId: 'run-1',
+  threadId: 'thread-1',
+  timestamp: Date.now(),
+}
+
+function createResumePersistence(
+  initial?: ChatResumeSnapshot | null,
+): ChatServerPersistence {
+  return {
+    getItem: vi.fn(() => initial),
+    setItem: vi.fn(),
+    removeItem: vi.fn(),
+  }
+}
+
+describe('ChatClient resume', () => {
+  it('tracks the run/thread of an interrupted run', async () => {
+    const { adapter, contexts } = recordingAdapter([
+      [
+        runStarted,
+        text('a'),
+        text('b'),
+        {
+          type: EventType.RUN_FINISHED,
+          runId: 'run-1',
+          threadId: 'thread-1',
+          timestamp: Date.now(),
+          outcome: {
+            type: 'interrupt',
+            interrupts: [{ id: 'interrupt-1', reason: 'client_tool_input' }],
+          },
+        },
+      ],
+    ])
+    const client = new ChatClient({ connection: adapter })
+    await client.append({
+      id: 'u1',
+      role: 'user',
+      parts: [{ type: 'text', content: 'hi' }],
+      createdAt: new Date(),
+    })
+
+    const state = client.getResumeState()
+    expect(state).not.toBeNull()
+    expect(state?.threadId).toBe('thread-1')
+    expect(state?.runId).toBe(contexts[0]?.runId)
+    expect(state).not.toHaveProperty('cursor')
+  })
+
+  it('clears resume state once the run finishes', async () => {
+    const { adapter } = recordingAdapter([
+      (ctx) => [
+        runStarted,
+        text('a'),
+        {
+          type: EventType.RUN_FINISHED,
+          runId: ctx?.runId ?? 'run-1',
+          threadId: 'thread-1',
+          timestamp: Date.now(),
+          finishReason: 'stop',
+        },
+      ],
+    ])
+    const client = new ChatClient({ connection: adapter })
+    await client.append({
+      id: 'u1',
+      role: 'user',
+      parts: [{ type: 'text', content: 'hi' }],
+      createdAt: new Date(),
+    })
+    expect(client.getResumeState()).toBeNull()
+  })
+
+  it('preserves resume state and tracks pending interrupts on interrupt terminal', async () => {
+    const { adapter } = recordingAdapter([
+      (ctx) => [
+        {
+          type: EventType.RUN_STARTED,
+          runId: ctx?.runId ?? 'run-1',
+          threadId: ctx?.threadId ?? 'thread-1',
+          timestamp: Date.now(),
+        },
+        text('a'),
+        {
+          type: EventType.RUN_FINISHED,
+          runId: ctx?.runId ?? 'run-1',
+          threadId: ctx?.threadId ?? 'thread-1',
+          timestamp: Date.now(),
+          outcome: {
+            type: 'interrupt',
+            interrupts: [
+              {
+                id: 'interrupt-1',
+                reason: 'approval_required',
+                toolCallId: 'tool-1',
+                metadata: { kind: 'approval' },
+              },
+            ],
+          },
+        },
+      ],
+    ])
+    const client = new ChatClient({ connection: adapter, threadId: 'thread-1' })
+
+    await client.sendMessage('hi')
+
+    expect(client.getResumeState()).toEqual({
+      threadId: 'thread-1',
+      runId: expect.any(String),
+    })
+    expect(client.getPendingInterrupts()).toEqual([
+      expect.objectContaining({ id: 'interrupt-1' }),
+    ])
+  })
+
+  it('resumeInterrupts sends AG-UI resume entries with the interrupted run context', async () => {
+    const resumeItems: Array<RunAgentResumeItem> = [
+      {
+        interruptId: 'interrupt-1',
+        status: 'resolved',
+        payload: { approved: true },
+      },
+    ]
+    const { adapter, contexts } = recordingAdapter([
+      (ctx) => [
+        {
+          type: EventType.RUN_STARTED,
+          runId: ctx?.runId ?? 'run-1',
+          threadId: ctx?.threadId ?? 'thread-1',
+          timestamp: Date.now(),
+        },
+        text('a'),
+        {
+          type: EventType.RUN_FINISHED,
+          runId: ctx?.runId ?? 'run-1',
+          threadId: ctx?.threadId ?? 'thread-1',
+          timestamp: Date.now(),
+          outcome: {
+            type: 'interrupt',
+            interrupts: [
+              {
+                id: 'interrupt-1',
+                reason: 'approval_required',
+                metadata: { kind: 'approval' },
+              },
+            ],
+          },
+        },
+      ],
+      (ctx) => [
+        {
+          type: EventType.RUN_FINISHED,
+          runId: ctx?.runId ?? 'run-1',
+          threadId: ctx?.threadId ?? 'thread-1',
+          timestamp: Date.now(),
+          outcome: { type: 'success' },
+        },
+      ],
+    ])
+    const client = new ChatClient({ connection: adapter, threadId: 'thread-1' })
+
+    await client.sendMessage('hi')
+    const resumeState = client.getResumeState()
+    await client.resumeInterrupts(resumeItems)
+
+    expect(contexts[1]?.threadId).toBe(resumeState?.threadId)
+    expect(contexts[1]?.runId).toBe(resumeState?.runId)
+    expect(contexts[1]?.resume).toEqual(resumeItems)
+    expect(client.getPendingInterrupts()).toEqual([])
+    expect(client.getResumeState()).toBeNull()
+  })
+
+  it('resumeInterrupts reconnects without re-sending message history', async () => {
+    const resumeItems: Array<RunAgentResumeItem> = [
+      {
+        interruptId: 'interrupt-1',
+        status: 'resolved',
+        payload: { value: 'ok' },
+      },
+    ]
+    const { adapter, contexts, sentMessages } = recordingAdapter([
+      (ctx) => [
+        {
+          type: EventType.RUN_STARTED,
+          runId: ctx?.runId ?? 'run-1',
+          threadId: ctx?.threadId ?? 'thread-1',
+          timestamp: Date.now(),
+        },
+        text('a'),
+        {
+          type: EventType.RUN_FINISHED,
+          runId: ctx?.runId ?? 'run-1',
+          threadId: ctx?.threadId ?? 'thread-1',
+          timestamp: Date.now(),
+          outcome: {
+            type: 'interrupt',
+            interrupts: [{ id: 'interrupt-1', reason: 'client_tool_input' }],
+          },
+        },
+      ],
+      [],
+    ])
+    const client = new ChatClient({ connection: adapter, threadId: 'thread-1' })
+
+    await client.sendMessage('hi')
+    expect(sentMessages[0]).toHaveLength(1)
+
+    await client.resumeInterrupts(resumeItems)
+
+    expect(contexts[1]?.resume).toEqual(resumeItems)
+    expect(sentMessages[1]).toEqual([])
+  })
+
+  it('clears resume state and pending interrupts on a runless RUN_ERROR', async () => {
+    const { adapter } = recordingAdapter([
+      (ctx) => [
+        {
+          type: EventType.RUN_STARTED,
+          runId: ctx?.runId ?? 'run-1',
+          threadId: ctx?.threadId ?? 'thread-1',
+          timestamp: Date.now(),
+        },
+        text('a'),
+        {
+          type: EventType.RUN_FINISHED,
+          runId: ctx?.runId ?? 'run-1',
+          threadId: ctx?.threadId ?? 'thread-1',
+          timestamp: Date.now(),
+          outcome: {
+            type: 'interrupt',
+            interrupts: [{ id: 'interrupt-1', reason: 'client_tool_input' }],
+          },
+        },
+      ],
+      [
+        {
+          type: EventType.RUN_FINISHED,
+          runId: 'fresh-send-run',
+          threadId: 'thread-1',
+          timestamp: Date.now(),
+          outcome: { type: 'success' },
+        },
+      ],
+    ])
+    const client = new ChatClient({ connection: adapter, threadId: 'thread-1' })
+
+    await client.sendMessage('hi')
+    expect(client.getPendingInterrupts()).toHaveLength(1)
+    ;(
+      client as unknown as {
+        observeInterruptState: (chunk: StreamChunk) => void
+      }
+    ).observeInterruptState({
+      type: EventType.RUN_ERROR,
+      message: 'session failed',
+      timestamp: Date.now(),
+    })
+
+    expect(client.getResumeState()).toBeNull()
+    expect(client.getPendingInterrupts()).toEqual([])
+    await expect(client.sendMessage('fresh')).resolves.toBeUndefined()
+  })
+
+  it('blocks normal input while interrupts are pending', async () => {
+    const { adapter, contexts } = recordingAdapter([
+      (ctx) => [
+        {
+          type: EventType.RUN_STARTED,
+          runId: ctx?.runId ?? 'run-1',
+          threadId: ctx?.threadId ?? 'thread-1',
+          timestamp: Date.now(),
+        },
+        text('a'),
+        {
+          type: EventType.RUN_FINISHED,
+          runId: ctx?.runId ?? 'run-1',
+          threadId: ctx?.threadId ?? 'thread-1',
+          timestamp: Date.now(),
+          outcome: {
+            type: 'interrupt',
+            interrupts: [{ id: 'interrupt-1', reason: 'client_tool_input' }],
+          },
+        },
+      ],
+    ])
+    const client = new ChatClient({ connection: adapter })
+
+    await client.sendMessage('hi')
+    await expect(client.sendMessage('blocked')).rejects.toThrow(
+      'pending interrupts',
+    )
+    await expect(
+      client.append({
+        id: 'u2',
+        role: 'user',
+        parts: [{ type: 'text', content: 'blocked' }],
+        createdAt: new Date(),
+      }),
+    ).rejects.toThrow('pending interrupts')
+
+    expect(contexts).toHaveLength(1)
+  })
+
+  it('keeps pending interrupts when an unrelated run finishes', async () => {
+    const { adapter, contexts } = recordingAdapter([
+      (ctx) => [
+        {
+          type: EventType.RUN_STARTED,
+          runId: ctx?.runId ?? 'run-a',
+          threadId: ctx?.threadId ?? 'thread-1',
+          timestamp: Date.now(),
+        },
+        text('a'),
+        {
+          type: EventType.RUN_FINISHED,
+          runId: ctx?.runId ?? 'run-a',
+          threadId: ctx?.threadId ?? 'thread-1',
+          timestamp: Date.now(),
+          outcome: {
+            type: 'interrupt',
+            interrupts: [{ id: 'interrupt-a', reason: 'client_tool_input' }],
+          },
+        },
+      ],
+    ])
+    const client = new ChatClient({ connection: adapter, threadId: 'thread-1' })
+
+    await client.sendMessage('hi')
+    expect(client.getPendingInterrupts()).toHaveLength(1)
+    ;(
+      client as unknown as {
+        observeInterruptState: (chunk: StreamChunk) => void
+      }
+    ).observeInterruptState({
+      type: EventType.RUN_FINISHED,
+      runId: 'run-b',
+      threadId: 'thread-1',
+      timestamp: Date.now(),
+      outcome: { type: 'success' },
+    })
+
+    expect(client.getPendingInterrupts()).toEqual([
+      expect.objectContaining({ id: 'interrupt-a' }),
+    ])
+    expect(client.getResumeState()?.runId).not.toBe('run-b')
+    await expect(client.sendMessage('blocked')).rejects.toThrow(
+      'pending interrupts',
+    )
+    expect(contexts).toHaveLength(1)
+  })
+
+  it('keeps pending interrupts when an unrelated run starts and finishes', async () => {
+    const { adapter, contexts } = recordingAdapter([
+      (ctx) => [
+        {
+          type: EventType.RUN_STARTED,
+          runId: ctx?.runId ?? 'run-a',
+          threadId: ctx?.threadId ?? 'thread-1',
+          timestamp: Date.now(),
+        },
+        text('a'),
+        {
+          type: EventType.RUN_FINISHED,
+          runId: ctx?.runId ?? 'run-a',
+          threadId: ctx?.threadId ?? 'thread-1',
+          timestamp: Date.now(),
+          outcome: {
+            type: 'interrupt',
+            interrupts: [{ id: 'interrupt-a', reason: 'client_tool_input' }],
+          },
+        },
+      ],
+    ])
+    const client = new ChatClient({ connection: adapter, threadId: 'thread-1' })
+
+    await client.sendMessage('hi')
+    const interruptedState = client.getResumeState()
+    expect(client.getPendingInterrupts()).toHaveLength(1)
+    const internals = client as unknown as {
+      updateRunLifecycle: (chunk: StreamChunk) => void
+      observeInterruptState: (chunk: StreamChunk) => void
+    }
+    internals.updateRunLifecycle({
+      type: EventType.RUN_STARTED,
+      runId: 'run-b',
+      threadId: 'thread-1',
+      timestamp: Date.now(),
+    })
+    internals.observeInterruptState({
+      type: EventType.RUN_FINISHED,
+      runId: 'run-b',
+      threadId: 'thread-1',
+      timestamp: Date.now(),
+      outcome: { type: 'success' },
+    })
+
+    expect(client.getResumeState()).toEqual(interruptedState)
+    expect(client.getPendingInterrupts()).toEqual([
+      expect.objectContaining({ id: 'interrupt-a' }),
+    ])
+    await expect(client.sendMessage('blocked')).rejects.toThrow(
+      'pending interrupts',
+    )
+    expect(contexts).toHaveLength(1)
+  })
+
+  it('keeps pending interrupts when an unrelated run errors', async () => {
+    const { adapter, contexts } = recordingAdapter([
+      (ctx) => [
+        {
+          type: EventType.RUN_STARTED,
+          runId: ctx?.runId ?? 'run-a',
+          threadId: ctx?.threadId ?? 'thread-1',
+          timestamp: Date.now(),
+        },
+        text('a'),
+        {
+          type: EventType.RUN_FINISHED,
+          runId: ctx?.runId ?? 'run-a',
+          threadId: ctx?.threadId ?? 'thread-1',
+          timestamp: Date.now(),
+          outcome: {
+            type: 'interrupt',
+            interrupts: [{ id: 'interrupt-a', reason: 'client_tool_input' }],
+          },
+        },
+      ],
+    ])
+    const client = new ChatClient({ connection: adapter, threadId: 'thread-1' })
+
+    await client.sendMessage('hi')
+    expect(client.getPendingInterrupts()).toHaveLength(1)
+    ;(
+      client as unknown as {
+        observeInterruptState: (chunk: StreamChunk) => void
+      }
+    ).observeInterruptState({
+      type: EventType.RUN_ERROR,
+      runId: 'run-b',
+      message: 'unrelated failure',
+      timestamp: Date.now(),
+    })
+
+    expect(client.getPendingInterrupts()).toEqual([
+      expect.objectContaining({ id: 'interrupt-a' }),
+    ])
+    await expect(
+      client.append({
+        id: 'u2',
+        role: 'user',
+        parts: [{ type: 'text', content: 'blocked' }],
+        createdAt: new Date(),
+      }),
+    ).rejects.toThrow('pending interrupts')
+    expect(contexts).toHaveLength(1)
+  })
+
+  it('clear removes resume state and pending interrupts', async () => {
+    const { adapter, contexts } = recordingAdapter([
+      (ctx) => [
+        {
+          type: EventType.RUN_STARTED,
+          runId: ctx?.runId ?? 'run-1',
+          threadId: ctx?.threadId ?? 'thread-1',
+          timestamp: Date.now(),
+        },
+        text('a'),
+        {
+          type: EventType.RUN_FINISHED,
+          runId: ctx?.runId ?? 'run-1',
+          threadId: ctx?.threadId ?? 'thread-1',
+          timestamp: Date.now(),
+          outcome: {
+            type: 'interrupt',
+            interrupts: [{ id: 'interrupt-1', reason: 'client_tool_input' }],
+          },
+        },
+      ],
+      [
+        {
+          type: EventType.RUN_FINISHED,
+          runId: 'fresh-send-run',
+          threadId: 'thread-1',
+          timestamp: Date.now(),
+          outcome: { type: 'success' },
+        },
+      ],
+      [
+        {
+          type: EventType.RUN_FINISHED,
+          runId: 'fresh-append-run',
+          threadId: 'thread-1',
+          timestamp: Date.now(),
+          outcome: { type: 'success' },
+        },
+      ],
+    ])
+    const seenResumeStates: Array<ReturnType<ChatClient['getResumeState']>> = []
+    const seenPendingInterrupts: Array<
+      ReturnType<ChatClient['getPendingInterrupts']>
+    > = []
+    const client = new ChatClient({
+      connection: adapter,
+      threadId: 'thread-1',
+      onResumeStateChange: (resumeState, pendingInterrupts) => {
+        seenResumeStates.push(resumeState)
+        seenPendingInterrupts.push(pendingInterrupts)
+      },
+    })
+
+    await client.sendMessage('hi')
+    expect(client.getResumeState()).not.toBeNull()
+    expect(client.getPendingInterrupts()).toHaveLength(1)
+
+    client.clear()
+
+    expect(client.getResumeState()).toBeNull()
+    expect(client.getPendingInterrupts()).toEqual([])
+    expect(seenResumeStates.at(-1)).toBeNull()
+    expect(seenPendingInterrupts.at(-1)).toEqual([])
+    await expect(client.sendMessage('fresh')).resolves.toBeUndefined()
+    await expect(
+      client.append({
+        id: 'u2',
+        role: 'user',
+        parts: [{ type: 'text', content: 'fresh append' }],
+        createdAt: new Date(),
+      }),
+    ).resolves.toBeUndefined()
+    expect(contexts).toHaveLength(3)
+  })
+
+  it('addToolApprovalResponse sends a compatibility resume item', async () => {
+    const { adapter, contexts } = recordingAdapter([
+      (ctx) => [
+        {
+          type: EventType.RUN_STARTED,
+          runId: ctx?.runId ?? 'run-1',
+          threadId: ctx?.threadId ?? 'thread-1',
+          timestamp: Date.now(),
+        },
+        text('a'),
+        {
+          type: EventType.RUN_FINISHED,
+          runId: ctx?.runId ?? 'run-1',
+          threadId: ctx?.threadId ?? 'thread-1',
+          timestamp: Date.now(),
+          outcome: {
+            type: 'interrupt',
+            interrupts: [
+              {
+                id: 'approval-1',
+                reason: 'approval_required',
+                toolCallId: 'tool-1',
+                metadata: { kind: 'approval' },
+              },
+            ],
+          },
+        },
+      ],
+      [
+        {
+          type: EventType.RUN_FINISHED,
+          runId: 'run-1',
+          threadId: 'thread-1',
+          timestamp: Date.now(),
+          outcome: { type: 'success' },
+        },
+      ],
+    ])
+    const client = new ChatClient({ connection: adapter, threadId: 'thread-1' })
+
+    await client.sendMessage('hi')
+    await client.addToolApprovalResponse({ id: 'approval-1', approved: true })
+
+    expect(contexts[1]?.resume).toEqual([
+      {
+        interruptId: 'approval-1',
+        status: 'resolved',
+        payload: { approved: true },
+      },
+    ])
+  })
+
+  it('addToolApprovalResponse waits for all pending approval interrupts before resuming', async () => {
+    const { adapter, contexts } = recordingAdapter([
+      (ctx) => [
+        {
+          type: EventType.RUN_STARTED,
+          runId: ctx?.runId ?? 'run-1',
+          threadId: ctx?.threadId ?? 'thread-1',
+          timestamp: Date.now(),
+        },
+        text('a'),
+        {
+          type: EventType.RUN_FINISHED,
+          runId: ctx?.runId ?? 'run-1',
+          threadId: ctx?.threadId ?? 'thread-1',
+          timestamp: Date.now(),
+          outcome: {
+            type: 'interrupt',
+            interrupts: [
+              {
+                id: 'approval-1',
+                reason: 'approval_required',
+                toolCallId: 'tool-1',
+                metadata: { kind: 'approval' },
+              },
+              {
+                id: 'approval-2',
+                reason: 'approval_required',
+                toolCallId: 'tool-2',
+                metadata: { kind: 'approval' },
+              },
+            ],
+          },
+        },
+      ],
+      [],
+    ])
+    const client = new ChatClient({ connection: adapter, threadId: 'thread-1' })
+
+    await client.sendMessage('hi')
+    await client.addToolApprovalResponse({ id: 'approval-1', approved: true })
+
+    expect(contexts).toHaveLength(1)
+
+    await client.addToolApprovalResponse({ id: 'approval-2', approved: false })
+
+    expect(contexts).toHaveLength(2)
+    expect(contexts[1]?.resume).toEqual([
+      {
+        interruptId: 'approval-1',
+        status: 'resolved',
+        payload: { approved: true },
+      },
+      {
+        interruptId: 'approval-2',
+        status: 'cancelled',
+        payload: { approved: false },
+      },
+    ])
+  })
+
+  it('restores pending interrupts from an initial resume snapshot', async () => {
+    const { adapter, contexts } = recordingAdapter([
+      [
+        {
+          type: EventType.RUN_FINISHED,
+          runId: 'run-1',
+          threadId: 'thread-1',
+          timestamp: Date.now(),
+          outcome: { type: 'success' },
+        },
+      ],
+    ])
+    const client = new ChatClient({
+      connection: adapter,
+      initialResumeSnapshot: {
+        resumeState: {
+          threadId: 'thread-1',
+          runId: 'run-1',
+        },
+        pendingInterrupts: [
+          {
+            id: 'approval-1',
+            reason: 'approval_required',
+            toolCallId: 'tool-1',
+            metadata: { kind: 'approval' },
+          },
+        ],
+      },
+    })
+
+    expect(client.getResumeState()).toEqual({
+      threadId: 'thread-1',
+      runId: 'run-1',
+    })
+    expect(client.getPendingInterrupts()).toEqual([
+      expect.objectContaining({ id: 'approval-1' }),
+    ])
+
+    await client.addToolApprovalResponse({ id: 'approval-1', approved: true })
+
+    expect(contexts[0]?.threadId).toBe('thread-1')
+    expect(contexts[0]?.runId).toBe('run-1')
+    expect(contexts[0]?.resume).toEqual([
+      {
+        interruptId: 'approval-1',
+        status: 'resolved',
+        payload: { approved: true },
+      },
+    ])
+  })
+
+  it('hydrates resume state and pending interrupts from persistence.server using thread id', async () => {
+    const persistence = createResumePersistence({
+      resumeState: {
+        threadId: 'thread-1',
+        runId: 'run-1',
+      },
+      pendingInterrupts: [
+        {
+          id: 'approval-1',
+          reason: 'approval_required',
+          toolCallId: 'tool-1',
+        },
+      ],
+    })
+    const { adapter } = recordingAdapter([[]])
+
+    const client = new ChatClient({
+      connection: adapter,
+      threadId: 'thread-1',
+      persistence: { server: persistence },
+    })
+
+    expect(persistence.getItem).toHaveBeenCalledWith('thread-1')
+    expect(client.getResumeState()).toEqual({
+      threadId: 'thread-1',
+      runId: 'run-1',
+    })
+    expect(client.getPendingInterrupts()).toEqual([
+      expect.objectContaining({ id: 'approval-1' }),
+    ])
+  })
+
+  it('persists resume snapshots to persistence.server using thread id', async () => {
+    const persistence = createResumePersistence()
+    const { adapter } = recordingAdapter([
+      (ctx) => [
+        {
+          type: EventType.RUN_STARTED,
+          runId: ctx?.runId ?? 'run-1',
+          threadId: ctx?.threadId ?? 'thread-1',
+          timestamp: Date.now(),
+        },
+        text('a'),
+        {
+          type: EventType.RUN_FINISHED,
+          runId: ctx?.runId ?? 'run-1',
+          threadId: ctx?.threadId ?? 'thread-1',
+          timestamp: Date.now(),
+          outcome: {
+            type: 'interrupt',
+            interrupts: [{ id: 'interrupt-1', reason: 'client_tool_input' }],
+          },
+        },
+      ],
+    ])
+    const onResumeStateChange = vi.fn()
+    const client = new ChatClient({
+      connection: adapter,
+      threadId: 'thread-1',
+      persistence: { server: persistence },
+      onResumeStateChange,
+    })
+
+    await client.sendMessage('hi')
+
+    expect(persistence.setItem).toHaveBeenLastCalledWith('thread-1', {
+      resumeState: client.getResumeState(),
+      pendingInterrupts: client.getPendingInterrupts(),
+    })
+    expect(onResumeStateChange).toHaveBeenCalled()
+  })
+
+  it('removes the server snapshot when resume state is cleared', async () => {
+    const persistence = createResumePersistence()
+    const { adapter } = recordingAdapter([
+      (ctx) => [
+        {
+          type: EventType.RUN_STARTED,
+          runId: ctx?.runId ?? 'run-1',
+          threadId: ctx?.threadId ?? 'thread-1',
+          timestamp: Date.now(),
+        },
+        text('a'),
+        {
+          type: EventType.RUN_FINISHED,
+          runId: ctx?.runId ?? 'run-1',
+          threadId: ctx?.threadId ?? 'thread-1',
+          timestamp: Date.now(),
+          outcome: {
+            type: 'interrupt',
+            interrupts: [{ id: 'interrupt-1', reason: 'client_tool_input' }],
+          },
+        },
+      ],
+    ])
+    const client = new ChatClient({
+      connection: adapter,
+      threadId: 'thread-1',
+      persistence: { server: persistence },
+    })
+
+    await client.sendMessage('hi')
+    client.clear()
+
+    expect(persistence.removeItem).toHaveBeenCalledWith('thread-1')
+  })
+
+  it('swallows server persistence failures', async () => {
+    const persistence: ChatServerPersistence = {
+      getItem: vi.fn(() => {
+        throw new Error('read failed')
+      }),
+      setItem: vi.fn(() => {
+        throw new Error('write failed')
+      }),
+      removeItem: vi.fn(() => {
+        throw new Error('remove failed')
+      }),
+    }
+    const { adapter } = recordingAdapter([
+      (ctx) => [
+        {
+          type: EventType.RUN_STARTED,
+          runId: ctx?.runId ?? 'run-1',
+          threadId: ctx?.threadId ?? 'thread-1',
+          timestamp: Date.now(),
+        },
+        text('a'),
+        {
+          type: EventType.RUN_FINISHED,
+          runId: ctx?.runId ?? 'run-1',
+          threadId: ctx?.threadId ?? 'thread-1',
+          timestamp: Date.now(),
+          outcome: {
+            type: 'interrupt',
+            interrupts: [{ id: 'interrupt-1', reason: 'client_tool_input' }],
+          },
+        },
+      ],
+    ])
+
+    const client = new ChatClient({
+      connection: adapter,
+      threadId: 'thread-1',
+      persistence: { server: persistence },
+    })
+
+    await expect(client.sendMessage('hi')).resolves.toBeUndefined()
+    expect(() => client.clear()).not.toThrow()
+  })
+
+  it('surfaces rejected server persistence writes to onError without breaking chat', async () => {
+    const writeError = new Error('write failed')
+    const persistence: ChatServerPersistence = {
+      getItem: vi.fn(() => undefined),
+      setItem: vi.fn(() => Promise.reject(writeError)),
+      removeItem: vi.fn(() => Promise.resolve()),
+    }
+    const { adapter } = recordingAdapter([
+      (ctx) => [
+        {
+          type: EventType.RUN_STARTED,
+          runId: ctx?.runId ?? 'run-1',
+          threadId: ctx?.threadId ?? 'thread-1',
+          timestamp: Date.now(),
+        },
+        text('a'),
+        {
+          type: EventType.RUN_FINISHED,
+          runId: ctx?.runId ?? 'run-1',
+          threadId: ctx?.threadId ?? 'thread-1',
+          timestamp: Date.now(),
+          outcome: {
+            type: 'interrupt',
+            interrupts: [{ id: 'interrupt-1', reason: 'client_tool_input' }],
+          },
+        },
+      ],
+    ])
+    const onError = vi.fn()
+
+    const client = new ChatClient({
+      connection: adapter,
+      threadId: 'thread-1',
+      persistence: { server: persistence },
+      onError,
+    })
+
+    // Chat must not break: the send resolves normally.
+    await expect(client.sendMessage('hi')).resolves.toBeUndefined()
+
+    // The rejected persistence write is surfaced to the observable sink.
+    await vi.waitFor(() => {
+      expect(onError).toHaveBeenCalledWith(writeError)
+    })
+  })
+
+  it('surfaces server persistence failures to console.warn when no onError is provided', async () => {
+    const warnSpy = vi.spyOn(console, 'warn').mockImplementation(() => {})
+    const writeError = new Error('write failed')
+    const persistence: ChatServerPersistence = {
+      getItem: vi.fn(() => undefined),
+      setItem: vi.fn(() => Promise.reject(writeError)),
+      removeItem: vi.fn(() => Promise.resolve()),
+    }
+    const { adapter } = recordingAdapter([
+      (ctx) => [
+        {
+          type: EventType.RUN_STARTED,
+          runId: ctx?.runId ?? 'run-1',
+          threadId: ctx?.threadId ?? 'thread-1',
+          timestamp: Date.now(),
+        },
+        text('a'),
+        {
+          type: EventType.RUN_FINISHED,
+          runId: ctx?.runId ?? 'run-1',
+          threadId: ctx?.threadId ?? 'thread-1',
+          timestamp: Date.now(),
+          outcome: {
+            type: 'interrupt',
+            interrupts: [{ id: 'interrupt-1', reason: 'client_tool_input' }],
+          },
+        },
+      ],
+    ])
+
+    const client = new ChatClient({
+      connection: adapter,
+      threadId: 'thread-1',
+      persistence: { server: persistence },
+    })
+
+    await expect(client.sendMessage('hi')).resolves.toBeUndefined()
+
+    await vi.waitFor(() => {
+      expect(warnSpy).toHaveBeenCalledWith(
+        '[TanStack AI] Server persistence adapter error (non-fatal):',
+        writeError,
+      )
+    })
+
+    warnSpy.mockRestore()
+  })
+
+  it('prefers explicit initialResumeSnapshot over persistence.server', () => {
+    const persistence = createResumePersistence({
+      resumeState: {
+        threadId: 'thread-1',
+        runId: 'stored-run',
+      },
+      pendingInterrupts: [{ id: 'stored', reason: 'client_tool_input' }],
+    })
+    const { adapter } = recordingAdapter([[]])
+
+    const client = new ChatClient({
+      connection: adapter,
+      threadId: 'thread-1',
+      persistence: { server: persistence },
+      initialResumeSnapshot: {
+        resumeState: {
+          threadId: 'thread-1',
+          runId: 'explicit-run',
+        },
+        pendingInterrupts: [{ id: 'explicit', reason: 'client_tool_input' }],
+      },
+    })
+
+    expect(client.getResumeState()).toEqual({
+      threadId: 'thread-1',
+      runId: 'explicit-run',
+    })
+    expect(client.getPendingInterrupts()).toEqual([
+      expect.objectContaining({ id: 'explicit' }),
+    ])
+  })
+
+  it('does not read persistence.server when explicit initialResumeSnapshot is provided', async () => {
+    const persistence: ChatServerPersistence = {
+      getItem: vi.fn(() => Promise.reject(new Error('read failed'))),
+      setItem: vi.fn(),
+      removeItem: vi.fn(),
+    }
+    const { adapter } = recordingAdapter([[]])
+
+    const client = new ChatClient({
+      connection: adapter,
+      threadId: 'thread-1',
+      persistence: { server: persistence },
+      initialResumeSnapshot: {
+        resumeState: {
+          threadId: 'thread-1',
+          runId: 'explicit-run',
+        },
+        pendingInterrupts: [{ id: 'explicit', reason: 'client_tool_input' }],
+      },
+    })
+
+    await Promise.resolve()
+
+    expect(persistence.getItem).not.toHaveBeenCalled()
+    expect(client.getResumeState()).toEqual({
+      threadId: 'thread-1',
+      runId: 'explicit-run',
+    })
+    expect(client.getPendingInterrupts()).toEqual([
+      expect.objectContaining({ id: 'explicit' }),
+    ])
+  })
+
+  it('ignores async server hydrate that resolves after clear', async () => {
+    const storedSnapshot: ChatResumeSnapshot = {
+      resumeState: {
+        threadId: 'thread-1',
+        runId: 'stored-run',
+      },
+      pendingInterrupts: [{ id: 'stored', reason: 'client_tool_input' }],
+    }
+    let resolveHydrate: (snapshot: ChatResumeSnapshot) => void = () => {}
+    const persistence: ChatServerPersistence = {
+      getItem: vi.fn(
+        () =>
+          new Promise<ChatResumeSnapshot>((resolve) => {
+            resolveHydrate = resolve
+          }),
+      ),
+      setItem: vi.fn(),
+      removeItem: vi.fn(),
+    }
+    const { adapter } = recordingAdapter([[]])
+    const client = new ChatClient({
+      connection: adapter,
+      threadId: 'thread-1',
+      persistence: { server: persistence },
+    })
+
+    client.clear()
+    resolveHydrate(storedSnapshot)
+    await Promise.resolve()
+
+    expect(client.getResumeState()).toBeNull()
+    expect(client.getPendingInterrupts()).toEqual([])
+    expect(persistence.removeItem).toHaveBeenCalledWith('thread-1')
+    expect(persistence.setItem).not.toHaveBeenCalled()
+  })
+
+  it('ignores async server hydrate that resolves after dispose', async () => {
+    const storedSnapshot: ChatResumeSnapshot = {
+      resumeState: {
+        threadId: 'thread-1',
+        runId: 'stored-run',
+      },
+      pendingInterrupts: [{ id: 'stored', reason: 'client_tool_input' }],
+    }
+    let resolveHydrate: (snapshot: ChatResumeSnapshot) => void = () => {}
+    const persistence: ChatServerPersistence = {
+      getItem: vi.fn(
+        () =>
+          new Promise<ChatResumeSnapshot>((resolve) => {
+            resolveHydrate = resolve
+          }),
+      ),
+      setItem: vi.fn(),
+      removeItem: vi.fn(),
+    }
+    const { adapter } = recordingAdapter([[]])
+    const onResumeStateChange = vi.fn()
+    const client = new ChatClient({
+      connection: adapter,
+      threadId: 'thread-1',
+      persistence: { server: persistence },
+      onResumeStateChange,
+    })
+
+    client.dispose()
+    resolveHydrate(storedSnapshot)
+    await Promise.resolve()
+
+    expect(client.getResumeState()).toBeNull()
+    expect(client.getPendingInterrupts()).toEqual([])
+    expect(onResumeStateChange).not.toHaveBeenCalled()
+    expect(persistence.setItem).not.toHaveBeenCalled()
+  })
+
+  it('hydrates async server resume state without connecting', async () => {
+    const storedSnapshot: ChatResumeSnapshot = {
+      resumeState: {
+        threadId: 'thread-1',
+        runId: 'stored-run',
+      },
+      pendingInterrupts: [],
+    }
+    let resolveHydrate: (snapshot: ChatResumeSnapshot) => void = () => {}
+    const persistence: ChatServerPersistence = {
+      getItem: vi.fn(
+        () =>
+          new Promise<ChatResumeSnapshot>((resolve) => {
+            resolveHydrate = resolve
+          }),
+      ),
+      setItem: vi.fn(),
+      removeItem: vi.fn(),
+    }
+    const { adapter, contexts } = recordingAdapter([[]])
+    const onResumeStateChange = vi.fn()
+
+    const client = new ChatClient({
+      connection: adapter,
+      threadId: 'thread-1',
+      persistence: { server: persistence },
+      onResumeStateChange,
+    })
+
+    resolveHydrate(storedSnapshot)
+    await Promise.resolve()
+    await Promise.resolve()
+
+    expect(client.getResumeState()).toEqual(storedSnapshot.resumeState)
+    expect(onResumeStateChange).toHaveBeenCalledWith(
+      storedSnapshot.resumeState,
+      [],
+    )
+    expect(contexts).toHaveLength(0)
+  })
+
+  it('does not persist late resume snapshots after server-only clear', async () => {
+    const writes: Array<ChatResumeSnapshot | null> = []
+    let releaseLateChunk: () => void = () => {}
+    let markLateChunkReady: () => void = () => {}
+    const lateChunkReady = new Promise<void>((resolve) => {
+      markLateChunkReady = resolve
+    })
+    const persistence: ChatServerPersistence = {
+      getItem: vi.fn(() => null),
+      setItem: vi.fn((_id, snapshot) => {
+        writes.push(snapshot)
+      }),
+      removeItem: vi.fn(() => {
+        writes.push(null)
+      }),
+    }
+    const adapter: ConnectConnectionAdapter = {
+      async *connect(_messages, _data, _signal, runContext) {
+        yield {
+          type: EventType.RUN_STARTED,
+          runId: runContext?.runId ?? 'run-1',
+          threadId: 'thread-1',
+          timestamp: Date.now(),
+        }
+        await new Promise<void>((resolve) => {
+          releaseLateChunk = resolve
+          markLateChunkReady()
+        })
+        yield text('late')
+      },
+    }
+    const client = new ChatClient({
+      connection: adapter,
+      threadId: 'thread-1',
+      persistence: { server: persistence },
+    })
+
+    const sendPromise = client.sendMessage('hi')
+    await lateChunkReady
+    client.clear()
+    releaseLateChunk()
+    await sendPromise
+
+    expect(persistence.removeItem).toHaveBeenCalledWith('thread-1')
+    expect(writes.at(-1)).toBeNull()
+  })
+
+  it('keeps server resume persistence removed when async set resolves after clear', async () => {
+    let storedSnapshot: ChatResumeSnapshot | null = null
+    const pendingSets: Array<{
+      snapshot: ChatResumeSnapshot
+      resolve: () => void
+    }> = []
+    const persistence: ChatServerPersistence = {
+      getItem: vi.fn(() => storedSnapshot),
+      setItem: vi.fn((_id, snapshot) => {
+        return new Promise<void>((resolve) => {
+          pendingSets.push({
+            snapshot,
+            resolve: () => {
+              storedSnapshot = snapshot
+              resolve()
+            },
+          })
+        })
+      }),
+      removeItem: vi.fn(() => {
+        storedSnapshot = null
+      }),
+    }
+    const { adapter } = recordingAdapter([
+      (ctx) => [
+        {
+          type: EventType.RUN_STARTED,
+          runId: ctx?.runId ?? 'run-1',
+          threadId: ctx?.threadId ?? 'thread-1',
+          timestamp: Date.now(),
+        },
+        text('a'),
+        {
+          type: EventType.RUN_FINISHED,
+          runId: ctx?.runId ?? 'run-1',
+          threadId: ctx?.threadId ?? 'thread-1',
+          timestamp: Date.now(),
+          outcome: {
+            type: 'interrupt',
+            interrupts: [{ id: 'interrupt-1', reason: 'client_tool_input' }],
+          },
+        },
+      ],
+    ])
+    const client = new ChatClient({
+      connection: adapter,
+      threadId: 'thread-1',
+      persistence: { server: persistence },
+    })
+
+    await client.sendMessage('hi')
+    expect(pendingSets.length).toBeGreaterThan(0)
+
+    client.clear()
+    for (const pendingSet of pendingSets) {
+      pendingSet.resolve()
+    }
+    await Promise.all(
+      pendingSets.map(
+        () => new Promise<void>((resolve) => queueMicrotask(resolve)),
+      ),
+    )
+
+    expect(persistence.removeItem).toHaveBeenCalledWith('thread-1')
+    expect(storedSnapshot).toBeNull()
+  })
+
+  it('addToolResult for pending client-tool input sends a resume item', async () => {
+    const { adapter, contexts } = recordingAdapter([
+      (ctx) => [
+        {
+          type: EventType.RUN_STARTED,
+          runId: ctx?.runId ?? 'run-1',
+          threadId: ctx?.threadId ?? 'thread-1',
+          timestamp: Date.now(),
+        },
+        text('a'),
+        {
+          type: EventType.RUN_FINISHED,
+          runId: ctx?.runId ?? 'run-1',
+          threadId: ctx?.threadId ?? 'thread-1',
+          timestamp: Date.now(),
+          outcome: {
+            type: 'interrupt',
+            interrupts: [
+              {
+                id: 'interrupt-tool-1',
+                reason: 'client_tool_input',
+                toolCallId: 'tool-call-1',
+              },
+            ],
+          },
+        },
+      ],
+      [],
+    ])
+    const client = new ChatClient({ connection: adapter, threadId: 'thread-1' })
+
+    await client.sendMessage('hi')
+    const resumeState = client.getResumeState()
+    await client.addToolResult({
+      toolCallId: 'tool-call-1',
+      tool: 'lookup',
+      output: { answer: 42 },
+    })
+
+    expect(contexts[1]?.threadId).toBe(resumeState?.threadId)
+    expect(contexts[1]?.runId).toBe(resumeState?.runId)
+    expect(contexts[1]?.resume).toEqual([
+      {
+        interruptId: 'interrupt-tool-1',
+        status: 'resolved',
+        payload: { answer: 42 },
+      },
+    ])
+  })
+
+  it('addToolResult waits for all pending client-tool interrupts before resuming', async () => {
+    const { adapter, contexts } = recordingAdapter([
+      (ctx) => [
+        {
+          type: EventType.RUN_STARTED,
+          runId: ctx?.runId ?? 'run-1',
+          threadId: ctx?.threadId ?? 'thread-1',
+          timestamp: Date.now(),
+        },
+        text('a'),
+        {
+          type: EventType.RUN_FINISHED,
+          runId: ctx?.runId ?? 'run-1',
+          threadId: ctx?.threadId ?? 'thread-1',
+          timestamp: Date.now(),
+          outcome: {
+            type: 'interrupt',
+            interrupts: [
+              {
+                id: 'interrupt-tool-1',
+                reason: 'client_tool_input',
+                toolCallId: 'tool-call-1',
+              },
+              {
+                id: 'interrupt-tool-2',
+                reason: 'client_tool_input',
+                toolCallId: 'tool-call-2',
+              },
+            ],
+          },
+        },
+      ],
+      [],
+    ])
+    const client = new ChatClient({ connection: adapter, threadId: 'thread-1' })
+
+    await client.sendMessage('hi')
+    await client.addToolResult({
+      toolCallId: 'tool-call-1',
+      tool: 'lookup',
+      output: { answer: 42 },
+    })
+
+    expect(contexts).toHaveLength(1)
+
+    await client.addToolResult({
+      toolCallId: 'tool-call-2',
+      tool: 'lookup',
+      output: { answer: 43 },
+    })
+
+    expect(contexts).toHaveLength(2)
+    expect(contexts[1]?.resume).toEqual([
+      {
+        interruptId: 'interrupt-tool-1',
+        status: 'resolved',
+        payload: { answer: 42 },
+      },
+      {
+        interruptId: 'interrupt-tool-2',
+        status: 'resolved',
+        payload: { answer: 43 },
+      },
+    ])
+  })
+})
diff --git a/packages/ai-client/tests/chat-client.test.ts b/packages/ai-client/tests/chat-client.test.ts
index 7f8cb66c4..89456978e 100644
--- a/packages/ai-client/tests/chat-client.test.ts
+++ b/packages/ai-client/tests/chat-client.test.ts
@@ -14,7 +14,11 @@ import type {
   ConnectionAdapter,
 } from '../src/connection-adapters'
 import type { ModelMessage, StreamChunk } from '@tanstack/ai/client'
-import type { ChatClientPersistence, UIMessage } from '../src/types'
+import type {
+  ChatClientPersistence,
+  ChatServerPersistence,
+  UIMessage,
+} from '../src/types'
 
 describe('ChatClient', () => {
   const persistedMessage: UIMessage = {
@@ -96,6 +100,20 @@ describe('ChatClient', () => {
       expect(client.getMessages()).toEqual([persistedMessage])
     })
 
+    it('should hydrate messages from persistence.client', () => {
+      const adapter = createMockConnectionAdapter()
+      const persistence = createPersistence([persistedMessage])
+
+      const client = new ChatClient({
+        connection: adapter,
+        id: 'chat-1',
+        persistence: { client: persistence },
+      })
+
+      expect(persistence.getItem).toHaveBeenCalledWith('chat-1')
+      expect(client.getMessages()).toEqual([persistedMessage])
+    })
+
     it('should prefer persisted messages over initial messages', () => {
       const adapter = createMockConnectionAdapter()
       const persistence = createPersistence([persistedMessage])
@@ -216,6 +234,32 @@ describe('ChatClient', () => {
       ])
     })
 
+    it('should ignore async persistence hydration after dispose', async () => {
+      const adapter = createMockConnectionAdapter()
+      const deferred = createDeferred<Array<UIMessage>>()
+      const onMessagesChange = vi.fn()
+      const persistence = {
+        getItem: vi.fn(() => deferred.promise),
+        setItem: vi.fn(),
+        removeItem: vi.fn(),
+      }
+
+      const client = new ChatClient({
+        connection: adapter,
+        id: 'chat-1',
+        initialMessages: [initialMessage],
+        onMessagesChange,
+        persistence,
+      })
+
+      client.dispose()
+      deferred.resolve([persistedMessage])
+      await new Promise((resolve) => setTimeout(resolve, 0))
+
+      expect(client.getMessages()).toEqual([initialMessage])
+      expect(onMessagesChange).not.toHaveBeenCalled()
+    })
+
     it('should keep current constructor behavior when persistence is omitted', () => {
       const adapter = createMockConnectionAdapter()
 
@@ -677,6 +721,132 @@ describe('ChatClient', () => {
       expect(storedMessages).toEqual(client.getMessages())
     })
 
+    it('should keep fresh runless chunks after server-only clear drains an ignored terminal chunk', async () => {
+      const releaseStaleTerminal = createDeferred<void>()
+      const staleTerminalAttempted = createDeferred<void>()
+      const queuedChunks: Array<{
+        prompt: string
+        chunks: Array<StreamChunk>
+      }> = []
+      let wakeSubscriber: (() => void) | null = null
+      const wakeQueuedSubscriber = () => {
+        const wake = wakeSubscriber
+        wakeSubscriber = null
+        wake?.()
+      }
+      const adapter: ConnectionAdapter = {
+        subscribe: vi.fn(
+          (_signal?: AbortSignal): AsyncIterable<StreamChunk> => {
+            return (async function* () {
+              while (true) {
+                if (queuedChunks.length === 0) {
+                  await new Promise<void>((resolve) => {
+                    wakeSubscriber = resolve
+                  })
+                }
+                const next = queuedChunks.shift()
+                if (!next) continue
+                yield next.chunks[0]!
+                if (next.prompt === 'A') {
+                  await releaseStaleTerminal.promise
+                  yield* next.chunks.slice(1)
+                  staleTerminalAttempted.resolve()
+                  continue
+                }
+                yield* next.chunks.slice(1)
+              }
+            })()
+          },
+        ),
+        send: vi.fn(
+          async (
+            messages: Array<UIMessage> | Array<ModelMessage>,
+            _data,
+            _signal,
+            runContext,
+          ) => {
+            const prompt = messages
+              .flatMap((message) => ('parts' in message ? message.parts : []))
+              .find((part) => part.type === 'text')?.content
+
+            queuedChunks.push({
+              prompt: prompt ?? '',
+              chunks:
+                prompt === 'A'
+                  ? [
+                      {
+                        type: EventType.RUN_STARTED,
+                        threadId: runContext?.threadId ?? 'thread-1',
+                        runId: runContext?.runId ?? 'run-cleared',
+                        timestamp: Date.now(),
+                      } as StreamChunk,
+                      {
+                        type: EventType.RUN_FINISHED,
+                        threadId: runContext?.threadId ?? 'thread-1',
+                        runId: runContext?.runId ?? 'run-cleared',
+                        timestamp: Date.now(),
+                      } as StreamChunk,
+                    ]
+                  : createTextChunks(
+                      'fresh server-only response',
+                      'fresh-msg',
+                    ).map((chunk) => {
+                      if (
+                        chunk.type === 'TEXT_MESSAGE_START' ||
+                        chunk.type === 'TEXT_MESSAGE_CONTENT' ||
+                        chunk.type === 'TEXT_MESSAGE_END' ||
+                        chunk.type === 'RUN_FINISHED'
+                      ) {
+                        const { runId: _runId, ...withoutRunId } = chunk
+                        return withoutRunId as StreamChunk
+                      }
+                      return chunk
+                    }),
+            })
+            wakeQueuedSubscriber()
+          },
+        ),
+      }
+      const serverPersistence: ChatServerPersistence = {
+        getItem: vi.fn(() => undefined),
+        setItem: vi.fn(),
+        removeItem: vi.fn(),
+      }
+      const client = new ChatClient({
+        connection: adapter,
+        id: 'chat-1',
+        persistence: { server: serverPersistence },
+      })
+
+      const firstSend = client.sendMessage('A')
+      await vi.waitFor(() => {
+        expect(client.getSessionGenerating()).toBe(true)
+      })
+
+      client.clear()
+      releaseStaleTerminal.resolve()
+      await staleTerminalAttempted.promise
+      await firstSend
+
+      const secondSend = client.sendMessage('B')
+
+      const getFinalText = () =>
+        client
+          .getMessages()
+          .flatMap((message) => message.parts)
+          .filter((part) => part.type === 'text')
+          .map((part) => part.content)
+          .join('')
+
+      await vi.waitFor(() => {
+        expect(getFinalText()).toContain('fresh server-only response')
+      })
+      await secondSend
+
+      const finalText = getFinalText()
+      expect(finalText).toContain('B')
+      expect(finalText).not.toContain('A')
+    })
     it('should ignore stale messages snapshot after persisted clear', async () => {
       let storedMessages: Array<UIMessage> | undefined
       const releaseSnapshot = createDeferred<void>()
@@ -2320,7 +2490,7 @@ describe('ChatClient', () => {
       expect(persistence.setItem).not.toHaveBeenCalled()
     })
 
-    it('should not abort an in-flight stream when persistence is omitted', async () => {
+    it('should abort an in-flight stream when persistence is omitted', async () => {
       let abortSignal: AbortSignal | undefined
       // Gate the chunks on a deferred (instead of a fixed timer) so they are
       // released strictly after clear() runs — otherwise the assertion races
@@ -2342,18 +2512,14 @@ describe('ChatClient', () => {
       })
 
       client.clear()
-      expect(abortSignal?.aborted).toBe(false)
+      expect(abortSignal?.aborted).toBe(true)
 
-      // Without persistence, clear() does not abort the in-flight stream, so
-      // its chunks still populate messages once they arrive.
+      // Clear invalidates in-flight stream work even when message persistence
+      // is omitted, so delayed chunks cannot repopulate messages.
       releaseChunks.resolve()
       await sendPromise
 
-      expect(client.getMessages()).toEqual(
-        expect.arrayContaining([
-          expect.objectContaining({ role: 'assistant' }),
-        ]),
-      )
+      expect(client.getMessages()).toEqual([])
     })
 
     it('should prevent delayed stream chunks from recreating messages after clear', async () => {
@@ -3238,16 +3404,16 @@ describe('ChatClient', () => {
 
       const client = new ChatClient({
         connection: adapter,
-        body: { model: 'gpt-4', temperature: 0.7 },
+        body: { model: 'gpt-5.5', temperature: 0.7 },
       })
 
       await client.sendMessage('Hello', {
-        model: 'gpt-4-turbo',
+        model: 'gpt-5.5',
         maxTokens: 100,
       })
 
       // Per-message body should override base body
-      expect(capturedData?.['model']).toBe('gpt-4-turbo')
+      expect(capturedData?.['model']).toBe('gpt-5.5')
       expect(capturedData?.['temperature']).toBe(0.7) // From base body
       expect(capturedData?.['maxTokens']).toBe(100) // From per-message body
     })
@@ -3264,13 +3430,13 @@ describe('ChatClient', () => {
 
       const client = new ChatClient({
         connection: adapter,
-        forwardedProps: { provider: 'openai', model: 'gpt-4o' },
+        forwardedProps: { provider: 'openai', model: 'gpt-5.5' },
       })
 
       await client.sendMessage('Hello')
 
       expect(capturedData?.['provider']).toBe('openai')
-      expect(capturedData?.['model']).toBe('gpt-4o')
+      expect(capturedData?.['model']).toBe('gpt-5.5')
     })
 
     it('updateOptions({ forwardedProps }) leaves a previously-set body intact', async () => {
@@ -3286,15 +3452,15 @@ describe('ChatClient', () => {
       const client = new ChatClient({
         connection: adapter,
         body: { provider: 'openai' },
-        forwardedProps: { model: 'gpt-4' },
+        forwardedProps: { model: 'gpt-5.5' },
       })
 
       // Replace only `forwardedProps` — `body` must survive.
-      client.updateOptions({ forwardedProps: { model: 'gpt-4o' } })
+      client.updateOptions({ forwardedProps: { model: 'gpt-5.5' } })
 
       await client.sendMessage('Hi')
       expect(captures[0]?.['provider']).toBe('openai')
-      expect(captures[0]?.['model']).toBe('gpt-4o')
+      expect(captures[0]?.['model']).toBe('gpt-5.5')
     })
 
     it('updateOptions({ body }) leaves a previously-set forwardedProps intact', async () => {
@@ -3310,14 +3476,14 @@ describe('ChatClient', () => {
       const client = new ChatClient({
         connection: adapter,
         body: { provider: 'openai' },
-        forwardedProps: { model: 'gpt-4' },
+        forwardedProps: { model: 'gpt-5.5' },
       })
 
       client.updateOptions({ body: { provider: 'anthropic' } })
 
       await client.sendMessage('Hi')
       expect(captures[0]?.['provider']).toBe('anthropic')
-      expect(captures[0]?.['model']).toBe('gpt-4')
+      expect(captures[0]?.['model']).toBe('gpt-5.5')
     })
 
     it('should merge body and forwardedProps with forwardedProps winning', async () => {
@@ -3334,14 +3500,14 @@ describe('ChatClient', () => {
         connection: adapter,
         // Legacy `body` and new `forwardedProps` declared together —
         // simulates a mid-migration codebase.
-        body: { model: 'gpt-4', temperature: 0.7 },
-        forwardedProps: { model: 'gpt-4o' },
+        body: { model: 'gpt-5.5', temperature: 0.7 },
+        forwardedProps: { model: 'gpt-5.5' },
       })
 
       await client.sendMessage('Hello')
 
       // forwardedProps wins on key collision so partial migrations are sane.
-      expect(capturedData?.['model']).toBe('gpt-4o')
+      expect(capturedData?.['model']).toBe('gpt-5.5')
       // Non-conflicting keys from `body` are still forwarded.
       expect(capturedData?.['temperature']).toBe(0.7)
     })
@@ -3404,7 +3570,7 @@ describe('ChatClient', () => {
 
       const client = new ChatClient({
         connection: adapter,
-        body: { model: 'gpt-4' },
+        body: { model: 'gpt-5.5' },
       })
 
       // First message with per-message body
@@ -3414,7 +3580,7 @@ describe('ChatClient', () => {
       // Second message without per-message body should not have temperature
       await client.sendMessage('Second')
       expect(capturedData?.['temperature']).toBeUndefined()
-      expect(capturedData?.['model']).toBe('gpt-4')
+      expect(capturedData?.['model']).toBe('gpt-5.5')
     })
 
     it('should emit events with multimodal content', async () => {
diff --git a/packages/ai-client/tests/client-persistor.test.ts b/packages/ai-client/tests/client-persistor.test.ts
index 05cc4380c..55430faaa 100644
--- a/packages/ai-client/tests/client-persistor.test.ts
+++ b/packages/ai-client/tests/client-persistor.test.ts
@@ -1,12 +1,19 @@
-import { beforeEach, describe, expect, it, vi } from 'vitest'
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
 import { EventType } from '@tanstack/ai/client'
-import { ChatPersistor } from '../src/client-persistor'
+import {
+  ChatPersistor,
+  localStorageAIPersistence,
+} from '../src/client-persistor'
 import { createMockPersistence, createUIMessage } from './test-utils'
 import type { StreamChunk } from '@tanstack/ai/client'
 import type { ChatClientPersistence, UIMessage } from '../src/types'
 
 const CHAT_ID = 'chat-1'
 
+afterEach(() => {
+  vi.unstubAllGlobals()
+})
+
 /** Resolve after pending micro- and macro-tasks have drained. */
 function flushAsync(): Promise<void> {
   return new Promise((resolve) => setTimeout(resolve, 0))
@@ -76,6 +83,40 @@ function messagesSnapshot(): StreamChunk {
 }
 
 describe('ChatPersistor', () => {
+  describe('localStorageAIPersistence', () => {
+    it('stores generic values under the configured prefix', () => {
+      const storage = new Map<string, string>()
+      vi.stubGlobal('localStorage', {
+        get length() {
+          return storage.size
+        },
+        clear: vi.fn(() => storage.clear()),
+        getItem: vi.fn((key: string) => storage.get(key) ?? null),
+        key: vi.fn(
+          (index: number) => Array.from(storage.keys())[index] ?? null,
+        ),
+        removeItem: vi.fn((key: string) => {
+          storage.delete(key)
+        }),
+        setItem: vi.fn((key: string, value: string) => {
+          storage.set(key, value)
+        }),
+      } satisfies Storage)
+
+      const adapter = localStorageAIPersistence<{ count: number }>({
+        keyPrefix: 'custom-prefix:',
+      })
+
+      adapter.setItem('value-1', { count: 42 })
+
+      expect(globalThis.localStorage.setItem).toHaveBeenCalledWith(
+        'custom-prefix:value-1',
+        JSON.stringify({ count: 42 }),
+      )
+      expect(adapter.getItem('value-1')).toEqual({ count: 42 })
+    })
+  })
+
   describe('readInitial', () => {
     it('returns the stored messages from a synchronous getItem', () => {
       const stored = [createUIMessage('m-1')]
diff --git a/packages/ai-client/tests/connection-adapters-resumable.test.ts b/packages/ai-client/tests/connection-adapters-resumable.test.ts
new file mode 100644
index 000000000..d5aa059a4
--- /dev/null
+++ b/packages/ai-client/tests/connection-adapters-resumable.test.ts
@@ -0,0 +1,157 @@
+import { describe, expect, it, vi } from 'vitest'
+import { EventType } from '@tanstack/ai/client'
+import {
+  DurableStreamIncompleteError,
+  fetchServerSentEvents,
+} from '../src/connection-adapters'
+import type { StreamChunk } from '@tanstack/ai/client'
+
+function readerFromString(body: string) {
+  let sent = false
+  return {
+    read: vi.fn(async () => {
+      if (sent) return { done: true, value: undefined }
+      sent = true
+      return { done: false, value: new TextEncoder().encode(body) }
+    }),
+    releaseLock: vi.fn(),
+  }
+}
+
+function sseResponse(body: string): Response {
+  return {
+    ok: true,
+    body: { getReader: () => readerFromString(body) },
+    headers: new Headers(),
+  } as unknown as Response
+}
+
+function contentEvent(id: string, delta: string): string {
+  const chunk = {
+    type: EventType.TEXT_MESSAGE_CONTENT,
+    messageId: 'm',
+    model: 'test',
+    timestamp: 0,
+    delta,
+    content: delta,
+  }
+  return `id: ${id}\ndata: ${JSON.stringify(chunk)}\n\n`
+}
+
+function finishedEvent(id: string): string {
+  const chunk = {
+    type: EventType.RUN_FINISHED,
+    threadId: 't',
+    runId: 'r',
+    model: 'test',
+    timestamp: 0,
+    finishReason: 'stop',
+  }
+  return `id: ${id}\ndata: ${JSON.stringify(chunk)}\n\n`
+}
+
+describe('resumable SSE connection adapter', () => {
+  it('reconnects with Last-Event-ID and de-dupes already-seen chunks', async () => {
+    const fetchClient = vi.fn(async (_url: any, init: any) => {
+      if (fetchClient.mock.calls.length === 1) {
+        // First response: 3 tagged chunks, then the connection closes with no
+        // terminal event (a mid-stream drop).
+        return sseResponse(
+          contentEvent('run@1', '1') +
+            contentEvent('run@2', '2') +
+            contentEvent('run@3', '3'),
+        )
+      }
+      // Second response (reconnect): server replays from the offset — it
+      // re-sends seq 3 (must be de-duped), then the tail + terminal.
+      expect((init.headers as Record<string, string>)['Last-Event-ID']).toBe(
+        'run@3',
+      )
+      return sseResponse(
+        contentEvent('run@3', '3') +
+          contentEvent('run@4', '4') +
+          finishedEvent('run@5'),
+      )
+    })
+
+    const adapter = fetchServerSentEvents('/api/chat', {
+      fetchClient: fetchClient as unknown as typeof fetch,
+    })
+
+    const chunks: Array<StreamChunk> = []
+    for await (const chunk of adapter.connect(
+      [{ role: 'user', content: 'hi' }],
+      undefined,
+      undefined,
+      { threadId: 't', runId: 'r' },
+    )) {
+      chunks.push(chunk)
+    }
+
+    const deltas = chunks
+      .filter((c) => c.type === EventType.TEXT_MESSAGE_CONTENT)
+      .map((c) => (c as { delta: string }).delta)
+    expect(deltas).toEqual(['1', '2', '3', '4'])
+    expect(chunks[chunks.length - 1]?.type).toBe(EventType.RUN_FINISHED)
+    expect(fetchClient).toHaveBeenCalledTimes(2)
+  })
+
+  it('joinRun opens the stream from the start with ?offset=-1', async () => {
+    const fetchClient = vi.fn(async (_url: unknown, _init?: unknown) =>
+      sseResponse(finishedEvent('run@1')),
+    )
+    const adapter = fetchServerSentEvents('/api/chat', {
+      fetchClient: fetchClient as unknown as typeof fetch,
+    })
+
+    const chunks: Array<StreamChunk> = []
+    for await (const chunk of adapter.joinRun('run-x')) {
+      chunks.push(chunk)
+    }
+
+    const calledUrl = String(fetchClient.mock.calls[0]![0])
+    expect(calledUrl).toContain('offset=-1')
+    expect(calledUrl).toContain('runId=run-x')
+    expect(chunks.map((c) => c.type)).toContain(EventType.RUN_FINISHED)
+  })
+
+  // Finding 6: a durable (id-tagged) run that ends with no terminal event and
+  // makes no forward progress on reconnect must surface an error, not silently
+  // return leaving the consumer with neither a terminal nor a failure.
+  it('surfaces an error when a durable run ends without a terminal and cannot progress', async () => {
+    const fetchClient = vi.fn(async () => {
+      if (fetchClient.mock.calls.length === 1) {
+        // First pass: two tagged content events, then a clean end with NO
+        // terminal — the adapter reconnects from run@2.
+        return sseResponse(
+          contentEvent('run@1', '1') + contentEvent('run@2', '2'),
+        )
+      }
+      // Reconnect: server replays nothing new (no progress) and still no
+      // terminal — the run cannot complete.
+      return sseResponse('')
+    })
+
+    const adapter = fetchServerSentEvents('/api/chat', {
+      fetchClient: fetchClient as unknown as typeof fetch,
+    })
+
+    const deltas: Array<string> = []
+    await expect(async () => {
+      for await (const chunk of adapter.connect(
+        [{ role: 'user', content: 'hi' }],
+        undefined,
+        undefined,
+        { threadId: 't', runId: 'r' },
+      )) {
+        if (chunk.type === EventType.TEXT_MESSAGE_CONTENT) {
+          deltas.push((chunk as { delta: string }).delta)
+        }
+      }
+    }).rejects.toBeInstanceOf(DurableStreamIncompleteError)
+
+    // The consumer still received everything delivered before the failure.
+    expect(deltas).toEqual(['1', '2'])
+    expect(fetchClient).toHaveBeenCalledTimes(2)
+  })
+})
diff --git a/packages/ai-client/tests/connection-adapters-xhr.test.ts b/packages/ai-client/tests/connection-adapters-xhr.test.ts
index c69430f5a..eedb5c6a9 100644
--- a/packages/ai-client/tests/connection-adapters-xhr.test.ts
+++ b/packages/ai-client/tests/connection-adapters-xhr.test.ts
@@ -125,6 +125,50 @@ describe('xhr connection adapters', () => {
       })
     })
 
+    it('sends resume in the AG-UI request body', async () => {
+      const { xhr, xhrFactory } = createFakeXhrFactory()
+      const adapter = xhrServerSentEvents('/api/chat', { xhrFactory })
+
+      const iterator = adapter
+        .connect([], undefined, undefined, {
+          threadId: 'thread-1',
+          runId: 'run-1',
+          resume: [
+            {
+              interruptId: 'interrupt-1',
+              status: 'resolved',
+              payload: { approved: true },
+            },
+            {
+              interruptId: 'interrupt-2',
+              status: 'cancelled',
+            },
+          ],
+        })
+        [Symbol.asyncIterator]()
+      const nextChunk = iterator.next()
+      await nextTick()
+
+      const body = JSON.parse(xhr.requestBody ?? '{}')
+      expect(body.resume).toEqual([
+        {
+          interruptId: 'interrupt-1',
+          status: 'resolved',
+          payload: { approved: true },
+        },
+        {
+          interruptId: 'interrupt-2',
+          status: 'cancelled',
+        },
+      ])
+
+      xhr.progress('data: [DONE]\n\n')
+      await expect(nextChunk).resolves.toMatchObject({
+        done: false,
+        value: { type: EventType.RUN_FINISHED },
+      })
+    })
+
     it('synthesizes RUN_FINISHED for [DONE] and ignores later bytes', async () => {
       const { xhr, xhrFactory } = createFakeXhrFactory()
       const adapter = xhrServerSentEvents('/api/chat', { xhrFactory })
diff --git a/packages/ai-client/tests/connection-adapters.test.ts b/packages/ai-client/tests/connection-adapters.test.ts
index 5339e0c7d..4c98d25d1 100644
--- a/packages/ai-client/tests/connection-adapters.test.ts
+++ b/packages/ai-client/tests/connection-adapters.test.ts
@@ -2,6 +2,7 @@ import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
 import { EventType } from '@tanstack/ai/client'
 import {
   fetchHttpStream,
+  fetcherToConnectionAdapter,
   fetchServerSentEvents,
   normalizeConnectionAdapter,
   rpcStream,
@@ -9,6 +10,7 @@ import {
 } from '../src/connection-adapters'
 import { UnsupportedResponseStreamError } from '../src'
 import type { StreamChunk } from '@tanstack/ai/client'
+import type { ChatFetcher } from '../src/types'
 
 describe('connection-adapters', () => {
   let originalFetch: typeof fetch
@@ -414,6 +416,61 @@ describe('connection-adapters', () => {
       expect(body.forwardedProps).toMatchObject({ key: 'value' })
     })
 
+    it('should include resume in the AG-UI request body', async () => {
+      const mockReader = {
+        read: vi.fn().mockResolvedValue({ done: true, value: undefined }),
+        releaseLock: vi.fn(),
+      }
+
+      const mockResponse = {
+        ok: true,
+        body: {
+          getReader: () => mockReader,
+        },
+      }
+
+      fetchMock.mockResolvedValue(mockResponse as any)
+
+      const adapter = fetchServerSentEvents('/api/chat')
+
+      for await (const _ of adapter.connect(
+        [{ role: 'user', content: 'Hello' }],
+        undefined,
+        undefined,
+        {
+          threadId: 'thread-1',
+          runId: 'run-1',
+          resume: [
+            {
+              interruptId: 'interrupt-1',
+              status: 'resolved',
+              payload: { approved: true },
+            },
+            {
+              interruptId: 'interrupt-2',
+              status: 'cancelled',
+            },
+          ],
+        },
+      )) {
+        // Consume
+      }
+
+      const call = fetchMock.mock.calls[0]
+      const body = JSON.parse(call?.[1]?.body as string)
+      expect(body.resume).toEqual([
+        {
+          interruptId: 'interrupt-1',
+          status: 'resolved',
+          payload: { approved: true },
+        },
+        {
+          interruptId: 'interrupt-2',
+          status: 'cancelled',
+        },
+      ])
+    })
+
     it('should mirror forwardedProps under legacy `data` field for backward-compat', async () => {
       const mockReader = {
         read: vi.fn().mockResolvedValue({ done: true, value: undefined }),
@@ -429,7 +486,7 @@ describe('connection-adapters', () => {
 
       for await (const _ of adapter.connect(
         [{ role: 'user', content: 'Hello' }],
-        { provider: 'openai', model: 'gpt-4o' },
+        { provider: 'openai', model: 'gpt-5.5' },
       )) {
         // Consume
       }
@@ -440,7 +497,7 @@ describe('connection-adapters', () => {
       // `body.forwardedProps.X`. Both must contain the same content
       // until the legacy `body` client option is removed.
       expect(body.data).toEqual(body.forwardedProps)
-      expect(body.data).toMatchObject({ provider: 'openai', model: 'gpt-4o' })
+      expect(body.data).toMatchObject({ provider: 'openai', model: 'gpt-5.5' })
     })
 
     it('should use custom fetchClient when provided', async () => {
@@ -561,7 +618,7 @@ describe('connection-adapters', () => {
       fetchMock.mockResolvedValue(mockResponse as any)
 
       const adapter = fetchServerSentEvents('/api/chat', {
-        body: { model: 'gpt-4o', provider: 'openai' },
+        body: { model: 'gpt-5.5', provider: 'openai' },
       })
 
       for await (const _ of adapter.connect(
@@ -574,7 +631,7 @@ describe('connection-adapters', () => {
       const call = fetchMock.mock.calls[0]
       const body = JSON.parse(call?.[1]?.body as string)
       expect(body.forwardedProps).toMatchObject({
-        model: 'gpt-4o',
+        model: 'gpt-5.5',
         provider: 'openai',
         key: 'value',
       })
@@ -987,6 +1044,49 @@ describe('connection-adapters', () => {
         expect.arrayContaining([expect.objectContaining({ role: 'user' })]),
         data,
         undefined,
+        undefined,
+      )
+    })
+
+    it('should pass run context to stream factory', async () => {
+      const streamFactory = vi.fn().mockImplementation(function* () {
+        yield {
+          type: EventType.RUN_FINISHED,
+          runId: 'run-1',
+          threadId: 'thread-1',
+          model: 'test',
+          timestamp: Date.now(),
+          finishReason: 'stop',
+        }
+      })
+
+      const adapter = stream(streamFactory)
+      const runContext = {
+        threadId: 'thread-1',
+        runId: 'run-1',
+        resume: [
+          {
+            interruptId: 'interrupt-1',
+            status: 'resolved' as const,
+            payload: { approved: true },
+          },
+        ],
+      }
+
+      for await (const _ of adapter.connect(
+        [{ role: 'user', content: 'Hello' }],
+        { key: 'value' },
+        undefined,
+        runContext,
+      )) {
+        // Consume
+      }
+
+      expect(streamFactory).toHaveBeenCalledWith(
+        expect.arrayContaining([expect.objectContaining({ role: 'user' })]),
+        { key: 'value' },
+        undefined,
+        runContext,
       )
     })
   })
@@ -1175,7 +1275,7 @@ describe('connection-adapters', () => {
       })
 
       const adapter = rpcStream(rpcCall)
-      const data = { model: 'gpt-4o' }
+      const data = { model: 'gpt-5.5' }
 
       for await (const _ of adapter.connect(
         [{ role: 'user', content: 'Hello' }],
@@ -1188,7 +1288,92 @@ describe('connection-adapters', () => {
         expect.arrayContaining([expect.objectContaining({ role: 'user' })]),
         data,
         undefined,
+        undefined,
       )
     })
+
+    it('should pass run context to RPC call', async () => {
+      const rpcCall = vi.fn().mockImplementation(function* () {
+        yield {
+          type: EventType.RUN_FINISHED,
+          runId: 'run-1',
+          threadId: 'thread-1',
+          model: 'test',
+          timestamp: Date.now(),
+          finishReason: 'stop',
+        }
+      })
+
+      const adapter = rpcStream(rpcCall)
+      const runContext = {
+        threadId: 'thread-1',
+        runId: 'run-1',
+        resume: [
+          {
+            interruptId: 'interrupt-1',
+            status: 'cancelled' as const,
+          },
+        ],
+      }
+
+      for await (const _ of adapter.connect(
+        [{ role: 'user', content: 'Hello' }],
+        { model: 'gpt-5.5' },
+        undefined,
+        runContext,
+      )) {
+        // Consume
+      }
+
+      expect(rpcCall).toHaveBeenCalledWith(
+        expect.arrayContaining([expect.objectContaining({ role: 'user' })]),
+        { model: 'gpt-5.5' },
+        undefined,
+        runContext,
+      )
+    })
+  })
+
+  describe('fetcherToConnectionAdapter', () => {
+    it('should forward resume to custom fetchers', async () => {
+      const fetcher = vi.fn<ChatFetcher>(async function* () {
+        yield {
+          type: EventType.RUN_FINISHED,
+          threadId: 'thread-1',
+          runId: 'run-1',
+          timestamp: Date.now(),
+        } as StreamChunk
+      })
+      const adapter = fetcherToConnectionAdapter(fetcher)
+      const abortController = new AbortController()
+
+      for await (const _ of adapter.connect(
+        [],
+        undefined,
+        abortController.signal,
+        {
+          threadId: 'thread-1',
+          runId: 'run-1',
+          resume: [
+            {
+              interruptId: 'interrupt-1',
+              status: 'resolved',
+              payload: { approved: true },
+            },
+          ],
+        },
+      )) {
+        // Consume
+      }
+
+      const [input] = fetcher.mock.calls[0]!
+      expect(input.resume).toEqual([
+        {
+          interruptId: 'interrupt-1',
+          status: 'resolved',
+          payload: { approved: true },
+        },
+      ])
+    })
   })
 })
diff --git a/packages/ai-client/tests/generation-client.test.ts b/packages/ai-client/tests/generation-client.test.ts
index fb921a89a..978fdf77c 100644
--- a/packages/ai-client/tests/generation-client.test.ts
+++ b/packages/ai-client/tests/generation-client.test.ts
@@ -1,8 +1,16 @@
 import { describe, expect, it, vi } from 'vitest'
 import { EventType } from '@tanstack/ai/client'
-import { GenerationClient, UnsupportedResponseStreamError } from '../src'
+import {
+  GenerationClient,
+  UnsupportedResponseStreamError,
+  VideoGenerationClient,
+} from '../src'
 import type { StreamChunk } from '@tanstack/ai/client'
 import type { ConnectConnectionAdapter } from '../src/connection-adapters'
+import type {
+  GenerationResumeSnapshot,
+  GenerationServerPersistence,
+} from '../src'
 
 // Helper to create a mock connect-based adapter from StreamChunks
 function createMockConnection(
@@ -17,6 +25,34 @@ function createMockConnection(
   }
 }
 
+function createDeferred<T = void>(): {
+  promise: Promise<T>
+  resolve: (value: T | PromiseLike<T>) => void
+  reject: (reason?: unknown) => void
+} {
+  let resolve!: (value: T | PromiseLike<T>) => void
+  let reject!: (reason?: unknown) => void
+  const promise = new Promise<T>((res, rej) => {
+    resolve = res
+    reject = rej
+  })
+  return { promise, resolve, reject }
+}
+
+async function waitForCondition(assertion: () => void): Promise<void> {
+  let lastError: unknown
+  for (let attempt = 0; attempt < 20; attempt++) {
+    try {
+      assertion()
+      return
+    } catch (error) {
+      lastError = error
+      await new Promise((resolve) => setTimeout(resolve, 0))
+    }
+  }
+  throw lastError
+}
+
 describe('GenerationClient', () => {
   describe('fetcher mode', () => {
     it('should generate a result using fetcher', async () => {
@@ -433,6 +469,266 @@ describe('GenerationClient', () => {
       expect(client.getStatus()).toBe('idle')
     })
 
+    it('should ignore chunks yielded after stop() by an abort-ignoring connection', async () => {
+      const onResult = vi.fn()
+      const aborted = createDeferred()
+
+      const connection: ConnectConnectionAdapter = {
+        async *connect(_msgs, _data, signal) {
+          yield {
+            type: EventType.RUN_STARTED as const,
+            runId: 'run-1',
+            threadId: 'thread-1',
+            timestamp: Date.now(),
+          }
+          signal?.addEventListener('abort', () => aborted.resolve(undefined), {
+            once: true,
+          })
+          await aborted.promise
+          yield {
+            type: EventType.CUSTOM as const,
+            name: 'generation:result',
+            value: { id: 'late-result' },
+            timestamp: Date.now(),
+          }
+          yield {
+            type: EventType.RUN_FINISHED as const,
+            runId: 'run-1',
+            threadId: 'thread-1',
+            finishReason: 'stop' as const,
+            timestamp: Date.now(),
+          }
+        },
+      }
+
+      const client = new GenerationClient({
+        connection,
+        onResult,
+      })
+
+      const generatePromise = client.generate({ prompt: 'test' })
+      await new Promise((resolve) => setTimeout(resolve, 0))
+
+      client.stop()
+      await generatePromise
+
+      expect(onResult).not.toHaveBeenCalled()
+      expect(client.getResult()).toBeNull()
+      expect(client.getStatus()).toBe('idle')
+    })
+
+    it('should not let a stopped run clear the controller for a newer generation', async () => {
+      const firstAborted = createDeferred()
+      const firstCanFinish = createDeferred()
+      const secondAborted = createDeferred()
+      const signals: Array<AbortSignal | undefined> = []
+
+      const connection: ConnectConnectionAdapter = {
+        async *connect(_msgs, data, signal) {
+          signals.push(signal)
+          if (data?.prompt === 'first') {
+            yield {
+              type: EventType.RUN_STARTED as const,
+              runId: 'run-1',
+              threadId: 'thread-1',
+              timestamp: Date.now(),
+            }
+            signal?.addEventListener(
+              'abort',
+              () => firstAborted.resolve(undefined),
+              { once: true },
+            )
+            await firstAborted.promise
+            await firstCanFinish.promise
+            yield {
+              type: EventType.CUSTOM as const,
+              name: 'generation:result',
+              value: { id: 'late-first' },
+              timestamp: Date.now(),
+            }
+            return
+          }
+
+          yield {
+            type: EventType.RUN_STARTED as const,
+            runId: 'run-2',
+            threadId: 'thread-1',
+            timestamp: Date.now(),
+          }
+          signal?.addEventListener(
+            'abort',
+            () => secondAborted.resolve(undefined),
+            { once: true },
+          )
+          await secondAborted.promise
+        },
+      }
+
+      const client = new GenerationClient({
+        connection,
+      })
+
+      const firstGenerate = client.generate({ prompt: 'first' })
+      await waitForCondition(() => {
+        expect(signals).toHaveLength(1)
+      })
+
+      client.stop()
+      const secondGenerate = client.generate({ prompt: 'second' })
+      await waitForCondition(() => {
+        expect(signals).toHaveLength(2)
+        expect(client.getIsLoading()).toBe(true)
+      })
+
+      firstCanFinish.resolve(undefined)
+      await firstGenerate
+
+      expect(client.getIsLoading()).toBe(true)
+
+      client.stop()
+      expect(signals[1]?.aborted).toBe(true)
+
+      await secondGenerate
+      expect(client.getIsLoading()).toBe(false)
+    })
+
+    it('should ignore video chunks yielded after stop() by an abort-ignoring connection', async () => {
+      const onResult = vi.fn()
+      const onStatusUpdate = vi.fn()
+      const aborted = createDeferred()
+
+      const connection: ConnectConnectionAdapter = {
+        async *connect(_msgs, _data, signal) {
+          yield {
+            type: EventType.RUN_STARTED as const,
+            runId: 'run-1',
+            threadId: 'thread-1',
+            timestamp: Date.now(),
+          }
+          signal?.addEventListener('abort', () => aborted.resolve(undefined), {
+            once: true,
+          })
+          await aborted.promise
+          yield {
+            type: EventType.CUSTOM as const,
+            name: 'generation:result',
+            value: { id: 'late-video' },
+            timestamp: Date.now(),
+          }
+          yield {
+            type: EventType.CUSTOM as const,
+            name: 'video:status',
+            value: { status: 'completed', progress: 100 },
+            timestamp: Date.now(),
+          }
+          yield {
+            type: EventType.RUN_FINISHED as const,
+            runId: 'run-1',
+            threadId: 'thread-1',
+            finishReason: 'stop' as const,
+            timestamp: Date.now(),
+          }
+        },
+      }
+
+      const client = new VideoGenerationClient({
+        connection,
+        onResult,
+        onStatusUpdate,
+      })
+
+      const generatePromise = client.generate({ prompt: 'test' })
+      await new Promise((resolve) => setTimeout(resolve, 0))
+
+      client.stop()
+      await generatePromise
+
+      expect(onResult).not.toHaveBeenCalled()
+      expect(onStatusUpdate).not.toHaveBeenCalled()
+      expect(client.getResult()).toBeNull()
+      expect(client.getVideoStatus()).toBeNull()
+      expect(client.getStatus()).toBe('idle')
+    })
+
+    it('should not let a stopped video run clear the controller for a newer generation', async () => {
+      const firstAborted = createDeferred()
+      const firstCanFinish = createDeferred()
+      const secondAborted = createDeferred()
+      const signals: Array<AbortSignal | undefined> = []
+
+      const connection: ConnectConnectionAdapter = {
+        async *connect(_msgs, data, signal) {
+          signals.push(signal)
+          if (data?.prompt === 'first') {
+            yield {
+              type: EventType.RUN_STARTED as const,
+              runId: 'run-1',
+              threadId: 'thread-1',
+              timestamp: Date.now(),
+            }
+            signal?.addEventListener(
+              'abort',
+              () => firstAborted.resolve(undefined),
+              { once: true },
+            )
+            await firstAborted.promise
+            await firstCanFinish.promise
+            yield {
+              type: EventType.CUSTOM as const,
+              name: 'generation:result',
+              value: {
+                jobId: 'late-first',
+                status: 'completed',
+                url: 'https://example.com/late.mp4',
+              },
+              timestamp: Date.now(),
+            }
+            return
+          }
+
+          yield {
+            type: EventType.RUN_STARTED as const,
+            runId: 'run-2',
+            threadId: 'thread-1',
+            timestamp: Date.now(),
+          }
+          signal?.addEventListener(
+            'abort',
+            () => secondAborted.resolve(undefined),
+            { once: true },
+          )
+          await secondAborted.promise
+        },
+      }
+
+      const client = new VideoGenerationClient({
+        connection,
+      })
+
+      const firstGenerate = client.generate({ prompt: 'first' })
+      await waitForCondition(() => {
+        expect(signals).toHaveLength(1)
+      })
+
+      client.stop()
+      const secondGenerate = client.generate({ prompt: 'second' })
+      await waitForCondition(() => {
+        expect(signals).toHaveLength(2)
+        expect(client.getIsLoading()).toBe(true)
+      })
+
+      firstCanFinish.resolve(undefined)
+      await firstGenerate
+
+      expect(client.getIsLoading()).toBe(true)
+
+      client.stop()
+      expect(signals[1]?.aborted).toBe(true)
+
+      await secondGenerate
+      expect(client.getIsLoading()).toBe(false)
+    })
+
     it('should not set result if fetcher resolves after stop()', async () => {
       let resolvePromise: (value: { id: string }) => void
       const onResult = vi.fn()
@@ -1031,4 +1327,131 @@ describe('GenerationClient', () => {
       expect(states).toEqual(['generating', 'error'])
     })
   })
+
+  describe('resume snapshot persistence', () => {
+    it('reports rejected persistence writes without rejecting generation', async () => {
+      const warningSpy = vi.spyOn(console, 'warn').mockImplementation(() => {})
+      const persistenceError = new Error('persistence failed')
+      const persistence: GenerationServerPersistence = {
+        getItem: vi.fn(),
+        setItem: vi.fn(async () => {
+          throw persistenceError
+        }),
+        removeItem: vi.fn(),
+      }
+      const client = new GenerationClient({
+        connection: createMockConnection([
+          {
+            type: EventType.RUN_STARTED,
+            runId: 'run-1',
+            threadId: 'thread-1',
+            timestamp: Date.now(),
+          },
+        ]),
+        persistence: { server: persistence },
+      })
+
+      await expect(client.generate({ prompt: 'test' })).resolves.toBeUndefined()
+
+      await waitForCondition(() => {
+        expect(warningSpy).toHaveBeenCalledWith(
+          '[TanStack AI] Failed to persist generation resume snapshot',
+          persistenceError,
+        )
+      })
+
+      warningSpy.mockRestore()
+    })
+
+    it('keeps a delayed running write from overwriting a terminal complete snapshot', async () => {
+      const runningWrite = createDeferred()
+      let storedSnapshot: GenerationResumeSnapshot | undefined
+      const persistence: GenerationServerPersistence = {
+        getItem: vi.fn(),
+        setItem: vi.fn(async (_id, snapshot) => {
+          if (snapshot.status === 'running') {
+            await runningWrite.promise
+          }
+          storedSnapshot = snapshot
+        }),
+        removeItem: vi.fn(),
+      }
+      const client = new GenerationClient({
+        connection: createMockConnection([
+          {
+            type: EventType.RUN_STARTED,
+            runId: 'run-1',
+            threadId: 'thread-1',
+            timestamp: Date.now(),
+          },
+          {
+            type: EventType.RUN_FINISHED,
+            runId: 'run-1',
+            threadId: 'thread-1',
+            finishReason: 'stop',
+            timestamp: Date.now(),
+          },
+        ]),
+        persistence: { server: persistence },
+      })
+
+      await client.generate({ prompt: 'test' })
+      expect(persistence.setItem).toHaveBeenCalledTimes(1)
+      runningWrite.resolve(undefined)
+
+      await waitForCondition(() => {
+        expect(persistence.setItem).toHaveBeenCalledTimes(2)
+        expect(storedSnapshot).toMatchObject({
+          status: 'complete',
+          resumeState: null,
+        })
+      })
+    })
+
+    it('keeps a delayed video running write from overwriting a terminal error snapshot', async () => {
+      const runningWrite = createDeferred()
+      let storedSnapshot: GenerationResumeSnapshot | undefined
+      const persistence: GenerationServerPersistence = {
+        getItem: vi.fn(),
+        setItem: vi.fn(async (_id, snapshot) => {
+          if (snapshot.status === 'running') {
+            await runningWrite.promise
+          }
+          storedSnapshot = snapshot
+        }),
+        removeItem: vi.fn(),
+      }
+      const client = new VideoGenerationClient({
+        connection: createMockConnection([
+          {
+            type: EventType.RUN_STARTED,
+            runId: 'run-1',
+            threadId: 'thread-1',
+            timestamp: Date.now(),
+          },
+          {
+            type: EventType.RUN_ERROR,
+            runId: 'run-1',
+            threadId: 'thread-1',
+            message: 'Video failed',
+            timestamp: Date.now(),
+          },
+        ]),
+        persistence: { server: persistence },
+      })
+
+      await client.generate({ prompt: 'test' })
+      expect(persistence.setItem).toHaveBeenCalledTimes(1)
+      runningWrite.resolve(undefined)
+
+      await waitForCondition(() => {
+        expect(persistence.setItem).toHaveBeenCalledTimes(2)
+        expect(storedSnapshot).toMatchObject({
+          status: 'error',
+          resumeState: null,
+          error: { message: 'Video failed' },
+        })
+      })
+    })
+  })
 })
diff --git a/packages/ai-client/tests/generation-resume-state.test.ts b/packages/ai-client/tests/generation-resume-state.test.ts
new file mode 100644
index 000000000..74f8fad78
--- /dev/null
+++ b/packages/ai-client/tests/generation-resume-state.test.ts
@@ -0,0 +1,259 @@
+import { describe, expect, it } from 'vitest'
+import { EventType } from '@tanstack/ai/client'
+import {
+  GENERATION_EVENTS,
+  updateGenerationResumeSnapshot,
+} from '../src/generation-types'
+import type { PersistedArtifactRef, StreamChunk } from '@tanstack/ai/client'
+import type { GenerationResumeSnapshot } from '../src/generation-types'
+
+const artifactRef: PersistedArtifactRef = {
+  role: 'output',
+  artifactId: 'artifact-1',
+  threadId: 'thread-1',
+  runId: 'run-1',
+  name: 'image.png',
+  mimeType: 'image/png',
+  size: 1234,
+  createdAt: '2026-07-06T00:00:00.000Z',
+  source: {
+    activity: 'image',
+    path: 'thread-1/run-1/image.png',
+    provider: 'test',
+    model: 'image-model',
+    mediaType: 'image',
+  },
+}
+
+function reduceChunks(
+  chunks: ReadonlyArray<StreamChunk>,
+  initial?: GenerationResumeSnapshot,
+): GenerationResumeSnapshot {
+  let snapshot = initial
+  for (const chunk of chunks) {
+    snapshot = updateGenerationResumeSnapshot(snapshot, chunk)
+  }
+  if (!snapshot) {
+    throw new Error('Expected at least one generation event')
+  }
+  return snapshot
+}
+
+describe('generation resume state reducer', () => {
+  it('tracks thread and run from persisted generation events', () => {
+    const snapshot = reduceChunks([
+      {
+        type: EventType.RUN_STARTED,
+        threadId: 'thread-1',
+        runId: 'run-1',
+        timestamp: 1,
+      },
+      {
+        type: EventType.CUSTOM,
+        name: GENERATION_EVENTS.PROGRESS,
+        value: { progress: 50, message: 'Halfway' },
+        threadId: 'thread-1',
+        runId: 'run-1',
+        timestamp: 2,
+      },
+    ])
+
+    expect(snapshot).toMatchObject({
+      resumeState: {
+        threadId: 'thread-1',
+        runId: 'run-1',
+      },
+      status: 'running',
+      lastEvent: {
+        type: EventType.CUSTOM,
+        name: GENERATION_EVENTS.PROGRESS,
+      },
+    })
+  })
+
+  it('stores generation artifacts as persisted refs only', () => {
+    const snapshot = reduceChunks([
+      {
+        type: EventType.CUSTOM,
+        name: GENERATION_EVENTS.ARTIFACTS,
+        value: [
+          artifactRef,
+          {
+            b64Json: 'raw-media-bytes',
+            url: 'data:image/png;base64,raw-media-bytes',
+          },
+        ],
+        threadId: 'thread-1',
+        runId: 'run-1',
+        timestamp: 1,
+      },
+    ])
+
+    expect(snapshot.pendingArtifacts).toEqual([artifactRef])
+    expect(JSON.stringify(snapshot)).not.toContain('raw-media-bytes')
+    expect(snapshot.activity).toBe('image')
+  })
+
+  it('sanitizes artifact refs before storing them in resume snapshots', () => {
+    const unsafeArtifactRef = {
+      ...artifactRef,
+      externalUrl: 'data:image/png;base64,raw-artifact-bytes',
+      b64Json: 'raw-artifact-bytes',
+      blob: new Blob(['raw-artifact-bytes']),
+      url: `https://example.com/${'x'.repeat(4096)}`,
+      source: {
+        ...artifactRef.source,
+        extraRawField: 'raw-artifact-bytes',
+      },
+    }
+
+    const snapshot = reduceChunks([
+      {
+        type: EventType.CUSTOM,
+        name: GENERATION_EVENTS.ARTIFACTS,
+        value: [unsafeArtifactRef],
+        threadId: 'thread-1',
+        runId: 'run-1',
+        timestamp: 1,
+      },
+      {
+        type: EventType.CUSTOM,
+        name: GENERATION_EVENTS.RESULT,
+        value: {
+          id: 'result-1',
+          artifacts: [unsafeArtifactRef],
+        },
+        threadId: 'thread-1',
+        runId: 'run-1',
+        timestamp: 2,
+      },
+    ])
+
+    expect(snapshot.pendingArtifacts).toEqual([artifactRef])
+    expect(snapshot.result?.artifacts).toEqual([artifactRef])
+    expect(JSON.stringify(snapshot)).not.toContain('raw-artifact-bytes')
+    expect(JSON.stringify(snapshot)).not.toContain('b64Json')
+    expect(JSON.stringify(snapshot)).not.toContain('extraRawField')
+  })
+
+  it('stores terminal result metadata without raw generated bytes', () => {
+    const snapshot = reduceChunks([
+      {
+        type: EventType.CUSTOM,
+        name: GENERATION_EVENTS.RESULT,
+        value: {
+          id: 'result-1',
+          model: 'image-model',
+          images: [
+            {
+              b64Json: 'raw-image-bytes',
+              url: 'data:image/png;base64,raw-image-bytes',
+              revisedPrompt: 'clean prompt',
+            },
+          ],
+          artifacts: [artifactRef],
+        },
+        threadId: 'thread-1',
+        runId: 'run-1',
+        timestamp: 2,
+      },
+      {
+        type: EventType.RUN_FINISHED,
+        threadId: 'thread-1',
+        runId: 'run-1',
+        finishReason: 'stop',
+        timestamp: 3,
+      },
+    ])
+
+    expect(snapshot.resumeState).toBeNull()
+    expect(snapshot.status).toBe('complete')
+    expect(snapshot.result).toMatchObject({
+      id: 'result-1',
+      model: 'image-model',
+      artifacts: [artifactRef],
+    })
+    expect(JSON.stringify(snapshot)).not.toContain('raw-image-bytes')
+    expect(JSON.stringify(snapshot)).not.toContain('b64Json')
+  })
+
+  it('omits non-durable and oversized result URLs from resume snapshots', () => {
+    const oversizedUrl = `https://example.com/${'x'.repeat(4096)}`
+    const unsafeUrls = [
+      'data:image/png;base64,raw-image-bytes',
+      'blob:https://example.com/raw-image-bytes',
+      oversizedUrl,
+    ]
+
+    for (const url of unsafeUrls) {
+      const snapshot = reduceChunks([
+        {
+          type: EventType.CUSTOM,
+          name: GENERATION_EVENTS.RESULT,
+          value: {
+            id: 'result-1',
+            model: 'image-model',
+            url,
+            artifacts: [artifactRef],
+          },
+          threadId: 'thread-1',
+          runId: 'run-1',
+          timestamp: 2,
+        },
+      ])
+
+      expect(snapshot.result).toMatchObject({
+        id: 'result-1',
+        model: 'image-model',
+        artifacts: [artifactRef],
+      })
+      expect(snapshot.result).not.toHaveProperty('url')
+      expect(JSON.stringify(snapshot)).not.toContain('raw-image-bytes')
+      expect(JSON.stringify(snapshot)).not.toContain(oversizedUrl)
+    }
+  })
+
+  it('clears resume state and stores lightweight error metadata on terminal errors', () => {
+    const snapshot = reduceChunks([
+      {
+        type: EventType.RUN_STARTED,
+        threadId: 'thread-1',
+        runId: 'run-1',
+        timestamp: 1,
+      },
+      {
+        type: EventType.RUN_ERROR,
+        threadId: 'thread-1',
+        runId: 'run-1',
+        message: 'Generation failed',
+        code: 'provider_error',
+        error: { message: 'legacy message' },
+        timestamp: 2,
+      },
+    ])
+
+    expect(snapshot).toMatchObject({
+      resumeState: null,
+      status: 'error',
+      error: {
+        message: 'Generation failed',
+        code: 'provider_error',
+      },
+    })
+  })
+
+  it('does not model explicit stop as durable cancel state', () => {
+    const snapshot = reduceChunks([
+      {
+        type: EventType.RUN_STARTED,
+        threadId: 'thread-1',
+        runId: 'run-1',
+        timestamp: 1,
+      },
+    ])
+
+    expect(snapshot.status).toBe('running')
+    expect(snapshot).not.toHaveProperty('cancelled')
+    expect(snapshot).not.toHaveProperty('cancelEndpoint')
+  })
+})
diff --git a/packages/ai-durable-stream/package.json b/packages/ai-durable-stream/package.json
new file mode 100644
index 000000000..c3337b5a6
--- /dev/null
+++ b/packages/ai-durable-stream/package.json
@@ -0,0 +1,50 @@
+{
+  "name": "@tanstack/ai-durable-stream",
+  "version": "0.1.0",
+  "description": "Delivery durability for TanStack AI over the durable-streams HTTP protocol — a resumable StreamDurability transport sink (append/read/resume) that stores zero delivery events itself.",
+  "author": "",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/TanStack/ai.git",
+    "directory": "packages/ai-durable-stream"
+  },
+  "keywords": [
+    "ai",
+    "tanstack",
+    "durable-streams",
+    "delivery-durability",
+    "resumable",
+    "sse"
+  ],
+  "type": "module",
+  "module": "./dist/esm/index.js",
+  "types": "./dist/esm/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/esm/index.d.ts",
+      "import": "./dist/esm/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "src"
+  ],
+  "scripts": {
+    "build": "vite build",
+    "clean": "premove ./build ./dist",
+    "lint:fix": "eslint ./src --fix",
+    "test:build": "publint --strict",
+    "test:eslint": "eslint ./src",
+    "test:lib": "vitest",
+    "test:lib:dev": "pnpm test:lib --watch",
+    "test:types": "tsc"
+  },
+  "peerDependencies": {
+    "@tanstack/ai": "workspace:^"
+  },
+  "devDependencies": {
+    "@tanstack/ai": "workspace:*",
+    "@vitest/coverage-v8": "4.0.14"
+  }
+}
diff --git a/packages/ai-durable-stream/src/durable-stream.ts b/packages/ai-durable-stream/src/durable-stream.ts
new file mode 100644
index 000000000..c69db4c3e
--- /dev/null
+++ b/packages/ai-durable-stream/src/durable-stream.ts
@@ -0,0 +1,328 @@
+import { decodeOffset, encodeOffset } from '@tanstack/ai'
+import type { StreamChunk, StreamDurability } from '@tanstack/ai'
+
+/**
+ * Options for {@link durableStream}.
+ */
+export interface DurableStreamOptions {
+  /** Base URL of the durable-streams server (no trailing slash needed). */
+  server: string
+  /**
+   * Prefix for the stream name (`{prefix}/{runId}`). Defaults to `runs`, so a
+   * run lands at `runs/{runId}`.
+   */
+  streamPrefix?: string
+  /**
+   * `fetch` implementation to use. Defaults to the global `fetch`. Injectable
+   * for testing and for wiring a custom transport / auth layer.
+   */
+  fetch?: typeof globalThis.fetch
+}
+
+/** One parsed SSE event from a durable-streams read. */
+interface SseEvent {
+  id?: string
+  event?: string
+  data?: string
+}
+
+/** Read a byte `ReadableStream` as `\n`-delimited lines (blank lines included). */
+async function* readLines(
+  body: ReadableStream<Uint8Array>,
+): AsyncGenerator<string> {
+  const reader = body.getReader()
+  const decoder = new TextDecoder()
+  let buffer = ''
+  try {
+    for (;;) {
+      const { done, value } = await reader.read()
+      if (done) break
+      buffer += decoder.decode(value, { stream: true })
+      const parts = buffer.split('\n')
+      buffer = parts.pop() ?? ''
+      for (const raw of parts) {
+        yield raw.endsWith('\r') ? raw.slice(0, -1) : raw
+      }
+    }
+    if (buffer) {
+      yield buffer.endsWith('\r') ? buffer.slice(0, -1) : buffer
+    }
+  } finally {
+    reader.releaseLock()
+  }
+}
+
+/**
+ * Parse an SSE `ReadableStream` into discrete events. Events are separated by a
+ * blank line; `id:` / `event:` / `data:` fields are collected per event. `:`
+ * comment lines (proxy/CDN keepalives) are skipped. A final event not
+ * terminated by a trailing blank line is still flushed.
+ */
+async function* parseSseEvents(
+  body: ReadableStream<Uint8Array>,
+): AsyncGenerator<SseEvent> {
+  let current: SseEvent = {}
+  let hasField = false
+
+  for await (const line of readLines(body)) {
+    if (line === '') {
+      if (hasField) {
+        yield current
+        current = {}
+        hasField = false
+      }
+      continue
+    }
+    if (line.startsWith(':')) continue
+    const colon = line.indexOf(':')
+    const field = colon === -1 ? line : line.slice(0, colon)
+    let value = colon === -1 ? '' : line.slice(colon + 1)
+    if (value.startsWith(' ')) value = value.slice(1)
+    if (field === 'id') current.id = value
+    else if (field === 'event') current.event = value
+    else if (field === 'data') {
+      current.data =
+        current.data === undefined ? value : `${current.data}\n${value}`
+    }
+    hasField = true
+  }
+  if (hasField) yield current
+}
+
+/** Extract the seq token (`-1` / `now` / a number) from a `runId@seq` offset. */
+function offsetToken(offset: string): string {
+  return offset.includes('@')
+    ? offset.slice(offset.lastIndexOf('@') + 1)
+    : offset
+}
+
+/**
+ * Interpret a live-read `event: control` frame's `data`. A rollover frame
+ * carries `{ offset }` (resume the read from there across a live-window
+ * boundary); a close frame carries `{ closed: true }` (the server finalized the
+ * stream). Anything else — absent data, invalid JSON, or an object with neither
+ * signal — yields `{}`, which the caller treats as malformed.
+ */
+function parseControlFrame(data: string | undefined): {
+  offset?: string
+  closed?: boolean
+} {
+  if (data === undefined) return {}
+  let parsed: unknown
+  try {
+    parsed = JSON.parse(data)
+  } catch {
+    return {}
+  }
+  if (typeof parsed !== 'object' || parsed === null) return {}
+  const result: { offset?: string; closed?: boolean } = {}
+  const offset = (parsed as { offset?: unknown }).offset
+  if (typeof offset === 'string') result.offset = offset
+  const closed = (parsed as { closed?: unknown }).closed
+  if (closed === true) result.closed = true
+  return result
+}
+
+function safeSearchParam(request: Request, key: string): string | null {
+  try {
+    return new URL(request.url).searchParams.get(key)
+  } catch {
+    return null
+  }
+}
+
+/**
+ * A {@link StreamDurability} backed by the
+ * [durable-streams](https://durablestreams.com) HTTP protocol. We own **zero**
+ * delivery-event storage — the durable-streams server owns the bytes (its own
+ * WAL / group-commit), and this adapter is a thin append/read/resume shim.
+ *
+ * - `runId()` — fresh: minted; resume: parsed from `Last-Event-ID` / `?offset`.
+ * - stream name — `${streamPrefix ?? 'runs'}/${runId}`.
+ * - `append` — `PUT` the stream once (idempotent create), then `POST` each chunk
+ *   INDIVIDUALLY (sequential awaited POSTs preserve order); every chunk is tagged
+ *   with its OWN backend offset (from that POST's `Stream-Next-Offset`), so the
+ *   returned offset array is fully populated (one resume offset per chunk) and
+ *   exactly-once holds at any batch size. durable-streams is built for
+ *   high-throughput per-append writes with server-side group-commit, so
+ *   one-POST-per-chunk is the intended usage.
+ * - `read` — `GET ?offset=&live=sse`, parsing `data` events into `{ seq, chunk }`
+ *   and reconnecting across the CDN live-window boundary via the last offset. The
+ *   `id:` the server replays for chunk i equals the offset `append` tagged chunk
+ *   i with on the fresh pass — the invariant that makes resume exactly-once.
+ *
+ * @example
+ * ```ts
+ * import { toServerSentEventsResponse } from '@tanstack/ai'
+ * import { durableStream } from '@tanstack/ai-durable-stream'
+ *
+ * export async function POST(request: Request) {
+ *   const stream = chat({ adapter, model: 'gpt-5.5', messages })
+ *   return toServerSentEventsResponse(stream, {
+ *     durability: { adapter: durableStream(request, { server: process.env.DS_URL! }) },
+ *   })
+ * }
+ * ```
+ */
+export function durableStream(
+  request: Request,
+  options: DurableStreamOptions,
+): StreamDurability {
+  const fetchFn = options.fetch ?? globalThis.fetch
+  const prefix = options.streamPrefix ?? 'runs'
+  // Validate the server as an absolute URL at construction, so a malformed
+  // base fails loudly here rather than surfacing later as an opaque fetch
+  // error deep inside `append` / `read`.
+  try {
+    void new URL(options.server)
+  } catch {
+    throw new Error(
+      `durableStream: invalid server URL: ${JSON.stringify(options.server)}`,
+    )
+  }
+  const server = options.server.replace(/\/$/, '')
+
+  const resumeOffset =
+    request.headers.get('Last-Event-ID') ?? safeSearchParam(request, 'offset')
+
+  let cachedRunId: string | undefined
+  const runId = (): string => {
+    if (cachedRunId === undefined) {
+      if (resumeOffset && resumeOffset.includes('@')) {
+        cachedRunId = decodeOffset(resumeOffset).runId
+      } else {
+        cachedRunId = safeSearchParam(request, 'runId') ?? crypto.randomUUID()
+      }
+    }
+    return cachedRunId
+  }
+
+  const streamUrl = (): string =>
+    `${server}/streams/${encodeURIComponent(`${prefix}/${runId()}`)}`
+
+  let created = false
+  const ensureCreated = async (): Promise<void> => {
+    if (created) return
+    // Idempotent create. A repeat PUT (e.g. a second server instance for the
+    // same run) is a server-side no-op.
+    const res = await fetchFn(streamUrl(), { method: 'PUT' })
+    if (!res.ok) {
+      throw new Error(
+        `durableStream: failed to create stream (${res.status} ${res.statusText})`,
+      )
+    }
+    created = true
+  }
+
+  return {
+    resumeFrom: () => resumeOffset,
+    runId,
+    append: async (chunks, startSeq) => {
+      await ensureCreated()
+      // POST each chunk INDIVIDUALLY (sequential awaited POSTs preserve order)
+      // and capture EACH message's own backend offset from its response's
+      // `Stream-Next-Offset`. This yields a fully-populated per-chunk offset
+      // array — every chunk carries a backend-addressable resume id — so a
+      // mid-batch reconnect resumes at the exact chunk it dropped on and
+      // exactly-once holds at ANY batch size (the transport `batch` option only
+      // controls how many chunks are handed to one `append` call; we POST them
+      // one-by-one internally). The tagged offset MUST equal the `id:` the
+      // server will emit for that same chunk on a GET replay, so the fresh path
+      // and the resume path share one key space.
+      const id = runId()
+      const offsets: Array<string> = []
+      for (let i = 0; i < chunks.length; i++) {
+        const res = await fetchFn(streamUrl(), {
+          method: 'POST',
+          headers: { 'Content-Type': 'application/json' },
+          body: JSON.stringify([chunks[i]]),
+        })
+        if (!res.ok) {
+          throw new Error(
+            `durableStream: failed to append (${res.status} ${res.statusText})`,
+          )
+        }
+        const next = res.headers.get('Stream-Next-Offset')
+        const seq =
+          next !== null && Number.isFinite(Number(next))
+            ? Number(next)
+            : startSeq + i
+        offsets.push(encodeOffset(id, seq))
+      }
+      return offsets
+    },
+    read: async function* (offset, signal) {
+      let cursor = offsetToken(offset)
+      // Reconnect loop: the CDN live window closes the SSE response
+      // periodically (~60s); resume from the last delivered offset.
+      reconnect: for (;;) {
+        if (signal?.aborted) return
+        const url = `${streamUrl()}?offset=${encodeURIComponent(
+          cursor,
+        )}&live=sse`
+        const res = await fetchFn(url, { method: 'GET', signal })
+        if (!res.ok) {
+          throw new Error(
+            `durableStream: failed to read (${res.status} ${res.statusText})`,
+          )
+        }
+        if (!res.body) {
+          throw new Error('durableStream: read response had no body')
+        }
+        // A read ends legitimately only when it saw the run's terminal event
+        // or the server flagged the stream closed (`Stream-Closed` header /
+        // a `{ closed: true }` control frame). A bare EOF without either means
+        // the live window was cut mid-run — surface it rather than silently
+        // truncating a still-in-flight read.
+        const streamClosed = res.headers.get('Stream-Closed') === 'true'
+        let genuineEnd = streamClosed
+        for await (const evt of parseSseEvents(res.body)) {
+          if (evt.event === 'control') {
+            const parsed = parseControlFrame(evt.data)
+            if (parsed.offset !== undefined) {
+              cursor = parsed.offset
+              continue reconnect
+            }
+            if (parsed.closed) {
+              genuineEnd = true
+              continue
+            }
+            // A control frame we cannot act on (unparseable, or neither a
+            // rollover offset nor a close signal) — surface rather than
+            // silently ending the read.
+            throw new Error(
+              'durableStream: malformed control frame (no offset or close signal) in read stream',
+            )
+          }
+          if (evt.data === undefined) continue
+          const chunk = JSON.parse(evt.data) as StreamChunk
+          // Every data event MUST carry a numeric offset id; a missing /
+          // non-numeric id would yield a `NaN` seq that corrupts the resume
+          // cursor, so reject the frame instead.
+          if (evt.id === undefined) {
+            throw new Error(
+              'durableStream: read event missing id (cannot derive resume offset)',
+            )
+          }
+          const seq = Number(evt.id)
+          if (!Number.isFinite(seq)) {
+            throw new Error(
+              `durableStream: read event has non-numeric id: ${JSON.stringify(
+                evt.id,
+              )}`,
+            )
+          }
+          cursor = evt.id
+          if (chunk.type === 'RUN_FINISHED' || chunk.type === 'RUN_ERROR') {
+            genuineEnd = true
+          }
+          yield { seq, chunk }
+        }
+        if (genuineEnd) return
+        throw new Error(
+          'durableStream: read stream ended without a terminal event or close signal — connection was likely cut short.',
+        )
+      }
+    },
+  }
+}
diff --git a/packages/ai-durable-stream/src/index.ts b/packages/ai-durable-stream/src/index.ts
new file mode 100644
index 000000000..74bb8d4ad
--- /dev/null
+++ b/packages/ai-durable-stream/src/index.ts
@@ -0,0 +1,6 @@
+/**
+ * `@tanstack/ai-durable-stream` — a {@link StreamDurability} backend over the
+ * durable-streams HTTP protocol, for production-grade delivery durability.
+ */
+export { durableStream } from './durable-stream'
+export type { DurableStreamOptions } from './durable-stream'
diff --git a/packages/ai-durable-stream/tests/durable-stream.test.ts b/packages/ai-durable-stream/tests/durable-stream.test.ts
new file mode 100644
index 000000000..4a7b956f5
--- /dev/null
+++ b/packages/ai-durable-stream/tests/durable-stream.test.ts
@@ -0,0 +1,532 @@
+import { describe, expect, it, vi } from 'vitest'
+import { encodeOffset, toServerSentEventsResponse } from '@tanstack/ai'
+import { durableStream } from '../src'
+import type { StreamChunk } from '@tanstack/ai'
+
+function textChunk(delta: string): StreamChunk {
+  return { type: 'TEXT_MESSAGE_CONTENT', delta, timestamp: 0 } as StreamChunk
+}
+
+async function readBody(res: Response): Promise<string> {
+  const reader = res.body!.getReader()
+  const decoder = new TextDecoder()
+  let out = ''
+  for (;;) {
+    const { done, value } = await reader.read()
+    if (done) break
+    out += decoder.decode(value)
+  }
+  return out
+}
+
+function parseSseEvents(body: string): Array<{ id?: string; data: string }> {
+  return body
+    .split('\n\n')
+    .filter((block) => block.trim().length > 0)
+    .map((block) => {
+      const lines = block.split('\n')
+      const idLine = lines.find((l) => l.startsWith('id: '))
+      const dataLine = lines.find((l) => l.startsWith('data: '))
+      return {
+        ...(idLine ? { id: idLine.slice('id: '.length) } : {}),
+        data: dataLine ? dataLine.slice('data: '.length) : '',
+      }
+    })
+}
+
+/**
+ * A fake DS server that assigns NON-1-based, non-contiguous offsets (1000,
+ * 1007, 1014, …) so a test can prove the client-facing ids are the BACKEND's
+ * offsets rather than a transport-local 1-based counter.
+ */
+function makeNon1BasedDsServer() {
+  const entries: Array<{ offset: number; data: string }> = []
+  let nextOffset = 1000
+  const fetchStub = vi.fn(
+    async (input: string | URL | Request, init?: RequestInit) => {
+      const url = new URL(typeof input === 'string' ? input : input.toString())
+      const method = (init?.method ?? 'GET').toUpperCase()
+      if (method === 'PUT') return new Response(null, { status: 201 })
+      if (method === 'POST') {
+        const body = JSON.parse(String(init?.body)) as Array<unknown>
+        let last = nextOffset
+        for (const c of body) {
+          last = nextOffset
+          entries.push({ offset: nextOffset, data: JSON.stringify(c) })
+          nextOffset += 7
+        }
+        return new Response(null, {
+          status: 200,
+          headers: { 'Stream-Next-Offset': String(last) },
+        })
+      }
+      // GET (read strictly after ?offset)
+      const offsetParam = url.searchParams.get('offset') ?? '-1'
+      const from =
+        offsetParam === '-1' || offsetParam === ''
+          ? Number.NEGATIVE_INFINITY
+          : Number(offsetParam)
+      let sse = ''
+      for (const e of entries) {
+        if (e.offset > from) sse += `id: ${e.offset}\ndata: ${e.data}\n\n`
+      }
+      return new Response(sse, {
+        status: 200,
+        headers: {
+          'Content-Type': 'text/event-stream',
+          'Stream-Closed': 'true',
+        },
+      })
+    },
+  )
+  return { fetchStub, entries }
+}
+
+/**
+ * An in-memory fake of the durable-streams HTTP protocol:
+ * - PUT  /streams/{name}         create (idempotent)
+ * - POST /streams/{name}         append JSON array; sets `Stream-Next-Offset`
+ * - GET  /streams/{name}?offset= read SSE from strictly after `offset`
+ */
+function makeFakeDsServer() {
+  const streams = new Map<string, Array<string>>()
+  const puts: Array<{ name: string; created: boolean }> = []
+
+  const fetchStub = vi.fn(
+    async (input: string | URL | Request, init?: RequestInit) => {
+      const url = new URL(typeof input === 'string' ? input : input.toString())
+      const method = (init?.method ?? 'GET').toUpperCase()
+      const name = decodeURIComponent(url.pathname.replace(/^\/streams\//, ''))
+
+      if (method === 'PUT') {
+        const created = !streams.has(name)
+        if (created) streams.set(name, [])
+        puts.push({ name, created })
+        return new Response(null, { status: created ? 201 : 200 })
+      }
+
+      if (method === 'POST') {
+        const body = JSON.parse(String(init?.body)) as Array<unknown>
+        const arr = streams.get(name) ?? []
+        if (!streams.has(name)) streams.set(name, arr)
+        for (const c of body) arr.push(JSON.stringify(c))
+        return new Response(null, {
+          status: 200,
+          headers: { 'Stream-Next-Offset': String(arr.length) },
+        })
+      }
+
+      // GET (read)
+      const arr = streams.get(name) ?? []
+      const offsetParam = url.searchParams.get('offset') ?? '-1'
+      const from =
+        offsetParam === '-1' || offsetParam === ''
+          ? 0
+          : offsetParam === 'now'
+            ? arr.length
+            : Number(offsetParam)
+      let sse = ''
+      for (let i = from; i < arr.length; i++) {
+        const pos = i + 1
+        sse += `id: ${pos}\ndata: ${arr[i]}\n\n`
+      }
+      // This fake returns the finalized stored range then EOF, so flag the
+      // stream closed — a genuine end (not a cut-short live window).
+      return new Response(sse, {
+        status: 200,
+        headers: {
+          'Content-Type': 'text/event-stream',
+          'Stream-Closed': 'true',
+        },
+      })
+    },
+  )
+
+  return { fetchStub, streams, puts }
+}
+
+describe('durableStream', () => {
+  it('parses runId and stream identity from the request', () => {
+    const { fetchStub } = makeFakeDsServer()
+    const d = durableStream(
+      new Request('https://app.test/api/chat?runId=run-1', { method: 'POST' }),
+      { server: 'https://ds.test', fetch: fetchStub },
+    )
+    expect(d.resumeFrom()).toBeNull()
+    expect(d.runId()).toBe('run-1')
+  })
+
+  it('creates the stream once (PUT idempotent) and advances the offset on append', async () => {
+    const { fetchStub, puts } = makeFakeDsServer()
+    const d = durableStream(
+      new Request('https://app.test/api/chat?runId=run-2', { method: 'POST' }),
+      { server: 'https://ds.test', fetch: fetchStub },
+    )
+
+    // append POSTs each chunk INDIVIDUALLY and reads back its own backend
+    // offset, so EVERY chunk carries a resume offset (fully populated array,
+    // no `undefined`) — this is what makes a mid-batch reconnect exactly-once.
+    const first = await d.append(
+      [textChunk('a'), textChunk('b'), textChunk('c')],
+      1,
+    )
+    expect(first).toEqual([
+      encodeOffset('run-2', 1),
+      encodeOffset('run-2', 2),
+      encodeOffset('run-2', 3),
+    ])
+
+    const second = await d.append([textChunk('d'), textChunk('e')], 4)
+    expect(second).toEqual([encodeOffset('run-2', 4), encodeOffset('run-2', 5)])
+
+    // The stream is created exactly once, on the first append (PUT-once);
+    // per-chunk POSTs never re-PUT. The server-side PUT stays idempotent.
+    expect(puts).toHaveLength(1)
+    expect(puts[0]).toEqual({ name: 'runs/run-2', created: true })
+  })
+
+  it('reads the full stream from the start', async () => {
+    const { fetchStub } = makeFakeDsServer()
+    const d = durableStream(
+      new Request('https://app.test/api/chat?runId=run-3', { method: 'POST' }),
+      { server: 'https://ds.test', fetch: fetchStub },
+    )
+    await d.append([textChunk('a'), textChunk('b'), textChunk('c')], 1)
+
+    const read: Array<{ seq: number; delta: string }> = []
+    for await (const { seq, chunk } of d.read('-1')) {
+      read.push({ seq, delta: (chunk as { delta: string }).delta })
+    }
+    expect(read).toEqual([
+      { seq: 1, delta: 'a' },
+      { seq: 2, delta: 'b' },
+      { seq: 3, delta: 'c' },
+    ])
+  })
+
+  it('reads exactly the tail strictly after a resume offset', async () => {
+    const { fetchStub } = makeFakeDsServer()
+    // Produce under a known run.
+    const producer = durableStream(
+      new Request('https://app.test/api/chat?runId=run-4', { method: 'POST' }),
+      { server: 'https://ds.test', fetch: fetchStub },
+    )
+    await producer.append(
+      [textChunk('a'), textChunk('b'), textChunk('c'), textChunk('d')],
+      1,
+    )
+
+    // Reconnect carrying Last-Event-ID at seq 2.
+    const reconnect = durableStream(
+      new Request('https://app.test/api/chat', {
+        method: 'POST',
+        headers: { 'Last-Event-ID': encodeOffset('run-4', 2) },
+      }),
+      { server: 'https://ds.test', fetch: fetchStub },
+    )
+    expect(reconnect.resumeFrom()).toBe(encodeOffset('run-4', 2))
+    expect(reconnect.runId()).toBe('run-4')
+
+    const read: Array<{ seq: number; delta: string }> = []
+    for await (const { seq, chunk } of reconnect.read(
+      reconnect.resumeFrom()!,
+    )) {
+      read.push({ seq, delta: (chunk as { delta: string }).delta })
+    }
+    expect(read).toEqual([
+      { seq: 3, delta: 'c' },
+      { seq: 4, delta: 'd' },
+    ])
+  })
+
+  // Finding 7b: a malformed server URL is rejected at construction.
+  it('rejects a malformed server URL at construction', () => {
+    expect(() =>
+      durableStream(
+        new Request('https://app.test/api/chat', { method: 'POST' }),
+        { server: 'not a url' },
+      ),
+    ).toThrow(/invalid server URL/)
+  })
+
+  // Finding 7c: a read data event without a usable numeric id must throw rather
+  // than yield a `NaN` seq that would corrupt the resume cursor.
+  it('throws on a read data event missing its id', async () => {
+    const fetchStub = vi.fn(async (_input: unknown, init?: RequestInit) => {
+      const method = (init?.method ?? 'GET').toUpperCase()
+      if (method === 'PUT') return new Response(null, { status: 201 })
+      // A data event with no `id:` line.
+      return new Response(`data: ${JSON.stringify(textChunk('x'))}\n\n`, {
+        status: 200,
+        headers: { 'Content-Type': 'text/event-stream' },
+      })
+    })
+    const d = durableStream(
+      new Request('https://app.test/api/chat?runId=run-noid', {
+        method: 'POST',
+      }),
+      {
+        server: 'https://ds.test',
+        fetch: fetchStub as unknown as typeof fetch,
+      },
+    )
+    await expect(async () => {
+      for await (const _ of d.read('-1')) {
+        // drain
+      }
+    }).rejects.toThrow(/missing id/)
+  })
+
+  it('throws on a read data event with a non-numeric id', async () => {
+    const fetchStub = vi.fn(async (_input: unknown, init?: RequestInit) => {
+      const method = (init?.method ?? 'GET').toUpperCase()
+      if (method === 'PUT') return new Response(null, { status: 201 })
+      return new Response(
+        `id: abc\ndata: ${JSON.stringify(textChunk('x'))}\n\n`,
+        {
+          status: 200,
+          headers: { 'Content-Type': 'text/event-stream' },
+        },
+      )
+    })
+    const d = durableStream(
+      new Request('https://app.test/api/chat?runId=run-badid', {
+        method: 'POST',
+      }),
+      {
+        server: 'https://ds.test',
+        fetch: fetchStub as unknown as typeof fetch,
+      },
+    )
+    await expect(async () => {
+      for await (const _ of d.read('-1')) {
+        // drain
+      }
+    }).rejects.toThrow(/non-numeric id/)
+  })
+
+  // Finding 5: a read that ends without a terminal / close signal (a cut-short
+  // live window) must surface rather than silently truncating.
+  it('surfaces a bare-EOF end of a still-in-flight read', async () => {
+    const fetchStub = vi.fn(async (_input: unknown, init?: RequestInit) => {
+      const method = (init?.method ?? 'GET').toUpperCase()
+      if (method === 'PUT') return new Response(null, { status: 201 })
+      // Two data events, then EOF — no terminal chunk, no Stream-Closed header,
+      // no rollover control frame.
+      return new Response(
+        `id: 1\ndata: ${JSON.stringify(textChunk('a'))}\n\n` +
+          `id: 2\ndata: ${JSON.stringify(textChunk('b'))}\n\n`,
+        { status: 200, headers: { 'Content-Type': 'text/event-stream' } },
+      )
+    })
+    const d = durableStream(
+      new Request('https://app.test/api/chat?runId=run-trunc', {
+        method: 'POST',
+      }),
+      {
+        server: 'https://ds.test',
+        fetch: fetchStub as unknown as typeof fetch,
+      },
+    )
+    const seen: Array<string> = []
+    await expect(async () => {
+      for await (const { chunk } of d.read('-1')) {
+        seen.push((chunk as { delta: string }).delta)
+      }
+    }).rejects.toThrow(/ended without a terminal event or close signal/)
+    // It still delivered what it saw before surfacing the truncation.
+    expect(seen).toEqual(['a', 'b'])
+  })
+
+  it('surfaces a malformed control frame instead of silently ending', async () => {
+    const fetchStub = vi.fn(async (_input: unknown, init?: RequestInit) => {
+      const method = (init?.method ?? 'GET').toUpperCase()
+      if (method === 'PUT') return new Response(null, { status: 201 })
+      // A control frame with unparseable data (neither a rollover offset nor a
+      // close signal).
+      return new Response(`event: control\ndata: not-json\n\n`, {
+        status: 200,
+        headers: { 'Content-Type': 'text/event-stream' },
+      })
+    })
+    const d = durableStream(
+      new Request('https://app.test/api/chat?runId=run-ctrl', {
+        method: 'POST',
+      }),
+      {
+        server: 'https://ds.test',
+        fetch: fetchStub as unknown as typeof fetch,
+      },
+    )
+    await expect(async () => {
+      for await (const _ of d.read('-1')) {
+        // drain
+      }
+    }).rejects.toThrow(/malformed control frame/)
+  })
+})
+
+// Finding 1: the client-facing SSE ids on a FRESH run must be the offsets the
+// backend actually assigns (here, non-1-based 1000/1007/1014…), and a reconnect
+// carrying one of those backend offsets must resume correctly.
+describe('durableStream + toServerSentEventsResponse (backend-offset ids)', () => {
+  function textStream(deltas: Array<string>): AsyncIterable<StreamChunk> {
+    return {
+      async *[Symbol.asyncIterator]() {
+        for (const d of deltas) yield textChunk(d)
+      },
+    }
+  }
+
+  async function sseIds(res: Response): Promise<Array<string | undefined>> {
+    return parseSseEvents(await readBody(res)).map((e) => e.id)
+  }
+
+  it('tags fresh-run events with the backend offsets (not a 1-based counter)', async () => {
+    const { fetchStub } = makeNon1BasedDsServer()
+    const durability = durableStream(
+      new Request('https://app.test/api/chat?runId=run-x', { method: 'POST' }),
+      { server: 'https://ds.test', fetch: fetchStub },
+    )
+    // batch:1 so every chunk flushes as its own append and carries a backend id.
+    const res = toServerSentEventsResponse(textStream(['1', '2', '3']), {
+      durability: { adapter: durability, batch: 1 },
+    })
+    expect(await sseIds(res)).toEqual([
+      encodeOffset('run-x', 1000),
+      encodeOffset('run-x', 1007),
+      encodeOffset('run-x', 1014),
+    ])
+  })
+
+  it('resumes from a backend offset carried in Last-Event-ID', async () => {
+    const { fetchStub } = makeNon1BasedDsServer()
+    // Produce the full run first.
+    await readBody(
+      toServerSentEventsResponse(textStream(['1', '2', '3']), {
+        durability: {
+          adapter: durableStream(
+            new Request('https://app.test/api/chat?runId=run-x', {
+              method: 'POST',
+            }),
+            { server: 'https://ds.test', fetch: fetchStub },
+          ),
+          batch: 1,
+        },
+      }),
+    )
+
+    // Reconnect at the backend offset 1007; the input stream must NOT be
+    // iterated on resume.
+    const exploding: AsyncIterable<StreamChunk> = {
+      [Symbol.asyncIterator]() {
+        return {
+          next() {
+            throw new Error('input stream must not be iterated on resume')
+          },
+        }
+      },
+    }
+    const reconnect = durableStream(
+      new Request('https://app.test/api/chat', {
+        method: 'POST',
+        headers: { 'Last-Event-ID': encodeOffset('run-x', 1007) },
+      }),
+      { server: 'https://ds.test', fetch: fetchStub },
+    )
+    const res = toServerSentEventsResponse(exploding, {
+      durability: { adapter: reconnect },
+    })
+    const events = parseSseEvents(await readBody(res))
+    expect(events.map((e) => e.id)).toEqual([encodeOffset('run-x', 1014)])
+    expect(events.map((e) => JSON.parse(e.data).delta)).toEqual(['3'])
+  })
+})
+
+// Finding 1 (exactly-once): with the DEFAULT batch (>1), an entire short run is
+// one `append` call. Per-chunk POSTing tags EVERY chunk with its own backend
+// offset, so a mid-batch drop (including a drop within the very first batch)
+// resumes at the exact chunk it dropped on — each chunk is delivered exactly
+// once, no dup and no skip. The old per-batch tagging left every non-last chunk
+// id-less, so this fails against it (and it must NOT be weakened to batch:1).
+describe('durableStream — exactly-once across a mid-batch reconnect', () => {
+  function textStream(deltas: Array<string>): AsyncIterable<StreamChunk> {
+    return {
+      async *[Symbol.asyncIterator]() {
+        for (const d of deltas) yield textChunk(d)
+      },
+    }
+  }
+
+  it('delivers each chunk exactly once when the socket drops mid-first-batch', async () => {
+    const { fetchStub } = makeNon1BasedDsServer()
+    const full = ['a', 'b', 'c', 'd', 'e', 'f']
+
+    // Produce the whole run with the DEFAULT batch (no `batch` option). All 6
+    // chunks (< 32) buffer into a single `append`; the fix POSTs them one-by-one
+    // so each gets its own backend offset (1000, 1007, 1014, …).
+    const produced = parseSseEvents(
+      await readBody(
+        toServerSentEventsResponse(textStream(full), {
+          durability: {
+            adapter: durableStream(
+              new Request('https://app.test/api/chat?runId=run-eo', {
+                method: 'POST',
+              }),
+              { server: 'https://ds.test', fetch: fetchStub },
+            ),
+          },
+        }),
+      ),
+    )
+
+    // Core of the fix: EVERY chunk in the batch carries a resume id. Under the
+    // old per-batch tagging only the last chunk did (the rest were id-less), so
+    // this assertion fails against the pre-fix code.
+    expect(produced).toHaveLength(6)
+    expect(produced.every((e) => e.id !== undefined)).toBe(true)
+    expect(produced.map((e) => JSON.parse(e.data).delta)).toEqual(full)
+
+    // Simulate a socket drop MID-BATCH after receiving only the first 2 chunks
+    // (well within the single 6-chunk first batch). The client's last-seen id is
+    // the 2nd chunk's backend offset — defined only because of per-chunk tagging.
+    const beforeDrop = produced.slice(0, 2)
+    const lastSeenId = beforeDrop.at(-1)?.id
+    expect(lastSeenId).toBeDefined()
+
+    // Reconnect carrying that id as Last-Event-ID; the input stream must NOT be
+    // re-iterated on resume (replay reads only from the backend).
+    const exploding: AsyncIterable<StreamChunk> = {
+      [Symbol.asyncIterator]() {
+        return {
+          next() {
+            throw new Error('input stream must not be iterated on resume')
+          },
+        }
+      },
+    }
+    const afterDrop = parseSseEvents(
+      await readBody(
+        toServerSentEventsResponse(exploding, {
+          durability: {
+            adapter: durableStream(
+              new Request('https://app.test/api/chat', {
+                method: 'POST',
+                headers: { 'Last-Event-ID': lastSeenId! },
+              }),
+              { server: 'https://ds.test', fetch: fetchStub },
+            ),
+          },
+        }),
+      ),
+    )
+
+    // What the joiner actually saw = pre-drop prefix + post-reconnect tail. The
+    // backend replays strictly AFTER the offset, so there is no overlap: each
+    // chunk appears exactly once, in order, with none skipped.
+    const received = [...beforeDrop, ...afterDrop].map(
+      (e) => JSON.parse(e.data).delta as string,
+    )
+    expect(received).toEqual(full)
+  })
+})
diff --git a/packages/ai-durable-stream/tsconfig.json b/packages/ai-durable-stream/tsconfig.json
new file mode 100644
index 000000000..c38689f4e
--- /dev/null
+++ b/packages/ai-durable-stream/tsconfig.json
@@ -0,0 +1,8 @@
+{
+  "extends": "../../tsconfig.base.json",
+  "compilerOptions": {
+    "outDir": "dist"
+  },
+  "include": ["src", "tests"],
+  "exclude": ["node_modules", "dist"]
+}
diff --git a/packages/ai-durable-stream/vite.config.ts b/packages/ai-durable-stream/vite.config.ts
new file mode 100644
index 000000000..11f5b20b7
--- /dev/null
+++ b/packages/ai-durable-stream/vite.config.ts
@@ -0,0 +1,37 @@
+import { defineConfig, mergeConfig } from 'vitest/config'
+import { tanstackViteConfig } from '@tanstack/vite-config'
+import packageJson from './package.json'
+
+const config = defineConfig({
+  test: {
+    name: packageJson.name,
+    dir: './',
+    watch: false,
+
+    globals: true,
+    environment: 'node',
+    include: ['tests/**/*.test.ts'],
+    coverage: {
+      provider: 'v8',
+      reporter: ['text', 'json', 'html', 'lcov'],
+      exclude: [
+        'node_modules/',
+        'dist/',
+        'tests/',
+        '**/*.test.ts',
+        '**/*.config.ts',
+        '**/types.ts',
+      ],
+      include: ['src/**/*.ts'],
+    },
+  },
+})
+
+export default mergeConfig(
+  config,
+  tanstackViteConfig({
+    entry: ['./src/index.ts'],
+    srcDir: './src',
+    cjs: false,
+  }),
+)
diff --git a/packages/ai-event-client/src/index.ts b/packages/ai-event-client/src/index.ts
index 0bd1fdc12..310a6d8e0 100644
--- a/packages/ai-event-client/src/index.ts
+++ b/packages/ai-event-client/src/index.ts
@@ -614,6 +614,9 @@ export interface SummarizeUsageEvent extends BaseEventContext {
 /** Emitted when an image request starts. */
 export interface ImageRequestStartedEvent extends BaseEventContext {
   requestId: string
+  threadId?: string
+  runId?: string
+  cursor?: string
   provider: string
   model: string
   prompt: string
@@ -630,6 +633,9 @@ export interface ImageRequestStartedEvent extends BaseEventContext {
 /** Emitted when an image request completes. */
 export interface ImageRequestCompletedEvent extends BaseEventContext {
   requestId: string
+  threadId?: string
+  runId?: string
+  cursor?: string
   provider: string
   model: string
   images: Array<{ url?: string; b64Json?: string }>
@@ -639,6 +645,9 @@ export interface ImageRequestCompletedEvent extends BaseEventContext {
 /** Emitted when image usage metrics are available. */
 export interface ImageUsageEvent extends BaseEventContext {
   requestId: string
+  threadId?: string
+  runId?: string
+  cursor?: string
   model: string
   usage: TokenUsage
 }
@@ -650,6 +659,9 @@ export interface ImageUsageEvent extends BaseEventContext {
 /** Emitted when a speech request starts. */
 export interface SpeechRequestStartedEvent extends BaseEventContext {
   requestId: string
+  threadId?: string
+  runId?: string
+  cursor?: string
   provider: string
   model: string
   text: string
@@ -661,6 +673,9 @@ export interface SpeechRequestStartedEvent extends BaseEventContext {
 /** Emitted when a speech request completes. */
 export interface SpeechRequestCompletedEvent extends BaseEventContext {
   requestId: string
+  threadId?: string
+  runId?: string
+  cursor?: string
   provider: string
   model: string
   audio: string
@@ -673,6 +688,9 @@ export interface SpeechRequestCompletedEvent extends BaseEventContext {
 /** Emitted when speech usage metrics are available. */
 export interface SpeechUsageEvent extends BaseEventContext {
   requestId: string
+  threadId?: string
+  runId?: string
+  cursor?: string
   model: string
   usage: TokenUsage
 }
@@ -684,6 +702,9 @@ export interface SpeechUsageEvent extends BaseEventContext {
 /** Emitted when a transcription request starts. */
 export interface TranscriptionRequestStartedEvent extends BaseEventContext {
   requestId: string
+  threadId?: string
+  runId?: string
+  cursor?: string
   provider: string
   model: string
   language?: string
@@ -694,6 +715,9 @@ export interface TranscriptionRequestStartedEvent extends BaseEventContext {
 /** Emitted when a transcription request completes. */
 export interface TranscriptionRequestCompletedEvent extends BaseEventContext {
   requestId: string
+  threadId?: string
+  runId?: string
+  cursor?: string
   provider: string
   model: string
   text: string
@@ -704,6 +728,9 @@ export interface TranscriptionRequestCompletedEvent extends BaseEventContext {
 /** Emitted when transcription usage metrics are available. */
 export interface TranscriptionUsageEvent extends BaseEventContext {
   requestId: string
+  threadId?: string
+  runId?: string
+  cursor?: string
   model: string
   usage: TokenUsage
 }
@@ -715,6 +742,9 @@ export interface TranscriptionUsageEvent extends BaseEventContext {
 /** Emitted when an audio generation request starts. */
 export interface AudioRequestStartedEvent extends BaseEventContext {
   requestId: string
+  threadId?: string
+  runId?: string
+  cursor?: string
   provider: string
   model: string
   prompt: string
@@ -743,6 +773,9 @@ export type AudioRequestCompletedAudio =
 /** Emitted when an audio generation request completes. */
 export interface AudioRequestCompletedEvent extends BaseEventContext {
   requestId: string
+  threadId?: string
+  runId?: string
+  cursor?: string
   provider: string
   model: string
   audio: AudioRequestCompletedAudio
@@ -752,6 +785,9 @@ export interface AudioRequestCompletedEvent extends BaseEventContext {
 /** Emitted when an audio generation request fails. */
 export interface AudioRequestErrorEvent extends BaseEventContext {
   requestId: string
+  threadId?: string
+  runId?: string
+  cursor?: string
   provider: string
   model: string
   error: { message: string; name?: string }
@@ -761,6 +797,9 @@ export interface AudioRequestErrorEvent extends BaseEventContext {
 /** Emitted when a speech generation request fails. */
 export interface SpeechRequestErrorEvent extends BaseEventContext {
   requestId: string
+  threadId?: string
+  runId?: string
+  cursor?: string
   provider: string
   model: string
   error: { message: string; name?: string }
@@ -770,6 +809,9 @@ export interface SpeechRequestErrorEvent extends BaseEventContext {
 /** Emitted when a transcription request fails. */
 export interface TranscriptionRequestErrorEvent extends BaseEventContext {
   requestId: string
+  threadId?: string
+  runId?: string
+  cursor?: string
   provider: string
   model: string
   error: { message: string; name?: string }
@@ -779,6 +821,9 @@ export interface TranscriptionRequestErrorEvent extends BaseEventContext {
 /** Emitted when audio usage metrics are available. */
 export interface AudioUsageEvent extends BaseEventContext {
   requestId: string
+  threadId?: string
+  runId?: string
+  cursor?: string
   model: string
   usage: TokenUsage
 }
@@ -790,6 +835,9 @@ export interface AudioUsageEvent extends BaseEventContext {
 /** Emitted when a video request starts. */
 export interface VideoRequestStartedEvent extends BaseEventContext {
   requestId: string
+  threadId?: string
+  runId?: string
+  cursor?: string
   provider: string
   model: string
   requestType: 'create' | 'status' | 'url'
@@ -802,6 +850,9 @@ export interface VideoRequestStartedEvent extends BaseEventContext {
 /** Emitted when a video request completes. */
 export interface VideoRequestCompletedEvent extends BaseEventContext {
   requestId: string
+  threadId?: string
+  runId?: string
+  cursor?: string
   provider: string
   model: string
   requestType: 'create' | 'status' | 'url'
@@ -816,6 +867,9 @@ export interface VideoRequestCompletedEvent extends BaseEventContext {
 /** Emitted when video usage metrics are available. */
 export interface VideoUsageEvent extends BaseEventContext {
   requestId: string
+  threadId?: string
+  runId?: string
+  cursor?: string
   model: string
   usage: TokenUsage
 }
diff --git a/packages/ai-persistence-drizzle/drizzle.config.ts b/packages/ai-persistence-drizzle/drizzle.config.ts
new file mode 100644
index 000000000..f9d243c25
--- /dev/null
+++ b/packages/ai-persistence-drizzle/drizzle.config.ts
@@ -0,0 +1,14 @@
+import { defineConfig } from 'drizzle-kit'
+
+/**
+ * drizzle-kit config for the batteries-included sqlite backend. Migrations are
+ * generated from `src/schema.ts` into `drizzle/` and shipped with the package
+ * (see the `files` field); `sqlPersistence({ migrate: true })` applies them.
+ *
+ * Regenerate with `pnpm db:generate` after any schema change.
+ */
+export default defineConfig({
+  dialect: 'sqlite',
+  schema: './src/schema.ts',
+  out: './drizzle',
+})
diff --git a/packages/ai-persistence-drizzle/drizzle/0000_cute_vision.sql b/packages/ai-persistence-drizzle/drizzle/0000_cute_vision.sql
new file mode 100644
index 000000000..76e81e8fd
--- /dev/null
+++ b/packages/ai-persistence-drizzle/drizzle/0000_cute_vision.sql
@@ -0,0 +1,54 @@
+CREATE TABLE `artifacts` (
+	`artifact_id` text PRIMARY KEY NOT NULL,
+	`run_id` text NOT NULL,
+	`thread_id` text NOT NULL,
+	`name` text NOT NULL,
+	`mime_type` text NOT NULL,
+	`size` integer NOT NULL,
+	`external_url` text,
+	`created_at` integer NOT NULL
+);
+--> statement-breakpoint
+CREATE TABLE `blobs` (
+	`key` text PRIMARY KEY NOT NULL,
+	`content_type` text,
+	`size` integer,
+	`etag` text,
+	`custom_metadata_json` text,
+	`created_at` integer,
+	`updated_at` integer,
+	`body` blob
+);
+--> statement-breakpoint
+CREATE TABLE `interrupts` (
+	`interrupt_id` text PRIMARY KEY NOT NULL,
+	`run_id` text NOT NULL,
+	`thread_id` text NOT NULL,
+	`status` text NOT NULL,
+	`requested_at` integer NOT NULL,
+	`resolved_at` integer,
+	`payload_json` text NOT NULL,
+	`response_json` text
+);
+--> statement-breakpoint
+CREATE TABLE `messages` (
+	`thread_id` text PRIMARY KEY NOT NULL,
+	`messages_json` text NOT NULL
+);
+--> statement-breakpoint
+CREATE TABLE `metadata` (
+	`scope` text NOT NULL,
+	`key` text NOT NULL,
+	`value_json` text NOT NULL,
+	PRIMARY KEY(`scope`, `key`)
+);
+--> statement-breakpoint
+CREATE TABLE `runs` (
+	`run_id` text PRIMARY KEY NOT NULL,
+	`thread_id` text NOT NULL,
+	`status` text NOT NULL,
+	`started_at` integer NOT NULL,
+	`finished_at` integer,
+	`error` text,
+	`usage_json` text
+);
diff --git a/packages/ai-persistence-drizzle/drizzle/meta/0000_snapshot.json b/packages/ai-persistence-drizzle/drizzle/meta/0000_snapshot.json
new file mode 100644
index 000000000..ff5e60c63
--- /dev/null
+++ b/packages/ai-persistence-drizzle/drizzle/meta/0000_snapshot.json
@@ -0,0 +1,335 @@
+{
+  "version": "6",
+  "dialect": "sqlite",
+  "id": "5e224922-d0ca-4cac-bf7b-5813ad6f6d5d",
+  "prevId": "00000000-0000-0000-0000-000000000000",
+  "tables": {
+    "artifacts": {
+      "name": "artifacts",
+      "columns": {
+        "artifact_id": {
+          "name": "artifact_id",
+          "type": "text",
+          "primaryKey": true,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "run_id": {
+          "name": "run_id",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "thread_id": {
+          "name": "thread_id",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "name": {
+          "name": "name",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "mime_type": {
+          "name": "mime_type",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "size": {
+          "name": "size",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "external_url": {
+          "name": "external_url",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false,
+          "autoincrement": false
+        },
+        "created_at": {
+          "name": "created_at",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        }
+      },
+      "indexes": {},
+      "foreignKeys": {},
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {},
+      "checkConstraints": {}
+    },
+    "blobs": {
+      "name": "blobs",
+      "columns": {
+        "key": {
+          "name": "key",
+          "type": "text",
+          "primaryKey": true,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "content_type": {
+          "name": "content_type",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false,
+          "autoincrement": false
+        },
+        "size": {
+          "name": "size",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": false,
+          "autoincrement": false
+        },
+        "etag": {
+          "name": "etag",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false,
+          "autoincrement": false
+        },
+        "custom_metadata_json": {
+          "name": "custom_metadata_json",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false,
+          "autoincrement": false
+        },
+        "created_at": {
+          "name": "created_at",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": false,
+          "autoincrement": false
+        },
+        "updated_at": {
+          "name": "updated_at",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": false,
+          "autoincrement": false
+        },
+        "body": {
+          "name": "body",
+          "type": "blob",
+          "primaryKey": false,
+          "notNull": false,
+          "autoincrement": false
+        }
+      },
+      "indexes": {},
+      "foreignKeys": {},
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {},
+      "checkConstraints": {}
+    },
+    "interrupts": {
+      "name": "interrupts",
+      "columns": {
+        "interrupt_id": {
+          "name": "interrupt_id",
+          "type": "text",
+          "primaryKey": true,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "run_id": {
+          "name": "run_id",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "thread_id": {
+          "name": "thread_id",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "status": {
+          "name": "status",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "requested_at": {
+          "name": "requested_at",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "resolved_at": {
+          "name": "resolved_at",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": false,
+          "autoincrement": false
+        },
+        "payload_json": {
+          "name": "payload_json",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "response_json": {
+          "name": "response_json",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false,
+          "autoincrement": false
+        }
+      },
+      "indexes": {},
+      "foreignKeys": {},
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {},
+      "checkConstraints": {}
+    },
+    "messages": {
+      "name": "messages",
+      "columns": {
+        "thread_id": {
+          "name": "thread_id",
+          "type": "text",
+          "primaryKey": true,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "messages_json": {
+          "name": "messages_json",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        }
+      },
+      "indexes": {},
+      "foreignKeys": {},
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {},
+      "checkConstraints": {}
+    },
+    "metadata": {
+      "name": "metadata",
+      "columns": {
+        "scope": {
+          "name": "scope",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "key": {
+          "name": "key",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "value_json": {
+          "name": "value_json",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        }
+      },
+      "indexes": {},
+      "foreignKeys": {},
+      "compositePrimaryKeys": {
+        "metadata_scope_key_pk": {
+          "columns": ["scope", "key"],
+          "name": "metadata_scope_key_pk"
+        }
+      },
+      "uniqueConstraints": {},
+      "checkConstraints": {}
+    },
+    "runs": {
+      "name": "runs",
+      "columns": {
+        "run_id": {
+          "name": "run_id",
+          "type": "text",
+          "primaryKey": true,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "thread_id": {
+          "name": "thread_id",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "status": {
+          "name": "status",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "started_at": {
+          "name": "started_at",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "finished_at": {
+          "name": "finished_at",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": false,
+          "autoincrement": false
+        },
+        "error": {
+          "name": "error",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false,
+          "autoincrement": false
+        },
+        "usage_json": {
+          "name": "usage_json",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false,
+          "autoincrement": false
+        }
+      },
+      "indexes": {},
+      "foreignKeys": {},
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {},
+      "checkConstraints": {}
+    }
+  },
+  "views": {},
+  "enums": {},
+  "_meta": {
+    "schemas": {},
+    "tables": {},
+    "columns": {}
+  },
+  "internal": {
+    "indexes": {}
+  }
+}
diff --git a/packages/ai-persistence-drizzle/drizzle/meta/_journal.json b/packages/ai-persistence-drizzle/drizzle/meta/_journal.json
new file mode 100644
index 000000000..136516dfa
--- /dev/null
+++ b/packages/ai-persistence-drizzle/drizzle/meta/_journal.json
@@ -0,0 +1,13 @@
+{
+  "version": "7",
+  "dialect": "sqlite",
+  "entries": [
+    {
+      "idx": 0,
+      "version": "6",
+      "when": 1783594836281,
+      "tag": "0000_cute_vision",
+      "breakpoints": true
+    }
+  ]
+}
diff --git a/packages/ai-persistence-drizzle/package.json b/packages/ai-persistence-drizzle/package.json
new file mode 100644
index 000000000..70a5f8b49
--- /dev/null
+++ b/packages/ai-persistence-drizzle/package.json
@@ -0,0 +1,57 @@
+{
+  "name": "@tanstack/ai-persistence-drizzle",
+  "version": "0.1.0",
+  "description": "Drizzle ORM backend for TanStack AI state persistence — the batteries-included sqlPersistence (bundled migrations) and bring-your-own drizzlePersistence(db), with an exported schema you can drive with drizzle-kit.",
+  "author": "",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/TanStack/ai.git",
+    "directory": "packages/ai-persistence-drizzle"
+  },
+  "keywords": [
+    "ai",
+    "tanstack",
+    "persistence",
+    "drizzle",
+    "sqlite"
+  ],
+  "type": "module",
+  "module": "./dist/esm/index.js",
+  "types": "./dist/esm/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/esm/index.d.ts",
+      "import": "./dist/esm/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "src",
+    "drizzle",
+    "drizzle.config.ts"
+  ],
+  "scripts": {
+    "build": "vite build",
+    "clean": "premove ./build ./dist",
+    "db:generate": "drizzle-kit generate",
+    "lint:fix": "eslint ./src --fix",
+    "test:build": "publint --strict",
+    "test:eslint": "eslint ./src",
+    "test:lib": "vitest",
+    "test:lib:dev": "pnpm test:lib --watch",
+    "test:types": "tsc"
+  },
+  "peerDependencies": {
+    "@tanstack/ai": "workspace:^",
+    "@tanstack/ai-persistence": "workspace:^",
+    "drizzle-orm": ">=0.44.0"
+  },
+  "devDependencies": {
+    "@tanstack/ai": "workspace:*",
+    "@tanstack/ai-persistence": "workspace:*",
+    "@vitest/coverage-v8": "4.0.14",
+    "drizzle-kit": "^0.31.0",
+    "drizzle-orm": "^0.45.0"
+  }
+}
diff --git a/packages/ai-persistence-drizzle/src/index.ts b/packages/ai-persistence-drizzle/src/index.ts
new file mode 100644
index 000000000..7a7dd8f6f
--- /dev/null
+++ b/packages/ai-persistence-drizzle/src/index.ts
@@ -0,0 +1,145 @@
+/**
+ * Drizzle-backed **state** persistence for TanStack AI.
+ *
+ * Two entry points, one `AIPersistence` contract:
+ *
+ * - {@link sqlPersistence} — batteries-included. Give it a `dialect` + `url` and
+ *   it builds the database, applies the migrations bundled in `drizzle/`
+ *   (generated by drizzle-kit), and returns a ready `AIPersistence`.
+ * - {@link drizzlePersistence} — bring-your-own. Pass a Drizzle sqlite `db` you
+ *   already constructed and migrated (via `drizzle-kit` against the exported
+ *   {@link schema}); this just wires the stores over it.
+ *
+ * Locks are not part of the SQL schema — an in-memory lock is provided as a dev
+ * default so the returned persistence is complete. Swap in a distributed lock
+ * for multi-process deployments.
+ */
+import { existsSync, readFileSync } from 'node:fs'
+import { dirname, join } from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { DatabaseSync } from 'node:sqlite'
+import { drizzle } from 'drizzle-orm/sqlite-proxy'
+import { InMemoryLockStore } from '@tanstack/ai'
+import {
+  createArtifactStore,
+  createBlobStore,
+  createInterruptStore,
+  createMessageStore,
+  createMetadataStore,
+  createRunStore,
+} from './stores'
+import { schema } from './schema'
+import type { DrizzleDb } from './stores'
+import type { AIPersistence } from '@tanstack/ai-persistence'
+
+export { schema }
+export type { DrizzleDb } from './stores'
+export * from './schema'
+
+/** Wire the AIPersistence stores over an existing Drizzle sqlite database. */
+export function drizzlePersistence(db: DrizzleDb): AIPersistence {
+  return {
+    stores: {
+      messages: createMessageStore(db),
+      runs: createRunStore(db),
+      interrupts: createInterruptStore(db),
+      metadata: createMetadataStore(db),
+      artifacts: createArtifactStore(db),
+      blobs: createBlobStore(db),
+      locks: new InMemoryLockStore(),
+    },
+  }
+}
+
+export interface SqlPersistenceOptions {
+  /**
+   * SQL dialect. Only `'sqlite'` is bundled with batteries (migrations shipped
+   * in `drizzle/`), so it is the sole accepted value and the default. For
+   * `postgres`/`mysql`, construct your own Drizzle db and use
+   * {@link drizzlePersistence} with migrations generated from the exported
+   * {@link schema} — `sqlPersistence` cannot build those for you.
+   */
+  dialect?: 'sqlite'
+  /** Database URL/path. For sqlite: `:memory:` or a file path (`file:` prefix optional). */
+  url: string
+  /** Apply the bundled migrations on construction (default false). */
+  migrate?: boolean
+}
+
+/** Build an {@link AIPersistence} from a dialect + url, applying bundled migrations. */
+export function sqlPersistence(opts: SqlPersistenceOptions): AIPersistence {
+  // `dialect` is typed `'sqlite'` only, but guard at runtime so an untyped JS
+  // caller passing another dialect fails loud instead of silently getting a
+  // sqlite db.
+  const dialect = opts.dialect ?? 'sqlite'
+  // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition
+  if (dialect !== 'sqlite') {
+    throw new Error(
+      `sqlPersistence bundles the sqlite dialect only; for '${dialect}' construct a Drizzle db yourself and use drizzlePersistence(db) with migrations generated from the exported schema.`,
+    )
+  }
+  const sqlite = new DatabaseSync(normalizeSqliteUrl(opts.url))
+  if (opts.migrate) applyBundledMigrations(sqlite)
+  const db = drizzle((sql, params, method) => {
+    const stmt = sqlite.prepare(sql)
+    if (method === 'run') {
+      stmt.run(...params)
+      return Promise.resolve({ rows: [] })
+    }
+    if (method === 'get') {
+      const row = stmt.get(...params)
+      // The store impl only ever selects via `.all()`, so `get` is unused; a
+      // missing row maps to an empty positional array either way.
+      return Promise.resolve({ rows: row ? Object.values(row) : [] })
+    }
+    const rows = stmt.all(...params)
+    return Promise.resolve({ rows: rows.map((row) => Object.values(row)) })
+  })
+  return drizzlePersistence(db)
+}
+
+function normalizeSqliteUrl(url: string): string {
+  if (url === ':memory:') return url
+  return url.startsWith('file:') ? url.slice('file:'.length) : url
+}
+
+interface MigrationJournal {
+  entries?: Array<{ tag: string }>
+}
+
+/** Locate the bundled `drizzle/` migrations dir relative to this module (src or dist). */
+function findMigrationsDir(): string {
+  let dir = dirname(fileURLToPath(import.meta.url))
+  for (let i = 0; i < 8; i++) {
+    const candidate = join(dir, 'drizzle')
+    if (existsSync(join(candidate, 'meta', '_journal.json'))) return candidate
+    const parent = dirname(dir)
+    if (parent === dir) break
+    dir = parent
+  }
+  throw new Error('Could not locate the bundled drizzle migrations directory.')
+}
+
+function applyBundledMigrations(sqlite: DatabaseSync): void {
+  const migrationsDir = findMigrationsDir()
+  const journal = JSON.parse(
+    readFileSync(join(migrationsDir, 'meta', '_journal.json'), 'utf8'),
+  ) as MigrationJournal
+  sqlite.exec(
+    'CREATE TABLE IF NOT EXISTS __drizzle_migrations (tag TEXT PRIMARY KEY, applied_at INTEGER NOT NULL)',
+  )
+  const appliedRows = sqlite
+    .prepare('SELECT tag FROM __drizzle_migrations')
+    .all() as Array<{ tag: string }>
+  const applied = new Set(appliedRows.map((row) => row.tag))
+  for (const entry of journal.entries ?? []) {
+    if (applied.has(entry.tag)) continue
+    const sql = readFileSync(join(migrationsDir, `${entry.tag}.sql`), 'utf8')
+    sqlite.exec(sql)
+    sqlite
+      .prepare(
+        'INSERT INTO __drizzle_migrations (tag, applied_at) VALUES (?, ?)',
+      )
+      .run(entry.tag, Date.now())
+  }
+}
diff --git a/packages/ai-persistence-drizzle/src/schema.ts b/packages/ai-persistence-drizzle/src/schema.ts
new file mode 100644
index 000000000..ee18c86ef
--- /dev/null
+++ b/packages/ai-persistence-drizzle/src/schema.ts
@@ -0,0 +1,105 @@
+/**
+ * Drizzle schema for the TanStack AI **state** persistence contract.
+ *
+ * Each table mirrors the corresponding record in
+ * `@tanstack/ai-persistence`'s `types.ts` column-for-column. JSON-valued fields
+ * are stored in `*_json` text columns (portable across sqlite/pg/mysql); epoch
+ * millisecond timestamps are stored as integers.
+ *
+ * This schema is the single source of truth for migrations: run
+ * `pnpm db:generate` (drizzle-kit) after any change here. It is also exported
+ * from the package so bring-your-own-drizzle users can drive their own
+ * migration workflow against it.
+ *
+ * NOTE: keep this in sync with the sibling Prisma schema fragment
+ * (`@tanstack/ai-persistence-prisma`). See coupling `persistence-schema-dual-source`.
+ */
+import {
+  blob,
+  integer,
+  primaryKey,
+  sqliteTable,
+  text,
+} from 'drizzle-orm/sqlite-core'
+import type { InterruptRecord, RunStatus } from '@tanstack/ai-persistence'
+import type { ModelMessage, TokenUsage } from '@tanstack/ai'
+
+/** Thread message history (`MessageStore`). */
+export const messages = sqliteTable('messages', {
+  threadId: text('thread_id').primaryKey(),
+  messagesJson: text('messages_json', { mode: 'json' })
+    .$type<Array<ModelMessage>>()
+    .notNull(),
+})
+
+/** Run lifecycle records (`RunStore`). */
+export const runs = sqliteTable('runs', {
+  runId: text('run_id').primaryKey(),
+  threadId: text('thread_id').notNull(),
+  status: text('status').$type<RunStatus>().notNull(),
+  startedAt: integer('started_at').notNull(),
+  finishedAt: integer('finished_at'),
+  error: text('error'),
+  usageJson: text('usage_json', { mode: 'json' }).$type<TokenUsage>(),
+})
+
+/** Interrupt / approval records (`InterruptStore`). */
+export const interrupts = sqliteTable('interrupts', {
+  interruptId: text('interrupt_id').primaryKey(),
+  runId: text('run_id').notNull(),
+  threadId: text('thread_id').notNull(),
+  status: text('status').$type<InterruptRecord['status']>().notNull(),
+  requestedAt: integer('requested_at').notNull(),
+  resolvedAt: integer('resolved_at'),
+  payloadJson: text('payload_json', { mode: 'json' })
+    .$type<Record<string, unknown>>()
+    .notNull(),
+  responseJson: text('response_json', { mode: 'json' }).$type<unknown>(),
+})
+
+/** Scoped key/value metadata (`MetadataStore`). */
+export const metadata = sqliteTable(
+  'metadata',
+  {
+    scope: text('scope').notNull(),
+    key: text('key').notNull(),
+    valueJson: text('value_json', { mode: 'json' }).$type<unknown>().notNull(),
+  },
+  (table) => [primaryKey({ columns: [table.scope, table.key] })],
+)
+
+/** Generation artifact references (`ArtifactStore`). Bytes live in the blob store. */
+export const artifacts = sqliteTable('artifacts', {
+  artifactId: text('artifact_id').primaryKey(),
+  runId: text('run_id').notNull(),
+  threadId: text('thread_id').notNull(),
+  name: text('name').notNull(),
+  mimeType: text('mime_type').notNull(),
+  size: integer('size').notNull(),
+  externalUrl: text('external_url'),
+  createdAt: integer('created_at').notNull(),
+})
+
+/** Generic blob objects (`BlobStore`). */
+export const blobs = sqliteTable('blobs', {
+  key: text('key').primaryKey(),
+  contentType: text('content_type'),
+  size: integer('size'),
+  etag: text('etag'),
+  customMetadataJson: text('custom_metadata_json', { mode: 'json' }).$type<
+    Record<string, string>
+  >(),
+  createdAt: integer('created_at'),
+  updatedAt: integer('updated_at'),
+  body: blob('body', { mode: 'buffer' }),
+})
+
+/** The full state schema, for `drizzlePersistence(db)` and drizzle-kit. */
+export const schema = {
+  messages,
+  runs,
+  interrupts,
+  metadata,
+  artifacts,
+  blobs,
+}
diff --git a/packages/ai-persistence-drizzle/src/stores.ts b/packages/ai-persistence-drizzle/src/stores.ts
new file mode 100644
index 000000000..8c768ec71
--- /dev/null
+++ b/packages/ai-persistence-drizzle/src/stores.ts
@@ -0,0 +1,507 @@
+/**
+ * AIPersistence store implementations over a Drizzle sqlite database.
+ *
+ * Each method mirrors the semantics of the reference in-memory backend
+ * (`@tanstack/ai-persistence`'s `memory.ts`). JSON columns are handled by
+ * Drizzle's `text({ mode: 'json' })`; blob bytes by `blob({ mode: 'buffer' })`.
+ */
+import { and, asc, eq, gt, gte, lt } from 'drizzle-orm'
+import {
+  artifacts,
+  blobs,
+  interrupts,
+  messages,
+  metadata,
+  runs,
+} from './schema'
+import type { SQL } from 'drizzle-orm'
+import type { BaseSQLiteDatabase } from 'drizzle-orm/sqlite-core'
+import type { ModelMessage } from '@tanstack/ai'
+import type {
+  ArtifactRecord,
+  ArtifactStore,
+  BlobBody,
+  BlobListOptions,
+  BlobListPage,
+  BlobObject,
+  BlobRecord,
+  BlobStore,
+  InterruptRecord,
+  InterruptStore,
+  MessageStore,
+  MetadataStore,
+  RunRecord,
+  RunStore,
+} from '@tanstack/ai-persistence'
+
+/**
+ * Any Drizzle sqlite database (better-sqlite3, libsql, node:sqlite proxy, D1, …).
+ *
+ * Typed as the schema-agnostic slice of the query builder we actually use, so a
+ * BYO `db` constructed with any `{ schema }` is assignable regardless of its
+ * `TFullSchema` (which is invariant on the full `BaseSQLiteDatabase`).
+ */
+export type DrizzleDb = Pick<
+  BaseSQLiteDatabase<'sync' | 'async', unknown>,
+  'select' | 'insert' | 'update' | 'delete'
+>
+
+const textEncoder = new TextEncoder()
+const textDecoder = new TextDecoder()
+
+/**
+ * Smallest string strictly greater than every string that starts with `prefix`,
+ * used as the exclusive upper bound of a literal prefix range scan. Increments
+ * the last non-`U+FFFF` UTF-16 code unit (carrying over trailing `U+FFFF`s).
+ * Returns `undefined` when no finite bound exists — an empty prefix, or a prefix
+ * consisting solely of `U+FFFF` — in which case the caller omits the upper bound.
+ */
+function prefixUpperBound(prefix: string): string | undefined {
+  let i = prefix.length - 1
+  while (i >= 0 && prefix.charCodeAt(i) === 0xffff) i--
+  if (i < 0) return undefined
+  return prefix.slice(0, i) + String.fromCharCode(prefix.charCodeAt(i) + 1)
+}
+
+function copyBytes(bytes: Uint8Array): Uint8Array {
+  return new Uint8Array(bytes)
+}
+
+function bytesToArrayBuffer(bytes: Uint8Array): ArrayBuffer {
+  const buffer = new ArrayBuffer(bytes.byteLength)
+  new Uint8Array(buffer).set(bytes)
+  return buffer
+}
+
+async function bytesFromStream(
+  stream: ReadableStream<Uint8Array>,
+): Promise<Uint8Array> {
+  const reader = stream.getReader()
+  const chunks: Array<Uint8Array> = []
+  let total = 0
+  try {
+    // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition
+    while (true) {
+      const { done, value } = await reader.read()
+      if (done) break
+      chunks.push(copyBytes(value))
+      total += value.byteLength
+    }
+  } finally {
+    reader.releaseLock()
+  }
+  const bytes = new Uint8Array(total)
+  let offset = 0
+  for (const chunk of chunks) {
+    bytes.set(chunk, offset)
+    offset += chunk.byteLength
+  }
+  return bytes
+}
+
+async function bytesFromBlobBody(body: BlobBody): Promise<Uint8Array> {
+  if (typeof body === 'string') return textEncoder.encode(body)
+  if (body instanceof ArrayBuffer) return new Uint8Array(body.slice(0))
+  if (ArrayBuffer.isView(body)) {
+    return copyBytes(
+      new Uint8Array(body.buffer, body.byteOffset, body.byteLength),
+    )
+  }
+  if (typeof Blob !== 'undefined' && body instanceof Blob) {
+    return new Uint8Array(await body.arrayBuffer())
+  }
+  if (typeof ReadableStream !== 'undefined' && body instanceof ReadableStream) {
+    return bytesFromStream(body)
+  }
+  throw new TypeError('Unsupported blob body.')
+}
+
+export function createMessageStore(db: DrizzleDb): MessageStore {
+  return {
+    async loadThread(threadId) {
+      const rows = await db
+        .select({ messagesJson: messages.messagesJson })
+        .from(messages)
+        .where(eq(messages.threadId, threadId))
+      return rows[0]?.messagesJson ?? []
+    },
+    async saveThread(threadId, msgs: Array<ModelMessage>) {
+      await db
+        .insert(messages)
+        .values({ threadId, messagesJson: msgs })
+        .onConflictDoUpdate({
+          target: messages.threadId,
+          set: { messagesJson: msgs },
+        })
+    },
+  }
+}
+
+function mapRun(row: typeof runs.$inferSelect): RunRecord {
+  return {
+    runId: row.runId,
+    threadId: row.threadId,
+    status: row.status,
+    startedAt: row.startedAt,
+    ...(row.finishedAt != null ? { finishedAt: row.finishedAt } : {}),
+    ...(row.error != null ? { error: row.error } : {}),
+    ...(row.usageJson != null ? { usage: row.usageJson } : {}),
+  }
+}
+
+export function createRunStore(db: DrizzleDb): RunStore {
+  const store: RunStore = {
+    async createOrResume(input) {
+      const existing = await store.get(input.runId)
+      if (existing) return existing
+      const record: RunRecord = {
+        runId: input.runId,
+        threadId: input.threadId,
+        status: input.status ?? 'running',
+        startedAt: input.startedAt,
+      }
+      await db
+        .insert(runs)
+        .values({
+          runId: record.runId,
+          threadId: record.threadId,
+          status: record.status,
+          startedAt: record.startedAt,
+        })
+        .onConflictDoNothing({ target: runs.runId })
+      return (await store.get(input.runId)) ?? record
+    },
+    async update(runId, patch) {
+      const set: Partial<typeof runs.$inferInsert> = {}
+      if (patch.status !== undefined) set.status = patch.status
+      if (patch.finishedAt !== undefined) set.finishedAt = patch.finishedAt
+      if (patch.error !== undefined) set.error = patch.error
+      if (patch.usage !== undefined) set.usageJson = patch.usage
+      if (Object.keys(set).length === 0) return
+      await db.update(runs).set(set).where(eq(runs.runId, runId))
+    },
+    async get(runId) {
+      const rows = await db.select().from(runs).where(eq(runs.runId, runId))
+      const row = rows[0]
+      return row ? mapRun(row) : null
+    },
+  }
+  return store
+}
+
+function mapInterrupt(row: typeof interrupts.$inferSelect): InterruptRecord {
+  return {
+    interruptId: row.interruptId,
+    runId: row.runId,
+    threadId: row.threadId,
+    status: row.status,
+    requestedAt: row.requestedAt,
+    ...(row.resolvedAt != null ? { resolvedAt: row.resolvedAt } : {}),
+    payload: row.payloadJson,
+    ...(row.responseJson != null ? { response: row.responseJson } : {}),
+  }
+}
+
+export function createInterruptStore(db: DrizzleDb): InterruptStore {
+  return {
+    async create(record) {
+      await db
+        .insert(interrupts)
+        .values({
+          interruptId: record.interruptId,
+          runId: record.runId,
+          threadId: record.threadId,
+          status: record.status,
+          requestedAt: record.requestedAt,
+          payloadJson: record.payload,
+          responseJson: record.response ?? null,
+        })
+        .onConflictDoNothing({ target: interrupts.interruptId })
+    },
+    async resolve(interruptId, response) {
+      await db
+        .update(interrupts)
+        .set({
+          status: 'resolved',
+          resolvedAt: Date.now(),
+          responseJson: response ?? null,
+        })
+        .where(eq(interrupts.interruptId, interruptId))
+    },
+    async cancel(interruptId) {
+      await db
+        .update(interrupts)
+        .set({ status: 'cancelled', resolvedAt: Date.now() })
+        .where(eq(interrupts.interruptId, interruptId))
+    },
+    async get(interruptId) {
+      const rows = await db
+        .select()
+        .from(interrupts)
+        .where(eq(interrupts.interruptId, interruptId))
+      const row = rows[0]
+      return row ? mapInterrupt(row) : null
+    },
+    async list(threadId) {
+      const rows = await db
+        .select()
+        .from(interrupts)
+        .where(eq(interrupts.threadId, threadId))
+        .orderBy(asc(interrupts.requestedAt))
+      return rows.map(mapInterrupt)
+    },
+    async listPending(threadId) {
+      const rows = await db
+        .select()
+        .from(interrupts)
+        .where(
+          and(
+            eq(interrupts.threadId, threadId),
+            eq(interrupts.status, 'pending'),
+          ),
+        )
+        .orderBy(asc(interrupts.requestedAt))
+      return rows.map(mapInterrupt)
+    },
+    async listByRun(runId) {
+      const rows = await db
+        .select()
+        .from(interrupts)
+        .where(eq(interrupts.runId, runId))
+        .orderBy(asc(interrupts.requestedAt))
+      return rows.map(mapInterrupt)
+    },
+    async listPendingByRun(runId) {
+      const rows = await db
+        .select()
+        .from(interrupts)
+        .where(
+          and(eq(interrupts.runId, runId), eq(interrupts.status, 'pending')),
+        )
+        .orderBy(asc(interrupts.requestedAt))
+      return rows.map(mapInterrupt)
+    },
+  }
+}
+
+export function createMetadataStore(db: DrizzleDb): MetadataStore {
+  return {
+    async get(scope, key) {
+      const rows = await db
+        .select({ valueJson: metadata.valueJson })
+        .from(metadata)
+        .where(and(eq(metadata.scope, scope), eq(metadata.key, key)))
+      const row = rows[0]
+      return row ? row.valueJson : null
+    },
+    async set(scope, key, value) {
+      await db
+        .insert(metadata)
+        .values({ scope, key, valueJson: value })
+        .onConflictDoUpdate({
+          target: [metadata.scope, metadata.key],
+          set: { valueJson: value },
+        })
+    },
+    async delete(scope, key) {
+      await db
+        .delete(metadata)
+        .where(and(eq(metadata.scope, scope), eq(metadata.key, key)))
+    },
+  }
+}
+
+function mapArtifact(row: typeof artifacts.$inferSelect): ArtifactRecord {
+  return {
+    artifactId: row.artifactId,
+    runId: row.runId,
+    threadId: row.threadId,
+    name: row.name,
+    mimeType: row.mimeType,
+    size: row.size,
+    ...(row.externalUrl != null ? { externalUrl: row.externalUrl } : {}),
+    createdAt: row.createdAt,
+  }
+}
+
+export function createArtifactStore(db: DrizzleDb): ArtifactStore {
+  return {
+    async save(record) {
+      const values = {
+        artifactId: record.artifactId,
+        runId: record.runId,
+        threadId: record.threadId,
+        name: record.name,
+        mimeType: record.mimeType,
+        size: record.size,
+        externalUrl: record.externalUrl ?? null,
+        createdAt: record.createdAt,
+      }
+      await db
+        .insert(artifacts)
+        .values(values)
+        .onConflictDoUpdate({
+          target: artifacts.artifactId,
+          set: {
+            runId: values.runId,
+            threadId: values.threadId,
+            name: values.name,
+            mimeType: values.mimeType,
+            size: values.size,
+            externalUrl: values.externalUrl,
+            createdAt: values.createdAt,
+          },
+        })
+    },
+    async get(artifactId) {
+      const rows = await db
+        .select()
+        .from(artifacts)
+        .where(eq(artifacts.artifactId, artifactId))
+      const row = rows[0]
+      return row ? mapArtifact(row) : null
+    },
+    async list(runId) {
+      const rows = await db
+        .select()
+        .from(artifacts)
+        .where(eq(artifacts.runId, runId))
+        .orderBy(asc(artifacts.createdAt), asc(artifacts.artifactId))
+      return rows.map(mapArtifact)
+    },
+    async delete(artifactId) {
+      await db.delete(artifacts).where(eq(artifacts.artifactId, artifactId))
+    },
+    async deleteForRun(runId) {
+      await db.delete(artifacts).where(eq(artifacts.runId, runId))
+    },
+  }
+}
+
+function blobRecordSnapshot(row: typeof blobs.$inferSelect): BlobRecord {
+  return {
+    key: row.key,
+    ...(row.size != null ? { size: row.size } : {}),
+    ...(row.etag != null ? { etag: row.etag } : {}),
+    ...(row.contentType != null ? { contentType: row.contentType } : {}),
+    ...(row.customMetadataJson != null
+      ? { customMetadata: { ...row.customMetadataJson } }
+      : {}),
+    ...(row.createdAt != null ? { createdAt: row.createdAt } : {}),
+    ...(row.updatedAt != null ? { updatedAt: row.updatedAt } : {}),
+  }
+}
+
+function blobObject(row: typeof blobs.$inferSelect): BlobObject {
+  const bytes = row.body
+    ? copyBytes(new Uint8Array(row.body))
+    : new Uint8Array()
+  return {
+    ...blobRecordSnapshot(row),
+    body: new ReadableStream<Uint8Array>({
+      start(controller) {
+        controller.enqueue(copyBytes(bytes))
+        controller.close()
+      },
+    }),
+    arrayBuffer: () => Promise.resolve(bytesToArrayBuffer(bytes)),
+    text: () => Promise.resolve(textDecoder.decode(bytes)),
+  }
+}
+
+export function createBlobStore(db: DrizzleDb): BlobStore {
+  const readRow = async (key: string) => {
+    const rows = await db.select().from(blobs).where(eq(blobs.key, key))
+    return rows[0] ?? null
+  }
+  return {
+    async put(key, body, options) {
+      const bytes = await bytesFromBlobBody(body)
+      const existing = await readRow(key)
+      const now = Date.now()
+      const contentType =
+        options?.contentType ??
+        (typeof Blob !== 'undefined' && body instanceof Blob
+          ? body.type || undefined
+          : undefined)
+      const customMetadata = options?.customMetadata
+        ? { ...options.customMetadata }
+        : undefined
+      const record = {
+        key,
+        contentType: contentType ?? null,
+        size: bytes.byteLength,
+        etag: crypto.randomUUID(),
+        customMetadataJson: customMetadata ?? null,
+        createdAt: existing?.createdAt ?? now,
+        updatedAt: now,
+        body: Buffer.from(bytes),
+      }
+      await db
+        .insert(blobs)
+        .values(record)
+        .onConflictDoUpdate({
+          target: blobs.key,
+          set: {
+            contentType: record.contentType,
+            size: record.size,
+            etag: record.etag,
+            customMetadataJson: record.customMetadataJson,
+            createdAt: record.createdAt,
+            updatedAt: record.updatedAt,
+            body: record.body,
+          },
+        })
+      const stored = await readRow(key)
+      return stored ? blobRecordSnapshot(stored) : blobRecordSnapshot(record)
+    },
+    async get(key) {
+      const row = await readRow(key)
+      return row ? blobObject(row) : null
+    },
+    async head(key) {
+      const row = await readRow(key)
+      return row ? blobRecordSnapshot(row) : null
+    },
+    async delete(key) {
+      await db.delete(blobs).where(eq(blobs.key, key))
+    },
+    async list(options?: BlobListOptions): Promise<BlobListPage> {
+      const limit = options?.limit
+      if (limit === 0) return { objects: [], truncated: false }
+      const prefix = options?.prefix ?? ''
+      // Match the prefix LITERALLY and case-sensitively to mirror the reference
+      // in-memory backend's `key.startsWith(prefix)`. A SQL `LIKE '${prefix}%'`
+      // would treat `_`/`%` in the caller's prefix as wildcards and, on SQLite,
+      // match case-insensitively for ASCII. Instead use a half-open range on the
+      // (BINARY-collated) key column: `key >= prefix AND key < upperBound`, where
+      // upperBound is the smallest string strictly greater than every key that
+      // starts with `prefix`. This contains no LIKE metacharacters and relies on
+      // the default binary/byte ordering, giving literal, case-sensitive matching.
+      const conditions: Array<SQL> = []
+      if (prefix !== '') {
+        conditions.push(gte(blobs.key, prefix))
+        const upperBound = prefixUpperBound(prefix)
+        if (upperBound !== undefined) {
+          conditions.push(lt(blobs.key, upperBound))
+        }
+      }
+      if (options?.cursor !== undefined) {
+        conditions.push(gt(blobs.key, options.cursor))
+      }
+      const base = db
+        .select()
+        .from(blobs)
+        .where(and(...conditions))
+        .orderBy(asc(blobs.key))
+      const rows = await (limit === undefined ? base : base.limit(limit + 1))
+      const pageRows = limit === undefined ? rows : rows.slice(0, limit)
+      const objects = pageRows.map(blobRecordSnapshot)
+      const truncated = limit !== undefined && rows.length > limit
+      return {
+        objects,
+        ...(truncated ? { cursor: pageRows.at(-1)?.key, truncated } : {}),
+      }
+    },
+  }
+}
diff --git a/packages/ai-persistence-drizzle/tests/drizzle.conformance.test.ts b/packages/ai-persistence-drizzle/tests/drizzle.conformance.test.ts
new file mode 100644
index 000000000..a624bc933
--- /dev/null
+++ b/packages/ai-persistence-drizzle/tests/drizzle.conformance.test.ts
@@ -0,0 +1,6 @@
+import { runPersistenceConformance } from '@tanstack/ai-persistence/testkit'
+import { sqlPersistence } from '../src/index'
+
+runPersistenceConformance('drizzle-sqlite', () =>
+  sqlPersistence({ dialect: 'sqlite', url: ':memory:', migrate: true }),
+)
diff --git a/packages/ai-persistence-drizzle/tsconfig.json b/packages/ai-persistence-drizzle/tsconfig.json
new file mode 100644
index 000000000..c38689f4e
--- /dev/null
+++ b/packages/ai-persistence-drizzle/tsconfig.json
@@ -0,0 +1,8 @@
+{
+  "extends": "../../tsconfig.base.json",
+  "compilerOptions": {
+    "outDir": "dist"
+  },
+  "include": ["src", "tests"],
+  "exclude": ["node_modules", "dist"]
+}
diff --git a/packages/ai-persistence-drizzle/vite.config.ts b/packages/ai-persistence-drizzle/vite.config.ts
new file mode 100644
index 000000000..11f5b20b7
--- /dev/null
+++ b/packages/ai-persistence-drizzle/vite.config.ts
@@ -0,0 +1,37 @@
+import { defineConfig, mergeConfig } from 'vitest/config'
+import { tanstackViteConfig } from '@tanstack/vite-config'
+import packageJson from './package.json'
+
+const config = defineConfig({
+  test: {
+    name: packageJson.name,
+    dir: './',
+    watch: false,
+
+    globals: true,
+    environment: 'node',
+    include: ['tests/**/*.test.ts'],
+    coverage: {
+      provider: 'v8',
+      reporter: ['text', 'json', 'html', 'lcov'],
+      exclude: [
+        'node_modules/',
+        'dist/',
+        'tests/',
+        '**/*.test.ts',
+        '**/*.config.ts',
+        '**/types.ts',
+      ],
+      include: ['src/**/*.ts'],
+    },
+  },
+})
+
+export default mergeConfig(
+  config,
+  tanstackViteConfig({
+    entry: ['./src/index.ts'],
+    srcDir: './src',
+    cjs: false,
+  }),
+)
diff --git a/packages/ai-persistence-prisma/.gitignore b/packages/ai-persistence-prisma/.gitignore
new file mode 100644
index 000000000..e1c30d225
--- /dev/null
+++ b/packages/ai-persistence-prisma/.gitignore
@@ -0,0 +1,3 @@
+# Scratch sqlite databases used to generate migrations / run tests.
+prisma/*.db
+prisma/*.db-journal
diff --git a/packages/ai-persistence-prisma/package.json b/packages/ai-persistence-prisma/package.json
new file mode 100644
index 000000000..b387e8fa6
--- /dev/null
+++ b/packages/ai-persistence-prisma/package.json
@@ -0,0 +1,87 @@
+{
+  "name": "@tanstack/ai-persistence-prisma",
+  "version": "0.1.0",
+  "description": "Prisma backend for TanStack AI state persistence — bring your own PrismaClient. Ships a schema.prisma fragment mirroring @tanstack/ai-persistence-drizzle column-for-column, plus prismaPersistence(prisma) wiring the AIPersistence stores over a PrismaClient.",
+  "author": "",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/TanStack/ai.git",
+    "directory": "packages/ai-persistence-prisma"
+  },
+  "keywords": [
+    "ai",
+    "tanstack",
+    "persistence",
+    "prisma",
+    "sqlite"
+  ],
+  "type": "module",
+  "module": "./dist/esm/index.js",
+  "types": "./dist/esm/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/esm/index.d.ts",
+      "import": "./dist/esm/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "src",
+    "prisma"
+  ],
+  "scripts": {
+    "build": "vite build",
+    "clean": "premove ./build ./dist",
+    "db:generate": "prisma generate",
+    "lint:fix": "eslint ./src --fix",
+    "test:build": "publint --strict",
+    "test:eslint": "eslint ./src",
+    "test:lib": "vitest",
+    "test:lib:dev": "pnpm test:lib --watch",
+    "test:types": "tsc"
+  },
+  "nx": {
+    "targets": {
+      "db:generate": {
+        "cache": false
+      },
+      "build": {
+        "dependsOn": [
+          "db:generate",
+          "^build"
+        ]
+      },
+      "test:lib": {
+        "dependsOn": [
+          "db:generate",
+          "^build"
+        ]
+      },
+      "test:types": {
+        "dependsOn": [
+          "db:generate",
+          "^build"
+        ]
+      },
+      "test:eslint": {
+        "dependsOn": [
+          "db:generate",
+          "^build"
+        ]
+      }
+    }
+  },
+  "peerDependencies": {
+    "@prisma/client": ">=6",
+    "@tanstack/ai": "workspace:^",
+    "@tanstack/ai-persistence": "workspace:^"
+  },
+  "devDependencies": {
+    "@prisma/client": "^6.19.3",
+    "@tanstack/ai": "workspace:*",
+    "@tanstack/ai-persistence": "workspace:*",
+    "@vitest/coverage-v8": "4.0.14",
+    "prisma": "^6.19.3"
+  }
+}
diff --git a/packages/ai-persistence-prisma/prisma/migrations/20260709120042_init/migration.sql b/packages/ai-persistence-prisma/prisma/migrations/20260709120042_init/migration.sql
new file mode 100644
index 000000000..9140976fd
--- /dev/null
+++ b/packages/ai-persistence-prisma/prisma/migrations/20260709120042_init/migration.sql
@@ -0,0 +1,61 @@
+-- CreateTable
+CREATE TABLE "messages" (
+    "thread_id" TEXT NOT NULL PRIMARY KEY,
+    "messages_json" TEXT NOT NULL
+);
+
+-- CreateTable
+CREATE TABLE "runs" (
+    "run_id" TEXT NOT NULL PRIMARY KEY,
+    "thread_id" TEXT NOT NULL,
+    "status" TEXT NOT NULL,
+    "started_at" BIGINT NOT NULL,
+    "finished_at" BIGINT,
+    "error" TEXT,
+    "usage_json" TEXT
+);
+
+-- CreateTable
+CREATE TABLE "interrupts" (
+    "interrupt_id" TEXT NOT NULL PRIMARY KEY,
+    "run_id" TEXT NOT NULL,
+    "thread_id" TEXT NOT NULL,
+    "status" TEXT NOT NULL,
+    "requested_at" BIGINT NOT NULL,
+    "resolved_at" BIGINT,
+    "payload_json" TEXT NOT NULL,
+    "response_json" TEXT
+);
+
+-- CreateTable
+CREATE TABLE "metadata" (
+    "scope" TEXT NOT NULL,
+    "key" TEXT NOT NULL,
+    "value_json" TEXT NOT NULL,
+
+    PRIMARY KEY ("scope", "key")
+);
+
+-- CreateTable
+CREATE TABLE "artifacts" (
+    "artifact_id" TEXT NOT NULL PRIMARY KEY,
+    "run_id" TEXT NOT NULL,
+    "thread_id" TEXT NOT NULL,
+    "name" TEXT NOT NULL,
+    "mime_type" TEXT NOT NULL,
+    "size" BIGINT NOT NULL,
+    "external_url" TEXT,
+    "created_at" BIGINT NOT NULL
+);
+
+-- CreateTable
+CREATE TABLE "blobs" (
+    "key" TEXT NOT NULL PRIMARY KEY,
+    "content_type" TEXT,
+    "size" BIGINT,
+    "etag" TEXT,
+    "custom_metadata_json" TEXT,
+    "created_at" BIGINT,
+    "updated_at" BIGINT,
+    "body" BLOB
+);
diff --git a/packages/ai-persistence-prisma/prisma/migrations/migration_lock.toml b/packages/ai-persistence-prisma/prisma/migrations/migration_lock.toml
new file mode 100644
index 000000000..2a5a44419
--- /dev/null
+++ b/packages/ai-persistence-prisma/prisma/migrations/migration_lock.toml
@@ -0,0 +1,3 @@
+# Please do not edit this file manually
+# It should be added in your version-control system (e.g., Git)
+provider = "sqlite"
diff --git a/packages/ai-persistence-prisma/prisma/schema.prisma b/packages/ai-persistence-prisma/prisma/schema.prisma
new file mode 100644
index 000000000..ae2f3031a
--- /dev/null
+++ b/packages/ai-persistence-prisma/prisma/schema.prisma
@@ -0,0 +1,101 @@
+// Prisma schema for the TanStack AI **state** persistence contract.
+//
+// Kept in sync with packages/ai-persistence-drizzle/src/schema.ts — see coupling
+// persistence-schema-dual-source. The two ORMs describe the SAME state tables and
+// have NO auto-converter: any change here MUST be mirrored in the drizzle schema,
+// with regenerated migrations for BOTH ORMs and the shared conformance suite
+// re-run against memory + drizzle + prisma.
+//
+// JSON-valued fields are stored in `*_json` TEXT columns (portable, and matching
+// drizzle's `text({ mode: 'json' })` on-disk shape); epoch-millisecond timestamps
+// and sizes are stored as integers. Prisma's `Json` type is unavailable on
+// sqlite, so the store layer serializes/deserializes those columns with
+// JSON.stringify/parse.
+//
+// Integer columns use Prisma `BigInt` (not `Int`): both map to a sqlite
+// `INTEGER` column — so the DDL matches drizzle's `integer()` column-for-column
+// — but `BigInt` covers the full 64-bit range that epoch-millisecond timestamps
+// require (`Int` caps at 32 bits). The store layer converts bigint <-> number at
+// the boundary so records stay plain `number`s, matching the drizzle backend.
+
+generator client {
+  provider = "prisma-client-js"
+}
+
+datasource db {
+  provider = "sqlite"
+  url      = env("DATABASE_URL")
+}
+
+/// Thread message history (`MessageStore`).
+model Message {
+  threadId     String @id @map("thread_id")
+  messagesJson String @map("messages_json")
+
+  @@map("messages")
+}
+
+/// Run lifecycle records (`RunStore`).
+model Run {
+  runId      String  @id @map("run_id")
+  threadId   String  @map("thread_id")
+  status     String
+  startedAt  BigInt  @map("started_at")
+  finishedAt BigInt? @map("finished_at")
+  error      String?
+  usageJson  String? @map("usage_json")
+
+  @@map("runs")
+}
+
+/// Interrupt / approval records (`InterruptStore`).
+model Interrupt {
+  interruptId  String  @id @map("interrupt_id")
+  runId        String  @map("run_id")
+  threadId     String  @map("thread_id")
+  status       String
+  requestedAt  BigInt  @map("requested_at")
+  resolvedAt   BigInt? @map("resolved_at")
+  payloadJson  String  @map("payload_json")
+  responseJson String? @map("response_json")
+
+  @@map("interrupts")
+}
+
+/// Scoped key/value metadata (`MetadataStore`).
+model Metadata {
+  scope     String
+  key       String
+  valueJson String @map("value_json")
+
+  @@id([scope, key])
+  @@map("metadata")
+}
+
+/// Generation artifact references (`ArtifactStore`). Bytes live in the blob store.
+model Artifact {
+  artifactId  String  @id @map("artifact_id")
+  runId       String  @map("run_id")
+  threadId    String  @map("thread_id")
+  name        String
+  mimeType    String  @map("mime_type")
+  size        BigInt
+  externalUrl String? @map("external_url")
+  createdAt   BigInt  @map("created_at")
+
+  @@map("artifacts")
+}
+
+/// Generic blob objects (`BlobStore`).
+model Blob {
+  key                String  @id
+  contentType        String? @map("content_type")
+  size               BigInt?
+  etag               String?
+  customMetadataJson String? @map("custom_metadata_json")
+  createdAt          BigInt? @map("created_at")
+  updatedAt          BigInt? @map("updated_at")
+  body               Bytes?
+
+  @@map("blobs")
+}
diff --git a/packages/ai-persistence-prisma/src/index.ts b/packages/ai-persistence-prisma/src/index.ts
new file mode 100644
index 000000000..09ab56573
--- /dev/null
+++ b/packages/ai-persistence-prisma/src/index.ts
@@ -0,0 +1,44 @@
+/**
+ * Prisma-backed **state** persistence for TanStack AI.
+ *
+ * Bring your own `PrismaClient`: add the model fragment shipped in this
+ * package's `prisma/schema.prisma` to your own Prisma schema, run
+ * `prisma migrate` through your normal workflow, then pass the generated
+ * client to {@link prismaPersistence}. This wires the `AIPersistence` stores
+ * (messages, runs, interrupts, metadata, artifacts, blobs) over it.
+ *
+ * The Prisma schema mirrors `@tanstack/ai-persistence-drizzle`'s exported
+ * schema column-for-column — see coupling `persistence-schema-dual-source`.
+ * Any change to one schema MUST be mirrored in the other, with regenerated
+ * migrations for both ORMs and the shared conformance suite re-run.
+ *
+ * Locks are not part of the SQL schema — an in-memory lock is provided as a dev
+ * default so the returned persistence is complete. Swap in a distributed lock
+ * for multi-process deployments.
+ */
+import { InMemoryLockStore } from '@tanstack/ai'
+import {
+  createArtifactStore,
+  createBlobStore,
+  createInterruptStore,
+  createMessageStore,
+  createMetadataStore,
+  createRunStore,
+} from './stores'
+import type { PrismaClient } from '@prisma/client'
+import type { AIPersistence } from '@tanstack/ai-persistence'
+
+/** Wire the AIPersistence stores over an existing Prisma `PrismaClient`. */
+export function prismaPersistence(prisma: PrismaClient): AIPersistence {
+  return {
+    stores: {
+      messages: createMessageStore(prisma),
+      runs: createRunStore(prisma),
+      interrupts: createInterruptStore(prisma),
+      metadata: createMetadataStore(prisma),
+      artifacts: createArtifactStore(prisma),
+      blobs: createBlobStore(prisma),
+      locks: new InMemoryLockStore(),
+    },
+  }
+}
diff --git a/packages/ai-persistence-prisma/src/stores.ts b/packages/ai-persistence-prisma/src/stores.ts
new file mode 100644
index 000000000..72be8bbd3
--- /dev/null
+++ b/packages/ai-persistence-prisma/src/stores.ts
@@ -0,0 +1,495 @@
+/**
+ * AIPersistence store implementations over a Prisma `PrismaClient`.
+ *
+ * Each method mirrors the semantics of the reference in-memory backend
+ * (`@tanstack/ai-persistence`'s `memory.ts`) and the sibling Drizzle backend
+ * (`@tanstack/ai-persistence-drizzle`'s `stores.ts`). JSON-valued columns are
+ * TEXT (Prisma's `Json` type is unavailable on sqlite), so they are serialized
+ * with `JSON.stringify`/`JSON.parse` here; blob bytes use Prisma's `Bytes`.
+ */
+import type { PrismaClient } from '@prisma/client'
+import type { ModelMessage } from '@tanstack/ai'
+import type {
+  ArtifactRecord,
+  ArtifactStore,
+  BlobBody,
+  BlobListOptions,
+  BlobListPage,
+  BlobObject,
+  BlobRecord,
+  BlobStore,
+  InterruptRecord,
+  InterruptStore,
+  MessageStore,
+  MetadataStore,
+  RunRecord,
+  RunStatus,
+  RunStore,
+} from '@tanstack/ai-persistence'
+
+const textEncoder = new TextEncoder()
+const textDecoder = new TextDecoder()
+
+/**
+ * Smallest string strictly greater than every string that starts with `prefix`,
+ * used as the exclusive upper bound of a literal prefix range scan. Increments
+ * the last non-`U+FFFF` UTF-16 code unit (carrying over trailing `U+FFFF`s).
+ * Returns `undefined` when no finite bound exists — an empty prefix, or a prefix
+ * consisting solely of `U+FFFF` — in which case the caller omits the upper bound.
+ */
+function prefixUpperBound(prefix: string): string | undefined {
+  let i = prefix.length - 1
+  while (i >= 0 && prefix.charCodeAt(i) === 0xffff) i--
+  if (i < 0) return undefined
+  return prefix.slice(0, i) + String.fromCharCode(prefix.charCodeAt(i) + 1)
+}
+
+function copyBytes(bytes: Uint8Array): Uint8Array {
+  return new Uint8Array(bytes)
+}
+
+function bytesToArrayBuffer(bytes: Uint8Array): ArrayBuffer {
+  const buffer = new ArrayBuffer(bytes.byteLength)
+  new Uint8Array(buffer).set(bytes)
+  return buffer
+}
+
+async function bytesFromStream(
+  stream: ReadableStream<Uint8Array>,
+): Promise<Uint8Array> {
+  const reader = stream.getReader()
+  const chunks: Array<Uint8Array> = []
+  let total = 0
+  try {
+    // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition
+    while (true) {
+      const { done, value } = await reader.read()
+      if (done) break
+      chunks.push(copyBytes(value))
+      total += value.byteLength
+    }
+  } finally {
+    reader.releaseLock()
+  }
+  const bytes = new Uint8Array(total)
+  let offset = 0
+  for (const chunk of chunks) {
+    bytes.set(chunk, offset)
+    offset += chunk.byteLength
+  }
+  return bytes
+}
+
+async function bytesFromBlobBody(body: BlobBody): Promise<Uint8Array> {
+  if (typeof body === 'string') return textEncoder.encode(body)
+  if (body instanceof ArrayBuffer) return new Uint8Array(body.slice(0))
+  if (ArrayBuffer.isView(body)) {
+    return copyBytes(
+      new Uint8Array(body.buffer, body.byteOffset, body.byteLength),
+    )
+  }
+  if (typeof Blob !== 'undefined' && body instanceof Blob) {
+    return new Uint8Array(await body.arrayBuffer())
+  }
+  if (typeof ReadableStream !== 'undefined' && body instanceof ReadableStream) {
+    return bytesFromStream(body)
+  }
+  throw new TypeError('Unsupported blob body.')
+}
+
+export function createMessageStore(prisma: PrismaClient): MessageStore {
+  return {
+    async loadThread(threadId) {
+      const row = await prisma.message.findUnique({ where: { threadId } })
+      if (!row) return []
+      return JSON.parse(row.messagesJson) as Array<ModelMessage>
+    },
+    async saveThread(threadId, msgs: Array<ModelMessage>) {
+      const messagesJson = JSON.stringify(msgs)
+      await prisma.message.upsert({
+        where: { threadId },
+        create: { threadId, messagesJson },
+        update: { messagesJson },
+      })
+    },
+  }
+}
+
+interface RunRow {
+  runId: string
+  threadId: string
+  status: string
+  startedAt: bigint
+  finishedAt: bigint | null
+  error: string | null
+  usageJson: string | null
+}
+
+function mapRun(row: RunRow): RunRecord {
+  return {
+    runId: row.runId,
+    threadId: row.threadId,
+    status: row.status as RunStatus,
+    startedAt: Number(row.startedAt),
+    ...(row.finishedAt != null ? { finishedAt: Number(row.finishedAt) } : {}),
+    ...(row.error != null ? { error: row.error } : {}),
+    ...(row.usageJson != null
+      ? { usage: JSON.parse(row.usageJson) as RunRecord['usage'] }
+      : {}),
+  }
+}
+
+export function createRunStore(prisma: PrismaClient): RunStore {
+  const store: RunStore = {
+    async createOrResume(input) {
+      const existing = await store.get(input.runId)
+      if (existing) return existing
+      const record: RunRecord = {
+        runId: input.runId,
+        threadId: input.threadId,
+        status: input.status ?? 'running',
+        startedAt: input.startedAt,
+      }
+      // Upsert with an empty update = insert-if-absent (never overwrites an
+      // existing run), matching the reference createOrResume semantics.
+      await prisma.run.upsert({
+        where: { runId: record.runId },
+        create: {
+          runId: record.runId,
+          threadId: record.threadId,
+          status: record.status,
+          startedAt: BigInt(record.startedAt),
+        },
+        update: {},
+      })
+      return (await store.get(input.runId)) ?? record
+    },
+    async update(runId, patch) {
+      const data: {
+        status?: RunStatus
+        finishedAt?: bigint
+        error?: string
+        usageJson?: string
+      } = {}
+      if (patch.status !== undefined) data.status = patch.status
+      if (patch.finishedAt !== undefined)
+        data.finishedAt = BigInt(patch.finishedAt)
+      if (patch.error !== undefined) data.error = patch.error
+      if (patch.usage !== undefined)
+        data.usageJson = JSON.stringify(patch.usage)
+      if (Object.keys(data).length === 0) return
+      // updateMany no-ops (does not throw) when the run does not exist.
+      await prisma.run.updateMany({ where: { runId }, data })
+    },
+    async get(runId) {
+      const row = await prisma.run.findUnique({ where: { runId } })
+      return row ? mapRun(row) : null
+    },
+  }
+  return store
+}
+
+interface InterruptRow {
+  interruptId: string
+  runId: string
+  threadId: string
+  status: string
+  requestedAt: bigint
+  resolvedAt: bigint | null
+  payloadJson: string
+  responseJson: string | null
+}
+
+function mapInterrupt(row: InterruptRow): InterruptRecord {
+  return {
+    interruptId: row.interruptId,
+    runId: row.runId,
+    threadId: row.threadId,
+    status: row.status as InterruptRecord['status'],
+    requestedAt: Number(row.requestedAt),
+    ...(row.resolvedAt != null ? { resolvedAt: Number(row.resolvedAt) } : {}),
+    payload: JSON.parse(row.payloadJson) as Record<string, unknown>,
+    ...(row.responseJson != null
+      ? { response: JSON.parse(row.responseJson) as unknown }
+      : {}),
+  }
+}
+
+export function createInterruptStore(prisma: PrismaClient): InterruptStore {
+  return {
+    async create(record) {
+      await prisma.interrupt.upsert({
+        where: { interruptId: record.interruptId },
+        create: {
+          interruptId: record.interruptId,
+          runId: record.runId,
+          threadId: record.threadId,
+          status: record.status,
+          requestedAt: BigInt(record.requestedAt),
+          payloadJson: JSON.stringify(record.payload),
+          responseJson:
+            record.response == null ? null : JSON.stringify(record.response),
+        },
+        update: {},
+      })
+    },
+    async resolve(interruptId, response) {
+      await prisma.interrupt.updateMany({
+        where: { interruptId },
+        data: {
+          status: 'resolved',
+          resolvedAt: BigInt(Date.now()),
+          responseJson: response == null ? null : JSON.stringify(response),
+        },
+      })
+    },
+    async cancel(interruptId) {
+      await prisma.interrupt.updateMany({
+        where: { interruptId },
+        data: { status: 'cancelled', resolvedAt: BigInt(Date.now()) },
+      })
+    },
+    async get(interruptId) {
+      const row = await prisma.interrupt.findUnique({ where: { interruptId } })
+      return row ? mapInterrupt(row) : null
+    },
+    async list(threadId) {
+      const rows = await prisma.interrupt.findMany({
+        where: { threadId },
+        orderBy: { requestedAt: 'asc' },
+      })
+      return rows.map(mapInterrupt)
+    },
+    async listPending(threadId) {
+      const rows = await prisma.interrupt.findMany({
+        where: { threadId, status: 'pending' },
+        orderBy: { requestedAt: 'asc' },
+      })
+      return rows.map(mapInterrupt)
+    },
+    async listByRun(runId) {
+      const rows = await prisma.interrupt.findMany({
+        where: { runId },
+        orderBy: { requestedAt: 'asc' },
+      })
+      return rows.map(mapInterrupt)
+    },
+    async listPendingByRun(runId) {
+      const rows = await prisma.interrupt.findMany({
+        where: { runId, status: 'pending' },
+        orderBy: { requestedAt: 'asc' },
+      })
+      return rows.map(mapInterrupt)
+    },
+  }
+}
+
+export function createMetadataStore(prisma: PrismaClient): MetadataStore {
+  return {
+    async get(scope, key) {
+      const row = await prisma.metadata.findUnique({
+        where: { scope_key: { scope, key } },
+      })
+      return row ? (JSON.parse(row.valueJson) as unknown) : null
+    },
+    async set(scope, key, value) {
+      const valueJson = JSON.stringify(value)
+      await prisma.metadata.upsert({
+        where: { scope_key: { scope, key } },
+        create: { scope, key, valueJson },
+        update: { valueJson },
+      })
+    },
+    async delete(scope, key) {
+      await prisma.metadata.deleteMany({ where: { scope, key } })
+    },
+  }
+}
+
+interface ArtifactRow {
+  artifactId: string
+  runId: string
+  threadId: string
+  name: string
+  mimeType: string
+  size: bigint
+  externalUrl: string | null
+  createdAt: bigint
+}
+
+function mapArtifact(row: ArtifactRow): ArtifactRecord {
+  return {
+    artifactId: row.artifactId,
+    runId: row.runId,
+    threadId: row.threadId,
+    name: row.name,
+    mimeType: row.mimeType,
+    size: Number(row.size),
+    ...(row.externalUrl != null ? { externalUrl: row.externalUrl } : {}),
+    createdAt: Number(row.createdAt),
+  }
+}
+
+export function createArtifactStore(prisma: PrismaClient): ArtifactStore {
+  return {
+    async save(record) {
+      const data = {
+        runId: record.runId,
+        threadId: record.threadId,
+        name: record.name,
+        mimeType: record.mimeType,
+        size: BigInt(record.size),
+        externalUrl: record.externalUrl ?? null,
+        createdAt: BigInt(record.createdAt),
+      }
+      await prisma.artifact.upsert({
+        where: { artifactId: record.artifactId },
+        create: { artifactId: record.artifactId, ...data },
+        update: data,
+      })
+    },
+    async get(artifactId) {
+      const row = await prisma.artifact.findUnique({ where: { artifactId } })
+      return row ? mapArtifact(row) : null
+    },
+    async list(runId) {
+      const rows = await prisma.artifact.findMany({
+        where: { runId },
+        orderBy: [{ createdAt: 'asc' }, { artifactId: 'asc' }],
+      })
+      return rows.map(mapArtifact)
+    },
+    async delete(artifactId) {
+      await prisma.artifact.deleteMany({ where: { artifactId } })
+    },
+    async deleteForRun(runId) {
+      await prisma.artifact.deleteMany({ where: { runId } })
+    },
+  }
+}
+
+interface BlobRow {
+  key: string
+  contentType: string | null
+  size: bigint | null
+  etag: string | null
+  customMetadataJson: string | null
+  createdAt: bigint | null
+  updatedAt: bigint | null
+  body: Uint8Array | null
+}
+
+function blobRecordSnapshot(row: BlobRow): BlobRecord {
+  return {
+    key: row.key,
+    ...(row.size != null ? { size: Number(row.size) } : {}),
+    ...(row.etag != null ? { etag: row.etag } : {}),
+    ...(row.contentType != null ? { contentType: row.contentType } : {}),
+    ...(row.customMetadataJson != null
+      ? {
+          customMetadata: JSON.parse(row.customMetadataJson) as Record<
+            string,
+            string
+          >,
+        }
+      : {}),
+    ...(row.createdAt != null ? { createdAt: Number(row.createdAt) } : {}),
+    ...(row.updatedAt != null ? { updatedAt: Number(row.updatedAt) } : {}),
+  }
+}
+
+function blobObject(row: BlobRow): BlobObject {
+  const bytes = row.body
+    ? copyBytes(new Uint8Array(row.body))
+    : new Uint8Array()
+  return {
+    ...blobRecordSnapshot(row),
+    body: new ReadableStream<Uint8Array>({
+      start(controller) {
+        controller.enqueue(copyBytes(bytes))
+        controller.close()
+      },
+    }),
+    arrayBuffer: () => Promise.resolve(bytesToArrayBuffer(bytes)),
+    text: () => Promise.resolve(textDecoder.decode(bytes)),
+  }
+}
+
+export function createBlobStore(prisma: PrismaClient): BlobStore {
+  const readRow = (key: string): Promise<BlobRow | null> =>
+    prisma.blob.findUnique({ where: { key } })
+  return {
+    async put(key, body, options) {
+      const bytes = await bytesFromBlobBody(body)
+      const existing = await readRow(key)
+      const now = Date.now()
+      const contentType =
+        options?.contentType ??
+        (typeof Blob !== 'undefined' && body instanceof Blob
+          ? body.type || undefined
+          : undefined)
+      const customMetadata = options?.customMetadata
+        ? { ...options.customMetadata }
+        : undefined
+      const record = {
+        contentType: contentType ?? null,
+        size: BigInt(bytes.byteLength),
+        etag: crypto.randomUUID(),
+        customMetadataJson: customMetadata
+          ? JSON.stringify(customMetadata)
+          : null,
+        createdAt: existing?.createdAt ?? BigInt(now),
+        updatedAt: BigInt(now),
+        body: Buffer.from(bytes),
+      }
+      const stored = await prisma.blob.upsert({
+        where: { key },
+        create: { key, ...record },
+        update: record,
+      })
+      return blobRecordSnapshot(stored)
+    },
+    async get(key) {
+      const row = await readRow(key)
+      return row ? blobObject(row) : null
+    },
+    async head(key) {
+      const row = await readRow(key)
+      return row ? blobRecordSnapshot(row) : null
+    },
+    async delete(key) {
+      await prisma.blob.deleteMany({ where: { key } })
+    },
+    async list(options?: BlobListOptions): Promise<BlobListPage> {
+      const limit = options?.limit
+      if (limit === 0) return { objects: [], truncated: false }
+      const prefix = options?.prefix ?? ''
+      // Match the prefix LITERALLY and case-sensitively to mirror the reference
+      // in-memory backend's `key.startsWith(prefix)`. Prisma's `startsWith`
+      // compiles to a SQL `LIKE` on sqlite, which treats `_`/`%` in the prefix
+      // as wildcards and matches case-insensitively for ASCII. Instead use a
+      // half-open range on the (BINARY-collated) key column — `key >= prefix AND
+      // key < upperBound` — which contains no LIKE metacharacters and relies on
+      // binary/byte ordering, giving literal, case-sensitive matching.
+      const upperBound = prefixUpperBound(prefix)
+      const rows = await prisma.blob.findMany({
+        where: {
+          key: {
+            gte: prefix,
+            ...(upperBound !== undefined ? { lt: upperBound } : {}),
+            ...(options?.cursor !== undefined ? { gt: options.cursor } : {}),
+          },
+        },
+        orderBy: { key: 'asc' },
+        ...(limit === undefined ? {} : { take: limit + 1 }),
+      })
+      const pageRows = limit === undefined ? rows : rows.slice(0, limit)
+      const objects = pageRows.map(blobRecordSnapshot)
+      const truncated = limit !== undefined && rows.length > limit
+      return {
+        objects,
+        ...(truncated ? { cursor: pageRows.at(-1)?.key, truncated } : {}),
+      }
+    },
+  }
+}
diff --git a/packages/ai-persistence-prisma/tests/prisma.conformance.test.ts b/packages/ai-persistence-prisma/tests/prisma.conformance.test.ts
new file mode 100644
index 000000000..65215b637
--- /dev/null
+++ b/packages/ai-persistence-prisma/tests/prisma.conformance.test.ts
@@ -0,0 +1,62 @@
+import { readFile, readdir } from 'node:fs/promises'
+import { mkdtempSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { afterAll } from 'vitest'
+import { PrismaClient } from '@prisma/client'
+import { runPersistenceConformance } from '@tanstack/ai-persistence/testkit'
+import { prismaPersistence } from '../src/index'
+
+const migrationsDir = fileURLToPath(
+  new URL('../prisma/migrations', import.meta.url),
+)
+
+const clients: Array<PrismaClient> = []
+
+/** Read every generated migration's DDL, in journal order, as raw statements. */
+async function migrationStatements(): Promise<Array<string>> {
+  const entries = await readdir(migrationsDir, { withFileTypes: true })
+  const dirs = entries
+    .filter((entry) => entry.isDirectory())
+    .map((entry) => entry.name)
+    .sort()
+  const statements: Array<string> = []
+  for (const dir of dirs) {
+    const sql = await readFile(
+      join(migrationsDir, dir, 'migration.sql'),
+      'utf8',
+    )
+    for (const raw of sql.split(';')) {
+      const statement = raw
+        .split('\n')
+        .filter((line) => !line.trimStart().startsWith('--'))
+        .join('\n')
+        .trim()
+      if (statement) statements.push(statement)
+    }
+  }
+  return statements
+}
+
+/** Create a PrismaClient over a fresh temp sqlite file with migrations applied. */
+async function makeTestClient(): Promise<PrismaClient> {
+  const dir = mkdtempSync(join(tmpdir(), 'tanstack-ai-prisma-'))
+  const dbPath = join(dir, 'state.db').replace(/\\/g, '/')
+  const prisma = new PrismaClient({
+    datasources: { db: { url: `file:${dbPath}` } },
+  })
+  clients.push(prisma)
+  for (const statement of await migrationStatements()) {
+    await prisma.$executeRawUnsafe(statement)
+  }
+  return prisma
+}
+
+afterAll(async () => {
+  await Promise.all(clients.map((client) => client.$disconnect()))
+})
+
+runPersistenceConformance('prisma', async () =>
+  prismaPersistence(await makeTestClient()),
+)
diff --git a/packages/ai-persistence-prisma/tsconfig.json b/packages/ai-persistence-prisma/tsconfig.json
new file mode 100644
index 000000000..c38689f4e
--- /dev/null
+++ b/packages/ai-persistence-prisma/tsconfig.json
@@ -0,0 +1,8 @@
+{
+  "extends": "../../tsconfig.base.json",
+  "compilerOptions": {
+    "outDir": "dist"
+  },
+  "include": ["src", "tests"],
+  "exclude": ["node_modules", "dist"]
+}
diff --git a/packages/ai-persistence-prisma/vite.config.ts b/packages/ai-persistence-prisma/vite.config.ts
new file mode 100644
index 000000000..11f5b20b7
--- /dev/null
+++ b/packages/ai-persistence-prisma/vite.config.ts
@@ -0,0 +1,37 @@
+import { defineConfig, mergeConfig } from 'vitest/config'
+import { tanstackViteConfig } from '@tanstack/vite-config'
+import packageJson from './package.json'
+
+const config = defineConfig({
+  test: {
+    name: packageJson.name,
+    dir: './',
+    watch: false,
+
+    globals: true,
+    environment: 'node',
+    include: ['tests/**/*.test.ts'],
+    coverage: {
+      provider: 'v8',
+      reporter: ['text', 'json', 'html', 'lcov'],
+      exclude: [
+        'node_modules/',
+        'dist/',
+        'tests/',
+        '**/*.test.ts',
+        '**/*.config.ts',
+        '**/types.ts',
+      ],
+      include: ['src/**/*.ts'],
+    },
+  },
+})
+
+export default mergeConfig(
+  config,
+  tanstackViteConfig({
+    entry: ['./src/index.ts'],
+    srcDir: './src',
+    cjs: false,
+  }),
+)
diff --git a/packages/ai-persistence/package.json b/packages/ai-persistence/package.json
new file mode 100644
index 000000000..e76fc9f7f
--- /dev/null
+++ b/packages/ai-persistence/package.json
@@ -0,0 +1,68 @@
+{
+  "name": "@tanstack/ai-persistence",
+  "version": "0.1.0",
+  "description": "Headless AIPersistence layer for TanStack AI — durable runs, message history, append-only AG-UI public events, interrupts, artifacts, and resumable runs as composable middleware (withChatPersistence, withGenerationPersistence, defineAIPersistence, memoryPersistence; defineChatPersistence is deprecated compatibility).",
+  "author": "",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/TanStack/ai.git",
+    "directory": "packages/ai-persistence"
+  },
+  "keywords": [
+    "ai",
+    "ai-sdk",
+    "typescript",
+    "tanstack",
+    "persistence",
+    "durable",
+    "resume",
+    "event-log",
+    "chat-history",
+    "ag-ui"
+  ],
+  "type": "module",
+  "module": "./dist/esm/index.js",
+  "types": "./dist/esm/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/esm/index.d.ts",
+      "import": "./dist/esm/index.js"
+    },
+    "./testkit": {
+      "types": "./dist/esm/testkit/conformance.d.ts",
+      "import": "./dist/esm/testkit/conformance.js"
+    }
+  },
+  "files": [
+    "dist",
+    "src"
+  ],
+  "scripts": {
+    "build": "vite build",
+    "clean": "premove ./build ./dist",
+    "lint:fix": "eslint ./src --fix",
+    "test:build": "publint --strict",
+    "test:eslint": "eslint ./src",
+    "test:lib": "vitest",
+    "test:lib:dev": "pnpm test:lib --watch",
+    "test:types": "tsc"
+  },
+  "dependencies": {
+    "@tanstack/ai-utils": "workspace:*"
+  },
+  "peerDependencies": {
+    "@tanstack/ai": "workspace:^",
+    "vitest": "^4.0.14"
+  },
+  "peerDependenciesMeta": {
+    "vitest": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@tanstack/ai": "workspace:*",
+    "@vitest/coverage-v8": "4.0.14",
+    "vitest": "^4.0.14"
+  }
+}
diff --git a/packages/ai-persistence/src/capabilities.ts b/packages/ai-persistence/src/capabilities.ts
new file mode 100644
index 000000000..b1673a4ab
--- /dev/null
+++ b/packages/ai-persistence/src/capabilities.ts
@@ -0,0 +1,23 @@
+/**
+ * Persistence capability tokens.
+ *
+ * `withChatPersistence` PROVIDES these so later middleware (and harness adapters)
+ * can read durable state. `LocksCapability` is re-exported from core
+ * (`@tanstack/ai`) — a shared, single-owner token owned with the sandbox layer.
+ */
+import { createCapability } from '@tanstack/ai'
+import type { AIPersistence, InterruptStore } from './types'
+
+export const PersistenceCapability =
+  createCapability<AIPersistence>()('persistence')
+
+export const InterruptsCapability = createCapability<InterruptStore>()(
+  'persistence.interrupts',
+)
+
+export const [getPersistence, providePersistence] = PersistenceCapability
+export const [getInterrupts, provideInterrupts] = InterruptsCapability
+
+// Shared, single-owner tokens live in core; re-export so consumers import
+// everything persistence-related from this package.
+export { LocksCapability, getLocks, provideLocks } from '@tanstack/ai'
diff --git a/packages/ai-persistence/src/index.ts b/packages/ai-persistence/src/index.ts
new file mode 100644
index 000000000..8cc98ebe4
--- /dev/null
+++ b/packages/ai-persistence/src/index.ts
@@ -0,0 +1,63 @@
+// Store contracts + aggregate
+export {
+  defineAIPersistence,
+  defineChatPersistence,
+  validatePersistenceFeatures,
+} from './types'
+export type {
+  PersistenceMode,
+  PersistenceFeature,
+  MessageStore,
+  RunStatus,
+  RunRecord,
+  RunStore,
+  InterruptRecord,
+  InterruptStore,
+  MetadataStore,
+  ArtifactRecord,
+  ArtifactStore,
+  BlobBody,
+  BlobRecord,
+  BlobObject,
+  BlobListPage,
+  BlobPutOptions,
+  BlobListOptions,
+  BlobStore,
+  AIPersistence,
+  ChatPersistence,
+} from './types'
+
+// Middleware
+export { withChatPersistence, withGenerationPersistence } from './middleware'
+export type {
+  GenerationArtifactDescriptor,
+  GenerationArtifactExtractionInput,
+  GenerationArtifactNameInput,
+  WithPersistenceOptions,
+} from './middleware'
+
+export type {
+  PersistedArtifactActivity,
+  PersistedArtifactRef,
+  PersistedArtifactRole,
+} from '@tanstack/ai'
+
+// Reference in-memory implementation
+export { memoryPersistence } from './memory'
+
+// Interrupt controller
+export { createInterruptController } from './interrupts'
+export type { InterruptController } from './interrupts'
+
+// Capabilities (incl. re-exported core Locks token)
+export {
+  PersistenceCapability,
+  InterruptsCapability,
+  getPersistence,
+  providePersistence,
+  getInterrupts,
+  provideInterrupts,
+  LocksCapability,
+  getLocks,
+  provideLocks,
+} from './capabilities'
diff --git a/packages/ai-persistence/src/interrupts.ts b/packages/ai-persistence/src/interrupts.ts
new file mode 100644
index 000000000..fdc39c084
--- /dev/null
+++ b/packages/ai-persistence/src/interrupts.ts
@@ -0,0 +1,28 @@
+import type { InterruptRecord, InterruptStore } from './types'
+
+export interface InterruptController {
+  resolve: (interruptId: string, response?: unknown) => Promise<void>
+  cancel: (interruptId: string) => Promise<void>
+  request: (
+    record: Omit<InterruptRecord, 'status' | 'resolvedAt'>,
+  ) => Promise<void>
+  listPending: (threadId: string) => Promise<Array<InterruptRecord>>
+  listPendingByRun: (runId: string) => Promise<Array<InterruptRecord>>
+}
+
+export function createInterruptController(opts: {
+  store: InterruptStore
+}): InterruptController {
+  const { store } = opts
+  return {
+    resolve: (interruptId, response) => store.resolve(interruptId, response),
+    cancel: (interruptId) => store.cancel(interruptId),
+    request: (record) =>
+      store.create({
+        ...record,
+        status: 'pending',
+      }),
+    listPending: (threadId) => store.listPending(threadId),
+    listPendingByRun: (runId) => store.listPendingByRun(runId),
+  }
+}
diff --git a/packages/ai-persistence/src/memory.ts b/packages/ai-persistence/src/memory.ts
new file mode 100644
index 000000000..be711e535
--- /dev/null
+++ b/packages/ai-persistence/src/memory.ts
@@ -0,0 +1,354 @@
+import { InMemoryLockStore } from '@tanstack/ai'
+import { defineAIPersistence } from './types'
+import type { ModelMessage } from '@tanstack/ai'
+import type {
+  AIPersistence,
+  ArtifactRecord,
+  ArtifactStore,
+  BlobBody,
+  BlobListOptions,
+  BlobObject,
+  BlobRecord,
+  BlobStore,
+  InterruptRecord,
+  InterruptStore,
+  MessageStore,
+  MetadataStore,
+  RunRecord,
+  RunStore,
+} from './types'
+
+class MemoryMessageStore implements MessageStore {
+  private readonly threads = new Map<string, Array<ModelMessage>>()
+  loadThread(threadId: string): Promise<Array<ModelMessage>> {
+    return Promise.resolve(this.threads.get(threadId)?.slice() ?? [])
+  }
+  saveThread(threadId: string, messages: Array<ModelMessage>): Promise<void> {
+    this.threads.set(threadId, messages.slice())
+    return Promise.resolve()
+  }
+}
+
+class MemoryRunStore implements RunStore {
+  private readonly runs = new Map<string, RunRecord>()
+  createOrResume(input: {
+    runId: string
+    threadId: string
+    status?: RunRecord['status']
+    startedAt: number
+  }): Promise<RunRecord> {
+    const existing = this.runs.get(input.runId)
+    if (existing) return Promise.resolve(existing)
+    const record: RunRecord = {
+      runId: input.runId,
+      threadId: input.threadId,
+      status: input.status ?? 'running',
+      startedAt: input.startedAt,
+    }
+    this.runs.set(record.runId, record)
+    return Promise.resolve(record)
+  }
+  update(
+    runId: string,
+    patch: Partial<
+      Pick<RunRecord, 'status' | 'finishedAt' | 'error' | 'usage'>
+    >,
+  ): Promise<void> {
+    const existing = this.runs.get(runId)
+    if (existing) this.runs.set(runId, { ...existing, ...patch })
+    return Promise.resolve()
+  }
+  get(runId: string): Promise<RunRecord | null> {
+    return Promise.resolve(this.runs.get(runId) ?? null)
+  }
+}
+
+class MemoryInterruptStore implements InterruptStore {
+  private readonly interrupts = new Map<string, InterruptRecord>()
+  create(record: Omit<InterruptRecord, 'resolvedAt'>): Promise<void> {
+    this.interrupts.set(record.interruptId, { ...record })
+    return Promise.resolve()
+  }
+  resolve(interruptId: string, response?: unknown): Promise<void> {
+    const existing = this.interrupts.get(interruptId)
+    if (existing) {
+      this.interrupts.set(interruptId, {
+        ...existing,
+        status: 'resolved',
+        resolvedAt: Date.now(),
+        response,
+      })
+    }
+    return Promise.resolve()
+  }
+  cancel(interruptId: string): Promise<void> {
+    const existing = this.interrupts.get(interruptId)
+    if (existing) {
+      this.interrupts.set(interruptId, {
+        ...existing,
+        status: 'cancelled',
+        resolvedAt: Date.now(),
+      })
+    }
+    return Promise.resolve()
+  }
+  get(interruptId: string): Promise<InterruptRecord | null> {
+    return Promise.resolve(this.interrupts.get(interruptId) ?? null)
+  }
+  list(threadId: string): Promise<Array<InterruptRecord>> {
+    return Promise.resolve(
+      [...this.interrupts.values()].filter(
+        (interrupt) => interrupt.threadId === threadId,
+      ),
+    )
+  }
+  listPending(threadId: string): Promise<Array<InterruptRecord>> {
+    return Promise.resolve(
+      [...this.interrupts.values()].filter(
+        (interrupt) =>
+          interrupt.threadId === threadId && interrupt.status === 'pending',
+      ),
+    )
+  }
+  listByRun(runId: string): Promise<Array<InterruptRecord>> {
+    return Promise.resolve(
+      [...this.interrupts.values()].filter(
+        (interrupt) => interrupt.runId === runId,
+      ),
+    )
+  }
+  listPendingByRun(runId: string): Promise<Array<InterruptRecord>> {
+    return Promise.resolve(
+      [...this.interrupts.values()].filter(
+        (interrupt) =>
+          interrupt.runId === runId && interrupt.status === 'pending',
+      ),
+    )
+  }
+}
+
+class MemoryMetadataStore implements MetadataStore {
+  private readonly values = new Map<string, unknown>()
+  get(scope: string, key: string): Promise<unknown | null> {
+    const storageKey = `${scope}:${key}`
+    return Promise.resolve(
+      this.values.has(storageKey) ? this.values.get(storageKey) : null,
+    )
+  }
+  set(scope: string, key: string, value: unknown): Promise<void> {
+    this.values.set(`${scope}:${key}`, value)
+    return Promise.resolve()
+  }
+  delete(scope: string, key: string): Promise<void> {
+    this.values.delete(`${scope}:${key}`)
+    return Promise.resolve()
+  }
+}
+
+class MemoryArtifactStore implements ArtifactStore {
+  private readonly artifacts = new Map<string, ArtifactRecord>()
+  save(record: ArtifactRecord): Promise<void> {
+    this.artifacts.set(record.artifactId, { ...record })
+    return Promise.resolve()
+  }
+  get(artifactId: string): Promise<ArtifactRecord | null> {
+    return Promise.resolve(this.artifacts.get(artifactId) ?? null)
+  }
+  list(runId: string): Promise<Array<ArtifactRecord>> {
+    return Promise.resolve(
+      [...this.artifacts.values()].filter((a) => a.runId === runId),
+    )
+  }
+  delete(artifactId: string): Promise<void> {
+    this.artifacts.delete(artifactId)
+    return Promise.resolve()
+  }
+  deleteForRun(runId: string): Promise<void> {
+    for (const artifact of this.artifacts.values()) {
+      if (artifact.runId === runId) this.artifacts.delete(artifact.artifactId)
+    }
+    return Promise.resolve()
+  }
+}
+
+interface MemoryBlobEntry {
+  record: BlobRecord
+  bytes: Uint8Array
+}
+
+const textEncoder = new TextEncoder()
+const textDecoder = new TextDecoder()
+
+function copyBytes(bytes: Uint8Array): Uint8Array {
+  return new Uint8Array(bytes)
+}
+
+function bytesToArrayBuffer(bytes: Uint8Array): ArrayBuffer {
+  const buffer = new ArrayBuffer(bytes.byteLength)
+  new Uint8Array(buffer).set(bytes)
+  return buffer
+}
+
+async function bytesFromStream(
+  stream: ReadableStream<Uint8Array>,
+): Promise<Uint8Array> {
+  const reader = stream.getReader()
+  const chunks: Array<Uint8Array> = []
+  let total = 0
+  try {
+    // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition
+    while (true) {
+      const { done, value } = await reader.read()
+      if (done) break
+      chunks.push(copyBytes(value))
+      total += value.byteLength
+    }
+  } finally {
+    reader.releaseLock()
+  }
+
+  const bytes = new Uint8Array(total)
+  let offset = 0
+  for (const chunk of chunks) {
+    bytes.set(chunk, offset)
+    offset += chunk.byteLength
+  }
+  return bytes
+}
+
+async function bytesFromBlobBody(body: BlobBody): Promise<Uint8Array> {
+  if (typeof body === 'string') {
+    return textEncoder.encode(body)
+  }
+  if (body instanceof ArrayBuffer) {
+    return new Uint8Array(body.slice(0))
+  }
+  if (ArrayBuffer.isView(body)) {
+    return copyBytes(
+      new Uint8Array(body.buffer, body.byteOffset, body.byteLength),
+    )
+  }
+  if (typeof Blob !== 'undefined' && body instanceof Blob) {
+    return new Uint8Array(await body.arrayBuffer())
+  }
+  if (typeof ReadableStream !== 'undefined' && body instanceof ReadableStream) {
+    return bytesFromStream(body)
+  }
+  throw new TypeError('Unsupported blob body.')
+}
+
+function blobRecordSnapshot(record: BlobRecord): BlobRecord {
+  return {
+    ...record,
+    ...(record.customMetadata
+      ? { customMetadata: { ...record.customMetadata } }
+      : {}),
+  }
+}
+
+function blobObject(record: BlobRecord, bytes: Uint8Array): BlobObject {
+  const copied = copyBytes(bytes)
+  return {
+    ...blobRecordSnapshot(record),
+    body: new ReadableStream<Uint8Array>({
+      start(controller) {
+        controller.enqueue(copyBytes(copied))
+        controller.close()
+      },
+    }),
+    arrayBuffer: () => Promise.resolve(bytesToArrayBuffer(copied)),
+    text: () => Promise.resolve(textDecoder.decode(copied)),
+  }
+}
+
+class MemoryBlobStore implements BlobStore {
+  private readonly blobs = new Map<string, MemoryBlobEntry>()
+  private nextEtag = 1
+
+  async put(
+    key: string,
+    body: BlobBody,
+    options?: {
+      contentType?: string
+      customMetadata?: Record<string, string>
+    },
+  ): Promise<BlobRecord> {
+    const bytes = await bytesFromBlobBody(body)
+    const existing = this.blobs.get(key)
+    const now = Date.now()
+    const record: BlobRecord = {
+      key,
+      size: bytes.byteLength,
+      etag: String(this.nextEtag++),
+      contentType:
+        options?.contentType ??
+        (typeof Blob !== 'undefined' && body instanceof Blob
+          ? body.type || undefined
+          : undefined),
+      customMetadata: options?.customMetadata
+        ? { ...options.customMetadata }
+        : undefined,
+      createdAt: existing?.record.createdAt ?? now,
+      updatedAt: now,
+    }
+    this.blobs.set(key, { record, bytes: copyBytes(bytes) })
+    return blobRecordSnapshot(record)
+  }
+
+  get(key: string): Promise<BlobObject | null> {
+    const entry = this.blobs.get(key)
+    return Promise.resolve(entry ? blobObject(entry.record, entry.bytes) : null)
+  }
+
+  head(key: string): Promise<BlobRecord | null> {
+    const entry = this.blobs.get(key)
+    return Promise.resolve(entry ? blobRecordSnapshot(entry.record) : null)
+  }
+
+  delete(key: string): Promise<void> {
+    this.blobs.delete(key)
+    return Promise.resolve()
+  }
+
+  list(options?: BlobListOptions): Promise<{
+    objects: Array<BlobRecord>
+    cursor?: string
+    truncated?: boolean
+  }> {
+    const limit = options?.limit
+    if (limit === 0) {
+      return Promise.resolve({ objects: [], truncated: false })
+    }
+    const keys = [...this.blobs.keys()]
+      .filter((key) => key.startsWith(options?.prefix ?? ''))
+      .filter((key) => options?.cursor === undefined || key > options.cursor)
+      .sort()
+    const pageKeys = limit === undefined ? keys : keys.slice(0, limit)
+    const objects = pageKeys.map((key) => {
+      const blob = this.blobs.get(key)
+      if (blob === undefined) {
+        throw new Error(`Missing blob for listed key: ${key}`)
+      }
+      return blobRecordSnapshot(blob.record)
+    })
+    const truncated = limit !== undefined && keys.length > limit
+    return Promise.resolve({
+      objects,
+      ...(truncated ? { cursor: pageKeys.at(-1), truncated } : {}),
+    })
+  }
+}
+
+export function memoryPersistence(): AIPersistence {
+  return defineAIPersistence({
+    stores: {
+      messages: new MemoryMessageStore(),
+      runs: new MemoryRunStore(),
+      interrupts: new MemoryInterruptStore(),
+      metadata: new MemoryMetadataStore(),
+      artifacts: new MemoryArtifactStore(),
+      blobs: new MemoryBlobStore(),
+      locks: new InMemoryLockStore(),
+    },
+  })
+}
diff --git a/packages/ai-persistence/src/middleware.ts b/packages/ai-persistence/src/middleware.ts
new file mode 100644
index 000000000..ea55ffb42
--- /dev/null
+++ b/packages/ai-persistence/src/middleware.ts
@@ -0,0 +1,961 @@
+import { defineChatMiddleware } from '@tanstack/ai'
+import { base64ToUint8Array } from '@tanstack/ai-utils'
+import {
+  InterruptsCapability,
+  LocksCapability,
+  PersistenceCapability,
+  provideInterrupts,
+  provideLocks,
+  providePersistence,
+} from './capabilities'
+import { validatePersistenceFeatures } from './types'
+import type {
+  AbortInfo,
+  ChatMiddleware,
+  ChatMiddlewareConfig,
+  ChatMiddlewareContext,
+  ChatResumeToolState,
+  ErrorInfo,
+  FinishInfo,
+  GenerationAbortInfo,
+  GenerationErrorInfo,
+  GenerationFinishInfo,
+  GenerationMiddleware,
+  GenerationMiddlewareContext,
+  PersistedArtifactActivity,
+  PersistedArtifactRef,
+  PersistedArtifactRole,
+  RunAgentResumeItem,
+  StreamChunk,
+  TokenUsage,
+} from '@tanstack/ai'
+import type {
+  AIPersistence,
+  ArtifactRecord,
+  BlobBody,
+  InterruptRecord,
+  PersistenceFeature,
+  RunStore,
+} from './types'
+
+export interface WithPersistenceOptions {
+  features?: Array<PersistenceFeature>
+  extractArtifacts?: (
+    input: GenerationArtifactExtractionInput,
+  ) =>
+    | Array<GenerationArtifactDescriptor | PersistedArtifactRef>
+    | Promise<Array<GenerationArtifactDescriptor | PersistedArtifactRef>>
+  nameArtifact?: (input: GenerationArtifactNameInput) => string
+}
+
+export interface GenerationArtifactDescriptor {
+  role: PersistedArtifactRole
+  path: string
+  mediaType?: PersistedArtifactRef['source']['mediaType']
+  mimeType?: string
+  bytes?: BlobBody
+  url?: string
+  json?: unknown
+  name?: string
+  jobId?: string
+  expiresAt?: string | Date
+}
+
+export interface GenerationArtifactExtractionInput {
+  activity: PersistedArtifactActivity
+  provider: string
+  model: string
+  threadId: string
+  runId: string
+  inputs: unknown
+  result: unknown
+}
+
+export interface GenerationArtifactNameInput {
+  descriptor: GenerationArtifactDescriptor
+  activity: PersistedArtifactActivity
+  provider: string
+  model: string
+  threadId: string
+  runId: string
+  index: number
+}
+
+const runState = new WeakMap<
+  object,
+  { merged: boolean; interrupted: boolean }
+>()
+
+function defaultFeatures(
+  persistence: AIPersistence,
+): Array<PersistenceFeature> {
+  const features: Array<PersistenceFeature> = []
+  if (persistence.stores.messages) features.push('messages')
+  if (persistence.stores.runs && persistence.stores.interrupts) {
+    features.push('interrupts')
+  }
+  if (persistence.stores.metadata) features.push('metadata')
+  if (persistence.stores.locks) features.push('locks')
+  if (persistence.stores.artifacts && persistence.stores.blobs) {
+    features.push('artifacts', 'blobs')
+  }
+  return features
+}
+
+const validResumeStatuses = new Set(['resolved', 'cancelled'])
+
+function validatePendingResumes(
+  pending: Array<InterruptRecord>,
+  resume: Array<RunAgentResumeItem> | undefined,
+): Map<string, RunAgentResumeItem> {
+  const pendingInterruptIds = new Set(
+    pending.map((interrupt) => interrupt.interruptId),
+  )
+  const resumeByInterruptId = new Map(
+    (resume ?? []).map((entry) => [entry.interruptId, entry]),
+  )
+  if (pending.length === 0) {
+    const staleEntry = resume?.[0]
+    if (staleEntry) {
+      throw new Error(
+        `Resume entry references non-pending interrupt ${staleEntry.interruptId}.`,
+      )
+    }
+    return resumeByInterruptId
+  }
+  if (!resume || resume.length === 0) {
+    throw new Error(
+      `Thread has pending interrupts; resume is required before accepting new input.`,
+    )
+  }
+
+  for (const interrupt of pending) {
+    const entry = resumeByInterruptId.get(interrupt.interruptId)
+    if (!entry) {
+      throw new Error(
+        `Missing resume entry for pending interrupt ${interrupt.interruptId}.`,
+      )
+    }
+    if (!validResumeStatuses.has(entry.status)) {
+      throw new Error(
+        `Invalid resume status for pending interrupt ${interrupt.interruptId}: ${entry.status}.`,
+      )
+    }
+  }
+  for (const entry of resume) {
+    if (!pendingInterruptIds.has(entry.interruptId)) {
+      throw new Error(
+        `Resume entry references non-pending interrupt ${entry.interruptId}.`,
+      )
+    }
+  }
+  return resumeByInterruptId
+}
+
+async function applyPendingResumes(
+  pending: Array<InterruptRecord>,
+  resumeByInterruptId: Map<string, RunAgentResumeItem>,
+  interrupts: NonNullable<AIPersistence['stores']['interrupts']>,
+): Promise<void> {
+  for (const interrupt of pending) {
+    const entry = resumeByInterruptId.get(interrupt.interruptId)
+    if (!entry) continue
+    if (entry.status === 'resolved') {
+      await interrupts.resolve(interrupt.interruptId, entry.payload)
+    } else {
+      await interrupts.cancel(interrupt.interruptId)
+    }
+  }
+}
+
+function objectValue(value: unknown): Record<string, unknown> | null {
+  return value && typeof value === 'object'
+    ? (value as Record<string, unknown>)
+    : null
+}
+
+function stringField(
+  value: Record<string, unknown>,
+  key: string,
+): string | undefined {
+  return typeof value[key] === 'string' ? value[key] : undefined
+}
+
+function interruptKind(interrupt: InterruptRecord): string | undefined {
+  const metadata = objectValue(interrupt.payload.metadata)
+  return metadata ? stringField(metadata, 'kind') : undefined
+}
+
+function resolvedApprovalDecision(entry: RunAgentResumeItem): boolean {
+  if (entry.status === 'cancelled') return false
+  const payload = objectValue(entry.payload)
+  return typeof payload?.approved === 'boolean' ? payload.approved : true
+}
+
+function resumeToolStateFromPending(
+  pending: Array<InterruptRecord>,
+  resumeByInterruptId: Map<string, RunAgentResumeItem>,
+): ChatResumeToolState | undefined {
+  const approvals = new Map<string, boolean>()
+  const clientToolResults = new Map<string, unknown>()
+
+  for (const interrupt of pending) {
+    const entry = resumeByInterruptId.get(interrupt.interruptId)
+    if (!entry) continue
+
+    const kind = interruptKind(interrupt)
+    const reason = stringField(interrupt.payload, 'reason')
+    const toolCallId = stringField(interrupt.payload, 'toolCallId')
+
+    if (kind === 'approval' || reason === 'approval_required') {
+      approvals.set(interrupt.interruptId, resolvedApprovalDecision(entry))
+      continue
+    }
+
+    if (
+      entry.status === 'resolved' &&
+      toolCallId &&
+      (kind === 'client_tool' || reason === 'client_tool_input')
+    ) {
+      clientToolResults.set(toolCallId, entry.payload)
+    }
+  }
+
+  if (approvals.size === 0 && clientToolResults.size === 0) return undefined
+  return { approvals, clientToolResults }
+}
+
+function interruptPayload(interrupt: unknown): Record<string, unknown> {
+  return interrupt && typeof interrupt === 'object'
+    ? { ...(interrupt as Record<string, unknown>) }
+    : { value: interrupt }
+}
+
+function isArtifactRef(value: unknown): value is PersistedArtifactRef {
+  const record = objectValue(value)
+  return !!record && typeof record.artifactId === 'string'
+}
+
+function mediaActivity(
+  activity: GenerationMiddlewareContext['activity'],
+): PersistedArtifactActivity | undefined {
+  return activity === 'image' ||
+    activity === 'audio' ||
+    activity === 'tts' ||
+    activity === 'video' ||
+    activity === 'transcription'
+    ? activity
+    : undefined
+}
+
+function parseDataUrl(
+  value: string,
+): { mimeType: string; bytes: Uint8Array } | undefined {
+  const match = /^data:([^;,]+)?(;base64)?,(.*)$/s.exec(value)
+  if (!match) return undefined
+  const mimeType = match[1] || 'application/octet-stream'
+  const payload = decodeURIComponent(match[3] ?? '')
+  return {
+    mimeType,
+    bytes: match[2]
+      ? base64ToUint8Array(payload)
+      : new TextEncoder().encode(payload),
+  }
+}
+
+function extensionForMime(mimeType: string | undefined): string {
+  if (mimeType === undefined) return 'bin'
+
+  switch (mimeType) {
+    case 'image/png':
+      return 'png'
+    case 'image/jpeg':
+      return 'jpg'
+    case 'audio/wav':
+      return 'wav'
+    case 'audio/mpeg':
+      return 'mp3'
+    case 'audio/mp3':
+      return 'mp3'
+    case 'video/mp4':
+      return 'mp4'
+    case 'application/json':
+      return 'json'
+    default:
+      return 'bin'
+  }
+}
+
+function defaultArtifactName(
+  descriptor: GenerationArtifactDescriptor,
+  activity: PersistedArtifactActivity,
+  index: number,
+): string {
+  const ext = extensionForMime(descriptor.mimeType)
+  return `${activity}-${descriptor.role}-${descriptor.mediaType ?? 'artifact'}-${index}.${ext}`
+}
+
+function sourcePartDescriptors(
+  part: unknown,
+  role: PersistedArtifactRole,
+  path: string,
+): Array<GenerationArtifactDescriptor> {
+  const record = objectValue(part)
+  const type = stringField(record ?? {}, 'type')
+  const source = objectValue(record?.source)
+  if (
+    !record ||
+    !source ||
+    (type !== 'image' && type !== 'audio' && type !== 'video')
+  ) {
+    return []
+  }
+  const sourceType = stringField(source, 'type')
+  const mimeType = stringField(source, 'mimeType') ?? `${type}/mpeg`
+  if (sourceType === 'data') {
+    const value = stringField(source, 'value')
+    if (!value) return []
+    return [
+      {
+        role,
+        path,
+        mediaType: type,
+        mimeType,
+        bytes: base64ToUint8Array(value),
+      },
+    ]
+  }
+  if (sourceType === 'url') {
+    const value = stringField(source, 'value')
+    if (!value) return []
+    return [{ role, path, mediaType: type, mimeType, url: value }]
+  }
+  return []
+}
+
+function promptInputDescriptors(
+  inputs: unknown,
+): Array<GenerationArtifactDescriptor> {
+  const prompt = objectValue(inputs)?.prompt
+  if (!Array.isArray(prompt)) return []
+
+  const counts: Record<string, number> = { image: 0, audio: 0, video: 0 }
+  const descriptors: Array<GenerationArtifactDescriptor> = []
+  for (const part of prompt) {
+    const type = stringField(objectValue(part) ?? {}, 'type')
+    if (type !== 'image' && type !== 'audio' && type !== 'video') continue
+    const index = counts[type] ?? 0
+    counts[type] = index + 1
+    descriptors.push(
+      ...sourcePartDescriptors(part, 'input', `prompt.${type}s.${index}`),
+    )
+  }
+  return descriptors
+}
+
+function generatedMediaDescriptor(args: {
+  role: PersistedArtifactRole
+  path: string
+  mediaType: 'image' | 'audio' | 'video'
+  mimeType: string
+  media: unknown
+  jobId?: string
+  expiresAt?: string | Date
+}): GenerationArtifactDescriptor | undefined {
+  const media = objectValue(args.media)
+  if (!media) return undefined
+  const b64Json = stringField(media, 'b64Json')
+  if (b64Json) {
+    return {
+      role: args.role,
+      path: args.path,
+      mediaType: args.mediaType,
+      mimeType: stringField(media, 'contentType') ?? args.mimeType,
+      bytes: base64ToUint8Array(b64Json),
+      jobId: args.jobId,
+      expiresAt: args.expiresAt,
+    }
+  }
+  const url = stringField(media, 'url')
+  if (url) {
+    return {
+      role: args.role,
+      path: args.path,
+      mediaType: args.mediaType,
+      mimeType: stringField(media, 'contentType') ?? args.mimeType,
+      url,
+      jobId: args.jobId,
+      expiresAt: args.expiresAt,
+    }
+  }
+  return undefined
+}
+
+function builtInArtifactDescriptors(
+  activity: PersistedArtifactActivity,
+  inputs: unknown,
+  result: unknown,
+): Array<GenerationArtifactDescriptor> {
+  const descriptors = promptInputDescriptors(inputs)
+  const output = objectValue(result)
+  if (!output) return descriptors
+
+  if (activity === 'image' && Array.isArray(output.images)) {
+    output.images.forEach((image, index) => {
+      const descriptor = generatedMediaDescriptor({
+        role: 'output',
+        path: `images.${index}`,
+        mediaType: 'image',
+        mimeType: 'image/png',
+        media: image,
+      })
+      if (descriptor) descriptors.push(descriptor)
+    })
+  }
+
+  if (activity === 'audio') {
+    const descriptor = generatedMediaDescriptor({
+      role: 'output',
+      path: 'audio',
+      mediaType: 'audio',
+      mimeType: 'audio/mpeg',
+      media: output.audio,
+    })
+    if (descriptor) descriptors.push(descriptor)
+  }
+
+  if (activity === 'tts') {
+    const audio = stringField(output, 'audio')
+    if (audio) {
+      const format = stringField(output, 'format')
+      descriptors.push({
+        role: 'output',
+        path: 'audio',
+        mediaType: 'audio',
+        mimeType:
+          stringField(output, 'contentType') ??
+          (format ? `audio/${format}` : 'audio/mpeg'),
+        bytes: base64ToUint8Array(audio),
+      })
+    }
+  }
+
+  if (activity === 'video' && typeof output.url === 'string') {
+    descriptors.push({
+      role: 'output',
+      path: 'video',
+      mediaType: 'video',
+      mimeType: 'video/mp4',
+      url: output.url,
+      jobId: stringField(output, 'jobId'),
+      expiresAt:
+        output.expiresAt instanceof Date ? output.expiresAt : undefined,
+    })
+  }
+
+  if (activity === 'transcription') {
+    const audio = objectValue(inputs)?.audio
+    if (typeof audio === 'string') {
+      const data = parseDataUrl(audio)
+      descriptors.push({
+        role: 'input',
+        path: 'audio',
+        mediaType: 'audio',
+        mimeType: data?.mimeType ?? 'audio/mpeg',
+        bytes: data?.bytes ?? base64ToUint8Array(audio),
+      })
+    } else if (audio instanceof ArrayBuffer) {
+      descriptors.push({
+        role: 'input',
+        path: 'audio',
+        mediaType: 'audio',
+        mimeType: 'audio/mpeg',
+        bytes: audio.slice(0),
+      })
+    } else if (typeof Blob !== 'undefined' && audio instanceof Blob) {
+      descriptors.push({
+        role: 'input',
+        path: 'audio',
+        mediaType: 'audio',
+        mimeType: audio.type || 'audio/mpeg',
+        bytes: audio,
+      })
+    }
+    if (Array.isArray(output.segments) || Array.isArray(output.words)) {
+      descriptors.push({
+        role: 'output',
+        path: 'transcription',
+        mediaType: 'json',
+        mimeType: 'application/json',
+        json: output,
+      })
+    }
+  }
+
+  return descriptors
+}
+
+async function descriptorBody(
+  descriptor: GenerationArtifactDescriptor,
+): Promise<{
+  body: BlobBody
+  size: number
+  mimeType: string
+  externalUrl?: string
+}> {
+  if (descriptor.json !== undefined) {
+    const body = JSON.stringify(descriptor.json)
+    return {
+      body,
+      size: new TextEncoder().encode(body).byteLength,
+      mimeType: descriptor.mimeType ?? 'application/json',
+    }
+  }
+
+  if (descriptor.bytes !== undefined) {
+    const body = descriptor.bytes
+    let size: number
+    if (typeof body === 'string') {
+      size = new TextEncoder().encode(body).byteLength
+    } else if (body instanceof ArrayBuffer) {
+      size = body.byteLength
+    } else if (ArrayBuffer.isView(body)) {
+      size = body.byteLength
+    } else if (typeof Blob !== 'undefined' && body instanceof Blob) {
+      size = body.size
+    } else {
+      size = 0
+    }
+    return {
+      body,
+      size,
+      mimeType: descriptor.mimeType ?? 'application/octet-stream',
+    }
+  }
+
+  if (descriptor.url) {
+    const data = parseDataUrl(descriptor.url)
+    if (data) {
+      return {
+        body: data.bytes,
+        size: data.bytes.byteLength,
+        mimeType: descriptor.mimeType ?? data.mimeType,
+      }
+    }
+    const response = await fetch(descriptor.url)
+    if (!response.ok) {
+      throw new Error(
+        `Failed to persist artifact from ${descriptor.url}: HTTP ${response.status}`,
+      )
+    }
+    const body = await response.arrayBuffer()
+    return {
+      body,
+      size: body.byteLength,
+      mimeType:
+        descriptor.mimeType ??
+        response.headers.get('content-type') ??
+        'application/octet-stream',
+      externalUrl: descriptor.url,
+    }
+  }
+
+  throw new Error(
+    `Artifact descriptor ${descriptor.path} has no bytes, url, or json.`,
+  )
+}
+
+async function persistGenerationArtifacts(
+  persistence: AIPersistence,
+  opts: WithPersistenceOptions | undefined,
+  ctx: GenerationMiddlewareContext,
+  result: unknown,
+): Promise<Array<PersistedArtifactRef>> {
+  const activity = mediaActivity(ctx.activity)
+  if (!activity) return []
+
+  const threadId = ctx.threadId ?? ctx.requestId
+  const runId = ctx.runId ?? ctx.requestId
+  const extractionInput: GenerationArtifactExtractionInput = {
+    activity,
+    provider: ctx.provider,
+    model: ctx.model,
+    threadId,
+    runId,
+    inputs: ctx.artifactInputs,
+    result,
+  }
+  const extracted =
+    opts?.extractArtifacts !== undefined
+      ? await opts.extractArtifacts(extractionInput)
+      : builtInArtifactDescriptors(activity, ctx.artifactInputs, result)
+
+  if (extracted.length === 0) return []
+
+  const existingRefs = extracted.filter(isArtifactRef)
+  const descriptors = extracted.filter(
+    (item): item is GenerationArtifactDescriptor => !isArtifactRef(item),
+  )
+  if (descriptors.length === 0) return existingRefs
+
+  if (!persistence.stores.artifacts || !persistence.stores.blobs) {
+    throw new Error(
+      'Generation artifact persistence requires stores.artifacts and stores.blobs.',
+    )
+  }
+
+  const refs: Array<PersistedArtifactRef> = [...existingRefs]
+  for (const [index, descriptor] of descriptors.entries()) {
+    const artifactId = ctx.createId('artifact')
+    const { body, size, mimeType, externalUrl } =
+      await descriptorBody(descriptor)
+    const key = `artifacts/${runId}/${artifactId}`
+    await persistence.stores.blobs.put(key, body, {
+      contentType: mimeType,
+      customMetadata: {
+        runId,
+        threadId,
+        role: descriptor.role,
+        activity,
+        path: descriptor.path,
+      },
+    })
+    const createdAtMs = Date.now()
+    const name =
+      opts?.nameArtifact?.({
+        descriptor: { ...descriptor, mimeType },
+        activity,
+        provider: ctx.provider,
+        model: ctx.model,
+        threadId,
+        runId,
+        index,
+      }) ??
+      descriptor.name ??
+      defaultArtifactName({ ...descriptor, mimeType }, activity, index)
+    const record: ArtifactRecord = {
+      artifactId,
+      runId,
+      threadId,
+      name,
+      mimeType,
+      size,
+      externalUrl,
+      createdAt: createdAtMs,
+    }
+    await persistence.stores.artifacts.save(record)
+    refs.push({
+      role: descriptor.role,
+      artifactId,
+      threadId,
+      runId,
+      name,
+      mimeType,
+      size,
+      createdAt: new Date(createdAtMs).toISOString(),
+      ...(externalUrl ? { externalUrl } : {}),
+      source: {
+        activity,
+        path: descriptor.path,
+        provider: ctx.provider,
+        model: ctx.model,
+        mediaType: descriptor.mediaType,
+        jobId: descriptor.jobId,
+        expiresAt:
+          descriptor.expiresAt instanceof Date
+            ? descriptor.expiresAt.toISOString()
+            : descriptor.expiresAt,
+      },
+    })
+  }
+
+  return refs
+}
+
+// ---------------------------------------------------------------------------
+// Shared store / feature plan
+// ---------------------------------------------------------------------------
+
+interface PersistencePlan {
+  features: Array<PersistenceFeature>
+  wantsMessages: boolean
+  wantsInterrupts: boolean
+  wantsLocks: boolean
+  wantsArtifactPersistence: boolean
+  runs: AIPersistence['stores']['runs']
+}
+
+function resolvePersistencePlan(
+  persistence: AIPersistence,
+  opts?: WithPersistenceOptions,
+): PersistencePlan {
+  const features = opts?.features ?? defaultFeatures(persistence)
+  validatePersistenceFeatures(persistence, features)
+
+  const wantsMessages = features.includes('messages')
+  const wantsInterrupts = features.includes('interrupts')
+  const wantsLocks = features.includes('locks')
+  const wantsArtifactStore = features.includes('artifacts')
+  const wantsBlobStore = features.includes('blobs')
+  if (wantsArtifactStore !== wantsBlobStore) {
+    throw new Error(
+      'Generation artifact persistence requires both stores.artifacts and stores.blobs.',
+    )
+  }
+
+  return {
+    features,
+    wantsMessages,
+    wantsInterrupts,
+    wantsLocks,
+    wantsArtifactPersistence: wantsArtifactStore && wantsBlobStore,
+    runs: persistence.stores.runs,
+  }
+}
+
+async function createOrResumeRun(
+  runs: RunStore | undefined,
+  runId: string,
+  threadId: string,
+): Promise<void> {
+  await runs?.createOrResume({
+    runId,
+    threadId,
+    startedAt: Date.now(),
+  })
+}
+
+async function completeRun(
+  runs: RunStore | undefined,
+  runId: string,
+  usage?: TokenUsage,
+): Promise<void> {
+  await runs?.update(runId, {
+    status: 'completed',
+    finishedAt: Date.now(),
+    ...(usage ? { usage } : {}),
+  })
+}
+
+async function failRun(
+  runs: RunStore | undefined,
+  runId: string,
+  error: unknown,
+): Promise<void> {
+  await runs?.update(runId, {
+    status: 'failed',
+    finishedAt: Date.now(),
+    error: error instanceof Error ? error.message : String(error),
+  })
+}
+
+async function interruptRun(
+  runs: RunStore | undefined,
+  runId: string,
+): Promise<void> {
+  await runs?.update(runId, {
+    status: 'interrupted',
+    finishedAt: Date.now(),
+  })
+}
+
+// ---------------------------------------------------------------------------
+// Chat middleware
+// ---------------------------------------------------------------------------
+
+/**
+ * Chat-only persistence middleware. Provides durable **state** for `chat()`:
+ * thread messages, run records, interrupts, and locks. Delivery durability
+ * (replaying a disconnected/reloaded stream) lives on the transport layer via
+ * `StreamDurability`, not here — this middleware never mutates the chunk stream.
+ */
+export function withChatPersistence(
+  persistence: AIPersistence,
+  opts?: WithPersistenceOptions,
+): ChatMiddleware {
+  const plan = resolvePersistencePlan(persistence, opts)
+  const { wantsMessages, wantsInterrupts, wantsLocks, runs } = plan
+
+  const provides = [
+    PersistenceCapability,
+    ...(wantsInterrupts ? [InterruptsCapability] : []),
+    ...(wantsLocks ? [LocksCapability] : []),
+  ]
+
+  return defineChatMiddleware({
+    name: 'chat-persistence',
+    provides,
+    setup(ctx: ChatMiddlewareContext) {
+      providePersistence(ctx, persistence)
+
+      runState.set(ctx, {
+        merged: false,
+        interrupted: false,
+      })
+
+      if (wantsInterrupts && persistence.stores.interrupts) {
+        provideInterrupts(ctx, persistence.stores.interrupts)
+      }
+      if (wantsLocks && persistence.stores.locks) {
+        provideLocks(ctx, persistence.stores.locks)
+      }
+    },
+
+    async onConfig(ctx: ChatMiddlewareContext, config: ChatMiddlewareConfig) {
+      if (ctx.phase !== 'init') return
+
+      let resumeToolState: ChatResumeToolState | undefined
+
+      if (wantsInterrupts && persistence.stores.interrupts) {
+        const pending = await persistence.stores.interrupts.listPending(
+          ctx.threadId,
+        )
+        const resumeByInterruptId = validatePendingResumes(
+          pending,
+          config.resume,
+        )
+        resumeToolState = resumeToolStateFromPending(
+          pending,
+          resumeByInterruptId,
+        )
+        await applyPendingResumes(
+          pending,
+          resumeByInterruptId,
+          persistence.stores.interrupts,
+        )
+      }
+
+      await createOrResumeRun(runs, ctx.runId, ctx.threadId)
+
+      if (!wantsMessages || !persistence.stores.messages) {
+        return resumeToolState ? { resumeToolState } : undefined
+      }
+      const state = runState.get(ctx)
+      if (state?.merged) {
+        return resumeToolState ? { resumeToolState } : undefined
+      }
+      if (state) state.merged = true
+
+      const stored = await persistence.stores.messages.loadThread(ctx.threadId)
+      const merged = config.messages.length > 0 ? config.messages : stored
+      return {
+        messages: merged,
+        ...(resumeToolState ? { resumeToolState } : {}),
+      }
+    },
+
+    async onChunk(ctx: ChatMiddlewareContext, chunk: StreamChunk) {
+      // State-only: react to the interrupt boundary (create interrupt records,
+      // mark the run interrupted, snapshot thread messages). The chunk stream is
+      // never mutated — delivery durability is a transport-layer concern.
+      if (
+        chunk.type !== 'RUN_FINISHED' ||
+        chunk.outcome?.type !== 'interrupt'
+      ) {
+        return
+      }
+      const state = runState.get(ctx)
+      if (!state) return
+
+      if (wantsInterrupts && persistence.stores.interrupts) {
+        for (const interrupt of chunk.outcome.interrupts) {
+          await persistence.stores.interrupts.create({
+            interruptId: interrupt.id,
+            runId: ctx.runId,
+            threadId: ctx.threadId,
+            status: 'pending',
+            requestedAt: Date.now(),
+            payload: interruptPayload(interrupt),
+          })
+        }
+      }
+      await interruptRun(runs, ctx.runId)
+      if (wantsMessages && persistence.stores.messages) {
+        await persistence.stores.messages.saveThread(ctx.threadId, [
+          ...ctx.messages,
+        ])
+      }
+      state.interrupted = true
+    },
+
+    async onFinish(ctx: ChatMiddlewareContext, info: FinishInfo) {
+      if (runState.get(ctx)?.interrupted) return
+      await completeRun(runs, ctx.runId, info.usage)
+      if (wantsMessages && persistence.stores.messages) {
+        await persistence.stores.messages.saveThread(ctx.threadId, [
+          ...ctx.messages,
+        ])
+      }
+    },
+
+    async onError(ctx: ChatMiddlewareContext, info: ErrorInfo) {
+      await failRun(runs, ctx.runId, info.error)
+    },
+
+    async onAbort(ctx: ChatMiddlewareContext, _info: AbortInfo) {
+      await interruptRun(runs, ctx.runId)
+    },
+  })
+}
+
+// ---------------------------------------------------------------------------
+// Generation middleware
+// ---------------------------------------------------------------------------
+
+/**
+ * Generation-only persistence middleware. Tracks run status and optionally
+ * persists media artifacts/blobs for image, audio, TTS, video, and
+ * transcription activities.
+ */
+export function withGenerationPersistence(
+  persistence: AIPersistence,
+  opts?: WithPersistenceOptions,
+): GenerationMiddleware {
+  const plan = resolvePersistencePlan(persistence, opts)
+  const { wantsArtifactPersistence, runs } = plan
+
+  return {
+    name: 'generation-persistence',
+
+    async onStart(ctx: GenerationMiddlewareContext) {
+      await createOrResumeRun(
+        runs,
+        ctx.runId ?? ctx.requestId,
+        ctx.threadId ?? ctx.requestId,
+      )
+      if (!wantsArtifactPersistence) return
+      ctx.resultTransforms?.push(async (result) => {
+        const refs = await persistGenerationArtifacts(
+          persistence,
+          opts,
+          ctx,
+          result,
+        )
+        if (refs.length === 0) return undefined
+        const existing = objectValue(result)?.artifacts
+        return {
+          ...(objectValue(result) ?? {}),
+          artifacts: [...(Array.isArray(existing) ? existing : []), ...refs],
+        }
+      })
+    },
+
+    async onFinish(
+      ctx: GenerationMiddlewareContext,
+      info: GenerationFinishInfo,
+    ) {
+      await completeRun(runs, ctx.runId ?? ctx.requestId, info.usage)
+    },
+
+    async onError(ctx: GenerationMiddlewareContext, info: GenerationErrorInfo) {
+      await failRun(runs, ctx.runId ?? ctx.requestId, info.error)
+    },
+
+    async onAbort(
+      ctx: GenerationMiddlewareContext,
+      _info: GenerationAbortInfo,
+    ) {
+      await interruptRun(runs, ctx.runId ?? ctx.requestId)
+    },
+  }
+}
diff --git a/packages/ai-persistence/src/testkit/conformance.ts b/packages/ai-persistence/src/testkit/conformance.ts
new file mode 100644
index 000000000..e2e80edfc
--- /dev/null
+++ b/packages/ai-persistence/src/testkit/conformance.ts
@@ -0,0 +1,354 @@
+/**
+ * Shared conformance suite for the `AIPersistence` state contract.
+ *
+ * Every backend (memory, drizzle, prisma, …) runs this identical suite so that
+ * schema drift or an implementation gap fails immediately. It exercises every
+ * method of every store the persistence exposes; stores that are absent (a
+ * backend may not provide `locks`, for example) are skipped, so the suite is
+ * universal across backends.
+ *
+ * Artifacts are tested via `externalUrl` (not inline `bytes`) so the assertions
+ * hold identically for byte-storing (memory) and reference-only (SQL) backends.
+ */
+import { beforeAll, describe, expect, it } from 'vitest'
+import type { AIPersistence } from '../types'
+
+type MakePersistence = () => Promise<AIPersistence> | AIPersistence
+
+/**
+ * Register a Vitest suite that validates `makePersistence()` against the full
+ * `AIPersistence` contract.
+ */
+export function runPersistenceConformance(
+  name: string,
+  makePersistence: MakePersistence,
+): void {
+  describe(`AIPersistence conformance: ${name}`, () => {
+    let persistence: AIPersistence
+
+    beforeAll(async () => {
+      persistence = await makePersistence()
+    })
+
+    describe('messages', () => {
+      it('round-trips a thread and returns [] for unknown threads', async () => {
+        const store = persistence.stores.messages
+        if (!store) return
+
+        expect(await store.loadThread('thread-unknown')).toEqual([])
+
+        await store.saveThread('thread-msg', [
+          { role: 'user', content: 'hi' },
+          { role: 'assistant', content: 'hello' },
+        ])
+        expect(await store.loadThread('thread-msg')).toEqual([
+          { role: 'user', content: 'hi' },
+          { role: 'assistant', content: 'hello' },
+        ])
+
+        // Overwrites, not appends.
+        await store.saveThread('thread-msg', [
+          { role: 'user', content: 'redo' },
+        ])
+        expect(await store.loadThread('thread-msg')).toEqual([
+          { role: 'user', content: 'redo' },
+        ])
+      })
+    })
+
+    describe('runs', () => {
+      it('creates, resumes idempotently, updates, and gets', async () => {
+        const store = persistence.stores.runs
+        if (!store) return
+
+        expect(await store.get('run-missing')).toBeNull()
+
+        const created = await store.createOrResume({
+          runId: 'run-1',
+          threadId: 'thread-1',
+          startedAt: 1000,
+        })
+        expect(created).toMatchObject({
+          runId: 'run-1',
+          threadId: 'thread-1',
+          status: 'running',
+          startedAt: 1000,
+        })
+
+        // createOrResume is idempotent: returns the existing record unchanged.
+        const resumed = await store.createOrResume({
+          runId: 'run-1',
+          threadId: 'thread-different',
+          startedAt: 9999,
+        })
+        expect(resumed).toMatchObject({
+          runId: 'run-1',
+          threadId: 'thread-1',
+          startedAt: 1000,
+        })
+
+        await store.update('run-1', {
+          status: 'completed',
+          finishedAt: 2000,
+          usage: { promptTokens: 3, completionTokens: 4, totalTokens: 7 },
+        })
+        const done = await store.get('run-1')
+        expect(done).toMatchObject({
+          runId: 'run-1',
+          status: 'completed',
+          finishedAt: 2000,
+          usage: { promptTokens: 3, completionTokens: 4, totalTokens: 7 },
+        })
+
+        await store.update('run-1', { status: 'failed', error: 'boom' })
+        const failed = await store.get('run-1')
+        expect(failed?.status).toBe('failed')
+        expect(failed?.error).toBe('boom')
+
+        // Updating a missing run is a no-op (does not throw, does not create).
+        await store.update('run-absent', { status: 'completed' })
+        expect(await store.get('run-absent')).toBeNull()
+      })
+    })
+
+    describe('interrupts', () => {
+      it('creates, resolves, cancels, and lists by thread and run', async () => {
+        const store = persistence.stores.interrupts
+        if (!store) return
+
+        expect(await store.get('int-missing')).toBeNull()
+
+        await store.create({
+          interruptId: 'int-1',
+          runId: 'run-i',
+          threadId: 'thread-i',
+          status: 'pending',
+          requestedAt: 10,
+          payload: { tool: 'search', args: { q: 'x' } },
+        })
+        await store.create({
+          interruptId: 'int-2',
+          runId: 'run-i',
+          threadId: 'thread-i',
+          status: 'pending',
+          requestedAt: 20,
+          payload: { tool: 'write' },
+        })
+        await store.create({
+          interruptId: 'int-3',
+          runId: 'run-other',
+          threadId: 'thread-i',
+          status: 'pending',
+          requestedAt: 30,
+          payload: {},
+        })
+
+        const one = await store.get('int-1')
+        expect(one).toMatchObject({
+          interruptId: 'int-1',
+          runId: 'run-i',
+          threadId: 'thread-i',
+          status: 'pending',
+          requestedAt: 10,
+          payload: { tool: 'search', args: { q: 'x' } },
+        })
+
+        expect(
+          (await store.list('thread-i')).map((r) => r.interruptId),
+        ).toEqual(['int-1', 'int-2', 'int-3'])
+        expect(
+          (await store.listByRun('run-i')).map((r) => r.interruptId),
+        ).toEqual(['int-1', 'int-2'])
+        expect(
+          (await store.listPending('thread-i')).map((r) => r.interruptId),
+        ).toEqual(['int-1', 'int-2', 'int-3'])
+
+        await store.resolve('int-1', { ok: true })
+        const resolved = await store.get('int-1')
+        expect(resolved?.status).toBe('resolved')
+        expect(resolved?.response).toEqual({ ok: true })
+        expect(typeof resolved?.resolvedAt).toBe('number')
+
+        await store.cancel('int-2')
+        const cancelled = await store.get('int-2')
+        expect(cancelled?.status).toBe('cancelled')
+        expect(typeof cancelled?.resolvedAt).toBe('number')
+
+        expect(
+          (await store.listPending('thread-i')).map((r) => r.interruptId),
+        ).toEqual(['int-3'])
+        expect(
+          (await store.listPendingByRun('run-i')).map((r) => r.interruptId),
+        ).toEqual([])
+      })
+    })
+
+    describe('metadata', () => {
+      it('sets, gets, scopes, and deletes', async () => {
+        const store = persistence.stores.metadata
+        if (!store) return
+
+        expect(await store.get('scope-a', 'k')).toBeNull()
+
+        await store.set('scope-a', 'k', { n: 1 })
+        await store.set('scope-b', 'k', { n: 2 })
+        expect(await store.get('scope-a', 'k')).toEqual({ n: 1 })
+        expect(await store.get('scope-b', 'k')).toEqual({ n: 2 })
+
+        await store.set('scope-a', 'k', { n: 3 })
+        expect(await store.get('scope-a', 'k')).toEqual({ n: 3 })
+
+        await store.delete('scope-a', 'k')
+        expect(await store.get('scope-a', 'k')).toBeNull()
+        // Delete is scoped: scope-b untouched.
+        expect(await store.get('scope-b', 'k')).toEqual({ n: 2 })
+      })
+    })
+
+    describe('artifacts', () => {
+      it('saves, gets, lists by run, and deletes', async () => {
+        const store = persistence.stores.artifacts
+        if (!store) return
+
+        expect(await store.get('art-missing')).toBeNull()
+
+        await store.save({
+          artifactId: 'art-1',
+          runId: 'run-art',
+          threadId: 'thread-art',
+          name: 'image.png',
+          mimeType: 'image/png',
+          size: 123,
+          externalUrl: 'https://example.com/image.png',
+          createdAt: 500,
+        })
+        await store.save({
+          artifactId: 'art-2',
+          runId: 'run-art',
+          threadId: 'thread-art',
+          name: 'clip.mp4',
+          mimeType: 'video/mp4',
+          size: 456,
+          externalUrl: 'https://example.com/clip.mp4',
+          createdAt: 600,
+        })
+
+        const got = await store.get('art-1')
+        expect(got).toMatchObject({
+          artifactId: 'art-1',
+          runId: 'run-art',
+          threadId: 'thread-art',
+          name: 'image.png',
+          mimeType: 'image/png',
+          size: 123,
+          externalUrl: 'https://example.com/image.png',
+          createdAt: 500,
+        })
+
+        expect(
+          (await store.list('run-art')).map((a) => a.artifactId).sort(),
+        ).toEqual(['art-1', 'art-2'])
+        expect(await store.list('run-none')).toEqual([])
+
+        if (store.delete) {
+          await store.delete('art-1')
+          expect(await store.get('art-1')).toBeNull()
+          expect(
+            (await store.list('run-art')).map((a) => a.artifactId),
+          ).toEqual(['art-2'])
+        }
+        if (store.deleteForRun) {
+          await store.deleteForRun('run-art')
+          expect(await store.list('run-art')).toEqual([])
+        }
+      })
+    })
+
+    describe('blobs', () => {
+      it('puts, gets, heads, lists, and deletes', async () => {
+        const store = persistence.stores.blobs
+        if (!store) return
+
+        const put = await store.put('blobs/a.txt', 'hello world', {
+          contentType: 'text/plain',
+          customMetadata: { owner: 'alice' },
+        })
+        expect(put.key).toBe('blobs/a.txt')
+        expect(put.size).toBe('hello world'.length)
+        expect(put.contentType).toBe('text/plain')
+
+        const got = await store.get('blobs/a.txt')
+        expect(got).not.toBeNull()
+        expect(await got?.text()).toBe('hello world')
+        expect(got?.customMetadata).toEqual({ owner: 'alice' })
+
+        const head = await store.head('blobs/a.txt')
+        expect(head?.key).toBe('blobs/a.txt')
+        expect(head?.size).toBe('hello world'.length)
+
+        expect(await store.get('blobs/missing')).toBeNull()
+        expect(await store.head('blobs/missing')).toBeNull()
+
+        await store.put('blobs/b.txt', 'second')
+        await store.put('other/c.txt', 'third')
+
+        const page = await store.list({ prefix: 'blobs/' })
+        expect(page.objects.map((o) => o.key).sort()).toEqual([
+          'blobs/a.txt',
+          'blobs/b.txt',
+        ])
+
+        const limited = await store.list({ prefix: 'blobs/', limit: 1 })
+        expect(limited.objects).toHaveLength(1)
+        expect(limited.truncated).toBe(true)
+        expect(limited.cursor).toBeDefined()
+
+        const rest = await store.list({
+          prefix: 'blobs/',
+          cursor: limited.cursor,
+        })
+        expect(rest.objects.map((o) => o.key)).not.toContain(
+          limited.objects[0]?.key,
+        )
+
+        await store.delete('blobs/a.txt')
+        expect(await store.get('blobs/a.txt')).toBeNull()
+      })
+
+      it('matches list prefixes literally and case-sensitively', async () => {
+        const store = persistence.stores.blobs
+        if (!store) return
+
+        // `run_` contains a SQL LIKE metacharacter (`_`), and the differing-case
+        // keys probe case sensitivity. Only the keys that literally start with
+        // the exact bytes `run_` must come back — `_` must NOT match any single
+        // character, and `RUN_1/...` (upper-case) must be excluded.
+        await store.put('run_1/x', 'a')
+        await store.put('run_2/y', 'b')
+        await store.put('runX/z', 'c') // `_` as wildcard would wrongly match this
+        await store.put('RUN_1/w', 'd') // case-insensitive match would include this
+
+        const page = await store.list({ prefix: 'run_' })
+        expect(page.objects.map((o) => o.key).sort()).toEqual([
+          'run_1/x',
+          'run_2/y',
+        ])
+      })
+    })
+
+    describe('locks', () => {
+      it('runs the critical section and returns its value', async () => {
+        const store = persistence.stores.locks
+        if (!store) return
+
+        const order: Array<string> = []
+        const result = await store.withLock('lock-key', async () => {
+          order.push('inside')
+          return 42
+        })
+        expect(result).toBe(42)
+        expect(order).toEqual(['inside'])
+      })
+    })
+  })
+}
diff --git a/packages/ai-persistence/src/types.ts b/packages/ai-persistence/src/types.ts
new file mode 100644
index 000000000..7c3bb4415
--- /dev/null
+++ b/packages/ai-persistence/src/types.ts
@@ -0,0 +1,209 @@
+import type { LockStore, ModelMessage, TokenUsage } from '@tanstack/ai'
+
+export type PersistenceMode = 'messages' | 'chat' | 'agent'
+
+export type PersistenceFeature =
+  | 'messages'
+  | 'interrupts'
+  | 'metadata'
+  | 'locks'
+  | 'artifacts'
+  | 'blobs'
+
+export interface MessageStore {
+  loadThread: (threadId: string) => Promise<Array<ModelMessage>>
+  saveThread: (threadId: string, messages: Array<ModelMessage>) => Promise<void>
+}
+
+export type RunStatus = 'running' | 'completed' | 'failed' | 'interrupted'
+
+export interface RunRecord {
+  runId: string
+  threadId: string
+  status: RunStatus
+  startedAt: number
+  finishedAt?: number
+  error?: string
+  usage?: TokenUsage
+}
+
+export interface RunStore {
+  createOrResume: (
+    input: Pick<RunRecord, 'runId' | 'threadId'> & {
+      status?: RunStatus
+      startedAt: number
+    },
+  ) => Promise<RunRecord>
+  update: (
+    runId: string,
+    patch: Partial<
+      Pick<RunRecord, 'status' | 'finishedAt' | 'error' | 'usage'>
+    >,
+  ) => Promise<void>
+  get: (runId: string) => Promise<RunRecord | null>
+}
+
+export interface InterruptRecord {
+  interruptId: string
+  runId: string
+  threadId: string
+  status: 'pending' | 'resolved' | 'cancelled'
+  requestedAt: number
+  resolvedAt?: number
+  payload: Record<string, unknown>
+  response?: unknown
+}
+
+export interface InterruptStore {
+  create: (record: Omit<InterruptRecord, 'resolvedAt'>) => Promise<void>
+  resolve: (interruptId: string, response?: unknown) => Promise<void>
+  cancel: (interruptId: string) => Promise<void>
+  get: (interruptId: string) => Promise<InterruptRecord | null>
+  list: (threadId: string) => Promise<Array<InterruptRecord>>
+  listPending: (threadId: string) => Promise<Array<InterruptRecord>>
+  listByRun: (runId: string) => Promise<Array<InterruptRecord>>
+  listPendingByRun: (runId: string) => Promise<Array<InterruptRecord>>
+}
+
+export interface MetadataStore {
+  get: (scope: string, key: string) => Promise<unknown | null>
+  set: (scope: string, key: string, value: unknown) => Promise<void>
+  delete: (scope: string, key: string) => Promise<void>
+}
+
+export interface ArtifactRecord {
+  artifactId: string
+  runId: string
+  threadId: string
+  name: string
+  mimeType: string
+  size: number
+  bytes?: Uint8Array
+  externalUrl?: string
+  createdAt: number
+}
+
+export interface ArtifactStore {
+  save: (record: ArtifactRecord) => Promise<void>
+  get: (artifactId: string) => Promise<ArtifactRecord | null>
+  list: (runId: string) => Promise<Array<ArtifactRecord>>
+  delete?: (artifactId: string) => Promise<void>
+  deleteForRun?: (runId: string) => Promise<void>
+}
+
+export type BlobBody =
+  | ReadableStream<Uint8Array>
+  | ArrayBuffer
+  | ArrayBufferView
+  | string
+  | Blob
+  | Uint8Array
+
+export interface BlobRecord {
+  key: string
+  size?: number
+  etag?: string
+  contentType?: string
+  customMetadata?: Record<string, string>
+  createdAt?: number
+  updatedAt?: number
+}
+
+export interface BlobObject extends BlobRecord {
+  arrayBuffer: () => Promise<ArrayBuffer>
+  text: () => Promise<string>
+  body?: ReadableStream<Uint8Array>
+}
+
+export interface BlobListPage {
+  objects: Array<BlobRecord>
+  cursor?: string
+  truncated?: boolean
+}
+
+export interface BlobPutOptions {
+  contentType?: string
+  customMetadata?: Record<string, string>
+}
+
+export interface BlobListOptions {
+  prefix?: string
+  cursor?: string
+  limit?: number
+}
+
+export interface BlobStore {
+  put: (
+    key: string,
+    body: BlobBody,
+    options?: BlobPutOptions,
+  ) => Promise<BlobRecord>
+  get: (key: string) => Promise<BlobObject | null>
+  head: (key: string) => Promise<BlobRecord | null>
+  delete: (key: string) => Promise<void>
+  list: (options?: BlobListOptions) => Promise<BlobListPage>
+}
+
+export interface AIPersistence {
+  stores: {
+    messages?: MessageStore
+    runs?: RunStore
+    interrupts?: InterruptStore
+    metadata?: MetadataStore
+    locks?: LockStore
+    artifacts?: ArtifactStore
+    blobs?: BlobStore
+  }
+}
+
+/** @deprecated Use AIPersistence. */
+export type ChatPersistence = AIPersistence
+
+const featureRequirements: Record<
+  PersistenceFeature,
+  Array<keyof AIPersistence['stores']>
+> = {
+  messages: ['messages'],
+  interrupts: ['runs', 'interrupts'],
+  metadata: ['metadata'],
+  locks: ['locks'],
+  artifacts: ['artifacts'],
+  blobs: ['blobs'],
+}
+
+export function validatePersistenceFeatures(
+  persistence: AIPersistence,
+  features: Array<PersistenceFeature>,
+): void {
+  const missing = new Map<
+    PersistenceFeature,
+    Array<keyof AIPersistence['stores']>
+  >()
+  for (const feature of features) {
+    const missingStores = featureRequirements[feature].filter(
+      (store) => !persistence.stores[store],
+    )
+    if (missingStores.length > 0) {
+      missing.set(feature, missingStores)
+    }
+  }
+  if (missing.size === 0) return
+
+  const details = [...missing]
+    .map(
+      ([feature, stores]) =>
+        `${feature} requires ${stores.map((s) => `stores.${s}`).join(', ')}`,
+    )
+    .join('; ')
+  throw new Error(`AIPersistence is missing required stores: ${details}`)
+}
+
+export function defineAIPersistence(persistence: AIPersistence): AIPersistence {
+  return persistence
+}
+
+/**
+ * @deprecated Use defineAIPersistence.
+ * @alias
+ */
+export const defineChatPersistence = defineAIPersistence
diff --git a/packages/ai-persistence/tests/generation-artifacts.test.ts b/packages/ai-persistence/tests/generation-artifacts.test.ts
new file mode 100644
index 000000000..ae95cff20
--- /dev/null
+++ b/packages/ai-persistence/tests/generation-artifacts.test.ts
@@ -0,0 +1,487 @@
+import { describe, expect, it, vi } from 'vitest'
+import {
+  EventType,
+  generateAudio,
+  generateImage,
+  generateTranscription,
+} from '@tanstack/ai'
+import { defineAIPersistence } from '../src/types'
+import { memoryPersistence } from '../src/memory'
+import { withGenerationPersistence } from '../src/middleware'
+import type {
+  GenerationArtifactDescriptor,
+  GenerationArtifactExtractionInput,
+  GenerationArtifactNameInput,
+} from '../src'
+import type {
+  AudioAdapter,
+  AudioGenerationResult,
+  ImageAdapter,
+  PersistedArtifactRef,
+  StreamChunk,
+  TranscriptionAdapter,
+  TranscriptionResult,
+} from '@tanstack/ai'
+
+void (undefined as unknown as GenerationArtifactDescriptor)
+void (undefined as unknown as GenerationArtifactExtractionInput)
+void (undefined as unknown as GenerationArtifactNameInput)
+
+type AudioGenerateOptions = Parameters<typeof generateAudio>[0] & {
+  threadId?: string
+  runId?: string
+  replay?: unknown
+}
+
+type TranscriptionGenerateOptions = Parameters<
+  typeof generateTranscription
+>[0] & {
+  threadId?: string
+  runId?: string
+}
+
+const imageAdapterTypes: ImageAdapter<string>['~types'] = {
+  providerOptions: {},
+  modelProviderOptionsByName: {},
+  modelSizeByName: {},
+  modelInputModalitiesByName: {},
+}
+
+const audioAdapterTypes: AudioAdapter<string>['~types'] = {
+  providerOptions: {},
+}
+
+const transcriptionAdapterTypes: TranscriptionAdapter<string>['~types'] = {
+  providerOptions: {},
+}
+
+async function collect(stream: AsyncIterable<StreamChunk>) {
+  const chunks: Array<StreamChunk> = []
+  for await (const chunk of stream) chunks.push(chunk)
+  return chunks
+}
+
+function imageAdapter(): ImageAdapter<string> {
+  return {
+    kind: 'image',
+    name: 'test-image-provider',
+    model: 'test-image-model',
+    '~types': imageAdapterTypes,
+    generateImages: vi.fn(async () => ({
+      id: 'image-result',
+      model: 'test-image-model',
+      images: [{ b64Json: 'b3V0cHV0LWltYWdl' }],
+    })),
+  }
+}
+
+function audioAdapter(): AudioAdapter<string> {
+  return {
+    kind: 'audio',
+    name: 'test-audio-provider',
+    model: 'test-audio-model',
+    '~types': audioAdapterTypes,
+    generateAudio: vi.fn(async () => ({
+      id: 'audio-result',
+      model: 'test-audio-model',
+      audio: {
+        b64Json: 'b3V0cHV0LWF1ZGlv',
+        contentType: 'audio/wav',
+        duration: 1,
+      },
+    })),
+  }
+}
+
+function transcriptionAdapter(): TranscriptionAdapter<string> {
+  return {
+    kind: 'transcription',
+    name: 'test-transcription-provider',
+    model: 'test-transcription-model',
+    '~types': transcriptionAdapterTypes,
+    transcribe: vi.fn(async () => ({
+      id: 'transcription-result',
+      model: 'test-transcription-model',
+      text: 'hello world',
+      language: 'en',
+      segments: [{ id: 0, start: 0, end: 1, text: 'hello world' }],
+    })),
+  }
+}
+
+describe('withGenerationPersistence generation artifacts', () => {
+  it('persists built-in image output artifacts and attaches refs', async () => {
+    const persistence = memoryPersistence()
+
+    const result = await generateImage({
+      adapter: imageAdapter(),
+      prompt: 'make an image',
+      threadId: 'thread-image',
+      runId: 'run-image',
+      middleware: [withGenerationPersistence(persistence)],
+    })
+
+    expect(result.artifacts).toHaveLength(1)
+    expect(result.artifacts?.[0]).toMatchObject({
+      role: 'output',
+      threadId: 'thread-image',
+      runId: 'run-image',
+      mimeType: 'image/png',
+      size: 12,
+      source: {
+        activity: 'image',
+        path: 'images.0',
+        provider: 'test-image-provider',
+        model: 'test-image-model',
+        mediaType: 'image',
+      },
+    })
+
+    const record = await persistence.stores.artifacts!.get(
+      result.artifacts![0]!.artifactId,
+    )
+    expect(record).toMatchObject({
+      runId: 'run-image',
+      threadId: 'thread-image',
+      mimeType: 'image/png',
+      size: 12,
+    })
+    const blob = await persistence.stores.blobs!.get(
+      `artifacts/run-image/${result.artifacts![0]!.artifactId}`,
+    )
+    await expect(blob?.text()).resolves.toBe('output-image')
+  })
+
+  it('persists non-image media outputs', async () => {
+    const persistence = memoryPersistence()
+
+    const result = (await generateAudio({
+      adapter: audioAdapter(),
+      prompt: 'make audio',
+      threadId: 'thread-audio',
+      runId: 'run-audio',
+      middleware: [withGenerationPersistence(persistence)],
+    } as AudioGenerateOptions)) as AudioGenerationResult
+
+    expect(result.artifacts).toHaveLength(1)
+    expect(result.artifacts?.[0]).toMatchObject({
+      role: 'output',
+      mimeType: 'audio/wav',
+      size: 12,
+      source: {
+        activity: 'audio',
+        path: 'audio',
+        mediaType: 'audio',
+      },
+    })
+  })
+
+  it('persists media inputs and includes input refs on the result', async () => {
+    const persistence = memoryPersistence()
+
+    const result = await generateImage({
+      adapter: imageAdapter(),
+      prompt: [
+        { type: 'text', content: 'edit this' },
+        {
+          type: 'image',
+          source: {
+            type: 'data',
+            value: 'aW5wdXQtaW1hZ2U=',
+            mimeType: 'image/png',
+          },
+        },
+      ],
+      threadId: 'thread-input',
+      runId: 'run-input',
+      middleware: [withGenerationPersistence(persistence)],
+    })
+
+    expect(result.artifacts?.map((artifact) => artifact.role)).toEqual([
+      'input',
+      'output',
+    ])
+    const input = result.artifacts?.[0]
+    expect(input).toMatchObject({
+      role: 'input',
+      mimeType: 'image/png',
+      size: 11,
+      source: { path: 'prompt.images.0', mediaType: 'image' },
+    })
+  })
+
+  it('fails loudly when artifact persistence is explicitly enabled but stores are missing', () => {
+    const full = memoryPersistence()
+    const persistence = defineAIPersistence({
+      stores: {
+        runs: full.stores.runs,
+      },
+    })
+
+    expect(() =>
+      withGenerationPersistence(persistence, {
+        features: ['artifacts', 'blobs'],
+      }),
+    ).toThrow(/artifacts.*stores\.artifacts.*blobs.*stores\.blobs/i)
+  })
+
+  it('uses custom artifact extraction instead of built-in extraction', async () => {
+    const persistence = memoryPersistence()
+
+    const result = await generateImage({
+      adapter: imageAdapter(),
+      prompt: [
+        { type: 'text', content: 'edit this' },
+        {
+          type: 'image',
+          source: {
+            type: 'data',
+            value: 'aW5wdXQtaW1hZ2U=',
+            mimeType: 'image/png',
+          },
+        },
+      ],
+      threadId: 'thread-custom',
+      runId: 'run-custom',
+      middleware: [
+        withGenerationPersistence(persistence, {
+          extractArtifacts: () => [
+            {
+              role: 'output',
+              path: 'custom',
+              mediaType: 'json',
+              mimeType: 'application/json',
+              json: { ok: true },
+              name: 'custom.json',
+            },
+          ],
+        }),
+      ],
+    })
+
+    expect(result.artifacts).toHaveLength(1)
+    expect(result.artifacts?.[0]).toMatchObject({
+      name: 'custom.json',
+      mimeType: 'application/json',
+      source: { path: 'custom', mediaType: 'json' },
+    })
+  })
+
+  it('does not leak data URL bytes into artifact refs', async () => {
+    const persistence = memoryPersistence()
+    const dataUrl = 'data:image/png;base64,ZGF0YS11cmwtYnl0ZXM='
+
+    const result = await generateImage({
+      adapter: imageAdapter(),
+      prompt: 'make an image',
+      threadId: 'thread-data-url',
+      runId: 'run-data-url',
+      middleware: [
+        withGenerationPersistence(persistence, {
+          extractArtifacts: () => [
+            {
+              role: 'input',
+              path: 'prompt.images.0',
+              mediaType: 'image',
+              url: dataUrl,
+            },
+            {
+              role: 'output',
+              path: 'images.0',
+              mediaType: 'image',
+              url: dataUrl,
+            },
+          ],
+        }),
+      ],
+    })
+
+    expect(result.artifacts).toHaveLength(2)
+    expect(result.artifacts?.map((artifact) => artifact.externalUrl)).toEqual([
+      undefined,
+      undefined,
+    ])
+    expect(JSON.stringify(result.artifacts)).not.toContain(dataUrl)
+
+    const [input, output] = result.artifacts!
+    await expect(
+      persistence.stores.blobs
+        ?.get(`artifacts/run-data-url/${input!.artifactId}`)
+        .then((blob) => blob?.text()),
+    ).resolves.toBe('data-url-bytes')
+    await expect(
+      persistence.stores.blobs
+        ?.get(`artifacts/run-data-url/${output!.artifactId}`)
+        .then((blob) => blob?.text()),
+    ).resolves.toBe('data-url-bytes')
+  })
+
+  it('uses nameArtifact overrides', async () => {
+    const persistence = memoryPersistence()
+
+    const result = (await generateAudio({
+      adapter: audioAdapter(),
+      prompt: 'make audio',
+      threadId: 'thread-name',
+      runId: 'run-name',
+      middleware: [
+        withGenerationPersistence(persistence, {
+          nameArtifact: ({ descriptor, index }) =>
+            `${descriptor.role}-${descriptor.mediaType}-${index}.bin`,
+        }),
+      ],
+    } as AudioGenerateOptions)) as AudioGenerationResult
+
+    expect(result.artifacts?.[0]?.name).toBe('output-audio-0.bin')
+  })
+
+  it('emits generation:artifacts before generation:result with persisted refs', async () => {
+    const persistence = memoryPersistence()
+
+    const chunks = await collect(
+      generateImage<ImageAdapter<string>, true>({
+        adapter: imageAdapter(),
+        prompt: 'make an image',
+        stream: true,
+        threadId: 'thread-stream',
+        runId: 'run-stream',
+        middleware: [withGenerationPersistence(persistence)],
+      }),
+    )
+
+    const customEvents = chunks.filter(
+      (chunk) => chunk.type === EventType.CUSTOM,
+    )
+    expect(customEvents.map((chunk) => chunk.name)).toEqual([
+      'generation:artifacts',
+      'generation:result',
+    ])
+    expect(customEvents[0]?.value).toEqual(
+      (customEvents[1]?.value as { artifacts?: unknown }).artifacts,
+    )
+  })
+
+  it('uses the same fallback run and thread ids for streamed events and persisted artifact refs', async () => {
+    const persistence = memoryPersistence()
+
+    const chunks = await collect(
+      generateImage<ImageAdapter<string>, true>({
+        adapter: imageAdapter(),
+        prompt: 'make an image',
+        stream: true,
+        middleware: [withGenerationPersistence(persistence)],
+      }),
+    )
+
+    const started = chunks.find((chunk) => chunk.type === EventType.RUN_STARTED)
+    const result = chunks.find(
+      (chunk) =>
+        chunk.type === EventType.CUSTOM && chunk.name === 'generation:result',
+    )
+    const artifact = (
+      result?.value as { artifacts?: Array<PersistedArtifactRef> } | undefined
+    )?.artifacts?.[0]
+
+    expect(started).toMatchObject({
+      runId: expect.any(String),
+      threadId: expect.any(String),
+    })
+    expect(artifact).toMatchObject({
+      runId: started?.runId,
+      threadId: started?.threadId,
+    })
+    await expect(
+      persistence.stores.artifacts!.list(started!.runId!),
+    ).resolves.toHaveLength(1)
+  })
+
+  it('does not re-persist replayed generation results', async () => {
+    const persistence = memoryPersistence()
+    const put = vi.spyOn(persistence.stores.blobs!, 'put')
+
+    const result = (await generateAudio({
+      adapter: audioAdapter(),
+      prompt: 'ignored',
+      replay: {
+        result: {
+          id: 'replayed',
+          model: 'test-audio-model',
+          audio: { b64Json: 'cmVwbGF5ZWQ=', contentType: 'audio/wav' },
+        },
+      },
+      middleware: [withGenerationPersistence(persistence)],
+    } as AudioGenerateOptions)) as AudioGenerationResult
+
+    expect(result.artifacts).toBeUndefined()
+    expect(put).not.toHaveBeenCalled()
+  })
+
+  it('does not persist generation artifacts when artifact features are disabled', async () => {
+    const persistence = memoryPersistence()
+    const put = vi.spyOn(persistence.stores.blobs!, 'put')
+    const save = vi.spyOn(persistence.stores.artifacts!, 'save')
+
+    const result = await generateImage({
+      adapter: imageAdapter(),
+      prompt: 'make an image',
+      threadId: 'thread-messages-only',
+      runId: 'run-messages-only',
+      middleware: [
+        withGenerationPersistence(persistence, { features: ['messages'] }),
+      ],
+    })
+
+    expect(result.artifacts).toBeUndefined()
+    expect(put).not.toHaveBeenCalled()
+    expect(save).not.toHaveBeenCalled()
+  })
+
+  it('fails early when artifact persistence is enabled without a paired blob store', () => {
+    const full = memoryPersistence()
+    const persistence = defineAIPersistence({
+      stores: {
+        artifacts: full.stores.artifacts,
+      },
+    })
+
+    expect(() =>
+      withGenerationPersistence(persistence, { features: ['artifacts'] }),
+    ).toThrow(
+      /artifact persistence requires both stores\.artifacts and stores\.blobs/i,
+    )
+  })
+
+  it('persists transcription structured JSON output', async () => {
+    const persistence = memoryPersistence()
+
+    const result = (await generateTranscription({
+      adapter: transcriptionAdapter(),
+      audio: 'aW5wdXQtYXVkaW8=',
+      responseFormat: 'verbose_json',
+      threadId: 'thread-transcription',
+      runId: 'run-transcription',
+      middleware: [withGenerationPersistence(persistence)],
+    } as TranscriptionGenerateOptions)) as TranscriptionResult
+
+    expect(result.artifacts?.map((artifact) => artifact.role)).toEqual([
+      'input',
+      'output',
+    ])
+    const structured = result.artifacts?.find(
+      (artifact) => artifact.source.mediaType === 'json',
+    ) as PersistedArtifactRef | undefined
+    expect(structured).toMatchObject({
+      role: 'output',
+      mimeType: 'application/json',
+      source: {
+        activity: 'transcription',
+        path: 'transcription',
+        mediaType: 'json',
+      },
+    })
+    const blob = await persistence.stores.blobs!.get(
+      `artifacts/run-transcription/${structured!.artifactId}`,
+    )
+    await expect(blob?.text()).resolves.toContain('"segments"')
+  })
+})
diff --git a/packages/ai-persistence/tests/interrupts.test.ts b/packages/ai-persistence/tests/interrupts.test.ts
new file mode 100644
index 000000000..9480b656c
--- /dev/null
+++ b/packages/ai-persistence/tests/interrupts.test.ts
@@ -0,0 +1,667 @@
+import { describe, expect, it, vi } from 'vitest'
+import { EventType, chat } from '@tanstack/ai'
+import type { AnyTextAdapter, StreamChunk, Tool } from '@tanstack/ai'
+import { memoryPersistence } from '../src/memory'
+import { withChatPersistence } from '../src/middleware'
+import { defineAIPersistence, validatePersistenceFeatures } from '../src/types'
+
+function mockAdapter(iterations: Array<Array<StreamChunk>>) {
+  const calls: Array<unknown> = []
+  let i = 0
+  const adapter = {
+    kind: 'text',
+    name: 'mock',
+    model: 'test-model',
+    '~types': {},
+    chatStream: (opts: unknown) => {
+      calls.push(opts)
+      const chunks = iterations[i] ?? []
+      i++
+      return (async function* () {
+        for (const c of chunks) yield c
+      })()
+    },
+    structuredOutput: async () => ({ data: {}, rawText: '{}' }),
+  } as unknown as AnyTextAdapter
+  return { adapter, calls }
+}
+
+async function collect(stream: AsyncIterable<StreamChunk>) {
+  const out: Array<StreamChunk> = []
+  for await (const c of stream) out.push(c)
+  return out
+}
+
+const interruptFinished = (): StreamChunk => ({
+  type: EventType.RUN_FINISHED,
+  runId: 'r1',
+  threadId: 't1',
+  finishReason: 'tool_calls',
+  timestamp: 1,
+  outcome: {
+    type: 'interrupt',
+    interrupts: [
+      {
+        id: 'interrupt-1',
+        reason: 'tool_call',
+        message: 'Approve the tool call?',
+        toolCallId: 'tool-call-1',
+      },
+    ],
+  },
+})
+
+const runStarted = (): StreamChunk => ({
+  type: EventType.RUN_STARTED,
+  runId: 'r1',
+  threadId: 't1',
+  timestamp: 1,
+})
+
+const toolStart = (): StreamChunk => ({
+  type: EventType.TOOL_CALL_START,
+  toolCallId: 'tool-call-1',
+  toolCallName: 'clientSearch',
+  toolName: 'clientSearch',
+  timestamp: 1,
+})
+
+const toolArgs = (): StreamChunk => ({
+  type: EventType.TOOL_CALL_ARGS,
+  toolCallId: 'tool-call-1',
+  delta: '{"query":"test"}',
+  timestamp: 1,
+})
+
+const text = (delta: string): StreamChunk => ({
+  type: EventType.TEXT_MESSAGE_CONTENT,
+  messageId: 'm1',
+  delta,
+  timestamp: 1,
+})
+
+const runFinished = (runId = 'r1'): StreamChunk => ({
+  type: EventType.RUN_FINISHED,
+  runId,
+  threadId: 't1',
+  finishReason: 'stop',
+  timestamp: 1,
+})
+
+const clientTool = (name: string): Tool => ({
+  name,
+  description: `${name} client tool`,
+})
+
+const approvalClientTool = (name: string): Tool => ({
+  ...clientTool(name),
+  needsApproval: true,
+})
+
+describe('interrupt persistence', () => {
+  it('requires run and interrupt stores', () => {
+    const stores = memoryPersistence().stores
+    expect(() =>
+      validatePersistenceFeatures(
+        defineAIPersistence({
+          stores: {
+            messages: stores.messages,
+          },
+        }),
+        ['interrupts'],
+      ),
+    ).toThrow(/interrupts.*stores\.runs.*stores\.interrupts/i)
+  })
+
+  it('persists RUN_FINISHED interrupt outcomes as pending interrupt records', async () => {
+    const persistence = memoryPersistence()
+    const { adapter } = mockAdapter([[runStarted(), interruptFinished()]])
+
+    const chunks = await collect(
+      chat({
+        adapter,
+        messages: [{ role: 'user', content: 'hi' }],
+        runId: 'r1',
+        threadId: 't1',
+        middleware: [
+          withChatPersistence(persistence, { features: ['interrupts'] }),
+        ],
+      }) as AsyncIterable<StreamChunk>,
+    )
+
+    const pending = await persistence.stores.interrupts!.listPending('t1')
+    expect(pending).toHaveLength(1)
+    expect(pending[0]?.interruptId).toBe('interrupt-1')
+    expect((await persistence.stores.runs!.get('r1'))?.status).toBe(
+      'interrupted',
+    )
+    // Persistence is state-only: it never stamps delivery cursors on the stream.
+    expect(chunks.every((chunk) => !('cursor' in chunk))).toBe(true)
+  })
+
+  it('saves thread messages when a messages-enabled run pauses on an interrupt', async () => {
+    const persistence = memoryPersistence()
+    const { adapter } = mockAdapter([[runStarted(), interruptFinished()]])
+
+    await collect(
+      chat({
+        adapter,
+        messages: [{ role: 'user', content: 'hi' }],
+        runId: 'r1',
+        threadId: 't1',
+        middleware: [
+          withChatPersistence(persistence, {
+            features: ['messages', 'interrupts'],
+          }),
+        ],
+      }) as AsyncIterable<StreamChunk>,
+    )
+
+    expect(await persistence.stores.messages!.loadThread('t1')).toEqual([
+      { role: 'user', content: 'hi' },
+    ])
+  })
+
+  it('does not persist duplicate records before terminal interrupt outcome', async () => {
+    const persistence = memoryPersistence()
+    const create = vi.spyOn(persistence.stores.interrupts!, 'create')
+    const { adapter } = mockAdapter([
+      [
+        runStarted(),
+        toolStart(),
+        toolArgs(),
+        {
+          type: EventType.RUN_FINISHED,
+          runId: 'r1',
+          threadId: 't1',
+          finishReason: 'tool_calls',
+          timestamp: 1,
+        },
+      ],
+    ])
+
+    await collect(
+      chat({
+        adapter,
+        messages: [{ role: 'user', content: 'hi' }],
+        tools: [approvalClientTool('clientSearch')],
+        runId: 'r1',
+        threadId: 't1',
+        middleware: [
+          withChatPersistence(persistence, { features: ['interrupts'] }),
+        ],
+      }) as AsyncIterable<StreamChunk>,
+    )
+
+    expect(create).toHaveBeenCalledTimes(1)
+    expect(await persistence.stores.interrupts!.listPending('t1')).toHaveLength(
+      1,
+    )
+  })
+
+  it('blocks normal new input while a thread has pending interrupts', async () => {
+    const persistence = memoryPersistence()
+    await persistence.stores.interrupts!.create({
+      interruptId: 'interrupt-1',
+      runId: 'old-run',
+      threadId: 't1',
+      status: 'pending',
+      requestedAt: 1,
+      payload: {},
+    })
+    const { adapter } = mockAdapter([[interruptFinished()]])
+
+    await expect(
+      collect(
+        chat({
+          adapter,
+          messages: [{ role: 'user', content: 'new input' }],
+          runId: 'r2',
+          threadId: 't1',
+          middleware: [
+            withChatPersistence(persistence, { features: ['interrupts'] }),
+          ],
+        }) as AsyncIterable<StreamChunk>,
+      ),
+    ).rejects.toThrow(/pending interrupt/i)
+
+    expect(await persistence.stores.runs!.get('r2')).toBeNull()
+  })
+
+  it('treats resume entries as interrupt continuation on the same run', async () => {
+    const persistence = memoryPersistence()
+    const first = mockAdapter([[runStarted(), interruptFinished()]])
+    await collect(
+      chat({
+        adapter: first.adapter,
+        messages: [{ role: 'user', content: 'hi' }],
+        runId: 'r1',
+        threadId: 't1',
+        middleware: [
+          withChatPersistence(persistence, { features: ['interrupts'] }),
+        ],
+      }) as AsyncIterable<StreamChunk>,
+    )
+    expect(await persistence.stores.interrupts!.listPending('t1')).toHaveLength(
+      1,
+    )
+
+    const continuation = mockAdapter([
+      [runStarted(), text('continued'), runFinished('r1')],
+    ])
+    const chunks = await collect(
+      chat({
+        adapter: continuation.adapter,
+        messages: [],
+        runId: 'r1',
+        threadId: 't1',
+        resume: [
+          {
+            interruptId: 'interrupt-1',
+            status: 'resolved',
+            payload: { approved: true },
+          },
+        ],
+        middleware: [
+          withChatPersistence(persistence, { features: ['interrupts'] }),
+        ],
+      }) as AsyncIterable<StreamChunk>,
+    )
+
+    expect(continuation.calls).toHaveLength(1)
+    expect(chunks).toContainEqual(
+      expect.objectContaining({ delta: 'continued' }),
+    )
+    expect(await persistence.stores.interrupts!.listPending('t1')).toEqual([])
+    expect(
+      (await persistence.stores.interrupts!.get('interrupt-1'))?.status,
+    ).toBe('resolved')
+  })
+
+  it('applies persisted approval and client-tool resume decisions with empty client messages', async () => {
+    const persistence = memoryPersistence()
+    const toolCallChunks = () => [
+      runStarted(),
+      toolStart(),
+      toolArgs(),
+      {
+        type: EventType.RUN_FINISHED,
+        runId: 'r1',
+        threadId: 't1',
+        finishReason: 'tool_calls',
+        timestamp: 1,
+      } as StreamChunk,
+    ]
+    const first = mockAdapter([toolCallChunks()])
+    await collect(
+      chat({
+        adapter: first.adapter,
+        messages: [{ role: 'user', content: 'hi' }],
+        tools: [approvalClientTool('clientSearch')],
+        runId: 'r1',
+        threadId: 't1',
+        middleware: [
+          withChatPersistence(persistence, { features: ['interrupts'] }),
+        ],
+      }) as AsyncIterable<StreamChunk>,
+    )
+
+    const approvalInterrupt = await persistence.stores.interrupts!.get(
+      'approval_tool-call-1',
+    )
+    expect(approvalInterrupt?.status).toBe('pending')
+
+    const afterApproval = mockAdapter([toolCallChunks()])
+    const approvalChunks = await collect(
+      chat({
+        adapter: afterApproval.adapter,
+        messages: [],
+        tools: [approvalClientTool('clientSearch')],
+        runId: 'r1',
+        threadId: 't1',
+        resume: [
+          {
+            interruptId: 'approval_tool-call-1',
+            status: 'resolved',
+            payload: { approved: true },
+          },
+        ],
+        middleware: [
+          withChatPersistence(persistence, { features: ['interrupts'] }),
+        ],
+      }) as AsyncIterable<StreamChunk>,
+    )
+
+    expect(afterApproval.calls).toHaveLength(1)
+    expect(
+      (
+        afterApproval.calls[0] as { approvals?: ReadonlyMap<string, boolean> }
+      ).approvals?.get('approval_tool-call-1'),
+    ).toBe(true)
+    expect(
+      approvalChunks.find(
+        (chunk) =>
+          chunk.type === EventType.RUN_FINISHED &&
+          chunk.outcome?.type === 'interrupt',
+      ),
+    ).toMatchObject({
+      outcome: {
+        interrupts: [
+          {
+            id: 'client_tool_tool-call-1',
+            reason: 'client_tool_input',
+            toolCallId: 'tool-call-1',
+          },
+        ],
+      },
+    })
+    expect(
+      (await persistence.stores.interrupts!.get('approval_tool-call-1'))
+        ?.status,
+    ).toBe('resolved')
+    expect(
+      (await persistence.stores.interrupts!.get('client_tool_tool-call-1'))
+        ?.status,
+    ).toBe('pending')
+
+    const afterClientTool = mockAdapter([
+      toolCallChunks(),
+      [runStarted(), text('done'), runFinished('r1')],
+    ])
+    const finalChunks = await collect(
+      chat({
+        adapter: afterClientTool.adapter,
+        messages: [],
+        tools: [clientTool('clientSearch')],
+        runId: 'r1',
+        threadId: 't1',
+        resume: [
+          {
+            interruptId: 'client_tool_tool-call-1',
+            status: 'resolved',
+            payload: { answer: 42 },
+          },
+        ],
+        middleware: [
+          withChatPersistence(persistence, { features: ['interrupts'] }),
+        ],
+      }) as AsyncIterable<StreamChunk>,
+    )
+
+    expect(afterClientTool.calls).toHaveLength(2)
+    expect(finalChunks).toContainEqual(
+      expect.objectContaining({
+        type: EventType.TOOL_CALL_RESULT,
+        toolCallId: 'tool-call-1',
+        content: JSON.stringify({ answer: 42 }),
+      }),
+    )
+    expect(finalChunks).toContainEqual(
+      expect.objectContaining({ delta: 'done' }),
+    )
+    expect(await persistence.stores.interrupts!.listPending('t1')).toEqual([])
+  })
+
+  it('rejects invalid resume entries against pending interrupts', async () => {
+    const persistence = memoryPersistence()
+    const first = mockAdapter([[runStarted(), interruptFinished()]])
+    await collect(
+      chat({
+        adapter: first.adapter,
+        messages: [{ role: 'user', content: 'hi' }],
+        runId: 'r1',
+        threadId: 't1',
+        middleware: [
+          withChatPersistence(persistence, { features: ['interrupts'] }),
+        ],
+      }) as AsyncIterable<StreamChunk>,
+    )
+
+    const continuation = mockAdapter([[text('SHOULD NOT RUN')]])
+    await expect(
+      collect(
+        chat({
+          adapter: continuation.adapter,
+          messages: [],
+          runId: 'r1',
+          threadId: 't1',
+          resume: [],
+          middleware: [
+            withChatPersistence(persistence, { features: ['interrupts'] }),
+          ],
+        }) as AsyncIterable<StreamChunk>,
+      ),
+    ).rejects.toThrow(/pending interrupts.*resume is required/i)
+
+    await expect(
+      collect(
+        chat({
+          adapter: continuation.adapter,
+          messages: [],
+          runId: 'r1',
+          threadId: 't1',
+          resume: [{ interruptId: 'stale-interrupt', status: 'resolved' }],
+          middleware: [
+            withChatPersistence(persistence, { features: ['interrupts'] }),
+          ],
+        }) as AsyncIterable<StreamChunk>,
+      ),
+    ).rejects.toThrow(/missing resume entry.*interrupt-1/i)
+
+    expect(continuation.calls).toHaveLength(0)
+    expect(await persistence.stores.interrupts!.listPending('t1')).toHaveLength(
+      1,
+    )
+  })
+
+  it('rejects stale resume entries when a thread has no pending interrupts', async () => {
+    const persistence = memoryPersistence()
+    const first = mockAdapter([[runStarted(), text('done'), runFinished()]])
+    await collect(
+      chat({
+        adapter: first.adapter,
+        messages: [{ role: 'user', content: 'hi' }],
+        runId: 'r1',
+        threadId: 't1',
+        middleware: [
+          withChatPersistence(persistence, { features: ['interrupts'] }),
+        ],
+      }) as AsyncIterable<StreamChunk>,
+    )
+    expect(await persistence.stores.interrupts!.listPending('t1')).toEqual([])
+
+    const continuation = mockAdapter([[text('SHOULD NOT RUN')]])
+    await expect(
+      collect(
+        chat({
+          adapter: continuation.adapter,
+          messages: [],
+          runId: 'r1',
+          threadId: 't1',
+          resume: [{ interruptId: 'stale-interrupt', status: 'resolved' }],
+          middleware: [
+            withChatPersistence(persistence, { features: ['interrupts'] }),
+          ],
+        }) as AsyncIterable<StreamChunk>,
+      ),
+    ).rejects.toThrow(/non-pending interrupt stale-interrupt/i)
+
+    expect(continuation.calls).toHaveLength(0)
+  })
+
+  it('accepts resume only when every pending interrupt has a valid matching entry', async () => {
+    const persistence = memoryPersistence()
+    await persistence.stores.interrupts!.create({
+      interruptId: 'interrupt-1',
+      runId: 'old-run',
+      threadId: 't1',
+      status: 'pending',
+      requestedAt: 1,
+      payload: {},
+    })
+    const bad = mockAdapter([[runStarted(), interruptFinished()]])
+
+    await expect(
+      collect(
+        chat({
+          adapter: bad.adapter,
+          messages: [{ role: 'user', content: 'new input' }],
+          runId: 'r2',
+          threadId: 't1',
+          resume: [{ interruptId: 'different', status: 'resolved' }],
+          middleware: [
+            withChatPersistence(persistence, { features: ['interrupts'] }),
+          ],
+        }) as AsyncIterable<StreamChunk>,
+      ),
+    ).rejects.toThrow(/missing resume entry.*interrupt-1/i)
+
+    const good = mockAdapter([
+      [runStarted(), { ...interruptFinished(), runId: 'r2' }],
+    ])
+    await collect(
+      chat({
+        adapter: good.adapter,
+        messages: [{ role: 'user', content: 'new input' }],
+        runId: 'r2',
+        threadId: 't1',
+        resume: [{ interruptId: 'interrupt-1', status: 'resolved' }],
+        middleware: [
+          withChatPersistence(persistence, { features: ['interrupts'] }),
+        ],
+      }) as AsyncIterable<StreamChunk>,
+    )
+
+    expect(good.calls).toHaveLength(1)
+  })
+
+  it('rejects extra stale resume entries when pending interrupts are satisfied', async () => {
+    const persistence = memoryPersistence()
+    await persistence.stores.interrupts!.create({
+      interruptId: 'interrupt-1',
+      runId: 'old-run',
+      threadId: 't1',
+      status: 'pending',
+      requestedAt: 1,
+      payload: {},
+    })
+    const run = mockAdapter([[text('SHOULD NOT RUN')]])
+
+    await expect(
+      collect(
+        chat({
+          adapter: run.adapter,
+          messages: [{ role: 'user', content: 'new input' }],
+          runId: 'r2',
+          threadId: 't1',
+          resume: [
+            { interruptId: 'interrupt-1', status: 'resolved' },
+            { interruptId: 'stale-interrupt', status: 'resolved' },
+          ],
+          middleware: [
+            withChatPersistence(persistence, { features: ['interrupts'] }),
+          ],
+        }) as AsyncIterable<StreamChunk>,
+      ),
+    ).rejects.toThrow(/non-pending interrupt stale-interrupt/i)
+
+    expect(run.calls).toHaveLength(0)
+    expect(await persistence.stores.interrupts!.listPending('t1')).toHaveLength(
+      1,
+    )
+  })
+
+  it('applies valid resume entries and allows later normal input', async () => {
+    const persistence = memoryPersistence()
+    await persistence.stores.interrupts!.create({
+      interruptId: 'resolve-me',
+      runId: 'old-run',
+      threadId: 't1',
+      status: 'pending',
+      requestedAt: 1,
+      payload: {},
+    })
+    await persistence.stores.interrupts!.create({
+      interruptId: 'cancel-me',
+      runId: 'old-run',
+      threadId: 't1',
+      status: 'pending',
+      requestedAt: 1,
+      payload: {},
+    })
+
+    const resumeRun = mockAdapter([
+      [runStarted(), text('ok'), runFinished('r2')],
+    ])
+    await collect(
+      chat({
+        adapter: resumeRun.adapter,
+        messages: [{ role: 'user', content: 'resume' }],
+        runId: 'r2',
+        threadId: 't1',
+        resume: [
+          {
+            interruptId: 'resolve-me',
+            status: 'resolved',
+            payload: { approved: true },
+          },
+          { interruptId: 'cancel-me', status: 'cancelled' },
+        ],
+        middleware: [
+          withChatPersistence(persistence, { features: ['interrupts'] }),
+        ],
+      }) as AsyncIterable<StreamChunk>,
+    )
+
+    expect(await persistence.stores.interrupts!.listPending('t1')).toEqual([])
+    expect(
+      (await persistence.stores.interrupts!.get('resolve-me'))?.status,
+    ).toBe('resolved')
+    expect(
+      (await persistence.stores.interrupts!.get('resolve-me'))?.response,
+    ).toEqual({ approved: true })
+    expect(
+      (await persistence.stores.interrupts!.get('cancel-me'))?.status,
+    ).toBe('cancelled')
+
+    const nextRun = mockAdapter([
+      [runStarted(), text('next'), runFinished('r3')],
+    ])
+    await collect(
+      chat({
+        adapter: nextRun.adapter,
+        messages: [{ role: 'user', content: 'next' }],
+        runId: 'r3',
+        threadId: 't1',
+        middleware: [
+          withChatPersistence(persistence, { features: ['interrupts'] }),
+        ],
+      }) as AsyncIterable<StreamChunk>,
+    )
+    expect(nextRun.calls).toHaveLength(1)
+  })
+
+  it('marks terminal interrupt outcomes as interrupted', async () => {
+    const persistence = memoryPersistence()
+    const { adapter } = mockAdapter([[runStarted(), interruptFinished()]])
+
+    await collect(
+      chat({
+        adapter,
+        messages: [{ role: 'user', content: 'hi' }],
+        runId: 'r1',
+        threadId: 't1',
+        middleware: [
+          withChatPersistence(persistence, { features: ['interrupts'] }),
+        ],
+      }) as AsyncIterable<StreamChunk>,
+    )
+
+    expect((await persistence.stores.runs!.get('r1'))?.status).toBe(
+      'interrupted',
+    )
+    expect(await persistence.stores.interrupts!.listPending('t1')).toHaveLength(
+      1,
+    )
+  })
+})
diff --git a/packages/ai-persistence/tests/memory.conformance.test.ts b/packages/ai-persistence/tests/memory.conformance.test.ts
new file mode 100644
index 000000000..0b382b6a0
--- /dev/null
+++ b/packages/ai-persistence/tests/memory.conformance.test.ts
@@ -0,0 +1,4 @@
+import { runPersistenceConformance } from '../src/testkit/conformance'
+import { memoryPersistence } from '../src/memory'
+
+runPersistenceConformance('memory', () => memoryPersistence())
diff --git a/packages/ai-persistence/tests/memory.test.ts b/packages/ai-persistence/tests/memory.test.ts
new file mode 100644
index 000000000..5676d0f7c
--- /dev/null
+++ b/packages/ai-persistence/tests/memory.test.ts
@@ -0,0 +1,317 @@
+import { describe, expect, it } from 'vitest'
+import { memoryPersistence } from '../src/memory'
+import {
+  defineAIPersistence,
+  defineChatPersistence,
+  validatePersistenceFeatures,
+} from '../src/types'
+import type { AIPersistence, ChatPersistence } from '../src/types'
+
+describe('memoryPersistence', () => {
+  it('returns a namespaced AIPersistence with every state store present', () => {
+    const p = memoryPersistence()
+    expect(p.stores.messages).toBeDefined()
+    expect(p.stores.runs).toBeDefined()
+    expect(p.stores.interrupts).toBeDefined()
+    expect(p.stores.artifacts).toBeDefined()
+    expect(p.stores.blobs).toBeDefined()
+    expect(p.stores.locks).toBeDefined()
+  })
+
+  it('exposes only state stores (no delivery event stores)', () => {
+    const stores = memoryPersistence().stores as Record<string, unknown>
+    expect('publicEvents' in stores).toBe(false)
+    expect('internalEvents' in stores).toBe(false)
+  })
+
+  it('defineAIPersistence is an identity helper', () => {
+    const persistence = memoryPersistence()
+    expect(defineAIPersistence(persistence)).toBe(persistence)
+  })
+
+  it('keeps deprecated ChatPersistence compatibility exports as aliases', () => {
+    const persistence: ChatPersistence = memoryPersistence()
+    const aiPersistence: AIPersistence = persistence
+    expect(defineChatPersistence(persistence)).toBe(aiPersistence)
+  })
+
+  it('fails loudly when requested feature stores are missing', () => {
+    expect(() =>
+      validatePersistenceFeatures(
+        defineAIPersistence({
+          stores: { messages: memoryPersistence().stores.messages },
+        }),
+        ['interrupts'],
+      ),
+    ).toThrow(/interrupts.*stores\.runs.*stores\.interrupts/i)
+  })
+
+  it('allows message-only persistence without event stores', () => {
+    const messages = memoryPersistence().stores.messages!
+    expect(() =>
+      validatePersistenceFeatures(
+        defineAIPersistence({ stores: { messages } }),
+        ['messages'],
+      ),
+    ).not.toThrow()
+  })
+
+  it('allows blob persistence when a blob store is present', () => {
+    const blobs = memoryPersistence().stores.blobs!
+    expect(() =>
+      validatePersistenceFeatures(defineAIPersistence({ stores: { blobs } }), [
+        'blobs',
+      ]),
+    ).not.toThrow()
+  })
+
+  describe('runs', () => {
+    it('createOrResume is idempotent and update patches status', async () => {
+      const { runs } = memoryPersistence().stores
+      const a = await runs!.createOrResume({
+        runId: 'r1',
+        threadId: 't1',
+        startedAt: 100,
+      })
+      expect(a.status).toBe('running')
+      // Resume returns the SAME record, not a fresh one.
+      const b = await runs!.createOrResume({
+        runId: 'r1',
+        threadId: 't1',
+        startedAt: 999,
+      })
+      expect(b.startedAt).toBe(100)
+
+      await runs!.update('r1', { status: 'completed', finishedAt: 200 })
+      const got = await runs!.get('r1')
+      expect(got?.status).toBe('completed')
+      expect(got?.finishedAt).toBe(200)
+    })
+  })
+
+  describe('messages', () => {
+    it('round-trips a thread transcript', async () => {
+      const { messages } = memoryPersistence().stores
+      expect(await messages!.loadThread('t1')).toEqual([])
+      await messages!.saveThread('t1', [{ role: 'user', content: 'hi' }])
+      expect(await messages!.loadThread('t1')).toEqual([
+        { role: 'user', content: 'hi' },
+      ])
+    })
+  })
+
+  describe('interrupts', () => {
+    it('creates, resolves, and lists pending interrupts by thread', async () => {
+      const { interrupts } = memoryPersistence().stores
+      await interrupts!.create({
+        interruptId: 'i1',
+        runId: 'r1',
+        threadId: 't1',
+        status: 'pending',
+        requestedAt: 1,
+        payload: { kind: 'approval' },
+      })
+      expect((await interrupts!.get('i1'))?.status).toBe('pending')
+      expect(await interrupts!.listPending('t1')).toHaveLength(1)
+      await interrupts!.resolve('i1', { action: 'approve' })
+      expect((await interrupts!.get('i1'))?.status).toBe('resolved')
+      expect(await interrupts!.listPending('t1')).toHaveLength(0)
+    })
+
+    it('lists interrupts and pending interrupts by run', async () => {
+      const { interrupts } = memoryPersistence().stores
+      await interrupts!.create({
+        interruptId: 'i1',
+        runId: 'r1',
+        threadId: 't1',
+        status: 'pending',
+        requestedAt: 1,
+        payload: { kind: 'approval' },
+      })
+      await interrupts!.create({
+        interruptId: 'i2',
+        runId: 'r1',
+        threadId: 't2',
+        status: 'pending',
+        requestedAt: 2,
+        payload: { kind: 'input' },
+      })
+      await interrupts!.create({
+        interruptId: 'i3',
+        runId: 'r2',
+        threadId: 't1',
+        status: 'pending',
+        requestedAt: 3,
+        payload: { kind: 'other' },
+      })
+
+      await interrupts!.resolve('i2')
+
+      expect(
+        (await interrupts!.listByRun('r1')).map(
+          (interrupt) => interrupt.interruptId,
+        ),
+      ).toEqual(['i1', 'i2'])
+      expect(
+        (await interrupts!.listPendingByRun('r1')).map(
+          (interrupt) => interrupt.interruptId,
+        ),
+      ).toEqual(['i1'])
+    })
+  })
+
+  describe('artifacts', () => {
+    it('saves, gets, and lists by run', async () => {
+      const { artifacts } = memoryPersistence().stores
+      await artifacts!.save({
+        artifactId: 'art1',
+        runId: 'r1',
+        threadId: 't1',
+        name: 'out.txt',
+        mimeType: 'text/plain',
+        size: 3,
+        createdAt: 1,
+      })
+      expect((await artifacts!.get('art1'))?.name).toBe('out.txt')
+      expect(await artifacts!.list('r1')).toHaveLength(1)
+      expect(await artifacts!.list('other')).toHaveLength(0)
+    })
+
+    it('deletes individual artifacts', async () => {
+      const { artifacts } = memoryPersistence().stores
+      await artifacts!.save({
+        artifactId: 'art1',
+        runId: 'r1',
+        threadId: 't1',
+        name: 'out.txt',
+        mimeType: 'text/plain',
+        size: 3,
+        createdAt: 1,
+      })
+
+      await artifacts!.delete!('art1')
+
+      expect(await artifacts!.get('art1')).toBeNull()
+      expect(await artifacts!.list('r1')).toEqual([])
+    })
+
+    it('deletes artifacts for a run without touching other runs', async () => {
+      const { artifacts } = memoryPersistence().stores
+      await artifacts!.save({
+        artifactId: 'art1',
+        runId: 'r1',
+        threadId: 't1',
+        name: 'one.txt',
+        mimeType: 'text/plain',
+        size: 3,
+        createdAt: 1,
+      })
+      await artifacts!.save({
+        artifactId: 'art2',
+        runId: 'r1',
+        threadId: 't1',
+        name: 'two.txt',
+        mimeType: 'text/plain',
+        size: 3,
+        createdAt: 2,
+      })
+      await artifacts!.save({
+        artifactId: 'art3',
+        runId: 'r2',
+        threadId: 't1',
+        name: 'three.txt',
+        mimeType: 'text/plain',
+        size: 5,
+        createdAt: 3,
+      })
+
+      await artifacts!.deleteForRun!('r1')
+
+      expect(await artifacts!.list('r1')).toEqual([])
+      expect((await artifacts!.get('art3'))?.name).toBe('three.txt')
+    })
+  })
+
+  describe('blobs', () => {
+    it('puts, reads, heads, lists, and deletes blobs', async () => {
+      const { blobs } = memoryPersistence().stores
+
+      const written = await blobs!.put('runs/r1/out.txt', 'hello', {
+        contentType: 'text/plain',
+        customMetadata: { runId: 'r1' },
+      })
+
+      expect(written.key).toBe('runs/r1/out.txt')
+      expect(written.size).toBe(5)
+      expect(written.contentType).toBe('text/plain')
+      expect(written.customMetadata).toEqual({ runId: 'r1' })
+
+      const head = await blobs!.head('runs/r1/out.txt')
+      expect(head).toMatchObject({
+        key: 'runs/r1/out.txt',
+        size: 5,
+        contentType: 'text/plain',
+      })
+
+      const object = await blobs!.get('runs/r1/out.txt')
+      expect(await object!.text()).toBe('hello')
+      expect(new Uint8Array(await object!.arrayBuffer())).toEqual(
+        new TextEncoder().encode('hello'),
+      )
+
+      await blobs!.put('runs/r2/out.txt', new Uint8Array([1, 2, 3]))
+      expect(
+        (await blobs!.list({ prefix: 'runs/r1/' })).objects.map(
+          (record) => record.key,
+        ),
+      ).toEqual(['runs/r1/out.txt'])
+
+      await blobs!.delete('runs/r1/out.txt')
+
+      expect(await blobs!.get('runs/r1/out.txt')).toBeNull()
+      expect(await blobs!.head('runs/r1/out.txt')).toBeNull()
+    })
+
+    it('uses the same string ordering for pagination cursors as sorting', async () => {
+      const { blobs } = memoryPersistence().stores
+      await blobs!.put('k-a', 'a')
+      await blobs!.put('k-B', 'b')
+      await blobs!.put('k-c', 'c')
+
+      const first = await blobs!.list({ prefix: 'k-', limit: 1 })
+      const second = await blobs!.list({
+        prefix: 'k-',
+        limit: 10,
+        cursor: first.cursor,
+      })
+
+      expect([
+        ...first.objects.map((record) => record.key),
+        ...second.objects.map((record) => record.key),
+      ]).toEqual(['k-B', 'k-a', 'k-c'])
+    })
+
+    it('treats limit zero as an empty untruncated page without a cursor', async () => {
+      const { blobs } = memoryPersistence().stores
+      await blobs!.put('runs/r1/out.txt', 'hello')
+
+      await expect(blobs!.list({ limit: 0 })).resolves.toEqual({
+        objects: [],
+        truncated: false,
+      })
+    })
+  })
+
+  describe('metadata', () => {
+    it('returns null for missing metadata and preserves stored undefined', async () => {
+      const { metadata } = memoryPersistence().stores
+      expect(await metadata!.get('scope', 'missing')).toBeNull()
+
+      await metadata!.set('scope', 'present', undefined)
+      expect(await metadata!.get('scope', 'present')).toBeUndefined()
+
+      await metadata!.delete('scope', 'present')
+      expect(await metadata!.get('scope', 'present')).toBeNull()
+    })
+  })
+})
diff --git a/packages/ai-persistence/tests/state-only.test.ts b/packages/ai-persistence/tests/state-only.test.ts
new file mode 100644
index 000000000..ecefc0917
--- /dev/null
+++ b/packages/ai-persistence/tests/state-only.test.ts
@@ -0,0 +1,105 @@
+import { describe, expect, it } from 'vitest'
+import { EventType, chat } from '@tanstack/ai'
+import type { AnyTextAdapter, StreamChunk } from '@tanstack/ai'
+import { memoryPersistence } from '../src/memory'
+import { withChatPersistence } from '../src/middleware'
+
+function mockAdapter(iterations: Array<Array<StreamChunk>>) {
+  const calls: Array<unknown> = []
+  let i = 0
+  const adapter = {
+    kind: 'text',
+    name: 'mock',
+    model: 'test-model',
+    '~types': {},
+    chatStream: (opts: unknown) => {
+      calls.push(opts)
+      const chunks = iterations[i] ?? []
+      i++
+      return (async function* () {
+        for (const c of chunks) yield c
+      })()
+    },
+    structuredOutput: async () => ({ data: {}, rawText: '{}' }),
+  } as unknown as AnyTextAdapter
+  return { adapter, calls }
+}
+
+const script = (): Array<Array<StreamChunk>> => [
+  [
+    { type: EventType.RUN_STARTED, runId: 'r1', threadId: 't1', timestamp: 1 },
+    {
+      type: EventType.TEXT_MESSAGE_CONTENT,
+      messageId: 'm1',
+      delta: 'hello world',
+      timestamp: 1,
+    },
+    {
+      type: EventType.RUN_FINISHED,
+      runId: 'r1',
+      threadId: 't1',
+      finishReason: 'stop',
+      timestamp: 1,
+    },
+  ],
+]
+
+async function collect(stream: AsyncIterable<StreamChunk>) {
+  const out: Array<StreamChunk> = []
+  for await (const c of stream) out.push(c)
+  return out
+}
+
+describe('state-only persistence', () => {
+  it('exposes only state stores (no delivery event stores)', () => {
+    const stores = memoryPersistence().stores as Record<string, unknown>
+    expect('publicEvents' in stores).toBe(false)
+    expect('internalEvents' in stores).toBe(false)
+    // The delivery stream sink is gone too.
+    expect('stream' in memoryPersistence()).toBe(false)
+  })
+
+  it('persists thread messages and run status', async () => {
+    const persistence = memoryPersistence()
+    const { adapter } = mockAdapter(script())
+
+    await collect(
+      chat({
+        adapter,
+        messages: [{ role: 'user', content: 'hi' }],
+        runId: 'r1',
+        threadId: 't1',
+        middleware: [withChatPersistence(persistence)],
+      }) as AsyncIterable<StreamChunk>,
+    )
+
+    expect((await persistence.stores.runs!.get('r1'))?.status).toBe('completed')
+    expect(
+      (await persistence.stores.messages!.loadThread('t1')).length,
+    ).toBeGreaterThan(0)
+  })
+
+  it('produces chunks byte-identical to a non-persisted run (no cursor)', async () => {
+    const persisted = await collect(
+      chat({
+        adapter: mockAdapter(script()).adapter,
+        messages: [{ role: 'user', content: 'hi' }],
+        runId: 'r1',
+        threadId: 't1',
+        middleware: [withChatPersistence(memoryPersistence())],
+      }) as AsyncIterable<StreamChunk>,
+    )
+
+    const plain = await collect(
+      chat({
+        adapter: mockAdapter(script()).adapter,
+        messages: [{ role: 'user', content: 'hi' }],
+        runId: 'r1',
+        threadId: 't1',
+      }) as AsyncIterable<StreamChunk>,
+    )
+
+    expect(JSON.stringify(persisted)).toEqual(JSON.stringify(plain))
+    expect(persisted.every((c) => !('cursor' in c))).toBe(true)
+  })
+})
diff --git a/packages/ai-persistence/tests/with-persistence.test.ts b/packages/ai-persistence/tests/with-persistence.test.ts
new file mode 100644
index 000000000..070368765
--- /dev/null
+++ b/packages/ai-persistence/tests/with-persistence.test.ts
@@ -0,0 +1,280 @@
+import { describe, expect, it } from 'vitest'
+import { EventType, chat } from '@tanstack/ai'
+import type { AnyTextAdapter, StreamChunk } from '@tanstack/ai'
+import { memoryPersistence } from '../src/memory'
+import { withChatPersistence } from '../src/middleware'
+import { defineAIPersistence } from '../src/types'
+
+// --- minimal mock text adapter ---------------------------------------------
+
+function mockAdapter(iterations: Array<Array<StreamChunk>>) {
+  const calls: Array<unknown> = []
+  let i = 0
+  const adapter = {
+    kind: 'text',
+    name: 'mock',
+    model: 'test-model',
+    '~types': {},
+    chatStream: (opts: unknown) => {
+      calls.push(opts)
+      const chunks = iterations[i] ?? []
+      i++
+      return (async function* () {
+        for (const c of chunks) yield c
+      })()
+    },
+    structuredOutput: async () => ({ data: {}, rawText: '{}' }),
+  } as unknown as AnyTextAdapter
+  return { adapter, calls }
+}
+
+const ev = {
+  runStarted: (runId = 'r1', threadId = 't1'): StreamChunk => ({
+    type: EventType.RUN_STARTED,
+    runId,
+    threadId,
+    timestamp: 1,
+  }),
+  text: (delta: string): StreamChunk => ({
+    type: EventType.TEXT_MESSAGE_CONTENT,
+    messageId: 'm1',
+    delta,
+    timestamp: 1,
+  }),
+  runFinished: (runId = 'r1', threadId = 't1'): StreamChunk => ({
+    type: EventType.RUN_FINISHED,
+    runId,
+    threadId,
+    finishReason: 'stop',
+    timestamp: 1,
+  }),
+  interrupted: (interruptId = 'interrupt-1'): StreamChunk => ({
+    type: EventType.RUN_FINISHED,
+    runId: 'r1',
+    threadId: 't1',
+    finishReason: 'stop',
+    timestamp: 1,
+    outcome: {
+      type: 'interrupt',
+      interrupts: [
+        {
+          id: interruptId,
+          reason: 'approval_required',
+          toolCallId: 'tool-1',
+          metadata: { kind: 'approval' },
+        },
+      ],
+    },
+  }),
+}
+
+async function collect(stream: AsyncIterable<StreamChunk>) {
+  const out: Array<StreamChunk> = []
+  for await (const c of stream) out.push(c)
+  return out
+}
+
+async function expectCollectRejects(
+  stream: AsyncIterable<StreamChunk>,
+  pattern: RegExp,
+) {
+  await expect(collect(stream)).rejects.toThrow(pattern)
+}
+
+describe('withChatPersistence (state-only)', () => {
+  it('completes the run and saves the transcript', async () => {
+    const persistence = memoryPersistence()
+    const { adapter } = mockAdapter([
+      [ev.runStarted(), ev.text('hello'), ev.runFinished()],
+    ])
+
+    const chunks = await collect(
+      chat({
+        adapter,
+        messages: [{ role: 'user', content: 'hi' }],
+        runId: 'r1',
+        threadId: 't1',
+        middleware: [withChatPersistence(persistence)],
+      }) as AsyncIterable<StreamChunk>,
+    )
+
+    // The persistence middleware never stamps delivery cursors on the stream.
+    expect(chunks.length).toBeGreaterThan(0)
+    expect(chunks.every((c) => !('cursor' in c))).toBe(true)
+
+    // Run is completed and the transcript is saved.
+    expect((await persistence.stores.runs!.get('r1'))?.status).toBe('completed')
+    expect(
+      (await persistence.stores.messages!.loadThread('t1')).length,
+    ).toBeGreaterThan(0)
+  })
+
+  it('records an interrupt and marks the run interrupted', async () => {
+    const persistence = memoryPersistence()
+    const { adapter } = mockAdapter([[ev.runStarted(), ev.interrupted()]])
+
+    await collect(
+      chat({
+        adapter,
+        messages: [{ role: 'user', content: 'hi' }],
+        runId: 'r1',
+        threadId: 't1',
+        middleware: [withChatPersistence(persistence)],
+      }) as AsyncIterable<StreamChunk>,
+    )
+
+    expect((await persistence.stores.runs!.get('r1'))?.status).toBe(
+      'interrupted',
+    )
+    expect(await persistence.stores.interrupts!.listPending('t1')).toHaveLength(
+      1,
+    )
+  })
+
+  it('blocks normal new input while a thread has pending interrupts', async () => {
+    const persistence = memoryPersistence()
+    const first = mockAdapter([[ev.runStarted(), ev.interrupted()]])
+
+    await collect(
+      chat({
+        adapter: first.adapter,
+        messages: [{ role: 'user', content: 'hi' }],
+        runId: 'r1',
+        threadId: 't1',
+        middleware: [withChatPersistence(persistence)],
+      }) as AsyncIterable<StreamChunk>,
+    )
+
+    const next = mockAdapter([[ev.text('SHOULD NOT RUN')]])
+    await expectCollectRejects(
+      chat({
+        adapter: next.adapter,
+        messages: [{ role: 'user', content: 'new input' }],
+        runId: 'r2',
+        threadId: 't1',
+        middleware: [withChatPersistence(persistence)],
+      }) as AsyncIterable<StreamChunk>,
+      /pending interrupts.*resume is required/i,
+    )
+    expect(next.calls.length).toBe(0)
+  })
+
+  it('requires resume entries to match all pending interrupts', async () => {
+    const persistence = memoryPersistence()
+    const first = mockAdapter([[ev.runStarted(), ev.interrupted()]])
+
+    await collect(
+      chat({
+        adapter: first.adapter,
+        messages: [{ role: 'user', content: 'hi' }],
+        runId: 'r1',
+        threadId: 't1',
+        middleware: [withChatPersistence(persistence)],
+      }) as AsyncIterable<StreamChunk>,
+    )
+
+    const next = mockAdapter([[ev.text('SHOULD NOT RUN')]])
+    await expectCollectRejects(
+      chat({
+        adapter: next.adapter,
+        messages: [{ role: 'user', content: 'new input' }],
+        runId: 'r2',
+        threadId: 't1',
+        resume: [{ interruptId: 'other-interrupt', status: 'resolved' }],
+        middleware: [withChatPersistence(persistence)],
+      }) as AsyncIterable<StreamChunk>,
+      /missing resume entry for pending interrupt interrupt-1/i,
+    )
+    expect(next.calls.length).toBe(0)
+  })
+
+  it('applies matching resume entries and then allows new input', async () => {
+    const persistence = memoryPersistence()
+    const first = mockAdapter([[ev.runStarted(), ev.interrupted()]])
+
+    await collect(
+      chat({
+        adapter: first.adapter,
+        messages: [{ role: 'user', content: 'hi' }],
+        runId: 'r1',
+        threadId: 't1',
+        middleware: [withChatPersistence(persistence)],
+      }) as AsyncIterable<StreamChunk>,
+    )
+
+    const next = mockAdapter([[ev.runStarted('r2', 't1'), ev.text('fresh')]])
+    const chunks = await collect(
+      chat({
+        adapter: next.adapter,
+        messages: [{ role: 'user', content: 'new input' }],
+        runId: 'r2',
+        threadId: 't1',
+        resume: [
+          {
+            interruptId: 'interrupt-1',
+            status: 'resolved',
+            payload: { approved: true },
+          },
+        ],
+        middleware: [withChatPersistence(persistence)],
+      }) as AsyncIterable<StreamChunk>,
+    )
+
+    expect(next.calls.length).toBe(1)
+    expect(
+      chunks.some((chunk) => chunk.type === EventType.TEXT_MESSAGE_CONTENT),
+    ).toBe(true)
+    expect(
+      (await persistence.stores.interrupts!.get('interrupt-1'))?.status,
+    ).toBe('resolved')
+  })
+
+  it('persists messages without requiring a run store', async () => {
+    const full = memoryPersistence()
+    const persistence = defineAIPersistence({
+      stores: { messages: full.stores.messages },
+    })
+    const { adapter } = mockAdapter([
+      [ev.runStarted(), ev.text('hello'), ev.runFinished()],
+    ])
+
+    await collect(
+      chat({
+        adapter,
+        messages: [{ role: 'user', content: 'hi' }],
+        runId: 'r1',
+        threadId: 't1',
+        middleware: [
+          withChatPersistence(persistence, { features: ['messages'] }),
+        ],
+      }) as AsyncIterable<StreamChunk>,
+    )
+
+    expect(await persistence.stores.messages!.loadThread('t1')).not.toEqual([])
+  })
+
+  it('fails loudly when interrupts are requested without a run store', () => {
+    const persistence = defineAIPersistence({
+      stores: { messages: memoryPersistence().stores.messages },
+    })
+
+    expect(() =>
+      withChatPersistence(persistence, { features: ['interrupts'] }),
+    ).toThrow(/interrupts.*stores\.runs.*stores\.interrupts/i)
+  })
+
+  it('is a no-op without the middleware: the stream is unchanged', async () => {
+    const { adapter } = mockAdapter([
+      [ev.runStarted(), ev.text('plain'), ev.runFinished()],
+    ])
+    const chunks = await collect(
+      chat({
+        adapter,
+        messages: [{ role: 'user', content: 'hi' }],
+        runId: 'r1',
+        threadId: 't1',
+      }) as AsyncIterable<StreamChunk>,
+    )
+    expect(chunks.every((c) => !('cursor' in c))).toBe(true)
+  })
+})
diff --git a/packages/ai-persistence/tsconfig.json b/packages/ai-persistence/tsconfig.json
new file mode 100644
index 000000000..c38689f4e
--- /dev/null
+++ b/packages/ai-persistence/tsconfig.json
@@ -0,0 +1,8 @@
+{
+  "extends": "../../tsconfig.base.json",
+  "compilerOptions": {
+    "outDir": "dist"
+  },
+  "include": ["src", "tests"],
+  "exclude": ["node_modules", "dist"]
+}
diff --git a/packages/ai-persistence/vite.config.ts b/packages/ai-persistence/vite.config.ts
new file mode 100644
index 000000000..95f0f3d72
--- /dev/null
+++ b/packages/ai-persistence/vite.config.ts
@@ -0,0 +1,41 @@
+import { defineConfig, mergeConfig } from 'vitest/config'
+import { tanstackViteConfig } from '@tanstack/vite-config'
+import packageJson from './package.json'
+
+const config = defineConfig({
+  test: {
+    name: packageJson.name,
+    dir: './',
+    watch: false,
+
+    globals: true,
+    environment: 'node',
+    include: ['tests/**/*.test.ts'],
+    coverage: {
+      provider: 'v8',
+      reporter: ['text', 'json', 'html', 'lcov'],
+      exclude: [
+        'node_modules/',
+        'dist/',
+        'tests/',
+        '**/*.test.ts',
+        '**/*.config.ts',
+        '**/types.ts',
+      ],
+      include: ['src/**/*.ts'],
+    },
+  },
+})
+
+export default mergeConfig(
+  config,
+  tanstackViteConfig({
+    entry: ['./src/index.ts', './src/testkit/conformance.ts'],
+    srcDir: './src',
+    // The conformance testkit imports Vitest; keep it external so the built
+    // artifact references the consumer's Vitest at test time instead of
+    // bundling the runner.
+    externalDeps: ['vitest'],
+    cjs: false,
+  }),
+)
diff --git a/packages/ai-preact/src/types.ts b/packages/ai-preact/src/types.ts
index faa04edae..91aee1804 100644
--- a/packages/ai-preact/src/types.ts
+++ b/packages/ai-preact/src/types.ts
@@ -1,9 +1,16 @@
-import type { AnyClientTool, ModelMessage, SchemaInput } from '@tanstack/ai'
+import type {
+  AnyClientTool,
+  ModelMessage,
+  RunAgentResumeItem,
+  SchemaInput,
+} from '@tanstack/ai'
 import type {
   AIDevtoolsDisplayOptions,
   ChatClientOptions,
   ChatClientState,
+  ChatPendingInterrupt,
   ChatRequestBody,
+  ChatResumeState,
   ClientContextOptionFromTools,
   ConnectionStatus,
   DistributedOmit,
@@ -43,6 +50,7 @@ export type UseChatOptions<
   | 'onSubscriptionChange'
   | 'onConnectionStatusChange'
   | 'onSessionGeneratingChange'
+  | 'onResumeStateChange'
   | 'context'
   | 'devtools'
 > & {
@@ -96,6 +104,13 @@ export interface UseChatReturn<
     approved: boolean
   }) => Promise<void>
 
+  resumeState: ChatResumeState | null
+  pendingInterrupts: Array<ChatPendingInterrupt>
+  resumeInterrupts: (
+    resume: Array<RunAgentResumeItem>,
+    state?: ChatResumeState,
+  ) => Promise<boolean>
+
   /**
    * Reload the last assistant message
    */
diff --git a/packages/ai-preact/src/use-chat.ts b/packages/ai-preact/src/use-chat.ts
index e10cb171d..3ba38f54e 100644
--- a/packages/ai-preact/src/use-chat.ts
+++ b/packages/ai-preact/src/use-chat.ts
@@ -10,10 +10,16 @@ import {
 } from 'preact/hooks'
 import type {
   ChatClientState,
+  ChatPendingInterrupt,
+  ChatResumeState,
   ConnectionStatus,
   InferredClientContext,
 } from '@tanstack/ai-client'
-import type { AnyClientTool, ModelMessage } from '@tanstack/ai'
+import type {
+  AnyClientTool,
+  ModelMessage,
+  RunAgentResumeItem,
+} from '@tanstack/ai'
 
 import type {
   MultimodalContent,
@@ -39,6 +45,12 @@ export function useChat<
   const [connectionStatus, setConnectionStatus] =
     useState<ConnectionStatus>('disconnected')
   const [sessionGenerating, setSessionGenerating] = useState(false)
+  const [resumeState, setResumeState] = useState<ChatResumeState | null>(
+    options.initialResumeSnapshot?.resumeState ?? null,
+  )
+  const [pendingInterrupts, setPendingInterrupts] = useState<
+    Array<ChatPendingInterrupt>
+  >(options.initialResumeSnapshot?.pendingInterrupts ?? [])
 
   // Track current messages in a ref to preserve them when client is recreated
   const messagesRef = useRef<Array<UIMessage<TTools>>>(
@@ -49,10 +61,20 @@ export function useChat<
   const cleanupInvalidationRef = useRef<ReturnType<typeof setTimeout> | null>(
     null,
   )
+  const cleanupDisposalRef = useRef<{
+    client: ChatClient
+    timeout: ReturnType<typeof setTimeout>
+  } | null>(null)
   const optionsRef = useRef<UseChatOptions<TTools, TContext>>(options)
 
   optionsRef.current = options
 
+  const syncResumeState = useCallback((target: ChatClient | null) => {
+    if (!target) return
+    setResumeState(target.getResumeState())
+    setPendingInterrupts(target.getPendingInterrupts())
+  }, [])
+
   useEffect(() => {
     messagesRef.current = messages
   }, [messages])
@@ -85,6 +107,9 @@ export function useChat<
       ...(initialOptions.persistence !== undefined && {
         persistence: initialOptions.persistence,
       }),
+      ...(initialOptions.initialResumeSnapshot !== undefined && {
+        initialResumeSnapshot: initialOptions.initialResumeSnapshot,
+      }),
       ...(initialOptions.context !== undefined && {
         context: initialOptions.context,
       }),
@@ -130,6 +155,7 @@ export function useChat<
       onLoadingChange: (newIsLoading: boolean) => {
         if (activeClientRef.current !== instance) return
         setIsLoading(newIsLoading)
+        syncResumeState(instance)
       },
       onStatusChange: (newStatus: ChatClientState) => {
         if (activeClientRef.current !== instance) return
@@ -151,10 +177,15 @@ export function useChat<
         if (activeClientRef.current !== instance) return
         setSessionGenerating(isGenerating)
       },
+      onResumeStateChange: (nextResumeState, nextPendingInterrupts) => {
+        if (activeClientRef.current !== instance) return
+        setResumeState(nextResumeState)
+        setPendingInterrupts(nextPendingInterrupts)
+      },
     })
     activeClientRef.current = instance
     return instance
-  }, [clientId])
+  }, [clientId, syncResumeState])
 
   useEffect(() => {
     const clientMessages = client.getMessages()
@@ -191,12 +222,20 @@ export function useChat<
   // DO NOT include isLoading in dependencies - that would cause the cleanup
   // to run when isLoading changes, aborting continuation requests.
   useEffect(() => {
+    if (cleanupDisposalRef.current?.client === client) {
+      clearTimeout(cleanupDisposalRef.current.timeout)
+      cleanupDisposalRef.current = null
+    }
     if (cleanupInvalidationRef.current) {
       clearTimeout(cleanupInvalidationRef.current)
       cleanupInvalidationRef.current = null
     }
     activeClientRef.current = client
     client.mountDevtools()
+    // Delivery-durability resume is transparent: the resumable SSE connection
+    // adapter reattaches via the browser's native Last-Event-ID on reconnect.
+    // We only seed interrupt (state) resume from the client here.
+    syncResumeState(client)
 
     return () => {
       cleanupInvalidationRef.current = setTimeout(() => {
@@ -214,29 +253,50 @@ export function useChat<
       } else {
         client.stop()
       }
-      client.dispose()
+      const disposal = {
+        client,
+        timeout: setTimeout(() => {
+          client.dispose()
+          if (cleanupDisposalRef.current === disposal) {
+            cleanupDisposalRef.current = null
+          }
+        }, 0),
+      }
+      cleanupDisposalRef.current = disposal
     }
-  }, [client])
+  }, [client, syncResumeState])
 
   // All callback options are read through optionsRef at call time, so fresh
   // closures from each render are picked up without recreating the client.
   const sendMessage = useCallback(
     async (content: string | MultimodalContent) => {
-      await client.sendMessage(content)
+      try {
+        await client.sendMessage(content)
+      } finally {
+        syncResumeState(client)
+      }
     },
-    [client],
+    [client, syncResumeState],
   )
 
   const append = useCallback(
     async (message: ModelMessage | UIMessage) => {
-      await client.append(message)
+      try {
+        await client.append(message)
+      } finally {
+        syncResumeState(client)
+      }
     },
-    [client],
+    [client, syncResumeState],
   )
 
   const reload = useCallback(async () => {
-    await client.reload()
-  }, [client])
+    try {
+      await client.reload()
+    } finally {
+      syncResumeState(client)
+    }
+  }, [client, syncResumeState])
 
   const stop = useCallback(() => {
     client.stop()
@@ -244,7 +304,8 @@ export function useChat<
 
   const clear = useCallback(() => {
     client.clear()
-  }, [client])
+    syncResumeState(client)
+  }, [client, syncResumeState])
 
   const setMessagesManually = useCallback(
     (newMessages: Array<UIMessage<TTools>>) => {
@@ -269,8 +330,18 @@ export function useChat<
   const addToolApprovalResponse = useCallback(
     async (response: { id: string; approved: boolean }) => {
       await client.addToolApprovalResponse(response)
+      syncResumeState(client)
     },
-    [client],
+    [client, syncResumeState],
+  )
+
+  const resumeInterrupts = useCallback(
+    async (resumeItems: Array<RunAgentResumeItem>, state?: ChatResumeState) => {
+      const result = await client.resumeInterrupts(resumeItems, state)
+      syncResumeState(client)
+      return result
+    },
+    [client, syncResumeState],
   )
 
   const renderedMessages = client.getMessages()
@@ -291,5 +362,8 @@ export function useChat<
     clear,
     addToolResult,
     addToolApprovalResponse,
+    resumeState,
+    pendingInterrupts,
+    resumeInterrupts,
   }
 }
diff --git a/packages/ai-preact/tests/use-chat.test.ts b/packages/ai-preact/tests/use-chat.test.ts
index 11e874c41..205decf7a 100644
--- a/packages/ai-preact/tests/use-chat.test.ts
+++ b/packages/ai-preact/tests/use-chat.test.ts
@@ -4,7 +4,7 @@ import type { SubscribeConnectionAdapter } from '@tanstack/ai-client'
 import { act, renderHook, waitFor } from '@testing-library/preact'
 import { StrictMode } from 'preact/compat'
 import { useState } from 'preact/hooks'
-import { describe, expect, it, vi } from 'vitest'
+import { afterEach, describe, expect, it, vi } from 'vitest'
 import type { UIMessage } from '../src/types'
 import { useChat } from '../src/use-chat'
 import {
@@ -15,6 +15,10 @@ import {
 } from './test-utils'
 
 describe('useChat', () => {
+  afterEach(() => {
+    vi.doUnmock('preact/hooks')
+  })
+
   function createDeferred<T>() {
     let resolve!: (value: T) => void
     const promise = new Promise<T>((promiseResolve) => {
diff --git a/packages/ai-react/src/types.ts b/packages/ai-react/src/types.ts
index 87c4076f1..cf38b8a13 100644
--- a/packages/ai-react/src/types.ts
+++ b/packages/ai-react/src/types.ts
@@ -2,13 +2,16 @@ import type {
   AnyClientTool,
   InferSchemaType,
   ModelMessage,
+  RunAgentResumeItem,
   SchemaInput,
 } from '@tanstack/ai/client'
 import type {
   AIDevtoolsDisplayOptions,
   ChatClientOptions,
   ChatClientState,
+  ChatPendingInterrupt,
   ChatRequestBody,
+  ChatResumeState,
   ClientContextOptionFromTools,
   ConnectionStatus,
   DistributedOmit,
@@ -71,6 +74,7 @@ export type UseChatOptions<
   | 'onSubscriptionChange'
   | 'onConnectionStatusChange'
   | 'onSessionGeneratingChange'
+  | 'onResumeStateChange'
   | 'context'
   | 'devtools'
 > & {
@@ -161,6 +165,13 @@ interface BaseUseChatReturn<
     approved: boolean
   }) => Promise<void>
 
+  resumeState: ChatResumeState | null
+  pendingInterrupts: Array<ChatPendingInterrupt>
+  resumeInterrupts: (
+    resume: Array<RunAgentResumeItem>,
+    state?: ChatResumeState,
+  ) => Promise<boolean>
+
   /**
    * Reload the last assistant message
    */
diff --git a/packages/ai-react/src/use-chat.ts b/packages/ai-react/src/use-chat.ts
index 37444b569..b4dda3d3c 100644
--- a/packages/ai-react/src/use-chat.ts
+++ b/packages/ai-react/src/use-chat.ts
@@ -5,11 +5,14 @@ import type {
   AnyClientTool,
   InferSchemaType,
   ModelMessage,
+  RunAgentResumeItem,
   SchemaInput,
   StreamChunk,
 } from '@tanstack/ai/client'
 import type {
   ChatClientState,
+  ChatPendingInterrupt,
+  ChatResumeState,
   ConnectionStatus,
   InferredClientContext,
   StructuredOutputPart,
@@ -43,6 +46,12 @@ export function useChat<
   const [connectionStatus, setConnectionStatus] =
     useState<ConnectionStatus>('disconnected')
   const [sessionGenerating, setSessionGenerating] = useState(false)
+  const [resumeState, setResumeState] = useState<ChatResumeState | null>(
+    options.initialResumeSnapshot?.resumeState ?? null,
+  )
+  const [pendingInterrupts, setPendingInterrupts] = useState<
+    Array<ChatPendingInterrupt>
+  >(options.initialResumeSnapshot?.pendingInterrupts ?? [])
 
   type Partial = DeepPartial<InferSchemaType<NonNullable<TSchema>>>
   type Final = InferSchemaType<NonNullable<TSchema>>
@@ -56,6 +65,10 @@ export function useChat<
   const cleanupInvalidationRef = useRef<ReturnType<typeof setTimeout> | null>(
     null,
   )
+  const cleanupDisposalRef = useRef<{
+    client: ChatClient
+    timeout: ReturnType<typeof setTimeout>
+  } | null>(null)
 
   // Update ref synchronously during render so it's always current when useMemo runs.
   messagesRef.current = messages
@@ -64,6 +77,12 @@ export function useChat<
   const optionsRef = useRef<UseChatOptions<TTools, TSchema, TContext>>(options)
   optionsRef.current = options
 
+  const syncResumeState = useCallback((target: ChatClient | null) => {
+    if (!target) return
+    setResumeState(target.getResumeState())
+    setPendingInterrupts(target.getPendingInterrupts())
+  }, [])
+
   // Create ChatClient instance with callbacks to sync state
   const client = useMemo(() => {
     const messagesToUse = options.initialMessages || []
@@ -93,6 +112,9 @@ export function useChat<
       ...(initialOptions.persistence !== undefined && {
         persistence: initialOptions.persistence,
       }),
+      ...(initialOptions.initialResumeSnapshot !== undefined && {
+        initialResumeSnapshot: initialOptions.initialResumeSnapshot,
+      }),
       ...(initialOptions.context !== undefined && {
         context: initialOptions.context,
       }),
@@ -135,6 +157,7 @@ export function useChat<
       onLoadingChange: (newIsLoading: boolean) => {
         if (activeClientRef.current !== instance) return
         setIsLoading(newIsLoading)
+        syncResumeState(instance)
       },
       onErrorChange: (newError: Error | undefined) => {
         if (activeClientRef.current !== instance) return
@@ -156,10 +179,15 @@ export function useChat<
         if (activeClientRef.current !== instance) return
         setSessionGenerating(isGenerating)
       },
+      onResumeStateChange: (nextResumeState, nextPendingInterrupts) => {
+        if (activeClientRef.current !== instance) return
+        setResumeState(nextResumeState)
+        setPendingInterrupts(nextPendingInterrupts)
+      },
     })
     activeClientRef.current = instance
     return instance
-  }, [clientId])
+  }, [clientId, syncResumeState])
 
   useEffect(() => {
     const clientMessages = client.getMessages()
@@ -201,12 +229,20 @@ export function useChat<
   }, [client, options.live])
 
   useEffect(() => {
+    if (cleanupDisposalRef.current?.client === client) {
+      clearTimeout(cleanupDisposalRef.current.timeout)
+      cleanupDisposalRef.current = null
+    }
     if (cleanupInvalidationRef.current) {
       clearTimeout(cleanupInvalidationRef.current)
       cleanupInvalidationRef.current = null
     }
     activeClientRef.current = client
     client.mountDevtools()
+    // Delivery-durability resume is transparent: the resumable SSE connection
+    // adapter re-attaches via the browser's native Last-Event-ID on reconnect.
+    // We only seed interrupt (state) resume from the client here.
+    syncResumeState(client)
 
     return () => {
       cleanupInvalidationRef.current = setTimeout(() => {
@@ -224,27 +260,48 @@ export function useChat<
       } else {
         client.stop()
       }
-      client.dispose()
+      const disposal = {
+        client,
+        timeout: setTimeout(() => {
+          client.dispose()
+          if (cleanupDisposalRef.current === disposal) {
+            cleanupDisposalRef.current = null
+          }
+        }, 0),
+      }
+      cleanupDisposalRef.current = disposal
     }
-  }, [client])
+  }, [client, syncResumeState])
 
   const sendMessage = useCallback(
     async (content: string | MultimodalContent) => {
-      await client.sendMessage(content)
+      try {
+        await client.sendMessage(content)
+      } finally {
+        syncResumeState(client)
+      }
     },
-    [client],
+    [client, syncResumeState],
   )
 
   const append = useCallback(
     async (message: ModelMessage | UIMessage) => {
-      await client.append(message)
+      try {
+        await client.append(message)
+      } finally {
+        syncResumeState(client)
+      }
     },
-    [client],
+    [client, syncResumeState],
   )
 
   const reload = useCallback(async () => {
-    await client.reload()
-  }, [client])
+    try {
+      await client.reload()
+    } finally {
+      syncResumeState(client)
+    }
+  }, [client, syncResumeState])
 
   const stop = useCallback(() => {
     client.stop()
@@ -252,7 +309,8 @@ export function useChat<
 
   const clear = useCallback(() => {
     client.clear()
-  }, [client])
+    syncResumeState(client)
+  }, [client, syncResumeState])
 
   const setMessagesManually = useCallback(
     (newMessages: Array<UIMessage<TTools>>) => {
@@ -277,8 +335,21 @@ export function useChat<
   const addToolApprovalResponse = useCallback(
     async (response: { id: string; approved: boolean }) => {
       await client.addToolApprovalResponse(response)
+      syncResumeState(client)
     },
-    [client],
+    [client, syncResumeState],
+  )
+
+  const resumeInterrupts = useCallback(
+    async (resumeItems: Array<RunAgentResumeItem>, state?: ChatResumeState) => {
+      const result = await client.resumeInterrupts(
+        resumeItems,
+        state ?? undefined,
+      )
+      syncResumeState(client)
+      return result
+    },
+    [client, syncResumeState],
   )
 
   // The "active" structured-output part is the one on the assistant message
@@ -346,6 +417,9 @@ export function useChat<
     clear,
     addToolResult,
     addToolApprovalResponse,
+    resumeState,
+    pendingInterrupts,
+    resumeInterrupts,
     partial,
     final,
   } as unknown as UseChatReturn<TTools, TSchema>
diff --git a/packages/ai-react/src/use-generate-audio.ts b/packages/ai-react/src/use-generate-audio.ts
index a5f8223c0..402566ef0 100644
--- a/packages/ai-react/src/use-generate-audio.ts
+++ b/packages/ai-react/src/use-generate-audio.ts
@@ -6,8 +6,13 @@ import type {
   ConnectConnectionAdapter,
   GenerationClientState,
   GenerationFetcher,
+  GenerationPendingArtifact,
+  GenerationPersistenceOptions,
+  GenerationResumeSnapshot,
+  GenerationResumeState,
   InferGenerationOutputFromReturn,
 } from '@tanstack/ai-client'
+import type { PersistedArtifactRef } from '@tanstack/ai/client'
 
 /**
  * Options for the useGenerateAudio hook.
@@ -25,6 +30,10 @@ export interface UseGenerateAudioOptions<TOutput = AudioGenerationResult> {
   body?: Record<string, any>
   /** Display options for TanStack AI Devtools. */
   devtools?: AIDevtoolsDisplayOptions
+  /** Server-side lightweight generation state persistence. */
+  persistence?: GenerationPersistenceOptions
+  /** Initial lightweight resume snapshot restored by the app. */
+  initialResumeSnapshot?: GenerationResumeSnapshot
   /**
    * Callback when audio is generated. Can optionally return a transformed value.
    *
@@ -61,6 +70,14 @@ export interface UseGenerateAudioReturn<TOutput = AudioGenerationResult> {
   stop: () => void
   /** Clear result, error, and return to idle */
   reset: () => void
+  /** Lightweight generation resume snapshot, if one is available */
+  resumeSnapshot: GenerationResumeSnapshot | undefined
+  /** Current resumable run/cursor state, if one is available */
+  resumeState: GenerationResumeState | null
+  /** Pending persisted artifact references observed during generation/replay */
+  pendingArtifacts: Array<GenerationPendingArtifact>
+  /** Final persisted artifact references observed from a replayed result */
+  resultArtifacts: Array<PersistedArtifactRef>
 }
 
 /**
@@ -106,19 +123,19 @@ export function useGenerateAudio<TTransformed = void>(
     hookName: 'useGenerateAudio',
     outputKind: 'audio' as const,
   }
-  const { generate, result, isLoading, error, status, stop, reset } =
-    useGeneration<AudioGenerateInput, AudioGenerationResult, TTransformed>({
-      ...options,
-      devtools,
-    })
+  const generation = useGeneration<
+    AudioGenerateInput,
+    AudioGenerationResult,
+    TTransformed
+  >({
+    ...options,
+    devtools,
+  })
 
   return {
-    generate: generate as (input: AudioGenerateInput) => Promise<void>,
-    result,
-    isLoading,
-    error,
-    status,
-    stop,
-    reset,
+    ...generation,
+    generate: generation.generate as (
+      input: AudioGenerateInput,
+    ) => Promise<void>,
   }
 }
diff --git a/packages/ai-react/src/use-generate-image.ts b/packages/ai-react/src/use-generate-image.ts
index 078a792d1..0f6b06c78 100644
--- a/packages/ai-react/src/use-generate-image.ts
+++ b/packages/ai-react/src/use-generate-image.ts
@@ -5,9 +5,14 @@ import type {
   ConnectConnectionAdapter,
   GenerationClientState,
   GenerationFetcher,
+  GenerationPendingArtifact,
+  GenerationPersistenceOptions,
+  GenerationResumeSnapshot,
+  GenerationResumeState,
   ImageGenerateInput,
   InferGenerationOutputFromReturn,
 } from '@tanstack/ai-client'
+import type { PersistedArtifactRef } from '@tanstack/ai/client'
 
 /**
  * Options for the useGenerateImage hook.
@@ -25,6 +30,10 @@ export interface UseGenerateImageOptions<TOutput = ImageGenerationResult> {
   body?: Record<string, any>
   /** Display options for TanStack AI Devtools. */
   devtools?: AIDevtoolsDisplayOptions
+  /** Server-side lightweight generation state persistence. */
+  persistence?: GenerationPersistenceOptions
+  /** Initial lightweight resume snapshot restored by the app. */
+  initialResumeSnapshot?: GenerationResumeSnapshot
   /**
    * Callback when images are generated. Can optionally return a transformed value.
    *
@@ -61,6 +70,14 @@ export interface UseGenerateImageReturn<TOutput = ImageGenerationResult> {
   stop: () => void
   /** Clear result, error, and return to idle */
   reset: () => void
+  /** Lightweight generation resume snapshot, if one is available */
+  resumeSnapshot: GenerationResumeSnapshot | undefined
+  /** Current resumable run/cursor state, if one is available */
+  resumeState: GenerationResumeState | null
+  /** Pending persisted artifact references observed during generation/replay */
+  pendingArtifacts: Array<GenerationPendingArtifact>
+  /** Final persisted artifact references observed from a replayed result */
+  resultArtifacts: Array<PersistedArtifactRef>
 }
 
 /**
@@ -108,19 +125,19 @@ export function useGenerateImage<TTransformed = void>(
     hookName: 'useGenerateImage',
     outputKind: 'image' as const,
   }
-  const { generate, result, isLoading, error, status, stop, reset } =
-    useGeneration<ImageGenerateInput, ImageGenerationResult, TTransformed>({
-      ...options,
-      devtools,
-    })
+  const generation = useGeneration<
+    ImageGenerateInput,
+    ImageGenerationResult,
+    TTransformed
+  >({
+    ...options,
+    devtools,
+  })
 
   return {
-    generate: generate as (input: ImageGenerateInput) => Promise<void>,
-    result,
-    isLoading,
-    error,
-    status,
-    stop,
-    reset,
+    ...generation,
+    generate: generation.generate as (
+      input: ImageGenerateInput,
+    ) => Promise<void>,
   }
 }
diff --git a/packages/ai-react/src/use-generate-speech.ts b/packages/ai-react/src/use-generate-speech.ts
index b22199ff5..65da8e3dc 100644
--- a/packages/ai-react/src/use-generate-speech.ts
+++ b/packages/ai-react/src/use-generate-speech.ts
@@ -5,9 +5,14 @@ import type {
   ConnectConnectionAdapter,
   GenerationClientState,
   GenerationFetcher,
+  GenerationPendingArtifact,
+  GenerationPersistenceOptions,
+  GenerationResumeSnapshot,
+  GenerationResumeState,
   InferGenerationOutputFromReturn,
   SpeechGenerateInput,
 } from '@tanstack/ai-client'
+import type { PersistedArtifactRef } from '@tanstack/ai/client'
 
 /**
  * Options for the useGenerateSpeech hook.
@@ -25,6 +30,10 @@ export interface UseGenerateSpeechOptions<TOutput = TTSResult> {
   body?: Record<string, any>
   /** Display options for TanStack AI Devtools. */
   devtools?: AIDevtoolsDisplayOptions
+  /** Server-side lightweight generation state persistence. */
+  persistence?: GenerationPersistenceOptions
+  /** Initial lightweight resume snapshot restored by the app. */
+  initialResumeSnapshot?: GenerationResumeSnapshot
   /**
    * Callback when speech is generated. Can optionally return a transformed value.
    *
@@ -61,6 +70,14 @@ export interface UseGenerateSpeechReturn<TOutput = TTSResult> {
   stop: () => void
   /** Clear result, error, and return to idle */
   reset: () => void
+  /** Lightweight generation resume snapshot, if one is available */
+  resumeSnapshot: GenerationResumeSnapshot | undefined
+  /** Current resumable run/cursor state, if one is available */
+  resumeState: GenerationResumeState | null
+  /** Pending persisted artifact references observed during generation/replay */
+  pendingArtifacts: Array<GenerationPendingArtifact>
+  /** Final persisted artifact references observed from a replayed result */
+  resultArtifacts: Array<PersistedArtifactRef>
 }
 
 /**
@@ -102,19 +119,19 @@ export function useGenerateSpeech<TTransformed = void>(
     hookName: 'useGenerateSpeech',
     outputKind: 'audio' as const,
   }
-  const { generate, result, isLoading, error, status, stop, reset } =
-    useGeneration<SpeechGenerateInput, TTSResult, TTransformed>({
-      ...options,
-      devtools,
-    })
+  const generation = useGeneration<
+    SpeechGenerateInput,
+    TTSResult,
+    TTransformed
+  >({
+    ...options,
+    devtools,
+  })
 
   return {
-    generate: generate as (input: SpeechGenerateInput) => Promise<void>,
-    result,
-    isLoading,
-    error,
-    status,
-    stop,
-    reset,
+    ...generation,
+    generate: generation.generate as (
+      input: SpeechGenerateInput,
+    ) => Promise<void>,
   }
 }
diff --git a/packages/ai-react/src/use-generate-video.ts b/packages/ai-react/src/use-generate-video.ts
index 3aece73c5..0a2f015cc 100644
--- a/packages/ai-react/src/use-generate-video.ts
+++ b/packages/ai-react/src/use-generate-video.ts
@@ -7,11 +7,16 @@ import type {
   ConnectConnectionAdapter,
   GenerationClientState,
   GenerationFetcher,
+  GenerationPendingArtifact,
+  GenerationPersistenceOptions,
+  GenerationResumeSnapshot,
+  GenerationResumeState,
   InferGenerationOutputFromReturn,
   VideoGenerateInput,
   VideoGenerateResult,
   VideoStatusInfo,
 } from '@tanstack/ai-client'
+import type { PersistedArtifactRef } from '@tanstack/ai/client'
 
 /**
  * Options for the useGenerateVideo hook.
@@ -27,6 +32,10 @@ export interface UseGenerateVideoOptions<TOutput = VideoGenerateResult> {
   body?: Record<string, any>
   /** Display options for TanStack AI Devtools. */
   devtools?: AIDevtoolsDisplayOptions
+  /** Server-side lightweight generation state persistence. */
+  persistence?: GenerationPersistenceOptions
+  /** Initial lightweight resume snapshot restored by the app (read-only state). */
+  initialResumeSnapshot?: GenerationResumeSnapshot
   /**
    * Callback when video generation completes. Can optionally return a transformed value.
    *
@@ -71,6 +80,14 @@ export interface UseGenerateVideoReturn<TOutput = VideoGenerateResult> {
   stop: () => void
   /** Clear all state and return to idle */
   reset: () => void
+  /** Lightweight generation resume snapshot, if one is available */
+  resumeSnapshot: GenerationResumeSnapshot | undefined
+  /** Current resumable run/cursor state, if one is available */
+  resumeState: GenerationResumeState | null
+  /** Pending persisted artifact references observed during generation/replay */
+  pendingArtifacts: Array<GenerationPendingArtifact>
+  /** Final persisted artifact references observed from a replayed result */
+  resultArtifacts: Array<PersistedArtifactRef>
 }
 
 /**
@@ -127,6 +144,9 @@ export function useGenerateVideo<TTransformed = void>(
   const [isLoading, setIsLoading] = useState(false)
   const [error, setError] = useState<Error | undefined>(undefined)
   const [status, setStatus] = useState<GenerationClientState>('idle')
+  const [resumeSnapshot, setResumeSnapshot] = useState<
+    GenerationResumeSnapshot | undefined
+  >(options.initialResumeSnapshot)
 
   const optionsRef = useRef(options)
   optionsRef.current = options
@@ -142,6 +162,10 @@ export function useGenerateVideo<TTransformed = void>(
     const baseOptions = {
       id: clientId,
       body: opts.body,
+      ...(opts.persistence !== undefined && { persistence: opts.persistence }),
+      ...(opts.initialResumeSnapshot !== undefined && {
+        initialResumeSnapshot: opts.initialResumeSnapshot,
+      }),
       devtoolsBridgeFactory: createVideoDevtoolsBridge,
       devtools: {
         ...opts.devtools,
@@ -177,6 +201,7 @@ export function useGenerateVideo<TTransformed = void>(
       onStatusChange: setStatus,
       onJobIdChange: setJobId,
       onVideoStatusChange: setVideoStatus,
+      onResumeSnapshotChange: setResumeSnapshot,
     }
 
     if (opts.connection) {
@@ -206,7 +231,8 @@ export function useGenerateVideo<TTransformed = void>(
     })
   }, [client, options.body])
 
-  // Cleanup on unmount
+  // Mount devtools and clean up on unmount. Generation runs are never
+  // auto-started on mount — persisted state is read-only for display.
   useEffect(() => {
     client.mountDevtools()
 
@@ -240,5 +266,9 @@ export function useGenerateVideo<TTransformed = void>(
     status,
     stop,
     reset,
+    resumeSnapshot,
+    resumeState: resumeSnapshot?.resumeState ?? null,
+    pendingArtifacts: resumeSnapshot?.pendingArtifacts ?? [],
+    resultArtifacts: resumeSnapshot?.result?.artifacts ?? [],
   }
 }
diff --git a/packages/ai-react/src/use-generation.ts b/packages/ai-react/src/use-generation.ts
index 6e5557d9b..55ead65a3 100644
--- a/packages/ai-react/src/use-generation.ts
+++ b/packages/ai-react/src/use-generation.ts
@@ -8,8 +8,13 @@ import type {
   GenerationClientOptions,
   GenerationClientState,
   GenerationFetcher,
+  GenerationPendingArtifact,
+  GenerationPersistenceOptions,
+  GenerationResumeSnapshot,
+  GenerationResumeState,
   InferGenerationOutputFromReturn,
 } from '@tanstack/ai-client'
+import type { PersistedArtifactRef } from '@tanstack/ai/client'
 
 /**
  * Options for the useGeneration hook.
@@ -31,6 +36,10 @@ export interface UseGenerationOptions<TInput, TResult, TOutput = TResult> {
   body?: Record<string, any>
   /** Display options for TanStack AI Devtools. */
   devtools?: AIDevtoolsDisplayOptions
+  /** Server-side lightweight generation state persistence. */
+  persistence?: GenerationPersistenceOptions
+  /** Initial lightweight resume snapshot restored by the app (read-only state). */
+  initialResumeSnapshot?: GenerationResumeSnapshot
   /**
    * Callback when a result is received. Can optionally return a transformed value.
    *
@@ -67,6 +76,14 @@ export interface UseGenerationReturn<TOutput> {
   stop: () => void
   /** Clear result, error, and return to idle */
   reset: () => void
+  /** Lightweight generation state snapshot, if one is available */
+  resumeSnapshot: GenerationResumeSnapshot | undefined
+  /** Observed run/cursor metadata from the snapshot (read-only state) */
+  resumeState: GenerationResumeState | null
+  /** Pending persisted artifact references observed during generation/replay */
+  pendingArtifacts: Array<GenerationPendingArtifact>
+  /** Final persisted artifact references observed from a replayed result */
+  resultArtifacts: Array<PersistedArtifactRef>
 }
 
 /**
@@ -111,6 +128,9 @@ export function useGeneration<
   const [isLoading, setIsLoading] = useState(false)
   const [error, setError] = useState<Error | undefined>(undefined)
   const [status, setStatus] = useState<GenerationClientState>('idle')
+  const [resumeSnapshot, setResumeSnapshot] = useState<
+    GenerationResumeSnapshot | undefined
+  >(options.initialResumeSnapshot)
 
   const optionsRef = useRef(options)
   optionsRef.current = options
@@ -125,6 +145,10 @@ export function useGeneration<
     const clientOptions: GenerationClientOptions<TInput, TResult, TOutput> = {
       id: clientId,
       body: opts.body,
+      ...(opts.persistence !== undefined && { persistence: opts.persistence }),
+      ...(opts.initialResumeSnapshot !== undefined && {
+        initialResumeSnapshot: opts.initialResumeSnapshot,
+      }),
       devtoolsBridgeFactory: createGenerationDevtoolsBridge,
       devtools: {
         hookName: 'useGeneration',
@@ -150,6 +174,7 @@ export function useGeneration<
       onLoadingChange: setIsLoading,
       onErrorChange: setError,
       onStatusChange: setStatus,
+      onResumeSnapshotChange: setResumeSnapshot,
     }
 
     if (opts.connection) {
@@ -179,7 +204,8 @@ export function useGeneration<
     })
   }, [client, options.body])
 
-  // Cleanup on unmount
+  // Mount devtools and clean up on unmount. Generation runs are never
+  // auto-started on mount — persisted state is read-only for display.
   useEffect(() => {
     client.mountDevtools()
 
@@ -211,5 +237,9 @@ export function useGeneration<
     status,
     stop,
     reset,
+    resumeSnapshot,
+    resumeState: resumeSnapshot?.resumeState ?? null,
+    pendingArtifacts: resumeSnapshot?.pendingArtifacts ?? [],
+    resultArtifacts: resumeSnapshot?.result?.artifacts ?? [],
   }
 }
diff --git a/packages/ai-react/src/use-summarize.ts b/packages/ai-react/src/use-summarize.ts
index 9de8eeb71..9e36d0263 100644
--- a/packages/ai-react/src/use-summarize.ts
+++ b/packages/ai-react/src/use-summarize.ts
@@ -5,9 +5,14 @@ import type {
   ConnectConnectionAdapter,
   GenerationClientState,
   GenerationFetcher,
+  GenerationPendingArtifact,
+  GenerationPersistenceOptions,
+  GenerationResumeSnapshot,
+  GenerationResumeState,
   InferGenerationOutputFromReturn,
   SummarizeGenerateInput,
 } from '@tanstack/ai-client'
+import type { PersistedArtifactRef } from '@tanstack/ai/client'
 
 /**
  * Options for the useSummarize hook.
@@ -25,6 +30,10 @@ export interface UseSummarizeOptions<TOutput = SummarizationResult> {
   body?: Record<string, any>
   /** Display options for TanStack AI Devtools. */
   devtools?: AIDevtoolsDisplayOptions
+  /** Server-side lightweight generation state persistence. */
+  persistence?: GenerationPersistenceOptions
+  /** Initial lightweight resume snapshot restored by the app. */
+  initialResumeSnapshot?: GenerationResumeSnapshot
   /**
    * Callback when summarization is complete. Can optionally return a transformed value.
    *
@@ -61,6 +70,14 @@ export interface UseSummarizeReturn<TOutput = SummarizationResult> {
   stop: () => void
   /** Clear result, error, and return to idle */
   reset: () => void
+  /** Lightweight generation resume snapshot, if one is available */
+  resumeSnapshot: GenerationResumeSnapshot | undefined
+  /** Current resumable run/cursor state, if one is available */
+  resumeState: GenerationResumeState | null
+  /** Pending persisted artifact references observed during generation/replay */
+  pendingArtifacts: Array<GenerationPendingArtifact>
+  /** Final persisted artifact references observed from a replayed result */
+  resultArtifacts: Array<PersistedArtifactRef>
 }
 
 /**
@@ -105,19 +122,19 @@ export function useSummarize<TTransformed = void>(
     hookName: 'useSummarize',
     outputKind: 'text' as const,
   }
-  const { generate, result, isLoading, error, status, stop, reset } =
-    useGeneration<SummarizeGenerateInput, SummarizationResult, TTransformed>({
-      ...options,
-      devtools,
-    })
+  const generation = useGeneration<
+    SummarizeGenerateInput,
+    SummarizationResult,
+    TTransformed
+  >({
+    ...options,
+    devtools,
+  })
 
   return {
-    generate: generate as (input: SummarizeGenerateInput) => Promise<void>,
-    result,
-    isLoading,
-    error,
-    status,
-    stop,
-    reset,
+    ...generation,
+    generate: generation.generate as (
+      input: SummarizeGenerateInput,
+    ) => Promise<void>,
   }
 }
diff --git a/packages/ai-react/src/use-transcription.ts b/packages/ai-react/src/use-transcription.ts
index d0e01df8c..b752bce39 100644
--- a/packages/ai-react/src/use-transcription.ts
+++ b/packages/ai-react/src/use-transcription.ts
@@ -5,9 +5,14 @@ import type {
   ConnectConnectionAdapter,
   GenerationClientState,
   GenerationFetcher,
+  GenerationPendingArtifact,
+  GenerationPersistenceOptions,
+  GenerationResumeSnapshot,
+  GenerationResumeState,
   InferGenerationOutputFromReturn,
   TranscriptionGenerateInput,
 } from '@tanstack/ai-client'
+import type { PersistedArtifactRef } from '@tanstack/ai/client'
 
 /**
  * Options for the useTranscription hook.
@@ -25,6 +30,10 @@ export interface UseTranscriptionOptions<TOutput = TranscriptionResult> {
   body?: Record<string, any>
   /** Display options for TanStack AI Devtools. */
   devtools?: AIDevtoolsDisplayOptions
+  /** Server-side lightweight generation state persistence. */
+  persistence?: GenerationPersistenceOptions
+  /** Initial lightweight resume snapshot restored by the app. */
+  initialResumeSnapshot?: GenerationResumeSnapshot
   /**
    * Callback when transcription is complete. Can optionally return a transformed value.
    *
@@ -61,6 +70,14 @@ export interface UseTranscriptionReturn<TOutput = TranscriptionResult> {
   stop: () => void
   /** Clear result, error, and return to idle */
   reset: () => void
+  /** Lightweight generation resume snapshot, if one is available */
+  resumeSnapshot: GenerationResumeSnapshot | undefined
+  /** Current resumable run/cursor state, if one is available */
+  resumeState: GenerationResumeState | null
+  /** Pending persisted artifact references observed during generation/replay */
+  pendingArtifacts: Array<GenerationPendingArtifact>
+  /** Final persisted artifact references observed from a replayed result */
+  resultArtifacts: Array<PersistedArtifactRef>
 }
 
 /**
@@ -110,20 +127,16 @@ export function useTranscription<TTransformed = void>(
     hookName: 'useTranscription',
     outputKind: 'text' as const,
   }
-  const { generate, result, isLoading, error, status, stop, reset } =
-    useGeneration<
-      TranscriptionGenerateInput,
-      TranscriptionResult,
-      TTransformed
-    >({ ...options, devtools })
+  const generation = useGeneration<
+    TranscriptionGenerateInput,
+    TranscriptionResult,
+    TTransformed
+  >({ ...options, devtools })
 
   return {
-    generate: generate as (input: TranscriptionGenerateInput) => Promise<void>,
-    result,
-    isLoading,
-    error,
-    status,
-    stop,
-    reset,
+    ...generation,
+    generate: generation.generate as (
+      input: TranscriptionGenerateInput,
+    ) => Promise<void>,
   }
 }
diff --git a/packages/ai-react/tests/use-chat.test.ts b/packages/ai-react/tests/use-chat.test.ts
index 8e43eedc1..bc1576179 100644
--- a/packages/ai-react/tests/use-chat.test.ts
+++ b/packages/ai-react/tests/use-chat.test.ts
@@ -3,7 +3,7 @@ import { EventType } from '@tanstack/ai'
 import type { SubscribeConnectionAdapter } from '@tanstack/ai-client'
 import { act, renderHook, waitFor } from '@testing-library/react'
 import { StrictMode, useState } from 'react'
-import { describe, expect, it, vi } from 'vitest'
+import { afterEach, describe, expect, it, vi } from 'vitest'
 import type { UIMessage, UseChatOptions } from '../src/types'
 import { useChat } from '../src/use-chat'
 import {
@@ -14,6 +14,10 @@ import {
 } from './test-utils'
 
 describe('useChat', () => {
+  afterEach(() => {
+    vi.doUnmock('react')
+  })
+
   function createDeferred<T>() {
     let resolve!: (value: T) => void
     const promise = new Promise<T>((promiseResolve) => {
@@ -230,6 +234,18 @@ describe('useChat', () => {
       // Client should be the same instance, state should persist
       expect(result.current.messages).toBe(initialMessages)
     })
+
+    it('does not expose delivery-cursor resume/autoResume machinery', () => {
+      // Delivery-durability resume is now transparent (the resumable SSE
+      // connection adapter reattaches via native Last-Event-ID). useChat only
+      // keeps interrupt (state) resume: `resumeInterrupts` + `resumeState`.
+      const adapter = createMockConnectionAdapter()
+      const { result } = renderUseChat({ connection: adapter })
+
+      expect(result.current).not.toHaveProperty('resume')
+      expect(typeof result.current.resumeInterrupts).toBe('function')
+      expect(result.current.resumeState).toBeNull()
+    })
   })
 
   describe('state synchronization', () => {
@@ -1854,6 +1870,56 @@ describe('useChat', () => {
   })
 
   describe('sessionGenerating', () => {
+    it('updates resume state from live interrupt chunks without a wrapper call', async () => {
+      const chunks: Array<StreamChunk> = [
+        {
+          type: EventType.RUN_STARTED,
+          runId: 'run-live-interrupt',
+          threadId: 'thread-live',
+          timestamp: Date.now(),
+        },
+        {
+          type: EventType.TEXT_MESSAGE_CONTENT,
+          messageId: 'msg-live-interrupt',
+          timestamp: Date.now(),
+          delta: 'needs input',
+        },
+        {
+          type: EventType.RUN_FINISHED,
+          runId: 'run-live-interrupt',
+          threadId: 'thread-live',
+          timestamp: Date.now(),
+          outcome: {
+            type: 'interrupt',
+            interrupts: [
+              {
+                id: 'interrupt-live',
+                reason: 'client_tool_input',
+              },
+            ],
+          },
+        },
+      ]
+      const adapter: SubscribeConnectionAdapter = {
+        subscribe: async function* () {
+          for (const chunk of chunks) yield chunk
+        },
+        send: vi.fn(async () => {}),
+      }
+
+      const { result } = renderUseChat({ connection: adapter, live: true })
+
+      await waitFor(() => {
+        expect(result.current.resumeState).toEqual({
+          threadId: 'thread-live',
+          runId: 'run-live-interrupt',
+        })
+        expect(result.current.pendingInterrupts).toEqual([
+          expect.objectContaining({ id: 'interrupt-live' }),
+        ])
+      })
+    })
+
     it('should expose sessionGenerating and update from stream run events', async () => {
       // Build chunks as a typed StreamChunk array so each yielded event is
       // checked against the AGUI discriminated union — no inline `as any`.
diff --git a/packages/ai-react/tests/use-generation.test.ts b/packages/ai-react/tests/use-generation.test.ts
index f3540b520..fa323e69e 100644
--- a/packages/ai-react/tests/use-generation.test.ts
+++ b/packages/ai-react/tests/use-generation.test.ts
@@ -8,8 +8,19 @@ import { useTranscription } from '../src/use-transcription'
 import { useSummarize } from '../src/use-summarize'
 import { useGenerateVideo } from '../src/use-generate-video'
 import { createMockConnectionAdapter } from './test-utils'
-import type { StreamChunk, TTSResult, TranscriptionResult } from '@tanstack/ai'
+import type {
+  PersistedArtifactRef,
+  StreamChunk,
+  TTSResult,
+  TranscriptionResult,
+} from '@tanstack/ai'
 import { EventType } from '@tanstack/ai'
+import type {
+  ConnectConnectionAdapter,
+  GenerationResumeSnapshot,
+  GenerationServerPersistence,
+  RunAgentInputContext,
+} from '@tanstack/ai-client'
 
 // Helper to create generation stream chunks
 function createGenerationChunks(result: unknown): Array<StreamChunk> {
@@ -71,6 +82,87 @@ function createVideoChunks(jobId: string, url: string): Array<StreamChunk> {
   ]
 }
 
+const videoResumeSnapshot: GenerationResumeSnapshot = {
+  resumeState: {
+    threadId: 'thread-resume',
+    runId: 'run-resume',
+  },
+  status: 'running',
+}
+
+const replayedVideoArtifact: PersistedArtifactRef = {
+  role: 'output',
+  artifactId: 'artifact-video-1',
+  threadId: 'thread-resume',
+  runId: 'run-resume',
+  name: 'video.mp4',
+  mimeType: 'video/mp4',
+  size: 1234,
+  createdAt: '2026-07-06T00:00:00.000Z',
+  externalUrl: 'https://example.com/video.mp4',
+  source: {
+    activity: 'video',
+    path: 'runs/run-resume/video.mp4',
+    provider: 'test',
+    model: 'test-video',
+    mediaType: 'video',
+    jobId: 'job-replay',
+    expiresAt: '2026-07-07T00:00:00.000Z',
+  },
+}
+
+function createReplayVideoChunks(): Array<StreamChunk> {
+  return [
+    {
+      type: EventType.RUN_STARTED,
+      runId: 'run-resume',
+      threadId: 'thread-resume',
+      timestamp: Date.now(),
+    },
+    {
+      type: EventType.CUSTOM,
+      name: 'generation:result',
+      value: {
+        jobId: 'job-replay',
+        status: 'completed',
+        url: 'https://example.com/video.mp4',
+        artifacts: [replayedVideoArtifact],
+      },
+      timestamp: Date.now(),
+    },
+    {
+      type: EventType.RUN_FINISHED,
+      runId: 'run-resume',
+      threadId: 'thread-resume',
+      timestamp: Date.now(),
+    },
+  ]
+}
+
+function createRunContextCaptureAdapter(chunks: Array<StreamChunk>): {
+  adapter: ConnectConnectionAdapter
+  connect: ReturnType<typeof vi.fn>
+  runContexts: Array<RunAgentInputContext | undefined>
+} {
+  const runContexts: Array<RunAgentInputContext | undefined> = []
+  const connect = vi.fn()
+  const adapter: ConnectConnectionAdapter = {
+    async *connect(_messages, _data, _signal, runContext) {
+      connect(runContext)
+      runContexts.push(runContext)
+      for (const chunk of chunks) {
+        yield chunk
+      }
+    },
+  }
+  return { adapter, connect, runContexts }
+}
+
+async function flushPromises(): Promise<void> {
+  await Promise.resolve()
+  await new Promise((resolve) => setTimeout(resolve, 0))
+}
+
 // Helper to create error stream chunks.
 // NOTE: The AG-UI spec for RUN_ERROR carries `message` directly on the event
 // (not nested under `error`). We emit BOTH shapes here because GenerationClient
@@ -276,6 +368,52 @@ describe('useGeneration', () => {
       // Resolve the promise after unmount — should not cause errors
       resolvePromise!({ id: '1' })
     })
+
+    it('does not auto-fire a generation on mount from a persisted running snapshot', async () => {
+      // Regression guard for the removed generation resume surface: mounting a
+      // generation hook that has server persistence and a persisted `running`
+      // snapshot must NOT start a fresh empty-prompt generation (previously
+      // `maybeAutoResume()` -> `resume()` -> `generate({})` fired here).
+      const { adapter, connect } = createRunContextCaptureAdapter(
+        createGenerationChunks({ id: '1' }),
+      )
+      const persistence: GenerationServerPersistence = {
+        getItem: vi.fn(() => ({
+          resumeState: { threadId: 'thread-resume', runId: 'run-resume' },
+          status: 'running' as const,
+        })),
+        setItem: vi.fn(),
+        removeItem: vi.fn(),
+      }
+
+      const { result } = renderHook(() =>
+        useGeneration({
+          id: 'no-auto-fire',
+          connection: adapter,
+          persistence: { server: persistence },
+          initialResumeSnapshot: {
+            resumeState: { threadId: 'thread-resume', runId: 'run-resume' },
+            status: 'running',
+          },
+        }),
+      )
+
+      await act(async () => {
+        await flushPromises()
+      })
+
+      expect(connect).not.toHaveBeenCalled()
+      // Persisted state is read-only for display; the client never reads it
+      // back to drive a resume, so getItem is not consulted on mount.
+      expect(persistence.getItem).not.toHaveBeenCalled()
+      expect(result.current.isLoading).toBe(false)
+      expect(result.current.status).toBe('idle')
+      // The persisted snapshot is still exposed as read-only state.
+      expect(result.current.resumeState).toEqual({
+        threadId: 'thread-resume',
+        runId: 'run-resume',
+      })
+    })
   })
 })
 
@@ -535,7 +673,7 @@ describe('useSummarize', () => {
     const mockResult = {
       id: 'sum-1',
       summary: 'A brief summary',
-      model: 'gpt-4',
+      model: 'gpt-5.5',
       usage: { promptTokens: 100, completionTokens: 20, totalTokens: 120 },
     }
 
@@ -554,7 +692,7 @@ describe('useSummarize', () => {
   })
 
   it('should summarize text using connection', async () => {
-    const mockResult = { summary: 'A brief summary', model: 'gpt-4' }
+    const mockResult = { summary: 'A brief summary', model: 'gpt-5.5' }
     const chunks = createGenerationChunks(mockResult)
     const adapter = createMockConnectionAdapter({ chunks })
 
@@ -681,6 +819,39 @@ describe('useGenerateVideo', () => {
     expect(result.current.videoStatus).toBeNull()
     expect(result.current.status).toBe('idle')
   })
+
+  it('does not auto-fire a video generation on mount from a persisted running snapshot', async () => {
+    // Regression guard for the removed generation resume surface (video).
+    const { adapter, connect } = createRunContextCaptureAdapter(
+      createReplayVideoChunks(),
+    )
+    const persistence: GenerationServerPersistence = {
+      getItem: vi.fn(() => videoResumeSnapshot),
+      setItem: vi.fn(),
+      removeItem: vi.fn(),
+    }
+
+    const { result } = renderHook(() =>
+      useGenerateVideo({
+        id: 'video-no-auto-fire',
+        connection: adapter,
+        persistence: { server: persistence },
+        initialResumeSnapshot: videoResumeSnapshot,
+      }),
+    )
+
+    await act(async () => {
+      await flushPromises()
+    })
+
+    expect(connect).not.toHaveBeenCalled()
+    expect(persistence.getItem).not.toHaveBeenCalled()
+    expect(result.current.isLoading).toBe(false)
+    expect(result.current.status).toBe('idle')
+    // The persisted snapshot remains exposed as read-only state.
+    expect(result.current.resumeSnapshot).toEqual(videoResumeSnapshot)
+    expect(result.current.resumeState).toEqual(videoResumeSnapshot.resumeState)
+  })
 })
 
 describe('onResult transform', () => {
diff --git a/packages/ai-sandbox/package.json b/packages/ai-sandbox/package.json
index ad9284c23..5a9ea95d1 100644
--- a/packages/ai-sandbox/package.json
+++ b/packages/ai-sandbox/package.json
@@ -54,16 +54,21 @@
   },
   "peerDependencies": {
     "@ngrok/ngrok": "^1.0.0",
-    "@tanstack/ai": "workspace:^"
+    "@tanstack/ai": "workspace:^",
+    "@tanstack/ai-persistence": "workspace:^"
   },
   "peerDependenciesMeta": {
     "@ngrok/ngrok": {
       "optional": true
+    },
+    "@tanstack/ai-persistence": {
+      "optional": true
     }
   },
   "devDependencies": {
     "@ngrok/ngrok": "^1.7.0",
     "@tanstack/ai": "workspace:*",
+    "@tanstack/ai-persistence": "workspace:*",
     "@vitest/coverage-v8": "4.0.14"
   }
 }
diff --git a/packages/ai-sandbox/src/capabilities.ts b/packages/ai-sandbox/src/capabilities.ts
index 8abd7f95d..a37e28f6d 100644
--- a/packages/ai-sandbox/src/capabilities.ts
+++ b/packages/ai-sandbox/src/capabilities.ts
@@ -5,12 +5,17 @@
  * - `SandboxCapability` is PROVIDED by `withSandbox` and REQUIRED by harness
  *   adapters (`requires: [SandboxCapability]`).
  * - `SandboxStoreCapability` / `LocksCapability` are OPTIONALLY required by
- *   `withSandbox`. v1 falls back to in-memory defaults; the future persistence
- *   package PROVIDES durable implementations.
+ *   `withSandbox`. It falls back to in-memory defaults; `withChatPersistence(...)`
+ *   can provide durable metadata and lock implementations.
  */
-import { createCapability } from '@tanstack/ai'
+import {
+  LocksCapability,
+  createCapability,
+  getLocks,
+  provideLocks,
+} from '@tanstack/ai'
 import type { SandboxHandle } from './contracts'
-import type { LockStore, SandboxStore } from './store'
+import type { SandboxStore } from './store'
 import type { SandboxPolicy } from './policy'
 import type { ToolBridgeProvisioner } from './tool-bridge'
 
@@ -19,8 +24,6 @@ export const SandboxCapability = createCapability<SandboxHandle>()('sandbox')
 export const SandboxStoreCapability =
   createCapability<SandboxStore>()('sandbox-store')
 
-export const LocksCapability = createCapability<LockStore>()('locks')
-
 /**
  * The active sandbox policy, provided by `withSandbox` from the definition.
  * Harness adapters read it to map allow/ask/deny rules onto their native
@@ -41,7 +44,8 @@ export const ToolBridgeProvisionerCapability =
 /** Destructured accessors for adapters: `getSandbox(ctx)` reads the handle. */
 export const [getSandbox, provideSandbox] = SandboxCapability
 export const [getSandboxStore, provideSandboxStore] = SandboxStoreCapability
-export const [getLocks, provideLocks] = LocksCapability
 export const [getSandboxPolicy, provideSandboxPolicy] = SandboxPolicyCapability
 export const [getToolBridgeProvisioner, provideToolBridgeProvisioner] =
   ToolBridgeProvisionerCapability
+
+export { LocksCapability, getLocks, provideLocks }
diff --git a/packages/ai-sandbox/src/index.ts b/packages/ai-sandbox/src/index.ts
index 2c5bf2855..8521e856b 100644
--- a/packages/ai-sandbox/src/index.ts
+++ b/packages/ai-sandbox/src/index.ts
@@ -39,6 +39,15 @@ export type {
   ReuseStrategy,
   SnapshotStrategy,
 } from './sandbox'
+export {
+  WORKSPACE_PERSISTENCE_METADATA_SCOPE,
+  workspacePersistenceArtifactId,
+  workspacePersistenceManifestKey,
+} from './workspace-persistence-types'
+export type {
+  WorkspacePersistenceManifest,
+  WorkspacePersistenceOptions,
+} from './workspace-persistence-types'
 
 // Workspace
 export {
diff --git a/packages/ai-sandbox/src/middleware.ts b/packages/ai-sandbox/src/middleware.ts
index 83dfe7cd4..7dd93b70a 100644
--- a/packages/ai-sandbox/src/middleware.ts
+++ b/packages/ai-sandbox/src/middleware.ts
@@ -29,6 +29,11 @@ import { ProjectionCapability, provideWorkspaceProjection } from './projection'
 import { resolveSecret } from './secrets'
 import { watchWorkspace } from './watch'
 import { DEFAULT_WORKSPACE_ROOT } from './bootstrap'
+import {
+  checkpointWorkspacePersistenceEvent,
+  restoreWorkspacePersistence,
+} from './workspace-persistence'
+import { resolveWorkspacePersistenceOptions } from './workspace-persistence-types'
 import type {
   AbortInfo,
   ChatMiddlewareContext,
@@ -36,26 +41,96 @@ import type {
   SandboxFileEvent,
   SandboxFileHookEvent,
 } from '@tanstack/ai'
+import type { AIPersistence } from '@tanstack/ai-persistence'
 import type { SandboxHandle } from './contracts'
 import type {
   SandboxDefinition,
   SandboxEnsureContext,
   SandboxHooks,
 } from './sandbox'
+import type { SandboxRecord, SandboxStore } from './store'
 import type { SandboxWatchHandle } from './watch'
+import type { ResolvedWorkspacePersistenceOptions } from './workspace-persistence-types'
 
 /** Per-request state we need to carry from `setup` to the terminal hooks. */
 interface SandboxRunState {
   handle: SandboxHandle
   ensureCtx: SandboxEnsureContext
-  watcher?: SandboxWatchHandle
+  watchers: Array<SandboxWatchHandle>
   /** In-flight `enriched.diff()` promises queued by the `fileEvents.diff`
    * watcher callback, awaited before teardown so a pending diff isn't
    * dropped when the run finishes/aborts/errors mid-computation. */
   pendingDiffs: Array<Promise<void>>
+  /** In-flight workspace persistence checkpoints queued by file events. */
+  pendingWorkspacePersistence: Array<Promise<void>>
+  workspacePersistenceErrors: Array<unknown>
+  workspacePersistenceOptions?: ResolvedWorkspacePersistenceOptions
 }
 
 const runState = new WeakMap<object, SandboxRunState>()
+const persistenceStores = new WeakMap<AIPersistence, SandboxStore>()
+const SANDBOX_METADATA_SCOPE = 'tanstack.ai.sandbox'
+
+async function getOptionalPersistence(
+  ctx: ChatMiddlewareContext,
+): Promise<AIPersistence | undefined> {
+  try {
+    const { PersistenceCapability } = await import('@tanstack/ai-persistence')
+    return ctx.getOptional(PersistenceCapability)
+  } catch (error) {
+    if (isMissingOptionalPersistence(error)) return undefined
+    throw error
+  }
+}
+
+function isMissingOptionalPersistence(error: unknown): boolean {
+  return (
+    error instanceof Error &&
+    (error.message.includes('@tanstack/ai-persistence') ||
+      error.message.includes('ERR_MODULE_NOT_FOUND') ||
+      error.message.includes('MODULE_NOT_FOUND'))
+  )
+}
+
+function isSandboxRecord(value: unknown): value is SandboxRecord {
+  if (value === null || typeof value !== 'object') return false
+  const record = value as Record<string, unknown>
+  return (
+    typeof record.key === 'string' &&
+    typeof record.provider === 'string' &&
+    typeof record.providerSandboxId === 'string' &&
+    typeof record.threadId === 'string' &&
+    typeof record.updatedAt === 'number' &&
+    (record.latestSnapshotId === undefined ||
+      typeof record.latestSnapshotId === 'string') &&
+    (record.latestRunId === undefined || typeof record.latestRunId === 'string')
+  )
+}
+
+function sandboxStoreFromPersistence(
+  persistence: AIPersistence | undefined,
+): SandboxStore | undefined {
+  const metadata = persistence?.stores.metadata
+  if (!persistence || !metadata) return undefined
+
+  const existing = persistenceStores.get(persistence)
+  if (existing) return existing
+
+  const store: SandboxStore = {
+    async get(key) {
+      const value = await metadata.get(SANDBOX_METADATA_SCOPE, key)
+      return isSandboxRecord(value) ? value : null
+    },
+    async upsert(record) {
+      await metadata.set(SANDBOX_METADATA_SCOPE, record.key, record)
+    },
+    async delete(key) {
+      await metadata.delete(SANDBOX_METADATA_SCOPE, key)
+    },
+  }
+  persistenceStores.set(persistence, store)
+  return store
+}
 
 /** Defensively pull tenant scoping out of the runtime context, if present. */
 function tenantFrom(
@@ -69,11 +144,16 @@ function tenantFrom(
   return { userId, orgId }
 }
 
-function buildEnsureCtx(ctx: ChatMiddlewareContext): SandboxEnsureContext {
+function buildEnsureCtx(
+  ctx: ChatMiddlewareContext,
+  persistence?: AIPersistence,
+): SandboxEnsureContext {
   return {
     threadId: ctx.threadId,
     runId: ctx.runId,
-    store: ctx.getOptional(SandboxStoreCapability),
+    store:
+      ctx.getOptional(SandboxStoreCapability) ??
+      sandboxStoreFromPersistence(persistence),
     locks: ctx.getOptional(LocksCapability),
     tenant: tenantFrom(ctx.context),
     signal: ctx.signal,
@@ -107,6 +187,19 @@ async function dispatchDefinitionHooks(
   }
 }
 
+async function workspacePersistenceError(
+  state: SandboxRunState,
+): Promise<unknown | undefined> {
+  await Promise.allSettled(state.pendingWorkspacePersistence)
+  if (
+    state.workspacePersistenceOptions?.consistency === 'strict' &&
+    state.workspacePersistenceErrors.length > 0
+  ) {
+    return state.workspacePersistenceErrors[0]
+  }
+  return undefined
+}
+
 export function withSandbox(
   definition: SandboxDefinition,
 ): DefinedChatMiddleware<
@@ -123,16 +216,23 @@ export function withSandbox(
     optionalRequires: [SandboxStoreCapability, LocksCapability],
 
     async setup(ctx) {
-      const ensureCtx = buildEnsureCtx(ctx)
+      const persistence = await getOptionalPersistence(ctx)
+      const ensureCtx = buildEnsureCtx(ctx, persistence)
       const handle = await definition.ensure(ensureCtx)
       provideSandbox(ctx, handle)
       if (definition.policy) provideSandboxPolicy(ctx, definition.policy)
 
-      const watchRoot = definition.workspace?.root ?? DEFAULT_WORKSPACE_ROOT
+      const workspacePersistenceOptions = resolveWorkspacePersistenceOptions({
+        workspacePersistence: definition.persistence?.workspace,
+        workspace: definition.workspace,
+        defaultKey: definition.key(ensureCtx),
+      })
+      const publicWatchRoot =
+        definition.workspace?.root ?? DEFAULT_WORKSPACE_ROOT
       let baseSha = ''
       try {
         const shaRes = await handle.process.exec('git rev-parse HEAD', {
-          cwd: watchRoot,
+          cwd: publicWatchRoot,
         })
         if (shaRes.exitCode === 0) baseSha = shaRes.stdout.trim()
       } catch {
@@ -164,43 +264,94 @@ export function withSandbox(
       }
 
       const hooks = definition.hooks
+      if (workspacePersistenceOptions) {
+        await restoreWorkspacePersistence({
+          handle,
+          persistence,
+          options: workspacePersistenceOptions,
+          runId: ctx.runId,
+          threadId: ctx.threadId,
+        })
+      }
       await hooks?.onReady?.(handle)
 
       const fe = resolveFileEvents(definition.fileEvents)
       const pendingDiffs: Array<Promise<void>> = []
-      let watcher: SandboxWatchHandle | undefined
-      if (fe.enabled) {
-        const runtime = getSandboxRuntime(ctx, { optional: true })
-        watcher = await watchWorkspace(handle, {
-          onEvent: (event: SandboxFileEvent) => {
-            const enriched = buildFileHookEvent(
+      const pendingWorkspacePersistence: Array<Promise<void>> = []
+      const workspacePersistenceErrors: Array<unknown> = []
+      const watchers: Array<SandboxWatchHandle> = []
+      const runtime = getSandboxRuntime(ctx, { optional: true })
+      const enqueueWorkspacePersistence = (event: SandboxFileEvent): void => {
+        if (!workspacePersistenceOptions) return
+        pendingWorkspacePersistence.push(
+          checkpointWorkspacePersistenceEvent(
+            {
               handle,
-              watchRoot,
-              baseSha,
-              event,
-            )
-            void dispatchDefinitionHooks(hooks, enriched)
-            runtime?.emit(enriched)
-            if (fe.diff) {
-              pendingDiffs.push(
-                enriched
-                  .diff()
-                  .then((diff) => {
-                    runtime?.emitFileDiff({ path: event.path, diff })
-                  })
-                  .catch(() => undefined),
+              persistence,
+              options: workspacePersistenceOptions,
+              runId: ctx.runId,
+              threadId: ctx.threadId,
+            },
+            event,
+          ).catch((error) => {
+            workspacePersistenceErrors.push(error)
+          }),
+        )
+      }
+      if (fe.enabled) {
+        const persistenceSharesPublicRoot =
+          workspacePersistenceOptions?.root === publicWatchRoot
+        watchers.push(
+          await watchWorkspace(handle, {
+            root: publicWatchRoot,
+            onEvent: (event: SandboxFileEvent) => {
+              const enriched = buildFileHookEvent(
+                handle,
+                publicWatchRoot,
+                baseSha,
+                event,
               )
-            }
-          },
-          ...(ctx.signal !== undefined ? { signal: ctx.signal } : {}),
-        })
+              void dispatchDefinitionHooks(hooks, enriched)
+              runtime?.emit(enriched)
+              if (persistenceSharesPublicRoot) {
+                enqueueWorkspacePersistence(event)
+              }
+              if (fe.diff) {
+                pendingDiffs.push(
+                  enriched
+                    .diff()
+                    .then((diff) => {
+                      runtime?.emitFileDiff({ path: event.path, diff })
+                    })
+                    .catch(() => undefined),
+                )
+              }
+            },
+            ...(ctx.signal !== undefined ? { signal: ctx.signal } : {}),
+          }),
+        )
+      }
+      if (
+        workspacePersistenceOptions &&
+        (!fe.enabled || workspacePersistenceOptions.root !== publicWatchRoot)
+      ) {
+        watchers.push(
+          await watchWorkspace(handle, {
+            root: workspacePersistenceOptions.root,
+            onEvent: enqueueWorkspacePersistence,
+            ...(ctx.signal !== undefined ? { signal: ctx.signal } : {}),
+          }),
+        )
       }
 
       runState.set(ctx, {
         handle,
         ensureCtx,
         pendingDiffs,
-        ...(watcher ? { watcher } : {}),
+        pendingWorkspacePersistence,
+        workspacePersistenceErrors,
+        watchers,
+        ...(workspacePersistenceOptions ? { workspacePersistenceOptions } : {}),
       })
     },
 
@@ -209,10 +360,18 @@ export function withSandbox(
       if (!state) return
       const { handle, ensureCtx } = state
 
-      await state.watcher?.stop()
+      await Promise.all(state.watchers.map((watcher) => watcher.stop()))
       await Promise.allSettled(state.pendingDiffs)
+      const persistenceError = await workspacePersistenceError(state)
 
       const lifecycle = definition.lifecycle
+      if (persistenceError) {
+        if (lifecycle?.destroyOnComplete) {
+          await definition.destroy(ensureCtx)
+          await definition.hooks?.onDestroy?.()
+        }
+        throw persistenceError
+      }
 
       if (
         lifecycle?.snapshot === 'after-run' &&
@@ -244,8 +403,9 @@ export function withSandbox(
       const state = runState.get(ctx)
       if (!state) return
 
-      await state.watcher?.stop()
+      await Promise.all(state.watchers.map((watcher) => watcher.stop()))
       await Promise.allSettled(state.pendingDiffs)
+      const persistenceError = await workspacePersistenceError(state)
 
       // ALWAYS tear down on an explicit abort, regardless of `destroyOnComplete`.
       // The in-sandbox agent process is not killed by closing its IO stream
@@ -255,14 +415,16 @@ export function withSandbox(
       // `destroyOnComplete:false` governs *successful completion*, never cancel.
       await definition.destroy(state.ensureCtx)
       await definition.hooks?.onDestroy?.()
+      if (persistenceError) throw persistenceError
     },
 
     async onError(ctx, info) {
       const state = runState.get(ctx)
       if (!state) return
 
-      await state.watcher?.stop()
+      await Promise.all(state.watchers.map((watcher) => watcher.stop()))
       await Promise.allSettled(state.pendingDiffs)
+      const persistenceError = await workspacePersistenceError(state)
       await definition.hooks?.onError?.(info.error)
 
       // On failure, only tear down when the lifecycle says so; otherwise leave
@@ -271,6 +433,7 @@ export function withSandbox(
         await definition.destroy(state.ensureCtx)
         await definition.hooks?.onDestroy?.()
       }
+      if (persistenceError) throw persistenceError
     },
   })
 }
diff --git a/packages/ai-sandbox/src/sandbox.ts b/packages/ai-sandbox/src/sandbox.ts
index b1f20859e..8408558e7 100644
--- a/packages/ai-sandbox/src/sandbox.ts
+++ b/packages/ai-sandbox/src/sandbox.ts
@@ -16,6 +16,7 @@ import type { SandboxKeyInput } from './key'
 import type { LockStore, SandboxStore } from './store'
 import type { SandboxPolicy } from './policy'
 import type { WorkspaceDefinition } from './workspace'
+import type { WorkspacePersistenceOptions } from './workspace-persistence-types'
 
 /**
  * Sandbox-scoped hooks declared on `defineSandbox`. File hooks fire for every
@@ -55,6 +56,9 @@ export interface SandboxConfig {
   id: string
   provider: SandboxProvider
   workspace?: WorkspaceDefinition
+  persistence?: {
+    workspace?: boolean | WorkspacePersistenceOptions
+  }
   policy?: SandboxPolicy
   lifecycle?: SandboxLifecycle
   /** Sandbox-scoped file/lifecycle hooks. */
@@ -80,6 +84,9 @@ export interface SandboxDefinition {
   readonly id: string
   readonly provider: SandboxProvider
   readonly workspace?: WorkspaceDefinition
+  readonly persistence?: {
+    workspace?: boolean | WorkspacePersistenceOptions
+  }
   readonly policy?: SandboxPolicy
   readonly lifecycle?: SandboxLifecycle
   /** Sandbox-scoped file/lifecycle hooks. */
@@ -253,6 +260,7 @@ export function defineSandbox(config: SandboxConfig): SandboxDefinition {
     id: config.id,
     provider: config.provider,
     workspace: config.workspace,
+    persistence: config.persistence,
     policy: config.policy,
     lifecycle: config.lifecycle,
     hooks: config.hooks,
diff --git a/packages/ai-sandbox/src/store.ts b/packages/ai-sandbox/src/store.ts
index 7371cfbd6..b1b211f0f 100644
--- a/packages/ai-sandbox/src/store.ts
+++ b/packages/ai-sandbox/src/store.ts
@@ -1,12 +1,14 @@
 /**
  * Persistence seams for the sandbox layer.
  *
- * v1 ships ONLY in-memory implementations (single-process resume). These are
- * deliberately pluggable OPTIONAL capabilities so the future persistence
- * package can `provide` durable implementations (D1/Postgres/Durable Objects)
- * without the sandbox layer changing. Do NOT hardcode storage here.
+ * v1 ships an in-memory sandbox record store for single-process resume.
+ * Durable persistence can be supplied through optional middleware
+ * capabilities.
  */
 
+export type { LockStore } from '@tanstack/ai'
+export { InMemoryLockStore } from '@tanstack/ai'
+
 /** One persisted sandbox instance, keyed by the compound sandbox instance key. */
 export interface SandboxRecord {
   /** Compound key (see computeSandboxKey). */
@@ -30,15 +32,6 @@ export interface SandboxStore {
   delete: (key: string) => Promise<void>
 }
 
-/**
- * Mutual exclusion around sandbox ensure so two concurrent runs for the same
- * thread don't both create a sandbox. The in-memory default is single-process;
- * the persistence layer provides a distributed lock (e.g. a Durable Object).
- */
-export interface LockStore {
-  withLock: <T>(key: string, fn: () => Promise<T>) => Promise<T>
-}
-
 /** In-memory {@link SandboxStore}. Resume works only within one process. */
 export class InMemorySandboxStore implements SandboxStore {
   private readonly map = new Map<string, SandboxRecord>()
@@ -57,27 +50,3 @@ export class InMemorySandboxStore implements SandboxStore {
     return Promise.resolve()
   }
 }
-
-/**
- * In-memory {@link LockStore} — a per-key promise chain. Correct within a
- * single process; multi-instance correctness needs a distributed lock from the
- * persistence layer.
- */
-export class InMemoryLockStore implements LockStore {
-  private readonly chains = new Map<string, Promise<unknown>>()
-
-  withLock<T>(key: string, fn: () => Promise<T>): Promise<T> {
-    const prior = this.chains.get(key) ?? Promise.resolve()
-    // Chain after the prior holder regardless of how it settled.
-    const run = prior.then(fn, fn)
-    // Keep the chain alive but swallow rejections so one failure doesn't poison the lock.
-    this.chains.set(
-      key,
-      run.then(
-        () => undefined,
-        () => undefined,
-      ),
-    )
-    return run
-  }
-}
diff --git a/packages/ai-sandbox/src/workspace-persistence-types.ts b/packages/ai-sandbox/src/workspace-persistence-types.ts
new file mode 100644
index 000000000..92975e9e8
--- /dev/null
+++ b/packages/ai-sandbox/src/workspace-persistence-types.ts
@@ -0,0 +1,82 @@
+import { DEFAULT_WORKSPACE_ROOT } from './bootstrap'
+import type { WorkspaceDefinition } from './workspace'
+
+export const WORKSPACE_PERSISTENCE_METADATA_SCOPE =
+  'tanstack.ai.sandbox.workspace'
+
+export interface WorkspacePersistenceOptions {
+  key?: string
+  root?: string
+  include?: Array<string>
+  exclude?: Array<string>
+  maxFileBytes?: number
+  consistency?: 'strict' | 'best-effort'
+}
+
+export interface WorkspacePersistenceManifest {
+  version: 1
+  files: Record<
+    string,
+    {
+      artifactId: string
+      size: number
+      updatedAt: number
+    }
+  >
+  deleted: Record<string, number>
+}
+
+export interface ResolvedWorkspacePersistenceOptions {
+  key: string
+  root: string
+  include?: Array<string>
+  exclude: Array<string>
+  maxFileBytes: number
+  consistency: 'strict' | 'best-effort'
+}
+
+const DEFAULT_MAX_FILE_BYTES = 10 * 1024 * 1024
+const DEFAULT_EXCLUDE = [
+  'node_modules',
+  '.git',
+  'dist',
+  'build',
+  '.cache',
+  '.env*',
+]
+
+export function workspacePersistenceManifestKey(key: string): string {
+  return `workspace:${key}:manifest`
+}
+
+export function workspacePersistenceArtifactId(
+  key: string,
+  path: string,
+): string {
+  return `workspace:${key}:file:${encodeURIComponent(path)}`
+}
+
+export function resolveWorkspacePersistenceOptions(input: {
+  workspacePersistence: boolean | WorkspacePersistenceOptions | undefined
+  workspace: WorkspaceDefinition | undefined
+  defaultKey: string
+}): ResolvedWorkspacePersistenceOptions | undefined {
+  if (
+    input.workspacePersistence === undefined ||
+    input.workspacePersistence === false
+  ) {
+    return undefined
+  }
+
+  const options =
+    input.workspacePersistence === true ? {} : input.workspacePersistence
+
+  return {
+    key: options.key ?? input.defaultKey,
+    root: options.root ?? input.workspace?.root ?? DEFAULT_WORKSPACE_ROOT,
+    include: options.include,
+    exclude: [...DEFAULT_EXCLUDE, ...(options.exclude ?? [])],
+    maxFileBytes: options.maxFileBytes ?? DEFAULT_MAX_FILE_BYTES,
+    consistency: options.consistency ?? 'strict',
+  }
+}
diff --git a/packages/ai-sandbox/src/workspace-persistence.ts b/packages/ai-sandbox/src/workspace-persistence.ts
new file mode 100644
index 000000000..fc8a1837b
--- /dev/null
+++ b/packages/ai-sandbox/src/workspace-persistence.ts
@@ -0,0 +1,317 @@
+import {
+  WORKSPACE_PERSISTENCE_METADATA_SCOPE,
+  workspacePersistenceArtifactId,
+  workspacePersistenceManifestKey,
+} from './workspace-persistence-types'
+import type { SandboxFileEvent } from '@tanstack/ai'
+import type { AIPersistence } from '@tanstack/ai-persistence'
+import type { SandboxHandle } from './contracts'
+import type {
+  ResolvedWorkspacePersistenceOptions,
+  WorkspacePersistenceManifest,
+} from './workspace-persistence-types'
+
+export {
+  WORKSPACE_PERSISTENCE_METADATA_SCOPE,
+  resolveWorkspacePersistenceOptions,
+  workspacePersistenceArtifactId,
+  workspacePersistenceManifestKey,
+} from './workspace-persistence-types'
+export type {
+  ResolvedWorkspacePersistenceOptions,
+  WorkspacePersistenceManifest,
+  WorkspacePersistenceOptions,
+} from './workspace-persistence-types'
+
+export interface WorkspacePersistenceRunContext {
+  handle: SandboxHandle
+  persistence: AIPersistence | undefined
+  options: ResolvedWorkspacePersistenceOptions
+  runId: string
+  threadId: string
+}
+
+export async function restoreWorkspacePersistence(
+  context: WorkspacePersistenceRunContext,
+): Promise<void> {
+  await runWorkspacePersistence(context.options, async () => {
+    const stores = requiredStores(context)
+    const manifest = await readManifest(stores.metadata, context.options.key)
+    for (const path of Object.keys(manifest.deleted)) {
+      if (!shouldPersistPath(path, context.options)) continue
+      await removeIfPresent(context.handle, path)
+    }
+    for (const [path, file] of Object.entries(manifest.files)) {
+      if (!shouldPersistPath(path, context.options)) continue
+      const artifact = await stores.artifacts.get(file.artifactId)
+      if (!artifact?.bytes) {
+        throw new Error(
+          `Workspace persistence artifact is missing for "${path}"`,
+        )
+      }
+      await mkdirParents(context.handle, path, context.options.root)
+      await context.handle.fs.write(path, artifact.bytes)
+    }
+  })
+}
+
+export function checkpointWorkspacePersistenceEvent(
+  context: WorkspacePersistenceRunContext,
+  event: SandboxFileEvent,
+): Promise<void> {
+  return runWorkspacePersistence(context.options, async () => {
+    const stores = requiredStores(context)
+    if (!shouldPersistPath(event.path, context.options)) return
+
+    await withOptionalLock(
+      stores.locks,
+      `workspace-persistence:${context.options.key}`,
+      async () => {
+        const manifest = await readManifest(
+          stores.metadata,
+          context.options.key,
+        )
+
+        if (event.type === 'delete') {
+          delete manifest.files[event.path]
+          manifest.deleted[event.path] = event.timestamp
+          await writeManifest(stores.metadata, context.options.key, manifest)
+          return
+        }
+
+        let bytes: Uint8Array
+        try {
+          bytes = await context.handle.fs.readBytes(event.path)
+        } catch (error) {
+          if (!isMissingFileError(error)) throw error
+          delete manifest.files[event.path]
+          manifest.deleted[event.path] = event.timestamp
+          await writeManifest(stores.metadata, context.options.key, manifest)
+          return
+        }
+        if (bytes.byteLength > context.options.maxFileBytes) {
+          throw new Error(
+            `Workspace persistence skipped "${event.path}" because it is ${bytes.byteLength} bytes, exceeding maxFileBytes ${context.options.maxFileBytes}`,
+          )
+        }
+
+        const artifactId = workspacePersistenceArtifactId(
+          context.options.key,
+          event.path,
+        )
+        await stores.artifacts.save({
+          artifactId,
+          runId: context.runId,
+          threadId: context.threadId,
+          name: event.path,
+          mimeType: 'application/octet-stream',
+          size: bytes.byteLength,
+          bytes,
+          createdAt: event.timestamp,
+        })
+        manifest.files[event.path] = {
+          artifactId,
+          size: bytes.byteLength,
+          updatedAt: event.timestamp,
+        }
+        delete manifest.deleted[event.path]
+        await writeManifest(stores.metadata, context.options.key, manifest)
+      },
+    )
+  })
+}
+
+function requiredStores(context: WorkspacePersistenceRunContext): {
+  metadata: NonNullable<AIPersistence['stores']['metadata']>
+  artifacts: NonNullable<AIPersistence['stores']['artifacts']>
+  locks: AIPersistence['stores']['locks']
+} {
+  const metadata = context.persistence?.stores.metadata
+  const artifacts = context.persistence?.stores.artifacts
+  if (!metadata || !artifacts) {
+    throw new Error(
+      'Workspace persistence requires AIPersistence stores.metadata and stores.artifacts',
+    )
+  }
+  return { metadata, artifacts, locks: context.persistence?.stores.locks }
+}
+
+async function runWorkspacePersistence(
+  options: ResolvedWorkspacePersistenceOptions,
+  fn: () => Promise<void>,
+): Promise<void> {
+  if (options.consistency === 'strict') {
+    await fn()
+    return
+  }
+  try {
+    await fn()
+  } catch {
+    // best-effort persistence must not fail the sandbox run
+  }
+}
+
+async function withOptionalLock<T>(
+  locks: AIPersistence['stores']['locks'],
+  key: string,
+  fn: () => Promise<T>,
+): Promise<T> {
+  if (!locks) return fn()
+  return locks.withLock(key, fn)
+}
+
+async function readManifest(
+  metadata: NonNullable<AIPersistence['stores']['metadata']>,
+  key: string,
+): Promise<WorkspacePersistenceManifest> {
+  const value = await metadata.get(
+    WORKSPACE_PERSISTENCE_METADATA_SCOPE,
+    workspacePersistenceManifestKey(key),
+  )
+  if (value === null) return emptyManifest()
+  if (isWorkspacePersistenceManifest(value)) return value
+  throw new Error('Workspace persistence manifest is invalid')
+}
+
+async function writeManifest(
+  metadata: NonNullable<AIPersistence['stores']['metadata']>,
+  key: string,
+  manifest: WorkspacePersistenceManifest,
+): Promise<void> {
+  await metadata.set(
+    WORKSPACE_PERSISTENCE_METADATA_SCOPE,
+    workspacePersistenceManifestKey(key),
+    manifest,
+  )
+}
+
+function emptyManifest(): WorkspacePersistenceManifest {
+  return { version: 1, files: {}, deleted: {} }
+}
+
+function isWorkspacePersistenceManifest(
+  value: unknown,
+): value is WorkspacePersistenceManifest {
+  if (value === null || typeof value !== 'object') return false
+  const record = value as Record<string, unknown>
+  return (
+    record.version === 1 &&
+    isRecord(record.files) &&
+    Object.values(record.files).every(isManifestFile) &&
+    isNumberRecord(record.deleted)
+  )
+}
+
+function isManifestFile(value: unknown): boolean {
+  if (value === null || typeof value !== 'object') return false
+  const record = value as Record<string, unknown>
+  return (
+    typeof record.artifactId === 'string' &&
+    typeof record.size === 'number' &&
+    typeof record.updatedAt === 'number'
+  )
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return value !== null && typeof value === 'object' && !Array.isArray(value)
+}
+
+function isNumberRecord(value: unknown): value is Record<string, number> {
+  return (
+    isRecord(value) && Object.values(value).every((v) => typeof v === 'number')
+  )
+}
+
+function shouldPersistPath(
+  path: string,
+  options: ResolvedWorkspacePersistenceOptions,
+): boolean {
+  const root = trimTrailingSlash(options.root)
+  if (hasTraversalSegment(path) || hasTraversalSegment(root)) return false
+  if (path !== root && !path.startsWith(`${root}/`)) return false
+  const relative = path === root ? '' : path.slice(root.length + 1)
+  if (relative === '') return false
+  if (
+    options.include &&
+    !options.include.some((p) => matchesPattern(path, relative, p))
+  ) {
+    return false
+  }
+  return !options.exclude.some((p) => matchesPattern(path, relative, p))
+}
+
+function matchesPattern(
+  path: string,
+  relative: string,
+  pattern: string,
+): boolean {
+  if (pattern === '') return false
+  if (pattern.startsWith('/')) return globToRegExp(pattern).test(path)
+  if (globToRegExp(pattern).test(relative)) return true
+  return relative
+    .split('/')
+    .some((segment) => globToRegExp(pattern).test(segment))
+}
+
+function globToRegExp(pattern: string): RegExp {
+  const escaped = pattern
+    .split('**')
+    .map((part) =>
+      part.replace(/[.+^${}()|[\]\\]/g, '\\$&').replace(/\*/g, '[^/]*'),
+    )
+    .join('.*')
+  return new RegExp(`^${escaped}$`)
+}
+
+async function mkdirParents(
+  handle: SandboxHandle,
+  path: string,
+  root: string,
+): Promise<void> {
+  const parent = path.slice(0, path.lastIndexOf('/'))
+  const normalizedRoot = trimTrailingSlash(root)
+  if (
+    !parent ||
+    parent === normalizedRoot ||
+    !parent.startsWith(`${normalizedRoot}/`)
+  ) {
+    return
+  }
+
+  const parts = parent.slice(normalizedRoot.length + 1).split('/')
+  let current = normalizedRoot
+  for (const part of parts) {
+    current = `${current}/${part}`
+    await handle.fs.mkdir(current)
+  }
+}
+
+async function removeIfPresent(
+  handle: SandboxHandle,
+  path: string,
+): Promise<void> {
+  if (!(await handle.fs.exists(path))) return
+  try {
+    await handle.fs.remove(path)
+  } catch (error) {
+    if (!isMissingFileError(error)) throw error
+  }
+}
+
+function trimTrailingSlash(path: string): string {
+  return path.replace(/\/+$/, '')
+}
+
+function hasTraversalSegment(path: string): boolean {
+  return path.split('/').some((segment) => segment === '..')
+}
+
+function isMissingFileError(error: unknown): boolean {
+  if (!(error instanceof Error)) return false
+  const message = error.message.toLowerCase()
+  return (
+    message.includes('enoent') ||
+    message.includes('no such file') ||
+    message.includes('not found')
+  )
+}
diff --git a/packages/ai-sandbox/tests/harness-cwd.test.ts b/packages/ai-sandbox/tests/harness-cwd.test.ts
index 88d9bd593..e1eafff58 100644
--- a/packages/ai-sandbox/tests/harness-cwd.test.ts
+++ b/packages/ai-sandbox/tests/harness-cwd.test.ts
@@ -3,6 +3,10 @@ import * as path from 'node:path'
 import { resolveHarnessCwd } from '../src/harness-cwd'
 import type { SandboxHandle } from '../src/contracts'
 
+function normalizePathSeparators(value: string): string {
+  return value.replaceAll('\\', '/')
+}
+
 function fakeHandle(
   provider: string,
   id: string,
@@ -23,8 +27,13 @@ describe('resolveHarnessCwd', () => {
   it('maps nested virtual paths under /workspace on local-process', () => {
     const root = '/tmp/tanstack-ai-sandboxes/abc'
     expect(
-      resolveHarnessCwd(fakeHandle('local-process', root), '/workspace/my-app'),
-    ).toBe(path.join(root, 'my-app'))
+      normalizePathSeparators(
+        resolveHarnessCwd(
+          fakeHandle('local-process', root),
+          '/workspace/my-app',
+        ),
+      ),
+    ).toBe(normalizePathSeparators(path.join(root, 'my-app')))
   })
 
   it('passes virtual paths through when workspaceRoot is /workspace', () => {
diff --git a/packages/ai-sandbox/tests/persistence-direct.test.ts b/packages/ai-sandbox/tests/persistence-direct.test.ts
new file mode 100644
index 000000000..e1cf69751
--- /dev/null
+++ b/packages/ai-sandbox/tests/persistence-direct.test.ts
@@ -0,0 +1,189 @@
+import { describe, expect, it } from 'vitest'
+import {
+  EventType,
+  InMemoryLockStore,
+  chat,
+  defineChatMiddleware,
+} from '@tanstack/ai'
+import {
+  memoryPersistence,
+  withChatPersistence,
+} from '@tanstack/ai-persistence'
+import {
+  SandboxStoreCapability,
+  defineSandbox,
+  defineWorkspace,
+  provideSandboxStore,
+  withSandbox,
+} from '../src'
+import { InMemorySandboxStore } from '../src/store'
+import { FULL_CAPS, makeFakeProvider } from './fakes'
+import type {
+  AnyTextAdapter,
+  ChatMiddleware,
+  LockStore,
+  StreamChunk,
+} from '@tanstack/ai'
+import type { SandboxCapabilities } from '../src/contracts'
+import type { SandboxStore } from '../src/store'
+
+function adapter(): AnyTextAdapter {
+  const mock = {
+    kind: 'text',
+    name: 'mock',
+    model: 'test-model',
+    '~types': {},
+    chatStream: () =>
+      (async function* () {
+        yield await Promise.resolve({
+          type: EventType.RUN_FINISHED,
+          runId: 'run',
+          threadId: 'thread',
+          finishReason: 'stop',
+          timestamp: 1,
+        } satisfies StreamChunk)
+      })(),
+    structuredOutput: () => Promise.resolve({ data: {}, rawText: '{}' }),
+  }
+  return mock as unknown as AnyTextAdapter
+}
+
+async function collect(stream: AsyncIterable<StreamChunk>): Promise<void> {
+  for await (const _chunk of stream) {
+    // drain
+  }
+}
+
+function withExplicitSandboxStore(store: SandboxStore): ChatMiddleware {
+  return defineChatMiddleware({
+    name: 'explicit-sandbox-store',
+    provides: [SandboxStoreCapability],
+    setup(ctx) {
+      provideSandboxStore(ctx, store)
+    },
+  })
+}
+
+function countingLockStore(base: LockStore): LockStore & { calls: number } {
+  return {
+    calls: 0,
+    withLock(key, fn) {
+      this.calls += 1
+      return base.withLock(key, fn)
+    },
+  }
+}
+
+const workspace = defineWorkspace({ source: { type: 'none' } })
+
+describe('withSandbox with direct persistence capabilities', () => {
+  it('uses persistence locks and metadata to resume sandbox runs without the bridge', async () => {
+    const persistence = memoryPersistence()
+    const locks = countingLockStore(new InMemoryLockStore())
+    persistence.stores.locks = locks
+    const provider = makeFakeProvider()
+    const sandbox = defineSandbox({
+      id: 'direct-persistence',
+      provider,
+      workspace,
+      fileEvents: false,
+    })
+
+    await collect(
+      chat({
+        adapter: adapter(),
+        threadId: 'thread-1',
+        runId: 'run-1',
+        messages: [{ role: 'user', content: 'first' }],
+        middleware: [withChatPersistence(persistence), withSandbox(sandbox)],
+      }),
+    )
+    await collect(
+      chat({
+        adapter: adapter(),
+        threadId: 'thread-1',
+        runId: 'run-2',
+        messages: [{ role: 'user', content: 'second' }],
+        middleware: [withChatPersistence(persistence), withSandbox(sandbox)],
+      }),
+    )
+
+    expect(locks.calls).toBe(2)
+    expect(provider.calls.create).toBe(1)
+    expect(provider.calls.resume).toBe(1)
+  })
+
+  it('restores sandbox state from persistence metadata when resume falls back to snapshots', async () => {
+    const persistence = memoryPersistence()
+    const ephemeralCaps: SandboxCapabilities = {
+      ...FULL_CAPS,
+      durableFilesystem: false,
+    }
+    const provider = makeFakeProvider({
+      resumeReturnsNull: true,
+      caps: ephemeralCaps,
+    })
+    const sandbox = defineSandbox({
+      id: 'metadata-snapshot',
+      provider,
+      workspace,
+      fileEvents: false,
+      lifecycle: { reuse: 'thread', snapshot: 'after-setup' },
+    })
+
+    await collect(
+      chat({
+        adapter: adapter(),
+        threadId: 'thread-1',
+        runId: 'run-1',
+        messages: [{ role: 'user', content: 'first' }],
+        middleware: [withChatPersistence(persistence), withSandbox(sandbox)],
+      }),
+    )
+    await collect(
+      chat({
+        adapter: adapter(),
+        threadId: 'thread-1',
+        runId: 'run-2',
+        messages: [{ role: 'user', content: 'second' }],
+        middleware: [withChatPersistence(persistence), withSandbox(sandbox)],
+      }),
+    )
+
+    expect(provider.calls.create).toBe(1)
+    expect(provider.calls.resume).toBe(1)
+    expect(provider.calls.restoreSnapshot).toBe(1)
+  })
+
+  it('prefers an explicit sandbox store over the persistence-derived store', async () => {
+    const persistence = memoryPersistence()
+    const explicitStore = new InMemorySandboxStore()
+    const provider = makeFakeProvider()
+    const sandbox = defineSandbox({
+      id: 'explicit-store',
+      provider,
+      workspace,
+      fileEvents: false,
+    })
+
+    await collect(
+      chat({
+        adapter: adapter(),
+        threadId: 'thread-1',
+        runId: 'run-1',
+        messages: [{ role: 'user', content: 'first' }],
+        middleware: [
+          withChatPersistence(persistence),
+          withExplicitSandboxStore(explicitStore),
+          withSandbox(sandbox),
+        ],
+      }),
+    )
+
+    const key = sandbox.key({ threadId: 'thread-1', runId: 'run-1' })
+    expect(await explicitStore.get(key)).not.toBeNull()
+    expect(
+      await persistence.stores.metadata?.get('tanstack.ai.sandbox', key),
+    ).toBeNull()
+  })
+})
diff --git a/packages/ai-sandbox/tests/workspace-persistence.test.ts b/packages/ai-sandbox/tests/workspace-persistence.test.ts
new file mode 100644
index 000000000..7ba98f8ef
--- /dev/null
+++ b/packages/ai-sandbox/tests/workspace-persistence.test.ts
@@ -0,0 +1,645 @@
+import { readFileSync } from 'node:fs'
+import { describe, expect, it } from 'vitest'
+import { EventType, chat } from '@tanstack/ai'
+import {
+  memoryPersistence,
+  withChatPersistence,
+} from '@tanstack/ai-persistence'
+import { defineSandbox, defineWorkspace, withSandbox } from '../src'
+import {
+  WORKSPACE_PERSISTENCE_METADATA_SCOPE,
+  workspacePersistenceArtifactId,
+  workspacePersistenceManifestKey,
+} from '../src/workspace-persistence'
+import type { AnyTextAdapter, StreamChunk } from '@tanstack/ai'
+import type { SandboxHandle, SandboxProvider } from '../src/contracts'
+
+const encoder = new TextEncoder()
+const decoder = new TextDecoder()
+
+function finishChunk(runId: string, threadId: string): StreamChunk {
+  return {
+    type: EventType.RUN_FINISHED,
+    runId,
+    threadId,
+    finishReason: 'stop',
+    timestamp: 1,
+  }
+}
+
+function adapter(
+  run: (input: { runId: string; threadId: string }) => Promise<void> | void,
+): AnyTextAdapter {
+  return {
+    kind: 'text',
+    name: 'mock',
+    model: 'test-model',
+    '~types': {},
+    chatStream: (input: { runId?: string; threadId?: string }) =>
+      (async function* () {
+        const runId = input.runId ?? 'run'
+        const threadId = input.threadId ?? 'thread'
+        await run({ runId, threadId })
+        yield finishChunk(runId, threadId)
+      })(),
+    structuredOutput: () => Promise.resolve({ data: {}, rawText: '{}' }),
+  } as unknown as AnyTextAdapter
+}
+
+async function collect(stream: AsyncIterable<StreamChunk>): Promise<void> {
+  for await (const _chunk of stream) {
+    // drain
+  }
+}
+
+async function collectChunks(
+  stream: AsyncIterable<StreamChunk>,
+): Promise<Array<StreamChunk>> {
+  const chunks: Array<StreamChunk> = []
+  for await (const chunk of stream) chunks.push(chunk)
+  return chunks
+}
+
+function fakeWorkspaceHandle() {
+  const watchers: Array<{
+    root: string
+    cb: (e: { type: string; path: string }) => void
+  }> = []
+  const files = new Map<string, Uint8Array>()
+  const readBytesErrors = new Set<string>()
+  const madeDirs: Array<string> = []
+  const removed: Array<string> = []
+  const watchedPaths: Array<string> = []
+  const handle: SandboxHandle & {
+    files: Map<string, Uint8Array>
+    readBytesErrors: Set<string>
+    madeDirs: Array<string>
+    removed: Array<string>
+    watchedPaths: Array<string>
+    fire: (path: string) => Promise<void>
+  } = {
+    id: 'sandbox-1',
+    provider: 'fake',
+    files,
+    readBytesErrors,
+    madeDirs,
+    removed,
+    watchedPaths,
+    async fire(path) {
+      for (const watcher of watchers) {
+        if (isUnderRoot(path, watcher.root))
+          watcher.cb({ type: 'change', path })
+      }
+      await Promise.resolve()
+    },
+    capabilities: {
+      fs: true,
+      exec: true,
+      env: true,
+      ports: false,
+      backgroundProcesses: false,
+      writableStdin: true,
+      snapshots: false,
+      networkPolicy: false,
+      durableFilesystem: false,
+      fork: false,
+    },
+    fs: {
+      read: (path) =>
+        Promise.resolve(decoder.decode(files.get(path) ?? new Uint8Array())),
+      readBytes: (path) => {
+        if (readBytesErrors.has(path)) {
+          return Promise.reject(new Error(`ENOENT: no such file, open ${path}`))
+        }
+        if (!files.has(path)) {
+          return Promise.reject(new Error(`ENOENT: no such file, open ${path}`))
+        }
+        return Promise.resolve(files.get(path) ?? new Uint8Array())
+      },
+      write: (path, data) => {
+        files.set(
+          path,
+          typeof data === 'string'
+            ? encoder.encode(data)
+            : new Uint8Array(data),
+        )
+        return Promise.resolve()
+      },
+      list: () => Promise.resolve([]),
+      mkdir: (path) => {
+        madeDirs.push(path)
+        return Promise.resolve()
+      },
+      remove: (path) => {
+        removed.push(path)
+        files.delete(path)
+        return Promise.resolve()
+      },
+      rename: () => Promise.resolve(),
+      exists: (path) => Promise.resolve(files.has(path)),
+      watch: (path, cb) => {
+        watchedPaths.push(path)
+        const watcher = { root: path, cb }
+        watchers.push(watcher)
+        return Promise.resolve({
+          stop: () => {
+            const index = watchers.indexOf(watcher)
+            if (index !== -1) watchers.splice(index, 1)
+            return Promise.resolve()
+          },
+        })
+      },
+    },
+    git: {} as SandboxHandle['git'],
+    process: {
+      exec: () => Promise.resolve({ stdout: '', stderr: '', exitCode: 1 }),
+      spawn: () => Promise.reject(new Error('not implemented')),
+    },
+    ports: { connect: () => Promise.reject(new Error('not implemented')) },
+    env: { set: () => Promise.resolve() },
+    destroy: () => Promise.resolve(),
+  }
+  return handle
+}
+
+function isUnderRoot(path: string, root: string): boolean {
+  const normalizedRoot = root.replace(/\/+$/, '')
+  return path === normalizedRoot || path.startsWith(`${normalizedRoot}/`)
+}
+
+function fakeProvider(handle: SandboxHandle): SandboxProvider {
+  return {
+    name: 'fake',
+    capabilities: () => handle.capabilities,
+    create: () => Promise.resolve(handle),
+    resume: () => Promise.resolve(handle),
+    destroy: () => Promise.resolve(),
+  }
+}
+
+function workspaceSandbox(handle: SandboxHandle) {
+  return defineSandbox({
+    id: 'project',
+    provider: fakeProvider(handle),
+    workspace: defineWorkspace({ source: { type: 'none' } }),
+    persistence: {
+      workspace: {
+        key: 'project-123',
+      },
+    },
+  })
+}
+
+describe('managed workspace persistence', () => {
+  it('persists changed workspace files through artifacts and metadata', async () => {
+    const persistence = memoryPersistence()
+    const handle = fakeWorkspaceHandle()
+    const path = '/workspace/src/app.ts'
+    const sandbox = workspaceSandbox(handle)
+
+    await collect(
+      chat({
+        adapter: adapter(() => {
+          handle.files.set(path, encoder.encode('export const app = 1\n'))
+          handle.fire(path)
+        }),
+        threadId: 'thread-1',
+        runId: 'run-1',
+        messages: [{ role: 'user', content: 'build app' }],
+        middleware: [withChatPersistence(persistence), withSandbox(sandbox)],
+      }),
+    )
+
+    const artifact = await persistence.stores.artifacts?.get(
+      workspacePersistenceArtifactId('project-123', path),
+    )
+    const manifest = await persistence.stores.metadata?.get(
+      WORKSPACE_PERSISTENCE_METADATA_SCOPE,
+      workspacePersistenceManifestKey('project-123'),
+    )
+
+    expect(decoder.decode(artifact?.bytes)).toBe('export const app = 1\n')
+    expect(manifest).toMatchObject({
+      version: 1,
+      files: {
+        [path]: {
+          artifactId: workspacePersistenceArtifactId('project-123', path),
+          size: 21,
+        },
+      },
+    })
+  })
+
+  it('restores persisted workspace files before onReady hooks run', async () => {
+    const persistence = memoryPersistence()
+    const handle = fakeWorkspaceHandle()
+    const path = '/workspace/src/app.ts'
+    const artifactId = workspacePersistenceArtifactId('project-123', path)
+    let contentSeenOnReady = ''
+
+    await persistence.stores.artifacts?.save({
+      artifactId,
+      runId: 'seed-run',
+      threadId: 'thread-1',
+      name: path,
+      mimeType: 'application/octet-stream',
+      size: 12,
+      bytes: encoder.encode('restored app'),
+      createdAt: 1,
+    })
+    await persistence.stores.metadata?.set(
+      WORKSPACE_PERSISTENCE_METADATA_SCOPE,
+      workspacePersistenceManifestKey('project-123'),
+      {
+        version: 1,
+        files: {
+          [path]: {
+            artifactId,
+            size: 12,
+            updatedAt: 1,
+          },
+        },
+        deleted: {},
+      },
+    )
+
+    const sandbox = defineSandbox({
+      id: 'project',
+      provider: fakeProvider(handle),
+      workspace: defineWorkspace({ source: { type: 'none' } }),
+      persistence: {
+        workspace: {
+          key: 'project-123',
+        },
+      },
+      hooks: {
+        onReady: async (readyHandle) => {
+          contentSeenOnReady = await readyHandle.fs.read(path)
+        },
+      },
+    })
+
+    await collect(
+      chat({
+        adapter: adapter(() => undefined),
+        threadId: 'thread-1',
+        runId: 'run-1',
+        messages: [{ role: 'user', content: 'resume app' }],
+        middleware: [withChatPersistence(persistence), withSandbox(sandbox)],
+      }),
+    )
+
+    expect(contentSeenOnReady).toBe('restored app')
+    expect(handle.madeDirs).toContain('/workspace/src')
+  })
+
+  it('does not persist default excluded files', async () => {
+    const persistence = memoryPersistence()
+    const handle = fakeWorkspaceHandle()
+    const sandbox = workspaceSandbox(handle)
+    const path = '/workspace/.env.local'
+
+    await collect(
+      chat({
+        adapter: adapter(() => {
+          handle.files.set(path, encoder.encode('SECRET=value\n'))
+          handle.fire(path)
+        }),
+        threadId: 'thread-1',
+        runId: 'run-1',
+        messages: [{ role: 'user', content: 'write env' }],
+        middleware: [withChatPersistence(persistence), withSandbox(sandbox)],
+      }),
+    )
+
+    expect(
+      await persistence.stores.artifacts?.get(
+        workspacePersistenceArtifactId('project-123', path),
+      ),
+    ).toBeNull()
+  })
+
+  it('persists workspace files when public file events are disabled', async () => {
+    const persistence = memoryPersistence()
+    const handle = fakeWorkspaceHandle()
+    const path = '/workspace/src/app.ts'
+    const sandbox = defineSandbox({
+      id: 'project',
+      provider: fakeProvider(handle),
+      workspace: defineWorkspace({ source: { type: 'none' } }),
+      fileEvents: false,
+      persistence: {
+        workspace: {
+          key: 'project-123',
+        },
+      },
+    })
+
+    const chunks = await collectChunks(
+      chat({
+        adapter: adapter(() => {
+          handle.files.set(path, encoder.encode('export const app = 2\n'))
+          handle.fire(path)
+        }),
+        threadId: 'thread-1',
+        runId: 'run-1',
+        messages: [{ role: 'user', content: 'build quiet app' }],
+        middleware: [withChatPersistence(persistence), withSandbox(sandbox)],
+      }),
+    )
+
+    const artifact = await persistence.stores.artifacts?.get(
+      workspacePersistenceArtifactId('project-123', path),
+    )
+
+    expect(decoder.decode(artifact?.bytes)).toBe('export const app = 2\n')
+    expect(
+      chunks.some(
+        (chunk) =>
+          chunk.type === EventType.CUSTOM && chunk.name === 'sandbox.file',
+      ),
+    ).toBe(false)
+  })
+
+  it('watches the configured persistence root', async () => {
+    const persistence = memoryPersistence()
+    const handle = fakeWorkspaceHandle()
+    const path = '/project/src/app.ts'
+    const sandbox = defineSandbox({
+      id: 'project',
+      provider: fakeProvider(handle),
+      workspace: defineWorkspace({
+        source: { type: 'none' },
+        root: '/project',
+      }),
+      persistence: {
+        workspace: {
+          key: 'project-123',
+          root: '/project',
+        },
+      },
+    })
+
+    await collect(
+      chat({
+        adapter: adapter(() => {
+          handle.files.set(path, encoder.encode('export const custom = true\n'))
+          handle.fire(path)
+        }),
+        threadId: 'thread-1',
+        runId: 'run-1',
+        messages: [{ role: 'user', content: 'build custom root app' }],
+        middleware: [withChatPersistence(persistence), withSandbox(sandbox)],
+      }),
+    )
+
+    const artifact = await persistence.stores.artifacts?.get(
+      workspacePersistenceArtifactId('project-123', path),
+    )
+
+    expect(decoder.decode(artifact?.bytes)).toBe('export const custom = true\n')
+    expect(handle.watchedPaths).toEqual(['/project'])
+  })
+
+  it('keeps public file events on the workspace root when persistence uses a narrower root', async () => {
+    const persistence = memoryPersistence()
+    const handle = fakeWorkspaceHandle()
+    const publicPath = '/workspace/src/app.ts'
+    const persistedPath = '/workspace/.persist/state.json'
+    const sandbox = defineSandbox({
+      id: 'project',
+      provider: fakeProvider(handle),
+      workspace: defineWorkspace({ source: { type: 'none' } }),
+      persistence: {
+        workspace: {
+          key: 'project-123',
+          root: '/workspace/.persist',
+        },
+      },
+    })
+
+    const chunks = await collectChunks(
+      chat({
+        adapter: adapter(async () => {
+          handle.files.set(publicPath, encoder.encode('export const app = 3\n'))
+          await handle.fire(publicPath)
+          handle.files.set(persistedPath, encoder.encode('{"ok":true}\n'))
+          await handle.fire(persistedPath)
+        }),
+        threadId: 'thread-1',
+        runId: 'run-1',
+        messages: [{ role: 'user', content: 'build app with state' }],
+        middleware: [withChatPersistence(persistence), withSandbox(sandbox)],
+      }),
+    )
+
+    const publicEvent = chunks.find(
+      (chunk) =>
+        chunk.type === EventType.CUSTOM &&
+        chunk.name === 'sandbox.file' &&
+        chunk.value.path === publicPath,
+    )
+    const artifact = await persistence.stores.artifacts?.get(
+      workspacePersistenceArtifactId('project-123', persistedPath),
+    )
+
+    expect(publicEvent).toBeDefined()
+    expect(decoder.decode(artifact?.bytes)).toBe('{"ok":true}\n')
+    expect(handle.watchedPaths).toEqual(['/workspace', '/workspace/.persist'])
+  })
+
+  it('does not fail strict persistence when a changed file disappears before it can be read', async () => {
+    const persistence = memoryPersistence()
+    const handle = fakeWorkspaceHandle()
+    const path = '/workspace/src/transient.ts'
+    const sandbox = workspaceSandbox(handle)
+
+    await collect(
+      chat({
+        adapter: adapter(async () => {
+          handle.files.set(
+            path,
+            encoder.encode('export const transient = true\n'),
+          )
+          handle.readBytesErrors.add(path)
+          await handle.fire(path)
+          handle.files.delete(path)
+          handle.readBytesErrors.delete(path)
+          await handle.fire(path)
+        }),
+        threadId: 'thread-1',
+        runId: 'run-1',
+        messages: [{ role: 'user', content: 'write transient file' }],
+        middleware: [withChatPersistence(persistence), withSandbox(sandbox)],
+      }),
+    )
+
+    const manifest = await persistence.stores.metadata?.get(
+      WORKSPACE_PERSISTENCE_METADATA_SCOPE,
+      workspacePersistenceManifestKey('project-123'),
+    )
+
+    expect(manifest).toMatchObject({
+      version: 1,
+      files: {},
+      deleted: {
+        [path]: expect.any(Number),
+      },
+    })
+  })
+
+  it('ignores traversal paths from persisted manifests during restore', async () => {
+    const persistence = memoryPersistence()
+    const handle = fakeWorkspaceHandle()
+    const path = '/workspace/../outside.txt'
+    const artifactId = workspacePersistenceArtifactId('project-123', path)
+
+    await persistence.stores.artifacts?.save({
+      artifactId,
+      runId: 'seed-run',
+      threadId: 'thread-1',
+      name: path,
+      mimeType: 'application/octet-stream',
+      size: 7,
+      bytes: encoder.encode('outside'),
+      createdAt: 1,
+    })
+    await persistence.stores.metadata?.set(
+      WORKSPACE_PERSISTENCE_METADATA_SCOPE,
+      workspacePersistenceManifestKey('project-123'),
+      {
+        version: 1,
+        files: {
+          [path]: {
+            artifactId,
+            size: 7,
+            updatedAt: 1,
+          },
+        },
+        deleted: {
+          [path]: 1,
+        },
+      },
+    )
+
+    await collect(
+      chat({
+        adapter: adapter(() => undefined),
+        threadId: 'thread-1',
+        runId: 'run-1',
+        messages: [{ role: 'user', content: 'restore workspace' }],
+        middleware: [
+          withChatPersistence(persistence),
+          withSandbox(workspaceSandbox(handle)),
+        ],
+      }),
+    )
+
+    expect(handle.files.has(path)).toBe(false)
+    expect(handle.removed).not.toContain(path)
+  })
+
+  it('keeps root public workspace persistence declarations independent of the optional persistence peer', () => {
+    const indexSource = readFileSync(
+      new URL('../src/index.ts', import.meta.url),
+      'utf8',
+    )
+    let publicTypeSource = ''
+
+    expect(() => {
+      publicTypeSource = readFileSync(
+        new URL('../src/workspace-persistence-types.ts', import.meta.url),
+        'utf8',
+      )
+    }).not.toThrow()
+    expect(indexSource).toMatch(
+      /export\s+\{[\s\S]*WORKSPACE_PERSISTENCE_METADATA_SCOPE[\s\S]*workspacePersistenceArtifactId[\s\S]*workspacePersistenceManifestKey[\s\S]*\}\s+from '\.\/workspace-persistence-types'/,
+    )
+    expect(indexSource).toMatch(
+      /export type\s+\{[\s\S]*WorkspacePersistenceManifest[\s\S]*WorkspacePersistenceOptions[\s\S]*\}\s+from '\.\/workspace-persistence-types'/,
+    )
+    expect(indexSource).not.toMatch(
+      /export\s+\{[\s\S]*WORKSPACE_PERSISTENCE_METADATA_SCOPE[\s\S]*workspacePersistenceArtifactId[\s\S]*workspacePersistenceManifestKey[\s\S]*\}\s+from '\.\/workspace-persistence'/,
+    )
+    expect(publicTypeSource).not.toContain('@tanstack/ai-persistence')
+  })
+
+  it('replays delete tombstones during restore', async () => {
+    const persistence = memoryPersistence()
+    const handle = fakeWorkspaceHandle()
+    const path = '/workspace/src/removed.ts'
+    handle.files.set(path, encoder.encode('bootstrap file'))
+
+    await persistence.stores.metadata?.set(
+      WORKSPACE_PERSISTENCE_METADATA_SCOPE,
+      workspacePersistenceManifestKey('project-123'),
+      {
+        version: 1,
+        files: {},
+        deleted: {
+          [path]: 1,
+        },
+      },
+    )
+
+    const sandbox = workspaceSandbox(handle)
+
+    await collect(
+      chat({
+        adapter: adapter(() => undefined),
+        threadId: 'thread-1',
+        runId: 'run-1',
+        messages: [{ role: 'user', content: 'restore deleted file' }],
+        middleware: [withChatPersistence(persistence), withSandbox(sandbox)],
+      }),
+    )
+
+    expect(handle.files.has(path)).toBe(false)
+    expect(handle.removed).toContain(path)
+  })
+
+  it('does not fail strict restore when a tombstoned file is already absent', async () => {
+    const persistence = memoryPersistence()
+    const handle = fakeWorkspaceHandle()
+    const path = '/workspace/src/already-removed.ts'
+    handle.fs.remove = (removePath) => {
+      if (!handle.files.has(removePath)) {
+        return Promise.reject(
+          new Error(`ENOENT: no such file or directory, unlink ${removePath}`),
+        )
+      }
+      handle.removed.push(removePath)
+      handle.files.delete(removePath)
+      return Promise.resolve()
+    }
+
+    await persistence.stores.metadata?.set(
+      WORKSPACE_PERSISTENCE_METADATA_SCOPE,
+      workspacePersistenceManifestKey('project-123'),
+      {
+        version: 1,
+        files: {},
+        deleted: {
+          [path]: 1,
+        },
+      },
+    )
+
+    await expect(
+      collect(
+        chat({
+          adapter: adapter(() => undefined),
+          threadId: 'thread-1',
+          runId: 'run-1',
+          messages: [{ role: 'user', content: 'restore deleted file' }],
+          middleware: [
+            withChatPersistence(persistence),
+            withSandbox(workspaceSandbox(handle)),
+          ],
+        }),
+      ),
+    ).resolves.toBeUndefined()
+
+    expect(handle.removed).not.toContain(path)
+  })
+})
diff --git a/packages/ai-solid/src/types.ts b/packages/ai-solid/src/types.ts
index cc7d99a3b..580d0be1c 100644
--- a/packages/ai-solid/src/types.ts
+++ b/packages/ai-solid/src/types.ts
@@ -2,13 +2,16 @@ import type {
   AnyClientTool,
   InferSchemaType,
   ModelMessage,
+  RunAgentResumeItem,
   SchemaInput,
 } from '@tanstack/ai'
 import type {
   AIDevtoolsDisplayOptions,
   ChatClientOptions,
   ChatClientState,
+  ChatPendingInterrupt,
   ChatRequestBody,
+  ChatResumeState,
   ClientContextOptionFromTools,
   ConnectionStatus,
   DistributedOmit,
@@ -67,6 +70,7 @@ export type UseChatOptions<
   | 'onSubscriptionChange'
   | 'onConnectionStatusChange'
   | 'onSessionGeneratingChange'
+  | 'onResumeStateChange'
   | 'context'
   | 'devtools'
 > & {
@@ -147,6 +151,13 @@ interface BaseUseChatReturn<
     approved: boolean
   }) => Promise<void>
 
+  resumeState: Accessor<ChatResumeState | null>
+  pendingInterrupts: Accessor<Array<ChatPendingInterrupt>>
+  resumeInterrupts: (
+    resume: Array<RunAgentResumeItem>,
+    state?: ChatResumeState,
+  ) => Promise<boolean>
+
   /**
    * Reload the last assistant message
    */
diff --git a/packages/ai-solid/src/use-chat.ts b/packages/ai-solid/src/use-chat.ts
index 9a6e404cf..67500602b 100644
--- a/packages/ai-solid/src/use-chat.ts
+++ b/packages/ai-solid/src/use-chat.ts
@@ -11,6 +11,8 @@ import { ChatClient } from '@tanstack/ai-client'
 import { createChatDevtoolsBridge } from '@tanstack/ai-client/devtools'
 import type {
   ChatClientState,
+  ChatPendingInterrupt,
+  ChatResumeState,
   ConnectionStatus,
   InferredClientContext,
   StructuredOutputPart,
@@ -19,6 +21,7 @@ import type {
   AnyClientTool,
   InferSchemaType,
   ModelMessage,
+  RunAgentResumeItem,
   SchemaInput,
   StreamChunk,
 } from '@tanstack/ai'
@@ -54,6 +57,17 @@ export function useChat<
   const [connectionStatus, setConnectionStatus] =
     createSignal<ConnectionStatus>('disconnected')
   const [sessionGenerating, setSessionGenerating] = createSignal(false)
+  const [resumeState, setResumeState] = createSignal<ChatResumeState | null>(
+    options.initialResumeSnapshot?.resumeState ?? null,
+  )
+  const [pendingInterrupts, setPendingInterrupts] = createSignal<
+    Array<ChatPendingInterrupt>
+  >(options.initialResumeSnapshot?.pendingInterrupts ?? [])
+
+  const syncResumeState = () => {
+    setResumeState(client().getResumeState())
+    setPendingInterrupts(client().getPendingInterrupts())
+  }
 
   // Structured-output `partial` / `final` are derived from `messages` —
   // specifically from the structured-output part on the latest assistant
@@ -86,6 +100,9 @@ export function useChat<
       ...(options.persistence !== undefined && {
         persistence: options.persistence,
       }),
+      ...(options.initialResumeSnapshot !== undefined && {
+        initialResumeSnapshot: options.initialResumeSnapshot,
+      }),
       body: options.body,
       ...(options.threadId !== undefined && { threadId: options.threadId }),
       ...(options.forwardedProps !== undefined && {
@@ -119,6 +136,7 @@ export function useChat<
       },
       onLoadingChange: (newIsLoading: boolean) => {
         setIsLoading(newIsLoading)
+        syncResumeState()
       },
       onStatusChange: (newStatus: ChatClientState) => {
         setStatus(newStatus)
@@ -135,6 +153,10 @@ export function useChat<
       onSessionGeneratingChange: (isGenerating: boolean) => {
         setSessionGenerating(isGenerating)
       },
+      onResumeStateChange: (nextResumeState, nextPendingInterrupts) => {
+        setResumeState(nextResumeState)
+        setPendingInterrupts(nextPendingInterrupts)
+      },
     })
     // Only recreate when clientId changes
     // Connection and other options are captured at creation time
@@ -174,6 +196,10 @@ export function useChat<
 
   onMount(() => {
     client().mountDevtools()
+    // Delivery-durability resume is transparent: the resumable SSE connection
+    // adapter reattaches via the browser's native Last-Event-ID on reconnect.
+    // We only seed interrupt (state) resume from the client here.
+    syncResumeState()
   })
 
   // Cleanup on unmount: stop any in-flight requests.
@@ -190,15 +216,27 @@ export function useChat<
   // or mutated options propagate without recreating the client.
 
   const sendMessage = async (content: string | MultimodalContent) => {
-    await client().sendMessage(content)
+    try {
+      await client().sendMessage(content)
+    } finally {
+      syncResumeState()
+    }
   }
 
   const append = async (message: ModelMessage | UIMessage<TTools>) => {
-    await client().append(message)
+    try {
+      await client().append(message)
+    } finally {
+      syncResumeState()
+    }
   }
 
   const reload = async () => {
-    await client().reload()
+    try {
+      await client().reload()
+    } finally {
+      syncResumeState()
+    }
   }
 
   const stop = () => {
@@ -207,6 +245,7 @@ export function useChat<
 
   const clear = () => {
     client().clear()
+    syncResumeState()
   }
 
   const setMessagesManually = (newMessages: Array<UIMessage<TTools>>) => {
@@ -228,6 +267,16 @@ export function useChat<
     approved: boolean
   }) => {
     await client().addToolApprovalResponse(response)
+    syncResumeState()
+  }
+
+  const resumeInterrupts = async (
+    resumeItems: Array<RunAgentResumeItem>,
+    state?: ChatResumeState,
+  ) => {
+    const result = await client().resumeInterrupts(resumeItems, state)
+    syncResumeState()
+    return result
   }
 
   // The "active" structured-output part is on the assistant message after
@@ -287,6 +336,9 @@ export function useChat<
     clear,
     addToolResult,
     addToolApprovalResponse,
+    resumeState,
+    pendingInterrupts,
+    resumeInterrupts,
     partial,
     final,
   } as unknown as UseChatReturn<TTools, TSchema>
diff --git a/packages/ai-solid/src/use-generate-audio.ts b/packages/ai-solid/src/use-generate-audio.ts
index 94bfac297..fdca21fac 100644
--- a/packages/ai-solid/src/use-generate-audio.ts
+++ b/packages/ai-solid/src/use-generate-audio.ts
@@ -1,4 +1,8 @@
 import { useGeneration } from './use-generation'
+import type {
+  UseGenerationOptions,
+  UseGenerationReturn,
+} from './use-generation'
 import type { AudioGenerationResult, StreamChunk } from '@tanstack/ai'
 import type {
   AIDevtoolsDisplayOptions,
@@ -15,7 +19,12 @@ import type { Accessor } from 'solid-js'
  *
  * @template TOutput - The transformed output type (defaults to AudioGenerationResult)
  */
-export interface UseGenerateAudioOptions<TOutput = AudioGenerationResult> {
+export interface UseGenerateAudioOptions<
+  TOutput = AudioGenerationResult,
+> extends Pick<
+  UseGenerationOptions<AudioGenerateInput, AudioGenerationResult, TOutput>,
+  'persistence' | 'initialResumeSnapshot'
+> {
   /** Connect-based adapter for streaming transport (SSE, HTTP stream, custom) */
   connection?: ConnectConnectionAdapter
   /** Direct async function for audio generation */
@@ -47,7 +56,9 @@ export interface UseGenerateAudioOptions<TOutput = AudioGenerationResult> {
  *
  * @template TOutput - The transformed output type (defaults to AudioGenerationResult)
  */
-export interface UseGenerateAudioReturn<TOutput = AudioGenerationResult> {
+export interface UseGenerateAudioReturn<
+  TOutput = AudioGenerationResult,
+> extends Omit<UseGenerationReturn<TOutput>, 'generate'> {
   /** Trigger audio generation */
   generate: (input: AudioGenerateInput) => Promise<void>
   /** The generation result containing audio, or null */
@@ -58,10 +69,6 @@ export interface UseGenerateAudioReturn<TOutput = AudioGenerationResult> {
   error: Accessor<Error | undefined>
   /** Current state of the generation */
   status: Accessor<GenerationClientState>
-  /** Abort the current generation */
-  stop: () => void
-  /** Clear result, error, and return to idle */
-  reset: () => void
 }
 
 /**
@@ -101,19 +108,19 @@ export function useGenerateAudio<TTransformed = void>(
     hookName: 'useGenerateAudio',
     outputKind: 'audio' as const,
   }
-  const { generate, result, isLoading, error, status, stop, reset } =
-    useGeneration<AudioGenerateInput, AudioGenerationResult, TTransformed>({
-      ...options,
-      devtools,
-    })
+  const generation = useGeneration<
+    AudioGenerateInput,
+    AudioGenerationResult,
+    TTransformed
+  >({
+    ...options,
+    devtools,
+  })
 
   return {
-    generate: generate as (input: AudioGenerateInput) => Promise<void>,
-    result,
-    isLoading,
-    error,
-    status,
-    stop,
-    reset,
+    ...generation,
+    generate: generation.generate as (
+      input: AudioGenerateInput,
+    ) => Promise<void>,
   }
 }
diff --git a/packages/ai-solid/src/use-generate-image.ts b/packages/ai-solid/src/use-generate-image.ts
index b88902163..5a85ba6f3 100644
--- a/packages/ai-solid/src/use-generate-image.ts
+++ b/packages/ai-solid/src/use-generate-image.ts
@@ -1,4 +1,8 @@
 import { useGeneration } from './use-generation'
+import type {
+  UseGenerationOptions,
+  UseGenerationReturn,
+} from './use-generation'
 import type { ImageGenerationResult, StreamChunk } from '@tanstack/ai'
 import type {
   AIDevtoolsDisplayOptions,
@@ -15,7 +19,12 @@ import type { Accessor } from 'solid-js'
  *
  * @template TOutput - The transformed output type (defaults to ImageGenerationResult)
  */
-export interface UseGenerateImageOptions<TOutput = ImageGenerationResult> {
+export interface UseGenerateImageOptions<
+  TOutput = ImageGenerationResult,
+> extends Pick<
+  UseGenerationOptions<ImageGenerateInput, ImageGenerationResult, TOutput>,
+  'persistence' | 'initialResumeSnapshot'
+> {
   /** Connect-based adapter for streaming transport (SSE, HTTP stream, custom) */
   connection?: ConnectConnectionAdapter
   /** Direct async function for image generation */
@@ -47,7 +56,9 @@ export interface UseGenerateImageOptions<TOutput = ImageGenerationResult> {
  *
  * @template TOutput - The transformed output type (defaults to ImageGenerationResult)
  */
-export interface UseGenerateImageReturn<TOutput = ImageGenerationResult> {
+export interface UseGenerateImageReturn<
+  TOutput = ImageGenerationResult,
+> extends Omit<UseGenerationReturn<TOutput>, 'generate'> {
   /** Trigger image generation */
   generate: (input: ImageGenerateInput) => Promise<void>
   /** The generation result containing images, or null */
@@ -58,10 +69,6 @@ export interface UseGenerateImageReturn<TOutput = ImageGenerationResult> {
   error: Accessor<Error | undefined>
   /** Current state of the generation */
   status: Accessor<GenerationClientState>
-  /** Abort the current generation */
-  stop: () => void
-  /** Clear result, error, and return to idle */
-  reset: () => void
 }
 
 /**
@@ -109,19 +116,19 @@ export function useGenerateImage<TTransformed = void>(
     hookName: 'useGenerateImage',
     outputKind: 'image' as const,
   }
-  const { generate, result, isLoading, error, status, stop, reset } =
-    useGeneration<ImageGenerateInput, ImageGenerationResult, TTransformed>({
-      ...options,
-      devtools,
-    })
+  const generation = useGeneration<
+    ImageGenerateInput,
+    ImageGenerationResult,
+    TTransformed
+  >({
+    ...options,
+    devtools,
+  })
 
   return {
-    generate: generate as (input: ImageGenerateInput) => Promise<void>,
-    result,
-    isLoading,
-    error,
-    status,
-    stop,
-    reset,
+    ...generation,
+    generate: generation.generate as (
+      input: ImageGenerateInput,
+    ) => Promise<void>,
   }
 }
diff --git a/packages/ai-solid/src/use-generate-speech.ts b/packages/ai-solid/src/use-generate-speech.ts
index b682e71a4..96fd5a5cc 100644
--- a/packages/ai-solid/src/use-generate-speech.ts
+++ b/packages/ai-solid/src/use-generate-speech.ts
@@ -1,4 +1,8 @@
 import { useGeneration } from './use-generation'
+import type {
+  UseGenerationOptions,
+  UseGenerationReturn,
+} from './use-generation'
 import type { StreamChunk, TTSResult } from '@tanstack/ai'
 import type {
   AIDevtoolsDisplayOptions,
@@ -15,7 +19,10 @@ import type { Accessor } from 'solid-js'
  *
  * @template TOutput - The transformed output type (defaults to TTSResult)
  */
-export interface UseGenerateSpeechOptions<TOutput = TTSResult> {
+export interface UseGenerateSpeechOptions<TOutput = TTSResult> extends Pick<
+  UseGenerationOptions<SpeechGenerateInput, TTSResult, TOutput>,
+  'persistence' | 'initialResumeSnapshot'
+> {
   /** Connect-based adapter for streaming transport (SSE, HTTP stream, custom) */
   connection?: ConnectConnectionAdapter
   /** Direct async function for speech generation */
@@ -47,7 +54,10 @@ export interface UseGenerateSpeechOptions<TOutput = TTSResult> {
  *
  * @template TOutput - The transformed output type (defaults to TTSResult)
  */
-export interface UseGenerateSpeechReturn<TOutput = TTSResult> {
+export interface UseGenerateSpeechReturn<TOutput = TTSResult> extends Omit<
+  UseGenerationReturn<TOutput>,
+  'generate'
+> {
   /** Trigger speech generation */
   generate: (input: SpeechGenerateInput) => Promise<void>
   /** The TTS result containing audio data, or null */
@@ -58,10 +68,6 @@ export interface UseGenerateSpeechReturn<TOutput = TTSResult> {
   error: Accessor<Error | undefined>
   /** Current state of the generation */
   status: Accessor<GenerationClientState>
-  /** Abort the current generation */
-  stop: () => void
-  /** Clear result, error, and return to idle */
-  reset: () => void
 }
 
 /**
@@ -103,19 +109,19 @@ export function useGenerateSpeech<TTransformed = void>(
     hookName: 'useGenerateSpeech',
     outputKind: 'audio' as const,
   }
-  const { generate, result, isLoading, error, status, stop, reset } =
-    useGeneration<SpeechGenerateInput, TTSResult, TTransformed>({
-      ...options,
-      devtools,
-    })
+  const generation = useGeneration<
+    SpeechGenerateInput,
+    TTSResult,
+    TTransformed
+  >({
+    ...options,
+    devtools,
+  })
 
   return {
-    generate: generate as (input: SpeechGenerateInput) => Promise<void>,
-    result,
-    isLoading,
-    error,
-    status,
-    stop,
-    reset,
+    ...generation,
+    generate: generation.generate as (
+      input: SpeechGenerateInput,
+    ) => Promise<void>,
   }
 }
diff --git a/packages/ai-solid/src/use-generate-video.ts b/packages/ai-solid/src/use-generate-video.ts
index 4fd68b5de..0b8af0fd6 100644
--- a/packages/ai-solid/src/use-generate-video.ts
+++ b/packages/ai-solid/src/use-generate-video.ts
@@ -14,11 +14,16 @@ import type {
   ConnectConnectionAdapter,
   GenerationClientState,
   GenerationFetcher,
+  GenerationPendingArtifact,
+  GenerationPersistenceOptions,
+  GenerationResumeSnapshot,
+  GenerationResumeState,
   InferGenerationOutputFromReturn,
   VideoGenerateInput,
   VideoGenerateResult,
   VideoStatusInfo,
 } from '@tanstack/ai-client'
+import type { PersistedArtifactRef } from '@tanstack/ai/client'
 import type { Accessor } from 'solid-js'
 
 /**
@@ -37,6 +42,10 @@ export interface UseGenerateVideoOptions<TOutput = VideoGenerateResult> {
   body?: Record<string, any>
   /** Display options for TanStack AI Devtools. */
   devtools?: AIDevtoolsDisplayOptions
+  /** Server-side lightweight generation state persistence. */
+  persistence?: GenerationPersistenceOptions
+  /** Initial lightweight resume snapshot restored by the app (read-only state). */
+  initialResumeSnapshot?: GenerationResumeSnapshot
   /**
    * Callback when video generation completes. Can optionally return a transformed value.
    *
@@ -81,6 +90,14 @@ export interface UseGenerateVideoReturn<TOutput = VideoGenerateResult> {
   stop: () => void
   /** Clear all state and return to idle */
   reset: () => void
+  /** Lightweight generation resume snapshot, if one is available */
+  resumeSnapshot: Accessor<GenerationResumeSnapshot | undefined>
+  /** Observed run/cursor metadata from the snapshot (read-only state) */
+  resumeState: Accessor<GenerationResumeState | null>
+  /** Pending persisted artifact references observed during generation/replay */
+  pendingArtifacts: Accessor<Array<GenerationPendingArtifact>>
+  /** Final persisted artifact references observed from a replayed result */
+  resultArtifacts: Accessor<Array<PersistedArtifactRef>>
 }
 
 /**
@@ -139,6 +156,10 @@ export function useGenerateVideo<TTransformed = void>(
   const [isLoading, setIsLoading] = createSignal(false)
   const [error, setError] = createSignal<Error | undefined>(undefined)
   const [status, setStatus] = createSignal<GenerationClientState>('idle')
+  const [resumeSnapshot, setResumeSnapshot] = createSignal<
+    GenerationResumeSnapshot | undefined
+  >(options.initialResumeSnapshot)
+  let disposed = false
 
   const client = createMemo(() => {
     // Conditional spread on `body`: VideoGenerationClientOptions.body
@@ -146,6 +167,12 @@ export function useGenerateVideo<TTransformed = void>(
     const baseOptions = {
       id: clientId,
       body: options.body,
+      ...(options.persistence !== undefined && {
+        persistence: options.persistence,
+      }),
+      ...(options.initialResumeSnapshot !== undefined && {
+        initialResumeSnapshot: options.initialResumeSnapshot,
+      }),
       devtoolsBridgeFactory: createVideoDevtoolsBridge,
       devtools: {
         ...options.devtools,
@@ -159,17 +186,44 @@ export function useGenerateVideo<TTransformed = void>(
       onResult: ((r: VideoGenerateResult) => options.onResult?.(r)) as (
         result: VideoGenerateResult,
       ) => TOutput | null | void,
-      onError: (e: Error) => options.onError?.(e),
-      onProgress: (p: number, m?: string) => options.onProgress?.(p, m),
-      onChunk: (c: StreamChunk) => options.onChunk?.(c),
-      onJobCreated: (id: string) => options.onJobCreated?.(id),
-      onStatusUpdate: (s: VideoStatusInfo) => options.onStatusUpdate?.(s),
-      onResultChange: setResult,
-      onLoadingChange: setIsLoading,
-      onErrorChange: setError,
-      onStatusChange: setStatus,
-      onJobIdChange: setJobId,
-      onVideoStatusChange: setVideoStatus,
+      onError: (e: Error) => {
+        if (!disposed) options.onError?.(e)
+      },
+      onProgress: (p: number, m?: string) => {
+        if (!disposed) options.onProgress?.(p, m)
+      },
+      onChunk: (c: StreamChunk) => {
+        if (!disposed) options.onChunk?.(c)
+      },
+      onJobCreated: (id: string) => {
+        if (!disposed) options.onJobCreated?.(id)
+      },
+      onStatusUpdate: (s: VideoStatusInfo) => {
+        if (!disposed) options.onStatusUpdate?.(s)
+      },
+      onResultChange: (r: TOutput | null) => {
+        if (!disposed) setResult(() => r)
+      },
+      onLoadingChange: (l: boolean) => {
+        if (!disposed) setIsLoading(l)
+      },
+      onErrorChange: (e: Error | undefined) => {
+        if (!disposed) setError(e)
+      },
+      onStatusChange: (s: GenerationClientState) => {
+        if (!disposed) setStatus(s)
+      },
+      onJobIdChange: (id: string | null) => {
+        if (!disposed) setJobId(id)
+      },
+      onVideoStatusChange: (s: VideoStatusInfo | null) => {
+        if (!disposed) setVideoStatus(s)
+      },
+      onResumeSnapshotChange: (
+        snapshot: GenerationResumeSnapshot | undefined,
+      ) => {
+        if (!disposed) setResumeSnapshot(snapshot)
+      },
     }
 
     if (options.connection) {
@@ -199,12 +253,15 @@ export function useGenerateVideo<TTransformed = void>(
     })
   })
 
+  // Mount devtools only. Generation runs are never auto-started on mount —
+  // persisted state is read-only for display.
   onMount(() => {
     client().mountDevtools()
   })
 
   // Cleanup on unmount: stop any in-flight requests and unregister devtools
   onCleanup(() => {
+    disposed = true
     client().dispose()
   })
 
@@ -230,5 +287,9 @@ export function useGenerateVideo<TTransformed = void>(
     status,
     stop,
     reset,
+    resumeSnapshot,
+    resumeState: () => resumeSnapshot()?.resumeState ?? null,
+    pendingArtifacts: () => resumeSnapshot()?.pendingArtifacts ?? [],
+    resultArtifacts: () => resumeSnapshot()?.result?.artifacts ?? [],
   }
 }
diff --git a/packages/ai-solid/src/use-generation.ts b/packages/ai-solid/src/use-generation.ts
index 2db94a579..bd78244fb 100644
--- a/packages/ai-solid/src/use-generation.ts
+++ b/packages/ai-solid/src/use-generation.ts
@@ -15,8 +15,13 @@ import type {
   GenerationClientOptions,
   GenerationClientState,
   GenerationFetcher,
+  GenerationPendingArtifact,
+  GenerationPersistenceOptions,
+  GenerationResumeSnapshot,
+  GenerationResumeState,
   InferGenerationOutputFromReturn,
 } from '@tanstack/ai-client'
+import type { PersistedArtifactRef } from '@tanstack/ai/client'
 import type { Accessor } from 'solid-js'
 
 /**
@@ -39,6 +44,10 @@ export interface UseGenerationOptions<TInput, TResult, TOutput = TResult> {
   body?: Record<string, any>
   /** Display options for TanStack AI Devtools. */
   devtools?: AIDevtoolsDisplayOptions
+  /** Server-side lightweight generation state persistence. */
+  persistence?: GenerationPersistenceOptions
+  /** Initial lightweight resume snapshot restored by the app (read-only state). */
+  initialResumeSnapshot?: GenerationResumeSnapshot
   /**
    * Callback when a result is received. Can optionally return a transformed value.
    *
@@ -75,6 +84,14 @@ export interface UseGenerationReturn<TOutput> {
   stop: () => void
   /** Clear result, error, and return to idle */
   reset: () => void
+  /** Lightweight generation resume snapshot, if one is available */
+  resumeSnapshot: Accessor<GenerationResumeSnapshot | undefined>
+  /** Observed run/cursor metadata from the snapshot (read-only state) */
+  resumeState: Accessor<GenerationResumeState | null>
+  /** Pending persisted artifact references observed during generation/replay */
+  pendingArtifacts: Accessor<Array<GenerationPendingArtifact>>
+  /** Final persisted artifact references observed from a replayed result */
+  resultArtifacts: Accessor<Array<PersistedArtifactRef>>
 }
 
 /**
@@ -120,6 +137,10 @@ export function useGeneration<
   const [isLoading, setIsLoading] = createSignal(false)
   const [error, setError] = createSignal<Error | undefined>(undefined)
   const [status, setStatus] = createSignal<GenerationClientState>('idle')
+  const [resumeSnapshot, setResumeSnapshot] = createSignal<
+    GenerationResumeSnapshot | undefined
+  >(options.initialResumeSnapshot)
+  let disposed = false
 
   const client = createMemo(() => {
     // Conditional spread on `body`: `GenerationClientOptions.body` is a
@@ -128,6 +149,12 @@ export function useGeneration<
     const clientOptions: GenerationClientOptions<TInput, TResult, TOutput> = {
       id: clientId,
       body: options.body,
+      ...(options.persistence !== undefined && {
+        persistence: options.persistence,
+      }),
+      ...(options.initialResumeSnapshot !== undefined && {
+        initialResumeSnapshot: options.initialResumeSnapshot,
+      }),
       devtoolsBridgeFactory: createGenerationDevtoolsBridge,
       devtools: {
         ...options.devtools,
@@ -140,13 +167,30 @@ export function useGeneration<
       onResult: ((r: TResult) => options.onResult?.(r)) as (
         result: TResult,
       ) => TOutput | null | void,
-      onError: (e: Error) => options.onError?.(e),
-      onProgress: (p: number, m?: string) => options.onProgress?.(p, m),
-      onChunk: (c: StreamChunk) => options.onChunk?.(c),
-      onResultChange: setResult,
-      onLoadingChange: setIsLoading,
-      onErrorChange: setError,
-      onStatusChange: setStatus,
+      onError: (e: Error) => {
+        if (!disposed) options.onError?.(e)
+      },
+      onProgress: (p: number, m?: string) => {
+        if (!disposed) options.onProgress?.(p, m)
+      },
+      onChunk: (c: StreamChunk) => {
+        if (!disposed) options.onChunk?.(c)
+      },
+      onResultChange: (r) => {
+        if (!disposed) setResult(() => r)
+      },
+      onLoadingChange: (l) => {
+        if (!disposed) setIsLoading(l)
+      },
+      onErrorChange: (e) => {
+        if (!disposed) setError(e)
+      },
+      onStatusChange: (s) => {
+        if (!disposed) setStatus(s)
+      },
+      onResumeSnapshotChange: (snapshot) => {
+        if (!disposed) setResumeSnapshot(snapshot)
+      },
     }
 
     if (options.connection) {
@@ -176,12 +220,15 @@ export function useGeneration<
     })
   })
 
+  // Mount devtools only. Generation runs are never auto-started on mount —
+  // persisted state is read-only for display.
   onMount(() => {
     client().mountDevtools()
   })
 
   // Cleanup on unmount: stop any in-flight requests and unregister devtools
   onCleanup(() => {
+    disposed = true
     client().dispose()
   })
 
@@ -205,5 +252,9 @@ export function useGeneration<
     status,
     stop,
     reset,
+    resumeSnapshot,
+    resumeState: () => resumeSnapshot()?.resumeState ?? null,
+    pendingArtifacts: () => resumeSnapshot()?.pendingArtifacts ?? [],
+    resultArtifacts: () => resumeSnapshot()?.result?.artifacts ?? [],
   }
 }
diff --git a/packages/ai-solid/src/use-summarize.ts b/packages/ai-solid/src/use-summarize.ts
index b6a9eefc6..804d7cd6d 100644
--- a/packages/ai-solid/src/use-summarize.ts
+++ b/packages/ai-solid/src/use-summarize.ts
@@ -1,4 +1,8 @@
 import { useGeneration } from './use-generation'
+import type {
+  UseGenerationOptions,
+  UseGenerationReturn,
+} from './use-generation'
 import type { StreamChunk, SummarizationResult } from '@tanstack/ai'
 import type {
   AIDevtoolsDisplayOptions,
@@ -15,7 +19,12 @@ import type { Accessor } from 'solid-js'
  *
  * @template TOutput - The transformed output type (defaults to SummarizationResult)
  */
-export interface UseSummarizeOptions<TOutput = SummarizationResult> {
+export interface UseSummarizeOptions<
+  TOutput = SummarizationResult,
+> extends Pick<
+  UseGenerationOptions<SummarizeGenerateInput, SummarizationResult, TOutput>,
+  'persistence' | 'initialResumeSnapshot'
+> {
   /** Connect-based adapter for streaming transport (SSE, HTTP stream, custom) */
   connection?: ConnectConnectionAdapter
   /** Direct async function for summarization */
@@ -47,7 +56,10 @@ export interface UseSummarizeOptions<TOutput = SummarizationResult> {
  *
  * @template TOutput - The transformed output type (defaults to SummarizationResult)
  */
-export interface UseSummarizeReturn<TOutput = SummarizationResult> {
+export interface UseSummarizeReturn<TOutput = SummarizationResult> extends Omit<
+  UseGenerationReturn<TOutput>,
+  'generate'
+> {
   /** Trigger summarization */
   generate: (input: SummarizeGenerateInput) => Promise<void>
   /** The summarization result, or null */
@@ -58,10 +70,6 @@ export interface UseSummarizeReturn<TOutput = SummarizationResult> {
   error: Accessor<Error | undefined>
   /** Current state of the generation */
   status: Accessor<GenerationClientState>
-  /** Abort the current summarization */
-  stop: () => void
-  /** Clear result, error, and return to idle */
-  reset: () => void
 }
 
 /**
@@ -106,19 +114,19 @@ export function useSummarize<TTransformed = void>(
     hookName: 'useSummarize',
     outputKind: 'text' as const,
   }
-  const { generate, result, isLoading, error, status, stop, reset } =
-    useGeneration<SummarizeGenerateInput, SummarizationResult, TTransformed>({
-      ...options,
-      devtools,
-    })
+  const generation = useGeneration<
+    SummarizeGenerateInput,
+    SummarizationResult,
+    TTransformed
+  >({
+    ...options,
+    devtools,
+  })
 
   return {
-    generate: generate as (input: SummarizeGenerateInput) => Promise<void>,
-    result,
-    isLoading,
-    error,
-    status,
-    stop,
-    reset,
+    ...generation,
+    generate: generation.generate as (
+      input: SummarizeGenerateInput,
+    ) => Promise<void>,
   }
 }
diff --git a/packages/ai-solid/src/use-transcription.ts b/packages/ai-solid/src/use-transcription.ts
index e3e19ee7d..fadb5aabf 100644
--- a/packages/ai-solid/src/use-transcription.ts
+++ b/packages/ai-solid/src/use-transcription.ts
@@ -1,4 +1,8 @@
 import { useGeneration } from './use-generation'
+import type {
+  UseGenerationOptions,
+  UseGenerationReturn,
+} from './use-generation'
 import type { StreamChunk, TranscriptionResult } from '@tanstack/ai'
 import type {
   AIDevtoolsDisplayOptions,
@@ -15,7 +19,16 @@ import type { Accessor } from 'solid-js'
  *
  * @template TOutput - The transformed output type (defaults to TranscriptionResult)
  */
-export interface UseTranscriptionOptions<TOutput = TranscriptionResult> {
+export interface UseTranscriptionOptions<
+  TOutput = TranscriptionResult,
+> extends Pick<
+  UseGenerationOptions<
+    TranscriptionGenerateInput,
+    TranscriptionResult,
+    TOutput
+  >,
+  'persistence' | 'initialResumeSnapshot'
+> {
   /** Connect-based adapter for streaming transport (SSE, HTTP stream, custom) */
   connection?: ConnectConnectionAdapter
   /** Direct async function for transcription */
@@ -47,7 +60,9 @@ export interface UseTranscriptionOptions<TOutput = TranscriptionResult> {
  *
  * @template TOutput - The transformed output type (defaults to TranscriptionResult)
  */
-export interface UseTranscriptionReturn<TOutput = TranscriptionResult> {
+export interface UseTranscriptionReturn<
+  TOutput = TranscriptionResult,
+> extends Omit<UseGenerationReturn<TOutput>, 'generate'> {
   /** Trigger transcription */
   generate: (input: TranscriptionGenerateInput) => Promise<void>
   /** The transcription result, or null */
@@ -58,10 +73,6 @@ export interface UseTranscriptionReturn<TOutput = TranscriptionResult> {
   error: Accessor<Error | undefined>
   /** Current state of the generation */
   status: Accessor<GenerationClientState>
-  /** Abort the current transcription */
-  stop: () => void
-  /** Clear result, error, and return to idle */
-  reset: () => void
 }
 
 /**
@@ -112,20 +123,16 @@ export function useTranscription<TTransformed = void>(
     hookName: 'useTranscription',
     outputKind: 'text' as const,
   }
-  const { generate, result, isLoading, error, status, stop, reset } =
-    useGeneration<
-      TranscriptionGenerateInput,
-      TranscriptionResult,
-      TTransformed
-    >({ ...options, devtools })
+  const generation = useGeneration<
+    TranscriptionGenerateInput,
+    TranscriptionResult,
+    TTransformed
+  >({ ...options, devtools })
 
   return {
-    generate: generate as (input: TranscriptionGenerateInput) => Promise<void>,
-    result,
-    isLoading,
-    error,
-    status,
-    stop,
-    reset,
+    ...generation,
+    generate: generation.generate as (
+      input: TranscriptionGenerateInput,
+    ) => Promise<void>,
   }
 }
diff --git a/packages/ai-solid/tests/use-generation.test.ts b/packages/ai-solid/tests/use-generation.test.ts
index 562268aa0..c365c8b10 100644
--- a/packages/ai-solid/tests/use-generation.test.ts
+++ b/packages/ai-solid/tests/use-generation.test.ts
@@ -10,6 +10,12 @@ import { useGenerateVideo } from '../src/use-generate-video'
 import { createMockConnectionAdapter } from './test-utils'
 import type { StreamChunk, TTSResult, TranscriptionResult } from '@tanstack/ai'
 import { EventType } from '@tanstack/ai'
+import type {
+  ConnectConnectionAdapter,
+  GenerationResumeSnapshot,
+  GenerationServerPersistence,
+  RunAgentInputContext,
+} from '@tanstack/ai-client'
 
 // Helper to create generation stream chunks
 function createGenerationChunks(result: unknown): Array<StreamChunk> {
@@ -71,6 +77,60 @@ function createVideoChunks(jobId: string, url: string): Array<StreamChunk> {
   ]
 }
 
+const videoResumeSnapshot: GenerationResumeSnapshot = {
+  resumeState: {
+    threadId: 'thread-resume',
+    runId: 'run-resume',
+  },
+  status: 'running',
+}
+
+function createReplayVideoChunks(): Array<StreamChunk> {
+  return [
+    {
+      type: EventType.RUN_STARTED,
+      runId: 'run-resume',
+      threadId: 'thread-resume',
+      timestamp: Date.now(),
+    },
+    {
+      type: EventType.CUSTOM,
+      name: 'generation:result',
+      value: {
+        jobId: 'job-replay',
+        status: 'completed',
+        url: 'https://example.com/video.mp4',
+      },
+      timestamp: Date.now(),
+    },
+    {
+      type: EventType.RUN_FINISHED,
+      runId: 'run-resume',
+      threadId: 'thread-resume',
+      timestamp: Date.now(),
+    },
+  ]
+}
+
+function createRunContextCaptureAdapter(chunks: Array<StreamChunk>): {
+  adapter: ConnectConnectionAdapter
+  connect: ReturnType<typeof vi.fn>
+  runContexts: Array<RunAgentInputContext | undefined>
+} {
+  const runContexts: Array<RunAgentInputContext | undefined> = []
+  const connect = vi.fn()
+  const adapter: ConnectConnectionAdapter = {
+    async *connect(_messages, _data, _signal, runContext) {
+      connect(runContext)
+      runContexts.push(runContext)
+      for (const chunk of chunks) {
+        yield chunk
+      }
+    },
+  }
+  return { adapter, connect, runContexts }
+}
+
 // Helper to create error stream chunks.
 // NOTE: The AG-UI spec for RUN_ERROR carries `message` directly on the event
 // (not nested under `error`). We emit BOTH shapes here because GenerationClient
@@ -809,7 +869,7 @@ describe('useSummarize', () => {
       const mockResult = {
         id: 'sum-1',
         summary: 'A brief summary',
-        model: 'gpt-4',
+        model: 'gpt-5.5',
         usage: { promptTokens: 100, completionTokens: 20, totalTokens: 120 },
       }
       const onResult = vi.fn()
@@ -851,7 +911,7 @@ describe('useSummarize', () => {
 
   describe('connection mode', () => {
     it('should summarize text using connection', async () => {
-      const mockResult = { summary: 'A brief summary', model: 'gpt-4' }
+      const mockResult = { summary: 'A brief summary', model: 'gpt-5.5' }
       const chunks = createGenerationChunks(mockResult)
       const adapter = createMockConnectionAdapter({ chunks })
 
@@ -869,7 +929,7 @@ describe('useSummarize', () => {
       const mockResult = {
         id: 'sum-1',
         summary: 'A brief summary',
-        model: 'gpt-4',
+        model: 'gpt-5.5',
         usage: { promptTokens: 100, completionTokens: 20, totalTokens: 120 },
       }
 
@@ -1074,6 +1134,38 @@ describe('useGenerateVideo', () => {
       expect(result.isLoading()).toBe(false)
       expect(result.status()).toBe('idle')
     })
+
+    it('does not auto-fire a video generation on mount from a persisted running snapshot', async () => {
+      // Regression guard for the removed generation resume surface (video).
+      const { adapter, connect } = createRunContextCaptureAdapter(
+        createReplayVideoChunks(),
+      )
+      const persistence: GenerationServerPersistence = {
+        getItem: vi.fn(() => videoResumeSnapshot),
+        setItem: vi.fn(),
+        removeItem: vi.fn(),
+      }
+
+      const { result } = renderHook(() =>
+        useGenerateVideo({
+          id: 'video-no-auto-fire',
+          connection: adapter,
+          persistence: { server: persistence },
+          initialResumeSnapshot: videoResumeSnapshot,
+        }),
+      )
+
+      await Promise.resolve()
+      await new Promise((resolve) => setTimeout(resolve, 0))
+
+      expect(connect).not.toHaveBeenCalled()
+      expect(persistence.getItem).not.toHaveBeenCalled()
+      expect(result.isLoading()).toBe(false)
+      expect(result.status()).toBe('idle')
+      // The persisted snapshot remains exposed as read-only state.
+      expect(result.resumeSnapshot()).toEqual(videoResumeSnapshot)
+      expect(result.resumeState()).toEqual(videoResumeSnapshot.resumeState)
+    })
   })
 
   describe('error handling', () => {
diff --git a/packages/ai-svelte/src/create-chat.svelte.ts b/packages/ai-svelte/src/create-chat.svelte.ts
index 506d9843f..a631b3fd9 100644
--- a/packages/ai-svelte/src/create-chat.svelte.ts
+++ b/packages/ai-svelte/src/create-chat.svelte.ts
@@ -1,7 +1,10 @@
 import { ChatClient } from '@tanstack/ai-client'
 import { createChatDevtoolsBridge } from '@tanstack/ai-client/devtools'
+import { onMount } from 'svelte'
 import type {
   ChatClientState,
+  ChatPendingInterrupt,
+  ChatResumeState,
   ConnectionStatus,
   InferredClientContext,
   StructuredOutputPart,
@@ -10,6 +13,7 @@ import type {
   AnyClientTool,
   InferSchemaType,
   ModelMessage,
+  RunAgentResumeItem,
   SchemaInput,
   StreamChunk,
 } from '@tanstack/ai'
@@ -71,6 +75,12 @@ export function createChat<
   let isSubscribed = $state(false)
   let connectionStatus = $state<ConnectionStatus>('disconnected')
   let sessionGenerating = $state(false)
+  let resumeState = $state<ChatResumeState | null>(
+    options.initialResumeSnapshot?.resumeState ?? null,
+  )
+  let pendingInterrupts = $state<Array<ChatPendingInterrupt>>(
+    options.initialResumeSnapshot?.pendingInterrupts ?? [],
+  )
 
   // Structured-output `partial` / `final` are derived from `messages` —
   // specifically from the structured-output part on the latest assistant
@@ -103,6 +113,9 @@ export function createChat<
     ...(options.persistence !== undefined && {
       persistence: options.persistence,
     }),
+    ...(options.initialResumeSnapshot !== undefined && {
+      initialResumeSnapshot: options.initialResumeSnapshot,
+    }),
     ...(options.body !== undefined && { body: options.body }),
     ...(options.threadId !== undefined && { threadId: options.threadId }),
     ...(options.forwardedProps !== undefined && {
@@ -137,6 +150,7 @@ export function createChat<
     },
     onLoadingChange: (newIsLoading: boolean) => {
       isLoading = newIsLoading
+      syncResumeState()
     },
     onStatusChange: (newStatus: ChatClientState) => {
       status = newStatus
@@ -153,8 +167,17 @@ export function createChat<
     onSessionGeneratingChange: (isGenerating: boolean) => {
       sessionGenerating = isGenerating
     },
+    onResumeStateChange: (nextResumeState, nextPendingInterrupts) => {
+      resumeState = nextResumeState
+      pendingInterrupts = nextPendingInterrupts
+    },
   })
 
+  function syncResumeState() {
+    resumeState = client.getResumeState()
+    pendingInterrupts = client.getPendingInterrupts()
+  }
+
   messages = client.getMessages()
 
   if (options.live) {
@@ -163,6 +186,19 @@ export function createChat<
 
   client.mountDevtools()
 
+  if (typeof window !== 'undefined') {
+    try {
+      onMount(() => {
+        // Delivery-durability resume is transparent: the resumable SSE
+        // connection adapter reattaches via the browser's native
+        // Last-Event-ID on reconnect. We only seed interrupt (state) resume.
+        syncResumeState()
+      })
+    } catch {
+      // Svelte lifecycle hooks are only valid during component initialization.
+    }
+  }
+
   // Note: Cleanup is handled by calling stop() directly when needed.
   // Unlike React/Vue/Solid, Svelte 5 runes like $effect can only be used
   // during component initialization, so we don't add automatic cleanup here.
@@ -170,15 +206,27 @@ export function createChat<
 
   // Define methods
   const sendMessage = async (content: string | MultimodalContent) => {
-    await client.sendMessage(content)
+    try {
+      await client.sendMessage(content)
+    } finally {
+      syncResumeState()
+    }
   }
 
   const append = async (message: ModelMessage | UIMessage<TTools>) => {
-    await client.append(message)
+    try {
+      await client.append(message)
+    } finally {
+      syncResumeState()
+    }
   }
 
   const reload = async () => {
-    await client.reload()
+    try {
+      await client.reload()
+    } finally {
+      syncResumeState()
+    }
   }
 
   const stop = () => {
@@ -191,6 +239,7 @@ export function createChat<
 
   const clear = () => {
     client.clear()
+    syncResumeState()
   }
 
   const setMessages = (newMessages: Array<UIMessage<TTools>>) => {
@@ -212,6 +261,16 @@ export function createChat<
     approved: boolean
   }) => {
     await client.addToolApprovalResponse(response)
+    syncResumeState()
+  }
+
+  const resumeInterrupts = async (
+    resumeItems: Array<RunAgentResumeItem>,
+    state?: ChatResumeState,
+  ) => {
+    const result = await client.resumeInterrupts(resumeItems, state)
+    syncResumeState()
+    return result
   }
 
   /**
@@ -293,6 +352,12 @@ export function createChat<
     get sessionGenerating() {
       return sessionGenerating
     },
+    get resumeState() {
+      return resumeState
+    },
+    get pendingInterrupts() {
+      return pendingInterrupts
+    },
     get partial() {
       return partial
     },
@@ -308,6 +373,7 @@ export function createChat<
     clear,
     addToolResult,
     addToolApprovalResponse,
+    resumeInterrupts,
     updateBody,
     updateForwardedProps,
     updateContext,
diff --git a/packages/ai-svelte/src/create-generate-audio.svelte.ts b/packages/ai-svelte/src/create-generate-audio.svelte.ts
index 5838ee6f2..87ded3f2a 100644
--- a/packages/ai-svelte/src/create-generate-audio.svelte.ts
+++ b/packages/ai-svelte/src/create-generate-audio.svelte.ts
@@ -1,4 +1,8 @@
 import { createGeneration } from './create-generation.svelte'
+import type {
+  CreateGenerationOptions,
+  CreateGenerationReturn,
+} from './create-generation.svelte'
 import type { AudioGenerationResult, StreamChunk } from '@tanstack/ai'
 import type {
   AIDevtoolsDisplayOptions,
@@ -14,7 +18,12 @@ import type {
  *
  * @template TOutput - The output type after optional transform (defaults to AudioGenerationResult)
  */
-export interface CreateGenerateAudioOptions<TOutput = AudioGenerationResult> {
+export interface CreateGenerateAudioOptions<
+  TOutput = AudioGenerationResult,
+> extends Pick<
+  CreateGenerationOptions<AudioGenerateInput, AudioGenerationResult, TOutput>,
+  'persistence' | 'initialResumeSnapshot'
+> {
   /** Connect-based adapter for streaming transport (SSE, HTTP stream, custom) */
   connection?: ConnectConnectionAdapter
   /** Direct async function for audio generation */
@@ -46,7 +55,9 @@ export interface CreateGenerateAudioOptions<TOutput = AudioGenerationResult> {
  *
  * @template TOutput - The output type (after optional transform)
  */
-export interface CreateGenerateAudioReturn<TOutput = AudioGenerationResult> {
+export interface CreateGenerateAudioReturn<
+  TOutput = AudioGenerationResult,
+> extends Omit<CreateGenerationReturn<TOutput>, 'generate'> {
   /** The generation result containing audio, or null */
   readonly result: TOutput | null
   /** Whether generation is in progress */
@@ -57,12 +68,6 @@ export interface CreateGenerateAudioReturn<TOutput = AudioGenerationResult> {
   readonly status: GenerationClientState
   /** Trigger audio generation */
   generate: (input: AudioGenerateInput) => Promise<void>
-  /** Abort the current generation */
-  stop: () => void
-  /** Clear result, error, and return to idle */
-  reset: () => void
-  /** Update additional body parameters */
-  updateBody: (body: Record<string, any>) => void
 }
 
 /**
@@ -130,5 +135,18 @@ export function createGenerateAudio<TTransformed = void>(
     stop: gen.stop,
     reset: gen.reset,
     updateBody: gen.updateBody,
+    dispose: gen.dispose,
+    get resumeSnapshot() {
+      return gen.resumeSnapshot
+    },
+    get resumeState() {
+      return gen.resumeState
+    },
+    get pendingArtifacts() {
+      return gen.pendingArtifacts
+    },
+    get resultArtifacts() {
+      return gen.resultArtifacts
+    },
   }
 }
diff --git a/packages/ai-svelte/src/create-generate-image.svelte.ts b/packages/ai-svelte/src/create-generate-image.svelte.ts
index 0909ddca2..e42b70d55 100644
--- a/packages/ai-svelte/src/create-generate-image.svelte.ts
+++ b/packages/ai-svelte/src/create-generate-image.svelte.ts
@@ -1,4 +1,8 @@
 import { createGeneration } from './create-generation.svelte'
+import type {
+  CreateGenerationOptions,
+  CreateGenerationReturn,
+} from './create-generation.svelte'
 import type { ImageGenerationResult, StreamChunk } from '@tanstack/ai'
 import type {
   AIDevtoolsDisplayOptions,
@@ -14,7 +18,12 @@ import type {
  *
  * @template TOutput - The output type after optional transform (defaults to ImageGenerationResult)
  */
-export interface CreateGenerateImageOptions<TOutput = ImageGenerationResult> {
+export interface CreateGenerateImageOptions<
+  TOutput = ImageGenerationResult,
+> extends Pick<
+  CreateGenerationOptions<ImageGenerateInput, ImageGenerationResult, TOutput>,
+  'persistence' | 'initialResumeSnapshot'
+> {
   /** Connect-based adapter for streaming transport (SSE, HTTP stream, custom) */
   connection?: ConnectConnectionAdapter
   /** Direct async function for image generation */
@@ -46,7 +55,9 @@ export interface CreateGenerateImageOptions<TOutput = ImageGenerationResult> {
  *
  * @template TOutput - The output type (after optional transform)
  */
-export interface CreateGenerateImageReturn<TOutput = ImageGenerationResult> {
+export interface CreateGenerateImageReturn<
+  TOutput = ImageGenerationResult,
+> extends Omit<CreateGenerationReturn<TOutput>, 'generate'> {
   /** The generation result containing images, or null */
   readonly result: TOutput | null
   /** Whether generation is in progress */
@@ -57,12 +68,6 @@ export interface CreateGenerateImageReturn<TOutput = ImageGenerationResult> {
   readonly status: GenerationClientState
   /** Trigger image generation */
   generate: (input: ImageGenerateInput) => Promise<void>
-  /** Abort the current generation */
-  stop: () => void
-  /** Clear result, error, and return to idle */
-  reset: () => void
-  /** Update additional body parameters */
-  updateBody: (body: Record<string, any>) => void
 }
 
 /**
@@ -139,5 +144,18 @@ export function createGenerateImage<TTransformed = void>(
     stop: gen.stop,
     reset: gen.reset,
     updateBody: gen.updateBody,
+    dispose: gen.dispose,
+    get resumeSnapshot() {
+      return gen.resumeSnapshot
+    },
+    get resumeState() {
+      return gen.resumeState
+    },
+    get pendingArtifacts() {
+      return gen.pendingArtifacts
+    },
+    get resultArtifacts() {
+      return gen.resultArtifacts
+    },
   }
 }
diff --git a/packages/ai-svelte/src/create-generate-speech.svelte.ts b/packages/ai-svelte/src/create-generate-speech.svelte.ts
index 20ccafbf9..90daf58e4 100644
--- a/packages/ai-svelte/src/create-generate-speech.svelte.ts
+++ b/packages/ai-svelte/src/create-generate-speech.svelte.ts
@@ -1,4 +1,8 @@
 import { createGeneration } from './create-generation.svelte'
+import type {
+  CreateGenerationOptions,
+  CreateGenerationReturn,
+} from './create-generation.svelte'
 import type { StreamChunk, TTSResult } from '@tanstack/ai'
 import type {
   AIDevtoolsDisplayOptions,
@@ -14,7 +18,10 @@ import type {
  *
  * @template TOutput - The output type after optional transform (defaults to TTSResult)
  */
-export interface CreateGenerateSpeechOptions<TOutput = TTSResult> {
+export interface CreateGenerateSpeechOptions<TOutput = TTSResult> extends Pick<
+  CreateGenerationOptions<SpeechGenerateInput, TTSResult, TOutput>,
+  'persistence' | 'initialResumeSnapshot'
+> {
   /** Connect-based adapter for streaming transport (SSE, HTTP stream, custom) */
   connection?: ConnectConnectionAdapter
   /** Direct async function for speech generation */
@@ -46,7 +53,10 @@ export interface CreateGenerateSpeechOptions<TOutput = TTSResult> {
  *
  * @template TOutput - The output type (after optional transform)
  */
-export interface CreateGenerateSpeechReturn<TOutput = TTSResult> {
+export interface CreateGenerateSpeechReturn<TOutput = TTSResult> extends Omit<
+  CreateGenerationReturn<TOutput>,
+  'generate'
+> {
   /** The TTS result containing audio data, or null */
   readonly result: TOutput | null
   /** Whether generation is in progress */
@@ -57,12 +67,6 @@ export interface CreateGenerateSpeechReturn<TOutput = TTSResult> {
   readonly status: GenerationClientState
   /** Trigger speech generation */
   generate: (input: SpeechGenerateInput) => Promise<void>
-  /** Abort the current generation */
-  stop: () => void
-  /** Clear result, error, and return to idle */
-  reset: () => void
-  /** Update additional body parameters */
-  updateBody: (body: Record<string, any>) => void
 }
 
 /**
@@ -126,5 +130,18 @@ export function createGenerateSpeech<TTransformed = void>(
     stop: gen.stop,
     reset: gen.reset,
     updateBody: gen.updateBody,
+    dispose: gen.dispose,
+    get resumeSnapshot() {
+      return gen.resumeSnapshot
+    },
+    get resumeState() {
+      return gen.resumeState
+    },
+    get pendingArtifacts() {
+      return gen.pendingArtifacts
+    },
+    get resultArtifacts() {
+      return gen.resultArtifacts
+    },
   }
 }
diff --git a/packages/ai-svelte/src/create-generate-video.svelte.ts b/packages/ai-svelte/src/create-generate-video.svelte.ts
index 05f2d787b..45460fc1e 100644
--- a/packages/ai-svelte/src/create-generate-video.svelte.ts
+++ b/packages/ai-svelte/src/create-generate-video.svelte.ts
@@ -6,11 +6,16 @@ import type {
   ConnectConnectionAdapter,
   GenerationClientState,
   GenerationFetcher,
+  GenerationPendingArtifact,
+  GenerationPersistenceOptions,
+  GenerationResumeSnapshot,
+  GenerationResumeState,
   InferGenerationOutputFromReturn,
   VideoGenerateInput,
   VideoGenerateResult,
   VideoStatusInfo,
 } from '@tanstack/ai-client'
+import type { PersistedArtifactRef } from '@tanstack/ai/client'
 
 /**
  * Options for the createGenerateVideo function.
@@ -28,6 +33,10 @@ export interface CreateGenerateVideoOptions<TOutput = VideoGenerateResult> {
   body?: Record<string, any>
   /** Display options for TanStack AI Devtools. */
   devtools?: AIDevtoolsDisplayOptions
+  /** Server-side lightweight generation state persistence. */
+  persistence?: GenerationPersistenceOptions
+  /** Initial lightweight resume snapshot restored by the app (read-only state). */
+  initialResumeSnapshot?: GenerationResumeSnapshot
   /**
    * Callback when video generation completes. Can optionally return a transformed value.
    *
@@ -76,6 +85,14 @@ export interface CreateGenerateVideoReturn<TOutput = VideoGenerateResult> {
   dispose: () => void
   /** Update additional body parameters */
   updateBody: (body: Record<string, any>) => void
+  /** Lightweight generation resume snapshot, if one is available */
+  readonly resumeSnapshot: GenerationResumeSnapshot | undefined
+  /** Observed run/cursor metadata from the snapshot (read-only state) */
+  readonly resumeState: GenerationResumeState | null
+  /** Pending persisted artifact references observed during generation/replay */
+  readonly pendingArtifacts: Array<GenerationPendingArtifact>
+  /** Final persisted artifact references observed from a replayed result */
+  readonly resultArtifacts: Array<PersistedArtifactRef>
 }
 
 /**
@@ -133,6 +150,17 @@ export function createGenerateVideo<TTransformed = void>(
   let isLoading = $state(false)
   let error = $state<Error | undefined>(undefined)
   let status = $state<GenerationClientState>('idle')
+  let resumeSnapshot = $state<GenerationResumeSnapshot | undefined>(
+    options.initialResumeSnapshot,
+  )
+  let disposed = false
+
+  const setResumeSnapshotState = (
+    snapshot: GenerationResumeSnapshot | undefined,
+  ) => {
+    if (disposed) return
+    resumeSnapshot = snapshot
+  }
 
   // `body` uses a conditional spread because `VideoGenerationClientOptions.body`
   // is declared `body?: Record<string, any>` (absent vs. present) under
@@ -141,6 +169,12 @@ export function createGenerateVideo<TTransformed = void>(
   const baseOptions = {
     id: clientId,
     body: options.body,
+    ...(options.persistence !== undefined && {
+      persistence: options.persistence,
+    }),
+    ...(options.initialResumeSnapshot !== undefined && {
+      initialResumeSnapshot: options.initialResumeSnapshot,
+    }),
     devtoolsBridgeFactory: createVideoDevtoolsBridge,
     devtools: {
       ...options.devtools,
@@ -154,29 +188,46 @@ export function createGenerateVideo<TTransformed = void>(
     onResult: ((r: VideoGenerateResult) => options.onResult?.(r)) as (
       result: VideoGenerateResult,
     ) => TOutput | null | void,
-    onError: (e: Error) => options.onError?.(e),
-    onProgress: (p: number, m?: string) => options.onProgress?.(p, m),
-    onChunk: (c: StreamChunk) => options.onChunk?.(c),
-    onJobCreated: (id: string) => options.onJobCreated?.(id),
-    onStatusUpdate: (s: VideoStatusInfo) => options.onStatusUpdate?.(s),
+    onError: (e: Error) => {
+      if (!disposed) options.onError?.(e)
+    },
+    onProgress: (p: number, m?: string) => {
+      if (!disposed) options.onProgress?.(p, m)
+    },
+    onChunk: (c: StreamChunk) => {
+      if (!disposed) options.onChunk?.(c)
+    },
+    onJobCreated: (id: string) => {
+      if (!disposed) options.onJobCreated?.(id)
+    },
+    onStatusUpdate: (s: VideoStatusInfo) => {
+      if (!disposed) options.onStatusUpdate?.(s)
+    },
     onResultChange: (r: TOutput | null) => {
+      if (disposed) return
       result = r
     },
     onLoadingChange: (l: boolean) => {
+      if (disposed) return
       isLoading = l
     },
     onErrorChange: (e: Error | undefined) => {
+      if (disposed) return
       error = e
     },
     onStatusChange: (s: GenerationClientState) => {
+      if (disposed) return
       status = s
     },
     onJobIdChange: (id: string | null) => {
+      if (disposed) return
       jobId = id
     },
     onVideoStatusChange: (s: VideoStatusInfo | null) => {
+      if (disposed) return
       videoStatus = s
     },
+    onResumeSnapshotChange: setResumeSnapshotState,
   }
 
   let client: VideoGenerationClient<TOutput>
@@ -197,6 +248,8 @@ export function createGenerateVideo<TTransformed = void>(
     )
   }
 
+  // Mount devtools only. Generation runs are never auto-started on setup —
+  // persisted state is read-only for display.
   client.mountDevtools()
 
   // Note: Cleanup is handled by calling dispose() directly when needed.
@@ -217,6 +270,7 @@ export function createGenerateVideo<TTransformed = void>(
   }
 
   const dispose = () => {
+    disposed = true
     client.dispose()
   }
 
@@ -248,5 +302,17 @@ export function createGenerateVideo<TTransformed = void>(
     reset,
     dispose,
     updateBody,
+    get resumeSnapshot() {
+      return resumeSnapshot
+    },
+    get resumeState() {
+      return resumeSnapshot?.resumeState ?? null
+    },
+    get pendingArtifacts() {
+      return resumeSnapshot?.pendingArtifacts ?? []
+    },
+    get resultArtifacts() {
+      return resumeSnapshot?.result?.artifacts ?? []
+    },
   }
 }
diff --git a/packages/ai-svelte/src/create-generation.svelte.ts b/packages/ai-svelte/src/create-generation.svelte.ts
index a731ac398..5f80a7b7e 100644
--- a/packages/ai-svelte/src/create-generation.svelte.ts
+++ b/packages/ai-svelte/src/create-generation.svelte.ts
@@ -7,8 +7,13 @@ import type {
   GenerationClientOptions,
   GenerationClientState,
   GenerationFetcher,
+  GenerationPendingArtifact,
+  GenerationPersistenceOptions,
+  GenerationResumeSnapshot,
+  GenerationResumeState,
   InferGenerationOutputFromReturn,
 } from '@tanstack/ai-client'
+import type { PersistedArtifactRef } from '@tanstack/ai/client'
 
 /**
  * Options for the createGeneration function.
@@ -30,6 +35,10 @@ export interface CreateGenerationOptions<TInput, TResult, TOutput = TResult> {
   body?: Record<string, any>
   /** Display options for TanStack AI Devtools. */
   devtools?: AIDevtoolsDisplayOptions
+  /** Server-side lightweight generation state persistence. */
+  persistence?: GenerationPersistenceOptions
+  /** Initial lightweight resume snapshot restored by the app (read-only state). */
+  initialResumeSnapshot?: GenerationResumeSnapshot
   /**
    * Callback when a result is received. Can optionally return a transformed value.
    *
@@ -70,6 +79,14 @@ export interface CreateGenerationReturn<TOutput> {
   dispose: () => void
   /** Update additional body parameters */
   updateBody: (body: Record<string, any>) => void
+  /** Lightweight generation resume snapshot, if one is available */
+  readonly resumeSnapshot: GenerationResumeSnapshot | undefined
+  /** Observed run/cursor metadata from the snapshot (read-only state) */
+  readonly resumeState: GenerationResumeState | null
+  /** Pending persisted artifact references observed during generation/replay */
+  readonly pendingArtifacts: Array<GenerationPendingArtifact>
+  /** Final persisted artifact references observed from a replayed result */
+  readonly resultArtifacts: Array<PersistedArtifactRef>
 }
 
 /**
@@ -129,6 +146,17 @@ export function createGeneration<
   let isLoading = $state(false)
   let error = $state<Error | undefined>(undefined)
   let status = $state<GenerationClientState>('idle')
+  let resumeSnapshot = $state<GenerationResumeSnapshot | undefined>(
+    options.initialResumeSnapshot,
+  )
+  let disposed = false
+
+  const setResumeSnapshotState = (
+    snapshot: GenerationResumeSnapshot | undefined,
+  ) => {
+    if (disposed) return
+    resumeSnapshot = snapshot
+  }
 
   // `body` uses a conditional spread because `GenerationClientOptions.body`
   // is declared `body?: Record<string, any>` (absent vs. present) under
@@ -138,6 +166,12 @@ export function createGeneration<
   const clientOptions: GenerationClientOptions<TInput, TResult, TOutput> = {
     id: clientId,
     body: options.body,
+    ...(options.persistence !== undefined && {
+      persistence: options.persistence,
+    }),
+    ...(options.initialResumeSnapshot !== undefined && {
+      initialResumeSnapshot: options.initialResumeSnapshot,
+    }),
     devtoolsBridgeFactory: createGenerationDevtoolsBridge,
     devtools: {
       ...options.devtools,
@@ -150,21 +184,32 @@ export function createGeneration<
     onResult: ((r: TResult) => options.onResult?.(r)) as (
       result: TResult,
     ) => TOutput | null | void,
-    onError: (e: Error) => options.onError?.(e),
-    onProgress: (p: number, m?: string) => options.onProgress?.(p, m),
-    onChunk: (c: StreamChunk) => options.onChunk?.(c),
+    onError: (e: Error) => {
+      if (!disposed) options.onError?.(e)
+    },
+    onProgress: (p: number, m?: string) => {
+      if (!disposed) options.onProgress?.(p, m)
+    },
+    onChunk: (c: StreamChunk) => {
+      if (!disposed) options.onChunk?.(c)
+    },
     onResultChange: (r: TOutput | null) => {
+      if (disposed) return
       result = r
     },
     onLoadingChange: (l: boolean) => {
+      if (disposed) return
       isLoading = l
     },
     onErrorChange: (e: Error | undefined) => {
+      if (disposed) return
       error = e
     },
     onStatusChange: (s: GenerationClientState) => {
+      if (disposed) return
       status = s
     },
+    onResumeSnapshotChange: setResumeSnapshotState,
   }
 
   let client: GenerationClient<TInput, TResult, TOutput>
@@ -185,6 +230,8 @@ export function createGeneration<
     )
   }
 
+  // Mount devtools only. Generation runs are never auto-started on setup —
+  // persisted state is read-only for display.
   client.mountDevtools()
 
   // Note: Cleanup is handled by calling dispose() directly when needed.
@@ -205,6 +252,7 @@ export function createGeneration<
   }
 
   const dispose = () => {
+    disposed = true
     client.dispose()
   }
 
@@ -230,5 +278,17 @@ export function createGeneration<
     reset,
     dispose,
     updateBody,
+    get resumeSnapshot() {
+      return resumeSnapshot
+    },
+    get resumeState() {
+      return resumeSnapshot?.resumeState ?? null
+    },
+    get pendingArtifacts() {
+      return resumeSnapshot?.pendingArtifacts ?? []
+    },
+    get resultArtifacts() {
+      return resumeSnapshot?.result?.artifacts ?? []
+    },
   }
 }
diff --git a/packages/ai-svelte/src/create-summarize.svelte.ts b/packages/ai-svelte/src/create-summarize.svelte.ts
index 0009eee15..5d582de21 100644
--- a/packages/ai-svelte/src/create-summarize.svelte.ts
+++ b/packages/ai-svelte/src/create-summarize.svelte.ts
@@ -1,4 +1,8 @@
 import { createGeneration } from './create-generation.svelte'
+import type {
+  CreateGenerationOptions,
+  CreateGenerationReturn,
+} from './create-generation.svelte'
 import type { StreamChunk, SummarizationResult } from '@tanstack/ai'
 import type {
   AIDevtoolsDisplayOptions,
@@ -14,7 +18,12 @@ import type {
  *
  * @template TOutput - The output type after optional transform (defaults to SummarizationResult)
  */
-export interface CreateSummarizeOptions<TOutput = SummarizationResult> {
+export interface CreateSummarizeOptions<
+  TOutput = SummarizationResult,
+> extends Pick<
+  CreateGenerationOptions<SummarizeGenerateInput, SummarizationResult, TOutput>,
+  'persistence' | 'initialResumeSnapshot'
+> {
   /** Connect-based adapter for streaming transport (SSE, HTTP stream, custom) */
   connection?: ConnectConnectionAdapter
   /** Direct async function for summarization */
@@ -46,7 +55,9 @@ export interface CreateSummarizeOptions<TOutput = SummarizationResult> {
  *
  * @template TOutput - The output type (after optional transform)
  */
-export interface CreateSummarizeReturn<TOutput = SummarizationResult> {
+export interface CreateSummarizeReturn<
+  TOutput = SummarizationResult,
+> extends Omit<CreateGenerationReturn<TOutput>, 'generate'> {
   /** The summarization result, or null */
   readonly result: TOutput | null
   /** Whether summarization is in progress */
@@ -57,12 +68,6 @@ export interface CreateSummarizeReturn<TOutput = SummarizationResult> {
   readonly status: GenerationClientState
   /** Trigger summarization */
   generate: (input: SummarizeGenerateInput) => Promise<void>
-  /** Abort the current summarization */
-  stop: () => void
-  /** Clear result, error, and return to idle */
-  reset: () => void
-  /** Update additional body parameters */
-  updateBody: (body: Record<string, any>) => void
 }
 
 /**
@@ -134,5 +139,18 @@ export function createSummarize<TTransformed = void>(
     stop: gen.stop,
     reset: gen.reset,
     updateBody: gen.updateBody,
+    dispose: gen.dispose,
+    get resumeSnapshot() {
+      return gen.resumeSnapshot
+    },
+    get resumeState() {
+      return gen.resumeState
+    },
+    get pendingArtifacts() {
+      return gen.pendingArtifacts
+    },
+    get resultArtifacts() {
+      return gen.resultArtifacts
+    },
   }
 }
diff --git a/packages/ai-svelte/src/create-transcription.svelte.ts b/packages/ai-svelte/src/create-transcription.svelte.ts
index b6583cb98..f6a7fdfae 100644
--- a/packages/ai-svelte/src/create-transcription.svelte.ts
+++ b/packages/ai-svelte/src/create-transcription.svelte.ts
@@ -1,4 +1,8 @@
 import { createGeneration } from './create-generation.svelte'
+import type {
+  CreateGenerationOptions,
+  CreateGenerationReturn,
+} from './create-generation.svelte'
 import type { StreamChunk, TranscriptionResult } from '@tanstack/ai'
 import type {
   AIDevtoolsDisplayOptions,
@@ -14,7 +18,16 @@ import type {
  *
  * @template TOutput - The output type after optional transform (defaults to TranscriptionResult)
  */
-export interface CreateTranscriptionOptions<TOutput = TranscriptionResult> {
+export interface CreateTranscriptionOptions<
+  TOutput = TranscriptionResult,
+> extends Pick<
+  CreateGenerationOptions<
+    TranscriptionGenerateInput,
+    TranscriptionResult,
+    TOutput
+  >,
+  'persistence' | 'initialResumeSnapshot'
+> {
   /** Connect-based adapter for streaming transport (SSE, HTTP stream, custom) */
   connection?: ConnectConnectionAdapter
   /** Direct async function for transcription */
@@ -46,7 +59,9 @@ export interface CreateTranscriptionOptions<TOutput = TranscriptionResult> {
  *
  * @template TOutput - The output type (after optional transform)
  */
-export interface CreateTranscriptionReturn<TOutput = TranscriptionResult> {
+export interface CreateTranscriptionReturn<
+  TOutput = TranscriptionResult,
+> extends Omit<CreateGenerationReturn<TOutput>, 'generate'> {
   /** The transcription result, or null */
   readonly result: TOutput | null
   /** Whether transcription is in progress */
@@ -57,12 +72,6 @@ export interface CreateTranscriptionReturn<TOutput = TranscriptionResult> {
   readonly status: GenerationClientState
   /** Trigger transcription */
   generate: (input: TranscriptionGenerateInput) => Promise<void>
-  /** Abort the current transcription */
-  stop: () => void
-  /** Clear result, error, and return to idle */
-  reset: () => void
-  /** Update additional body parameters */
-  updateBody: (body: Record<string, any>) => void
 }
 
 /**
@@ -141,5 +150,18 @@ export function createTranscription<TTransformed = void>(
     stop: gen.stop,
     reset: gen.reset,
     updateBody: gen.updateBody,
+    dispose: gen.dispose,
+    get resumeSnapshot() {
+      return gen.resumeSnapshot
+    },
+    get resumeState() {
+      return gen.resumeState
+    },
+    get pendingArtifacts() {
+      return gen.pendingArtifacts
+    },
+    get resultArtifacts() {
+      return gen.resultArtifacts
+    },
   }
 }
diff --git a/packages/ai-svelte/src/types.ts b/packages/ai-svelte/src/types.ts
index ffa7c0122..e416fdb15 100644
--- a/packages/ai-svelte/src/types.ts
+++ b/packages/ai-svelte/src/types.ts
@@ -2,13 +2,16 @@ import type {
   AnyClientTool,
   InferSchemaType,
   ModelMessage,
+  RunAgentResumeItem,
   SchemaInput,
 } from '@tanstack/ai'
 import type {
   AIDevtoolsDisplayOptions,
   ChatClientOptions,
   ChatClientState,
+  ChatPendingInterrupt,
   ChatRequestBody,
+  ChatResumeState,
   ClientContextOptionFromTools,
   ConnectionStatus,
   DistributedOmit,
@@ -66,6 +69,7 @@ export type CreateChatOptions<
   | 'onSubscriptionChange'
   | 'onConnectionStatusChange'
   | 'onSessionGeneratingChange'
+  | 'onResumeStateChange'
   | 'context'
   | 'devtools'
 > & {
@@ -152,6 +156,13 @@ interface BaseCreateChatReturn<
     approved: boolean
   }) => Promise<void>
 
+  readonly resumeState: ChatResumeState | null
+  readonly pendingInterrupts: Array<ChatPendingInterrupt>
+  resumeInterrupts: (
+    resume: Array<RunAgentResumeItem>,
+    state?: ChatResumeState,
+  ) => Promise<boolean>
+
   /**
    * Reload the last assistant message
    */
diff --git a/packages/ai-svelte/tests/create-generation.test.ts b/packages/ai-svelte/tests/create-generation.test.ts
index ca2761c9f..2da5759e4 100644
--- a/packages/ai-svelte/tests/create-generation.test.ts
+++ b/packages/ai-svelte/tests/create-generation.test.ts
@@ -8,6 +8,11 @@ import { createGenerateVideo } from '../src/create-generate-video.svelte'
 import { createMockConnectionAdapter } from './test-utils'
 import { EventType, type StreamChunk } from '@tanstack/ai'
 import type { TTSResult, TranscriptionResult } from '@tanstack/ai'
+import type {
+  ConnectConnectionAdapter,
+  GenerationResumeSnapshot,
+  RunAgentInputContext,
+} from '@tanstack/ai-client'
 
 // Helper to create generation stream chunks
 function createGenerationChunks(result: unknown): Array<StreamChunk> {
@@ -71,6 +76,33 @@ function createVideoChunks(jobId: string, url: string): Array<StreamChunk> {
   ]
 }
 
+const videoResumeSnapshot: GenerationResumeSnapshot = {
+  resumeState: {
+    threadId: 'thread-resume',
+    runId: 'run-resume',
+  },
+  status: 'running',
+}
+
+function createRunContextCaptureAdapter(chunks: Array<StreamChunk>): {
+  adapter: ConnectConnectionAdapter
+  connect: ReturnType<typeof vi.fn>
+  runContexts: Array<RunAgentInputContext | undefined>
+} {
+  const runContexts: Array<RunAgentInputContext | undefined> = []
+  const connect = vi.fn()
+  const adapter: ConnectConnectionAdapter = {
+    async *connect(_messages, _data, _signal, runContext) {
+      connect(runContext)
+      runContexts.push(runContext)
+      for (const chunk of chunks) {
+        yield chunk
+      }
+    },
+  }
+  return { adapter, connect, runContexts }
+}
+
 // Helper to create error stream chunks
 function createErrorChunks(message: string): Array<StreamChunk> {
   return [
@@ -186,6 +218,33 @@ describe('createGeneration', () => {
       expect(gen.status).toBe('error')
       expect(gen.error?.message).toBe('Generation failed')
     })
+
+    it('does not auto-fire a generation on setup from a persisted running snapshot', async () => {
+      // Regression guard for the removed generation resume surface.
+      const snapshot: GenerationResumeSnapshot = {
+        resumeState: { threadId: 'thread-resume', runId: 'run-resume' },
+        status: 'running',
+      }
+      const { adapter, connect } = createRunContextCaptureAdapter([])
+      const getItem = vi.fn(() => snapshot)
+      const gen = createGeneration({
+        id: 'no-auto-fire',
+        connection: adapter,
+        persistence: {
+          server: { getItem, setItem: vi.fn(), removeItem: vi.fn() },
+        },
+        initialResumeSnapshot: snapshot,
+      })
+
+      await Promise.resolve()
+
+      expect(connect).not.toHaveBeenCalled()
+      expect(getItem).not.toHaveBeenCalled()
+      expect(gen.isLoading).toBe(false)
+      expect(gen.status).toBe('idle')
+      // The persisted snapshot remains exposed as read-only state.
+      expect(gen.resumeState).toEqual(snapshot.resumeState)
+    })
   })
 
   describe('stop and reset', () => {
@@ -489,7 +548,7 @@ describe('createSummarize', () => {
     const mockResult = {
       id: 'sum-1',
       summary: 'A brief summary',
-      model: 'gpt-4',
+      model: 'gpt-5.5',
       usage: { promptTokens: 1, completionTokens: 1, totalTokens: 2 },
     }
 
@@ -504,7 +563,7 @@ describe('createSummarize', () => {
   })
 
   it('should summarize text using connection', async () => {
-    const mockResult = { summary: 'A brief summary', model: 'gpt-4' }
+    const mockResult = { summary: 'A brief summary', model: 'gpt-5.5' }
     const chunks = createGenerationChunks(mockResult)
     const adapter = createMockConnectionAdapter({ chunks })
 
@@ -538,7 +597,7 @@ describe('createSummarize', () => {
       fetcher: async () => ({
         id: 'sum-1',
         summary: 'A brief summary',
-        model: 'gpt-4',
+        model: 'gpt-5.5',
         usage: { promptTokens: 1, completionTokens: 1, totalTokens: 2 },
       }),
     })
@@ -658,6 +717,30 @@ describe('createGenerateVideo', () => {
     expect(gen.status).toBe('idle')
   })
 
+  it('does not auto-fire a video generation on setup from a persisted running snapshot', async () => {
+    // Regression guard for the removed generation resume surface (video).
+    const { adapter, connect } = createRunContextCaptureAdapter([])
+    const getItem = vi.fn(() => videoResumeSnapshot)
+    const gen = createGenerateVideo({
+      id: 'video-no-auto-fire',
+      connection: adapter,
+      persistence: {
+        server: { getItem, setItem: vi.fn(), removeItem: vi.fn() },
+      },
+      initialResumeSnapshot: videoResumeSnapshot,
+    })
+
+    await Promise.resolve()
+
+    expect(connect).not.toHaveBeenCalled()
+    expect(getItem).not.toHaveBeenCalled()
+    expect(gen.isLoading).toBe(false)
+    expect(gen.status).toBe('idle')
+    // The persisted snapshot remains exposed as read-only state.
+    expect(gen.resumeSnapshot).toEqual(videoResumeSnapshot)
+    expect(gen.resumeState).toEqual(videoResumeSnapshot.resumeState)
+  })
+
   it('should expose generate, stop, reset, and updateBody methods', () => {
     const adapter = createMockConnectionAdapter()
     const gen = createGenerateVideo({ connection: adapter })
diff --git a/packages/ai-utils/src/base64.ts b/packages/ai-utils/src/base64.ts
index d5a45347f..3013c3baf 100644
--- a/packages/ai-utils/src/base64.ts
+++ b/packages/ai-utils/src/base64.ts
@@ -1,11 +1,12 @@
 /**
  * Cross-runtime base64 helpers.
  *
- * Both `arrayBufferToBase64` and `base64ToArrayBuffer` prefer the new native
- * `Uint8Array.toBase64()` / `Uint8Array.fromBase64()` methods (TC39 base64
- * proposal, Stage 3) when available — they are significantly faster and more
- * memory-efficient than the byte-walking fallback. The fallbacks use Node's
- * `Buffer` when present, then `atob`/`btoa` for browser / edge runtimes.
+ * `arrayBufferToBase64`, `base64ToUint8Array`, and `base64ToArrayBuffer`
+ * prefer the new native `Uint8Array.toBase64()` / `Uint8Array.fromBase64()`
+ * methods (TC39 base64 proposal, Stage 3) when available — they are
+ * significantly faster and more memory-efficient than the byte-walking
+ * fallback. The fallbacks use Node's `Buffer` when present, then
+ * `atob`/`btoa` for browser / edge runtimes.
  */
 
 interface Uint8ArrayWithBase64 {
@@ -56,13 +57,13 @@ export function arrayBufferToBase64(buffer: ArrayBuffer): string {
 }
 
 /**
- * Decode a base64 string into an `ArrayBuffer`.
+ * Decode a base64 string into a `Uint8Array`.
  */
-export function base64ToArrayBuffer(base64: string): ArrayBuffer {
+export function base64ToUint8Array(base64: string): Uint8Array {
   // eslint-disable-next-line no-restricted-syntax -- feature-detecting Uint8Array.fromBase64 Stage-3 proposal not yet in lib.es types
   const fast = (Uint8Array as unknown as Uint8ArrayWithBase64).fromBase64
   if (typeof fast === 'function') {
-    return fast(base64).buffer as ArrayBuffer
+    return fast(base64)
   }
 
   if (typeof atob === 'function') {
@@ -71,13 +72,23 @@ export function base64ToArrayBuffer(base64: string): ArrayBuffer {
     for (let i = 0; i < binary.length; i++) {
       bytes[i] = binary.charCodeAt(i)
     }
-    return bytes.buffer
+    return bytes
   }
 
   if (typeof Buffer !== 'undefined' && typeof Buffer.from === 'function') {
-    const buf = Buffer.from(base64, 'base64')
-    return buf.buffer.slice(buf.byteOffset, buf.byteOffset + buf.byteLength)
+    return new Uint8Array(Buffer.from(base64, 'base64'))
   }
 
   throw new Error('No base64 decoder available in this environment.')
 }
+
+/**
+ * Decode a base64 string into an `ArrayBuffer`.
+ */
+export function base64ToArrayBuffer(base64: string): ArrayBuffer {
+  const bytes = base64ToUint8Array(base64)
+  return bytes.buffer.slice(
+    bytes.byteOffset,
+    bytes.byteOffset + bytes.byteLength,
+  ) as ArrayBuffer
+}
diff --git a/packages/ai-utils/src/index.ts b/packages/ai-utils/src/index.ts
index 843d5eb37..619338eee 100644
--- a/packages/ai-utils/src/index.ts
+++ b/packages/ai-utils/src/index.ts
@@ -2,4 +2,8 @@ export { generateId } from './id'
 export { getApiKeyFromEnv } from './env'
 export { transformNullsToUndefined, undoNullWidening } from './transforms'
 export type { NullWideningMap } from './transforms'
-export { arrayBufferToBase64, base64ToArrayBuffer } from './base64'
+export {
+  arrayBufferToBase64,
+  base64ToArrayBuffer,
+  base64ToUint8Array,
+} from './base64'
diff --git a/packages/ai-utils/tests/base64.test.ts b/packages/ai-utils/tests/base64.test.ts
index 53e86af6e..8f768d50a 100644
--- a/packages/ai-utils/tests/base64.test.ts
+++ b/packages/ai-utils/tests/base64.test.ts
@@ -1,5 +1,9 @@
 import { describe, it, expect } from 'vitest'
-import { arrayBufferToBase64, base64ToArrayBuffer } from '../src/base64'
+import {
+  arrayBufferToBase64,
+  base64ToArrayBuffer,
+  base64ToUint8Array,
+} from '../src/base64'
 
 describe('base64 helpers', () => {
   it('round-trips bytes through arrayBufferToBase64 and base64ToArrayBuffer', () => {
@@ -9,13 +13,19 @@ describe('base64 helpers', () => {
     expect(Array.from(decoded)).toEqual(Array.from(bytes))
   })
 
+  it('round-trips bytes through arrayBufferToBase64 and base64ToUint8Array', () => {
+    const bytes = new Uint8Array([0, 1, 2, 3, 254, 255, 128, 64, 32])
+    const base64 = arrayBufferToBase64(bytes.buffer)
+    expect(Array.from(base64ToUint8Array(base64))).toEqual(Array.from(bytes))
+  })
+
   it('encodes a known string to the expected base64', () => {
     const bytes = new TextEncoder().encode('hello world')
     expect(arrayBufferToBase64(bytes.buffer)).toBe('aGVsbG8gd29ybGQ=')
   })
 
   it('decodes a known base64 string to the expected bytes', () => {
-    const decoded = new Uint8Array(base64ToArrayBuffer('aGVsbG8gd29ybGQ='))
+    const decoded = base64ToUint8Array('aGVsbG8gd29ybGQ=')
     expect(new TextDecoder().decode(decoded)).toBe('hello world')
   })
 
@@ -27,7 +37,7 @@ describe('base64 helpers', () => {
     for (let i = 0; i < size; i++) bytes[i] = i & 0xff
 
     const base64 = arrayBufferToBase64(bytes.buffer)
-    const decoded = new Uint8Array(base64ToArrayBuffer(base64))
+    const decoded = base64ToUint8Array(base64)
     expect(decoded.length).toBe(size)
     // Spot-check a few entries rather than comparing the full buffer.
     expect(decoded[0]).toBe(0)
diff --git a/packages/ai-vue/src/types.ts b/packages/ai-vue/src/types.ts
index 60fe898fd..3c824e7df 100644
--- a/packages/ai-vue/src/types.ts
+++ b/packages/ai-vue/src/types.ts
@@ -2,13 +2,16 @@ import type {
   AnyClientTool,
   InferSchemaType,
   ModelMessage,
+  RunAgentResumeItem,
   SchemaInput,
 } from '@tanstack/ai'
 import type {
   AIDevtoolsDisplayOptions,
   ChatClientOptions,
   ChatClientState,
+  ChatPendingInterrupt,
   ChatRequestBody,
+  ChatResumeState,
   ClientContextOptionFromTools,
   ConnectionStatus,
   DistributedOmit,
@@ -68,6 +71,7 @@ export type UseChatOptions<
   | 'onSubscriptionChange'
   | 'onConnectionStatusChange'
   | 'onSessionGeneratingChange'
+  | 'onResumeStateChange'
   | 'context'
   | 'devtools'
 > & {
@@ -150,6 +154,13 @@ interface BaseUseChatReturn<
     approved: boolean
   }) => Promise<void>
 
+  resumeState: DeepReadonly<ShallowRef<ChatResumeState | null>>
+  pendingInterrupts: DeepReadonly<ShallowRef<Array<ChatPendingInterrupt>>>
+  resumeInterrupts: (
+    resume: Array<RunAgentResumeItem>,
+    state?: ChatResumeState,
+  ) => Promise<boolean>
+
   /**
    * Reload the last assistant message
    */
diff --git a/packages/ai-vue/src/use-chat.ts b/packages/ai-vue/src/use-chat.ts
index 31719591d..27060eb46 100644
--- a/packages/ai-vue/src/use-chat.ts
+++ b/packages/ai-vue/src/use-chat.ts
@@ -13,11 +13,14 @@ import type {
   AnyClientTool,
   InferSchemaType,
   ModelMessage,
+  RunAgentResumeItem,
   SchemaInput,
   StreamChunk,
 } from '@tanstack/ai'
 import type {
   ChatClientState,
+  ChatPendingInterrupt,
+  ChatResumeState,
   ConnectionStatus,
   InferredClientContext,
   StructuredOutputPart,
@@ -53,6 +56,12 @@ export function useChat<
   const isSubscribed = shallowRef(false)
   const connectionStatus = shallowRef<ConnectionStatus>('disconnected')
   const sessionGenerating = shallowRef(false)
+  const resumeState = shallowRef<ChatResumeState | null>(
+    options.initialResumeSnapshot?.resumeState ?? null,
+  )
+  const pendingInterrupts = shallowRef<Array<ChatPendingInterrupt>>(
+    options.initialResumeSnapshot?.pendingInterrupts ?? [],
+  )
 
   // Structured-output `partial` / `final` are derived from `messages` —
   // specifically from the structured-output part on the latest assistant
@@ -89,6 +98,9 @@ export function useChat<
     ...(options.persistence !== undefined && {
       persistence: options.persistence,
     }),
+    ...(options.initialResumeSnapshot !== undefined && {
+      initialResumeSnapshot: options.initialResumeSnapshot,
+    }),
     ...(options.body !== undefined && { body: options.body }),
     ...(options.threadId !== undefined && { threadId: options.threadId }),
     ...(options.forwardedProps !== undefined && {
@@ -122,6 +134,7 @@ export function useChat<
     },
     onLoadingChange: (newIsLoading: boolean) => {
       isLoading.value = newIsLoading
+      syncResumeState()
     },
     onStatusChange: (newStatus: ChatClientState) => {
       status.value = newStatus
@@ -138,8 +151,17 @@ export function useChat<
     onSessionGeneratingChange: (isGenerating: boolean) => {
       sessionGenerating.value = isGenerating
     },
+    onResumeStateChange: (nextResumeState, nextPendingInterrupts) => {
+      resumeState.value = nextResumeState
+      pendingInterrupts.value = nextPendingInterrupts
+    },
   })
 
+  function syncResumeState() {
+    resumeState.value = client.getResumeState()
+    pendingInterrupts.value = client.getPendingInterrupts()
+  }
+
   messages.value = client.getMessages()
 
   // Sync body / forwardedProps changes to the client.
@@ -174,6 +196,10 @@ export function useChat<
 
   onMounted(() => {
     client.mountDevtools()
+    // Delivery-durability resume is transparent: the resumable SSE connection
+    // adapter reattaches via the browser's native Last-Event-ID on reconnect.
+    // We only seed interrupt (state) resume from the client here.
+    syncResumeState()
   })
 
   // Cleanup on unmount: stop any in-flight requests
@@ -191,15 +217,27 @@ export function useChat<
   // or mutated options propagate without recreating the client.
 
   const sendMessage = async (content: string | MultimodalContent) => {
-    await client.sendMessage(content)
+    try {
+      await client.sendMessage(content)
+    } finally {
+      syncResumeState()
+    }
   }
 
   const append = async (message: ModelMessage | UIMessage<TTools>) => {
-    await client.append(message)
+    try {
+      await client.append(message)
+    } finally {
+      syncResumeState()
+    }
   }
 
   const reload = async () => {
-    await client.reload()
+    try {
+      await client.reload()
+    } finally {
+      syncResumeState()
+    }
   }
 
   const stop = () => {
@@ -208,6 +246,7 @@ export function useChat<
 
   const clear = () => {
     client.clear()
+    syncResumeState()
   }
 
   const setMessagesManually = (newMessages: Array<UIMessage<TTools>>) => {
@@ -229,6 +268,16 @@ export function useChat<
     approved: boolean
   }) => {
     await client.addToolApprovalResponse(response)
+    syncResumeState()
+  }
+
+  const resumeInterrupts = async (
+    resumeItems: Array<RunAgentResumeItem>,
+    state?: ChatResumeState,
+  ) => {
+    const result = await client.resumeInterrupts(resumeItems, state)
+    syncResumeState()
+    return result
   }
 
   // The "active" structured-output part is the one on the assistant message
@@ -292,6 +341,9 @@ export function useChat<
     clear,
     addToolResult,
     addToolApprovalResponse,
+    resumeState: readonly(resumeState),
+    pendingInterrupts: readonly(pendingInterrupts),
+    resumeInterrupts,
     partial: readonly(partial),
     final: readonly(final),
   } as unknown as UseChatReturn<TTools, TSchema>
diff --git a/packages/ai-vue/src/use-generate-audio.ts b/packages/ai-vue/src/use-generate-audio.ts
index 91c8eb6a0..48fb347d6 100644
--- a/packages/ai-vue/src/use-generate-audio.ts
+++ b/packages/ai-vue/src/use-generate-audio.ts
@@ -1,4 +1,8 @@
 import { useGeneration } from './use-generation'
+import type {
+  UseGenerationOptions,
+  UseGenerationReturn,
+} from './use-generation'
 import type { AudioGenerationResult, StreamChunk } from '@tanstack/ai'
 import type {
   AIDevtoolsDisplayOptions,
@@ -15,7 +19,12 @@ import type { DeepReadonly, ShallowRef } from 'vue'
  *
  * @template TOutput - The output type after optional transform (defaults to AudioGenerationResult)
  */
-export interface UseGenerateAudioOptions<TOutput = AudioGenerationResult> {
+export interface UseGenerateAudioOptions<
+  TOutput = AudioGenerationResult,
+> extends Pick<
+  UseGenerationOptions<AudioGenerateInput, AudioGenerationResult, TOutput>,
+  'persistence' | 'initialResumeSnapshot'
+> {
   /** Connect-based adapter for streaming transport (SSE, HTTP stream, custom) */
   connection?: ConnectConnectionAdapter
   /** Direct async function for audio generation */
@@ -47,7 +56,9 @@ export interface UseGenerateAudioOptions<TOutput = AudioGenerationResult> {
  *
  * @template TOutput - The output type (after optional transform)
  */
-export interface UseGenerateAudioReturn<TOutput = AudioGenerationResult> {
+export interface UseGenerateAudioReturn<
+  TOutput = AudioGenerationResult,
+> extends Omit<UseGenerationReturn<TOutput>, 'generate'> {
   /** Trigger audio generation */
   generate: (input: AudioGenerateInput) => Promise<void>
   /** The generation result containing audio, or null */
@@ -58,10 +69,6 @@ export interface UseGenerateAudioReturn<TOutput = AudioGenerationResult> {
   error: DeepReadonly<ShallowRef<Error | undefined>>
   /** Current state of the generation */
   status: DeepReadonly<ShallowRef<GenerationClientState>>
-  /** Abort the current generation */
-  stop: () => void
-  /** Clear result, error, and return to idle */
-  reset: () => void
 }
 
 /**
@@ -101,19 +108,19 @@ export function useGenerateAudio<TTransformed = void>(
     hookName: 'useGenerateAudio',
     outputKind: 'audio' as const,
   }
-  const { generate, result, isLoading, error, status, stop, reset } =
-    useGeneration<AudioGenerateInput, AudioGenerationResult, TTransformed>({
-      ...options,
-      devtools,
-    })
+  const generation = useGeneration<
+    AudioGenerateInput,
+    AudioGenerationResult,
+    TTransformed
+  >({
+    ...options,
+    devtools,
+  })
 
   return {
-    generate: generate as (input: AudioGenerateInput) => Promise<void>,
-    result,
-    isLoading,
-    error,
-    status,
-    stop,
-    reset,
+    ...generation,
+    generate: generation.generate as (
+      input: AudioGenerateInput,
+    ) => Promise<void>,
   }
 }
diff --git a/packages/ai-vue/src/use-generate-image.ts b/packages/ai-vue/src/use-generate-image.ts
index f80cc2f5c..f40c88767 100644
--- a/packages/ai-vue/src/use-generate-image.ts
+++ b/packages/ai-vue/src/use-generate-image.ts
@@ -1,4 +1,8 @@
 import { useGeneration } from './use-generation'
+import type {
+  UseGenerationOptions,
+  UseGenerationReturn,
+} from './use-generation'
 import type { ImageGenerationResult, StreamChunk } from '@tanstack/ai'
 import type {
   AIDevtoolsDisplayOptions,
@@ -15,7 +19,12 @@ import type { DeepReadonly, ShallowRef } from 'vue'
  *
  * @template TOutput - The output type after optional transform (defaults to ImageGenerationResult)
  */
-export interface UseGenerateImageOptions<TOutput = ImageGenerationResult> {
+export interface UseGenerateImageOptions<
+  TOutput = ImageGenerationResult,
+> extends Pick<
+  UseGenerationOptions<ImageGenerateInput, ImageGenerationResult, TOutput>,
+  'persistence' | 'initialResumeSnapshot'
+> {
   /** Connect-based adapter for streaming transport (SSE, HTTP stream, custom) */
   connection?: ConnectConnectionAdapter
   /** Direct async function for image generation */
@@ -47,7 +56,9 @@ export interface UseGenerateImageOptions<TOutput = ImageGenerationResult> {
  *
  * @template TOutput - The output type (after optional transform)
  */
-export interface UseGenerateImageReturn<TOutput = ImageGenerationResult> {
+export interface UseGenerateImageReturn<
+  TOutput = ImageGenerationResult,
+> extends Omit<UseGenerationReturn<TOutput>, 'generate'> {
   /** Trigger image generation */
   generate: (input: ImageGenerateInput) => Promise<void>
   /** The generation result containing images, or null */
@@ -58,10 +69,6 @@ export interface UseGenerateImageReturn<TOutput = ImageGenerationResult> {
   error: DeepReadonly<ShallowRef<Error | undefined>>
   /** Current state of the generation */
   status: DeepReadonly<ShallowRef<GenerationClientState>>
-  /** Abort the current generation */
-  stop: () => void
-  /** Clear result, error, and return to idle */
-  reset: () => void
 }
 
 /**
@@ -111,19 +118,19 @@ export function useGenerateImage<TTransformed = void>(
     hookName: 'useGenerateImage',
     outputKind: 'image' as const,
   }
-  const { generate, result, isLoading, error, status, stop, reset } =
-    useGeneration<ImageGenerateInput, ImageGenerationResult, TTransformed>({
-      ...options,
-      devtools,
-    })
+  const generation = useGeneration<
+    ImageGenerateInput,
+    ImageGenerationResult,
+    TTransformed
+  >({
+    ...options,
+    devtools,
+  })
 
   return {
-    generate: generate as (input: ImageGenerateInput) => Promise<void>,
-    result,
-    isLoading,
-    error,
-    status,
-    stop,
-    reset,
+    ...generation,
+    generate: generation.generate as (
+      input: ImageGenerateInput,
+    ) => Promise<void>,
   }
 }
diff --git a/packages/ai-vue/src/use-generate-speech.ts b/packages/ai-vue/src/use-generate-speech.ts
index 2302fc766..574d58517 100644
--- a/packages/ai-vue/src/use-generate-speech.ts
+++ b/packages/ai-vue/src/use-generate-speech.ts
@@ -1,4 +1,8 @@
 import { useGeneration } from './use-generation'
+import type {
+  UseGenerationOptions,
+  UseGenerationReturn,
+} from './use-generation'
 import type { StreamChunk, TTSResult } from '@tanstack/ai'
 import type {
   AIDevtoolsDisplayOptions,
@@ -15,7 +19,10 @@ import type { DeepReadonly, ShallowRef } from 'vue'
  *
  * @template TOutput - The output type after optional transform (defaults to TTSResult)
  */
-export interface UseGenerateSpeechOptions<TOutput = TTSResult> {
+export interface UseGenerateSpeechOptions<TOutput = TTSResult> extends Pick<
+  UseGenerationOptions<SpeechGenerateInput, TTSResult, TOutput>,
+  'persistence' | 'initialResumeSnapshot'
+> {
   /** Connect-based adapter for streaming transport (SSE, HTTP stream, custom) */
   connection?: ConnectConnectionAdapter
   /** Direct async function for speech generation */
@@ -47,7 +54,10 @@ export interface UseGenerateSpeechOptions<TOutput = TTSResult> {
  *
  * @template TOutput - The output type (after optional transform)
  */
-export interface UseGenerateSpeechReturn<TOutput = TTSResult> {
+export interface UseGenerateSpeechReturn<TOutput = TTSResult> extends Omit<
+  UseGenerationReturn<TOutput>,
+  'generate'
+> {
   /** Trigger speech generation */
   generate: (input: SpeechGenerateInput) => Promise<void>
   /** The TTS result containing audio data, or null */
@@ -58,10 +68,6 @@ export interface UseGenerateSpeechReturn<TOutput = TTSResult> {
   error: DeepReadonly<ShallowRef<Error | undefined>>
   /** Current state of the generation */
   status: DeepReadonly<ShallowRef<GenerationClientState>>
-  /** Abort the current generation */
-  stop: () => void
-  /** Clear result, error, and return to idle */
-  reset: () => void
 }
 
 /**
@@ -105,19 +111,19 @@ export function useGenerateSpeech<TTransformed = void>(
     hookName: 'useGenerateSpeech',
     outputKind: 'audio' as const,
   }
-  const { generate, result, isLoading, error, status, stop, reset } =
-    useGeneration<SpeechGenerateInput, TTSResult, TTransformed>({
-      ...options,
-      devtools,
-    })
+  const generation = useGeneration<
+    SpeechGenerateInput,
+    TTSResult,
+    TTransformed
+  >({
+    ...options,
+    devtools,
+  })
 
   return {
-    generate: generate as (input: SpeechGenerateInput) => Promise<void>,
-    result,
-    isLoading,
-    error,
-    status,
-    stop,
-    reset,
+    ...generation,
+    generate: generation.generate as (
+      input: SpeechGenerateInput,
+    ) => Promise<void>,
   }
 }
diff --git a/packages/ai-vue/src/use-generate-video.ts b/packages/ai-vue/src/use-generate-video.ts
index 644558508..823ab8a73 100644
--- a/packages/ai-vue/src/use-generate-video.ts
+++ b/packages/ai-vue/src/use-generate-video.ts
@@ -14,11 +14,16 @@ import type {
   ConnectConnectionAdapter,
   GenerationClientState,
   GenerationFetcher,
+  GenerationPendingArtifact,
+  GenerationPersistenceOptions,
+  GenerationResumeSnapshot,
+  GenerationResumeState,
   InferGenerationOutputFromReturn,
   VideoGenerateInput,
   VideoGenerateResult,
   VideoStatusInfo,
 } from '@tanstack/ai-client'
+import type { PersistedArtifactRef } from '@tanstack/ai/client'
 import type { DeepReadonly, ShallowRef } from 'vue'
 
 /**
@@ -37,6 +42,10 @@ export interface UseGenerateVideoOptions<TOutput = VideoGenerateResult> {
   body?: Record<string, any>
   /** Display options for TanStack AI Devtools. */
   devtools?: AIDevtoolsDisplayOptions
+  /** Server-side lightweight generation state persistence. */
+  persistence?: GenerationPersistenceOptions
+  /** Initial lightweight resume snapshot restored by the app (read-only state). */
+  initialResumeSnapshot?: GenerationResumeSnapshot
   /**
    * Callback when video generation completes. Can optionally return a transformed value.
    *
@@ -81,6 +90,14 @@ export interface UseGenerateVideoReturn<TOutput = VideoGenerateResult> {
   stop: () => void
   /** Clear all state and return to idle */
   reset: () => void
+  /** Lightweight generation resume snapshot, if one is available */
+  resumeSnapshot: DeepReadonly<ShallowRef<GenerationResumeSnapshot | undefined>>
+  /** Observed run/cursor metadata from the snapshot (read-only state) */
+  resumeState: DeepReadonly<ShallowRef<GenerationResumeState | null>>
+  /** Pending persisted artifact references observed during generation/replay */
+  pendingArtifacts: DeepReadonly<ShallowRef<Array<GenerationPendingArtifact>>>
+  /** Final persisted artifact references observed from a replayed result */
+  resultArtifacts: DeepReadonly<ShallowRef<Array<PersistedArtifactRef>>>
 }
 
 /**
@@ -137,6 +154,29 @@ export function useGenerateVideo<TTransformed = void>(
   const isLoading = shallowRef(false)
   const error = shallowRef<Error | undefined>(undefined)
   const status = shallowRef<GenerationClientState>('idle')
+  const resumeSnapshot = shallowRef<GenerationResumeSnapshot | undefined>(
+    options.initialResumeSnapshot,
+  )
+  const resumeState = shallowRef<GenerationResumeState | null>(
+    options.initialResumeSnapshot?.resumeState ?? null,
+  )
+  const pendingArtifacts = shallowRef<Array<GenerationPendingArtifact>>(
+    options.initialResumeSnapshot?.pendingArtifacts ?? [],
+  )
+  const resultArtifacts = shallowRef<Array<PersistedArtifactRef>>(
+    options.initialResumeSnapshot?.result?.artifacts ?? [],
+  )
+  let disposed = false
+
+  const setResumeSnapshotState = (
+    snapshot: GenerationResumeSnapshot | undefined,
+  ) => {
+    if (disposed) return
+    resumeSnapshot.value = snapshot
+    resumeState.value = snapshot?.resumeState ?? null
+    pendingArtifacts.value = snapshot?.pendingArtifacts ?? []
+    resultArtifacts.value = snapshot?.result?.artifacts ?? []
+  }
 
   // Conditional spread on `body`: `VideoGenerationClientOptions.body` is a
   // strict optional and under EOPT we must omit the key when absent rather
@@ -144,6 +184,12 @@ export function useGenerateVideo<TTransformed = void>(
   const baseOptions = {
     id: clientId,
     body: options.body,
+    ...(options.persistence !== undefined && {
+      persistence: options.persistence,
+    }),
+    ...(options.initialResumeSnapshot !== undefined && {
+      initialResumeSnapshot: options.initialResumeSnapshot,
+    }),
     devtoolsBridgeFactory: createVideoDevtoolsBridge,
     devtools: {
       ...options.devtools,
@@ -157,29 +203,46 @@ export function useGenerateVideo<TTransformed = void>(
     onResult: ((r: VideoGenerateResult) => options.onResult?.(r)) as (
       result: VideoGenerateResult,
     ) => TOutput | null | void,
-    onError: (e: Error) => options.onError?.(e),
-    onProgress: (p: number, m?: string) => options.onProgress?.(p, m),
-    onChunk: (c: StreamChunk) => options.onChunk?.(c),
-    onJobCreated: (id: string) => options.onJobCreated?.(id),
-    onStatusUpdate: (s: VideoStatusInfo) => options.onStatusUpdate?.(s),
+    onError: (e: Error) => {
+      if (!disposed) options.onError?.(e)
+    },
+    onProgress: (p: number, m?: string) => {
+      if (!disposed) options.onProgress?.(p, m)
+    },
+    onChunk: (c: StreamChunk) => {
+      if (!disposed) options.onChunk?.(c)
+    },
+    onJobCreated: (id: string) => {
+      if (!disposed) options.onJobCreated?.(id)
+    },
+    onStatusUpdate: (s: VideoStatusInfo) => {
+      if (!disposed) options.onStatusUpdate?.(s)
+    },
     onResultChange: (r: TOutput | null) => {
+      if (disposed) return
       result.value = r
     },
     onLoadingChange: (l: boolean) => {
+      if (disposed) return
       isLoading.value = l
     },
     onErrorChange: (e: Error | undefined) => {
+      if (disposed) return
       error.value = e
     },
     onStatusChange: (s: GenerationClientState) => {
+      if (disposed) return
       status.value = s
     },
     onJobIdChange: (id: string | null) => {
+      if (disposed) return
       jobId.value = id
     },
     onVideoStatusChange: (s: VideoStatusInfo | null) => {
+      if (disposed) return
       videoStatus.value = s
     },
+    onResumeSnapshotChange: setResumeSnapshotState,
   }
 
   let client: VideoGenerationClient<TOutput>
@@ -212,12 +275,15 @@ export function useGenerateVideo<TTransformed = void>(
     },
   )
 
+  // Mount devtools only. Generation runs are never auto-started on mount —
+  // persisted state is read-only for display.
   onMounted(() => {
     client.mountDevtools()
   })
 
   // Cleanup on scope dispose: stop any in-flight requests and unregister devtools
   onScopeDispose(() => {
+    disposed = true
     client.dispose()
   })
 
@@ -247,5 +313,9 @@ export function useGenerateVideo<TTransformed = void>(
     status: readonly(status),
     stop,
     reset,
+    resumeSnapshot: readonly(resumeSnapshot),
+    resumeState: readonly(resumeState),
+    pendingArtifacts: readonly(pendingArtifacts),
+    resultArtifacts: readonly(resultArtifacts),
   }
 }
diff --git a/packages/ai-vue/src/use-generation.ts b/packages/ai-vue/src/use-generation.ts
index 596f14e97..6c6005d66 100644
--- a/packages/ai-vue/src/use-generation.ts
+++ b/packages/ai-vue/src/use-generation.ts
@@ -15,8 +15,13 @@ import type {
   GenerationClientOptions,
   GenerationClientState,
   GenerationFetcher,
+  GenerationPendingArtifact,
+  GenerationPersistenceOptions,
+  GenerationResumeSnapshot,
+  GenerationResumeState,
   InferGenerationOutputFromReturn,
 } from '@tanstack/ai-client'
+import type { PersistedArtifactRef } from '@tanstack/ai/client'
 import type { DeepReadonly, ShallowRef } from 'vue'
 
 /**
@@ -39,6 +44,10 @@ export interface UseGenerationOptions<TInput, TResult, TOutput = TResult> {
   body?: Record<string, any>
   /** Display options for TanStack AI Devtools. */
   devtools?: AIDevtoolsDisplayOptions
+  /** Server-side lightweight generation state persistence. */
+  persistence?: GenerationPersistenceOptions
+  /** Initial lightweight resume snapshot restored by the app (read-only state). */
+  initialResumeSnapshot?: GenerationResumeSnapshot
   /**
    * Callback when a result is received. Can optionally return a transformed value.
    *
@@ -75,6 +84,14 @@ export interface UseGenerationReturn<TOutput> {
   stop: () => void
   /** Clear result, error, and return to idle */
   reset: () => void
+  /** Lightweight generation resume snapshot, if one is available */
+  resumeSnapshot: DeepReadonly<ShallowRef<GenerationResumeSnapshot | undefined>>
+  /** Observed run/cursor metadata from the snapshot (read-only state) */
+  resumeState: DeepReadonly<ShallowRef<GenerationResumeState | null>>
+  /** Pending persisted artifact references observed during generation/replay */
+  pendingArtifacts: DeepReadonly<ShallowRef<Array<GenerationPendingArtifact>>>
+  /** Final persisted artifact references observed from a replayed result */
+  resultArtifacts: DeepReadonly<ShallowRef<Array<PersistedArtifactRef>>>
 }
 
 /**
@@ -122,6 +139,29 @@ export function useGeneration<
   const isLoading = shallowRef(false)
   const error = shallowRef<Error | undefined>(undefined)
   const status = shallowRef<GenerationClientState>('idle')
+  const resumeSnapshot = shallowRef<GenerationResumeSnapshot | undefined>(
+    options.initialResumeSnapshot,
+  )
+  const resumeState = shallowRef<GenerationResumeState | null>(
+    options.initialResumeSnapshot?.resumeState ?? null,
+  )
+  const pendingArtifacts = shallowRef<Array<GenerationPendingArtifact>>(
+    options.initialResumeSnapshot?.pendingArtifacts ?? [],
+  )
+  const resultArtifacts = shallowRef<Array<PersistedArtifactRef>>(
+    options.initialResumeSnapshot?.result?.artifacts ?? [],
+  )
+  let disposed = false
+
+  const setResumeSnapshotState = (
+    snapshot: GenerationResumeSnapshot | undefined,
+  ) => {
+    if (disposed) return
+    resumeSnapshot.value = snapshot
+    resumeState.value = snapshot?.resumeState ?? null
+    pendingArtifacts.value = snapshot?.pendingArtifacts ?? []
+    resultArtifacts.value = snapshot?.result?.artifacts ?? []
+  }
 
   // Conditional spread on `body`: `GenerationClientOptions.body` is a strict
   // optional (`body?: Record<string, any>`), and under EOPT we must omit the
@@ -129,6 +169,12 @@ export function useGeneration<
   const clientOptions: GenerationClientOptions<TInput, TResult, TOutput> = {
     id: clientId,
     body: options.body,
+    ...(options.persistence !== undefined && {
+      persistence: options.persistence,
+    }),
+    ...(options.initialResumeSnapshot !== undefined && {
+      initialResumeSnapshot: options.initialResumeSnapshot,
+    }),
     devtoolsBridgeFactory: createGenerationDevtoolsBridge,
     devtools: {
       ...options.devtools,
@@ -141,21 +187,32 @@ export function useGeneration<
     onResult: ((r: TResult) => options.onResult?.(r)) as (
       result: TResult,
     ) => TOutput | null | void,
-    onError: (e: Error) => options.onError?.(e),
-    onProgress: (p: number, m?: string) => options.onProgress?.(p, m),
-    onChunk: (c: StreamChunk) => options.onChunk?.(c),
+    onError: (e: Error) => {
+      if (!disposed) options.onError?.(e)
+    },
+    onProgress: (p: number, m?: string) => {
+      if (!disposed) options.onProgress?.(p, m)
+    },
+    onChunk: (c: StreamChunk) => {
+      if (!disposed) options.onChunk?.(c)
+    },
     onResultChange: (r: TOutput | null) => {
+      if (disposed) return
       result.value = r
     },
     onLoadingChange: (l: boolean) => {
+      if (disposed) return
       isLoading.value = l
     },
     onErrorChange: (e: Error | undefined) => {
+      if (disposed) return
       error.value = e
     },
     onStatusChange: (s: GenerationClientState) => {
+      if (disposed) return
       status.value = s
     },
+    onResumeSnapshotChange: setResumeSnapshotState,
   }
 
   let client: GenerationClient<TInput, TResult, TOutput>
@@ -188,12 +245,15 @@ export function useGeneration<
     },
   )
 
+  // Mount devtools only. Generation runs are never auto-started on mount —
+  // persisted state is read-only for display.
   onMounted(() => {
     client.mountDevtools()
   })
 
   // Cleanup on scope dispose: stop any in-flight requests and unregister devtools
   onScopeDispose(() => {
+    disposed = true
     client.dispose()
   })
 
@@ -221,5 +281,9 @@ export function useGeneration<
     status: readonly(status),
     stop,
     reset,
+    resumeSnapshot: readonly(resumeSnapshot),
+    resumeState: readonly(resumeState),
+    pendingArtifacts: readonly(pendingArtifacts),
+    resultArtifacts: readonly(resultArtifacts),
   }
 }
diff --git a/packages/ai-vue/src/use-summarize.ts b/packages/ai-vue/src/use-summarize.ts
index 7297c5277..e49a5a1f2 100644
--- a/packages/ai-vue/src/use-summarize.ts
+++ b/packages/ai-vue/src/use-summarize.ts
@@ -1,4 +1,8 @@
 import { useGeneration } from './use-generation'
+import type {
+  UseGenerationOptions,
+  UseGenerationReturn,
+} from './use-generation'
 import type { StreamChunk, SummarizationResult } from '@tanstack/ai'
 import type {
   AIDevtoolsDisplayOptions,
@@ -15,7 +19,12 @@ import type { DeepReadonly, ShallowRef } from 'vue'
  *
  * @template TOutput - The output type after optional transform (defaults to SummarizationResult)
  */
-export interface UseSummarizeOptions<TOutput = SummarizationResult> {
+export interface UseSummarizeOptions<
+  TOutput = SummarizationResult,
+> extends Pick<
+  UseGenerationOptions<SummarizeGenerateInput, SummarizationResult, TOutput>,
+  'persistence' | 'initialResumeSnapshot'
+> {
   /** Connect-based adapter for streaming transport (SSE, HTTP stream, custom) */
   connection?: ConnectConnectionAdapter
   /** Direct async function for summarization */
@@ -47,7 +56,10 @@ export interface UseSummarizeOptions<TOutput = SummarizationResult> {
  *
  * @template TOutput - The output type (after optional transform)
  */
-export interface UseSummarizeReturn<TOutput = SummarizationResult> {
+export interface UseSummarizeReturn<TOutput = SummarizationResult> extends Omit<
+  UseGenerationReturn<TOutput>,
+  'generate'
+> {
   /** Trigger summarization */
   generate: (input: SummarizeGenerateInput) => Promise<void>
   /** The summarization result, or null */
@@ -58,10 +70,6 @@ export interface UseSummarizeReturn<TOutput = SummarizationResult> {
   error: DeepReadonly<ShallowRef<Error | undefined>>
   /** Current state of the generation */
   status: DeepReadonly<ShallowRef<GenerationClientState>>
-  /** Abort the current summarization */
-  stop: () => void
-  /** Clear result, error, and return to idle */
-  reset: () => void
 }
 
 /**
@@ -106,19 +114,19 @@ export function useSummarize<TTransformed = void>(
     hookName: 'useSummarize',
     outputKind: 'text' as const,
   }
-  const { generate, result, isLoading, error, status, stop, reset } =
-    useGeneration<SummarizeGenerateInput, SummarizationResult, TTransformed>({
-      ...options,
-      devtools,
-    })
+  const generation = useGeneration<
+    SummarizeGenerateInput,
+    SummarizationResult,
+    TTransformed
+  >({
+    ...options,
+    devtools,
+  })
 
   return {
-    generate: generate as (input: SummarizeGenerateInput) => Promise<void>,
-    result,
-    isLoading,
-    error,
-    status,
-    stop,
-    reset,
+    ...generation,
+    generate: generation.generate as (
+      input: SummarizeGenerateInput,
+    ) => Promise<void>,
   }
 }
diff --git a/packages/ai-vue/src/use-transcription.ts b/packages/ai-vue/src/use-transcription.ts
index 26e42156c..69410e039 100644
--- a/packages/ai-vue/src/use-transcription.ts
+++ b/packages/ai-vue/src/use-transcription.ts
@@ -1,4 +1,8 @@
 import { useGeneration } from './use-generation'
+import type {
+  UseGenerationOptions,
+  UseGenerationReturn,
+} from './use-generation'
 import type { StreamChunk, TranscriptionResult } from '@tanstack/ai'
 import type {
   AIDevtoolsDisplayOptions,
@@ -15,7 +19,16 @@ import type { DeepReadonly, ShallowRef } from 'vue'
  *
  * @template TOutput - The output type after optional transform (defaults to TranscriptionResult)
  */
-export interface UseTranscriptionOptions<TOutput = TranscriptionResult> {
+export interface UseTranscriptionOptions<
+  TOutput = TranscriptionResult,
+> extends Pick<
+  UseGenerationOptions<
+    TranscriptionGenerateInput,
+    TranscriptionResult,
+    TOutput
+  >,
+  'persistence' | 'initialResumeSnapshot'
+> {
   /** Connect-based adapter for streaming transport (SSE, HTTP stream, custom) */
   connection?: ConnectConnectionAdapter
   /** Direct async function for transcription */
@@ -47,7 +60,9 @@ export interface UseTranscriptionOptions<TOutput = TranscriptionResult> {
  *
  * @template TOutput - The output type (after optional transform)
  */
-export interface UseTranscriptionReturn<TOutput = TranscriptionResult> {
+export interface UseTranscriptionReturn<
+  TOutput = TranscriptionResult,
+> extends Omit<UseGenerationReturn<TOutput>, 'generate'> {
   /** Trigger transcription */
   generate: (input: TranscriptionGenerateInput) => Promise<void>
   /** The transcription result, or null */
@@ -58,10 +73,6 @@ export interface UseTranscriptionReturn<TOutput = TranscriptionResult> {
   error: DeepReadonly<ShallowRef<Error | undefined>>
   /** Current state of the generation */
   status: DeepReadonly<ShallowRef<GenerationClientState>>
-  /** Abort the current transcription */
-  stop: () => void
-  /** Clear result, error, and return to idle */
-  reset: () => void
 }
 
 /**
@@ -111,20 +122,16 @@ export function useTranscription<TTransformed = void>(
     hookName: 'useTranscription',
     outputKind: 'text' as const,
   }
-  const { generate, result, isLoading, error, status, stop, reset } =
-    useGeneration<
-      TranscriptionGenerateInput,
-      TranscriptionResult,
-      TTransformed
-    >({ ...options, devtools })
+  const generation = useGeneration<
+    TranscriptionGenerateInput,
+    TranscriptionResult,
+    TTransformed
+  >({ ...options, devtools })
 
   return {
-    generate: generate as (input: TranscriptionGenerateInput) => Promise<void>,
-    result,
-    isLoading,
-    error,
-    status,
-    stop,
-    reset,
+    ...generation,
+    generate: generation.generate as (
+      input: TranscriptionGenerateInput,
+    ) => Promise<void>,
   }
 }
diff --git a/packages/ai-vue/tests/use-generation.test.ts b/packages/ai-vue/tests/use-generation.test.ts
index 21b40eafe..a1cbe1739 100644
--- a/packages/ai-vue/tests/use-generation.test.ts
+++ b/packages/ai-vue/tests/use-generation.test.ts
@@ -10,6 +10,11 @@ import { useSummarize } from '../src/use-summarize'
 import { useGenerateVideo } from '../src/use-generate-video'
 import { createMockConnectionAdapter } from './test-utils'
 import type { StreamChunk, TTSResult, TranscriptionResult } from '@tanstack/ai'
+import type {
+  ConnectConnectionAdapter,
+  GenerationResumeSnapshot,
+  RunAgentInputContext,
+} from '@tanstack/ai-client'
 import type { DeepReadonly } from 'vue'
 
 // Helper to create generation stream chunks
@@ -62,6 +67,60 @@ function createVideoChunks(jobId: string, url: string): Array<StreamChunk> {
   ] as unknown as Array<StreamChunk>
 }
 
+const videoResumeSnapshot: GenerationResumeSnapshot = {
+  resumeState: {
+    threadId: 'thread-resume',
+    runId: 'run-resume',
+  },
+  status: 'running',
+}
+
+function createReplayVideoChunks(): Array<StreamChunk> {
+  return [
+    {
+      type: 'RUN_STARTED',
+      runId: 'run-resume',
+      threadId: 'thread-resume',
+      timestamp: Date.now(),
+    },
+    {
+      type: 'CUSTOM',
+      name: 'generation:result',
+      value: {
+        jobId: 'job-replay',
+        status: 'completed',
+        url: 'https://example.com/video.mp4',
+      },
+      timestamp: Date.now(),
+    },
+    {
+      type: 'RUN_FINISHED',
+      runId: 'run-resume',
+      threadId: 'thread-resume',
+      timestamp: Date.now(),
+    },
+  ] as unknown as Array<StreamChunk>
+}
+
+function createRunContextCaptureAdapter(chunks: Array<StreamChunk>): {
+  adapter: ConnectConnectionAdapter
+  connect: ReturnType<typeof vi.fn>
+  runContexts: Array<RunAgentInputContext | undefined>
+} {
+  const runContexts: Array<RunAgentInputContext | undefined> = []
+  const connect = vi.fn()
+  const adapter: ConnectConnectionAdapter = {
+    async *connect(_messages, _data, _signal, runContext) {
+      connect(runContext)
+      runContexts.push(runContext)
+      for (const chunk of chunks) {
+        yield chunk
+      }
+    },
+  }
+  return { adapter, connect, runContexts }
+}
+
 // Helper to create error stream chunks
 function createErrorChunks(message: string): Array<StreamChunk> {
   return [
@@ -187,6 +246,38 @@ describe('useGeneration', () => {
       expect(result.status.value).toBe('error')
       expect(result.error.value?.message).toBe('Generation failed')
     })
+
+    it('does not auto-fire a generation on mount from a persisted running snapshot', async () => {
+      // Regression guard for the removed generation resume surface.
+      const snapshot: GenerationResumeSnapshot = {
+        resumeState: { threadId: 'thread-resume', runId: 'run-resume' },
+        status: 'running',
+      }
+      const { adapter, connect } = createRunContextCaptureAdapter(
+        createGenerationChunks({ id: '1' }),
+      )
+      const getItem = vi.fn(() => snapshot)
+      const { result } = renderHook(() =>
+        useGeneration({
+          id: 'no-auto-fire',
+          connection: adapter,
+          persistence: {
+            server: { getItem, setItem: vi.fn(), removeItem: vi.fn() },
+          },
+          initialResumeSnapshot: snapshot,
+        }),
+      )
+
+      await flushPromises()
+      await nextTick()
+
+      expect(connect).not.toHaveBeenCalled()
+      expect(getItem).not.toHaveBeenCalled()
+      expect(result.isLoading.value).toBe(false)
+      expect(result.status.value).toBe('idle')
+      // The persisted snapshot remains exposed as read-only state.
+      expect(result.resumeState.value).toEqual(snapshot.resumeState)
+    })
   })
 
   describe('stop and reset', () => {
@@ -586,7 +677,7 @@ describe('useSummarize', () => {
   it('should summarize text using fetcher', async () => {
     const mockResult = {
       summary: 'A brief summary',
-      model: 'gpt-4',
+      model: 'gpt-5.5',
     }
 
     const { result } = renderHook(() =>
@@ -604,7 +695,7 @@ describe('useSummarize', () => {
   })
 
   it('should summarize text using connection', async () => {
-    const mockResult = { summary: 'A brief summary', model: 'gpt-4' }
+    const mockResult = { summary: 'A brief summary', model: 'gpt-5.5' }
     const chunks = createGenerationChunks(mockResult)
     const adapter = createMockConnectionAdapter({ chunks })
 
@@ -761,6 +852,35 @@ describe('useGenerateVideo', () => {
     expect(result.status.value).toBe('idle')
   })
 
+  it('does not auto-fire a video generation on mount from a persisted running snapshot', async () => {
+    // Regression guard for the removed generation resume surface (video).
+    const { adapter, connect } = createRunContextCaptureAdapter(
+      createReplayVideoChunks(),
+    )
+    const getItem = vi.fn(() => videoResumeSnapshot)
+    const { result } = renderHook(() =>
+      useGenerateVideo({
+        id: 'video-no-auto-fire',
+        connection: adapter,
+        persistence: {
+          server: { getItem, setItem: vi.fn(), removeItem: vi.fn() },
+        },
+        initialResumeSnapshot: videoResumeSnapshot,
+      }),
+    )
+
+    await flushPromises()
+    await nextTick()
+
+    expect(connect).not.toHaveBeenCalled()
+    expect(getItem).not.toHaveBeenCalled()
+    expect(result.isLoading.value).toBe(false)
+    expect(result.status.value).toBe('idle')
+    // The persisted snapshot remains exposed as read-only state.
+    expect(result.resumeSnapshot.value).toEqual(videoResumeSnapshot)
+    expect(result.resumeState.value).toEqual(videoResumeSnapshot.resumeState)
+  })
+
   it('should require either connection or fetcher', () => {
     expect(() => {
       renderHook(() => useGenerateVideo({} as any))
diff --git a/packages/ai/package.json b/packages/ai/package.json
index a1dcf9a97..f88be6ae6 100644
--- a/packages/ai/package.json
+++ b/packages/ai/package.json
@@ -85,7 +85,7 @@
     "tanstack-intent"
   ],
   "dependencies": {
-    "@ag-ui/core": "^0.0.52",
+    "@ag-ui/core": "^0.0.57",
     "@standard-schema/spec": "^1.1.0",
     "@tanstack/ai-event-client": "workspace:*",
     "@tanstack/ai-utils": "workspace:*",
diff --git a/packages/ai/skills/ai-core/persistence/SKILL.md b/packages/ai/skills/ai-core/persistence/SKILL.md
new file mode 100644
index 000000000..245f1e0ee
--- /dev/null
+++ b/packages/ai/skills/ai-core/persistence/SKILL.md
@@ -0,0 +1,149 @@
+---
+name: ai-core/persistence
+description: >
+  Durable STATE for chat() via withChatPersistence middleware and AIPersistence;
+  media generation via withGenerationPersistence. Persists thread messages, run
+  records, interrupts, metadata, locks, and artifacts/blobs through optional
+  feature-validated stores. Interrupts resume with RunAgentInput.resume[].
+  Delivery durability (replaying a disconnected/reloaded stream) is a separate
+  TRANSPORT concern, not part of this middleware. Backends: memoryPersistence,
+  drizzlePersistence/sqlPersistence, prismaPersistence.
+type: sub-skill
+library: tanstack-ai
+library_version: '0.30.0'
+sources:
+  - 'TanStack/ai:docs/persistence/overview.md'
+---
+
+# Persistence (state durability)
+
+> **Dependency note:** This skill builds on ai-core and ai-core/middleware. Read those first.
+
+## Core rules
+
+- Persistence middleware persists **state only**: thread messages, run records,
+  interrupts, metadata, locks, and generation artifacts/blobs. It never mutates
+  the chunk stream and stamps **no** cursor. A `chat()` with no persistence
+  middleware produces byte-identical chunks.
+- **Delivery durability** (a client disconnects/reloads and still receives the
+  full ordered stream) is a **transport-layer** concern, handled by a pluggable
+  `StreamDurability` sink on the transport helpers — NOT by this middleware.
+  There is no in-band `cursor` and no `chat({ cursor })` replay. Wire it by
+  passing `durability` to
+  `toServerSentEventsResponse(stream, { durability: { adapter } })`
+  (or `toHttpResponse`): `memoryStream(request)` (process-local, dev/test) or
+  `durableStream(request, { server })` from `@tanstack/ai-durable-stream`
+  (durable-streams protocol, production). Each SSE event is tagged
+  `id: <runId@seq>`; native `EventSource` resumes via `Last-Event-ID` with zero
+  client cursor code, and `fetchServerSentEvents(...).joinRun(runId)` attaches a
+  second tab from the start (`?offset=-1`). Ceiling: replays what was PRODUCED,
+  not an interrupted completion — keep the producer alive past the socket
+  (`waitUntil`/durable object/queue). See `docs/persistence/delivery-durability.md`.
+- The primary interface is `AIPersistence`; use `defineAIPersistence(...)` for
+  custom stores. `ChatPersistence` / `defineChatPersistence` are deprecated
+  compatibility aliases only.
+- Use **`withChatPersistence(persistence, { features? })`** for `chat()`:
+  `setup` (provide capabilities), `onConfig` (load+merge thread messages,
+  server-authoritative; validate + apply pending interrupt resumes),
+  `onChunk` (interrupt boundary side-effects only — create interrupt records,
+  mark the run interrupted, snapshot messages), and `onFinish`/`onError`/`onAbort`
+  (run status + usage + transcript save).
+- Use **`withGenerationPersistence(persistence, { features? })`** for media
+  generation (`generateImage`, `generateAudio`, TTS, video, transcription):
+  run status updates and optional artifact/blob persistence.
+- Pending user-actionable interrupts are represented by
+  `RUN_FINISHED.outcome.type === 'interrupt'`, persisted in `InterruptStore`,
+  and resumed with AG-UI `RunAgentInput.resume[]`. Normal new input on the same
+  thread is blocked by default while pending interrupts exist. Interrupt resume
+  is STATE (approvals / client-tool results), not delivery.
+
+## Server — state-persisted endpoint
+
+```ts
+import { chat, toServerSentEventsResponse } from '@tanstack/ai'
+import { anthropicText } from '@tanstack/ai-anthropic'
+import { withChatPersistence } from '@tanstack/ai-persistence'
+import { sqlPersistence } from '@tanstack/ai-persistence-drizzle'
+
+const persistence = sqlPersistence({
+  dialect: 'sqlite',
+  url: 'file:./chat.db',
+  migrate: true,
+})
+
+export async function POST(request: Request) {
+  const { messages, threadId, runId, resume } = await request.json()
+  const stream = chat({
+    threadId,
+    runId,
+    resume,
+    adapter: anthropicText('claude-sonnet-4-6'),
+    messages,
+    middleware: [withChatPersistence(persistence)],
+  })
+  return toServerSentEventsResponse(stream)
+}
+```
+
+## Client — resolving interrupts
+
+For pending interrupts, send resume entries matching every pending interrupt
+with `resumeInterrupts(...)`:
+
+```ts
+await chat.resumeInterrupts([
+  {
+    interruptId: 'interrupt-1',
+    status: 'resolved',
+    payload: { approved: true },
+  },
+])
+```
+
+`chat.getResumeState()` returns `{ threadId, runId }` for the interrupted run so
+the interrupt resume can be reissued across a full page reload (persist it via
+`persistence: { server }`).
+
+## Stores and features
+
+`AIPersistence` stores are optional, but feature validation is fail-loud:
+
+| Feature      | Required stores                 |
+| ------------ | ------------------------------- |
+| `messages`   | `messages`                      |
+| `interrupts` | `runs`, `interrupts`            |
+| `metadata`   | `metadata`                      |
+| `locks`      | `locks`                         |
+| `artifacts`  | `artifacts`                     |
+| `blobs`      | `blobs` (pair with `artifacts`) |
+
+## Backends
+
+```ts
+import { memoryPersistence } from '@tanstack/ai-persistence' // tests/prototypes
+import {
+  sqlPersistence, // batteries: builds the db + runs bundled migrations
+  drizzlePersistence, // BYO drizzle db
+} from '@tanstack/ai-persistence-drizzle'
+import { prismaPersistence } from '@tanstack/ai-persistence-prisma' // BYO PrismaClient
+```
+
+Each ORM owns its own migrations (drizzle-kit / prisma migrate). The state
+tables are `messages`, `runs`, `interrupts`, `metadata`, `artifacts`, `blobs`.
+
+## Sandboxes
+
+Place `withChatPersistence(...)` before `withSandbox(...)` to make sandbox
+resume and ensure-locking durable across processes. `withSandbox(...)` reads
+the configured persistence metadata store for sandbox records and uses the
+shared `locks` capability from `@tanstack/ai` when `withChatPersistence(...)`
+provides it.
+
+## Gotchas
+
+- `ModelMessage` has no id; message reconciliation is whole-transcript and
+  server-authoritative (client messages win when present, else stored history).
+- The chat middleware never mutates the stream — do not expect a cursor on
+  persisted chunks. Delivery replay lives on the transport layer.
+- Approval custom events are legacy projection. Primary actionable waits are
+  `RUN_FINISHED.outcome.type === 'interrupt'`.
diff --git a/packages/ai/skills/ai-core/tool-calling/SKILL.md b/packages/ai/skills/ai-core/tool-calling/SKILL.md
index 4837705ab..6b9ad9324 100644
--- a/packages/ai/skills/ai-core/tool-calling/SKILL.md
+++ b/packages/ai/skills/ai-core/tool-calling/SKILL.md
@@ -239,9 +239,12 @@ function ChatPage() {
 
 ### Pattern 3: Tool with Approval Flow
 
-Set `needsApproval: true` in the definition. Execution pauses until the client
-calls `addToolApprovalResponse()`. The part has `state: "approval-requested"`
-and an `approval` object with an `id`.
+Set `needsApproval: true` in the definition. Execution pauses with
+`RUN_FINISHED.outcome.type === 'interrupt'`; legacy approval UI still sees a
+tool-call part with `state: "approval-requested"` and an `approval` object with
+an `id`. The primary resume path is AG-UI `RunAgentInput.resume[]` via
+`resumeInterrupts(...)`. `addToolApprovalResponse()` remains the compatibility
+UI helper and forwards matching pending approval interrupts when present.
 
 ```typescript
 import { toolDefinition } from '@tanstack/ai'
@@ -271,7 +274,12 @@ Client -- render approval UI and respond:
 import { useChat, fetchServerSentEvents } from "@tanstack/ai-react";
 
 function ChatPage() {
-  const { messages, addToolApprovalResponse } = useChat({
+  const {
+    messages,
+    pendingInterrupts,
+    resumeInterrupts,
+    addToolApprovalResponse,
+  } = useChat({
     connection: fetchServerSentEvents("/api/chat"),
   });
 
@@ -322,6 +330,19 @@ function ChatPage() {
 }
 ```
 
+For new interrupt-aware UIs, render `pendingInterrupts` and resume them
+directly:
+
+```typescript
+await resumeInterrupts([
+  {
+    interruptId: pendingInterrupts[0].id,
+    status: 'resolved',
+    payload: { approved: true },
+  },
+])
+```
+
 ### Pattern 4: Lazy Tool Discovery
 
 Set `lazy: true` on rarely-needed tools. The LLM sees their names via a synthetic
@@ -635,7 +656,7 @@ import { anthropicText } from '@tanstack/ai-anthropic'
 export async function POST(request: Request) {
   const { messages } = await request.json()
   const stream = chat({
-    adapter: anthropicText('claude-sonnet-4-5'),
+    adapter: anthropicText('claude-sonnet-4-6'),
     messages,
     tools: [
       codeExecutionTool(
@@ -671,7 +692,7 @@ import { openaiText } from '@tanstack/ai-openai'
 export async function POST(request: Request) {
   const { messages } = await request.json()
   const stream = chat({
-    adapter: openaiText('gpt-5.2'),
+    adapter: openaiText('gpt-5.5'),
     messages,
     tools: [
       shellTool({
diff --git a/packages/ai/src/activities/chat/index.ts b/packages/ai/src/activities/chat/index.ts
index 93e7a6481..b8d9341ef 100644
--- a/packages/ai/src/activities/chat/index.ts
+++ b/packages/ai/src/activities/chat/index.ts
@@ -49,6 +49,7 @@ import type {
   ConstrainedModelMessage,
   CustomEvent,
   InferSchemaType,
+  Interrupt,
   JSONSchema,
   LazyToolsConfig,
   ModelMessage,
@@ -178,7 +179,7 @@ export interface TextActivityOptions<
   TStream extends boolean,
   TContext = unknown,
 > {
-  /** The text adapter to use (created by a provider function like openaiText('gpt-4o')) */
+  /** The text adapter to use (created by a provider function like openaiText('gpt-5.5')) */
   adapter: TAdapter
   /**
    * Conversation messages. Accepts:
@@ -254,6 +255,11 @@ export interface TextActivityOptions<
   runId?: TextOptions['runId']
   /** Parent run ID for AG-UI protocol nested run correlation. */
   parentRunId?: TextOptions['parentRunId']
+  /**
+   * AG-UI interrupt resume responses. Persistence middleware validates these
+   * before accepting new input on a thread with pending interrupts.
+   */
+  resume?: TextOptions['resume']
   /**
    * Optional Standard Schema for structured output.
    * When provided, the activity will:
@@ -265,7 +271,7 @@ export interface TextActivityOptions<
    * @example
    * ```ts
    * const result = await chat({
-   *   adapter: openaiText('gpt-4o'),
+   *   adapter: openaiText('gpt-5.5'),
    *   messages: [{ role: 'user', content: 'Generate a person' }],
    *   outputSchema: z.object({ name: z.string(), age: z.number() })
    * })
@@ -286,7 +292,7 @@ export interface TextActivityOptions<
    * @example Non-streaming text
    * ```ts
    * const text = await chat({
-   *   adapter: openaiText('gpt-4o'),
+   *   adapter: openaiText('gpt-5.5'),
    *   messages: [{ role: 'user', content: 'Hello!' }],
    *   stream: false
    * })
@@ -301,7 +307,7 @@ export interface TextActivityOptions<
    * @example
    * ```ts
    * const stream = chat({
-   *   adapter: openaiText('gpt-4o'),
+   *   adapter: openaiText('gpt-5.5'),
    *   messages: [...],
    *   middleware: [loggingMiddleware, redactionMiddleware],
    * })
@@ -531,12 +537,15 @@ class TextEngine<
   private eventOptions?: Record<string, unknown> | undefined
   private eventToolNames?: Array<string>
   private finishedEvent: RunFinishedEvent | null = null
+  private deferredToolCallRunFinishedChunks: Array<StreamChunk> = []
   private earlyTermination = false
   private toolPhase: ToolPhaseResult = 'continue'
   private cyclePhase: CyclePhase = 'processText'
   // Client state extracted from initial messages (before conversion to ModelMessage)
   private readonly initialApprovals: Map<string, boolean>
   private readonly initialClientToolResults: Map<string, any>
+  private readonly resumeApprovals = new Map<string, boolean>()
+  private readonly resumeClientToolResults = new Map<string, any>()
 
   // AG-UI protocol IDs
   private readonly threadId: string
@@ -861,12 +870,15 @@ class TextEngine<
       // requested AND the run hasn't already errored/aborted, run it through
       // the middleware pipeline. The terminal hook fires once at the very
       // end (after finalization), not after the agent loop.
+      // Actionable waits already emitted a RUN_FINISHED interrupt terminal, so
+      // do not run finalization after `processToolCalls()` pauses the stream.
       //
       // Native combined mode takes a different path: the agent loop's final-
       // turn text IS the schema-constrained JSON, so we harvest it from
       // `accumulatedContent` instead of issuing a second provider call.
       if (
         this.finalStructuredOutput &&
+        this.toolPhase !== 'wait' &&
         !this.isCancelled() &&
         !this.finalizationError
       ) {
@@ -1048,6 +1060,8 @@ class TextEngine<
         ? this.finalStructuredOutput.jsonSchema
         : undefined
 
+    const { approvals } = this.collectClientState()
+
     for await (const chunk of this.adapter.chatStream({
       model: this.params.model,
       messages: this.messages,
@@ -1063,7 +1077,7 @@ class TextEngine<
       // Expose provided capabilities (e.g. sandbox) to harness adapters.
       capabilities: this.middlewareCtx,
       // Client approval decisions, for harness interactive-approval resolution.
-      approvals: this.initialApprovals,
+      approvals,
       ...(combinedSchema ? { outputSchema: combinedSchema } : {}),
     })) {
       if (this.isCancelled()) {
@@ -1138,6 +1152,10 @@ class TextEngine<
         ) {
           continue
         }
+        if (this.shouldDeferToolCallRunFinished(outputChunk)) {
+          this.deferredToolCallRunFinishedChunks.push(outputChunk)
+          continue
+        }
         this.logger.output(`type=${outputChunk.type}`, { chunk: outputChunk })
         yield outputChunk
         this.middlewareCtx.chunkIndex++
@@ -1403,6 +1421,8 @@ class TextEngine<
       executionResult.needsApproval.length > 0 ||
       executionResult.needsClientExecution.length > 0
     ) {
+      this.discardDeferredToolCallRunFinishedChunks()
+
       if (executionResult.results.length > 0) {
         for (const chunk of this.buildToolResultChunks(
           executionResult.results,
@@ -1413,19 +1433,13 @@ class TextEngine<
         }
       }
 
-      for (const chunk of this.buildApprovalChunks(
-        executionResult.needsApproval,
-        finishEvent,
-      )) {
-        yield* this.pipeThroughMiddleware(chunk)
-      }
-
-      for (const chunk of this.buildClientToolChunks(
-        executionResult.needsClientExecution,
-        finishEvent,
-      )) {
-        yield* this.pipeThroughMiddleware(chunk)
-      }
+      yield* this.pipeThroughMiddleware(
+        this.buildInterruptFinishedChunk(
+          finishEvent,
+          executionResult.needsApproval,
+          executionResult.needsClientExecution,
+        ),
+      )
 
       this.setToolPhase('wait')
       return 'wait'
@@ -1489,6 +1503,7 @@ class TextEngine<
     }
 
     if (executableToolCalls.length === 0) {
+      yield* this.flushDeferredToolCallRunFinishedChunks()
       // All tool calls were undiscovered lazy tools — errors emitted, continue loop
       this.toolCallManager.clear()
       this.setToolPhase('continue')
@@ -1569,24 +1584,20 @@ class TextEngine<
         }
       }
 
-      for (const chunk of this.buildApprovalChunks(
-        executionResult.needsApproval,
-        finishEvent,
-      )) {
-        yield* this.pipeThroughMiddleware(chunk)
-      }
-
-      for (const chunk of this.buildClientToolChunks(
-        executionResult.needsClientExecution,
-        finishEvent,
-      )) {
-        yield* this.pipeThroughMiddleware(chunk)
-      }
+      yield* this.pipeThroughMiddleware(
+        this.buildInterruptFinishedChunk(
+          finishEvent,
+          executionResult.needsApproval,
+          executionResult.needsClientExecution,
+        ),
+      )
 
       this.setToolPhase('wait')
       return
     }
 
+    yield* this.flushDeferredToolCallRunFinishedChunks()
+
     const toolResultChunks = this.buildToolResultChunks(
       executionResult.results,
       finishEvent,
@@ -1612,6 +1623,28 @@ class TextEngine<
     this.setToolPhase('continue')
   }
 
+  private shouldDeferToolCallRunFinished(chunk: StreamChunk): boolean {
+    return (
+      chunk.type === EventType.RUN_FINISHED &&
+      this.finishedEvent?.finishReason === 'tool_calls' &&
+      this.tools.length > 0 &&
+      this.toolCallManager.hasToolCalls()
+    )
+  }
+
+  private *flushDeferredToolCallRunFinishedChunks(): Generator<StreamChunk> {
+    for (const chunk of this.deferredToolCallRunFinishedChunks) {
+      this.logger.output(`type=${chunk.type}`, { chunk })
+      yield chunk
+      this.middlewareCtx.chunkIndex++
+    }
+    this.deferredToolCallRunFinishedChunks = []
+  }
+
+  private discardDeferredToolCallRunFinishedChunks(): void {
+    this.deferredToolCallRunFinishedChunks = []
+  }
+
   private shouldExecuteToolPhase(): boolean {
     return (
       this.finishedEvent?.finishReason === 'tool_calls' &&
@@ -1682,6 +1715,12 @@ class TextEngine<
     // Start with the initial client state extracted from original messages
     const approvals = new Map(this.initialApprovals)
     const clientToolResults = new Map(this.initialClientToolResults)
+    for (const [approvalId, approved] of this.resumeApprovals) {
+      approvals.set(approvalId, approved)
+    }
+    for (const [toolCallId, result] of this.resumeClientToolResults) {
+      clientToolResults.set(toolCallId, result)
+    }
 
     // Also check current messages for any additional tool results (from server tools)
     for (const message of this.messages) {
@@ -1720,54 +1759,61 @@ class TextEngine<
     return { approvals, clientToolResults }
   }
 
-  private buildApprovalChunks(
+  private buildActionableInterrupts(
     approvals: Array<ApprovalRequest>,
-    finishEvent: RunFinishedEvent,
-  ): Array<StreamChunk> {
-    const chunks: Array<StreamChunk> = []
+    clientRequests: Array<ClientToolRequest>,
+  ): Array<Interrupt> {
+    const interrupts: Array<Interrupt> = []
 
     for (const approval of approvals) {
-      chunks.push({
-        type: 'CUSTOM',
-        timestamp: Date.now(),
-        model: finishEvent.model,
-        name: 'approval-requested',
-        value: {
-          toolCallId: approval.toolCallId,
+      interrupts.push({
+        id: approval.approvalId,
+        reason: 'approval_required',
+        message: `Approval required to run ${approval.toolName}`,
+        toolCallId: approval.toolCallId,
+        responseSchema: {
+          type: 'object',
+          properties: { approved: { type: 'boolean' } },
+          required: ['approved'],
+        },
+        metadata: {
+          kind: 'approval',
           toolName: approval.toolName,
           input: approval.input,
-          approval: {
-            id: approval.approvalId,
-            needsApproval: true,
-          },
         },
-      } as StreamChunk)
+      })
     }
 
-    return chunks
-  }
-
-  private buildClientToolChunks(
-    clientRequests: Array<ClientToolRequest>,
-    finishEvent: RunFinishedEvent,
-  ): Array<StreamChunk> {
-    const chunks: Array<StreamChunk> = []
-
     for (const clientTool of clientRequests) {
-      chunks.push({
-        type: 'CUSTOM',
-        timestamp: Date.now(),
-        model: finishEvent.model,
-        name: 'tool-input-available',
-        value: {
-          toolCallId: clientTool.toolCallId,
+      interrupts.push({
+        id: `client_tool_${clientTool.toolCallId}`,
+        reason: 'client_tool_input',
+        message: `Client tool ${clientTool.toolName} is ready to run`,
+        toolCallId: clientTool.toolCallId,
+        metadata: {
+          kind: 'client_tool',
           toolName: clientTool.toolName,
           input: clientTool.input,
         },
-      } as StreamChunk)
+      })
     }
 
-    return chunks
+    return interrupts
+  }
+
+  private buildInterruptFinishedChunk(
+    finishEvent: RunFinishedEvent,
+    approvals: Array<ApprovalRequest>,
+    clientRequests: Array<ClientToolRequest>,
+  ): StreamChunk {
+    return {
+      ...finishEvent,
+      timestamp: Date.now(),
+      outcome: {
+        type: 'interrupt',
+        interrupts: this.buildActionableInterrupts(approvals, clientRequests),
+      },
+    }
   }
 
   private buildToolResultChunks(
@@ -2514,12 +2560,28 @@ class TextEngine<
       messages: this.messages,
       systemPrompts: [...this.systemPrompts],
       tools: [...this.tools],
+      resume: this.params.resume,
+      resumeToolState: {
+        approvals: this.resumeApprovals,
+        clientToolResults: this.resumeClientToolResults,
+      },
       metadata: this.params.metadata,
       modelOptions: this.params.modelOptions,
     }
   }
 
   private applyMiddlewareConfig(config: ChatMiddlewareConfig): void {
+    if (config.resumeToolState?.approvals) {
+      for (const [approvalId, approved] of config.resumeToolState.approvals) {
+        this.resumeApprovals.set(approvalId, approved)
+      }
+    }
+    if (config.resumeToolState?.clientToolResults) {
+      for (const [toolCallId, result] of config.resumeToolState
+        .clientToolResults) {
+        this.resumeClientToolResults.set(toolCallId, result)
+      }
+    }
     this.messages = config.messages
     this.systemPrompts = config.systemPrompts
     this.tools = config.tools
@@ -2637,7 +2699,7 @@ class TextEngine<
  * import { openaiText } from '@tanstack/ai-openai'
  *
  * for await (const chunk of chat({
- *   adapter: openaiText('gpt-4o'),
+ *   adapter: openaiText('gpt-5.5'),
  *   messages: [{ role: 'user', content: 'What is the weather?' }],
  *   tools: [weatherTool]
  * })) {
@@ -2650,7 +2712,7 @@ class TextEngine<
  * @example One-shot text (streaming without tools)
  * ```ts
  * for await (const chunk of chat({
- *   adapter: openaiText('gpt-4o'),
+ *   adapter: openaiText('gpt-5.5'),
  *   messages: [{ role: 'user', content: 'Hello!' }]
  * })) {
  *   console.log(chunk)
@@ -2660,7 +2722,7 @@ class TextEngine<
  * @example Non-streaming text (stream: false)
  * ```ts
  * const text = await chat({
- *   adapter: openaiText('gpt-4o'),
+ *   adapter: openaiText('gpt-5.5'),
  *   messages: [{ role: 'user', content: 'Hello!' }],
  *   stream: false
  * })
@@ -2672,7 +2734,7 @@ class TextEngine<
  * import { z } from 'zod'
  *
  * const result = await chat({
- *   adapter: openaiText('gpt-4o'),
+ *   adapter: openaiText('gpt-5.5'),
  *   messages: [{ role: 'user', content: 'Research and summarize the topic' }],
  *   tools: [researchTool, analyzeTool],
  *   outputSchema: z.object({
@@ -3125,11 +3187,12 @@ function runStreamingStructuredOutput<
     undoNullWidening(data, nullWideningMap)
 
   // The implementation generator yields the broader internal type
-  // (`StreamChunk | StructuredOutputCompleteEvent<T>`) so agent-loop
-  // CustomEvents can flow through; the public-facing type narrows to
-  // `Exclude<StreamChunk, CustomEvent> | StructuredOutputCompleteEvent<T>`
-  // which lets consumers narrow `chunk.value` cleanly. The widen→narrow
-  // is contained here so consumers see only the strict type.
+  // (`StreamChunk | StructuredOutputCompleteEvent<T>`) so middleware and
+  // tool-emitted CustomEvents can flow through. Core approval/client-tool
+  // waits are represented by RUN_FINISHED interrupt outcomes, not by direct
+  // CUSTOM wait events.
+  // The contained cast keeps the public stream type focused on
+  // structured-output completion.
   return runStreamingStructuredOutputImpl(
     options,
     jsonSchema,
@@ -3139,11 +3202,11 @@ function runStreamingStructuredOutput<
 
 /**
  * Internal generator return type — broader than the public
- * `StructuredOutputStream<T>`. The public type pins three tagged `CUSTOM`
- * events (`structured-output.complete`, `approval-requested`,
- * `tool-input-available`) so consumers can narrow `chunk.value` cleanly by
- * literal `name`. At runtime, tools can also emit arbitrary user-defined
- * `CustomEvent`s through the `emitCustomEvent` context API; those flow
+ * `StructuredOutputStream<T>`. The structured-output completion event remains
+ * the pinned public CUSTOM event for this stream; approval and client-tool
+ * waits now surface as RUN_FINISHED interrupt outcomes. At runtime, tools can
+ * still emit arbitrary user-defined `CustomEvent`s through the
+ * `emitCustomEvent` context API; those flow
  * through this generator with `name: string` and are widened out at the
  * public boundary because keeping them would collapse the typed narrow back
  * to `any`. The cast inside `runStreamingStructuredOutput` is where that
diff --git a/packages/ai/src/activities/chat/middleware/index.ts b/packages/ai/src/activities/chat/middleware/index.ts
index 0de3edba2..6d231eedd 100644
--- a/packages/ai/src/activities/chat/middleware/index.ts
+++ b/packages/ai/src/activities/chat/middleware/index.ts
@@ -3,6 +3,7 @@ export type {
   ChatMiddlewareContext,
   ChatMiddlewarePhase,
   ChatMiddlewareConfig,
+  ChatResumeToolState,
   StructuredOutputMiddlewareConfig,
   ToolCallHookContext,
   BeforeToolCallDecision,
diff --git a/packages/ai/src/activities/chat/middleware/types.ts b/packages/ai/src/activities/chat/middleware/types.ts
index 74502b5c7..741d2df45 100644
--- a/packages/ai/src/activities/chat/middleware/types.ts
+++ b/packages/ai/src/activities/chat/middleware/types.ts
@@ -1,6 +1,7 @@
 import type {
   JSONSchema,
   ModelMessage,
+  RunAgentResumeItem,
   StreamChunk,
   TokenUsage,
   Tool,
@@ -133,7 +134,7 @@ export interface ChatMiddlewareContext<TContext = unknown> {
   activity: 'chat'
   /** Provider name (e.g., 'openai', 'anthropic') */
   provider: string
-  /** Model identifier (e.g., 'gpt-4o') */
+  /** Model identifier (e.g., 'gpt-5.5') */
   model: string
   /** Source of the chat invocation — always 'server' for server-side chat */
   source: 'client' | 'server'
@@ -208,10 +209,22 @@ export interface ChatMiddlewareConfig {
   messages: Array<ModelMessage>
   systemPrompts: Array<SystemPrompt>
   tools: Array<Tool>
+  resume?: Array<RunAgentResumeItem> | undefined
+  resumeToolState?: ChatResumeToolState | undefined
   metadata?: Record<string, unknown> | undefined
   modelOptions?: Record<string, unknown> | undefined
 }
 
+/**
+ * Tool decisions reconstructed by server-side middleware from validated resume
+ * entries. This lets empty-message interrupt resumes continue tool execution
+ * without relying on client message history.
+ */
+export interface ChatResumeToolState {
+  approvals?: ReadonlyMap<string, boolean> | undefined
+  clientToolResults?: ReadonlyMap<string, unknown> | undefined
+}
+
 /**
  * Config passed to onStructuredOutputConfig.
  *
diff --git a/packages/ai/src/activities/chat/stream/processor.ts b/packages/ai/src/activities/chat/stream/processor.ts
index 610846be5..5a755631c 100644
--- a/packages/ai/src/activities/chat/stream/processor.ts
+++ b/packages/ai/src/activities/chat/stream/processor.ts
@@ -50,6 +50,7 @@ import type {
 } from './types'
 import type {
   ContentPart,
+  Interrupt,
   MessagePart,
   ModelMessage,
   StreamChunk,
@@ -1429,6 +1430,10 @@ export class StreamProcessor {
     this.finishReason = chunk.finishReason ?? null
     this.activeRuns.delete(chunk.runId)
 
+    if (chunk.outcome?.type === 'interrupt') {
+      this.handleInterrupts(chunk.outcome.interrupts)
+    }
+
     if (this.activeRuns.size === 0) {
       this.isDone = true
       this.completeAllToolCalls()
@@ -1436,6 +1441,63 @@ export class StreamProcessor {
     }
   }
 
+  private handleInterrupts(interrupts: Array<Interrupt>): void {
+    for (const interrupt of interrupts) {
+      const metadata =
+        interrupt.metadata && typeof interrupt.metadata === 'object'
+          ? interrupt.metadata
+          : {}
+      const kind = typeof metadata.kind === 'string' ? metadata.kind : undefined
+      const toolCallId = interrupt.toolCallId
+      if (!toolCallId) continue
+
+      const toolName =
+        typeof metadata.toolName === 'string'
+          ? metadata.toolName
+          : this.findToolCallName(toolCallId)
+      const input = Object.hasOwn(metadata, 'input') ? metadata.input : {}
+
+      if (kind === 'approval' || interrupt.reason === 'approval_required') {
+        const resolvedMessageId =
+          this.getActiveAssistantMessageId() ??
+          this.toolCallToMessage.get(toolCallId)
+        if (resolvedMessageId) {
+          this.messages = updateToolCallApproval(
+            this.messages,
+            resolvedMessageId,
+            toolCallId,
+            interrupt.id,
+          )
+          this.emitMessagesChange()
+        }
+
+        this.events.onApprovalRequest?.({
+          toolCallId,
+          toolName,
+          input,
+          approvalId: interrupt.id,
+        })
+        continue
+      }
+
+      if (kind === 'client_tool' || interrupt.reason === 'client_tool_input') {
+        this.events.onToolCall?.({
+          toolCallId,
+          toolName,
+          input,
+        })
+      }
+    }
+  }
+
+  private findToolCallName(toolCallId: string): string {
+    for (const state of this.messageStates.values()) {
+      const toolCall = state.toolCalls.get(toolCallId)
+      if (toolCall) return toolCall.name
+    }
+    return ''
+  }
+
   /**
    * Handle RUN_ERROR event
    */
@@ -1656,10 +1718,15 @@ export class StreamProcessor {
   /**
    * Handle CUSTOM event.
    *
-   * Handles special custom events emitted by the TextEngine (not adapters):
-   * - 'tool-input-available': Client tool needs execution. Fires onToolCall.
-   * - 'approval-requested': Tool needs user approval. Updates tool-call part
-   *   state and fires onApprovalRequest.
+   * Handles custom events consumed by the processor:
+   * - 'tool-input-available': Legacy/replay-compatible input for client tool
+   *   execution. Fires onToolCall.
+   * - 'approval-requested': Legacy/replay-compatible input for tool approval.
+   *   Updates tool-call part state and fires onApprovalRequest.
+   *
+   * Current core streams represent user-actionable waits through
+   * RUN_FINISHED.outcome.type === 'interrupt'; these custom events are not the
+   * source of truth for new emissions.
    *
    * @see docs/chat-architecture.md#client-tools-and-approval-flows — Full flow details
    */
@@ -1890,6 +1957,13 @@ export class StreamProcessor {
       return
     }
 
+    // RUN_FINISHED interrupt handling can mark the rendered part as waiting on
+    // user action before the completion safety net runs. Keep the parsed
+    // argument bookkeeping above, but do not downgrade that visible state.
+    if (this.isToolCallPartAwaitingUserAction(toolCall.id)) {
+      return
+    }
+
     // Update UIMessage
     this.messages = updateToolCallPart(this.messages, messageId, {
       id: toolCall.id,
@@ -1909,6 +1983,19 @@ export class StreamProcessor {
     )
   }
 
+  private isToolCallPartAwaitingUserAction(toolCallId: string): boolean {
+    return this.messages.some((msg) =>
+      // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition -- `parts` is typed as required, but seeded ModelMessage-shaped messages can lack it at runtime.
+      msg.parts?.some(
+        (part) =>
+          part.type === 'tool-call' &&
+          part.id === toolCallId &&
+          (part.state === 'approval-requested' ||
+            part.state === 'approval-responded'),
+      ),
+    )
+  }
+
   /**
    * Whether the rendered tool-call part for the given id has reached the
    * terminal 'error' state. Used to prevent the completion safety net from
diff --git a/packages/ai/src/activities/generateAudio/index.ts b/packages/ai/src/activities/generateAudio/index.ts
index a9c452b98..95eb28c05 100644
--- a/packages/ai/src/activities/generateAudio/index.ts
+++ b/packages/ai/src/activities/generateAudio/index.ts
@@ -7,8 +7,13 @@
 
 import { aiEventClient } from '@tanstack/ai-event-client'
 import { streamGenerationResult } from '../stream-generation-result.js'
+import {
+  generationIdentityFields,
+  rejectEventsOnlyReplay,
+} from '../generation-run'
 import { resolveDebugOption } from '../../logger/resolve'
 import {
+  applyGenerationResultTransforms,
   createGenerationContext,
   runGenerationError,
   runGenerationFinish,
@@ -17,7 +22,7 @@ import {
 } from '../middleware'
 import type { InternalLogger } from '../../logger/internal-logger'
 import type { DebugOption } from '../../logger/types'
-import type { GenerationMiddleware } from '../middleware'
+import type { GenerationMiddleware, GenerationRunOptions } from '../middleware'
 import type { AudioAdapter } from './adapter'
 import type { AudioGenerationResult, StreamChunk } from '../../types'
 
@@ -55,7 +60,7 @@ export type AudioProviderOptions<TAdapter> = TAdapter extends {
 export interface AudioActivityOptions<
   TAdapter extends AudioAdapter<string, AudioProviderOptions<TAdapter>>,
   TStream extends boolean = false,
-> {
+> extends GenerationRunOptions<AudioGenerationResult> {
   /** The audio adapter to use (must be created with a model) */
   adapter: TAdapter & { kind: typeof kind }
   /** Text description of the desired audio */
@@ -134,8 +139,9 @@ export function generateAudio<
   options: AudioActivityOptions<TAdapter, TStream>,
 ): AudioActivityResult<TStream> {
   if (options.stream) {
-    return streamGenerationResult(() =>
-      runGenerateAudio(options),
+    return streamGenerationResult(
+      (resolvedOptions) => runGenerateAudio({ ...options, ...resolvedOptions }),
+      options,
     ) as AudioActivityResult<TStream>
   }
   return runGenerateAudio(options) as AudioActivityResult<TStream>
@@ -149,11 +155,20 @@ async function runGenerateAudio<
 >(
   options: AudioActivityOptions<TAdapter, boolean>,
 ): Promise<AudioGenerationResult> {
+  rejectEventsOnlyReplay(options.replay)
+
+  if (options.replay && 'result' in options.replay) {
+    return options.replay.result as AudioGenerationResult
+  }
+
   const {
     adapter,
     stream: _stream,
     debug: _debug,
     middleware,
+    threadId,
+    runId,
+    replay: _replay,
     ...rest
   } = options
   const model = adapter.model
@@ -164,6 +179,7 @@ async function runGenerateAudio<
     (adapter as { name?: string; provider?: string }).provider ??
     (adapter as { name?: string }).name ??
     'unknown'
+  const identity = { threadId, runId }
 
   const mwCtx = createGenerationContext({
     requestId,
@@ -171,6 +187,9 @@ async function runGenerateAudio<
     provider: adapter.name,
     model,
     modelOptions: rest.modelOptions,
+    threadId,
+    runId,
+    artifactInputs: { prompt: rest.prompt, duration: rest.duration },
     createId,
   })
 
@@ -178,6 +197,7 @@ async function runGenerateAudio<
 
   aiEventClient.emit('audio:request:started', {
     requestId,
+    ...generationIdentityFields(identity),
     provider: adapter.name,
     model,
     prompt: rest.prompt,
@@ -192,11 +212,13 @@ async function runGenerateAudio<
   })
 
   try {
-    const result = await adapter.generateAudio({ ...rest, model, logger })
+    const rawResult = await adapter.generateAudio({ ...rest, model, logger })
+    const result = await applyGenerationResultTransforms(mwCtx, rawResult)
     const elapsedMs = Date.now() - startTime
 
     aiEventClient.emit('audio:request:completed', {
       requestId,
+      ...generationIdentityFields(identity),
       provider: adapter.name,
       model,
       audio: result.audio,
@@ -208,6 +230,7 @@ async function runGenerateAudio<
     if (result.usage) {
       aiEventClient.emit('audio:usage', {
         requestId,
+        ...generationIdentityFields(identity),
         model,
         usage: result.usage,
         modelOptions: rest.modelOptions as Record<string, unknown> | undefined,
@@ -232,6 +255,7 @@ async function runGenerateAudio<
     const err = error as Error
     aiEventClient.emit('audio:request:error', {
       requestId,
+      ...generationIdentityFields(identity),
       provider: adapter.name,
       model,
       error: { message: err.message, name: err.name },
diff --git a/packages/ai/src/activities/generateImage/index.ts b/packages/ai/src/activities/generateImage/index.ts
index b87fbc724..eecf00961 100644
--- a/packages/ai/src/activities/generateImage/index.ts
+++ b/packages/ai/src/activities/generateImage/index.ts
@@ -7,8 +7,13 @@
 
 import { aiEventClient } from '@tanstack/ai-event-client'
 import { streamGenerationResult } from '../stream-generation-result.js'
+import {
+  generationIdentityFields,
+  rejectEventsOnlyReplay,
+} from '../generation-run'
 import { resolveDebugOption } from '../../logger/resolve'
 import {
+  applyGenerationResultTransforms,
   createGenerationContext,
   runGenerationError,
   runGenerationFinish,
@@ -18,7 +23,7 @@ import {
 import { resolveMediaPrompt } from '../../utilities/media-prompt'
 import type { InternalLogger } from '../../logger/internal-logger'
 import type { DebugOption } from '../../logger/types'
-import type { GenerationMiddleware } from '../middleware'
+import type { GenerationMiddleware, GenerationRunOptions } from '../middleware'
 import type { ImageAdapter } from './adapter'
 import type {
   ImageGenerationResult,
@@ -137,19 +142,20 @@ export type ImageActivityOptions<
    * `GenerationMiddleware` contract for a custom backend.
    */
   middleware?: Array<GenerationMiddleware>
-} & ({} extends ImageProviderOptionsForModel<TAdapter, TAdapter['model']>
-  ? {
-      /** Provider-specific options for image generation */ modelOptions?: ImageProviderOptionsForModel<
-        TAdapter,
-        TAdapter['model']
-      >
-    }
-  : {
-      /** Provider-specific options for image generation */ modelOptions: ImageProviderOptionsForModel<
-        TAdapter,
-        TAdapter['model']
-      >
-    })
+} & GenerationRunOptions<ImageGenerationResult> &
+  ({} extends ImageProviderOptionsForModel<TAdapter, TAdapter['model']>
+    ? {
+        /** Provider-specific options for image generation */ modelOptions?: ImageProviderOptionsForModel<
+          TAdapter,
+          TAdapter['model']
+        >
+      }
+    : {
+        /** Provider-specific options for image generation */ modelOptions: ImageProviderOptionsForModel<
+          TAdapter,
+          TAdapter['model']
+        >
+      })
 
 // ===========================
 // Activity Result Type
@@ -225,8 +231,9 @@ export function generateImage<
   options: ImageActivityOptions<TAdapter, TStream>,
 ): ImageActivityResult<TStream> {
   if (options.stream) {
-    return streamGenerationResult(() =>
-      runGenerateImage(options),
+    return streamGenerationResult(
+      (resolvedOptions) => runGenerateImage({ ...options, ...resolvedOptions }),
+      options,
     ) as ImageActivityResult<TStream>
   }
 
@@ -242,17 +249,27 @@ async function runGenerateImage<
 >(
   options: ImageActivityOptions<TAdapter, boolean>,
 ): Promise<ImageGenerationResult> {
+  rejectEventsOnlyReplay(options.replay)
+
+  if (options.replay && 'result' in options.replay) {
+    return options.replay.result as ImageGenerationResult
+  }
+
   const {
     adapter,
     stream: _stream,
     debug: _debug,
     middleware,
+    threadId,
+    runId,
+    replay: _replay,
     ...rest
   } = options
   const model = adapter.model
   const requestId = createId('image')
   const startTime = Date.now()
   const logger: InternalLogger = resolveDebugOption(options.debug)
+  const identity = { threadId, runId }
 
   const mwCtx = createGenerationContext({
     requestId,
@@ -260,6 +277,9 @@ async function runGenerateImage<
     provider: adapter.name,
     model,
     modelOptions: rest.modelOptions,
+    threadId,
+    runId,
+    artifactInputs: { prompt: rest.prompt },
     createId,
   })
 
@@ -271,6 +291,7 @@ async function runGenerateImage<
 
   aiEventClient.emit('image:request:started', {
     requestId,
+    ...generationIdentityFields(identity),
     provider: adapter.name,
     model,
     prompt: resolved.text,
@@ -295,11 +316,13 @@ async function runGenerateImage<
   })
 
   try {
-    const result = await adapter.generateImages({ ...rest, model, logger })
+    const rawResult = await adapter.generateImages({ ...rest, model, logger })
+    const result = await applyGenerationResultTransforms(mwCtx, rawResult)
     const duration = Date.now() - startTime
 
     aiEventClient.emit('image:request:completed', {
       requestId,
+      ...generationIdentityFields(identity),
       provider: adapter.name,
       model,
       // GeneratedImage is a discriminated `{ url } | { b64Json }` union, but the
@@ -319,6 +342,7 @@ async function runGenerateImage<
     if (result.usage) {
       aiEventClient.emit('image:usage', {
         requestId,
+        ...generationIdentityFields(identity),
         model,
         usage: result.usage,
         modelOptions: rest.modelOptions,
diff --git a/packages/ai/src/activities/generateSpeech/index.ts b/packages/ai/src/activities/generateSpeech/index.ts
index 06baabaa9..d4aa018bf 100644
--- a/packages/ai/src/activities/generateSpeech/index.ts
+++ b/packages/ai/src/activities/generateSpeech/index.ts
@@ -7,8 +7,13 @@
 
 import { aiEventClient } from '@tanstack/ai-event-client'
 import { streamGenerationResult } from '../stream-generation-result.js'
+import {
+  generationIdentityFields,
+  rejectEventsOnlyReplay,
+} from '../generation-run'
 import { resolveDebugOption } from '../../logger/resolve'
 import {
+  applyGenerationResultTransforms,
   createGenerationContext,
   runGenerationError,
   runGenerationFinish,
@@ -17,7 +22,7 @@ import {
 } from '../middleware'
 import type { InternalLogger } from '../../logger/internal-logger'
 import type { DebugOption } from '../../logger/types'
-import type { GenerationMiddleware } from '../middleware'
+import type { GenerationMiddleware, GenerationRunOptions } from '../middleware'
 import type { TTSAdapter } from './adapter'
 import type { StreamChunk, TTSResult } from '../../types'
 
@@ -54,7 +59,7 @@ export type TTSProviderOptions<TAdapter> =
 export interface TTSActivityOptions<
   TAdapter extends TTSAdapter<string, TTSProviderOptions<TAdapter>>,
   TStream extends boolean = false,
-> {
+> extends GenerationRunOptions<TTSResult> {
   /** The TTS adapter to use (must be created with a model) */
   adapter: TAdapter & { kind: typeof kind }
   /** The text to convert to speech */
@@ -144,8 +149,10 @@ export function generateSpeech<
   TStream extends boolean = false,
 >(options: TTSActivityOptions<TAdapter, TStream>): TTSActivityResult<TStream> {
   if (options.stream) {
-    return streamGenerationResult(() =>
-      runGenerateSpeech(options),
+    return streamGenerationResult(
+      (resolvedOptions) =>
+        runGenerateSpeech({ ...options, ...resolvedOptions }),
+      options,
     ) as TTSActivityResult<TStream>
   }
   return runGenerateSpeech(options) as TTSActivityResult<TStream>
@@ -157,11 +164,20 @@ export function generateSpeech<
 async function runGenerateSpeech<
   TAdapter extends TTSAdapter<string, TTSProviderOptions<TAdapter>>,
 >(options: TTSActivityOptions<TAdapter, boolean>): Promise<TTSResult> {
+  rejectEventsOnlyReplay(options.replay)
+
+  if (options.replay && 'result' in options.replay) {
+    return options.replay.result as TTSResult
+  }
+
   const {
     adapter,
     stream: _stream,
     debug: _debug,
     middleware,
+    threadId,
+    runId,
+    replay: _replay,
     ...rest
   } = options
   const model = adapter.model
@@ -172,6 +188,7 @@ async function runGenerateSpeech<
     (adapter as { name?: string; provider?: string }).provider ??
     (adapter as { name?: string }).name ??
     'unknown'
+  const identity = { threadId, runId }
 
   const mwCtx = createGenerationContext({
     requestId,
@@ -179,6 +196,14 @@ async function runGenerateSpeech<
     provider: adapter.name,
     model,
     modelOptions: rest.modelOptions,
+    threadId,
+    runId,
+    artifactInputs: {
+      text: rest.text,
+      voice: rest.voice,
+      format: rest.format,
+      speed: rest.speed,
+    },
     createId,
   })
 
@@ -186,6 +211,7 @@ async function runGenerateSpeech<
 
   aiEventClient.emit('speech:request:started', {
     requestId,
+    ...generationIdentityFields(identity),
     provider: adapter.name,
     model,
     text: rest.text,
@@ -202,11 +228,13 @@ async function runGenerateSpeech<
   })
 
   try {
-    const result = await adapter.generateSpeech({ ...rest, model, logger })
+    const rawResult = await adapter.generateSpeech({ ...rest, model, logger })
+    const result = await applyGenerationResultTransforms(mwCtx, rawResult)
     const duration = Date.now() - startTime
 
     aiEventClient.emit('speech:request:completed', {
       requestId,
+      ...generationIdentityFields(identity),
       provider: adapter.name,
       model,
       audio: result.audio,
@@ -221,6 +249,7 @@ async function runGenerateSpeech<
     if (result.usage) {
       aiEventClient.emit('speech:usage', {
         requestId,
+        ...generationIdentityFields(identity),
         model,
         usage: result.usage,
         modelOptions: rest.modelOptions as Record<string, unknown> | undefined,
@@ -245,6 +274,7 @@ async function runGenerateSpeech<
     const err = error as Error
     aiEventClient.emit('speech:request:error', {
       requestId,
+      ...generationIdentityFields(identity),
       provider: adapter.name,
       model,
       error: { message: err.message, name: err.name },
diff --git a/packages/ai/src/activities/generateTranscription/index.ts b/packages/ai/src/activities/generateTranscription/index.ts
index 31b4b3a0c..0c3d3299c 100644
--- a/packages/ai/src/activities/generateTranscription/index.ts
+++ b/packages/ai/src/activities/generateTranscription/index.ts
@@ -7,8 +7,13 @@
 
 import { aiEventClient } from '@tanstack/ai-event-client'
 import { streamGenerationResult } from '../stream-generation-result.js'
+import {
+  generationIdentityFields,
+  rejectEventsOnlyReplay,
+} from '../generation-run'
 import { resolveDebugOption } from '../../logger/resolve'
 import {
+  applyGenerationResultTransforms,
   createGenerationContext,
   runGenerationError,
   runGenerationFinish,
@@ -17,7 +22,7 @@ import {
 } from '../middleware'
 import type { InternalLogger } from '../../logger/internal-logger'
 import type { DebugOption } from '../../logger/types'
-import type { GenerationMiddleware } from '../middleware'
+import type { GenerationMiddleware, GenerationRunOptions } from '../middleware'
 import type { TranscriptionAdapter } from './adapter'
 import type {
   StreamChunk,
@@ -61,7 +66,7 @@ export interface TranscriptionActivityOptions<
     TranscriptionProviderOptions<TAdapter>
   >,
   TStream extends boolean = false,
-> {
+> extends GenerationRunOptions<TranscriptionResult> {
   /** The transcription adapter to use (must be created with a model) */
   adapter: TAdapter & { kind: typeof kind }
   /** The audio data to transcribe - can be base64 string, File, Blob, or Buffer */
@@ -171,8 +176,10 @@ export function generateTranscription<
   options: TranscriptionActivityOptions<TAdapter, TStream>,
 ): TranscriptionActivityResult<TStream> {
   if (options.stream) {
-    return streamGenerationResult(() =>
-      runGenerateTranscription(options),
+    return streamGenerationResult(
+      (resolvedOptions) =>
+        runGenerateTranscription({ ...options, ...resolvedOptions }),
+      options,
     ) as TranscriptionActivityResult<TStream>
   }
 
@@ -192,11 +199,20 @@ async function runGenerateTranscription<
 >(
   options: TranscriptionActivityOptions<TAdapter, boolean>,
 ): Promise<TranscriptionResult> {
+  rejectEventsOnlyReplay(options.replay)
+
+  if (options.replay && 'result' in options.replay) {
+    return options.replay.result as TranscriptionResult
+  }
+
   const {
     adapter,
     stream: _stream,
     debug: _debug,
     middleware,
+    threadId,
+    runId,
+    replay: _replay,
     ...rest
   } = options
   const model = adapter.model
@@ -207,6 +223,7 @@ async function runGenerateTranscription<
     (adapter as { name?: string; provider?: string }).provider ??
     (adapter as { name?: string }).name ??
     'unknown'
+  const identity = { threadId, runId }
 
   const mwCtx = createGenerationContext({
     requestId,
@@ -214,6 +231,14 @@ async function runGenerateTranscription<
     provider: adapter.name,
     model,
     modelOptions: rest.modelOptions,
+    threadId,
+    runId,
+    artifactInputs: {
+      audio: rest.audio,
+      language: rest.language,
+      prompt: rest.prompt,
+      responseFormat: rest.responseFormat,
+    },
     createId,
   })
 
@@ -221,6 +246,7 @@ async function runGenerateTranscription<
 
   aiEventClient.emit('transcription:request:started', {
     requestId,
+    ...generationIdentityFields(identity),
     provider: adapter.name,
     model,
     language: rest.language,
@@ -236,11 +262,13 @@ async function runGenerateTranscription<
   })
 
   try {
-    const result = await adapter.transcribe({ ...rest, model, logger })
+    const rawResult = await adapter.transcribe({ ...rest, model, logger })
+    const result = await applyGenerationResultTransforms(mwCtx, rawResult)
     const duration = Date.now() - startTime
 
     aiEventClient.emit('transcription:request:completed', {
       requestId,
+      ...generationIdentityFields(identity),
       provider: adapter.name,
       model,
       text: result.text,
@@ -267,6 +295,7 @@ async function runGenerateTranscription<
     const err = error as Error
     aiEventClient.emit('transcription:request:error', {
       requestId,
+      ...generationIdentityFields(identity),
       provider: adapter.name,
       model,
       error: { message: err.message, name: err.name },
diff --git a/packages/ai/src/activities/generateVideo/index.ts b/packages/ai/src/activities/generateVideo/index.ts
index 3c30803c9..b6efd0f94 100644
--- a/packages/ai/src/activities/generateVideo/index.ts
+++ b/packages/ai/src/activities/generateVideo/index.ts
@@ -9,8 +9,14 @@
 
 import { aiEventClient } from '@tanstack/ai-event-client'
 import { toRunErrorPayload } from '../error-payload'
+import {
+  generationIdentityFields,
+  rejectEventsOnlyReplay,
+  replayGenerationEvents,
+} from '../generation-run'
 import { resolveDebugOption } from '../../logger/resolve'
 import {
+  applyGenerationResultTransforms,
   createGenerationContext,
   runGenerationAbort,
   runGenerationError,
@@ -20,7 +26,11 @@ import {
 } from '../middleware'
 import type { InternalLogger } from '../../logger/internal-logger'
 import type { DebugOption } from '../../logger/types'
-import type { GenerationMiddleware } from '../middleware'
+import type {
+  GenerationMiddleware,
+  GenerationRunIdentity,
+  GenerationRunOptions,
+} from '../middleware'
 import type { VideoAdapter } from './adapter'
 import type {
   MediaPrompt,
@@ -126,58 +136,57 @@ interface VideoActivityBaseOptions<
 export type VideoCreateOptions<
   TAdapter extends VideoAdapter<string, any, any, any>,
   TStream extends boolean = false,
-> = VideoActivityBaseOptions<TAdapter> & {
-  /** Request type - create a new job (default if not specified) */
-  request?: 'create'
-  /**
-   * Description of the desired video. Either a plain string, or — for models
-   * that support image-conditioned generation — an ordered array of content
-   * parts interleaving text with image inputs. Image parts may carry
-   * `metadata.role` (`'start_frame' | 'end_frame' | 'reference' |
-   * 'character'`) to disambiguate intent; positional fallback otherwise. The
-   * accepted part types are narrowed per model via the adapter's
-   * input-modality map.
-   */
-  prompt: VideoPromptForAdapter<TAdapter>
-  /** Video size — format depends on the provider (e.g., "16:9", "1280x720") */
-  size?: VideoSizeForAdapter<TAdapter>
-  /**
-   * Video duration in seconds. Adapters that declare a per-model duration
-   * map narrow this to the model's valid union (e.g. `4 | 6 | 8` for Veo 3).
-   * Pass `adapter.snapDuration(seconds)` to coerce raw seconds to a valid
-   * value.
-   */
-  duration?: VideoDurationForAdapter<TAdapter>
-  /**
-   * Whether to stream the video generation lifecycle.
-   * When true, returns an AsyncIterable<StreamChunk> that handles the full
-   * job lifecycle: create job, poll for status, yield updates, and yield final result.
-   * When false or not provided, returns a Promise<VideoJobResult>.
-   *
-   * @default false
-   */
-  stream?: TStream
-  /** Polling interval in milliseconds (stream mode only). @default 2000 */
-  pollingInterval?: number
-  /** Maximum time to wait before timing out in milliseconds (stream mode only). @default 600000 */
-  maxDuration?: number
-  /** Custom run ID (stream mode only) */
-  runId?: string
-  /**
-   * Enable debug logging. Pass `true` to enable all categories, `false` to
-   * silence everything including errors, or a `DebugConfig` object for granular
-   * control and/or a custom `Logger`.
-   */
-  debug?: DebugOption
-  /**
-   * Observe-only middleware notified on start, usage, success, and error. Pass
-   * `otelMiddleware()` to emit OpenTelemetry spans, or implement the
-   * `GenerationMiddleware` contract for a custom backend. In streaming mode the
-   * span covers the full create→poll→complete lifecycle; in non-streaming mode
-   * it covers job submission. An abandoned stream fires `onAbort`.
-   */
-  middleware?: Array<GenerationMiddleware>
-} & ({} extends VideoProviderOptions<TAdapter>
+> = VideoActivityBaseOptions<TAdapter> &
+  GenerationRunOptions<VideoJobResult | VideoUrlResult> & {
+    /** Request type - create a new job (default if not specified) */
+    request?: 'create'
+    /**
+     * Description of the desired video. Either a plain string, or — for models
+     * that support image-conditioned generation — an ordered array of content
+     * parts interleaving text with image inputs. Image parts may carry
+     * `metadata.role` (`'start_frame' | 'end_frame' | 'reference' |
+     * 'character'`) to disambiguate intent; positional fallback otherwise. The
+     * accepted part types are narrowed per model via the adapter's
+     * input-modality map.
+     */
+    prompt: VideoPromptForAdapter<TAdapter>
+    /** Video size — format depends on the provider (e.g., "16:9", "1280x720") */
+    size?: VideoSizeForAdapter<TAdapter>
+    /**
+     * Video duration in seconds. Adapters that declare a per-model duration
+     * map narrow this to the model's valid union (e.g. `4 | 6 | 8` for Veo 3).
+     * Pass `adapter.snapDuration(seconds)` to coerce raw seconds to a valid
+     * value.
+     */
+    duration?: VideoDurationForAdapter<TAdapter>
+    /**
+     * Whether to stream the video generation lifecycle.
+     * When true, returns an AsyncIterable<StreamChunk> that handles the full
+     * job lifecycle: create job, poll for status, yield updates, and yield final result.
+     * When false or not provided, returns a Promise<VideoJobResult>.
+     *
+     * @default false
+     */
+    stream?: TStream
+    /** Polling interval in milliseconds (stream mode only). @default 2000 */
+    pollingInterval?: number
+    /** Maximum time to wait before timing out in milliseconds (stream mode only). @default 600000 */
+    maxDuration?: number
+    /**
+     * Enable debug logging. Pass `true` to enable all categories, `false` to
+     * silence everything including errors, or a `DebugConfig` object for granular
+     * control and/or a custom `Logger`.
+     */
+    debug?: DebugOption
+    /**
+     * Observe-only middleware notified on start, usage, success, and error. Pass
+     * `otelMiddleware()` to emit OpenTelemetry spans, or implement the
+     * `GenerationMiddleware` contract for a custom backend. In streaming mode the
+     * span covers the full create→poll→complete lifecycle; in non-streaming mode
+     * it covers job submission. An abandoned stream fires `onAbort`.
+     */
+    middleware?: Array<GenerationMiddleware>
+  } & ({} extends VideoProviderOptions<TAdapter>
     ? {
         /** Provider-specific options for video generation */ modelOptions?: VideoProviderOptions<TAdapter>
       }
@@ -316,7 +325,22 @@ export function generateVideo<
 async function runCreateVideoJob<
   TAdapter extends VideoAdapter<string, any, any, any>,
 >(options: VideoCreateOptions<TAdapter, boolean>): Promise<VideoJobResult> {
-  const { adapter, prompt, size, duration, modelOptions, middleware } = options
+  rejectEventsOnlyReplay(options.replay)
+
+  if (options.replay && 'result' in options.replay) {
+    return options.replay.result as VideoJobResult
+  }
+
+  const {
+    adapter,
+    prompt,
+    size,
+    duration,
+    modelOptions,
+    middleware,
+    threadId,
+    runId,
+  } = options
   const model = adapter.model
   const requestId = createId('video')
   const startTime = Date.now()
@@ -332,6 +356,9 @@ async function runCreateVideoJob<
     provider: adapter.name,
     model,
     modelOptions,
+    threadId,
+    runId,
+    artifactInputs: { prompt, size, duration },
     createId,
   })
 
@@ -343,7 +370,7 @@ async function runCreateVideoJob<
   })
 
   try {
-    const result = await adapter.createVideoJob({
+    const rawResult = await adapter.createVideoJob({
       model,
       prompt,
       size,
@@ -351,6 +378,7 @@ async function runCreateVideoJob<
       modelOptions,
       logger,
     })
+    const result = await applyGenerationResultTransforms(mwCtx, rawResult)
     logger.output(`activity=generateVideo jobId=${result.jobId}`, {
       jobId: result.jobId,
       model: result.model,
@@ -385,6 +413,11 @@ function sleep(ms: number): Promise<void> {
 async function* runStreamingVideoGeneration<
   TAdapter extends VideoAdapter<string, any, any, any>,
 >(options: VideoCreateOptions<TAdapter, true>): AsyncIterable<StreamChunk> {
+  if (options.replay?.events) {
+    yield* replayGenerationEvents(options.replay)
+    return
+  }
+
   const { adapter, prompt, size, duration, modelOptions, middleware } = options
   const model = adapter.model
   const runId = options.runId ?? createId('run')
@@ -398,21 +431,59 @@ async function* runStreamingVideoGeneration<
     (adapter as { name?: string }).name ??
     'unknown'
 
-  const threadId = createId('thread')
+  const threadId = options.threadId ?? createId('thread')
+  const identity = { threadId, runId }
 
   yield {
     type: 'RUN_STARTED',
     runId,
     threadId,
+    ...generationIdentityFields(identity),
     timestamp: Date.now(),
   } as StreamChunk
 
+  if (options.replay && 'result' in options.replay) {
+    const replayResult = options.replay.result as {
+      artifacts?: Array<unknown>
+    }
+    if (replayResult.artifacts && replayResult.artifacts.length > 0) {
+      yield {
+        type: 'CUSTOM',
+        name: 'generation:artifacts',
+        value: replayResult.artifacts,
+        ...generationIdentityFields(identity),
+        timestamp: Date.now(),
+      } as StreamChunk
+    }
+
+    yield {
+      type: 'CUSTOM',
+      name: 'generation:result',
+      value: options.replay.result,
+      ...generationIdentityFields(identity),
+      timestamp: Date.now(),
+    } as StreamChunk
+
+    yield {
+      type: 'RUN_FINISHED',
+      runId,
+      threadId,
+      finishReason: 'stop',
+      ...generationIdentityFields(identity),
+      timestamp: Date.now(),
+    } as StreamChunk
+    return
+  }
+
   const mwCtx = createGenerationContext({
     requestId,
     activity: 'video',
     provider: adapter.name,
     model,
     modelOptions,
+    threadId,
+    runId,
+    artifactInputs: { prompt, size, duration },
     createId,
   })
 
@@ -444,6 +515,7 @@ async function* runStreamingVideoGeneration<
       type: 'CUSTOM',
       name: 'video:job:created',
       value: { jobId: jobResult.jobId },
+      ...generationIdentityFields(identity),
       timestamp: Date.now(),
     } as StreamChunk
 
@@ -463,11 +535,16 @@ async function* runStreamingVideoGeneration<
           progress: statusResult.progress,
           error: statusResult.error,
         },
+        ...generationIdentityFields(identity),
         timestamp: Date.now(),
       } as StreamChunk
 
       if (statusResult.status === 'completed') {
-        const urlResult = await adapter.getVideoUrl(jobResult.jobId)
+        const rawUrlResult = await adapter.getVideoUrl(jobResult.jobId)
+        const urlResult = await applyGenerationResultTransforms(
+          mwCtx,
+          rawUrlResult,
+        )
 
         logger.output(
           `activity=generateVideo jobId=${jobResult.jobId} status=completed`,
@@ -489,16 +566,24 @@ async function* runStreamingVideoGeneration<
         })
         settled = true
 
+        if (urlResult.artifacts && urlResult.artifacts.length > 0) {
+          yield {
+            type: 'CUSTOM',
+            name: 'generation:artifacts',
+            value: urlResult.artifacts,
+            ...generationIdentityFields(identity),
+            timestamp: Date.now(),
+          } as StreamChunk
+        }
+
         yield {
           type: 'CUSTOM',
           name: 'generation:result',
           value: {
-            jobId: jobResult.jobId,
+            ...urlResult,
             status: 'completed',
-            url: urlResult.url,
-            expiresAt: urlResult.expiresAt,
-            ...(urlResult.usage ? { usage: urlResult.usage } : {}),
           },
+          ...generationIdentityFields(identity),
           timestamp: Date.now(),
         } as StreamChunk
 
@@ -507,6 +592,7 @@ async function* runStreamingVideoGeneration<
           runId,
           threadId,
           finishReason: 'stop',
+          ...generationIdentityFields(identity),
           timestamp: Date.now(),
         } as StreamChunk
         return
@@ -537,6 +623,7 @@ async function* runStreamingVideoGeneration<
       type: 'RUN_ERROR',
       runId,
       threadId,
+      ...generationIdentityFields(identity),
       message: payload.message,
       code: payload.code,
       error: payload,
@@ -583,22 +670,26 @@ async function* runStreamingVideoGeneration<
  */
 export async function getVideoJobStatus<
   TAdapter extends VideoAdapter<string, any, any, any>,
->(options: {
-  adapter: TAdapter & { kind: typeof kind }
-  jobId: string
-}): Promise<{
+>(
+  options: {
+    adapter: TAdapter & { kind: typeof kind }
+    jobId: string
+  } & GenerationRunIdentity,
+): Promise<{
   status: 'pending' | 'processing' | 'completed' | 'failed'
   progress?: number
   url?: string
   error?: string
   usage?: TokenUsage
 }> {
-  const { adapter, jobId } = options
+  const { adapter, jobId, threadId, runId } = options
   const requestId = createId('video-status')
   const startTime = Date.now()
+  const identity = { threadId, runId }
 
   aiEventClient.emit('video:request:started', {
     requestId,
+    ...generationIdentityFields(identity),
     provider: adapter.name,
     model: adapter.model,
     requestType: 'status',
@@ -615,6 +706,7 @@ export async function getVideoJobStatus<
       const urlResult = await adapter.getVideoUrl(jobId)
       aiEventClient.emit('video:request:completed', {
         requestId,
+        ...generationIdentityFields(identity),
         provider: adapter.name,
         model: adapter.model,
         requestType: 'status',
@@ -628,6 +720,7 @@ export async function getVideoJobStatus<
       if (urlResult.usage) {
         aiEventClient.emit('video:usage', {
           requestId,
+          ...generationIdentityFields(identity),
           model: adapter.model,
           usage: urlResult.usage,
           timestamp: Date.now(),
@@ -644,6 +737,7 @@ export async function getVideoJobStatus<
         error instanceof Error ? error.message : 'Failed to get video URL'
       aiEventClient.emit('video:request:completed', {
         requestId,
+        ...generationIdentityFields(identity),
         provider: adapter.name,
         model: adapter.model,
         requestType: 'status',
@@ -665,6 +759,7 @@ export async function getVideoJobStatus<
 
   aiEventClient.emit('video:request:completed', {
     requestId,
+    ...generationIdentityFields(identity),
     provider: adapter.name,
     model: adapter.model,
     requestType: 'status',
diff --git a/packages/ai/src/activities/generation-run.ts b/packages/ai/src/activities/generation-run.ts
new file mode 100644
index 000000000..328363f52
--- /dev/null
+++ b/packages/ai/src/activities/generation-run.ts
@@ -0,0 +1,31 @@
+import type { GenerationReplayInput, GenerationRunIdentity } from './middleware'
+import type { StreamChunk } from '../types'
+
+export function rejectEventsOnlyReplay(
+  replay: GenerationReplayInput<unknown> | undefined,
+): void {
+  if (replay?.events && !('result' in replay)) {
+    throw new Error(
+      'Generation replay with events requires stream: true or a replay.result.',
+    )
+  }
+}
+
+export function generationIdentityFields(identity: GenerationRunIdentity): {
+  threadId?: string
+  runId?: string
+} {
+  return {
+    ...(identity.threadId !== undefined ? { threadId: identity.threadId } : {}),
+    ...(identity.runId !== undefined ? { runId: identity.runId } : {}),
+  }
+}
+
+export async function* replayGenerationEvents(
+  replay: GenerationReplayInput<unknown>,
+): AsyncIterable<StreamChunk> {
+  if (!replay.events) return
+  for await (const event of replay.events) {
+    yield event
+  }
+}
diff --git a/packages/ai/src/activities/middleware/index.ts b/packages/ai/src/activities/middleware/index.ts
index 79454ac5c..6b0045c84 100644
--- a/packages/ai/src/activities/middleware/index.ts
+++ b/packages/ai/src/activities/middleware/index.ts
@@ -4,11 +4,17 @@ export type {
   GenerationActivity,
   GenerationMiddleware,
   GenerationMiddlewareContext,
+  GenerationResultTransform,
+  GenerationResultTransformContext,
   GenerationUsageInfo,
   GenerationFinishInfo,
   GenerationAbortInfo,
   GenerationErrorInfo,
   AnyGenerationMiddleware,
+  GenerationRunIdentity,
+  GenerationReplayInput,
+  GenerationReplayOptions,
+  GenerationRunOptions,
 } from './types'
 export {
   createGenerationContext,
@@ -17,4 +23,5 @@ export {
   runGenerationFinish,
   runGenerationAbort,
   runGenerationError,
+  applyGenerationResultTransforms,
 } from './run'
diff --git a/packages/ai/src/activities/middleware/run.ts b/packages/ai/src/activities/middleware/run.ts
index 6983b1e55..4ae63db3e 100644
--- a/packages/ai/src/activities/middleware/run.ts
+++ b/packages/ai/src/activities/middleware/run.ts
@@ -4,6 +4,7 @@ import type {
   GenerationFinishInfo,
   GenerationMiddleware,
   GenerationMiddlewareContext,
+  GenerationResultTransformContext,
   GenerationUsageInfo,
 } from './types'
 
@@ -19,6 +20,9 @@ export function createGenerationContext(args: {
   provider: string
   model: string
   modelOptions?: unknown
+  threadId?: string
+  runId?: string
+  artifactInputs?: unknown
   createId: (prefix: string) => string
 }): GenerationMiddlewareContext {
   return {
@@ -27,9 +31,13 @@ export function createGenerationContext(args: {
     provider: args.provider,
     model: args.model,
     modelOptions: args.modelOptions,
+    threadId: args.threadId,
+    runId: args.runId,
     source: 'server',
     createId: args.createId,
     context: undefined,
+    resultTransforms: [],
+    artifactInputs: args.artifactInputs,
   }
 }
 
@@ -86,3 +94,20 @@ export function runGenerationError(
 ): Promise<void> {
   return run(middleware, (mw) => mw.onError?.(ctx, info))
 }
+
+export async function applyGenerationResultTransforms<TResult>(
+  ctx: GenerationMiddlewareContext,
+  result: TResult,
+): Promise<TResult> {
+  let current = result
+  const transformCtx: GenerationResultTransformContext = { middleware: ctx }
+
+  for (const transform of ctx.resultTransforms ?? []) {
+    const transformed = await transform(current, transformCtx)
+    if (transformed !== undefined) {
+      current = transformed as TResult
+    }
+  }
+
+  return current
+}
diff --git a/packages/ai/src/activities/middleware/types.ts b/packages/ai/src/activities/middleware/types.ts
index 99ae3e44e..7f5b9ffc4 100644
--- a/packages/ai/src/activities/middleware/types.ts
+++ b/packages/ai/src/activities/middleware/types.ts
@@ -1,4 +1,4 @@
-import type { TokenUsage } from '../../types'
+import type { StreamChunk, TokenUsage } from '../../types'
 
 // ===========================
 // Generation middleware
@@ -39,6 +39,36 @@ export type GenerationActivity =
   | 'tts'
   | 'transcription'
 
+/** Caller/server supplied identity for a generation run. */
+export interface GenerationRunIdentity {
+  /** Stable conversation/thread id for correlating generation events. */
+  threadId?: string
+  /** Stable run id for correlating generation events. */
+  runId?: string
+}
+
+export interface GenerationReplayInput<TResult = unknown> {
+  /**
+   * Previously persisted public generation events. Streaming replay yields
+   * these events as-is and does not call the provider.
+   */
+  events?: Iterable<StreamChunk> | AsyncIterable<StreamChunk>
+  /**
+   * Previously persisted terminal result. Non-streaming replay returns this
+   * value as-is; streaming replay wraps it in the standard generation event
+   * envelope. Result transforms are intentionally skipped for replay.
+   */
+  result?: TResult
+}
+
+/** Optional replay hook shared by media generation activities. */
+export interface GenerationReplayOptions<TResult = unknown> {
+  replay?: GenerationReplayInput<TResult>
+}
+
+export type GenerationRunOptions<TResult = unknown> = GenerationRunIdentity &
+  GenerationReplayOptions<TResult>
+
 /**
  * Stable context passed to every {@link GenerationMiddleware} hook. Created
  * once per activity call and shared across the hooks of that call.
@@ -60,6 +90,10 @@ export interface GenerationMiddlewareContext<TContext = unknown> {
   provider: string
   /** Model id. Emitted as `gen_ai.request.model`. */
   model: string
+  /** Stable conversation/thread id, when supplied by the caller. */
+  threadId?: string
+  /** Stable run id, when supplied by the caller. */
+  runId?: string
   /**
    * Provider-specific options passed to the activity, if any. Typed `unknown`
    * because each activity's options are strongly typed per model; a supertype
@@ -72,8 +106,30 @@ export interface GenerationMiddlewareContext<TContext = unknown> {
   createId: (prefix: string) => string
   /** Runtime context provided by the activity options, if any. */
   context: TContext
+  /**
+   * Result transforms registered by middleware during this activity call.
+   * Transforms run after the raw adapter result exists and before the final
+   * result is returned or streamed. Push multiple transforms to run them in
+   * registration order.
+   */
+  resultTransforms?: Array<GenerationResultTransform<any, TContext>>
+  /**
+   * Activity inputs captured for middleware that needs to transform or persist
+   * the result together with reconstructable request metadata.
+   */
+  artifactInputs?: unknown
+}
+
+export interface GenerationResultTransformContext<TContext = unknown> {
+  /** Stable context for the activity call being transformed. */
+  middleware: GenerationMiddlewareContext<TContext>
 }
 
+export type GenerationResultTransform<TResult = unknown, TContext = unknown> = (
+  result: TResult,
+  ctx: GenerationResultTransformContext<TContext>,
+) => TResult | undefined | Promise<TResult | undefined>
+
 // ===========================
 // Hook payloads
 // ===========================
diff --git a/packages/ai/src/activities/stream-generation-result.ts b/packages/ai/src/activities/stream-generation-result.ts
index 1bb530179..ea01ba2d9 100644
--- a/packages/ai/src/activities/stream-generation-result.ts
+++ b/packages/ai/src/activities/stream-generation-result.ts
@@ -6,6 +6,11 @@
 
 import { EventType } from '@ag-ui/core'
 import { toRunErrorPayload } from './error-payload'
+import {
+  generationIdentityFields,
+  replayGenerationEvents,
+} from './generation-run'
+import type { GenerationRunOptions } from './middleware'
 import type { StreamChunk } from '../types'
 
 function createId(prefix: string): string {
@@ -23,26 +28,54 @@ function createId(prefix: string): string {
  * @returns An AsyncIterable of StreamChunks with RUN_STARTED, CUSTOM(generation:result), and RUN_FINISHED events on success, or RUN_STARTED and RUN_ERROR on failure
  */
 export async function* streamGenerationResult<TResult>(
-  generator: () => Promise<TResult>,
-  options?: { runId?: string; threadId?: string },
+  generator: (
+    options: GenerationRunOptions<TResult> & {
+      runId: string
+      threadId: string
+    },
+  ) => Promise<TResult>,
+  options?: GenerationRunOptions<TResult>,
 ): AsyncIterable<StreamChunk> {
+  if (options?.replay?.events) {
+    yield* replayGenerationEvents(options.replay)
+    return
+  }
+
   const runId = options?.runId ?? createId('run')
   const threadId = options?.threadId ?? createId('thread')
+  const identity = { runId, threadId }
+  const resolvedOptions = { ...options, ...identity }
 
   yield {
     type: EventType.RUN_STARTED,
     runId,
     threadId,
+    ...generationIdentityFields(resolvedOptions),
     timestamp: Date.now(),
   }
 
   try {
-    const result = await generator()
+    const result =
+      options?.replay && 'result' in options.replay
+        ? (options.replay.result as TResult)
+        : await generator(resolvedOptions)
+    const artifacts = (result as { artifacts?: unknown }).artifacts
+
+    if (Array.isArray(artifacts) && artifacts.length > 0) {
+      yield {
+        type: EventType.CUSTOM,
+        name: 'generation:artifacts',
+        value: artifacts,
+        ...generationIdentityFields(resolvedOptions),
+        timestamp: Date.now(),
+      }
+    }
 
     yield {
       type: EventType.CUSTOM,
       name: 'generation:result',
       value: result as unknown,
+      ...generationIdentityFields(resolvedOptions),
       timestamp: Date.now(),
     }
 
@@ -51,6 +84,7 @@ export async function* streamGenerationResult<TResult>(
       runId,
       threadId,
       finishReason: 'stop',
+      ...generationIdentityFields(resolvedOptions),
       timestamp: Date.now(),
     }
   } catch (error: unknown) {
@@ -63,6 +97,7 @@ export async function* streamGenerationResult<TResult>(
       payload.code !== undefined ? { code: payload.code } : undefined
     yield {
       type: EventType.RUN_ERROR,
+      ...generationIdentityFields(identity),
       message: payload.message,
       ...codeFields,
       // Deprecated nested form for backward compatibility
diff --git a/packages/ai/src/client.ts b/packages/ai/src/client.ts
index 254daf736..1a9d8e623 100644
--- a/packages/ai/src/client.ts
+++ b/packages/ai/src/client.ts
@@ -1,3 +1,194 @@
+import type {
+  AudioGenerationOptions,
+  ImageGenerationOptions,
+  TTSOptions,
+  TranscriptionOptions,
+  VideoGenerationOptions,
+} from './types'
+
+export type GenerationKind =
+  | 'image'
+  | 'audio'
+  | 'tts'
+  | 'video'
+  | 'transcription'
+
+type GenerationInputByKind = {
+  image: Omit<ImageGenerationOptions, 'logger' | 'model'>
+  audio: Omit<AudioGenerationOptions, 'logger' | 'model'>
+  tts: Omit<TTSOptions, 'logger' | 'model'>
+  video: Omit<VideoGenerationOptions, 'logger' | 'model'>
+  transcription: Omit<TranscriptionOptions, 'logger' | 'model'>
+}
+
+export interface GenerationParams<TKind extends GenerationKind> {
+  input: GenerationInputByKind[TKind]
+  forwardedProps: Record<string, unknown>
+  threadId?: string
+  runId?: string
+}
+
+const generationKinds = [
+  'image',
+  'audio',
+  'tts',
+  'video',
+  'transcription',
+] as const satisfies ReadonlyArray<GenerationKind>
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null && !Array.isArray(value)
+}
+
+function hasOwnKey(value: Record<string, unknown>, key: string): boolean {
+  return Object.prototype.hasOwnProperty.call(value, key)
+}
+
+function isGenerationEnvelope(body: unknown): body is Record<string, unknown> {
+  return (
+    isRecord(body) &&
+    (hasOwnKey(body, 'data') || hasOwnKey(body, 'forwardedProps'))
+  )
+}
+
+function assertGenerationKind(kind: unknown): asserts kind is GenerationKind {
+  if (!generationKinds.includes(kind as GenerationKind)) {
+    throw new Error(
+      `Unsupported generation kind: ${String(
+        kind,
+      )}. Expected one of ${generationKinds.join(', ')}.`,
+    )
+  }
+}
+
+function assertInputForKind(
+  kind: GenerationKind,
+  input: unknown,
+): asserts input is GenerationInputByKind[GenerationKind] {
+  if (!isRecord(input)) {
+    throw new Error(`Generation ${kind} input must be an object.`)
+  }
+
+  const requiredKey =
+    kind === 'tts' ? 'text' : kind === 'transcription' ? 'audio' : 'prompt'
+
+  if (!hasOwnKey(input, requiredKey)) {
+    throw new Error(`Generation ${kind} input must include ${requiredKey}.`)
+  }
+}
+
+function isInputForKind(kind: GenerationKind, input: unknown): boolean {
+  if (!isRecord(input)) return false
+
+  const requiredKey =
+    kind === 'tts' ? 'text' : kind === 'transcription' ? 'audio' : 'prompt'
+
+  return hasOwnKey(input, requiredKey)
+}
+
+function forwardedPropsFromEnvelope(
+  envelope: Record<string, unknown>,
+): Record<string, unknown> {
+  if (!hasOwnKey(envelope, 'forwardedProps')) {
+    return {}
+  }
+
+  if (!isRecord(envelope.forwardedProps)) {
+    throw new Error('Generation envelope forwardedProps must be an object.')
+  }
+
+  return envelope.forwardedProps
+}
+
+function optionalStringField(
+  envelope: Record<string, unknown>,
+  key: 'threadId' | 'runId',
+): string | undefined {
+  if (!hasOwnKey(envelope, key)) {
+    return undefined
+  }
+
+  const value = envelope[key]
+  if (typeof value !== 'string') {
+    throw new Error(`Generation envelope ${key} must be a string.`)
+  }
+
+  return value
+}
+
+function generationIdentityFields(envelope: Record<string, unknown>): {
+  threadId?: string
+  runId?: string
+} {
+  const identity: {
+    threadId?: string
+    runId?: string
+  } = {}
+  const threadId = optionalStringField(envelope, 'threadId')
+  const runId = optionalStringField(envelope, 'runId')
+
+  if (threadId !== undefined) identity.threadId = threadId
+  if (runId !== undefined) identity.runId = runId
+
+  return identity
+}
+
+export function generationParamsFromBody<TKind extends GenerationKind>(
+  kind: TKind,
+  body: unknown,
+): GenerationParams<TKind> {
+  assertGenerationKind(kind)
+
+  if (isInputForKind(kind, body)) {
+    assertInputForKind(kind, body)
+    return {
+      input: body as GenerationInputByKind[TKind],
+      forwardedProps: {},
+    }
+  }
+
+  if (!isGenerationEnvelope(body)) {
+    assertInputForKind(kind, body)
+    return {
+      input: body as GenerationInputByKind[TKind],
+      forwardedProps: {},
+    }
+  }
+
+  if (!hasOwnKey(body, 'data')) {
+    throw new Error(`Generation ${kind} envelope must include data.`)
+  }
+
+  const input = body.data
+  assertInputForKind(kind, input)
+
+  const forwardedProps = forwardedPropsFromEnvelope(body)
+
+  return {
+    input: input as GenerationInputByKind[TKind],
+    forwardedProps,
+    ...generationIdentityFields(body),
+  }
+}
+
+export async function generationParamsFromRequest<TKind extends GenerationKind>(
+  kind: TKind,
+  request: Request,
+): Promise<GenerationParams<TKind>> {
+  let body: unknown
+  try {
+    body = await request.json()
+  } catch (error) {
+    throw new Error('Invalid JSON request body.', { cause: error })
+  }
+
+  if (!isRecord(body)) {
+    throw new Error('Generation request body must be a JSON object.')
+  }
+
+  return generationParamsFromBody(kind, body)
+}
+
 export enum EventType {
   TEXT_MESSAGE_START = 'TEXT_MESSAGE_START',
   TEXT_MESSAGE_CONTENT = 'TEXT_MESSAGE_CONTENT',
@@ -103,8 +294,14 @@ export type {
   MediaPromptPart,
   MessagePart,
   ModelMessage,
+  PersistedArtifactActivity,
+  PersistedArtifactRef,
+  PersistedArtifactRole,
+  Interrupt,
+  RunAgentResumeItem,
   RunErrorEvent,
   RunFinishedEvent,
+  RunFinishedOutcome,
   SchemaInput,
   StreamChunk,
   StructuredOutputPart,
diff --git a/packages/ai/src/custom-events.ts b/packages/ai/src/custom-events.ts
new file mode 100644
index 000000000..78905434d
--- /dev/null
+++ b/packages/ai/src/custom-events.ts
@@ -0,0 +1,107 @@
+/**
+ * Catalog of well-known AG-UI `CUSTOM` event names used by the sandbox/agent
+ * layers, plus their payload shapes.
+ *
+ * The persisted run log is the AG-UI `StreamChunk` stream itself — there is no
+ * separate `RunEvent` type. Agent activity that has no first-class AG-UI event
+ * (process output, file diffs, ports, approvals, artifacts, sandbox lifecycle)
+ * rides on `CUSTOM` events carrying one of these names. Centralizing the names +
+ * payloads here keeps emitters (harness adapters, sandbox) and consumers
+ * (persistence projections, devtools, diff/terminal panels) in agreement without
+ * inventing a parallel event union.
+ */
+import { EventType } from './types'
+import type { CustomEvent, StreamChunk } from './types'
+
+/** Well-known CUSTOM event names. */
+export const CUSTOM_EVENT = {
+  FILE_CHANGED: 'file.changed',
+  PROCESS_STDOUT: 'process.stdout',
+  PROCESS_STDERR: 'process.stderr',
+  PORT_OPENED: 'port.opened',
+  APPROVAL_REQUESTED: 'approval.requested',
+  APPROVAL_RESOLVED: 'approval.resolved',
+  ARTIFACT_CREATED: 'artifact.created',
+  SANDBOX_CREATED: 'sandbox.created',
+  SANDBOX_RESUMED: 'sandbox.resumed',
+} as const
+
+/** Union of the well-known CUSTOM event name literals. */
+export type WellKnownCustomEventName =
+  (typeof CUSTOM_EVENT)[keyof typeof CUSTOM_EVENT]
+
+// ---- Payload shapes ----
+
+export interface FileChangedPayload {
+  type: 'create' | 'change' | 'delete'
+  /** Absolute path inside the sandbox (under the workspace root). */
+  path: string
+  /** Unified diff, when the harness can produce one. */
+  diff?: string
+  timestamp: number
+}
+
+export interface ProcessOutputPayload {
+  /** Stable id for the spawned process whose output this is. */
+  processId: string
+  /** A chunk of stdout/stderr text. */
+  chunk: string
+}
+
+export interface PortOpenedPayload {
+  port: number
+  /** Externally reachable URL, when the provider exposes one. */
+  url?: string
+}
+
+export interface ApprovalRequestedPayload {
+  approvalId: string
+  title: string
+  /** Free-form detail describing the action awaiting approval. */
+  [key: string]: unknown
+}
+
+export interface ApprovalResolvedPayload {
+  approvalId: string
+  granted: boolean
+}
+
+export interface ArtifactCreatedPayload {
+  artifactId: string
+  name: string
+  mimeType: string
+  size: number
+}
+
+export interface SandboxLifecyclePayload {
+  sandboxId: string
+  provider: string
+}
+
+/** Maps each well-known name to its payload type. */
+export interface CustomEventPayloads {
+  [CUSTOM_EVENT.FILE_CHANGED]: FileChangedPayload
+  [CUSTOM_EVENT.PROCESS_STDOUT]: ProcessOutputPayload
+  [CUSTOM_EVENT.PROCESS_STDERR]: ProcessOutputPayload
+  [CUSTOM_EVENT.PORT_OPENED]: PortOpenedPayload
+  [CUSTOM_EVENT.APPROVAL_REQUESTED]: ApprovalRequestedPayload
+  [CUSTOM_EVENT.APPROVAL_RESOLVED]: ApprovalResolvedPayload
+  [CUSTOM_EVENT.ARTIFACT_CREATED]: ArtifactCreatedPayload
+  [CUSTOM_EVENT.SANDBOX_CREATED]: SandboxLifecyclePayload
+  [CUSTOM_EVENT.SANDBOX_RESUMED]: SandboxLifecyclePayload
+}
+
+/** A CUSTOM event narrowed to a specific well-known name and its payload. */
+export type WellKnownCustomEvent<TName extends WellKnownCustomEventName> =
+  CustomEvent & { name: TName; value: CustomEventPayloads[TName] }
+
+/**
+ * Type guard: is `chunk` a CUSTOM event with the given well-known `name`?
+ * Narrows the payload type when true, so consumers read `chunk.value` typed.
+ */
+export function isCustomEvent<TName extends WellKnownCustomEventName>(
+  chunk: StreamChunk,
+  name: TName,
+): chunk is WellKnownCustomEvent<TName> {
+  return chunk.type === EventType.CUSTOM && chunk.name === name
+}
diff --git a/packages/ai/src/index.ts b/packages/ai/src/index.ts
index 194e04729..ea3eddfc4 100644
--- a/packages/ai/src/index.ts
+++ b/packages/ai/src/index.ts
@@ -79,6 +79,10 @@ export {
   toHttpResponse,
 } from './stream-to-response'
 
+// Delivery durability (transport layer)
+export { memoryStream, encodeOffset, decodeOffset } from './stream-durability'
+export type { StreamDurability } from './stream-durability'
+
 // Tool call management
 export { ToolCallManager } from './activities/chat/tools/tool-calls'
 
@@ -110,6 +114,7 @@ export type {
   ChatMiddlewareContext,
   ChatMiddlewarePhase,
   ChatMiddlewareConfig,
+  ChatResumeToolState,
   StructuredOutputMiddlewareConfig,
   ToolCallHookContext,
   BeforeToolCallDecision,
@@ -133,12 +138,18 @@ export type {
 export type {
   GenerationMiddleware,
   GenerationMiddlewareContext,
+  GenerationResultTransform,
+  GenerationResultTransformContext,
   GenerationActivity,
   GenerationUsageInfo,
   GenerationFinishInfo,
   GenerationAbortInfo,
   GenerationErrorInfo,
   AnyGenerationMiddleware,
+  GenerationRunIdentity,
+  GenerationReplayInput,
+  GenerationReplayOptions,
+  GenerationRunOptions,
 } from './activities/middleware/index'
 // Capability primitives + middleware builder
 export {
@@ -156,6 +167,28 @@ export type {
   AnyChatMiddleware,
 } from './activities/chat/middleware/index'
 
+// Shared lock primitive (one global 'locks' capability; see locks.ts)
+export {
+  LocksCapability,
+  getLocks,
+  provideLocks,
+  InMemoryLockStore,
+} from './locks'
+export type { LockStore } from './locks'
+
+// Well-known AG-UI CUSTOM event catalog (agent activity rides on CUSTOM events)
+export { CUSTOM_EVENT, isCustomEvent } from './custom-events'
+export type {
+  WellKnownCustomEventName,
+  FileChangedPayload,
+  ProcessOutputPayload,
+  PortOpenedPayload,
+  ApprovalRequestedPayload,
+  ApprovalResolvedPayload,
+  ArtifactCreatedPayload,
+  SandboxLifecyclePayload,
+} from './custom-events'
+
 // All types
 export * from './types'
 
@@ -248,6 +281,8 @@ export {
   mergeAgentTools,
 } from './utilities/chat-params'
 
+export { generationParamsFromBody, generationParamsFromRequest } from './client'
+
 // AG-UI wire serialization (used internally by @tanstack/ai-client)
 export { uiMessagesToWire } from './utilities/ag-ui-wire'
 export type { WireMessage } from './utilities/ag-ui-wire'
diff --git a/packages/ai/src/locks.ts b/packages/ai/src/locks.ts
new file mode 100644
index 000000000..06c4727f3
--- /dev/null
+++ b/packages/ai/src/locks.ts
@@ -0,0 +1,56 @@
+/**
+ * Distributed-mutex primitive, shared across the sandbox and persistence
+ * layers via the middleware capability system.
+ *
+ * `LocksCapability` lives in core (rather than in `@tanstack/ai-sandbox` or
+ * `@tanstack/ai-persistence`) so there is exactly ONE `'locks'` token: capability
+ * names must be globally unique, and both `withSandbox` (which optionally
+ * requires it) and `withChatPersistence` (which provides a durable implementation)
+ * must reference the same handle. The in-memory default here is correct within a
+ * single process; the persistence layer provides a distributed lock (e.g. a
+ * Durable Object) for multi-instance deployments.
+ */
+import { createCapability } from './activities/chat/middleware/capabilities'
+
+/**
+ * Mutual exclusion around a critical section keyed by `key`. Used by the
+ * sandbox `ensure` algorithm so two concurrent runs for the same thread don't
+ * both create a sandbox, and available to any middleware that needs a named lock.
+ */
+export interface LockStore {
+  withLock: <T>(key: string, fn: () => Promise<T>) => Promise<T>
+}
+
+/**
+ * The lock capability. PROVIDED by `withChatPersistence` (durable) and OPTIONALLY
+ * required by `withSandbox`. Falls back to {@link InMemoryLockStore} when no
+ * middleware provides it.
+ */
+export const LocksCapability = createCapability<LockStore>()('locks')
+
+/** Destructured accessors: `getLocks(ctx)` / `provideLocks(ctx, store)`. */
+export const [getLocks, provideLocks] = LocksCapability
+
+/**
+ * In-memory {@link LockStore} — a per-key promise chain. Correct within a
+ * single process; multi-instance correctness needs a distributed lock from the
+ * persistence layer.
+ */
+export class InMemoryLockStore implements LockStore {
+  private readonly chains = new Map<string, Promise<unknown>>()
+
+  withLock<T>(key: string, fn: () => Promise<T>): Promise<T> {
+    const prior = this.chains.get(key) ?? Promise.resolve()
+    // Chain after the prior holder regardless of how it settled.
+    const run = prior.then(fn, fn)
+    // Keep the chain alive but swallow rejections so one failure doesn't poison the lock.
+    this.chains.set(
+      key,
+      run.then(
+        () => undefined,
+        () => undefined,
+      ),
+    )
+    return run
+  }
+}
diff --git a/packages/ai/src/stream-durability.ts b/packages/ai/src/stream-durability.ts
new file mode 100644
index 000000000..b06f507dc
--- /dev/null
+++ b/packages/ai/src/stream-durability.ts
@@ -0,0 +1,332 @@
+import type { StreamChunk } from './types'
+
+/**
+ * A pluggable sink for **delivery durability** — the transport-layer concern of
+ * letting a client disconnect, reload, or open a second tab and still receive
+ * the full, ordered run stream exactly once.
+ *
+ * This is deliberately thin: append / read / resume-detect and nothing else. It
+ * stores no run status, no messages, no interrupts — those are *state*
+ * durability (the middleware layer). Keeping this interface small is what stops
+ * delivery durability drifting back into "a transport wearing a store costume".
+ *
+ * Adapters close over the incoming `Request` (that is why they are constructed
+ * as `memoryStream(request)` / `durableStream(request, opts)`), so `request`
+ * never pollutes the transport-helper signature.
+ *
+ * Offsets are opaque strings of the form `runId@seq` (see {@link encodeOffset}).
+ * The sentinels `-1` (from the start) and `now` (tail — only future writes) may
+ * appear in the seq position.
+ */
+export interface StreamDurability {
+  /**
+   * The offset to resume from, read off the captured request — the
+   * `Last-Event-ID` header (native `EventSource` reconnect) or, failing that,
+   * the `?offset` query param. Returns `null` for a fresh run (produce path).
+   */
+  resumeFrom: () => string | null
+  /**
+   * The stable run/stream id for this request. Minted (`crypto.randomUUID()`)
+   * for a fresh run; parsed from the resume offset / `?runId` param otherwise.
+   * Memoized so repeated calls return the same id.
+   */
+  runId: () => string
+  /**
+   * Append a batch of chunks. The first chunk takes sequence number `startSeq`,
+   * the next `startSeq + 1`, and so on (sequence numbers are 1-based).
+   *
+   * Resolves to a per-chunk array of the **resume offsets the transport should
+   * tag each chunk with** (its client-facing SSE `id:`), aligned position-for-
+   * position with `chunks`. An element is `undefined` when that chunk carries
+   * no resumable offset.
+   *
+   * The offsets MUST be the offsets the backend will actually accept on a
+   * `read(offset)` resume — never a transport-local counter — so a reconnect
+   * resumes against the real backend key space:
+   *
+   * - {@link memoryStream} tags **every** chunk (`runId@seq`), because its log
+   *   is per-chunk addressable.
+   * - `durableStream` also tags **every** chunk: it POSTs chunks one-by-one and
+   *   reads back each chunk's own backend offset, so the returned array is fully
+   *   populated (no `undefined`) and a mid-batch reconnect resumes at the exact
+   *   chunk it dropped on — exactly-once at any batch size.
+   *
+   * A backend that could only learn a coarser (e.g. per-batch) offset would
+   * return `undefined` for the untagged chunks; the client then relies on
+   * id-keyed de-dup for a partial replay. Prefer per-chunk tagging so exactly-
+   * once does not depend on client de-dup.
+   */
+  append: (
+    chunks: Array<StreamChunk>,
+    startSeq: number,
+  ) => Promise<Array<string | undefined>>
+  /**
+   * Replay the chunks strictly after `offset`. Pass `-1` (or an offset whose
+   * seq is `-1`) to replay from the start. Yields `{ seq, chunk }` in order.
+   *
+   * An optional `signal` bounds a live-tailing read: when it aborts, the read
+   * stops waiting for further appends and ends. Without it, a join to a runId
+   * with no in-process producer (a crash, a cross-instance run, or a bogus id)
+   * would park forever.
+   */
+  read: (
+    offset: string,
+    signal?: AbortSignal,
+  ) => AsyncIterable<{ seq: number; chunk: StreamChunk }>
+  /**
+   * Mark the run terminated so a concurrently live-tailing {@link read} (a
+   * mid-stream join / reconnect) stops waiting for further appends and returns.
+   * Called by the producer when the source stream ends — whether it ended with
+   * a terminal event, a thrown error, or simply ran dry. Optional: backends
+   * that detect completion from the stored terminal event (or their own
+   * close signal) need not implement it.
+   */
+  markComplete?: () => void
+}
+
+/**
+ * Encode a durability offset. The format is `runId@seq`; the seq may be a
+ * 1-based sequence number, or the sentinel `-1` (from start) / `now` (tail).
+ */
+export function encodeOffset(runId: string, seq: number | 'now'): string {
+  return `${runId}@${seq}`
+}
+
+/**
+ * The seq token of an offset — the substring after the LAST `@`, or the whole
+ * string when there is no `@` (a bare seq token).
+ */
+function seqTokenOf(offset: string): string {
+  return offset.includes('@')
+    ? offset.slice(offset.lastIndexOf('@') + 1)
+    : offset
+}
+
+/**
+ * Parse a seq token into its numeric value. The sentinels agree with
+ * {@link seqThreshold}: `-1` / `''` (from start) → `-1`, `now` (tail) →
+ * `+Infinity`. Throws only on a genuinely malformed (non-sentinel,
+ * non-numeric) token — never on a sentinel.
+ */
+function parseSeqToken(token: string): number {
+  if (token === '' || token === '-1') return -1
+  if (token === 'now') return Number.POSITIVE_INFINITY
+  const n = Number(token)
+  if (!Number.isFinite(n)) {
+    throw new Error(`Invalid durability offset seq: ${token}`)
+  }
+  return n
+}
+
+/**
+ * The run id of a `runId@seq` offset — everything before the LAST `@`, so run
+ * ids that themselves contain `@` round-trip. Deliberately does NOT parse the
+ * seq, so the sentinels `now` / `-1` (and any future seq form) never make run
+ * id extraction throw. When there is no `@`, the whole string is the run id.
+ */
+export function runIdOf(offset: string): string {
+  const at = offset.lastIndexOf('@')
+  return at === -1 ? offset : offset.slice(0, at)
+}
+
+/**
+ * Decode a `runId@seq` offset. Splits on the LAST `@` so run ids that
+ * themselves contain `@` round-trip. The seq is parsed via the shared sentinel
+ * logic, so `runId@now` (→ `+Infinity`) and `runId@-1` (→ `-1`) decode without
+ * throwing; only a missing `@` or a non-sentinel non-numeric seq throws.
+ */
+export function decodeOffset(offset: string): { runId: string; seq: number } {
+  const at = offset.lastIndexOf('@')
+  if (at === -1) {
+    throw new Error(`Invalid durability offset (missing @): ${offset}`)
+  }
+  return {
+    runId: offset.slice(0, at),
+    seq: parseSeqToken(offset.slice(at + 1)),
+  }
+}
+
+/**
+ * Resolve the seq threshold a `read(offset)` should replay strictly after.
+ * Understands full `runId@seq` offsets and bare seq tokens, plus the sentinels
+ * `-1` (from start; threshold `-1` so every 1-based seq qualifies) and `now`
+ * (tail → `+Infinity`, so no already-stored chunk qualifies).
+ */
+function seqThreshold(offset: string): number {
+  return parseSeqToken(seqTokenOf(offset))
+}
+
+/**
+ * Reject a run id that would break SSE framing if it flowed into an `id:` line.
+ * A caller-supplied `?runId` (or a reconnect `Last-Event-ID`) is untrusted; a
+ * CR/LF in it could inject or split SSE events once it is emitted as
+ * `id: {runId}@{seq}`. Throws rather than silently sanitizing.
+ */
+function assertValidRunId(runId: string): string {
+  if (/[\r\n]/.test(runId)) {
+    throw new Error(
+      `Invalid runId (must not contain CR/LF): ${JSON.stringify(runId)}`,
+    )
+  }
+  return runId
+}
+
+function readResumeOffset(request: Request): string | null {
+  const header = request.headers.get('Last-Event-ID')
+  if (header) return header
+  try {
+    const param = new URL(request.url).searchParams.get('offset')
+    if (param) return param
+  } catch {
+    // A relative / opaque URL has no query string to parse — treat as fresh.
+  }
+  return null
+}
+
+function runIdFor(request: Request, resumeOffset: string | null): string {
+  if (resumeOffset && resumeOffset.includes('@')) {
+    // Extract without parsing the seq, so a `runId@now` / `runId@-1` sentinel
+    // resume offset yields the run id instead of throwing.
+    return assertValidRunId(runIdOf(resumeOffset))
+  }
+  try {
+    const param = new URL(request.url).searchParams.get('runId')
+    if (param) return assertValidRunId(param)
+  } catch (err) {
+    // Re-throw a CR/LF rejection; swallow only the URL-parse failure (a
+    // relative / opaque URL has no query string) and fall through to minting.
+    if (err instanceof Error && err.message.startsWith('Invalid runId')) {
+      throw err
+    }
+  }
+  return crypto.randomUUID()
+}
+
+/** Terminal chunk types after which a run's delivery log is complete. */
+function isTerminalChunk(chunk: StreamChunk): boolean {
+  return chunk.type === 'RUN_FINISHED' || chunk.type === 'RUN_ERROR'
+}
+
+/**
+ * One run's in-process delivery log: the ordered entries, a `complete` flag
+ * (set once the run terminates), and the waiters a live-tailing `read` parks on
+ * until the next append or completion.
+ */
+interface MemoryLog {
+  entries: Array<{ seq: number; chunk: StreamChunk }>
+  complete: boolean
+  waiters: Array<() => void>
+}
+
+/**
+ * Process-local delivery log, shared across requests so a second tab / reconnect
+ * hitting the same server instance can replay an in-flight or finished run.
+ *
+ * ponytail: process-local map, dev/test backend only. It is NOT durable across
+ * restarts and NOT shared across instances — production uses `durableStream`
+ * (the durable-streams protocol adapter) instead.
+ */
+const memoryLogs = new Map<string, MemoryLog>()
+
+function getOrCreateLog(id: string): MemoryLog {
+  let log = memoryLogs.get(id)
+  if (!log) {
+    log = { entries: [], complete: false, waiters: [] }
+    memoryLogs.set(id, log)
+  }
+  return log
+}
+
+/** Wake every waiter parked on a live-tailing read of this log. */
+function wakeWaiters(log: MemoryLog): void {
+  const waiters = log.waiters
+  log.waiters = []
+  for (const wake of waiters) wake()
+}
+
+/**
+ * The zero-infrastructure {@link StreamDurability} backend: an in-process log.
+ *
+ * Perfect for local dev and tests — a reconnect or second tab that reaches the
+ * same process replays the ordered stream. It does NOT survive a restart and is
+ * NOT shared across server instances; swap in `durableStream` from
+ * `@tanstack/ai-durable-stream` for production.
+ */
+export function memoryStream(request: Request): StreamDurability {
+  const resumeOffset = readResumeOffset(request)
+  let cachedRunId: string | undefined
+
+  const runId = (): string => {
+    if (cachedRunId === undefined) {
+      cachedRunId = runIdFor(request, resumeOffset)
+    }
+    return cachedRunId
+  }
+
+  return {
+    resumeFrom: () => resumeOffset,
+    runId,
+    append: async (chunks, startSeq) => {
+      const id = runId()
+      const log = getOrCreateLog(id)
+      // Every chunk is per-chunk addressable in this log's own key space, so
+      // tag each with its `runId@seq` offset — that IS the offset a resumer
+      // passes back to `read`.
+      const offsets = chunks.map((chunk, i) => {
+        const seq = startSeq + i
+        log.entries.push({ seq, chunk })
+        if (isTerminalChunk(chunk)) log.complete = true
+        return encodeOffset(id, seq)
+      })
+      wakeWaiters(log)
+      return offsets
+    },
+    markComplete: () => {
+      const log = getOrCreateLog(runId())
+      log.complete = true
+      wakeWaiters(log)
+    },
+    read: async function* (offset, signal) {
+      const id = runId()
+      const threshold = seqThreshold(offset)
+      const log = getOrCreateLog(id)
+      // Live-tail: drain everything currently past the threshold, then park on
+      // the next append until a terminal chunk is read or the run is marked
+      // complete. Without this, a mid-stream join returns at the current tail
+      // BEFORE the run finishes, truncating the joiner's view.
+      let index = 0
+      for (;;) {
+        while (index < log.entries.length) {
+          const entry = log.entries[index]
+          index += 1
+          if (entry && entry.seq > threshold) {
+            yield entry
+            if (isTerminalChunk(entry.chunk)) return
+          }
+        }
+        if (log.complete) return
+        // A consumer that already aborted must not park.
+        if (signal?.aborted) return
+        // Park until the next append / completion, OR the consumer aborts.
+        // Threading the abort wake is what stops a join to a runId with no
+        // in-process producer (crash, cross-instance, or bogus id) — whose log
+        // is created empty here and never gets a `markComplete` — from parking
+        // forever: the caller bounds it with its request/consumer signal.
+        await new Promise<void>((resolve) => {
+          const onAbort = () => {
+            const i = log.waiters.indexOf(wake)
+            if (i !== -1) log.waiters.splice(i, 1)
+            resolve()
+          }
+          const wake = () => {
+            signal?.removeEventListener('abort', onAbort)
+            resolve()
+          }
+          log.waiters.push(wake)
+          signal?.addEventListener('abort', onAbort)
+        })
+        if (signal?.aborted) return
+      }
+    },
+  }
+}
diff --git a/packages/ai/src/stream-to-response.ts b/packages/ai/src/stream-to-response.ts
index 9850f4d60..07b7fb56e 100644
--- a/packages/ai/src/stream-to-response.ts
+++ b/packages/ai/src/stream-to-response.ts
@@ -1,4 +1,6 @@
 import { toRunErrorPayload } from './activities/error-payload'
+import { encodeOffset } from './stream-durability'
+import type { StreamDurability } from './stream-durability'
 import type { StreamChunk } from './types'
 
 /**
@@ -50,21 +52,31 @@ export async function streamToText(
 export function toServerSentEventsStream(
   stream: AsyncIterable<StreamChunk>,
   abortController?: AbortController,
+  getId?: (chunk: StreamChunk, index: number) => string | undefined,
 ): ReadableStream<Uint8Array> {
   const encoder = new TextEncoder()
 
   return new ReadableStream({
     async start(controller) {
       try {
+        let index = 0
         for await (const chunk of stream) {
           // Check if stream was cancelled/aborted
           if (abortController?.signal.aborted) {
             break
           }
 
+          // Tag the event with an `id:` line when a resolver is supplied
+          // (delivery durability offsets). Native `EventSource` echoes the
+          // last `id:` back as `Last-Event-ID` on reconnect, which is how
+          // resume works with zero client-side cursor state.
+          const id = getId?.(chunk, index)
+          index += 1
+          const idLine = id !== undefined ? `id: ${id}\n` : ''
+
           // Send each chunk as Server-Sent Events format
           controller.enqueue(
-            encoder.encode(`data: ${JSON.stringify(chunk)}\n\n`),
+            encoder.encode(`${idLine}data: ${JSON.stringify(chunk)}\n\n`),
           )
         }
 
@@ -99,6 +111,147 @@ export function toServerSentEventsStream(
   })
 }
 
+/** Default number of chunks buffered before a durability `append`. */
+const DEFAULT_DURABILITY_BATCH = 32
+
+/**
+ * Resolve and validate the durability batch size. A non-positive-integer (0,
+ * negative, fractional, or `NaN`) is rejected rather than clamped: silently
+ * `Math.max(1, …)`-ing a `NaN` used to disable size-based flushing entirely
+ * (`length >= NaN` is always false), which is a subtle footgun.
+ */
+function resolveBatchSize(batch: number | undefined): number {
+  if (batch === undefined) return DEFAULT_DURABILITY_BATCH
+  if (!Number.isInteger(batch) || batch <= 0) {
+    throw new Error(
+      `Invalid durability batch size: ${batch}. Must be a positive integer.`,
+    )
+  }
+  return batch
+}
+
+/**
+ * Boundaries at which the batching producer flushes early, regardless of the
+ * batch size — terminal events and tool-call ends. Flushing here keeps the
+ * durability log promptly consistent at semantically meaningful points.
+ */
+function isDurabilityFlushBoundary(chunk: StreamChunk): boolean {
+  return (
+    chunk.type === 'RUN_FINISHED' ||
+    chunk.type === 'RUN_ERROR' ||
+    chunk.type === 'TOOL_CALL_END'
+  )
+}
+
+/**
+ * Build the delivery-durable source iterable for a transport helper.
+ *
+ * - **Resume** (`resumeFrom()` non-null): replay strictly after the offset,
+ *   reading only from the durability log. The input `stream` is NEVER iterated,
+ *   so `chat()`'s lazy iterator never fires the provider — the untouched
+ *   generator is simply GC'd. This is what makes resume free of re-invocation.
+ * - **Fresh** (`resumeFrom()` null): iterate `stream`, buffering up to `batch`
+ *   chunks (flushing early at terminal / tool-call boundaries), `append` each
+ *   batch to the log, then forward. Appending BEFORE forwarding guarantees a
+ *   reconnecting client can always replay exactly what it already saw.
+ *
+ * The returned `getId` maps each forwarded chunk to its `runId@seq` offset, for
+ * the SSE `id:` line (ignored by the ndjson HTTP helper).
+ */
+function durableStreamSource(
+  stream: AsyncIterable<StreamChunk>,
+  durability: StreamDurability,
+  options: { abortController?: AbortController; batch?: number },
+): {
+  source: AsyncIterable<StreamChunk>
+  getId: (chunk: StreamChunk) => string | undefined
+} {
+  const runId = durability.runId()
+  const resumeOffset = durability.resumeFrom()
+  const batchSize = resolveBatchSize(options.batch)
+  const abortController = options.abortController
+  const idByChunk = new WeakMap<object, string>()
+  const getId = (chunk: StreamChunk): string | undefined => idByChunk.get(chunk)
+
+  async function* produce(): AsyncIterable<StreamChunk> {
+    let seq = 1
+    let batch: Array<StreamChunk> = []
+    let batchStart = 1
+
+    async function* flush(): AsyncIterable<StreamChunk> {
+      if (batch.length === 0) return
+      const toForward = batch
+      batch = []
+      // Tag each forwarded chunk's client-facing SSE `id:` with the offset the
+      // BACKEND returned for it — never a transport-local counter. On resume
+      // the backend derives seq from this id, so the two must be the same key
+      // space. Both bundled backends tag every chunk (`memoryStream` per-chunk;
+      // `durableStream` POSTs chunks one-by-one for a per-chunk offset), so a
+      // mid-batch reconnect resumes exactly-once. A backend that returned
+      // `undefined` for some chunks would leave those without an `id:`.
+      const offsets = await durability.append(toForward, batchStart)
+      toForward.forEach((chunk, i) => {
+        const offset = offsets[i]
+        if (offset !== undefined) idByChunk.set(chunk, offset)
+      })
+      for (const chunk of toForward) yield chunk
+    }
+
+    try {
+      for await (const chunk of stream) {
+        if (abortController?.signal.aborted) break
+        if (batch.length === 0) batchStart = seq
+        batch.push(chunk)
+        seq += 1
+        if (batch.length >= batchSize || isDurabilityFlushBoundary(chunk)) {
+          yield* flush()
+        }
+      }
+      yield* flush()
+    } catch (error) {
+      // The provider stream threw. Persist a terminal RUN_ERROR to the
+      // durability log so a resumer / joiner learns the run failed (otherwise
+      // the log ends with no terminal and they wait forever). Flush any
+      // buffered chunks first, then append the terminal WITHOUT forwarding it
+      // live — the transport layer synthesizes the live RUN_ERROR on rethrow,
+      // so forwarding here too would double-emit.
+      yield* flush()
+      if (!abortController?.signal.aborted) {
+        const errorChunk = {
+          type: 'RUN_ERROR',
+          timestamp: Date.now(),
+          error: toRunErrorPayload(error),
+        } as StreamChunk
+        await durability.append([errorChunk], seq)
+      }
+      throw error
+    } finally {
+      // Unblock any live-tailing join, however the run ended (terminal, thrown,
+      // or a source that simply ran dry with no terminal event).
+      durability.markComplete?.()
+    }
+  }
+
+  async function* replay(offset: string): AsyncIterable<StreamChunk> {
+    // Thread the consumer's abort signal into the read so a live-tailing join
+    // (a mid-stream reconnect) that is aborted — or that hit a runId with no
+    // in-process producer — stops parking and ends instead of hanging forever.
+    for await (const { seq, chunk } of durability.read(
+      offset,
+      abortController?.signal,
+    )) {
+      if (abortController?.signal.aborted) break
+      idByChunk.set(chunk, encodeOffset(runId, seq))
+      yield chunk
+    }
+  }
+
+  return {
+    source: resumeOffset !== null ? replay(resumeOffset) : produce(),
+    getId,
+  }
+}
+
 /**
  * Convert a StreamChunk async iterable to a Response in Server-Sent Events format
  *
@@ -107,21 +260,30 @@ export function toServerSentEventsStream(
  * - Each chunk is followed by "\n\n"
  * - Stream ends when the underlying iterable is exhausted (RUN_FINISHED is the terminal event)
  *
+ * Pass a `durability` sink (`memoryStream(request)` / `durableStream(request)`)
+ * to make the stream resumable: fresh runs are appended to the log and each SSE
+ * event is tagged with an `id:` offset; a reconnect (native `Last-Event-ID`) or
+ * a `?offset` join replays from the log without re-running the producer. `batch`
+ * controls how many chunks are buffered per `append` (default 32).
+ *
  * @param stream - AsyncIterable of StreamChunks from chat()
- * @param init - Optional Response initialization options (including `abortController`)
+ * @param init - Optional Response initialization options (including `abortController`, `durability`, `batch`)
  * @returns Response in Server-Sent Events format
  *
  * @example
  * ```typescript
- * const stream = chat({ adapter: openaiText(), model: "gpt-4o", messages: [...] });
- * return toServerSentEventsResponse(stream, { abortController });
+ * const stream = chat({ adapter: openaiText(), model: "gpt-5.5", messages: [...] });
+ * return toServerSentEventsResponse(stream, { durability: { adapter: memoryStream(request) } });
  * ```
  */
 export function toServerSentEventsResponse(
   stream: AsyncIterable<StreamChunk>,
-  init?: ResponseInit & { abortController?: AbortController },
+  init?: ResponseInit & {
+    abortController?: AbortController
+    durability?: { adapter: StreamDurability; batch?: number }
+  },
 ): Response {
-  const { headers, abortController, ...responseInit } = init ?? {}
+  const { headers, abortController, durability, ...responseInit } = init ?? {}
 
   // Start with default SSE headers
   const mergedHeaders = new Headers({
@@ -139,7 +301,18 @@ export function toServerSentEventsResponse(
     })
   }
 
-  return new Response(toServerSentEventsStream(stream, abortController), {
+  let body: ReadableStream<Uint8Array>
+  if (durability) {
+    const { source, getId } = durableStreamSource(stream, durability.adapter, {
+      abortController,
+      batch: durability.batch,
+    })
+    body = toServerSentEventsStream(source, abortController, getId)
+  } else {
+    body = toServerSentEventsStream(stream, abortController)
+  }
+
+  return new Response(body, {
     ...responseInit,
     headers: mergedHeaders,
   })
@@ -227,21 +400,40 @@ export function toHttpStream(
  *
  * This format is compatible with `fetchHttpStream` connection adapter.
  *
+ * Pass a `durability` sink to make the stream resumable (same semantics as
+ * {@link toServerSentEventsResponse}); ndjson carries no `id:` line, so this
+ * relies on the `?offset` query param rather than native `Last-Event-ID`.
+ *
  * @param stream - AsyncIterable of StreamChunks from chat()
- * @param init - Optional Response initialization options (including `abortController`)
+ * @param init - Optional Response initialization options (including `abortController`, `durability`, `batch`)
  * @returns Response in HTTP stream format (newline-delimited JSON)
  *
  * @example
  * ```typescript
- * const stream = chat({ adapter: openaiText(), model: "gpt-4o", messages: [...] });
- * return toHttpResponse(stream, { abortController });
+ * const stream = chat({ adapter: openaiText(), model: "gpt-5.5", messages: [...] });
+ * return toHttpResponse(stream, { durability: { adapter: memoryStream(request) } });
  * ```
  */
 export function toHttpResponse(
   stream: AsyncIterable<StreamChunk>,
-  init?: ResponseInit & { abortController?: AbortController },
+  init?: ResponseInit & {
+    abortController?: AbortController
+    durability?: { adapter: StreamDurability; batch?: number }
+  },
 ): Response {
-  return new Response(toHttpStream(stream, init?.abortController), {
-    ...init,
+  const { abortController, durability, ...responseInit } = init ?? {}
+
+  const body = durability
+    ? toHttpStream(
+        durableStreamSource(stream, durability.adapter, {
+          abortController,
+          batch: durability.batch,
+        }).source,
+        abortController,
+      )
+    : toHttpStream(stream, abortController)
+
+  return new Response(body, {
+    ...responseInit,
   })
 }
diff --git a/packages/ai/src/types.ts b/packages/ai/src/types.ts
index 6917c8140..cbff017b5 100644
--- a/packages/ai/src/types.ts
+++ b/packages/ai/src/types.ts
@@ -18,6 +18,7 @@ import type {
 import type {
   BaseEvent as AGUIBaseEvent,
   CustomEvent as AGUICustomEvent,
+  Interrupt as AGUIInterrupt,
   MessagesSnapshotEvent as AGUIMessagesSnapshotEvent,
   ReasoningEncryptedValueEvent as AGUIReasoningEncryptedValueEvent,
   ReasoningEndEvent as AGUIReasoningEndEvent,
@@ -25,8 +26,10 @@ import type {
   ReasoningMessageEndEvent as AGUIReasoningMessageEndEvent,
   ReasoningMessageStartEvent as AGUIReasoningMessageStartEvent,
   ReasoningStartEvent as AGUIReasoningStartEvent,
+  ResumeEntry as AGUIResumeEntry,
   RunErrorEvent as AGUIRunErrorEvent,
   RunFinishedEvent as AGUIRunFinishedEvent,
+  RunFinishedOutcome as AGUIRunFinishedOutcome,
   RunStartedEvent as AGUIRunStartedEvent,
   StateDeltaEvent as AGUIStateDeltaEvent,
   StateSnapshotEvent as AGUIStateSnapshotEvent,
@@ -970,6 +973,13 @@ export interface TextOptions<
    */
   parentRunId?: string
 
+  /**
+   * AG-UI interrupt resume responses supplied by the client on a follow-up run.
+   * Threaded through request parsing now so later runtime behavior can resolve
+   * upstream-native interrupts.
+   */
+  resume?: Array<RunAgentResumeItem>
+
   /**
    * Middleware capability context for this run. The engine populates it with
    * the live middleware context so harness adapters that declare
@@ -1059,6 +1069,12 @@ export type {
  */
 export type UsageTotals = TokenUsage
 
+export type Interrupt = AGUIInterrupt
+
+export type RunFinishedOutcome = AGUIRunFinishedOutcome
+
+export type RunAgentResumeItem = AGUIResumeEntry
+
 /**
  * Emitted when a run completes successfully.
  *
@@ -1483,11 +1499,15 @@ export type ChatStream = AsyncIterable<
 /**
  * Public type for streams returned by `chat({ outputSchema, stream: true })`.
  *
- * Yields all standard `StreamChunk` lifecycle events plus the three tagged
- * `CUSTOM` events the orchestrator can emit through this path:
+ * Yields all standard `StreamChunk` lifecycle events plus the typed
+ * structured-output `CUSTOM` event emitted through this path:
  * - `structured-output.complete` — terminal event with typed `value.object: T`
- * - `approval-requested` — server tool needs approval (pauses the run)
- * - `tool-input-available` — client tool invocation (pauses the run)
+ *
+ * User-actionable waits, such as tool approval and client tool input, are
+ * represented by `RUN_FINISHED.outcome.type === 'interrupt'` in current core
+ * streams. Legacy `approval-requested` and `tool-input-available` custom
+ * events may still be consumed for replay and backward compatibility, but
+ * they are not the current source of truth for waits.
  *
  * Each variant has a literal `name`, so a single discriminated narrow gives
  * you a typed `value` with no helper or cast:
@@ -1496,8 +1516,6 @@ export type ChatStream = AsyncIterable<
  * for await (const chunk of stream) {
  *   if (chunk.type === 'CUSTOM' && chunk.name === 'structured-output.complete') {
  *     chunk.value.object // typed as T
- *   } else if (chunk.type === 'CUSTOM' && chunk.name === 'approval-requested') {
- *     chunk.value.toolCallId // typed as string
  *   }
  * }
  * ```
@@ -1808,6 +1826,36 @@ export type GeneratedMediaSource =
       url?: never
     }
 
+export type PersistedArtifactRole = 'input' | 'output'
+
+export type PersistedArtifactActivity =
+  | 'image'
+  | 'audio'
+  | 'tts'
+  | 'video'
+  | 'transcription'
+
+export interface PersistedArtifactRef {
+  role: PersistedArtifactRole
+  artifactId: string
+  threadId: string
+  runId: string
+  name: string
+  mimeType: string
+  size: number
+  createdAt: string
+  externalUrl?: string
+  source: {
+    activity: PersistedArtifactActivity
+    path: string
+    provider: string
+    model: string
+    mediaType?: 'image' | 'audio' | 'video' | 'document' | 'json'
+    jobId?: string
+    expiresAt?: string
+  }
+}
+
 /**
  * A single generated image
  */
@@ -1828,6 +1876,8 @@ export interface ImageGenerationResult {
   images: Array<GeneratedImage>
   /** Token usage information (if available) */
   usage?: TokenUsage
+  /** Persisted artifact references for generated assets, when available */
+  artifacts?: Array<PersistedArtifactRef>
 }
 
 // ============================================================================
@@ -1879,6 +1929,8 @@ export interface AudioGenerationResult {
   audio: GeneratedAudio
   /** Token usage information (if available) */
   usage?: TokenUsage
+  /** Persisted artifact references for generated assets, when available */
+  artifacts?: Array<PersistedArtifactRef>
 }
 
 // ============================================================================
@@ -1970,6 +2022,8 @@ export interface VideoUrlResult {
    * real billed quantity — so consumers can compute exact cost.
    */
   usage?: TokenUsage
+  /** Persisted artifact references for generated assets, when available */
+  artifacts?: Array<PersistedArtifactRef>
 }
 
 // ============================================================================
@@ -2019,6 +2073,8 @@ export interface TTSResult {
   contentType?: string
   /** Token usage information (if provided by the adapter) */
   usage?: TokenUsage
+  /** Persisted artifact references for generated assets, when available */
+  artifacts?: Array<PersistedArtifactRef>
 }
 
 // ============================================================================
@@ -2109,6 +2165,8 @@ export interface TranscriptionResult {
   words?: Array<TranscriptionWord>
   /** Token usage information (if provided by the adapter) */
   usage?: TokenUsage
+  /** Persisted artifact references for generated assets, when available */
+  artifacts?: Array<PersistedArtifactRef>
 }
 
 /**
diff --git a/packages/ai/src/utilities/chat-params.ts b/packages/ai/src/utilities/chat-params.ts
index fd70872da..2370d0efd 100644
--- a/packages/ai/src/utilities/chat-params.ts
+++ b/packages/ai/src/utilities/chat-params.ts
@@ -3,6 +3,7 @@ import type { Context as AGUIContext } from '@ag-ui/core'
 import type {
   JSONSchema,
   ModelMessage,
+  RunAgentResumeItem,
   SchemaInput,
   Tool,
   UIMessage,
@@ -38,7 +39,7 @@ function isValidParts(value: unknown): value is Array<{ type: string }> {
  * reasoning/activity/developer-role normalization internally.
  *
  * @throws An error with a migration-pointing message when the body does
- *   not conform to AG-UI 0.0.52 `RunAgentInputSchema`. Surface this as a
+ *   not conform to AG-UI `RunAgentInputSchema`. Surface this as a
  *   400 Bad Request to the client.
  */
 export function chatParamsFromRequestBody(body: unknown): Promise<{
@@ -49,6 +50,7 @@ export function chatParamsFromRequestBody(body: unknown): Promise<{
   tools: Array<{ name: string; description: string; parameters: JSONSchema }>
   forwardedProps: Record<string, unknown>
   state: unknown
+  resume?: Array<RunAgentResumeItem>
   /**
    * @deprecated Use `aguiContext` instead. This alias will be removed in a
    * future release.
@@ -101,6 +103,7 @@ export function chatParamsFromRequestBody(body: unknown): Promise<{
     }>,
     forwardedProps: (parsed.forwardedProps ?? {}) as Record<string, unknown>,
     state: parsed.state,
+    resume: parsed.resume,
     context: aguiContext,
     aguiContext,
   })
diff --git a/packages/ai/tests/chat-params.test.ts b/packages/ai/tests/chat-params.test.ts
index 3ecde911b..d9f35166f 100644
--- a/packages/ai/tests/chat-params.test.ts
+++ b/packages/ai/tests/chat-params.test.ts
@@ -22,6 +22,17 @@ describe('chatParamsFromRequestBody', () => {
     tools: [],
     context: [],
     forwardedProps: { temperature: 0.7 },
+    resume: [
+      {
+        interruptId: 'interrupt-1',
+        status: 'resolved',
+        payload: { approved: true },
+      },
+      {
+        interruptId: 'interrupt-2',
+        status: 'cancelled',
+      },
+    ],
   }
 
   it('returns parsed fields verbatim on a valid body', async () => {
@@ -33,6 +44,17 @@ describe('chatParamsFromRequestBody', () => {
     expect(result.forwardedProps).toEqual({ temperature: 0.7 })
     expect(result.aguiContext).toEqual([])
     expect(result.context).toBe(result.aguiContext)
+    // Delivery cursor is gone — request parsing never surfaces a `cursor`.
+    expect('cursor' in result).toBe(false)
+    expect(result.resume).toEqual(validBody.resume)
+  })
+
+  it('ignores any `cursor` field on the body (delivery cursor removed)', async () => {
+    const result = await chatParamsFromRequestBody({
+      ...validBody,
+      cursor: 'cursor-1',
+    })
+    expect('cursor' in result).toBe(false)
   })
 
   it('preserves the `parts` field on messages (AG-UI strip mode tolerates extras in raw JSON)', async () => {
diff --git a/packages/ai/tests/chat.test.ts b/packages/ai/tests/chat.test.ts
index a9ae8c97c..c92169229 100644
--- a/packages/ai/tests/chat.test.ts
+++ b/packages/ai/tests/chat.test.ts
@@ -22,6 +22,17 @@ function lazyServerTool(name: string, executeFn: (args: any) => any): Tool {
   }
 }
 
+function expectSingleRunFinished(
+  chunks: Array<StreamChunk>,
+): Extract<StreamChunk, { type: 'RUN_FINISHED' }> {
+  const terminals = chunks.filter(
+    (chunk): chunk is Extract<StreamChunk, { type: 'RUN_FINISHED' }> =>
+      chunk.type === 'RUN_FINISHED',
+  )
+  expect(terminals).toHaveLength(1)
+  return terminals[0]!
+}
+
 // ============================================================================
 // Tests
 // ============================================================================
@@ -409,7 +420,7 @@ describe('chat()', () => {
   // Client tools (no execute)
   // ==========================================================================
   describe('client tools (no execute)', () => {
-    it('should yield CUSTOM tool-input-available event for client tools', async () => {
+    it('should yield an interrupt outcome for client tools', async () => {
       const { adapter } = createMockAdapter({
         iterations: [
           [
@@ -429,17 +440,89 @@ describe('chat()', () => {
 
       const chunks = await collectChunks(stream as AsyncIterable<StreamChunk>)
 
-      // Should yield a CUSTOM event for tool-input-available
-      const customChunks = chunks.filter(
-        (c) =>
-          c.type === 'CUSTOM' && (c as any).name === 'tool-input-available',
+      const runFinished = expectSingleRunFinished(chunks)
+      expect(runFinished).toMatchObject({
+        type: 'RUN_FINISHED',
+        finishReason: 'tool_calls',
+        outcome: {
+          type: 'interrupt',
+          interrupts: [
+            {
+              id: 'client_tool_call_1',
+              reason: 'client_tool_input',
+              toolCallId: 'call_1',
+              metadata: {
+                kind: 'client_tool',
+                toolName: 'clientSearch',
+                input: { query: 'test' },
+              },
+            },
+          ],
+        },
+      })
+    })
+
+    it('should not run streaming structured-output finalization after a client-tool interrupt', async () => {
+      const structuredOutputSpy = vi.fn().mockResolvedValue({
+        data: { status: 'done' },
+        rawText: '{"status":"done"}',
+      })
+      const { adapter } = createMockAdapter({
+        iterations: [
+          [
+            ev.runStarted(),
+            ev.toolStart('call_1', 'clientSearch'),
+            ev.toolArgs('call_1', '{"query":"test"}'),
+            ev.runFinished('tool_calls'),
+          ],
+        ],
+        structuredOutput: structuredOutputSpy,
+      })
+
+      const stream = chat({
+        adapter,
+        messages: [{ role: 'user', content: 'Search for test' }],
+        tools: [clientTool('clientSearch')],
+        outputSchema: {
+          type: 'object',
+          properties: { status: { type: 'string' } },
+          required: ['status'],
+        },
+        stream: true,
+      })
+
+      const chunks = await collectChunks(
+        stream as unknown as AsyncIterable<StreamChunk>,
       )
-      expect(customChunks).toHaveLength(1)
 
-      const value = (customChunks[0] as any).value
-      expect(value.toolCallId).toBe('call_1')
-      expect(value.toolName).toBe('clientSearch')
-      expect(value.input).toEqual({ query: 'test' })
+      expect(structuredOutputSpy).not.toHaveBeenCalled()
+
+      const runFinished = expectSingleRunFinished(chunks)
+      expect(runFinished.outcome?.type).toBe('interrupt')
+
+      const interruptTerminalIndex = chunks.indexOf(runFinished)
+      const chunksAfterInterrupt = chunks.slice(interruptTerminalIndex + 1)
+      expect(
+        chunksAfterInterrupt.some(
+          (chunk) =>
+            chunk.type === EventType.CUSTOM &&
+            (chunk as { name?: string }).name === 'structured-output.complete',
+        ),
+      ).toBe(false)
+      expect(
+        chunksAfterInterrupt.some(
+          (chunk) =>
+            chunk.type === EventType.CUSTOM &&
+            (chunk as { name?: string }).name === 'structured-output.start',
+        ),
+      ).toBe(false)
+      expect(
+        chunksAfterInterrupt.some(
+          (chunk) =>
+            chunk.type === EventType.RUN_STARTED ||
+            chunk.type === EventType.RUN_FINISHED,
+        ),
+      ).toBe(false)
     })
   })
 
@@ -485,13 +568,36 @@ describe('chat()', () => {
       )
       expect(toolResultChunks).toHaveLength(1)
 
-      // Client tool should get a tool-input-available event
-      const customChunks = chunks.filter(
+      const toolResultIndex = chunks.findIndex(
         (c) =>
-          c.type === 'CUSTOM' && (c as any).name === 'tool-input-available',
+          c.type === 'TOOL_CALL_RESULT' && 'content' in c && (c as any).content,
       )
-      expect(customChunks).toHaveLength(1)
-      expect((customChunks[0] as any).value.toolName).toBe('showNotification')
+      const runFinished = expectSingleRunFinished(chunks)
+      const runFinishedIndex = chunks.indexOf(runFinished)
+      expect(runFinishedIndex).toBeGreaterThan(toolResultIndex)
+      expect(runFinished).toMatchObject({
+        type: 'RUN_FINISHED',
+        outcome: {
+          type: 'interrupt',
+          interrupts: [
+            {
+              reason: 'client_tool_input',
+              toolCallId: 'call_client',
+              metadata: {
+                kind: 'client_tool',
+                toolName: 'showNotification',
+                input: { message: 'done' },
+              },
+            },
+          ],
+        },
+      })
+      expect(
+        chunks.some(
+          (c) =>
+            c.type === 'CUSTOM' && (c as any).name === 'tool-input-available',
+        ),
+      ).toBe(false)
 
       // Adapter called once (waiting for client result, not looping)
       expect(calls).toHaveLength(1)
@@ -550,13 +656,36 @@ describe('chat()', () => {
       )
       expect(toolResultChunks).toHaveLength(1)
 
-      // Client tool should get a tool-input-available event
-      const customChunks = chunks.filter(
+      const toolResultIndex = chunks.findIndex(
         (c) =>
-          c.type === 'CUSTOM' && (c as any).name === 'tool-input-available',
+          c.type === 'TOOL_CALL_RESULT' && 'content' in c && (c as any).content,
       )
-      expect(customChunks).toHaveLength(1)
-      expect((customChunks[0] as any).value.toolName).toBe('showNotification')
+      const runFinished = expectSingleRunFinished(chunks)
+      const runFinishedIndex = chunks.indexOf(runFinished)
+      expect(runFinishedIndex).toBeGreaterThan(toolResultIndex)
+      expect(runFinished).toMatchObject({
+        type: 'RUN_FINISHED',
+        outcome: {
+          type: 'interrupt',
+          interrupts: [
+            {
+              reason: 'client_tool_input',
+              toolCallId: 'call_client',
+              metadata: {
+                kind: 'client_tool',
+                toolName: 'showNotification',
+                input: { message: 'done' },
+              },
+            },
+          ],
+        },
+      })
+      expect(
+        chunks.some(
+          (c) =>
+            c.type === 'CUSTOM' && (c as any).name === 'tool-input-available',
+        ),
+      ).toBe(false)
 
       // Adapter should NOT be called (still waiting for client result)
       expect(calls).toHaveLength(0)
@@ -567,7 +696,7 @@ describe('chat()', () => {
   // Approval flow
   // ==========================================================================
   describe('approval flow', () => {
-    it('should yield CUSTOM approval-requested event for tools with needsApproval', async () => {
+    it('should end with an interrupt outcome for tools with needsApproval', async () => {
       const { adapter } = createMockAdapter({
         iterations: [
           [
@@ -590,18 +719,43 @@ describe('chat()', () => {
 
       const chunks = await collectChunks(stream as AsyncIterable<StreamChunk>)
 
-      const approvalChunks = chunks.filter(
-        (c) => c.type === 'CUSTOM' && (c as any).name === 'approval-requested',
-      )
-      expect(approvalChunks).toHaveLength(1)
+      const runFinished = expectSingleRunFinished(chunks)
+      expect(runFinished).toBeDefined()
+      expect(runFinished).toMatchObject({
+        type: 'RUN_FINISHED',
+        finishReason: 'tool_calls',
+        outcome: {
+          type: 'interrupt',
+          interrupts: [
+            {
+              id: 'approval_call_1',
+              reason: 'approval_required',
+              message: 'Approval required to run dangerousTool',
+              toolCallId: 'call_1',
+              responseSchema: {
+                type: 'object',
+                properties: { approved: { type: 'boolean' } },
+                required: ['approved'],
+              },
+              metadata: {
+                kind: 'approval',
+                toolName: 'dangerousTool',
+                input: { action: 'delete' },
+              },
+            },
+          ],
+        },
+      })
 
-      const value = (approvalChunks[0] as any).value
-      expect(value.toolCallId).toBe('call_1')
-      expect(value.toolName).toBe('dangerousTool')
-      expect(value.approval.needsApproval).toBe(true)
+      expect(
+        chunks.some(
+          (c) =>
+            c.type === 'CUSTOM' && (c as any).name === 'approval-requested',
+        ),
+      ).toBe(false)
     })
 
-    it('should yield CUSTOM approval-requested for client tools with needsApproval', async () => {
+    it('should end with an interrupt outcome for client tools with needsApproval', async () => {
       const { adapter } = createMockAdapter({
         iterations: [
           [
@@ -621,10 +775,99 @@ describe('chat()', () => {
 
       const chunks = await collectChunks(stream as AsyncIterable<StreamChunk>)
 
-      const approvalChunks = chunks.filter(
-        (c) => c.type === 'CUSTOM' && (c as any).name === 'approval-requested',
-      )
-      expect(approvalChunks).toHaveLength(1)
+      const runFinished = expectSingleRunFinished(chunks)
+      expect(runFinished).toMatchObject({
+        type: 'RUN_FINISHED',
+        finishReason: 'tool_calls',
+        outcome: {
+          type: 'interrupt',
+          interrupts: [
+            {
+              id: 'approval_call_1',
+              reason: 'approval_required',
+              toolCallId: 'call_1',
+              metadata: {
+                kind: 'approval',
+                toolName: 'clientDanger',
+                input: {},
+              },
+            },
+          ],
+        },
+      })
+    })
+
+    it('should end with an interrupt outcome for client tool execution waits', async () => {
+      const { adapter } = createMockAdapter({
+        iterations: [
+          [
+            ev.runStarted(),
+            ev.toolStart('call_1', 'clientSearch'),
+            ev.toolArgs('call_1', '{"query":"test"}'),
+            ev.runFinished('tool_calls'),
+          ],
+        ],
+      })
+
+      const stream = chat({
+        adapter,
+        messages: [{ role: 'user', content: 'Search for test' }],
+        tools: [clientTool('clientSearch')],
+      })
+
+      const chunks = await collectChunks(stream as AsyncIterable<StreamChunk>)
+      const runFinished = expectSingleRunFinished(chunks)
+
+      expect(runFinished).toMatchObject({
+        type: 'RUN_FINISHED',
+        finishReason: 'tool_calls',
+        outcome: {
+          type: 'interrupt',
+          interrupts: [
+            {
+              id: 'client_tool_call_1',
+              reason: 'client_tool_input',
+              message: 'Client tool clientSearch is ready to run',
+              toolCallId: 'call_1',
+              metadata: {
+                kind: 'client_tool',
+                toolName: 'clientSearch',
+                input: { query: 'test' },
+              },
+            },
+          ],
+        },
+      })
+      expect(
+        chunks.some(
+          (c) =>
+            c.type === 'CUSTOM' && (c as any).name === 'tool-input-available',
+        ),
+      ).toBe(false)
+    })
+
+    it('should not expose internal lazy-tool waits as interrupts', async () => {
+      const { adapter } = createMockAdapter({
+        iterations: [
+          [
+            ev.runStarted(),
+            ev.toolStart('call_1', 'missingLazyTool'),
+            ev.toolArgs('call_1', '{}'),
+            ev.runFinished('tool_calls'),
+          ],
+          [ev.runStarted(), ev.textContent('done'), ev.runFinished('stop')],
+        ],
+      })
+
+      const stream = chat({
+        adapter,
+        messages: [{ role: 'user', content: 'Use the lazy tool' }],
+        tools: [lazyServerTool('missingLazyTool', () => ({ ok: true }))],
+      })
+
+      const chunks = await collectChunks(stream as AsyncIterable<StreamChunk>)
+      const runFinished = chunks.findLast((c) => c.type === 'RUN_FINISHED')
+      expect((runFinished as any)?.outcome?.type).not.toBe('interrupt')
     })
   })
 
diff --git a/packages/ai/tests/custom-events.test.ts b/packages/ai/tests/custom-events.test.ts
new file mode 100644
index 000000000..6566c0ab8
--- /dev/null
+++ b/packages/ai/tests/custom-events.test.ts
@@ -0,0 +1,52 @@
+import { describe, expect, it } from 'vitest'
+import { CUSTOM_EVENT, isCustomEvent } from '../src/custom-events'
+import { EventType } from '../src/types'
+import type { StreamChunk } from '../src/types'
+
+describe('CUSTOM_EVENT catalog', () => {
+  it('exposes the well-known agent-activity event names', () => {
+    expect(CUSTOM_EVENT.FILE_CHANGED).toBe('file.changed')
+    expect(CUSTOM_EVENT.PROCESS_STDOUT).toBe('process.stdout')
+    expect(CUSTOM_EVENT.PROCESS_STDERR).toBe('process.stderr')
+    expect(CUSTOM_EVENT.PORT_OPENED).toBe('port.opened')
+    expect(CUSTOM_EVENT.APPROVAL_REQUESTED).toBe('approval.requested')
+    expect(CUSTOM_EVENT.APPROVAL_RESOLVED).toBe('approval.resolved')
+    expect(CUSTOM_EVENT.ARTIFACT_CREATED).toBe('artifact.created')
+    expect(CUSTOM_EVENT.SANDBOX_CREATED).toBe('sandbox.created')
+    expect(CUSTOM_EVENT.SANDBOX_RESUMED).toBe('sandbox.resumed')
+  })
+})
+
+describe('isCustomEvent', () => {
+  const fileChanged: StreamChunk = {
+    type: EventType.CUSTOM,
+    name: CUSTOM_EVENT.FILE_CHANGED,
+    value: { type: 'change', path: '/workspace/a.ts', timestamp: 1 },
+    timestamp: 1,
+  }
+
+  it('returns true for a matching CUSTOM event name', () => {
+    expect(isCustomEvent(fileChanged, CUSTOM_EVENT.FILE_CHANGED)).toBe(true)
+  })
+
+  it('returns false for a CUSTOM event with a different name', () => {
+    expect(isCustomEvent(fileChanged, CUSTOM_EVENT.PORT_OPENED)).toBe(false)
+  })
+
+  it('returns false for a non-CUSTOM chunk', () => {
+    const runStarted: StreamChunk = {
+      type: EventType.RUN_STARTED,
+      runId: 'r',
+      threadId: 't',
+      timestamp: 1,
+    }
+    expect(isCustomEvent(runStarted, CUSTOM_EVENT.FILE_CHANGED)).toBe(false)
+  })
+
+  it('narrows the payload type when matched', () => {
+    if (isCustomEvent(fileChanged, CUSTOM_EVENT.FILE_CHANGED)) {
+      // Type-level: value is FileChangedPayload — `.path` is a string.
+      expect(fileChanged.value.path).toBe('/workspace/a.ts')
+    }
+  })
+})
diff --git a/packages/ai/tests/generation-params.test.ts b/packages/ai/tests/generation-params.test.ts
new file mode 100644
index 000000000..0e8924153
--- /dev/null
+++ b/packages/ai/tests/generation-params.test.ts
@@ -0,0 +1,170 @@
+import { describe, expect, expectTypeOf, it } from 'vitest'
+import {
+  generationParamsFromBody,
+  generationParamsFromRequest,
+} from '../src/client'
+
+describe('generation params helpers', () => {
+  it('extracts envelope data and forwarded props separately', () => {
+    const params = generationParamsFromBody('image', {
+      data: { prompt: 'draw a mountain' },
+      forwardedProps: { tenantId: 'acme' },
+      threadId: 'thread-1',
+      runId: 'run-1',
+    })
+
+    expect(params).toEqual({
+      input: { prompt: 'draw a mountain' },
+      forwardedProps: { tenantId: 'acme' },
+      threadId: 'thread-1',
+      runId: 'run-1',
+    })
+  })
+
+  it('throws when an envelope is missing data', () => {
+    expect(() =>
+      generationParamsFromBody('audio', {
+        forwardedProps: { tenantId: 'acme' },
+      }),
+    ).toThrow(/data/)
+  })
+
+  it('treats non-envelope bodies as raw input with empty forwarded props', () => {
+    const params = generationParamsFromBody('tts', {
+      text: 'hello',
+      threadId: 'raw-thread',
+    })
+
+    expect(params).toEqual({
+      input: {
+        text: 'hello',
+        threadId: 'raw-thread',
+      },
+      forwardedProps: {},
+    })
+  })
+
+  it('treats valid raw input with incidental data as raw input', () => {
+    const body = {
+      prompt: 'draw a mountain',
+      data: { traceId: 'trace-1' },
+    }
+
+    expect(generationParamsFromBody('image', body)).toEqual({
+      input: body,
+      forwardedProps: {},
+    })
+  })
+
+  it('treats valid raw input with incidental forwarded props as raw input', () => {
+    const body = {
+      prompt: 'draw a mountain',
+      forwardedProps: { ignored: true },
+    }
+
+    expect(generationParamsFromBody('image', body)).toEqual({
+      input: body,
+      forwardedProps: {},
+    })
+  })
+
+  it('extracts identity only from envelopes', () => {
+    const raw = generationParamsFromBody('video', {
+      prompt: 'launch',
+      runId: 'raw-run',
+    })
+    const envelope = generationParamsFromBody('video', {
+      data: { prompt: 'launch' },
+      runId: 'envelope-run',
+    })
+
+    expect(raw).toEqual({
+      input: { prompt: 'launch', runId: 'raw-run' },
+      forwardedProps: {},
+    })
+    expect(envelope.runId).toBe('envelope-run')
+  })
+
+  it('throws when envelope forwarded props are not an object', () => {
+    expect(() =>
+      generationParamsFromBody('image', {
+        data: { prompt: 'draw a mountain' },
+        forwardedProps: 'invalid',
+      }),
+    ).toThrow(/forwardedProps/)
+  })
+
+  it('throws when envelope identity fields are not strings', () => {
+    expect(() =>
+      generationParamsFromBody('image', {
+        data: { prompt: 'draw a mountain' },
+        threadId: 123,
+      }),
+    ).toThrow(/threadId/)
+    expect(() =>
+      generationParamsFromBody('image', {
+        data: { prompt: 'draw a mountain' },
+        runId: 123,
+      }),
+    ).toThrow(/runId/)
+  })
+
+  it('parses request JSON before extracting params', async () => {
+    const request = new Request('https://example.test/generate', {
+      method: 'POST',
+      body: JSON.stringify({
+        data: { audio: 'base64-audio' },
+        forwardedProps: { locale: 'en' },
+      }),
+    })
+
+    await expect(
+      generationParamsFromRequest('transcription', request),
+    ).resolves.toEqual({
+      input: { audio: 'base64-audio' },
+      forwardedProps: { locale: 'en' },
+    })
+  })
+
+  it('throws a clear error for malformed request JSON', async () => {
+    const request = new Request('https://example.test/generate', {
+      method: 'POST',
+      body: '{',
+    })
+
+    await expect(generationParamsFromRequest('image', request)).rejects.toThrow(
+      /Invalid JSON request body/,
+    )
+  })
+
+  it('throws a clear error for non-object request JSON', async () => {
+    const request = new Request('https://example.test/generate', {
+      method: 'POST',
+      body: JSON.stringify(null),
+    })
+
+    await expect(generationParamsFromRequest('image', request)).rejects.toThrow(
+      /JSON object/,
+    )
+  })
+
+  it('narrows input by generation kind', () => {
+    const image = generationParamsFromBody('image', {
+      data: { prompt: 'draw a mountain' },
+    })
+    const speech = generationParamsFromBody('tts', {
+      data: { text: 'hello' },
+    })
+
+    expectTypeOf(image.input).toHaveProperty('prompt')
+    expectTypeOf(speech.input).toHaveProperty('text')
+
+    if (false) {
+      // @ts-expect-error tts input is not image input
+      expectTypeOf(speech.input).toHaveProperty('prompt')
+
+      // @ts-expect-error kind is required
+      generationParamsFromBody({ data: { prompt: 'draw a mountain' } })
+    }
+  })
+})
diff --git a/packages/ai/tests/generation-result-transforms.test.ts b/packages/ai/tests/generation-result-transforms.test.ts
new file mode 100644
index 000000000..5f746efdf
--- /dev/null
+++ b/packages/ai/tests/generation-result-transforms.test.ts
@@ -0,0 +1,215 @@
+import { describe, expect, it } from 'vitest'
+import {
+  applyGenerationResultTransforms,
+  createGenerationContext,
+  runGenerationStart,
+} from '../src/activities/middleware/run'
+import { generateVideo } from '../src/activities/generateVideo'
+import type { GenerationMiddleware } from '../src/activities/middleware'
+import type { VideoAdapter } from '../src/activities/generateVideo'
+import type { PersistedArtifactRef, StreamChunk } from '../src/types'
+
+describe('applyGenerationResultTransforms', () => {
+  type TestResult = { value: string }
+
+  function createTestContext() {
+    return createGenerationContext({
+      requestId: 'test-request',
+      activity: 'image',
+      provider: 'test-provider',
+      model: 'test-model',
+      createId: (prefix) => `${prefix}-id`,
+    })
+  }
+
+  it('runs transforms in order and passes replacements to later transforms', async () => {
+    const ctx = createTestContext()
+    const calls: Array<string> = []
+    ctx.resultTransforms?.push(
+      (result: TestResult) => {
+        calls.push(`first:${result.value}`)
+        return { value: 'first-replacement' }
+      },
+      (result: TestResult) => {
+        calls.push(`second:${result.value}`)
+        return { value: 'second-replacement' }
+      },
+    )
+
+    const result = await applyGenerationResultTransforms<TestResult>(ctx, {
+      value: 'raw',
+    })
+
+    expect(calls).toEqual(['first:raw', 'second:first-replacement'])
+    expect(result).toEqual({ value: 'second-replacement' })
+  })
+
+  it('keeps the prior result when a transform returns undefined', async () => {
+    const ctx = createTestContext()
+    ctx.resultTransforms?.push(
+      () => ({ value: 'first-replacement' }),
+      () => undefined,
+    )
+
+    const result = await applyGenerationResultTransforms<TestResult>(ctx, {
+      value: 'raw',
+    })
+
+    expect(result).toEqual({ value: 'first-replacement' })
+  })
+
+  it('rejects when a transform throws', async () => {
+    const ctx = createTestContext()
+    const error = new Error('transform failed')
+    ctx.resultTransforms?.push(() => {
+      throw error
+    })
+
+    await expect(
+      applyGenerationResultTransforms<TestResult>(ctx, { value: 'raw' }),
+    ).rejects.toThrow(error)
+  })
+
+  it('lets middleware register transforms on start', async () => {
+    const ctx = createTestContext()
+    const middleware = [
+      {
+        onStart: () => {
+          ctx.resultTransforms?.push((result: TestResult) => ({
+            value: `${result.value}-registered`,
+          }))
+        },
+      },
+    ]
+
+    await runGenerationStart(middleware, ctx)
+
+    await expect(
+      applyGenerationResultTransforms<TestResult>(ctx, { value: 'raw' }),
+    ).resolves.toEqual({ value: 'raw-registered' })
+  })
+
+  it('runs middleware-registered transforms in middleware order', async () => {
+    const ctx = createTestContext()
+    const middleware = [
+      {
+        onStart: () => {
+          ctx.resultTransforms?.push((result: TestResult) => ({
+            value: `${result.value}-first`,
+          }))
+        },
+      },
+      {
+        onStart: () => {
+          ctx.resultTransforms?.push((result: TestResult) => ({
+            value: `${result.value}-second`,
+          }))
+        },
+      },
+    ]
+
+    await runGenerationStart(middleware, ctx)
+
+    await expect(
+      applyGenerationResultTransforms<TestResult>(ctx, { value: 'raw' }),
+    ).resolves.toEqual({ value: 'raw-first-second' })
+  })
+
+  it('lets one middleware register multiple transforms', async () => {
+    const ctx = createTestContext()
+    const middleware = [
+      {
+        onStart: () => {
+          ctx.resultTransforms?.push((result: TestResult) => ({
+            value: `${result.value}-first`,
+          }))
+          ctx.resultTransforms?.push((result: TestResult) => ({
+            value: `${result.value}-second`,
+          }))
+        },
+      },
+    ]
+
+    await runGenerationStart(middleware, ctx)
+
+    await expect(
+      applyGenerationResultTransforms<TestResult>(ctx, { value: 'raw' }),
+    ).resolves.toEqual({ value: 'raw-first-second' })
+  })
+})
+
+describe('generateVideo result transforms', () => {
+  it('preserves transformed fields in streamed generation result payload', async () => {
+    const artifact: PersistedArtifactRef = {
+      role: 'output',
+      artifactId: 'artifact-1',
+      threadId: 'thread-1',
+      runId: 'run-1',
+      name: 'video.mp4',
+      mimeType: 'video/mp4',
+      size: 123,
+      createdAt: '2026-07-06T00:00:00.000Z',
+      source: {
+        activity: 'video',
+        path: 'video',
+        provider: 'test-provider',
+        model: 'test-video-model',
+        mediaType: 'video',
+        jobId: 'transformed-job',
+      },
+    }
+    const adapter: VideoAdapter<string> = {
+      kind: 'video',
+      name: 'test-provider',
+      model: 'test-video-model',
+      '~types': undefined as never,
+      createVideoJob: async () => ({
+        jobId: 'raw-job',
+        model: 'test-video-model',
+      }),
+      getVideoStatus: async () => ({
+        jobId: 'raw-job',
+        status: 'completed',
+      }),
+      getVideoUrl: async () => ({
+        jobId: 'raw-job',
+        url: 'https://example.com/raw.mp4',
+      }),
+      availableDurations: () => ({ kind: 'none' }),
+      snapDuration: () => undefined,
+    }
+    const middleware: Array<GenerationMiddleware> = [
+      {
+        onStart: (ctx) => {
+          ctx.resultTransforms?.push((result) => ({
+            ...result,
+            jobId: 'transformed-job',
+            artifacts: [artifact],
+          }))
+        },
+      },
+    ]
+
+    let terminalResult: StreamChunk | undefined
+    for await (const chunk of generateVideo({
+      adapter,
+      prompt: 'test video',
+      stream: true,
+      pollingInterval: 0,
+      middleware,
+    })) {
+      if (chunk.type === 'CUSTOM' && chunk.name === 'generation:result') {
+        terminalResult = chunk
+        break
+      }
+    }
+
+    expect(terminalResult?.type).toBe('CUSTOM')
+    expect(terminalResult?.value).toEqual({
+      jobId: 'transformed-job',
+      status: 'completed',
+      url: 'https://example.com/raw.mp4',
+      artifacts: [artifact],
+    })
+  })
+})
diff --git a/packages/ai/tests/generation-run-identity-replay.test.ts b/packages/ai/tests/generation-run-identity-replay.test.ts
new file mode 100644
index 000000000..b56ab862b
--- /dev/null
+++ b/packages/ai/tests/generation-run-identity-replay.test.ts
@@ -0,0 +1,538 @@
+import { aiEventClient } from '@tanstack/ai-event-client'
+import { EventType } from '@ag-ui/core'
+import { describe, expect, it, vi } from 'vitest'
+import {
+  generateAudio,
+  generateImage,
+  generateSpeech,
+  generateTranscription,
+  generateVideo,
+  getVideoJobStatus,
+} from '../src'
+import type { AudioAdapter } from '../src/activities/generateAudio'
+import type { ImageAdapter } from '../src/activities/generateImage'
+import type { TTSAdapter } from '../src/activities/generateSpeech'
+import type { TranscriptionAdapter } from '../src/activities/generateTranscription'
+import type { VideoAdapter } from '../src/activities/generateVideo'
+import type {
+  PersistedArtifactRef,
+  StreamChunk,
+  VideoStatusResult,
+} from '../src/types'
+
+async function collect(stream: AsyncIterable<StreamChunk>) {
+  const chunks: Array<StreamChunk> = []
+  for await (const chunk of stream) chunks.push(chunk)
+  return chunks
+}
+
+function chunkSummary(chunk: StreamChunk) {
+  return {
+    type: chunk.type,
+    runId: 'runId' in chunk ? chunk.runId : undefined,
+    threadId: 'threadId' in chunk ? chunk.threadId : undefined,
+  }
+}
+
+const imageAdapterTypes: ImageAdapter<string>['~types'] = {
+  providerOptions: {},
+  modelProviderOptionsByName: {},
+  modelSizeByName: {},
+  modelInputModalitiesByName: {},
+}
+
+const audioAdapterTypes: AudioAdapter<string>['~types'] = {
+  providerOptions: {},
+}
+
+const ttsAdapterTypes: TTSAdapter<string>['~types'] = {
+  providerOptions: {},
+}
+
+const transcriptionAdapterTypes: TranscriptionAdapter<string>['~types'] = {
+  providerOptions: {},
+}
+
+const videoAdapterTypes: VideoAdapter<string>['~types'] = {
+  providerOptions: {},
+  modelProviderOptionsByName: {},
+  modelSizeByName: {},
+  modelInputModalitiesByName: {},
+  modelDurationByName: {},
+}
+
+function createMockVideoAdapter(overrides?: {
+  createVideoJob?: VideoAdapter<string>['createVideoJob']
+  getVideoStatus?: VideoAdapter<string>['getVideoStatus']
+  getVideoUrl?: VideoAdapter<string>['getVideoUrl']
+}): VideoAdapter<string> {
+  return {
+    kind: 'video',
+    name: 'test-video',
+    model: 'test-model',
+    '~types': videoAdapterTypes,
+    availableDurations: () => ({ kind: 'none' }),
+    snapDuration: () => undefined,
+    createVideoJob:
+      overrides?.createVideoJob ??
+      vi.fn(async () => ({
+        jobId: 'job-1',
+        model: 'test-model',
+      })),
+    getVideoStatus:
+      overrides?.getVideoStatus ??
+      vi.fn(
+        async (): Promise<VideoStatusResult> => ({
+          jobId: 'job-1',
+          status: 'completed',
+        }),
+      ),
+    getVideoUrl:
+      overrides?.getVideoUrl ??
+      vi.fn(async () => ({
+        jobId: 'job-1',
+        url: 'https://example.com/video.mp4',
+      })),
+  }
+}
+
+describe('generation run identity and replay', () => {
+  it('passes identity through one-shot generation stream events', async () => {
+    const adapter: ImageAdapter<string> = {
+      kind: 'image',
+      name: 'test-image',
+      model: 'test-model',
+      '~types': imageAdapterTypes,
+      generateImages: vi.fn(async () => ({
+        id: 'img-1',
+        model: 'test-model',
+        images: [{ url: 'https://example.com/image.png' }],
+      })),
+    }
+
+    const chunks = await collect(
+      generateImage({
+        adapter,
+        prompt: 'A mountain',
+        stream: true,
+        threadId: 'thread-1',
+        runId: 'run-1',
+      }),
+    )
+
+    expect(chunks.map(chunkSummary)).toEqual([
+      {
+        type: 'RUN_STARTED',
+        runId: 'run-1',
+        threadId: 'thread-1',
+      },
+      {
+        type: 'CUSTOM',
+        runId: 'run-1',
+        threadId: 'thread-1',
+      },
+      {
+        type: 'RUN_FINISHED',
+        runId: 'run-1',
+        threadId: 'thread-1',
+      },
+    ])
+  })
+
+  it('adds identity metadata to direct generation devtools events', async () => {
+    const emit = vi.spyOn(aiEventClient, 'emit').mockImplementation(() => {})
+    const adapter: AudioAdapter<string> = {
+      kind: 'audio',
+      name: 'test-audio',
+      model: 'test-model',
+      '~types': audioAdapterTypes,
+      generateAudio: vi.fn(async () => ({
+        id: 'audio-1',
+        model: 'test-model',
+        audio: { url: 'https://example.com/audio.mp3' },
+      })),
+    }
+
+    await generateAudio({
+      adapter,
+      prompt: 'drums',
+      threadId: 'thread-a',
+      runId: 'run-a',
+    })
+
+    expect(emit).toHaveBeenCalledWith(
+      'audio:request:started',
+      expect.objectContaining({
+        threadId: 'thread-a',
+        runId: 'run-a',
+      }),
+    )
+    expect(emit).toHaveBeenCalledWith(
+      'audio:request:completed',
+      expect.objectContaining({
+        threadId: 'thread-a',
+        runId: 'run-a',
+      }),
+    )
+  })
+
+  it('passes identity through speech, transcription, and video streams', async () => {
+    const speech = await collect(
+      generateSpeech({
+        adapter: {
+          kind: 'tts',
+          name: 'test-tts',
+          model: 'test-model',
+          '~types': ttsAdapterTypes,
+          generateSpeech: vi.fn(async () => ({
+            id: 'speech-1',
+            model: 'test-model',
+            audio: 'base64',
+            format: 'mp3',
+          })),
+        },
+        text: 'hello',
+        stream: true,
+        threadId: 'thread-s',
+        runId: 'run-s',
+      }),
+    )
+
+    const transcription = await collect(
+      generateTranscription({
+        adapter: {
+          kind: 'transcription',
+          name: 'test-transcription',
+          model: 'test-model',
+          '~types': transcriptionAdapterTypes,
+          transcribe: vi.fn(async () => ({
+            id: 'tx-1',
+            model: 'test-model',
+            text: 'hello',
+          })),
+        },
+        audio: 'base64',
+        stream: true,
+        threadId: 'thread-t',
+        runId: 'run-t',
+      }),
+    )
+
+    const videoAdapter = createMockVideoAdapter()
+
+    const video = await collect(
+      generateVideo({
+        adapter: videoAdapter,
+        prompt: 'test',
+        stream: true,
+        pollingInterval: 0,
+        threadId: 'thread-v',
+        runId: 'run-v',
+      }),
+    )
+
+    expect(speech.map(chunkSummary)).toContainEqual({
+      type: 'CUSTOM',
+      runId: 'run-s',
+      threadId: 'thread-s',
+    })
+    expect(transcription.map(chunkSummary)).toContainEqual({
+      type: 'CUSTOM',
+      runId: 'run-t',
+      threadId: 'thread-t',
+    })
+    expect(video.map(chunkSummary)).toContainEqual({
+      type: 'RUN_FINISHED',
+      runId: 'run-v',
+      threadId: 'thread-v',
+    })
+  })
+
+  it('replays persisted generation events without calling the adapter', async () => {
+    const adapter: ImageAdapter<string> = {
+      kind: 'image',
+      name: 'test-image',
+      model: 'test-model',
+      '~types': imageAdapterTypes,
+      generateImages: vi.fn(async () => {
+        throw new Error('provider should not be called')
+      }),
+    }
+    const replayEvents = [
+      {
+        type: EventType.CUSTOM,
+        name: 'generation:result',
+        value: {
+          id: 'persisted-image',
+          model: 'test-model',
+          images: [{ url: 'https://example.com/persisted.png' }],
+        },
+        runId: 'run-replay',
+        threadId: 'thread-replay',
+      },
+      {
+        type: EventType.RUN_FINISHED,
+        runId: 'run-replay',
+        threadId: 'thread-replay',
+        finishReason: 'stop',
+      },
+    ] satisfies Array<StreamChunk>
+
+    const chunks = await collect(
+      generateImage({
+        adapter,
+        prompt: 'ignored',
+        stream: true,
+        replay: { events: replayEvents },
+      }),
+    )
+
+    expect(adapter.generateImages).not.toHaveBeenCalled()
+    expect(chunks).toEqual(replayEvents)
+  })
+
+  it('returns a replayed final result without running transforms or the adapter', async () => {
+    const adapter: AudioAdapter<string> = {
+      kind: 'audio',
+      name: 'test-audio',
+      model: 'test-model',
+      '~types': audioAdapterTypes,
+      generateAudio: vi.fn(async () => {
+        throw new Error('provider should not be called')
+      }),
+    }
+    const transform = vi.fn((result) => result)
+    const persisted = {
+      id: 'audio-replay',
+      model: 'test-model',
+      audio: { url: 'https://example.com/replayed.mp3' },
+    }
+
+    const result = await generateAudio({
+      adapter,
+      prompt: 'ignored',
+      replay: { result: persisted },
+      middleware: [
+        {
+          onStart: (ctx) => {
+            ctx.resultTransforms?.push(transform)
+          },
+        },
+      ],
+    })
+
+    expect(adapter.generateAudio).not.toHaveBeenCalled()
+    expect(transform).not.toHaveBeenCalled()
+    expect(result).toBe(persisted)
+  })
+
+  it('emits replayed video artifacts before the replayed streaming result without running middleware or the adapter', async () => {
+    const artifact: PersistedArtifactRef = {
+      role: 'output',
+      artifactId: 'artifact-replay',
+      threadId: 'thread-video-replay',
+      runId: 'run-video-replay',
+      name: 'video.mp4',
+      mimeType: 'video/mp4',
+      size: 12,
+      createdAt: '2026-07-06T00:00:00.000Z',
+      source: {
+        activity: 'video',
+        path: 'video',
+        provider: 'test-video',
+        model: 'test-model',
+        mediaType: 'video',
+        jobId: 'job-replay',
+      },
+    }
+    const createVideoJob = vi.fn(async () => {
+      throw new Error('video provider should not be called')
+    })
+    const onStart = vi.fn(() => {
+      throw new Error('middleware should not run for replay')
+    })
+
+    const chunks = await collect(
+      generateVideo({
+        adapter: createMockVideoAdapter({ createVideoJob }),
+        prompt: 'ignored',
+        stream: true,
+        threadId: 'thread-video-replay',
+        runId: 'run-video-replay',
+        replay: {
+          result: {
+            jobId: 'job-replay',
+            url: 'https://example.com/replayed.mp4',
+            artifacts: [artifact],
+          },
+        },
+        middleware: [{ onStart }],
+      }),
+    )
+
+    const customEvents = chunks.filter(
+      (chunk) => chunk.type === EventType.CUSTOM,
+    )
+    expect(customEvents.map((chunk) => chunk.name)).toEqual([
+      'generation:artifacts',
+      'generation:result',
+    ])
+    expect(customEvents[0]?.value).toEqual([artifact])
+    expect(
+      (customEvents[1]?.value as { artifacts?: unknown }).artifacts,
+    ).toEqual([artifact])
+    expect(createVideoJob).not.toHaveBeenCalled()
+    expect(onStart).not.toHaveBeenCalled()
+  })
+
+  it('rejects non-stream events-only replay without calling providers', async () => {
+    const replayEvents = [
+      {
+        type: EventType.CUSTOM,
+        name: 'generation:result',
+        value: { id: 'persisted', model: 'test-model' },
+        runId: 'run-replay',
+        threadId: 'thread-replay',
+      },
+    ] satisfies Array<StreamChunk>
+    const expectedMessage =
+      'Generation replay with events requires stream: true or a replay.result.'
+
+    const imageGenerate = vi.fn(async () => {
+      throw new Error('image provider should not be called')
+    })
+    await expect(
+      generateImage({
+        adapter: {
+          kind: 'image',
+          name: 'test-image',
+          model: 'test-model',
+          '~types': imageAdapterTypes,
+          generateImages: imageGenerate,
+        },
+        prompt: 'ignored',
+        replay: { events: replayEvents },
+      }),
+    ).rejects.toThrow(expectedMessage)
+    expect(imageGenerate).not.toHaveBeenCalled()
+
+    const audioGenerate = vi.fn(async () => {
+      throw new Error('audio provider should not be called')
+    })
+    await expect(
+      generateAudio({
+        adapter: {
+          kind: 'audio',
+          name: 'test-audio',
+          model: 'test-model',
+          '~types': audioAdapterTypes,
+          generateAudio: audioGenerate,
+        },
+        prompt: 'ignored',
+        replay: { events: replayEvents },
+      }),
+    ).rejects.toThrow(expectedMessage)
+    expect(audioGenerate).not.toHaveBeenCalled()
+
+    const speechGenerate = vi.fn(async () => {
+      throw new Error('speech provider should not be called')
+    })
+    await expect(
+      generateSpeech({
+        adapter: {
+          kind: 'tts',
+          name: 'test-tts',
+          model: 'test-model',
+          '~types': ttsAdapterTypes,
+          generateSpeech: speechGenerate,
+        },
+        text: 'ignored',
+        replay: { events: replayEvents },
+      }),
+    ).rejects.toThrow(expectedMessage)
+    expect(speechGenerate).not.toHaveBeenCalled()
+
+    const transcribe = vi.fn(async () => {
+      throw new Error('transcription provider should not be called')
+    })
+    await expect(
+      generateTranscription({
+        adapter: {
+          kind: 'transcription',
+          name: 'test-transcription',
+          model: 'test-model',
+          '~types': transcriptionAdapterTypes,
+          transcribe,
+        },
+        audio: 'ignored',
+        replay: { events: replayEvents },
+      }),
+    ).rejects.toThrow(expectedMessage)
+    expect(transcribe).not.toHaveBeenCalled()
+
+    const createVideoJob = vi.fn(async () => {
+      throw new Error('video provider should not be called')
+    })
+    await expect(
+      generateVideo({
+        adapter: createMockVideoAdapter({ createVideoJob }),
+        prompt: 'ignored',
+        replay: { events: replayEvents },
+      }),
+    ).rejects.toThrow(expectedMessage)
+    expect(createVideoJob).not.toHaveBeenCalled()
+  })
+
+  it('adds identity to video status devtools events', async () => {
+    const emit = vi.spyOn(aiEventClient, 'emit').mockImplementation(() => {})
+    const adapter = createMockVideoAdapter({
+      createVideoJob: vi.fn(),
+      getVideoStatus: vi.fn(
+        async (): Promise<VideoStatusResult> => ({
+          jobId: 'job-status',
+          status: 'completed',
+          progress: 100,
+        }),
+      ),
+      getVideoUrl: vi.fn(async () => ({
+        jobId: 'job-status',
+        url: 'https://example.com/status-video.mp4',
+        usage: {
+          promptTokens: 0,
+          completionTokens: 0,
+          totalTokens: 0,
+          unitsBilled: 1,
+        },
+      })),
+    })
+
+    await getVideoJobStatus({
+      adapter,
+      jobId: 'job-status',
+      threadId: 'thread-status',
+      runId: 'run-status',
+    })
+
+    expect(emit).toHaveBeenCalledWith(
+      'video:request:started',
+      expect.objectContaining({
+        threadId: 'thread-status',
+        runId: 'run-status',
+      }),
+    )
+    expect(emit).toHaveBeenCalledWith(
+      'video:request:completed',
+      expect.objectContaining({
+        threadId: 'thread-status',
+        runId: 'run-status',
+      }),
+    )
+    expect(emit).toHaveBeenCalledWith(
+      'video:usage',
+      expect.objectContaining({
+        threadId: 'thread-status',
+        runId: 'run-status',
+      }),
+    )
+  })
+})
diff --git a/packages/ai/tests/interrupts.test.ts b/packages/ai/tests/interrupts.test.ts
new file mode 100644
index 000000000..1c99e0ab5
--- /dev/null
+++ b/packages/ai/tests/interrupts.test.ts
@@ -0,0 +1,83 @@
+import { describe, expect, expectTypeOf, it } from 'vitest'
+import { EventType } from '@ag-ui/core'
+import type {
+  Interrupt,
+  RunAgentResumeItem,
+  RunFinishedEvent,
+  RunFinishedOutcome,
+  TextOptions,
+} from '../src/types'
+
+describe('AG-UI interrupt protocol types', () => {
+  it('allows RUN_FINISHED success, interrupt, and legacy outcomes', () => {
+    const success = {
+      type: EventType.RUN_FINISHED,
+      threadId: 'thread-1',
+      runId: 'run-1',
+      timestamp: 1,
+      outcome: { type: 'success' },
+    } satisfies RunFinishedEvent
+
+    const interrupt = {
+      type: EventType.RUN_FINISHED,
+      threadId: 'thread-1',
+      runId: 'run-1',
+      timestamp: 1,
+      outcome: {
+        type: 'interrupt',
+        interrupts: [
+          {
+            id: 'interrupt-1',
+            reason: 'tool_call',
+            message: 'Approve the tool call?',
+            toolCallId: 'tool-call-1',
+            responseSchema: {
+              type: 'object',
+              properties: { approved: { type: 'boolean' } },
+              required: ['approved'],
+            },
+            expiresAt: '2026-04-20T17:00:00Z',
+            metadata: { surface: 'test' },
+          },
+        ],
+      },
+    } satisfies RunFinishedEvent
+
+    const legacy: RunFinishedEvent = {
+      type: EventType.RUN_FINISHED,
+      threadId: 'thread-1',
+      runId: 'run-1',
+      timestamp: 1,
+    }
+
+    expect(success.outcome).toEqual({ type: 'success' })
+    expect(interrupt.outcome.interrupts[0]?.id).toBe('interrupt-1')
+    expect(legacy.outcome).toBeUndefined()
+  })
+
+  it('exposes resume items on TextOptions', () => {
+    const resume = [
+      {
+        interruptId: 'interrupt-1',
+        status: 'resolved',
+        payload: { approved: true },
+      },
+      {
+        interruptId: 'interrupt-2',
+        status: 'cancelled',
+      },
+    ] satisfies Array<RunAgentResumeItem>
+
+    const options = {
+      model: 'test-model',
+      messages: [],
+      logger: undefined as never,
+      resume,
+    } satisfies TextOptions
+
+    expect(options.resume).toBe(resume)
+    expectTypeOf<RunFinishedOutcome>().toMatchTypeOf<
+      { type: 'success' } | { type: 'interrupt'; interrupts: Array<Interrupt> }
+    >()
+  })
+})
diff --git a/packages/ai/tests/locks.test.ts b/packages/ai/tests/locks.test.ts
new file mode 100644
index 000000000..bf1972d97
--- /dev/null
+++ b/packages/ai/tests/locks.test.ts
@@ -0,0 +1,88 @@
+import { describe, expect, it } from 'vitest'
+import {
+  InMemoryLockStore,
+  LocksCapability,
+  getLocks,
+  provideLocks,
+} from '../src/locks'
+import { CapabilityRegistry } from '../src/activities/chat/middleware/capabilities'
+
+describe('InMemoryLockStore', () => {
+  it('serializes concurrent withLock calls for the same key', async () => {
+    const store = new InMemoryLockStore()
+    const order: Array<string> = []
+
+    const first = store.withLock('k', async () => {
+      order.push('first-start')
+      await new Promise((r) => setTimeout(r, 20))
+      order.push('first-end')
+      return 1
+    })
+    // Second acquire happens while first holds the lock.
+    const second = store.withLock('k', async () => {
+      order.push('second-start')
+      order.push('second-end')
+      return 2
+    })
+
+    const [a, b] = await Promise.all([first, second])
+    expect(a).toBe(1)
+    expect(b).toBe(2)
+    // Second must not interleave: it starts only after first fully ends.
+    expect(order).toEqual([
+      'first-start',
+      'first-end',
+      'second-start',
+      'second-end',
+    ])
+  })
+
+  it('runs different keys concurrently', async () => {
+    const store = new InMemoryLockStore()
+    const order: Array<string> = []
+
+    const a = store.withLock('a', async () => {
+      order.push('a-start')
+      await new Promise((r) => setTimeout(r, 20))
+      order.push('a-end')
+    })
+    const b = store.withLock('b', async () => {
+      order.push('b-start')
+      order.push('b-end')
+    })
+
+    await Promise.all([a, b])
+    // b (different key) runs while a is still waiting on its timeout.
+    expect(order.slice(0, 2)).toEqual(['a-start', 'b-start'])
+  })
+
+  it('keeps the lock usable after a holder throws', async () => {
+    const store = new InMemoryLockStore()
+    await expect(
+      store.withLock('k', async () => {
+        throw new Error('boom')
+      }),
+    ).rejects.toThrow('boom')
+
+    // Lock is not poisoned: a subsequent acquire still runs.
+    await expect(store.withLock('k', async () => 'ok')).resolves.toBe('ok')
+  })
+})
+
+describe('LocksCapability', () => {
+  it('is named "locks"', () => {
+    expect(LocksCapability.capabilityName).toBe('locks')
+  })
+
+  it('round-trips a LockStore through provide/get', () => {
+    const ctx = { capabilities: new CapabilityRegistry() }
+    const store = new InMemoryLockStore()
+    provideLocks(ctx, store)
+    expect(getLocks(ctx)).toBe(store)
+  })
+
+  it('getLocks returns undefined when optional and not provided', () => {
+    const ctx = { capabilities: new CapabilityRegistry() }
+    expect(getLocks(ctx, { optional: true })).toBeUndefined()
+  })
+})
diff --git a/packages/ai/tests/stream-durability.test.ts b/packages/ai/tests/stream-durability.test.ts
new file mode 100644
index 000000000..8bc1043fb
--- /dev/null
+++ b/packages/ai/tests/stream-durability.test.ts
@@ -0,0 +1,270 @@
+import { describe, expect, it } from 'vitest'
+import {
+  decodeOffset,
+  encodeOffset,
+  memoryStream,
+  runIdOf,
+} from '../src/stream-durability'
+import type { StreamChunk } from '../src/types'
+
+function chunk(delta: string): StreamChunk {
+  return {
+    type: 'TEXT_MESSAGE_CONTENT',
+    delta,
+    timestamp: 0,
+  } as StreamChunk
+}
+
+function terminal(): StreamChunk {
+  return { type: 'RUN_FINISHED', timestamp: 0 } as StreamChunk
+}
+
+describe('encodeOffset / decodeOffset', () => {
+  it('round-trips a runId and seq', () => {
+    const offset = encodeOffset('run-abc', 7)
+    expect(offset).toBe('run-abc@7')
+    expect(decodeOffset(offset)).toEqual({ runId: 'run-abc', seq: 7 })
+  })
+
+  it('round-trips runIds that contain @', () => {
+    const offset = encodeOffset('tenant@run-1', 3)
+    expect(decodeOffset(offset)).toEqual({ runId: 'tenant@run-1', seq: 3 })
+  })
+
+  // Finding 2: the `now` / `-1` sentinels must not make decode / runId
+  // extraction throw (`Number('now')` → NaN used to throw).
+  it('decodes the `now` sentinel without throwing (tail → +Infinity)', () => {
+    const offset = encodeOffset('run-x', 'now')
+    expect(offset).toBe('run-x@now')
+    expect(decodeOffset(offset)).toEqual({
+      runId: 'run-x',
+      seq: Number.POSITIVE_INFINITY,
+    })
+  })
+
+  it('decodes the `-1` sentinel without throwing (from start)', () => {
+    expect(decodeOffset('run-x@-1')).toEqual({ runId: 'run-x', seq: -1 })
+  })
+
+  it('extracts the runId from a sentinel offset without parsing the seq', () => {
+    expect(runIdOf('run-x@now')).toBe('run-x')
+    expect(runIdOf('run-x@-1')).toBe('run-x')
+    expect(runIdOf('tenant@run-1@now')).toBe('tenant@run-1')
+    expect(runIdOf('bare-run')).toBe('bare-run')
+  })
+
+  it('resolves a resume runId carried in Last-Event-ID with a `now` seq', () => {
+    // A tail-join reconnect carries `runId@now`; runId() must not throw.
+    const durability = memoryStream(
+      new Request('https://example.test/api/chat', {
+        method: 'POST',
+        headers: { 'Last-Event-ID': encodeOffset('run-now', 'now') },
+      }),
+    )
+    expect(durability.resumeFrom()).toBe('run-now@now')
+    expect(durability.runId()).toBe('run-now')
+  })
+
+  it('still throws on a genuinely malformed offset', () => {
+    expect(() => decodeOffset('no-at-sign')).toThrow(/missing @/)
+    expect(() => decodeOffset('run@not-a-number')).toThrow(
+      /Invalid durability offset seq/,
+    )
+  })
+})
+
+describe('memoryStream', () => {
+  it('treats a request with no offset as a fresh run and replays from the start', async () => {
+    const request = new Request('https://example.test/api/chat', {
+      method: 'POST',
+    })
+    const durability = memoryStream(request)
+
+    expect(durability.resumeFrom()).toBeNull()
+    const runId = durability.runId()
+    expect(runId).toBeTruthy()
+
+    await durability.append([chunk('a'), chunk('b'), chunk('c')], 1)
+    // Mark complete so the live-tailing read returns after draining.
+    durability.markComplete!()
+
+    const read: Array<{ seq: number; delta: string }> = []
+    for await (const { seq, chunk: c } of durability.read('-1')) {
+      read.push({ seq, delta: (c as { delta: string }).delta })
+    }
+    expect(read).toEqual([
+      { seq: 1, delta: 'a' },
+      { seq: 2, delta: 'b' },
+      { seq: 3, delta: 'c' },
+    ])
+  })
+
+  it('append returns the per-chunk backend offsets to tag with', async () => {
+    const durability = memoryStream(
+      new Request('https://example.test/api/chat?runId=run-off', {
+        method: 'POST',
+      }),
+    )
+    const offsets = await durability.append(
+      [chunk('a'), chunk('b'), chunk('c')],
+      1,
+    )
+    expect(offsets).toEqual([
+      encodeOffset('run-off', 1),
+      encodeOffset('run-off', 2),
+      encodeOffset('run-off', 3),
+    ])
+  })
+
+  it('resumes strictly after the offset carried in Last-Event-ID', async () => {
+    // First, a producer writes three chunks under a known run.
+    const producer = memoryStream(
+      new Request('https://example.test/api/chat?runId=run-resume', {
+        method: 'POST',
+      }),
+    )
+    expect(producer.runId()).toBe('run-resume')
+    const offsets = await producer.append(
+      [chunk('a'), chunk('b'), chunk('c')],
+      1,
+    )
+    expect(offsets).toEqual([
+      encodeOffset('run-resume', 1),
+      encodeOffset('run-resume', 2),
+      encodeOffset('run-resume', 3),
+    ])
+    producer.markComplete!()
+
+    // A reconnect arrives carrying Last-Event-ID at seq 2.
+    const reconnect = memoryStream(
+      new Request('https://example.test/api/chat', {
+        method: 'POST',
+        headers: { 'Last-Event-ID': encodeOffset('run-resume', 2) },
+      }),
+    )
+    expect(reconnect.resumeFrom()).toBe(encodeOffset('run-resume', 2))
+    expect(reconnect.runId()).toBe('run-resume')
+
+    const read: Array<string> = []
+    for await (const { chunk: c } of reconnect.read(reconnect.resumeFrom()!)) {
+      read.push((c as { delta: string }).delta)
+    }
+    expect(read).toEqual(['c'])
+  })
+
+  it('reads the offset from the ?offset query param when no header is present', async () => {
+    const producer = memoryStream(
+      new Request('https://example.test/api/chat?runId=run-q', {
+        method: 'POST',
+      }),
+    )
+    await producer.append([chunk('x'), chunk('y')], 1)
+    producer.markComplete!()
+
+    const joiner = memoryStream(
+      new Request(
+        `https://example.test/api/chat?offset=${encodeURIComponent(
+          encodeOffset('run-q', -1),
+        )}`,
+        { method: 'POST' },
+      ),
+    )
+    expect(joiner.resumeFrom()).toBe(encodeOffset('run-q', -1))
+    expect(joiner.runId()).toBe('run-q')
+
+    const read: Array<string> = []
+    for await (const { chunk: c } of joiner.read(joiner.resumeFrom()!)) {
+      read.push((c as { delta: string }).delta)
+    }
+    expect(read).toEqual(['x', 'y'])
+  })
+
+  // Finding 3: a mid-stream join must live-tail — receive future appends up to
+  // the terminal, not return at the snapshot tail before the run finishes.
+  it('live-tails a join on a still-producing run through the terminal', async () => {
+    const runId = 'run-live'
+    const producer = memoryStream(
+      new Request(`https://example.test/api/chat?runId=${runId}`, {
+        method: 'POST',
+      }),
+    )
+    await producer.append([chunk('a'), chunk('b')], 1)
+
+    // A joiner attaches mid-stream and reads from the start.
+    const joiner = memoryStream(
+      new Request(
+        `https://example.test/api/chat?offset=${encodeURIComponent(
+          encodeOffset(runId, -1),
+        )}`,
+        { method: 'POST' },
+      ),
+    )
+
+    const received: Array<string> = []
+    const done = (async () => {
+      for await (const { chunk: c } of joiner.read(joiner.resumeFrom()!)) {
+        received.push((c as { delta?: string }).delta ?? `[${c.type}]`)
+      }
+    })()
+
+    // Give the joiner a tick to drain the initial snapshot and park.
+    await new Promise((r) => setTimeout(r, 10))
+    expect(received).toEqual(['a', 'b'])
+
+    // The producer emits more, then the terminal.
+    await producer.append([chunk('c'), chunk('d')], 3)
+    await producer.append([terminal()], 5)
+
+    await done
+    expect(received).toEqual(['a', 'b', 'c', 'd', '[RUN_FINISHED]'])
+  })
+
+  // Finding 2 (hang guard): a join to a runId with no in-process producer
+  // (crash / cross-instance / bogus id) creates an empty log and parks — no
+  // `markComplete` ever fires. Threading the consumer's AbortSignal must wake
+  // the parked waiter so the iteration ends instead of hanging forever.
+  it('does not hang: an aborted join to a never-produced runId terminates', async () => {
+    const controller = new AbortController()
+    const joiner = memoryStream(
+      new Request('https://example.test/api/chat?runId=never-produced-run', {
+        method: 'POST',
+      }),
+    )
+
+    const received: Array<string> = []
+    const iterated = (async () => {
+      for await (const { chunk: c } of joiner.read('-1', controller.signal)) {
+        received.push((c as { delta?: string }).delta ?? `[${c.type}]`)
+      }
+    })()
+
+    // Nothing is ever produced under this runId, so the read parks. Give it a
+    // tick to create its empty log and park on the (never-fired) next append.
+    await new Promise((r) => setTimeout(r, 10))
+    expect(received).toEqual([])
+
+    // The abort must wake the parked waiter and end the iteration. Race against
+    // a deadline so a regression (parking forever) fails loudly rather than
+    // hanging the whole suite.
+    controller.abort()
+    const timedOut = Symbol('timed-out')
+    const outcome = await Promise.race([
+      iterated.then(() => 'done' as const),
+      new Promise<typeof timedOut>((r) => setTimeout(() => r(timedOut), 1000)),
+    ])
+    expect(outcome).toBe('done')
+    expect(received).toEqual([])
+  })
+
+  it('rejects a caller-supplied ?runId containing CR/LF (SSE injection)', () => {
+    const durability = memoryStream(
+      new Request(
+        `https://example.test/api/chat?runId=${encodeURIComponent(
+          'evil\ninjected',
+        )}`,
+        { method: 'POST' },
+      ),
+    )
+    expect(() => durability.runId()).toThrow(/Invalid runId/)
+  })
+})
diff --git a/packages/ai/tests/stream-processor.test.ts b/packages/ai/tests/stream-processor.test.ts
index d3b5fd194..bbdade127 100644
--- a/packages/ai/tests/stream-processor.test.ts
+++ b/packages/ai/tests/stream-processor.test.ts
@@ -3,7 +3,15 @@ import {
   StreamProcessor,
   createReplayStream,
 } from '../src/activities/chat/stream/processor'
+import { chat } from '../src/activities/chat/index'
 import { EventType } from '../src/types'
+import {
+  createMockAdapter,
+  collectChunks,
+  serverTool,
+  clientTool,
+  ev as chatEv,
+} from './test-utils'
 import type { Mock } from 'vitest'
 import type { StreamProcessorEvents } from '../src/activities/chat/stream/processor'
 import type { ChunkStrategy } from '../src/activities/chat/stream/types'
@@ -1143,6 +1151,129 @@ describe('StreamProcessor', () => {
       })
     })
 
+    it('should handle approval interrupts on RUN_FINISHED', () => {
+      const events = spyEvents()
+      const processor = new StreamProcessor({ events })
+      processor.prepareAssistantMessage()
+
+      processor.processChunk(ev.runStarted())
+      processor.processChunk(ev.toolStart('tc-1', 'dangerousTool'))
+      processor.processChunk(ev.toolArgs('tc-1', '{"action":"delete"}'))
+      processor.processChunk({
+        ...ev.runFinished('tool_calls'),
+        outcome: {
+          type: 'interrupt',
+          interrupts: [
+            {
+              id: 'approval-1',
+              reason: 'approval_required',
+              toolCallId: 'tc-1',
+              metadata: {
+                kind: 'approval',
+                toolName: 'dangerousTool',
+                input: { action: 'delete' },
+              },
+            },
+          ],
+        },
+      })
+
+      const toolCallPart = processor
+        .getMessages()[0]!
+        .parts.find((p) => p.type === 'tool-call') as ToolCallPart
+      expect(toolCallPart.state).toBe('approval-requested')
+      expect(toolCallPart.approval).toEqual({
+        id: 'approval-1',
+        needsApproval: true,
+      })
+      expect(events.onApprovalRequest).toHaveBeenCalledWith({
+        toolCallId: 'tc-1',
+        toolName: 'dangerousTool',
+        input: { action: 'delete' },
+        approvalId: 'approval-1',
+      })
+    })
+
+    it('should handle client tool interrupts on RUN_FINISHED', () => {
+      const events = spyEvents()
+      const processor = new StreamProcessor({ events })
+      processor.prepareAssistantMessage()
+
+      processor.processChunk(ev.runStarted())
+      processor.processChunk(ev.toolStart('tc-1', 'clientSearch'))
+      processor.processChunk(ev.toolArgs('tc-1', '{"query":"test"}'))
+      processor.processChunk({
+        ...ev.runFinished('tool_calls'),
+        outcome: {
+          type: 'interrupt',
+          interrupts: [
+            {
+              id: 'client_tool_tc-1',
+              reason: 'client_tool_input',
+              toolCallId: 'tc-1',
+              metadata: {
+                kind: 'client_tool',
+                toolName: 'clientSearch',
+                input: { query: 'test' },
+              },
+            },
+          ],
+        },
+      })
+
+      expect(events.onToolCall).toHaveBeenCalledWith({
+        toolCallId: 'tc-1',
+        toolName: 'clientSearch',
+        input: { query: 'test' },
+      })
+    })
+
+    it('should deliver client tool interrupt before stream end for mixed tool streams', async () => {
+      const order: Array<string> = []
+      const events = spyEvents()
+      events.onToolCall.mockImplementation(() => {
+        order.push('tool-call')
+      })
+      events.onStreamEnd.mockImplementation(() => {
+        order.push('stream-end')
+      })
+      const processor = new StreamProcessor({ events })
+      processor.prepareAssistantMessage()
+
+      const { adapter } = createMockAdapter({
+        iterations: [
+          [
+            chatEv.runStarted(),
+            chatEv.toolStart('call_server', 'searchTools'),
+            chatEv.toolArgs('call_server', '{"query":"hello"}'),
+            chatEv.toolStart('call_client', 'showNotification'),
+            chatEv.toolArgs('call_client', '{"message":"done"}'),
+            chatEv.runFinished('tool_calls'),
+          ],
+        ],
+      })
+      const stream = chat({
+        adapter,
+        messages: [{ role: 'user', content: 'Search and notify' }],
+        tools: [
+          serverTool('searchTools', () => ({ results: ['a', 'b'] })),
+          clientTool('showNotification'),
+        ],
+      })
+      const chunks = await collectChunks(stream as AsyncIterable<StreamChunk>)
+
+      for (const streamChunk of chunks) {
+        processor.processChunk(streamChunk)
+      }
+
+      expect(events.onToolCall).toHaveBeenCalledWith({
+        toolCallId: 'call_client',
+        toolName: 'showNotification',
+        input: { message: 'done' },
+      })
+      expect(order).toEqual(['tool-call', 'stream-end'])
+    })
+
     it('addToolApprovalResponse should approve a tool call', () => {
       const events = spyEvents()
       const processor = new StreamProcessor({ events })
@@ -1999,6 +2130,51 @@ describe('StreamProcessor', () => {
       await StreamProcessor.replay(recording, { events })
       expect(events.onStreamEnd).toHaveBeenCalledTimes(1)
     })
+
+    it('replay should consume legacy approval-requested CUSTOM chunks after RUN_FINISHED', async () => {
+      const events = spyEvents()
+      const recording = {
+        version: '1.0' as const,
+        timestamp: Date.now(),
+        chunks: [
+          { chunk: ev.runStarted(), timestamp: Date.now(), index: 0 },
+          {
+            chunk: ev.toolStart('tc-1', 'dangerousTool'),
+            timestamp: Date.now(),
+            index: 1,
+          },
+          {
+            chunk: ev.toolArgs('tc-1', '{"action":"delete"}'),
+            timestamp: Date.now(),
+            index: 2,
+          },
+          {
+            chunk: ev.runFinished('tool_calls'),
+            timestamp: Date.now(),
+            index: 3,
+          },
+          {
+            chunk: ev.custom('approval-requested', {
+              toolCallId: 'tc-1',
+              toolName: 'dangerousTool',
+              input: { action: 'delete' },
+              approval: { id: 'approval-1', needsApproval: true },
+            }),
+            timestamp: Date.now(),
+            index: 4,
+          },
+        ],
+      }
+
+      await StreamProcessor.replay(recording, { events })
+
+      expect(events.onApprovalRequest).toHaveBeenCalledWith({
+        toolCallId: 'tc-1',
+        toolName: 'dangerousTool',
+        input: { action: 'delete' },
+        approvalId: 'approval-1',
+      })
+    })
   })
 
   // ==========================================================================
diff --git a/packages/ai/tests/stream-to-response-durability.test.ts b/packages/ai/tests/stream-to-response-durability.test.ts
new file mode 100644
index 000000000..cc92340a7
--- /dev/null
+++ b/packages/ai/tests/stream-to-response-durability.test.ts
@@ -0,0 +1,211 @@
+import { describe, expect, it, vi } from 'vitest'
+import { encodeOffset, memoryStream } from '../src/stream-durability'
+import { toServerSentEventsResponse } from '../src/stream-to-response'
+import type { StreamChunk } from '../src/types'
+
+function textChunk(delta: string): StreamChunk {
+  return { type: 'TEXT_MESSAGE_CONTENT', delta, timestamp: 0 } as StreamChunk
+}
+
+function fiveChunkStream(): {
+  stream: AsyncIterable<StreamChunk>
+  iterated: () => boolean
+} {
+  let started = false
+  const stream: AsyncIterable<StreamChunk> = {
+    async *[Symbol.asyncIterator]() {
+      started = true
+      for (const d of ['1', '2', '3', '4', '5']) {
+        yield textChunk(d)
+      }
+    },
+  }
+  return { stream, iterated: () => started }
+}
+
+async function readBody(res: Response): Promise<string> {
+  const reader = res.body!.getReader()
+  const decoder = new TextDecoder()
+  let out = ''
+  for (;;) {
+    const { done, value } = await reader.read()
+    if (done) break
+    out += decoder.decode(value)
+  }
+  return out
+}
+
+function parseSseEvents(body: string): Array<{ id?: string; data: string }> {
+  return body
+    .split('\n\n')
+    .filter((block) => block.trim().length > 0)
+    .map((block) => {
+      const lines = block.split('\n')
+      const idLine = lines.find((l) => l.startsWith('id: '))
+      const dataLine = lines.find((l) => l.startsWith('data: '))
+      return {
+        ...(idLine ? { id: idLine.slice('id: '.length) } : {}),
+        data: dataLine ? dataLine.slice('data: '.length) : '',
+      }
+    })
+}
+
+describe('toServerSentEventsResponse with durability', () => {
+  it('appends + forwards a fresh run, tagging each event with an id offset', async () => {
+    const request = new Request('https://example.test/api/chat', {
+      method: 'POST',
+    })
+    const durability = memoryStream(request)
+    const runId = durability.runId()
+    const { stream, iterated } = fiveChunkStream()
+
+    const res = toServerSentEventsResponse(stream, {
+      durability: { adapter: durability },
+    })
+    const events = parseSseEvents(await readBody(res))
+
+    expect(iterated()).toBe(true)
+    expect(events).toHaveLength(5)
+    expect(events.map((e) => e.id)).toEqual([
+      encodeOffset(runId, 1),
+      encodeOffset(runId, 2),
+      encodeOffset(runId, 3),
+      encodeOffset(runId, 4),
+      encodeOffset(runId, 5),
+    ])
+
+    // The durability log now holds all 5 chunks.
+    const logged: Array<string> = []
+    for await (const { chunk } of durability.read('-1')) {
+      logged.push((chunk as { delta: string }).delta)
+    }
+    expect(logged).toEqual(['1', '2', '3', '4', '5'])
+  })
+
+  it('replays from the log on resume and never iterates the input stream', async () => {
+    // Produce a run under a known id.
+    const producerReq = new Request(
+      'https://example.test/api/chat?runId=run-x',
+      { method: 'POST' },
+    )
+    const { stream } = fiveChunkStream()
+    await readBody(
+      toServerSentEventsResponse(stream, {
+        durability: { adapter: memoryStream(producerReq) },
+      }),
+    )
+
+    // Reconnect carrying Last-Event-ID at seq 2.
+    const reconnectReq = new Request('https://example.test/api/chat', {
+      method: 'POST',
+      headers: { 'Last-Event-ID': encodeOffset('run-x', 2) },
+    })
+    const exploding: AsyncIterable<StreamChunk> = {
+      [Symbol.asyncIterator]() {
+        return {
+          next() {
+            throw new Error('input stream must not be iterated on resume')
+          },
+        }
+      },
+    }
+
+    const res = toServerSentEventsResponse(exploding, {
+      durability: { adapter: memoryStream(reconnectReq) },
+    })
+    const events = parseSseEvents(await readBody(res))
+
+    expect(events.map((e) => e.id)).toEqual([
+      encodeOffset('run-x', 3),
+      encodeOffset('run-x', 4),
+      encodeOffset('run-x', 5),
+    ])
+    expect(events.map((e) => JSON.parse(e.data).delta)).toEqual(['3', '4', '5'])
+  })
+
+  it('batches appends to at most `batch` chunks', async () => {
+    const request = new Request('https://example.test/api/chat?runId=run-b', {
+      method: 'POST',
+    })
+    const durability = memoryStream(request)
+    const appendSpy = vi.spyOn(durability, 'append')
+    const { stream } = fiveChunkStream()
+
+    await readBody(
+      toServerSentEventsResponse(stream, {
+        durability: { adapter: durability, batch: 2 },
+      }),
+    )
+
+    const batchSizes = appendSpy.mock.calls.map(([chunks]) => chunks.length)
+    expect(batchSizes.every((n) => n <= 2)).toBe(true)
+    expect(batchSizes.reduce((a, b) => a + b, 0)).toBe(5)
+  })
+
+  // Finding 7a: a non-positive-integer batch is rejected loudly (a NaN used to
+  // silently disable size-based flushing: `length >= NaN` is always false).
+  it('rejects a non-positive-integer batch size', () => {
+    const durability = memoryStream(
+      new Request('https://example.test/api/chat?runId=run-bad-batch', {
+        method: 'POST',
+      }),
+    )
+    const { stream } = fiveChunkStream()
+    for (const bad of [0, -1, 1.5, NaN]) {
+      expect(() =>
+        toServerSentEventsResponse(stream, {
+          durability: { adapter: durability, batch: bad },
+        }),
+      ).toThrow(/Invalid durability batch size/)
+    }
+    // A valid positive integer is accepted.
+    expect(() =>
+      toServerSentEventsResponse(stream, {
+        durability: { adapter: durability, batch: 4 },
+      }),
+    ).not.toThrow()
+  })
+
+  // Finding 4: when the provider stream throws, a terminal RUN_ERROR must be
+  // persisted to the durability log, so a later reader / join learns the run
+  // failed instead of finding a log with no terminal.
+  it('persists a terminal RUN_ERROR to the log when the stream throws', async () => {
+    const request = new Request('https://example.test/api/chat?runId=run-err', {
+      method: 'POST',
+    })
+    const durability = memoryStream(request)
+
+    const throwing: AsyncIterable<StreamChunk> = {
+      async *[Symbol.asyncIterator]() {
+        yield textChunk('1')
+        throw new Error('provider exploded')
+      },
+    }
+
+    // The live consumer still sees a RUN_ERROR (emitted by the transport).
+    const liveEvents = parseSseEvents(
+      await readBody(
+        toServerSentEventsResponse(throwing, {
+          durability: { adapter: durability },
+        }),
+      ),
+    )
+    const liveTypes = liveEvents.map((e) => JSON.parse(e.data).type)
+    expect(liveTypes).toContain('RUN_ERROR')
+
+    // A second reader / joiner replaying the log sees the persisted terminal.
+    const joiner = memoryStream(
+      new Request('https://example.test/api/chat?runId=run-err', {
+        method: 'POST',
+      }),
+    )
+    const logged: Array<StreamChunk> = []
+    for await (const { chunk } of joiner.read('-1')) {
+      logged.push(chunk)
+    }
+    expect(logged.map((c) => c.type)).toEqual([
+      'TEXT_MESSAGE_CONTENT',
+      'RUN_ERROR',
+    ])
+  })
+})
diff --git a/packages/ai/tests/tool-call-manager.test.ts b/packages/ai/tests/tool-call-manager.test.ts
index 14b35e9d9..b9d644e4d 100644
--- a/packages/ai/tests/tool-call-manager.test.ts
+++ b/packages/ai/tests/tool-call-manager.test.ts
@@ -67,7 +67,7 @@ describe('ToolCallManager', () => {
   const mockFinishedEvent = {
     type: 'RUN_FINISHED',
     runId: 'test-run-id',
-    model: 'gpt-4',
+    model: 'gpt-5.5',
     timestamp: Date.now(),
     finishReason: 'tool_calls',
   } as unknown as RunFinishedEvent
@@ -544,6 +544,8 @@ describe('executeToolCalls', () => {
 
       expect(result.needsApproval).toHaveLength(1)
       expect(result.needsApproval[0]?.toolCallId).toBe('call_1')
+      expect(result.needsApproval[0]?.toolName).toBe('delete_local_data')
+      expect(result.needsApproval[0]?.input).toEqual({ key: 'myKey' })
       expect(result.needsApproval[0]?.approvalId).toBe('approval_call_1')
       expect(result.results).toHaveLength(0)
       expect(result.needsClientExecution).toHaveLength(0)
@@ -799,6 +801,9 @@ describe('executeToolCalls', () => {
 
       expect(result.needsApproval).toHaveLength(1)
       expect(result.needsApproval[0]?.approvalId).toBe('approval_call_1')
+      expect(result.needsApproval[0]?.toolCallId).toBe('call_1')
+      expect(result.needsApproval[0]?.toolName).toBe('delete_record')
+      expect(result.needsApproval[0]?.input).toEqual({ id: 'rec_123' })
       expect(result.results).toHaveLength(0)
     })
 
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
index 5eab53f64..510cfa054 100644
--- a/pnpm-lock.yaml
+++ b/pnpm-lock.yaml
@@ -303,7 +303,7 @@ importers:
         version: 17.2.3
       nitro:
         specifier: 3.0.1-alpha.2
-        version: 3.0.1-alpha.2(@emnapi/core@1.11.1)(@emnapi/runtime@1.11.1)(aws4fetch@1.0.20)(chokidar@5.0.0)(rolldown@1.1.3)(rollup@4.60.1)(vite@7.3.3(@types/node@24.10.3)(jiti@2.6.1)(less@4.6.6)(lightningcss@1.30.2)(sass@1.101.0)(terser@5.44.1)(tsx@4.21.0)(yaml@2.8.2))
+        version: 3.0.1-alpha.2(@emnapi/core@1.11.1)(@emnapi/runtime@1.11.1)(aws4fetch@1.0.20)(chokidar@5.0.0)(drizzle-orm@0.45.2(@cloudflare/workers-types@4.20260317.1)(@opentelemetry/api@1.9.1)(@prisma/client@6.19.3(prisma@6.19.3(typescript@5.9.3))(typescript@5.9.3))(@types/pg@8.20.0)(mysql2@3.22.5(@types/node@24.10.3))(pg@8.21.0)(prisma@6.19.3(typescript@5.9.3)))(mysql2@3.22.5(@types/node@24.10.3))(rolldown@1.1.3)(rollup@4.60.1)(vite@7.3.3(@types/node@24.10.3)(jiti@2.6.1)(less@4.6.6)(lightningcss@1.30.2)(sass@1.101.0)(terser@5.44.1)(tsx@4.21.0)(yaml@2.8.2))
       tailwindcss:
         specifier: ^4.1.18
         version: 4.1.18
@@ -421,7 +421,7 @@ importers:
         version: link:../../packages/ai-react
       '@tanstack/nitro-v2-vite-plugin':
         specifier: ^1.154.7
-        version: 1.154.7(aws4fetch@1.0.20)(rolldown@1.1.3)(vite@7.3.3(@types/node@24.10.3)(jiti@2.6.1)(less@4.6.6)(lightningcss@1.30.2)(sass@1.101.0)(terser@5.44.1)(tsx@4.21.0)(yaml@2.8.2))
+        version: 1.154.7(aws4fetch@1.0.20)(drizzle-orm@0.45.2(@cloudflare/workers-types@4.20260317.1)(@opentelemetry/api@1.9.1)(@prisma/client@6.19.3(prisma@6.19.3(magicast@0.5.2)(typescript@5.9.3))(typescript@5.9.3))(@types/pg@8.20.0)(mysql2@3.22.5(@types/node@24.10.3))(pg@8.21.0)(prisma@6.19.3(magicast@0.5.2)(typescript@5.9.3)))(mysql2@3.22.5(@types/node@24.10.3))(rolldown@1.1.3)(vite@7.3.3(@types/node@24.10.3)(jiti@2.6.1)(less@4.6.6)(lightningcss@1.30.2)(sass@1.101.0)(terser@5.44.1)(tsx@4.21.0)(yaml@2.8.2))
       '@tanstack/react-router':
         specifier: ^1.158.4
         version: 1.159.5(react-dom@19.2.3(react@19.2.3))(react@19.2.3)
@@ -670,6 +670,12 @@ importers:
       '@tanstack/ai-openrouter':
         specifier: workspace:*
         version: link:../../packages/ai-openrouter
+      '@tanstack/ai-persistence':
+        specifier: workspace:*
+        version: link:../../packages/ai-persistence
+      '@tanstack/ai-persistence-drizzle':
+        specifier: workspace:*
+        version: link:../../packages/ai-persistence-drizzle
       '@tanstack/ai-react':
         specifier: workspace:*
         version: link:../../packages/ai-react
@@ -693,7 +699,7 @@ importers:
         version: link:../../packages/ai-sandbox-vercel
       '@tanstack/nitro-v2-vite-plugin':
         specifier: ^1.154.7
-        version: 1.154.7(aws4fetch@1.0.20)(rolldown@1.1.3)(vite@7.3.3(@types/node@24.10.3)(jiti@2.6.1)(less@4.6.6)(lightningcss@1.30.2)(sass@1.101.0)(terser@5.44.1)(tsx@4.21.0)(yaml@2.8.2))
+        version: 1.154.7(aws4fetch@1.0.20)(drizzle-orm@0.45.2(@cloudflare/workers-types@4.20260317.1)(@opentelemetry/api@1.9.1)(@prisma/client@6.19.3(prisma@6.19.3(typescript@5.9.3))(typescript@5.9.3))(@types/pg@8.20.0)(mysql2@3.22.5(@types/node@24.10.3))(pg@8.21.0)(prisma@6.19.3(typescript@5.9.3)))(mysql2@3.22.5(@types/node@24.10.3))(rolldown@1.1.3)(vite@7.3.3(@types/node@24.10.3)(jiti@2.6.1)(less@4.6.6)(lightningcss@1.30.2)(sass@1.101.0)(terser@5.44.1)(tsx@4.21.0)(yaml@2.8.2))
       '@tanstack/react-devtools':
         specifier: ^0.9.10
         version: 0.9.10(@types/react-dom@19.2.3(@types/react@19.2.7))(@types/react@19.2.7)(csstype@3.2.3)(react-dom@19.2.3(react@19.2.3))(react@19.2.3)(solid-js@1.9.10)
@@ -829,7 +835,7 @@ importers:
         version: 0.561.0(react@19.2.3)
       nitro:
         specifier: 3.0.1-alpha.2
-        version: 3.0.1-alpha.2(@emnapi/core@1.11.1)(@emnapi/runtime@1.11.1)(aws4fetch@1.0.20)(chokidar@5.0.0)(rolldown@1.1.3)(rollup@4.60.1)(vite@7.3.3(@types/node@24.10.3)(jiti@2.6.1)(less@4.6.6)(lightningcss@1.30.2)(sass@1.101.0)(terser@5.44.1)(tsx@4.21.0)(yaml@2.8.2))
+        version: 3.0.1-alpha.2(@emnapi/core@1.11.1)(@emnapi/runtime@1.11.1)(aws4fetch@1.0.20)(chokidar@5.0.0)(drizzle-orm@0.45.2(@cloudflare/workers-types@4.20260317.1)(@opentelemetry/api@1.9.1)(@prisma/client@6.19.3(prisma@6.19.3(typescript@5.9.3))(typescript@5.9.3))(@types/pg@8.20.0)(mysql2@3.22.5(@types/node@24.10.3))(pg@8.21.0)(prisma@6.19.3(typescript@5.9.3)))(mysql2@3.22.5(@types/node@24.10.3))(rolldown@1.1.3)(rollup@4.60.1)(vite@7.3.3(@types/node@24.10.3)(jiti@2.6.1)(less@4.6.6)(lightningcss@1.30.2)(sass@1.101.0)(terser@5.44.1)(tsx@4.21.0)(yaml@2.8.2))
       react:
         specifier: ^19.2.3
         version: 19.2.3
@@ -966,7 +972,7 @@ importers:
         version: 0.561.0(react@19.2.3)
       nitro:
         specifier: latest
-        version: 3.0.260610-beta(aws4fetch@1.0.20)(chokidar@5.0.0)(dotenv@17.2.3)(giget@2.0.0)(jiti@2.6.1)(miniflare@4.20260617.1)(rollup@4.60.1)(vite@7.3.3(@types/node@24.10.3)(jiti@2.6.1)(less@4.6.6)(lightningcss@1.30.2)(sass@1.101.0)(terser@5.44.1)(tsx@4.21.0)(yaml@2.8.2))(wrangler@4.103.0)
+        version: 3.0.260610-beta(aws4fetch@1.0.20)(chokidar@5.0.0)(dotenv@17.2.3)(drizzle-orm@0.45.2(@opentelemetry/api@1.9.1)(@prisma/client@6.19.3(prisma@6.19.3(typescript@5.9.3))(typescript@5.9.3))(@types/pg@8.20.0)(mysql2@3.22.5(@types/node@24.10.3))(pg@8.21.0)(prisma@6.19.3(typescript@5.9.3)))(giget@2.0.0)(jiti@2.6.1)(miniflare@4.20260617.1)(mysql2@3.22.5(@types/node@24.10.3))(rollup@4.60.1)(vite@7.3.3(@types/node@24.10.3)(jiti@2.6.1)(less@4.6.6)(lightningcss@1.30.2)(sass@1.101.0)(terser@5.44.1)(tsx@4.21.0)(yaml@2.8.2))(wrangler@4.103.0)
       radix-ui:
         specifier: ^1.4.3
         version: 1.4.3(@types/react-dom@19.2.3(@types/react@19.2.7))(@types/react@19.2.7)(react-dom@19.2.3(react@19.2.3))(react@19.2.3)
@@ -1066,7 +1072,7 @@ importers:
         version: link:../../packages/ai-solid-ui
       '@tanstack/nitro-v2-vite-plugin':
         specifier: ^1.154.7
-        version: 1.154.7(aws4fetch@1.0.20)(rolldown@1.1.3)(vite@7.3.3(@types/node@24.10.3)(jiti@2.6.1)(less@4.6.6)(lightningcss@1.30.2)(sass@1.101.0)(terser@5.44.1)(tsx@4.21.0)(yaml@2.8.2))
+        version: 1.154.7(aws4fetch@1.0.20)(drizzle-orm@0.45.2(@cloudflare/workers-types@4.20260317.1)(@opentelemetry/api@1.9.1)(@prisma/client@6.19.3(prisma@6.19.3(typescript@5.9.3))(typescript@5.9.3))(@types/pg@8.20.0)(mysql2@3.22.5(@types/node@24.10.3))(pg@8.21.0)(prisma@6.19.3(typescript@5.9.3)))(mysql2@3.22.5(@types/node@24.10.3))(rolldown@1.1.3)(vite@7.3.3(@types/node@24.10.3)(jiti@2.6.1)(less@4.6.6)(lightningcss@1.30.2)(sass@1.101.0)(terser@5.44.1)(tsx@4.21.0)(yaml@2.8.2))
       '@tanstack/router-plugin':
         specifier: ^1.158.4
         version: 1.159.5(@tanstack/react-router@1.159.5(react-dom@19.2.3(react@19.2.3))(react@19.2.3))(vite-plugin-solid@2.11.10(solid-js@1.9.10)(vite@7.3.3(@types/node@24.10.3)(jiti@2.6.1)(less@4.6.6)(lightningcss@1.30.2)(sass@1.101.0)(terser@5.44.1)(tsx@4.21.0)(yaml@2.8.2)))(vite@7.3.3(@types/node@24.10.3)(jiti@2.6.1)(less@4.6.6)(lightningcss@1.30.2)(sass@1.101.0)(terser@5.44.1)(tsx@4.21.0)(yaml@2.8.2))
@@ -1312,8 +1318,8 @@ importers:
   packages/ai:
     dependencies:
       '@ag-ui/core':
-        specifier: ^0.0.52
-        version: 0.0.52
+        specifier: ^0.0.57
+        version: 0.0.57
       '@standard-schema/spec':
         specifier: ^1.1.0
         version: 1.1.0
@@ -1658,6 +1664,15 @@ importers:
         specifier: ^2.11.10
         version: 2.11.10(solid-js@1.9.10)(vite@7.3.3(@types/node@24.10.3)(jiti@2.6.1)(less@4.6.6)(lightningcss@1.30.2)(sass@1.101.0)(terser@5.44.1)(tsx@4.21.0)(yaml@2.8.2))
 
+  packages/ai-durable-stream:
+    devDependencies:
+      '@tanstack/ai':
+        specifier: workspace:*
+        version: link:../ai
+      '@vitest/coverage-v8':
+        specifier: 4.0.14
+        version: 4.0.14(vitest@4.1.4)
+
   packages/ai-elevenlabs:
     dependencies:
       '@elevenlabs/client':
@@ -1971,6 +1986,58 @@ importers:
         specifier: ^4.2.0
         version: 4.3.6
 
+  packages/ai-persistence:
+    dependencies:
+      '@tanstack/ai-utils':
+        specifier: workspace:*
+        version: link:../ai-utils
+    devDependencies:
+      '@tanstack/ai':
+        specifier: workspace:*
+        version: link:../ai
+      '@vitest/coverage-v8':
+        specifier: 4.0.14
+        version: 4.0.14(vitest@4.1.4)
+      vitest:
+        specifier: ^4.0.14
+        version: 4.1.4(@opentelemetry/api@1.9.1)(@types/node@24.10.3)(@vitest/coverage-v8@4.0.14)(happy-dom@20.0.11)(jsdom@27.3.0(postcss@8.5.15))(vite@7.3.3(@types/node@24.10.3)(jiti@2.6.1)(less@4.6.6)(lightningcss@1.30.2)(sass@1.101.0)(terser@5.44.1)(tsx@4.21.0)(yaml@2.8.2))
+
+  packages/ai-persistence-drizzle:
+    devDependencies:
+      '@tanstack/ai':
+        specifier: workspace:*
+        version: link:../ai
+      '@tanstack/ai-persistence':
+        specifier: workspace:*
+        version: link:../ai-persistence
+      '@vitest/coverage-v8':
+        specifier: 4.0.14
+        version: 4.0.14(vitest@4.1.4)
+      drizzle-kit:
+        specifier: ^0.31.0
+        version: 0.31.10
+      drizzle-orm:
+        specifier: ^0.45.0
+        version: 0.45.2(@cloudflare/workers-types@4.20260317.1)(@opentelemetry/api@1.9.1)(@prisma/client@6.19.3(prisma@6.19.3(typescript@5.9.3))(typescript@5.9.3))(@types/pg@8.20.0)(mysql2@3.22.5(@types/node@24.10.3))(pg@8.21.0)(prisma@6.19.3(typescript@5.9.3))
+
+  packages/ai-persistence-prisma:
+    devDependencies:
+      '@prisma/client':
+        specifier: ^6.19.3
+        version: 6.19.3(prisma@6.19.3(typescript@5.9.3))(typescript@5.9.3)
+      '@tanstack/ai':
+        specifier: workspace:*
+        version: link:../ai
+      '@tanstack/ai-persistence':
+        specifier: workspace:*
+        version: link:../ai-persistence
+      '@vitest/coverage-v8':
+        specifier: 4.0.14
+        version: 4.0.14(vitest@4.1.4)
+      prisma:
+        specifier: ^6.19.3
+        version: 6.19.3(magicast@0.5.2)(typescript@5.9.3)
+
   packages/ai-preact:
     dependencies:
       '@tanstack/ai-client':
@@ -2085,6 +2152,9 @@ importers:
       '@tanstack/ai':
         specifier: workspace:*
         version: link:../ai
+      '@tanstack/ai-persistence':
+        specifier: workspace:*
+        version: link:../ai-persistence
       '@vitest/coverage-v8':
         specifier: 4.0.14
         version: 4.0.14(vitest@4.1.4)
@@ -2518,6 +2588,9 @@ importers:
       '@tanstack/ai-openrouter':
         specifier: workspace:*
         version: link:../../packages/ai-openrouter
+      '@tanstack/ai-persistence':
+        specifier: workspace:*
+        version: link:../../packages/ai-persistence
       '@tanstack/ai-react':
         specifier: workspace:*
         version: link:../../packages/ai-react
@@ -2529,7 +2602,7 @@ importers:
         version: 0.4.1
       '@tanstack/nitro-v2-vite-plugin':
         specifier: ^1.154.7
-        version: 1.154.7(aws4fetch@1.0.20)(rolldown@1.1.3)(vite@7.3.3(@types/node@24.10.3)(jiti@2.6.1)(less@4.6.6)(lightningcss@1.30.2)(sass@1.101.0)(terser@5.44.1)(tsx@4.21.0)(yaml@2.8.2))
+        version: 1.154.7(aws4fetch@1.0.20)(drizzle-orm@0.45.2(@cloudflare/workers-types@4.20260317.1)(@opentelemetry/api@1.9.1)(@prisma/client@6.19.3(prisma@6.19.3(typescript@5.9.3))(typescript@5.9.3))(@types/pg@8.20.0)(mysql2@3.22.5(@types/node@24.10.3))(pg@8.21.0)(prisma@6.19.3(typescript@5.9.3)))(mysql2@3.22.5(@types/node@24.10.3))(rolldown@1.1.3)(vite@7.3.3(@types/node@24.10.3)(jiti@2.6.1)(less@4.6.6)(lightningcss@1.30.2)(sass@1.101.0)(terser@5.44.1)(tsx@4.21.0)(yaml@2.8.2))
       '@tanstack/react-ai-devtools':
         specifier: workspace:*
         version: link:../../packages/react-ai-devtools
@@ -2641,7 +2714,7 @@ importers:
         version: link:../../packages/ai-react-ui
       '@tanstack/nitro-v2-vite-plugin':
         specifier: ^1.154.7
-        version: 1.154.7(aws4fetch@1.0.20)(rolldown@1.1.3)(vite@7.3.3(@types/node@24.10.3)(jiti@2.6.1)(less@4.6.6)(lightningcss@1.30.2)(sass@1.101.0)(terser@5.44.1)(tsx@4.21.0)(yaml@2.8.2))
+        version: 1.154.7(aws4fetch@1.0.20)(drizzle-orm@0.45.2(@cloudflare/workers-types@4.20260317.1)(@opentelemetry/api@1.9.1)(@prisma/client@6.19.3(prisma@6.19.3(magicast@0.5.2)(typescript@5.9.3))(typescript@5.9.3))(@types/pg@8.20.0)(mysql2@3.22.5(@types/node@24.10.3))(pg@8.21.0)(prisma@6.19.3(magicast@0.5.2)(typescript@5.9.3)))(mysql2@3.22.5(@types/node@24.10.3))(rolldown@1.1.3)(vite@7.3.3(@types/node@24.10.3)(jiti@2.6.1)(less@4.6.6)(lightningcss@1.30.2)(sass@1.101.0)(terser@5.44.1)(tsx@4.21.0)(yaml@2.8.2))
       '@tanstack/react-router':
         specifier: ^1.158.4
         version: 1.159.5(react-dom@19.2.3(react@19.2.3))(react@19.2.3)
@@ -2650,7 +2723,7 @@ importers:
         version: 1.159.5(crossws@0.4.6(srvx@0.11.17))(react-dom@19.2.3(react@19.2.3))(react@19.2.3)(vite-plugin-solid@2.11.10(solid-js@1.9.10)(vite@7.3.3(@types/node@24.10.3)(jiti@2.6.1)(less@4.6.6)(lightningcss@1.30.2)(sass@1.101.0)(terser@5.44.1)(tsx@4.21.0)(yaml@2.8.2)))(vite@7.3.3(@types/node@24.10.3)(jiti@2.6.1)(less@4.6.6)(lightningcss@1.30.2)(sass@1.101.0)(terser@5.44.1)(tsx@4.21.0)(yaml@2.8.2))
       '@tanstack/start':
         specifier: ^1.120.20
-        version: 1.120.20(@types/node@24.10.3)(aws4fetch@1.0.20)(crossws@0.4.6(srvx@0.11.17))(db0@0.3.4)(ioredis@5.8.2)(jiti@2.6.1)(less@4.6.6)(lightningcss@1.30.2)(react-dom@19.2.3(react@19.2.3))(react@19.2.3)(rolldown@1.1.3)(sass@1.101.0)(terser@5.44.1)(tsx@4.21.0)(vite-plugin-solid@2.11.10(solid-js@1.9.10)(vite@7.3.3(@types/node@24.10.3)(jiti@2.6.1)(less@4.6.6)(lightningcss@1.30.2)(sass@1.101.0)(terser@5.44.1)(tsx@4.21.0)(yaml@2.8.2)))(vite@7.3.3(@types/node@24.10.3)(jiti@2.6.1)(less@4.6.6)(lightningcss@1.30.2)(sass@1.101.0)(terser@5.44.1)(tsx@4.21.0)(yaml@2.8.2))(yaml@2.8.2)
+        version: 1.120.20(647307324c217c342a2641e0cabd8372)
       highlight.js:
         specifier: ^11.11.1
         version: 11.11.1
@@ -2752,8 +2825,8 @@ packages:
   '@acemir/cssom@0.9.29':
     resolution: {integrity: sha512-G90x0VW+9nW4dFajtjCoT+NM0scAfH9Mb08IcjgFHYbfiL/lU04dTF9JuVOi3/OH+DJCQdcIseSXkdCB9Ky6JA==}
 
-  '@ag-ui/core@0.0.52':
-    resolution: {integrity: sha512-Xo0bUaNV56EqylzcrAuhUkQX7et7+SZIrqZZtEByGwEq/I1EHny6ZMkWHLkKR7UNi0FJZwJyhKYmKJS3B2SEgA==}
+  '@ag-ui/core@0.0.57':
+    resolution: {integrity: sha512-gho1OWjNE6E3Rl7ZEZ1wr2CEpUHjLFU0FqzCZZk439TicLu+BfLCMkMokB07bMGlRmbJ60hM6LW60iOVauCx+Q==}
 
   '@agentclientprotocol/sdk@0.25.1':
     resolution: {integrity: sha512-jx2rF3bdpGwZ75Q/meyEDLLbYmbtxk82Uh9hDCdxDvcEedBnNSF5hZAnL/kJR5VNz56JqwOmqnAqasC84MwwkQ==}
@@ -3854,6 +3927,9 @@ packages:
   '@deno/shim-deno@0.19.2':
     resolution: {integrity: sha512-q3VTHl44ad8T2Tw2SpeAvghdGOjlnLPDNO2cpOxwMrBE/PVas6geWpbpIgrM+czOCH0yejp0yi8OaTuB+NU40Q==}
 
+  '@drizzle-team/brocli@0.10.2':
+    resolution: {integrity: sha512-z33Il7l5dKjUgGULTqBsQBQwckHh5AbIuxhdsIxDDiZAzBOrZO6q9ogcWC65kU382AfynTfgNumVcNIjuIua6w==}
+
   '@elevenlabs/client@1.3.1':
     resolution: {integrity: sha512-bQUxA/X7TZRSSZ6UM6a6A+1qQy5Wh7vMn+zbZP6Yl1WrupxHL4M0XMnl/n9+fsol1Ib4tN/2Nhx1E5JDS7QdKw==}
 
@@ -3891,6 +3967,14 @@ packages:
   '@emnapi/wasi-threads@1.2.2':
     resolution: {integrity: sha512-c95qOXkHdydNKhscBTebqEC1CVAZpyqOfVfBzQ1qgzyl3gfeldUjIggDbIZgDKsHLgnsM+igH7TJ/eAasaVuMA==}
 
+  '@esbuild-kit/core-utils@3.3.2':
+    resolution: {integrity: sha512-sPRAnw9CdSsRmEtnsl2WXWdyquogVpB3yZ3dgwJfe8zrOzTsV7cJvmwrKVa+0ma5BoiGJ+BoqkMvawbayKUsqQ==}
+    deprecated: 'Merged into tsx: https://tsx.is'
+
+  '@esbuild-kit/esm-loader@2.6.5':
+    resolution: {integrity: sha512-FxEMIkJKnodyA1OaCUoEvbYRkoZlLZ4d/eXFu9Fh8CbBBgP5EmZxrfTRyN0qpXZ4vOvqnE5YdRdcrmUUXuU+dA==}
+    deprecated: 'Merged into tsx: https://tsx.is'
+
   '@esbuild/aix-ppc64@0.20.2':
     resolution: {integrity: sha512-D+EBOJHXdNZcLJRBkhENNG8Wji2kgc9AZ9KiPr1JuZjsNtyHzrsfLRrY0tk2H2aoFu6RANO1y1iPPUCDYWkb5g==}
     engines: {node: '>=12'}
@@ -3921,6 +4005,12 @@ packages:
     cpu: [ppc64]
     os: [aix]
 
+  '@esbuild/android-arm64@0.18.20':
+    resolution: {integrity: sha512-Nz4rJcchGDtENV0eMKUNa6L12zz2zBDXuhj/Vjh18zGqB44Bi7MBMSXjgunJgjRhCmKOjnPuZp4Mb6OKqtMHLQ==}
+    engines: {node: '>=12'}
+    cpu: [arm64]
+    os: [android]
+
   '@esbuild/android-arm64@0.20.2':
     resolution: {integrity: sha512-mRzjLacRtl/tWU0SvD8lUEwb61yP9cqQo6noDZP/O8VkwafSYwZ4yWy24kan8jE/IMERpYncRt2dw438LP3Xmg==}
     engines: {node: '>=12'}
@@ -3951,6 +4041,12 @@ packages:
     cpu: [arm64]
     os: [android]
 
+  '@esbuild/android-arm@0.18.20':
+    resolution: {integrity: sha512-fyi7TDI/ijKKNZTUJAQqiG5T7YjJXgnzkURqmGj13C6dCqckZBLdl4h7bkhHt/t0WP+zO9/zwroDvANaOqO5Sw==}
+    engines: {node: '>=12'}
+    cpu: [arm]
+    os: [android]
+
   '@esbuild/android-arm@0.20.2':
     resolution: {integrity: sha512-t98Ra6pw2VaDhqNWO2Oph2LXbz/EJcnLmKLGBJwEwXX/JAN83Fym1rU8l0JUWK6HkIbWONCSSatf4sf2NBRx/w==}
     engines: {node: '>=12'}
@@ -3981,6 +4077,12 @@ packages:
     cpu: [arm]
     os: [android]
 
+  '@esbuild/android-x64@0.18.20':
+    resolution: {integrity: sha512-8GDdlePJA8D6zlZYJV/jnrRAi6rOiNaCC/JclcXpB+KIuvfBN4owLtgzY2bsxnx666XjJx2kDPUmnTtR8qKQUg==}
+    engines: {node: '>=12'}
+    cpu: [x64]
+    os: [android]
+
   '@esbuild/android-x64@0.20.2':
     resolution: {integrity: sha512-btzExgV+/lMGDDa194CcUQm53ncxzeBrWJcncOBxuC6ndBkKxnHdFJn86mCIgTELsooUmwUm9FkhSp5HYu00Rg==}
     engines: {node: '>=12'}
@@ -4011,6 +4113,12 @@ packages:
     cpu: [x64]
     os: [android]
 
+  '@esbuild/darwin-arm64@0.18.20':
+    resolution: {integrity: sha512-bxRHW5kHU38zS2lPTPOyuyTm+S+eobPUnTNkdJEfAddYgEcll4xkT8DB9d2008DtTbl7uJag2HuE5NZAZgnNEA==}
+    engines: {node: '>=12'}
+    cpu: [arm64]
+    os: [darwin]
+
   '@esbuild/darwin-arm64@0.20.2':
     resolution: {integrity: sha512-4J6IRT+10J3aJH3l1yzEg9y3wkTDgDk7TSDFX+wKFiWjqWp/iCfLIYzGyasx9l0SAFPT1HwSCR+0w/h1ES/MjA==}
     engines: {node: '>=12'}
@@ -4041,6 +4149,12 @@ packages:
     cpu: [arm64]
     os: [darwin]
 
+  '@esbuild/darwin-x64@0.18.20':
+    resolution: {integrity: sha512-pc5gxlMDxzm513qPGbCbDukOdsGtKhfxD1zJKXjCCcU7ju50O7MeAZ8c4krSJcOIJGFR+qx21yMMVYwiQvyTyQ==}
+    engines: {node: '>=12'}
+    cpu: [x64]
+    os: [darwin]
+
   '@esbuild/darwin-x64@0.20.2':
     resolution: {integrity: sha512-tBcXp9KNphnNH0dfhv8KYkZhjc+H3XBkF5DKtswJblV7KlT9EI2+jeA8DgBjp908WEuYll6pF+UStUCfEpdysA==}
     engines: {node: '>=12'}
@@ -4071,6 +4185,12 @@ packages:
     cpu: [x64]
     os: [darwin]
 
+  '@esbuild/freebsd-arm64@0.18.20':
+    resolution: {integrity: sha512-yqDQHy4QHevpMAaxhhIwYPMv1NECwOvIpGCZkECn8w2WFHXjEwrBn3CeNIYsibZ/iZEUemj++M26W3cNR5h+Tw==}
+    engines: {node: '>=12'}
+    cpu: [arm64]
+    os: [freebsd]
+
   '@esbuild/freebsd-arm64@0.20.2':
     resolution: {integrity: sha512-d3qI41G4SuLiCGCFGUrKsSeTXyWG6yem1KcGZVS+3FYlYhtNoNgYrWcvkOoaqMhwXSMrZRl69ArHsGJ9mYdbbw==}
     engines: {node: '>=12'}
@@ -4101,6 +4221,12 @@ packages:
     cpu: [arm64]
     os: [freebsd]
 
+  '@esbuild/freebsd-x64@0.18.20':
+    resolution: {integrity: sha512-tgWRPPuQsd3RmBZwarGVHZQvtzfEBOreNuxEMKFcd5DaDn2PbBxfwLcj4+aenoh7ctXcbXmOQIn8HI6mCSw5MQ==}
+    engines: {node: '>=12'}
+    cpu: [x64]
+    os: [freebsd]
+
   '@esbuild/freebsd-x64@0.20.2':
     resolution: {integrity: sha512-d+DipyvHRuqEeM5zDivKV1KuXn9WeRX6vqSqIDgwIfPQtwMP4jaDsQsDncjTDDsExT4lR/91OLjRo8bmC1e+Cw==}
     engines: {node: '>=12'}
@@ -4131,6 +4257,12 @@ packages:
     cpu: [x64]
     os: [freebsd]
 
+  '@esbuild/linux-arm64@0.18.20':
+    resolution: {integrity: sha512-2YbscF+UL7SQAVIpnWvYwM+3LskyDmPhe31pE7/aoTMFKKzIc9lLbyGUpmmb8a8AixOL61sQ/mFh3jEjHYFvdA==}
+    engines: {node: '>=12'}
+    cpu: [arm64]
+    os: [linux]
+
   '@esbuild/linux-arm64@0.20.2':
     resolution: {integrity: sha512-9pb6rBjGvTFNira2FLIWqDk/uaf42sSyLE8j1rnUpuzsODBq7FvpwHYZxQ/It/8b+QOS1RYfqgGFNLRI+qlq2A==}
     engines: {node: '>=12'}
@@ -4161,6 +4293,12 @@ packages:
     cpu: [arm64]
     os: [linux]
 
+  '@esbuild/linux-arm@0.18.20':
+    resolution: {integrity: sha512-/5bHkMWnq1EgKr1V+Ybz3s1hWXok7mDFUMQ4cG10AfW3wL02PSZi5kFpYKrptDsgb2WAJIvRcDm+qIvXf/apvg==}
+    engines: {node: '>=12'}
+    cpu: [arm]
+    os: [linux]
+
   '@esbuild/linux-arm@0.20.2':
     resolution: {integrity: sha512-VhLPeR8HTMPccbuWWcEUD1Az68TqaTYyj6nfE4QByZIQEQVWBB8vup8PpR7y1QHL3CpcF6xd5WVBU/+SBEvGTg==}
     engines: {node: '>=12'}
@@ -4191,6 +4329,12 @@ packages:
     cpu: [arm]
     os: [linux]
 
+  '@esbuild/linux-ia32@0.18.20':
+    resolution: {integrity: sha512-P4etWwq6IsReT0E1KHU40bOnzMHoH73aXp96Fs8TIT6z9Hu8G6+0SHSw9i2isWrD2nbx2qo5yUqACgdfVGx7TA==}
+    engines: {node: '>=12'}
+    cpu: [ia32]
+    os: [linux]
+
   '@esbuild/linux-ia32@0.20.2':
     resolution: {integrity: sha512-o10utieEkNPFDZFQm9CoP7Tvb33UutoJqg3qKf1PWVeeJhJw0Q347PxMvBgVVFgouYLGIhFYG0UGdBumROyiig==}
     engines: {node: '>=12'}
@@ -4221,6 +4365,12 @@ packages:
     cpu: [ia32]
     os: [linux]
 
+  '@esbuild/linux-loong64@0.18.20':
+    resolution: {integrity: sha512-nXW8nqBTrOpDLPgPY9uV+/1DjxoQ7DoB2N8eocyq8I9XuqJ7BiAMDMf9n1xZM9TgW0J8zrquIb/A7s3BJv7rjg==}
+    engines: {node: '>=12'}
+    cpu: [loong64]
+    os: [linux]
+
   '@esbuild/linux-loong64@0.20.2':
     resolution: {integrity: sha512-PR7sp6R/UC4CFVomVINKJ80pMFlfDfMQMYynX7t1tNTeivQ6XdX5r2XovMmha/VjR1YN/HgHWsVcTRIMkymrgQ==}
     engines: {node: '>=12'}
@@ -4251,6 +4401,12 @@ packages:
     cpu: [loong64]
     os: [linux]
 
+  '@esbuild/linux-mips64el@0.18.20':
+    resolution: {integrity: sha512-d5NeaXZcHp8PzYy5VnXV3VSd2D328Zb+9dEq5HE6bw6+N86JVPExrA6O68OPwobntbNJ0pzCpUFZTo3w0GyetQ==}
+    engines: {node: '>=12'}
+    cpu: [mips64el]
+    os: [linux]
+
   '@esbuild/linux-mips64el@0.20.2':
     resolution: {integrity: sha512-4BlTqeutE/KnOiTG5Y6Sb/Hw6hsBOZapOVF6njAESHInhlQAghVVZL1ZpIctBOoTFbQyGW+LsVYZ8lSSB3wkjA==}
     engines: {node: '>=12'}
@@ -4281,6 +4437,12 @@ packages:
     cpu: [mips64el]
     os: [linux]
 
+  '@esbuild/linux-ppc64@0.18.20':
+    resolution: {integrity: sha512-WHPyeScRNcmANnLQkq6AfyXRFr5D6N2sKgkFo2FqguP44Nw2eyDlbTdZwd9GYk98DZG9QItIiTlFLHJHjxP3FA==}
+    engines: {node: '>=12'}
+    cpu: [ppc64]
+    os: [linux]
+
   '@esbuild/linux-ppc64@0.20.2':
     resolution: {integrity: sha512-rD3KsaDprDcfajSKdn25ooz5J5/fWBylaaXkuotBDGnMnDP1Uv5DLAN/45qfnf3JDYyJv/ytGHQaziHUdyzaAg==}
     engines: {node: '>=12'}
@@ -4311,6 +4473,12 @@ packages:
     cpu: [ppc64]
     os: [linux]
 
+  '@esbuild/linux-riscv64@0.18.20':
+    resolution: {integrity: sha512-WSxo6h5ecI5XH34KC7w5veNnKkju3zBRLEQNY7mv5mtBmrP/MjNBCAlsM2u5hDBlS3NGcTQpoBvRzqBcRtpq1A==}
+    engines: {node: '>=12'}
+    cpu: [riscv64]
+    os: [linux]
+
   '@esbuild/linux-riscv64@0.20.2':
     resolution: {integrity: sha512-snwmBKacKmwTMmhLlz/3aH1Q9T8v45bKYGE3j26TsaOVtjIag4wLfWSiZykXzXuE1kbCE+zJRmwp+ZbIHinnVg==}
     engines: {node: '>=12'}
@@ -4341,6 +4509,12 @@ packages:
     cpu: [riscv64]
     os: [linux]
 
+  '@esbuild/linux-s390x@0.18.20':
+    resolution: {integrity: sha512-+8231GMs3mAEth6Ja1iK0a1sQ3ohfcpzpRLH8uuc5/KVDFneH6jtAJLFGafpzpMRO6DzJ6AvXKze9LfFMrIHVQ==}
+    engines: {node: '>=12'}
+    cpu: [s390x]
+    os: [linux]
+
   '@esbuild/linux-s390x@0.20.2':
     resolution: {integrity: sha512-wcWISOobRWNm3cezm5HOZcYz1sKoHLd8VL1dl309DiixxVFoFe/o8HnwuIwn6sXre88Nwj+VwZUvJf4AFxkyrQ==}
     engines: {node: '>=12'}
@@ -4371,6 +4545,12 @@ packages:
     cpu: [s390x]
     os: [linux]
 
+  '@esbuild/linux-x64@0.18.20':
+    resolution: {integrity: sha512-UYqiqemphJcNsFEskc73jQ7B9jgwjWrSayxawS6UVFZGWrAAtkzjxSqnoclCXxWtfwLdzU+vTpcNYhpn43uP1w==}
+    engines: {node: '>=12'}
+    cpu: [x64]
+    os: [linux]
+
   '@esbuild/linux-x64@0.20.2':
     resolution: {integrity: sha512-1MdwI6OOTsfQfek8sLwgyjOXAu+wKhLEoaOLTjbijk6E2WONYpH9ZU2mNtR+lZ2B4uwr+usqGuVfFT9tMtGvGw==}
     engines: {node: '>=12'}
@@ -4425,6 +4605,12 @@ packages:
     cpu: [arm64]
     os: [netbsd]
 
+  '@esbuild/netbsd-x64@0.18.20':
+    resolution: {integrity: sha512-iO1c++VP6xUBUmltHZoMtCUdPlnPGdBom6IrO4gyKPFFVBKioIImVooR5I83nTew5UOYrk3gIJhbZh8X44y06A==}
+    engines: {node: '>=12'}
+    cpu: [x64]
+    os: [netbsd]
+
   '@esbuild/netbsd-x64@0.20.2':
     resolution: {integrity: sha512-K8/DhBxcVQkzYc43yJXDSyjlFeHQJBiowJ0uVL6Tor3jGQfSGHNNJcWxNbOI8v5k82prYqzPuwkzHt3J1T1iZQ==}
     engines: {node: '>=12'}
@@ -4479,6 +4665,12 @@ packages:
     cpu: [arm64]
     os: [openbsd]
 
+  '@esbuild/openbsd-x64@0.18.20':
+    resolution: {integrity: sha512-e5e4YSsuQfX4cxcygw/UCPIEP6wbIL+se3sxPdCiMbFLBWu0eiZOJ7WoD+ptCLrmjZBK1Wk7I6D/I3NglUGOxg==}
+    engines: {node: '>=12'}
+    cpu: [x64]
+    os: [openbsd]
+
   '@esbuild/openbsd-x64@0.20.2':
     resolution: {integrity: sha512-eMpKlV0SThJmmJgiVyN9jTPJ2VBPquf6Kt/nAoo6DgHAoN57K15ZghiHaMvqjCye/uU4X5u3YSMgVBI1h3vKrQ==}
     engines: {node: '>=12'}
@@ -4533,6 +4725,12 @@ packages:
     cpu: [arm64]
     os: [openharmony]
 
+  '@esbuild/sunos-x64@0.18.20':
+    resolution: {integrity: sha512-kDbFRFp0YpTQVVrqUd5FTYmWo45zGaXe0X8E1G/LKFC0v8x0vWrhOWSLITcCn63lmZIxfOMXtCfti/RxN/0wnQ==}
+    engines: {node: '>=12'}
+    cpu: [x64]
+    os: [sunos]
+
   '@esbuild/sunos-x64@0.20.2':
     resolution: {integrity: sha512-2UyFtRC6cXLyejf/YEld4Hajo7UHILetzE1vsRcGL3earZEW77JxrFjH4Ez2qaTiEfMgAXxfAZCm1fvM/G/o8w==}
     engines: {node: '>=12'}
@@ -4563,6 +4761,12 @@ packages:
     cpu: [x64]
     os: [sunos]
 
+  '@esbuild/win32-arm64@0.18.20':
+    resolution: {integrity: sha512-ddYFR6ItYgoaq4v4JmQQaAI5s7npztfV4Ag6NrhiaW0RrnOXqBkgwZLofVTlq1daVTQNhtI5oieTvkRPfZrePg==}
+    engines: {node: '>=12'}
+    cpu: [arm64]
+    os: [win32]
+
   '@esbuild/win32-arm64@0.20.2':
     resolution: {integrity: sha512-GRibxoawM9ZCnDxnP3usoUDO9vUkpAxIIZ6GQI+IlVmr5kP3zUq+l17xELTHMWTWzjxa2guPNyrpq1GWmPvcGQ==}
     engines: {node: '>=12'}
@@ -4593,6 +4797,12 @@ packages:
     cpu: [arm64]
     os: [win32]
 
+  '@esbuild/win32-ia32@0.18.20':
+    resolution: {integrity: sha512-Wv7QBi3ID/rROT08SABTS7eV4hX26sVduqDOTe1MvGMjNd3EjOz4b7zeexIR62GTIEKrfJXKL9LFxTYgkyeu7g==}
+    engines: {node: '>=12'}
+    cpu: [ia32]
+    os: [win32]
+
   '@esbuild/win32-ia32@0.20.2':
     resolution: {integrity: sha512-HfLOfn9YWmkSKRQqovpnITazdtquEW8/SoHW7pWpuEeguaZI4QnCRW6b+oZTztdBnZOS2hqJ6im/D5cPzBTTlQ==}
     engines: {node: '>=12'}
@@ -4623,6 +4833,12 @@ packages:
     cpu: [ia32]
     os: [win32]
 
+  '@esbuild/win32-x64@0.18.20':
+    resolution: {integrity: sha512-kTdfRcSiDfQca/y9QIkng02avJ+NCaQvrMejlsB3RRv5sE9rRoeBPISaZpKxHELzRxZyLvNts1P27W3wV+8geQ==}
+    engines: {node: '>=12'}
+    cpu: [x64]
+    os: [win32]
+
   '@esbuild/win32-x64@0.20.2':
     resolution: {integrity: sha512-N49X4lJX27+l9jbLKSqZ6bKNjzQvHaT8IIFUy+YIqmXQdjYCToGWwOItDrfby14c78aDd5NHQl29xingXfCdLQ==}
     engines: {node: '>=12'}
@@ -6396,6 +6612,36 @@ packages:
   '@poppinss/exception@1.2.3':
     resolution: {integrity: sha512-dCED+QRChTVatE9ibtoaxc+WkdzOSjYTKi/+uacHWIsfodVfpsueo3+DKpgU5Px8qXjgmXkSvhXvSCz3fnP9lw==}
 
+  '@prisma/client@6.19.3':
+    resolution: {integrity: sha512-mKq3jQFhjvko5LTJFHGilsuQs+W+T3Gm451NzuTDGQxwCzwXHYnIu2zGkRoW+Exq3Rob7yp2MfzSrdIiZVhrBg==}
+    engines: {node: '>=18.18'}
+    peerDependencies:
+      prisma: '*'
+      typescript: '>=5.1.0'
+    peerDependenciesMeta:
+      prisma:
+        optional: true
+      typescript:
+        optional: true
+
+  '@prisma/config@6.19.3':
+    resolution: {integrity: sha512-CBPT44BjlQxEt8kiMEauji2WHTDoVBOKl7UlewXmUgBPnr/oPRZC3psci5chJnYmH0ivEIog2OU9PGWoki3DLQ==}
+
+  '@prisma/debug@6.19.3':
+    resolution: {integrity: sha512-ljkJ+SgpXNktLG0Q/n4JGYCkKf0f8oYLyjImS2I8e2q2WCfdRRtWER062ZV/ixaNP2M2VKlWXVJiGzZaUgbKZw==}
+
+  '@prisma/engines-version@7.1.1-3.c2990dca591cba766e3b7ef5d9e8a84796e47ab7':
+    resolution: {integrity: sha512-03bgb1VD5gvuumNf+7fVGBzfpJPjmqV423l/WxsWk2cNQ42JD0/SsFBPhN6z8iAvdHs07/7ei77SKu7aZfq8bA==}
+
+  '@prisma/engines@6.19.3':
+    resolution: {integrity: sha512-RSYxtlYFl5pJ8ZePgMv0lZ9IzVCOdTPOegrs2qcbAEFrBI1G33h6wyC9kjQvo0DnYEhEVY0X4LsuFHXLKQk88g==}
+
+  '@prisma/fetch-engine@6.19.3':
+    resolution: {integrity: sha512-tKtl/qco9Nt7LU5iKhpultD8O4vMCZcU2CHjNTnRrL1QvSUr5W/GcyFPjNL87GtRrwBc7ubXXD9xy4EvLvt8JA==}
+
+  '@prisma/get-platform@6.19.3':
+    resolution: {integrity: sha512-xFj1VcJ1N3MKooOQAGO0W5tsd0W2QzIvW7DD7c/8H14Zmp4jseeWAITm+w2LLoLrlhoHdPPh0NMZ8mfL6puoHA==}
+
   '@protobufjs/aspromise@1.1.2':
     resolution: {integrity: sha512-j+gKExEuLmKwvz3OgROXtrJ2UG2x8Ch2YZUxahh+s1F2HZ+wAceUNLkvy6zKCPVRkU++ZWQrdxsUeQXmcg4uoQ==}
 
@@ -8931,6 +9177,9 @@ packages:
   '@types/node@24.10.3':
     resolution: {integrity: sha512-gqkrWUsS8hcm0r44yn7/xZeV1ERva/nLgrLxFRUGb7aoNMIJfZJ3AC261zDQuOAKC7MiXai1WCpYc48jAHoShQ==}
 
+  '@types/pg@8.20.0':
+    resolution: {integrity: sha512-bEPFOaMAHTEP1EzpvHTbmwR8UsFyHSKsRisLIHVMXnpNefSbGA1bD6CVy+qKjGSqmZqNqBDV2azOBo8TgkcVow==}
+
   '@types/react-dom@19.2.3':
     resolution: {integrity: sha512-jp2L/eY6fn+KgVVQAOqYItbF0VY/YApe5Mz2F0aykSO8gx31bYCZyvSeYxCHKvzHG5eZjc+zyaS5BrBWya2+kQ==}
     peerDependencies:
@@ -9611,6 +9860,10 @@ packages:
     resolution: {integrity: sha512-wvUjBtSGN7+7SjNpq/9M2Tg350UZD3q62IFZLbRAR1bSMlCo1ZaeW+BJ+D090e4hIIZLBcTDWe4Mh4jvUDajzQ==}
     engines: {node: '>= 0.4'}
 
+  aws-ssl-profiles@1.1.2:
+    resolution: {integrity: sha512-NZKeq9AfyQvEeNlN0zSYAaWrmBffJh3IELMZfRpJVWgrpEbtEpnjvzqBPf+mxoI287JohRDoa+/nsfqqiZmF6g==}
+    engines: {node: '>= 6.0.0'}
+
   aws4fetch@1.0.20:
     resolution: {integrity: sha512-/djoAN709iY65ETD6LKCtyyEI04XIBP5xVvfmNxsEP0uJB5tyaGBztSryRr4HqMStr9R06PisQE7m9zDTXKu6g==}
 
@@ -9881,6 +10134,14 @@ packages:
     resolution: {integrity: sha512-/Nf7TyzTx6S3yRJObOAV7956r8cr2+Oj8AC5dt8wSP3BQAoeX58NoHyCU8P8zGkNXStjTSi6fzO6F0pBdcYbEg==}
     engines: {node: '>= 0.8'}
 
+  c12@3.1.0:
+    resolution: {integrity: sha512-uWoS8OU1MEIsOv8p/5a82c3H31LsWVR5qiyXVfBNOzfffjUWtPnhAb4BYI2uG2HfGmZmFjCtui5XNWaps+iFuw==}
+    peerDependencies:
+      magicast: ^0.3.5
+    peerDependenciesMeta:
+      magicast:
+        optional: true
+
   c12@3.3.2:
     resolution: {integrity: sha512-QkikB2X5voO1okL3QsES0N690Sn/K9WokXqUsDQsWy5SnYb+psYQFGA10iy1bZHj3fjISKsI67Q90gruvWWM3A==}
     peerDependencies:
@@ -10460,6 +10721,10 @@ packages:
   deep-is@0.1.4:
     resolution: {integrity: sha512-oIPzksmTg4/MriiaYGO+okXDT7ztn/w3Eptv/+gSIdMdKsJo0u4CfYNFJPy+4SKMuCqGw2wxnA+URMg3t8a/bQ==}
 
+  deepmerge-ts@7.1.5:
+    resolution: {integrity: sha512-HOJkrhaYsweh+W+e74Yn7YStZOilkoPb6fycpwNLKzSPtruFs48nYis0zy5yJz1+ktUhHxoRDJ27RQAWLIJVJw==}
+    engines: {node: '>=16.0.0'}
+
   deepmerge@4.3.1:
     resolution: {integrity: sha512-3sUqbMEc77XqpdNO7FRyRog+eW3ph+GYCbj+rK+uYyRMuwsVy0rMiVtPn+QJlKFvWP/1PYpapqYn0Me2knFn+A==}
     engines: {node: '>=0.10.0'}
@@ -10600,6 +10865,102 @@ packages:
     resolution: {integrity: sha512-IrPdXQsk2BbzvCBGBOTmmSH5SodmqZNt4ERAZDmW4CT+tL8VtvinqywuANaFu4bOMWki16nqf0e4oC0QIaDr/g==}
     engines: {node: '>=10'}
 
+  drizzle-kit@0.31.10:
+    resolution: {integrity: sha512-7OZcmQUrdGI+DUNNsKBn1aW8qSoKuTH7d0mYgSP8bAzdFzKoovxEFnoGQp2dVs82EOJeYycqRtciopszwUf8bw==}
+    hasBin: true
+
+  drizzle-orm@0.45.2:
+    resolution: {integrity: sha512-kY0BSaTNYWnoDMVoyY8uxmyHjpJW1geOmBMdSSicKo9CIIWkSxMIj2rkeSR51b8KAPB7m+qysjuHme5nKP+E5Q==}
+    peerDependencies:
+      '@aws-sdk/client-rds-data': '>=3'
+      '@cloudflare/workers-types': '>=4'
+      '@electric-sql/pglite': '>=0.2.0'
+      '@libsql/client': '>=0.10.0'
+      '@libsql/client-wasm': '>=0.10.0'
+      '@neondatabase/serverless': '>=0.10.0'
+      '@op-engineering/op-sqlite': '>=2'
+      '@opentelemetry/api': ^1.4.1
+      '@planetscale/database': '>=1.13'
+      '@prisma/client': '*'
+      '@tidbcloud/serverless': '*'
+      '@types/better-sqlite3': '*'
+      '@types/pg': '*'
+      '@types/sql.js': '*'
+      '@upstash/redis': '>=1.34.7'
+      '@vercel/postgres': '>=0.8.0'
+      '@xata.io/client': '*'
+      better-sqlite3: '>=7'
+      bun-types: '*'
+      expo-sqlite: '>=14.0.0'
+      gel: '>=2'
+      knex: '*'
+      kysely: '*'
+      mysql2: '>=2'
+      pg: '>=8'
+      postgres: '>=3'
+      prisma: '*'
+      sql.js: '>=1'
+      sqlite3: '>=5'
+    peerDependenciesMeta:
+      '@aws-sdk/client-rds-data':
+        optional: true
+      '@cloudflare/workers-types':
+        optional: true
+      '@electric-sql/pglite':
+        optional: true
+      '@libsql/client':
+        optional: true
+      '@libsql/client-wasm':
+        optional: true
+      '@neondatabase/serverless':
+        optional: true
+      '@op-engineering/op-sqlite':
+        optional: true
+      '@opentelemetry/api':
+        optional: true
+      '@planetscale/database':
+        optional: true
+      '@prisma/client':
+        optional: true
+      '@tidbcloud/serverless':
+        optional: true
+      '@types/better-sqlite3':
+        optional: true
+      '@types/pg':
+        optional: true
+      '@types/sql.js':
+        optional: true
+      '@upstash/redis':
+        optional: true
+      '@vercel/postgres':
+        optional: true
+      '@xata.io/client':
+        optional: true
+      better-sqlite3:
+        optional: true
+      bun-types:
+        optional: true
+      expo-sqlite:
+        optional: true
+      gel:
+        optional: true
+      knex:
+        optional: true
+      kysely:
+        optional: true
+      mysql2:
+        optional: true
+      pg:
+        optional: true
+      postgres:
+        optional: true
+      prisma:
+        optional: true
+      sql.js:
+        optional: true
+      sqlite3:
+        optional: true
+
   dts-resolver@2.1.3:
     resolution: {integrity: sha512-bihc7jPC90VrosXNzK0LTE2cuLP6jr0Ro8jk+kMugHReJVLIpHz/xadeq3MhuwyO4TD4OA3L1Q8pBBFRc08Tsw==}
     engines: {node: '>=20.19.0'}
@@ -10630,6 +10991,9 @@ packages:
   ee-first@1.1.1:
     resolution: {integrity: sha512-WMwm9LhRUo+WUaRN+vRuETqG89IgZphVSNkdFgeb6sS/E4OrDIN7t48CAewSHXc6C8lefD8KKfr5vY61brQlow==}
 
+  effect@3.21.0:
+    resolution: {integrity: sha512-PPN80qRokCd1f015IANNhrwOnLO7GrrMQfk4/lnZRE/8j7UPWrNNjPV0uBrZutI/nHzernbW+J0hdqQysHiSnQ==}
+
   electron-to-chromium@1.5.267:
     resolution: {integrity: sha512-0Drusm6MVRXSOJpGbaSVgcQsuB4hEkMpHXaVstcPmhu5LIedxs1xNK/nIxmQIU/RPC0+1/o0AVZfBTkTNJOdUw==}
 
@@ -10750,6 +11114,11 @@ packages:
       esbuild: '>=0.12'
       solid-js: '>= 1.0'
 
+  esbuild@0.18.20:
+    resolution: {integrity: sha512-ceqxoedUrcayh7Y7ZX6NdbbDzGROiyVBgC4PriJThBKSVPWnnFHZAkfI1lJT8QFkOwH4qOS2SJkS4wvpGl8BpA==}
+    engines: {node: '>=12'}
+    hasBin: true
+
   esbuild@0.20.2:
     resolution: {integrity: sha512-WdOOppmUNU+IbZ0PaDiTst80zjnrOkyJNHoKupIcVyU8Lvla3Ugx94VzkQ32Ijqd7UhHJy75gNWDMUekcrSJ6g==}
     engines: {node: '>=12'}
@@ -11085,6 +11454,10 @@ packages:
     engines: {node: '>= 10.17.0'}
     hasBin: true
 
+  fast-check@3.23.2:
+    resolution: {integrity: sha512-h5+1OzzfCC3Ef7VbtKdcv7zsstUQwUDlYpUTvjeUsJAssPgLn7QzbboPtL5ro04Mq0rPOsMzl7q5hIbRs2wD1A==}
+    engines: {node: '>=8.0.0'}
+
   fast-deep-equal@3.1.3:
     resolution: {integrity: sha512-f3qQ9oQy9j2AhBe/H9VC91wLmKBCCU/gDOnKNAYG5hswO7BLKj09Hc5HYNz9cGI++xlpDCIgDaitVs03ATR84Q==}
 
@@ -11331,6 +11704,9 @@ packages:
     resolution: {integrity: sha512-zV/5HKTfCeKWnxG0Dmrw51hEWFGfcF2xiXqcA3+J90WDuP0SvoiSO5ORvcBsifmx/FoIjgQN3oNOGaQ5PhLFkg==}
     engines: {node: '>=18'}
 
+  generate-function@2.3.1:
+    resolution: {integrity: sha512-eeB5GfMNeevm/GRYq20ShmsaGcmI81kIX2K9XQx5miC8KdHaC6Jm0qQ8ZNeGOi7wYB8OsdxKs+Y2oVuTFuVwKQ==}
+
   gensync@1.0.0-beta.2:
     resolution: {integrity: sha512-3hN7NaskYvMDLQY55gnW3NQ+mesEAepTqlg+VEbj7zzqEMBVNhzcGYYeqFo/TlYz6eQiFcp1HcsCZO+nGgS8zg==}
     engines: {node: '>=6.9.0'}
@@ -11669,6 +12045,10 @@ packages:
     resolution: {integrity: sha512-2Tth85cXwGFHfvRgZWszZSvdo+0Xsqmw8k8ZwxScfcBneNUraK+dxRxRm24nszx80Y0TVio8kKLt5sLE7ZCLlw==}
     engines: {node: '>=0.10.0'}
 
+  iconv-lite@0.7.2:
+    resolution: {integrity: sha512-im9DjEDQ55s9fL4EYzOAv0yMqmMBSZp6G0VvFyTMPKWxiSBHUj9NW/qqLmXUwXrrM7AvqSlTCfvqRb0cM8yYqw==}
+    engines: {node: '>=0.10.0'}
+
   ieee754@1.2.1:
     resolution: {integrity: sha512-dcyqhDvX1C46lXZcVqCpK+FtMRQVdIMN6/Df5js2zouUsqG7I6sFxitIC+7KYK29KdXOLHdu9zL4sFnoVQnqaA==}
 
@@ -11884,6 +12264,9 @@ packages:
   is-promise@4.0.0:
     resolution: {integrity: sha512-hvpoI6korhJMnej285dSg6nu1+e6uxs7zG3BYAm5byqDsgJNWwxzM6z6iZiAgQR4TJ30JmBTOwqZUw3WlyH3AQ==}
 
+  is-property@1.0.2:
+    resolution: {integrity: sha512-Ks/IoX00TtClbGQr4TWXemAnktAQvYB7HzcCxDGqEZU6oCmb2INHuOoKxbtR+HFkmYWBKv/dOZtGRiAjDhj92g==}
+
   is-reference@1.2.1:
     resolution: {integrity: sha512-U82MsXXiFIrjCK4otLT+o2NA2Cd2g5MLoOVXUZjIOhLurrRxpEXzI8O0KZHr3IjLvlAH1kTPYSuqer5T9ZVBKQ==}
 
@@ -12445,6 +12828,10 @@ packages:
     resolution: {integrity: sha512-jumlc0BIUrS3qJGgIkWZsyfAM7NCWiBcCDhnd+3NNM5KbBmLTgHVfWBcg6W+rLUsIpzpERPsvwUP7CckAQSOoA==}
     engines: {node: '>=12'}
 
+  lru.min@1.1.4:
+    resolution: {integrity: sha512-DqC6n3QQ77zdFpCMASA1a3Jlb64Hv2N2DciFGkO/4L9+q/IpIAuRlKOvCXabtRW6cQf8usbmM6BE/TOPysCdIA==}
+    engines: {bun: '>=1.0.0', deno: '>=1.30.0', node: '>=8.0.0'}
+
   lucide-react@0.561.0:
     resolution: {integrity: sha512-Y59gMY38tl4/i0qewcqohPdEbieBy7SovpBL9IFebhc2mDd8x4PZSOsiFRkpPcOq6bj1r/mjH/Rk73gSlIJP2A==}
     peerDependencies:
@@ -12922,9 +13309,19 @@ packages:
     resolution: {integrity: sha512-WWdIxpyjEn+FhQJQQv9aQAYlHoNVdzIzUySNV1gHUPDSdZJ3yZn7pAAbQcV7B56Mvu881q9FZV+0Vx2xC44VWA==}
     engines: {node: ^18.17.0 || >=20.5.0}
 
+  mysql2@3.22.5:
+    resolution: {integrity: sha512-95uZ2TrPWAZdwpB3vvvDbmEMcNG8yIeNCyu6GUcr/QnWEE/wXm7+mhOCsdQfWQDTV7qYT/PDUZ4U4UPP4AsXqQ==}
+    engines: {node: '>= 8.0'}
+    peerDependencies:
+      '@types/node': '>= 8'
+
   mz@2.7.0:
     resolution: {integrity: sha512-z81GNO7nnYMEhrGh9LeymoE4+Yr0Wn5McHIZMK5cfQCl+NDX08sCZgUc9/6MHni9IWuFLm1Z3HTCXu2z9fN62Q==}
 
+  named-placeholders@1.1.6:
+    resolution: {integrity: sha512-Tz09sEL2EEuv5fFowm419c1+a/jSMiBjI9gHxVLrVdbUkkNUUfjsVYs9pVZu5oCon/kmRh9TfLEObFtkVxmY0w==}
+    engines: {node: '>=8.0.0'}
+
   nan@2.27.0:
     resolution: {integrity: sha512-hC+0LidcL3XE4rp1C4H54KujgXKzbfyTngZTwBByQxsOxCEKZT0MPQ4hOKUH2jU1OYstqdDH4onyHPDzcV0XdQ==}
 
@@ -13446,9 +13843,46 @@ packages:
   pend@1.2.0:
     resolution: {integrity: sha512-F3asv42UuXchdzt+xXqfW1OGlVBe+mxa2mqI0pg5yAHZPvFmY3Y6drSf/GQ1A86WgWEN9Kzh/WrgKa6iGcHXLg==}
 
+  perfect-debounce@1.0.0:
+    resolution: {integrity: sha512-xCy9V055GLEqoFaHoC1SoLIaLmWctgCUaBaWxDZ7/Zx4CTyX7cJQLJOok/orfjZAh9kEYpjJa4d0KcJmCbctZA==}
+
   perfect-debounce@2.0.0:
     resolution: {integrity: sha512-fkEH/OBiKrqqI/yIgjR92lMfs2K8105zt/VT6+7eTjNwisrsh47CeIED9z58zI7DfKdH3uHAn25ziRZn3kgAow==}
 
+  pg-cloudflare@1.4.0:
+    resolution: {integrity: sha512-Vo7z/6rrQYxpNRylp4Tlob2elzbh+N/MOQbxFVWCxS7oEx6jF53GTJFxK2WWpKuBRkmiin4Mt+xofFDjx09R0A==}
+
+  pg-connection-string@2.13.0:
+    resolution: {integrity: sha512-EMnU9E2fSULdsbErBbMaXJvFeD9B4+nPcM3f+4lsiCR0BHLPrLVjv3DbyM2hgQQviKJaTWIRRTjKjWlHg3p2ig==}
+
+  pg-int8@1.0.1:
+    resolution: {integrity: sha512-WCtabS6t3c8SkpDBUlb1kjOs7l66xsGdKpIPZsg4wR+B3+u9UAum2odSsF9tnvxg80h4ZxLWMy4pRjOsFIqQpw==}
+    engines: {node: '>=4.0.0'}
+
+  pg-pool@3.14.0:
+    resolution: {integrity: sha512-gKtPkFdQPU3DksooVLi9LsjZxrsBUZIpa+7aVx+LV5pNh0KzP4Zleud2po+ConrxbuXGBJ6Hfer6hdgpIBpBaw==}
+    peerDependencies:
+      pg: '>=8.0'
+
+  pg-protocol@1.14.0:
+    resolution: {integrity: sha512-n5taZ1kO3s9ngDTVxsEznOqCyToTgz0FLuPq0B33COy5pPpuWJpY3/2oRBVETuOgzdqRXfWpM9HIhp2LBBT1BA==}
+
+  pg-types@2.2.0:
+    resolution: {integrity: sha512-qTAAlrEsl8s4OiEQY69wDvcMIdQN6wdz5ojQiOy6YRMuynxenON0O5oCpJI6lshc6scgAY8qvJ2On/p+CXY0GA==}
+    engines: {node: '>=4'}
+
+  pg@8.21.0:
+    resolution: {integrity: sha512-AUP1EYJuHraQGsVoCQVIcM7TEJVGtDzxWtGFZd8rds9d+CCXlU5Js1rYgfLNvxy9iJrpHjGrRjoi/3BT9fRyiA==}
+    engines: {node: '>= 16.0.0'}
+    peerDependencies:
+      pg-native: '>=3.0.1'
+    peerDependenciesMeta:
+      pg-native:
+        optional: true
+
+  pgpass@1.0.5:
+    resolution: {integrity: sha512-FdW9r/jQZhSeohs1Z3sI1yxFQNFvMcnmfuj4WBMUTxOrAyLMaTcE1aAMBiTlbMNaXvBCQuVi0R7hd8udDSP7ug==}
+
   picocolors@1.1.1:
     resolution: {integrity: sha512-xceH2snhtb5M9liqDsmEw56le376mTZkEX/jEb/RxNFyegNul7eNslCXP9FDj/Lcu0X8KEyMceP2ntpaHrDEVA==}
 
@@ -13558,9 +13992,21 @@ packages:
     resolution: {integrity: sha512-3Ybi1tAuwAP9s0r1UQ2J4n5Y0G05bJkpUIO0/bI9MhwmD70S5aTWbXGBwxHrelT+XM1k6dM0pk+SwNkpTRN7Pg==}
     engines: {node: ^10 || ^12 || >=14}
 
-  postcss@8.5.9:
-    resolution: {integrity: sha512-7a70Nsot+EMX9fFU3064K/kdHWZqGVY+BADLyXc8Dfv+mTLLVl6JzJpPaCZ2kQL9gIJvKXSLMHhqdRRjwQeFtw==}
-    engines: {node: ^10 || ^12 || >=14}
+  postgres-array@2.0.0:
+    resolution: {integrity: sha512-VpZrUqU5A69eQyW2c5CA1jtLecCsN2U/bD6VilrFDWq5+5UIEVO7nazS3TEcHf1zuPYO/sqGvUvW62g86RXZuA==}
+    engines: {node: '>=4'}
+
+  postgres-bytea@1.0.1:
+    resolution: {integrity: sha512-5+5HqXnsZPE65IJZSMkZtURARZelel2oXUEO8rH83VS/hxH5vv1uHquPg5wZs8yMAfdv971IU+kcPUczi7NVBQ==}
+    engines: {node: '>=0.10.0'}
+
+  postgres-date@1.0.7:
+    resolution: {integrity: sha512-suDmjLVQg78nMK2UZ454hAG+OAW+HQPZ6n++TNDUX+L0+uUlLywnoxJKDou51Zm+zTCjrCl0Nq6J9C5hP9vK/Q==}
+    engines: {node: '>=0.10.0'}
+
+  postgres-interval@1.2.0:
+    resolution: {integrity: sha512-9ZhXKM/rw350N1ovuWHbGxnGh/SNJ4cnxHiM0rxE4VN41wsg8P8zWn9hv/buK00RP4WvlOyr/RBDiptyxVbkZQ==}
+    engines: {node: '>=0.10.0'}
 
   preact@10.28.1:
     resolution: {integrity: sha512-u1/ixq/lVQI0CakKNvLDEcW5zfCjUQfZdK9qqWuIJtsezuyG6pk9TWj75GMuI/EzRSZB/VAE43sNWWZfiy8psw==}
@@ -13609,6 +14055,16 @@ packages:
     resolution: {integrity: sha512-9uBdv/B4EefsuAL+pWqueZyZS2Ba+LxfFeQ9DN14HU4bN8bhaxKdkpjpB6fs9+pSjIBu+FXQHImEg8j/Lw0+vA==}
     engines: {node: ^18.14.0 || ^20.0.0 || ^22.0.0 || >=24.0.0}
 
+  prisma@6.19.3:
+    resolution: {integrity: sha512-++ZJ0ijLrDJF6hNB4t4uxg2br3fC4H9Yc9tcbjr2fcNFP3rh/SBNrAgjhsqBU4Ght8JPrVofG/ZkXfnSfnYsFg==}
+    engines: {node: '>=18.18'}
+    hasBin: true
+    peerDependencies:
+      typescript: '>=5.1.0'
+    peerDependenciesMeta:
+      typescript:
+        optional: true
+
   proc-log@4.2.0:
     resolution: {integrity: sha512-g8+OnU/L2v+wyiVK+D5fA34J7EH8jZ8DDlvwhRCMxmMj7UCBvxiO1mGeN+36JXIKF4zevU4kRBd8lVgG9vLelA==}
     engines: {node: ^14.17.0 || ^16.13.0 || >=18.0.0}
@@ -13698,6 +14154,9 @@ packages:
     engines: {node: '>=18'}
     hasBin: true
 
+  pure-rand@6.1.0:
+    resolution: {integrity: sha512-bVWawvoZoBYpp6yIoQtQXHZjmz35RSVHnUOTefl8Vcjr8snTPY1wnpSPMWekcFwbxI6gtmT7rSYPFvz71ldiOA==}
+
   qs@6.14.0:
     resolution: {integrity: sha512-YWWTjgABSKcvs/nWBi9PycY/JiPJqOD4JA6o9Sej2AtvSGarXxKC3OQSk4pAarbdQlKAh5D4FCQkJNkW+GAn3w==}
     engines: {node: '>=0.6'}
@@ -14446,9 +14905,17 @@ packages:
   split-ca@1.0.1:
     resolution: {integrity: sha512-Q5thBSxp5t8WPTTJQS59LrGqOZqOsrhDGDVm8azCqIBjSBd7nd9o2PM+mDulQQkh8h//4U6hFZnc/mul8t5pWQ==}
 
+  split2@4.2.0:
+    resolution: {integrity: sha512-UcjcJOWknrNkF6PLX83qcHM6KHgVKNkV62Y8a5uYDVv9ydGQVwAHMKqHdJje1VTWpljG0WYpCDhrCdAOYH4TWg==}
+    engines: {node: '>= 10.x'}
+
   sprintf-js@1.0.3:
     resolution: {integrity: sha512-D9cPgkvLlV3t3IzL0D0YLvGA9Ahk4PcvVwUbN0dSGr1aP0Nrt4AEnTUbuGvquEC0mA64Gqt1fzirlRs5ibXx8g==}
 
+  sql-escaper@1.3.3:
+    resolution: {integrity: sha512-BsTCV265VpTp8tm1wyIm1xqQCS+Q9NHx2Sr+WcnUrgLrQ6yiDIvHYJV5gHxsj1lMBy2zm5twLaZao8Jd+S8JJw==}
+    engines: {bun: '>=1.0.0', deno: '>=2.0.0', node: '>=12.0.0'}
+
   srvx@0.10.1:
     resolution: {integrity: sha512-A//xtfak4eESMWWydSRFUVvCTQbSwivnGCEf8YGPe2eHU0+Z6znfUTCPF0a7oV3sObSOcrXHlL6Bs9vVctfXdg==}
     engines: {node: '>=20.16.0'}
@@ -15917,6 +16384,10 @@ packages:
   xmlchars@2.2.0:
     resolution: {integrity: sha512-JZnDKK8B0RCDw84FNdDAIpZK+JuJw+s7Lz8nksI7SIuU3UXJJslUthsi+uWBUYOwPFwW7W7PRLRfUKpxjtjFCw==}
 
+  xtend@4.0.2:
+    resolution: {integrity: sha512-LKYU1iAXJXUgAXn9URjiu+MWhyUXHsvfp7mcuYm9dSUKK0/CjtrUwFAxD82/mCWbtLsGjFIad0wIsod4zrTAEQ==}
+    engines: {node: '>=0.4'}
+
   y18n@5.0.8:
     resolution: {integrity: sha512-0pfFzegeDWJHJIAmTLRP2DwHjdF5s7jo9tuztdQxAhINCdvS+3nGINqPd00AphqJR/0LhANUS6/+7SCb98YOfA==}
     engines: {node: '>=10'}
@@ -16007,7 +16478,7 @@ snapshots:
 
   '@acemir/cssom@0.9.29': {}
 
-  '@ag-ui/core@0.0.52':
+  '@ag-ui/core@0.0.57':
     dependencies:
       zod: 3.25.76
 
@@ -17778,6 +18249,8 @@ snapshots:
       '@deno/shim-deno-test': 0.5.0
       which: 4.0.0
 
+  '@drizzle-team/brocli@0.10.2': {}
+
   '@elevenlabs/client@1.3.1(@types/dom-mediacapture-record@1.0.22)':
     dependencies:
       '@elevenlabs/types': 0.9.1
@@ -17842,8 +18315,18 @@ snapshots:
       tslib: 2.8.1
     optional: true
 
-  '@esbuild/aix-ppc64@0.20.2':
-    optional: true
+  '@esbuild-kit/core-utils@3.3.2':
+    dependencies:
+      esbuild: 0.18.20
+      source-map-support: 0.5.21
+
+  '@esbuild-kit/esm-loader@2.6.5':
+    dependencies:
+      '@esbuild-kit/core-utils': 3.3.2
+      get-tsconfig: 4.13.0
+
+  '@esbuild/aix-ppc64@0.20.2':
+    optional: true
 
   '@esbuild/aix-ppc64@0.25.12':
     optional: true
@@ -17857,6 +18340,9 @@ snapshots:
   '@esbuild/aix-ppc64@0.28.1':
     optional: true
 
+  '@esbuild/android-arm64@0.18.20':
+    optional: true
+
   '@esbuild/android-arm64@0.20.2':
     optional: true
 
@@ -17872,6 +18358,9 @@ snapshots:
   '@esbuild/android-arm64@0.28.1':
     optional: true
 
+  '@esbuild/android-arm@0.18.20':
+    optional: true
+
   '@esbuild/android-arm@0.20.2':
     optional: true
 
@@ -17887,6 +18376,9 @@ snapshots:
   '@esbuild/android-arm@0.28.1':
     optional: true
 
+  '@esbuild/android-x64@0.18.20':
+    optional: true
+
   '@esbuild/android-x64@0.20.2':
     optional: true
 
@@ -17902,6 +18394,9 @@ snapshots:
   '@esbuild/android-x64@0.28.1':
     optional: true
 
+  '@esbuild/darwin-arm64@0.18.20':
+    optional: true
+
   '@esbuild/darwin-arm64@0.20.2':
     optional: true
 
@@ -17917,6 +18412,9 @@ snapshots:
   '@esbuild/darwin-arm64@0.28.1':
     optional: true
 
+  '@esbuild/darwin-x64@0.18.20':
+    optional: true
+
   '@esbuild/darwin-x64@0.20.2':
     optional: true
 
@@ -17932,6 +18430,9 @@ snapshots:
   '@esbuild/darwin-x64@0.28.1':
     optional: true
 
+  '@esbuild/freebsd-arm64@0.18.20':
+    optional: true
+
   '@esbuild/freebsd-arm64@0.20.2':
     optional: true
 
@@ -17947,6 +18448,9 @@ snapshots:
   '@esbuild/freebsd-arm64@0.28.1':
     optional: true
 
+  '@esbuild/freebsd-x64@0.18.20':
+    optional: true
+
   '@esbuild/freebsd-x64@0.20.2':
     optional: true
 
@@ -17962,6 +18466,9 @@ snapshots:
   '@esbuild/freebsd-x64@0.28.1':
     optional: true
 
+  '@esbuild/linux-arm64@0.18.20':
+    optional: true
+
   '@esbuild/linux-arm64@0.20.2':
     optional: true
 
@@ -17977,6 +18484,9 @@ snapshots:
   '@esbuild/linux-arm64@0.28.1':
     optional: true
 
+  '@esbuild/linux-arm@0.18.20':
+    optional: true
+
   '@esbuild/linux-arm@0.20.2':
     optional: true
 
@@ -17992,6 +18502,9 @@ snapshots:
   '@esbuild/linux-arm@0.28.1':
     optional: true
 
+  '@esbuild/linux-ia32@0.18.20':
+    optional: true
+
   '@esbuild/linux-ia32@0.20.2':
     optional: true
 
@@ -18007,6 +18520,9 @@ snapshots:
   '@esbuild/linux-ia32@0.28.1':
     optional: true
 
+  '@esbuild/linux-loong64@0.18.20':
+    optional: true
+
   '@esbuild/linux-loong64@0.20.2':
     optional: true
 
@@ -18022,6 +18538,9 @@ snapshots:
   '@esbuild/linux-loong64@0.28.1':
     optional: true
 
+  '@esbuild/linux-mips64el@0.18.20':
+    optional: true
+
   '@esbuild/linux-mips64el@0.20.2':
     optional: true
 
@@ -18037,6 +18556,9 @@ snapshots:
   '@esbuild/linux-mips64el@0.28.1':
     optional: true
 
+  '@esbuild/linux-ppc64@0.18.20':
+    optional: true
+
   '@esbuild/linux-ppc64@0.20.2':
     optional: true
 
@@ -18052,6 +18574,9 @@ snapshots:
   '@esbuild/linux-ppc64@0.28.1':
     optional: true
 
+  '@esbuild/linux-riscv64@0.18.20':
+    optional: true
+
   '@esbuild/linux-riscv64@0.20.2':
     optional: true
 
@@ -18067,6 +18592,9 @@ snapshots:
   '@esbuild/linux-riscv64@0.28.1':
     optional: true
 
+  '@esbuild/linux-s390x@0.18.20':
+    optional: true
+
   '@esbuild/linux-s390x@0.20.2':
     optional: true
 
@@ -18082,6 +18610,9 @@ snapshots:
   '@esbuild/linux-s390x@0.28.1':
     optional: true
 
+  '@esbuild/linux-x64@0.18.20':
+    optional: true
+
   '@esbuild/linux-x64@0.20.2':
     optional: true
 
@@ -18109,6 +18640,9 @@ snapshots:
   '@esbuild/netbsd-arm64@0.28.1':
     optional: true
 
+  '@esbuild/netbsd-x64@0.18.20':
+    optional: true
+
   '@esbuild/netbsd-x64@0.20.2':
     optional: true
 
@@ -18136,6 +18670,9 @@ snapshots:
   '@esbuild/openbsd-arm64@0.28.1':
     optional: true
 
+  '@esbuild/openbsd-x64@0.18.20':
+    optional: true
+
   '@esbuild/openbsd-x64@0.20.2':
     optional: true
 
@@ -18163,6 +18700,9 @@ snapshots:
   '@esbuild/openharmony-arm64@0.28.1':
     optional: true
 
+  '@esbuild/sunos-x64@0.18.20':
+    optional: true
+
   '@esbuild/sunos-x64@0.20.2':
     optional: true
 
@@ -18178,6 +18718,9 @@ snapshots:
   '@esbuild/sunos-x64@0.28.1':
     optional: true
 
+  '@esbuild/win32-arm64@0.18.20':
+    optional: true
+
   '@esbuild/win32-arm64@0.20.2':
     optional: true
 
@@ -18193,6 +18736,9 @@ snapshots:
   '@esbuild/win32-arm64@0.28.1':
     optional: true
 
+  '@esbuild/win32-ia32@0.18.20':
+    optional: true
+
   '@esbuild/win32-ia32@0.20.2':
     optional: true
 
@@ -18208,6 +18754,9 @@ snapshots:
   '@esbuild/win32-ia32@0.28.1':
     optional: true
 
+  '@esbuild/win32-x64@0.18.20':
+    optional: true
+
   '@esbuild/win32-x64@0.20.2':
     optional: true
 
@@ -19998,6 +20547,41 @@ snapshots:
 
   '@poppinss/exception@1.2.3': {}
 
+  '@prisma/client@6.19.3(prisma@6.19.3(typescript@5.9.3))(typescript@5.9.3)':
+    optionalDependencies:
+      prisma: 6.19.3(magicast@0.5.2)(typescript@5.9.3)
+      typescript: 5.9.3
+
+  '@prisma/config@6.19.3(magicast@0.5.2)':
+    dependencies:
+      c12: 3.1.0(magicast@0.5.2)
+      deepmerge-ts: 7.1.5
+      effect: 3.21.0
+      empathic: 2.0.0
+    transitivePeerDependencies:
+      - magicast
+
+  '@prisma/debug@6.19.3': {}
+
+  '@prisma/engines-version@7.1.1-3.c2990dca591cba766e3b7ef5d9e8a84796e47ab7': {}
+
+  '@prisma/engines@6.19.3':
+    dependencies:
+      '@prisma/debug': 6.19.3
+      '@prisma/engines-version': 7.1.1-3.c2990dca591cba766e3b7ef5d9e8a84796e47ab7
+      '@prisma/fetch-engine': 6.19.3
+      '@prisma/get-platform': 6.19.3
+
+  '@prisma/fetch-engine@6.19.3':
+    dependencies:
+      '@prisma/debug': 6.19.3
+      '@prisma/engines-version': 7.1.1-3.c2990dca591cba766e3b7ef5d9e8a84796e47ab7
+      '@prisma/get-platform': 6.19.3
+
+  '@prisma/get-platform@6.19.3':
+    dependencies:
+      '@prisma/debug': 6.19.3
+
   '@protobufjs/aspromise@1.1.2': {}
 
   '@protobufjs/base64@1.1.2': {}
@@ -21864,9 +22448,45 @@ snapshots:
 
   '@tanstack/history@1.154.14': {}
 
-  '@tanstack/nitro-v2-vite-plugin@1.154.7(aws4fetch@1.0.20)(rolldown@1.1.3)(vite@7.3.3(@types/node@24.10.3)(jiti@2.6.1)(less@4.6.6)(lightningcss@1.30.2)(sass@1.101.0)(terser@5.44.1)(tsx@4.21.0)(yaml@2.8.2))':
+  '@tanstack/nitro-v2-vite-plugin@1.154.7(aws4fetch@1.0.20)(drizzle-orm@0.45.2(@cloudflare/workers-types@4.20260317.1)(@opentelemetry/api@1.9.1)(@prisma/client@6.19.3(prisma@6.19.3(magicast@0.5.2)(typescript@5.9.3))(typescript@5.9.3))(@types/pg@8.20.0)(mysql2@3.22.5(@types/node@24.10.3))(pg@8.21.0)(prisma@6.19.3(magicast@0.5.2)(typescript@5.9.3)))(mysql2@3.22.5(@types/node@24.10.3))(rolldown@1.1.3)(vite@7.3.3(@types/node@24.10.3)(jiti@2.6.1)(less@4.6.6)(lightningcss@1.30.2)(sass@1.101.0)(terser@5.44.1)(tsx@4.21.0)(yaml@2.8.2))':
+    dependencies:
+      nitropack: 2.13.1(aws4fetch@1.0.20)(drizzle-orm@0.45.2(@cloudflare/workers-types@4.20260317.1)(@opentelemetry/api@1.9.1)(@prisma/client@6.19.3(prisma@6.19.3(magicast@0.5.2)(typescript@5.9.3))(typescript@5.9.3))(@types/pg@8.20.0)(mysql2@3.22.5(@types/node@24.10.3))(pg@8.21.0)(prisma@6.19.3(magicast@0.5.2)(typescript@5.9.3)))(mysql2@3.22.5(@types/node@24.10.3))(rolldown@1.1.3)
+      pathe: 2.0.3
+      vite: 7.3.3(@types/node@24.10.3)(jiti@2.6.1)(less@4.6.6)(lightningcss@1.30.2)(sass@1.101.0)(terser@5.44.1)(tsx@4.21.0)(yaml@2.8.2)
+    transitivePeerDependencies:
+      - '@azure/app-configuration'
+      - '@azure/cosmos'
+      - '@azure/data-tables'
+      - '@azure/identity'
+      - '@azure/keyvault-secrets'
+      - '@azure/storage-blob'
+      - '@capacitor/preferences'
+      - '@deno/kv'
+      - '@electric-sql/pglite'
+      - '@libsql/client'
+      - '@netlify/blobs'
+      - '@planetscale/database'
+      - '@upstash/redis'
+      - '@vercel/blob'
+      - '@vercel/functions'
+      - '@vercel/kv'
+      - aws4fetch
+      - bare-abort-controller
+      - better-sqlite3
+      - drizzle-orm
+      - encoding
+      - idb-keyval
+      - mysql2
+      - react-native-b4a
+      - rolldown
+      - sqlite3
+      - supports-color
+      - uploadthing
+      - xml2js
+
+  '@tanstack/nitro-v2-vite-plugin@1.154.7(aws4fetch@1.0.20)(drizzle-orm@0.45.2(@cloudflare/workers-types@4.20260317.1)(@opentelemetry/api@1.9.1)(@prisma/client@6.19.3(prisma@6.19.3(typescript@5.9.3))(typescript@5.9.3))(@types/pg@8.20.0)(mysql2@3.22.5(@types/node@24.10.3))(pg@8.21.0)(prisma@6.19.3(typescript@5.9.3)))(mysql2@3.22.5(@types/node@24.10.3))(rolldown@1.1.3)(vite@7.3.3(@types/node@24.10.3)(jiti@2.6.1)(less@4.6.6)(lightningcss@1.30.2)(sass@1.101.0)(terser@5.44.1)(tsx@4.21.0)(yaml@2.8.2))':
     dependencies:
-      nitropack: 2.13.1(aws4fetch@1.0.20)(rolldown@1.1.3)
+      nitropack: 2.13.1(aws4fetch@1.0.20)(drizzle-orm@0.45.2(@cloudflare/workers-types@4.20260317.1)(@opentelemetry/api@1.9.1)(@prisma/client@6.19.3(prisma@6.19.3(typescript@5.9.3))(typescript@5.9.3))(@types/pg@8.20.0)(mysql2@3.22.5(@types/node@24.10.3))(pg@8.21.0)(prisma@6.19.3(typescript@5.9.3)))(mysql2@3.22.5(@types/node@24.10.3))(rolldown@1.1.3)
       pathe: 2.0.3
       vite: 7.3.3(@types/node@24.10.3)(jiti@2.6.1)(less@4.6.6)(lightningcss@1.30.2)(sass@1.101.0)(terser@5.44.1)(tsx@4.21.0)(yaml@2.8.2)
     transitivePeerDependencies:
@@ -22001,9 +22621,9 @@ snapshots:
       tiny-invariant: 1.3.3
       tiny-warning: 1.0.3
 
-  '@tanstack/react-start-plugin@1.131.50(@tanstack/react-router@1.159.5(react-dom@19.2.3(react@19.2.3))(react@19.2.3))(@vitejs/plugin-react@4.7.0(vite@7.3.3(@types/node@24.10.3)(jiti@2.6.1)(less@4.6.6)(lightningcss@1.30.2)(sass@1.101.0)(terser@5.44.1)(tsx@4.21.0)(yaml@2.8.2)))(aws4fetch@1.0.20)(rolldown@1.1.3)(vite-plugin-solid@2.11.10(solid-js@1.9.10)(vite@7.3.3(@types/node@24.10.3)(jiti@2.6.1)(less@4.6.6)(lightningcss@1.30.2)(sass@1.101.0)(terser@5.44.1)(tsx@4.21.0)(yaml@2.8.2)))(vite@7.3.3(@types/node@24.10.3)(jiti@2.6.1)(less@4.6.6)(lightningcss@1.30.2)(sass@1.101.0)(terser@5.44.1)(tsx@4.21.0)(yaml@2.8.2))':
+  '@tanstack/react-start-plugin@1.131.50(@tanstack/react-router@1.159.5(react-dom@19.2.3(react@19.2.3))(react@19.2.3))(@vitejs/plugin-react@4.7.0(vite@7.3.3(@types/node@24.10.3)(jiti@2.6.1)(less@4.6.6)(lightningcss@1.30.2)(sass@1.101.0)(terser@5.44.1)(tsx@4.21.0)(yaml@2.8.2)))(aws4fetch@1.0.20)(drizzle-orm@0.45.2(@cloudflare/workers-types@4.20260317.1)(@opentelemetry/api@1.9.1)(@prisma/client@6.19.3(prisma@6.19.3(magicast@0.5.2)(typescript@5.9.3))(typescript@5.9.3))(@types/pg@8.20.0)(mysql2@3.22.5(@types/node@24.10.3))(pg@8.21.0)(prisma@6.19.3(magicast@0.5.2)(typescript@5.9.3)))(mysql2@3.22.5(@types/node@24.10.3))(rolldown@1.1.3)(vite-plugin-solid@2.11.10(solid-js@1.9.10)(vite@7.3.3(@types/node@24.10.3)(jiti@2.6.1)(less@4.6.6)(lightningcss@1.30.2)(sass@1.101.0)(terser@5.44.1)(tsx@4.21.0)(yaml@2.8.2)))(vite@7.3.3(@types/node@24.10.3)(jiti@2.6.1)(less@4.6.6)(lightningcss@1.30.2)(sass@1.101.0)(terser@5.44.1)(tsx@4.21.0)(yaml@2.8.2))':
     dependencies:
-      '@tanstack/start-plugin-core': 1.131.50(@tanstack/react-router@1.159.5(react-dom@19.2.3(react@19.2.3))(react@19.2.3))(aws4fetch@1.0.20)(rolldown@1.1.3)(vite-plugin-solid@2.11.10(solid-js@1.9.10)(vite@7.3.3(@types/node@24.10.3)(jiti@2.6.1)(less@4.6.6)(lightningcss@1.30.2)(sass@1.101.0)(terser@5.44.1)(tsx@4.21.0)(yaml@2.8.2)))(vite@7.3.3(@types/node@24.10.3)(jiti@2.6.1)(less@4.6.6)(lightningcss@1.30.2)(sass@1.101.0)(terser@5.44.1)(tsx@4.21.0)(yaml@2.8.2))
+      '@tanstack/start-plugin-core': 1.131.50(@tanstack/react-router@1.159.5(react-dom@19.2.3(react@19.2.3))(react@19.2.3))(aws4fetch@1.0.20)(drizzle-orm@0.45.2(@cloudflare/workers-types@4.20260317.1)(@opentelemetry/api@1.9.1)(@prisma/client@6.19.3(prisma@6.19.3(magicast@0.5.2)(typescript@5.9.3))(typescript@5.9.3))(@types/pg@8.20.0)(mysql2@3.22.5(@types/node@24.10.3))(pg@8.21.0)(prisma@6.19.3(magicast@0.5.2)(typescript@5.9.3)))(mysql2@3.22.5(@types/node@24.10.3))(rolldown@1.1.3)(vite-plugin-solid@2.11.10(solid-js@1.9.10)(vite@7.3.3(@types/node@24.10.3)(jiti@2.6.1)(less@4.6.6)(lightningcss@1.30.2)(sass@1.101.0)(terser@5.44.1)(tsx@4.21.0)(yaml@2.8.2)))(vite@7.3.3(@types/node@24.10.3)(jiti@2.6.1)(less@4.6.6)(lightningcss@1.30.2)(sass@1.101.0)(terser@5.44.1)(tsx@4.21.0)(yaml@2.8.2))
       '@vitejs/plugin-react': 4.7.0(vite@7.3.3(@types/node@24.10.3)(jiti@2.6.1)(less@4.6.6)(lightningcss@1.30.2)(sass@1.101.0)(terser@5.44.1)(tsx@4.21.0)(yaml@2.8.2))
       pathe: 2.0.3
       vite: 7.3.3(@types/node@24.10.3)(jiti@2.6.1)(less@4.6.6)(lightningcss@1.30.2)(sass@1.101.0)(terser@5.44.1)(tsx@4.21.0)(yaml@2.8.2)
@@ -22043,11 +22663,11 @@ snapshots:
       - webpack
       - xml2js
 
-  '@tanstack/react-start-router-manifest@1.120.19(@types/node@24.10.3)(aws4fetch@1.0.20)(db0@0.3.4)(ioredis@5.8.2)(jiti@2.6.1)(less@4.6.6)(lightningcss@1.30.2)(rolldown@1.1.3)(sass@1.101.0)(terser@5.44.1)(tsx@4.21.0)(yaml@2.8.2)':
+  '@tanstack/react-start-router-manifest@1.120.19(@types/node@24.10.3)(aws4fetch@1.0.20)(db0@0.3.4(drizzle-orm@0.45.2(@cloudflare/workers-types@4.20260317.1)(@opentelemetry/api@1.9.1)(@prisma/client@6.19.3(prisma@6.19.3(magicast@0.5.2)(typescript@5.9.3))(typescript@5.9.3))(@types/pg@8.20.0)(mysql2@3.22.5(@types/node@24.10.3))(pg@8.21.0)(prisma@6.19.3(magicast@0.5.2)(typescript@5.9.3)))(mysql2@3.22.5(@types/node@24.10.3)))(drizzle-orm@0.45.2(@cloudflare/workers-types@4.20260317.1)(@opentelemetry/api@1.9.1)(@prisma/client@6.19.3(prisma@6.19.3(magicast@0.5.2)(typescript@5.9.3))(typescript@5.9.3))(@types/pg@8.20.0)(mysql2@3.22.5(@types/node@24.10.3))(pg@8.21.0)(prisma@6.19.3(magicast@0.5.2)(typescript@5.9.3)))(ioredis@5.8.2)(jiti@2.6.1)(less@4.6.6)(lightningcss@1.30.2)(mysql2@3.22.5(@types/node@24.10.3))(rolldown@1.1.3)(sass@1.101.0)(terser@5.44.1)(tsx@4.21.0)(yaml@2.8.2)':
     dependencies:
       '@tanstack/router-core': 1.157.16
       tiny-invariant: 1.3.3
-      vinxi: 0.5.3(@types/node@24.10.3)(aws4fetch@1.0.20)(db0@0.3.4)(ioredis@5.8.2)(jiti@2.6.1)(less@4.6.6)(lightningcss@1.30.2)(rolldown@1.1.3)(sass@1.101.0)(terser@5.44.1)(tsx@4.21.0)(yaml@2.8.2)
+      vinxi: 0.5.3(@types/node@24.10.3)(aws4fetch@1.0.20)(db0@0.3.4(drizzle-orm@0.45.2(@cloudflare/workers-types@4.20260317.1)(@opentelemetry/api@1.9.1)(@prisma/client@6.19.3(prisma@6.19.3(magicast@0.5.2)(typescript@5.9.3))(typescript@5.9.3))(@types/pg@8.20.0)(mysql2@3.22.5(@types/node@24.10.3))(pg@8.21.0)(prisma@6.19.3(magicast@0.5.2)(typescript@5.9.3)))(mysql2@3.22.5(@types/node@24.10.3)))(drizzle-orm@0.45.2(@cloudflare/workers-types@4.20260317.1)(@opentelemetry/api@1.9.1)(@prisma/client@6.19.3(prisma@6.19.3(magicast@0.5.2)(typescript@5.9.3))(typescript@5.9.3))(@types/pg@8.20.0)(mysql2@3.22.5(@types/node@24.10.3))(pg@8.21.0)(prisma@6.19.3(magicast@0.5.2)(typescript@5.9.3)))(ioredis@5.8.2)(jiti@2.6.1)(less@4.6.6)(lightningcss@1.30.2)(mysql2@3.22.5(@types/node@24.10.3))(rolldown@1.1.3)(sass@1.101.0)(terser@5.44.1)(tsx@4.21.0)(yaml@2.8.2)
     transitivePeerDependencies:
       - '@azure/app-configuration'
       - '@azure/cosmos'
@@ -22518,11 +23138,11 @@ snapshots:
       '@tanstack/store': 0.8.0
       solid-js: 1.9.10
 
-  '@tanstack/start-api-routes@1.120.19(@types/node@24.10.3)(aws4fetch@1.0.20)(crossws@0.4.6(srvx@0.11.17))(db0@0.3.4)(ioredis@5.8.2)(jiti@2.6.1)(less@4.6.6)(lightningcss@1.30.2)(rolldown@1.1.3)(sass@1.101.0)(terser@5.44.1)(tsx@4.21.0)(yaml@2.8.2)':
+  '@tanstack/start-api-routes@1.120.19(@types/node@24.10.3)(aws4fetch@1.0.20)(crossws@0.4.6(srvx@0.11.17))(db0@0.3.4(drizzle-orm@0.45.2(@cloudflare/workers-types@4.20260317.1)(@opentelemetry/api@1.9.1)(@prisma/client@6.19.3(prisma@6.19.3(magicast@0.5.2)(typescript@5.9.3))(typescript@5.9.3))(@types/pg@8.20.0)(mysql2@3.22.5(@types/node@24.10.3))(pg@8.21.0)(prisma@6.19.3(magicast@0.5.2)(typescript@5.9.3)))(mysql2@3.22.5(@types/node@24.10.3)))(drizzle-orm@0.45.2(@cloudflare/workers-types@4.20260317.1)(@opentelemetry/api@1.9.1)(@prisma/client@6.19.3(prisma@6.19.3(magicast@0.5.2)(typescript@5.9.3))(typescript@5.9.3))(@types/pg@8.20.0)(mysql2@3.22.5(@types/node@24.10.3))(pg@8.21.0)(prisma@6.19.3(magicast@0.5.2)(typescript@5.9.3)))(ioredis@5.8.2)(jiti@2.6.1)(less@4.6.6)(lightningcss@1.30.2)(mysql2@3.22.5(@types/node@24.10.3))(rolldown@1.1.3)(sass@1.101.0)(terser@5.44.1)(tsx@4.21.0)(yaml@2.8.2)':
     dependencies:
       '@tanstack/router-core': 1.157.16
       '@tanstack/start-server-core': 1.141.1(crossws@0.4.6(srvx@0.11.17))
-      vinxi: 0.5.3(@types/node@24.10.3)(aws4fetch@1.0.20)(db0@0.3.4)(ioredis@5.8.2)(jiti@2.6.1)(less@4.6.6)(lightningcss@1.30.2)(rolldown@1.1.3)(sass@1.101.0)(terser@5.44.1)(tsx@4.21.0)(yaml@2.8.2)
+      vinxi: 0.5.3(@types/node@24.10.3)(aws4fetch@1.0.20)(db0@0.3.4(drizzle-orm@0.45.2(@cloudflare/workers-types@4.20260317.1)(@opentelemetry/api@1.9.1)(@prisma/client@6.19.3(prisma@6.19.3(magicast@0.5.2)(typescript@5.9.3))(typescript@5.9.3))(@types/pg@8.20.0)(mysql2@3.22.5(@types/node@24.10.3))(pg@8.21.0)(prisma@6.19.3(magicast@0.5.2)(typescript@5.9.3)))(mysql2@3.22.5(@types/node@24.10.3)))(drizzle-orm@0.45.2(@cloudflare/workers-types@4.20260317.1)(@opentelemetry/api@1.9.1)(@prisma/client@6.19.3(prisma@6.19.3(magicast@0.5.2)(typescript@5.9.3))(typescript@5.9.3))(@types/pg@8.20.0)(mysql2@3.22.5(@types/node@24.10.3))(pg@8.21.0)(prisma@6.19.3(magicast@0.5.2)(typescript@5.9.3)))(ioredis@5.8.2)(jiti@2.6.1)(less@4.6.6)(lightningcss@1.30.2)(mysql2@3.22.5(@types/node@24.10.3))(rolldown@1.1.3)(sass@1.101.0)(terser@5.44.1)(tsx@4.21.0)(yaml@2.8.2)
     transitivePeerDependencies:
       - '@azure/app-configuration'
       - '@azure/cosmos'
@@ -22594,21 +23214,21 @@ snapshots:
       tiny-invariant: 1.3.3
       tiny-warning: 1.0.3
 
-  '@tanstack/start-config@1.120.20(@types/node@24.10.3)(aws4fetch@1.0.20)(crossws@0.4.6(srvx@0.11.17))(db0@0.3.4)(ioredis@5.8.2)(jiti@2.6.1)(less@4.6.6)(lightningcss@1.30.2)(react-dom@19.2.3(react@19.2.3))(react@19.2.3)(rolldown@1.1.3)(sass@1.101.0)(terser@5.44.1)(tsx@4.21.0)(vite-plugin-solid@2.11.10(solid-js@1.9.10)(vite@7.3.3(@types/node@24.10.3)(jiti@2.6.1)(less@4.6.6)(lightningcss@1.30.2)(sass@1.101.0)(terser@5.44.1)(tsx@4.21.0)(yaml@2.8.2)))(vite@7.3.3(@types/node@24.10.3)(jiti@2.6.1)(less@4.6.6)(lightningcss@1.30.2)(sass@1.101.0)(terser@5.44.1)(tsx@4.21.0)(yaml@2.8.2))(yaml@2.8.2)':
+  '@tanstack/start-config@1.120.20(647307324c217c342a2641e0cabd8372)':
     dependencies:
       '@tanstack/react-router': 1.159.5(react-dom@19.2.3(react@19.2.3))(react@19.2.3)
-      '@tanstack/react-start-plugin': 1.131.50(@tanstack/react-router@1.159.5(react-dom@19.2.3(react@19.2.3))(react@19.2.3))(@vitejs/plugin-react@4.7.0(vite@7.3.3(@types/node@24.10.3)(jiti@2.6.1)(less@4.6.6)(lightningcss@1.30.2)(sass@1.101.0)(terser@5.44.1)(tsx@4.21.0)(yaml@2.8.2)))(aws4fetch@1.0.20)(rolldown@1.1.3)(vite-plugin-solid@2.11.10(solid-js@1.9.10)(vite@7.3.3(@types/node@24.10.3)(jiti@2.6.1)(less@4.6.6)(lightningcss@1.30.2)(sass@1.101.0)(terser@5.44.1)(tsx@4.21.0)(yaml@2.8.2)))(vite@7.3.3(@types/node@24.10.3)(jiti@2.6.1)(less@4.6.6)(lightningcss@1.30.2)(sass@1.101.0)(terser@5.44.1)(tsx@4.21.0)(yaml@2.8.2))
+      '@tanstack/react-start-plugin': 1.131.50(@tanstack/react-router@1.159.5(react-dom@19.2.3(react@19.2.3))(react@19.2.3))(@vitejs/plugin-react@4.7.0(vite@7.3.3(@types/node@24.10.3)(jiti@2.6.1)(less@4.6.6)(lightningcss@1.30.2)(sass@1.101.0)(terser@5.44.1)(tsx@4.21.0)(yaml@2.8.2)))(aws4fetch@1.0.20)(drizzle-orm@0.45.2(@cloudflare/workers-types@4.20260317.1)(@opentelemetry/api@1.9.1)(@prisma/client@6.19.3(prisma@6.19.3(magicast@0.5.2)(typescript@5.9.3))(typescript@5.9.3))(@types/pg@8.20.0)(mysql2@3.22.5(@types/node@24.10.3))(pg@8.21.0)(prisma@6.19.3(magicast@0.5.2)(typescript@5.9.3)))(mysql2@3.22.5(@types/node@24.10.3))(rolldown@1.1.3)(vite-plugin-solid@2.11.10(solid-js@1.9.10)(vite@7.3.3(@types/node@24.10.3)(jiti@2.6.1)(less@4.6.6)(lightningcss@1.30.2)(sass@1.101.0)(terser@5.44.1)(tsx@4.21.0)(yaml@2.8.2)))(vite@7.3.3(@types/node@24.10.3)(jiti@2.6.1)(less@4.6.6)(lightningcss@1.30.2)(sass@1.101.0)(terser@5.44.1)(tsx@4.21.0)(yaml@2.8.2))
       '@tanstack/router-generator': 1.141.1
       '@tanstack/router-plugin': 1.159.5(@tanstack/react-router@1.159.5(react-dom@19.2.3(react@19.2.3))(react@19.2.3))(vite-plugin-solid@2.11.10(solid-js@1.9.10)(vite@7.3.3(@types/node@24.10.3)(jiti@2.6.1)(less@4.6.6)(lightningcss@1.30.2)(sass@1.101.0)(terser@5.44.1)(tsx@4.21.0)(yaml@2.8.2)))(vite@7.3.3(@types/node@24.10.3)(jiti@2.6.1)(less@4.6.6)(lightningcss@1.30.2)(sass@1.101.0)(terser@5.44.1)(tsx@4.21.0)(yaml@2.8.2))
       '@tanstack/server-functions-plugin': 1.141.0(vite@7.3.3(@types/node@24.10.3)(jiti@2.6.1)(less@4.6.6)(lightningcss@1.30.2)(sass@1.101.0)(terser@5.44.1)(tsx@4.21.0)(yaml@2.8.2))
       '@tanstack/start-server-functions-handler': 1.120.19(crossws@0.4.6(srvx@0.11.17))
       '@vitejs/plugin-react': 4.7.0(vite@7.3.3(@types/node@24.10.3)(jiti@2.6.1)(less@4.6.6)(lightningcss@1.30.2)(sass@1.101.0)(terser@5.44.1)(tsx@4.21.0)(yaml@2.8.2))
       import-meta-resolve: 4.2.0
-      nitropack: 2.12.9(aws4fetch@1.0.20)(rolldown@1.1.3)
+      nitropack: 2.12.9(aws4fetch@1.0.20)(drizzle-orm@0.45.2(@cloudflare/workers-types@4.20260317.1)(@opentelemetry/api@1.9.1)(@prisma/client@6.19.3(prisma@6.19.3(magicast@0.5.2)(typescript@5.9.3))(typescript@5.9.3))(@types/pg@8.20.0)(mysql2@3.22.5(@types/node@24.10.3))(pg@8.21.0)(prisma@6.19.3(magicast@0.5.2)(typescript@5.9.3)))(mysql2@3.22.5(@types/node@24.10.3))(rolldown@1.1.3)
       ofetch: 1.5.1
       react: 19.2.3
       react-dom: 19.2.3(react@19.2.3)
-      vinxi: 0.5.3(@types/node@24.10.3)(aws4fetch@1.0.20)(db0@0.3.4)(ioredis@5.8.2)(jiti@2.6.1)(less@4.6.6)(lightningcss@1.30.2)(rolldown@1.1.3)(sass@1.101.0)(terser@5.44.1)(tsx@4.21.0)(yaml@2.8.2)
+      vinxi: 0.5.3(@types/node@24.10.3)(aws4fetch@1.0.20)(db0@0.3.4(drizzle-orm@0.45.2(@cloudflare/workers-types@4.20260317.1)(@opentelemetry/api@1.9.1)(@prisma/client@6.19.3(prisma@6.19.3(magicast@0.5.2)(typescript@5.9.3))(typescript@5.9.3))(@types/pg@8.20.0)(mysql2@3.22.5(@types/node@24.10.3))(pg@8.21.0)(prisma@6.19.3(magicast@0.5.2)(typescript@5.9.3)))(mysql2@3.22.5(@types/node@24.10.3)))(drizzle-orm@0.45.2(@cloudflare/workers-types@4.20260317.1)(@opentelemetry/api@1.9.1)(@prisma/client@6.19.3(prisma@6.19.3(magicast@0.5.2)(typescript@5.9.3))(typescript@5.9.3))(@types/pg@8.20.0)(mysql2@3.22.5(@types/node@24.10.3))(pg@8.21.0)(prisma@6.19.3(magicast@0.5.2)(typescript@5.9.3)))(ioredis@5.8.2)(jiti@2.6.1)(less@4.6.6)(lightningcss@1.30.2)(mysql2@3.22.5(@types/node@24.10.3))(rolldown@1.1.3)(sass@1.101.0)(terser@5.44.1)(tsx@4.21.0)(yaml@2.8.2)
       vite: 7.3.3(@types/node@24.10.3)(jiti@2.6.1)(less@4.6.6)(lightningcss@1.30.2)(sass@1.101.0)(terser@5.44.1)(tsx@4.21.0)(yaml@2.8.2)
       zod: 3.25.76
     transitivePeerDependencies:
@@ -22662,7 +23282,7 @@ snapshots:
 
   '@tanstack/start-fn-stubs@1.154.7': {}
 
-  '@tanstack/start-plugin-core@1.131.50(@tanstack/react-router@1.159.5(react-dom@19.2.3(react@19.2.3))(react@19.2.3))(aws4fetch@1.0.20)(rolldown@1.1.3)(vite-plugin-solid@2.11.10(solid-js@1.9.10)(vite@7.3.3(@types/node@24.10.3)(jiti@2.6.1)(less@4.6.6)(lightningcss@1.30.2)(sass@1.101.0)(terser@5.44.1)(tsx@4.21.0)(yaml@2.8.2)))(vite@7.3.3(@types/node@24.10.3)(jiti@2.6.1)(less@4.6.6)(lightningcss@1.30.2)(sass@1.101.0)(terser@5.44.1)(tsx@4.21.0)(yaml@2.8.2))':
+  '@tanstack/start-plugin-core@1.131.50(@tanstack/react-router@1.159.5(react-dom@19.2.3(react@19.2.3))(react@19.2.3))(aws4fetch@1.0.20)(drizzle-orm@0.45.2(@cloudflare/workers-types@4.20260317.1)(@opentelemetry/api@1.9.1)(@prisma/client@6.19.3(prisma@6.19.3(magicast@0.5.2)(typescript@5.9.3))(typescript@5.9.3))(@types/pg@8.20.0)(mysql2@3.22.5(@types/node@24.10.3))(pg@8.21.0)(prisma@6.19.3(magicast@0.5.2)(typescript@5.9.3)))(mysql2@3.22.5(@types/node@24.10.3))(rolldown@1.1.3)(vite-plugin-solid@2.11.10(solid-js@1.9.10)(vite@7.3.3(@types/node@24.10.3)(jiti@2.6.1)(less@4.6.6)(lightningcss@1.30.2)(sass@1.101.0)(terser@5.44.1)(tsx@4.21.0)(yaml@2.8.2)))(vite@7.3.3(@types/node@24.10.3)(jiti@2.6.1)(less@4.6.6)(lightningcss@1.30.2)(sass@1.101.0)(terser@5.44.1)(tsx@4.21.0)(yaml@2.8.2))':
     dependencies:
       '@babel/code-frame': 7.26.2
       '@babel/core': 7.29.0
@@ -22678,7 +23298,7 @@ snapshots:
       babel-dead-code-elimination: 1.0.10
       cheerio: 1.1.2
       h3: 1.13.0
-      nitropack: 2.12.9(aws4fetch@1.0.20)(rolldown@1.1.3)
+      nitropack: 2.12.9(aws4fetch@1.0.20)(drizzle-orm@0.45.2(@cloudflare/workers-types@4.20260317.1)(@opentelemetry/api@1.9.1)(@prisma/client@6.19.3(prisma@6.19.3(magicast@0.5.2)(typescript@5.9.3))(typescript@5.9.3))(@types/pg@8.20.0)(mysql2@3.22.5(@types/node@24.10.3))(pg@8.21.0)(prisma@6.19.3(magicast@0.5.2)(typescript@5.9.3)))(mysql2@3.22.5(@types/node@24.10.3))(rolldown@1.1.3)
       pathe: 2.0.3
       ufo: 1.6.1
       vite: 7.3.3(@types/node@24.10.3)(jiti@2.6.1)(less@4.6.6)(lightningcss@1.30.2)(sass@1.101.0)(terser@5.44.1)(tsx@4.21.0)(yaml@2.8.2)
@@ -22914,13 +23534,13 @@ snapshots:
     dependencies:
       '@tanstack/router-core': 1.159.4
 
-  '@tanstack/start@1.120.20(@types/node@24.10.3)(aws4fetch@1.0.20)(crossws@0.4.6(srvx@0.11.17))(db0@0.3.4)(ioredis@5.8.2)(jiti@2.6.1)(less@4.6.6)(lightningcss@1.30.2)(react-dom@19.2.3(react@19.2.3))(react@19.2.3)(rolldown@1.1.3)(sass@1.101.0)(terser@5.44.1)(tsx@4.21.0)(vite-plugin-solid@2.11.10(solid-js@1.9.10)(vite@7.3.3(@types/node@24.10.3)(jiti@2.6.1)(less@4.6.6)(lightningcss@1.30.2)(sass@1.101.0)(terser@5.44.1)(tsx@4.21.0)(yaml@2.8.2)))(vite@7.3.3(@types/node@24.10.3)(jiti@2.6.1)(less@4.6.6)(lightningcss@1.30.2)(sass@1.101.0)(terser@5.44.1)(tsx@4.21.0)(yaml@2.8.2))(yaml@2.8.2)':
+  '@tanstack/start@1.120.20(647307324c217c342a2641e0cabd8372)':
     dependencies:
       '@tanstack/react-start-client': 1.141.1(react-dom@19.2.3(react@19.2.3))(react@19.2.3)
-      '@tanstack/react-start-router-manifest': 1.120.19(@types/node@24.10.3)(aws4fetch@1.0.20)(db0@0.3.4)(ioredis@5.8.2)(jiti@2.6.1)(less@4.6.6)(lightningcss@1.30.2)(rolldown@1.1.3)(sass@1.101.0)(terser@5.44.1)(tsx@4.21.0)(yaml@2.8.2)
+      '@tanstack/react-start-router-manifest': 1.120.19(@types/node@24.10.3)(aws4fetch@1.0.20)(db0@0.3.4(drizzle-orm@0.45.2(@cloudflare/workers-types@4.20260317.1)(@opentelemetry/api@1.9.1)(@prisma/client@6.19.3(prisma@6.19.3(magicast@0.5.2)(typescript@5.9.3))(typescript@5.9.3))(@types/pg@8.20.0)(mysql2@3.22.5(@types/node@24.10.3))(pg@8.21.0)(prisma@6.19.3(magicast@0.5.2)(typescript@5.9.3)))(mysql2@3.22.5(@types/node@24.10.3)))(drizzle-orm@0.45.2(@cloudflare/workers-types@4.20260317.1)(@opentelemetry/api@1.9.1)(@prisma/client@6.19.3(prisma@6.19.3(magicast@0.5.2)(typescript@5.9.3))(typescript@5.9.3))(@types/pg@8.20.0)(mysql2@3.22.5(@types/node@24.10.3))(pg@8.21.0)(prisma@6.19.3(magicast@0.5.2)(typescript@5.9.3)))(ioredis@5.8.2)(jiti@2.6.1)(less@4.6.6)(lightningcss@1.30.2)(mysql2@3.22.5(@types/node@24.10.3))(rolldown@1.1.3)(sass@1.101.0)(terser@5.44.1)(tsx@4.21.0)(yaml@2.8.2)
       '@tanstack/react-start-server': 1.141.1(crossws@0.4.6(srvx@0.11.17))(react-dom@19.2.3(react@19.2.3))(react@19.2.3)
-      '@tanstack/start-api-routes': 1.120.19(@types/node@24.10.3)(aws4fetch@1.0.20)(crossws@0.4.6(srvx@0.11.17))(db0@0.3.4)(ioredis@5.8.2)(jiti@2.6.1)(less@4.6.6)(lightningcss@1.30.2)(rolldown@1.1.3)(sass@1.101.0)(terser@5.44.1)(tsx@4.21.0)(yaml@2.8.2)
-      '@tanstack/start-config': 1.120.20(@types/node@24.10.3)(aws4fetch@1.0.20)(crossws@0.4.6(srvx@0.11.17))(db0@0.3.4)(ioredis@5.8.2)(jiti@2.6.1)(less@4.6.6)(lightningcss@1.30.2)(react-dom@19.2.3(react@19.2.3))(react@19.2.3)(rolldown@1.1.3)(sass@1.101.0)(terser@5.44.1)(tsx@4.21.0)(vite-plugin-solid@2.11.10(solid-js@1.9.10)(vite@7.3.3(@types/node@24.10.3)(jiti@2.6.1)(less@4.6.6)(lightningcss@1.30.2)(sass@1.101.0)(terser@5.44.1)(tsx@4.21.0)(yaml@2.8.2)))(vite@7.3.3(@types/node@24.10.3)(jiti@2.6.1)(less@4.6.6)(lightningcss@1.30.2)(sass@1.101.0)(terser@5.44.1)(tsx@4.21.0)(yaml@2.8.2))(yaml@2.8.2)
+      '@tanstack/start-api-routes': 1.120.19(@types/node@24.10.3)(aws4fetch@1.0.20)(crossws@0.4.6(srvx@0.11.17))(db0@0.3.4(drizzle-orm@0.45.2(@cloudflare/workers-types@4.20260317.1)(@opentelemetry/api@1.9.1)(@prisma/client@6.19.3(prisma@6.19.3(magicast@0.5.2)(typescript@5.9.3))(typescript@5.9.3))(@types/pg@8.20.0)(mysql2@3.22.5(@types/node@24.10.3))(pg@8.21.0)(prisma@6.19.3(magicast@0.5.2)(typescript@5.9.3)))(mysql2@3.22.5(@types/node@24.10.3)))(drizzle-orm@0.45.2(@cloudflare/workers-types@4.20260317.1)(@opentelemetry/api@1.9.1)(@prisma/client@6.19.3(prisma@6.19.3(magicast@0.5.2)(typescript@5.9.3))(typescript@5.9.3))(@types/pg@8.20.0)(mysql2@3.22.5(@types/node@24.10.3))(pg@8.21.0)(prisma@6.19.3(magicast@0.5.2)(typescript@5.9.3)))(ioredis@5.8.2)(jiti@2.6.1)(less@4.6.6)(lightningcss@1.30.2)(mysql2@3.22.5(@types/node@24.10.3))(rolldown@1.1.3)(sass@1.101.0)(terser@5.44.1)(tsx@4.21.0)(yaml@2.8.2)
+      '@tanstack/start-config': 1.120.20(647307324c217c342a2641e0cabd8372)
       '@tanstack/start-server-functions-client': 1.131.50(vite@7.3.3(@types/node@24.10.3)(jiti@2.6.1)(less@4.6.6)(lightningcss@1.30.2)(sass@1.101.0)(terser@5.44.1)(tsx@4.21.0)(yaml@2.8.2))
       '@tanstack/start-server-functions-handler': 1.120.19(crossws@0.4.6(srvx@0.11.17))
       '@tanstack/start-server-functions-server': 1.131.2(vite@7.3.3(@types/node@24.10.3)(jiti@2.6.1)(less@4.6.6)(lightningcss@1.30.2)(sass@1.101.0)(terser@5.44.1)(tsx@4.21.0)(yaml@2.8.2))
@@ -23207,6 +23827,13 @@ snapshots:
     dependencies:
       undici-types: 7.16.0
 
+  '@types/pg@8.20.0':
+    dependencies:
+      '@types/node': 24.10.3
+      pg-protocol: 1.14.0
+      pg-types: 2.2.0
+    optional: true
+
   '@types/react-dom@19.2.3(@types/react@19.2.7)':
     dependencies:
       '@types/react': 19.2.7
@@ -24073,6 +24700,9 @@ snapshots:
     dependencies:
       possible-typed-array-names: 1.1.0
 
+  aws-ssl-profiles@1.1.2:
+    optional: true
+
   aws4fetch@1.0.20: {}
 
   axios@1.13.2:
@@ -24429,6 +25059,23 @@ snapshots:
 
   bytes@3.1.2: {}
 
+  c12@3.1.0(magicast@0.5.2):
+    dependencies:
+      chokidar: 4.0.3
+      confbox: 0.2.2
+      defu: 6.1.4
+      dotenv: 16.6.1
+      exsolve: 1.0.8
+      giget: 2.0.0
+      jiti: 2.6.1
+      ohash: 2.0.11
+      pathe: 2.0.3
+      perfect-debounce: 1.0.0
+      pkg-types: 2.3.0
+      rc9: 2.1.2
+    optionalDependencies:
+      magicast: 0.5.2
+
   c12@3.3.2(magicast@0.5.2):
     dependencies:
       chokidar: 4.0.3
@@ -24943,7 +25590,15 @@ snapshots:
 
   dayjs@1.11.19: {}
 
-  db0@0.3.4: {}
+  db0@0.3.4(drizzle-orm@0.45.2(@cloudflare/workers-types@4.20260317.1)(@opentelemetry/api@1.9.1)(@prisma/client@6.19.3(prisma@6.19.3(magicast@0.5.2)(typescript@5.9.3))(typescript@5.9.3))(@types/pg@8.20.0)(mysql2@3.22.5(@types/node@24.10.3))(pg@8.21.0)(prisma@6.19.3(magicast@0.5.2)(typescript@5.9.3)))(mysql2@3.22.5(@types/node@24.10.3)):
+    optionalDependencies:
+      drizzle-orm: 0.45.2(@cloudflare/workers-types@4.20260317.1)(@opentelemetry/api@1.9.1)(@prisma/client@6.19.3(prisma@6.19.3(magicast@0.5.2)(typescript@5.9.3))(typescript@5.9.3))(@types/pg@8.20.0)(mysql2@3.22.5(@types/node@24.10.3))(pg@8.21.0)(prisma@6.19.3(magicast@0.5.2)(typescript@5.9.3))
+      mysql2: 3.22.5(@types/node@24.10.3)
+
+  db0@0.3.4(drizzle-orm@0.45.2(@opentelemetry/api@1.9.1)(@prisma/client@6.19.3(prisma@6.19.3(typescript@5.9.3))(typescript@5.9.3))(@types/pg@8.20.0)(mysql2@3.22.5(@types/node@24.10.3))(pg@8.21.0)(prisma@6.19.3(typescript@5.9.3)))(mysql2@3.22.5(@types/node@24.10.3)):
+    optionalDependencies:
+      drizzle-orm: 0.45.2(@cloudflare/workers-types@4.20260317.1)(@opentelemetry/api@1.9.1)(@prisma/client@6.19.3(prisma@6.19.3(typescript@5.9.3))(typescript@5.9.3))(@types/pg@8.20.0)(mysql2@3.22.5(@types/node@24.10.3))(pg@8.21.0)(prisma@6.19.3(typescript@5.9.3))
+      mysql2: 3.22.5(@types/node@24.10.3)
 
   de-indent@1.0.2: {}
 
@@ -24992,6 +25647,8 @@ snapshots:
 
   deep-is@0.1.4: {}
 
+  deepmerge-ts@7.1.5: {}
+
   deepmerge@4.3.1: {}
 
   defaults@1.0.4:
@@ -25120,6 +25777,34 @@ snapshots:
 
   dotenv@8.6.0: {}
 
+  drizzle-kit@0.31.10:
+    dependencies:
+      '@drizzle-team/brocli': 0.10.2
+      '@esbuild-kit/esm-loader': 2.6.5
+      esbuild: 0.25.12
+      tsx: 4.21.0
+
+  drizzle-orm@0.45.2(@cloudflare/workers-types@4.20260317.1)(@opentelemetry/api@1.9.1)(@prisma/client@6.19.3(prisma@6.19.3(magicast@0.5.2)(typescript@5.9.3))(typescript@5.9.3))(@types/pg@8.20.0)(mysql2@3.22.5(@types/node@24.10.3))(pg@8.21.0)(prisma@6.19.3(magicast@0.5.2)(typescript@5.9.3)):
+    optionalDependencies:
+      '@cloudflare/workers-types': 4.20260317.1
+      '@opentelemetry/api': 1.9.1
+      '@prisma/client': 6.19.3(prisma@6.19.3(typescript@5.9.3))(typescript@5.9.3)
+      '@types/pg': 8.20.0
+      mysql2: 3.22.5(@types/node@24.10.3)
+      pg: 8.21.0
+      prisma: 6.19.3(magicast@0.5.2)(typescript@5.9.3)
+    optional: true
+
+  drizzle-orm@0.45.2(@cloudflare/workers-types@4.20260317.1)(@opentelemetry/api@1.9.1)(@prisma/client@6.19.3(prisma@6.19.3(typescript@5.9.3))(typescript@5.9.3))(@types/pg@8.20.0)(mysql2@3.22.5(@types/node@24.10.3))(pg@8.21.0)(prisma@6.19.3(typescript@5.9.3)):
+    optionalDependencies:
+      '@cloudflare/workers-types': 4.20260317.1
+      '@opentelemetry/api': 1.9.1
+      '@prisma/client': 6.19.3(prisma@6.19.3(typescript@5.9.3))(typescript@5.9.3)
+      '@types/pg': 8.20.0
+      mysql2: 3.22.5(@types/node@24.10.3)
+      pg: 8.21.0
+      prisma: 6.19.3(magicast@0.5.2)(typescript@5.9.3)
+
   dts-resolver@2.1.3(oxc-resolver@11.15.0(@emnapi/core@1.11.1)(@emnapi/runtime@1.11.1)):
     optionalDependencies:
       oxc-resolver: 11.15.0(@emnapi/core@1.11.1)(@emnapi/runtime@1.11.1)
@@ -25147,6 +25832,11 @@ snapshots:
 
   ee-first@1.1.1: {}
 
+  effect@3.21.0:
+    dependencies:
+      '@standard-schema/spec': 1.1.0
+      fast-check: 3.23.2
+
   electron-to-chromium@1.5.267: {}
 
   emoji-regex@10.6.0: {}
@@ -25258,6 +25948,31 @@ snapshots:
     transitivePeerDependencies:
       - supports-color
 
+  esbuild@0.18.20:
+    optionalDependencies:
+      '@esbuild/android-arm': 0.18.20
+      '@esbuild/android-arm64': 0.18.20
+      '@esbuild/android-x64': 0.18.20
+      '@esbuild/darwin-arm64': 0.18.20
+      '@esbuild/darwin-x64': 0.18.20
+      '@esbuild/freebsd-arm64': 0.18.20
+      '@esbuild/freebsd-x64': 0.18.20
+      '@esbuild/linux-arm': 0.18.20
+      '@esbuild/linux-arm64': 0.18.20
+      '@esbuild/linux-ia32': 0.18.20
+      '@esbuild/linux-loong64': 0.18.20
+      '@esbuild/linux-mips64el': 0.18.20
+      '@esbuild/linux-ppc64': 0.18.20
+      '@esbuild/linux-riscv64': 0.18.20
+      '@esbuild/linux-s390x': 0.18.20
+      '@esbuild/linux-x64': 0.18.20
+      '@esbuild/netbsd-x64': 0.18.20
+      '@esbuild/openbsd-x64': 0.18.20
+      '@esbuild/sunos-x64': 0.18.20
+      '@esbuild/win32-arm64': 0.18.20
+      '@esbuild/win32-ia32': 0.18.20
+      '@esbuild/win32-x64': 0.18.20
+
   esbuild@0.20.2:
     optionalDependencies:
       '@esbuild/aix-ppc64': 0.20.2
@@ -25817,6 +26532,10 @@ snapshots:
     transitivePeerDependencies:
       - supports-color
 
+  fast-check@3.23.2:
+    dependencies:
+      pure-rand: 6.1.0
+
   fast-deep-equal@3.1.3: {}
 
   fast-equals@5.4.0: {}
@@ -26054,6 +26773,11 @@ snapshots:
     transitivePeerDependencies:
       - supports-color
 
+  generate-function@2.3.1:
+    dependencies:
+      is-property: 1.0.2
+    optional: true
+
   gensync@1.0.0-beta.2: {}
 
   get-caller-file@2.0.5: {}
@@ -26502,6 +27226,11 @@ snapshots:
     dependencies:
       safer-buffer: 2.1.2
 
+  iconv-lite@0.7.2:
+    dependencies:
+      safer-buffer: 2.1.2
+    optional: true
+
   ieee754@1.2.1: {}
 
   ignore@5.3.2: {}
@@ -26694,6 +27423,9 @@ snapshots:
 
   is-promise@4.0.0: {}
 
+  is-property@1.0.2:
+    optional: true
+
   is-reference@1.2.1:
     dependencies:
       '@types/estree': 1.0.8
@@ -27312,6 +28044,9 @@ snapshots:
 
   lru-cache@7.18.3: {}
 
+  lru.min@1.1.4:
+    optional: true
+
   lucide-react@0.561.0(react@19.2.3):
     dependencies:
       react: 19.2.3
@@ -28094,12 +28829,30 @@ snapshots:
 
   mute-stream@2.0.0: {}
 
+  mysql2@3.22.5(@types/node@24.10.3):
+    dependencies:
+      '@types/node': 24.10.3
+      aws-ssl-profiles: 1.1.2
+      denque: 2.1.0
+      generate-function: 2.3.1
+      iconv-lite: 0.7.2
+      long: 5.3.2
+      lru.min: 1.1.4
+      named-placeholders: 1.1.6
+      sql-escaper: 1.3.3
+    optional: true
+
   mz@2.7.0:
     dependencies:
       any-promise: 1.3.0
       object-assign: 4.1.1
       thenify-all: 1.6.0
 
+  named-placeholders@1.1.6:
+    dependencies:
+      lru.min: 1.1.4
+    optional: true
+
   nan@2.27.0:
     optional: true
 
@@ -28159,11 +28912,11 @@ snapshots:
       rollup: 4.60.1
       tailwindcss: 4.1.18
 
-  nitro@3.0.1-alpha.2(@emnapi/core@1.11.1)(@emnapi/runtime@1.11.1)(aws4fetch@1.0.20)(chokidar@5.0.0)(rolldown@1.1.3)(rollup@4.60.1)(vite@7.3.3(@types/node@24.10.3)(jiti@2.6.1)(less@4.6.6)(lightningcss@1.30.2)(sass@1.101.0)(terser@5.44.1)(tsx@4.21.0)(yaml@2.8.2)):
+  nitro@3.0.1-alpha.2(@emnapi/core@1.11.1)(@emnapi/runtime@1.11.1)(aws4fetch@1.0.20)(chokidar@5.0.0)(drizzle-orm@0.45.2(@cloudflare/workers-types@4.20260317.1)(@opentelemetry/api@1.9.1)(@prisma/client@6.19.3(prisma@6.19.3(typescript@5.9.3))(typescript@5.9.3))(@types/pg@8.20.0)(mysql2@3.22.5(@types/node@24.10.3))(pg@8.21.0)(prisma@6.19.3(typescript@5.9.3)))(mysql2@3.22.5(@types/node@24.10.3))(rolldown@1.1.3)(rollup@4.60.1)(vite@7.3.3(@types/node@24.10.3)(jiti@2.6.1)(less@4.6.6)(lightningcss@1.30.2)(sass@1.101.0)(terser@5.44.1)(tsx@4.21.0)(yaml@2.8.2)):
     dependencies:
       consola: 3.4.2
       crossws: 0.4.6(srvx@0.10.1)
-      db0: 0.3.4
+      db0: 0.3.4(drizzle-orm@0.45.2(@opentelemetry/api@1.9.1)(@prisma/client@6.19.3(prisma@6.19.3(typescript@5.9.3))(typescript@5.9.3))(@types/pg@8.20.0)(mysql2@3.22.5(@types/node@24.10.3))(pg@8.21.0)(prisma@6.19.3(typescript@5.9.3)))(mysql2@3.22.5(@types/node@24.10.3))
       h3: 2.0.1-rc.22(crossws@0.4.6(srvx@0.10.1))
       jiti: 2.6.1
       nf3: 0.3.17
@@ -28174,7 +28927,7 @@ snapshots:
       srvx: 0.10.1
       undici: 7.28.0
       unenv: 2.0.0-rc.24
-      unstorage: 2.0.0-alpha.7(aws4fetch@1.0.20)(chokidar@5.0.0)(db0@0.3.4)(ofetch@2.0.0-alpha.3)
+      unstorage: 2.0.0-alpha.7(aws4fetch@1.0.20)(chokidar@5.0.0)(db0@0.3.4(drizzle-orm@0.45.2(@opentelemetry/api@1.9.1)(@prisma/client@6.19.3(prisma@6.19.3(typescript@5.9.3))(typescript@5.9.3))(@types/pg@8.20.0)(mysql2@3.22.5(@types/node@24.10.3))(pg@8.21.0)(prisma@6.19.3(typescript@5.9.3)))(mysql2@3.22.5(@types/node@24.10.3)))(ofetch@2.0.0-alpha.3)
     optionalDependencies:
       rolldown: 1.1.3
       rollup: 4.60.1
@@ -28210,11 +28963,11 @@ snapshots:
       - sqlite3
       - uploadthing
 
-  nitro@3.0.260610-beta(aws4fetch@1.0.20)(chokidar@5.0.0)(dotenv@17.2.3)(giget@2.0.0)(jiti@2.6.1)(miniflare@4.20260617.1)(rollup@4.60.1)(vite@7.3.3(@types/node@24.10.3)(jiti@2.6.1)(less@4.6.6)(lightningcss@1.30.2)(sass@1.101.0)(terser@5.44.1)(tsx@4.21.0)(yaml@2.8.2))(wrangler@4.103.0):
+  nitro@3.0.260610-beta(aws4fetch@1.0.20)(chokidar@5.0.0)(dotenv@17.2.3)(drizzle-orm@0.45.2(@opentelemetry/api@1.9.1)(@prisma/client@6.19.3(prisma@6.19.3(typescript@5.9.3))(typescript@5.9.3))(@types/pg@8.20.0)(mysql2@3.22.5(@types/node@24.10.3))(pg@8.21.0)(prisma@6.19.3(typescript@5.9.3)))(giget@2.0.0)(jiti@2.6.1)(miniflare@4.20260617.1)(mysql2@3.22.5(@types/node@24.10.3))(rollup@4.60.1)(vite@7.3.3(@types/node@24.10.3)(jiti@2.6.1)(less@4.6.6)(lightningcss@1.30.2)(sass@1.101.0)(terser@5.44.1)(tsx@4.21.0)(yaml@2.8.2))(wrangler@4.103.0):
     dependencies:
       consola: 3.4.2
       crossws: 0.4.6(srvx@0.11.17)
-      db0: 0.3.4
+      db0: 0.3.4(drizzle-orm@0.45.2(@opentelemetry/api@1.9.1)(@prisma/client@6.19.3(prisma@6.19.3(typescript@5.9.3))(typescript@5.9.3))(@types/pg@8.20.0)(mysql2@3.22.5(@types/node@24.10.3))(pg@8.21.0)(prisma@6.19.3(typescript@5.9.3)))(mysql2@3.22.5(@types/node@24.10.3))
       env-runner: 0.1.14(miniflare@4.20260617.1)(wrangler@4.103.0)
       h3: 2.0.1-rc.22(crossws@0.4.6(srvx@0.11.17))
       hookable: 6.1.1
@@ -28225,7 +28978,7 @@ snapshots:
       rolldown: 1.1.3
       srvx: 0.11.17
       unenv: 2.0.0-rc.24
-      unstorage: 2.0.0-alpha.7(aws4fetch@1.0.20)(chokidar@5.0.0)(db0@0.3.4)(ofetch@2.0.0-alpha.3)
+      unstorage: 2.0.0-alpha.7(aws4fetch@1.0.20)(chokidar@5.0.0)(db0@0.3.4(drizzle-orm@0.45.2(@opentelemetry/api@1.9.1)(@prisma/client@6.19.3(prisma@6.19.3(typescript@5.9.3))(typescript@5.9.3))(@types/pg@8.20.0)(mysql2@3.22.5(@types/node@24.10.3))(pg@8.21.0)(prisma@6.19.3(typescript@5.9.3)))(mysql2@3.22.5(@types/node@24.10.3)))(ofetch@2.0.0-alpha.3)
     optionalDependencies:
       dotenv: 17.2.3
       giget: 2.0.0
@@ -28264,7 +29017,7 @@ snapshots:
       - uploadthing
       - wrangler
 
-  nitropack@2.12.9(aws4fetch@1.0.20)(rolldown@1.1.3):
+  nitropack@2.12.9(aws4fetch@1.0.20)(drizzle-orm@0.45.2(@cloudflare/workers-types@4.20260317.1)(@opentelemetry/api@1.9.1)(@prisma/client@6.19.3(prisma@6.19.3(magicast@0.5.2)(typescript@5.9.3))(typescript@5.9.3))(@types/pg@8.20.0)(mysql2@3.22.5(@types/node@24.10.3))(pg@8.21.0)(prisma@6.19.3(magicast@0.5.2)(typescript@5.9.3)))(mysql2@3.22.5(@types/node@24.10.3))(rolldown@1.1.3):
     dependencies:
       '@cloudflare/kv-asset-handler': 0.4.2
       '@rollup/plugin-alias': 5.1.1(rollup@4.60.1)
@@ -28285,7 +29038,7 @@ snapshots:
       cookie-es: 2.0.1
       croner: 9.1.0
       crossws: 0.3.5
-      db0: 0.3.4
+      db0: 0.3.4(drizzle-orm@0.45.2(@cloudflare/workers-types@4.20260317.1)(@opentelemetry/api@1.9.1)(@prisma/client@6.19.3(prisma@6.19.3(magicast@0.5.2)(typescript@5.9.3))(typescript@5.9.3))(@types/pg@8.20.0)(mysql2@3.22.5(@types/node@24.10.3))(pg@8.21.0)(prisma@6.19.3(magicast@0.5.2)(typescript@5.9.3)))(mysql2@3.22.5(@types/node@24.10.3))
       defu: 6.1.4
       destr: 2.0.5
       dot-prop: 10.1.0
@@ -28331,7 +29084,7 @@ snapshots:
       unenv: 2.0.0-rc.24
       unimport: 5.5.0
       unplugin-utils: 0.3.1
-      unstorage: 1.17.4(aws4fetch@1.0.20)(db0@0.3.4)(ioredis@5.8.2)
+      unstorage: 1.17.4(aws4fetch@1.0.20)(db0@0.3.4(drizzle-orm@0.45.2(@cloudflare/workers-types@4.20260317.1)(@opentelemetry/api@1.9.1)(@prisma/client@6.19.3(prisma@6.19.3(magicast@0.5.2)(typescript@5.9.3))(typescript@5.9.3))(@types/pg@8.20.0)(mysql2@3.22.5(@types/node@24.10.3))(pg@8.21.0)(prisma@6.19.3(magicast@0.5.2)(typescript@5.9.3)))(mysql2@3.22.5(@types/node@24.10.3)))(ioredis@5.8.2)
       untyped: 2.0.0
       unwasm: 0.3.11
       youch: 4.1.0-beta.13
@@ -28366,7 +29119,109 @@ snapshots:
       - supports-color
       - uploadthing
 
-  nitropack@2.13.1(aws4fetch@1.0.20)(rolldown@1.1.3):
+  nitropack@2.13.1(aws4fetch@1.0.20)(drizzle-orm@0.45.2(@cloudflare/workers-types@4.20260317.1)(@opentelemetry/api@1.9.1)(@prisma/client@6.19.3(prisma@6.19.3(magicast@0.5.2)(typescript@5.9.3))(typescript@5.9.3))(@types/pg@8.20.0)(mysql2@3.22.5(@types/node@24.10.3))(pg@8.21.0)(prisma@6.19.3(magicast@0.5.2)(typescript@5.9.3)))(mysql2@3.22.5(@types/node@24.10.3))(rolldown@1.1.3):
+    dependencies:
+      '@cloudflare/kv-asset-handler': 0.4.2
+      '@rollup/plugin-alias': 6.0.0(rollup@4.57.1)
+      '@rollup/plugin-commonjs': 29.0.0(rollup@4.57.1)
+      '@rollup/plugin-inject': 5.0.5(rollup@4.57.1)
+      '@rollup/plugin-json': 6.1.0(rollup@4.57.1)
+      '@rollup/plugin-node-resolve': 16.0.3(rollup@4.57.1)
+      '@rollup/plugin-replace': 6.0.3(rollup@4.57.1)
+      '@rollup/plugin-terser': 0.4.4(rollup@4.57.1)
+      '@vercel/nft': 1.3.0(rollup@4.57.1)
+      archiver: 7.0.1
+      c12: 3.3.3(magicast@0.5.2)
+      chokidar: 5.0.0
+      citty: 0.1.6
+      compatx: 0.2.0
+      confbox: 0.2.2
+      consola: 3.4.2
+      cookie-es: 2.0.0
+      croner: 9.1.0
+      crossws: 0.3.5
+      db0: 0.3.4(drizzle-orm@0.45.2(@cloudflare/workers-types@4.20260317.1)(@opentelemetry/api@1.9.1)(@prisma/client@6.19.3(prisma@6.19.3(magicast@0.5.2)(typescript@5.9.3))(typescript@5.9.3))(@types/pg@8.20.0)(mysql2@3.22.5(@types/node@24.10.3))(pg@8.21.0)(prisma@6.19.3(magicast@0.5.2)(typescript@5.9.3)))(mysql2@3.22.5(@types/node@24.10.3))
+      defu: 6.1.4
+      destr: 2.0.5
+      dot-prop: 10.1.0
+      esbuild: 0.27.7
+      escape-string-regexp: 5.0.0
+      etag: 1.8.1
+      exsolve: 1.0.8
+      globby: 16.1.0
+      gzip-size: 7.0.0
+      h3: 1.15.5
+      hookable: 5.5.3
+      httpxy: 0.1.7
+      ioredis: 5.9.2
+      jiti: 2.6.1
+      klona: 2.0.6
+      knitwork: 1.3.0
+      listhen: 1.9.0
+      magic-string: 0.30.21
+      magicast: 0.5.2
+      mime: 4.1.0
+      mlly: 1.8.0
+      node-fetch-native: 1.6.7
+      node-mock-http: 1.0.4
+      ofetch: 1.5.1
+      ohash: 2.0.11
+      pathe: 2.0.3
+      perfect-debounce: 2.0.0
+      pkg-types: 2.3.0
+      pretty-bytes: 7.1.0
+      radix3: 1.1.2
+      rollup: 4.57.1
+      rollup-plugin-visualizer: 6.0.5(rolldown@1.1.3)(rollup@4.57.1)
+      scule: 1.3.0
+      semver: 7.7.4
+      serve-placeholder: 2.0.2
+      serve-static: 2.2.1
+      source-map: 0.7.6
+      std-env: 3.10.0
+      ufo: 1.6.3
+      ultrahtml: 1.6.0
+      uncrypto: 0.1.3
+      unctx: 2.5.0
+      unenv: 2.0.0-rc.24
+      unimport: 5.6.0
+      unplugin-utils: 0.3.1
+      unstorage: 1.17.4(aws4fetch@1.0.20)(db0@0.3.4(drizzle-orm@0.45.2(@cloudflare/workers-types@4.20260317.1)(@opentelemetry/api@1.9.1)(@prisma/client@6.19.3(prisma@6.19.3(magicast@0.5.2)(typescript@5.9.3))(typescript@5.9.3))(@types/pg@8.20.0)(mysql2@3.22.5(@types/node@24.10.3))(pg@8.21.0)(prisma@6.19.3(magicast@0.5.2)(typescript@5.9.3)))(mysql2@3.22.5(@types/node@24.10.3)))(ioredis@5.9.2)
+      untyped: 2.0.0
+      unwasm: 0.5.3
+      youch: 4.1.0-beta.13
+      youch-core: 0.3.3
+    transitivePeerDependencies:
+      - '@azure/app-configuration'
+      - '@azure/cosmos'
+      - '@azure/data-tables'
+      - '@azure/identity'
+      - '@azure/keyvault-secrets'
+      - '@azure/storage-blob'
+      - '@capacitor/preferences'
+      - '@deno/kv'
+      - '@electric-sql/pglite'
+      - '@libsql/client'
+      - '@netlify/blobs'
+      - '@planetscale/database'
+      - '@upstash/redis'
+      - '@vercel/blob'
+      - '@vercel/functions'
+      - '@vercel/kv'
+      - aws4fetch
+      - bare-abort-controller
+      - better-sqlite3
+      - drizzle-orm
+      - encoding
+      - idb-keyval
+      - mysql2
+      - react-native-b4a
+      - rolldown
+      - sqlite3
+      - supports-color
+      - uploadthing
+
+  nitropack@2.13.1(aws4fetch@1.0.20)(drizzle-orm@0.45.2(@cloudflare/workers-types@4.20260317.1)(@opentelemetry/api@1.9.1)(@prisma/client@6.19.3(prisma@6.19.3(typescript@5.9.3))(typescript@5.9.3))(@types/pg@8.20.0)(mysql2@3.22.5(@types/node@24.10.3))(pg@8.21.0)(prisma@6.19.3(typescript@5.9.3)))(mysql2@3.22.5(@types/node@24.10.3))(rolldown@1.1.3):
     dependencies:
       '@cloudflare/kv-asset-handler': 0.4.2
       '@rollup/plugin-alias': 6.0.0(rollup@4.57.1)
@@ -28387,7 +29242,7 @@ snapshots:
       cookie-es: 2.0.0
       croner: 9.1.0
       crossws: 0.3.5
-      db0: 0.3.4
+      db0: 0.3.4(drizzle-orm@0.45.2(@opentelemetry/api@1.9.1)(@prisma/client@6.19.3(prisma@6.19.3(typescript@5.9.3))(typescript@5.9.3))(@types/pg@8.20.0)(mysql2@3.22.5(@types/node@24.10.3))(pg@8.21.0)(prisma@6.19.3(typescript@5.9.3)))(mysql2@3.22.5(@types/node@24.10.3))
       defu: 6.1.4
       destr: 2.0.5
       dot-prop: 10.1.0
@@ -28433,7 +29288,7 @@ snapshots:
       unenv: 2.0.0-rc.24
       unimport: 5.6.0
       unplugin-utils: 0.3.1
-      unstorage: 1.17.4(aws4fetch@1.0.20)(db0@0.3.4)(ioredis@5.9.2)
+      unstorage: 1.17.4(aws4fetch@1.0.20)(db0@0.3.4(drizzle-orm@0.45.2(@cloudflare/workers-types@4.20260317.1)(@opentelemetry/api@1.9.1)(@prisma/client@6.19.3(prisma@6.19.3(typescript@5.9.3))(typescript@5.9.3))(@types/pg@8.20.0)(mysql2@3.22.5(@types/node@24.10.3))(pg@8.21.0)(prisma@6.19.3(typescript@5.9.3)))(mysql2@3.22.5(@types/node@24.10.3)))(ioredis@5.9.2)
       untyped: 2.0.0
       unwasm: 0.5.3
       youch: 4.1.0-beta.13
@@ -28968,8 +29823,52 @@ snapshots:
 
   pend@1.2.0: {}
 
+  perfect-debounce@1.0.0: {}
+
   perfect-debounce@2.0.0: {}
 
+  pg-cloudflare@1.4.0:
+    optional: true
+
+  pg-connection-string@2.13.0:
+    optional: true
+
+  pg-int8@1.0.1:
+    optional: true
+
+  pg-pool@3.14.0(pg@8.21.0):
+    dependencies:
+      pg: 8.21.0
+    optional: true
+
+  pg-protocol@1.14.0:
+    optional: true
+
+  pg-types@2.2.0:
+    dependencies:
+      pg-int8: 1.0.1
+      postgres-array: 2.0.0
+      postgres-bytea: 1.0.1
+      postgres-date: 1.0.7
+      postgres-interval: 1.2.0
+    optional: true
+
+  pg@8.21.0:
+    dependencies:
+      pg-connection-string: 2.13.0
+      pg-pool: 3.14.0(pg@8.21.0)
+      pg-protocol: 1.14.0
+      pg-types: 2.2.0
+      pgpass: 1.0.5
+    optionalDependencies:
+      pg-cloudflare: 1.4.0
+    optional: true
+
+  pgpass@1.0.5:
+    dependencies:
+      split2: 4.2.0
+    optional: true
+
   picocolors@1.1.1: {}
 
   picomatch@2.3.1: {}
@@ -29059,11 +29958,19 @@ snapshots:
       picocolors: 1.1.1
       source-map-js: 1.2.1
 
-  postcss@8.5.9:
+  postgres-array@2.0.0:
+    optional: true
+
+  postgres-bytea@1.0.1:
+    optional: true
+
+  postgres-date@1.0.7:
+    optional: true
+
+  postgres-interval@1.2.0:
     dependencies:
-      nanoid: 3.3.11
-      picocolors: 1.1.1
-      source-map-js: 1.2.1
+      xtend: 4.0.2
+    optional: true
 
   preact@10.28.1: {}
 
@@ -29102,6 +30009,15 @@ snapshots:
       ansi-styles: 5.2.0
       react-is: 18.3.1
 
+  prisma@6.19.3(magicast@0.5.2)(typescript@5.9.3):
+    dependencies:
+      '@prisma/config': 6.19.3(magicast@0.5.2)
+      '@prisma/engines': 6.19.3
+    optionalDependencies:
+      typescript: 5.9.3
+    transitivePeerDependencies:
+      - magicast
+
   proc-log@4.2.0: {}
 
   process-nextick-args@2.0.1: {}
@@ -29250,6 +30166,8 @@ snapshots:
       - typescript
       - utf-8-validate
 
+  pure-rand@6.1.0: {}
+
   qs@6.14.0:
     dependencies:
       side-channel: 1.1.0
@@ -30310,8 +31228,14 @@ snapshots:
 
   split-ca@1.0.1: {}
 
+  split2@4.2.0:
+    optional: true
+
   sprintf-js@1.0.3: {}
 
+  sql-escaper@1.3.3:
+    optional: true
+
   srvx@0.10.1: {}
 
   srvx@0.11.17: {}
@@ -31060,7 +31984,7 @@ snapshots:
     dependencies:
       rolldown: 1.0.0-beta.53
 
-  unstorage@1.17.4(aws4fetch@1.0.20)(db0@0.3.4)(ioredis@5.8.2):
+  unstorage@1.17.4(aws4fetch@1.0.20)(db0@0.3.4(drizzle-orm@0.45.2(@cloudflare/workers-types@4.20260317.1)(@opentelemetry/api@1.9.1)(@prisma/client@6.19.3(prisma@6.19.3(magicast@0.5.2)(typescript@5.9.3))(typescript@5.9.3))(@types/pg@8.20.0)(mysql2@3.22.5(@types/node@24.10.3))(pg@8.21.0)(prisma@6.19.3(magicast@0.5.2)(typescript@5.9.3)))(mysql2@3.22.5(@types/node@24.10.3)))(ioredis@5.8.2):
     dependencies:
       anymatch: 3.1.3
       chokidar: 5.0.0
@@ -31072,10 +31996,25 @@ snapshots:
       ufo: 1.6.3
     optionalDependencies:
       aws4fetch: 1.0.20
-      db0: 0.3.4
+      db0: 0.3.4(drizzle-orm@0.45.2(@cloudflare/workers-types@4.20260317.1)(@opentelemetry/api@1.9.1)(@prisma/client@6.19.3(prisma@6.19.3(magicast@0.5.2)(typescript@5.9.3))(typescript@5.9.3))(@types/pg@8.20.0)(mysql2@3.22.5(@types/node@24.10.3))(pg@8.21.0)(prisma@6.19.3(magicast@0.5.2)(typescript@5.9.3)))(mysql2@3.22.5(@types/node@24.10.3))
       ioredis: 5.8.2
 
-  unstorage@1.17.4(aws4fetch@1.0.20)(db0@0.3.4)(ioredis@5.9.2):
+  unstorage@1.17.4(aws4fetch@1.0.20)(db0@0.3.4(drizzle-orm@0.45.2(@cloudflare/workers-types@4.20260317.1)(@opentelemetry/api@1.9.1)(@prisma/client@6.19.3(prisma@6.19.3(magicast@0.5.2)(typescript@5.9.3))(typescript@5.9.3))(@types/pg@8.20.0)(mysql2@3.22.5(@types/node@24.10.3))(pg@8.21.0)(prisma@6.19.3(magicast@0.5.2)(typescript@5.9.3)))(mysql2@3.22.5(@types/node@24.10.3)))(ioredis@5.9.2):
+    dependencies:
+      anymatch: 3.1.3
+      chokidar: 5.0.0
+      destr: 2.0.5
+      h3: 1.15.5
+      lru-cache: 11.2.4
+      node-fetch-native: 1.6.7
+      ofetch: 1.5.1
+      ufo: 1.6.3
+    optionalDependencies:
+      aws4fetch: 1.0.20
+      db0: 0.3.4(drizzle-orm@0.45.2(@cloudflare/workers-types@4.20260317.1)(@opentelemetry/api@1.9.1)(@prisma/client@6.19.3(prisma@6.19.3(magicast@0.5.2)(typescript@5.9.3))(typescript@5.9.3))(@types/pg@8.20.0)(mysql2@3.22.5(@types/node@24.10.3))(pg@8.21.0)(prisma@6.19.3(magicast@0.5.2)(typescript@5.9.3)))(mysql2@3.22.5(@types/node@24.10.3))
+      ioredis: 5.9.2
+
+  unstorage@1.17.4(aws4fetch@1.0.20)(db0@0.3.4(drizzle-orm@0.45.2(@cloudflare/workers-types@4.20260317.1)(@opentelemetry/api@1.9.1)(@prisma/client@6.19.3(prisma@6.19.3(typescript@5.9.3))(typescript@5.9.3))(@types/pg@8.20.0)(mysql2@3.22.5(@types/node@24.10.3))(pg@8.21.0)(prisma@6.19.3(typescript@5.9.3)))(mysql2@3.22.5(@types/node@24.10.3)))(ioredis@5.9.2):
     dependencies:
       anymatch: 3.1.3
       chokidar: 5.0.0
@@ -31087,14 +32026,14 @@ snapshots:
       ufo: 1.6.3
     optionalDependencies:
       aws4fetch: 1.0.20
-      db0: 0.3.4
+      db0: 0.3.4(drizzle-orm@0.45.2(@opentelemetry/api@1.9.1)(@prisma/client@6.19.3(prisma@6.19.3(typescript@5.9.3))(typescript@5.9.3))(@types/pg@8.20.0)(mysql2@3.22.5(@types/node@24.10.3))(pg@8.21.0)(prisma@6.19.3(typescript@5.9.3)))(mysql2@3.22.5(@types/node@24.10.3))
       ioredis: 5.9.2
 
-  unstorage@2.0.0-alpha.7(aws4fetch@1.0.20)(chokidar@5.0.0)(db0@0.3.4)(ofetch@2.0.0-alpha.3):
+  unstorage@2.0.0-alpha.7(aws4fetch@1.0.20)(chokidar@5.0.0)(db0@0.3.4(drizzle-orm@0.45.2(@opentelemetry/api@1.9.1)(@prisma/client@6.19.3(prisma@6.19.3(typescript@5.9.3))(typescript@5.9.3))(@types/pg@8.20.0)(mysql2@3.22.5(@types/node@24.10.3))(pg@8.21.0)(prisma@6.19.3(typescript@5.9.3)))(mysql2@3.22.5(@types/node@24.10.3)))(ofetch@2.0.0-alpha.3):
     optionalDependencies:
       aws4fetch: 1.0.20
       chokidar: 5.0.0
-      db0: 0.3.4
+      db0: 0.3.4(drizzle-orm@0.45.2(@opentelemetry/api@1.9.1)(@prisma/client@6.19.3(prisma@6.19.3(typescript@5.9.3))(typescript@5.9.3))(@types/pg@8.20.0)(mysql2@3.22.5(@types/node@24.10.3))(pg@8.21.0)(prisma@6.19.3(typescript@5.9.3)))(mysql2@3.22.5(@types/node@24.10.3))
       ofetch: 2.0.0-alpha.3
 
   untun@0.1.3:
@@ -31204,7 +32143,7 @@ snapshots:
       d3-time: 3.1.0
       d3-timer: 3.0.1
 
-  vinxi@0.5.3(@types/node@24.10.3)(aws4fetch@1.0.20)(db0@0.3.4)(ioredis@5.8.2)(jiti@2.6.1)(less@4.6.6)(lightningcss@1.30.2)(rolldown@1.1.3)(sass@1.101.0)(terser@5.44.1)(tsx@4.21.0)(yaml@2.8.2):
+  vinxi@0.5.3(@types/node@24.10.3)(aws4fetch@1.0.20)(db0@0.3.4(drizzle-orm@0.45.2(@cloudflare/workers-types@4.20260317.1)(@opentelemetry/api@1.9.1)(@prisma/client@6.19.3(prisma@6.19.3(magicast@0.5.2)(typescript@5.9.3))(typescript@5.9.3))(@types/pg@8.20.0)(mysql2@3.22.5(@types/node@24.10.3))(pg@8.21.0)(prisma@6.19.3(magicast@0.5.2)(typescript@5.9.3)))(mysql2@3.22.5(@types/node@24.10.3)))(drizzle-orm@0.45.2(@cloudflare/workers-types@4.20260317.1)(@opentelemetry/api@1.9.1)(@prisma/client@6.19.3(prisma@6.19.3(magicast@0.5.2)(typescript@5.9.3))(typescript@5.9.3))(@types/pg@8.20.0)(mysql2@3.22.5(@types/node@24.10.3))(pg@8.21.0)(prisma@6.19.3(magicast@0.5.2)(typescript@5.9.3)))(ioredis@5.8.2)(jiti@2.6.1)(less@4.6.6)(lightningcss@1.30.2)(mysql2@3.22.5(@types/node@24.10.3))(rolldown@1.1.3)(sass@1.101.0)(terser@5.44.1)(tsx@4.21.0)(yaml@2.8.2):
     dependencies:
       '@babel/core': 7.29.0
       '@babel/plugin-syntax-jsx': 7.27.1(@babel/core@7.29.0)
@@ -31226,7 +32165,7 @@ snapshots:
       hookable: 5.5.3
       http-proxy: 1.18.1
       micromatch: 4.0.8
-      nitropack: 2.12.9(aws4fetch@1.0.20)(rolldown@1.1.3)
+      nitropack: 2.12.9(aws4fetch@1.0.20)(drizzle-orm@0.45.2(@cloudflare/workers-types@4.20260317.1)(@opentelemetry/api@1.9.1)(@prisma/client@6.19.3(prisma@6.19.3(magicast@0.5.2)(typescript@5.9.3))(typescript@5.9.3))(@types/pg@8.20.0)(mysql2@3.22.5(@types/node@24.10.3))(pg@8.21.0)(prisma@6.19.3(magicast@0.5.2)(typescript@5.9.3)))(mysql2@3.22.5(@types/node@24.10.3))(rolldown@1.1.3)
       node-fetch-native: 1.6.7
       path-to-regexp: 6.3.0
       pathe: 1.1.2
@@ -31237,7 +32176,7 @@ snapshots:
       ufo: 1.6.1
       unctx: 2.4.1
       unenv: 1.10.0
-      unstorage: 1.17.4(aws4fetch@1.0.20)(db0@0.3.4)(ioredis@5.8.2)
+      unstorage: 1.17.4(aws4fetch@1.0.20)(db0@0.3.4(drizzle-orm@0.45.2(@cloudflare/workers-types@4.20260317.1)(@opentelemetry/api@1.9.1)(@prisma/client@6.19.3(prisma@6.19.3(magicast@0.5.2)(typescript@5.9.3))(typescript@5.9.3))(@types/pg@8.20.0)(mysql2@3.22.5(@types/node@24.10.3))(pg@8.21.0)(prisma@6.19.3(magicast@0.5.2)(typescript@5.9.3)))(mysql2@3.22.5(@types/node@24.10.3)))(ioredis@5.8.2)
       vite: 6.4.2(@types/node@24.10.3)(jiti@2.6.1)(less@4.6.6)(lightningcss@1.30.2)(sass@1.101.0)(terser@5.44.1)(tsx@4.21.0)(yaml@2.8.2)
       zod: 3.25.76
     transitivePeerDependencies:
@@ -31394,7 +32333,7 @@ snapshots:
       esbuild: 0.27.7
       fdir: 6.5.0(picomatch@4.0.4)
       picomatch: 4.0.4
-      postcss: 8.5.9
+      postcss: 8.5.15
       rollup: 4.60.1
       tinyglobby: 0.2.16
     optionalDependencies:
@@ -31413,7 +32352,7 @@ snapshots:
       esbuild: 0.27.7
       fdir: 6.5.0(picomatch@4.0.4)
       picomatch: 4.0.4
-      postcss: 8.5.9
+      postcss: 8.5.15
       rollup: 4.60.1
       tinyglobby: 0.2.16
     optionalDependencies:
@@ -31792,6 +32731,9 @@ snapshots:
 
   xmlchars@2.2.0: {}
 
+  xtend@4.0.2:
+    optional: true
+
   y18n@5.0.8: {}
 
   yallist@3.1.1: {}
diff --git a/pnpm-workspace.yaml b/pnpm-workspace.yaml
index 093c13db0..f72e0e24a 100644
--- a/pnpm-workspace.yaml
+++ b/pnpm-workspace.yaml
@@ -61,3 +61,9 @@ allowBuilds:
   # JS fallback, so their native builds are not required.
   cpu-features: false
   ssh2: false
+  # @tanstack/ai-persistence-prisma needs the Prisma query engine downloaded
+  # (@prisma/engines postinstall) and the client generated (prisma generate,
+  # wired as the package's db:generate Nx target) for its conformance suite.
+  '@prisma/client': true
+  '@prisma/engines': true
+  prisma: true
diff --git a/testing/e2e/package.json b/testing/e2e/package.json
index b761eb58a..c064faa1b 100644
--- a/testing/e2e/package.json
+++ b/testing/e2e/package.json
@@ -31,6 +31,7 @@
     "@tanstack/ai-ollama": "workspace:*",
     "@tanstack/ai-openai": "workspace:*",
     "@tanstack/ai-openrouter": "workspace:*",
+    "@tanstack/ai-persistence": "workspace:*",
     "@tanstack/ai-react": "workspace:*",
     "@tanstack/ai-react-ui": "workspace:*",
     "@tanstack/devtools-event-bus": "^0.4.1",
diff --git a/testing/e2e/src/components/ChatUI.tsx b/testing/e2e/src/components/ChatUI.tsx
index 9bd218180..f626f0a20 100644
--- a/testing/e2e/src/components/ChatUI.tsx
+++ b/testing/e2e/src/components/ChatUI.tsx
@@ -16,6 +16,7 @@ interface ChatUIProps {
     id: string
     approved: boolean
   }) => Promise<void>
+  hasPendingInterrupt?: boolean
   showImageInput?: boolean
   onStop?: () => void
   /** When the streaming structured-output CUSTOM event lands, the page
@@ -33,6 +34,7 @@ export function ChatUI({
   onSendMessage,
   onSendMessageWithImage,
   addToolApprovalResponse,
+  hasPendingInterrupt = false,
   showImageInput,
   onStop,
   structuredObject,
@@ -49,6 +51,7 @@ export function ChatUI({
   }, [messages])
 
   const handleSubmit = () => {
+    if (hasPendingInterrupt) return
     if (!input.trim()) return
     onSendMessage(input.trim())
     setInput('')
@@ -229,12 +232,13 @@ export function ChatUI({
             }
           }}
           placeholder="Type a message..."
+          disabled={hasPendingInterrupt}
           className="flex-1 bg-gray-800 border border-gray-700 rounded px-3 py-2 text-sm focus:outline-none focus:border-orange-500/50"
         />
         <button
           data-testid="send-button"
           onClick={handleSubmit}
-          disabled={!input.trim() || isLoading}
+          disabled={!input.trim() || isLoading || hasPendingInterrupt}
           className="px-4 py-2 bg-orange-500 text-white rounded text-sm font-medium disabled:opacity-50"
         >
           Send
diff --git a/testing/e2e/src/lib/media-providers.ts b/testing/e2e/src/lib/media-providers.ts
index 90446f9e3..19e3095b4 100644
--- a/testing/e2e/src/lib/media-providers.ts
+++ b/testing/e2e/src/lib/media-providers.ts
@@ -61,7 +61,7 @@ export function createImageAdapter(
   testId?: string,
 ) {
   const headers = testHeaders(testId)
-  const factories: Record<string, () => any> = {
+  const factories: Partial<Record<Provider, () => any>> = {
     openai: () =>
       createOpenaiImage('gpt-image-1', DUMMY_KEY, {
         baseURL: openaiUrl(aimockPort),
@@ -88,7 +88,7 @@ export function createTTSAdapter(
   testId?: string,
 ) {
   const headers = testHeaders(testId)
-  const factories: Record<string, () => any> = {
+  const factories: Partial<Record<Provider, () => any>> = {
     openai: () =>
       createOpenaiSpeech('tts-1', DUMMY_KEY, {
         baseURL: openaiUrl(aimockPort),
@@ -118,7 +118,7 @@ export function createTranscriptionAdapter(
 ) {
   const headers = testHeaders(testId)
   const openaiTranscriptionModel = getOpenaiTranscriptionModel(options)
-  const factories: Record<string, () => any> = {
+  const factories: Partial<Record<Provider, () => any>> = {
     openai: () =>
       createOpenaiTranscription(openaiTranscriptionModel, DUMMY_KEY, {
         baseURL: openaiUrl(aimockPort),
@@ -152,16 +152,18 @@ export function createVideoAdapter(
   testId?: string,
 ) {
   const headers = testHeaders(testId)
-  const factories: Record<string, () => any> = {
+  const geminiConfig = {
+    allowUrlFetch: false,
+    httpOptions: { baseUrl: llmockBase(aimockPort), headers },
+  }
+  const factories: Partial<Record<Provider, () => any>> = {
     openai: () =>
       createOpenaiVideo('sora-2', DUMMY_KEY, {
         baseURL: openaiUrl(aimockPort),
         defaultHeaders: headers,
       }),
     gemini: () =>
-      createGeminiVideo('veo-3.1-generate-preview', DUMMY_KEY, {
-        httpOptions: { baseUrl: llmockBase(aimockPort), headers },
-      }),
+      createGeminiVideo('veo-3.1-generate-preview', DUMMY_KEY, geminiConfig),
   }
   const factory = factories[provider]
   if (!factory) throw new Error(`No video adapter for provider: ${provider}`)
@@ -188,7 +190,7 @@ export function createAudioAdapter(
       headers,
     })
   }
-  const factories: Record<string, () => any> = {
+  const factories: Partial<Record<Provider, () => any>> = {
     gemini: () =>
       createGeminiAudio('lyria-3-clip-preview', DUMMY_KEY, {
         httpOptions: { baseUrl: base, headers },
diff --git a/testing/e2e/src/routeTree.gen.ts b/testing/e2e/src/routeTree.gen.ts
index 14ffbf330..8abc6f917 100644
--- a/testing/e2e/src/routeTree.gen.ts
+++ b/testing/e2e/src/routeTree.gen.ts
@@ -45,6 +45,7 @@ import { Route as ApiMcpAppsChatRouteImport } from './routes/api.mcp-apps-chat'
 import { Route as ApiMcpAppsCallRouteImport } from './routes/api.mcp-apps-call'
 import { Route as ApiLazyToolsWireRouteImport } from './routes/api.lazy-tools-wire'
 import { Route as ApiImageRouteImport } from './routes/api.image'
+import { Route as ApiDurableDeliveryRouteImport } from './routes/api.durable-delivery'
 import { Route as ApiChatRouteImport } from './routes/api.chat'
 import { Route as ApiAudioRouteImport } from './routes/api.audio'
 import { Route as ApiArktypeToolWireRouteImport } from './routes/api.arktype-tool-wire'
@@ -242,6 +243,11 @@ const ApiImageRoute = ApiImageRouteImport.update({
   path: '/api/image',
   getParentRoute: () => rootRouteImport,
 } as any)
+const ApiDurableDeliveryRoute = ApiDurableDeliveryRouteImport.update({
+  id: '/api/durable-delivery',
+  path: '/api/durable-delivery',
+  getParentRoute: () => rootRouteImport,
+} as any)
 const ApiChatRoute = ApiChatRouteImport.update({
   id: '/api/chat',
   path: '/api/chat',
@@ -323,6 +329,7 @@ export interface FileRoutesByFullPath {
   '/api/arktype-tool-wire': typeof ApiArktypeToolWireRoute
   '/api/audio': typeof ApiAudioRouteWithChildren
   '/api/chat': typeof ApiChatRoute
+  '/api/durable-delivery': typeof ApiDurableDeliveryRoute
   '/api/image': typeof ApiImageRouteWithChildren
   '/api/lazy-tools-wire': typeof ApiLazyToolsWireRoute
   '/api/mcp-apps-call': typeof ApiMcpAppsCallRoute
@@ -373,6 +380,7 @@ export interface FileRoutesByTo {
   '/api/arktype-tool-wire': typeof ApiArktypeToolWireRoute
   '/api/audio': typeof ApiAudioRouteWithChildren
   '/api/chat': typeof ApiChatRoute
+  '/api/durable-delivery': typeof ApiDurableDeliveryRoute
   '/api/image': typeof ApiImageRouteWithChildren
   '/api/lazy-tools-wire': typeof ApiLazyToolsWireRoute
   '/api/mcp-apps-call': typeof ApiMcpAppsCallRoute
@@ -424,6 +432,7 @@ export interface FileRoutesById {
   '/api/arktype-tool-wire': typeof ApiArktypeToolWireRoute
   '/api/audio': typeof ApiAudioRouteWithChildren
   '/api/chat': typeof ApiChatRoute
+  '/api/durable-delivery': typeof ApiDurableDeliveryRoute
   '/api/image': typeof ApiImageRouteWithChildren
   '/api/lazy-tools-wire': typeof ApiLazyToolsWireRoute
   '/api/mcp-apps-call': typeof ApiMcpAppsCallRoute
@@ -476,6 +485,7 @@ export interface FileRouteTypes {
     | '/api/arktype-tool-wire'
     | '/api/audio'
     | '/api/chat'
+    | '/api/durable-delivery'
     | '/api/image'
     | '/api/lazy-tools-wire'
     | '/api/mcp-apps-call'
@@ -526,6 +536,7 @@ export interface FileRouteTypes {
     | '/api/arktype-tool-wire'
     | '/api/audio'
     | '/api/chat'
+    | '/api/durable-delivery'
     | '/api/image'
     | '/api/lazy-tools-wire'
     | '/api/mcp-apps-call'
@@ -576,6 +587,7 @@ export interface FileRouteTypes {
     | '/api/arktype-tool-wire'
     | '/api/audio'
     | '/api/chat'
+    | '/api/durable-delivery'
     | '/api/image'
     | '/api/lazy-tools-wire'
     | '/api/mcp-apps-call'
@@ -627,6 +639,7 @@ export interface RootRouteChildren {
   ApiArktypeToolWireRoute: typeof ApiArktypeToolWireRoute
   ApiAudioRoute: typeof ApiAudioRouteWithChildren
   ApiChatRoute: typeof ApiChatRoute
+  ApiDurableDeliveryRoute: typeof ApiDurableDeliveryRoute
   ApiImageRoute: typeof ApiImageRouteWithChildren
   ApiLazyToolsWireRoute: typeof ApiLazyToolsWireRoute
   ApiMcpAppsCallRoute: typeof ApiMcpAppsCallRoute
@@ -908,6 +921,13 @@ declare module '@tanstack/react-router' {
       preLoaderRoute: typeof ApiImageRouteImport
       parentRoute: typeof rootRouteImport
     }
+    '/api/durable-delivery': {
+      id: '/api/durable-delivery'
+      path: '/api/durable-delivery'
+      fullPath: '/api/durable-delivery'
+      preLoaderRoute: typeof ApiDurableDeliveryRouteImport
+      parentRoute: typeof rootRouteImport
+    }
     '/api/chat': {
       id: '/api/chat'
       path: '/api/chat'
@@ -1072,6 +1092,7 @@ const rootRouteChildren: RootRouteChildren = {
   ApiArktypeToolWireRoute: ApiArktypeToolWireRoute,
   ApiAudioRoute: ApiAudioRouteWithChildren,
   ApiChatRoute: ApiChatRoute,
+  ApiDurableDeliveryRoute: ApiDurableDeliveryRoute,
   ApiImageRoute: ApiImageRouteWithChildren,
   ApiLazyToolsWireRoute: ApiLazyToolsWireRoute,
   ApiMcpAppsCallRoute: ApiMcpAppsCallRoute,
diff --git a/testing/e2e/src/routes/$provider/$feature.tsx b/testing/e2e/src/routes/$provider/$feature.tsx
index ed1dfa9ea..cc7698391 100644
--- a/testing/e2e/src/routes/$provider/$feature.tsx
+++ b/testing/e2e/src/routes/$provider/$feature.tsx
@@ -1,9 +1,14 @@
-import { useState } from 'react'
+import { useEffect, useState } from 'react'
 import { createFileRoute } from '@tanstack/react-router'
 import { uiMessagesToWire } from '@tanstack/ai'
 import { fetchServerSentEvents, useChat } from '@tanstack/ai-react'
 import { clientTools } from '@tanstack/ai-client'
-import type { ChatClientPersistence, UIMessage } from '@tanstack/ai-client'
+import type {
+  ChatClientPersistence,
+  ChatPendingInterrupt,
+  ChatResumeSnapshot,
+  UIMessage,
+} from '@tanstack/ai-client'
 import type { GeminiInteractionsCustomEventValue } from '@tanstack/ai-gemini/experimental'
 import type { Feature, Mode, Provider } from '@/lib/types'
 import { ALL_FEATURES, ALL_PROVIDERS } from '@/lib/types'
@@ -23,9 +28,11 @@ export const Route = createFileRoute('/$provider/$feature')({
   component: FeaturePage,
   validateSearch: (search: Record<string, unknown>) => {
     const port =
-      typeof search.aimockPort === 'string'
-        ? parseInt(search.aimockPort, 10)
-        : undefined
+      typeof search.aimockPort === 'number'
+        ? search.aimockPort
+        : typeof search.aimockPort === 'string'
+          ? parseInt(search.aimockPort, 10)
+          : undefined
     const rawMode = typeof search.mode === 'string' ? search.mode : undefined
     return {
       testId: typeof search.testId === 'string' ? search.testId : undefined,
@@ -36,6 +43,10 @@ export const Route = createFileRoute('/$provider/$feature')({
           : undefined,
       persistence:
         search.persistence === 'localStorage' ? 'localStorage' : undefined,
+      serverPersistence:
+        search.serverPersistence === true ||
+        search.serverPersistence === 1 ||
+        search.serverPersistence === '1',
     }
   },
 })
@@ -84,6 +95,61 @@ const isProvider = (s: string): s is Provider =>
   (ALL_PROVIDERS as ReadonlyArray<string>).includes(s)
 const isFeature = (s: string): s is Feature =>
   (ALL_FEATURES as ReadonlyArray<string>).includes(s)
+const isRecord = (value: unknown): value is Record<string, unknown> =>
+  value !== null && typeof value === 'object' && !Array.isArray(value)
+
+function parsePendingInterrupts(value: unknown): Array<ChatPendingInterrupt> {
+  if (!Array.isArray(value)) return []
+
+  const interrupts: Array<ChatPendingInterrupt> = []
+  for (const item of value) {
+    if (!item || typeof item !== 'object') continue
+    const interrupt = item as Record<string, unknown>
+    if (
+      typeof interrupt.id !== 'string' ||
+      typeof interrupt.reason !== 'string'
+    ) {
+      continue
+    }
+    interrupts.push({
+      id: interrupt.id,
+      reason: interrupt.reason,
+      ...(typeof interrupt.toolCallId === 'string'
+        ? { toolCallId: interrupt.toolCallId }
+        : {}),
+      ...(isRecord(interrupt.metadata) ? { metadata: interrupt.metadata } : {}),
+    })
+  }
+  return interrupts
+}
+
+function parseStoredResumeSnapshot(
+  raw: string | null,
+): ChatResumeSnapshot | null {
+  if (!raw) return null
+  const parsed = JSON.parse(raw) as unknown
+  if (!parsed || typeof parsed !== 'object') return null
+  const value = parsed as Record<string, unknown>
+  const resumeState =
+    value.resumeState && typeof value.resumeState === 'object'
+      ? (value.resumeState as Record<string, unknown>)
+      : value
+
+  if (
+    typeof resumeState.threadId !== 'string' ||
+    typeof resumeState.runId !== 'string'
+  ) {
+    return null
+  }
+
+  return {
+    resumeState: {
+      threadId: resumeState.threadId,
+      runId: resumeState.runId,
+    },
+    pendingInterrupts: parsePendingInterrupts(value.pendingInterrupts),
+  }
+}
 
 function FeaturePage() {
   const { provider, feature } = Route.useParams()
@@ -215,8 +281,10 @@ function ChatFeature({
 
   const tools = needsApproval ? clientTools(addToCartClient) : undefined
 
-  const { testId, aimockPort, persistence } = Route.useSearch()
+  const { testId, aimockPort, persistence, serverPersistence } =
+    Route.useSearch()
   const persistenceEnabled = persistence === 'localStorage'
+  const serverPersistenceEnabled = serverPersistence === true
   const baseChatId = `e2e-chat-${testId ?? `${provider}-${feature}`}`
   // When persistence is on, expose a tiny thread switcher so e2e can verify that
   // changing the `id` in place swaps to that id's own persisted history (the
@@ -227,6 +295,19 @@ function ChatFeature({
     persistenceEnabled ? 'a' : null,
   )
   const chatId = activeThread ? `${baseChatId}:${activeThread}` : baseChatId
+  const resumeStorageKey = `${chatId}:resume-state`
+  const [initialResumeSnapshot] = useState<ChatResumeSnapshot | null>(() => {
+    if (!serverPersistenceEnabled) return null
+    if (typeof window === 'undefined') return null
+    try {
+      return parseStoredResumeSnapshot(
+        window.localStorage.getItem(resumeStorageKey),
+      )
+    } catch {
+      window.localStorage.removeItem(resumeStorageKey)
+      return null
+    }
+  })
 
   const [structuredObject, setStructuredObject] = useState<unknown>(null)
   const [contentDeltaCount, setContentDeltaCount] = useState(0)
@@ -243,6 +324,7 @@ function ChatFeature({
               data?: unknown
               threadId: string
               runId: string
+              resume?: Array<unknown>
             },
             options: { signal: AbortSignal },
           ) =>
@@ -269,6 +351,7 @@ function ChatFeature({
                 tools: [],
                 context: [],
                 forwardedProps: input.data,
+                ...(input.resume ? { resume: input.resume } : {}),
               }),
               signal: options.signal,
             }),
@@ -280,6 +363,8 @@ function ChatFeature({
     sendMessage,
     isLoading,
     addToolApprovalResponse,
+    resumeState,
+    pendingInterrupts,
     stop,
     clear,
   } = useChat({
@@ -292,9 +377,13 @@ function ChatFeature({
       testId,
       aimockPort,
       previousInteractionId: interactionId,
+      serverPersistence: serverPersistenceEnabled,
     },
     persistence:
-      persistence === 'localStorage' ? localStoragePersistence : undefined,
+      persistence === 'localStorage' || serverPersistenceEnabled
+        ? localStoragePersistence
+        : undefined,
+    ...(initialResumeSnapshot ? { initialResumeSnapshot } : {}),
     onCustomEvent: (eventType, data) => {
       if (eventType === 'structured-output.complete') {
         const value = data as { object: unknown; raw: string } | undefined
@@ -313,8 +402,43 @@ function ChatFeature({
     },
   })
 
+  // Delivery-durability resume is transparent now (the resumable SSE
+  // connection adapter reattaches via the browser's native Last-Event-ID),
+  // so there is no client `resume()` call. We still persist the interrupt
+  // (state) resume snapshot so a full reload can restore pending interrupts.
+  useEffect(() => {
+    if (!serverPersistenceEnabled) return
+    if (resumeState) {
+      const snapshot: ChatResumeSnapshot = {
+        resumeState,
+        pendingInterrupts,
+      }
+      window.localStorage.setItem(resumeStorageKey, JSON.stringify(snapshot))
+    } else {
+      window.localStorage.removeItem(resumeStorageKey)
+    }
+  }, [
+    pendingInterrupts,
+    resumeState,
+    resumeStorageKey,
+    serverPersistenceEnabled,
+  ])
+
   return (
     <>
+      {resumeState && (
+        <div
+          data-testid="resume-state"
+          data-thread-id={resumeState.threadId}
+          data-run-id={resumeState.runId}
+          hidden
+        />
+      )}
+      <div
+        data-testid="pending-interrupt-count"
+        data-count={String(pendingInterrupts.length)}
+        hidden
+      />
       {interactionId && (
         <div data-testid="gemini-interaction-id" hidden>
           {interactionId}
@@ -376,6 +500,7 @@ function ChatFeature({
         addToolApprovalResponse={
           needsApproval ? addToolApprovalResponse : undefined
         }
+        hasPendingInterrupt={pendingInterrupts.length > 0}
         showImageInput={showImageInput}
         onStop={stop}
       />
diff --git a/testing/e2e/src/routes/$provider/index.tsx b/testing/e2e/src/routes/$provider/index.tsx
index 94e72acba..a4df2b8cc 100644
--- a/testing/e2e/src/routes/$provider/index.tsx
+++ b/testing/e2e/src/routes/$provider/index.tsx
@@ -29,6 +29,7 @@ function ProviderPage() {
               aimockPort: undefined,
               mode: undefined,
               persistence: undefined,
+              serverPersistence: false,
             }}
             className="p-3 bg-gray-800/50 border border-gray-700 rounded-lg hover:border-orange-500/40 transition-colors text-center text-sm"
           >
diff --git a/testing/e2e/src/routes/api.chat.ts b/testing/e2e/src/routes/api.chat.ts
index f3a5a4fe1..251bcac3c 100644
--- a/testing/e2e/src/routes/api.chat.ts
+++ b/testing/e2e/src/routes/api.chat.ts
@@ -6,12 +6,28 @@ import {
   toServerSentEventsResponse,
 } from '@tanstack/ai'
 import type { StreamChunk } from '@tanstack/ai'
+import {
+  memoryPersistence,
+  withChatPersistence,
+  type AIPersistence,
+} from '@tanstack/ai-persistence'
 import type { Feature, Provider } from '@/lib/types'
 import { createTextAdapter } from '@/lib/providers'
 import { featureConfigs } from '@/lib/features'
 import { guitarRecommendationSchema, recipeSchema } from '@/lib/schemas'
 
 const DEFAULT_SYSTEM_PROMPT = 'You are a helpful assistant for a guitar store.'
+const persistenceByTestId = new Map<string, AIPersistence>()
+
+function getPersistence(testId: string | undefined): AIPersistence {
+  const key = testId ?? '__default__'
+  let persistence = persistenceByTestId.get(key)
+  if (!persistence) {
+    persistence = memoryPersistence()
+    persistenceByTestId.set(key, persistence)
+  }
+  return persistence
+}
 
 export const Route = createFileRoute('/api/chat')({
   server: {
@@ -48,6 +64,7 @@ export const Route = createFileRoute('/api/chat')({
           typeof fp.previousInteractionId === 'string'
             ? fp.previousInteractionId
             : undefined
+        const serverPersistence = fp.serverPersistence === true
 
         const config = featureConfigs[feature]
         const modelOverride = config.modelOverrides?.[provider]
@@ -68,6 +85,13 @@ export const Route = createFileRoute('/api/chat')({
 
         try {
           const systemPrompt = config.systemPrompt ?? DEFAULT_SYSTEM_PROMPT
+          const middleware = serverPersistence
+            ? [
+                withChatPersistence(getPersistence(testId), {
+                  features: ['messages', 'interrupts'],
+                }),
+              ]
+            : undefined
 
           // Test-only flag — when truthy, the route promotes the system
           // prompt to object-form and attaches Anthropic `cache_control`
@@ -119,6 +143,8 @@ export const Route = createFileRoute('/api/chat')({
                   messages: params.messages,
                   threadId: params.threadId,
                   runId: params.runId,
+                  ...(params.resume && { resume: params.resume }),
+                  ...(middleware && { middleware }),
                   outputSchema: guitarRecommendationSchema,
                   stream: true,
                   abortController,
@@ -131,6 +157,8 @@ export const Route = createFileRoute('/api/chat')({
                     messages: params.messages,
                     threadId: params.threadId,
                     runId: params.runId,
+                    ...(params.resume && { resume: params.resume }),
+                    ...(middleware && { middleware }),
                     outputSchema: recipeSchema,
                     stream: true,
                     abortController,
@@ -145,6 +173,8 @@ export const Route = createFileRoute('/api/chat')({
                       messages: params.messages,
                       threadId: params.threadId,
                       runId: params.runId,
+                      ...(params.resume && { resume: params.resume }),
+                      ...(middleware && { middleware }),
                       outputSchema: guitarRecommendationSchema,
                       stream: true,
                       abortController,
@@ -158,6 +188,8 @@ export const Route = createFileRoute('/api/chat')({
                       messages: params.messages,
                       threadId: params.threadId,
                       runId: params.runId,
+                      ...(params.resume && { resume: params.resume }),
+                      ...(middleware && { middleware }),
                       ...(rootObservabilityMetadata && {
                         metadata: rootObservabilityMetadata,
                       }),
diff --git a/testing/e2e/src/routes/api.durable-delivery.ts b/testing/e2e/src/routes/api.durable-delivery.ts
new file mode 100644
index 000000000..f6412b28e
--- /dev/null
+++ b/testing/e2e/src/routes/api.durable-delivery.ts
@@ -0,0 +1,65 @@
+import { createFileRoute } from '@tanstack/react-router'
+import { memoryStream, toServerSentEventsResponse } from '@tanstack/ai'
+import type { StreamChunk } from '@tanstack/ai'
+
+/**
+ * A provider-free delivery-durability harness route. It streams a FIXED
+ * sequence of AG-UI events through the transport helper's `durability` sink
+ * (`memoryStream`), so the delivery e2e can assert disconnect→reconnect→ordered
+ * resume and second-tab join deterministically, with no LLM in the loop.
+ *
+ * - `POST` with no offset → fresh run: produce + append the fixed sequence,
+ *   tagging each SSE event with an `id: runId@seq` offset.
+ * - `POST` with `Last-Event-ID` → reconnect: replay strictly after the offset
+ *   from the log (the fixed sequence is never re-produced).
+ * - `GET  ?offset=-1&runId=…` → second-tab join: replay from the start.
+ */
+function fixedRun(threadId: string, runId: string): AsyncIterable<StreamChunk> {
+  return (async function* () {
+    yield {
+      type: 'RUN_STARTED',
+      threadId,
+      runId,
+      timestamp: Date.now(),
+    } as StreamChunk
+    for (let i = 1; i <= 5; i++) {
+      yield {
+        type: 'TEXT_MESSAGE_CONTENT',
+        messageId: 'm',
+        model: 'fixed',
+        delta: String(i),
+        content: String(i),
+        timestamp: Date.now(),
+      } as StreamChunk
+    }
+    yield {
+      type: 'RUN_FINISHED',
+      threadId,
+      runId,
+      model: 'fixed',
+      finishReason: 'stop',
+      timestamp: Date.now(),
+    } as StreamChunk
+  })()
+}
+
+export const Route = createFileRoute('/api/durable-delivery')({
+  server: {
+    handlers: {
+      POST: async ({ request }) => {
+        const durability = memoryStream(request)
+        const runId = durability.runId()
+        return toServerSentEventsResponse(fixedRun('thread-durable', runId), {
+          durability: { adapter: durability, batch: 2 },
+        })
+      },
+      GET: async ({ request }) => {
+        const durability = memoryStream(request)
+        const runId = durability.runId()
+        return toServerSentEventsResponse(fixedRun('thread-durable', runId), {
+          durability: { adapter: durability },
+        })
+      },
+    },
+  },
+})
diff --git a/testing/e2e/src/routes/api.image.stream.ts b/testing/e2e/src/routes/api.image.stream.ts
index bd65b9756..9c4b1f6c1 100644
--- a/testing/e2e/src/routes/api.image.stream.ts
+++ b/testing/e2e/src/routes/api.image.stream.ts
@@ -1,8 +1,8 @@
 import { createFileRoute } from '@tanstack/react-router'
-import { generateImage, toHttpResponse } from '@tanstack/ai'
-import { createImageAdapter } from '@/lib/media-providers'
+import { createImageOptions, generateImage, toHttpResponse } from '@tanstack/ai'
 import type { MediaPrompt } from '@tanstack/ai'
 import type { Provider } from '@/lib/types'
+import { createImageAdapter } from '@/lib/media-providers'
 
 export const Route = createFileRoute('/api/image/stream')({
   server: {
@@ -24,15 +24,19 @@ export const Route = createFileRoute('/api/image/stream')({
         const adapter = createImageAdapter(provider, aimockPort, testId)
 
         try {
-          const stream = generateImage({
-            adapter,
-            prompt,
-            numberOfImages: numberOfImages ?? 1,
-            stream: true,
-          })
+          const stream = generateImage<typeof adapter, true>(
+            createImageOptions({
+              adapter,
+              prompt,
+              numberOfImages: numberOfImages ?? 1,
+              stream: true,
+            }),
+          )
           return toHttpResponse(stream, { abortController })
-        } catch (error: any) {
-          return new Response(JSON.stringify({ error: error.message }), {
+        } catch (error) {
+          const message =
+            error instanceof Error ? error.message : 'Image generation failed'
+          return new Response(JSON.stringify({ error: message }), {
             status: 500,
             headers: { 'Content-Type': 'application/json' },
           })
diff --git a/testing/e2e/src/routes/api.image.ts b/testing/e2e/src/routes/api.image.ts
index d8b455a63..98a4406ff 100644
--- a/testing/e2e/src/routes/api.image.ts
+++ b/testing/e2e/src/routes/api.image.ts
@@ -1,8 +1,12 @@
 import { createFileRoute } from '@tanstack/react-router'
-import { generateImage, toServerSentEventsResponse } from '@tanstack/ai'
-import { createImageAdapter } from '@/lib/media-providers'
+import {
+  createImageOptions,
+  generateImage,
+  toServerSentEventsResponse,
+} from '@tanstack/ai'
 import type { MediaPrompt } from '@tanstack/ai'
 import type { Provider } from '@/lib/types'
+import { createImageAdapter } from '@/lib/media-providers'
 
 export const Route = createFileRoute('/api/image')({
   server: {
@@ -24,15 +28,19 @@ export const Route = createFileRoute('/api/image')({
         const adapter = createImageAdapter(provider, aimockPort, testId)
 
         try {
-          const stream = generateImage({
-            adapter,
-            prompt,
-            numberOfImages: numberOfImages ?? 1,
-            stream: true,
-          })
+          const stream = generateImage<typeof adapter, true>(
+            createImageOptions({
+              adapter,
+              prompt,
+              numberOfImages: numberOfImages ?? 1,
+              stream: true,
+            }),
+          )
           return toServerSentEventsResponse(stream, { abortController })
-        } catch (error: any) {
-          return new Response(JSON.stringify({ error: error.message }), {
+        } catch (error) {
+          const message =
+            error instanceof Error ? error.message : 'Image generation failed'
+          return new Response(JSON.stringify({ error: message }), {
             status: 500,
             headers: { 'Content-Type': 'application/json' },
           })
diff --git a/testing/e2e/src/routes/api.video.stream.ts b/testing/e2e/src/routes/api.video.stream.ts
index 88eb1a189..aa64c840e 100644
--- a/testing/e2e/src/routes/api.video.stream.ts
+++ b/testing/e2e/src/routes/api.video.stream.ts
@@ -1,8 +1,8 @@
 import { createFileRoute } from '@tanstack/react-router'
-import { generateVideo, toHttpResponse } from '@tanstack/ai'
-import { createVideoAdapter } from '@/lib/media-providers'
+import { createVideoOptions, generateVideo, toHttpResponse } from '@tanstack/ai'
 import type { MediaPrompt } from '@tanstack/ai'
 import type { Provider } from '@/lib/types'
+import { createVideoAdapter } from '@/lib/media-providers'
 
 export const Route = createFileRoute('/api/video/stream')({
   server: {
@@ -22,15 +22,19 @@ export const Route = createFileRoute('/api/video/stream')({
         const adapter = createVideoAdapter(provider, aimockPort, testId)
 
         try {
-          const stream = generateVideo({
-            adapter,
-            prompt,
-            stream: true,
-            pollingInterval: 500,
-          })
+          const stream = generateVideo<typeof adapter, true>(
+            createVideoOptions({
+              adapter,
+              prompt,
+              stream: true,
+              pollingInterval: 500,
+            }),
+          )
           return toHttpResponse(stream, { abortController })
-        } catch (error: any) {
-          return new Response(JSON.stringify({ error: error.message }), {
+        } catch (error) {
+          const message =
+            error instanceof Error ? error.message : 'Video generation failed'
+          return new Response(JSON.stringify({ error: message }), {
             status: 500,
             headers: { 'Content-Type': 'application/json' },
           })
diff --git a/testing/e2e/src/routes/api.video.ts b/testing/e2e/src/routes/api.video.ts
index a9b0903ec..6ba08b420 100644
--- a/testing/e2e/src/routes/api.video.ts
+++ b/testing/e2e/src/routes/api.video.ts
@@ -1,8 +1,12 @@
 import { createFileRoute } from '@tanstack/react-router'
-import { generateVideo, toServerSentEventsResponse } from '@tanstack/ai'
-import { createVideoAdapter } from '@/lib/media-providers'
+import {
+  createVideoOptions,
+  generateVideo,
+  toServerSentEventsResponse,
+} from '@tanstack/ai'
 import type { MediaPrompt } from '@tanstack/ai'
 import type { Provider } from '@/lib/types'
+import { createVideoAdapter } from '@/lib/media-providers'
 
 export const Route = createFileRoute('/api/video')({
   server: {
@@ -22,15 +26,19 @@ export const Route = createFileRoute('/api/video')({
         const adapter = createVideoAdapter(provider, aimockPort, testId)
 
         try {
-          const stream = generateVideo({
-            adapter,
-            prompt,
-            stream: true,
-            pollingInterval: 500,
-          })
+          const stream = generateVideo<typeof adapter, true>(
+            createVideoOptions({
+              adapter,
+              prompt,
+              stream: true,
+              pollingInterval: 500,
+            }),
+          )
           return toServerSentEventsResponse(stream, { abortController })
-        } catch (error: any) {
-          return new Response(JSON.stringify({ error: error.message }), {
+        } catch (error) {
+          const message =
+            error instanceof Error ? error.message : 'Video generation failed'
+          return new Response(JSON.stringify({ error: message }), {
             status: 500,
             headers: { 'Content-Type': 'application/json' },
           })
diff --git a/testing/e2e/tests/delivery-durability.spec.ts b/testing/e2e/tests/delivery-durability.spec.ts
new file mode 100644
index 000000000..42d56f467
--- /dev/null
+++ b/testing/e2e/tests/delivery-durability.spec.ts
@@ -0,0 +1,107 @@
+import { expect, test } from '@playwright/test'
+
+/**
+ * Delivery durability (transport layer) over real HTTP.
+ *
+ * These exercise the server-side `durability` sink end-to-end: a fresh run is
+ * appended to the log and each SSE event is tagged with an `id: runId@seq`
+ * offset; a reconnect (native `Last-Event-ID`) or a `?offset` join replays from
+ * the log without re-producing.
+ *
+ * We test only the **producer-alive** path deterministically (the log is fully
+ * written by the first request). The **producer-dead** case — where the client
+ * disconnects mid-run and the producer process is torn down with it — cannot be
+ * resumed by the log alone; it needs the producer to outlive the socket
+ * (`waitUntil` / durable object / queue), which is a per-platform deployment
+ * concern, not something this transport can guarantee. The client-side
+ * auto-reconnect (Last-Event-ID resend + de-dupe) is covered by unit tests in
+ * `@tanstack/ai-client`.
+ */
+
+interface SseEvent {
+  id?: string
+  data: unknown
+}
+
+function parseSse(body: string): Array<SseEvent> {
+  return body
+    .split('\n\n')
+    .filter((block) => block.trim().length > 0)
+    .map((block) => {
+      const lines = block.split('\n')
+      const idLine = lines.find((l) => l.startsWith('id:'))
+      const dataLine = lines.find((l) => l.startsWith('data:'))
+      const rawData = dataLine
+        ? dataLine.slice(dataLine.indexOf(':') + 1).trim()
+        : ''
+      return {
+        ...(idLine ? { id: idLine.slice(idLine.indexOf(':') + 1).trim() } : {}),
+        data: JSON.parse(rawData),
+      }
+    })
+}
+
+function eventType(e: SseEvent): string {
+  return (e.data as { type: string }).type
+}
+
+function contentDeltas(events: Array<SseEvent>): Array<string> {
+  return events
+    .filter((e) => eventType(e) === 'TEXT_MESSAGE_CONTENT')
+    .map((e) => (e.data as { delta: string }).delta)
+}
+
+test.describe('delivery durability', () => {
+  test('disconnect → reconnect resumes the ordered stream exactly once', async ({
+    request,
+  }) => {
+    // Fresh run: produce + persist the full ordered sequence.
+    const produce = await request.post('/api/durable-delivery', { data: {} })
+    expect(produce.ok()).toBeTruthy()
+    const produced = parseSse(await produce.text())
+
+    // Sequence: RUN_STARTED(1), content 1..5 (seq 2..6), RUN_FINISHED(7).
+    expect(contentDeltas(produced)).toEqual(['1', '2', '3', '4', '5'])
+    expect(produced.every((e) => e.id !== undefined)).toBeTruthy()
+
+    // Client received through seq 3 (RUN_STARTED, content "1", content "2")
+    // then dropped. Reconnect from that offset via native Last-Event-ID.
+    const resumeFrom = produced[2]!.id!
+    const reconnect = await request.post('/api/durable-delivery', {
+      headers: { 'Last-Event-ID': resumeFrom },
+      data: {},
+    })
+    expect(reconnect.ok()).toBeTruthy()
+    const resumed = parseSse(await reconnect.text())
+
+    // Exactly the tail, in order, exactly once — content "3","4","5" then RUN_FINISHED.
+    expect(contentDeltas(resumed)).toEqual(['3', '4', '5'])
+    expect(eventType(resumed[resumed.length - 1]!)).toBe('RUN_FINISHED')
+    // Every resumed offset is strictly after the resume point (no replay overlap).
+    const resumeSeq = Number(resumeFrom.slice(resumeFrom.lastIndexOf('@') + 1))
+    for (const e of resumed) {
+      const seq = Number(e.id!.slice(e.id!.lastIndexOf('@') + 1))
+      expect(seq).toBeGreaterThan(resumeSeq)
+    }
+  })
+
+  test('a second tab joins an existing run from the start', async ({
+    request,
+  }) => {
+    const produce = await request.post('/api/durable-delivery', { data: {} })
+    const produced = parseSse(await produce.text())
+    const firstId = produced[0]!.id!
+    const runId = firstId.slice(0, firstId.lastIndexOf('@'))
+
+    // Join from the start with ?offset=-1 (a fresh tab attaching to the run).
+    const join = await request.get(
+      `/api/durable-delivery?offset=-1&runId=${encodeURIComponent(runId)}`,
+    )
+    expect(join.ok()).toBeTruthy()
+    const joined = parseSse(await join.text())
+
+    expect(contentDeltas(joined)).toEqual(['1', '2', '3', '4', '5'])
+    expect(eventType(joined[0]!)).toBe('RUN_STARTED')
+    expect(eventType(joined[joined.length - 1]!)).toBe('RUN_FINISHED')
+  })
+})
diff --git a/testing/e2e/tests/tool-approval.spec.ts b/testing/e2e/tests/tool-approval.spec.ts
index 4af029661..ea10209fd 100644
--- a/testing/e2e/tests/tool-approval.spec.ts
+++ b/testing/e2e/tests/tool-approval.spec.ts
@@ -29,6 +29,40 @@ for (const provider of providersFor('tool-approval')) {
       await waitForAssistantText(page, 'added')
     })
 
+    test('approval interrupt remains visible after reload and resumes on approve', async ({
+      page,
+      testId,
+      aimockPort,
+    }) => {
+      await page.goto(
+        `${featureUrl(provider, 'tool-approval', testId, aimockPort)}&serverPersistence=1`,
+      )
+
+      await sendMessage(page, '[approval] add the stratocaster to my cart')
+
+      await expect(page.getByTestId('approval-prompt-addToCart')).toBeVisible({
+        timeout: 20_000,
+      })
+      await expect(page.getByTestId('pending-interrupt-count')).toHaveAttribute(
+        'data-count',
+        '1',
+      )
+
+      await expect(page.getByTestId('send-button')).toBeDisabled()
+
+      await page.reload()
+
+      await expect(page.getByTestId('approval-prompt-addToCart')).toBeVisible({
+        timeout: 20_000,
+      })
+      await expect(page.getByTestId('pending-interrupt-count')).toHaveAttribute(
+        'data-count',
+        '1',
+      )
+      await approveToolCall(page, 'addToCart')
+      await waitForAssistantText(page, 'added')
+    })
+
     test('follow-up message after approval does not produce empty tool_use.name (issue #532)', async ({
       page,
       testId,