@ai-sdk/openai 3.0.13 → 3.0.15

package/src/tool/mcp.ts

@@ -0,0 +1,125 @@
+import {
+  createProviderToolFactoryWithOutputSchema,
+  lazySchema,
+  zodSchema,
+} from '@ai-sdk/provider-utils';
+import { JSONValue } from '@ai-sdk/provider';
+import { z } from 'zod/v4';
+
+const jsonValueSchema: z.ZodType<JSONValue> = z.lazy(() =>
+  z.union([
+    z.string(),
+    z.number(),
+    z.boolean(),
+    z.null(),
+    z.array(jsonValueSchema),
+    z.record(z.string(), jsonValueSchema),
+  ]),
+);
+
+export const mcpArgsSchema = lazySchema(() =>
+  zodSchema(
+    z
+      .object({
+        serverLabel: z.string(),
+        allowedTools: z
+          .union([
+            z.array(z.string()),
+            z.object({
+              readOnly: z.boolean().optional(),
+              toolNames: z.array(z.string()).optional(),
+            }),
+          ])
+          .optional(),
+        authorization: z.string().optional(),
+        connectorId: z.string().optional(),
+        headers: z.record(z.string(), z.string()).optional(),
+
+        requireApproval: z
+          .union([
+            z.enum(['always', 'never']),
+            z.object({
+              never: z
+                .object({
+                  toolNames: z.array(z.string()).optional(),
+                })
+                .optional(),
+            }),
+          ])
+          .optional(),
+        serverDescription: z.string().optional(),
+        serverUrl: z.string().optional(),
+      })
+      .refine(
+        v => v.serverUrl != null || v.connectorId != null,
+        'One of serverUrl or connectorId must be provided.',
+      ),
+  ),
+);
+
+const mcpInputSchema = lazySchema(() => zodSchema(z.object({})));
+
+export const mcpOutputSchema = lazySchema(() =>
+  zodSchema(
+    z.object({
+      type: z.literal('call'),
+      serverLabel: z.string(),
+      name: z.string(),
+      arguments: z.string(),
+      output: z.string().nullish(),
+      error: z.union([z.string(), jsonValueSchema]).optional(),
+    }),
+  ),
+);
+
+type McpArgs = {
+  /** A label for this MCP server, used to identify it in tool calls. */
+  serverLabel: string;
+  /** List of allowed tool names or a filter object. */
+  allowedTools?:
+    | string[]
+    | {
+        readOnly?: boolean;
+        toolNames?: string[];
+      };
+  /** OAuth access token usable with the remote MCP server or connector. */
+  authorization?: string;
+  /** Identifier for a service connector. */
+  connectorId?: string;
+  /** Optional HTTP headers to send to the MCP server. */
+  headers?: Record<string, string>;
+  /**
+   * Which tools require approval before execution.
+   */
+  requireApproval?:
+    | 'always'
+    | 'never'
+    | {
+        never?: {
+          toolNames?: string[];
+        };
+      };
+  /** Optional description of the MCP server. */
+  serverDescription?: string;
+  /** URL for the MCP server. One of serverUrl or connectorId must be provided. */
+  serverUrl?: string;
+};
+
+export const mcpToolFactory = createProviderToolFactoryWithOutputSchema<
+  {},
+  {
+    type: 'call';
+    serverLabel: string;
+    name: string;
+    arguments: string;
+    output?: string | null;
+    error?: JSONValue;
+  },
+  McpArgs
+>({
+  id: 'openai.mcp',
+  inputSchema: mcpInputSchema,
+  outputSchema: mcpOutputSchema,
+});
+
+export const mcp = (args: McpArgs) => mcpToolFactory(args);

package/src/tool/shell.ts

