@openrouter/sdk 0.3.7 → 0.3.10

package/esm/lib/next-turn-params.js

@@ -0,0 +1,129 @@
+/**
+ * Type guard to check if a value is a Record<string, unknown>
+ */
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+/**
+ * Build a NextTurnParamsContext from the current request
+ * Extracts relevant fields that can be modified by nextTurnParams functions
+ *
+ * @param request - The current OpenResponsesRequest
+ * @returns Context object with current parameter values
+ */
+export function buildNextTurnParamsContext(request) {
+    return {
+        input: request.input ?? [],
+        model: request.model ?? '',
+        models: request.models ?? [],
+        temperature: request.temperature ?? null,
+        maxOutputTokens: request.maxOutputTokens ?? null,
+        topP: request.topP ?? null,
+        topK: request.topK,
+        instructions: request.instructions ?? null,
+    };
+}
+/**
+ * Execute nextTurnParams functions for all called tools
+ * Composes functions when multiple tools modify the same parameter
+ *
+ * @param toolCalls - Tool calls that were executed in this turn
+ * @param tools - All available tools
+ * @param currentRequest - The current request
+ * @returns Object with computed parameter values
+ */
+export async function executeNextTurnParamsFunctions(toolCalls, tools, currentRequest) {
+    // Build initial context from current request
+    const context = buildNextTurnParamsContext(currentRequest);
+    // Collect all nextTurnParams functions from tools (in tools array order)
+    const result = {};
+    const workingContext = { ...context };
+    for (const tool of tools) {
+        if (!tool.function.nextTurnParams) {
+            continue;
+        }
+        // Find tool calls for this tool
+        const callsForTool = toolCalls.filter(tc => tc.name === tool.function.name);
+        for (const call of callsForTool) {
+            // For each parameter function in this tool's nextTurnParams
+            // We need to process each key individually to maintain type safety
+            const nextParams = tool.function.nextTurnParams;
+            // Validate that call.arguments is a record using type guard
+            if (!isRecord(call.arguments)) {
+                const typeStr = Array.isArray(call.arguments)
+                    ? 'array'
+                    : typeof call.arguments;
+                throw new Error(`Tool call arguments for ${tool.function.name} must be an object, got ${typeStr}`);
+            }
+            // Process each parameter key with proper typing
+            await processNextTurnParamsForCall(nextParams, call.arguments, workingContext, result, tool.function.name);
+        }
+    }
+    return result;
+}
+/**
+ * Process nextTurnParams for a single tool call with full type safety
+ */
+async function processNextTurnParamsForCall(nextParams, params, workingContext, result, toolName) {
+    // Type-safe processing for each known parameter key
+    // We iterate through keys and use runtime checks instead of casts
+    for (const paramKey of Object.keys(nextParams)) {
+        const fn = nextParams[paramKey];
+        if (typeof fn !== 'function') {
+            continue;
+        }
+        // Validate that paramKey is actually a key of NextTurnParamsContext
+        if (!isValidNextTurnParamKey(paramKey)) {
+            if (process.env['NODE_ENV'] !== 'production') {
+                console.warn(`Invalid nextTurnParams key "${paramKey}" in tool "${toolName}". ` +
+                    `Valid keys: input, model, models, temperature, maxOutputTokens, topP, topK, instructions`);
+            }
+            continue;
+        }
+        // Execute the function and await the result
+        const newValue = await Promise.resolve(fn(params, workingContext));
+        // Update both result and workingContext to enable composition
+        // Later tools will see modifications made by earlier tools
+        setNextTurnParam(result, paramKey, newValue);
+        setNextTurnParam(workingContext, paramKey, newValue);
+    }
+}
+/**
+ * Type guard to check if a string is a valid NextTurnParamsContext key
+ */
+function isValidNextTurnParamKey(key) {
+    const validKeys = new Set([
+        'input',
+        'model',
+        'models',
+        'temperature',
+        'maxOutputTokens',
+        'topP',
+        'topK',
+        'instructions',
+    ]);
+    return validKeys.has(key);
+}
+/**
+ * Type-safe setter for NextTurnParamsContext
+ * This wrapper is needed because TypeScript doesn't properly narrow the type
+ * after the type guard, even though we've validated the key
+ */
+function setNextTurnParam(target, key, value) {
+    target[key] = value;
+}
+/**
+ * Apply computed nextTurnParams to the current request
+ * Returns a new request object with updated parameters
+ *
+ * @param request - The current request
+ * @param computedParams - Computed parameter values from nextTurnParams functions
+ * @returns New request with updated parameters
+ */
+export function applyNextTurnParamsToRequest(request, computedParams) {
+    return {
+        ...request,
+        ...computedParams,
+    };
+}
+//# sourceMappingURL=next-turn-params.js.map

