@openrouter/sdk 0.9.11 → 0.10.2

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
      */