@openrouter/sdk 0.9.11 → 0.11.2

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

@@ -1,6 +1,6 @@
 import type { $ZodObject, $ZodShape, $ZodType, infer as zodInfer } from 'zod/v4/core';
 import type * as models from '../models/index.js';
-import type { OpenResponsesStreamEvent } from '../models/index.js';
+import type { StreamEvents } from '../models/index.js';
 import type { ModelResult } from './model-result.js';
 /**
  * Tool type enum for enhanced tools
@@ -14,12 +14,68 @@ export declare enum ToolType {
  */
 export interface TurnContext {
     /** The specific tool call being executed (only available during tool execution) */
-    toolCall?: models.OpenResponsesFunctionToolCall;
+    toolCall?: models.FunctionCallItem;
     /** Number of tool execution turns so far (1-indexed: first turn = 1, 0 = initial request) */
     numberOfTurns: number;
     /** The full request being sent to the API (only available during tool execution) */
-    turnRequest?: models.OpenResponsesRequest;
+    turnRequest?: models.ResponsesRequest;
 }
+/**
+ * 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.InputsUnion;
     /** 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;
 }
 /**
@@ -255,8 +315,8 @@ export interface StepResult<TTools extends readonly Tool[] = readonly Tool[]> {
     readonly text: string;
     readonly toolCalls: TypedToolCallUnion<TTools>[];
     readonly toolResults: ToolExecutionResultUnion<TTools>[];
-    readonly response: models.OpenResponsesNonStreamingResponse;
-    readonly usage?: models.OpenResponsesUsage | null | undefined;
+    readonly response: models.OpenResponsesResult;
+    readonly usage?: models.Usage | null | undefined;
     readonly finishReason?: string | undefined;
     readonly warnings?: Warning[] | undefined;
     readonly experimental_providerMetadata?: Record<string, unknown> | undefined;
@@ -287,7 +347,7 @@ export interface ExecuteToolsResult<TTools extends readonly Tool[]> {
 }
 /**
  * Standard tool format for OpenRouter API (JSON Schema based)
- * Matches OpenResponsesRequestToolFunction structure
+ * Matches ResponsesRequestToolFunction structure
  */
 export interface APITool {
     type: 'function';
@@ -321,13 +381,41 @@ export type ToolResultEvent<TResult = unknown, TPreliminaryResults = unknown> =
     timestamp: number;
     preliminaryResults?: TPreliminaryResults[];
 };
+/**
+ * Tool call output event carrying the fully-formed FunctionCallOutputItem.
+ * Broadcast by executeToolRound so passive consumers (getItemsStream) can yield
+ * tool results in real-time without owning tool execution.
+ */
+export type ToolCallOutputEvent = {
+    type: 'tool.call_output';
+    output: models.FunctionCallOutputItem;
+    timestamp: number;
+};
+/**
+ * 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 StreamEvents 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> = StreamEvents | ToolPreliminaryResultEvent<TEvent> | ToolResultEvent<TResult, TEvent> | ToolCallOutputEvent | TurnStartEvent | TurnEndEvent;
 /**
  * Type guard to check if an event is a tool preliminary result event
  */
@@ -336,6 +424,18 @@ 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 tool call output event
+ */
+export declare function isToolCallOutputEvent(event: ResponseStreamEvent): event is ToolCallOutputEvent;
+/**
+ * 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
@@ -359,14 +459,14 @@ export type ChatStreamEvent<TEvent = unknown> = {
     delta: string;
 } | {
     type: 'message.complete';
-    response: models.OpenResponsesNonStreamingResponse;
+    response: models.OpenResponsesResult;
 } | {
     type: 'tool.preliminary_result';
     toolCallId: string;
     result: TEvent;
 } | {
     type: string;
-    event: OpenResponsesStreamEvent;
+    event: StreamEvents;
 };
 /**
  * Result of a tool execution that hasn't been sent to the model yet
@@ -405,7 +505,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.InputsUnion;
     /** Previous response ID for chaining (OpenRouter server-side optimization) */
     previousResponseId?: string;
     /** Tool calls awaiting human approval */
