@stackfactor/agent-utils 1.2.20 → 1.3.1

package/dist/esm/langChain.js

@@ -10,6 +10,7 @@ import logger from "./logger.js";
 import { z } from "zod";
 import { transformJSONSchema } from "@anthropic-ai/sdk/lib/transform-json-schema";
 import { getAbortSignal } from "./runtimeContext.js";
+import { assertTavilyUsable, buildTavilyTools, getTavilyOptions, } from "./tavily.js";
 const JSON_ESCAPE_INSTRUCTION = `
 CRITICAL - Your response must be valid JSON. Escape ALL special characters in string values:
 - Newlines → \\n
@@ -603,114 +604,12 @@ 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.
+ * ordinary completions, but providers switch to an array of blocks whenever the
+ * turn carries more than prose — tool-use blocks in agentic runs, or Anthropic's
+ * thinking blocks — so without this the JSON parse pipeline would receive a
+ * non-string and the call would fail.
  * @param content - A message's `content` field, or a raw string
  * @returns The concatenated text of all text blocks
  */
@@ -729,108 +628,6 @@ const extractTextContent = (content) => {
     }
     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
@@ -857,13 +654,6 @@ 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
@@ -897,7 +687,7 @@ const getLLMModel = (modelName, config, schema = null) => {
             ...outputConfig,
             ...modelSettings,
         });
-        return webSearchTool ? model.bindTools([webSearchTool]) : model;
+        return model;
     }
     // Gemini models (Google)
     else if (modelName.startsWith("gemini-")) {
@@ -910,11 +700,6 @@ 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
@@ -922,9 +707,9 @@ const getLLMModel = (modelName, config, schema = null) => {
         // parse/validate pipeline is unchanged.
         if (schema) {
             const jsonSchema = sanitizeGeminiSchema(buildJsonSchema(schema));
-            return bound.withConfig({ responseSchema: jsonSchema });
+            return model.withConfig({ responseSchema: jsonSchema });
         }
-        return bound;
+        return model;
     }
     // GPT models (OpenAI)
     else if (modelName.startsWith("gpt-")) {
@@ -932,41 +717,24 @@ 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 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.
+        // Use native structured output with a JSON schema. `modelKwargs` is spread
+        // verbatim into the Chat Completions request.
         if (schema) {
             const jsonSchema = strictifyJsonSchema(buildJsonSchema(schema));
-            openAISettings.modelKwargs = webSearchTool
-                ? {
-                    text: {
-                        format: {
-                            type: "json_schema",
-                            name: "response_schema",
-                            strict: true,
-                            schema: jsonSchema,
-                        },
+            openAISettings.modelKwargs = {
+                response_format: {
+                    type: "json_schema",
+                    json_schema: {
+                        name: "response_schema",
+                        strict: true,
+                        schema: jsonSchema,
                     },
-                }
-                : {
-                    response_format: {
-                        type: "json_schema",
-                        json_schema: {
-                            name: "response_schema",
-                            strict: true,
-                            schema: jsonSchema,
-                        },
-                    },
-                };
+                },
+            };
         }
-        const model = new ChatOpenAI(openAISettings);
-        return webSearchTool ? model.bindTools([webSearchTool]) : model;
+        return new ChatOpenAI(openAISettings);
     }
     // OpenAI-compatible providers: DeepSeek, Kimi (Moonshot), GLM (Zhipu)
     const openAICompatible = getOpenAICompatibleProvider(modelName, config);
@@ -991,22 +759,28 @@ const getLLMModel = (modelName, config, schema = null) => {
  *   an empty array
  * @param responseFormat - Optional structured response format descriptor passed to the
  *   LangChain agent constructor
- * @param config - Configuration object forwarded to `getLLMModel` (API keys, temperature, etc.)
+ * @param config - Configuration object forwarded to `getLLMModel` (API keys, temperature,
+ *   etc.), plus optional `tavily` (`true` or a `TavilyConfig`) to append the web tools
+ * @param usageTracker - Optional accumulator the Tavily tools bill their credits and
+ *   record their sources into; the LLM's own token usage is tracked by `runAgent`
  * @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 createAgent = (name, modelName, systemPrompt, tools = [], responseFormat, config, usageTracker = null) => {
+    // The Tavily tools join the agent's tool list rather than being bound inside
+    // `getLLMModel`: they run client-side, so only the agent loop can execute
+    // them, and the agent binds its own tools to the model anyway — anything
+    // bound there would be dropped.
+    const tavilyOptions = getTavilyOptions(config);
+    let tavilyTools = [];
+    if (tavilyOptions) {
+        assertTavilyUsable(config, tavilyOptions);
+        tavilyTools = buildTavilyTools(config, tavilyOptions, usageTracker);
+    }
     const agent = createLangChainAgent({
         name: name,
-        model: getLLMModel(modelName, { ...config, webSearch: null }),
+        model: getLLMModel(modelName, config),
         systemPrompt: systemPrompt.trim(),
-        tools: webSearchTool ? [...tools, webSearchTool] : tools,
+        tools: tavilyTools.length > 0 ? [...tools, ...tavilyTools] : tools,
         ...(responseFormat ? { responseFormat: responseFormat } : {}),
     });
     return agent;
@@ -1093,13 +867,6 @@ 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.`);
@@ -1337,15 +1104,15 @@ 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`.
+ * Setting `config.tavily` adds the Tavily web tools (`web_search`, `web_extract`, and
+ * optionally `web_map` / `web_crawl`). They execute in this process, so they require
+ * `config.agentic` to be `true`; the credits spent and the URLs returned 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, optional `recursionLimit`, and optional `webSearch` (`true` or a
- *   `WebSearchConfig`)
+ *   flag, optional `recursionLimit`, and optional `tavily` (`true` or a
+ *   `TavilyConfig`)
  * @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 }`
