@agentionai/agents 1.8.0 → 1.10.0

package/dist/agents/AgentConfig.d.ts

@@ -131,6 +131,12 @@ export interface OpenAISpecificConfig {
     reasoningEffort?: ReasoningEffort;
     seed?: number;
     user?: string;
+    /**
+     * Provider-defined / server-side tools (e.g. web search, file search, code
+     * interpreter). These run on OpenAI's infrastructure rather than locally —
+     * see `lib/tools/BuiltInTool.ts`.
+     */
+    builtInTools?: BuiltInTool[];
 }
 /**
  * Vendor-specific configuration for Mistral
@@ -164,11 +170,6 @@ export interface LlamaCppSpecificConfig {
     /** Base URL of the llama.cpp server's OpenAI-compatible API (default: `http://localhost:8080/v1`) */
     baseURL?: string;
 }
-/** Vendor-specific configuration for Cerebras */
-export interface CerebrasSpecificConfig {
-    /** Cerebras OpenAI-compatible API base URL. */
-    baseURL?: string;
-}
 /**
  * Vendor-specific configuration for OpenRouter
  *
@@ -212,9 +213,13 @@ export interface OpenRouterSpecificConfig {
     /** Reasoning configuration for models that support it. */
     reasoning?: OpenRouterReasoningConfig;
     /**
-     * OpenRouter plugins to enable — web search, file parsing, context
-     * compression, moderation. Passed through untouched; see
+     * OpenRouter plugins to enable — file parsing, context compression,
+     * moderation. Passed through untouched; see
      * https://openrouter.ai/docs/guides/features/plugins for the shapes.
+     *
+     * The `{ id: "web" }` web search plugin is deprecated in favour of the
+     * `openrouter:web_search` server tool — use {@link builtInTools} /
+     * `openRouterWebSearchTool()` instead.
      */
     plugins?: unknown[];
     /**
@@ -233,6 +238,13 @@ export interface OpenRouterSpecificConfig {
     appTitle?: string;
     /** Disable parallel tool calling (sends `parallel_tool_calls: false`). */
     disableParallelToolUse?: boolean;
+    /**
+     * Provider-defined / server-side tools (e.g. `openrouter:web_search`,
+     * `openrouter:web_fetch`). These run on OpenRouter's infrastructure rather
+     * than locally — see `lib/tools/BuiltInTool.ts`. Prefer these over the
+     * deprecated {@link OpenRouterSpecificConfig.plugins} web search plugin.
+     */
+    builtInTools?: BuiltInTool[];
 }
 /**
  * Generic vendor-specific configuration container

package/dist/agents/llamacpp/LlamaCppAgent.d.ts

@@ -99,6 +99,18 @@ export declare class LlamaCppAgent extends OpenAICompatibleAgent {
      * included, is on `raw`.
      */
     listModels(): Promise<ModelInfo<LlamaCppModelCard>[]>;
+    /**
+     * Tells the server to end the model's reasoning phase early, mid-stream,
+     * via llama.cpp's proprietary `/chat/completions/control` endpoint. Useful
+     * for cutting off a model that is thinking for too long without waiting
+     * for it to decide to stop on its own.
+     *
+     * A no-op if no streamed completion is in flight yet (`lastChunkId` unset).
+     * Best-effort: a failed request is logged (when `debug` is on) rather than
+     * thrown, since this is a side channel to a turn that should otherwise
+     * proceed normally.
+     */
+    skipReasoning(): Promise<void>;
 }
 export {};
 //# sourceMappingURL=LlamaCppAgent.d.ts.map

package/dist/agents/llamacpp/LlamaCppAgent.js

@@ -68,6 +68,36 @@ class LlamaCppAgent extends OpenAICompatibleAgent_1.OpenAICompatibleAgent {
             },
         }));
     }
