@ai-sdk/provider-utils 5.0.0-beta.9 → 5.0.0-canary.32

package/src/types/tool.ts

@@ -1,97 +1,33 @@
-import { JSONValue } from '@ai-sdk/provider';
-import { FlexibleSchema } from '../schema';
-import { ToolResultOutput } from './content-part';
-import { ModelMessage } from './model-message';
-import { ProviderOptions } from './provider-options';
-import { Context } from './context';
+import type { JSONValue, SharedV4ProviderMetadata } from '@ai-sdk/provider';
+import type { FlexibleSchema } from '../schema';
+import type { ToolResultOutput } from './content-part';
+import type { Context } from './context';
+import type { NeverOptional } from './never-optional';
+import type { ProviderOptions } from './provider-options';
+import type { SensitiveContext } from './sensitive-context';
+import type {
+  ToolExecuteFunction,
+  ToolExecutionOptions,
+} from './tool-execute-function';
+import type { ToolNeedsApprovalFunction } from './tool-needs-approval-function';
 
 /**
- * Additional options that are sent into each tool execution.
- */
-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.
-   */
-  toolCallId: string;
-
-  /**
-   * Messages that were sent to the language model to initiate the response that contained the tool call.
-   * The messages **do not** include the system prompt nor the assistant response that contained the tool call.
-   */
-  messages: ModelMessage[];
-
-  /**
-   * An optional abort signal that indicates that the overall operation should be aborted.
-   */
-  abortSignal?: AbortSignal;
-
-  /**
-   * User-defined 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.
-   *
-   * 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: CONTEXT;
-}
-
-/**
- * Function that is called to determine if the tool needs approval before it can be executed.
- */
-export 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.
-     */
-    toolCallId: string;
-
-    /**
-     * Messages that were sent to the language model to initiate the response that contained the tool call.
-     * The messages **do not** include the system prompt nor the assistant response that contained the tool call.
-     */
-    messages: ModelMessage[];
-
-    /**
-     * Additional context.
-     *
-     * Experimental (can break in patch releases).
-     */
-    experimental_context: CONTEXT;
-  },
-) => boolean | PromiseLike<boolean>;
-
-/**
- * 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<CONTEXT>,
-) => AsyncIterable<OUTPUT> | PromiseLike<OUTPUT> | OUTPUT;
-
-// 0 extends 1 & N checks for any
-// [N] extends [never] checks for never
-type NeverOptional<N, T> = 0 extends 1 & N
-  ? Partial<T>
-  : [N] extends [never]
-    ? Partial<Record<keyof T, undefined>>
-    : T;
-
-/**
- * Helper type to determine the output properties of a tool.
+ * Helper type to determine the outputSchema and execute function properties of a tool.
  */
 type ToolOutputProperties<
   INPUT,
   OUTPUT,
