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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ai-sdk/provider-utils",
-  "version": "5.0.0-beta.6",
+  "version": "5.0.0-beta.8",
   "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.4"
+    "@ai-sdk/provider": "4.0.0-beta.5"
   },
   "devDependencies": {
     "@types/node": "20.17.24",

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/types/content-part.ts

@@ -111,9 +111,9 @@ export interface CustomPart {
   type: 'custom';
 
   /**
-   * The kind of custom content, in the format `{provider}-{provider-type}`.
+   * The kind of custom content, in the format `{provider}.{provider-type}`.
    */
-  kind: string;
+  kind: `${string}.${string}`;
 
   /**
    * Additional provider-specific metadata. They are passed through

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 }
 > {

package/src/types/index.ts

@@ -13,19 +13,21 @@ export type {
   ToolResultOutput,
   ToolResultPart,
 } from './content-part';
+export type { Context } from './context';
 export type { DataContent } from './data-content';
 export { executeTool } from './execute-tool';
+export type { InferToolContext } from './infer-tool-context';
+export type { InferToolInput } from './infer-tool-input';
+export type { InferToolOutput } from './infer-tool-output';
 export type { ModelMessage } from './model-message';
 export type { ProviderOptions } from './provider-options';
 export type { SystemModelMessage } from './system-model-message';
 export {
   dynamicTool,
   tool,
-  type InferToolInput,
-  type InferToolOutput,
   type Tool,
-  type ToolExecutionOptions,
   type ToolExecuteFunction,
+  type ToolExecutionOptions,
   type ToolNeedsApprovalFunction,
 } from './tool';
 export type { ToolApprovalRequest } from './tool-approval-request';
@@ -34,9 +36,3 @@ export type { ToolCall } from './tool-call';
 export type { ToolContent, ToolModelMessage } from './tool-model-message';
 export type { ToolResult } from './tool-result';
 export type { UserContent, UserModelMessage } from './user-model-message';
-import type { ToolExecutionOptions } from './tool';
-
-/**
- * @deprecated Use ToolExecutionOptions instead.
- */
-export type ToolCallOptions = ToolExecutionOptions;

package/src/types/infer-tool-context.ts

@@ -0,0 +1,7 @@
+import type { Tool } from './tool';
+
+/**
+ * Infer the context type of a tool.
+ */
+export type InferToolContext<TOOL extends Tool<any, any, any>> =
+  TOOL extends Tool<any, any, infer CONTEXT> ? CONTEXT : never;

package/src/types/infer-tool-input.ts

@@ -0,0 +1,7 @@
+import type { Tool } from './tool';
+
+/**
+ * Infer the input type of a tool.
+ */
+export type InferToolInput<TOOL extends Tool<any, any, any>> =
+  TOOL extends Tool<infer INPUT, any, any> ? INPUT : never;

package/src/types/infer-tool-output.ts

@@ -0,0 +1,7 @@
+import type { Tool } from './tool';
+
+/**
+ * Infer the output type of a tool.
+ */
+export type InferToolOutput<TOOL extends Tool<any, any, any>> =
+  TOOL extends Tool<any, infer OUTPUT, any> ? OUTPUT : never;

package/src/types/tool.ts

@@ -3,11 +3,12 @@ import { FlexibleSchema } from '../schema';
 import { ToolResultOutput } from './content-part';
 import { ModelMessage } from './model-message';
 import { ProviderOptions } from './provider-options';
+import { Context } from './context';
 
 /**
- * Additional options that are sent into each tool call.
+ * Additional options that are sent into each tool execution.
  */
-export interface ToolExecutionOptions {
+export 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.
    */
@@ -36,13 +37,13 @@ export 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.
  */
-export type ToolNeedsApprovalFunction<INPUT> = (
+export type ToolNeedsApprovalFunction<INPUT, CONTEXT extends Context> = (
   input: INPUT,
   options: {
     /**
@@ -61,13 +62,16 @@ export type ToolNeedsApprovalFunction<INPUT> = (
      *
      * Experimental (can break in patch releases).
      */
-    experimental_context?: unknown;
+    experimental_context: CONTEXT;
   },
 ) => boolean | PromiseLike<boolean>;
 
-export type ToolExecuteFunction<INPUT, OUTPUT> = (
+/**
+ * Function that executes the tool and returns either a single result or a stream of results.
+ */
+export type ToolExecuteFunction<INPUT, OUTPUT, CONTEXT extends Context> = (
   input: INPUT,
-  options: ToolExecutionOptions,
+  options: ToolExecutionOptions<CONTEXT>,
 ) => AsyncIterable<OUTPUT> | PromiseLike<OUTPUT> | OUTPUT;
 
 // 0 extends 1 & N checks for any
@@ -78,7 +82,14 @@ type NeverOptional<N, T> = 0 extends 1 & N
     ? Partial<Record<keyof T, undefined>>
     : T;
 
-type ToolOutputProperties<INPUT, OUTPUT> = NeverOptional<
+/**
+ * Helper type to determine the output properties of a tool.
+ */
+type ToolOutputProperties<
+  INPUT,
+  OUTPUT,
+  CONTEXT extends Context,
+> = NeverOptional<
   OUTPUT,
   | {
       /**
@@ -88,7 +99,7 @@ type ToolOutputProperties<INPUT, OUTPUT> = NeverOptional<
        * @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>;
     }
@@ -108,6 +119,7 @@ type ToolOutputProperties<INPUT, OUTPUT> = NeverOptional<
 export 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.
@@ -143,12 +155,22 @@ export type Tool<
    */
   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>;
+    | ToolNeedsApprovalFunction<
+        [INPUT] extends [never] ? unknown : INPUT,
+        NoInfer<CONTEXT>
+      >;
 
   /**
    * Strict mode setting for the tool.
@@ -163,14 +185,18 @@ export type Tool<
    * 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,
+    options: { inputTextDelta: string } & ToolExecutionOptions<
+      NoInfer<CONTEXT>
+    >,
   ) => void | PromiseLike<void>;
 
   /**
@@ -180,9 +206,9 @@ export type Tool<
   onInputAvailable?: (
     options: {
       input: [INPUT] extends [never] ? unknown : INPUT;
-    } & ToolExecutionOptions,
+    } & ToolExecutionOptions<NoInfer<CONTEXT>>,
   ) => void | PromiseLike<void>;
-} & ToolOutputProperties<INPUT, OUTPUT> & {
+} & ToolOutputProperties<INPUT, OUTPUT, NoInfer<CONTEXT>> & {
     /**
      * Optional conversion function that maps the tool result to an output that can be used by the language model.
      *
@@ -257,28 +283,22 @@ export type Tool<
       }
   );
 
-/**
- * Infer the input type of a tool.
- */
-export type InferToolInput<TOOL extends Tool> =
-  TOOL extends Tool<infer INPUT, any> ? INPUT : never;
-
-/**
- * Infer the output type of a tool.
- */
-export type InferToolOutput<TOOL extends Tool> =
-  TOOL extends Tool<any, infer OUTPUT> ? OUTPUT : never;
-
 /**
  * Helper function for inferring the execute args of a tool.
  */
 // Note: overload order is important for auto-completion
-export function tool<INPUT, OUTPUT>(
-  tool: Tool<INPUT, OUTPUT>,
-): Tool<INPUT, OUTPUT>;
-export function tool<INPUT>(tool: Tool<INPUT, never>): Tool<INPUT, never>;
-export function tool<OUTPUT>(tool: Tool<never, OUTPUT>): Tool<never, OUTPUT>;
-export function tool(tool: Tool<never, never>): Tool<never, never>;
+export function tool<INPUT, OUTPUT, CONTEXT extends Context>(
+  tool: Tool<INPUT, OUTPUT, CONTEXT>,
+): Tool<INPUT, OUTPUT, CONTEXT>;
+export function tool<INPUT, CONTEXT extends Context>(
+  tool: Tool<INPUT, never, CONTEXT>,
+): Tool<INPUT, never, CONTEXT>;
+export function tool<OUTPUT, CONTEXT extends Context>(
+  tool: Tool<never, OUTPUT, CONTEXT>,
+): Tool<never, OUTPUT, CONTEXT>;
+export function tool<CONTEXT extends Context>(
+  tool: Tool<never, never, CONTEXT>,
+): Tool<never, never, CONTEXT>;
 export function tool(tool: any): any {
   return tool;
 }
@@ -291,7 +311,7 @@ export 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.
@@ -318,8 +338,8 @@ export 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';
 } {
   return { ...tool, type: 'dynamic' };