@openrouter/sdk 0.3.14 → 0.3.16

package/esm/lib/conversation-state.js

@@ -0,0 +1,207 @@
+import { normalizeInputToArray } from './turn-context.js';
+/**
+ * Type guard to verify an object is a valid UnsentToolResult
+ */
+function isValidUnsentToolResult(obj) {
+    if (typeof obj !== 'object' || obj === null)
+        return false;
+    const candidate = obj;
+    return (typeof candidate['callId'] === 'string' &&
+        typeof candidate['name'] === 'string' &&
+        'output' in candidate);
+}
+/**
+ * Type guard to verify an object is a valid ParsedToolCall
+ */
+function isValidParsedToolCall(obj) {
+    if (typeof obj !== 'object' || obj === null)
+        return false;
+    const candidate = obj;
+    return (typeof candidate['id'] === 'string' &&
+        typeof candidate['name'] === 'string' &&
+        'arguments' in candidate);
+}
+/**
+ * Generate a unique ID for a conversation
+ * Uses crypto.randomUUID if available, falls back to timestamp + random
+ */
+export function generateConversationId() {
+    if (typeof crypto !== 'undefined' && crypto.randomUUID) {
+        return `conv_${crypto.randomUUID()}`;
+    }
+    // Fallback for environments without crypto.randomUUID
+    return `conv_${Date.now()}_${Math.random().toString(36).substring(2, 15)}`;
+}
+/**
+ * Create an initial conversation state
+ * @param id - Optional custom ID, generates one if not provided
+ */
+export function createInitialState(id) {
+    const now = Date.now();
+    return {
+        id: id ?? generateConversationId(),
+        messages: [],
+        status: 'in_progress',
+        createdAt: now,
+        updatedAt: now,
+    };
+}
+/**
+ * Update a conversation state with new values
+ * Automatically updates the updatedAt timestamp
+ */
+export function updateState(state, updates) {
+    return {
+        ...state,
+        ...updates,
+        updatedAt: Date.now(),
+    };
+}
+/**
+ * Append new items to the message history
+ */
+export function appendToMessages(current, newItems) {
+    const currentArray = normalizeInputToArray(current);
+    return [...currentArray, ...newItems];
+}
+/**
+ * Check if a tool call requires approval
+ * @param toolCall - The tool call to check
+ * @param tools - Available tools
+ * @param context - Turn context for the approval check
+ * @param callLevelCheck - Optional call-level approval function (overrides tool-level), can be async
+ */
+export async function toolRequiresApproval(toolCall, tools, context, callLevelCheck) {
+    // Call-level check takes precedence
+    if (callLevelCheck) {
+        return callLevelCheck(toolCall, context);
+    }
+    // Fall back to tool-level setting
+    const tool = tools.find(t => t.function.name === toolCall.name);
+    if (!tool)
+        return false;
+    const requireApproval = tool.function.requireApproval;
+    // If it's a function, call it with the tool's arguments and context
+    if (typeof requireApproval === 'function') {
+        return requireApproval(toolCall.arguments, context);
+    }
+    // Otherwise treat as boolean
+    return requireApproval ?? false;
+}
+/**
+ * Partition tool calls into those requiring approval and those that can auto-execute
+ * @param toolCalls - Tool calls to partition
+ * @param tools - Available tools
+ * @param context - Turn context for the approval check
+ * @param callLevelCheck - Optional call-level approval function (overrides tool-level), can be async
+ */
+export async function partitionToolCalls(toolCalls, tools, context, callLevelCheck) {
+    const requiresApproval = [];
+    const autoExecute = [];
+    for (const tc of toolCalls) {
+        if (await toolRequiresApproval(tc, tools, context, callLevelCheck)) {
+            requiresApproval.push(tc);
+        }
+        else {
+            autoExecute.push(tc);
+        }
+    }
+    return { requiresApproval, autoExecute };
+}
+/**
+ * Create an unsent tool result from a successful execution
+ */
+export function createUnsentResult(callId, name, output) {
+    const result = { callId, name, output };
+    if (!isValidUnsentToolResult(result)) {
+        throw new Error('Invalid UnsentToolResult structure');
+    }
+    return result;
+}
+/**
+ * Create an unsent tool result from a rejection
+ */
+export function createRejectedResult(callId, name, reason) {
+    const result = {
+        callId,
+        name,
+        output: null,
+        error: reason ?? 'Tool call rejected by user',
+    };
+    if (!isValidUnsentToolResult(result)) {
+        throw new Error('Invalid UnsentToolResult structure');
+    }
+    return result;
+}
+/**
+ * Convert unsent tool results to API format for sending to the model
+ */
+export function unsentResultsToAPIFormat(results) {
+    return results.map(r => ({
+        type: 'function_call_output',
+        id: `output_${r.callId}`,
+        callId: r.callId,
+        output: r.error
+            ? JSON.stringify({ error: r.error })
+            : JSON.stringify(r.output),
+    }));
+}
+/**
+ * Extract text content from a response
+ */
+export function extractTextFromResponse(response) {
+    if (!response.output) {
+        return '';
+    }
+    const outputs = Array.isArray(response.output) ? response.output : [response.output];
+    const textParts = [];
+    for (const item of outputs) {
+        if (item.type === 'message' && item.content) {
+            for (const content of item.content) {
+                if (content.type === 'output_text' && content.text) {
+                    textParts.push(content.text);
+                }
+            }
+        }
+    }
+    return textParts.join('');
+}
+/**
+ * Extract tool calls from a response
+ */
+export function extractToolCallsFromResponse(response) {
+    if (!response.output) {
+        return [];
+    }
+    const outputs = Array.isArray(response.output) ? response.output : [response.output];
+    const toolCalls = [];
+    for (const item of outputs) {
+        if (item.type === 'function_call') {
+            let parsedArguments;
+            if (typeof item.arguments === 'string') {
+                try {
+                    parsedArguments = JSON.parse(item.arguments);
+                }
+                catch (error) {
+                    // Log warning and skip malformed tool call, similar to stream-transformers.ts
+                    console.warn(`Failed to parse arguments for tool call "${item.name}": ${error instanceof Error ? error.message : String(error)}`);
+                    continue;
+                }
+            }
+            else {
+                parsedArguments = item.arguments;
+            }
+            const toolCall = {
+                id: item.callId ?? item.id ?? '',
+                name: item.name ?? '',
+                arguments: parsedArguments,
+            };
+            if (!isValidParsedToolCall(toolCall)) {
+                throw new Error(`Invalid tool call structure for tool: ${item.name}`);
+            }
+            toolCalls.push(toolCall);
+        }
+    }
+    return toolCalls;
+}
+//# sourceMappingURL=conversation-state.js.map

