@ai-sdk/provider-utils 4.0.5 → 4.0.7

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

@@ -0,0 +1,23 @@
+import { ToolResultPart } from './content-part';
+import { ProviderOptions } from './provider-options';
+import { ToolApprovalResponse } from './tool-approval-response';
+
+/**
+A tool message. It contains the result of one or more tool calls.
+ */
+export type ToolModelMessage = {
+  role: 'tool';
+  content: ToolContent;
+
+  /**
+  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;
+};
+
+/**
+Content of a tool message. It is an array of tool result parts.
+ */
+export type ToolContent = Array<ToolResultPart | ToolApprovalResponse>;

package/src/types/tool-result.ts

@@ -0,0 +1,35 @@
+/**
+Typed tool result that is returned by `generateText` and `streamText`.
+It contains the tool call ID, the tool name, the tool arguments, and the tool result.
+ */
+export interface ToolResult<NAME extends string, INPUT, OUTPUT> {
+  /**
+ID of the tool call. This ID is used to match the tool call with the tool result.
+   */
+  toolCallId: string;
+
+  /**
+Name of the tool that was called.
+   */
+  toolName: NAME;
+
+  /**
+Arguments of the tool call. This is a JSON-serializable object that matches the tool's input schema.
+     */
+  input: INPUT;
+
+  /**
+Result of the tool call. This is the result of the tool's execution.
+     */
+  output: OUTPUT;
+
+  /**
+   * Whether the tool result has been executed by the provider.
+   */
+  providerExecuted?: boolean;
+
+  /**
+   * Whether the tool is dynamic.
+   */
+  dynamic?: boolean;
+}

package/src/types/tool.test-d.ts

@@ -0,0 +1,228 @@
+import { LanguageModelV3ToolResultPart } from '@ai-sdk/provider';
+import { describe, expectTypeOf, it } from 'vitest';
+import { z } from 'zod/v4';
+import { FlexibleSchema } from '../schema';
+import { ModelMessage } from './model-message';
+import { Tool, tool, ToolExecuteFunction } from './tool';
+import { ToolResultOutput } from './content-part';
+
+describe('tool type', () => {
+  describe('input type', () => {
+    it('should work with fixed inputSchema', () => {
+      const aTool = tool({
+        inputSchema: z.object({ number: z.number() }),
+      });
+
+      expectTypeOf(aTool).toEqualTypeOf<Tool<{ number: number }, never>>();
+      expectTypeOf(aTool.execute).toEqualTypeOf<undefined>();
+      expectTypeOf(aTool.execute).not.toEqualTypeOf<Function>();
+      expectTypeOf(aTool.inputSchema).toEqualTypeOf<
+        FlexibleSchema<{ number: number }>
+      >();
+    });
+
+    it('should work with flexible inputSchema', <T>() => {
+      const aTool = tool({
+        inputSchema: null as unknown as FlexibleSchema<T>,
+      });
+
+      expectTypeOf(aTool).toEqualTypeOf<Tool<T, never>>();
+      expectTypeOf(aTool.execute).toEqualTypeOf<undefined>();
+      expectTypeOf(aTool.execute).not.toEqualTypeOf<Function>();
+      expectTypeOf(aTool.inputSchema).toEqualTypeOf<FlexibleSchema<T>>();
+    });
+
+    it('should infer input type correctly when inputExamples are present with optional/default zod schema', () => {
+      const inputSchema = z.object({
+        location: z.string(),
+        unit: z.enum(['celsius', 'fahrenheit']).optional().default('celsius'),
+      });
+
+      tool({
+        description: 'Get the weather for a location',
+        inputSchema,
+        inputExamples: [
+          { input: { location: 'San Francisco', unit: 'celsius' } },
+        ],
+        execute: async input => {
+          expectTypeOf(input).toEqualTypeOf<z.infer<typeof inputSchema>>();
+          return { temperature: 20, unit: input.unit };
+        },
+      });
+    });
+
+    it('should infer input type correctly when inputExamples are present with refine zod schema', () => {
+      const inputSchema = z.object({
+        code: z.string().refine(val => val.length === 3),
+      });
+
+      tool({
+        description: 'Get code details',
+        inputSchema,
+        inputExamples: [{ input: { code: 'ABC' } }],
+        execute: async input => {
+          expectTypeOf(input).toEqualTypeOf<z.infer<typeof inputSchema>>();
+          return { valid: true };
+        },
+      });
+    });
+  });
+
+  describe('output type', () => {
+    it('should derive output type from execute function', () => {
+      const aTool = tool({
+        inputSchema: z.object({ number: z.number() }),
+        execute: async input => {
+          expectTypeOf(input).toEqualTypeOf<{ number: number }>();
+          return 'test' as const;
+        },
+      });
+
+      expectTypeOf(aTool).toEqualTypeOf<Tool<{ number: number }, 'test'>>();
+      expectTypeOf(aTool.execute).toMatchTypeOf<
+        ToolExecuteFunction<{ number: number }, 'test'> | undefined
+      >();
+      expectTypeOf(aTool.execute).not.toEqualTypeOf<undefined>();
+      expectTypeOf(aTool.inputSchema).toEqualTypeOf<
+        FlexibleSchema<{ number: number }>
+      >();
+    });
+
+    it('should derive const schema from async generator execute function', () => {
+      const aTool = tool({
+        inputSchema: z.object({ number: z.number() }),
+        execute: async function* () {
+          yield 'test' as const;
+        },
+      });
+
+      expectTypeOf(aTool).toEqualTypeOf<Tool<{ number: number }, 'test'>>();
+      expectTypeOf(aTool.execute).toEqualTypeOf<
+        ToolExecuteFunction<{ number: number }, 'test'> | undefined
+      >();
+      expectTypeOf(aTool.inputSchema).toEqualTypeOf<
+        FlexibleSchema<{ number: number }>
+      >();
+    });
+  });
+
+  describe('toModelOutput', () => {
+    it('should infer toModelOutput argument when there is only an input schema', () => {
+      const aTool = tool({
+        inputSchema: z.object({ number: z.number() }),
+        toModelOutput: ({ output }) => {
+          expectTypeOf(output).toEqualTypeOf<any>();
+          return { type: 'text', value: 'test' };
+        },
+      });
+
+      expectTypeOf(aTool.toModelOutput).toMatchTypeOf<
+        | ((options: {
+            toolCallId: string;
+            input: { number: number };
+            output: any;
+          }) => ToolResultOutput | PromiseLike<ToolResultOutput>)
+        | undefined
+      >();
+    });
+
+    it('should infer toModelOutput argument when there is an execute function', () => {
+      const aTool = tool({
+        inputSchema: z.object({ number: z.number() }),
+        execute: async () => 'test' as const,
+        toModelOutput: ({ output }) => {
+          expectTypeOf(output).toEqualTypeOf<'test'>();
+          return { type: 'text', value: 'test' };
+        },
+      });
+
+      expectTypeOf(aTool.toModelOutput).toMatchTypeOf<
+        | ((options: {
+            toolCallId: string;
+            input: { number: number };
+            output: 'test';
+          }) => ToolResultOutput | PromiseLike<ToolResultOutput>)
+        | undefined
+      >();
+    });
+
+    it('should infer toModelOutput argument when there is an output schema', () => {
+      const aTool = tool({
+        inputSchema: z.object({ number: z.number() }),
+        outputSchema: z.literal('test'),
+        toModelOutput: ({ output }) => {
+          expectTypeOf(output).toEqualTypeOf<'test'>();
+          return { type: 'text', value: 'test' };
+        },
+      });
+
+      expectTypeOf(aTool.toModelOutput).toMatchTypeOf<
+        | ((options: {
+            toolCallId: string;
+            input: { number: number };
+            output: 'test';
+          }) => ToolResultOutput | PromiseLike<ToolResultOutput>)
+        | undefined
+      >();
+    });
+  });
+
+  describe('needsApproval (function)', () => {
+    it('should infer needsApproval argument when there is only an input schema', () => {
+      const aTool = tool({
+        inputSchema: z.object({ number: z.number() }),
+        needsApproval: (input, options) => {
+          expectTypeOf(input).toEqualTypeOf<{ number: number }>();
+          expectTypeOf(options).toEqualTypeOf<{
+            toolCallId: string;
+            messages: ModelMessage[];
+            experimental_context?: unknown;
+          }>();
+          return true;
+        },
+      });
+
+      expectTypeOf(aTool.needsApproval).toMatchTypeOf<
+        | boolean
+        | ((
+            input: { number: number },
+            options: {
+              toolCallId: string;
+              messages: ModelMessage[];
+              experimental_context: unknown;
+            },
+          ) => boolean | PromiseLike<boolean>)
+        | undefined
+      >();
+    });
+
+    it('should infer needsApproval argument when there is an execute function', () => {
+      const aTool = tool({
+        inputSchema: z.object({ number: z.number() }),
+        execute: async () => 'test' as const,
+        needsApproval: (input, options) => {
+          expectTypeOf(input).toEqualTypeOf<{ number: number }>();
+          expectTypeOf(options).toEqualTypeOf<{
+            toolCallId: string;
+            messages: ModelMessage[];
+            experimental_context?: unknown;
+          }>();
+          return true;
+        },
+      });
+
+      expectTypeOf(aTool.needsApproval).toMatchTypeOf<
+        | boolean
+        | ((
+            input: { number: number },
+            options: {
+              toolCallId: string;
+              messages: ModelMessage[];
+              experimental_context: unknown;
+            },
+          ) => boolean | PromiseLike<boolean>)
+        | undefined
+      >();
+    });
+  });
+});

package/src/types/tool.ts

@@ -0,0 +1,324 @@
+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';
+
+/**
+ * Additional options that are sent into each tool call.
+ */
+export interface ToolExecutionOptions {
+  /**
+   * 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?: unknown;
+}
+
+/**
+ * Function that is called to determine if the tool needs approval before it can be executed.
+ */
+export type ToolNeedsApprovalFunction<INPUT> = (
+  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?: unknown;
+  },
+) => boolean | PromiseLike<boolean>;
+
+export type ToolExecuteFunction<INPUT, OUTPUT> = (
+  input: INPUT,
+  options: ToolExecutionOptions,
+) => 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;
+
+type ToolOutputProperties<INPUT, OUTPUT> = 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.
+
+@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>;
+
+      outputSchema?: FlexibleSchema<OUTPUT>;
+    }
+  | {
+      outputSchema: FlexibleSchema<OUTPUT>;
+
+      execute?: never;
+    }
+>;
+
+/**
+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.
+ */
+export type Tool<
+  INPUT extends JSONValue | unknown | never = any,
+  OUTPUT extends JSONValue | 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.
+   */
+  title?: 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;
+
+  /**
+   * The schema of the input that the tool expects.
+   * The language model will use this to generate the input.
+   * It is also used to validate the output of the language model.
+   *
+   * You can use descriptions on the schema properties to make the input understandable for the language model.
+   */
+  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> }>;
+
+  /**
+   * Whether the tool needs approval before it can be executed.
+   */
+  needsApproval?:
+    | boolean
+    | ToolNeedsApprovalFunction<[INPUT] extends [never] ? unknown : INPUT>;
+
+  /**
+   * 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.
+   */
+  onInputStart?: (options: ToolExecutionOptions) => 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>;
+
+  /**
+   * 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> & {
+    /**
+     * 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: [INPUT] extends [never] ? unknown : INPUT;
+
+      /**
+       * The output of the tool call.
+       */
+      output: 0 extends 1 & OUTPUT
+        ? 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;
+      }
+  );
+
+/**
+ * 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(tool: any): any {
+  return tool;
+}
+
+/**
+ * Defines a dynamic tool.
+ */
+export function dynamicTool(tool: {
+  description?: string;
+  title?: string;
+  providerOptions?: ProviderOptions;
+  inputSchema: FlexibleSchema<unknown>;
+  execute: ToolExecuteFunction<unknown, unknown>;
+
+  /**
+   * 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>;
+}): Tool<unknown, unknown> & {
+  type: 'dynamic';
+} {
+  return { ...tool, type: 'dynamic' };
+}

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

@@ -0,0 +1,22 @@
+import { FilePart, ImagePart, TextPart } from './content-part';
+import { ProviderOptions } from './provider-options';
+
+/**
+A user message. It can contain text or a combination of text and images.
+ */
+export type UserModelMessage = {
+  role: 'user';
+  content: UserContent;
+
+  /**
+    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;
+};
+
+/**
+  Content of a user message. It can be a string or an array of text and image parts.
+   */
+export type UserContent = string | Array<TextPart | ImagePart | FilePart>;

package/src/uint8-utils.ts

@@ -0,0 +1,26 @@
+// btoa and atob need to be invoked as a function call, not as a method call.
+// Otherwise CloudFlare will throw a
+// "TypeError: Illegal invocation: function called with incorrect this reference"
+const { btoa, atob } = globalThis;
+
+export function convertBase64ToUint8Array(base64String: string) {
+  const base64Url = base64String.replace(/-/g, '+').replace(/_/g, '/');
+  const latin1string = atob(base64Url);
+  return Uint8Array.from(latin1string, byte => byte.codePointAt(0)!);
+}
+
+export function convertUint8ArrayToBase64(array: Uint8Array): string {
+  let latin1string = '';
+
+  // Note: regular for loop to support older JavaScript versions that
+  // do not support for..of on Uint8Array
+  for (let i = 0; i < array.length; i++) {
+    latin1string += String.fromCodePoint(array[i]);
+  }
+
+  return btoa(latin1string);
+}
+
+export function convertToBase64(value: string | Uint8Array): string {
+  return value instanceof Uint8Array ? convertUint8ArrayToBase64(value) : value;
+}