@ai-sdk/openai 4.x breaking changes: 4.0.99 to 4.0.109

@ai-sdk/openai 4.0.99: promptCacheOptions type changed

@ai-sdk/openai 4.0.99 released 21 October 2026Published 21 October 2026Updated 4 November 2026

@ai-sdk/openai 4.0.99 declares promptCacheOptions with a different type on OpenAILanguageModelResponsesOptions and OpenAIResponsesProviderOptions. The changelog for the same release adds support for 12h prompt cache writes and cache prewarming. Code that supplies or reads that member through either type may stop type-checking after the upgrade.

What changed

• OpenAILanguageModelResponsesOptions. Version 4.0.99 declares promptCacheOptions with another type than 4.0.98 did. The finding is breaking, with medium confidence, and it is reported wherever the type is imported from @ai-sdk/openai and named in a type position.
• OpenAIResponsesProviderOptions. This carries the same change. In the exported declarations it is an alias of OpenAILanguageModelResponsesOptions, so one options object in your code can produce both reports and one correction can settle both.
• What a report means. Naming either type does not mean the changed member reaches that code. A file that only passes options along, without setting or reading promptCacheOptions, may need no edit.

Before and after

Neither finding has a deterministic rewrite, so there is no fixed before and after pair for this release. The scan reports any type position that names either type imported from the package:

import type { OpenAIResponsesProviderOptions } from '@ai-sdk/openai';

The declaration of the underlying type reads the same in 4.0.98 and 4.0.99:

type OpenAILanguageModelResponsesOptions = InferSchema<typeof openaiLanguageModelResponsesOptionsSchema>;

What differs is the schema behind that line, where promptCacheOptions has another type. Open dist/index.d.ts in the installed 4.0.99 package to read the new member type, then bring the code that sets or reads it into line with that declaration and leave the rest of the file alone.

Migration guidance and its limits

Both findings carry assisted patches. emendant fix writes one only when you name a model provider, on the command line or in your Emendant configuration. Without a provider, each finding is reported with its guidance and nothing is changed. Nothing in this release is report only. Run emendant scan first to see which files are named, then emendant fix for the patches.

Each patch is checked with your typecheck and your tests. Read the patch header to see which checks passed, and review every edit that touches promptCacheOptions. Whether to adopt the new prompt cache behaviour is your decision, and a patch does not make it for you.

A report on a file that never sets or reads promptCacheOptions may need no edit, and a patch may not be available for it. Review the surrounding code before you accept a change there.

A clean scan does not cover these types reached through your own re-export, or a same-named type imported from another module. Those are not reported. This page covers the two changes the feed carries for 4.0.99 and nothing else in the release.

What Emendant detects, fixes and verifies

2 changes in @ai-sdk/openai 4.0.99. 0 automatic fixes, 2 fixes requiring a model provider you choose, 0 report only. Each patch states which checks passed. Understand patch evidence.

emendant explain <change-id> prints any row's entry, guidance and sources at the terminal.

Requires emendant@0.3.0 or later. Feed entry feed/npm/@ai-sdk/openai/4.0.99.json, snapshot 2026-10-21.1.

Primary sources

• @ai-sdk/openai@4.0.99npm registry, the published package
• @ai-sdk/openai@4.0.98npm registry, the published package

@ai-sdk/openai 4.0.106: apiKey on OpenAIProviderSettings and headers on realtime configs changed

@ai-sdk/openai 4.0.106 released 30 October 2026Published 30 October 2026

@ai-sdk/openai 4.0.106 declares apiKey on OpenAIProviderSettings with another type, and declares headers with another type on Experimental_OpenAIRealtimeModelConfig and Experimental_OpenAIRealtimeModelLiveConfig. Code that supplies or reads those members through these types may stop type-checking after the upgrade. The release changelog says provider API key and token settings now accept promises and callbacks.

What changed

• OpenAIProviderSettings. At 4.0.105 apiKey is declared as string. At 4.0.106 it is declared as Resolvable<string>, and the declaration notes that a function is called before each request and may return a promise. The finding is breaking, with medium confidence, and it is reported wherever the type is imported from @ai-sdk/openai and named in a type position.
• Experimental_OpenAIRealtimeModelConfig. The release declares headers with another type. The same import-and-type-position rule decides where it is reported.
• Experimental_OpenAIRealtimeModelLiveConfig. This carries the same headers change as its own finding, so a file that names both types can appear twice in a scan.
• What a report means. Naming one of these types does not mean the changed member reaches that code. A file that only passes a value along, without setting or reading apiKey or headers, may need no edit.

Before and after

None of the three findings has a deterministic rewrite, so there is no fixed before and after pair. The scan reports a type import like this one:

import type { OpenAIProviderSettings } from '@ai-sdk/openai';

The shape change behind the OpenAIProviderSettings report is in the declaration of apiKey. At 4.0.105:

  apiKey?: string;

At 4.0.106:

  apiKey?: Resolvable<string>;

