@ai-sdk/provider-utils 5.0.0-beta.2 → 5.0.0-beta.20

package/src/response-handler.ts

@@ -64,7 +64,7 @@ export const createJsonErrorResponseHandler =
           isRetryable: isRetryable?.(response, parsedError),
         }),
       };
-    } catch (parseError) {
+    } catch {
       return {
         responseHeaders,
         value: new APICallError({

package/src/secure-json-parse.ts

@@ -83,7 +83,7 @@ export function secureJsonParse(text: string) {
   try {
     // Performance optimization, see https://github.com/fastify/secure-json-parse/pull/90
     Error.stackTraceLimit = 0;
-  } catch (e) {
+  } catch {
     // Fallback in case Error is immutable (v8 readonly)
     return _parse(text);
   }

package/src/serialize-model-options.ts

@@ -0,0 +1,63 @@
+import { JSONObject } from '@ai-sdk/provider';
+import { isJSONSerializable } from './is-json-serializable';
+import { Resolvable } from './resolve';
+
+/**
+ * Serializes a model instance for workflow step boundaries.
+ * Returns the `modelId` plus the JSON-serializable config properties.
+ *
+ * Non-serializable values are omitted. As a special case, a
+ * function-valued `headers` property is resolved during serialization
+ * and included if the returned value is JSON-serializable.
+ *
+ * Used as the body of `static [WORKFLOW_SERIALIZE]` in provider models.
+ *
+ * @example
+ * ```ts
+ * static [WORKFLOW_SERIALIZE](model: MyLanguageModel) {
+ *   return serializeModelOptions({
+ *     modelId: model.modelId,
+ *     config: model.config,
+ *   });
+ * }
+ * ```
+ */
+export function serializeModelOptions<
+  CONFIG extends {
+    headers?: Resolvable<Record<string, string | undefined>>;
+  },
+>(options: {
+  modelId: string;
+  config: CONFIG;
+}): {
+  modelId: string;
+  config: JSONObject;
+} {
+  const serializableConfig: JSONObject = {};
+  for (const [key, value] of Object.entries(options.config)) {
+    if (key === 'headers') {
+      const resolvedHeaders = resolveSync(value);
+      if (isJSONSerializable(resolvedHeaders)) {
+        serializableConfig[key] = resolvedHeaders;
+      }
+    } else if (isJSONSerializable(value)) {
+      serializableConfig[key] = value;
+    }
+  }
+  return { modelId: options.modelId, config: serializableConfig };
+}
+
+function resolveSync<T>(value: Resolvable<T>): T {
+  let next: unknown = value;
+  if (typeof value === 'function') {
+    next = (value as () => unknown)();
+  }
+
+  // the serialization for workflows currently only supports synchronous values
+  // TODO introduce SerializationError
+  if (next instanceof Promise) {
+    throw new Error('Promise returned from resolveSync');
+  }
+
+  return next as T;
+}

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

@@ -22,7 +22,7 @@ export function parseDateDef(
 
   if (Array.isArray(strategy)) {
     return {
-      anyOf: strategy.map((item, i) => parseDateDef(def, refs, item)),
+      anyOf: strategy.map(item => parseDateDef(def, refs, item)),
     };
   }
 

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

@@ -42,7 +42,7 @@ export function parseIntersectionDef(
         'additionalProperties' in schema &&
         schema.additionalProperties === false
       ) {
-        const { additionalProperties, ...rest } = schema;
+        const { additionalProperties: _additionalProperties, ...rest } = schema;
         nestedSchema = rest;
       }
       mergedAllOf.push(nestedSchema);

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

@@ -38,7 +38,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 +56,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/types/assistant-model-message.ts

@@ -1,5 +1,7 @@
 import {
+  CustomPart,
   FilePart,
+  ReasoningFilePart,
   ReasoningPart,
   TextPart,
   ToolCallPart,
@@ -31,8 +33,10 @@ export type AssistantContent =
   | string
   | Array<
       | TextPart
+      | CustomPart
       | FilePart
       | ReasoningPart
+      | ReasoningFilePart
       | ToolCallPart
       | ToolResultPart
       | ToolApprovalRequest

package/src/types/content-part.ts

@@ -1,6 +1,7 @@
 import { JSONValue } from '@ai-sdk/provider';
 import { DataContent } from './data-content';
 import { ProviderOptions } from './provider-options';
+import { ProviderReference } from './provider-reference';
 
 /**
  * Text content part of a prompt. It contains a string of text.
@@ -32,8 +33,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.
@@ -60,9 +62,10 @@ export interface FilePart {
    * File data. Can either be:
    *
    * - data: a base64-encoded string, a Uint8Array, an ArrayBuffer, or a Buffer
-   * - URL: a URL that points to the image
+   * - URL: a URL that points to the file
+   * - ProviderReference: a provider reference from `uploadFile`
    */
-  data: DataContent | URL;
+  data: DataContent | URL | ProviderReference;
 
   /**
    * Optional filename of the file.
@@ -103,6 +106,55 @@ 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.
+ */
+export interface ReasoningFilePart {
+  type: 'reasoning-file';
+
+  /**
+   * File data. Can either be:
+   *
+   * - data: a base64-encoded string, a Uint8Array, an ArrayBuffer, or a Buffer
+   * - URL: a URL that points to the file
+   */
+  data: DataContent | URL;
+
+  /**
+   * IANA media type of the file.
+   *
+   * @see https://www.iana.org/assignments/media-types/media-types.xhtml
+   */
+  mediaType: 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;
+}
+
 /**
  * Tool call content part of a prompt. It contains a tool call (usually generated by the AI model).
  */
@@ -241,14 +293,6 @@ export type ToolResultOutput =
              */
             providerOptions?: ProviderOptions;
           }
-        | {
-            /**
-             * @deprecated Use image-data or file-data instead.
-             */
-            type: 'media';
-            data: string;
-            mediaType: string;
-          }
         | {
             type: 'file-data';
 
@@ -281,12 +325,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';
 
             /**
@@ -299,6 +352,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.
              */
@@ -306,7 +373,7 @@ export type ToolResultOutput =
           }
         | {
             /**
-             * Images that are referenced using base64 encoded data.
+             * @deprecated Use file-data instead.
              */
             type: 'image-data';
 
@@ -328,7 +395,7 @@ export type ToolResultOutput =
           }
         | {
             /**
-             * Images that are referenced using a URL.
+             * @deprecated Use file-url instead.
              */
             type: 'image-url';
 
@@ -344,7 +411,7 @@ export type ToolResultOutput =
           }
         | {
             /**
-             * Images that are referenced using a provider file id.
+             * @deprecated Use file-reference instead.
              */
             type: 'image-file-id';
 
@@ -358,6 +425,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/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

@@ -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,12 @@
+import { HasRequiredKey } from '../has-required-key';
+import type { Tool } from './tool';
+
+/**
+ * Infer the context type of a tool.
+ */
+export type InferToolContext<TOOL extends Tool> =
+  TOOL extends Tool<any, any, infer CONTEXT>
+    ? HasRequiredKey<CONTEXT> extends true
+      ? CONTEXT
+      : never
+    : 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'
+    >
+>;