@openrouter/sdk 0.9.11 → 0.11.2

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

@@ -0,0 +1,68 @@
+import type { $ZodObject, $ZodShape } from 'zod/v4/core';
+import type { ToolExecuteContext, TurnContext } from './tool-types.js';
+/**
+ * Listener function called when context values change
+ * Receives a shallow copy of the full context store
+ */
+type ContextChangeListener = (snapshot: Record<string, Record<string, unknown>>) => void;
+/**
+ * Context input can be a static value, a sync function, or an async function
+ */
+export type ContextInput<T extends Record<string, Record<string, unknown>>> = T | ((turn: TurnContext) => T) | ((turn: TurnContext) => Promise<T>);
+/**
+ * Mutable context store shared across all tool executions within a callModel invocation.
+ * Stores context keyed by tool name: `{ get_weather: { apiKey: '...' }, db_query: { dbUrl: '...' } }`.
+ * Notifies listeners on changes.
+ */
+export declare class ToolContextStore {
+    private store;
+    private listeners;
+    constructor(initialValues?: Record<string, Record<string, unknown>>);
+    /** Subscribe to context changes. Returns an unsubscribe function. */
+    subscribe(listener: ContextChangeListener): () => void;
+    /** Get a deep-shallow copy of the full context (all tools) */
+    getSnapshot(): Record<string, Record<string, unknown>>;
+    /** Get a shallow copy of context for a specific tool */
+    getToolContext(toolName: string): Record<string, unknown>;
+    /** Set context for a specific tool and notify listeners */
+    setToolContext(toolName: string, values: Record<string, unknown>): void;
+    /** Merge partial values into a specific tool's context and notify listeners */
+    mergeToolContext(toolName: string, partial: Record<string, unknown>): void;
+    private notifyListeners;
+}
+/**
+ * Build a flat ToolExecuteContext for a specific tool.
+ * Returns a merged object with TurnContext fields, a `local` getter
+ * (reads from the store on each access), `shared` getter, and mutation methods.
+ *
+ * The `local` and `shared` getters are live — calling `setContext()` or
+ * `setSharedContext()` and then reading the property reflects updated values immediately.
+ *
+ * @param turnContext - The current turn context
+ * @param store - The shared context store (keyed by tool name)
+ * @param toolName - The tool's name
+ * @param schema - The tool's contextSchema (for validation)
+ * @param sharedSchema - The shared contextSchema (for validation)
+ * @returns A flat ToolExecuteContext
+ */
+export declare function buildToolExecuteContext<TName extends string, TContext extends Record<string, unknown>, TShared extends Record<string, unknown> = Record<string, unknown>>(turnContext: TurnContext, store: ToolContextStore | undefined, toolName: TName, schema: $ZodObject<$ZodShape> | undefined, sharedSchema?: $ZodObject<$ZodShape> | undefined): ToolExecuteContext<TName, TContext, TShared>;
+/**
+ * Resolve a context input (static value, sync function, or async function) to a plain object.
+ *
+ * @param contextInput - The context value or function from callModel
+ * @param turnContext - The current turn context for function resolution
+ * @returns The resolved context object (keyed by tool name)
+ */
+export declare function resolveContext<T extends Record<string, Record<string, unknown>>>(contextInput: ContextInput<T> | undefined, turnContext: TurnContext): Promise<T>;
+/**
+ * Extract and validate context values for a specific tool from the context store.
+ * Returns a shallow copy so the caller cannot mutate the store directly.
+ *
+ * @param store - The shared context store (keyed by tool name)
+ * @param toolName - The tool's name
+ * @param schema - The tool's contextSchema
+ * @returns A shallow copy of the validated context values for this tool
+ */
+export declare function extractToolContext(store: ToolContextStore, toolName: string, schema: $ZodObject<$ZodShape> | undefined): Record<string, unknown>;
+export {};
+//# sourceMappingURL=tool-context.d.ts.map

package/esm/lib/tool-context.js