package/esm/lib/model-result.d.ts

@@ -2,13 +2,21 @@ import type { OpenRouterCore } from '../core.js';
 import type * as models from '../models/index.js';
 import type { CallModelInput } from './async-params.js';
 import type { RequestOptions } from './sdks.js';
-import type { ResponseStreamEvent, InferToolEventsUnion, ParsedToolCall, StopWhen, Tool, ToolStreamEvent } from './tool-types.js';
+import type { ConversationState, ResponseStreamEvent, InferToolEventsUnion, InferToolOutputsUnion, ParsedToolCall, StateAccessor, StopWhen, Tool, ToolStreamEvent, TurnContext } from './tool-types.js';
 export interface GetResponseOptions<TTools extends readonly Tool[]> {
     request: CallModelInput<TTools>;
     client: OpenRouterCore;
     options?: RequestOptions;
     tools?: TTools;
     stopWhen?: StopWhen<TTools>;
+    state?: StateAccessor<TTools>;
+    /**
+     * Call-level approval check - overrides tool-level requireApproval setting
+     * Receives the tool call and turn context, can be sync or async
+     */
+    requireApproval?: (toolCall: ParsedToolCall<TTools[number]>, context: TurnContext) => boolean | Promise<boolean>;
+    approveToolCalls?: string[];
+    rejectToolCalls?: string[];
 }
 /**
  * A wrapper around a streaming response that provides multiple consumption patterns.
@@ -31,7 +39,6 @@ export interface GetResponseOptions<TTools extends readonly Tool[]> {
  */
 export declare class ModelResult<TTools extends readonly Tool[]> {
     private reusableStream;
-    private streamPromise;
     private textPromise;
     private options;
     private initPromise;
@@ -40,21 +47,172 @@ export declare class ModelResult<TTools extends readonly Tool[]> {
     private toolEventBroadcaster;
     private allToolExecutionRounds;
     private resolvedRequest;
+    private stateAccessor;
+    private currentState;
+    private requireApprovalFn;
+    private approvedToolCalls;
+    private rejectedToolCalls;
+    private isResumingFromApproval;
     constructor(options: GetResponseOptions<TTools>);
     /**
      * 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.
      */
     private ensureBroadcaster;
     /**
      * Type guard to check if a value is a non-streaming response
+     * Only requires 'output' field and absence of 'toReadableStream' method
      */
     private isNonStreamingResponse;
+    /**
+     * 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
+     */
+    private getInitialResponse;
+    /**
+     * 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
+     */
+    private saveResponseToState;
+    /**
+     * Mark state as complete.
+     * Sets the conversation status to 'complete' indicating no further tool execution is needed.
+     */
+    private markStateComplete;
+    /**
+     * 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
+     */
+    private saveToolResultsToState;
+    /**
+     * 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
+     */
+    private checkForInterruption;
+    /**
+     * 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.
+     */
+    private shouldStopExecution;
+    /**
+     * 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
+     */
+    private hasExecutableToolCalls;
+    /**
+     * 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
+     */
+    private executeAutoApproveTools;
+    /**
+     * 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
+     */
+    private handleApprovalCheck;
+    /**
+     * 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
+     */
+    private executeToolRound;
+    /**
+     * Resolve async functions for the current turn.
+     * Updates the resolved request with turn-specific parameter values.
+     *
+     * @param turnContext - The turn context for parameter resolution
+     */
+    private resolveAsyncFunctionsForTurn;
+    /**
+     * Apply nextTurnParams from executed tools.
+     * Allows tools to modify request parameters for subsequent turns.
+     *
+     * @param toolCalls - The tool calls that were just executed
+     */
+    private applyNextTurnParams;
+    /**
+     * 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
+     */
+    private makeFollowupRequest;
+    /**
+     * 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
+     */
+    private validateFinalResponse;
+    /**
+     * 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
+     */
+    private resolveRequestForContext;
+    /**
+     * 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
+     */
+    private saveStateSafely;
+    /**
+     * 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
+     */
+    private clearOptionalStateProperties;
     /**
      * Initialize the stream if not already started
      * This is idempotent - multiple calls will return the same promise
      */
     private initStream;
+    /**
+     * Process approval/rejection decisions and resume execution
+     */
+    private processApprovalDecisions;
+    /**
+     * Continue execution with unsent tool results
+     */
+    private continueWithUnsentResults;
     /**
      * Execute tools automatically if they are provided and have execute functions
      * This is idempotent - multiple calls will return the same promise
@@ -78,9 +236,9 @@ export declare class ModelResult<TTools extends readonly Tool[]> {
     /**
      * 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(): AsyncIterableIterator<ResponseStreamEvent<InferToolEventsUnion<TTools>>>;
+    getFullResponsesStream(): AsyncIterableIterator<ResponseStreamEvent<InferToolEventsUnion<TTools>, InferToolOutputsUnion<TTools>>>;
     /**
      * Stream only text deltas as they arrive.
      * This filters the full event stream to only yield text content.
@@ -121,5 +279,22 @@ export declare class ModelResult<TTools extends readonly Tool[]> {
      * Cancel the underlying stream and all consumers
      */
     cancel(): Promise<void>;
+    /**
+     * Check if the conversation requires human approval to continue.
+     * Returns true if there are pending tool calls awaiting approval.
+     */
+    requiresApproval(): Promise<boolean>;
+    /**
+     * Get the pending tool calls that require approval.
+     * Returns empty array if no approvals needed.
+     */
+    getPendingToolCalls(): Promise<ParsedToolCall<TTools[number]>[]>;
+    /**
+     * 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.
+     */
+    getState(): Promise<ConversationState<TTools>>;
 }
 //# sourceMappingURL=model-result.d.ts.map