@ai-sdk/openai 4.0.0-beta.4 → 4.0.0-beta.41

package/docs/03-openai.mdx

@@ -257,6 +257,11 @@ The following provider options are available:
 - **forceReasoning** _boolean_
   Force treating this model as a reasoning model. This is useful for "stealth" reasoning models (e.g. via a custom baseURL) where the model ID is not recognized by the SDK's allowlist. When enabled, the SDK applies reasoning-model parameter compatibility rules and defaults `systemMessageMode` to `developer` unless overridden.
 
+- **contextManagement** _Array<object>_
+  Enable server-side context management (compaction). When configured, the server automatically compresses conversation context when token usage crosses a specified threshold. Each object in the array should have:
+  - `type`: `'compaction'`
+  - `compactThreshold`: _number_ — the token count at which compaction is triggered
+
 The OpenAI responses provider also returns provider-specific metadata:
 
 For Responses models, you can type this metadata using `OpenaiResponsesProviderMetadata`:
@@ -764,7 +769,7 @@ const result = await generateText({
     }),
   },
   prompt: 'List the files in my home directory.',
-  stopWhen: stepCountIs(2),
+  stopWhen: isStepCount(2),
 });
 ```
 
@@ -922,7 +927,7 @@ const result = await generateText({
     }),
   },
   prompt: 'Use the skill to solve this problem.',
-  stopWhen: stepCountIs(5),
+  stopWhen: isStepCount(5),
 });
 ```
 
@@ -937,7 +942,7 @@ enabling iterative, multi-step code editing workflows.
 
 ```ts
 import { openai } from '@ai-sdk/openai';
-import { generateText, stepCountIs } from 'ai';
+import { generateText, isStepCount } from 'ai';
 
 const result = await generateText({
   model: openai('gpt-5.1'),
@@ -949,7 +954,7 @@ const result = await generateText({
     }),
   },
   prompt: 'Create a python file that calculates the factorial of a number',
-  stopWhen: stepCountIs(5),
+  stopWhen: isStepCount(5),
 });
 ```
 
@@ -958,6 +963,145 @@ Your execute function must return:
 - **status** _'completed' | 'failed'_ - Whether the patch was applied successfully
 - **output** _string_ (optional) - Human-readable log text (e.g., results or error messages)
 
