@stackfactor/agent-utils 1.2.16 → 1.2.19

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/agentProto.d.ts

@@ -6,7 +6,7 @@ import * as grpc from "@grpc/grpc-js";
  * zero or more `Progress` frames (driven by the agent's `onProgress`) followed
  * by exactly one `Result` or `Error`.
  */
-export declare const PROTO = "\nsyntax = \"proto3\";\npackage stackfactor.agent.v1;\n\nservice Agent {\n  rpc Execute(ExecuteRequest) returns (stream Update);\n  // Liveness/health probe served by serve() itself \u2014 no agent code required.\n  // deep=true also exercises the StackFactor auth callback (BACKEND_URL).\n  rpc HealthCheck(HealthCheckRequest) returns (HealthCheckResponse);\n}\n\nmessage ExecuteRequest {\n  string content_type = 1;\n  string data_json    = 2;\n  string config_json  = 3;\n  string request_json = 4;\n  int32  event        = 5;\n}\n\nmessage HealthCheckRequest {\n  // Optional JSON carrying { authToken } for the deep backend-callback check.\n  string request_json = 1;\n  bool   deep         = 2;\n  // Deep check only: repo-relative path to the agent's self-check module to run\n  // (e.g. \"src/check.js\"). Empty \u2192 fall back to the conventional \"src/check.js\".\n  string check_code   = 3;\n  // Deep check only: JSON of the resolved agent config (constantsAndVars/\n  // secrets) made available to the self-check as ctx.config. May be empty.\n  string config_json  = 4;\n}\n\n// One result row from the agent's self-check module. The agent owns only its\n// own checks; reachability/ingress/version-drift rows are synthesised backend-\n// side. severity is optional: \"warn\" marks a failing check as non-blocking;\n// empty or \"error\" is blocking.\nmessage CheckResult {\n  string name     = 1;\n  bool   ok       = 2;\n  string detail   = 3;\n  string severity = 4;\n}\n\nmessage HealthCheckResponse {\n  bool   ok                  = 1;\n  bool   backend_reachable   = 2;\n  string version             = 3;\n  string message             = 4;\n  repeated CheckResult checks = 5;\n}\n\nmessage Update {\n  oneof payload {\n    Progress  progress = 1;\n    Result    result   = 2;\n    ErrorInfo error    = 3;\n  }\n}\n\nmessage Progress  { int32 progress = 1; string message = 2; }\nmessage Result    { string result_json = 1; }\nmessage ErrorInfo { int32 code = 1; string message = 2; }\n";
+export declare const PROTO = "\nsyntax = \"proto3\";\npackage stackfactor.agent.v1;\n\nservice Agent {\n  rpc Execute(ExecuteRequest) returns (stream Update);\n  // Liveness/health probe served by serve() itself \u2014 no agent code required.\n  // deep=true also exercises the StackFactor auth callback (BACKEND_URL).\n  rpc HealthCheck(HealthCheckRequest) returns (HealthCheckResponse);\n}\n\nmessage ExecuteRequest {\n  string content_type = 1;\n  string data_json    = 2;\n  string config_json  = 3;\n  string request_json = 4;\n  int32  event        = 5;\n  // Optional repo-relative module to run INSTEAD of the agent's main (e.g.\n  // \"src/webhooks/inbound-sms.js\"). Empty -> main, which is every pre-webhook\n  // caller, so this stays wire-compatible with agents built before it existed.\n  // Set by the webhook receiver from the integration's webHooks[].code. Follows\n  // the same untrusted-path rules as HealthCheck's check_code.\n  string code         = 6;\n}\n\nmessage HealthCheckRequest {\n  // Optional JSON carrying { authToken } for the deep backend-callback check.\n  string request_json = 1;\n  bool   deep         = 2;\n  // Deep check only: repo-relative path to the agent's self-check module to run\n  // (e.g. \"src/check.js\"). Empty \u2192 fall back to the conventional \"src/check.js\".\n  string check_code   = 3;\n  // Deep check only: JSON of the resolved agent config (constantsAndVars/\n  // secrets) made available to the self-check as ctx.config. May be empty.\n  string config_json  = 4;\n}\n\n// One result row from the agent's self-check module. The agent owns only its\n// own checks; reachability/ingress/version-drift rows are synthesised backend-\n// side. severity is optional: \"warn\" marks a failing check as non-blocking;\n// empty or \"error\" is blocking.\nmessage CheckResult {\n  string name     = 1;\n  bool   ok       = 2;\n  string detail   = 3;\n  string severity = 4;\n}\n\nmessage HealthCheckResponse {\n  bool   ok                  = 1;\n  bool   backend_reachable   = 2;\n  string version             = 3;\n  string message             = 4;\n  repeated CheckResult checks = 5;\n}\n\nmessage Update {\n  oneof payload {\n    Progress  progress = 1;\n    Result    result   = 2;\n    ErrorInfo error    = 3;\n  }\n}\n\nmessage Progress  { int32 progress = 1; string message = 2; }\nmessage Result    { string result_json = 1; }\nmessage ErrorInfo { int32 code = 1; string message = 2; }\n";
 /**
  * Loads the Agent proto package. proto-loader reads from a file, so the embedded
  * schema is written to a temp path — keeps the package self-contained across the

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

@@ -1 +1 @@
-{"version":3,"file":"agentProto.d.ts","sourceRoot":"","sources":["../../src/agentProto.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,IAAI,MAAM,eAAe,CAAC;AAMtC;;;;;;GAMG;AACH,eAAO,MAAM,KAAK,09DA6DjB,CAAC;AAEF;;;;;GAKG;AACH,eAAO,MAAM,gBAAgB,QAAO,GAWnC,CAAC;AAEF,oEAAoE;AACpE,eAAO,MAAM,gBAAgB,QAAO,IAAI,CAAC,iBACc,CAAC"}
+{"version":3,"file":"agentProto.d.ts","sourceRoot":"","sources":["../../src/agentProto.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,IAAI,MAAM,eAAe,CAAC;AAMtC;;;;;;GAMG;AACH,eAAO,MAAM,KAAK,y3EAmEjB,CAAC;AAEF;;;;;GAKG;AACH,eAAO,MAAM,gBAAgB,QAAO,GAWnC,CAAC;AAEF,oEAAoE;AACpE,eAAO,MAAM,gBAAgB,QAAO,IAAI,CAAC,iBACc,CAAC"}

package/dist/cjs/agentProto.js

@@ -63,6 +63,12 @@ message ExecuteRequest {
   string config_json  = 3;
   string request_json = 4;
   int32  event        = 5;
+  // Optional repo-relative module to run INSTEAD of the agent's main (e.g.
+  // "src/webhooks/inbound-sms.js"). Empty -> main, which is every pre-webhook
+  // caller, so this stays wire-compatible with agents built before it existed.
+  // Set by the webhook receiver from the integration's webHooks[].code. Follows
+  // the same untrusted-path rules as HealthCheck's check_code.
+  string code         = 6;
 }
 
 message HealthCheckRequest {

package/dist/cjs/client.d.ts

@@ -10,6 +10,13 @@ export interface AgentExecuteRequest {
     config_json: string;
     request_json: string;
     event: number;
+    /**
+     * Optional repo-relative module to run instead of the agent's `main` — the
+     * webhook receiver sets it from the integration's `webHooks[].code`. Omit (or
+     * pass "") for every other caller; the agent then runs `main` exactly as
+     * before. Agents built against an older agent-utils ignore the field.
+     */
+    code?: string;
 }
 export interface CallAgentOptions {
     /**

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

@@ -1 +1 @@
-{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../../src/client.ts"],"names":[],"mappings":"AAGA;;;;;GAKG;AACH,MAAM,WAAW,mBAAmB;IAClC,YAAY,EAAE,MAAM,CAAC;IACrB,SAAS,EAAE,MAAM,CAAC;IAClB,WAAW,EAAE,MAAM,CAAC;IACpB,YAAY,EAAE,MAAM,CAAC;IACrB,KAAK,EAAE,MAAM,CAAC;CACf;AAED,MAAM,WAAW,gBAAgB;IAC/B;;;;OAIG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,+EAA+E;IAC/E,UAAU,CAAC,EAAE,CAAC,MAAM,EAAE;QAAE,QAAQ,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,KAAK,IAAI,CAAC;IACrE,gFAAgF;IAChF,MAAM,CAAC,EAAE,WAAW,CAAC;IACrB,gFAAgF;IAChF,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AA8DD;;;;;;;;GAQG;AACH,eAAO,MAAM,SAAS,GACpB,UAAU,MAAM,EAChB,SAAS,mBAAmB,EAC5B,UAAS,gBAAqB,KAC7B,OAAO,CAAC,GAAG,CA0DV,CAAC;AAEL,MAAM,WAAW,iBAAiB;IAChC,wEAAwE;IACxE,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB;;;OAGG;IACH,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,0EAA0E;IAC1E,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB;;;OAGG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB;;;OAGG;IACH,MAAM,CAAC,EAAE,GAAG,CAAC;IACb,uEAAuE;IACvE,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED,+DAA+D;AAC/D,MAAM,WAAW,UAAU;IACzB,IAAI,EAAE,MAAM,CAAC;IACb,EAAE,EAAE,OAAO,CAAC;IACZ,MAAM,EAAE,MAAM,CAAC;IACf,uDAAuD;IACvD,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,WAAW,WAAW;IAC1B,2EAA2E;IAC3E,EAAE,EAAE,OAAO,CAAC;IACZ,gFAAgF;IAChF,gBAAgB,EAAE,OAAO,CAAC;IAC1B,8DAA8D;IAC9D,OAAO,EAAE,MAAM,CAAC;IAChB,6EAA6E;IAC7E,OAAO,EAAE,MAAM,CAAC;IAChB,gFAAgF;IAChF,MAAM,EAAE,UAAU,EAAE,CAAC;CACtB;AAID;;;;;;;GAOG;AACH,eAAO,MAAM,UAAU,GACrB,UAAU,MAAM,EAChB,UAAS,iBAAsB,KAC9B,OAAO,CAAC,WAAW,CA8ClB,CAAC"}
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../../src/client.ts"],"names":[],"mappings":"AAGA;;;;;GAKG;AACH,MAAM,WAAW,mBAAmB;IAClC,YAAY,EAAE,MAAM,CAAC;IACrB,SAAS,EAAE,MAAM,CAAC;IAClB,WAAW,EAAE,MAAM,CAAC;IACpB,YAAY,EAAE,MAAM,CAAC;IACrB,KAAK,EAAE,MAAM,CAAC;IACd;;;;;OAKG;IACH,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED,MAAM,WAAW,gBAAgB;IAC/B;;;;OAIG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,+EAA+E;IAC/E,UAAU,CAAC,EAAE,CAAC,MAAM,EAAE;QAAE,QAAQ,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,KAAK,IAAI,CAAC;IACrE,gFAAgF;IAChF,MAAM,CAAC,EAAE,WAAW,CAAC;IACrB,gFAAgF;IAChF,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AA8DD;;;;;;;;GAQG;AACH,eAAO,MAAM,SAAS,GACpB,UAAU,MAAM,EAChB,SAAS,mBAAmB,EAC5B,UAAS,gBAAqB,KAC7B,OAAO,CAAC,GAAG,CA0DV,CAAC;AAEL,MAAM,WAAW,iBAAiB;IAChC,wEAAwE;IACxE,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB;;;OAGG;IACH,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,0EAA0E;IAC1E,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB;;;OAGG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB;;;OAGG;IACH,MAAM,CAAC,EAAE,GAAG,CAAC;IACb,uEAAuE;IACvE,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED,+DAA+D;AAC/D,MAAM,WAAW,UAAU;IACzB,IAAI,EAAE,MAAM,CAAC;IACb,EAAE,EAAE,OAAO,CAAC;IACZ,MAAM,EAAE,MAAM,CAAC;IACf,uDAAuD;IACvD,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,WAAW,WAAW;IAC1B,2EAA2E;IAC3E,EAAE,EAAE,OAAO,CAAC;IACZ,gFAAgF;IAChF,gBAAgB,EAAE,OAAO,CAAC;IAC1B,8DAA8D;IAC9D,OAAO,EAAE,MAAM,CAAC;IAChB,6EAA6E;IAC7E,OAAO,EAAE,MAAM,CAAC;IAChB,gFAAgF;IAChF,MAAM,EAAE,UAAU,EAAE,CAAC;CACtB;AAID;;;;;;;GAOG;AACH,eAAO,MAAM,UAAU,GACrB,UAAU,MAAM,EAChB,UAAS,iBAAsB,KAC9B,OAAO,CAAC,WAAW,CA8ClB,CAAC"}

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"}