@@ -0,0 +1,175 @@
+import * as z4 from 'zod/v4';
+import { SHARED_CONTEXT_KEY } from './tool-types.js';
+//#endregion
+//#region ToolContextStore
+/**
+ * Mutable context store shared across all tool executions within a callModel invocation.
+ * Stores context keyed by tool name: `{ get_weather: { apiKey: '...' }, db_query: { dbUrl: '...' } }`.
+ * Notifies listeners on changes.
+ */
+export class ToolContextStore {
+    constructor(initialValues = {}) {
+        this.listeners = new Set();
+        this.store = {};
+        for (const [key, value] of Object.entries(initialValues)) {
+            this.store[key] = { ...value };
+        }
+    }
+    /** Subscribe to context changes. Returns an unsubscribe function. */
+    subscribe(listener) {
+        this.listeners.add(listener);
+        return () => {
+            this.listeners.delete(listener);
+        };
+    }
+    /** Get a deep-shallow copy of the full context (all tools) */
+    getSnapshot() {
+        const snapshot = {};
+        for (const [key, value] of Object.entries(this.store)) {
+            snapshot[key] = { ...value };
+        }
+        return snapshot;
+    }
+    /** Get a shallow copy of context for a specific tool */
+    getToolContext(toolName) {
+        const data = this.store[toolName];
+        if (!data) {
+            return {};
+        }
+        return { ...data };
+    }
+    /** Set context for a specific tool and notify listeners */
+    setToolContext(toolName, values) {
+        this.store[toolName] = { ...values };
+        this.notifyListeners();
+    }
+    /** Merge partial values into a specific tool's context and notify listeners */
+    mergeToolContext(toolName, partial) {
+        const existing = this.store[toolName] ?? {};
+        this.store[toolName] = { ...existing, ...partial };
+        this.notifyListeners();
+    }
+    notifyListeners() {
+        const snapshot = {};
+        for (const [key, value] of Object.entries(this.store)) {
+            snapshot[key] = { ...value };
+        }
+        for (const listener of this.listeners) {
+            listener(snapshot);
+        }
+    }
+}
+//#endregion
+//#region buildToolExecuteContext
+/**
+ * Validate a partial update against a schema's shape, filtering to known keys
+ * and validating each key individually. Returns the filtered partial.
+ */
+function validatePartialAgainstSchema(partial, schema) {
+    const schemaKeys = Object.keys(schema._zod.def.shape);
+    const filteredPartial = {};
+    for (const [key, value] of Object.entries(partial)) {
+        if (schemaKeys.includes(key)) {
+            filteredPartial[key] = value;
+        }
+    }
+    const shape = schema._zod.def.shape;
+    for (const [key, value] of Object.entries(filteredPartial)) {
+        const keySchema = shape[key];
+        if (keySchema) {
+            z4.parse(keySchema, value);
+        }
+    }
+    return filteredPartial;
+}
+/**
+ * Build a flat ToolExecuteContext for a specific tool.
+ * Returns a merged object with TurnContext fields, a `local` getter
+ * (reads from the store on each access), `shared` getter, and mutation methods.
+ *
+ * The `local` and `shared` getters are live — calling `setContext()` or
+ * `setSharedContext()` and then reading the property reflects updated values immediately.
+ *
+ * @param turnContext - The current turn context
+ * @param store - The shared context store (keyed by tool name)
+ * @param toolName - The tool's name
+ * @param schema - The tool's contextSchema (for validation)
+ * @param sharedSchema - The shared contextSchema (for validation)
+ * @returns A flat ToolExecuteContext
+ */
+export function buildToolExecuteContext(turnContext, store, toolName, schema, sharedSchema) {
+    // Validate initial context eagerly (throws on bad data)
+    if (store && schema) {
+        extractToolContext(store, toolName, schema);
+    }
+    if (store && sharedSchema) {
+        extractToolContext(store, SHARED_CONTEXT_KEY, sharedSchema);
+    }
+    const ctx = {
+        ...turnContext,
+        get local() {
+            const data = store ? store.getToolContext(toolName) : {};
+            return Object.freeze(data);
+        },
+        setContext(partial) {
+            if (!store || !schema) {
+                return;
+            }
+            const filteredPartial = validatePartialAgainstSchema(partial, schema);
+            store.mergeToolContext(toolName, filteredPartial);
+        },
+        get shared() {
+            const data = store ? store.getToolContext(SHARED_CONTEXT_KEY) : {};
+            return Object.freeze(data);
+        },
+        setSharedContext(partial) {
+            if (!store || !sharedSchema) {
+                return;
+            }
+            const filteredPartial = validatePartialAgainstSchema(partial, sharedSchema);
+            store.mergeToolContext(SHARED_CONTEXT_KEY, filteredPartial);
+        },
+    };
+    return ctx;
+}
+//#endregion
+//#region resolveContext
+/**
+ * Resolve a context input (static value, sync function, or async function) to a plain object.
+ *
+ * @param contextInput - The context value or function from callModel
+ * @param turnContext - The current turn context for function resolution
+ * @returns The resolved context object (keyed by tool name)
+ */
+export async function resolveContext(contextInput, turnContext) {
+    if (contextInput === undefined) {
+        return {};
+    }
+    if (typeof contextInput === 'function') {
+        return Promise.resolve(contextInput(turnContext));
+    }
+    return contextInput;
+}
+//#endregion
+//#region extractToolContext
+/**
+ * Extract and validate context values for a specific tool from the context store.
+ * Returns a shallow copy so the caller cannot mutate the store directly.
+ *
+ * @param store - The shared context store (keyed by tool name)
+ * @param toolName - The tool's name
+ * @param schema - The tool's contextSchema
+ * @returns A shallow copy of the validated context values for this tool
+ */
+export function extractToolContext(store, toolName, schema) {
+    if (!schema) {
+        return {};
+    }
+    const toolData = store.getToolContext(toolName);
+    // Validate the extracted values against the schema
+    z4.parse(schema, toolData);
+    // getToolContext already returns a shallow copy
+    return toolData;
+}
+//#endregion
+//# sourceMappingURL=tool-context.js.map

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