package/esm/lib/reusable-stream.js

@@ -75,23 +75,23 @@ export class ReusableReadableStream {
                     self.consumers.delete(consumerId);
                     throw self.sourceError;
                 }
-                // Wait for more data - but check conditions after setting up the promise
-                // to avoid race condition where source completes between check and wait
+                // Set up the waiting promise FIRST to avoid race condition
+                // where source completes after the check but before promise is set
                 const waitPromise = new Promise((resolve, reject) => {
                     consumer.waitingPromise = {
                         resolve,
                         reject,
                     };
-                });
-                // Double-check conditions after setting up promise to handle race
-                if (self.sourceComplete || self.sourceError || consumer.position < self.buffer.length) {
-                    // Resolve immediately if conditions changed
-                    if (consumer.waitingPromise) {
-                        consumer.waitingPromise.resolve();
-                        consumer.waitingPromise = null;
+                    // Immediately check if we should resolve after setting up the promise
+                    // This handles the case where data arrived or source completed
+                    // between our initial checks and promise creation
+                    if (self.sourceComplete || self.sourceError || consumer.position < self.buffer.length) {
+                        resolve();
                     }
-                }
+                });
                 await waitPromise;
+                // Clear the promise reference after it resolves
+                consumer.waitingPromise = null;
                 // Recursively try again after waking up
                 return this.next();
             },

package/esm/lib/stop-conditions.d.ts

@@ -0,0 +1,80 @@
+import type { StepResult, StopCondition, Tool } from './tool-types.js';
+/**
+ * Stop condition that checks if step count equals or exceeds a specific number
+ * @param stepCount - The number of steps to allow before stopping
+ * @returns StopCondition that returns true when steps.length >= stepCount
+ *
+ * @example
+ * ```typescript
+ * stopWhen: stepCountIs(5) // Stop after 5 steps
+ * ```
+ */
+export declare function stepCountIs(stepCount: number): StopCondition;
+/**
+ * Stop condition that checks if any step contains a tool call with the given name
+ * @param toolName - The name of the tool to check for
+ * @returns StopCondition that returns true if the tool was called in any step
+ *
+ * @example
+ * ```typescript
+ * stopWhen: hasToolCall('search') // Stop when search tool is called
+ * ```
+ */
+export declare function hasToolCall(toolName: string): StopCondition;
+/**
+ * Evaluates an array of stop conditions
+ * Returns true if ANY condition returns true (OR logic)
+ * @param options - Object containing stopConditions and steps
+ * @returns Promise<boolean> indicating if execution should stop
+ *
+ * @example
+ * ```typescript
+ * const shouldStop = await isStopConditionMet({
+ *   stopConditions: [stepCountIs(5), hasToolCall('search')],
+ *   steps: allSteps
+ * });
+ * ```
+ */
+export declare function isStopConditionMet<TTools extends readonly Tool[]>(options: {
+    readonly stopConditions: ReadonlyArray<StopCondition<TTools>>;
+    readonly steps: ReadonlyArray<StepResult<TTools>>;
+}): Promise<boolean>;
+/**
+ * Stop when total token usage exceeds a threshold
+ * OpenRouter-specific helper using usage data
+ *
+ * @param maxTokens - Maximum total tokens to allow
+ * @returns StopCondition that returns true when token usage exceeds threshold
+ *
+ * @example
+ * ```typescript
+ * stopWhen: maxTokensUsed(10000) // Stop when total tokens exceed 10,000
+ * ```
+ */
+export declare function maxTokensUsed(maxTokens: number): StopCondition;
+/**
+ * Stop when total cost exceeds a threshold
+ * OpenRouter-specific helper using cost data
+ *
+ * @param maxCostInDollars - Maximum cost in dollars to allow
+ * @returns StopCondition that returns true when cost exceeds threshold
+ *
+ * @example
+ * ```typescript
+ * stopWhen: maxCost(0.50) // Stop when total cost exceeds $0.50
+ * ```
+ */
+export declare function maxCost(maxCostInDollars: number): StopCondition;
+/**
+ * Stop when a specific finish reason is encountered
+ *
+ * @param reason - The finish reason to check for
+ * @returns StopCondition that returns true when finish reason matches
+ *
+ * @example
+ * ```typescript
+ * stopWhen: finishReasonIs('length') // Stop when context length limit is hit
+ * ```
+ */
+export declare function finishReasonIs(reason: string): StopCondition;
+//# sourceMappingURL=stop-conditions.d.ts.map

