@spinabot/brigade 0.1.2 → 1.0.1

package/dist/agents/extensions/modules/perplexity.js

@@ -0,0 +1,358 @@
+/**
+ * Perplexity web-search provider — structured search results.
+ *
+ * Two transports exist in Perplexity's ecosystem: the structured Search API
+ * (`/search`) and the Sonar chat-completions API (`/chat/completions` with
+ * built-in citations). Brigade ships the Search API for v1 because it
+ * returns clean URL hits without an extra "extract synthesized answer"
+ * step. The Sonar path is a future bolt-on.
+ *
+ * Endpoint: `https://api.perplexity.ai/search`. Auth: `Authorization: Bearer`.
+ *
+ * Operator config (`tools.web.search.providers.perplexity`):
+ *   { apiKey?, country?, searchRecencyFilter?, searchDomainFilter?[] }
+ */
+import { defineModule } from "../types.js";
+import { DEFAULT_TIMEOUT_SECONDS, readResponseText } from "../../tools/web-shared.js";
+import { readProviderConfigSlot, resolveProviderApiKey, resolveSiteName, wrapSearchHit, mergeSignals, } from "./web-provider-helpers.js";
+import { normalizeFreshness, parseIsoDateRange, WEB_DOCS_URL, } from "./web-search-filters.js";
+// re-import to keep helper visibility in runSonarChat below the top-level
+// import block (some bundlers need this when the function is declared at
+// module scope).
+void resolveSiteName;
+const PERPLEXITY_SEARCH_ENDPOINT = "https://api.perplexity.ai/search";
+const PERPLEXITY_CHAT_ENDPOINT = "https://api.perplexity.ai/chat/completions";
+function isValidIsoDate(raw) {
+    if (!raw)
+        return false;
+    return /^\d{4}-\d{2}-\d{2}$/.test(raw) && Number.isFinite(Date.parse(`${raw}T00:00:00Z`));
+}
+function createPerplexitySearchProvider() {
+    return {
+        id: "perplexity",
+        label: "Perplexity",
+        hint: "Perplexity Search API — research-grade ranked URL hits.",
+        requiresCredential: true,
+        envVars: ["PERPLEXITY_API_KEY"],
+        signupUrl: "https://www.perplexity.ai/settings/api",
+        docsUrl: "https://docs.perplexity.ai/api-reference/search-post",
+        placeholder: "pplx-…",
+        autoDetectOrder: 45,
+        supportsFilters: true,
+        isConfigured(cfg, env) {
+            return (resolveProviderApiKey({
+                cfg,
+                env,
+                providerId: "perplexity",
+                kind: "search",
+                envVars: ["PERPLEXITY_API_KEY"],
+            }) !== undefined);
+        },
+        createTool(ctx) {
+            const apiKey = resolveProviderApiKey({
+                cfg: ctx.config,
+                env: ctx.env,
+                providerId: "perplexity",
+                kind: "search",
+                envVars: ["PERPLEXITY_API_KEY"],
+            });
+            if (!apiKey)
+                return null;
+            const cfgSlot = readProviderConfigSlot({
+                cfg: ctx.config,
+                providerId: "perplexity",
+                kind: "search",
+            });
+            const timeoutMs = (ctx.runtime?.timeoutMs ?? DEFAULT_TIMEOUT_SECONDS * 1_000) | 0;
+            return {
+                description: "Perplexity Search — research-mode ranked results with date metadata. Supports country, language, recency (day/week/month/year), and ISO date ranges.",
+                parameters: {
+                    type: "object",
+                    properties: {
+                        query: { type: "string" },
+                        count: { type: "integer", minimum: 1, maximum: 10 },
+                        country: {
+                            type: "string",
+                            description: "2-letter country code (e.g. 'US', 'DE').",
+                        },
+                        language: {
+                            type: "string",
+                            description: "ISO 639-1 language code (e.g., 'en', 'de').",
+                        },
+                        freshness: {
+                            type: "string",
+                            description: "Recency: 'day' / 'week' / 'month' / 'year'.",
+                        },
+                        date_after: {
+                            type: "string",
+                            description: "Only results on or after this date (YYYY-MM-DD).",
+                        },
+                        date_before: {
+                            type: "string",
+                            description: "Only results on or before this date (YYYY-MM-DD).",
+                        },
+                    },
+                    required: ["query"],
+                },
+                async execute(args, signal) {
+                    const a = (args ?? {});
+                    const readStr = (v) => typeof v === "string" && v.trim().length > 0 ? v.trim() : undefined;
+                    const query = String(a.query ?? "").trim();
+                    if (!query)
+                        throw new Error("perplexity: missing query");
+                    const max_results = Math.min(Math.max(Number(a.count ?? 10) | 0, 1), 10);
+                    const argCountry = readStr(a.country);
+                    const argFreshnessRaw = readStr(a.freshness);
+                    const argDateAfter = readStr(a.date_after);
+                    const argDateBefore = readStr(a.date_before);
+                    const argLanguage = readStr(a.language);
+                    let perCallFreshness;
+                    if (argFreshnessRaw) {
+                        perCallFreshness = normalizeFreshness(argFreshnessRaw, "perplexity");
+                        if (!perCallFreshness) {
+                            return {
+                                provider: "perplexity",
+                                error: "invalid_freshness",
+                                message: `Invalid freshness \"${argFreshnessRaw}\". Use day, week, month, or year.`,
+                                docs: WEB_DOCS_URL,
+                            };
+                        }
+                    }
+                    let perCallAfter;
+                    let perCallBefore;
+                    if (argDateAfter || argDateBefore) {
+                        const range = parseIsoDateRange({
+                            rawDateAfter: argDateAfter,
+                            rawDateBefore: argDateBefore,
+                            invalidDateAfterMessage: `Invalid date_after \"${argDateAfter}\". Use YYYY-MM-DD.`,
+                            invalidDateBeforeMessage: `Invalid date_before \"${argDateBefore}\". Use YYYY-MM-DD.`,
+                            invalidDateRangeMessage: "date_after must be on or before date_before.",
+                            docs: WEB_DOCS_URL,
+                        });
+                        if ("error" in range)
+                            return { provider: "perplexity", ...range };
+                        perCallAfter = range.dateAfter;
+                        perCallBefore = range.dateBefore;
+                    }
+                    const transport = cfgSlot.transport === "sonar" ? "sonar" : "search";
+                    if (transport === "sonar") {
+                        return await runSonarChat({
+                            query,
+                            maxResults: max_results,
+                            apiKey,
+                            cfgSlot,
+                            timeoutMs,
+                            signal,
+                        });
+                    }
+                    const body = { query, max_results };
+                    const effCountry = argCountry ?? cfgSlot.country;
+                    if (effCountry)
+                        body.country = effCountry;
+                    const effRecency = perCallFreshness ?? cfgSlot.searchRecencyFilter;
+                    if (effRecency)
+                        body.search_recency_filter = effRecency;
+                    if (cfgSlot.searchDomainFilter?.length) {
+                        body.search_domain_filter = cfgSlot.searchDomainFilter.slice(0, 20);
+                    }
+                    const langs = [];
+                    if (argLanguage && /^[a-z]{2}$/i.test(argLanguage))
+                        langs.push(argLanguage.toLowerCase());
+                    if (cfgSlot.searchLanguageFilter?.length) {
+                        for (const l of cfgSlot.searchLanguageFilter) {
+                            if (/^[a-z]{2}$/i.test(l)) {
+                                const lower = l.toLowerCase();
+                                if (!langs.includes(lower))
+                                    langs.push(lower);
+                            }
+                        }
+                    }
+                    if (langs.length)
+                        body.search_language_filter = langs;
+                    const effAfter = perCallAfter ?? cfgSlot.searchAfterDate;
+                    const effBefore = perCallBefore ?? cfgSlot.searchBeforeDate;
+                    if (effAfter && isValidIsoDate(effAfter))
+                        body.search_after_date = effAfter;
+                    if (effBefore && isValidIsoDate(effBefore))
+                        body.search_before_date = effBefore;
+                    if (typeof cfgSlot.maxTokens === "number" && cfgSlot.maxTokens > 0) {
+                        body.max_tokens = cfgSlot.maxTokens | 0;
+                    }
+                    if (typeof cfgSlot.maxTokensPerPage === "number" && cfgSlot.maxTokensPerPage > 0) {
+                        body.max_tokens_per_page = cfgSlot.maxTokensPerPage | 0;
+                    }
+                    const controller = new AbortController();
+                    const timer = setTimeout(() => controller.abort(new Error("timeout")), timeoutMs);
+                    timer.unref?.();
+                    const combined = mergeSignals([signal, controller.signal]);
+                    try {
+                        const response = await fetch(PERPLEXITY_SEARCH_ENDPOINT, {
+                            method: "POST",
+                            headers: {
+                                "content-type": "application/json",
+                                authorization: `Bearer ${apiKey}`,
+                                // Telemetry hints — Perplexity uses these to bucket
+                                // usage for OpenRouter-routed flows + ranking.
+                                "http-referer": "https://github.com/spinabot/brigade",
+                                "x-title": "Brigade",
+                            },
+                            body: JSON.stringify(body),
+                            signal: combined,
+                        });
+                        const { text: rawBody } = await readResponseText(response.body, 2_000_000);
+                        if (response.status !== 200) {
+                            const safe = rawBody.replace(/[\x00-\x1f\x7f]/g, " ").slice(0, 200);
+                            throw new Error(`perplexity: HTTP ${response.status} — ${safe}`);
+                        }
+                        const data = (() => {
+                            try {
+                                return JSON.parse(rawBody);
+                            }
+                            catch {
+                                throw new Error("perplexity: invalid JSON from upstream");
+                            }
+                        })();
+                        const rawHits = Array.isArray(data.results) ? data.results : [];
+                        const results = rawHits
+                            .map((h) => {
+                            const title = typeof h.title === "string" ? h.title.trim() : "";
+                            const url = typeof h.url === "string" ? h.url.trim() : "";
+                            if (!title || !url)
+                                return null;
+                            return wrapSearchHit({
+                                title,
+                                url,
+                                snippet: typeof h.snippet === "string" ? h.snippet.trim() : undefined,
+                                siteName: resolveSiteName(url),
+                                published: typeof h.date === "string" ? h.date : undefined,
+                            });
+                        })
+                            .filter((r) => r !== null);
+                        return { provider: "perplexity", results };
+                    }
+                    finally {
+                        clearTimeout(timer);
+                    }
+                },
+            };
+        },
+    };
+}
+/**
+ * Run a Perplexity Sonar chat completion. Treats the question as a single
+ * user turn and asks the model to answer with citations. Returns the
+ * answer (envelope-wrapped) plus a flattened `citations[]` derived from
+ * BOTH the top-level `citations` array AND `choices[].message.annotations`
+ * (Perplexity emits citations in both spots depending on model version).
+ */
+async function runSonarChat(params) {
+    const { query, maxResults, apiKey, cfgSlot, timeoutMs } = params;
+    const model = cfgSlot.sonarModel?.trim() || "sonar";
+    const body = {
+        model,
+        messages: [
+            {
+                role: "system",
+                content: "You are a research assistant. Answer the user's question concisely, citing each claim with the source URL. Return only the answer text.",
+            },
+            { role: "user", content: query },
+        ],
+    };
+    if (cfgSlot.searchRecencyFilter)
+        body.search_recency_filter = cfgSlot.searchRecencyFilter;
+    if (cfgSlot.searchDomainFilter?.length) {
+        body.search_domain_filter = cfgSlot.searchDomainFilter.slice(0, 20);
+    }
+    if (cfgSlot.country)
+        body.country = cfgSlot.country;
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(new Error("timeout")), timeoutMs);
+    timer.unref?.();
+    const combined = mergeSignals([params.signal, controller.signal]);
+    try {
+        const response = await fetch(PERPLEXITY_CHAT_ENDPOINT, {
+            method: "POST",
+            headers: {
+                "content-type": "application/json",
+                authorization: `Bearer ${apiKey}`,
+                "http-referer": "https://github.com/spinabot/brigade",
+                "x-title": "Brigade",
+            },
+            body: JSON.stringify(body),
+            signal: combined,
+        });
+        const { text: rawBody } = await readResponseText(response.body, 2_000_000);
+        if (response.status !== 200) {
+            const safe = rawBody.replace(/[\x00-\x1f\x7f]/g, " ").slice(0, 200);
+            throw new Error(`perplexity sonar: HTTP ${response.status} — ${safe}`);
+        }
+        const data = (() => {
+            try {
+                return JSON.parse(rawBody);
+            }
+            catch {
+                throw new Error("perplexity sonar: invalid JSON from upstream");
+            }
+        })();
+        const choices = Array.isArray(data.choices) ? data.choices : [];
+        const message = choices[0]?.message;
+        const answerText = typeof message?.content === "string" ? message.content.trim() : "";
+        // Citations come from EITHER the top-level `citations[]` (Perplexity
+        // classic shape) OR `choices[0].message.annotations[]` with type
+        // `url_citation`. Merge both, dedupe by URL, cap at maxResults.
+        const citations = new Set();
+        const topCites = Array.isArray(data.citations) ? data.citations : [];
+        for (const c of topCites) {
+            if (typeof c === "string" && c.trim())
+                citations.add(c.trim());
+        }
+        const annotations = Array.isArray(message?.annotations)
+            ? message.annotations
+            : [];
+        for (const ann of annotations) {
+            if (ann?.type === "url_citation") {
+                const inner = ann.url_citation;
+                const candidate = typeof ann.url === "string"
+                    ? ann.url
+                    : typeof inner?.url === "string"
+                        ? inner.url
+                        : "";
+                if (candidate)
+                    citations.add(candidate);
+            }
+        }
+        const citationList = Array.from(citations).slice(0, maxResults);
+        // Sonar doesn't return per-hit titles; surface the citation URLs as
+        // minimal result rows so the schema matches the search transport.
+        // Title falls back to hostname; snippet wraps the URL itself.
+        const results = citationList
+            .map((u) => {
+            try {
+                const host = new URL(u).hostname;
+                return wrapSearchHit({ title: host, url: u, siteName: host });
+            }
+            catch {
+                return null;
+            }
+        })
+            .filter((h) => h !== null);
+        return {
+            provider: "perplexity",
+            mode: "sonar",
+            results,
+            answer: answerText, // gets wrapped downstream by web-search.ts normalizer
+            citations: citationList,
+        };
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
+export const perplexityModule = defineModule({
+    id: "perplexity",
+    register(b) {
+        b.webSearch(createPerplexitySearchProvider());
+    },
+});
+export { createPerplexitySearchProvider };
+//# sourceMappingURL=perplexity.js.map

package/dist/agents/extensions/modules/perplexity.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"perplexity.js","sourceRoot":"","sources":["../../../../src/agents/extensions/modules/perplexity.ts"],"names":[],"mappings":"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"}

