@m4ike1/ion-coding-agent 0.1.0

package/dist/core/webfetch/backend-exa.js

@@ -0,0 +1,282 @@
+/**
+ * Exa backend for `webfetch` search: the second, Firecrawl-independent search
+ * path. Two transports, no vendored SDK:
+ *
+ * - With `EXA_API_KEY` (or the `exaApiKey` setting): official REST
+ *   `POST https://api.exa.ai/search` with an `x-api-key` header.
+ * - Without a key: the hosted MCP endpoint (`POST https://mcp.exa.ai/mcp`),
+ *   a single JSON-RPC `tools/call` to `web_search_exa` that answers with a
+ *   formatted text payload over SSE. No account required.
+ *
+ * Page fetching stays with Firecrawl/undici; Exa is search-only here so the
+ * keyless path never has to invent a document fetch.
+ */
+import { request as undiciRequest } from "undici";
+import { clampLimit, WEBFETCH_REQUEST_TIMEOUT_MS, WebfetchError } from "./guardrails.js";
+export const EXA_BASE_URL = "https://api.exa.ai";
+export const EXA_MCP_URL = "https://mcp.exa.ai/mcp";
+export const EXA_API_KEY_ENV = "EXA_API_KEY";
+/** Exa's public search cap; the tool clamps lower anyway. */
+export const WEBFETCH_EXA_MAX_LIMIT = 100;
+const EXA_HTTP_HEADROOM_MS = 5_000;
+const EXA_SEARCH_TYPE = "auto";
+/** Explicit settings value wins; `EXA_API_KEY` env is the fallback. Unset means the keyless hosted MCP tier. */
+export function resolveExaApiKey(explicit, env = process.env) {
+    const trimmed = explicit?.trim() || env[EXA_API_KEY_ENV]?.trim();
+    return trimmed || undefined;
+}
+export class ExaError extends WebfetchError {
+    status;
+    /** True when the caller should try the next search backend. */
+    fallback;
+    constructor(message, options) {
+        super(message, options.code);
+        this.name = "ExaError";
+        this.status = options.status;
+        this.fallback = options.fallback;
+    }
+}
+/** True when a failed Exa call should fall through to the next search backend. */
+export function isExaFallbackEligible(error) {
+    return error instanceof ExaError ? error.fallback : false;
+}
+async function defaultPost(url, body, init) {
+    const timeoutSignal = AbortSignal.timeout(init.timeoutMs + EXA_HTTP_HEADROOM_MS);
+    const signal = init.signal ? AbortSignal.any([init.signal, timeoutSignal]) : timeoutSignal;
+    let response;
+    try {
+        response = await undiciRequest(url, {
+            method: "POST",
+            headers: { "content-type": "application/json", ...init.headers },
+            body: JSON.stringify(body),
+            signal,
+        });
+    }
+    catch (error) {
+        if (timeoutSignal.aborted && !init.signal?.aborted) {
+            throw new ExaError(`Exa request to ${new URL(url).pathname} timed out`, { code: "timeout", fallback: true });
+        }
+        if (init.signal?.aborted) {
+            throw new Error("Operation aborted");
+        }
+        const reason = error instanceof Error ? error.message : String(error);
+        throw new ExaError(`Exa request to ${new URL(url).pathname} failed: ${reason}`, {
+            code: "transport",
+            fallback: true,
+        });
+    }
+    try {
+        return { status: response.statusCode, text: await response.body.text() };
+    }
+    catch (error) {
+        const reason = error instanceof Error ? error.message : String(error);
+        throw new ExaError(`Exa response could not be read: ${reason}`, { code: "transport", fallback: true });
+    }
+}
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function asString(value) {
+    return typeof value === "string" && value.length > 0 ? value : undefined;
+}
+function asNumber(value) {
+    return typeof value === "number" && Number.isFinite(value) ? value : undefined;
+}
+/** `N/A` is how the hosted MCP tool renders missing metadata. */
+function metaOrUndefined(value) {
+    if (!value)
+        return undefined;
+    const trimmed = value.trim();
+    return trimmed === "" || trimmed.toUpperCase() === "N/A" ? undefined : trimmed;
+}
+/**
+ * Parse the keyless hosted-MCP payload. Results are blocks of
+ * `Title:/URL:/Published:/Author:/Highlights:` lines; a result without a URL is
+ * dropped rather than surfaced as a broken ref.
+ */
+export function parseExaMcpResults(text) {
+    const results = [];
+    for (const block of text.split(/\n(?=Title:\s)/)) {
+        const title = /^Title:\s*(.+)$/m.exec(block)?.[1]?.trim();
+        const url = /^URL:\s*(.+)$/m.exec(block)?.[1]?.trim();
+        if (!url || !/^https?:\/\//i.test(url))
+            continue;
+        const publishedDate = metaOrUndefined(/^Published:\s*(.+)$/m.exec(block)?.[1]);
+        const highlights = /^Highlights:\s*\n?([\s\S]*)$/m.exec(block)?.[1]?.trim() ?? "";
+        results.push({ title: title || url, url, snippet: highlights, publishedDate });
+    }
+    return results;
+}
+/** Extract the first JSON-RPC text content from a plain or SSE-framed body. */
+export function extractMcpText(body) {
+    const candidates = [];
+    const trimmed = body.trim();
+    if (trimmed.startsWith("{")) {
+        candidates.push(trimmed);
+    }
+    for (const line of body.split("\n")) {
+        if (line.startsWith("data: ")) {
+            candidates.push(line.slice(6).trim());
+        }
+    }
+    for (const candidate of candidates) {
+        if (!candidate.startsWith("{"))
+            continue;
+        let json;
+        try {
+            json = JSON.parse(candidate);
+        }
+        catch {
+            continue;
+        }
+        if (!isRecord(json) || !isRecord(json.result) || !Array.isArray(json.result.content))
+            continue;
+        for (const item of json.result.content) {
+            if (isRecord(item) && item.type === "text" && typeof item.text === "string" && item.text.trim()) {
+                return item.text;
+            }
+        }
+    }
+    return undefined;
+}
+function normalizeRestResults(json) {
+    if (!isRecord(json) || !Array.isArray(json.results))
+        return [];
+    const results = [];
+    for (const entry of json.results) {
+        if (!isRecord(entry))
+            continue;
+        const url = asString(entry.url);
+        if (!url)
+            continue;
+        const highlights = Array.isArray(entry.highlights)
+            ? entry.highlights.filter((item) => typeof item === "string")
+            : [];
+        const text = asString(entry.text);
+        results.push({
+            title: asString(entry.title) || url,
+            url,
+            snippet: highlights.join("\n") || (text?.slice(0, 300) ?? ""),
+            publishedDate: asString(entry.publishedDate),
+        });
+    }
+    return results;
+}
+function readRestMeta(json) {
+    if (!isRecord(json))
+        return {};
+    const meta = {};
+    const requestId = asString(json.requestId);
+    if (requestId)
+        meta.requestId = requestId;
+    const cost = isRecord(json.costDollars) ? asNumber(json.costDollars.total) : undefined;
+    if (cost !== undefined)
+        meta.costDollars = cost;
+    return meta;
+}
+function exaErrorMessage(text) {
+    try {
+        const json = JSON.parse(text);
+        if (isRecord(json) && isRecord(json.error) && typeof json.error.message === "string") {
+            return json.error.message;
+        }
+        if (isRecord(json) && typeof json.error === "string")
+            return json.error;
+    }
+    catch {
+        return undefined;
+    }
+    return undefined;
+}
+function throwForStatus(status, text) {
+    const detail = exaErrorMessage(text);
+    const message = `Exa request failed with status ${status}${detail ? `: ${detail}` : ""}`;
+    // Auth, quota, and server failures are worth another backend; a 4xx request
+    // shape error is not, and would fail the same way everywhere.
+    if (status === 401 || status === 402 || status === 403 || status === 429 || status >= 500) {
+        throw new ExaError(message, { code: "transport", status, fallback: true });
+    }
+    throw new ExaError(message, { code: "transport", status, fallback: false });
+}
+export function createExaBackend(options = {}) {
+    const timeoutMs = options.timeoutMs ?? WEBFETCH_REQUEST_TIMEOUT_MS;
+    const post = options.post ?? defaultPost;
+    const backend = {
+        id: "exa",
+        lastMeta: undefined,
+        async search(intent, searchOptions) {
+            if (!intent.query) {
+                throw new Error("Search query must not be empty");
+            }
+            // Exa has no image vertical, so image-only intents are answered by
+            // Firecrawl when it is available. With no Exa-capable modality left,
+            // return nothing instead of inventing web results for an image request.
+            const webCount = intent.results.web ?? 0;
+            const newsCount = intent.results.news ?? 0;
+            if (webCount + newsCount === 0)
+                return [];
+            const limit = clampLimit(webCount + newsCount, {
+                fallback: 10,
+                min: 1,
+                max: WEBFETCH_EXA_MAX_LIMIT,
+            });
+            if (options.apiKey) {
+                const response = await post(`${EXA_BASE_URL}/search`, {
+                    query: intent.query,
+                    numResults: limit,
+                    type: EXA_SEARCH_TYPE,
+                    ...(intent.filters.recencyMs !== undefined
+                        ? { startPublishedDate: new Date(Date.now() - intent.filters.recencyMs).toISOString() }
+                        : {}),
+                    ...(intent.filters.domains ? { includeDomains: intent.filters.domains } : {}),
+                    contents: { highlights: true },
+                }, { headers: { "x-api-key": options.apiKey }, timeoutMs, signal: searchOptions.signal });
+                if (response.status !== 200) {
+                    throwForStatus(response.status, response.text);
+                }
+                let json;
+                try {
+                    json = JSON.parse(response.text);
+                }
+                catch {
+                    throw new ExaError("Exa returned invalid JSON", { code: "transport", fallback: true });
+                }
+                backend.lastMeta = readRestMeta(json);
+                return normalizeRestResults(json);
+            }
+            // The keyless MCP tier exposes no recency or domain controls, so a filtered
+            // request cannot be honored here; say so instead of silently dropping the
+            // filter. The keyed REST tier above supports both.
+            if (intent.filters.recencyMs !== undefined || intent.filters.domains) {
+                throw new ExaError("Exa's keyless search tier cannot apply recency or domain filters; set EXA_API_KEY to use them", { code: "unavailable", fallback: false });
+            }
+            const response = await post(EXA_MCP_URL, {
+                jsonrpc: "2.0",
+                id: 1,
+                method: "tools/call",
+                params: {
+                    name: "web_search_exa",
+                    arguments: { query: intent.query, type: EXA_SEARCH_TYPE, numResults: limit },
+                },
+            }, { headers: { accept: "application/json, text/event-stream" }, timeoutMs, signal: searchOptions.signal });
+            if (response.status !== 200) {
+                throwForStatus(response.status, response.text);
+            }
+            const text = extractMcpText(response.text);
+            if (!text) {
+                throw new ExaError("Exa returned no readable result payload", { code: "empty", fallback: true });
+            }
+            backend.lastMeta = undefined;
+            return parseExaMcpResults(text);
+        },
+        async fetch(_url) {
+            // Page fetching is Firecrawl/undici territory; the Exa backend is search-only.
+            throw new ExaError("The Exa backend does not fetch pages; use webextract", {
+                code: "unavailable",
+                fallback: false,
+            });
+        },
+    };
+    return backend;
+}
+//# sourceMappingURL=backend-exa.js.map

package/dist/core/webfetch/backend-exa.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"backend-exa.js","sourceRoot":"","sources":["../../../src/core/webfetch/backend-exa.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Exa backend for `webfetch` search: the second, Firecrawl-independent search\n * path. Two transports, no vendored SDK:\n *\n * - With `EXA_API_KEY` (or the `exaApiKey` setting): official REST\n *   `POST https://api.exa.ai/search` with an `x-api-key` header.\n * - Without a key: the hosted MCP endpoint (`POST https://mcp.exa.ai/mcp`),\n *   a single JSON-RPC `tools/call` to `web_search_exa` that answers with a\n *   formatted text payload over SSE. No account required.\n *\n * Page fetching stays with Firecrawl/undici; Exa is search-only here so the\n * keyless path never has to invent a document fetch.\n */\n\nimport { request as undiciRequest } from \"undici\";\nimport type { WebDocument, WebSearchBackend, WebSearchResult } from \"./backend.ts\";\nimport { clampLimit, WEBFETCH_REQUEST_TIMEOUT_MS, WebfetchError, type WebfetchErrorCode } from \"./guardrails.ts\";\nimport type { ResolvedSearchIntent } from \"./search-intent.ts\";\n\nexport const EXA_BASE_URL = \"https://api.exa.ai\";\nexport const EXA_MCP_URL = \"https://mcp.exa.ai/mcp\";\nexport const EXA_API_KEY_ENV = \"EXA_API_KEY\";\n/** Exa's public search cap; the tool clamps lower anyway. */\nexport const WEBFETCH_EXA_MAX_LIMIT = 100;\nconst EXA_HTTP_HEADROOM_MS = 5_000;\nconst EXA_SEARCH_TYPE = \"auto\";\n\n/** Explicit settings value wins; `EXA_API_KEY` env is the fallback. Unset means the keyless hosted MCP tier. */\nexport function resolveExaApiKey(explicit?: string, env: NodeJS.ProcessEnv = process.env): string | undefined {\n\tconst trimmed = explicit?.trim() || env[EXA_API_KEY_ENV]?.trim();\n\treturn trimmed || undefined;\n}\n\nexport class ExaError extends WebfetchError {\n\treadonly status?: number;\n\t/** True when the caller should try the next search backend. */\n\treadonly fallback: boolean;\n\tconstructor(message: string, options: { code: WebfetchErrorCode; status?: number; fallback: boolean }) {\n\t\tsuper(message, options.code);\n\t\tthis.name = \"ExaError\";\n\t\tthis.status = options.status;\n\t\tthis.fallback = options.fallback;\n\t}\n}\n\n/** True when a failed Exa call should fall through to the next search backend. */\nexport function isExaFallbackEligible(error: unknown): boolean {\n\treturn error instanceof ExaError ? error.fallback : false;\n}\n\nexport interface ExaBackend extends WebSearchBackend {\n\treadonly id: \"exa\";\n\t/** `requestId`/`costDollars` from the most recent keyed search, for observability. */\n\tlastMeta: { requestId?: string; costDollars?: number } | undefined;\n}\n\nexport type ExaPostFn = (\n\turl: string,\n\tbody: Record<string, unknown>,\n\tinit: { headers: Record<string, string>; timeoutMs: number; signal?: AbortSignal },\n) => Promise<{ status: number; text: string }>;\n\nasync function defaultPost(\n\turl: string,\n\tbody: Record<string, unknown>,\n\tinit: { headers: Record<string, string>; timeoutMs: number; signal?: AbortSignal },\n): Promise<{ status: number; text: string }> {\n\tconst timeoutSignal = AbortSignal.timeout(init.timeoutMs + EXA_HTTP_HEADROOM_MS);\n\tconst signal = init.signal ? AbortSignal.any([init.signal, timeoutSignal]) : timeoutSignal;\n\tlet response: Awaited<ReturnType<typeof undiciRequest>>;\n\ttry {\n\t\tresponse = await undiciRequest(url, {\n\t\t\tmethod: \"POST\",\n\t\t\theaders: { \"content-type\": \"application/json\", ...init.headers },\n\t\t\tbody: JSON.stringify(body),\n\t\t\tsignal,\n\t\t});\n\t} catch (error) {\n\t\tif (timeoutSignal.aborted && !init.signal?.aborted) {\n\t\t\tthrow new ExaError(`Exa request to ${new URL(url).pathname} timed out`, { code: \"timeout\", fallback: true });\n\t\t}\n\t\tif (init.signal?.aborted) {\n\t\t\tthrow new Error(\"Operation aborted\");\n\t\t}\n\t\tconst reason = error instanceof Error ? error.message : String(error);\n\t\tthrow new ExaError(`Exa request to ${new URL(url).pathname} failed: ${reason}`, {\n\t\t\tcode: \"transport\",\n\t\t\tfallback: true,\n\t\t});\n\t}\n\ttry {\n\t\treturn { status: response.statusCode, text: await response.body.text() };\n\t} catch (error) {\n\t\tconst reason = error instanceof Error ? error.message : String(error);\n\t\tthrow new ExaError(`Exa response could not be read: ${reason}`, { code: \"transport\", fallback: true });\n\t}\n}\n\nfunction isRecord(value: unknown): value is Record<string, unknown> {\n\treturn typeof value === \"object\" && value !== null && !Array.isArray(value);\n}\n\nfunction asString(value: unknown): string | undefined {\n\treturn typeof value === \"string\" && value.length > 0 ? value : undefined;\n}\n\nfunction asNumber(value: unknown): number | undefined {\n\treturn typeof value === \"number\" && Number.isFinite(value) ? value : undefined;\n}\n\n/** `N/A` is how the hosted MCP tool renders missing metadata. */\nfunction metaOrUndefined(value: string | undefined): string | undefined {\n\tif (!value) return undefined;\n\tconst trimmed = value.trim();\n\treturn trimmed === \"\" || trimmed.toUpperCase() === \"N/A\" ? undefined : trimmed;\n}\n\n/**\n * Parse the keyless hosted-MCP payload. Results are blocks of\n * `Title:/URL:/Published:/Author:/Highlights:` lines; a result without a URL is\n * dropped rather than surfaced as a broken ref.\n */\nexport function parseExaMcpResults(text: string): WebSearchResult[] {\n\tconst results: WebSearchResult[] = [];\n\tfor (const block of text.split(/\\n(?=Title:\\s)/)) {\n\t\tconst title = /^Title:\\s*(.+)$/m.exec(block)?.[1]?.trim();\n\t\tconst url = /^URL:\\s*(.+)$/m.exec(block)?.[1]?.trim();\n\t\tif (!url || !/^https?:\\/\\//i.test(url)) continue;\n\t\tconst publishedDate = metaOrUndefined(/^Published:\\s*(.+)$/m.exec(block)?.[1]);\n\t\tconst highlights = /^Highlights:\\s*\\n?([\\s\\S]*)$/m.exec(block)?.[1]?.trim() ?? \"\";\n\t\tresults.push({ title: title || url, url, snippet: highlights, publishedDate });\n\t}\n\treturn results;\n}\n\n/** Extract the first JSON-RPC text content from a plain or SSE-framed body. */\nexport function extractMcpText(body: string): string | undefined {\n\tconst candidates: string[] = [];\n\tconst trimmed = body.trim();\n\tif (trimmed.startsWith(\"{\")) {\n\t\tcandidates.push(trimmed);\n\t}\n\tfor (const line of body.split(\"\\n\")) {\n\t\tif (line.startsWith(\"data: \")) {\n\t\t\tcandidates.push(line.slice(6).trim());\n\t\t}\n\t}\n\tfor (const candidate of candidates) {\n\t\tif (!candidate.startsWith(\"{\")) continue;\n\t\tlet json: unknown;\n\t\ttry {\n\t\t\tjson = JSON.parse(candidate) as unknown;\n\t\t} catch {\n\t\t\tcontinue;\n\t\t}\n\t\tif (!isRecord(json) || !isRecord(json.result) || !Array.isArray(json.result.content)) continue;\n\t\tfor (const item of json.result.content) {\n\t\t\tif (isRecord(item) && item.type === \"text\" && typeof item.text === \"string\" && item.text.trim()) {\n\t\t\t\treturn item.text;\n\t\t\t}\n\t\t}\n\t}\n\treturn undefined;\n}\n\nfunction normalizeRestResults(json: unknown): WebSearchResult[] {\n\tif (!isRecord(json) || !Array.isArray(json.results)) return [];\n\tconst results: WebSearchResult[] = [];\n\tfor (const entry of json.results) {\n\t\tif (!isRecord(entry)) continue;\n\t\tconst url = asString(entry.url);\n\t\tif (!url) continue;\n\t\tconst highlights = Array.isArray(entry.highlights)\n\t\t\t? entry.highlights.filter((item): item is string => typeof item === \"string\")\n\t\t\t: [];\n\t\tconst text = asString(entry.text);\n\t\tresults.push({\n\t\t\ttitle: asString(entry.title) || url,\n\t\t\turl,\n\t\t\tsnippet: highlights.join(\"\\n\") || (text?.slice(0, 300) ?? \"\"),\n\t\t\tpublishedDate: asString(entry.publishedDate),\n\t\t});\n\t}\n\treturn results;\n}\n\nfunction readRestMeta(json: unknown): { requestId?: string; costDollars?: number } {\n\tif (!isRecord(json)) return {};\n\tconst meta: { requestId?: string; costDollars?: number } = {};\n\tconst requestId = asString(json.requestId);\n\tif (requestId) meta.requestId = requestId;\n\tconst cost = isRecord(json.costDollars) ? asNumber(json.costDollars.total) : undefined;\n\tif (cost !== undefined) meta.costDollars = cost;\n\treturn meta;\n}\n\nfunction exaErrorMessage(text: string): string | undefined {\n\ttry {\n\t\tconst json = JSON.parse(text) as unknown;\n\t\tif (isRecord(json) && isRecord(json.error) && typeof json.error.message === \"string\") {\n\t\t\treturn json.error.message;\n\t\t}\n\t\tif (isRecord(json) && typeof json.error === \"string\") return json.error;\n\t} catch {\n\t\treturn undefined;\n\t}\n\treturn undefined;\n}\n\nfunction throwForStatus(status: number, text: string): never {\n\tconst detail = exaErrorMessage(text);\n\tconst message = `Exa request failed with status ${status}${detail ? `: ${detail}` : \"\"}`;\n\t// Auth, quota, and server failures are worth another backend; a 4xx request\n\t// shape error is not, and would fail the same way everywhere.\n\tif (status === 401 || status === 402 || status === 403 || status === 429 || status >= 500) {\n\t\tthrow new ExaError(message, { code: \"transport\", status, fallback: true });\n\t}\n\tthrow new ExaError(message, { code: \"transport\", status, fallback: false });\n}\n\nexport interface ExaBackendOptions {\n\tapiKey?: string;\n\ttimeoutMs?: number;\n\tpost?: ExaPostFn;\n}\n\nexport function createExaBackend(options: ExaBackendOptions = {}): ExaBackend {\n\tconst timeoutMs = options.timeoutMs ?? WEBFETCH_REQUEST_TIMEOUT_MS;\n\tconst post = options.post ?? defaultPost;\n\n\tconst backend: ExaBackend = {\n\t\tid: \"exa\",\n\t\tlastMeta: undefined,\n\t\tasync search(\n\t\t\tintent: ResolvedSearchIntent,\n\t\t\tsearchOptions: { limit: number; signal?: AbortSignal },\n\t\t): Promise<WebSearchResult[]> {\n\t\t\tif (!intent.query) {\n\t\t\t\tthrow new Error(\"Search query must not be empty\");\n\t\t\t}\n\t\t\t// Exa has no image vertical, so image-only intents are answered by\n\t\t\t// Firecrawl when it is available. With no Exa-capable modality left,\n\t\t\t// return nothing instead of inventing web results for an image request.\n\t\t\tconst webCount = intent.results.web ?? 0;\n\t\t\tconst newsCount = intent.results.news ?? 0;\n\t\t\tif (webCount + newsCount === 0) return [];\n\t\t\tconst limit = clampLimit(webCount + newsCount, {\n\t\t\t\tfallback: 10,\n\t\t\t\tmin: 1,\n\t\t\t\tmax: WEBFETCH_EXA_MAX_LIMIT,\n\t\t\t});\n\t\t\tif (options.apiKey) {\n\t\t\t\tconst response = await post(\n\t\t\t\t\t`${EXA_BASE_URL}/search`,\n\t\t\t\t\t{\n\t\t\t\t\t\tquery: intent.query,\n\t\t\t\t\t\tnumResults: limit,\n\t\t\t\t\t\ttype: EXA_SEARCH_TYPE,\n\t\t\t\t\t\t...(intent.filters.recencyMs !== undefined\n\t\t\t\t\t\t\t? { startPublishedDate: new Date(Date.now() - intent.filters.recencyMs).toISOString() }\n\t\t\t\t\t\t\t: {}),\n\t\t\t\t\t\t...(intent.filters.domains ? { includeDomains: intent.filters.domains } : {}),\n\t\t\t\t\t\tcontents: { highlights: true },\n\t\t\t\t\t},\n\t\t\t\t\t{ headers: { \"x-api-key\": options.apiKey }, timeoutMs, signal: searchOptions.signal },\n\t\t\t\t);\n\t\t\t\tif (response.status !== 200) {\n\t\t\t\t\tthrowForStatus(response.status, response.text);\n\t\t\t\t}\n\t\t\t\tlet json: unknown;\n\t\t\t\ttry {\n\t\t\t\t\tjson = JSON.parse(response.text) as unknown;\n\t\t\t\t} catch {\n\t\t\t\t\tthrow new ExaError(\"Exa returned invalid JSON\", { code: \"transport\", fallback: true });\n\t\t\t\t}\n\t\t\t\tbackend.lastMeta = readRestMeta(json);\n\t\t\t\treturn normalizeRestResults(json);\n\t\t\t}\n\n\t\t\t// The keyless MCP tier exposes no recency or domain controls, so a filtered\n\t\t\t// request cannot be honored here; say so instead of silently dropping the\n\t\t\t// filter. The keyed REST tier above supports both.\n\t\t\tif (intent.filters.recencyMs !== undefined || intent.filters.domains) {\n\t\t\t\tthrow new ExaError(\n\t\t\t\t\t\"Exa's keyless search tier cannot apply recency or domain filters; set EXA_API_KEY to use them\",\n\t\t\t\t\t{ code: \"unavailable\", fallback: false },\n\t\t\t\t);\n\t\t\t}\n\t\t\tconst response = await post(\n\t\t\t\tEXA_MCP_URL,\n\t\t\t\t{\n\t\t\t\t\tjsonrpc: \"2.0\",\n\t\t\t\t\tid: 1,\n\t\t\t\t\tmethod: \"tools/call\",\n\t\t\t\t\tparams: {\n\t\t\t\t\t\tname: \"web_search_exa\",\n\t\t\t\t\t\targuments: { query: intent.query, type: EXA_SEARCH_TYPE, numResults: limit },\n\t\t\t\t\t},\n\t\t\t\t},\n\t\t\t\t{ headers: { accept: \"application/json, text/event-stream\" }, timeoutMs, signal: searchOptions.signal },\n\t\t\t);\n\t\t\tif (response.status !== 200) {\n\t\t\t\tthrowForStatus(response.status, response.text);\n\t\t\t}\n\t\t\tconst text = extractMcpText(response.text);\n\t\t\tif (!text) {\n\t\t\t\tthrow new ExaError(\"Exa returned no readable result payload\", { code: \"empty\", fallback: true });\n\t\t\t}\n\t\t\tbackend.lastMeta = undefined;\n\t\t\treturn parseExaMcpResults(text);\n\t\t},\n\t\tasync fetch(_url: string): Promise<WebDocument> {\n\t\t\t// Page fetching is Firecrawl/undici territory; the Exa backend is search-only.\n\t\t\tthrow new ExaError(\"The Exa backend does not fetch pages; use webextract\", {\n\t\t\t\tcode: \"unavailable\",\n\t\t\t\tfallback: false,\n\t\t\t});\n\t\t},\n\t};\n\treturn backend;\n}\n"]}

