@stackfactor/agent-utils 1.2.16 → 1.2.18

package/README.md

@@ -40,7 +40,7 @@ When `expectsJsonResponse` is `true` (the default), JSON escape instructions are
 | Parameter             | Type                 | Default         | Description                                                                                              |
 | --------------------- | -------------------- | --------------- | -------------------------------------------------------------------------------------------------------- |
 | `modelName`           | `string`             | —               | Model identifier: `"gpt-4o"`, `"claude-3-5-sonnet"`, `"gemini-1.5-pro"`, `"deepseek-chat"`, `"kimi-k2-0905-preview"`, `"glm-4.6"`, etc. |
-| `config`              | `object`             | —               | API keys (`openAIAPIKey`, `anthropicAPIKey`, `googleAPIKey`, `deepSeekAPIKey`, `kimiAPIKey`, `glmAPIKey`), `temperature`, `agentic`, `recursionLimit` |
+| `config`              | `object`             | —               | API keys (`openAIAPIKey`, `anthropicAPIKey`, `googleAPIKey`, `deepSeekAPIKey`, `kimiAPIKey`, `glmAPIKey`), `temperature`, `agentic`, `recursionLimit`, `webSearch` |
 | `prompt`              | `string \| object[]` | —               | Plain string or array of `{ role, content }` message objects                                             |
 | `onProgressReport`    | `function \| null`   | `null`          | Async callback receiving `{ message, progress }` updates                                                 |
 | `minPercent`          | `number`             | `0`             | Lower bound for progress percentage                                                                      |
@@ -254,6 +254,71 @@ Shared constants used across the package.
 
 ---
 