package/dist/agents/extensions/modules/searxng.d.ts

@@ -0,0 +1,43 @@
+/**
+ * SearXNG web-search provider — keyless, self-hosted metasearch.
+ *
+ * SearXNG aggregates dozens of search engines on a single instance the
+ * operator runs themselves. Brigade pings the configured `baseUrl/search`
+ * with `format=json`. No API key needed — the credential here is the URL.
+ *
+ * Why ship a self-hosted option: when all paid providers are quota-exhausted
+ * or down, a private SearXNG instance keeps `web_search` working. Privacy-
+ * conscious operators also prefer it.
+ *
+ * Operator config (`tools.web.search.providers.searxng`):
+ *   { baseUrl?, categories?, language? }
+ *
+ * baseUrl defaults to env `SEARXNG_BASE_URL` if config-side is unset.
+ *
+ * SSRF posture: an http:// baseUrl must point at a private/loopback host —
+ * `assertHttpUrlTargetsPrivateNetwork` is checked at runtime. https:// is
+ * allowed for any host (operator's responsibility).
+ */
+import type { WebSearchProvider } from "../types.js";
+interface SearxngConfig {
+    baseUrl?: string;
+    categories?: string;
+    language?: string;
+}
+declare function resolveSearxngBaseUrl(cfgSlot: Partial<SearxngConfig>, env?: NodeJS.ProcessEnv): string | undefined;
+/**
+ * Validate the configured base URL — refuse non-http(s), refuse plain `http://`
+ * pointed at a public host (would be unencrypted credentials over the open
+ * net), allow private/loopback for http://, allow any host for https://.
+ */
+declare function validateSearxngBaseUrl(baseUrl: string): void;
+declare function buildSearxngUrl(args: {
+    baseUrl: string;
+    query: string;
+    categories?: string;
+    language?: string;
+}): string;
+declare function createSearxngSearchProvider(): WebSearchProvider;
+export declare const searxngModule: import("../types.js").BrigadeModule;
+export { buildSearxngUrl, createSearxngSearchProvider, resolveSearxngBaseUrl, validateSearxngBaseUrl };
+//# sourceMappingURL=searxng.d.ts.map

