@ai-sdk/openai 4.0.0-beta.4 → 4.0.0-beta.41

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

@@ -1,18 +1,24 @@
 import {
-  LanguageModelV3CallOptions,
-  SharedV3Warning,
   UnsupportedFunctionalityError,
+  type LanguageModelV4CallOptions,
+  type SharedV4ProviderReference,
+  type SharedV4Warning,
 } from '@ai-sdk/provider';
-import { ToolNameMapping, validateTypes } from '@ai-sdk/provider-utils';
+import {
+  resolveProviderReference,
+  validateTypes,
+  type ToolNameMapping,
+} 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';
+import type { OpenAIResponsesTool } from './openai-responses-api';
 
 export async function prepareResponsesTools({
   tools,
@@ -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

@@ -1,8 +1,8 @@
-import {
+import type {
   openaiResponsesChunkSchema,
   OpenAIResponsesLogprobs,
 } from './openai-responses-api';
-import { InferSchema } from '@ai-sdk/provider-utils';
+import type { InferSchema } from '@ai-sdk/provider-utils';
 
 type OpenaiResponsesChunk = InferSchema<typeof openaiResponsesChunkSchema>;
 
@@ -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,83 @@
+import type { SkillsV4, SharedV4Warning } from '@ai-sdk/provider';
+import {
+  combineHeaders,
+  convertInlineFileDataToUint8Array,
+  createJsonResponseHandler,
+  postFormDataToApi,
+  type FetchFunction,
+} 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 = convertInlineFileDataToUint8Array(file.data);
+      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,26 +1,42 @@
-import { SpeechModelV3, SharedV3Warning } from '@ai-sdk/provider';
+import type { 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 type { OpenAIConfig } from '../openai-config';
 import { openaiFailedResponseHandler } from '../openai-error';
-import { OpenAISpeechAPITypes } from './openai-speech-api';
+import type { OpenAISpeechAPITypes } from './openai-speech-api';
 import {
   openaiSpeechModelOptionsSchema,
-  OpenAISpeechModelId,
+  type OpenAISpeechModelId,
 } from './openai-speech-options';
-
 interface OpenAISpeechModelConfig extends OpenAIConfig {
   _internal?: {
     currentDate?: () => Date;
   };
 }
 
-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 +55,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 +114,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 +128,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/speech/openai-speech-options.ts

@@ -1,4 +1,8 @@
-import { InferSchema, lazySchema, zodSchema } from '@ai-sdk/provider-utils';
+import {
+  lazySchema,
+  zodSchema,
+  type InferSchema,
+} from '@ai-sdk/provider-utils';
 import { z } from 'zod/v4';
 
 export type OpenAISpeechModelId =

package/src/tool/apply-patch.ts

@@ -1,5 +1,5 @@
 import {
-  createProviderToolFactoryWithOutputSchema,
+  createProviderDefinedToolFactoryWithOutputSchema,
   lazySchema,
   zodSchema,
 } from '@ai-sdk/provider-utils';
@@ -98,39 +98,40 @@ export type ApplyPatchOperation =
  * - Returns the status of applying those patches (completed or failed)
  *
  */
-export const applyPatchToolFactory = createProviderToolFactoryWithOutputSchema<
-  {
-    /**
-     * The unique ID of the apply patch tool call generated by the model.
-     */
-    callId: string;
+export const applyPatchToolFactory =
+  createProviderDefinedToolFactoryWithOutputSchema<
+    {
+      /**
+       * The unique ID of the apply patch tool call generated by the model.
+       */
+      callId: string;
 
-    /**
-     * The specific create, delete, or update instruction for the apply_patch tool call.
-     */
-    operation: ApplyPatchOperation;
-  },
-  {
-    /**
-     * The status of the apply patch tool call output.
-     * - 'completed': The patch was applied successfully.
-     * - 'failed': The patch failed to apply.
-     */
-    status: 'completed' | 'failed';
+      /**
+       * The specific create, delete, or update instruction for the apply_patch tool call.
+       */
+      operation: ApplyPatchOperation;
+    },
+    {
+      /**
+       * The status of the apply patch tool call output.
+       * - 'completed': The patch was applied successfully.
+       * - 'failed': The patch failed to apply.
+       */
+      status: 'completed' | 'failed';
 
-    /**
-     * Optional human-readable log text from the apply patch tool
-     * (e.g., patch results or errors).
-     */
-    output?: string;
-  },
-  // No configuration options for apply_patch
-  {}
->({
-  id: 'openai.apply_patch',
-  inputSchema: applyPatchInputSchema,
-  outputSchema: applyPatchOutputSchema,
-});
+      /**
+       * Optional human-readable log text from the apply patch tool
+       * (e.g., patch results or errors).
+       */
+      output?: string;
+    },
+    // No configuration options for apply_patch
+    {}
+  >({
+    id: 'openai.apply_patch',
+    inputSchema: applyPatchInputSchema,
+    outputSchema: applyPatchOutputSchema,
+  });
 
 /**
  * The apply_patch tool lets GPT-5.1 create, update, and delete files in your

package/src/tool/code-interpreter.ts

@@ -1,5 +1,5 @@
 import {
-  createProviderToolFactoryWithOutputSchema,
+  createProviderExecutedToolFactory,
   lazySchema,
   zodSchema,
 } from '@ai-sdk/provider-utils';
@@ -53,49 +53,48 @@ type CodeInterpreterArgs = {
   container?: string | { fileIds?: string[] };
 };
 
-export const codeInterpreterToolFactory =
-  createProviderToolFactoryWithOutputSchema<
-    {
-      /**
-       * The code to run, or null if not available.
-       */
-      code?: string | null;
+export const codeInterpreterToolFactory = createProviderExecutedToolFactory<
+  {
+    /**
+     * The code to run, or null if not available.
+     */
+    code?: string | null;
 
-      /**
-       * The ID of the container used to run the code.
-       */
-      containerId: string;
-    },
-    {
-      /**
-       * The outputs generated by the code interpreter, such as logs or images.
-       * Can be null if no outputs are available.
-       */
-      outputs?: Array<
-        | {
-            type: 'logs';
+    /**
+     * The ID of the container used to run the code.
+     */
+    containerId: string;
+  },
+  {
+    /**
+     * The outputs generated by the code interpreter, such as logs or images.
+     * Can be null if no outputs are available.
+     */
+    outputs?: Array<
+      | {
+          type: 'logs';
 
-            /**
-             * The logs output from the code interpreter.
-             */
-            logs: string;
-          }
-        | {
-            type: 'image';
+          /**
+           * The logs output from the code interpreter.
+           */
+          logs: string;
+        }
+      | {
+          type: 'image';
 
-            /**
-             * The URL of the image output from the code interpreter.
-             */
-            url: string;
-          }
-      > | null;
-    },
-    CodeInterpreterArgs
-  >({
-    id: 'openai.code_interpreter',
-    inputSchema: codeInterpreterInputSchema,
-    outputSchema: codeInterpreterOutputSchema,
-  });
+          /**
+           * The URL of the image output from the code interpreter.
+           */
+          url: string;
+        }
+    > | null;
+  },
+  CodeInterpreterArgs
+>({
+  id: 'openai.code_interpreter',
+  inputSchema: codeInterpreterInputSchema,
+  outputSchema: codeInterpreterOutputSchema,
+});
 
 export const codeInterpreter = (
   args: CodeInterpreterArgs = {}, // default

package/src/tool/custom.ts

@@ -1,5 +1,5 @@
 import {
-  createProviderToolFactory,
+  createProviderDefinedToolFactory,
   lazySchema,
   zodSchema,
 } from '@ai-sdk/provider-utils';
@@ -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([
@@ -28,14 +27,9 @@ export const customArgsSchema = lazySchema(() =>
 
 const customInputSchema = lazySchema(() => zodSchema(z.string()));
 
-export const customToolFactory = createProviderToolFactory<
+export const customToolFactory = createProviderDefinedToolFactory<
   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/file-search.ts

@@ -1,10 +1,10 @@
 import {
-  createProviderToolFactoryWithOutputSchema,
+  createProviderExecutedToolFactory,
   lazySchema,
   zodSchema,
 } from '@ai-sdk/provider-utils';
 import { z } from 'zod/v4';
-import {
+import type {
   OpenAIResponsesFileSearchToolComparisonFilter,
   OpenAIResponsesFileSearchToolCompoundFilter,
 } from '../responses/openai-responses-api';
@@ -59,7 +59,7 @@ export const fileSearchOutputSchema = lazySchema(() =>
   ),
 );
 
-export const fileSearch = createProviderToolFactoryWithOutputSchema<
+export const fileSearch = createProviderExecutedToolFactory<
   {},
   {
     /**

package/src/tool/image-generation.ts

@@ -1,5 +1,5 @@
 import {
-  createProviderToolFactoryWithOutputSchema,
+  createProviderExecutedToolFactory,
   lazySchema,
   zodSchema,
 } from '@ai-sdk/provider-utils';
@@ -104,7 +104,7 @@ type ImageGenerationArgs = {
   size?: 'auto' | '1024x1024' | '1024x1536' | '1536x1024';
 };
 
-const imageGenerationToolFactory = createProviderToolFactoryWithOutputSchema<
+const imageGenerationToolFactory = createProviderExecutedToolFactory<
   {},
   {
     /**

package/src/tool/local-shell.ts

@@ -1,5 +1,5 @@
 import {
-  createProviderToolFactoryWithOutputSchema,
+  createProviderDefinedToolFactoryWithOutputSchema,
   lazySchema,
   zodSchema,
 } from '@ai-sdk/provider-utils';
@@ -24,7 +24,7 @@ export const localShellOutputSchema = lazySchema(() =>
   zodSchema(z.object({ output: z.string() })),
 );
 
-export const localShell = createProviderToolFactoryWithOutputSchema<
+export const localShell = createProviderDefinedToolFactoryWithOutputSchema<
   {
     /**
      * Execute a shell command on the server.

package/src/tool/mcp.ts

@@ -1,9 +1,9 @@
 import {
-  createProviderToolFactoryWithOutputSchema,
+  createProviderExecutedToolFactory,
   lazySchema,
   zodSchema,
 } from '@ai-sdk/provider-utils';
-import { JSONValue } from '@ai-sdk/provider';
+import type { JSONValue } from '@ai-sdk/provider';
 import { z } from 'zod/v4';
 
 const jsonValueSchema: z.ZodType<JSONValue> = z.lazy(() =>
@@ -105,7 +105,7 @@ type McpArgs = {
   serverUrl?: string;
 };
 
-export const mcpToolFactory = createProviderToolFactoryWithOutputSchema<
+export const mcpToolFactory = createProviderExecutedToolFactory<
   {},
   {
     type: 'call';