@openrouter/sdk 0.8.0 → 0.10.2

package/esm/lib/conversation-state.js

@@ -5,10 +5,11 @@ import { normalizeInputToArray } from './turn-context.js';
 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);
+    return ('callId' in obj &&
+        typeof obj.callId === 'string' &&
+        'name' in obj &&
+        typeof obj.name === 'string' &&
+        'output' in obj);
 }
 /**
  * Type guard to verify an object is a valid ParsedToolCall
@@ -16,10 +17,11 @@ function isValidUnsentToolResult(obj) {
 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);
+    return ('id' in obj &&
+        typeof obj.id === 'string' &&
+        'name' in obj &&
+        typeof obj.name === 'string' &&
+        'arguments' in obj);
 }
 /**
  * Generate a unique ID for a conversation
@@ -156,9 +158,9 @@ export function extractTextFromResponse(response) {
     const outputs = Array.isArray(response.output) ? response.output : [response.output];
     const textParts = [];
     for (const item of outputs) {
-        if (item.type === 'message' && item.content) {
+        if (item.type === 'message' && 'content' in item && item.content) {
             for (const content of item.content) {
-                if (content.type === 'output_text' && content.text) {
+                if (content.type === 'output_text' && 'text' in content && content.text) {
                     textParts.push(content.text);
                 }
             }
@@ -176,31 +178,32 @@ export function extractToolCallsFromResponse(response) {
     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;
+        if (item.type !== 'function_call' || !('arguments' in item)) {
+            continue;
+        }
+        let parsedArguments;
+        if (typeof item.arguments === 'string') {
+            try {
+                parsedArguments = JSON.parse(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}`);
+            catch (error) {
+                // Log warning and skip malformed tool call, similar to stream-transformers.ts
+                console.warn(`Failed to parse arguments for tool call "${'name' in item ? item.name : 'unknown'}": ${error instanceof Error ? error.message : String(error)}`);
+                continue;
             }
-            toolCalls.push(toolCall);
         }
+        else {
+            parsedArguments = item.arguments;
+        }
+        const toolCall = {
+            id: ('callId' in item ? item.callId : undefined) ?? item.id ?? '',
+            name: ('name' in item ? item.name : undefined) ?? '',
+            arguments: parsedArguments,
+        };
+        if (!isValidParsedToolCall(toolCall)) {
+            throw new Error(`Invalid tool call structure for tool: ${toolCall.name}`);
+        }
+        toolCalls.push(toolCall);
     }
     return toolCalls;
 }

package/esm/lib/env.d.ts

@@ -7,9 +7,13 @@ export interface Env {
      */
     OPENROUTER_HTTP_REFERER?: string | undefined;
     /**
-     * Sets the xTitle parameter for all supported operations
+     * Sets the appTitle parameter for all supported operations
      */
-    OPENROUTER_X_TITLE?: string | undefined;
+    OPENROUTER_APP_TITLE?: string | undefined;
+    /**
+     * Sets the appCategories parameter for all supported operations
+     */
+    OPENROUTER_APP_CATEGORIES?: string | undefined;
     OPENROUTER_DEBUG?: boolean | undefined;
 }
 export declare const envSchema: z.ZodType<Env, unknown>;

package/esm/lib/env.js