+    /**
+     * Tells the server to end the model's reasoning phase early, mid-stream,
+     * via llama.cpp's proprietary `/chat/completions/control` endpoint. Useful
+     * for cutting off a model that is thinking for too long without waiting
+     * for it to decide to stop on its own.
+     *
+     * A no-op if no streamed completion is in flight yet (`lastChunkId` unset).
+     * Best-effort: a failed request is logged (when `debug` is on) rather than
+     * thrown, since this is a side channel to a turn that should otherwise
+     * proceed normally.
+     */
+    async skipReasoning() {
+        if (!this.lastChunkId)
+            return;
+        try {
+            await fetch(`${this.config.baseURL}/chat/completions/control`, {
+                method: "POST",
+                headers: { "Content-Type": "application/json" },
+                body: JSON.stringify({
+                    action: "reasoning_end",
+                    id: this.lastChunkId,
+                }),
+            });
+        }
+        catch (error) {
+            if (this.debug) {
+                console.error(`Failed to signal reasoning_end to ${this.getVendorName()}: ${error instanceof Error ? error.message : "Unknown error"}`);
+            }
+        }
+    }
 }
 exports.LlamaCppAgent = LlamaCppAgent;
 //# sourceMappingURL=LlamaCppAgent.js.map

package/dist/agents/openai/OpenAiAgent.d.ts

@@ -1,6 +1,7 @@
 import { BaseAgent, BaseAgentConfig, ModelInfo, TokenUsage } from "../BaseAgent";
 import { ExecuteOptions } from "../cancellation";
 import { History, MessageContent } from "../../history/History";
+import { type BuiltInTool } from "../../tools/BuiltInTool";
 import { Tool, Response, ResponseUsage } from "openai/resources/responses/responses";
 import type { Model as OpenAIModelCard } from "openai/resources/models";
 import { OpenAIModel, ReasoningEffort, ReasoningEffortFor } from "../model-types";
@@ -23,6 +24,12 @@ type AgentConfig<M extends OpenAIModel = OpenAIModel> = BaseAgentConfig & {
      */
     reasoningEffort?: ReasoningEffortFor<M>;
     user?: string;
+    /**
+     * Provider-defined / server-side tools (e.g. web search, file search, code
+     * interpreter). These run on OpenAI's infrastructure rather than locally.
+     * @see lib/tools/BuiltInTool.ts
+     */
+    builtInTools?: BuiltInTool[];
 };
 /**
  * Lowest `reasoning.effort` the given model accepts, used to resolve
@@ -78,6 +85,15 @@ export declare class OpenAiAgent<M extends OpenAIModel = OpenAIModel> extends Ba
      */
     listModels(): Promise<ModelInfo<OpenAIModelCard>[]>;
     protected getToolDefinitions(): Tool[];
