@ai-sdk/openai 3.0.105 → 3.0.107

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ai-sdk/openai",
-  "version": "3.0.105",
+  "version": "3.0.107",
   "license": "Apache-2.0",
   "sideEffects": false,
   "main": "./dist/index.js",

package/src/openai-stream-error.ts

@@ -5,9 +5,43 @@ type StreamError = {
   message: string;
   code?: string | number | null;
   type?: string | null;
-  frame: unknown;
 };
 
+export type OpenAIProviderStreamError = {
+  readonly message: string;
+  readonly type?: string;
+  readonly code?: string | number;
+  readonly statusCode: number;
+  readonly isRetryable: boolean;
+  readonly data: unknown;
+};
+
+/**
+ * Flattens an OpenAI stream error frame (`{ type: 'error', error: {...} }` or
+ * `response.failed`) so consumers can read `message` and `code` at the top
+ * level. The raw frame is kept in `data`.
+ */
+export function createOpenAIProviderStreamError(
+  frame: unknown,
+): OpenAIProviderStreamError | undefined {
+  const streamError = parseStreamError(frame);
+
+  if (streamError == null) {
+    return undefined;
+  }
+
+  const statusCode = getStatusCode(streamError);
+
+  return {
+    message: streamError.message,
+    type: streamError.type ?? undefined,
+    code: streamError.code ?? undefined,
+    statusCode,
+    isRetryable: isRetryableStreamError(streamError, statusCode),
+    data: frame,
+  };
+}
+
 export async function throwIfOpenAIStreamErrorBeforeOutput<T>({
   stream,
   getError,
@@ -103,7 +137,6 @@ function parseStreamError(frame: unknown): StreamError | undefined {
           message: responseError.message,
           code: getStringOrNumber(responseError.code),
           type: 'response.failed',
-          frame,
         }
       : undefined;
   }
@@ -119,7 +152,6 @@ function parseStreamError(frame: unknown): StreamError | undefined {
         message: error.message,
         code: getStringOrNumber(error.code),
         type: typeof error.type === 'string' ? error.type : undefined,
-        frame,
       }
     : undefined;
 }
