@openrouter/sdk 0.3.7 → 0.3.11

package/esm/lib/stream-type-guards.d.ts

@@ -0,0 +1,29 @@
+import type * as models from '../models/index.js';
+/**
+ * Type guards for OpenResponses stream events
+ * These enable proper TypeScript narrowing without type casts
+ */
+export declare function isOutputTextDeltaEvent(event: models.OpenResponsesStreamEvent): event is models.OpenResponsesStreamEventResponseOutputTextDelta;
+export declare function isReasoningDeltaEvent(event: models.OpenResponsesStreamEvent): event is models.OpenResponsesReasoningDeltaEvent;
+export declare function isFunctionCallArgumentsDeltaEvent(event: models.OpenResponsesStreamEvent): event is models.OpenResponsesStreamEventResponseFunctionCallArgumentsDelta;
+export declare function isOutputItemAddedEvent(event: models.OpenResponsesStreamEvent): event is models.OpenResponsesStreamEventResponseOutputItemAdded;
+export declare function isOutputItemDoneEvent(event: models.OpenResponsesStreamEvent): event is models.OpenResponsesStreamEventResponseOutputItemDone;
+export declare function isResponseCompletedEvent(event: models.OpenResponsesStreamEvent): event is models.OpenResponsesStreamEventResponseCompleted;
+export declare function isResponseFailedEvent(event: models.OpenResponsesStreamEvent): event is models.OpenResponsesStreamEventResponseFailed;
+export declare function isResponseIncompleteEvent(event: models.OpenResponsesStreamEvent): event is models.OpenResponsesStreamEventResponseIncomplete;
+export declare function isFunctionCallArgumentsDoneEvent(event: models.OpenResponsesStreamEvent): event is models.OpenResponsesStreamEventResponseFunctionCallArgumentsDone;
+export declare function isOutputMessage(item: unknown): item is models.ResponsesOutputMessage;
+export declare function isFunctionCallOutputItem(item: unknown): item is models.ResponsesOutputItemFunctionCall;
+export declare function isReasoningOutputItem(item: unknown): item is models.ResponsesOutputItemReasoning;
+export declare function isWebSearchCallOutputItem(item: unknown): item is models.ResponsesWebSearchCallOutput;
+export declare function isFileSearchCallOutputItem(item: unknown): item is models.ResponsesOutputItemFileSearchCall;
+export declare function isImageGenerationCallOutputItem(item: unknown): item is models.ResponsesImageGenerationCall;
+export declare function isOutputTextPart(part: unknown): part is models.ResponseOutputText;
+export declare function isRefusalPart(part: unknown): part is models.OpenAIResponsesRefusalContent;
+export declare function isFileCitationAnnotation(annotation: unknown): annotation is models.FileCitation;
+export declare function isURLCitationAnnotation(annotation: unknown): annotation is models.URLCitation;
+export declare function isFilePathAnnotation(annotation: unknown): annotation is models.FilePath;
+export declare function hasTypeProperty(item: unknown): item is {
+    type: string;
+};
+//# sourceMappingURL=stream-type-guards.d.ts.map

package/esm/lib/stream-type-guards.js

