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

package/src/types/index.ts

@@ -3,38 +3,39 @@ export type {
   AssistantModelMessage,
 } from './assistant-model-message';
 export type {
+  CustomPart,
   FilePart,
   ImagePart,
+  ReasoningFilePart,
   ReasoningPart,
   TextPart,
   ToolCallPart,
   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 { InferToolSetContext } from './infer-tool-set-context';
 export type { ModelMessage } from './model-message';
 export type { ProviderOptions } from './provider-options';
+export type { ProviderReference } from './provider-reference';
 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 { ToolSet } from './tool-set';
 export type { ToolApprovalRequest } from './tool-approval-request';
 export type { ToolApprovalResponse } from './tool-approval-response';
 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/infer-tool-set-context.ts

@@ -0,0 +1,17 @@
+import type { InferToolContext } from './infer-tool-context';
+import type { ToolSet } from './tool-set';
+import type { UnionToIntersection } from './union-to-intersection';
+
+/**
+ * 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`.
+ */
+export type InferToolSetContext<TOOLS extends ToolSet> = UnionToIntersection<
+  {
+    [K in keyof TOOLS]: InferToolContext<NoInfer<TOOLS[K]>>;
+  }[keyof TOOLS]
+>;

package/src/types/provider-options.ts

@@ -1,4 +1,4 @@
-import { SharedV3ProviderOptions } from '@ai-sdk/provider';
+import { SharedV4ProviderOptions } from '@ai-sdk/provider';
 
 /**
  * Additional provider-specific options.
@@ -6,4 +6,4 @@ import { SharedV3ProviderOptions } from '@ai-sdk/provider';
  * They are passed through to the provider from the AI SDK and enable
  * provider-specific functionality that can be fully encapsulated in the provider.
  */
-export type ProviderOptions = SharedV3ProviderOptions;
+export type ProviderOptions = SharedV4ProviderOptions;

package/src/types/provider-reference.ts

@@ -0,0 +1,10 @@
+import { SharedV4ProviderReference } from '@ai-sdk/provider';
+
+/**
+ * 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.
+ */
+export type ProviderReference = SharedV4ProviderReference;

package/src/types/tool-set.ts

@@ -0,0 +1,22 @@
+import type { Tool } from './tool';
+
+/**
+ * A mapping of tool names to tool definitions.
+ */
+export 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'
+    >
+>;

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,13 +206,15 @@ 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.
      *
      * 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: {
       /**
@@ -255,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;
 }
@@ -289,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.
@@ -316,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' };

package/src/types/union-to-intersection.ts

@@ -0,0 +1,17 @@
+/**
+ * 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.
+ */
+export type UnionToIntersection<U> = (
+  U extends unknown ? (arg: U) => void : never
+) extends (arg: infer I) => void
+  ? I
+  : never;

package/src/validate-download-url.ts

@@ -18,11 +18,16 @@ export function validateDownloadUrl(url: string): void {
     });
   }
 
-  // Only allow http and https protocols
+  // data: URLs are inline content, so they do not trigger a network fetch or SSRF risk.
+  if (parsed.protocol === 'data:') {
+    return;
+  }
+
+  // Only allow http and https network protocols
   if (parsed.protocol !== 'http:' && parsed.protocol !== 'https:') {
     throw new DownloadError({
       url,
-      message: `URL scheme must be http or https, got ${parsed.protocol}`,
+      message: `URL scheme must be http, https, or data, got ${parsed.protocol}`,
     });
   }