@openrouter/sdk 0.9.11 → 0.10.2

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

@@ -13,7 +13,7 @@ export interface ToolOrchestrationResult {
     finalResponse: models.OpenResponsesNonStreamingResponse;
     allResponses: models.OpenResponsesNonStreamingResponse[];
     toolExecutionResults: ToolExecutionResult<Tool>[];
-    conversationInput: models.OpenResponsesInput;
+    conversationInput: models.OpenResponsesInputUnion;
 }
 /**
  * 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.OpenResponsesInputUnion, tools: APITool[]) => Promise<models.OpenResponsesNonStreamingResponse>, initialInput: models.OpenResponsesInputUnion, initialRequest: models.OpenResponsesRequest, tools: Tool[], apiTools: APITool[], options?: ToolExecutionOptions): Promise<ToolOrchestrationResult>;
 /**
  * Convert tool execution results to a map for easy lookup
  */

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

@@ -20,6 +20,62 @@ export interface TurnContext {
     /** The full request being sent to the API (only available during tool execution) */
     turnRequest?: models.OpenResponsesRequest;
 }
+/**
+ * Extract context schema type from a tool definition
+ * Returns the inferred type of the tool's contextSchema, or empty object if none
+ */
+export type InferToolContext<T> = T extends {
+    function: {
+        contextSchema: infer S;
+    };
+} ? S extends $ZodType ? zodInfer<S> : Record<string, never> : Record<string, never>;
+/**
+ * Extract tool name from a tool definition
+ */
+type InferToolName<T> = T extends {
+    function: {
+        name: infer N extends string;
+    };
+} ? N : string;
+/**
+ * Flat execute context passed as the second argument to tool execute functions.
+ * Merges TurnContext fields with a `local` getter (own tool context) and `setContext()`.
+ *
+ * @template TName - The tool's literal name string
+ * @template TContext - The shape of the tool's contextSchema
+ * @template TShared - The shape of the sharedContextSchema
+ */
+export type ToolExecuteContext<TName extends string = string, TContext extends Record<string, unknown> = Record<string, unknown>, TShared extends Record<string, unknown> = Record<string, unknown>> = TurnContext & {
+    /** The tool's name (type-level only, for generic inference) */
+    readonly _toolName?: TName;
+    /** This tool's own context (reads from the store, frozen snapshot) */
+    local: Readonly<TContext>;
+    /** Mutate this tool's context in the shared store (persists across turns) */
+    setContext(partial: Partial<TContext>): void;
+    /** Shared context visible to all tools */
+    shared: Readonly<TShared>;
+    /** Mutate the shared context in the store (persists across turns) */
+    setSharedContext(partial: Partial<TShared>): void;
+};
+/**
+ * Context map keyed by tool name for callModel's `context` option.
+ * Each key is a tool's name, each value is that tool's inferred context type.
+ */
+export type ToolContextMap<T extends readonly Tool[]> = {
+    [K in T[number] as InferToolName<K>]: InferToolContext<K>;
+};
+/**
+ * Context map with an optional `shared` key for shared context.
+ * When TShared is provided (non-empty), a `shared` key is added to the map.
+ */
+export type ToolContextMapWithShared<T extends readonly Tool[], TShared extends Record<string, unknown> = Record<string, never>> = ToolContextMap<T> & (TShared extends Record<string, never> ? {} : {
+    shared: TShared;
+});
+/**
+ * Reserved key in the context store for shared context data.
+ * The tool name 'shared' is forbidden — it's reserved for this purpose.
+ */
+export declare const SHARED_CONTEXT_KEY: "shared";
 /**
  * Context passed to nextTurnParams functions
  * Contains current request state for parameter computation
@@ -27,7 +83,7 @@ export interface TurnContext {
  */
 export type NextTurnParamsContext = {
     /** Current input (messages) */
-    input: models.OpenResponsesInput;
+    input: models.OpenResponsesInputUnion;
     /** Current model selection */
     model: string;
     /** Current models array */
@@ -64,6 +120,8 @@ export interface BaseToolFunction<TInput extends $ZodObject<$ZodShape>> {
     name: string;
     description?: string;
     inputSchema: TInput;
+    /** Zod schema declaring the context data this tool needs */
+    contextSchema?: $ZodObject<$ZodShape>;
     nextTurnParams?: NextTurnParamsFunctions<zodInfer<TInput>>;
     /**
      * Whether this tool requires human approval before execution
@@ -73,10 +131,12 @@ export interface BaseToolFunction<TInput extends $ZodObject<$ZodShape>> {
 }
 /**
  * Regular tool with synchronous or asynchronous execute function and optional outputSchema
+ * @template TContext - Shape of the tool's context (inferred from contextSchema)
+ * @template TName - The tool's literal name string
  */
-export interface ToolFunctionWithExecute<TInput extends $ZodObject<$ZodShape>, TOutput extends $ZodType = $ZodType<unknown>> extends BaseToolFunction<TInput> {
+export interface ToolFunctionWithExecute<TInput extends $ZodObject<$ZodShape>, TOutput extends $ZodType = $ZodType<unknown>, TContext extends Record<string, unknown> = Record<string, unknown>, TName extends string = string> extends BaseToolFunction<TInput> {
     outputSchema?: TOutput;
-    execute: (params: zodInfer<TInput>, context?: TurnContext) => Promise<zodInfer<TOutput>> | zodInfer<TOutput>;
+    execute: (params: zodInfer<TInput>, context?: ToolExecuteContext<TName, TContext>) => Promise<zodInfer<TOutput>> | zodInfer<TOutput>;
 }
 /**
  * Generator-based tool with async generator execute function
@@ -100,10 +160,10 @@ export interface ToolFunctionWithExecute<TInput extends $ZodObject<$ZodShape>, T
  * }
  * ```
  */
-export interface ToolFunctionWithGenerator<TInput extends $ZodObject<$ZodShape>, TEvent extends $ZodType = $ZodType<unknown>, TOutput extends $ZodType = $ZodType<unknown>> extends BaseToolFunction<TInput> {
+export interface ToolFunctionWithGenerator<TInput extends $ZodObject<$ZodShape>, TEvent extends $ZodType = $ZodType<unknown>, TOutput extends $ZodType = $ZodType<unknown>, TContext extends Record<string, unknown> = Record<string, unknown>, TName extends string = string> extends BaseToolFunction<TInput> {
     eventSchema: TEvent;
     outputSchema: TOutput;
-    execute: (params: zodInfer<TInput>, context?: TurnContext) => AsyncGenerator<zodInfer<TEvent> | zodInfer<TOutput>, zodInfer<TOutput> | void>;
+    execute: (params: zodInfer<TInput>, context?: ToolExecuteContext<TName, TContext>) => AsyncGenerator<zodInfer<TEvent> | zodInfer<TOutput>, zodInfer<TOutput> | void>;
 }
 /**
  * Manual tool without execute function - requires manual handling by developer
@@ -114,16 +174,16 @@ export interface ManualToolFunction<TInput extends $ZodObject<$ZodShape>, TOutpu
 /**
  * Tool with execute function (regular or generator)
  */
-export type ToolWithExecute<TInput extends $ZodObject<$ZodShape> = $ZodObject<$ZodShape>, TOutput extends $ZodType = $ZodType<unknown>> = {
+export type ToolWithExecute<TInput extends $ZodObject<$ZodShape> = $ZodObject<$ZodShape>, TOutput extends $ZodType = $ZodType<unknown>, TContext extends Record<string, unknown> = Record<string, unknown>> = {
     type: ToolType.Function;
-    function: ToolFunctionWithExecute<TInput, TOutput>;
+    function: ToolFunctionWithExecute<TInput, TOutput, TContext>;
 };
 /**
  * Tool with generator execute function
  */
-export type ToolWithGenerator<TInput extends $ZodObject<$ZodShape> = $ZodObject<$ZodShape>, TEvent extends $ZodType = $ZodType<unknown>, TOutput extends $ZodType = $ZodType<unknown>> = {
+export type ToolWithGenerator<TInput extends $ZodObject<$ZodShape> = $ZodObject<$ZodShape>, TEvent extends $ZodType = $ZodType<unknown>, TOutput extends $ZodType = $ZodType<unknown>, TContext extends Record<string, unknown> = Record<string, unknown>> = {
     type: ToolType.Function;
-    function: ToolFunctionWithGenerator<TInput, TEvent, TOutput>;
+    function: ToolFunctionWithGenerator<TInput, TEvent, TOutput, TContext>;
 };
 /**
  * Tool without execute function (manual handling)
@@ -235,8 +295,8 @@ export interface ParsedToolCall<T extends Tool> {
 export interface ToolExecutionResult<T extends Tool> {
     toolCallId: string;
     toolName: string;
-    result: T extends ToolWithExecute<any, infer O> | ToolWithGenerator<any, any, infer O> ? zodInfer<O> : unknown;
-    preliminaryResults?: T extends ToolWithGenerator<any, infer E, any> ? zodInfer<E>[] : undefined;
+    result: T extends ToolWithExecute<$ZodObject<$ZodShape>, infer O> | ToolWithGenerator<$ZodObject<$ZodShape>, $ZodType<unknown>, infer O> ? zodInfer<O> : unknown;
+    preliminaryResults?: T extends ToolWithGenerator<$ZodObject<$ZodShape>, infer E> ? zodInfer<E>[] : undefined;
     error?: Error;
 }
 /**
@@ -321,13 +381,31 @@ export type ToolResultEvent<TResult = unknown, TPreliminaryResults = unknown> =
     timestamp: number;
     preliminaryResults?: TPreliminaryResults[];
 };
+/**
+ * Turn start event emitted at the beginning of each API turn
+ * Turn 0 is the initial request, subsequent turns follow tool execution
+ */
+export type TurnStartEvent = {
+    type: 'turn.start';
+    turnNumber: number;
+    timestamp: number;
+};
+/**
+ * Turn end event emitted at the end of each API turn
+ */
+export type TurnEndEvent = {
+    type: 'turn.end';
+    turnNumber: number;
+    timestamp: number;
+};
 /**
  * Enhanced stream event types for getFullResponsesStream
- * Extends OpenResponsesStreamEvent with tool preliminary results and tool results
+ * Extends OpenResponsesStreamEvent with tool preliminary results, tool results,
+ * and turn delimiter events for multi-turn streaming
  * @template TEvent - The event type from generator tools
  * @template TResult - The result type from tool execution
  */
-export type ResponseStreamEvent<TEvent = unknown, TResult = unknown> = OpenResponsesStreamEvent | ToolPreliminaryResultEvent<TEvent> | ToolResultEvent<TResult, TEvent>;
+export type ResponseStreamEvent<TEvent = unknown, TResult = unknown> = OpenResponsesStreamEvent | ToolPreliminaryResultEvent<TEvent> | ToolResultEvent<TResult, TEvent> | TurnStartEvent | TurnEndEvent;
 /**
  * Type guard to check if an event is a tool preliminary result event
  */
@@ -336,6 +414,14 @@ export declare function isToolPreliminaryResultEvent<TEvent = unknown>(event: Re
  * Type guard to check if an event is a tool result event
  */
 export declare function isToolResultEvent<TResult = unknown, TPreliminaryResults = unknown>(event: ResponseStreamEvent<TPreliminaryResults, TResult>): event is ToolResultEvent<TResult, TPreliminaryResults>;
+/**
+ * Type guard to check if an event is a turn start event
+ */
+export declare function isTurnStartEvent(event: ResponseStreamEvent): event is TurnStartEvent;
+/**
+ * Type guard to check if an event is a turn end event
+ */
+export declare function isTurnEndEvent(event: ResponseStreamEvent): event is TurnEndEvent;
 /**
  * Tool stream event types for getToolStream
  * Includes both argument deltas and preliminary results
@@ -405,7 +491,7 @@ export interface ConversationState<TTools extends readonly Tool[] = readonly Too
     /** Unique identifier for this conversation */
     id: string;
     /** Full message history */
-    messages: models.OpenResponsesInput;
+    messages: models.OpenResponsesInputUnion;
     /** Previous response ID for chaining (OpenRouter server-side optimization) */
     previousResponseId?: string;
     /** Tool calls awaiting human approval */
@@ -465,4 +551,5 @@ export declare function toolHasApprovalConfigured(tool: Tool): boolean;
  * Type guard to check if any tools in array have approval configured at runtime
  */
 export declare function hasApprovalRequiredTools(tools: readonly Tool[]): boolean;
+export {};
 //# sourceMappingURL=tool-types.d.ts.map

package/esm/lib/tool-types.js

@@ -5,6 +5,11 @@ export var ToolType;
 (function (ToolType) {
     ToolType["Function"] = "function";
 })(ToolType || (ToolType = {}));
+/**
+ * Reserved key in the context store for shared context data.
+ * The tool name 'shared' is forbidden — it's reserved for this purpose.
+ */
+export const SHARED_CONTEXT_KEY = 'shared';
 /**
  * Type guard to check if a tool has an execute function
  */
@@ -41,6 +46,18 @@ export function isToolPreliminaryResultEvent(event) {
 export function isToolResultEvent(event) {
     return event.type === 'tool.result';
 }
+/**
+ * Type guard to check if an event is a turn start event
+ */
+export function isTurnStartEvent(event) {
+    return event.type === 'turn.start';
+}
+/**
+ * Type guard to check if an event is a turn end event
+ */
+export function isTurnEndEvent(event) {
+    return event.type === 'turn.end';
+}
 /**
  * Type guard to check if a tool has approval configured at runtime
  */

package/esm/lib/tool.d.ts

@@ -1,55 +1,49 @@
 import type { $ZodObject, $ZodShape, $ZodType, infer as zodInfer } from 'zod/v4/core';
-import { type TurnContext, type ToolWithExecute, type ToolWithGenerator, type ManualTool, type NextTurnParamsFunctions, type ToolApprovalCheck } from "./tool-types.js";
+import { type Tool, type ToolExecuteContext, type ToolWithExecute, type ToolWithGenerator, type ManualTool, type NextTurnParamsFunctions, type ToolApprovalCheck } from "./tool-types.js";
 /**
  * Configuration for a regular tool with outputSchema
  */
-type RegularToolConfigWithOutput<TInput extends $ZodObject<$ZodShape>, TOutput extends $ZodType> = {
-    name: string;
+type RegularToolConfigWithOutput<TInput extends $ZodObject<$ZodShape>, TOutput extends $ZodType, TContext extends Record<string, unknown> = Record<string, unknown>, TName extends string = string> = {
+    name: TName;
     description?: string;
     inputSchema: TInput;
     outputSchema: TOutput;
     eventSchema?: undefined;
+    /** Zod schema declaring the context data this tool needs */
+    contextSchema?: $ZodObject<$ZodShape>;
     nextTurnParams?: NextTurnParamsFunctions<zodInfer<TInput>>;
-    /**
-     * Whether this tool requires human approval before execution
-     * Can be a boolean or an async function that receives the tool's input params and context
-     */
     requireApproval?: boolean | ToolApprovalCheck<zodInfer<TInput>>;
-    execute: (params: zodInfer<TInput>, context?: TurnContext) => Promise<zodInfer<TOutput>> | zodInfer<TOutput>;
+    execute: (params: zodInfer<TInput>, context?: ToolExecuteContext<TName, TContext>) => Promise<zodInfer<TOutput>> | zodInfer<TOutput>;
 };
 /**
  * Configuration for a regular tool without outputSchema (infers return type from execute)
  */
-type RegularToolConfigWithoutOutput<TInput extends $ZodObject<$ZodShape>, TReturn> = {
-    name: string;
+type RegularToolConfigWithoutOutput<TInput extends $ZodObject<$ZodShape>, TReturn, TContext extends Record<string, unknown> = Record<string, unknown>, TName extends string = string> = {
+    name: TName;
     description?: string;
     inputSchema: TInput;
     outputSchema?: undefined;
     eventSchema?: undefined;
+    /** Zod schema declaring the context data this tool needs */
+    contextSchema?: $ZodObject<$ZodShape>;
     nextTurnParams?: NextTurnParamsFunctions<zodInfer<TInput>>;
-    /**
-     * Whether this tool requires human approval before execution
-     * Can be a boolean or an async function that receives the tool's input params and context
-     */
     requireApproval?: boolean | ToolApprovalCheck<zodInfer<TInput>>;
-    execute: (params: zodInfer<TInput>, context?: TurnContext) => Promise<TReturn> | TReturn;
+    execute: (params: zodInfer<TInput>, context?: ToolExecuteContext<TName, TContext>) => Promise<TReturn> | TReturn;
 };
 /**
  * Configuration for a generator tool (with eventSchema)
  */
-type GeneratorToolConfig<TInput extends $ZodObject<$ZodShape>, TEvent extends $ZodType, TOutput extends $ZodType> = {
-    name: string;
+type GeneratorToolConfig<TInput extends $ZodObject<$ZodShape>, TEvent extends $ZodType, TOutput extends $ZodType, TContext extends Record<string, unknown> = Record<string, unknown>, TName extends string = string> = {
+    name: TName;
     description?: string;
     inputSchema: TInput;
     eventSchema: TEvent;
     outputSchema: TOutput;
+    /** Zod schema declaring the context data this tool needs */
+    contextSchema?: $ZodObject<$ZodShape>;
     nextTurnParams?: NextTurnParamsFunctions<zodInfer<TInput>>;
-    /**
-     * Whether this tool requires human approval before execution
-     * Can be a boolean or an async function that receives the tool's input params and context
-     */
     requireApproval?: boolean | ToolApprovalCheck<zodInfer<TInput>>;
-    execute: (params: zodInfer<TInput>, context?: TurnContext) => AsyncGenerator<zodInfer<TEvent> | zodInfer<TOutput>>;
+    execute: (params: zodInfer<TInput>, context?: ToolExecuteContext<TName, TContext>) => AsyncGenerator<zodInfer<TEvent> | zodInfer<TOutput>>;
 };
 /**
  * Configuration for a manual tool (execute: false, no eventSchema or outputSchema)
@@ -58,14 +52,27 @@ type ManualToolConfig<TInput extends $ZodObject<$ZodShape>> = {
     name: string;
     description?: string;
     inputSchema: TInput;
+    /** Zod schema declaring the context data this tool needs */
+    contextSchema?: $ZodObject<$ZodShape>;
     nextTurnParams?: NextTurnParamsFunctions<zodInfer<TInput>>;
-    /**
-     * Whether this tool requires human approval before execution
-     * Can be a boolean or an async function that receives the tool's input params and context
-     */
     requireApproval?: boolean | ToolApprovalCheck<zodInfer<TInput>>;
     execute: false;
 };
+/**
+ * Loose config type for the `tool<TShared>()` overload.
+ * Accepts any valid tool config while typing `ctx.shared` from TShared.
+ */
+type ToolConfigWithSharedContext<TShared extends Record<string, unknown>> = {
+    name: string;
+    description?: string;
+    inputSchema: $ZodObject<$ZodShape>;
+    outputSchema?: $ZodType;
+    eventSchema?: $ZodType;
+    contextSchema?: $ZodObject<$ZodShape>;
+    nextTurnParams?: NextTurnParamsFunctions<Record<string, unknown>>;
+    requireApproval?: boolean | ToolApprovalCheck<Record<string, unknown>>;
+    execute: ((params: Record<string, unknown>, context?: ToolExecuteContext<string, Record<string, unknown>, TShared>) => unknown) | ((params: Record<string, unknown>, context?: ToolExecuteContext<string, Record<string, unknown>, TShared>) => AsyncGenerator<unknown>) | false;
+};
 /**
  * Creates a tool with full type inference from Zod schemas.
  *
@@ -74,46 +81,28 @@ type ManualToolConfig<TInput extends $ZodObject<$ZodShape>> = {
  * - **Regular tool**: When `execute` is a function (no `eventSchema`)
  * - **Manual tool**: When `execute: false` is set
  *
- * @example Regular tool:
- * ```typescript
- * const weatherTool = tool({
- *   name: "get_weather",
- *   description: "Get weather for a location",
- *   inputSchema: z.object({ location: z.string() }),
- *   outputSchema: z.object({ temperature: z.number() }),
- *   execute: async (params) => {
- *     // params is typed as { location: string }
- *     return { temperature: 72 }; // return type is enforced
- *   },
- * });
- * ```
+ * Shared context typing: Pass a type parameter to type `ctx.shared`
+ * in the execute callback. Runtime validation happens at callModel
+ * via `sharedContextSchema`.
  *
- * @example Generator tool (with eventSchema):
+ * @example Regular tool with typed shared context:
  * ```typescript
- * const progressTool = tool({
- *   name: "process_data",
- *   inputSchema: z.object({ data: z.string() }),
- *   eventSchema: z.object({ progress: z.number() }),
- *   outputSchema: z.object({ result: z.string() }),
- *   execute: async function* (params) {
- *     yield { progress: 50 }; // typed as event
- *     yield { result: "done" }; // typed as output
- *   },
- * });
- * ```
+ * type SharedCtx = z.infer<typeof SharedContextSchema>;
  *
- * @example Manual tool (execute: false):
- * ```typescript
- * const manualTool = tool({
- *   name: "external_action",
- *   inputSchema: z.object({ action: z.string() }),
- *   execute: false,
+ * const execTool = tool<SharedCtx>({
+ *   name: "sandbox_exec",
+ *   inputSchema: z.object({ command: z.string() }),
+ *   execute: async (params, ctx) => {
+ *     ctx?.shared._sessionId;       // string | undefined
+ *     return { output: '...' };
+ *   },
  * });
  * ```
  */
-export declare function tool<TInput extends $ZodObject<$ZodShape>, TEvent extends $ZodType, TOutput extends $ZodType>(config: GeneratorToolConfig<TInput, TEvent, TOutput>): ToolWithGenerator<TInput, TEvent, TOutput>;
+export declare function tool<TInput extends $ZodObject<$ZodShape>, TEvent extends $ZodType, TOutput extends $ZodType, TContext extends Record<string, unknown> = Record<string, unknown>, TName extends string = string>(config: GeneratorToolConfig<TInput, TEvent, TOutput, TContext, TName>): ToolWithGenerator<TInput, TEvent, TOutput, TContext>;
 export declare function tool<TInput extends $ZodObject<$ZodShape>>(config: ManualToolConfig<TInput>): ManualTool<TInput>;
-export declare function tool<TInput extends $ZodObject<$ZodShape>, TOutput extends $ZodType>(config: RegularToolConfigWithOutput<TInput, TOutput>): ToolWithExecute<TInput, TOutput>;
-export declare function tool<TInput extends $ZodObject<$ZodShape>, TReturn>(config: RegularToolConfigWithoutOutput<TInput, TReturn>): ToolWithExecute<TInput, $ZodType<TReturn>>;
+export declare function tool<TInput extends $ZodObject<$ZodShape>, TOutput extends $ZodType, TContext extends Record<string, unknown> = Record<string, unknown>, TName extends string = string>(config: RegularToolConfigWithOutput<TInput, TOutput, TContext, TName>): ToolWithExecute<TInput, TOutput, TContext>;
+export declare function tool<TInput extends $ZodObject<$ZodShape>, TReturn, TContext extends Record<string, unknown> = Record<string, unknown>, TName extends string = string>(config: RegularToolConfigWithoutOutput<TInput, TReturn, TContext, TName>): ToolWithExecute<TInput, $ZodType<TReturn>, TContext>;
+export declare function tool<TShared extends Record<string, unknown>>(config: ToolConfigWithSharedContext<TShared>): Tool;
 export {};
 //# sourceMappingURL=tool.d.ts.map

package/esm/lib/tool.js

@@ -1,20 +1,12 @@
-import { ToolType, } from "./tool-types.js";
-/**
- * Type guard to check if config is a generator tool config (has eventSchema)
- */
-function isGeneratorConfig(config) {
-    return "eventSchema" in config && config.eventSchema !== undefined;
-}
-/**
- * Type guard to check if config is a manual tool config (execute === false)
- */
-function isManualConfig(config) {
-    return config.execute === false;
-}
+import { ToolType, SHARED_CONTEXT_KEY, } from "./tool-types.js";
 // Implementation
 export function tool(config) {
+    // 'shared' is reserved for shared context — forbid it as a tool name
+    if (config.name === SHARED_CONTEXT_KEY) {
+        throw new Error(`Tool name "${SHARED_CONTEXT_KEY}" is reserved for shared context. Choose a different name.`);
+    }
     // Check for manual tool first (execute === false)
-    if (isManualConfig(config)) {
+    if (config.execute === false) {
         const fn = {
             name: config.name,
             inputSchema: config.inputSchema,
@@ -22,6 +14,9 @@ export function tool(config) {
         if (config.description !== undefined) {
             fn.description = config.description;
         }
+        if (config.contextSchema !== undefined) {
+            fn.contextSchema = config.contextSchema;
+        }
         if (config.nextTurnParams !== undefined) {
             fn.nextTurnParams = config.nextTurnParams;
         }
@@ -34,18 +29,20 @@ export function tool(config) {
         };
     }
     // Check for generator tool (has eventSchema)
-    if (isGeneratorConfig(config)) {
+    if ('eventSchema' in config && config.eventSchema !== undefined) {
         const fn = {
             name: config.name,
             inputSchema: config.inputSchema,
             eventSchema: config.eventSchema,
             outputSchema: config.outputSchema,
-            // Types now align - config.execute matches the interface type
             execute: config.execute,
         };
         if (config.description !== undefined) {
             fn.description = config.description;
         }
+        if (config.contextSchema !== undefined) {
+            fn.contextSchema = config.contextSchema;
+        }
         if (config.nextTurnParams !== undefined) {
             fn.nextTurnParams = config.nextTurnParams;
         }
@@ -58,21 +55,20 @@ export function tool(config) {
         };
     }
     // Regular tool (has execute function, no eventSchema)
-    // TypeScript can't infer the relationship between TReturn and TOutput
-    // So we build the object without type annotation, then return with correct type
     const functionObj = {
         name: config.name,
         inputSchema: config.inputSchema,
         execute: config.execute,
         ...(config.description !== undefined && { description: config.description }),
         ...(config.outputSchema !== undefined && { outputSchema: config.outputSchema }),
+        ...(config.contextSchema !== undefined && { contextSchema: config.contextSchema }),
         ...(config.nextTurnParams !== undefined && { nextTurnParams: config.nextTurnParams }),
         ...(config.requireApproval !== undefined && { requireApproval: config.requireApproval }),
     };
-    // The function signature guarantees this is type-safe via overloads
     return {
         type: ToolType.Function,
         function: functionObj,
     };
 }
+//#endregion
 //# sourceMappingURL=tool.js.map

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

@@ -46,5 +46,5 @@ export declare function buildTurnContext(options: BuildTurnContextOptions): Turn
  * // Returns: [{ role: "user", content: "Hello!" }]
  * ```
  */
-export declare function normalizeInputToArray(input: models.OpenResponsesInput): Array<models.OpenResponsesInput1>;
+export declare function normalizeInputToArray(input: models.OpenResponsesInputUnion): Array<models.OpenResponsesInputUnion1>;
 //# sourceMappingURL=turn-context.d.ts.map

package/esm/models/assistantmessage.d.ts

@@ -2,6 +2,7 @@ import * as z from "zod/v4";
 import { ClosedEnum } from "../types/enums.js";
 import { Result as SafeParseResult } from "../types/fp.js";
 import { AssistantMessageImages, AssistantMessageImages$Outbound } from "./assistantmessageimages.js";
+import { ChatCompletionAudioOutput, ChatCompletionAudioOutput$Outbound } from "./chatcompletionaudiooutput.js";
 import { ChatMessageContentItem, ChatMessageContentItem$Outbound } from "./chatmessagecontentitem.js";
 import { ChatMessageToolCall, ChatMessageToolCall$Outbound } from "./chatmessagetoolcall.js";
 import { SDKValidationError } from "./errors/sdkvalidationerror.js";
@@ -47,6 +48,10 @@ export type AssistantMessage = {
      * Generated images from image generation models
      */
     images?: Array<AssistantMessageImages> | undefined;
+    /**
+     * Audio output data or reference
+     */
+    audio?: ChatCompletionAudioOutput | undefined;
 };
 /** @internal */
 export declare const AssistantMessageRole$inboundSchema: z.ZodEnum<typeof AssistantMessageRole>;
@@ -72,6 +77,7 @@ export type AssistantMessage$Outbound = {
     reasoning?: string | null | undefined;
     reasoning_details?: Array<ReasoningDetailUnion$Outbound> | undefined;
     images?: Array<AssistantMessageImages$Outbound> | undefined;
+    audio?: ChatCompletionAudioOutput$Outbound | undefined;
 };
 /** @internal */
 export declare const AssistantMessage$outboundSchema: z.ZodType<AssistantMessage$Outbound, AssistantMessage>;