@ai-sdk/provider-utils 5.0.0-beta.2 → 5.0.0-beta.21

package/dist/index.d.ts

@@ -1,8 +1,10 @@
-import { LanguageModelV3FunctionTool, LanguageModelV3ProviderTool, ImageModelV3File, AISDKError, JSONSchema7, JSONParseError, TypeValidationError, JSONValue, APICallError, LanguageModelV3Prompt, SharedV3ProviderOptions, TypeValidationContext } from '@ai-sdk/provider';
+import { ImageModelV4File, LanguageModelV4FunctionTool, LanguageModelV4ProviderTool, AISDKError, JSONSchema7, JSONParseError, TypeValidationError, JSONValue, APICallError, LanguageModelV4Prompt, LanguageModelV4FilePart, SharedV4ProviderReference, LanguageModelV4CallOptions, SharedV4Warning, SharedV4ProviderOptions, JSONObject, TypeValidationContext } from '@ai-sdk/provider';
+export { getErrorMessage } from '@ai-sdk/provider';
 import { StandardSchemaV1, StandardJSONSchemaV1 } from '@standard-schema/spec';
 export * from '@standard-schema/spec';
 import * as z3 from 'zod/v3';
 import * as z4 from 'zod/v4';
+export { WORKFLOW_DESERIALIZE, WORKFLOW_SERIALIZE } from '@workflow/serde';
 export { EventSourceMessage, EventSourceParserStream } from 'eventsource-parser/stream';
 
 declare function combineHeaders(...headers: Array<Record<string, string | undefined> | undefined>): Record<string, string | undefined>;
