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

package/CHANGELOG.md

@@ -1,5 +1,21 @@
 # @ai-sdk/provider-utils
 
+## 5.0.0-beta.20
+
+### Patch Changes
+
+- b3976a2: Add workflow serialization support to all provider models.
+
+  **`@ai-sdk/provider-utils`:** New `serializeModel()` helper that extracts only serializable properties from a model instance, filtering out functions and objects containing functions. Third-party provider authors can use this to add workflow support to their own models.
+
+  **All providers:** `headers` is now optional in provider config types. This is non-breaking — existing code that passes `headers` continues to work. Custom provider implementations that construct model configs manually can now omit `headers`, which is useful when models are deserialized from a workflow step boundary where auth is provided separately.
+
+  All provider model classes now include `WORKFLOW_SERIALIZE` and `WORKFLOW_DESERIALIZE` static methods, enabling them to cross workflow step boundaries without serialization errors.
+
+- ff5eba1: feat: roll `image-*` tool output types into their equivalent `file-*` types
+- Updated dependencies [ff5eba1]
+  - @ai-sdk/provider@4.0.0-beta.12
+
 ## 5.0.0-beta.19
 
 ### Major Changes

package/dist/index.d.ts

@@ -1,8 +1,9 @@
-import { LanguageModelV4FunctionTool, LanguageModelV4ProviderTool, ImageModelV4File, AISDKError, JSONSchema7, JSONParseError, TypeValidationError, JSONValue, APICallError, LanguageModelV4Prompt, LanguageModelV4FilePart, SharedV4ProviderReference, LanguageModelV4CallOptions, SharedV4Warning, SharedV4ProviderOptions, TypeValidationContext } from '@ai-sdk/provider';
+import { ImageModelV4File, LanguageModelV4FunctionTool, LanguageModelV4ProviderTool, AISDKError, JSONSchema7, JSONParseError, TypeValidationError, JSONValue, APICallError, LanguageModelV4Prompt, LanguageModelV4FilePart, SharedV4ProviderReference, LanguageModelV4CallOptions, SharedV4Warning, SharedV4ProviderOptions, JSONObject, TypeValidationContext } from '@ai-sdk/provider';
 import { StandardSchemaV1, StandardJSONSchemaV1 } from '@standard-schema/spec';
 export * from '@standard-schema/spec';
 import * as z3 from 'zod/v3';
 import * as z4 from 'zod/v4';
+export { WORKFLOW_DESERIALIZE, WORKFLOW_SERIALIZE } from '@workflow/serde';
 export { EventSourceMessage, EventSourceParserStream } from 'eventsource-parser/stream';
 
 declare function combineHeaders(...headers: Array<Record<string, string | undefined> | undefined>): Record<string, string | undefined>;