-  CONTEXT extends Context,
+  CONTEXT extends Context | unknown | never,
 > = NeverOptional<
   OUTPUT,
   | {
+      /**
+       * The optional schema of the output that the tool produces.
+       *
+       * If not provided, the output shape will be inferred from the execute function.
+       */
+      outputSchema?: FlexibleSchema<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.
@@ -100,10 +36,13 @@ type ToolOutputProperties<
        * @options.abortSignal is a signal that can be used to abort the tool call.
        */
       execute: ToolExecuteFunction<INPUT, OUTPUT, CONTEXT>;
-
-      outputSchema?: FlexibleSchema<OUTPUT>;
     }
   | {
+      /**
+       * The schema of the output that the tool produces.
+       *
+       * Required when no execute function is provided.
+       */
       outputSchema: FlexibleSchema<OUTPUT>;
 
       execute?: never;
@@ -111,23 +50,13 @@ type ToolOutputProperties<
 >;
 
 /**
- * A tool contains the description and the schema of the input that the tool expects.
- * This enables the language model to generate the input.
- *
- * The tool can also contain an optional execute function for the actual execution function of the tool.
+ * Common properties shared by all tool kinds.
  */
-export type Tool<
+type BaseTool<
   INPUT extends JSONValue | unknown | never = any,
   OUTPUT extends JSONValue | unknown | never = any,
-  CONTEXT extends Context = Context,
+  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.
-   * Not used for provider-defined tools.
-   */
-  description?: string;
-
   /**
    * An optional title of the tool.
    */
@@ -140,6 +69,17 @@ export type Tool<
    */
   providerOptions?: ProviderOptions;
 
+  /**
+   * Optional metadata about the tool itself (e.g. its source).
+   *
+   * Unlike `providerOptions`, this metadata is not sent to the language
+   * model. Instead, it is propagated onto the resulting tool call's
+   * `providerMetadata` so consumers can read it from tool call / result
+   * parts and UI message parts. This is useful for sources of dynamic
+   * tools (e.g. an MCP server) to identify themselves.
+   */
+  providerMetadata?: SharedV4ProviderMetadata;
+
   /**
    * The schema of the input that the tool expects.
    * The language model will use this to generate the input.
@@ -149,12 +89,6 @@ export type Tool<
    */
   inputSchema: FlexibleSchema<INPUT>;
 
-  /**
-   * An optional list of input examples that show the language
-   * model what the input should look like.
-   */
-  inputExamples?: Array<{ input: NoInfer<INPUT> }>;
-
   /**
    * An optional schema describing the context that the tool expects.
    *
@@ -162,8 +96,16 @@ export type Tool<
    */
   contextSchema?: FlexibleSchema<CONTEXT>;
 
+  /**
+   * Marks top-level context properties that contain sensitive data and should be excluded from telemetry.
+   * Properties marked as `true` are omitted from telemetry integrations.
+   */
+  sensitiveContext?: SensitiveContext<CONTEXT>;
+
   /**
    * Whether the tool needs approval before it can be executed.
+   *
+   * @deprecated Tool approval is handled on a `generateText` / `streamText` level now.
    */
   needsApproval?:
     | boolean
@@ -172,15 +114,6 @@ export type Tool<
         NoInfer<CONTEXT>
       >;
 
-  /**
-   * Strict mode setting for the tool.
-   *
-   * Providers that support strict mode will use this setting to determine
-   * how the input should be generated. Strict mode will always produce
-   * valid inputs, but it might limit what input schemas are supported.
-   */
-  strict?: boolean;
-
   /**
    * Optional function that is called when the argument streaming starts.
    * Only called when the tool is used in a streaming context.
@@ -208,83 +141,196 @@ export type Tool<
       input: [INPUT] extends [never] ? unknown : INPUT;
     } & 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: {
     /**
-     * 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).
+     * The ID of the tool call. You can use it e.g. when sending tool-call related information with stream data.
      */
-    toModelOutput?: (options: {
-      /**
-       * The ID of the tool call. You can use it e.g. when sending tool-call related information with stream data.
-       */
-      toolCallId: string;
+    toolCallId: string;
 
-      /**
-       * The input of the tool call.
-       */
-      input: [INPUT] extends [never] ? unknown : INPUT;
+    /**
+     * The input of the tool call.
+     */
+    input: [INPUT] extends [never] ? unknown : INPUT;
 
-      /**
-       * The output of the tool call.
-       */
-      output: 0 extends 1 & OUTPUT
+    /**
+     * The output of the tool call.
+     */
+    output: 0 extends 1 & OUTPUT
+      ? any
+      : [OUTPUT] extends [never]
         ? any
-        : [OUTPUT] extends [never]
-          ? any
-          : NoInfer<OUTPUT>;
-    }) => ToolResultOutput | PromiseLike<ToolResultOutput>;
-  } & (
-    | {
-        /**
-         * Tool with user-defined input and output schemas.
-         */
-        type?: undefined | 'function';
-      }
-    | {
-        /**
-         * Tool that is defined at runtime (e.g. an MCP tool).
-         * The types of input and output are not known at development time.
-         */
-        type: 'dynamic';
-      }
-    | {
-        /**
-         * Tool with provider-defined input and output schemas.
-         */
-        type: 'provider';
-
-        /**
-         * The ID of the tool. Must follow the format `<provider-name>.<unique-tool-name>`.
-         */
-        id: `${string}.${string}`;
-
-        /**
-         * The arguments for configuring the tool. Must match the expected arguments defined by the provider for this tool.
-         */
-        args: Record<string, unknown>;
-
-        /**
-         * Whether this provider-executed tool supports deferred results.
-         *
-         * When true, the tool result may not be returned in the same turn as the
-         * tool call (e.g., when using programmatic tool calling where a server tool
-         * triggers a client-executed tool, and the server tool's result is deferred
-         * until the client tool is resolved).
-         *
-         * This flag allows the AI SDK to handle tool results that arrive without
-         * a matching tool call in the current response.
-         *
-         * @default false
-         */
-        supportsDeferredResults?: boolean;
-      }
-  );
+        : NoInfer<OUTPUT>;
+  }) => ToolResultOutput | PromiseLike<ToolResultOutput>;
+} & ToolOutputProperties<INPUT, OUTPUT, NoInfer<CONTEXT>>;
+
+/**
+ * Common properties shared by function-style tools.
+ */
+type BaseFunctionTool<
+  INPUT extends JSONValue | unknown | never = any,
+  OUTPUT extends JSONValue | unknown | never = any,
+  CONTEXT extends Context | unknown | never = any,
+> = BaseTool<INPUT, OUTPUT, CONTEXT> & {
+  /**
+   * An optional description of what the tool does.
+   * Will be used by the language model to decide whether to use the tool.
+   */
+  description?: string;
+
+  /**
+   * Strict mode setting for the tool.
+   *
+   * Providers that support strict mode will use this setting to determine
+   * how the input should be generated. Strict mode will always produce
+   * valid inputs, but it might limit what input schemas are supported.
+   */
+  strict?: boolean;
+
+  /**
+   * An optional list of input examples that show the language
+   * model what the input should look like.
+   */
+  inputExamples?: Array<{ input: NoInfer<INPUT> }>;
+
+  // make all properties available to improve usage dx
+  id?: never;
+  isProviderExecuted?: never;
+  args?: never;
+  supportsDeferredResults?: never;
+};
+
+/**
+ * Tool with user-defined input and output schemas that is executed by the AI SDK.
+ */
+export type FunctionTool<
+  INPUT extends JSONValue | unknown | never = any,
+  OUTPUT extends JSONValue | unknown | never = any,
+  CONTEXT extends Context | unknown | never = any,
+> = BaseFunctionTool<INPUT, OUTPUT, CONTEXT> & {
+  type?: undefined | 'function';
+};
+
+/**
+ * Tool that is defined at runtime.
+ * The types of input and output are not known at development time.
+ *
+ * For example, MCP tools that are not known at development time.
+ */
+export type DynamicTool<
+  INPUT extends JSONValue | unknown | never = any,
+  OUTPUT extends JSONValue | unknown | never = any,
+  CONTEXT extends Context | unknown | never = any,
+> = BaseFunctionTool<INPUT, OUTPUT, CONTEXT> & {
+  type: 'dynamic';
+};
+
+/**
+ * Common properties shared by provider tools.
+ */
+type BaseProviderTool<
+  INPUT extends JSONValue | unknown | never = any,
+  OUTPUT extends JSONValue | unknown | never = any,
+  CONTEXT extends Context | unknown | never = any,
+> = BaseTool<INPUT, OUTPUT, CONTEXT> & {
+  type: 'provider';
+
+  /**
+   * The ID of the tool. Must follow the format `<provider-name>.<unique-tool-name>`.
+   */
+  id: `${string}.${string}`;
+
+  /**
+   * The arguments for configuring the tool. Must match the expected arguments defined by the provider for this tool.
+   */
+  args: Record<string, unknown>;
+
+  // make all properties available to improve usage dx
+  description?: never;
+  strict?: never;
+  inputExamples?: never;
+};
+
+/**
+ * Tool with provider-defined input and output schemas that is executed by the
+ * user.
+ *
+ * For example, shell tools that are executed in a local shell, but have provider-defined input and output schemas.
+ */
+export type ProviderDefinedTool<
+  INPUT extends JSONValue | unknown | never = any,
+  OUTPUT extends JSONValue | unknown | never = any,
+  CONTEXT extends Context | unknown | never = any,
+> = BaseProviderTool<INPUT, OUTPUT, CONTEXT> & {
+  /**
+   * Flag that indicates whether the tool is executed by the provider.
+   */
+  isProviderExecuted: false;
+
+  // make all properties available to improve usage dx
+  supportsDeferredResults?: never;
+};
+
+/**
+ * Tool with provider-defined input and output schemas that is executed by the
+ * provider.
+ *
+ * For example, web search tools and code execution tools that are executed by the provider itself.
+ */
+export type ProviderExecutedTool<
+  INPUT extends JSONValue | unknown | never = any,
+  OUTPUT extends JSONValue | unknown | never = any,
+  CONTEXT extends Context | unknown | never = any,
+> = BaseProviderTool<INPUT, OUTPUT, CONTEXT> & {
+  /**
+   * Flag that indicates whether the tool is executed by the provider.
+   */
+  isProviderExecuted: true;
+
+  /**
+   * Whether this provider-executed tool supports deferred results.
+   *
+   * When true, the tool result may not be returned in the same turn as the
+   * tool call (e.g., when using programmatic tool calling where a server tool
+   * triggers a client-executed tool, and the server tool's result is deferred
+   * until the client tool is resolved).
+   *
+   * This flag allows the AI SDK to handle tool results that arrive without
+   * a matching tool call in the current response.
+   *
+   * @default false
+   */
+  supportsDeferredResults?: boolean;
+};
 
 /**
- * Helper function for inferring the execute args of a tool.
+ * A tool can either be user-defined or provider-defined.
+ *
+ * It contains the schemas and metadata needed for the language model to call
+ * the tool and can include an execute function for tools that are executed by
+ * the AI SDK.
+ */
+export type Tool<
+  INPUT extends JSONValue | unknown | never = any,
+  OUTPUT extends JSONValue | unknown | never = any,
+  CONTEXT extends Context | unknown | never = any,
+> =
+  | FunctionTool<INPUT, OUTPUT, CONTEXT>
+  | DynamicTool<INPUT, OUTPUT, CONTEXT>
+  | ProviderDefinedTool<INPUT, OUTPUT, CONTEXT>
+  | ProviderExecutedTool<INPUT, OUTPUT, CONTEXT>;
+
+/**
+ * Infer the tool type from a tool object.
+ *
+ * This is useful for type inference when working with tool objects.
  */
 // Note: overload order is important for auto-completion
 export function tool<INPUT, OUTPUT, CONTEXT extends Context>(
@@ -304,43 +350,10 @@ export function tool(tool: any): any {
 }
 
 /**
- * Defines a dynamic tool.
+ * Define a dynamic tool.
  */
-export function dynamicTool(tool: {
-  description?: string;
-  title?: string;
-  providerOptions?: ProviderOptions;
-  inputSchema: FlexibleSchema<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.
-   *
-   * If not provided, the tool result will be sent as a JSON object.
-   */
-  toModelOutput?: (options: {
-    /**
-     * The ID of the tool call. You can use it e.g. when sending tool-call related information with stream data.
-     */
-    toolCallId: string;
-
-    /**
-     * The input of the tool call.
-     */
-    input: unknown;
-
-    /**
-     * The output of the tool call.
-     */
-    output: unknown;
-  }) => ToolResultOutput | PromiseLike<ToolResultOutput>;
-
-  /**
-   * Whether the tool needs approval before it can be executed.
-   */
-  needsApproval?: boolean | ToolNeedsApprovalFunction<unknown, Context>;
-}): Tool<unknown, unknown, Context> & {
-  type: 'dynamic';
-} {
-  return { ...tool, type: 'dynamic' };
+export function dynamicTool(
+  tool: Omit<DynamicTool<unknown, unknown, Context>, 'type'>,
+): DynamicTool<unknown, unknown, Context> {
+  return { ...tool, type: 'dynamic' } as DynamicTool<unknown, unknown, Context>;
 }

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

@@ -1,5 +1,5 @@
-import { FilePart, ImagePart, TextPart } from './content-part';
-import { ProviderOptions } from './provider-options';
+import type { FilePart, ImagePart, TextPart } from './content-part';
+import type { ProviderOptions } from './provider-options';
 
 /**
  * A user message. It can contain text or a combination of text and images.

package/src/validate-types.ts

@@ -1,6 +1,8 @@
-import { TypeValidationContext, TypeValidationError } from '@ai-sdk/provider';
-import { FlexibleSchema, asSchema } from './schema';
-
+import {
+  TypeValidationError,
+  type TypeValidationContext,
+} from '@ai-sdk/provider';
+import { asSchema, type FlexibleSchema } from './schema';
 /**
  * Validates the types of an unknown object using a schema and
  * return a strongly-typed object.