@aria-cli/tools 1.0.0

package/dist-cjs/policy.js

@@ -0,0 +1,156 @@
+"use strict";
+/**
+ * Tool Policy Engine
+ *
+ * Evaluates whether a tool is allowed based on allow/deny lists with group expansion.
+ * Supports layered policy merging (intersection semantics) for arion + RunOptions policies.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TOOL_GROUPS = void 0;
+exports.expandGroups = expandGroups;
+exports.isToolAllowed = isToolAllowed;
+exports.mergePolicies = mergePolicies;
+/** Built-in tool groups */
+exports.TOOL_GROUPS = {
+    "group:memory": [
+        "remember",
+        "recall",
+        "forget",
+        "recall_knowledge",
+        "reflect",
+        "search",
+        "learn",
+        "session_history",
+    ],
+    "group:web": ["web_search", "web_fetch", "browse", "browser"],
+    "group:filesystem": ["read_file", "write_file", "edit_file", "glob", "grep", "ls", "apply_patch"],
+    "group:shell": [
+        "bash",
+        "exec",
+        "spawn",
+        "kill",
+        "list_processes",
+        "wait_process",
+        "write_stdin",
+        "process",
+    ],
+    "group:arion": [
+        "hatch_arion",
+        "wake_arion",
+        "rest_arion",
+        "retire_arion",
+        "delegate_arion",
+        "manage_network",
+        "list_clients",
+        "deploy",
+    ],
+    "group:meta": [
+        "ask_user",
+        "quest_update",
+        "quest_list",
+        "search",
+        "learn",
+        "learn_tool",
+        "learn_skill",
+        "create_tool",
+        "create_skill",
+        "use_skill",
+        "restart",
+        "spawn_worker",
+        "check_delegation",
+        "pause_delegation",
+        "resume_delegation",
+        "quest_report",
+        "self_diagnose",
+    ],
+};
+/**
+ * Expand group references in a policy list.
+ * "group:memory" → ["remember", "recall", "forget", "reflect"]
+ * Individual tool names pass through unchanged.
+ * Unknown group names are ignored (treated as empty).
+ */
+function expandGroups(names) {
+    const result = new Set();
+    for (const name of names) {
+        const lower = name.toLowerCase();
+        if (lower.startsWith("group:")) {
+            const members = exports.TOOL_GROUPS[lower];
+            if (members) {
+                for (const member of members) {
+                    result.add(member.toLowerCase());
+                }
+            }
+            // Unknown group names are silently ignored
+        }
+        else {
+            result.add(lower);
+        }
+    }
+    return result;
+}
+/**
+ * Evaluate whether a tool is allowed by a policy.
+ * Rules:
+ * 1. If allow is empty/undefined and restrictAllow is false/undefined
+ *    → all tools allowed (then check deny)
+ * 2. If allow is non-empty OR restrictAllow=true
+ *    → only listed tools/groups allowed (empty allow + restrictAllow=true denies all)
+ * 3. Deny always wins over allow
+ */
+function isToolAllowed(toolName, policy) {
+    const normalized = toolName.toLowerCase();
+    // Check allow list: when restricted, tool must be in allowed set.
+    const isAllowRestricted = policy.restrictAllow === true || (policy.allow !== undefined && policy.allow.length > 0);
+    if (isAllowRestricted) {
+        const allowed = expandGroups(policy.allow ?? []);
+        if (!allowed.has(normalized)) {
+            return false;
+        }
+    }
+    // Check deny list: deny always wins
+    if (policy.deny && policy.deny.length > 0) {
+        const denied = expandGroups(policy.deny);
+        if (denied.has(normalized)) {
+            return false;
+        }
+    }
+    return true;
+}
+/**
+ * Merge two policies (intersection). Used for layered evaluation:
+ * arion policy ∩ RunOptions policy = effective policy.
+ * A tool must be allowed by BOTH layers.
+ */
+function mergePolicies(a, b) {
+    // Merge deny: union of both deny lists
+    const mergedDeny = [...(a.deny ?? []), ...(b.deny ?? [])];
+    // Merge allow with restriction semantics:
+    // - both restricted: intersection (possibly empty = deny all)
+    // - one restricted: inherit that restriction
+    // - neither restricted: unrestricted
+    const aRestricts = a.restrictAllow === true || (a.allow?.length ?? 0) > 0;
+    const bRestricts = b.restrictAllow === true || (b.allow?.length ?? 0) > 0;
+    let mergedAllow;
+    let mergedRestrictAllow = false;
+    if (aRestricts && bRestricts) {
+        const expandedA = expandGroups(a.allow ?? []);
+        const expandedB = expandGroups(b.allow ?? []);
+        mergedAllow = [...expandedA].filter((name) => expandedB.has(name));
+        mergedRestrictAllow = true;
+    }
+    else if (aRestricts) {
+        mergedAllow = [...(a.allow ?? [])];
+        mergedRestrictAllow = true;
+    }
+    else if (bRestricts) {
+        mergedAllow = [...(b.allow ?? [])];
+        mergedRestrictAllow = true;
+    }
+    return {
+        ...(mergedAllow !== undefined ? { allow: mergedAllow } : {}),
+        ...(mergedRestrictAllow ? { restrictAllow: true } : {}),
+        ...(mergedDeny.length ? { deny: mergedDeny } : {}),
+    };
+}
+//# sourceMappingURL=policy.js.map