@@ -16,6 +17,50 @@ declare function combineHeaders(...headers: Array<Record<string, string | undefi
  */
 declare function convertAsyncIteratorToReadableStream<T>(iterator: AsyncIterator<T>): ReadableStream<T>;
 
+/**
+ * Convert an ImageModelV4File to a URL or data URI string.
+ *
+ * If the file is a URL, it returns the URL as-is.
+ * If the file is base64 data, it returns a data URI with the base64 data.
+ * If the file is a Uint8Array, it converts it to base64 and returns a data URI.
+ */
+declare function convertImageModelFileToDataUri(file: ImageModelV4File): string;
+
+/**
+ * Converts an input object to FormData for multipart/form-data requests.
+ *
+ * Handles the following cases:
+ * - `null` or `undefined` values are skipped
+ * - Arrays with a single element are appended as a single value
+ * - Arrays with multiple elements are appended with `[]` suffix (e.g., `image[]`)
+ *   unless `useArrayBrackets` is set to `false`
+ * - All other values are appended directly
+ *
+ * @param input - The input object to convert. Use a generic type for type validation.
+ * @param options - Optional configuration object.
+ * @param options.useArrayBrackets - Whether to add `[]` suffix for multi-element arrays.
+ *   Defaults to `true`. Set to `false` for APIs that expect repeated keys without brackets.
+ * @returns A FormData object containing the input values.
+ *
+ * @example
+ * ```ts
+ * type MyInput = {
+ *   model: string;
+ *   prompt: string;
+ *   images: Blob[];
+ * };
+ *
+ * const formData = convertToFormData<MyInput>({
+ *   model: 'gpt-image-1',
+ *   prompt: 'A cat',
+ *   images: [blob1, blob2],
+ * });
+ * ```
+ */
+declare function convertToFormData<T extends Record<string, unknown>>(input: T, options?: {
+    useArrayBrackets?: boolean;
+}): FormData;
+
 /**
  * Interface for mapping between custom tool names and provider tool names.
  */
@@ -81,60 +126,6 @@ declare class DelayedPromise<T> {
     isPending(): boolean;
 }
 
-/**
- * Extracts the headers from a response object and returns them as a key-value object.
- *
- * @param response - The response object to extract headers from.
- * @returns The headers as a key-value object.
- */
-declare function extractResponseHeaders(response: Response): {
-    [k: string]: string;
-};
-
-/**
- * Convert an ImageModelV4File to a URL or data URI string.
- *
- * If the file is a URL, it returns the URL as-is.
- * If the file is base64 data, it returns a data URI with the base64 data.
- * If the file is a Uint8Array, it converts it to base64 and returns a data URI.
- */
-declare function convertImageModelFileToDataUri(file: ImageModelV4File): string;
-
-/**
- * Converts an input object to FormData for multipart/form-data requests.
- *
- * Handles the following cases:
- * - `null` or `undefined` values are skipped
- * - Arrays with a single element are appended as a single value
- * - Arrays with multiple elements are appended with `[]` suffix (e.g., `image[]`)
- *   unless `useArrayBrackets` is set to `false`
- * - All other values are appended directly
- *
- * @param input - The input object to convert. Use a generic type for type validation.
- * @param options - Optional configuration object.
- * @param options.useArrayBrackets - Whether to add `[]` suffix for multi-element arrays.
- *   Defaults to `true`. Set to `false` for APIs that expect repeated keys without brackets.
- * @returns A FormData object containing the input values.
- *
- * @example
- * ```ts
- * type MyInput = {
- *   model: string;
- *   prompt: string;
- *   images: Blob[];
- * };
- *
- * const formData = convertToFormData<MyInput>({
- *   model: 'gpt-image-1',
- *   prompt: 'A cat',
- *   images: [blob1, blob2],
- * });
- * ```
- */
-declare function convertToFormData<T extends Record<string, unknown>>(input: T, options?: {
-    useArrayBrackets?: boolean;
-}): FormData;
-
 /**
  * Download a file from a URL and return it as a Blob.
  *
@@ -168,35 +159,14 @@ declare class DownloadError extends AISDKError {
 }
 
 /**
- * Default maximum download size: 2 GiB.
- *
- * `fetch().arrayBuffer()` has ~2x peak memory overhead (undici buffers the
- * body internally, then creates the JS ArrayBuffer), so very large downloads
- * risk exceeding the default V8 heap limit on 64-bit systems and terminating
- * the process with an out-of-memory error.
- *
- * Setting this limit converts an unrecoverable OOM crash into a catchable
- * `DownloadError`.
- */
-declare const DEFAULT_MAX_DOWNLOAD_SIZE: number;
-/**
- * Reads a fetch Response body with a size limit to prevent memory exhaustion.
- *
- * Checks the Content-Length header for early rejection, then reads the body
- * incrementally via ReadableStream and aborts with a DownloadError when the
- * limit is exceeded.
+ * Extracts the headers from a response object and returns them as a key-value object.
  *
- * @param response - The fetch Response to read.
- * @param url - The URL being downloaded (used in error messages).
- * @param maxBytes - Maximum allowed bytes. Defaults to DEFAULT_MAX_DOWNLOAD_SIZE.
- * @returns A Uint8Array containing the response body.
- * @throws DownloadError if the response exceeds maxBytes.
+ * @param response - The response object to extract headers from.
+ * @returns The headers as a key-value object.
  */
-declare function readResponseWithSizeLimit({ response, url, maxBytes, }: {
-    response: Response;
-    url: string;
-    maxBytes?: number;
-}): Promise<Uint8Array>;
+declare function extractResponseHeaders(response: Response): {
+    [k: string]: string;
+};
 
 /**
  * Fetch function type (standardizes the version of fetch used).
@@ -439,6 +409,34 @@ declare function loadApiKey({ apiKey, environmentVariableName, apiKeyParameterNa
     description: string;
 }): string;
 
+/**
+ * Loads an optional `string` setting from the environment or a parameter.
+ *
+ * @param settingValue - The setting value.
+ * @param environmentVariableName - The environment variable name.
+ * @returns The setting value.
+ */
+declare function loadOptionalSetting({ settingValue, environmentVariableName, }: {
+    settingValue: string | undefined;
+    environmentVariableName: string;
+}): string | undefined;
+
+/**
+ * Loads a `string` setting from the environment or a parameter.
+ *
+ * @param settingValue - The setting value.
+ * @param environmentVariableName - The environment variable name.
+ * @param settingName - The setting name.
+ * @param description - The description of the setting.
+ * @returns The setting value.
+ */
+declare function loadSetting({ settingValue, environmentVariableName, settingName, description, }: {
+    settingValue: string | undefined;
+    environmentVariableName: string;
+    settingName: string;
+    description: string;
+}): string;
+
 type ReasoningLevel = Exclude<LanguageModelV4CallOptions['reasoning'], 'none' | 'provider-default' | undefined>;
 declare function isCustomReasoning(reasoning: LanguageModelV4CallOptions['reasoning']): reasoning is Exclude<LanguageModelV4CallOptions['reasoning'], 'provider-default' | undefined>;
 /**
@@ -474,34 +472,6 @@ declare function mapReasoningToProviderBudget({ reasoning, maxOutputTokens, maxR
     warnings: SharedV4Warning[];
 }): number | undefined;
 
-/**
- * Loads an optional `string` setting from the environment or a parameter.
- *
- * @param settingValue - The setting value.
- * @param environmentVariableName - The environment variable name.
- * @returns The setting value.
- */
-declare function loadOptionalSetting({ settingValue, environmentVariableName, }: {
-    settingValue: string | undefined;
-    environmentVariableName: string;
-}): string | undefined;
-
-/**
- * Loads a `string` setting from the environment or a parameter.
- *
- * @param settingValue - The setting value.
- * @param environmentVariableName - The environment variable name.
- * @param settingName - The setting name.
- * @param description - The description of the setting.
- * @returns The setting value.
- */
-declare function loadSetting({ settingValue, environmentVariableName, settingName, description, }: {
-    settingValue: string | undefined;
-    environmentVariableName: string;
-    settingName: string;
-    description: string;
-}): string;
-
 type MaybePromiseLike<T> = T | PromiseLike<T>;
 
 /**
@@ -869,6 +839,11 @@ type ToolResultOutput = {
          * URL of the file.
          */
         url: string;
+        /**
+         * IANA media type.
+         * @see https://www.iana.org/assignments/media-types/media-types.xhtml
+         */
+        mediaType?: string;
         /**
          * Provider-specific options.
          */
@@ -904,7 +879,7 @@ type ToolResultOutput = {
         providerOptions?: ProviderOptions;
     } | {
         /**
-         * Images that are referenced using base64 encoded data.
+         * @deprecated Use file-data instead.
          */
         type: 'image-data';
         /**
@@ -922,7 +897,7 @@ type ToolResultOutput = {
         providerOptions?: ProviderOptions;
     } | {
         /**
-         * Images that are referenced using a URL.
+         * @deprecated Use file-url instead.
          */
         type: 'image-url';
         /**
@@ -935,7 +910,7 @@ type ToolResultOutput = {
         providerOptions?: ProviderOptions;
     } | {
         /**
-         * @deprecated Use image-file-reference instead.
+         * @deprecated Use file-reference instead.
          */
         type: 'image-file-id';
         /**
@@ -953,7 +928,7 @@ type ToolResultOutput = {
         providerOptions?: ProviderOptions;
     } | {
         /**
-         * Images that are referenced using a provider reference.
+         * @deprecated Use file-reference instead.
          */
         type: 'image-file-reference';
         /**
@@ -1395,6 +1370,37 @@ declare function createProviderToolFactoryWithOutputSchema<INPUT, OUTPUT, ARGS e
     supportsDeferredResults?: boolean;
 }): ProviderToolFactoryWithOutputSchema<INPUT, OUTPUT, ARGS, CONTEXT>;
 
+/**
+ * Default maximum download size: 2 GiB.
+ *
+ * `fetch().arrayBuffer()` has ~2x peak memory overhead (undici buffers the
+ * body internally, then creates the JS ArrayBuffer), so very large downloads
+ * risk exceeding the default V8 heap limit on 64-bit systems and terminating
+ * the process with an out-of-memory error.
+ *
+ * Setting this limit converts an unrecoverable OOM crash into a catchable
+ * `DownloadError`.
+ */
+declare const DEFAULT_MAX_DOWNLOAD_SIZE: number;
+/**
+ * Reads a fetch Response body with a size limit to prevent memory exhaustion.
+ *
+ * Checks the Content-Length header for early rejection, then reads the body
+ * incrementally via ReadableStream and aborts with a DownloadError when the
+ * limit is exceeded.
+ *
+ * @param response - The fetch Response to read.
+ * @param url - The URL being downloaded (used in error messages).
+ * @param maxBytes - Maximum allowed bytes. Defaults to DEFAULT_MAX_DOWNLOAD_SIZE.
+ * @returns A Uint8Array containing the response body.
+ * @throws DownloadError if the response exceeds maxBytes.
+ */
+declare function readResponseWithSizeLimit({ response, url, maxBytes, }: {
+    response: Response;
+    url: string;
+    maxBytes?: number;
+}): Promise<Uint8Array>;
+
 /**
  * Removes entries from a record where the value is null or undefined.
  * @param record - The input object whose entries may be null or undefined.
@@ -1402,6 +1408,28 @@ declare function createProviderToolFactoryWithOutputSchema<INPUT, OUTPUT, ARGS e
  */
 declare function removeUndefinedEntries<T>(record: Record<string, T | undefined>): Record<string, T>;
 
+/**
+ * A value or a lazy provider of a value, each of which may be synchronous or asynchronous.
+ *
+ * @template T The resolved type after {@link resolve} runs.
+ *
+ * One of:
+ * - A plain value of type {@link T}
+ * - A {@link PromiseLike} of {@link T} (e.g. a `Promise<T>`)
+ * - A zero-argument function that returns a plain {@link T}
+ * - A zero-argument function that returns a {@link PromiseLike} of {@link T}
+ *
+ * The function form is only invoked when passed to {@link resolve}; it is not distinguished from
+ * a {@link T} that happens to be a function—callers should wrap function values if disambiguation
+ * is required.
+ */
+type Resolvable<T> = MaybePromiseLike<T> | (() => MaybePromiseLike<T>);
+/**
+ * Resolves a value that could be a raw value, a Promise, a function returning a value,
+ * or a function returning a Promise.
+ */
+declare function resolve<T>(value: Resolvable<T>): Promise<T>;
+
 /**
  * Resolves a provider reference to the provider-specific identifier for the
  * given provider. Throws `NoSuchProviderReferenceError` if the provider is not
@@ -1412,12 +1440,35 @@ declare function resolveProviderReference({ reference, provider, }: {
     provider: string;
 }): string;
 
-type Resolvable<T> = MaybePromiseLike<T> | (() => MaybePromiseLike<T>);
 /**
- * Resolves a value that could be a raw value, a Promise, a function returning a value,
- * or a function returning a Promise.
+ * 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,
+ *   });
+ * }
+ * ```
  */
-declare function resolve<T>(value: Resolvable<T>): Promise<T>;
+declare function serializeModelOptions<CONFIG extends {
+    headers?: Resolvable<Record<string, string | undefined>>;
+}>(options: {
+    modelId: string;
+    config: CONFIG;
+}): {
+    modelId: string;
+    config: JSONObject;
+};
 
 /**
  * Strips file extension segments from a filename.
@@ -1633,4 +1684,4 @@ interface ToolResult<NAME extends string, INPUT, OUTPUT> {
     dynamic?: boolean;
 }
 
-export { type AssistantContent, type AssistantModelMessage, type Context, type CustomPart, DEFAULT_MAX_DOWNLOAD_SIZE, type DataContent, DelayedPromise, DownloadError, type FetchFunction, type FilePart, type FlexibleSchema, type HasRequiredKey, type IdGenerator, type ImagePart, type InferSchema, type InferToolContext, type InferToolInput, type InferToolOutput, type InferToolSetContext, type LazySchema, type MaybePromiseLike, type ModelMessage, type ParseResult, type ProviderOptions, type ProviderReference, type ProviderToolFactory, type ProviderToolFactoryWithOutputSchema, type ReasoningFilePart, type ReasoningPart, type Resolvable, type ResponseHandler, type Schema, type SystemModelMessage, type TextPart, type Tool, type ToolApprovalRequest, type ToolApprovalResponse, type ToolCall, type ToolCallPart, type ToolContent, type ToolExecuteFunction, type ToolExecutionOptions, type ToolModelMessage, type ToolNameMapping, type ToolNeedsApprovalFunction, type ToolResult, type ToolResultOutput, type ToolResultPart, type ToolSet, type UserContent, type UserModelMessage, VERSION, type ValidationResult, asSchema, combineHeaders, convertAsyncIteratorToReadableStream, convertBase64ToUint8Array, convertImageModelFileToDataUri, convertToBase64, convertToFormData, convertUint8ArrayToBase64, createBinaryResponseHandler, createEventSourceResponseHandler, createIdGenerator, createJsonErrorResponseHandler, createJsonResponseHandler, createProviderToolFactory, createProviderToolFactoryWithOutputSchema, createStatusCodeErrorResponseHandler, createToolNameMapping, delay, downloadBlob, dynamicTool, executeTool, extractResponseHeaders, generateId, getErrorMessage, getFromApi, getRuntimeEnvironmentUserAgent, injectJsonInstructionIntoMessages, isAbortError, isCustomReasoning, isNonNullable, isParsableJson, isProviderReference, isUrlSupported, jsonSchema, lazySchema, loadApiKey, loadOptionalSetting, loadSetting, mapReasoningToProviderBudget, mapReasoningToProviderEffort, mediaTypeToExtension, normalizeHeaders, parseJSON, parseJsonEventStream, parseProviderOptions, postFormDataToApi, postJsonToApi, postToApi, readResponseWithSizeLimit, removeUndefinedEntries, resolve, resolveProviderReference, safeParseJSON, safeValidateTypes, stripFileExtension, tool, validateDownloadUrl, validateTypes, withUserAgentSuffix, withoutTrailingSlash, zodSchema };
+export { type AssistantContent, type AssistantModelMessage, type Context, type CustomPart, DEFAULT_MAX_DOWNLOAD_SIZE, type DataContent, DelayedPromise, DownloadError, type FetchFunction, type FilePart, type FlexibleSchema, type HasRequiredKey, type IdGenerator, type ImagePart, type InferSchema, type InferToolContext, type InferToolInput, type InferToolOutput, type InferToolSetContext, type LazySchema, type MaybePromiseLike, type ModelMessage, type ParseResult, type ProviderOptions, type ProviderReference, type ProviderToolFactory, type ProviderToolFactoryWithOutputSchema, type ReasoningFilePart, type ReasoningPart, type Resolvable, type ResponseHandler, type Schema, type SystemModelMessage, type TextPart, type Tool, type ToolApprovalRequest, type ToolApprovalResponse, type ToolCall, type ToolCallPart, type ToolContent, type ToolExecuteFunction, type ToolExecutionOptions, type ToolModelMessage, type ToolNameMapping, type ToolNeedsApprovalFunction, type ToolResult, type ToolResultOutput, type ToolResultPart, type ToolSet, type UserContent, type UserModelMessage, VERSION, type ValidationResult, asSchema, combineHeaders, convertAsyncIteratorToReadableStream, convertBase64ToUint8Array, convertImageModelFileToDataUri, convertToBase64, convertToFormData, convertUint8ArrayToBase64, createBinaryResponseHandler, createEventSourceResponseHandler, createIdGenerator, createJsonErrorResponseHandler, createJsonResponseHandler, createProviderToolFactory, createProviderToolFactoryWithOutputSchema, createStatusCodeErrorResponseHandler, createToolNameMapping, delay, downloadBlob, dynamicTool, executeTool, extractResponseHeaders, generateId, getErrorMessage, getFromApi, getRuntimeEnvironmentUserAgent, injectJsonInstructionIntoMessages, isAbortError, isCustomReasoning, isNonNullable, isParsableJson, isProviderReference, isUrlSupported, jsonSchema, lazySchema, loadApiKey, loadOptionalSetting, loadSetting, mapReasoningToProviderBudget, mapReasoningToProviderEffort, mediaTypeToExtension, normalizeHeaders, parseJSON, parseJsonEventStream, parseProviderOptions, postFormDataToApi, postJsonToApi, postToApi, readResponseWithSizeLimit, removeUndefinedEntries, resolve, resolveProviderReference, safeParseJSON, safeValidateTypes, serializeModelOptions, stripFileExtension, tool, validateDownloadUrl, validateTypes, withUserAgentSuffix, withoutTrailingSlash, zodSchema };