+    /**
+     * Combine locally-executed tool definitions with provider-defined
+     * (server-side) built-in tools, in the shape the Responses API expects.
+     * Cast to `Tool[]`: built-in tool objects (e.g. `{ type: "web_search" }`)
+     * don't fit the SDK's `Tool` union, which only names `function` tools plus
+     * the specific built-ins it has typed — the same passthrough `ClaudeAgent`
+     * uses for its own `ToolUnion[]`.
+     */
+    protected getAllToolDefinitions(): Tool[];
     /**
      * Build the `reasoning` field for a Responses API request, as an object to
      * spread into the request params.

package/dist/agents/openai/OpenAiAgent.js

@@ -71,6 +71,7 @@ class OpenAiAgent extends BaseAgent_1.BaseAgent {
         const disableReasoning = config.disableReasoning ?? vendorConfig.disableReasoning ?? false;
         const reasoningEffort = config.reasoningEffort ?? vendorConfig.reasoningEffort;
         const user = config.user ?? vendorConfig.user;
+        const builtInTools = config.builtInTools ?? vendorConfig.builtInTools;
         this.config = {
             model: config.model || "gpt-4.1-mini",
             // No default. `max_output_tokens` is optional on the Responses API, and
@@ -84,6 +85,7 @@ class OpenAiAgent extends BaseAgent_1.BaseAgent {
             disableReasoning,
             reasoningEffort,
             user,
+            builtInTools,
             apiKey: config.apiKey,
             temperature: config.temperature,
             topP: config.topP,
@@ -136,6 +138,20 @@ class OpenAiAgent extends BaseAgent_1.BaseAgent {
             };
         });
     }
+    /**
+     * Combine locally-executed tool definitions with provider-defined
+     * (server-side) built-in tools, in the shape the Responses API expects.
+     * Cast to `Tool[]`: built-in tool objects (e.g. `{ type: "web_search" }`)
+     * don't fit the SDK's `Tool` union, which only names `function` tools plus
+     * the specific built-ins it has typed — the same passthrough `ClaudeAgent`
+     * uses for its own `ToolUnion[]`.
+     */
+    getAllToolDefinitions() {
+        return [
+            ...this.getToolDefinitions(),
+            ...(this.config.builtInTools ?? []),
+        ];
+    }
     /**
      * Build the `reasoning` field for a Responses API request, as an object to
      * spread into the request params.
@@ -204,7 +220,7 @@ class OpenAiAgent extends BaseAgent_1.BaseAgent {
                 model: this.config.model,
                 max_output_tokens: this.config.maxTokens,
                 input: inputMessages,
-                tools: this.getToolDefinitions(),
+                tools: this.getAllToolDefinitions(),
                 store: false,
                 temperature: this.config.temperature,
                 top_p: this.config.topP,
@@ -331,7 +347,7 @@ class OpenAiAgent extends BaseAgent_1.BaseAgent {
                         model: this.config.model,
                         max_output_tokens: this.config.maxTokens,
                         input: inputMessages,
-                        tools: this.getToolDefinitions(),
+                        tools: this.getAllToolDefinitions(),
                         store: false,
                         temperature: this.config.temperature,
                         top_p: this.config.topP,
@@ -511,7 +527,7 @@ class OpenAiAgent extends BaseAgent_1.BaseAgent {
             model: this.config.model,
             max_output_tokens: this.config.maxTokens,
             input: inputMessages,
-            tools: this.getToolDefinitions(),
+            tools: this.getAllToolDefinitions(),
             store: false,
             stream: true,
             temperature: this.config.temperature,

package/dist/agents/openai-compatible/OpenAICompatibleAgent.d.ts

@@ -35,6 +35,20 @@ export declare abstract class OpenAICompatibleAgent extends BaseAgent {
     protected config: Partial<OpenAICompatibleConfig>;
     private vizEventId?;
     private currentToolCallCount;
+    /**
+     * The `id` of the most recently seen streamed `ChatCompletionChunk`
+     * (`chatcmpl-...`). Internal only — some servers key control-plane calls
+     * (e.g. llama.cpp's `/chat/completions/control`) off the in-flight
+     * completion's id, so it needs to be captured somewhere subclasses can
+     * reach it, but it isn't part of the public `StreamChunk` shape.
+     */
+    protected lastChunkId?: string;
+    /**
+     * Whether this server accepts a replayed `reasoning_content` field on an
+     * assistant message. `undefined` until proven otherwise — see
+     * {@link withReasoningReplayFallback}.
+     */
+    private reasoningReplaySupported?;
     constructor(config: OpenAICompatibleConfig & {
         vendor: AgentVendor;
     }, history?: History);