package/dist-cjs/policy.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"policy.js","sourceRoot":"","sources":["../src/policy.ts"],"names":[],"mappings":";AAAA;;;;;GAKG;;;AA4EH,oCAiBC;AAWD,sCAsBC;AAOD,sCAgCC;AAtJD,2BAA2B;AACd,QAAA,WAAW,GAA6B;IACnD,cAAc,EAAE;QACd,UAAU;QACV,QAAQ;QACR,QAAQ;QACR,kBAAkB;QAClB,SAAS;QACT,QAAQ;QACR,OAAO;QACP,iBAAiB;KAClB;IACD,WAAW,EAAE,CAAC,YAAY,EAAE,WAAW,EAAE,QAAQ,EAAE,SAAS,CAAC;IAC7D,kBAAkB,EAAE,CAAC,WAAW,EAAE,YAAY,EAAE,WAAW,EAAE,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,aAAa,CAAC;IACjG,aAAa,EAAE;QACb,MAAM;QACN,MAAM;QACN,OAAO;QACP,MAAM;QACN,gBAAgB;QAChB,cAAc;QACd,aAAa;QACb,SAAS;KACV;IACD,aAAa,EAAE;QACb,aAAa;QACb,YAAY;QACZ,YAAY;QACZ,cAAc;QACd,gBAAgB;QAChB,gBAAgB;QAChB,cAAc;QACd,QAAQ;KACT;IACD,YAAY,EAAE;QACZ,UAAU;QACV,cAAc;QACd,YAAY;QACZ,QAAQ;QACR,OAAO;QACP,YAAY;QACZ,aAAa;QACb,aAAa;QACb,cAAc;QACd,WAAW;QACX,SAAS;QACT,cAAc;QACd,kBAAkB;QAClB,kBAAkB;QAClB,mBAAmB;QACnB,cAAc;QACd,eAAe;KAChB;CACF,CAAC;AAEF;;;;;GAKG;AACH,SAAgB,YAAY,CAAC,KAAe;IAC1C,MAAM,MAAM,GAAG,IAAI,GAAG,EAAU,CAAC;IACjC,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;QACzB,MAAM,KAAK,GAAG,IAAI,CAAC,WAAW,EAAE,CAAC;QACjC,IAAI,KAAK,CAAC,UAAU,CAAC,QAAQ,CAAC,EAAE,CAAC;YAC/B,MAAM,OAAO,GAAG,mBAAW,CAAC,KAAK,CAAC,CAAC;YACnC,IAAI,OAAO,EAAE,CAAC;gBACZ,KAAK,MAAM,MAAM,IAAI,OAAO,EAAE,CAAC;oBAC7B,MAAM,CAAC,GAAG,CAAC,MAAM,CAAC,WAAW,EAAE,CAAC,CAAC;gBACnC,CAAC;YACH,CAAC;YACD,2CAA2C;QAC7C,CAAC;aAAM,CAAC;YACN,MAAM,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC;QACpB,CAAC;IACH,CAAC;IACD,OAAO,MAAM,CAAC;AAChB,CAAC;AAED;;;;;;;;GAQG;AACH,SAAgB,aAAa,CAAC,QAAgB,EAAE,MAAkB;IAChE,MAAM,UAAU,GAAG,QAAQ,CAAC,WAAW,EAAE,CAAC;IAE1C,kEAAkE;IAClE,MAAM,iBAAiB,GACrB,MAAM,CAAC,aAAa,KAAK,IAAI,IAAI,CAAC,MAAM,CAAC,KAAK,KAAK,SAAS,IAAI,MAAM,CAAC,KAAK,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC;IAC3F,IAAI,iBAAiB,EAAE,CAAC;QACtB,MAAM,OAAO,GAAG,YAAY,CAAC,MAAM,CAAC,KAAK,IAAI,EAAE,CAAC,CAAC;QACjD,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,UAAU,CAAC,EAAE,CAAC;YAC7B,OAAO,KAAK,CAAC;QACf,CAAC;IACH,CAAC;IAED,oCAAoC;IACpC,IAAI,MAAM,CAAC,IAAI,IAAI,MAAM,CAAC,IAAI,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QAC1C,MAAM,MAAM,GAAG,YAAY,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;QACzC,IAAI,MAAM,CAAC,GAAG,CAAC,UAAU,CAAC,EAAE,CAAC;YAC3B,OAAO,KAAK,CAAC;QACf,CAAC;IACH,CAAC;IAED,OAAO,IAAI,CAAC;AACd,CAAC;AAED;;;;GAIG;AACH,SAAgB,aAAa,CAAC,CAAa,EAAE,CAAa;IACxD,uCAAuC;IACvC,MAAM,UAAU,GAAG,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,IAAI,EAAE,CAAC,EAAE,GAAG,CAAC,CAAC,CAAC,IAAI,IAAI,EAAE,CAAC,CAAC,CAAC;IAE1D,0CAA0C;IAC1C,8DAA8D;IAC9D,6CAA6C;IAC7C,qCAAqC;IACrC,MAAM,UAAU,GAAG,CAAC,CAAC,aAAa,KAAK,IAAI,IAAI,CAAC,CAAC,CAAC,KAAK,EAAE,MAAM,IAAI,CAAC,CAAC,GAAG,CAAC,CAAC;IAC1E,MAAM,UAAU,GAAG,CAAC,CAAC,aAAa,KAAK,IAAI,IAAI,CAAC,CAAC,CAAC,KAAK,EAAE,MAAM,IAAI,CAAC,CAAC,GAAG,CAAC,CAAC;IAE1E,IAAI,WAAiC,CAAC;IACtC,IAAI,mBAAmB,GAAG,KAAK,CAAC;IAEhC,IAAI,UAAU,IAAI,UAAU,EAAE,CAAC;QAC7B,MAAM,SAAS,GAAG,YAAY,CAAC,CAAC,CAAC,KAAK,IAAI,EAAE,CAAC,CAAC;QAC9C,MAAM,SAAS,GAAG,YAAY,CAAC,CAAC,CAAC,KAAK,IAAI,EAAE,CAAC,CAAC;QAC9C,WAAW,GAAG,CAAC,GAAG,SAAS,CAAC,CAAC,MAAM,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,SAAS,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC,CAAC;QACnE,mBAAmB,GAAG,IAAI,CAAC;IAC7B,CAAC;SAAM,IAAI,UAAU,EAAE,CAAC;QACtB,WAAW,GAAG,CAAC,GAAG,CAAC,CAAC,CAAC,KAAK,IAAI,EAAE,CAAC,CAAC,CAAC;QACnC,mBAAmB,GAAG,IAAI,CAAC;IAC7B,CAAC;SAAM,IAAI,UAAU,EAAE,CAAC;QACtB,WAAW,GAAG,CAAC,GAAG,CAAC,CAAC,CAAC,KAAK,IAAI,EAAE,CAAC,CAAC,CAAC;QACnC,mBAAmB,GAAG,IAAI,CAAC;IAC7B,CAAC;IAED,OAAO;QACL,GAAG,CAAC,WAAW,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,WAAW,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QAC5D,GAAG,CAAC,mBAAmB,CAAC,CAAC,CAAC,EAAE,aAAa,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QACvD,GAAG,CAAC,UAAU,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,UAAU,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;KACnD,CAAC;AACJ,CAAC"}