@@ -16,6 +18,50 @@ declare function combineHeaders(...headers: Array<Record<string, string | undefi
  */
 declare function convertAsyncIteratorToReadableStream<T>(iterator: AsyncIterator<T>): ReadableStream<T>;
 
+/**
+ * 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: ImageModelV4File): string;
+
+/**
+ * Converts an input object to FormData for multipart/form-data requests.
+ *
+ * Handles the following cases:
+ * - `null` or `undefined` values are skipped
+ * - Arrays with a single element are appended as a single value
+ * - Arrays with multiple elements are appended with `[]` suffix (e.g., `image[]`)
+ *   unless `useArrayBrackets` is set to `false`
+ * - All other values are appended directly
+ *
+ * @param input - The input object to convert. Use a generic type for type validation.
+ * @param options - Optional configuration object.
+ * @param options.useArrayBrackets - Whether to add `[]` suffix for multi-element arrays.
+ *   Defaults to `true`. Set to `false` for APIs that expect repeated keys without brackets.
+ * @returns A FormData object containing the input values.
+ *
+ * @example
+ * ```ts
+ * type MyInput = {
+ *   model: string;
+ *   prompt: string;
+ *   images: Blob[];
+ * };
+ *
+ * const formData = convertToFormData<MyInput>({
+ *   model: 'gpt-image-1',
+ *   prompt: 'A cat',
+ *   images: [blob1, blob2],
+ * });
+ * ```
+ */
+declare function convertToFormData<T extends Record<string, unknown>>(input: T, options?: {
+    useArrayBrackets?: boolean;
+}): FormData;
+
 /**
  * Interface for mapping between custom tool names and provider tool names.
  */
@@ -41,20 +87,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;
 
 /**
@@ -86,60 +127,6 @@ declare class DelayedPromise<T> {
     isPending(): boolean;
 }
 
-/**
- * Extracts the headers from a response object and returns them as a key-value object.
- *
- * @param response - The response object to extract headers from.
- * @returns The headers as a key-value object.
- */
-declare function extractResponseHeaders(response: Response): {
-    [k: string]: string;
-};
-
-/**
- * Convert an ImageModelV3File 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;
-
-/**
- * Converts an input object to FormData for multipart/form-data requests.
- *
- * Handles the following cases:
- * - `null` or `undefined` values are skipped
- * - Arrays with a single element are appended as a single value
- * - Arrays with multiple elements are appended with `[]` suffix (e.g., `image[]`)
- *   unless `useArrayBrackets` is set to `false`
- * - All other values are appended directly
- *
- * @param input - The input object to convert. Use a generic type for type validation.
- * @param options - Optional configuration object.
- * @param options.useArrayBrackets - Whether to add `[]` suffix for multi-element arrays.
- *   Defaults to `true`. Set to `false` for APIs that expect repeated keys without brackets.
- * @returns A FormData object containing the input values.
- *
- * @example
- * ```ts
- * type MyInput = {
- *   model: string;
- *   prompt: string;
- *   images: Blob[];
- * };
- *
- * const formData = convertToFormData<MyInput>({
- *   model: 'gpt-image-1',
- *   prompt: 'A cat',
- *   images: [blob1, blob2],
- * });
- * ```
- */
-declare function convertToFormData<T extends Record<string, unknown>>(input: T, options?: {
-    useArrayBrackets?: boolean;
-}): FormData;
-
 /**
  * Download a file from a URL and return it as a Blob.
  *
@@ -173,35 +160,14 @@ declare class DownloadError extends AISDKError {
 }
 
 /**
- * Default maximum download size: 2 GiB.
- *
- * `fetch().arrayBuffer()` has ~2x peak memory overhead (undici buffers the
- * body internally, then creates the JS ArrayBuffer), so very large downloads
- * risk exceeding the default V8 heap limit on 64-bit systems and terminating
- * the process with an out-of-memory error.
- *
- * Setting this limit converts an unrecoverable OOM crash into a catchable
- * `DownloadError`.
- */
-declare const DEFAULT_MAX_DOWNLOAD_SIZE: number;
-/**
- * Reads a fetch Response body with a size limit to prevent memory exhaustion.
- *
- * Checks the Content-Length header for early rejection, then reads the body
- * incrementally via ReadableStream and aborts with a DownloadError when the
- * limit is exceeded.
+ * Extracts the headers from a response object and returns them as a key-value object.
  *
- * @param response - The fetch Response to read.
- * @param url - The URL being downloaded (used in error messages).
- * @param maxBytes - Maximum allowed bytes. Defaults to DEFAULT_MAX_DOWNLOAD_SIZE.
- * @returns A Uint8Array containing the response body.
- * @throws DownloadError if the response exceeds maxBytes.
+ * @param response - The response object to extract headers from.
+ * @returns The headers as a key-value object.
  */
-declare function readResponseWithSizeLimit({ response, url, maxBytes, }: {
-    response: Response;
-    url: string;
-    maxBytes?: number;
-}): Promise<Uint8Array>;
+declare function extractResponseHeaders(response: Response): {
+    [k: string]: string;
+};
 
 /**
  * Fetch function type (standardizes the version of fetch used).
@@ -234,8 +200,6 @@ type IdGenerator = () => string;
  */
 declare const generateId: IdGenerator;
 
-declare function getErrorMessage(error: unknown | undefined): string;
-
 /**
  * Used to mark schemas so we can support both Zod and custom schemas.
  */
@@ -389,12 +353,19 @@ declare const getFromApi: <T>({ url, headers, successfulResponseHandler, failedR
 
 declare function getRuntimeEnvironmentUserAgent(globalThisAny?: any): string;
 
+/**
+ * Checks if an object has required keys.
+ * @param OBJECT - The object to check.
+ * @returns True if the object has required keys, false otherwise.
+ */
+type HasRequiredKey<OBJECT> = {} extends OBJECT ? false : true;
+
 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 +378,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.
  *
@@ -459,6 +436,41 @@ declare function loadSetting({ settingValue, environmentVariableName, settingNam
     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;
+
 type MaybePromiseLike<T> = T | PromiseLike<T>;
 
 /**
@@ -549,7 +561,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 +598,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 +623,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 +660,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).
  */
@@ -748,13 +813,6 @@ type ToolResultOutput = {
          * Provider-specific options.
          */
         providerOptions?: ProviderOptions;
-    } | {
-        /**
-         * @deprecated Use image-data or file-data instead.
-         */
-        type: 'media';
-        data: string;
-        mediaType: string;
     } | {
         type: 'file-data';
         /**
@@ -780,11 +838,19 @@ type ToolResultOutput = {
          * URL of the file.
          */
         url: string;
+        /**
+         * IANA media type.
+         * @see https://www.iana.org/assignments/media-types/media-types.xhtml
+         */
+        mediaType?: string;
         /**
          * Provider-specific options.
          */
         providerOptions?: ProviderOptions;
     } | {
+        /**
+         * @deprecated Use file-reference instead.
+         */
         type: 'file-id';
         /**
          * ID of the file.
@@ -799,9 +865,20 @@ 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.
+         * @deprecated Use file-data instead.
          */
         type: 'image-data';
         /**
@@ -819,7 +896,7 @@ type ToolResultOutput = {
         providerOptions?: ProviderOptions;
     } | {
         /**
-         * Images that are referenced using a URL.
+         * @deprecated Use file-url instead.
          */
         type: 'image-url';
         /**
@@ -832,7 +909,7 @@ type ToolResultOutput = {
         providerOptions?: ProviderOptions;
     } | {
         /**
-         * Images that are referenced using a provider file id.
+         * @deprecated Use file-reference instead.
          */
         type: 'image-file-id';
         /**
@@ -848,6 +925,20 @@ type ToolResultOutput = {
          * Provider-specific options.
          */
         providerOptions?: ProviderOptions;
+    } | {
+        /**
+         * @deprecated Use file-reference instead.
+         */
+        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 +984,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 +1071,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 | unknown | never> {
     /**
      * The ID of the tool call. You can use it e.g. when sending tool-call related information with stream data.
      */
@@ -997,7 +1093,7 @@ interface ToolExecutionOptions {
      */
     abortSignal?: AbortSignal;
     /**
-     * User-defined context.
+     * User-defined runtime context.
      *
      * Treat the context object as immutable inside tools.
      * Mutating the context object can lead to race conditions and unexpected results
@@ -1005,15 +1101,13 @@ interface ToolExecutionOptions {
      *
      * If you need to mutate the context, analyze the tool calls and results
      * in `prepareStep` and update it there.
-     *
-     * Experimental (can break in patch releases).
      */
-    experimental_context?: unknown;
+    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 | unknown | never> = (input: INPUT, options: {
     /**
      * The ID of the tool call. You can use it e.g. when sending tool-call related information with stream data.
      */
@@ -1024,15 +1118,26 @@ type ToolNeedsApprovalFunction<INPUT> = (input: INPUT, options: {
      */
     messages: ModelMessage[];
     /**
-     * Additional context.
+     * User-defined runtime context.
+     *
+     * Treat the context object as immutable inside tools.
+     * Mutating the context object can lead to race conditions and unexpected results
+     * when tools are called in parallel.
      *
-     * Experimental (can break in patch releases).
+     * If you need to mutate the context, analyze the tool calls and results
+     * in `prepareStep` and update it there.
      */
-    experimental_context?: unknown;
+    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 | unknown | never> = (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 | unknown | never> = 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 +1145,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 +1157,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 | unknown | never = any> = {
     /**
      * An optional description of what the tool does.
      * Will be used by the language model to decide whether to use the tool.
@@ -1084,10 +1189,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 +1213,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 +1289,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 +1304,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 +1327,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 +1367,38 @@ declare function createProviderToolFactoryWithOutputSchema<INPUT, OUTPUT, ARGS e
      * @default false
      */
     supportsDeferredResults?: boolean;
-}): ProviderToolFactoryWithOutputSchema<INPUT, OUTPUT, ARGS>;
+}): ProviderToolFactoryWithOutputSchema<INPUT, OUTPUT, ARGS, CONTEXT>;
+
+/**
+ * Default maximum download size: 2 GiB.
+ *
+ * `fetch().arrayBuffer()` has ~2x peak memory overhead (undici buffers the
+ * body internally, then creates the JS ArrayBuffer), so very large downloads
+ * risk exceeding the default V8 heap limit on 64-bit systems and terminating
+ * the process with an out-of-memory error.
+ *
+ * Setting this limit converts an unrecoverable OOM crash into a catchable
+ * `DownloadError`.
+ */
+declare const DEFAULT_MAX_DOWNLOAD_SIZE: number;
+/**
+ * Reads a fetch Response body with a size limit to prevent memory exhaustion.
+ *
+ * Checks the Content-Length header for early rejection, then reads the body
+ * incrementally via ReadableStream and aborts with a DownloadError when the
+ * limit is exceeded.
+ *
+ * @param response - The fetch Response to read.
+ * @param url - The URL being downloaded (used in error messages).
+ * @param maxBytes - Maximum allowed bytes. Defaults to DEFAULT_MAX_DOWNLOAD_SIZE.
+ * @returns A Uint8Array containing the response body.
+ * @throws DownloadError if the response exceeds maxBytes.
+ */
+declare function readResponseWithSizeLimit({ response, url, maxBytes, }: {
+    response: Response;
+    url: string;
+    maxBytes?: number;
+}): Promise<Uint8Array>;
 
 /**
  * Removes entries from a record where the value is null or undefined.
@@ -1269,6 +1407,21 @@ declare function createProviderToolFactoryWithOutputSchema<INPUT, OUTPUT, ARGS e
  */
 declare function removeUndefinedEntries<T>(record: Record<string, T | undefined>): Record<string, T>;
 
+/**
+ * A value or a lazy provider of a value, each of which may be synchronous or asynchronous.
+ *
+ * @template T The resolved type after {@link resolve} runs.
+ *
+ * One of:
+ * - A plain value of type {@link T}
+ * - A {@link PromiseLike} of {@link T} (e.g. a `Promise<T>`)
+ * - A zero-argument function that returns a plain {@link T}
+ * - A zero-argument function that returns a {@link PromiseLike} of {@link T}
+ *
+ * The function form is only invoked when passed to {@link resolve}; it is not distinguished from
+ * a {@link T} that happens to be a function—callers should wrap function values if disambiguation
+ * is required.
+ */
 type Resolvable<T> = MaybePromiseLike<T> | (() => MaybePromiseLike<T>);
 /**
  * Resolves a value that could be a raw value, a Promise, a function returning a value,
@@ -1276,6 +1429,46 @@ type Resolvable<T> = MaybePromiseLike<T> | (() => MaybePromiseLike<T>);
  */
 declare function resolve<T>(value: Resolvable<T>): Promise<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;
+
+/**
+ * Serializes a model instance for workflow step boundaries.
+ * Returns the `modelId` plus the JSON-serializable config properties.
+ *
+ * Non-serializable values are omitted. As a special case, a
+ * function-valued `headers` property is resolved during serialization
+ * and included if the returned value is JSON-serializable.
+ *
+ * Used as the body of `static [WORKFLOW_SERIALIZE]` in provider models.
+ *
+ * @example
+ * ```ts
+ * static [WORKFLOW_SERIALIZE](model: MyLanguageModel) {
+ *   return serializeModelOptions({
+ *     modelId: model.modelId,
+ *     config: model.config,
+ *   });
+ * }
+ * ```
+ */
+declare function serializeModelOptions<CONFIG extends {
+    headers?: Resolvable<Record<string, string | undefined>>;
+}>(options: {
+    modelId: string;
+    config: CONFIG;
+}): {
+    modelId: string;
+    config: JSONObject;
+};
+
 /**
  * Strips file extension segments from a filename.
  *
@@ -1354,18 +1547,89 @@ 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>;
-    input: INPUT;
-    options: ToolExecutionOptions;
+/**
+ * A tool that is guaranteed to expose an execute function.
+ */
+type ExecutableTool<TOOL extends Tool = Tool> = TOOL & {
+    execute: NonNullable<TOOL['execute']>;
+};
+/**
+ * Checks whether a tool exposes an execute function.
+ */
+declare function isExecutableTool<TOOL extends Tool>(tool: TOOL | undefined): tool is ExecutableTool<TOOL>;
+
+/**
+ * Infer the context type of a tool.
+ */
+type InferToolContext<TOOL extends Tool> = TOOL extends Tool<any, any, infer CONTEXT> ? HasRequiredKey<CONTEXT> extends true ? CONTEXT : never : 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;
+
+/**
+ * Executes a tool function and normalizes its results into a stream of outputs.
+ *
+ * - If the tool's `execute` function returns an `AsyncIterable`, each yielded value is emitted as
+ *   `{ type: "preliminary", output }`. After iteration completes, the last yielded value is emitted
+ *   again as `{ type: "final", output }`.
+ * - If the tool returns a direct value or Promise, a single `{ type: "final", output }` is yielded.
+ *
+ * @param params.tool The tool whose `execute` function should be invoked.
+ * @param params.input The input value to pass to the tool.
+ * @param params.options Additional options for tool execution.
+ * @yields A preliminary output for each streamed value, followed by a final output, or a single final
+ * output for non-streaming tools.
+ */
+declare function executeTool<TOOL extends Tool>({ tool, input, options, }: {
+    tool: ExecutableTool<TOOL>;
+    input: InferToolInput<TOOL>;
+    options: ToolExecutionOptions<InferToolContext<TOOL>>;
 }): AsyncGenerator<{
     type: 'preliminary';
-    output: OUTPUT;
+    output: InferToolOutput<TOOL>;
 } | {
     type: 'final';
-    output: OUTPUT;
+    output: InferToolOutput<TOOL>;
 }>;
 
+/**
+ * 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 +1689,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 ExecutableTool, type FetchFunction, type FilePart, type FlexibleSchema, type HasRequiredKey, 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, getFromApi, getRuntimeEnvironmentUserAgent, injectJsonInstructionIntoMessages, isAbortError, isCustomReasoning, isExecutableTool, 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, serializeModelOptions, stripFileExtension, tool, validateDownloadUrl, validateTypes, withUserAgentSuffix, withoutTrailingSlash, zodSchema };