@openrouter/sdk 0.1.18 → 0.1.23

package/esm/lib/stream-transformers.d.ts

@@ -0,0 +1,47 @@
+import * as models from "../models/index.js";
+import { ReusableReadableStream } from "./reusable-stream.js";
+import { ParsedToolCall } from "./tool-types.js";
+/**
+ * Extract text deltas from responses stream events
+ */
+export declare function extractTextDeltas(stream: ReusableReadableStream<models.OpenResponsesStreamEvent>): AsyncIterableIterator<string>;
+/**
+ * Extract reasoning deltas from responses stream events
+ */
+export declare function extractReasoningDeltas(stream: ReusableReadableStream<models.OpenResponsesStreamEvent>): AsyncIterableIterator<string>;
+/**
+ * Extract tool call argument deltas from responses stream events
+ */
+export declare function extractToolDeltas(stream: ReusableReadableStream<models.OpenResponsesStreamEvent>): AsyncIterableIterator<string>;
+/**
+ * Build incremental message updates from responses stream events
+ * Returns AssistantMessage (chat format) instead of ResponsesOutputMessage
+ */
+export declare function buildMessageStream(stream: ReusableReadableStream<models.OpenResponsesStreamEvent>): AsyncIterableIterator<models.AssistantMessage>;
+/**
+ * Consume stream until completion and return the complete response
+ */
+export declare function consumeStreamForCompletion(stream: ReusableReadableStream<models.OpenResponsesStreamEvent>): Promise<models.OpenResponsesNonStreamingResponse>;
+/**
+ * Extract the first message from a completed response
+ */
+export declare function extractMessageFromResponse(response: models.OpenResponsesNonStreamingResponse): models.AssistantMessage;
+/**
+ * Extract text from a response, either from outputText or by concatenating message content
+ */
+export declare function extractTextFromResponse(response: models.OpenResponsesNonStreamingResponse): string;
+/**
+ * Extract all tool calls from a completed response
+ * Returns parsed tool calls with arguments as objects (not JSON strings)
+ */
+export declare function extractToolCallsFromResponse(response: models.OpenResponsesNonStreamingResponse): ParsedToolCall[];
+/**
+ * Build incremental tool call updates from responses stream events
+ * Yields structured tool call objects as they're built from deltas
+ */
+export declare function buildToolCallStream(stream: ReusableReadableStream<models.OpenResponsesStreamEvent>): AsyncIterableIterator<ParsedToolCall>;
+/**
+ * Check if a response contains any tool calls
+ */
+export declare function responseHasToolCalls(response: models.OpenResponsesNonStreamingResponse): boolean;
+//# sourceMappingURL=stream-transformers.d.ts.map

package/esm/lib/stream-transformers.js