@@ -1,6 +1,8 @@
 import type { $ZodType } from 'zod/v4/core';
-import type { APITool, Tool, ParsedToolCall, ToolExecutionResult, TurnContext } from './tool-types.js';
+import type { $ZodObject, $ZodShape } from 'zod/v4/core';
+import type { APITool, ParsedToolCall, Tool, ToolExecutionResult, TurnContext } from './tool-types.js';
 import * as z4 from 'zod/v4';
+import { type ToolContextStore } from './tool-context.js';
 export declare const ZodError: z4.z.core.$constructor<z4.ZodError<unknown>, z4.z.core.$ZodIssue[]>;
 /**
  * Recursively remove keys prefixed with ~ from an object.
@@ -36,25 +38,27 @@ export declare function validateToolInput<T>(schema: $ZodType<T>, args: unknown)
  */
 export declare function validateToolOutput<T>(schema: $ZodType<T>, result: unknown): T;
 /**
- * Parse tool call arguments from JSON string
+ * Parse tool call arguments from JSON string.
+ * Treats empty/whitespace-only strings as an empty object — some providers
+ * return `arguments: ""` for tools that take no parameters.
  */
 export declare function parseToolCallArguments(argumentsString: string): unknown;
 /**
  * Execute a regular (non-generator) tool
  */
-export declare function executeRegularTool(tool: Tool, toolCall: ParsedToolCall<Tool>, context: TurnContext): Promise<ToolExecutionResult<Tool>>;
+export declare function executeRegularTool(tool: Tool, toolCall: ParsedToolCall<Tool>, context: TurnContext, contextStore?: ToolContextStore, sharedSchema?: $ZodObject<$ZodShape>): 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<Tool>, context: TurnContext, onPreliminaryResult?: (toolCallId: string, result: unknown) => void): Promise<ToolExecutionResult<Tool>>;
+export declare function executeGeneratorTool(tool: Tool, toolCall: ParsedToolCall<Tool>, context: TurnContext, onPreliminaryResult?: (toolCallId: string, result: unknown) => void, contextStore?: ToolContextStore, sharedSchema?: $ZodObject<$ZodShape>): 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<Tool>, context: TurnContext, onPreliminaryResult?: (toolCallId: string, result: unknown) => void): Promise<ToolExecutionResult<Tool>>;
+export declare function executeTool(tool: Tool, toolCall: ParsedToolCall<Tool>, context: TurnContext, onPreliminaryResult?: (toolCallId: string, result: unknown) => void, contextStore?: ToolContextStore, sharedSchema?: $ZodObject<$ZodShape>): Promise<ToolExecutionResult<Tool>>;
 /**
  * Find a tool by name in the tools array
  */

package/esm/lib/tool-executor.js

@@ -1,5 +1,6 @@
 import * as z4 from 'zod/v4';
 import { hasExecuteFunction, isGeneratorTool, isRegularExecuteTool } from './tool-types.js';
+import { buildToolExecuteContext } from './tool-context.js';
 // Re-export ZodError for convenience
 export const ZodError = z4.ZodError;
 /**
@@ -96,30 +97,40 @@ function tryValidate(schema, value) {
     return result.success;
 }
 /**
- * Parse tool call arguments from JSON string
+ * Parse tool call arguments from JSON string.
+ * Treats empty/whitespace-only strings as an empty object — some providers
+ * return `arguments: ""` for tools that take no parameters.
  */
 export function parseToolCallArguments(argumentsString) {
+    const trimmed = argumentsString.trim();
+    if (!trimmed) {
+        return {};
+    }
     try {
-        return JSON.parse(argumentsString);
+        return JSON.parse(trimmed);
     }
     catch (error) {
         throw new Error(`Failed to parse tool call arguments: ${error instanceof Error ? error.message : String(error)}`);
     }
 }
