@effect/ai-openai 4.0.0-beta.1 → 4.0.0-beta.100

package/dist/OpenAiTool.d.ts

@@ -1,29 +1,34 @@
 /**
- * OpenAI provider-defined tools for use with the LanguageModel.
+ * The `OpenAiTool` module defines OpenAI provider tools for Effect AI language
+ * model requests. It exposes typed descriptors for tools such as Apply Patch,
+ * Code Interpreter, File Search, Image Generation, MCP, Web Search, and
+ * shell-like local tools, including their provider names, configuration
+ * arguments, call parameters, success schemas, and handler requirements.
  *
- * Provides tools that are natively supported by OpenAI's API, including
- * code interpreter, file search, and web search functionality.
- *
- * @since 1.0.0
+ * @since 4.0.0
  */
 import * as Schema from "effect/Schema";
 import * as Tool from "effect/unstable/ai/Tool";
 /**
  * Union of all OpenAI provider-defined tools.
  *
- * @since 1.0.0
  * @category models
+ * @since 4.0.0
  */
 export type OpenAiTool = ReturnType<typeof ApplyPatch> | ReturnType<typeof CodeInterpreter> | ReturnType<typeof FileSearch> | ReturnType<typeof Shell> | ReturnType<typeof ImageGeneration> | ReturnType<typeof LocalShell> | ReturnType<typeof Mcp> | ReturnType<typeof WebSearch> | ReturnType<typeof WebSearchPreview>;
 /**
- * OpenAI Apply Patch tool.
+ * Defines the OpenAI Apply Patch tool that allows the model to apply diffs by creating,
+ * deleting, or updating files. This local tool runs in your environment and
+ * requires a handler to execute file operations.
+ *
+ * **When to use**
  *
- * Allows the model to apply diffs by creating, deleting, or updating files.
- * This is a local tool that runs in your environment and requires a handler
- * to execute file operations.
+ * Use when you want an OpenAI model to request structured file edits as create,
+ * delete, or update operations that your application executes through a local
+ * handler.
  *
- * @since 1.0.0
  * @category tools
+ * @since 4.0.0
  */
 export declare const ApplyPatch: <Mode extends Tool.FailureMode | undefined = undefined>(args: {
     readonly failureMode?: Mode | undefined;
@@ -52,42 +57,51 @@ export declare const ApplyPatch: <Mode extends Tool.FailureMode | undefined = un
     readonly failureMode: Mode extends undefined ? "error" : Mode;
 }, true>;
 /**
- * OpenAI Code Interpreter tool.
+ * Defines the OpenAI Code Interpreter tool that allows the model to execute Python code in
+ * a sandboxed environment.
+ *
+ * **When to use**
+ *
+ * Use to enable OpenAI-hosted Python execution for a model response.
  *
- * Allows the model to execute Python code in a sandboxed environment.
+ * **Details**
+ *
+ * The tool is configured with a `container` argument. Successful tool calls
+ * expose `outputs`, which may contain logs or generated images, or `null` when
+ * no outputs are available.
  *
- * @since 1.0.0
  * @category tools
+ * @since 4.0.0
  */
 export declare const CodeInterpreter: <Mode extends Tool.FailureMode | undefined = undefined>(args: {
     readonly container: string | {
         readonly type: "auto";
-        readonly memory_limit?: "1g" | "4g" | "16g" | "64g" | null;
-        readonly network_policy?: {
-            readonly type: "disabled";
-        } | {
+        readonly file_ids?: readonly string[];
+        readonly memory_limit?: "16g" | "1g" | "4g" | "64g" | null;
+        readonly network_policy?: Schema.Struct.ReadonlySide<{
+            readonly type: Schema.Literal<"disabled">;
+        }, "Encoded"> | {
             readonly type: "allowlist";
             readonly allowed_domains: readonly string[];
-            readonly domain_secrets?: readonly {
-                readonly value: string;
-                readonly name: string;
-                readonly domain: string;
-            }[];
+            readonly domain_secrets?: readonly Schema.Struct.ReadonlySide<{
+                readonly domain: Schema.String;
+                readonly name: Schema.String;
+                readonly value: Schema.String;
+            }, "Encoded">[];
         };
-        readonly file_ids?: readonly string[];
     };
 }) => Tool.ProviderDefined<"openai.code_interpreter", "OpenAiCodeInterpreter", {
     readonly args: Schema.Struct<{
         readonly container: Schema.Union<readonly [Schema.String, Schema.Struct<{
             readonly type: Schema.Literal<"auto">;
-            readonly file_ids: Schema.optionalKey<Schema.Array$<Schema.String>>;
+            readonly file_ids: Schema.optionalKey<Schema.$Array<Schema.String>>;
             readonly memory_limit: Schema.optionalKey<Schema.Union<readonly [Schema.Literals<readonly ["1g", "4g", "16g", "64g"]>, Schema.Null]>>;
             readonly network_policy: Schema.optionalKey<Schema.Union<readonly [Schema.Struct<{
                 readonly type: Schema.Literal<"disabled">;
             }>, Schema.Struct<{
                 readonly type: Schema.Literal<"allowlist">;
-                readonly allowed_domains: Schema.Array$<Schema.String>;
-                readonly domain_secrets: Schema.optionalKey<Schema.Array$<Schema.Struct<{
+                readonly allowed_domains: Schema.$Array<Schema.String>;
+                readonly domain_secrets: Schema.optionalKey<Schema.$Array<Schema.Struct<{
                     readonly domain: Schema.String;
                     readonly name: Schema.String;
                     readonly value: Schema.String;
@@ -100,7 +114,7 @@ export declare const CodeInterpreter: <Mode extends Tool.FailureMode | undefined
         readonly container_id: Schema.String;
     }>;
     readonly success: Schema.Struct<{
-        readonly outputs: Schema.Union<readonly [Schema.Array$<Schema.Union<readonly [Schema.Struct<{
+        readonly outputs: Schema.Union<readonly [Schema.$Array<Schema.Union<readonly [Schema.Struct<{
             readonly type: Schema.Literal<"logs">;
             readonly logs: Schema.String;
         }>, Schema.Struct<{
@@ -112,44 +126,58 @@ export declare const CodeInterpreter: <Mode extends Tool.FailureMode | undefined
     readonly failureMode: Mode extends undefined ? "error" : Mode;
 }, false>;
 /**
- * OpenAI File Search tool.
+ * Defines the OpenAI File Search tool that enables the model to search through uploaded
+ * files and vector stores.
+ *
+ * **When to use**
  *
- * Enables the model to search through uploaded files and vector stores.
+ * Use to let an OpenAI model search uploaded files through one or more vector
+ * stores.
+ *
+ * **Details**
+ *
+ * The tool requires `vector_store_ids` and accepts optional `filters`,
+ * `max_num_results`, and `ranking_options`. Successful tool calls expose the
+ * search `status`, generated `queries`, and optional `results`.
  *
- * @since 1.0.0
  * @category tools
+ * @since 4.0.0
  */
 export declare const FileSearch: <Mode extends Tool.FailureMode | undefined = undefined>(args: {
-    readonly vector_store_ids: readonly string[];
-    readonly filters?: {
-        readonly value: string | number | boolean | readonly (string | number)[];
-        readonly type: "eq" | "ne" | "gt" | "gte" | "lt" | "lte";
-        readonly key: string;
-    } | {
-        readonly type: "and" | "or";
-        readonly filters: readonly unknown[];
-    } | null;
+    readonly filters?: Schema.Struct.ReadonlySide<{
+        readonly type: Schema.Literals<readonly ["eq", "ne", "gt", "gte", "lt", "lte", "in", "nin"]>;
+        readonly key: Schema.String;
+        readonly value: Schema.Union<readonly [Schema.String, Schema.Number, Schema.Boolean, Schema.$Array<Schema.Union<readonly [Schema.String, Schema.Number]>>]>;
+    }, "Encoded"> | Schema.Struct.ReadonlySide<{
+        readonly type: Schema.Literals<readonly ["and", "or"]>;
+        readonly filters: Schema.$Array<Schema.Union<readonly [Schema.Struct<{
+            readonly type: Schema.Literals<readonly ["eq", "ne", "gt", "gte", "lt", "lte", "in", "nin"]>;
+            readonly key: Schema.String;
+            readonly value: Schema.Union<readonly [Schema.String, Schema.Number, Schema.Boolean, Schema.$Array<Schema.Union<readonly [Schema.String, Schema.Number]>>]>;
+        }>, Schema.Unknown]>>;
+    }, "Encoded"> | null;
     readonly max_num_results?: number;
     readonly ranking_options?: {
         readonly ranker?: "auto" | "default-2024-11-15";
         readonly score_threshold?: number;
-        readonly hybrid_search?: {
-            readonly embedding_weight: number;
-            readonly text_weight: number;
-        };
+        readonly hybrid_search?: Schema.Struct.ReadonlySide<{
+            readonly embedding_weight: Schema.Number;
+            readonly text_weight: Schema.Number;
+        }, "Encoded">;
     };
+    readonly vector_store_ids: readonly string[];
 }) => Tool.ProviderDefined<"openai.file_search", "OpenAiFileSearch", {
     readonly args: Schema.Struct<{
         readonly filters: Schema.optionalKey<Schema.Union<readonly [Schema.Union<readonly [Schema.Struct<{
-            readonly type: Schema.Literals<readonly ["eq", "ne", "gt", "gte", "lt", "lte"]>;
+            readonly type: Schema.Literals<readonly ["eq", "ne", "gt", "gte", "lt", "lte", "in", "nin"]>;
             readonly key: Schema.String;
-            readonly value: Schema.Union<readonly [Schema.String, Schema.Number, Schema.Boolean, Schema.Array$<Schema.Union<readonly [Schema.String, Schema.Number]>>]>;
+            readonly value: Schema.Union<readonly [Schema.String, Schema.Number, Schema.Boolean, Schema.$Array<Schema.Union<readonly [Schema.String, Schema.Number]>>]>;
         }>, Schema.Struct<{
             readonly type: Schema.Literals<readonly ["and", "or"]>;
-            readonly filters: Schema.Array$<Schema.Union<readonly [Schema.Struct<{
-                readonly type: Schema.Literals<readonly ["eq", "ne", "gt", "gte", "lt", "lte"]>;
+            readonly filters: Schema.$Array<Schema.Union<readonly [Schema.Struct<{
+                readonly type: Schema.Literals<readonly ["eq", "ne", "gt", "gte", "lt", "lte", "in", "nin"]>;
                 readonly key: Schema.String;
-                readonly value: Schema.Union<readonly [Schema.String, Schema.Number, Schema.Boolean, Schema.Array$<Schema.Union<readonly [Schema.String, Schema.Number]>>]>;
+                readonly value: Schema.Union<readonly [Schema.String, Schema.Number, Schema.Boolean, Schema.$Array<Schema.Union<readonly [Schema.String, Schema.Number]>>]>;
             }>, Schema.Unknown]>>;
         }>]>, Schema.Null]>>;
         readonly max_num_results: Schema.optionalKey<Schema.Number>;
@@ -161,13 +189,13 @@ export declare const FileSearch: <Mode extends Tool.FailureMode | undefined = un
                 readonly text_weight: Schema.Number;
             }>>;
         }>>;
-        readonly vector_store_ids: Schema.Array$<Schema.String>;
+        readonly vector_store_ids: Schema.$Array<Schema.String>;
     }>;
     readonly parameters: Schema.Void;
     readonly success: Schema.Struct<{
         readonly status: Schema.Literals<readonly ["in_progress", "searching", "completed", "incomplete", "failed"]>;
-        readonly queries: Schema.Array$<Schema.String>;
-        readonly results: Schema.optionalKey<Schema.Union<readonly [Schema.Array$<Schema.Struct<{
+        readonly queries: Schema.$Array<Schema.String>;
+        readonly results: Schema.optionalKey<Schema.Union<readonly [Schema.$Array<Schema.Struct<{
             readonly file_id: Schema.optionalKey<Schema.String>;
             readonly text: Schema.optionalKey<Schema.String>;
             readonly filename: Schema.optionalKey<Schema.String>;
@@ -179,27 +207,38 @@ export declare const FileSearch: <Mode extends Tool.FailureMode | undefined = un
     readonly failureMode: Mode extends undefined ? "error" : Mode;
 }, false>;
 /**
- * OpenAI Image Generation tool.
+ * Defines the OpenAI Image Generation tool that enables the model to generate images using
+ * the GPT image models.
  *
- * Enables the model to generate images using the GPT image models.
+ * **When to use**
+ *
+ * Use to enable OpenAI provider-defined image generation through a language
+ * model response.
+ *
+ * **Details**
+ *
+ * The tool configures the `image_generation` provider tool, including model,
+ * size, quality, output format, moderation, background, input-image options,
+ * and partial image settings. Successful tool calls expose `result` as base64
+ * image data or `null`.
  *
- * @since 1.0.0
  * @category tools
+ * @since 4.0.0
  */
 export declare const ImageGeneration: <Mode extends Tool.FailureMode | undefined = undefined>(args: {
-    readonly model?: string;
-    readonly size?: "auto" | "1024x1024" | "1024x1536" | "1536x1024";
-    readonly quality?: "auto" | "low" | "high" | "medium";
-    readonly background?: "auto" | "transparent" | "opaque";
-    readonly output_format?: "png" | "webp" | "jpeg";
-    readonly output_compression?: number;
-    readonly partial_images?: number;
-    readonly moderation?: "auto" | "low";
-    readonly input_fidelity?: "low" | "high" | null;
+    readonly background?: "auto" | "opaque" | "transparent";
+    readonly input_fidelity?: "high" | "low" | null;
     readonly input_image_mask?: {
-        readonly file_id?: string;
         readonly image_url?: string;
+        readonly file_id?: string;
     };
+    readonly model?: string;
+    readonly moderation?: "auto" | "low";
+    readonly output_compression?: number;
+    readonly output_format?: "jpeg" | "png" | "webp";
+    readonly partial_images?: number;
+    readonly quality?: "auto" | "high" | "low" | "medium";
+    readonly size?: string;
 }) => Tool.ProviderDefined<"openai.image_generation", "OpenAiImageGeneration", {
     readonly args: Schema.Struct<{
         readonly background: Schema.optionalKey<Schema.Literals<readonly ["transparent", "opaque", "auto"]>>;
@@ -214,7 +253,7 @@ export declare const ImageGeneration: <Mode extends Tool.FailureMode | undefined
         readonly output_format: Schema.optionalKey<Schema.Literals<readonly ["png", "webp", "jpeg"]>>;
         readonly partial_images: Schema.optionalKey<Schema.Number>;
         readonly quality: Schema.optionalKey<Schema.Literals<readonly ["low", "medium", "high", "auto"]>>;
-        readonly size: Schema.optionalKey<Schema.Literals<readonly ["1024x1024", "1024x1536", "1536x1024", "auto"]>>;
+        readonly size: Schema.optionalKey<Schema.Union<readonly [Schema.String, Schema.Literals<readonly ["1024x1024", "1024x1536", "1536x1024", "auto"]>]>>;
     }>;
     readonly parameters: Schema.Void;
     readonly success: Schema.Struct<{
@@ -224,13 +263,23 @@ export declare const ImageGeneration: <Mode extends Tool.FailureMode | undefined
     readonly failureMode: Mode extends undefined ? "error" : Mode;
 }, false>;
 /**
- * OpenAI Local Shell tool.
+ * Defines the OpenAI Local Shell tool that enables the model to run a command with a local
+ * shell. This local tool runs in your environment and requires a handler to
+ * execute commands.
+ *
+ * **When to use**
+ *
+ * Use to let an OpenAI model request local shell commands that your application
+ * executes through a handler.
+ *
+ * **Details**
  *
- * Enables the model to run a command with a local shell. This is a local tool
- * that runs in your environment and requires a handler to execute commands.
+ * The tool exposes a provider-defined `local_shell` call. It is marked as
+ * handler-required, so applications must provide the command execution policy
+ * and implementation.
  *
- * @since 1.0.0
  * @category tools
+ * @since 4.0.0
  */
 export declare const LocalShell: <Mode extends Tool.FailureMode | undefined = undefined>(args: {
     readonly failureMode?: Mode | undefined;
@@ -239,7 +288,7 @@ export declare const LocalShell: <Mode extends Tool.FailureMode | undefined = un
     readonly parameters: Schema.Struct<{
         readonly action: Schema.Struct<{
             readonly type: Schema.Literal<"exec">;
-            readonly command: Schema.Array$<Schema.String>;
+            readonly command: Schema.$Array<Schema.String>;
             readonly timeout_ms: Schema.optionalKey<Schema.Union<readonly [Schema.Number, Schema.Null]>>;
             readonly working_directory: Schema.optionalKey<Schema.Union<readonly [Schema.String, Schema.Null]>>;
             readonly env: Schema.Struct<{}>;
@@ -253,24 +302,35 @@ export declare const LocalShell: <Mode extends Tool.FailureMode | undefined = un
     readonly failureMode: Mode extends undefined ? "error" : Mode;
 }, true>;
 /**
- * OpenAI MCP tool.
+ * Defines the OpenAI MCP tool that gives the model access to additional tools via remote
+ * Model Context Protocol (MCP) servers.
  *
- * Gives the model access to additional tools via remote Model Context Protocol
- * (MCP) servers
+ * **When to use**
+ *
+ * Use to let an OpenAI model call tools exposed by a remote MCP server.
+ *
+ * **Details**
+ *
+ * The tool accepts MCP server configuration such as allowed tools,
+ * authorization, connector id, approval requirements, server metadata, and
+ * server URL. Tool call results include the called tool name, arguments, output,
+ * error, and server label.
+ *
+ * **Gotchas**
+ *
+ * This schema leaves both `server_url` and `connector_id` optional, but OpenAI
+ * may require a server URL or connector id for a usable MCP tool configuration.
  *
- * @since 1.0.0
  * @category tools
+ * @since 4.0.0
  */
 export declare const Mcp: <Mode extends Tool.FailureMode | undefined = undefined>(args: {
-    readonly server_label: string;
     readonly allowed_tools?: readonly string[] | {
         readonly tool_names?: readonly string[];
         readonly read_only?: boolean;
     } | null;
-    readonly server_url?: string;
-    readonly connector_id?: "connector_dropbox" | "connector_gmail" | "connector_googlecalendar" | "connector_googledrive" | "connector_microsoftteams" | "connector_outlookcalendar" | "connector_outlookemail" | "connector_sharepoint";
     readonly authorization?: string;
-    readonly server_description?: string;
+    readonly connector_id?: "connector_dropbox" | "connector_gmail" | "connector_googlecalendar" | "connector_googledrive" | "connector_microsoftteams" | "connector_outlookcalendar" | "connector_outlookemail" | "connector_sharepoint";
     readonly require_approval?: "always" | "never" | {
         readonly always?: {
             readonly tool_names?: readonly string[];
@@ -281,21 +341,24 @@ export declare const Mcp: <Mode extends Tool.FailureMode | undefined = undefined
             readonly read_only?: boolean;
         };
     } | null;
+    readonly server_description?: string;
+    readonly server_label: string;
+    readonly server_url?: string;
 }) => Tool.ProviderDefined<"openai.mcp", "OpenAiMcp", {
     readonly args: Schema.Struct<{
-        readonly allowed_tools: Schema.optionalKey<Schema.Union<readonly [Schema.Union<readonly [Schema.Array$<Schema.String>, Schema.Struct<{
-            readonly tool_names: Schema.optionalKey<Schema.Array$<Schema.String>>;
+        readonly allowed_tools: Schema.optionalKey<Schema.Union<readonly [Schema.Union<readonly [Schema.$Array<Schema.String>, Schema.Struct<{
+            readonly tool_names: Schema.optionalKey<Schema.$Array<Schema.String>>;
             readonly read_only: Schema.optionalKey<Schema.Boolean>;
         }>]>, Schema.Null]>>;
         readonly authorization: Schema.optionalKey<Schema.String>;
         readonly connector_id: Schema.optionalKey<Schema.Literals<readonly ["connector_dropbox", "connector_gmail", "connector_googlecalendar", "connector_googledrive", "connector_microsoftteams", "connector_outlookcalendar", "connector_outlookemail", "connector_sharepoint"]>>;
         readonly require_approval: Schema.optionalKey<Schema.Union<readonly [Schema.Union<readonly [Schema.Struct<{
             readonly always: Schema.optionalKey<Schema.Struct<{
-                readonly tool_names: Schema.optionalKey<Schema.Array$<Schema.String>>;
+                readonly tool_names: Schema.optionalKey<Schema.$Array<Schema.String>>;
                 readonly read_only: Schema.optionalKey<Schema.Boolean>;
             }>>;
             readonly never: Schema.optionalKey<Schema.Struct<{
-                readonly tool_names: Schema.optionalKey<Schema.Array$<Schema.String>>;
+                readonly tool_names: Schema.optionalKey<Schema.$Array<Schema.String>>;
                 readonly read_only: Schema.optionalKey<Schema.Boolean>;
             }>>;
         }>, Schema.Literals<readonly ["always", "never"]>]>, Schema.Null]>>;
@@ -303,7 +366,7 @@ export declare const Mcp: <Mode extends Tool.FailureMode | undefined = undefined
         readonly server_label: Schema.String;
         readonly server_url: Schema.optionalKey<Schema.String>;
     }>;
-    readonly parameters: Schema.Void;
+    readonly parameters: Schema.Unknown;
     readonly success: Schema.Struct<{
         readonly type: Schema.Literal<"mcp_call">;
         readonly name: Schema.String;
@@ -316,14 +379,21 @@ export declare const Mcp: <Mode extends Tool.FailureMode | undefined = undefined
     readonly failureMode: Mode extends undefined ? "error" : Mode;
 }, false>;
 /**
- * OpenAI Function Shell tool.
+ * Defines the OpenAI shell tool for model-requested command execution.
+ *
+ * **When to use**
+ *
+ * Use to let an OpenAI model request shell commands that your application
+ * executes through a handler.
  *
- * Enables the model to execute one or more shell commands in a managed
- * environment. This is a local tool that runs in your environment and requires
- * a handler to execute commands.
+ * **Details**
+ *
+ * The tool exposes a provider-defined `shell` call. It is marked as
+ * handler-required, so applications must provide the command execution policy
+ * and implementation.
  *
- * @since 1.0.0
  * @category tools
+ * @since 4.0.0
  */
 export declare const Shell: <Mode extends Tool.FailureMode | undefined = undefined>(args: {
     readonly failureMode?: Mode | undefined;
@@ -331,13 +401,13 @@ export declare const Shell: <Mode extends Tool.FailureMode | undefined = undefin
     readonly args: Schema.Void;
     readonly parameters: Schema.Struct<{
         readonly action: Schema.Struct<{
-            readonly commands: Schema.Array$<Schema.String>;
+            readonly commands: Schema.$Array<Schema.String>;
             readonly timeout_ms: Schema.Union<readonly [Schema.Number, Schema.Null]>;
             readonly max_output_length: Schema.Union<readonly [Schema.Number, Schema.Null]>;
         }>;
     }>;
     readonly success: Schema.Struct<{
-        readonly output: Schema.Array$<Schema.Struct<{
+        readonly output: Schema.$Array<Schema.Struct<{
             readonly stdout: Schema.String;
             readonly stderr: Schema.String;
             readonly outcome: Schema.Union<readonly [Schema.Struct<{
@@ -346,20 +416,34 @@ export declare const Shell: <Mode extends Tool.FailureMode | undefined = undefin
                 readonly type: Schema.Literal<"exit">;
                 readonly exit_code: Schema.Number;
             }>]>;
+            readonly created_by: Schema.optionalKey<Schema.String>;
         }>>;
     }>;
     readonly failure: Schema.Never;
     readonly failureMode: Mode extends undefined ? "error" : Mode;
 }, true>;
 /**
- * OpenAI Web Search tool.
+ * Defines the OpenAI Web Search tool that enables the model to search the web for
+ * information.
+ *
+ * **When to use**
+ *
+ * Use to enable OpenAI provider-defined web search for a model response.
+ *
+ * **Details**
  *
- * Enables the model to search the web for information.
+ * The tool accepts optional filters, user location, and search context size.
+ * Successful calls expose the performed search action and status.
+ *
+ * @see {@link WebSearchPreview} for the preview web search provider tool
  *
- * @since 1.0.0
  * @category tools
+ * @since 4.0.0
  */
 export declare const WebSearch: <Mode extends Tool.FailureMode | undefined = undefined>(args: {
+    readonly filters?: {
+        readonly allowed_domains?: readonly string[] | null;
+    } | null;
     readonly user_location?: {
         readonly type?: "approximate";
         readonly country?: string | null;
@@ -367,14 +451,11 @@ export declare const WebSearch: <Mode extends Tool.FailureMode | undefined = und
         readonly city?: string | null;
         readonly timezone?: string | null;
     } | null;
-    readonly search_context_size?: "low" | "high" | "medium";
-    readonly filters?: {
-        readonly allowed_domains?: readonly string[] | null;
-    } | null;
+    readonly search_context_size?: "high" | "low" | "medium";
 }) => Tool.ProviderDefined<"openai.web_search", "OpenAiWebSearch", {
     readonly args: Schema.Struct<{
         readonly filters: Schema.optionalKey<Schema.Union<readonly [Schema.Struct<{
-            readonly allowed_domains: Schema.optionalKey<Schema.Union<readonly [Schema.Array$<Schema.String>, Schema.Null]>>;
+            readonly allowed_domains: Schema.optionalKey<Schema.Union<readonly [Schema.$Array<Schema.String>, Schema.Null]>>;
         }>, Schema.Null]>>;
         readonly user_location: Schema.optionalKey<Schema.Union<readonly [Schema.Struct<{
             readonly type: Schema.optionalKey<Schema.Literal<"approximate">>;
@@ -389,8 +470,8 @@ export declare const WebSearch: <Mode extends Tool.FailureMode | undefined = und
         readonly action: Schema.Union<readonly [Schema.Struct<{
             readonly type: Schema.Literal<"search">;
             readonly query: Schema.optionalKey<Schema.String>;
-            readonly queries: Schema.optionalKey<Schema.Array$<Schema.String>>;
-            readonly sources: Schema.optionalKey<Schema.Array$<Schema.Struct<{
+            readonly queries: Schema.optionalKey<Schema.$Array<Schema.String>>;
+            readonly sources: Schema.optionalKey<Schema.$Array<Schema.Struct<{
                 readonly type: Schema.Literal<"url">;
                 readonly url: Schema.String;
             }>>>;
@@ -407,8 +488,8 @@ export declare const WebSearch: <Mode extends Tool.FailureMode | undefined = und
         readonly action: Schema.Union<readonly [Schema.Struct<{
             readonly type: Schema.Literal<"search">;
             readonly query: Schema.optionalKey<Schema.String>;
-            readonly queries: Schema.optionalKey<Schema.Array$<Schema.String>>;
-            readonly sources: Schema.optionalKey<Schema.Array$<Schema.Struct<{
+            readonly queries: Schema.optionalKey<Schema.$Array<Schema.String>>;
+            readonly sources: Schema.optionalKey<Schema.$Array<Schema.Struct<{
                 readonly type: Schema.Literal<"url">;
                 readonly url: Schema.String;
             }>>>;
@@ -426,12 +507,21 @@ export declare const WebSearch: <Mode extends Tool.FailureMode | undefined = und
     readonly failureMode: Mode extends undefined ? "error" : Mode;
 }, false>;
 /**
- * OpenAI Web Search Preview tool.
+ * Defines the OpenAI preview Web Search tool for model responses.
+ *
+ * **When to use**
+ *
+ * Use to enable the preview OpenAI web search provider tool.
+ *
+ * **Details**
+ *
+ * The preview tool accepts optional user location and search context size, then
+ * exposes the performed search action and status in successful calls.
  *
- * Preview version of the web search tool with additional features.
+ * @see {@link WebSearch} for the stable web search provider tool
  *
- * @since 1.0.0
  * @category tools
+ * @since 4.0.0
  */
 export declare const WebSearchPreview: <Mode extends Tool.FailureMode | undefined = undefined>(args: {
     readonly user_location?: {
@@ -441,7 +531,7 @@ export declare const WebSearchPreview: <Mode extends Tool.FailureMode | undefine
         readonly city?: string | null;
         readonly timezone?: string | null;
     } | null;
-    readonly search_context_size?: "low" | "high" | "medium";
+    readonly search_context_size?: "high" | "low" | "medium";
 }) => Tool.ProviderDefined<"openai.web_search_preview", "OpenAiWebSearchPreview", {
     readonly args: Schema.Struct<{
         readonly user_location: Schema.optionalKey<Schema.Union<readonly [Schema.Struct<{
@@ -458,8 +548,8 @@ export declare const WebSearchPreview: <Mode extends Tool.FailureMode | undefine
         readonly action: Schema.Union<readonly [Schema.Struct<{
             readonly type: Schema.Literal<"search">;
             readonly query: Schema.optionalKey<Schema.String>;
-            readonly queries: Schema.optionalKey<Schema.Array$<Schema.String>>;
-            readonly sources: Schema.optionalKey<Schema.Array$<Schema.Struct<{
+            readonly queries: Schema.optionalKey<Schema.$Array<Schema.String>>;
+            readonly sources: Schema.optionalKey<Schema.$Array<Schema.Struct<{
                 readonly type: Schema.Literal<"url">;
                 readonly url: Schema.String;
             }>>>;

package/dist/OpenAiTool.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"OpenAiTool.d.ts","sourceRoot":"","sources":["../src/OpenAiTool.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,OAAO,KAAK,MAAM,MAAM,eAAe,CAAA;AACvC,OAAO,KAAK,IAAI,MAAM,yBAAyB,CAAA;AAG/C;;;;;GAKG;AACH,MAAM,MAAM,UAAU,GAClB,UAAU,CAAC,OAAO,UAAU,CAAC,GAC7B,UAAU,CAAC,OAAO,eAAe,CAAC,GAClC,UAAU,CAAC,OAAO,UAAU,CAAC,GAC7B,UAAU,CAAC,OAAO,KAAK,CAAC,GACxB,UAAU,CAAC,OAAO,eAAe,CAAC,GAClC,UAAU,CAAC,OAAO,UAAU,CAAC,GAC7B,UAAU,CAAC,OAAO,GAAG,CAAC,GACtB,UAAU,CAAC,OAAO,SAAS,CAAC,GAC5B,UAAU,CAAC,OAAO,gBAAgB,CAAC,CAAA;AAEvC;;;;;;;;;GASG;AACH,eAAO,MAAM,UAAU;;;;;;;;;;;;;;;;;;;;;;;;;QAarB,CAAA;AAEF;;;;;;;GAOG;AACH,eAAO,MAAM,eAAe;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;SAc1B,CAAA;AAEF;;;;;;;GAOG;AACH,eAAO,MAAM,UAAU;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;SAerB,CAAA;AAEF;;;;;;;GAOG;AACH,eAAO,MAAM,eAAe;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;SAmB1B,CAAA;AAEF;;;;;;;;GAQG;AACH,eAAO,MAAM,UAAU;;;;;;;;;;;;;;;;;;;QAWrB,CAAA;AAEF;;;;;;;;GAQG;AACH,eAAO,MAAM,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;SAqBd,CAAA;AAEF;;;;;;;;;GASG;AACH,eAAO,MAAM,KAAK;;;;;;;;;;;;;;;;;;;;;;;;;QAWhB,CAAA;AAEF;;;;;;;GAOG;AACH,eAAO,MAAM,SAAS;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;SAgBpB,CAAA;AAEF;;;;;;;GAOG;AACH,eAAO,MAAM,gBAAgB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;SAY3B,CAAA"}
+{"version":3,"file":"OpenAiTool.d.ts","sourceRoot":"","sources":["../src/OpenAiTool.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AACH,OAAO,KAAK,MAAM,MAAM,eAAe,CAAA;AACvC,OAAO,KAAK,IAAI,MAAM,yBAAyB,CAAA;AAG/C;;;;;GAKG;AACH,MAAM,MAAM,UAAU,GAClB,UAAU,CAAC,OAAO,UAAU,CAAC,GAC7B,UAAU,CAAC,OAAO,eAAe,CAAC,GAClC,UAAU,CAAC,OAAO,UAAU,CAAC,GAC7B,UAAU,CAAC,OAAO,KAAK,CAAC,GACxB,UAAU,CAAC,OAAO,eAAe,CAAC,GAClC,UAAU,CAAC,OAAO,UAAU,CAAC,GAC7B,UAAU,CAAC,OAAO,GAAG,CAAC,GACtB,UAAU,CAAC,OAAO,SAAS,CAAC,GAC5B,UAAU,CAAC,OAAO,gBAAgB,CAAC,CAAA;AAEvC;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,UAAU;;;;;;;;;;;;;;;;;;;;;;;;;QAarB,CAAA;AAEF;;;;;;;;;;;;;;;;GAgBG;AACH,eAAO,MAAM,eAAe;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;SAc1B,CAAA;AAEF;;;;;;;;;;;;;;;;;GAiBG;AACH,eAAO,MAAM,UAAU;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;SAerB,CAAA;AAEF;;;;;;;;;;;;;;;;;;GAkBG;AACH,eAAO,MAAM,eAAe;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;SAmB1B,CAAA;AAEF;;;;;;;;;;;;;;;;;;GAkBG;AACH,eAAO,MAAM,UAAU;;;;;;;;;;;;;;;;;;;QAWrB,CAAA;AAEF;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,eAAO,MAAM,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;SAsBd,CAAA;AAEF;;;;;;;;;;;;;;;;GAgBG;AACH,eAAO,MAAM,KAAK;;;;;;;;;;;;;;;;;;;;;;;;;;QAWhB,CAAA;AAEF;;;;;;;;;;;;;;;;;GAiBG;AACH,eAAO,MAAM,SAAS;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;SAgBpB,CAAA;AAEF;;;;;;;;;;;;;;;;GAgBG;AACH,eAAO,MAAM,gBAAgB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;SAY3B,CAAA"}