@@ -0,0 +1,280 @@
+/**
+ * Extract text deltas from responses stream events
+ */
+export async function* extractTextDeltas(stream) {
+    const consumer = stream.createConsumer();
+    for await (const event of consumer) {
+        if ("type" in event && event.type === "response.output_text.delta") {
+            const deltaEvent = event;
+            if (deltaEvent.delta) {
+                yield deltaEvent.delta;
+            }
+        }
+    }
+}
+/**
+ * Extract reasoning deltas from responses stream events
+ */
+export async function* extractReasoningDeltas(stream) {
+    const consumer = stream.createConsumer();
+    for await (const event of consumer) {
+        if ("type" in event && event.type === "response.reasoning_text.delta") {
+            const deltaEvent = event;
+            if (deltaEvent.delta) {
+                yield deltaEvent.delta;
+            }
+        }
+    }
+}
+/**
+ * Extract tool call argument deltas from responses stream events
+ */
+export async function* extractToolDeltas(stream) {
+    const consumer = stream.createConsumer();
+    for await (const event of consumer) {
+        if ("type" in event && event.type === "response.function_call_arguments.delta") {
+            const deltaEvent = event;
+            if (deltaEvent.delta) {
+                yield deltaEvent.delta;
+            }
+        }
+    }
+}
+/**
+ * Build incremental message updates from responses stream events
+ * Returns AssistantMessage (chat format) instead of ResponsesOutputMessage
+ */
+export async function* buildMessageStream(stream) {
+    const consumer = stream.createConsumer();
+    // Track the accumulated text
+    let currentText = "";
+    let hasStarted = false;
+    for await (const event of consumer) {
+        if (!("type" in event))
+            continue;
+        switch (event.type) {
+            case "response.output_item.added": {
+                const itemEvent = event;
+                if (itemEvent.item && "type" in itemEvent.item && itemEvent.item.type === "message") {
+                    hasStarted = true;
+                    currentText = "";
+                }
+                break;
+            }
+            case "response.output_text.delta": {
+                const deltaEvent = event;
+                if (hasStarted && deltaEvent.delta) {
+                    currentText += deltaEvent.delta;
+                    // Yield updated message
+                    yield {
+                        role: "assistant",
+                        content: currentText,
+                    };
+                }
+                break;
+            }
+            case "response.output_item.done": {
+                const itemDoneEvent = event;
+                if (itemDoneEvent.item && "type" in itemDoneEvent.item && itemDoneEvent.item.type === "message") {
+                    // Yield final complete message
+                    const outputMessage = itemDoneEvent.item;
+                    yield convertToAssistantMessage(outputMessage);
+                }
+                break;
+            }
+        }
+    }
+}
+/**
+ * Consume stream until completion and return the complete response
+ */
+export async function consumeStreamForCompletion(stream) {
+    const consumer = stream.createConsumer();
+    for await (const event of consumer) {
+        if (!("type" in event))
+            continue;
+        if (event.type === "response.completed") {
+            const completedEvent = event;
+            return completedEvent.response;
+        }
+        if (event.type === "response.failed") {
+            const failedEvent = event;
+            // The failed event contains the full response with error information
+            throw new Error(`Response failed: ${JSON.stringify(failedEvent.response.error)}`);
+        }
+        if (event.type === "response.incomplete") {
+            const incompleteEvent = event;
+            // Return the incomplete response
+            return incompleteEvent.response;
+        }
+    }
+    throw new Error("Stream ended without completion event");
+}
+/**
+ * Convert ResponsesOutputMessage to AssistantMessage (chat format)
+ */
+function convertToAssistantMessage(outputMessage) {
+    // Extract text content
+    const textContent = outputMessage.content
+        .filter((part) => "type" in part && part.type === "output_text")
+        .map((part) => part.text)
+        .join("");
+    return {
+        role: "assistant",
+        content: textContent || null,
+    };
+}
+/**
+ * Extract the first message from a completed response
+ */
+export function extractMessageFromResponse(response) {
+    const messageItem = response.output.find((item) => "type" in item && item.type === "message");
+    if (!messageItem) {
+        throw new Error("No message found in response output");
+    }
+    return convertToAssistantMessage(messageItem);
+}
+/**
+ * Extract text from a response, either from outputText or by concatenating message content
+ */
+export function extractTextFromResponse(response) {
+    // Use pre-concatenated outputText if available
+    if (response.outputText) {
+        return response.outputText;
+    }
+    // Otherwise, extract from the first message (convert to AssistantMessage which has string content)
+    const message = extractMessageFromResponse(response);
+    // AssistantMessage.content is string | Array | null | undefined
+    if (typeof message.content === "string") {
+        return message.content;
+    }
+    return "";
+}
+/**
+ * Extract all tool calls from a completed response
+ * Returns parsed tool calls with arguments as objects (not JSON strings)
+ */
+export function extractToolCallsFromResponse(response) {
+    const toolCalls = [];
+    for (const item of response.output) {
+        if ("type" in item && item.type === "function_call") {
+            const functionCallItem = item;
+            try {
+                const parsedArguments = JSON.parse(functionCallItem.arguments);
+                toolCalls.push({
+                    id: functionCallItem.callId,
+                    name: functionCallItem.name,
+                    arguments: parsedArguments,
+                });
+            }
+            catch (error) {
+                console.error(`Failed to parse tool call arguments for ${functionCallItem.name}:`, error);
+                // Include the tool call with unparsed arguments
+                toolCalls.push({
+                    id: functionCallItem.callId,
+                    name: functionCallItem.name,
+                    arguments: functionCallItem.arguments, // Keep as string if parsing fails
+                });
+            }
+        }
+    }
+    return toolCalls;
+}
+/**
+ * Build incremental tool call updates from responses stream events
+ * Yields structured tool call objects as they're built from deltas
+ */
+export async function* buildToolCallStream(stream) {
+    const consumer = stream.createConsumer();
+    // Track tool calls being built
+    const toolCallsInProgress = new Map();
+    for await (const event of consumer) {
+        if (!("type" in event))
+            continue;
+        switch (event.type) {
+            case "response.output_item.added": {
+                const itemEvent = event;
+                if (itemEvent.item &&
+                    "type" in itemEvent.item &&
+                    itemEvent.item.type === "function_call") {
+                    const functionCallItem = itemEvent.item;
+                    toolCallsInProgress.set(functionCallItem.callId, {
+                        id: functionCallItem.callId,
+                        name: functionCallItem.name,
+                        argumentsAccumulated: "",
+                    });
+                }
+                break;
+            }
+            case "response.function_call_arguments.delta": {
+                const deltaEvent = event;
+                const toolCall = toolCallsInProgress.get(deltaEvent.itemId);
+                if (toolCall && deltaEvent.delta) {
+                    toolCall.argumentsAccumulated += deltaEvent.delta;
+                }
+                break;
+            }
+            case "response.function_call_arguments.done": {
+                const doneEvent = event;
+                const toolCall = toolCallsInProgress.get(doneEvent.itemId);
+                if (toolCall) {
+                    // Parse complete arguments
+                    try {
+                        const parsedArguments = JSON.parse(doneEvent.arguments);
+                        yield {
+                            id: toolCall.id,
+                            name: doneEvent.name,
+                            arguments: parsedArguments,
+                        };
+                    }
+                    catch (error) {
+                        // Yield with unparsed arguments if parsing fails
+                        yield {
+                            id: toolCall.id,
+                            name: doneEvent.name,
+                            arguments: doneEvent.arguments,
+                        };
+                    }
+                    // Clean up
+                    toolCallsInProgress.delete(doneEvent.itemId);
+                }
+                break;
+            }
+            case "response.output_item.done": {
+                const itemDoneEvent = event;
+                if (itemDoneEvent.item &&
+                    "type" in itemDoneEvent.item &&
+                    itemDoneEvent.item.type === "function_call") {
+                    const functionCallItem = itemDoneEvent.item;
+                    // Yield final tool call if we haven't already
+                    if (toolCallsInProgress.has(functionCallItem.callId)) {
+                        try {
+                            const parsedArguments = JSON.parse(functionCallItem.arguments);
+                            yield {
+                                id: functionCallItem.callId,
+                                name: functionCallItem.name,
+                                arguments: parsedArguments,
+                            };
+                        }
+                        catch (error) {
+                            yield {
+                                id: functionCallItem.callId,
+                                name: functionCallItem.name,
+                                arguments: functionCallItem.arguments,
+                            };
+                        }
+                        toolCallsInProgress.delete(functionCallItem.callId);
+                    }
+                }
+                break;
+            }
+        }
+    }
+}
+/**
+ * Check if a response contains any tool calls
+ */
+export function responseHasToolCalls(response) {
+    return response.output.some((item) => "type" in item && item.type === "function_call");
+}
+//# sourceMappingURL=stream-transformers.js.map

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

