@ai-sdk/openai 3.0.28 → 3.0.30

package/docs/03-openai.mdx

@@ -708,8 +708,8 @@ const result = await generateText({
 
 #### Shell Tool
 
-The OpenAI Responses API supports the shell tool for GPT-5.1 models through the `openai.tools.shell` tool.
-The shell tool allows allows running bash commands and interacting with a command line.
+The OpenAI Responses API supports the shell tool through the `openai.tools.shell` tool.
+The shell tool allows running bash commands and interacting with a command line.
 The model proposes shell commands; your integration executes them and returns the outputs.
 
 <Note type="warning">
@@ -717,16 +717,18 @@ The model proposes shell commands; your integration executes them and returns th
   add strict allow-/deny-lists before forwarding a command to the system shell.
 </Note>
 
+The shell tool supports three environment modes that control where commands are executed:
+
+##### Local Execution (default)
+
+When no `environment` is specified (or `type: 'local'` is used), commands are executed locally via your `execute` callback:
+
 ```ts
 import { openai } from '@ai-sdk/openai';
 import { generateText } from 'ai';
-import { exec } from 'child_process';
-import { promisify } from 'util';
-
-const execAsync = promisify(exec);
 
 const result = await generateText({
-  model: openai('gpt-5.1'),
+  model: openai('gpt-5.2'),
   tools: {
     shell: openai.tools.shell({
       execute: async ({ action }) => {
@@ -739,12 +741,131 @@ const result = await generateText({
 });
 ```
 
-Your execute function must return an output array with results for each command:
+##### Hosted Container (auto)
+
+Set `environment.type` to `'containerAuto'` to run commands in an OpenAI-hosted container. No `execute` callback is needed — OpenAI handles execution server-side:
+
+```ts
+const result = await generateText({
+  model: openai('gpt-5.2'),
+  tools: {
+    shell: openai.tools.shell({
+      environment: {
+        type: 'containerAuto',
+        // optional configuration:
+        memoryLimit: '4g',
+        fileIds: ['file-abc123'],
+        networkPolicy: {
+          type: 'allowlist',
+          allowedDomains: ['example.com'],
+        },
+      },
+    }),
+  },
+  prompt: 'Install numpy and compute the eigenvalues of a 3x3 matrix.',
+});
+```
+
+The `containerAuto` environment supports:
+
+- **fileIds** _string[]_ - File IDs to make available in the container
+- **memoryLimit** _'1g' | '4g' | '16g' | '64g'_ - Memory limit for the container
+- **networkPolicy** - Network access policy:
+  - `{ type: 'disabled' }` — no network access
+  - `{ type: 'allowlist', allowedDomains: string[], domainSecrets?: Array<{ domain, name, value }> }` — allow specific domains with optional secrets
+
+##### Existing Container Reference
+
+Set `environment.type` to `'containerReference'` to use an existing container by ID:
+
+```ts
+const result = await generateText({
+  model: openai('gpt-5.2'),
+  tools: {
+    shell: openai.tools.shell({
+      environment: {
+        type: 'containerReference',
+        containerId: 'cntr_abc123',
+      },
+    }),
+  },
+  prompt: 'Check the status of running processes.',
+});
+```
+
+##### Execute Callback
+
+For local execution (default or `type: 'local'`), your execute function must return an output array with results for each command:
 
 - **stdout** _string_ - Standard output from the command
 - **stderr** _string_ - Standard error from the command
 - **outcome** - Either `{ type: 'timeout' }` or `{ type: 'exit', exitCode: number }`
 
+##### Skills
+
+[Skills](https://platform.openai.com/docs/guides/tools-skills) are versioned bundles of files with a `SKILL.md` manifest that extend the shell tool's capabilities. They can be attached to both `containerAuto` and `local` environments.
+
+**Container skills** support two formats — by reference (for skills uploaded to OpenAI) or inline (as a base64-encoded zip):
+
+```ts
+const result = await generateText({
+  model: openai('gpt-5.2'),
+  tools: {
+    shell: openai.tools.shell({
+      environment: {
+        type: 'containerAuto',
+        skills: [
+          // By reference:
+          { type: 'skillReference', skillId: 'skill_abc123' },
+          // Or inline:
+          {
+            type: 'inline',
+            name: 'my-skill',
+            description: 'What this skill does',
+            source: {
+              type: 'base64',
+              mediaType: 'application/zip',
+              data: readFileSync('./my-skill.zip').toString('base64'),
+            },
+          },
+        ],
+      },
+    }),
+  },
+  prompt: 'Use the skill to solve this problem.',
+});
+```
+
+**Local skills** point to a directory on disk containing a `SKILL.md` file:
+
+```ts
+const result = await generateText({
+  model: openai('gpt-5.2'),
+  tools: {
+    shell: openai.tools.shell({
+      execute: async ({ action }) => {
+        // ... your local execution implementation ...
+        return { output: results };
+      },
+      environment: {
+        type: 'local',
+        skills: [
+          {
+            name: 'my-skill',
+            description: 'What this skill does',
+            path: resolve('path/to/skill-directory'),
+          },
+        ],
+      },
+    }),
+  },
+  prompt: 'Use the skill to solve this problem.',
+  stopWhen: stepCountIs(5),
+});
+```
+
+For more details on creating skills, see the [OpenAI Skills documentation](https://platform.openai.com/docs/guides/tools-skills).
+
 #### Apply Patch Tool
 
 The OpenAI Responses API supports the apply patch tool for GPT-5.1 models through the `openai.tools.applyPatch` tool.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ai-sdk/openai",
-  "version": "3.0.28",
+  "version": "3.0.30",
   "license": "Apache-2.0",
   "sideEffects": false,
   "main": "./dist/index.js",
@@ -44,8 +44,8 @@
     "tsup": "^8",
     "typescript": "5.8.3",
     "zod": "3.25.76",
-    "@ai-sdk/test-server": "1.0.3",
-    "@vercel/ai-tsconfig": "0.0.0"
+    "@vercel/ai-tsconfig": "0.0.0",
+    "@ai-sdk/test-server": "1.0.3"
   },
   "peerDependencies": {
     "zod": "^3.25.76 || ^4.1.8"

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

@@ -133,7 +133,7 @@ export class OpenAIImageModel implements ImageModelV3 {
         },
         providerMetadata: {
           openai: {
-            images: response.data.map(item => ({
+            images: response.data.map((item, index) => ({
               ...(item.revised_prompt
                 ? { revisedPrompt: item.revised_prompt }
                 : {}),
@@ -142,6 +142,11 @@ export class OpenAIImageModel implements ImageModelV3 {
               quality: response.quality ?? undefined,
               background: response.background ?? undefined,
               outputFormat: response.output_format ?? undefined,
+              ...distributeTokenDetails(
+                response.usage?.input_tokens_details,
+                index,
+                response.data.length,
+              ),
             })),
           },
         },
@@ -190,7 +195,7 @@ export class OpenAIImageModel implements ImageModelV3 {
       },
       providerMetadata: {
         openai: {
-          images: response.data.map(item => ({
+          images: response.data.map((item, index) => ({
             ...(item.revised_prompt
               ? { revisedPrompt: item.revised_prompt }
               : {}),
@@ -199,6 +204,11 @@ export class OpenAIImageModel implements ImageModelV3 {
             quality: response.quality ?? undefined,
             background: response.background ?? undefined,
             outputFormat: response.output_format ?? undefined,
+            ...distributeTokenDetails(
+              response.usage?.input_tokens_details,
+              index,
+              response.data.length,
+            ),
           })),
         },
       },
@@ -206,6 +216,40 @@ export class OpenAIImageModel implements ImageModelV3 {
   }
 }
 
+/**
+ * Distributes input token details evenly across images, with the remainder
+ * assigned to the last image so that summing across all entries gives the
+ * exact total.
+ */
+function distributeTokenDetails(
+  details:
+    | { image_tokens?: number | null; text_tokens?: number | null }
+    | null
+    | undefined,
+  index: number,
+  total: number,
+): { imageTokens?: number; textTokens?: number } {
+  if (details == null) {
+    return {};
+  }
+
+  const result: { imageTokens?: number; textTokens?: number } = {};
+
+  if (details.image_tokens != null) {
+    const base = Math.floor(details.image_tokens / total);
+    const remainder = details.image_tokens - base * (total - 1);
+    result.imageTokens = index === total - 1 ? remainder : base;
+  }
+
+  if (details.text_tokens != null) {
+    const base = Math.floor(details.text_tokens / total);
+    const remainder = details.text_tokens - base * (total - 1);
+    result.textTokens = index === total - 1 ? remainder : base;
+  }
+
+  return result;
+}
+
 type OpenAIImageEditInput = {
   /**
    * Allows to set transparency for the background of the generated image(s).

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

@@ -302,16 +302,49 @@ export async function convertToOpenAIResponsesInput({
                 break;
               }
 
+              const resolvedResultToolName = toolNameMapping.toProviderToolName(
+                part.toolName,
+              );
+
+              /*
+               * Shell tool results are separate output items (shell_call_output)
+               * with their own item IDs distinct from the shell_call's item ID.
+               * Since the pipeline only preserves the shell_call's item ID in
+               * callProviderMetadata, we reconstruct the full shell_call_output
+               * instead of using an item_reference with the wrong ID.
+               */
+              if (hasShellTool && resolvedResultToolName === 'shell') {
+                if (part.output.type === 'json') {
+                  const parsedOutput = await validateTypes({
+                    value: part.output.value,
+                    schema: shellOutputSchema,
+                  });
+                  input.push({
+                    type: 'shell_call_output',
+                    call_id: part.toolCallId,
+                    output: parsedOutput.output.map(item => ({
+                      stdout: item.stdout,
+                      stderr: item.stderr,
+                      outcome:
+                        item.outcome.type === 'timeout'
+                          ? { type: 'timeout' as const }
+                          : {
+                              type: 'exit' as const,
+                              exit_code: item.outcome.exitCode,
+                            },
+                    })),
+                  });
+                }
+                break;
+              }
+
               if (store) {
                 const itemId =
                   (
-                    part as {
-                      providerMetadata?: {
-                        [providerOptionsName]?: { itemId?: string };
-                      };
-                    }
-                  ).providerMetadata?.[providerOptionsName]?.itemId ??
-                  part.toolCallId;
+                    part.providerOptions?.[providerOptionsName] as
+                      | { itemId?: string }
+                      | undefined
+                  )?.itemId ?? part.toolCallId;
                 input.push({ type: 'item_reference', id: itemId });
               } else {
                 warnings.push({

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

@@ -142,8 +142,10 @@ export type OpenAIResponsesShellCall = {
 
 export type OpenAIResponsesShellCallOutput = {
   type: 'shell_call_output';
+  id?: string;
   call_id: string;
-  max_output_length?: number;
+  status?: 'in_progress' | 'completed' | 'incomplete';
+  max_output_length?: number | null;
   output: Array<{
     stdout: string;
     stderr: string;
@@ -328,6 +330,52 @@ export type OpenAIResponsesTool =
     }
   | {
       type: 'shell';
+      environment?:
+        | {
+            type: 'container_auto';
+            file_ids?: string[];
+            memory_limit?: '1g' | '4g' | '16g' | '64g';
+            network_policy?:
+              | { type: 'disabled' }
+              | {
+                  type: 'allowlist';
+                  allowed_domains: string[];
+                  domain_secrets?: Array<{
+                    domain: string;
+                    name: string;
+                    value: string;
+                  }>;
+                };
+            skills?: Array<
+              | {
+                  type: 'skill_reference';
+                  skill_id: string;
+                  version?: string;
+                }
+              | {
+                  type: 'inline';
+                  name: string;
+                  description: string;
+                  source: {
+                    type: 'base64';
+                    media_type: 'application/zip';
+                    data: string;
+                  };
+                }
+            >;
+          }
+        | {
+            type: 'container_reference';
+            container_id: string;
+          }
+        | {
+            type: 'local';
+            skills?: Array<{
+              name: string;
+              description: string;
+              path: string;
+            }>;
+          };
     };
 
 export type OpenAIResponsesReasoning = {
@@ -486,6 +534,25 @@ export const openaiResponsesChunkSchema = lazySchema(() =>
               commands: z.array(z.string()),
             }),
           }),
+          z.object({
+            type: z.literal('shell_call_output'),
+            id: z.string(),
+            call_id: z.string(),
+            status: z.enum(['in_progress', 'completed', 'incomplete']),
+            output: z.array(
+              z.object({
+                stdout: z.string(),
+                stderr: z.string(),
+                outcome: z.discriminatedUnion('type', [
+                  z.object({ type: z.literal('timeout') }),
+                  z.object({
+                    type: z.literal('exit'),
+                    exit_code: z.number(),
+                  }),
+                ]),
+              }),
+            ),
+          }),
         ]),
       }),
       z.object({
@@ -679,6 +746,25 @@ export const openaiResponsesChunkSchema = lazySchema(() =>
               commands: z.array(z.string()),
             }),
           }),
+          z.object({
+            type: z.literal('shell_call_output'),
+            id: z.string(),
+            call_id: z.string(),
+            status: z.enum(['in_progress', 'completed', 'incomplete']),
+            output: z.array(
+              z.object({
+                stdout: z.string(),
+                stderr: z.string(),
+                outcome: z.discriminatedUnion('type', [
+                  z.object({ type: z.literal('timeout') }),
+                  z.object({
+                    type: z.literal('exit'),
+                    exit_code: z.number(),
+                  }),
+                ]),
+              }),
+            ),
+          }),
         ]),
       }),
       z.object({
@@ -1064,6 +1150,25 @@ export const openaiResponsesResponseSchema = lazySchema(() =>
                 commands: z.array(z.string()),
               }),
             }),
+            z.object({
+              type: z.literal('shell_call_output'),
+              id: z.string(),
+              call_id: z.string(),
+              status: z.enum(['in_progress', 'completed', 'incomplete']),
+              output: z.array(
+                z.object({
+                  stdout: z.string(),
+                  stderr: z.string(),
+                  outcome: z.discriminatedUnion('type', [
+                    z.object({ type: z.literal('timeout') }),
+                    z.object({
+                      type: z.literal('exit'),
+                      exit_code: z.number(),
+                    }),
+                  ]),
+                }),
+              ),
+            }),
           ]),
         )
         .optional(),

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

@@ -37,7 +37,7 @@ import { fileSearchOutputSchema } from '../tool/file-search';
 import { imageGenerationOutputSchema } from '../tool/image-generation';
 import { localShellInputSchema } from '../tool/local-shell';
 import { mcpOutputSchema } from '../tool/mcp';
-import { shellInputSchema } from '../tool/shell';
+import { shellInputSchema, shellOutputSchema } from '../tool/shell';
 import { webSearchOutputSchema } from '../tool/web-search';
 import {
   convertOpenAIResponsesUsage,
@@ -417,6 +417,16 @@ export class OpenAIResponsesLanguageModel implements LanguageModelV3 {
       toolChoice,
     });
 
+    const shellToolEnvType = (
+      tools?.find(
+        tool => tool.type === 'provider' && tool.id === 'openai.shell',
+      ) as { args?: { environment?: { type?: string } } } | undefined
+    )?.args?.environment?.type;
+
+    const isShellProviderExecuted =
+      shellToolEnvType === 'containerAuto' ||
+      shellToolEnvType === 'containerReference';
+
     return {
       webSearchToolName,
       args: {
@@ -428,6 +438,7 @@ export class OpenAIResponsesLanguageModel implements LanguageModelV3 {
       store,
       toolNameMapping,
       providerOptionsName,
+      isShellProviderExecuted,
     };
   }
 
@@ -440,6 +451,7 @@ export class OpenAIResponsesLanguageModel implements LanguageModelV3 {
       webSearchToolName,
       toolNameMapping,
       providerOptionsName,
+      isShellProviderExecuted,
     } = await this.getArgs(options);
     const url = this.config.url({
       path: '/responses',
@@ -556,6 +568,7 @@ export class OpenAIResponsesLanguageModel implements LanguageModelV3 {
                 commands: part.action.commands,
               },
             } satisfies InferSchema<typeof shellInputSchema>),
+            ...(isShellProviderExecuted && { providerExecuted: true }),
             providerMetadata: {
               [providerOptionsName]: {
                 itemId: part.id,
@@ -566,6 +579,28 @@ export class OpenAIResponsesLanguageModel implements LanguageModelV3 {
           break;
         }
 
+        case 'shell_call_output': {
+          content.push({
+            type: 'tool-result',
+            toolCallId: part.call_id,
+            toolName: toolNameMapping.toCustomToolName('shell'),
+            result: {
+              output: part.output.map(item => ({
+                stdout: item.stdout,
+                stderr: item.stderr,
+                outcome:
+                  item.outcome.type === 'exit'
+                    ? {
+                        type: 'exit' as const,
+                        exitCode: item.outcome.exit_code,
+                      }
+                    : { type: 'timeout' as const },
+              })),
+            } satisfies InferSchema<typeof shellOutputSchema>,
+          });
+          break;
+        }
+
         case 'message': {
           for (const contentPart of part.content) {
             if (
@@ -910,6 +945,7 @@ export class OpenAIResponsesLanguageModel implements LanguageModelV3 {
       toolNameMapping,
       store,
       providerOptionsName,
+      isShellProviderExecuted,
     } = await this.getArgs(options);
 
     const { responseHeaders, value: response } = await postJsonToApi({
@@ -1160,6 +1196,8 @@ export class OpenAIResponsesLanguageModel implements LanguageModelV3 {
                   toolName: toolNameMapping.toCustomToolName('shell'),
                   toolCallId: value.item.call_id,
                 };
+              } else if (value.item.type === 'shell_call_output') {
+                // shell_call_output is handled in output_item.done
               } else if (value.item.type === 'message') {
                 ongoingAnnotations.splice(0, ongoingAnnotations.length);
                 controller.enqueue({
@@ -1469,10 +1507,40 @@ export class OpenAIResponsesLanguageModel implements LanguageModelV3 {
                       commands: value.item.action.commands,
                     },
                   } satisfies InferSchema<typeof shellInputSchema>),
+                  ...(isShellProviderExecuted && {
+                    providerExecuted: true,
+                  }),
                   providerMetadata: {
                     [providerOptionsName]: { itemId: value.item.id },
                   },
                 });
+              } else if (value.item.type === 'shell_call_output') {
+                controller.enqueue({
+                  type: 'tool-result',
+                  toolCallId: value.item.call_id,
+                  toolName: toolNameMapping.toCustomToolName('shell'),
+                  result: {
+                    output: value.item.output.map(
+                      (item: {
+                        stdout: string;
+                        stderr: string;
+                        outcome:
+                          | { type: 'exit'; exit_code: number }
+                          | { type: 'timeout' };
+                      }) => ({
+                        stdout: item.stdout,
+                        stderr: item.stderr,
+                        outcome:
+                          item.outcome.type === 'exit'
+                            ? {
+                                type: 'exit' as const,
+                                exitCode: item.outcome.exit_code,
+                              }
+                            : { type: 'timeout' as const },
+                      }),
+                    ),
+                  } satisfies InferSchema<typeof shellOutputSchema>,
+                });
               } else if (value.item.type === 'reasoning') {
                 const activeReasoningPart = activeReasoning[value.item.id];