package/dist/core/webfetch/backend-firecrawl.d.ts

@@ -0,0 +1,59 @@
+/**
+ * Firecrawl backend for webfetch: thin `undici` POSTs to the hosted Firecrawl
+ * API. The SDK is never vendored (extra `axios` dep) and the server is never
+ * vendored (AGPL-3.0).
+ *
+ * Auth is an optional `Bearer` key, omitted entirely on the keyless tier.
+ * Resolve it with `resolveFirecrawlApiKey` (explicit settings value first,
+ * `FIRECRAWL_API_KEY` env second).
+ */
+import type { WebSearchBackend } from "./backend.ts";
+import { WebfetchError, type WebfetchErrorCode } from "./guardrails.ts";
+export declare const FIRECRAWL_BASE_URL = "https://api.firecrawl.dev";
+export declare const FIRECRAWL_API_KEY_ENV = "FIRECRAWL_API_KEY";
+/** Explicit settings value wins; `FIRECRAWL_API_KEY` env is the fallback. Keyless (undefined) works with lower limits. */
+export declare function resolveFirecrawlApiKey(explicit?: string, env?: NodeJS.ProcessEnv): string | undefined;
+export declare class FirecrawlError extends WebfetchError {
+    readonly status?: number;
+    /** True when the caller should try the `undici` direct-fetch fallback (transport/auth failure, never content failure). */
+    readonly fallback: boolean;
+    constructor(message: string, options: {
+        code: WebfetchErrorCode;
+        status?: number;
+        fallback: boolean;
+    });
+}
+/**
+ * The keyless Firecrawl tier refused this network (403 "your IP address looks
+ * suspicious", 401 without a key, or 429 on the shared anonymous pool). This is
+ * provider-side and often IP-dependent, so the message names the exact fix
+ * instead of leaking the raw status. Direct page fetch still works through the
+ * `undici` fallback; only search is unavailable.
+ */
+export declare function keylessUnavailableMessage(status: number, path: string): string;
+/** True when a failed Firecrawl call should fall back to direct `undici` fetch instead of surfacing the error. */
+export declare function isFallbackEligible(error: unknown): boolean;
+export interface FirecrawlResponseMeta {
+    warning?: string;
+    creditsUsed?: number;
+}
+export interface FirecrawlBackend extends WebSearchBackend {
+    readonly id: "firecrawl";
+    /** `warning`/`creditsUsed` from the most recent search or scrape, for cost observability in tool details. */
+    lastMeta: FirecrawlResponseMeta | undefined;
+}
+export type FirecrawlPostFn = (path: string, body: Record<string, unknown>, init: {
+    headers: Record<string, string>;
+    timeoutMs: number;
+    signal?: AbortSignal;
+}) => Promise<{
+    status: number;
+    json: unknown;
+}>;
+export interface FirecrawlBackendOptions {
+    apiKey?: string;
+    timeoutMs?: number;
+    post?: FirecrawlPostFn;
+}
+export declare function createFirecrawlBackend(options?: FirecrawlBackendOptions): FirecrawlBackend;
+//# sourceMappingURL=backend-firecrawl.d.ts.map