@@ -0,0 +1,109 @@
+/**
+ * Type guards for OpenResponses stream events
+ * These enable proper TypeScript narrowing without type casts
+ */
+// Stream event type guards
+export function isOutputTextDeltaEvent(event) {
+    return 'type' in event && event.type === 'response.output_text.delta';
+}
+export function isReasoningDeltaEvent(event) {
+    return 'type' in event && event.type === 'response.reasoning_text.delta';
+}
+export function isFunctionCallArgumentsDeltaEvent(event) {
+    return 'type' in event && event.type === 'response.function_call_arguments.delta';
+}
+export function isOutputItemAddedEvent(event) {
+    return 'type' in event && event.type === 'response.output_item.added';
+}
+export function isOutputItemDoneEvent(event) {
+    return 'type' in event && event.type === 'response.output_item.done';
+}
+export function isResponseCompletedEvent(event) {
+    return 'type' in event && event.type === 'response.completed';
+}
+export function isResponseFailedEvent(event) {
+    return 'type' in event && event.type === 'response.failed';
+}
+export function isResponseIncompleteEvent(event) {
+    return 'type' in event && event.type === 'response.incomplete';
+}
+export function isFunctionCallArgumentsDoneEvent(event) {
+    return 'type' in event && event.type === 'response.function_call_arguments.done';
+}
+// Output item type guards
+export function isOutputMessage(item) {
+    return (typeof item === 'object' &&
+        item !== null &&
+        'type' in item &&
+        item.type === 'message');
+}
+export function isFunctionCallOutputItem(item) {
+    return (typeof item === 'object' &&
+        item !== null &&
+        'type' in item &&
+        item.type === 'function_call');
+}
+export function isReasoningOutputItem(item) {
+    return (typeof item === 'object' &&
+        item !== null &&
+        'type' in item &&
+        item.type === 'reasoning');
+}
+export function isWebSearchCallOutputItem(item) {
+    return (typeof item === 'object' &&
+        item !== null &&
+        'type' in item &&
+        item.type === 'web_search_call');
+}
+export function isFileSearchCallOutputItem(item) {
+    return (typeof item === 'object' &&
+        item !== null &&
+        'type' in item &&
+        item.type === 'file_search_call');
+}
+export function isImageGenerationCallOutputItem(item) {
+    return (typeof item === 'object' &&
+        item !== null &&
+        'type' in item &&
+        item.type === 'image_generation_call');
+}
+// Content part type guards
+export function isOutputTextPart(part) {
+    return (typeof part === 'object' &&
+        part !== null &&
+        'type' in part &&
+        part.type === 'output_text');
+}
+export function isRefusalPart(part) {
+    return (typeof part === 'object' &&
+        part !== null &&
+        'type' in part &&
+        part.type === 'refusal');
+}
+// Annotation type guards for Claude conversion
+export function isFileCitationAnnotation(annotation) {
+    return (typeof annotation === 'object' &&
+        annotation !== null &&
+        'type' in annotation &&
+        annotation.type === 'file_citation');
+}
+export function isURLCitationAnnotation(annotation) {
+    return (typeof annotation === 'object' &&
+        annotation !== null &&
+        'type' in annotation &&
+        annotation.type === 'url_citation');
+}
+export function isFilePathAnnotation(annotation) {
+    return (typeof annotation === 'object' &&
+        annotation !== null &&
+        'type' in annotation &&
+        annotation.type === 'file_path');
+}
+// Helper to check if output has a type property
+export function hasTypeProperty(item) {
+    return (typeof item === 'object' &&
+        item !== null &&
+        'type' in item &&
+        typeof item.type === 'string');
+}
+//# sourceMappingURL=stream-type-guards.js.map

package/esm/lib/tool-executor.d.ts

@@ -1,13 +1,15 @@
-import type { ZodType } from 'zod/v4';
+import type { ZodType } from 'zod';
 import type { APITool, Tool, ParsedToolCall, ToolExecutionResult, TurnContext } from './tool-types.js';
 /**
  * Convert a Zod schema to JSON Schema using Zod v4's toJSONSchema function
+ * Uses type assertion to bridge zod (user schemas) and zod/v4 (toJSONSchema)
  */
 export declare function convertZodToJsonSchema(zodSchema: ZodType): Record<string, unknown>;
 /**
  * Convert tools to OpenRouter API format
+ * Accepts readonly arrays for better type compatibility
  */
-export declare function convertToolsToAPIFormat(tools: Tool[]): APITool[];
+export declare function convertToolsToAPIFormat(tools: readonly Tool[]): APITool[];
 /**
  * Validate tool input against Zod schema
  * @throws ZodError if validation fails
@@ -25,19 +27,19 @@ export declare function parseToolCallArguments(argumentsString: string): unknown
 /**
  * Execute a regular (non-generator) tool
  */
