@ai-sdk/provider-utils 5.0.0-beta.3 → 5.0.0-beta.30

package/src/to-json-schema/zod3-to-json-schema/parsers/literal.ts

@@ -1,4 +1,4 @@
-import { ZodLiteralDef } from 'zod/v3';
+import type { ZodLiteralDef } from 'zod/v3';
 
 export type JsonSchema7LiteralType =
   | {

package/src/to-json-schema/zod3-to-json-schema/parsers/map.ts

@@ -1,10 +1,9 @@
-import { ZodMapDef } from 'zod/v3';
+import type { ZodMapDef } from 'zod/v3';
 import { parseDef } from '../parse-def';
-import { JsonSchema7Type } from '../parse-types';
-import { Refs } from '../refs';
+import type { JsonSchema7Type } from '../parse-types';
+import type { Refs } from '../refs';
 import { parseAnyDef } from './any';
-import { JsonSchema7RecordType, parseRecordDef } from './record';
-
+import { parseRecordDef, type JsonSchema7RecordType } from './record';
 export type JsonSchema7MapType = {
   type: 'array';
   maxItems: 125;

package/src/to-json-schema/zod3-to-json-schema/parsers/native-enum.ts

@@ -1,4 +1,4 @@
-import { ZodNativeEnumDef } from 'zod/v3';
+import type { ZodNativeEnumDef } from 'zod/v3';
 
 export type JsonSchema7NativeEnumType = {
   type: 'string' | 'number' | ['string', 'number'];

package/src/to-json-schema/zod3-to-json-schema/parsers/never.ts

@@ -1,5 +1,4 @@
-import { JsonSchema7AnyType, parseAnyDef } from './any';
-
+import { parseAnyDef, type JsonSchema7AnyType } from './any';
 export type JsonSchema7NeverType = {
   not: JsonSchema7AnyType;
 };

package/src/to-json-schema/zod3-to-json-schema/parsers/nullable.ts

@@ -1,8 +1,8 @@
-import { ZodNullableDef } from 'zod/v3';
+import type { ZodNullableDef } from 'zod/v3';
 import { parseDef } from '../parse-def';
-import { JsonSchema7Type } from '../parse-types';
-import { Refs } from '../refs';
-import { JsonSchema7NullType } from './null';
+import type { JsonSchema7Type } from '../parse-types';
+import type { Refs } from '../refs';
+import type { JsonSchema7NullType } from './null';
 import { primitiveMappings } from './union';
 
 export type JsonSchema7NullableType =

package/src/to-json-schema/zod3-to-json-schema/parsers/number.ts

@@ -1,4 +1,4 @@
-import { ZodNumberDef } from 'zod/v3';
+import type { ZodNumberDef } from 'zod/v3';
 
 export type JsonSchema7NumberType = {
   type: 'number' | 'integer';

package/src/to-json-schema/zod3-to-json-schema/parsers/object.ts

@@ -1,7 +1,7 @@
-import { ZodObjectDef, ZodTypeAny } from 'zod/v3';
+import type { ZodObjectDef, ZodTypeAny } from 'zod/v3';
 import { parseDef } from '../parse-def';
-import { JsonSchema7Type } from '../parse-types';
-import { Refs } from '../refs';
+import type { JsonSchema7Type } from '../parse-types';
+import type { Refs } from '../refs';
 
 export type JsonSchema7ObjectType = {
   type: 'object';

package/src/to-json-schema/zod3-to-json-schema/parsers/optional.ts

@@ -1,7 +1,7 @@
-import { ZodOptionalDef } from 'zod/v3';
+import type { ZodOptionalDef } from 'zod/v3';
 import { parseDef } from '../parse-def';
-import { JsonSchema7Type } from '../parse-types';
-import { Refs } from '../refs';
+import type { JsonSchema7Type } from '../parse-types';
+import type { Refs } from '../refs';
 import { parseAnyDef } from './any';
 
 export const parseOptionalDef = (

package/src/to-json-schema/zod3-to-json-schema/parsers/pipeline.ts

@@ -1,8 +1,8 @@
-import { ZodPipelineDef } from 'zod/v3';
+import type { ZodPipelineDef } from 'zod/v3';
 import { parseDef } from '../parse-def';
-import { JsonSchema7Type } from '../parse-types';
-import { Refs } from '../refs';
-import { JsonSchema7AllOfType } from './intersection';
+import type { JsonSchema7Type } from '../parse-types';
+import type { Refs } from '../refs';
+import type { JsonSchema7AllOfType } from './intersection';
 
 export const parsePipelineDef = (
   def: ZodPipelineDef<any, any>,

package/src/to-json-schema/zod3-to-json-schema/parsers/promise.ts

@@ -1,7 +1,7 @@
-import { ZodPromiseDef } from 'zod/v3';
+import type { ZodPromiseDef } from 'zod/v3';
 import { parseDef } from '../parse-def';
-import { JsonSchema7Type } from '../parse-types';
-import { Refs } from '../refs';
+import type { JsonSchema7Type } from '../parse-types';
+import type { Refs } from '../refs';
 
 export function parsePromiseDef(
   def: ZodPromiseDef,

package/src/to-json-schema/zod3-to-json-schema/parsers/readonly.ts

@@ -1,6 +1,6 @@
-import { ZodReadonlyDef } from 'zod/v3';
+import type { ZodReadonlyDef } from 'zod/v3';
 import { parseDef } from '../parse-def';
-import { Refs } from '../refs';
+import type { Refs } from '../refs';
 
 export const parseReadonlyDef = (def: ZodReadonlyDef<any>, refs: Refs) => {
   return parseDef(def.innerType._def, refs);

package/src/to-json-schema/zod3-to-json-schema/parsers/record.ts

@@ -1,16 +1,15 @@
 import {
   ZodFirstPartyTypeKind,
-  ZodMapDef,
-  ZodRecordDef,
-  ZodTypeAny,
+  type ZodMapDef,
+  type ZodRecordDef,
+  type ZodTypeAny,
 } from 'zod/v3';
 import { parseDef } from '../parse-def';
-import { JsonSchema7Type } from '../parse-types';
-import { Refs } from '../refs';
+import type { JsonSchema7Type } from '../parse-types';
+import type { Refs } from '../refs';
 import { parseBrandedDef } from './branded';
-import { JsonSchema7EnumType } from './enum';
-import { JsonSchema7StringType, parseStringDef } from './string';
-
+import type { JsonSchema7EnumType } from './enum';
+import { parseStringDef, type JsonSchema7StringType } from './string';
 type JsonSchema7RecordPropertyNamesType =
   | Omit<JsonSchema7StringType, 'type'>
   | Omit<JsonSchema7EnumType, 'type'>;
@@ -38,7 +37,7 @@ export function parseRecordDef(
     def.keyType?._def.typeName === ZodFirstPartyTypeKind.ZodString &&
     def.keyType._def.checks?.length
   ) {
-    const { type, ...keyType } = parseStringDef(def.keyType._def, refs);
+    const { type: _type, ...keyType } = parseStringDef(def.keyType._def, refs);
 
     return {
       ...schema,
@@ -56,7 +55,7 @@ export function parseRecordDef(
     def.keyType._def.type._def.typeName === ZodFirstPartyTypeKind.ZodString &&
     def.keyType._def.type._def.checks?.length
   ) {
-    const { type, ...keyType } = parseBrandedDef(
+    const { type: _type, ...keyType } = parseBrandedDef(
       def.keyType._def,
       refs,
     ) as JsonSchema7StringType;

package/src/to-json-schema/zod3-to-json-schema/parsers/set.ts

@@ -1,7 +1,7 @@
-import { ZodSetDef } from 'zod/v3';
+import type { ZodSetDef } from 'zod/v3';
 import { parseDef } from '../parse-def';
-import { JsonSchema7Type } from '../parse-types';
-import { Refs } from '../refs';
+import type { JsonSchema7Type } from '../parse-types';
+import type { Refs } from '../refs';
 
 export type JsonSchema7SetType = {
   type: 'array';

package/src/to-json-schema/zod3-to-json-schema/parsers/string.ts

@@ -1,5 +1,5 @@
-import { ZodStringDef } from 'zod/v3';
-import { Refs } from '../refs';
+import type { ZodStringDef } from 'zod/v3';
+import type { Refs } from '../refs';
 
 let emojiRegex: RegExp | undefined = undefined;
 

package/src/to-json-schema/zod3-to-json-schema/parsers/tuple.ts

@@ -1,7 +1,7 @@
-import { ZodTupleDef, ZodTupleItems, ZodTypeAny } from 'zod/v3';
+import type { ZodTupleDef, ZodTupleItems, ZodTypeAny } from 'zod/v3';
 import { parseDef } from '../parse-def';
-import { JsonSchema7Type } from '../parse-types';
-import { Refs } from '../refs';
+import type { JsonSchema7Type } from '../parse-types';
+import type { Refs } from '../refs';
 
 export type JsonSchema7TupleType = {
   type: 'array';

package/src/to-json-schema/zod3-to-json-schema/parsers/undefined.ts

@@ -1,5 +1,4 @@
-import { JsonSchema7AnyType, parseAnyDef } from './any';
-
+import { parseAnyDef, type JsonSchema7AnyType } from './any';
 export type JsonSchema7UndefinedType = {
   not: JsonSchema7AnyType;
 };

package/src/to-json-schema/zod3-to-json-schema/parsers/union.ts

@@ -1,12 +1,12 @@
-import {
+import type {
   ZodDiscriminatedUnionDef,
   ZodLiteralDef,
   ZodTypeAny,
   ZodUnionDef,
 } from 'zod/v3';
 import { parseDef } from '../parse-def';
-import { JsonSchema7Type } from '../parse-types';
-import { Refs } from '../refs';
+import type { JsonSchema7Type } from '../parse-types';
+import type { Refs } from '../refs';
 
 export const primitiveMappings = {
   ZodString: 'string',

package/src/to-json-schema/zod3-to-json-schema/parsers/unknown.ts

@@ -1,5 +1,4 @@
-import { JsonSchema7AnyType, parseAnyDef } from './any';
-
+import { parseAnyDef, type JsonSchema7AnyType } from './any';
 export type JsonSchema7UnknownType = JsonSchema7AnyType;
 
 export function parseUnknownDef(): JsonSchema7UnknownType {

package/src/to-json-schema/zod3-to-json-schema/refs.ts

@@ -1,6 +1,6 @@
-import { ZodTypeDef } from 'zod/v3';
-import { getDefaultOptions, Options } from './options';
-import { JsonSchema7Type } from './parse-types';
+import type { ZodTypeDef } from 'zod/v3';
+import { getDefaultOptions, type Options } from './options';
+import type { JsonSchema7Type } from './parse-types';
 
 export type Refs = {
   seen: Map<ZodTypeDef, Seen>;

package/src/to-json-schema/zod3-to-json-schema/select-parser.ts

@@ -28,9 +28,9 @@ import { parseTupleDef } from './parsers/tuple';
 import { parseUndefinedDef } from './parsers/undefined';
 import { parseUnionDef } from './parsers/union';
 import { parseUnknownDef } from './parsers/unknown';
-import { Refs } from './refs';
+import type { Refs } from './refs';
 import { parseReadonlyDef } from './parsers/readonly';
-import { JsonSchema7Type } from './parse-types';
+import type { JsonSchema7Type } from './parse-types';
 
 export type InnerDefGetter = () => any;
 

package/src/to-json-schema/zod3-to-json-schema/zod3-to-json-schema.ts

@@ -1,7 +1,7 @@
-import { ZodSchema } from 'zod/v3';
-import { Options } from './options';
+import type { ZodSchema } from 'zod/v3';
+import type { Options } from './options';
 import { parseDef } from './parse-def';
-import { JsonSchema7Type } from './parse-types';
+import type { JsonSchema7Type } from './parse-types';
 import { getRefs } from './refs';
 import { parseAnyDef } from './parsers/any';
 

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

@@ -1,4 +1,5 @@
-import {
+import type {
+  CustomPart,
   FilePart,
   ReasoningFilePart,
   ReasoningPart,
@@ -6,8 +7,8 @@ import {
   ToolCallPart,
   ToolResultPart,
 } from './content-part';
-import { ProviderOptions } from './provider-options';
-import { ToolApprovalRequest } from './tool-approval-request';
+import type { ProviderOptions } from './provider-options';
+import type { ToolApprovalRequest } from './tool-approval-request';
 
 /**
  * An assistant message. It can contain text, tool calls, or a combination of text and tool calls.
@@ -32,6 +33,7 @@ export type AssistantContent =
   | string
   | Array<
       | TextPart
+      | CustomPart
       | FilePart
       | ReasoningPart
       | ReasoningFilePart

package/src/types/content-part.ts

@@ -1,6 +1,8 @@
-import { JSONValue } from '@ai-sdk/provider';
-import { DataContent } from './data-content';
-import { ProviderOptions } from './provider-options';
+import type { JSONValue } from '@ai-sdk/provider';
+import type { DataContent } from './data-content';
+import type { FileData, FileDataData, FileDataUrl } from './file-data';
+import type { ProviderOptions } from './provider-options';
+import type { ProviderReference } from './provider-reference';
 
 /**
  * Text content part of a prompt. It contains a string of text.
@@ -23,6 +25,9 @@ export interface TextPart {
 
 /**
  * Image content part of a prompt. It contains an image.
+ *
+ * @deprecated Use `FilePart` with `mediaType: 'image'` instead:
+ * `{ type: 'file', mediaType: 'image', data: { type: 'data', data } }`.
  */
 export interface ImagePart {
   type: 'image';
@@ -32,8 +37,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.
@@ -57,12 +63,16 @@ export interface FilePart {
   type: 'file';
 
   /**
-   * File data. Can either be:
+   * File data. Either a tagged shape or a bare shorthand:
    *
-   * - data: a base64-encoded string, a Uint8Array, an ArrayBuffer, or a Buffer
-   * - URL: a URL that points to the image
+   * - `{ type: 'data', data }` or bare `DataContent`: raw bytes
+   *   (base64 string, Uint8Array, ArrayBuffer, Buffer)
+   * - `{ type: 'url', url }` or bare `URL`: a URL that points to the file
+   * - `{ type: 'reference', reference }` or bare `ProviderReference`:
+   *   a provider reference from `uploadFile`
+   * - `{ type: 'text', text }`: inline text content (tagged only)
    */
-  data: DataContent | URL;
+  data: FileData | DataContent | URL | ProviderReference;
 
   /**
    * Optional filename of the file.
@@ -70,7 +80,14 @@ export interface FilePart {
   filename?: string;
 
   /**
-   * IANA media type of the file.
+   * Either a full IANA media type (`type/subtype`, e.g. `image/png`) or just
+   * the top-level IANA segment (e.g. `image`, `audio`, `video`, `text`).
+   *
+   * `*`-subtype wildcards (e.g. `image/*`) are normalized as equivalent to the
+   * top-level segment alone (e.g. `image`). Providers can use the helpers in
+   * `@ai-sdk/provider-utils` (`isFullMediaType`, `getTopLevelMediaType`,
+   * `detectMediaType`) to resolve the field according to their API
+   * requirements.
    *
    * @see https://www.iana.org/assignments/media-types/media-types.xhtml
    */
@@ -103,6 +120,26 @@ 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.
  */
@@ -110,12 +147,21 @@ export interface ReasoningFilePart {
   type: 'reasoning-file';
 
   /**
-   * File data. Can either be:
+   * Reasoning file data.
    *
-   * - data: a base64-encoded string, a Uint8Array, an ArrayBuffer, or a Buffer
-   * - URL: a URL that points to the file
+   * Reasoning files originate from a model's reasoning output and are always
+   * raw bytes or a fetchable URL. Unlike `FilePart.data`, the `reference` and
+   * `text` shapes are not supported here: provider references describe files
+   * uploaded by the user (not produced as model output), and reasoning text is
+   * carried by `ReasoningPart` rather than as a file.
+   *
+   * Either a tagged shape or a bare shorthand:
+   *
+   * - `{ type: 'data', data }` or bare `DataContent`: raw bytes
+   *   (base64 string, Uint8Array, ArrayBuffer, Buffer)
+   * - `{ type: 'url', url }` or bare `URL`: a URL that points to the file
    */
-  data: DataContent | URL;
+  data: FileDataData | FileDataUrl | DataContent | URL;
 
   /**
    * IANA media type of the file.
@@ -270,14 +316,6 @@ export type ToolResultOutput =
              */
             providerOptions?: ProviderOptions;
           }
-        | {
-            /**
-             * @deprecated Use image-data or file-data instead.
-             */
-            type: 'media';
-            data: string;
-            mediaType: string;
-          }
         | {
             type: 'file-data';
 
@@ -310,12 +348,21 @@ export type ToolResultOutput =
              */
             url: string;
 
+            /**
+             * IANA media type.
+             * @see https://www.iana.org/assignments/media-types/media-types.xhtml
+             */
+            mediaType?: string; // Temporarily optional. TODO: make required in v8, after migration period.
+
             /**
              * Provider-specific options.
              */
             providerOptions?: ProviderOptions;
           }
         | {
+            /**
+             * @deprecated Use file-reference instead.
+             */
             type: 'file-id';
 
             /**
@@ -328,6 +375,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.
              */
@@ -335,7 +396,7 @@ export type ToolResultOutput =
           }
         | {
             /**
-             * Images that are referenced using base64 encoded data.
+             * @deprecated Use file-data instead.
              */
             type: 'image-data';
 
@@ -357,7 +418,7 @@ export type ToolResultOutput =
           }
         | {
             /**
-             * Images that are referenced using a URL.
+             * @deprecated Use file-url instead.
              */
             type: 'image-url';
 
@@ -373,7 +434,7 @@ export type ToolResultOutput =
           }
         | {
             /**
-             * Images that are referenced using a provider file id.
+             * @deprecated Use file-reference instead.
              */
             type: 'image-file-id';
 
@@ -387,6 +448,23 @@ export type ToolResultOutput =
              */
             fileId: string | Record<string, string>;
 
+            /**
+             * Provider-specific options.
+             */
+            providerOptions?: ProviderOptions;
+          }
+        | {
+            /**
+             * @deprecated Use file-reference instead.
+             */
+            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/executable-tool.ts

@@ -0,0 +1,17 @@
+import type { Tool } from './tool';
+
+/**
+ * A tool that is guaranteed to expose an execute function.
+ */
+export type ExecutableTool<TOOL extends Tool = Tool> = TOOL & {
+  execute: NonNullable<TOOL['execute']>;
+};
+
+/**
+ * Checks whether a tool exposes an execute function.
+ */
+export function isExecutableTool<TOOL extends Tool>(
+  tool: TOOL | undefined,
+): tool is ExecutableTool<TOOL> {
+  return tool != null && typeof tool.execute === 'function';
+}

package/src/types/execute-tool.ts

@@ -1,21 +1,41 @@
 import { isAsyncIterable } from '../is-async-iterable';
-import { ToolExecutionOptions, ToolExecuteFunction } from './tool';
+import type { ExecutableTool } from './executable-tool';
+import type { InferToolContext } from './infer-tool-context';
+import type { InferToolInput } from './infer-tool-input';
+import type { InferToolOutput } from './infer-tool-output';
+import type { Tool } from './tool';
+import type { ToolExecutionOptions } from './tool-execute-function';
 
-export async function* executeTool<INPUT, OUTPUT>({
-  execute,
+/**
+ * Executes a tool function and normalizes its results into a stream of outputs.
+ *
+ * - If the tool's `execute` function returns an `AsyncIterable`, each yielded value is emitted as
+ *   `{ type: "preliminary", output }`. After iteration completes, the last yielded value is emitted
+ *   again as `{ type: "final", output }`.
+ * - If the tool returns a direct value or Promise, a single `{ type: "final", output }` is yielded.
+ *
+ * @param params.tool The tool whose `execute` function should be invoked.
+ * @param params.input The input value to pass to the tool.
+ * @param params.options Additional options for tool execution.
+ * @yields A preliminary output for each streamed value, followed by a final output, or a single final
+ * output for non-streaming tools.
+ */
+export async function* executeTool<TOOL extends Tool>({
+  tool,
   input,
   options,
 }: {
-  execute: ToolExecuteFunction<INPUT, OUTPUT>;
-  input: INPUT;
-  options: ToolExecutionOptions;
+  tool: ExecutableTool<TOOL>;
+  input: InferToolInput<TOOL>;
+  options: ToolExecutionOptions<InferToolContext<TOOL>>;
 }): AsyncGenerator<
-  { type: 'preliminary'; output: OUTPUT } | { type: 'final'; output: OUTPUT }
+  | { type: 'preliminary'; output: InferToolOutput<TOOL> }
+  | { type: 'final'; output: InferToolOutput<TOOL> }
 > {
-  const result = execute(input, options);
+  const result = tool.execute(input, options);
 
   if (isAsyncIterable(result)) {
-    let lastOutput: OUTPUT | undefined;
+    let lastOutput: InferToolOutput<TOOL> | undefined;
     for await (const output of result) {
       lastOutput = output;
       yield { type: 'preliminary', output };

package/src/types/file-data.ts

@@ -0,0 +1,48 @@
+import type {
+  SharedV4FileDataReference,
+  SharedV4FileDataText,
+  SharedV4FileDataUrl,
+} from '@ai-sdk/provider';
+import type { DataContent } from './data-content';
+
+/**
+ * File data variant containing raw bytes (`Uint8Array`, `ArrayBuffer`, or
+ * `Buffer`) or a base64-encoded string.
+ *
+ * This is slightly more permissive than `SharedV4FileDataData`.
+ */
+export interface FileDataData {
+  type: 'data';
+  data: DataContent;
+}
+
+/**
+ * File data variant containing a URL that points to the file.
+ */
+export type FileDataUrl = SharedV4FileDataUrl;
+
+/**
+ * File data variant containing a provider reference (`{ [provider]: id }`).
+ */
+export type FileDataReference = SharedV4FileDataReference;
+
+/**
+ * File data variant containing inline text content (e.g. an inline text
+ * document).
+ */
+export type FileDataText = SharedV4FileDataText;
+
+/**
+ * File data as a tagged discriminated union:
+ *
+ * - `{ type: 'data', data }`: raw bytes (`Uint8Array`, `ArrayBuffer`, or
+ *   `Buffer`) or a base64-encoded string.
+ * - `{ type: 'url', url }`: a URL that points to the file.
+ * - `{ type: 'reference', reference }`: a provider reference (`{ [provider]: id }`).
+ * - `{ type: 'text', text }`: inline text content (e.g. an inline text document).
+ */
+export type FileData =
+  | FileDataData
+  | FileDataUrl
+  | FileDataReference
+  | FileDataText;