@ai-sdk/openai 4.0.9 → 4.0.11

package/src/chat/openai-chat-language-model-options.ts

@@ -66,6 +66,10 @@ export type OpenAIChatModelId =
   | 'gpt-5.4-pro-2026-03-05'
   | 'gpt-5.5'
   | 'gpt-5.5-2026-04-23'
+  | 'gpt-5.6'
+  | 'gpt-5.6-luna'
+  | 'gpt-5.6-sol'
+  | 'gpt-5.6-terra'
   | (string & {});
 
 export const openaiLanguageModelChatOptions = lazySchema(() =>
@@ -105,7 +109,7 @@ export const openaiLanguageModelChatOptions = lazySchema(() =>
        * Reasoning effort for reasoning models. Defaults to `medium`.
        */
       reasoningEffort: z
-        .enum(['none', 'minimal', 'low', 'medium', 'high', 'xhigh'])
+        .enum(['none', 'minimal', 'low', 'medium', 'high', 'xhigh', 'max'])
         .optional(),
 
       /**
@@ -159,11 +163,25 @@ export const openaiLanguageModelChatOptions = lazySchema(() =>
        */
       promptCacheKey: z.string().optional(),
 
+      /**
+       * Prompt cache behavior for GPT-5.6 and later models.
+       * `mode` controls whether OpenAI also places an implicit breakpoint.
+       * `ttl` sets the minimum cache lifetime and currently only supports 30 minutes.
+       */
+      promptCacheOptions: z
+        .object({
+          mode: z.enum(['implicit', 'explicit']).optional(),
+          ttl: z.literal('30m').optional(),
+        })
+        .optional(),
+
       /**
        * The retention policy for the prompt cache.
        * - 'in_memory': Default. Standard prompt caching behavior.
        * - '24h': Extended prompt caching that keeps cached prefixes active for up to 24 hours.
-       *          Currently only available for 5.1 series models.
+       *          Available for models before GPT-5.6 that support extended caching.
+       *
+       * @deprecated For GPT-5.6 and later models, use `promptCacheOptions.ttl`.
        *
        * @default 'in_memory'
        */

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

@@ -196,6 +196,7 @@ export class OpenAIChatLanguageModel implements LanguageModelV4 {
       reasoning_effort: resolvedReasoningEffort,
       service_tier: openaiOptions.serviceTier,
       prompt_cache_key: openaiOptions.promptCacheKey,
+      prompt_cache_options: openaiOptions.promptCacheOptions,
       prompt_cache_retention: openaiOptions.promptCacheRetention,
       safety_identifier: openaiOptions.safetyIdentifier,
 

package/src/chat/openai-chat-prompt.ts

@@ -9,12 +9,12 @@ export type ChatCompletionMessage =
 
 export interface ChatCompletionSystemMessage {
   role: 'system';
-  content: string;
+  content: string | Array<ChatCompletionContentPartText>;
 }
 
 export interface ChatCompletionDeveloperMessage {
   role: 'developer';
-  content: string;
+  content: string | Array<ChatCompletionContentPartText>;
 }
 
 export interface ChatCompletionUserMessage {
@@ -31,26 +31,30 @@ export type ChatCompletionContentPart =
 export interface ChatCompletionContentPartText {
   type: 'text';
   text: string;
+  prompt_cache_breakpoint?: { mode: 'explicit' };
 }
 
 export interface ChatCompletionContentPartImage {
   type: 'image_url';
   image_url: { url: string };
+  prompt_cache_breakpoint?: { mode: 'explicit' };
 }
 
 export interface ChatCompletionContentPartInputAudio {
   type: 'input_audio';
   input_audio: { data: string; format: 'wav' | 'mp3' };
+  prompt_cache_breakpoint?: { mode: 'explicit' };
 }
 
 export interface ChatCompletionContentPartFile {
   type: 'file';
   file: { filename: string; file_data: string } | { file_id: string };
+  prompt_cache_breakpoint?: { mode: 'explicit' };
 }
 
 export interface ChatCompletionAssistantMessage {
   role: 'assistant';
-  content?: string | null;
+  content?: string | null | Array<ChatCompletionContentPartText>;
   tool_calls?: Array<ChatCompletionMessageToolCall>;
 }
 
@@ -65,6 +69,6 @@ export interface ChatCompletionMessageToolCall {
 
 export interface ChatCompletionToolMessage {
   role: 'tool';
-  content: string;
+  content: string | Array<ChatCompletionContentPartText>;
   tool_call_id: string;
 }

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

@@ -42,7 +42,8 @@ export function getOpenAILanguageModelCapabilities(
     modelId.startsWith('gpt-5.2') ||
     modelId.startsWith('gpt-5.3') ||
     modelId.startsWith('gpt-5.4') ||
-    modelId.startsWith('gpt-5.5');
+    modelId.startsWith('gpt-5.5') ||
+    modelId.startsWith('gpt-5.6');
 
   const systemMessageMode = isReasoningModel ? 'developer' : 'system';
 

package/src/responses/convert-openai-responses-usage.ts

@@ -5,6 +5,7 @@ export type OpenAIResponsesUsage = {
   output_tokens: number;
   input_tokens_details?: {
     cached_tokens?: number | null;
+    cache_write_tokens?: number | null;
     orchestration_input_tokens?: number | null;
     orchestration_input_cached_tokens?: number | null;
   } | null;
@@ -37,14 +38,16 @@ export function convertOpenAIResponsesUsage(
   const inputTokens = usage.input_tokens;
   const outputTokens = usage.output_tokens;
   const cachedTokens = usage.input_tokens_details?.cached_tokens ?? 0;
+  const cacheWriteTokens =
+    usage.input_tokens_details?.cache_write_tokens ?? undefined;
   const reasoningTokens = usage.output_tokens_details?.reasoning_tokens ?? 0;
 
   return {
     inputTokens: {
       total: inputTokens,
-      noCache: inputTokens - cachedTokens,
+      noCache: inputTokens - cachedTokens - (cacheWriteTokens ?? 0),
       cacheRead: cachedTokens,
-      cacheWrite: undefined,
+      cacheWrite: cacheWriteTokens,
     },
     outputTokens: {
       total: outputTokens,

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

@@ -1,6 +1,7 @@
 import {
   UnsupportedFunctionalityError,
   type LanguageModelV4Prompt,
+  type SharedV4ProviderOptions,
   type LanguageModelV4ToolApprovalResponsePart,
   type SharedV4Warning,
 } from '@ai-sdk/provider';
@@ -41,6 +42,17 @@ function serializeToolCallArguments(input: unknown): string {
   return JSON.stringify(input === undefined ? {} : input);
 }
 
+type OpenAIPromptCacheBreakpoint = { mode: 'explicit' };
+
+function getPromptCacheBreakpoint(
+  providerOptions: SharedV4ProviderOptions | undefined,
+  providerOptionsName: string,
+): OpenAIPromptCacheBreakpoint | undefined {
+  return providerOptions?.[providerOptionsName]?.promptCacheBreakpoint as
+    | OpenAIPromptCacheBreakpoint
+    | undefined;
+}
+
 /**
  * This is soft-deprecated. Use provider references instead. Kept for backward compatibility
  * with the `fileIdPrefixes` option.
@@ -89,16 +101,48 @@ export async function convertToOpenAIResponsesInput({
   const warnings: Array<SharedV4Warning> = [];
   const processedApprovalIds = new Set<string>();
 
-  for (const { role, content } of prompt) {
+  for (const { role, content, providerOptions } of prompt) {
     switch (role) {
       case 'system': {
         switch (systemMessageMode) {
           case 'system': {
-            input.push({ role: 'system', content });
+            const promptCacheBreakpoint = getPromptCacheBreakpoint(
+              providerOptions,
+              providerOptionsName,
+            );
+            input.push({
+              role: 'system',
+              content:
+                promptCacheBreakpoint == null
+                  ? content
+                  : [
+                      {
+                        type: 'input_text',
+                        text: content,
+                        prompt_cache_breakpoint: promptCacheBreakpoint,
+                      },
+                    ],
+            });
             break;
           }
           case 'developer': {
-            input.push({ role: 'developer', content });
+            const promptCacheBreakpoint = getPromptCacheBreakpoint(
+              providerOptions,
+              providerOptionsName,
+            );
+            input.push({
+              role: 'developer',
+              content:
+                promptCacheBreakpoint == null
+                  ? content
+                  : [
+                      {
+                        type: 'input_text',
+                        text: content,
+                        prompt_cache_breakpoint: promptCacheBreakpoint,
+                      },
+                    ],
+            });
             break;
           }
           case 'remove': {
@@ -124,9 +168,23 @@ export async function convertToOpenAIResponsesInput({
           content: content.map((part, index) => {
             switch (part.type) {
               case 'text': {
-                return { type: 'input_text', text: part.text };
+                const promptCacheBreakpoint = getPromptCacheBreakpoint(
+                  part.providerOptions,
+                  providerOptionsName,
+                );
+                return {
+                  type: 'input_text',
+                  text: part.text,
+                  ...(promptCacheBreakpoint != null && {
+                    prompt_cache_breakpoint: promptCacheBreakpoint,
+                  }),
+                };
               }
               case 'file': {
+                const promptCacheBreakpoint = getPromptCacheBreakpoint(
+                  part.providerOptions,
+                  providerOptionsName,
+                );
                 switch (part.data.type) {
                   case 'reference': {
                     const fileId = resolveProviderReference({
@@ -141,12 +199,18 @@ export async function convertToOpenAIResponsesInput({
                         detail:
                           part.providerOptions?.[providerOptionsName]
                             ?.imageDetail,
+                        ...(promptCacheBreakpoint != null && {
+                          prompt_cache_breakpoint: promptCacheBreakpoint,
+                        }),
                       };
                     }
 
                     return {
                       type: 'input_file',
                       file_id: fileId,
+                      ...(promptCacheBreakpoint != null && {
+                        prompt_cache_breakpoint: promptCacheBreakpoint,
+                      }),
                     };
                   }
                   case 'text': {
@@ -172,12 +236,18 @@ export async function convertToOpenAIResponsesInput({
                         detail:
                           part.providerOptions?.[providerOptionsName]
                             ?.imageDetail,
+                        ...(promptCacheBreakpoint != null && {
+                          prompt_cache_breakpoint: promptCacheBreakpoint,
+                        }),
                       };
                     } else {
                       if (part.data.type === 'url') {
                         return {
                           type: 'input_file',
                           file_url: part.data.url.toString(),
+                          ...(promptCacheBreakpoint != null && {
+                            prompt_cache_breakpoint: promptCacheBreakpoint,
+                          }),
                         };
                       }
 
@@ -204,6 +274,9 @@ export async function convertToOpenAIResponsesInput({
                                   : `part-${index}`),
                               file_data: `data:${fullMediaType};base64,${convertToBase64(part.data.data)}`,
                             }),
+                        ...(promptCacheBreakpoint != null && {
+                          prompt_cache_breakpoint: promptCacheBreakpoint,
+                        }),
                       };
                     }
                   }
@@ -813,9 +886,19 @@ export async function convertToOpenAIResponsesInput({
               case 'content':
                 outputValue = output.value
                   .map(item => {
+                    const promptCacheBreakpoint = getPromptCacheBreakpoint(
+                      item.providerOptions,
+                      providerOptionsName,
+                    );
                     switch (item.type) {
                       case 'text':
-                        return { type: 'input_text' as const, text: item.text };
+                        return {
+                          type: 'input_text' as const,
+                          text: item.text,
+                          ...(promptCacheBreakpoint != null && {
+                            prompt_cache_breakpoint: promptCacheBreakpoint,
+                          }),
+                        };
                       case 'file': {
                         const topLevel = getTopLevelMediaType(item.mediaType);
                         const imageDetail =
@@ -831,12 +914,18 @@ export async function convertToOpenAIResponsesInput({
                               type: 'input_image' as const,
                               image_url: `data:${fullMediaType};base64,${convertToBase64(item.data.data)}`,
                               detail: imageDetail,
+                              ...(promptCacheBreakpoint != null && {
+                                prompt_cache_breakpoint: promptCacheBreakpoint,
+                              }),
                             };
                           }
                           return {
                             type: 'input_file' as const,
                             filename: item.filename ?? 'data',
                             file_data: `data:${fullMediaType};base64,${convertToBase64(item.data.data)}`,
+                            ...(promptCacheBreakpoint != null && {
+                              prompt_cache_breakpoint: promptCacheBreakpoint,
+                            }),
                           };
                         }
 
@@ -846,11 +935,17 @@ export async function convertToOpenAIResponsesInput({
                               type: 'input_image' as const,
                               image_url: item.data.url.toString(),
                               detail: imageDetail,
+                              ...(promptCacheBreakpoint != null && {
+                                prompt_cache_breakpoint: promptCacheBreakpoint,
+                              }),
                             };
                           }
                           return {
                             type: 'input_file' as const,
                             file_url: item.data.url.toString(),
+                            ...(promptCacheBreakpoint != null && {
+                              prompt_cache_breakpoint: promptCacheBreakpoint,
+                            }),
                           };
                         }
 
@@ -897,9 +992,19 @@ export async function convertToOpenAIResponsesInput({
             case 'content':
               contentValue = output.value
                 .map(item => {
+                  const promptCacheBreakpoint = getPromptCacheBreakpoint(
+                    item.providerOptions,
+                    providerOptionsName,
+                  );
                   switch (item.type) {
                     case 'text': {
-                      return { type: 'input_text' as const, text: item.text };
+                      return {
+                        type: 'input_text' as const,
+                        text: item.text,
+                        ...(promptCacheBreakpoint != null && {
+                          prompt_cache_breakpoint: promptCacheBreakpoint,
+                        }),
+                      };
                     }
 
                     case 'file': {
@@ -917,12 +1022,18 @@ export async function convertToOpenAIResponsesInput({
                             type: 'input_image' as const,
                             image_url: `data:${fullMediaType};base64,${convertToBase64(item.data.data)}`,
                             detail: imageDetail,
+                            ...(promptCacheBreakpoint != null && {
+                              prompt_cache_breakpoint: promptCacheBreakpoint,
+                            }),
                           };
                         }
                         return {
                           type: 'input_file' as const,
                           filename: item.filename ?? 'data',
                           file_data: `data:${fullMediaType};base64,${convertToBase64(item.data.data)}`,
+                          ...(promptCacheBreakpoint != null && {
+                            prompt_cache_breakpoint: promptCacheBreakpoint,
+                          }),
                         };
                       }
 
@@ -932,11 +1043,17 @@ export async function convertToOpenAIResponsesInput({
                             type: 'input_image' as const,
                             image_url: item.data.url.toString(),
                             detail: imageDetail,
+                            ...(promptCacheBreakpoint != null && {
+                              prompt_cache_breakpoint: promptCacheBreakpoint,
+                            }),
                           };
                         }
                         return {
                           type: 'input_file' as const,
                           file_url: item.data.url.toString(),
+                          ...(promptCacheBreakpoint != null && {
+                            prompt_cache_breakpoint: promptCacheBreakpoint,
+                          }),
                         };
                       }
 

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

@@ -73,18 +73,49 @@ export type OpenAIResponsesApplyPatchOperationDiffDoneChunk = {
 
 export type OpenAIResponsesSystemMessage = {
   role: 'system' | 'developer';
-  content: string;
+  content:
+    | string
+    | Array<{
+        type: 'input_text';
+        text: string;
+        prompt_cache_breakpoint?: { mode: 'explicit' };
+      }>;
 };
 
 export type OpenAIResponsesUserMessage = {
   role: 'user';
   content: Array<
-    | { type: 'input_text'; text: string }
-    | { type: 'input_image'; image_url: string }
-    | { type: 'input_image'; file_id: string }
-    | { type: 'input_file'; file_url: string }
-    | { type: 'input_file'; filename: string; file_data: string }
-    | { type: 'input_file'; file_id: string }
+    | {
+        type: 'input_text';
+        text: string;
+        prompt_cache_breakpoint?: { mode: 'explicit' };
+      }
+    | {
+        type: 'input_image';
+        image_url: string;
+        prompt_cache_breakpoint?: { mode: 'explicit' };
+      }
+    | {
+        type: 'input_image';
+        file_id: string;
+        prompt_cache_breakpoint?: { mode: 'explicit' };
+      }
+    | {
+        type: 'input_file';
+        file_url: string;
+        prompt_cache_breakpoint?: { mode: 'explicit' };
+      }
+    | {
+        type: 'input_file';
+        filename: string;
+        file_data: string;
+        prompt_cache_breakpoint?: { mode: 'explicit' };
+      }
+    | {
+        type: 'input_file';
+        file_id: string;
+        prompt_cache_breakpoint?: { mode: 'explicit' };
+      }
   >;
 };
 
@@ -110,10 +141,27 @@ export type OpenAIResponsesFunctionCallOutput = {
   output:
     | string
     | Array<
-        | { type: 'input_text'; text: string }
-        | { type: 'input_image'; image_url: string }
-        | { type: 'input_file'; filename: string; file_data: string }
-        | { type: 'input_file'; file_url: string }
+        | {
+            type: 'input_text';
+            text: string;
+            prompt_cache_breakpoint?: { mode: 'explicit' };
+          }
+        | {
+            type: 'input_image';
+            image_url: string;
+            prompt_cache_breakpoint?: { mode: 'explicit' };
+          }
+        | {
+            type: 'input_file';
+            filename: string;
+            file_data: string;
+            prompt_cache_breakpoint?: { mode: 'explicit' };
+          }
+        | {
+            type: 'input_file';
+            file_url: string;
+            prompt_cache_breakpoint?: { mode: 'explicit' };
+          }
       >;
 };
 
@@ -534,6 +582,7 @@ export const openaiResponsesChunkSchema = lazySchema(() =>
             input_tokens_details: z
               .object({
                 cached_tokens: z.number().nullish(),
+                cache_write_tokens: z.number().nullish(),
                 orchestration_input_tokens: z.number().nullish(),
                 orchestration_input_cached_tokens: z.number().nullish(),
               })
@@ -546,6 +595,11 @@ export const openaiResponsesChunkSchema = lazySchema(() =>
               })
               .nullish(),
           }),
+          reasoning: z
+            .object({
+              context: z.string().nullish(),
+            })
+            .nullish(),
           service_tier: z.string().nullish(),
         }),
       }),
@@ -566,6 +620,7 @@ export const openaiResponsesChunkSchema = lazySchema(() =>
               input_tokens_details: z
                 .object({
                   cached_tokens: z.number().nullish(),
+                  cache_write_tokens: z.number().nullish(),
                   orchestration_input_tokens: z.number().nullish(),
                   orchestration_input_cached_tokens: z.number().nullish(),
                 })
@@ -579,6 +634,11 @@ export const openaiResponsesChunkSchema = lazySchema(() =>
                 .nullish(),
             })
             .nullish(),
+          reasoning: z
+            .object({
+              context: z.string().nullish(),
+            })
+            .nullish(),
           service_tier: z.string().nullish(),
         }),
       }),
@@ -1426,6 +1486,11 @@ export const openaiResponsesResponseSchema = lazySchema(() =>
         )
         .optional(),
       service_tier: z.string().nullish(),
+      reasoning: z
+        .object({
+          context: z.string().nullish(),
+        })
+        .nullish(),
       incomplete_details: z.object({ reason: z.string() }).nullish(),
       usage: z
         .object({
@@ -1433,6 +1498,7 @@ export const openaiResponsesResponseSchema = lazySchema(() =>
           input_tokens_details: z
             .object({
               cached_tokens: z.number().nullish(),
+              cache_write_tokens: z.number().nullish(),
               orchestration_input_tokens: z.number().nullish(),
               orchestration_input_cached_tokens: z.number().nullish(),
             })

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

@@ -53,6 +53,10 @@ export const openaiResponsesReasoningModelIds = [
   'gpt-5.4-pro-2026-03-05',
   'gpt-5.5',
   'gpt-5.5-2026-04-23',
+  'gpt-5.6',
+  'gpt-5.6-luna',
+  'gpt-5.6-sol',
+  'gpt-5.6-terra',
 ] as const;
 
 export const openaiResponsesModelIds = [
@@ -121,6 +125,10 @@ export type OpenAIResponsesModelId =
   | 'gpt-5.4-pro-2026-03-05'
   | 'gpt-5.5'
   | 'gpt-5.5-2026-04-23'
+  | 'gpt-5.6'
+  | 'gpt-5.6-luna'
+  | 'gpt-5.6-sol'
+  | 'gpt-5.6-terra'
   | 'gpt-5-2025-08-07'
   | 'gpt-5-chat-latest'
   | 'gpt-5-codex'
@@ -222,11 +230,25 @@ export const openaiLanguageModelResponsesOptionsSchema = lazySchema(() =>
        */
       promptCacheKey: z.string().nullish(),
 
+      /**
+       * Prompt cache behavior for GPT-5.6 and later models.
+       * `mode` controls whether OpenAI also places an implicit breakpoint.
+       * `ttl` sets the minimum cache lifetime and currently only supports 30 minutes.
+       */
+      promptCacheOptions: z
+        .object({
+          mode: z.enum(['implicit', 'explicit']).optional(),
+          ttl: z.literal('30m').optional(),
+        })
+        .optional(),
+
       /**
        * The retention policy for the prompt cache.
        * - 'in_memory': Default. Standard prompt caching behavior.
        * - '24h': Extended prompt caching that keeps cached prefixes active for up to 24 hours.
-       *          Currently only available for 5.1 series models.
+       *          Available for models before GPT-5.6 that support extended caching.
+       *
+       * @deprecated For GPT-5.6 and later models, use `promptCacheOptions.ttl`.
        *
        * @default 'in_memory'
        */
@@ -235,15 +257,26 @@ export const openaiLanguageModelResponsesOptionsSchema = lazySchema(() =>
       /**
        * Reasoning effort for reasoning models. Defaults to `medium`. If you use
        * `providerOptions` to set the `reasoningEffort` option, this model setting will be ignored.
-       * Valid values: 'none' | 'minimal' | 'low' | 'medium' | 'high' | 'xhigh'
-       *
-       * The 'none' type for `reasoningEffort` is only available for OpenAI's GPT-5.1
-       * models. Also, the 'xhigh' type for `reasoningEffort` is only available for
-       * OpenAI's GPT-5.1-Codex-Max model. Setting `reasoningEffort` to 'none' or 'xhigh' with unsupported models will result in
-       * an error.
+       * GPT-5.6 supports 'none' | 'low' | 'medium' | 'high' | 'xhigh' | 'max'.
+       * Supported values vary by model.
        */
       reasoningEffort: z.string().nullish(),
 
+      /**
+       * Controls how much model work GPT-5.6 performs before returning a final answer.
+       * `standard` is the default. `pro` increases quality, latency, and token usage.
+       */
+      reasoningMode: z.enum(['standard', 'pro']).optional(),
+
+      /**
+       * Controls which available reasoning items GPT-5.6 can use.
+       * `auto` uses the model default, `current_turn` excludes reasoning from earlier
+       * turns, and `all_turns` makes compatible earlier reasoning available.
+       */
+      reasoningContext: z
+        .enum(['auto', 'current_turn', 'all_turns'])
+        .optional(),
+
       /**
        * Controls reasoning summary output from the model.
        * Set to "auto" to automatically receive the richest level available,