-export declare function executeRegularTool(tool: Tool, toolCall: ParsedToolCall, context: TurnContext): Promise<ToolExecutionResult>;
+export declare function executeRegularTool(tool: Tool, toolCall: ParsedToolCall<Tool>, context: TurnContext): Promise<ToolExecutionResult<Tool>>;
 /**
  * Execute a generator tool and collect preliminary and final results
  * - Intermediate yields are validated against eventSchema (preliminary events)
  * - Last yield is validated against outputSchema (final result sent to model)
  * - Generator must emit at least one value
  */
-export declare function executeGeneratorTool(tool: Tool, toolCall: ParsedToolCall, context: TurnContext, onPreliminaryResult?: (toolCallId: string, result: unknown) => void): Promise<ToolExecutionResult>;
+export declare function executeGeneratorTool(tool: Tool, toolCall: ParsedToolCall<Tool>, context: TurnContext, onPreliminaryResult?: (toolCallId: string, result: unknown) => void): Promise<ToolExecutionResult<Tool>>;
 /**
  * Execute a tool call
  * Automatically detects if it's a regular or generator tool
  */
-export declare function executeTool(tool: Tool, toolCall: ParsedToolCall, context: TurnContext, onPreliminaryResult?: (toolCallId: string, result: unknown) => void): Promise<ToolExecutionResult>;
+export declare function executeTool(tool: Tool, toolCall: ParsedToolCall<Tool>, context: TurnContext, onPreliminaryResult?: (toolCallId: string, result: unknown) => void): Promise<ToolExecutionResult<Tool>>;
 /**
  * Find a tool by name in the tools array
  */
@@ -45,9 +47,9 @@ export declare function findToolByName(tools: Tool[], name: string): Tool | unde
 /**
  * Format tool execution result as a string for sending to the model
  */
-export declare function formatToolResultForModel(result: ToolExecutionResult): string;
+export declare function formatToolResultForModel(result: ToolExecutionResult<Tool>): string;
 /**
  * Create a user-friendly error message for tool execution errors
  */
-export declare function formatToolExecutionError(error: Error, toolCall: ParsedToolCall): string;
+export declare function formatToolExecutionError(error: Error, toolCall: ParsedToolCall<Tool>): string;
 //# sourceMappingURL=tool-executor.d.ts.map

package/esm/lib/tool-executor.js