package/dist/agents/extensions/modules/searxng.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"searxng.d.ts","sourceRoot":"","sources":["../../../../src/agents/extensions/modules/searxng.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAGH,OAAO,KAAK,EAIX,iBAAiB,EACjB,MAAM,aAAa,CAAC;AAUrB,UAAU,aAAa;IACtB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,iBAAS,qBAAqB,CAAC,OAAO,EAAE,OAAO,CAAC,aAAa,CAAC,EAAE,GAAG,CAAC,EAAE,MAAM,CAAC,UAAU,GAAG,MAAM,GAAG,SAAS,CAK3G;AAED;;;;GAIG;AACH,iBAAS,sBAAsB,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAqBrD;AAED,iBAAS,eAAe,CAAC,IAAI,EAAE;IAC9B,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,EAAE,MAAM,CAAC;IACd,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,EAAE,MAAM,CAAC;CAClB,GAAG,MAAM,CAUT;AAYD,iBAAS,2BAA2B,IAAI,iBAAiB,CA8GxD;AAED,eAAO,MAAM,aAAa,qCAKxB,CAAC;AAEH,OAAO,EAAE,eAAe,EAAE,2BAA2B,EAAE,qBAAqB,EAAE,sBAAsB,EAAE,CAAC"}

package/dist/agents/extensions/modules/searxng.js

