@ai-sdk/openai 4.0.0-beta.3 → 4.0.0-beta.31

package/src/responses/openai-responses-prepare-tools.ts

@@ -1,15 +1,21 @@
 import {
-  LanguageModelV3CallOptions,
-  SharedV3Warning,
+  LanguageModelV4CallOptions,
+  SharedV4ProviderReference,
+  SharedV4Warning,
   UnsupportedFunctionalityError,
 } from '@ai-sdk/provider';
-import { ToolNameMapping, validateTypes } from '@ai-sdk/provider-utils';
+import {
+  resolveProviderReference,
+  ToolNameMapping,
+  validateTypes,
+} from '@ai-sdk/provider-utils';
 import { codeInterpreterArgsSchema } from '../tool/code-interpreter';
 import { fileSearchArgsSchema } from '../tool/file-search';
 import { imageGenerationArgsSchema } from '../tool/image-generation';
 import { customArgsSchema } from '../tool/custom';
 import { mcpArgsSchema } from '../tool/mcp';
 import { shellArgsSchema } from '../tool/shell';
+import { toolSearchArgsSchema } from '../tool/tool-search';
 import { webSearchArgsSchema } from '../tool/web-search';
 import { webSearchPreviewArgsSchema } from '../tool/web-search-preview';
 import { OpenAIResponsesTool } from './openai-responses-api';