package/dist/core/webfetch/backend-firecrawl.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"backend-firecrawl.d.ts","sourceRoot":"","sources":["../../../src/core/webfetch/backend-firecrawl.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAGH,OAAO,KAAK,EAAe,gBAAgB,EAAmB,MAAM,cAAc,CAAC;AACnF,OAAO,EAIN,aAAa,EACb,KAAK,iBAAiB,EACtB,MAAM,iBAAiB,CAAC;AAGzB,eAAO,MAAM,kBAAkB,8BAA8B,CAAC;AAC9D,eAAO,MAAM,qBAAqB,sBAAsB,CAAC;AAIzD,0HAA0H;AAC1H,wBAAgB,sBAAsB,CAAC,QAAQ,CAAC,EAAE,MAAM,EAAE,GAAG,GAAE,MAAM,CAAC,UAAwB,GAAG,MAAM,GAAG,SAAS,CAGlH;AAED,qBAAa,cAAe,SAAQ,aAAa;IAChD,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IACzB,0HAA0H;IAC1H,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAC;IAC3B,YAAY,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE;QAAE,IAAI,EAAE,iBAAiB,CAAC;QAAC,MAAM,CAAC,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,OAAO,CAAA;KAAE,EAKpG;CACD;AAED;;;;;;GAMG;AACH,wBAAgB,yBAAyB,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,CAa9E;AAED,kHAAkH;AAClH,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAM1D;AAED,MAAM,WAAW,qBAAqB;IACrC,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,WAAW,CAAC,EAAE,MAAM,CAAC;CACrB;AAED,MAAM,WAAW,gBAAiB,SAAQ,gBAAgB;IACzD,QAAQ,CAAC,EAAE,EAAE,WAAW,CAAC;IACzB,6GAA6G;IAC7G,QAAQ,EAAE,qBAAqB,GAAG,SAAS,CAAC;CAC5C;AAED,MAAM,MAAM,eAAe,GAAG,CAC7B,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC7B,IAAI,EAAE;IAAE,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAAC,SAAS,EAAE,MAAM,CAAC;IAAC,MAAM,CAAC,EAAE,WAAW,CAAA;CAAE,KAC9E,OAAO,CAAC;IAAE,MAAM,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,OAAO,CAAA;CAAE,CAAC,CAAC;AA2ChD,MAAM,WAAW,uBAAuB;IACvC,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,IAAI,CAAC,EAAE,eAAe,CAAC;CACvB;AAoGD,wBAAgB,sBAAsB,CAAC,OAAO,GAAE,uBAA4B,GAAG,gBAAgB,CAqJ9F","sourcesContent":["/**\n * Firecrawl backend for webfetch: thin `undici` POSTs to the hosted Firecrawl\n * API. The SDK is never vendored (extra `axios` dep) and the server is never\n * vendored (AGPL-3.0).\n *\n * Auth is an optional `Bearer` key, omitted entirely on the keyless tier.\n * Resolve it with `resolveFirecrawlApiKey` (explicit settings value first,\n * `FIRECRAWL_API_KEY` env second).\n */\n\nimport { request as undiciRequest } from \"undici\";\nimport type { WebDocument, WebSearchBackend, WebSearchResult } from \"./backend.ts\";\nimport {\n\tclampLimit,\n\tWEBFETCH_FIRECRAWL_MAX_LIMIT,\n\tWEBFETCH_REQUEST_TIMEOUT_MS,\n\tWebfetchError,\n\ttype WebfetchErrorCode,\n} from \"./guardrails.ts\";\nimport type { ResolvedSearchIntent } from \"./search-intent.ts\";\n\nexport const FIRECRAWL_BASE_URL = \"https://api.firecrawl.dev\";\nexport const FIRECRAWL_API_KEY_ENV = \"FIRECRAWL_API_KEY\";\nconst FIRECRAWL_502_MAX_ATTEMPTS = 3;\nconst FIRECRAWL_HTTP_HEADROOM_MS = 5_000;\n\n/** Explicit settings value wins; `FIRECRAWL_API_KEY` env is the fallback. Keyless (undefined) works with lower limits. */\nexport function resolveFirecrawlApiKey(explicit?: string, env: NodeJS.ProcessEnv = process.env): string | undefined {\n\tconst trimmed = explicit?.trim() || env[FIRECRAWL_API_KEY_ENV]?.trim();\n\treturn trimmed || undefined;\n}\n\nexport class FirecrawlError extends WebfetchError {\n\treadonly status?: number;\n\t/** True when the caller should try the `undici` direct-fetch fallback (transport/auth failure, never content failure). */\n\treadonly fallback: boolean;\n\tconstructor(message: string, options: { code: WebfetchErrorCode; status?: number; fallback: boolean }) {\n\t\tsuper(message, options.code);\n\t\tthis.name = \"FirecrawlError\";\n\t\tthis.status = options.status;\n\t\tthis.fallback = options.fallback;\n\t}\n}\n\n/**\n * The keyless Firecrawl tier refused this network (403 \"your IP address looks\n * suspicious\", 401 without a key, or 429 on the shared anonymous pool). This is\n * provider-side and often IP-dependent, so the message names the exact fix\n * instead of leaking the raw status. Direct page fetch still works through the\n * `undici` fallback; only search is unavailable.\n */\nexport function keylessUnavailableMessage(status: number, path: string): string {\n\tconst reason =\n\t\tstatus === 429\n\t\t\t? \"the keyless rate limit was exhausted\"\n\t\t\t: status === 401\n\t\t\t\t? \"no API key was sent\"\n\t\t\t\t: \"this network is not allowed on the anonymous tier\";\n\treturn [\n\t\t`Firecrawl ${path} is unavailable: ${reason} (status ${status}).`,\n\t\t\"Set a Firecrawl API key to fix this: add the `firecrawlApiKey` setting or the\",\n\t\t\"`FIRECRAWL_API_KEY` environment variable, then retry.\",\n\t\t\"`webextract` still works without a key: it fetches pages directly.\",\n\t].join(\" \");\n}\n\n/** True when a failed Firecrawl call should fall back to direct `undici` fetch instead of surfacing the error. */\nexport function isFallbackEligible(error: unknown): boolean {\n\tif (error instanceof FirecrawlError) return error.fallback;\n\tif (error instanceof WebfetchError) {\n\t\treturn error.code === \"timeout\" || error.code === \"transport\" || error.code === \"empty\";\n\t}\n\treturn false;\n}\n\nexport interface FirecrawlResponseMeta {\n\twarning?: string;\n\tcreditsUsed?: number;\n}\n\nexport interface FirecrawlBackend extends WebSearchBackend {\n\treadonly id: \"firecrawl\";\n\t/** `warning`/`creditsUsed` from the most recent search or scrape, for cost observability in tool details. */\n\tlastMeta: FirecrawlResponseMeta | undefined;\n}\n\nexport type FirecrawlPostFn = (\n\tpath: string,\n\tbody: Record<string, unknown>,\n\tinit: { headers: Record<string, string>; timeoutMs: number; signal?: AbortSignal },\n) => Promise<{ status: number; json: unknown }>;\n\nasync function defaultPost(\n\tpath: string,\n\tbody: Record<string, unknown>,\n\tinit: { headers: Record<string, string>; timeoutMs: number; signal?: AbortSignal },\n): Promise<{ status: number; json: unknown }> {\n\tconst timeoutSignal = AbortSignal.timeout(init.timeoutMs + FIRECRAWL_HTTP_HEADROOM_MS);\n\tconst signal = init.signal ? AbortSignal.any([init.signal, timeoutSignal]) : timeoutSignal;\n\tlet response: Awaited<ReturnType<typeof undiciRequest>>;\n\ttry {\n\t\tresponse = await undiciRequest(`${FIRECRAWL_BASE_URL}${path}`, {\n\t\t\tmethod: \"POST\",\n\t\t\theaders: { \"content-type\": \"application/json\", ...init.headers },\n\t\t\tbody: JSON.stringify(body),\n\t\t\tsignal,\n\t\t});\n\t} catch (error) {\n\t\tif (timeoutSignal.aborted && !init.signal?.aborted) {\n\t\t\tthrow new WebfetchError(`Firecrawl request to ${path} timed out`, \"timeout\");\n\t\t}\n\t\tif (init.signal?.aborted) {\n\t\t\tthrow new Error(\"Operation aborted\");\n\t\t}\n\t\tconst reason = error instanceof Error ? error.message : String(error);\n\t\tthrow new WebfetchError(`Firecrawl request to ${path} failed: ${reason}`, \"transport\");\n\t}\n\tlet text: string;\n\ttry {\n\t\ttext = await response.body.text();\n\t} catch (error) {\n\t\tconst reason = error instanceof Error ? error.message : String(error);\n\t\tthrow new WebfetchError(`Firecrawl request to ${path} failed: ${reason}`, \"transport\");\n\t}\n\tlet json: unknown;\n\ttry {\n\t\tjson = text ? (JSON.parse(text) as unknown) : undefined;\n\t} catch {\n\t\tthrow new WebfetchError(`Firecrawl request to ${path} returned invalid JSON`, \"transport\");\n\t}\n\treturn { status: response.statusCode, json };\n}\n\nexport interface FirecrawlBackendOptions {\n\tapiKey?: string;\n\ttimeoutMs?: number;\n\tpost?: FirecrawlPostFn;\n}\n\nfunction isRecord(value: unknown): value is Record<string, unknown> {\n\treturn typeof value === \"object\" && value !== null && !Array.isArray(value);\n}\n\nfunction asString(value: unknown): string | undefined {\n\treturn typeof value === \"string\" ? value : undefined;\n}\n\nfunction asNumber(value: unknown): number | undefined {\n\treturn typeof value === \"number\" && Number.isFinite(value) ? value : undefined;\n}\n\nfunction firecrawlErrorMessage(json: unknown): string | undefined {\n\tif (!isRecord(json)) return undefined;\n\tconst direct = asString(json.error);\n\tif (direct) return direct;\n\tif (isRecord(json.data)) {\n\t\tconst nested = asString(json.data.error);\n\t\tif (nested) return nested;\n\t}\n\treturn undefined;\n}\n\nfunction readMeta(json: unknown): FirecrawlResponseMeta | undefined {\n\tif (!isRecord(json)) return undefined;\n\tconst data = isRecord(json.data) ? json.data : undefined;\n\tconst warning = asString(json.warning) ?? (data ? asString(data.warning) : undefined);\n\tconst creditsUsed = asNumber(json.creditsUsed) ?? (data ? asNumber(data.creditsUsed) : undefined);\n\tif (warning === undefined && creditsUsed === undefined) return undefined;\n\treturn { warning, creditsUsed };\n}\n\nfunction normalizeSearchEntry(entry: unknown, source: \"web\" | \"images\" | \"news\"): WebSearchResult | undefined {\n\tif (!isRecord(entry)) return undefined;\n\tconst url = asString(entry.url);\n\tif (!url) return undefined;\n\tconst markdown = asString(entry.markdown);\n\tconst description = asString(entry.description);\n\tconst snippet =\n\t\tsource === \"news\" ? (asString(entry.snippet) ?? description ?? \"\") : description || markdown?.slice(0, 300) || \"\";\n\treturn {\n\t\ttitle: asString(entry.title) || url,\n\t\turl,\n\t\tsnippet,\n\t\tpublishedDate: asString(entry.publishedDate) ?? asString(entry.date),\n\t\tscore: asNumber(entry.score),\n\t\tsource,\n\t\t...(source === \"images\"\n\t\t\t? {\n\t\t\t\t\timageUrl: asString(entry.imageUrl) ?? asString(entry.image),\n\t\t\t\t\timageWidth: asNumber(entry.imageWidth),\n\t\t\t\t\timageHeight: asNumber(entry.imageHeight),\n\t\t\t\t}\n\t\t\t: {}),\n\t};\n}\n\n/**\n * Flatten Firecrawl's per-source buckets into one ordered list, each bucket\n * trimmed to its requested budget. Web hits keep their inline markdown as the\n * snippet; image hits point at the image and its source page.\n */\nfunction normalizeSearchResponse(json: unknown, budgets: Record<string, number>): WebSearchResult[] {\n\tif (!isRecord(json)) return [];\n\tconst data = json.data;\n\tconst results: WebSearchResult[] = [];\n\tfor (const source of [\"web\", \"images\", \"news\"] as const) {\n\t\tconst budget = budgets[source];\n\t\tif (budget === undefined) continue;\n\t\tconst bucket = isRecord(data) ? data[source] : undefined;\n\t\tconst entries = Array.isArray(bucket) ? bucket : source === \"web\" && Array.isArray(data) ? data : undefined;\n\t\tif (!entries) continue;\n\t\tlet taken = 0;\n\t\tfor (const entry of entries) {\n\t\t\tif (taken >= budget) break;\n\t\t\tconst normalized = normalizeSearchEntry(entry, source);\n\t\t\tif (!normalized) continue;\n\t\t\tresults.push(normalized);\n\t\t\ttaken++;\n\t\t}\n\t}\n\treturn results;\n}\n\nfunction normalizeScrapeResponse(url: string, json: unknown): WebDocument {\n\tconst data = isRecord(json) ? (isRecord(json.data) ? json.data : undefined) : undefined;\n\tconst markdown = (data ? asString(data.markdown) : undefined) ?? \"\";\n\tconst metadata = data && isRecord(data.metadata) ? data.metadata : undefined;\n\tconst title = (metadata ? asString(metadata.title) : undefined) ?? (data ? asString(data.title) : undefined) ?? url;\n\tif (!markdown.trim()) {\n\t\tthrow new FirecrawlError(`Firecrawl scrape of ${url} returned no usable text`, {\n\t\t\tcode: \"empty\",\n\t\t\tfallback: true,\n\t\t});\n\t}\n\treturn { url, title, markdown, fetchedAt: new Date().toISOString() };\n}\n\nexport function createFirecrawlBackend(options: FirecrawlBackendOptions = {}): FirecrawlBackend {\n\tconst timeoutMs = options.timeoutMs ?? WEBFETCH_REQUEST_TIMEOUT_MS;\n\tconst post = options.post ?? defaultPost;\n\tconst headers: Record<string, string> = {};\n\tif (options.apiKey) {\n\t\theaders.authorization = `Bearer ${options.apiKey}`;\n\t}\n\n\tasync function callApi(\n\t\tpath: string,\n\t\tbody: Record<string, unknown>,\n\t\tsignal?: AbortSignal,\n\t): Promise<{ status: number; json: unknown }> {\n\t\tlet lastError: unknown;\n\t\tfor (let attempt = 1; attempt <= FIRECRAWL_502_MAX_ATTEMPTS; attempt++) {\n\t\t\tif (signal?.aborted) {\n\t\t\t\tthrow new Error(\"Operation aborted\");\n\t\t\t}\n\t\t\ttry {\n\t\t\t\tconst response = await post(path, body, { headers, timeoutMs, signal });\n\t\t\t\tif (response.status === 502 && attempt < FIRECRAWL_502_MAX_ATTEMPTS) {\n\t\t\t\t\tlastError = new FirecrawlError(`Firecrawl request to ${path} failed with status 502`, {\n\t\t\t\t\t\tcode: \"transport\",\n\t\t\t\t\t\tstatus: 502,\n\t\t\t\t\t\tfallback: true,\n\t\t\t\t\t});\n\t\t\t\t\tcontinue;\n\t\t\t\t}\n\t\t\t\treturn response;\n\t\t\t} catch (error) {\n\t\t\t\tif (error instanceof FirecrawlError && error.status === 502 && attempt < FIRECRAWL_502_MAX_ATTEMPTS) {\n\t\t\t\t\tlastError = error;\n\t\t\t\t\tcontinue;\n\t\t\t\t}\n\t\t\t\tthrow error;\n\t\t\t}\n\t\t}\n\t\tthrow lastError;\n\t}\n\n\tfunction throwForStatus(path: string, status: number, json: unknown): never {\n\t\tconst detail = firecrawlErrorMessage(json);\n\t\t// Keyless 401/403/429 is provider-side (anonymous pool or blocked network),\n\t\t// not a transport blip: name the fix instead of the raw status.\n\t\tif (!options.apiKey && (status === 401 || status === 403 || status === 429)) {\n\t\t\tthrow new FirecrawlError(keylessUnavailableMessage(status, path), {\n\t\t\t\tcode: \"unavailable\",\n\t\t\t\tstatus,\n\t\t\t\tfallback: true,\n\t\t\t});\n\t\t}\n\t\tconst message = `Firecrawl request to ${path} failed with status ${status}${detail ? `: ${detail}` : \"\"}`;\n\t\tif (status === 401 || status === 403) {\n\t\t\tthrow new FirecrawlError(message, { code: \"transport\", status, fallback: true });\n\t\t}\n\t\tif (status === 402 || status === 429 || status >= 500) {\n\t\t\tthrow new FirecrawlError(message, { code: \"transport\", status, fallback: true });\n\t\t}\n\t\tthrow new FirecrawlError(message, { code: \"transport\", status, fallback: false });\n\t}\n\n\tconst backend: FirecrawlBackend = {\n\t\tid: \"firecrawl\",\n\t\tlastMeta: undefined,\n\t\tasync search(\n\t\t\tintent: ResolvedSearchIntent,\n\t\t\tsearchOptions: { limit: number; signal?: AbortSignal },\n\t\t): Promise<WebSearchResult[]> {\n\t\t\tif (!intent.query) {\n\t\t\t\tthrow new Error(\"Search query must not be empty\");\n\t\t\t}\n\t\t\t// Per-modality limits: sum the requested counts, then slice each bucket\n\t\t\t// back to its own budget so one modality cannot starve another.\n\t\t\tconst sources: Array<\"web\" | \"images\" | \"news\"> = [];\n\t\t\tif (intent.results.web !== undefined) sources.push(\"web\");\n\t\t\tif (intent.results.images !== undefined) sources.push(\"images\");\n\t\t\tif (intent.results.news !== undefined) sources.push(\"news\");\n\t\t\tconst budgets: Record<string, number> = {};\n\t\t\tlet total = 0;\n\t\t\tfor (const source of sources) {\n\t\t\t\tconst count = clampLimit(intent.results[source] ?? 0, {\n\t\t\t\t\tfallback: 1,\n\t\t\t\t\tmin: 1,\n\t\t\t\t\tmax: WEBFETCH_FIRECRAWL_MAX_LIMIT,\n\t\t\t\t});\n\t\t\t\tbudgets[source] = count;\n\t\t\t\ttotal += count;\n\t\t\t}\n\t\t\ttotal = clampLimit(total, { fallback: 10, min: 1, max: WEBFETCH_FIRECRAWL_MAX_LIMIT });\n\n\t\t\tconst body: Record<string, unknown> = {\n\t\t\t\tquery: intent.query,\n\t\t\t\tlimit: total,\n\t\t\t\tsources,\n\t\t\t\thighlights: true,\n\t\t\t\ttimeout: timeoutMs,\n\t\t\t};\n\t\t\tif (intent.filters.domains) {\n\t\t\t\t// Firecrawl treats includeDomains/excludeDomains as mutually exclusive;\n\t\t\t\t// a request for both is narrowed to the include list.\n\t\t\t\tbody.includeDomains = intent.filters.domains;\n\t\t\t}\n\t\t\tif (intent.filters.recencyMs !== undefined) {\n\t\t\t\tbody.tbs = `qdr:d${Math.max(1, Math.round(intent.filters.recencyMs / (24 * 60 * 60 * 1000)))}`;\n\t\t\t}\n\t\t\tif (intent.filters.language) {\n\t\t\t\tbody.country = intent.filters.language;\n\t\t\t}\n\t\t\t// Page text is only useful for web hits; image and news hits carry their\n\t\t\t// own metadata and are cheaper without a scrape.\n\t\t\tif (intent.results.web !== undefined) {\n\t\t\t\tbody.scrapeOptions = { formats: [\"markdown\"], onlyMainContent: true };\n\t\t\t}\n\n\t\t\tconst response = await callApi(\"/v2/search\", body, searchOptions.signal);\n\t\t\tif (response.status !== 200) {\n\t\t\t\tthrowForStatus(\"/v2/search\", response.status, response.json);\n\t\t\t}\n\t\t\tif (isRecord(response.json) && response.json.success === false) {\n\t\t\t\tthrow new FirecrawlError(firecrawlErrorMessage(response.json) ?? \"Firecrawl search failed\", {\n\t\t\t\t\tcode: \"transport\",\n\t\t\t\t\tstatus: response.status,\n\t\t\t\t\tfallback: false,\n\t\t\t\t});\n\t\t\t}\n\t\t\tbackend.lastMeta = readMeta(response.json);\n\t\t\treturn normalizeSearchResponse(response.json, budgets);\n\t\t},\n\t\tasync fetch(url: string, fetchOptions: { signal?: AbortSignal }): Promise<WebDocument> {\n\t\t\tconst response = await callApi(\n\t\t\t\t\"/v2/scrape\",\n\t\t\t\t{ url, formats: [\"markdown\"], onlyMainContent: true, timeout: timeoutMs },\n\t\t\t\tfetchOptions.signal,\n\t\t\t);\n\t\t\tif (response.status !== 200) {\n\t\t\t\tthrowForStatus(\"/v2/scrape\", response.status, response.json);\n\t\t\t}\n\t\t\tif (isRecord(response.json) && response.json.success === false) {\n\t\t\t\tthrow new FirecrawlError(firecrawlErrorMessage(response.json) ?? `Firecrawl scrape of ${url} failed`, {\n\t\t\t\t\tcode: \"transport\",\n\t\t\t\t\tstatus: response.status,\n\t\t\t\t\tfallback: false,\n\t\t\t\t});\n\t\t\t}\n\t\t\tbackend.lastMeta = readMeta(response.json);\n\t\t\treturn normalizeScrapeResponse(url, response.json);\n\t\t},\n\t};\n\treturn backend;\n}\n"]}