@openrouter/sdk 0.3.14 → 0.3.16

package/esm/lib/model-result.js

@@ -1,20 +1,34 @@
 import { ToolEventBroadcaster } from './tool-event-broadcaster.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 { buildResponsesMessageStream, buildToolCallStream, consumeStreamForCompletion, extractReasoningDeltas, extractResponsesMessageFromResponse, extractTextDeltas, extractTextFromResponse, extractToolCallsFromResponse, extractToolDeltas, } 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 { isStopConditionMet } from './stop-conditions.js';
+import { isStopConditionMet, stepCountIs } from './stop-conditions.js';
+/**
+ * Default maximum number of tool execution steps if no stopWhen is specified.
+ * This prevents infinite loops in tool execution.
+ */
+const DEFAULT_MAX_STEPS = 5;
 /**
  * Type guard for stream event with toReadableStream method
+ * Checks constructor name, prototype, and method availability
  */
 function isEventStream(value) {
-    return (value !== null &&
-        typeof value === 'object' &&
-        'toReadableStream' in value &&
-        typeof value.toReadableStream === 'function');
+    if (value === null || typeof value !== 'object') {
+        return false;
+    }
+    // Check constructor name for EventStream
+    const constructorName = Object.getPrototypeOf(value)?.constructor?.name;
+    if (constructorName === 'EventStream') {
+        return true;
+    }
+    // Fallback: check for toReadableStream method (may be on prototype)
+    const maybeStream = value;
+    return typeof maybeStream.toReadableStream === 'function';
 }
 /**
  * Type guard for output items with a type property
@@ -47,7 +61,6 @@ function hasTypeProperty(item) {
 export class ModelResult {
     constructor(options) {
         this.reusableStream = null;
-        this.streamPromise = null;
         this.textPromise = null;
         this.initPromise = null;
         this.toolExecutionPromise = null;
@@ -56,11 +69,31 @@ export class ModelResult {
         this.allToolExecutionRounds = [];
         // Track resolved request after async function resolution
         this.resolvedRequest = null;
+        // State management for multi-turn conversations
+        this.stateAccessor = null;
+        this.currentState = null;
+        this.requireApprovalFn = null;
+        this.approvedToolCalls = [];
+        this.rejectedToolCalls = [];
+        this.isResumingFromApproval = false;
         this.options = options;
+        // Runtime validation: approval decisions require state
+        const hasApprovalDecisions = (options.approveToolCalls && options.approveToolCalls.length > 0) ||
+            (options.rejectToolCalls && options.rejectToolCalls.length > 0);
+        if (hasApprovalDecisions && !options.state) {
+            throw new Error('approveToolCalls and rejectToolCalls require a state accessor. ' +
+                'Provide a StateAccessor via the "state" parameter to persist approval decisions.');
+        }
+        // Initialize state management
+        this.stateAccessor = options.state ?? null;
+        this.requireApprovalFn = options.requireApproval ?? null;
+        this.approvedToolCalls = options.approveToolCalls ?? [];
+        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.
      */
     ensureBroadcaster() {
         if (!this.toolEventBroadcaster) {
@@ -70,15 +103,389 @@ export class ModelResult {
     }
     /**
      * Type guard to check if a value is a non-streaming response
+     * Only requires 'output' field and absence of 'toReadableStream' method
      */
     isNonStreamingResponse(value) {
         return (value !== null &&
             typeof value === 'object' &&
-            'id' in value &&
-            'object' in value &&
             'output' in value &&
             !('toReadableStream' in value));
     }
+    // =========================================================================
+    // Extracted Helper Methods for executeToolsIfNeeded
+    // =========================================================================
+    /**
+     * Get initial response from stream or cached final response.
+     * Consumes the stream to completion if needed to extract the response.
+     *
+     * @returns The complete non-streaming response
+     * @throws Error if neither stream nor response has been initialized
+     */
+    async getInitialResponse() {
+        if (this.finalResponse) {
+            return this.finalResponse;
+        }
+        if (this.reusableStream) {
+            return consumeStreamForCompletion(this.reusableStream);
+        }
+        throw new Error('Neither stream nor response initialized');
+    }
+    /**
+     * Save response output to state.
+     * Appends the response output to the message history and records the response ID.
+     *
+     * @param response - The API response to save
+     */
+    async saveResponseToState(response) {
+        if (!this.stateAccessor || !this.currentState)
+            return;
+        const outputItems = Array.isArray(response.output)
+            ? response.output
+            : [response.output];
+        await this.saveStateSafely({
+            messages: appendToMessages(this.currentState.messages, outputItems),
+            previousResponseId: response.id,
+        });
+    }
+    /**
+     * Mark state as complete.
+     * Sets the conversation status to 'complete' indicating no further tool execution is needed.
+     */
+    async markStateComplete() {
+        await this.saveStateSafely({ status: 'complete' });
+    }
+    /**
+     * Save tool results to state.
+     * Appends tool execution results to the message history for multi-turn context.
+     *
+     * @param toolResults - The tool execution results to save
+     */
+    async saveToolResultsToState(toolResults) {
+        if (!this.currentState)
+            return;
+        await this.saveStateSafely({
+            messages: appendToMessages(this.currentState.messages, toolResults),
+        });
+    }
+    /**
+     * Check if execution should be interrupted by external signal.
+     * Polls the state accessor for interruption flags set by external processes.
+     *
+     * @param currentResponse - The current response to save as partial state
+     * @returns True if interrupted and caller should exit, false to continue
+     */
+    async checkForInterruption(currentResponse) {
+        if (!this.stateAccessor)
+            return false;
+        const freshState = await this.stateAccessor.load();
+        if (!freshState?.interruptedBy)
+            return false;
+        // Save partial state
+        if (this.currentState) {
+            const currentToolCalls = extractToolCallsFromResponse(currentResponse);
+            await this.saveStateSafely({
+                status: 'interrupted',
+                partialResponse: {
+                    text: extractTextFromResponseState(currentResponse),
+                    toolCalls: currentToolCalls,
+                },
+            });
+        }
+        this.finalResponse = currentResponse;
+        return true;
+    }
+    /**
+     * Check if stop conditions are met.
+     * Returns true if execution should stop.
+     *
+     * @remarks
+     * Default: stepCountIs(DEFAULT_MAX_STEPS) if no stopWhen is specified.
+     * This evaluates stop conditions against the complete step history.
+     */
+    async shouldStopExecution() {
+        const stopWhen = this.options.stopWhen ?? stepCountIs(DEFAULT_MAX_STEPS);
+        const stopConditions = Array.isArray(stopWhen)
+            ? stopWhen
+            : [stopWhen];
+        return isStopConditionMet({
+            stopConditions,
+            steps: this.allToolExecutionRounds.map((round) => ({
+                stepType: 'continue',
+                text: extractTextFromResponse(round.response),
+                toolCalls: round.toolCalls,
+                toolResults: round.toolResults.map((tr) => ({
+                    toolCallId: tr.callId,
+                    toolName: round.toolCalls.find((tc) => tc.id === tr.callId)?.name ?? '',
+                    result: JSON.parse(tr.output),
+                })),
+                response: round.response,
+                usage: round.response.usage,
+                finishReason: undefined,
+            })),
+        });
+    }
+    /**
+     * Check if any tool calls have execute functions.
+     * Used to determine if automatic tool execution should be attempted.
+     *
+     * @param toolCalls - The tool calls to check
+     * @returns True if at least one tool call has an executable function
+     */
+    hasExecutableToolCalls(toolCalls) {
+        return toolCalls.some((toolCall) => {
+            const tool = this.options.tools?.find((t) => t.function.name === toolCall.name);
+            return tool && hasExecuteFunction(tool);
+        });
+    }
+    /**
+     * Execute tools that can auto-execute (don't require approval).
+     * Processes tool calls that are approved for automatic execution.
+     *
+     * @param toolCalls - The tool calls to execute
+     * @param turnContext - The current turn context
+     * @returns Array of unsent tool results for later submission
+     */
+    async executeAutoApproveTools(toolCalls, turnContext) {
+        const results = [];
+        for (const tc of toolCalls) {
+            const tool = this.options.tools?.find(t => t.function.name === tc.name);
+            if (!tool || !hasExecuteFunction(tool))
+                continue;
+            const result = await executeTool(tool, tc, turnContext);
+            if (result.error) {
+                results.push(createRejectedResult(tc.id, String(tc.name), result.error.message));
+            }
+            else {
+                results.push(createUnsentResult(tc.id, String(tc.name), result.result));
+            }
+        }
+        return results;
+    }
+    /**
+     * Check for tools requiring approval and handle accordingly.
+     * Partitions tool calls into those needing approval and those that can auto-execute.
+     *
+     * @param toolCalls - The tool calls to check
+     * @param currentRound - The current execution round (1-indexed)
+     * @param currentResponse - The current response to save if pausing
+     * @returns True if execution should pause for approval, false to continue
+     * @throws Error if approval is required but no state accessor is configured
+     */
+    async handleApprovalCheck(toolCalls, currentRound, currentResponse) {
+        if (!this.options.tools)
+            return false;
+        const turnContext = { numberOfTurns: currentRound };
+        const { requiresApproval: needsApproval, autoExecute } = await partitionToolCalls(toolCalls, this.options.tools, turnContext, this.requireApprovalFn ?? undefined);
+        if (needsApproval.length === 0)
+            return false;
+        // Validate: approval requires state accessor
+        if (!this.stateAccessor) {
+            const toolNames = needsApproval.map(tc => tc.name).join(', ');
+            throw new Error(`Tool(s) require approval but no state accessor is configured: ${toolNames}. ` +
+                'Provide a StateAccessor via the "state" parameter to enable approval workflows.');
+        }
+        // Execute auto-approve tools
+        const unsentResults = await this.executeAutoApproveTools(autoExecute, turnContext);
+        // Save state with pending approvals
+        const stateUpdates = {
+            pendingToolCalls: needsApproval,
+            status: 'awaiting_approval',
+        };
+        if (unsentResults.length > 0) {
+            stateUpdates.unsentToolResults = unsentResults;
+        }
+        await this.saveStateSafely(stateUpdates);
+        this.finalResponse = currentResponse;
+        return true; // Pause for approval
+    }
+    /**
+     * Execute all tools in a single round.
+     * Runs each tool call sequentially and collects results for API submission.
+     * Emits tool.result events after each tool execution completes.
+     *
+     * @param toolCalls - The tool calls to execute
+     * @param turnContext - The current turn context
+     * @returns Array of function call outputs formatted for the API
+     */
+    async executeToolRound(toolCalls, turnContext) {
+        const toolResults = [];
+        for (const toolCall of toolCalls) {
+            const tool = this.options.tools?.find((t) => t.function.name === toolCall.name);
+            if (!tool || !hasExecuteFunction(tool))
+                continue;
+            // Track preliminary results for this specific tool call
+            const preliminaryResultsForCall = [];
+            // Create callback for real-time preliminary results
+            const onPreliminaryResult = this.toolEventBroadcaster
+                ? (callId, resultValue) => {
+                    // Track preliminary results for the tool.result event
+                    const typedResult = resultValue;
+                    preliminaryResultsForCall.push(typedResult);
+                    // Emit preliminary result event
+                    this.toolEventBroadcaster?.push({
+                        type: 'preliminary_result',
+                        toolCallId: callId,
+                        result: typedResult,
+                    });
+                }
+                : undefined;
+            const result = await executeTool(tool, toolCall, turnContext, onPreliminaryResult);
+            // Emit tool.result event with final result and any preliminary results
+            if (this.toolEventBroadcaster) {
+                const toolResultEvent = {
+                    type: 'tool_result',
+                    toolCallId: toolCall.id,
+                    result: (result.error ? { error: result.error.message } : result.result),
+                    ...(preliminaryResultsForCall.length > 0 && { preliminaryResults: preliminaryResultsForCall }),
+                };
+                this.toolEventBroadcaster.push(toolResultEvent);
+            }
+            toolResults.push({
+                type: 'function_call_output',
+                id: `output_${toolCall.id}`,
+                callId: toolCall.id,
+                output: result.error
+                    ? JSON.stringify({ error: result.error.message })
+                    : JSON.stringify(result.result),
+            });
+        }
+        return toolResults;
+    }
+    /**
+     * Resolve async functions for the current turn.
+     * Updates the resolved request with turn-specific parameter values.
+     *
+     * @param turnContext - The turn context for parameter resolution
+     */
+    async resolveAsyncFunctionsForTurn(turnContext) {
+        if (hasAsyncFunctions(this.options.request)) {
+            const resolved = await resolveAsyncFunctions(this.options.request, turnContext);
+            this.resolvedRequest = { ...resolved, stream: false };
+        }
+    }
+    /**
+     * Apply nextTurnParams from executed tools.
+     * Allows tools to modify request parameters for subsequent turns.
+     *
+     * @param toolCalls - The tool calls that were just executed
+     */
+    async applyNextTurnParams(toolCalls) {
+        if (!this.options.tools || toolCalls.length === 0 || !this.resolvedRequest) {
+            return;
+        }
+        const computedParams = await executeNextTurnParamsFunctions(toolCalls, this.options.tools, this.resolvedRequest);
+        if (Object.keys(computedParams).length > 0) {
+            this.resolvedRequest = applyNextTurnParamsToRequest(this.resolvedRequest, computedParams);
+        }
+    }
+    /**
+     * 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
+     */
+    async makeFollowupRequest(currentResponse, toolResults) {
+        // Build new input with tool results
+        const newInput = [
+            ...(Array.isArray(currentResponse.output)
+                ? currentResponse.output
+                : [currentResponse.output]),
+            ...toolResults,
+        ];
+        if (!this.resolvedRequest) {
+            throw new Error('Request not initialized');
+        }
+        const newRequest = {
+            ...this.resolvedRequest,
+            input: newInput,
+            stream: false,
+        };
+        const newResult = await betaResponsesSend(this.options.client, 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);
+        }
+        else if (this.isNonStreamingResponse(value)) {
+            return value;
+        }
+        else {
+            throw new Error('Unexpected response type from API');
+        }
+    }
+    /**
+     * Validate the final response has required fields.
+     *
+     * @param response - The response to validate
+     * @throws Error if response is missing required fields or has invalid output
+     */
+    validateFinalResponse(response) {
+        if (!response?.id || !response?.output) {
+            throw new Error('Invalid final response: missing required fields');
+        }
+        if (!Array.isArray(response.output) || response.output.length === 0) {
+            throw new Error('Invalid final response: empty or invalid output');
+        }
+    }
+    /**
+     * Resolve async functions in the request for a given turn context.
+     * Extracts non-function fields and resolves any async parameter functions.
+     *
+     * @param context - The turn context for parameter resolution
+     * @returns The resolved request without async functions
+     */
+    async resolveRequestForContext(context) {
+        if (hasAsyncFunctions(this.options.request)) {
+            return resolveAsyncFunctions(this.options.request, context);
+        }
+        // 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;
+        return rest;
+    }
+    /**
+     * Safely persist state with error handling.
+     * Wraps state save operations to ensure failures are properly reported.
+     *
+     * @param updates - Optional partial state updates to apply before saving
+     * @throws Error if state persistence fails
+     */
+    async saveStateSafely(updates) {
+        if (!this.stateAccessor || !this.currentState)
+            return;
+        if (updates) {
+            this.currentState = updateState(this.currentState, updates);
+        }
+        try {
+            await this.stateAccessor.save(this.currentState);
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            throw new Error(`Failed to persist conversation state: ${message}`);
+        }
+    }
+    /**
+     * Remove optional properties from state when they should be cleared.
+     * Uses delete to properly remove optional properties rather than setting undefined.
+     *
+     * @param props - Array of property names to remove from current state
+     */
+    clearOptionalStateProperties(props) {
+        if (!this.currentState)
+            return;
+        for (const prop of props) {
+            delete this.currentState[prop];
+        }
+    }
+    // =========================================================================
+    // Core Methods
+    // =========================================================================
     /**
      * Initialize the stream if not already started
      * This is idempotent - multiple calls will return the same promise
@@ -88,23 +495,57 @@ export class ModelResult {
             return this.initPromise;
         }
         this.initPromise = (async () => {
+            // Load or create state if accessor provided
+            if (this.stateAccessor) {
+                const loadedState = await this.stateAccessor.load();
+                if (loadedState) {
+                    this.currentState = loadedState;
+                    // Check if we're resuming from awaiting_approval with decisions
+                    if (loadedState.status === 'awaiting_approval' &&
+                        (this.approvedToolCalls.length > 0 || this.rejectedToolCalls.length > 0)) {
+                        this.isResumingFromApproval = true;
+                        await this.processApprovalDecisions();
+                        return; // Skip normal initialization, we're resuming
+                    }
+                    // Check for interruption flag and handle
+                    if (loadedState.interruptedBy) {
+                        // Clear interruption flag and continue from saved state
+                        this.currentState = updateState(loadedState, { status: 'in_progress' });
+                        this.clearOptionalStateProperties(['interruptedBy']);
+                        await this.saveStateSafely();
+                    }
+                }
+                else {
+                    this.currentState = createInitialState();
+                }
+                // Update status to in_progress
+                await this.saveStateSafely({ status: 'in_progress' });
+            }
             // Resolve async functions before initial request
             // Build initial turn context (turn 0 for initial request)
             const initialContext = {
                 numberOfTurns: 0,
             };
             // Resolve any async functions first
-            let baseRequest;
-            if (hasAsyncFunctions(this.options.request)) {
-                baseRequest = await resolveAsyncFunctions(this.options.request, initialContext);
-            }
-            else {
-                // Already resolved, extract non-function fields
-                // Since request is CallModelInput, we need to filter out stopWhen
-                // Note: tools are already in API format at this point (converted in callModel())
-                const { stopWhen: _, ...rest } = this.options.request;
-                // Cast to ResolvedCallModelInput - we know it's resolved if hasAsyncFunctions returned false
-                baseRequest = rest;
+            let baseRequest = await this.resolveRequestForContext(initialContext);
+            // If we have state with existing messages, use those as input
+            if (this.currentState && this.currentState.messages &&
+                Array.isArray(this.currentState.messages) && this.currentState.messages.length > 0) {
+                // Append new input to existing messages
+                const newInput = baseRequest.input;
+                if (newInput) {
+                    const inputArray = Array.isArray(newInput) ? newInput : [newInput];
+                    baseRequest = {
+                        ...baseRequest,
+                        input: appendToMessages(this.currentState.messages, inputArray),
+                    };
+                }
+                else {
+                    baseRequest = {
+                        ...baseRequest,
+                        input: this.currentState.messages,
+                    };
+                }
             }
             // Store resolved request with stream mode
             this.resolvedRequest = {
@@ -113,22 +554,145 @@ export class ModelResult {
             };
             // Force stream mode for initial request
             const request = this.resolvedRequest;
-            // Create the stream promise
-            this.streamPromise = betaResponsesSend(this.options.client, request, this.options.options).then((result) => {
-                if (!result.ok) {
-                    throw result.error;
-                }
-                // When stream: true, the API returns EventStream
-                // TypeScript can't narrow the union type based on runtime parameter values,
-                // so we assert the type here based on our knowledge that stream=true
-                return result.value;
-            });
-            // Wait for the stream and create the reusable stream
-            const eventStream = await this.streamPromise;
-            this.reusableStream = new ReusableReadableStream(eventStream);
+            // Make the API request
+            const apiResult = await betaResponsesSend(this.options.client, request, this.options.options);
+            if (!apiResult.ok) {
+                throw apiResult.error;
+            }
+            // Handle both streaming and non-streaming responses
+            // The API may return a non-streaming response even when stream: true is requested
+            if (isEventStream(apiResult.value)) {
+                this.reusableStream = new ReusableReadableStream(apiResult.value);
+            }
+            else if (this.isNonStreamingResponse(apiResult.value)) {
+                // API returned a complete response directly - use it as the final response
+                this.finalResponse = apiResult.value;
+            }
+            else {
+                throw new Error('Unexpected response type from API');
+            }
         })();
         return this.initPromise;
     }
+    /**
+     * Process approval/rejection decisions and resume execution
+     */
+    async processApprovalDecisions() {
+        if (!this.currentState || !this.stateAccessor) {
+            throw new Error('Cannot process approval decisions without state');
+        }
+        const pendingCalls = this.currentState.pendingToolCalls ?? [];
+        const unsentResults = [...(this.currentState.unsentToolResults ?? [])];
+        // Build turn context - numberOfTurns represents the current turn (1-indexed after initial)
+        const turnContext = {
+            numberOfTurns: this.allToolExecutionRounds.length + 1,
+        };
+        // Process approvals - execute the approved tools
+        for (const callId of this.approvedToolCalls) {
+            const toolCall = pendingCalls.find(tc => tc.id === callId);
+            if (!toolCall)
+                continue;
+            const tool = this.options.tools?.find(t => t.function.name === toolCall.name);
+            if (!tool || !hasExecuteFunction(tool)) {
+                // Can't execute, create error result
+                unsentResults.push(createRejectedResult(callId, String(toolCall.name), 'Tool not found or not executable'));
+                continue;
+            }
+            const result = await executeTool(tool, toolCall, turnContext);
+            if (result.error) {
+                unsentResults.push(createRejectedResult(callId, String(toolCall.name), result.error.message));
+            }
+            else {
+                unsentResults.push(createUnsentResult(callId, String(toolCall.name), result.result));
+            }
+        }
+        // Process rejections
+        for (const callId of this.rejectedToolCalls) {
+            const toolCall = pendingCalls.find(tc => tc.id === callId);
+            if (!toolCall)
+                continue;
+            unsentResults.push(createRejectedResult(callId, String(toolCall.name), 'Rejected by user'));
+        }
+        // Remove processed calls from pending
+        const processedIds = new Set([...this.approvedToolCalls, ...this.rejectedToolCalls]);
+        const remainingPending = pendingCalls.filter(tc => !processedIds.has(tc.id));
+        // Update state - conditionally include optional properties only if they have values
+        const stateUpdates = {
+            status: remainingPending.length > 0 ? 'awaiting_approval' : 'in_progress',
+        };
+        if (remainingPending.length > 0) {
+            stateUpdates.pendingToolCalls = remainingPending;
+        }
+        if (unsentResults.length > 0) {
+            stateUpdates.unsentToolResults = unsentResults;
+        }
+        await this.saveStateSafely(stateUpdates);
+        // Clear optional properties if they should be empty
+        const propsToClear = [];
+        if (remainingPending.length === 0)
+            propsToClear.push('pendingToolCalls');
+        if (unsentResults.length === 0)
+            propsToClear.push('unsentToolResults');
+        if (propsToClear.length > 0) {
+            this.clearOptionalStateProperties(propsToClear);
+            await this.saveStateSafely();
+        }
+        // If we still have pending approvals, stop here
+        if (remainingPending.length > 0) {
+            return;
+        }
+        // Otherwise, continue with tool execution using unsent results
+        await this.continueWithUnsentResults();
+    }
+    /**
+     * Continue execution with unsent tool results
+     */
+    async continueWithUnsentResults() {
+        if (!this.currentState || !this.stateAccessor)
+            return;
+        const unsentResults = this.currentState.unsentToolResults ?? [];
+        if (unsentResults.length === 0)
+            return;
+        // Convert to API format
+        const toolOutputs = unsentResultsToAPIFormat(unsentResults);
+        // Build new input with tool results
+        const currentMessages = this.currentState.messages;
+        const newInput = appendToMessages(currentMessages, toolOutputs);
+        // Clear unsent results from state
+        this.currentState = updateState(this.currentState, {
+            messages: newInput,
+        });
+        this.clearOptionalStateProperties(['unsentToolResults']);
+        await this.saveStateSafely();
+        // Build request with the updated input
+        // numberOfTurns represents the current turn number (1-indexed after initial)
+        const turnContext = {
+            numberOfTurns: this.allToolExecutionRounds.length + 1,
+        };
+        const baseRequest = await this.resolveRequestForContext(turnContext);
+        // Create request with the accumulated messages
+        const request = {
+            ...baseRequest,
+            input: newInput,
+            stream: true,
+        };
+        this.resolvedRequest = request;
+        // Make the API request
+        const apiResult = await betaResponsesSend(this.options.client, request, this.options.options);
+        if (!apiResult.ok) {
+            throw apiResult.error;
+        }
+        // Handle both streaming and non-streaming responses
+        if (isEventStream(apiResult.value)) {
+            this.reusableStream = new ReusableReadableStream(apiResult.value);
+        }
+        else if (this.isNonStreamingResponse(apiResult.value)) {
+            this.finalResponse = apiResult.value;
+        }
+        else {
+            throw new Error('Unexpected response type from API');
+        }
+    }
     /**
      * Execute tools automatically if they are provided and have execute functions
      * This is idempotent - multiple calls will return the same promise
@@ -139,179 +703,81 @@ export class ModelResult {
         }
         this.toolExecutionPromise = (async () => {
             await this.initStream();
-            if (!this.reusableStream) {
-                throw new Error('Stream not initialized');
+            // If resuming from approval and still pending, don't continue
+            if (this.isResumingFromApproval && this.currentState?.status === 'awaiting_approval') {
+                return;
             }
-            // Note: Async functions already resolved in initStream()
-            // Get the initial response
-            const initialResponse = await consumeStreamForCompletion(this.reusableStream);
-            // Check if we have tools and if auto-execution is enabled
-            const shouldAutoExecute = this.options.tools &&
-                this.options.tools.length > 0 &&
-                initialResponse.output.some((item) => hasTypeProperty(item) && item.type === 'function_call');
-            if (!shouldAutoExecute) {
-                // No tools to execute, use initial response
-                this.finalResponse = initialResponse;
+            // Get initial response
+            let currentResponse = await this.getInitialResponse();
+            // Save initial response to state
+            await this.saveResponseToState(currentResponse);
+            // Check if tools should be executed
+            const hasToolCalls = currentResponse.output.some((item) => hasTypeProperty(item) && item.type === 'function_call');
+            if (!this.options.tools?.length || !hasToolCalls) {
+                this.finalResponse = currentResponse;
+                await this.markStateComplete();
                 return;
             }
-            // Extract tool calls
-            const toolCalls = extractToolCallsFromResponse(initialResponse);
-            // Check if any have execute functions
-            const executableTools = toolCalls.filter((toolCall) => {
-                const tool = this.options.tools?.find((t) => t.function.name === toolCall.name);
-                return tool && hasExecuteFunction(tool);
-            });
-            if (executableTools.length === 0) {
-                // No executable tools, use initial response
-                this.finalResponse = initialResponse;
+            // Extract and check tool calls
+            const toolCalls = extractToolCallsFromResponse(currentResponse);
+            // Check for approval requirements
+            if (await this.handleApprovalCheck(toolCalls, 0, currentResponse)) {
+                return; // Paused for approval
+            }
+            if (!this.hasExecutableToolCalls(toolCalls)) {
+                this.finalResponse = currentResponse;
+                await this.markStateComplete();
                 return;
             }
-            let currentResponse = initialResponse;
+            // Main execution loop
             let currentRound = 0;
             while (true) {
-                // Check stopWhen conditions
-                if (this.options.stopWhen) {
-                    const stopConditions = Array.isArray(this.options.stopWhen)
-                        ? this.options.stopWhen
-                        : [this.options.stopWhen];
-                    const shouldStop = await isStopConditionMet({
-                        stopConditions,
-                        steps: this.allToolExecutionRounds.map((round) => ({
-                            stepType: 'continue',
-                            text: extractTextFromResponse(round.response),
-                            toolCalls: round.toolCalls,
-                            toolResults: round.toolResults.map((tr) => ({
-                                toolCallId: tr.callId,
-                                toolName: round.toolCalls.find((tc) => tc.id === tr.callId)?.name ?? '',
-                                result: JSON.parse(tr.output),
-                            })),
-                            response: round.response,
-                            usage: round.response.usage,
-                            finishReason: undefined, // OpenResponsesNonStreamingResponse doesn't have finishReason
-                        })),
-                    });
-                    if (shouldStop) {
-                        break;
-                    }
+                // Check for external interruption
+                if (await this.checkForInterruption(currentResponse)) {
+                    return;
+                }
+                // Check stop conditions
+                if (await this.shouldStopExecution()) {
+                    break;
                 }
                 const currentToolCalls = extractToolCallsFromResponse(currentResponse);
                 if (currentToolCalls.length === 0) {
                     break;
                 }
-                const hasExecutable = currentToolCalls.some((toolCall) => {
-                    const tool = this.options.tools?.find((t) => t.function.name === toolCall.name);
-                    return tool && hasExecuteFunction(tool);
-                });
-                if (!hasExecutable) {
+                // Check for approval requirements
+                if (await this.handleApprovalCheck(currentToolCalls, currentRound + 1, currentResponse)) {
+                    return;
+                }
+                if (!this.hasExecutableToolCalls(currentToolCalls)) {
                     break;
                 }
-                // Build turn context for this round (for async parameter resolution only)
-                const turnContext = {
-                    numberOfTurns: currentRound + 1, // 1-indexed
-                };
+                // Build turn context
+                const turnContext = { numberOfTurns: currentRound + 1 };
                 // Resolve async functions for this turn
-                if (hasAsyncFunctions(this.options.request)) {
-                    const resolved = await resolveAsyncFunctions(this.options.request, turnContext);
-                    // Update resolved request with new values
-                    this.resolvedRequest = {
-                        ...resolved,
-                        stream: false, // Tool execution turns don't need streaming
-                    };
-                }
-                // Execute all tool calls
-                const toolResults = [];
-                for (const toolCall of currentToolCalls) {
-                    const tool = this.options.tools?.find((t) => t.function.name === toolCall.name);
-                    if (!tool || !hasExecuteFunction(tool)) {
-                        continue;
-                    }
-                    // Create callback for real-time preliminary results
-                    const onPreliminaryResult = this.toolEventBroadcaster
-                        ? (callId, resultValue) => {
-                            this.toolEventBroadcaster?.push({
-                                type: 'preliminary_result',
-                                toolCallId: callId,
-                                result: resultValue,
-                            });
-                        }
-                        : undefined;
-                    const result = await executeTool(tool, toolCall, turnContext, onPreliminaryResult);
-                    toolResults.push({
-                        type: 'function_call_output',
-                        id: `output_${toolCall.id}`,
-                        callId: toolCall.id,
-                        output: result.error
-                            ? JSON.stringify({
-                                error: result.error.message,
-                            })
-                            : JSON.stringify(result.result),
-                    });
-                }
-                // Store execution round info including tool results
+                await this.resolveAsyncFunctionsForTurn(turnContext);
+                // Execute tools
+                const toolResults = await this.executeToolRound(currentToolCalls, turnContext);
+                // Track execution round
                 this.allToolExecutionRounds.push({
                     round: currentRound,
                     toolCalls: currentToolCalls,
                     response: currentResponse,
                     toolResults,
                 });
-                // Execute nextTurnParams functions for tools that were called
-                if (this.options.tools && currentToolCalls.length > 0) {
-                    if (!this.resolvedRequest) {
-                        throw new Error('Request not initialized');
-                    }
-                    const computedParams = await executeNextTurnParamsFunctions(currentToolCalls, this.options.tools, this.resolvedRequest);
-                    // Apply computed parameters to the resolved request for next turn
-                    if (Object.keys(computedParams).length > 0) {
-                        this.resolvedRequest = applyNextTurnParamsToRequest(this.resolvedRequest, computedParams);
-                    }
-                }
-                // Build new input with tool results
-                // For the Responses API, we need to include the tool results in the input
-                const newInput = [
-                    ...(Array.isArray(currentResponse.output)
-                        ? currentResponse.output
-                        : [
-                            currentResponse.output,
-                        ]),
-                    ...toolResults,
-                ];
-                // Make new request with tool results
-                if (!this.resolvedRequest) {
-                    throw new Error('Request not initialized');
-                }
-                const newRequest = {
-                    ...this.resolvedRequest,
-                    input: newInput,
-                    stream: false,
-                };
-                const newResult = await betaResponsesSend(this.options.client, newRequest, this.options.options);
-                if (!newResult.ok) {
-                    throw newResult.error;
-                }
-                // Handle the result - it might be a stream or a response
-                const value = newResult.value;
-                if (isEventStream(value)) {
-                    // It's a stream, consume it
-                    const stream = new ReusableReadableStream(value);
-                    currentResponse = await consumeStreamForCompletion(stream);
-                }
-                else if (this.isNonStreamingResponse(value)) {
-                    currentResponse = value;
-                }
-                else {
-                    throw new Error('Unexpected response type from API');
-                }
+                // Save tool results to state
+                await this.saveToolResultsToState(toolResults);
+                // Apply nextTurnParams
+                await this.applyNextTurnParams(currentToolCalls);
+                // Make follow-up request
+                currentResponse = await this.makeFollowupRequest(currentResponse, toolResults);
+                // Save new response to state
+                await this.saveResponseToState(currentResponse);
                 currentRound++;
             }
-            // Validate the final response has required fields
-            if (!currentResponse || !currentResponse.id || !currentResponse.output) {
-                throw new Error('Invalid final response: missing required fields');
-            }
-            // Ensure the response is in a completed state (has output content)
-            if (!Array.isArray(currentResponse.output) || currentResponse.output.length === 0) {
-                throw new Error('Invalid final response: empty or invalid output');
-            }
+            // Validate and finalize
+            this.validateFinalResponse(currentResponse);
             this.finalResponse = currentResponse;
+            await this.markStateComplete();
         })();
         return this.toolExecutionPromise;
     }
@@ -351,7 +817,7 @@ export class ModelResult {
     /**
      * Stream all response events as they arrive.
      * Multiple consumers can iterate over this stream concurrently.
-     * Preliminary tool results are streamed in REAL-TIME as generator tools yield.
+     * Preliminary tool results and tool results are streamed in REAL-TIME as generator tools yield.
      */
     getFullResponsesStream() {
         return async function* () {
@@ -371,14 +837,25 @@ export class ModelResult {
             for await (const event of consumer) {
                 yield event;
             }
-            // Yield tool preliminary results as they arrive (real-time!)
+            // Yield tool events as they arrive (real-time!)
             for await (const event of toolEventConsumer) {
-                yield {
-                    type: 'tool.preliminary_result',
-                    toolCallId: event.toolCallId,
-                    result: event.result,
-                    timestamp: Date.now(),
-                };
+                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;
@@ -468,9 +945,11 @@ export class ModelResult {
                     content: delta,
                 };
             }
-            // Yield tool events as they arrive (real-time!)
+            // Yield only preliminary_result events (filter out tool_result events)
             for await (const event of toolEventConsumer) {
-                yield event;
+                if (event.type === 'preliminary_result') {
+                    yield event;
+                }
             }
             // Ensure execution completed (handles errors)
             await executionPromise;
@@ -484,6 +963,10 @@ export class ModelResult {
      */
     async getToolCalls() {
         await this.initStream();
+        // Handle non-streaming response case - use finalResponse directly
+        if (this.finalResponse) {
+            return extractToolCallsFromResponse(this.finalResponse);
+        }
         if (!this.reusableStream) {
             throw new Error('Stream not initialized');
         }
@@ -511,5 +994,50 @@ export class ModelResult {
             await this.reusableStream.cancel();
         }
     }
+    // =========================================================================
+    // Multi-Turn Conversation State Methods
+    // =========================================================================
+    /**
+     * Check if the conversation requires human approval to continue.
+     * Returns true if there are pending tool calls awaiting approval.
+     */
+    async requiresApproval() {
+        await this.initStream();
+        // If we have pending tool calls in state, approval is required
+        if (this.currentState?.status === 'awaiting_approval') {
+            return true;
+        }
+        // Also check if pendingToolCalls is populated
+        return (this.currentState?.pendingToolCalls?.length ?? 0) > 0;
+    }
+    /**
+     * Get the pending tool calls that require approval.
+     * Returns empty array if no approvals needed.
+     */
+    async getPendingToolCalls() {
+        await this.initStream();
+        // Try to trigger tool execution to populate pending calls
+        if (!this.isResumingFromApproval) {
+            await this.executeToolsIfNeeded();
+        }
+        return (this.currentState?.pendingToolCalls ?? []);
+    }
+    /**
+     * Get the current conversation state.
+     * Useful for inspection, debugging, or custom persistence.
+     * Note: This returns the raw ConversationState for inspection only.
+     * To resume a conversation, use the StateAccessor pattern.
+     */
+    async getState() {
+        await this.initStream();
+        // Ensure tool execution has been attempted (to populate final state)
+        if (!this.isResumingFromApproval) {
+            await this.executeToolsIfNeeded();
+        }
+        if (!this.currentState) {
+            throw new Error('State not initialized. Make sure a StateAccessor was provided to callModel.');
+        }
+        return this.currentState;
+    }
 }
 //# sourceMappingURL=model-result.js.map