@@ -7,7 +7,8 @@ import { dlv } from "./dlv.js";
 export const envSchema = z.object({
     OPENROUTER_API_KEY: z.string().optional(),
     OPENROUTER_HTTP_REFERER: z.string().optional(),
-    OPENROUTER_X_TITLE: z.string().optional(),
+    OPENROUTER_APP_TITLE: z.string().optional(),
+    OPENROUTER_APP_CATEGORIES: z.string().optional(),
     OPENROUTER_DEBUG: z.coerce.boolean().optional(),
 });
 /**
@@ -53,8 +54,11 @@ export function fillGlobals(options) {
     if (typeof envVars.OPENROUTER_HTTP_REFERER !== "undefined") {
         clone.httpReferer ?? (clone.httpReferer = envVars.OPENROUTER_HTTP_REFERER);
     }
-    if (typeof envVars.OPENROUTER_X_TITLE !== "undefined") {
-        clone.xTitle ?? (clone.xTitle = envVars.OPENROUTER_X_TITLE);
+    if (typeof envVars.OPENROUTER_APP_TITLE !== "undefined") {
+        clone.appTitle ?? (clone.appTitle = envVars.OPENROUTER_APP_TITLE);
+    }
+    if (typeof envVars.OPENROUTER_APP_CATEGORIES !== "undefined") {
+        clone.appCategories ?? (clone.appCategories = envVars.OPENROUTER_APP_CATEGORIES);
     }
     return clone;
 }

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

@@ -2,15 +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 { ConversationState, ResponseStreamEvent, InferToolEventsUnion, InferToolOutputsUnion, ParsedToolCall, StateAccessor, StopWhen, Tool, ToolStreamEvent, TurnContext } from './tool-types.js';
+import type { $ZodObject, $ZodShape } from 'zod/v4/core';
+import type { ConversationState, ToolContextMapWithShared, ResponseStreamEvent, InferToolEventsUnion, InferToolOutputsUnion, ParsedToolCall, StateAccessor, StopWhen, Tool, ToolStreamEvent, TurnContext } from './tool-types.js';
+import { type ContextInput } from './tool-context.js';
 import { type StreamableOutputItem } from './stream-transformers.js';
-export interface GetResponseOptions<TTools extends readonly Tool[]> {
-    request: CallModelInput<TTools>;
+export interface GetResponseOptions<TTools extends readonly Tool[], TShared extends Record<string, unknown> = Record<string, never>> {
+    request: CallModelInput<TTools, TShared>;
     client: OpenRouterCore;
     options?: RequestOptions;
     tools?: TTools;
     stopWhen?: StopWhen<TTools>;
     state?: StateAccessor<TTools>;
+    /** Typed context data passed to tools via contextSchema. `shared` key for shared context. */
+    context?: ContextInput<ToolContextMapWithShared<TTools, TShared>>;
+    /** Zod schema for shared context validation */
+    sharedContextSchema?: $ZodObject<$ZodShape>;
     /**
      * Call-level approval check - overrides tool-level requireApproval setting
      * Receives the tool call and turn context, can be sync or async
@@ -18,6 +24,10 @@ export interface GetResponseOptions<TTools extends readonly Tool[]> {
     requireApproval?: (toolCall: ParsedToolCall<TTools[number]>, context: TurnContext) => boolean | Promise<boolean>;
     approveToolCalls?: string[];
     rejectToolCalls?: string[];
+    /** Callback invoked at the start of each tool execution turn */
+    onTurnStart?: (context: TurnContext) => void | Promise<void>;
+    /** Callback invoked at the end of each tool execution turn */
+    onTurnEnd?: (context: TurnContext, response: models.OpenResponsesNonStreamingResponse) => void | Promise<void>;
 }
 /**
  * A wrapper around a streaming response that provides multiple consumption patterns.
@@ -37,8 +47,9 @@ export interface GetResponseOptions<TTools extends readonly Tool[]> {
  * ReusableReadableStream implementation.
  *
  * @template TTools - The tools array type to enable typed tool calls and results
+ * @template TShared - The shape of the shared context (inferred from sharedContextSchema)
  */