@@ -0,0 +1,191 @@
+/**
+ * SearXNG web-search provider — keyless, self-hosted metasearch.
+ *
+ * SearXNG aggregates dozens of search engines on a single instance the
+ * operator runs themselves. Brigade pings the configured `baseUrl/search`
+ * with `format=json`. No API key needed — the credential here is the URL.
+ *
+ * Why ship a self-hosted option: when all paid providers are quota-exhausted
+ * or down, a private SearXNG instance keeps `web_search` working. Privacy-
+ * conscious operators also prefer it.
+ *
+ * Operator config (`tools.web.search.providers.searxng`):
+ *   { baseUrl?, categories?, language? }
+ *
+ * baseUrl defaults to env `SEARXNG_BASE_URL` if config-side is unset.
+ *
+ * SSRF posture: an http:// baseUrl must point at a private/loopback host —
+ * `assertHttpUrlTargetsPrivateNetwork` is checked at runtime. https:// is
+ * allowed for any host (operator's responsibility).
+ */
+import { defineModule } from "../types.js";
+import { classifyHostnameSync } from "../../../infra/net/fetch-guard.js";
+import { DEFAULT_TIMEOUT_SECONDS, readResponseText } from "../../tools/web-shared.js";
+import { readProviderConfigSlot, resolveSiteName, wrapSearchHit, mergeSignals, } from "./web-provider-helpers.js";
+function resolveSearxngBaseUrl(cfgSlot, env) {
+    const cfg = cfgSlot.baseUrl?.trim();
+    if (cfg)
+        return cfg.replace(/\/$/, "");
+    const envValue = env?.SEARXNG_BASE_URL?.trim();
+    return envValue ? envValue.replace(/\/$/, "") : undefined;
+}
+/**
+ * Validate the configured base URL — refuse non-http(s), refuse plain `http://`
+ * pointed at a public host (would be unencrypted credentials over the open
+ * net), allow private/loopback for http://, allow any host for https://.
+ */
+function validateSearxngBaseUrl(baseUrl) {
+    let parsed;
+    try {
+        parsed = new URL(baseUrl);
+    }
+    catch {
+        throw new Error("SearXNG base URL must be a valid http(s) URL.");
+    }
+    if (parsed.protocol !== "http:" && parsed.protocol !== "https:") {
+        throw new Error("SearXNG base URL must use http:// or https://.");
+    }
+    if (parsed.protocol === "http:") {
+        const reason = classifyHostnameSync(parsed.hostname);
+        // `classifyHostnameSync` returns a string when the host is on the
+        // SSRF refuse-list. For SearXNG specifically that's GOOD — http://
+        // targeting a private host is exactly the safe configuration.
+        if (!reason) {
+            throw new Error("SearXNG plain-http base URL must point at a private / loopback host. Use https:// for public instances.");
+        }
+    }
+}
+function buildSearxngUrl(args) {
+    const url = new URL(args.baseUrl);
+    const pathname = url.pathname.endsWith("/") ? `${url.pathname}search` : `${url.pathname}/search`;
+    url.pathname = pathname;
+    url.search = "";
+    url.searchParams.set("q", args.query);
+    url.searchParams.set("format", "json");
+    if (args.categories)
+        url.searchParams.set("categories", args.categories);
+    if (args.language)
+        url.searchParams.set("language", args.language);
+    return url.toString();
+}
+function createSearxngSearchProvider() {
+    return {
+        id: "searxng",
+        label: "SearXNG",
+        hint: "Self-hosted metasearch. Operator provides the instance URL.",
+        // requiresCredential: true — the "credential" is the URL, not a key.
+        requiresCredential: true,
+        envVars: ["SEARXNG_BASE_URL"],
+        signupUrl: "https://docs.searxng.org/admin/installation.html",
+        docsUrl: "https://docs.searxng.org/",
+        placeholder: "http://localhost:8888",
+        // Lowest priority — picked only when nothing better is configured.
+        // (Equal to DuckDuckGo at 200; DDG ships keyless so it usually wins.)
+        autoDetectOrder: 180,
+        isConfigured(cfg, env) {
+            const cfgSlot = readProviderConfigSlot({
+                cfg,
+                providerId: "searxng",
+                kind: "search",
+            });
+            return resolveSearxngBaseUrl(cfgSlot, env) !== undefined;
+        },
+        createTool(ctx) {
+            const cfgSlot = readProviderConfigSlot({
+                cfg: ctx.config,
+                providerId: "searxng",
+                kind: "search",
+            });
+            const baseUrl = resolveSearxngBaseUrl(cfgSlot, ctx.env);
+            if (!baseUrl)
+                return null;
+            try {
+                validateSearxngBaseUrl(baseUrl);
+            }
+            catch {
+                // Operator misconfiguration — surface as a tool error at execute
+                // time, not at registration (so the error includes the URL the
+                // model attempted to use).
+            }
+            const timeoutMs = (ctx.runtime?.timeoutMs ?? DEFAULT_TIMEOUT_SECONDS * 1_000) | 0;
+            return {
+                description: "SearXNG self-hosted metasearch — keyless, privacy-first.",
+                parameters: {
+                    type: "object",
+                    properties: {
+                        query: { type: "string" },
+                        count: { type: "integer", minimum: 1, maximum: 25 },
+                    },
+                    required: ["query"],
+                },
+                async execute(args, signal) {
+                    validateSearxngBaseUrl(baseUrl);
+                    const query = String(args.query ?? "").trim();
+                    if (!query)
+                        throw new Error("searxng: missing query");
+                    const count = Math.min(Math.max(Number(args.count ?? 10) | 0, 1), 25);
+                    const url = buildSearxngUrl({
+                        baseUrl,
+                        query,
+                        categories: cfgSlot.categories,
+                        language: cfgSlot.language,
+                    });
+                    const controller = new AbortController();
+                    const timer = setTimeout(() => controller.abort(new Error("timeout")), timeoutMs);
+                    timer.unref?.();
+                    const combined = mergeSignals([signal, controller.signal]);
+                    try {
+                        const response = await fetch(url, {
+                            method: "GET",
+                            headers: { accept: "application/json" },
+                            signal: combined,
+                        });
+                        const { text: body, truncated } = await readResponseText(response.body, 1_000_000);
+                        if (truncated)
+                            throw new Error("searxng: response too large");
+                        if (response.status !== 200) {
+                            const safe = body.replace(/[\x00-\x1f\x7f]/g, " ").slice(0, 200);
+                            throw new Error(`searxng: HTTP ${response.status} — ${safe}`);
+                        }
+                        const data = (() => {
+                            try {
+                                return JSON.parse(body);
+                            }
+                            catch {
+                                throw new Error("searxng: invalid JSON from upstream");
+                            }
+                        })();
+                        const rawHits = Array.isArray(data.results) ? data.results : [];
+                        const results = rawHits
+                            .slice(0, count)
+                            .map((h) => {
+                            const title = typeof h.title === "string" ? h.title.trim() : "";
+                            const u = typeof h.url === "string" ? h.url.trim() : "";
+                            if (!title || !u)
+                                return null;
+                            return wrapSearchHit({
+                                title,
+                                url: u,
+                                snippet: typeof h.content === "string" ? h.content.trim() : undefined,
+                                siteName: resolveSiteName(u),
+                            });
+                        })
+                            .filter((r) => r !== null);
+                        return { provider: "searxng", results };
+                    }
+                    finally {
+                        clearTimeout(timer);
+                    }
+                },
+            };
+        },
+    };
+}
+export const searxngModule = defineModule({
+    id: "searxng",
+    register(b) {
+        b.webSearch(createSearxngSearchProvider());
+    },
+});
+export { buildSearxngUrl, createSearxngSearchProvider, resolveSearxngBaseUrl, validateSearxngBaseUrl };
+//# sourceMappingURL=searxng.js.map

package/dist/agents/extensions/modules/searxng.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"searxng.js","sourceRoot":"","sources":["../../../../src/agents/extensions/modules/searxng.ts"],"names":[],"mappings":"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"}