@openrouter/sdk 0.9.11 → 0.11.2

package/esm/lib/model-result.js

@@ -1,14 +1,15 @@
 import { ToolEventBroadcaster } from './tool-event-broadcaster.js';
+import { ToolContextStore, resolveContext } from './tool-context.js';
 import { betaResponsesSend } from '../funcs/betaResponsesSend.js';
 import { hasAsyncFunctions, resolveAsyncFunctions, } from './async-params.js';
 import { appendToMessages, createInitialState, createRejectedResult, createUnsentResult, extractTextFromResponse as extractTextFromResponseState, partitionToolCalls, unsentResultsToAPIFormat, updateState, } from './conversation-state.js';
 import { ReusableReadableStream } from './reusable-stream.js';
-import { buildItemsStream, buildResponsesMessageStream, buildToolCallStream, consumeStreamForCompletion, extractReasoningDeltas, extractResponsesMessageFromResponse, extractTextDeltas, extractTextFromResponse, extractToolCallsFromResponse, extractToolDeltas, } from './stream-transformers.js';
+import { buildItemsStream, buildResponsesMessageStream, buildToolCallStream, consumeStreamForCompletion, extractReasoningDeltas, extractResponsesMessageFromResponse, extractTextDeltas, extractTextFromResponse, extractToolCallsFromResponse, extractToolDeltas, itemsStreamHandlers, streamTerminationEvents, } from './stream-transformers.js';
 import { executeTool } from './tool-executor.js';
 import { executeNextTurnParamsFunctions, applyNextTurnParamsToRequest } from './next-turn-params.js';
-import { hasExecuteFunction } from './tool-types.js';
+import { hasExecuteFunction, isToolCallOutputEvent } from './tool-types.js';
 import { isStopConditionMet, stepCountIs } from './stop-conditions.js';
