diff --git a/.changeset/persistence-orm-locks-naming-collation.md b/.changeset/persistence-orm-locks-naming-collation.md
new file mode 100644
index 000000000..b8d9f16da
--- /dev/null
+++ b/.changeset/persistence-orm-locks-naming-collation.md
@@ -0,0 +1,20 @@
+---
+'@tanstack/ai-persistence-drizzle': patch
+'@tanstack/ai-persistence-prisma': patch
+'@tanstack/ai-persistence-cloudflare': patch
+---
+
+Persistence ORM backends: safer locks and clearer SQLite naming.
+
+- `drizzlePersistence` and `prismaPersistence` no longer return a `locks` store.
+  Bundling an `InMemoryLockStore` silently handed multi-instance deployments a
+  lock that does not lock across instances. Consumers that need a lock (e.g.
+  `withSandbox`) transparently fall back to an in-process lock; use a
+  distributed backend such as the Cloudflare Durable Object lock for
+  cross-instance locking.
+- `@tanstack/ai-persistence-drizzle` renames `TanstackAiSchema` →
+  `TanstackAiSqliteSchema` and `DrizzleDb` → `DrizzleSqliteDb` to make the
+  SQLite-only surface explicit. The old names remain as `@deprecated` aliases.
+- `metadata.set` with a nullish value now throws a clear error on both SQL
+  backends (a NOT NULL JSON column cannot store `undefined`/`null`) instead of a
+  cryptic driver failure — use `delete` to clear a value.
diff --git a/.changeset/persistence-v2.md b/.changeset/persistence-v2.md
new file mode 100644
index 000000000..8c12f8161
--- /dev/null
+++ b/.changeset/persistence-v2.md
@@ -0,0 +1,79 @@
+---
+'@tanstack/ai': minor
+'@tanstack/ai-client': minor
+'@tanstack/ai-persistence': patch
+'@tanstack/ai-persistence-cloudflare': patch
+'@tanstack/ai-persistence-drizzle': patch
+'@tanstack/ai-persistence-prisma': patch
+'@tanstack/ai-sandbox': minor
+'@tanstack/ai-event-client': patch
+'@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: durable state via middleware and a pluggable store contract.
+
+State durability lives on the middleware layer as `withChatPersistence` /
+`withGenerationPersistence`, backed by a store contract (messages, runs,
+interrupts, metadata, locks). The `@tanstack/ai-persistence` package 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 ORM state backends, while `@tanstack/ai-persistence-cloudflare`
+provides first-class D1 and Durable Object backed stores.
+
+Durable media artifact/blob storage (artifact metadata plus blob bytes, and
+the sandbox workspace-file checkpoints built on it) is split out to a
+follow-up release; persisted generation results reference provider media URLs,
+which may expire.
+
+Replaying a disconnected/reloaded stream (resumable streams) is a separate
+transport-level feature and ships independently — the persistence middleware
+owns zero delivery-event storage.
+
+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, and the client
+(`@tanstack/ai-client`) plus every framework binding (`@tanstack/ai-react`,
+`-solid`, `-vue`, `-svelte`, `-angular`, `-preact`) switch to interrupt-only
+resume.
+
+The delivery-store / SQL-driver packages that only existed to back the removed
+event log — `@tanstack/ai-persistence-sql`,
+`@tanstack/ai-persistence-sqlite`, and `@tanstack/ai-persistence-postgres` — are
+removed. They were never published (part of this same unreleased persistence
+work), so no npm tombstone release is needed.
+
+Generation events no longer expose transport cursors; they retain their thread
+and run identifiers for correlation.
+
+**Breaking (`@tanstack/ai-client` and every framework binding):** the
+`persistence` option changed shape. It was a single flat message-storage adapter
+and is now a `{ client?, server? }` object — `client` stores the rendered
+`UIMessage[]` (keyed by the chat `id`) and `server` stores the resume snapshot
+`{ resumeState, pendingInterrupts }` (keyed by `threadId`). This is a hard
+rename with no bridging union, so a flat adapter no longer type-checks. Migrate
+by moving your existing message adapter under `client`:
+
+```ts
+// Before
+useChat({
+  connection,
+  persistence: localStoragePersistence(),
+})
+
+// After
+useChat({
+  connection,
+  persistence: {
+    client: localStoragePersistence(), // messages (chat id)
+    // server: localStoragePersistence(), // optional: resume snapshot (threadId)
+  },
+})
+```
diff --git a/docs/api/ai-angular.md b/docs/api/ai-angular.md
index 291ad2cc5..00bf98619 100644
--- a/docs/api/ai-angular.md
+++ b/docs/api/ai-angular.md
@@ -90,7 +90,13 @@ import type {
   DeepPartial,
 } from "@tanstack/ai-angular";
 import type { ModelMessage, InferSchemaType } from "@tanstack/ai/client";
-import type { ChatClientState, ConnectionStatus } from "@tanstack/ai-client";
+import type {
+  ChatClientState,
+  ConnectionStatus,
+  ChatResumeState,
+  ChatPendingInterrupt,
+  RunAgentResumeItem,
+} from "@tanstack/ai-client";
 type TSchema = any;
 
 interface InjectChatResult {
@@ -118,6 +124,15 @@ interface InjectChatResult {
   isSubscribed: Signal<boolean>;
   connectionStatus: Signal<ConnectionStatus>;
   sessionGenerating: Signal<boolean>;
+  // Correlation ids `{ threadId, runId }` for the interrupted run, or null.
+  resumeState: Signal<ChatResumeState | null>;
+  // Interrupts currently awaiting a resume response.
+  pendingInterrupts: Signal<ChatPendingInterrupt[]>;
+  // Resolve pending interrupts by sending AG-UI resume entries.
+  resumeInterrupts: (
+    resume: RunAgentResumeItem[],
+    state?: ChatResumeState,
+  ) => Promise<boolean>;
   // Only present when outputSchema is supplied:
   partial: Signal<DeepPartial<InferSchemaType<TSchema>>>;
   final: Signal<InferSchemaType<TSchema> | null>;
@@ -380,9 +395,12 @@ export class CustomGenerationComponent {
 }
 ```
 
-**Options:** `connection?`, `fetcher?`, `id?`, `body?` (reactive), `devtools?`, `onResult?`, `onError?`, `onProgress?`, `onChunk?`
+**Options:** `connection?`, `fetcher?`, `id?`, `body?` (reactive), `persistence?`, `initialResumeSnapshot?`, `devtools?`, `onResult?`, `onError?`, `onProgress?`, `onChunk?`
+
+**Returns:** `generate`, `result`, `isLoading`, `error`, `status`, `stop`, `reset`, `resumeSnapshot`, `resumeState` (reactive), `pendingArtifacts`, `resultArtifacts` — all reactive state is a read-only `Signal<T>`.
 
-**Returns:** `generate`, `result`, `isLoading`, `error`, `status`, `stop`, `reset` — 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 01eb1587b..f2e5c7bd0 100644
--- a/docs/api/ai-react.md
+++ b/docs/api/ai-react.md
@@ -85,7 +85,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
@@ -101,6 +101,11 @@ Extends `ChatClientOptions` from `@tanstack/ai-client`:
 ```typescript
 import type { UIMessage } from "@tanstack/ai-react";
 import type { ModelMessage } from "@tanstack/ai";
+import type {
+  ChatResumeState,
+  ChatPendingInterrupt,
+  RunAgentResumeItem,
+} from "@tanstack/ai-client";
 
 interface UseChatReturn {
   messages: UIMessage[];
@@ -123,6 +128,15 @@ interface UseChatReturn {
   error: Error | undefined;
   setMessages: (messages: UIMessage[]) => void;
   clear: () => void;
+  // Correlation ids `{ threadId, runId }` for the interrupted run, or null.
+  resumeState: ChatResumeState | null;
+  // Interrupts currently awaiting a resume response.
+  pendingInterrupts: ChatPendingInterrupt[];
+  // Resolve pending interrupts by sending AG-UI resume entries.
+  resumeInterrupts: (
+    resume: RunAgentResumeItem[],
+    state?: ChatResumeState,
+  ) => Promise<boolean>;
 }
 ```
 
@@ -158,6 +172,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`, `initialResumeSnapshot`, `devtools`, `onResult`, `onError`,
+`onProgress`, and `onChunk`.
+
+Generation hook returns include `generate`, `result`, `isLoading`, `error`,
+`status`, `stop`, `reset`, `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 46de176a9..ed3b6e01e 100644
--- a/docs/api/ai-solid.md
+++ b/docs/api/ai-solid.md
@@ -76,7 +76,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
@@ -93,6 +93,11 @@ Extends `ChatClientOptions` from `@tanstack/ai-client`:
 import type { Accessor } from "solid-js";
 import type { UIMessage } from "@tanstack/ai-solid";
 import type { ModelMessage } from "@tanstack/ai/client";
+import type {
+  ChatResumeState,
+  ChatPendingInterrupt,
+  RunAgentResumeItem,
+} from "@tanstack/ai-client";
 
 interface UseChatReturn {
   messages: Accessor<UIMessage[]>;
@@ -115,11 +120,39 @@ interface UseChatReturn {
   error: Accessor<Error | undefined>;
   setMessages: (messages: UIMessage[]) => void;
   clear: () => void;
+  // Correlation ids `{ threadId, runId }` for the interrupted run, or null.
+  resumeState: Accessor<ChatResumeState | null>;
+  // Interrupts currently awaiting a resume response.
+  pendingInterrupts: Accessor<ChatPendingInterrupt[]>;
+  // Resolve pending interrupts by sending AG-UI resume entries.
+  resumeInterrupts: (
+    resume: RunAgentResumeItem[],
+    state?: ChatResumeState,
+  ) => Promise<boolean>;
 }
 ```
 
 **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`, `initialResumeSnapshot`, `devtools`, `onResult`, `onError`,
+`onProgress`, and `onChunk`.
+
+Generation hook returns include `generate`, `result`, `isLoading`, `error`,
+`status`, `stop`, `reset`, `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 8e7768b87..a2ed59f3f 100644
--- a/docs/api/ai-svelte.md
+++ b/docs/api/ai-svelte.md
@@ -74,7 +74,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)
@@ -90,7 +90,7 @@ Extends `ChatClientOptions` from `@tanstack/ai-client` (minus internal state cal
 ### Returns
 
 ```typescript
-import type { UIMessage, MultimodalContent, ChatClientState, ConnectionStatus } from "@tanstack/ai-client";
+import type { UIMessage, MultimodalContent, ChatClientState, ConnectionStatus, ChatResumeState, ChatPendingInterrupt, RunAgentResumeItem } from "@tanstack/ai-client";
 import type { ModelMessage } from "@tanstack/ai";
 
 interface CreateChatReturn<TContext = unknown> {
@@ -118,6 +118,15 @@ interface CreateChatReturn<TContext = unknown> {
   readonly sessionGenerating: boolean;
   setMessages: (messages: UIMessage[]) => void;
   clear: () => void;
+  // Correlation ids `{ threadId, runId }` for the interrupted run, or null.
+  readonly resumeState: ChatResumeState | null;
+  // Interrupts currently awaiting a resume response.
+  readonly pendingInterrupts: ChatPendingInterrupt[];
+  // Resolve pending interrupts by sending AG-UI resume entries.
+  resumeInterrupts: (
+    resume: RunAgentResumeItem[],
+    state?: ChatResumeState,
+  ) => Promise<boolean>;
   /** @deprecated Use `updateForwardedProps` instead. */
   updateBody: (body: Record<string, any>) => void;
   updateForwardedProps: (forwardedProps: Record<string, any>) => void;
@@ -297,9 +306,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?`, `initialResumeSnapshot?`, `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`, `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 06542576d..69a5dc93f 100644
--- a/docs/api/ai-vue.md
+++ b/docs/api/ai-vue.md
@@ -95,6 +95,9 @@ import type {
   MultimodalContent,
   ChatClientState,
   ConnectionStatus,
+  ChatResumeState,
+  ChatPendingInterrupt,
+  RunAgentResumeItem,
 } from "@tanstack/ai-client";
 
 interface UseChatReturn {
@@ -122,6 +125,15 @@ interface UseChatReturn {
   sessionGenerating: DeepReadonly<ShallowRef<boolean>>;
   setMessages: (messages: UIMessage[]) => void;
   clear: () => void;
+  // Correlation ids `{ threadId, runId }` for the interrupted run, or null.
+  resumeState: DeepReadonly<ShallowRef<ChatResumeState | null>>;
+  // Interrupts currently awaiting a resume response.
+  pendingInterrupts: DeepReadonly<ShallowRef<ChatPendingInterrupt[]>>;
+  // Resolve pending interrupts by sending AG-UI resume entries.
+  resumeInterrupts: (
+    resume: RunAgentResumeItem[],
+    state?: ChatResumeState,
+  ) => Promise<boolean>;
 }
 ```
 
@@ -314,9 +326,12 @@ const { generate, result, isLoading, error, status, stop, reset } =
   });
 ```
 
-**Options:** `connection?`, `fetcher?`, `id?`, `body?`, `onResult?`, `onError?`, `onProgress?`, `onChunk?`
+**Options:** `connection?`, `fetcher?`, `id?`, `body?`, `persistence?`, `initialResumeSnapshot?`, `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`, `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..7ec0f5bd6 100644
--- a/docs/architecture/approval-flow-processing.md
+++ b/docs/architecture/approval-flow-processing.md
@@ -1,448 +1,240 @@
 ---
 title: Approval Flow Processing Architecture
 id: approval-flow-processing
-description: "Internal architecture of TanStack AI's tool approval system — state machine, streaming protocol, concurrency control, and chained approval mechanics."
+description: "Internal architecture of TanStack AI tool approvals, interrupts, persistence, and typed client resume handling."
 keywords:
   - tanstack ai
   - approval flow
-  - tool approval
-  - architecture
+  - interrupts
   - state machine
-  - streaming protocol
-  - internals
-  - concurrency
+  - persistence
 ---
 
 # Approval Flow Processing Architecture
 
-> Internal architecture reference for the tool approval system in TanStack AI.
-> Covers the full lifecycle from stream event to continuation, with emphasis on
-> concurrency control and the chained approval mechanism.
-
----
-
-## Table of Contents
-
-1. [Overview](#overview)
-2. [Component Responsibilities](#component-responsibilities)
-3. [Type System](#type-system)
-4. [State Machine](#state-machine)
-5. [Single Approval Lifecycle](#single-approval-lifecycle)
-6. [Chained Approvals and Continuation Control](#chained-approvals-and-continuation-control)
-7. [Stream Event Protocol](#stream-event-protocol)
-8. [Key Source Files](#key-source-files)
-
----
-
-## Overview
-
-The approval flow allows tools marked with `needsApproval: true` to pause
-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 flow spans three layers:
-
-```mermaid
-flowchart TD
-    A[Server - TextEngine]
-    B[StreamProcessor]
-    C[ChatClient]
-
-    A -- "AG-UI stream · SSE / HTTP" --> B
-    B -- "events" --> C
-```
-
-| 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 |
-
-Framework hooks (`useChat` in React, Solid, Vue, Svelte) delegate to
-`ChatClient`, which owns all concurrency and continuation logic.
-
----
-
-## Component Responsibilities
-
-### TextEngine (server)
-
-- 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.
-
-### StreamProcessor (`packages/ai/src/activities/chat/stream/processor.ts`)
-
-- Single source of truth for `UIMessage[]` state.
-- On `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.
-- On `addToolApprovalResponse(approvalId, approved)`:
-  1. Calls `updateToolCallApprovalResponse()` to set state to
-     `approval-responded` and record `approval.approved`.
-- Provides `areAllToolsComplete()` which the ChatClient uses to decide whether
-  to auto-continue the conversation.
-
-### ChatClient (`packages/ai-client/src/chat-client.ts`)
-
-- Owns the streaming lifecycle (`streamResponse`), post-stream action queue,
-  and continuation control flags.
-- Exposes `addToolApprovalResponse()` as the public API for responding to
-  approval requests.
-- Manages two critical flags for continuation:
-  - `continuationPending` — prevents concurrent `streamResponse` calls.
-  - `continuationSkipped` — detects when a queued continuation check was
-    suppressed by `continuationPending` and needs re-evaluation.
-
-### Framework Hooks (React `useChat`, Solid `useChat`, etc.)
-
-- Wrap `ChatClient` methods in framework-specific reactive primitives.
-- Expose `addToolApprovalResponse` directly to the component.
-- No approval-specific logic beyond delegation.
-
----
-
-## Type System
-
-### ToolCallState
-
-```typescript group=approval-flow-processing
-type ToolCallState =
-  | 'awaiting-input'       // TOOL_CALL_START received, no arguments yet
-  | 'input-streaming'      // Partial arguments being received
-  | 'input-complete'       // All arguments received (TOOL_CALL_END)
-  | 'approval-requested'   // Waiting for user approval
-  | 'approval-responded'   // User has approved or denied
-```
-
-### ToolCallPart (approval-relevant fields)
-
-```typescript group=approval-flow-processing
-interface ToolCallPart {
-  type: 'tool-call'
-  id: string               // Unique tool call ID
-  name: string             // Tool name
-  arguments: string        // JSON string of arguments
-  state: ToolCallState
-
-  approval?: {
-    id: string             // Unique approval ID (NOT the toolCallId)
-    needsApproval: boolean // Always true when present
-    approved?: boolean     // undefined until user responds
-  }
-
-  output?: any             // Set after execution (client tools)
+Tool approval is an interrupt-and-resume protocol. A run that needs user input
+ends with one canonical event:
+
+```ts
+const event = {
+  type: 'RUN_FINISHED',
+  runId: 'run-1',
+  threadId: 'thread-1',
+  timestamp: Date.now(),
+  outcome: {
+    type: 'interrupt',
+    interrupts: [
+      {
+        id: 'approval-1',
+        reason: 'approval_required',
+        metadata: { kind: 'approval' },
+      },
+    ],
+  },
 }
 ```
 
-### Key distinction: approval ID vs tool call ID
-
-The `approval.id` is a separate identifier generated per approval request.
-All user-facing APIs (`addToolApprovalResponse`) use the **approval ID**,
-not the tool call ID. This allows the system to correlate approval responses
-even when multiple tools share similar call IDs across different messages.
-
----
-
-## State Machine
-
-```mermaid
-flowchart TD
-    S1[awaiting-input]
-    S2[input-streaming]
-    S3[input-complete]
-    S4[approval-requested]
-    S5([execute directly])
-    S6[approval-responded]
-    S7([execute tool])
-    S8([cancelled])
-
-    S1 -- "TOOL_CALL_START" --> S2
-    S2 -- "TOOL_CALL_ARGS" --> S3
-    S3 -- "TOOL_CALL_END · needsApproval: true" --> S4
-    S3 -- "TOOL_CALL_END · needsApproval: false" --> S5
-    S4 -- "addToolApprovalResponse()" --> S6
-    S6 -- "approved: true" --> S7
-    S6 -- "approved: false" --> S8
-```
-
-### Terminal states for `areAllToolsComplete()`
-
-A tool call is considered complete (and eligible for auto-continuation) when
-any of the following is true:
-
-1. `state === 'approval-responded'` — user approved or denied
-2. `output !== undefined && !approval` — client tool finished (no approval flow)
-3. A corresponding `tool-result` part exists — server tool finished
-
----
-
-## Single Approval Lifecycle
-
-Step-by-step flow for a single tool requiring approval:
-
-### 1. Server emits approval request during stream
-
-```
-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      { finishReason: "tool_calls" }
-```
+The canonical event stream is the only approval event stream. Server state
+persistence stores the interrupt record; stream delivery replay (resumable
+streams) is a separate transport concern.
 
-### 2. StreamProcessor processes the CUSTOM chunk
+## Responsibilities
 
+| Layer | Responsibility |
+| --- | --- |
+| Tool definition | Declares `needsApproval: true` for a sensitive operation. |
+| Chat engine | Stops before tool execution and emits the interrupt outcome. |
+| Chat persistence middleware | Creates pending interrupt records, marks the run interrupted, and snapshots messages. |
+| Chat client | Exposes `pendingInterrupts`, preserves `resumeState`, and sends typed resume entries. |
+| Application UI | Explains the operation and resolves or cancels each interrupt. |
+
+## Server setup
+
+Define the tool and add state persistence before handling requests:
+
+```ts
+// tools.ts
+import { toolDefinition } from '@tanstack/ai'
+import { z } from 'zod'
+
+export const deleteProject = toolDefinition({
+  name: 'delete_project',
+  description: 'Delete a project permanently',
+  inputSchema: z.object({ projectId: z.string() }),
+  outputSchema: z.object({ deleted: z.boolean() }),
+  needsApproval: true,
+}).server(async ({ projectId }) => {
+  await deleteProjectFromDatabase(projectId)
+  return { deleted: true }
+})
+
+declare function deleteProjectFromDatabase(projectId: string): Promise<void>
+```
+
+```ts
+// app/api/chat/route.ts
+import {
+  chat,
+  chatParamsFromRequest,
+  toServerSentEventsResponse,
+} from '@tanstack/ai'
+import { openaiText } from '@tanstack/ai-openai'
+import { withChatPersistence } from '@tanstack/ai-persistence'
+import { sqlitePersistence } from '@tanstack/ai-persistence-drizzle/sqlite'
+import { deleteProject } from './tools'
+
+const persistence = sqlitePersistence({
+  url: 'file:.tanstack-ai/state.sqlite',
+  migrate: true,
+})
+
+export async function POST(request: Request) {
+  const params = await chatParamsFromRequest(request)
+  const stream = chat({
+    adapter: openaiText('gpt-5.5'),
+    messages: params.messages,
+    threadId: params.threadId,
+    runId: params.runId,
+    ...(params.resume ? { resume: params.resume } : {}),
+    tools: [deleteProject],
+    middleware: [withChatPersistence(persistence)],
+  })
+
+  return toServerSentEventsResponse(stream)
+}
 ```
-handleCustomEvent():
-  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 })
-```
-
-### 3. Stream ends, ChatClient processes
-
-```
-streamResponse() finally block:
-  1. setIsLoading(false)
-  2. drainPostStreamActions() → (nothing queued)
-  3. streamCompletedSuccessfully check:
-     lastPart is tool-call (not tool-result) → no auto-continue
-  → Returns to caller (sendMessage resolves)
-```
-
-The conversation is now paused. The UI renders the approval prompt.
-
-### 4. User approves
-
-```
-addToolApprovalResponse({ id: "appr-1", approved: true }):
-  1. processor.addToolApprovalResponse("appr-1", true)
-     → updateToolCallApprovalResponse():
-       part.approval.approved = true
-       part.state = "approval-responded"
-  2. isLoading is false → call checkForContinuation() directly
-```
-
-### 5. Continuation
-
-```
-checkForContinuation():
-  1. continuationPending = false, isLoading = false → proceed
-  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
-  6. continuationPending = false
-```
-
----
-
-## Chained Approvals and Continuation Control
-
-The most complex scenario: a continuation stream produces **another** tool call
-that also needs approval, and the user responds to it while the stream is still
-active.
 
-### The Problem
-
-```
-Timeline:
-─────────────────────────────────────────────────────────────
-
-1. User approves tool A
-   └─ checkForContinuation() sets continuationPending = true
-   └─ streamResponse() starts (stream 2)
-
-2. Stream 2 produces tool B needing approval
-   └─ approval-requested chunk processed
-   └─ UI shows approval prompt for tool B
-
-3. User approves tool B WHILE stream 2 is still active
-   └─ addToolApprovalResponse():
-      └─ processor state updated (approval-responded)
-      └─ isLoading is true → queues checkForContinuation
-
-4. Stream 2 ends
-   └─ streamResponse() finally block:
-      └─ setIsLoading(false)
-      └─ drainPostStreamActions():
-         └─ Runs queued checkForContinuation()
-         └─ BUT continuationPending is STILL TRUE (from step 1)
-         └─ *** EARLY RETURN — approval swallowed ***
-   └─ Returns to step 1's checkForContinuation()
-   └─ continuationPending = false
-
-5. Nobody re-checks → tool B's approval is lost
+There is no feature flag. Middleware behavior follows the stores present on the
+`AIPersistence` object. `interrupts` requires `runs`; invalid store
+combinations fail at compile time when statically known and at runtime for
+untyped JavaScript.
+
+## Client state machine
+
+A single approval follows this sequence:
+
+1. The model emits a tool call.
+2. The client tool-call part reaches `approval-requested`.
+3. The run ends with `RUN_FINISHED.outcome.type === 'interrupt'`.
+4. `useChat` exposes the descriptor in `pendingInterrupts` and retains
+   `{ threadId, runId }` in `resumeState`.
+5. The UI calls `resumeInterrupts(...)` with a resolution for every pending
+   interrupt.
+6. The next request carries those values in `RunAgentInput.resume`.
+7. Persistence validates and resolves the stored records before the engine
+   continues the tool call.
+
+Normal input is rejected at step 4. This prevents a second branch from being
+created while the existing run still waits for a decision.
+
+## Real React approval UI
+
+Use the values returned by `useChat`. Rendering the actual
+`pendingInterrupts` array keeps ids and types connected to the hook that owns
+the run.
+
+```tsx group=approval-flow-processing
+import { fetchServerSentEvents, useChat } from '@tanstack/ai-react'
+
+export function ApprovalQueue() {
+  const chat = useChat({
+    id: 'project-chat',
+    threadId: 'project-thread',
+    connection: fetchServerSentEvents('/api/chat'),
+  })
+
+  return (
+    <section>
+      {chat.pendingInterrupts.map((interrupt) => (
+        <article key={interrupt.id}>
+          <p>Approval required: {interrupt.reason}</p>
+          <button
+            onClick={() =>
+              void chat.resumeInterrupts([
+                {
+                  interruptId: interrupt.id,
+                  status: 'resolved',
+                  payload: { approved: true },
+                },
+              ])
+            }
+          >
+            Approve
+          </button>
+          <button
+            onClick={() =>
+              void chat.resumeInterrupts([
+                { interruptId: interrupt.id, status: 'cancelled' },
+              ])
+            }
+          >
+            Deny
+          </button>
+        </article>
+      ))}
+    </section>
+  )
+}
 ```
 
-### The Solution: `continuationSkipped` Flag
-
-Two flags work together to handle this:
-
-- **`continuationPending`** — prevents concurrent `streamResponse()` calls.
-  Set to `true` when entering `checkForContinuation`'s streaming path, cleared
-  in the `finally` block.
-
-- **`continuationSkipped`** — set to `true` whenever `checkForContinuation()`
-  returns early due to `continuationPending` or `isLoading` being true.
-  Checked after `continuationPending` is cleared to trigger a re-evaluation.
+For a batch, send one entry per pending interrupt in one call:
 
-```typescript
-class ChatClient {
-  private continuationPending = false
-  private continuationSkipped = false
-  private isLoading = false
+```tsx group=approval-flow-processing
+import type { RunAgentResumeItem } from '@tanstack/ai/client'
 
-  private shouldAutoSend(): boolean { return false }
-  private async streamResponse(): Promise<void> {}
-
-  private async checkForContinuation(): Promise<void> {
-    if (this.continuationPending || this.isLoading) {
-      this.continuationSkipped = true   // ← Mark that a check was suppressed
-      return
-    }
-
-    if (this.shouldAutoSend()) {
-      this.continuationPending = true
-      this.continuationSkipped = false  // ← Reset before entering stream
-      try {
-        await this.streamResponse()
-      } finally {
-        this.continuationPending = false
+function resolveInterrupt(
+  interruptId: string,
+  approved: boolean,
+): RunAgentResumeItem {
+  return approved
+    ? {
+        interruptId,
+        status: 'resolved',
+        payload: { approved: true },
       }
-      // If a check was skipped during the stream, re-evaluate now
-      if (this.continuationSkipped) {
-        this.continuationSkipped = false
-        await this.checkForContinuation()  // ← Recurse safely
-      }
-    }
-  }
+    : { interruptId, status: 'cancelled' }
 }
-```
-
-### Why the recursion is safe
-
-The recursion terminates because:
-
-1. **`continuationSkipped` is only set when a real check was suppressed.** After
-   the final stream (e.g., a text-only response), no new approvals arrive, so
-   `continuationSkipped` stays `false` and the recursion stops.
-
-2. **`shouldAutoSend()` returns `false` when tools are still pending approval.**
-   If a new approval arrives that hasn't been responded to yet, `areAllToolsComplete()`
-   returns `false` and the method exits without streaming.
-
-3. **Each recursion level sets `continuationPending = true`**, preventing any
-   concurrent checks from entering the streaming path.
-
-### Corrected Timeline
-
-```
-Timeline (with fix):
-─────────────────────────────────────────────────────────────
-
-1. User approves tool A
-   └─ checkForContinuation() [OUTER]
-   └─ continuationPending = true, continuationSkipped = false
-   └─ streamResponse() starts (stream 2)
-
-2. Stream 2 produces tool B, user approves during stream
-   └─ Queues checkForContinuation as post-stream action
-
-3. Stream 2 ends
-   └─ drainPostStreamActions():
-      └─ checkForContinuation(): continuationPending is true
-         └─ continuationSkipped = true  ← MARKED
-         └─ returns early
-   └─ Back in OUTER: continuationPending = false
-
-4. OUTER checks continuationSkipped → true
-   └─ continuationSkipped = false
-   └─ Recurses into checkForContinuation() [INNER]
-   └─ shouldAutoSend() → true (tool B is approval-responded)
-   └─ continuationPending = true
-   └─ streamResponse() → stream 3 (final text response)
-   └─ continuationPending = false
-   └─ continuationSkipped is false → no further recursion
-
-5. Done. All three streams completed correctly.
-```
 
----
-
-## Stream Event Protocol
-
-### Approval-related AG-UI events
-
-These are `CUSTOM` events emitted by the TextEngine, not by adapters directly.
-
-#### `approval-requested`
-
-Emitted when a tool with `needsApproval: true` has its arguments finalized.
-
-```typescript ignore
-{
-  type: 'CUSTOM',
-  name: 'approval-requested',
-  value: {
-    toolCallId: string,    // ID of the tool call
-    toolName: string,      // Name of the tool
-    input: any,            // Parsed arguments
-    approval: {
-      id: string,          // Unique approval ID
-      needsApproval: true
-    }
-  }
+function ResolveAll({ approved }: { approved: boolean }) {
+  const chat = useChat({
+    threadId: 'project-thread',
+    connection: fetchServerSentEvents('/api/chat'),
+  })
+
+  return (
+    <button
+      onClick={() =>
+        void chat.resumeInterrupts(
+          chat.pendingInterrupts.map((interrupt) =>
+            resolveInterrupt(interrupt.id, approved),
+          ),
+        )
+      }
+    >
+      Resolve all
+    </button>
+  )
 }
 ```
 
-**Processor handling:** `handleCustomEvent()` → `updateToolCallApproval()` →
-`onApprovalRequest` callback.
-
-#### Relation to other tool events
+## Persistence and concurrency
 
-A complete approval tool call in the stream looks like:
+`withChatPersistence` performs these state transitions:
 
-```
-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 boundary | Run status | Other writes |
+| --- | --- | --- |
+| Start | `running` | Load and merge stored messages. |
+| Interrupt outcome | `interrupted` | Create pending interrupts and save messages. |
+| Successful finish | `completed` | Save messages and usage. |
+| Provider/server error | `failed` | Save the error. |
+| Abort | `interrupted` | Mark the run interrupted. |
 
-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
+When multiple workers can resume the same thread, provide a `locks` store.
+Cloudflare Durable Objects can supply that store while D1 supplies messages,
+runs, and interrupts. See [Cloudflare Persistence](../persistence/cloudflare).
 
----
+## State durability versus stream delivery
 
-## Key Source Files
-
-| File | Role |
-|------|------|
-| `packages/ai/src/types.ts` | `ToolCallState`, `ToolCallPart`, tool approval types |
-| `packages/ai/src/activities/chat/stream/processor.ts` | `handleCustomEvent()` (approval-requested), `areAllToolsComplete()`, `addToolApprovalResponse()` |
-| `packages/ai/src/activities/chat/stream/message-updaters.ts` | `updateToolCallApproval()`, `updateToolCallApprovalResponse()` |
-| `packages/ai-client/src/chat-client.ts` | `addToolApprovalResponse()`, `checkForContinuation()`, continuation flags |
-| `packages/ai-react/src/use-chat.ts` | React hook: exposes `addToolApprovalResponse` |
-| `packages/ai-solid/src/use-chat.ts` | Solid hook: exposes `addToolApprovalResponse` |
-| `packages/ai-vue/src/use-chat.ts` | Vue composable: exposes `addToolApprovalResponse` |
-| `packages/ai-svelte/src/create-chat.svelte.ts` | Svelte: exposes `addToolApprovalResponse` |
-| `packages/ai-client/tests/chat-client.test.ts` | Chained approval test (`describe('chained tool approvals')`) |
-| `packages/ai/docs/chat-architecture.md` | Internal stream processing architecture |
+Persisted interrupts survive page reloads and server restarts. They do not make
+the live byte stream replayable — that is stream re-attach / delivery
+durability, a separate transport-layer feature landing in PR #955.
diff --git a/docs/chat/connection-adapters.md b/docs/chat/connection-adapters.md
index a67e17e6f..4f3836732 100644
--- a/docs/chat/connection-adapters.md
+++ b/docs/chat/connection-adapters.md
@@ -2,532 +2,198 @@
 title: Connection Adapters
 id: connection-adapters
 order: 3
-description: "Connection adapters bridge your client and server in TanStack AI — SSE, HTTP streaming, server functions, RPC, and persistent transports like WebSockets via subscribe/send."
+description: "Connect TanStack AI clients to SSE, NDJSON, server functions, RPC, or subscription transports."
 keywords:
   - tanstack ai
   - connection adapters
   - sse
   - server-sent events
-  - http stream
+  - ndjson
   - websocket
-  - rpc
-  - server functions
-  - fetcher
-  - streaming transport
-  - fetchServerSentEvents
-  - subscribe send
 ---
 
-A **connection adapter** is the piece that decides _how_ chunks get from your server to the `ChatClient` (and through it, to your framework's `useChat`). Everything else in TanStack AI — chunk processing, message reassembly, tool calls, UI updates — is transport-agnostic. The adapter is the only thing that touches the network.
+# Connection Adapters
 
-This page covers every supported transport, when to pick which, and how to build a custom one.
+A connection adapter owns the client-to-server transport. Pass exactly one of
+`connection` or `fetcher` to `useChat`.
 
-## Pick a Transport
-
-| You have… | Use |
+| Adapter | Server response |
 | --- | --- |
-| A normal HTTP server and want the default | [`fetchServerSentEvents`](#server-sent-events-sse) |
-| An environment that blocks SSE (some edge runtimes, strict proxies) | [`fetchHttpStream`](#http-streaming-ndjson) |
-| React Native or Expo | [`xhrHttpStream`](#react-native-and-expo) by default, [`xhrServerSentEvents`](#react-native-and-expo) for SSE, or [`fetchHttpStream`](#http-streaming-ndjson) only when streaming `fetch` is available |
-| Code that **synchronously** returns an `AsyncIterable<StreamChunk>` (in-process `chat()`, an RSC stream, tests) | [`stream`](#server-functions-and-direct-async-iterables) |
-| An **async** call — a TanStack Start server function or any `Promise`-returning function — resolving to a `Response` or an `AsyncIterable<StreamChunk>` | [`fetcher`](#server-functions-via-fetcher) |
-| An RPC framework like Cap'n Web, gRPC-Web, or tRPC | [`rpcStream`](#rpc-streams) |
-| A single long-lived WebSocket (or BroadcastChannel, postMessage, shared worker) serving many runs | [Custom `subscribe` / `send` adapter](#persistent-transports-websockets-and-friends) |
-| Standard SSE but with custom fetch wrapping (auth refresh, retries) | [`fetchServerSentEvents` with `fetchClient`](#custom-fetch-client) |
-| Something else entirely (HTTP/3, Server-Sent Events over a different protocol, etc.) | [Custom `connect` adapter](#custom-request-scoped-adapters) |
-
-All adapters produce the same `StreamChunk` events ([AG-UI Protocol](../migration/ag-ui-compliance)) — the choice is purely about transport.
-
-## Server-Sent Events (SSE)
-
-The default. SSE is well-supported across browsers, transparent through most proxies, and easy to debug. Pair it with `toServerSentEventsResponse()` on the server.
-
-```typescript
-import { useChat, fetchServerSentEvents } from "@tanstack/ai-react";
-
-const { messages, sendMessage } = useChat({
-  connection: fetchServerSentEvents("/api/chat"),
-});
-```
-
-**Dynamic URL and headers.** Pass functions when the value depends on per-request state (current user, fresh token):
-
-```typescript
-import { useChat, fetchServerSentEvents } from "@tanstack/ai-react";
-import { currentUserId, getToken } from "./auth";
-
-const { messages } = useChat({
-  connection: fetchServerSentEvents(
-    () => `/api/chat?user=${currentUserId}`,
-    () => ({
-      headers: { Authorization: `Bearer ${getToken()}` },
-    }),
-  ),
-});
-```
-
-**Static body.** Anything in `options.body` is merged into the AG-UI `forwardedProps` payload sent to your server. Per-message data passed to `sendMessage` wins over this:
-
-```typescript
-import { useChat, fetchServerSentEvents } from "@tanstack/ai-react";
-
-const { messages } = useChat({
-  connection: fetchServerSentEvents("/api/chat", {
-    body: { provider: "openai", model: "gpt-5.1" },
-  }),
-});
-```
-
-> **Tip:** `body` and `forwardedProps` populate the same wire field. Use `body` for static defaults, the `forwardedProps` constructor option (or per-`sendMessage` `data`) for dynamic values. Runtime values always win.
-
-## HTTP Streaming (NDJSON)
-
-For environments that don't speak SSE — some edge runtimes, certain mobile WebViews, or anywhere a proxy strips `text/event-stream` — use raw newline-delimited JSON. The wire format is one JSON `StreamChunk` per line:
-
-```typescript
-import { useChat, fetchHttpStream } from "@tanstack/ai-react";
-
-const { messages } = useChat({
-  connection: fetchHttpStream("/api/chat"),
-});
-```
-
-Server-side, write each chunk as `JSON.stringify(chunk) + "\n"` to the response body. Options (`url`, `headers`, `body`, `fetchClient`, dynamic functions) match `fetchServerSentEvents` exactly.
-
-## React Native and Expo
-
-You have a native app that needs to call your own backend rather than a
-same-origin browser route. Use `useChat` from `@tanstack/ai-react` with an
-explicit chat transport and an absolute URL. By the end of this section, the
-client adapter and server response helper will be paired correctly for React
-Native or Expo.
-
-```typescript
-const baseUrl =
-  process.env.EXPO_PUBLIC_TANSTACK_AI_BASE_URL ??
-  'http://127.0.0.1:8787'
-const httpUrl = `${baseUrl}/chat/http`
-const sseUrl = `${baseUrl}/chat/sse`
-```
-
-Use the URL your runtime can reach. iOS simulators can often use `localhost` or
-`127.0.0.1`, Android emulators commonly use `10.0.2.2` to reach the host
-machine, and physical devices need a LAN or tunneled URL.
-
-Prefer `xhrHttpStream()` for Expo and React Native. It pairs with
-`toHttpResponse()` and reads newline-delimited JSON through incremental XHR
-progress events:
-
-```typescript
-import { useChat, xhrHttpStream } from "@tanstack/ai-react";
-
-const baseUrl = process.env.EXPO_PUBLIC_TANSTACK_AI_BASE_URL ?? 'http://127.0.0.1:8787';
-const httpUrl = `${baseUrl}/chat/http`;
-
-const chat = useChat({
-  connection: xhrHttpStream(httpUrl),
-});
-```
-
-Use `xhrServerSentEvents()` when your server returns `text/event-stream` via
-`toServerSentEventsResponse()`:
-
-```typescript
-import { useChat, xhrServerSentEvents } from "@tanstack/ai-react";
-
-const baseUrl = process.env.EXPO_PUBLIC_TANSTACK_AI_BASE_URL ?? 'http://127.0.0.1:8787';
-const sseUrl = `${baseUrl}/chat/sse`;
-
-const chat = useChat({
-  connection: xhrServerSentEvents(sseUrl),
-});
-```
-
-Only use `fetchHttpStream()` if your exact React Native runtime exposes
-streaming `fetch` responses, `Response.body.getReader()`, and `TextDecoder`.
-The server still returns newline-delimited JSON with `toHttpResponse()`:
-
-```typescript
-import { useChat, fetchHttpStream } from "@tanstack/ai-react";
-
-const baseUrl = process.env.EXPO_PUBLIC_TANSTACK_AI_BASE_URL ?? 'http://127.0.0.1:8787';
-const httpUrl = `${baseUrl}/chat/http`;
-
-const chat = useChat({
-  connection: fetchHttpStream(httpUrl),
-});
-```
-
-If one of those fetch-streaming APIs is missing, `fetchHttpStream()` throws
-`UnsupportedResponseStreamError`. A polyfill that buffers the response does not
-make fetch streaming compatible; the adapter needs incremental bytes. Switch to
-`xhrHttpStream()` or `xhrServerSentEvents()` instead.
-
-Keep provider SDKs and server helpers on your backend. The React Native bundle
-should import hooks and connection adapters, not OpenAI/Anthropic/Gemini SDKs,
-React DOM UI, devtools UI, or other framework packages. For a complete mobile
-walkthrough, see [Quick Start: React Native](../getting-started/quick-start-react-native).
-
-## Server Functions and Direct Async Iterables
-
-When your client can call into your server without going over HTTP — RSC streams, in-process tests, a direct in-process `chat()` call — skip the transport entirely. `stream()` takes a factory that returns an `AsyncIterable<StreamChunk>` **synchronously** and wires it straight into the client. (A [TanStack Start](https://tanstack.com/start) server function returns a `Promise`, so it needs [`fetcher`](#server-functions-via-fetcher), not `stream()` — see the next section.)
-
-```typescript
-import { useChat, stream } from "@tanstack/ai-react";
-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.
-const { messages } = useChat({
-  connection: stream((messages, data) => chatServerFn({ messages, ...data })),
-});
+| `fetchServerSentEvents` | `text/event-stream` |
+| `fetchHttpStream` | newline-delimited JSON |
+| `stream` | `ReadableStream` or `AsyncIterable` |
+| `rpcStream` | application RPC stream |
+| custom `subscribe` / `send` | WebSocket or another persistent transport |
+
+NDJSON is only an HTTP framing format. It is not tied to the sandbox harness.
+
+## Server-Sent Events
+
+Create a server endpoint that returns `toServerSentEventsResponse(...)`:
+
+```ts
+// app/api/chat/route.ts
+import {
+  chat,
+  chatParamsFromRequest,
+  toServerSentEventsResponse,
+} from '@tanstack/ai'
+import { openaiText } from '@tanstack/ai-openai'
+
+export async function POST(request: Request) {
+  const params = await chatParamsFromRequest(request)
+  const stream = chat({
+    adapter: openaiText('gpt-5.5'),
+    messages: params.messages,
+    threadId: params.threadId,
+    runId: params.runId,
+    ...(params.resume ? { resume: params.resume } : {}),
+  })
+
+  return toServerSentEventsResponse(stream)
+}
 ```
 
-The factory receives the conversation messages plus any per-request `data` you passed to `sendMessage`. Return any async iterable that yields `StreamChunk` objects — a generator, the output of `chat()` on the server, a transformed stream, anything.
-
-> **Tip:** `stream()` is **request-scoped**. The factory is invoked once per `sendMessage`, the iterable runs to completion, and the connection closes. If you need a single long-lived channel that multiplexes many sends — for example a WebSocket — use [`subscribe` / `send`](#persistent-transports-websockets-and-friends) instead.
-
-## Server Functions via `fetcher`
-
-When you call into your server with an **async** function — the universal case for a [TanStack Start](https://tanstack.com/start) server function, which always returns a `Promise` — use the top-level `fetcher` option instead of a connection adapter. `fetcher` is a sibling of `connection` (provide exactly one), and it accepts a plain async function. It mirrors the `fetcher` option on the [generation hooks](../media/generation-hooks). The most common shape is a handler that ends with `toServerSentEventsResponse(...)` and resolves to a `Response`:
+Connect from React:
 
-```typescript ignore
-// server/chat.server.ts
-import { createServerFn } from "@tanstack/react-start";
-import { chat, toServerSentEventsResponse } from "@tanstack/ai";
-import { openaiText } from "@tanstack/ai-openai";
-import type { UIMessage } from "@tanstack/ai";
+```tsx
+import { fetchServerSentEvents, useChat } from '@tanstack/ai-react'
 
-export const chatFn = createServerFn({ method: "POST" })
-  .inputValidator((data: { messages: Array<UIMessage> }) => data)
-  .handler(({ data }) =>
-    toServerSentEventsResponse(
-      chat({ adapter: openaiText("gpt-5.1"), messages: data.messages }),
-    ),
-  );
-```
-
-```typescript
-import { useChat } from "@tanstack/ai-react";
-import { chatFn } from "./server/chat.server";
+export function Chat() {
+  const chat = useChat({
+    connection: fetchServerSentEvents('/api/chat'),
+  })
 
-const { messages, sendMessage } = useChat({
-  fetcher: ({ messages }, { signal }) => chatFn({ data: { messages }, signal }),
-});
+  return (
+    <button onClick={() => void chat.sendMessage('Hello')}>
+      Send
+    </button>
+  )
+}
 ```
 
-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 adapter sends AG-UI `RunAgentInput`, parses each SSE `data:` event, and
+passes the event to the chat client. `stop()` aborts the active request.
 
-> **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.
+### Headers and dynamic options
 
-## RPC Streams
+The URL may be static or resolved for each request. Options may also be static,
+synchronous, or asynchronous, which supports rotating credentials.
 
-`rpcStream()` is identical in behavior to `stream()` but reads better at call sites that hand off to an RPC client. Use it when integrating with Cap'n Web, gRPC-Web, tRPC subscriptions, or any RPC framework that already returns an async iterable:
-
-```typescript
-import { useChat, rpcStream } from "@tanstack/ai-react";
-import { api } from "./rpc-client";
-
-// `api.chat.stream` is your RPC method; it must return an AsyncIterable<StreamChunk>.
-const { messages } = useChat({
-  connection: rpcStream((messages, data) =>
-    api.chat.stream({ messages, ...data }),
-  ),
-});
-```
+```tsx
+import { fetchServerSentEvents, useChat } from '@tanstack/ai-react'
 
-## Persistent Transports (WebSockets and Friends)
+declare function getAccessToken(): Promise<string>
 
-A persistent transport — WebSocket, BroadcastChannel, postMessage between iframes, a shared worker — is fundamentally different from request/response. You open the channel **once**, then send and receive over it for the lifetime of the client. `stream()`/`connect()` can't model this cleanly because they assume one async iterable per request.
+export function AuthenticatedChat() {
+  const chat = useChat({
+    connection: fetchServerSentEvents('/api/chat', async () => ({
+      headers: {
+        Authorization: `Bearer ${await getAccessToken()}`,
+      },
+      credentials: 'include',
+      body: { model: 'gpt-5.5' },
+    })),
+  })
 
-For these cases, implement the `SubscribeConnectionAdapter` interface directly. The shape (full definition in [The Adapter Interface](#the-adapter-interface)):
-
-```typescript
-import type { SubscribeConnectionAdapter } from "@tanstack/ai-react";
-
-// subscribe(abortSignal?): AsyncIterable<StreamChunk>   — long-lived
-// send(messages, data?, abortSignal?, runContext?): Promise<void> — one per user message
-```
-
-- `subscribe()` is called **once** by the `ChatClient` and returns a long-lived async iterable of every chunk the channel produces.
-- `send()` is called **once per user message** to push a request frame onto the channel. It returns when the frame has been written — chunks arrive separately through `subscribe()`.
-
-The runtime correlates them: chunks emitted on the subscription queue between `send()` and the next terminal event (`RUN_FINISHED` / `RUN_ERROR`) are attributed to that run.
-
-### WebSocket example
-
-```typescript
-import { useChat, type SubscribeConnectionAdapter } from "@tanstack/ai-react";
-import type { StreamChunk } from "@tanstack/ai";
-
-function websocketConnection(url: string): SubscribeConnectionAdapter {
-  const ws = new WebSocket(url);
-  const queue: Array<StreamChunk> = [];
-  let pending: ((chunk: StreamChunk | null) => void) | null = null;
-  let closed = false;
-
-  const ready = new Promise<void>((resolve) => {
-    ws.addEventListener("open", () => resolve(), { once: true });
-  });
-
-  function deliver(chunk: StreamChunk | null) {
-    const resolve = pending;
-    if (resolve) {
-      pending = null;
-      resolve(chunk);
-    } else if (chunk !== null) {
-      queue.push(chunk);
-    }
-  }
-
-  ws.addEventListener("message", (event) => {
-    const chunk: StreamChunk = JSON.parse(event.data);
-    deliver(chunk);
-  });
-  ws.addEventListener("close", () => {
-    closed = true;
-    deliver(null);
-  });
-
-  return {
-    async *subscribe(abortSignal) {
-      while (!abortSignal?.aborted && !closed) {
-        const buffered = queue.shift();
-        if (buffered !== undefined) {
-          yield buffered;
-          continue;
-        }
-        const chunk = await new Promise<StreamChunk | null>((resolve) => {
-          pending = resolve;
-          abortSignal?.addEventListener("abort", () => resolve(null), {
-            once: true,
-          });
-        });
-        if (chunk === null) return;
-        yield chunk;
-      }
-    },
-
-    async send(messages, data, _abortSignal, runContext) {
-      await ready;
-      ws.send(
-        JSON.stringify({
-          threadId: runContext?.threadId,
-          runId: runContext?.runId,
-          messages,
-          data,
-        }),
-      );
-    },
-  };
+  return <button onClick={() => void chat.sendMessage('Hello')}>Send</button>
 }
-
-const { messages } = useChat({
-  connection: websocketConnection("wss://example.com/chat"),
-});
 ```
 
-> **Tip:** Your server is responsible for emitting `RUN_FINISHED` (or `RUN_ERROR`) at the end of each run. Without it, the client will not know the assistant turn has ended and will wait indefinitely. See [Streaming](./streaming) for the full event lifecycle.
-
-### When to choose persistent over request-scoped
+Static adapter `body` values form the base request data. Hook
+`forwardedProps`, then per-send data, take precedence over the same keys.
 
-Pick `subscribe` / `send` when **any** of these are true:
+## NDJSON over HTTP
 
-- A single connection multiplexes many runs (chat thread keeps the socket open across messages).
-- The server pushes chunks outside of a request (presence updates, server-initiated tool calls, broadcast notifications).
-- You want to share one connection across multiple tabs (BroadcastChannel) or workers.
+Return `toHttpResponse(...)` from the server:
 
-Otherwise, prefer `fetchServerSentEvents` or `stream()` — they're simpler and require no connection lifecycle management.
+```ts
+// app/api/chat-ndjson/route.ts
+import { chat, chatParamsFromRequest, toHttpResponse } from '@tanstack/ai'
+import { openaiText } from '@tanstack/ai-openai'
 
-## Custom Fetch Client
-
-If you're keeping SSE or HTTP streaming but need to wrap `fetch` — for auth refresh, retries, logging, or routing through an edge proxy — pass a `fetchClient`:
-
-```typescript
-import { useChat, fetchServerSentEvents } from "@tanstack/ai-react";
-import { refreshToken } from "./auth";
-
-async function authedFetch(input: RequestInfo | URL, init?: RequestInit) {
-  let response = await fetch(input, init);
-  if (response.status === 401) {
-    await refreshToken();
-    response = await fetch(input, init);
-  }
-  return response;
+export async function POST(request: Request) {
+  const params = await chatParamsFromRequest(request)
+  return toHttpResponse(
+    chat({
+      adapter: openaiText('gpt-5.5'),
+      messages: params.messages,
+      threadId: params.threadId,
+      runId: params.runId,
+      ...(params.resume ? { resume: params.resume } : {}),
+    }),
+  )
 }
-
-const { messages } = useChat({
-  connection: fetchServerSentEvents("/api/chat", {
-    fetchClient: authedFetch,
-  }),
-});
 ```
 
-The `fetchClient` must satisfy the standard `fetch` signature. `fetchHttpStream` accepts the same option.
-
-## Custom Request-Scoped Adapters
-
-When none of the built-ins fit but the transport is still request-scoped (one request per user message), implement `ConnectConnectionAdapter` directly. This is the lowest-level escape hatch short of going persistent:
-
-```typescript
-import { useChat, type ConnectConnectionAdapter } from "@tanstack/ai-react";
-import type { StreamChunk } from "@tanstack/ai";
-
-const myAdapter: ConnectConnectionAdapter = {
-  async *connect(messages, data, abortSignal, runContext) {
-    const response = await fetch("/api/chat", {
-      method: "POST",
-      headers: { "Content-Type": "application/json" },
-      body: JSON.stringify({
-        threadId: runContext?.threadId,
-        runId: runContext?.runId,
-        messages,
-        ...data,
-      }),
-      ...(abortSignal ? { signal: abortSignal } : {}),
-    });
-
-    if (!response.ok) throw new Error(`HTTP ${response.status}`);
-    if (!response.body) throw new Error("Response has no body");
-
-    // Example: newline-delimited JSON. Replace this loop with whatever
-    // framing your wire format uses, yielding one `StreamChunk` per event.
-    const reader = response.body.getReader();
-    const decoder = new TextDecoder();
-    let buffer = "";
-    while (true) {
-      const { done, value } = await reader.read();
-      if (done) break;
-      buffer += decoder.decode(value, { stream: true });
-      const lines = buffer.split("\n");
-      buffer = lines.pop() ?? "";
-      for (const line of lines) {
-        if (line.trim()) {
-          const chunk: StreamChunk = JSON.parse(line);
-          yield chunk;
-        }
-      }
-    }
-  },
-};
-
-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.
-
-## The Adapter Interface
-
-A `ConnectionAdapter` is a union — provide **either** `connect`, **or** both `subscribe` and `send`. Never both modes.
+Use the matching client adapter:
 
-```typescript
-import type { UIMessage } from "@tanstack/ai-client";
-import type { ModelMessage, StreamChunk } from "@tanstack/ai";
+```tsx
+import { fetchHttpStream, useChat } from '@tanstack/ai-react'
 
-export interface RunAgentInputContext {
-  threadId: string;
-  runId: string;
-  parentRunId?: string;
-  clientTools?: Array<{ name: string; description: string; parameters: unknown }>;
-  forwardedProps?: Record<string, unknown>;
-}
-
-export interface ConnectConnectionAdapter {
-  connect(
-    messages: UIMessage[] | ModelMessage[],
-    data?: Record<string, any>,
-    abortSignal?: AbortSignal,
-    runContext?: RunAgentInputContext,
-  ): AsyncIterable<StreamChunk>;
-}
+export function NdjsonChat() {
+  const chat = useChat({
+    connection: fetchHttpStream('/api/chat-ndjson'),
+  })
 
-export interface SubscribeConnectionAdapter {
-  subscribe(abortSignal?: AbortSignal): AsyncIterable<StreamChunk>;
-  send(
-    messages: UIMessage[] | ModelMessage[],
-    data?: Record<string, any>,
-    abortSignal?: AbortSignal,
-    runContext?: RunAgentInputContext,
-  ): Promise<void>;
+  return <button onClick={() => void chat.sendMessage('Hello')}>Send</button>
 }
-
-export type ConnectionAdapter =
-  | ConnectConnectionAdapter
-  | SubscribeConnectionAdapter;
 ```
 
-Internally, `ChatClient` normalizes both shapes to a single `subscribe`/`send` pair via `normalizeConnectionAdapter()`. If you provide `connect`, it gets wrapped in an async queue; if you provide `subscribe` + `send` natively, they're used as-is.
-
-## Authentication
+`fetchHttpStream` parses one JSON event per line. It honors request aborts but
+does not reconnect and does not use resume offsets.
 
-Static headers go in `options.headers`:
+## Direct fetchers and server functions
 
-```typescript
-import { useChat, fetchServerSentEvents } from "@tanstack/ai-react";
-import { token } from "./auth";
+Use `fetcher` when the framework can call a server function directly. Return a
+`Response` with SSE or an `AsyncIterable<StreamChunk>`.
 
-const { messages } = useChat({
-  connection: fetchServerSentEvents("/api/chat", {
-    headers: { Authorization: `Bearer ${token}` },
-  }),
-});
-```
+```tsx
+import { useChat } from '@tanstack/ai-react'
+import { runChat } from './server-functions'
 
-For tokens that change per request (refresh tokens, short-lived JWTs), pass a function — it's called on every send, so the header always reflects the latest token:
+export function ServerFunctionChat() {
+  const chat = useChat({
+    fetcher: ({ messages, threadId, runId, resume }, { signal }) =>
+      runChat({ messages, threadId, runId, resume, signal }),
+  })
 
-```typescript
-import { useChat, fetchServerSentEvents } from "@tanstack/ai-react";
-import { getToken } from "./auth";
-
-const { messages } = useChat({
-  connection: fetchServerSentEvents("/api/chat", () => ({
-    headers: { Authorization: `Bearer ${getToken()}` },
-  })),
-});
+  return <button onClick={() => void chat.sendMessage('Hello')}>Send</button>
+}
 ```
 
-Cookies are sent automatically when `credentials` is `"same-origin"` (default) or `"include"`.
-
-## Cancellation
+The hook supplies an `AbortSignal`; forward it so `stop()` reaches the server
+function or provider.
 
-Every adapter — built-in or custom — receives an `AbortSignal`. Built-ins propagate it to `fetch`; custom adapters must honor it themselves. `useChat`'s `stop()` aborts the current run by triggering the signal:
-
-```typescript
-import { useChat, fetchServerSentEvents } from "@tanstack/ai-react";
-
-const { stop } = useChat({ connection: fetchServerSentEvents("/api/chat") });
-stop(); // aborts the active stream
-```
+## Custom adapters
 
-For `SubscribeConnectionAdapter`, the signal in `subscribe()` ends the entire subscription (component unmount); the signal in `send()` ends just the in-flight send.
+Implement `connect` for request/response transports:
 
-## Error Handling
+```ts
+import type {
+  ConnectConnectionAdapter,
+} from '@tanstack/ai-client'
+import type { StreamChunk } from '@tanstack/ai'
 
-Adapters should throw on transport errors (HTTP non-2xx, parse failures, dropped sockets). The `ChatClient` catches the throw, emits a `RUN_ERROR` chunk if none has been emitted yet, and surfaces it via `onError` / the `error` state:
+declare function callRpc(input: {
+  messages: unknown
+  signal?: AbortSignal
+}): AsyncIterable<StreamChunk>
 
-```typescript
-import { useChat, fetchServerSentEvents } from "@tanstack/ai-react";
-
-const { error } = useChat({
-  connection: fetchServerSentEvents("/api/chat"),
-  onError: (err) => console.error("Chat failed:", err),
-});
+const connection: ConnectConnectionAdapter = {
+  connect(messages, _data, signal) {
+    return callRpc({ messages, signal })
+  },
+}
 ```
 
-Don't swallow `AbortError` — let it propagate so the client knows the abort succeeded.
-
-## Best Practices
-
-- **Default to SSE.** It's the most compatible and the easiest to debug. Switch only when something blocks it.
-- **Use `stream()` when you can.** If you control both sides and don't need HTTP semantics, server functions are faster to wire up than building a custom adapter.
-- **Reach for `subscribe`/`send` only when you need persistence.** WebSockets are powerful but require you to handle reconnection, run correlation, and lifecycle yourself.
-- **Always honor `abortSignal`.** It's how the client cleans up on unmount and on `stop()`.
-- **Emit `RUN_FINISHED` from the server.** Without it, the client never knows the turn ended.
+Use `subscribe` plus `send` for a persistent transport such as a WebSocket.
+The subscription yields server events continuously; `send` starts or resumes a
+run. If the transport offers replay, its adapter owns that protocol and its
+offsets.
 
-## Next Steps
+## Errors and cancellation
 
-- [Streaming](./streaming) — the full event lifecycle and `StreamChunk` types
-- [AG-UI Client Compliance](../migration/ag-ui-compliance) — the wire protocol your server emits
-- [Cloudflare Adapter](../community-adapters/cloudflare) — example of a custom `fetchClient` in production
-- [API Reference: `@tanstack/ai-client`](../api/ai-client) — full type signatures
+Connection adapters throw on non-successful HTTP responses and malformed
+stream data. `useChat` exposes the resulting `error` and calls `onError`.
+Calling `stop()` aborts the current client request.
diff --git a/docs/chat/persistence.md b/docs/chat/persistence.md
index 985c8aa2d..73fdedf42 100644
--- a/docs/chat/persistence.md
+++ b/docs/chat/persistence.md
@@ -2,152 +2,224 @@
 title: Persistence
 id: chat-persistence
 order: 5
-description: "Persist chat conversations on the client with TanStack AI — hydrate on load, save on change, and clear on reset using a simple getItem/setItem/removeItem adapter."
+description: "Persist rendered chat state and interrupt resume state in the browser with localStorage, sessionStorage, IndexedDB, or a custom adapter."
 keywords:
   - tanstack ai
   - persistence
   - chat history
   - localStorage
+  - sessionStorage
   - indexeddb
   - offline
-  - hydration
 ---
 
-By default a `ChatClient` (and every framework `useChat`/`createChat` wrapper) keeps messages in memory only — reload the page or navigate away and the conversation is gone. The optional **persistence adapter** wires the client to a storage backend so conversations survive reloads, with no manual `initialMessages` + `onFinish` boilerplate.
+# Client Chat Persistence
 
-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.
+`useChat` can persist two browser-side values independently:
 
-## The adapter interface
+- `persistence.client` stores the rendered `UIMessage[]` under the chat `id`.
+- `persistence.server` stores the latest `ChatResumeSnapshot` under the
+  `threadId`. The snapshot contains the run identity and any pending
+  interrupts needed after a reload.
 
-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`:
+This is client hydration, not server state durability. Persist authoritative
+messages, runs, and interrupts with `withChatPersistence(...)`. Making an
+in-flight response replayable is a separate transport feature (stream re-attach
+/ delivery durability, landing in PR #955). See
+[Chat Persistence](../persistence/chat-persistence) for the complete flow.
 
-```typescript
-import type { UIMessage } from "@tanstack/ai-client";
+## Use IndexedDB for chat messages
 
-interface ChatClientPersistence {
-  getItem: (
-    id: string,
-  ) =>
-    | Array<UIMessage>
-    | null
-    | undefined
-    | Promise<Array<UIMessage> | null | undefined>;
-  setItem: (id: string, messages: Array<UIMessage>) => void | Promise<void>;
-  removeItem: (id: string) => void | Promise<void>;
+IndexedDB uses the browser's structured-clone algorithm, so values such as the
+optional `UIMessage.createdAt` `Date` survive a round trip without a custom
+codec.
+
+```tsx
+import {
+  indexedDBPersistence,
+} from '@tanstack/ai-client'
+import { fetchServerSentEvents, useChat } from '@tanstack/ai-react'
+import type { UIMessage } from '@tanstack/ai-react'
+
+export function SupportChat() {
+  const chat = useChat({
+    id: 'support-chat',
+    threadId: 'support-thread',
+    connection: fetchServerSentEvents('/api/chat'),
+    persistence: {
+      client: indexedDBPersistence<Array<UIMessage>>({
+        databaseName: 'support-app',
+        objectStoreName: 'chat-state',
+      }),
+    },
+  })
+
+  return (
+    <form
+      onSubmit={(event) => {
+        event.preventDefault()
+        const data = new FormData(event.currentTarget)
+        const message = data.get('message')
+        if (typeof message === 'string' && message.trim()) {
+          void chat.sendMessage(message)
+          event.currentTarget.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.isLoading}>Send</button>
+      <button type="button" onClick={() => chat.clear()}>
+        Clear
+      </button>
+    </form>
+  )
 }
 ```
 
-The `id` passed to each method is the client's `id` option. Provide a stable `id` per conversation so the right history is loaded back:
+`clear()` removes both in-memory state and the persisted entries. Storage
+operations may be synchronous or asynchronous; the chat client serializes its
+writes so a slower write cannot overwrite newer state.
 
-```typescript
-import { ChatClient } from "@tanstack/ai-client";
-import { adapter, myPersistenceAdapter } from "./chat-setup";
-
-const client = new ChatClient({
-  id: "conversation-123",
-  connection: adapter,
-  persistence: myPersistenceAdapter,
-});
-```
+## Use localStorage or sessionStorage
 
-## What the client does for you
+Web Storage only stores strings. `localStoragePersistence` and
+`sessionStoragePersistence` use JSON by default for JSON-safe values. Chat
+messages can contain `Date`, so provide a codec that restores it.
 
-When a `persistence` 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.
+```tsx
+import {
+  localStoragePersistence,
+  sessionStoragePersistence,
+} from '@tanstack/ai-client'
+import { fetchServerSentEvents, useChat } from '@tanstack/ai-react'
+import type { ChatResumeSnapshot } from '@tanstack/ai-client'
+import type { UIMessage } from '@tanstack/ai-react'
+
+type StoredMessage = Omit<UIMessage, 'createdAt'> & {
+  createdAt?: string
+}
 
-When `persistence` is omitted, nothing changes — the client behaves exactly as before. The option is fully backwards compatible.
+function serializeJson(value: unknown): string {
+  const stringify: (input: unknown) => unknown = JSON.stringify
+  const serialized = stringify(value)
+  if (typeof serialized !== 'string') {
+    throw new TypeError('The value is not JSON serializable.')
+  }
+  return serialized
+}
 
-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.
+const messages = localStoragePersistence<Array<UIMessage>>({
+  keyPrefix: 'my-app:messages:',
+  serialize: serializeJson,
+  deserialize(value) {
+    const stored: Array<StoredMessage> = JSON.parse(value)
+    return stored.map(({ createdAt, ...message }) => ({
+      ...message,
+      ...(createdAt ? { createdAt: new Date(createdAt) } : {}),
+    }))
+  },
+})
 
-## Framework usage
+const resumes = sessionStoragePersistence<ChatResumeSnapshot>({
+  keyPrefix: 'my-app:resume:',
+  serialize: serializeJson,
+  deserialize(value) {
+    return JSON.parse(value)
+  },
+})
 
-Every framework wrapper accepts the same `persistence` option and forwards it to the underlying `ChatClient`:
+export function PersistentChat() {
+  const chat = useChat({
+    id: 'chat-1',
+    threadId: 'thread-1',
+    connection: fetchServerSentEvents('/api/chat'),
+    persistence: { client: messages, server: resumes },
+  })
 
-```tsx
-// React / Preact
-import { useChat, fetchServerSentEvents } from "@tanstack/ai-react";
-import { myPersistenceAdapter } from "./persistence";
-
-const chat = useChat({
-  id: "conversation-123",
-  connection: fetchServerSentEvents("/api/chat"),
-  persistence: myPersistenceAdapter,
-});
+  return <p>{chat.messages.length} messages</p>
+}
 ```
 
-```ts
-// Solid / Vue — same option
-import { useChat, fetchServerSentEvents } from "@tanstack/ai-solid";
-import { myPersistenceAdapter } from "./persistence";
-
-const chat = useChat({
-  id: "conversation-123",
-  connection: fetchServerSentEvents("/api/chat"),
-  persistence: myPersistenceAdapter,
-});
-```
+`localStorage` survives browser restarts. `sessionStorage` is scoped to the
+current tab. Both adapters default to the key prefix `tanstack-ai:`.
 
-```ts ignore
-// Svelte
-const chat = createChat({
-  id: "conversation-123",
-  connection: fetchServerSentEvents("/api/chat"),
-  persistence: myPersistenceAdapter,
-});
-```
+## Resume pending interrupts after reload
 
-## Example: `localStorage`
+The hook exposes the persisted interrupt state directly. Render
+`pendingInterrupts` and call the returned `resumeInterrupts` function; do not
+manufacture a hook return type outside a component.
 
-A synchronous adapter backed by `localStorage`. Note that `UIMessage.createdAt` is a `Date`, which `JSON.stringify` turns into a string — revive it on read if you depend on it:
+```tsx
+import { fetchServerSentEvents, useChat } from '@tanstack/ai-react'
+
+export function Interrupts() {
+  const { pendingInterrupts, resumeInterrupts } = useChat({
+    threadId: 'thread-1',
+    connection: fetchServerSentEvents('/api/chat'),
+  })
+
+  return (
+    <ul>
+      {pendingInterrupts.map((interrupt) => (
+        <li key={interrupt.id}>
+          <span>{interrupt.reason}</span>
+          <button
+            onClick={() =>
+              void resumeInterrupts([
+                {
+                  interruptId: interrupt.id,
+                  status: 'resolved',
+                  payload: { approved: true },
+                },
+              ])
+            }
+          >
+            Continue
+          </button>
+          <button
+            onClick={() =>
+              void resumeInterrupts([
+                { interruptId: interrupt.id, status: 'cancelled' },
+              ])
+            }
+          >
+            Cancel
+          </button>
+        </li>
+      ))}
+    </ul>
+  )
+}
+```
 
-```typescript
-import type { ChatClientPersistence, UIMessage } from "@tanstack/ai-client";
+The server still validates that every resume entry matches a pending
+interrupt. Normal new input is rejected while interrupts remain unresolved.
 
-const localStoragePersistence: ChatClientPersistence = {
-  getItem: (id) => {
-    const raw = window.localStorage.getItem(id);
-    if (!raw) return null;
-    const stored: Array<UIMessage> = JSON.parse(raw);
-    return stored.map((message) => ({
-      ...message,
-      createdAt:
-        typeof message.createdAt === "string"
-          ? new Date(message.createdAt)
-          : message.createdAt,
-    }));
-  },
-  setItem: (id, messages) => {
-    window.localStorage.setItem(id, JSON.stringify(messages));
-  },
-  removeItem: (id) => {
-    window.localStorage.removeItem(id);
-  },
-};
-```
+## SSR and custom adapters
 
-## Example: IndexedDB (async)
+Browser storage is unavailable during SSR. The built-in adapters throw
+`StorageUnavailableError` when first used outside a browser rather than
+silently dropping data. Construct and use them in client components, or pass a
+custom `ChatStorageAdapter<T>` backed by your runtime's storage.
 
-For larger histories or structured queries, back the adapter with an async store such as IndexedDB. The client awaits async methods automatically:
+```ts
+import type { ChatStorageAdapter } from '@tanstack/ai-client'
 
-```typescript
-import type { ChatClientPersistence } from "@tanstack/ai-client";
-import { db } from "./db";
+declare const adapter: ChatStorageAdapter<string>
 
-const indexedDbPersistence: ChatClientPersistence = {
-  getItem: async (id) => {
-    const record = await db.conversations.get(id);
-    return record?.messages;
-  },
-  setItem: async (id, messages) => {
-    await db.conversations.put({ id, messages, updatedAt: Date.now() });
-  },
-  removeItem: async (id) => {
-    await db.conversations.delete(id);
-  },
-};
+await adapter.setItem('chat-1', 'value')
+const value = await adapter.getItem('chat-1')
+await adapter.removeItem('chat-1')
 ```
 
-Any backend works — IndexedDB, SQLite (Electron/Tauri), a remote database, or an in-memory `Map` for tests — as long as it implements the three methods.
+Keep `id` and `threadId` stable. Changing either selects a different persisted
+record.
diff --git a/docs/config.json b/docs/config.json
index 7debc1ba4..6f95a2b6c 100644
--- a/docs/config.json
+++ b/docs/config.json
@@ -108,7 +108,7 @@
           "label": "Tool Approval Flow",
           "to": "tools/tool-approval",
           "addedAt": "2026-04-15",
-          "updatedAt": "2026-07-08"
+          "updatedAt": "2026-07-09"
         },
         {
           "label": "Lazy Tool Discovery",
@@ -145,7 +145,7 @@
           "label": "MCP Apps",
           "to": "mcp/apps",
           "addedAt": "2026-06-24",
-          "updatedAt": "2026-06-26"
+          "updatedAt": "2026-07-03"
         }
       ]
     },
@@ -166,7 +166,8 @@
         {
           "label": "Connection Adapters",
           "to": "chat/connection-adapters",
-          "addedAt": "2026-04-15"
+          "addedAt": "2026-04-15",
+          "updatedAt": "2026-07-17"
         },
         {
           "label": "Thinking & Reasoning",
@@ -176,7 +177,8 @@
         {
           "label": "Persistence",
           "to": "chat/persistence",
-          "addedAt": "2026-06-02"
+          "addedAt": "2026-06-02",
+          "updatedAt": "2026-07-17"
         }
       ]
     },
@@ -275,7 +277,7 @@
           "label": "Transcription",
           "to": "media/transcription",
           "addedAt": "2026-04-15",
-          "updatedAt": "2026-07-03"
+          "updatedAt": "2026-07-17"
         },
         {
           "label": "Audio Recording",
@@ -304,7 +306,8 @@
         {
           "label": "Generation Hooks",
           "to": "media/generation-hooks",
-          "addedAt": "2026-04-15"
+          "addedAt": "2026-04-15",
+          "updatedAt": "2026-07-17"
         }
       ]
     },
@@ -337,7 +340,7 @@
           "label": "Overview",
           "to": "sandbox/overview",
           "addedAt": "2026-06-16",
-          "updatedAt": "2026-06-30"
+          "updatedAt": "2026-07-17"
         },
         {
           "label": "Quick Start",
@@ -379,7 +382,8 @@
         {
           "label": "Lifecycle & Snapshots",
           "to": "sandbox/lifecycle",
-          "addedAt": "2026-06-29"
+          "addedAt": "2026-06-29",
+          "updatedAt": "2026-07-09"
         },
         {
           "label": "Events",
@@ -400,6 +404,89 @@
         }
       ]
     },
+    {
+      "label": "Persistence",
+      "children": [
+        {
+          "label": "Overview",
+          "to": "persistence/overview",
+          "addedAt": "2026-06-18",
+          "updatedAt": "2026-07-18"
+        },
+        {
+          "label": "Persistence Controls",
+          "to": "persistence/controls",
+          "addedAt": "2026-07-08",
+          "updatedAt": "2026-07-18"
+        },
+        {
+          "label": "Migrations",
+          "to": "persistence/migrations",
+          "addedAt": "2026-07-08",
+          "updatedAt": "2026-07-18"
+        },
+        {
+          "label": "Chat Persistence",
+          "to": "persistence/chat-persistence",
+          "addedAt": "2026-07-03",
+          "updatedAt": "2026-07-10"
+        },
+        {
+          "label": "Sandbox Persistence",
+          "to": "persistence/sandbox-persistence",
+          "addedAt": "2026-07-03",
+          "updatedAt": "2026-07-18"
+        },
+        {
+          "label": "Generation Persistence",
+          "to": "persistence/generation-persistence",
+          "addedAt": "2026-07-07",
+          "updatedAt": "2026-07-18"
+        },
+        {
+          "label": "MCP Persistence",
+          "to": "persistence/mcp-persistence",
+          "addedAt": "2026-07-08",
+          "updatedAt": "2026-07-18"
+        },
+        {
+          "label": "Cloudflare",
+          "to": "persistence/cloudflare",
+          "addedAt": "2026-07-03",
+          "updatedAt": "2026-07-18"
+        },
+        {
+          "label": "Prisma",
+          "to": "persistence/prisma",
+          "addedAt": "2026-07-08",
+          "updatedAt": "2026-07-18"
+        },
+        {
+          "label": "Drizzle",
+          "to": "persistence/drizzle",
+          "addedAt": "2026-07-08",
+          "updatedAt": "2026-07-18"
+        },
+        {
+          "label": "SQL Backends",
+          "to": "persistence/sql-backends",
+          "addedAt": "2026-07-03",
+          "updatedAt": "2026-07-18"
+        },
+        {
+          "label": "Custom Stores",
+          "to": "persistence/custom-stores",
+          "addedAt": "2026-07-03",
+          "updatedAt": "2026-07-18"
+        },
+        {
+          "label": "Persistence Internals",
+          "to": "persistence/internals",
+          "addedAt": "2026-07-08",
+          "updatedAt": "2026-07-18"
+        }
+      ]
+    },
     {
       "label": "Advanced",
       "children": [
@@ -491,13 +578,13 @@
           "label": "@tanstack/ai-react",
           "to": "api/ai-react",
           "addedAt": "2026-04-15",
-          "updatedAt": "2026-07-08"
+          "updatedAt": "2026-07-17"
         },
         {
           "label": "@tanstack/ai-solid",
           "to": "api/ai-solid",
           "addedAt": "2026-04-15",
-          "updatedAt": "2026-07-08"
+          "updatedAt": "2026-07-17"
         },
         {
           "label": "@tanstack/ai-preact",
@@ -509,19 +596,19 @@
           "label": "@tanstack/ai-vue",
           "to": "api/ai-vue",
           "addedAt": "2026-04-15",
-          "updatedAt": "2026-07-08"
+          "updatedAt": "2026-07-17"
         },
         {
           "label": "@tanstack/ai-svelte",
           "to": "api/ai-svelte",
           "addedAt": "2026-04-15",
-          "updatedAt": "2026-07-08"
+          "updatedAt": "2026-07-17"
         },
         {
           "label": "@tanstack/ai-angular",
           "to": "api/ai-angular",
           "addedAt": "2026-06-15",
-          "updatedAt": "2026-07-08"
+          "updatedAt": "2026-07-17"
         }
       ]
     },
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..1ca0eb387 100644
--- a/docs/media/generation-hooks.md
+++ b/docs/media/generation-hooks.md
@@ -2,7 +2,7 @@
 title: Generation Hooks
 id: generation-hooks
 order: 7
-description: "Framework hooks for every TanStack AI media generation type — useGenerateImage, useGenerateAudio, useGenerateSpeech, useTranscription, useSummarize, useGenerateVideo."
+description: "Framework hooks for TanStack AI image, audio, speech, transcription, summarization, and video generation."
 keywords:
   - tanstack ai
   - generation hooks
@@ -12,46 +12,49 @@ keywords:
   - useTranscription
   - useSummarize
   - useGenerateVideo
-  - react hooks
 ---
 
 # Generation Hooks
 
-TanStack AI provides framework hooks for every generation type: image, audio, speech, transcription, summarization, and video. Each hook connects to a server endpoint and manages loading, error, and result state for you.
+Generation hooks connect a client UI to a generation endpoint and manage
+loading, result, error, progress, cancellation, and lightweight persisted state.
 
-## Overview
-
-Generation hooks share a consistent API across all media types:
-
-| Hook | Input | Result Type |
-|------|-------|-------------|
+| Hook | Input | Result |
+| --- | --- | --- |
 | `useGenerateImage` | `ImageGenerateInput` | `ImageGenerationResult` |
 | `useGenerateAudio` | `AudioGenerateInput` | `AudioGenerationResult` |
 | `useGenerateSpeech` | `SpeechGenerateInput` | `TTSResult` |
 | `useTranscription` | `TranscriptionGenerateInput` | `TranscriptionResult` |
 | `useSummarize` | `SummarizeGenerateInput` | `SummarizationResult` |
 | `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).
+| `useGeneration` | custom `TInput` | custom `TResult` |
 
-## Server Setup
+Pass exactly one `connection` or `fetcher`.
 
-Before using hooks on the client, you need a server endpoint that runs the generation and returns the result as SSE. Here's a minimal image generation endpoint:
+## Server endpoint
 
-```typescript
-// routes/api/generate/image.ts
-import { generateImage, toServerSentEventsResponse } from '@tanstack/ai'
+```ts
+// app/api/generate/image/route.ts
+import {
+  generateImage,
+  generationParamsFromRequest,
+  toServerSentEventsResponse,
+} from '@tanstack/ai'
 import { openaiImage } from '@tanstack/ai-openai'
 
-export async function POST(req: Request) {
-  const { prompt, size, numberOfImages } = await req.json()
+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 prompts only.')
+  }
 
   const stream = generateImage({
-    adapter: openaiImage('dall-e-3'),
-    prompt,
-    size,
-    numberOfImages,
+    ...(threadId ? { threadId } : {}),
+    ...(runId ? { runId } : {}),
+    adapter: openaiImage('gpt-image-2'),
+    prompt: input.prompt,
     stream: true,
   })
 
@@ -59,395 +62,239 @@ 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.
-
-## useGenerateImage
+Use the matching generation helper and request kind for other media. Validate
+app routing data before passing it into provider options.
 
-Trigger image generation and render the results.
+## Image generation
 
 ```tsx
-import { useGenerateImage, fetchServerSentEvents } from '@tanstack/ai-react'
 import { useState } from 'react'
+import { fetchServerSentEvents, useGenerateImage } from '@tanstack/ai-react'
 
-function ImageGenerator() {
+export function ImageGenerator() {
   const [prompt, setPrompt] = useState('')
-  const { generate, result, isLoading, error, reset } = useGenerateImage({
+  const image = useGenerateImage({
     connection: fetchServerSentEvents('/api/generate/image'),
   })
 
   return (
-    <div>
+    <section>
       <input
         value={prompt}
-        onChange={(e) => setPrompt(e.target.value)}
-        placeholder="Describe an image..."
+        onChange={(event) => setPrompt(event.target.value)}
       />
       <button
-        onClick={() => generate({ prompt })}
-        disabled={isLoading || !prompt.trim()}
+        disabled={image.isLoading || !prompt.trim()}
+        onClick={() => void image.generate({ prompt })}
       >
-        {isLoading ? 'Generating...' : 'Generate'}
+        Generate
+      </button>
+      <button disabled={!image.isLoading} onClick={image.stop}>
+        Stop
       </button>
 
-      {error && <p>Error: {error.message}</p>}
-
-      {result?.images.map((img, i) => (
+      {image.error ? <p>{image.error.message}</p> : null}
+      {image.result?.images.map((item, index) => (
         <img
-          key={i}
-          src={img.url || `data:image/png;base64,${img.b64Json}`}
-          alt={img.revisedPrompt || 'Generated image'}
+          key={item.url ?? index}
+          src={item.url ?? `data:image/png;base64,${item.b64Json}`}
+          alt={item.revisedPrompt ?? 'Generated image'}
         />
       ))}
-
-      {result && <button onClick={reset}>Clear</button>}
-    </div>
+    </section>
   )
 }
 ```
 
-The `generate` function accepts an `ImageGenerateInput`:
-
-| Field | Type | Description |
-|-------|------|-------------|
-| `prompt` | `string` | Text description of the desired image (required) |
-| `numberOfImages` | `number` | Number of images to generate |
-| `size` | `string` | Image size in WIDTHxHEIGHT format (e.g., `"1024x1024"`) |
-| `modelOptions` | `Record<string, any>` | Model-specific options |
-
-## useGenerateSpeech
-
-Convert text to speech and play it back.
+## Speech generation
 
 ```tsx
-import { useGenerateSpeech, fetchServerSentEvents } from '@tanstack/ai-react'
-import { useRef } from 'react'
+import { fetchServerSentEvents, useGenerateSpeech } from '@tanstack/ai-react'
 
-function SpeechGenerator() {
-  const audioRef = useRef<HTMLAudioElement>(null)
-  const { generate, result, isLoading, error } = useGenerateSpeech({
+export function SpeechGenerator() {
+  const speech = useGenerateSpeech({
     connection: fetchServerSentEvents('/api/generate/speech'),
   })
 
   return (
-    <div>
+    <section>
       <button
-        onClick={() => generate({ text: 'Hello, welcome to TanStack AI!', voice: 'alloy' })}
-        disabled={isLoading}
+        disabled={speech.isLoading}
+        onClick={() =>
+          void speech.generate({ text: 'Welcome', voice: 'alloy' })
+        }
       >
-        {isLoading ? 'Generating...' : 'Generate Speech'}
+        Generate speech
       </button>
-
-      {error && <p>Error: {error.message}</p>}
-
-      {result && (
+      {speech.result ? (
         <audio
-          ref={audioRef}
-          src={`data:audio/${result.format};base64,${result.audio}`}
           controls
-          autoPlay
+          src={`data:audio/${speech.result.format};base64,${speech.result.audio}`}
         />
-      )}
-    </div>
+      ) : null}
+    </section>
   )
 }
 ```
 
-The `generate` function accepts a `SpeechGenerateInput`:
-
-| Field | Type | Description |
-|-------|------|-------------|
-| `text` | `string` | The text to convert to speech (required) |
-| `voice` | `string` | The voice to use (e.g., `"alloy"`, `"echo"`) |
-| `format` | `'mp3' \| 'opus' \| 'aac' \| 'flac' \| 'wav' \| 'pcm'` | Output audio format |
-| `speed` | `number` | Audio speed (0.25 to 4.0) |
-| `modelOptions` | `Record<string, any>` | Model-specific options |
-
-The `TTSResult` contains `audio` (base64-encoded), `format`, and optionally `duration` and `contentType`.
-
-## useTranscription
-
-Transcribe audio files to text.
+## Transcription
 
 ```tsx
-import { useTranscription, fetchServerSentEvents } from '@tanstack/ai-react'
+import { fetchServerSentEvents, useTranscription } from '@tanstack/ai-react'
 
-function Transcriber() {
-  const { generate, result, isLoading, error } = useTranscription({
-    connection: fetchServerSentEvents('/api/transcribe'),
+export function Transcriber({ audio }: { audio: string }) {
+  const transcription = useTranscription({
+    connection: fetchServerSentEvents('/api/generate/transcription'),
   })
 
-  const handleFile = (e: React.ChangeEvent<HTMLInputElement>) => {
-    const file = e.target.files?.[0]
-    if (file) {
-      const reader = new FileReader()
-      reader.onload = () => {
-        generate({ audio: reader.result as string, language: 'en' })
-      }
-      reader.readAsDataURL(file)
-    }
-  }
-
   return (
-    <div>
-      <input type="file" accept="audio/*" onChange={handleFile} />
-
-      {isLoading && <p>Transcribing...</p>}
-      {error && <p>Error: {error.message}</p>}
-
-      {result && (
-        <div>
-          <h3>Transcription</h3>
-          <p>{result.text}</p>
-          {result.language && <p>Language: {result.language}</p>}
-          {result.duration && <p>Duration: {result.duration}s</p>}
-        </div>
-      )}
-    </div>
+    <section>
+      <button
+        disabled={transcription.isLoading}
+        onClick={() => void transcription.generate({ audio })}
+      >
+        Transcribe
+      </button>
+      <p>{transcription.result?.text}</p>
+    </section>
   )
 }
 ```
 
-The `generate` function accepts a `TranscriptionGenerateInput`:
-
-| Field | Type | Description |
-|-------|------|-------------|
-| `audio` | `string \| File \| Blob \| ArrayBuffer` | Audio data -- base64 string, File, Blob, or ArrayBuffer (required) |
-| `language` | `string` | Language in ISO-639-1 format (e.g., `"en"`) |
-| `prompt` | `string` | Optional prompt to guide the transcription |
-| `responseFormat` | `'json' \| 'text' \| 'srt' \| 'verbose_json' \| 'vtt'` | Common output format |
-| `modelOptions` | `Record<string, any>` | Model-specific options |
-
-## useSummarize
+## Summarization and video
 
-Summarize long text with configurable output styles.
+The hooks keep the same control shape:
 
 ```tsx
-import { useSummarize, fetchServerSentEvents } from '@tanstack/ai-react'
-import { useState } from 'react'
-
-function Summarizer() {
-  const [text, setText] = useState('')
-  const { generate, result, isLoading, error } = useSummarize({
-    connection: fetchServerSentEvents('/api/summarize'),
+import {
+  fetchServerSentEvents,
+  useGenerateVideo,
+  useSummarize,
+} from '@tanstack/ai-react'
+
+export function MediaActions() {
+  const summary = useSummarize({
+    connection: fetchServerSentEvents('/api/generate/summary'),
+  })
+  const video = useGenerateVideo({
+    connection: fetchServerSentEvents('/api/generate/video'),
   })
 
   return (
     <div>
-      <textarea
-        value={text}
-        onChange={(e) => setText(e.target.value)}
-        placeholder="Paste text to summarize..."
-        rows={8}
-      />
       <button
-        onClick={() => generate({ text, style: 'bullet-points', maxLength: 200 })}
-        disabled={isLoading || !text.trim()}
+        onClick={() =>
+          void summary.generate({ text: 'Long text to summarize...' })
+        }
       >
-        {isLoading ? 'Summarizing...' : 'Summarize'}
+        Summarize
       </button>
-
-      {error && <p>Error: {error.message}</p>}
-
-      {result && (
-        <div>
-          <h3>Summary</h3>
-          <p>{result.summary}</p>
-        </div>
-      )}
-    </div>
-  )
-}
-```
-
-The `generate` function accepts a `SummarizeGenerateInput`:
-
-| Field | Type | Description |
-|-------|------|-------------|
-| `text` | `string` | The text to summarize (required) |
-| `maxLength` | `number` | Maximum length of the summary |
-| `style` | `'bullet-points' \| 'paragraph' \| 'concise'` | Summary style |
-| `focus` | `Array<string>` | Topics to focus on |
-| `modelOptions` | `Record<string, any>` | Model-specific options |
-
-## useGenerateVideo
-
-Video generation is asynchronous -- a job is created on the server, then polled for status until completion. The hook manages the full lifecycle and exposes `jobId` and `videoStatus` so you can show progress.
-
-```tsx
-import { useGenerateVideo, fetchServerSentEvents } from '@tanstack/ai-react'
-
-function VideoGenerator() {
-  const { generate, result, jobId, videoStatus, isLoading, error } =
-    useGenerateVideo({
-      connection: fetchServerSentEvents('/api/generate/video'),
-      onStatusUpdate: (status) => {
-        console.log(`Video ${status.jobId}: ${status.status} (${status.progress}%)`)
-      },
-    })
-
-  return (
-    <div>
       <button
-        onClick={() => generate({ prompt: 'A flying car over a city', duration: 5 })}
-        disabled={isLoading}
+        onClick={() => void video.generate({ prompt: 'A city flyover' })}
       >
-        {isLoading ? 'Generating...' : 'Generate Video'}
+        Generate video
       </button>
-
-      {isLoading && videoStatus && (
-        <div>
-          <p>Job: {jobId}</p>
-          <p>Status: {videoStatus.status}</p>
-          {videoStatus.progress != null && (
-            <progress value={videoStatus.progress} max={100} />
-          )}
-        </div>
-      )}
-
-      {error && <p>Error: {error.message}</p>}
-
-      {result && (
-        <video src={result.url} controls autoPlay style={{ maxWidth: '100%' }} />
-      )}
     </div>
   )
 }
 ```
 
-The `generate` function accepts a `VideoGenerateInput`:
-
-| Field | Type | Description |
-|-------|------|-------------|
-| `prompt` | `string` | Text description of the desired video (required) |
-| `size` | `string` | Video size -- format depends on provider (e.g., `"16:9"`, `"1280x720"`) |
-| `duration` | `number` | Video duration in seconds |
-| `modelOptions` | `Record<string, any>` | Model-specific options |
-
-`useGenerateVideo` returns two extra properties beyond the standard set:
+Video generation may report job and progress events before a final result. The
+hook normalizes those events into the same status/error/result controls.
 
-| Property | Type | Description |
-|----------|------|-------------|
-| `jobId` | `string \| null` | The current job ID, set when the server creates a video job |
-| `videoStatus` | `VideoStatusInfo \| null` | Live status updates with `status`, `progress`, and `jobId` |
+## Shared return values
 
-The `VideoStatusInfo` type:
-
-```typescript
-interface VideoStatusInfo {
-  jobId: string
-  status: 'pending' | 'processing' | 'completed' | 'failed'
-  progress?: number     // 0-100
-  url?: string          // Set when completed
-  error?: string        // Set when failed
-}
-```
+All generation hooks expose:
 
-The hook also accepts `onJobCreated` and `onStatusUpdate` callbacks for fine-grained tracking.
+| Value | Meaning |
+| --- | --- |
+| `generate(input)` | Start an explicit generation request. |
+| `result` | Latest completed result or `null`. |
+| `isLoading` / `status` | Current client state. |
+| `error` | Latest error. |
+| `stop()` | Abort the current client connection. |
+| `reset()` | Clear local result and error state. |
+| `resumeSnapshot` | Lightweight observed run snapshot. |
+| `resumeState` | Observed `{ threadId, runId }` or `null`. |
+| `pendingArtifacts` | Artifact refs observed before completion. |
+| `resultArtifacts` | Artifact refs attached to the completed result. |
 
-## Base Hook: useGeneration
+`stop()` does not delete server state. Whether it stops provider work depends
+on whether the endpoint forwards and honors the abort signal.
 
-All specialized hooks are built on `useGeneration`. Use it directly when you have a custom generation type that doesn't fit the built-in hooks.
+## Persist the lightweight snapshot
 
 ```tsx
-import { useGeneration, fetchServerSentEvents } from '@tanstack/ai-react'
-
-interface EmbeddingInput {
-  text: string
-  model?: string
+import { localStoragePersistence } from '@tanstack/ai-client'
+import { fetchServerSentEvents, useGenerateVideo } from '@tanstack/ai-react'
+import type { GenerationResumeSnapshot } from '@tanstack/ai-client'
+
+function serializeJson(value: unknown): string {
+  const stringify: (input: unknown) => unknown = JSON.stringify
+  const serialized = stringify(value)
+  if (typeof serialized !== 'string') {
+    throw new TypeError('The value is not JSON serializable.')
+  }
+  return serialized
 }
 
-interface EmbeddingResult {
-  embedding: Array<number>
-  model: string
-  usage: { totalTokens: number }
-}
+const snapshots = localStoragePersistence<GenerationResumeSnapshot>({
+  keyPrefix: 'my-app:generation:',
+  serialize: serializeJson,
+  deserialize: JSON.parse,
+})
 
-function EmbeddingGenerator() {
-  const { generate, result, isLoading, error } = useGeneration<
-    EmbeddingInput,
-    EmbeddingResult
-  >({
-    connection: fetchServerSentEvents('/api/generate/embedding'),
+export function TrailerGenerator() {
+  const video = useGenerateVideo({
+    id: 'trailer-video',
+    connection: fetchServerSentEvents('/api/generate/video'),
+    persistence: { server: snapshots },
   })
 
   return (
-    <div>
-      <button onClick={() => generate({ text: 'Hello world' })} disabled={isLoading}>
-        Generate Embedding
+    <section>
+      <button
+        disabled={video.isLoading}
+        onClick={() => void video.generate({ prompt: 'A city flyover' })}
+      >
+        Generate
       </button>
-      {result && <p>Dimensions: {result.embedding.length}</p>}
-    </div>
+      {video.resultArtifacts.map((artifact) => (
+        <a
+          key={artifact.artifactId}
+          href={`/api/artifacts/${artifact.artifactId}`}
+        >
+          {artifact.name}
+        </a>
+      ))}
+    </section>
   )
 }
 ```
 
-### Options
-
-`UseGenerationOptions<TInput, TResult>` accepts:
-
-| Option | Type | Description |
-|--------|------|-------------|
-| `connection` | `ConnectConnectionAdapter` | Streaming transport (SSE, HTTP stream, custom) |
-| `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 |
-| `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) |
-| `onChunk` | `(chunk: StreamChunk) => void` | Per-chunk callback (connection mode only) |
-
-### Return Value
-
-`UseGenerationReturn<TOutput>` provides:
-
-| Property | Type | Description |
-|----------|------|-------------|
-| `generate` | `(input: TInput) => Promise<void>` | Trigger a generation request |
-| `result` | `TOutput \| null` | The generation result, or null |
-| `isLoading` | `boolean` | Whether a generation is in progress |
-| `error` | `Error \| undefined` | Current error, if any |
-| `status` | `GenerationClientState` | `'idle'` \| `'generating'` \| `'success'` \| `'error'` |
-| `stop` | `() => void` | Abort the current generation |
-| `reset` | `() => void` | Clear result, error, and return to idle |
-
-### Result Transforms
-
-The `onResult` callback can transform what gets stored in `result`:
-
-```tsx
-import { useGenerateImage, fetchServerSentEvents } from '@tanstack/ai-react'
-import type { ImageGenerationResult } from '@tanstack/ai'
-
-const { result } = useGenerateImage({
-  connection: fetchServerSentEvents('/api/generate/image'),
-  onResult: (raw: ImageGenerationResult) => raw.images.map((img) => img.url || img.b64Json),
-})
-// result is now string[] instead of ImageGenerationResult
-```
-
-## 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 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` |
+The `server` slot names the **server-authoritative** resume snapshot — the
+observed run identity keyed by the hook `id` — not a requirement that the store
+physically run on a server. Any `getItem`/`setItem`/`removeItem` adapter
+satisfies it, so backing it with `localStoragePersistence` is valid: a browser
+reload re-hydrates the run identity for display. In production you would
+typically point the same slot at a real server-side store.
 
-All three packages re-export `fetchServerSentEvents`, `fetchHttpStream`, and `stream` from `@tanstack/ai-client` for convenience.
+The snapshot contains no delivery offset, does not store media bytes, and does
+not auto-resume a run. Persist bytes on the server with
+`withGenerationPersistence(...)`; see
+[Generation Persistence](../persistence/generation-persistence).
 
-**Vue note:** Return values are wrapped in `DeepReadonly<ShallowRef<>>` -- access them with `.value` in both `<script>` and `<template>`.
+## Framework variants
 
-**Svelte note:** Functions use the `create*` naming convention and return Svelte 5 reactive state via `$state`.
+React, Vue, Svelte, Solid, and Angular expose the same capabilities with their
+native reactive conventions. React return values are plain values and
+functions; Vue uses refs, Svelte uses reactive getters, and Solid/Angular use
+accessors or signals.
 
-## Next Steps
+## Next steps
 
-- [Image Generation](./image-generation) -- Provider-specific options, sizes, and model availability
-- [Text-to-Speech](./text-to-speech) -- Voice options, audio formats, and streaming audio
-- [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
+- [Image Generation](./image-generation)
+- [Text-to-Speech](./text-to-speech)
+- [Transcription](./transcription)
+- [Video Generation](./video-generation)
+- [Generation Persistence](../persistence/generation-persistence)
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..9baaa326f
--- /dev/null
+++ b/docs/persistence/chat-persistence.md
@@ -0,0 +1,167 @@
+---
+title: Chat Persistence
+id: chat-persistence
+---
+
+# Chat Persistence
+
+Server chat persistence makes messages, run status, and interrupts
+authoritative beyond one request. Browser persistence can additionally hydrate
+rendered UI state. Reconnecting to an in-flight SSE response (resumable
+streams) is a third, independent transport-level feature.
+
+## Persist state on the server
+
+```ts
+// app/api/chat/route.ts
+import {
+  chat,
+  chatParamsFromRequest,
+  toServerSentEventsResponse,
+} from '@tanstack/ai'
+import { openaiText } from '@tanstack/ai-openai'
+import { withChatPersistence } from '@tanstack/ai-persistence'
+import { sqlitePersistence } from '@tanstack/ai-persistence-drizzle/sqlite'
+
+const persistence = sqlitePersistence({
+  url: 'file:.tanstack-ai/chat.sqlite',
+  migrate: true,
+})
+
+export async function POST(request: Request) {
+  const params = await chatParamsFromRequest(request)
+  const stream = chat({
+    adapter: openaiText('gpt-5.5'),
+    messages: params.messages,
+    threadId: params.threadId,
+    runId: params.runId,
+    ...(params.resume ? { resume: params.resume } : {}),
+    middleware: [withChatPersistence(persistence)],
+  })
+
+  return toServerSentEventsResponse(stream)
+}
+```
+
+There is no feature list. The middleware uses the stores that are present:
+
+- `messages` loads and saves the full model-message thread;
+- `runs` records running, completed, failed, or interrupted status;
+- `interrupts` records pending user/tool waits and requires `runs`;
+- `locks` is provided to other middleware for cross-worker coordination.
+
+SQLite's `migrate: true` is convenient for local development. In production,
+copy and apply the bundled migrations through your normal deployment workflow.
+
+## Hydrate the React client
+
+```tsx
+import {
+  indexedDBPersistence,
+  sessionStoragePersistence,
+} from '@tanstack/ai-client'
+import { fetchServerSentEvents, useChat } from '@tanstack/ai-react'
+import type {
+  ChatResumeSnapshot,
+  UIMessage,
+} from '@tanstack/ai-client'
+
+function serializeJson(value: unknown): string {
+  const stringify: (input: unknown) => unknown = JSON.stringify
+  const serialized = stringify(value)
+  if (typeof serialized !== 'string') {
+    throw new TypeError('The value is not JSON serializable.')
+  }
+  return serialized
+}
+
+const resumeStorage = sessionStoragePersistence<ChatResumeSnapshot>({
+  keyPrefix: 'my-app:chat-resume:',
+  serialize: serializeJson,
+  deserialize: JSON.parse,
+})
+
+export function Chat() {
+  const chat = useChat({
+    id: 'support-chat',
+    threadId: 'support-thread',
+    connection: fetchServerSentEvents('/api/chat'),
+    persistence: {
+      client: indexedDBPersistence<Array<UIMessage>>(),
+      server: resumeStorage,
+    },
+  })
+
+  return (
+    <main>
+      {chat.messages.map((message) => (
+        <p key={message.id}>
+          {message.parts.map((part, index) =>
+            part.type === 'text' ? (
+              <span key={index}>{part.content}</span>
+            ) : null,
+          )}
+        </p>
+      ))}
+
+      {chat.pendingInterrupts.map((interrupt) => (
+        <div key={interrupt.id}>
+          <span>{interrupt.reason}</span>
+          <button
+            onClick={() =>
+              void chat.resumeInterrupts([
+                {
+                  interruptId: interrupt.id,
+                  status: 'resolved',
+                  payload: { approved: true },
+                },
+              ])
+            }
+          >
+            Continue
+          </button>
+          <button
+            onClick={() =>
+              void chat.resumeInterrupts([
+                { interruptId: interrupt.id, status: 'cancelled' },
+              ])
+            }
+          >
+            Cancel
+          </button>
+        </div>
+      ))}
+    </main>
+  )
+}
+```
+
+The client message adapter is keyed by `id`; the resume snapshot adapter is
+keyed by `threadId`. Keep both stable. IndexedDB preserves `Date` values through
+structured clone. Web Storage uses JSON and needs a codec for values that are
+not JSON-safe.
+
+## Resume semantics
+
+When a run ends with an interrupt outcome, `useChat` records its
+`resumeState` and `pendingInterrupts`. A later `resumeInterrupts(...)` call
+sends typed `RunAgentResumeItem` entries. The server verifies that every entry
+matches a pending interrupt before resolving or cancelling stored records.
+
+Normal messages on that thread are rejected until pending interrupts are
+handled. This prevents accidental conversation forks.
+
+## Stream re-attach is separate
+
+Reconnecting to an in-flight SSE response without re-running the provider is a
+separate transport-layer feature (stream re-attach / delivery durability),
+landing in PR #955 — not part of the state middleware. It affects transport
+replay only. State middleware still owns messages, runs, and interrupts;
+neither `UIMessage` nor server persistence records carry stream delivery
+offsets.
+
+## Clear and retention
+
+`chat.clear()` clears browser state. It does not delete authoritative server
+records. Server-side deletion, archival, and tenant retention policies belong
+in your application and backend stores.
diff --git a/docs/persistence/cloudflare.md b/docs/persistence/cloudflare.md
new file mode 100644
index 000000000..e5f439b0e
--- /dev/null
+++ b/docs/persistence/cloudflare.md
@@ -0,0 +1,167 @@
+---
+title: Cloudflare Persistence
+id: cloudflare
+---
+
+# Cloudflare Persistence
+
+`@tanstack/ai-persistence-cloudflare` maps state stores to Cloudflare-native
+primitives:
+
+| Binding | Stores |
+| --- | --- |
+| D1 | `messages`, `runs`, `interrupts`, `metadata` |
+| Durable Objects | `locks` |
+
+Pass only the bindings you need. The return type contains exactly the stores
+those bindings can provide.
+
+This package persists state. It does not provide a stream-delivery adapter;
+stream re-attach / delivery durability is a separate transport-layer feature,
+landing in PR #955.
+
+## Configure bindings
+
+```jsonc
+// wrangler.jsonc
+{
+  "d1_databases": [
+    {
+      "binding": "AI_STATE",
+      "database_name": "tanstack-ai-state",
+      "database_id": "<database-id>",
+      "migrations_dir": "migrations"
+    }
+  ],
+  "durable_objects": {
+    "bindings": [
+      {
+        "name": "AI_LOCKS",
+        "class_name": "CloudflareLockDurableObject"
+      }
+    ]
+  },
+  "migrations": [
+    {
+      "tag": "v1",
+      "new_sqlite_classes": ["CloudflareLockDurableObject"]
+    }
+  ]
+}
+```
+
+Re-export the lock Durable Object from your Worker entry:
+
+```ts
+export { CloudflareLockDurableObject } from '@tanstack/ai-persistence-cloudflare'
+```
+
+## Create persistence
+
+```ts group=cloudflare
+/// <reference types="@cloudflare/workers-types" />
+import { cloudflarePersistence } from '@tanstack/ai-persistence-cloudflare'
+
+interface Env {
+  AI_STATE: D1Database
+  AI_LOCKS: DurableObjectNamespace
+}
+
+export function createPersistence(env: Env) {
+  return cloudflarePersistence({
+    d1: env.AI_STATE,
+    durableObjects: env.AI_LOCKS,
+    lockOptions: {
+      leaseDurationMs: 30_000,
+      retryDelayMs: 50,
+    },
+  })
+}
+```
+
+D1 stores structured records in SQLite tables. Each lock key is routed to a
+Durable Object, which serializes owners and uses leases/alarms for recovery.
+
+## Use it with chat
+
+```ts group=cloudflare
+import {
+  chat,
+  chatParamsFromRequest,
+  toServerSentEventsResponse,
+} from '@tanstack/ai'
+import { openaiText } from '@tanstack/ai-openai'
+import { withChatPersistence } from '@tanstack/ai-persistence'
+
+export default {
+  async fetch(request: Request, env: Env) {
+    try {
+      const params = await chatParamsFromRequest(request)
+      const persistence = createPersistence(env)
+      const stream = chat({
+        adapter: openaiText('gpt-5.5'),
+        messages: params.messages,
+        threadId: params.threadId,
+        runId: params.runId,
+        ...(params.resume ? { resume: params.resume } : {}),
+        middleware: [withChatPersistence(persistence)],
+      })
+
+      return toServerSentEventsResponse(stream)
+    } catch (error) {
+      if (error instanceof Response) return error
+      throw error
+    }
+  },
+}
+```
+
+## Apply D1 migrations
+
+The package exports an ordered `d1Migrations` manifest and a CLI. Copy the SQL
+into the directory managed by Wrangler:
+
+```bash
+pnpm exec tanstack-ai-cloudflare-migrations --out migrations
+wrangler d1 migrations apply tanstack-ai-state --local
+wrangler d1 migrations apply tanstack-ai-state --remote
+```
+
+Use `--stdout` to print the ordered SQL. Existing divergent files are not
+overwritten unless `--force` is passed. Commit the copied migrations and apply
+them before deploying code that uses the stores.
+
+Programmatic tooling can read the same manifest:
+
+```ts
+import { d1Migrations } from '@tanstack/ai-persistence-cloudflare'
+
+for (const migration of d1Migrations) {
+  console.log(migration.filename)
+}
+```
+
+## Override selected stores
+
+Use Cloudflare as the base and replace only application-owned stores:
+
+```ts group=cloudflare
+import { composePersistence } from '@tanstack/ai-persistence'
+import type { InterruptStore, RunStore } from '@tanstack/ai-persistence'
+
+declare const customInterrupts: InterruptStore
+declare const customRuns: RunStore
+
+export function createComposedPersistence(env: Env) {
+  return composePersistence(createPersistence(env), {
+    overrides: {
+      interrupts: customInterrupts,
+      runs: customRuns,
+    },
+  })
+}
+```
+
+D1 continues to own messages and metadata, and Durable Objects own locks.
+Cross-backend transactions are not added by composition; design retries and
+consistency explicitly.
diff --git a/docs/persistence/controls.md b/docs/persistence/controls.md
new file mode 100644
index 000000000..eea2f7251
--- /dev/null
+++ b/docs/persistence/controls.md
@@ -0,0 +1,165 @@
+---
+title: Persistence Controls
+id: controls
+---
+
+# Persistence Controls
+
+Persistence is controlled by store presence. Supply only the state stores your
+workflow needs and compose backends per store.
+
+## Decision table
+
+| Requirement | Stores or option |
+| --- | --- |
+| Rendered messages after a browser reload | `useChat({ persistence: { client } })` |
+| Pending client interrupt state after reload | `useChat({ persistence: { server } })` |
+| Authoritative server transcript | `messages` |
+| Run status and usage | `runs` |
+| Durable approvals or human input | `interrupts` and `runs` |
+| App or integration checkpoints | `metadata` |
+| Cross-worker coordination | `locks` |
+| Replay an in-flight response | Stream re-attach / delivery durability (separate transport feature, landing in PR #955 — not a store) |
+
+`withChatPersistence(persistence)` and
+`withGenerationPersistence(persistence)` inspect the stores. Store presence is
+the complete capability selection mechanism.
+
+## Compose and override stores
+
+`composePersistence` takes the base backend first and a configuration object
+second:
+
+```ts group=controls
+/// <reference types="@cloudflare/workers-types" />
+import {
+  composePersistence,
+  defineAIPersistence,
+} from '@tanstack/ai-persistence'
+import { cloudflarePersistence } from '@tanstack/ai-persistence-cloudflare'
+import type {
+  InterruptStore,
+  RunStore,
+} from '@tanstack/ai-persistence'
+
+declare const env: {
+  AI_STATE: D1Database
+  AI_LOCKS: DurableObjectNamespace
+}
+declare const interrupts: InterruptStore
+declare const runs: RunStore
+
+const base = cloudflarePersistence({
+  d1: env.AI_STATE,
+  durableObjects: env.AI_LOCKS,
+})
+
+const custom = defineAIPersistence({ stores: { interrupts, runs } })
+
+const persistence = composePersistence(base, {
+  overrides: {
+    interrupts: custom.stores.interrupts,
+    runs: custom.stores.runs,
+  },
+})
+```
+
+Each override is independent:
+
+| Override value | Result |
+| --- | --- |
+| key omitted | Inherit the base store. |
+| `undefined` | Inherit the base store. |
+| a store object | Replace that store only. |
+| `false` | Remove that store. |
+
+```ts group=controls
+const withoutLocks = composePersistence(base, {
+  overrides: {
+    locks: false,
+  },
+})
+```
+
+The type of `withoutLocks.stores` no longer contains a required `locks` key.
+Unknown store names fail type checking and are also rejected at runtime when
+values arrive from untyped JavaScript.
+
+## Valid store combinations
+
+Some capabilities require related stores:
+
+- `interrupts` requires `runs` for chat persistence.
+
+Known-invalid static compositions fail to type-check at the middleware call.
+Runtime validation covers dynamically typed inputs.
+
+```ts group=controls
+import { withGenerationPersistence } from '@tanstack/ai-persistence'
+
+const generationPersistence = composePersistence(base, {
+  overrides: {},
+})
+
+const middleware = withGenerationPersistence(generationPersistence)
+```
+
+## Consistency across backends
+
+Composition routes each method call to its selected store. It does not add a
+distributed transaction across stores. When related state spans services:
+
+- make writes idempotent;
+- use stable run and interrupt keys;
+- decide which store is authoritative;
+- handle a successful write followed by a failed related write;
+- use a lock when concurrent workers can mutate the same logical record.
+
+Overriding `interrupts` and `runs` together is often safer when the custom
+database needs transactional guarantees across those records.
+
+## Client controls
+
+Browser persistence is also per concern:
+
+```tsx
+import {
+  indexedDBPersistence,
+  sessionStoragePersistence,
+} from '@tanstack/ai-client'
+import { fetchServerSentEvents, useChat } from '@tanstack/ai-react'
+import type {
+  ChatResumeSnapshot,
+  UIMessage,
+} from '@tanstack/ai-client'
+
+function serializeJson(value: unknown): string {
+  const stringify: (input: unknown) => unknown = JSON.stringify
+  const serialized = stringify(value)
+  if (typeof serialized !== 'string') {
+    throw new TypeError('The value is not JSON serializable.')
+  }
+  return serialized
+}
+
+export function Chat() {
+  const chat = useChat({
+    id: 'chat-1',
+    threadId: 'thread-1',
+    connection: fetchServerSentEvents('/api/chat'),
+    persistence: {
+      client: indexedDBPersistence<Array<UIMessage>>(),
+      server: sessionStoragePersistence<ChatResumeSnapshot>({
+        serialize: serializeJson,
+        deserialize: JSON.parse,
+      }),
+    },
+  })
+
+  return <button onClick={() => chat.clear()}>Clear</button>
+}
+```
+
+Web Storage uses JSON and needs codecs for non-JSON values. IndexedDB uses
+structured clone. All browser adapters fail visibly when used in an SSR
+environment without the corresponding browser API.
diff --git a/docs/persistence/custom-stores.md b/docs/persistence/custom-stores.md
new file mode 100644
index 000000000..27f0435a4
--- /dev/null
+++ b/docs/persistence/custom-stores.md
@@ -0,0 +1,162 @@
+---
+title: Custom Stores
+id: custom-stores
+---
+
+# Custom Persistence Stores
+
+Implement custom stores when your infrastructure is not covered by the
+packaged backends or when selected data must remain in an application-owned
+database.
+
+## Define the stores you provide
+
+```ts
+import { defineAIPersistence } from '@tanstack/ai-persistence'
+import type {
+  MessageStore,
+  RunStore,
+} from '@tanstack/ai-persistence'
+
+declare const messages: MessageStore
+declare const runs: RunStore
+
+export const persistence = defineAIPersistence({
+  stores: { messages, runs },
+})
+```
+
+`defineAIPersistence` preserves the exact store keys in the type and rejects
+unknown keys at runtime. Middleware behavior follows the keys that exist.
+
+## Store interfaces
+
+### Messages
+
+```ts
+import type { ModelMessage } from '@tanstack/ai'
+
+interface MessageStore {
+  loadThread(threadId: string): Promise<Array<ModelMessage>>
+  saveThread(
+    threadId: string,
+    messages: Array<ModelMessage>,
+  ): Promise<void>
+}
+```
+
+`saveThread` receives the full authoritative model-message history, not a
+delta.
+
+### Runs
+
+```ts
+import type { RunRecord } from '@tanstack/ai-persistence'
+
+interface RunStore {
+  createOrResume(input: {
+    runId: string
+    threadId: string
+    status?: 'running' | 'completed' | 'failed' | 'interrupted'
+    startedAt: number
+  }): Promise<RunRecord>
+  update(
+    runId: string,
+    patch: Partial<
+      Pick<RunRecord, 'status' | 'finishedAt' | 'error' | 'usage'>
+    >,
+  ): Promise<void>
+  get(runId: string): Promise<RunRecord | null>
+}
+```
+
+Implement `createOrResume` idempotently. Retries may repeat the same run id.
+
+### Interrupts
+
+```ts
+import type { InterruptRecord } from '@tanstack/ai-persistence'
+
+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>>
+}
+```
+
+An `interrupts` store requires a `runs` store when used with chat persistence.
+
+### Metadata
+
+```ts
+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>
+}
+```
+
+Namespaces and value schemas are application-owned.
+
+### Locks
+
+`LockStore` comes from `@tanstack/ai`. Use it to serialize work that may run on
+multiple workers. A lock implementation should use leases or another recovery
+mechanism so a crashed owner cannot block forever. `withLock` passes an
+`AbortSignal` to the critical section. Lease-backed implementations abort that
+signal when ownership can no longer be guaranteed; callbacks must stop starting
+external mutations and pass the signal to cancellable dependencies.
+
+## Example message store
+
+```ts
+import type {
+  MessageStore,
+} from '@tanstack/ai-persistence'
+import type { ModelMessage } from '@tanstack/ai'
+
+const threads = new Map<string, Array<ModelMessage>>()
+
+export const messages: MessageStore = {
+  async loadThread(threadId) {
+    return [...(threads.get(threadId) ?? [])]
+  },
+  async saveThread(threadId, nextMessages) {
+    threads.set(threadId, [...nextMessages])
+  },
+}
+```
+
+For durable infrastructure, preserve the same semantics with database
+transactions, conditional writes, or stable idempotency keys.
+
+## Override selected packaged stores
+
+```ts
+/// <reference types="@cloudflare/workers-types" />
+
+import { composePersistence } from '@tanstack/ai-persistence'
+import { cloudflarePersistence } from '@tanstack/ai-persistence-cloudflare'
+import type { InterruptStore, RunStore } from '@tanstack/ai-persistence'
+
+declare const env: {
+  AI_STATE: D1Database
+}
+declare const interrupts: InterruptStore
+declare const runs: RunStore
+
+const base = cloudflarePersistence({ d1: env.AI_STATE })
+
+export const persistence = composePersistence(base, {
+  overrides: { interrupts, runs },
+})
+```
+
+Only those two stores move to the custom database; D1 still owns messages and
+metadata. Composition does not create a transaction across those systems;
+design related writes accordingly.
diff --git a/docs/persistence/drizzle.md b/docs/persistence/drizzle.md
new file mode 100644
index 000000000..ecc028378
--- /dev/null
+++ b/docs/persistence/drizzle.md
@@ -0,0 +1,167 @@
+---
+title: Persistence with Drizzle
+id: drizzle
+---
+
+# Persistence with Drizzle
+
+`@tanstack/ai-persistence-drizzle` supports SQLite-family Drizzle databases.
+It has two entry points:
+
+- the package root accepts an already-created, migrated `DrizzleSqliteDb` and is
+  safe to import in edge runtimes;
+- `/sqlite` is a Node-only convenience factory built on `node:sqlite`.
+
+There is no dialect option. For MySQL, PostgreSQL, or another Drizzle dialect,
+implement the `AIPersistence` stores for that database or use the Prisma
+backend.
+
+## Node SQLite
+
+```ts
+import { sqlitePersistence } from '@tanstack/ai-persistence-drizzle/sqlite'
+
+export const persistence = sqlitePersistence({
+  url: 'file:.tanstack-ai/state.sqlite',
+  migrate: true,
+})
+```
+
+`url` may be `:memory:`, a filesystem path, or a `file:`-prefixed path.
+`migrate: true` applies the bundled migrations before creating stores. Prefer
+deployment-time migrations in production.
+
+## Bring your own SQLite Drizzle database
+
+```ts group=drizzle-d1
+/// <reference types="@cloudflare/workers-types" />
+import { drizzle } from 'drizzle-orm/d1'
+import {
+  drizzlePersistence,
+  schema,
+} from '@tanstack/ai-persistence-drizzle'
+
+declare const env: { AI_STATE: D1Database }
+
+const db = drizzle(env.AI_STATE, { schema })
+export const persistence = drizzlePersistence(db)
+```
+
+The root entry does not import Node built-ins and works with Cloudflare D1 and
+other SQLite-compatible Drizzle drivers. The application owns connection
+lifecycle and migration timing.
+
+## Use the middleware
+
+```ts group=drizzle-d1
+import {
+  chat,
+  chatParamsFromRequest,
+  toServerSentEventsResponse,
+} from '@tanstack/ai'
+import { openaiText } from '@tanstack/ai-openai'
+import { withChatPersistence } from '@tanstack/ai-persistence'
+
+export async function POST(request: Request) {
+  const params = await chatParamsFromRequest(request)
+  const stream = chat({
+    adapter: openaiText('gpt-5.5'),
+    messages: params.messages,
+    threadId: params.threadId,
+    runId: params.runId,
+    ...(params.resume ? { resume: params.resume } : {}),
+    middleware: [withChatPersistence(persistence)],
+  })
+
+  return toServerSentEventsResponse(stream)
+}
+```
+
+`drizzlePersistence` provides all state stores except `locks`: this backend has
+no distributed lock, so consumers that need one (such as `withSandbox`) fall
+back to an in-process lock. When multiple workers must share a lock service, use
+`composePersistence` to add a distributed `locks` implementation — for example
+the Cloudflare Durable Object lock from `@tanstack/ai-persistence-cloudflare`.
+
+## Get the migrations
+
+The package exports the ordered `sqliteMigrations` manifest:
+
+```ts
+import { sqliteMigrations } from '@tanstack/ai-persistence-drizzle'
+
+for (const migration of sqliteMigrations) {
+  console.log(migration.id, migration.filename)
+}
+```
+
+Or copy canonical SQL files with the CLI:
+
+```bash
+pnpm exec tanstack-ai-drizzle-migrations --out migrations/tanstack-ai
+```
+
+Use `--stdout` to print the SQL. The CLI refuses to replace a divergent file
+unless `--force` is passed. Commit the copied files and apply them using your
+normal SQLite, D1, or Drizzle deployment workflow.
+
+## Schema ownership
+
+The exported `schema` contains `messages`, `runs`, `interrupts`, and
+`metadata`. Application tables may live beside these tables in the same
+database.
+
+## Own the schema
+
+If your project already uses drizzle-kit, you can own the TanStack AI schema
+outright instead of applying the bundled SQL. Emit the schema module into your
+project:
+
+```bash
+pnpm exec tanstack-ai-drizzle-schema --out src/db
+```
+
+This writes `src/db/tanstack-ai-schema.ts` — a regular Drizzle schema file that
+imports from **your** installed `drizzle-orm`. The CLI refuses to replace a
+divergent file unless `--force` is passed; `--stdout` prints the module instead.
+
+Add the file to your drizzle-kit schema paths so your own migration journal
+owns the DDL:
+
+```ts
+import { defineConfig } from 'drizzle-kit'
+
+export default defineConfig({
+  dialect: 'sqlite',
+  schema: ['./src/db/schema.ts', './src/db/tanstack-ai-schema.ts'],
+  out: './drizzle',
+})
+```
+
+Then pass the schema back so the runtime reads and writes through your copy:
+
+```ts
+import { drizzlePersistence } from '@tanstack/ai-persistence-drizzle'
+import { schema } from './tanstack-ai-schema'
+import { db } from './db'
+
+export const persistence = drizzlePersistence(db, { schema })
+```
+
+Because the runtime operates on the table objects you pass, the file is truly
+yours to shape:
+
+- **Rename tables and columns**, or drop the explicit column names and rely on
+  your drizzle `casing` configuration — the stores read database names from
+  your objects, so the generated SQL follows your conventions.
+- **Add app-owned columns** — for example a `userId` column on `messages` to
+  scope threads to users. Keep added columns nullable or defaulted so the
+  store inserts succeed; the TanStack AI stores never read or write them.
+- **Keep the contract columns** with their data shapes. The
+  `TanstackAiSqliteSchema` type enforces the shapes at compile time, and
+  `drizzlePersistence` validates the tables and columns exist at construction.
+
+When you own the schema this way, migrations flow entirely through your
+drizzle-kit journal — package upgrades that change the schema surface as
+drizzle-kit diffs when you update the emitted file. Don't mix this with the
+bundled SQL migrations: pick one DDL owner per database.
diff --git a/docs/persistence/generation-persistence.md b/docs/persistence/generation-persistence.md
new file mode 100644
index 000000000..2b3119a9b
--- /dev/null
+++ b/docs/persistence/generation-persistence.md
@@ -0,0 +1,121 @@
+---
+title: Generation Persistence
+id: generation-persistence
+---
+
+# Generation Persistence
+
+Generation persistence records run status for media generation activities.
+Client hooks may store a lightweight, read-only snapshot containing run
+identity, status, and errors.
+
+Generated bytes never belong in browser resume state.
+
+## Create the server endpoint
+
+```ts group=generation-persistence
+import {
+  generateImage,
+  generationParamsFromRequest,
+  toServerSentEventsResponse,
+} from '@tanstack/ai'
+import { openaiImage } from '@tanstack/ai-openai'
+import { withGenerationPersistence } from '@tanstack/ai-persistence'
+import { sqlitePersistence } from '@tanstack/ai-persistence-drizzle/sqlite'
+
+const persistence = sqlitePersistence({
+  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 stream = generateImage({
+    ...(threadId ? { threadId } : {}),
+    ...(runId ? { runId } : {}),
+    adapter: openaiImage('gpt-image-2'),
+    prompt: input.prompt,
+    stream: true,
+    middleware: [withGenerationPersistence(persistence)],
+  })
+
+  return toServerSentEventsResponse(stream)
+}
+```
+
+Use the matching request kind for audio, TTS, video, or transcription.
+`withGenerationPersistence` records runs whenever a `runs` store is present.
+
+Keep run ids unique across chat and generation when they share a backend,
+because `RunStore` is keyed by `runId`.
+
+## Persist the client snapshot
+
+```tsx
+import { localStoragePersistence } from '@tanstack/ai-client'
+import { fetchServerSentEvents, useGenerateImage } from '@tanstack/ai-react'
+import type { GenerationResumeSnapshot } from '@tanstack/ai-client'
+
+function serializeJson(value: unknown): string {
+  const stringify: (input: unknown) => unknown = JSON.stringify
+  const serialized = stringify(value)
+  if (typeof serialized !== 'string') {
+    throw new TypeError('The value is not JSON serializable.')
+  }
+  return serialized
+}
+
+const snapshots = localStoragePersistence<GenerationResumeSnapshot>({
+  keyPrefix: 'my-app:generation:',
+  serialize: serializeJson,
+  deserialize: JSON.parse,
+})
+
+export function HeroImageGenerator() {
+  const image = useGenerateImage({
+    id: 'hero-image',
+    connection: fetchServerSentEvents('/api/generate/image'),
+    persistence: { server: snapshots },
+  })
+
+  return (
+    <section>
+      <button
+        disabled={image.isLoading}
+        onClick={() =>
+          void image.generate({ prompt: 'A glass cabin in a pine forest' })
+        }
+      >
+        Generate
+      </button>
+
+      {image.resumeState ? <p>Last run: {image.resumeState.runId}</p> : null}
+    </section>
+  )
+}
+```
+
+The snapshot has no stream delivery offset and exposes no `resume()` action.
+Generation starts only when `generate(...)` is called. The snapshot is useful
+for observability after reload; it does not restart or reconnect to provider
+work.
+
+## Media bytes are not stored yet
+
+Persisted generation results reference the media URLs the provider returned.
+Provider CDN URLs typically expire, so a snapshot inspected much later may
+point at media that is no longer downloadable. Durable artifact storage
+(artifact metadata plus blob bytes, served from your own storage) is a
+follow-up feature and is not part of this release.
+
+## Delivery remains separate
+
+State persistence makes the run and result queryable after completion. It does
+not replay an in-flight response — that is a separate transport-layer feature
+(stream re-attach / delivery durability), landing in PR #955.
diff --git a/docs/persistence/internals.md b/docs/persistence/internals.md
new file mode 100644
index 000000000..ca0537cdc
--- /dev/null
+++ b/docs/persistence/internals.md
@@ -0,0 +1,108 @@
+---
+title: Persistence Internals
+id: internals
+---
+
+# Persistence Internals
+
+This page describes the contracts between middleware, state stores, and
+browser storage.
+
+## Two separate boundaries
+
+```text
+Application state        Browser hydration
+-----------------        -----------------
+AIPersistence stores     ChatStorageAdapter
+middleware lifecycle     UIMessage/snapshot
+server authoritative     client convenience
+```
+
+Stream delivery (replaying an in-flight SSE response) is a third, transport-only
+boundary — stream re-attach / delivery durability, a separate feature landing in
+PR #955 — and intentionally shares nothing with these two. State middleware
+never mutates chunks to add delivery offsets, and browser chat persistence
+stores rendered messages or interrupt resume snapshots, not server event logs.
+
+## Chat middleware lifecycle
+
+`withChatPersistence(persistence)` derives a plan from store presence:
+
+1. `setup` provides persistence, interrupt, and lock capabilities when their
+   stores exist.
+2. `onConfig` creates or resumes the run, loads pending interrupts, validates
+   resume entries, resolves or cancels them, then merges stored messages into
+   the request.
+3. `onChunk` reacts only to a `RUN_FINISHED` interrupt outcome by storing
+   interrupts, marking the run interrupted, and saving messages.
+4. `onFinish`, `onError`, and `onAbort` terminalize the run record.
+
+The canonical AG-UI chunk stream remains unchanged; persistence does not create
+a second event stream.
+
+## Generation middleware lifecycle
+
+`withGenerationPersistence(persistence)` records the run: `onStart` creates or
+resumes the run record, and `onFinish`, `onError`, and `onAbort` terminalize
+it. Durable media storage (artifact metadata plus blob bytes) is a follow-up
+feature.
+
+## Composition semantics
+
+```ts
+import {
+  composePersistence,
+  memoryPersistence,
+} from '@tanstack/ai-persistence'
+
+const base = memoryPersistence()
+const replacement = base.stores.messages
+
+const result = composePersistence(base, {
+  overrides: {
+    messages: replacement,
+    metadata: undefined,
+    locks: false,
+  },
+})
+```
+
+- `messages` is replaced.
+- `metadata` is inherited because the override is `undefined`.
+- `locks` is removed.
+- every omitted store is inherited.
+
+Composition copies the store map and does not mutate or dispose either input.
+The return type calculates which keys are required, optional, replaced, or
+removed. Unknown store keys are rejected statically and by runtime validation.
+
+Middleware adds capability validation:
+
+- chat rejects `interrupts` without `runs`.
+
+The runtime checks are required because JavaScript, configuration loading, and
+explicitly widened types can bypass static guarantees.
+
+## Backend ownership
+
+Packaged backends own resources differently:
+
+- Drizzle accepts a migrated SQLite-family database; its root import is
+  edge-safe. The `/sqlite` entry creates a Node SQLite connection.
+- Prisma accepts the application's generated and migrated client.
+- Cloudflare maps D1 to structured stores and Durable Objects to locks.
+
+`composePersistence` does not add distributed transactions. When related
+stores use different systems, adapter authors must define retry,
+idempotency, and consistency behavior.
+
+## Browser storage
+
+`ChatStorageAdapter<T>` allows synchronous or asynchronous `getItem`,
+`setItem`, and `removeItem`. The chat persistence controller orders writes and
+owns hydration/cleanup independently of the main `ChatClient` stream logic.
+
+Web Storage adapters serialize strings and require a codec for non-JSON values.
+IndexedDB uses structured clone. All three built-ins throw
+`StorageUnavailableError` when their browser API is unavailable, including
+SSR.
diff --git a/docs/persistence/mcp-persistence.md b/docs/persistence/mcp-persistence.md
new file mode 100644
index 000000000..5d375a347
--- /dev/null
+++ b/docs/persistence/mcp-persistence.md
@@ -0,0 +1,109 @@
+---
+title: MCP Persistence
+id: mcp-persistence
+---
+
+# MCP Persistence
+
+MCP does not define a separate persistence backend or event log. MCP tools run
+inside the normal chat lifecycle, so messages, runs, and interrupts use the
+same `AIPersistence` stores as any other chat. App-owned MCP session and OAuth
+correlation can use `metadata`.
+
+## Persist an MCP-backed chat
+
+```ts
+// app/api/chat/route.ts
+import {
+  chat,
+  chatParamsFromRequest,
+  toServerSentEventsResponse,
+} from '@tanstack/ai'
+import { openaiText } from '@tanstack/ai-openai'
+import { createMCPClient } from '@tanstack/ai-mcp'
+import { withChatPersistence } from '@tanstack/ai-persistence'
+import { sqlitePersistence } from '@tanstack/ai-persistence-drizzle/sqlite'
+
+const persistence = sqlitePersistence({
+  url: 'file:.tanstack-ai/mcp.sqlite',
+  migrate: true,
+})
+
+const weather = await createMCPClient({
+  transport: { type: 'http', url: 'https://weather.example.com/mcp' },
+})
+
+export async function POST(request: Request) {
+  const params = await chatParamsFromRequest(request)
+  const stream = chat({
+    adapter: openaiText('gpt-5.5'),
+    messages: params.messages,
+    threadId: params.threadId,
+    runId: params.runId,
+    ...(params.resume ? { resume: params.resume } : {}),
+    mcp: { clients: [weather] },
+    middleware: [withChatPersistence(persistence)],
+  })
+
+  return toServerSentEventsResponse(stream)
+}
+```
+
+The client uses the normal chat API:
+
+```tsx
+import { fetchServerSentEvents, useChat } from '@tanstack/ai-react'
+
+export function McpChat() {
+  const chat = useChat({
+    threadId: 'weather-thread',
+    connection: fetchServerSentEvents('/api/chat'),
+  })
+
+  return (
+    <button onClick={() => void chat.sendMessage('Will it rain tomorrow?')}>
+      Ask
+    </button>
+  )
+}
+```
+
+No feature list is required. Message, run, and interrupt behavior follows the
+stores present on `persistence`.
+
+## Store app-owned MCP metadata
+
+```ts
+import type { AIPersistence } from '@tanstack/ai-persistence'
+
+export 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 },
+  )
+}
+```
+
+TanStack AI does not prescribe the metadata value schema. Version values that
+must survive application upgrades, and avoid storing access tokens unless the
+backend and retention policy are designed for secrets.
+
+## Coordinate concurrent session changes
+
+Use `locks` when more than one worker can refresh or mutate the same remote MCP
+session.
+
+Making MCP chat SSE replayable is a separate transport-layer concern (stream
+re-attach / delivery durability, landing in PR #955); it is not an MCP state
+store.
diff --git a/docs/persistence/migrations.md b/docs/persistence/migrations.md
new file mode 100644
index 000000000..f68d64f1b
--- /dev/null
+++ b/docs/persistence/migrations.md
@@ -0,0 +1,91 @@
+---
+title: Persistence Migrations
+id: migrations
+---
+
+# Persistence Migrations
+
+Migration ownership depends on the backend. Apply schema changes before
+deploying code that reads or writes the corresponding stores.
+
+## Drizzle SQLite
+
+The Drizzle package bundles ordered canonical SQLite migrations. Copy them into
+your repository:
+
+```bash
+pnpm exec tanstack-ai-drizzle-migrations --out migrations/tanstack-ai
+```
+
+Or print the ordered SQL:
+
+```bash
+pnpm exec tanstack-ai-drizzle-migrations --stdout
+```
+
+The CLI preserves existing identical files and refuses to overwrite divergent
+files without `--force`. Apply the copied SQL using your normal SQLite,
+Drizzle, or D1 deployment process.
+
+For local Node development, the `/sqlite` factory can apply the same manifest:
+
+```ts
+import { sqlitePersistence } from '@tanstack/ai-persistence-drizzle/sqlite'
+
+const persistence = sqlitePersistence({
+  url: 'file:.tanstack-ai/state.sqlite',
+  migrate: true,
+})
+```
+
+Avoid request-time migrations in production.
+
+Projects that already run drizzle-kit can skip the bundled SQL entirely: emit
+the schema module with `tanstack-ai-drizzle-schema`, add it to your drizzle-kit
+schema paths, and let your own journal generate the DDL. See
+[Own the schema](./drizzle#own-the-schema). Pick one DDL owner per database —
+bundled SQL or your journal, not both.
+
+## Cloudflare D1
+
+The Cloudflare package provides D1-specific migration assets:
+
+```bash
+pnpm exec tanstack-ai-cloudflare-migrations --out migrations
+wrangler d1 migrations apply tanstack-ai-state --remote
+```
+
+It also exports `d1Migrations` for programmatic tooling. Durable Object locks
+do not use the D1 table migration set; configure their bindings and Durable
+Object migration tags in Wrangler.
+
+## Prisma
+
+Prisma ships a provider-neutral models fragment, then delegates SQL generation
+to your application:
+
+```bash
+pnpm exec tanstack-ai-prisma-models --out prisma/schema
+pnpm prisma migrate dev --name add-tanstack-ai-persistence
+pnpm prisma generate
+pnpm prisma migrate deploy
+```
+
+The copied fragment contains no datasource or generator. Keep those in your
+application schema and commit the native migration Prisma creates for your
+provider.
+
+## Custom stores
+
+Custom `AIPersistence` adapters own their schema and migrations entirely.
+Maintain compatibility with the public store records and method semantics;
+TanStack AI does not inspect your table layout.
+
+## Upgrade discipline
+
+1. Read the package release notes for schema changes.
+2. Refresh copied assets in a reviewable branch.
+3. Inspect the diff rather than using `--force` blindly.
+4. Back up production state where required.
+5. Apply migrations before deploying code that depends on them.
+6. Keep rollback and partial-deployment behavior explicit.
diff --git a/docs/persistence/overview.md b/docs/persistence/overview.md
new file mode 100644
index 000000000..c951a9409
--- /dev/null
+++ b/docs/persistence/overview.md
@@ -0,0 +1,129 @@
+---
+title: Persistence Overview
+id: overview
+---
+
+# Persistence Overview
+
+Persistence stores authoritative state — messages, runs, pending interrupts,
+metadata, and locks. It is configured with persistence middleware.
+
+Reconnecting to an in-flight streaming response is a separate transport-layer
+feature (stream re-attach / delivery durability, landing in PR #955), not part
+of this middleware. Persisting state does not automatically make a live
+response replayable, and a replayable response does not replace authoritative
+application state.
+
+## Store contract
+
+An `AIPersistence` object can expose these stores:
+
+| Store | Purpose |
+| --- | --- |
+| `messages` | Authoritative model-message history per thread. |
+| `runs` | Run status, timing, errors, and usage. |
+| `interrupts` | Pending, resolved, or cancelled human/tool waits. |
+| `metadata` | App and integration key/value state. |
+| `locks` | Cross-worker coordination. |
+
+Middleware activates behavior from the stores that are present; there is no
+separate enablement list.
+
+## Minimal server state persistence
+
+```ts
+import {
+  chat,
+  chatParamsFromRequest,
+  toServerSentEventsResponse,
+} from '@tanstack/ai'
+import { openaiText } from '@tanstack/ai-openai'
+import { withChatPersistence } from '@tanstack/ai-persistence'
+import { sqlitePersistence } from '@tanstack/ai-persistence-drizzle/sqlite'
+
+const persistence = sqlitePersistence({
+  url: 'file:.tanstack-ai/state.sqlite',
+  migrate: true,
+})
+
+export async function POST(request: Request) {
+  const params = await chatParamsFromRequest(request)
+  const stream = chat({
+    adapter: openaiText('gpt-5.5'),
+    messages: params.messages,
+    threadId: params.threadId,
+    runId: params.runId,
+    ...(params.resume ? { resume: params.resume } : {}),
+    middleware: [withChatPersistence(persistence)],
+  })
+
+  return toServerSentEventsResponse(stream)
+}
+```
+
+The Node convenience factory is SQLite-only. For an existing SQLite-family
+Drizzle database, including Cloudflare D1, use the edge-safe root
+`drizzlePersistence(db)`. For another database engine, implement the
+`AIPersistence` store interfaces or use Prisma.
+
+## Compose backends by store
+
+Use one backend as the first argument and replace only selected stores through
+the second argument:
+
+```ts
+/// <reference types="@cloudflare/workers-types" />
+import { composePersistence } from '@tanstack/ai-persistence'
+import { cloudflarePersistence } from '@tanstack/ai-persistence-cloudflare'
+import { defineAIPersistence } from '@tanstack/ai-persistence'
+import type { AIPersistenceStores } from '@tanstack/ai-persistence'
+
+declare const env: {
+  AI_STATE: D1Database
+  AI_LOCKS: DurableObjectNamespace
+}
+declare const myInterruptStore: NonNullable<
+  AIPersistenceStores['interrupts']
+>
+declare const myRunStore: NonNullable<AIPersistenceStores['runs']>
+
+const base = cloudflarePersistence({
+  d1: env.AI_STATE,
+  durableObjects: env.AI_LOCKS,
+})
+
+const appStores = defineAIPersistence({
+  stores: {
+    interrupts: myInterruptStore,
+    runs: myRunStore,
+  },
+})
+
+const persistence = composePersistence(base, {
+  overrides: {
+    interrupts: appStores.stores.interrupts,
+    runs: appStores.stores.runs,
+  },
+})
+```
+
+An omitted or explicitly `undefined` override inherits the base store. A store
+object replaces that one store. `false` removes it. The return type tracks the
+resulting keys, and runtime validation rejects unknown keys from untyped
+JavaScript.
+
+Cross-store consistency remains your responsibility. If `runs` and
+`interrupts` live in separate systems, design for partial failure and retries.
+
+## Choose a backend
+
+- [Cloudflare](./cloudflare): D1 structured state and Durable Object locks.
+- [Drizzle](./drizzle): SQLite-family Drizzle databases and a Node SQLite
+  convenience factory.
+- [Prisma](./prisma): provider-neutral Prisma models with your migrated client.
+- [Custom Stores](./custom-stores): implement only the store contracts you
+  need.
+
+Then choose a journey: [Chat](./chat-persistence),
+[Generation](./generation-persistence), [Sandbox](./sandbox-persistence), or
+[MCP](./mcp-persistence).
diff --git a/docs/persistence/prisma.md b/docs/persistence/prisma.md
new file mode 100644
index 000000000..2fbc42bc0
--- /dev/null
+++ b/docs/persistence/prisma.md
@@ -0,0 +1,148 @@
+---
+title: Persistence with Prisma
+id: prisma
+---
+
+# Persistence with Prisma
+
+`@tanstack/ai-persistence-prisma` accepts your generated and migrated
+`PrismaClient`. The package provides a provider-neutral models fragment, not a
+datasource, generator, connection URL, or prebuilt SQL migration.
+
+## Copy the models fragment
+
+```bash
+pnpm exec tanstack-ai-prisma-models --out prisma/schema
+```
+
+This writes `tanstack-ai.prisma`, containing only the TanStack AI models. Point
+Prisma at that multi-file schema directory alongside your application's
+datasource, generator, and models.
+
+Use `--stdout` to inspect the fragment. The CLI refuses to overwrite a
+divergent file unless `--force` is passed.
+
+The same asset is available programmatically:
+
+```ts
+import {
+  prismaModels,
+  prismaModelsFilename,
+} from '@tanstack/ai-persistence-prisma'
+
+console.log(prismaModelsFilename)
+console.log(prismaModels)
+```
+
+## Generate a native migration
+
+Use Prisma's normal workflow for your selected provider:
+
+```bash
+pnpm prisma migrate dev --name add-tanstack-ai-persistence
+pnpm prisma generate
+```
+
+Deploy the resulting application-owned migrations normally:
+
+```bash
+pnpm prisma migrate deploy
+```
+
+This lets Prisma generate provider-specific SQL and integrate the models with
+the rest of your schema history.
+
+## Create persistence
+
+```ts
+import { PrismaClient } from '@prisma/client'
+import { prismaPersistence } from '@tanstack/ai-persistence-prisma'
+
+const prisma = new PrismaClient()
+export const persistence = prismaPersistence(prisma)
+```
+
+The adapter provides messages, runs, interrupts, and metadata. The application
+owns client connection and shutdown lifecycle.
+
+## Use it with chat
+
+```ts
+import {
+  chat,
+  chatParamsFromRequest,
+  toServerSentEventsResponse,
+} from '@tanstack/ai'
+import { openaiText } from '@tanstack/ai-openai'
+import { withChatPersistence } from '@tanstack/ai-persistence'
+import { persistence } from './persistence'
+
+export async function POST(request: Request) {
+  const params = await chatParamsFromRequest(request)
+  const stream = chat({
+    adapter: openaiText('gpt-5.5'),
+    messages: params.messages,
+    threadId: params.threadId,
+    runId: params.runId,
+    ...(params.resume ? { resume: params.resume } : {}),
+    middleware: [withChatPersistence(persistence)],
+  })
+
+  return toServerSentEventsResponse(stream)
+}
+```
+
+`prismaPersistence` provides no `locks` store: this backend has no distributed
+lock, so consumers that need one (such as `withSandbox`) fall back to an
+in-process lock. Use `composePersistence` to add a distributed `locks`
+implementation — for example the Cloudflare Durable Object lock from
+`@tanstack/ai-persistence-cloudflare` — or to route selected stores to another
+system. Composition does not add a transaction across multiple backends.
+
+## Model layout
+
+The fragment maps four persisted store contracts to `Message`, `Run`,
+`Interrupt`, and `Metadata` models. IDs and timestamps use portable Prisma
+types so the application can generate migrations for its chosen provider.
+
+## Rename the models
+
+The fragment is yours once copied, and its model names are generic — an
+application often already has a `Message` or `Run` model. Rename the TanStack
+AI models freely and map each store to the renamed client delegate:
+
+```prisma
+/// Renamed from `Message` to avoid a collision.
+model ChatMessage {
+  threadId     String @id @map("thread_id")
+  messagesJson String @map("messages_json")
+
+  @@map("messages")
+}
+```
+
+```ts
+import { PrismaClient } from '@prisma/client'
+import { prismaPersistence } from '@tanstack/ai-persistence-prisma'
+
+const prisma = new PrismaClient()
+
+export const persistence = prismaPersistence(prisma, {
+  models: { messages: 'chatMessage' },
+})
+```
+
+Map values are the camelCase client accessor names (`prisma.chatMessage`), not
+the PascalCase model names. Unmapped stores keep their default names
+(`message`, `run`, `interrupt`, `metadata`), and `prismaPersistence` throws a
+`PrismaModelError` naming every store whose delegate cannot be found.
+
+What stays fixed is the client-level field surface: keep the fragment's field
+names and types, and the default composite unique alias `scope_key` on the
+metadata model. Everything else is yours:
+
+- **Database names** — table and column names are already governed by
+  `@@map` / `@map` in your copy; change them without touching the runtime.
+- **Extra app-owned fields** — for example a `userId` on the messages model to
+  scope threads to users. Keep added fields optional or defaulted so the
+  store creates succeed; the TanStack AI stores never read or write them.
diff --git a/docs/persistence/sandbox-persistence.md b/docs/persistence/sandbox-persistence.md
new file mode 100644
index 000000000..6edebb7ca
--- /dev/null
+++ b/docs/persistence/sandbox-persistence.md
@@ -0,0 +1,87 @@
+---
+title: Sandbox Persistence
+id: sandbox-persistence
+---
+
+# Sandbox Persistence
+
+Sandbox persistence covers sandbox instance metadata used to resume a provider
+sandbox across runs.
+
+`withSandbox` reads persistence supplied by an earlier
+`withChatPersistence(...)` middleware: when the persistence exposes a
+`metadata` store, sandbox records (provider sandbox id, latest snapshot id,
+workspace key) are stored there, so a later run on the same thread resumes the
+existing sandbox instead of creating a new one. Without persistence, an
+in-memory store is used and resume works only within the same process.
+
+## Add persistence before sandbox middleware
+
+```ts
+import {
+  chat,
+  chatParamsFromRequest,
+  toServerSentEventsResponse,
+} from '@tanstack/ai'
+import { openaiText } from '@tanstack/ai-openai'
+import { withChatPersistence } from '@tanstack/ai-persistence'
+import { sqlitePersistence } from '@tanstack/ai-persistence-drizzle/sqlite'
+import { withSandbox } from '@tanstack/ai-sandbox'
+import { repoSandbox } from './repo-sandbox'
+
+const persistence = sqlitePersistence({
+  url: 'file:.tanstack-ai/sandbox.sqlite',
+  migrate: true,
+})
+
+export async function POST(request: Request) {
+  const params = await chatParamsFromRequest(request)
+  const stream = chat({
+    adapter: openaiText('gpt-5.5'),
+    messages: params.messages,
+    threadId: params.threadId,
+    runId: params.runId,
+    ...(params.resume ? { resume: params.resume } : {}),
+    middleware: [
+      withChatPersistence(persistence),
+      withSandbox(repoSandbox),
+    ],
+  })
+
+  return toServerSentEventsResponse(stream)
+}
+```
+
+The React client remains a normal chat client:
+
+```tsx
+import { fetchServerSentEvents, useChat } from '@tanstack/ai-react'
+
+export function CodingChat() {
+  const chat = useChat({
+    threadId: 'coding-thread',
+    connection: fetchServerSentEvents('/api/chat'),
+  })
+
+  return (
+    <button onClick={() => void chat.sendMessage('Update the README')}>
+      Run
+    </button>
+  )
+}
+```
+
+## Workspace file durability
+
+Provider snapshots (`lifecycle: { snapshot: 'after-run' }`) remain the way to
+preserve a sandbox's disk state between runs on providers that support them.
+Storing changed workspace files in your own persistence backend (per-file
+checkpoints restored into a fresh sandbox) depends on artifact/blob storage
+and lands in a follow-up release.
+
+## Delivery is not sandbox persistence
+
+Sandbox persistence does not make chat output replayable. Reconnecting to an
+in-flight run is a separate transport-layer feature (stream re-attach /
+delivery durability, landing in PR #955). Sandbox file events remain canonical
+stream chunks; persistence does not create a second event stream.
diff --git a/docs/persistence/sql-backends.md b/docs/persistence/sql-backends.md
new file mode 100644
index 000000000..2865663f5
--- /dev/null
+++ b/docs/persistence/sql-backends.md
@@ -0,0 +1,81 @@
+---
+title: SQL Backends
+id: sql-backends
+---
+
+# SQL Backends
+
+TanStack AI ships two SQL-oriented state adapters with different ownership
+models.
+
+| Adapter | Database support | Connection ownership | Schema workflow |
+| --- | --- | --- | --- |
+| `@tanstack/ai-persistence-drizzle` | SQLite-family only | Bring a migrated Drizzle DB, or use Node `/sqlite` | Bundled SQLite migration manifest and CLI |
+| `@tanstack/ai-persistence-prisma` | Providers supported by your Prisma schema | Bring your generated `PrismaClient` | Copy models fragment, then use Prisma migrate |
+
+The Drizzle adapter does not accept a dialect selector. Its schema and stores
+use SQLite APIs. For a non-SQLite Drizzle database, implement the public
+`AIPersistence` store interfaces for that dialect.
+
+## Local SQLite
+
+```ts
+import { sqlitePersistence } from '@tanstack/ai-persistence-drizzle/sqlite'
+
+export const persistence = sqlitePersistence({
+  url: 'file:.tanstack-ai/state.sqlite',
+  migrate: true,
+})
+```
+
+## Existing SQLite or D1 Drizzle database
+
+```ts
+/// <reference types="@cloudflare/workers-types" />
+import {
+  drizzlePersistence,
+  schema,
+} from '@tanstack/ai-persistence-drizzle'
+import { drizzle } from 'drizzle-orm/d1'
+
+declare const stateDatabase: D1Database
+
+const db = drizzle(stateDatabase, { schema })
+export const persistence = drizzlePersistence(db)
+```
+
+The package root is edge-safe; `/sqlite` is Node-only.
+
+## Prisma
+
+```ts group=sql-backends
+import { PrismaClient } from '@prisma/client'
+import { prismaPersistence } from '@tanstack/ai-persistence-prisma'
+
+const prisma = new PrismaClient()
+export const persistence = prismaPersistence(prisma)
+```
+
+Copy the package's models fragment and create provider-native migrations before
+constructing the adapter. See [Prisma](./prisma).
+
+## Store coverage
+
+Both adapters provide messages, runs, interrupts, and metadata. Neither
+provides a `locks` store; add a distributed store when multiple processes can
+mutate the same run:
+
+```ts group=sql-backends
+import { composePersistence } from '@tanstack/ai-persistence'
+import type { LockStore } from '@tanstack/ai'
+
+declare const distributedLocks: LockStore
+
+const coordinated = composePersistence(persistence, {
+  overrides: { locks: distributedLocks },
+})
+```
+
+For Cloudflare-native state, [Cloudflare Persistence](./cloudflare) combines
+D1 and Durable Object locks. For another SQL library, start with
+[Custom Stores](./custom-stores).
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 c4520fce2..2ab21975d 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..43260de0a 100644
--- a/examples/ts-react-chat/.env.example
+++ b/examples/ts-react-chat/.env.example
@@ -2,6 +2,9 @@
 # Get yours at: https://platform.openai.com/api-keys
 OPENAI_API_KEY=
 
+# SQLite persistence demo (/sqlite-persistence)
+SQLITE_CHAT_DB_URL=file:./sqlite-chat-persistence.db
+
 # 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..4517c1fde 100644
--- a/examples/ts-react-chat/README.md
+++ b/examples/ts-react-chat/README.md
@@ -37,8 +37,24 @@ An example chat application built with TanStack Start, TanStack Store, and **Tan
 
 ```env
 OPENAI_API_KEY=your_openai_api_key
+SQLITE_CHAT_DB_URL=file:./sqlite-chat-persistence.db
 ```
 
+## SQLite Persistence Demo
+
+The `/sqlite-persistence` route demonstrates server state persistence with the
+Node SQLite adapter and browser hydration with `localStorage`. Set
+`SQLITE_CHAT_DB_URL` or use the default `file:./sqlite-chat-persistence.db`,
+then run the app and open `/sqlite-persistence`.
+
+The server uses `@tanstack/ai-persistence-drizzle/sqlite` for messages, runs,
+and interrupts. The client stores rendered messages and its lightweight
+interrupt resume snapshot separately. Refresh after a completed response to
+see both sides hydrate the same stable thread.
+
+Replaying a transiently dropped SSE connection (resumable streams) is a
+separate transport-level feature and is not configured in this demo.
+
 ## 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 +94,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 +123,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 061f74d78..f5ab05666 100644
--- a/examples/ts-react-chat/src/components/Header.tsx
+++ b/examples/ts-react-chat/src/components/Header.tsx
@@ -6,6 +6,7 @@ import {
   BadgeCheck,
   Braces,
   Code2,
+  Database,
   FileAudio,
   FileText,
   Guitar,
@@ -245,6 +246,19 @@ export default function Header() {
             <span className="font-medium">Persistent Chats</span>
           </Link>
 
+          <Link
+            to="/sqlite-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">SQLite Persistence</span>
+          </Link>
+
           <Link
             to="/example/runtime-context"
             onClick={() => setIsOpen(false)}
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/lib/sqlite-persistence.ts b/examples/ts-react-chat/src/lib/sqlite-persistence.ts
new file mode 100644
index 000000000..212f036dc
--- /dev/null
+++ b/examples/ts-react-chat/src/lib/sqlite-persistence.ts
@@ -0,0 +1,36 @@
+import { sqlitePersistence } from '@tanstack/ai-persistence-drizzle/sqlite'
+import { composePersistence } from '@tanstack/ai-persistence'
+
+/**
+ * Durable **state** persistence for the persistent-chat demo.
+ *
+ * Persistence v2 ships a Node SQLite backend (Drizzle + bundled migrations)
+ * through {@link sqlitePersistence}. Other SQL databases can implement the
+ * persistence store interfaces over their existing database client.
+ * Replaying a dropped SSE connection (resumable streams) is a separate
+ * transport concern, not handled here.
+ */
+type ChatPersistence = ReturnType<typeof createChatPersistenceBackend>
+
+let persistence: ChatPersistence | undefined
+
+function createChatPersistenceBackend() {
+  return composePersistence(
+    sqlitePersistence({
+      url:
+        process.env.SQLITE_CHAT_DB_URL ?? 'file:./sqlite-chat-persistence.db',
+      migrate: true,
+    }),
+    {
+      overrides: {
+        metadata: false,
+        locks: false,
+      },
+    },
+  )
+}
+
+export function createChatPersistence(): ChatPersistence {
+  persistence ??= createChatPersistenceBackend()
+  return persistence
+}
diff --git a/examples/ts-react-chat/src/routeTree.gen.ts b/examples/ts-react-chat/src/routeTree.gen.ts
index b223bce09..2fa2f9029 100644
--- a/examples/ts-react-chat/src/routeTree.gen.ts
+++ b/examples/ts-react-chat/src/routeTree.gen.ts
@@ -11,6 +11,7 @@
 import { Route as rootRouteImport } from './routes/__root'
 import { Route as TypesafeToolsRouteImport } from './routes/typesafe-tools'
 import { Route as ThreadsRouteImport } from './routes/threads'
+import { Route as SqlitePersistenceRouteImport } from './routes/sqlite-persistence'
 import { Route as ServerFnChatRouteImport } from './routes/server-fn-chat'
 import { Route as SandboxesRouteImport } from './routes/sandboxes'
 import { Route as RealtimeRouteImport } from './routes/realtime'
@@ -36,6 +37,7 @@ import { Route as ApiTanchatRouteImport } from './routes/api.tanchat'
 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 ApiSqlitePersistentChatRouteImport } from './routes/api.sqlite-persistent-chat'
 import { Route as ApiSandboxTriageRouteImport } from './routes/api.sandbox-triage'
 import { Route as ApiMcpStatusRouteImport } from './routes/api.mcp-status'
 import { Route as ApiMcpPoolRouteImport } from './routes/api.mcp-pool'
@@ -65,6 +67,11 @@ const ThreadsRoute = ThreadsRouteImport.update({
   path: '/threads',
   getParentRoute: () => rootRouteImport,
 } as any)
+const SqlitePersistenceRoute = SqlitePersistenceRouteImport.update({
+  id: '/sqlite-persistence',
+  path: '/sqlite-persistence',
+  getParentRoute: () => rootRouteImport,
+} as any)
 const ServerFnChatRoute = ServerFnChatRouteImport.update({
   id: '/server-fn-chat',
   path: '/server-fn-chat',
@@ -193,6 +200,11 @@ const ApiStructuredChatRoute = ApiStructuredChatRouteImport.update({
   path: '/api/structured-chat',
   getParentRoute: () => rootRouteImport,
 } as any)
+const ApiSqlitePersistentChatRoute = ApiSqlitePersistentChatRouteImport.update({
+  id: '/api/sqlite-persistent-chat',
+  path: '/api/sqlite-persistent-chat',
+  getParentRoute: () => rootRouteImport,
+} as any)
 const ApiSandboxTriageRoute = ApiSandboxTriageRouteImport.update({
   id: '/api/sandbox-triage',
   path: '/api/sandbox-triage',
@@ -296,6 +308,7 @@ export interface FileRoutesByFullPath {
   '/realtime': typeof RealtimeRoute
   '/sandboxes': typeof SandboxesRoute
   '/server-fn-chat': typeof ServerFnChatRoute
+  '/sqlite-persistence': typeof SqlitePersistenceRoute
   '/threads': typeof ThreadsRoute
   '/typesafe-tools': typeof TypesafeToolsRoute
   '/api/capability-demo': typeof ApiCapabilityDemoRoute
@@ -310,6 +323,7 @@ export interface FileRoutesByFullPath {
   '/api/mcp-pool': typeof ApiMcpPoolRoute
   '/api/mcp-status': typeof ApiMcpStatusRoute
   '/api/sandbox-triage': typeof ApiSandboxTriageRoute
+  '/api/sqlite-persistent-chat': typeof ApiSqlitePersistentChatRoute
   '/api/structured-chat': typeof ApiStructuredChatRoute
   '/api/structured-output': typeof ApiStructuredOutputRoute
   '/api/summarize': typeof ApiSummarizeRoute
@@ -343,6 +357,7 @@ export interface FileRoutesByTo {
   '/realtime': typeof RealtimeRoute
   '/sandboxes': typeof SandboxesRoute
   '/server-fn-chat': typeof ServerFnChatRoute
+  '/sqlite-persistence': typeof SqlitePersistenceRoute
   '/threads': typeof ThreadsRoute
   '/typesafe-tools': typeof TypesafeToolsRoute
   '/api/capability-demo': typeof ApiCapabilityDemoRoute
@@ -357,6 +372,7 @@ export interface FileRoutesByTo {
   '/api/mcp-pool': typeof ApiMcpPoolRoute
   '/api/mcp-status': typeof ApiMcpStatusRoute
   '/api/sandbox-triage': typeof ApiSandboxTriageRoute
+  '/api/sqlite-persistent-chat': typeof ApiSqlitePersistentChatRoute
   '/api/structured-chat': typeof ApiStructuredChatRoute
   '/api/structured-output': typeof ApiStructuredOutputRoute
   '/api/summarize': typeof ApiSummarizeRoute
@@ -391,6 +407,7 @@ export interface FileRoutesById {
   '/realtime': typeof RealtimeRoute
   '/sandboxes': typeof SandboxesRoute
   '/server-fn-chat': typeof ServerFnChatRoute
+  '/sqlite-persistence': typeof SqlitePersistenceRoute
   '/threads': typeof ThreadsRoute
   '/typesafe-tools': typeof TypesafeToolsRoute
   '/api/capability-demo': typeof ApiCapabilityDemoRoute
@@ -405,6 +422,7 @@ export interface FileRoutesById {
   '/api/mcp-pool': typeof ApiMcpPoolRoute
   '/api/mcp-status': typeof ApiMcpStatusRoute
   '/api/sandbox-triage': typeof ApiSandboxTriageRoute
+  '/api/sqlite-persistent-chat': typeof ApiSqlitePersistentChatRoute
   '/api/structured-chat': typeof ApiStructuredChatRoute
   '/api/structured-output': typeof ApiStructuredOutputRoute
   '/api/summarize': typeof ApiSummarizeRoute
@@ -440,6 +458,7 @@ export interface FileRouteTypes {
     | '/realtime'
     | '/sandboxes'
     | '/server-fn-chat'
+    | '/sqlite-persistence'
     | '/threads'
     | '/typesafe-tools'
     | '/api/capability-demo'
@@ -454,6 +473,7 @@ export interface FileRouteTypes {
     | '/api/mcp-pool'
     | '/api/mcp-status'
     | '/api/sandbox-triage'
+    | '/api/sqlite-persistent-chat'
     | '/api/structured-chat'
     | '/api/structured-output'
     | '/api/summarize'
@@ -487,6 +507,7 @@ export interface FileRouteTypes {
     | '/realtime'
     | '/sandboxes'
     | '/server-fn-chat'
+    | '/sqlite-persistence'
     | '/threads'
     | '/typesafe-tools'
     | '/api/capability-demo'
@@ -501,6 +522,7 @@ export interface FileRouteTypes {
     | '/api/mcp-pool'
     | '/api/mcp-status'
     | '/api/sandbox-triage'
+    | '/api/sqlite-persistent-chat'
     | '/api/structured-chat'
     | '/api/structured-output'
     | '/api/summarize'
@@ -534,6 +556,7 @@ export interface FileRouteTypes {
     | '/realtime'
     | '/sandboxes'
     | '/server-fn-chat'
+    | '/sqlite-persistence'
     | '/threads'
     | '/typesafe-tools'
     | '/api/capability-demo'
@@ -548,6 +571,7 @@ export interface FileRouteTypes {
     | '/api/mcp-pool'
     | '/api/mcp-status'
     | '/api/sandbox-triage'
+    | '/api/sqlite-persistent-chat'
     | '/api/structured-chat'
     | '/api/structured-output'
     | '/api/summarize'
@@ -582,6 +606,7 @@ export interface RootRouteChildren {
   RealtimeRoute: typeof RealtimeRoute
   SandboxesRoute: typeof SandboxesRoute
   ServerFnChatRoute: typeof ServerFnChatRoute
+  SqlitePersistenceRoute: typeof SqlitePersistenceRoute
   ThreadsRoute: typeof ThreadsRoute
   TypesafeToolsRoute: typeof TypesafeToolsRoute
   ApiCapabilityDemoRoute: typeof ApiCapabilityDemoRoute
@@ -596,6 +621,7 @@ export interface RootRouteChildren {
   ApiMcpPoolRoute: typeof ApiMcpPoolRoute
   ApiMcpStatusRoute: typeof ApiMcpStatusRoute
   ApiSandboxTriageRoute: typeof ApiSandboxTriageRoute
+  ApiSqlitePersistentChatRoute: typeof ApiSqlitePersistentChatRoute
   ApiStructuredChatRoute: typeof ApiStructuredChatRoute
   ApiStructuredOutputRoute: typeof ApiStructuredOutputRoute
   ApiSummarizeRoute: typeof ApiSummarizeRoute
@@ -634,6 +660,13 @@ declare module '@tanstack/react-router' {
       preLoaderRoute: typeof ThreadsRouteImport
       parentRoute: typeof rootRouteImport
     }
+    '/sqlite-persistence': {
+      id: '/sqlite-persistence'
+      path: '/sqlite-persistence'
+      fullPath: '/sqlite-persistence'
+      preLoaderRoute: typeof SqlitePersistenceRouteImport
+      parentRoute: typeof rootRouteImport
+    }
     '/server-fn-chat': {
       id: '/server-fn-chat'
       path: '/server-fn-chat'
@@ -809,6 +842,13 @@ declare module '@tanstack/react-router' {
       preLoaderRoute: typeof ApiStructuredChatRouteImport
       parentRoute: typeof rootRouteImport
     }
+    '/api/sqlite-persistent-chat': {
+      id: '/api/sqlite-persistent-chat'
+      path: '/api/sqlite-persistent-chat'
+      fullPath: '/api/sqlite-persistent-chat'
+      preLoaderRoute: typeof ApiSqlitePersistentChatRouteImport
+      parentRoute: typeof rootRouteImport
+    }
     '/api/sandbox-triage': {
       id: '/api/sandbox-triage'
       path: '/api/sandbox-triage'
@@ -950,6 +990,7 @@ const rootRouteChildren: RootRouteChildren = {
   RealtimeRoute: RealtimeRoute,
   SandboxesRoute: SandboxesRoute,
   ServerFnChatRoute: ServerFnChatRoute,
+  SqlitePersistenceRoute: SqlitePersistenceRoute,
   ThreadsRoute: ThreadsRoute,
   TypesafeToolsRoute: TypesafeToolsRoute,
   ApiCapabilityDemoRoute: ApiCapabilityDemoRoute,
@@ -964,6 +1005,7 @@ const rootRouteChildren: RootRouteChildren = {
   ApiMcpPoolRoute: ApiMcpPoolRoute,
   ApiMcpStatusRoute: ApiMcpStatusRoute,
   ApiSandboxTriageRoute: ApiSandboxTriageRoute,
+  ApiSqlitePersistentChatRoute: ApiSqlitePersistentChatRoute,
   ApiStructuredChatRoute: ApiStructuredChatRoute,
   ApiStructuredOutputRoute: ApiStructuredOutputRoute,
   ApiSummarizeRoute: ApiSummarizeRoute,
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.sqlite-persistent-chat.ts b/examples/ts-react-chat/src/routes/api.sqlite-persistent-chat.ts
new file mode 100644
index 000000000..c8c407da1
--- /dev/null
+++ b/examples/ts-react-chat/src/routes/api.sqlite-persistent-chat.ts
@@ -0,0 +1,52 @@
+import { createFileRoute } from '@tanstack/react-router'
+import {
+  chat,
+  chatParamsFromRequestBody,
+  maxIterations,
+  toServerSentEventsResponse,
+} from '@tanstack/ai'
+import { openaiText } from '@tanstack/ai-openai'
+import { withChatPersistence } from '@tanstack/ai-persistence'
+import { createChatPersistence } from '@/lib/sqlite-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.
+Keep answers short enough that the streaming behavior is easy to inspect.`
+
+const persistence = createChatPersistence()
+
+export const Route = createFileRoute('/api/sqlite-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)],
+          systemPrompts: [SYSTEM_PROMPT],
+          agentLoopStrategy: maxIterations(4),
+          messages: params.messages,
+          threadId: params.threadId,
+          runId: params.runId,
+          ...(params.resume ? { resume: params.resume } : {}),
+        })
+
+        return toServerSentEventsResponse(stream)
+      },
+    },
+  },
+})
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/sqlite-persistence.tsx b/examples/ts-react-chat/src/routes/sqlite-persistence.tsx
new file mode 100644
index 000000000..e26ee3895
--- /dev/null
+++ b/examples/ts-react-chat/src/routes/sqlite-persistence.tsx
@@ -0,0 +1,216 @@
+import { useState } from 'react'
+import { createFileRoute } from '@tanstack/react-router'
+import { fetchServerSentEvents, useChat } from '@tanstack/ai-react'
+import { localStoragePersistence } from '@tanstack/ai-client'
+import { Square } from 'lucide-react'
+import type { ChatResumeSnapshot, UIMessage } from '@tanstack/ai-client'
+
+const THREAD_ID_KEY = 'tanstack-ai:sqlite-persistence:thread-id'
+const RESUME_KEY_PREFIX = 'tanstack-ai:sqlite-persistence:resume:'
+const MESSAGES_KEY_PREFIX = 'tanstack-ai:sqlite-persistence:messages:'
+
+type StoredUIMessage = Omit<UIMessage, 'createdAt'> & {
+  createdAt?: Date | string
+}
+
+function isStoredUIMessage(value: unknown): value is StoredUIMessage {
+  return (
+    value !== null &&
+    typeof value === 'object' &&
+    'id' in value &&
+    typeof value.id === 'string' &&
+    'role' in value &&
+    (value.role === 'system' ||
+      value.role === 'user' ||
+      value.role === 'assistant') &&
+    'parts' in value &&
+    Array.isArray(value.parts) &&
+    (!('createdAt' in value) ||
+      value.createdAt instanceof Date ||
+      typeof value.createdAt === 'string')
+  )
+}
+
+function serializeJson(value: unknown): string {
+  const stringify: (input: unknown) => unknown = JSON.stringify
+  const serialized = stringify(value)
+  if (typeof serialized !== 'string') {
+    throw new TypeError('The persistence value is not JSON serializable')
+  }
+  return serialized
+}
+
+function deserializeMessages(raw: string): Array<UIMessage> {
+  const parsed: unknown = JSON.parse(raw)
+  if (!Array.isArray(parsed) || !parsed.every(isStoredUIMessage)) {
+    throw new TypeError('Stored messages are invalid')
+  }
+  return parsed.map(({ createdAt, ...message }) => ({
+    ...message,
+    ...(createdAt
+      ? {
+          createdAt:
+            createdAt instanceof Date ? createdAt : new Date(createdAt),
+        }
+      : {}),
+  }))
+}
+
+function getStableThreadId(): string {
+  if (typeof window === 'undefined') return 'sqlite-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 = localStoragePersistence<Array<UIMessage>>({
+  keyPrefix: MESSAGES_KEY_PREFIX,
+  serialize: serializeJson,
+  deserialize: deserializeMessages,
+})
+
+const resumePersistence = localStoragePersistence<ChatResumeSnapshot>({
+  keyPrefix: RESUME_KEY_PREFIX,
+  serialize: serializeJson,
+  deserialize: JSON.parse,
+})
+
+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 SqlitePersistenceRoute() {
+  const [threadId] = useState(getStableThreadId)
+  const [input, setInput] = useState('')
+
+  const { messages, sendMessage, isLoading, error, resumeState, stop, clear } =
+    useChat({
+      id: threadId,
+      threadId,
+      connection: fetchServerSentEvents('/api/sqlite-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 and wait for it to finish, then refresh to hydrate
+              the same thread from browser and SQLite state. During an active
+              request, the process-local delivery log can replay a transiently
+              dropped SSE connection.
+            </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 after it completes"
+            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('/sqlite-persistence')({
+  component: SqlitePersistenceRoute,
+})
diff --git a/examples/ts-react-chat/src/routes/threads.tsx b/examples/ts-react-chat/src/routes/threads.tsx
index 5ab90294e..b23bfdf55 100644
--- a/examples/ts-react-chat/src/routes/threads.tsx
+++ b/examples/ts-react-chat/src/routes/threads.tsx
@@ -1,7 +1,7 @@
 import { useEffect, useRef, useState } from 'react'
 import { createFileRoute } from '@tanstack/react-router'
 import { fetchServerSentEvents, useChat } from '@tanstack/ai-react'
-import { clientTools } from '@tanstack/ai-client'
+import { clientTools, localStoragePersistence } from '@tanstack/ai-client'
 import { ThinkingPart } from '@tanstack/ai-react-ui'
 import ReactMarkdown from 'react-markdown'
 import rehypeRaw from 'rehype-raw'
@@ -9,7 +9,7 @@ import rehypeSanitize from 'rehype-sanitize'
 import rehypeHighlight from 'rehype-highlight'
 import remarkGfm from 'remark-gfm'
 import { MessageSquare, Plus, Square, Trash2 } from 'lucide-react'
-import type { ChatClientPersistence, UIMessage } from '@tanstack/ai-client'
+import type { UIMessage } from '@tanstack/ai-client'
 import GuitarRecommendation from '@/components/example-GuitarRecommendation'
 import {
   addToCartToolDef,
@@ -86,41 +86,52 @@ interface ThreadMeta {
   updatedAt: number
 }
 
+type StoredUIMessage = Omit<UIMessage, 'createdAt'> & {
+  createdAt?: Date | string
+}
+
 const hasWindow = () => typeof window !== 'undefined'
 
-/**
- * Per-thread history adapter. Each thread's messages live under their own
- * namespaced key, so this satisfies the PR's `ChatClientPersistence` contract
- * (get/set/remove by id) while keeping threads isolated from each other.
- */
-const threadPersistence: ChatClientPersistence = {
-  getItem: (id) => {
-    if (!hasWindow()) return null
-    const raw = window.localStorage.getItem(THREAD_KEY_PREFIX + id)
-    if (!raw) return null
-    // `UIMessage.createdAt` is a Date that JSON.stringify turned into a string —
-    // revive it on read.
-    return (JSON.parse(raw) as Array<UIMessage>).map((message) => ({
-      ...message,
-      createdAt:
-        typeof message.createdAt === 'string'
-          ? new Date(message.createdAt)
-          : message.createdAt,
-    }))
-  },
-  setItem: (id, messages) => {
-    if (!hasWindow()) return
-    window.localStorage.setItem(
-      THREAD_KEY_PREFIX + id,
-      JSON.stringify(messages),
-    )
-  },
-  removeItem: (id) => {
-    if (!hasWindow()) return
-    window.localStorage.removeItem(THREAD_KEY_PREFIX + id)
-  },
+function isStoredUIMessage(value: unknown): value is StoredUIMessage {
+  return (
+    value !== null &&
+    typeof value === 'object' &&
+    'id' in value &&
+    typeof value.id === 'string' &&
+    'role' in value &&
+    (value.role === 'system' ||
+      value.role === 'user' ||
+      value.role === 'assistant') &&
+    'parts' in value &&
+    Array.isArray(value.parts) &&
+    (!('createdAt' in value) ||
+      value.createdAt instanceof Date ||
+      typeof value.createdAt === 'string')
+  )
+}
+
+function deserializeThreadMessages(raw: string): Array<UIMessage> {
+  const parsed: unknown = JSON.parse(raw)
+  if (!Array.isArray(parsed) || !parsed.every(isStoredUIMessage)) {
+    throw new TypeError('Stored messages are invalid')
+  }
+  return parsed.map(({ createdAt, ...message }) => ({
+    ...message,
+    ...(createdAt
+      ? {
+          createdAt:
+            createdAt instanceof Date ? createdAt : new Date(createdAt),
+        }
+      : {}),
+  }))
 }
 
+const threadPersistence = localStoragePersistence<Array<UIMessage>>({
+  keyPrefix: THREAD_KEY_PREFIX,
+  serialize: (messages) => JSON.stringify(messages),
+  deserialize: deserializeThreadMessages,
+})
+
 function readIndex(): Array<ThreadMeta> {
   if (!hasWindow()) return []
   try {
@@ -465,7 +476,7 @@ function ThreadChat({
   } = useChat({
     id: threadId,
     connection: fetchServerSentEvents('/api/tanchat'),
-    persistence: threadPersistence,
+    persistence: { client: threadPersistence },
     tools,
     body: CHAT_BODY,
     onFinish: () => onActivity(),
diff --git a/knip.json b/knip.json
index c7995c1aa..b61b6a870 100644
--- a/knip.json
+++ b/knip.json
@@ -1,6 +1,10 @@
 {
   "$schema": "https://unpkg.com/knip@5/schema.json",
-  "ignoreDependencies": ["@faker-js/faker", "@aws-sdk/client-bedrock"],
+  "ignoreDependencies": [
+    "@faker-js/faker",
+    "@aws-sdk/client-bedrock",
+    "@cloudflare/workers-types"
+  ],
   "ignoreWorkspaces": [
     "examples/**",
     "testing/**",
@@ -40,7 +44,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 +61,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/package.json b/package.json
index bbfd9e496..d23fb5591 100644
--- a/package.json
+++ b/package.json
@@ -62,6 +62,7 @@
     "@aws-sdk/client-bedrock": "^3.1057.0",
     "@changesets/changelog-github": "^0.7.0",
     "@changesets/cli": "^2.30.0",
+    "@cloudflare/workers-types": "^4.20260317.1",
     "@faker-js/faker": "^10.1.0",
     "@tanstack/eslint-config": "0.4.0",
     "@tanstack/typedoc-config": "0.3.1",
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 570f0ce22..186d5dee9 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..03a4f4aff 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'
@@ -9,9 +10,36 @@ import {
   createTextChunks,
   renderInjectChat,
 } from './test-utils'
+import type { StreamChunk } from '@tanstack/ai/client'
+import type {
+  ConnectConnectionAdapter,
+  RunAgentInputContext,
+} from '@tanstack/ai-client'
 
 const tick = () => new Promise((r) => setTimeout(r, 0))
 
+/**
+ * A connect adapter that records the `runContext` of each connect and echoes a
+ * success terminal for the interrupted run so a resume clears cleanly.
+ */
+function recordingResumeAdapter() {
+  const contexts: Array<RunAgentInputContext | undefined> = []
+  const adapter: ConnectConnectionAdapter = {
+    // eslint-disable-next-line @typescript-eslint/require-await
+    async *connect(_messages, _data, _signal, runContext) {
+      contexts.push(runContext)
+      yield {
+        type: EventType.RUN_FINISHED,
+        runId: runContext?.runId ?? 'run-1',
+        threadId: runContext?.threadId ?? 'thread-1',
+        timestamp: Date.now(),
+        outcome: { type: 'success' },
+      } as StreamChunk
+    },
+  }
+  return { adapter, contexts }
+}
+
 describe('injectChat', () => {
   it('initializes with default state', () => {
     const adapter = createMockConnectionAdapter()
@@ -120,6 +148,120 @@ 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' })]),
+    )
+  })
+
+  it('hydrates pending interrupts from initialResumeSnapshot and blocks fresh input', async () => {
+    const adapter = createMockConnectionAdapter()
+    const { result } = renderInjectChat({
+      connection: adapter,
+      threadId: 'thread-1',
+      initialResumeSnapshot: {
+        resumeState: { threadId: 'thread-1', runId: 'run-1' },
+        pendingInterrupts: [
+          {
+            id: 'interrupt-tool-1',
+            reason: 'client_tool_input',
+            toolCallId: 'tool-call-1',
+          },
+        ],
+      },
+    })
+
+    // The hydrated interrupt is live: a normal send is rejected until it is
+    // resolved. This is the observable proof that the snapshot hydrated.
+    await expect(result.sendMessage('blocked')).rejects.toThrow(
+      'pending interrupts',
+    )
+  })
+
+  it('resolves an interrupt hydrated from initialResumeSnapshot using its run context', async () => {
+    const { adapter, contexts } = recordingResumeAdapter()
+    const onResumeStateChange = vi.fn()
+    const { result } = renderInjectChat({
+      connection: adapter,
+      threadId: 'thread-1',
+      onResumeStateChange,
+      initialResumeSnapshot: {
+        resumeState: { threadId: 'thread-1', runId: 'run-1' },
+        pendingInterrupts: [
+          {
+            id: 'interrupt-tool-1',
+            reason: 'client_tool_input',
+            toolCallId: 'tool-call-1',
+          },
+        ],
+      },
+    })
+
+    await result.addToolResult({
+      toolCallId: 'tool-call-1',
+      tool: 'lookup',
+      output: { answer: 42 },
+    })
+
+    // The reconnect reuses the hydrated thread/run ids and forwards the
+    // resolved interrupt as a resume entry — only possible if the snapshot's
+    // resumeState + pending interrupt hydrated into the client.
+    expect(contexts[0]?.threadId).toBe('thread-1')
+    expect(contexts[0]?.runId).toBe('run-1')
+    expect(contexts[0]?.resume).toEqual([
+      {
+        interruptId: 'interrupt-tool-1',
+        status: 'resolved',
+        payload: { answer: 42 },
+      },
+    ])
+    // Resolution clears the resume state, forwarded to onResumeStateChange.
+    expect(onResumeStateChange).toHaveBeenLastCalledWith(null, [])
+  })
+})
+
 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/package.json b/packages/ai-client/package.json
index 37dfbd1b2..05f5c7af2 100644
--- a/packages/ai-client/package.json
+++ b/packages/ai-client/package.json
@@ -68,6 +68,7 @@
   "devDependencies": {
     "@standard-schema/spec": "^1.1.0",
     "@vitest/coverage-v8": "4.0.14",
+    "fake-indexeddb": "^6.2.5",
     "vite": "^7.3.3",
     "zod": "^4.2.0"
   }
diff --git a/packages/ai-client/src/chat-client.ts b/packages/ai-client/src/chat-client.ts
index d5ed91a8b..af1e2ee74 100644
--- a/packages/ai-client/src/chat-client.ts
+++ b/packages/ai-client/src/chat-client.ts
@@ -12,11 +12,13 @@ import {
   getChunkRunId,
   normalizeConnectionAdapter,
 } from './connection-adapters'
-import { ChatPersistor } from './client-persistor'
+import { ChatPersistenceController } from './chat-persistence-controller'
+import { ClearedStreamTracker } from './cleared-stream-tracker'
 import type {
   AnyClientTool,
   ContentPart,
   ModelMessage,
+  RunAgentResumeItem,
   StreamChunk,
 } from '@tanstack/ai/client'
 import type {
@@ -36,6 +38,9 @@ import type {
   ChatClientOptions,
   ChatClientState,
   ChatFetcher,
+  ChatPendingInterrupt,
+  ChatResumeSnapshot,
+  ChatResumeState,
   ConnectionStatus,
   MessagePart,
   MultimodalContent,
@@ -59,6 +64,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,
@@ -97,11 +106,48 @@ export class ChatClient<
   private connection: SubscribeConnectionAdapter
   private readonly uniqueId: string
   private readonly threadId: string
-  // All persistence concerns (hydrate / save / clear, plus suppression of late
-  // 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 persistenceController: ChatPersistenceController<TTools>
+  // Whether a server-persistence resume adapter is configured. A resume that
+  // sends an EMPTY `messages` array relies on the server reconstructing the
+  // interrupted run's transcript (and translating the raw `resume` entries into
+  // approvals / client-tool results) from its own state store — which only
+  // happens when server-side persistence is active. When it is NOT, the server
+  // is stateless across requests, so the client must re-send its own transcript
+  // (with the approval-responded tool-call parts) on resume; otherwise the run
+  // continues with no history and no way to apply the decision. The presence of
+  // a `persistence.server` adapter is the app's declaration that run state is
+  // durable server-side, so it gates the no-history optimization.
+  private readonly hasServerResumePersistence: boolean
+  private readonly clearedStreamTracker = new ClearedStreamTracker()
+  // 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 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
+  // Set when a resume request fails at the connection layer. The connect-wrapper
+  // synthesizes a RUN_ERROR for that runId which the subscription loop would
+  // otherwise use to clear interrupt state — but a connection failure leaves the
+  // interrupt pending server-side, so this run's terminal RUN_ERROR must not
+  // clear it. Consumed once by observeInterruptState.
+  private connectFailureResumeRunId: string | 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
@@ -159,6 +205,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 +220,7 @@ 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) {
-      this.persistor = new ChatPersistor(
-        options.persistence,
-        this.uniqueId,
-        (messages) => this.processor.setMessages(messages),
-      )
-    }
+    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,14 +259,53 @@ export class ChatClient<
           options.onConnectionStatusChange || (() => {}),
         onSessionGeneratingChange:
           options.onSessionGeneratingChange || (() => {}),
+        onResumeStateChange: options.onResumeStateChange || (() => {}),
         onCustomEvent: options.onCustomEvent || (() => {}),
       },
     }
 
+    this.hasServerResumePersistence = Boolean(options.persistence?.server)
+
+    this.persistenceController = new ChatPersistenceController({
+      chatId: this.uniqueId,
+      threadId: this.threadId,
+      messageAdapter: options.persistence?.client,
+      resumeAdapter: options.persistence?.server,
+      applyMessages: (messages) => this.processor.setMessages(messages),
+      applyResumeSnapshot: (snapshot) => {
+        if (!this.isValidResumeSnapshot(snapshot)) {
+          this.reportServerPersistenceError(
+            new Error('Ignored malformed resume snapshot from persistence.'),
+          )
+          return
+        }
+        this.applyResumeSnapshot(snapshot)
+        this.notifyResumeStateChange()
+      },
+      canHydrateResume: () => this.lastResume === null,
+      reportResumeError: (error) => this.reportServerPersistenceError(error),
+      reportPersistenceError: (error) =>
+        this.reportClientPersistenceError(error),
+    })
+
+    const storedResumeSnapshot = options.initialResumeSnapshot
+      ? undefined
+      : this.persistenceController.readInitialResumeSnapshot()
+    const resumeSnapshot = options.initialResumeSnapshot ?? storedResumeSnapshot
+    if (resumeSnapshot && !(resumeSnapshot instanceof Promise)) {
+      if (this.isValidResumeSnapshot(resumeSnapshot)) {
+        this.applyResumeSnapshot(resumeSnapshot)
+      } else {
+        this.reportServerPersistenceError(
+          new Error('Ignored malformed resume snapshot from persistence.'),
+        )
+      }
+    }
+
     // Create StreamProcessor with event handlers.
     // Use conditional spreads so we don't pass `undefined` into
     // `StreamProcessorOptions` fields under `exactOptionalPropertyTypes`.
-    const persistedMessages = this.persistor?.readInitial()
+    const persistedMessages = this.persistenceController.readInitialMessages()
     const initialMessages = Array.isArray(persistedMessages)
       ? persistedMessages
       : options.initialMessages
@@ -234,7 +317,7 @@ export class ChatClient<
       ...(initialMessages ? { initialMessages } : {}),
       events: {
         onMessagesChange: (messages: Array<UIMessage>) => {
-          this.persistor?.notifyMessagesChanged(messages)
+          this.persistenceController.messagesChanged(messages)
           this.callbacksRef.current.onMessagesChange(messages)
         },
         onStreamStart: () => {
@@ -432,7 +515,81 @@ export class ChatClient<
       },
     })
 
-    this.persistor?.hydrateAsync(persistedMessages)
+    this.persistenceController.hydrateMessages(persistedMessages)
+    if (!options.initialResumeSnapshot) {
+      this.persistenceController.hydrateResumeSnapshot(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 {
+    this.reportPersistenceError(
+      error,
+      'Server persistence adapter error (non-fatal):',
+    )
+  }
+
+  /**
+   * Route a caught client (message) persistence error to the same observable
+   * sink as server persistence. Message persistence is best-effort — a failing
+   * message adapter (corrupt stored JSON, a quota-exceeded write, etc.) must
+   * never break chat — but the failure is no longer swallowed silently: it
+   * reaches the consumer's `onError` when provided, otherwise `console.warn`.
+   */
+  private reportClientPersistenceError(error: unknown): void {
+    this.reportPersistenceError(
+      error,
+      'Message persistence adapter error (non-fatal):',
+    )
+  }
+
+  private reportPersistenceError(error: unknown, warning: string): void {
+    const normalized = error instanceof Error ? error : new Error(String(error))
+    if (this.hasUserOnError) {
+      this.callbacksRef.current.onError(normalized)
+    } else {
+      console.warn(`[TanStack AI] ${warning}`, normalized)
+    }
+  }
+
+  private applyResumeSnapshot(snapshot: ChatResumeSnapshot): void {
+    this.lastResume = { ...snapshot.resumeState }
+    this.pendingInterrupts = [...(snapshot.pendingInterrupts ?? [])]
+    this.pendingInterruptRunId =
+      this.pendingInterrupts.length > 0 ? this.lastResume.runId : null
+  }
+
+  /**
+   * Structural guard for a persisted resume snapshot. A parseable-but-garbage
+   * blob (e.g. `{}` or a snapshot missing `resumeState`) must not flow into
+   * `applyResumeSnapshot`, where `{ ...undefined }` would seed a bogus
+   * `lastResume` of `{ threadId: undefined, runId: undefined }` and strand the
+   * client on an unanswerable resume. Anything that fails this check is treated
+   * as "no snapshot" and reported via the resume error sink.
+   */
+  private isValidResumeSnapshot(
+    snapshot: unknown,
+  ): snapshot is ChatResumeSnapshot {
+    if (typeof snapshot !== 'object' || snapshot === null) {
+      return false
+    }
+    const record = snapshot as Record<string, unknown>
+    const resumeState = record.resumeState
+    if (typeof resumeState !== 'object' || resumeState === null) {
+      return false
+    }
+    const state = resumeState as Record<string, unknown>
+    if (typeof state.threadId !== 'string' || typeof state.runId !== 'string') {
+      return false
+    }
+    const { pendingInterrupts } = record
+    return pendingInterrupts === undefined || Array.isArray(pendingInterrupts)
   }
 
   mountDevtools(): void {
@@ -445,17 +602,19 @@ 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.clearedStreamTracker.takeRunlessRunId()
     if (!runId) return
     this.activeRunIds.delete(runId)
     this.setSessionGenerating(this.activeRunIds.size > 0)
-    this.resolveProcessing()
+    if (!getChunkRunId(chunk)) {
+      this.resolveProcessing()
+    }
   }
 
   private updateRunLifecycle(
@@ -464,8 +623,13 @@ 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.clearedStreamTracker.onRunStarted(chunkRunId)
       this.setSessionGenerating(true)
       return
     }
@@ -477,11 +641,11 @@ export class ChatClient<
     const runId = getChunkRunId(chunk)
     if (runId) {
       this.activeRunIds.delete(runId)
-      this.persistor?.onRunSettled(runId)
+      this.clearedStreamTracker.onRunSettled(runId)
     } else if (chunk.type === 'RUN_ERROR') {
       // RUN_ERROR without runId is a session-level error; clear all runs.
       this.activeRunIds.clear()
-      this.persistor?.onSessionRunError()
+      this.clearedStreamTracker.onSessionRunError()
     }
     this.setSessionGenerating(this.activeRunIds.size > 0)
     if (options?.resolveProcessing !== false) {
@@ -489,6 +653,121 @@ 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
+    }
+
+    // A connection failure during a resume produced this run's synthetic
+    // RUN_ERROR. The run is not actually terminal server-side (we never reached
+    // it), so leave interrupt state intact and let the user retry. Consume the
+    // marker so a later genuine terminal event can still clear the state.
+    if (
+      chunk.type === 'RUN_ERROR' &&
+      runId &&
+      this.connectFailureResumeRunId === runId
+    ) {
+      this.connectFailureResumeRunId = null
+      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
+  }
+
+  /**
+   * The interrupts (approval requests / client-tool input requests) the current
+   * run is waiting on, or an empty array when nothing is pending. Pair each with
+   * a `RunAgentResumeItem` and hand them to `resumeInterrupts()` to continue.
+   */
+  getPendingInterrupts(): Array<ChatPendingInterrupt> {
+    return [...this.pendingInterrupts]
+  }
+
+  /**
+   * Continue an interrupted run by sending resume decisions for its pending
+   * interrupts. `resume` is one `RunAgentResumeItem` per interrupt; `state`
+   * targets a specific run (defaults to the tracked `getResumeState()`, e.g.
+   * after a reload seeded from persistence).
+   *
+   * Resolves to `true` when a resume stream was started, `false` when there is
+   * nothing to resume (no target run) or a request is already in flight. Most
+   * apps never call this directly — `addToolResult` / `addToolApprovalResponse`
+   * drive it automatically once every pending interrupt has been answered.
+   */
+  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,9 +803,25 @@ export class ChatClient<
     this.devtoolsBridge.emitSnapshot()
   }
 
-  private resetSessionGenerating(): void {
+  private notifyResumeStateChange(): void {
+    const resumeState = this.getResumeState()
+    const pendingInterrupts = this.getPendingInterrupts()
+    this.persistenceController.persistResumeSnapshot(
+      resumeState ? { resumeState, pendingInterrupts } : null,
+    )
+    this.callbacksRef.current.onResumeStateChange(
+      resumeState,
+      pendingInterrupts,
+    )
+  }
+
+  private resetSessionGenerating(options?: {
+    preserveClearedStreamTracking?: boolean
+  }): void {
     this.activeRunIds.clear()
-    this.persistor?.resetIgnored()
+    if (!options?.preserveClearedStreamTracking) {
+      this.clearedStreamTracker.resetActiveRuns()
+    }
     this.setSessionGenerating(false)
   }
 
@@ -675,14 +970,13 @@ export class ChatClient<
       if (this.connectionStatus === 'connecting') {
         this.setConnectionStatus('connected')
       }
-      const shouldIgnore = this.persistor?.shouldIgnoreChunk(chunk) ?? false
+      const shouldIgnore = this.clearedStreamTracker.shouldIgnoreChunk(chunk)
       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 +990,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 +1059,7 @@ export class ChatClient<
    *     ],
    *     id: 'custom-message-id'
    *   },
-   *   { model: 'gpt-4-audio' }
+   *   { model: 'gpt-5.5' }
    * )
    * ```
    */
@@ -777,6 +1072,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 +1112,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 +1159,36 @@ 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,
+    )
+    // Snapshot the interrupt state before sending. A connection failure during
+    // a resume synthesizes a RUN_ERROR (see the connect-wrapper) that the
+    // subscription loop treats as a terminal event and uses to CLEAR
+    // lastResume/pendingInterrupts — even though the interrupt is still pending
+    // server-side. Capture it here so the connect-failure catch can restore it
+    // and keep the user able to retry.
+    const resumeInterruptSnapshot = isResumeRequest
+      ? {
+          lastResume: this.lastResume ? { ...this.lastResume } : null,
+          pendingInterrupts: [...this.pendingInterrupts],
+          pendingInterruptRunId: this.pendingInterruptRunId,
+        }
+      : null
+    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')
@@ -873,8 +1206,14 @@ export class ChatClient<
     let runTerminalEventEmitted = false
 
     try {
-      // Get UIMessages with parts (preserves approval state and client tool results)
-      const messages = this.processor.getMessages()
+      // Get UIMessages with parts (preserves approval state and client tool results).
+      // On resume we omit the transcript ONLY when server persistence can rebuild
+      // it; a stateless server needs the client's transcript (whose tool-call
+      // parts now carry the approval-responded decision) to continue the run.
+      const messages =
+        isResumeRequest && this.hasServerResumePersistence
+          ? []
+          : this.processor.getMessages()
       const clientTools = new Map(this.clientToolsRef.current)
       const runtimeContext = this.context
 
@@ -935,7 +1274,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 +1284,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 +1303,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
 
@@ -1009,6 +1354,26 @@ export class ChatClient<
           return false
         }
         if (generation === this.streamGeneration) {
+          if (isResumeRequest && resumeInterruptSnapshot) {
+            // A connection failure means the resume never reached the server,
+            // so the interrupt is still pending there. Restore both the
+            // pending-resume slots (consumed at the top of this method) and the
+            // interrupt state (which the synthetic RUN_ERROR just cleared via
+            // the subscription loop) so the user isn't stranded and a follow-up
+            // `resumeInterrupts()` retries the same run.
+            this.lastResume = resumeInterruptSnapshot.lastResume
+            this.pendingInterrupts = resumeInterruptSnapshot.pendingInterrupts
+            this.pendingInterruptRunId =
+              resumeInterruptSnapshot.pendingInterruptRunId
+            this.pendingResumeThreadId = resumeThreadId
+            this.pendingResumeRunId = resumeRunId
+            this.pendingResumeItems = resumeItems
+            // Mark this run so the synthetic RUN_ERROR the connect-wrapper
+            // pushed can't clear the interrupt state we just restored, whether
+            // the subscription loop processes it before or after this catch.
+            this.connectFailureResumeRunId = runId
+            this.notifyResumeStateChange()
+          }
           this.reportStreamError(err)
           if (activeDevtoolsRunId) {
             this.devtoolsBridge.emitRunLifecycle(
@@ -1161,27 +1526,38 @@ export class ChatClient<
   }
 
   /**
-   * Clear all messages
+   * Reset the chat to an empty state. Beyond clearing all messages this also
+   * cancels any in-flight stream, stops shared session-generating tracking,
+   * discards resume state (pending interrupts / tracked run) and deletes the
+   * persisted message and resume snapshots, and clears the current error. Use
+   * it to start a fresh conversation, not merely to hide the transcript.
    */
   clear(): void {
-    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()
+    const hadLocalStream = this.abortController !== null
+    this.clearedStreamTracker.snapshotClear({
+      messages: this.processor.getMessages(),
+      activeRunIds: this.activeRunIds,
+      currentRunId: this.currentRunId,
+    })
+    // Suppress persisting the empty snapshot that clearMessages emits, then
+    // remove the stored conversation outright.
+    this.persistenceController.prepareMessagesClear()
+    if (this.isLoading || hadLocalStream) {
+      this.cancelInFlightStream({ setReadyStatus: true })
+      this.resetSessionGenerating({ preserveClearedStreamTracking: true })
+    } else if (this.activeRunIds.size > 0) {
+      this.resetSessionGenerating({ preserveClearedStreamTracking: true })
     }
     this.processor.clearMessages()
-    this.persistor?.remove()
+    this.persistenceController.removeMessages()
+    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 +1610,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 +1666,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 +1696,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 +1724,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 +1943,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 +1957,17 @@ 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.persistenceController.dispose()
     this.unsubscribe()
     this.devtoolsBridge.dispose()
     this.devtoolsMounted = false
diff --git a/packages/ai-client/src/chat-persistence-controller.ts b/packages/ai-client/src/chat-persistence-controller.ts
new file mode 100644
index 000000000..1e158be20
--- /dev/null
+++ b/packages/ai-client/src/chat-persistence-controller.ts
@@ -0,0 +1,298 @@
+import type { AnyClientTool } from '@tanstack/ai/client'
+import type {
+  ChatClientPersistence,
+  ChatResumeSnapshot,
+  ChatServerPersistence,
+  UIMessage,
+} from './types'
+
+type MaybePromise<T> = T | Promise<T>
+
+interface ChatPersistenceControllerOptions<
+  TTools extends ReadonlyArray<AnyClientTool>,
+> {
+  chatId: string
+  threadId: string
+  messageAdapter?: ChatClientPersistence<TTools>
+  resumeAdapter?: ChatServerPersistence
+  applyMessages: (messages: Array<UIMessage<TTools>>) => void
+  applyResumeSnapshot: (snapshot: ChatResumeSnapshot) => void
+  canHydrateResume: () => boolean
+  reportResumeError: (error: unknown) => void
+  reportPersistenceError: (error: unknown) => void
+}
+
+function isPromiseLike<T>(value: unknown): value is PromiseLike<T> {
+  return (
+    typeof value === 'object' &&
+    value !== null &&
+    'then' in value &&
+    typeof value.then === 'function'
+  )
+}
+
+/** Internal persistence coordinator used by ChatClient. */
+export class ChatPersistenceController<
+  TTools extends ReadonlyArray<AnyClientTool> = ReadonlyArray<AnyClientTool>,
+> {
+  private messageHydrationGeneration = 0
+  private messageOperationGeneration = 0
+  private readonly messageOperations: Array<
+    () => MaybePromise<void | undefined>
+  > = []
+  private messageOperationPending = false
+  private skipNextMessagePersist = false
+  // Set when the initial message read fails (sync throw or async rejection).
+  // While set, no `setItem` is attempted so a transient read failure — e.g. a
+  // corrupt stored JSON blob that throws inside `getItem`/`deserialize` — can't
+  // clobber the on-disk history with the fresh (empty) session. Cleared only by
+  // an explicit user reset (`removeMessages`, i.e. `clear()`), which deletes the
+  // stored copy outright and makes subsequent writes safe again.
+  private messageWritesSuspended = false
+
+  private resumeGeneration = 0
+  private desiredResumeSnapshot: ChatResumeSnapshot | null = null
+  private resumeOperationPending = false
+  private disposed = false
+
+  constructor(
+    private readonly options: ChatPersistenceControllerOptions<TTools>,
+  ) {}
+
+  readInitialMessages():
+    | Array<UIMessage<TTools>>
+    | null
+    | undefined
+    | Promise<Array<UIMessage<TTools>> | null | undefined> {
+    try {
+      return this.options.messageAdapter?.getItem(this.options.chatId)
+    } catch (error) {
+      // A failed read must not silently start an empty chat AND then let the
+      // next `messagesChanged` overwrite the stored history. Report it and
+      // suspend writes until an explicit reset.
+      this.options.reportPersistenceError(error)
+      this.messageWritesSuspended = true
+      return undefined
+    }
+  }
+
+  hydrateMessages(
+    stored:
+      | Array<UIMessage<TTools>>
+      | null
+      | undefined
+      | Promise<Array<UIMessage<TTools>> | null | undefined>,
+  ): void {
+    if (!isPromiseLike<Array<UIMessage<TTools>> | null | undefined>(stored)) {
+      return
+    }
+
+    const generation = this.messageHydrationGeneration
+    void Promise.resolve(stored)
+      .then((messages) => {
+        if (
+          !this.disposed &&
+          Array.isArray(messages) &&
+          generation === this.messageHydrationGeneration
+        ) {
+          this.options.applyMessages(messages)
+        }
+      })
+      .catch((error: unknown) => {
+        // An async read that rejects (e.g. IndexedDB open failure, or a
+        // deserialize throw in a Promise-returning adapter) is the same hazard
+        // as a sync throw: report it and suspend writes so we don't overwrite
+        // the stored history with the fresh session.
+        this.options.reportPersistenceError(error)
+        this.messageWritesSuspended = true
+      })
+  }
+
+  messagesChanged(messages: Array<UIMessage<TTools>>): void {
+    this.messageHydrationGeneration++
+    if (this.disposed || !this.options.messageAdapter) {
+      return
+    }
+    if (this.skipNextMessagePersist) {
+      this.skipNextMessagePersist = false
+      return
+    }
+    if (this.messageWritesSuspended) {
+      // Initial read failed; refuse to persist so we can't destroy the stored
+      // copy. A later reload with working storage can still recover it.
+      return
+    }
+
+    const generation = this.messageOperationGeneration
+    const snapshot = [...messages]
+    this.runMessageOperation(() => {
+      if (this.disposed || generation !== this.messageOperationGeneration) {
+        return
+      }
+      return this.options.messageAdapter?.setItem(this.options.chatId, snapshot)
+    })
+  }
+
+  prepareMessagesClear(): void {
+    this.skipNextMessagePersist = true
+  }
+
+  removeMessages(): void {
+    if (this.disposed || !this.options.messageAdapter) {
+      return
+    }
+    // An explicit reset (clear()) deletes the stored copy outright, so there is
+    // nothing left to protect — resume normal persistence for the fresh chat.
+    this.messageWritesSuspended = false
+
+    const generation = ++this.messageOperationGeneration
+    this.runMessageOperation(() => {
+      if (this.disposed || generation !== this.messageOperationGeneration) {
+        return
+      }
+      return this.options.messageAdapter?.removeItem(this.options.chatId)
+    })
+  }
+
+  readInitialResumeSnapshot():
+    | ChatResumeSnapshot
+    | null
+    | undefined
+    | Promise<ChatResumeSnapshot | null | undefined> {
+    try {
+      return this.options.resumeAdapter?.getItem(this.options.threadId)
+    } catch (error) {
+      this.options.reportResumeError(error)
+      return undefined
+    }
+  }
+
+  hydrateResumeSnapshot(
+    stored:
+      | ChatResumeSnapshot
+      | null
+      | undefined
+      | Promise<ChatResumeSnapshot | null | undefined>,
+  ): void {
+    if (!isPromiseLike<ChatResumeSnapshot | null | undefined>(stored)) {
+      return
+    }
+
+    const generation = this.resumeGeneration
+    void Promise.resolve(stored)
+      .then((snapshot) => {
+        if (
+          snapshot &&
+          !this.disposed &&
+          generation === this.resumeGeneration &&
+          this.options.canHydrateResume()
+        ) {
+          this.options.applyResumeSnapshot(snapshot)
+        }
+      })
+      .catch((error: unknown) => {
+        this.options.reportResumeError(error)
+      })
+  }
+
+  persistResumeSnapshot(snapshot: ChatResumeSnapshot | null): void {
+    this.resumeGeneration++
+    this.desiredResumeSnapshot = snapshot
+      ? {
+          resumeState: { ...snapshot.resumeState },
+          pendingInterrupts: [...(snapshot.pendingInterrupts ?? [])],
+        }
+      : null
+    this.flushResumeSnapshot()
+  }
+
+  dispose(): void {
+    this.disposed = true
+    this.messageHydrationGeneration++
+    this.messageOperationGeneration++
+    this.resumeGeneration++
+  }
+
+  private runMessageOperation(
+    operation: () => MaybePromise<void | undefined>,
+  ): void {
+    this.messageOperations.push(operation)
+    this.drainMessageOperations()
+  }
+
+  private drainMessageOperations(): void {
+    while (!this.messageOperationPending) {
+      const operation = this.messageOperations.shift()
+      if (!operation) {
+        return
+      }
+
+      this.messageOperationPending = true
+      try {
+        const result = operation()
+        if (isPromiseLike(result)) {
+          void Promise.resolve(result)
+            .catch((error: unknown) => {
+              // Best-effort: a write failure must not break chat, but it must
+              // not vanish either.
+              this.options.reportPersistenceError(error)
+            })
+            .then(() => {
+              this.messageOperationPending = false
+              this.drainMessageOperations()
+            })
+          return
+        }
+        this.messageOperationPending = false
+      } catch (error) {
+        this.messageOperationPending = false
+        this.options.reportPersistenceError(error)
+      }
+    }
+  }
+
+  private flushResumeSnapshot(): void {
+    if (
+      this.disposed ||
+      this.resumeOperationPending ||
+      !this.options.resumeAdapter
+    ) {
+      return
+    }
+
+    const generation = this.resumeGeneration
+    const snapshot = this.desiredResumeSnapshot
+    this.resumeOperationPending = true
+
+    let result: void | Promise<void>
+    try {
+      result = snapshot
+        ? this.options.resumeAdapter.setItem(this.options.threadId, snapshot)
+        : this.options.resumeAdapter.removeItem(this.options.threadId)
+    } catch (error) {
+      this.options.reportResumeError(error)
+      this.finishResumeOperation(generation)
+      return
+    }
+
+    if (!isPromiseLike(result)) {
+      this.finishResumeOperation(generation)
+      return
+    }
+
+    void Promise.resolve(result)
+      .catch((error: unknown) => {
+        this.options.reportResumeError(error)
+      })
+      .then(() => {
+        this.finishResumeOperation(generation)
+      })
+  }
+
+  private finishResumeOperation(generation: number): void {
+    this.resumeOperationPending = false
+    if (!this.disposed && generation !== this.resumeGeneration) {
+      this.flushResumeSnapshot()
+    }
+  }
+}
diff --git a/packages/ai-client/src/cleared-stream-tracker.ts b/packages/ai-client/src/cleared-stream-tracker.ts
new file mode 100644
index 000000000..e9471ad53
--- /dev/null
+++ b/packages/ai-client/src/cleared-stream-tracker.ts
@@ -0,0 +1,151 @@
+import { getChunkRunId } from './connection-adapters'
+import type { StreamChunk } from '@tanstack/ai/client'
+import type { UIMessage } from './types'
+
+function getChunkToolCallId(chunk: StreamChunk): string | undefined {
+  return 'toolCallId' in chunk && typeof chunk.toolCallId === 'string'
+    ? chunk.toolCallId
+    : undefined
+}
+
+function getChunkMessageId(chunk: StreamChunk): string | undefined {
+  return 'messageId' in chunk && typeof chunk.messageId === 'string'
+    ? chunk.messageId
+    : undefined
+}
+
+function getChunkParentMessageId(chunk: StreamChunk): string | undefined {
+  return 'parentMessageId' in chunk && typeof chunk.parentMessageId === 'string'
+    ? chunk.parentMessageId
+    : undefined
+}
+
+/** Tracks stream chunks that must be ignored after the owning chat is cleared. */
+export class ClearedStreamTracker {
+  private readonly clearedMessageIds = new Set<string>()
+  private readonly clearedRunIds = new Set<string>()
+  private readonly ignoredActiveRunIds = new Set<string>()
+  private readonly clearedToolCallIds = new Set<string>()
+  private currentRunlessRunId: string | null = null
+
+  snapshotClear(context: {
+    messages: Array<UIMessage>
+    activeRunIds: Set<string>
+    currentRunId: string | null
+  }): void {
+    for (const message of context.messages) {
+      this.clearedMessageIds.add(message.id)
+    }
+    for (const runId of context.activeRunIds) {
+      this.clearedRunIds.add(runId)
+      this.ignoredActiveRunIds.add(runId)
+    }
+    if (context.currentRunId) {
+      this.clearedRunIds.add(context.currentRunId)
+      this.ignoredActiveRunIds.add(context.currentRunId)
+    }
+  }
+
+  shouldIgnoreChunk(chunk: StreamChunk): boolean {
+    const runId = getChunkRunId(chunk)
+    if (runId && this.clearedRunIds.has(runId)) {
+      if (chunk.type === 'RUN_STARTED') {
+        this.ignoredActiveRunIds.add(runId)
+        this.currentRunlessRunId = runId
+      }
+      this.markIgnoredChunkIds(chunk)
+      return true
+    }
+
+    if (runId && this.ignoredActiveRunIds.has(runId)) {
+      this.markIgnoredChunkIds(chunk)
+      return true
+    }
+
+    if (this.isRunlessChunkFromIgnoredRun(chunk)) {
+      this.markIgnoredChunkIds(chunk)
+      return true
+    }
+
+    const toolCallId = getChunkToolCallId(chunk)
+    if (toolCallId && this.clearedToolCallIds.has(toolCallId)) {
+      return true
+    }
+
+    const parentMessageId = getChunkParentMessageId(chunk)
+    if (parentMessageId && this.clearedMessageIds.has(parentMessageId)) {
+      if (toolCallId) {
+        this.clearedToolCallIds.add(toolCallId)
+      }
+      return true
+    }
+
+    const messageId = getChunkMessageId(chunk)
+    return Boolean(messageId && this.clearedMessageIds.has(messageId))
+  }
+
+  onRunStarted(runId: string): void {
+    this.currentRunlessRunId = runId
+  }
+
+  onRunSettled(runId: string): void {
+    this.ignoredActiveRunIds.delete(runId)
+    this.clearedRunIds.delete(runId)
+    if (this.currentRunlessRunId === runId) {
+      this.currentRunlessRunId =
+        this.ignoredActiveRunIds.values().next().value ?? null
+    }
+  }
+
+  onSessionRunError(): void {
+    this.ignoredActiveRunIds.clear()
+    this.currentRunlessRunId = null
+  }
+
+  resetActiveRuns(): void {
+    this.ignoredActiveRunIds.clear()
+    this.currentRunlessRunId = null
+  }
+
+  takeRunlessRunId(): string | null {
+    const runId = this.currentRunlessRunId
+    if (!runId) return null
+    this.ignoredActiveRunIds.delete(runId)
+    this.clearedRunIds.delete(runId)
+    this.currentRunlessRunId =
+      this.ignoredActiveRunIds.values().next().value ?? null
+    return runId
+  }
+
+  private markIgnoredChunkIds(chunk: StreamChunk): void {
+    const messageId = getChunkMessageId(chunk)
+    if (messageId) {
+      this.clearedMessageIds.add(messageId)
+    }
+    const toolCallId = getChunkToolCallId(chunk)
+    if (toolCallId) {
+      this.clearedToolCallIds.add(toolCallId)
+    }
+  }
+
+  private isRunlessChunkFromIgnoredRun(chunk: StreamChunk): boolean {
+    const runId = getChunkRunId(chunk)
+    if (runId || !this.currentRunlessRunId) return false
+    if (
+      !this.ignoredActiveRunIds.has(this.currentRunlessRunId) &&
+      !this.clearedRunIds.has(this.currentRunlessRunId)
+    ) {
+      return false
+    }
+    return (
+      chunk.type === 'TEXT_MESSAGE_START' ||
+      chunk.type === 'TEXT_MESSAGE_CONTENT' ||
+      chunk.type === 'TOOL_CALL_START' ||
+      chunk.type === 'TOOL_CALL_ARGS' ||
+      chunk.type === 'TOOL_CALL_END' ||
+      chunk.type === 'TOOL_CALL_RESULT' ||
+      chunk.type === 'MESSAGES_SNAPSHOT' ||
+      chunk.type === 'RUN_ERROR'
+    )
+  }
+}
diff --git a/packages/ai-client/src/client-persistor.ts b/packages/ai-client/src/client-persistor.ts
deleted file mode 100644
index 517aaf0a7..000000000
--- a/packages/ai-client/src/client-persistor.ts
+++ /dev/null
@@ -1,337 +0,0 @@
-import { getChunkRunId } from './connection-adapters'
-import type { StreamChunk } from '@tanstack/ai/client'
-import type { ChatClientPersistence, UIMessage } from './types'
-
-// `StreamChunk` is a discriminated union; `toolCallId` / `messageId` /
-// `parentMessageId` exist on only some members. Narrow with `in` (matching
-// `getChunkRunId`) instead of asserting a shape, so the field's real type is
-// preserved and a protocol rename can't be read past silently.
-function getChunkToolCallId(chunk: StreamChunk): string | undefined {
-  return 'toolCallId' in chunk && typeof chunk.toolCallId === 'string'
-    ? chunk.toolCallId
-    : undefined
-}
-
-function getChunkMessageId(chunk: StreamChunk): string | undefined {
-  return 'messageId' in chunk && typeof chunk.messageId === 'string'
-    ? chunk.messageId
-    : undefined
-}
-
-function getChunkParentMessageId(chunk: StreamChunk): string | undefined {
-  return 'parentMessageId' in chunk && typeof chunk.parentMessageId === 'string'
-    ? chunk.parentMessageId
-    : undefined
-}
-
-/**
- * Encapsulates everything persistence-related for `ChatClient` so the client
- * itself stays focused on streaming and message state.
- *
- * Two responsibilities live here:
- *
- * 1. **Storage orchestration** — hydrate from `getItem(id)` on creation, save to
- *    `setItem(id, messages)` on every change through an ordered write queue, and
- *    `removeItem(id)` on clear. A generation counter discards stale writes when a
- *    removal or a newer conversation supersedes an in-flight async operation.
- * 2. **Clear-during-stream suppression** — when a conversation is cleared while a
- *    stream is still producing, late chunks for the cleared run(s) must not
- *    repopulate the now-empty state. The persistor tracks the cleared ids and
- *    decides, per chunk, whether the client should ignore it.
- *
- * All adapter calls are best-effort: a throwing or rejecting adapter is swallowed
- * so storage problems never break the chat.
- */
-export class ChatPersistor {
-  // --- storage queue state ---
-  private skipNextPersist = false
-  private generation = 0
-  private queue: Promise<void> = Promise.resolve()
-  private queuePending = false
-  // Bumped on every message change; lets an in-flight async hydration detect
-  // that the message list moved on and avoid clobbering it.
-  private messagesGeneration = 0
-
-  // --- clear-during-stream suppression state ---
-  private readonly clearedMessageIds = new Set<string>()
-  private readonly clearedRunIds = new Set<string>()
-  private readonly ignoredActiveRunIds = new Set<string>()
-  private readonly clearedToolCallIds = new Set<string>()
-  private currentRunlessRunId: string | null = null
-
-  constructor(
-    private readonly adapter: ChatClientPersistence,
-    private readonly id: string,
-    private readonly applyMessages: (messages: Array<UIMessage>) => void,
-  ) {}
-
-  // ---------------------------------------------------------------------------
-  // Storage orchestration
-  // ---------------------------------------------------------------------------
-
-  /**
-   * Synchronously read the persisted messages for constructor-time hydration.
-   * Returns the raw `getItem` result (which may be a promise for async stores).
-   */
-  readInitial():
-    | Array<UIMessage>
-    | null
-    | undefined
-    | Promise<Array<UIMessage> | null | undefined> {
-    try {
-      return this.adapter.getItem(this.id)
-    } catch {
-      return undefined
-    }
-  }
-
-  /**
-   * Apply messages from an async `getItem` once it resolves, unless the message
-   * list has already changed since hydration began.
-   */
-  hydrateAsync(
-    persistedMessages:
-      | Array<UIMessage>
-      | null
-      | undefined
-      | Promise<Array<UIMessage> | null | undefined>,
-  ): void {
-    if (!(persistedMessages instanceof Promise)) {
-      return
-    }
-
-    const hydrationGeneration = this.messagesGeneration
-    persistedMessages
-      .then((messages) => {
-        if (
-          Array.isArray(messages) &&
-          this.messagesGeneration === hydrationGeneration
-        ) {
-          this.applyMessages(messages)
-        }
-      })
-      .catch(() => {
-        // Persistence adapters are best-effort and must not break chat setup.
-      })
-  }
-
-  /**
-   * 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
-   * persisted between `clearMessages()` and {@link remove}.
-   */
-  notifyMessagesChanged(messages: Array<UIMessage>): void {
-    this.messagesGeneration++
-    if (this.skipNextPersist) {
-      this.skipNextPersist = false
-      return
-    }
-    const generation = this.generation
-    const messagesSnapshot = [...messages]
-    this.runOperation(() => {
-      if (generation !== this.generation) {
-        return
-      }
-      return this.adapter.setItem(this.id, messagesSnapshot)
-    })
-  }
-
-  /** Remove the persisted conversation. Invalidates any queued writes. */
-  remove(): void {
-    const generation = ++this.generation
-    this.runOperation(() => {
-      if (generation !== this.generation) {
-        return
-      }
-      return this.adapter.removeItem(this.id)
-    })
-  }
-
-  private runOperation(operation: () => void | Promise<void>): void {
-    if (this.queuePending) {
-      const queued = this.queue.then(operation).catch(() => {
-        // Persistence adapters are best-effort and must not break chat updates.
-      })
-      this.queue = queued
-      void queued.finally(() => {
-        if (this.queue === queued) {
-          this.queuePending = false
-        }
-      })
-      return
-    }
-
-    try {
-      const result = operation()
-      if (result instanceof Promise) {
-        this.queuePending = true
-        const queued = result.catch(() => {
-          // Persistence adapters are best-effort and must not break chat updates.
-        })
-        this.queue = queued
-        void queued.finally(() => {
-          if (this.queue === queued) {
-            this.queuePending = false
-          }
-        })
-      }
-    } catch {
-      // Persistence adapters are best-effort and must not break chat updates.
-    }
-  }
-
-  // ---------------------------------------------------------------------------
-  // Clear-during-stream suppression
-  // ---------------------------------------------------------------------------
-
-  /**
-   * Capture the message/run ids that exist at the moment of a clear so chunks
-   * still arriving for them can be ignored.
-   */
-  snapshotClear(context: {
-    messages: Array<UIMessage>
-    activeRunIds: Set<string>
-    currentRunId: string | null
-  }): void {
-    for (const message of context.messages) {
-      this.clearedMessageIds.add(message.id)
-    }
-    for (const runId of context.activeRunIds) {
-      this.clearedRunIds.add(runId)
-      this.ignoredActiveRunIds.add(runId)
-    }
-    if (context.currentRunId) {
-      this.clearedRunIds.add(context.currentRunId)
-      this.ignoredActiveRunIds.add(context.currentRunId)
-    }
-  }
-
-  /** Mark that the next persisted message change (the clear itself) is skipped. */
-  beginClear(): void {
-    this.skipNextPersist = true
-  }
-
-  /** Whether a chunk belongs to cleared state and should not be processed. */
-  shouldIgnoreChunk(chunk: StreamChunk): boolean {
-    const runId = getChunkRunId(chunk)
-    if (runId && this.clearedRunIds.has(runId)) {
-      if (chunk.type === 'RUN_STARTED') {
-        this.ignoredActiveRunIds.add(runId)
-        this.currentRunlessRunId = runId
-      }
-      this.markIgnoredChunkIds(chunk)
-      return true
-    }
-
-    if (runId && this.ignoredActiveRunIds.has(runId)) {
-      this.markIgnoredChunkIds(chunk)
-      return true
-    }
-
-    if (this.isRunlessChunkFromIgnoredRun(chunk)) {
-      this.markIgnoredChunkIds(chunk)
-      return true
-    }
-
-    const toolCallId = getChunkToolCallId(chunk)
-    if (toolCallId && this.clearedToolCallIds.has(toolCallId)) {
-      return true
-    }
-
-    const parentMessageId = getChunkParentMessageId(chunk)
-    if (parentMessageId && this.clearedMessageIds.has(parentMessageId)) {
-      if (toolCallId) {
-        this.clearedToolCallIds.add(toolCallId)
-      }
-      return true
-    }
-
-    const messageId = getChunkMessageId(chunk)
-    if (!messageId) {
-      return false
-    }
-    if (this.clearedMessageIds.has(messageId)) {
-      return true
-    }
-
-    return false
-  }
-
-  /**
-   * The owning client calls this when a run starts so runless content chunks
-   * (adapters that omit `runId` on content events) can be attributed to it.
-   */
-  onRunStarted(runId: string): void {
-    this.currentRunlessRunId = runId
-  }
-
-  /** Forget a settled run, advancing the runless pointer to another ignored run. */
-  onRunSettled(runId: string): void {
-    this.ignoredActiveRunIds.delete(runId)
-    this.clearedRunIds.delete(runId)
-    if (this.currentRunlessRunId === runId) {
-      this.currentRunlessRunId =
-        this.ignoredActiveRunIds.values().next().value ?? null
-    }
-  }
-
-  /** A session-level (runId-less) RUN_ERROR clears all ignored-run tracking. */
-  onSessionRunError(): void {
-    this.ignoredActiveRunIds.clear()
-    this.currentRunlessRunId = null
-  }
-
-  /** Clear the ignored-active-run markers (mirrors a session-generating reset). */
-  resetIgnored(): void {
-    this.ignoredActiveRunIds.clear()
-  }
-
-  /**
-   * Consume the current runless run id (if any), forgetting it. Used when an
-   * ignored, runId-less RUN_ERROR drains the run the client is still tracking.
-   */
-  takeRunlessRunId(): string | null {
-    const runId = this.currentRunlessRunId
-    if (!runId) return null
-    this.ignoredActiveRunIds.delete(runId)
-    this.clearedRunIds.delete(runId)
-    // Advance to another still-ignored run (mirroring `onRunSettled`) so that
-    // when two cleared runs drain concurrently, draining one via a runId-less
-    // RUN_ERROR doesn't stop suppressing the other's runless content.
-    this.currentRunlessRunId =
-      this.ignoredActiveRunIds.values().next().value ?? null
-    return runId
-  }
-
-  private markIgnoredChunkIds(chunk: StreamChunk): void {
-    const messageId = getChunkMessageId(chunk)
-    if (messageId) {
-      this.clearedMessageIds.add(messageId)
-    }
-    const toolCallId = getChunkToolCallId(chunk)
-    if (toolCallId) {
-      this.clearedToolCallIds.add(toolCallId)
-    }
-  }
-
-  private isRunlessChunkFromIgnoredRun(chunk: StreamChunk): boolean {
-    const runId = getChunkRunId(chunk)
-    if (runId || !this.currentRunlessRunId) return false
-    if (
-      !this.ignoredActiveRunIds.has(this.currentRunlessRunId) &&
-      !this.clearedRunIds.has(this.currentRunlessRunId)
-    ) {
-      return false
-    }
-    return (
-      chunk.type === 'TEXT_MESSAGE_START' ||
-      chunk.type === 'TEXT_MESSAGE_CONTENT' ||
-      chunk.type === 'TOOL_CALL_START' ||
-      chunk.type === 'TOOL_CALL_ARGS' ||
-      chunk.type === 'TOOL_CALL_END' ||
-      chunk.type === 'TOOL_CALL_RESULT' ||
-      chunk.type === 'MESSAGES_SNAPSHOT' ||
-      chunk.type === 'RUN_ERROR'
-    )
-  }
-}
diff --git a/packages/ai-client/src/connection-adapters.ts b/packages/ai-client/src/connection-adapters.ts
index 3c4010047..90097f8e9 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,
@@ -199,6 +200,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
@@ -443,6 +446,7 @@ function buildRunAgentInputBody(
     ...(runContext?.parentRunId !== undefined && {
       parentRunId: runContext.parentRunId,
     }),
+    ...(runContext?.resume !== undefined && { resume: runContext.resume }),
     state: {},
     messages: wireMessages,
     tools: runContext?.clientTools ?? [],
@@ -482,7 +486,7 @@ function buildRunAgentInputBody(
  * const connection = fetchServerSentEvents('/api/chat', async () => ({
  *   body: {
  *     provider: 'openai',
- *     model: 'gpt-4o',
+ *     model: 'gpt-5.5',
  *   }
  * }));
  * ```
@@ -524,6 +528,7 @@ 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,
@@ -566,7 +571,7 @@ export function fetchServerSentEvents(
  * const connection = fetchHttpStream('/api/chat', async () => ({
  *   body: {
  *     provider: 'openai',
- *     model: 'gpt-4o',
+ *     model: 'gpt-5.5',
  *   }
  * }));
  * ```
@@ -941,13 +946,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 +988,7 @@ export function fetcherToConnectionAdapter(
           data,
           threadId: runContext.threadId,
           runId: runContext.runId,
+          ...(runContext.resume !== undefined && { resume: runContext.resume }),
         },
         { signal: abortSignal },
       )
@@ -1047,13 +1054,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..86d03cb0e 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,24 @@ 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. It does
+   * not trigger any generation, but it is **not** inert: it seeds the client's
+   * live resume snapshot, which subsequent run events merge into and which
+   * `getResumeSnapshot()` returns and the client re-persists. Later reads
+   * therefore reflect this seed merged with observed activity, not the original
+   * value verbatim.
+   */
+  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 +245,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 +336,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 +466,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..04b271437 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,33 @@ export type {
   DistributedOmit,
   MultimodalContent,
 } from './types'
+export {
+  StorageUnavailableError,
+  indexedDBPersistence,
+  localStoragePersistence,
+  sessionStoragePersistence,
+} from './storage-adapters'
+export type {
+  IndexedDBPersistenceOptions,
+  JsonPrimitive,
+  JsonValue,
+  StorageCodec,
+  WebStoragePersistenceOptions,
+} from './storage-adapters'
 // Generation client types
 export type {
   InferGenerationOutput,
   InferGenerationOutputFromReturn,
   GenerationClientState,
+  GenerationResumeState,
+  GenerationResumeStatus,
+  GenerationResumeSnapshot,
+  GenerationPendingArtifact,
+  GenerationResultSnapshot,
+  GenerationErrorSnapshot,
+  GenerationEventSnapshot,
+  GenerationServerPersistence,
+  GenerationPersistenceOptions,
   GenerationClientOptions,
   GenerationFetcher,
   GenerationFetcherOptions,
@@ -55,7 +83,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 +103,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,
diff --git a/packages/ai-client/src/storage-adapters.ts b/packages/ai-client/src/storage-adapters.ts
new file mode 100644
index 000000000..755238328
--- /dev/null
+++ b/packages/ai-client/src/storage-adapters.ts
@@ -0,0 +1,275 @@
+import type { ChatStorageAdapter } from './types'
+
+export type JsonPrimitive = string | number | boolean | null
+export type JsonValue =
+  | JsonPrimitive
+  | Array<JsonValue>
+  | { [key: string]: JsonValue }
+
+export interface StorageCodec<TValue> {
+  serialize: (value: TValue) => string
+  deserialize: (value: string) => TValue
+}
+
+export interface WebStoragePersistenceOptions<TValue> {
+  keyPrefix?: string
+  serialize?: (value: TValue) => string
+  deserialize?: (value: string) => TValue
+}
+
+export interface IndexedDBPersistenceOptions {
+  databaseName?: string
+  objectStoreName?: string
+  keyPrefix?: string
+}
+
+type NonJsonValue =
+  | bigint
+  | Date
+  | symbol
+  | undefined
+  | ((...args: Array<never>) => unknown)
+
+type IsJsonSerializable<TValue> = [TValue] extends [JsonPrimitive]
+  ? true
+  : [TValue] extends [NonJsonValue]
+    ? false
+    : TValue extends ReadonlyArray<infer TItem>
+      ? IsJsonSerializable<TItem>
+      : TValue extends object
+        ? false extends {
+            [TKey in keyof TValue]-?: IsJsonSerializable<TValue[TKey]>
+          }[keyof TValue]
+          ? false
+          : true
+        : false
+
+type WebStorageArguments<TValue> =
+  IsJsonSerializable<TValue> extends true
+    ? [options?: WebStoragePersistenceOptions<TValue>]
+    : [options: WebStoragePersistenceOptions<TValue> & StorageCodec<TValue>]
+
+type StorageName = 'localStorage' | 'sessionStorage' | 'indexedDB'
+
+/**
+ * Thrown by a storage adapter when its backing store is absent — most commonly
+ * during server-side rendering, where `localStorage` / `sessionStorage` /
+ * `indexedDB` do not exist on `globalThis`. The adapters check availability
+ * lazily, **per operation**, so constructing an adapter never throws; the error
+ * surfaces from `getItem` / `setItem` / `removeItem` (rejected promise for
+ * IndexedDB). The chat persistence layer treats it as best-effort and routes it
+ * to `onError` / `console.warn` rather than breaking chat.
+ */
+export class StorageUnavailableError extends Error {
+  constructor(storageName: StorageName) {
+    super(`${storageName} is not available in this environment.`)
+    this.name = 'StorageUnavailableError'
+  }
+}
+
+function stringifyJson<TValue>(value: TValue): string {
+  const stringify: (input: unknown) => unknown = JSON.stringify
+  const serialized = stringify(value)
+  if (typeof serialized !== 'string') {
+    throw new TypeError('The value is not JSON serializable.')
+  }
+  return serialized
+}
+
+function createWebStoragePersistence<TValue>(
+  storageName: 'localStorage' | 'sessionStorage',
+  options: WebStoragePersistenceOptions<TValue>,
+): ChatStorageAdapter<TValue> {
+  const keyPrefix = options.keyPrefix ?? 'tanstack-ai:'
+  const serialize = options.serialize ?? stringifyJson
+  const deserialize = options.deserialize ?? JSON.parse
+  const key = (id: string) => `${keyPrefix}${id}`
+
+  const getStorage = (): Storage => {
+    const browserGlobals: {
+      localStorage?: Storage
+      sessionStorage?: Storage
+    } = globalThis
+    const storage = browserGlobals[storageName]
+    if (!storage) {
+      throw new StorageUnavailableError(storageName)
+    }
+    return storage
+  }
+
+  return {
+    getItem(id) {
+      const item = getStorage().getItem(key(id))
+      return item === null ? null : deserialize(item)
+    },
+    setItem(id, value) {
+      getStorage().setItem(key(id), serialize(value))
+    },
+    removeItem(id) {
+      getStorage().removeItem(key(id))
+    },
+  }
+}
+
+/**
+ * A `ChatStorageAdapter` backed by `window.localStorage` (persists across
+ * reloads and browser restarts). Keys are namespaced with `keyPrefix`, which
+ * defaults to `tanstack-ai:`. Every operation reads `localStorage` lazily and
+ * throws {@link StorageUnavailableError} when it is absent (e.g. SSR), so the
+ * adapter can be constructed safely on the server.
+ *
+ * The `serialize` / `deserialize` codec defaults to `JSON.stringify` /
+ * `JSON.parse`. When `TValue` is JSON-serializable the codec is optional; when
+ * it is not (it contains `Date`, `Map`, `bigint`, etc.), the type signature
+ * **requires** you to pass a `serialize`/`deserialize` pair.
+ */
+export function localStoragePersistence<TValue = JsonValue>(
+  ...[options = {}]: WebStorageArguments<TValue>
+): ChatStorageAdapter<TValue> {
+  return createWebStoragePersistence('localStorage', options)
+}
+
+/**
+ * A `ChatStorageAdapter` backed by `window.sessionStorage` (scoped to the tab
+ * and cleared when it closes). Identical to {@link localStoragePersistence} in
+ * every other respect: `tanstack-ai:` default `keyPrefix`, lazy per-operation
+ * {@link StorageUnavailableError} on SSR, and a JSON codec that becomes a
+ * required argument when `TValue` is not JSON-serializable.
+ */
+export function sessionStoragePersistence<TValue = JsonValue>(
+  ...[options = {}]: WebStorageArguments<TValue>
+): ChatStorageAdapter<TValue> {
+  return createWebStoragePersistence('sessionStorage', options)
+}
+
+/**
+ * A `ChatStorageAdapter` backed by IndexedDB, for values too large for Web
+ * Storage or that benefit from structured-clone storage. All operations are
+ * async and the database opens lazily on first use; keys are namespaced with
+ * `keyPrefix` (default `tanstack-ai:`). When IndexedDB is unavailable (e.g.
+ * SSR) each operation rejects with {@link StorageUnavailableError}.
+ *
+ * No serialize/deserialize codec is needed or accepted — values are stored via
+ * IndexedDB's native structured clone, so `Date`, `Map`, `ArrayBuffer`, etc.
+ * round-trip without a JSON step.
+ */
+export function indexedDBPersistence<TValue>(
+  options: IndexedDBPersistenceOptions = {},
+): ChatStorageAdapter<TValue> {
+  const databaseName = options.databaseName ?? 'tanstack-ai'
+  const objectStoreName = options.objectStoreName ?? 'persistence'
+  const keyPrefix = options.keyPrefix ?? 'tanstack-ai:'
+  let databasePromise: Promise<IDBDatabase> | undefined
+
+  const openDatabase = (): Promise<IDBDatabase> => {
+    if (databasePromise) {
+      return databasePromise
+    }
+
+    databasePromise = new Promise<IDBDatabase>((resolve, reject) => {
+      const browserGlobals: { indexedDB?: IDBFactory } = globalThis
+      const factory = browserGlobals.indexedDB
+      if (!factory) {
+        reject(new StorageUnavailableError('indexedDB'))
+        return
+      }
+
+      let request: IDBOpenDBRequest
+      let openFailed = false
+      try {
+        request = factory.open(databaseName)
+      } catch (error) {
+        reject(error)
+        return
+      }
+
+      request.onupgradeneeded = () => {
+        if (!request.result.objectStoreNames.contains(objectStoreName)) {
+          request.result.createObjectStore(objectStoreName)
+        }
+      }
+      request.onerror = () => {
+        openFailed = true
+        reject(request.error ?? new Error(`Failed to open ${databaseName}.`))
+      }
+      request.onblocked = () => {
+        openFailed = true
+        reject(
+          new Error(
+            `Opening IndexedDB database "${databaseName}" was blocked.`,
+          ),
+        )
+      }
+      request.onsuccess = () => {
+        const database = request.result
+        if (openFailed) {
+          database.close()
+          return
+        }
+        database.onversionchange = () => {
+          database.close()
+          databasePromise = undefined
+        }
+        resolve(database)
+      }
+    }).catch((error: unknown) => {
+      databasePromise = undefined
+      throw error
+    })
+
+    return databasePromise
+  }
+
+  const runRequest = async <TResult>(
+    mode: IDBTransactionMode,
+    createRequest: (store: IDBObjectStore) => IDBRequest<TResult>,
+  ): Promise<TResult> => {
+    const database = await openDatabase()
+    return new Promise<TResult>((resolve, reject) => {
+      let request: IDBRequest<TResult>
+      let result: TResult
+      try {
+        const transaction = database.transaction(objectStoreName, mode)
+        request = createRequest(transaction.objectStore(objectStoreName))
+        request.onsuccess = () => {
+          result = request.result
+        }
+        request.onerror = () => {
+          reject(request.error ?? new Error('IndexedDB request failed.'))
+        }
+        transaction.oncomplete = () => {
+          resolve(result)
+        }
+        transaction.onerror = () => {
+          reject(
+            transaction.error ?? new Error('IndexedDB transaction failed.'),
+          )
+        }
+        transaction.onabort = () => {
+          reject(
+            transaction.error ?? new Error('IndexedDB transaction aborted.'),
+          )
+        }
+      } catch (error) {
+        reject(error)
+      }
+    })
+  }
+
+  const key = (id: string) => `${keyPrefix}${id}`
+  return {
+    getItem(id) {
+      return runRequest('readonly', (store) => store.get(key(id)))
+    },
+    setItem(id, value) {
+      return runRequest('readwrite', (store) => store.put(value, key(id))).then(
+        () => undefined,
+      )
+    },
+    removeItem(id) {
+      return runRequest('readwrite', (store) => store.delete(key(id))).then(
+        () => undefined,
+      )
+    },
+  }
+}
diff --git a/packages/ai-client/src/types.ts b/packages/ai-client/src/types.ts
index 8e385d45b..4c78af7fe 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,20 +19,42 @@ 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
- * merged body — `ChatClientOptions.body` plus any per-call data passed to
- * `sendMessage(...)`. `threadId` / `runId` are the AG-UI correlation ids
- * the chat client uses to track this turn — forward them to your server
- * if it needs to correlate requests.
+ * `messages` is the full UIMessage history (not a delta) for a normal turn.
+ * On a **resume** request (see `resume` below) it is deliberately an **empty
+ * array** — the server continues the interrupted run from its own persisted
+ * state, so the client sends the resume decisions rather than re-sending the
+ * conversation. `data` is the merged body — `ChatClientOptions.body` plus any
+ * per-call data passed to `sendMessage(...)`. `threadId` / `runId` are the
+ * AG-UI correlation ids the chat client uses to track this turn — forward them
+ * to your server if it needs to correlate requests.
  */
 export interface ChatFetcherInput {
   messages: Array<UIMessage>
   data?: Record<string, unknown>
   threadId: string
   runId: string
+  /**
+   * Present only when continuing an interrupted run (an approval response or a
+   * client-tool result). Each item resolves one pending interrupt via the AG-UI
+   * `RunAgentInput.resume[]` contract; forward it to `chat()` on the server.
+   * When set, `messages` is empty and `runId` reuses the interrupted run's id.
+   */
+  resume?: Array<RunAgentResumeItem>
 }
 
 export interface ChatFetcherOptions {
@@ -281,23 +305,27 @@ 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>
+
+export interface ChatPersistenceOptions<
+  TTools extends ReadonlyArray<AnyClientTool> = any,
+> {
+  client?: ChatClientPersistence<TTools>
+  server?: ChatServerPersistence
+}
+
 type IsUnknown<T> = unknown extends T
   ? [T] extends [unknown]
     ? true
@@ -389,9 +417,13 @@ export interface ChatClientBaseOptions<
   initialMessages?: Array<UIMessage<TTools>>
 
   /**
-   * Optional persistence adapter for chat messages.
+   * Optional persistence adapters for chat state.
+   *
+   * `client` stores client-rendered `UIMessage[]` using this chat's `id`;
+   * `server` stores `{ resumeState, pendingInterrupts }` using this chat's
+   * `threadId`.
    */
-  persistence?: ChatClientPersistence<TTools>
+  persistence?: ChatPersistenceOptions<TTools>
 
   /**
    * Unique identifier for this chat instance
@@ -405,6 +437,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
@@ -492,6 +531,20 @@ export interface ChatClientBaseOptions<
    */
   onSessionGeneratingChange?: (isGenerating: boolean) => void
 
+  /**
+   * Callback for the current resumable run state and pending interrupts.
+   *
+   * Note: this fires on **every** terminal stream chunk (RUN_FINISHED /
+   * RUN_ERROR), not only when the values actually change — a run that finishes
+   * with no interrupt still invokes it with `(null, [])`. Treat it as a
+   * "resume state may have changed" signal and diff against your own last
+   * value if you need change-only semantics.
+   */
+  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..554c106b6
--- /dev/null
+++ b/packages/ai-client/tests/chat-client-resume.test.ts
@@ -0,0 +1,1632 @@
+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 when server persistence is configured', 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' }],
+          },
+        },
+      ],
+      [],
+    ])
+    // A server-persistence resume adapter declares that run state is durable
+    // server-side, so the server rebuilds the interrupted run's transcript and
+    // the client can omit it on resume.
+    const client = new ChatClient({
+      connection: adapter,
+      threadId: 'thread-1',
+      persistence: { server: createResumePersistence() },
+    })
+
+    await client.sendMessage('hi')
+    expect(sentMessages[0]).toHaveLength(1)
+
+    await client.resumeInterrupts(resumeItems)
+
+    expect(contexts[1]?.resume).toEqual(resumeItems)
+    expect(sentMessages[1]).toEqual([])
+  })
+
+  it('resumeInterrupts re-sends message history when server persistence is absent', async () => {
+    // Without server persistence the server is stateless across requests, so a
+    // resume with an empty transcript would strand the run (no history, no way
+    // to apply the decision). The client must re-send its own transcript — whose
+    // tool-call parts now carry the approval-responded decision — so a stateless
+    // server can continue the run. Regression coverage for the broken plain
+    // (non-persistence) approval path.
+    const resumeItems: Array<RunAgentResumeItem> = [
+      {
+        interruptId: 'interrupt-1',
+        status: 'resolved',
+        payload: { approved: true },
+      },
+    ]
+    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: 'approval_required',
+                metadata: { kind: 'approval' },
+              },
+            ],
+          },
+        },
+      ],
+      [],
+    ])
+    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)
+    // The transcript (user turn + the interrupted assistant turn) is re-sent.
+    expect(sentMessages[1]?.length).toBeGreaterThan(0)
+  })
+
+  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 },
+      },
+    ])
+  })
+
+  it('restores resume state and stays retryable when the resume connection fails', async () => {
+    let failNext = true
+    const contexts: Array<RunAgentInputContext | undefined> = []
+    const adapter: ConnectConnectionAdapter = {
+      // eslint-disable-next-line @typescript-eslint/require-await
+      async *connect(_messages, _data, _signal, runContext) {
+        contexts.push(runContext)
+        if (failNext) {
+          failNext = false
+          throw new Error('network down')
+        }
+        yield {
+          type: EventType.RUN_FINISHED,
+          runId: runContext?.runId ?? 'run-1',
+          threadId: runContext?.threadId ?? 'thread-1',
+          timestamp: Date.now(),
+          outcome: { type: 'success' },
+        }
+      },
+    }
+    const onError = vi.fn()
+    const client = new ChatClient({
+      connection: adapter,
+      threadId: 'thread-1',
+      onError,
+      initialResumeSnapshot: {
+        resumeState: { threadId: 'thread-1', runId: 'run-1' },
+        pendingInterrupts: [
+          {
+            id: 'approval-1',
+            reason: 'approval_required',
+            toolCallId: 'tool-1',
+            metadata: { kind: 'approval' },
+          },
+        ],
+      },
+    })
+
+    const resume: Array<RunAgentResumeItem> = [
+      {
+        interruptId: 'approval-1',
+        status: 'resolved',
+        payload: { approved: true },
+      },
+    ]
+
+    // First attempt fails at the connection layer.
+    await expect(client.resumeInterrupts(resume)).resolves.toBe(false)
+    // Let the synthetic RUN_ERROR the connect-wrapper pushed drain through the
+    // subscription loop; the interrupt state must survive it.
+    await new Promise((resolve) => setTimeout(resolve, 5))
+
+    expect(onError).toHaveBeenCalled()
+    // The interrupt is still pending server-side — not stranded.
+    expect(client.getResumeState()).toEqual({
+      threadId: 'thread-1',
+      runId: 'run-1',
+    })
+    expect(client.getPendingInterrupts()).toEqual([
+      expect.objectContaining({ id: 'approval-1' }),
+    ])
+
+    // Retrying the same resume now succeeds and clears the state.
+    await expect(client.resumeInterrupts(resume)).resolves.toBe(true)
+    await new Promise((resolve) => setTimeout(resolve, 5))
+
+    expect(contexts).toHaveLength(2)
+    expect(contexts[1]?.runId).toBe('run-1')
+    expect(contexts[1]?.resume).toEqual(resume)
+    expect(client.getResumeState()).toBeNull()
+    expect(client.getPendingInterrupts()).toEqual([])
+  })
+
+  it('clears resume state and removes the snapshot when the run finished server-side before remount', async () => {
+    const persistence = createResumePersistence({
+      resumeState: { threadId: 'thread-1', runId: 'run-1' },
+      pendingInterrupts: [
+        {
+          id: 'approval-1',
+          reason: 'approval_required',
+          toolCallId: 'tool-1',
+          metadata: { kind: 'approval' },
+        },
+      ],
+    })
+    // The run already completed server-side while the client was unloaded, so
+    // the resume request comes back finished with no interrupt.
+    const { adapter } = recordingAdapter([
+      (ctx) => [
+        {
+          type: EventType.RUN_FINISHED,
+          runId: ctx?.runId ?? 'run-1',
+          threadId: 'thread-1',
+          timestamp: Date.now(),
+          outcome: { type: 'success' },
+        },
+      ],
+    ])
+    const client = new ChatClient({
+      connection: adapter,
+      threadId: 'thread-1',
+      persistence: { server: persistence },
+    })
+
+    // Remount seeded the interrupt from the persisted snapshot.
+    expect(client.getResumeState()).toEqual({
+      threadId: 'thread-1',
+      runId: 'run-1',
+    })
+
+    await client.addToolApprovalResponse({ id: 'approval-1', approved: true })
+    await new Promise((resolve) => setTimeout(resolve, 5))
+
+    expect(client.getResumeState()).toBeNull()
+    expect(client.getPendingInterrupts()).toEqual([])
+    expect(persistence.removeItem).toHaveBeenCalledWith('thread-1')
+  })
+
+  it('ignores a malformed synchronous resume snapshot and reports it', () => {
+    const warnSpy = vi.spyOn(console, 'warn').mockImplementation(() => {})
+    const persistence: ChatServerPersistence = {
+      // Parseable but structurally invalid — no resumeState.
+      getItem: vi.fn(() => ({ foo: 'bar' }) as unknown as ChatResumeSnapshot),
+      setItem: vi.fn(),
+      removeItem: vi.fn(),
+    }
+    const { adapter } = recordingAdapter([[]])
+    const client = new ChatClient({
+      connection: adapter,
+      threadId: 'thread-1',
+      persistence: { server: persistence },
+    })
+
+    expect(client.getResumeState()).toBeNull()
+    expect(client.getPendingInterrupts()).toEqual([])
+    expect(warnSpy).toHaveBeenCalledWith(
+      '[TanStack AI] Server persistence adapter error (non-fatal):',
+      expect.any(Error),
+    )
+    warnSpy.mockRestore()
+  })
+
+  it('ignores a malformed async-hydrated resume snapshot and reports it to onError', async () => {
+    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 onError = vi.fn()
+    const client = new ChatClient({
+      connection: adapter,
+      threadId: 'thread-1',
+      persistence: { server: persistence },
+      onError,
+    })
+
+    // resumeState is present but missing the required runId.
+    resolveHydrate({
+      resumeState: { threadId: 'thread-1' },
+    } as unknown as ChatResumeSnapshot)
+    await Promise.resolve()
+    await Promise.resolve()
+
+    expect(client.getResumeState()).toBeNull()
+    expect(client.getPendingInterrupts()).toEqual([])
+    expect(onError).toHaveBeenCalledWith(expect.any(Error))
+  })
+})
diff --git a/packages/ai-client/tests/chat-client.test.ts b/packages/ai-client/tests/chat-client.test.ts
index 7f8cb66c4..b539bf1dc 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 = {
@@ -89,7 +93,21 @@ describe('ChatClient', () => {
       const client = new ChatClient({
         connection: adapter,
         id: 'chat-1',
-        persistence,
+        persistence: { client: persistence },
+      })
+
+      expect(persistence.getItem).toHaveBeenCalledWith('chat-1')
+      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')
@@ -104,7 +122,7 @@ describe('ChatClient', () => {
         connection: adapter,
         id: 'chat-1',
         initialMessages: [initialMessage],
-        persistence,
+        persistence: { client: persistence },
       })
 
       expect(client.getMessages()).toEqual([persistedMessage])
@@ -118,7 +136,7 @@ describe('ChatClient', () => {
         connection: adapter,
         id: 'chat-1',
         initialMessages: [initialMessage],
-        persistence,
+        persistence: { client: persistence },
       })
 
       expect(client.getMessages()).toEqual([initialMessage])
@@ -132,7 +150,7 @@ describe('ChatClient', () => {
         connection: adapter,
         id: 'chat-1',
         initialMessages: [initialMessage],
-        persistence,
+        persistence: { client: persistence },
       })
 
       expect(client.getMessages()).toEqual([initialMessage])
@@ -146,7 +164,7 @@ describe('ChatClient', () => {
         connection: adapter,
         id: 'chat-1',
         initialMessages: [initialMessage],
-        persistence,
+        persistence: { client: persistence },
       })
 
       expect(client.getMessages()).toEqual([])
@@ -166,7 +184,7 @@ describe('ChatClient', () => {
         id: 'chat-1',
         initialMessages: [initialMessage],
         onMessagesChange,
-        persistence,
+        persistence: { client: persistence },
       })
 
       expect(client.getMessages()).toEqual([initialMessage])
@@ -191,7 +209,7 @@ describe('ChatClient', () => {
         connection: adapter,
         id: 'chat-1',
         initialMessages: [initialMessage],
-        persistence,
+        persistence: { client: persistence },
       })
 
       client.setMessagesManually([
@@ -216,6 +234,86 @@ 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: persistence },
+      })
+
+      client.dispose()
+      deferred.resolve([persistedMessage])
+      await new Promise((resolve) => setTimeout(resolve, 0))
+
+      expect(client.getMessages()).toEqual([initialMessage])
+      expect(onMessagesChange).not.toHaveBeenCalled()
+    })
+
+    it('reports a throwing message getItem and refuses to overwrite stored history', async () => {
+      const readError = new Error('corrupt stored JSON')
+      const persistence: ChatClientPersistence = {
+        getItem: vi.fn(() => {
+          throw readError
+        }),
+        setItem: vi.fn(),
+        removeItem: vi.fn(),
+      }
+      const onError = vi.fn()
+      const adapter = createMockConnectionAdapter({
+        chunks: createTextChunks('Hi'),
+      })
+      const client = new ChatClient({
+        connection: adapter,
+        id: 'chat-1',
+        onError,
+        persistence: { client: persistence },
+      })
+
+      // The failed read is reported, not swallowed.
+      expect(onError).toHaveBeenCalledWith(readError)
+
+      await client.sendMessage('hello')
+
+      // ...and the fresh session must not clobber the (recoverable) stored copy.
+      expect(persistence.setItem).not.toHaveBeenCalled()
+    })
+
+    it('warns on a throwing message getItem when no onError is provided', () => {
+      const warnSpy = vi.spyOn(console, 'warn').mockImplementation(() => {})
+      const readError = new Error('corrupt stored JSON')
+      const persistence: ChatClientPersistence = {
+        getItem: vi.fn(() => {
+          throw readError
+        }),
+        setItem: vi.fn(),
+        removeItem: vi.fn(),
+      }
+      const adapter = createMockConnectionAdapter()
+      const client = new ChatClient({
+        connection: adapter,
+        id: 'chat-1',
+        persistence: { client: persistence },
+      })
+
+      expect(client.getMessages()).toEqual([])
+      expect(warnSpy).toHaveBeenCalledWith(
+        '[TanStack AI] Message persistence adapter error (non-fatal):',
+        readError,
+      )
+      warnSpy.mockRestore()
+    })
+
     it('should keep current constructor behavior when persistence is omitted', () => {
       const adapter = createMockConnectionAdapter()
 
@@ -415,7 +513,7 @@ describe('ChatClient', () => {
       const client = new ChatClient({
         connection: adapter,
         id: 'chat-1',
-        persistence,
+        persistence: { client: persistence },
       })
 
       const firstSend = client.sendMessage('A')
@@ -510,7 +608,7 @@ describe('ChatClient', () => {
       const client = new ChatClient({
         connection: adapter,
         id: 'chat-1',
-        persistence,
+        persistence: { client: persistence },
       })
 
       const sendPromise = client.sendMessage('A')
@@ -644,7 +742,7 @@ describe('ChatClient', () => {
       const client = new ChatClient({
         connection: adapter,
         id: 'chat-1',
-        persistence,
+        persistence: { client: persistence },
       })
 
       const firstSend = client.sendMessage('A')
@@ -677,6 +775,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>()
@@ -721,7 +945,7 @@ describe('ChatClient', () => {
       const client = new ChatClient({
         connection: adapter,
         id: 'chat-1',
-        persistence,
+        persistence: { client: persistence },
       })
 
       const sendPromise = client.sendMessage('A')
@@ -774,7 +998,7 @@ describe('ChatClient', () => {
       const client = new ChatClient({
         connection: adapter,
         id: 'chat-1',
-        persistence,
+        persistence: { client: persistence },
         onError,
       })
 
@@ -892,7 +1116,7 @@ describe('ChatClient', () => {
       const client = new ChatClient({
         connection: adapter,
         id: 'chat-1',
-        persistence,
+        persistence: { client: persistence },
       })
 
       const firstSend = client.sendMessage('A')
@@ -985,7 +1209,7 @@ describe('ChatClient', () => {
       const client = new ChatClient({
         connection: adapter,
         id: 'chat-1',
-        persistence,
+        persistence: { client: persistence },
       })
 
       const sendPromise = client.sendMessage('A')
@@ -1054,7 +1278,7 @@ describe('ChatClient', () => {
       const client = new ChatClient({
         connection: adapter,
         id: 'chat-1',
-        persistence,
+        persistence: { client: persistence },
       })
 
       const sendPromise = client.sendMessage('A')
@@ -1110,7 +1334,7 @@ describe('ChatClient', () => {
       const client = new ChatClient({
         connection: adapter,
         id: 'chat-1',
-        persistence,
+        persistence: { client: persistence },
       })
 
       const sendPromise = client.sendMessage('A')
@@ -1178,7 +1402,7 @@ describe('ChatClient', () => {
       const client = new ChatClient({
         connection: adapter,
         id: 'chat-1',
-        persistence: createPersistence(),
+        persistence: { client: createPersistence() },
       })
 
       const sendPromise = client.sendMessage('A')
@@ -1246,7 +1470,7 @@ describe('ChatClient', () => {
       const client = new ChatClient({
         connection: adapter,
         id: 'chat-1',
-        persistence,
+        persistence: { client: persistence },
       })
 
       client.subscribe()
@@ -1940,7 +2164,7 @@ describe('ChatClient', () => {
         const client = new ChatClient({
           connection,
           id: 'chat-1',
-          persistence,
+          persistence: { client: persistence },
         })
 
         client.subscribe()
@@ -2308,7 +2532,7 @@ describe('ChatClient', () => {
       const client = new ChatClient({
         connection: adapter,
         id: 'chat-1',
-        persistence,
+        persistence: { client: persistence },
       })
 
       await client.sendMessage('Hello')
@@ -2320,7 +2544,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 +2566,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 () => {
@@ -2365,7 +2585,7 @@ describe('ChatClient', () => {
       const client = new ChatClient({
         connection: adapter,
         id: 'chat-1',
-        persistence,
+        persistence: { client: persistence },
       })
 
       const sendPromise = client.sendMessage('Hello')
@@ -2404,7 +2624,7 @@ describe('ChatClient', () => {
       const client = new ChatClient({
         connection: adapter,
         id: 'chat-1',
-        persistence,
+        persistence: { client: persistence },
       })
 
       const sendPromise = client.sendMessage('Hello')
@@ -2450,7 +2670,7 @@ describe('ChatClient', () => {
       const client = new ChatClient({
         connection,
         id: 'chat-1',
-        persistence,
+        persistence: { client: persistence },
       })
 
       const firstSend = client.sendMessage('A')
@@ -2500,7 +2720,7 @@ describe('ChatClient', () => {
       const client = new ChatClient({
         connection: createMockConnectionAdapter(),
         id: 'chat-1',
-        persistence,
+        persistence: { client: persistence },
       })
 
       client.setMessagesManually([initialMessage])
@@ -2523,7 +2743,7 @@ describe('ChatClient', () => {
       const client = new ChatClient({
         connection: adapter,
         id: 'chat-1',
-        persistence,
+        persistence: { client: persistence },
       })
 
       await client.sendMessage('Hello')
@@ -2541,7 +2761,7 @@ describe('ChatClient', () => {
       const client = new ChatClient({
         connection: adapter,
         id: 'chat-1',
-        persistence,
+        persistence: { client: persistence },
       })
 
       client.setMessagesManually([initialMessage])
@@ -2563,7 +2783,7 @@ describe('ChatClient', () => {
       const client = new ChatClient({
         connection: adapter,
         id: 'chat-1',
-        persistence,
+        persistence: { client: persistence },
       })
 
       await client.sendMessage('Hello')
@@ -2614,7 +2834,7 @@ describe('ChatClient', () => {
         id: 'chat-1',
         initialMessages: [initialMessage],
         onMessagesChange,
-        persistence,
+        persistence: { client: persistence },
       })
 
       expect(client.getMessages()).toEqual([initialMessage])
@@ -3238,16 +3458,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 +3484,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 +3506,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 +3530,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 +3554,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 +3624,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 +3634,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/chat-persistence-controller.test.ts b/packages/ai-client/tests/chat-persistence-controller.test.ts
new file mode 100644
index 000000000..ceb69e194
--- /dev/null
+++ b/packages/ai-client/tests/chat-persistence-controller.test.ts
@@ -0,0 +1,404 @@
+import { describe, expect, it, vi } from 'vitest'
+import { ChatPersistenceController } from '../src/chat-persistence-controller'
+import { localStoragePersistence } from '../src/storage-adapters'
+import { createUIMessage } from './test-utils'
+import type {
+  ChatClientPersistence,
+  ChatResumeSnapshot,
+  ChatServerPersistence,
+  UIMessage,
+} from '../src/types'
+
+function deferred<T>() {
+  let resolve: (value: T) => void = () => {
+    throw new Error('Deferred promise resolved before initialization')
+  }
+  let reject: (reason?: unknown) => void = () => {
+    throw new Error('Deferred promise rejected before initialization')
+  }
+  const promise = new Promise<T>((promiseResolve, promiseReject) => {
+    resolve = promiseResolve
+    reject = promiseReject
+  })
+  return { promise, reject, resolve }
+}
+
+function messageAdapter(
+  initial?: Array<UIMessage> | null,
+): ChatClientPersistence {
+  return {
+    getItem: vi.fn(() => initial),
+    setItem: vi.fn(),
+    removeItem: vi.fn(),
+  }
+}
+
+function resumeAdapter(
+  initial?: ChatResumeSnapshot | null,
+): ChatServerPersistence {
+  return {
+    getItem: vi.fn(() => initial),
+    setItem: vi.fn(),
+    removeItem: vi.fn(),
+  }
+}
+
+function resumeSnapshot(runId: string): ChatResumeSnapshot {
+  return {
+    resumeState: { threadId: 'thread-1', runId },
+    pendingInterrupts: [],
+  }
+}
+
+function createController(options: {
+  messages?: ChatClientPersistence
+  resume?: ChatServerPersistence
+  canHydrateResume?: () => boolean
+}) {
+  const applyMessages = vi.fn<(messages: Array<UIMessage>) => void>()
+  const applyResumeSnapshot = vi.fn<(snapshot: ChatResumeSnapshot) => void>()
+  const reportResumeError = vi.fn<(error: unknown) => void>()
+  const reportPersistenceError = vi.fn<(error: unknown) => void>()
+  const controller = new ChatPersistenceController({
+    chatId: 'chat-1',
+    threadId: 'thread-1',
+    messageAdapter: options.messages,
+    resumeAdapter: options.resume,
+    applyMessages,
+    applyResumeSnapshot,
+    canHydrateResume: options.canHydrateResume ?? (() => true),
+    reportResumeError,
+    reportPersistenceError,
+  })
+  return {
+    applyMessages,
+    applyResumeSnapshot,
+    controller,
+    reportResumeError,
+    reportPersistenceError,
+  }
+}
+
+describe('ChatPersistenceController', () => {
+  it('reads synchronous message and resume state with their independent keys', () => {
+    const messages = [createUIMessage('stored')]
+    const snapshot = resumeSnapshot('stored-run')
+    const messagesStore = messageAdapter(messages)
+    const resumeStore = resumeAdapter(snapshot)
+    const { controller } = createController({
+      messages: messagesStore,
+      resume: resumeStore,
+    })
+
+    expect(controller.readInitialMessages()).toBe(messages)
+    expect(controller.readInitialResumeSnapshot()).toBe(snapshot)
+    expect(messagesStore.getItem).toHaveBeenCalledWith('chat-1')
+    expect(resumeStore.getItem).toHaveBeenCalledWith('thread-1')
+  })
+
+  it('hydrates asynchronous lanes without letting stale reads overwrite newer state', async () => {
+    const messagesRead = deferred<Array<UIMessage>>()
+    const resumeRead = deferred<ChatResumeSnapshot>()
+    const messagesStore = messageAdapter()
+    messagesStore.getItem = vi.fn(() => messagesRead.promise)
+    const resumeStore = resumeAdapter()
+    resumeStore.getItem = vi.fn(() => resumeRead.promise)
+    const { applyMessages, applyResumeSnapshot, controller } = createController(
+      {
+        messages: messagesStore,
+        resume: resumeStore,
+      },
+    )
+
+    controller.hydrateMessages(controller.readInitialMessages())
+    controller.hydrateResumeSnapshot(controller.readInitialResumeSnapshot())
+    controller.messagesChanged([createUIMessage('local')])
+    controller.persistResumeSnapshot(null)
+    messagesRead.resolve([createUIMessage('stale')])
+    resumeRead.resolve(resumeSnapshot('stale-run'))
+    await Promise.all([messagesRead.promise, resumeRead.promise])
+    await Promise.resolve()
+
+    expect(applyMessages).not.toHaveBeenCalled()
+    expect(applyResumeSnapshot).not.toHaveBeenCalled()
+  })
+
+  it('keeps message and resume writes on independent ordered lanes', async () => {
+    const firstMessageWrite = deferred<void>()
+    const firstResumeWrite = deferred<void>()
+    const messagesStore = messageAdapter()
+    messagesStore.setItem = vi
+      .fn()
+      .mockReturnValueOnce(firstMessageWrite.promise)
+      .mockResolvedValue(undefined)
+    const resumeStore = resumeAdapter()
+    resumeStore.setItem = vi.fn(() => firstResumeWrite.promise)
+    const { controller } = createController({
+      messages: messagesStore,
+      resume: resumeStore,
+    })
+
+    controller.messagesChanged([createUIMessage('message-a')])
+    controller.messagesChanged([createUIMessage('message-b')])
+    controller.persistResumeSnapshot(resumeSnapshot('run-a'))
+    controller.persistResumeSnapshot(null)
+
+    expect(messagesStore.setItem).toHaveBeenCalledTimes(1)
+    expect(resumeStore.setItem).toHaveBeenCalledTimes(1)
+    expect(resumeStore.removeItem).not.toHaveBeenCalled()
+
+    firstMessageWrite.resolve()
+    await firstMessageWrite.promise
+    await Promise.resolve()
+    expect(messagesStore.setItem).toHaveBeenCalledTimes(2)
+
+    firstResumeWrite.resolve()
+    await firstResumeWrite.promise
+    await Promise.resolve()
+    expect(resumeStore.removeItem).toHaveBeenCalledWith('thread-1')
+  })
+
+  it('skips superseded queued resume writes and reconciles the newest state', async () => {
+    const firstWrite = deferred<void>()
+    const resumeStore = resumeAdapter()
+    resumeStore.setItem = vi
+      .fn()
+      .mockReturnValueOnce(firstWrite.promise)
+      .mockResolvedValue(undefined)
+    const { controller } = createController({ resume: resumeStore })
+
+    controller.persistResumeSnapshot(resumeSnapshot('run-a'))
+    controller.persistResumeSnapshot(resumeSnapshot('run-b'))
+    controller.persistResumeSnapshot(null)
+    firstWrite.resolve()
+    await firstWrite.promise
+    await Promise.resolve()
+    await Promise.resolve()
+
+    expect(resumeStore.setItem).toHaveBeenCalledTimes(1)
+    expect(resumeStore.removeItem).toHaveBeenCalledWith('thread-1')
+  })
+
+  it('removes messages after skipping the clear snapshot and invalidates queued writes', async () => {
+    const firstWrite = deferred<void>()
+    const messagesStore = messageAdapter()
+    messagesStore.setItem = vi
+      .fn()
+      .mockReturnValueOnce(firstWrite.promise)
+      .mockResolvedValue(undefined)
+    const { controller } = createController({ messages: messagesStore })
+
+    controller.messagesChanged([createUIMessage('before')])
+    controller.messagesChanged([createUIMessage('queued')])
+    controller.prepareMessagesClear()
+    controller.messagesChanged([])
+    controller.removeMessages()
+    firstWrite.resolve()
+    await firstWrite.promise
+    await Promise.resolve()
+    await Promise.resolve()
+
+    expect(messagesStore.setItem).toHaveBeenCalledTimes(1)
+    expect(messagesStore.removeItem).toHaveBeenCalledWith('chat-1')
+  })
+
+  it('invalidates asynchronous hydration and queued work on dispose', async () => {
+    const messagesRead = deferred<Array<UIMessage>>()
+    const resumeRead = deferred<ChatResumeSnapshot>()
+    const pendingWrite = deferred<void>()
+    const messagesStore = messageAdapter()
+    messagesStore.getItem = vi.fn(() => messagesRead.promise)
+    messagesStore.setItem = vi
+      .fn()
+      .mockReturnValueOnce(pendingWrite.promise)
+      .mockResolvedValue(undefined)
+    const resumeStore = resumeAdapter()
+    resumeStore.getItem = vi.fn(() => resumeRead.promise)
+    const { applyMessages, applyResumeSnapshot, controller } = createController(
+      {
+        messages: messagesStore,
+        resume: resumeStore,
+      },
+    )
+
+    controller.hydrateMessages(controller.readInitialMessages())
+    controller.hydrateResumeSnapshot(controller.readInitialResumeSnapshot())
+    controller.messagesChanged([createUIMessage('in-flight')])
+    controller.messagesChanged([createUIMessage('queued')])
+    controller.dispose()
+    messagesRead.resolve([createUIMessage('stored')])
+    resumeRead.resolve(resumeSnapshot('stored-run'))
+    pendingWrite.resolve()
+    await Promise.all([
+      messagesRead.promise,
+      resumeRead.promise,
+      pendingWrite.promise,
+    ])
+    await Promise.resolve()
+
+    expect(applyMessages).not.toHaveBeenCalled()
+    expect(applyResumeSnapshot).not.toHaveBeenCalled()
+    expect(messagesStore.setItem).toHaveBeenCalledTimes(1)
+  })
+
+  it('keeps message failures best-effort and reports resume failures', async () => {
+    vi.stubGlobal('localStorage', undefined)
+    const messagesStore = localStoragePersistence<Array<UIMessage>>({
+      serialize: (messages) => {
+        const value = JSON.stringify(messages)
+        if (value === undefined) {
+          throw new TypeError('Messages are not JSON serializable')
+        }
+        return value
+      },
+      deserialize: JSON.parse,
+    })
+    const resumeStore = localStoragePersistence<ChatResumeSnapshot>({
+      serialize: (snapshot) => {
+        const value = JSON.stringify(snapshot)
+        if (value === undefined) {
+          throw new TypeError('Resume state is not JSON serializable')
+        }
+        return value
+      },
+      deserialize: JSON.parse,
+    })
+    const { controller, reportResumeError } = createController({
+      messages: messagesStore,
+      resume: resumeStore,
+    })
+
+    expect(controller.readInitialMessages()).toBeUndefined()
+    expect(controller.readInitialResumeSnapshot()).toBeUndefined()
+    expect(reportResumeError).toHaveBeenCalledTimes(1)
+    controller.messagesChanged([createUIMessage('message')])
+    controller.persistResumeSnapshot(resumeSnapshot('run'))
+    await Promise.resolve()
+
+    expect(reportResumeError).toHaveBeenCalledTimes(2)
+  })
+
+  it('reports a synchronous message read failure and refuses to overwrite the stored copy', () => {
+    const readError = new Error('corrupt stored JSON')
+    const messagesStore: ChatClientPersistence = {
+      getItem: vi.fn(() => {
+        throw readError
+      }),
+      setItem: vi.fn(),
+      removeItem: vi.fn(),
+    }
+    const { controller, reportPersistenceError } = createController({
+      messages: messagesStore,
+    })
+
+    // Simulate ChatClient's constructor sequence: read, then a message change.
+    expect(controller.readInitialMessages()).toBeUndefined()
+    expect(reportPersistenceError).toHaveBeenCalledTimes(1)
+    expect(reportPersistenceError).toHaveBeenCalledWith(readError)
+
+    controller.messagesChanged([createUIMessage('fresh')])
+
+    // The failed read must not lead to clobbering the (possibly recoverable)
+    // stored history with the fresh, empty-ish session.
+    expect(messagesStore.setItem).not.toHaveBeenCalled()
+  })
+
+  it('reports an asynchronous message read rejection and suspends writes', async () => {
+    const readError = new Error('async read failed')
+    const messagesRead = deferred<Array<UIMessage>>()
+    const messagesStore: ChatClientPersistence = {
+      getItem: vi.fn(() => messagesRead.promise),
+      setItem: vi.fn(),
+      removeItem: vi.fn(),
+    }
+    const { controller, reportPersistenceError } = createController({
+      messages: messagesStore,
+    })
+
+    controller.hydrateMessages(controller.readInitialMessages())
+    messagesRead.reject(readError)
+    await messagesRead.promise.catch(() => {})
+    await Promise.resolve()
+
+    expect(reportPersistenceError).toHaveBeenCalledTimes(1)
+    expect(reportPersistenceError).toHaveBeenCalledWith(readError)
+
+    controller.messagesChanged([createUIMessage('fresh')])
+    expect(messagesStore.setItem).not.toHaveBeenCalled()
+  })
+
+  it('persists normally when the initial read succeeds', () => {
+    const messagesStore = messageAdapter([createUIMessage('stored')])
+    const { controller, reportPersistenceError } = createController({
+      messages: messagesStore,
+    })
+
+    expect(controller.readInitialMessages()).toEqual([createUIMessage('stored')])
+    controller.messagesChanged([createUIMessage('next')])
+
+    expect(reportPersistenceError).not.toHaveBeenCalled()
+    expect(messagesStore.setItem).toHaveBeenCalledTimes(1)
+    expect(messagesStore.setItem).toHaveBeenCalledWith('chat-1', [
+      createUIMessage('next'),
+    ])
+  })
+
+  it('resumes persistence after an explicit clear (removeMessages) despite a prior read failure', () => {
+    const messagesStore: ChatClientPersistence = {
+      getItem: vi.fn(() => {
+        throw new Error('corrupt stored JSON')
+      }),
+      setItem: vi.fn(),
+      removeItem: vi.fn(),
+    }
+    const { controller } = createController({ messages: messagesStore })
+
+    controller.readInitialMessages()
+    controller.messagesChanged([createUIMessage('suppressed')])
+    expect(messagesStore.setItem).not.toHaveBeenCalled()
+
+    // Explicit user reset deletes the stored copy, so new writes are safe again.
+    controller.removeMessages()
+    expect(messagesStore.removeItem).toHaveBeenCalledWith('chat-1')
+    controller.messagesChanged([createUIMessage('fresh-after-clear')])
+    expect(messagesStore.setItem).toHaveBeenCalledTimes(1)
+  })
+
+  it('reports synchronous write failures instead of swallowing them', () => {
+    const writeError = new Error('quota exceeded')
+    const messagesStore: ChatClientPersistence = {
+      getItem: vi.fn(() => null),
+      setItem: vi.fn(() => {
+        throw writeError
+      }),
+      removeItem: vi.fn(),
+    }
+    const { controller, reportPersistenceError } = createController({
+      messages: messagesStore,
+    })
+
+    controller.messagesChanged([createUIMessage('message')])
+
+    expect(reportPersistenceError).toHaveBeenCalledTimes(1)
+    expect(reportPersistenceError).toHaveBeenCalledWith(writeError)
+  })
+
+  it('reports asynchronous write rejections instead of swallowing them', async () => {
+    const writeError = new Error('async write failed')
+    const messagesStore: ChatClientPersistence = {
+      getItem: vi.fn(() => null),
+      setItem: vi.fn(() => Promise.reject(writeError)),
+      removeItem: vi.fn(),
+    }
+    const { controller, reportPersistenceError } = createController({
+      messages: messagesStore,
+    })
+
+    controller.messagesChanged([createUIMessage('message')])
+    await Promise.resolve()
+    await Promise.resolve()
+
+    expect(reportPersistenceError).toHaveBeenCalledTimes(1)
+    expect(reportPersistenceError).toHaveBeenCalledWith(writeError)
+  })
+})
diff --git a/packages/ai-client/tests/cleared-stream-tracker.test.ts b/packages/ai-client/tests/cleared-stream-tracker.test.ts
new file mode 100644
index 000000000..e5aef700c
--- /dev/null
+++ b/packages/ai-client/tests/cleared-stream-tracker.test.ts
@@ -0,0 +1,110 @@
+import { describe, expect, it } from 'vitest'
+import { EventType } from '@tanstack/ai/client'
+import { ClearedStreamTracker } from '../src/cleared-stream-tracker'
+import { createUIMessage } from './test-utils'
+import type { StreamChunk } from '@tanstack/ai/client'
+
+function runStarted(runId: string): StreamChunk {
+  return { type: EventType.RUN_STARTED, threadId: 'thread-1', runId }
+}
+
+function runFinished(runId: string): StreamChunk {
+  return { type: EventType.RUN_FINISHED, threadId: 'thread-1', runId }
+}
+
+function runError(message: string = 'boom'): StreamChunk {
+  return { type: EventType.RUN_ERROR, message }
+}
+
+function textContent(messageId: string): StreamChunk {
+  return { type: EventType.TEXT_MESSAGE_CONTENT, messageId, delta: 'hi' }
+}
+
+function toolCallStart(
+  toolCallId: string,
+  parentMessageId?: string,
+): StreamChunk {
+  return {
+    type: EventType.TOOL_CALL_START,
+    toolCallId,
+    toolCallName: 'tool',
+    toolName: 'tool',
+    ...(parentMessageId ? { parentMessageId } : {}),
+  }
+}
+
+describe('ClearedStreamTracker', () => {
+  it('does not filter chunks before a clear', () => {
+    const tracker = new ClearedStreamTracker()
+
+    expect(tracker.shouldIgnoreChunk(runStarted('run-1'))).toBe(false)
+    expect(tracker.shouldIgnoreChunk(textContent('message-1'))).toBe(false)
+  })
+
+  it('filters cleared message, run, runless, and tool-call chunks', () => {
+    const tracker = new ClearedStreamTracker()
+    tracker.snapshotClear({
+      messages: [createUIMessage('parent-message')],
+      activeRunIds: new Set(['run-1']),
+      currentRunId: null,
+    })
+
+    expect(tracker.shouldIgnoreChunk(runStarted('run-1'))).toBe(true)
+    expect(tracker.shouldIgnoreChunk(textContent('late-message'))).toBe(true)
+    expect(
+      tracker.shouldIgnoreChunk(toolCallStart('tool-1', 'parent-message')),
+    ).toBe(true)
+    expect(tracker.shouldIgnoreChunk(toolCallStart('tool-1'))).toBe(true)
+    expect(tracker.shouldIgnoreChunk(textContent('parent-message'))).toBe(true)
+  })
+
+  it('forgets settled runs and advances across multiple cleared runs', () => {
+    const tracker = new ClearedStreamTracker()
+    tracker.snapshotClear({
+      messages: [],
+      activeRunIds: new Set(['run-1', 'run-2']),
+      currentRunId: null,
+    })
+    tracker.shouldIgnoreChunk(runStarted('run-1'))
+    tracker.shouldIgnoreChunk(runStarted('run-2'))
+
+    tracker.onRunSettled('run-2')
+
+    expect(tracker.shouldIgnoreChunk(runFinished('run-2'))).toBe(false)
+    expect(tracker.shouldIgnoreChunk(textContent('late-run-1'))).toBe(true)
+    expect(tracker.takeRunlessRunId()).toBe('run-1')
+    expect(tracker.takeRunlessRunId()).toBeNull()
+  })
+
+  it('clears active runless tracking after a session error without reviving known ids', () => {
+    const tracker = new ClearedStreamTracker()
+    tracker.snapshotClear({
+      messages: [createUIMessage('cleared-message')],
+      activeRunIds: new Set(['run-1']),
+      currentRunId: null,
+    })
+    tracker.shouldIgnoreChunk(runStarted('run-1'))
+    expect(tracker.shouldIgnoreChunk(runError())).toBe(true)
+
+    tracker.onSessionRunError()
+
+    expect(tracker.shouldIgnoreChunk(textContent('fresh-message'))).toBe(false)
+    expect(tracker.shouldIgnoreChunk(textContent('cleared-message'))).toBe(true)
+  })
+
+  it('resetActiveRuns keeps durable cleared ids while removing runless attribution', () => {
+    const tracker = new ClearedStreamTracker()
+    tracker.snapshotClear({
+      messages: [createUIMessage('cleared-message')],
+      activeRunIds: new Set(['run-1']),
+      currentRunId: null,
+    })
+    tracker.shouldIgnoreChunk(runStarted('run-1'))
+
+    tracker.resetActiveRuns()
+
+    expect(tracker.shouldIgnoreChunk(textContent('fresh-message'))).toBe(false)
+    expect(tracker.shouldIgnoreChunk(runStarted('run-1'))).toBe(true)
+    expect(tracker.shouldIgnoreChunk(textContent('cleared-message'))).toBe(true)
+  })
+})
diff --git a/packages/ai-client/tests/client-persistor.test.ts b/packages/ai-client/tests/client-persistor.test.ts
deleted file mode 100644
index 05cc4380c..000000000
--- a/packages/ai-client/tests/client-persistor.test.ts
+++ /dev/null
@@ -1,497 +0,0 @@
-import { beforeEach, describe, expect, it, vi } from 'vitest'
-import { EventType } from '@tanstack/ai/client'
-import { ChatPersistor } 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'
-
-/** Resolve after pending micro- and macro-tasks have drained. */
-function flushAsync(): Promise<void> {
-  return new Promise((resolve) => setTimeout(resolve, 0))
-}
-
-/** A promise with externally accessible resolve/reject. */
-function createDeferred<T>() {
-  let resolve!: (value: T) => void
-  let reject!: (reason?: unknown) => void
-  const promise = new Promise<T>((res, rej) => {
-    resolve = res
-    reject = rej
-  })
-  return { promise, resolve, reject }
-}
-
-/**
- * Build a persistor wired to `adapter` with a spy `applyMessages` callback so
- * tests can assert what (if anything) gets re-applied to the client.
- */
-function createPersistor(adapter: ChatClientPersistence, id: string = CHAT_ID) {
-  const applyMessages = vi.fn<(messages: Array<UIMessage>) => void>()
-  const persistor = new ChatPersistor(adapter, id, applyMessages)
-  return { persistor, applyMessages }
-}
-
-// --- typed StreamChunk fixtures -------------------------------------------
-// These satisfy the StreamChunk union directly (no casts). The persistor only
-// ever reads `type` and the relevant id field off a chunk, and unit-test chunks
-// are never run through the connection adapter's run-context map, so the run id
-// must live on the chunk itself (only RUN_STARTED/RUN_FINISHED carry one).
-
-function runStarted(runId: string, threadId: string = 'thread-1'): StreamChunk {
-  return { type: EventType.RUN_STARTED, threadId, runId }
-}
-
-function runFinished(
-  runId: string,
-  threadId: string = 'thread-1',
-): StreamChunk {
-  return { type: EventType.RUN_FINISHED, threadId, runId }
-}
-
-function runError(message: string = 'boom'): StreamChunk {
-  return { type: EventType.RUN_ERROR, message }
-}
-
-function textContent(messageId: string, delta: string = 'hi'): StreamChunk {
-  return { type: EventType.TEXT_MESSAGE_CONTENT, messageId, delta }
-}
-
-function toolCallStart(
-  toolCallId: string,
-  parentMessageId?: string,
-): StreamChunk {
-  return {
-    type: EventType.TOOL_CALL_START,
-    toolCallId,
-    toolCallName: 'tool',
-    toolName: 'tool',
-    ...(parentMessageId ? { parentMessageId } : {}),
-  }
-}
-
-function messagesSnapshot(): StreamChunk {
-  return { type: EventType.MESSAGES_SNAPSHOT, messages: [] }
-}
-
-describe('ChatPersistor', () => {
-  describe('readInitial', () => {
-    it('returns the stored messages from a synchronous getItem', () => {
-      const stored = [createUIMessage('m-1')]
-      const adapter = createMockPersistence(stored)
-      const { persistor } = createPersistor(adapter)
-
-      expect(persistor.readInitial()).toBe(stored)
-      expect(adapter.getItem).toHaveBeenCalledWith(CHAT_ID)
-    })
-
-    it('returns the promise from an asynchronous getItem', () => {
-      const stored = [createUIMessage('m-1')]
-      const adapter = createMockPersistence()
-      adapter.getItem = vi.fn(() => Promise.resolve(stored))
-      const { persistor } = createPersistor(adapter)
-
-      expect(persistor.readInitial()).toBeInstanceOf(Promise)
-    })
-
-    it('swallows a throwing getItem and returns undefined', () => {
-      const adapter = createMockPersistence()
-      adapter.getItem = vi.fn(() => {
-        throw new Error('storage unavailable')
-      })
-      const { persistor } = createPersistor(adapter)
-
-      expect(persistor.readInitial()).toBeUndefined()
-    })
-  })
-
-  describe('hydrateAsync', () => {
-    it('applies messages once the promise resolves to an array', async () => {
-      const stored = [createUIMessage('persisted-1')]
-      const { persistor, applyMessages } = createPersistor(
-        createMockPersistence(),
-      )
-
-      persistor.hydrateAsync(Promise.resolve(stored))
-      await flushAsync()
-
-      expect(applyMessages).toHaveBeenCalledWith(stored)
-    })
-
-    it.each([
-      ['null', null],
-      ['undefined', undefined],
-    ])(
-      'does not apply when the promise resolves to %s',
-      async (_label, value) => {
-        const { persistor, applyMessages } = createPersistor(
-          createMockPersistence(),
-        )
-
-        persistor.hydrateAsync(Promise.resolve(value))
-        await flushAsync()
-
-        expect(applyMessages).not.toHaveBeenCalled()
-      },
-    )
-
-    it('does nothing for a synchronous (non-promise) value', async () => {
-      const { persistor, applyMessages } = createPersistor(
-        createMockPersistence(),
-      )
-
-      persistor.hydrateAsync([createUIMessage('m-1')])
-      await flushAsync()
-
-      expect(applyMessages).not.toHaveBeenCalled()
-    })
-
-    it('does not apply if messages changed before hydration resolves', async () => {
-      const deferred = createDeferred<Array<UIMessage>>()
-      const { persistor, applyMessages } = createPersistor(
-        createMockPersistence(),
-      )
-
-      persistor.hydrateAsync(deferred.promise)
-      // A local change lands before the slow getItem resolves.
-      persistor.notifyMessagesChanged([createUIMessage('local-1')])
-      deferred.resolve([createUIMessage('persisted-1')])
-      await flushAsync()
-
-      expect(applyMessages).not.toHaveBeenCalled()
-    })
-
-    it('swallows a rejected hydration promise', async () => {
-      const { persistor, applyMessages } = createPersistor(
-        createMockPersistence(),
-      )
-
-      persistor.hydrateAsync(Promise.reject(new Error('read failed')))
-      await flushAsync()
-
-      expect(applyMessages).not.toHaveBeenCalled()
-    })
-  })
-
-  describe('notifyMessagesChanged', () => {
-    it('persists the messages on change', () => {
-      const adapter = createMockPersistence()
-      const { persistor } = createPersistor(adapter)
-      const messages = [createUIMessage('m-1')]
-
-      persistor.notifyMessagesChanged(messages)
-
-      expect(adapter.setItem).toHaveBeenCalledWith(CHAT_ID, messages)
-    })
-
-    it('persists a snapshot, not the live array reference', () => {
-      const adapter = createMockPersistence()
-      const { persistor } = createPersistor(adapter)
-      const messages = [createUIMessage('m-1')]
-
-      persistor.notifyMessagesChanged(messages)
-      messages.push(createUIMessage('m-2'))
-
-      const persisted = vi.mocked(adapter.setItem).mock.calls[0]?.[1]
-      expect(persisted).toHaveLength(1)
-    })
-
-    it('skips exactly one write after beginClear, then resumes', () => {
-      const adapter = createMockPersistence()
-      const { persistor } = createPersistor(adapter)
-
-      persistor.notifyMessagesChanged([createUIMessage('m-1')])
-      persistor.beginClear()
-      persistor.notifyMessagesChanged([]) // the clear's empty snapshot — skipped
-      persistor.notifyMessagesChanged([createUIMessage('m-2')])
-
-      expect(adapter.setItem).toHaveBeenCalledTimes(2)
-    })
-
-    it('swallows a synchronous setItem error', () => {
-      const adapter = createMockPersistence()
-      adapter.setItem = vi.fn(() => {
-        throw new Error('quota exceeded')
-      })
-      const { persistor } = createPersistor(adapter)
-
-      expect(() =>
-        persistor.notifyMessagesChanged([createUIMessage('m-1')]),
-      ).not.toThrow()
-    })
-
-    it('runs async writes sequentially (FIFO, no overlap)', async () => {
-      const first = createDeferred<void>()
-      const second = createDeferred<void>()
-      const adapter = createMockPersistence()
-      adapter.setItem = vi
-        .fn()
-        .mockReturnValueOnce(first.promise)
-        .mockReturnValueOnce(second.promise)
-      const { persistor } = createPersistor(adapter)
-
-      persistor.notifyMessagesChanged([createUIMessage('a')])
-      persistor.notifyMessagesChanged([createUIMessage('b')])
-      // Second write is queued behind the first and must not have started yet.
-      expect(adapter.setItem).toHaveBeenCalledTimes(1)
-
-      first.resolve()
-      await flushAsync()
-
-      expect(adapter.setItem).toHaveBeenCalledTimes(2)
-      expect(vi.mocked(adapter.setItem).mock.calls[1]?.[1]).toEqual([
-        createUIMessage('b'),
-      ])
-    })
-
-    it('keeps writing after an async write rejects', async () => {
-      const adapter = createMockPersistence()
-      adapter.setItem = vi
-        .fn()
-        .mockRejectedValueOnce(new Error('transient'))
-        .mockResolvedValue(undefined)
-      const { persistor } = createPersistor(adapter)
-
-      persistor.notifyMessagesChanged([createUIMessage('a')])
-      persistor.notifyMessagesChanged([createUIMessage('b')])
-      await flushAsync()
-
-      expect(adapter.setItem).toHaveBeenCalledTimes(2)
-    })
-  })
-
-  describe('remove', () => {
-    it('removes the persisted conversation', () => {
-      const adapter = createMockPersistence()
-      const { persistor } = createPersistor(adapter)
-
-      persistor.remove()
-
-      expect(adapter.removeItem).toHaveBeenCalledWith(CHAT_ID)
-    })
-
-    it('swallows a synchronous removeItem error', () => {
-      const adapter = createMockPersistence()
-      adapter.removeItem = vi.fn(() => {
-        throw new Error('locked')
-      })
-      const { persistor } = createPersistor(adapter)
-
-      expect(() => persistor.remove()).not.toThrow()
-    })
-
-    it('invalidates a queued write that a removal supersedes', async () => {
-      const inFlight = createDeferred<void>()
-      const adapter = createMockPersistence()
-      adapter.setItem = vi
-        .fn()
-        .mockReturnValueOnce(inFlight.promise) // write A (in flight)
-        .mockResolvedValue(undefined) // write B (would run later)
-      const { persistor } = createPersistor(adapter)
-
-      persistor.notifyMessagesChanged([createUIMessage('a')]) // starts, in flight
-      persistor.notifyMessagesChanged([createUIMessage('b')]) // queued behind A
-      persistor.remove() // bumps generation, queued behind B
-
-      inFlight.resolve()
-      await flushAsync()
-
-      // B's generation was superseded by remove(), so only A was written.
-      expect(adapter.setItem).toHaveBeenCalledTimes(1)
-      expect(adapter.removeItem).toHaveBeenCalledTimes(1)
-    })
-  })
-
-  describe('clear-during-stream suppression', () => {
-    it('does not ignore chunks before a clear', () => {
-      const { persistor } = createPersistor(createMockPersistence())
-
-      expect(persistor.shouldIgnoreChunk(runStarted('run-1'))).toBe(false)
-      expect(persistor.shouldIgnoreChunk(textContent('msg-1'))).toBe(false)
-    })
-
-    it('ignores chunks for a message id captured at clear time', () => {
-      const { persistor } = createPersistor(createMockPersistence())
-      persistor.snapshotClear({
-        messages: [createUIMessage('msg-1')],
-        activeRunIds: new Set(),
-        currentRunId: null,
-      })
-
-      expect(persistor.shouldIgnoreChunk(textContent('msg-1'))).toBe(true)
-      expect(persistor.shouldIgnoreChunk(textContent('msg-other'))).toBe(false)
-    })
-
-    it('ignores a RUN_STARTED for an active run captured at clear time', () => {
-      const { persistor } = createPersistor(createMockPersistence())
-      persistor.snapshotClear({
-        messages: [],
-        activeRunIds: new Set(['run-1']),
-        currentRunId: null,
-      })
-
-      expect(persistor.shouldIgnoreChunk(runStarted('run-1'))).toBe(true)
-    })
-
-    it('ignores the in-flight currentRunId captured at clear time', () => {
-      const { persistor } = createPersistor(createMockPersistence())
-      persistor.snapshotClear({
-        messages: [],
-        activeRunIds: new Set(),
-        currentRunId: 'run-current',
-      })
-
-      expect(persistor.shouldIgnoreChunk(runStarted('run-current'))).toBe(true)
-    })
-
-    it('ignores runless content chunks belonging to a cleared run', () => {
-      const { persistor } = createPersistor(createMockPersistence())
-      persistor.snapshotClear({
-        messages: [],
-        activeRunIds: new Set(['run-1']),
-        currentRunId: null,
-      })
-      // The cleared run starts again, pinning it as the current runless run.
-      persistor.shouldIgnoreChunk(runStarted('run-1'))
-
-      expect(persistor.shouldIgnoreChunk(textContent('late-msg'))).toBe(true)
-      expect(persistor.shouldIgnoreChunk(messagesSnapshot())).toBe(true)
-    })
-
-    it('ignores tool chunks by cleared parentMessageId and remembers the toolCallId', () => {
-      const { persistor } = createPersistor(createMockPersistence())
-      persistor.snapshotClear({
-        messages: [createUIMessage('parent-msg')],
-        activeRunIds: new Set(),
-        currentRunId: null,
-      })
-
-      // First seen via its parent message id...
-      expect(
-        persistor.shouldIgnoreChunk(toolCallStart('tc-1', 'parent-msg')),
-      ).toBe(true)
-      // ...then a later chunk for the same tool call (no parent) is still ignored.
-      expect(persistor.shouldIgnoreChunk(toolCallStart('tc-1'))).toBe(true)
-    })
-  })
-
-  describe('run lifecycle hooks', () => {
-    beforeEach(() => {
-      vi.clearAllMocks()
-    })
-
-    it('forgets a settled run so a later run with the same id is not ignored', () => {
-      const { persistor } = createPersistor(createMockPersistence())
-      persistor.snapshotClear({
-        messages: [],
-        activeRunIds: new Set(['run-1']),
-        currentRunId: null,
-      })
-      expect(persistor.shouldIgnoreChunk(runStarted('run-1'))).toBe(true)
-
-      persistor.onRunSettled('run-1')
-
-      expect(persistor.shouldIgnoreChunk(runStarted('run-1'))).toBe(false)
-    })
-
-    it('stops ignoring runless chunks after a session-level run error', () => {
-      const { persistor } = createPersistor(createMockPersistence())
-      persistor.snapshotClear({
-        messages: [],
-        activeRunIds: new Set(['run-1']),
-        currentRunId: null,
-      })
-      persistor.shouldIgnoreChunk(runStarted('run-1'))
-      expect(persistor.shouldIgnoreChunk(textContent('late-1'))).toBe(true)
-
-      persistor.onSessionRunError()
-
-      // A fresh runless chunk is no longer attributed to the cleared run. (An
-      // already-seen message id stays ignored — shouldIgnoreChunk records it.)
-      expect(persistor.shouldIgnoreChunk(textContent('late-2'))).toBe(false)
-    })
-
-    it('takeRunlessRunId returns and clears the current runless run, then null', () => {
-      const { persistor } = createPersistor(createMockPersistence())
-      persistor.snapshotClear({
-        messages: [],
-        activeRunIds: new Set(['run-1']),
-        currentRunId: null,
-      })
-      persistor.shouldIgnoreChunk(runStarted('run-1'))
-
-      expect(persistor.takeRunlessRunId()).toBe('run-1')
-      expect(persistor.takeRunlessRunId()).toBeNull()
-      // The drained run is no longer pinned, so runless chunks aren't ignored.
-      expect(persistor.shouldIgnoreChunk(textContent('late'))).toBe(false)
-    })
-
-    it('resetIgnored only clears active-run markers, not cleared ids', () => {
-      const { persistor } = createPersistor(createMockPersistence())
-      persistor.snapshotClear({
-        messages: [createUIMessage('msg-1')],
-        activeRunIds: new Set(['run-1']),
-        currentRunId: null,
-      })
-
-      persistor.resetIgnored()
-
-      // Cleared run/message ids survive a reset (they outlive the active run).
-      expect(persistor.shouldIgnoreChunk(runStarted('run-1'))).toBe(true)
-      expect(persistor.shouldIgnoreChunk(textContent('msg-1'))).toBe(true)
-    })
-
-    it('does not ignore an unrelated runId-less run error', () => {
-      const { persistor } = createPersistor(createMockPersistence())
-
-      expect(persistor.shouldIgnoreChunk(runError())).toBe(false)
-    })
-
-    it('onRunStarted for a non-cleared run does not suppress runless chunks', () => {
-      const { persistor } = createPersistor(createMockPersistence())
-
-      // Pinning a live (never-cleared) run must not start swallowing its output.
-      persistor.onRunStarted('run-live')
-
-      expect(persistor.shouldIgnoreChunk(textContent('content'))).toBe(false)
-    })
-
-    it('advances the runless pointer when the active run finishes', () => {
-      const { persistor } = createPersistor(createMockPersistence())
-      persistor.snapshotClear({
-        messages: [],
-        activeRunIds: new Set(['run-1', 'run-2']),
-        currentRunId: null,
-      })
-      persistor.shouldIgnoreChunk(runStarted('run-1'))
-      persistor.shouldIgnoreChunk(runStarted('run-2'))
-
-      // run-2 was the pinned runless run; settling it falls back to run-1.
-      persistor.onRunSettled('run-2')
-
-      expect(persistor.shouldIgnoreChunk(runFinished('run-2'))).toBe(false)
-      expect(persistor.shouldIgnoreChunk(textContent('late'))).toBe(true)
-    })
-
-    it('keeps suppressing a second cleared run after the first drains via a runless error', () => {
-      const { persistor } = createPersistor(createMockPersistence())
-      persistor.snapshotClear({
-        messages: [],
-        activeRunIds: new Set(['run-1', 'run-2']),
-        currentRunId: null,
-      })
-      persistor.shouldIgnoreChunk(runStarted('run-1'))
-      persistor.shouldIgnoreChunk(runStarted('run-2')) // run-2 now pinned
-
-      // A runId-less RUN_ERROR drains the pinned run (run-2)...
-      expect(persistor.takeRunlessRunId()).toBe('run-2')
-
-      // ...but run-1 is still cleared, so its runless content stays suppressed
-      // instead of leaking through once the pointer advances back to it.
-      expect(persistor.shouldIgnoreChunk(textContent('late-from-run-1'))).toBe(
-        true,
-      )
-    })
-  })
-})
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-client/tests/storage-adapters-types.test-d.ts b/packages/ai-client/tests/storage-adapters-types.test-d.ts
new file mode 100644
index 000000000..e0312882d
--- /dev/null
+++ b/packages/ai-client/tests/storage-adapters-types.test-d.ts
@@ -0,0 +1,45 @@
+import {
+  indexedDBPersistence,
+  localStoragePersistence,
+  sessionStoragePersistence,
+} from '../src/index'
+import type {
+  ChatPersistenceOptions,
+  ChatStorageAdapter,
+  UIMessage,
+} from '../src/index'
+
+const local = localStoragePersistence<{
+  count: number
+  labels: Array<string>
+}>()
+const session = sessionStoragePersistence<Array<string>>()
+const indexed = indexedDBPersistence<{ createdAt: Date }>()
+
+const localAdapter: ChatStorageAdapter<{
+  count: number
+  labels: Array<string>
+}> = local
+const sessionAdapter: ChatStorageAdapter<Array<string>> = session
+const indexedAdapter: ChatStorageAdapter<{ createdAt: Date }> = indexed
+
+// @ts-expect-error - default Web Storage JSON cannot preserve Date instances
+localStoragePersistence<{ createdAt: Date }>()
+// @ts-expect-error - both codec directions are required for non-JSON values
+sessionStoragePersistence<{ createdAt: Date }>({
+  serialize: (value) => value.createdAt.toISOString(),
+})
+
+localStoragePersistence<{ createdAt: Date }>({
+  serialize: (value) => value.createdAt.toISOString(),
+  deserialize: (value) => ({ createdAt: new Date(value) }),
+})
+
+declare const messagePersistence: ChatStorageAdapter<Array<UIMessage>>
+// @ts-expect-error - chat persistence must name the client lane explicitly
+const directPersistence: ChatPersistenceOptions = messagePersistence
+
+void localAdapter
+void sessionAdapter
+void indexedAdapter
+void directPersistence
diff --git a/packages/ai-client/tests/storage-adapters.test.ts b/packages/ai-client/tests/storage-adapters.test.ts
new file mode 100644
index 000000000..d58c37200
--- /dev/null
+++ b/packages/ai-client/tests/storage-adapters.test.ts
@@ -0,0 +1,173 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+import { IDBFactory } from 'fake-indexeddb'
+import {
+  StorageUnavailableError,
+  indexedDBPersistence,
+  localStoragePersistence,
+  sessionStoragePersistence,
+} from '../src/storage-adapters'
+
+function memoryStorage(): Storage {
+  const values = new Map<string, string>()
+  return {
+    get length() {
+      return values.size
+    },
+    clear: () => values.clear(),
+    getItem: (key) => values.get(key) ?? null,
+    key: (index) => [...values.keys()][index] ?? null,
+    removeItem: (key) => {
+      values.delete(key)
+    },
+    setItem: (key, value) => {
+      values.set(key, value)
+    },
+  }
+}
+
+function openDatabase(factory: IDBFactory, name: string, version: number) {
+  return new Promise<IDBDatabase>((resolve, reject) => {
+    const request = factory.open(name, version)
+    request.onerror = () => reject(request.error)
+    request.onsuccess = () => resolve(request.result)
+  })
+}
+
+afterEach(() => {
+  vi.unstubAllGlobals()
+  vi.restoreAllMocks()
+})
+
+describe.each([
+  ['localStoragePersistence', 'localStorage', localStoragePersistence],
+  ['sessionStoragePersistence', 'sessionStorage', sessionStoragePersistence],
+] as const)('%s', (_name, globalName, createAdapter) => {
+  beforeEach(() => {
+    vi.stubGlobal(globalName, memoryStorage())
+  })
+
+  it('round-trips JSON values under the configured prefix and removes them', () => {
+    const adapter = createAdapter<{ count: number; labels: Array<string> }>({
+      keyPrefix: 'custom:',
+    })
+    const storage = globalThis[globalName]
+
+    adapter.setItem('entry', { count: 2, labels: ['a', 'b'] })
+
+    expect(storage.getItem('custom:entry')).toBe(
+      JSON.stringify({ count: 2, labels: ['a', 'b'] }),
+    )
+    expect(adapter.getItem('entry')).toEqual({
+      count: 2,
+      labels: ['a', 'b'],
+    })
+    adapter.removeItem('entry')
+    expect(adapter.getItem('entry')).toBeNull()
+  })
+
+  it('uses existing codec hooks for values outside JSON semantics', () => {
+    const adapter = createAdapter<{ createdAt: Date }>({
+      serialize: (value) => value.createdAt.toISOString(),
+      deserialize: (value) => ({ createdAt: new Date(value) }),
+    })
+
+    adapter.setItem('dated', { createdAt: new Date('2026-01-02T00:00:00Z') })
+
+    expect(adapter.getItem('dated')).toEqual({
+      createdAt: new Date('2026-01-02T00:00:00Z'),
+    })
+  })
+
+  it('constructs during SSR but throws an observable unavailable error on use', () => {
+    vi.stubGlobal(globalName, undefined)
+    const adapter = createAdapter<{ value: string }>()
+
+    expect(() => adapter.getItem('entry')).toThrow(StorageUnavailableError)
+    expect(() => adapter.setItem('entry', { value: 'x' })).toThrow(
+      StorageUnavailableError,
+    )
+    expect(() => adapter.removeItem('entry')).toThrow(StorageUnavailableError)
+  })
+})
+
+describe('indexedDBPersistence', () => {
+  let factory: IDBFactory
+
+  beforeEach(() => {
+    factory = new IDBFactory()
+    vi.stubGlobal('indexedDB', factory)
+  })
+
+  it('round-trips structured-clone values, namespaces keys, and removes them', async () => {
+    const first = indexedDBPersistence<{ createdAt: Date }>({
+      databaseName: 'roundtrip',
+      keyPrefix: 'first:',
+    })
+    const second = indexedDBPersistence<{ createdAt: Date }>({
+      databaseName: 'roundtrip',
+      keyPrefix: 'second:',
+    })
+    const value = { createdAt: new Date('2026-03-04T00:00:00Z') }
+
+    await first.setItem('entry', value)
+    await second.setItem('entry', {
+      createdAt: new Date('2026-05-06T00:00:00Z'),
+    })
+
+    await expect(first.getItem('entry')).resolves.toEqual(value)
+    await expect(second.getItem('entry')).resolves.not.toEqual(value)
+    await first.removeItem('entry')
+    await expect(first.getItem('entry')).resolves.toBeUndefined()
+    await expect(second.getItem('entry')).resolves.toBeDefined()
+  })
+
+  it('caches its opened database connection', async () => {
+    const open = vi.spyOn(factory, 'open')
+    const adapter = indexedDBPersistence<string>({ databaseName: 'cached' })
+
+    await adapter.setItem('a', 'one')
+    await adapter.getItem('a')
+    await adapter.removeItem('a')
+
+    expect(open).toHaveBeenCalledTimes(1)
+  })
+
+  it('closes its connection on versionchange so upgrades are not blocked', async () => {
+    const adapter = indexedDBPersistence<string>({
+      databaseName: 'versionchange',
+    })
+    await adapter.setItem('a', 'one')
+
+    const upgraded = await openDatabase(factory, 'versionchange', 2)
+
+    expect(upgraded.version).toBe(2)
+    upgraded.close()
+  })
+
+  it('rejects open failures and does not cache the rejection', async () => {
+    const openError = new Error('open failed')
+    const open = vi.spyOn(factory, 'open').mockImplementation(() => {
+      throw openError
+    })
+    const adapter = indexedDBPersistence<string>({ databaseName: 'failed' })
+
+    await expect(adapter.getItem('a')).rejects.toBe(openError)
+    await expect(adapter.getItem('a')).rejects.toBe(openError)
+    expect(open).toHaveBeenCalledTimes(2)
+  })
+
+  it('constructs during SSR and rejects operations when IndexedDB is unavailable', async () => {
+    vi.stubGlobal('indexedDB', undefined)
+    const adapter = indexedDBPersistence<string>({ databaseName: 'ssr' })
+
+    await expect(adapter.getItem('a')).rejects.toBeInstanceOf(
+      StorageUnavailableError,
+    )
+    await expect(adapter.setItem('a', 'one')).rejects.toBeInstanceOf(
+      StorageUnavailableError,
+    )
+    await expect(adapter.removeItem('a')).rejects.toBeInstanceOf(
+      StorageUnavailableError,
+    )
+  })
+})
diff --git a/packages/ai-client/tests/test-utils.ts b/packages/ai-client/tests/test-utils.ts
index 82d37ddc2..5541613db 100644
--- a/packages/ai-client/tests/test-utils.ts
+++ b/packages/ai-client/tests/test-utils.ts
@@ -1,7 +1,6 @@
-import { vi } from 'vitest'
 import type { ConnectConnectionAdapter } from '../src/connection-adapters'
 import type { ModelMessage, StreamChunk } from '@tanstack/ai/client'
-import type { ChatClientPersistence, UIMessage } from '../src/types'
+import type { UIMessage } from '../src/types'
 
 /**
  * Build a minimal text {@link UIMessage} for tests.
@@ -14,20 +13,6 @@ export function createUIMessage(
   return { id, role, parts: [{ type: 'text', content: text }] }
 }
 
-/**
- * Create a persistence adapter whose three methods are vitest spies. `getItem`
- * synchronously returns `initial` (defaults to `undefined`); override individual
- * methods via the returned object's `.mock*` helpers for async/error scenarios.
- */
-export function createMockPersistence(
-  initial?: Array<UIMessage> | null,
-): ChatClientPersistence {
-  return {
-    getItem: vi.fn(() => initial),
-    setItem: vi.fn(),
-    removeItem: vi.fn(),
-  }
-}
 /**
  * Options for creating a mock connection adapter
  */
diff --git a/packages/ai-event-client/src/index.ts b/packages/ai-event-client/src/index.ts
index 0bd1fdc12..815c8a565 100644
--- a/packages/ai-event-client/src/index.ts
+++ b/packages/ai-event-client/src/index.ts
@@ -614,6 +614,8 @@ export interface SummarizeUsageEvent extends BaseEventContext {
 /** Emitted when an image request starts. */
 export interface ImageRequestStartedEvent extends BaseEventContext {
   requestId: string
+  threadId?: string
+  runId?: string
   provider: string
   model: string
   prompt: string
@@ -630,6 +632,8 @@ export interface ImageRequestStartedEvent extends BaseEventContext {
 /** Emitted when an image request completes. */
 export interface ImageRequestCompletedEvent extends BaseEventContext {
   requestId: string
+  threadId?: string
+  runId?: string
   provider: string
   model: string
   images: Array<{ url?: string; b64Json?: string }>
@@ -639,6 +643,8 @@ export interface ImageRequestCompletedEvent extends BaseEventContext {
 /** Emitted when image usage metrics are available. */
 export interface ImageUsageEvent extends BaseEventContext {
   requestId: string
+  threadId?: string
+  runId?: string
   model: string
   usage: TokenUsage
 }
@@ -650,6 +656,8 @@ export interface ImageUsageEvent extends BaseEventContext {
 /** Emitted when a speech request starts. */
 export interface SpeechRequestStartedEvent extends BaseEventContext {
   requestId: string
+  threadId?: string
+  runId?: string
   provider: string
   model: string
   text: string
@@ -661,6 +669,8 @@ export interface SpeechRequestStartedEvent extends BaseEventContext {
 /** Emitted when a speech request completes. */
 export interface SpeechRequestCompletedEvent extends BaseEventContext {
   requestId: string
+  threadId?: string
+  runId?: string
   provider: string
   model: string
   audio: string
@@ -673,6 +683,8 @@ export interface SpeechRequestCompletedEvent extends BaseEventContext {
 /** Emitted when speech usage metrics are available. */
 export interface SpeechUsageEvent extends BaseEventContext {
   requestId: string
+  threadId?: string
+  runId?: string
   model: string
   usage: TokenUsage
 }
@@ -684,6 +696,8 @@ export interface SpeechUsageEvent extends BaseEventContext {
 /** Emitted when a transcription request starts. */
 export interface TranscriptionRequestStartedEvent extends BaseEventContext {
   requestId: string
+  threadId?: string
+  runId?: string
   provider: string
   model: string
   language?: string
@@ -694,6 +708,8 @@ export interface TranscriptionRequestStartedEvent extends BaseEventContext {
 /** Emitted when a transcription request completes. */
 export interface TranscriptionRequestCompletedEvent extends BaseEventContext {
   requestId: string
+  threadId?: string
+  runId?: string
   provider: string
   model: string
   text: string
@@ -704,6 +720,8 @@ export interface TranscriptionRequestCompletedEvent extends BaseEventContext {
 /** Emitted when transcription usage metrics are available. */
 export interface TranscriptionUsageEvent extends BaseEventContext {
   requestId: string
+  threadId?: string
+  runId?: string
   model: string
   usage: TokenUsage
 }
@@ -715,6 +733,8 @@ export interface TranscriptionUsageEvent extends BaseEventContext {
 /** Emitted when an audio generation request starts. */
 export interface AudioRequestStartedEvent extends BaseEventContext {
   requestId: string
+  threadId?: string
+  runId?: string
   provider: string
   model: string
   prompt: string
@@ -743,6 +763,8 @@ export type AudioRequestCompletedAudio =
 /** Emitted when an audio generation request completes. */
 export interface AudioRequestCompletedEvent extends BaseEventContext {
   requestId: string
+  threadId?: string
+  runId?: string
   provider: string
   model: string
   audio: AudioRequestCompletedAudio
@@ -752,6 +774,8 @@ export interface AudioRequestCompletedEvent extends BaseEventContext {
 /** Emitted when an audio generation request fails. */
 export interface AudioRequestErrorEvent extends BaseEventContext {
   requestId: string
+  threadId?: string
+  runId?: string
   provider: string
   model: string
   error: { message: string; name?: string }
@@ -761,6 +785,8 @@ export interface AudioRequestErrorEvent extends BaseEventContext {
 /** Emitted when a speech generation request fails. */
 export interface SpeechRequestErrorEvent extends BaseEventContext {
   requestId: string
+  threadId?: string
+  runId?: string
   provider: string
   model: string
   error: { message: string; name?: string }
@@ -770,6 +796,8 @@ export interface SpeechRequestErrorEvent extends BaseEventContext {
 /** Emitted when a transcription request fails. */
 export interface TranscriptionRequestErrorEvent extends BaseEventContext {
   requestId: string
+  threadId?: string
+  runId?: string
   provider: string
   model: string
   error: { message: string; name?: string }
@@ -779,6 +807,8 @@ export interface TranscriptionRequestErrorEvent extends BaseEventContext {
 /** Emitted when audio usage metrics are available. */
 export interface AudioUsageEvent extends BaseEventContext {
   requestId: string
+  threadId?: string
+  runId?: string
   model: string
   usage: TokenUsage
 }
@@ -790,6 +820,8 @@ export interface AudioUsageEvent extends BaseEventContext {
 /** Emitted when a video request starts. */
 export interface VideoRequestStartedEvent extends BaseEventContext {
   requestId: string
+  threadId?: string
+  runId?: string
   provider: string
   model: string
   requestType: 'create' | 'status' | 'url'
@@ -802,6 +834,8 @@ export interface VideoRequestStartedEvent extends BaseEventContext {
 /** Emitted when a video request completes. */
 export interface VideoRequestCompletedEvent extends BaseEventContext {
   requestId: string
+  threadId?: string
+  runId?: string
   provider: string
   model: string
   requestType: 'create' | 'status' | 'url'
@@ -816,6 +850,8 @@ export interface VideoRequestCompletedEvent extends BaseEventContext {
 /** Emitted when video usage metrics are available. */
 export interface VideoUsageEvent extends BaseEventContext {
   requestId: string
+  threadId?: string
+  runId?: string
   model: string
   usage: TokenUsage
 }
diff --git a/packages/ai-event-client/tests/emit.test.ts b/packages/ai-event-client/tests/emit.test.ts
index 34afc58e0..fa17e3be3 100644
--- a/packages/ai-event-client/tests/emit.test.ts
+++ b/packages/ai-event-client/tests/emit.test.ts
@@ -86,6 +86,32 @@ describe('AI devtools event emission', () => {
     expect(dispatchedEvents).toHaveLength(0)
   })
 
+  it('preserves thread and run identifiers on generation events', () => {
+    const eventClientEmit = vi
+      .spyOn(aiEventClient, 'emit')
+      .mockImplementation(() => undefined)
+    const payload = {
+      eventId: 'event-generation-1',
+      timestamp: 2,
+      requestId: 'request-generation-1',
+      provider: 'image-provider',
+      model: 'image-model',
+      prompt: 'draw a square',
+      threadId: 'thread-1',
+      runId: 'run-1',
+    } satisfies AIDevtoolsEventMap['image:request:started']
+
+    emitAIDevtoolsEvent('image:request:started', payload)
+
+    expect(eventClientEmit).toHaveBeenCalledWith(
+      'image:request:started',
+      expect.objectContaining({
+        threadId: 'thread-1',
+        runId: 'run-1',
+      }),
+    )
+  })
+
   it('can dispatch directly to the devtools bus without using the event client', () => {
     const eventClientEmit = vi
       .spyOn(aiEventClient, 'emit')
diff --git a/packages/ai-event-client/tests/generation-events-types.test-d.ts b/packages/ai-event-client/tests/generation-events-types.test-d.ts
new file mode 100644
index 000000000..b4caec9fa
--- /dev/null
+++ b/packages/ai-event-client/tests/generation-events-types.test-d.ts
@@ -0,0 +1,27 @@
+import type { AIDevtoolsEventMap } from '../src'
+
+const imageStarted = {
+  eventId: 'event-1',
+  timestamp: 1,
+  requestId: 'request-1',
+  provider: 'image-provider',
+  model: 'image-model',
+  prompt: 'draw a square',
+  threadId: 'thread-1',
+  runId: 'run-1',
+} satisfies AIDevtoolsEventMap['image:request:started']
+
+void imageStarted
+
+const staleCursor = {
+  eventId: 'event-2',
+  timestamp: 2,
+  requestId: 'request-2',
+  provider: 'image-provider',
+  model: 'image-model',
+  prompt: 'draw a circle',
+  // @ts-expect-error generation event cursors are owned by stream adapters
+  cursor: 'adapter-offset',
+} satisfies AIDevtoolsEventMap['image:request:started']
+
+void staleCursor
diff --git a/packages/ai-persistence-cloudflare/bin/tanstack-ai-cloudflare-migrations.mjs b/packages/ai-persistence-cloudflare/bin/tanstack-ai-cloudflare-migrations.mjs
new file mode 100644
index 000000000..0a4de6588
--- /dev/null
+++ b/packages/ai-persistence-cloudflare/bin/tanstack-ai-cloudflare-migrations.mjs
@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+import '../dist/esm/cli.js'
diff --git a/packages/ai-persistence-cloudflare/migrations/0000_tanstack_ai_initial.sql b/packages/ai-persistence-cloudflare/migrations/0000_tanstack_ai_initial.sql
new file mode 100644
index 000000000..3e5570ec1
--- /dev/null
+++ b/packages/ai-persistence-cloudflare/migrations/0000_tanstack_ai_initial.sql
@@ -0,0 +1,32 @@
+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-cloudflare/package.json b/packages/ai-persistence-cloudflare/package.json
new file mode 100644
index 000000000..c7bc6b2ef
--- /dev/null
+++ b/packages/ai-persistence-cloudflare/package.json
@@ -0,0 +1,64 @@
+{
+  "name": "@tanstack/ai-persistence-cloudflare",
+  "version": "0.0.0",
+  "description": "Cloudflare D1 and Durable Object state persistence for TanStack AI.",
+  "author": "",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/TanStack/ai.git",
+    "directory": "packages/ai-persistence-cloudflare"
+  },
+  "keywords": [
+    "ai",
+    "tanstack",
+    "persistence",
+    "cloudflare",
+    "d1",
+    "durable-objects"
+  ],
+  "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"
+    }
+  },
+  "bin": {
+    "tanstack-ai-cloudflare-migrations": "./bin/tanstack-ai-cloudflare-migrations.mjs"
+  },
+  "files": [
+    "bin",
+    "dist",
+    "migrations",
+    "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": {
+    "@cloudflare/workers-types": ">=4.20260317.1",
+    "@tanstack/ai": "workspace:^",
+    "@tanstack/ai-persistence": "workspace:^",
+    "@tanstack/ai-persistence-drizzle": "workspace:^",
+    "drizzle-orm": ">=0.44.0"
+  },
+  "devDependencies": {
+    "@cloudflare/workers-types": "^4.20260317.1",
+    "@tanstack/ai": "workspace:*",
+    "@tanstack/ai-persistence": "workspace:*",
+    "@tanstack/ai-persistence-drizzle": "workspace:*",
+    "@vitest/coverage-v8": "4.0.14",
+    "drizzle-orm": "^0.45.0",
+    "miniflare": "^4.20260609.0"
+  }
+}
diff --git a/packages/ai-persistence-cloudflare/src/assets.d.ts b/packages/ai-persistence-cloudflare/src/assets.d.ts
new file mode 100644
index 000000000..b04692701
--- /dev/null
+++ b/packages/ai-persistence-cloudflare/src/assets.d.ts
@@ -0,0 +1,4 @@
+declare module '*.sql?raw' {
+  const contents: string
+  export default contents
+}
diff --git a/packages/ai-persistence-cloudflare/src/assets/0000_tanstack_ai_initial.sql b/packages/ai-persistence-cloudflare/src/assets/0000_tanstack_ai_initial.sql
new file mode 100644
index 000000000..3e5570ec1
--- /dev/null
+++ b/packages/ai-persistence-cloudflare/src/assets/0000_tanstack_ai_initial.sql
@@ -0,0 +1,32 @@
+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-cloudflare/src/bindings.ts b/packages/ai-persistence-cloudflare/src/bindings.ts
new file mode 100644
index 000000000..cdf01afac
--- /dev/null
+++ b/packages/ai-persistence-cloudflare/src/bindings.ts
@@ -0,0 +1,24 @@
+export interface DurableObjectStubBinding {
+  fetch: (
+    input: Request | string | URL,
+    init?: RequestInit,
+  ) => Promise<Response>
+}
+
+/** The Durable Object namespace surface used by the lock client. */
+export interface DurableObjectNamespaceBinding<TId = unknown> {
+  idFromName: (name: string) => TId
+  get: (id: TId) => DurableObjectStubBinding
+}
+
+export interface LockDurableObjectStorage {
+  get: (key: string) => Promise<unknown>
+  put: (key: string, value: unknown) => Promise<void>
+  delete: (key: string) => Promise<boolean>
+  setAlarm: (timestamp: number) => Promise<void>
+  deleteAlarm: () => Promise<void>
+}
+
+export interface LockDurableObjectState {
+  storage: LockDurableObjectStorage
+}
diff --git a/packages/ai-persistence-cloudflare/src/cli.ts b/packages/ai-persistence-cloudflare/src/cli.ts
new file mode 100644
index 000000000..6d17f2681
--- /dev/null
+++ b/packages/ai-persistence-cloudflare/src/cli.ts
@@ -0,0 +1,4 @@
+#!/usr/bin/env node
+import { runCloudflareMigrationsCli } from './migration-cli'
+
+await runCloudflareMigrationsCli(process.argv.slice(2))
diff --git a/packages/ai-persistence-cloudflare/src/d1.ts b/packages/ai-persistence-cloudflare/src/d1.ts
new file mode 100644
index 000000000..011e70ce4
--- /dev/null
+++ b/packages/ai-persistence-cloudflare/src/d1.ts
@@ -0,0 +1,13 @@
+import { drizzle } from 'drizzle-orm/d1'
+import { drizzlePersistence, schema } from '@tanstack/ai-persistence-drizzle'
+
+/** Create the structured stores owned by a migrated Cloudflare D1 binding. */
+export function createD1Stores(d1: D1Database) {
+  const persistence = drizzlePersistence(drizzle(d1, { schema }))
+  return {
+    messages: persistence.stores.messages,
+    runs: persistence.stores.runs,
+    interrupts: persistence.stores.interrupts,
+    metadata: persistence.stores.metadata,
+  }
+}
diff --git a/packages/ai-persistence-cloudflare/src/index.ts b/packages/ai-persistence-cloudflare/src/index.ts
new file mode 100644
index 000000000..d9cb63439
--- /dev/null
+++ b/packages/ai-persistence-cloudflare/src/index.ts
@@ -0,0 +1,82 @@
+import { createD1Stores } from './d1'
+import { createDurableObjectLockStore } from './locks'
+import type {
+  AIPersistence,
+  AIPersistenceStores,
+  InterruptStore,
+  MessageStore,
+  MetadataStore,
+  RunStore,
+} from '@tanstack/ai-persistence'
+import type { LockStore } from '@tanstack/ai'
+import type { DurableObjectLockStoreOptions } from './locks'
+
+export { createD1Stores } from './d1'
+export {
+  CloudflareLockDurableObject,
+  createDurableObjectLockStore,
+} from './locks'
+export { d1Migrations } from './migrations'
+export type { D1Migration } from './migrations'
+export type { DurableObjectLockStoreOptions } from './locks'
+export type {
+  DurableObjectNamespaceBinding,
+  DurableObjectStubBinding,
+  LockDurableObjectState,
+  LockDurableObjectStorage,
+} from './bindings'
+
+export interface CloudflarePersistenceOptions {
+  d1?: D1Database
+  durableObjects?: DurableObjectNamespace
+  lockOptions?: DurableObjectLockStoreOptions
+}
+
+interface D1Stores {
+  messages: MessageStore
+  runs: RunStore
+  interrupts: InterruptStore
+  metadata: MetadataStore
+}
+
+interface DurableObjectStores {
+  locks: LockStore
+}
+
+type BindingStores<
+  TOptions,
+  TKey extends PropertyKey,
+  TStores,
+> = TKey extends keyof TOptions
+  ? undefined extends TOptions[TKey]
+    ? Partial<TStores>
+    : TStores
+  : {}
+
+type Simplify<T> = { [TKey in keyof T]: T[TKey] }
+
+export type CloudflarePersistenceStores<TOptions> = Simplify<
+  BindingStores<TOptions, 'd1', D1Stores> &
+    BindingStores<TOptions, 'durableObjects', DurableObjectStores>
+>
+
+/**
+ * Compose only the stores backed by the supplied Cloudflare bindings.
+ * Binding keys remain exact in the return type, including optional bindings.
+ */
+export function cloudflarePersistence<
+  const TOptions extends CloudflarePersistenceOptions,
+>(options: TOptions): AIPersistence<CloudflarePersistenceStores<TOptions>>
+export function cloudflarePersistence(
+  options: CloudflarePersistenceOptions,
+): AIPersistence {
+  const stores: AIPersistenceStores = {}
+  if (options.d1) Object.assign(stores, createD1Stores(options.d1))
+  if (options.durableObjects) {
+    stores.locks = createDurableObjectLockStore(
+      options.durableObjects,
+      options.lockOptions,
+    )
+  }
+  return { stores }
+}
diff --git a/packages/ai-persistence-cloudflare/src/locks.ts b/packages/ai-persistence-cloudflare/src/locks.ts
new file mode 100644
index 000000000..871ff0076
--- /dev/null
+++ b/packages/ai-persistence-cloudflare/src/locks.ts
@@ -0,0 +1,376 @@
+import type { LockStore } from '@tanstack/ai'
+import type {
+  DurableObjectNamespaceBinding,
+  DurableObjectStubBinding,
+  LockDurableObjectState,
+} from './bindings'
+
+interface LeaseRecord {
+  ownerId: string
+  expiresAt: number
+}
+
+interface LeaseRequest {
+  ownerId: string
+  leaseDurationMs: number
+}
+
+export interface DurableObjectLockStoreOptions {
+  /** Duration of each lock lease. Defaults to 30 seconds. */
+  leaseDurationMs?: number
+  /** Renewal cadence. Defaults to one third of the lease duration. */
+  renewIntervalMs?: number
+  /** Maximum time spent retrying a contended acquire. Defaults to 30 seconds. */
+  acquireTimeoutMs?: number
+  /** Delay between contended acquire attempts. Defaults to 50 milliseconds. */
+  retryDelayMs?: number
+  /** Override owner ID generation, primarily for deterministic runtimes/tests. */
+  createOwnerId?: () => string
+}
+
+interface ResolvedLockOptions {
+  leaseDurationMs: number
+  renewIntervalMs: number
+  acquireTimeoutMs: number
+  retryDelayMs: number
+  createOwnerId: () => string
+}
+
+type SettledValue<T> =
+  | { status: 'fulfilled'; value: T }
+  | { status: 'rejected'; reason: unknown }
+
+const leaseKey = 'lease'
+
+function isLeaseRecord(value: unknown): value is LeaseRecord {
+  return (
+    value !== null &&
+    typeof value === 'object' &&
+    'ownerId' in value &&
+    typeof value.ownerId === 'string' &&
+    'expiresAt' in value &&
+    typeof value.expiresAt === 'number'
+  )
+}
+
+function isLeaseRequest(value: unknown): value is LeaseRequest {
+  return (
+    value !== null &&
+    typeof value === 'object' &&
+    'ownerId' in value &&
+    typeof value.ownerId === 'string' &&
+    value.ownerId.length > 0 &&
+    'leaseDurationMs' in value &&
+    typeof value.leaseDurationMs === 'number' &&
+    Number.isFinite(value.leaseDurationMs) &&
+    value.leaseDurationMs > 0
+  )
+}
+
+function response(status: number): Response {
+  return new Response(null, { status })
+}
+
+/**
+ * Durable Object class backing distributed lock leases.
+ *
+ * Bind this class in Wrangler and pass the resulting namespace to
+ * `cloudflarePersistence({ durableObjects })`.
+ *
+ * SECURITY: this DO must ONLY be reachable through its namespace binding (via
+ * `createDurableObjectLockStore`). Its `fetch` handler trusts the caller's
+ * `ownerId` and performs no authentication, so routing public HTTP straight to
+ * this class exposes an unauthenticated lock-manipulation surface — anyone
+ * could acquire, renew, or release any lock key. Never wire it into a public
+ * Worker route; reach it only by `namespace.get(namespace.idFromName(key))`.
+ */
+export class CloudflareLockDurableObject {
+  private operationChain: Promise<void> = Promise.resolve()
+
+  constructor(private readonly state: LockDurableObjectState) {}
+
+  fetch(request: Request): Promise<Response> {
+    return this.serialize(() => this.handleRequest(request))
+  }
+
+  alarm(): Promise<void> {
+    return this.serialize(async () => {
+      const lease = await this.readLease()
+      if (!lease) {
+        await this.state.storage.deleteAlarm()
+        return
+      }
+      if (lease.expiresAt > Date.now()) {
+        await this.state.storage.setAlarm(lease.expiresAt)
+        return
+      }
+      await this.state.storage.delete(leaseKey)
+      await this.state.storage.deleteAlarm()
+    })
+  }
+
+  private async handleRequest(request: Request): Promise<Response> {
+    if (request.method !== 'POST') return response(405)
+    let input: unknown
+    try {
+      input = await request.json()
+    } catch {
+      return response(400)
+    }
+    if (!isLeaseRequest(input)) return response(400)
+
+    const operation = new URL(request.url).pathname
+    if (operation === '/acquire') return this.acquire(input)
+    if (operation === '/renew') return this.renew(input)
+    if (operation === '/release') return this.release(input.ownerId)
+    return response(404)
+  }
+
+  private async acquire(input: LeaseRequest): Promise<Response> {
+    const current = await this.readLease()
+    if (current && current.expiresAt > Date.now()) return response(409)
+    await this.writeLease(input)
+    return response(200)
+  }
+
+  private async renew(input: LeaseRequest): Promise<Response> {
+    const current = await this.readLease()
+    if (
+      !current ||
+      current.ownerId !== input.ownerId ||
+      current.expiresAt <= Date.now()
+    ) {
+      return response(409)
+    }
+    await this.writeLease(input)
+    return response(200)
+  }
+
+  private async release(ownerId: string): Promise<Response> {
+    const current = await this.readLease()
+    if (!current || current.ownerId !== ownerId) return response(409)
+    await this.state.storage.delete(leaseKey)
+    await this.state.storage.deleteAlarm()
+    return response(200)
+  }
+
+  private async readLease(): Promise<LeaseRecord | undefined> {
+    const value = await this.state.storage.get(leaseKey)
+    if (value === undefined) return undefined
+    if (!isLeaseRecord(value)) {
+      throw new Error('Durable Object lock lease is invalid')
+    }
+    return value
+  }
+
+  private async writeLease(input: LeaseRequest): Promise<void> {
+    const lease: LeaseRecord = {
+      ownerId: input.ownerId,
+      expiresAt: Date.now() + input.leaseDurationMs,
+    }
+    await this.state.storage.put(leaseKey, lease)
+    await this.state.storage.setAlarm(lease.expiresAt)
+  }
+
+  private serialize<T>(operation: () => Promise<T>): Promise<T> {
+    const result = this.operationChain.then(operation, operation)
+    this.operationChain = result.then(
+      () => undefined,
+      () => undefined,
+    )
+    return result
+  }
+}
+
+function resolveOptions(
+  options: DurableObjectLockStoreOptions,
+): ResolvedLockOptions {
+  const leaseDurationMs = options.leaseDurationMs ?? 30_000
+  const renewIntervalMs = options.renewIntervalMs ?? leaseDurationMs / 3
+  const acquireTimeoutMs = options.acquireTimeoutMs ?? 30_000
+  const retryDelayMs = options.retryDelayMs ?? 50
+  for (const [name, value] of [
+    ['leaseDurationMs', leaseDurationMs],
+    ['renewIntervalMs', renewIntervalMs],
+    ['acquireTimeoutMs', acquireTimeoutMs],
+    ['retryDelayMs', retryDelayMs],
+  ] as const) {
+    if (!Number.isFinite(value) || value <= 0) {
+      throw new RangeError(`${name} must be a positive finite number`)
+    }
+  }
+  if (renewIntervalMs >= leaseDurationMs) {
+    throw new RangeError('renewIntervalMs must be less than leaseDurationMs')
+  }
+  return {
+    leaseDurationMs,
+    renewIntervalMs,
+    acquireTimeoutMs,
+    retryDelayMs,
+    createOwnerId: options.createOwnerId ?? (() => crypto.randomUUID()),
+  }
+}
+
+function sleep(milliseconds: number, signal?: AbortSignal): Promise<void> {
+  return new Promise((resolve) => {
+    if (signal?.aborted) {
+      resolve()
+      return
+    }
+    const timeout = setTimeout(() => {
+      signal?.removeEventListener('abort', stopWaiting)
+      resolve()
+    }, milliseconds)
+    const stopWaiting = () => {
+      clearTimeout(timeout)
+      resolve()
+    }
+    signal?.addEventListener('abort', stopWaiting, { once: true })
+  })
+}
+
+function isAborted(signal: AbortSignal): boolean {
+  return signal.aborted
+}
+
+async function settle<T>(promise: Promise<T>): Promise<SettledValue<T>> {
+  try {
+    return { status: 'fulfilled', value: await promise }
+  } catch (error) {
+    return { status: 'rejected', reason: error }
+  }
+}
+
+async function lockOperation(
+  stub: DurableObjectStubBinding,
+  operation: 'acquire' | 'renew' | 'release',
+  ownerId: string,
+  leaseDurationMs: number,
+): Promise<Response> {
+  return stub.fetch(
+    new Request(`https://tanstack-ai-lock.invalid/${operation}`, {
+      method: 'POST',
+      body: JSON.stringify({ ownerId, leaseDurationMs }),
+      headers: { 'content-type': 'application/json' },
+    }),
+  )
+}
+
+function operationError(operation: string, status: number): Error {
+  return new Error(
+    `Durable Object lock ${operation} failed with status ${status}`,
+  )
+}
+
+async function acquireLease(
+  stub: DurableObjectStubBinding,
+  ownerId: string,
+  options: ResolvedLockOptions,
+): Promise<void> {
+  const deadline = Date.now() + options.acquireTimeoutMs
+  for (;;) {
+    const result = await lockOperation(
+      stub,
+      'acquire',
+      ownerId,
+      options.leaseDurationMs,
+    )
+    if (result.ok) return
+    if (result.status !== 409) throw operationError('acquire', result.status)
+    if (Date.now() >= deadline) {
+      throw new Error('Durable Object lock acquire timed out')
+    }
+    await sleep(options.retryDelayMs)
+  }
+}
+
+async function renewLeaseUntilFinished(
+  stub: DurableObjectStubBinding,
+  ownerId: string,
+  options: ResolvedLockOptions,
+  signal: AbortSignal,
+): Promise<void> {
+  for (;;) {
+    if (isAborted(signal)) return
+    await sleep(options.renewIntervalMs, signal)
+    if (isAborted(signal)) return
+    const result = await lockOperation(
+      stub,
+      'renew',
+      ownerId,
+      options.leaseDurationMs,
+    )
+    if (!result.ok) throw operationError('renew', result.status)
+  }
+}
+
+function throwFailures(failures: Array<unknown>): void {
+  if (failures.length === 1) throw failures[0]
+  if (failures.length > 1) {
+    throw new AggregateError(failures, 'Durable Object lock operation failed')
+  }
+}
+
+/** Create a distributed LockStore backed by one Durable Object per lock key. */
+export function createDurableObjectLockStore<TId>(
+  namespace: DurableObjectNamespaceBinding<TId>,
+  lockOptions: DurableObjectLockStoreOptions = {},
+): LockStore {
+  const options = resolveOptions(lockOptions)
+  return {
+    async withLock<T>(
+      key: string,
+      fn: (signal: AbortSignal) => Promise<T>,
+    ): Promise<T> {
+      const ownerId = options.createOwnerId()
+      const stub = namespace.get(namespace.idFromName(key))
+      await acquireLease(stub, ownerId, options)
+
+      const workFinished = new AbortController()
+      const leaseOwned = new AbortController()
+      const workResultPromise = settle(
+        Promise.resolve().then(() => fn(leaseOwned.signal)),
+      )
+      const renewalResultPromise = settle(
+        renewLeaseUntilFinished(
+          stub,
+          ownerId,
+          options,
+          workFinished.signal,
+        ).catch((error: unknown) => {
+          leaseOwned.abort(error)
+          throw error
+        }),
+      )
+      const workResult = await workResultPromise
+      workFinished.abort()
+      const renewalResult = await renewalResultPromise
+      // A 409 from `release` means the lease was no longer ours (it expired, or
+      // another owner acquired it) by the time the critical section finished.
+      // We surface that as a thrown error and let `withLock` reject even though
+      // the work itself may have completed: a lost lease means mutual exclusion
+      // could have been violated mid-section, so the caller must NOT treat the
+      // result as if it ran under the lock. `leaseOwned` is aborted when renewal
+      // fails, so a well-behaved critical section will already have stopped.
+      const releaseResult = await settle(
+        lockOperation(stub, 'release', ownerId, options.leaseDurationMs).then(
+          (result) => {
+            if (!result.ok) throw operationError('release', result.status)
+          },
+        ),
+      )
+
+      const failures: Array<unknown> = []
+      if (workResult.status === 'rejected') failures.push(workResult.reason)
+      if (renewalResult.status === 'rejected') {
+        failures.push(renewalResult.reason)
+      }
+      if (releaseResult.status === 'rejected') {
+        failures.push(releaseResult.reason)
+      }
+      throwFailures(failures)
+      if (workResult.status === 'rejected') throw workResult.reason
+      return workResult.value
+    },
+  }
+}
diff --git a/packages/ai-persistence-cloudflare/src/migration-cli.ts b/packages/ai-persistence-cloudflare/src/migration-cli.ts
new file mode 100644
index 000000000..ff3ecc17a
--- /dev/null
+++ b/packages/ai-persistence-cloudflare/src/migration-cli.ts
@@ -0,0 +1,125 @@
+import { mkdir, readFile, writeFile } from 'node:fs/promises'
+import { join } from 'node:path'
+import { d1Migrations } from './migrations'
+
+export interface MigrationCliOutput {
+  writeStdout: (value: string) => void
+}
+
+export class MigrationCliError extends Error {
+  constructor(message: string) {
+    super(message)
+    this.name = 'MigrationCliError'
+  }
+}
+
+const usage = `Usage: tanstack-ai-cloudflare-migrations (--out <directory> | --stdout) [--force]
+
+Options:
+  --out <directory>  Copy the ordered Cloudflare D1 migration files.
+  --stdout           Print the ordered migration SQL.
+  --force            Replace divergent files when copying.
+  --help             Show this help.
+`
+
+interface ParsedArguments {
+  force: boolean
+  help: boolean
+  outDirectory?: string
+  stdout: boolean
+}
+
+function parseArguments(args: ReadonlyArray<string>): ParsedArguments {
+  let force = false
+  let help = false
+  let outDirectory: string | undefined
+  let stdout = false
+
+  for (let index = 0; index < args.length; index++) {
+    const argument = args[index]
+    if (argument === '--force') {
+      force = true
+    } else if (argument === '--help' || argument === '-h') {
+      help = true
+    } else if (argument === '--stdout') {
+      stdout = true
+    } else if (argument === '--out') {
+      const value = args[index + 1]
+      if (!value || value.startsWith('-')) {
+        throw new MigrationCliError('--out requires a directory.')
+      }
+      if (outDirectory !== undefined) {
+        throw new MigrationCliError('--out may only be provided once.')
+      }
+      outDirectory = value
+      index++
+    } else {
+      throw new MigrationCliError(`Unknown argument: ${argument ?? ''}`)
+    }
+  }
+
+  return { force, help, outDirectory, stdout }
+}
+
+function isMissingFileError(error: unknown): boolean {
+  return error instanceof Error && 'code' in error && error.code === 'ENOENT'
+}
+
+async function readExistingFile(path: string): Promise<string | undefined> {
+  try {
+    return await readFile(path, 'utf8')
+  } catch (error) {
+    if (isMissingFileError(error)) return undefined
+    throw error
+  }
+}
+
+/** Execute the D1 migration asset CLI. Exported for deterministic CLI tests. */
+export async function runCloudflareMigrationsCli(
+  args: ReadonlyArray<string>,
+  output: MigrationCliOutput = {
+    writeStdout(value) {
+      process.stdout.write(value)
+    },
+  },
+): Promise<void> {
+  const parsed = parseArguments(args)
+  if (parsed.help) {
+    output.writeStdout(usage)
+    return
+  }
+
+  const outputCount =
+    Number(parsed.stdout) + Number(parsed.outDirectory != null)
+  if (outputCount !== 1) {
+    throw new MigrationCliError(
+      'Provide exactly one output mode: --out <directory> or --stdout.',
+    )
+  }
+  if (parsed.stdout) {
+    if (parsed.force) {
+      throw new MigrationCliError('--force can only be used with --out.')
+    }
+    output.writeStdout(
+      `${d1Migrations.map((migration) => migration.sql.trimEnd()).join('\n\n')}\n`,
+    )
+    return
+  }
+
+  const outDirectory = parsed.outDirectory
+  if (!outDirectory) {
+    throw new MigrationCliError('--out requires a directory.')
+  }
+  await mkdir(outDirectory, { recursive: true })
+  for (const migration of d1Migrations) {
+    const destination = join(outDirectory, migration.filename)
+    const existing = await readExistingFile(destination)
+    if (existing === migration.sql) continue
+    if (existing !== undefined && !parsed.force) {
+      throw new MigrationCliError(
+        `Refusing to overwrite divergent migration file: ${destination}. Re-run with --force to replace it.`,
+      )
+    }
+    await writeFile(destination, migration.sql, 'utf8')
+  }
+}
diff --git a/packages/ai-persistence-cloudflare/src/migrations.ts b/packages/ai-persistence-cloudflare/src/migrations.ts
new file mode 100644
index 000000000..0d24c5b49
--- /dev/null
+++ b/packages/ai-persistence-cloudflare/src/migrations.ts
@@ -0,0 +1,25 @@
+import initialMigrationSql from './assets/0000_tanstack_ai_initial.sql?raw'
+
+export interface D1Migration {
+  id: string
+  filename: string
+  sql: string
+}
+
+/**
+ * PROVENANCE: `assets/0000_tanstack_ai_initial.sql` is a byte-for-byte copy of
+ * the Drizzle asset
+ * (`@tanstack/ai-persistence-drizzle`'s `src/assets/0000_tanstack_ai_initial.sql`).
+ * `createD1Stores` runs the Drizzle stores against a D1 database migrated with
+ * this SQL, so the copy MUST stay identical to Drizzle's. The test "cloudflare
+ * D1 asset matches the drizzle asset" (`tests/migrations.test.ts`) fails on any
+ * drift.
+ */
+/** Ordered D1 migrations for messages, runs, interrupts, and metadata. */
+export const d1Migrations: ReadonlyArray<D1Migration> = [
+  {
+    id: '0000_tanstack_ai_initial',
+    filename: '0000_tanstack_ai_initial.sql',
+    sql: initialMigrationSql,
+  },
+]
diff --git a/packages/ai-persistence-cloudflare/tests/api-types.test-d.ts b/packages/ai-persistence-cloudflare/tests/api-types.test-d.ts
new file mode 100644
index 000000000..af7eca8b8
--- /dev/null
+++ b/packages/ai-persistence-cloudflare/tests/api-types.test-d.ts
@@ -0,0 +1,65 @@
+/// <reference types="@cloudflare/workers-types" />
+import { expectTypeOf } from 'vitest'
+import { composePersistence } from '@tanstack/ai-persistence'
+import {
+  CloudflareLockDurableObject,
+  cloudflarePersistence,
+} from '../src/index'
+import type {
+  InterruptStore,
+  MessageStore,
+  MetadataStore,
+  RunStore,
+} from '@tanstack/ai-persistence'
+import type { LockStore } from '@tanstack/ai'
+
+declare const d1: D1Database
+declare const durableObjects: DurableObjectNamespace
+declare const durableObjectState: DurableObjectState
+
+new CloudflareLockDurableObject(durableObjectState)
+
+expectTypeOf(cloudflarePersistence({}).stores).toEqualTypeOf<{}>()
+expectTypeOf(cloudflarePersistence({ d1 }).stores).toEqualTypeOf<{
+  messages: MessageStore
+  runs: RunStore
+  interrupts: InterruptStore
+  metadata: MetadataStore
+}>()
+expectTypeOf(cloudflarePersistence({ durableObjects }).stores).toEqualTypeOf<{
+  locks: LockStore
+}>()
+expectTypeOf(
+  cloudflarePersistence({ d1, durableObjects }).stores,
+).toEqualTypeOf<{
+  messages: MessageStore
+  runs: RunStore
+  interrupts: InterruptStore
+  metadata: MetadataStore
+  locks: LockStore
+}>()
+
+declare const optionalD1: D1Database | undefined
+expectTypeOf(cloudflarePersistence({ d1: optionalD1 }).stores).toEqualTypeOf<{
+  messages?: MessageStore
+  runs?: RunStore
+  interrupts?: InterruptStore
+  metadata?: MetadataStore
+}>()
+
+const d1Persistence = cloudflarePersistence({ d1 })
+declare const customInterrupts: InterruptStore
+const replaced = composePersistence(d1Persistence, {
+  overrides: { interrupts: customInterrupts },
+})
+expectTypeOf(replaced.stores.interrupts).toEqualTypeOf<InterruptStore>()
+expectTypeOf(replaced.stores.runs).toEqualTypeOf<RunStore>()
+
+const removed = composePersistence(d1Persistence, {
+  overrides: { interrupts: false },
+})
+expectTypeOf(removed.stores).toEqualTypeOf<{
+  messages: MessageStore
+  runs: RunStore
+  metadata: MetadataStore
+}>()
diff --git a/packages/ai-persistence-cloudflare/tests/locks.test.ts b/packages/ai-persistence-cloudflare/tests/locks.test.ts
new file mode 100644
index 000000000..c40822089
--- /dev/null
+++ b/packages/ai-persistence-cloudflare/tests/locks.test.ts
@@ -0,0 +1,359 @@
+import { afterEach, describe, expect, it, vi } from 'vitest'
+import {
+  CloudflareLockDurableObject,
+  createDurableObjectLockStore,
+} from '../src/index'
+import type {
+  DurableObjectNamespaceBinding,
+  DurableObjectStubBinding,
+  LockDurableObjectStorage,
+} from '../src/index'
+
+class FakeLockStorage implements LockDurableObjectStorage {
+  readonly values = new Map<string, unknown>()
+  alarm: number | undefined
+
+  get(key: string): Promise<unknown> {
+    return Promise.resolve(this.values.get(key))
+  }
+
+  put(key: string, value: unknown): Promise<void> {
+    this.values.set(key, value)
+    return Promise.resolve()
+  }
+
+  delete(key: string): Promise<boolean> {
+    return Promise.resolve(this.values.delete(key))
+  }
+
+  setAlarm(timestamp: number): Promise<void> {
+    this.alarm = timestamp
+    return Promise.resolve()
+  }
+
+  deleteAlarm(): Promise<void> {
+    this.alarm = undefined
+    return Promise.resolve()
+  }
+}
+
+function request(
+  operation: 'acquire' | 'renew' | 'release',
+  ownerId: string,
+  leaseDurationMs = 100,
+): Request {
+  return new Request(`https://lock.invalid/${operation}`, {
+    method: 'POST',
+    body: JSON.stringify({ ownerId, leaseDurationMs }),
+    headers: { 'content-type': 'application/json' },
+  })
+}
+
+function deferred<T>() {
+  let resolve: (value: T) => void = () => undefined
+  const promise = new Promise<T>((promiseResolve) => {
+    resolve = promiseResolve
+  })
+  return { promise, resolve }
+}
+
+function waitForAbort(signal: AbortSignal): Promise<void> {
+  if (signal.aborted) return Promise.resolve()
+  return new Promise((resolve) => {
+    signal.addEventListener('abort', () => resolve(), { once: true })
+  })
+}
+
+async function ownerIdFrom(request: Request): Promise<string | undefined> {
+  const body: unknown = await request.clone().json()
+  if (
+    typeof body !== 'object' ||
+    body === null ||
+    !('ownerId' in body) ||
+    typeof body.ownerId !== 'string'
+  ) {
+    return undefined
+  }
+  return body.ownerId
+}
+
+afterEach(() => {
+  vi.useRealTimers()
+})
+
+describe('CloudflareLockDurableObject', () => {
+  it('acquires, renews, and releases an owner-scoped lease', async () => {
+    vi.useFakeTimers()
+    vi.setSystemTime(1_000)
+    const storage = new FakeLockStorage()
+    const durableObject = new CloudflareLockDurableObject({ storage })
+
+    expect((await durableObject.fetch(request('acquire', 'one'))).status).toBe(
+      200,
+    )
+    expect((await durableObject.fetch(request('acquire', 'two'))).status).toBe(
+      409,
+    )
+    vi.setSystemTime(1_050)
+    expect((await durableObject.fetch(request('renew', 'one'))).status).toBe(
+      200,
+    )
+    expect(storage.alarm).toBe(1_150)
+    expect((await durableObject.fetch(request('release', 'two'))).status).toBe(
+      409,
+    )
+    expect((await durableObject.fetch(request('release', 'one'))).status).toBe(
+      200,
+    )
+    expect((await durableObject.fetch(request('acquire', 'two'))).status).toBe(
+      200,
+    )
+  })
+
+  it('expires a lease from the Durable Object alarm', async () => {
+    vi.useFakeTimers()
+    vi.setSystemTime(2_000)
+    const storage = new FakeLockStorage()
+    const durableObject = new CloudflareLockDurableObject({ storage })
+    await durableObject.fetch(request('acquire', 'one'))
+
+    vi.setSystemTime(2_101)
+    await durableObject.alarm()
+
+    expect((await durableObject.fetch(request('acquire', 'two'))).status).toBe(
+      200,
+    )
+  })
+})
+
+describe('Durable Object LockStore', () => {
+  it('renews a long-running critical section and awaits release', async () => {
+    vi.useFakeTimers()
+    vi.setSystemTime(3_000)
+    const storage = new FakeLockStorage()
+    const server = new CloudflareLockDurableObject({ storage })
+    const operations: Array<string> = []
+    const stub: DurableObjectStubBinding = {
+      fetch(input) {
+        const requestInput =
+          input instanceof Request ? input : new Request(input)
+        operations.push(new URL(requestInput.url).pathname)
+        return server.fetch(requestInput)
+      },
+    }
+    const namespace: DurableObjectNamespaceBinding<string> = {
+      idFromName: (name) => name,
+      get: () => stub,
+    }
+    const store = createDurableObjectLockStore(namespace, {
+      leaseDurationMs: 100,
+      renewIntervalMs: 40,
+      retryDelayMs: 5,
+      acquireTimeoutMs: 100,
+      createOwnerId: () => 'owner',
+    })
+    const work = deferred<string>()
+    const result = store.withLock('workspace', () => work.promise)
+
+    await vi.advanceTimersByTimeAsync(0)
+    await vi.advanceTimersByTimeAsync(41)
+    expect(operations).toContain('/renew')
+    work.resolve('done')
+    await expect(result).resolves.toBe('done')
+    expect(operations.at(-1)).toBe('/release')
+  })
+
+  it('surfaces renewal failure after user work settles and still releases', async () => {
+    vi.useFakeTimers()
+    const operations: Array<string> = []
+    const stub: DurableObjectStubBinding = {
+      fetch(input) {
+        const requestInput =
+          input instanceof Request ? input : new Request(input)
+        const operation = new URL(requestInput.url).pathname
+        operations.push(operation)
+        return Promise.resolve(
+          new Response(null, { status: operation === '/renew' ? 503 : 200 }),
+        )
+      },
+    }
+    const namespace: DurableObjectNamespaceBinding<string> = {
+      idFromName: (name) => name,
+      get: () => stub,
+    }
+    const store = createDurableObjectLockStore(namespace, {
+      leaseDurationMs: 100,
+      renewIntervalMs: 40,
+      createOwnerId: () => 'owner',
+    })
+    const work = deferred<string>()
+    const result = store.withLock('workspace', () => work.promise)
+
+    await vi.advanceTimersByTimeAsync(0)
+    await vi.advanceTimersByTimeAsync(41)
+    work.resolve('done')
+
+    await expect(result).rejects.toThrow(/renew.*503/i)
+    expect(operations.at(-1)).toBe('/release')
+  })
+
+  it('aborts a lost lease before another owner enters after expiry', async () => {
+    vi.useFakeTimers()
+    vi.setSystemTime(4_000)
+    const storage = new FakeLockStorage()
+    const server = new CloudflareLockDurableObject({ storage })
+    const stub: DurableObjectStubBinding = {
+      async fetch(input) {
+        const requestInput =
+          input instanceof Request ? input : new Request(input)
+        const operation = new URL(requestInput.url).pathname
+        const ownerId = await ownerIdFrom(requestInput)
+        if (
+          ownerId === 'owner-1' &&
+          (operation === '/renew' || operation === '/release')
+        ) {
+          return new Response(null, { status: 503 })
+        }
+        return server.fetch(requestInput)
+      },
+    }
+    const namespace: DurableObjectNamespaceBinding<string> = {
+      idFromName: (name) => name,
+      get: () => stub,
+    }
+    const firstStore = createDurableObjectLockStore(namespace, {
+      leaseDurationMs: 100,
+      renewIntervalMs: 40,
+      retryDelayMs: 5,
+      acquireTimeoutMs: 200,
+      createOwnerId: () => 'owner-1',
+    })
+    const secondStore = createDurableObjectLockStore(namespace, {
+      leaseDurationMs: 100,
+      renewIntervalMs: 40,
+      retryDelayMs: 5,
+      acquireTimeoutMs: 200,
+      createOwnerId: () => 'owner-2',
+    })
+    const legacyStop = deferred<void>()
+    let active = 0
+    let maximumActive = 0
+    let firstAborted = false
+
+    const first = firstStore.withLock('workspace', async (signal) => {
+      active += 1
+      maximumActive = Math.max(maximumActive, active)
+      if (signal instanceof AbortSignal) {
+        await waitForAbort(signal)
+        firstAborted = signal.aborted
+      } else {
+        await legacyStop.promise
+      }
+      active -= 1
+    })
+    const firstError = first.then(
+      () => undefined,
+      (error: unknown) => error,
+    )
+    await vi.advanceTimersByTimeAsync(0)
+    const second = secondStore.withLock('workspace', async () => {
+      active += 1
+      maximumActive = Math.max(maximumActive, active)
+      active -= 1
+      return 'second'
+    })
+
+    await vi.advanceTimersByTimeAsync(110)
+    legacyStop.resolve()
+    await expect(second).resolves.toBe('second')
+    await expect(firstError).resolves.toBeInstanceOf(AggregateError)
+
+    expect(firstAborted).toBe(true)
+    expect(maximumActive).toBe(1)
+  })
+
+  it('surfaces release failure', async () => {
+    const stub: DurableObjectStubBinding = {
+      fetch(input) {
+        const requestInput =
+          input instanceof Request ? input : new Request(input)
+        const operation = new URL(requestInput.url).pathname
+        return Promise.resolve(
+          new Response(null, { status: operation === '/release' ? 503 : 200 }),
+        )
+      },
+    }
+    const namespace: DurableObjectNamespaceBinding<string> = {
+      idFromName: (name) => name,
+      get: () => stub,
+    }
+    const store = createDurableObjectLockStore(namespace, {
+      createOwnerId: () => 'owner',
+    })
+
+    await expect(store.withLock('workspace', async () => 42)).rejects.toThrow(
+      /release.*503/i,
+    )
+  })
+
+  it('preserves a critical section rejection with an undefined reason', async () => {
+    const namespace: DurableObjectNamespaceBinding<string> = {
+      idFromName: (name) => name,
+      get: () => ({ fetch: () => Promise.resolve(new Response()) }),
+    }
+    const store = createDurableObjectLockStore(namespace)
+
+    await expect(
+      store.withLock('workspace', () => Promise.reject(undefined)),
+    ).rejects.toBeUndefined()
+  })
+
+  it('aggregates critical section and release failures', async () => {
+    const workError = new Error('work failed')
+    const stub: DurableObjectStubBinding = {
+      fetch(input) {
+        const requestInput =
+          input instanceof Request ? input : new Request(input)
+        const operation = new URL(requestInput.url).pathname
+        return Promise.resolve(
+          new Response(null, { status: operation === '/release' ? 503 : 200 }),
+        )
+      },
+    }
+    const namespace: DurableObjectNamespaceBinding<string> = {
+      idFromName: (name) => name,
+      get: () => stub,
+    }
+    const store = createDurableObjectLockStore(namespace)
+
+    const error = await store
+      .withLock('workspace', () => Promise.reject(workError))
+      .then(
+        () => undefined,
+        (reason: unknown) => reason,
+      )
+
+    expect(error).toBeInstanceOf(AggregateError)
+    expect(error).toMatchObject({
+      errors: [
+        workError,
+        expect.objectContaining({
+          message: expect.stringMatching(/release.*503/i),
+        }),
+      ],
+    })
+  })
+
+  it('rejects invalid lease timing before acquiring', () => {
+    const namespace: DurableObjectNamespaceBinding<string> = {
+      idFromName: (name) => name,
+      get: () => ({ fetch: () => Promise.resolve(new Response()) }),
+    }
+    expect(() =>
+      createDurableObjectLockStore(namespace, {
+        leaseDurationMs: 100,
+        renewIntervalMs: 100,
+      }),
+    ).toThrow(/renewIntervalMs.*leaseDurationMs/)
+  })
+})
diff --git a/packages/ai-persistence-cloudflare/tests/migration-cli.test.ts b/packages/ai-persistence-cloudflare/tests/migration-cli.test.ts
new file mode 100644
index 000000000..5e5fd529b
--- /dev/null
+++ b/packages/ai-persistence-cloudflare/tests/migration-cli.test.ts
@@ -0,0 +1,65 @@
+import { mkdtemp, readFile, rm, writeFile } from 'node:fs/promises'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { afterEach, describe, expect, it } from 'vitest'
+import { d1Migrations } from '../src/migrations'
+import { runCloudflareMigrationsCli } from '../src/migration-cli'
+
+const temporaryDirectories: Array<string> = []
+
+async function createTemporaryDirectory(): Promise<string> {
+  const directory = await mkdtemp(join(tmpdir(), 'tanstack-ai-cloudflare-cli-'))
+  temporaryDirectories.push(directory)
+  return directory
+}
+
+afterEach(async () => {
+  await Promise.all(
+    temporaryDirectories
+      .splice(0)
+      .map((directory) => rm(directory, { recursive: true, force: true })),
+  )
+})
+
+describe('Cloudflare D1 migrations CLI', () => {
+  it('prints canonical migration SQL to stdout', async () => {
+    let output = ''
+    await runCloudflareMigrationsCli(['--stdout'], {
+      writeStdout(value) {
+        output += value
+      },
+    })
+
+    expect(output).toBe(`${d1Migrations[0]?.sql.trimEnd()}\n`)
+  })
+
+  it('copies migrations without overwriting divergent files by default', async () => {
+    const directory = await createTemporaryDirectory()
+    await runCloudflareMigrationsCli(['--out', directory])
+
+    const migration = d1Migrations[0]
+    expect(migration).toBeDefined()
+    if (!migration) return
+    const destination = join(directory, migration.filename)
+    expect(await readFile(destination, 'utf8')).toBe(migration.sql)
+
+    await writeFile(destination, 'user-owned contents', 'utf8')
+    await expect(
+      runCloudflareMigrationsCli(['--out', directory]),
+    ).rejects.toThrow(/refusing to overwrite/i)
+    expect(await readFile(destination, 'utf8')).toBe('user-owned contents')
+
+    await runCloudflareMigrationsCli(['--out', directory, '--force'])
+    expect(await readFile(destination, 'utf8')).toBe(migration.sql)
+  })
+
+  it('fails on ambiguous or incomplete output options', async () => {
+    const directory = await createTemporaryDirectory()
+    await expect(runCloudflareMigrationsCli([])).rejects.toThrow(
+      /--out.*--stdout/i,
+    )
+    await expect(
+      runCloudflareMigrationsCli(['--stdout', '--out', directory]),
+    ).rejects.toThrow(/exactly one/i)
+  })
+})
diff --git a/packages/ai-persistence-cloudflare/tests/migrations.test.ts b/packages/ai-persistence-cloudflare/tests/migrations.test.ts
new file mode 100644
index 000000000..f2ddeeed6
--- /dev/null
+++ b/packages/ai-persistence-cloudflare/tests/migrations.test.ts
@@ -0,0 +1,53 @@
+import { readFile } from 'node:fs/promises'
+import { fileURLToPath } from 'node:url'
+import { describe, expect, it } from 'vitest'
+import { d1Migrations } from '../src/index'
+
+async function readAsset(url: string): Promise<string> {
+  return readFile(fileURLToPath(new URL(url, import.meta.url)), 'utf8')
+}
+
+describe('D1 migrations', () => {
+  it('exports the canonical structured-state migration', () => {
+    expect(d1Migrations).toHaveLength(1)
+    expect(d1Migrations[0]).toMatchObject({
+      id: '0000_tanstack_ai_initial',
+      filename: '0000_tanstack_ai_initial.sql',
+    })
+    const sql = d1Migrations[0]?.sql ?? ''
+    expect(sql).toMatch(/CREATE TABLE [`"]messages[`"]/)
+    expect(sql).toMatch(/CREATE TABLE [`"]runs[`"]/)
+    expect(sql).toMatch(/CREATE TABLE [`"]interrupts[`"]/)
+    expect(sql).toMatch(/CREATE TABLE [`"]metadata[`"]/)
+  })
+
+  it('keeps the published migration equal to the embedded asset', async () => {
+    const embedded = await readFile(
+      fileURLToPath(
+        new URL('../src/assets/0000_tanstack_ai_initial.sql', import.meta.url),
+      ),
+      'utf8',
+    )
+    const published = await readFile(
+      fileURLToPath(
+        new URL('../migrations/0000_tanstack_ai_initial.sql', import.meta.url),
+      ),
+      'utf8',
+    )
+    expect(published).toBe(embedded)
+    expect(d1Migrations[0]?.sql).toBe(embedded)
+  })
+
+  // `createD1Stores` runs the Drizzle stores against a D1 database migrated
+  // with this copy of the Drizzle migration, so it must stay byte-for-byte
+  // identical to the Drizzle asset. Drift breaks the stores at runtime.
+  it('cloudflare D1 asset matches the drizzle asset', async () => {
+    const cloudflareSql = await readAsset(
+      '../src/assets/0000_tanstack_ai_initial.sql',
+    )
+    const drizzleSql = await readAsset(
+      '../../ai-persistence-drizzle/src/assets/0000_tanstack_ai_initial.sql',
+    )
+    expect(cloudflareSql).toBe(drizzleSql)
+  })
+})
diff --git a/packages/ai-persistence-cloudflare/tests/package-contract.test.ts b/packages/ai-persistence-cloudflare/tests/package-contract.test.ts
new file mode 100644
index 000000000..8c8039860
--- /dev/null
+++ b/packages/ai-persistence-cloudflare/tests/package-contract.test.ts
@@ -0,0 +1,46 @@
+import { readFile } from 'node:fs/promises'
+import { fileURLToPath } from 'node:url'
+import { describe, expect, it } from 'vitest'
+import packageJson from '../package.json'
+
+describe('Cloudflare package contract', () => {
+  it('starts at 0.0.1 and publishes the root, CLI, and D1 assets', () => {
+    expect(packageJson.exports).toEqual({
+      '.': {
+        types: './dist/esm/index.d.ts',
+        import: './dist/esm/index.js',
+      },
+    })
+    expect(packageJson.bin).toEqual({
+      'tanstack-ai-cloudflare-migrations':
+        './bin/tanstack-ai-cloudflare-migrations.mjs',
+    })
+    expect(packageJson.files).toEqual(
+      expect.arrayContaining(['bin', 'dist', 'migrations', 'src']),
+    )
+  })
+
+  it('keeps Node built-ins, Buffer, and the CLI out of the root graph', async () => {
+    const rootFiles = [
+      'bindings.ts',
+      'd1.ts',
+      'index.ts',
+      'locks.ts',
+      'migrations.ts',
+    ]
+    for (const filename of rootFiles) {
+      const contents = await readFile(
+        fileURLToPath(new URL(`../src/${filename}`, import.meta.url)),
+        'utf8',
+      )
+      expect(contents, filename).not.toMatch(/from ['"]node:/)
+      expect(contents, filename).not.toMatch(/\bBuffer\b/)
+    }
+    const root = await readFile(
+      fileURLToPath(new URL('../src/index.ts', import.meta.url)),
+      'utf8',
+    )
+    expect(root).not.toMatch(/migration-cli/)
+    expect(root).not.toMatch(/\.\/cli/)
+  })
+})
diff --git a/packages/ai-persistence-cloudflare/tests/runtime.conformance.test.ts b/packages/ai-persistence-cloudflare/tests/runtime.conformance.test.ts
new file mode 100644
index 000000000..fcfdee664
--- /dev/null
+++ b/packages/ai-persistence-cloudflare/tests/runtime.conformance.test.ts
@@ -0,0 +1,77 @@
+/// <reference types="@cloudflare/workers-types" />
+import { afterAll, beforeAll, describe, expect, it } from 'vitest'
+import { Miniflare } from 'miniflare'
+import { runPersistenceConformance } from '@tanstack/ai-persistence/testkit'
+import { cloudflarePersistence, d1Migrations } from '../src/index'
+import { composePersistence } from '@tanstack/ai-persistence'
+import type { AIPersistence, InterruptStore } from '@tanstack/ai-persistence'
+
+interface RuntimeBindings {
+  AI_DB: D1Database
+}
+
+describe('Cloudflare persistence on Miniflare bindings', () => {
+  let miniflare: Miniflare
+  let persistence: AIPersistence
+
+  beforeAll(async () => {
+    miniflare = new Miniflare({
+      compatibilityDate: '2026-06-24',
+      d1Databases: ['AI_DB'],
+      modules: true,
+      script: 'export default { fetch() { return new Response("ok") } }',
+    })
+    const bindings = await miniflare.getBindings<RuntimeBindings>()
+    for (const migration of d1Migrations) {
+      const statements = migration.sql
+        .split('--> statement-breakpoint')
+        .map((statement) => statement.trim())
+        .filter((statement) => statement.length > 0)
+      await bindings.AI_DB.batch(
+        statements.map((statement) => bindings.AI_DB.prepare(statement)),
+      )
+    }
+    persistence = cloudflarePersistence({
+      d1: bindings.AI_DB,
+    })
+  })
+
+  afterAll(async () => {
+    await miniflare.dispose()
+  })
+
+  runPersistenceConformance('cloudflare-d1', () => persistence, {
+    // This composition supplies only a D1 binding (no Durable Object), so
+    // there is no lock store.
+    skip: ['locks'],
+  })
+
+  it('composes a custom interrupt store while retaining D1 runs', () => {
+    const customInterrupts: InterruptStore = {
+      create: () => Promise.resolve(),
+      resolve: () => Promise.resolve(),
+      cancel: () => Promise.resolve(),
+      get: () => Promise.resolve(null),
+      list: () => Promise.resolve([]),
+      listPending: () => Promise.resolve([]),
+      listByRun: () => Promise.resolve([]),
+      listPendingByRun: () => Promise.resolve([]),
+    }
+    const composed = composePersistence(persistence, {
+      overrides: { interrupts: customInterrupts },
+    })
+
+    expect(composed.stores.interrupts).toBe(customInterrupts)
+    expect(composed.stores.runs).toBe(persistence.stores.runs)
+  })
+
+  it('removes only stores explicitly disabled by an override', () => {
+    const composed = composePersistence(persistence, {
+      overrides: { interrupts: false },
+    })
+
+    expect('interrupts' in composed.stores).toBe(false)
+    expect(composed.stores.runs).toBe(persistence.stores.runs)
+    expect(composed.stores.messages).toBe(persistence.stores.messages)
+  })
+})
diff --git a/packages/ai-persistence-cloudflare/tsconfig.json b/packages/ai-persistence-cloudflare/tsconfig.json
new file mode 100644
index 000000000..1ca53bbf0
--- /dev/null
+++ b/packages/ai-persistence-cloudflare/tsconfig.json
@@ -0,0 +1,9 @@
+{
+  "extends": "../../tsconfig.base.json",
+  "compilerOptions": {
+    "outDir": "dist",
+    "types": ["node", "@cloudflare/workers-types"]
+  },
+  "include": ["src", "tests"],
+  "exclude": ["node_modules", "dist"]
+}
diff --git a/packages/ai-persistence-cloudflare/vite.config.ts b/packages/ai-persistence-cloudflare/vite.config.ts
new file mode 100644
index 000000000..bba59f080
--- /dev/null
+++ b/packages/ai-persistence-cloudflare/vite.config.ts
@@ -0,0 +1,40 @@
+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/cli.ts'],
+    srcDir: './src',
+    cjs: false,
+    beforeWriteDeclarationFile(filePath, content) {
+      if (!/[\\/]index\.d\.ts$/.test(filePath)) return content
+      return `/// <reference types="@cloudflare/workers-types" />\n${content}`
+    },
+  }),
+)
diff --git a/packages/ai-persistence-drizzle/bin/tanstack-ai-drizzle-migrations.mjs b/packages/ai-persistence-drizzle/bin/tanstack-ai-drizzle-migrations.mjs
new file mode 100755
index 000000000..0a4de6588
--- /dev/null
+++ b/packages/ai-persistence-drizzle/bin/tanstack-ai-drizzle-migrations.mjs
@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+import '../dist/esm/cli.js'
diff --git a/packages/ai-persistence-drizzle/bin/tanstack-ai-drizzle-schema.mjs b/packages/ai-persistence-drizzle/bin/tanstack-ai-drizzle-schema.mjs
new file mode 100755
index 000000000..c33270c7f
--- /dev/null
+++ b/packages/ai-persistence-drizzle/bin/tanstack-ai-drizzle-schema.mjs
@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+import '../dist/esm/schema-cli-main.js'
diff --git a/packages/ai-persistence-drizzle/drizzle.config.ts b/packages/ai-persistence-drizzle/drizzle.config.ts
new file mode 100644
index 000000000..a3602a3d5
--- /dev/null
+++ b/packages/ai-persistence-drizzle/drizzle.config.ts
@@ -0,0 +1,19 @@
+import { defineConfig } from 'drizzle-kit'
+
+/**
+ * drizzle-kit config for the SQLite schema. Migrations are generated from
+ * `src/schema.ts` into `drizzle/`, shipped with the package, exposed through
+ * `sqliteMigrations`, and applied by the Node-only `sqlitePersistence` factory.
+ *
+ * Regenerate with `pnpm db:generate` after any schema change. `sqliteMigrations`
+ * and the D1 sibling load the DUPLICATE at `src/assets/0000_tanstack_ai_initial.sql`,
+ * which `db:generate` does NOT update — copy the regenerated
+ * `drizzle/0000_tanstack_ai_initial.sql` over it (the package-contract test
+ * "keeps the shipped drizzle-kit migration equal to the embedded asset" guards
+ * the two against drift).
+ */
+export default defineConfig({
+  dialect: 'sqlite',
+  schema: './src/schema.ts',
+  out: './drizzle',
+})
diff --git a/packages/ai-persistence-drizzle/drizzle/0000_tanstack_ai_initial.sql b/packages/ai-persistence-drizzle/drizzle/0000_tanstack_ai_initial.sql
new file mode 100644
index 000000000..3e5570ec1
--- /dev/null
+++ b/packages/ai-persistence-drizzle/drizzle/0000_tanstack_ai_initial.sql
@@ -0,0 +1,32 @@
+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..2f24bec81
--- /dev/null
+++ b/packages/ai-persistence-drizzle/drizzle/meta/0000_snapshot.json
@@ -0,0 +1,203 @@
+{
+  "version": "6",
+  "dialect": "sqlite",
+  "id": "7c2d61ca-85d3-486d-be8c-ff358edba179",
+  "prevId": "00000000-0000-0000-0000-000000000000",
+  "tables": {
+    "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..29a26ea4b
--- /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": 1784347380743,
+      "tag": "0000_tanstack_ai_initial",
+      "breakpoints": true
+    }
+  ]
+}
diff --git a/packages/ai-persistence-drizzle/package.json b/packages/ai-persistence-drizzle/package.json
new file mode 100644
index 000000000..03d6ad10c
--- /dev/null
+++ b/packages/ai-persistence-drizzle/package.json
@@ -0,0 +1,66 @@
+{
+  "name": "@tanstack/ai-persistence-drizzle",
+  "version": "0.0.0",
+  "description": "SQLite-family Drizzle persistence for TanStack AI, with an edge-safe bring-your-own database adapter, a Node SQLite factory, and bundled migrations.",
+  "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"
+    },
+    "./sqlite": {
+      "types": "./dist/esm/sqlite.d.ts",
+      "import": "./dist/esm/sqlite.js"
+    }
+  },
+  "bin": {
+    "tanstack-ai-drizzle-migrations": "./bin/tanstack-ai-drizzle-migrations.mjs",
+    "tanstack-ai-drizzle-schema": "./bin/tanstack-ai-drizzle-schema.mjs"
+  },
+  "files": [
+    "bin",
+    "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/assets.d.ts b/packages/ai-persistence-drizzle/src/assets.d.ts
new file mode 100644
index 000000000..b02bb85ed
--- /dev/null
+++ b/packages/ai-persistence-drizzle/src/assets.d.ts
@@ -0,0 +1,9 @@
+declare module '*.sql?raw' {
+  const contents: string
+  export default contents
+}
+
+declare module '*.ts?raw' {
+  const contents: string
+  export default contents
+}
diff --git a/packages/ai-persistence-drizzle/src/assets/0000_tanstack_ai_initial.sql b/packages/ai-persistence-drizzle/src/assets/0000_tanstack_ai_initial.sql
new file mode 100644
index 000000000..3e5570ec1
--- /dev/null
+++ b/packages/ai-persistence-drizzle/src/assets/0000_tanstack_ai_initial.sql
@@ -0,0 +1,32 @@
+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/src/assets/tanstack-ai-schema.ts b/packages/ai-persistence-drizzle/src/assets/tanstack-ai-schema.ts
new file mode 100644
index 000000000..86cb944e1
--- /dev/null
+++ b/packages/ai-persistence-drizzle/src/assets/tanstack-ai-schema.ts
@@ -0,0 +1,73 @@
+/**
+ * TanStack AI persistence schema — emitted by `tanstack-ai-drizzle-schema`.
+ *
+ * This file is yours. Add it to your drizzle-kit `schema` paths so your own
+ * migration journal owns the DDL, then pass it back to the runtime:
+ *
+ * ```ts
+ * import { drizzlePersistence } from '@tanstack/ai-persistence-drizzle'
+ * import { schema } from './tanstack-ai-schema'
+ *
+ * const persistence = drizzlePersistence(db, { schema })
+ * ```
+ *
+ * You may rename tables and columns (or drop the explicit column names below
+ * and rely on your drizzle `casing` configuration) and add extra app-owned
+ * columns — keep added columns nullable or defaulted so the runtime's inserts
+ * succeed, and keep the columns below with these data shapes.
+ */
+import { 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] })],
+)
+
+/** The full state schema, for `drizzlePersistence(db, { schema })` and drizzle-kit. */
+export const schema = {
+  messages,
+  runs,
+  interrupts,
+  metadata,
+}
diff --git a/packages/ai-persistence-drizzle/src/cli.ts b/packages/ai-persistence-drizzle/src/cli.ts
new file mode 100644
index 000000000..6b9378a08
--- /dev/null
+++ b/packages/ai-persistence-drizzle/src/cli.ts
@@ -0,0 +1,10 @@
+#!/usr/bin/env node
+import { runDrizzleMigrationsCli } from './migration-cli'
+
+try {
+  await runDrizzleMigrationsCli(process.argv.slice(2))
+} catch (error) {
+  const message = error instanceof Error ? error.message : String(error)
+  process.stderr.write(`${message}\n`)
+  process.exitCode = 1
+}
diff --git a/packages/ai-persistence-drizzle/src/index.ts b/packages/ai-persistence-drizzle/src/index.ts
new file mode 100644
index 000000000..01b4eca9c
--- /dev/null
+++ b/packages/ai-persistence-drizzle/src/index.ts
@@ -0,0 +1,77 @@
+/**
+ * Drizzle-backed SQLite-family persistence for TanStack AI.
+ *
+ * This root entry is safe to import in edge runtimes. Pass an already-created
+ * and migrated SQLite-compatible Drizzle database, including Cloudflare D1, to
+ * {@link drizzlePersistence}. Node's built-in SQLite convenience factory lives
+ * at `@tanstack/ai-persistence-drizzle/sqlite`.
+ */
+import { schema } from './schema'
+import { assertTanstackAiSchema } from './schema-contract'
+import {
+  createInterruptStore,
+  createMessageStore,
+  createMetadataStore,
+  createRunStore,
+} from './stores'
+import type { TanstackAiSqliteSchema } from './schema-contract'
+import type { DrizzleSqliteDb, TanstackAiTables } from './stores'
+
+export { schema } from './schema'
+export { sqliteMigrations } from './migrations'
+export { drizzleSchemaFilename, drizzleSchemaSource } from './schema-source'
+export { DrizzleSchemaError } from './schema-contract'
+export type { TanstackAiSqliteSchema } from './schema-contract'
+export type { SqliteMigration } from './migrations'
+export type { DrizzleSqliteDb } from './stores'
+// Deprecated aliases kept for backward compatibility (both are SQLite-only).
+export type { TanstackAiSchema } from './schema-contract'
+export type { DrizzleDb } from './stores'
+
+export interface DrizzlePersistenceOptions {
+  /**
+   * Operate over your project's own copy of the TanStack AI schema instead of
+   * the bundled one — emit it with `tanstack-ai-drizzle-schema`, add it to
+   * your drizzle-kit schema paths, and pass it here. Table and column database
+   * names are yours to change (drizzle `casing` transforms included), and
+   * tables may carry extra app-owned columns as long as they are nullable or
+   * defaulted. Defaults to the bundled `schema` export.
+   */
+  schema?: TanstackAiSqliteSchema
+}
+
+/**
+ * Wire TanStack AI persistence stores over a migrated Drizzle SQLite database.
+ *
+ * No `locks` store is returned: this backend has no distributed lock primitive,
+ * and bundling an `InMemoryLockStore` would silently hand multi-instance
+ * deployments a lock that does not lock across instances. Consumers that need a
+ * lock (e.g. `withSandbox`) transparently fall back to an in-process
+ * `InMemoryLockStore`; for cross-instance locking use a distributed backend such
+ * as the Cloudflare Durable Object lock (`@tanstack/ai-persistence-cloudflare`).
+ */
+export function drizzlePersistence(
+  db: DrizzleSqliteDb,
+  options?: DrizzlePersistenceOptions,
+) {
+  const tables = resolveTables(options?.schema)
+  return {
+    stores: {
+      messages: createMessageStore(db, tables),
+      runs: createRunStore(db, tables),
+      interrupts: createInterruptStore(db, tables),
+      metadata: createMetadataStore(db, tables),
+    },
+  }
+}
+
+function resolveTables(input?: TanstackAiSqliteSchema): TanstackAiTables {
+  if (!input) return schema
+  assertTanstackAiSchema(input)
+  // Safe widening: the stores only depend on the column *data* shapes, which
+  // `TanstackAiSqliteSchema` pins at the call site, and on the runtime table/column
+  // objects, which carry their own database names into the generated SQL. The
+  // concrete `TanstackAiTables` name literals are phantom types the store code
+  // never relies on.
+  return input as TanstackAiTables
+}
diff --git a/packages/ai-persistence-drizzle/src/migration-cli.ts b/packages/ai-persistence-drizzle/src/migration-cli.ts
new file mode 100644
index 000000000..c55b2b6cb
--- /dev/null
+++ b/packages/ai-persistence-drizzle/src/migration-cli.ts
@@ -0,0 +1,125 @@
+import { mkdir, readFile, writeFile } from 'node:fs/promises'
+import { join } from 'node:path'
+import { sqliteMigrations } from './migrations'
+
+export interface MigrationCliOutput {
+  writeStdout: (value: string) => void
+}
+
+export class MigrationCliError extends Error {
+  constructor(message: string) {
+    super(message)
+    this.name = 'MigrationCliError'
+  }
+}
+
+const usage = `Usage: tanstack-ai-drizzle-migrations (--out <directory> | --stdout) [--force]
+
+Options:
+  --out <directory>  Copy the ordered SQLite migration files.
+  --stdout           Print the ordered migration SQL.
+  --force            Replace divergent files when copying.
+  --help             Show this help.
+`
+
+interface ParsedArguments {
+  force: boolean
+  help: boolean
+  outDirectory?: string
+  stdout: boolean
+}
+
+function parseArguments(args: ReadonlyArray<string>): ParsedArguments {
+  let force = false
+  let help = false
+  let outDirectory: string | undefined
+  let stdout = false
+
+  for (let index = 0; index < args.length; index++) {
+    const argument = args[index]
+    if (argument === '--force') {
+      force = true
+    } else if (argument === '--help' || argument === '-h') {
+      help = true
+    } else if (argument === '--stdout') {
+      stdout = true
+    } else if (argument === '--out') {
+      const value = args[index + 1]
+      if (!value || value.startsWith('-')) {
+        throw new MigrationCliError('--out requires a directory.')
+      }
+      if (outDirectory !== undefined) {
+        throw new MigrationCliError('--out may only be provided once.')
+      }
+      outDirectory = value
+      index++
+    } else {
+      throw new MigrationCliError(`Unknown argument: ${argument ?? ''}`)
+    }
+  }
+
+  return { force, help, outDirectory, stdout }
+}
+
+function isMissingFileError(error: unknown): boolean {
+  return error instanceof Error && 'code' in error && error.code === 'ENOENT'
+}
+
+async function readExistingFile(path: string): Promise<string | undefined> {
+  try {
+    return await readFile(path, 'utf8')
+  } catch (error) {
+    if (isMissingFileError(error)) return undefined
+    throw error
+  }
+}
+
+/** Execute the migration asset CLI. Exported for deterministic CLI tests. */
+export async function runDrizzleMigrationsCli(
+  args: ReadonlyArray<string>,
+  output: MigrationCliOutput = {
+    writeStdout(value) {
+      process.stdout.write(value)
+    },
+  },
+): Promise<void> {
+  const parsed = parseArguments(args)
+  if (parsed.help) {
+    output.writeStdout(usage)
+    return
+  }
+
+  const outputCount =
+    Number(parsed.stdout) + Number(parsed.outDirectory != null)
+  if (outputCount !== 1) {
+    throw new MigrationCliError(
+      'Provide exactly one output mode: --out <directory> or --stdout.',
+    )
+  }
+  if (parsed.stdout) {
+    if (parsed.force) {
+      throw new MigrationCliError('--force can only be used with --out.')
+    }
+    output.writeStdout(
+      `${sqliteMigrations.map((migration) => migration.sql.trimEnd()).join('\n\n')}\n`,
+    )
+    return
+  }
+
+  const outDirectory = parsed.outDirectory
+  if (!outDirectory) {
+    throw new MigrationCliError('--out requires a directory.')
+  }
+  await mkdir(outDirectory, { recursive: true })
+  for (const migration of sqliteMigrations) {
+    const destination = join(outDirectory, migration.filename)
+    const existing = await readExistingFile(destination)
+    if (existing === migration.sql) continue
+    if (existing !== undefined && !parsed.force) {
+      throw new MigrationCliError(
+        `Refusing to overwrite divergent migration file: ${destination}. Re-run with --force to replace it.`,
+      )
+    }
+    await writeFile(destination, migration.sql, 'utf8')
+  }
+}
diff --git a/packages/ai-persistence-drizzle/src/migrations.ts b/packages/ai-persistence-drizzle/src/migrations.ts
new file mode 100644
index 000000000..889f6426f
--- /dev/null
+++ b/packages/ai-persistence-drizzle/src/migrations.ts
@@ -0,0 +1,20 @@
+import initialMigrationSql from './assets/0000_tanstack_ai_initial.sql?raw'
+
+/** A canonical SQLite migration bundled with the adapter. */
+export interface SqliteMigration {
+  /** Stable identifier recorded in the TanStack AI migration table. */
+  id: string
+  /** Filename used by the migration copy CLI. */
+  filename: string
+  /** SQL applied atomically with its migration bookkeeping row. */
+  sql: string
+}
+
+/** Ordered canonical migrations for the TanStack AI SQLite schema. */
+export const sqliteMigrations: ReadonlyArray<SqliteMigration> = [
+  {
+    id: '0000_tanstack_ai_initial',
+    filename: '0000_tanstack_ai_initial.sql',
+    sql: initialMigrationSql,
+  },
+]
diff --git a/packages/ai-persistence-drizzle/src/schema-cli-main.ts b/packages/ai-persistence-drizzle/src/schema-cli-main.ts
new file mode 100644
index 000000000..64c7f6439
--- /dev/null
+++ b/packages/ai-persistence-drizzle/src/schema-cli-main.ts
@@ -0,0 +1,10 @@
+#!/usr/bin/env node
+import { runDrizzleSchemaCli } from './schema-cli'
+
+try {
+  await runDrizzleSchemaCli(process.argv.slice(2))
+} catch (error) {
+  const message = error instanceof Error ? error.message : String(error)
+  process.stderr.write(`${message}\n`)
+  process.exitCode = 1
+}
diff --git a/packages/ai-persistence-drizzle/src/schema-cli.ts b/packages/ai-persistence-drizzle/src/schema-cli.ts
new file mode 100644
index 000000000..9d9de0930
--- /dev/null
+++ b/packages/ai-persistence-drizzle/src/schema-cli.ts
@@ -0,0 +1,124 @@
+import { mkdir, readFile, writeFile } from 'node:fs/promises'
+import { join } from 'node:path'
+import { drizzleSchemaFilename, drizzleSchemaSource } from './schema-source'
+
+export interface SchemaCliOutput {
+  writeStdout: (value: string) => void
+}
+
+export class SchemaCliError extends Error {
+  constructor(message: string) {
+    super(message)
+    this.name = 'SchemaCliError'
+  }
+}
+
+const usage = `Usage: tanstack-ai-drizzle-schema (--out <directory> | --stdout) [--force]
+
+Emits the TanStack AI Drizzle schema module so your project owns it: add the
+file to your drizzle-kit schema paths and pass it to drizzlePersistence(db, { schema }).
+
+Options:
+  --out <directory>  Copy the schema module into the directory.
+  --stdout           Print the schema module.
+  --force            Replace a divergent file when copying.
+  --help             Show this help.
+`
+
+interface ParsedArguments {
+  force: boolean
+  help: boolean
+  outDirectory?: string
+  stdout: boolean
+}
+
+function parseArguments(args: ReadonlyArray<string>): ParsedArguments {
+  let force = false
+  let help = false
+  let outDirectory: string | undefined
+  let stdout = false
+
+  for (let index = 0; index < args.length; index++) {
+    const argument = args[index]
+    if (argument === '--force') {
+      force = true
+    } else if (argument === '--help' || argument === '-h') {
+      help = true
+    } else if (argument === '--stdout') {
+      stdout = true
+    } else if (argument === '--out') {
+      const value = args[index + 1]
+      if (!value || value.startsWith('-')) {
+        throw new SchemaCliError('--out requires a directory.')
+      }
+      if (outDirectory !== undefined) {
+        throw new SchemaCliError('--out may only be provided once.')
+      }
+      outDirectory = value
+      index++
+    } else {
+      throw new SchemaCliError(`Unknown argument: ${argument ?? ''}`)
+    }
+  }
+
+  return { force, help, outDirectory, stdout }
+}
+
+function isMissingFileError(error: unknown): boolean {
+  return error instanceof Error && 'code' in error && error.code === 'ENOENT'
+}
+
+async function readExistingFile(path: string): Promise<string | undefined> {
+  try {
+    return await readFile(path, 'utf8')
+  } catch (error) {
+    if (isMissingFileError(error)) return undefined
+    throw error
+  }
+}
+
+/** Execute the schema asset CLI. Exported for deterministic CLI tests. */
+export async function runDrizzleSchemaCli(
+  args: ReadonlyArray<string>,
+  output: SchemaCliOutput = {
+    writeStdout(value) {
+      process.stdout.write(value)
+    },
+  },
+): Promise<void> {
+  const parsed = parseArguments(args)
+  if (parsed.help) {
+    output.writeStdout(usage)
+    return
+  }
+
+  const outputCount =
+    Number(parsed.stdout) + Number(parsed.outDirectory != null)
+  if (outputCount !== 1) {
+    throw new SchemaCliError(
+      'Provide exactly one output mode: --out <directory> or --stdout.',
+    )
+  }
+  if (parsed.stdout) {
+    if (parsed.force) {
+      throw new SchemaCliError('--force can only be used with --out.')
+    }
+    output.writeStdout(`${drizzleSchemaSource.trimEnd()}\n`)
+    return
+  }
+
+  const outDirectory = parsed.outDirectory
+  if (!outDirectory) {
+    throw new SchemaCliError('--out requires a directory.')
+  }
+  await mkdir(outDirectory, { recursive: true })
+  const destination = join(outDirectory, drizzleSchemaFilename)
+  const existing = await readExistingFile(destination)
+  if (existing === drizzleSchemaSource) return
+  if (existing !== undefined && !parsed.force) {
+    throw new SchemaCliError(
+      `Refusing to overwrite divergent schema file: ${destination}. Re-run with --force to replace it.`,
+    )
+  }
+  await writeFile(destination, drizzleSchemaSource, 'utf8')
+}
diff --git a/packages/ai-persistence-drizzle/src/schema-contract.ts b/packages/ai-persistence-drizzle/src/schema-contract.ts
new file mode 100644
index 000000000..9a8d53319
--- /dev/null
+++ b/packages/ai-persistence-drizzle/src/schema-contract.ts
@@ -0,0 +1,137 @@
+/**
+ * Structural contract for a user-supplied TanStack AI Drizzle schema.
+ *
+ * `drizzlePersistence` accepts any schema whose tables and columns carry the
+ * required data shapes; table and column **database names are free**. This lets
+ * a project own the schema file (emitted by `tanstack-ai-drizzle-schema`),
+ * generate DDL through its own drizzle-kit journal — including projects using
+ * drizzle's `casing` name transforms — and extend tables with extra columns
+ * (for example an ownership `user_id`) without falling out of contract.
+ *
+ * Only the columns listed here are read or written by the stores. Extra
+ * columns must therefore be nullable or defaulted so inserts succeed.
+ */
+import { Column, is } from 'drizzle-orm'
+import { SQLiteTable } from 'drizzle-orm/sqlite-core'
+import type { AnySQLiteColumn } from 'drizzle-orm/sqlite-core'
+import type { InterruptRecord, RunStatus } from '@tanstack/ai-persistence'
+import type { ModelMessage, TokenUsage } from '@tanstack/ai'
+
+/**
+ * A column whose decoded (`data`) type is `TData`. Name, table name, and
+ * driver specifics are intentionally unconstrained.
+ */
+type AiColumn<TData> = AnySQLiteColumn<{ data: TData }>
+
+type AiTable<TColumns> = SQLiteTable & TColumns
+
+/**
+ * The schema shape `drizzlePersistence` can operate over. `schema` exported
+ * from this package satisfies it, as does the file emitted by the
+ * `tanstack-ai-drizzle-schema` CLI. SQLite-only (the columns are Drizzle
+ * SQLite columns), which the name makes explicit.
+ */
+export interface TanstackAiSqliteSchema {
+  messages: AiTable<{
+    threadId: AiColumn<string>
+    messagesJson: AiColumn<Array<ModelMessage>>
+  }>
+  runs: AiTable<{
+    runId: AiColumn<string>
+    threadId: AiColumn<string>
+    status: AiColumn<RunStatus>
+    startedAt: AiColumn<number>
+    finishedAt: AiColumn<number>
+    error: AiColumn<string>
+    usageJson: AiColumn<TokenUsage>
+  }>
+  interrupts: AiTable<{
+    interruptId: AiColumn<string>
+    runId: AiColumn<string>
+    threadId: AiColumn<string>
+    status: AiColumn<InterruptRecord['status']>
+    requestedAt: AiColumn<number>
+    resolvedAt: AiColumn<number>
+    payloadJson: AiColumn<Record<string, unknown>>
+    responseJson: AiColumn<unknown>
+  }>
+  metadata: AiTable<{
+    scope: AiColumn<string>
+    key: AiColumn<string>
+    valueJson: AiColumn<unknown>
+  }>
+}
+
+/**
+ * @deprecated Renamed to {@link TanstackAiSqliteSchema} — the contract is
+ * SQLite-only, which the old name did not signal.
+ */
+export type TanstackAiSchema = TanstackAiSqliteSchema
+
+const requiredColumns: {
+  [K in keyof TanstackAiSqliteSchema]: ReadonlyArray<string>
+} = {
+  messages: ['threadId', 'messagesJson'],
+  runs: [
+    'runId',
+    'threadId',
+    'status',
+    'startedAt',
+    'finishedAt',
+    'error',
+    'usageJson',
+  ],
+  interrupts: [
+    'interruptId',
+    'runId',
+    'threadId',
+    'status',
+    'requestedAt',
+    'resolvedAt',
+    'payloadJson',
+    'responseJson',
+  ],
+  metadata: ['scope', 'key', 'valueJson'],
+}
+
+const tableKeys = Object.keys(requiredColumns) as Array<
+  keyof TanstackAiSqliteSchema
+>
+
+/** A user-supplied schema failed the {@link TanstackAiSqliteSchema} contract. */
+export class DrizzleSchemaError extends Error {
+  constructor(problems: ReadonlyArray<string>) {
+    super(
+      `Invalid TanStack AI Drizzle schema:\n${problems
+        .map((problem) => `  - ${problem}`)
+        .join('\n')}`,
+    )
+    this.name = 'DrizzleSchemaError'
+  }
+}
+
+/**
+ * Assert `input` structurally satisfies the store contract at runtime: every
+ * table is a Drizzle SQLite table and carries every column property the
+ * stores reference. Column data shapes are enforced by the
+ * {@link TanstackAiSqliteSchema} type at compile time and are not re-checked here.
+ */
+export function assertTanstackAiSchema(input: TanstackAiSqliteSchema): void {
+  const problems: Array<string> = []
+  for (const tableKey of tableKeys) {
+    const table: unknown = input[tableKey]
+    if (!is(table, SQLiteTable)) {
+      problems.push(`\`${tableKey}\` is not a Drizzle SQLite table.`)
+      continue
+    }
+    for (const columnKey of requiredColumns[tableKey]) {
+      const column: unknown = Reflect.get(table, columnKey)
+      if (!is(column, Column)) {
+        problems.push(
+          `\`${tableKey}.${columnKey}\` is missing or not a Drizzle column.`,
+        )
+      }
+    }
+  }
+  if (problems.length > 0) throw new DrizzleSchemaError(problems)
+}
diff --git a/packages/ai-persistence-drizzle/src/schema-source.ts b/packages/ai-persistence-drizzle/src/schema-source.ts
new file mode 100644
index 000000000..fbce6e2cd
--- /dev/null
+++ b/packages/ai-persistence-drizzle/src/schema-source.ts
@@ -0,0 +1,12 @@
+import source from './assets/tanstack-ai-schema.ts?raw'
+
+/** Filename used by the schema copy CLI. */
+export const drizzleSchemaFilename = 'tanstack-ai-schema.ts'
+
+/**
+ * Source text of the user-facing TanStack AI Drizzle schema module, emitted by
+ * `tanstack-ai-drizzle-schema`. Structurally identical to this package's
+ * bundled `schema` (a test enforces it); the copy exists so a project's own
+ * drizzle-kit journal can own the DDL.
+ */
+export const drizzleSchemaSource: string = source
diff --git a/packages/ai-persistence-drizzle/src/schema.ts b/packages/ai-persistence-drizzle/src/schema.ts
new file mode 100644
index 000000000..97ffc79a4
--- /dev/null
+++ b/packages/ai-persistence-drizzle/src/schema.ts
@@ -0,0 +1,78 @@
+/**
+ * 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; 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.
+ *
+ * PROVENANCE: `db:generate` emits DDL into `drizzle/`, but the runtime's
+ * `sqliteMigrations` (and the D1 sibling) load the DUPLICATE at
+ * `src/assets/0000_tanstack_ai_initial.sql`. `db:generate` alone does NOT touch
+ * that asset — copy the regenerated `drizzle/0000_tanstack_ai_initial.sql` over
+ * it, or the shipped migration goes stale. The package-contract test "keeps the
+ * shipped drizzle-kit migration equal to the embedded asset" fails on drift.
+ *
+ * Also keep this in sync with the sibling Prisma schema fragment
+ * (`@tanstack/ai-persistence-prisma`'s `src/assets/tanstack-ai.prisma`).
+ */
+import { 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] })],
+)
+
+/** The full state schema, for `drizzlePersistence(db)` and drizzle-kit. */
+export const schema = {
+  messages,
+  runs,
+  interrupts,
+  metadata,
+}
diff --git a/packages/ai-persistence-drizzle/src/sqlite-migrations.ts b/packages/ai-persistence-drizzle/src/sqlite-migrations.ts
new file mode 100644
index 000000000..1866c339d
--- /dev/null
+++ b/packages/ai-persistence-drizzle/src/sqlite-migrations.ts
@@ -0,0 +1,68 @@
+import type { DatabaseSync } from 'node:sqlite'
+import type { SqliteMigration } from './migrations'
+
+const MIGRATIONS_TABLE = '__tanstack_ai_migrations'
+
+/** Error raised when a bundled SQLite migration cannot be applied atomically. */
+export class SqliteMigrationError extends Error {
+  readonly migrationId: string
+
+  constructor(migrationId: string, cause: unknown) {
+    const detail = cause instanceof Error ? cause.message : String(cause)
+    super(`Failed to apply SQLite migration "${migrationId}": ${detail}`, {
+      cause,
+    })
+    this.name = 'SqliteMigrationError'
+    this.migrationId = migrationId
+  }
+}
+
+/**
+ * Apply ordered migrations with each migration SQL and bookkeeping insert in
+ * the same transaction. A failed migration leaves no partial schema changes or
+ * applied marker, so retrying after the underlying issue is corrected is safe.
+ */
+export function applySqliteMigrations(
+  database: DatabaseSync,
+  migrations: ReadonlyArray<SqliteMigration>,
+): void {
+  database.exec(`
+    CREATE TABLE IF NOT EXISTS ${MIGRATIONS_TABLE} (
+      migration_id TEXT PRIMARY KEY NOT NULL,
+      applied_at INTEGER NOT NULL
+    )
+  `)
+
+  const findApplied = database.prepare(
+    `SELECT migration_id FROM ${MIGRATIONS_TABLE} WHERE migration_id = ?`,
+  )
+  const recordApplied = database.prepare(
+    `INSERT INTO ${MIGRATIONS_TABLE} (migration_id, applied_at) VALUES (?, ?)`,
+  )
+
+  for (const migration of migrations) {
+    database.exec('BEGIN IMMEDIATE')
+    try {
+      if (findApplied.get(migration.id) !== undefined) {
+        database.exec('COMMIT')
+        continue
+      }
+      database.exec(migration.sql)
+      recordApplied.run(migration.id, Date.now())
+      database.exec('COMMIT')
+    } catch (error) {
+      try {
+        database.exec('ROLLBACK')
+      } catch (rollbackError) {
+        throw new SqliteMigrationError(
+          migration.id,
+          new AggregateError(
+            [error, rollbackError],
+            'Migration failed and its transaction could not be rolled back.',
+          ),
+        )
+      }
+      throw new SqliteMigrationError(migration.id, error)
+    }
+  }
+}
diff --git a/packages/ai-persistence-drizzle/src/sqlite.ts b/packages/ai-persistence-drizzle/src/sqlite.ts
new file mode 100644
index 000000000..0774c3ff0
--- /dev/null
+++ b/packages/ai-persistence-drizzle/src/sqlite.ts
@@ -0,0 +1,82 @@
+/** Node-only SQLite convenience factory for TanStack AI persistence. */
+import { mkdirSync } from 'node:fs'
+import { dirname } from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { DatabaseSync } from 'node:sqlite'
+import { drizzle } from 'drizzle-orm/sqlite-proxy'
+import { sqliteMigrations } from './migrations'
+import { applySqliteMigrations } from './sqlite-migrations'
+import { drizzlePersistence } from './index'
+
+export { SqliteMigrationError } from './sqlite-migrations'
+
+export interface SqlitePersistenceOptions {
+  /** `:memory:`, a filesystem path, or a `file:`-prefixed filesystem path. */
+  url: string
+  /** Apply the bundled TanStack AI migrations before creating stores. */
+  migrate?: boolean
+}
+
+/** Build persistence over Node's built-in SQLite driver. */
+export function sqlitePersistence(options: SqlitePersistenceOptions) {
+  const filename = normalizeSqliteUrl(options.url)
+  ensureParentDirectory(filename)
+  const sqlite = new DatabaseSync(filename)
+  try {
+    if (options.migrate) applySqliteMigrations(sqlite, sqliteMigrations)
+  } catch (error) {
+    sqlite.close()
+    throw error
+  }
+
+  const db = drizzle((sql, params, method) => {
+    const statement = sqlite.prepare(sql)
+    if (method === 'run') {
+      statement.run(...params)
+      return Promise.resolve({ rows: [] })
+    }
+    if (method === 'get') {
+      const row = statement.get(...params)
+      return Promise.resolve({ rows: row ? Object.values(row) : [] })
+    }
+    const rows = statement.all(...params)
+    return Promise.resolve({ rows: rows.map((row) => Object.values(row)) })
+  })
+
+  const persistence = drizzlePersistence(db)
+  let closed = false
+  return {
+    ...persistence,
+    close() {
+      if (closed) return
+      sqlite.close()
+      closed = true
+    },
+  }
+}
+
+function normalizeSqliteUrl(url: string): string {
+  if (url === ':memory:' || url === 'file::memory:') return ':memory:'
+  if (url.startsWith('file://')) return validateFilename(fileURLToPath(url))
+  if (url.startsWith('file:')) {
+    return validateFilename(url.slice('file:'.length))
+  }
+  const isWindowsPath = /^[A-Za-z]:[\\/]/.test(url)
+  if (!isWindowsPath && /^[A-Za-z][A-Za-z\d+.-]*:/.test(url)) {
+    throw new Error(`Unsupported SQLite URL scheme: ${url}`)
+  }
+  return validateFilename(url)
+}
+
+function validateFilename(filename: string): string {
+  if (filename.length === 0 || filename.includes('\0')) {
+    throw new Error('SQLite URL must identify a non-empty filesystem path')
+  }
+  return filename
+}
+
+function ensureParentDirectory(filename: string): void {
+  if (filename === ':memory:') return
+  const parent = dirname(filename)
+  if (parent !== '.') mkdirSync(parent, { recursive: true })
+}
diff --git a/packages/ai-persistence-drizzle/src/stores.ts b/packages/ai-persistence-drizzle/src/stores.ts
new file mode 100644
index 000000000..c840cdb2a
--- /dev/null
+++ b/packages/ai-persistence-drizzle/src/stores.ts
@@ -0,0 +1,274 @@
+/**
+ * AIPersistence store implementations over a Drizzle sqlite database.
+ *
+ * Each method mirrors the reference in-memory backend
+ * (`@tanstack/ai-persistence`'s `memory.ts`), including the insert-if-absent
+ * `InterruptStore.create` and `RunStore.createOrResume` semantics
+ * (`onConflictDoNothing`). JSON columns are handled by Drizzle's
+ * `text({ mode: 'json' })`.
+ */
+import { and, asc, eq } from 'drizzle-orm'
+import type { interrupts, runs, schema } from './schema'
+import type { BaseSQLiteDatabase } from 'drizzle-orm/sqlite-core'
+import type { ModelMessage } from '@tanstack/ai'
+import type {
+  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 DrizzleSqliteDb = Pick<
+  BaseSQLiteDatabase<'sync' | 'async', unknown>,
+  'select' | 'insert' | 'update' | 'delete'
+>
+
+/**
+ * @deprecated Renamed to {@link DrizzleSqliteDb} — this backend is SQLite-only
+ * (better-sqlite3, libsql, node:sqlite, D1). The old name did not signal that.
+ */
+export type DrizzleDb = DrizzleSqliteDb
+
+/**
+ * The concrete table set the stores are written against. A user-supplied
+ * {@link TanstackAiSchema} is validated by `assertTanstackAiSchema` and then
+ * used through this type: only column *data* shapes matter to the store code —
+ * table/column database names are carried by the runtime objects, so a schema
+ * with different names (drizzle `casing` transforms, renamed tables, extra
+ * app-owned columns) produces correct SQL through the same code paths.
+ */
+export type TanstackAiTables = typeof schema
+
+export function createMessageStore(
+  db: DrizzleSqliteDb,
+  { messages }: TanstackAiTables,
+): 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: DrizzleSqliteDb,
+  { runs }: TanstackAiTables,
+): 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: DrizzleSqliteDb,
+  { interrupts }: TanstackAiTables,
+): InterruptStore {
+  return {
+    async create(record) {
+      await db
+        .insert(interrupts)
+        .values({
+          interruptId: record.interruptId,
+          runId: record.runId,
+          threadId: record.threadId,
+          status: 'pending',
+          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)
+    },
+  }
+}
+
+function assertStorableMetadata(value: unknown): void {
+  if (value == null) {
+    throw new TypeError(
+      `TanStack AI metadata values must be defined, non-null JSON; received ${
+        value === undefined ? '`undefined`' : '`null`'
+      }. Use \`delete(scope, key)\` to clear a value.`,
+    )
+  }
+}
+
+export function createMetadataStore(
+  db: DrizzleSqliteDb,
+  { metadata }: TanstackAiTables,
+): 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) {
+      // SQL backends store JSON text in a NOT NULL column and cannot persist a
+      // nullish value: `text({ mode: 'json' })` binds a JS `null` as SQL NULL
+      // (it never serializes it to the text `"null"`), and `undefined` has no
+      // JSON at all — both violate NOT NULL. Reject nullish with a clear error
+      // (consistent with the sibling Prisma backend) instead of a cryptic
+      // driver failure. Unlike the in-memory reference, which round-trips
+      // nullish; use `delete` to clear.
+      assertStorableMetadata(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)))
+    },
+  }
+}
diff --git a/packages/ai-persistence-drizzle/tests/api-types.test-d.ts b/packages/ai-persistence-drizzle/tests/api-types.test-d.ts
new file mode 100644
index 000000000..bf414cb40
--- /dev/null
+++ b/packages/ai-persistence-drizzle/tests/api-types.test-d.ts
@@ -0,0 +1,39 @@
+import { expectTypeOf } from 'vitest'
+import type { DrizzleD1Database } from 'drizzle-orm/d1'
+import type {
+  InterruptStore,
+  MessageStore,
+  MetadataStore,
+  RunStore,
+} from '@tanstack/ai-persistence'
+import { drizzlePersistence, schema } from '../src/index'
+import { sqlitePersistence } from '../src/sqlite'
+import { schema as emittedSchema } from '../src/assets/tanstack-ai-schema'
+import { variantSchema } from './variant-schema'
+import type { TanstackAiSqliteSchema } from '../src/index'
+
+declare const d1Database: DrizzleD1Database
+const d1Persistence = drizzlePersistence(d1Database)
+expectTypeOf(d1Persistence.stores.messages).toEqualTypeOf<MessageStore>()
+expectTypeOf(d1Persistence.stores.runs).toEqualTypeOf<RunStore>()
+expectTypeOf(d1Persistence.stores.interrupts).toEqualTypeOf<InterruptStore>()
+expectTypeOf(d1Persistence.stores.metadata).toEqualTypeOf<MetadataStore>()
+// No `locks` store: this backend has no distributed lock (see drizzlePersistence).
+expectTypeOf(d1Persistence.stores).not.toHaveProperty('locks')
+
+const sqlite = sqlitePersistence({ url: ':memory:', migrate: true })
+expectTypeOf(sqlite.stores).toEqualTypeOf<typeof d1Persistence.stores>()
+expectTypeOf(sqlite.close).toEqualTypeOf<() => void>()
+
+// The bundled schema, the emitted schema asset, and a renamed/extended variant
+// must all satisfy the injectable schema contract.
+expectTypeOf(schema).toExtend<TanstackAiSqliteSchema>()
+expectTypeOf(emittedSchema).toExtend<TanstackAiSqliteSchema>()
+expectTypeOf(variantSchema).toExtend<TanstackAiSqliteSchema>()
+
+const customPersistence = drizzlePersistence(d1Database, {
+  schema: variantSchema,
+})
+expectTypeOf(customPersistence.stores).toEqualTypeOf<
+  typeof d1Persistence.stores
+>()
diff --git a/packages/ai-persistence-drizzle/tests/custom-schema.test.ts b/packages/ai-persistence-drizzle/tests/custom-schema.test.ts
new file mode 100644
index 000000000..7f94e73d0
--- /dev/null
+++ b/packages/ai-persistence-drizzle/tests/custom-schema.test.ts
@@ -0,0 +1,113 @@
+import { DatabaseSync } from 'node:sqlite'
+import { describe, expect, it } from 'vitest'
+import { eq } from 'drizzle-orm'
+import { sqliteTable, text } from 'drizzle-orm/sqlite-core'
+import { drizzle } from 'drizzle-orm/sqlite-proxy'
+import { runPersistenceConformance } from '@tanstack/ai-persistence/testkit'
+import { DrizzleSchemaError, drizzlePersistence, schema } from '../src/index'
+import { variantDdl, variantSchema } from './variant-schema'
+import type { TanstackAiSqliteSchema } from '../src/index'
+import type { DrizzleSqliteDb } from '../src/index'
+
+function createVariantDb(): { db: DrizzleSqliteDb; sqlite: DatabaseSync } {
+  const sqlite = new DatabaseSync(':memory:')
+  for (const statement of variantDdl) sqlite.exec(statement)
+  const db = drizzle((sql, params, method) => {
+    const statement = sqlite.prepare(sql)
+    if (method === 'run') {
+      statement.run(...params)
+      return Promise.resolve({ rows: [] })
+    }
+    if (method === 'get') {
+      const row = statement.get(...params)
+      return Promise.resolve({ rows: row ? Object.values(row) : [] })
+    }
+    const rows = statement.all(...params)
+    return Promise.resolve({ rows: rows.map((row) => Object.values(row)) })
+  })
+  return { db, sqlite }
+}
+
+// The full store contract must hold when the runtime operates over a schema
+// whose table and column database names all differ from the bundled ones.
+runPersistenceConformance(
+  'drizzle-sqlite (injected variant schema)',
+  () => drizzlePersistence(createVariantDb().db, { schema: variantSchema }),
+  // This backend has no distributed lock primitive.
+  { skip: ['locks'] },
+)
+
+describe('drizzlePersistence with an injected schema', () => {
+  it('writes through the injected table and column names', async () => {
+    const { db, sqlite } = createVariantDb()
+    const persistence = drizzlePersistence(db, { schema: variantSchema })
+
+    await persistence.stores.messages.saveThread('thread-1', [
+      { role: 'user', content: 'hello' },
+    ])
+
+    const row = sqlite
+      .prepare('SELECT threadId, messagesJson FROM app_ai_messages')
+      .get()
+    expect(row?.threadId).toBe('thread-1')
+    expect(JSON.parse(String(row?.messagesJson))).toEqual([
+      { role: 'user', content: 'hello' },
+    ])
+  })
+
+  it('coexists with app-owned columns on the same tables', async () => {
+    const { db, sqlite } = createVariantDb()
+    const persistence = drizzlePersistence(db, { schema: variantSchema })
+
+    await persistence.stores.messages.saveThread('thread-owned', [
+      { role: 'user', content: 'mine' },
+    ])
+    // The app claims ownership through its own extension column.
+    await db
+      .update(variantSchema.messages)
+      .set({ userId: 'user-42' })
+      .where(eq(variantSchema.messages.threadId, 'thread-owned'))
+
+    // Store updates leave the app-owned column untouched.
+    await persistence.stores.messages.saveThread('thread-owned', [
+      { role: 'user', content: 'mine' },
+      { role: 'assistant', content: 'yours' },
+    ])
+
+    const row = sqlite
+      .prepare('SELECT userId FROM app_ai_messages WHERE threadId = ?')
+      .get('thread-owned')
+    expect(row?.userId).toBe('user-42')
+    expect(
+      await persistence.stores.messages.loadThread('thread-owned'),
+    ).toHaveLength(2)
+  })
+
+  it('rejects a schema with missing tables or columns', () => {
+    const { db } = createVariantDb()
+
+    const { metadata: _dropped, ...withoutMetadata } = schema
+    expect(() =>
+      drizzlePersistence(db, {
+        schema: withoutMetadata as unknown as TanstackAiSqliteSchema,
+      }),
+    ).toThrow(DrizzleSchemaError)
+    expect(() =>
+      drizzlePersistence(db, {
+        schema: withoutMetadata as unknown as TanstackAiSqliteSchema,
+      }),
+    ).toThrow(/`metadata` is not a Drizzle SQLite table/)
+
+    const incompleteMessages = sqliteTable('messages', {
+      threadId: text('thread_id').primaryKey(),
+    })
+    expect(() =>
+      drizzlePersistence(db, {
+        schema: {
+          ...schema,
+          messages: incompleteMessages,
+        } as unknown as TanstackAiSqliteSchema,
+      }),
+    ).toThrow(/`messages\.messagesJson` is missing/)
+  })
+})
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..7c6e03df4
--- /dev/null
+++ b/packages/ai-persistence-drizzle/tests/drizzle.conformance.test.ts
@@ -0,0 +1,9 @@
+import { runPersistenceConformance } from '@tanstack/ai-persistence/testkit'
+import { sqlitePersistence } from '../src/sqlite'
+
+runPersistenceConformance(
+  'drizzle-sqlite',
+  () => sqlitePersistence({ url: ':memory:', migrate: true }),
+  // This backend has no distributed lock primitive.
+  { skip: ['locks'] },
+)
diff --git a/packages/ai-persistence-drizzle/tests/migration-cli.test.ts b/packages/ai-persistence-drizzle/tests/migration-cli.test.ts
new file mode 100644
index 000000000..2743a2cbb
--- /dev/null
+++ b/packages/ai-persistence-drizzle/tests/migration-cli.test.ts
@@ -0,0 +1,65 @@
+import { mkdtemp, readFile, rm, writeFile } from 'node:fs/promises'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { afterEach, describe, expect, it } from 'vitest'
+import { sqliteMigrations } from '../src/migrations'
+import { runDrizzleMigrationsCli } from '../src/migration-cli'
+
+const temporaryDirectories: Array<string> = []
+
+async function createTemporaryDirectory(): Promise<string> {
+  const directory = await mkdtemp(join(tmpdir(), 'tanstack-ai-drizzle-cli-'))
+  temporaryDirectories.push(directory)
+  return directory
+}
+
+afterEach(async () => {
+  await Promise.all(
+    temporaryDirectories
+      .splice(0)
+      .map((directory) => rm(directory, { recursive: true, force: true })),
+  )
+})
+
+describe('drizzle migrations CLI', () => {
+  it('prints canonical migration SQL to stdout', async () => {
+    let output = ''
+    await runDrizzleMigrationsCli(['--stdout'], {
+      writeStdout(value) {
+        output += value
+      },
+    })
+
+    expect(output).toBe(`${sqliteMigrations[0]?.sql.trimEnd()}\n`)
+  })
+
+  it('copies migrations without overwriting divergent files by default', async () => {
+    const directory = await createTemporaryDirectory()
+    await runDrizzleMigrationsCli(['--out', directory])
+
+    const migration = sqliteMigrations[0]
+    expect(migration).toBeDefined()
+    if (!migration) return
+    const destination = join(directory, migration.filename)
+    expect(await readFile(destination, 'utf8')).toBe(migration.sql)
+
+    await writeFile(destination, 'user-owned contents', 'utf8')
+    await expect(runDrizzleMigrationsCli(['--out', directory])).rejects.toThrow(
+      /refusing to overwrite/i,
+    )
+    expect(await readFile(destination, 'utf8')).toBe('user-owned contents')
+
+    await runDrizzleMigrationsCli(['--out', directory, '--force'])
+    expect(await readFile(destination, 'utf8')).toBe(migration.sql)
+  })
+
+  it('fails on ambiguous or incomplete output options', async () => {
+    const directory = await createTemporaryDirectory()
+    await expect(runDrizzleMigrationsCli([])).rejects.toThrow(
+      /--out.*--stdout/i,
+    )
+    await expect(
+      runDrizzleMigrationsCli(['--stdout', '--out', directory]),
+    ).rejects.toThrow(/exactly one/i)
+  })
+})
diff --git a/packages/ai-persistence-drizzle/tests/migrations.test.ts b/packages/ai-persistence-drizzle/tests/migrations.test.ts
new file mode 100644
index 000000000..f9a016907
--- /dev/null
+++ b/packages/ai-persistence-drizzle/tests/migrations.test.ts
@@ -0,0 +1,101 @@
+import { DatabaseSync } from 'node:sqlite'
+import { afterEach, describe, expect, it } from 'vitest'
+import { sqliteMigrations } from '../src/migrations'
+import { applySqliteMigrations } from '../src/sqlite-migrations'
+
+const databases: Array<DatabaseSync> = []
+
+function createDatabase(): DatabaseSync {
+  const database = new DatabaseSync(':memory:')
+  databases.push(database)
+  return database
+}
+
+afterEach(() => {
+  for (const database of databases.splice(0)) database.close()
+})
+
+describe('sqlite migrations', () => {
+  it('exposes an ordered canonical manifest and applies it idempotently', () => {
+    expect(sqliteMigrations.map((migration) => migration.id)).toEqual([
+      '0000_tanstack_ai_initial',
+    ])
+
+    const database = createDatabase()
+    applySqliteMigrations(database, sqliteMigrations)
+    applySqliteMigrations(database, sqliteMigrations)
+
+    const tableNames = database
+      .prepare(
+        "SELECT name FROM sqlite_master WHERE type = 'table' ORDER BY name",
+      )
+      .all()
+      .map((row) => row.name)
+    expect(tableNames).toEqual(
+      expect.arrayContaining([
+        '__tanstack_ai_migrations',
+        'interrupts',
+        'messages',
+        'metadata',
+        'runs',
+      ]),
+    )
+    expect(
+      database
+        .prepare('SELECT migration_id FROM __tanstack_ai_migrations')
+        .all(),
+    ).toEqual([{ migration_id: '0000_tanstack_ai_initial' }])
+  })
+
+  it('rolls back migration SQL and bookkeeping together, then permits retry', () => {
+    const database = createDatabase()
+    const failingMigration = {
+      id: '0000_retry_test',
+      filename: '0000_retry_test.sql',
+      sql: `
+        CREATE TABLE retry_target (id INTEGER PRIMARY KEY);
+        CREATE TRIGGER reject_migration_bookkeeping
+        BEFORE INSERT ON __tanstack_ai_migrations
+        BEGIN
+          SELECT RAISE(ABORT, 'bookkeeping failed');
+        END;
+      `,
+    }
+
+    expect(() => applySqliteMigrations(database, [failingMigration])).toThrow(
+      'bookkeeping failed',
+    )
+    expect(
+      database
+        .prepare(
+          "SELECT name FROM sqlite_master WHERE type = 'table' AND name = 'retry_target'",
+        )
+        .get(),
+    ).toBeUndefined()
+    expect(
+      database
+        .prepare('SELECT migration_id FROM __tanstack_ai_migrations')
+        .all(),
+    ).toEqual([])
+
+    applySqliteMigrations(database, [
+      {
+        ...failingMigration,
+        sql: 'CREATE TABLE retry_target (id INTEGER PRIMARY KEY);',
+      },
+    ])
+
+    expect(
+      database
+        .prepare(
+          "SELECT name FROM sqlite_master WHERE type = 'table' AND name = 'retry_target'",
+        )
+        .get(),
+    ).toEqual({ name: 'retry_target' })
+    expect(
+      database
+        .prepare('SELECT migration_id FROM __tanstack_ai_migrations')
+        .all(),
+    ).toEqual([{ migration_id: '0000_retry_test' }])
+  })
+})
diff --git a/packages/ai-persistence-drizzle/tests/package-contract.test.ts b/packages/ai-persistence-drizzle/tests/package-contract.test.ts
new file mode 100644
index 000000000..dfcdb7a6b
--- /dev/null
+++ b/packages/ai-persistence-drizzle/tests/package-contract.test.ts
@@ -0,0 +1,67 @@
+import { readFile } from 'node:fs/promises'
+import { fileURLToPath } from 'node:url'
+import { describe, expect, it } from 'vitest'
+import packageJson from '../package.json'
+
+describe('drizzle package contract', () => {
+  it('publishes the edge root, Node sqlite subpath, CLI, and migration assets', () => {
+    expect(packageJson.exports).toEqual({
+      '.': {
+        types: './dist/esm/index.d.ts',
+        import: './dist/esm/index.js',
+      },
+      './sqlite': {
+        types: './dist/esm/sqlite.d.ts',
+        import: './dist/esm/sqlite.js',
+      },
+    })
+    expect(packageJson.bin).toEqual({
+      'tanstack-ai-drizzle-migrations':
+        './bin/tanstack-ai-drizzle-migrations.mjs',
+      'tanstack-ai-drizzle-schema': './bin/tanstack-ai-drizzle-schema.mjs',
+    })
+    expect(packageJson.files).toEqual(
+      expect.arrayContaining(['bin', 'dist', 'src', 'drizzle']),
+    )
+  })
+
+  it('keeps Node built-ins and Buffer out of the root import graph', async () => {
+    const rootFiles = [
+      'index.ts',
+      'migrations.ts',
+      'schema.ts',
+      'schema-contract.ts',
+      'schema-source.ts',
+      'stores.ts',
+    ]
+    for (const filename of rootFiles) {
+      const contents = await readFile(
+        fileURLToPath(new URL(`../src/${filename}`, import.meta.url)),
+        'utf8',
+      )
+      expect(contents, filename).not.toMatch(/from ['"]node:/)
+      expect(contents, filename).not.toMatch(/\bBuffer\b/)
+    }
+    const root = await readFile(
+      fileURLToPath(new URL('../src/index.ts', import.meta.url)),
+      'utf8',
+    )
+    expect(root).not.toMatch(/from ['"].*sqlite/)
+  })
+
+  it('keeps the shipped drizzle-kit migration equal to the embedded asset', async () => {
+    const embedded = await readFile(
+      fileURLToPath(
+        new URL('../src/assets/0000_tanstack_ai_initial.sql', import.meta.url),
+      ),
+      'utf8',
+    )
+    const shipped = await readFile(
+      fileURLToPath(
+        new URL('../drizzle/0000_tanstack_ai_initial.sql', import.meta.url),
+      ),
+      'utf8',
+    )
+    expect(shipped).toBe(embedded)
+  })
+})
diff --git a/packages/ai-persistence-drizzle/tests/schema-cli.test.ts b/packages/ai-persistence-drizzle/tests/schema-cli.test.ts
new file mode 100644
index 000000000..c24afee87
--- /dev/null
+++ b/packages/ai-persistence-drizzle/tests/schema-cli.test.ts
@@ -0,0 +1,67 @@
+import { mkdtemp, readFile, rm, writeFile } from 'node:fs/promises'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { afterEach, describe, expect, it } from 'vitest'
+import { drizzleSchemaFilename, drizzleSchemaSource } from '../src/index'
+import { runDrizzleSchemaCli } from '../src/schema-cli'
+
+const temporaryDirectories: Array<string> = []
+
+async function createTemporaryDirectory(): Promise<string> {
+  const directory = await mkdtemp(join(tmpdir(), 'tanstack-ai-drizzle-schema-'))
+  temporaryDirectories.push(directory)
+  return directory
+}
+
+afterEach(async () => {
+  await Promise.all(
+    temporaryDirectories
+      .splice(0)
+      .map((directory) => rm(directory, { recursive: true, force: true })),
+  )
+})
+
+describe('Drizzle schema CLI', () => {
+  it('prints the schema module to stdout', async () => {
+    let output = ''
+    await runDrizzleSchemaCli(['--stdout'], {
+      writeStdout(value) {
+        output += value
+      },
+    })
+    expect(output).toBe(`${drizzleSchemaSource.trimEnd()}\n`)
+    expect(output).toContain('sqliteTable')
+    expect(output).toContain('drizzlePersistence(db, { schema })')
+  })
+
+  it('copies the schema without overwriting divergent files by default', async () => {
+    const directory = await createTemporaryDirectory()
+    await runDrizzleSchemaCli(['--out', directory])
+
+    const destination = join(directory, drizzleSchemaFilename)
+    expect(await readFile(destination, 'utf8')).toBe(drizzleSchemaSource)
+
+    // Re-running against an identical file is a no-op.
+    await runDrizzleSchemaCli(['--out', directory])
+
+    await writeFile(destination, 'user-owned contents', 'utf8')
+    await expect(runDrizzleSchemaCli(['--out', directory])).rejects.toThrow(
+      /refusing to overwrite/i,
+    )
+    expect(await readFile(destination, 'utf8')).toBe('user-owned contents')
+
+    await runDrizzleSchemaCli(['--out', directory, '--force'])
+    expect(await readFile(destination, 'utf8')).toBe(drizzleSchemaSource)
+  })
+
+  it('fails on ambiguous or incomplete output options', async () => {
+    const directory = await createTemporaryDirectory()
+    await expect(runDrizzleSchemaCli([])).rejects.toThrow(/--out.*--stdout/i)
+    await expect(
+      runDrizzleSchemaCli(['--stdout', '--out', directory]),
+    ).rejects.toThrow(/exactly one/i)
+    await expect(runDrizzleSchemaCli(['--stdout', '--force'])).rejects.toThrow(
+      /--force can only be used with --out/i,
+    )
+  })
+})
diff --git a/packages/ai-persistence-drizzle/tests/schema-source.test.ts b/packages/ai-persistence-drizzle/tests/schema-source.test.ts
new file mode 100644
index 000000000..f72716a3f
--- /dev/null
+++ b/packages/ai-persistence-drizzle/tests/schema-source.test.ts
@@ -0,0 +1,31 @@
+import { describe, expect, it } from 'vitest'
+import { getTableConfig } from 'drizzle-orm/sqlite-core'
+import { schema as bundled } from '../src/schema'
+import { schema as emitted } from '../src/assets/tanstack-ai-schema'
+import type { SQLiteTable } from 'drizzle-orm/sqlite-core'
+
+function normalize(table: SQLiteTable) {
+  const config = getTableConfig(table)
+  return {
+    name: config.name,
+    columns: config.columns.map((column) => ({
+      name: column.name,
+      sqlType: column.getSQLType(),
+      notNull: column.notNull,
+      primary: column.primary,
+    })),
+    primaryKeys: config.primaryKeys.map((primaryKey) =>
+      primaryKey.columns.map((column) => column.name),
+    ),
+  }
+}
+
+describe('emitted schema asset', () => {
+  it('is structurally identical to the bundled schema', () => {
+    const tableKeys = Object.keys(bundled) as Array<keyof typeof bundled>
+    expect(Object.keys(emitted)).toEqual(Object.keys(bundled))
+    for (const key of tableKeys) {
+      expect(normalize(emitted[key]), key).toEqual(normalize(bundled[key]))
+    }
+  })
+})
diff --git a/packages/ai-persistence-drizzle/tests/sqlite.test.ts b/packages/ai-persistence-drizzle/tests/sqlite.test.ts
new file mode 100644
index 000000000..299081cc0
--- /dev/null
+++ b/packages/ai-persistence-drizzle/tests/sqlite.test.ts
@@ -0,0 +1,53 @@
+import { mkdtemp, rm, stat } from 'node:fs/promises'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { afterEach, describe, expect, it } from 'vitest'
+import { sqlitePersistence } from '../src/sqlite'
+
+const temporaryDirectories: Array<string> = []
+
+afterEach(async () => {
+  for (const directory of temporaryDirectories.splice(0)) {
+    await rm(directory, { recursive: true, force: true })
+  }
+})
+
+async function temporaryDirectory(): Promise<string> {
+  const directory = await mkdtemp(join(tmpdir(), 'tanstack-ai-sqlite-'))
+  temporaryDirectories.push(directory)
+  return directory
+}
+
+describe('sqlitePersistence', () => {
+  it('creates a missing parent directory for a filesystem database', async () => {
+    const root = await temporaryDirectory()
+    const databasePath = join(root, 'nested', 'state.sqlite')
+    const persistence = sqlitePersistence({
+      url: `file:${databasePath}`,
+      migrate: true,
+    })
+
+    try {
+      await expect(stat(databasePath)).resolves.toMatchObject({
+        isFile: expect.any(Function),
+      })
+    } finally {
+      persistence.close()
+    }
+  })
+
+  it('exposes an idempotent close for the database handle it owns', () => {
+    const persistence = sqlitePersistence({ url: ':memory:' })
+
+    expect(() => {
+      persistence.close()
+      persistence.close()
+    }).not.toThrow()
+  })
+
+  it('rejects non-file URI schemes before touching the filesystem', () => {
+    expect(() =>
+      sqlitePersistence({ url: 'https://example.test/state.sqlite' }),
+    ).toThrow(/unsupported SQLite URL/i)
+  })
+})
diff --git a/packages/ai-persistence-drizzle/tests/store-behavior.test.ts b/packages/ai-persistence-drizzle/tests/store-behavior.test.ts
new file mode 100644
index 000000000..f5e680a9b
--- /dev/null
+++ b/packages/ai-persistence-drizzle/tests/store-behavior.test.ts
@@ -0,0 +1,40 @@
+import { afterEach, describe, expect, it } from 'vitest'
+import { sqlitePersistence } from '../src/sqlite'
+
+type Persistence = ReturnType<typeof sqlitePersistence>
+
+const open: Array<Persistence> = []
+
+function persistence(): Persistence {
+  const created = sqlitePersistence({ url: ':memory:', migrate: true })
+  open.push(created)
+  return created
+}
+
+afterEach(() => {
+  for (const created of open.splice(0)) created.close()
+})
+
+describe('drizzle metadata nullish values', () => {
+  it('rejects nullish values with a clear error instead of a NOT NULL crash', async () => {
+    const { stores } = persistence()
+
+    // A NOT NULL json column cannot store nullish; surface a clear, actionable
+    // error (consistent with the Prisma backend) rather than a driver crash.
+    await expect(stores.metadata.set('scope', 'u', undefined)).rejects.toThrow(
+      /metadata values must be defined/,
+    )
+    await expect(stores.metadata.set('scope', 'n', null)).rejects.toThrow(
+      /metadata values must be defined/,
+    )
+    expect(await stores.metadata.get('scope', 'u')).toBeNull()
+
+    // Falsy-but-defined values are stored and round-trip.
+    await stores.metadata.set('scope', 'zero', 0)
+    expect(await stores.metadata.get('scope', 'zero')).toBe(0)
+    await stores.metadata.set('scope', 'empty', '')
+    expect(await stores.metadata.get('scope', 'empty')).toBe('')
+    await stores.metadata.set('scope', 'obj', { a: 1 })
+    expect(await stores.metadata.get('scope', 'obj')).toEqual({ a: 1 })
+  })
+})
diff --git a/packages/ai-persistence-drizzle/tests/variant-schema.ts b/packages/ai-persistence-drizzle/tests/variant-schema.ts
new file mode 100644
index 000000000..46551464d
--- /dev/null
+++ b/packages/ai-persistence-drizzle/tests/variant-schema.ts
@@ -0,0 +1,93 @@
+/**
+ * A deliberately renamed copy of the TanStack AI schema for exercising
+ * `drizzlePersistence(db, { schema })`: prefixed table names, camelCase column
+ * names (as a project using drizzle `casing`-style conventions would have),
+ * and an extra app-owned `userId` ownership column on the messages table.
+ * Structure (data shapes, nullability, primary keys) matches the contract.
+ */
+import { integer, primaryKey, sqliteTable, text } from 'drizzle-orm/sqlite-core'
+import type { InterruptRecord, RunStatus } from '@tanstack/ai-persistence'
+import type { ModelMessage, TokenUsage } from '@tanstack/ai'
+
+const messages = sqliteTable('app_ai_messages', {
+  threadId: text('threadId').primaryKey(),
+  messagesJson: text('messagesJson', { mode: 'json' })
+    .$type<Array<ModelMessage>>()
+    .notNull(),
+  // App-owned extension the TanStack AI stores never read or write.
+  userId: text('userId'),
+})
+
+const runs = sqliteTable('app_ai_runs', {
+  runId: text('runId').primaryKey(),
+  threadId: text('threadId').notNull(),
+  status: text('status').$type<RunStatus>().notNull(),
+  startedAt: integer('startedAt').notNull(),
+  finishedAt: integer('finishedAt'),
+  error: text('errorText'),
+  usageJson: text('usageJson', { mode: 'json' }).$type<TokenUsage>(),
+})
+
+const interrupts = sqliteTable('app_ai_interrupts', {
+  interruptId: text('interruptId').primaryKey(),
+  runId: text('runId').notNull(),
+  threadId: text('threadId').notNull(),
+  status: text('status').$type<InterruptRecord['status']>().notNull(),
+  requestedAt: integer('requestedAt').notNull(),
+  resolvedAt: integer('resolvedAt'),
+  payloadJson: text('payloadJson', { mode: 'json' })
+    .$type<Record<string, unknown>>()
+    .notNull(),
+  responseJson: text('responseJson', { mode: 'json' }).$type<unknown>(),
+})
+
+const metadata = sqliteTable(
+  'app_ai_metadata',
+  {
+    scope: text('scopeName').notNull(),
+    key: text('keyName').notNull(),
+    valueJson: text('valueJson', { mode: 'json' }).$type<unknown>().notNull(),
+  },
+  (table) => [primaryKey({ columns: [table.scope, table.key] })],
+)
+
+export const variantSchema = {
+  messages,
+  runs,
+  interrupts,
+  metadata,
+}
+
+/** DDL matching {@link variantSchema}, applied directly in tests. */
+export const variantDdl: ReadonlyArray<string> = [
+  `CREATE TABLE app_ai_messages (
+    threadId text PRIMARY KEY NOT NULL,
+    messagesJson text NOT NULL,
+    userId text
+  );`,
+  `CREATE TABLE app_ai_runs (
+    runId text PRIMARY KEY NOT NULL,
+    threadId text NOT NULL,
+    status text NOT NULL,
+    startedAt integer NOT NULL,
+    finishedAt integer,
+    errorText text,
+    usageJson text
+  );`,
+  `CREATE TABLE app_ai_interrupts (
+    interruptId text PRIMARY KEY NOT NULL,
+    runId text NOT NULL,
+    threadId text NOT NULL,
+    status text NOT NULL,
+    requestedAt integer NOT NULL,
+    resolvedAt integer,
+    payloadJson text NOT NULL,
+    responseJson text
+  );`,
+  `CREATE TABLE app_ai_metadata (
+    scopeName text NOT NULL,
+    keyName text NOT NULL,
+    valueJson text NOT NULL,
+    PRIMARY KEY(scopeName, keyName)
+  );`,
+]
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..05551030c
--- /dev/null
+++ b/packages/ai-persistence-drizzle/vite.config.ts
@@ -0,0 +1,42 @@
+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/sqlite.ts',
+      './src/cli.ts',
+      './src/schema-cli-main.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/bin/tanstack-ai-prisma-models.mjs b/packages/ai-persistence-prisma/bin/tanstack-ai-prisma-models.mjs
new file mode 100644
index 000000000..0a4de6588
--- /dev/null
+++ b/packages/ai-persistence-prisma/bin/tanstack-ai-prisma-models.mjs
@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+import '../dist/esm/cli.js'
diff --git a/packages/ai-persistence-prisma/package.json b/packages/ai-persistence-prisma/package.json
new file mode 100644
index 000000000..f83cd0e39
--- /dev/null
+++ b/packages/ai-persistence-prisma/package.json
@@ -0,0 +1,91 @@
+{
+  "name": "@tanstack/ai-persistence-prisma",
+  "version": "0.0.0",
+  "description": "Prisma persistence for TanStack AI with a provider-neutral models fragment and bring-your-own migrated 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",
+    "database"
+  ],
+  "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"
+    }
+  },
+  "bin": {
+    "tanstack-ai-prisma-models": "./bin/tanstack-ai-prisma-models.mjs"
+  },
+  "files": [
+    "bin",
+    "dist",
+    "src",
+    "prisma/tanstack-ai.prisma"
+  ],
+  "scripts": {
+    "build": "vite build",
+    "clean": "premove ./build ./dist",
+    "db:generate": "prisma generate --schema ./prisma",
+    "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.7.0",
+    "@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/schema.prisma b/packages/ai-persistence-prisma/prisma/schema.prisma
new file mode 100644
index 000000000..3506e60fb
--- /dev/null
+++ b/packages/ai-persistence-prisma/prisma/schema.prisma
@@ -0,0 +1,10 @@
+// Internal test-client configuration. The models live in the provider-neutral
+// sibling fragment that is shipped to package consumers.
+generator client {
+  provider = "prisma-client-js"
+}
+
+datasource db {
+  provider = "sqlite"
+  url      = env("DATABASE_URL")
+}
diff --git a/packages/ai-persistence-prisma/prisma/tanstack-ai.prisma b/packages/ai-persistence-prisma/prisma/tanstack-ai.prisma
new file mode 100644
index 000000000..aa716415b
--- /dev/null
+++ b/packages/ai-persistence-prisma/prisma/tanstack-ai.prisma
@@ -0,0 +1,50 @@
+// Provider-neutral TanStack AI persistence models.
+//
+// Copy this file into a Prisma multi-file schema directory, then create and
+// apply migrations using the application's selected provider and normal Prisma
+// workflow. This fragment intentionally contains no datasource or generator.
+
+/// 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")
+}
diff --git a/packages/ai-persistence-prisma/src/assets.d.ts b/packages/ai-persistence-prisma/src/assets.d.ts
new file mode 100644
index 000000000..33c9a3e00
--- /dev/null
+++ b/packages/ai-persistence-prisma/src/assets.d.ts
@@ -0,0 +1,4 @@
+declare module '*.prisma?raw' {
+  const contents: string
+  export default contents
+}
diff --git a/packages/ai-persistence-prisma/src/assets/tanstack-ai.prisma b/packages/ai-persistence-prisma/src/assets/tanstack-ai.prisma
new file mode 100644
index 000000000..aa716415b
--- /dev/null
+++ b/packages/ai-persistence-prisma/src/assets/tanstack-ai.prisma
@@ -0,0 +1,50 @@
+// Provider-neutral TanStack AI persistence models.
+//
+// Copy this file into a Prisma multi-file schema directory, then create and
+// apply migrations using the application's selected provider and normal Prisma
+// workflow. This fragment intentionally contains no datasource or generator.
+
+/// 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")
+}
diff --git a/packages/ai-persistence-prisma/src/cli.ts b/packages/ai-persistence-prisma/src/cli.ts
new file mode 100644
index 000000000..21273f6e3
--- /dev/null
+++ b/packages/ai-persistence-prisma/src/cli.ts
@@ -0,0 +1,10 @@
+#!/usr/bin/env node
+import { runPrismaModelsCli } from './models-cli'
+
+try {
+  await runPrismaModelsCli(process.argv.slice(2))
+} catch (error) {
+  const message = error instanceof Error ? error.message : String(error)
+  process.stderr.write(`${message}\n`)
+  process.exitCode = 1
+}
diff --git a/packages/ai-persistence-prisma/src/index.ts b/packages/ai-persistence-prisma/src/index.ts
new file mode 100644
index 000000000..3250f5920
--- /dev/null
+++ b/packages/ai-persistence-prisma/src/index.ts
@@ -0,0 +1,57 @@
+/**
+ * Prisma-backed state persistence for TanStack AI.
+ *
+ * Add the provider-neutral {@link prismaModels} fragment to a Prisma multi-file
+ * schema, run Prisma's normal migration workflow for your selected provider,
+ * then pass the generated client to {@link prismaPersistence}.
+ */
+import { resolveDelegates } from './model-contract'
+import {
+  createInterruptStore,
+  createMessageStore,
+  createMetadataStore,
+  createRunStore,
+} from './stores'
+import type { PrismaModelMap } from './model-contract'
+import type { PrismaClient } from '@prisma/client'
+
+export { prismaModels, prismaModelsFilename } from './models'
+export { PrismaModelError } from './model-contract'
+export type { PrismaModelMap } from './model-contract'
+
+export interface PrismaPersistenceOptions {
+  /**
+   * Rename the TanStack AI models in your copy of the fragment — for example
+   * to avoid a collision with an existing `Message` or `Run` model — and map
+   * each store to the renamed client delegate here. Values are the camelCase
+   * client accessor names: `model ChatMessage` → `{ messages: 'chatMessage' }`.
+   * Keep the field names and types from the fragment; database table and
+   * column names are already yours via `@@map` / `@map`.
+   */
+  models?: PrismaModelMap
+}
+
+/**
+ * Wire TanStack AI persistence stores over a migrated Prisma client.
+ *
+ * No `locks` store is returned: this backend has no distributed lock primitive,
+ * and bundling an `InMemoryLockStore` would silently hand multi-instance
+ * deployments a lock that does not lock across instances. Consumers that need a
+ * lock (e.g. `withSandbox`) transparently fall back to an in-process
+ * `InMemoryLockStore`; for cross-instance locking use a distributed backend such
+ * as the Cloudflare Durable Object lock (`@tanstack/ai-persistence-cloudflare`).
+ */
+export function prismaPersistence(
+  prisma: PrismaClient,
+  options?: PrismaPersistenceOptions,
+) {
+  const delegates = resolveDelegates(prisma, options?.models)
+  return {
+    stores: {
+      messages: createMessageStore(delegates),
+      runs: createRunStore(delegates),
+      interrupts: createInterruptStore(delegates),
+      metadata: createMetadataStore(delegates),
+    },
+  }
+}
diff --git a/packages/ai-persistence-prisma/src/model-contract.ts b/packages/ai-persistence-prisma/src/model-contract.ts
new file mode 100644
index 000000000..d2c9d618f
--- /dev/null
+++ b/packages/ai-persistence-prisma/src/model-contract.ts
@@ -0,0 +1,217 @@
+/**
+ * Structural contract for the Prisma model delegates the stores operate over.
+ *
+ * `prismaPersistence` accepts a model-name map so applications can rename the
+ * TanStack AI models in their own copy of the fragment — for example to avoid
+ * collisions with an existing `Message` or `Run` model — and point the runtime
+ * at the renamed delegates (`prismaPersistence(prisma, { models })`).
+ *
+ * What stays fixed is the **client-level field surface**: field names
+ * (`threadId`, `messagesJson`, …), their types, and the default composite
+ * unique alias `scope_key` on the metadata model. Database table and column
+ * names are already yours via `@@map` / `@map` in the fragment, and extra
+ * app-owned fields are ignored by the stores (keep them optional or defaulted
+ * so creates succeed).
+ *
+ * The delegate interfaces below are the minimal structural slice of the
+ * generated client the stores call; the generated delegates satisfy them
+ * (asserted in the package's type tests).
+ */
+
+export interface MessageRow {
+  threadId: string
+  messagesJson: string
+}
+
+export interface RunRow {
+  runId: string
+  threadId: string
+  status: string
+  startedAt: bigint
+  finishedAt: bigint | null
+  error: string | null
+  usageJson: string | null
+}
+
+export interface InterruptRow {
+  interruptId: string
+  runId: string
+  threadId: string
+  status: string
+  requestedAt: bigint
+  resolvedAt: bigint | null
+  payloadJson: string
+  responseJson: string | null
+}
+
+export interface MetadataRow {
+  scope: string
+  key: string
+  valueJson: string
+}
+
+export interface MessageDelegate {
+  findUnique: (args: {
+    where: { threadId: string }
+  }) => Promise<MessageRow | null>
+  upsert: (args: {
+    where: { threadId: string }
+    create: { threadId: string; messagesJson: string }
+    update: { messagesJson: string }
+  }) => Promise<unknown>
+}
+
+export interface RunDelegate {
+  findUnique: (args: { where: { runId: string } }) => Promise<RunRow | null>
+  upsert: (args: {
+    where: { runId: string }
+    create: {
+      runId: string
+      threadId: string
+      status: string
+      startedAt: bigint
+    }
+    update: Record<string, never>
+  }) => Promise<unknown>
+  updateMany: (args: {
+    where: { runId: string }
+    data: {
+      status?: string
+      finishedAt?: bigint
+      error?: string
+      usageJson?: string
+    }
+  }) => Promise<unknown>
+}
+
+export interface InterruptDelegate {
+  findUnique: (args: {
+    where: { interruptId: string }
+  }) => Promise<InterruptRow | null>
+  findMany: (args: {
+    where: { threadId?: string; runId?: string; status?: string }
+    orderBy: { requestedAt: 'asc' }
+  }) => Promise<Array<InterruptRow>>
+  upsert: (args: {
+    where: { interruptId: string }
+    create: {
+      interruptId: string
+      runId: string
+      threadId: string
+      status: string
+      requestedAt: bigint
+      payloadJson: string
+      responseJson: string | null
+    }
+    update: Record<string, never>
+  }) => Promise<unknown>
+  updateMany: (args: {
+    where: { interruptId: string }
+    data: { status: string; resolvedAt: bigint; responseJson?: string | null }
+  }) => Promise<unknown>
+}
+
+export interface MetadataDelegate {
+  findUnique: (args: {
+    where: { scope_key: { scope: string; key: string } }
+  }) => Promise<MetadataRow | null>
+  upsert: (args: {
+    where: { scope_key: { scope: string; key: string } }
+    create: { scope: string; key: string; valueJson: string }
+    update: { valueJson: string }
+  }) => Promise<unknown>
+  deleteMany: (args: {
+    where: { scope: string; key: string }
+  }) => Promise<unknown>
+}
+
+/** The delegate set the stores operate over. */
+export interface TanstackAiDelegates {
+  message: MessageDelegate
+  run: RunDelegate
+  interrupt: InterruptDelegate
+  metadata: MetadataDelegate
+}
+
+/**
+ * Store key → Prisma client delegate property. Values are the camelCase
+ * client accessor names (`prisma.<name>`), not the PascalCase model names:
+ * a `model ChatMessage` is reached as `chatMessage`.
+ */
+export interface PrismaModelMap {
+  messages?: string
+  runs?: string
+  interrupts?: string
+  metadata?: string
+}
+
+const defaultModelNames: Required<PrismaModelMap> = {
+  messages: 'message',
+  runs: 'run',
+  interrupts: 'interrupt',
+  metadata: 'metadata',
+}
+
+const storeKeys = Object.keys(defaultModelNames) as Array<
+  keyof Required<PrismaModelMap>
+>
+
+const delegateKeyByStoreKey: {
+  [K in keyof Required<PrismaModelMap>]: keyof TanstackAiDelegates
+} = {
+  messages: 'message',
+  runs: 'run',
+  interrupts: 'interrupt',
+  metadata: 'metadata',
+}
+
+/** A model map pointed `prismaPersistence` at missing or invalid delegates. */
+export class PrismaModelError extends Error {
+  constructor(problems: ReadonlyArray<string>) {
+    super(
+      `Invalid TanStack AI Prisma model mapping:\n${problems
+        .map((problem) => `  - ${problem}`)
+        .join('\n')}`,
+    )
+    this.name = 'PrismaModelError'
+  }
+}
+
+function isDelegate(value: unknown): boolean {
+  return (
+    value !== null &&
+    typeof value === 'object' &&
+    typeof Reflect.get(value, 'findUnique') === 'function' &&
+    typeof Reflect.get(value, 'upsert') === 'function'
+  )
+}
+
+/**
+ * Resolve the four store delegates off the client, applying any model-name
+ * overrides and verifying each resolved delegate looks like a Prisma model
+ * delegate. Field shapes are enforced at compile time by the delegate
+ * interfaces and are not re-checked here.
+ */
+export function resolveDelegates(
+  client: object,
+  models?: PrismaModelMap,
+): TanstackAiDelegates {
+  const problems: Array<string> = []
+  const resolved: Partial<Record<keyof TanstackAiDelegates, unknown>> = {}
+  for (const storeKey of storeKeys) {
+    const modelName = models?.[storeKey] ?? defaultModelNames[storeKey]
+    const candidate: unknown = Reflect.get(client, modelName)
+    if (!isDelegate(candidate)) {
+      problems.push(
+        `\`${storeKey}\` maps to \`client.${modelName}\`, which is not a Prisma model delegate.`,
+      )
+      continue
+    }
+    resolved[delegateKeyByStoreKey[storeKey]] = candidate
+  }
+  if (problems.length > 0) throw new PrismaModelError(problems)
+  // Safe narrowing: presence and delegate shape were verified above; the
+  // per-method argument/result types are pinned by the delegate interfaces,
+  // which the generated client's delegates satisfy (asserted in type tests).
+  return resolved as TanstackAiDelegates
+}
diff --git a/packages/ai-persistence-prisma/src/models-cli.ts b/packages/ai-persistence-prisma/src/models-cli.ts
new file mode 100644
index 000000000..42410dd8e
--- /dev/null
+++ b/packages/ai-persistence-prisma/src/models-cli.ts
@@ -0,0 +1,121 @@
+import { mkdir, readFile, writeFile } from 'node:fs/promises'
+import { join } from 'node:path'
+import { prismaModels, prismaModelsFilename } from './models'
+
+export interface ModelsCliOutput {
+  writeStdout: (value: string) => void
+}
+
+export class ModelsCliError extends Error {
+  constructor(message: string) {
+    super(message)
+    this.name = 'ModelsCliError'
+  }
+}
+
+const usage = `Usage: tanstack-ai-prisma-models (--out <directory> | --stdout) [--force]
+
+Options:
+  --out <directory>  Copy the models-only Prisma schema fragment.
+  --stdout           Print the models-only Prisma schema fragment.
+  --force            Replace a divergent fragment when copying.
+  --help             Show this help.
+`
+
+interface ParsedArguments {
+  force: boolean
+  help: boolean
+  outDirectory?: string
+  stdout: boolean
+}
+
+function parseArguments(args: ReadonlyArray<string>): ParsedArguments {
+  let force = false
+  let help = false
+  let outDirectory: string | undefined
+  let stdout = false
+
+  for (let index = 0; index < args.length; index++) {
+    const argument = args[index]
+    if (argument === '--force') {
+      force = true
+    } else if (argument === '--help' || argument === '-h') {
+      help = true
+    } else if (argument === '--stdout') {
+      stdout = true
+    } else if (argument === '--out') {
+      const value = args[index + 1]
+      if (!value || value.startsWith('-')) {
+        throw new ModelsCliError('--out requires a directory.')
+      }
+      if (outDirectory !== undefined) {
+        throw new ModelsCliError('--out may only be provided once.')
+      }
+      outDirectory = value
+      index++
+    } else {
+      throw new ModelsCliError(`Unknown argument: ${argument ?? ''}`)
+    }
+  }
+
+  return { force, help, outDirectory, stdout }
+}
+
+function isMissingFileError(error: unknown): boolean {
+  return error instanceof Error && 'code' in error && error.code === 'ENOENT'
+}
+
+async function readExistingFile(path: string): Promise<string | undefined> {
+  try {
+    return await readFile(path, 'utf8')
+  } catch (error) {
+    if (isMissingFileError(error)) return undefined
+    throw error
+  }
+}
+
+/** Execute the models asset CLI. Exported for deterministic CLI tests. */
+export async function runPrismaModelsCli(
+  args: ReadonlyArray<string>,
+  output: ModelsCliOutput = {
+    writeStdout(value) {
+      process.stdout.write(value)
+    },
+  },
+): Promise<void> {
+  const parsed = parseArguments(args)
+  if (parsed.help) {
+    output.writeStdout(usage)
+    return
+  }
+
+  const outputCount =
+    Number(parsed.stdout) + Number(parsed.outDirectory != null)
+  if (outputCount !== 1) {
+    throw new ModelsCliError(
+      'Provide exactly one output mode: --out <directory> or --stdout.',
+    )
+  }
+  if (parsed.stdout) {
+    if (parsed.force) {
+      throw new ModelsCliError('--force can only be used with --out.')
+    }
+    output.writeStdout(`${prismaModels.trimEnd()}\n`)
+    return
+  }
+
+  const outDirectory = parsed.outDirectory
+  if (!outDirectory) {
+    throw new ModelsCliError('--out requires a directory.')
+  }
+  await mkdir(outDirectory, { recursive: true })
+  const destination = join(outDirectory, prismaModelsFilename)
+  const existing = await readExistingFile(destination)
+  if (existing === prismaModels) return
+  if (existing !== undefined && !parsed.force) {
+    throw new ModelsCliError(
+      `Refusing to overwrite divergent Prisma models file: ${destination}. Re-run with --force to replace it.`,
+    )
+  }
+  await writeFile(destination, prismaModels, 'utf8')
+}
diff --git a/packages/ai-persistence-prisma/src/models.ts b/packages/ai-persistence-prisma/src/models.ts
new file mode 100644
index 000000000..6e22bb77b
--- /dev/null
+++ b/packages/ai-persistence-prisma/src/models.ts
@@ -0,0 +1,7 @@
+import models from './assets/tanstack-ai.prisma?raw'
+
+/** Filename used by the Prisma models copy CLI. */
+export const prismaModelsFilename = 'tanstack-ai.prisma'
+
+/** Provider-neutral, models-only Prisma schema fragment. */
+export const prismaModels: string = models
diff --git a/packages/ai-persistence-prisma/src/stores.ts b/packages/ai-persistence-prisma/src/stores.ts
new file mode 100644
index 000000000..0089ae0eb
--- /dev/null
+++ b/packages/ai-persistence-prisma/src/stores.ts
@@ -0,0 +1,237 @@
+/**
+ * AIPersistence store implementations over a Prisma `PrismaClient`.
+ *
+ * Each method mirrors the reference in-memory backend
+ * (`@tanstack/ai-persistence`'s `memory.ts`) and the sibling Drizzle backend
+ * (`@tanstack/ai-persistence-drizzle`'s `stores.ts`), including the
+ * insert-if-absent `InterruptStore.create` and `RunStore.createOrResume`
+ * semantics (`upsert` with an empty `update`). JSON-valued columns use
+ * provider-neutral Prisma `String` fields, so they are serialized with
+ * `JSON.stringify`/`JSON.parse` here.
+ */
+import type {
+  InterruptRow,
+  RunRow,
+  TanstackAiDelegates,
+} from './model-contract'
+import type { ModelMessage } from '@tanstack/ai'
+import type {
+  InterruptRecord,
+  InterruptStore,
+  MessageStore,
+  MetadataStore,
+  RunRecord,
+  RunStatus,
+  RunStore,
+} from '@tanstack/ai-persistence'
+
+export function createMessageStore({
+  message,
+}: TanstackAiDelegates): MessageStore {
+  return {
+    async loadThread(threadId) {
+      const row = await 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 message.upsert({
+        where: { threadId },
+        create: { threadId, messagesJson },
+        update: { messagesJson },
+      })
+    },
+  }
+}
+
+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({ run }: TanstackAiDelegates): 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 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 run.updateMany({ where: { runId }, data })
+    },
+    async get(runId) {
+      const row = await run.findUnique({ where: { runId } })
+      return row ? mapRun(row) : null
+    },
+  }
+  return store
+}
+
+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({
+  interrupt,
+}: TanstackAiDelegates): InterruptStore {
+  return {
+    async create(record) {
+      await interrupt.upsert({
+        where: { interruptId: record.interruptId },
+        create: {
+          interruptId: record.interruptId,
+          runId: record.runId,
+          threadId: record.threadId,
+          status: 'pending',
+          requestedAt: BigInt(record.requestedAt),
+          payloadJson: JSON.stringify(record.payload),
+          responseJson:
+            record.response == null ? null : JSON.stringify(record.response),
+        },
+        update: {},
+      })
+    },
+    async resolve(interruptId, response) {
+      await interrupt.updateMany({
+        where: { interruptId },
+        data: {
+          status: 'resolved',
+          resolvedAt: BigInt(Date.now()),
+          responseJson: response == null ? null : JSON.stringify(response),
+        },
+      })
+    },
+    async cancel(interruptId) {
+      await interrupt.updateMany({
+        where: { interruptId },
+        data: { status: 'cancelled', resolvedAt: BigInt(Date.now()) },
+      })
+    },
+    async get(interruptId) {
+      const row = await interrupt.findUnique({ where: { interruptId } })
+      return row ? mapInterrupt(row) : null
+    },
+    async list(threadId) {
+      const rows = await interrupt.findMany({
+        where: { threadId },
+        orderBy: { requestedAt: 'asc' },
+      })
+      return rows.map(mapInterrupt)
+    },
+    async listPending(threadId) {
+      const rows = await interrupt.findMany({
+        where: { threadId, status: 'pending' },
+        orderBy: { requestedAt: 'asc' },
+      })
+      return rows.map(mapInterrupt)
+    },
+    async listByRun(runId) {
+      const rows = await interrupt.findMany({
+        where: { runId },
+        orderBy: { requestedAt: 'asc' },
+      })
+      return rows.map(mapInterrupt)
+    },
+    async listPendingByRun(runId) {
+      const rows = await interrupt.findMany({
+        where: { runId, status: 'pending' },
+        orderBy: { requestedAt: 'asc' },
+      })
+      return rows.map(mapInterrupt)
+    },
+  }
+}
+
+function assertStorableMetadata(value: unknown): void {
+  if (value == null) {
+    throw new TypeError(
+      `TanStack AI metadata values must be defined, non-null JSON; received ${
+        value === undefined ? '`undefined`' : '`null`'
+      }. Use \`delete(scope, key)\` to clear a value.`,
+    )
+  }
+}
+
+export function createMetadataStore({
+  metadata,
+}: TanstackAiDelegates): MetadataStore {
+  return {
+    async get(scope, key) {
+      const row = await metadata.findUnique({
+        where: { scope_key: { scope, key } },
+      })
+      return row ? (JSON.parse(row.valueJson) as unknown) : null
+    },
+    async set(scope, key, value) {
+      // SQL backends store JSON text in a NOT NULL column and cannot persist a
+      // nullish value: `JSON.stringify(undefined)` is `undefined` (no string),
+      // and the sibling Drizzle backend binds a JS `null` as SQL NULL — both
+      // violate NOT NULL. Reject nullish with a clear error (consistent across
+      // the SQL backends) instead of a cryptic driver failure. Unlike the
+      // in-memory reference, which round-trips nullish; use `delete` to clear.
+      assertStorableMetadata(value)
+      const valueJson = JSON.stringify(value)
+      await metadata.upsert({
+        where: { scope_key: { scope, key } },
+        create: { scope, key, valueJson },
+        update: { valueJson },
+      })
+    },
+    async delete(scope, key) {
+      await metadata.deleteMany({ where: { scope, key } })
+    },
+  }
+}
diff --git a/packages/ai-persistence-prisma/tests/api-types.test-d.ts b/packages/ai-persistence-prisma/tests/api-types.test-d.ts
new file mode 100644
index 000000000..67e4fc687
--- /dev/null
+++ b/packages/ai-persistence-prisma/tests/api-types.test-d.ts
@@ -0,0 +1,38 @@
+import { expectTypeOf } from 'vitest'
+import { PrismaClient } from '@prisma/client'
+import type {
+  InterruptStore,
+  MessageStore,
+  MetadataStore,
+  RunStore,
+} from '@tanstack/ai-persistence'
+import { prismaPersistence } from '../src/index'
+import type {
+  InterruptDelegate,
+  MessageDelegate,
+  MetadataDelegate,
+  RunDelegate,
+} from '../src/model-contract'
+
+declare const prisma: PrismaClient
+const persistence = prismaPersistence(prisma)
+
+// The generated client's delegates must satisfy the structural delegate
+// contract the stores are written against — this is what makes renamed
+// delegates from a user-generated client interchangeable with canonical ones.
+expectTypeOf(prisma.message).toExtend<MessageDelegate>()
+expectTypeOf(prisma.run).toExtend<RunDelegate>()
+expectTypeOf(prisma.interrupt).toExtend<InterruptDelegate>()
+expectTypeOf(prisma.metadata).toExtend<MetadataDelegate>()
+
+const mapped = prismaPersistence(prisma, {
+  models: { messages: 'chatMessage' },
+})
+expectTypeOf(mapped.stores).toEqualTypeOf<typeof persistence.stores>()
+
+expectTypeOf(persistence.stores.messages).toEqualTypeOf<MessageStore>()
+expectTypeOf(persistence.stores.runs).toEqualTypeOf<RunStore>()
+expectTypeOf(persistence.stores.interrupts).toEqualTypeOf<InterruptStore>()
+expectTypeOf(persistence.stores.metadata).toEqualTypeOf<MetadataStore>()
+// No `locks` store: this backend has no distributed lock (see prismaPersistence).
+expectTypeOf(persistence.stores).not.toHaveProperty('locks')
diff --git a/packages/ai-persistence-prisma/tests/model-mapping.test.ts b/packages/ai-persistence-prisma/tests/model-mapping.test.ts
new file mode 100644
index 000000000..573243251
--- /dev/null
+++ b/packages/ai-persistence-prisma/tests/model-mapping.test.ts
@@ -0,0 +1,137 @@
+import { rm } from 'node:fs/promises'
+import { mkdtempSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { DatabaseSync } from 'node:sqlite'
+import { afterAll, describe, expect, it } from 'vitest'
+import { PrismaClient } from '@prisma/client'
+import { runPersistenceConformance } from '@tanstack/ai-persistence/testkit'
+import { PrismaModelError, prismaPersistence } from '../src/index'
+
+const clients: Array<PrismaClient> = []
+const temporaryDirectories: Array<string> = []
+
+const sqliteTestSchema = `
+  CREATE TABLE messages (
+    thread_id TEXT NOT NULL PRIMARY KEY,
+    messages_json TEXT NOT NULL
+  );
+  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
+  );
+  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
+  );
+  CREATE TABLE metadata (
+    scope TEXT NOT NULL,
+    key TEXT NOT NULL,
+    value_json TEXT NOT NULL,
+    PRIMARY KEY (scope, key)
+  );
+`
+
+async function makeTestClient(): Promise<PrismaClient> {
+  const dir = mkdtempSync(join(tmpdir(), 'tanstack-ai-prisma-mapping-'))
+  temporaryDirectories.push(dir)
+  const dbPath = join(dir, 'state.db').replace(/\\/g, '/')
+  const database = new DatabaseSync(dbPath)
+  try {
+    database.exec(sqliteTestSchema)
+  } finally {
+    database.close()
+  }
+  const prisma = new PrismaClient({
+    datasources: { db: { url: `file:${dbPath}` } },
+  })
+  clients.push(prisma)
+  return prisma
+}
+
+/**
+ * A client whose TanStack AI model delegates live under renamed accessors, as
+ * generated from a fragment whose models were renamed to avoid collisions
+ * (e.g. `model ChatMessage`). Aliasing the canonical delegates is faithful:
+ * a delegate is bound to its model, not to the property it hangs off.
+ */
+async function makeRenamedClient(): Promise<PrismaClient> {
+  const prisma = await makeTestClient()
+  const renamed = {
+    chatMessage: prisma.message,
+    chatRun: prisma.run,
+    chatInterrupt: prisma.interrupt,
+    chatMetadata: prisma.metadata,
+  }
+  return renamed as unknown as PrismaClient
+}
+
+const renamedModels = {
+  messages: 'chatMessage',
+  runs: 'chatRun',
+  interrupts: 'chatInterrupt',
+  metadata: 'chatMetadata',
+}
+
+afterAll(async () => {
+  await Promise.all(clients.map((client) => client.$disconnect()))
+  await Promise.all(
+    temporaryDirectories.map((directory) =>
+      rm(directory, { recursive: true, force: true }),
+    ),
+  )
+})
+
+// The full store contract must hold when every model is reached through a
+// renamed delegate.
+runPersistenceConformance(
+  'prisma (renamed models)',
+  async () =>
+    prismaPersistence(await makeRenamedClient(), { models: renamedModels }),
+  // This backend has no distributed lock primitive.
+  { skip: ['locks'] },
+)
+
+describe('prismaPersistence model mapping', () => {
+  it('rejects a mapping that points at missing delegates', async () => {
+    const prisma = await makeTestClient()
+    expect(() =>
+      prismaPersistence(prisma, { models: { messages: 'chatMessage' } }),
+    ).toThrow(PrismaModelError)
+    expect(() =>
+      prismaPersistence(prisma, { models: { messages: 'chatMessage' } }),
+    ).toThrow(/`messages` maps to `client\.chatMessage`/)
+  })
+
+  it('lists every unresolved model in one error', async () => {
+    const prisma = await makeRenamedClient()
+    // Default names resolve nothing on a fully renamed client.
+    expect(() => prismaPersistence(prisma)).toThrow(
+      /messages[\s\S]*runs[\s\S]*interrupts[\s\S]*metadata/,
+    )
+  })
+
+  it('supports partial maps over an otherwise canonical client', async () => {
+    const prisma = await makeTestClient()
+    const persistence = prismaPersistence(prisma, {
+      models: { messages: 'message' },
+    })
+    await persistence.stores.messages.saveThread('thread-1', [
+      { role: 'user', content: 'hello' },
+    ])
+    expect(
+      await persistence.stores.messages.loadThread('thread-1'),
+    ).toHaveLength(1)
+  })
+})
diff --git a/packages/ai-persistence-prisma/tests/models-cli.test.ts b/packages/ai-persistence-prisma/tests/models-cli.test.ts
new file mode 100644
index 000000000..36a997568
--- /dev/null
+++ b/packages/ai-persistence-prisma/tests/models-cli.test.ts
@@ -0,0 +1,59 @@
+import { mkdtemp, readFile, rm, writeFile } from 'node:fs/promises'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { afterEach, describe, expect, it } from 'vitest'
+import { prismaModels, prismaModelsFilename } from '../src/index'
+import { runPrismaModelsCli } from '../src/models-cli'
+
+const temporaryDirectories: Array<string> = []
+
+async function createTemporaryDirectory(): Promise<string> {
+  const directory = await mkdtemp(join(tmpdir(), 'tanstack-ai-prisma-cli-'))
+  temporaryDirectories.push(directory)
+  return directory
+}
+
+afterEach(async () => {
+  await Promise.all(
+    temporaryDirectories
+      .splice(0)
+      .map((directory) => rm(directory, { recursive: true, force: true })),
+  )
+})
+
+describe('Prisma models CLI', () => {
+  it('prints the models fragment to stdout', async () => {
+    let output = ''
+    await runPrismaModelsCli(['--stdout'], {
+      writeStdout(value) {
+        output += value
+      },
+    })
+    expect(output).toBe(`${prismaModels.trimEnd()}\n`)
+  })
+
+  it('copies the fragment without overwriting divergent files by default', async () => {
+    const directory = await createTemporaryDirectory()
+    await runPrismaModelsCli(['--out', directory])
+
+    const destination = join(directory, prismaModelsFilename)
+    expect(await readFile(destination, 'utf8')).toBe(prismaModels)
+
+    await writeFile(destination, 'user-owned contents', 'utf8')
+    await expect(runPrismaModelsCli(['--out', directory])).rejects.toThrow(
+      /refusing to overwrite/i,
+    )
+    expect(await readFile(destination, 'utf8')).toBe('user-owned contents')
+
+    await runPrismaModelsCli(['--out', directory, '--force'])
+    expect(await readFile(destination, 'utf8')).toBe(prismaModels)
+  })
+
+  it('fails on ambiguous or incomplete output options', async () => {
+    const directory = await createTemporaryDirectory()
+    await expect(runPrismaModelsCli([])).rejects.toThrow(/--out.*--stdout/i)
+    await expect(
+      runPrismaModelsCli(['--stdout', '--out', directory]),
+    ).rejects.toThrow(/exactly one/i)
+  })
+})
diff --git a/packages/ai-persistence-prisma/tests/models.test.ts b/packages/ai-persistence-prisma/tests/models.test.ts
new file mode 100644
index 000000000..5711faaeb
--- /dev/null
+++ b/packages/ai-persistence-prisma/tests/models.test.ts
@@ -0,0 +1,66 @@
+import { execFileSync } from 'node:child_process'
+import { mkdtemp, readFile, rm, writeFile } from 'node:fs/promises'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { afterEach, describe, expect, it } from 'vitest'
+import { prismaModels, prismaModelsFilename } from '../src/index'
+
+const temporaryDirectories: Array<string> = []
+const prismaCli = fileURLToPath(
+  new URL('../node_modules/prisma/build/index.js', import.meta.url),
+)
+
+async function createTemporaryDirectory(): Promise<string> {
+  const directory = await mkdtemp(join(tmpdir(), 'tanstack-ai-prisma-models-'))
+  temporaryDirectories.push(directory)
+  return directory
+}
+
+afterEach(async () => {
+  await Promise.all(
+    temporaryDirectories
+      .splice(0)
+      .map((directory) => rm(directory, { recursive: true, force: true })),
+  )
+})
+
+describe('Prisma models asset', () => {
+  it('is a models-only fragment with no provider or client generator', () => {
+    expect(prismaModelsFilename).toBe('tanstack-ai.prisma')
+    expect(prismaModels).toContain('model Message')
+    expect(prismaModels).toContain('model Metadata')
+    expect(prismaModels).not.toMatch(/\bgenerator\s+\w+\s*{/)
+    expect(prismaModels).not.toMatch(/\bdatasource\s+\w+\s*{/)
+  })
+
+  it('keeps the shipped models file equal to the embedded asset', async () => {
+    const shipped = await readFile(
+      fileURLToPath(new URL('../prisma/tanstack-ai.prisma', import.meta.url)),
+      'utf8',
+    )
+    expect(shipped).toBe(prismaModels)
+  })
+
+  it.each([
+    ['sqlite', 'file:./state.db'],
+    ['postgresql', 'postgresql://user:password@localhost:5432/database'],
+    ['mysql', 'mysql://user:password@localhost:3306/database'],
+  ])('validates when composed into a %s schema', async (provider, url) => {
+    const directory = await createTemporaryDirectory()
+    const schemaPath = join(directory, 'schema.prisma')
+    await writeFile(
+      schemaPath,
+      `datasource db {\n  provider = "${provider}"\n  url = "${url}"\n}\n\n${prismaModels}`,
+      'utf8',
+    )
+
+    expect(() =>
+      execFileSync(
+        process.execPath,
+        [prismaCli, 'validate', '--schema', schemaPath],
+        { encoding: 'utf8', stdio: 'pipe' },
+      ),
+    ).not.toThrow()
+  })
+})
diff --git a/packages/ai-persistence-prisma/tests/package-contract.test.ts b/packages/ai-persistence-prisma/tests/package-contract.test.ts
new file mode 100644
index 000000000..a823747df
--- /dev/null
+++ b/packages/ai-persistence-prisma/tests/package-contract.test.ts
@@ -0,0 +1,28 @@
+import { describe, expect, it } from 'vitest'
+import packageJson from '../package.json'
+
+describe('Prisma package contract', () => {
+  it('publishes the adapter, models CLI, and provider-neutral models asset', () => {
+    expect(packageJson.exports).toEqual({
+      '.': {
+        types: './dist/esm/index.d.ts',
+        import: './dist/esm/index.js',
+      },
+    })
+    expect(packageJson.bin).toEqual({
+      'tanstack-ai-prisma-models': './bin/tanstack-ai-prisma-models.mjs',
+    })
+    expect(packageJson.files).toEqual(
+      expect.arrayContaining([
+        'bin',
+        'dist',
+        'src',
+        'prisma/tanstack-ai.prisma',
+      ]),
+    )
+  })
+
+  it('requires a Prisma client with generally available multi-file schemas', () => {
+    expect(packageJson.peerDependencies['@prisma/client']).toBe('>=6.7.0')
+  })
+})
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..69c029199
--- /dev/null
+++ b/packages/ai-persistence-prisma/tests/prisma.conformance.test.ts
@@ -0,0 +1,82 @@
+import { rm } from 'node:fs/promises'
+import { mkdtempSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { DatabaseSync } from 'node:sqlite'
+import { afterAll } from 'vitest'
+import { PrismaClient } from '@prisma/client'
+import { runPersistenceConformance } from '@tanstack/ai-persistence/testkit'
+import { prismaPersistence } from '../src/index'
+
+const clients: Array<PrismaClient> = []
+const temporaryDirectories: Array<string> = []
+
+const sqliteTestSchema = `
+  CREATE TABLE messages (
+    thread_id TEXT NOT NULL PRIMARY KEY,
+    messages_json TEXT NOT NULL
+  );
+  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
+  );
+  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
+  );
+  CREATE TABLE metadata (
+    scope TEXT NOT NULL,
+    key TEXT NOT NULL,
+    value_json TEXT NOT NULL,
+    PRIMARY KEY (scope, key)
+  );
+`
+
+function initializeSqliteTestDatabase(path: string): void {
+  const database = new DatabaseSync(path)
+  try {
+    database.exec(sqliteTestSchema)
+  } finally {
+    database.close()
+  }
+}
+
+/** Create a PrismaClient over a fresh initialized temporary SQLite database. */
+async function makeTestClient(): Promise<PrismaClient> {
+  const dir = mkdtempSync(join(tmpdir(), 'tanstack-ai-prisma-'))
+  temporaryDirectories.push(dir)
+  const dbPath = join(dir, 'state.db').replace(/\\/g, '/')
+  initializeSqliteTestDatabase(dbPath)
+  const prisma = new PrismaClient({
+    datasources: { db: { url: `file:${dbPath}` } },
+  })
+  clients.push(prisma)
+  return prisma
+}
+
+afterAll(async () => {
+  await Promise.all(clients.map((client) => client.$disconnect()))
+  await Promise.all(
+    temporaryDirectories.map((directory) =>
+      rm(directory, { recursive: true, force: true }),
+    ),
+  )
+})
+
+runPersistenceConformance(
+  'prisma',
+  async () => prismaPersistence(await makeTestClient()),
+  // This backend has no distributed lock primitive.
+  { skip: ['locks'] },
+)
diff --git a/packages/ai-persistence-prisma/tests/store-behavior.test.ts b/packages/ai-persistence-prisma/tests/store-behavior.test.ts
new file mode 100644
index 000000000..f1b862b74
--- /dev/null
+++ b/packages/ai-persistence-prisma/tests/store-behavior.test.ts
@@ -0,0 +1,72 @@
+import { rm } from 'node:fs/promises'
+import { mkdtempSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { DatabaseSync } from 'node:sqlite'
+import { afterAll, describe, expect, it } from 'vitest'
+import { PrismaClient } from '@prisma/client'
+import { prismaPersistence } from '../src/index'
+
+const clients: Array<PrismaClient> = []
+const directories: Array<string> = []
+
+// Only the tables these tests query need to exist; the generated client carries
+// all delegates regardless of which tables the database has.
+const schema = `
+  CREATE TABLE metadata (
+    scope TEXT NOT NULL,
+    key TEXT NOT NULL,
+    value_json TEXT NOT NULL,
+    PRIMARY KEY (scope, key)
+  );
+`
+
+function makePersistence(): ReturnType<typeof prismaPersistence> {
+  const dir = mkdtempSync(join(tmpdir(), 'tanstack-ai-prisma-behavior-'))
+  directories.push(dir)
+  const dbPath = join(dir, 'state.db').replace(/\\/g, '/')
+  const database = new DatabaseSync(dbPath)
+  try {
+    database.exec(schema)
+  } finally {
+    database.close()
+  }
+  const prisma = new PrismaClient({
+    datasources: { db: { url: `file:${dbPath}` } },
+  })
+  clients.push(prisma)
+  return prismaPersistence(prisma)
+}
+
+afterAll(async () => {
+  await Promise.all(clients.map((client) => client.$disconnect()))
+  await Promise.all(
+    directories.map((directory) =>
+      rm(directory, { recursive: true, force: true }),
+    ),
+  )
+})
+
+describe('prisma metadata nullish values', () => {
+  it('rejects nullish values with a clear error instead of a NOT NULL crash', async () => {
+    const { stores } = makePersistence()
+
+    // A NOT NULL column cannot store nullish; surface a clear, actionable error
+    // (consistent with the Drizzle backend) rather than a driver crash.
+    await expect(stores.metadata.set('scope', 'u', undefined)).rejects.toThrow(
+      /metadata values must be defined/,
+    )
+    await expect(stores.metadata.set('scope', 'n', null)).rejects.toThrow(
+      /metadata values must be defined/,
+    )
+    expect(await stores.metadata.get('scope', 'u')).toBeNull()
+
+    // Falsy-but-defined values are stored and round-trip.
+    await stores.metadata.set('scope', 'zero', 0)
+    expect(await stores.metadata.get('scope', 'zero')).toBe(0)
+    await stores.metadata.set('scope', 'empty', '')
+    expect(await stores.metadata.get('scope', 'empty')).toBe('')
+    await stores.metadata.set('scope', 'obj', { a: 1 })
+    expect(await stores.metadata.get('scope', 'obj')).toEqual({ a: 1 })
+  })
+})
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..f56314fed
--- /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', './src/cli.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..152652b50
--- /dev/null
+++ b/packages/ai-persistence/package.json
@@ -0,0 +1,63 @@
+{
+  "name": "@tanstack/ai-persistence",
+  "version": "0.0.0",
+  "description": "Composable state persistence for TanStack AI messages, runs, interrupts, metadata, and locks.",
+  "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",
+    "chat-history"
+  ],
+  "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"
+  },
+  "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..2f38ec96c
--- /dev/null
+++ b/packages/ai-persistence/src/capabilities.ts
@@ -0,0 +1,24 @@
+/**
+ * Persistence capability tokens.
+ *
+ * `withChatPersistence` PROVIDES these so later middleware (and harness adapters)
+ * can read durable state. `LocksCapability` is re-exported from core
+ * (`@tanstack/ai`): the `'locks'` token lives in core so there is exactly one of
+ * it, shared by both the sandbox and persistence layers — neither layer owns it.
+ */
+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..b2d24e3b4
--- /dev/null
+++ b/packages/ai-persistence/src/index.ts
@@ -0,0 +1,39 @@
+// Store contracts + aggregate
+export { composePersistence, defineAIPersistence } from './types'
+export type {
+  MessageStore,
+  RunStatus,
+  RunRecord,
+  RunStore,
+  InterruptRecord,
+  InterruptStatus,
+  InterruptStore,
+  MetadataStore,
+  AIPersistence,
+  AIPersistenceStores,
+  AIPersistenceOverrides,
+  ComposedAIPersistenceStores,
+} from './types'
+
+// Middleware
+export { withChatPersistence, withGenerationPersistence } from './middleware'
+
+// 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..f8cc1d329
--- /dev/null
+++ b/packages/ai-persistence/src/interrupts.ts
@@ -0,0 +1,24 @@
+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),
+    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..ea070cecb
--- /dev/null
+++ b/packages/ai-persistence/src/memory.ts
@@ -0,0 +1,164 @@
+import { InMemoryLockStore } from '@tanstack/ai'
+import { defineAIPersistence } from './types'
+import type { LockStore, ModelMessage } from '@tanstack/ai'
+import type {
+  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, 'status' | 'resolvedAt'>,
+  ): Promise<void> {
+    // Insert-if-absent (canonical semantics, matching the SQL backends'
+    // ON CONFLICT DO NOTHING): a duplicate id must never clobber an existing —
+    // possibly already resolved — interrupt back to pending.
+    if (!this.interrupts.has(record.interruptId)) {
+      this.interrupts.set(record.interruptId, { ...record, status: 'pending' })
+    }
+    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()
+  }
+}
+
+interface MemoryPersistenceStores {
+  messages: MessageStore
+  runs: RunStore
+  interrupts: InterruptStore
+  metadata: MetadataStore
+  locks: LockStore
+}
+
+export function memoryPersistence() {
+  const stores: MemoryPersistenceStores = {
+    messages: new MemoryMessageStore(),
+    runs: new MemoryRunStore(),
+    interrupts: new MemoryInterruptStore(),
+    metadata: new MemoryMetadataStore(),
+    locks: new InMemoryLockStore(),
+  }
+  return defineAIPersistence({ stores })
+}
diff --git a/packages/ai-persistence/src/middleware.ts b/packages/ai-persistence/src/middleware.ts
new file mode 100644
index 000000000..38860abce
--- /dev/null
+++ b/packages/ai-persistence/src/middleware.ts
@@ -0,0 +1,502 @@
+import { defineChatMiddleware } from '@tanstack/ai'
+import {
+  InterruptsCapability,
+  LocksCapability,
+  PersistenceCapability,
+  provideInterrupts,
+  provideLocks,
+  providePersistence,
+} from './capabilities'
+import {
+  validateChatPersistenceStores,
+  validatePersistenceStoreKeys,
+} from './types'
+import type {
+  AbortInfo,
+  ChatMiddleware,
+  ChatMiddlewareConfig,
+  ChatMiddlewareContext,
+  ChatResumeToolState,
+  ErrorInfo,
+  FinishInfo,
+  GenerationAbortInfo,
+  GenerationErrorInfo,
+  GenerationFinishInfo,
+  GenerationMiddleware,
+  GenerationMiddlewareContext,
+  RunAgentResumeItem,
+  StreamChunk,
+  TokenUsage,
+} from '@tanstack/ai'
+import type {
+  AIPersistence,
+  AIPersistenceStores,
+  InterruptRecord,
+  RunStore,
+} from './types'
+
+interface RunStateEntry {
+  merged: boolean
+  interrupted: boolean
+  /**
+   * Resumes accepted in `onConfig` but not yet committed to the interrupt
+   * store. They are applied (resolve/cancel) only once the run reaches a
+   * successful boundary — see {@link commitPendingResumes}. Left uncommitted
+   * (still pending in the store) if the run fails or aborts first.
+   */
+  pendingResumes?: {
+    pending: Array<InterruptRecord>
+    resumeByInterruptId: Map<string, RunAgentResumeItem>
+  }
+}
+
+const runState = new WeakMap<object, RunStateEntry>()
+
+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)
+    }
+  }
+}
+
+/**
+ * Commit the resumes stashed in `onConfig`, marking each resumed interrupt
+ * resolved/cancelled. Called only from success boundaries (`onFinish`, and the
+ * `onChunk` interrupt boundary) so a provider failure or abort between accepting
+ * the resume and reaching a boundary leaves the interrupts pending — the
+ * approval is not consumed and a retry with the same resume succeeds. Idempotent
+ * and a no-op when nothing is stashed.
+ */
+async function commitPendingResumes(
+  state: RunStateEntry | undefined,
+  interrupts: AIPersistence['stores']['interrupts'],
+): Promise<void> {
+  if (!state?.pendingResumes || !interrupts) return
+  const { pending, resumeByInterruptId } = state.pendingResumes
+  state.pendingResumes = undefined
+  await applyPendingResumes(pending, resumeByInterruptId, interrupts)
+}
+
+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)
+  // Fail closed: persisted resume payloads may be malformed or truncated, so a
+  // missing/non-boolean `approved` denies the tool rather than running it.
+  return typeof payload?.approved === 'boolean' ? payload.approved : false
+}
+
+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 }
+}
+
+// ---------------------------------------------------------------------------
+// Shared store / feature plan
+// ---------------------------------------------------------------------------
+
+interface PersistencePlan {
+  wantsMessages: boolean
+  wantsInterrupts: boolean
+  wantsLocks: boolean
+  runs: AIPersistence['stores']['runs']
+}
+
+function resolvePersistencePlan(persistence: AIPersistence): PersistencePlan {
+  return {
+    wantsMessages: persistence.stores.messages !== undefined,
+    wantsInterrupts: persistence.stores.interrupts !== undefined,
+    wantsLocks: persistence.stores.locks !== undefined,
+    runs: persistence.stores.runs,
+  }
+}
+
+type StoreIsDefinitelyPresent<
+  TStores extends AIPersistenceStores,
+  TKey extends keyof AIPersistenceStores,
+> = TKey extends keyof TStores
+  ? object extends Pick<TStores, TKey>
+    ? false
+    : [Exclude<TStores[TKey], undefined>] extends [never]
+      ? false
+      : true
+  : false
+
+type StoreIsDefinitelyAbsent<
+  TStores extends AIPersistenceStores,
+  TKey extends keyof AIPersistenceStores,
+> = TKey extends keyof TStores
+  ? [Exclude<TStores[TKey], undefined>] extends [never]
+    ? true
+    : false
+  : true
+
+type InvalidChatPersistence<TStores extends AIPersistenceStores> =
+  StoreIsDefinitelyPresent<TStores, 'interrupts'> extends true
+    ? StoreIsDefinitelyAbsent<TStores, 'runs'>
+    : false
+
+type ValidChatPersistence<TStores extends AIPersistenceStores> =
+  InvalidChatPersistence<TStores> extends true ? never : unknown
+
+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. This middleware never
+ * mutates the chunk stream; delivery durability (replaying a
+ * disconnected/reloaded stream) is a separate transport-layer concern tracked
+ * in PR #955.
+ *
+ * ⚠️ AUTHORITATIVE-HISTORY CONTRACT: when a request carries a non-empty
+ * `messages` array it is treated as the FULL conversation history and, on
+ * finish, **overwrites** the entire stored thread. Post only the complete
+ * transcript, never a delta — sending just the newest message(s) will replace
+ * (and thereby destroy) the stored thread. To continue a stored thread without
+ * resending history, pass an empty `messages` array and the stored transcript
+ * is loaded and used.
+ */
+export function withChatPersistence<TStores extends AIPersistenceStores>(
+  persistence: AIPersistence<TStores> & ValidChatPersistence<TStores>,
+): ChatMiddleware
+export function withChatPersistence(
+  persistence: AIPersistence,
+): ChatMiddleware {
+  validateChatPersistenceStores(persistence)
+  const plan = resolvePersistencePlan(persistence)
+  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,
+        )
+        // Defer marking these interrupts resolved/cancelled until the run
+        // succeeds (see commitPendingResumes). Committing here would consume the
+        // approval even if the run then failed, breaking a retry.
+        const state = runState.get(ctx)
+        if (state && pending.length > 0) {
+          state.pendingResumes = { pending, resumeByInterruptId }
+        }
+      }
+
+      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) {
+        // The run reached a new interrupt boundary, so the resumes it consumed
+        // are committed before the fresh interrupts are recorded.
+        await commitPendingResumes(state, persistence.stores.interrupts)
+        for (const interrupt of chunk.outcome.interrupts) {
+          await persistence.stores.interrupts.create({
+            interruptId: interrupt.id,
+            runId: ctx.runId,
+            threadId: ctx.threadId,
+            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) {
+      const state = runState.get(ctx)
+      if (state?.interrupted) return
+      // The run completed successfully, so commit the resumes it consumed.
+      await commitPendingResumes(state, persistence.stores.interrupts)
+      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 (run records) for
+ * image, audio, TTS, video, and transcription activities.
+ */
+export function withGenerationPersistence<TStores extends AIPersistenceStores>(
+  persistence: AIPersistence<TStores>,
+): GenerationMiddleware
+export function withGenerationPersistence(
+  persistence: AIPersistence,
+): GenerationMiddleware {
+  validatePersistenceStoreKeys(persistence)
+  const { runs } = resolvePersistencePlan(persistence)
+
+  return {
+    name: 'generation-persistence',
+
+    async onStart(ctx: GenerationMiddlewareContext) {
+      await createOrResumeRun(
+        runs,
+        ctx.runId ?? ctx.requestId,
+        ctx.threadId ?? ctx.requestId,
+      )
+    },
+
+    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..fd24a7c58
--- /dev/null
+++ b/packages/ai-persistence/src/testkit/conformance.ts
@@ -0,0 +1,379 @@
+/**
+ * Shared conformance suite for the `AIPersistence` state contract.
+ *
+ * Every backend (memory, drizzle, prisma, cloudflare, …) runs this identical
+ * suite so that schema drift or an implementation gap fails immediately. It
+ * exercises every method of every store the persistence exposes and is the
+ * authoritative compatibility gate for the store interfaces in `../types.ts`.
+ *
+ * SKIPPING: a backend that deliberately omits a store (e.g. drizzle has no
+ * `locks`) must declare it in `options.skip`. A store that is absent AND not
+ * listed in `skip` fails the suite loudly — silent gaps are not allowed.
+ */
+import { beforeAll, describe, expect, it } from 'vitest'
+import type { ModelMessage } from '@tanstack/ai'
+import type { AIPersistence, AIPersistenceStores } from '../types'
+
+type MakePersistence = () => Promise<AIPersistence> | AIPersistence
+
+export interface PersistenceConformanceOptions {
+  /**
+   * Store keys this backend intentionally does not provide. Any store that is
+   * absent from the persistence and NOT listed here fails the suite, so a
+   * dropped/misconfigured store can never pass silently.
+   */
+  skip?: Array<keyof AIPersistenceStores>
+}
+
+/**
+ * Register a Vitest suite that validates `makePersistence()` against the full
+ * `AIPersistence` contract.
+ */
+export function runPersistenceConformance(
+  name: string,
+  makePersistence: MakePersistence,
+  options?: PersistenceConformanceOptions,
+): void {
+  const skip = new Set<keyof AIPersistenceStores>(options?.skip ?? [])
+
+  describe(`AIPersistence conformance: ${name}`, () => {
+    let persistence: AIPersistence
+
+    beforeAll(async () => {
+      persistence = await makePersistence()
+    })
+
+    /**
+     * Return the store for `key`, or `null` when the backend intentionally
+     * skips it. Throws (failing the test) when a store is missing but was not
+     * declared in `options.skip`.
+     */
+    function resolveStore<TKey extends keyof AIPersistenceStores>(
+      key: TKey,
+    ): NonNullable<AIPersistenceStores[TKey]> | null {
+      const store = persistence.stores[key]
+      if (store) return store
+      if (skip.has(key)) return null
+      throw new Error(
+        `AIPersistence conformance: store '${key}' is missing. ` +
+          `Provide it, or pass { skip: ['${key}'] } if the omission is intentional.`,
+      )
+    }
+
+    describe('messages', () => {
+      it('round-trips a thread and returns [] for unknown threads', async () => {
+        const store = resolveStore('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' },
+        ])
+      })
+
+      it('round-trips rich message shapes with deep equality', async () => {
+        const store = resolveStore('messages')
+        if (!store) return
+
+        const rich: Array<ModelMessage> = [
+          { role: 'user', content: 'plain string' },
+          {
+            // Tool-call message with JSON arguments.
+            role: 'assistant',
+            content: '',
+            toolCalls: [
+              {
+                id: 'call-1',
+                type: 'function',
+                function: {
+                  name: 'search',
+                  arguments: '{"query":"weather in Paris"}',
+                },
+              },
+            ],
+          },
+          {
+            // Tool result message.
+            role: 'tool',
+            content: '{"temperature":21,"unit":"C"}',
+            toolCallId: 'call-1',
+          },
+          {
+            // Multi-part content: text + image reference.
+            role: 'user',
+            content: [
+              { type: 'text', content: 'What is in this image?' },
+              {
+                type: 'image',
+                source: {
+                  type: 'url',
+                  value: 'https://example.com/cat.png',
+                  mimeType: 'image/png',
+                },
+              },
+            ],
+          },
+          {
+            // Reasoning / thinking part.
+            role: 'assistant',
+            content: 'Here is my answer.',
+            thinking: [
+              {
+                content: 'The user is asking about the image.',
+                signature: 'sig-1',
+              },
+            ],
+          },
+        ]
+
+        await store.saveThread('thread-rich', rich)
+        expect(await store.loadThread('thread-rich')).toEqual(rich)
+      })
+    })
+
+    describe('runs', () => {
+      it('creates, resumes idempotently, updates, and gets', async () => {
+        const store = resolveStore('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 = resolveStore('interrupts')
+        if (!store) return
+
+        expect(await store.get('int-missing')).toBeNull()
+
+        await store.create({
+          interruptId: 'int-1',
+          runId: 'run-i',
+          threadId: 'thread-i',
+          requestedAt: 10,
+          payload: { tool: 'search', args: { q: 'x' } },
+        })
+        await store.create({
+          interruptId: 'int-2',
+          runId: 'run-i',
+          threadId: 'thread-i',
+          requestedAt: 20,
+          payload: { tool: 'write' },
+        })
+        await store.create({
+          interruptId: 'int-3',
+          runId: 'run-other',
+          threadId: 'thread-i',
+          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([])
+      })
+
+      it('create is insert-if-absent: a duplicate id never clobbers a resolved interrupt', async () => {
+        const store = resolveStore('interrupts')
+        if (!store) return
+
+        await store.create({
+          interruptId: 'int-dup',
+          runId: 'run-dup',
+          threadId: 'thread-dup',
+          requestedAt: 100,
+          payload: { attempt: 1 },
+        })
+        await store.resolve('int-dup', { answer: 42 })
+
+        // A second create with the SAME id must be a no-op — not overwrite the
+        // now-resolved record back to pending with a fresh payload.
+        await store.create({
+          interruptId: 'int-dup',
+          runId: 'run-dup',
+          threadId: 'thread-dup',
+          requestedAt: 200,
+          payload: { attempt: 2 },
+        })
+
+        const after = await store.get('int-dup')
+        expect(after?.status).toBe('resolved')
+        expect(after?.response).toEqual({ answer: 42 })
+        expect(after?.payload).toEqual({ attempt: 1 })
+        expect(after?.requestedAt).toBe(100)
+      })
+    })
+
+    describe('metadata', () => {
+      it('sets, gets, scopes, and deletes', async () => {
+        const store = resolveStore('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('locks', () => {
+      it('runs the critical section and returns its value', async () => {
+        const store = resolveStore('locks')
+        if (!store) return
+
+        const order: Array<string> = []
+        const result = await store.withLock('lock-key', () => {
+          order.push('inside')
+          return Promise.resolve(42)
+        })
+        expect(result).toBe(42)
+        expect(order).toEqual(['inside'])
+      })
+
+      it('serializes concurrent holders of the same key (mutual exclusion)', async () => {
+        const store = resolveStore('locks')
+        if (!store) return
+
+        let active = 0
+        let overlaps = 0
+        const enterExit = async () => {
+          active += 1
+          if (active > 1) overlaps += 1
+          // Yield so a second critical section would interleave if the lock
+          // failed to exclude it.
+          await Promise.resolve()
+          await Promise.resolve()
+          active -= 1
+        }
+
+        await Promise.all([
+          store.withLock('mx-key', enterExit),
+          store.withLock('mx-key', enterExit),
+          store.withLock('mx-key', enterExit),
+        ])
+
+        expect(overlaps).toBe(0)
+      })
+
+      it('releases the lock when the critical section throws', async () => {
+        const store = resolveStore('locks')
+        if (!store) return
+
+        await expect(
+          store.withLock('throw-key', () => Promise.reject(new Error('boom'))),
+        ).rejects.toThrow('boom')
+
+        // The lock must have been released despite the throw: a subsequent
+        // acquisition runs rather than deadlocking.
+        const result = await store.withLock('throw-key', () =>
+          Promise.resolve('recovered'),
+        )
+        expect(result).toBe('recovered')
+      })
+    })
+  })
+}
diff --git a/packages/ai-persistence/src/types.ts b/packages/ai-persistence/src/types.ts
new file mode 100644
index 000000000..74df410da
--- /dev/null
+++ b/packages/ai-persistence/src/types.ts
@@ -0,0 +1,385 @@
+import type { LockStore, ModelMessage, TokenUsage } from '@tanstack/ai'
+
+// ===========================================================================
+// Store contracts
+// ===========================================================================
+//
+// EVOLUTION POLICY
+// ----------------
+// These store interfaces are the compatibility surface between the core
+// middleware and every backend (memory, drizzle, prisma, cloudflare, …).
+// To avoid breaking existing adapters:
+//
+//   - New store methods are added as OPTIONAL (`method?: (...) => ...`). The
+//     middleware feature-detects them (`store.method?.(...)`) and degrades
+//     gracefully when a backend has not implemented them yet.
+//   - Never tighten an existing method's required arguments or widen its
+//     required return shape in a breaking way.
+//
+// The shared conformance testkit (`./testkit/conformance.ts`) is the
+// authoritative compatibility gate: every invariant documented on the methods
+// below is asserted there, and every backend runs the identical suite. If an
+// invariant is not encoded in the testkit, adapters cannot discover it — so
+// promote new invariants into both the JSDoc here AND the testkit.
+//
+// TIMESTAMP CONVENTION
+// --------------------
+// Store *records* (`RunRecord`, `InterruptRecord`) speak **epoch
+// milliseconds** (`number`), the native unit for SQL/`BIGINT` columns and
+// `Date.now()`. Wire/result references that leave the persistence layer speak
+// **ISO-8601 strings**. The middleware performs the number→ISO conversion at
+// the boundary; do not mix the two on a single field.
+
+/**
+ * Durable store for a thread's full message transcript.
+ *
+ * A "thread" is the unit of conversation history. `saveThread` always receives
+ * and persists the **complete, authoritative** message list — it is an
+ * overwrite, never an append. The middleware snapshots `ctx.messages` (the full
+ * running transcript) into it.
+ */
+export interface MessageStore {
+  /**
+   * Return the full stored transcript for `threadId`, in insertion order.
+   *
+   * INVARIANT: returns an empty array (never `null`/`undefined`) for a thread
+   * that was never saved. Callers treat `[]` as "no history".
+   */
+  loadThread: (threadId: string) => Promise<Array<ModelMessage>>
+  /**
+   * Overwrite the stored transcript for `threadId` with `messages`.
+   *
+   * INVARIANT: this is a full replace. `messages` is the complete authoritative
+   * history; the previous contents are discarded (not merged or appended).
+   */
+  saveThread: (threadId: string, messages: Array<ModelMessage>) => Promise<void>
+}
+
+export type RunStatus = 'running' | 'completed' | 'failed' | 'interrupted'
+
+/**
+ * A single generation/chat run.
+ *
+ * @property startedAt - Epoch ms when the run was first created.
+ * @property finishedAt - Epoch ms when the run reached a terminal status.
+ */
+export interface RunRecord {
+  runId: string
+  threadId: string
+  status: RunStatus
+  startedAt: number
+  finishedAt?: number
+  error?: string
+  usage?: TokenUsage
+}
+
+/** Durable store for run lifecycle records. */
+export interface RunStore {
+  /**
+   * Create a run record, or return the existing one if `runId` is already
+   * present (resume).
+   *
+   * INVARIANT (idempotency): if a record for `runId` already exists it is
+   * returned **unchanged** and the passed `threadId`/`startedAt`/`status` are
+   * ignored. This is what makes resuming a run safe — the second call for a
+   * `runId` must not mutate `startedAt`, `threadId`, or status. `status`
+   * defaults to `'running'` on first creation.
+   */
+  createOrResume: (
+    input: Pick<RunRecord, 'runId' | 'threadId' | 'startedAt'> & {
+      status?: RunStatus
+    },
+  ) => Promise<RunRecord>
+  /**
+   * Patch a run record's mutable fields.
+   *
+   * INVARIANT: updating a `runId` that does not exist is a **no-op** — it must
+   * not throw and must not create a record.
+   */
+  update: (
+    runId: string,
+    patch: Partial<
+      Pick<RunRecord, 'status' | 'finishedAt' | 'error' | 'usage'>
+    >,
+  ) => Promise<void>
+  /** Return the run record for `runId`, or `null` if none exists. */
+  get: (runId: string) => Promise<RunRecord | null>
+}
+
+/** Lifecycle status of a human-in-the-loop interrupt. */
+export type InterruptStatus = 'pending' | 'resolved' | 'cancelled'
+
+/**
+ * A human-in-the-loop interrupt (tool approval, client-tool input request, …).
+ *
+ * @property requestedAt - Epoch ms when the interrupt was created.
+ * @property resolvedAt - Epoch ms when the interrupt was resolved/cancelled;
+ *   absent while pending.
+ */
+export interface InterruptRecord {
+  interruptId: string
+  runId: string
+  threadId: string
+  status: InterruptStatus
+  requestedAt: number
+  resolvedAt?: number
+  payload: Record<string, unknown>
+  response?: unknown
+}
+
+/** Durable store for human-in-the-loop interrupts. */
+export interface InterruptStore {
+  /**
+   * Persist a new interrupt in the `'pending'` state.
+   *
+   * The record is accepted without `status`/`resolvedAt` so a "born resolved"
+   * interrupt is unrepresentable — every interrupt begins pending and only
+   * `resolve`/`cancel` may move it to a terminal state.
+   *
+   * INVARIANT (insert-if-absent): if an interrupt with the same `interruptId`
+   * already exists, `create` is a **no-op** — it must NOT overwrite the
+   * existing record. This is the canonical behaviour (SQL backends implement it
+   * via `ON CONFLICT DO NOTHING` / upsert-with-empty-update), so a duplicate
+   * create can never clobber a resolved interrupt back to pending.
+   */
+  create: (
+    record: Omit<InterruptRecord, 'status' | 'resolvedAt'>,
+  ) => Promise<void>
+  /**
+   * Move an interrupt to `'resolved'`, stamping `resolvedAt` and storing
+   * `response`. A no-op if `interruptId` does not exist.
+   */
+  resolve: (interruptId: string, response?: unknown) => Promise<void>
+  /**
+   * Move an interrupt to `'cancelled'`, stamping `resolvedAt`. A no-op if
+   * `interruptId` does not exist.
+   */
+  cancel: (interruptId: string) => Promise<void>
+  /** Return the interrupt for `interruptId`, or `null` if none exists. */
+  get: (interruptId: string) => Promise<InterruptRecord | null>
+  /**
+   * All interrupts for a thread.
+   *
+   * INVARIANT: ordered by insertion (equivalently `requestedAt` ascending). SQL
+   * backends MUST `ORDER BY requested_at` — the middleware and testkit rely on
+   * this stable ordering.
+   */
+  list: (threadId: string) => Promise<Array<InterruptRecord>>
+  /** Pending interrupts for a thread, ordered by `requestedAt` ascending. */
+  listPending: (threadId: string) => Promise<Array<InterruptRecord>>
+  /** All interrupts for a run, ordered by `requestedAt` ascending. */
+  listByRun: (runId: string) => Promise<Array<InterruptRecord>>
+  /** Pending interrupts for a run, ordered by `requestedAt` ascending. */
+  listPendingByRun: (runId: string) => Promise<Array<InterruptRecord>>
+}
+
+/**
+ * Scoped key/value store for arbitrary JSON metadata.
+ *
+ * `(scope, key)` is the composite identity; the same `key` under different
+ * scopes is independent.
+ */
+export interface MetadataStore {
+  /**
+   * Return the stored value for `(scope, key)`, or `null` if absent.
+   *
+   * CAVEAT: the return type is `unknown | null`, where `| null` collapses into
+   * `unknown` — a stored value of `null` is therefore **indistinguishable from
+   * absence** at the type level. Callers that must persist a real `null`
+   * distinctly from "not set" should wrap it (e.g. store `{ value: null }`).
+   */
+  get: (scope: string, key: string) => Promise<unknown | null>
+  /** Insert or overwrite the value for `(scope, key)`. */
+  set: (scope: string, key: string, value: unknown) => Promise<void>
+  /** Remove `(scope, key)`. A no-op if absent. Does not affect other scopes. */
+  delete: (scope: string, key: string) => Promise<void>
+}
+
+export interface AIPersistenceStores {
+  messages?: MessageStore
+  runs?: RunStore
+  interrupts?: InterruptStore
+  metadata?: MetadataStore
+  locks?: LockStore
+}
+
+export interface AIPersistence<
+  TStores extends AIPersistenceStores = AIPersistenceStores,
+> {
+  stores: ExactStoreKeys<TStores>
+}
+
+type StoreKey = keyof AIPersistenceStores
+type ExactStoreKeys<TStores> =
+  Exclude<keyof TStores, StoreKey> extends never
+    ? TStores
+    : TStores & Record<Exclude<keyof TStores, StoreKey>, never>
+
+export type AIPersistenceOverrides = {
+  [TKey in StoreKey]?: AIPersistenceStores[TKey] | false
+}
+
+type BaseStoreValue<
+  TBase extends AIPersistenceStores,
+  TKey extends StoreKey,
+> = TKey extends keyof TBase ? TBase[TKey] : never
+
+type OverrideStoreValue<
+  TOverrides extends AIPersistenceOverrides,
+  TKey extends StoreKey,
+> = TKey extends keyof TOverrides ? TOverrides[TKey] : never
+
+type ResolvedStoreValue<
+  TBase extends AIPersistenceStores,
+  TOverrides extends AIPersistenceOverrides,
+  TKey extends StoreKey,
+> = TKey extends keyof TOverrides
+  ?
+      | Exclude<OverrideStoreValue<TOverrides, TKey>, false | undefined>
+      | (undefined extends OverrideStoreValue<TOverrides, TKey>
+          ? Exclude<BaseStoreValue<TBase, TKey>, undefined>
+          : never)
+  : Exclude<BaseStoreValue<TBase, TKey>, undefined>
+
+type BaseStoreIsRequired<
+  TBase extends AIPersistenceStores,
+  TKey extends StoreKey,
+> = TKey extends keyof TBase
+  ? object extends Pick<TBase, TKey>
+    ? false
+    : true
+  : false
+
+type ResolvedStoreIsRequired<
+  TBase extends AIPersistenceStores,
+  TOverrides extends AIPersistenceOverrides,
+  TKey extends StoreKey,
+> = TKey extends keyof TOverrides
+  ? false extends OverrideStoreValue<TOverrides, TKey>
+    ? false
+    : undefined extends OverrideStoreValue<TOverrides, TKey>
+      ? BaseStoreIsRequired<TBase, TKey>
+      : true
+  : BaseStoreIsRequired<TBase, TKey>
+
+type ResolvedRequiredKeys<
+  TBase extends AIPersistenceStores,
+  TOverrides extends AIPersistenceOverrides,
+> = {
+  [TKey in StoreKey]-?: [ResolvedStoreValue<TBase, TOverrides, TKey>] extends [
+    never,
+  ]
+    ? never
+    : ResolvedStoreIsRequired<TBase, TOverrides, TKey> extends true
+      ? TKey
+      : never
+}[StoreKey]
+
+type ResolvedOptionalKeys<
+  TBase extends AIPersistenceStores,
+  TOverrides extends AIPersistenceOverrides,
+> = {
+  [TKey in StoreKey]-?: [ResolvedStoreValue<TBase, TOverrides, TKey>] extends [
+    never,
+  ]
+    ? never
+    : ResolvedStoreIsRequired<TBase, TOverrides, TKey> extends true
+      ? never
+      : TKey
+}[StoreKey]
+
+type Simplify<T> = { [TKey in keyof T]: T[TKey] }
+
+export type ComposedAIPersistenceStores<
+  TBase extends AIPersistenceStores,
+  TOverrides extends AIPersistenceOverrides,
+> = Simplify<
+  {
+    [TKey in ResolvedRequiredKeys<TBase, TOverrides>]: ResolvedStoreValue<
+      TBase,
+      TOverrides,
+      TKey
+    >
+  } & {
+    [TKey in ResolvedOptionalKeys<TBase, TOverrides>]?: ResolvedStoreValue<
+      TBase,
+      TOverrides,
+      TKey
+    >
+  }
+>
+
+const storeKeys = [
+  'messages',
+  'runs',
+  'interrupts',
+  'metadata',
+  'locks',
+] satisfies Array<StoreKey>
+
+const storeKeySet = new Set<string>(storeKeys)
+
+function assertKnownStoreKeys(stores: object, location: string): void {
+  for (const key of Object.keys(stores)) {
+    if (!storeKeySet.has(key)) {
+      throw new Error(`Unknown AIPersistence ${location} key: ${key}`)
+    }
+  }
+}
+
+export function validatePersistenceStoreKeys(persistence: AIPersistence): void {
+  assertKnownStoreKeys(persistence.stores, 'store')
+}
+
+export function validateChatPersistenceStores(
+  persistence: AIPersistence,
+): void {
+  validatePersistenceStoreKeys(persistence)
+  if (persistence.stores.interrupts && !persistence.stores.runs) {
+    throw new Error('Chat persistence stores.interrupts requires stores.runs.')
+  }
+}
+
+export function defineAIPersistence<TStores extends AIPersistenceStores>(
+  persistence: AIPersistence<ExactStoreKeys<TStores>>,
+): AIPersistence<TStores> {
+  validatePersistenceStoreKeys(persistence)
+  return persistence
+}
+
+export function composePersistence<
+  TBase extends AIPersistenceStores,
+  TOverrides extends AIPersistenceOverrides,
+>(
+  base: AIPersistence<TBase>,
+  config: {
+    overrides: ExactStoreKeys<TOverrides>
+  },
+): AIPersistence<ComposedAIPersistenceStores<TBase, TOverrides>>
+export function composePersistence(
+  base: AIPersistence,
+  config: { overrides: AIPersistenceOverrides },
+): AIPersistence {
+  validatePersistenceStoreKeys(base)
+  assertKnownStoreKeys(config.overrides, 'override')
+
+  const stores: AIPersistenceStores = { ...base.stores }
+  for (const key of storeKeys) {
+    if (!Object.prototype.hasOwnProperty.call(config.overrides, key)) continue
+    const override = config.overrides[key]
+    if (override === false) {
+      delete stores[key]
+    } else if (override !== undefined) {
+      setStore(stores, key, override)
+    }
+  }
+  return { stores }
+}
+
+function setStore<TKey extends StoreKey>(
+  stores: AIPersistenceStores,
+  key: TKey,
+  value: NonNullable<AIPersistenceStores[TKey]>,
+): void {
+  stores[key] = value
+}
diff --git a/packages/ai-persistence/tests/capabilities.test.ts b/packages/ai-persistence/tests/capabilities.test.ts
new file mode 100644
index 000000000..cbf83d8c2
--- /dev/null
+++ b/packages/ai-persistence/tests/capabilities.test.ts
@@ -0,0 +1,146 @@
+import { describe, expect, it } from 'vitest'
+import { EventType, chat, defineChatMiddleware } from '@tanstack/ai'
+import type {
+  AnyTextAdapter,
+  ChatMiddlewareContext,
+  LockStore,
+  StreamChunk,
+} from '@tanstack/ai'
+import { memoryPersistence } from '../src/memory'
+import { withChatPersistence } from '../src/middleware'
+import {
+  InterruptsCapability,
+  LocksCapability,
+  PersistenceCapability,
+  getInterrupts,
+  getLocks,
+  getPersistence,
+} from '../src/capabilities'
+import { createInterruptController } from '../src/interrupts'
+import type { AIPersistence, InterruptStore } from '../src'
+
+function mockAdapter(chunks: Array<StreamChunk>) {
+  return {
+    kind: 'text',
+    name: 'mock',
+    model: 'test-model',
+    '~types': {},
+    chatStream: () =>
+      (async function* () {
+        for (const c of chunks) yield c
+      })(),
+    structuredOutput: async () => ({ data: {}, rawText: '{}' }),
+  } as unknown as AnyTextAdapter
+}
+
+async function collect(stream: AsyncIterable<StreamChunk>) {
+  const out: Array<StreamChunk> = []
+  for await (const c of stream) out.push(c)
+  return out
+}
+
+describe('persistence capabilities', () => {
+  it('provides persistence, interrupts, and locks to downstream middleware', async () => {
+    const persistence = memoryPersistence()
+    const seen: {
+      persistence?: AIPersistence
+      interrupts?: InterruptStore
+      locks?: LockStore
+    } = {}
+
+    const consumer = defineChatMiddleware({
+      name: 'capability-consumer',
+      requires: [PersistenceCapability, InterruptsCapability, LocksCapability],
+      setup(ctx: ChatMiddlewareContext) {
+        seen.persistence = getPersistence(ctx)
+        seen.interrupts = getInterrupts(ctx)
+        seen.locks = getLocks(ctx)
+      },
+    })
+
+    await collect(
+      chat({
+        adapter: mockAdapter([
+          {
+            type: EventType.RUN_STARTED,
+            runId: 'r1',
+            threadId: 't1',
+            timestamp: 1,
+          },
+          {
+            type: EventType.RUN_FINISHED,
+            runId: 'r1',
+            threadId: 't1',
+            finishReason: 'stop',
+            timestamp: 1,
+          },
+        ]),
+        messages: [{ role: 'user', content: 'hi' }],
+        runId: 'r1',
+        threadId: 't1',
+        middleware: [withChatPersistence(persistence), consumer],
+      }) as AsyncIterable<StreamChunk>,
+    )
+
+    expect(seen.persistence).toBe(persistence)
+    expect(seen.interrupts).toBe(persistence.stores.interrupts)
+    expect(seen.locks).toBe(persistence.stores.locks)
+  })
+})
+
+describe('createInterruptController', () => {
+  it('delegates request/resolve/cancel/list to the underlying store', async () => {
+    const persistence = memoryPersistence()
+    const controller = createInterruptController({
+      store: persistence.stores.interrupts!,
+    })
+
+    await controller.request({
+      interruptId: 'c1',
+      runId: 'run-c',
+      threadId: 'thread-c',
+      requestedAt: 1,
+      payload: { kind: 'approval' },
+    })
+    expect(await controller.listPending('thread-c')).toHaveLength(1)
+    expect(await controller.listPendingByRun('run-c')).toHaveLength(1)
+
+    await controller.resolve('c1', { approved: true })
+    expect((await persistence.stores.interrupts!.get('c1'))?.status).toBe(
+      'resolved',
+    )
+    expect((await persistence.stores.interrupts!.get('c1'))?.response).toEqual({
+      approved: true,
+    })
+    expect(await controller.listPending('thread-c')).toHaveLength(0)
+
+    await controller.request({
+      interruptId: 'c2',
+      runId: 'run-c',
+      threadId: 'thread-c',
+      requestedAt: 2,
+      payload: {},
+    })
+    await controller.cancel('c2')
+    expect((await persistence.stores.interrupts!.get('c2'))?.status).toBe(
+      'cancelled',
+    )
+  })
+
+  it('creates interrupts in the pending state', async () => {
+    const persistence = memoryPersistence()
+    const controller = createInterruptController({
+      store: persistence.stores.interrupts!,
+    })
+    await controller.request({
+      interruptId: 'c1',
+      runId: 'run-c',
+      threadId: 'thread-c',
+      requestedAt: 1,
+      payload: {},
+    })
+    expect((await persistence.stores.interrupts!.get('c1'))?.status).toBe(
+      'pending',
+    )
+  })
+})
diff --git a/packages/ai-persistence/tests/error-abort.test.ts b/packages/ai-persistence/tests/error-abort.test.ts
new file mode 100644
index 000000000..f1d5a2639
--- /dev/null
+++ b/packages/ai-persistence/tests/error-abort.test.ts
@@ -0,0 +1,285 @@
+import { describe, expect, it, vi } from 'vitest'
+import { EventType, chat, generateImage } from '@tanstack/ai'
+import type {
+  AnyTextAdapter,
+  GenerationAbortInfo,
+  GenerationErrorInfo,
+  GenerationMiddlewareContext,
+  ImageAdapter,
+  StreamChunk,
+} from '@tanstack/ai'
+import { memoryPersistence } from '../src/memory'
+import {
+  withChatPersistence,
+  withGenerationPersistence,
+} from '../src/middleware'
+import { composePersistence } 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 }
+}
+
+const runStarted = (): StreamChunk => ({
+  type: EventType.RUN_STARTED,
+  runId: 'r1',
+  threadId: 't1',
+  timestamp: 1,
+})
+
+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', toolCallId: 'tc1' }],
+  },
+})
+
+async function collect(stream: AsyncIterable<StreamChunk>) {
+  const out: Array<StreamChunk> = []
+  for await (const c of stream) out.push(c)
+  return out
+}
+
+function throwingChatAdapter(thrown: unknown): AnyTextAdapter {
+  return {
+    kind: 'text',
+    name: 'mock',
+    model: 'test-model',
+    '~types': {},
+    chatStream: () =>
+      (async function* () {
+        yield runStarted()
+        throw thrown
+      })(),
+    structuredOutput: async () => ({ data: {}, rawText: '{}' }),
+  } as unknown as AnyTextAdapter
+}
+
+describe('chat persistence error/abort hooks', () => {
+  it('marks the run failed when the provider throws mid-stream', async () => {
+    const persistence = memoryPersistence()
+
+    await expect(
+      collect(
+        chat({
+          adapter: throwingChatAdapter(new Error('provider exploded')),
+          messages: [{ role: 'user', content: 'hi' }],
+          runId: 'r1',
+          threadId: 't1',
+          middleware: [withChatPersistence(persistence)],
+        }) as AsyncIterable<StreamChunk>,
+      ),
+    ).rejects.toThrow('provider exploded')
+
+    const run = await persistence.stores.runs!.get('r1')
+    expect(run?.status).toBe('failed')
+    expect(run?.error).toBe('provider exploded')
+  })
+
+  it('coerces a non-Error thrown value into the run error string', async () => {
+    const persistence = memoryPersistence()
+
+    await expect(
+      collect(
+        chat({
+          adapter: throwingChatAdapter('string failure'),
+          messages: [{ role: 'user', content: 'hi' }],
+          runId: 'r1',
+          threadId: 't1',
+          middleware: [withChatPersistence(persistence)],
+        }) as AsyncIterable<StreamChunk>,
+      ),
+    ).rejects.toBeDefined()
+
+    const run = await persistence.stores.runs!.get('r1')
+    expect(run?.status).toBe('failed')
+    expect(run?.error).toBe('string failure')
+  })
+
+  it('propagates and does not swallow a store error thrown while recording an interrupt', async () => {
+    const base = memoryPersistence()
+    const real = base.stores.interrupts!
+    const createError = new Error('interrupts.create failed')
+    const persistence = composePersistence(base, {
+      overrides: {
+        interrupts: {
+          create: () => Promise.reject(createError),
+          resolve: (id, r) => real.resolve(id, r),
+          cancel: (id) => real.cancel(id),
+          get: (id) => real.get(id),
+          list: (t) => real.list(t),
+          listPending: (t) => real.listPending(t),
+          listByRun: (r) => real.listByRun(r),
+          listPendingByRun: (r) => real.listPendingByRun(r),
+        },
+      },
+    })
+
+    await expect(
+      collect(
+        chat({
+          adapter: mockAdapter([[runStarted(), interruptFinished()]]).adapter,
+          messages: [{ role: 'user', content: 'hi' }],
+          runId: 'r1',
+          threadId: 't1',
+          middleware: [withChatPersistence(persistence)],
+        }) as AsyncIterable<StreamChunk>,
+      ),
+    ).rejects.toThrow('interrupts.create failed')
+  })
+
+  it('leaves the interrupt persisted when the follow-up thread snapshot fails (partial write)', async () => {
+    const base = memoryPersistence()
+    const realMessages = base.stores.messages!
+    const saveError = new Error('saveThread failed')
+    const persistence = composePersistence(base, {
+      overrides: {
+        messages: {
+          loadThread: (t) => realMessages.loadThread(t),
+          saveThread: () => Promise.reject(saveError),
+        },
+      },
+    })
+
+    await expect(
+      collect(
+        chat({
+          adapter: mockAdapter([[runStarted(), interruptFinished()]]).adapter,
+          messages: [{ role: 'user', content: 'hi' }],
+          runId: 'r1',
+          threadId: 't1',
+          middleware: [withChatPersistence(persistence)],
+        }) as AsyncIterable<StreamChunk>,
+      ),
+    ).rejects.toThrow('saveThread failed')
+
+    // The interrupt was created before the failing snapshot, so it survives:
+    // recovery/retry can still see the pending interrupt.
+    const pending = await base.stores.interrupts!.listPending('t1')
+    expect(pending.map((p) => p.interruptId)).toEqual(['interrupt-1'])
+  })
+})
+
+function imageAdapterThatThrows(thrown: unknown): ImageAdapter<string> {
+  return {
+    kind: 'image',
+    name: 'test-image-provider',
+    model: 'test-image-model',
+    '~types': {
+      providerOptions: {},
+      modelProviderOptionsByName: {},
+      modelSizeByName: {},
+      modelInputModalitiesByName: {},
+    },
+    generateImages: vi.fn(() => Promise.reject(thrown)),
+  }
+}
+
+describe('generation persistence error/abort hooks', () => {
+  it('marks the run failed when generation throws', async () => {
+    const persistence = memoryPersistence()
+
+    await expect(
+      generateImage({
+        adapter: imageAdapterThatThrows(new Error('image boom')),
+        prompt: 'make an image',
+        threadId: 't-img',
+        runId: 'r-img',
+        middleware: [withGenerationPersistence(persistence)],
+      }),
+    ).rejects.toThrow('image boom')
+
+    const run = await persistence.stores.runs!.get('r-img')
+    expect(run?.status).toBe('failed')
+    expect(run?.error).toBe('image boom')
+  })
+
+  it('coerces a non-Error generation failure into the run error string', async () => {
+    const persistence = memoryPersistence()
+
+    await expect(
+      generateImage({
+        adapter: imageAdapterThatThrows('image string failure'),
+        prompt: 'make an image',
+        threadId: 't-img',
+        runId: 'r-img',
+        middleware: [withGenerationPersistence(persistence)],
+      }),
+    ).rejects.toBeDefined()
+
+    const run = await persistence.stores.runs!.get('r-img')
+    expect(run?.status).toBe('failed')
+    expect(run?.error).toBe('image string failure')
+  })
+
+  it('marks the run interrupted on generation abort', async () => {
+    const persistence = memoryPersistence()
+    const middleware = withGenerationPersistence(persistence)
+
+    await persistence.stores.runs!.createOrResume({
+      runId: 'r-abort',
+      threadId: 't-abort',
+      startedAt: 1,
+    })
+
+    // Drive the abort hook directly: only long-poll activities (video) route
+    // through onAbort at runtime, so exercise the handler in isolation.
+    const ctx = {
+      runId: 'r-abort',
+      threadId: 't-abort',
+      requestId: 'req-abort',
+    } as GenerationMiddlewareContext
+    await middleware.onAbort?.(ctx, {
+      duration: 1,
+      reason: 'client cancelled',
+    } as GenerationAbortInfo)
+
+    expect((await persistence.stores.runs!.get('r-abort'))?.status).toBe(
+      'interrupted',
+    )
+  })
+
+  it('coerces a non-Error into the run error string via the onError handler', async () => {
+    const persistence = memoryPersistence()
+    const middleware = withGenerationPersistence(persistence)
+    await persistence.stores.runs!.createOrResume({
+      runId: 'r-err',
+      threadId: 't-err',
+      startedAt: 1,
+    })
+    const ctx = {
+      runId: 'r-err',
+      threadId: 't-err',
+      requestId: 'req-err',
+    } as GenerationMiddlewareContext
+    await middleware.onError?.(ctx, {
+      error: { code: 500 },
+      duration: 1,
+    } as unknown as GenerationErrorInfo)
+
+    const run = await persistence.stores.runs!.get('r-err')
+    expect(run?.status).toBe('failed')
+    expect(run?.error).toBe('[object Object]')
+  })
+})
diff --git a/packages/ai-persistence/tests/interrupts.test.ts b/packages/ai-persistence/tests/interrupts.test.ts
new file mode 100644
index 000000000..302660d2c
--- /dev/null
+++ b/packages/ai-persistence/tests/interrupts.test.ts
@@ -0,0 +1,867 @@
+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'
+
+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('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)],
+      }) 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)],
+      }) 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)],
+      }) 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',
+      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)],
+        }) 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)],
+      }) 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)],
+      }) 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)],
+      }) 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)],
+      }) 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)],
+      }) 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)],
+      }) 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)],
+        }) 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)],
+        }) 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)],
+      }) 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)],
+        }) 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',
+      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)],
+        }) 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)],
+      }) 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',
+      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)],
+        }) 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',
+      requestedAt: 1,
+      payload: {},
+    })
+    await persistence.stores.interrupts!.create({
+      interruptId: 'cancel-me',
+      runId: 'old-run',
+      threadId: 't1',
+      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)],
+      }) 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)],
+      }) 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)],
+      }) as AsyncIterable<StreamChunk>,
+    )
+
+    expect((await persistence.stores.runs!.get('r1'))?.status).toBe(
+      'interrupted',
+    )
+    expect(await persistence.stores.interrupts!.listPending('t1')).toHaveLength(
+      1,
+    )
+  })
+
+  it('keeps the interrupt pending when a resume run fails, and a retry succeeds', async () => {
+    const persistence = memoryPersistence()
+
+    // Run 1 pauses on an interrupt.
+    const first = mockAdapter([[runStarted(), interruptFinished()]])
+    await collect(
+      chat({
+        adapter: first.adapter,
+        messages: [{ role: 'user', content: 'hi' }],
+        runId: 'r1',
+        threadId: 't1',
+        middleware: [withChatPersistence(persistence)],
+      }) as AsyncIterable<StreamChunk>,
+    )
+    expect(await persistence.stores.interrupts!.listPending('t1')).toHaveLength(
+      1,
+    )
+
+    // Run 2 (the resume) accepts the approval, then the provider fails
+    // mid-stream (e.g. HTTP 500) before reaching any success boundary.
+    const failing = {
+      kind: 'text',
+      name: 'mock',
+      model: 'test-model',
+      '~types': {},
+      chatStream: () =>
+        (async function* () {
+          yield runStarted()
+          throw new Error('provider 500')
+        })(),
+      structuredOutput: async () => ({ data: {}, rawText: '{}' }),
+    } as unknown as AnyTextAdapter
+
+    await expect(
+      collect(
+        chat({
+          adapter: failing,
+          messages: [],
+          runId: 'r1',
+          threadId: 't1',
+          resume: [
+            {
+              interruptId: 'interrupt-1',
+              status: 'resolved',
+              payload: { approved: true },
+            },
+          ],
+          middleware: [withChatPersistence(persistence)],
+        }) as AsyncIterable<StreamChunk>,
+      ),
+    ).rejects.toThrow('provider 500')
+
+    // The approval was NOT consumed: the interrupt is pending again and the run
+    // is marked failed.
+    expect(
+      (await persistence.stores.interrupts!.get('interrupt-1'))?.status,
+    ).toBe('pending')
+    expect(await persistence.stores.interrupts!.listPending('t1')).toHaveLength(
+      1,
+    )
+    expect((await persistence.stores.runs!.get('r1'))?.status).toBe('failed')
+
+    // Retrying with the same resume now succeeds and consumes the approval.
+    const retry = mockAdapter([
+      [runStarted(), text('continued'), runFinished('r1')],
+    ])
+    const chunks = await collect(
+      chat({
+        adapter: retry.adapter,
+        messages: [],
+        runId: 'r1',
+        threadId: 't1',
+        resume: [
+          {
+            interruptId: 'interrupt-1',
+            status: 'resolved',
+            payload: { approved: true },
+          },
+        ],
+        middleware: [withChatPersistence(persistence)],
+      }) as AsyncIterable<StreamChunk>,
+    )
+    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('fails closed: an approval resume without an `approved` flag denies the tool', async () => {
+    const persistence = memoryPersistence()
+    await persistence.stores.interrupts!.create({
+      interruptId: 'approval-1',
+      runId: 'r1',
+      threadId: 't1',
+      requestedAt: 1,
+      payload: { toolCallId: 'tc1', metadata: { kind: 'approval' } },
+    })
+
+    const run = mockAdapter([[runStarted(), text('ok'), runFinished('r1')]])
+    await collect(
+      chat({
+        adapter: run.adapter,
+        messages: [],
+        runId: 'r1',
+        threadId: 't1',
+        // Malformed/truncated persisted payload: no `approved` field.
+        resume: [
+          { interruptId: 'approval-1', status: 'resolved', payload: {} },
+        ],
+        middleware: [withChatPersistence(persistence)],
+      }) as AsyncIterable<StreamChunk>,
+    )
+
+    const approvals = (
+      run.calls[0] as { approvals?: ReadonlyMap<string, boolean> }
+    ).approvals
+    expect(approvals?.get('approval-1')).toBe(false)
+  })
+
+  it('honors an explicit approved:true resume payload', async () => {
+    const persistence = memoryPersistence()
+    await persistence.stores.interrupts!.create({
+      interruptId: 'approval-1',
+      runId: 'r1',
+      threadId: 't1',
+      requestedAt: 1,
+      payload: { toolCallId: 'tc1', metadata: { kind: 'approval' } },
+    })
+
+    const run = mockAdapter([[runStarted(), text('ok'), runFinished('r1')]])
+    await collect(
+      chat({
+        adapter: run.adapter,
+        messages: [],
+        runId: 'r1',
+        threadId: 't1',
+        resume: [
+          {
+            interruptId: 'approval-1',
+            status: 'resolved',
+            payload: { approved: true },
+          },
+        ],
+        middleware: [withChatPersistence(persistence)],
+      }) as AsyncIterable<StreamChunk>,
+    )
+
+    const approvals = (
+      run.calls[0] as { approvals?: ReadonlyMap<string, boolean> }
+    ).approvals
+    expect(approvals?.get('approval-1')).toBe(true)
+  })
+
+  it('denies the tool when an approval is cancelled', async () => {
+    const persistence = memoryPersistence()
+    await persistence.stores.interrupts!.create({
+      interruptId: 'approval-1',
+      runId: 'r1',
+      threadId: 't1',
+      requestedAt: 1,
+      payload: { toolCallId: 'tc1', metadata: { kind: 'approval' } },
+    })
+
+    const run = mockAdapter([[runStarted(), text('ok'), runFinished('r1')]])
+    await collect(
+      chat({
+        adapter: run.adapter,
+        messages: [],
+        runId: 'r1',
+        threadId: 't1',
+        resume: [{ interruptId: 'approval-1', status: 'cancelled' }],
+        middleware: [withChatPersistence(persistence)],
+      }) as AsyncIterable<StreamChunk>,
+    )
+
+    const approvals = (
+      run.calls[0] as { approvals?: ReadonlyMap<string, boolean> }
+    ).approvals
+    expect(approvals?.get('approval-1')).toBe(false)
+    expect(
+      (await persistence.stores.interrupts!.get('approval-1'))?.status,
+    ).toBe('cancelled')
+  })
+
+  it('drops the result of a cancelled client-tool interrupt', async () => {
+    const persistence = memoryPersistence()
+    await persistence.stores.interrupts!.create({
+      interruptId: 'client-1',
+      runId: 'r1',
+      threadId: 't1',
+      requestedAt: 1,
+      payload: { toolCallId: 'tc1', metadata: { kind: 'client_tool' } },
+    })
+
+    const run = mockAdapter([[runStarted(), text('ok'), runFinished('r1')]])
+    await collect(
+      chat({
+        adapter: run.adapter,
+        messages: [],
+        runId: 'r1',
+        threadId: 't1',
+        resume: [
+          {
+            interruptId: 'client-1',
+            status: 'cancelled',
+            payload: { answer: 99 },
+          },
+        ],
+        middleware: [withChatPersistence(persistence)],
+      }) as AsyncIterable<StreamChunk>,
+    )
+
+    // A cancelled client tool never surfaces its payload as a tool result: the
+    // resume state carries no entry for the tool call.
+    const clientToolResults = (
+      run.calls[0] as { clientToolResults?: ReadonlyMap<string, unknown> }
+    ).clientToolResults
+    expect(clientToolResults?.get('tc1')).toBeUndefined()
+    expect((await persistence.stores.interrupts!.get('client-1'))?.status).toBe(
+      'cancelled',
+    )
+  })
+
+  it('tolerates malformed persisted interrupt payloads without crashing', async () => {
+    const persistence = memoryPersistence()
+    // Payload with the wrong shapes for the defensive parsers: metadata is a
+    // string (not an object), toolCallId is a number.
+    await persistence.stores.interrupts!.create({
+      interruptId: 'weird-1',
+      runId: 'r1',
+      threadId: 't1',
+      requestedAt: 1,
+      payload: { metadata: 'not-an-object', toolCallId: 123 },
+    })
+
+    const run = mockAdapter([[runStarted(), text('ok'), runFinished('r1')]])
+    await collect(
+      chat({
+        adapter: run.adapter,
+        messages: [],
+        runId: 'r1',
+        threadId: 't1',
+        resume: [{ interruptId: 'weird-1', status: 'resolved', payload: {} }],
+        middleware: [withChatPersistence(persistence)],
+      }) as AsyncIterable<StreamChunk>,
+    )
+
+    // The run is unaffected (no approval/client-tool detected) and the resume is
+    // still committed on success.
+    expect(run.calls).toHaveLength(1)
+    expect(
+      (run.calls[0] as { approvals?: ReadonlyMap<string, boolean> }).approvals
+        ?.size ?? 0,
+    ).toBe(0)
+    expect((await persistence.stores.interrupts!.get('weird-1'))?.status).toBe(
+      'resolved',
+    )
+  })
+})
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..560069ecf
--- /dev/null
+++ b/packages/ai-persistence/tests/memory.test.ts
@@ -0,0 +1,132 @@
+import { describe, expect, it } from 'vitest'
+import { memoryPersistence } from '../src/memory'
+import { defineAIPersistence } 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.locks).toBeDefined()
+  })
+
+  it('exposes the complete state store set', () => {
+    expect(Object.keys(memoryPersistence().stores).sort()).toEqual([
+      'interrupts',
+      'locks',
+      'messages',
+      'metadata',
+      'runs',
+    ])
+  })
+
+  it('defineAIPersistence is an identity helper', () => {
+    const persistence = memoryPersistence()
+    expect(defineAIPersistence(persistence)).toBe(persistence)
+  })
+
+  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',
+        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',
+        requestedAt: 1,
+        payload: { kind: 'approval' },
+      })
+      await interrupts!.create({
+        interruptId: 'i2',
+        runId: 'r1',
+        threadId: 't2',
+        requestedAt: 2,
+        payload: { kind: 'input' },
+      })
+      await interrupts!.create({
+        interruptId: 'i3',
+        runId: 'r2',
+        threadId: 't1',
+        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('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/persistence-composition.test.ts b/packages/ai-persistence/tests/persistence-composition.test.ts
new file mode 100644
index 000000000..07bf755bb
--- /dev/null
+++ b/packages/ai-persistence/tests/persistence-composition.test.ts
@@ -0,0 +1,155 @@
+import { describe, expect, it } from 'vitest'
+import { composePersistence, defineAIPersistence } from '../src'
+import {
+  createInterruptStore,
+  createMessageStore,
+  createMetadataStore,
+  createRunStore,
+} from './persistence-fixtures'
+
+describe('composePersistence', () => {
+  it('replaces only the named store', () => {
+    const baseMessages = createMessageStore()
+    const overrideMessages = createMessageStore()
+    const runs = createRunStore()
+    const base = defineAIPersistence({
+      stores: { messages: baseMessages, runs },
+    })
+
+    const composed = composePersistence(base, {
+      overrides: { messages: overrideMessages },
+    })
+
+    expect(composed.stores.messages).toBe(overrideMessages)
+    expect(composed.stores.runs).toBe(runs)
+  })
+
+  it('applies multiple overrides independently', () => {
+    const base = defineAIPersistence({
+      stores: {
+        messages: createMessageStore(),
+        runs: createRunStore(),
+        interrupts: createInterruptStore(),
+      },
+    })
+    const messages = createMessageStore()
+    const runs = createRunStore()
+
+    const composed = composePersistence(base, {
+      overrides: { messages, runs },
+    })
+
+    expect(composed.stores.messages).toBe(messages)
+    expect(composed.stores.runs).toBe(runs)
+    expect(composed.stores.interrupts).toBe(base.stores.interrupts)
+  })
+
+  it('removes each store explicitly overridden with false', () => {
+    const base = defineAIPersistence({
+      stores: {
+        messages: createMessageStore(),
+        runs: createRunStore(),
+        interrupts: createInterruptStore(),
+      },
+    })
+
+    const composed = composePersistence(base, {
+      overrides: { runs: false, interrupts: false },
+    })
+
+    expect('runs' in composed.stores).toBe(false)
+    expect('interrupts' in composed.stores).toBe(false)
+    expect(composed.stores.messages).toBe(base.stores.messages)
+    expect(base.stores.runs).toBeDefined()
+    expect(base.stores.interrupts).toBeDefined()
+  })
+
+  it('inherits omitted and explicitly undefined stores from the base', () => {
+    const messages = createMessageStore()
+    const runs = createRunStore()
+    const metadata = createMetadataStore()
+    const base = defineAIPersistence({ stores: { messages, runs, metadata } })
+
+    const composed = composePersistence(base, {
+      overrides: { messages: undefined, metadata: createMetadataStore() },
+    })
+
+    expect(composed.stores.messages).toBe(messages)
+    expect(composed.stores.runs).toBe(runs)
+    expect(composed.stores.metadata).not.toBe(metadata)
+  })
+
+  it('does not mutate or assume ownership of base and override resources', () => {
+    let baseDisposeCalls = 0
+    let overrideDisposeCalls = 0
+    const baseMessages = {
+      ...createMessageStore(),
+      dispose: () => {
+        baseDisposeCalls += 1
+      },
+    }
+    const overrideMessages = {
+      ...createMessageStore(),
+      dispose: () => {
+        overrideDisposeCalls += 1
+      },
+    }
+    const base = defineAIPersistence({
+      stores: { messages: baseMessages, runs: createRunStore() },
+    })
+    const overrides = { messages: overrideMessages }
+    Object.freeze(base.stores)
+    Object.freeze(overrides)
+
+    const composed = composePersistence(base, { overrides })
+
+    expect(composed).not.toBe(base)
+    expect(composed.stores).not.toBe(base.stores)
+    expect(base.stores.messages).toBe(baseMessages)
+    expect(overrides.messages).toBe(overrideMessages)
+    expect(baseDisposeCalls).toBe(0)
+    expect(overrideDisposeCalls).toBe(0)
+  })
+
+  it('rejects unknown override keys received from untyped JavaScript', () => {
+    const base = defineAIPersistence({
+      stores: { messages: createMessageStore() },
+    })
+    const overrides = { messages: createMessageStore() }
+    Reflect.set(overrides, 'unknownStore', createRunStore())
+
+    expect(() => composePersistence(base, { overrides })).toThrow(
+      /unknown.*unknownStore/i,
+    )
+  })
+
+  it('rejects unknown base store keys received from untyped JavaScript', () => {
+    const stores = { messages: createMessageStore() }
+    Reflect.set(stores, 'unknownStore', createRunStore())
+
+    expect(() => defineAIPersistence({ stores })).toThrow(
+      /unknown.*unknownStore/i,
+    )
+  })
+
+  it('routes calls only to the selected store', async () => {
+    const baseCalls: Array<string> = []
+    const overrideCalls: Array<string> = []
+    const base = defineAIPersistence({
+      stores: {
+        messages: createMessageStore((threadId) => baseCalls.push(threadId)),
+      },
+    })
+    const overrideMessages = createMessageStore((threadId) =>
+      overrideCalls.push(threadId),
+    )
+    const composed = composePersistence(base, {
+      overrides: { messages: overrideMessages },
+    })
+
+    await composed.stores.messages.saveThread('thread-1', [])
+
+    expect(overrideCalls).toEqual(['thread-1'])
+    expect(baseCalls).toEqual([])
+  })
+})
diff --git a/packages/ai-persistence/tests/persistence-fixtures.ts b/packages/ai-persistence/tests/persistence-fixtures.ts
new file mode 100644
index 000000000..f86ec7ce5
--- /dev/null
+++ b/packages/ai-persistence/tests/persistence-fixtures.ts
@@ -0,0 +1,64 @@
+import type {
+  InterruptStore,
+  MessageStore,
+  MetadataStore,
+  RunRecord,
+  RunStore,
+} from '../src'
+
+export function createMessageStore(
+  onSave?: (threadId: string) => void,
+): MessageStore {
+  return {
+    loadThread: () => Promise.resolve([]),
+    saveThread: (threadId) => {
+      onSave?.(threadId)
+      return Promise.resolve()
+    },
+  }
+}
+
+export function createRunStore(): RunStore {
+  const runs = new Map<string, RunRecord>()
+  return {
+    createOrResume: (input) => {
+      const existing = 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,
+      }
+      runs.set(record.runId, record)
+      return Promise.resolve(record)
+    },
+    update: (runId, patch) => {
+      const existing = runs.get(runId)
+      if (existing) runs.set(runId, { ...existing, ...patch })
+      return Promise.resolve()
+    },
+    get: (runId) => Promise.resolve(runs.get(runId) ?? null),
+  }
+}
+
+export function createInterruptStore(): InterruptStore {
+  return {
+    create: () => Promise.resolve(),
+    resolve: () => Promise.resolve(),
+    cancel: () => Promise.resolve(),
+    get: () => Promise.resolve(null),
+    list: () => Promise.resolve([]),
+    listPending: () => Promise.resolve([]),
+    listByRun: () => Promise.resolve([]),
+    listPendingByRun: () => Promise.resolve([]),
+  }
+}
+
+export function createMetadataStore(): MetadataStore {
+  return {
+    get: () => Promise.resolve(null),
+    set: () => Promise.resolve(),
+    delete: () => Promise.resolve(),
+  }
+}
diff --git a/packages/ai-persistence/tests/persistence-types.test-d.ts b/packages/ai-persistence/tests/persistence-types.test-d.ts
new file mode 100644
index 000000000..f27a2444e
--- /dev/null
+++ b/packages/ai-persistence/tests/persistence-types.test-d.ts
@@ -0,0 +1,142 @@
+import { expectTypeOf } from 'vitest'
+import {
+  composePersistence,
+  defineAIPersistence,
+  memoryPersistence,
+  withChatPersistence,
+  withGenerationPersistence,
+} from '../src'
+import type { LockStore } from '@tanstack/ai'
+import type {
+  AIPersistence,
+  InterruptStore,
+  MessageStore,
+  MetadataStore,
+  RunStore,
+} from '../src'
+
+declare const messages: MessageStore
+declare const replacementMessages: MessageStore & {
+  readonly source: 'override-messages'
+}
+declare const runs: RunStore
+declare const replacementRuns: RunStore & {
+  readonly source: 'override-runs'
+}
+declare const interrupts: InterruptStore
+declare const metadata: MetadataStore
+declare const locks: LockStore
+
+const messagesOnly = defineAIPersistence({ stores: { messages } })
+expectTypeOf(messagesOnly).toEqualTypeOf<
+  AIPersistence<{ messages: MessageStore }>
+>()
+expectTypeOf(messagesOnly.stores).toEqualTypeOf<{
+  messages: MessageStore
+}>()
+// @ts-expect-error exact persistence types do not invent absent stores
+messagesOnly.stores.runs
+
+// @ts-expect-error persistence aggregates accept only registered store keys
+defineAIPersistence({ stores: { unknownStore: messages } })
+
+type InvalidExplicitStores = {
+  messages: MessageStore
+  unknownStore: MessageStore
+}
+const invalidExplicitPersistence: AIPersistence<InvalidExplicitStores> = {
+  // @ts-expect-error explicit AIPersistence store maps are exact too
+  stores: { messages, unknownStore: messages },
+}
+void invalidExplicitPersistence
+
+const base = defineAIPersistence({
+  stores: { messages, runs, interrupts, metadata },
+})
+
+const replaced = composePersistence(base, {
+  overrides: { messages: replacementMessages },
+})
+expectTypeOf(replaced.stores).toEqualTypeOf<{
+  messages: typeof replacementMessages
+  runs: RunStore
+  interrupts: InterruptStore
+  metadata: MetadataStore
+}>()
+
+const multiple = composePersistence(base, {
+  overrides: { messages: replacementMessages, runs: replacementRuns },
+})
+expectTypeOf(multiple.stores.messages).toEqualTypeOf<
+  typeof replacementMessages
+>()
+expectTypeOf(multiple.stores.runs).toEqualTypeOf<typeof replacementRuns>()
+expectTypeOf(multiple.stores.interrupts).toEqualTypeOf<InterruptStore>()
+
+// @ts-expect-error persistence overrides accept only registered store keys
+composePersistence(base, { overrides: { unknownStore: messages } })
+
+const removed = composePersistence(base, {
+  overrides: { runs: false, interrupts: false },
+})
+expectTypeOf(removed.stores).toEqualTypeOf<{
+  messages: MessageStore
+  metadata: MetadataStore
+}>()
+// @ts-expect-error false removes the store from the exact result
+removed.stores.runs
+// @ts-expect-error false removes the store from the exact result
+removed.stores.interrupts
+
+const inherited = composePersistence(base, {
+  overrides: { messages: undefined },
+})
+expectTypeOf(inherited.stores.messages).toEqualTypeOf<MessageStore>()
+expectTypeOf(inherited.stores.runs).toEqualTypeOf<RunStore>()
+
+declare const uncertainRemoval: MessageStore | false
+const uncertain = composePersistence(base, {
+  overrides: { messages: uncertainRemoval },
+})
+expectTypeOf(uncertain.stores.messages).toEqualTypeOf<
+  MessageStore | undefined
+>()
+expectTypeOf(uncertain.stores.runs).toEqualTypeOf<RunStore>()
+
+declare const uncertainReplacement: MessageStore | undefined
+const uncertainInherited = composePersistence(base, {
+  overrides: { messages: uncertainReplacement },
+})
+expectTypeOf(uncertainInherited.stores.messages).toEqualTypeOf<MessageStore>()
+
+withChatPersistence(messagesOnly)
+withChatPersistence(defineAIPersistence({ stores: { runs } }))
+withChatPersistence(
+  defineAIPersistence({ stores: { runs, interrupts, messages } }),
+)
+// @ts-expect-error a known interrupt store requires a known run store
+withChatPersistence(defineAIPersistence({ stores: { interrupts } }))
+
+withGenerationPersistence(defineAIPersistence({ stores: { runs } }))
+
+const chatWithRemovedRuns = composePersistence(base, {
+  overrides: { runs: false },
+})
+// @ts-expect-error composition carries the missing run dependency into chat
+withChatPersistence(chatWithRemovedRuns)
+
+declare const broadPersistence: AIPersistence
+declare const dynamicChatPersistence: AIPersistence<{
+  runs?: RunStore
+  interrupts?: InterruptStore
+}>
+withChatPersistence(broadPersistence)
+withChatPersistence(dynamicChatPersistence)
+withGenerationPersistence(broadPersistence)
+
+const memoryWithCustomLocks = composePersistence(memoryPersistence(), {
+  overrides: { locks },
+})
+expectTypeOf(memoryWithCustomLocks.stores.locks).toEqualTypeOf<LockStore>()
+const mutableMemoryPersistence = memoryPersistence()
+mutableMemoryPersistence.stores.locks = locks
diff --git a/packages/ai-persistence/tests/persistence-validation.test.ts b/packages/ai-persistence/tests/persistence-validation.test.ts
new file mode 100644
index 000000000..12c23adc5
--- /dev/null
+++ b/packages/ai-persistence/tests/persistence-validation.test.ts
@@ -0,0 +1,41 @@
+import { describe, expect, it } from 'vitest'
+import { withChatPersistence } from '../src/middleware'
+import type { AIPersistence } from '../src'
+import {
+  createInterruptStore,
+  createMessageStore,
+  createRunStore,
+} from './persistence-fixtures'
+
+describe('persistence store dependency validation', () => {
+  it('rejects a dynamic chat persistence with interrupts but no runs', () => {
+    const persistence: AIPersistence = {
+      stores: { interrupts: createInterruptStore() },
+    }
+
+    expect(() => withChatPersistence(persistence)).toThrow(
+      /interrupts.*stores\.runs/i,
+    )
+  })
+
+  it('allows independent message and run stores for chat', () => {
+    const messages: AIPersistence = {
+      stores: { messages: createMessageStore() },
+    }
+    const runs: AIPersistence = { stores: { runs: createRunStore() } }
+
+    expect(() => withChatPersistence(messages)).not.toThrow()
+    expect(() => withChatPersistence(runs)).not.toThrow()
+  })
+
+  it('allows a dynamic chat persistence with paired run and interrupt stores', () => {
+    const persistence: AIPersistence = {
+      stores: {
+        runs: createRunStore(),
+        interrupts: createInterruptStore(),
+      },
+    }
+
+    expect(() => withChatPersistence(persistence)).not.toThrow()
+  })
+})
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..63ac63be3
--- /dev/null
+++ b/packages/ai-persistence/tests/state-only.test.ts
@@ -0,0 +1,97 @@
+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('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..3065ae8ba
--- /dev/null
+++ b/packages/ai-persistence/tests/with-persistence.test.ts
@@ -0,0 +1,268 @@
+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)],
+      }) as AsyncIterable<StreamChunk>,
+    )
+
+    expect(await persistence.stores.messages!.loadThread('t1')).not.toEqual([])
+  })
+
+  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 f1866f5e5..3f1cc1b08 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..f932b1ef2 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) => {
@@ -87,7 +91,7 @@ describe('useChat', () => {
       const { result } = renderUseChat({
         connection: adapter,
         id: 'persisted-chat',
-        persistence,
+        persistence: { client: persistence },
       })
 
       await waitFor(() => {
@@ -116,7 +120,7 @@ describe('useChat', () => {
         connection: adapter,
         id: 'persisted-empty-chat',
         initialMessages,
-        persistence,
+        persistence: { client: persistence },
       })
 
       await waitFor(() => {
@@ -156,7 +160,7 @@ describe('useChat', () => {
         const chat = useChat({
           connection: createMockConnectionAdapter(),
           id,
-          persistence,
+          persistence: { client: persistence },
         })
 
         return { ...chat, setId }
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 32b3e885a..30c9ff202 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 || []
@@ -78,6 +97,17 @@ export function useChat<
       ? { connection: initialOptions.connection }
       : { fetcher: initialOptions.fetcher }
 
+    const instanceHolder: {
+      current: ChatClient<TTools, TContext> | undefined
+    } = { current: undefined }
+    const getActiveInstance = () => {
+      const currentInstance = instanceHolder.current
+      if (!currentInstance || activeClientRef.current !== currentInstance) {
+        return undefined
+      }
+      return currentInstance
+    }
+    const pendingInitializationErrors: Array<Error> = []
     const instance = new ChatClient<TTools, TContext>({
       devtoolsBridgeFactory: createChatDevtoolsBridge,
       ...transport,
@@ -93,6 +123,9 @@ export function useChat<
       ...(initialOptions.persistence !== undefined && {
         persistence: initialOptions.persistence,
       }),
+      ...(initialOptions.initialResumeSnapshot !== undefined && {
+        initialResumeSnapshot: initialOptions.initialResumeSnapshot,
+      }),
       ...(initialOptions.context !== undefined && {
         context: initialOptions.context,
       }),
@@ -103,63 +136,80 @@ export function useChat<
         outputKind: initialOptions.outputSchema ? 'structured' : 'chat',
       },
       onResponse: (response) => {
-        if (activeClientRef.current !== instance) return
+        if (!getActiveInstance()) return
         void optionsRef.current.onResponse?.(response)
       },
       onChunk: (chunk: StreamChunk) => {
-        if (activeClientRef.current !== instance) return
+        if (!getActiveInstance()) return
         optionsRef.current.onChunk?.(chunk)
       },
       onFinish: (message: UIMessage<TTools>) => {
-        if (activeClientRef.current !== instance) return
+        if (!getActiveInstance()) return
         optionsRef.current.onFinish?.(message)
       },
       onError: (error: Error) => {
-        if (activeClientRef.current !== instance) return
+        const currentInstance = instanceHolder.current
+        if (!currentInstance) {
+          pendingInitializationErrors.push(error)
+          return
+        }
+        if (activeClientRef.current !== currentInstance) return
         optionsRef.current.onError?.(error)
       },
       ...(initialOptions.tools !== undefined && {
         tools: initialOptions.tools,
       }),
       onCustomEvent: (eventType, data, context) => {
-        if (activeClientRef.current !== instance) return
+        if (!getActiveInstance()) return
         optionsRef.current.onCustomEvent?.(eventType, data, context)
       },
       ...(options.streamProcessor !== undefined && {
         streamProcessor: options.streamProcessor,
       }),
       onMessagesChange: (newMessages: Array<UIMessage<TTools>>) => {
-        if (activeClientRef.current !== instance) return
+        if (!getActiveInstance()) return
         setMessages(newMessages)
       },
       onLoadingChange: (newIsLoading: boolean) => {
-        if (activeClientRef.current !== instance) return
+        const currentInstance = getActiveInstance()
+        if (!currentInstance) return
         setIsLoading(newIsLoading)
+        syncResumeState(currentInstance)
       },
       onErrorChange: (newError: Error | undefined) => {
-        if (activeClientRef.current !== instance) return
+        if (!getActiveInstance()) return
         setError(newError)
       },
       onStatusChange: (status: ChatClientState) => {
-        if (activeClientRef.current !== instance) return
+        if (!getActiveInstance()) return
         setStatus(status)
       },
       onSubscriptionChange: (nextIsSubscribed: boolean) => {
-        if (activeClientRef.current !== instance) return
+        if (!getActiveInstance()) return
         setIsSubscribed(nextIsSubscribed)
       },
       onConnectionStatusChange: (nextStatus: ConnectionStatus) => {
-        if (activeClientRef.current !== instance) return
+        if (!getActiveInstance()) return
         setConnectionStatus(nextStatus)
       },
       onSessionGeneratingChange: (isGenerating: boolean) => {
-        if (activeClientRef.current !== instance) return
+        if (!getActiveInstance()) return
         setSessionGenerating(isGenerating)
       },
+      onResumeStateChange: (nextResumeState, nextPendingInterrupts) => {
+        if (!getActiveInstance()) return
+        setResumeState(nextResumeState)
+        setPendingInterrupts(nextPendingInterrupts)
+      },
     })
+    instanceHolder.current = instance
     activeClientRef.current = instance
+    for (const error of pendingInitializationErrors) {
+      if (activeClientRef.current !== instance) break
+      optionsRef.current.onError?.(error)
+    }
     return instance
-  }, [clientId])
+  }, [clientId, syncResumeState])
 
   useEffect(() => {
     const clientMessages = client.getMessages()
@@ -201,12 +251,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 +282,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 +331,8 @@ export function useChat<
 
   const clear = useCallback(() => {
     client.clear()
-  }, [client])
+    syncResumeState(client)
+  }, [client, syncResumeState])
 
   const setMessagesManually = useCallback(
     (newMessages: Array<UIMessage<TTools>>) => {
@@ -277,8 +357,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 +439,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..7511c58fe 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) => {
@@ -36,6 +40,29 @@ describe('useChat', () => {
       expect(result.current.sessionGenerating).toBe(false)
     })
 
+    it('reports persistence errors raised while the client is initializing', () => {
+      const persistenceError = new Error('resume persistence unavailable')
+      const onError = vi.fn()
+
+      expect(() =>
+        renderUseChat({
+          connection: createMockConnectionAdapter(),
+          onError,
+          persistence: {
+            server: {
+              getItem: () => {
+                throw persistenceError
+              },
+              setItem: vi.fn(),
+              removeItem: vi.fn(),
+            },
+          },
+        }),
+      ).not.toThrow()
+      expect(onError).toHaveBeenCalledOnce()
+      expect(onError).toHaveBeenCalledWith(persistenceError)
+    })
+
     it('should subscribe immediately when live is true', async () => {
       const adapter = createMockConnectionAdapter()
       const { result } = renderUseChat({ connection: adapter, live: true })
@@ -86,7 +113,7 @@ describe('useChat', () => {
       const { result } = renderUseChat({
         connection: adapter,
         id: 'persisted-chat',
-        persistence,
+        persistence: { client: persistence },
       })
 
       await waitFor(() => {
@@ -115,7 +142,7 @@ describe('useChat', () => {
         connection: adapter,
         id: 'persisted-empty-chat',
         initialMessages,
-        persistence,
+        persistence: { client: persistence },
       })
 
       await waitFor(() => {
@@ -155,7 +182,7 @@ describe('useChat', () => {
         const chat = useChat({
           connection: createMockConnectionAdapter(),
           id,
-          persistence,
+          persistence: { client: persistence },
         })
 
         return { ...chat, setId }
@@ -230,6 +257,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 +1893,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/approvals.ts b/packages/ai-sandbox/src/approvals.ts
index 41aad31a9..e98b8780b 100644
--- a/packages/ai-sandbox/src/approvals.ts
+++ b/packages/ai-sandbox/src/approvals.ts
@@ -15,13 +15,17 @@
  * `approvalId` is stable for a given (provider, kind, target) so a client grant
  * matches the same action on the resumed run.
  */
-import { EventType } from '@tanstack/ai'
+import { CUSTOM_EVENT, EventType } from '@tanstack/ai'
 import { evaluateCommand } from './policy'
 import type { SandboxPolicy } from './policy'
 import type { StreamChunk } from '@tanstack/ai'
 
-/** CUSTOM event name emitted when a harness action needs client approval. */
-export const APPROVAL_REQUESTED_EVENT = 'approval-requested'
+/**
+ * CUSTOM event name emitted when a harness action needs client approval.
+ * Sourced from the core catalog so the emitter can never drift from the name
+ * consumers match against (see `@tanstack/ai` `CUSTOM_EVENT.APPROVAL_REQUESTED`).
+ */
+export const APPROVAL_REQUESTED_EVENT = CUSTOM_EVENT.APPROVAL_REQUESTED
 
 /** A stable, opaque approval id for a harness action. */
 export function approvalId(input: {
diff --git a/packages/ai-sandbox/src/capabilities.ts b/packages/ai-sandbox/src/capabilities.ts
index 8abd7f95d..1a8693428 100644
--- a/packages/ai-sandbox/src/capabilities.ts
+++ b/packages/ai-sandbox/src/capabilities.ts
@@ -5,12 +5,19 @@
  * - `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. No middleware provides
+ *   `SandboxStoreCapability` directly — instead, when a persistence middleware
+ *   supplies `PersistenceCapability`, `withSandbox` adapts its `stores.metadata`
+ *   into a `SandboxStore`; `LocksCapability` is consumed as-is when provided.
  */
-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 +26,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 +46,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/contracts.ts b/packages/ai-sandbox/src/contracts.ts
index 062fb74e7..093c3ec4a 100644
--- a/packages/ai-sandbox/src/contracts.ts
+++ b/packages/ai-sandbox/src/contracts.ts
@@ -67,8 +67,9 @@ export interface ProcessOptions {
  * A live background process. `stdout`/`stderr` are async-iterables of decoded
  * chunks; `stdin.write` feeds the process (duplex — required for ACP harness
  * protocols such as Codex / Gemini CLI). There is intentionally NO
- * reconnect-to-a-running-process in v1 — that belongs to the durable-stream /
- * persistence layer.
+ * reconnect-to-a-running-process here — that is the durable-stream half, which
+ * moved to PR #955. (The persistence layer that lands in this PR persists the
+ * workspace tree, not a live process attachment.)
  */
 export interface SpawnHandle {
   readonly pid: number
diff --git a/packages/ai-sandbox/src/index.ts b/packages/ai-sandbox/src/index.ts
index 2c5bf2855..02aaea8cd 100644
--- a/packages/ai-sandbox/src/index.ts
+++ b/packages/ai-sandbox/src/index.ts
@@ -39,7 +39,6 @@ export type {
   ReuseStrategy,
   SnapshotStrategy,
 } from './sandbox'
-
 // Workspace
 export {
   defineWorkspace,
diff --git a/packages/ai-sandbox/src/middleware.ts b/packages/ai-sandbox/src/middleware.ts
index d25314429..ccc4a6021 100644
--- a/packages/ai-sandbox/src/middleware.ts
+++ b/packages/ai-sandbox/src/middleware.ts
@@ -5,8 +5,8 @@
  * - `setup`: resume-or-create the sandbox (via the definition's ensure
  *   algorithm), provide the handle, using the optional SandboxStore/Locks
  *   capabilities when a persistence middleware supplied them (in-memory
- *   fallback otherwise). If `fileEvents` is not false, starts a watcher
- *   that dispatches to sandbox-scoped hooks and forwards to the runtime sink.
+ *   fallback otherwise). If `fileEvents` is not false, starts a watcher that
+ *   dispatches to sandbox-scoped hooks and forwards to the runtime sink.
  * - `onFinish`/`onAbort`/`onError`: stop the watcher, snapshot (`after-run`)
  *   and/or destroy per lifecycle.
  *
@@ -37,19 +37,21 @@ 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'
 
 /** 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. */
@@ -59,6 +61,69 @@ interface SandboxRunState {
 }
 
 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
+}
 
 /**
  * Stop the watcher and drain any in-flight `diff()` promises before teardown,
@@ -73,13 +138,20 @@ async function drainWatcher(
   // Guard `stop()`: a rejecting watcher teardown must NOT propagate out of
   // here, or the caller skips the `definition.destroy(...)` that follows —
   // leaking the sandbox on exactly the abort path that must ALWAYS tear down.
-  try {
-    await state.watcher?.stop()
-  } catch (error) {
-    state.logger?.warn('sandbox watcher stop failed', { phase, error })
+  for (const watcher of state.watchers) {
+    try {
+      await watcher.stop()
+    } catch (error) {
+      state.logger?.warn('sandbox watcher stop failed', { phase, error })
+    }
   }
   await Promise.allSettled(state.pendingDiffs)
-  if (state.watcher) state.logger?.sandbox('sandbox watcher stopped', { phase })
+  if (state.watchers.length > 0) {
+    state.logger?.sandbox('sandbox watcher stopped', {
+      phase,
+      count: state.watchers.length,
+    })
+  }
 }
 
 /** Defensively pull tenant scoping out of the runtime context, if present. */
@@ -94,11 +166,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,
@@ -157,7 +234,8 @@ 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)
@@ -230,55 +308,51 @@ export function withSandbox(
 
       const fe = resolveFileEvents(definition.fileEvents)
       const pendingDiffs: Array<Promise<void>> = []
-      let watcher: SandboxWatchHandle | undefined
+      const watchers: Array<SandboxWatchHandle> = []
       if (fe.enabled) {
-        watcher = await watchWorkspace(handle, {
-          onEvent: (event: SandboxFileEvent) => {
-            const enriched = buildFileHookEvent(
-              handle,
-              watchRoot,
-              baseSha,
-              event,
-              logger,
-            )
-            void dispatchDefinitionHooks(hooks, enriched, logger)
-            runtime?.emit(enriched)
-            if (fe.diff) {
-              pendingDiffs.push(
-                enriched
-                  .diff()
-                  .then((diff) => {
-                    runtime?.emitFileDiff({ path: event.path, diff })
-                  })
-                  .catch((error: unknown) => {
-                    logger?.warn('sandbox file diff emit failed', {
-                      path: event.path,
-                      error,
-                    })
-                  }),
+        watchers.push(
+          await watchWorkspace(handle, {
+            root: watchRoot,
+            onEvent: (event: SandboxFileEvent) => {
+              const enriched = buildFileHookEvent(
+                handle,
+                watchRoot,
+                baseSha,
+                event,
+                logger,
               )
-            }
-          },
-          // Watch the SAME root the enrichment layer relativizes against
-          // (`buildFileHookEvent(handle, watchRoot, …)` and the `baseSha`
-          // capture). Without this the watcher defaults to `/workspace` while
-          // enrichment uses `watchRoot`, so a custom `workspace.root` makes the
-          // two look at different directories and git pathspecs break.
-          root: watchRoot,
-          ...(ctx.signal !== undefined ? { signal: ctx.signal } : {}),
-          ...(logger !== undefined ? { logger } : {}),
-        })
+              void dispatchDefinitionHooks(hooks, enriched, logger)
+              runtime?.emit(enriched)
+              if (fe.diff) {
+                pendingDiffs.push(
+                  enriched
+                    .diff()
+                    .then((diff) => {
+                      runtime?.emitFileDiff({ path: event.path, diff })
+                    })
+                    .catch((error: unknown) => {
+                      logger?.warn('sandbox file diff emit failed', {
+                        path: event.path,
+                        error,
+                      })
+                    }),
+                )
+              }
+            },
+            ...(ctx.signal !== undefined ? { signal: ctx.signal } : {}),
+            ...(logger !== undefined ? { logger } : {}),
+          }),
+        )
         logger?.sandbox('sandbox watcher started', {
           root: watchRoot,
           diff: fe.diff,
         })
       }
-
       runState.set(ctx, {
         handle,
         ensureCtx,
         pendingDiffs,
-        ...(watcher ? { watcher } : {}),
+        watchers,
         ...(logger !== undefined ? { logger } : {}),
       })
     },
@@ -291,7 +365,6 @@ export function withSandbox(
       await drainWatcher(state, 'finish')
 
       const lifecycle = definition.lifecycle
-
       if (
         lifecycle?.snapshot === 'after-run' &&
         handle.capabilities.snapshots &&
diff --git a/packages/ai-sandbox/src/sandbox.ts b/packages/ai-sandbox/src/sandbox.ts
index b1f20859e..0a3b292f3 100644
--- a/packages/ai-sandbox/src/sandbox.ts
+++ b/packages/ai-sandbox/src/sandbox.ts
@@ -132,108 +132,127 @@ export function defineSandbox(config: SandboxConfig): SandboxDefinition {
     const key = computeSandboxKey(keyInputFor(ctx))
     const caps = config.provider.capabilities()
 
-    return locks.withLock(`sandbox:${key}`, async () => {
-      const effectiveSnapshot: SnapshotStrategy =
-        config.lifecycle?.snapshot ?? (caps.snapshots ? 'after-setup' : 'none')
-      const maxAgeMs = parseMaxAgeMs(config.lifecycle?.snapshotMaxAge)
+    return locks.withLock(`sandbox:${key}`, async (lockSignal) => {
+      const combined = combineAbortSignals(lockSignal, ctx.signal)
+      const signal = combined.signal
+      try {
+        const effectiveSnapshot: SnapshotStrategy =
+          config.lifecycle?.snapshot ??
+          (caps.snapshots ? 'after-setup' : 'none')
+        const maxAgeMs = parseMaxAgeMs(config.lifecycle?.snapshotMaxAge)
 
-      const existing = await store.get(key)
-      if (existing) {
-        // Check whether the record has exceeded snapshotMaxAge; if so,
-        // discard and fall through to a fresh create.
-        const tooOld =
-          maxAgeMs !== undefined && Date.now() - existing.updatedAt > maxAgeMs
+        const existing = await store.get(key)
+        signal.throwIfAborted()
+        if (existing) {
+          // Check whether the record has exceeded snapshotMaxAge; if so,
+          // discard and fall through to a fresh create.
+          const tooOld =
+            maxAgeMs !== undefined && Date.now() - existing.updatedAt > maxAgeMs
 
-        if (!tooOld) {
-          // 1) Try to reconnect to the still-running sandbox.
-          const resumed = await config.provider.resume({
-            id: existing.providerSandboxId,
-            signal: ctx.signal,
-          })
-          if (resumed) {
-            await store.upsert({
-              ...existing,
-              latestRunId: ctx.runId,
-              updatedAt: Date.now(),
+          if (!tooOld) {
+            // 1) Try to reconnect to the still-running sandbox.
+            const resumed = await config.provider.resume({
+              id: existing.providerSandboxId,
+              signal,
             })
-            return resumed
+            if (resumed) {
+              signal.throwIfAborted()
+              await store.upsert({
+                ...existing,
+                latestRunId: ctx.runId,
+                updatedAt: Date.now(),
+              })
+              return resumed
+            }
+            // 2) Else restore from the latest snapshot, if supported.
+            if (
+              existing.latestSnapshotId &&
+              caps.snapshots &&
+              config.provider.restoreSnapshot
+            ) {
+              const restored = await config.provider.restoreSnapshot({
+                snapshotId: existing.latestSnapshotId,
+                workspace: config.workspace,
+                policy: config.policy,
+                env:
+                  config.workspace?.secrets !== undefined
+                    ? resolveAllSecrets(config.workspace.secrets)
+                    : undefined,
+                signal,
+              })
+              signal.throwIfAborted()
+              await store.upsert({
+                ...existing,
+                providerSandboxId: restored.id,
+                latestRunId: ctx.runId,
+                updatedAt: Date.now(),
+              })
+              return restored
+            }
           }
-          // 2) Else restore from the latest snapshot, if supported.
-          if (
-            existing.latestSnapshotId &&
-            caps.snapshots &&
-            config.provider.restoreSnapshot
-          ) {
-            const restored = await config.provider.restoreSnapshot({
-              snapshotId: existing.latestSnapshotId,
-              workspace: config.workspace,
-              policy: config.policy,
-              env:
-                config.workspace?.secrets !== undefined
-                  ? resolveAllSecrets(config.workspace.secrets)
-                  : undefined,
-              signal: ctx.signal,
-            })
-            await store.upsert({
-              ...existing,
-              providerSandboxId: restored.id,
-              latestRunId: ctx.runId,
-              updatedAt: Date.now(),
+          // 3) Else fall through and re-create under the same identity
+          //    (capability-aware degradation for ephemeral-disk providers, or
+          //    snapshotMaxAge TTL exceeded).
+        }
+
+        const created = await config.provider.create({
+          // Deterministic id so consumers can reconstruct the provider sandbox
+          // address from run context (not just from the store record).
+          id: key,
+          workspace: config.workspace,
+          policy: config.policy,
+          env:
+            config.workspace?.secrets !== undefined
+              ? resolveAllSecrets(config.workspace.secrets)
+              : undefined,
+          signal,
+        })
+        await assertLeaseOwnedOrDestroy(signal, created)
+
+        if (config.workspace) {
+          try {
+            await bootstrapWorkspace(created, config.workspace, {
+              signal,
             })
-            return restored
+          } catch (error) {
+            // Bootstrap failed after the sandbox was created but before it was
+            // recorded — destroy the orphan so a failed/retried run doesn't leak
+            // a (billed) sandbox, then surface the original error.
+            try {
+              await created.destroy()
+            } catch (cleanupError) {
+              throw new AggregateError(
+                [error, cleanupError],
+                'Sandbox bootstrap and orphan cleanup failed',
+              )
+            }
+            throw error
           }
         }
-        // 3) Else fall through and re-create under the same identity
-        //    (capability-aware degradation for ephemeral-disk providers, or
-        //    snapshotMaxAge TTL exceeded).
-      }
 
-      const created = await config.provider.create({
-        // Deterministic id so consumers can reconstruct the provider sandbox
-        // address from run context (not just from the store record).
-        id: key,
-        workspace: config.workspace,
-        policy: config.policy,
-        env:
-          config.workspace?.secrets !== undefined
-            ? resolveAllSecrets(config.workspace.secrets)
-            : undefined,
-        signal: ctx.signal,
-      })
-
-      if (config.workspace) {
-        try {
-          await bootstrapWorkspace(created, config.workspace, {
-            signal: ctx.signal,
-          })
-        } catch (error) {
-          // Bootstrap failed after the sandbox was created but before it was
-          // recorded — destroy the orphan so a failed/retried run doesn't leak
-          // a (billed) sandbox, then surface the original error.
-          await created.destroy().catch(() => {})
-          throw error
+        let latestSnapshotId: string | undefined
+        if (
+          effectiveSnapshot === 'after-setup' &&
+          caps.snapshots &&
+          created.snapshot
+        ) {
+          latestSnapshotId = (await created.snapshot('after-setup')).id
         }
-      }
 
-      let latestSnapshotId: string | undefined
-      if (
-        effectiveSnapshot === 'after-setup' &&
-        caps.snapshots &&
-        created.snapshot
-      ) {
-        latestSnapshotId = (await created.snapshot('after-setup')).id
+        await assertLeaseOwnedOrDestroy(signal, created)
+        await store.upsert({
+          key,
+          provider: config.provider.name,
+          providerSandboxId: created.id,
+          latestSnapshotId,
+          threadId: ctx.threadId,
+          latestRunId: ctx.runId,
+          updatedAt: Date.now(),
+        })
+        return created
+      } finally {
+        combined.dispose()
       }
-
-      await store.upsert({
-        key,
-        provider: config.provider.name,
-        providerSandboxId: created.id,
-        latestSnapshotId,
-        threadId: ctx.threadId,
-        latestRunId: ctx.runId,
-        updatedAt: Date.now(),
-      })
-      return created
     })
   }
 
@@ -262,3 +281,50 @@ export function defineSandbox(config: SandboxConfig): SandboxDefinition {
     destroy,
   }
 }
+
+function combineAbortSignals(
+  leaseSignal: AbortSignal,
+  callerSignal: AbortSignal | undefined,
+): { signal: AbortSignal; dispose: () => void } {
+  const controller = new AbortController()
+  const signals = callerSignal ? [leaseSignal, callerSignal] : [leaseSignal]
+  const listeners = new Map<AbortSignal, () => void>()
+
+  for (const signal of signals) {
+    if (signal.aborted) {
+      controller.abort(signal.reason)
+      break
+    }
+    const onAbort = () => controller.abort(signal.reason)
+    listeners.set(signal, onAbort)
+    signal.addEventListener('abort', onAbort, { once: true })
+  }
+
+  return {
+    signal: controller.signal,
+    dispose: () => {
+      for (const [signal, listener] of listeners) {
+        signal.removeEventListener('abort', listener)
+      }
+    },
+  }
+}
+
+async function assertLeaseOwnedOrDestroy(
+  signal: AbortSignal,
+  handle: SandboxHandle,
+): Promise<void> {
+  try {
+    signal.throwIfAborted()
+  } catch (error) {
+    try {
+      await handle.destroy()
+    } catch (cleanupError) {
+      throw new AggregateError(
+        [error, cleanupError],
+        'Sandbox lease loss and orphan cleanup failed',
+      )
+    }
+    throw error
+  }
+}
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/tests/ensure.test.ts b/packages/ai-sandbox/tests/ensure.test.ts
index 1de55787c..a65197351 100644
--- a/packages/ai-sandbox/tests/ensure.test.ts
+++ b/packages/ai-sandbox/tests/ensure.test.ts
@@ -3,6 +3,7 @@ import { defineSandbox } from '../src/sandbox'
 import { defineWorkspace, githubRepo } from '../src/workspace'
 import { InMemoryLockStore, InMemorySandboxStore } from '../src/store'
 import { FULL_CAPS, makeFakeProvider } from './fakes'
+import type { LockStore } from '@tanstack/ai'
 import type { SandboxCapabilities } from '../src/contracts'
 
 const baseCtx = () => ({
@@ -28,7 +29,10 @@ describe('ensureSandbox algorithm', () => {
     expect(provider.calls.create).toBe(1)
     expect(provider.calls.resume).toBe(0)
     // bootstrap cloned the repo + can run setup (fake handle tracks files)
-    const files = (handle as unknown as { files: Map<string, string> }).files
+    if (!('files' in handle) || !(handle.files instanceof Map)) {
+      throw new Error('Expected the fake sandbox file map')
+    }
+    const files = handle.files
     expect(files.has('/workspace/.git')).toBe(true)
     // recorded in the store under the compound key
     const rec = await ctx.store.get(def.key(ctx))
@@ -155,6 +159,31 @@ describe('ensureSandbox algorithm', () => {
     expect(a.id).toBe(b.id)
   })
 
+  it('destroys an unrecorded sandbox when the lease is lost after creation', async () => {
+    const lease = new AbortController()
+    const locks: LockStore = {
+      withLock: (_key, fn) => fn(lease.signal),
+    }
+    const provider = makeFakeProvider()
+    const create = provider.create.bind(provider)
+    provider.create = async (input) => {
+      const handle = await create(input)
+      lease.abort(new Error('lease lost'))
+      return handle
+    }
+    const def = defineSandbox({ id: 'repo', provider, workspace })
+    const ctx = { ...baseCtx(), locks }
+
+    await expect(def.ensure(ctx)).rejects.toThrow('lease lost')
+
+    const created = provider.created[0]
+    if (!created || !('destroyed' in created)) {
+      throw new Error('Expected a created fake sandbox')
+    }
+    expect(created.destroyed).toBe(true)
+    expect(await ctx.store.get(def.key(ctx))).toBeNull()
+  })
+
   it('defaults to snapshot after-setup when provider supports snapshots and no lifecycle.snapshot set', async () => {
     // caps.snapshots = true, no explicit lifecycle.snapshot → effectiveSnapshot should be 'after-setup'
     const provider = makeFakeProvider() // FULL_CAPS has snapshots: true
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-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 23d6495e8..327058d37 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/test-utils.ts b/packages/ai-solid/tests/test-utils.ts
index 82bff2ad7..5d0b1fd48 100644
--- a/packages/ai-solid/tests/test-utils.ts
+++ b/packages/ai-solid/tests/test-utils.ts
@@ -46,6 +46,9 @@ export function renderUseChat(options?: UseChatOptions) {
           setMessages: hook.setMessages,
           addToolResult: hook.addToolResult,
           addToolApprovalResponse: hook.addToolApprovalResponse,
+          resumeState: hook.resumeState(),
+          pendingInterrupts: hook.pendingInterrupts(),
+          resumeInterrupts: hook.resumeInterrupts,
         }
       },
     },
diff --git a/packages/ai-solid/tests/use-chat-resume.test.ts b/packages/ai-solid/tests/use-chat-resume.test.ts
new file mode 100644
index 000000000..6d8121d8e
--- /dev/null
+++ b/packages/ai-solid/tests/use-chat-resume.test.ts
@@ -0,0 +1,130 @@
+import { waitFor } from '@solidjs/testing-library'
+import { EventType } from '@tanstack/ai'
+import { describe, expect, it, vi } from 'vitest'
+import type { RunAgentResumeItem, StreamChunk } from '@tanstack/ai'
+import type {
+  ConnectConnectionAdapter,
+  RunAgentInputContext,
+  SubscribeConnectionAdapter,
+} from '@tanstack/ai-client'
+import { createMockConnectionAdapter, renderUseChat } from './test-utils'
+
+/**
+ * A connect adapter that records the `runContext` of each connect and echoes a
+ * success terminal for the interrupted run so a resume clears cleanly.
+ */
+function recordingResumeAdapter() {
+  const contexts: Array<RunAgentInputContext | undefined> = []
+  const adapter: ConnectConnectionAdapter = {
+    // eslint-disable-next-line @typescript-eslint/require-await
+    async *connect(_messages, _data, _signal, runContext) {
+      contexts.push(runContext)
+      yield {
+        type: EventType.RUN_FINISHED,
+        runId: runContext?.runId ?? 'run-1',
+        threadId: runContext?.threadId ?? 'thread-1',
+        timestamp: Date.now(),
+        outcome: { type: 'success' },
+      } as StreamChunk
+    },
+  }
+  return { adapter, contexts }
+}
+
+describe('useChat resume surface', () => {
+  it('hydrates resumeState and pendingInterrupts from initialResumeSnapshot', () => {
+    const adapter = createMockConnectionAdapter()
+    const { result } = renderUseChat({
+      connection: adapter,
+      threadId: 'thread-1',
+      initialResumeSnapshot: {
+        resumeState: { threadId: 'thread-1', runId: 'run-1' },
+        pendingInterrupts: [
+          {
+            id: 'approval-1',
+            reason: 'approval_required',
+            toolCallId: 'tool-1',
+            metadata: { kind: 'approval' },
+          },
+        ],
+      },
+    })
+
+    expect(result.current.resumeState).toEqual({
+      threadId: 'thread-1',
+      runId: 'run-1',
+    })
+    expect(result.current.pendingInterrupts).toEqual([
+      expect.objectContaining({ id: 'approval-1' }),
+    ])
+  })
+
+  it('resumeInterrupts forwards resume items to the client and clears pending interrupts', async () => {
+    const { adapter, contexts } = recordingResumeAdapter()
+    const { result } = renderUseChat({
+      connection: adapter,
+      threadId: 'thread-1',
+      initialResumeSnapshot: {
+        resumeState: { threadId: 'thread-1', runId: 'run-1' },
+        pendingInterrupts: [{ id: 'interrupt-1', reason: 'client_tool_input' }],
+      },
+    })
+
+    const resumeItems: Array<RunAgentResumeItem> = [
+      { interruptId: 'interrupt-1', status: 'resolved', payload: { value: 'ok' } },
+    ]
+    await result.current.resumeInterrupts(resumeItems)
+
+    // The interrupted run's thread/run id is reused and the resume entries are
+    // forwarded to the connection.
+    expect(contexts[0]?.threadId).toBe('thread-1')
+    expect(contexts[0]?.runId).toBe('run-1')
+    expect(contexts[0]?.resume).toEqual(resumeItems)
+
+    await waitFor(() => {
+      expect(result.current.pendingInterrupts).toEqual([])
+      expect(result.current.resumeState).toBeNull()
+    })
+  })
+
+  it('updates resumeState and pendingInterrupts reactively via onResumeStateChange', async () => {
+    const chunks: Array<StreamChunk> = [
+      {
+        type: EventType.RUN_STARTED,
+        runId: 'run-live-interrupt',
+        threadId: 'thread-live',
+        timestamp: Date.now(),
+      },
+      {
+        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 })
+
+    // No sendMessage() wrapper call here — the update must arrive purely
+    // through the client's onResumeStateChange callback into the signal.
+    await waitFor(() => {
+      expect(result.current.resumeState).toEqual({
+        threadId: 'thread-live',
+        runId: 'run-live-interrupt',
+      })
+      expect(result.current.pendingInterrupts).toEqual([
+        expect.objectContaining({ id: 'interrupt-live' }),
+      ])
+    })
+  })
+})
diff --git a/packages/ai-solid/tests/use-chat.test.ts b/packages/ai-solid/tests/use-chat.test.ts
index 31ba2f26f..f2c9c0524 100644
--- a/packages/ai-solid/tests/use-chat.test.ts
+++ b/packages/ai-solid/tests/use-chat.test.ts
@@ -74,7 +74,7 @@ describe('useChat', () => {
       const { result } = renderUseChat({
         connection: adapter,
         id: 'persisted-chat',
-        persistence,
+        persistence: { client: persistence },
       })
 
       await waitFor(() => {
@@ -103,7 +103,7 @@ describe('useChat', () => {
         connection: adapter,
         id: 'persisted-empty-chat',
         initialMessages,
-        persistence,
+        persistence: { client: persistence },
       })
 
       await waitFor(() => {
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 4aaf99f00..91db27ceb 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-svelte/tests/use-chat-resume.test.ts b/packages/ai-svelte/tests/use-chat-resume.test.ts
new file mode 100644
index 000000000..9c08787c6
--- /dev/null
+++ b/packages/ai-svelte/tests/use-chat-resume.test.ts
@@ -0,0 +1,136 @@
+import { EventType } from '@tanstack/ai'
+import { describe, expect, it, vi } from 'vitest'
+import type { RunAgentResumeItem, StreamChunk } from '@tanstack/ai'
+import type {
+  ConnectConnectionAdapter,
+  RunAgentInputContext,
+  SubscribeConnectionAdapter,
+} from '@tanstack/ai-client'
+import { createChat } from '../src/create-chat.svelte'
+import { createMockConnectionAdapter } from './test-utils'
+
+async function waitFor(check: () => void, timeout = 1000) {
+  const start = Date.now()
+  for (;;) {
+    try {
+      check()
+      return
+    } catch (err) {
+      if (Date.now() - start > timeout) throw err
+      await new Promise((resolve) => setTimeout(resolve, 10))
+    }
+  }
+}
+
+/**
+ * A connect adapter that records the `runContext` of each connect and echoes a
+ * success terminal for the interrupted run so a resume clears cleanly.
+ */
+function recordingResumeAdapter() {
+  const contexts: Array<RunAgentInputContext | undefined> = []
+  const adapter: ConnectConnectionAdapter = {
+    // eslint-disable-next-line @typescript-eslint/require-await
+    async *connect(_messages, _data, _signal, runContext) {
+      contexts.push(runContext)
+      yield {
+        type: EventType.RUN_FINISHED,
+        runId: runContext?.runId ?? 'run-1',
+        threadId: runContext?.threadId ?? 'thread-1',
+        timestamp: Date.now(),
+        outcome: { type: 'success' },
+      } as StreamChunk
+    },
+  }
+  return { adapter, contexts }
+}
+
+describe('createChat resume surface', () => {
+  it('hydrates resumeState and pendingInterrupts from initialResumeSnapshot', () => {
+    const adapter = createMockConnectionAdapter({ chunks: [] })
+    const chat = createChat({
+      connection: adapter,
+      threadId: 'thread-1',
+      initialResumeSnapshot: {
+        resumeState: { threadId: 'thread-1', runId: 'run-1' },
+        pendingInterrupts: [
+          {
+            id: 'approval-1',
+            reason: 'approval_required',
+            toolCallId: 'tool-1',
+            metadata: { kind: 'approval' },
+          },
+        ],
+      },
+    })
+
+    expect(chat.resumeState).toEqual({ threadId: 'thread-1', runId: 'run-1' })
+    expect(chat.pendingInterrupts).toEqual([
+      expect.objectContaining({ id: 'approval-1' }),
+    ])
+  })
+
+  it('resumeInterrupts forwards resume items to the client and clears pending interrupts', async () => {
+    const { adapter, contexts } = recordingResumeAdapter()
+    const chat = createChat({
+      connection: adapter,
+      threadId: 'thread-1',
+      initialResumeSnapshot: {
+        resumeState: { threadId: 'thread-1', runId: 'run-1' },
+        pendingInterrupts: [{ id: 'interrupt-1', reason: 'client_tool_input' }],
+      },
+    })
+
+    const resumeItems: Array<RunAgentResumeItem> = [
+      { interruptId: 'interrupt-1', status: 'resolved', payload: { value: 'ok' } },
+    ]
+    await chat.resumeInterrupts(resumeItems)
+
+    expect(contexts[0]?.threadId).toBe('thread-1')
+    expect(contexts[0]?.runId).toBe('run-1')
+    expect(contexts[0]?.resume).toEqual(resumeItems)
+
+    expect(chat.pendingInterrupts).toEqual([])
+    expect(chat.resumeState).toBeNull()
+  })
+
+  it('updates resumeState and pendingInterrupts reactively via onResumeStateChange', async () => {
+    const chunks: Array<StreamChunk> = [
+      {
+        type: EventType.RUN_STARTED,
+        runId: 'run-live-interrupt',
+        threadId: 'thread-live',
+        timestamp: Date.now(),
+      },
+      {
+        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 chat = createChat({ connection: adapter, live: true })
+
+    // No sendMessage() wrapper call here — the update must arrive purely
+    // through the client's onResumeStateChange callback into the rune.
+    await waitFor(() => {
+      expect(chat.resumeState).toEqual({
+        threadId: 'thread-live',
+        runId: 'run-live-interrupt',
+      })
+      expect(chat.pendingInterrupts).toEqual([
+        expect.objectContaining({ id: 'interrupt-live' }),
+      ])
+    })
+  })
+})
diff --git a/packages/ai-svelte/tests/use-chat.test.ts b/packages/ai-svelte/tests/use-chat.test.ts
index ff5b846ba..fd6fe11ef 100644
--- a/packages/ai-svelte/tests/use-chat.test.ts
+++ b/packages/ai-svelte/tests/use-chat.test.ts
@@ -73,7 +73,7 @@ describe('createChat', () => {
     const chat = createChat({
       connection: mockConnection,
       id: 'persisted-chat',
-      persistence,
+      persistence: { client: persistence },
     })
 
     expect(chat.messages).toEqual(persistedMessages)
@@ -100,7 +100,7 @@ describe('createChat', () => {
       connection: mockConnection,
       id: 'persisted-chat',
       initialMessages,
-      persistence,
+      persistence: { client: persistence },
     })
 
     expect(chat.messages).toEqual([])
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 8c54bd9cc..e6bb219d9 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/test-utils.ts b/packages/ai-vue/tests/test-utils.ts
index 3f8c05c46..50525b818 100644
--- a/packages/ai-vue/tests/test-utils.ts
+++ b/packages/ai-vue/tests/test-utils.ts
@@ -54,6 +54,9 @@ export function renderUseChat(options?: UseChatOptions) {
       setMessages: hook.setMessages,
       addToolResult: hook.addToolResult,
       addToolApprovalResponse: hook.addToolApprovalResponse,
+      resumeState: hook.resumeState,
+      pendingInterrupts: hook.pendingInterrupts,
+      resumeInterrupts: hook.resumeInterrupts,
     }
   }
 
diff --git a/packages/ai-vue/tests/use-chat-resume.test.ts b/packages/ai-vue/tests/use-chat-resume.test.ts
new file mode 100644
index 000000000..e20f617be
--- /dev/null
+++ b/packages/ai-vue/tests/use-chat-resume.test.ts
@@ -0,0 +1,146 @@
+import { EventType } from '@tanstack/ai'
+import { flushPromises } from '@vue/test-utils'
+import { describe, expect, it, vi } from 'vitest'
+import type { RunAgentResumeItem, StreamChunk } from '@tanstack/ai'
+import type {
+  ConnectConnectionAdapter,
+  RunAgentInputContext,
+  SubscribeConnectionAdapter,
+} from '@tanstack/ai-client'
+import { createMockConnectionAdapter, renderUseChat } from './test-utils'
+
+/**
+ * Poll `check` across microtask/macrotask boundaries until it stops throwing.
+ * `@vue/test-utils` ships `flushPromises` but no `waitFor`, and live-mode
+ * stream chunks land over several async ticks.
+ */
+async function waitFor(check: () => void, timeout = 1000) {
+  const start = Date.now()
+  for (;;) {
+    try {
+      check()
+      return
+    } catch (err) {
+      if (Date.now() - start > timeout) throw err
+      await flushPromises()
+      await new Promise((resolve) => setTimeout(resolve, 10))
+    }
+  }
+}
+
+/**
+ * A connect adapter that records the `runContext` of each connect and echoes a
+ * success terminal for the interrupted run so a resume clears cleanly.
+ */
+function recordingResumeAdapter() {
+  const contexts: Array<RunAgentInputContext | undefined> = []
+  const adapter: ConnectConnectionAdapter = {
+    // eslint-disable-next-line @typescript-eslint/require-await
+    async *connect(_messages, _data, _signal, runContext) {
+      contexts.push(runContext)
+      yield {
+        type: EventType.RUN_FINISHED,
+        runId: runContext?.runId ?? 'run-1',
+        threadId: runContext?.threadId ?? 'thread-1',
+        timestamp: Date.now(),
+        outcome: { type: 'success' },
+      } as StreamChunk
+    },
+  }
+  return { adapter, contexts }
+}
+
+describe('useChat resume surface', () => {
+  it('hydrates resumeState and pendingInterrupts from initialResumeSnapshot', () => {
+    const adapter = createMockConnectionAdapter()
+    const { result } = renderUseChat({
+      connection: adapter,
+      threadId: 'thread-1',
+      initialResumeSnapshot: {
+        resumeState: { threadId: 'thread-1', runId: 'run-1' },
+        pendingInterrupts: [
+          {
+            id: 'approval-1',
+            reason: 'approval_required',
+            toolCallId: 'tool-1',
+            metadata: { kind: 'approval' },
+          },
+        ],
+      },
+    })
+
+    expect(result.current.resumeState).toEqual({
+      threadId: 'thread-1',
+      runId: 'run-1',
+    })
+    expect(result.current.pendingInterrupts).toEqual([
+      expect.objectContaining({ id: 'approval-1' }),
+    ])
+  })
+
+  it('resumeInterrupts forwards resume items to the client and clears pending interrupts', async () => {
+    const { adapter, contexts } = recordingResumeAdapter()
+    const { result } = renderUseChat({
+      connection: adapter,
+      threadId: 'thread-1',
+      initialResumeSnapshot: {
+        resumeState: { threadId: 'thread-1', runId: 'run-1' },
+        pendingInterrupts: [{ id: 'interrupt-1', reason: 'client_tool_input' }],
+      },
+    })
+
+    const resumeItems: Array<RunAgentResumeItem> = [
+      { interruptId: 'interrupt-1', status: 'resolved', payload: { value: 'ok' } },
+    ]
+    await result.current.resumeInterrupts(resumeItems)
+    await flushPromises()
+
+    expect(contexts[0]?.threadId).toBe('thread-1')
+    expect(contexts[0]?.runId).toBe('run-1')
+    expect(contexts[0]?.resume).toEqual(resumeItems)
+
+    expect(result.current.pendingInterrupts).toEqual([])
+    expect(result.current.resumeState).toBeNull()
+  })
+
+  it('updates resumeState and pendingInterrupts reactively via onResumeStateChange', async () => {
+    const chunks: Array<StreamChunk> = [
+      {
+        type: EventType.RUN_STARTED,
+        runId: 'run-live-interrupt',
+        threadId: 'thread-live',
+        timestamp: Date.now(),
+      },
+      {
+        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 })
+
+    // No sendMessage() wrapper call here — the update must arrive purely
+    // through the client's onResumeStateChange callback into the ref.
+    await waitFor(() => {
+      expect(result.current.resumeState).toEqual({
+        threadId: 'thread-live',
+        runId: 'run-live-interrupt',
+      })
+      expect(result.current.pendingInterrupts).toEqual([
+        expect.objectContaining({ id: 'interrupt-live' }),
+      ])
+    })
+  })
+})
diff --git a/packages/ai-vue/tests/use-chat.test.ts b/packages/ai-vue/tests/use-chat.test.ts
index 0e227afe5..b513ef2c0 100644
--- a/packages/ai-vue/tests/use-chat.test.ts
+++ b/packages/ai-vue/tests/use-chat.test.ts
@@ -73,7 +73,7 @@ describe('useChat', () => {
       const { result } = renderUseChat({
         connection: adapter,
         id: 'persisted-chat',
-        persistence,
+        persistence: { client: persistence },
       })
       await flushPromises()
 
@@ -101,7 +101,7 @@ describe('useChat', () => {
         connection: adapter,
         id: 'persisted-chat',
         initialMessages,
-        persistence,
+        persistence: { client: persistence },
       })
       await flushPromises()
 
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..3636d310c
--- /dev/null
+++ b/packages/ai/skills/ai-core/persistence/SKILL.md
@@ -0,0 +1,180 @@
+---
+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, and locks through optional composable stores.
+  Interrupts resume with RunAgentInput.resume[].
+  Stream re-attach/delivery durability (replaying a disconnected/reloaded
+  stream) is a separate TRANSPORT feature (lands in PR #955), not part of this
+  middleware. Backends: memoryPersistence,
+  drizzlePersistence/sqlitePersistence, prismaPersistence.
+type: sub-skill
+library: tanstack-ai
+library_version: '0.10.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, and locks. It never mutates the chunk stream and stamps
+  **no** cursor. A `chat()` with no persistence middleware produces
+  byte-identical chunks.
+- **Stream re-attach / delivery durability** (a client disconnects or reloads
+  and still receives the full ordered stream) is a separate **transport-layer**
+  feature, not part of this middleware — it lands in PR #955. This middleware
+  stamps no delivery offsets: there is no in-band `cursor` and no
+  `chat({ cursor })` replay.
+- The persistence interface is `AIPersistence`; use
+  `defineAIPersistence({ stores })` for custom stores and
+  `composePersistence(base, { overrides })` to replace or disable individual
+  stores.
+- Use **`withChatPersistence(persistence)`** 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)`** for media
+  generation (`generateImage`, `generateAudio`, TTS, video, transcription):
+  run status updates. Durable media artifact/blob storage is a follow-up
+  feature; persisted results reference provider media URLs, which may expire.
+- 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 { sqlitePersistence } from '@tanstack/ai-persistence-drizzle/sqlite'
+
+const persistence = sqlitePersistence({
+  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(...)`:
+
+```tsx
+import { fetchServerSentEvents, useChat } from '@tanstack/ai-react'
+
+export function ApprovalChat() {
+  const chat = useChat({
+    connection: fetchServerSentEvents('/api/chat'),
+  })
+
+  return (
+    <button
+      type="button"
+      onClick={() => {
+        void chat.resumeInterrupts([
+          {
+            interruptId: 'interrupt-1',
+            status: 'resolved',
+            payload: { approved: true },
+          },
+        ])
+      }}
+    >
+      Approve
+    </button>
+  )
+}
+```
+
+`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 composition
+
+`AIPersistence` stores are optional, but dependent store pairs are validated
+fail-loud:
+
+| Capability   | Required stores      |
+| ------------ | -------------------- |
+| `messages`   | `messages`           |
+| `interrupts` | `runs`, `interrupts` |
+| `metadata`   | `metadata`           |
+| `locks`      | `locks`              |
+
+## Backends
+
+```ts
+import { memoryPersistence } from '@tanstack/ai-persistence' // tests/prototypes
+import {
+  drizzlePersistence, // BYO migrated SQLite-family Drizzle db, including D1
+  sqliteMigrations, // bundled SQL for custom migration workflows
+} from '@tanstack/ai-persistence-drizzle'
+import { sqlitePersistence } from '@tanstack/ai-persistence-drizzle/sqlite'
+import { prismaPersistence } from '@tanstack/ai-persistence-prisma' // BYO PrismaClient
+```
+
+The Drizzle package exports `sqliteMigrations` and a migration-copy CLI. The
+Prisma package exports `prismaModels` and a model-copy CLI so applications can
+incorporate the models into their own provider-specific migration workflow.
+The state tables are `messages`, `runs`, `interrupts`, and `metadata`.
+
+Projects that run their own drizzle-kit journal can own the schema instead of
+applying the bundled SQL: emit it with the `tanstack-ai-drizzle-schema` CLI
+(`--out <dir>` / `--stdout`), add the emitted file to the drizzle-kit `schema`
+paths, and pass it back via `drizzlePersistence(db, { schema })`. The runtime
+reads and writes through the injected table objects, so renamed tables/columns
+(including drizzle `casing` conventions) and extra app-owned columns (for
+example a nullable `userId` on `messages` for thread ownership) are supported;
+the `TanstackAiSchema` type pins the required column data shapes and
+construction validates tables/columns exist (`DrizzleSchemaError`).
+
+The Prisma models in the fragment are renameable the same way (an app often
+already has a `Message` or `Run` model): rename them in your copy and map each
+store to the renamed client delegate via
+`prismaPersistence(prisma, { models: { messages: 'chatMessage' } })` — values
+are camelCase client accessor names. Keep the fragment's field names/types and
+the metadata `scope_key` composite alias; DB names are governed by
+`@@map`/`@map`, and extra app-owned optional fields are ignored by the stores.
+Unresolvable delegates throw `PrismaModelError` at construction.
+
+## 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 0196f73b9..a311a3368 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"),
   });
 
@@ -325,6 +333,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 },
+  },
+])
+```
+
 > **Type-safe approval:** With typed `tools`, `part.approval` exists **only**
 > on parts for tools defined with `needsApproval: true`. Tools without approval
 > have no `approval` field (reading it is a compile error). For a
@@ -647,7 +668,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(
@@ -683,7 +704,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..d6d41409d 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,15 +3202,17 @@ 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
- * 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
- * widening happens.
+ * `StructuredOutputStream<T>`. On this path core emits the structured-output
+ * CUSTOM events (`structured-output.start`/`.complete`); approval and
+ * client-tool waits now surface as RUN_FINISHED interrupt outcomes, not CUSTOM
+ * events. The public `StructuredOutputStream` union still carries the legacy
+ * `ApprovalRequestedEvent`/`ToolInputAvailableEvent` for replay/back-compat,
+ * but core no longer emits them here. 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 widening happens.
  */
 type StructuredOutputStreamInternal<T> = AsyncIterable<
   StreamChunk | StructuredOutputCompleteEvent<T>
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 2eb6f774b..be7cc09ff 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,
@@ -1449,6 +1450,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()
@@ -1456,6 +1461,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
    */
@@ -1676,10 +1738,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
    */
@@ -1910,6 +1977,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. The arguments are complete now, so surface the parsed
     // input on the part. For adapters that skip TOOL_CALL_ARGS the arguments
     // string was back-filled from TOOL_CALL_END.input, so this parse matches
@@ -1937,6 +2011,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 ec2e72890..1029cd81a 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,10 @@ import {
 } from '../middleware/run'
 import type { InternalLogger } from '../../logger/internal-logger'
 import type { DebugOption } from '../../logger/types'
-import type { GenerationMiddleware } from '../middleware/types'
+import type {
+  GenerationMiddleware,
+  GenerationRunOptions,
+} from '../middleware/types'
 import type { AudioAdapter } from './adapter'
 import type { AudioGenerationResult, StreamChunk } from '../../types'
 
@@ -55,7 +63,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 +142,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 +158,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 +182,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 +190,9 @@ async function runGenerateAudio<
     provider: adapter.name,
     model,
     modelOptions: rest.modelOptions,
+    threadId,
+    runId,
+    artifactInputs: { prompt: rest.prompt, duration: rest.duration },
     createId,
   })
 
@@ -178,6 +200,7 @@ async function runGenerateAudio<
 
   aiEventClient.emit('audio:request:started', {
     requestId,
+    ...generationIdentityFields(identity),
     provider: adapter.name,
     model,
     prompt: rest.prompt,
@@ -192,11 +215,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 +233,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 +258,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 8021e0ce2..40f0b5573 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,10 @@ 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/types'
+import type {
+  GenerationMiddleware,
+  GenerationRunOptions,
+} from '../middleware/types'
 import type { ImageAdapter } from './adapter'
 import type {
   ImageGenerationResult,
@@ -137,19 +145,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 +234,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 +252,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 +280,9 @@ async function runGenerateImage<
     provider: adapter.name,
     model,
     modelOptions: rest.modelOptions,
+    threadId,
+    runId,
+    artifactInputs: { prompt: rest.prompt },
     createId,
   })
 
@@ -271,6 +294,7 @@ async function runGenerateImage<
 
   aiEventClient.emit('image:request:started', {
     requestId,
+    ...generationIdentityFields(identity),
     provider: adapter.name,
     model,
     prompt: resolved.text,
@@ -295,11 +319,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 +345,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 06ac193c8..1456dd8e4 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,10 @@ import {
 } from '../middleware/run'
 import type { InternalLogger } from '../../logger/internal-logger'
 import type { DebugOption } from '../../logger/types'
-import type { GenerationMiddleware } from '../middleware/types'
+import type {
+  GenerationMiddleware,
+  GenerationRunOptions,
+} from '../middleware/types'
 import type { TTSAdapter } from './adapter'
 import type { StreamChunk, TTSResult } from '../../types'
 
@@ -54,7 +62,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 +152,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 +167,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 +191,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 +199,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 +214,7 @@ async function runGenerateSpeech<
 
   aiEventClient.emit('speech:request:started', {
     requestId,
+    ...generationIdentityFields(identity),
     provider: adapter.name,
     model,
     text: rest.text,
@@ -202,11 +231,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 +252,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 +277,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 03c6a9ed1..1d6d45b7e 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,10 @@ import {
 } from '../middleware/run'
 import type { InternalLogger } from '../../logger/internal-logger'
 import type { DebugOption } from '../../logger/types'
-import type { GenerationMiddleware } from '../middleware/types'
+import type {
+  GenerationMiddleware,
+  GenerationRunOptions,
+} from '../middleware/types'
 import type { TranscriptionAdapter } from './adapter'
 import type {
   StreamChunk,
@@ -61,7 +69,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 +179,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 +202,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 +226,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 +234,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 +249,7 @@ async function runGenerateTranscription<
 
   aiEventClient.emit('transcription:request:started', {
     requestId,
+    ...generationIdentityFields(identity),
     provider: adapter.name,
     model,
     language: rest.language,
@@ -236,11 +265,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 +298,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 1f1a5f5ea..d07e5a554 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/run'
 import type { InternalLogger } from '../../logger/internal-logger'
 import type { DebugOption } from '../../logger/types'
-import type { GenerationMiddleware } from '../middleware/types'
+import type {
+  GenerationMiddleware,
+  GenerationRunIdentity,
+  GenerationRunOptions,
+} from '../middleware/types'
 import type { VideoAdapter } from './adapter'
 import type {
   MediaPrompt,
@@ -140,58 +150,57 @@ interface VideoActivityBaseOptions<
 export type VideoCreateOptions<
   TAdapter extends VideoAdapter<string, any, any, 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>
       }
@@ -330,7 +339,22 @@ export function generateVideo<
 async function runCreateVideoJob<
   TAdapter extends VideoAdapter<string, any, any, 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()
@@ -346,6 +370,9 @@ async function runCreateVideoJob<
     provider: adapter.name,
     model,
     modelOptions,
+    threadId,
+    runId,
+    artifactInputs: { prompt, size, duration },
     createId,
   })
 
@@ -357,7 +384,7 @@ async function runCreateVideoJob<
   })
 
   try {
-    const result = await adapter.createVideoJob({
+    const rawResult = await adapter.createVideoJob({
       model,
       prompt,
       size,
@@ -365,6 +392,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,
@@ -399,6 +427,11 @@ function sleep(ms: number): Promise<void> {
 async function* runStreamingVideoGeneration<
   TAdapter extends VideoAdapter<string, any, any, 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')
@@ -412,21 +445,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,
   })
 
@@ -458,6 +529,7 @@ async function* runStreamingVideoGeneration<
       type: 'CUSTOM',
       name: 'video:job:created',
       value: { jobId: jobResult.jobId },
+      ...generationIdentityFields(identity),
       timestamp: Date.now(),
     } as StreamChunk
 
@@ -477,11 +549,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`,
@@ -503,16 +580,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
 
@@ -521,6 +606,7 @@ async function* runStreamingVideoGeneration<
           runId,
           threadId,
           finishReason: 'stop',
+          ...generationIdentityFields(identity),
           timestamp: Date.now(),
         } as StreamChunk
         return
@@ -551,6 +637,7 @@ async function* runStreamingVideoGeneration<
       type: 'RUN_ERROR',
       runId,
       threadId,
+      ...generationIdentityFields(identity),
       message: payload.message,
       code: payload.code,
       error: payload,
@@ -597,22 +684,26 @@ async function* runStreamingVideoGeneration<
  */
 export async function getVideoJobStatus<
   TAdapter extends VideoAdapter<string, any, any, 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',
@@ -629,6 +720,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',
@@ -642,6 +734,7 @@ export async function getVideoJobStatus<
       if (urlResult.usage) {
         aiEventClient.emit('video:usage', {
           requestId,
+          ...generationIdentityFields(identity),
           model: adapter.model,
           usage: urlResult.usage,
           timestamp: Date.now(),
@@ -658,6 +751,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',
@@ -679,6 +773,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..ed91759c3
--- /dev/null
+++ b/packages/ai/src/activities/generation-run.ts
@@ -0,0 +1,115 @@
+import { EventType } from '@ag-ui/core'
+import { toRunErrorPayload } from './error-payload'
+import type {
+  GenerationReplayInput,
+  GenerationRunIdentity,
+} from './middleware/types'
+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 } : {}),
+  }
+}
+
+/**
+ * Build the RUN_ERROR terminal chunk used by both the live generation path and
+ * replay. Mirrors the envelope emitted by `streamGenerationResult`'s catch: a
+ * top-level `message`/`code` plus the deprecated nested `error` form.
+ */
+function buildGenerationRunError(
+  error: unknown,
+  identity: GenerationRunIdentity,
+  fallbackMessage: string,
+): StreamChunk {
+  const payload = toRunErrorPayload(error, fallbackMessage)
+  const codeFields =
+    payload.code !== undefined ? { code: payload.code } : undefined
+  return {
+    type: EventType.RUN_ERROR,
+    ...generationIdentityFields(identity),
+    message: payload.message,
+    ...codeFields,
+    // Deprecated nested form for backward compatibility.
+    error: {
+      message: payload.message,
+      ...codeFields,
+    },
+    timestamp: Date.now(),
+  }
+}
+
+function isTerminalEvent(event: StreamChunk): boolean {
+  return (
+    event.type === EventType.RUN_FINISHED || event.type === EventType.RUN_ERROR
+  )
+}
+
+function eventIdentity(event: StreamChunk): GenerationRunIdentity {
+  return {
+    ...('runId' in event && typeof event.runId === 'string'
+      ? { runId: event.runId }
+      : {}),
+    ...('threadId' in event && typeof event.threadId === 'string'
+      ? { threadId: event.threadId }
+      : {}),
+  }
+}
+
+/**
+ * Replay persisted generation events with the same terminal guarantees as the
+ * live path, so a replayed stream always completes the StreamProcessor:
+ *
+ * - If iterating the persisted log throws (e.g. a persistence store fails
+ *   mid-read), emit a RUN_ERROR terminal instead of letting the raw error
+ *   escape uncaught.
+ * - If the log ends without a terminal event (RUN_FINISHED/RUN_ERROR) — e.g. a
+ *   run interrupted mid-persist truncated the log — synthesize a RUN_ERROR so
+ *   consumers don't hang waiting for a completion that will never come.
+ */
+export async function* replayGenerationEvents(
+  replay: GenerationReplayInput<unknown>,
+): AsyncIterable<StreamChunk> {
+  if (!replay.events) return
+  let sawTerminal = false
+  let lastIdentity: GenerationRunIdentity = {}
+  try {
+    for await (const event of replay.events) {
+      const identity = eventIdentity(event)
+      lastIdentity = { ...lastIdentity, ...identity }
+      if (isTerminalEvent(event)) sawTerminal = true
+      yield event
+    }
+  } catch (error: unknown) {
+    yield buildGenerationRunError(
+      error,
+      lastIdentity,
+      'Generation replay failed',
+    )
+    return
+  }
+  if (!sawTerminal) {
+    yield buildGenerationRunError(
+      new Error(
+        'Persisted generation replay ended before a terminal RUN_FINISHED or ' +
+          'RUN_ERROR event (the run was likely interrupted mid-persist).',
+      ),
+      lastIdentity,
+      'Generation replay truncated',
+    )
+  }
+}
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..565fcf91a 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,37 @@ 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. Replay is a pure re-emission: ALL middleware hooks are skipped
+   * (not just result transforms) and the provider is never called.
+   */
+  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 +91,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 +107,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..e8e4cfc25 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/types'
 import type { StreamChunk } from '../types'
 
 function createId(prefix: string): string {
@@ -18,31 +23,67 @@ function createId(prefix: string): string {
  * This allows non-streaming activities (image, speech, transcription, summarize)
  * to be sent over the same streaming transport as chat.
  *
- * @param generator - An async function that performs the generation and returns the result
- * @param options - Optional configuration (runId, threadId)
- * @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
+ * @param generator - Performs the generation. Receives the resolved run
+ *   options — the caller's `options` plus concrete `{ runId, threadId }` — and
+ *   returns the result. Not called on the replay path.
+ * @param options - Optional run configuration: `runId`/`threadId` identity and
+ *   an optional `replay` (persisted `events` to re-emit, or a persisted
+ *   `result` to re-wrap without calling the generator).
+ * @returns An AsyncIterable of StreamChunks. Live success yields RUN_STARTED,
+ *   an optional CUSTOM(generation:artifacts), CUSTOM(generation:result), then
+ *   RUN_FINISHED; live failure yields RUN_STARTED then RUN_ERROR. Events-based
+ *   replay re-emits the persisted events, guaranteeing a terminal RUN_ERROR if
+ *   the log throws mid-read or ends before a terminal event.
  */
 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 +92,7 @@ export async function* streamGenerationResult<TResult>(
       runId,
       threadId,
       finishReason: 'stop',
+      ...generationIdentityFields(resolvedOptions),
       timestamp: Date.now(),
     }
   } catch (error: unknown) {
@@ -63,6 +105,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..1cdd33edc
--- /dev/null
+++ b/packages/ai/src/custom-events.ts
@@ -0,0 +1,113 @@
+/**
+ * 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 events use a hyphen (not the dot convention of the other names):
+  // `approval-requested` is the frozen legacy CUSTOM wire name that the chat
+  // stream processor still consumes for replay/back-compat (see
+  // `activities/chat/stream/processor.ts`) and that the sandbox harness emits
+  // (`@tanstack/ai-sandbox` `APPROVAL_REQUESTED_EVENT`, derived from this
+  // constant). Renaming it would break replay of persisted logs.
+  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 102987c02..d407d846f 100644
--- a/packages/ai/src/index.ts
+++ b/packages/ai/src/index.ts
@@ -110,6 +110,7 @@ export type {
   ChatMiddlewareContext,
   ChatMiddlewarePhase,
   ChatMiddlewareConfig,
+  ChatResumeToolState,
   StructuredOutputMiddlewareConfig,
   ToolCallHookContext,
   BeforeToolCallDecision,
@@ -133,12 +134,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 +163,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'
 
@@ -249,6 +278,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..7dd62ba36
--- /dev/null
+++ b/packages/ai/src/locks.ts
@@ -0,0 +1,69 @@
+/**
+ * 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 an implementation from
+ * its backend) must reference the same handle. The in-memory default here is
+ * correct within a single process; whether the provided store is actually
+ * distributed depends on the backend — only a lock store backed by shared
+ * infrastructure (e.g. Cloudflare's Durable Object store) is safe across
+ * instances; most backends' stores are not.
+ */
+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. Lease-backed implementations abort `signal` as soon as ownership can
+ * no longer be guaranteed. The callback must stop starting externally visible
+ * mutations when the signal aborts and pass it to cancellable dependencies.
+ */
+export interface LockStore {
+  withLock: <T>(
+    key: string,
+    fn: (signal: AbortSignal) => Promise<T>,
+  ) => Promise<T>
+}
+
+/**
+ * The lock capability. PROVIDED by `withChatPersistence` (backed by its lock
+ * store, which is only distributed for backends like Cloudflare's Durable
+ * Object store) 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: (signal: AbortSignal) => Promise<T>,
+  ): Promise<T> {
+    const prior = this.chains.get(key) ?? Promise.resolve()
+    const runCriticalSection = () => fn(new AbortController().signal)
+    // Chain after the prior holder regardless of how it settled.
+    const run = prior.then(runCriticalSection, runCriticalSection)
+    // 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/types.ts b/packages/ai/src/types.ts
index 983e220e8..8ce417611 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,
@@ -979,6 +982,16 @@ export interface TextOptions<
    */
   parentRunId?: string
 
+  /**
+   * AG-UI interrupt resume responses supplied by the client on a follow-up run.
+   * Parsed from the request and threaded into the middleware config as `resume`.
+   * Persistence middleware consumes it (via `onConfig`) to reconstruct the run's
+   * tool state (`resumeToolState`: approvals + client tool results) from the
+   * pending interrupts, so an interrupted run can continue even when the
+   * follow-up request carries no prior message history.
+   */
+  resume?: Array<RunAgentResumeItem>
+
   /**
    * Middleware capability context for this run. The engine populates it with
    * the live middleware context so harness adapters that declare
@@ -1068,6 +1081,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.
  *
@@ -1457,9 +1476,14 @@ export interface SkillRegisteredEvent extends CustomEvent {
 }
 
 /**
- * Every CUSTOM event TanStack AI itself emits, as a discriminated union on
- * `name`. User-emitted custom events (via `emitCustomEvent` with a custom name)
- * are intentionally absent — they still flow at runtime.
+ * The typed CUSTOM events in TanStack AI's own vocabulary, as a discriminated
+ * union on `name`. Most are emitted by core today, but `ApprovalRequestedEvent`
+ * and `ToolInputAvailableEvent` are NOT — core no longer emits them; user-
+ * actionable waits now surface as `RUN_FINISHED` with `outcome.type ===
+ * 'interrupt'`. They remain in this union so they can still be consumed when
+ * replaying persisted legacy logs. User-emitted custom events (via
+ * `emitCustomEvent` with a custom name) are intentionally absent — they still
+ * flow at runtime.
  */
 export type KnownCustomEvent =
   | SandboxFileCustomEvent
@@ -1492,11 +1516,17 @@ 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` events emitted through this path:
+ * - `structured-output.start` — emitted before the schema-constrained turn
  * - `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)
+ *
+ * The union also includes `ApprovalRequestedEvent | ToolInputAvailableEvent`,
+ * but core NO LONGER emits those: user-actionable waits (tool approval, client
+ * tool input) surface as `RUN_FINISHED.outcome.type === 'interrupt'`. The two
+ * legacy custom events stay in the type only so they can be consumed when
+ * replaying persisted legacy logs — 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:
@@ -1505,8 +1535,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
  *   }
  * }
  * ```
@@ -1817,6 +1845,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
  */
@@ -1837,6 +1895,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>
 }
 
 // ============================================================================
@@ -1888,6 +1948,8 @@ export interface AudioGenerationResult {
   audio: GeneratedAudio
   /** Token usage information (if available) */
   usage?: TokenUsage
+  /** Persisted artifact references for generated assets, when available */
+  artifacts?: Array<PersistedArtifactRef>
 }
 
 // ============================================================================
@@ -1979,6 +2041,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>
 }
 
 // ============================================================================
@@ -2028,6 +2092,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>
 }
 
 // ============================================================================
@@ -2118,6 +2184,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..10e8a343f 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,223 @@ describe('chat()', () => {
 
       const chunks = await collectChunks(stream as AsyncIterable<StreamChunk>)
 
-      const approvalChunks = chunks.filter(
-        (c) => c.type === 'CUSTOM' && (c as any).name === 'approval-requested',
+      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')
+    })
+  })
+
+  // ==========================================================================
+  // Deferred tool-call RUN_FINISHED flush
+  // ==========================================================================
+  describe('deferred tool-call RUN_FINISHED flush', () => {
+    it('flushes the deferred RUN_FINISHED(tool_calls) into the output stream', async () => {
+      const executeSpy = vi.fn().mockReturnValue({ temp: 72 })
+
+      const { adapter } = createMockAdapter({
+        iterations: [
+          // First iteration ends with RUN_FINISHED(tool_calls). The engine
+          // defers this terminal so tool results can be interleaved, then
+          // flushes it before continuing the agent loop.
+          [
+            ev.runStarted(),
+            ev.toolStart('call_1', 'getWeather'),
+            ev.toolArgs('call_1', '{"city":"NYC"}'),
+            ev.runFinished('tool_calls'),
+          ],
+          [
+            ev.runStarted(),
+            ev.textStart(),
+            ev.textContent('72F in NYC.'),
+            ev.textEnd(),
+            ev.runFinished('stop'),
+          ],
+        ],
+      })
+
+      const stream = chat({
+        adapter,
+        messages: [{ role: 'user', content: 'Weather?' }],
+        tools: [serverTool('getWeather', executeSpy)],
+      })
+
+      const chunks = await collectChunks(stream as AsyncIterable<StreamChunk>)
+
+      // The deferred RUN_FINISHED(tool_calls) must be FLUSHED, not discarded.
+      // If the engine discarded it, only the final RUN_FINISHED(stop) would
+      // appear and this expectation would fail.
+      const toolCallsFinished = chunks.filter(
+        (c) =>
+          c.type === 'RUN_FINISHED' && (c as any).finishReason === 'tool_calls',
+      )
+      expect(toolCallsFinished).toHaveLength(1)
+
+      // The final terminal is still present.
+      const stopFinished = chunks.filter(
+        (c) => c.type === 'RUN_FINISHED' && (c as any).finishReason === 'stop',
+      )
+      expect(stopFinished).toHaveLength(1)
+
+      // The flushed tool_calls terminal precedes the final stop terminal.
+      const toolCallsIndex = chunks.findIndex(
+        (c) =>
+          c.type === 'RUN_FINISHED' && (c as any).finishReason === 'tool_calls',
+      )
+      const stopIndex = chunks.findIndex(
+        (c) => c.type === 'RUN_FINISHED' && (c as any).finishReason === 'stop',
+      )
+      expect(toolCallsIndex).toBeLessThan(stopIndex)
+    })
+  })
+
+  // ==========================================================================
+  // resumeToolState merge (middleware-injected approvals)
+  // ==========================================================================
+  describe('resumeToolState merge', () => {
+    it('merges middleware-injected resumeToolState.approvals into tool execution', async () => {
+      const executeSpy = vi.fn().mockReturnValue({ ok: true })
+
+      const { adapter } = createMockAdapter({
+        iterations: [
+          [
+            ev.runStarted(),
+            ev.toolStart('call_1', 'dangerousTool'),
+            ev.toolArgs('call_1', '{}'),
+            ev.runFinished('tool_calls'),
+          ],
+          [
+            ev.runStarted(),
+            ev.textStart(),
+            ev.textContent('done'),
+            ev.textEnd(),
+            ev.runFinished('stop'),
+          ],
+        ],
+      })
+
+      const stream = chat({
+        adapter,
+        messages: [{ role: 'user', content: 'go' }],
+        tools: [
+          { ...serverTool('dangerousTool', executeSpy), needsApproval: true },
+        ],
+        // Middleware reconstructs an approval decision (as persistence
+        // middleware does from resume entries) and injects it via onConfig.
+        // The approvals map is keyed by `approval_${toolCallId}`.
+        middleware: [
+          {
+            onConfig: () => ({
+              resumeToolState: {
+                approvals: new Map([['approval_call_1', true]]),
+              },
+            }),
+          },
+        ],
+      })
+
+      const chunks = await collectChunks(stream as AsyncIterable<StreamChunk>)
+
+      // The injected approval must flow through applyMiddlewareConfig →
+      // resumeApprovals → collectClientState so the needsApproval tool
+      // executes instead of interrupting for approval.
+      expect(executeSpy).toHaveBeenCalledTimes(1)
+
+      // The run completes normally — no approval interrupt outcome.
+      const interrupts = chunks.filter(
+        (c) =>
+          c.type === 'RUN_FINISHED' && (c as any).outcome?.type === 'interrupt',
       )
-      expect(approvalChunks).toHaveLength(1)
+      expect(interrupts).toHaveLength(0)
     })
   })
 
diff --git a/packages/ai/tests/custom-events.test.ts b/packages/ai/tests/custom-events.test.ts
new file mode 100644
index 000000000..23d5ef18d
--- /dev/null
+++ b/packages/ai/tests/custom-events.test.ts
@@ -0,0 +1,70 @@
+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')
+  })
+
+  it('pins APPROVAL_REQUESTED to the wire name the chat stream processor consumes', () => {
+    // The processor's legacy/replay branch matches this exact string
+    // (activities/chat/stream/processor.ts). If the catalog drifts from the
+    // wire name, `isCustomEvent(chunk, CUSTOM_EVENT.APPROVAL_REQUESTED)` and
+    // replay of persisted approval logs both silently stop matching.
+    expect(CUSTOM_EVENT.APPROVAL_REQUESTED).toBe('approval-requested')
+
+    // A CUSTOM chunk carrying the wire name is recognized via the catalog
+    // constant — the emitter/consumer agreement the catalog exists to enforce.
+    const emitted: StreamChunk = {
+      type: EventType.CUSTOM,
+      name: 'approval-requested',
+      value: { approvalId: 'a1', title: 'Run build' },
+      timestamp: 1,
+    }
+    expect(isCustomEvent(emitted, CUSTOM_EVENT.APPROVAL_REQUESTED)).toBe(true)
+  })
+})
+
+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..04b913e65
--- /dev/null
+++ b/packages/ai/tests/generation-run-identity-replay.test.ts
@@ -0,0 +1,634 @@
+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('emits a RUN_ERROR terminal when replaying events throws mid-iteration', 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 firstEvent: StreamChunk = {
+      type: EventType.CUSTOM,
+      name: 'generation:result',
+      value: { id: 'persisted-image', model: 'test-model', images: [] },
+      runId: 'run-throw',
+      threadId: 'thread-throw',
+    }
+    async function* throwingEvents(): AsyncIterable<StreamChunk> {
+      yield firstEvent
+      // Simulate a persistence store failing partway through the log read.
+      throw new Error('store exploded')
+    }
+
+    const chunks = await collect(
+      generateImage({
+        adapter,
+        prompt: 'ignored',
+        stream: true,
+        replay: { events: throwingEvents() },
+      }),
+    )
+
+    expect(adapter.generateImages).not.toHaveBeenCalled()
+    // The already-yielded event is preserved, then a RUN_ERROR terminal is
+    // synthesized instead of the raw error escaping the stream.
+    expect(chunks[0]).toEqual(firstEvent)
+    const terminal = chunks[chunks.length - 1]!
+    expect(terminal.type).toBe(EventType.RUN_ERROR)
+    expect((terminal as { message?: string }).message).toContain(
+      'store exploded',
+    )
+    // Identity is carried from the last replayed event so consumers correlate.
+    expect((terminal as { runId?: string }).runId).toBe('run-throw')
+    expect((terminal as { threadId?: string }).threadId).toBe('thread-throw')
+  })
+
+  it('synthesizes a RUN_ERROR terminal when a replayed log ends before a terminal event', 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')
+      }),
+    }
+    // A run interrupted mid-persist leaves a log with no RUN_FINISHED/RUN_ERROR.
+    const truncatedEvents = [
+      {
+        type: EventType.RUN_STARTED,
+        runId: 'run-trunc',
+        threadId: 'thread-trunc',
+      },
+      {
+        type: EventType.CUSTOM,
+        name: 'generation:result',
+        value: { id: 'persisted-image', model: 'test-model', images: [] },
+        runId: 'run-trunc',
+        threadId: 'thread-trunc',
+      },
+    ] satisfies Array<StreamChunk>
+
+    const chunks = await collect(
+      generateImage({
+        adapter,
+        prompt: 'ignored',
+        stream: true,
+        replay: { events: truncatedEvents },
+      }),
+    )
+
+    expect(adapter.generateImages).not.toHaveBeenCalled()
+    // Persisted events are re-emitted verbatim...
+    expect(chunks.slice(0, truncatedEvents.length)).toEqual(truncatedEvents)
+    // ...then a synthesized RUN_ERROR terminal completes the stream so the
+    // StreamProcessor doesn't hang waiting for a terminal that never persisted.
+    expect(chunks).toHaveLength(truncatedEvents.length + 1)
+    const terminal = chunks[chunks.length - 1]!
+    expect(terminal.type).toBe(EventType.RUN_ERROR)
+    expect((terminal as { message?: string }).message).toMatch(
+      /ended before a terminal/i,
+    )
+    expect((terminal as { runId?: string }).runId).toBe('run-trunc')
+    expect((terminal as { threadId?: string }).threadId).toBe('thread-trunc')
+  })
+
+  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..a0911b250
--- /dev/null
+++ b/packages/ai/tests/locks.test.ts
@@ -0,0 +1,100 @@
+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')
+  })
+
+  it('provides a live lease signal to the critical section', async () => {
+    const store = new InMemoryLockStore()
+
+    await expect(
+      store.withLock('k', async (signal) => {
+        expect(signal).toBeInstanceOf(AbortSignal)
+        expect(signal.aborted).toBe(false)
+        return '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-processor.test.ts b/packages/ai/tests/stream-processor.test.ts
index 4921f7e2f..d9bb3827b 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'
@@ -1186,6 +1194,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 })
@@ -2042,6 +2173,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/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 e006a80cf..9417c163c 100644
--- a/pnpm-lock.yaml
+++ b/pnpm-lock.yaml
@@ -23,6 +23,9 @@ importers:
       '@changesets/cli':
         specifier: ^2.30.0
         version: 2.30.0(@types/node@24.10.3)
+      '@cloudflare/workers-types':
+        specifier: ^4.20260317.1
+        version: 4.20260317.1
       '@faker-js/faker':
         specifier: ^10.1.0
         version: 10.1.0
@@ -176,7 +179,7 @@ importers:
     devDependencies:
       '@cloudflare/vite-plugin':
         specifier: ^1.42.1
-        version: 1.42.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))(workerd@1.20260617.1)(wrangler@4.103.0)
+        version: 1.42.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))(workerd@1.20260617.1)(wrangler@4.103.0(@cloudflare/workers-types@4.20260317.1))
       '@tailwindcss/vite':
         specifier: ^4.1.18
         version: 4.1.18(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))
@@ -303,7 +306,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 +424,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 +673,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 +702,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 +838,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 +975,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(@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)))(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(@cloudflare/workers-types@4.20260317.1))
       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 +1075,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 +1321,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
@@ -1503,6 +1512,9 @@ importers:
       '@vitest/coverage-v8':
         specifier: 4.0.14
         version: 4.0.14(vitest@4.1.4)
+      fake-indexeddb:
+        specifier: ^6.2.5
+        version: 6.2.5
       vite:
         specifier: ^7.3.3
         version: 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)
@@ -1971,6 +1983,78 @@ importers:
         specifier: ^4.2.0
         version: 4.3.6
 
+  packages/ai-persistence:
+    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-cloudflare:
+    devDependencies:
+      '@cloudflare/workers-types':
+        specifier: ^4.20260317.1
+        version: 4.20260317.1
+      '@tanstack/ai':
+        specifier: workspace:*
+        version: link:../ai
+      '@tanstack/ai-persistence':
+        specifier: workspace:*
+        version: link:../ai-persistence
+      '@tanstack/ai-persistence-drizzle':
+        specifier: workspace:*
+        version: link:../ai-persistence-drizzle
+      '@vitest/coverage-v8':
+        specifier: 4.0.14
+        version: 4.0.14(vitest@4.1.4)
+      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))
+      miniflare:
+        specifier: ^4.20260609.0
+        version: 4.20260617.1
+
+  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 +2169,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 +2605,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 +2619,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 +2731,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 +2740,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 +2842,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 +3944,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 +3984,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.hirok.io'
+
+  '@esbuild-kit/esm-loader@2.6.5':
+    resolution: {integrity: sha512-FxEMIkJKnodyA1OaCUoEvbYRkoZlLZ4d/eXFu9Fh8CbBBgP5EmZxrfTRyN0qpXZ4vOvqnE5YdRdcrmUUXuU+dA==}
+    deprecated: 'Merged into tsx: https://tsx.hirok.io'
+
   '@esbuild/aix-ppc64@0.20.2':
     resolution: {integrity: sha512-D+EBOJHXdNZcLJRBkhENNG8Wji2kgc9AZ9KiPr1JuZjsNtyHzrsfLRrY0tk2H2aoFu6RANO1y1iPPUCDYWkb5g==}
     engines: {node: '>=12'}
@@ -3921,6 +4022,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 +4058,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 +4094,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 +4130,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 +4166,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 +4202,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 +4238,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 +4274,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 +4310,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 +4346,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 +4382,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 +4418,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 +4454,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 +4490,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 +4526,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 +4562,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 +4622,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 +4682,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 +4742,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 +4778,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 +4814,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 +4850,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 +6629,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 +9194,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 +9877,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 +10151,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 +10738,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 +10882,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 +11008,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 +11131,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 +11471,14 @@ packages:
     engines: {node: '>= 10.17.0'}
     hasBin: true
 
+  fake-indexeddb@6.2.5:
+    resolution: {integrity: sha512-CGnyrvbhPlWYMngksqrSSUT1BAVP49dZocrHuK0SvtR0D5TMs5wP0o3j7jexDJW01KSadjBp1M/71o/KR3nD1w==}
+    engines: {node: '>=18'}
+
+  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 +11725,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 +12066,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 +12285,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 +12849,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 +13330,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 +13864,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 +14013,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,11 +14076,21 @@ 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}
 
-  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}
-
-  process-nextick-args@2.0.1:
+  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}
+
+  process-nextick-args@2.0.1:
     resolution: {integrity: sha512-3ouUOpQhtgrbOa17J7+uxOTpITYWaGP7/AhoR3+A+/1e9skrzelGi/dXzEYyvbxubEF6Wn2ypscTKiKJFFn1ag==}
 
   process@0.11.10:
@@ -13698,6 +14175,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 +14926,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 +16405,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 +16499,7 @@ snapshots:
 
   '@acemir/cssom@0.9.29': {}
 
-  '@ag-ui/core@0.0.52':
+  '@ag-ui/core@0.0.57':
     dependencies:
       zod: 3.25.76
 
@@ -17638,7 +18130,7 @@ snapshots:
     optionalDependencies:
       workerd: 1.20260617.1
 
-  '@cloudflare/vite-plugin@1.42.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))(workerd@1.20260617.1)(wrangler@4.103.0)':
+  '@cloudflare/vite-plugin@1.42.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))(workerd@1.20260617.1)(wrangler@4.103.0(@cloudflare/workers-types@4.20260317.1))':
     dependencies:
       '@cloudflare/unenv-preset': 2.16.1(unenv@2.0.0-rc.24)(workerd@1.20260617.1)
       miniflare: 4.20260617.1
@@ -17778,6 +18270,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,6 +18336,16 @@ snapshots:
       tslib: 2.8.1
     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
 
@@ -17857,6 +18361,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 +18379,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 +18397,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 +18415,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 +18433,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 +18451,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 +18469,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 +18487,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 +18505,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 +18523,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 +18541,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 +18559,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 +18577,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 +18595,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 +18613,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 +18631,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 +18661,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 +18691,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 +18721,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 +18739,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 +18757,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 +18775,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 +20568,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 +22469,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)(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)
+      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)(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 +22642,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 +22684,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 +23159,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 +23235,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 +23303,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 +23319,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 +23555,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 +23848,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 +24721,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 +25080,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 +25611,10 @@ 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(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 +25663,8 @@ snapshots:
 
   deep-is@0.1.4: {}
 
+  deepmerge-ts@7.1.5: {}
+
   deepmerge@4.3.1: {}
 
   defaults@1.0.4:
@@ -25120,6 +25793,23 @@ 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(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 +25837,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: {}
@@ -25190,7 +25885,7 @@ snapshots:
 
   env-paths@2.2.1: {}
 
-  env-runner@0.1.14(miniflare@4.20260617.1)(wrangler@4.103.0):
+  env-runner@0.1.14(miniflare@4.20260617.1)(wrangler@4.103.0(@cloudflare/workers-types@4.20260317.1)):
     dependencies:
       crossws: 0.4.6(srvx@0.11.17)
       exsolve: 1.0.8
@@ -25258,6 +25953,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 +26537,12 @@ snapshots:
     transitivePeerDependencies:
       - supports-color
 
+  fake-indexeddb@6.2.5: {}
+
+  fast-check@3.23.2:
+    dependencies:
+      pure-rand: 6.1.0
+
   fast-deep-equal@3.1.3: {}
 
   fast-equals@5.4.0: {}
@@ -26054,6 +26780,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 +27233,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 +27430,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 +28051,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 +28836,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 +28919,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(@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))
       h3: 2.0.1-rc.22(crossws@0.4.6(srvx@0.10.1))
       jiti: 2.6.1
       nf3: 0.3.17
@@ -28174,7 +28934,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(@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)))(ofetch@2.0.0-alpha.3)
     optionalDependencies:
       rolldown: 1.1.3
       rollup: 4.60.1
@@ -28210,12 +28970,12 @@ 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(@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)))(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(@cloudflare/workers-types@4.20260317.1)):
     dependencies:
       consola: 3.4.2
       crossws: 0.4.6(srvx@0.11.17)
-      db0: 0.3.4
-      env-runner: 0.1.14(miniflare@4.20260617.1)(wrangler@4.103.0)
+      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))
+      env-runner: 0.1.14(miniflare@4.20260617.1)(wrangler@4.103.0(@cloudflare/workers-types@4.20260317.1))
       h3: 2.0.1-rc.22(crossws@0.4.6(srvx@0.11.17))
       hookable: 6.1.1
       nf3: 0.3.17
@@ -28225,7 +28985,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(@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)))(ofetch@2.0.0-alpha.3)
     optionalDependencies:
       dotenv: 17.2.3
       giget: 2.0.0
@@ -28264,7 +29024,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 +29045,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(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
@@ -28331,7 +29091,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 +29126,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(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
+      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 +29249,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(@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))
       defu: 6.1.4
       destr: 2.0.5
       dot-prop: 10.1.0
@@ -28433,7 +29295,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 +29830,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 +29965,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 +30016,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 +30173,8 @@ snapshots:
       - typescript
       - utf-8-validate
 
+  pure-rand@6.1.0: {}
+
   qs@6.14.0:
     dependencies:
       side-channel: 1.1.0
@@ -30310,8 +31235,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 +31991,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 +32003,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(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.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(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@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 +32033,14 @@ 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(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(@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)))(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(@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))
       ofetch: 2.0.0-alpha.3
 
   untun@0.1.3:
@@ -31204,7 +32150,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 +32172,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 +32183,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 +32340,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 +32359,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 +32738,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 0a9b1e81a..15bd90fb1 100644
--- a/testing/e2e/src/lib/media-providers.ts
+++ b/testing/e2e/src/lib/media-providers.ts
@@ -62,7 +62,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),
@@ -89,7 +89,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),
@@ -123,7 +123,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),
@@ -158,6 +158,10 @@ export function createVideoAdapter(
   feature: Feature = 'video-gen',
 ) {
   const headers = testHeaders(testId)
+  const geminiConfig = (baseUrl: string) => ({
+    allowUrlFetch: false,
+    httpOptions: { baseUrl, headers },
+  })
   // Gemini Omni Flash only serves the Interactions API; its background
   // video jobs run through a dedicated aimock mount (see geminiOmniVideoMount
   // in global-setup.ts) addressed via a distinct baseUrl prefix so aimock's
@@ -166,25 +170,24 @@ export function createVideoAdapter(
     if (provider !== 'gemini') {
       throw new Error(`No interactions-video adapter for provider: ${provider}`)
     }
-    return createGeminiVideo('gemini-omni-flash-preview', DUMMY_KEY, {
-      httpOptions: { baseUrl: `${llmockBase(aimockPort)}/omni-video`, headers },
-    })
+    return createGeminiVideo(
+      'gemini-omni-flash-preview',
+      DUMMY_KEY,
+      geminiConfig(`${llmockBase(aimockPort)}/omni-video`),
+    )
   }
-  const factories: Record<string, () => any> = {
+  const factories: Partial<Record<Provider, () => any>> = {
     openai: () =>
       createOpenaiVideo('sora-2', DUMMY_KEY, {
         baseURL: openaiUrl(aimockPort),
         defaultHeaders: headers,
       }),
     gemini: () =>
-      // `httpOptions` is a valid inherited `GoogleGenAIOptions` key (image/audio
-      // pass it the same way), but `GeminiVideoConfig`'s own `allowUrlFetch`
-      // member makes tsc drop the inherited keys from `Omit<…, 'apiKey'>`, so
-      // the literal is rejected here only. Cast to the param type — the mock
-      // base URL is required at runtime.
-      createGeminiVideo('veo-3.1-generate-preview', DUMMY_KEY, {
-        httpOptions: { baseUrl: llmockBase(aimockPort), headers },
-      } as unknown as Parameters<typeof createGeminiVideo>[2]),
+      createGeminiVideo(
+        'veo-3.1-generate-preview',
+        DUMMY_KEY,
+        geminiConfig(llmockBase(aimockPort)),
+      ),
   }
   const factory = factories[provider]
   if (!factory) throw new Error(`No video adapter for provider: ${provider}`)
@@ -211,7 +214,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/routes/$provider/$feature.tsx b/testing/e2e/src/routes/$provider/$feature.tsx
index 8846161f6..dddc1a777 100644
--- a/testing/e2e/src/routes/$provider/$feature.tsx
+++ b/testing/e2e/src/routes/$provider/$feature.tsx
@@ -2,8 +2,12 @@ import { 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 { clientTools, localStoragePersistence } from '@tanstack/ai-client'
+import type {
+  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 +27,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 +42,10 @@ export const Route = createFileRoute('/$provider/$feature')({
           : undefined,
       persistence:
         search.persistence === 'localStorage' ? 'localStorage' : undefined,
+      serverPersistence:
+        search.serverPersistence === true ||
+        search.serverPersistence === 1 ||
+        search.serverPersistence === '1',
     }
   },
 })
@@ -60,31 +70,115 @@ const addToCartClient = addToCartToolDef.client((args) => ({
   quantity: args.quantity,
 }))
 
-const localStoragePersistence: ChatClientPersistence = {
-  getItem: (id) => {
-    const item = window.localStorage.getItem(id)
-    return item
-      ? (JSON.parse(item) as Array<UIMessage>).map((message) => ({
-          ...message,
-          createdAt:
-            typeof message.createdAt === 'string'
-              ? new Date(message.createdAt)
-              : message.createdAt,
-        }))
-      : null
-  },
-  setItem: (id, messages) => {
-    window.localStorage.setItem(id, JSON.stringify(messages))
-  },
-  removeItem: (id) => {
-    window.localStorage.removeItem(id)
-  },
+type StoredUIMessage = Omit<UIMessage, 'createdAt'> & {
+  createdAt?: Date | string
+}
+
+function serializeJson(value: unknown): string {
+  const serialized = JSON.stringify(value)
+  if (serialized === undefined) {
+    throw new TypeError('The persistence value is not JSON serializable')
+  }
+  return serialized
 }
 
 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 isStoredUIMessage(value: unknown): value is StoredUIMessage {
+  return (
+    isRecord(value) &&
+    typeof value.id === 'string' &&
+    (value.role === 'system' ||
+      value.role === 'user' ||
+      value.role === 'assistant') &&
+    Array.isArray(value.parts) &&
+    (value.createdAt === undefined ||
+      value.createdAt instanceof Date ||
+      typeof value.createdAt === 'string')
+  )
+}
+
+function deserializeMessages(raw: string): Array<UIMessage> {
+  const parsed: unknown = JSON.parse(raw)
+  if (!Array.isArray(parsed) || !parsed.every(isStoredUIMessage)) {
+    throw new TypeError('Stored messages are invalid')
+  }
+  return parsed.map(({ createdAt, ...message }) => ({
+    ...message,
+    ...(createdAt
+      ? {
+          createdAt:
+            createdAt instanceof Date ? createdAt : new Date(createdAt),
+        }
+      : {}),
+  }))
+}
+
+function parsePendingInterrupts(value: unknown): Array<ChatPendingInterrupt> {
+  if (!Array.isArray(value)) return []
+
+  const interrupts: Array<ChatPendingInterrupt> = []
+  for (const item of value) {
+    if (!isRecord(item)) continue
+    const interrupt = item
+    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 deserializeResumeSnapshot(raw: string): ChatResumeSnapshot {
+  const parsed: unknown = JSON.parse(raw)
+  if (!isRecord(parsed)) {
+    throw new TypeError('Stored resume snapshot is invalid')
+  }
+  const value = parsed
+  const resumeState = isRecord(value.resumeState) ? value.resumeState : value
+
+  if (
+    typeof resumeState.threadId !== 'string' ||
+    typeof resumeState.runId !== 'string'
+  ) {
+    throw new TypeError('Stored resume state is invalid')
+  }
+
+  return {
+    resumeState: {
+      threadId: resumeState.threadId,
+      runId: resumeState.runId,
+    },
+    pendingInterrupts: parsePendingInterrupts(value.pendingInterrupts),
+  }
+}
+
+const messagePersistence = localStoragePersistence<Array<UIMessage>>({
+  keyPrefix: '',
+  serialize: serializeJson,
+  deserialize: deserializeMessages,
+})
+
+const resumePersistence = localStoragePersistence<ChatResumeSnapshot>({
+  keyPrefix: 'tanstack-ai:e2e:resume:',
+  serialize: serializeJson,
+  deserialize: deserializeResumeSnapshot,
+})
 
 function FeaturePage() {
   const { provider, feature } = Route.useParams()
@@ -226,8 +320,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
@@ -254,6 +350,7 @@ function ChatFeature({
               data?: unknown
               threadId: string
               runId: string
+              resume?: Array<unknown>
             },
             options: { signal: AbortSignal },
           ) =>
@@ -280,6 +377,7 @@ function ChatFeature({
                 tools: [],
                 context: [],
                 forwardedProps: input.data,
+                ...(input.resume ? { resume: input.resume } : {}),
               }),
               signal: options.signal,
             }),
@@ -291,10 +389,13 @@ function ChatFeature({
     sendMessage,
     isLoading,
     addToolApprovalResponse,
+    resumeState,
+    pendingInterrupts,
     stop,
     clear,
   } = useChat({
     id: chatId,
+    threadId: chatId,
     ...transport,
     tools,
     body: {
@@ -303,9 +404,15 @@ function ChatFeature({
       testId,
       aimockPort,
       previousInteractionId: interactionId,
+      serverPersistence: serverPersistenceEnabled,
     },
     persistence:
-      persistence === 'localStorage' ? localStoragePersistence : undefined,
+      persistenceEnabled || serverPersistenceEnabled
+        ? {
+            client: messagePersistence,
+            ...(serverPersistenceEnabled ? { server: resumePersistence } : {}),
+          }
+        : undefined,
     onCustomEvent: (eventType, data) => {
       if (eventType === 'structured-output.complete') {
         const value = data as { object: unknown; raw: string } | undefined
@@ -326,6 +433,19 @@ function ChatFeature({
 
   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}
@@ -387,6 +507,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..0533f7d8f 100644
--- a/testing/e2e/src/routes/api.chat.ts
+++ b/testing/e2e/src/routes/api.chat.ts
@@ -6,12 +6,39 @@ import {
   toServerSentEventsResponse,
 } from '@tanstack/ai'
 import type { StreamChunk } from '@tanstack/ai'
+import {
+  composePersistence,
+  memoryPersistence,
+  withChatPersistence,
+} 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.'
+type TestPersistence = ReturnType<typeof createTestPersistence>
+
+const persistenceByTestId = new Map<string, TestPersistence>()
+
+function createTestPersistence() {
+  return composePersistence(memoryPersistence(), {
+    overrides: {
+      metadata: false,
+      locks: false,
+    },
+  })
+}
+
+function getPersistence(testId: string | undefined): TestPersistence {
+  const key = testId ?? '__default__'
+  let persistence = persistenceByTestId.get(key)
+  if (!persistence) {
+    persistence = createTestPersistence()
+    persistenceByTestId.set(key, persistence)
+  }
+  return persistence
+}
 
 export const Route = createFileRoute('/api/chat')({
   server: {
@@ -48,6 +75,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 +96,9 @@ export const Route = createFileRoute('/api/chat')({
 
         try {
           const systemPrompt = config.systemPrompt ?? DEFAULT_SYSTEM_PROMPT
+          const middleware = serverPersistence
+            ? [withChatPersistence(getPersistence(testId))]
+            : undefined
 
           // Test-only flag — when truthy, the route promotes the system
           // prompt to object-form and attaches Anthropic `cache_control`
@@ -119,6 +150,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 +164,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 +180,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 +195,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.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 05c5b74f1..2fc7acffe 100644
--- a/testing/e2e/src/routes/api.video.stream.ts
+++ b/testing/e2e/src/routes/api.video.stream.ts
@@ -1,7 +1,7 @@
 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 { createVideoAdapter } from '@/lib/media-providers'
 import type { Feature, Provider } from '@/lib/types'
 
 export const Route = createFileRoute('/api/video/stream')({
@@ -28,15 +28,19 @@ export const Route = createFileRoute('/api/video/stream')({
         )
 
         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 83ceec707..5b4d6431c 100644
--- a/testing/e2e/src/routes/api.video.ts
+++ b/testing/e2e/src/routes/api.video.ts
@@ -1,7 +1,11 @@
 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 { createVideoAdapter } from '@/lib/media-providers'
 import type { Feature, Provider } from '@/lib/types'
 
 export const Route = createFileRoute('/api/video')({
@@ -28,15 +32,19 @@ export const Route = createFileRoute('/api/video')({
         )
 
         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/tool-approval.spec.ts b/testing/e2e/tests/tool-approval.spec.ts
index 4af029661..2197e995a 100644
--- a/testing/e2e/tests/tool-approval.spec.ts
+++ b/testing/e2e/tests/tool-approval.spec.ts
@@ -29,6 +29,88 @@ 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('approval interrupt survives reload and denial completes the run without executing the tool', async ({
+      page,
+      testId,
+      aimockPort,
+    }) => {
+      await page.goto(
+        `${featureUrl(provider, 'tool-approval', testId, aimockPort)}&serverPersistence=1`,
+      )
+
+      await sendMessage(page, '[approval-deny] 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()
+
+      // The persisted approval interrupt is restored after reload.
+      await expect(page.getByTestId('approval-prompt-addToCart')).toBeVisible({
+        timeout: 20_000,
+      })
+      await expect(page.getByTestId('pending-interrupt-count')).toHaveAttribute(
+        'data-count',
+        '1',
+      )
+
+      await denyToolCall(page, 'addToCart')
+
+      // The run resumes and completes with the denial reflected in the reply.
+      // The addToCart client tool is never executed (its result would read
+      // "added to your cart"); the assistant instead acknowledges the denial.
+      await waitForAssistantText(page, "won't add")
+
+      // The interrupt is resolved and gone: prompt hidden, count back to zero.
+      await expect(
+        page.getByTestId('approval-prompt-addToCart'),
+      ).not.toBeVisible({ timeout: 10_000 })
+      await expect(page.getByTestId('pending-interrupt-count')).toHaveAttribute(
+        'data-count',
+        '0',
+      )
+    })
+
     test('follow-up message after approval does not produce empty tool_use.name (issue #532)', async ({
       page,
       testId,