diff --git a/docs/reference/classes/StreamProcessor.md b/docs/reference/classes/StreamProcessor.md
index d523262a12..68d03d2c2c 100644
--- a/docs/reference/classes/StreamProcessor.md
+++ b/docs/reference/classes/StreamProcessor.md
@@ -3,7 +3,7 @@ id: StreamProcessor
 title: StreamProcessor
 ---
 
-Defined in: [packages/ai/src/activities/chat/stream/processor.ts:237](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/stream/processor.ts#L237)
+Defined in: [packages/ai/src/activities/chat/stream/processor.ts:238](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/stream/processor.ts#L238)
 
 StreamProcessor - State machine for processing AI response streams
 
@@ -30,7 +30,7 @@ State tracking:
 new StreamProcessor(options?): StreamProcessor;
 ```
 
-Defined in: [packages/ai/src/activities/chat/stream/processor.ts:306](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/stream/processor.ts#L306)
+Defined in: [packages/ai/src/activities/chat/stream/processor.ts:307](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/stream/processor.ts#L307)
 
 #### Parameters
 
@@ -50,7 +50,7 @@ Defined in: [packages/ai/src/activities/chat/stream/processor.ts:306](https://gi
 addToolApprovalResponse(approvalId, approved): void;
 ```
 
-Defined in: [packages/ai/src/activities/chat/stream/processor.ts:498](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/stream/processor.ts#L498)
+Defined in: [packages/ai/src/activities/chat/stream/processor.ts:499](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/stream/processor.ts#L499)
 
 Add an approval response (called by client after handling onApprovalRequest)
 
@@ -79,7 +79,7 @@ addToolResult(
    error?): void;
 ```
 
-Defined in: [packages/ai/src/activities/chat/stream/processor.ts:447](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/stream/processor.ts#L447)
+Defined in: [packages/ai/src/activities/chat/stream/processor.ts:448](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/stream/processor.ts#L448)
 
 Add a tool result (called by client after handling onToolCall)
 
@@ -112,7 +112,7 @@ addUserMessage(
    metadata?): UIMessage;
 ```
 
-Defined in: [packages/ai/src/activities/chat/stream/processor.ts:386](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/stream/processor.ts#L386)
+Defined in: [packages/ai/src/activities/chat/stream/processor.ts:387](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/stream/processor.ts#L387)
 
 Add a user message to the conversation.
 Supports both simple string content and multimodal content arrays.
@@ -167,7 +167,7 @@ processor.addUserMessage('Hello!', 'custom-id-123')
 areAllToolsComplete(): boolean;
 ```
 
-Defined in: [packages/ai/src/activities/chat/stream/processor.ts:538](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/stream/processor.ts#L538)
+Defined in: [packages/ai/src/activities/chat/stream/processor.ts:539](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/stream/processor.ts#L539)
 
 Check if all tool calls in the last assistant message are complete
 Useful for auto-continue logic
@@ -184,7 +184,7 @@ Useful for auto-continue logic
 clearMessages(): void;
 ```
 
-Defined in: [packages/ai/src/activities/chat/stream/processor.ts:628](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/stream/processor.ts#L628)
+Defined in: [packages/ai/src/activities/chat/stream/processor.ts:629](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/stream/processor.ts#L629)
 
 Clear all messages
 
@@ -200,7 +200,7 @@ Clear all messages
 finalizeStream(): void;
 ```
 
-Defined in: [packages/ai/src/activities/chat/stream/processor.ts:3454](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/stream/processor.ts#L3454)
+Defined in: [packages/ai/src/activities/chat/stream/processor.ts:3478](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/stream/processor.ts#L3478)
 
 Finalize the stream — complete all pending operations.
 
@@ -224,7 +224,7 @@ docs/chat-architecture.md#single-shot-text-response — Finalization step
 getCurrentAssistantMessageId(): string | null;
 ```
 
-Defined in: [packages/ai/src/activities/chat/stream/processor.ts:431](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/stream/processor.ts#L431)
+Defined in: [packages/ai/src/activities/chat/stream/processor.ts:432](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/stream/processor.ts#L432)
 
 Get the current assistant message ID (if one has been created).
 Returns null if prepareAssistantMessage() was called but no content
@@ -242,7 +242,7 @@ has arrived yet.
 getMessages(): UIMessage<unknown>[];
 ```
 
-Defined in: [packages/ai/src/activities/chat/stream/processor.ts:530](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/stream/processor.ts#L530)
+Defined in: [packages/ai/src/activities/chat/stream/processor.ts:531](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/stream/processor.ts#L531)
 
 Get current messages
 
@@ -258,7 +258,7 @@ Get current messages
 getRecording(): ChunkRecording | null;
 ```
 
-Defined in: [packages/ai/src/activities/chat/stream/processor.ts:3626](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/stream/processor.ts#L3626)
+Defined in: [packages/ai/src/activities/chat/stream/processor.ts:3650](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/stream/processor.ts#L3650)
 
 Get the current recording
 
@@ -274,7 +274,7 @@ Get the current recording
 getState(): ProcessorState;
 ```
 
-Defined in: [packages/ai/src/activities/chat/stream/processor.ts:3583](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/stream/processor.ts#L3583)
+Defined in: [packages/ai/src/activities/chat/stream/processor.ts:3607](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/stream/processor.ts#L3607)
 
 Get current processor state (aggregated across all messages)
 
@@ -290,7 +290,7 @@ Get current processor state (aggregated across all messages)
 prepareAssistantMessage(): void;
 ```
 
-Defined in: [packages/ai/src/activities/chat/stream/processor.ts:421](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/stream/processor.ts#L421)
+Defined in: [packages/ai/src/activities/chat/stream/processor.ts:422](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/stream/processor.ts#L422)
 
 Prepare for a new assistant message stream.
 Does NOT create the message immediately -- the message is created lazily
@@ -310,7 +310,7 @@ auto-continuation produces no content.
 prependMessages(messages): void;
 ```
 
-Defined in: [packages/ai/src/activities/chat/stream/processor.ts:347](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/stream/processor.ts#L347)
+Defined in: [packages/ai/src/activities/chat/stream/processor.ts:348](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/stream/processor.ts#L348)
 
 Put older UI messages at the front of the conversation.
 
@@ -346,7 +346,7 @@ processor.prependMessages([oldest])
 process(stream): Promise<ProcessorResult>;
 ```
 
-Defined in: [packages/ai/src/activities/chat/stream/processor.ts:654](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/stream/processor.ts#L654)
+Defined in: [packages/ai/src/activities/chat/stream/processor.ts:655](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/stream/processor.ts#L655)
 
 Process a stream and emit events through handlers
 
@@ -368,7 +368,7 @@ Process a stream and emit events through handlers
 processChunk(chunk): void;
 ```
 
-Defined in: [packages/ai/src/activities/chat/stream/processor.ts:688](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/stream/processor.ts#L688)
+Defined in: [packages/ai/src/activities/chat/stream/processor.ts:689](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/stream/processor.ts#L689)
 
 Process a single chunk from the stream.
 
@@ -398,7 +398,7 @@ docs/chat-architecture.md#adapter-contract — Expected event types and ordering
 removeMessagesAfter(index): void;
 ```
 
-Defined in: [packages/ai/src/activities/chat/stream/processor.ts:578](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/stream/processor.ts#L578)
+Defined in: [packages/ai/src/activities/chat/stream/processor.ts:579](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/stream/processor.ts#L579)
 
 Remove messages after a certain index (for reload/retry)
 
@@ -420,7 +420,7 @@ Remove messages after a certain index (for reload/retry)
 reset(): void;
 ```
 
-Defined in: [packages/ai/src/activities/chat/stream/processor.ts:3657](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/stream/processor.ts#L3657)
+Defined in: [packages/ai/src/activities/chat/stream/processor.ts:3681](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/stream/processor.ts#L3681)
 
 Full reset (including messages)
 
@@ -436,7 +436,7 @@ Full reset (including messages)
 setMessages(messages): void;
 ```
 
-Defined in: [packages/ai/src/activities/chat/stream/processor.ts:326](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/stream/processor.ts#L326)
+Defined in: [packages/ai/src/activities/chat/stream/processor.ts:327](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/stream/processor.ts#L327)
 
 Set the messages array (e.g., from persisted state)
 
@@ -458,7 +458,7 @@ Set the messages array (e.g., from persisted state)
 startRecording(): void;
 ```
 
-Defined in: [packages/ai/src/activities/chat/stream/processor.ts:3613](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/stream/processor.ts#L3613)
+Defined in: [packages/ai/src/activities/chat/stream/processor.ts:3637](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/stream/processor.ts#L3637)
 
 Start recording chunks
 
@@ -477,7 +477,7 @@ toModelMessages(): ModelMessage<
   | null>[];
 ```
 
-Defined in: [packages/ai/src/activities/chat/stream/processor.ts:519](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/stream/processor.ts#L519)
+Defined in: [packages/ai/src/activities/chat/stream/processor.ts:520](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/stream/processor.ts#L520)
 
 Get the conversation as ModelMessages (for sending to LLM)
 
@@ -496,7 +496,7 @@ Get the conversation as ModelMessages (for sending to LLM)
 static replay(recording, options?): Promise<ProcessorResult>;
 ```
 
-Defined in: [packages/ai/src/activities/chat/stream/processor.ts:3678](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/stream/processor.ts#L3678)
+Defined in: [packages/ai/src/activities/chat/stream/processor.ts:3702](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/stream/processor.ts#L3702)
 
 Replay a recording through the processor
 
diff --git a/docs/reference/functions/chat.md b/docs/reference/functions/chat.md
index 93aca2e357..3d0dc6f2a9 100644
--- a/docs/reference/functions/chat.md
+++ b/docs/reference/functions/chat.md
@@ -7,7 +7,7 @@ title: chat
 function chat<TAdapter, TSchema, TStream, TTools, TInterrupts, TContext, TMiddleware, TAgents>(options): TextActivityResult<TSchema, TStream, TTools>;
 ```
 
-Defined in: [packages/ai/src/activities/chat/index.ts:6220](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/index.ts#L6220)
+Defined in: [packages/ai/src/activities/chat/index.ts:6302](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/index.ts#L6302)
 
 Text activity - handles agentic text generation, one-shot text generation, and agentic structured output.
 
diff --git a/docs/reference/functions/createReplayStream.md b/docs/reference/functions/createReplayStream.md
index fc546df40e..a1aad5c526 100644
--- a/docs/reference/functions/createReplayStream.md
+++ b/docs/reference/functions/createReplayStream.md
@@ -7,7 +7,7 @@ title: createReplayStream
 function createReplayStream(recording): AsyncIterable<AGUIEvent>;
 ```
 
-Defined in: [packages/ai/src/activities/chat/stream/processor.ts:3690](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/stream/processor.ts#L3690)
+Defined in: [packages/ai/src/activities/chat/stream/processor.ts:3714](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/stream/processor.ts#L3714)
 
 Create an async iterable from a recording
 
diff --git a/docs/reference/functions/stableJson.md b/docs/reference/functions/stableJson.md
new file mode 100644
index 0000000000..6525c861e5
--- /dev/null
+++ b/docs/reference/functions/stableJson.md
@@ -0,0 +1,25 @@
+---
+id: stableJson
+title: stableJson
+---
+
+```ts
+function stableJson(value): string;
+```
+
+Defined in: [packages/ai/src/utilities/stable-json.ts:7](https://github.com/TanStack/ai/blob/main/packages/ai/src/utilities/stable-json.ts#L7)
+
+JSON text with the keys of every object in sorted order. Arrays keep their
+order. A store can give a value back with its keys in another order
+(PostgreSQL `jsonb` does, and so does a schema parse), so compare or hash
+this, not `JSON.stringify`, when the value went through a store.
+
+## Parameters
+
+### value
+
+`unknown`
+
+## Returns
+
+`string`
diff --git a/docs/reference/index.md b/docs/reference/index.md
index b484fac120..1bb4158d63 100644
--- a/docs/reference/index.md
+++ b/docs/reference/index.md
@@ -616,6 +616,7 @@ title: "@tanstack/ai"
 - [runAgentStream](functions/runAgentStream.md)
 - [score](functions/score.md)
 - [splitMidConversationChanges](functions/splitMidConversationChanges.md)
+- [stableJson](functions/stableJson.md)
 - [streamToText](functions/streamToText.md)
 - [subagentHostMessageId](functions/subagentHostMessageId.md)
 - [subagentInputOf](functions/subagentInputOf.md)
diff --git a/docs/reference/interfaces/ActivityDeltaEvent.md b/docs/reference/interfaces/ActivityDeltaEvent.md
index f993f7fd0e..f91534b02c 100644
--- a/docs/reference/interfaces/ActivityDeltaEvent.md
+++ b/docs/reference/interfaces/ActivityDeltaEvent.md
@@ -3,7 +3,7 @@ id: ActivityDeltaEvent
 title: ActivityDeltaEvent
 ---
 
-Defined in: [packages/ai/src/types.ts:2088](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2088)
+Defined in: [packages/ai/src/types.ts:2103](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2103)
 
 RFC 6902 JSON Patch against an existing activity's `content`.
 
@@ -22,4 +22,4 @@ RFC 6902 JSON Patch against an existing activity's `content`.
 type: "ACTIVITY_DELTA";
 ```
 
-Defined in: [packages/ai/src/types.ts:2092](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2092)
+Defined in: [packages/ai/src/types.ts:2107](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2107)
diff --git a/docs/reference/interfaces/ActivitySnapshotEvent.md b/docs/reference/interfaces/ActivitySnapshotEvent.md
index db03de3d85..0648d8f3ce 100644
--- a/docs/reference/interfaces/ActivitySnapshotEvent.md
+++ b/docs/reference/interfaces/ActivitySnapshotEvent.md
@@ -3,7 +3,7 @@ id: ActivitySnapshotEvent
 title: ActivitySnapshotEvent
 ---
 
-Defined in: [packages/ai/src/types.ts:2075](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2075)
+Defined in: [packages/ai/src/types.ts:2090](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2090)
 
 Full activity state for an `ActivityMessage`.
 
@@ -22,4 +22,4 @@ Full activity state for an `ActivityMessage`.
 type: "ACTIVITY_SNAPSHOT";
 ```
 
-Defined in: [packages/ai/src/types.ts:2079](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2079)
+Defined in: [packages/ai/src/types.ts:2094](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2094)
diff --git a/docs/reference/interfaces/AgentLoopState.md b/docs/reference/interfaces/AgentLoopState.md
index ab9b159d1a..2d9b758f48 100644
--- a/docs/reference/interfaces/AgentLoopState.md
+++ b/docs/reference/interfaces/AgentLoopState.md
@@ -3,7 +3,7 @@ id: AgentLoopState
 title: AgentLoopState
 ---
 
-Defined in: [packages/ai/src/types.ts:1248](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1248)
+Defined in: [packages/ai/src/types.ts:1263](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1263)
 
 State passed to agent loop strategy for determining whether to continue
 
@@ -15,7 +15,7 @@ State passed to agent loop strategy for determining whether to continue
 finishReason: string | null;
 ```
 
-Defined in: [packages/ai/src/types.ts:1254](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1254)
+Defined in: [packages/ai/src/types.ts:1269](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1269)
 
 Finish reason from the last response
 
@@ -27,7 +27,7 @@ Finish reason from the last response
 iterationCount: number;
 ```
 
-Defined in: [packages/ai/src/types.ts:1250](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1250)
+Defined in: [packages/ai/src/types.ts:1265](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1265)
 
 Current iteration count (0-indexed). One iteration = one model turn.
 
@@ -39,7 +39,7 @@ Current iteration count (0-indexed). One iteration = one model turn.
 lastTurnToolCallCount: number;
 ```
 
-Defined in: [packages/ai/src/types.ts:1266](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1266)
+Defined in: [packages/ai/src/types.ts:1281](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1281)
 
 Tool calls in the most recent batch — a live model turn or a
 pending/resume batch (0 when the last phase produced no tool calls).
@@ -55,7 +55,7 @@ messages: ModelMessage<
   | null>[];
 ```
 
-Defined in: [packages/ai/src/types.ts:1252](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1252)
+Defined in: [packages/ai/src/types.ts:1267](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1267)
 
 Current messages array
 
@@ -67,7 +67,7 @@ Current messages array
 toolCallCount: number;
 ```
 
-Defined in: [packages/ai/src/types.ts:1261](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1261)
+Defined in: [packages/ai/src/types.ts:1276](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1276)
 
 Cumulative tool calls counted so far in this run (model-emitted during the
 agent loop, including ones skipped by middleware, and pending tools from
diff --git a/docs/reference/interfaces/AudioGenerationOptions.md b/docs/reference/interfaces/AudioGenerationOptions.md
index 7cee4027bd..0131c059ca 100644
--- a/docs/reference/interfaces/AudioGenerationOptions.md
+++ b/docs/reference/interfaces/AudioGenerationOptions.md
@@ -3,7 +3,7 @@ id: AudioGenerationOptions
 title: AudioGenerationOptions
 ---
 
-Defined in: [packages/ai/src/types.ts:2549](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2549)
+Defined in: [packages/ai/src/types.ts:2564](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2564)
 
 Options for audio generation (music, sound effects, etc.).
 These are the common options supported across providers.
@@ -22,7 +22,7 @@ These are the common options supported across providers.
 optional abortSignal?: AbortSignal;
 ```
 
-Defined in: [packages/ai/src/types.ts:2571](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2571)
+Defined in: [packages/ai/src/types.ts:2586](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2586)
 
 Effective abort signal composed by the activity from caller `abortSignal`
 and/or `timeout`. Adapters should forward this to the provider SDK when
@@ -36,7 +36,7 @@ supported. Request-specific — never store on a global client config.
 optional duration?: number;
 ```
 
-Defined in: [packages/ai/src/types.ts:2557](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2557)
+Defined in: [packages/ai/src/types.ts:2572](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2572)
 
 Desired duration in seconds
 
@@ -48,7 +48,7 @@ Desired duration in seconds
 logger: InternalLogger;
 ```
 
-Defined in: [packages/ai/src/types.ts:2565](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2565)
+Defined in: [packages/ai/src/types.ts:2580](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2580)
 
 Internal logger threaded from the generateAudio() entry point. Adapters
 must call logger.request() before the SDK call and logger.errors() in
@@ -62,7 +62,7 @@ catch blocks.
 model: string;
 ```
 
-Defined in: [packages/ai/src/types.ts:2553](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2553)
+Defined in: [packages/ai/src/types.ts:2568](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2568)
 
 The model to use for audio generation
 
@@ -74,7 +74,7 @@ The model to use for audio generation
 optional modelOptions?: TProviderOptions;
 ```
 
-Defined in: [packages/ai/src/types.ts:2559](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2559)
+Defined in: [packages/ai/src/types.ts:2574](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2574)
 
 Model-specific options for audio generation
 
@@ -86,6 +86,6 @@ Model-specific options for audio generation
 prompt: string;
 ```
 
-Defined in: [packages/ai/src/types.ts:2555](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2555)
+Defined in: [packages/ai/src/types.ts:2570](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2570)
 
 Text description of the desired audio
diff --git a/docs/reference/interfaces/AudioGenerationResult.md b/docs/reference/interfaces/AudioGenerationResult.md
index 3ef3932ee8..c2fc260e2f 100644
--- a/docs/reference/interfaces/AudioGenerationResult.md
+++ b/docs/reference/interfaces/AudioGenerationResult.md
@@ -3,7 +3,7 @@ id: AudioGenerationResult
 title: AudioGenerationResult
 ---
 
-Defined in: [packages/ai/src/types.ts:2587](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2587)
+Defined in: [packages/ai/src/types.ts:2602](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2602)
 
 Result of audio generation
 
@@ -15,7 +15,7 @@ Result of audio generation
 optional artifacts?: PersistedArtifactRef[];
 ```
 
-Defined in: [packages/ai/src/types.ts:2597](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2597)
+Defined in: [packages/ai/src/types.ts:2612](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2612)
 
 Persisted artifact references for generated assets, when available
 
@@ -27,7 +27,7 @@ Persisted artifact references for generated assets, when available
 audio: GeneratedAudio;
 ```
 
-Defined in: [packages/ai/src/types.ts:2593](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2593)
+Defined in: [packages/ai/src/types.ts:2608](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2608)
 
 The generated audio
 
@@ -39,7 +39,7 @@ The generated audio
 id: string;
 ```
 
-Defined in: [packages/ai/src/types.ts:2589](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2589)
+Defined in: [packages/ai/src/types.ts:2604](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2604)
 
 Unique identifier for the generation
 
@@ -51,7 +51,7 @@ Unique identifier for the generation
 model: string;
 ```
 
-Defined in: [packages/ai/src/types.ts:2591](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2591)
+Defined in: [packages/ai/src/types.ts:2606](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2606)
 
 Model used for generation
 
@@ -63,6 +63,6 @@ Model used for generation
 optional usage?: TokenUsage<ProviderUsageDetails>;
 ```
 
-Defined in: [packages/ai/src/types.ts:2595](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2595)
+Defined in: [packages/ai/src/types.ts:2610](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2610)
 
 Token usage information (if available)
diff --git a/docs/reference/interfaces/BaseAGUIEvent.md b/docs/reference/interfaces/BaseAGUIEvent.md
index 4e94a83380..639e98fc5c 100644
--- a/docs/reference/interfaces/BaseAGUIEvent.md
+++ b/docs/reference/interfaces/BaseAGUIEvent.md
@@ -3,7 +3,7 @@ id: BaseAGUIEvent
 title: BaseAGUIEvent
 ---
 
-Defined in: [packages/ai/src/types.ts:1597](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1597)
+Defined in: [packages/ai/src/types.ts:1612](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1612)
 
 Base structure for AG-UI events.
 Extends @ag-ui/core BaseEvent. TanStack extras ride in `metadata`.
@@ -28,7 +28,7 @@ Extends @ag-ui/core BaseEvent. TanStack extras ride in `metadata`.
 optional metadata?: Record<string, any>;
 ```
 
-Defined in: [packages/ai/src/types.ts:1598](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1598)
+Defined in: [packages/ai/src/types.ts:1613](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1613)
 
 Extra information attached to this event.
 
diff --git a/docs/reference/interfaces/CatalogVoice.md b/docs/reference/interfaces/CatalogVoice.md
index c58595053c..d71d010265 100644
--- a/docs/reference/interfaces/CatalogVoice.md
+++ b/docs/reference/interfaces/CatalogVoice.md
@@ -3,7 +3,7 @@ id: CatalogVoice
 title: CatalogVoice
 ---
 
-Defined in: [packages/ai/src/types.ts:3037](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L3037)
+Defined in: [packages/ai/src/types.ts:3052](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L3052)
 
 One voice from a provider's catalog.
 
@@ -15,7 +15,7 @@ One voice from a provider's catalog.
 optional description?: string;
 ```
 
-Defined in: [packages/ai/src/types.ts:3045](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L3045)
+Defined in: [packages/ai/src/types.ts:3060](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L3060)
 
 Provider description of the voice
 
@@ -27,7 +27,7 @@ Provider description of the voice
 optional labels?: Record<string, string>;
 ```
 
-Defined in: [packages/ai/src/types.ts:3049](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L3049)
+Defined in: [packages/ai/src/types.ts:3064](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L3064)
 
 Provider labels, such as accent, age, or use case
 
@@ -39,7 +39,7 @@ Provider labels, such as accent, age, or use case
 optional name?: string;
 ```
 
-Defined in: [packages/ai/src/types.ts:3041](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L3041)
+Defined in: [packages/ai/src/types.ts:3056](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L3056)
 
 Display name, when the provider stores one
 
@@ -51,7 +51,7 @@ Display name, when the provider stores one
 optional origin?: VoiceOrigin;
 ```
 
-Defined in: [packages/ai/src/types.ts:3043](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L3043)
+Defined in: [packages/ai/src/types.ts:3058](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L3058)
 
 Where the voice came from
 
@@ -63,7 +63,7 @@ Where the voice came from
 optional previewUrl?: string;
 ```
 
-Defined in: [packages/ai/src/types.ts:3047](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L3047)
+Defined in: [packages/ai/src/types.ts:3062](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L3062)
 
 URL of a sample, when the provider hosts one
 
@@ -75,6 +75,6 @@ URL of a sample, when the provider hosts one
 voiceId: string;
 ```
 
-Defined in: [packages/ai/src/types.ts:3039](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L3039)
+Defined in: [packages/ai/src/types.ts:3054](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L3054)
 
 Pass this to `generateSpeech()` as `voice`
diff --git a/docs/reference/interfaces/CodeModeConsoleEvent.md b/docs/reference/interfaces/CodeModeConsoleEvent.md
index 2eabbc8f40..5ddf598fba 100644
--- a/docs/reference/interfaces/CodeModeConsoleEvent.md
+++ b/docs/reference/interfaces/CodeModeConsoleEvent.md
@@ -3,7 +3,7 @@ id: CodeModeConsoleEvent
 title: CodeModeConsoleEvent
 ---
 
-Defined in: [packages/ai/src/types.ts:1912](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1912)
+Defined in: [packages/ai/src/types.ts:1927](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1927)
 
 Custom event for extensibility.
 
@@ -21,7 +21,7 @@ Custom event for extensibility.
 optional metadata?: Record<string, any>;
 ```
 
-Defined in: [packages/ai/src/types.ts:1814](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1814)
+Defined in: [packages/ai/src/types.ts:1829](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1829)
 
 Extra information attached to this event.
 
@@ -37,7 +37,7 @@ Extra information attached to this event.
 name: "code_mode:console";
 ```
 
-Defined in: [packages/ai/src/types.ts:1913](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1913)
+Defined in: [packages/ai/src/types.ts:1928](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1928)
 
 What this custom event is. Required: without it a consumer cannot route
 the value.
@@ -56,7 +56,7 @@ CustomEvent.name
 type: "CUSTOM";
 ```
 
-Defined in: [packages/ai/src/types.ts:1813](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1813)
+Defined in: [packages/ai/src/types.ts:1828](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1828)
 
 #### Inherited from
 
@@ -70,7 +70,7 @@ Defined in: [packages/ai/src/types.ts:1813](https://github.com/TanStack/ai/blob/
 value: object;
 ```
 
-Defined in: [packages/ai/src/types.ts:1914](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1914)
+Defined in: [packages/ai/src/types.ts:1929](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1929)
 
 The payload. Any JSON value, and required.
 
diff --git a/docs/reference/interfaces/CodeModeExecutionStartedEvent.md b/docs/reference/interfaces/CodeModeExecutionStartedEvent.md
index 8a8c76b433..892d1f57b1 100644
--- a/docs/reference/interfaces/CodeModeExecutionStartedEvent.md
+++ b/docs/reference/interfaces/CodeModeExecutionStartedEvent.md
@@ -3,7 +3,7 @@ id: CodeModeExecutionStartedEvent
 title: CodeModeExecutionStartedEvent
 ---
 
-Defined in: [packages/ai/src/types.ts:1908](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1908)
+Defined in: [packages/ai/src/types.ts:1923](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1923)
 
 Custom event for extensibility.
 
@@ -21,7 +21,7 @@ Custom event for extensibility.
 optional metadata?: Record<string, any>;
 ```
 
-Defined in: [packages/ai/src/types.ts:1814](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1814)
+Defined in: [packages/ai/src/types.ts:1829](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1829)
 
 Extra information attached to this event.
 
@@ -37,7 +37,7 @@ Extra information attached to this event.
 name: "code_mode:execution_started";
 ```
 
-Defined in: [packages/ai/src/types.ts:1909](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1909)
+Defined in: [packages/ai/src/types.ts:1924](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1924)
 
 What this custom event is. Required: without it a consumer cannot route
 the value.
@@ -56,7 +56,7 @@ CustomEvent.name
 type: "CUSTOM";
 ```
 
-Defined in: [packages/ai/src/types.ts:1813](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1813)
+Defined in: [packages/ai/src/types.ts:1828](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1828)
 
 #### Inherited from
 
@@ -70,7 +70,7 @@ Defined in: [packages/ai/src/types.ts:1813](https://github.com/TanStack/ai/blob/
 value: object;
 ```
 
-Defined in: [packages/ai/src/types.ts:1910](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1910)
+Defined in: [packages/ai/src/types.ts:1925](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1925)
 
 The payload. Any JSON value, and required.
 
diff --git a/docs/reference/interfaces/CodeModeExternalCallEvent.md b/docs/reference/interfaces/CodeModeExternalCallEvent.md
index dbc399b52f..f46ec936c5 100644
--- a/docs/reference/interfaces/CodeModeExternalCallEvent.md
+++ b/docs/reference/interfaces/CodeModeExternalCallEvent.md
@@ -3,7 +3,7 @@ id: CodeModeExternalCallEvent
 title: CodeModeExternalCallEvent
 ---
 
-Defined in: [packages/ai/src/types.ts:1920](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1920)
+Defined in: [packages/ai/src/types.ts:1935](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1935)
 
 Custom event for extensibility.
 
@@ -21,7 +21,7 @@ Custom event for extensibility.
 optional metadata?: Record<string, any>;
 ```
 
-Defined in: [packages/ai/src/types.ts:1814](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1814)
+Defined in: [packages/ai/src/types.ts:1829](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1829)
 
 Extra information attached to this event.
 
@@ -37,7 +37,7 @@ Extra information attached to this event.
 name: "code_mode:external_call";
 ```
 
-Defined in: [packages/ai/src/types.ts:1921](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1921)
+Defined in: [packages/ai/src/types.ts:1936](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1936)
 
 What this custom event is. Required: without it a consumer cannot route
 the value.
@@ -56,7 +56,7 @@ CustomEvent.name
 type: "CUSTOM";
 ```
 
-Defined in: [packages/ai/src/types.ts:1813](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1813)
+Defined in: [packages/ai/src/types.ts:1828](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1828)
 
 #### Inherited from
 
@@ -70,7 +70,7 @@ Defined in: [packages/ai/src/types.ts:1813](https://github.com/TanStack/ai/blob/
 value: object;
 ```
 
-Defined in: [packages/ai/src/types.ts:1922](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1922)
+Defined in: [packages/ai/src/types.ts:1937](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1937)
 
 The payload. Any JSON value, and required.
 
diff --git a/docs/reference/interfaces/CodeModeExternalErrorEvent.md b/docs/reference/interfaces/CodeModeExternalErrorEvent.md
index 7cf6097ff6..afcd5f6f43 100644
--- a/docs/reference/interfaces/CodeModeExternalErrorEvent.md
+++ b/docs/reference/interfaces/CodeModeExternalErrorEvent.md
@@ -3,7 +3,7 @@ id: CodeModeExternalErrorEvent
 title: CodeModeExternalErrorEvent
 ---
 
-Defined in: [packages/ai/src/types.ts:1928](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1928)
+Defined in: [packages/ai/src/types.ts:1943](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1943)
 
 Custom event for extensibility.
 
@@ -21,7 +21,7 @@ Custom event for extensibility.
 optional metadata?: Record<string, any>;
 ```
 
-Defined in: [packages/ai/src/types.ts:1814](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1814)
+Defined in: [packages/ai/src/types.ts:1829](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1829)
 
 Extra information attached to this event.
 
@@ -37,7 +37,7 @@ Extra information attached to this event.
 name: "code_mode:external_error";
 ```
 
-Defined in: [packages/ai/src/types.ts:1929](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1929)
+Defined in: [packages/ai/src/types.ts:1944](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1944)
 
 What this custom event is. Required: without it a consumer cannot route
 the value.
@@ -56,7 +56,7 @@ CustomEvent.name
 type: "CUSTOM";
 ```
 
-Defined in: [packages/ai/src/types.ts:1813](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1813)
+Defined in: [packages/ai/src/types.ts:1828](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1828)
 
 #### Inherited from
 
@@ -70,7 +70,7 @@ Defined in: [packages/ai/src/types.ts:1813](https://github.com/TanStack/ai/blob/
 value: object;
 ```
 
-Defined in: [packages/ai/src/types.ts:1930](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1930)
+Defined in: [packages/ai/src/types.ts:1945](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1945)
 
 The payload. Any JSON value, and required.
 
diff --git a/docs/reference/interfaces/CodeModeExternalResultEvent.md b/docs/reference/interfaces/CodeModeExternalResultEvent.md
index 8904913c18..bfbfd4f419 100644
--- a/docs/reference/interfaces/CodeModeExternalResultEvent.md
+++ b/docs/reference/interfaces/CodeModeExternalResultEvent.md
@@ -3,7 +3,7 @@ id: CodeModeExternalResultEvent
 title: CodeModeExternalResultEvent
 ---
 
-Defined in: [packages/ai/src/types.ts:1924](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1924)
+Defined in: [packages/ai/src/types.ts:1939](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1939)
 
 Custom event for extensibility.
 
@@ -21,7 +21,7 @@ Custom event for extensibility.
 optional metadata?: Record<string, any>;
 ```
 
-Defined in: [packages/ai/src/types.ts:1814](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1814)
+Defined in: [packages/ai/src/types.ts:1829](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1829)
 
 Extra information attached to this event.
 
@@ -37,7 +37,7 @@ Extra information attached to this event.
 name: "code_mode:external_result";
 ```
 
-Defined in: [packages/ai/src/types.ts:1925](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1925)
+Defined in: [packages/ai/src/types.ts:1940](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1940)
 
 What this custom event is. Required: without it a consumer cannot route
 the value.
@@ -56,7 +56,7 @@ CustomEvent.name
 type: "CUSTOM";
 ```
 
-Defined in: [packages/ai/src/types.ts:1813](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1813)
+Defined in: [packages/ai/src/types.ts:1828](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1828)
 
 #### Inherited from
 
@@ -70,7 +70,7 @@ Defined in: [packages/ai/src/types.ts:1813](https://github.com/TanStack/ai/blob/
 value: object;
 ```
 
-Defined in: [packages/ai/src/types.ts:1926](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1926)
+Defined in: [packages/ai/src/types.ts:1941](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1941)
 
 The payload. Any JSON value, and required.
 
diff --git a/docs/reference/interfaces/CodeModeSnippetCallEvent.md b/docs/reference/interfaces/CodeModeSnippetCallEvent.md
index abda9401f3..e1a9b4d5e3 100644
--- a/docs/reference/interfaces/CodeModeSnippetCallEvent.md
+++ b/docs/reference/interfaces/CodeModeSnippetCallEvent.md
@@ -3,7 +3,7 @@ id: CodeModeSnippetCallEvent
 title: CodeModeSnippetCallEvent
 ---
 
-Defined in: [packages/ai/src/types.ts:1932](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1932)
+Defined in: [packages/ai/src/types.ts:1947](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1947)
 
 Custom event for extensibility.
 
@@ -21,7 +21,7 @@ Custom event for extensibility.
 optional metadata?: Record<string, any>;
 ```
 
-Defined in: [packages/ai/src/types.ts:1814](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1814)
+Defined in: [packages/ai/src/types.ts:1829](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1829)
 
 Extra information attached to this event.
 
@@ -37,7 +37,7 @@ Extra information attached to this event.
 name: "code_mode:snippet_call";
 ```
 
-Defined in: [packages/ai/src/types.ts:1933](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1933)
+Defined in: [packages/ai/src/types.ts:1948](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1948)
 
 What this custom event is. Required: without it a consumer cannot route
 the value.
@@ -56,7 +56,7 @@ CustomEvent.name
 type: "CUSTOM";
 ```
 
-Defined in: [packages/ai/src/types.ts:1813](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1813)
+Defined in: [packages/ai/src/types.ts:1828](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1828)
 
 #### Inherited from
 
@@ -70,7 +70,7 @@ Defined in: [packages/ai/src/types.ts:1813](https://github.com/TanStack/ai/blob/
 value: object;
 ```
 
-Defined in: [packages/ai/src/types.ts:1934](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1934)
+Defined in: [packages/ai/src/types.ts:1949](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1949)
 
 The payload. Any JSON value, and required.
 
diff --git a/docs/reference/interfaces/CodeModeSnippetErrorEvent.md b/docs/reference/interfaces/CodeModeSnippetErrorEvent.md
index 4027b86922..c821730b13 100644
--- a/docs/reference/interfaces/CodeModeSnippetErrorEvent.md
+++ b/docs/reference/interfaces/CodeModeSnippetErrorEvent.md
@@ -3,7 +3,7 @@ id: CodeModeSnippetErrorEvent
 title: CodeModeSnippetErrorEvent
 ---
 
-Defined in: [packages/ai/src/types.ts:1945](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1945)
+Defined in: [packages/ai/src/types.ts:1960](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1960)
 
 Custom event for extensibility.
 
@@ -21,7 +21,7 @@ Custom event for extensibility.
 optional metadata?: Record<string, any>;
 ```
 
-Defined in: [packages/ai/src/types.ts:1814](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1814)
+Defined in: [packages/ai/src/types.ts:1829](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1829)
 
 Extra information attached to this event.
 
@@ -37,7 +37,7 @@ Extra information attached to this event.
 name: "code_mode:snippet_error";
 ```
 
-Defined in: [packages/ai/src/types.ts:1946](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1946)
+Defined in: [packages/ai/src/types.ts:1961](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1961)
 
 What this custom event is. Required: without it a consumer cannot route
 the value.
@@ -56,7 +56,7 @@ CustomEvent.name
 type: "CUSTOM";
 ```
 
-Defined in: [packages/ai/src/types.ts:1813](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1813)
+Defined in: [packages/ai/src/types.ts:1828](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1828)
 
 #### Inherited from
 
@@ -70,7 +70,7 @@ Defined in: [packages/ai/src/types.ts:1813](https://github.com/TanStack/ai/blob/
 value: object;
 ```
 
-Defined in: [packages/ai/src/types.ts:1947](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1947)
+Defined in: [packages/ai/src/types.ts:1962](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1962)
 
 The payload. Any JSON value, and required.
 
diff --git a/docs/reference/interfaces/CodeModeSnippetResultEvent.md b/docs/reference/interfaces/CodeModeSnippetResultEvent.md
index acb9c6aa79..a9596f93df 100644
--- a/docs/reference/interfaces/CodeModeSnippetResultEvent.md
+++ b/docs/reference/interfaces/CodeModeSnippetResultEvent.md
@@ -3,7 +3,7 @@ id: CodeModeSnippetResultEvent
 title: CodeModeSnippetResultEvent
 ---
 
-Defined in: [packages/ai/src/types.ts:1936](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1936)
+Defined in: [packages/ai/src/types.ts:1951](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1951)
 
 Custom event for extensibility.
 
@@ -21,7 +21,7 @@ Custom event for extensibility.
 optional metadata?: Record<string, any>;
 ```
 
-Defined in: [packages/ai/src/types.ts:1814](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1814)
+Defined in: [packages/ai/src/types.ts:1829](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1829)
 
 Extra information attached to this event.
 
@@ -37,7 +37,7 @@ Extra information attached to this event.
 name: "code_mode:snippet_result";
 ```
 
-Defined in: [packages/ai/src/types.ts:1937](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1937)
+Defined in: [packages/ai/src/types.ts:1952](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1952)
 
 What this custom event is. Required: without it a consumer cannot route
 the value.
@@ -56,7 +56,7 @@ CustomEvent.name
 type: "CUSTOM";
 ```
 
-Defined in: [packages/ai/src/types.ts:1813](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1813)
+Defined in: [packages/ai/src/types.ts:1828](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1828)
 
 #### Inherited from
 
@@ -70,7 +70,7 @@ Defined in: [packages/ai/src/types.ts:1813](https://github.com/TanStack/ai/blob/
 value: object;
 ```
 
-Defined in: [packages/ai/src/types.ts:1938](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1938)
+Defined in: [packages/ai/src/types.ts:1953](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1953)
 
 The payload. Any JSON value, and required.
 
diff --git a/docs/reference/interfaces/CustomEvent.md b/docs/reference/interfaces/CustomEvent.md
index 6927a3aeb9..ef7bf7172f 100644
--- a/docs/reference/interfaces/CustomEvent.md
+++ b/docs/reference/interfaces/CustomEvent.md
@@ -3,7 +3,7 @@ id: CustomEvent
 title: CustomEvent
 ---
 
-Defined in: [packages/ai/src/types.ts:1812](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1812)
+Defined in: [packages/ai/src/types.ts:1827](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1827)
 
 Custom event for extensibility.
 
@@ -43,7 +43,7 @@ Custom event for extensibility.
 optional metadata?: Record<string, any>;
 ```
 
-Defined in: [packages/ai/src/types.ts:1814](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1814)
+Defined in: [packages/ai/src/types.ts:1829](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1829)
 
 Extra information attached to this event.
 
@@ -61,4 +61,4 @@ Omit.metadata
 type: "CUSTOM";
 ```
 
-Defined in: [packages/ai/src/types.ts:1813](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1813)
+Defined in: [packages/ai/src/types.ts:1828](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1828)
diff --git a/docs/reference/interfaces/DefaultMessageMetadataByModality.md b/docs/reference/interfaces/DefaultMessageMetadataByModality.md
index 0c808b7c09..3e26403e2c 100644
--- a/docs/reference/interfaces/DefaultMessageMetadataByModality.md
+++ b/docs/reference/interfaces/DefaultMessageMetadataByModality.md
@@ -3,7 +3,7 @@ id: DefaultMessageMetadataByModality
 title: DefaultMessageMetadataByModality
 ---
 
-Defined in: [packages/ai/src/types.ts:3412](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L3412)
+Defined in: [packages/ai/src/types.ts:3427](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L3427)
 
 Default metadata type for adapters that don't define custom metadata.
 Uses unknown for all modalities.
@@ -16,7 +16,7 @@ Uses unknown for all modalities.
 audio: unknown;
 ```
 
-Defined in: [packages/ai/src/types.ts:3415](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L3415)
+Defined in: [packages/ai/src/types.ts:3430](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L3430)
 
 ***
 
@@ -26,7 +26,7 @@ Defined in: [packages/ai/src/types.ts:3415](https://github.com/TanStack/ai/blob/
 document: unknown;
 ```
 
-Defined in: [packages/ai/src/types.ts:3417](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L3417)
+Defined in: [packages/ai/src/types.ts:3432](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L3432)
 
 ***
 
@@ -36,7 +36,7 @@ Defined in: [packages/ai/src/types.ts:3417](https://github.com/TanStack/ai/blob/
 image: unknown;
 ```
 
-Defined in: [packages/ai/src/types.ts:3414](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L3414)
+Defined in: [packages/ai/src/types.ts:3429](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L3429)
 
 ***
 
@@ -46,7 +46,7 @@ Defined in: [packages/ai/src/types.ts:3414](https://github.com/TanStack/ai/blob/
 text: unknown;
 ```
 
-Defined in: [packages/ai/src/types.ts:3413](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L3413)
+Defined in: [packages/ai/src/types.ts:3428](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L3428)
 
 ***
 
@@ -56,4 +56,4 @@ Defined in: [packages/ai/src/types.ts:3413](https://github.com/TanStack/ai/blob/
 video: unknown;
 ```
 
-Defined in: [packages/ai/src/types.ts:3416](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L3416)
+Defined in: [packages/ai/src/types.ts:3431](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L3431)
diff --git a/docs/reference/interfaces/Embedding.md b/docs/reference/interfaces/Embedding.md
index abe6abf573..ed15a7e8af 100644
--- a/docs/reference/interfaces/Embedding.md
+++ b/docs/reference/interfaces/Embedding.md
@@ -3,7 +3,7 @@ id: Embedding
 title: Embedding
 ---
 
-Defined in: [packages/ai/src/types.ts:3387](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L3387)
+Defined in: [packages/ai/src/types.ts:3402](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L3402)
 
 A single embedding vector.
 
@@ -15,7 +15,7 @@ A single embedding vector.
 index: number;
 ```
 
-Defined in: [packages/ai/src/types.ts:3391](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L3391)
+Defined in: [packages/ai/src/types.ts:3406](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L3406)
 
 Position of the source item in the (normalized) input array
 
@@ -27,6 +27,6 @@ Position of the source item in the (normalized) input array
 vector: number[];
 ```
 
-Defined in: [packages/ai/src/types.ts:3389](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L3389)
+Defined in: [packages/ai/src/types.ts:3404](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L3404)
 
 The embedding vector
diff --git a/docs/reference/interfaces/EmbeddingOptions.md b/docs/reference/interfaces/EmbeddingOptions.md
index f570cffa1d..2e17c2ef9a 100644
--- a/docs/reference/interfaces/EmbeddingOptions.md
+++ b/docs/reference/interfaces/EmbeddingOptions.md
@@ -3,7 +3,7 @@ id: EmbeddingOptions
 title: EmbeddingOptions
 ---
 
-Defined in: [packages/ai/src/types.ts:3358](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L3358)
+Defined in: [packages/ai/src/types.ts:3373](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L3373)
 
 Options for embedding generation, as received by adapters. The `embed()`
 entry point normalizes a single input item to an array before calling the
@@ -23,7 +23,7 @@ adapter, so `input` is always an array here.
 optional abortSignal?: AbortSignal;
 ```
 
-Defined in: [packages/ai/src/types.ts:3381](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L3381)
+Defined in: [packages/ai/src/types.ts:3396](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L3396)
 
 Effective abort signal composed by the activity from caller `abortSignal`
 and/or `timeout`. Adapters should forward this to the provider SDK when
@@ -37,7 +37,7 @@ supported. Request-specific — never store on a global client config.
 optional dimensions?: number;
 ```
 
-Defined in: [packages/ai/src/types.ts:3367](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L3367)
+Defined in: [packages/ai/src/types.ts:3382](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L3382)
 
 Requested output dimensionality. Adapters for models with fixed
 dimensions throw a clear runtime error when this is set.
@@ -50,7 +50,7 @@ dimensions throw a clear runtime error when this is set.
 input: EmbeddingInputItem[];
 ```
 
-Defined in: [packages/ai/src/types.ts:3362](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L3362)
+Defined in: [packages/ai/src/types.ts:3377](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L3377)
 
 The items to embed — one vector per item
 
@@ -62,7 +62,7 @@ The items to embed — one vector per item
 logger: InternalLogger;
 ```
 
-Defined in: [packages/ai/src/types.ts:3375](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L3375)
+Defined in: [packages/ai/src/types.ts:3390](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L3390)
 
 Internal logger threaded from the embed() entry point. Adapters must
 call logger.request() before the SDK call and logger.errors() in catch
@@ -76,7 +76,7 @@ blocks.
 model: string;
 ```
 
-Defined in: [packages/ai/src/types.ts:3360](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L3360)
+Defined in: [packages/ai/src/types.ts:3375](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L3375)
 
 The model to use for embedding generation
 
@@ -88,6 +88,6 @@ The model to use for embedding generation
 optional modelOptions?: TProviderOptions;
 ```
 
-Defined in: [packages/ai/src/types.ts:3369](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L3369)
+Defined in: [packages/ai/src/types.ts:3384](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L3384)
 
 Model-specific options for embedding generation
diff --git a/docs/reference/interfaces/EmbeddingResult.md b/docs/reference/interfaces/EmbeddingResult.md
index f3ea1ceaff..8400dada0d 100644
--- a/docs/reference/interfaces/EmbeddingResult.md
+++ b/docs/reference/interfaces/EmbeddingResult.md
@@ -3,7 +3,7 @@ id: EmbeddingResult
 title: EmbeddingResult
 ---
 
-Defined in: [packages/ai/src/types.ts:3397](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L3397)
+Defined in: [packages/ai/src/types.ts:3412](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L3412)
 
 Result of embedding generation.
 
@@ -15,7 +15,7 @@ Result of embedding generation.
 embeddings: Embedding[];
 ```
 
-Defined in: [packages/ai/src/types.ts:3403](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L3403)
+Defined in: [packages/ai/src/types.ts:3418](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L3418)
 
 One embedding per input item, in input order
 
@@ -27,7 +27,7 @@ One embedding per input item, in input order
 id: string;
 ```
 
-Defined in: [packages/ai/src/types.ts:3399](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L3399)
+Defined in: [packages/ai/src/types.ts:3414](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L3414)
 
 Unique identifier for the generation
 
@@ -39,7 +39,7 @@ Unique identifier for the generation
 model: string;
 ```
 
-Defined in: [packages/ai/src/types.ts:3401](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L3401)
+Defined in: [packages/ai/src/types.ts:3416](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L3416)
 
 Model used for generation
 
@@ -51,6 +51,6 @@ Model used for generation
 optional usage?: TokenUsage<ProviderUsageDetails>;
 ```
 
-Defined in: [packages/ai/src/types.ts:3405](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L3405)
+Defined in: [packages/ai/src/types.ts:3420](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L3420)
 
 Token usage information (if provided by the adapter)
diff --git a/docs/reference/interfaces/EmitCustomEventOptions.md b/docs/reference/interfaces/EmitCustomEventOptions.md
index bf847d7b55..1a1c510665 100644
--- a/docs/reference/interfaces/EmitCustomEventOptions.md
+++ b/docs/reference/interfaces/EmitCustomEventOptions.md
@@ -3,7 +3,7 @@ id: EmitCustomEventOptions
 title: EmitCustomEventOptions
 ---
 
-Defined in: [packages/ai/src/types.ts:865](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L865)
+Defined in: [packages/ai/src/types.ts:880](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L880)
 
 Options for a single `emitCustomEvent` call, on both the tool-execution and
 middleware contexts.
@@ -16,7 +16,7 @@ middleware contexts.
 optional batch?: boolean;
 ```
 
-Defined in: [packages/ai/src/types.ts:874](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L874)
+Defined in: [packages/ai/src/types.ts:889](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L889)
 
 Keep this event in the durability batch with later chunks.
 CUSTOM events flush as soon as they are emitted, so a progress
diff --git a/docs/reference/interfaces/FileChangedEvent.md b/docs/reference/interfaces/FileChangedEvent.md
index 789b5ca165..cc6d0b8cfe 100644
--- a/docs/reference/interfaces/FileChangedEvent.md
+++ b/docs/reference/interfaces/FileChangedEvent.md
@@ -3,7 +3,7 @@ id: FileChangedEvent
 title: FileChangedEvent
 ---
 
-Defined in: [packages/ai/src/types.ts:1898](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1898)
+Defined in: [packages/ai/src/types.ts:1913](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1913)
 
 Custom event for extensibility.
 
@@ -21,7 +21,7 @@ Custom event for extensibility.
 optional metadata?: Record<string, any>;
 ```
 
-Defined in: [packages/ai/src/types.ts:1814](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1814)
+Defined in: [packages/ai/src/types.ts:1829](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1829)
 
 Extra information attached to this event.
 
@@ -37,7 +37,7 @@ Extra information attached to this event.
 name: "file.changed";
 ```
 
-Defined in: [packages/ai/src/types.ts:1899](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1899)
+Defined in: [packages/ai/src/types.ts:1914](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1914)
 
 What this custom event is. Required: without it a consumer cannot route
 the value.
@@ -56,7 +56,7 @@ CustomEvent.name
 type: "CUSTOM";
 ```
 
-Defined in: [packages/ai/src/types.ts:1813](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1813)
+Defined in: [packages/ai/src/types.ts:1828](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1828)
 
 #### Inherited from
 
@@ -70,7 +70,7 @@ Defined in: [packages/ai/src/types.ts:1813](https://github.com/TanStack/ai/blob/
 value: object;
 ```
 
-Defined in: [packages/ai/src/types.ts:1900](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1900)
+Defined in: [packages/ai/src/types.ts:1915](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1915)
 
 The payload. Any JSON value, and required.
 
diff --git a/docs/reference/interfaces/GeneratedVoice.md b/docs/reference/interfaces/GeneratedVoice.md
index 2abaa4e884..9412bbb7e7 100644
--- a/docs/reference/interfaces/GeneratedVoice.md
+++ b/docs/reference/interfaces/GeneratedVoice.md
@@ -3,7 +3,7 @@ id: GeneratedVoice
 title: GeneratedVoice
 ---
 
-Defined in: [packages/ai/src/types.ts:3129](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L3129)
+Defined in: [packages/ai/src/types.ts:3144](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L3144)
 
 A single voice produced by [VoiceGenerationOptions](VoiceGenerationOptions.md).
 
@@ -15,7 +15,7 @@ A single voice produced by [VoiceGenerationOptions](VoiceGenerationOptions.md).
 optional audio?: string;
 ```
 
-Defined in: [packages/ai/src/types.ts:3136](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L3136)
+Defined in: [packages/ai/src/types.ts:3151](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L3151)
 
 Base64-encoded preview audio, when the provider returns one
 
@@ -27,7 +27,7 @@ Base64-encoded preview audio, when the provider returns one
 optional contentType?: string;
 ```
 
-Defined in: [packages/ai/src/types.ts:3140](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L3140)
+Defined in: [packages/ai/src/types.ts:3155](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L3155)
 
 Content type of the preview (e.g. 'audio/mpeg')
 
@@ -39,7 +39,7 @@ Content type of the preview (e.g. 'audio/mpeg')
 optional duration?: number;
 ```
 
-Defined in: [packages/ai/src/types.ts:3142](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L3142)
+Defined in: [packages/ai/src/types.ts:3157](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L3157)
 
 Duration of the preview in seconds, if available
 
@@ -51,7 +51,7 @@ Duration of the preview in seconds, if available
 optional format?: string;
 ```
 
-Defined in: [packages/ai/src/types.ts:3138](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L3138)
+Defined in: [packages/ai/src/types.ts:3153](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L3153)
 
 Audio format of the preview (e.g. 'mp3')
 
@@ -63,7 +63,7 @@ Audio format of the preview (e.g. 'mp3')
 optional language?: string;
 ```
 
-Defined in: [packages/ai/src/types.ts:3144](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L3144)
+Defined in: [packages/ai/src/types.ts:3159](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L3159)
 
 Language of the preview, if reported
 
@@ -75,7 +75,7 @@ Language of the preview, if reported
 saved: boolean;
 ```
 
-Defined in: [packages/ai/src/types.ts:3149](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L3149)
+Defined in: [packages/ai/src/types.ts:3164](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L3164)
 
 Whether the voice is persisted in the provider's voice library. Unsaved
 voices are previews and generally expire.
@@ -88,7 +88,7 @@ voices are previews and generally expire.
 status: VoiceTrainingStatus;
 ```
 
-Defined in: [packages/ai/src/types.ts:3154](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L3154)
+Defined in: [packages/ai/src/types.ts:3169](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L3169)
 
 Whether the voice can be used in `generateSpeech()` yet. Required so a
 caller never has to guess: every adapter states it outright.
@@ -101,7 +101,7 @@ caller never has to guess: every adapter states it outright.
 voiceId: string;
 ```
 
-Defined in: [packages/ai/src/types.ts:3134](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L3134)
+Defined in: [packages/ai/src/types.ts:3149](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L3149)
 
 The provider's voice identifier. Pass it straight back as the `voice`
 option on `generateSpeech()`.
diff --git a/docs/reference/interfaces/ImageGenerationOptions.md b/docs/reference/interfaces/ImageGenerationOptions.md
index 04459d6666..06e9eb8e07 100644
--- a/docs/reference/interfaces/ImageGenerationOptions.md
+++ b/docs/reference/interfaces/ImageGenerationOptions.md
@@ -3,7 +3,7 @@ id: ImageGenerationOptions
 title: ImageGenerationOptions
 ---
 
-Defined in: [packages/ai/src/types.ts:2420](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2420)
+Defined in: [packages/ai/src/types.ts:2435](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2435)
 
 Options for image generation.
 These are the common options supported across providers.
@@ -26,7 +26,7 @@ These are the common options supported across providers.
 optional abortSignal?: AbortSignal;
 ```
 
-Defined in: [packages/ai/src/types.ts:2452](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2452)
+Defined in: [packages/ai/src/types.ts:2467](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2467)
 
 Effective abort signal composed by the activity from caller `abortSignal`
 and/or `timeout`. Adapters should forward this to the provider SDK when
@@ -40,7 +40,7 @@ supported. Request-specific — never store on a global client config.
 logger: InternalLogger;
 ```
 
-Defined in: [packages/ai/src/types.ts:2446](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2446)
+Defined in: [packages/ai/src/types.ts:2461](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2461)
 
 Internal logger threaded from the generateImage() entry point. Adapters must
 call logger.request() before the SDK call and logger.errors() in catch blocks.
@@ -53,7 +53,7 @@ call logger.request() before the SDK call and logger.errors() in catch blocks.
 model: string;
 ```
 
-Defined in: [packages/ai/src/types.ts:2425](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2425)
+Defined in: [packages/ai/src/types.ts:2440](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2440)
 
 The model to use for image generation
 
@@ -65,7 +65,7 @@ The model to use for image generation
 optional modelOptions?: TProviderOptions;
 ```
 
-Defined in: [packages/ai/src/types.ts:2441](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2441)
+Defined in: [packages/ai/src/types.ts:2456](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2456)
 
 Model-specific options for image generation
 
@@ -77,7 +77,7 @@ Model-specific options for image generation
 optional numberOfImages?: number;
 ```
 
-Defined in: [packages/ai/src/types.ts:2437](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2437)
+Defined in: [packages/ai/src/types.ts:2452](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2452)
 
 Number of images to generate (default: 1)
 
@@ -89,7 +89,7 @@ Number of images to generate (default: 1)
 prompt: MediaPrompt;
 ```
 
-Defined in: [packages/ai/src/types.ts:2435](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2435)
+Defined in: [packages/ai/src/types.ts:2450](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2450)
 
 Description of the desired image(s): a plain string, or an ordered array
 of content parts for image-conditioned generation (image-to-image,
@@ -107,6 +107,6 @@ multimodal `contents`, OpenAI `images.edit()`, fal `image_url` /
 optional size?: TSize;
 ```
 
-Defined in: [packages/ai/src/types.ts:2439](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2439)
+Defined in: [packages/ai/src/types.ts:2454](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2454)
 
 Image size in WIDTHxHEIGHT format (e.g., "1024x1024")
diff --git a/docs/reference/interfaces/ImageGenerationResult.md b/docs/reference/interfaces/ImageGenerationResult.md
index 5b152d3651..e2950d8036 100644
--- a/docs/reference/interfaces/ImageGenerationResult.md
+++ b/docs/reference/interfaces/ImageGenerationResult.md
@@ -3,7 +3,7 @@ id: ImageGenerationResult
 title: ImageGenerationResult
 ---
 
-Defined in: [packages/ai/src/types.ts:2528](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2528)
+Defined in: [packages/ai/src/types.ts:2543](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2543)
 
 Result of image generation
 
@@ -15,7 +15,7 @@ Result of image generation
 optional artifacts?: PersistedArtifactRef[];
 ```
 
-Defined in: [packages/ai/src/types.ts:2538](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2538)
+Defined in: [packages/ai/src/types.ts:2553](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2553)
 
 Persisted artifact references for generated assets, when available
 
@@ -27,7 +27,7 @@ Persisted artifact references for generated assets, when available
 id: string;
 ```
 
-Defined in: [packages/ai/src/types.ts:2530](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2530)
+Defined in: [packages/ai/src/types.ts:2545](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2545)
 
 Unique identifier for the generation
 
@@ -39,7 +39,7 @@ Unique identifier for the generation
 images: GeneratedImage[];
 ```
 
-Defined in: [packages/ai/src/types.ts:2534](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2534)
+Defined in: [packages/ai/src/types.ts:2549](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2549)
 
 Array of generated images
 
@@ -51,7 +51,7 @@ Array of generated images
 model: string;
 ```
 
-Defined in: [packages/ai/src/types.ts:2532](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2532)
+Defined in: [packages/ai/src/types.ts:2547](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2547)
 
 Model used for generation
 
@@ -63,6 +63,6 @@ Model used for generation
 optional usage?: TokenUsage<ProviderUsageDetails>;
 ```
 
-Defined in: [packages/ai/src/types.ts:2536](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2536)
+Defined in: [packages/ai/src/types.ts:2551](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2551)
 
 Token usage information (if available)
diff --git a/docs/reference/interfaces/LazyToolsConfig.md b/docs/reference/interfaces/LazyToolsConfig.md
index 243d1d9b66..29ba8fb81a 100644
--- a/docs/reference/interfaces/LazyToolsConfig.md
+++ b/docs/reference/interfaces/LazyToolsConfig.md
@@ -3,7 +3,7 @@ id: LazyToolsConfig
 title: LazyToolsConfig
 ---
 
-Defined in: [packages/ai/src/types.ts:1136](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1136)
+Defined in: [packages/ai/src/types.ts:1151](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1151)
 
 Configuration for the lazy-tool discovery catalog, shared by chat() and
 Code Mode. Optional in both — lazy behavior is triggered purely by tools
@@ -19,7 +19,7 @@ always returns the full description + schema.
 optional includeDescription?: "full" | "first-sentence" | "none";
 ```
 
-Defined in: [packages/ai/src/types.ts:1142](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1142)
+Defined in: [packages/ai/src/types.ts:1157](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1157)
 
 How much of each lazy tool's description appears in the pre-discovery
 catalog (the names list shown before the model discovers the tool).
diff --git a/docs/reference/interfaces/ListVoicesOptions.md b/docs/reference/interfaces/ListVoicesOptions.md
index 71ba100000..3b30fe1989 100644
--- a/docs/reference/interfaces/ListVoicesOptions.md
+++ b/docs/reference/interfaces/ListVoicesOptions.md
@@ -3,7 +3,7 @@ id: ListVoicesOptions
 title: ListVoicesOptions
 ---
 
-Defined in: [packages/ai/src/types.ts:3053](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L3053)
+Defined in: [packages/ai/src/types.ts:3068](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L3068)
 
 Options for listing a provider's voices.
 
@@ -15,7 +15,7 @@ Options for listing a provider's voices.
 optional abortSignal?: AbortSignal;
 ```
 
-Defined in: [packages/ai/src/types.ts:3063](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L3063)
+Defined in: [packages/ai/src/types.ts:3078](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L3078)
 
 Effective abort signal. Adapters forward this to the provider SDK when
 supported.
@@ -28,7 +28,7 @@ supported.
 optional origins?: VoiceOrigin[];
 ```
 
-Defined in: [packages/ai/src/types.ts:3058](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L3058)
+Defined in: [packages/ai/src/types.ts:3073](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L3073)
 
 Restrict the result to voices of these origins. Adapters filter server
 side when the provider supports it, and in memory otherwise.
diff --git a/docs/reference/interfaces/ListVoicesResult.md b/docs/reference/interfaces/ListVoicesResult.md
index 0ac1c6cac8..e84eb0b79f 100644
--- a/docs/reference/interfaces/ListVoicesResult.md
+++ b/docs/reference/interfaces/ListVoicesResult.md
@@ -3,7 +3,7 @@ id: ListVoicesResult
 title: ListVoicesResult
 ---
 
-Defined in: [packages/ai/src/types.ts:3067](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L3067)
+Defined in: [packages/ai/src/types.ts:3082](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L3082)
 
 Result of listing a provider's voices.
 
@@ -15,6 +15,6 @@ Result of listing a provider's voices.
 voices: CatalogVoice[];
 ```
 
-Defined in: [packages/ai/src/types.ts:3069](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L3069)
+Defined in: [packages/ai/src/types.ts:3084](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L3084)
 
 The voices available to this account
diff --git a/docs/reference/interfaces/LiveVideoGenerationOptions.md b/docs/reference/interfaces/LiveVideoGenerationOptions.md
index 24c669b90c..154ae88a43 100644
--- a/docs/reference/interfaces/LiveVideoGenerationOptions.md
+++ b/docs/reference/interfaces/LiveVideoGenerationOptions.md
@@ -3,7 +3,7 @@ id: LiveVideoGenerationOptions
 title: LiveVideoGenerationOptions
 ---
 
-Defined in: [packages/ai/src/types.ts:2832](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2832)
+Defined in: [packages/ai/src/types.ts:2847](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2847)
 
 **`Experimental`**
 
@@ -25,7 +25,7 @@ Options for live generation (prompt-steerable video sessions).
 optional abortSignal?: AbortSignal;
 ```
 
-Defined in: [packages/ai/src/types.ts:2855](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2855)
+Defined in: [packages/ai/src/types.ts:2870](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2870)
 
 **`Experimental`**
 
@@ -41,7 +41,7 @@ supported. Request-specific — never store on a global client config.
 logger: InternalLogger;
 ```
 
-Defined in: [packages/ai/src/types.ts:2849](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2849)
+Defined in: [packages/ai/src/types.ts:2864](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2864)
 
 **`Experimental`**
 
@@ -57,7 +57,7 @@ catch blocks.
 model: string;
 ```
 
-Defined in: [packages/ai/src/types.ts:2836](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2836)
+Defined in: [packages/ai/src/types.ts:2851](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2851)
 
 **`Experimental`**
 
@@ -71,7 +71,7 @@ The model to use for live generation
 optional modelOptions?: TProviderOptions;
 ```
 
-Defined in: [packages/ai/src/types.ts:2843](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2843)
+Defined in: [packages/ai/src/types.ts:2858](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2858)
 
 **`Experimental`**
 
@@ -86,7 +86,7 @@ resolution/seed/audio are browser `sendCommand` fields.
 prompt: string;
 ```
 
-Defined in: [packages/ai/src/types.ts:2838](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2838)
+Defined in: [packages/ai/src/types.ts:2853](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2853)
 
 **`Experimental`**
 
diff --git a/docs/reference/interfaces/LiveVideoGenerationResult.md b/docs/reference/interfaces/LiveVideoGenerationResult.md
index 8d603dbf4e..a69c75941a 100644
--- a/docs/reference/interfaces/LiveVideoGenerationResult.md
+++ b/docs/reference/interfaces/LiveVideoGenerationResult.md
@@ -3,7 +3,7 @@ id: LiveVideoGenerationResult
 title: LiveVideoGenerationResult
 ---
 
-Defined in: [packages/ai/src/types.ts:2868](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2868)
+Defined in: [packages/ai/src/types.ts:2883](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2883)
 
 **`Experimental`**
 
@@ -24,7 +24,7 @@ that attaches `FAL_KEY`. Do not send `token` as Key credentials.
 expiresAt: number;
 ```
 
-Defined in: [packages/ai/src/types.ts:2879](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2879)
+Defined in: [packages/ai/src/types.ts:2894](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2894)
 
 **`Experimental`**
 
@@ -38,7 +38,7 @@ Token expiry as milliseconds since epoch
 id: string;
 ```
 
-Defined in: [packages/ai/src/types.ts:2870](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2870)
+Defined in: [packages/ai/src/types.ts:2885](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2885)
 
 **`Experimental`**
 
@@ -52,7 +52,7 @@ Unique identifier for this generation
 model: string;
 ```
 
-Defined in: [packages/ai/src/types.ts:2875](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2875)
+Defined in: [packages/ai/src/types.ts:2890](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2890)
 
 **`Experimental`**
 
@@ -67,7 +67,7 @@ fal: WMA app id `fal-ai/minimax-h3-max-director`.
 prompt: string;
 ```
 
-Defined in: [packages/ai/src/types.ts:2881](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2881)
+Defined in: [packages/ai/src/types.ts:2896](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2896)
 
 **`Experimental`**
 
@@ -81,7 +81,7 @@ Prompt the client should send when it starts the session
 optional sessionId?: string;
 ```
 
-Defined in: [packages/ai/src/types.ts:2885](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2885)
+Defined in: [packages/ai/src/types.ts:2900](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2900)
 
 **`Experimental`**
 
@@ -95,7 +95,7 @@ Provider session id, when the adapter created one
 status: "ready" | "waiting";
 ```
 
-Defined in: [packages/ai/src/types.ts:2883](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2883)
+Defined in: [packages/ai/src/types.ts:2898](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2898)
 
 **`Experimental`**
 
@@ -109,7 +109,7 @@ Session status after the server half finishes
 token: string;
 ```
 
-Defined in: [packages/ai/src/types.ts:2877](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2877)
+Defined in: [packages/ai/src/types.ts:2892](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2892)
 
 **`Experimental`**
 
@@ -123,7 +123,7 @@ Short-lived session token. Reactor uses this to connect. fal does not.
 optional usage?: TokenUsage<ProviderUsageDetails>;
 ```
 
-Defined in: [packages/ai/src/types.ts:2887](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2887)
+Defined in: [packages/ai/src/types.ts:2902](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2902)
 
 **`Experimental`**
 
diff --git a/docs/reference/interfaces/MediaInputMetadata.md b/docs/reference/interfaces/MediaInputMetadata.md
index 14aa4f06fc..008e088d45 100644
--- a/docs/reference/interfaces/MediaInputMetadata.md
+++ b/docs/reference/interfaces/MediaInputMetadata.md
@@ -3,7 +3,7 @@ id: MediaInputMetadata
 title: MediaInputMetadata
 ---
 
-Defined in: [packages/ai/src/types.ts:2343](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2343)
+Defined in: [packages/ai/src/types.ts:2358](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2358)
 
 Metadata convention for image / video / audio inputs to media generation.
 Carried on `ImagePart.metadata` / `VideoPart.metadata` / `AudioPart.metadata`
@@ -17,7 +17,7 @@ when used as conditioning inputs to `generateImage()` or `generateVideo()`.
 optional role?: MediaInputRole;
 ```
 
-Defined in: [packages/ai/src/types.ts:2345](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2345)
+Defined in: [packages/ai/src/types.ts:2360](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2360)
 
 Optional role hint disambiguating the part's intent for the adapter
 
@@ -29,7 +29,7 @@ Optional role hint disambiguating the part's intent for the adapter
 optional tag?: string;
 ```
 
-Defined in: [packages/ai/src/types.ts:2354](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2354)
+Defined in: [packages/ai/src/types.ts:2369](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2369)
 
 Optional user-defined label for this input (e.g. `'woman-in-red-dress'`).
 **Informational only** — adapters never read it and the SDK never
diff --git a/docs/reference/interfaces/MessagesSnapshotEvent.md b/docs/reference/interfaces/MessagesSnapshotEvent.md
index 5f4f7b95d7..14fe0a2bfe 100644
--- a/docs/reference/interfaces/MessagesSnapshotEvent.md
+++ b/docs/reference/interfaces/MessagesSnapshotEvent.md
@@ -3,7 +3,7 @@ id: MessagesSnapshotEvent
 title: MessagesSnapshotEvent
 ---
 
-Defined in: [packages/ai/src/types.ts:1791](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1791)
+Defined in: [packages/ai/src/types.ts:1806](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1806)
 
 Emitted to provide a snapshot of all messages in a conversation.
 
diff --git a/docs/reference/interfaces/PersistedArtifactRef.md b/docs/reference/interfaces/PersistedArtifactRef.md
index f0a0c5710d..1f14de6d90 100644
--- a/docs/reference/interfaces/PersistedArtifactRef.md
+++ b/docs/reference/interfaces/PersistedArtifactRef.md
@@ -3,7 +3,7 @@ id: PersistedArtifactRef
 title: PersistedArtifactRef
 ---
 
-Defined in: [packages/ai/src/types.ts:2482](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2482)
+Defined in: [packages/ai/src/types.ts:2497](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2497)
 
 ## Properties
 
@@ -13,7 +13,7 @@ Defined in: [packages/ai/src/types.ts:2482](https://github.com/TanStack/ai/blob/
 artifactId: string;
 ```
 
-Defined in: [packages/ai/src/types.ts:2484](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2484)
+Defined in: [packages/ai/src/types.ts:2499](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2499)
 
 ***
 
@@ -23,7 +23,7 @@ Defined in: [packages/ai/src/types.ts:2484](https://github.com/TanStack/ai/blob/
 createdAt: string;
 ```
 
-Defined in: [packages/ai/src/types.ts:2490](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2490)
+Defined in: [packages/ai/src/types.ts:2505](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2505)
 
 ***
 
@@ -33,7 +33,7 @@ Defined in: [packages/ai/src/types.ts:2490](https://github.com/TanStack/ai/blob/
 mimeType: string;
 ```
 
-Defined in: [packages/ai/src/types.ts:2488](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2488)
+Defined in: [packages/ai/src/types.ts:2503](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2503)
 
 ***
 
@@ -43,7 +43,7 @@ Defined in: [packages/ai/src/types.ts:2488](https://github.com/TanStack/ai/blob/
 name: string;
 ```
 
-Defined in: [packages/ai/src/types.ts:2487](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2487)
+Defined in: [packages/ai/src/types.ts:2502](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2502)
 
 ***
 
@@ -53,7 +53,7 @@ Defined in: [packages/ai/src/types.ts:2487](https://github.com/TanStack/ai/blob/
 role: PersistedArtifactRole;
 ```
 
-Defined in: [packages/ai/src/types.ts:2483](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2483)
+Defined in: [packages/ai/src/types.ts:2498](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2498)
 
 ***
 
@@ -63,7 +63,7 @@ Defined in: [packages/ai/src/types.ts:2483](https://github.com/TanStack/ai/blob/
 runId: string;
 ```
 
-Defined in: [packages/ai/src/types.ts:2486](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2486)
+Defined in: [packages/ai/src/types.ts:2501](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2501)
 
 ***
 
@@ -73,7 +73,7 @@ Defined in: [packages/ai/src/types.ts:2486](https://github.com/TanStack/ai/blob/
 size: number;
 ```
 
-Defined in: [packages/ai/src/types.ts:2489](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2489)
+Defined in: [packages/ai/src/types.ts:2504](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2504)
 
 ***
 
@@ -83,7 +83,7 @@ Defined in: [packages/ai/src/types.ts:2489](https://github.com/TanStack/ai/blob/
 source: object;
 ```
 
-Defined in: [packages/ai/src/types.ts:2506](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2506)
+Defined in: [packages/ai/src/types.ts:2521](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2521)
 
 #### activity
 
@@ -135,7 +135,7 @@ provider: string;
 optional sourceUrl?: string;
 ```
 
-Defined in: [packages/ai/src/types.ts:2497](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2497)
+Defined in: [packages/ai/src/types.ts:2512](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2512)
 
 Where these bytes were fetched FROM — the provider's original result URL,
 or a caller-supplied prompt URL when `allowInputUrl` opted that in. Usually
@@ -150,7 +150,7 @@ instead.
 threadId: string;
 ```
 
-Defined in: [packages/ai/src/types.ts:2485](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2485)
+Defined in: [packages/ai/src/types.ts:2500](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2500)
 
 ***
 
@@ -160,7 +160,7 @@ Defined in: [packages/ai/src/types.ts:2485](https://github.com/TanStack/ai/blob/
 optional url?: string;
 ```
 
-Defined in: [packages/ai/src/types.ts:2505](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2505)
+Defined in: [packages/ai/src/types.ts:2520](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2520)
 
 Durable app-origin URL that serves this artifact's persisted bytes (your
 `GET` route around `retrieveArtifact` / `retrieveBlob`). Stamped by
diff --git a/docs/reference/interfaces/ProviderTool.md b/docs/reference/interfaces/ProviderTool.md
index d1ead35173..77390f3732 100644
--- a/docs/reference/interfaces/ProviderTool.md
+++ b/docs/reference/interfaces/ProviderTool.md
@@ -63,7 +63,7 @@ Defined in: [packages/ai/src/tools/provider-tool.ts:24](https://github.com/TanSt
 description: string;
 ```
 
-Defined in: [packages/ai/src/types.ts:1029](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1029)
+Defined in: [packages/ai/src/types.ts:1044](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1044)
 
 Clear description of what the tool does.
 
@@ -88,7 +88,7 @@ Be specific about what the tool does, what parameters it needs, and what it retu
 optional execute?: (args, context?) => any;
 ```
 
-Defined in: [packages/ai/src/types.ts:1109](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1109)
+Defined in: [packages/ai/src/types.ts:1124](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1124)
 
 Optional function to execute when the model calls this tool.
 
@@ -136,7 +136,7 @@ execute: async (args) => {
 optional inputSchema?: SchemaInput;
 ```
 
-Defined in: [packages/ai/src/types.ts:1069](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1069)
+Defined in: [packages/ai/src/types.ts:1084](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1084)
 
 Schema describing the tool's input parameters.
 
@@ -194,7 +194,7 @@ type({
 optional lazy?: boolean;
 ```
 
-Defined in: [packages/ai/src/types.ts:1115](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1115)
+Defined in: [packages/ai/src/types.ts:1130](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1130)
 
 If true, this tool is lazy and will only be sent to the LLM after being discovered via the lazy tool discovery mechanism. Works with both chat() (the synthetic discovery tool) and Code Mode (kept out of the system prompt and revealed via discover_tools).
 
@@ -210,7 +210,7 @@ If true, this tool is lazy and will only be sent to the LLM after being discover
 optional metadata?: Record<string, any>;
 ```
 
-Defined in: [packages/ai/src/types.ts:1126](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1126)
+Defined in: [packages/ai/src/types.ts:1141](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1141)
 
 Additional metadata for adapters or custom extensions
 
@@ -226,7 +226,7 @@ Additional metadata for adapters or custom extensions
 name: string;
 ```
 
-Defined in: [packages/ai/src/types.ts:1019](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1019)
+Defined in: [packages/ai/src/types.ts:1034](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1034)
 
 Unique name of the tool (used by the model to call it).
 
@@ -251,7 +251,7 @@ Must be unique within the tools array.
 optional needsApproval?: boolean;
 ```
 
-Defined in: [packages/ai/src/types.ts:1112](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1112)
+Defined in: [packages/ai/src/types.ts:1127](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1127)
 
 If true, tool execution requires user approval before running. Works with both server and client tools.
 
@@ -267,7 +267,7 @@ If true, tool execution requires user approval before running. Works with both s
 optional outputSchema?: SchemaInput;
 ```
 
-Defined in: [packages/ai/src/types.ts:1090](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1090)
+Defined in: [packages/ai/src/types.ts:1105](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1105)
 
 Optional schema for validating tool output.
 
@@ -302,7 +302,7 @@ z.object({
 optional replay?: "safe" | "never";
 ```
 
-Defined in: [packages/ai/src/types.ts:1123](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1123)
+Defined in: [packages/ai/src/types.ts:1138](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1138)
 
 Whether a host may run this tool again after a crash cut the run
 between the call and its result. `'safe'` runs it again. Omit the
diff --git a/docs/reference/interfaces/RawEvent.md b/docs/reference/interfaces/RawEvent.md
index af56d5666a..366d4df232 100644
--- a/docs/reference/interfaces/RawEvent.md
+++ b/docs/reference/interfaces/RawEvent.md
@@ -3,7 +3,7 @@ id: RawEvent
 title: RawEvent
 ---
 
-Defined in: [packages/ai/src/types.ts:2096](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2096)
+Defined in: [packages/ai/src/types.ts:2111](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2111)
 
 AG-UI 1.0 RawEvent shape.
 
diff --git a/docs/reference/interfaces/ReasoningEncryptedValueEvent.md b/docs/reference/interfaces/ReasoningEncryptedValueEvent.md
index 5caa608bc9..1a5569f3a4 100644
--- a/docs/reference/interfaces/ReasoningEncryptedValueEvent.md
+++ b/docs/reference/interfaces/ReasoningEncryptedValueEvent.md
@@ -3,7 +3,7 @@ id: ReasoningEncryptedValueEvent
 title: ReasoningEncryptedValueEvent
 ---
 
-Defined in: [packages/ai/src/types.ts:2067](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2067)
+Defined in: [packages/ai/src/types.ts:2082](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2082)
 
 Emitted for encrypted reasoning values.
 
diff --git a/docs/reference/interfaces/ReasoningEndEvent.md b/docs/reference/interfaces/ReasoningEndEvent.md
index 466e2072c1..2e97b79321 100644
--- a/docs/reference/interfaces/ReasoningEndEvent.md
+++ b/docs/reference/interfaces/ReasoningEndEvent.md
@@ -3,7 +3,7 @@ id: ReasoningEndEvent
 title: ReasoningEndEvent
 ---
 
-Defined in: [packages/ai/src/types.ts:2060](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2060)
+Defined in: [packages/ai/src/types.ts:2075](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2075)
 
 Emitted when reasoning ends for a message.
 
diff --git a/docs/reference/interfaces/ReasoningMessageChunkEvent.md b/docs/reference/interfaces/ReasoningMessageChunkEvent.md
index e9b51e4d2a..fcd8129f45 100644
--- a/docs/reference/interfaces/ReasoningMessageChunkEvent.md
+++ b/docs/reference/interfaces/ReasoningMessageChunkEvent.md
@@ -3,7 +3,7 @@ id: ReasoningMessageChunkEvent
 title: ReasoningMessageChunkEvent
 ---
 
-Defined in: [packages/ai/src/types.ts:2105](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2105)
+Defined in: [packages/ai/src/types.ts:2120](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2120)
 
 AG-UI 1.0 ReasoningMessageChunkEvent shape.
 
diff --git a/docs/reference/interfaces/ReasoningMessageContentEvent.md b/docs/reference/interfaces/ReasoningMessageContentEvent.md
index 6fd3c42088..3c2ae420f8 100644
--- a/docs/reference/interfaces/ReasoningMessageContentEvent.md
+++ b/docs/reference/interfaces/ReasoningMessageContentEvent.md
@@ -3,7 +3,7 @@ id: ReasoningMessageContentEvent
 title: ReasoningMessageContentEvent
 ---
 
-Defined in: [packages/ai/src/types.ts:2046](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2046)
+Defined in: [packages/ai/src/types.ts:2061](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2061)
 
 Emitted when reasoning message content is generated.
 
diff --git a/docs/reference/interfaces/ReasoningMessageEndEvent.md b/docs/reference/interfaces/ReasoningMessageEndEvent.md
index 27247194a3..10ab0880df 100644
--- a/docs/reference/interfaces/ReasoningMessageEndEvent.md
+++ b/docs/reference/interfaces/ReasoningMessageEndEvent.md
@@ -3,7 +3,7 @@ id: ReasoningMessageEndEvent
 title: ReasoningMessageEndEvent
 ---
 
-Defined in: [packages/ai/src/types.ts:2053](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2053)
+Defined in: [packages/ai/src/types.ts:2068](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2068)
 
 Emitted when a reasoning message ends.
 
diff --git a/docs/reference/interfaces/ReasoningMessageStartEvent.md b/docs/reference/interfaces/ReasoningMessageStartEvent.md
index 4b912c3691..381b4d6d4c 100644
--- a/docs/reference/interfaces/ReasoningMessageStartEvent.md
+++ b/docs/reference/interfaces/ReasoningMessageStartEvent.md
@@ -3,7 +3,7 @@ id: ReasoningMessageStartEvent
 title: ReasoningMessageStartEvent
 ---
 
-Defined in: [packages/ai/src/types.ts:2039](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2039)
+Defined in: [packages/ai/src/types.ts:2054](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2054)
 
 Emitted when a reasoning message starts.
 
diff --git a/docs/reference/interfaces/ReasoningStartEvent.md b/docs/reference/interfaces/ReasoningStartEvent.md
index e6fa2dacae..40e50f936c 100644
--- a/docs/reference/interfaces/ReasoningStartEvent.md
+++ b/docs/reference/interfaces/ReasoningStartEvent.md
@@ -3,7 +3,7 @@ id: ReasoningStartEvent
 title: ReasoningStartEvent
 ---
 
-Defined in: [packages/ai/src/types.ts:2032](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2032)
+Defined in: [packages/ai/src/types.ts:2047](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2047)
 
 Emitted when reasoning starts for a message.
 
diff --git a/docs/reference/interfaces/RerankAdapterResult.md b/docs/reference/interfaces/RerankAdapterResult.md
index 349e46e86d..8f047595df 100644
--- a/docs/reference/interfaces/RerankAdapterResult.md
+++ b/docs/reference/interfaces/RerankAdapterResult.md
@@ -3,7 +3,7 @@ id: RerankAdapterResult
 title: RerankAdapterResult
 ---
 
-Defined in: [packages/ai/src/types.ts:2291](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2291)
+Defined in: [packages/ai/src/types.ts:2306](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2306)
 
 Provider-level rerank result. Adapters return scored indices into the
 (serialized) `documents` array plus usage — never the documents themselves.
@@ -17,7 +17,7 @@ The activity attaches the original documents.
 id: string;
 ```
 
-Defined in: [packages/ai/src/types.ts:2292](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2292)
+Defined in: [packages/ai/src/types.ts:2307](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2307)
 
 ***
 
@@ -27,7 +27,7 @@ Defined in: [packages/ai/src/types.ts:2292](https://github.com/TanStack/ai/blob/
 ranking: object[];
 ```
 
-Defined in: [packages/ai/src/types.ts:2294](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2294)
+Defined in: [packages/ai/src/types.ts:2309](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2309)
 
 Scored results, highest relevance first, as indices into `documents`.
 
@@ -51,4 +51,4 @@ score: number;
 usage: TokenUsage;
 ```
 
-Defined in: [packages/ai/src/types.ts:2295](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2295)
+Defined in: [packages/ai/src/types.ts:2310](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2310)
diff --git a/docs/reference/interfaces/RerankOptions.md b/docs/reference/interfaces/RerankOptions.md
index f37b10185c..ed17d4dbb7 100644
--- a/docs/reference/interfaces/RerankOptions.md
+++ b/docs/reference/interfaces/RerankOptions.md
@@ -3,7 +3,7 @@ id: RerankOptions
 title: RerankOptions
 ---
 
-Defined in: [packages/ai/src/types.ts:2264](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2264)
+Defined in: [packages/ai/src/types.ts:2279](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2279)
 
 Options passed to a [RerankAdapter](RerankAdapter.md). Documents reach the adapter
 already serialized to strings — the `rerank()` activity stringifies object
@@ -24,7 +24,7 @@ deal with the caller's document type.
 optional abortSignal?: AbortSignal;
 ```
 
-Defined in: [packages/ai/src/types.ts:2277](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2277)
+Defined in: [packages/ai/src/types.ts:2292](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2292)
 
 Forwarded to the provider request for cancellation.
 
@@ -36,7 +36,7 @@ Forwarded to the provider request for cancellation.
 documents: string[];
 ```
 
-Defined in: [packages/ai/src/types.ts:2271](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2271)
+Defined in: [packages/ai/src/types.ts:2286](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2286)
 
 Documents to rerank, pre-serialized to strings by the activity.
 
@@ -48,7 +48,7 @@ Documents to rerank, pre-serialized to strings by the activity.
 logger: InternalLogger;
 ```
 
-Defined in: [packages/ai/src/types.ts:2283](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2283)
+Defined in: [packages/ai/src/types.ts:2298](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2298)
 
 Internal logger threaded from the rerank() entry point. Adapters must call
 logger.request() before the provider call and logger.errors() in catch
@@ -62,7 +62,7 @@ blocks.
 model: string;
 ```
 
-Defined in: [packages/ai/src/types.ts:2267](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2267)
+Defined in: [packages/ai/src/types.ts:2282](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2282)
 
 ***
 
@@ -72,7 +72,7 @@ Defined in: [packages/ai/src/types.ts:2267](https://github.com/TanStack/ai/blob/
 optional modelOptions?: TProviderOptions;
 ```
 
-Defined in: [packages/ai/src/types.ts:2275](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2275)
+Defined in: [packages/ai/src/types.ts:2290](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2290)
 
 Provider-specific options forwarded by the rerank() activity.
 
@@ -84,7 +84,7 @@ Provider-specific options forwarded by the rerank() activity.
 query: string;
 ```
 
-Defined in: [packages/ai/src/types.ts:2269](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2269)
+Defined in: [packages/ai/src/types.ts:2284](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2284)
 
 The search query documents are scored against.
 
@@ -96,6 +96,6 @@ The search query documents are scored against.
 optional topN?: number;
 ```
 
-Defined in: [packages/ai/src/types.ts:2273](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2273)
+Defined in: [packages/ai/src/types.ts:2288](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2288)
 
 Return only the top N results. Passed through to the provider.
diff --git a/docs/reference/interfaces/RerankResult.md b/docs/reference/interfaces/RerankResult.md
index 14f35aad72..1913ee3b47 100644
--- a/docs/reference/interfaces/RerankResult.md
+++ b/docs/reference/interfaces/RerankResult.md
@@ -3,7 +3,7 @@ id: RerankResult
 title: RerankResult
 ---
 
-Defined in: [packages/ai/src/types.ts:2303](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2303)
+Defined in: [packages/ai/src/types.ts:2318](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2318)
 
 Public result of the `rerank()` activity, generic over the caller's document
 element type so `document` / `rerankedDocuments` carry the original values
@@ -23,7 +23,7 @@ element type so `document` / `rerankedDocuments` carry the original values
 id: string;
 ```
 
-Defined in: [packages/ai/src/types.ts:2304](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2304)
+Defined in: [packages/ai/src/types.ts:2319](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2319)
 
 ***
 
@@ -33,7 +33,7 @@ Defined in: [packages/ai/src/types.ts:2304](https://github.com/TanStack/ai/blob/
 model: string;
 ```
 
-Defined in: [packages/ai/src/types.ts:2305](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2305)
+Defined in: [packages/ai/src/types.ts:2320](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2320)
 
 ***
 
@@ -43,7 +43,7 @@ Defined in: [packages/ai/src/types.ts:2305](https://github.com/TanStack/ai/blob/
 ranking: object[];
 ```
 
-Defined in: [packages/ai/src/types.ts:2307](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2307)
+Defined in: [packages/ai/src/types.ts:2322](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2322)
 
 Scored results, highest relevance first.
 
@@ -73,7 +73,7 @@ score: number;
 rerankedDocuments: TDocument[];
 ```
 
-Defined in: [packages/ai/src/types.ts:2309](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2309)
+Defined in: [packages/ai/src/types.ts:2324](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2324)
 
 The documents reordered by relevance — `ranking.map(r => r.document)`.
 
@@ -85,7 +85,7 @@ The documents reordered by relevance — `ranking.map(r => r.document)`.
 usage: TokenUsage;
 ```
 
-Defined in: [packages/ai/src/types.ts:2316](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2316)
+Defined in: [packages/ai/src/types.ts:2331](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2331)
 
 Usage for the request. Rerank typically bills in provider-defined "search
 units" (`usage.billed = { quantity, unit: 'units' }`) rather than tokens.
diff --git a/docs/reference/interfaces/ResolvedPromptCache.md b/docs/reference/interfaces/ResolvedPromptCache.md
index 66141f41fc..8e036f7e82 100644
--- a/docs/reference/interfaces/ResolvedPromptCache.md
+++ b/docs/reference/interfaces/ResolvedPromptCache.md
@@ -3,7 +3,7 @@ id: ResolvedPromptCache
 title: ResolvedPromptCache
 ---
 
-Defined in: [packages/ai/src/types.ts:1317](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1317)
+Defined in: [packages/ai/src/types.ts:1332](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1332)
 
 What chat() gives the adapter.
 
@@ -15,7 +15,7 @@ What chat() gives the adapter.
 optional key?: string;
 ```
 
-Defined in: [packages/ai/src/types.ts:1319](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1319)
+Defined in: [packages/ai/src/types.ts:1334](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1334)
 
 ***
 
@@ -25,4 +25,4 @@ Defined in: [packages/ai/src/types.ts:1319](https://github.com/TanStack/ai/blob/
 retention: PromptCacheRetention;
 ```
 
-Defined in: [packages/ai/src/types.ts:1318](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1318)
+Defined in: [packages/ai/src/types.ts:1333](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1333)
diff --git a/docs/reference/interfaces/ResponseFormat.md b/docs/reference/interfaces/ResponseFormat.md
index b4db476599..75ef218070 100644
--- a/docs/reference/interfaces/ResponseFormat.md
+++ b/docs/reference/interfaces/ResponseFormat.md
@@ -3,7 +3,7 @@ id: ResponseFormat
 title: ResponseFormat
 ---
 
-Defined in: [packages/ai/src/types.ts:1164](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1164)
+Defined in: [packages/ai/src/types.ts:1179](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1179)
 
 Structured output format specification.
 
@@ -31,7 +31,7 @@ TypeScript type of the expected data structure (for type safety)
 optional __data?: TData;
 ```
 
-Defined in: [packages/ai/src/types.ts:1242](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1242)
+Defined in: [packages/ai/src/types.ts:1257](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1257)
 
 **`Internal`**
 
@@ -48,7 +48,7 @@ Allows the SDK to know what type to expect when parsing the response.
 optional json_schema?: object;
 ```
 
-Defined in: [packages/ai/src/types.ts:1181](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1181)
+Defined in: [packages/ai/src/types.ts:1196](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1196)
 
 JSON schema specification (required when type is "json_schema").
 
@@ -137,7 +137,7 @@ https://platform.openai.com/docs/guides/structured-outputs#strict-mode
 type: "json_object" | "json_schema";
 ```
 
-Defined in: [packages/ai/src/types.ts:1173](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1173)
+Defined in: [packages/ai/src/types.ts:1188](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1188)
 
 Type of structured output.
 
diff --git a/docs/reference/interfaces/RunErrorEvent.md b/docs/reference/interfaces/RunErrorEvent.md
index 97c5615687..83b98f62a2 100644
--- a/docs/reference/interfaces/RunErrorEvent.md
+++ b/docs/reference/interfaces/RunErrorEvent.md
@@ -3,7 +3,7 @@ id: RunErrorEvent
 title: RunErrorEvent
 ---
 
-Defined in: [packages/ai/src/types.ts:1663](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1663)
+Defined in: [packages/ai/src/types.ts:1678](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1678)
 
 Emitted when an error occurs during a run.
 
@@ -23,7 +23,7 @@ Spec `usage[]` is provider/model token counts. Interrupt errors live in
 optional error?: object;
 ```
 
-Defined in: [packages/ai/src/types.ts:1676](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1676)
+Defined in: [packages/ai/src/types.ts:1691](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1691)
 
 Nested payload kept for in-process / durability consumers.
 
@@ -47,7 +47,7 @@ message: string;
 optional errorType?: string;
 ```
 
-Defined in: [packages/ai/src/types.ts:1694](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1694)
+Defined in: [packages/ai/src/types.ts:1709](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1709)
 
 The provider's error type, for example `overloaded_error` or
 `rate_limit_exceeded`. `code` stays the HTTP status. A string of at most
@@ -61,7 +61,7 @@ The provider's error type, for example `overloaded_error` or
 optional metadata?: object & Record<string, any>;
 ```
 
-Defined in: [packages/ai/src/types.ts:1701](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1701)
+Defined in: [packages/ai/src/types.ts:1716](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1716)
 
 #### Type Declaration
 
@@ -79,7 +79,7 @@ optional tanstack?: TanStackRunMetadata;
 optional model?: string;
 ```
 
-Defined in: [packages/ai/src/types.ts:1674](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1674)
+Defined in: [packages/ai/src/types.ts:1689](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1689)
 
 Restored on the client from `metadata.tanstack`.
 
@@ -91,7 +91,7 @@ Restored on the client from `metadata.tanstack`.
 optional rawText?: string;
 ```
 
-Defined in: [packages/ai/src/types.ts:1682](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1682)
+Defined in: [packages/ai/src/types.ts:1697](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1697)
 
 The model text of a failed structured output: JSON that did not parse,
 or a value that failed the `outputSchema` check. `chat()` moves it to
@@ -105,7 +105,7 @@ or a value that failed the `outputSchema` check. `chat()` moves it to
 optional requestId?: string;
 ```
 
-Defined in: [packages/ai/src/types.ts:1700](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1700)
+Defined in: [packages/ai/src/types.ts:1715](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1715)
 
 The provider's request id, from the SDK error or the `request-id` /
 `x-request-id` header. Give it to the provider's support.
@@ -119,7 +119,7 @@ The provider's request id, from the SDK error or the `request-id` /
 optional retryAfterMs?: number;
 ```
 
-Defined in: [packages/ai/src/types.ts:1688](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1688)
+Defined in: [packages/ai/src/types.ts:1703](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1703)
 
 How long the provider asks you to wait before a retry, in milliseconds.
 Adapters read it from the `retry-after-ms` or `retry-after` header.
@@ -133,7 +133,7 @@ Adapters read it from the `retry-after-ms` or `retry-after` header.
 optional runId?: string;
 ```
 
-Defined in: [packages/ai/src/types.ts:1672](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1672)
+Defined in: [packages/ai/src/types.ts:1687](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1687)
 
 Restored on the client from `metadata.tanstack`.
 
@@ -145,7 +145,7 @@ Restored on the client from `metadata.tanstack`.
 optional threadId?: string;
 ```
 
-Defined in: [packages/ai/src/types.ts:1670](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1670)
+Defined in: [packages/ai/src/types.ts:1685](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1685)
 
 Restored on the client from `metadata.tanstack`.
 
@@ -157,7 +157,7 @@ Restored on the client from `metadata.tanstack`.
 type: RUN_ERROR;
 ```
 
-Defined in: [packages/ai/src/types.ts:1667](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1667)
+Defined in: [packages/ai/src/types.ts:1682](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1682)
 
 ***
 
@@ -167,4 +167,4 @@ Defined in: [packages/ai/src/types.ts:1667](https://github.com/TanStack/ai/blob/
 optional usage?: TokenUsage<ProviderUsageDetails> | TokenUsage[];
 ```
 
-Defined in: [packages/ai/src/types.ts:1668](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1668)
+Defined in: [packages/ai/src/types.ts:1683](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1683)
diff --git a/docs/reference/interfaces/RunFinishedEvent.md b/docs/reference/interfaces/RunFinishedEvent.md
index 205c4e8fd5..cb3b1ab265 100644
--- a/docs/reference/interfaces/RunFinishedEvent.md
+++ b/docs/reference/interfaces/RunFinishedEvent.md
@@ -3,7 +3,7 @@ id: RunFinishedEvent
 title: RunFinishedEvent
 ---
 
-Defined in: [packages/ai/src/types.ts:1641](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1641)
+Defined in: [packages/ai/src/types.ts:1656](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1656)
 
 Emitted when a run completes successfully.
 
@@ -23,7 +23,7 @@ Spec `usage[]` is provider/model token counts. TanStack leftovers live in
 optional finishReason?: "length" | "stop" | "content_filter" | "tool_calls" | null;
 ```
 
-Defined in: [packages/ai/src/types.ts:1652](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1652)
+Defined in: [packages/ai/src/types.ts:1667](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1667)
 
 Restored on the client from `metadata.tanstack`.
 
@@ -35,7 +35,7 @@ Restored on the client from `metadata.tanstack`.
 optional metadata?: object & Record<string, any>;
 ```
 
-Defined in: [packages/ai/src/types.ts:1653](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1653)
+Defined in: [packages/ai/src/types.ts:1668](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1668)
 
 #### Type Declaration
 
@@ -53,7 +53,7 @@ optional tanstack?: TanStackRunMetadata;
 optional model?: string;
 ```
 
-Defined in: [packages/ai/src/types.ts:1648](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1648)
+Defined in: [packages/ai/src/types.ts:1663](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1663)
 
 Restored on the client from `metadata.tanstack`.
 
@@ -65,7 +65,7 @@ Restored on the client from `metadata.tanstack`.
 optional responseId?: string;
 ```
 
-Defined in: [packages/ai/src/types.ts:1650](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1650)
+Defined in: [packages/ai/src/types.ts:1665](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1665)
 
 Provider generation ID. Restored from `metadata.tanstack`.
 
@@ -77,7 +77,7 @@ Provider generation ID. Restored from `metadata.tanstack`.
 type: RUN_FINISHED;
 ```
 
-Defined in: [packages/ai/src/types.ts:1645](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1645)
+Defined in: [packages/ai/src/types.ts:1660](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1660)
 
 ***
 
@@ -87,4 +87,4 @@ Defined in: [packages/ai/src/types.ts:1645](https://github.com/TanStack/ai/blob/
 optional usage?: TokenUsage<ProviderUsageDetails> | TokenUsage[];
 ```
 
-Defined in: [packages/ai/src/types.ts:1646](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1646)
+Defined in: [packages/ai/src/types.ts:1661](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1661)
diff --git a/docs/reference/interfaces/RunStartedEvent.md b/docs/reference/interfaces/RunStartedEvent.md
index fe05438b94..9bba780bd6 100644
--- a/docs/reference/interfaces/RunStartedEvent.md
+++ b/docs/reference/interfaces/RunStartedEvent.md
@@ -3,7 +3,7 @@ id: RunStartedEvent
 title: RunStartedEvent
 ---
 
-Defined in: [packages/ai/src/types.ts:1611](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1611)
+Defined in: [packages/ai/src/types.ts:1626](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1626)
 
 Emitted when a run starts.
 This is the first event in any streaming response.
diff --git a/docs/reference/interfaces/SandboxCreatedEvent.md b/docs/reference/interfaces/SandboxCreatedEvent.md
index 81859cceea..3e654493b8 100644
--- a/docs/reference/interfaces/SandboxCreatedEvent.md
+++ b/docs/reference/interfaces/SandboxCreatedEvent.md
@@ -3,7 +3,7 @@ id: SandboxCreatedEvent
 title: SandboxCreatedEvent
 ---
 
-Defined in: [packages/ai/src/types.ts:1887](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1887)
+Defined in: [packages/ai/src/types.ts:1902](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1902)
 
 `withSandbox` sends this after it creates a new sandbox.
 
@@ -19,7 +19,7 @@ Defined in: [packages/ai/src/types.ts:1887](https://github.com/TanStack/ai/blob/
 optional metadata?: Record<string, any>;
 ```
 
-Defined in: [packages/ai/src/types.ts:1814](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1814)
+Defined in: [packages/ai/src/types.ts:1829](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1829)
 
 Extra information attached to this event.
 
@@ -35,7 +35,7 @@ Extra information attached to this event.
 name: "sandbox.created";
 ```
 
-Defined in: [packages/ai/src/types.ts:1888](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1888)
+Defined in: [packages/ai/src/types.ts:1903](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1903)
 
 What this custom event is. Required: without it a consumer cannot route
 the value.
@@ -54,7 +54,7 @@ CustomEvent.name
 type: "CUSTOM";
 ```
 
-Defined in: [packages/ai/src/types.ts:1813](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1813)
+Defined in: [packages/ai/src/types.ts:1828](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1828)
 
 #### Inherited from
 
@@ -68,7 +68,7 @@ Defined in: [packages/ai/src/types.ts:1813](https://github.com/TanStack/ai/blob/
 value: object;
 ```
 
-Defined in: [packages/ai/src/types.ts:1889](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1889)
+Defined in: [packages/ai/src/types.ts:1904](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1904)
 
 The payload. Any JSON value, and required.
 
diff --git a/docs/reference/interfaces/SandboxFileCustomEvent.md b/docs/reference/interfaces/SandboxFileCustomEvent.md
index 4635353730..cdc55f82d3 100644
--- a/docs/reference/interfaces/SandboxFileCustomEvent.md
+++ b/docs/reference/interfaces/SandboxFileCustomEvent.md
@@ -3,7 +3,7 @@ id: SandboxFileCustomEvent
 title: SandboxFileCustomEvent
 ---
 
-Defined in: [packages/ai/src/types.ts:1869](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1869)
+Defined in: [packages/ai/src/types.ts:1884](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1884)
 
 Custom event for extensibility.
 
@@ -21,7 +21,7 @@ Custom event for extensibility.
 optional metadata?: Record<string, any>;
 ```
 
-Defined in: [packages/ai/src/types.ts:1814](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1814)
+Defined in: [packages/ai/src/types.ts:1829](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1829)
 
 Extra information attached to this event.
 
@@ -37,7 +37,7 @@ Extra information attached to this event.
 name: "sandbox.file";
 ```
 
-Defined in: [packages/ai/src/types.ts:1870](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1870)
+Defined in: [packages/ai/src/types.ts:1885](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1885)
 
 What this custom event is. Required: without it a consumer cannot route
 the value.
@@ -56,7 +56,7 @@ CustomEvent.name
 type: "CUSTOM";
 ```
 
-Defined in: [packages/ai/src/types.ts:1813](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1813)
+Defined in: [packages/ai/src/types.ts:1828](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1828)
 
 #### Inherited from
 
@@ -70,7 +70,7 @@ Defined in: [packages/ai/src/types.ts:1813](https://github.com/TanStack/ai/blob/
 value: object;
 ```
 
-Defined in: [packages/ai/src/types.ts:1871](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1871)
+Defined in: [packages/ai/src/types.ts:1886](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1886)
 
 The payload. Any JSON value, and required.
 
diff --git a/docs/reference/interfaces/SandboxFileDiffEvent.md b/docs/reference/interfaces/SandboxFileDiffEvent.md
index 7bfd28477f..8e847c800d 100644
--- a/docs/reference/interfaces/SandboxFileDiffEvent.md
+++ b/docs/reference/interfaces/SandboxFileDiffEvent.md
@@ -3,7 +3,7 @@ id: SandboxFileDiffEvent
 title: SandboxFileDiffEvent
 ---
 
-Defined in: [packages/ai/src/types.ts:1877](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1877)
+Defined in: [packages/ai/src/types.ts:1892](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1892)
 
 Custom event for extensibility.
 
@@ -21,7 +21,7 @@ Custom event for extensibility.
 optional metadata?: Record<string, any>;
 ```
 
-Defined in: [packages/ai/src/types.ts:1814](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1814)
+Defined in: [packages/ai/src/types.ts:1829](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1829)
 
 Extra information attached to this event.
 
@@ -37,7 +37,7 @@ Extra information attached to this event.
 name: "sandbox.file.diff";
 ```
 
-Defined in: [packages/ai/src/types.ts:1878](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1878)
+Defined in: [packages/ai/src/types.ts:1893](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1893)
 
 What this custom event is. Required: without it a consumer cannot route
 the value.
@@ -56,7 +56,7 @@ CustomEvent.name
 type: "CUSTOM";
 ```
 
-Defined in: [packages/ai/src/types.ts:1813](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1813)
+Defined in: [packages/ai/src/types.ts:1828](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1828)
 
 #### Inherited from
 
@@ -70,7 +70,7 @@ Defined in: [packages/ai/src/types.ts:1813](https://github.com/TanStack/ai/blob/
 value: object;
 ```
 
-Defined in: [packages/ai/src/types.ts:1879](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1879)
+Defined in: [packages/ai/src/types.ts:1894](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1894)
 
 The payload. Any JSON value, and required.
 
diff --git a/docs/reference/interfaces/SandboxResumedEvent.md b/docs/reference/interfaces/SandboxResumedEvent.md
index 9495a743fe..cc3e8949f3 100644
--- a/docs/reference/interfaces/SandboxResumedEvent.md
+++ b/docs/reference/interfaces/SandboxResumedEvent.md
@@ -3,7 +3,7 @@ id: SandboxResumedEvent
 title: SandboxResumedEvent
 ---
 
-Defined in: [packages/ai/src/types.ts:1892](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1892)
+Defined in: [packages/ai/src/types.ts:1907](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1907)
 
 `withSandbox` sends this after it resumes an existing sandbox.
 
@@ -19,7 +19,7 @@ Defined in: [packages/ai/src/types.ts:1892](https://github.com/TanStack/ai/blob/
 optional metadata?: Record<string, any>;
 ```
 
-Defined in: [packages/ai/src/types.ts:1814](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1814)
+Defined in: [packages/ai/src/types.ts:1829](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1829)
 
 Extra information attached to this event.
 
@@ -35,7 +35,7 @@ Extra information attached to this event.
 name: "sandbox.resumed";
 ```
 
-Defined in: [packages/ai/src/types.ts:1893](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1893)
+Defined in: [packages/ai/src/types.ts:1908](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1908)
 
 What this custom event is. Required: without it a consumer cannot route
 the value.
@@ -54,7 +54,7 @@ CustomEvent.name
 type: "CUSTOM";
 ```
 
-Defined in: [packages/ai/src/types.ts:1813](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1813)
+Defined in: [packages/ai/src/types.ts:1828](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1828)
 
 #### Inherited from
 
@@ -68,7 +68,7 @@ Defined in: [packages/ai/src/types.ts:1813](https://github.com/TanStack/ai/blob/
 value: object;
 ```
 
-Defined in: [packages/ai/src/types.ts:1894](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1894)
+Defined in: [packages/ai/src/types.ts:1909](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1909)
 
 The payload. Any JSON value, and required.
 
diff --git a/docs/reference/interfaces/SandboxStartingEvent.md b/docs/reference/interfaces/SandboxStartingEvent.md
index 72865c27cb..2bbaaabf87 100644
--- a/docs/reference/interfaces/SandboxStartingEvent.md
+++ b/docs/reference/interfaces/SandboxStartingEvent.md
@@ -3,7 +3,7 @@ id: SandboxStartingEvent
 title: SandboxStartingEvent
 ---
 
-Defined in: [packages/ai/src/types.ts:1882](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1882)
+Defined in: [packages/ai/src/types.ts:1897](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1897)
 
 `withSandbox` sends this before it creates or resumes the sandbox.
 
@@ -19,7 +19,7 @@ Defined in: [packages/ai/src/types.ts:1882](https://github.com/TanStack/ai/blob/
 optional metadata?: Record<string, any>;
 ```
 
-Defined in: [packages/ai/src/types.ts:1814](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1814)
+Defined in: [packages/ai/src/types.ts:1829](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1829)
 
 Extra information attached to this event.
 
@@ -35,7 +35,7 @@ Extra information attached to this event.
 name: "sandbox.starting";
 ```
 
-Defined in: [packages/ai/src/types.ts:1883](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1883)
+Defined in: [packages/ai/src/types.ts:1898](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1898)
 
 What this custom event is. Required: without it a consumer cannot route
 the value.
@@ -54,7 +54,7 @@ CustomEvent.name
 type: "CUSTOM";
 ```
 
-Defined in: [packages/ai/src/types.ts:1813](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1813)
+Defined in: [packages/ai/src/types.ts:1828](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1828)
 
 #### Inherited from
 
@@ -68,7 +68,7 @@ Defined in: [packages/ai/src/types.ts:1813](https://github.com/TanStack/ai/blob/
 value: object;
 ```
 
-Defined in: [packages/ai/src/types.ts:1884](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1884)
+Defined in: [packages/ai/src/types.ts:1899](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1899)
 
 The payload. Any JSON value, and required.
 
diff --git a/docs/reference/interfaces/ServerTool.md b/docs/reference/interfaces/ServerTool.md
index 67f32d5fac..afafb72ef5 100644
--- a/docs/reference/interfaces/ServerTool.md
+++ b/docs/reference/interfaces/ServerTool.md
@@ -95,7 +95,7 @@ Defined in: [packages/ai/src/activities/chat/tools/tool-definition.ts:101](https
 description: string;
 ```
 
-Defined in: [packages/ai/src/types.ts:1029](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1029)
+Defined in: [packages/ai/src/types.ts:1044](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1044)
 
 Clear description of what the tool does.
 
@@ -120,7 +120,7 @@ Be specific about what the tool does, what parameters it needs, and what it retu
 optional execute?: ToolExecuteFunction<TInput, TOutput, TContext>;
 ```
 
-Defined in: [packages/ai/src/types.ts:1109](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1109)
+Defined in: [packages/ai/src/types.ts:1124](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1124)
 
 Optional function to execute when the model calls this tool.
 
@@ -228,7 +228,7 @@ type({
 optional lazy?: boolean;
 ```
 
-Defined in: [packages/ai/src/types.ts:1115](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1115)
+Defined in: [packages/ai/src/types.ts:1130](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1130)
 
 If true, this tool is lazy and will only be sent to the LLM after being discovered via the lazy tool discovery mechanism. Works with both chat() (the synthetic discovery tool) and Code Mode (kept out of the system prompt and revealed via discover_tools).
 
@@ -244,7 +244,7 @@ If true, this tool is lazy and will only be sent to the LLM after being discover
 optional metadata?: Record<string, any>;
 ```
 
-Defined in: [packages/ai/src/types.ts:1126](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1126)
+Defined in: [packages/ai/src/types.ts:1141](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1141)
 
 Additional metadata for adapters or custom extensions
 
@@ -260,7 +260,7 @@ Additional metadata for adapters or custom extensions
 name: TName;
 ```
 
-Defined in: [packages/ai/src/types.ts:1019](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1019)
+Defined in: [packages/ai/src/types.ts:1034](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1034)
 
 Unique name of the tool (used by the model to call it).
 
@@ -336,7 +336,7 @@ z.object({
 optional replay?: "safe" | "never";
 ```
 
-Defined in: [packages/ai/src/types.ts:1123](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1123)
+Defined in: [packages/ai/src/types.ts:1138](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1138)
 
 Whether a host may run this tool again after a crash cut the run
 between the call and its result. `'safe'` runs it again. Omit the
diff --git a/docs/reference/interfaces/SessionIdEvent.md b/docs/reference/interfaces/SessionIdEvent.md
index 173a3ff921..7fa09fdf4e 100644
--- a/docs/reference/interfaces/SessionIdEvent.md
+++ b/docs/reference/interfaces/SessionIdEvent.md
@@ -3,7 +3,7 @@ id: SessionIdEvent
 title: SessionIdEvent
 ---
 
-Defined in: [packages/ai/src/types.ts:1902](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1902)
+Defined in: [packages/ai/src/types.ts:1917](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1917)
 
 Custom event for extensibility.
 
@@ -21,7 +21,7 @@ Custom event for extensibility.
 optional metadata?: Record<string, any>;
 ```
 
-Defined in: [packages/ai/src/types.ts:1814](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1814)
+Defined in: [packages/ai/src/types.ts:1829](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1829)
 
 Extra information attached to this event.
 
@@ -37,7 +37,7 @@ Extra information attached to this event.
 name: `${string}.session-id`;
 ```
 
-Defined in: [packages/ai/src/types.ts:1903](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1903)
+Defined in: [packages/ai/src/types.ts:1918](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1918)
 
 What this custom event is. Required: without it a consumer cannot route
 the value.
@@ -56,7 +56,7 @@ CustomEvent.name
 type: "CUSTOM";
 ```
 
-Defined in: [packages/ai/src/types.ts:1813](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1813)
+Defined in: [packages/ai/src/types.ts:1828](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1828)
 
 #### Inherited from
 
@@ -70,7 +70,7 @@ Defined in: [packages/ai/src/types.ts:1813](https://github.com/TanStack/ai/blob/
 value: object;
 ```
 
-Defined in: [packages/ai/src/types.ts:1904](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1904)
+Defined in: [packages/ai/src/types.ts:1919](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1919)
 
 The payload. Any JSON value, and required.
 
diff --git a/docs/reference/interfaces/SnippetRegisteredEvent.md b/docs/reference/interfaces/SnippetRegisteredEvent.md
index f3bc8ca302..4a8e344738 100644
--- a/docs/reference/interfaces/SnippetRegisteredEvent.md
+++ b/docs/reference/interfaces/SnippetRegisteredEvent.md
@@ -3,7 +3,7 @@ id: SnippetRegisteredEvent
 title: SnippetRegisteredEvent
 ---
 
-Defined in: [packages/ai/src/types.ts:1949](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1949)
+Defined in: [packages/ai/src/types.ts:1964](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1964)
 
 Custom event for extensibility.
 
@@ -21,7 +21,7 @@ Custom event for extensibility.
 optional metadata?: Record<string, any>;
 ```
 
-Defined in: [packages/ai/src/types.ts:1814](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1814)
+Defined in: [packages/ai/src/types.ts:1829](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1829)
 
 Extra information attached to this event.
 
@@ -37,7 +37,7 @@ Extra information attached to this event.
 name: "snippet:registered";
 ```
 
-Defined in: [packages/ai/src/types.ts:1950](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1950)
+Defined in: [packages/ai/src/types.ts:1965](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1965)
 
 What this custom event is. Required: without it a consumer cannot route
 the value.
@@ -56,7 +56,7 @@ CustomEvent.name
 type: "CUSTOM";
 ```
 
-Defined in: [packages/ai/src/types.ts:1813](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1813)
+Defined in: [packages/ai/src/types.ts:1828](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1828)
 
 #### Inherited from
 
@@ -70,7 +70,7 @@ Defined in: [packages/ai/src/types.ts:1813](https://github.com/TanStack/ai/blob/
 value: object;
 ```
 
-Defined in: [packages/ai/src/types.ts:1951](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1951)
+Defined in: [packages/ai/src/types.ts:1966](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1966)
 
 The payload. Any JSON value, and required.
 
diff --git a/docs/reference/interfaces/StateDeltaEvent.md b/docs/reference/interfaces/StateDeltaEvent.md
index cd7e5c6d4b..20bbf48701 100644
--- a/docs/reference/interfaces/StateDeltaEvent.md
+++ b/docs/reference/interfaces/StateDeltaEvent.md
@@ -3,7 +3,7 @@ id: StateDeltaEvent
 title: StateDeltaEvent
 ---
 
-Defined in: [packages/ai/src/types.ts:1805](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1805)
+Defined in: [packages/ai/src/types.ts:1820](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1820)
 
 Emitted to provide an incremental state update.
 
diff --git a/docs/reference/interfaces/StateSnapshotEvent.md b/docs/reference/interfaces/StateSnapshotEvent.md
index 6dd24c50e8..de03bc5956 100644
--- a/docs/reference/interfaces/StateSnapshotEvent.md
+++ b/docs/reference/interfaces/StateSnapshotEvent.md
@@ -3,7 +3,7 @@ id: StateSnapshotEvent
 title: StateSnapshotEvent
 ---
 
-Defined in: [packages/ai/src/types.ts:1798](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1798)
+Defined in: [packages/ai/src/types.ts:1813](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1813)
 
 Emitted to provide a full state snapshot.
 
diff --git a/docs/reference/interfaces/StepFinishedEvent.md b/docs/reference/interfaces/StepFinishedEvent.md
index 5e9da065d0..f3c2752a89 100644
--- a/docs/reference/interfaces/StepFinishedEvent.md
+++ b/docs/reference/interfaces/StepFinishedEvent.md
@@ -3,7 +3,7 @@ id: StepFinishedEvent
 title: StepFinishedEvent
 ---
 
-Defined in: [packages/ai/src/types.ts:1778](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1778)
+Defined in: [packages/ai/src/types.ts:1793](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1793)
 
 Emitted when a thinking/reasoning step finishes.
 
diff --git a/docs/reference/interfaces/StepStartedEvent.md b/docs/reference/interfaces/StepStartedEvent.md
index afc5dc4563..18b9d19aed 100644
--- a/docs/reference/interfaces/StepStartedEvent.md
+++ b/docs/reference/interfaces/StepStartedEvent.md
@@ -3,7 +3,7 @@ id: StepStartedEvent
 title: StepStartedEvent
 ---
 
-Defined in: [packages/ai/src/types.ts:1771](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1771)
+Defined in: [packages/ai/src/types.ts:1786](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1786)
 
 Emitted when a thinking/reasoning step starts.
 
diff --git a/docs/reference/interfaces/StreamProcessorEvents.md b/docs/reference/interfaces/StreamProcessorEvents.md
index 16257e100a..967ff4a267 100644
--- a/docs/reference/interfaces/StreamProcessorEvents.md
+++ b/docs/reference/interfaces/StreamProcessorEvents.md
@@ -3,7 +3,7 @@ id: StreamProcessorEvents
 title: StreamProcessorEvents
 ---
 
-Defined in: [packages/ai/src/activities/chat/stream/processor.ts:101](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/stream/processor.ts#L101)
+Defined in: [packages/ai/src/activities/chat/stream/processor.ts:102](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/stream/processor.ts#L102)
 
 Events emitted by the StreamProcessor
 
@@ -15,7 +15,7 @@ Events emitted by the StreamProcessor
 optional onApprovalRequest?: (args) => void;
 ```
 
-Defined in: [packages/ai/src/activities/chat/stream/processor.ts:116](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/stream/processor.ts#L116)
+Defined in: [packages/ai/src/activities/chat/stream/processor.ts:117](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/stream/processor.ts#L117)
 
 #### Parameters
 
@@ -49,7 +49,7 @@ Defined in: [packages/ai/src/activities/chat/stream/processor.ts:116](https://gi
 optional onCustomEvent?: (eventType, data, context) => void;
 ```
 
-Defined in: [packages/ai/src/activities/chat/stream/processor.ts:124](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/stream/processor.ts#L124)
+Defined in: [packages/ai/src/activities/chat/stream/processor.ts:125](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/stream/processor.ts#L125)
 
 #### Parameters
 
@@ -79,7 +79,7 @@ Defined in: [packages/ai/src/activities/chat/stream/processor.ts:124](https://gi
 optional onError?: (error) => void;
 ```
 
-Defined in: [packages/ai/src/activities/chat/stream/processor.ts:108](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/stream/processor.ts#L108)
+Defined in: [packages/ai/src/activities/chat/stream/processor.ts:109](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/stream/processor.ts#L109)
 
 #### Parameters
 
@@ -99,7 +99,7 @@ Defined in: [packages/ai/src/activities/chat/stream/processor.ts:108](https://gi
 optional onMessagesChange?: (messages) => void;
 ```
 
-Defined in: [packages/ai/src/activities/chat/stream/processor.ts:103](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/stream/processor.ts#L103)
+Defined in: [packages/ai/src/activities/chat/stream/processor.ts:104](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/stream/processor.ts#L104)
 
 #### Parameters
 
@@ -119,7 +119,7 @@ Defined in: [packages/ai/src/activities/chat/stream/processor.ts:103](https://gi
 optional onStreamEnd?: (message) => void;
 ```
 
-Defined in: [packages/ai/src/activities/chat/stream/processor.ts:107](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/stream/processor.ts#L107)
+Defined in: [packages/ai/src/activities/chat/stream/processor.ts:108](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/stream/processor.ts#L108)
 
 #### Parameters
 
@@ -139,7 +139,7 @@ Defined in: [packages/ai/src/activities/chat/stream/processor.ts:107](https://gi
 optional onStreamStart?: () => void;
 ```
 
-Defined in: [packages/ai/src/activities/chat/stream/processor.ts:106](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/stream/processor.ts#L106)
+Defined in: [packages/ai/src/activities/chat/stream/processor.ts:107](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/stream/processor.ts#L107)
 
 #### Returns
 
@@ -153,7 +153,7 @@ Defined in: [packages/ai/src/activities/chat/stream/processor.ts:106](https://gi
 optional onStructuredOutputChange?: (args) => void;
 ```
 
-Defined in: [packages/ai/src/activities/chat/stream/processor.ts:143](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/stream/processor.ts#L143)
+Defined in: [packages/ai/src/activities/chat/stream/processor.ts:144](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/stream/processor.ts#L144)
 
 #### Parameters
 
@@ -207,7 +207,7 @@ Defined in: [packages/ai/src/activities/chat/stream/processor.ts:143](https://gi
 optional onTextUpdate?: (messageId, content) => void;
 ```
 
-Defined in: [packages/ai/src/activities/chat/stream/processor.ts:131](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/stream/processor.ts#L131)
+Defined in: [packages/ai/src/activities/chat/stream/processor.ts:132](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/stream/processor.ts#L132)
 
 #### Parameters
 
@@ -231,7 +231,7 @@ Defined in: [packages/ai/src/activities/chat/stream/processor.ts:131](https://gi
 optional onThinkingUpdate?: (messageId, stepId, content) => void;
 ```
 
-Defined in: [packages/ai/src/activities/chat/stream/processor.ts:138](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/stream/processor.ts#L138)
+Defined in: [packages/ai/src/activities/chat/stream/processor.ts:139](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/stream/processor.ts#L139)
 
 #### Parameters
 
@@ -259,7 +259,7 @@ Defined in: [packages/ai/src/activities/chat/stream/processor.ts:138](https://gi
 optional onToolCall?: (args) => void;
 ```
 
-Defined in: [packages/ai/src/activities/chat/stream/processor.ts:111](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/stream/processor.ts#L111)
+Defined in: [packages/ai/src/activities/chat/stream/processor.ts:112](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/stream/processor.ts#L112)
 
 #### Parameters
 
@@ -289,7 +289,7 @@ Defined in: [packages/ai/src/activities/chat/stream/processor.ts:111](https://gi
 optional onToolCallStateChange?: (messageId, toolCallId, state, args) => void;
 ```
 
-Defined in: [packages/ai/src/activities/chat/stream/processor.ts:132](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/stream/processor.ts#L132)
+Defined in: [packages/ai/src/activities/chat/stream/processor.ts:133](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/stream/processor.ts#L133)
 
 #### Parameters
 
diff --git a/docs/reference/interfaces/StreamProcessorOptions.md b/docs/reference/interfaces/StreamProcessorOptions.md
index 812225a65b..296bf9b5d3 100644
--- a/docs/reference/interfaces/StreamProcessorOptions.md
+++ b/docs/reference/interfaces/StreamProcessorOptions.md
@@ -3,7 +3,7 @@ id: StreamProcessorOptions
 title: StreamProcessorOptions
 ---
 
-Defined in: [packages/ai/src/activities/chat/stream/processor.ts:159](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/stream/processor.ts#L159)
+Defined in: [packages/ai/src/activities/chat/stream/processor.ts:160](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/stream/processor.ts#L160)
 
 Options for StreamProcessor
 
@@ -15,7 +15,7 @@ Options for StreamProcessor
 optional chunkStrategy?: ChunkStrategy;
 ```
 
-Defined in: [packages/ai/src/activities/chat/stream/processor.ts:160](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/stream/processor.ts#L160)
+Defined in: [packages/ai/src/activities/chat/stream/processor.ts:161](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/stream/processor.ts#L161)
 
 ***
 
@@ -25,7 +25,7 @@ Defined in: [packages/ai/src/activities/chat/stream/processor.ts:160](https://gi
 optional events?: StreamProcessorEvents;
 ```
 
-Defined in: [packages/ai/src/activities/chat/stream/processor.ts:162](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/stream/processor.ts#L162)
+Defined in: [packages/ai/src/activities/chat/stream/processor.ts:163](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/stream/processor.ts#L163)
 
 Event-driven handlers
 
@@ -37,7 +37,7 @@ Event-driven handlers
 optional initialMessages?: UIMessage<unknown>[];
 ```
 
-Defined in: [packages/ai/src/activities/chat/stream/processor.ts:169](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/stream/processor.ts#L169)
+Defined in: [packages/ai/src/activities/chat/stream/processor.ts:170](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/stream/processor.ts#L170)
 
 Initial messages to populate the processor
 
@@ -49,7 +49,7 @@ Initial messages to populate the processor
 optional jsonParser?: object;
 ```
 
-Defined in: [packages/ai/src/activities/chat/stream/processor.ts:163](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/stream/processor.ts#L163)
+Defined in: [packages/ai/src/activities/chat/stream/processor.ts:164](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/stream/processor.ts#L164)
 
 #### parse
 
@@ -75,7 +75,7 @@ parse: (jsonString) => any;
 optional recording?: boolean;
 ```
 
-Defined in: [packages/ai/src/activities/chat/stream/processor.ts:167](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/stream/processor.ts#L167)
+Defined in: [packages/ai/src/activities/chat/stream/processor.ts:168](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/stream/processor.ts#L168)
 
 Enable recording for replay testing
 
@@ -87,7 +87,7 @@ Enable recording for replay testing
 optional subagentRunId?: string;
 ```
 
-Defined in: [packages/ai/src/activities/chat/stream/processor.ts:174](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/stream/processor.ts#L174)
+Defined in: [packages/ai/src/activities/chat/stream/processor.ts:175](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/stream/processor.ts#L175)
 
 Set on the processor of a subagent card. Chunks tagged with this id are
 the card's own; chunks for an id no card holds are dropped.
diff --git a/docs/reference/interfaces/StructuredOutputCompleteEvent.md b/docs/reference/interfaces/StructuredOutputCompleteEvent.md
index 49a2f55a62..181d932ba4 100644
--- a/docs/reference/interfaces/StructuredOutputCompleteEvent.md
+++ b/docs/reference/interfaces/StructuredOutputCompleteEvent.md
@@ -3,7 +3,7 @@ id: StructuredOutputCompleteEvent
 title: StructuredOutputCompleteEvent
 ---
 
-Defined in: [packages/ai/src/types.ts:1835](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1835)
+Defined in: [packages/ai/src/types.ts:1850](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1850)
 
 Final event of a streaming structured-output run. Carries the validated
 `object` (typed as `T` after the orchestrator runs Standard Schema parsing),
@@ -40,7 +40,7 @@ if (chunk.type === 'CUSTOM' && chunk.name === 'structured-output.complete') {
 optional metadata?: Record<string, any>;
 ```
 
-Defined in: [packages/ai/src/types.ts:1814](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1814)
+Defined in: [packages/ai/src/types.ts:1829](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1829)
 
 Extra information attached to this event.
 
@@ -56,7 +56,7 @@ Extra information attached to this event.
 name: "structured-output.complete";
 ```
 
-Defined in: [packages/ai/src/types.ts:1838](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1838)
+Defined in: [packages/ai/src/types.ts:1853](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1853)
 
 What this custom event is. Required: without it a consumer cannot route
 the value.
@@ -75,7 +75,7 @@ CustomEvent.name
 type: "CUSTOM";
 ```
 
-Defined in: [packages/ai/src/types.ts:1813](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1813)
+Defined in: [packages/ai/src/types.ts:1828](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1828)
 
 #### Inherited from
 
@@ -89,7 +89,7 @@ Defined in: [packages/ai/src/types.ts:1813](https://github.com/TanStack/ai/blob/
 value: object;
 ```
 
-Defined in: [packages/ai/src/types.ts:1839](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1839)
+Defined in: [packages/ai/src/types.ts:1854](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1854)
 
 The payload. Any JSON value, and required.
 
diff --git a/docs/reference/interfaces/StructuredOutputStartEvent.md b/docs/reference/interfaces/StructuredOutputStartEvent.md
index fd231c12e3..6c269fd860 100644
--- a/docs/reference/interfaces/StructuredOutputStartEvent.md
+++ b/docs/reference/interfaces/StructuredOutputStartEvent.md
@@ -3,7 +3,7 @@ id: StructuredOutputStartEvent
 title: StructuredOutputStartEvent
 ---
 
-Defined in: [packages/ai/src/types.ts:1850](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1850)
+Defined in: [packages/ai/src/types.ts:1865](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1865)
 
 Emitted at the start of a streaming structured-output run, before the JSON
 deltas. Tells consumers that the upcoming `TEXT_MESSAGE_CONTENT` deltas
@@ -24,7 +24,7 @@ made per-message rather than globally.
 optional metadata?: Record<string, any>;
 ```
 
-Defined in: [packages/ai/src/types.ts:1814](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1814)
+Defined in: [packages/ai/src/types.ts:1829](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1829)
 
 Extra information attached to this event.
 
@@ -40,7 +40,7 @@ Extra information attached to this event.
 name: "structured-output.start";
 ```
 
-Defined in: [packages/ai/src/types.ts:1851](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1851)
+Defined in: [packages/ai/src/types.ts:1866](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1866)
 
 What this custom event is. Required: without it a consumer cannot route
 the value.
@@ -59,7 +59,7 @@ CustomEvent.name
 type: "CUSTOM";
 ```
 
-Defined in: [packages/ai/src/types.ts:1813](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1813)
+Defined in: [packages/ai/src/types.ts:1828](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1828)
 
 #### Inherited from
 
@@ -73,7 +73,7 @@ Defined in: [packages/ai/src/types.ts:1813](https://github.com/TanStack/ai/blob/
 value: object;
 ```
 
-Defined in: [packages/ai/src/types.ts:1852](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1852)
+Defined in: [packages/ai/src/types.ts:1867](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1867)
 
 The payload. Any JSON value, and required.
 
diff --git a/docs/reference/interfaces/SubagentErrorEvent.md b/docs/reference/interfaces/SubagentErrorEvent.md
index bbaa3cf603..1f13265315 100644
--- a/docs/reference/interfaces/SubagentErrorEvent.md
+++ b/docs/reference/interfaces/SubagentErrorEvent.md
@@ -3,7 +3,7 @@ id: SubagentErrorEvent
 title: SubagentErrorEvent
 ---
 
-Defined in: [packages/ai/src/types.ts:2168](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2168)
+Defined in: [packages/ai/src/types.ts:2183](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2183)
 
 A child agent failed. The parent run can continue.
 
diff --git a/docs/reference/interfaces/SubagentFinishedEvent.md b/docs/reference/interfaces/SubagentFinishedEvent.md
index 31502a2027..5968fcbbb0 100644
--- a/docs/reference/interfaces/SubagentFinishedEvent.md
+++ b/docs/reference/interfaces/SubagentFinishedEvent.md
@@ -3,7 +3,7 @@ id: SubagentFinishedEvent
 title: SubagentFinishedEvent
 ---
 
-Defined in: [packages/ai/src/types.ts:2161](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2161)
+Defined in: [packages/ai/src/types.ts:2176](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2176)
 
 A child agent's segment of this run ended.
 
diff --git a/docs/reference/interfaces/SubagentStartedEvent.md b/docs/reference/interfaces/SubagentStartedEvent.md
index ca68e6d933..7966cad7ba 100644
--- a/docs/reference/interfaces/SubagentStartedEvent.md
+++ b/docs/reference/interfaces/SubagentStartedEvent.md
@@ -3,7 +3,7 @@ id: SubagentStartedEvent
 title: SubagentStartedEvent
 ---
 
-Defined in: [packages/ai/src/types.ts:2154](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2154)
+Defined in: [packages/ai/src/types.ts:2169](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2169)
 
 A child agent started. The later chunks for that child carry the same
 `subagentRunId`.
diff --git a/docs/reference/interfaces/SummarizationOptions.md b/docs/reference/interfaces/SummarizationOptions.md
index 5e0b8b7c47..23727b82bc 100644
--- a/docs/reference/interfaces/SummarizationOptions.md
+++ b/docs/reference/interfaces/SummarizationOptions.md
@@ -3,7 +3,7 @@ id: SummarizationOptions
 title: SummarizationOptions
 ---
 
-Defined in: [packages/ai/src/types.ts:2214](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2214)
+Defined in: [packages/ai/src/types.ts:2229](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2229)
 
 ## Type Parameters
 
@@ -19,7 +19,7 @@ Defined in: [packages/ai/src/types.ts:2214](https://github.com/TanStack/ai/blob/
 optional abortSignal?: AbortSignal;
 ```
 
-Defined in: [packages/ai/src/types.ts:2244](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2244)
+Defined in: [packages/ai/src/types.ts:2259](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2259)
 
 Effective abort signal composed by the activity from caller `abortSignal`
 and/or `timeout`. Adapters should forward this to the provider SDK when
@@ -33,7 +33,7 @@ supported. Request-specific — never store on a global client config.
 optional focus?: string[];
 ```
 
-Defined in: [packages/ai/src/types.ts:2221](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2221)
+Defined in: [packages/ai/src/types.ts:2236](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2236)
 
 ***
 
@@ -43,7 +43,7 @@ Defined in: [packages/ai/src/types.ts:2221](https://github.com/TanStack/ai/blob/
 logger: InternalLogger;
 ```
 
-Defined in: [packages/ai/src/types.ts:2238](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2238)
+Defined in: [packages/ai/src/types.ts:2253](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2253)
 
 Internal logger threaded from the summarize() entry point. Adapters must
 call logger.request() before the SDK call and logger.errors() in catch blocks.
@@ -56,7 +56,7 @@ call logger.request() before the SDK call and logger.errors() in catch blocks.
 optional maxLength?: number;
 ```
 
-Defined in: [packages/ai/src/types.ts:2219](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2219)
+Defined in: [packages/ai/src/types.ts:2234](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2234)
 
 ***
 
@@ -66,7 +66,7 @@ Defined in: [packages/ai/src/types.ts:2219](https://github.com/TanStack/ai/blob/
 model: string;
 ```
 
-Defined in: [packages/ai/src/types.ts:2217](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2217)
+Defined in: [packages/ai/src/types.ts:2232](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2232)
 
 ***
 
@@ -76,7 +76,7 @@ Defined in: [packages/ai/src/types.ts:2217](https://github.com/TanStack/ai/blob/
 optional modelOptions?: TProviderOptions;
 ```
 
-Defined in: [packages/ai/src/types.ts:2223](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2223)
+Defined in: [packages/ai/src/types.ts:2238](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2238)
 
 Provider-specific options forwarded by the summarize() activity.
 
@@ -88,7 +88,7 @@ Provider-specific options forwarded by the summarize() activity.
 optional runId?: string;
 ```
 
-Defined in: [packages/ai/src/types.ts:2232](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2232)
+Defined in: [packages/ai/src/types.ts:2247](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2247)
 
 Run identity forwarded from the summarize() activity. When set, the
 streaming adapter stamps it onto the emitted `RUN_STARTED` (via the wrapped
@@ -105,7 +105,7 @@ their own.
 optional style?: "bullet-points" | "paragraph" | "concise";
 ```
 
-Defined in: [packages/ai/src/types.ts:2220](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2220)
+Defined in: [packages/ai/src/types.ts:2235](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2235)
 
 ***
 
@@ -115,7 +115,7 @@ Defined in: [packages/ai/src/types.ts:2220](https://github.com/TanStack/ai/blob/
 text: string;
 ```
 
-Defined in: [packages/ai/src/types.ts:2218](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2218)
+Defined in: [packages/ai/src/types.ts:2233](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2233)
 
 ***
 
@@ -125,4 +125,4 @@ Defined in: [packages/ai/src/types.ts:2218](https://github.com/TanStack/ai/blob/
 threadId: string;
 ```
 
-Defined in: [packages/ai/src/types.ts:2233](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2233)
+Defined in: [packages/ai/src/types.ts:2248](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2248)
diff --git a/docs/reference/interfaces/SummarizationResult.md b/docs/reference/interfaces/SummarizationResult.md
index 0e60744aa6..22fce7af8b 100644
--- a/docs/reference/interfaces/SummarizationResult.md
+++ b/docs/reference/interfaces/SummarizationResult.md
@@ -3,7 +3,7 @@ id: SummarizationResult
 title: SummarizationResult
 ---
 
-Defined in: [packages/ai/src/types.ts:2247](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2247)
+Defined in: [packages/ai/src/types.ts:2262](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2262)
 
 ## Properties
 
@@ -13,7 +13,7 @@ Defined in: [packages/ai/src/types.ts:2247](https://github.com/TanStack/ai/blob/
 id: string;
 ```
 
-Defined in: [packages/ai/src/types.ts:2248](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2248)
+Defined in: [packages/ai/src/types.ts:2263](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2263)
 
 ***
 
@@ -23,7 +23,7 @@ Defined in: [packages/ai/src/types.ts:2248](https://github.com/TanStack/ai/blob/
 model: string;
 ```
 
-Defined in: [packages/ai/src/types.ts:2249](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2249)
+Defined in: [packages/ai/src/types.ts:2264](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2264)
 
 ***
 
@@ -33,7 +33,7 @@ Defined in: [packages/ai/src/types.ts:2249](https://github.com/TanStack/ai/blob/
 summary: string;
 ```
 
-Defined in: [packages/ai/src/types.ts:2250](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2250)
+Defined in: [packages/ai/src/types.ts:2265](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2265)
 
 ***
 
@@ -43,4 +43,4 @@ Defined in: [packages/ai/src/types.ts:2250](https://github.com/TanStack/ai/blob/
 usage: TokenUsage;
 ```
 
-Defined in: [packages/ai/src/types.ts:2251](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2251)
+Defined in: [packages/ai/src/types.ts:2266](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2266)
diff --git a/docs/reference/interfaces/TTSAlignment.md b/docs/reference/interfaces/TTSAlignment.md
index d7bb045f3c..1c7db14aa9 100644
--- a/docs/reference/interfaces/TTSAlignment.md
+++ b/docs/reference/interfaces/TTSAlignment.md
@@ -3,7 +3,7 @@ id: TTSAlignment
 title: TTSAlignment
 ---
 
-Defined in: [packages/ai/src/types.ts:2916](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2916)
+Defined in: [packages/ai/src/types.ts:2931](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2931)
 
 Timings for the generated audio, returned when `timestamps: true` was
 requested and the adapter declares `capabilities.timestamps`.
@@ -20,7 +20,7 @@ All times are **seconds**; adapters convert.
 endSeconds: number[];
 ```
 
-Defined in: [packages/ai/src/types.ts:2924](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2924)
+Defined in: [packages/ai/src/types.ts:2939](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2939)
 
 End of each entry in seconds. Same length as `texts`.
 
@@ -32,7 +32,7 @@ End of each entry in seconds. Same length as `texts`.
 startSeconds: number[];
 ```
 
-Defined in: [packages/ai/src/types.ts:2922](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2922)
+Defined in: [packages/ai/src/types.ts:2937](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2937)
 
 Start of each entry in seconds. Same length as `texts`.
 
@@ -44,7 +44,7 @@ Start of each entry in seconds. Same length as `texts`.
 texts: string[];
 ```
 
-Defined in: [packages/ai/src/types.ts:2920](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2920)
+Defined in: [packages/ai/src/types.ts:2935](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2935)
 
 Entry text, in audio order.
 
@@ -56,6 +56,6 @@ Entry text, in audio order.
 unit: "character" | "word";
 ```
 
-Defined in: [packages/ai/src/types.ts:2918](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2918)
+Defined in: [packages/ai/src/types.ts:2933](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2933)
 
 Granularity of each entry.
diff --git a/docs/reference/interfaces/TTSOptions.md b/docs/reference/interfaces/TTSOptions.md
index f11b7413e4..fa047f2bc1 100644
--- a/docs/reference/interfaces/TTSOptions.md
+++ b/docs/reference/interfaces/TTSOptions.md
@@ -3,7 +3,7 @@ id: TTSOptions
 title: TTSOptions
 ---
 
-Defined in: [packages/ai/src/types.ts:2948](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2948)
+Defined in: [packages/ai/src/types.ts:2963](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2963)
 
 Options for text-to-speech generation.
 These are the common options supported across providers.
@@ -22,7 +22,7 @@ These are the common options supported across providers.
 optional abortSignal?: AbortSignal;
 ```
 
-Defined in: [packages/ai/src/types.ts:2988](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2988)
+Defined in: [packages/ai/src/types.ts:3003](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L3003)
 
 Effective abort signal composed by the activity from caller `abortSignal`
 and/or `timeout`. Adapters should forward this to the provider SDK when
@@ -36,7 +36,7 @@ supported. Request-specific — never store on a global client config.
 optional format?: "mp3" | "opus" | "aac" | "flac" | "wav" | "pcm";
 ```
 
-Defined in: [packages/ai/src/types.ts:2972](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2972)
+Defined in: [packages/ai/src/types.ts:2987](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2987)
 
 The output audio format
 
@@ -48,7 +48,7 @@ The output audio format
 logger: InternalLogger;
 ```
 
-Defined in: [packages/ai/src/types.ts:2982](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2982)
+Defined in: [packages/ai/src/types.ts:2997](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2997)
 
 Internal logger threaded from the generateSpeech() entry point. Adapters
 must call logger.request() before the SDK call and logger.errors() in
@@ -62,7 +62,7 @@ catch blocks.
 model: string;
 ```
 
-Defined in: [packages/ai/src/types.ts:2950](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2950)
+Defined in: [packages/ai/src/types.ts:2965](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2965)
 
 The model to use for TTS generation
 
@@ -74,7 +74,7 @@ The model to use for TTS generation
 optional modelOptions?: TProviderOptions;
 ```
 
-Defined in: [packages/ai/src/types.ts:2976](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2976)
+Defined in: [packages/ai/src/types.ts:2991](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2991)
 
 Model-specific options for TTS generation
 
@@ -86,7 +86,7 @@ Model-specific options for TTS generation
 optional speed?: number;
 ```
 
-Defined in: [packages/ai/src/types.ts:2974](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2974)
+Defined in: [packages/ai/src/types.ts:2989](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2989)
 
 The speed of the generated audio (0.25 to 4.0)
 
@@ -98,7 +98,7 @@ The speed of the generated audio (0.25 to 4.0)
 text: string;
 ```
 
-Defined in: [packages/ai/src/types.ts:2956](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2956)
+Defined in: [packages/ai/src/types.ts:2971](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2971)
 
 The text to convert to speech. When the caller passed `turns`, the
 activity fills this with the turn texts joined by newlines so adapters
@@ -112,7 +112,7 @@ that only read `text` still receive the full script.
 optional timestamps?: boolean;
 ```
 
-Defined in: [packages/ai/src/types.ts:2968](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2968)
+Defined in: [packages/ai/src/types.ts:2983](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2983)
 
 Ask for `alignment` / `segments` on the result. Rejected by the activity
 unless the adapter declares `capabilities.timestamps`, because on some
@@ -126,7 +126,7 @@ providers this is a different endpoint rather than free metadata.
 optional turns?: TTSTurn[];
 ```
 
-Defined in: [packages/ai/src/types.ts:2962](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2962)
+Defined in: [packages/ai/src/types.ts:2977](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2977)
 
 Multi-voice dialogue turns, when the caller asked for dialogue. Only
 adapters that declare `capabilities.maxSpeakers` ever see this — the
@@ -140,6 +140,6 @@ activity rejects `turns` for the rest.
 optional voice?: string;
 ```
 
-Defined in: [packages/ai/src/types.ts:2970](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2970)
+Defined in: [packages/ai/src/types.ts:2985](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2985)
 
 The voice to use for generation
diff --git a/docs/reference/interfaces/TTSResult.md b/docs/reference/interfaces/TTSResult.md
index 7668e44ba7..ce1d2344fa 100644
--- a/docs/reference/interfaces/TTSResult.md
+++ b/docs/reference/interfaces/TTSResult.md
@@ -3,7 +3,7 @@ id: TTSResult
 title: TTSResult
 ---
 
-Defined in: [packages/ai/src/types.ts:2994](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2994)
+Defined in: [packages/ai/src/types.ts:3009](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L3009)
 
 Result of text-to-speech generation.
 
@@ -15,7 +15,7 @@ Result of text-to-speech generation.
 optional alignment?: TTSAlignment;
 ```
 
-Defined in: [packages/ai/src/types.ts:3009](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L3009)
+Defined in: [packages/ai/src/types.ts:3024](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L3024)
 
 Character- or word-level timings, present when `timestamps: true` was
 requested. Use this rather than `duration` to find where *speech* ends.
@@ -28,7 +28,7 @@ requested. Use this rather than `duration` to find where *speech* ends.
 optional artifacts?: PersistedArtifactRef[];
 ```
 
-Defined in: [packages/ai/src/types.ts:3020](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L3020)
+Defined in: [packages/ai/src/types.ts:3035](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L3035)
 
 Persisted artifact references for generated assets, when available
 
@@ -40,7 +40,7 @@ Persisted artifact references for generated assets, when available
 audio: string;
 ```
 
-Defined in: [packages/ai/src/types.ts:3000](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L3000)
+Defined in: [packages/ai/src/types.ts:3015](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L3015)
 
 Base64-encoded audio data
 
@@ -52,7 +52,7 @@ Base64-encoded audio data
 optional contentType?: string;
 ```
 
-Defined in: [packages/ai/src/types.ts:3016](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L3016)
+Defined in: [packages/ai/src/types.ts:3031](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L3031)
 
 Content type of the audio (e.g., 'audio/mp3')
 
@@ -64,7 +64,7 @@ Content type of the audio (e.g., 'audio/mp3')
 optional duration?: number;
 ```
 
-Defined in: [packages/ai/src/types.ts:3004](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L3004)
+Defined in: [packages/ai/src/types.ts:3019](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L3019)
 
 Duration of the audio file in seconds, if available
 
@@ -76,7 +76,7 @@ Duration of the audio file in seconds, if available
 format: string;
 ```
 
-Defined in: [packages/ai/src/types.ts:3002](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L3002)
+Defined in: [packages/ai/src/types.ts:3017](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L3017)
 
 Audio format of the generated audio
 
@@ -88,7 +88,7 @@ Audio format of the generated audio
 id: string;
 ```
 
-Defined in: [packages/ai/src/types.ts:2996](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2996)
+Defined in: [packages/ai/src/types.ts:3011](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L3011)
 
 Unique identifier for the generation
 
@@ -100,7 +100,7 @@ Unique identifier for the generation
 model: string;
 ```
 
-Defined in: [packages/ai/src/types.ts:2998](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2998)
+Defined in: [packages/ai/src/types.ts:3013](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L3013)
 
 Model used for generation
 
@@ -112,7 +112,7 @@ Model used for generation
 optional segments?: TTSSegment[];
 ```
 
-Defined in: [packages/ai/src/types.ts:3014](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L3014)
+Defined in: [packages/ai/src/types.ts:3029](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L3029)
 
 Per-turn (or per-utterance) spans of the audio, present when
 `timestamps: true` was requested and the provider reports segmentation.
@@ -125,6 +125,6 @@ Per-turn (or per-utterance) spans of the audio, present when
 optional usage?: TokenUsage<ProviderUsageDetails>;
 ```
 
-Defined in: [packages/ai/src/types.ts:3018](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L3018)
+Defined in: [packages/ai/src/types.ts:3033](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L3033)
 
 Token usage information (if provided by the adapter)
diff --git a/docs/reference/interfaces/TTSSegment.md b/docs/reference/interfaces/TTSSegment.md
index e3678366eb..8eddcf3840 100644
--- a/docs/reference/interfaces/TTSSegment.md
+++ b/docs/reference/interfaces/TTSSegment.md
@@ -3,7 +3,7 @@ id: TTSSegment
 title: TTSSegment
 ---
 
-Defined in: [packages/ai/src/types.ts:2931](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2931)
+Defined in: [packages/ai/src/types.ts:2946](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2946)
 
 A stretch of audio attributable to one turn (multi-voice) or one utterance
 (single voice). This is what tells a consumer which turn is where.
@@ -16,7 +16,7 @@ A stretch of audio attributable to one turn (multi-voice) or one utterance
 endSeconds: number;
 ```
 
-Defined in: [packages/ai/src/types.ts:2935](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2935)
+Defined in: [packages/ai/src/types.ts:2950](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2950)
 
 End of the segment in seconds.
 
@@ -28,7 +28,7 @@ End of the segment in seconds.
 startSeconds: number;
 ```
 
-Defined in: [packages/ai/src/types.ts:2933](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2933)
+Defined in: [packages/ai/src/types.ts:2948](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2948)
 
 Start of the segment in seconds.
 
@@ -40,7 +40,7 @@ Start of the segment in seconds.
 optional text?: string;
 ```
 
-Defined in: [packages/ai/src/types.ts:2941](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2941)
+Defined in: [packages/ai/src/types.ts:2956](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2956)
 
 Text spoken in this segment, when the provider reports it.
 
@@ -52,7 +52,7 @@ Text spoken in this segment, when the provider reports it.
 optional turnIndex?: number;
 ```
 
-Defined in: [packages/ai/src/types.ts:2937](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2937)
+Defined in: [packages/ai/src/types.ts:2952](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2952)
 
 Index into the request's `turns`, when the provider reports it.
 
@@ -64,6 +64,6 @@ Index into the request's `turns`, when the provider reports it.
 optional voice?: string;
 ```
 
-Defined in: [packages/ai/src/types.ts:2939](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2939)
+Defined in: [packages/ai/src/types.ts:2954](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2954)
 
 Voice heard in this segment, when the provider reports it.
diff --git a/docs/reference/interfaces/TTSTurn.md b/docs/reference/interfaces/TTSTurn.md
index 7e57318cb2..c3c7c0325e 100644
--- a/docs/reference/interfaces/TTSTurn.md
+++ b/docs/reference/interfaces/TTSTurn.md
@@ -3,7 +3,7 @@ id: TTSTurn
 title: TTSTurn
 ---
 
-Defined in: [packages/ai/src/types.ts:2901](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2901)
+Defined in: [packages/ai/src/types.ts:2916](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2916)
 
 One turn of a multi-voice dialogue request.
 
@@ -19,7 +19,7 @@ single `text` + `voice` pair.
 text: string;
 ```
 
-Defined in: [packages/ai/src/types.ts:2903](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2903)
+Defined in: [packages/ai/src/types.ts:2918](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2918)
 
 The text this voice speaks.
 
@@ -31,6 +31,6 @@ The text this voice speaks.
 voice: string;
 ```
 
-Defined in: [packages/ai/src/types.ts:2905](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2905)
+Defined in: [packages/ai/src/types.ts:2920](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2920)
 
 Provider voice id (ElevenLabs) or voice name (Gemini) for this turn.
diff --git a/docs/reference/interfaces/TanStackMessageMetadata.md b/docs/reference/interfaces/TanStackMessageMetadata.md
index 0feba5256f..446e8a2e14 100644
--- a/docs/reference/interfaces/TanStackMessageMetadata.md
+++ b/docs/reference/interfaces/TanStackMessageMetadata.md
@@ -16,7 +16,7 @@ Shape of `metadata.tanstack` on a message.
 optional continues?: string;
 ```
 
-Defined in: [packages/ai/src/types.ts:761](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L761)
+Defined in: [packages/ai/src/types.ts:768](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L768)
 
 On an assistant wire row that exists only to keep the block order: the
 id of the assistant row before it. Our server joins the two rows into
@@ -47,6 +47,18 @@ stopped at the output limit, so its tool calls are not complete.
 
 ***
 
+### loopStopped?
+
+```ts
+optional loopStopped?: boolean;
+```
+
+Defined in: [packages/ai/src/types.ts:714](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L714)
+
+See `TanStackRunMetadata.loopStopped`. Set on the last assistant message of the run.
+
+***
+
 ### model?
 
 ```ts
@@ -63,7 +75,7 @@ Defined in: [packages/ai/src/types.ts:704](https://github.com/TanStack/ai/blob/m
 optional reasoningItem?: boolean;
 ```
 
-Defined in: [packages/ai/src/types.ts:725](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L725)
+Defined in: [packages/ai/src/types.ts:732](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L732)
 
 The model call of this assistant message sent a reasoning item. The
 OpenAI Responses adapter sets it. A replay that lost that reasoning item
@@ -88,7 +100,7 @@ Defined in: [packages/ai/src/types.ts:707](https://github.com/TanStack/ai/blob/m
 optional responseItems?: object[];
 ```
 
-Defined in: [packages/ai/src/types.ts:718](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L718)
+Defined in: [packages/ai/src/types.ts:720](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L720)
 
 The provider's answer items of this assistant message, in order, for a
 same-model replay. The OpenAI Responses adapter keeps each output
@@ -106,6 +118,14 @@ id: string;
 optional phase?: string;
 ```
 
+#### textLength?
+
+```ts
+optional textLength?: number;
+```
+
+UTF-16 text length, retaining item boundaries when adjacent text is merged.
+
 ***
 
 ### run?
@@ -114,7 +134,7 @@ optional phase?: string;
 optional run?: object;
 ```
 
-Defined in: [packages/ai/src/types.ts:733](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L733)
+Defined in: [packages/ai/src/types.ts:740](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L740)
 
 The chat run that produced this assistant message. `withPersistence` sets
 `id`. `reconstructChat` with `includeRuns: true` adds the finished run's
@@ -146,7 +166,7 @@ optional startedAt?: number;
 optional runId?: string;
 ```
 
-Defined in: [packages/ai/src/types.ts:727](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L727)
+Defined in: [packages/ai/src/types.ts:734](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L734)
 
 Parent chat run that produced this assistant message.
 
@@ -158,7 +178,7 @@ Parent chat run that produced this assistant message.
 optional signature?: string;
 ```
 
-Defined in: [packages/ai/src/types.ts:737](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L737)
+Defined in: [packages/ai/src/types.ts:744](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L744)
 
 Thinking signature for a `role: 'reasoning'` fan-out message.
 
@@ -190,7 +210,7 @@ Defined in: [packages/ai/src/types.ts:706](https://github.com/TanStack/ai/blob/m
 optional structuredOutput?: object;
 ```
 
-Defined in: [packages/ai/src/types.ts:747](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L747)
+Defined in: [packages/ai/src/types.ts:754](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L754)
 
 #### data?
 
@@ -236,7 +256,7 @@ optional status?: "error" | "complete" | "streaming";
 optional subagent?: SubagentWireInfo;
 ```
 
-Defined in: [packages/ai/src/types.ts:735](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L735)
+Defined in: [packages/ai/src/types.ts:742](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L742)
 
 Card data on a child wire message. See `uiMessagesToWire`.
 
@@ -248,7 +268,7 @@ Card data on a child wire message. See `uiMessagesToWire`.
 optional toolCallMetadata?: Record<string, unknown>;
 ```
 
-Defined in: [packages/ai/src/types.ts:739](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L739)
+Defined in: [packages/ai/src/types.ts:746](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L746)
 
 Per-tool-call provider metadata keyed by tool call id (e.g. Gemini thoughtSignature).
 
@@ -260,7 +280,7 @@ Per-tool-call provider metadata keyed by tool call id (e.g. Gemini thoughtSignat
 optional toolResult?: object;
 ```
 
-Defined in: [packages/ai/src/types.ts:740](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L740)
+Defined in: [packages/ai/src/types.ts:747](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L747)
 
 #### content?
 
@@ -288,7 +308,7 @@ optional id?: string;
 optional toolResultOutcome?: ToolResultOutcome;
 ```
 
-Defined in: [packages/ai/src/types.ts:746](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L746)
+Defined in: [packages/ai/src/types.ts:753](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L753)
 
 Outcome of a cancelled or denied tool result; when present, the UI state is `error`.
 
@@ -300,4 +320,4 @@ Outcome of a cancelled or denied tool result; when present, the UI state is `err
 optional uiResources?: UIResourcePart[];
 ```
 
-Defined in: [packages/ai/src/types.ts:755](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L755)
+Defined in: [packages/ai/src/types.ts:762](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L762)
diff --git a/docs/reference/interfaces/TanStackRunMetadata.md b/docs/reference/interfaces/TanStackRunMetadata.md
index 89f966d4b8..04b1fa5172 100644
--- a/docs/reference/interfaces/TanStackRunMetadata.md
+++ b/docs/reference/interfaces/TanStackRunMetadata.md
@@ -3,7 +3,7 @@ id: TanStackRunMetadata
 title: TanStackRunMetadata
 ---
 
-Defined in: [packages/ai/src/types.ts:767](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L767)
+Defined in: [packages/ai/src/types.ts:774](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L774)
 
 Shape of `metadata.tanstack` on run events.
 
@@ -15,7 +15,7 @@ Shape of `metadata.tanstack` on run events.
 optional args?: string;
 ```
 
-Defined in: [packages/ai/src/types.ts:795](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L795)
+Defined in: [packages/ai/src/types.ts:810](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L810)
 
 The raw tool argument string on `TOOL_CALL_END`, as the provider sent it.
 
@@ -27,7 +27,7 @@ The raw tool argument string on `TOOL_CALL_END`, as the provider sent it.
 optional errorType?: string;
 ```
 
-Defined in: [packages/ai/src/types.ts:788](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L788)
+Defined in: [packages/ai/src/types.ts:803](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L803)
 
 On a `RUN_ERROR`. See `RunErrorEvent.errorType`.
 
@@ -39,7 +39,7 @@ On a `RUN_ERROR`. See `RunErrorEvent.errorType`.
 optional finishReason?: "length" | "stop" | "content_filter" | "tool_calls" | null;
 ```
 
-Defined in: [packages/ai/src/types.ts:775](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L775)
+Defined in: [packages/ai/src/types.ts:782](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L782)
 
 ***
 
@@ -49,7 +49,7 @@ Defined in: [packages/ai/src/types.ts:775](https://github.com/TanStack/ai/blob/m
 optional index?: number;
 ```
 
-Defined in: [packages/ai/src/types.ts:782](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L782)
+Defined in: [packages/ai/src/types.ts:797](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L797)
 
 ***
 
@@ -59,7 +59,7 @@ Defined in: [packages/ai/src/types.ts:782](https://github.com/TanStack/ai/blob/m
 optional input?: unknown;
 ```
 
-Defined in: [packages/ai/src/types.ts:793](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L793)
+Defined in: [packages/ai/src/types.ts:808](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L808)
 
 Parsed `TOOL_CALL_END` input. Spec `TOOL_CALL_END` has no top-level `input`.
 
@@ -71,7 +71,23 @@ Parsed `TOOL_CALL_END` input. Spec `TOOL_CALL_END` has no top-level `input`.
 optional interruptErrors?: readonly InterruptSubmissionError[];
 ```
 
-Defined in: [packages/ai/src/types.ts:778](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L778)
+Defined in: [packages/ai/src/types.ts:793](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L793)
+
+***
+
+### loopStopped?
+
+```ts
+optional loopStopped?: boolean;
+```
+
+Defined in: [packages/ai/src/types.ts:790](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L790)
+
+`true` on the last `RUN_FINISHED` of a run that the agent loop stopped
+before the model was done: `agentLoopStrategy` (for example
+`maxIterations`) or a middleware `onShouldContinue` returned `false`
+while tool results waited for the next model call. `finishReason` stays
+the reason of the last model call.
 
 ***
 
@@ -81,7 +97,7 @@ Defined in: [packages/ai/src/types.ts:778](https://github.com/TanStack/ai/blob/m
 optional model?: string;
 ```
 
-Defined in: [packages/ai/src/types.ts:769](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L769)
+Defined in: [packages/ai/src/types.ts:776](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L776)
 
 ***
 
@@ -91,7 +107,7 @@ Defined in: [packages/ai/src/types.ts:769](https://github.com/TanStack/ai/blob/m
 optional rawText?: string;
 ```
 
-Defined in: [packages/ai/src/types.ts:786](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L786)
+Defined in: [packages/ai/src/types.ts:801](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L801)
 
 On a `RUN_ERROR`. See `RunErrorEvent.rawText`.
 
@@ -103,7 +119,7 @@ On a `RUN_ERROR`. See `RunErrorEvent.rawText`.
 optional reasoningItem?: boolean;
 ```
 
-Defined in: [packages/ai/src/types.ts:774](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L774)
+Defined in: [packages/ai/src/types.ts:781](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L781)
 
 See `TanStackMessageMetadata.reasoningItem`.
 
@@ -115,7 +131,7 @@ See `TanStackMessageMetadata.reasoningItem`.
 optional requestId?: string;
 ```
 
-Defined in: [packages/ai/src/types.ts:790](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L790)
+Defined in: [packages/ai/src/types.ts:805](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L805)
 
 On a `RUN_ERROR`. See `RunErrorEvent.requestId`.
 
@@ -127,7 +143,7 @@ On a `RUN_ERROR`. See `RunErrorEvent.requestId`.
 optional responseId?: string;
 ```
 
-Defined in: [packages/ai/src/types.ts:770](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L770)
+Defined in: [packages/ai/src/types.ts:777](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L777)
 
 ***
 
@@ -137,7 +153,7 @@ Defined in: [packages/ai/src/types.ts:770](https://github.com/TanStack/ai/blob/m
 optional responseItems?: object[];
 ```
 
-Defined in: [packages/ai/src/types.ts:772](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L772)
+Defined in: [packages/ai/src/types.ts:779](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L779)
 
 The answer items of this model call. See `TanStackMessageMetadata.responseItems`.
 
@@ -153,6 +169,14 @@ id: string;
 optional phase?: string;
 ```
 
+#### textLength?
+
+```ts
+optional textLength?: number;
+```
+
+UTF-16 text length, retaining item boundaries when adjacent text is merged.
+
 ***
 
 ### retryAfterMs?
@@ -161,7 +185,7 @@ optional phase?: string;
 optional retryAfterMs?: number;
 ```
 
-Defined in: [packages/ai/src/types.ts:784](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L784)
+Defined in: [packages/ai/src/types.ts:799](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L799)
 
 On a `RUN_ERROR`. See `RunErrorEvent.retryAfterMs`.
 
@@ -173,7 +197,7 @@ On a `RUN_ERROR`. See `RunErrorEvent.retryAfterMs`.
 optional runId?: string;
 ```
 
-Defined in: [packages/ai/src/types.ts:780](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L780)
+Defined in: [packages/ai/src/types.ts:795](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L795)
 
 ***
 
@@ -183,7 +207,7 @@ Defined in: [packages/ai/src/types.ts:780](https://github.com/TanStack/ai/blob/m
 optional sessionId?: string;
 ```
 
-Defined in: [packages/ai/src/types.ts:781](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L781)
+Defined in: [packages/ai/src/types.ts:796](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L796)
 
 ***
 
@@ -193,7 +217,7 @@ Defined in: [packages/ai/src/types.ts:781](https://github.com/TanStack/ai/blob/m
 optional source?: MessageSource;
 ```
 
-Defined in: [packages/ai/src/types.ts:768](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L768)
+Defined in: [packages/ai/src/types.ts:775](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L775)
 
 ***
 
@@ -203,7 +227,7 @@ Defined in: [packages/ai/src/types.ts:768](https://github.com/TanStack/ai/blob/m
 optional state?: ToolOutputState;
 ```
 
-Defined in: [packages/ai/src/types.ts:791](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L791)
+Defined in: [packages/ai/src/types.ts:806](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L806)
 
 ***
 
@@ -213,7 +237,7 @@ Defined in: [packages/ai/src/types.ts:791](https://github.com/TanStack/ai/blob/m
 optional threadId?: string;
 ```
 
-Defined in: [packages/ai/src/types.ts:779](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L779)
+Defined in: [packages/ai/src/types.ts:794](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L794)
 
 ***
 
@@ -223,6 +247,6 @@ Defined in: [packages/ai/src/types.ts:779](https://github.com/TanStack/ai/blob/m
 optional usage?: TokenUsageLeftover;
 ```
 
-Defined in: [packages/ai/src/types.ts:777](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L777)
+Defined in: [packages/ai/src/types.ts:792](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L792)
 
 TokenUsage fields that have no AG-UI `usage[]` equivalent.
diff --git a/docs/reference/interfaces/TextCompactOptions.md b/docs/reference/interfaces/TextCompactOptions.md
index f9ba2d9f94..3379e76105 100644
--- a/docs/reference/interfaces/TextCompactOptions.md
+++ b/docs/reference/interfaces/TextCompactOptions.md
@@ -3,7 +3,7 @@ id: TextCompactOptions
 title: TextCompactOptions
 ---
 
-Defined in: [packages/ai/src/types.ts:1570](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1570)
+Defined in: [packages/ai/src/types.ts:1585](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1585)
 
 What `TextAdapter.compact` receives.
 
@@ -18,7 +18,7 @@ messages: ModelMessage<
   | null>[];
 ```
 
-Defined in: [packages/ai/src/types.ts:1572](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1572)
+Defined in: [packages/ai/src/types.ts:1587](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1587)
 
 The history to compact.
 
@@ -30,7 +30,7 @@ The history to compact.
 model: string;
 ```
 
-Defined in: [packages/ai/src/types.ts:1573](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1573)
+Defined in: [packages/ai/src/types.ts:1588](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1588)
 
 ***
 
@@ -40,7 +40,7 @@ Defined in: [packages/ai/src/types.ts:1573](https://github.com/TanStack/ai/blob/
 optional signal?: AbortSignal;
 ```
 
-Defined in: [packages/ai/src/types.ts:1574](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1574)
+Defined in: [packages/ai/src/types.ts:1589](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1589)
 
 ***
 
@@ -50,7 +50,7 @@ Defined in: [packages/ai/src/types.ts:1574](https://github.com/TanStack/ai/blob/
 optional systemPrompts?: SystemPrompt[];
 ```
 
-Defined in: [packages/ai/src/types.ts:1578](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1578)
+Defined in: [packages/ai/src/types.ts:1593](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1593)
 
 The system prompts of the chat call.
 
@@ -62,6 +62,6 @@ The system prompts of the chat call.
 optional wrapFetch?: FetchWrapper;
 ```
 
-Defined in: [packages/ai/src/types.ts:1576](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1576)
+Defined in: [packages/ai/src/types.ts:1591](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1591)
 
 Wraps the fetch of the compaction request.
diff --git a/docs/reference/interfaces/TextCompletionChunk.md b/docs/reference/interfaces/TextCompletionChunk.md
index 447aced4b3..cc6ed2ceaf 100644
--- a/docs/reference/interfaces/TextCompletionChunk.md
+++ b/docs/reference/interfaces/TextCompletionChunk.md
@@ -3,7 +3,7 @@ id: TextCompletionChunk
 title: TextCompletionChunk
 ---
 
-Defined in: [packages/ai/src/types.ts:2205](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2205)
+Defined in: [packages/ai/src/types.ts:2220](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2220)
 
 ## Properties
 
@@ -13,7 +13,7 @@ Defined in: [packages/ai/src/types.ts:2205](https://github.com/TanStack/ai/blob/
 content: string;
 ```
 
-Defined in: [packages/ai/src/types.ts:2208](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2208)
+Defined in: [packages/ai/src/types.ts:2223](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2223)
 
 ***
 
@@ -23,7 +23,7 @@ Defined in: [packages/ai/src/types.ts:2208](https://github.com/TanStack/ai/blob/
 optional finishReason?: "length" | "stop" | "content_filter" | null;
 ```
 
-Defined in: [packages/ai/src/types.ts:2210](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2210)
+Defined in: [packages/ai/src/types.ts:2225](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2225)
 
 ***
 
@@ -33,7 +33,7 @@ Defined in: [packages/ai/src/types.ts:2210](https://github.com/TanStack/ai/blob/
 id: string;
 ```
 
-Defined in: [packages/ai/src/types.ts:2206](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2206)
+Defined in: [packages/ai/src/types.ts:2221](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2221)
 
 ***
 
@@ -43,7 +43,7 @@ Defined in: [packages/ai/src/types.ts:2206](https://github.com/TanStack/ai/blob/
 model: string;
 ```
 
-Defined in: [packages/ai/src/types.ts:2207](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2207)
+Defined in: [packages/ai/src/types.ts:2222](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2222)
 
 ***
 
@@ -53,7 +53,7 @@ Defined in: [packages/ai/src/types.ts:2207](https://github.com/TanStack/ai/blob/
 optional role?: "assistant";
 ```
 
-Defined in: [packages/ai/src/types.ts:2209](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2209)
+Defined in: [packages/ai/src/types.ts:2224](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2224)
 
 ***
 
@@ -63,4 +63,4 @@ Defined in: [packages/ai/src/types.ts:2209](https://github.com/TanStack/ai/blob/
 optional usage?: TokenUsage<ProviderUsageDetails>;
 ```
 
-Defined in: [packages/ai/src/types.ts:2211](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2211)
+Defined in: [packages/ai/src/types.ts:2226](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2226)
diff --git a/docs/reference/interfaces/TextMessageChunkEvent.md b/docs/reference/interfaces/TextMessageChunkEvent.md
index 54433acfdd..d21a36c621 100644
--- a/docs/reference/interfaces/TextMessageChunkEvent.md
+++ b/docs/reference/interfaces/TextMessageChunkEvent.md
@@ -3,7 +3,7 @@ id: TextMessageChunkEvent
 title: TextMessageChunkEvent
 ---
 
-Defined in: [packages/ai/src/types.ts:2099](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2099)
+Defined in: [packages/ai/src/types.ts:2114](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2114)
 
 AG-UI 1.0 TextMessageChunkEvent shape.
 
diff --git a/docs/reference/interfaces/TextMessageContentEvent.md b/docs/reference/interfaces/TextMessageContentEvent.md
index 4699294b67..f78ebff9e0 100644
--- a/docs/reference/interfaces/TextMessageContentEvent.md
+++ b/docs/reference/interfaces/TextMessageContentEvent.md
@@ -3,7 +3,7 @@ id: TextMessageContentEvent
 title: TextMessageContentEvent
 ---
 
-Defined in: [packages/ai/src/types.ts:1716](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1716)
+Defined in: [packages/ai/src/types.ts:1731](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1731)
 
 Emitted when text content is generated (streaming tokens).
 
diff --git a/docs/reference/interfaces/TextMessageEndEvent.md b/docs/reference/interfaces/TextMessageEndEvent.md
index 1fb7497633..717afac99f 100644
--- a/docs/reference/interfaces/TextMessageEndEvent.md
+++ b/docs/reference/interfaces/TextMessageEndEvent.md
@@ -3,7 +3,7 @@ id: TextMessageEndEvent
 title: TextMessageEndEvent
 ---
 
-Defined in: [packages/ai/src/types.ts:1723](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1723)
+Defined in: [packages/ai/src/types.ts:1738](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1738)
 
 Emitted when a text message completes.
 
diff --git a/docs/reference/interfaces/TextMessageStartEvent.md b/docs/reference/interfaces/TextMessageStartEvent.md
index 1e278e38b3..798cbc2ce3 100644
--- a/docs/reference/interfaces/TextMessageStartEvent.md
+++ b/docs/reference/interfaces/TextMessageStartEvent.md
@@ -3,7 +3,7 @@ id: TextMessageStartEvent
 title: TextMessageStartEvent
 ---
 
-Defined in: [packages/ai/src/types.ts:1709](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1709)
+Defined in: [packages/ai/src/types.ts:1724](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1724)
 
 Emitted when a text message starts.
 
diff --git a/docs/reference/interfaces/TextOptions.md b/docs/reference/interfaces/TextOptions.md
index 5efb79c920..22ed6ee154 100644
--- a/docs/reference/interfaces/TextOptions.md
+++ b/docs/reference/interfaces/TextOptions.md
@@ -3,7 +3,7 @@ id: TextOptions
 title: TextOptions
 ---
 
-Defined in: [packages/ai/src/types.ts:1346](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1346)
+Defined in: [packages/ai/src/types.ts:1361](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1361)
 
 Options passed into the SDK and further piped to the AI provider.
 
@@ -29,7 +29,7 @@ Options passed into the SDK and further piped to the AI provider.
 optional abortController?: AbortController;
 ```
 
-Defined in: [packages/ai/src/types.ts:1474](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1474)
+Defined in: [packages/ai/src/types.ts:1489](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1489)
 
 AbortController for request cancellation.
 
@@ -56,7 +56,7 @@ https://developer.mozilla.org/en-US/docs/Web/API/AbortController
 optional agentLoopStrategy?: AgentLoopStrategy;
 ```
 
-Defined in: [packages/ai/src/types.ts:1374](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1374)
+Defined in: [packages/ai/src/types.ts:1389](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1389)
 
 ***
 
@@ -66,7 +66,7 @@ Defined in: [packages/ai/src/types.ts:1374](https://github.com/TanStack/ai/blob/
 optional approvals?: ReadonlyMap<string, boolean>;
 ```
 
-Defined in: [packages/ai/src/types.ts:1566](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1566)
+Defined in: [packages/ai/src/types.ts:1581](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1581)
 
 Client approval decisions for this run, keyed by approval id. The engine
 populates this from approvals carried on the incoming messages. Harness
@@ -82,7 +82,7 @@ here). Undefined for direct adapter usage outside the chat engine.
 optional capabilities?: CapabilityContext;
 ```
 
-Defined in: [packages/ai/src/types.ts:1557](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1557)
+Defined in: [packages/ai/src/types.ts:1572](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1572)
 
 Middleware capability context for this run. The engine populates it with
 the live middleware context so harness adapters that declare
@@ -99,7 +99,7 @@ direct adapter usage outside the chat engine.
 optional context?: TContext;
 ```
 
-Defined in: [packages/ai/src/types.ts:1358](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1358)
+Defined in: [packages/ai/src/types.ts:1373](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1373)
 
 Runtime context provided by the caller and passed to middleware and
 server-side tool implementations.
@@ -112,7 +112,7 @@ server-side tool implementations.
 optional lazyToolsConfig?: LazyToolsConfig;
 ```
 
-Defined in: [packages/ai/src/types.ts:1412](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1412)
+Defined in: [packages/ai/src/types.ts:1427](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1427)
 
 Optional configuration for lazy-tool discovery (tools marked `lazy: true`).
 Tunes how much of each lazy tool's description appears in the discovery
@@ -126,7 +126,7 @@ catalog. Optional — defaults to `{ includeDescription: 'none' }`.
 logger: InternalLogger;
 ```
 
-Defined in: [packages/ai/src/types.ts:1481](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1481)
+Defined in: [packages/ai/src/types.ts:1496](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1496)
 
 Internal logger threaded from the chat entry point. Adapter implementations
 must call `logger.request()` before SDK calls, `logger.provider()` for each
@@ -143,7 +143,7 @@ messages: ModelMessage<
   | null>[];
 ```
 
-Defined in: [packages/ai/src/types.ts:1352](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1352)
+Defined in: [packages/ai/src/types.ts:1367](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1367)
 
 ***
 
@@ -153,7 +153,7 @@ Defined in: [packages/ai/src/types.ts:1352](https://github.com/TanStack/ai/blob/
 optional metadata?: Record<string, any>;
 ```
 
-Defined in: [packages/ai/src/types.ts:1423](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1423)
+Defined in: [packages/ai/src/types.ts:1438](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1438)
 
 Observability metadata attached to this call. Surfaced to middleware,
 devtools, and the event client; values may be arbitrarily structured
@@ -172,7 +172,7 @@ OpenAI's and OpenRouter's `metadata` are both Record<string, string>).
 optional midConversationChanges?: MidConversationChanges;
 ```
 
-Defined in: [packages/ai/src/types.ts:1522](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1522)
+Defined in: [packages/ai/src/types.ts:1537](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1537)
 
 The tools and system prompts that changed between model calls. The
 engine sets it only when `adapter.midConversationChannels` has a channel
@@ -188,7 +188,7 @@ Adapters resolve it with `splitMidConversationChanges`.
 model: string;
 ```
 
-Defined in: [packages/ai/src/types.ts:1351](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1351)
+Defined in: [packages/ai/src/types.ts:1366](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1366)
 
 ***
 
@@ -198,7 +198,7 @@ Defined in: [packages/ai/src/types.ts:1351](https://github.com/TanStack/ai/blob/
 optional modelOptions?: TProviderOptionsForModel;
 ```
 
-Defined in: [packages/ai/src/types.ts:1424](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1424)
+Defined in: [packages/ai/src/types.ts:1439](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1439)
 
 ***
 
@@ -208,7 +208,7 @@ Defined in: [packages/ai/src/types.ts:1424](https://github.com/TanStack/ai/blob/
 optional outputSchema?: SchemaInput;
 ```
 
-Defined in: [packages/ai/src/types.ts:1460](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1460)
+Defined in: [packages/ai/src/types.ts:1475](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1475)
 
 Schema for structured output.
 
@@ -243,7 +243,7 @@ Schema for structured output.
 optional parentRunId?: string;
 ```
 
-Defined in: [packages/ai/src/types.ts:1503](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1503)
+Defined in: [packages/ai/src/types.ts:1518](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1518)
 
 Parent run ID for AG-UI protocol nested run correlation.
 Surfaced for observability/middleware; not consumed by the LLM call.
@@ -256,7 +256,7 @@ Surfaced for observability/middleware; not consumed by the LLM call.
 optional parentSubagentRunId?: string;
 ```
 
-Defined in: [packages/ai/src/types.ts:1538](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1538)
+Defined in: [packages/ai/src/types.ts:1553](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1553)
 
 The subagentRunId of the child that started this one, for a nested child.
 Middleware reads it as `ctx.parentSubagentRunId`.
@@ -269,7 +269,7 @@ Middleware reads it as `ctx.parentSubagentRunId`.
 optional promptCache?: ResolvedPromptCache;
 ```
 
-Defined in: [packages/ai/src/types.ts:1492](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1492)
+Defined in: [packages/ai/src/types.ts:1507](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1507)
 
 Automatic prompt caching for this request. `chat()` sets it. When it is
 absent, the adapter adds no automatic cache fields.
@@ -282,7 +282,7 @@ absent, the adapter adds no automatic cache fields.
 optional reasoning?: ReasoningRequest;
 ```
 
-Defined in: [packages/ai/src/types.ts:1431](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1431)
+Defined in: [packages/ai/src/types.ts:1446](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1446)
 
 How hard the model thinks, normalized by `chat()`. `undefined`: the user
 did not ask, so the adapter sends nothing and the provider default applies.
@@ -297,7 +297,7 @@ wire field.
 optional repairToolInput?: false | ((context) => unknown);
 ```
 
-Defined in: [packages/ai/src/types.ts:1387](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1387)
+Defined in: [packages/ai/src/types.ts:1402](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1402)
 
 How a tool input that fails the final check is repaired. By default,
 common model mistakes such as `"5"` for a number are repaired against the
@@ -313,7 +313,7 @@ validation error to the model.
 optional request?: Request | RequestInit;
 ```
 
-Defined in: [packages/ai/src/types.ts:1432](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1432)
+Defined in: [packages/ai/src/types.ts:1447](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1447)
 
 ***
 
@@ -323,7 +323,7 @@ Defined in: [packages/ai/src/types.ts:1432](https://github.com/TanStack/ai/blob/
 optional resume?: RunAgentResumeItem[];
 ```
 
-Defined in: [packages/ai/src/types.ts:1547](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1547)
+Defined in: [packages/ai/src/types.ts:1562](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1562)
 
 AG-UI interrupt resume responses supplied by the client on a follow-up run.
 A first-party generic item carries the original request in `metadata`.
@@ -336,7 +336,7 @@ A first-party generic item carries the original request in `metadata`.
 optional retry?: object;
 ```
 
-Defined in: [packages/ai/src/types.ts:1397](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1397)
+Defined in: [packages/ai/src/types.ts:1412](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1412)
 
 Retry a model call when the provider error has a wait time (usually a
 429). `chat()` waits for the `retryAfterMs` time of the `RUN_ERROR`, then
@@ -370,7 +370,7 @@ Longest wait time to accept, in milliseconds. Default 60 000.
 optional runId?: string;
 ```
 
-Defined in: [packages/ai/src/types.ts:1498](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1498)
+Defined in: [packages/ai/src/types.ts:1513](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1513)
 
 Run ID for AG-UI protocol run correlation.
 When provided, this will be used in RunStartedEvent and RunFinishedEvent.
@@ -384,7 +384,7 @@ If not provided, a unique ID will be generated.
 optional state?: unknown;
 ```
 
-Defined in: [packages/ai/src/types.ts:1541](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1541)
+Defined in: [packages/ai/src/types.ts:1556](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1556)
 
 Application state mirrored in a STATE_SNAPSHOT before an interrupt terminal.
 
@@ -396,7 +396,7 @@ Application state mirrored in a STATE_SNAPSHOT before an interrupt terminal.
 optional subagentName?: string;
 ```
 
-Defined in: [packages/ai/src/types.ts:1533](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1533)
+Defined in: [packages/ai/src/types.ts:1548](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1548)
 
 The agent name when this chat runs as a subagent. Middleware reads it as
 `ctx.subagentName`.
@@ -409,7 +409,7 @@ The agent name when this chat runs as a subagent. Middleware reads it as
 optional subagentRunId?: string;
 ```
 
-Defined in: [packages/ai/src/types.ts:1528](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1528)
+Defined in: [packages/ai/src/types.ts:1543](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1543)
 
 AG-UI subagent run id when this chat runs as a child of another run.
 A child `chat()` passes `ctx.subagentRunId`. Middleware reads it as
@@ -423,7 +423,7 @@ A child `chat()` passes `ctx.subagentRunId`. Middleware reads it as
 optional systemPrompts?: SystemPrompt[];
 ```
 
-Defined in: [packages/ai/src/types.ts:1373](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1373)
+Defined in: [packages/ai/src/types.ts:1388](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1388)
 
 System prompts to include with the request.
 
@@ -448,7 +448,7 @@ SystemPrompt
 threadId: string;
 ```
 
-Defined in: [packages/ai/src/types.ts:1487](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1487)
+Defined in: [packages/ai/src/types.ts:1502](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1502)
 
 Thread ID for AG-UI protocol run correlation. Required. It is used in
 RunStartedEvent and RunFinishedEvent.
@@ -461,7 +461,7 @@ RunStartedEvent and RunFinishedEvent.
 optional toolChoice?: ToolChoice<string>;
 ```
 
-Defined in: [packages/ai/src/types.ts:1508](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1508)
+Defined in: [packages/ai/src/types.ts:1523](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1523)
 
 How the model uses the tools of this request. `chat()` sets it only when
 the request has tools. A provider value in `modelOptions` wins over it.
@@ -474,7 +474,7 @@ the request has tools. A provider value in `modelOptions` wins over it.
 optional toolExecution?: "parallel" | "sequential";
 ```
 
-Defined in: [packages/ai/src/types.ts:1379](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1379)
+Defined in: [packages/ai/src/types.ts:1394](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1394)
 
 How the server tools of one model turn run. `'parallel'` (the default)
 starts them together, and `'sequential'` runs them one at a time.
@@ -487,7 +487,7 @@ starts them together, and `'sequential'` runs them one at a time.
 optional tools?: AnyTool[];
 ```
 
-Defined in: [packages/ai/src/types.ts:1353](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1353)
+Defined in: [packages/ai/src/types.ts:1368](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1368)
 
 ***
 
@@ -497,7 +497,7 @@ Defined in: [packages/ai/src/types.ts:1353](https://github.com/TanStack/ai/blob/
 optional wrapFetch?: FetchWrapper;
 ```
 
-Defined in: [packages/ai/src/types.ts:1514](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1514)
+Defined in: [packages/ai/src/types.ts:1529](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1529)
 
 Wraps the fetch of this request. The engine composes the `chat()` option
 and the middleware wrappers into one function. An adapter that supports
diff --git a/docs/reference/interfaces/Tool.md b/docs/reference/interfaces/Tool.md
index 4599ea4ff5..4fc379d1dd 100644
--- a/docs/reference/interfaces/Tool.md
+++ b/docs/reference/interfaces/Tool.md
@@ -3,7 +3,7 @@ id: Tool
 title: Tool
 ---
 
-Defined in: [packages/ai/src/types.ts:1005](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1005)
+Defined in: [packages/ai/src/types.ts:1020](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1020)
 
 Tool/Function definition for function calling.
 
@@ -51,7 +51,7 @@ or plain JSON Schema objects for runtime validation and type safety.
 description: string;
 ```
 
-Defined in: [packages/ai/src/types.ts:1029](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1029)
+Defined in: [packages/ai/src/types.ts:1044](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1044)
 
 Clear description of what the tool does.
 
@@ -72,7 +72,7 @@ Be specific about what the tool does, what parameters it needs, and what it retu
 optional execute?: ToolExecuteFunction<TInput, TOutput, TContext>;
 ```
 
-Defined in: [packages/ai/src/types.ts:1109](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1109)
+Defined in: [packages/ai/src/types.ts:1124](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1124)
 
 Optional function to execute when the model calls this tool.
 
@@ -108,7 +108,7 @@ execute: async (args) => {
 optional inputSchema?: TInput;
 ```
 
-Defined in: [packages/ai/src/types.ts:1069](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1069)
+Defined in: [packages/ai/src/types.ts:1084](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1084)
 
 Schema describing the tool's input parameters.
 
@@ -162,7 +162,7 @@ type({
 optional lazy?: boolean;
 ```
 
-Defined in: [packages/ai/src/types.ts:1115](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1115)
+Defined in: [packages/ai/src/types.ts:1130](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1130)
 
 If true, this tool is lazy and will only be sent to the LLM after being discovered via the lazy tool discovery mechanism. Works with both chat() (the synthetic discovery tool) and Code Mode (kept out of the system prompt and revealed via discover_tools).
 
@@ -174,7 +174,7 @@ If true, this tool is lazy and will only be sent to the LLM after being discover
 optional metadata?: Record<string, any>;
 ```
 
-Defined in: [packages/ai/src/types.ts:1126](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1126)
+Defined in: [packages/ai/src/types.ts:1141](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1141)
 
 Additional metadata for adapters or custom extensions
 
@@ -186,7 +186,7 @@ Additional metadata for adapters or custom extensions
 name: TName;
 ```
 
-Defined in: [packages/ai/src/types.ts:1019](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1019)
+Defined in: [packages/ai/src/types.ts:1034](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1034)
 
 Unique name of the tool (used by the model to call it).
 
@@ -207,7 +207,7 @@ Must be unique within the tools array.
 optional needsApproval?: boolean;
 ```
 
-Defined in: [packages/ai/src/types.ts:1112](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1112)
+Defined in: [packages/ai/src/types.ts:1127](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1127)
 
 If true, tool execution requires user approval before running. Works with both server and client tools.
 
@@ -219,7 +219,7 @@ If true, tool execution requires user approval before running. Works with both s
 optional outputSchema?: TOutput;
 ```
 
-Defined in: [packages/ai/src/types.ts:1090](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1090)
+Defined in: [packages/ai/src/types.ts:1105](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1105)
 
 Optional schema for validating tool output.
 
@@ -250,7 +250,7 @@ z.object({
 optional replay?: "safe" | "never";
 ```
 
-Defined in: [packages/ai/src/types.ts:1123](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1123)
+Defined in: [packages/ai/src/types.ts:1138](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1138)
 
 Whether a host may run this tool again after a crash cut the run
 between the call and its result. `'safe'` runs it again. Omit the
diff --git a/docs/reference/interfaces/ToolCallArgsEvent.md b/docs/reference/interfaces/ToolCallArgsEvent.md
index 3f2191375f..9b774a60a8 100644
--- a/docs/reference/interfaces/ToolCallArgsEvent.md
+++ b/docs/reference/interfaces/ToolCallArgsEvent.md
@@ -3,7 +3,7 @@ id: ToolCallArgsEvent
 title: ToolCallArgsEvent
 ---
 
-Defined in: [packages/ai/src/types.ts:1745](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1745)
+Defined in: [packages/ai/src/types.ts:1760](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1760)
 
 Emitted when tool call arguments are streaming.
 
diff --git a/docs/reference/interfaces/ToolCallChunkEvent.md b/docs/reference/interfaces/ToolCallChunkEvent.md
index 7c1bdaec32..4040eb788e 100644
--- a/docs/reference/interfaces/ToolCallChunkEvent.md
+++ b/docs/reference/interfaces/ToolCallChunkEvent.md
@@ -3,7 +3,7 @@ id: ToolCallChunkEvent
 title: ToolCallChunkEvent
 ---
 
-Defined in: [packages/ai/src/types.ts:2102](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2102)
+Defined in: [packages/ai/src/types.ts:2117](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2117)
 
 AG-UI 1.0 ToolCallChunkEvent shape.
 
diff --git a/docs/reference/interfaces/ToolCallEndEvent.md b/docs/reference/interfaces/ToolCallEndEvent.md
index d13835a295..c6a79e8374 100644
--- a/docs/reference/interfaces/ToolCallEndEvent.md
+++ b/docs/reference/interfaces/ToolCallEndEvent.md
@@ -3,7 +3,7 @@ id: ToolCallEndEvent
 title: ToolCallEndEvent
 ---
 
-Defined in: [packages/ai/src/types.ts:1752](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1752)
+Defined in: [packages/ai/src/types.ts:1767](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1767)
 
 Emitted when a tool call completes.
 
@@ -21,7 +21,7 @@ Emitted when a tool call completes.
 optional input?: unknown;
 ```
 
-Defined in: [packages/ai/src/types.ts:1755](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1755)
+Defined in: [packages/ai/src/types.ts:1770](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1770)
 
 Parsed tool arguments when the adapter already parsed them.
 
@@ -33,7 +33,7 @@ Parsed tool arguments when the adapter already parsed them.
 optional metadata?: Record<string, any>;
 ```
 
-Defined in: [packages/ai/src/types.ts:1756](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1756)
+Defined in: [packages/ai/src/types.ts:1771](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1771)
 
 Extra information attached to this event.
 
@@ -51,4 +51,4 @@ Omit.metadata
 type: "TOOL_CALL_END";
 ```
 
-Defined in: [packages/ai/src/types.ts:1753](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1753)
+Defined in: [packages/ai/src/types.ts:1768](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1768)
diff --git a/docs/reference/interfaces/ToolCallResultEvent.md b/docs/reference/interfaces/ToolCallResultEvent.md
index ff2bcbcdf3..a40d1fb5ed 100644
--- a/docs/reference/interfaces/ToolCallResultEvent.md
+++ b/docs/reference/interfaces/ToolCallResultEvent.md
@@ -3,7 +3,7 @@ id: ToolCallResultEvent
 title: ToolCallResultEvent
 ---
 
-Defined in: [packages/ai/src/types.ts:1764](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1764)
+Defined in: [packages/ai/src/types.ts:1779](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1779)
 
 Emitted when a tool call result is available.
 
diff --git a/docs/reference/interfaces/ToolCallStartEvent.md b/docs/reference/interfaces/ToolCallStartEvent.md
index 9767ddfa1e..81fd14ca17 100644
--- a/docs/reference/interfaces/ToolCallStartEvent.md
+++ b/docs/reference/interfaces/ToolCallStartEvent.md
@@ -3,7 +3,7 @@ id: ToolCallStartEvent
 title: ToolCallStartEvent
 ---
 
-Defined in: [packages/ai/src/types.ts:1731](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1731)
+Defined in: [packages/ai/src/types.ts:1746](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1746)
 
 Emitted when a tool call starts.
 
@@ -22,7 +22,7 @@ Emitted when a tool call starts.
 optional metadata?: Record<string, any>;
 ```
 
-Defined in: [packages/ai/src/types.ts:1737](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1737)
+Defined in: [packages/ai/src/types.ts:1752](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1752)
 
 Provider-specific metadata to carry into the ToolCall.
 
@@ -40,4 +40,4 @@ Omit.metadata
 type: "TOOL_CALL_START";
 ```
 
-Defined in: [packages/ai/src/types.ts:1735](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1735)
+Defined in: [packages/ai/src/types.ts:1750](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1750)
diff --git a/docs/reference/interfaces/ToolConfig.md b/docs/reference/interfaces/ToolConfig.md
index 22117e2bc6..57d1587c38 100644
--- a/docs/reference/interfaces/ToolConfig.md
+++ b/docs/reference/interfaces/ToolConfig.md
@@ -3,7 +3,7 @@ id: ToolConfig
 title: ToolConfig
 ---
 
-Defined in: [packages/ai/src/types.ts:1149](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1149)
+Defined in: [packages/ai/src/types.ts:1164](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1164)
 
 ## Indexable
 
diff --git a/docs/reference/interfaces/ToolDefinition.md b/docs/reference/interfaces/ToolDefinition.md
index 65856b6957..de1616951a 100644
--- a/docs/reference/interfaces/ToolDefinition.md
+++ b/docs/reference/interfaces/ToolDefinition.md
@@ -127,7 +127,7 @@ tool so the tool-call part's `approval` field stays gated on it.
 description: string;
 ```
 
-Defined in: [packages/ai/src/types.ts:1029](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1029)
+Defined in: [packages/ai/src/types.ts:1044](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1044)
 
 Clear description of what the tool does.
 
@@ -154,7 +154,7 @@ optional execute?: (args, context?) =>
 | Promise<InferSchemaType<TOutput>>;
 ```
 
-Defined in: [packages/ai/src/types.ts:1109](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1109)
+Defined in: [packages/ai/src/types.ts:1124](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1124)
 
 Optional function to execute when the model calls this tool.
 
@@ -275,7 +275,7 @@ type({
 optional lazy?: boolean;
 ```
 
-Defined in: [packages/ai/src/types.ts:1115](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1115)
+Defined in: [packages/ai/src/types.ts:1130](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1130)
 
 If true, this tool is lazy and will only be sent to the LLM after being discovered via the lazy tool discovery mechanism. Works with both chat() (the synthetic discovery tool) and Code Mode (kept out of the system prompt and revealed via discover_tools).
 
@@ -291,7 +291,7 @@ If true, this tool is lazy and will only be sent to the LLM after being discover
 optional metadata?: Record<string, any>;
 ```
 
-Defined in: [packages/ai/src/types.ts:1126](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1126)
+Defined in: [packages/ai/src/types.ts:1141](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1141)
 
 Additional metadata for adapters or custom extensions
 
@@ -307,7 +307,7 @@ Additional metadata for adapters or custom extensions
 name: TName;
 ```
 
-Defined in: [packages/ai/src/types.ts:1019](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1019)
+Defined in: [packages/ai/src/types.ts:1034](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1034)
 
 Unique name of the tool (used by the model to call it).
 
@@ -383,7 +383,7 @@ z.object({
 optional replay?: "safe" | "never";
 ```
 
-Defined in: [packages/ai/src/types.ts:1123](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1123)
+Defined in: [packages/ai/src/types.ts:1138](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1138)
 
 Whether a host may run this tool again after a crash cut the run
 between the call and its result. `'safe'` runs it again. Omit the
diff --git a/docs/reference/interfaces/ToolDefinitionInstance.md b/docs/reference/interfaces/ToolDefinitionInstance.md
index 63cb2c254b..8cacc812bd 100644
--- a/docs/reference/interfaces/ToolDefinitionInstance.md
+++ b/docs/reference/interfaces/ToolDefinitionInstance.md
@@ -93,7 +93,7 @@ Defined in: [packages/ai/src/activities/chat/tools/tool-definition.ts:163](https
 description: string;
 ```
 
-Defined in: [packages/ai/src/types.ts:1029](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1029)
+Defined in: [packages/ai/src/types.ts:1044](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1044)
 
 Clear description of what the tool does.
 
@@ -118,7 +118,7 @@ Be specific about what the tool does, what parameters it needs, and what it retu
 optional execute?: ToolExecuteFunction<TInput, TOutput, TContext>;
 ```
 
-Defined in: [packages/ai/src/types.ts:1109](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1109)
+Defined in: [packages/ai/src/types.ts:1124](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1124)
 
 Optional function to execute when the model calls this tool.
 
@@ -226,7 +226,7 @@ type({
 optional lazy?: boolean;
 ```
 
-Defined in: [packages/ai/src/types.ts:1115](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1115)
+Defined in: [packages/ai/src/types.ts:1130](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1130)
 
 If true, this tool is lazy and will only be sent to the LLM after being discovered via the lazy tool discovery mechanism. Works with both chat() (the synthetic discovery tool) and Code Mode (kept out of the system prompt and revealed via discover_tools).
 
@@ -242,7 +242,7 @@ If true, this tool is lazy and will only be sent to the LLM after being discover
 optional metadata?: Record<string, any>;
 ```
 
-Defined in: [packages/ai/src/types.ts:1126](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1126)
+Defined in: [packages/ai/src/types.ts:1141](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1141)
 
 Additional metadata for adapters or custom extensions
 
@@ -258,7 +258,7 @@ Additional metadata for adapters or custom extensions
 name: TName;
 ```
 
-Defined in: [packages/ai/src/types.ts:1019](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1019)
+Defined in: [packages/ai/src/types.ts:1034](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1034)
 
 Unique name of the tool (used by the model to call it).
 
@@ -334,7 +334,7 @@ z.object({
 optional replay?: "safe" | "never";
 ```
 
-Defined in: [packages/ai/src/types.ts:1123](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1123)
+Defined in: [packages/ai/src/types.ts:1138](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1138)
 
 Whether a host may run this tool again after a crash cut the run
 between the call and its result. `'safe'` runs it again. Omit the
diff --git a/docs/reference/interfaces/ToolInputRepairContext.md b/docs/reference/interfaces/ToolInputRepairContext.md
index d2abd45536..ae919e969b 100644
--- a/docs/reference/interfaces/ToolInputRepairContext.md
+++ b/docs/reference/interfaces/ToolInputRepairContext.md
@@ -3,7 +3,7 @@ id: ToolInputRepairContext
 title: ToolInputRepairContext
 ---
 
-Defined in: [packages/ai/src/types.ts:1332](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1332)
+Defined in: [packages/ai/src/types.ts:1347](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1347)
 
 What a `repairToolInput` function gets: a tool input that failed the check.
 
@@ -15,7 +15,7 @@ What a `repairToolInput` function gets: a tool input that failed the check.
 error: Error;
 ```
 
-Defined in: [packages/ai/src/types.ts:1340](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1340)
+Defined in: [packages/ai/src/types.ts:1355](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1355)
 
 The validation error. A Standard Schema error also has `issues`.
 
@@ -27,7 +27,7 @@ The validation error. A Standard Schema error also has `issues`.
 input: unknown;
 ```
 
-Defined in: [packages/ai/src/types.ts:1338](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1338)
+Defined in: [packages/ai/src/types.ts:1353](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1353)
 
 The input that failed, after approval edits and middleware.
 
@@ -39,7 +39,7 @@ The input that failed, after approval edits and middleware.
 tool: AnyTool;
 ```
 
-Defined in: [packages/ai/src/types.ts:1334](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1334)
+Defined in: [packages/ai/src/types.ts:1349](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1349)
 
 The tool the model called.
 
@@ -51,6 +51,6 @@ The tool the model called.
 toolCall: ToolCall;
 ```
 
-Defined in: [packages/ai/src/types.ts:1336](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1336)
+Defined in: [packages/ai/src/types.ts:1351](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1351)
 
 The call, with its id and the raw arguments text.
diff --git a/docs/reference/interfaces/TranscriptionOptions.md b/docs/reference/interfaces/TranscriptionOptions.md
index f982a1b642..a245438814 100644
--- a/docs/reference/interfaces/TranscriptionOptions.md
+++ b/docs/reference/interfaces/TranscriptionOptions.md
@@ -3,7 +3,7 @@ id: TranscriptionOptions
 title: TranscriptionOptions
 ---
 
-Defined in: [packages/ai/src/types.ts:3206](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L3206)
+Defined in: [packages/ai/src/types.ts:3221](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L3221)
 
 ## Type Parameters
 
@@ -19,7 +19,7 @@ Defined in: [packages/ai/src/types.ts:3206](https://github.com/TanStack/ai/blob/
 optional abortSignal?: AbortSignal;
 ```
 
-Defined in: [packages/ai/src/types.ts:3232](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L3232)
+Defined in: [packages/ai/src/types.ts:3247](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L3247)
 
 Effective abort signal composed by the activity from caller `abortSignal`
 and/or `timeout`. Adapters should forward this to the provider SDK when
@@ -33,7 +33,7 @@ supported. Request-specific — never store on a global client config.
 audio: string | ArrayBuffer | File | Blob;
 ```
 
-Defined in: [packages/ai/src/types.ts:3212](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L3212)
+Defined in: [packages/ai/src/types.ts:3227](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L3227)
 
 The audio data to transcribe - can be base64 string, File, Blob, or Buffer
 
@@ -45,7 +45,7 @@ The audio data to transcribe - can be base64 string, File, Blob, or Buffer
 optional language?: string;
 ```
 
-Defined in: [packages/ai/src/types.ts:3214](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L3214)
+Defined in: [packages/ai/src/types.ts:3229](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L3229)
 
 The language of the audio in ISO-639-1 format (e.g., 'en')
 
@@ -57,7 +57,7 @@ The language of the audio in ISO-639-1 format (e.g., 'en')
 logger: InternalLogger;
 ```
 
-Defined in: [packages/ai/src/types.ts:3226](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L3226)
+Defined in: [packages/ai/src/types.ts:3241](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L3241)
 
 Internal logger threaded from the generateTranscription() entry point.
 Adapters must call logger.request() before the SDK call and logger.errors()
@@ -71,7 +71,7 @@ in catch blocks.
 model: string;
 ```
 
-Defined in: [packages/ai/src/types.ts:3210](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L3210)
+Defined in: [packages/ai/src/types.ts:3225](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L3225)
 
 The model to use for transcription
 
@@ -83,7 +83,7 @@ The model to use for transcription
 optional modelOptions?: TProviderOptions;
 ```
 
-Defined in: [packages/ai/src/types.ts:3220](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L3220)
+Defined in: [packages/ai/src/types.ts:3235](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L3235)
 
 Model-specific options for transcription
 
@@ -95,7 +95,7 @@ Model-specific options for transcription
 optional prompt?: string;
 ```
 
-Defined in: [packages/ai/src/types.ts:3216](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L3216)
+Defined in: [packages/ai/src/types.ts:3231](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L3231)
 
 An optional prompt to guide the transcription
 
@@ -107,6 +107,6 @@ An optional prompt to guide the transcription
 optional responseFormat?: TranscriptionResponseFormat;
 ```
 
-Defined in: [packages/ai/src/types.ts:3218](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L3218)
+Defined in: [packages/ai/src/types.ts:3233](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L3233)
 
 The format of the transcription output
diff --git a/docs/reference/interfaces/TranscriptionResult.md b/docs/reference/interfaces/TranscriptionResult.md
index f058542dc3..0c1e9ef7fd 100644
--- a/docs/reference/interfaces/TranscriptionResult.md
+++ b/docs/reference/interfaces/TranscriptionResult.md
@@ -3,7 +3,7 @@ id: TranscriptionResult
 title: TranscriptionResult
 ---
 
-Defined in: [packages/ai/src/types.ts:3268](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L3268)
+Defined in: [packages/ai/src/types.ts:3283](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L3283)
 
 Result of audio transcription.
 
@@ -15,7 +15,7 @@ Result of audio transcription.
 optional artifacts?: PersistedArtifactRef[];
 ```
 
-Defined in: [packages/ai/src/types.ts:3286](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L3286)
+Defined in: [packages/ai/src/types.ts:3301](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L3301)
 
 Persisted artifact references for generated assets, when available
 
@@ -27,7 +27,7 @@ Persisted artifact references for generated assets, when available
 optional duration?: number;
 ```
 
-Defined in: [packages/ai/src/types.ts:3278](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L3278)
+Defined in: [packages/ai/src/types.ts:3293](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L3293)
 
 Duration of the audio in seconds
 
@@ -39,7 +39,7 @@ Duration of the audio in seconds
 id: string;
 ```
 
-Defined in: [packages/ai/src/types.ts:3270](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L3270)
+Defined in: [packages/ai/src/types.ts:3285](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L3285)
 
 Unique identifier for the transcription
 
@@ -51,7 +51,7 @@ Unique identifier for the transcription
 optional language?: string;
 ```
 
-Defined in: [packages/ai/src/types.ts:3276](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L3276)
+Defined in: [packages/ai/src/types.ts:3291](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L3291)
 
 Language detected or specified
 
@@ -63,7 +63,7 @@ Language detected or specified
 model: string;
 ```
 
-Defined in: [packages/ai/src/types.ts:3272](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L3272)
+Defined in: [packages/ai/src/types.ts:3287](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L3287)
 
 Model used for transcription
 
@@ -75,7 +75,7 @@ Model used for transcription
 optional segments?: TranscriptionSegment[];
 ```
 
-Defined in: [packages/ai/src/types.ts:3280](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L3280)
+Defined in: [packages/ai/src/types.ts:3295](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L3295)
 
 Detailed segments with timing, if available
 
@@ -87,7 +87,7 @@ Detailed segments with timing, if available
 text: string;
 ```
 
-Defined in: [packages/ai/src/types.ts:3274](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L3274)
+Defined in: [packages/ai/src/types.ts:3289](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L3289)
 
 The full transcribed text
 
@@ -99,7 +99,7 @@ The full transcribed text
 optional usage?: TokenUsage<ProviderUsageDetails>;
 ```
 
-Defined in: [packages/ai/src/types.ts:3284](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L3284)
+Defined in: [packages/ai/src/types.ts:3299](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L3299)
 
 Token usage information (if provided by the adapter)
 
@@ -111,6 +111,6 @@ Token usage information (if provided by the adapter)
 optional words?: TranscriptionWord[];
 ```
 
-Defined in: [packages/ai/src/types.ts:3282](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L3282)
+Defined in: [packages/ai/src/types.ts:3297](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L3297)
 
 Word-level timestamps, if available
diff --git a/docs/reference/interfaces/TranscriptionSegment.md b/docs/reference/interfaces/TranscriptionSegment.md
index 444ca692ea..cf195cec69 100644
--- a/docs/reference/interfaces/TranscriptionSegment.md
+++ b/docs/reference/interfaces/TranscriptionSegment.md
@@ -3,7 +3,7 @@ id: TranscriptionSegment
 title: TranscriptionSegment
 ---
 
-Defined in: [packages/ai/src/types.ts:3238](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L3238)
+Defined in: [packages/ai/src/types.ts:3253](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L3253)
 
 A single segment of transcribed audio with timing information.
 
@@ -15,7 +15,7 @@ A single segment of transcribed audio with timing information.
 optional confidence?: number;
 ```
 
-Defined in: [packages/ai/src/types.ts:3248](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L3248)
+Defined in: [packages/ai/src/types.ts:3263](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L3263)
 
 Confidence score (0-1), if available
 
@@ -27,7 +27,7 @@ Confidence score (0-1), if available
 end: number;
 ```
 
-Defined in: [packages/ai/src/types.ts:3244](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L3244)
+Defined in: [packages/ai/src/types.ts:3259](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L3259)
 
 End time of the segment in seconds
 
@@ -39,7 +39,7 @@ End time of the segment in seconds
 id: number;
 ```
 
-Defined in: [packages/ai/src/types.ts:3240](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L3240)
+Defined in: [packages/ai/src/types.ts:3255](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L3255)
 
 Unique identifier for the segment
 
@@ -51,7 +51,7 @@ Unique identifier for the segment
 optional speaker?: string;
 ```
 
-Defined in: [packages/ai/src/types.ts:3250](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L3250)
+Defined in: [packages/ai/src/types.ts:3265](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L3265)
 
 Speaker identifier, if diarization is enabled
 
@@ -63,7 +63,7 @@ Speaker identifier, if diarization is enabled
 start: number;
 ```
 
-Defined in: [packages/ai/src/types.ts:3242](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L3242)
+Defined in: [packages/ai/src/types.ts:3257](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L3257)
 
 Start time of the segment in seconds
 
@@ -75,6 +75,6 @@ Start time of the segment in seconds
 text: string;
 ```
 
-Defined in: [packages/ai/src/types.ts:3246](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L3246)
+Defined in: [packages/ai/src/types.ts:3261](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L3261)
 
 Transcribed text for this segment
diff --git a/docs/reference/interfaces/TranscriptionWord.md b/docs/reference/interfaces/TranscriptionWord.md
index 90e375eea4..ced7283063 100644
--- a/docs/reference/interfaces/TranscriptionWord.md
+++ b/docs/reference/interfaces/TranscriptionWord.md
@@ -3,7 +3,7 @@ id: TranscriptionWord
 title: TranscriptionWord
 ---
 
-Defined in: [packages/ai/src/types.ts:3256](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L3256)
+Defined in: [packages/ai/src/types.ts:3271](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L3271)
 
 A single word with timing information.
 
@@ -15,7 +15,7 @@ A single word with timing information.
 end: number;
 ```
 
-Defined in: [packages/ai/src/types.ts:3262](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L3262)
+Defined in: [packages/ai/src/types.ts:3277](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L3277)
 
 End time in seconds
 
@@ -27,7 +27,7 @@ End time in seconds
 start: number;
 ```
 
-Defined in: [packages/ai/src/types.ts:3260](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L3260)
+Defined in: [packages/ai/src/types.ts:3275](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L3275)
 
 Start time in seconds
 
@@ -39,6 +39,6 @@ Start time in seconds
 word: string;
 ```
 
-Defined in: [packages/ai/src/types.ts:3258](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L3258)
+Defined in: [packages/ai/src/types.ts:3273](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L3273)
 
 The transcribed word
diff --git a/docs/reference/interfaces/UIMessage.md b/docs/reference/interfaces/UIMessage.md
index 025c72c4b0..4a31126b93 100644
--- a/docs/reference/interfaces/UIMessage.md
+++ b/docs/reference/interfaces/UIMessage.md
@@ -3,7 +3,7 @@ id: UIMessage
 title: UIMessage
 ---
 
-Defined in: [packages/ai/src/types.ts:805](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L805)
+Defined in: [packages/ai/src/types.ts:820](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L820)
 
 UIMessage - Domain-specific message format optimized for building chat UIs
 Contains parts that can be text, tool calls, or tool results. Generic over
@@ -25,7 +25,7 @@ consumer side without manual casts.
 optional createdAt?: Date;
 ```
 
-Defined in: [packages/ai/src/types.ts:809](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L809)
+Defined in: [packages/ai/src/types.ts:824](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L824)
 
 ***
 
@@ -35,7 +35,7 @@ Defined in: [packages/ai/src/types.ts:809](https://github.com/TanStack/ai/blob/m
 id: string;
 ```
 
-Defined in: [packages/ai/src/types.ts:806](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L806)
+Defined in: [packages/ai/src/types.ts:821](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L821)
 
 ***
 
@@ -45,7 +45,7 @@ Defined in: [packages/ai/src/types.ts:806](https://github.com/TanStack/ai/blob/m
 optional metadata?: Record<string, any>;
 ```
 
-Defined in: [packages/ai/src/types.ts:816](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L816)
+Defined in: [packages/ai/src/types.ts:831](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L831)
 
 Optional AG-UI metadata bag. TanStack writes the `tanstack` key.
 User keys stay at the top.
@@ -58,7 +58,7 @@ User keys stay at the top.
 optional name?: string;
 ```
 
-Defined in: [packages/ai/src/types.ts:811](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L811)
+Defined in: [packages/ai/src/types.ts:826](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L826)
 
 Optional AG-UI sender name. Converters preserve it across wire and persist.
 
@@ -70,7 +70,7 @@ Optional AG-UI sender name. Converters preserve it across wire and persist.
 parts: MessagePart<TData>[];
 ```
 
-Defined in: [packages/ai/src/types.ts:808](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L808)
+Defined in: [packages/ai/src/types.ts:823](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L823)
 
 ***
 
@@ -80,4 +80,4 @@ Defined in: [packages/ai/src/types.ts:808](https://github.com/TanStack/ai/blob/m
 role: "assistant" | "user" | "activity" | "system";
 ```
 
-Defined in: [packages/ai/src/types.ts:807](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L807)
+Defined in: [packages/ai/src/types.ts:822](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L822)
diff --git a/docs/reference/interfaces/UIResourceEvent.md b/docs/reference/interfaces/UIResourceEvent.md
index baff55a6f9..262882305d 100644
--- a/docs/reference/interfaces/UIResourceEvent.md
+++ b/docs/reference/interfaces/UIResourceEvent.md
@@ -3,7 +3,7 @@ id: UIResourceEvent
 title: UIResourceEvent
 ---
 
-Defined in: [packages/ai/src/types.ts:1857](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1857)
+Defined in: [packages/ai/src/types.ts:1872](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1872)
 
 Emitted when an MCP tool returns a ui:// resource (MCP Apps). Reconciled into
  a UIResourcePart on the assistant UIMessage. Never enters model input.
@@ -20,7 +20,7 @@ Emitted when an MCP tool returns a ui:// resource (MCP Apps). Reconciled into
 optional metadata?: Record<string, any>;
 ```
 
-Defined in: [packages/ai/src/types.ts:1814](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1814)
+Defined in: [packages/ai/src/types.ts:1829](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1829)
 
 Extra information attached to this event.
 
@@ -36,7 +36,7 @@ Extra information attached to this event.
 name: "ui-resource";
 ```
 
-Defined in: [packages/ai/src/types.ts:1858](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1858)
+Defined in: [packages/ai/src/types.ts:1873](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1873)
 
 What this custom event is. Required: without it a consumer cannot route
 the value.
@@ -55,7 +55,7 @@ CustomEvent.name
 type: "CUSTOM";
 ```
 
-Defined in: [packages/ai/src/types.ts:1813](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1813)
+Defined in: [packages/ai/src/types.ts:1828](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1828)
 
 #### Inherited from
 
@@ -69,7 +69,7 @@ Defined in: [packages/ai/src/types.ts:1813](https://github.com/TanStack/ai/blob/
 value: object;
 ```
 
-Defined in: [packages/ai/src/types.ts:1859](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1859)
+Defined in: [packages/ai/src/types.ts:1874](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1874)
 
 The payload. Any JSON value, and required.
 
diff --git a/docs/reference/interfaces/VideoGenerationOptions.md b/docs/reference/interfaces/VideoGenerationOptions.md
index dea4f9509e..01e10b5a18 100644
--- a/docs/reference/interfaces/VideoGenerationOptions.md
+++ b/docs/reference/interfaces/VideoGenerationOptions.md
@@ -3,7 +3,7 @@ id: VideoGenerationOptions
 title: VideoGenerationOptions
 ---
 
-Defined in: [packages/ai/src/types.ts:2608](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2608)
+Defined in: [packages/ai/src/types.ts:2623](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2623)
 
 Options for video generation.
 These are the common options supported across providers.
@@ -30,7 +30,7 @@ These are the common options supported across providers.
 optional abortSignal?: AbortSignal;
 ```
 
-Defined in: [packages/ai/src/types.ts:2645](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2645)
+Defined in: [packages/ai/src/types.ts:2660](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2660)
 
 Effective abort signal composed by the activity from caller `abortSignal`
 and/or `timeout`. Adapters should forward this to the provider SDK when
@@ -44,7 +44,7 @@ supported. Request-specific — never store on a global client config.
 optional duration?: TDuration;
 ```
 
-Defined in: [packages/ai/src/types.ts:2632](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2632)
+Defined in: [packages/ai/src/types.ts:2647](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2647)
 
 Video duration. Adapters that declare a per-model duration map narrow
 this to that model's union (a number, `"8"`, or `"8s"`). Use
@@ -59,7 +59,7 @@ seconds, a `"6s"` template, or `"auto"` when the model lists it.
 logger: InternalLogger;
 ```
 
-Defined in: [packages/ai/src/types.ts:2639](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2639)
+Defined in: [packages/ai/src/types.ts:2654](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2654)
 
 Internal logger threaded from the generateVideo() entry point. Adapters must
 call logger.request() before the SDK call and logger.errors() in catch blocks.
@@ -72,7 +72,7 @@ call logger.request() before the SDK call and logger.errors() in catch blocks.
 model: string;
 ```
 
-Defined in: [packages/ai/src/types.ts:2614](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2614)
+Defined in: [packages/ai/src/types.ts:2629](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2629)
 
 The model to use for video generation
 
@@ -84,7 +84,7 @@ The model to use for video generation
 optional modelOptions?: TProviderOptions;
 ```
 
-Defined in: [packages/ai/src/types.ts:2634](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2634)
+Defined in: [packages/ai/src/types.ts:2649](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2649)
 
 Model-specific options for video generation
 
@@ -96,7 +96,7 @@ Model-specific options for video generation
 prompt: MediaPrompt;
 ```
 
-Defined in: [packages/ai/src/types.ts:2623](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2623)
+Defined in: [packages/ai/src/types.ts:2638](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2638)
 
 Description of the desired video: a plain string, or an ordered array of
 content parts for image-conditioned generation. Image parts may carry
@@ -113,6 +113,6 @@ provider-native request (e.g. OpenAI Sora `input_reference`, fal
 optional size?: TSize;
 ```
 
-Defined in: [packages/ai/src/types.ts:2625](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2625)
+Defined in: [packages/ai/src/types.ts:2640](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2640)
 
 Video size — format depends on the provider (e.g., "16:9", "1280x720")
diff --git a/docs/reference/interfaces/VideoJobResult.md b/docs/reference/interfaces/VideoJobResult.md
index d7bde2ed99..0dc1bdb933 100644
--- a/docs/reference/interfaces/VideoJobResult.md
+++ b/docs/reference/interfaces/VideoJobResult.md
@@ -3,7 +3,7 @@ id: VideoJobResult
 title: VideoJobResult
 ---
 
-Defined in: [packages/ai/src/types.ts:2651](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2651)
+Defined in: [packages/ai/src/types.ts:2666](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2666)
 
 Result of creating a video generation job.
 
@@ -15,7 +15,7 @@ Result of creating a video generation job.
 optional artifacts?: PersistedArtifactRef[];
 ```
 
-Defined in: [packages/ai/src/types.ts:2661](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2661)
+Defined in: [packages/ai/src/types.ts:2676](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2676)
 
 Durable artifact references, when generation persistence with an artifact +
 blob store is wired. A submission has no video yet, so this only carries
@@ -29,7 +29,7 @@ refs for persisted prompt INPUTS (e.g. a start frame).
 jobId: string;
 ```
 
-Defined in: [packages/ai/src/types.ts:2653](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2653)
+Defined in: [packages/ai/src/types.ts:2668](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2668)
 
 Unique job identifier for polling status
 
@@ -41,6 +41,6 @@ Unique job identifier for polling status
 model: string;
 ```
 
-Defined in: [packages/ai/src/types.ts:2655](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2655)
+Defined in: [packages/ai/src/types.ts:2670](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2670)
 
 Model used for generation
diff --git a/docs/reference/interfaces/VideoStatusResult.md b/docs/reference/interfaces/VideoStatusResult.md
index 854aa15a7d..d5a6c0cbd8 100644
--- a/docs/reference/interfaces/VideoStatusResult.md
+++ b/docs/reference/interfaces/VideoStatusResult.md
@@ -3,7 +3,7 @@ id: VideoStatusResult
 title: VideoStatusResult
 ---
 
-Defined in: [packages/ai/src/types.ts:2667](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2667)
+Defined in: [packages/ai/src/types.ts:2682](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2682)
 
 Status of a video generation job.
 
@@ -15,7 +15,7 @@ Status of a video generation job.
 optional error?: string;
 ```
 
-Defined in: [packages/ai/src/types.ts:2675](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2675)
+Defined in: [packages/ai/src/types.ts:2690](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2690)
 
 Error message if status is 'failed'
 
@@ -27,7 +27,7 @@ Error message if status is 'failed'
 jobId: string;
 ```
 
-Defined in: [packages/ai/src/types.ts:2669](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2669)
+Defined in: [packages/ai/src/types.ts:2684](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2684)
 
 Job identifier
 
@@ -39,7 +39,7 @@ Job identifier
 optional progress?: number;
 ```
 
-Defined in: [packages/ai/src/types.ts:2673](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2673)
+Defined in: [packages/ai/src/types.ts:2688](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2688)
 
 Progress percentage (0-100), if available
 
@@ -51,6 +51,6 @@ Progress percentage (0-100), if available
 status: "pending" | "processing" | "completed" | "failed";
 ```
 
-Defined in: [packages/ai/src/types.ts:2671](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2671)
+Defined in: [packages/ai/src/types.ts:2686](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2686)
 
 Current status of the job
diff --git a/docs/reference/interfaces/VideoStreamResult.md b/docs/reference/interfaces/VideoStreamResult.md
index edf23584e3..dc7ff04c30 100644
--- a/docs/reference/interfaces/VideoStreamResult.md
+++ b/docs/reference/interfaces/VideoStreamResult.md
@@ -3,7 +3,7 @@ id: VideoStreamResult
 title: VideoStreamResult
 ---
 
-Defined in: [packages/ai/src/types.ts:2704](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2704)
+Defined in: [packages/ai/src/types.ts:2719](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2719)
 
 Video bytes from a provider that has no public URL for the finished video.
 Core passes `body` to generation middleware, which streams it into storage
@@ -17,7 +17,7 @@ and sets `url`. Use `withGenerationPersistence` with `artifactUrl`.
 body: ReadableStream<Uint8Array<ArrayBufferLike>>;
 ```
 
-Defined in: [packages/ai/src/types.ts:2708](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2708)
+Defined in: [packages/ai/src/types.ts:2723](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2723)
 
 The video bytes. Read once, with backpressure. Never buffer it whole.
 
@@ -29,7 +29,7 @@ The video bytes. Read once, with backpressure. Never buffer it whole.
 contentType: string;
 ```
 
-Defined in: [packages/ai/src/types.ts:2710](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2710)
+Defined in: [packages/ai/src/types.ts:2725](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2725)
 
 MIME type of `body`, e.g. `video/mp4`.
 
@@ -41,7 +41,7 @@ MIME type of `body`, e.g. `video/mp4`.
 jobId: string;
 ```
 
-Defined in: [packages/ai/src/types.ts:2706](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2706)
+Defined in: [packages/ai/src/types.ts:2721](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2721)
 
 Job identifier
 
@@ -53,7 +53,7 @@ Job identifier
 optional url?: undefined;
 ```
 
-Defined in: [packages/ai/src/types.ts:2712](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2712)
+Defined in: [packages/ai/src/types.ts:2727](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2727)
 
 ***
 
@@ -63,4 +63,4 @@ Defined in: [packages/ai/src/types.ts:2712](https://github.com/TanStack/ai/blob/
 optional usage?: TokenUsage<ProviderUsageDetails>;
 ```
 
-Defined in: [packages/ai/src/types.ts:2711](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2711)
+Defined in: [packages/ai/src/types.ts:2726](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2726)
diff --git a/docs/reference/interfaces/VideoUrlResult.md b/docs/reference/interfaces/VideoUrlResult.md
index ea684aafe3..87eba8dbd1 100644
--- a/docs/reference/interfaces/VideoUrlResult.md
+++ b/docs/reference/interfaces/VideoUrlResult.md
@@ -3,7 +3,7 @@ id: VideoUrlResult
 title: VideoUrlResult
 ---
 
-Defined in: [packages/ai/src/types.ts:2681](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2681)
+Defined in: [packages/ai/src/types.ts:2696](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2696)
 
 Result containing the URL to a generated video.
 
@@ -15,7 +15,7 @@ Result containing the URL to a generated video.
 optional artifacts?: PersistedArtifactRef[];
 ```
 
-Defined in: [packages/ai/src/types.ts:2695](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2695)
+Defined in: [packages/ai/src/types.ts:2710](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2710)
 
 Persisted artifact references for generated assets, when available
 
@@ -27,7 +27,7 @@ Persisted artifact references for generated assets, when available
 optional body?: undefined;
 ```
 
-Defined in: [packages/ai/src/types.ts:2696](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2696)
+Defined in: [packages/ai/src/types.ts:2711](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2711)
 
 ***
 
@@ -37,7 +37,7 @@ Defined in: [packages/ai/src/types.ts:2696](https://github.com/TanStack/ai/blob/
 optional expiresAt?: Date;
 ```
 
-Defined in: [packages/ai/src/types.ts:2687](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2687)
+Defined in: [packages/ai/src/types.ts:2702](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2702)
 
 When the URL expires, if applicable
 
@@ -49,7 +49,7 @@ When the URL expires, if applicable
 jobId: string;
 ```
 
-Defined in: [packages/ai/src/types.ts:2683](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2683)
+Defined in: [packages/ai/src/types.ts:2698](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2698)
 
 Job identifier
 
@@ -61,7 +61,7 @@ Job identifier
 url: string;
 ```
 
-Defined in: [packages/ai/src/types.ts:2685](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2685)
+Defined in: [packages/ai/src/types.ts:2700](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2700)
 
 URL to the generated video
 
@@ -73,7 +73,7 @@ URL to the generated video
 optional usage?: TokenUsage<ProviderUsageDetails>;
 ```
 
-Defined in: [packages/ai/src/types.ts:2693](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2693)
+Defined in: [packages/ai/src/types.ts:2708](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2708)
 
 Usage information for the completed generation, when the adapter can report
 it. For usage-based providers (e.g. fal) this carries `billed` — the real
diff --git a/docs/reference/interfaces/VoiceGenerationOptions.md b/docs/reference/interfaces/VoiceGenerationOptions.md
index 1f56e886ab..521ca3b017 100644
--- a/docs/reference/interfaces/VoiceGenerationOptions.md
+++ b/docs/reference/interfaces/VoiceGenerationOptions.md
@@ -3,7 +3,7 @@ id: VoiceGenerationOptions
 title: VoiceGenerationOptions
 ---
 
-Defined in: [packages/ai/src/types.ts:3088](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L3088)
+Defined in: [packages/ai/src/types.ts:3103](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L3103)
 
 Options for creating a voice.
 
@@ -30,7 +30,7 @@ takes `referenceAudio` as an additional design reference.
 optional abortSignal?: AbortSignal;
 ```
 
-Defined in: [packages/ai/src/types.ts:3123](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L3123)
+Defined in: [packages/ai/src/types.ts:3138](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L3138)
 
 Effective abort signal composed by the activity from caller `abortSignal`
 and/or `timeout`. Adapters should forward this to the provider SDK when
@@ -44,7 +44,7 @@ supported. Request-specific - never store on a global client config.
 optional description?: string;
 ```
 
-Defined in: [packages/ai/src/types.ts:3109](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L3109)
+Defined in: [packages/ai/src/types.ts:3124](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L3124)
 
 Human-readable description stored alongside the voice
 
@@ -56,7 +56,7 @@ Human-readable description stored alongside the voice
 logger: InternalLogger;
 ```
 
-Defined in: [packages/ai/src/types.ts:3117](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L3117)
+Defined in: [packages/ai/src/types.ts:3132](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L3132)
 
 Internal logger threaded from the generateVoice() entry point. Adapters
 must call logger.request() before the SDK call and logger.errors() in
@@ -70,7 +70,7 @@ catch blocks.
 model: string;
 ```
 
-Defined in: [packages/ai/src/types.ts:3092](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L3092)
+Defined in: [packages/ai/src/types.ts:3107](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L3107)
 
 The model to use for voice creation
 
@@ -82,7 +82,7 @@ The model to use for voice creation
 optional modelOptions?: TProviderOptions;
 ```
 
-Defined in: [packages/ai/src/types.ts:3111](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L3111)
+Defined in: [packages/ai/src/types.ts:3126](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L3126)
 
 Model-specific options for voice creation
 
@@ -94,7 +94,7 @@ Model-specific options for voice creation
 optional name?: string;
 ```
 
-Defined in: [packages/ai/src/types.ts:3107](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L3107)
+Defined in: [packages/ai/src/types.ts:3122](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L3122)
 
 Name to store the voice under in the provider's voice library. Providers
 differ on what this implies — ElevenLabs only persists a designed voice
@@ -109,7 +109,7 @@ actually happened.
 optional prompt?: string;
 ```
 
-Defined in: [packages/ai/src/types.ts:3094](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L3094)
+Defined in: [packages/ai/src/types.ts:3109](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L3109)
 
 Text description of the voice to create, for design-capable models
 
@@ -121,7 +121,7 @@ Text description of the voice to create, for design-capable models
 optional referenceAudio?: string | ArrayBuffer | File | Blob;
 ```
 
-Defined in: [packages/ai/src/types.ts:3100](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L3100)
+Defined in: [packages/ai/src/types.ts:3115](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L3115)
 
 Reference audio of the speaker to clone - base64 string, base64 data URL,
 File, Blob, or ArrayBuffer. For clone-capable models. Remote URLs are not
diff --git a/docs/reference/interfaces/VoiceResult.md b/docs/reference/interfaces/VoiceResult.md
index 9f95abc673..295add1a1a 100644
--- a/docs/reference/interfaces/VoiceResult.md
+++ b/docs/reference/interfaces/VoiceResult.md
@@ -3,7 +3,7 @@ id: VoiceResult
 title: VoiceResult
 ---
 
-Defined in: [packages/ai/src/types.ts:3176](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L3176)
+Defined in: [packages/ai/src/types.ts:3191](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L3191)
 
 Result of voice creation.
 
@@ -18,7 +18,7 @@ models return exactly one.
 optional artifacts?: PersistedArtifactRef[];
 ```
 
-Defined in: [packages/ai/src/types.ts:3188](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L3188)
+Defined in: [packages/ai/src/types.ts:3203](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L3203)
 
 Persisted artifact references for generated assets, when available
 
@@ -30,7 +30,7 @@ Persisted artifact references for generated assets, when available
 id: string;
 ```
 
-Defined in: [packages/ai/src/types.ts:3178](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L3178)
+Defined in: [packages/ai/src/types.ts:3193](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L3193)
 
 Unique identifier for the generation
 
@@ -42,7 +42,7 @@ Unique identifier for the generation
 model: string;
 ```
 
-Defined in: [packages/ai/src/types.ts:3180](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L3180)
+Defined in: [packages/ai/src/types.ts:3195](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L3195)
 
 Model used for generation
 
@@ -54,7 +54,7 @@ Model used for generation
 optional previewText?: string;
 ```
 
-Defined in: [packages/ai/src/types.ts:3184](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L3184)
+Defined in: [packages/ai/src/types.ts:3199](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L3199)
 
 The line spoken in the previews, when the provider generated one
 
@@ -66,7 +66,7 @@ The line spoken in the previews, when the provider generated one
 optional usage?: TokenUsage<ProviderUsageDetails>;
 ```
 
-Defined in: [packages/ai/src/types.ts:3186](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L3186)
+Defined in: [packages/ai/src/types.ts:3201](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L3201)
 
 Token usage information (if provided by the adapter)
 
@@ -78,6 +78,6 @@ Token usage information (if provided by the adapter)
 voices: GeneratedVoice[];
 ```
 
-Defined in: [packages/ai/src/types.ts:3182](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L3182)
+Defined in: [packages/ai/src/types.ts:3197](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L3197)
 
 The voices produced, best-first when the provider ranks them
diff --git a/docs/reference/interfaces/WorldGenerationAssets.md b/docs/reference/interfaces/WorldGenerationAssets.md
index 3c1ce774f7..6300a983b0 100644
--- a/docs/reference/interfaces/WorldGenerationAssets.md
+++ b/docs/reference/interfaces/WorldGenerationAssets.md
@@ -3,7 +3,7 @@ id: WorldGenerationAssets
 title: WorldGenerationAssets
 ---
 
-Defined in: [packages/ai/src/types.ts:2759](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2759)
+Defined in: [packages/ai/src/types.ts:2774](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2774)
 
 **`Experimental`**
 
@@ -21,7 +21,7 @@ to fetch from a browser.
 optional caption?: string;
 ```
 
-Defined in: [packages/ai/src/types.ts:2761](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2761)
+Defined in: [packages/ai/src/types.ts:2776](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2776)
 
 **`Experimental`**
 
@@ -35,7 +35,7 @@ Auto-generated scene description
 optional imagery?: object;
 ```
 
-Defined in: [packages/ai/src/types.ts:2775](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2775)
+Defined in: [packages/ai/src/types.ts:2790](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2790)
 
 **`Experimental`**
 
@@ -53,7 +53,7 @@ optional panoUrl?: string;
 optional mesh?: object;
 ```
 
-Defined in: [packages/ai/src/types.ts:2770](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2770)
+Defined in: [packages/ai/src/types.ts:2785](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2785)
 
 **`Experimental`**
 
@@ -83,7 +83,7 @@ optional hqMeshUrl?: string;
 optional splats?: object;
 ```
 
-Defined in: [packages/ai/src/types.ts:2764](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2764)
+Defined in: [packages/ai/src/types.ts:2779](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2779)
 
 **`Experimental`**
 
@@ -115,7 +115,7 @@ Quality-key map of splat URLs (`100k`, `500k`, `full_res`, …)
 optional thumbnailUrl?: string;
 ```
 
-Defined in: [packages/ai/src/types.ts:2763](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2763)
+Defined in: [packages/ai/src/types.ts:2778](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2778)
 
 **`Experimental`**
 
diff --git a/docs/reference/interfaces/WorldGenerationOptions.md b/docs/reference/interfaces/WorldGenerationOptions.md
index cb4798e737..c84404592d 100644
--- a/docs/reference/interfaces/WorldGenerationOptions.md
+++ b/docs/reference/interfaces/WorldGenerationOptions.md
@@ -3,7 +3,7 @@ id: WorldGenerationOptions
 title: WorldGenerationOptions
 ---
 
-Defined in: [packages/ai/src/types.ts:2724](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2724)
+Defined in: [packages/ai/src/types.ts:2739](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2739)
 
 **`Experimental`**
 
@@ -25,7 +25,7 @@ Options for world generation (live session or finished job).
 optional abortSignal?: AbortSignal;
 ```
 
-Defined in: [packages/ai/src/types.ts:2749](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2749)
+Defined in: [packages/ai/src/types.ts:2764](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2764)
 
 **`Experimental`**
 
@@ -41,7 +41,7 @@ supported. Request-specific — never store on a global client config.
 logger: InternalLogger;
 ```
 
-Defined in: [packages/ai/src/types.ts:2743](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2743)
+Defined in: [packages/ai/src/types.ts:2758](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2758)
 
 **`Experimental`**
 
@@ -57,7 +57,7 @@ catch blocks.
 model: string;
 ```
 
-Defined in: [packages/ai/src/types.ts:2728](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2728)
+Defined in: [packages/ai/src/types.ts:2743](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2743)
 
 **`Experimental`**
 
@@ -71,7 +71,7 @@ The model to use for world generation
 optional modelOptions?: TProviderOptions;
 ```
 
-Defined in: [packages/ai/src/types.ts:2737](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2737)
+Defined in: [packages/ai/src/types.ts:2752](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2752)
 
 **`Experimental`**
 
@@ -88,7 +88,7 @@ token-mint fields.
 prompt: string;
 ```
 
-Defined in: [packages/ai/src/types.ts:2730](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2730)
+Defined in: [packages/ai/src/types.ts:2745](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2745)
 
 **`Experimental`**
 
diff --git a/docs/reference/interfaces/WorldGenerationResult.md b/docs/reference/interfaces/WorldGenerationResult.md
index 647cf88bb9..c947328e54 100644
--- a/docs/reference/interfaces/WorldGenerationResult.md
+++ b/docs/reference/interfaces/WorldGenerationResult.md
@@ -3,7 +3,7 @@ id: WorldGenerationResult
 title: WorldGenerationResult
 ---
 
-Defined in: [packages/ai/src/types.ts:2793](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2793)
+Defined in: [packages/ai/src/types.ts:2808](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2808)
 
 **`Experimental`**
 
@@ -27,7 +27,7 @@ Job adapters (World Labs): `status: 'ready'` with viewer `url` and
 optional assets?: WorldGenerationAssets;
 ```
 
-Defined in: [packages/ai/src/types.ts:2818](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2818)
+Defined in: [packages/ai/src/types.ts:2833](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2833)
 
 **`Experimental`**
 
@@ -41,7 +41,7 @@ Assets when a world job has finished and the provider returned them
 optional expiresAt?: number;
 ```
 
-Defined in: [packages/ai/src/types.ts:2804](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2804)
+Defined in: [packages/ai/src/types.ts:2819](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2819)
 
 **`Experimental`**
 
@@ -56,7 +56,7 @@ Job adapters: operation expiry when the provider sends it.
 id: string;
 ```
 
-Defined in: [packages/ai/src/types.ts:2795](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2795)
+Defined in: [packages/ai/src/types.ts:2810](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2810)
 
 **`Experimental`**
 
@@ -70,7 +70,7 @@ Unique identifier for this generation
 model: string;
 ```
 
-Defined in: [packages/ai/src/types.ts:2797](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2797)
+Defined in: [packages/ai/src/types.ts:2812](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2812)
 
 **`Experimental`**
 
@@ -84,7 +84,7 @@ Model used for generation (provider connect slug or model id)
 optional operationId?: string;
 ```
 
-Defined in: [packages/ai/src/types.ts:2816](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2816)
+Defined in: [packages/ai/src/types.ts:2831](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2831)
 
 **`Experimental`**
 
@@ -98,7 +98,7 @@ Provider operation id for a long-running world job
 prompt: string;
 ```
 
-Defined in: [packages/ai/src/types.ts:2806](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2806)
+Defined in: [packages/ai/src/types.ts:2821](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2821)
 
 **`Experimental`**
 
@@ -112,7 +112,7 @@ Prompt used to generate the world, or the prompt the client should send
 optional sessionId?: string;
 ```
 
-Defined in: [packages/ai/src/types.ts:2810](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2810)
+Defined in: [packages/ai/src/types.ts:2825](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2825)
 
 **`Experimental`**
 
@@ -126,7 +126,7 @@ Provider session id, when the adapter created one
 status: "ready" | "waiting";
 ```
 
-Defined in: [packages/ai/src/types.ts:2808](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2808)
+Defined in: [packages/ai/src/types.ts:2823](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2823)
 
 **`Experimental`**
 
@@ -140,7 +140,7 @@ Status after the server half finishes
 optional token?: string;
 ```
 
-Defined in: [packages/ai/src/types.ts:2799](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2799)
+Defined in: [packages/ai/src/types.ts:2814](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2814)
 
 **`Experimental`**
 
@@ -154,7 +154,7 @@ Short-lived session token for a live client connection
 optional url?: string;
 ```
 
-Defined in: [packages/ai/src/types.ts:2812](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2812)
+Defined in: [packages/ai/src/types.ts:2827](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2827)
 
 **`Experimental`**
 
@@ -168,7 +168,7 @@ Viewer URL for a finished world job (not an asset download URL)
 optional usage?: TokenUsage<ProviderUsageDetails>;
 ```
 
-Defined in: [packages/ai/src/types.ts:2820](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2820)
+Defined in: [packages/ai/src/types.ts:2835](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2835)
 
 **`Experimental`**
 
@@ -182,7 +182,7 @@ Token usage / billing, when the adapter can report it
 optional worldId?: string;
 ```
 
-Defined in: [packages/ai/src/types.ts:2814](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2814)
+Defined in: [packages/ai/src/types.ts:2829](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2829)
 
 **`Experimental`**
 
diff --git a/docs/reference/type-aliases/AGUIEvent.md b/docs/reference/type-aliases/AGUIEvent.md
index c1febccdbf..9a7f24214f 100644
--- a/docs/reference/type-aliases/AGUIEvent.md
+++ b/docs/reference/type-aliases/AGUIEvent.md
@@ -38,6 +38,6 @@ type AGUIEvent =
   | SubagentErrorEvent;
 ```
 
-Defined in: [packages/ai/src/types.ts:2114](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2114)
+Defined in: [packages/ai/src/types.ts:2129](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2129)
 
 Union of all AG-UI events.
diff --git a/docs/reference/type-aliases/AgentLoopStrategy.md b/docs/reference/type-aliases/AgentLoopStrategy.md
index 2c91c14895..3edad36e91 100644
--- a/docs/reference/type-aliases/AgentLoopStrategy.md
+++ b/docs/reference/type-aliases/AgentLoopStrategy.md
@@ -7,7 +7,7 @@ title: AgentLoopStrategy
 type AgentLoopStrategy = (state) => boolean;
 ```
 
-Defined in: [packages/ai/src/types.ts:1283](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1283)
+Defined in: [packages/ai/src/types.ts:1298](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1298)
 
 Strategy function that determines whether the agent loop should continue
 
diff --git a/docs/reference/type-aliases/AnyTool.md b/docs/reference/type-aliases/AnyTool.md
index 1f62f9335a..08da00afd9 100644
--- a/docs/reference/type-aliases/AnyTool.md
+++ b/docs/reference/type-aliases/AnyTool.md
@@ -7,7 +7,7 @@ title: AnyTool
 type AnyTool = Omit<Tool<any, any, any, any>, "execute"> & object;
 ```
 
-Defined in: [packages/ai/src/types.ts:1145](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1145)
+Defined in: [packages/ai/src/types.ts:1160](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1160)
 
 ## Type Declaration
 
diff --git a/docs/reference/type-aliases/ChatStream.md b/docs/reference/type-aliases/ChatStream.md
index 3efdf8f978..ce3e861a97 100644
--- a/docs/reference/type-aliases/ChatStream.md
+++ b/docs/reference/type-aliases/ChatStream.md
@@ -9,7 +9,7 @@ type ChatStream = AsyncIterable<
 | KnownCustomEvent>;
 ```
 
-Defined in: [packages/ai/src/types.ts:1984](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1984)
+Defined in: [packages/ai/src/types.ts:1999](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1999)
 
 The default chat streaming result: standard chunks plus every typed
  framework CUSTOM event, with the `value: any` catch-all excluded so
diff --git a/docs/reference/type-aliases/ConstrainedModelMessage.md b/docs/reference/type-aliases/ConstrainedModelMessage.md
index 4c284c356d..a1dd83730e 100644
--- a/docs/reference/type-aliases/ConstrainedModelMessage.md
+++ b/docs/reference/type-aliases/ConstrainedModelMessage.md
@@ -7,7 +7,7 @@ title: ConstrainedModelMessage
 type ConstrainedModelMessage<TInputModalitiesTypes> = Omit<ModelMessage, "content"> & object;
 ```
 
-Defined in: [packages/ai/src/types.ts:828](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L828)
+Defined in: [packages/ai/src/types.ts:843](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L843)
 
 A ModelMessage with content constrained to only allow content parts
 matching the specified input modalities.
diff --git a/docs/reference/type-aliases/EmbeddingContentParts.md b/docs/reference/type-aliases/EmbeddingContentParts.md
index db08f83caa..1a5688b37a 100644
--- a/docs/reference/type-aliases/EmbeddingContentParts.md
+++ b/docs/reference/type-aliases/EmbeddingContentParts.md
@@ -9,7 +9,7 @@ type EmbeddingContentParts = (
   | ImagePart)[];
 ```
 
-Defined in: [packages/ai/src/types.ts:3320](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L3320)
+Defined in: [packages/ai/src/types.ts:3335](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L3335)
 
 A fused multi-part embedding item: all parts are embedded together into a
 single vector (e.g. a product photo plus its caption). Written as a nested
diff --git a/docs/reference/type-aliases/EmbeddingInputItem.md b/docs/reference/type-aliases/EmbeddingInputItem.md
index 44076d85ea..b7ee6f3d44 100644
--- a/docs/reference/type-aliases/EmbeddingInputItem.md
+++ b/docs/reference/type-aliases/EmbeddingInputItem.md
@@ -11,7 +11,7 @@ type EmbeddingInputItem =
   | EmbeddingContentParts;
 ```
 
-Defined in: [packages/ai/src/types.ts:3329](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L3329)
+Defined in: [packages/ai/src/types.ts:3344](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L3344)
 
 One embeddable item, producing exactly one vector. A bare string is
 shorthand for a text part; a nested [EmbeddingContentParts](EmbeddingContentParts.md) array
diff --git a/docs/reference/type-aliases/EmbeddingInputItemFor.md b/docs/reference/type-aliases/EmbeddingInputItemFor.md
index 2bc6b2a5ec..b9a145f50f 100644
--- a/docs/reference/type-aliases/EmbeddingInputItemFor.md
+++ b/docs/reference/type-aliases/EmbeddingInputItemFor.md
@@ -10,7 +10,7 @@ type EmbeddingInputItemFor<TModalities> =
   | EmbeddingItemByModality[TModalities];
 ```
 
-Defined in: [packages/ai/src/types.ts:3349](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L3349)
+Defined in: [packages/ai/src/types.ts:3364](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L3364)
 
 Embedding item type narrowed to the modalities a specific model supports.
 `EmbeddingInputItemFor<'text'>` (a text-only model) is `string | TextPart`;
diff --git a/docs/reference/type-aliases/EmbeddingModality.md b/docs/reference/type-aliases/EmbeddingModality.md
index 1851a9ff3e..0e33e97592 100644
--- a/docs/reference/type-aliases/EmbeddingModality.md
+++ b/docs/reference/type-aliases/EmbeddingModality.md
@@ -7,7 +7,7 @@ title: EmbeddingModality
 type EmbeddingModality = "text" | "image";
 ```
 
-Defined in: [packages/ai/src/types.ts:3299](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L3299)
+Defined in: [packages/ai/src/types.ts:3314](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L3314)
 
 Input modalities an embedding model can accept. Unlike
 [MediaPromptModality](MediaPromptModality.md), `'text'` is listed explicitly because
diff --git a/docs/reference/type-aliases/EmbeddingModelInputModalitiesByName.md b/docs/reference/type-aliases/EmbeddingModelInputModalitiesByName.md
index 8031d9a6d5..4890d1f97e 100644
--- a/docs/reference/type-aliases/EmbeddingModelInputModalitiesByName.md
+++ b/docs/reference/type-aliases/EmbeddingModelInputModalitiesByName.md
@@ -7,7 +7,7 @@ title: EmbeddingModelInputModalitiesByName
 type EmbeddingModelInputModalitiesByName = Record<string, ReadonlyArray<EmbeddingModality>>;
 ```
 
-Defined in: [packages/ai/src/types.ts:3306](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L3306)
+Defined in: [packages/ai/src/types.ts:3321](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L3321)
 
 Per-model map from model name to the input modalities it accepts, used as
 an adapter type parameter (`TModelInputModalitiesByName`). Models absent
diff --git a/docs/reference/type-aliases/FetchWrapper.md b/docs/reference/type-aliases/FetchWrapper.md
index 80f5d50856..fc8c3749db 100644
--- a/docs/reference/type-aliases/FetchWrapper.md
+++ b/docs/reference/type-aliases/FetchWrapper.md
@@ -7,7 +7,7 @@ title: FetchWrapper
 type FetchWrapper = (next) => typeof fetch;
 ```
 
-Defined in: [packages/ai/src/types.ts:1327](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1327)
+Defined in: [packages/ai/src/types.ts:1342](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1342)
 
 Wraps the fetch of a model call. It gets the next fetch and gives back a
 new fetch. A wrapper can change the URL, the headers, the request, or the
diff --git a/docs/reference/type-aliases/GeneratedAudio.md b/docs/reference/type-aliases/GeneratedAudio.md
index 472f3a485a..daff01de59 100644
--- a/docs/reference/type-aliases/GeneratedAudio.md
+++ b/docs/reference/type-aliases/GeneratedAudio.md
@@ -7,7 +7,7 @@ title: GeneratedAudio
 type GeneratedAudio = GeneratedMediaSource & object;
 ```
 
-Defined in: [packages/ai/src/types.ts:2577](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2577)
+Defined in: [packages/ai/src/types.ts:2592](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2592)
 
 A single generated audio output
 
diff --git a/docs/reference/type-aliases/GeneratedImage.md b/docs/reference/type-aliases/GeneratedImage.md
index d92bfce1fd..a448a4947c 100644
--- a/docs/reference/type-aliases/GeneratedImage.md
+++ b/docs/reference/type-aliases/GeneratedImage.md
@@ -7,7 +7,7 @@ title: GeneratedImage
 type GeneratedImage = GeneratedMediaSource & object;
 ```
 
-Defined in: [packages/ai/src/types.ts:2520](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2520)
+Defined in: [packages/ai/src/types.ts:2535](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2535)
 
 A single generated image
 
diff --git a/docs/reference/type-aliases/GeneratedMediaSource.md b/docs/reference/type-aliases/GeneratedMediaSource.md
index c49a52f634..47ac9d5abb 100644
--- a/docs/reference/type-aliases/GeneratedMediaSource.md
+++ b/docs/reference/type-aliases/GeneratedMediaSource.md
@@ -15,7 +15,7 @@ type GeneratedMediaSource =
 };
 ```
 
-Defined in: [packages/ai/src/types.ts:2461](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2461)
+Defined in: [packages/ai/src/types.ts:2476](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2476)
 
 Source of a generated media asset. Exactly one of `url` or `b64Json` is
 present; the other is absent. Modeled as a mutually-exclusive union so the
diff --git a/docs/reference/type-aliases/InputModalitiesTypes.md b/docs/reference/type-aliases/InputModalitiesTypes.md
index 286cb0815e..80d8ca4c76 100644
--- a/docs/reference/type-aliases/InputModalitiesTypes.md
+++ b/docs/reference/type-aliases/InputModalitiesTypes.md
@@ -7,7 +7,7 @@ title: InputModalitiesTypes
 type InputModalitiesTypes = object;
 ```
 
-Defined in: [packages/ai/src/types.ts:819](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L819)
+Defined in: [packages/ai/src/types.ts:834](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L834)
 
 ## Properties
 
@@ -17,7 +17,7 @@ Defined in: [packages/ai/src/types.ts:819](https://github.com/TanStack/ai/blob/m
 inputModalities: ReadonlyArray<Modality>;
 ```
 
-Defined in: [packages/ai/src/types.ts:820](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L820)
+Defined in: [packages/ai/src/types.ts:835](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L835)
 
 ***
 
@@ -27,4 +27,4 @@ Defined in: [packages/ai/src/types.ts:820](https://github.com/TanStack/ai/blob/m
 messageMetadataByModality: DefaultMessageMetadataByModality;
 ```
 
-Defined in: [packages/ai/src/types.ts:821](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L821)
+Defined in: [packages/ai/src/types.ts:836](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L836)
diff --git a/docs/reference/type-aliases/Interrupt.md b/docs/reference/type-aliases/Interrupt.md
index 5dffaf3245..fb7e29639b 100644
--- a/docs/reference/type-aliases/Interrupt.md
+++ b/docs/reference/type-aliases/Interrupt.md
@@ -7,4 +7,4 @@ title: Interrupt
 type Interrupt = AGUIInterrupt;
 ```
 
-Defined in: [packages/ai/src/types.ts:1625](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1625)
+Defined in: [packages/ai/src/types.ts:1640](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1640)
diff --git a/docs/reference/type-aliases/KnownCustomEvent.md b/docs/reference/type-aliases/KnownCustomEvent.md
index 584360ac1c..3d232f251a 100644
--- a/docs/reference/type-aliases/KnownCustomEvent.md
+++ b/docs/reference/type-aliases/KnownCustomEvent.md
@@ -26,7 +26,7 @@ type KnownCustomEvent =
   | UIResourceEvent;
 ```
 
-Defined in: [packages/ai/src/types.ts:1959](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1959)
+Defined in: [packages/ai/src/types.ts:1974](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1974)
 
 Every CUSTOM event TanStack AI itself emits, as a discriminated union on
 `name`. User-emitted custom events (via `emitCustomEvent` with a custom name)
diff --git a/docs/reference/type-aliases/MediaInputRole.md b/docs/reference/type-aliases/MediaInputRole.md
index 5146f834ff..452c3762cc 100644
--- a/docs/reference/type-aliases/MediaInputRole.md
+++ b/docs/reference/type-aliases/MediaInputRole.md
@@ -13,7 +13,7 @@ type MediaInputRole =
   | "character";
 ```
 
-Defined in: [packages/ai/src/types.ts:2330](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2330)
+Defined in: [packages/ai/src/types.ts:2345](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2345)
 
 Optional role hint on a media input part (image / video / audio). Adapters
 read `metadata.role` to route the part to the provider-specific request
diff --git a/docs/reference/type-aliases/MediaPrompt.md b/docs/reference/type-aliases/MediaPrompt.md
index c86b816438..0980d6e54e 100644
--- a/docs/reference/type-aliases/MediaPrompt.md
+++ b/docs/reference/type-aliases/MediaPrompt.md
@@ -7,7 +7,7 @@ title: MediaPrompt
 type MediaPrompt = string | MediaPromptPart[];
 ```
 
-Defined in: [packages/ai/src/types.ts:2381](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2381)
+Defined in: [packages/ai/src/types.ts:2396](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2396)
 
 Prompt accepted by `generateImage()` / `generateVideo()`: a plain string,
 or an ordered array of content parts for image-conditioned generation
diff --git a/docs/reference/type-aliases/MediaPromptFor.md b/docs/reference/type-aliases/MediaPromptFor.md
index 7b5229aa12..ecd33895ad 100644
--- a/docs/reference/type-aliases/MediaPromptFor.md
+++ b/docs/reference/type-aliases/MediaPromptFor.md
@@ -11,7 +11,7 @@ type MediaPromptFor<TModalities> =
   | MediaPartByModality[TModalities])[];
 ```
 
-Defined in: [packages/ai/src/types.ts:2402](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2402)
+Defined in: [packages/ai/src/types.ts:2417](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2417)
 
 Prompt type narrowed to the modalities a specific model supports.
 `MediaPromptFor<never>` (a text-only model) is `string | Array<TextPart>`;
diff --git a/docs/reference/type-aliases/MediaPromptModality.md b/docs/reference/type-aliases/MediaPromptModality.md
index 5e348b99d2..415ce6bd71 100644
--- a/docs/reference/type-aliases/MediaPromptModality.md
+++ b/docs/reference/type-aliases/MediaPromptModality.md
@@ -7,6 +7,6 @@ title: MediaPromptModality
 type MediaPromptModality = "image" | "video" | "audio";
 ```
 
-Defined in: [packages/ai/src/types.ts:2386](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2386)
+Defined in: [packages/ai/src/types.ts:2401](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2401)
 
 Non-text modalities a media-generation model can accept in its prompt.
diff --git a/docs/reference/type-aliases/MediaPromptPart.md b/docs/reference/type-aliases/MediaPromptPart.md
index 5061baefeb..9e19fb51ae 100644
--- a/docs/reference/type-aliases/MediaPromptPart.md
+++ b/docs/reference/type-aliases/MediaPromptPart.md
@@ -11,7 +11,7 @@ type MediaPromptPart =
 | AudioPart<MediaInputMetadata>;
 ```
 
-Defined in: [packages/ai/src/types.ts:2363](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2363)
+Defined in: [packages/ai/src/types.ts:2378](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2378)
 
 A single part of a multimodal media-generation prompt. Reuses the chat
 content-part shapes: text parts carry the instruction, image / video /
diff --git a/docs/reference/type-aliases/ModelInputModalitiesByName.md b/docs/reference/type-aliases/ModelInputModalitiesByName.md
index 90b803398b..2eaca69807 100644
--- a/docs/reference/type-aliases/ModelInputModalitiesByName.md
+++ b/docs/reference/type-aliases/ModelInputModalitiesByName.md
@@ -7,7 +7,7 @@ title: ModelInputModalitiesByName
 type ModelInputModalitiesByName = Record<string, ReadonlyArray<MediaPromptModality>>;
 ```
 
-Defined in: [packages/ai/src/types.ts:2411](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2411)
+Defined in: [packages/ai/src/types.ts:2426](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2426)
 
 Per-model map from model name to the prompt modalities it accepts, used as
 an adapter type parameter (`TModelInputModalitiesByName`). Models absent
diff --git a/docs/reference/type-aliases/PersistedArtifactActivity.md b/docs/reference/type-aliases/PersistedArtifactActivity.md
index de6b445856..5f997324c7 100644
--- a/docs/reference/type-aliases/PersistedArtifactActivity.md
+++ b/docs/reference/type-aliases/PersistedArtifactActivity.md
@@ -7,4 +7,4 @@ title: PersistedArtifactActivity
 type PersistedArtifactActivity = "image" | "audio" | "tts" | "video" | "transcription";
 ```
 
-Defined in: [packages/ai/src/types.ts:2475](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2475)
+Defined in: [packages/ai/src/types.ts:2490](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2490)
diff --git a/docs/reference/type-aliases/PersistedArtifactRole.md b/docs/reference/type-aliases/PersistedArtifactRole.md
index ebf41a6aa5..b573e9ae6f 100644
--- a/docs/reference/type-aliases/PersistedArtifactRole.md
+++ b/docs/reference/type-aliases/PersistedArtifactRole.md
@@ -7,4 +7,4 @@ title: PersistedArtifactRole
 type PersistedArtifactRole = "input" | "output";
 ```
 
-Defined in: [packages/ai/src/types.ts:2473](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2473)
+Defined in: [packages/ai/src/types.ts:2488](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2488)
diff --git a/docs/reference/type-aliases/PromptCacheOptions.md b/docs/reference/type-aliases/PromptCacheOptions.md
index 8ffe26b41b..0f50856fda 100644
--- a/docs/reference/type-aliases/PromptCacheOptions.md
+++ b/docs/reference/type-aliases/PromptCacheOptions.md
@@ -12,7 +12,7 @@ type PromptCacheOptions =
 };
 ```
 
-Defined in: [packages/ai/src/types.ts:1312](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1312)
+Defined in: [packages/ai/src/types.ts:1327](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1327)
 
 The `promptCache` option of `chat()`: a retention, or an object with a
 retention and a cache key.
diff --git a/docs/reference/type-aliases/PromptCacheRetention.md b/docs/reference/type-aliases/PromptCacheRetention.md
index 7cf737651c..844349da03 100644
--- a/docs/reference/type-aliases/PromptCacheRetention.md
+++ b/docs/reference/type-aliases/PromptCacheRetention.md
@@ -7,7 +7,7 @@ title: PromptCacheRetention
 type PromptCacheRetention = "none" | "short" | "long";
 ```
 
-Defined in: [packages/ai/src/types.ts:1306](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1306)
+Defined in: [packages/ai/src/types.ts:1321](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1321)
 
 How long the provider keeps the cached start of a request.
 `'none'` turns automatic prompt caching off.
diff --git a/docs/reference/type-aliases/RunAgentResumeItem.md b/docs/reference/type-aliases/RunAgentResumeItem.md
index b5a8ba23ca..c0132b2e44 100644
--- a/docs/reference/type-aliases/RunAgentResumeItem.md
+++ b/docs/reference/type-aliases/RunAgentResumeItem.md
@@ -7,7 +7,7 @@ title: RunAgentResumeItem
 type RunAgentResumeItem = AGUIResumeEntry & object;
 ```
 
-Defined in: [packages/ai/src/types.ts:1629](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1629)
+Defined in: [packages/ai/src/types.ts:1644](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1644)
 
 ## Type Declaration
 
diff --git a/docs/reference/type-aliases/RunFinishedOutcome.md b/docs/reference/type-aliases/RunFinishedOutcome.md
index ccf1b92f51..2fb9a63898 100644
--- a/docs/reference/type-aliases/RunFinishedOutcome.md
+++ b/docs/reference/type-aliases/RunFinishedOutcome.md
@@ -7,4 +7,4 @@ title: RunFinishedOutcome
 type RunFinishedOutcome = AGUIRunFinishedOutcome;
 ```
 
-Defined in: [packages/ai/src/types.ts:1627](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1627)
+Defined in: [packages/ai/src/types.ts:1642](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1642)
diff --git a/docs/reference/type-aliases/StreamChunk.md b/docs/reference/type-aliases/StreamChunk.md
index b8a81a176b..4f623700c7 100644
--- a/docs/reference/type-aliases/StreamChunk.md
+++ b/docs/reference/type-aliases/StreamChunk.md
@@ -7,7 +7,7 @@ title: StreamChunk
 type StreamChunk = AGUIEvent;
 ```
 
-Defined in: [packages/ai/src/types.ts:2174](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2174)
+Defined in: [packages/ai/src/types.ts:2189](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2189)
 
 Chunk returned by the SDK during streaming chat completions.
 Uses the AG-UI protocol event format.
diff --git a/docs/reference/type-aliases/StructuredOutputStream.md b/docs/reference/type-aliases/StructuredOutputStream.md
index 1920bef713..530b83db3e 100644
--- a/docs/reference/type-aliases/StructuredOutputStream.md
+++ b/docs/reference/type-aliases/StructuredOutputStream.md
@@ -10,7 +10,7 @@ type StructuredOutputStream<T> = AsyncIterable<
 | StructuredOutputCompleteEvent<T>>;
 ```
 
-Defined in: [packages/ai/src/types.ts:2017](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2017)
+Defined in: [packages/ai/src/types.ts:2032](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2032)
 
 Public type for streams returned by `chat({ outputSchema, stream: true })`.
 
diff --git a/docs/reference/type-aliases/TaggedCustomEvent.md b/docs/reference/type-aliases/TaggedCustomEvent.md
index fea32f7c76..579f0cdd21 100644
--- a/docs/reference/type-aliases/TaggedCustomEvent.md
+++ b/docs/reference/type-aliases/TaggedCustomEvent.md
@@ -9,7 +9,7 @@ type TaggedCustomEvent<T> =
 | StructuredOutputCompleteEvent<T>;
 ```
 
-Defined in: [packages/ai/src/types.ts:2199](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2199)
+Defined in: [packages/ai/src/types.ts:2214](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L2214)
 
 Discriminated union of the orchestrator-tagged `CUSTOM` events. Each variant
 has a literal `name`, so a single narrow on `chunk.name` yields a typed
diff --git a/docs/reference/type-aliases/ToolChoice.md b/docs/reference/type-aliases/ToolChoice.md
index 5aff39f4fe..4a7764f904 100644
--- a/docs/reference/type-aliases/ToolChoice.md
+++ b/docs/reference/type-aliases/ToolChoice.md
@@ -14,7 +14,7 @@ type ToolChoice<TName> =
 };
 ```
 
-Defined in: [packages/ai/src/types.ts:1295](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1295)
+Defined in: [packages/ai/src/types.ts:1310](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1310)
 
 How the model uses the tools of a call.
 - `'auto'`: the model decides.
diff --git a/docs/reference/type-aliases/ToolExecuteFunction.md b/docs/reference/type-aliases/ToolExecuteFunction.md
index 53c9ef6f72..f7ce4755f7 100644
--- a/docs/reference/type-aliases/ToolExecuteFunction.md
+++ b/docs/reference/type-aliases/ToolExecuteFunction.md
@@ -11,7 +11,7 @@ type ToolExecuteFunction<TInput, TOutput, TContext> = undefined extends TContext
 | InferSchemaType<TOutput>;
 ```
 
-Defined in: [packages/ai/src/types.ts:978](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L978)
+Defined in: [packages/ai/src/types.ts:993](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L993)
 
 ## Type Parameters
 
diff --git a/docs/reference/type-aliases/ToolExecutionContext.md b/docs/reference/type-aliases/ToolExecutionContext.md
index 7b3d3ff8da..a1362f0003 100644
--- a/docs/reference/type-aliases/ToolExecutionContext.md
+++ b/docs/reference/type-aliases/ToolExecutionContext.md
@@ -7,7 +7,7 @@ title: ToolExecutionContext
 type ToolExecutionContext<TContext> = RuntimeContextField<TContext> & object;
 ```
 
-Defined in: [packages/ai/src/types.ts:890](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L890)
+Defined in: [packages/ai/src/types.ts:905](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L905)
 
 Context passed to tool execute functions, providing capabilities like
 emitting custom events during execution.
diff --git a/docs/reference/type-aliases/ToolInputResponse.md b/docs/reference/type-aliases/ToolInputResponse.md
index 7e57260cfd..7ae5b3f780 100644
--- a/docs/reference/type-aliases/ToolInputResponse.md
+++ b/docs/reference/type-aliases/ToolInputResponse.md
@@ -14,7 +14,7 @@ type ToolInputResponse =
 };
 ```
 
-Defined in: [packages/ai/src/types.ts:882](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L882)
+Defined in: [packages/ai/src/types.ts:897](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L897)
 
 The user's answer to an `mcp_input` interrupt.
 `resolved` carries the `payload` from `resolveInterrupt`.
diff --git a/docs/reference/type-aliases/TranscriptionResponseFormat.md b/docs/reference/type-aliases/TranscriptionResponseFormat.md
index 943853d088..68962846a4 100644
--- a/docs/reference/type-aliases/TranscriptionResponseFormat.md
+++ b/docs/reference/type-aliases/TranscriptionResponseFormat.md
@@ -7,7 +7,7 @@ title: TranscriptionResponseFormat
 type TranscriptionResponseFormat = "json" | "text" | "srt" | "verbose_json" | "vtt";
 ```
 
-Defined in: [packages/ai/src/types.ts:3199](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L3199)
+Defined in: [packages/ai/src/types.ts:3214](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L3214)
 
 Options for audio transcription.
 These are the common options supported across providers.
diff --git a/docs/reference/type-aliases/VoiceOrigin.md b/docs/reference/type-aliases/VoiceOrigin.md
index d68b563dac..2e5a334ca5 100644
--- a/docs/reference/type-aliases/VoiceOrigin.md
+++ b/docs/reference/type-aliases/VoiceOrigin.md
@@ -7,7 +7,7 @@ title: VoiceOrigin
 type VoiceOrigin = "premade" | "generated" | "cloned" | "professional";
 ```
 
-Defined in: [packages/ai/src/types.ts:3034](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L3034)
+Defined in: [packages/ai/src/types.ts:3049](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L3049)
 
 Where a voice in a provider's catalog came from.
 
diff --git a/docs/reference/type-aliases/VoiceTrainingStatus.md b/docs/reference/type-aliases/VoiceTrainingStatus.md
index 00fb291fbf..be89914d06 100644
--- a/docs/reference/type-aliases/VoiceTrainingStatus.md
+++ b/docs/reference/type-aliases/VoiceTrainingStatus.md
@@ -7,7 +7,7 @@ title: VoiceTrainingStatus
 type VoiceTrainingStatus = "ready" | "training" | "failed";
 ```
 
-Defined in: [packages/ai/src/types.ts:3168](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L3168)
+Defined in: [packages/ai/src/types.ts:3183](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L3183)
 
 Whether a created voice is usable.