@@ -1396,9 +1163,11 @@ const runPromptWithModel = async (modelName, config, prompt, onProgressReport, m
                 ? `${JSON_ESCAPE_INSTRUCTION}\n\n---\n\n${systemPrompt}`
                 : JSON_ESCAPE_INSTRUCTION;
         }
-        // Create the agent with tools
+        // Create the agent with tools. The tracker is handed over at construction
+        // because the Tavily tools bill their own credits as they run, rather than
+        // being reconciled from the response afterwards.
         const agent = createAgent(agentName, modelName, systemPrompt, [...tools], null, // responseFormat
-        config);
+        config, usageTracker);
         // Run the agent with progress callback
         const response = await runAgent(agent, userPrompt, config, onProgressReport || null, usageTracker);
         // Extract content from agent response
@@ -1531,7 +1300,6 @@ 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
@@ -1541,7 +1309,6 @@ 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.
@@ -1554,9 +1321,8 @@ const runPromptWithModel = async (modelName, config, prompt, onProgressReport, m
                             throw errorHandlingHelper.create(constants.HTTP_CODES.BAD_REQUEST, "Request cancelled by caller");
                         }
                         accumulateChunkUsage(streamUsage, chunk);
-                        collectWebSearchUsage(chunk, webSearchUsage);
                         // Counting every chunk (not just the ones carrying text) keeps
-                        // progress ticking through the pause while a search runs.
+                        // progress ticking through pauses in the stream.
                         chunkCount++;
                         rawContent += extractTextContent(chunk?.content ?? chunk);
                         if (chunkCount % progressReportInterval === 0) {
@@ -1586,7 +1352,6 @@ 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");
             }
@@ -1691,10 +1456,8 @@ const runPromptWithModel = async (modelName, config, prompt, onProgressReport, m
                 }
             }
             updateUsageTracker(usageTracker, modelName, extractUsageFromInvoke(response), config);