package/dist-cjs/providers/brave.d.ts

@@ -0,0 +1,10 @@
+import type { SearchProvider, SearchOptions, SearchResult, SearchProviderEnv } from "./search-provider.js";
+export declare class BraveSearchProvider implements SearchProvider {
+    private readonly env;
+    readonly name = "brave";
+    readonly requiresApiKey = true;
+    readonly priority = 1;
+    constructor(env?: SearchProviderEnv | Record<string, string | undefined>);
+    isAvailable(): boolean;
+    search(query: string, options?: SearchOptions): Promise<SearchResult[]>;
+}

package/dist-cjs/providers/brave.js

@@ -0,0 +1,67 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.BraveSearchProvider = void 0;
+const search_provider_js_1 = require("./search-provider.js");
+class BraveSearchProvider {
+    env;
+    name = "brave";
+    requiresApiKey = true;
+    priority = 1;
+    constructor(env = process.env) {
+        this.env = env;
+    }
+    isAvailable() {
+        const apiKey = (0, search_provider_js_1.resolveSearchProviderEnv)(this.env).BRAVE_API_KEY;
+        return Boolean(apiKey && apiKey.trim().length > 0);
+    }
+    async search(query, options) {
+        const apiKey = (0, search_provider_js_1.resolveSearchProviderEnv)(this.env).BRAVE_API_KEY;
+        if (!apiKey) {
+            throw new Error("BRAVE_API_KEY environment variable is not set");
+        }
+        const limit = options?.limit ?? 5;
+        const url = new URL("https://api.search.brave.com/res/v1/web/search");
+        url.searchParams.set("q", query);
+        url.searchParams.set("count", String(limit));
+        // Handle timeRange option (map to Brave's freshness parameter)
+        if (options?.timeRange) {
+            const freshnessMap = {
+                day: "pd",
+                week: "pw",
+                month: "pm",
+                year: "py",
+            };
+            const freshness = freshnessMap[options.timeRange];
+            if (freshness) {
+                url.searchParams.set("freshness", freshness);
+            }
+        }
+        const { signal, cleanup } = (0, search_provider_js_1.createProviderAbortSignal)(30_000, options?.signal);
+        try {
+            const response = await fetch(url.toString(), {
+                method: "GET",
+                headers: {
+                    Accept: "application/json",
+                    "X-Subscription-Token": apiKey,
+                },
+                signal,
+            });
+            if (!response.ok) {
+                throw new Error(`Brave Search API error: ${response.status} ${response.statusText}`);
+            }
+            const json = await response.json();
+            const webResults = json.web?.results || [];
+            return webResults.map((r) => ({
+                title: r.title,
+                url: r.url,
+                content: r.description,
+                score: r.relevance_score,
+            }));
+        }
+        finally {
+            cleanup();
+        }
+    }
+}
+exports.BraveSearchProvider = BraveSearchProvider;
+//# sourceMappingURL=brave.js.map