-import { isOutputMessage, isFunctionCallItem, isReasoningOutputItem, isWebSearchCallOutputItem, isFileSearchCallOutputItem, isImageGenerationCallOutputItem, hasTypeProperty, } from './stream-type-guards.js';
+import { isFunctionCallItem, isResponseCompletedEvent, isResponseFailedEvent, isResponseIncompleteEvent, isOutputTextDeltaEvent, isReasoningDeltaEvent, hasTypeProperty, } from './stream-type-guards.js';
 /**
  * Default maximum number of tool execution steps if no stopWhen is specified.
  * This prevents infinite loops in tool execution.
@@ -38,7 +39,7 @@ function isEventStream(value) {
  * - `await result.getText()` - Get just the text
  * - `await result.getResponse()` - Get the full response object
  * - `for await (const delta of result.getTextStream())` - Stream text deltas
- * - `for await (const msg of result.getNewMessagesStream())` - Stream incremental message updates
+ * - `for await (const msg of result.getNewMessagesStream())` - Stream cumulative message snapshots
  * - `for await (const event of result.getFullResponsesStream())` - Stream all response events
  *
  * For message format conversion, use the helper functions:
@@ -49,6 +50,7 @@ function isEventStream(value) {
  * ReusableReadableStream implementation.
  *
  * @template TTools - The tools array type to enable typed tool calls and results
+ * @template TShared - The shape of the shared context (inferred from sharedContextSchema)
  */
 export class ModelResult {
     constructor(options) {
@@ -68,6 +70,12 @@ export class ModelResult {
         this.approvedToolCalls = [];
         this.rejectedToolCalls = [];
         this.isResumingFromApproval = false;
+        // Unified turn broadcaster for multi-turn streaming
+        this.turnBroadcaster = null;
+        this.initialStreamPipeStarted = false;
+        this.initialPipePromise = null;
+        // Context store for typed tool context (persists across turns)
+        this.contextStore = null;
         this.options = options;
         // Runtime validation: approval decisions require state
         const hasApprovalDecisions = (options.approveToolCalls && options.approveToolCalls.length > 0) ||
@@ -83,15 +91,139 @@ export class ModelResult {
         this.rejectedToolCalls = options.rejectToolCalls ?? [];
     }
     /**
-     * Get or create the tool event broadcaster (lazy initialization).
-     * Ensures only one broadcaster exists for the lifetime of this ModelResult.
-     * Broadcasts both preliminary results and final tool results.
+     * Get or create the unified turn broadcaster (lazy initialization).
+     * Broadcasts all API stream events, tool events, and turn delimiters across turns.
      */
-    ensureBroadcaster() {
-        if (!this.toolEventBroadcaster) {
-            this.toolEventBroadcaster = new ToolEventBroadcaster();
+    ensureTurnBroadcaster() {
+        if (!this.turnBroadcaster) {
+            this.turnBroadcaster = new ToolEventBroadcaster();
         }
-        return this.toolEventBroadcaster;
+        return this.turnBroadcaster;
+    }
+    /**
+     * Start piping the initial stream into the turn broadcaster.
+     * Idempotent — only starts once even if called multiple times.
+     * Wraps the initial stream events with turn.start(0) / turn.end(0) delimiters.
+     */
+    startInitialStreamPipe() {
+        if (this.initialStreamPipeStarted)
+            return;
+        this.initialStreamPipeStarted = true;
+        const broadcaster = this.ensureTurnBroadcaster();
+        if (!this.reusableStream) {
+            return;
+        }
+        const stream = this.reusableStream;
+        this.initialPipePromise = (async () => {
+            broadcaster.push({
+                type: 'turn.start',
+                turnNumber: 0,
+                timestamp: Date.now(),
+            });
+            const consumer = stream.createConsumer();
+            for await (const event of consumer) {
+                broadcaster.push(event);
+            }
+            broadcaster.push({
+                type: 'turn.end',
+                turnNumber: 0,
+                timestamp: Date.now(),
+            });
+        })().catch((error) => {
+            broadcaster.complete(error instanceof Error ? error : new Error(String(error)));
+        });
+    }
+    /**
+     * Pipe a follow-up stream into the turn broadcaster and capture the completed response.
+     * Emits turn.start / turn.end delimiters around the stream events.
+     */
+    async pipeAndConsumeStream(stream, turnNumber) {
+        const broadcaster = this.turnBroadcaster;
+        broadcaster.push({
+            type: 'turn.start',
+            turnNumber,
+            timestamp: Date.now(),
+        });
+        const consumer = stream.createConsumer();
+        let completedResponse = null;
+        for await (const event of consumer) {
+            broadcaster.push(event);
+            if (isResponseCompletedEvent(event)) {
+                completedResponse = event.response;
+            }
+            if (isResponseFailedEvent(event)) {
+                const errorMsg = 'message' in event ? String(event.message) : 'Response failed';
+                throw new Error(errorMsg);
+            }
+            if (isResponseIncompleteEvent(event)) {
+                completedResponse = event.response;
+            }
+        }
+        broadcaster.push({
+            type: 'turn.end',
+            turnNumber,
+            timestamp: Date.now(),
+        });
+        if (!completedResponse) {
+            throw new Error('Follow-up stream ended without a completed response');
+        }
+        return completedResponse;
+    }
+    /**
+     * Push a tool result event to both the legacy tool event broadcaster
+     * and the unified turn broadcaster.
+     */
+    broadcastToolResult(toolCallId, result, preliminaryResults) {
+        this.toolEventBroadcaster?.push({
+            type: 'tool_result',
+            toolCallId,
+            result,
+            ...(preliminaryResults?.length && { preliminaryResults }),
+        });
+        this.turnBroadcaster?.push({
+            type: 'tool.result',
+            toolCallId,
+            result,
+            timestamp: Date.now(),
+            ...(preliminaryResults?.length && { preliminaryResults }),
+        });
+    }
+    /**
+     * Push a preliminary result event to both the legacy tool event broadcaster
+     * and the unified turn broadcaster.
+     */
+    broadcastPreliminaryResult(toolCallId, result) {
+        this.toolEventBroadcaster?.push({
+            type: 'preliminary_result',
+            toolCallId,
+            result,
+        });
+        this.turnBroadcaster?.push({
+            type: 'tool.preliminary_result',
+            toolCallId,
+            result,
+            timestamp: Date.now(),
+        });
+    }
+    /**
+     * Set up the turn broadcaster with tool execution and return the consumer.
+     * Used by stream methods that need to iterate over all turns.
+     */
+    startTurnBroadcasterExecution() {
+        const broadcaster = this.ensureTurnBroadcaster();
+        this.startInitialStreamPipe();
+        const consumer = broadcaster.createConsumer();
+        const executionPromise = this.executeToolsIfNeeded().finally(async () => {
+            // Wait for the initial stream pipe to finish pushing all events
+            // (including turn.end) before marking the broadcaster as complete.
+            // Without this, turn.end can be silently dropped if the pipe hasn't
+            // finished when executeToolsIfNeeded completes.
+            if (this.initialPipePromise) {
+                await this.initialPipePromise;
+            }
+            broadcaster.complete();
+        });
+        return { consumer, executionPromise };
     }
     /**
      * Type guard to check if a value is a non-streaming response
@@ -208,7 +340,7 @@ export class ModelResult {
                 toolResults: round.toolResults.map((tr) => ({
                     toolCallId: tr.callId,
                     toolName: round.toolCalls.find((tc) => tc.id === tr.callId)?.name ?? '',
-                    result: JSON.parse(tr.output),
+                    result: typeof tr.output === 'string' ? JSON.parse(tr.output) : tr.output,
                 })),
                 response: round.response,
                 usage: round.response.usage,
@@ -242,7 +374,7 @@ export class ModelResult {
             if (!tool || !hasExecuteFunction(tool)) {
                 return null;
             }
-            const result = await executeTool(tool, tc, turnContext);
+            const result = await executeTool(tool, tc, turnContext, undefined, this.contextStore ?? undefined, this.options.sharedContextSchema);
             if (result.error) {
                 return createRejectedResult(tc.id, String(tc.name), result.error.message);
             }
@@ -281,7 +413,10 @@ export class ModelResult {
     async handleApprovalCheck(toolCalls, currentRound, currentResponse) {
         if (!this.options.tools)
             return false;
-        const turnContext = { numberOfTurns: currentRound };
+        const turnContext = {
+            numberOfTurns: currentRound,
+            // context is handled via contextStore, not on TurnContext
+        };
         const { requiresApproval: needsApproval, autoExecute } = await partitionToolCalls(toolCalls, this.options.tools, turnContext, this.requireApprovalFn ?? undefined);
         if (needsApproval.length === 0)
             return false;
@@ -326,13 +461,7 @@ export class ModelResult {
                 const errorMessage = `Failed to parse tool call arguments for "${toolCall.name}": The model provided invalid JSON. ` +
                     `Raw arguments received: "${rawArgs}". ` +
                     `Please provide valid JSON arguments for this tool call.`;
-                if (this.toolEventBroadcaster) {
-                    this.toolEventBroadcaster.push({
-                        type: 'tool_result',
-                        toolCallId: toolCall.id,
-                        result: { error: errorMessage },
-                    });
-                }
+                this.broadcastToolResult(toolCall.id, { error: errorMessage });
                 return {
                     type: 'parse_error',
                     toolCall,
@@ -345,18 +474,15 @@ export class ModelResult {
                 };
             }
             const preliminaryResultsForCall = [];
-            const onPreliminaryResult = this.toolEventBroadcaster
+            const hasBroadcaster = this.toolEventBroadcaster || this.turnBroadcaster;
+            const onPreliminaryResult = hasBroadcaster
                 ? (callId, resultValue) => {
                     const typedResult = resultValue;
                     preliminaryResultsForCall.push(typedResult);
-                    this.toolEventBroadcaster?.push({
-                        type: 'preliminary_result',
-                        toolCallId: callId,
-                        result: typedResult,
-                    });
+                    this.broadcastPreliminaryResult(callId, typedResult);
                 }
                 : undefined;
-            const result = await executeTool(tool, toolCall, turnContext, onPreliminaryResult);
+            const result = await executeTool(tool, toolCall, turnContext, onPreliminaryResult, this.contextStore ?? undefined, this.options.sharedContextSchema);
             return {
                 type: 'execution',
                 toolCall,
@@ -376,18 +502,18 @@ export class ModelResult {
                 const errorMessage = settled.reason instanceof Error
                     ? settled.reason.message
                     : String(settled.reason);
-                if (this.toolEventBroadcaster) {
-                    this.toolEventBroadcaster.push({
-                        type: 'tool_result',
-                        toolCallId: originalToolCall.id,
-                        result: { error: errorMessage },
-                    });
-                }
-                toolResults.push({
+                this.broadcastToolResult(originalToolCall.id, { error: errorMessage });
+                const rejectedOutput = {
                     type: 'function_call_output',
                     id: `output_${originalToolCall.id}`,
                     callId: originalToolCall.id,
                     output: JSON.stringify({ error: errorMessage }),
+                };
+                toolResults.push(rejectedOutput);
+                this.turnBroadcaster?.push({
+                    type: 'tool.call_output',
+                    output: rejectedOutput,
+                    timestamp: Date.now(),
                 });
                 continue;
             }
@@ -396,27 +522,30 @@ export class ModelResult {
                 continue;
             if (value.type === 'parse_error') {
                 toolResults.push(value.output);
-                continue;
-            }
-            if (this.toolEventBroadcaster) {
-                this.toolEventBroadcaster.push({
-                    type: 'tool_result',
-                    toolCallId: value.toolCall.id,
-                    result: (value.result.error
-                        ? { error: value.result.error.message }
-                        : value.result.result),
-                    ...(value.preliminaryResultsForCall.length > 0 && {
-                        preliminaryResults: value.preliminaryResultsForCall,
-                    }),
+                this.turnBroadcaster?.push({
+                    type: 'tool.call_output',
+                    output: value.output,
+                    timestamp: Date.now(),
                 });
+                continue;
             }
-            toolResults.push({
+            const toolResult = (value.result.error
+                ? { error: value.result.error.message }
+                : value.result.result);
+            this.broadcastToolResult(value.toolCall.id, toolResult, value.preliminaryResultsForCall.length > 0 ? value.preliminaryResultsForCall : undefined);
+            const executedOutput = {
                 type: 'function_call_output',
                 id: `output_${value.toolCall.id}`,
                 callId: value.toolCall.id,
                 output: value.result.error
                     ? JSON.stringify({ error: value.result.error.message })
                     : JSON.stringify(value.result.result),
+            };
+            toolResults.push(executedOutput);
+            this.turnBroadcaster?.push({
+                type: 'tool.call_output',
+                output: executedOutput,
+                timestamp: Date.now(),
             });
         }
         return toolResults;
@@ -432,9 +561,10 @@ export class ModelResult {
             const resolved = await resolveAsyncFunctions(this.options.request, turnContext);
             // Preserve accumulated input from previous turns
             const preservedInput = this.resolvedRequest?.input;
+            const preservedStream = this.resolvedRequest?.stream;
             this.resolvedRequest = {
                 ...resolved,
-                stream: false,
+                stream: preservedStream ?? true,
                 ...(preservedInput !== undefined && { input: preservedInput }),
             };
         }
@@ -456,14 +586,9 @@ export class ModelResult {
     }
     /**
      * Make a follow-up API request with tool results.
-     * Continues the conversation after tool execution.
-     *
-     * @param currentResponse - The response that contained tool calls
-     * @param toolResults - The results from executing those tools
-     * @returns The new response from the API
+     * Uses streaming and pipes events through the turn broadcaster when available.
      */
-    async makeFollowupRequest(currentResponse, toolResults) {
-        // Build new input preserving original conversation + tool results
+    async makeFollowupRequest(currentResponse, toolResults, turnNumber) {
         const originalInput = this.resolvedRequest?.input;
         const normalizedOriginalInput = Array.isArray(originalInput)
             ? originalInput
@@ -487,17 +612,20 @@ export class ModelResult {
         };
         const newRequest = {
             ...this.resolvedRequest,
-            stream: false,
+            stream: true,
         };
-        const newResult = await betaResponsesSend(this.options.client, { openResponsesRequest: newRequest }, this.options.options);
+        const newResult = await betaResponsesSend(this.options.client, { responsesRequest: newRequest }, this.options.options);
         if (!newResult.ok) {
             throw newResult.error;
         }
         // Handle streaming or non-streaming response
         const value = newResult.value;
         if (isEventStream(value)) {
-            const stream = new ReusableReadableStream(value);
-            return consumeStreamForCompletion(stream);
+            const followUpStream = new ReusableReadableStream(value);
+            if (this.turnBroadcaster) {
+                return this.pipeAndConsumeStream(followUpStream, turnNumber);
+            }
+            return consumeStreamForCompletion(followUpStream);
         }
         else if (this.isNonStreamingResponse(value)) {
             return value;
@@ -533,7 +661,7 @@ export class ModelResult {
         }
         // Already resolved, extract non-function fields
         // Filter out stopWhen and state-related fields that aren't part of the API request
-        const { stopWhen: _, state: _s, requireApproval: _r, approveToolCalls: _a, rejectToolCalls: _rj, ...rest } = this.options.request;
+        const { stopWhen: _, state: _s, requireApproval: _r, approveToolCalls: _a, rejectToolCalls: _rj, context: _c, ...rest } = this.options.request;
         return rest;
     }
     /**
@@ -590,6 +718,12 @@ export class ModelResult {
                     // Check if we're resuming from awaiting_approval with decisions
                     if (loadedState.status === 'awaiting_approval' &&
                         (this.approvedToolCalls.length > 0 || this.rejectedToolCalls.length > 0)) {
+                        // Initialize context store before resuming so tools have access
+                        if (this.options.context !== undefined) {
+                            const approvalContext = { numberOfTurns: 0 };
+                            const resolvedCtx = await resolveContext(this.options.context, approvalContext);
+                            this.contextStore = new ToolContextStore(resolvedCtx);
+                        }
                         this.isResumingFromApproval = true;
                         await this.processApprovalDecisions();
                         return; // Skip normal initialization, we're resuming
@@ -610,9 +744,12 @@ export class ModelResult {
             }
             // Resolve async functions before initial request
             // Build initial turn context (turn 0 for initial request)
-            const initialContext = {
-                numberOfTurns: 0,
-            };
+            const initialContext = { numberOfTurns: 0 };
+            // Initialize context store from the context option
+            if (this.options.context !== undefined) {
+                const resolvedCtx = await resolveContext(this.options.context, initialContext);
+                this.contextStore = new ToolContextStore(resolvedCtx);
+            }
             // Resolve any async functions first
             let baseRequest = await this.resolveRequestForContext(initialContext);
             // If we have state with existing messages, use those as input
@@ -642,7 +779,7 @@ export class ModelResult {
             // Force stream mode for initial request
             const request = this.resolvedRequest;
             // Make the API request
-            const apiResult = await betaResponsesSend(this.options.client, { openResponsesRequest: request }, this.options.options);
+            const apiResult = await betaResponsesSend(this.options.client, { responsesRequest: request }, this.options.options);
             if (!apiResult.ok) {
                 throw apiResult.error;
             }
@@ -673,6 +810,7 @@ export class ModelResult {
         // Build turn context - numberOfTurns represents the current turn (1-indexed after initial)
         const turnContext = {
             numberOfTurns: this.allToolExecutionRounds.length + 1,
+            // context is handled via contextStore, not on TurnContext
         };
         // Process approvals - execute the approved tools
         for (const callId of this.approvedToolCalls) {
@@ -685,7 +823,7 @@ export class ModelResult {
                 unsentResults.push(createRejectedResult(callId, String(toolCall.name), 'Tool not found or not executable'));
                 continue;
             }
-            const result = await executeTool(tool, toolCall, turnContext);
+            const result = await executeTool(tool, toolCall, turnContext, undefined, this.contextStore ?? undefined, this.options.sharedContextSchema);
             if (result.error) {
                 unsentResults.push(createRejectedResult(callId, String(toolCall.name), result.error.message));
             }
@@ -765,7 +903,7 @@ export class ModelResult {
         };
         this.resolvedRequest = request;
         // Make the API request
-        const apiResult = await betaResponsesSend(this.options.client, { openResponsesRequest: request }, this.options.options);
+        const apiResult = await betaResponsesSend(this.options.client, { responsesRequest: request }, this.options.options);
         if (!apiResult.ok) {
             throw apiResult.error;
         }
@@ -839,7 +977,9 @@ export class ModelResult {
                     break;
                 }
                 // Build turn context
-                const turnContext = { numberOfTurns: currentRound + 1 };
+                const turnNumber = currentRound + 1;
+                const turnContext = { numberOfTurns: turnNumber };
+                await this.options.onTurnStart?.(turnContext);
                 // Resolve async functions for this turn
                 await this.resolveAsyncFunctionsForTurn(turnContext);
                 // Execute tools
@@ -855,8 +995,8 @@ export class ModelResult {
                 await this.saveToolResultsToState(toolResults);
                 // Apply nextTurnParams
                 await this.applyNextTurnParams(currentToolCalls);
-                // Make follow-up request
-                currentResponse = await this.makeFollowupRequest(currentResponse, toolResults);
+                currentResponse = await this.makeFollowupRequest(currentResponse, toolResults, turnNumber);
+                await this.options.onTurnEnd?.(turnContext, currentResponse);
                 // Save new response to state
                 await this.saveResponseToState(currentResponse);
                 currentRound++;
@@ -892,7 +1032,7 @@ export class ModelResult {
     /**
      * Get the complete response object including usage information.
      * This will consume the stream until completion and execute any tools.
-     * Returns the full OpenResponsesNonStreamingResponse with usage data (inputTokens, outputTokens, cachedTokens, etc.)
+     * Returns the full OpenResponsesResult with usage data (inputTokens, outputTokens, cachedTokens, etc.)
      */
     async getResponse() {
         await this.executeToolsIfNeeded();
@@ -902,63 +1042,56 @@ export class ModelResult {
         return this.finalResponse;
     }
     /**
-     * Stream all response events as they arrive.
+     * Stream all response events as they arrive across all turns.
      * Multiple consumers can iterate over this stream concurrently.
-     * Preliminary tool results and tool results are streamed in REAL-TIME as generator tools yield.
+     * Includes API events, tool events, and turn.start/turn.end delimiters.
      */
     getFullResponsesStream() {
         return async function* () {
             await this.initStream();
-            if (!this.reusableStream) {
+            if (!this.reusableStream && !this.finalResponse) {
                 throw new Error('Stream not initialized');
             }
-            // Get or create broadcaster for real-time tool events (lazy init prevents race conditions)
-            const broadcaster = this.ensureBroadcaster();
-            const toolEventConsumer = broadcaster.createConsumer();
-            // Start tool execution in background (completes broadcaster when done)
-            const executionPromise = this.executeToolsIfNeeded().finally(() => {
-                broadcaster.complete();
-            });
-            const consumer = this.reusableStream.createConsumer();
-            // Yield original API events
+            if (!this.options.tools?.length) {
+                if (this.reusableStream) {
+                    const consumer = this.reusableStream.createConsumer();
+                    for await (const event of consumer) {
+                        yield event;
+                    }
+                }
+                return;
+            }
+            const { consumer, executionPromise } = this.startTurnBroadcasterExecution();
             for await (const event of consumer) {
                 yield event;
             }
-            // Yield tool events as they arrive (real-time!)
-            for await (const event of toolEventConsumer) {
-                if (event.type === 'preliminary_result') {
-                    yield {
-                        type: 'tool.preliminary_result',
-                        toolCallId: event.toolCallId,
-                        result: event.result,
-                        timestamp: Date.now(),
-                    };
-                }
-                else if (event.type === 'tool_result') {
-                    yield {
-                        type: 'tool.result',
-                        toolCallId: event.toolCallId,
-                        result: event.result,
-                        timestamp: Date.now(),
-                        ...(event.preliminaryResults && { preliminaryResults: event.preliminaryResults }),
-                    };
-                }
-            }
-            // Ensure execution completed (handles errors)
             await executionPromise;
         }.call(this);
     }
     /**
-     * Stream only text deltas as they arrive.
-     * This filters the full event stream to only yield text content.
+     * Stream only text deltas as they arrive from all turns.
+     * This filters the full event stream to only yield text content,
+     * including text from follow-up responses in multi-turn tool loops.
      */
     getTextStream() {
         return async function* () {
             await this.initStream();
-            if (!this.reusableStream) {
+            if (!this.reusableStream && !this.finalResponse) {
                 throw new Error('Stream not initialized');
             }
-            yield* extractTextDeltas(this.reusableStream);
+            if (!this.options.tools?.length) {
+                if (this.reusableStream) {
+                    yield* extractTextDeltas(this.reusableStream);
+                }
+                return;
+            }
+            const { consumer, executionPromise } = this.startTurnBroadcasterExecution();
+            for await (const event of consumer) {
+                if (isOutputTextDeltaEvent(event)) {
+                    yield event.delta;
+                }
+            }
+            await executionPromise;
         }.call(this);
     }
     /**
@@ -978,40 +1111,46 @@ export class ModelResult {
     getItemsStream() {
         return async function* () {
             await this.initStream();
-            if (!this.reusableStream) {
+            if (!this.reusableStream && !this.finalResponse) {
                 throw new Error('Stream not initialized');
             }
-            // Stream all items from the API response cumulatively
-            yield* buildItemsStream(this.reusableStream);
-            // Execute tools if needed
-            await this.executeToolsIfNeeded();
-            // Yield function calls and outputs for each tool round
-            for (const round of this.allToolExecutionRounds) {
-                // Round 0's function_calls already yielded via buildItemsStream
-                if (round.round > 0) {
-                    for (const item of round.response.output) {
-                        if (isFunctionCallItem(item)) {
-                            yield item;
-                        }
-                    }
-                }
-                for (const toolResult of round.toolResults) {
-                    yield toolResult;
+            // No tools — stream single turn directly (no broadcaster needed)
+            if (!this.options.tools?.length) {
+                if (this.reusableStream) {
+                    yield* buildItemsStream(this.reusableStream);
                 }
+                return;
             }
-            // If tools were executed, yield all items from the final response
-            if (this.finalResponse && this.allToolExecutionRounds.length > 0) {
-                for (const item of this.finalResponse.output) {
-                    if (isOutputMessage(item) ||
-                        isFunctionCallItem(item) ||
-                        isReasoningOutputItem(item) ||
-                        isWebSearchCallOutputItem(item) ||
-                        isFileSearchCallOutputItem(item) ||
-                        isImageGenerationCallOutputItem(item)) {
-                        yield item;
+            // Use turnBroadcaster (same pattern as getTextStream/getFullResponsesStream).
+            // executeToolsIfNeeded() drives tool execution in the background while we
+            // passively consume events from the broadcaster in real-time.
+            const { consumer, executionPromise } = this.startTurnBroadcasterExecution();
+            const itemsInProgress = new Map();
+            for await (const event of consumer) {
+                // Tool call outputs → yield directly as function_call_output items
+                if (isToolCallOutputEvent(event)) {
+                    yield event.output;
+                    continue;
+                }
+                // Stream termination → reset items map for next turn
+                if ('type' in event && streamTerminationEvents.has(event.type)) {
+                    itemsInProgress.clear();
+                }
+                // API stream events → dispatch through item handlers
+                // Cast is necessary: TypeScript cannot narrow a union via Record key lookup,
+                // but `event.type in itemsStreamHandlers` guarantees the event is an
+                // StreamEvents whose type matches a handler key.
+                if ('type' in event && event.type in itemsStreamHandlers) {
+                    const handler = itemsStreamHandlers[event.type];
+                    if (handler) {
+                        const result = handler(event, itemsInProgress);
+                        if (result) {
+                            yield result;
+                        }
                     }
                 }
             }
+            await executionPromise;
         }.call(this);
     }
     /**
@@ -1019,20 +1158,22 @@ export class ModelResult {
      * while `getItemsStream()` streams all output item types (messages, function_calls,
      * reasoning, etc.) with cumulative updates.
      *
-     * Stream incremental message updates as content is added in responses format.
+     * Stream cumulative message snapshots as content is added in responses format.
      * Each iteration yields an updated version of the message with new content.
-     * Also yields function_call items and OpenResponsesFunctionCallOutput after tool execution completes.
-     * Returns ResponsesOutputMessage, ResponsesOutputItemFunctionCall, or OpenResponsesFunctionCallOutput
+     * Also yields function_call items and FunctionCallOutputItem after tool execution completes.
+     * Returns OutputMessage, OutputFunctionCallItem, or FunctionCallOutputItem
      * compatible with OpenAI Responses API format.
      */
     getNewMessagesStream() {
         return async function* () {
             await this.initStream();
-            if (!this.reusableStream) {
+            if (!this.reusableStream && !this.finalResponse) {
                 throw new Error('Stream not initialized');
             }
             // First yield messages from the stream in responses format
-            yield* buildResponsesMessageStream(this.reusableStream);
+            if (this.reusableStream) {
+                yield* buildResponsesMessageStream(this.reusableStream);
+            }
             // Execute tools if needed
             await this.executeToolsIfNeeded();
             // Yield function calls and their outputs for each executed tool
@@ -1059,20 +1200,33 @@ export class ModelResult {
         }.call(this);
     }
     /**
-     * Stream only reasoning deltas as they arrive.
-     * This filters the full event stream to only yield reasoning content.
+     * Stream only reasoning deltas as they arrive from all turns.
+     * This filters the full event stream to only yield reasoning content,
+     * including reasoning from follow-up responses in multi-turn tool loops.
      */
     getReasoningStream() {
         return async function* () {
             await this.initStream();
-            if (!this.reusableStream) {
+            if (!this.reusableStream && !this.finalResponse) {
                 throw new Error('Stream not initialized');
             }
-            yield* extractReasoningDeltas(this.reusableStream);
+            if (!this.options.tools?.length) {
+                if (this.reusableStream) {
+                    yield* extractReasoningDeltas(this.reusableStream);
+                }
+                return;
+            }
+            const { consumer, executionPromise } = this.startTurnBroadcasterExecution();
+            for await (const event of consumer) {
+                if (isReasoningDeltaEvent(event)) {
+                    yield event.delta;
+                }
+            }
+            await executionPromise;
         }.call(this);
     }
     /**
-     * Stream tool call argument deltas and preliminary results.
+     * Stream tool call argument deltas and preliminary results from all turns.
      * Preliminary results are streamed in REAL-TIME as generator tools yield.
      * - Tool call argument deltas as { type: "delta", content: string }
      * - Preliminary results as { type: "preliminary_result", toolCallId, result }
@@ -1080,30 +1234,31 @@ export class ModelResult {
     getToolStream() {
         return async function* () {
             await this.initStream();
-            if (!this.reusableStream) {
+            if (!this.reusableStream && !this.finalResponse) {
                 throw new Error('Stream not initialized');
             }
-            // Get or create broadcaster for real-time tool events (lazy init prevents race conditions)
-            const broadcaster = this.ensureBroadcaster();
-            const toolEventConsumer = broadcaster.createConsumer();
-            // Start tool execution in background (completes broadcaster when done)
-            const executionPromise = this.executeToolsIfNeeded().finally(() => {
-                broadcaster.complete();
-            });
-            // Yield tool deltas from API stream
-            for await (const delta of extractToolDeltas(this.reusableStream)) {
-                yield {
-                    type: 'delta',
-                    content: delta,
-                };
+            if (!this.options.tools?.length) {
+                if (this.reusableStream) {
+                    for await (const delta of extractToolDeltas(this.reusableStream)) {
+                        yield { type: 'delta', content: delta };
+                    }
+                }
+                return;
             }
-            // Yield only preliminary_result events (filter out tool_result events)
-            for await (const event of toolEventConsumer) {
-                if (event.type === 'preliminary_result') {
-                    yield event;
+            const { consumer, executionPromise } = this.startTurnBroadcasterExecution();
+            for await (const event of consumer) {
+                if (event.type === 'response.function_call_arguments.delta') {
+                    yield { type: 'delta', content: event.delta };
+                    continue;
+                }
+                if (event.type === 'tool.preliminary_result') {
+                    yield {
+                        type: 'preliminary_result',
+                        toolCallId: event.toolCallId,
+                        result: event.result,
+                    };
                 }
             }
-            // Ensure execution completed (handles errors)
             await executionPromise;
         }.call(this);
     }
@@ -1132,12 +1287,76 @@ export class ModelResult {
     getToolCallsStream() {
         return async function* () {
             await this.initStream();
-            if (!this.reusableStream) {
+            if (!this.reusableStream && !this.finalResponse) {
                 throw new Error('Stream not initialized');
             }
-            yield* buildToolCallStream(this.reusableStream);
+            if (this.reusableStream) {
+                yield* buildToolCallStream(this.reusableStream);
+            }
         }.call(this);
     }
+    /**
+     * Returns an async iterable that emits a full context snapshot every time
+     * any tool calls ctx.update(). Can be consumed concurrently with getText(),
+     * getToolStream(), etc.
+     *
+     * @example
+     * ```typescript
+     * for await (const snapshot of result.getContextUpdates()) {
+     *   console.log('Context changed:', snapshot);
+     * }
+     * ```
+     */
+    async *getContextUpdates() {
+        // Ensure stream is initialized (which creates the context store)
+        await this.initStream();
+        if (!this.contextStore) {
+            return;
+        }
+        const store = this.contextStore;
+        const queue = [];
+        let resolve = null;
+        let done = false;
+        const unsubscribe = store.subscribe((snapshot) => {
+            queue.push(snapshot);
+            if (resolve) {
+                resolve();
+                resolve = null;
+            }
+        });
+        // Signal completion when tool execution finishes
+        this.executeToolsIfNeeded().then(() => {
+            done = true;
+            if (resolve) {
+                resolve();
+                resolve = null;
+            }
+        }, () => {
+            done = true;
+            if (resolve) {
+                resolve();
+                resolve = null;
+            }
+        });
+        try {
+            while (!done) {
+                if (queue.length > 0) {
+                    yield queue.shift();
+                }
+                else {
+                    // Wait for next update or completion
+                    await new Promise((r) => { resolve = r; });
+                }
+            }
+            // Drain any remaining queued snapshots
+            while (queue.length > 0) {
+                yield queue.shift();
+            }
+        }
+        finally {
+            unsubscribe();
+        }
+    }
     /**
      * Cancel the underlying stream and all consumers
      */