@@ -465,4 +565,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,24 @@ export function isToolPreliminaryResultEvent(event) {
 export function isToolResultEvent(event) {
     return event.type === 'tool.result';
 }
+/**
+ * Type guard to check if an event is a tool call output event
+ */
+export function isToolCallOutputEvent(event) {
+    return event.type === 'tool.call_output';
+}
+/**
+ * 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

@@ -7,9 +7,9 @@ export interface BuildTurnContextOptions {
     /** Number of turns so far (1-indexed for tool execution, 0 for initial request) */
     numberOfTurns: number;
     /** The specific tool call being executed (optional for initial/async resolution contexts) */
-    toolCall?: models.OpenResponsesFunctionToolCall;
+    toolCall?: models.FunctionCallItem;
     /** The full request being sent to the API (optional for initial/async resolution contexts) */
-    turnRequest?: models.OpenResponsesRequest;
+    turnRequest?: models.ResponsesRequest;
 }
 /**
  * Build a turn context for tool execution or async parameter resolution
@@ -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.InputsUnion): Array<models.BaseInputsUnion>;
 //# sourceMappingURL=turn-context.d.ts.map

package/esm/lib/turn-context.js

@@ -49,7 +49,7 @@ export function normalizeInputToArray(input) {
     if (typeof input === 'string') {
         // Construct object with all required fields - type is optional
         const message = {
-            role: models.OpenResponsesEasyInputMessageRoleUser.User,
+            role: models.EasyInputMessageRoleUser.User,
             content: input,
         };
         return [message];

package/esm/lib/url.js

@@ -6,7 +6,8 @@ const hasOwn = Object.prototype.hasOwnProperty;
 export function pathToFunc(pathPattern, options) {
     const paramRE = /\{([a-zA-Z0-9_][a-zA-Z0-9_-]*?)\}/g;
     return function buildURLPath(params = {}) {
-        return pathPattern.replace(paramRE, function (_, placeholder) {
+        return pathPattern
+            .replace(paramRE, function (_, placeholder) {
             if (!hasOwn.call(params, placeholder)) {
                 throw new Error(`Parameter '${placeholder}' is required`);
             }
@@ -17,7 +18,8 @@ export function pathToFunc(pathPattern, options) {
             return options?.charEncoding === "percent"
                 ? encodeURIComponent(`${value}`)
                 : `${value}`;
-        });
+        })
+            .replace(/^\/+/, "");
     };
 }
 //# sourceMappingURL=url.js.map

package/esm/models/annotationaddedevent.d.ts

@@ -0,0 +1,20 @@
+import * as z from "zod/v4";
+import { Result as SafeParseResult } from "../types/fp.js";
+import { SDKValidationError } from "./errors/sdkvalidationerror.js";
+import { OpenAIResponsesAnnotation } from "./openairesponsesannotation.js";
+/**
+ * Event emitted when a text annotation is added to output
+ */
+export type AnnotationAddedEvent = {
+    type: "response.output_text.annotation.added";
+    outputIndex: number;
+    itemId: string;
+    contentIndex: number;
+    sequenceNumber: number;
+    annotationIndex: number;
+    annotation: OpenAIResponsesAnnotation;
+};
+/** @internal */
+export declare const AnnotationAddedEvent$inboundSchema: z.ZodType<AnnotationAddedEvent, unknown>;
+export declare function annotationAddedEventFromJSON(jsonString: string): SafeParseResult<AnnotationAddedEvent, SDKValidationError>;
+//# sourceMappingURL=annotationaddedevent.d.ts.map

package/esm/models/annotationaddedevent.js

@@ -0,0 +1,30 @@
+/*
+ * Code generated by Speakeasy (https://speakeasy.com). DO NOT EDIT.
+ * @generated-id: e5c5f2adf5f6
+ */
+import * as z from "zod/v4";
+import { remap as remap$ } from "../lib/primitives.js";
+import { safeParse } from "../lib/schemas.js";
+import { OpenAIResponsesAnnotation$inboundSchema, } from "./openairesponsesannotation.js";
+/** @internal */
+export const AnnotationAddedEvent$inboundSchema = z.object({
+    type: z.literal("response.output_text.annotation.added"),
+    output_index: z.number(),
+    item_id: z.string(),
+    content_index: z.number(),
+    sequence_number: z.number(),
+    annotation_index: z.number(),
+    annotation: OpenAIResponsesAnnotation$inboundSchema,
+}).transform((v) => {
+    return remap$(v, {
+        "output_index": "outputIndex",
+        "item_id": "itemId",
+        "content_index": "contentIndex",
+        "sequence_number": "sequenceNumber",
+        "annotation_index": "annotationIndex",
+    });
+});
+export function annotationAddedEventFromJSON(jsonString) {
+    return safeParse(jsonString, (x) => AnnotationAddedEvent$inboundSchema.parse(JSON.parse(x)), `Failed to parse 'AnnotationAddedEvent' from JSON`);
+}
+//# sourceMappingURL=annotationaddedevent.js.map