Code that reads apiKey back and treats it as a plain string needs to handle the wider type. Code that only assigns a string keeps working. For the two realtime config types the published declarations name headers as the changed member without spelling out the new type here, so open dist/index.d.ts in the installed 4.0.106 package and read it there.

Migration guidance and its limits

All three findings carry assisted patches. emendant fix writes one only when you name a model provider, on the command line or in your Emendant configuration. Without a provider, each finding is reported with its guidance and nothing is changed. Nothing in this release is report only. Run emendant scan first to see which files are named.

Each patch is checked with your typecheck and your tests. Read the patch header to see which checks passed, and review every edit that touches apiKey or headers. A patch brings the member into line with what 4.0.106 declares and should leave the rest of the file alone. Where a site only names the type, a patch may not be available.

A clean scan does not cover these types reached through your own re-export, or a same-named type imported from another module. Those are not reported. The changelog also says the experimental OpenAI Live getServerWebSocketConfig method can now resolve asynchronously and that its result must be awaited. That is outside the three findings above, so search your code for its call sites yourself. This page covers the three changes the feed carries for 4.0.106 and nothing else in the release.

What Emendant detects, fixes and verifies

3 changes in @ai-sdk/openai 4.0.106. 0 automatic fixes, 3 fixes requiring a model provider you choose, 0 report only. Each patch states which checks passed. Understand patch evidence.

emendant explain <change-id> prints any row's entry, guidance and sources at the terminal.

Requires emendant@0.3.0 or later. Feed entry feed/npm/@ai-sdk/openai/4.0.106.json, snapshot 2026-10-30.2.

Primary sources

• @ai-sdk/openai@4.0.106npm registry, the published package
• @ai-sdk/openai@4.0.105npm registry, the published package

@ai-sdk/openai 4.0.109: OpenAIImageModelGenerationOptions members changed

@ai-sdk/openai 4.0.109 released 5 November 2026Published 7 November 2026

@ai-sdk/openai 4.0.109 changes the members of OpenAIImageModelGenerationOptions. It newly declares optional complexity, frameCount, frameDurationMs and safetyIdentifier, and it declares outputFormat with another type. Code that supplies or reads those members through this type may stop type-checking after the upgrade. The release changelog ties the additions to GPT Image 2.6 model support and animated GIF output.

What changed

• New optional members. OpenAIImageModelGenerationOptions now declares complexity, frameCount, frameDurationMs and safetyIdentifier. The finding is breaking, with medium confidence, and it is reported wherever the type is imported from @ai-sdk/openai and named in a type position.
• outputFormat. At 4.0.108 it accepted png, jpeg and webp. At 4.0.109 the declaration also accepts gif. Code that narrows or switches over the old union should account for the new value.
• What a report means. Naming the type does not mean a changed member reaches that code. A file that only passes options along, without setting or reading one of the members above, may need no edit.

Before and after

This finding has no deterministic rewrite, so there is no fixed before and after pair. The scan reports a type import like this one:

import type { OpenAIImageModelGenerationOptions } from '@ai-sdk/openai';

The shape change that matters most is in the outputFormat declaration. At 4.0.108:

outputFormat?: "png" | "jpeg" | "webp" | undefined;

At 4.0.109:

outputFormat?: "png" | "jpeg" | "webp" | "gif" | undefined;

Code that reads outputFormat back and assumes the three older values needs to handle gif. Code that only assigns one of the older values keeps working. The four new members are optional, so code that never sets them is unaffected by those additions.

Migration guidance and its limits

The finding carries an assisted patch. emendant fix writes one only when you name a model provider, on the command line or in your Emendant configuration. Without a provider, the finding is reported with its guidance and nothing is changed. Nothing in this release is report only. Run emendant scan first to see which files are named.

Each patch is checked with your typecheck and your tests. Read the patch header to see which checks passed, and review every edit that touches outputFormat, complexity, frameCount, frameDurationMs or safetyIdentifier. A patch brings the member into line with what 4.0.109 declares and should leave the rest of the file alone.

A site that only names the type may need no edit, and a patch may not be available for it. Review the surrounding code before you accept a change there.

A clean scan does not cover this type reached through your own re-export, or a same-named type imported from another module. Those are not reported. The 4.0.109 declarations also give OpenAIImageModelEditOptions additional members, which this page does not cover, so check code that uses that type yourself. This page covers the one change the feed carries for 4.0.109 and nothing else in the release.

What Emendant detects, fixes and verifies

1 change in @ai-sdk/openai 4.0.109. 0 automatic fixes, 1 fixes requiring a model provider you choose, 0 report only. Each patch states which checks passed. Understand patch evidence.

emendant explain <change-id> prints any row's entry, guidance and sources at the terminal.

Requires emendant@0.3.0 or later. Feed entry feed/npm/@ai-sdk/openai/4.0.109.json, snapshot 2026-11-07.2.

Primary sources

• @ai-sdk/openai@4.0.109npm registry, the published package
• @ai-sdk/openai@4.0.108npm registry, the published package