-            const webSearchUsage = createWebSearchUsage();
-            collectWebSearchUsage(response, webSearchUsage);
-            updateWebSearchUsageTracker(usageTracker, modelName, webSearchUsage, config);
-            // Flattened because a server-tool turn returns content blocks, not a string.
+            // Flattened because providers return content blocks, not a string, once
+            // the turn carries anything besides prose.
             const rawContent = extractTextContent(response?.content ?? response);
             // If not expecting JSON, return raw content directly
             if (!expectsJsonResponse) {

package/dist/esm/tavily.d.ts

@@ -0,0 +1,91 @@
+import type { UsageTracker } from "./langChain.js";
+export type TavilyToolName = "search" | "extract" | "crawl" | "map";
+/**
+ * Caller-facing options for the Tavily tools. Enable them by setting
+ * `config.tavily` to `true` (defaults for every field) or to one of these
+ * objects, and supply `config.tavilyAPIKey`.
+ *
+ * Tavily runs client-side: the model emits a tool call, this process performs
+ * the HTTP request, and the result is appended to the conversation. That only
+ * happens inside an agent loop, so `config.agentic` must be `true` — see
+ * `assertTavilyUsable`.
+ */
+export type TavilyConfig = {
+    /**
+     * Which tools to expose. Every enabled tool spends its description tokens on
+     * every request, so this defaults to `["search", "extract"]`. Add `"map"` to
+     * let the model enumerate a site's URLs and `"crawl"` to let it read a whole
+     * section — `crawl` returns full content for every page it visits, which is
+     * the easiest way to exhaust a context window here.
+     */
+    tools?: TavilyToolName[];
+    /** Passed through to `/search`. Tavily defaults to `"basic"`. */
+    searchDepth?: "basic" | "advanced" | "fast" | "ultra-fast";
+    /** `"advanced"` also pulls tables and embedded content, at double the credits. */
+    extractDepth?: "basic" | "advanced";
+    /** Results per search. Defaults to `5`. */
+    maxResults?: number;
+    /**
+     * Relevant chunks returned per URL when the model supplies a `query` to
+     * `web_extract`. Defaults to `3`; ignored for whole-page extraction.
+     */
+    chunksPerSource?: number;
+    /** Per-URL character cap before truncation. Defaults to `60000`. */
+    maxCharsPerUrl?: number;
+    /** Character cap across a single tool call. Defaults to `150000`. */
+    maxCharsTotal?: number;
+    /** Restricts `/search` to these domains. */
+    includeDomains?: string[];
+    /** Excludes these domains from `/search`. */
+    excludeDomains?: string[];
+    /** Maximum pages a single `web_crawl` or `web_map` call may return. */
+    crawlLimit?: number;
+    /**
+     * Returns markdown (the default) or flattened text. Markdown preserves table
+     * and heading structure, which costs fewer tokens than the prose equivalent
+     * for the tabular documents this is usually pointed at.
+     */
+    format?: "markdown" | "text";
+};
+/**
+ * Normalizes `config.tavily` into an options object, returning `null` when the
+ * Tavily tools are off so callers can use it as the single enablement gate.
+ * @param config - The integration config object
+ * @returns Normalized options, or `null` when Tavily is not enabled
+ */
+export declare const getTavilyOptions: (config: any) => TavilyConfig | null;
+/**
+ * Fails fast on the two ways a Tavily config cannot work. Tavily tools are
+ * executed by the agent loop in this process, so outside agentic mode the model
+ * would be handed tools whose calls nothing answers: the turn ends silently and
+ * looks like the model ignored them. Called once at config time rather than
+ * discovered per request.
+ * @param config - The integration config object
+ * @param options - Normalized options from `getTavilyOptions`
+ */
+export declare const assertTavilyUsable: (config: any, options: TavilyConfig) => void;
+/**
+ * Builds the LangChain tools for the Tavily endpoints named in
+ * `options.tools`, closed over the run's config and usage tracker. Tools are
+ * created per run rather than shared, because each one bills into that run's
+ * tracker.
+ *
+ * `web_extract` covers both of the reading modes Tavily supports through one
+ * tool: with a `query` the API returns only the matching chunks of each page,
+ * and without one it returns the whole document. Splitting that into two tools
+ * would duplicate the description tokens on every request to express a
+ * distinction the API already makes with one optional field.
+ *
+ * @param config - Config object carrying `tavilyAPIKey` and cost constants
+ * @param options - Normalized options from `getTavilyOptions`
+ * @param usageTracker - Optional accumulator billed for every Tavily call
+ * @returns LangChain tool instances to append to the agent's tool list
+ */
+export declare const buildTavilyTools: (config: any, options: TavilyConfig, usageTracker?: UsageTracker | null) => any[];
+declare const _default: {
+    assertTavilyUsable: (config: any, options: TavilyConfig) => void;
+    buildTavilyTools: (config: any, options: TavilyConfig, usageTracker?: UsageTracker | null) => any[];
+    getTavilyOptions: (config: any) => TavilyConfig | null;
+};
+export default _default;
+//# sourceMappingURL=tavily.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"tavily.d.ts","sourceRoot":"","sources":["../../src/tavily.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AA6BnD,MAAM,MAAM,cAAc,GAAG,QAAQ,GAAG,SAAS,GAAG,OAAO,GAAG,KAAK,CAAC;AAEpE;;;;;;;;;GASG;AACH,MAAM,MAAM,YAAY,GAAG;IACzB;;;;;;OAMG;IACH,KAAK,CAAC,EAAE,cAAc,EAAE,CAAC;IACzB,iEAAiE;IACjE,WAAW,CAAC,EAAE,OAAO,GAAG,UAAU,GAAG,MAAM,GAAG,YAAY,CAAC;IAC3D,kFAAkF;IAClF,YAAY,CAAC,EAAE,OAAO,GAAG,UAAU,CAAC;IACpC,2CAA2C;IAC3C,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB;;;OAGG;IACH,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,oEAAoE;IACpE,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,qEAAqE;IACrE,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,4CAA4C;IAC5C,cAAc,CAAC,EAAE,MAAM,EAAE,CAAC;IAC1B,6CAA6C;IAC7C,cAAc,CAAC,EAAE,MAAM,EAAE,CAAC;IAC1B,uEAAuE;IACvE,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB;;;;OAIG;IACH,MAAM,CAAC,EAAE,UAAU,GAAG,MAAM,CAAC;CAC9B,CAAC;AAEF;;;;;GAKG;AACH,eAAO,MAAM,gBAAgB,GAAI,QAAQ,GAAG,KAAG,YAAY,GAAG,IAI7D,CAAC;AAEF;;;;;;;;GAQG;AACH,eAAO,MAAM,kBAAkB,GAAI,QAAQ,GAAG,EAAE,SAAS,YAAY,KAAG,IAsBvE,CAAC;AAqLF;;;;;;;;;;;;;;;;GAgBG;AACH,eAAO,MAAM,gBAAgB,GAC3B,QAAQ,GAAG,EACX,SAAS,YAAY,EACrB,eAAc,YAAY,GAAG,IAAW,KACvC,GAAG,EA2PL,CAAC;;iCA3dyC,GAAG,WAAW,YAAY,KAAG,IAAI;+BA6NlE,GAAG,WACF,YAAY,iBACP,YAAY,GAAG,IAAI,KAChC,GAAG,EAAE;+BA/OiC,GAAG,KAAG,YAAY,GAAG,IAAI;;AA4elE,wBAIE"}