@@ -2,15 +2,18 @@ import { toJSONSchema, ZodError } from 'zod/v4';
 import { hasExecuteFunction, isGeneratorTool, isRegularExecuteTool } from './tool-types.js';
 /**
  * Convert a Zod schema to JSON Schema using Zod v4's toJSONSchema function
+ * Uses type assertion to bridge zod (user schemas) and zod/v4 (toJSONSchema)
  */
 export function convertZodToJsonSchema(zodSchema) {
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
     const jsonSchema = toJSONSchema(zodSchema, {
-        target: 'openapi-3.0',
+        target: 'draft-7',
     });
     return jsonSchema;
 }
 /**
  * Convert tools to OpenRouter API format
+ * Accepts readonly arrays for better type compatibility
  */
 export function convertToolsToAPIFormat(tools) {
     return tools.map((tool) => ({
@@ -55,6 +58,8 @@ export async function executeRegularTool(tool, toolCall, context) {
     }
     try {
         // Validate input - the schema validation ensures type safety at runtime
+        // validateToolInput returns z.infer<typeof tool.function.inputSchema>
+        // which is exactly the type expected by execute
         const validatedInput = validateToolInput(tool.function.inputSchema, toolCall.arguments);
         // Execute tool with context
         const result = await Promise.resolve(tool.function.execute(validatedInput, context));
@@ -94,6 +99,7 @@ export async function executeGeneratorTool(tool, toolCall, context, onPreliminar
     }
     try {
         // Validate input - the schema validation ensures type safety at runtime
+        // The inputSchema's inferred type matches the execute function's parameter type by construction
         const validatedInput = validateToolInput(tool.function.inputSchema, toolCall.arguments);
         // Execute generator and collect all results
         const preliminaryResults = [];

package/esm/lib/tool-orchestrator.d.ts

@@ -4,7 +4,6 @@ import type { APITool, Tool, ToolExecutionResult } from './tool-types.js';
  * Options for tool execution
  */
 export interface ToolExecutionOptions {
-    maxRounds?: number;
     onPreliminaryResult?: (toolCallId: string, result: unknown) => void;
 }
 /**
@@ -13,7 +12,7 @@ export interface ToolExecutionOptions {
 export interface ToolOrchestrationResult {
     finalResponse: models.OpenResponsesNonStreamingResponse;
     allResponses: models.OpenResponsesNonStreamingResponse[];
-    toolExecutionResults: ToolExecutionResult[];
+    toolExecutionResults: ToolExecutionResult<Tool>[];
     conversationInput: models.OpenResponsesInput;
 }
 /**
@@ -22,29 +21,30 @@ export interface ToolOrchestrationResult {
  *
  * @param sendRequest - Function to send a request and get a response
  * @param initialInput - Starting input for the conversation
+ * @param initialRequest - Full initial request with all parameters
  * @param tools - Enhanced tools with Zod schemas and execute functions
  * @param apiTools - Converted tools in API format (JSON Schema)
  * @param options - Execution options
  * @returns Result containing final response and all execution data
  */
-export declare function executeToolLoop(sendRequest: (input: models.OpenResponsesInput, tools: APITool[]) => Promise<models.OpenResponsesNonStreamingResponse>, initialInput: models.OpenResponsesInput, tools: Tool[], apiTools: APITool[], options?: ToolExecutionOptions): Promise<ToolOrchestrationResult>;
+export declare function executeToolLoop(sendRequest: (input: models.OpenResponsesInput, tools: APITool[]) => Promise<models.OpenResponsesNonStreamingResponse>, initialInput: models.OpenResponsesInput, initialRequest: models.OpenResponsesRequest, tools: Tool[], apiTools: APITool[], options?: ToolExecutionOptions): Promise<ToolOrchestrationResult>;
 /**
  * Convert tool execution results to a map for easy lookup
  */
-export declare function toolResultsToMap(results: ToolExecutionResult[]): Map<string, {
+export declare function toolResultsToMap(results: ToolExecutionResult<Tool>[]): Map<string, {
     result: unknown;
     preliminaryResults?: unknown[];
 }>;
 /**
  * Build a summary of tool executions for debugging/logging
  */
-export declare function summarizeToolExecutions(results: ToolExecutionResult[]): string;
+export declare function summarizeToolExecutions(results: ToolExecutionResult<Tool>[]): string;
 /**
  * Check if any tool executions had errors
  */
-export declare function hasToolExecutionErrors(results: ToolExecutionResult[]): boolean;
+export declare function hasToolExecutionErrors(results: ToolExecutionResult<Tool>[]): boolean;
 /**
  * Get all tool execution errors
  */
-export declare function getToolExecutionErrors(results: ToolExecutionResult[]): Error[];
+export declare function getToolExecutionErrors(results: ToolExecutionResult<Tool>[]): Error[];
 //# sourceMappingURL=tool-orchestrator.d.ts.map

package/esm/lib/tool-orchestrator.js

@@ -1,30 +1,34 @@
 import { extractToolCallsFromResponse, responseHasToolCalls } from './stream-transformers.js';
+import { isFunctionCallOutputItem } from './stream-type-guards.js';
 import { executeTool, findToolByName } from './tool-executor.js';
 import { hasExecuteFunction } from './tool-types.js';
+import { buildTurnContext } from './turn-context.js';
+import { executeNextTurnParamsFunctions, applyNextTurnParamsToRequest } from './next-turn-params.js';
 /**
  * Execute tool calls and manage multi-turn conversations
  * This orchestrates the loop of: request -> tool calls -> execute -> send results -> repeat
  *
  * @param sendRequest - Function to send a request and get a response
  * @param initialInput - Starting input for the conversation
+ * @param initialRequest - Full initial request with all parameters
  * @param tools - Enhanced tools with Zod schemas and execute functions
  * @param apiTools - Converted tools in API format (JSON Schema)
  * @param options - Execution options
  * @returns Result containing final response and all execution data
  */
-export async function executeToolLoop(sendRequest, initialInput, tools, apiTools, options = {}) {
-    const maxRounds = options.maxRounds ?? 5;
+export async function executeToolLoop(sendRequest, initialInput, initialRequest, tools, apiTools, options = {}) {
     const onPreliminaryResult = options.onPreliminaryResult;
     const allResponses = [];
     const toolExecutionResults = [];
     let conversationInput = initialInput;
+    let currentRequest = { ...initialRequest };
     let currentRound = 0;
     let currentResponse;
     // Initial request
     currentResponse = await sendRequest(conversationInput, apiTools);
     allResponses.push(currentResponse);
-    // Loop until no more tool calls or max rounds reached
-    while (responseHasToolCalls(currentResponse) && currentRound < maxRounds) {
+    // Loop until no more tool calls (model decides when to stop)
+    while (responseHasToolCalls(currentResponse)) {
         currentRound++;
         // Extract tool calls from response
         const toolCalls = extractToolCallsFromResponse(currentResponse);
@@ -56,11 +60,26 @@ export async function executeToolLoop(sendRequest, initialInput, tools, apiTools
                 // Tool has no execute function - return null to filter out
                 return null;
             }
-            // Build turn context
-            const turnContext = {
-                numberOfTurns: currentRound,
-                messageHistory: conversationInput,
+            // Find the raw tool call from the response output
+            const rawToolCall = currentResponse.output.find((item) => isFunctionCallOutputItem(item) && item.callId === toolCall.id);
+            if (!rawToolCall) {
+                throw new Error(`Could not find raw tool call for ${toolCall.id}`);
+            }
+            // Convert to OpenResponsesFunctionToolCall format
+            const openResponsesToolCall = {
+                type: 'function_call',
+                callId: rawToolCall.callId,
+                name: rawToolCall.name,
+                arguments: rawToolCall.arguments,
+                id: rawToolCall.callId,
+                status: rawToolCall.status,
             };
+            // Build turn context with full information
+            const turnContext = buildTurnContext({
+                numberOfTurns: currentRound,
+                toolCall: openResponsesToolCall,
+                turnRequest: currentRequest,
+            });
             // Execute the tool
             return executeTool(tool, toolCall, turnContext, onPreliminaryResult);
         });
@@ -90,10 +109,17 @@ export async function executeToolLoop(sendRequest, initialInput, tools, apiTools
             }
         });
         toolExecutionResults.push(...roundResults);
+        // Execute nextTurnParams functions for tools that were called
+        const computedParams = await executeNextTurnParamsFunctions(toolCalls, tools, currentRequest);
+        // Apply computed parameters to request
+        if (Object.keys(computedParams).length > 0) {
+            currentRequest = applyNextTurnParamsToRequest(currentRequest, computedParams);
+            conversationInput = currentRequest.input ?? conversationInput;
+        }
         // Build array input with all output from previous response plus tool results
         // The API expects continuation via previousResponseId, not by including outputs
         // For now, we'll keep the conversation going via previousResponseId
-        conversationInput = initialInput; // Keep original input
+        // conversationInput is updated above if nextTurnParams modified it
         // Note: The OpenRouter Responses API uses previousResponseId for continuation
         // Tool results are automatically associated with the previous response's tool calls
         // Send updated conversation to API - this should use previousResponseId
@@ -147,6 +173,8 @@ export function hasToolExecutionErrors(results) {
  * Get all tool execution errors
  */
 export function getToolExecutionErrors(results) {
-    return results.filter((result) => result.error !== undefined).map((result) => result.error);
+    return results
+        .filter((result) => result.error !== undefined)
+        .map((result) => result.error);
 }
 //# sourceMappingURL=tool-orchestrator.js.map