+## Web Search
+
+Set `config.webSearch` to enable each provider's own web search tool. The provider runs the search server-side inside the same request — there is no client-side agent loop and no extra round trip — so every calling convention (streaming, non-streaming, agentic, with or without a Zod schema) is unchanged.
+
+| Provider  | Native tool                                                                                                    | Context control                       | Billing                     |
+| --------- | -------------------------------------------------------------------------------------------------------------- | ------------------------------------- | --------------------------- |
+| Anthropic | [`web_search` server tool](https://platform.claude.com/docs/en/agents-and-tools/tool-use/web-search-tool)         | Dynamic filtering (**on by default**) | $10 per 1,000 searches      |
+| OpenAI    | [`web_search` hosted tool](https://platform.openai.com/docs/guides/tools-web-search) (Responses API)              | `search_context_size`                 | Per search, model-dependent |
+| Google    | [`googleSearch` grounding](https://ai.google.dev/gemini-api/docs/google-search)                                   | None offered by the API               | Per grounded request        |
+
+```typescript
+const usageTracker = {};
+const result = await langChain.runPromptWithModel(
+  "claude-opus-5",
+  {
+    anthropicAPIKey: "sk-ant-...",
+    "claude-opus-5-web-search-costs": 10, // USD per 1,000 searches
+    webSearch: { maxUses: 5, allowedDomains: ["reuters.com", "bbc.com"] },
+  },
+  "What happened in the markets today?",
+  null, 0, 100, false, null, "StackFactor", [], usageTracker,
+);
+// usageTracker.tokens["claude-opus-5_webSearches"] === 2
+// usageTracker.cost includes 2 / 1000 * 10
+// usageTracker.webSearchSources === [{ url: "https://reuters.com/...", title: "..." }, ...]
+```
+
+### `WebSearchConfig`
+
+`webSearch: true` uses provider defaults. Pass an object to configure it; each field is only sent to the providers that accept it, and the rest are ignored.
+
+| Field               | Applies to        | Default      | Description                                                                                   |
+| ------------------- | ----------------- | ------------ | ----------------------------------------------------------------------------------------------- |
+| `maxUses`           | Anthropic         | unlimited    | Hard cap on searches per request                                                                 |
+| `allowedDomains`    | Anthropic, OpenAI | —            | Restrict results to these domains (bare domains, no scheme)                                      |
+| `blockedDomains`    | Anthropic         | —            | Exclude these domains; cannot be combined with `allowedDomains`                                   |
+| `userLocation`      | Anthropic, OpenAI | —            | `{ city, region, country, timezone }` — ISO 3166-1 alpha-2 country, IANA timezone                |
+| `searchContextSize` | OpenAI            | `"medium"`   | `"low" \| "medium" \| "high"` — how much context window results may consume                       |
+| `timeRange`         | Google            | —            | `{ startTime, endTime }` RFC 3339 window (`excludeDomains` is Vertex AI only and is not sent)    |
+| `dynamicFiltering`  | Anthropic         | `true`       | Filter results with code before they enter the context window; `false` forces `allowed_callers: ["direct"]` |
+| `responseInclusion` | Anthropic         | `"excluded"` | Whether filtered-away result blocks are echoed back in the response                               |
+| `toolVersion`       | Anthropic         | per model    | Pin the dated tool version instead of selecting it per model                                     |
+
+### Context management
+
+Search results are the largest thing web search puts into a request, so each provider's context controls are applied up front rather than left at their defaults.
+
+**Anthropic — dynamic filtering, on by default.** Basic search (`web_search_20250305`) loads *every* raw search result into the context window. From `web_search_20260209` Claude instead writes and runs code that filters the results first, so only relevant content is ingested. `buildWebSearchTool` picks the tool version per model: Claude 4.6 and later get `web_search_20260318` with filtering enabled and `response_inclusion: "excluded"` (which also keeps the consumed result blocks out of the response, cutting billed output tokens); earlier models, which lack programmatic tool calling, fall back to `web_search_20250305`. Pinning a filtering version on an older model via `toolVersion` automatically adds `allowed_callers: ["direct"]` so the request cannot 400. Anthropic provisions the code execution that filtering needs automatically and does not charge extra for it beyond token costs.
+
+**OpenAI — `search_context_size`.** This is OpenAI's only context knob and it is a genuine quality/cost tradeoff, so it is left at OpenAI's own balanced default of `"medium"` rather than silently downgraded. Set `searchContextSize: "low"` to minimize ingested context where answer depth matters less.
+
+**Google — no equivalent exists.** The Gemini API's `GoogleSearch` tool has no result-filtering or context-size field; grounded results are injected as-is. The only related lever, `dynamicRetrievalConfig`, belongs to the legacy Gemini 1.5 `googleSearchRetrieval` tool and gates *whether* a search happens, not how much of it is ingested. `searchTypes` is deliberately left unset so grounding stays on text-only web results instead of also returning image bytes.
+
+**Downstream.** Non-text blocks (`server_tool_use`, `web_search_tool_result`, code execution results) are dropped by `extractTextContent` and never re-sent: the library issues one self-contained request per call, so encrypted search results are not carried into follow-up turns. In agentic mode the agent loop does resend history, which is where dynamic filtering and `response_inclusion: "excluded"` matter most.
+
+**Notes**
+
+- Models without a native web search tool (DeepSeek, Kimi, GLM) log a warning and run the prompt without search, so one config can be pointed at any model.
+- Searches performed are added to `usageTracker` as `<model>_webSearches`, costed from `<model>-web-search-costs`. Sources are collected on `usageTracker.webSearchSources`, deduplicated by URL — Anthropic and Google both require citing the original sources when their output is shown to end users.
+- Combining web search with a Zod `schema` requires Gemini 3 or later on Google; Gemini 1.5/2.x reject `responseSchema` alongside `googleSearch` with a 400.
+- With `response_inclusion: "excluded"`, `usageTracker.webSearchSources` is populated from the citations attached to the answer rather than from every raw result — the sources actually used, which is what has to be displayed.
+- Enabling web search on a `gpt-*` model routes the request through OpenAI's Responses API, where the structured-output schema is sent as `text.format` instead of `response_format`. This is handled automatically.
+
+---
+
 ## Supported Models
 
 ### Text / Chat
@@ -294,6 +359,9 @@ The `config` object accepted by LangChain methods supports the following keys:
 | `maxTokens`       | `number`  | Maximum output tokens (default: `16384` for Claude, `200000` for other providers). For Claude, values above `21333` automatically enable LangChain streaming to bypass the Anthropic SDK's 10-minute non-streaming guard. |
 | `agentic`         | `boolean` | Enable agentic mode in `runPromptWithModel` |
 | `recursionLimit`  | `number`  | Max agent steps (default: `25`)             |
+| `webSearch`       | `boolean \| WebSearchConfig` | Enable the provider's native web search tool (see [Web Search](#web-search)) |
+
+Per-model cost constants are read from the same object using flat keys: `<model>-input-token-costs`, `<model>-output-token-costs`, `<model>-image-input-token-costs`, `<model>-image-output-token-costs`, `<model>-character-costs` (all USD per million), and `<model>-web-search-costs` (USD per **1,000** searches).
 
 ---
 

package/dist/cjs/index.d.ts

@@ -9,7 +9,7 @@ export { constants };
 export { errorHandling, AppError };
 export type { ParsedError } from "./errorHandling.js";
 export { langChain };
-export type { UsageTracker } from "./langChain.js";
+export type { UsageTracker, WebSearchConfig } from "./langChain.js";
 export { logger };
 export { serve };
 export { callAgent };

package/dist/cjs/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,SAAS,MAAM,YAAY,CAAC;AACnC,OAAO,aAAa,EAAE,EAAE,QAAQ,EAAE,MAAM,oBAAoB,CAAC;AAC7D,OAAO,SAAS,MAAM,gBAAgB,CAAC;AACvC,OAAO,MAAM,MAAM,aAAa,CAAC;AACjC,OAAO,EAAE,KAAK,EAAE,MAAM,YAAY,CAAC;AACnC,OAAO,EAAE,SAAS,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AACpD,OAAO,KAAK,cAAc,MAAM,qBAAqB,CAAC;AAEtD,OAAO,EAAE,SAAS,EAAE,CAAC;AAErB,OAAO,EAAE,aAAa,EAAE,QAAQ,EAAE,CAAC;AAEnC,YAAY,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AAEtD,OAAO,EAAE,SAAS,EAAE,CAAC;AAErB,YAAY,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AAEnD,OAAO,EAAE,MAAM,EAAE,CAAC;AAElB,OAAO,EAAE,KAAK,EAAE,CAAC;AAEjB,OAAO,EAAE,SAAS,EAAE,CAAC;AAErB,OAAO,EAAE,UAAU,EAAE,CAAC;AAEtB,YAAY,EACV,mBAAmB,EACnB,gBAAgB,EAChB,iBAAiB,EACjB,WAAW,GACZ,MAAM,aAAa,CAAC;AAErB,OAAO,EAAE,cAAc,EAAE,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,SAAS,MAAM,YAAY,CAAC;AACnC,OAAO,aAAa,EAAE,EAAE,QAAQ,EAAE,MAAM,oBAAoB,CAAC;AAC7D,OAAO,SAAS,MAAM,gBAAgB,CAAC;AACvC,OAAO,MAAM,MAAM,aAAa,CAAC;AACjC,OAAO,EAAE,KAAK,EAAE,MAAM,YAAY,CAAC;AACnC,OAAO,EAAE,SAAS,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AACpD,OAAO,KAAK,cAAc,MAAM,qBAAqB,CAAC;AAEtD,OAAO,EAAE,SAAS,EAAE,CAAC;AAErB,OAAO,EAAE,aAAa,EAAE,QAAQ,EAAE,CAAC;AAEnC,YAAY,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AAEtD,OAAO,EAAE,SAAS,EAAE,CAAC;AAErB,YAAY,EAAE,YAAY,EAAE,eAAe,EAAE,MAAM,gBAAgB,CAAC;AAEpE,OAAO,EAAE,MAAM,EAAE,CAAC;AAElB,OAAO,EAAE,KAAK,EAAE,CAAC;AAEjB,OAAO,EAAE,SAAS,EAAE,CAAC;AAErB,OAAO,EAAE,UAAU,EAAE,CAAC;AAEtB,YAAY,EACV,mBAAmB,EACnB,gBAAgB,EAChB,iBAAiB,EACjB,WAAW,GACZ,MAAM,aAAa,CAAC;AAErB,OAAO,EAAE,cAAc,EAAE,CAAC"}

package/dist/cjs/langChain.d.ts

@@ -9,6 +9,73 @@ export type UsageTracker = {
     tokens: {
         [tokenKey: string]: number;
     };
+    /**
+     * Sources returned by native web search, deduplicated by URL across every
+     * call in the run. Only present once a search has actually run. Anthropic and
+     * Google both require the original sources to be cited when their output is
+     * shown to end users, so they are surfaced here rather than discarded with
+     * the rest of the non-text content blocks.
+     */
+    webSearchSources?: {
+        url: string;
+        title?: string;
+    }[];
+};
+/**
+ * Caller-facing options for the providers' native web search tools. Enable web
+ * search by setting `config.webSearch` to `true` (provider defaults) or to one
+ * of these objects. Every field is optional and is only forwarded to the
+ * providers that accept it — see `buildWebSearchTool` for the mapping.
+ */
+export type WebSearchConfig = {
+    /** Anthropic only: hard cap on searches per request (`max_uses`). */
+    maxUses?: number;
+    /** Anthropic (`allowed_domains`) and OpenAI (`filters.allowed_domains`). */
+    allowedDomains?: string[];
+    /** Anthropic only (`blocked_domains`); cannot be combined with `allowedDomains`. */
+    blockedDomains?: string[];
+    /** Anthropic and OpenAI: approximate location used to localize results. */
+    userLocation?: {
+        city?: string;
+        region?: string;
+        /** Two-letter ISO 3166-1 alpha-2 code, e.g. `"US"`. */
+        country?: string;
+        /** IANA timezone ID, e.g. `"America/Los_Angeles"`. */
+        timezone?: string;
+    };
+    /**
+     * OpenAI only: how much of the context window search results may consume.
+     * OpenAI's default is `"medium"`; `"low"` minimizes context at some cost to
+     * answer quality, `"high"` is the expensive end.
+     */
+    searchContextSize?: "low" | "medium" | "high";
+    /** Gemini only: RFC 3339 window the search is restricted to. */
+    timeRange?: {
+        startTime: string;
+        endTime: string;
+    };
+    /**
+     * Anthropic only: opt out of dynamic filtering by forcing the search to be
+     * called directly (`allowed_callers: ["direct"]`). Defaults to `true` on
+     * models that support it — see `supportsAnthropicDynamicFiltering`. Turning
+     * this off means every raw search result lands in the context window.
+     */
+    dynamicFiltering?: boolean;
+    /**
+     * Anthropic only: whether search result blocks consumed by dynamic filtering
+     * are echoed back in the response. Defaults to `"excluded"`, which drops them
+     * and cuts the output tokens billed for content nothing downstream reads.
+     */
+    responseInclusion?: "full" | "excluded";
+    /**
+     * Anthropic only: pin the dated tool version instead of letting
+     * `buildWebSearchTool` pick per model. `web_search_20250305` is basic search,
+     * `web_search_20260209` adds dynamic filtering, `web_search_20260318` adds
+     * response-inclusion control. Pinning a filtering version on a model that
+     * cannot do programmatic tool calling returns a 400 unless
+     * `dynamicFiltering: false` is also set.
+     */
+    toolVersion?: string;
 };
 declare const _default: {
     checkIfAIProviderConfigured: (config: any) => void;

package/dist/cjs/langChain.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"langChain.d.ts","sourceRoot":"","sources":["../../src/langChain.ts"],"names":[],"mappings":"AAuGA;;;;;GAKG;AACH,MAAM,MAAM,YAAY,GAAG;IACzB,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE;QAAE,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAAA;KAAE,CAAC;CACxC,CAAC;;0CAE2C,GAAG,KAAG,IAAI;wBAktB/C,MAAM,aACD,MAAM,gBACH,MAAM,SACb,GAAG,EAAE,kBACI,GAAG,UACX,GAAG,KACV,GAAG;sBA0BG,GAAG,UACF,MAAM,UACN,GAAG,eACC,QAAQ,GAAG,IAAI,iBACb,YAAY,GAAG,IAAI,KAChC,OAAO,CAAC,GAAG,CAAC;oCA4XF,MAAM,UACT,GAAG,UACH,GAAG,oBACO,GAAG,eACT,MAAM,eACN,MAAM,wBACG,OAAO,WACpB,GAAG,cACA,MAAM,UACV,GAAG,EAAE,iBACE,YAAY,GAAG,IAAI,KAChC,OAAO,CAAC,GAAG,CAAC;sDA2tBF,MAAM,UACT,GAAG,UACH,MAAM,YACL,GAAG,iBACE,YAAY,GAAG,IAAI,KAChC,OAAO,CAAC,GAAG,CAAC;0CA//B8B,GAAG,KAAG,MAAM;+CAprB9C,YAAY,GAAG,IAAI,GAAG,SAAS,aAC7B,MAAM,kBACD,MAAM,UACd,GAAG,KACV,IAAI;mCAosBU,MAAM,mBACJ,MAAM,EAAE,KACxB,MAAM;;AAsiCT,wBASE"}
+{"version":3,"file":"langChain.d.ts","sourceRoot":"","sources":["../../src/langChain.ts"],"names":[],"mappings":"AAuGA;;;;;GAKG;AACH,MAAM,MAAM,YAAY,GAAG;IACzB,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE;QAAE,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAAA;KAAE,CAAC;IACvC;;;;;;OAMG;IACH,gBAAgB,CAAC,EAAE;QAAE,GAAG,EAAE,MAAM,CAAC;QAAC,KAAK,CAAC,EAAE,MAAM,CAAA;KAAE,EAAE,CAAC;CACtD,CAAC;AAskBF;;;;;GAKG;AACH,MAAM,MAAM,eAAe,GAAG;IAC5B,qEAAqE;IACrE,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,4EAA4E;IAC5E,cAAc,CAAC,EAAE,MAAM,EAAE,CAAC;IAC1B,oFAAoF;IACpF,cAAc,CAAC,EAAE,MAAM,EAAE,CAAC;IAC1B,2EAA2E;IAC3E,YAAY,CAAC,EAAE;QACb,IAAI,CAAC,EAAE,MAAM,CAAC;QACd,MAAM,CAAC,EAAE,MAAM,CAAC;QAChB,uDAAuD;QACvD,OAAO,CAAC,EAAE,MAAM,CAAC;QACjB,sDAAsD;QACtD,QAAQ,CAAC,EAAE,MAAM,CAAC;KACnB,CAAC;IACF;;;;OAIG;IACH,iBAAiB,CAAC,EAAE,KAAK,GAAG,QAAQ,GAAG,MAAM,CAAC;IAC9C,gEAAgE;IAChE,SAAS,CAAC,EAAE;QAAE,SAAS,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,CAAC;IACnD;;;;;OAKG;IACH,gBAAgB,CAAC,EAAE,OAAO,CAAC;IAC3B;;;;OAIG;IACH,iBAAiB,CAAC,EAAE,MAAM,GAAG,UAAU,CAAC;IACxC;;;;;;;OAOG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB,CAAC;;0CAxnB2C,GAAG,KAAG,IAAI;wBAujC/C,MAAM,aACD,MAAM,gBACH,MAAM,SACb,GAAG,EAAE,kBACI,GAAG,UACX,GAAG,KACV,GAAG;sBAiCG,GAAG,UACF,MAAM,UACN,GAAG,eACC,QAAQ,GAAG,IAAI,iBACb,YAAY,GAAG,IAAI,KAChC,OAAO,CAAC,GAAG,CAAC;oCA0YF,MAAM,UACT,GAAG,UACH,GAAG,oBACO,GAAG,eACT,MAAM,eACN,MAAM,wBACG,OAAO,WACpB,GAAG,cACA,MAAM,UACV,GAAG,EAAE,iBACE,YAAY,GAAG,IAAI,KAChC,OAAO,CAAC,GAAG,CAAC;sDAuuBF,MAAM,UACT,GAAG,UACH,MAAM,YACL,GAAG,iBACE,YAAY,GAAG,IAAI,KAChC,OAAO,CAAC,GAAG,CAAC;0CAjhC8B,GAAG,KAAG,MAAM;+CAviC9C,YAAY,GAAG,IAAI,GAAG,SAAS,aAC7B,MAAM,kBACD,MAAM,UACd,GAAG,KACV,IAAI;mCAujCU,MAAM,mBACJ,MAAM,EAAE,KACxB,MAAM;;AAwjCT,wBASE"}

package/dist/cjs/langChain.js

@@ -608,6 +608,234 @@ const resolveTemperatureSetting = (modelName, config) => {
     }
     return { temperature: clamped };
 };
+/**
+ * Whether a Claude model can run web search through dynamic filtering, where
+ * Claude writes and runs code that filters the search results before they reach
+ * the context window instead of loading every result into it. Requires Claude
+ * 4.6 or later (the models with programmatic tool calling); on anything earlier
+ * the filtering tool versions return a 400 unless search is pinned to
+ * `allowed_callers: ["direct"]`.
+ * @param modelName - The Claude model identifier being routed
+ * @returns `true` when the model supports dynamic filtering
+ */
+const supportsAnthropicDynamicFiltering = (modelName) => /^claude-(opus|sonnet|haiku)-4-(?:[6-9]|\d\d)\b/.test(modelName) ||
+    /^claude-(opus|sonnet|haiku|fable|mythos)-(?:[5-9]|\d\d)\b/.test(modelName);
+/**
+ * Normalizes `config.webSearch` into an options object, returning `null` when
+ * web search is off so callers can use it as the single enablement gate.
+ */
+const getWebSearchOptions = (config) => {
+    const webSearch = config?.webSearch;
+    if (!webSearch)
+        return null;
+    return webSearch === true ? {} : webSearch;
+};
+/**
+ * Builds the provider-native web search tool definition for a model:
+ *  - `claude-` → Anthropic's `web_search` server tool, executed by the Messages
+ *    API within a single request and answered with citations. Defaults to the
+ *    dynamic-filtering tool version on models that support it, so search results
+ *    are filtered by code before they reach the context window.
+ *  - `gpt-` → OpenAI's hosted `web_search` tool (Responses API). Context spend
+ *    is governed by `search_context_size` (OpenAI defaults to `medium`).
+ *  - `gemini-` → Google's `googleSearch` grounding tool. Google exposes no
+ *    result-filtering or context-size control; leaving `searchTypes` unset keeps
+ *    grounding on text-only web results rather than image bytes.
+ * Returns `null` for providers with no native web search (DeepSeek, Kimi, GLM),
+ * warning instead of throwing so one config can be pointed at any model.
+ * @param modelName - The model identifier being routed
+ * @param options - Normalized options from `getWebSearchOptions`
+ * @returns The provider's tool definition, or `null` when unsupported
+ */
+const buildWebSearchTool = (modelName, options) => {
+    const { allowedDomains, blockedDomains, userLocation } = options;
+    if (modelName.startsWith("claude-")) {
+        // The API returns a 400 when both filters are present, so fail locally
+        // rather than paying for the round trip.
+        if (allowedDomains && blockedDomains) {
+            throw errorHandling_js_1.default.create(const_js_1.default.HTTP_CODES.BAD_REQUEST, "Anthropic web search accepts allowedDomains or blockedDomains, not both.");
+        }
+        // Prefer the newest tool version the model can actually run. Basic search
+        // loads every result into the context window; from `web_search_20260209`
+        // Claude filters them with code first, and `web_search_20260318` can also
+        // keep the consumed results out of the response.
+        const canFilter = supportsAnthropicDynamicFiltering(modelName);
+        const type = options.toolVersion ||
+            (canFilter ? "web_search_20260318" : "web_search_20250305");
+        const version = Number(type.slice(-8));
+        // Filtering versions default to running search from inside code execution.
+        // Say so explicitly when it is not wanted (or not possible), which is what
+        // the API requires from models without programmatic tool calling.
+        const directOnly = version >= 20260209 && (options.dynamicFiltering === false || !canFilter);
+        return {
+            type,
+            name: "web_search",
+            ...(options.maxUses ? { max_uses: options.maxUses } : {}),
+            ...(allowedDomains ? { allowed_domains: allowedDomains } : {}),
+            ...(blockedDomains ? { blocked_domains: blockedDomains } : {}),
+            ...(userLocation
+                ? { user_location: { type: "approximate", ...userLocation } }
+                : {}),
+            ...(directOnly ? { allowed_callers: ["direct"] } : {}),
+            ...(version >= 20260318
+                ? { response_inclusion: options.responseInclusion || "excluded" }
+                : {}),
+        };
+    }
+    if (modelName.startsWith("gpt-")) {
+        return {
+            type: "web_search",
+            ...(allowedDomains
+                ? { filters: { allowed_domains: allowedDomains } }
+                : {}),
+            ...(userLocation
+                ? { user_location: { type: "approximate", ...userLocation } }
+                : {}),
+            ...(options.searchContextSize
+                ? { search_context_size: options.searchContextSize }
+                : {}),
+        };
+    }
+    if (modelName.startsWith("gemini-")) {
+        // `timeRangeFilter` is the only filter the Gemini API exposes;
+        // `excludeDomains` is a Vertex AI field and is rejected here, so domain
+        // filters are deliberately not mapped for Google.
+        return {
+            googleSearch: options.timeRange
+                ? { timeRangeFilter: options.timeRange }
+                : {},
+        };
+    }
+    logger_js_1.default.log(null, logger_js_1.default.levels.warn, `Model "${modelName}" has no native web search tool; ignoring the configured webSearch options.`);
+    return null;
+};
+/**
+ * Flattens LangChain message content into plain text. Content is a string for
+ * ordinary completions, but every provider switches to an array of blocks once
+ * a server-side tool runs — Anthropic interleaves `server_tool_use` and
+ * `web_search_tool_result` blocks with the answer text, and OpenAI's Responses
+ * API returns annotated text blocks — so without this the JSON parse pipeline
+ * would receive a non-string and every web-search call would fail.
+ * @param content - A message's `content` field, or a raw string
+ * @returns The concatenated text of all text blocks
+ */
+const extractTextContent = (content) => {
+    if (typeof content === "string")
+        return content;
+    if (!Array.isArray(content))
+        return "";
+    let text = "";
+    for (const block of content) {
+        if (typeof block === "string")
+            text += block;
+        else if (block?.type === "text" && typeof block.text === "string") {
+            text += block.text;
+        }
+    }
+    return text;
+};
+const createWebSearchUsage = () => ({
+    reportedRequests: 0,
+    callIds: new Set(),
+    grounded: false,
+    sources: new Map(),
+});
+/**
+ * Folds one message — or one streaming chunk — into a `WebSearchUsage`. Safe to
+ * call on every chunk of a stream and on messages that involved no search.
+ */
+const collectWebSearchUsage = (payload, usage) => {
+    if (!payload)
+        return;
+    const addSource = (url, title) => {
+        if (typeof url === "string" && url && !usage.sources.has(url)) {
+            usage.sources.set(url, {
+                url,
+                ...(typeof title === "string" ? { title } : {}),
+            });
+        }
+    };
+    if (Array.isArray(payload.content)) {
+        for (const block of payload.content) {
+            if (!block || typeof block !== "object")
+                continue;
+            // Anthropic: results of a search the API executed server-side.
+            if (block.type === "web_search_tool_result" &&
+                Array.isArray(block.content)) {
+                for (const result of block.content) {
+                    addSource(result?.url, result?.title);
+                }
+            }
+            // Anthropic: citations attached to the answer's text blocks.
+            if (Array.isArray(block.citations)) {
+                for (const citation of block.citations) {
+                    addSource(citation?.url, citation?.title);
+                }
+            }
+            // OpenAI Responses API: one block per executed search, plus url citations.
+            if (block.type === "web_search_call" && block.id) {
+                usage.callIds.add(block.id);
+            }
+            if (Array.isArray(block.annotations)) {
+                for (const annotation of block.annotations) {
+                    if (annotation?.type === "url_citation") {
+                        addSource(annotation.url, annotation.title);
+                    }
+                }
+            }
+        }
+    }
+    const metadata = payload.response_metadata;
+    if (!metadata)
+        return;
+    const requests = metadata.usage?.server_tool_use?.web_search_requests;
+    if (typeof requests === "number" && requests > usage.reportedRequests) {
+        usage.reportedRequests = requests;
+    }
+    const grounding = metadata.groundingMetadata;
+    if (grounding) {
+        usage.grounded = true;
+        for (const chunk of grounding.groundingChunks || []) {
+            addSource(chunk?.web?.uri, chunk?.web?.title);
+        }
+    }
+};
+/**
+ * Adds a call's web-search usage to the caller-supplied tracker. Searches are
+ * billed per request rather than per token (Anthropic charges $10 per 1,000
+ * searches; Google charges per grounded request), so the rate is read from the
+ * `<model>-web-search-costs` constant expressed in USD per 1,000 searches and
+ * accumulated under `<model>_webSearches`. Sources are appended to
+ * `tracker.webSearchSources`, deduplicated by URL across the whole run.
+ */
+const updateWebSearchUsageTracker = (tracker, modelName, usage, config) => {
+    if (!tracker || !modelName)
+        return;
+    // The three signals describe the same searches from different providers, so
+    // the largest one is the count rather than their sum.
+    const searches = Math.max(usage.reportedRequests, usage.callIds.size, usage.grounded ? 1 : 0);
+    if (!searches && usage.sources.size === 0)
+        return;
+    if (typeof tracker.cost !== "number")
+        tracker.cost = 0;
+    if (!tracker.tokens || typeof tracker.tokens !== "object")
+        tracker.tokens = {};
+    if (searches > 0) {
+        const addedCost = (searches / 1_000) * getModelRate(modelName, config, "web-search");
+        if (Number.isFinite(addedCost) && addedCost > 0)
+            tracker.cost += addedCost;
+        const key = `${modelName}_webSearches`;
+        tracker.tokens[key] = (tracker.tokens[key] || 0) + searches;
+    }
+    if (usage.sources.size > 0) {
+        const sources = tracker.webSearchSources || (tracker.webSearchSources = []);
+        for (const source of usage.sources.values()) {
+            if (!sources.some((existing) => existing.url === source.url)) {
+                sources.push(source);
+            }
+        }
+    }
+};
 /**
  * Instantiates and returns the appropriate LangChain chat model based on the model
  * name prefix. `claude-` maps to `ChatAnthropic`, `gemini-` maps to
@@ -634,6 +862,13 @@ const getLLMModel = (modelName, config, schema = null) => {
     // Resolve `temperature` with presence/support/range handling (see
     // resolveTemperatureSetting). Applied uniformly to every provider below.
     const modelSettings = resolveTemperatureSetting(modelName, config);
+    // Native web search (see buildWebSearchTool). The tool is bound to the model
+    // so both `.invoke()` and `.stream()` pick it up; the provider runs the search
+    // server-side within the same request, so no client-side agent loop is needed.
+    const webSearchOptions = getWebSearchOptions(config);
+    const webSearchTool = webSearchOptions
+        ? buildWebSearchTool(modelName, webSearchOptions)
+        : null;
     // Claude models (Anthropic)
     if (modelName.startsWith("claude-")) {
         // Anthropic's SDK rejects non-streamed requests when max_tokens is large
@@ -658,7 +893,7 @@ const getLLMModel = (modelName, config, schema = null) => {
                 },
             }
             : {};
-        return new anthropic_1.ChatAnthropic({
+        const model = new anthropic_1.ChatAnthropic({
             apiKey: config.anthropicAPIKey,
             maxTokens,
             modelName: modelName,
@@ -667,6 +902,7 @@ const getLLMModel = (modelName, config, schema = null) => {
             ...outputConfig,
             ...modelSettings,
         });
+        return webSearchTool ? model.bindTools([webSearchTool]) : model;
     }
     // Gemini models (Google)
     else if (modelName.startsWith("gemini-")) {
@@ -679,6 +915,11 @@ const getLLMModel = (modelName, config, schema = null) => {
             ...(schema ? { json: true } : {}),
             ...modelSettings,
         });
+        // Combining grounding with structured output requires Gemini 3 or later;
+        // Gemini 1.5/2.x reject `responseSchema` alongside `googleSearch` with a 400.
+        const bound = webSearchTool
+            ? model.bindTools([webSearchTool])
+            : model;
         // `responseSchema` additionally constrains the output shape. It is a
         // call-time option (not a constructor field), so it is bound onto the model
         // via `withConfig`. Gemini's schema is an OpenAPI 3.0 subset, so
@@ -686,9 +927,9 @@ const getLLMModel = (modelName, config, schema = null) => {
         // parse/validate pipeline is unchanged.
         if (schema) {
             const jsonSchema = sanitizeGeminiSchema(buildJsonSchema(schema));
-            return model.withConfig({ responseSchema: jsonSchema });
+            return bound.withConfig({ responseSchema: jsonSchema });
         }
-        return model;
+        return bound;
     }
     // GPT models (OpenAI)
     else if (modelName.startsWith("gpt-")) {
@@ -696,23 +937,41 @@ const getLLMModel = (modelName, config, schema = null) => {
             apiKey: config.openAIAPIKey,
             max_tokens: config.maxTokens || 200000,
             modelName: modelName,
+            // `web_search` is a hosted Responses API tool, so the request has to go to
+            // `/v1/responses` rather than `/v1/chat/completions`.
+            ...(webSearchTool ? { useResponsesApi: true } : {}),
             ...modelSettings,
         };
-        // Use native response_format with JSON schema for structured output
+        // Use native structured output with a JSON schema. The two endpoints spell
+        // the same thing differently — Chat Completions takes `response_format`,
+        // the Responses API takes `text.format` with the schema flattened one level
+        // — and `modelKwargs` is spread verbatim into whichever request is built.
         if (schema) {
             const jsonSchema = strictifyJsonSchema(buildJsonSchema(schema));
-            openAISettings.modelKwargs = {
-                response_format: {
-                    type: "json_schema",
-                    json_schema: {
-                        name: "response_schema",
-                        strict: true,
-                        schema: jsonSchema,
+            openAISettings.modelKwargs = webSearchTool
+                ? {
+                    text: {
+                        format: {
+                            type: "json_schema",
+                            name: "response_schema",
+                            strict: true,
+                            schema: jsonSchema,
+                        },
                     },
-                },
-            };
+                }
+                : {
+                    response_format: {
+                        type: "json_schema",
+                        json_schema: {
+                            name: "response_schema",
+                            strict: true,
+                            schema: jsonSchema,
+                        },
+                    },
+                };
         }
-        return new openai_1.ChatOpenAI(openAISettings);
+        const model = new openai_1.ChatOpenAI(openAISettings);
+        return webSearchTool ? model.bindTools([webSearchTool]) : model;
     }
     // OpenAI-compatible providers: DeepSeek, Kimi (Moonshot), GLM (Zhipu)
     const openAICompatible = getOpenAICompatibleProvider(modelName, config);
@@ -741,11 +1000,18 @@ const getLLMModel = (modelName, config, schema = null) => {
  * @returns A configured LangChain agent instance ready to be run with `runAgent`
  */
 const createAgent = (name, modelName, systemPrompt, tools = [], responseFormat, config) => {
+    // Native web search joins the agent's tool list instead of being bound inside
+    // `getLLMModel`: the agent binds its own tools to the model, which would drop
+    // anything already bound there.
+    const webSearchOptions = getWebSearchOptions(config);
+    const webSearchTool = webSearchOptions
+        ? buildWebSearchTool(modelName, webSearchOptions)
+        : null;
     const agent = (0, langchain_1.createAgent)({
         name: name,
-        model: getLLMModel(modelName, config),
+        model: getLLMModel(modelName, { ...config, webSearch: null }),
         systemPrompt: systemPrompt.trim(),
-        tools,
+        tools: webSearchTool ? [...tools, webSearchTool] : tools,
         ...(responseFormat ? { responseFormat: responseFormat } : {}),
     });
     return agent;
@@ -832,6 +1098,13 @@ const runAgent = async (agent, prompt, config, onProgress = null, usageTracker =
         }
     }
     updateUsageTracker(usageTracker, modelName, sumAgentResponseUsage(response), config);
+    // Web-search activity is spread across the agent's messages — one search may
+    // be reported by the message that ran it and cited by a later one.
+    const webSearchUsage = createWebSearchUsage();
+    for (const message of response?.messages || []) {
+        collectWebSearchUsage(message, webSearchUsage);
+    }
+    updateWebSearchUsageTracker(usageTracker, modelName, webSearchUsage, config);
     const endTime = Date.now();
     const duration = endTime - startTime;
     logger_js_1.default.log(null, logger_js_1.default.levels.info, `Agent "${agent.options?.name}" completed in ${Math.round(duration / 1000)} seconds.`);
@@ -1068,10 +1341,16 @@ const buildValidationRetryMessages = (priorMessages, rawContent, validationError
  *
  * When `expectsJsonResponse` is `true`, JSON escape instructions are prepended to the
  * system prompt and the parsed result is optionally validated against `schema`.
+ *
+ * Setting `config.webSearch` enables the provider's native web search tool in every
+ * mode (see `buildWebSearchTool`). The provider runs the search server-side inside the
+ * same request, so the return contract is unchanged; the searches performed and the
+ * sources cited are recorded on `usageTracker`.
  * @param modelName - The model identifier, e.g. `"gpt-4o"`, `"claude-3-5-sonnet"`,
  *   `"gemini-1.5-pro"`
  * @param config - Configuration object with API keys, `temperature`, optional `agentic`
- *   flag, and optional `recursionLimit`
+ *   flag, optional `recursionLimit`, and optional `webSearch` (`true` or a
+ *   `WebSearchConfig`)
  * @param prompt - The prompt to send; either a plain string (user message only) or an
  *   array of `{ role, content }` message objects
  * @param onProgressReport - Optional async callback invoked with `{ message, progress }`
@@ -1133,12 +1412,9 @@ const runPromptWithModel = async (modelName, config, prompt, onProgressReport, m
             throw errorHandling_js_1.default.create(const_js_1.default.HTTP_CODES.INTERNAL_SERVER_ERROR, "Agent returned no messages");
         }
         const lastMessage = messages[messages.length - 1];
-        let rawContent = lastMessage?.content || "";
-        // Handle array content blocks (e.g., from Gemini/Claude agent responses)
-        if (Array.isArray(rawContent)) {
-            const textBlock = rawContent.find((block) => typeof block === "object" && block.type === "text");
-            rawContent = textBlock?.text || "";
-        }
+        // Flattens the array content blocks that Gemini/Claude agent responses and
+        // any server-tool turn (e.g. web search) return.
+        const rawContent = extractTextContent(lastMessage?.content);
         // If not expecting JSON, return raw content directly
         if (!expectsJsonResponse) {
             return rawContent;
@@ -1260,6 +1536,7 @@ const runPromptWithModel = async (modelName, config, prompt, onProgressReport, m
                 output_tokens: 0,
                 total_tokens: 0,
             };
+            let webSearchUsage = createWebSearchUsage();
             // Inner loop: wait + retry on 429 around stream setup and consumption.
             // Usage is only recorded on a successful stream — partial streams that
             // error out with a rate limit are not counted. A 429 fired mid-stream
@@ -1269,6 +1546,7 @@ const runPromptWithModel = async (modelName, config, prompt, onProgressReport, m
                 rawContent = "";
                 chunkCount = 0;
                 streamUsage = { input_tokens: 0, output_tokens: 0, total_tokens: 0 };
+                webSearchUsage = createWebSearchUsage();
                 try {
                     // Honour caller cancellation: passing the signal tears down the
                     // upstream HTTP request so a cancelled call stops billing tokens.
@@ -1281,16 +1559,16 @@ const runPromptWithModel = async (modelName, config, prompt, onProgressReport, m
                             throw errorHandling_js_1.default.create(const_js_1.default.HTTP_CODES.BAD_REQUEST, "Request cancelled by caller");
                         }
                         accumulateChunkUsage(streamUsage, chunk);
-                        const content = chunk?.content || chunk;
-                        if (typeof content === "string") {
-                            rawContent += content;
-                            chunkCount++;
-                            if (chunkCount % progressReportInterval === 0) {
-                                await onProgressReport({
-                                    message: "Generating content...",
-                                    progress: Math.min(calcCurrentProgress(), maxPercent - 5),
-                                });
-                            }
+                        collectWebSearchUsage(chunk, webSearchUsage);
+                        // Counting every chunk (not just the ones carrying text) keeps
+                        // progress ticking through the pause while a search runs.
+                        chunkCount++;
+                        rawContent += extractTextContent(chunk?.content ?? chunk);
+                        if (chunkCount % progressReportInterval === 0) {
+                            await onProgressReport({
+                                message: "Generating content...",
+                                progress: Math.min(calcCurrentProgress(), maxPercent - 5),
+                            });
                         }
                     }
                     break; // stream completed without 429
@@ -1313,6 +1591,7 @@ const runPromptWithModel = async (modelName, config, prompt, onProgressReport, m
                 }
             }
             updateUsageTracker(usageTracker, modelName, streamUsage, config);
+            updateWebSearchUsageTracker(usageTracker, modelName, webSearchUsage, config);
             if (!rawContent) {
                 throw errorHandling_js_1.default.create(const_js_1.default.HTTP_CODES.INTERNAL_SERVER_ERROR, "LLM returned no content");
             }
@@ -1417,7 +1696,11 @@ const runPromptWithModel = async (modelName, config, prompt, onProgressReport, m
                 }
             }
             updateUsageTracker(usageTracker, modelName, extractUsageFromInvoke(response), config);
-            const rawContent = response?.content || response;
+            const webSearchUsage = createWebSearchUsage();
+            collectWebSearchUsage(response, webSearchUsage);
+            updateWebSearchUsageTracker(usageTracker, modelName, webSearchUsage, config);
+            // Flattened because a server-tool turn returns content blocks, not a string.
+            const rawContent = extractTextContent(response?.content ?? response);
             // If not expecting JSON, return raw content directly
             if (!expectsJsonResponse) {
                 return rawContent;

package/dist/esm/index.d.ts

@@ -9,7 +9,7 @@ export { constants };
 export { errorHandling, AppError };
 export type { ParsedError } from "./errorHandling.js";
 export { langChain };
-export type { UsageTracker } from "./langChain.js";
+export type { UsageTracker, WebSearchConfig } from "./langChain.js";
 export { logger };
 export { serve };
 export { callAgent };

package/dist/esm/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,SAAS,MAAM,YAAY,CAAC;AACnC,OAAO,aAAa,EAAE,EAAE,QAAQ,EAAE,MAAM,oBAAoB,CAAC;AAC7D,OAAO,SAAS,MAAM,gBAAgB,CAAC;AACvC,OAAO,MAAM,MAAM,aAAa,CAAC;AACjC,OAAO,EAAE,KAAK,EAAE,MAAM,YAAY,CAAC;AACnC,OAAO,EAAE,SAAS,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AACpD,OAAO,KAAK,cAAc,MAAM,qBAAqB,CAAC;AAEtD,OAAO,EAAE,SAAS,EAAE,CAAC;AAErB,OAAO,EAAE,aAAa,EAAE,QAAQ,EAAE,CAAC;AAEnC,YAAY,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AAEtD,OAAO,EAAE,SAAS,EAAE,CAAC;AAErB,YAAY,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AAEnD,OAAO,EAAE,MAAM,EAAE,CAAC;AAElB,OAAO,EAAE,KAAK,EAAE,CAAC;AAEjB,OAAO,EAAE,SAAS,EAAE,CAAC;AAErB,OAAO,EAAE,UAAU,EAAE,CAAC;AAEtB,YAAY,EACV,mBAAmB,EACnB,gBAAgB,EAChB,iBAAiB,EACjB,WAAW,GACZ,MAAM,aAAa,CAAC;AAErB,OAAO,EAAE,cAAc,EAAE,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,SAAS,MAAM,YAAY,CAAC;AACnC,OAAO,aAAa,EAAE,EAAE,QAAQ,EAAE,MAAM,oBAAoB,CAAC;AAC7D,OAAO,SAAS,MAAM,gBAAgB,CAAC;AACvC,OAAO,MAAM,MAAM,aAAa,CAAC;AACjC,OAAO,EAAE,KAAK,EAAE,MAAM,YAAY,CAAC;AACnC,OAAO,EAAE,SAAS,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AACpD,OAAO,KAAK,cAAc,MAAM,qBAAqB,CAAC;AAEtD,OAAO,EAAE,SAAS,EAAE,CAAC;AAErB,OAAO,EAAE,aAAa,EAAE,QAAQ,EAAE,CAAC;AAEnC,YAAY,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AAEtD,OAAO,EAAE,SAAS,EAAE,CAAC;AAErB,YAAY,EAAE,YAAY,EAAE,eAAe,EAAE,MAAM,gBAAgB,CAAC;AAEpE,OAAO,EAAE,MAAM,EAAE,CAAC;AAElB,OAAO,EAAE,KAAK,EAAE,CAAC;AAEjB,OAAO,EAAE,SAAS,EAAE,CAAC;AAErB,OAAO,EAAE,UAAU,EAAE,CAAC;AAEtB,YAAY,EACV,mBAAmB,EACnB,gBAAgB,EAChB,iBAAiB,EACjB,WAAW,GACZ,MAAM,aAAa,CAAC;AAErB,OAAO,EAAE,cAAc,EAAE,CAAC"}

package/dist/esm/langChain.d.ts

@@ -9,6 +9,73 @@ export type UsageTracker = {
     tokens: {
         [tokenKey: string]: number;
     };
+    /**
+     * Sources returned by native web search, deduplicated by URL across every
+     * call in the run. Only present once a search has actually run. Anthropic and
+     * Google both require the original sources to be cited when their output is
+     * shown to end users, so they are surfaced here rather than discarded with
+     * the rest of the non-text content blocks.
+     */
+    webSearchSources?: {
+        url: string;
+        title?: string;
+    }[];
+};
+/**
+ * Caller-facing options for the providers' native web search tools. Enable web
+ * search by setting `config.webSearch` to `true` (provider defaults) or to one
+ * of these objects. Every field is optional and is only forwarded to the
+ * providers that accept it — see `buildWebSearchTool` for the mapping.
+ */
+export type WebSearchConfig = {
+    /** Anthropic only: hard cap on searches per request (`max_uses`). */
+    maxUses?: number;
+    /** Anthropic (`allowed_domains`) and OpenAI (`filters.allowed_domains`). */
+    allowedDomains?: string[];
+    /** Anthropic only (`blocked_domains`); cannot be combined with `allowedDomains`. */
+    blockedDomains?: string[];
+    /** Anthropic and OpenAI: approximate location used to localize results. */
+    userLocation?: {
+        city?: string;
+        region?: string;
+        /** Two-letter ISO 3166-1 alpha-2 code, e.g. `"US"`. */
+        country?: string;
+        /** IANA timezone ID, e.g. `"America/Los_Angeles"`. */
+        timezone?: string;
+    };
+    /**
+     * OpenAI only: how much of the context window search results may consume.
+     * OpenAI's default is `"medium"`; `"low"` minimizes context at some cost to
+     * answer quality, `"high"` is the expensive end.
+     */
+    searchContextSize?: "low" | "medium" | "high";
+    /** Gemini only: RFC 3339 window the search is restricted to. */
+    timeRange?: {
+        startTime: string;
+        endTime: string;
+    };
+    /**
+     * Anthropic only: opt out of dynamic filtering by forcing the search to be
+     * called directly (`allowed_callers: ["direct"]`). Defaults to `true` on
+     * models that support it — see `supportsAnthropicDynamicFiltering`. Turning
+     * this off means every raw search result lands in the context window.
+     */
+    dynamicFiltering?: boolean;
+    /**
+     * Anthropic only: whether search result blocks consumed by dynamic filtering
+     * are echoed back in the response. Defaults to `"excluded"`, which drops them
+     * and cuts the output tokens billed for content nothing downstream reads.
+     */
+    responseInclusion?: "full" | "excluded";
+    /**
+     * Anthropic only: pin the dated tool version instead of letting
+     * `buildWebSearchTool` pick per model. `web_search_20250305` is basic search,
+     * `web_search_20260209` adds dynamic filtering, `web_search_20260318` adds
+     * response-inclusion control. Pinning a filtering version on a model that
+     * cannot do programmatic tool calling returns a 400 unless
+     * `dynamicFiltering: false` is also set.
+     */
+    toolVersion?: string;
 };
 declare const _default: {
     checkIfAIProviderConfigured: (config: any) => void;

package/dist/esm/langChain.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"langChain.d.ts","sourceRoot":"","sources":["../../src/langChain.ts"],"names":[],"mappings":"AAuGA;;;;;GAKG;AACH,MAAM,MAAM,YAAY,GAAG;IACzB,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE;QAAE,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAAA;KAAE,CAAC;CACxC,CAAC;;0CAE2C,GAAG,KAAG,IAAI;wBAktB/C,MAAM,aACD,MAAM,gBACH,MAAM,SACb,GAAG,EAAE,kBACI,GAAG,UACX,GAAG,KACV,GAAG;sBA0BG,GAAG,UACF,MAAM,UACN,GAAG,eACC,QAAQ,GAAG,IAAI,iBACb,YAAY,GAAG,IAAI,KAChC,OAAO,CAAC,GAAG,CAAC;oCA4XF,MAAM,UACT,GAAG,UACH,GAAG,oBACO,GAAG,eACT,MAAM,eACN,MAAM,wBACG,OAAO,WACpB,GAAG,cACA,MAAM,UACV,GAAG,EAAE,iBACE,YAAY,GAAG,IAAI,KAChC,OAAO,CAAC,GAAG,CAAC;sDA2tBF,MAAM,UACT,GAAG,UACH,MAAM,YACL,GAAG,iBACE,YAAY,GAAG,IAAI,KAChC,OAAO,CAAC,GAAG,CAAC;0CA//B8B,GAAG,KAAG,MAAM;+CAprB9C,YAAY,GAAG,IAAI,GAAG,SAAS,aAC7B,MAAM,kBACD,MAAM,UACd,GAAG,KACV,IAAI;mCAosBU,MAAM,mBACJ,MAAM,EAAE,KACxB,MAAM;;AAsiCT,wBASE"}
+{"version":3,"file":"langChain.d.ts","sourceRoot":"","sources":["../../src/langChain.ts"],"names":[],"mappings":"AAuGA;;;;;GAKG;AACH,MAAM,MAAM,YAAY,GAAG;IACzB,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE;QAAE,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAAA;KAAE,CAAC;IACvC;;;;;;OAMG;IACH,gBAAgB,CAAC,EAAE;QAAE,GAAG,EAAE,MAAM,CAAC;QAAC,KAAK,CAAC,EAAE,MAAM,CAAA;KAAE,EAAE,CAAC;CACtD,CAAC;AAskBF;;;;;GAKG;AACH,MAAM,MAAM,eAAe,GAAG;IAC5B,qEAAqE;IACrE,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,4EAA4E;IAC5E,cAAc,CAAC,EAAE,MAAM,EAAE,CAAC;IAC1B,oFAAoF;IACpF,cAAc,CAAC,EAAE,MAAM,EAAE,CAAC;IAC1B,2EAA2E;IAC3E,YAAY,CAAC,EAAE;QACb,IAAI,CAAC,EAAE,MAAM,CAAC;QACd,MAAM,CAAC,EAAE,MAAM,CAAC;QAChB,uDAAuD;QACvD,OAAO,CAAC,EAAE,MAAM,CAAC;QACjB,sDAAsD;QACtD,QAAQ,CAAC,EAAE,MAAM,CAAC;KACnB,CAAC;IACF;;;;OAIG;IACH,iBAAiB,CAAC,EAAE,KAAK,GAAG,QAAQ,GAAG,MAAM,CAAC;IAC9C,gEAAgE;IAChE,SAAS,CAAC,EAAE;QAAE,SAAS,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,CAAC;IACnD;;;;;OAKG;IACH,gBAAgB,CAAC,EAAE,OAAO,CAAC;IAC3B;;;;OAIG;IACH,iBAAiB,CAAC,EAAE,MAAM,GAAG,UAAU,CAAC;IACxC;;;;;;;OAOG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB,CAAC;;0CAxnB2C,GAAG,KAAG,IAAI;wBAujC/C,MAAM,aACD,MAAM,gBACH,MAAM,SACb,GAAG,EAAE,kBACI,GAAG,UACX,GAAG,KACV,GAAG;sBAiCG,GAAG,UACF,MAAM,UACN,GAAG,eACC,QAAQ,GAAG,IAAI,iBACb,YAAY,GAAG,IAAI,KAChC,OAAO,CAAC,GAAG,CAAC;oCA0YF,MAAM,UACT,GAAG,UACH,GAAG,oBACO,GAAG,eACT,MAAM,eACN,MAAM,wBACG,OAAO,WACpB,GAAG,cACA,MAAM,UACV,GAAG,EAAE,iBACE,YAAY,GAAG,IAAI,KAChC,OAAO,CAAC,GAAG,CAAC;sDAuuBF,MAAM,UACT,GAAG,UACH,MAAM,YACL,GAAG,iBACE,YAAY,GAAG,IAAI,KAChC,OAAO,CAAC,GAAG,CAAC;0CAjhC8B,GAAG,KAAG,MAAM;+CAviC9C,YAAY,GAAG,IAAI,GAAG,SAAS,aAC7B,MAAM,kBACD,MAAM,UACd,GAAG,KACV,IAAI;mCAujCU,MAAM,mBACJ,MAAM,EAAE,KACxB,MAAM;;AAwjCT,wBASE"}

package/dist/esm/langChain.js

@@ -603,6 +603,234 @@ const resolveTemperatureSetting = (modelName, config) => {
     }
     return { temperature: clamped };
 };
+/**
+ * Whether a Claude model can run web search through dynamic filtering, where
+ * Claude writes and runs code that filters the search results before they reach
+ * the context window instead of loading every result into it. Requires Claude
+ * 4.6 or later (the models with programmatic tool calling); on anything earlier
+ * the filtering tool versions return a 400 unless search is pinned to
+ * `allowed_callers: ["direct"]`.
+ * @param modelName - The Claude model identifier being routed
+ * @returns `true` when the model supports dynamic filtering
+ */
+const supportsAnthropicDynamicFiltering = (modelName) => /^claude-(opus|sonnet|haiku)-4-(?:[6-9]|\d\d)\b/.test(modelName) ||
+    /^claude-(opus|sonnet|haiku|fable|mythos)-(?:[5-9]|\d\d)\b/.test(modelName);
+/**
+ * Normalizes `config.webSearch` into an options object, returning `null` when
+ * web search is off so callers can use it as the single enablement gate.
+ */
+const getWebSearchOptions = (config) => {
+    const webSearch = config?.webSearch;
+    if (!webSearch)
+        return null;
+    return webSearch === true ? {} : webSearch;
+};
+/**
+ * Builds the provider-native web search tool definition for a model:
+ *  - `claude-` → Anthropic's `web_search` server tool, executed by the Messages
+ *    API within a single request and answered with citations. Defaults to the
+ *    dynamic-filtering tool version on models that support it, so search results
+ *    are filtered by code before they reach the context window.
+ *  - `gpt-` → OpenAI's hosted `web_search` tool (Responses API). Context spend
+ *    is governed by `search_context_size` (OpenAI defaults to `medium`).
+ *  - `gemini-` → Google's `googleSearch` grounding tool. Google exposes no
+ *    result-filtering or context-size control; leaving `searchTypes` unset keeps
+ *    grounding on text-only web results rather than image bytes.
+ * Returns `null` for providers with no native web search (DeepSeek, Kimi, GLM),
+ * warning instead of throwing so one config can be pointed at any model.
+ * @param modelName - The model identifier being routed
+ * @param options - Normalized options from `getWebSearchOptions`
+ * @returns The provider's tool definition, or `null` when unsupported
+ */
+const buildWebSearchTool = (modelName, options) => {
+    const { allowedDomains, blockedDomains, userLocation } = options;
+    if (modelName.startsWith("claude-")) {
+        // The API returns a 400 when both filters are present, so fail locally
+        // rather than paying for the round trip.
+        if (allowedDomains && blockedDomains) {
+            throw errorHandlingHelper.create(constants.HTTP_CODES.BAD_REQUEST, "Anthropic web search accepts allowedDomains or blockedDomains, not both.");
+        }
+        // Prefer the newest tool version the model can actually run. Basic search
+        // loads every result into the context window; from `web_search_20260209`
+        // Claude filters them with code first, and `web_search_20260318` can also
+        // keep the consumed results out of the response.
+        const canFilter = supportsAnthropicDynamicFiltering(modelName);
+        const type = options.toolVersion ||
+            (canFilter ? "web_search_20260318" : "web_search_20250305");
+        const version = Number(type.slice(-8));
+        // Filtering versions default to running search from inside code execution.
+        // Say so explicitly when it is not wanted (or not possible), which is what
+        // the API requires from models without programmatic tool calling.
+        const directOnly = version >= 20260209 && (options.dynamicFiltering === false || !canFilter);
+        return {
+            type,
+            name: "web_search",
+            ...(options.maxUses ? { max_uses: options.maxUses } : {}),
+            ...(allowedDomains ? { allowed_domains: allowedDomains } : {}),
+            ...(blockedDomains ? { blocked_domains: blockedDomains } : {}),
+            ...(userLocation
+                ? { user_location: { type: "approximate", ...userLocation } }
+                : {}),
+            ...(directOnly ? { allowed_callers: ["direct"] } : {}),
+            ...(version >= 20260318
+                ? { response_inclusion: options.responseInclusion || "excluded" }
+                : {}),
+        };
+    }
+    if (modelName.startsWith("gpt-")) {
+        return {
+            type: "web_search",
+            ...(allowedDomains
+                ? { filters: { allowed_domains: allowedDomains } }
+                : {}),
+            ...(userLocation
+                ? { user_location: { type: "approximate", ...userLocation } }
+                : {}),
+            ...(options.searchContextSize
+                ? { search_context_size: options.searchContextSize }
+                : {}),
+        };
+    }
+    if (modelName.startsWith("gemini-")) {
+        // `timeRangeFilter` is the only filter the Gemini API exposes;
+        // `excludeDomains` is a Vertex AI field and is rejected here, so domain
+        // filters are deliberately not mapped for Google.
+        return {
+            googleSearch: options.timeRange
+                ? { timeRangeFilter: options.timeRange }
+                : {},
+        };
+    }
+    logger.log(null, logger.levels.warn, `Model "${modelName}" has no native web search tool; ignoring the configured webSearch options.`);
+    return null;
+};
+/**
+ * Flattens LangChain message content into plain text. Content is a string for
+ * ordinary completions, but every provider switches to an array of blocks once
+ * a server-side tool runs — Anthropic interleaves `server_tool_use` and
+ * `web_search_tool_result` blocks with the answer text, and OpenAI's Responses
+ * API returns annotated text blocks — so without this the JSON parse pipeline
+ * would receive a non-string and every web-search call would fail.
+ * @param content - A message's `content` field, or a raw string
+ * @returns The concatenated text of all text blocks
+ */
+const extractTextContent = (content) => {
+    if (typeof content === "string")
+        return content;
+    if (!Array.isArray(content))
+        return "";
+    let text = "";
+    for (const block of content) {
+        if (typeof block === "string")
+            text += block;
+        else if (block?.type === "text" && typeof block.text === "string") {
+            text += block.text;
+        }
+    }
+    return text;
+};
+const createWebSearchUsage = () => ({
+    reportedRequests: 0,
+    callIds: new Set(),
+    grounded: false,
+    sources: new Map(),
+});
+/**
+ * Folds one message — or one streaming chunk — into a `WebSearchUsage`. Safe to
+ * call on every chunk of a stream and on messages that involved no search.
+ */
+const collectWebSearchUsage = (payload, usage) => {
+    if (!payload)
+        return;
+    const addSource = (url, title) => {
+        if (typeof url === "string" && url && !usage.sources.has(url)) {
+            usage.sources.set(url, {
+                url,
+                ...(typeof title === "string" ? { title } : {}),
+            });
+        }
+    };
+    if (Array.isArray(payload.content)) {
+        for (const block of payload.content) {
+            if (!block || typeof block !== "object")
+                continue;
+            // Anthropic: results of a search the API executed server-side.
+            if (block.type === "web_search_tool_result" &&
+                Array.isArray(block.content)) {
+                for (const result of block.content) {
+                    addSource(result?.url, result?.title);
+                }
+            }
+            // Anthropic: citations attached to the answer's text blocks.
+            if (Array.isArray(block.citations)) {
+                for (const citation of block.citations) {
+                    addSource(citation?.url, citation?.title);
+                }
+            }
+            // OpenAI Responses API: one block per executed search, plus url citations.
+            if (block.type === "web_search_call" && block.id) {
+                usage.callIds.add(block.id);
+            }
+            if (Array.isArray(block.annotations)) {
+                for (const annotation of block.annotations) {
+                    if (annotation?.type === "url_citation") {
+                        addSource(annotation.url, annotation.title);
+                    }
+                }
+            }
+        }
+    }
+    const metadata = payload.response_metadata;
+    if (!metadata)
+        return;
+    const requests = metadata.usage?.server_tool_use?.web_search_requests;
+    if (typeof requests === "number" && requests > usage.reportedRequests) {
+        usage.reportedRequests = requests;
+    }
+    const grounding = metadata.groundingMetadata;
+    if (grounding) {
+        usage.grounded = true;
+        for (const chunk of grounding.groundingChunks || []) {
+            addSource(chunk?.web?.uri, chunk?.web?.title);
+        }
+    }
+};
+/**
+ * Adds a call's web-search usage to the caller-supplied tracker. Searches are
+ * billed per request rather than per token (Anthropic charges $10 per 1,000
+ * searches; Google charges per grounded request), so the rate is read from the
+ * `<model>-web-search-costs` constant expressed in USD per 1,000 searches and
+ * accumulated under `<model>_webSearches`. Sources are appended to
+ * `tracker.webSearchSources`, deduplicated by URL across the whole run.
+ */
+const updateWebSearchUsageTracker = (tracker, modelName, usage, config) => {
+    if (!tracker || !modelName)
+        return;
+    // The three signals describe the same searches from different providers, so
+    // the largest one is the count rather than their sum.
+    const searches = Math.max(usage.reportedRequests, usage.callIds.size, usage.grounded ? 1 : 0);
+    if (!searches && usage.sources.size === 0)
+        return;
+    if (typeof tracker.cost !== "number")
+        tracker.cost = 0;
+    if (!tracker.tokens || typeof tracker.tokens !== "object")
+        tracker.tokens = {};
+    if (searches > 0) {
+        const addedCost = (searches / 1_000) * getModelRate(modelName, config, "web-search");
+        if (Number.isFinite(addedCost) && addedCost > 0)
+            tracker.cost += addedCost;
+        const key = `${modelName}_webSearches`;
+        tracker.tokens[key] = (tracker.tokens[key] || 0) + searches;
+    }
+    if (usage.sources.size > 0) {
+        const sources = tracker.webSearchSources || (tracker.webSearchSources = []);
+        for (const source of usage.sources.values()) {
+            if (!sources.some((existing) => existing.url === source.url)) {
+                sources.push(source);
+            }
+        }
+    }
+};
 /**
  * Instantiates and returns the appropriate LangChain chat model based on the model
  * name prefix. `claude-` maps to `ChatAnthropic`, `gemini-` maps to
@@ -629,6 +857,13 @@ const getLLMModel = (modelName, config, schema = null) => {
     // Resolve `temperature` with presence/support/range handling (see
     // resolveTemperatureSetting). Applied uniformly to every provider below.
     const modelSettings = resolveTemperatureSetting(modelName, config);
+    // Native web search (see buildWebSearchTool). The tool is bound to the model
+    // so both `.invoke()` and `.stream()` pick it up; the provider runs the search
+    // server-side within the same request, so no client-side agent loop is needed.
+    const webSearchOptions = getWebSearchOptions(config);
+    const webSearchTool = webSearchOptions
+        ? buildWebSearchTool(modelName, webSearchOptions)
+        : null;
     // Claude models (Anthropic)
     if (modelName.startsWith("claude-")) {
         // Anthropic's SDK rejects non-streamed requests when max_tokens is large
@@ -653,7 +888,7 @@ const getLLMModel = (modelName, config, schema = null) => {
                 },
             }
             : {};
-        return new ChatAnthropic({
+        const model = new ChatAnthropic({
             apiKey: config.anthropicAPIKey,
             maxTokens,
             modelName: modelName,
@@ -662,6 +897,7 @@ const getLLMModel = (modelName, config, schema = null) => {
             ...outputConfig,
             ...modelSettings,
         });
+        return webSearchTool ? model.bindTools([webSearchTool]) : model;
     }
     // Gemini models (Google)
     else if (modelName.startsWith("gemini-")) {
@@ -674,6 +910,11 @@ const getLLMModel = (modelName, config, schema = null) => {
             ...(schema ? { json: true } : {}),
             ...modelSettings,
         });
+        // Combining grounding with structured output requires Gemini 3 or later;
+        // Gemini 1.5/2.x reject `responseSchema` alongside `googleSearch` with a 400.
+        const bound = webSearchTool
+            ? model.bindTools([webSearchTool])
+            : model;
         // `responseSchema` additionally constrains the output shape. It is a
         // call-time option (not a constructor field), so it is bound onto the model
         // via `withConfig`. Gemini's schema is an OpenAPI 3.0 subset, so
@@ -681,9 +922,9 @@ const getLLMModel = (modelName, config, schema = null) => {
         // parse/validate pipeline is unchanged.
         if (schema) {
             const jsonSchema = sanitizeGeminiSchema(buildJsonSchema(schema));
-            return model.withConfig({ responseSchema: jsonSchema });
+            return bound.withConfig({ responseSchema: jsonSchema });
         }
-        return model;
+        return bound;
     }
     // GPT models (OpenAI)
     else if (modelName.startsWith("gpt-")) {
@@ -691,23 +932,41 @@ const getLLMModel = (modelName, config, schema = null) => {
             apiKey: config.openAIAPIKey,
             max_tokens: config.maxTokens || 200000,
             modelName: modelName,
+            // `web_search` is a hosted Responses API tool, so the request has to go to
+            // `/v1/responses` rather than `/v1/chat/completions`.
+            ...(webSearchTool ? { useResponsesApi: true } : {}),
             ...modelSettings,
         };
-        // Use native response_format with JSON schema for structured output
+        // Use native structured output with a JSON schema. The two endpoints spell
+        // the same thing differently — Chat Completions takes `response_format`,
+        // the Responses API takes `text.format` with the schema flattened one level
+        // — and `modelKwargs` is spread verbatim into whichever request is built.
         if (schema) {
             const jsonSchema = strictifyJsonSchema(buildJsonSchema(schema));
-            openAISettings.modelKwargs = {
-                response_format: {
-                    type: "json_schema",
-                    json_schema: {
-                        name: "response_schema",
-                        strict: true,
-                        schema: jsonSchema,
+            openAISettings.modelKwargs = webSearchTool
+                ? {
+                    text: {
+                        format: {
+                            type: "json_schema",
+                            name: "response_schema",
+                            strict: true,
+                            schema: jsonSchema,
+                        },
                     },
-                },
-            };
+                }
+                : {
+                    response_format: {
+                        type: "json_schema",
+                        json_schema: {
+                            name: "response_schema",
+                            strict: true,
+                            schema: jsonSchema,
+                        },
+                    },
+                };
         }
-        return new ChatOpenAI(openAISettings);
+        const model = new ChatOpenAI(openAISettings);
+        return webSearchTool ? model.bindTools([webSearchTool]) : model;
     }
     // OpenAI-compatible providers: DeepSeek, Kimi (Moonshot), GLM (Zhipu)
     const openAICompatible = getOpenAICompatibleProvider(modelName, config);
@@ -736,11 +995,18 @@ const getLLMModel = (modelName, config, schema = null) => {
  * @returns A configured LangChain agent instance ready to be run with `runAgent`
  */
 const createAgent = (name, modelName, systemPrompt, tools = [], responseFormat, config) => {
+    // Native web search joins the agent's tool list instead of being bound inside
+    // `getLLMModel`: the agent binds its own tools to the model, which would drop
+    // anything already bound there.
+    const webSearchOptions = getWebSearchOptions(config);
+    const webSearchTool = webSearchOptions
+        ? buildWebSearchTool(modelName, webSearchOptions)
+        : null;
     const agent = createLangChainAgent({
         name: name,
-        model: getLLMModel(modelName, config),
+        model: getLLMModel(modelName, { ...config, webSearch: null }),
         systemPrompt: systemPrompt.trim(),
-        tools,
+        tools: webSearchTool ? [...tools, webSearchTool] : tools,
         ...(responseFormat ? { responseFormat: responseFormat } : {}),
     });
     return agent;
@@ -827,6 +1093,13 @@ const runAgent = async (agent, prompt, config, onProgress = null, usageTracker =
         }
     }
     updateUsageTracker(usageTracker, modelName, sumAgentResponseUsage(response), config);
+    // Web-search activity is spread across the agent's messages — one search may
+    // be reported by the message that ran it and cited by a later one.
+    const webSearchUsage = createWebSearchUsage();
+    for (const message of response?.messages || []) {
+        collectWebSearchUsage(message, webSearchUsage);
+    }
+    updateWebSearchUsageTracker(usageTracker, modelName, webSearchUsage, config);
     const endTime = Date.now();
     const duration = endTime - startTime;
     logger.log(null, logger.levels.info, `Agent "${agent.options?.name}" completed in ${Math.round(duration / 1000)} seconds.`);
@@ -1063,10 +1336,16 @@ const buildValidationRetryMessages = (priorMessages, rawContent, validationError
  *
  * When `expectsJsonResponse` is `true`, JSON escape instructions are prepended to the
  * system prompt and the parsed result is optionally validated against `schema`.
+ *
+ * Setting `config.webSearch` enables the provider's native web search tool in every
+ * mode (see `buildWebSearchTool`). The provider runs the search server-side inside the
+ * same request, so the return contract is unchanged; the searches performed and the
+ * sources cited are recorded on `usageTracker`.
  * @param modelName - The model identifier, e.g. `"gpt-4o"`, `"claude-3-5-sonnet"`,
  *   `"gemini-1.5-pro"`
  * @param config - Configuration object with API keys, `temperature`, optional `agentic`
- *   flag, and optional `recursionLimit`
+ *   flag, optional `recursionLimit`, and optional `webSearch` (`true` or a
+ *   `WebSearchConfig`)
  * @param prompt - The prompt to send; either a plain string (user message only) or an
  *   array of `{ role, content }` message objects
  * @param onProgressReport - Optional async callback invoked with `{ message, progress }`
@@ -1128,12 +1407,9 @@ const runPromptWithModel = async (modelName, config, prompt, onProgressReport, m
             throw errorHandlingHelper.create(constants.HTTP_CODES.INTERNAL_SERVER_ERROR, "Agent returned no messages");
         }
         const lastMessage = messages[messages.length - 1];
-        let rawContent = lastMessage?.content || "";
-        // Handle array content blocks (e.g., from Gemini/Claude agent responses)
-        if (Array.isArray(rawContent)) {
-            const textBlock = rawContent.find((block) => typeof block === "object" && block.type === "text");
-            rawContent = textBlock?.text || "";
-        }
+        // Flattens the array content blocks that Gemini/Claude agent responses and
+        // any server-tool turn (e.g. web search) return.
+        const rawContent = extractTextContent(lastMessage?.content);
         // If not expecting JSON, return raw content directly
         if (!expectsJsonResponse) {
             return rawContent;
@@ -1255,6 +1531,7 @@ const runPromptWithModel = async (modelName, config, prompt, onProgressReport, m
                 output_tokens: 0,
                 total_tokens: 0,
             };
+            let webSearchUsage = createWebSearchUsage();
             // Inner loop: wait + retry on 429 around stream setup and consumption.
             // Usage is only recorded on a successful stream — partial streams that
             // error out with a rate limit are not counted. A 429 fired mid-stream
@@ -1264,6 +1541,7 @@ const runPromptWithModel = async (modelName, config, prompt, onProgressReport, m
                 rawContent = "";
                 chunkCount = 0;
                 streamUsage = { input_tokens: 0, output_tokens: 0, total_tokens: 0 };
+                webSearchUsage = createWebSearchUsage();
                 try {
                     // Honour caller cancellation: passing the signal tears down the
                     // upstream HTTP request so a cancelled call stops billing tokens.
@@ -1276,16 +1554,16 @@ const runPromptWithModel = async (modelName, config, prompt, onProgressReport, m
                             throw errorHandlingHelper.create(constants.HTTP_CODES.BAD_REQUEST, "Request cancelled by caller");
                         }
                         accumulateChunkUsage(streamUsage, chunk);
-                        const content = chunk?.content || chunk;
-                        if (typeof content === "string") {
-                            rawContent += content;
-                            chunkCount++;
-                            if (chunkCount % progressReportInterval === 0) {
-                                await onProgressReport({
-                                    message: "Generating content...",
-                                    progress: Math.min(calcCurrentProgress(), maxPercent - 5),
-                                });
-                            }
+                        collectWebSearchUsage(chunk, webSearchUsage);
+                        // Counting every chunk (not just the ones carrying text) keeps
+                        // progress ticking through the pause while a search runs.
+                        chunkCount++;
+                        rawContent += extractTextContent(chunk?.content ?? chunk);
+                        if (chunkCount % progressReportInterval === 0) {
+                            await onProgressReport({
+                                message: "Generating content...",
+                                progress: Math.min(calcCurrentProgress(), maxPercent - 5),
+                            });
                         }
                     }
                     break; // stream completed without 429
@@ -1308,6 +1586,7 @@ const runPromptWithModel = async (modelName, config, prompt, onProgressReport, m
                 }
             }
             updateUsageTracker(usageTracker, modelName, streamUsage, config);
+            updateWebSearchUsageTracker(usageTracker, modelName, webSearchUsage, config);
             if (!rawContent) {
                 throw errorHandlingHelper.create(constants.HTTP_CODES.INTERNAL_SERVER_ERROR, "LLM returned no content");
             }
@@ -1412,7 +1691,11 @@ const runPromptWithModel = async (modelName, config, prompt, onProgressReport, m
                 }
             }
             updateUsageTracker(usageTracker, modelName, extractUsageFromInvoke(response), config);
-            const rawContent = response?.content || response;
+            const webSearchUsage = createWebSearchUsage();
+            collectWebSearchUsage(response, webSearchUsage);
+            updateWebSearchUsageTracker(usageTracker, modelName, webSearchUsage, config);
+            // Flattened because a server-tool turn returns content blocks, not a string.
+            const rawContent = extractTextContent(response?.content ?? response);
             // If not expecting JSON, return raw content directly
             if (!expectsJsonResponse) {
                 return rawContent;

package/package.json

@@ -3,7 +3,7 @@
   "publishConfig": {
     "access": "public"
   },
-  "version": "1.2.16",
+  "version": "1.2.18",
   "description": "",
   "main": "dist/cjs/index.js",
   "module": "dist/esm/index.js",
@@ -19,7 +19,7 @@
     "work:release": "bash scripts/release.sh",
     "release": "bash scripts/release.sh",
     "release:fanout": "bash scripts/release-fanout.sh",
-    "ar-auth": "npm config set @stackfactor:registry https://us-central1-npm.pkg.dev/virtual-development-team/sf-devenv-npm-private/; TOKEN=$(gcloud auth print-access-token 2>/dev/null || curl -sfH 'Metadata-Flavor: Google' http://169.254.169.254/computeMetadata/v1/instance/service-accounts/default/token | sed -n 's/.*\"access_token\":\"\\([^\"]*\\)\".*/\\1/p'); test -n \"$TOKEN\" || { echo 'ar-auth: no credential — run: gcloud auth login' >&2; exit 1; }; npm config set //us-central1-npm.pkg.dev/virtual-development-team/:_authToken \"$TOKEN\"; echo 'ar-auth: Artifact Registry scope + token configured'",
+    "ar-auth": "npm config set @stackfactor:registry https://us-central1-npm.pkg.dev/virtual-development-team/sf-devenv-npm-private/; TOKEN=$(gcloud auth print-access-token 2>/dev/null || curl -sfH 'Metadata-Flavor: Google' http://169.254.169.254/computeMetadata/v1/instance/service-accounts/default/token | sed -n 's/.*\"access_token\":\"\\([^\"]*\\)\".*/\\1/p'); test -n \"$TOKEN\" || { echo 'ar-auth: no credential — run: gcloud auth login' >&2; exit 1; }; npm config set //us-central1-npm.pkg.dev/virtual-development-team/sf-devenv-npm-private/:_authToken \"$TOKEN\"; npm config set //us-central1-npm.pkg.dev/virtual-development-team/:_authToken \"$TOKEN\"; echo 'ar-auth: Artifact Registry scope + token configured'",
     "reinstall": "npm run ar-auth && npm ci"
   },
   "repository": {