@@ -53,6 +67,22 @@ export declare abstract class OpenAICompatibleAgent extends BaseAgent {
     protected process(_input: string): Promise<string>;
     execute(input: string | MessageContent[], options?: ExecuteOptions): Promise<string>;
     private callProvider;
+    /**
+     * Some OpenAI-compatible servers (Cerebras, at least as of 2026-08) reject
+     * any message carrying `reasoning_content` with a plain 400 — no per-field
+     * detail worth parsing, and other servers *require* the field (DeepSeek's
+     * thinking mode), so it can't just be dropped unconditionally either.
+     *
+     * Runs `request` normally first. On a 400 that could plausibly be caused by
+     * a replayed reasoning field, retries once with it stripped; if that
+     * succeeds, remembers the result so every later call in this agent's
+     * lifetime skips straight to the working shape instead of paying for the
+     * failed attempt again. If the retry also fails, the original error is
+     * what surfaces — it's more likely to point at the real problem.
+     */
+    private withReasoningReplayFallback;
+    /** Whether any assistant turn in history carries reasoning that would be replayed. */
+    private hasReplayableReasoning;
     protected handleResponse(response: ChatCompletion, options?: ExecuteOptions): Promise<string>;
     private handleToolCalls;
     /**

package/dist/agents/openai-compatible/OpenAICompatibleAgent.js

@@ -9,6 +9,7 @@ const BaseAgent_1 = require("../BaseAgent");
 const AgentEvent_1 = require("../AgentEvent");
 const cancellation_1 = require("../cancellation");
 const AgentError_1 = require("../errors/AgentError");
+const types_1 = require("../../history/types");
 const transformers_1 = require("../../history/transformers");
 const VizReporter_1 = require("../../viz/VizReporter");
 const VizConfig_1 = require("../../viz/VizConfig");
@@ -149,12 +150,11 @@ class OpenAICompatibleAgent extends BaseAgent_1.BaseAgent {
         }
     }
     async callProvider(options) {
-        const messages = transformers_1.chatCompletionsTransformer.toProvider(this.history.getEntries());
         const tools = this.tools.size > 0 ? this.getToolDefinitions() : undefined;
         this.startTurnTimer();
-        return this.client.chat.completions.create({
+        return this.withReasoningReplayFallback((includeReasoning) => this.client.chat.completions.create({
             model: this.config.model,
-            messages,
+            messages: transformers_1.chatCompletionsTransformer.toProvider(this.history.getEntries(), { includeReasoning }),
             tools,
             stream: false,
             max_tokens: this.config.maxTokens,
@@ -165,7 +165,49 @@ class OpenAICompatibleAgent extends BaseAgent_1.BaseAgent {
             presence_penalty: this.config.presencePenalty,
             frequency_penalty: this.config.frequencyPenalty,
             ...this.buildExtraRequestParams(),
-        }, { signal: options?.signal });
+        }, { signal: options?.signal }));
+    }
+    /**
+     * Some OpenAI-compatible servers (Cerebras, at least as of 2026-08) reject
+     * any message carrying `reasoning_content` with a plain 400 — no per-field
+     * detail worth parsing, and other servers *require* the field (DeepSeek's
+     * thinking mode), so it can't just be dropped unconditionally either.
+     *
+     * Runs `request` normally first. On a 400 that could plausibly be caused by
+     * a replayed reasoning field, retries once with it stripped; if that
+     * succeeds, remembers the result so every later call in this agent's
+     * lifetime skips straight to the working shape instead of paying for the
+     * failed attempt again. If the retry also fails, the original error is
+     * what surfaces — it's more likely to point at the real problem.
+     */
+    async withReasoningReplayFallback(request) {
+        const includeReasoning = this.reasoningReplaySupported !== false;
+        try {
+            return await request(includeReasoning);
+        }
+        catch (error) {
+            const worthRetrying = includeReasoning &&
+                this.hasReplayableReasoning() &&
+                error instanceof openai_1.default.APIError &&
+                error.status === 400;
+            if (!worthRetrying)
+                throw error;
+            try {
+                const result = await request(false);
+                this.reasoningReplaySupported = false;
+                return result;
+            }
+            catch {
+                throw error;
+            }
+        }
+    }
+    /** Whether any assistant turn in history carries reasoning that would be replayed. */
+    hasReplayableReasoning() {
+        return this.history
+            .getEntries()
+            .some((entry) => entry.role === "assistant" &&
+            entry.content.some((block) => (0, types_1.isThinkingContent)(block) && block.thinking.length > 0));
     }
     async handleResponse(response, options) {
         const usage = this.accumulateUsage(this.parseUsage(response));
@@ -329,12 +371,11 @@ class OpenAICompatibleAgent extends BaseAgent_1.BaseAgent {
         }
     }
     async *streamTurn(options) {
-        const messages = transformers_1.chatCompletionsTransformer.toProvider(this.history.getEntries());
         const tools = this.tools.size > 0 ? this.getToolDefinitions() : undefined;
         this.startTurnTimer();
-        const stream = await this.client.chat.completions.create({
+        const stream = await this.withReasoningReplayFallback((includeReasoning) => this.client.chat.completions.create({
             model: this.config.model,
-            messages,
+            messages: transformers_1.chatCompletionsTransformer.toProvider(this.history.getEntries(), { includeReasoning }),
             tools,
             stream: true,
             stream_options: { include_usage: true },
@@ -346,7 +387,7 @@ class OpenAICompatibleAgent extends BaseAgent_1.BaseAgent {
             presence_penalty: this.config.presencePenalty,
             frequency_penalty: this.config.frequencyPenalty,
             ...this.buildExtraRequestParams(),
-        }, { signal: options?.signal });
+        }, { signal: options?.signal }));
         let textContent = "";
         let reasoningContent = "";
         const toolCallAcc = new Map();
@@ -360,6 +401,8 @@ class OpenAICompatibleAgent extends BaseAgent_1.BaseAgent {
             // taking the last one covers both layouts without double-counting.
             if (chunk.usage)
                 streamUsage = chunk.usage;
+            if (chunk.id)
+                this.lastChunkId = chunk.id;
             if (chunk.choices.length === 0)
                 continue;
             const choice = chunk.choices[0];

package/dist/agents/openrouter/OpenRouterAgent.d.ts

@@ -129,6 +129,12 @@ export declare class OpenRouterAgent extends BaseAgent {
     private getClient;
     private createClient;
     protected getToolDefinitions(): Array<Record<string, unknown>>;
+    /**
+     * Combine locally-executed tool definitions with provider-defined
+     * (server-side) built-in tools (e.g. `openrouter:web_search`). Both sit in
+     * the same flat `tools` array OpenRouter's OpenAI-compatible endpoint takes.
+     */
+    protected getAllToolDefinitions(): Array<Record<string, unknown>>;
     protected process(_input: string): Promise<string>;
     /**
      * List the models OpenRouter offers, following pagination to the end.

package/dist/agents/openrouter/OpenRouterAgent.js

@@ -138,6 +138,7 @@ class OpenRouterAgent extends BaseAgent_1.BaseAgent {
             retryCodes: config.retryCodes ?? nested.retryCodes,
             reasoning: config.reasoning ?? nested.reasoning,
             plugins: config.plugins ?? nested.plugins,
+            builtInTools: config.builtInTools ?? nested.builtInTools,
             sessionId: config.sessionId ?? nested.sessionId,
             user: config.user ?? nested.user,
             serviceTier: config.serviceTier ?? nested.serviceTier,
@@ -202,6 +203,17 @@ class OpenRouterAgent extends BaseAgent_1.BaseAgent {
             };
         });
     }
+    /**
+     * Combine locally-executed tool definitions with provider-defined
+     * (server-side) built-in tools (e.g. `openrouter:web_search`). Both sit in
+     * the same flat `tools` array OpenRouter's OpenAI-compatible endpoint takes.
+     */
+    getAllToolDefinitions() {
+        return [
+            ...this.getToolDefinitions(),
+            ...(this.config.builtInTools ?? []),
+        ];
+    }
     async process(_input) {
         return "";
     }
@@ -381,7 +393,8 @@ class OpenRouterAgent extends BaseAgent_1.BaseAgent {
     /** The `ChatRequest` body, identical for the streaming and buffered paths. */
     buildRequest(stream) {
         const messages = transformers_1.openRouterTransformer.toProvider(this.history.getEntries());
-        const tools = this.tools.size > 0 ? this.getToolDefinitions() : undefined;
+        const allTools = this.getAllToolDefinitions();
+        const tools = allTools.length > 0 ? allTools : undefined;
         return {
             model: this.config.model,
             messages,

package/dist/history/transformers.d.ts

@@ -143,8 +143,17 @@ export declare const chatCompletionsTransformer: {
     /**
      * Convert normalized entries to Chat Completions message format.
      * Tool results become role:"tool" messages; tool calls are embedded in assistant messages.
+     *
+     * `includeReasoning` (default `true`) controls whether a prior assistant
+     * turn's reasoning is replayed as `reasoning_content`. DeepSeek's thinking
+     * mode requires it; some OpenAI-compatible servers (Cerebras) reject the
+     * field outright with a 400 on any message that carries it. Callers that
+     * have detected the latter pass `false` to fall back to the OpenAI-standard
+     * message shape.
      */
-    toProvider(entries: HistoryEntry[]): ChatCompletionMessage[];
+    toProvider(entries: HistoryEntry[], options?: {
+        includeReasoning?: boolean;
+    }): ChatCompletionMessage[];
     /**
      * Convert a Chat Completions response message to a normalized HistoryEntry.
      */

package/dist/history/transformers.js

@@ -630,8 +630,16 @@ exports.chatCompletionsTransformer = {
     /**
      * Convert normalized entries to Chat Completions message format.
      * Tool results become role:"tool" messages; tool calls are embedded in assistant messages.
+     *
+     * `includeReasoning` (default `true`) controls whether a prior assistant
+     * turn's reasoning is replayed as `reasoning_content`. DeepSeek's thinking
+     * mode requires it; some OpenAI-compatible servers (Cerebras) reject the
+     * field outright with a 400 on any message that carries it. Callers that
+     * have detected the latter pass `false` to fall back to the OpenAI-standard
+     * message shape.
      */
-    toProvider(entries) {
+    toProvider(entries, options) {
+        const includeReasoning = options?.includeReasoning ?? true;
         const messages = [];
         for (const entry of entries) {
             const textBlocks = entry.content.filter(types_1.isTextContent);
@@ -661,7 +669,7 @@ exports.chatCompletionsTransformer = {
                     .map((block) => block.thinking)
                     .filter((thought) => thought.length > 0)
                     .join("\n");
-                if (reasoning) {
+                if (reasoning && includeReasoning) {
                     msg.reasoning_content = reasoning;
                 }
                 if (toolUseBlocks.length > 0) {

package/dist/tools/BuiltInTool.d.ts

@@ -3,11 +3,14 @@
  *
  * Unlike `Tool`, these are not executed locally — the provider runs them as
  * part of generating its response (e.g. Anthropic's web search, bash, and
- * text editor tools). They carry no `execute` function or input schema; the
- * agent simply forwards their definition to the provider's API.
+ * text editor tools; OpenAI's web search, file search, and code interpreter;
+ * OpenRouter's web search/fetch server tools). They carry no `execute`
+ * function or input schema; the agent simply forwards their definition to
+ * the provider's API.
  *
  * Pass arbitrary built-in tool definitions straight through — only `type`
- * and `name` are required, any other provider-specific fields are allowed:
+ * is required. Anthropic also expects a `name` (the model's label for the
+ * tool); OpenAI and OpenRouter's built-in tool objects generally omit it.
  *
  * @example
  * ```typescript
@@ -19,13 +22,13 @@
  * });
  * ```
  *
- * Or use one of the helpers below for the well-known Anthropic tools.
+ * Or use one of the helpers below for the well-known tools of each provider.
  */
 export interface BuiltInTool {
     /** Provider-specific tool type identifier, e.g. `"web_search_20250305"` */
     type: string;
-    /** Name the model will use to refer to the tool, e.g. `"web_search"` */
-    name: string;
+    /** Name the model will use to refer to the tool, e.g. `"web_search"` (Anthropic only) */
+    name?: string;
     /** Any additional provider-specific configuration for this tool */
     [key: string]: unknown;
 }
@@ -63,6 +66,69 @@ export declare function bashTool(): BuiltInTool;
  * Anthropic's server-side text editor tool — lets Claude view and edit text files.
  */
 export declare function textEditorTool(version?: "20250124" | "20250429" | "20250728"): BuiltInTool;
+/**
+ * Options for OpenAI's web search tool (`web_search`), used on the Responses API.
+ * @see https://developers.openai.com/api/docs/guides/tools-web-search
+ */
+export interface OpenAiWebSearchToolOptions {
+    /** Only include results from these domains (max 100) */
+    allowedDomains?: string[];
+    /** Never include results from these domains (max 100) */
+    blockedDomains?: string[];
+    /** Approximate user location, used to localize search results */
+    userLocation?: {
+        type?: "approximate";
+        city?: string;
+        region?: string;
+        country?: string;
+        timezone?: string;
+    };
+    /** How much of the web page to feed back into context (higher = more thorough, more tokens) */
+    searchContextSize?: "low" | "medium" | "high";
+}
+/**
+ * OpenAI's server-side web search tool for the Responses API.
+ * The model decides when to search; results are fetched and processed by OpenAI.
+ */
+export declare function openAiWebSearchTool(options?: OpenAiWebSearchToolOptions): BuiltInTool;
+/**
+ * OpenAI's server-side file search tool — retrieves from vector stores you've
+ * already uploaded files to.
+ * @see https://developers.openai.com/api/docs/guides/tools-file-search
+ */
+export declare function openAiFileSearchTool(vectorStoreIds: string[], options?: {
+    maxNumResults?: number;
+}): BuiltInTool;
+/**
+ * OpenAI's server-side code interpreter tool — runs Python in a sandboxed container.
+ * Defaults to `container: { type: "auto" }`, which OpenAI provisions automatically
+ * and reuses across a conversation's follow-up requests.
+ * @see https://developers.openai.com/api/docs/guides/tools-code-interpreter
+ */
+export declare function openAiCodeInterpreterTool(containerId?: string): BuiltInTool;
+/**
+ * Options for OpenRouter's web search server tool (`openrouter:web_search`).
+ * @see https://openrouter.ai/docs/guides/features/server-tools/web-search
+ */
+export interface OpenRouterWebSearchToolOptions {
+    maxResults?: number;
+    maxTotalResults?: number;
+    searchContextSize?: "low" | "medium" | "high";
+    allowedDomains?: string[];
+    excludedDomains?: string[];
+}
+/**
+ * OpenRouter's server-side web search tool — works identically across every
+ * tool-calling model OpenRouter fronts, unlike each upstream provider's own
+ * (differently-shaped) web search tool.
+ */
+export declare function openRouterWebSearchTool(options?: OpenRouterWebSearchToolOptions): BuiltInTool;
+/**
+ * OpenRouter's server-side web fetch tool (`openrouter:web_fetch`) — retrieves
+ * and renders a specific URL, as opposed to searching.
+ * @see https://openrouter.ai/docs/guides/features/server-tools/overview
+ */
+export declare function openRouterWebFetchTool(): BuiltInTool;
 /**
  * Define an arbitrary provider-defined / built-in tool by its raw definition.
  * Use this to pass through tools not covered by the helpers above (or for

package/dist/tools/BuiltInTool.js

@@ -3,6 +3,11 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.webSearchTool = webSearchTool;
 exports.bashTool = bashTool;
 exports.textEditorTool = textEditorTool;
+exports.openAiWebSearchTool = openAiWebSearchTool;
+exports.openAiFileSearchTool = openAiFileSearchTool;
+exports.openAiCodeInterpreterTool = openAiCodeInterpreterTool;
+exports.openRouterWebSearchTool = openRouterWebSearchTool;
+exports.openRouterWebFetchTool = openRouterWebFetchTool;
 exports.builtInTool = builtInTool;
 /**
  * Anthropic's server-side web search tool.
@@ -42,6 +47,76 @@ function textEditorTool(version = "20250728") {
     };
     return { type: `text_editor_${version}`, name: names[version] };
 }
+/**
+ * OpenAI's server-side web search tool for the Responses API.
+ * The model decides when to search; results are fetched and processed by OpenAI.
+ */
+function openAiWebSearchTool(options = {}) {
+    const tool = { type: "web_search" };
+    if (options.allowedDomains || options.blockedDomains) {
+        tool.filters = {
+            ...(options.allowedDomains ? { allowed_domains: options.allowedDomains } : {}),
+            ...(options.blockedDomains ? { blocked_domains: options.blockedDomains } : {}),
+        };
+    }
+    if (options.userLocation) {
+        tool.user_location = { type: "approximate", ...options.userLocation };
+    }
+    if (options.searchContextSize) {
+        tool.search_context_size = options.searchContextSize;
+    }
+    return tool;
+}
+/**
+ * OpenAI's server-side file search tool — retrieves from vector stores you've
+ * already uploaded files to.
+ * @see https://developers.openai.com/api/docs/guides/tools-file-search
+ */
+function openAiFileSearchTool(vectorStoreIds, options = {}) {
+    const tool = { type: "file_search", vector_store_ids: vectorStoreIds };
+    if (options.maxNumResults !== undefined)
+        tool.max_num_results = options.maxNumResults;
+    return tool;
+}
+/**
+ * OpenAI's server-side code interpreter tool — runs Python in a sandboxed container.
+ * Defaults to `container: { type: "auto" }`, which OpenAI provisions automatically
+ * and reuses across a conversation's follow-up requests.
+ * @see https://developers.openai.com/api/docs/guides/tools-code-interpreter
+ */
+function openAiCodeInterpreterTool(containerId) {
+    return {
+        type: "code_interpreter",
+        container: containerId ?? { type: "auto" },
+    };
+}
+/**
+ * OpenRouter's server-side web search tool — works identically across every
+ * tool-calling model OpenRouter fronts, unlike each upstream provider's own
+ * (differently-shaped) web search tool.
+ */
+function openRouterWebSearchTool(options = {}) {
+    const tool = { type: "openrouter:web_search" };
+    if (options.maxResults !== undefined)
+        tool.max_results = options.maxResults;
+    if (options.maxTotalResults !== undefined)
+        tool.max_total_results = options.maxTotalResults;
+    if (options.searchContextSize)
+        tool.search_context_size = options.searchContextSize;
+    if (options.allowedDomains)
+        tool.allowed_domains = options.allowedDomains;
+    if (options.excludedDomains)
+        tool.excluded_domains = options.excludedDomains;
+    return tool;
+}
+/**
+ * OpenRouter's server-side web fetch tool (`openrouter:web_fetch`) — retrieves
+ * and renders a specific URL, as opposed to searching.
+ * @see https://openrouter.ai/docs/guides/features/server-tools/overview
+ */
+function openRouterWebFetchTool() {
+    return { type: "openrouter:web_fetch" };
+}
 /**
  * Define an arbitrary provider-defined / built-in tool by its raw definition.
  * Use this to pass through tools not covered by the helpers above (or for

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@agentionai/agents",
   "author": "Laurent Zuijdwijk",
-  "version": "1.8.0",
+  "version": "1.10.0",
   "description": "Agent Library",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",