package/esm/lib/stop-conditions.js

@@ -0,0 +1,104 @@
+/**
+ * Stop condition that checks if step count equals or exceeds a specific number
+ * @param stepCount - The number of steps to allow before stopping
+ * @returns StopCondition that returns true when steps.length >= stepCount
+ *
+ * @example
+ * ```typescript
+ * stopWhen: stepCountIs(5) // Stop after 5 steps
+ * ```
+ */
+export function stepCountIs(stepCount) {
+    return ({ steps }) => steps.length >= stepCount;
+}
+/**
+ * Stop condition that checks if any step contains a tool call with the given name
+ * @param toolName - The name of the tool to check for
+ * @returns StopCondition that returns true if the tool was called in any step
+ *
+ * @example
+ * ```typescript
+ * stopWhen: hasToolCall('search') // Stop when search tool is called
+ * ```
+ */
+export function hasToolCall(toolName) {
+    return ({ steps }) => {
+        return steps.some((step) => step.toolCalls.some((call) => call.name === toolName));
+    };
+}
+/**
+ * Evaluates an array of stop conditions
+ * Returns true if ANY condition returns true (OR logic)
+ * @param options - Object containing stopConditions and steps
+ * @returns Promise<boolean> indicating if execution should stop
+ *
+ * @example
+ * ```typescript
+ * const shouldStop = await isStopConditionMet({
+ *   stopConditions: [stepCountIs(5), hasToolCall('search')],
+ *   steps: allSteps
+ * });
+ * ```
+ */
+export async function isStopConditionMet(options) {
+    const { stopConditions, steps } = options;
+    // Evaluate all conditions in parallel
+    const results = await Promise.all(stopConditions.map((condition) => Promise.resolve(condition({
+        steps,
+    }))));
+    // Return true if ANY condition is true (OR logic)
+    return results.some((result) => result === true);
+}
+/**
+ * Stop when total token usage exceeds a threshold
+ * OpenRouter-specific helper using usage data
+ *
+ * @param maxTokens - Maximum total tokens to allow
+ * @returns StopCondition that returns true when token usage exceeds threshold
+ *
+ * @example
+ * ```typescript
+ * stopWhen: maxTokensUsed(10000) // Stop when total tokens exceed 10,000
+ * ```
+ */
+export function maxTokensUsed(maxTokens) {
+    return ({ steps }) => {
+        const totalTokens = steps.reduce((sum, step) => sum + (step.usage?.totalTokens ?? 0), 0);
+        return totalTokens >= maxTokens;
+    };
+}
+/**
+ * Stop when total cost exceeds a threshold
+ * OpenRouter-specific helper using cost data
+ *
+ * @param maxCostInDollars - Maximum cost in dollars to allow
+ * @returns StopCondition that returns true when cost exceeds threshold
+ *
+ * @example
+ * ```typescript
+ * stopWhen: maxCost(0.50) // Stop when total cost exceeds $0.50
+ * ```
+ */
+export function maxCost(maxCostInDollars) {
+    return ({ steps }) => {
+        const totalCost = steps.reduce((sum, step) => sum + (step.usage?.cost ?? 0), 0);
+        return totalCost >= maxCostInDollars;
+    };
+}
+/**
+ * Stop when a specific finish reason is encountered
+ *
+ * @param reason - The finish reason to check for
+ * @returns StopCondition that returns true when finish reason matches
+ *
+ * @example
+ * ```typescript
+ * stopWhen: finishReasonIs('length') // Stop when context length limit is hit
+ * ```
+ */
+export function finishReasonIs(reason) {
+    return ({ steps }) => {
+        return steps.some((step) => step.finishReason === reason);
+    };
+}
+//# sourceMappingURL=stop-conditions.js.map

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

@@ -1,6 +1,6 @@
 import type * as models from '../models/index.js';
 import type { ReusableReadableStream } from './reusable-stream.js';
-import type { ParsedToolCall } from './tool-types.js';
+import type { ParsedToolCall, Tool } from './tool-types.js';
 /**
  * Extract text deltas from responses stream events
  */
@@ -43,12 +43,12 @@ export declare function extractTextFromResponse(response: models.OpenResponsesNo
  * 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[];
+export declare function extractToolCallsFromResponse(response: models.OpenResponsesNonStreamingResponse): ParsedToolCall<Tool>[];
 /**
  * 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>;
+export declare function buildToolCallStream(stream: ReusableReadableStream<models.OpenResponsesStreamEvent>): AsyncIterableIterator<ParsedToolCall<Tool>>;
 /**
  * Check if a response contains any tool calls
  */