package/dist-cjs/providers/brave.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"brave.js","sourceRoot":"","sources":["../../src/providers/brave.ts"],"names":[],"mappings":";;;AAMA,6DAA2F;AAE3F,MAAa,mBAAmB;IAMX;IALV,IAAI,GAAG,OAAO,CAAC;IACf,cAAc,GAAG,IAAI,CAAC;IACtB,QAAQ,GAAG,CAAC,CAAC;IAEtB,YACmB,MAA8D,OAAO,CAAC,GAAG;QAAzE,QAAG,GAAH,GAAG,CAAsE;IACzF,CAAC;IAEJ,WAAW;QACT,MAAM,MAAM,GAAG,IAAA,6CAAwB,EAAC,IAAI,CAAC,GAAG,CAAC,CAAC,aAAa,CAAC;QAChE,OAAO,OAAO,CAAC,MAAM,IAAI,MAAM,CAAC,IAAI,EAAE,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC;IACrD,CAAC;IAED,KAAK,CAAC,MAAM,CAAC,KAAa,EAAE,OAAuB;QACjD,MAAM,MAAM,GAAG,IAAA,6CAAwB,EAAC,IAAI,CAAC,GAAG,CAAC,CAAC,aAAa,CAAC;QAChE,IAAI,CAAC,MAAM,EAAE,CAAC;YACZ,MAAM,IAAI,KAAK,CAAC,+CAA+C,CAAC,CAAC;QACnE,CAAC;QAED,MAAM,KAAK,GAAG,OAAO,EAAE,KAAK,IAAI,CAAC,CAAC;QAElC,MAAM,GAAG,GAAG,IAAI,GAAG,CAAC,gDAAgD,CAAC,CAAC;QACtE,GAAG,CAAC,YAAY,CAAC,GAAG,CAAC,GAAG,EAAE,KAAK,CAAC,CAAC;QACjC,GAAG,CAAC,YAAY,CAAC,GAAG,CAAC,OAAO,EAAE,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC;QAE7C,+DAA+D;QAC/D,IAAI,OAAO,EAAE,SAAS,EAAE,CAAC;YACvB,MAAM,YAAY,GAA2B;gBAC3C,GAAG,EAAE,IAAI;gBACT,IAAI,EAAE,IAAI;gBACV,KAAK,EAAE,IAAI;gBACX,IAAI,EAAE,IAAI;aACX,CAAC;YACF,MAAM,SAAS,GAAG,YAAY,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC;YAClD,IAAI,SAAS,EAAE,CAAC;gBACd,GAAG,CAAC,YAAY,CAAC,GAAG,CAAC,WAAW,EAAE,SAAS,CAAC,CAAC;YAC/C,CAAC;QACH,CAAC;QAED,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,GAAG,IAAA,8CAAyB,EAAC,MAAM,EAAE,OAAO,EAAE,MAAM,CAAC,CAAC;QAE/E,IAAI,CAAC;YACH,MAAM,QAAQ,GAAG,MAAM,KAAK,CAAC,GAAG,CAAC,QAAQ,EAAE,EAAE;gBAC3C,MAAM,EAAE,KAAK;gBACb,OAAO,EAAE;oBACP,MAAM,EAAE,kBAAkB;oBAC1B,sBAAsB,EAAE,MAAM;iBAC/B;gBACD,MAAM;aACP,CAAC,CAAC;YAEH,IAAI,CAAC,QAAQ,CAAC,EAAE,EAAE,CAAC;gBACjB,MAAM,IAAI,KAAK,CAAC,2BAA2B,QAAQ,CAAC,MAAM,IAAI,QAAQ,CAAC,UAAU,EAAE,CAAC,CAAC;YACvF,CAAC;YAED,MAAM,IAAI,GAAG,MAAM,QAAQ,CAAC,IAAI,EAAE,CAAC;YACnC,MAAM,UAAU,GAAG,IAAI,CAAC,GAAG,EAAE,OAAO,IAAI,EAAE,CAAC;YAE3C,OAAO,UAAU,CAAC,GAAG,CACnB,CAAC,CAAgF,EAAE,EAAE,CAAC,CAAC;gBACrF,KAAK,EAAE,CAAC,CAAC,KAAK;gBACd,GAAG,EAAE,CAAC,CAAC,GAAG;gBACV,OAAO,EAAE,CAAC,CAAC,WAAW;gBACtB,KAAK,EAAE,CAAC,CAAC,eAAe;aACzB,CAAC,CACH,CAAC;QACJ,CAAC;gBAAS,CAAC;YACT,OAAO,EAAE,CAAC;QACZ,CAAC;IACH,CAAC;CACF;AAvED,kDAuEC"}

package/dist-cjs/providers/duckduckgo.d.ts

@@ -0,0 +1,18 @@
+import type { SearchProvider, SearchOptions, SearchResult } from "./search-provider.js";
+export declare class DuckDuckGoSearchProvider implements SearchProvider {
+    readonly name = "duckduckgo";
+    readonly requiresApiKey = false;
+    readonly priority = 6;
+    isAvailable(): boolean;
+    search(query: string, options?: SearchOptions): Promise<SearchResult[]>;
+    /**
+     * Strip HTML tags from a string
+     */
+    private stripHtmlTags;
+    /**
+     * Decode HTML entities in URLs
+     */
+    private decodeHtmlEntities;
+    private resolveDuckDuckGoResultUrl;
+    private normalizeResultUrl;
+}

package/dist-cjs/providers/duckduckgo.js