@@ -20,8 +26,8 @@ export async function prepareResponsesTools({
   toolNameMapping,
   customProviderToolNames,
 }: {
-  tools: LanguageModelV3CallOptions['tools'];
-  toolChoice: LanguageModelV3CallOptions['toolChoice'] | undefined;
+  tools: LanguageModelV4CallOptions['tools'];
+  toolChoice: LanguageModelV4CallOptions['toolChoice'] | undefined;
   toolNameMapping?: ToolNameMapping;
   customProviderToolNames?: Set<string>;
 }): Promise<{
@@ -39,12 +45,12 @@ export async function prepareResponsesTools({
     | { type: 'mcp' }
     | { type: 'image_generation' }
     | { type: 'apply_patch' };
-  toolWarnings: SharedV3Warning[];
+  toolWarnings: SharedV4Warning[];
 }> {
   // when the tools array is empty, change it to undefined to prevent errors:
   tools = tools?.length ? tools : undefined;
 
-  const toolWarnings: SharedV3Warning[] = [];
+  const toolWarnings: SharedV4Warning[] = [];
 
   if (tools == null) {
     return { tools: undefined, toolChoice: undefined, toolWarnings };
@@ -56,15 +62,22 @@ export async function prepareResponsesTools({
 
   for (const tool of tools) {
     switch (tool.type) {
-      case 'function':
+      case 'function': {
+        const openaiOptions = tool.providerOptions?.openai as
+          | { deferLoading?: boolean }
+          | undefined;
+        const deferLoading = openaiOptions?.deferLoading;
+
         openaiTools.push({
           type: 'function',
           name: tool.name,
           description: tool.description,
           parameters: tool.inputSchema,
           ...(tool.strict != null ? { strict: tool.strict } : {}),
+          ...(deferLoading != null ? { defer_loading: deferLoading } : {}),
         });
         break;
+      }
       case 'provider': {
         switch (tool.id) {
           case 'openai.file_search': {
@@ -241,11 +254,28 @@ export async function prepareResponsesTools({
 
             openaiTools.push({
               type: 'custom',
-              name: args.name,
+              name: tool.name,
               description: args.description,
               format: args.format,
             });
-            resolvedCustomProviderToolNames.add(args.name);
+            resolvedCustomProviderToolNames.add(tool.name);
+            break;
+          }
+          case 'openai.tool_search': {
+            const args = await validateTypes({
+              value: tool.args,
+              schema: toolSearchArgsSchema,
+            });
+            openaiTools.push({
+              type: 'tool_search',
+              ...(args.execution != null ? { execution: args.execution } : {}),
+              ...(args.description != null
+                ? { description: args.description }
+                : {}),
+              ...(args.parameters != null
+                ? { parameters: args.parameters }
+                : {}),
+            });
             break;
           }
         }
@@ -335,7 +365,7 @@ function mapShellEnvironment(environment: {
       };
       skills?: Array<{
         type: string;
-        skillId?: string;
+        providerReference?: SharedV4ProviderReference;
         version?: string;
         name?: string;
         description?: string;
@@ -379,7 +409,7 @@ function mapShellSkills(
   skills:
     | Array<{
         type: string;
-        skillId?: string;
+        providerReference?: SharedV4ProviderReference;
         version?: string;
         name?: string;
         description?: string;
@@ -391,8 +421,11 @@ function mapShellSkills(
     skill.type === 'skillReference'
       ? {
           type: 'skill_reference' as const,
-          skill_id: skill.skillId!,
-          version: skill.version,
+          skill_id: resolveProviderReference({
+            reference: skill.providerReference ?? {},
+            provider: 'openai',
+          }),
+          version: skill.version ?? 'latest',
         }
       : {
           type: 'inline' as const,

package/src/responses/openai-responses-provider-metadata.ts

@@ -30,6 +30,16 @@ export type OpenaiResponsesProviderMetadata = {
   openai: ResponsesProviderMetadata;
 };
 
+export type ResponsesCompactionProviderMetadata = {
+  type: 'compaction';
+  itemId: string;
+  encryptedContent?: string;
+};
+
+export type OpenaiResponsesCompactionProviderMetadata = {
+  openai: ResponsesCompactionProviderMetadata;
+};
+
 export type ResponsesTextProviderMetadata = {
   itemId: string;
   phase?: 'commentary' | 'final_answer' | null;

package/src/skills/openai-skills-api.ts

@@ -0,0 +1,31 @@
+import { lazySchema, zodSchema } from '@ai-sdk/provider-utils';
+import { z } from 'zod/v4';
+
+export const openaiSkillResponseSchema = lazySchema(() =>
+  zodSchema(
+    z.object({
+      id: z.string(),
+      name: z.string().nullish(),
+      description: z.string().nullish(),
+      default_version: z.string().nullish(),
+      latest_version: z.string().nullish(),
+      created_at: z.number(),
+      updated_at: z.number().nullish(),
+    }),
+  ),
+);
+
+export type OpenAISkillResponse = ReturnType<
+  typeof openaiSkillResponseSchema
+>['_type'];
+
+export const openaiSkillVersionResponseSchema = lazySchema(() =>
+  zodSchema(
+    z.object({
+      id: z.string(),
+      version: z.string().nullish(),
+      name: z.string().nullish(),
+      description: z.string().nullish(),
+    }),
+  ),
+);

package/src/skills/openai-skills.ts

@@ -0,0 +1,87 @@
+import { SkillsV4, SharedV4Warning } from '@ai-sdk/provider';
+import {
+  combineHeaders,
+  convertBase64ToUint8Array,
+  createJsonResponseHandler,
+  FetchFunction,
+  postFormDataToApi,
+} from '@ai-sdk/provider-utils';
+import { openaiFailedResponseHandler } from '../openai-error';
+import { openaiSkillResponseSchema } from './openai-skills-api';
+
+interface OpenAISkillsConfig {
+  provider: string;
+  url: (options: { path: string }) => string;
+  headers: () => Record<string, string | undefined>;
+  fetch?: FetchFunction;
+}
+
+export class OpenAISkills implements SkillsV4 {
+  readonly specificationVersion = 'v4';
+
+  get provider(): string {
+    return this.config.provider;
+  }
+
+  constructor(private readonly config: OpenAISkillsConfig) {}
+
+  async uploadSkill(
+    params: Parameters<SkillsV4['uploadSkill']>[0],
+  ): Promise<Awaited<ReturnType<SkillsV4['uploadSkill']>>> {
+    const warnings: SharedV4Warning[] = [];
+
+    if (params.displayTitle != null) {
+      warnings.push({
+        type: 'unsupported',
+        feature: 'displayTitle',
+      });
+    }
+
+    const formData = new FormData();
+
+    for (const file of params.files) {
+      const content =
+        typeof file.content === 'string'
+          ? convertBase64ToUint8Array(file.content)
+          : file.content;
+
+      formData.append('files[]', new Blob([content]), file.path);
+    }
+
+    const { value: response } = await postFormDataToApi({
+      url: this.config.url({ path: '/skills' }),
+      headers: combineHeaders(this.config.headers()),
+      formData,
+      failedResponseHandler: openaiFailedResponseHandler,
+      successfulResponseHandler: createJsonResponseHandler(
+        openaiSkillResponseSchema,
+      ),
+      fetch: this.config.fetch,
+    });
+
+    return {
+      providerReference: { openai: response.id },
+      ...(response.name != null ? { name: response.name } : {}),
+      ...(response.description != null
+        ? { description: response.description }
+        : {}),
+      ...(response.latest_version != null
+        ? { latestVersion: response.latest_version }
+        : {}),
+      providerMetadata: {
+        openai: {
+          ...(response.default_version != null
+            ? { defaultVersion: response.default_version }
+            : {}),
+          ...(response.created_at != null
+            ? { createdAt: response.created_at }
+            : {}),
+          ...(response.updated_at != null
+            ? { updatedAt: response.updated_at }
+            : {}),
+        },
+      },
+      warnings,
+    };
+  }
+}

package/src/speech/openai-speech-model.ts

@@ -1,9 +1,12 @@
-import { SpeechModelV3, SharedV3Warning } from '@ai-sdk/provider';
+import { SpeechModelV4, SharedV4Warning } from '@ai-sdk/provider';
 import {
   combineHeaders,
   createBinaryResponseHandler,
   parseProviderOptions,
   postJsonToApi,
+  serializeModelOptions,
+  WORKFLOW_DESERIALIZE,
+  WORKFLOW_SERIALIZE,
 } from '@ai-sdk/provider-utils';
 import { OpenAIConfig } from '../openai-config';
 import { openaiFailedResponseHandler } from '../openai-error';
@@ -19,8 +22,22 @@ interface OpenAISpeechModelConfig extends OpenAIConfig {
   };
 }
 
-export class OpenAISpeechModel implements SpeechModelV3 {
-  readonly specificationVersion = 'v3';
+export class OpenAISpeechModel implements SpeechModelV4 {
+  readonly specificationVersion = 'v4';
+
+  static [WORKFLOW_SERIALIZE](model: OpenAISpeechModel) {
+    return serializeModelOptions({
+      modelId: model.modelId,
+      config: model.config,
+    });
+  }
+
+  static [WORKFLOW_DESERIALIZE](options: {
+    modelId: OpenAISpeechModelId;
+    config: OpenAISpeechModelConfig;
+  }) {
+    return new OpenAISpeechModel(options.modelId, options.config);
+  }
 
   get provider(): string {
     return this.config.provider;
@@ -39,8 +56,8 @@ export class OpenAISpeechModel implements SpeechModelV3 {
     instructions,
     language,
     providerOptions,
-  }: Parameters<SpeechModelV3['doGenerate']>[0]) {
-    const warnings: SharedV3Warning[] = [];
+  }: Parameters<SpeechModelV4['doGenerate']>[0]) {
+    const warnings: SharedV4Warning[] = [];
 
     // Parse provider options
     const openAIOptions = await parseProviderOptions({
@@ -98,8 +115,8 @@ export class OpenAISpeechModel implements SpeechModelV3 {
   }
 
   async doGenerate(
-    options: Parameters<SpeechModelV3['doGenerate']>[0],
-  ): Promise<Awaited<ReturnType<SpeechModelV3['doGenerate']>>> {
+    options: Parameters<SpeechModelV4['doGenerate']>[0],
+  ): Promise<Awaited<ReturnType<SpeechModelV4['doGenerate']>>> {
     const currentDate = this.config._internal?.currentDate?.() ?? new Date();
     const { requestBody, warnings } = await this.getArgs(options);
 
@@ -112,7 +129,7 @@ export class OpenAISpeechModel implements SpeechModelV3 {
         path: '/audio/speech',
         modelId: this.modelId,
       }),
-      headers: combineHeaders(this.config.headers(), options.headers),
+      headers: combineHeaders(this.config.headers?.(), options.headers),
       body: requestBody,
       failedResponseHandler: openaiFailedResponseHandler,
       successfulResponseHandler: createBinaryResponseHandler(),

package/src/tool/custom.ts

@@ -8,7 +8,6 @@ import { z } from 'zod/v4';
 export const customArgsSchema = lazySchema(() =>
   zodSchema(
     z.object({
-      name: z.string(),
       description: z.string().optional(),
       format: z
         .union([
@@ -31,11 +30,6 @@ const customInputSchema = lazySchema(() => zodSchema(z.string()));
 export const customToolFactory = createProviderToolFactory<
   string,
   {
-    /**
-     * The name of the custom tool, used to identify it in the API.
-     */
-    name: string;
-
     /**
      * An optional description of what the tool does.
      */

package/src/tool/shell.ts

@@ -3,6 +3,7 @@ import {
   lazySchema,
   zodSchema,
 } from '@ai-sdk/provider-utils';
+import type { SharedV4ProviderReference } from '@ai-sdk/provider';
 import { z } from 'zod/v4';
 
 export const shellInputSchema = lazySchema(() =>
@@ -39,7 +40,7 @@ const shellSkillsSchema = z
     z.discriminatedUnion('type', [
       z.object({
         type: z.literal('skillReference'),
-        skillId: z.string(),
+        providerReference: z.record(z.string(), z.string()),
         version: z.string().optional(),
       }),
       z.object({
@@ -125,7 +126,11 @@ type ShellArgs = {
               }>;
             };
         skills?: Array<
-          | { type: 'skillReference'; skillId: string; version?: string }
+          | {
+              type: 'skillReference';
+              providerReference: SharedV4ProviderReference;
+              version?: string;
+            }
           | {
               type: 'inline';
               name: string;

package/src/tool/tool-search.ts

@@ -0,0 +1,98 @@
+import { JSONObject } from '@ai-sdk/provider';
+import {
+  createProviderToolFactoryWithOutputSchema,
+  FlexibleSchema,
+  lazySchema,
+  zodSchema,
+} from '@ai-sdk/provider-utils';
+import { z } from 'zod/v4';
+
+export const toolSearchArgsSchema = lazySchema(() =>
+  zodSchema(
+    z.object({
+      execution: z.enum(['server', 'client']).optional(),
+      description: z.string().optional(),
+      parameters: z.record(z.string(), z.unknown()).optional(),
+    }),
+  ),
+);
+
+export const toolSearchInputSchema = lazySchema(() =>
+  zodSchema(
+    z.object({
+      arguments: z.unknown().optional(),
+      call_id: z.string().nullish(),
+    }),
+  ),
+);
+
+export const toolSearchOutputSchema: FlexibleSchema<{
+  tools: Array<JSONObject>;
+}> = lazySchema(() =>
+  zodSchema(
+    z.object({
+      tools: z.array(z.record(z.string(), z.unknown())),
+    }),
+  ),
+) as FlexibleSchema<{ tools: Array<JSONObject> }>;
+
+const toolSearchToolFactory = createProviderToolFactoryWithOutputSchema<
+  {
+    /**
+     * The arguments from the tool_search_call.
+     * This is preserved for multi-turn conversation reconstruction.
+     */
+    arguments?: unknown;
+
+    /**
+     * The call ID from the tool_search_call.
+     * Present for client-executed tool search; null for hosted.
+     */
+    call_id?: string | null;
+  },
+  {
+    /**
+     * The tools that were loaded by the tool search.
+     * These are the deferred tools that the model requested to load.
+     * Each tool is represented as a JSON object with properties depending on its type.
+     *
+     * Common properties include:
+     * - `type`: The type of the tool (e.g., 'function', 'web_search', etc.)
+     * - `name`: The name of the tool (for function tools)
+     * - `description`: A description of the tool
+     * - `deferLoading`: Whether this tool was deferred (had defer_loading: true)
+     * - `parameters`: The JSON Schema for the function parameters (for function tools)
+     * - `strict`: Whether to enable strict schema adherence (for function tools)
+     */
+    tools: Array<JSONObject>;
+  },
+  {
+    /**
+     * Whether the tool search is executed by the server (hosted) or client.
+     * - `'server'` (default): OpenAI performs the search across deferred tools.
+     * - `'client'`: The model emits a `tool_search_call` and your `execute`
+     *   function performs the lookup, returning the tools to load.
+     */
+    execution?: 'server' | 'client';
+
+    /**
+     * A description of the tool search capability.
+     * Only used for client-executed tool search.
+     */
+    description?: string;
+
+    /**
+     * JSON Schema for the search arguments your application expects.
+     * Only used for client-executed tool search.
+     */
+    parameters?: Record<string, unknown>;
+  }
+>({
+  id: 'openai.tool_search',
+  inputSchema: toolSearchInputSchema,
+  outputSchema: toolSearchOutputSchema,
+});
+
+export const toolSearch = (
+  args: Parameters<typeof toolSearchToolFactory>[0] = {},
+) => toolSearchToolFactory(args);

package/src/transcription/openai-transcription-model.ts

@@ -1,7 +1,7 @@
 import {
-  TranscriptionModelV3,
-  TranscriptionModelV3CallOptions,
-  SharedV3Warning,
+  TranscriptionModelV4,
+  TranscriptionModelV4CallOptions,
+  SharedV4Warning,
 } from '@ai-sdk/provider';
 import {
   combineHeaders,
@@ -10,6 +10,9 @@ import {
   mediaTypeToExtension,
   parseProviderOptions,
   postFormDataToApi,
+  serializeModelOptions,
+  WORKFLOW_DESERIALIZE,
+  WORKFLOW_SERIALIZE,
 } from '@ai-sdk/provider-utils';
 import { OpenAIConfig } from '../openai-config';
 import { openaiFailedResponseHandler } from '../openai-error';
@@ -21,7 +24,7 @@ import {
 } from './openai-transcription-options';
 
 export type OpenAITranscriptionCallOptions = Omit<
-  TranscriptionModelV3CallOptions,
+  TranscriptionModelV4CallOptions,
   'providerOptions'
 > & {
   providerOptions?: {
@@ -96,8 +99,22 @@ const languageMap = {
   welsh: 'cy',
 };
 
-export class OpenAITranscriptionModel implements TranscriptionModelV3 {
-  readonly specificationVersion = 'v3';
+export class OpenAITranscriptionModel implements TranscriptionModelV4 {
+  readonly specificationVersion = 'v4';
+
+  static [WORKFLOW_SERIALIZE](model: OpenAITranscriptionModel) {
+    return serializeModelOptions({
+      modelId: model.modelId,
+      config: model.config,
+    });
+  }
+
+  static [WORKFLOW_DESERIALIZE](options: {
+    modelId: OpenAITranscriptionModelId;
+    config: OpenAITranscriptionModelConfig;
+  }) {
+    return new OpenAITranscriptionModel(options.modelId, options.config);
+  }
 
   get provider(): string {
     return this.config.provider;
@@ -113,7 +130,7 @@ export class OpenAITranscriptionModel implements TranscriptionModelV3 {
     mediaType,
     providerOptions,
   }: OpenAITranscriptionCallOptions) {
-    const warnings: SharedV3Warning[] = [];
+    const warnings: SharedV4Warning[] = [];
 
     // Parse provider options
     const openAIOptions = await parseProviderOptions({
@@ -176,7 +193,7 @@ export class OpenAITranscriptionModel implements TranscriptionModelV3 {
 
   async doGenerate(
     options: OpenAITranscriptionCallOptions,
-  ): Promise<Awaited<ReturnType<TranscriptionModelV3['doGenerate']>>> {
+  ): Promise<Awaited<ReturnType<TranscriptionModelV4['doGenerate']>>> {
     const currentDate = this.config._internal?.currentDate?.() ?? new Date();
     const { formData, warnings } = await this.getArgs(options);
 
@@ -189,7 +206,7 @@ export class OpenAITranscriptionModel implements TranscriptionModelV3 {
         path: '/audio/transcriptions',
         modelId: this.modelId,
       }),
-      headers: combineHeaders(this.config.headers(), options.headers),
+      headers: combineHeaders(this.config.headers?.(), options.headers),
       formData,
       failedResponseHandler: openaiFailedResponseHandler,
       successfulResponseHandler: createJsonResponseHandler(