@@ -0,0 +1,85 @@
+import {
+  createProviderToolFactoryWithOutputSchema,
+  lazySchema,
+  zodSchema,
+} from '@ai-sdk/provider-utils';
+import { z } from 'zod/v4';
+
+export const shellInputSchema = lazySchema(() =>
+  zodSchema(
+    z.object({
+      action: z.object({
+        commands: z.array(z.string()),
+        timeoutMs: z.number().optional(),
+        maxOutputLength: z.number().optional(),
+      }),
+    }),
+  ),
+);
+
+export const shellOutputSchema = lazySchema(() =>
+  zodSchema(
+    z.object({
+      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'), exitCode: z.number() }),
+          ]),
+        }),
+      ),
+    }),
+  ),
+);
+
+export const shell = createProviderToolFactoryWithOutputSchema<
+  {
+    /**
+     * Shell tool action containing commands to execute.
+     */
+    action: {
+      /**
+       * A list of shell commands to execute.
+       */
+      commands: string[];
+
+      /**
+       * Optional timeout in milliseconds for the commands.
+       */
+      timeoutMs?: number;
+
+      /**
+       * Optional maximum number of characters to return from each command.
+       */
+      maxOutputLength?: number;
+    };
+  },
+  {
+    /**
+     * An array of shell call output contents.
+     */
+    output: Array<{
+      /**
+       * Standard output from the command.
+       */
+      stdout: string;
+
+      /**
+       * Standard error from the command.
+       */
+      stderr: string;
+
+      /**
+       * The outcome of the shell execution - either timeout or exit with code.
+       */
+      outcome: { type: 'timeout' } | { type: 'exit'; exitCode: number };
+    }>;
+  },
+  {}
+>({
+  id: 'openai.shell',
+  inputSchema: shellInputSchema,
+  outputSchema: shellOutputSchema,
+});

package/src/tool/web-search-preview.ts

@@ -0,0 +1,139 @@
+import {
+  createProviderToolFactoryWithOutputSchema,
+  lazySchema,
+  zodSchema,
+} from '@ai-sdk/provider-utils';
+import { z } from 'zod/v4';
+
+export const webSearchPreviewArgsSchema = lazySchema(() =>
+  zodSchema(
+    z.object({
+      searchContextSize: z.enum(['low', 'medium', 'high']).optional(),
+      userLocation: z
+        .object({
+          type: z.literal('approximate'),
+          country: z.string().optional(),
+          city: z.string().optional(),
+          region: z.string().optional(),
+          timezone: z.string().optional(),
+        })
+        .optional(),
+    }),
+  ),
+);
+
+export const webSearchPreviewInputSchema = lazySchema(() =>
+  zodSchema(z.object({})),
+);
+
+const webSearchPreviewOutputSchema = lazySchema(() =>
+  zodSchema(
+    z.object({
+      action: z.discriminatedUnion('type', [
+        z.object({
+          type: z.literal('search'),
+          query: z.string().optional(),
+        }),
+        z.object({
+          type: z.literal('openPage'),
+          url: z.string().nullish(),
+        }),
+        z.object({
+          type: z.literal('findInPage'),
+          url: z.string().nullish(),
+          pattern: z.string().nullish(),
+        }),
+      ]),
+    }),
+  ),
+);
+
+export const webSearchPreview = createProviderToolFactoryWithOutputSchema<
+  {
+    // Web search preview doesn't take input parameters - it's controlled by the prompt
+  },
+  {
+    /**
+     * An object describing the specific action taken in this web search call.
+     * Includes details on how the model used the web (search, open_page, find_in_page).
+     */
+    action:
+      | {
+          /**
+           * Action type "search" - Performs a web search query.
+           */
+          type: 'search';
+
+          /**
+           * The search query.
+           */
+          query?: string;
+        }
+      | {
+          /**
+           * Action type "openPage" - Opens a specific URL from search results.
+           */
+          type: 'openPage';
+
+          /**
+           * The URL opened by the model.
+           */
+          url?: string | null;
+        }
+      | {
+          /**
+           * Action type "findInPage": Searches for a pattern within a loaded page.
+           */
+          type: 'findInPage';
+
+          /**
+           * The URL of the page searched for the pattern.
+           */
+          url?: string | null;
+
+          /**
+           * The pattern or text to search for within the page.
+           */
+          pattern?: string | null;
+        };
+  },
+  {
+    /**
+     * Search context size to use for the web search.
+     * - high: Most comprehensive context, highest cost, slower response
+     * - medium: Balanced context, cost, and latency (default)
+     * - low: Least context, lowest cost, fastest response
+     */
+    searchContextSize?: 'low' | 'medium' | 'high';
+
+    /**
+     * User location information to provide geographically relevant search results.
+     */
+    userLocation?: {
+      /**
+       * Type of location (always 'approximate')
+       */
+      type: 'approximate';
+      /**
+       * Two-letter ISO country code (e.g., 'US', 'GB')
+       */
+      country?: string;
+      /**
+       * City name (free text, e.g., 'Minneapolis')
+       */
+      city?: string;
+      /**
+       * Region name (free text, e.g., 'Minnesota')
+       */
+      region?: string;
+      /**
+       * IANA timezone (e.g., 'America/Chicago')
+       */
+      timezone?: string;
+    };
+  }
+>({
+  id: 'openai.web_search_preview',
+  inputSchema: webSearchPreviewInputSchema,
+  outputSchema: webSearchPreviewOutputSchema,
+});