@@ -0,0 +1,181 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DuckDuckGoSearchProvider = void 0;
+const search_provider_js_1 = require("./search-provider.js");
+class DuckDuckGoSearchProvider {
+    name = "duckduckgo";
+    requiresApiKey = false;
+    priority = 6;
+    isAvailable() {
+        // DuckDuckGo is always available (no API key required)
+        return true;
+    }
+    async search(query, options) {
+        const limit = options?.limit ?? 5;
+        // DuckDuckGo HTML search endpoint (we'll parse the HTML response)
+        // The Instant Answer API doesn't provide web search results, only factoids
+        const url = new URL("https://html.duckduckgo.com/html/");
+        url.searchParams.set("q", query);
+        const { signal, cleanup } = (0, search_provider_js_1.createProviderAbortSignal)(30_000, options?.signal);
+        try {
+            const response = await fetch(url.toString(), {
+                method: "GET",
+                signal,
+                headers: {
+                    "User-Agent": "Mozilla/5.0 (compatible; ARIA/1.0)",
+                },
+            });
+            if (!response.ok) {
+                throw new Error(`DuckDuckGo Search error: ${response.status} ${response.statusText}`);
+            }
+            const html = await response.text();
+            // Parse HTML to extract search results
+            // DuckDuckGo HTML results have result__a (title/url) and result__snippet (description)
+            const results = [];
+            // First pass: extract all result__a links (title + url)
+            const linkMap = new Map();
+            const linkRegex = /<a(?=[^>]*\bclass=(["'])[^"']*\bresult__a\b[^"']*\1)(?=[^>]*\bhref=(["'])(.*?)\2)[^>]*>([\s\S]*?)<\/a>/gi;
+            let match;
+            let resultAnchorCount = 0;
+            while ((match = linkRegex.exec(html)) !== null) {
+                const rawHref = match[3];
+                const rawTitle = match[4];
+                if (!rawHref || !rawTitle) {
+                    continue;
+                }
+                resultAnchorCount++;
+                const url = this.resolveDuckDuckGoResultUrl(rawHref);
+                if (!url) {
+                    continue;
+                }
+                const title = this.stripHtmlTags(rawTitle);
+                if (!title) {
+                    continue;
+                }
+                linkMap.set(url, { title, url });
+            }
+            // If DDG returned result anchors but we extracted zero usable URLs, parsing is stale.
+            // Throw to allow router fallback rather than silently returning empty results.
+            if (resultAnchorCount > 0 && linkMap.size === 0) {
+                throw new Error("Could not resolve any result URLs from DuckDuckGo response");
+            }
+            // Second pass: extract snippets
+            const snippetRegex = /<(?:a|div|span)(?=[^>]*\bclass=(["'])[^"']*\bresult__snippet\b[^"']*\1)[^>]*>([\s\S]*?)<\/(?:a|div|span)>/gi;
+            const snippets = [];
+            while ((match = snippetRegex.exec(html)) !== null) {
+                const rawSnippet = match[2];
+                snippets.push(this.stripHtmlTags(rawSnippet ?? ""));
+            }
+            // Combine results (matching by order, which should align)
+            const linkEntries = Array.from(linkMap.values());
+            for (let i = 0; i < Math.min(linkEntries.length, limit); i++) {
+                const link = linkEntries[i];
+                if (!link) {
+                    continue;
+                }
+                const snippet = snippets[i] || link.title;
+                results.push({
+                    title: link.title,
+                    url: link.url,
+                    content: snippet,
+                });
+            }
+            return results;
+        }
+        finally {
+            cleanup();
+        }
+    }
+    /**
+     * Strip HTML tags from a string
+     */
+    stripHtmlTags(html) {
+        return html
+            .replace(/<[^>]*>/g, "")
+            .replace(/&nbsp;/g, " ")
+            .replace(/&amp;/g, "&")
+            .replace(/&lt;/g, "<")
+            .replace(/&gt;/g, ">")
+            .replace(/&quot;/g, '"')
+            .replace(/&#39;/g, "'")
+            .trim();
+    }
+    /**
+     * Decode HTML entities in URLs
+     */
+    decodeHtmlEntities(text) {
+        return text
+            .replace(/&amp;/g, "&")
+            .replace(/&lt;/g, "<")
+            .replace(/&gt;/g, ">")
+            .replace(/&quot;/g, '"')
+            .replace(/&#39;/g, "'");
+    }
+    resolveDuckDuckGoResultUrl(rawHref) {
+        const decodedHref = this.decodeHtmlEntities(rawHref).trim();
+        if (!decodedHref) {
+            return null;
+        }
+        let absoluteHref = decodedHref;
+        if (absoluteHref.startsWith("//")) {
+            absoluteHref = `https:${absoluteHref}`;
+        }
+        else if (absoluteHref.startsWith("/")) {
+            absoluteHref = `https://duckduckgo.com${absoluteHref}`;
+        }
+        let parsed;
+        try {
+            parsed = new URL(absoluteHref);
+        }
+        catch {
+            return null;
+        }
+        const hostname = parsed.hostname.toLowerCase();
+        if (hostname === "duckduckgo.com" || hostname.endsWith(".duckduckgo.com")) {
+            const redirected = parsed.searchParams.get("uddg");
+            if (!redirected) {
+                return null;
+            }
+            return this.normalizeResultUrl(redirected);
+        }
+        return this.normalizeResultUrl(absoluteHref);
+    }
+    normalizeResultUrl(candidate) {
+        let value = candidate.trim();
+        if (!value) {
+            return null;
+        }
+        if (value.startsWith("//")) {
+            value = `https:${value}`;
+        }
+        // Some uddg values are encoded multiple times; decode at most twice.
+        for (let i = 0; i < 2; i++) {
+            try {
+                const decoded = decodeURIComponent(value);
+                if (decoded === value) {
+                    break;
+                }
+                value = decoded;
+            }
+            catch {
+                break;
+            }
+        }
+        try {
+            const parsed = new URL(value);
+            if (parsed.protocol !== "http:" && parsed.protocol !== "https:") {
+                return null;
+            }
+            const hostname = parsed.hostname.toLowerCase();
+            if (hostname === "duckduckgo.com" || hostname.endsWith(".duckduckgo.com")) {
+                return null;
+            }
+            return parsed.toString();
+        }
+        catch {
+            return null;
+        }
+    }
+}
+exports.DuckDuckGoSearchProvider = DuckDuckGoSearchProvider;
+//# sourceMappingURL=duckduckgo.js.map

package/dist-cjs/providers/duckduckgo.js.map

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

package/dist-cjs/providers/exa.d.ts

@@ -0,0 +1,10 @@
+import type { SearchProvider, SearchOptions, SearchResult, SearchProviderEnv } from "./search-provider.js";
+export declare class ExaSearchProvider implements SearchProvider {
+    private readonly env;
+    readonly name = "exa";
+    readonly requiresApiKey = true;
+    readonly priority = 3;
+    constructor(env?: SearchProviderEnv | Record<string, string | undefined>);
+    isAvailable(): boolean;
+    search(query: string, options?: SearchOptions): Promise<SearchResult[]>;
+}

package/dist-cjs/providers/exa.js

@@ -0,0 +1,68 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ExaSearchProvider = void 0;
+const search_provider_js_1 = require("./search-provider.js");
+class ExaSearchProvider {
+    env;
+    name = "exa";
+    requiresApiKey = true;
+    priority = 3;
+    constructor(env = process.env) {
+        this.env = env;
+    }
+    isAvailable() {
+        const apiKey = (0, search_provider_js_1.resolveSearchProviderEnv)(this.env).EXA_API_KEY;
+        return Boolean(apiKey && apiKey.trim().length > 0);
+    }
+    async search(query, options) {
+        const apiKey = (0, search_provider_js_1.resolveSearchProviderEnv)(this.env).EXA_API_KEY;
+        if (!apiKey) {
+            throw new Error("EXA_API_KEY environment variable is not set");
+        }
+        const limit = options?.limit ?? 5;
+        const body = {
+            query,
+            numResults: limit,
+            useAutoprompt: true,
+            contents: {
+                text: true,
+            },
+        };
+        // Domain filtering
+        if (options?.domains) {
+            body.includeDomains = options.domains;
+        }
+        if (options?.excludeDomains) {
+            body.excludeDomains = options.excludeDomains;
+        }
+        const { signal, cleanup } = (0, search_provider_js_1.createProviderAbortSignal)(30_000, options?.signal);
+        try {
+            const response = await fetch("https://api.exa.ai/search", {
+                method: "POST",
+                headers: {
+                    "Content-Type": "application/json",
+                    "x-api-key": apiKey,
+                },
+                body: JSON.stringify(body),
+                signal,
+            });
+            if (!response.ok) {
+                throw new Error(`Exa Search API error: ${response.status} ${response.statusText}`);
+            }
+            const json = await response.json();
+            const results = (json.results || []);
+            return results.map((r) => ({
+                title: r.title,
+                url: r.url,
+                content: r.text || "",
+                score: r.score,
+                publishedDate: r.publishedDate,
+            }));
+        }
+        finally {
+            cleanup();
+        }
+    }
+}
+exports.ExaSearchProvider = ExaSearchProvider;
+//# sourceMappingURL=exa.js.map

package/dist-cjs/providers/exa.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"exa.js","sourceRoot":"","sources":["../../src/providers/exa.ts"],"names":[],"mappings":";;;AAMA,6DAA2F;AAE3F,MAAa,iBAAiB;IAMT;IALV,IAAI,GAAG,KAAK,CAAC;IACb,cAAc,GAAG,IAAI,CAAC;IACtB,QAAQ,GAAG,CAAC,CAAC;IAEtB,YACmB,MAA8D,OAAO,CAAC,GAAG;QAAzE,QAAG,GAAH,GAAG,CAAsE;IACzF,CAAC;IAEJ,WAAW;QACT,MAAM,MAAM,GAAG,IAAA,6CAAwB,EAAC,IAAI,CAAC,GAAG,CAAC,CAAC,WAAW,CAAC;QAC9D,OAAO,OAAO,CAAC,MAAM,IAAI,MAAM,CAAC,IAAI,EAAE,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC;IACrD,CAAC;IAED,KAAK,CAAC,MAAM,CAAC,KAAa,EAAE,OAAuB;QACjD,MAAM,MAAM,GAAG,IAAA,6CAAwB,EAAC,IAAI,CAAC,GAAG,CAAC,CAAC,WAAW,CAAC;QAC9D,IAAI,CAAC,MAAM,EAAE,CAAC;YACZ,MAAM,IAAI,KAAK,CAAC,6CAA6C,CAAC,CAAC;QACjE,CAAC;QAED,MAAM,KAAK,GAAG,OAAO,EAAE,KAAK,IAAI,CAAC,CAAC;QAElC,MAAM,IAAI,GAA4B;YACpC,KAAK;YACL,UAAU,EAAE,KAAK;YACjB,aAAa,EAAE,IAAI;YACnB,QAAQ,EAAE;gBACR,IAAI,EAAE,IAAI;aACX;SACF,CAAC;QAEF,mBAAmB;QACnB,IAAI,OAAO,EAAE,OAAO,EAAE,CAAC;YACrB,IAAI,CAAC,cAAc,GAAG,OAAO,CAAC,OAAO,CAAC;QACxC,CAAC;QACD,IAAI,OAAO,EAAE,cAAc,EAAE,CAAC;YAC5B,IAAI,CAAC,cAAc,GAAG,OAAO,CAAC,cAAc,CAAC;QAC/C,CAAC;QAED,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,GAAG,IAAA,8CAAyB,EAAC,MAAM,EAAE,OAAO,EAAE,MAAM,CAAC,CAAC;QAE/E,IAAI,CAAC;YACH,MAAM,QAAQ,GAAG,MAAM,KAAK,CAAC,2BAA2B,EAAE;gBACxD,MAAM,EAAE,MAAM;gBACd,OAAO,EAAE;oBACP,cAAc,EAAE,kBAAkB;oBAClC,WAAW,EAAE,MAAM;iBACpB;gBACD,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC;gBAC1B,MAAM;aACP,CAAC,CAAC;YAEH,IAAI,CAAC,QAAQ,CAAC,EAAE,EAAE,CAAC;gBACjB,MAAM,IAAI,KAAK,CAAC,yBAAyB,QAAQ,CAAC,MAAM,IAAI,QAAQ,CAAC,UAAU,EAAE,CAAC,CAAC;YACrF,CAAC;YAED,MAAM,IAAI,GAAG,MAAM,QAAQ,CAAC,IAAI,EAAE,CAAC;YACnC,MAAM,OAAO,GAAG,CAAC,IAAI,CAAC,OAAO,IAAI,EAAE,CAMjC,CAAC;YAEH,OAAO,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;gBACzB,KAAK,EAAE,CAAC,CAAC,KAAK;gBACd,GAAG,EAAE,CAAC,CAAC,GAAG;gBACV,OAAO,EAAE,CAAC,CAAC,IAAI,IAAI,EAAE;gBACrB,KAAK,EAAE,CAAC,CAAC,KAAK;gBACd,aAAa,EAAE,CAAC,CAAC,aAAa;aAC/B,CAAC,CAAC,CAAC;QACN,CAAC;gBAAS,CAAC;YACT,OAAO,EAAE,CAAC;QACZ,CAAC;IACH,CAAC;CACF;AA5ED,8CA4EC"}

package/dist-cjs/providers/firecrawl.d.ts

@@ -0,0 +1,10 @@
+import type { SearchProvider, SearchOptions, SearchResult, SearchProviderEnv } from "./search-provider.js";
+export declare class FirecrawlSearchProvider implements SearchProvider {
+    private readonly env;
+    readonly name = "firecrawl";
+    readonly requiresApiKey = true;
+    readonly priority = 2;
+    constructor(env?: SearchProviderEnv | Record<string, string | undefined>);
+    isAvailable(): boolean;
+    search(query: string, options?: SearchOptions): Promise<SearchResult[]>;
+}

package/dist-cjs/providers/firecrawl.js

@@ -0,0 +1,60 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FirecrawlSearchProvider = void 0;
+const search_provider_js_1 = require("./search-provider.js");
+class FirecrawlSearchProvider {
+    env;
+    name = "firecrawl";
+    requiresApiKey = true;
+    priority = 2;
+    constructor(env = process.env) {
+        this.env = env;
+    }
+    isAvailable() {
+        const apiKey = (0, search_provider_js_1.resolveSearchProviderEnv)(this.env).FIRECRAWL_API_KEY;
+        return Boolean(apiKey && apiKey.trim().length > 0);
+    }
+    async search(query, options) {
+        const apiKey = (0, search_provider_js_1.resolveSearchProviderEnv)(this.env).FIRECRAWL_API_KEY;
+        if (!apiKey) {
+            throw new Error("FIRECRAWL_API_KEY environment variable is not set");
+        }
+        const limit = options?.limit ?? 5;
+        const body = {
+            query,
+            limit,
+        };
+        const { signal, cleanup } = (0, search_provider_js_1.createProviderAbortSignal)(30_000, options?.signal);
+        try {
+            const response = await fetch("https://api.firecrawl.dev/v1/search", {
+                method: "POST",
+                headers: {
+                    "Content-Type": "application/json",
+                    Authorization: `Bearer ${apiKey}`,
+                },
+                body: JSON.stringify(body),
+                signal,
+            });
+            if (!response.ok) {
+                throw new Error(`Firecrawl Search API error: ${response.status} ${response.statusText}`);
+            }
+            const json = await response.json();
+            // Firecrawl can return 200 with success: false
+            if (json.success === false) {
+                throw new Error(`Firecrawl API error: ${json.error || "Unknown error"}`);
+            }
+            const results = (json.data || []);
+            return results.map((r) => ({
+                title: r.title,
+                url: r.url,
+                content: r.markdown || "",
+                score: r.score,
+            }));
+        }
+        finally {
+            cleanup();
+        }
+    }
+}
+exports.FirecrawlSearchProvider = FirecrawlSearchProvider;
+//# sourceMappingURL=firecrawl.js.map

package/dist-cjs/providers/firecrawl.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"firecrawl.js","sourceRoot":"","sources":["../../src/providers/firecrawl.ts"],"names":[],"mappings":";;;AAMA,6DAA2F;AAE3F,MAAa,uBAAuB;IAMf;IALV,IAAI,GAAG,WAAW,CAAC;IACnB,cAAc,GAAG,IAAI,CAAC;IACtB,QAAQ,GAAG,CAAC,CAAC;IAEtB,YACmB,MAA8D,OAAO,CAAC,GAAG;QAAzE,QAAG,GAAH,GAAG,CAAsE;IACzF,CAAC;IAEJ,WAAW;QACT,MAAM,MAAM,GAAG,IAAA,6CAAwB,EAAC,IAAI,CAAC,GAAG,CAAC,CAAC,iBAAiB,CAAC;QACpE,OAAO,OAAO,CAAC,MAAM,IAAI,MAAM,CAAC,IAAI,EAAE,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC;IACrD,CAAC;IAED,KAAK,CAAC,MAAM,CAAC,KAAa,EAAE,OAAuB;QACjD,MAAM,MAAM,GAAG,IAAA,6CAAwB,EAAC,IAAI,CAAC,GAAG,CAAC,CAAC,iBAAiB,CAAC;QACpE,IAAI,CAAC,MAAM,EAAE,CAAC;YACZ,MAAM,IAAI,KAAK,CAAC,mDAAmD,CAAC,CAAC;QACvE,CAAC;QAED,MAAM,KAAK,GAAG,OAAO,EAAE,KAAK,IAAI,CAAC,CAAC;QAElC,MAAM,IAAI,GAA4B;YACpC,KAAK;YACL,KAAK;SACN,CAAC;QAEF,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,GAAG,IAAA,8CAAyB,EAAC,MAAM,EAAE,OAAO,EAAE,MAAM,CAAC,CAAC;QAE/E,IAAI,CAAC;YACH,MAAM,QAAQ,GAAG,MAAM,KAAK,CAAC,qCAAqC,EAAE;gBAClE,MAAM,EAAE,MAAM;gBACd,OAAO,EAAE;oBACP,cAAc,EAAE,kBAAkB;oBAClC,aAAa,EAAE,UAAU,MAAM,EAAE;iBAClC;gBACD,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC;gBAC1B,MAAM;aACP,CAAC,CAAC;YAEH,IAAI,CAAC,QAAQ,CAAC,EAAE,EAAE,CAAC;gBACjB,MAAM,IAAI,KAAK,CAAC,+BAA+B,QAAQ,CAAC,MAAM,IAAI,QAAQ,CAAC,UAAU,EAAE,CAAC,CAAC;YAC3F,CAAC;YAED,MAAM,IAAI,GAAG,MAAM,QAAQ,CAAC,IAAI,EAAE,CAAC;YAEnC,+CAA+C;YAC/C,IAAI,IAAI,CAAC,OAAO,KAAK,KAAK,EAAE,CAAC;gBAC3B,MAAM,IAAI,KAAK,CAAC,wBAAwB,IAAI,CAAC,KAAK,IAAI,eAAe,EAAE,CAAC,CAAC;YAC3E,CAAC;YAED,MAAM,OAAO,GAAG,CAAC,IAAI,CAAC,IAAI,IAAI,EAAE,CAK9B,CAAC;YAEH,OAAO,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;gBACzB,KAAK,EAAE,CAAC,CAAC,KAAK;gBACd,GAAG,EAAE,CAAC,CAAC,GAAG;gBACV,OAAO,EAAE,CAAC,CAAC,QAAQ,IAAI,EAAE;gBACzB,KAAK,EAAE,CAAC,CAAC,KAAK;aACf,CAAC,CAAC,CAAC;QACN,CAAC;gBAAS,CAAC;YACT,OAAO,EAAE,CAAC;QACZ,CAAC;IACH,CAAC;CACF;AApED,0DAoEC"}

package/dist-cjs/providers/index.d.ts

@@ -0,0 +1,8 @@
+export type { SearchOptions, SearchResult, SearchProvider } from "./search-provider.js";
+export { JinaSearchProvider } from "./jina.js";
+export { DuckDuckGoSearchProvider } from "./duckduckgo.js";
+export { TavilySearchProvider } from "./tavily.js";
+export { BraveSearchProvider } from "./brave.js";
+export { ExaSearchProvider } from "./exa.js";
+export { FirecrawlSearchProvider } from "./firecrawl.js";
+export { SearchProviderRouter } from "./router.js";

package/dist-cjs/providers/index.js

@@ -0,0 +1,18 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SearchProviderRouter = exports.FirecrawlSearchProvider = exports.ExaSearchProvider = exports.BraveSearchProvider = exports.TavilySearchProvider = exports.DuckDuckGoSearchProvider = exports.JinaSearchProvider = void 0;
+var jina_js_1 = require("./jina.js");
+Object.defineProperty(exports, "JinaSearchProvider", { enumerable: true, get: function () { return jina_js_1.JinaSearchProvider; } });
+var duckduckgo_js_1 = require("./duckduckgo.js");
+Object.defineProperty(exports, "DuckDuckGoSearchProvider", { enumerable: true, get: function () { return duckduckgo_js_1.DuckDuckGoSearchProvider; } });
+var tavily_js_1 = require("./tavily.js");
+Object.defineProperty(exports, "TavilySearchProvider", { enumerable: true, get: function () { return tavily_js_1.TavilySearchProvider; } });
+var brave_js_1 = require("./brave.js");
+Object.defineProperty(exports, "BraveSearchProvider", { enumerable: true, get: function () { return brave_js_1.BraveSearchProvider; } });
+var exa_js_1 = require("./exa.js");
+Object.defineProperty(exports, "ExaSearchProvider", { enumerable: true, get: function () { return exa_js_1.ExaSearchProvider; } });
+var firecrawl_js_1 = require("./firecrawl.js");
+Object.defineProperty(exports, "FirecrawlSearchProvider", { enumerable: true, get: function () { return firecrawl_js_1.FirecrawlSearchProvider; } });
+var router_js_1 = require("./router.js");
+Object.defineProperty(exports, "SearchProviderRouter", { enumerable: true, get: function () { return router_js_1.SearchProviderRouter; } });
+//# sourceMappingURL=index.js.map

package/dist-cjs/providers/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/providers/index.ts"],"names":[],"mappings":";;;AACA,qCAA+C;AAAtC,6GAAA,kBAAkB,OAAA;AAC3B,iDAA2D;AAAlD,yHAAA,wBAAwB,OAAA;AACjC,yCAAmD;AAA1C,iHAAA,oBAAoB,OAAA;AAC7B,uCAAiD;AAAxC,+GAAA,mBAAmB,OAAA;AAC5B,mCAA6C;AAApC,2GAAA,iBAAiB,OAAA;AAC1B,+CAAyD;AAAhD,uHAAA,uBAAuB,OAAA;AAChC,yCAAmD;AAA1C,iHAAA,oBAAoB,OAAA"}