@@ -0,0 +1,53 @@
+import { type ZodType } from "zod/v4";
+import { EnhancedTool, ToolExecutionResult, ParsedToolCall, APITool, TurnContext } from "./tool-types.js";
+/**
+ * Convert a Zod schema to JSON Schema using Zod v4's toJSONSchema function
+ */
+export declare function convertZodToJsonSchema(zodSchema: ZodType): Record<string, any>;
+/**
+ * Convert enhanced tools to OpenRouter API format
+ */
+export declare function convertEnhancedToolsToAPIFormat(tools: EnhancedTool[]): APITool[];
+/**
+ * Validate tool input against Zod schema
+ * @throws ZodError if validation fails
+ */
+export declare function validateToolInput<T>(schema: ZodType<T>, args: unknown): T;
+/**
+ * Validate tool output against Zod schema
+ * @throws ZodError if validation fails
+ */
+export declare function validateToolOutput<T>(schema: ZodType<T>, result: unknown): T;
+/**
+ * Parse tool call arguments from JSON string
+ */
+export declare function parseToolCallArguments(argumentsString: string): unknown;
+/**
+ * Execute a regular (non-generator) tool
+ */
+export declare function executeRegularTool(tool: EnhancedTool, toolCall: ParsedToolCall, context: TurnContext): Promise<ToolExecutionResult>;
+/**
+ * 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: EnhancedTool, toolCall: ParsedToolCall, context: TurnContext, onPreliminaryResult?: (toolCallId: string, result: unknown) => void): Promise<ToolExecutionResult>;
+/**
+ * Execute a tool call
+ * Automatically detects if it's a regular or generator tool
+ */
+export declare function executeTool(tool: EnhancedTool, toolCall: ParsedToolCall, context: TurnContext, onPreliminaryResult?: (toolCallId: string, result: unknown) => void): Promise<ToolExecutionResult>;
+/**
+ * Find a tool by name in the tools array
+ */
+export declare function findToolByName(tools: EnhancedTool[], name: string): EnhancedTool | undefined;
+/**
+ * Format tool execution result as a string for sending to the model
+ */
+export declare function formatToolResultForModel(result: ToolExecutionResult): string;
+/**
+ * Create a user-friendly error message for tool execution errors
+ */
+export declare function formatToolExecutionError(error: Error, toolCall: ParsedToolCall): string;
+//# sourceMappingURL=tool-executor.d.ts.map

