@ai-sdk/openai 4.0.0-beta.7 → 4.0.0-beta.74

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

@@ -1,27 +1,50 @@
 import {
-  LanguageModelV4CallOptions,
-  SharedV4Warning,
   UnsupportedFunctionalityError,
+  type LanguageModelV4CallOptions,
+  type LanguageModelV4FunctionTool,
+  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 {
+  OpenAIResponsesFunctionTool,
+  OpenAIResponsesTool,
+} from './openai-responses-api';
+
+type OpenAIToolOptions = {
+  deferLoading?: boolean;
+  namespace?: {
+    name: string;
+    description: string;
+  };
+};
 
 export async function prepareResponsesTools({
   tools,
   toolChoice,
+  allowedTools,
   toolNameMapping,
   customProviderToolNames,
 }: {
   tools: LanguageModelV4CallOptions['tools'];
   toolChoice: LanguageModelV4CallOptions['toolChoice'] | undefined;
+  allowedTools?: {
+    toolNames: string[];
+    mode?: 'auto' | 'required';
+  };
   toolNameMapping?: ToolNameMapping;
   customProviderToolNames?: Set<string>;
 }): Promise<{
@@ -38,7 +61,12 @@ export async function prepareResponsesTools({
     | { type: 'code_interpreter' }
     | { type: 'mcp' }
     | { type: 'image_generation' }
-    | { type: 'apply_patch' };
+    | { type: 'apply_patch' }
+    | {
+        type: 'allowed_tools';
+        mode: 'auto' | 'required';
+        tools: Array<{ type: 'function'; name: string }>;
+      };
   toolWarnings: SharedV4Warning[];
 }> {
   // when the tools array is empty, change it to undefined to prevent errors:
@@ -51,20 +79,49 @@ export async function prepareResponsesTools({
   }
 
   const openaiTools: Array<OpenAIResponsesTool> = [];
+  const namespaceTools = new Map<
+    string,
+    Extract<OpenAIResponsesTool, { type: 'namespace' }>
+  >();
   const resolvedCustomProviderToolNames =
     customProviderToolNames ?? new Set<string>();
 
   for (const tool of tools) {
     switch (tool.type) {
-      case 'function':
-        openaiTools.push({
-          type: 'function',
-          name: tool.name,
-          description: tool.description,
-          parameters: tool.inputSchema,
-          ...(tool.strict != null ? { strict: tool.strict } : {}),
+      case 'function': {
+        const openaiOptions = tool.providerOptions?.openai as
+          | OpenAIToolOptions
+          | undefined;
+        const openaiFunctionTool = prepareFunctionTool({
+          tool,
+          options: openaiOptions,
         });
+        const namespace = openaiOptions?.namespace;
+
+        if (namespace == null) {
+          openaiTools.push(openaiFunctionTool);
+        } else {
+          let namespaceTool = namespaceTools.get(namespace.name);
+
+          if (namespaceTool == null) {
+            namespaceTool = {
+              type: 'namespace',
+              name: namespace.name,
+              description: namespace.description,
+              tools: [],
+            };
+            namespaceTools.set(namespace.name, namespaceTool);
+            openaiTools.push(namespaceTool);
+          } else if (namespaceTool.description !== namespace.description) {
+            throw new UnsupportedFunctionalityError({
+              functionality: `conflicting descriptions for OpenAI tool namespace "${namespace.name}"`,
+            });
+          }
+
+          namespaceTool.tools.push(openaiFunctionTool);
+        }
         break;
+      }
       case 'provider': {
         switch (tool.id) {
           case 'openai.file_search': {
@@ -241,11 +298,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;
           }
         }
@@ -260,6 +334,21 @@ export async function prepareResponsesTools({
     }
   }
 
+  if (allowedTools != null) {
+    return {
+      tools: openaiTools,
+      toolChoice: {
+        type: 'allowed_tools',
+        mode: allowedTools.mode ?? 'auto',
+        tools: allowedTools.toolNames.map(name => ({
+          type: 'function',
+          name: toolNameMapping?.toProviderToolName(name) ?? name,
+        })),
+      },
+      toolWarnings,
+    };
+  }
+
   if (toolChoice == null) {
     return { tools: openaiTools, toolChoice: undefined, toolWarnings };
   }
@@ -302,6 +391,25 @@ export async function prepareResponsesTools({
   }
 }
 
+function prepareFunctionTool({
+  tool,
+  options,
+}: {
+  tool: LanguageModelV4FunctionTool;
+  options: OpenAIToolOptions | undefined;
+}): OpenAIResponsesFunctionTool {
+  const deferLoading = options?.deferLoading;
+
+  return {
+    type: 'function',
+    name: tool.name,
+    description: tool.description,
+    parameters: tool.inputSchema,
+    ...(tool.strict != null ? { strict: tool.strict } : {}),
+    ...(deferLoading != null ? { defer_loading: deferLoading } : {}),
+  };
+}
+
 function mapShellEnvironment(environment: {
   type?: string;
   [key: string]: unknown;
@@ -335,7 +443,7 @@ function mapShellEnvironment(environment: {
       };
       skills?: Array<{
         type: string;
-        skillId?: string;
+        providerReference?: SharedV4ProviderReference;
         version?: string;
         name?: string;
         description?: string;
@@ -379,7 +487,7 @@ function mapShellSkills(
   skills:
     | Array<{
         type: string;
-        skillId?: string;
+        providerReference?: SharedV4ProviderReference;
         version?: string;
         name?: string;
         description?: string;
@@ -391,8 +499,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-options.ts → openai-speech-model-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/speech/openai-speech-model.ts

@@ -1,18 +1,20 @@
-import { SpeechModelV4, SharedV4Warning } 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,
-} from './openai-speech-options';
-
+  type OpenAISpeechModelId,
+} from './openai-speech-model-options';
 interface OpenAISpeechModelConfig extends OpenAIConfig {
   _internal?: {
     currentDate?: () => Date;
@@ -22,6 +24,20 @@ interface OpenAISpeechModelConfig extends OpenAIConfig {
 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;
   }
@@ -112,7 +128,7 @@ export class OpenAISpeechModel implements SpeechModelV4 {
         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/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<
   {},
   {
     /**