@ai-sdk/provider-utils 5.0.0-beta.7 → 5.0.0-beta.8

package/CHANGELOG.md

@@ -1,5 +1,14 @@
 # @ai-sdk/provider-utils
 
+## 5.0.0-beta.8
+
+### Major Changes
+
+- 986c6fd: feat(ai): change type of experimental_context from unknown to generic
+- 493295c: Remove the deprecated `ToolCallOptions` export.
+
+  Use `ToolExecutionOptions` instead.
+
 ## 5.0.0-beta.7
 
 ### Patch Changes

package/dist/index.d.mts

@@ -1052,9 +1052,14 @@ type UserContent = string | Array<TextPart | ImagePart | FilePart>;
 type ModelMessage = SystemModelMessage | UserModelMessage | AssistantModelMessage | ToolModelMessage;
 
 /**
- * Additional options that are sent into each tool call.
+ * A context object that is passed into tool execution.
  */
-interface ToolExecutionOptions {
+type Context = Record<string, unknown>;
+
+/**
+ * Additional options that are sent into each tool execution.
+ */
+interface ToolExecutionOptions<CONTEXT extends Context> {
     /**
      * The ID of the tool call. You can use it e.g. when sending tool-call related information with stream data.
      */
@@ -1080,12 +1085,12 @@ interface ToolExecutionOptions {
      *
      * Experimental (can break in patch releases).
      */
-    experimental_context?: unknown;
+    experimental_context: CONTEXT;
 }
 /**
  * Function that is called to determine if the tool needs approval before it can be executed.
  */
-type ToolNeedsApprovalFunction<INPUT> = (input: INPUT, options: {
+type ToolNeedsApprovalFunction<INPUT, CONTEXT extends Context> = (input: INPUT, options: {
     /**
      * The ID of the tool call. You can use it e.g. when sending tool-call related information with stream data.
      */
@@ -1100,11 +1105,17 @@ type ToolNeedsApprovalFunction<INPUT> = (input: INPUT, options: {
      *
      * Experimental (can break in patch releases).
      */
-    experimental_context?: unknown;
+    experimental_context: CONTEXT;
 }) => boolean | PromiseLike<boolean>;
-type ToolExecuteFunction<INPUT, OUTPUT> = (input: INPUT, options: ToolExecutionOptions) => AsyncIterable<OUTPUT> | PromiseLike<OUTPUT> | OUTPUT;
+/**
+ * Function that executes the tool and returns either a single result or a stream of results.
+ */
+type ToolExecuteFunction<INPUT, OUTPUT, CONTEXT extends Context> = (input: INPUT, options: ToolExecutionOptions<CONTEXT>) => AsyncIterable<OUTPUT> | PromiseLike<OUTPUT> | OUTPUT;
 type NeverOptional<N, T> = 0 extends 1 & N ? Partial<T> : [N] extends [never] ? Partial<Record<keyof T, undefined>> : T;
-type ToolOutputProperties<INPUT, OUTPUT> = NeverOptional<OUTPUT, {
+/**
+ * Helper type to determine the output properties of a tool.
+ */
+type ToolOutputProperties<INPUT, OUTPUT, CONTEXT extends Context> = NeverOptional<OUTPUT, {
     /**
      * An async function that is called with the arguments from the tool call and produces a result.
      * If not provided, the tool will not be executed automatically.
@@ -1112,7 +1123,7 @@ type ToolOutputProperties<INPUT, OUTPUT> = NeverOptional<OUTPUT, {
      * @args is the input of the tool call.
      * @options.abortSignal is a signal that can be used to abort the tool call.
      */
-    execute: ToolExecuteFunction<INPUT, OUTPUT>;
+    execute: ToolExecuteFunction<INPUT, OUTPUT, CONTEXT>;
     outputSchema?: FlexibleSchema<OUTPUT>;
 } | {
     outputSchema: FlexibleSchema<OUTPUT>;
@@ -1124,7 +1135,7 @@ type ToolOutputProperties<INPUT, OUTPUT> = NeverOptional<OUTPUT, {
  *
  * The tool can also contain an optional execute function for the actual execution function of the tool.
  */
-type Tool<INPUT extends JSONValue | unknown | never = any, OUTPUT extends JSONValue | unknown | never = any> = {
+type Tool<INPUT extends JSONValue | unknown | never = any, OUTPUT extends JSONValue | unknown | never = any, CONTEXT extends Context = Context> = {
     /**
      * An optional description of what the tool does.
      * Will be used by the language model to decide whether to use the tool.
@@ -1156,10 +1167,18 @@ type Tool<INPUT extends JSONValue | unknown | never = any, OUTPUT extends JSONVa
     inputExamples?: Array<{
         input: NoInfer<INPUT>;
     }>;
+    /**
+     * An optional schema describing the context that the tool expects.
+     *
+     * The context is passed to execute function as part of the execution options.
+     */
+    contextSchema?: FlexibleSchema<CONTEXT>;
     /**
      * Whether the tool needs approval before it can be executed.
      */
-    needsApproval?: boolean | ToolNeedsApprovalFunction<[INPUT] extends [never] ? unknown : INPUT>;
+    needsApproval?: boolean | ToolNeedsApprovalFunction<[
+        INPUT
+    ] extends [never] ? unknown : INPUT, NoInfer<CONTEXT>>;
     /**
      * Strict mode setting for the tool.
      *
@@ -1172,22 +1191,22 @@ type Tool<INPUT extends JSONValue | unknown | never = any, OUTPUT extends JSONVa
      * Optional function that is called when the argument streaming starts.
      * Only called when the tool is used in a streaming context.
      */
-    onInputStart?: (options: ToolExecutionOptions) => void | PromiseLike<void>;
+    onInputStart?: (options: ToolExecutionOptions<NoInfer<CONTEXT>>) => void | PromiseLike<void>;
     /**
      * Optional function that is called when an argument streaming delta is available.
      * Only called when the tool is used in a streaming context.
      */
     onInputDelta?: (options: {
         inputTextDelta: string;
-    } & ToolExecutionOptions) => void | PromiseLike<void>;
+    } & ToolExecutionOptions<NoInfer<CONTEXT>>) => void | PromiseLike<void>;
     /**
      * Optional function that is called when a tool call can be started,
      * even if the execute function is not provided.
      */
     onInputAvailable?: (options: {
         input: [INPUT] extends [never] ? unknown : INPUT;
-    } & ToolExecutionOptions) => void | PromiseLike<void>;
-} & ToolOutputProperties<INPUT, OUTPUT> & {
+    } & ToolExecutionOptions<NoInfer<CONTEXT>>) => void | PromiseLike<void>;
+} & ToolOutputProperties<INPUT, OUTPUT, NoInfer<CONTEXT>> & {
     /**
      * Optional conversion function that maps the tool result to an output that can be used by the language model.
      *
@@ -1248,21 +1267,13 @@ type Tool<INPUT extends JSONValue | unknown | never = any, OUTPUT extends JSONVa
      */
     supportsDeferredResults?: boolean;
 });
-/**
- * Infer the input type of a tool.
- */
-type InferToolInput<TOOL extends Tool> = TOOL extends Tool<infer INPUT, any> ? INPUT : never;
-/**
- * Infer the output type of a tool.
- */
-type InferToolOutput<TOOL extends Tool> = TOOL extends Tool<any, infer OUTPUT> ? OUTPUT : never;
 /**
  * Helper function for inferring the execute args of a tool.
  */
-declare function tool<INPUT, OUTPUT>(tool: Tool<INPUT, OUTPUT>): Tool<INPUT, OUTPUT>;
-declare function tool<INPUT>(tool: Tool<INPUT, never>): Tool<INPUT, never>;
-declare function tool<OUTPUT>(tool: Tool<never, OUTPUT>): Tool<never, OUTPUT>;
-declare function tool(tool: Tool<never, never>): Tool<never, never>;
+declare function tool<INPUT, OUTPUT, CONTEXT extends Context>(tool: Tool<INPUT, OUTPUT, CONTEXT>): Tool<INPUT, OUTPUT, CONTEXT>;
+declare function tool<INPUT, CONTEXT extends Context>(tool: Tool<INPUT, never, CONTEXT>): Tool<INPUT, never, CONTEXT>;
+declare function tool<OUTPUT, CONTEXT extends Context>(tool: Tool<never, OUTPUT, CONTEXT>): Tool<never, OUTPUT, CONTEXT>;
+declare function tool<CONTEXT extends Context>(tool: Tool<never, never, CONTEXT>): Tool<never, never, CONTEXT>;
 /**
  * Defines a dynamic tool.
  */
@@ -1271,7 +1282,7 @@ declare function dynamicTool(tool: {
     title?: string;
     providerOptions?: ProviderOptions;
     inputSchema: FlexibleSchema<unknown>;
-    execute: ToolExecuteFunction<unknown, unknown>;
+    execute: ToolExecuteFunction<unknown, unknown, Context>;
     /**
      * Optional conversion function that maps the tool result to an output that can be used by the language model.
      *
@@ -1294,32 +1305,32 @@ declare function dynamicTool(tool: {
     /**
      * Whether the tool needs approval before it can be executed.
      */
-    needsApproval?: boolean | ToolNeedsApprovalFunction<unknown>;
-}): Tool<unknown, unknown> & {
+    needsApproval?: boolean | ToolNeedsApprovalFunction<unknown, Context>;
+}): Tool<unknown, unknown, Context> & {
     type: 'dynamic';
 };
 
-type ProviderToolFactory<INPUT, ARGS extends object> = <OUTPUT>(options: ARGS & {
-    execute?: ToolExecuteFunction<INPUT, OUTPUT>;
-    needsApproval?: Tool<INPUT, OUTPUT>['needsApproval'];
-    toModelOutput?: Tool<INPUT, OUTPUT>['toModelOutput'];
-    onInputStart?: Tool<INPUT, OUTPUT>['onInputStart'];
-    onInputDelta?: Tool<INPUT, OUTPUT>['onInputDelta'];
-    onInputAvailable?: Tool<INPUT, OUTPUT>['onInputAvailable'];
-}) => Tool<INPUT, OUTPUT>;
-declare function createProviderToolFactory<INPUT, ARGS extends object>({ id, inputSchema, }: {
+type ProviderToolFactory<INPUT, ARGS extends object, CONTEXT extends Context = {}> = <OUTPUT>(options: ARGS & {
+    execute?: ToolExecuteFunction<INPUT, OUTPUT, CONTEXT>;
+    needsApproval?: Tool<INPUT, OUTPUT, CONTEXT>['needsApproval'];
+    toModelOutput?: Tool<INPUT, OUTPUT, CONTEXT>['toModelOutput'];
+    onInputStart?: Tool<INPUT, OUTPUT, CONTEXT>['onInputStart'];
+    onInputDelta?: Tool<INPUT, OUTPUT, CONTEXT>['onInputDelta'];
+    onInputAvailable?: Tool<INPUT, OUTPUT, CONTEXT>['onInputAvailable'];
+}) => Tool<INPUT, OUTPUT, CONTEXT>;
+declare function createProviderToolFactory<INPUT, ARGS extends object, CONTEXT extends Context = {}>({ id, inputSchema, }: {
     id: `${string}.${string}`;
     inputSchema: FlexibleSchema<INPUT>;
-}): ProviderToolFactory<INPUT, ARGS>;
-type ProviderToolFactoryWithOutputSchema<INPUT, OUTPUT, ARGS extends object> = (options: ARGS & {
-    execute?: ToolExecuteFunction<INPUT, OUTPUT>;
-    needsApproval?: Tool<INPUT, OUTPUT>['needsApproval'];
-    toModelOutput?: Tool<INPUT, OUTPUT>['toModelOutput'];
-    onInputStart?: Tool<INPUT, OUTPUT>['onInputStart'];
-    onInputDelta?: Tool<INPUT, OUTPUT>['onInputDelta'];
-    onInputAvailable?: Tool<INPUT, OUTPUT>['onInputAvailable'];
-}) => Tool<INPUT, OUTPUT>;
-declare function createProviderToolFactoryWithOutputSchema<INPUT, OUTPUT, ARGS extends object>({ id, inputSchema, outputSchema, supportsDeferredResults, }: {
+}): ProviderToolFactory<INPUT, ARGS, CONTEXT>;
+type ProviderToolFactoryWithOutputSchema<INPUT, OUTPUT, ARGS extends object, CONTEXT extends Context = {}> = (options: ARGS & {
+    execute?: ToolExecuteFunction<INPUT, OUTPUT, CONTEXT>;
+    needsApproval?: Tool<INPUT, OUTPUT, CONTEXT>['needsApproval'];
+    toModelOutput?: Tool<INPUT, OUTPUT, CONTEXT>['toModelOutput'];
+    onInputStart?: Tool<INPUT, OUTPUT, CONTEXT>['onInputStart'];
+    onInputDelta?: Tool<INPUT, OUTPUT, CONTEXT>['onInputDelta'];
+    onInputAvailable?: Tool<INPUT, OUTPUT, CONTEXT>['onInputAvailable'];
+}) => Tool<INPUT, OUTPUT, CONTEXT>;
+declare function createProviderToolFactoryWithOutputSchema<INPUT, OUTPUT, ARGS extends object, CONTEXT extends Context = {}>({ id, inputSchema, outputSchema, supportsDeferredResults, }: {
     id: `${string}.${string}`;
     inputSchema: FlexibleSchema<INPUT>;
     outputSchema: FlexibleSchema<OUTPUT>;
@@ -1334,7 +1345,7 @@ declare function createProviderToolFactoryWithOutputSchema<INPUT, OUTPUT, ARGS e
      * @default false
      */
     supportsDeferredResults?: boolean;
-}): ProviderToolFactoryWithOutputSchema<INPUT, OUTPUT, ARGS>;
+}): ProviderToolFactoryWithOutputSchema<INPUT, OUTPUT, ARGS, CONTEXT>;
 
 /**
  * Removes entries from a record where the value is null or undefined.
@@ -1428,10 +1439,29 @@ declare function withUserAgentSuffix(headers: HeadersInit | Record<string, strin
 
 declare function withoutTrailingSlash(url: string | undefined): string | undefined;
 
-declare function executeTool<INPUT, OUTPUT>({ execute, input, options, }: {
-    execute: ToolExecuteFunction<INPUT, OUTPUT>;
+/**
+ * Executes a tool function, supporting both synchronous and streaming/asynchronous results.
+ *
+ * This generator yields intermediate ("preliminary") outputs as they're produced, allowing callers
+ * to stream partial tool results before completion. When execution is finished, it yields a final output,
+ * ensuring all consumers receive a conclusive result.
+ *
+ * - If the tool's `execute` function returns an `AsyncIterable`, all intermediate values are yielded
+ *   as `{ type: "preliminary", output }` except the last, which is yielded as `{ type: "final", output }`.
+ * - If the tool returns a direct value or Promise, a single `{ type: "final", output }` is yielded.
+ *
+ * @template INPUT Input type for the tool execution.
+ * @template OUTPUT Output type for the tool execution.
+ * @template CONTEXT Context object extension for execution (extends Context).
+ * @param params.execute The tool execute function.
+ * @param params.input Input value to pass to the execute function.
+ * @param params.options Additional options for tool execution.
+ * @yields An object containing either a preliminary or final output from the tool.
+ */
+declare function executeTool<INPUT, OUTPUT, CONTEXT extends Context>({ execute, input, options, }: {
+    execute: ToolExecuteFunction<INPUT, OUTPUT, CONTEXT>;
     input: INPUT;
-    options: ToolExecutionOptions;
+    options: ToolExecutionOptions<NoInfer<CONTEXT>>;
 }): AsyncGenerator<{
     type: 'preliminary';
     output: OUTPUT;
@@ -1440,6 +1470,21 @@ declare function executeTool<INPUT, OUTPUT>({ execute, input, options, }: {
     output: OUTPUT;
 }>;
 
+/**
+ * Infer the context type of a tool.
+ */
+type InferToolContext<TOOL extends Tool<any, any, any>> = TOOL extends Tool<any, any, infer CONTEXT> ? CONTEXT : never;
+
+/**
+ * Infer the input type of a tool.
+ */
+type InferToolInput<TOOL extends Tool<any, any, any>> = TOOL extends Tool<infer INPUT, any, any> ? INPUT : never;
+
+/**
+ * Infer the output type of a tool.
+ */
+type InferToolOutput<TOOL extends Tool<any, any, any>> = TOOL extends Tool<any, infer OUTPUT, any> ? OUTPUT : never;
+
 /**
  * Typed tool call that is returned by generateText and streamText.
  * It contains the tool call ID, the tool name, and the tool arguments.
@@ -1499,9 +1544,4 @@ interface ToolResult<NAME extends string, INPUT, OUTPUT> {
     dynamic?: boolean;
 }
 
-/**
- * @deprecated Use ToolExecutionOptions instead.
- */
-type ToolCallOptions = ToolExecutionOptions;
-
-export { type AssistantContent, type AssistantModelMessage, type CustomPart, DEFAULT_MAX_DOWNLOAD_SIZE, type DataContent, DelayedPromise, DownloadError, type FetchFunction, type FilePart, type FlexibleSchema, type IdGenerator, type ImagePart, type InferSchema, type InferToolInput, type InferToolOutput, type LazySchema, type MaybePromiseLike, type ModelMessage, type ParseResult, type ProviderOptions, type ProviderToolFactory, type ProviderToolFactoryWithOutputSchema, type ReasoningFilePart, type ReasoningPart, type Resolvable, type ResponseHandler, type Schema, type SystemModelMessage, type TextPart, type Tool, type ToolApprovalRequest, type ToolApprovalResponse, type ToolCall, type ToolCallOptions, type ToolCallPart, type ToolContent, type ToolExecuteFunction, type ToolExecutionOptions, type ToolModelMessage, type ToolNameMapping, type ToolNeedsApprovalFunction, type ToolResult, type ToolResultOutput, type ToolResultPart, type UserContent, type UserModelMessage, VERSION, type ValidationResult, asSchema, combineHeaders, convertAsyncIteratorToReadableStream, convertBase64ToUint8Array, convertImageModelFileToDataUri, convertToBase64, convertToFormData, convertUint8ArrayToBase64, createBinaryResponseHandler, createEventSourceResponseHandler, createIdGenerator, createJsonErrorResponseHandler, createJsonResponseHandler, createProviderToolFactory, createProviderToolFactoryWithOutputSchema, createStatusCodeErrorResponseHandler, createToolNameMapping, delay, downloadBlob, dynamicTool, executeTool, extractResponseHeaders, generateId, getErrorMessage, getFromApi, getRuntimeEnvironmentUserAgent, injectJsonInstructionIntoMessages, isAbortError, isCustomReasoning, isNonNullable, isParsableJson, isUrlSupported, jsonSchema, lazySchema, loadApiKey, loadOptionalSetting, loadSetting, mapReasoningToProviderBudget, mapReasoningToProviderEffort, mediaTypeToExtension, normalizeHeaders, parseJSON, parseJsonEventStream, parseProviderOptions, postFormDataToApi, postJsonToApi, postToApi, readResponseWithSizeLimit, removeUndefinedEntries, resolve, safeParseJSON, safeValidateTypes, stripFileExtension, tool, validateDownloadUrl, validateTypes, withUserAgentSuffix, withoutTrailingSlash, zodSchema };
+export { type AssistantContent, type AssistantModelMessage, type Context, type CustomPart, DEFAULT_MAX_DOWNLOAD_SIZE, type DataContent, DelayedPromise, DownloadError, type FetchFunction, type FilePart, type FlexibleSchema, type IdGenerator, type ImagePart, type InferSchema, type InferToolContext, type InferToolInput, type InferToolOutput, type LazySchema, type MaybePromiseLike, type ModelMessage, type ParseResult, type ProviderOptions, type ProviderToolFactory, type ProviderToolFactoryWithOutputSchema, type ReasoningFilePart, type ReasoningPart, type Resolvable, type ResponseHandler, type Schema, type SystemModelMessage, type TextPart, type Tool, type ToolApprovalRequest, type ToolApprovalResponse, type ToolCall, type ToolCallPart, type ToolContent, type ToolExecuteFunction, type ToolExecutionOptions, type ToolModelMessage, type ToolNameMapping, type ToolNeedsApprovalFunction, type ToolResult, type ToolResultOutput, type ToolResultPart, type UserContent, type UserModelMessage, VERSION, type ValidationResult, asSchema, combineHeaders, convertAsyncIteratorToReadableStream, convertBase64ToUint8Array, convertImageModelFileToDataUri, convertToBase64, convertToFormData, convertUint8ArrayToBase64, createBinaryResponseHandler, createEventSourceResponseHandler, createIdGenerator, createJsonErrorResponseHandler, createJsonResponseHandler, createProviderToolFactory, createProviderToolFactoryWithOutputSchema, createStatusCodeErrorResponseHandler, createToolNameMapping, delay, downloadBlob, dynamicTool, executeTool, extractResponseHeaders, generateId, getErrorMessage, getFromApi, getRuntimeEnvironmentUserAgent, injectJsonInstructionIntoMessages, isAbortError, isCustomReasoning, isNonNullable, isParsableJson, isUrlSupported, jsonSchema, lazySchema, loadApiKey, loadOptionalSetting, loadSetting, mapReasoningToProviderBudget, mapReasoningToProviderEffort, mediaTypeToExtension, normalizeHeaders, parseJSON, parseJsonEventStream, parseProviderOptions, postFormDataToApi, postJsonToApi, postToApi, readResponseWithSizeLimit, removeUndefinedEntries, resolve, safeParseJSON, safeValidateTypes, stripFileExtension, tool, validateDownloadUrl, validateTypes, withUserAgentSuffix, withoutTrailingSlash, zodSchema };

package/dist/index.d.ts

@@ -1052,9 +1052,14 @@ type UserContent = string | Array<TextPart | ImagePart | FilePart>;
 type ModelMessage = SystemModelMessage | UserModelMessage | AssistantModelMessage | ToolModelMessage;
 
 /**
- * Additional options that are sent into each tool call.
+ * A context object that is passed into tool execution.
  */
-interface ToolExecutionOptions {
+type Context = Record<string, unknown>;
+
+/**
+ * Additional options that are sent into each tool execution.
+ */
+interface ToolExecutionOptions<CONTEXT extends Context> {
     /**
      * The ID of the tool call. You can use it e.g. when sending tool-call related information with stream data.
      */
@@ -1080,12 +1085,12 @@ interface ToolExecutionOptions {
      *
      * Experimental (can break in patch releases).
      */
-    experimental_context?: unknown;
+    experimental_context: CONTEXT;
 }
 /**
  * Function that is called to determine if the tool needs approval before it can be executed.
  */
-type ToolNeedsApprovalFunction<INPUT> = (input: INPUT, options: {
+type ToolNeedsApprovalFunction<INPUT, CONTEXT extends Context> = (input: INPUT, options: {
     /**
      * The ID of the tool call. You can use it e.g. when sending tool-call related information with stream data.
      */
@@ -1100,11 +1105,17 @@ type ToolNeedsApprovalFunction<INPUT> = (input: INPUT, options: {
      *
      * Experimental (can break in patch releases).
      */
-    experimental_context?: unknown;
+    experimental_context: CONTEXT;
 }) => boolean | PromiseLike<boolean>;
-type ToolExecuteFunction<INPUT, OUTPUT> = (input: INPUT, options: ToolExecutionOptions) => AsyncIterable<OUTPUT> | PromiseLike<OUTPUT> | OUTPUT;
+/**
+ * Function that executes the tool and returns either a single result or a stream of results.
+ */
+type ToolExecuteFunction<INPUT, OUTPUT, CONTEXT extends Context> = (input: INPUT, options: ToolExecutionOptions<CONTEXT>) => AsyncIterable<OUTPUT> | PromiseLike<OUTPUT> | OUTPUT;
 type NeverOptional<N, T> = 0 extends 1 & N ? Partial<T> : [N] extends [never] ? Partial<Record<keyof T, undefined>> : T;
-type ToolOutputProperties<INPUT, OUTPUT> = NeverOptional<OUTPUT, {
+/**
+ * Helper type to determine the output properties of a tool.
+ */
+type ToolOutputProperties<INPUT, OUTPUT, CONTEXT extends Context> = NeverOptional<OUTPUT, {
     /**
      * An async function that is called with the arguments from the tool call and produces a result.
      * If not provided, the tool will not be executed automatically.
@@ -1112,7 +1123,7 @@ type ToolOutputProperties<INPUT, OUTPUT> = NeverOptional<OUTPUT, {
      * @args is the input of the tool call.
      * @options.abortSignal is a signal that can be used to abort the tool call.
      */
-    execute: ToolExecuteFunction<INPUT, OUTPUT>;
+    execute: ToolExecuteFunction<INPUT, OUTPUT, CONTEXT>;
     outputSchema?: FlexibleSchema<OUTPUT>;
 } | {
     outputSchema: FlexibleSchema<OUTPUT>;
@@ -1124,7 +1135,7 @@ type ToolOutputProperties<INPUT, OUTPUT> = NeverOptional<OUTPUT, {
  *
  * The tool can also contain an optional execute function for the actual execution function of the tool.
  */
-type Tool<INPUT extends JSONValue | unknown | never = any, OUTPUT extends JSONValue | unknown | never = any> = {
+type Tool<INPUT extends JSONValue | unknown | never = any, OUTPUT extends JSONValue | unknown | never = any, CONTEXT extends Context = Context> = {
     /**
      * An optional description of what the tool does.
      * Will be used by the language model to decide whether to use the tool.
@@ -1156,10 +1167,18 @@ type Tool<INPUT extends JSONValue | unknown | never = any, OUTPUT extends JSONVa
     inputExamples?: Array<{
         input: NoInfer<INPUT>;
     }>;
+    /**
+     * An optional schema describing the context that the tool expects.
+     *
+     * The context is passed to execute function as part of the execution options.
+     */
+    contextSchema?: FlexibleSchema<CONTEXT>;
     /**
      * Whether the tool needs approval before it can be executed.
      */
-    needsApproval?: boolean | ToolNeedsApprovalFunction<[INPUT] extends [never] ? unknown : INPUT>;
+    needsApproval?: boolean | ToolNeedsApprovalFunction<[
+        INPUT
+    ] extends [never] ? unknown : INPUT, NoInfer<CONTEXT>>;
     /**
      * Strict mode setting for the tool.
      *
@@ -1172,22 +1191,22 @@ type Tool<INPUT extends JSONValue | unknown | never = any, OUTPUT extends JSONVa
      * Optional function that is called when the argument streaming starts.
      * Only called when the tool is used in a streaming context.
      */
-    onInputStart?: (options: ToolExecutionOptions) => void | PromiseLike<void>;
+    onInputStart?: (options: ToolExecutionOptions<NoInfer<CONTEXT>>) => void | PromiseLike<void>;
     /**
      * Optional function that is called when an argument streaming delta is available.
      * Only called when the tool is used in a streaming context.
      */
     onInputDelta?: (options: {
         inputTextDelta: string;
-    } & ToolExecutionOptions) => void | PromiseLike<void>;
+    } & ToolExecutionOptions<NoInfer<CONTEXT>>) => void | PromiseLike<void>;
     /**
      * Optional function that is called when a tool call can be started,
      * even if the execute function is not provided.
      */
     onInputAvailable?: (options: {
         input: [INPUT] extends [never] ? unknown : INPUT;
-    } & ToolExecutionOptions) => void | PromiseLike<void>;
-} & ToolOutputProperties<INPUT, OUTPUT> & {
+    } & ToolExecutionOptions<NoInfer<CONTEXT>>) => void | PromiseLike<void>;
+} & ToolOutputProperties<INPUT, OUTPUT, NoInfer<CONTEXT>> & {
     /**
      * Optional conversion function that maps the tool result to an output that can be used by the language model.
      *
@@ -1248,21 +1267,13 @@ type Tool<INPUT extends JSONValue | unknown | never = any, OUTPUT extends JSONVa
      */
     supportsDeferredResults?: boolean;
 });
-/**
- * Infer the input type of a tool.
- */
-type InferToolInput<TOOL extends Tool> = TOOL extends Tool<infer INPUT, any> ? INPUT : never;
-/**
- * Infer the output type of a tool.
- */
-type InferToolOutput<TOOL extends Tool> = TOOL extends Tool<any, infer OUTPUT> ? OUTPUT : never;
 /**
  * Helper function for inferring the execute args of a tool.
  */
-declare function tool<INPUT, OUTPUT>(tool: Tool<INPUT, OUTPUT>): Tool<INPUT, OUTPUT>;
-declare function tool<INPUT>(tool: Tool<INPUT, never>): Tool<INPUT, never>;
-declare function tool<OUTPUT>(tool: Tool<never, OUTPUT>): Tool<never, OUTPUT>;
-declare function tool(tool: Tool<never, never>): Tool<never, never>;
+declare function tool<INPUT, OUTPUT, CONTEXT extends Context>(tool: Tool<INPUT, OUTPUT, CONTEXT>): Tool<INPUT, OUTPUT, CONTEXT>;
+declare function tool<INPUT, CONTEXT extends Context>(tool: Tool<INPUT, never, CONTEXT>): Tool<INPUT, never, CONTEXT>;
+declare function tool<OUTPUT, CONTEXT extends Context>(tool: Tool<never, OUTPUT, CONTEXT>): Tool<never, OUTPUT, CONTEXT>;
+declare function tool<CONTEXT extends Context>(tool: Tool<never, never, CONTEXT>): Tool<never, never, CONTEXT>;
 /**
  * Defines a dynamic tool.
  */
@@ -1271,7 +1282,7 @@ declare function dynamicTool(tool: {
     title?: string;
     providerOptions?: ProviderOptions;
     inputSchema: FlexibleSchema<unknown>;
-    execute: ToolExecuteFunction<unknown, unknown>;
+    execute: ToolExecuteFunction<unknown, unknown, Context>;
     /**
      * Optional conversion function that maps the tool result to an output that can be used by the language model.
      *
@@ -1294,32 +1305,32 @@ declare function dynamicTool(tool: {
     /**
      * Whether the tool needs approval before it can be executed.
      */
-    needsApproval?: boolean | ToolNeedsApprovalFunction<unknown>;
-}): Tool<unknown, unknown> & {
+    needsApproval?: boolean | ToolNeedsApprovalFunction<unknown, Context>;
+}): Tool<unknown, unknown, Context> & {
     type: 'dynamic';
 };
 
-type ProviderToolFactory<INPUT, ARGS extends object> = <OUTPUT>(options: ARGS & {
-    execute?: ToolExecuteFunction<INPUT, OUTPUT>;
-    needsApproval?: Tool<INPUT, OUTPUT>['needsApproval'];
-    toModelOutput?: Tool<INPUT, OUTPUT>['toModelOutput'];
-    onInputStart?: Tool<INPUT, OUTPUT>['onInputStart'];
-    onInputDelta?: Tool<INPUT, OUTPUT>['onInputDelta'];
-    onInputAvailable?: Tool<INPUT, OUTPUT>['onInputAvailable'];
-}) => Tool<INPUT, OUTPUT>;
-declare function createProviderToolFactory<INPUT, ARGS extends object>({ id, inputSchema, }: {
+type ProviderToolFactory<INPUT, ARGS extends object, CONTEXT extends Context = {}> = <OUTPUT>(options: ARGS & {
+    execute?: ToolExecuteFunction<INPUT, OUTPUT, CONTEXT>;
+    needsApproval?: Tool<INPUT, OUTPUT, CONTEXT>['needsApproval'];
+    toModelOutput?: Tool<INPUT, OUTPUT, CONTEXT>['toModelOutput'];
+    onInputStart?: Tool<INPUT, OUTPUT, CONTEXT>['onInputStart'];
+    onInputDelta?: Tool<INPUT, OUTPUT, CONTEXT>['onInputDelta'];
+    onInputAvailable?: Tool<INPUT, OUTPUT, CONTEXT>['onInputAvailable'];
+}) => Tool<INPUT, OUTPUT, CONTEXT>;
+declare function createProviderToolFactory<INPUT, ARGS extends object, CONTEXT extends Context = {}>({ id, inputSchema, }: {
     id: `${string}.${string}`;
     inputSchema: FlexibleSchema<INPUT>;
-}): ProviderToolFactory<INPUT, ARGS>;
-type ProviderToolFactoryWithOutputSchema<INPUT, OUTPUT, ARGS extends object> = (options: ARGS & {
-    execute?: ToolExecuteFunction<INPUT, OUTPUT>;
-    needsApproval?: Tool<INPUT, OUTPUT>['needsApproval'];
-    toModelOutput?: Tool<INPUT, OUTPUT>['toModelOutput'];
-    onInputStart?: Tool<INPUT, OUTPUT>['onInputStart'];
-    onInputDelta?: Tool<INPUT, OUTPUT>['onInputDelta'];
-    onInputAvailable?: Tool<INPUT, OUTPUT>['onInputAvailable'];
-}) => Tool<INPUT, OUTPUT>;
-declare function createProviderToolFactoryWithOutputSchema<INPUT, OUTPUT, ARGS extends object>({ id, inputSchema, outputSchema, supportsDeferredResults, }: {
+}): ProviderToolFactory<INPUT, ARGS, CONTEXT>;
+type ProviderToolFactoryWithOutputSchema<INPUT, OUTPUT, ARGS extends object, CONTEXT extends Context = {}> = (options: ARGS & {
+    execute?: ToolExecuteFunction<INPUT, OUTPUT, CONTEXT>;
+    needsApproval?: Tool<INPUT, OUTPUT, CONTEXT>['needsApproval'];
+    toModelOutput?: Tool<INPUT, OUTPUT, CONTEXT>['toModelOutput'];
+    onInputStart?: Tool<INPUT, OUTPUT, CONTEXT>['onInputStart'];
+    onInputDelta?: Tool<INPUT, OUTPUT, CONTEXT>['onInputDelta'];
+    onInputAvailable?: Tool<INPUT, OUTPUT, CONTEXT>['onInputAvailable'];
+}) => Tool<INPUT, OUTPUT, CONTEXT>;
+declare function createProviderToolFactoryWithOutputSchema<INPUT, OUTPUT, ARGS extends object, CONTEXT extends Context = {}>({ id, inputSchema, outputSchema, supportsDeferredResults, }: {
     id: `${string}.${string}`;
     inputSchema: FlexibleSchema<INPUT>;
     outputSchema: FlexibleSchema<OUTPUT>;
@@ -1334,7 +1345,7 @@ declare function createProviderToolFactoryWithOutputSchema<INPUT, OUTPUT, ARGS e
      * @default false
      */
     supportsDeferredResults?: boolean;
-}): ProviderToolFactoryWithOutputSchema<INPUT, OUTPUT, ARGS>;
+}): ProviderToolFactoryWithOutputSchema<INPUT, OUTPUT, ARGS, CONTEXT>;
 
 /**
  * Removes entries from a record where the value is null or undefined.
@@ -1428,10 +1439,29 @@ declare function withUserAgentSuffix(headers: HeadersInit | Record<string, strin
 
 declare function withoutTrailingSlash(url: string | undefined): string | undefined;
 
-declare function executeTool<INPUT, OUTPUT>({ execute, input, options, }: {
-    execute: ToolExecuteFunction<INPUT, OUTPUT>;
+/**
+ * Executes a tool function, supporting both synchronous and streaming/asynchronous results.
+ *
+ * This generator yields intermediate ("preliminary") outputs as they're produced, allowing callers
+ * to stream partial tool results before completion. When execution is finished, it yields a final output,
+ * ensuring all consumers receive a conclusive result.
+ *
+ * - If the tool's `execute` function returns an `AsyncIterable`, all intermediate values are yielded
+ *   as `{ type: "preliminary", output }` except the last, which is yielded as `{ type: "final", output }`.
+ * - If the tool returns a direct value or Promise, a single `{ type: "final", output }` is yielded.
+ *
+ * @template INPUT Input type for the tool execution.
+ * @template OUTPUT Output type for the tool execution.
+ * @template CONTEXT Context object extension for execution (extends Context).
+ * @param params.execute The tool execute function.
+ * @param params.input Input value to pass to the execute function.
+ * @param params.options Additional options for tool execution.
+ * @yields An object containing either a preliminary or final output from the tool.
+ */
+declare function executeTool<INPUT, OUTPUT, CONTEXT extends Context>({ execute, input, options, }: {
+    execute: ToolExecuteFunction<INPUT, OUTPUT, CONTEXT>;
     input: INPUT;
-    options: ToolExecutionOptions;
+    options: ToolExecutionOptions<NoInfer<CONTEXT>>;
 }): AsyncGenerator<{
     type: 'preliminary';
     output: OUTPUT;
@@ -1440,6 +1470,21 @@ declare function executeTool<INPUT, OUTPUT>({ execute, input, options, }: {
     output: OUTPUT;
 }>;
 
+/**
+ * Infer the context type of a tool.
+ */
+type InferToolContext<TOOL extends Tool<any, any, any>> = TOOL extends Tool<any, any, infer CONTEXT> ? CONTEXT : never;
+
+/**
+ * Infer the input type of a tool.
+ */
+type InferToolInput<TOOL extends Tool<any, any, any>> = TOOL extends Tool<infer INPUT, any, any> ? INPUT : never;
+
+/**
+ * Infer the output type of a tool.
+ */
+type InferToolOutput<TOOL extends Tool<any, any, any>> = TOOL extends Tool<any, infer OUTPUT, any> ? OUTPUT : never;
+
 /**
  * Typed tool call that is returned by generateText and streamText.
  * It contains the tool call ID, the tool name, and the tool arguments.
@@ -1499,9 +1544,4 @@ interface ToolResult<NAME extends string, INPUT, OUTPUT> {
     dynamic?: boolean;
 }
 
-/**
- * @deprecated Use ToolExecutionOptions instead.
- */
-type ToolCallOptions = ToolExecutionOptions;
-
-export { type AssistantContent, type AssistantModelMessage, type CustomPart, DEFAULT_MAX_DOWNLOAD_SIZE, type DataContent, DelayedPromise, DownloadError, type FetchFunction, type FilePart, type FlexibleSchema, type IdGenerator, type ImagePart, type InferSchema, type InferToolInput, type InferToolOutput, type LazySchema, type MaybePromiseLike, type ModelMessage, type ParseResult, type ProviderOptions, type ProviderToolFactory, type ProviderToolFactoryWithOutputSchema, type ReasoningFilePart, type ReasoningPart, type Resolvable, type ResponseHandler, type Schema, type SystemModelMessage, type TextPart, type Tool, type ToolApprovalRequest, type ToolApprovalResponse, type ToolCall, type ToolCallOptions, type ToolCallPart, type ToolContent, type ToolExecuteFunction, type ToolExecutionOptions, type ToolModelMessage, type ToolNameMapping, type ToolNeedsApprovalFunction, type ToolResult, type ToolResultOutput, type ToolResultPart, type UserContent, type UserModelMessage, VERSION, type ValidationResult, asSchema, combineHeaders, convertAsyncIteratorToReadableStream, convertBase64ToUint8Array, convertImageModelFileToDataUri, convertToBase64, convertToFormData, convertUint8ArrayToBase64, createBinaryResponseHandler, createEventSourceResponseHandler, createIdGenerator, createJsonErrorResponseHandler, createJsonResponseHandler, createProviderToolFactory, createProviderToolFactoryWithOutputSchema, createStatusCodeErrorResponseHandler, createToolNameMapping, delay, downloadBlob, dynamicTool, executeTool, extractResponseHeaders, generateId, getErrorMessage, getFromApi, getRuntimeEnvironmentUserAgent, injectJsonInstructionIntoMessages, isAbortError, isCustomReasoning, isNonNullable, isParsableJson, isUrlSupported, jsonSchema, lazySchema, loadApiKey, loadOptionalSetting, loadSetting, mapReasoningToProviderBudget, mapReasoningToProviderEffort, mediaTypeToExtension, normalizeHeaders, parseJSON, parseJsonEventStream, parseProviderOptions, postFormDataToApi, postJsonToApi, postToApi, readResponseWithSizeLimit, removeUndefinedEntries, resolve, safeParseJSON, safeValidateTypes, stripFileExtension, tool, validateDownloadUrl, validateTypes, withUserAgentSuffix, withoutTrailingSlash, zodSchema };
+export { type AssistantContent, type AssistantModelMessage, type Context, type CustomPart, DEFAULT_MAX_DOWNLOAD_SIZE, type DataContent, DelayedPromise, DownloadError, type FetchFunction, type FilePart, type FlexibleSchema, type IdGenerator, type ImagePart, type InferSchema, type InferToolContext, type InferToolInput, type InferToolOutput, type LazySchema, type MaybePromiseLike, type ModelMessage, type ParseResult, type ProviderOptions, type ProviderToolFactory, type ProviderToolFactoryWithOutputSchema, type ReasoningFilePart, type ReasoningPart, type Resolvable, type ResponseHandler, type Schema, type SystemModelMessage, type TextPart, type Tool, type ToolApprovalRequest, type ToolApprovalResponse, type ToolCall, type ToolCallPart, type ToolContent, type ToolExecuteFunction, type ToolExecutionOptions, type ToolModelMessage, type ToolNameMapping, type ToolNeedsApprovalFunction, type ToolResult, type ToolResultOutput, type ToolResultPart, type UserContent, type UserModelMessage, VERSION, type ValidationResult, asSchema, combineHeaders, convertAsyncIteratorToReadableStream, convertBase64ToUint8Array, convertImageModelFileToDataUri, convertToBase64, convertToFormData, convertUint8ArrayToBase64, createBinaryResponseHandler, createEventSourceResponseHandler, createIdGenerator, createJsonErrorResponseHandler, createJsonResponseHandler, createProviderToolFactory, createProviderToolFactoryWithOutputSchema, createStatusCodeErrorResponseHandler, createToolNameMapping, delay, downloadBlob, dynamicTool, executeTool, extractResponseHeaders, generateId, getErrorMessage, getFromApi, getRuntimeEnvironmentUserAgent, injectJsonInstructionIntoMessages, isAbortError, isCustomReasoning, isNonNullable, isParsableJson, isUrlSupported, jsonSchema, lazySchema, loadApiKey, loadOptionalSetting, loadSetting, mapReasoningToProviderBudget, mapReasoningToProviderEffort, mediaTypeToExtension, normalizeHeaders, parseJSON, parseJsonEventStream, parseProviderOptions, postFormDataToApi, postJsonToApi, postToApi, readResponseWithSizeLimit, removeUndefinedEntries, resolve, safeParseJSON, safeValidateTypes, stripFileExtension, tool, validateDownloadUrl, validateTypes, withUserAgentSuffix, withoutTrailingSlash, zodSchema };

package/dist/index.js

@@ -676,7 +676,7 @@ function withUserAgentSuffix(headers, ...userAgentSuffixParts) {
 }
 
 // src/version.ts
-var VERSION = true ? "5.0.0-beta.7" : "0.0.0-test";
+var VERSION = true ? "5.0.0-beta.8" : "0.0.0-test";
 
 // src/get-from-api.ts
 var getOriginalFetch = () => globalThis.fetch;