@ai-sdk/provider-utils 5.0.0-beta.0 → 5.0.0-beta.10

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-import { LanguageModelV3FunctionTool, LanguageModelV3ProviderTool, ImageModelV3File, AISDKError, JSONSchema7, JSONParseError, TypeValidationError, JSONValue, APICallError, LanguageModelV3Prompt, SharedV3ProviderOptions, TypeValidationContext } from '@ai-sdk/provider';
+import { LanguageModelV4FunctionTool, LanguageModelV4ProviderTool, ImageModelV4File, AISDKError, JSONSchema7, JSONParseError, TypeValidationError, JSONValue, APICallError, LanguageModelV4Prompt, LanguageModelV4FilePart, SharedV4ProviderReference, LanguageModelV4CallOptions, SharedV4Warning, SharedV4ProviderOptions, TypeValidationContext } from '@ai-sdk/provider';
 import { StandardSchemaV1, StandardJSONSchemaV1 } from '@standard-schema/spec';
 export * from '@standard-schema/spec';
 import * as z3 from 'zod/v3';
@@ -41,20 +41,15 @@ interface ToolNameMapping {
  * @param tools - Tools that were passed to the language model.
  * @param providerToolNames - Maps the provider tool ids to the provider tool names.
  */
-declare function createToolNameMapping({ tools, providerToolNames, resolveProviderToolName, }: {
+declare function createToolNameMapping({ tools, providerToolNames, }: {
     /**
      * Tools that were passed to the language model.
      */
-    tools: Array<LanguageModelV3FunctionTool | LanguageModelV3ProviderTool> | undefined;
+    tools: Array<LanguageModelV4FunctionTool | LanguageModelV4ProviderTool> | undefined;
     /**
      * Maps the provider tool ids to the provider tool names.
      */
     providerToolNames: Record<`${string}.${string}`, string>;
-    /**
-     * Optional resolver for provider tool names that cannot be represented as
-     * static id -> name mappings (e.g. dynamic provider names).
-     */
-    resolveProviderToolName?: (tool: LanguageModelV3ProviderTool) => string | undefined;
 }): ToolNameMapping;
 
 /**
@@ -97,13 +92,13 @@ declare function extractResponseHeaders(response: Response): {
 };
 
 /**
- * Convert an ImageModelV3File to a URL or data URI string.
+ * Convert an ImageModelV4File to a URL or data URI string.
  *
  * If the file is a URL, it returns the URL as-is.
  * If the file is base64 data, it returns a data URI with the base64 data.
  * If the file is a Uint8Array, it converts it to base64 and returns a data URI.
  */
-declare function convertImageModelFileToDataUri(file: ImageModelV3File): string;
+declare function convertImageModelFileToDataUri(file: ImageModelV4File): string;
 
 /**
  * Converts an input object to FormData for multipart/form-data requests.
@@ -390,11 +385,11 @@ declare const getFromApi: <T>({ url, headers, successfulResponseHandler, failedR
 declare function getRuntimeEnvironmentUserAgent(globalThisAny?: any): string;
 
 declare function injectJsonInstructionIntoMessages({ messages, schema, schemaPrefix, schemaSuffix, }: {
-    messages: LanguageModelV3Prompt;
+    messages: LanguageModelV4Prompt;
     schema?: JSONSchema7;
     schemaPrefix?: string;
     schemaSuffix?: string;
-}): LanguageModelV3Prompt;
+}): LanguageModelV4Prompt;
 
 declare function isAbortError(error: unknown): error is Error;
 
@@ -407,6 +402,12 @@ declare function isAbortError(error: unknown): error is Error;
  */
 declare function isNonNullable<T>(value: T | undefined | null): value is NonNullable<T>;
 
+/**
+ * Checks whether file part data is a provider reference (a mapping of provider
+ * names to provider-specific identifiers) as opposed to raw bytes or a URL.
+ */
+declare function isProviderReference(data: LanguageModelV4FilePart['data']): data is SharedV4ProviderReference;
+
 /**
  * Checks if the given URL is supported natively by the model.
  *
@@ -431,6 +432,41 @@ declare function loadApiKey({ apiKey, environmentVariableName, apiKeyParameterNa
     description: string;
 }): string;
 
+type ReasoningLevel = Exclude<LanguageModelV4CallOptions['reasoning'], 'none' | 'provider-default' | undefined>;
+declare function isCustomReasoning(reasoning: LanguageModelV4CallOptions['reasoning']): reasoning is Exclude<LanguageModelV4CallOptions['reasoning'], 'provider-default' | undefined>;
+/**
+ * Maps a top-level reasoning level to a provider-specific effort string using
+ * the given effort map. Pushes a compatibility warning if the reasoning level
+ * maps to a different string, or an unsupported warning if the level is not
+ * present in the map.
+ *
+ * @returns The mapped effort string, or `undefined` if the level is not
+ *   supported.
+ */
+declare function mapReasoningToProviderEffort<T extends string>({ reasoning, effortMap, warnings, }: {
+    reasoning: ReasoningLevel;
+    effortMap: Partial<Record<ReasoningLevel, T>>;
+    warnings: SharedV4Warning[];
+}): T | undefined;
+/**
+ * Maps a top-level reasoning level to an absolute token budget by multiplying
+ * the model's max output tokens by a percentage from the budget percentages
+ * map. The result is clamped between `minReasoningBudget` (default 1024) and
+ * `maxReasoningBudget`. Pushes an unsupported warning if the level is not
+ * present in the budget percentages map.
+ *
+ * @returns The computed token budget, or `undefined` if the level is not
+ *   supported.
+ */
+declare function mapReasoningToProviderBudget({ reasoning, maxOutputTokens, maxReasoningBudget, minReasoningBudget, budgetPercentages, warnings, }: {
+    reasoning: ReasoningLevel;
+    maxOutputTokens: number;
+    maxReasoningBudget: number;
+    minReasoningBudget?: number;
+    budgetPercentages?: Partial<Record<ReasoningLevel, number>>;
+    warnings: SharedV4Warning[];
+}): number | undefined;
+
 /**
  * Loads an optional `string` setting from the environment or a parameter.
  *
@@ -549,7 +585,16 @@ type DataContent = string | Uint8Array | ArrayBuffer | Buffer;
  * They are passed through to the provider from the AI SDK and enable
  * provider-specific functionality that can be fully encapsulated in the provider.
  */
-type ProviderOptions = SharedV3ProviderOptions;
+type ProviderOptions = SharedV4ProviderOptions;
+
+/**
+ * A mapping of provider names to provider-specific file identifiers.
+ *
+ * Provider references allow files to be identified across different
+ * providers without re-uploading, by storing each provider's own
+ * identifier for the same logical file.
+ */
+type ProviderReference = SharedV4ProviderReference;
 
 /**
  * Text content part of a prompt. It contains a string of text.
@@ -577,8 +622,9 @@ interface ImagePart {
      *
      * - data: a base64-encoded string, a Uint8Array, an ArrayBuffer, or a Buffer
      * - URL: a URL that points to the image
+     * - ProviderReference: a provider reference from `uploadFile`
      */
-    image: DataContent | URL;
+    image: DataContent | URL | ProviderReference;
     /**
      * Optional IANA media type of the image.
      *
@@ -601,9 +647,10 @@ interface FilePart {
      * File data. Can either be:
      *
      * - data: a base64-encoded string, a Uint8Array, an ArrayBuffer, or a Buffer
-     * - URL: a URL that points to the image
+     * - URL: a URL that points to the file
+     * - ProviderReference: a provider reference from `uploadFile`
      */
-    data: DataContent | URL;
+    data: DataContent | URL | ProviderReference;
     /**
      * Optional filename of the file.
      */
@@ -637,6 +684,48 @@ interface ReasoningPart {
      */
     providerOptions?: ProviderOptions;
 }
+/**
+ * Custom content part of a prompt. It contains no standardized payload beyond
+ * provider-specific options.
+ */
+interface CustomPart {
+    type: 'custom';
+    /**
+     * The kind of custom content, in the format `{provider}.{provider-type}`.
+     */
+    kind: `${string}.${string}`;
+    /**
+     * Additional provider-specific metadata. They are passed through
+     * to the provider from the AI SDK and enable provider-specific
+     * functionality that can be fully encapsulated in the provider.
+     */
+    providerOptions?: ProviderOptions;
+}
+/**
+ * Reasoning file content part of a prompt. It contains a file generated as part of reasoning.
+ */
+interface ReasoningFilePart {
+    type: 'reasoning-file';
+    /**
+     * File data. Can either be:
+     *
+     * - data: a base64-encoded string, a Uint8Array, an ArrayBuffer, or a Buffer
+     * - URL: a URL that points to the file
+     */
+    data: DataContent | URL;
+    /**
+     * IANA media type of the file.
+     *
+     * @see https://www.iana.org/assignments/media-types/media-types.xhtml
+     */
+    mediaType: string;
+    /**
+     * Additional provider-specific metadata. They are passed through
+     * to the provider from the AI SDK and enable provider-specific
+     * functionality that can be fully encapsulated in the provider.
+     */
+    providerOptions?: ProviderOptions;
+}
 /**
  * Tool call content part of a prompt. It contains a tool call (usually generated by the AI model).
  */
@@ -785,6 +874,9 @@ type ToolResultOutput = {
          */
         providerOptions?: ProviderOptions;
     } | {
+        /**
+         * @deprecated Use file-reference instead.
+         */
         type: 'file-id';
         /**
          * ID of the file.
@@ -799,6 +891,17 @@ type ToolResultOutput = {
          * Provider-specific options.
          */
         providerOptions?: ProviderOptions;
+    } | {
+        type: 'file-reference';
+        /**
+         * Provider-specific references for the file.
+         * The key is the provider name, e.g. 'openai' or 'anthropic'.
+         */
+        providerReference: ProviderReference;
+        /**
+         * Provider-specific options.
+         */
+        providerOptions?: ProviderOptions;
     } | {
         /**
          * Images that are referenced using base64 encoded data.
@@ -832,7 +935,7 @@ type ToolResultOutput = {
         providerOptions?: ProviderOptions;
     } | {
         /**
-         * Images that are referenced using a provider file id.
+         * @deprecated Use image-file-reference instead.
          */
         type: 'image-file-id';
         /**
@@ -848,6 +951,20 @@ type ToolResultOutput = {
          * Provider-specific options.
          */
         providerOptions?: ProviderOptions;
+    } | {
+        /**
+         * Images that are referenced using a provider reference.
+         */
+        type: 'image-file-reference';
+        /**
+         * Provider-specific references for the image file.
+         * The key is the provider name, e.g. 'openai' or 'anthropic'.
+         */
+        providerReference: ProviderReference;
+        /**
+         * Provider-specific options.
+         */
+        providerOptions?: ProviderOptions;
     } | {
         /**
          * Custom content part. This can be used to implement
@@ -893,7 +1010,7 @@ type AssistantModelMessage = {
  * Content of an assistant message.
  * It can be a string or an array of text, image, reasoning, redacted reasoning, and tool call parts.
  */
-type AssistantContent = string | Array<TextPart | FilePart | ReasoningPart | ToolCallPart | ToolResultPart | ToolApprovalRequest>;
+type AssistantContent = string | Array<TextPart | CustomPart | FilePart | ReasoningPart | ReasoningFilePart | ToolCallPart | ToolResultPart | ToolApprovalRequest>;
 
 /**
  * A system message. It can contain system information.
@@ -980,9 +1097,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.
      */
@@ -1008,12 +1130,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.
      */
@@ -1028,11 +1150,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.
@@ -1040,7 +1168,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>;
@@ -1052,7 +1180,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.
@@ -1084,10 +1212,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.
      *
@@ -1100,26 +1236,28 @@ 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.
      *
      * If not provided, the tool result will be sent as a JSON object.
+     *
+     * This function is invoked on the server by `convertToModelMessages`, so ensure that you pass the same "tools" (ToolSet) to both "convertToModelMessages" and "streamText" (or other generation APIs).
      */
     toModelOutput?: (options: {
         /**
@@ -1174,21 +1312,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.
  */
@@ -1197,7 +1327,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.
      *
@@ -1220,32 +1350,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>;
@@ -1260,7 +1390,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.
@@ -1269,6 +1399,16 @@ declare function createProviderToolFactoryWithOutputSchema<INPUT, OUTPUT, ARGS e
  */
 declare function removeUndefinedEntries<T>(record: Record<string, T | undefined>): Record<string, T>;
 
+/**
+ * Resolves a provider reference to the provider-specific identifier for the
+ * given provider. Throws `NoSuchProviderReferenceError` if the provider is not
+ * found in the reference mapping.
+ */
+declare function resolveProviderReference({ reference, provider, }: {
+    reference: SharedV4ProviderReference;
+    provider: string;
+}): string;
+
 type Resolvable<T> = MaybePromiseLike<T> | (() => MaybePromiseLike<T>);
 /**
  * Resolves a value that could be a raw value, a Promise, a function returning a value,
@@ -1354,10 +1494,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;
@@ -1366,6 +1525,52 @@ 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;
+
+/**
+ * A mapping of tool names to tool definitions.
+ */
+type ToolSet = Record<string, (Tool<never, never, any> | Tool<any, any, any> | Tool<any, never, any> | Tool<never, any, any>) & Pick<Tool<any, any, any>, 'execute' | 'onInputAvailable' | 'onInputStart' | 'onInputDelta' | 'needsApproval'>>;
+
+/**
+ * Converts a union type `U` into an intersection type.
+ *
+ * For example:
+ *   type A = { a: number };
+ *   type B = { b: string };
+ *   type Union = A | B;
+ *   type Intersection = UnionToIntersection<Union>;
+ *   // Intersection is: { a: number } & { b: string }
+ *
+ * This is useful when you have a union of object types and need a type with all possible properties.
+ */
+type UnionToIntersection<U> = (U extends unknown ? (arg: U) => void : never) extends (arg: infer I) => void ? I : never;
+
+/**
+ * Infer the context type for a tool set.
+ *
+ * The inferred type contains all properties required by the contexts of the
+ * tools in the set.
+ *
+ * If there are incompatible properties, they will be of type `never`.
+ */
+type InferToolSetContext<TOOLS extends ToolSet> = UnionToIntersection<{
+    [K in keyof TOOLS]: InferToolContext<NoInfer<TOOLS[K]>>;
+}[keyof TOOLS]>;
+
 /**
  * Typed tool call that is returned by generateText and streamText.
  * It contains the tool call ID, the tool name, and the tool arguments.
@@ -1425,9 +1630,4 @@ interface ToolResult<NAME extends string, INPUT, OUTPUT> {
     dynamic?: boolean;
 }
 
-/**
- * @deprecated Use ToolExecutionOptions instead.
- */
-type ToolCallOptions = ToolExecutionOptions;
-
-export { type AssistantContent, type AssistantModelMessage, 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 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, isNonNullable, isParsableJson, isUrlSupported, jsonSchema, lazySchema, loadApiKey, loadOptionalSetting, loadSetting, 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 InferToolSetContext, type LazySchema, type MaybePromiseLike, type ModelMessage, type ParseResult, type ProviderOptions, type ProviderReference, 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 ToolSet, 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, isProviderReference, isUrlSupported, jsonSchema, lazySchema, loadApiKey, loadOptionalSetting, loadSetting, mapReasoningToProviderBudget, mapReasoningToProviderEffort, mediaTypeToExtension, normalizeHeaders, parseJSON, parseJsonEventStream, parseProviderOptions, postFormDataToApi, postJsonToApi, postToApi, readResponseWithSizeLimit, removeUndefinedEntries, resolve, resolveProviderReference, safeParseJSON, safeValidateTypes, stripFileExtension, tool, validateDownloadUrl, validateTypes, withUserAgentSuffix, withoutTrailingSlash, zodSchema };