+/**
+ * Build a ToolExecuteContext for a tool from a TurnContext and optional context store
+ */
+function buildExecuteCtx(tool, turnContext, contextStore, sharedSchema) {
+    return buildToolExecuteContext(turnContext, contextStore, tool.function.name, tool.function.contextSchema, sharedSchema);
+}
 /**
  * Execute a regular (non-generator) tool
  */
-export async function executeRegularTool(tool, toolCall, context) {
+export async function executeRegularTool(tool, toolCall, context, contextStore, sharedSchema) {
     if (!isRegularExecuteTool(tool)) {
         throw new Error(`Tool "${toolCall.name}" is not a regular execute tool or has no execute function`);
     }
     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);
+        const executeContext = buildExecuteCtx(tool, context, contextStore, sharedSchema);
         // Execute tool with context
-        const result = await Promise.resolve(tool.function.execute(validatedInput, context));
+        const result = await Promise.resolve(tool.function.execute(validatedInput, executeContext));
         // Validate output if schema is provided
         if (tool.function.outputSchema) {
             const validatedOutput = validateToolOutput(tool.function.outputSchema, result);
@@ -150,20 +161,19 @@ export async function executeRegularTool(tool, toolCall, context) {
  * - 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) {
+export async function executeGeneratorTool(tool, toolCall, context, onPreliminaryResult, contextStore, sharedSchema) {
     if (!isGeneratorTool(tool)) {
         throw new Error(`Tool "${toolCall.name}" is not a generator tool`);
     }
     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);
+        const executeContext = buildExecuteCtx(tool, context, contextStore, sharedSchema);
         const preliminaryResults = [];
-        let finalResult = undefined;
+        let finalResult;
         let hasFinalResult = false;
-        let lastEmittedValue = undefined;
+        let lastEmittedValue;
         let hasEmittedValue = false;
-        const iterator = tool.function.execute(validatedInput, context);
+        const iterator = tool.function.execute(validatedInput, executeContext);
         let iterResult = await iterator.next();
         while (!iterResult.done) {
             const event = iterResult.value;
@@ -214,14 +224,14 @@ export async function executeGeneratorTool(tool, toolCall, context, onPreliminar
  * Execute a tool call
  * Automatically detects if it's a regular or generator tool
  */
-export async function executeTool(tool, toolCall, context, onPreliminaryResult) {
+export async function executeTool(tool, toolCall, context, onPreliminaryResult, contextStore, sharedSchema) {
     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 executeGeneratorTool(tool, toolCall, context, onPreliminaryResult, contextStore, sharedSchema);
     }
-    return executeRegularTool(tool, toolCall, context);
+    return executeRegularTool(tool, toolCall, context, contextStore, sharedSchema);
 }
 /**
  * Find a tool by name in the tools array

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

@@ -10,10 +10,10 @@ export interface ToolExecutionOptions {
  * Result of the tool execution loop
  */
 export interface ToolOrchestrationResult {
-    finalResponse: models.OpenResponsesNonStreamingResponse;
-    allResponses: models.OpenResponsesNonStreamingResponse[];
+    finalResponse: models.OpenResponsesResult;
+    allResponses: models.OpenResponsesResult[];
     toolExecutionResults: ToolExecutionResult<Tool>[];
-    conversationInput: models.OpenResponsesInput;
+    conversationInput: models.InputsUnion;
 }
 /**
  * Execute tool calls and manage multi-turn conversations
@@ -27,7 +27,7 @@ export interface ToolOrchestrationResult {
  * @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, initialRequest: models.OpenResponsesRequest, tools: Tool[], apiTools: APITool[], options?: ToolExecutionOptions): Promise<ToolOrchestrationResult>;
+export declare function executeToolLoop(sendRequest: (input: models.InputsUnion, tools: APITool[]) => Promise<models.OpenResponsesResult>, initialInput: models.InputsUnion, initialRequest: models.ResponsesRequest, tools: Tool[], apiTools: APITool[], options?: ToolExecutionOptions): Promise<ToolOrchestrationResult>;
 /**
  * Convert tool execution results to a map for easy lookup
  */

package/esm/lib/tool-orchestrator.js

@@ -65,7 +65,7 @@ export async function executeToolLoop(sendRequest, initialInput, initialRequest,
             if (!rawToolCall) {
                 throw new Error(`Could not find raw tool call for ${toolCall.id}`);
             }
-            // Convert to OpenResponsesFunctionToolCall format
+            // Convert to FunctionCallItem format
             const openResponsesToolCall = {
                 type: 'function_call',
                 callId: rawToolCall.callId,