@@ -179,3 +211,26 @@ function getStringOrNumber(value: unknown): string | number | undefined {
 function isHttpErrorStatusCode(value: number): boolean {
   return Number.isInteger(value) && value >= 400 && value <= 599;
 }
+
+function isRetryableStatusCode(statusCode: number): boolean {
+  return (
+    statusCode === 408 ||
+    statusCode === 409 ||
+    statusCode === 429 ||
+    statusCode >= 500
+  );
+}
+
+function isRetryableStreamError(
+  error: StreamError,
+  statusCode: number,
+): boolean {
+  if (
+    error.code === 'insufficient_quota' ||
+    error.type === 'insufficient_quota'
+  ) {
+    return false;
+  }
+
+  return isRetryableStatusCode(statusCode);
+}

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

@@ -1,18 +1,23 @@
-import type { LanguageModelV3Usage } from '@ai-sdk/provider';
+import type { JSONObject, LanguageModelV3Usage } from '@ai-sdk/provider';
 
-export type OpenAIResponsesUsage = {
+export type OpenAIResponsesUsage = JSONObject & {
   input_tokens: number;
   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;
-  output_tokens_details?: {
-    reasoning_tokens?: number | null;
-    orchestration_output_tokens?: number | null;
-  } | null;
+  total_tokens?: number;
+  input_tokens_details?:
+    | (JSONObject & {
+        cached_tokens?: number | null;
+        cache_write_tokens?: number | null;
+        orchestration_input_tokens?: number | null;
+        orchestration_input_cached_tokens?: number | null;
+      })
+    | null;
+  output_tokens_details?:
+    | (JSONObject & {
+        reasoning_tokens?: number | null;
+        orchestration_output_tokens?: number | null;
+      })
+    | null;
 };
 
 export function convertOpenAIResponsesUsage(

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

@@ -46,22 +46,40 @@ function serializeToolCallArguments(input: unknown): string {
 
 async function convertFunctionToolResultOutput({
   output,
+  promptCacheBreakpoint,
   providerOptionsName,
   warnings,
 }: {
   output: LanguageModelV3ToolResultOutput;
+  promptCacheBreakpoint?: OpenAIPromptCacheBreakpoint;
   providerOptionsName: string;
   warnings: Array<SharedV3Warning>;
 }): Promise<OpenAIResponsesFunctionCallOutput['output']> {
+  const convertScalarOutput = (
+    value: string,
+  ): OpenAIResponsesFunctionCallOutput['output'] =>
+    promptCacheBreakpoint == null
+      ? value
+      : [
+          {
+            type: 'input_text',
+            text: value,
+            prompt_cache_breakpoint: promptCacheBreakpoint,
+          },
+        ];
+
   switch (output.type) {
     case 'text':
     case 'error-text':
-      return output.value;
-    case 'execution-denied':
-      return output.reason ?? 'Tool call execution denied.';
+      return convertScalarOutput(output.value);
+    case 'execution-denied': {
+      return convertScalarOutput(
+        output.reason ?? 'Tool call execution denied.',
+      );
+    }
     case 'json':
     case 'error-json':
-      return JSON.stringify(output.value);
+      return convertScalarOutput(JSON.stringify(output.value));
     case 'content':
       return output.value
         .map(item => {
@@ -246,6 +264,24 @@ function getPromptCacheBreakpoint(
     | undefined;
 }
 
+function getScalarToolResultPromptCacheBreakpoint({
+  output,
+  toolResultProviderOptions,
+  providerOptionsName,
+}: {
+  output: LanguageModelV3ToolResultOutput;
+  toolResultProviderOptions: SharedV3ProviderOptions | undefined;
+  providerOptionsName: string;
+}): OpenAIPromptCacheBreakpoint | undefined {
+  return output.type === 'content'
+    ? undefined
+    : (getPromptCacheBreakpoint(output.providerOptions, providerOptionsName) ??
+        getPromptCacheBreakpoint(
+          toolResultProviderOptions,
+          providerOptionsName,
+        ));
+}
+
 /**
  * Check if a string is a file ID based on the given prefixes
  * Returns false if prefixes is undefined (disables file ID detection)
@@ -989,13 +1025,29 @@ export async function convertToOpenAIResponsesInput({
               );
 
               const toolOutputs = await Promise.all(
-                parallelToolResultGroup.results.map(async result =>
-                  convertFunctionToolResultOutput({
-                    output: result.output,
-                    providerOptionsName,
-                    warnings,
-                  }),
-                ),
+                parallelToolResultGroup.results.map(async result => {
+                  const promptCacheBreakpoint =
+                    getScalarToolResultPromptCacheBreakpoint({
+                      output: result.output,
+                      toolResultProviderOptions: result.providerOptions,
+                      providerOptionsName,
+                    });
+
+                  return {
+                    output: await convertFunctionToolResultOutput({
+                      output: result.output,
+                      providerOptionsName,
+                      warnings,
+                    }),
+                    promptCacheBreakpoint,
+                  };
+                }),
+              );
+              const serializedToolOutputs = toolOutputs.map(({ output }) =>
+                typeof output === 'string' ? output : JSON.stringify(output),
+              );
+              const hasPromptCacheBreakpoint = toolOutputs.some(
+                ({ promptCacheBreakpoint }) => promptCacheBreakpoint != null,
               );
 
               input.push({
@@ -1003,13 +1055,16 @@ export async function convertToOpenAIResponsesInput({
                 call_id: parallelToolResultGroup.metadata.toolCallId,
                 // The internal wrapper returns one output containing the child
                 // results in the same order as the original tool_uses array.
-                output: toolOutputs
-                  .map(output =>
-                    typeof output === 'string'
-                      ? output
-                      : JSON.stringify(output),
-                  )
-                  .join('\n'),
+                output: hasPromptCacheBreakpoint
+                  ? serializedToolOutputs.map((text, index) => ({
+                      type: 'input_text',
+                      text: index === 0 ? text : `\n${text}`,
+                      ...(toolOutputs[index].promptCacheBreakpoint != null && {
+                        prompt_cache_breakpoint:
+                          toolOutputs[index].promptCacheBreakpoint,
+                      }),
+                    }))
+                  : serializedToolOutputs.join('\n'),
               });
             }
             continue;
@@ -1114,18 +1169,38 @@ export async function convertToOpenAIResponsesInput({
           }
 
           if (customProviderToolNames?.has(resolvedToolName)) {
+            const promptCacheBreakpoint =
+              getScalarToolResultPromptCacheBreakpoint({
+                output,
+                toolResultProviderOptions: part.providerOptions,
+                providerOptionsName,
+              });
+            const convertScalarOutput = (
+              value: string,
+            ): OpenAIResponsesCustomToolCallOutput['output'] =>
+              promptCacheBreakpoint == null
+                ? value
+                : [
+                    {
+                      type: 'input_text',
+                      text: value,
+                      prompt_cache_breakpoint: promptCacheBreakpoint,
+                    },
+                  ];
             let outputValue: OpenAIResponsesCustomToolCallOutput['output'];
             switch (output.type) {
               case 'text':
               case 'error-text':
-                outputValue = output.value;
+                outputValue = convertScalarOutput(output.value);
                 break;
               case 'execution-denied':
-                outputValue = output.reason ?? 'Tool call execution denied.';
+                outputValue = convertScalarOutput(
+                  output.reason ?? 'Tool call execution denied.',
+                );
                 break;
               case 'json':
               case 'error-json':
-                outputValue = JSON.stringify(output.value);
+                outputValue = convertScalarOutput(JSON.stringify(output.value));
                 break;
               case 'content':
                 outputValue = output.value
@@ -1205,6 +1280,11 @@ export async function convertToOpenAIResponsesInput({
 
           const contentValue = await convertFunctionToolResultOutput({
             output,
+            promptCacheBreakpoint: getScalarToolResultPromptCacheBreakpoint({
+              output,
+              toolResultProviderOptions: part.providerOptions,
+              providerOptionsName,
+            }),
             providerOptionsName,
             warnings,
           });

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

@@ -17,6 +17,37 @@ const jsonValueSchema: z.ZodType<JSONValue> = z.lazy(() =>
   ]),
 );
 
+const jsonObjectSchema = z.record(z.string(), jsonValueSchema.optional());
+
+const openaiResponsesUsageSchema = z.intersection(
+  jsonObjectSchema,
+  z.object({
+    input_tokens: z.number(),
+    input_tokens_details: z
+      .intersection(
+        jsonObjectSchema,
+        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(),
+        }),
+      )
+      .nullish(),
+    output_tokens: z.number(),
+    output_tokens_details: z
+      .intersection(
+        jsonObjectSchema,
+        z.object({
+          reasoning_tokens: z.number().nullish(),
+          orchestration_output_tokens: z.number().nullish(),
+        }),
+      )
+      .nullish(),
+    total_tokens: z.number().optional(),
+  }),
+);
+
 function isRecord(value: unknown): value is Record<string, unknown> {
   return value != null && typeof value === 'object' && !Array.isArray(value);
 }
@@ -675,24 +706,7 @@ export const openaiResponsesChunkSchema = lazySchema(() =>
         type: z.enum(['response.completed', 'response.incomplete']),
         response: z.object({
           incomplete_details: z.object({ reason: z.string() }).nullish(),
-          usage: z.object({
-            input_tokens: z.number(),
-            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(),
-              })
-              .nullish(),
-            output_tokens: z.number(),
-            output_tokens_details: z
-              .object({
-                reasoning_tokens: z.number().nullish(),
-                orchestration_output_tokens: z.number().nullish(),
-              })
-              .nullish(),
-          }),
+          usage: openaiResponsesUsageSchema.nullish(),
           reasoning: z
             .object({
               context: z.string().nullish(),
@@ -712,26 +726,7 @@ export const openaiResponsesChunkSchema = lazySchema(() =>
             })
             .nullish(),
           incomplete_details: z.object({ reason: z.string() }).nullish(),
-          usage: z
-            .object({
-              input_tokens: z.number(),
-              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(),
-                })
-                .nullish(),
-              output_tokens: z.number(),
-              output_tokens_details: z
-                .object({
-                  reasoning_tokens: z.number().nullish(),
-                  orchestration_output_tokens: z.number().nullish(),
-                })
-                .nullish(),
-            })
-            .nullish(),
+          usage: openaiResponsesUsageSchema.nullish(),
           reasoning: z
             .object({
               context: z.string().nullish(),
@@ -1563,26 +1558,7 @@ export const openaiResponsesResponseSchema = lazySchema(() =>
         })
         .nullish(),
       incomplete_details: z.object({ reason: z.string() }).nullish(),
-      usage: z
-        .object({
-          input_tokens: z.number(),
-          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(),
-            })
-            .nullish(),
-          output_tokens: z.number(),
-          output_tokens_details: z
-            .object({
-              reasoning_tokens: z.number().nullish(),
-              orchestration_output_tokens: z.number().nullish(),
-            })
-            .nullish(),
-        })
-        .optional(),
+      usage: openaiResponsesUsageSchema.nullish(),
     }),
   ),
 );

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

@@ -29,7 +29,10 @@ import {
 import type { OpenAIConfig } from '../openai-config';
 import { openaiFailedResponseHandler } from '../openai-error';
 import { getOpenAILanguageModelCapabilities } from '../openai-language-model-capabilities';
-import { throwIfOpenAIStreamErrorBeforeOutput } from '../openai-stream-error';
+import {
+  createOpenAIProviderStreamError,
+  throwIfOpenAIStreamErrorBeforeOutput,
+} from '../openai-stream-error';
 import type { applyPatchInputSchema } from '../tool/apply-patch';
 import type {
   codeInterpreterInputSchema,
@@ -2203,7 +2206,7 @@ export class OpenAIResponsesLanguageModel implements LanguageModelV3 {
                   raw: value.response.incomplete_details?.reason ?? undefined,
                 };
               }
-              usage = value.response.usage;
+              usage = value.response.usage ?? undefined;
               if (typeof value.response.service_tier === 'string') {
                 serviceTier = value.response.service_tier;
               }
@@ -2229,17 +2232,18 @@ export class OpenAIResponsesLanguageModel implements LanguageModelV3 {
 
               if (!encounteredStreamError && value.response.error != null) {
                 encounteredStreamError = true;
+                const error = {
+                  type: 'response.failed',
+                  sequence_number: value.sequence_number,
+                  response: {
+                    error: value.response.error,
+                    incomplete_details: value.response.incomplete_details,
+                    service_tier: value.response.service_tier,
+                  },
+                };
                 controller.enqueue({
                   type: 'error',
-                  error: {
-                    type: 'response.failed',
-                    sequence_number: value.sequence_number,
-                    response: {
-                      error: value.response.error,
-                      incomplete_details: value.response.incomplete_details,
-                      service_tier: value.response.service_tier,
-                    },
-                  },
+                  error: createOpenAIProviderStreamError(error) ?? error,
                 });
               }
             } else if (isResponseAnnotationAddedChunk(value)) {
@@ -2313,7 +2317,10 @@ export class OpenAIResponsesLanguageModel implements LanguageModelV3 {
             } else if (isErrorChunk(value)) {
               encounteredStreamError = true;
               finishReason = { unified: 'error', raw: 'error' };
-              controller.enqueue({ type: 'error', error: value });
+              controller.enqueue({
+                type: 'error',
+                error: createOpenAIProviderStreamError(value) ?? value,
+              });
             }
           },