@stackfactor/agent-utils 1.2.20 → 1.3.2

package/dist/esm/tavily.js

@@ -0,0 +1,395 @@
+import { tool } from "langchain";
+import { z } from "zod";
+import constants from "./const.js";
+import errorHandlingHelper from "./errorHandling.js";
+import logger from "./logger.js";
+import { getAbortSignal } from "./runtimeContext.js";
+const TAVILY_API_BASE = "https://api.tavily.com";
+/** Tavily list price per credit, used when the integration defines no rate. */
+const DEFAULT_CREDIT_COST_USD = 0.008;
+/**
+ * Context budgets, in characters, applied to everything a tool hands back to
+ * the model. Tavily returns whatever the page holds, and unlike a provider's
+ * native search there is nothing between its response and the context window,
+ * so these caps are the only thing standing between one `extract` call and a
+ * 100-page PDF. Roughly four characters per token: 60k ≈ 15k tokens per URL,
+ * 150k ≈ 37k tokens per call.
+ */
+const DEFAULT_MAX_CHARS_PER_URL = 60_000;
+const DEFAULT_MAX_CHARS_TOTAL = 150_000;
+/** Kept deliberately small — search finds documents, `extract` reads them. */
+const DEFAULT_MAX_RESULTS = 5;
+/** Tavily's own default when a query is supplied. */
+const DEFAULT_CHUNKS_PER_SOURCE = 3;
+/** Crawl returns full content per page, so the page count is the cost driver. */
+const DEFAULT_CRAWL_LIMIT = 10;
+/** Seconds. Tavily's own per-request default; crawls legitimately run long. */
+const DEFAULT_TIMEOUT_SECONDS = 60;
+const DEFAULT_CRAWL_TIMEOUT_SECONDS = 120;
+/**
+ * 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 const getTavilyOptions = (config) => {
+    const tavily = config?.tavily;
+    if (!tavily)
+        return null;
+    return tavily === true ? {} : tavily;
+};
+/**
+ * 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 const assertTavilyUsable = (config, options) => {
+    if (config?.agentic !== true) {
+        throw errorHandlingHelper.create(constants.HTTP_CODES.BAD_REQUEST, "Tavily tools run client-side and are only executed by the agent loop; set config.agentic to true to use them.");
+    }
+    if (!config?.tavilyAPIKey) {
+        throw errorHandlingHelper.create(constants.HTTP_CODES.INTERNAL_SERVER_ERROR, "Tavily tools are enabled but config.tavilyAPIKey is missing.");
+    }
+    const unknown = (options.tools || []).filter((name) => !["search", "extract", "crawl", "map"].includes(name));
+    if (unknown.length > 0) {
+        throw errorHandlingHelper.create(constants.HTTP_CODES.BAD_REQUEST, `Unknown Tavily tool(s): ${unknown.join(", ")}. Valid values are search, extract, crawl, map.`);
+    }
+};
+/** Retries for a transient (429/5xx) Tavily response before giving up. */
+const MAX_TAVILY_RETRIES = 2;
+/** Base delay for retry backoff; doubled on each subsequent attempt. */
+const RETRY_BASE_DELAY_MS = 500;
+const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+/**
+ * POSTs to one Tavily endpoint. The REST API is snake_case while the published
+ * SDK's option names are camelCase, so bodies here are written in the wire
+ * format the API actually accepts. `include_usage` is always set: the response
+ * then carries the exact credits the call consumed, which is what the tracker
+ * bills instead of an estimate. `timeout` is always set from the caller's
+ * budget so Tavily's own (shorter) per-endpoint defaults don't cut a call off
+ * before the time this library already told the caller it had.
+ *
+ * Rate-limit (429) and server (5xx) responses are retried with exponential
+ * backoff — everything else, including a caller-cancelled request, fails
+ * immediately.
+ * @param endpoint - The Tavily endpoint name, e.g. `"search"`
+ * @param body - Request body in the API's snake_case form; `undefined` values
+ *   are dropped so Tavily applies its own defaults
+ * @param apiKey - The Tavily API key
+ * @param timeoutSeconds - Per-request timeout forwarded to Tavily
+ * @returns The parsed JSON response
+ */
+const callTavily = async (endpoint, body, apiKey, timeoutSeconds) => {
+    const payload = {
+        include_usage: true,
+        timeout: timeoutSeconds,
+    };
+    for (const [key, value] of Object.entries(body)) {
+        if (value !== undefined && value !== null)
+            payload[key] = value;
+    }
+    for (let attempt = 0;; attempt++) {
+        let response;
+        try {
+            response = await fetch(`${TAVILY_API_BASE}/${endpoint}`, {
+                method: "POST",
+                headers: {
+                    "Content-Type": "application/json",
+                    Authorization: `Bearer ${apiKey}`,
+                },
+                body: JSON.stringify(payload),
+                // Honour caller cancellation the same way the LLM calls do, so an
+                // abandoned run stops paying for in-flight crawls.
+                signal: getAbortSignal() ?? undefined,
+            });
+        }
+        catch (err) {
+            throw errorHandlingHelper.create(constants.HTTP_CODES.INTERNAL_SERVER_ERROR, `Tavily ${endpoint} request failed: ${err?.message || String(err)}`);
+        }
+        if (response.ok)
+            return response.json();
+        const retryable = response.status === 429 || response.status >= 500;
+        if (retryable && attempt < MAX_TAVILY_RETRIES) {
+            await sleep(RETRY_BASE_DELAY_MS * 2 ** attempt);
+            continue;
+        }
+        const detail = await response.text().catch(() => "");
+        throw errorHandlingHelper.create(constants.HTTP_CODES.INTERNAL_SERVER_ERROR, `Tavily ${endpoint} returned ${response.status}: ${detail.slice(0, 500)}`);
+    }
+};
+/**
+ * Adds one Tavily call's credits to the tracker and records the URLs it
+ * returned. Credits come from the response's own `usage` block, priced with the
+ * `tavily-credit-costs` constant (USD per credit) and accumulated under
+ * `tavilyCredits`. Sources land on `tracker.webSearchSources`, deduplicated by
+ * URL across the whole run, so callers have the citation list Tavily's terms
+ * require when this output is shown to end users.
+ * @param tracker - The caller's usage accumulator; no-ops when absent
+ * @param config - Config object carrying the `tavily-credit-costs` constant
+ * @param credits - Credits reported by the Tavily response
+ * @param sources - URLs (and titles where known) the call returned
+ */
+const recordTavilyUsage = (tracker, config, credits, sources) => {
+    if (!tracker)
+        return;
+    if (typeof tracker.cost !== "number")
+        tracker.cost = 0;
+    if (!tracker.tokens || typeof tracker.tokens !== "object")
+        tracker.tokens = {};
+    if (Number.isFinite(credits) && credits > 0) {
+        const configured = Number(config?.["tavily-credit-costs"]);
+        const rate = Number.isFinite(configured)
+            ? configured
+            : DEFAULT_CREDIT_COST_USD;
+        const addedCost = credits * rate;
+        if (Number.isFinite(addedCost) && addedCost > 0)
+            tracker.cost += addedCost;
+        tracker.tokens.tavilyCredits =
+            (tracker.tokens.tavilyCredits || 0) + credits;
+    }
+    if (sources.length === 0)
+        return;
+    const existing = tracker.webSearchSources || (tracker.webSearchSources = []);
+    for (const source of sources) {
+        if (!source?.url)
+            continue;
+        if (!existing.some((entry) => entry.url === source.url)) {
+            existing.push(source);
+        }
+    }
+};
+/**
+ * Trims one document to whatever the per-URL and per-call budgets allow,
+ * appending a note when anything was cut.
+ * @param text - The document text
+ * @param budget - Mutable budget for the current tool call
+ * @returns The text, truncated with an inline note when over budget
+ */
+const applyBudget = (text, budget) => {
+    const body = typeof text === "string" ? text : "";
+    if (!body)
+        return "";
+    const allowance = Math.min(budget.perUrl, budget.remaining);
+    if (allowance <= 0) {
+        return "[omitted: this call's character budget is exhausted — request fewer URLs at a time]";
+    }
+    if (body.length <= allowance) {
+        budget.remaining -= body.length;
+        return body;
+    }
+    budget.remaining -= allowance;
+    return `${body.slice(0, allowance)}\n\n[truncated: ${allowance.toLocaleString()} of ${body.length.toLocaleString()} characters shown — narrow the query or request fewer URLs to see the parts that matter]`;
+};
+/**
+ * Renders documents for the model as titled markdown sections. Tavily's own
+ * result objects carry `score`, `published_date`, `favicon` and `id` alongside
+ * the content; none of that informs an answer, so only the title, URL and text
+ * are forwarded and the rest is dropped rather than billed as input tokens.
+ * @param documents - Documents to render
+ * @param budget - Mutable budget for the current tool call
+ * @returns A markdown string, or a not-found notice when there is nothing
+ */
+const renderDocuments = (documents, budget) => {
+    const sections = [];
+    for (const document of documents) {
+        const body = applyBudget(document.text, budget);
+        if (!body)
+            continue;
+        const heading = document.title
+            ? `## ${document.title}\n${document.url}`
+            : `## ${document.url}`;
+        sections.push(`${heading}\n\n${body}`);
+    }
+    if (sections.length === 0)
+        return "No content was returned.";
+    return sections.join("\n\n---\n\n");
+};
+/**
+ * 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 const buildTavilyTools = (config, options, usageTracker = null) => {
+    const apiKey = config.tavilyAPIKey;
+    const enabled = options.tools || ["search", "extract"];
+    const format = options.format || "markdown";
+    const maxCharsPerUrl = options.maxCharsPerUrl ?? DEFAULT_MAX_CHARS_PER_URL;
+    const maxCharsTotal = options.maxCharsTotal ?? DEFAULT_MAX_CHARS_TOTAL;
+    const crawlLimit = options.crawlLimit ?? DEFAULT_CRAWL_LIMIT;
+    const newBudget = () => ({
+        remaining: maxCharsTotal,
+        perUrl: maxCharsPerUrl,
+    });
+    const tools = [];
+    if (enabled.includes("search")) {
+        tools.push(tool(async ({ query, maxResults }) => {
+            const data = await callTavily("search", {
+                query,
+                search_depth: options.searchDepth,
+                max_results: maxResults || options.maxResults || DEFAULT_MAX_RESULTS,
+                include_domains: options.includeDomains,
+                exclude_domains: options.excludeDomains,
+                // Snippets only. Full page text is `web_extract`'s job, and
+                // asking for it here would pay for every result to find one.
+                include_raw_content: false,
+            }, apiKey, DEFAULT_TIMEOUT_SECONDS);
+            const results = data?.results || [];
+            recordTavilyUsage(usageTracker, config, data?.usage?.credits || 0, results.map((result) => ({
+                url: result?.url,
+                ...(result?.title ? { title: result.title } : {}),
+            })));
+            if (results.length === 0)
+                return "No results found.";
+            const budget = newBudget();
+            return renderDocuments(results.map((result) => ({
+                url: result?.url,
+                title: result?.title,
+                text: result?.content || "",
+            })), budget);
+        }, {
+            name: "web_search",
+            description: "Search the web and return short relevant snippets with their URLs. Use this to find documents; to read one in full or to pull specific passages from it, follow up with web_extract on the URL.",
+            schema: z.object({
+                query: z.string().describe("The search query."),
+                maxResults: z
+                    .number()
+                    .int()
+                    .min(1)
+                    .max(20)
+                    .optional()
+                    .describe("How many results to return. Defaults to 5."),
+            }),
+        }));
+    }
+    if (enabled.includes("extract")) {
+        tools.push(tool(async ({ urls, query }) => {
+            const data = await callTavily("extract", {
+                urls,
+                extract_depth: options.extractDepth,
+                format,
+                // `query` switches the API from whole-document extraction to
+                // returning only the chunks that match it.
+                query: query || undefined,
+                chunks_per_source: query
+                    ? options.chunksPerSource || DEFAULT_CHUNKS_PER_SOURCE
+                    : undefined,
+            }, apiKey, DEFAULT_TIMEOUT_SECONDS);
+            const results = data?.results || [];
+            recordTavilyUsage(usageTracker, config, data?.usage?.credits || 0, results.map((result) => ({
+                url: result?.url,
+                ...(result?.title ? { title: result.title } : {}),
+            })));
+            const budget = newBudget();
+            let rendered = renderDocuments(results.map((result) => ({
+                url: result?.url,
+                title: result?.title,
+                text: result?.raw_content || "",
+            })), budget);
+            // Surface per-URL failures: the model asked for these pages, and
+            // silently returning fewer than requested invites it to treat a
+            // fetch failure as an absence of content.
+            const failed = data?.failed_results || [];
+            if (failed.length > 0) {
+                const lines = failed
+                    .map((entry) => `- ${entry?.url}: ${entry?.error}`)
+                    .join("\n");
+                rendered += `\n\n---\n\nFailed to extract:\n${lines}`;
+            }
+            return rendered;
+        }, {
+            name: "web_extract",
+            description: "Read the content of specific URLs. Pass a query to get back only the passages relevant to it — much cheaper and usually sufficient. Omit the query to retrieve the whole document, which is appropriate when you need its full structure. Long documents are truncated, and the result says so when that happens.",
+            schema: z.object({
+                urls: z
+                    .array(z.string())
+                    .min(1)
+                    .max(20)
+                    .describe("The URLs to read."),
+                query: z
+                    .string()
+                    .optional()
+                    .describe("What to look for in each page. Omit to retrieve whole documents."),
+            }),
+        }));
+    }
+    if (enabled.includes("map")) {
+        tools.push(tool(async ({ url, instructions }) => {
+            const data = await callTavily("map", { url, instructions: instructions || undefined, limit: crawlLimit }, apiKey, DEFAULT_TIMEOUT_SECONDS);
+            const urls = data?.results || [];
+            recordTavilyUsage(usageTracker, config, data?.usage?.credits || 0, urls.map((entry) => ({ url: entry })));
+            if (urls.length === 0)
+                return "No URLs found.";
+            return `Found ${urls.length} URL(s) under ${data?.base_url || url}:\n${urls
+                .map((entry) => `- ${entry}`)
+                .join("\n")}`;
+        }, {
+            name: "web_map",
+            description: "List the URLs available under a site or section, without retrieving any page content. Use this to discover what a documentation site or document library holds, then read the ones you want with web_extract.",
+            schema: z.object({
+                url: z.string().describe("The site or section URL to map."),
+                instructions: z
+                    .string()
+                    .optional()
+                    .describe("Plain-language description of the pages worth including."),
+            }),
+        }));
+    }
+    if (enabled.includes("crawl")) {
+        tools.push(tool(async ({ url, instructions, limit }) => {
+            const data = await callTavily("crawl", {
+                url,
+                instructions: instructions || undefined,
+                limit: Math.min(limit || crawlLimit, crawlLimit),
+                extract_depth: options.extractDepth,
+                format,
+            }, apiKey, DEFAULT_CRAWL_TIMEOUT_SECONDS);
+            const results = data?.results || [];
+            recordTavilyUsage(usageTracker, config, data?.usage?.credits || 0, results.map((result) => ({ url: result?.url })));
+            const budget = newBudget();
+            return renderDocuments(results.map((result) => ({
+                url: result?.url,
+                title: result?.title,
+                text: result?.raw_content || "",
+            })), budget);
+        }, {
+            name: "web_crawl",
+            description: "Follow links from a starting URL and return the content of the pages found. This returns full page content for every page visited, so prefer web_map followed by web_extract when you only need a few pages. Use the instructions argument to describe which pages matter.",
+            schema: z.object({
+                url: z.string().describe("The URL to start crawling from."),
+                instructions: z
+                    .string()
+                    .optional()
+                    .describe("Plain-language description of the pages worth following."),
+                limit: z
+                    .number()
+                    .int()
+                    .min(1)
+                    .optional()
+                    .describe("Maximum pages to return; capped by the configured crawl limit."),
+            }),
+        }));
+    }
+    logger.log(null, logger.levels.info, `Tavily tools enabled: ${tools.map((entry) => entry.name).join(", ")}`);
+    return tools;
+};
+export default {
+    assertTavilyUsable,
+    buildTavilyTools,
+    getTavilyOptions,
+};

package/package.json

@@ -3,7 +3,7 @@
   "publishConfig": {
     "access": "public"
   },
-  "version": "1.2.20",
+  "version": "1.3.2",
   "description": "",
   "main": "dist/cjs/index.js",
   "module": "dist/esm/index.js",
@@ -14,6 +14,7 @@
   "scripts": {
     "clean": "rm -rf dist",
     "build": "npm run clean && tsc -p tsconfig.cjs.json && tsc -p tsconfig.esm.json && echo '{\"type\":\"commonjs\"}' > dist/cjs/package.json && echo '{\"type\":\"module\"}' > dist/esm/package.json",
+    "test": "npm run build && node --test \"test/**/*.test.js\"",
     "work:start": "bash scripts/work-start.sh",
     "work:commit": "bash scripts/work-commit.sh",
     "work:release": "bash scripts/release.sh",
@@ -62,6 +63,7 @@
     "zod": "^4.3.6"
   },
   "devDependencies": {
+    "@langchain/core": "^1.2.9",
     "typescript": "^5.9.3"
   }
 }