package/esm/lib/tool-executor.js

@@ -0,0 +1,181 @@
+import { ZodError, toJSONSchema } from "zod/v4";
+import { hasExecuteFunction, isGeneratorTool, isRegularExecuteTool, } from "./tool-types.js";
+/**
+ * Convert a Zod schema to JSON Schema using Zod v4's toJSONSchema function
+ */
+export function convertZodToJsonSchema(zodSchema) {
+    const jsonSchema = toJSONSchema(zodSchema, {
+        target: "openapi-3.0",
+    });
+    return jsonSchema;
+}
+/**
+ * Convert enhanced tools to OpenRouter API format
+ */
+export function convertEnhancedToolsToAPIFormat(tools) {
+    return tools.map((tool) => ({
+        type: "function",
+        name: tool.function.name,
+        description: tool.function.description || null,
+        strict: null,
+        parameters: convertZodToJsonSchema(tool.function.inputSchema),
+    }));
+}
+/**
+ * Validate tool input against Zod schema
+ * @throws ZodError if validation fails
+ */
+export function validateToolInput(schema, args) {
+    return schema.parse(args);
+}
+/**
+ * Validate tool output against Zod schema
+ * @throws ZodError if validation fails
+ */
+export function validateToolOutput(schema, result) {
+    return schema.parse(result);
+}
+/**
+ * Parse tool call arguments from JSON string
+ */
+export function parseToolCallArguments(argumentsString) {
+    try {
+        return JSON.parse(argumentsString);
+    }
+    catch (error) {
+        throw new Error(`Failed to parse tool call arguments: ${error instanceof Error ? error.message : String(error)}`);
+    }
+}
+/**
+ * Execute a regular (non-generator) tool
+ */
+export async function executeRegularTool(tool, toolCall, context) {
+    if (!isRegularExecuteTool(tool)) {
+        throw new Error(`Tool "${toolCall.name}" is not a regular execute tool or has no execute function`);
+    }
+    try {
+        // Validate input
+        const validatedInput = validateToolInput(tool.function.inputSchema, toolCall.arguments);
+        // Execute tool with context
+        const result = await Promise.resolve(tool.function.execute(validatedInput, context));
+        // Validate output if schema is provided
+        if (tool.function.outputSchema) {
+            const validatedOutput = validateToolOutput(tool.function.outputSchema, result);
+            return {
+                toolCallId: toolCall.id,
+                toolName: toolCall.name,
+                result: validatedOutput,
+            };
+        }
+        return {
+            toolCallId: toolCall.id,
+            toolName: toolCall.name,
+            result,
+        };
+    }
+    catch (error) {
+        return {
+            toolCallId: toolCall.id,
+            toolName: toolCall.name,
+            result: null,
+            error: error instanceof Error ? error : new Error(String(error)),
+        };
+    }
+}
+/**
+ * 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 async function executeGeneratorTool(tool, toolCall, context, onPreliminaryResult) {
+    if (!isGeneratorTool(tool)) {
+        throw new Error(`Tool "${toolCall.name}" is not a generator tool`);
+    }
+    try {
+        // Validate input
+        const validatedInput = validateToolInput(tool.function.inputSchema, toolCall.arguments);
+        // Execute generator and collect all results
+        const preliminaryResults = [];
+        let lastEmittedValue = null;
+        let hasEmittedValue = false;
+        for await (const event of tool.function.execute(validatedInput, context)) {
+            hasEmittedValue = true;
+            // Validate event against eventSchema
+            const validatedEvent = validateToolOutput(tool.function.eventSchema, event);
+            preliminaryResults.push(validatedEvent);
+            lastEmittedValue = validatedEvent;
+            // Emit preliminary result via callback
+            if (onPreliminaryResult) {
+                onPreliminaryResult(toolCall.id, validatedEvent);
+            }
+        }
+        // Generator must emit at least one value
+        if (!hasEmittedValue) {
+            throw new Error(`Generator tool "${toolCall.name}" completed without emitting any values`);
+        }
+        // Validate the last emitted value against outputSchema (this is the final result)
+        const finalResult = validateToolOutput(tool.function.outputSchema, lastEmittedValue);
+        // Remove last item from preliminaryResults since it's the final output
+        preliminaryResults.pop();
+        return {
+            toolCallId: toolCall.id,
+            toolName: toolCall.name,
+            result: finalResult,
+            preliminaryResults,
+        };
+    }
+    catch (error) {
+        return {
+            toolCallId: toolCall.id,
+            toolName: toolCall.name,
+            result: null,
+            error: error instanceof Error ? error : new Error(String(error)),
+        };
+    }
+}
+/**
+ * Execute a tool call
+ * Automatically detects if it's a regular or generator tool
+ */
+export async function executeTool(tool, toolCall, context, onPreliminaryResult) {
+    if (!hasExecuteFunction(tool)) {
+        throw new Error(`Tool "${toolCall.name}" has no execute function. Use manual tool execution.`);
+    }
+    if (isGeneratorTool(tool)) {
+        return executeGeneratorTool(tool, toolCall, context, onPreliminaryResult);
+    }
+    return executeRegularTool(tool, toolCall, context);
+}
+/**
+ * Find a tool by name in the tools array
+ */
+export function findToolByName(tools, name) {
+    return tools.find((tool) => tool.function.name === name);
+}
+/**
+ * Format tool execution result as a string for sending to the model
+ */
+export function formatToolResultForModel(result) {
+    if (result.error) {
+        return JSON.stringify({
+            error: result.error.message,
+            toolName: result.toolName,
+        });
+    }
+    return JSON.stringify(result.result);
+}
+/**
+ * Create a user-friendly error message for tool execution errors
+ */
+export function formatToolExecutionError(error, toolCall) {
+    if (error instanceof ZodError) {
+        const issues = error.issues.map((issue) => ({
+            path: issue.path.join("."),
+            message: issue.message,
+        }));
+        return `Tool "${toolCall.name}" validation error:\n${JSON.stringify(issues, null, 2)}`;
+    }
+    return `Tool "${toolCall.name}" execution error: ${error.message}`;
+}
+//# sourceMappingURL=tool-executor.js.map

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