-export declare class ModelResult<TTools extends readonly Tool[]> {
+export declare class ModelResult<TTools extends readonly Tool[], TShared extends Record<string, unknown> = Record<string, never>> {
     private reusableStream;
     private textPromise;
     private options;
@@ -54,13 +65,42 @@ export declare class ModelResult<TTools extends readonly Tool[]> {
     private approvedToolCalls;
     private rejectedToolCalls;
     private isResumingFromApproval;
-    constructor(options: GetResponseOptions<TTools>);
+    private turnBroadcaster;
+    private initialStreamPipeStarted;
+    private initialPipePromise;
+    private contextStore;
+    constructor(options: GetResponseOptions<TTools, TShared>);
     /**
-     * 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.
+     * Get or create the unified turn broadcaster (lazy initialization).
+     * Broadcasts all API stream events, tool events, and turn delimiters across turns.
      */
-    private ensureBroadcaster;
+    private ensureTurnBroadcaster;
+    /**
+     * Start piping the initial stream into the turn broadcaster.
+     * Idempotent — only starts once even if called multiple times.
+     * Wraps the initial stream events with turn.start(0) / turn.end(0) delimiters.
+     */
+    private startInitialStreamPipe;
+    /**
+     * Pipe a follow-up stream into the turn broadcaster and capture the completed response.
+     * Emits turn.start / turn.end delimiters around the stream events.
+     */
+    private pipeAndConsumeStream;
+    /**
+     * Push a tool result event to both the legacy tool event broadcaster
+     * and the unified turn broadcaster.
+     */
+    private broadcastToolResult;
+    /**
+     * Push a preliminary result event to both the legacy tool event broadcaster
+     * and the unified turn broadcaster.
+     */
+    private broadcastPreliminaryResult;
+    /**
+     * Set up the turn broadcaster with tool execution and return the consumer.
+     * Used by stream methods that need to iterate over all turns.
+     */
+    private startTurnBroadcasterExecution;
     /**
      * Type guard to check if a value is a non-streaming response
      * Only requires 'output' field and absence of 'toReadableStream' method
@@ -162,10 +202,11 @@ export declare class ModelResult<TTools extends readonly Tool[]> {
     private applyNextTurnParams;
     /**
      * Make a follow-up API request with tool results.
-     * Continues the conversation after tool execution.
+     * Uses streaming and pipes events through the turn broadcaster when available.
      *
      * @param currentResponse - The response that contained tool calls
      * @param toolResults - The results from executing those tools
+     * @param turnNumber - The turn number for this follow-up request
      * @returns The new response from the API
      */
     private makeFollowupRequest;
@@ -233,14 +274,15 @@ export declare class ModelResult<TTools extends readonly Tool[]> {
      */
     getResponse(): Promise<models.OpenResponsesNonStreamingResponse>;
     /**
-     * Stream all response events as they arrive.
+     * Stream all response events as they arrive across all turns.
      * Multiple consumers can iterate over this stream concurrently.
-     * Preliminary tool results and tool results are streamed in REAL-TIME as generator tools yield.
+     * Includes API events, tool events, and turn.start/turn.end delimiters.
      */
     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.
+     * Stream only text deltas as they arrive from all turns.
+     * This filters the full event stream to only yield text content,
+     * including text from follow-up responses in multi-turn tool loops.
      */
     getTextStream(): AsyncIterableIterator<string>;
     /**
@@ -271,12 +313,13 @@ export declare class ModelResult<TTools extends readonly Tool[]> {
      */
     getNewMessagesStream(): AsyncIterableIterator<models.ResponsesOutputMessage | models.OpenResponsesFunctionCallOutput | models.ResponsesOutputItemFunctionCall>;
     /**
-     * Stream only reasoning deltas as they arrive.
-     * This filters the full event stream to only yield reasoning content.
+     * Stream only reasoning deltas as they arrive from all turns.
+     * This filters the full event stream to only yield reasoning content,
+     * including reasoning from follow-up responses in multi-turn tool loops.
      */
     getReasoningStream(): AsyncIterableIterator<string>;
     /**
-     * Stream tool call argument deltas and preliminary results.
+     * Stream tool call argument deltas and preliminary results from all turns.
      * Preliminary results are streamed in REAL-TIME as generator tools yield.
      * - Tool call argument deltas as { type: "delta", content: string }
      * - Preliminary results as { type: "preliminary_result", toolCallId, result }
@@ -294,6 +337,19 @@ export declare class ModelResult<TTools extends readonly Tool[]> {
      * Each iteration yields a complete tool call with parsed arguments.
      */
     getToolCallsStream(): AsyncIterableIterator<ParsedToolCall<TTools[number]>>;
+    /**
+     * Returns an async iterable that emits a full context snapshot every time
+     * any tool calls ctx.update(). Can be consumed concurrently with getText(),
+     * getToolStream(), etc.
+     *
+     * @example
+     * ```typescript
+     * for await (const snapshot of result.getContextUpdates()) {
+     *   console.log('Context changed:', snapshot);
+     * }
+     * ```
+     */
+    getContextUpdates(): AsyncGenerator<ToolContextMapWithShared<TTools, TShared>>;
     /**
      * Cancel the underlying stream and all consumers
      */