melchizedek-agents 0.9.0

package/dist/lib/tools/webExtractTool.js

@@ -0,0 +1,461 @@
+/**
+ * lib/tools/webExtractTool.ts — deterministic URL → clean-text reading.
+ *
+ * WHY this file exists:
+ *   `web_search` routes to each provider's SERVER-SIDE search (§7.5): the
+ *   provider decides which pages to fetch and which snippets to quote. An
+ *   agent could never say "now read THIS article in full" — for a news
+ *   agent that is the difference between arbitrating what a search chose
+ *   to quote and actually reading the five articles being compared.
+ *   `web_extract` closes that gap: a plain client-side function tool that
+ *   fetches given URLs and returns the page's clean text. Deterministic,
+ *   no LLM summarization, and KEYLESS — it also works on local Ollama
+ *   agents, the first web capability local mode gets.
+ *
+ * DESIGN (cribbed from NousResearch/hermes-agent `web_extract`, adapted):
+ *   - Up to 5 URLs per call; per-page character budget (default 15k,
+ *     WEB_EXTRACT_CHAR_LIMIT env, clamped 2k–500k — deployment config,
+ *     never YAML, the XAI_COLLECTION_IDS doctrine).
+ *   - Over-budget pages return a head+tail window (~75%/25%) with an
+ *     omission marker. Hermes spills full text to disk and tells the
+ *     agent to page with read_file; melchizedek agents have no filesystem
+ *     tools, so paging is an `offset` param instead: the full text is
+ *     held in a 15-minute in-process cache and re-calling with
+ *     `{urls:[same], offset:N}` continues reading without refetching.
+ *   - Zero new dependencies: native fetch + a heuristic HTML→markdown
+ *     pipeline (strip script/style/nav chrome, prefer <article>/<main>,
+ *     headings/lists/links/blockquotes to markdown, entities decoded,
+ *     base64 images never survive because <img> collapses to alt text).
+ *
+ * SECURITY (SSRF):
+ *   Agents pass arbitrary URLs and this process may run server-side
+ *   (A2A on Heroku), so http(s)-only plus a literal-host guard: loopback,
+ *   RFC-1918, link-local/metadata (169.254.*), CGNAT, ULA/IPv6-local and
+ *   localhost-ish hostnames are refused, and redirects are followed
+ *   manually so every hop is re-checked. Deliberate v1 limit: the guard
+ *   inspects literals only — it does not resolve DNS, so a public
+ *   hostname that resolves privately can still slip; acceptable for a
+ *   tool that runs with no ambient credentials, revisit if that changes.
+ *
+ * FAILURE CONTRACT: never throws. Each URL yields either its content
+ *   block or an inline `Error:` block; one bad URL never sinks the rest.
+ */
+import { z } from 'zod';
+import { defineTool, toFunctionTool } from "./toolContract.js";
+export const WEB_EXTRACT_TOOL_NAME = 'web_extract';
+const MAX_URLS = 5;
+const DEFAULT_CHAR_LIMIT = 15_000;
+const MIN_CHAR_LIMIT = 2_000;
+const MAX_CHAR_LIMIT = 500_000;
+const HEAD_FRACTION = 0.75;
+const FETCH_TIMEOUT_MS = 15_000;
+const MAX_REDIRECTS = 5;
+const MAX_FETCH_BYTES = 5 * 1024 * 1024;
+const CACHE_TTL_MS = 15 * 60 * 1000;
+const CACHE_MAX_ENTRIES = 50;
+const USER_AGENT = 'Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 ' +
+    '(KHTML, like Gecko) Chrome/126.0.0.0 Safari/537.36 melchizedek-web-extract';
+/** Per-page char budget from the environment; malformed values warn and fall back. */
+export function extractCharLimit() {
+    const raw = process.env.WEB_EXTRACT_CHAR_LIMIT?.trim();
+    if (!raw)
+        return DEFAULT_CHAR_LIMIT;
+    const value = Number(raw);
+    if (!Number.isFinite(value)) {
+        console.warn(`[web_extract] WEB_EXTRACT_CHAR_LIMIT="${raw}" is not a number — using ${DEFAULT_CHAR_LIMIT}.`);
+        return DEFAULT_CHAR_LIMIT;
+    }
+    return Math.max(MIN_CHAR_LIMIT, Math.min(Math.floor(value), MAX_CHAR_LIMIT));
+}
+// ── SSRF guard ───────────────────────────────────────────────────────────────
+/** Reason the host is refused, or null when it looks routable. Literals only — see header. */
+export function blockedHostReason(hostname) {
+    const host = hostname.toLowerCase().replace(/^\[|\]$/g, '');
+    if (host === 'localhost' ||
+        host.endsWith('.localhost') ||
+        host.endsWith('.local') ||
+        host.endsWith('.internal') ||
+        host.endsWith('.home.arpa')) {
+        return 'local hostname';
+    }
+    const v4 = host.match(/^(\d{1,3})\.(\d{1,3})\.(\d{1,3})\.(\d{1,3})$/);
+    if (v4) {
+        const [a, b] = [Number(v4[1]), Number(v4[2])];
+        if (a === 0 || a === 10 || a === 127)
+            return 'private/loopback IPv4';
+        if (a === 169 && b === 254)
+            return 'link-local/metadata IPv4';
+        if (a === 172 && b >= 16 && b <= 31)
+            return 'private IPv4';
+        if (a === 192 && b === 168)
+            return 'private IPv4';
+        if (a === 100 && b >= 64 && b <= 127)
+            return 'CGNAT IPv4';
+        return null;
+    }
+    if (host.includes(':')) {
+        if (host === '::' || host === '::1')
+            return 'IPv6 loopback/unspecified';
+        if (/^f[cd]/.test(host))
+            return 'IPv6 unique-local';
+        if (host.startsWith('fe80'))
+            return 'IPv6 link-local';
+        if (host.startsWith('::ffff:'))
+            return blockedHostReason(host.slice(7)) ?? null;
+    }
+    return null;
+}
+// ── HTML → markdown-ish text (zero-dep heuristic) ───────────────────────────
+const NAMED_ENTITIES = {
+    amp: '&', lt: '<', gt: '>', quot: '"', apos: "'", nbsp: ' ',
+    mdash: '—', ndash: '–', hellip: '…', middot: '·', bull: '•',
+    lsquo: '‘', rsquo: '’', ldquo: '“', rdquo: '”',
+    laquo: '«', raquo: '»', copy: '©', reg: '®', trade: '™', times: '×', deg: '°',
+};
+export function decodeEntities(text) {
+    return text
+        .replace(/&#x([0-9a-fA-F]+);/g, (_, hex) => safeCodePoint(parseInt(hex, 16)))
+        .replace(/&#(\d+);/g, (_, dec) => safeCodePoint(parseInt(dec, 10)))
+        .replace(/&([a-zA-Z]+);/g, (m, name) => NAMED_ENTITIES[name.toLowerCase()] ?? m);
+}
+function safeCodePoint(code) {
+    try {
+        return String.fromCodePoint(code);
+    }
+    catch {
+        return '';
+    }
+}
+/** Inline content of a captured tag body: tags out, entities decoded, whitespace collapsed. */
+function inlineText(html) {
+    return decodeEntities(html.replace(/<[^>]+>/g, ' ')).replace(/\s+/g, ' ').trim();
+}
+/** Remove every `<tag ...>...</tag>` block (non-greedy — nested same-name tags mis-slice, acceptable heuristic). */
+function stripBlocks(html, tags) {
+    let out = html;
+    for (const tag of tags) {
+        out = out.replace(new RegExp(`<${tag}\\b[^>]*>[\\s\\S]*?<\\/${tag}>`, 'gi'), ' ');
+    }
+    return out;
+}
+export function extractHtml(html) {
+    const titleMatch = html.match(/<title[^>]*>([\s\S]*?)<\/title>/i);
+    const title = titleMatch ? inlineText(titleMatch[1]) || null : null;
+    let doc = html.replace(/<!--[\s\S]*?-->/g, ' ');
+    doc = stripBlocks(doc, ['script', 'style', 'noscript', 'template', 'svg', 'iframe', 'canvas', 'head']);
+    // Prefer the semantic article/main region; fall back to <body>, then the whole doc.
+    const region = longestMatch(doc, /<article\b[^>]*>[\s\S]*?<\/article>/gi) ??
+        longestMatch(doc, /<main\b[^>]*>[\s\S]*?<\/main>/gi) ??
+        longestMatch(doc, /<body\b[^>]*>[\s\S]*?<\/body>/gi) ??
+        doc;
+    let text = stripBlocks(region, ['nav', 'header', 'footer', 'aside', 'form', 'button', 'select', 'dialog']);
+    // Structure → markdown. Headings first (they consume their own bodies).
+    text = text.replace(/<h([1-6])[^>]*>([\s\S]*?)<\/h\1>/gi, (_, level, body) => {
+        const line = inlineText(body);
+        return line ? `\n\n${'#'.repeat(Number(level))} ${line}\n\n` : '\n\n';
+    });
+    // Links: keep absolute http(s) targets as markdown; relative links keep text only.
+    text = text.replace(/<a\b[^>]*href=["']?(https?:\/\/[^"'\s>]+)["']?[^>]*>([\s\S]*?)<\/a>/gi, (_, href, body) => {
+        const label = inlineText(body);
+        if (!label)
+            return ' ';
+        return label === href ? ` ${href} ` : ` [${label}](${href}) `;
+    });
+    // Images collapse to alt text — base64 payloads and trackers never reach the model.
+    text = text.replace(/<img\b[^>]*>/gi, (tag) => {
+        const alt = tag.match(/\balt=["']([^"']*)["']/i)?.[1]?.trim();
+        return alt ? ` [IMAGE: ${decodeEntities(alt)}] ` : ' ';
+    });
+    text = text
+        .replace(/<blockquote\b[^>]*>/gi, '\n\n> ')
+        .replace(/<li\b[^>]*>/gi, '\n- ')
+        .replace(/<(td|th)\b[^>]*>/gi, ' | ')
+        .replace(/<br\s*\/?>/gi, '\n')
+        .replace(/<\/(p|div|section|tr|table|ul|ol|blockquote|figure|pre)>/gi, '\n')
+        .replace(/<p\b[^>]*>/gi, '\n\n');
+    text = decodeEntities(text.replace(/<[^>]+>/g, ' '));
+    text = text
+        .replace(/\r/g, '')
+        .replace(/[ \t ]+/g, ' ')
+        .replace(/ ?\n ?/g, '\n')
+        .replace(/\n{3,}/g, '\n\n')
+        .trim();
+    return { title, text };
+}
+// ── Block-page detection ────────────────────────────────────────────────────
+//
+// The dangerous failure class is 200-with-garbage: Cloudflare challenges,
+// consent walls, "enable JavaScript" shells, and paywall stubs all return
+// HTTP 200 with real HTML, and the extractor would hand their boilerplate
+// to the model AS IF it were the article. Detection is deterministic and
+// lives here, not in agent prompts — a model judging "is this a real
+// article?" fails silently one time in ten; a signature scan doesn't.
+// Detected blocks collapse into the same labeled `Error:` shape as an
+// HTTP 403, so prompts only ever govern the RESPONSE to a known failure.
+//
+// False-positive guards: signature scans only run on SHORT extractions
+// (a real article quoting "just a moment" is long); paywall phrasing is
+// held to a tighter threshold than bot-check phrasing because it also
+// appears in the footers of readable articles.
+/** Extraction lengths at or below these invite the corresponding scan. */
+const BOT_CHECK_SCAN_MAX_CHARS = 2_000;
+const PAYWALL_SCAN_MAX_CHARS = 1_500;
+/** A big HTML document that extracts to almost nothing is a JS shell. */
+const THIN_TEXT_CHARS = 400;
+const THIN_HTML_MIN_BYTES = 20_000;
+const BOT_CHECK_SIGNATURES = [
+    [/just a moment/i, 'Cloudflare challenge'],
+    [/checking your browser before accessing/i, 'Cloudflare challenge'],
+    [/verify(?:ing)? (?:that )?you are (?:a )?human/i, 'bot check'],
+    [/enable javascript and cookies to continue/i, 'bot check'],
+    [/are you a robot/i, 'bot check'],
+    [/access to this page has been denied/i, 'access-denied page'],
+    [/pardon our interruption/i, 'bot check'],
+];
+const PAYWALL_SIGNATURES = [
+    [/subscribe to (?:read|continue)/i, 'paywall'],
+    [/subscription (?:is )?required/i, 'paywall'],
+    [/to continue reading(?:,| this)/i, 'paywall'],
+    [/create a free account to (?:read|continue)/i, 'registration wall'],
+    [/log in to (?:read|continue)/i, 'registration wall'],
+];
+/**
+ * Reason the extraction looks like a block page rather than content, or
+ * null when it looks legitimate. `htmlBytes` is the raw document size —
+ * the thinness check needs it to tell "big page, no text" (a JS shell)
+ * from a genuinely small page, which stays valid.
+ */
+export function blockedPageReason(text, htmlBytes) {
+    if (text.length <= BOT_CHECK_SCAN_MAX_CHARS) {
+        for (const [pattern, label] of BOT_CHECK_SIGNATURES) {
+            const hit = text.match(pattern);
+            if (hit)
+                return `page is a ${label} (detected: "${hit[0]}") — content unavailable`;
+        }
+    }
+    if (text.length <= PAYWALL_SCAN_MAX_CHARS) {
+        for (const [pattern, label] of PAYWALL_SIGNATURES) {
+            const hit = text.match(pattern);
+            if (hit)
+                return `page is behind a ${label} (detected: "${hit[0]}") — content unavailable`;
+        }
+    }
+    if (htmlBytes >= THIN_HTML_MIN_BYTES && text.length < THIN_TEXT_CHARS) {
+        return (`page yielded almost no text (${text.length} chars from ${htmlBytes} bytes of HTML) — ` +
+            'likely requires JavaScript or blocks automated readers');
+    }
+    return null;
+}
+function longestMatch(html, pattern) {
+    let best = null;
+    for (const match of html.match(pattern) ?? []) {
+        if (best === null || match.length > best.length)
+            best = match;
+    }
+    return best;
+}
+// ── Windowing (budget + paging) ─────────────────────────────────────────────
+/** Continuation hint rendered into omission markers — the agent copies it verbatim. */
+function continueCall(url, offset) {
+    return `web_extract({"urls":["${url}"],"offset":${offset}})`;
+}
+export function windowContent(text, url, limit, offset) {
+    const total = text.length;
+    if (offset !== undefined) {
+        if (offset >= total) {
+            return `[offset ${offset} is past the end — the cached page is ${total} chars long]`;
+        }
+        const end = Math.min(offset + limit, total);
+        const slice = text.slice(offset, end);
+        const head = `[resuming at char ${offset} of ${total}]\n\n`;
+        const foot = end < total
+            ? `\n\n[... ${total - end} chars remain — ${continueCall(url, end)} to continue ...]`
+            : '';
+        return head + slice + foot;
+    }
+    if (total <= limit)
+        return text;
+    const headLen = Math.floor(limit * HEAD_FRACTION);
+    const tailLen = limit - headLen;
+    const omittedFrom = headLen;
+    const omittedTo = total - tailLen;
+    return (text.slice(0, headLen) +
+        `\n\n[... chars ${omittedFrom}–${omittedTo} of ${total} omitted — ` +
+        `${continueCall(url, omittedFrom)} to continue reading ...]\n\n` +
+        text.slice(omittedTo));
+}
+const pageCache = new Map();
+/** Test hook — the cache is process-global. */
+export function clearWebExtractCache() {
+    pageCache.clear();
+}
+function cachedPage(url) {
+    const entry = pageCache.get(url);
+    if (!entry)
+        return null;
+    if (Date.now() - entry.fetchedAt > CACHE_TTL_MS) {
+        pageCache.delete(url);
+        return null;
+    }
+    return entry.page;
+}
+function cachePage(url, page) {
+    while (pageCache.size >= CACHE_MAX_ENTRIES) {
+        const oldest = pageCache.keys().next().value;
+        if (oldest === undefined)
+            break;
+        pageCache.delete(oldest);
+    }
+    pageCache.set(url, { page, fetchedAt: Date.now() });
+}
+/** Validate scheme + host; returns an error string or the parsed URL. */
+function checkUrl(raw) {
+    let parsed;
+    try {
+        parsed = new URL(raw);
+    }
+    catch {
+        return `Error: "${raw}" is not a valid absolute URL.`;
+    }
+    if (parsed.protocol !== 'http:' && parsed.protocol !== 'https:') {
+        return `Error: only http(s) URLs are supported (got ${parsed.protocol}//).`;
+    }
+    const blocked = blockedHostReason(parsed.hostname);
+    if (blocked)
+        return `Error: refusing to fetch ${parsed.hostname} (${blocked}).`;
+    return parsed;
+}
+/** Read the body with a hard byte cap so a huge response can't balloon memory. */
+async function readBodyCapped(res) {
+    if (!res.body)
+        return '';
+    const reader = res.body.getReader();
+    const chunks = [];
+    let received = 0;
+    for (;;) {
+        const { done, value } = await reader.read();
+        if (done)
+            break;
+        received += value.byteLength;
+        if (received > MAX_FETCH_BYTES) {
+            chunks.push(value.subarray(0, value.byteLength - (received - MAX_FETCH_BYTES)));
+            await reader.cancel();
+            break;
+        }
+        chunks.push(value);
+    }
+    const decoder = new TextDecoder('utf-8'); // charset sniffing deliberately skipped
+    return chunks.map((c) => decoder.decode(c, { stream: true })).join('') + decoder.decode();
+}
+/** Fetch with manual redirect following so every hop passes the SSRF guard. */
+async function fetchPage(url) {
+    let current = url;
+    for (let hop = 0; hop <= MAX_REDIRECTS; hop++) {
+        let res;
+        try {
+            res = await fetch(current, {
+                headers: {
+                    'User-Agent': USER_AGENT,
+                    Accept: 'text/html,application/xhtml+xml,text/plain;q=0.9,*/*;q=0.8',
+                },
+                redirect: 'manual',
+                signal: AbortSignal.timeout(FETCH_TIMEOUT_MS),
+            });
+        }
+        catch (err) {
+            const msg = err instanceof Error ? err.message : String(err);
+            return `Error: fetch failed (${msg}).`;
+        }
+        if (res.status >= 300 && res.status < 400) {
+            const location = res.headers.get('location');
+            if (!location)
+                return `Error: HTTP ${res.status} redirect with no Location header.`;
+            let next;
+            try {
+                next = new URL(location, current);
+            }
+            catch {
+                return `Error: redirect to unparseable URL "${location}".`;
+            }
+            const checked = checkUrl(next.toString());
+            if (typeof checked === 'string')
+                return checked;
+            current = checked;
+            continue;
+        }
+        if (!res.ok)
+            return `Error: HTTP ${res.status} ${res.statusText || ''}`.trim() + '.';
+        const contentType = (res.headers.get('content-type') ?? '').toLowerCase();
+        if (contentType.includes('application/pdf')) {
+            return 'Error: PDF extraction is not supported (keyless v1 reads HTML/text only).';
+        }
+        const isHtml = contentType.includes('html') || contentType === '';
+        const isText = contentType.startsWith('text/') ||
+            contentType.includes('json') ||
+            contentType.includes('xml');
+        if (!isHtml && !isText) {
+            return `Error: unsupported content-type "${contentType}".`;
+        }
+        const body = await readBodyCapped(res);
+        if (!isHtml)
+            return { title: null, text: body.trim() };
+        const page = extractHtml(body);
+        // Block pages are errors, not content — and deliberately NOT cached,
+        // so a later run against a recovered site fetches fresh.
+        const blocked = blockedPageReason(page.text, body.length);
+        if (blocked)
+            return `Error: ${blocked}`;
+        return page;
+    }
+    return `Error: more than ${MAX_REDIRECTS} redirects.`;
+}
+// ── The contract ────────────────────────────────────────────────────────────
+export const webExtractContract = defineTool({
+    name: WEB_EXTRACT_TOOL_NAME,
+    description: 'Read web pages in full. Fetches each URL directly and returns the clean page text ' +
+        '(markdown-ish, no summarization) — use it after web_search, or with any known URL, ' +
+        'to read an article beyond its headline or snippet. Long pages return a head+tail ' +
+        'window with an omission marker; to keep reading, call again with a SINGLE url and ' +
+        'the `offset` from the marker. Up to 5 URLs per call. HTML and plain text only (no PDFs).',
+    schema: z.object({
+        urls: z
+            .array(z.string())
+            .min(1)
+            .max(MAX_URLS)
+            .describe(`Absolute http(s) URLs to read (1–${MAX_URLS}).`),
+        offset: z
+            .number()
+            .int()
+            .min(0)
+            .optional()
+            .describe('Character offset to resume reading a previously truncated page from. ' +
+            'Only valid with exactly one url; copy the value from the omission marker.'),
+    }),
+    execute: async ({ urls, offset }) => {
+        if (offset !== undefined && urls.length !== 1) {
+            return 'Error: `offset` is only valid with exactly one url.';
+        }
+        const limit = extractCharLimit();
+        const blocks = await Promise.all(urls.map(async (raw) => {
+            const checked = checkUrl(raw.trim());
+            if (typeof checked === 'string')
+                return `=== ${raw} ===\n${checked}`;
+            const url = checked.toString();
+            let page = cachedPage(url);
+            if (!page) {
+                const fetched = await fetchPage(checked);
+                if (typeof fetched === 'string')
+                    return `=== ${url} ===\n${fetched}`;
+                page = fetched;
+                cachePage(url, page);
+            }
+            if (!page.text)
+                return `=== ${url} ===\nError: page yielded no readable text.`;
+            const header = page.title ? `=== ${url} ===\nTitle: ${page.title}\n\n` : `=== ${url} ===\n\n`;
+            return header + windowContent(page.text, url, limit, offset);
+        }));
+        return blocks.join('\n\n');
+    },
+});
+/** ADK surface, ready for the registry. */
+export const webExtractTool = toFunctionTool(webExtractContract);

package/dist/lib/tools/webSearchTool.d.ts

@@ -0,0 +1,53 @@
+/**
+ * lib/tools/webSearchTool.ts — provider-agnostic web search.
+ *
+ * WHY this file exists:
+ *   ADK's built-in GOOGLE_SEARCH tool is Gemini grounding — it THROWS for any
+ *   non-Gemini model. But every cloud provider this framework routes to has
+ *   its own native web search: Gemini grounding, Anthropic's web_search
+ *   server tool, OpenAI's Responses web_search tool, xAI's live search.
+ *   Declaring `web_search` in an agent's YAML tools list routes to whichever
+ *   of those the agent's model supports — the YAML stays model-agnostic.
+ *
+ * HOW IT WORKS:
+ *   ADK calls processLlmRequest() on every tool while building the request,
+ *   with llmRequest.model already set (LlmAgent resolves the model first).
+ *   - Gemini model  → push { googleSearch: {} } into config.tools, exactly
+ *     what ADK's own GoogleSearchTool does for Gemini 2+.
+ *   - Anything else → self-register in llmRequest.toolsDict as a sentinel.
+ *     _getDeclaration() returns undefined, so the sentinel is never sent as
+ *     a client-side function tool; each provider adapter calls
+ *     wantsWebSearch(llmRequest) and enables its provider's NATIVE search
+ *     (Claude: web_search server tool; GPT: Responses web_search; Grok:
+ *     Agent Tools web_search). Models with no native search (local Ollama) omit
+ *     the tool and warn — local mode stays keyless by design.
+ *
+ *   `google_search` remains available as the Gemini-only ADK tool for
+ *   backward compatibility; new YAMLs should declare `web_search`.
+ */
+import { BaseTool } from '@google/adk';
+import type { LlmRequest } from '@google/adk';
+export declare const WEB_SEARCH_TOOL_NAME = "web_search";
+export declare class WebSearchTool extends BaseTool {
+    constructor();
+    /** Never a client-side function tool — providers run search server-side. */
+    _getDeclaration(): undefined;
+    /** Server-side tool: nothing to execute locally. */
+    runAsync(): Promise<unknown>;
+    processLlmRequest({ llmRequest }: {
+        llmRequest: LlmRequest;
+    }): Promise<void>;
+}
+/** Shared instance, mirroring ADK's GOOGLE_SEARCH constant pattern. */
+export declare const WEB_SEARCH: WebSearchTool;
+/** True when the agent requested web search (non-Gemini sentinel path). */
+export declare function wantsWebSearch(llmRequest: LlmRequest): boolean;
+/** True for toolsDict entries adapters must NOT send as function tools. */
+export declare function isWebSearchSentinel(tool: unknown): boolean;
+/**
+ * Optional server-side domain filters for xAI's web_search tool, read from
+ * the environment at request-build time (see WHICH CONSTRAINTS above). With
+ * nothing configured this returns {} and the tool ships bare, exactly as it
+ * always has. xAI-only: apply on the xAI path, never on OpenAI's web_search.
+ */
+export declare function xaiWebSearchParamsFromEnv(): Record<string, unknown>;

package/dist/lib/tools/webSearchTool.js

@@ -0,0 +1,126 @@
+/**
+ * lib/tools/webSearchTool.ts — provider-agnostic web search.
+ *
+ * WHY this file exists:
+ *   ADK's built-in GOOGLE_SEARCH tool is Gemini grounding — it THROWS for any
+ *   non-Gemini model. But every cloud provider this framework routes to has
+ *   its own native web search: Gemini grounding, Anthropic's web_search
+ *   server tool, OpenAI's Responses web_search tool, xAI's live search.
+ *   Declaring `web_search` in an agent's YAML tools list routes to whichever
+ *   of those the agent's model supports — the YAML stays model-agnostic.
+ *
+ * HOW IT WORKS:
+ *   ADK calls processLlmRequest() on every tool while building the request,
+ *   with llmRequest.model already set (LlmAgent resolves the model first).
+ *   - Gemini model  → push { googleSearch: {} } into config.tools, exactly
+ *     what ADK's own GoogleSearchTool does for Gemini 2+.
+ *   - Anything else → self-register in llmRequest.toolsDict as a sentinel.
+ *     _getDeclaration() returns undefined, so the sentinel is never sent as
+ *     a client-side function tool; each provider adapter calls
+ *     wantsWebSearch(llmRequest) and enables its provider's NATIVE search
+ *     (Claude: web_search server tool; GPT: Responses web_search; Grok:
+ *     Agent Tools web_search). Models with no native search (local Ollama) omit
+ *     the tool and warn — local mode stays keyless by design.
+ *
+ *   `google_search` remains available as the Gemini-only ADK tool for
+ *   backward compatibility; new YAMLs should declare `web_search`.
+ */
+import { BaseTool } from '@google/adk';
+import { providerForModel } from "../models/providerMap.js";
+export const WEB_SEARCH_TOOL_NAME = 'web_search';
+export class WebSearchTool extends BaseTool {
+    constructor() {
+        super({
+            name: WEB_SEARCH_TOOL_NAME,
+            description: "Web search via the agent model's native search capability " +
+                '(Gemini grounding / Anthropic web_search / OpenAI web_search / xAI live search).',
+        });
+    }
+    /** Never a client-side function tool — providers run search server-side. */
+    _getDeclaration() {
+        return undefined;
+    }
+    /** Server-side tool: nothing to execute locally. */
+    async runAsync() {
+        return Promise.resolve();
+    }
+    async processLlmRequest({ llmRequest }) {
+        if (!llmRequest.model)
+            return;
+        if (providerForModel(llmRequest.model) === 'gemini') {
+            // Native Gemini grounding — same wire shape ADK's GoogleSearchTool
+            // emits for Gemini 2+ (we can't reuse that class: it throws for
+            // non-Gemini models, and this tool must never throw on routing).
+            llmRequest.config = llmRequest.config ?? {};
+            llmRequest.config.tools = llmRequest.config.tools ?? [];
+            llmRequest.config.tools.push({ googleSearch: {} });
+            return;
+        }
+        // Non-Gemini: leave a sentinel for the provider adapter. Safe because
+        // _getDeclaration() is undefined — ADK's appendTools never adds this
+        // to the function-tool declarations sent to the model.
+        llmRequest.toolsDict[WEB_SEARCH_TOOL_NAME] = this;
+    }
+}
+/** Shared instance, mirroring ADK's GOOGLE_SEARCH constant pattern. */
+export const WEB_SEARCH = new WebSearchTool();
+/** True when the agent requested web search (non-Gemini sentinel path). */
+export function wantsWebSearch(llmRequest) {
+    return llmRequest.toolsDict?.[WEB_SEARCH_TOOL_NAME] instanceof WebSearchTool;
+}
+/** True for toolsDict entries adapters must NOT send as function tools. */
+export function isWebSearchSentinel(tool) {
+    return tool instanceof WebSearchTool;
+}
+// ── xAI-only server-side constraints ─────────────────────────────────────────
+//
+// WHICH CONSTRAINTS (verified against docs.x.ai/developers/tools/web-search,
+// 2026-08-08): xAI's web_search accepts domain filters — allowed_domains /
+// excluded_domains (≤5 each, mutually exclusive), nested under a `filters`
+// object on the OpenAI-compatible wire — plus enable_image_search /
+// enable_image_understanding booleans (not plumbed here). Unlike x_search it
+// accepts NO from_date/to_date; there is no server-side date bound for web
+// results, so timeliness must come from the prompt or from x_search.
+//
+// Same doctrine as xSearchTool.xSearchParamsFromEnv: constraints are
+// deployment configuration (XAI_WEB_SEARCH_ALLOWED_DOMAINS /
+// XAI_WEB_SEARCH_EXCLUDED_DOMAINS, comma-separated), never YAML — the YAML
+// stays shareable. Misconfiguration degrades with a warning, never fatally:
+// oversize domain lists truncate, and when both lists are set the allowlist
+// wins. OpenAI's web_search takes no such params — callers must apply this
+// helper on the xAI path only.
+/** xAI's documented ceiling on allowed_domains / excluded_domains. */
+const XAI_WEB_SEARCH_MAX_DOMAINS = 5;
+/** Comma-separated domains from an env var; trimmed, capped at xAI's limit. */
+function domainsFromEnv(name) {
+    const domains = (process.env[name] ?? '')
+        .split(',')
+        .map((d) => d.trim())
+        .filter(Boolean);
+    if (domains.length > XAI_WEB_SEARCH_MAX_DOMAINS) {
+        console.warn(`[web_search] ${name} lists ${domains.length} domains — xAI caps the ` +
+            `list at ${XAI_WEB_SEARCH_MAX_DOMAINS}; keeping the first ${XAI_WEB_SEARCH_MAX_DOMAINS}.`);
+        return domains.slice(0, XAI_WEB_SEARCH_MAX_DOMAINS);
+    }
+    return domains;
+}
+/**
+ * Optional server-side domain filters for xAI's web_search tool, read from
+ * the environment at request-build time (see WHICH CONSTRAINTS above). With
+ * nothing configured this returns {} and the tool ships bare, exactly as it
+ * always has. xAI-only: apply on the xAI path, never on OpenAI's web_search.
+ */
+export function xaiWebSearchParamsFromEnv() {
+    const allowed = domainsFromEnv('XAI_WEB_SEARCH_ALLOWED_DOMAINS');
+    const excluded = domainsFromEnv('XAI_WEB_SEARCH_EXCLUDED_DOMAINS');
+    if (allowed.length > 0 && excluded.length > 0) {
+        console.warn('[web_search] XAI_WEB_SEARCH_ALLOWED_DOMAINS and _EXCLUDED_DOMAINS are ' +
+            'mutually exclusive (xAI rejects both together) — keeping the ' +
+            'allowlist, dropping the exclusions.');
+    }
+    if (allowed.length > 0)
+        return { filters: { allowed_domains: allowed } };
+    if (excluded.length > 0)
+        return { filters: { excluded_domains: excluded } };
+    return {};
+}