@ai-sdk/provider-utils 5.0.0-beta.28 → 5.0.0-beta.29

package/src/types/content-part.ts

@@ -1,7 +1,8 @@
-import { JSONValue } from '@ai-sdk/provider';
-import { DataContent } from './data-content';
-import { ProviderOptions } from './provider-options';
-import { ProviderReference } from './provider-reference';
+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.
@@ -24,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';
@@ -59,13 +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 file
-   * - ProviderReference: a provider reference from `uploadFile`
+   * - `{ 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 | ProviderReference;
+  data: FileData | DataContent | URL | ProviderReference;
 
   /**
    * Optional filename of the file.
@@ -73,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
    */
@@ -133,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.

package/src/types/executable-tool.ts

@@ -1,4 +1,4 @@
-import { Tool } from './tool';
+import type { Tool } from './tool';
 
 /**
  * A tool that is guaranteed to expose an execute function.

package/src/types/execute-tool.ts

@@ -1,9 +1,10 @@
 import { isAsyncIterable } from '../is-async-iterable';
-import { ExecutableTool } from './executable-tool';
-import { InferToolContext } from './infer-tool-context';
-import { InferToolInput } from './infer-tool-input';
-import { InferToolOutput } from './infer-tool-output';
-import { Tool, ToolExecutionOptions } 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';
 
 /**
  * Executes a tool function and normalizes its results into a stream of outputs.

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;

package/src/types/index.ts

@@ -16,6 +16,13 @@ export type {
 export type { Context } from './context';
 export type { DataContent } from './data-content';
 export { executeTool } from './execute-tool';
+export type {
+  FileData,
+  FileDataData,
+  FileDataReference,
+  FileDataText,
+  FileDataUrl,
+} from './file-data';
 export { isExecutableTool, type ExecutableTool } from './executable-tool';
 export type { InferToolContext } from './infer-tool-context';
 export type { InferToolInput } from './infer-tool-input';
@@ -29,11 +36,17 @@ export type { SystemModelMessage } from './system-model-message';
 export {
   dynamicTool,
   tool,
+  type DynamicTool,
+  type FunctionTool,
+  type ProviderDefinedTool,
+  type ProviderExecutedTool,
   type Tool,
-  type ToolExecuteFunction,
-  type ToolExecutionOptions,
-  type ToolNeedsApprovalFunction,
 } from './tool';
+export type {
+  ToolExecuteFunction,
+  ToolExecutionOptions,
+} from './tool-execute-function';
+export type { ToolNeedsApprovalFunction } from './tool-needs-approval-function';
 export type { ToolSet } from './tool-set';
 export type { ToolApprovalRequest } from './tool-approval-request';
 export type { ToolApprovalResponse } from './tool-approval-response';

package/src/types/infer-tool-context.ts

@@ -1,4 +1,4 @@
-import { HasRequiredKey } from '../has-required-key';
+import type { HasRequiredKey } from '../has-required-key';
 import type { Tool } from './tool';
 
 /**

package/src/types/model-message.ts

@@ -1,7 +1,7 @@
-import { AssistantModelMessage } from './assistant-model-message';
-import { SystemModelMessage } from './system-model-message';
-import { ToolModelMessage } from './tool-model-message';
-import { UserModelMessage } from './user-model-message';
+import type { AssistantModelMessage } from './assistant-model-message';
+import type { SystemModelMessage } from './system-model-message';
+import type { ToolModelMessage } from './tool-model-message';
+import type { UserModelMessage } from './user-model-message';
 
 /**
  * A message that can be used in the `messages` field of a prompt.

package/src/types/never-optional.ts

@@ -0,0 +1,7 @@
+// 0 extends 1 & N checks for any
+// [N] extends [never] checks for never
+export type NeverOptional<N, T> = 0 extends 1 & N
+  ? Partial<T>
+  : [N] extends [never]
+    ? Partial<Record<keyof T, undefined>>
+    : T;

package/src/types/provider-options.ts

@@ -1,4 +1,4 @@
-import { SharedV4ProviderOptions } from '@ai-sdk/provider';
+import type { SharedV4ProviderOptions } from '@ai-sdk/provider';
 
 /**
  * Additional provider-specific options.

package/src/types/provider-reference.ts

@@ -1,4 +1,4 @@
-import { SharedV4ProviderReference } from '@ai-sdk/provider';
+import type { SharedV4ProviderReference } from '@ai-sdk/provider';
 
 /**
  * A mapping of provider names to provider-specific file identifiers.

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

@@ -1,4 +1,4 @@
-import { ProviderOptions } from './provider-options';
+import type { ProviderOptions } from './provider-options';
 
 /**
  * A system message. It can contain system information.

package/src/types/tool-execute-function.ts

@@ -0,0 +1,50 @@
+import type { Context } from './context';
+import type { ModelMessage } from './model-message';
+
+/**
+ * Additional options that are sent into each tool execution.
+ */
+export interface ToolExecutionOptions<
+  CONTEXT extends Context | unknown | never,
+> {
+  /**
+   * 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;
+
+  /**
+   * Tool context as defined by the tool's context schema.
+   * The tool context is specific to the tool and is passed to the tool execution.
+   *
+   * 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.
+   */
+  context: CONTEXT;
+}
+
+/**
+ * Function that executes the tool and returns either a single result or a stream of results.
+ */
+export type ToolExecuteFunction<
+  INPUT,
+  OUTPUT,
+  CONTEXT extends Context | unknown | never,
+> = (
+  input: INPUT,
+  options: ToolExecutionOptions<CONTEXT>,
+) => AsyncIterable<OUTPUT> | PromiseLike<OUTPUT> | OUTPUT;

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

@@ -1,6 +1,6 @@
-import { ToolResultPart } from './content-part';
-import { ProviderOptions } from './provider-options';
-import { ToolApprovalResponse } from './tool-approval-response';
+import type { ToolResultPart } from './content-part';
+import type { ProviderOptions } from './provider-options';
+import type { ToolApprovalResponse } from './tool-approval-response';
 
 /**
  * A tool message. It contains the result of one or more tool calls.

package/src/types/tool-needs-approval-function.ts

@@ -0,0 +1,39 @@
+import type { Context } from './context';
+import type { ModelMessage } from './model-message';
+
+/**
+ * Function that is called to determine if the tool needs approval before it can be executed.
+ *
+ * @deprecated Tool approval is handled on a `generateText` / `streamText` level now.
+ */
+export type ToolNeedsApprovalFunction<
+  INPUT,
+  CONTEXT extends Context | unknown | never,
+> = (
+  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[];
+
+    /**
+     * Tool context as defined by the tool's context schema.
+     * The tool context is specific to the tool and is passed to the tool execution.
+     *
+     * 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.
+     */
+    context: CONTEXT;
+  },
+) => boolean | PromiseLike<boolean>;