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

package/dist/test/index.js

@@ -18,8 +18,8 @@ var __copyProps = (to, from, except, desc) => {
 var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
 
 // src/test/index.ts
-var test_exports = {};
-__export(test_exports, {
+var index_exports = {};
+__export(index_exports, {
   convertArrayToAsyncIterable: () => convertArrayToAsyncIterable,
   convertArrayToReadableStream: () => convertArrayToReadableStream,
   convertAsyncIterableToArray: () => convertAsyncIterableToArray,
@@ -28,7 +28,7 @@ __export(test_exports, {
   isNodeVersion: () => isNodeVersion,
   mockId: () => mockId
 });
-module.exports = __toCommonJS(test_exports);
+module.exports = __toCommonJS(index_exports);
 
 // src/test/convert-array-to-async-iterable.ts
 function convertArrayToAsyncIterable(values) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ai-sdk/provider-utils",
-  "version": "5.0.0-beta.0",
+  "version": "5.0.0-beta.10",
   "license": "Apache-2.0",
   "sideEffects": false,
   "main": "./dist/index.js",
@@ -35,7 +35,7 @@
   "dependencies": {
     "@standard-schema/spec": "^1.1.0",
     "eventsource-parser": "^3.0.6",
-    "@ai-sdk/provider": "4.0.0-beta.0"
+    "@ai-sdk/provider": "4.0.0-beta.6"
   },
   "devDependencies": {
     "@types/node": "20.17.24",
@@ -69,9 +69,7 @@
     "build": "pnpm clean && tsup --tsconfig tsconfig.build.json",
     "build:watch": "pnpm clean && tsup --watch",
     "clean": "del-cli dist *.tsbuildinfo",
-    "lint": "eslint \"./**/*.ts*\"",
     "type-check": "tsc --build",
-    "prettier-check": "prettier --check \"./**/*.ts*\"",
     "test": "pnpm test:node && pnpm test:edge",
     "test:update": "pnpm test:node -u",
     "test:watch": "vitest --config vitest.node.config.js",

package/src/convert-image-model-file-to-data-uri.ts

@@ -1,14 +1,14 @@
-import { ImageModelV3File } from '@ai-sdk/provider';
+import { ImageModelV4File } from '@ai-sdk/provider';
 import { convertUint8ArrayToBase64 } from './uint8-utils';
 
 /**
- * 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.
  */
-export function convertImageModelFileToDataUri(file: ImageModelV3File): string {
+export function convertImageModelFileToDataUri(file: ImageModelV4File): string {
   if (file.type === 'url') return file.url;
 
   return `data:${file.mediaType};base64,${

package/src/create-tool-name-mapping.ts

@@ -1,6 +1,6 @@
 import {
-  LanguageModelV3FunctionTool,
-  LanguageModelV3ProviderTool,
+  LanguageModelV4FunctionTool,
+  LanguageModelV4ProviderTool,
 } from '@ai-sdk/provider';
 
 /**
@@ -33,41 +33,25 @@ export interface ToolNameMapping {
 export function createToolNameMapping({
   tools = [],
   providerToolNames,
-  resolveProviderToolName,
 }: {
   /**
    * Tools that were passed to the language model.
    */
   tools:
-    | Array<LanguageModelV3FunctionTool | LanguageModelV3ProviderTool>
+    | 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 {
   const customToolNameToProviderToolName: Record<string, string> = {};
   const providerToolNameToCustomToolName: Record<string, string> = {};
 
   for (const tool of tools) {
-    if (tool.type === 'provider') {
-      const providerToolName =
-        resolveProviderToolName?.(tool) ??
-        (tool.id in providerToolNames ? providerToolNames[tool.id] : undefined);
-
-      if (providerToolName == null) {
-        continue;
-      }
-
+    if (tool.type === 'provider' && tool.id in providerToolNames) {
+      const providerToolName = providerToolNames[tool.id];
       customToolNameToProviderToolName[tool.name] = providerToolName;
       providerToolNameToCustomToolName[providerToolName] = tool.name;
     }

package/src/download-blob.ts

@@ -26,6 +26,11 @@ export async function downloadBlob(
       signal: options?.abortSignal,
     });
 
+    // Validate final URL after redirects to prevent SSRF via open redirect
+    if (response.redirected) {
+      validateDownloadUrl(response.url);
+    }
+
     if (!response.ok) {
       throw new DownloadError({
         url,

package/src/index.ts

@@ -23,8 +23,14 @@ export { getRuntimeEnvironmentUserAgent } from './get-runtime-environment-user-a
 export { injectJsonInstructionIntoMessages } from './inject-json-instruction';
 export * from './is-abort-error';
 export { isNonNullable } from './is-non-nullable';
+export { isProviderReference } from './is-provider-reference';
 export { isUrlSupported } from './is-url-supported';
 export * from './load-api-key';
+export {
+  isCustomReasoning,
+  mapReasoningToProviderBudget,
+  mapReasoningToProviderEffort,
+} from './map-reasoning-to-provider';
 export { loadOptionalSetting } from './load-optional-setting';
 export { loadSetting } from './load-setting';
 export { type MaybePromiseLike } from './maybe-promise-like';
@@ -41,6 +47,7 @@ export {
   type ProviderToolFactoryWithOutputSchema,
 } from './provider-tool-factory';
 export * from './remove-undefined-entries';
+export { resolveProviderReference } from './resolve-provider-reference';
 export * from './resolve';
 export * from './response-handler';
 export {

package/src/inject-json-instruction.ts

@@ -1,7 +1,7 @@
 import {
   JSONSchema7,
-  LanguageModelV3Message,
-  LanguageModelV3Prompt,
+  LanguageModelV4Message,
+  LanguageModelV4Prompt,
 } from '@ai-sdk/provider';
 
 const DEFAULT_SCHEMA_PREFIX = 'JSON schema:';
@@ -39,12 +39,12 @@ export function injectJsonInstructionIntoMessages({
   schemaPrefix,
   schemaSuffix,
 }: {
-  messages: LanguageModelV3Prompt;
+  messages: LanguageModelV4Prompt;
   schema?: JSONSchema7;
   schemaPrefix?: string;
   schemaSuffix?: string;
-}): LanguageModelV3Prompt {
-  const systemMessage: LanguageModelV3Message =
+}): LanguageModelV4Prompt {
+  const systemMessage: LanguageModelV4Message =
     messages[0]?.role === 'system'
       ? { ...messages[0] }
       : { role: 'system', content: '' };

package/src/is-provider-reference.ts

@@ -0,0 +1,18 @@
+import {
+  LanguageModelV4FilePart,
+  SharedV4ProviderReference,
+} from '@ai-sdk/provider';
+
+/**
+ * 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.
+ */
+export function isProviderReference(
+  data: LanguageModelV4FilePart['data'],
+): data is SharedV4ProviderReference {
+  return (
+    typeof data === 'object' &&
+    !(data instanceof Uint8Array) &&
+    !(data instanceof URL)
+  );
+}

package/src/map-reasoning-to-provider.ts

@@ -0,0 +1,105 @@
+import { LanguageModelV4CallOptions, SharedV4Warning } from '@ai-sdk/provider';
+
+export type ReasoningLevel = Exclude<
+  LanguageModelV4CallOptions['reasoning'],
+  'none' | 'provider-default' | undefined
+>;
+
+export function isCustomReasoning(
+  reasoning: LanguageModelV4CallOptions['reasoning'],
+): reasoning is Exclude<
+  LanguageModelV4CallOptions['reasoning'],
+  'provider-default' | undefined
+> {
+  return reasoning !== undefined && reasoning !== 'provider-default';
+}
+
+/**
+ * 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.
+ */
+export function mapReasoningToProviderEffort<T extends string>({
+  reasoning,
+  effortMap,
+  warnings,
+}: {
+  reasoning: ReasoningLevel;
+  effortMap: Partial<Record<ReasoningLevel, T>>;
+  warnings: SharedV4Warning[];
+}): T | undefined {
+  const mapped = effortMap[reasoning];
+
+  if (mapped == null) {
+    warnings.push({
+      type: 'unsupported',
+      feature: 'reasoning',
+      details: `reasoning "${reasoning}" is not supported by this model.`,
+    });
+    return undefined;
+  }
+
+  if (mapped !== reasoning) {
+    warnings.push({
+      type: 'compatibility',
+      feature: 'reasoning',
+      details: `reasoning "${reasoning}" is not directly supported by this model. mapped to effort "${mapped}".`,
+    });
+  }
+
+  return mapped;
+}
+
+const DEFAULT_REASONING_BUDGET_PERCENTAGES: Record<ReasoningLevel, number> = {
+  minimal: 0.02,
+  low: 0.1,
+  medium: 0.3,
+  high: 0.6,
+  xhigh: 0.9,
+};
+
+/**
+ * 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.
+ */
+export function mapReasoningToProviderBudget({
+  reasoning,
+  maxOutputTokens,
+  maxReasoningBudget,
+  minReasoningBudget = 1024,
+  budgetPercentages = DEFAULT_REASONING_BUDGET_PERCENTAGES,
+  warnings,
+}: {
+  reasoning: ReasoningLevel;
+  maxOutputTokens: number;
+  maxReasoningBudget: number;
+  minReasoningBudget?: number;
+  budgetPercentages?: Partial<Record<ReasoningLevel, number>>;
+  warnings: SharedV4Warning[];
+}): number | undefined {
+  const pct = budgetPercentages[reasoning];
+
+  if (pct == null) {
+    warnings.push({
+      type: 'unsupported',
+      feature: 'reasoning',
+      details: `reasoning "${reasoning}" is not supported by this model.`,
+    });
+    return undefined;
+  }
+
+  return Math.min(
+    maxReasoningBudget,
+    Math.max(minReasoningBudget, Math.round(maxOutputTokens * pct)),
+  );
+}

package/src/provider-tool-factory.ts

@@ -1,24 +1,33 @@
 import { tool, Tool, ToolExecuteFunction } from './types/tool';
 import { FlexibleSchema } from './schema';
+import { Context } from './types/context';
 
-export type ProviderToolFactory<INPUT, ARGS extends object> = <OUTPUT>(
+export type ProviderToolFactory<
+  INPUT,
+  ARGS extends object,
+  CONTEXT extends Context = {},
+> = <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'];
+    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>;
+) => Tool<INPUT, OUTPUT, CONTEXT>;
 
-export function createProviderToolFactory<INPUT, ARGS extends object>({
+export function createProviderToolFactory<
+  INPUT,
+  ARGS extends object,
+  CONTEXT extends Context = {},
+>({
   id,
   inputSchema,
 }: {
   id: `${string}.${string}`;
   inputSchema: FlexibleSchema<INPUT>;
-}): ProviderToolFactory<INPUT, ARGS> {
+}): ProviderToolFactory<INPUT, ARGS, CONTEXT> {
   return <OUTPUT>({
     execute,
     outputSchema,
@@ -29,14 +38,14 @@ export function createProviderToolFactory<INPUT, ARGS extends object>({
     onInputAvailable,
     ...args
   }: ARGS & {
-    execute?: ToolExecuteFunction<INPUT, OUTPUT>;
+    execute?: ToolExecuteFunction<INPUT, OUTPUT, CONTEXT>;
     outputSchema?: FlexibleSchema<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> =>
+    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> =>
     tool({
       type: 'provider',
       id,
@@ -56,21 +65,23 @@ export type ProviderToolFactoryWithOutputSchema<
   INPUT,
   OUTPUT,
   ARGS extends object,
+  CONTEXT extends Context = {},
 > = (
   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'];
+    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>;
+) => Tool<INPUT, OUTPUT, CONTEXT>;
 
 export function createProviderToolFactoryWithOutputSchema<
   INPUT,
   OUTPUT,
   ARGS extends object,
+  CONTEXT extends Context = {},
 >({
   id,
   inputSchema,
@@ -91,7 +102,7 @@ export function createProviderToolFactoryWithOutputSchema<
    * @default false
    */
   supportsDeferredResults?: boolean;
-}): ProviderToolFactoryWithOutputSchema<INPUT, OUTPUT, ARGS> {
+}): ProviderToolFactoryWithOutputSchema<INPUT, OUTPUT, ARGS, CONTEXT> {
   return ({
     execute,
     needsApproval,
@@ -101,13 +112,13 @@ export function createProviderToolFactoryWithOutputSchema<
     onInputAvailable,
     ...args
   }: 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> =>
+    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> =>
     tool({
       type: 'provider',
       id,

package/src/resolve-provider-reference.ts

@@ -0,0 +1,27 @@
+import {
+  NoSuchProviderReferenceError,
+  SharedV4ProviderReference,
+} from '@ai-sdk/provider';
+
+/**
+ * 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.
+ */
+export function resolveProviderReference({
+  reference,
+  provider,
+}: {
+  reference: SharedV4ProviderReference;
+  provider: string;
+}): string {
+  const id = reference[provider];
+  if (id != null) {
+    return id;
+  }
+
+  throw new NoSuchProviderReferenceError({
+    provider,
+    reference,
+  });
+}

package/src/types/assistant-model-message.ts

@@ -1,5 +1,7 @@
 import {
+  CustomPart,
   FilePart,
+  ReasoningFilePart,
   ReasoningPart,
   TextPart,
   ToolCallPart,
@@ -31,8 +33,10 @@ export type AssistantContent =
   | string
   | Array<
       | TextPart
+      | CustomPart
       | FilePart
       | ReasoningPart
+      | ReasoningFilePart
       | ToolCallPart
       | ToolResultPart
       | ToolApprovalRequest

package/src/types/content-part.ts

@@ -1,6 +1,7 @@
 import { JSONValue } from '@ai-sdk/provider';
 import { DataContent } from './data-content';
 import { ProviderOptions } from './provider-options';
+import { ProviderReference } from './provider-reference';
 
 /**
  * Text content part of a prompt. It contains a string of text.
@@ -32,8 +33,9 @@ export 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.
@@ -60,9 +62,10 @@ export 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.
@@ -103,6 +106,55 @@ export interface ReasoningPart {
   providerOptions?: ProviderOptions;
 }
 
+/**
+ * Custom content part of a prompt. It contains no standardized payload beyond
+ * provider-specific options.
+ */
+export 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.
+ */
+export 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).
  */
@@ -287,6 +339,9 @@ export type ToolResultOutput =
             providerOptions?: ProviderOptions;
           }
         | {
+            /**
+             * @deprecated Use file-reference instead.
+             */
             type: 'file-id';
 
             /**
@@ -299,6 +354,20 @@ export type ToolResultOutput =
              */
             fileId: string | Record<string, string>;
 
+            /**
+             * 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.
              */
@@ -344,7 +413,7 @@ export type ToolResultOutput =
           }
         | {
             /**
-             * Images that are referenced using a provider file id.
+             * @deprecated Use image-file-reference instead.
              */
             type: 'image-file-id';
 
@@ -358,6 +427,23 @@ export type ToolResultOutput =
              */
             fileId: string | Record<string, string>;
 
+            /**
+             * 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.
              */

package/src/types/context.ts

@@ -0,0 +1,4 @@
+/**
+ * A context object that is passed into tool execution.
+ */
+export type Context = Record<string, unknown>;

package/src/types/execute-tool.ts

@@ -1,14 +1,34 @@
 import { isAsyncIterable } from '../is-async-iterable';
-import { ToolExecutionOptions, ToolExecuteFunction } from './tool';
+import { Context } from './context';
+import { ToolExecuteFunction, ToolExecutionOptions } from './tool';
 
-export async function* executeTool<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.
+ */
+export async function* executeTool<INPUT, OUTPUT, CONTEXT extends Context>({
   execute,
   input,
   options,
 }: {
-  execute: ToolExecuteFunction<INPUT, OUTPUT>;
+  execute: ToolExecuteFunction<INPUT, OUTPUT, CONTEXT>;
   input: INPUT;
-  options: ToolExecutionOptions;
+  options: ToolExecutionOptions<NoInfer<CONTEXT>>;
 }): AsyncGenerator<
   { type: 'preliminary'; output: OUTPUT } | { type: 'final'; output: OUTPUT }
 > {