@ai-sdk/openai 4.0.18 → 4.0.20

package/docs/03-openai.mdx

@@ -457,6 +457,68 @@ metadata on tool-call parts. The SDK uses `providerMetadata.openai.namespace` or
 `providerOptions.openai.namespace` to round-trip the namespace back to OpenAI on
 subsequent requests.
 
+#### Programmatic Tool Calling
+
+OpenAI Programmatic Tool Calling lets supported Responses models generate and run
+hosted JavaScript that coordinates client-side function tools. Add the hosted tool
+with `openai.tools.programmaticToolCalling()`, then opt each eligible function into
+programmatic calls with `allowedCallers`.
+
+```ts
+import { openai, type OpenAIToolOptions } from '@ai-sdk/openai';
+import { generateText, isStepCount, tool } from 'ai';
+import { z } from 'zod';
+
+const result = await generateText({
+  model: openai('gpt-5.6'),
+  stopWhen: isStepCount(10),
+  prompt: 'Compare inventory with demand for sku_123.',
+  tools: {
+    program: openai.tools.programmaticToolCalling(),
+    getInventory: tool({
+      description: 'Get available inventory for a SKU.',
+      inputSchema: z.object({ sku: z.string() }),
+      execute: async ({ sku }) => ({ sku, availableUnits: 42 }),
+      providerOptions: {
+        openai: {
+          allowedCallers: ['programmatic'],
+          outputSchema: {
+            type: 'object',
+            properties: {
+              sku: { type: 'string' },
+              availableUnits: { type: 'number' },
+            },
+            required: ['sku', 'availableUnits'],
+            additionalProperties: false,
+          },
+        } satisfies OpenAIToolOptions,
+      },
+    }),
+  },
+});
+```
+
+`allowedCallers` supports:
+
+- `['direct']` (or omitted): only direct model tool calls
+- `['programmatic']`: only calls from hosted JavaScript
+- `['direct', 'programmatic']`: both invocation modes
+
+Use `outputSchema` to describe the JSON value returned by the function. This schema
+is sent to OpenAI as `output_schema` so generated JavaScript can safely use the
+returned fields. It does not replace the tool's AI SDK output validation or execution
+logic.
+
+The provider preserves program code, replay fingerprints, program outputs, and nested
+function caller metadata across the `generateText` and `streamText` tool loops,
+including stateless requests with `store: false`. Programmatic invocation is
+currently supported for AI SDK function tools; other OpenAI tool types remain
+direct-only through this integration.
+
+Treat generated programs and tool arguments as untrusted. Enforce authorization and
+approval inside every tool, avoid programmatic access to side-effecting tools unless
+the operation is idempotent, and set explicit step limits.
+
 #### Web Search Tool
 
 The OpenAI responses API supports web search through the `openai.tools.webSearch` tool.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ai-sdk/openai",
-  "version": "4.0.18",
+  "version": "4.0.20",
   "type": "module",
   "license": "Apache-2.0",
   "sideEffects": false,

package/src/image/openai-image-model-options.ts

@@ -26,13 +26,7 @@ export const modelMaxImagesPerCall: Record<OpenAIImageModelId, number> = {
   'chatgpt-image-latest': 10,
 };
 