+#### Tool Search
+
+Tool search allows the model to dynamically search for and load tools into context as needed,
+rather than loading all tool definitions up front. This can reduce token usage, cost, and latency
+when you have many tools. Mark the tools you want to make searchable with `deferLoading: true`
+in their `providerOptions`.
+
+There are two execution modes:
+
+- **Server-executed (hosted):** OpenAI searches across the deferred tools declared in the request and returns the loaded subset in the same response. No extra round-trip is needed.
+- **Client-executed:** The model emits a `tool_search_call`, your application performs the lookup, and you return the matching tools via the `execute` callback.
+
+##### Server-Executed (Hosted) Tool Search
+
+Use hosted tool search when the candidate tools are already known at request time.
+Add `openai.tools.toolSearch()` with no arguments and mark your tools with `deferLoading: true`:
+
+```ts
+import { openai } from '@ai-sdk/openai';
+import { generateText, tool, isStepCount } from 'ai';
+import { z } from 'zod';
+
+const result = await generateText({
+  model: openai.responses('gpt-5.4'),
+  prompt: 'What is the weather in San Francisco?',
+  stopWhen: isStepCount(10),
+  tools: {
+    toolSearch: openai.tools.toolSearch(),
+
+    get_weather: tool({
+      description: 'Get the current weather at a specific location',
+      inputSchema: z.object({
+        location: z.string(),
+        unit: z.enum(['celsius', 'fahrenheit']),
+      }),
+      execute: async ({ location, unit }) => ({
+        location,
+        temperature: unit === 'celsius' ? 18 : 64,
+      }),
+      providerOptions: {
+        openai: { deferLoading: true },
+      },
+    }),
+
+    search_files: tool({
+      description: 'Search through files in the workspace',
+      inputSchema: z.object({ query: z.string() }),
+      execute: async ({ query }) => ({
+        results: [`Found 3 files matching "${query}"`],
+      }),
+      providerOptions: {
+        openai: { deferLoading: true },
+      },
+    }),
+  },
+});
+```
+
+In hosted mode, the model internally searches the deferred tools, loads the relevant ones, and
+proceeds to call them — all within a single response. The `tool_search_call` and
+`tool_search_output` items appear in the response with `execution: 'server'` and `call_id: null`.
+
+##### Client-Executed Tool Search
+
+Use client-executed tool search when tool discovery depends on runtime state — for example,
+tools that vary per tenant, project, or external system. Pass `execution: 'client'` along with
+a `description`, `parameters` schema, and an `execute` callback:
+
+```ts
+import { openai } from '@ai-sdk/openai';
+import { generateText, tool, isStepCount } from 'ai';
+import { z } from 'zod';
+
+const result = await generateText({
+  model: openai.responses('gpt-5.4'),
+  prompt: 'What is the weather in San Francisco?',
+  stopWhen: isStepCount(10),
+  tools: {
+    toolSearch: openai.tools.toolSearch({
+      execution: 'client',
+      description: 'Search for available tools based on what the user needs.',
+      parameters: {
+        type: 'object',
+        properties: {
+          goal: {
+            type: 'string',
+            description: 'What the user is trying to accomplish',
+          },
+        },
+        required: ['goal'],
+        additionalProperties: false,
+      },
+      execute: async ({ arguments: args }) => {
+        // Your custom tool discovery logic here.
+        // Return the tools that match the search goal.
+        return {
+          tools: [
+            {
+              type: 'function',
+              name: 'get_weather',
+              description: 'Get the current weather at a specific location',
+              deferLoading: true,
+              parameters: {
+                type: 'object',
+                properties: {
+                  location: { type: 'string' },
+                },
+                required: ['location'],
+                additionalProperties: false,
+              },
+            },
+          ],
+        };
+      },
+    }),
+
+    get_weather: tool({
+      description: 'Get the current weather at a specific location',
+      inputSchema: z.object({ location: z.string() }),
+      execute: async ({ location }) => ({
+        location,
+        temperature: 64,
+        condition: 'Partly cloudy',
+      }),
+      providerOptions: {
+        openai: { deferLoading: true },
+      },
+    }),
+  },
+});
+```
+
+In client mode, the flow spans two steps:
+
+1. **Step 1:** The model emits a `tool_search_call` with `execution: 'client'` and a non-null `call_id`. The SDK calls your `execute` callback with the search arguments. Your callback returns the discovered tools.
+2. **Step 2:** The SDK sends the `tool_search_output` (with the matching `call_id`) back to the model. The model can now call the loaded tools as normal function calls.
+
+For more details, see the [OpenAI Tool Search documentation](https://platform.openai.com/docs/guides/tools-tool-search).
+
 #### Custom Tool
 
 The OpenAI Responses API supports
@@ -969,13 +1113,12 @@ SQL queries, code snippets, or any output that must match a specific pattern.
 
 ```ts
 import { openai } from '@ai-sdk/openai';
-import { generateText, stepCountIs } from 'ai';
+import { generateText, isStepCount } from 'ai';
 
 const result = await generateText({
   model: openai.responses('gpt-5.2-codex'),
   tools: {
     write_sql: openai.tools.customTool({
-      name: 'write_sql',
       description: 'Write a SQL SELECT query to answer the user question.',
       format: {
         type: 'grammar',
@@ -991,7 +1134,7 @@ const result = await generateText({
   },
   toolChoice: 'required',
   prompt: 'Write a SQL query to get all users older than 25.',
-  stopWhen: stepCountIs(3),
+  stopWhen: isStepCount(3),
 });
 ```
 
@@ -1005,7 +1148,6 @@ const result = streamText({
   model: openai.responses('gpt-5.2-codex'),
   tools: {
     write_sql: openai.tools.customTool({
-      name: 'write_sql',
       description: 'Write a SQL SELECT query to answer the user question.',
       format: {
         type: 'grammar',
@@ -1028,7 +1170,6 @@ for await (const chunk of result.fullStream) {
 
 The custom tool can be configured with:
 
-- **name** _string_ (required) - The name of the custom tool. Used to identify the tool in tool calls.
 - **description** _string_ (optional) - A description of what the tool does, to help the model understand when to use it.
 - **format** _object_ (optional) - The output format constraint. Omit for unconstrained text output.
   - **type** _'grammar' | 'text'_ - The format type. Use `'grammar'` for constrained output or `'text'` for explicit unconstrained text.
@@ -1053,8 +1194,9 @@ const result = await generateText({
           text: 'Please describe the image.',
         },
         {
-          type: 'image',
-          image: readFileSync('./data/image.png'),
+          type: 'file',
+          mediaType: 'image',
+          data: readFileSync('./data/image.png'),
         },
       ],
     },
@@ -1069,8 +1211,9 @@ You can also pass a file-id from the OpenAI Files API.
 
 ```ts
 {
-  type: 'image',
-  image: 'file-8EFBcWHsQxZV7YGezBC1fq'
+  type: 'file',
+  mediaType: 'image',
+  data: 'file-8EFBcWHsQxZV7YGezBC1fq'
 }
 ```
 
@@ -1078,8 +1221,9 @@ You can also pass the URL of an image.
 
 ```ts
 {
-  type: 'image',
-  image: 'https://sample.edu/image.png',
+  type: 'file',
+  mediaType: 'image',
+  data: 'https://sample.edu/image.png',
 }
 ```
 
@@ -1375,6 +1519,125 @@ for (const part of result.content) {
   are fields like `filename` that are directly available on the source object.
 </Note>
 
+#### Compaction
+
+The OpenAI Responses API supports server-side context compaction. When enabled, the server automatically compresses conversation context when token usage crosses a configured threshold. This is useful for long-running conversations or agent loops where you want to stay within token limits without manually managing context.
+
+The compaction item returned by the server is opaque and encrypted — it carries forward key prior state and reasoning into the next turn using fewer tokens. The AI SDK handles this automatically: compaction items are returned as text parts with special `providerMetadata`, and when passed back in subsequent requests they are sent as compaction input items.
+
+```ts highlight="7-11"
+import {
+  openai,
+  type OpenAILanguageModelResponsesOptions,
+} from '@ai-sdk/openai';
+import { generateText } from 'ai';
+
+const result = await generateText({
+  model: openai.responses('gpt-5.2'),
+  messages: conversationHistory,
+  providerOptions: {
+    openai: {
+      store: false,
+      contextManagement: [{ type: 'compaction', compactThreshold: 50000 }],
+    } satisfies OpenAILanguageModelResponsesOptions,
+  },
+});
+```
+
+**Configuration:**
+
+- **type** — Must be `'compaction'`
+- **compactThreshold** — The token count at which compaction is triggered. When the rendered input token count crosses this threshold, the server runs a compaction pass before continuing inference.
+
+<Note>
+  Server-side compaction is ZDR-friendly when you set `store: false` on your
+  requests.
+</Note>
+
+##### Detecting Compaction in Streams
+
+When using `streamText`, you can detect compaction by checking the `providerMetadata` on `text-start` and `text-end` events:
+
+```ts
+import {
+  openai,
+  type OpenAILanguageModelResponsesOptions,
+} from '@ai-sdk/openai';
+import { streamText } from 'ai';
+
+const result = streamText({
+  model: openai.responses('gpt-5.2'),
+  messages: conversationHistory,
+  providerOptions: {
+    openai: {
+      store: false,
+      contextManagement: [{ type: 'compaction', compactThreshold: 50000 }],
+    } satisfies OpenAILanguageModelResponsesOptions,
+  },
+});
+
+for await (const part of result.fullStream) {
+  switch (part.type) {
+    case 'text-start': {
+      const isCompaction = part.providerMetadata?.openai?.type === 'compaction';
+      if (isCompaction) {
+        // ... your logic
+      }
+      break;
+    }
+    case 'text-end': {
+      const isCompaction = part.providerMetadata?.openai?.type === 'compaction';
+      if (isCompaction) {
+        // ... your logic
+      }
+      break;
+    }
+    case 'text-delta': {
+      process.stdout.write(part.text);
+      break;
+    }
+  }
+}
+```
+
+##### Compaction in UI Applications
+
+When using `useChat` or other UI hooks, compaction items appear as text parts with `providerMetadata`. You can detect and style them differently in your UI:
+
+```tsx
+{
+  message.parts.map((part, index) => {
+    if (part.type === 'text') {
+      const isCompaction =
+        (part.providerMetadata?.openai as { type?: string } | undefined)
+          ?.type === 'compaction';
+
+      if (isCompaction) {
+        return (
+          <div
+            key={index}
+            className="bg-yellow-100 border-l-4 border-yellow-500 p-2"
+          >
+            <span className="font-bold">[Context Compacted]</span>
+            <p className="text-sm text-yellow-700">
+              The server compressed the conversation context to reduce token
+              usage.
+            </p>
+          </div>
+        );
+      }
+      return <div key={index}>{part.text}</div>;
+    }
+  });
+}
+```
+
+The metadata includes the following fields:
+
+- **type** — Always `'compaction'`
+- **itemId** _string_ — The ID of the compaction item in the Responses API
+- **encryptedContent** _string_ (optional) — The encrypted compaction state. This is automatically sent back to the API when the message is included in subsequent requests.
+
 ### Chat Models
 
 You can create models that call the [OpenAI chat API](https://platform.openai.com/docs/api-reference/chat) using the `.chat()` factory method.
@@ -1671,8 +1934,9 @@ const result = await generateText({
           text: 'Please describe the image.',
         },
         {
-          type: 'image',
-          image: readFileSync('./data/image.png'),
+          type: 'file',
+          mediaType: 'image',
+          data: readFileSync('./data/image.png'),
         },
       ],
     },
@@ -1687,8 +1951,9 @@ You can also pass the URL of an image.
 
 ```ts
 {
-  type: 'image',
-  image: 'https://sample.edu/image.png',
+  type: 'file',
+  mediaType: 'image',
+  data: 'https://sample.edu/image.png',
 }
 ```
 
@@ -1805,9 +2070,9 @@ const result = await generateText({
       content: [
         { type: 'text', text: 'Describe the image in detail.' },
         {
-          type: 'image',
-          image:
-            'https://github.com/vercel/ai/blob/main/examples/ai-functions/data/comic-cat.png?raw=true',
+          type: 'file',
+          mediaType: 'image',
+          data: 'https://github.com/vercel/ai/blob/main/examples/ai-functions/data/comic-cat.png?raw=true',
 
           // OpenAI specific options - image detail:
           providerOptions: {
@@ -2041,6 +2306,11 @@ The following optional provider options are available for OpenAI completion mode
 
 | Model                 | Image Input         | Audio Input         | Object Generation   | Tool Usage          |
 | --------------------- | ------------------- | ------------------- | ------------------- | ------------------- |
+| `gpt-5.4-pro`         | <Check size={18} /> | <Cross size={18} /> | <Check size={18} /> | <Check size={18} /> |
+| `gpt-5.4`             | <Check size={18} /> | <Cross size={18} /> | <Check size={18} /> | <Check size={18} /> |
+| `gpt-5.4-mini`        | <Check size={18} /> | <Cross size={18} /> | <Check size={18} /> | <Check size={18} /> |
+| `gpt-5.4-nano`        | <Check size={18} /> | <Cross size={18} /> | <Check size={18} /> | <Check size={18} /> |
+| `gpt-5.3-chat-latest` | <Check size={18} /> | <Cross size={18} /> | <Check size={18} /> | <Check size={18} /> |
 | `gpt-5.2-pro`         | <Check size={18} /> | <Cross size={18} /> | <Check size={18} /> | <Check size={18} /> |
 | `gpt-5.2-chat-latest` | <Check size={18} /> | <Cross size={18} /> | <Check size={18} /> | <Check size={18} /> |
 | `gpt-5.2`             | <Check size={18} /> | <Cross size={18} /> | <Check size={18} /> | <Check size={18} /> |

package/package.json

@@ -1,10 +1,10 @@
 {
   "name": "@ai-sdk/openai",
-  "version": "4.0.0-beta.4",
+  "version": "4.0.0-beta.41",
+  "type": "module",
   "license": "Apache-2.0",
   "sideEffects": false,
   "main": "./dist/index.js",
-  "module": "./dist/index.mjs",
   "types": "./dist/index.d.ts",
   "files": [
     "dist/**/*",
@@ -25,26 +25,25 @@
     "./package.json": "./package.json",
     ".": {
       "types": "./dist/index.d.ts",
-      "import": "./dist/index.mjs",
-      "require": "./dist/index.js"
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
     },
     "./internal": {
       "types": "./dist/internal/index.d.ts",
-      "import": "./dist/internal/index.mjs",
-      "module": "./dist/internal/index.mjs",
-      "require": "./dist/internal/index.js"
+      "import": "./dist/internal/index.js",
+      "default": "./dist/internal/index.js"
     }
   },
   "dependencies": {
-    "@ai-sdk/provider-utils": "5.0.0-beta.1",
-    "@ai-sdk/provider": "4.0.0-beta.0"
+    "@ai-sdk/provider": "4.0.0-beta.14",
+    "@ai-sdk/provider-utils": "5.0.0-beta.29"
   },
   "devDependencies": {
     "@types/node": "20.17.24",
     "tsup": "^8",
     "typescript": "5.8.3",
     "zod": "3.25.76",
-    "@ai-sdk/test-server": "2.0.0-beta.0",
+    "@ai-sdk/test-server": "2.0.0-beta.3",
     "@vercel/ai-tsconfig": "0.0.0"
   },
   "peerDependencies": {
@@ -54,12 +53,14 @@
     "node": ">=18"
   },
   "publishConfig": {
-    "access": "public"
+    "access": "public",
+    "provenance": true
   },
   "homepage": "https://ai-sdk.dev/docs",
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/vercel/ai.git"
+    "url": "https://github.com/vercel/ai",
+    "directory": "packages/openai"
   },
   "bugs": {
     "url": "https://github.com/vercel/ai/issues"
@@ -71,9 +72,7 @@
     "build": "pnpm clean && tsup --tsconfig tsconfig.build.json",
     "build:watch": "pnpm clean && tsup --watch",
     "clean": "del-cli dist docs *.tsbuildinfo",
-    "lint": "eslint \"./**/*.ts*\"",
     "type-check": "tsc --build",
-    "prettier-check": "prettier --check \"./**/*.ts*\"",
     "test": "pnpm test:node && pnpm test:edge",
     "test:update": "pnpm test:node -u",
     "test:watch": "vitest --config vitest.node.config.js",

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

@@ -1,4 +1,4 @@
-import { LanguageModelV3Usage } from '@ai-sdk/provider';
+import type { LanguageModelV4Usage } from '@ai-sdk/provider';
 
 export type OpenAIChatUsage = {
   prompt_tokens?: number | null;
@@ -16,7 +16,7 @@ export type OpenAIChatUsage = {
 
 export function convertOpenAIChatUsage(
   usage: OpenAIChatUsage | undefined | null,
-): LanguageModelV3Usage {
+): LanguageModelV4Usage {
   if (usage == null) {
     return {
       inputTokens: {