@@ -0,0 +1,50 @@
+import * as models from "../models/index.js";
+import { EnhancedTool, ToolExecutionResult } from "./tool-types.js";
+/**
+ * Options for tool execution
+ */
+export interface ToolExecutionOptions {
+    maxRounds?: number;
+    onPreliminaryResult?: (toolCallId: string, result: unknown) => void;
+}
+/**
+ * Result of the tool execution loop
+ */
+export interface ToolOrchestrationResult {
+    finalResponse: models.OpenResponsesNonStreamingResponse;
+    allResponses: models.OpenResponsesNonStreamingResponse[];
+    toolExecutionResults: ToolExecutionResult[];
+    conversationInput: models.OpenResponsesInput;
+}
+/**
+ * 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 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: any[]) => Promise<models.OpenResponsesNonStreamingResponse>, initialInput: models.OpenResponsesInput, tools: EnhancedTool[], apiTools: any[], options?: ToolExecutionOptions): Promise<ToolOrchestrationResult>;
+/**
+ * Convert tool execution results to a map for easy lookup
+ */
+export declare function toolResultsToMap(results: ToolExecutionResult[]): Map<string, {
+    result: unknown;
+    preliminaryResults?: unknown[];
+}>;
+/**
+ * Build a summary of tool executions for debugging/logging
+ */
+export declare function summarizeToolExecutions(results: ToolExecutionResult[]): string;
+/**
+ * Check if any tool executions had errors
+ */
+export declare function hasToolExecutionErrors(results: ToolExecutionResult[]): boolean;
+/**
+ * Get all tool execution errors
+ */
+export declare function getToolExecutionErrors(results: ToolExecutionResult[]): Error[];
+//# sourceMappingURL=tool-orchestrator.d.ts.map