-const defaultResponseFormatPrefixes = [
-  'chatgpt-image-',
-  'gpt-image-1-mini',
-  'gpt-image-1.5',
-  'gpt-image-1',
-  'gpt-image-2',
-];
+const defaultResponseFormatPrefixes = ['chatgpt-image-', 'gpt-image-'];
 
 export function hasDefaultResponseFormat(modelId: string): boolean {
   return defaultResponseFormatPrefixes.some(prefix =>
@@ -40,6 +34,13 @@ export function hasDefaultResponseFormat(modelId: string): boolean {
   );
 }
 
+export function getMaxImagesPerCall(modelId: OpenAIImageModelId): number {
+  return (
+    modelMaxImagesPerCall[modelId] ??
+    (modelId.startsWith('gpt-image-') ? 10 : 1)
+  );
+}
+
 const baseImageModelOptionsObject = z.object({
   /**
    * Quality of the generated image(s).

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

@@ -20,8 +20,8 @@ import type { OpenAIConfig } from '../openai-config';
 import { openaiFailedResponseHandler } from '../openai-error';
 import { openaiImageResponseSchema } from './openai-image-api';
 import {
+  getMaxImagesPerCall,
   hasDefaultResponseFormat,
-  modelMaxImagesPerCall,
   openaiImageModelEditOptions,
   openaiImageModelGenerationOptions,
   type OpenAIImageModelEditOptions,
@@ -51,7 +51,7 @@ export class OpenAIImageModel implements ImageModelV4 {
   }
 
   get maxImagesPerCall(): number {
-    return modelMaxImagesPerCall[this.modelId] ?? 1;
+    return getMaxImagesPerCall(this.modelId);
   }
 
   get provider(): string {

package/src/index.ts

@@ -7,6 +7,7 @@ export type {
   /** @deprecated Use `OpenAILanguageModelResponsesOptions` instead. */
   OpenAILanguageModelResponsesOptions as OpenAIResponsesProviderOptions,
 } from './responses/openai-responses-language-model-options';
+export type { OpenAIToolOptions } from './responses/openai-responses-prepare-tools';
 export type {
   OpenAILanguageModelChatOptions,
   /** @deprecated Use `OpenAILanguageModelChatOptions` instead. */

package/src/internal/index.ts

@@ -16,5 +16,6 @@ export * from '../tool/apply-patch';
 export * from '../tool/code-interpreter';
 export * from '../tool/file-search';
 export * from '../tool/image-generation';
+export * from '../tool/programmatic-tool-calling';
 export * from '../tool/web-search';
 export * from '../tool/web-search-preview';

package/src/openai-language-model-capabilities.ts

@@ -13,37 +13,37 @@ export type OpenAILanguageModelCapabilities = {
 export function getOpenAILanguageModelCapabilities(
   modelId: string,
 ): OpenAILanguageModelCapabilities {
+  const oSeriesVersion = getOSeriesVersion(modelId);
+  const gptVersion = getGptVersion(modelId);
+  const isGptChatModel =
+    gptVersion?.minor == null &&
+    (gptVersion?.variant?.startsWith('chat') ?? false);
+  const isGptNanoModel = gptVersion?.variant?.startsWith('nano') ?? false;
+
   const supportsFlexProcessing =
-    modelId.startsWith('o3') ||
-    modelId.startsWith('o4-mini') ||
-    (modelId.startsWith('gpt-5') && !modelId.startsWith('gpt-5-chat'));
+    (oSeriesVersion != null && oSeriesVersion >= 3) ||
+    (gptVersion != null && gptVersion.major >= 5 && !isGptChatModel);
 
   const supportsPriorityProcessing =
     modelId.startsWith('gpt-4') ||
-    (modelId.startsWith('gpt-5') &&
-      !modelId.startsWith('gpt-5-nano') &&
-      !modelId.startsWith('gpt-5-chat') &&
-      !modelId.startsWith('gpt-5.4-nano')) ||
-    modelId.startsWith('o3') ||
-    modelId.startsWith('o4-mini');
-
-  // Use allowlist approach: only known reasoning models should use 'developer' role
-  // This prevents issues with fine-tuned models, third-party models, and custom models
+    (gptVersion != null &&
+      gptVersion.major >= 5 &&
+      !isGptNanoModel &&
+      !isGptChatModel) ||
+    (oSeriesVersion != null && oSeriesVersion >= 3);
+
+  // Only recognizable OpenAI model families should use the developer role.
+  // Fine-tuned, third-party, and custom model IDs keep conservative defaults.
   const isReasoningModel =
-    modelId.startsWith('o1') ||
-    modelId.startsWith('o3') ||
-    modelId.startsWith('o4-mini') ||
-    (modelId.startsWith('gpt-5') && !modelId.startsWith('gpt-5-chat'));
+    oSeriesVersion != null ||
+    (gptVersion != null && gptVersion.major >= 5 && !isGptChatModel);
 
   // https://platform.openai.com/docs/guides/latest-model#gpt-5-1-parameter-compatibility
   // GPT-5.1 and later model families support temperature, topP, logProbs when reasoningEffort is none.
   const supportsNonReasoningParameters =
-    modelId.startsWith('gpt-5.1') ||
-    modelId.startsWith('gpt-5.2') ||
-    modelId.startsWith('gpt-5.3') ||
-    modelId.startsWith('gpt-5.4') ||
-    modelId.startsWith('gpt-5.5') ||
-    modelId.startsWith('gpt-5.6');
+    gptVersion != null &&
+    (gptVersion.major > 5 ||
+      (gptVersion.major === 5 && (gptVersion.minor ?? 0) >= 1));
 
   const systemMessageMode = isReasoningModel ? 'developer' : 'system';
 
@@ -55,3 +55,28 @@ export function getOpenAILanguageModelCapabilities(
     supportsNonReasoningParameters,
   };
 }
+
+function getOSeriesVersion(modelId: string): number | undefined {
+  const match = /^o(\d+)(?:-|$)/.exec(modelId);
+  return match == null ? undefined : Number(match[1]);
+}
+
+function getGptVersion(modelId: string):
+  | {
+      major: number;
+      minor: number | undefined;
+      variant: string | undefined;
+    }
+  | undefined {
+  const match = /^gpt-(\d+)(?:\.(\d+))?(?:-(.+))?$/.exec(modelId);
+
+  if (match == null) {
+    return undefined;
+  }
+
+  return {
+    major: Number(match[1]),
+    minor: match[2] == null ? undefined : Number(match[2]),
+    variant: match[3],
+  };
+}

package/src/openai-tools.ts

@@ -10,6 +10,7 @@ import { toolSearch } from './tool/tool-search';
 import { webSearch } from './tool/web-search';
 import { webSearchPreview } from './tool/web-search-preview';
 import { mcp } from './tool/mcp';
+import { programmaticToolCalling } from './tool/programmatic-tool-calling';
 
 export const openaiTools = {
   /**
@@ -135,6 +136,12 @@ export const openaiTools = {
    */
   mcp,
 
+  /**
+   * Programmatic Tool Calling lets OpenAI Responses models write and execute
+   * JavaScript that orchestrates eligible tools.
+   */
+  programmaticToolCalling,
+
   /**
    * Tool search allows the model to dynamically search for and load deferred
    * tools into the model's context as needed. This helps reduce overall token

package/src/responses/convert-to-openai-responses-input.ts

@@ -33,16 +33,34 @@ import type {
   OpenAIResponsesFunctionCallOutput,
   OpenAIResponsesInput,
   OpenAIResponsesReasoning,
+  OpenAIResponsesToolCaller,
 } from './openai-responses-api';
 import {
   toolSearchInputSchema,
   toolSearchOutputSchema,
 } from '../tool/tool-search';
+import {
+  programmaticToolCallingInputSchema,
+  programmaticToolCallingOutputSchema,
+} from '../tool/programmatic-tool-calling';
 
 function serializeToolCallArguments(input: unknown): string {
   return JSON.stringify(input === undefined ? {} : input);
 }
 
+function mapToolCaller(
+  caller:
+    | { type: 'direct' }
+    | { type: 'program'; callerId: string }
+    | undefined,
+): OpenAIResponsesToolCaller | undefined {
+  return caller == null
+    ? undefined
+    : caller.type === 'program'
+      ? { type: 'program', caller_id: caller.callerId }
+      : caller;
+}
+
 type OpenAIPromptCacheBreakpoint = { mode: 'explicit' };
 
 function getPromptCacheBreakpoint(
@@ -350,6 +368,11 @@ export async function convertToOpenAIResponsesInput({
                 ).providerMetadata?.[providerOptionsName]?.namespace) as
                 | string
                 | undefined;
+              const caller = part.providerOptions?.[providerOptionsName]
+                ?.caller as
+                | { type: 'direct' }
+                | { type: 'program'; callerId: string }
+                | undefined;
 
               if (hasConversation && id != null) {
                 break;
@@ -390,6 +413,27 @@ export async function convertToOpenAIResponsesInput({
                 break;
               }
 
+              if (resolvedToolName === 'programmatic_tool_calling') {
+                if (store && id != null) {
+                  input.push({ type: 'item_reference', id });
+                  break;
+                }
+
+                const parsedInput = await validateTypes({
+                  value: part.input,
+                  schema: programmaticToolCallingInputSchema,
+                });
+
+                input.push({
+                  type: 'program',
+                  id: id ?? part.toolCallId,
+                  call_id: part.toolCallId,
+                  code: parsedInput.code,
+                  fingerprint: parsedInput.fingerprint,
+                });
+                break;
+              }
+
               if (part.providerExecuted) {
                 if (store && id != null) {
                   input.push({ type: 'item_reference', id });
@@ -552,6 +596,9 @@ export async function convertToOpenAIResponsesInput({
                 name: resolvedToolName,
                 arguments: serializeToolCallArguments(part.input),
                 ...(namespace != null && { namespace }),
+                ...(caller != null && {
+                  caller: mapToolCaller(caller),
+                }),
               });
               break;
             }
@@ -613,6 +660,37 @@ export async function convertToOpenAIResponsesInput({
                 break;
               }
 
+              if (resolvedResultToolName === 'programmatic_tool_calling') {
+                const itemId = (part.providerOptions?.[providerOptionsName]
+                  ?.itemId ??
+                  (
+                    part as {
+                      providerMetadata?: {
+                        [providerOptionsName]?: { itemId?: string };
+                      };
+                    }
+                  ).providerMetadata?.[providerOptionsName]?.itemId ??
+                  part.toolCallId) as string;
+
+                if (store) {
+                  input.push({ type: 'item_reference', id: itemId });
+                } else if (part.output.type === 'json') {
+                  const parsedOutput = await validateTypes({
+                    value: part.output.value,
+                    schema: programmaticToolCallingOutputSchema,
+                  });
+
+                  input.push({
+                    type: 'program_output',
+                    id: itemId,
+                    call_id: part.toolCallId,
+                    result: parsedOutput.result,
+                    status: parsedOutput.status,
+                  });
+                }
+                break;
+              }
+
               /*
                * Shell tool results are separate output items (shell_call_output)
                * with their own item IDs distinct from the shell_call's item ID.
@@ -1163,10 +1241,18 @@ export async function convertToOpenAIResponsesInput({
               break;
           }
 
+          const caller = mapToolCaller(
+            part.providerOptions?.[providerOptionsName]?.caller as
+              | { type: 'direct' }
+              | { type: 'program'; callerId: string }
+              | undefined,
+          );
+
           input.push({
             type: 'function_call_output',
             call_id: part.toolCallId,
             output: contentValue,
+            ...(caller != null && { caller }),
           });
         }
 

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

@@ -84,6 +84,30 @@ const openaiResponsesComputerCallSchema = z.object({
     .nullish(),
 });
 
+const openaiResponsesToolCallerSchema = z.discriminatedUnion('type', [
+  z.object({ type: z.literal('direct') }),
+  z.object({
+    type: z.literal('program'),
+    caller_id: z.string(),
+  }),
+]);
+
+const openaiResponsesProgramSchema = z.object({
+  type: z.literal('program'),
+  id: z.string(),
+  call_id: z.string(),
+  code: z.string(),
+  fingerprint: z.string(),
+});
+
+const openaiResponsesProgramOutputSchema = z.object({
+  type: z.literal('program_output'),
+  id: z.string(),
+  call_id: z.string(),
+  result: z.string(),
+  status: z.enum(['completed', 'incomplete']),
+});
+
 export type OpenAIResponsesInput = Array<OpenAIResponsesInputItem>;
 
 export type OpenAIResponsesInputItem =
@@ -92,6 +116,8 @@ export type OpenAIResponsesInputItem =
   | OpenAIResponsesAssistantMessage
   | OpenAIResponsesFunctionCall
   | OpenAIResponsesFunctionCallOutput
+  | OpenAIResponsesProgram
+  | OpenAIResponsesProgramOutput
   | OpenAIResponsesCustomToolCall
   | OpenAIResponsesCustomToolCallOutput
   | OpenAIResponsesMcpApprovalResponse
@@ -201,6 +227,7 @@ export type OpenAIResponsesFunctionCall = {
   arguments: string;
   id?: string;
   namespace?: string;
+  caller?: OpenAIResponsesToolCaller;
 };
 
 export type OpenAIResponsesFunctionCallOutput = {
@@ -231,6 +258,27 @@ export type OpenAIResponsesFunctionCallOutput = {
             prompt_cache_breakpoint?: { mode: 'explicit' };
           }
       >;
+  caller?: OpenAIResponsesToolCaller;
+};
+
+export type OpenAIResponsesToolCaller =
+  | { type: 'direct' }
+  | { type: 'program'; caller_id: string };
+
+export type OpenAIResponsesProgram = {
+  type: 'program';
+  id: string;
+  call_id: string;
+  code: string;
+  fingerprint: string;
+};
+
+export type OpenAIResponsesProgramOutput = {
+  type: 'program_output';
+  id: string;
+  call_id: string;
+  result: string;
+  status: 'completed' | 'incomplete';
 };
 
 export type OpenAIResponsesCustomToolCall = {
@@ -428,6 +476,8 @@ export type OpenAIResponsesFunctionTool = {
   parameters: JSONSchema7;
   strict?: boolean;
   defer_loading?: boolean;
+  allowed_callers?: Array<'direct' | 'programmatic'>;
+  output_schema?: JSONSchema7;
 };
 
 export type OpenAIResponsesTool =
@@ -604,6 +654,9 @@ export type OpenAIResponsesTool =
       execution?: 'server' | 'client';
       description?: string;
       parameters?: Record<string, unknown>;
+    }
+  | {
+      type: 'programmatic_tool_calling';
     };
 
 export type OpenAIResponsesReasoning = {
@@ -761,7 +814,10 @@ export const openaiResponsesChunkSchema = lazySchema(() =>
             name: z.string(),
             arguments: z.string(),
             namespace: z.string().nullish(),
+            caller: openaiResponsesToolCallerSchema.nullish(),
           }),
+          openaiResponsesProgramSchema,
+          openaiResponsesProgramOutputSchema,
           z.object({
             type: z.literal('web_search_call'),
             id: z.string(),
@@ -905,9 +961,12 @@ export const openaiResponsesChunkSchema = lazySchema(() =>
             call_id: z.string(),
             name: z.string(),
             arguments: z.string(),
-            status: z.literal('completed'),
+            status: z.enum(['in_progress', 'completed', 'incomplete']),
             namespace: z.string().nullish(),
+            caller: openaiResponsesToolCallerSchema.nullish(),
           }),
+          openaiResponsesProgramSchema,
+          openaiResponsesProgramOutputSchema,
           z.object({
             type: z.literal('custom_tool_call'),
             id: z.string(),
@@ -1413,7 +1472,10 @@ export const openaiResponsesResponseSchema = lazySchema(() =>
               arguments: z.string(),
               id: z.string(),
               namespace: z.string().nullish(),
+              caller: openaiResponsesToolCallerSchema.nullish(),
             }),
+            openaiResponsesProgramSchema,
+            openaiResponsesProgramOutputSchema,
             z.object({
               type: z.literal('custom_tool_call'),
               call_id: z.string(),

package/src/responses/openai-responses-language-model.ts

@@ -48,6 +48,10 @@ import type {
   toolSearchInputSchema,
   toolSearchOutputSchema,
 } from '../tool/tool-search';
+import type {
+  programmaticToolCallingInputSchema,
+  programmaticToolCallingOutputSchema,
+} from '../tool/programmatic-tool-calling';
 import type { webSearchOutputSchema } from '../tool/web-search';
 import {
   convertOpenAIResponsesUsage,
@@ -313,6 +317,7 @@ export class OpenAIResponsesLanguageModel implements LanguageModelV4 {
         'openai.mcp': 'mcp',
         'openai.apply_patch': 'apply_patch',
         'openai.tool_search': 'tool_search',
+        'openai.programmatic_tool_calling': 'programmatic_tool_calling',
       },
     });
 
@@ -940,6 +945,56 @@ export class OpenAIResponsesLanguageModel implements LanguageModelV4 {
               [providerOptionsName]: {
                 itemId: part.id,
                 ...(part.namespace != null && { namespace: part.namespace }),
+                ...(part.caller != null && {
+                  caller:
+                    part.caller.type === 'program'
+                      ? {
+                          type: 'program',
+                          callerId: part.caller.caller_id,
+                        }
+                      : part.caller,
+                }),
+              },
+            },
+          });
+          break;
+        }
+
+        case 'program': {
+          content.push({
+            type: 'tool-call',
+            toolCallId: part.call_id,
+            toolName: toolNameMapping.toCustomToolName(
+              'programmatic_tool_calling',
+            ),
+            input: JSON.stringify({
+              code: part.code,
+              fingerprint: part.fingerprint,
+            } satisfies InferSchema<typeof programmaticToolCallingInputSchema>),
+            providerExecuted: true,
+            providerMetadata: {
+              [providerOptionsName]: {
+                itemId: part.id,
+              },
+            },
+          });
+          break;
+        }
+
+        case 'program_output': {
+          content.push({
+            type: 'tool-result',
+            toolCallId: part.call_id,
+            toolName: toolNameMapping.toCustomToolName(
+              'programmatic_tool_calling',
+            ),
+            result: {
+              result: part.result,
+              status: part.status,
+            } satisfies InferSchema<typeof programmaticToolCallingOutputSchema>,
+            providerMetadata: {
+              [providerOptionsName]: {
+                itemId: part.id,
               },
             },
           });
@@ -1631,6 +1686,54 @@ export class OpenAIResponsesLanguageModel implements LanguageModelV4 {
                       ...(value.item.namespace != null && {
                         namespace: value.item.namespace,
                       }),
+                      ...(value.item.caller != null && {
+                        caller:
+                          value.item.caller.type === 'program'
+                            ? {
+                                type: 'program',
+                                callerId: value.item.caller.caller_id,
+                              }
+                            : value.item.caller,
+                      }),
+                    },
+                  },
+                });
+              } else if (value.item.type === 'program') {
+                controller.enqueue({
+                  type: 'tool-call',
+                  toolCallId: value.item.call_id,
+                  toolName: toolNameMapping.toCustomToolName(
+                    'programmatic_tool_calling',
+                  ),
+                  input: JSON.stringify({
+                    code: value.item.code,
+                    fingerprint: value.item.fingerprint,
+                  } satisfies InferSchema<
+                    typeof programmaticToolCallingInputSchema
+                  >),
+                  providerExecuted: true,
+                  providerMetadata: {
+                    [providerOptionsName]: {
+                      itemId: value.item.id,
+                    },
+                  },
+                });
+              } else if (value.item.type === 'program_output') {
+                controller.enqueue({
+                  type: 'tool-result',
+                  toolCallId: value.item.call_id,
+                  toolName: toolNameMapping.toCustomToolName(
+                    'programmatic_tool_calling',
+                  ),
+                  result: {
+                    result: value.item.result,
+                    status: value.item.status,
+                  } satisfies InferSchema<
+                    typeof programmaticToolCallingOutputSchema
+                  >,
+                  providerMetadata: {
+                    [providerOptionsName]: {
+                      itemId: value.item.id,
                     },
                   },
                 });