package/src/tool/web-search.test-d.ts

@@ -0,0 +1,13 @@
+import { InferSchema, Tool } from '@ai-sdk/provider-utils';
+import { describe, expectTypeOf, it } from 'vitest';
+import { webSearch, webSearchOutputSchema } from './web-search';
+
+describe('web-search tool type', () => {
+  it('should have Tool type', () => {
+    const webSearchTool = webSearch();
+
+    expectTypeOf(webSearchTool).toEqualTypeOf<
+      Tool<{}, InferSchema<typeof webSearchOutputSchema>>
+    >();
+  });
+});

package/src/tool/web-search.ts

@@ -0,0 +1,179 @@
+import {
+  createProviderToolFactoryWithOutputSchema,
+  lazySchema,
+  zodSchema,
+} from '@ai-sdk/provider-utils';
+import { z } from 'zod/v4';
+
+export const webSearchArgsSchema = lazySchema(() =>
+  zodSchema(
+    z.object({
+      externalWebAccess: z.boolean().optional(),
+      filters: z
+        .object({ allowedDomains: z.array(z.string()).optional() })
+        .optional(),
+      searchContextSize: z.enum(['low', 'medium', 'high']).optional(),
+      userLocation: z
+        .object({
+          type: z.literal('approximate'),
+          country: z.string().optional(),
+          city: z.string().optional(),
+          region: z.string().optional(),
+          timezone: z.string().optional(),
+        })
+        .optional(),
+    }),
+  ),
+);
+
+const webSearchInputSchema = lazySchema(() => zodSchema(z.object({})));
+
+export const webSearchOutputSchema = lazySchema(() =>
+  zodSchema(
+    z.object({
+      action: z.discriminatedUnion('type', [
+        z.object({
+          type: z.literal('search'),
+          query: z.string().optional(),
+        }),
+        z.object({
+          type: z.literal('openPage'),
+          url: z.string().nullish(),
+        }),
+        z.object({
+          type: z.literal('findInPage'),
+          url: z.string().nullish(),
+          pattern: z.string().nullish(),
+        }),
+      ]),
+      sources: z
+        .array(
+          z.discriminatedUnion('type', [
+            z.object({ type: z.literal('url'), url: z.string() }),
+            z.object({ type: z.literal('api'), name: z.string() }),
+          ]),
+        )
+        .optional(),
+    }),
+  ),
+);
+
+export const webSearchToolFactory = createProviderToolFactoryWithOutputSchema<
+  {
+    // Web search doesn't take input parameters - it's controlled by the prompt
+  },
+  {
+    /**
+     * An object describing the specific action taken in this web search call.
+     * Includes details on how the model used the web (search, open_page, find_in_page).
+     */
+    action:
+      | {
+          /**
+           * Action type "search" - Performs a web search query.
+           */
+          type: 'search';
+
+          /**
+           * The search query.
+           */
+          query?: string;
+        }
+      | {
+          /**
+           * Action type "openPage" - Opens a specific URL from search results.
+           */
+          type: 'openPage';
+
+          /**
+           * The URL opened by the model.
+           */
+          url?: string | null;
+        }
+      | {
+          /**
+           * Action type "findInPage": Searches for a pattern within a loaded page.
+           */
+          type: 'findInPage';
+
+          /**
+           * The URL of the page searched for the pattern.
+           */
+          url?: string | null;
+
+          /**
+           * The pattern or text to search for within the page.
+           */
+          pattern?: string | null;
+        };
+
+    /**
+     * Optional sources cited by the model for the web search call.
+     */
+    sources?: Array<
+      { type: 'url'; url: string } | { type: 'api'; name: string }
+    >;
+  },
+  {
+    /**
+     * Whether to use external web access for fetching live content.
+     * - true: Fetch live web content (default)
+     * - false: Use cached/indexed results
+     */
+    externalWebAccess?: boolean;
+
+    /**
+     * Filters for the search.
+     */
+    filters?: {
+      /**
+       * Allowed domains for the search.
+       * If not provided, all domains are allowed.
+       * Subdomains of the provided domains are allowed as well.
+       */
+      allowedDomains?: string[];
+    };
+
+    /**
+     * Search context size to use for the web search.
+     * - high: Most comprehensive context, highest cost, slower response
+     * - medium: Balanced context, cost, and latency (default)
+     * - low: Least context, lowest cost, fastest response
+     */
+    searchContextSize?: 'low' | 'medium' | 'high';
+
+    /**
+     * User location information to provide geographically relevant search results.
+     */
+    userLocation?: {
+      /**
+       * Type of location (always 'approximate')
+       */
+      type: 'approximate';
+      /**
+       * Two-letter ISO country code (e.g., 'US', 'GB')
+       */
+      country?: string;
+      /**
+       * City name (free text, e.g., 'Minneapolis')
+       */
+      city?: string;
+      /**
+       * Region name (free text, e.g., 'Minnesota')
+       */
+      region?: string;
+      /**
+       * IANA timezone (e.g., 'America/Chicago')
+       */
+      timezone?: string;
+    };
+  }
+>({
+  id: 'openai.web_search',
+  inputSchema: webSearchInputSchema,
+  outputSchema: webSearchOutputSchema,
+});
+
+export const webSearch = (
+  args: Parameters<typeof webSearchToolFactory>[0] = {}, // default
+) => webSearchToolFactory(args);

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

@@ -0,0 +1,37 @@
+import { lazySchema, zodSchema } from '@ai-sdk/provider-utils';
+import { z } from 'zod/v4';
+
+export const openaiTranscriptionResponseSchema = lazySchema(() =>
+  zodSchema(
+    z.object({
+      text: z.string(),
+      language: z.string().nullish(),
+      duration: z.number().nullish(),
+      words: z
+        .array(
+          z.object({
+            word: z.string(),
+            start: z.number(),
+            end: z.number(),
+          }),
+        )
+        .nullish(),
+      segments: z
+        .array(
+          z.object({
+            id: z.number(),
+            seek: z.number(),
+            start: z.number(),
+            end: z.number(),
+            text: z.string(),
+            tokens: z.array(z.number()),
+            temperature: z.number(),
+            avg_logprob: z.number(),
+            compression_ratio: z.number(),
+            no_speech_prob: z.number(),
+          }),
+        )
+        .nullish(),
+    }),
+  ),
+);