agentic-pi 0.2.1 → 0.2.3

package/dist/extensions/web-search/providers/brave.js.map

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

package/dist/extensions/web-search/providers/exa.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Exa provider. https://docs.exa.ai/
+ *
+ * Endpoints used:
+ *   POST https://api.exa.ai/search    — neural/keyword search
+ *   POST https://api.exa.ai/contents  — fetch extracted content for one or more URLs
+ *
+ * Auth: `x-api-key: <key>`.
+ */
+import type { FetchImpl, Provider } from "../types.js";
+export interface ExaOptions {
+    apiKey: string;
+    fetchImpl?: FetchImpl;
+    baseUrl?: string;
+}
+export declare function createExaProvider(options: ExaOptions): Provider;

package/dist/extensions/web-search/providers/exa.js

@@ -0,0 +1,85 @@
+/**
+ * Exa provider. https://docs.exa.ai/
+ *
+ * Endpoints used:
+ *   POST https://api.exa.ai/search    — neural/keyword search
+ *   POST https://api.exa.ai/contents  — fetch extracted content for one or more URLs
+ *
+ * Auth: `x-api-key: <key>`.
+ */
+export function createExaProvider(options) {
+    const fetchImpl = options.fetchImpl ?? globalThis.fetch;
+    const baseUrl = options.baseUrl ?? "https://api.exa.ai";
+    return {
+        name: "exa",
+        supportsExtractedContent: true,
+        async search(params) {
+            const body = {
+                query: params.query,
+                numResults: params.maxResults,
+                type: params.searchDepth === "advanced" ? "neural" : "auto",
+            };
+            if (params.includeDomains?.length)
+                body.includeDomains = params.includeDomains;
+            if (params.excludeDomains?.length)
+                body.excludeDomains = params.excludeDomains;
+            if (params.includeContent === true) {
+                body.contents = { text: { maxCharacters: 4000 } };
+            }
+            const r = await fetchImpl(`${baseUrl}/search`, {
+                method: "POST",
+                headers: {
+                    "content-type": "application/json",
+                    "x-api-key": options.apiKey,
+                },
+                body: JSON.stringify(body),
+            });
+            if (!r.ok) {
+                const text = await r.text().catch(() => "");
+                throw new Error(`exa search failed: http ${r.status} ${text.slice(0, 200)}`);
+            }
+            const data = (await r.json());
+            return {
+                provider: "exa",
+                query: params.query,
+                results: (data.results ?? []).map((it) => ({
+                    title: it.title ?? "",
+                    url: it.url ?? "",
+                    content: it.text,
+                    score: it.score,
+                    publishedDate: it.publishedDate,
+                })),
+            };
+        },
+        async fetch(params) {
+            const r = await fetchImpl(`${baseUrl}/contents`, {
+                method: "POST",
+                headers: {
+                    "content-type": "application/json",
+                    "x-api-key": options.apiKey,
+                },
+                body: JSON.stringify({
+                    urls: [params.url],
+                    text: true,
+                }),
+            });
+            if (!r.ok) {
+                const text = await r.text().catch(() => "");
+                throw new Error(`exa contents failed: http ${r.status} ${text.slice(0, 200)}`);
+            }
+            const data = (await r.json());
+            const hit = data.results?.[0];
+            if (!hit?.text) {
+                throw new Error(`exa contents returned no text for ${params.url}`);
+            }
+            return {
+                provider: "exa",
+                url: params.url,
+                resolvedUrl: hit.url,
+                text: hit.text,
+                title: hit.title,
+            };
+        },
+    };
+}
+//# sourceMappingURL=exa.js.map

package/dist/extensions/web-search/providers/exa.js.map

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

package/dist/extensions/web-search/providers/tavily.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Tavily provider. https://docs.tavily.com/
+ *
+ * Endpoints used:
+ *   POST https://api.tavily.com/search   — ranked links + optional content + optional answer
+ *   POST https://api.tavily.com/extract  — bulk fetch + extracted text for a list of URLs
+ *
+ * API key passed as `api_key` in the JSON body (Tavily's documented
+ * convention; the Bearer header is rejected on /search).
+ */
+import type { FetchImpl, Provider } from "../types.js";
+export interface TavilyOptions {
+    apiKey: string;
+    fetchImpl?: FetchImpl;
+    /** Override for tests. */
+    baseUrl?: string;
+}
+export declare function createTavilyProvider(options: TavilyOptions): Provider;

package/dist/extensions/web-search/providers/tavily.js

@@ -0,0 +1,85 @@
+/**
+ * Tavily provider. https://docs.tavily.com/
+ *
+ * Endpoints used:
+ *   POST https://api.tavily.com/search   — ranked links + optional content + optional answer
+ *   POST https://api.tavily.com/extract  — bulk fetch + extracted text for a list of URLs
+ *
+ * API key passed as `api_key` in the JSON body (Tavily's documented
+ * convention; the Bearer header is rejected on /search).
+ */
+export function createTavilyProvider(options) {
+    const fetchImpl = options.fetchImpl ?? globalThis.fetch;
+    const baseUrl = options.baseUrl ?? "https://api.tavily.com";
+    return {
+        name: "tavily",
+        supportsExtractedContent: true,
+        async search(params) {
+            const body = {
+                api_key: options.apiKey,
+                query: params.query,
+                max_results: params.maxResults,
+                search_depth: params.searchDepth === "advanced" ? "advanced" : "basic",
+                include_answer: true,
+                include_raw_content: params.includeContent === true,
+            };
+            if (params.includeDomains?.length)
+                body.include_domains = params.includeDomains;
+            if (params.excludeDomains?.length)
+                body.exclude_domains = params.excludeDomains;
+            const r = await fetchImpl(`${baseUrl}/search`, {
+                method: "POST",
+                headers: { "content-type": "application/json" },
+                body: JSON.stringify(body),
+            });
+            if (!r.ok) {
+                const text = await r.text().catch(() => "");
+                throw new Error(`tavily search failed: http ${r.status} ${text.slice(0, 200)}`);
+            }
+            const data = (await r.json());
+            return {
+                provider: "tavily",
+                query: data.query ?? params.query,
+                answer: data.answer,
+                results: (data.results ?? []).map((it) => ({
+                    title: it.title ?? "",
+                    url: it.url ?? "",
+                    snippet: it.content,
+                    content: it.raw_content ?? undefined,
+                    score: it.score,
+                    publishedDate: it.published_date,
+                })),
+            };
+        },
+        async fetch(params) {
+            const r = await fetchImpl(`${baseUrl}/extract`, {
+                method: "POST",
+                headers: { "content-type": "application/json" },
+                body: JSON.stringify({
+                    api_key: options.apiKey,
+                    urls: [params.url],
+                }),
+            });
+            if (!r.ok) {
+                const text = await r.text().catch(() => "");
+                throw new Error(`tavily extract failed: http ${r.status} ${text.slice(0, 200)}`);
+            }
+            const data = (await r.json());
+            const hit = data.results?.[0];
+            if (!hit?.raw_content) {
+                const fail = data.failed_results?.[0];
+                throw new Error(fail?.error
+                    ? `tavily extract returned no content for ${params.url}: ${fail.error}`
+                    : `tavily extract returned no content for ${params.url}`);
+            }
+            return {
+                provider: "tavily",
+                url: params.url,
+                resolvedUrl: hit.url,
+                text: hit.raw_content,
+                title: hit.title,
+            };
+        },
+    };
+}
+//# sourceMappingURL=tavily.js.map

package/dist/extensions/web-search/providers/tavily.js.map

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

package/dist/extensions/web-search/rate-limit.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Tiny per-run call counter. Shared between web_search and web_fetch so the
+ * combined call count is bounded.
+ *
+ * When `max` is exceeded `consume()` returns false; the tool layer surfaces
+ * this as a structured error result (never throws).
+ */
+export declare class RateLimiter {
+    readonly max: number;
+    private used;
+    constructor(max: number);
+    consume(): boolean;
+    get remaining(): number;
+}

package/dist/extensions/web-search/rate-limit.js

@@ -0,0 +1,24 @@
+/**
+ * Tiny per-run call counter. Shared between web_search and web_fetch so the
+ * combined call count is bounded.
+ *
+ * When `max` is exceeded `consume()` returns false; the tool layer surfaces
+ * this as a structured error result (never throws).
+ */
+export class RateLimiter {
+    max;
+    used = 0;
+    constructor(max) {
+        this.max = max;
+    }
+    consume() {
+        if (this.used >= this.max)
+            return false;
+        this.used += 1;
+        return true;
+    }
+    get remaining() {
+        return Math.max(0, this.max - this.used);
+    }
+}
+//# sourceMappingURL=rate-limit.js.map

package/dist/extensions/web-search/rate-limit.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"rate-limit.js","sourceRoot":"","sources":["../../../src/extensions/web-search/rate-limit.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,MAAM,OAAO,WAAW;IAED;IADb,IAAI,GAAG,CAAC,CAAC;IACjB,YAAqB,GAAW;QAAX,QAAG,GAAH,GAAG,CAAQ;IAAG,CAAC;IAEpC,OAAO;QACL,IAAI,IAAI,CAAC,IAAI,IAAI,IAAI,CAAC,GAAG;YAAE,OAAO,KAAK,CAAC;QACxC,IAAI,CAAC,IAAI,IAAI,CAAC,CAAC;QACf,OAAO,IAAI,CAAC;IACd,CAAC;IAED,IAAI,SAAS;QACX,OAAO,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,CAAC,GAAG,GAAG,IAAI,CAAC,IAAI,CAAC,CAAC;IAC3C,CAAC;CACF"}

package/dist/extensions/web-search/safe-fetch.d.ts

@@ -0,0 +1,54 @@
+/**
+ * Safe-by-default HTTP GET wrapper for web_fetch.
+ *
+ * Rails:
+ *   - scheme must be http or https
+ *   - timeout via AbortController (default 15s)
+ *   - max response bytes hard-capped (default 1 MiB); streaming is aborted
+ *     once the cap is exceeded
+ *   - redirects followed manually, at most 3; scheme re-checked at each hop
+ *   - caller passes the content-type allowlist; non-matching responses
+ *     raise so the tool layer can return a structured error
+ *
+ * No SSRF private-range blocking is performed (deliberate per user
+ * decision). Operators who care should run this behind their own egress
+ * firewall.
+ */
+import type { FetchImpl } from "./types.js";
+export interface SafeFetchOptions {
+    /** Defaults to globalThis.fetch. Injected in tests. */
+    fetchImpl?: FetchImpl;
+    /** Per-request timeout in ms. Default 15_000. */
+    timeoutMs?: number;
+    /** Hard cap on response body bytes. Default 1 MiB. */
+    maxBytes?: number;
+    /** Max redirect hops. Default 3. */
+    maxRedirects?: number;
+    /**
+     * Allowed content-types as case-insensitive prefixes. A response is
+     * accepted if its Content-Type starts with any entry. Default: text/*,
+     * application/(xhtml+xml|xml|json).
+     */
+    allowedContentTypePrefixes?: string[];
+}
+export interface SafeFetchResult {
+    status: number;
+    contentType?: string;
+    body: string;
+    finalUrl: string;
+}
+export declare const SAFE_FETCH_DEFAULTS: {
+    timeoutMs: number;
+    maxBytes: number;
+    maxRedirects: number;
+};
+export declare class SafeFetchError extends Error {
+    readonly code: string;
+    readonly status?: number | undefined;
+    constructor(message: string, code: string, status?: number | undefined);
+}
+/**
+ * Issue a GET, follow redirects manually, cap byte count, enforce timeout
+ * and content-type. Returns the decoded body as a UTF-8 string.
+ */
+export declare function safeFetch(rawUrl: string, options?: SafeFetchOptions): Promise<SafeFetchResult>;

package/dist/extensions/web-search/safe-fetch.js

@@ -0,0 +1,172 @@
+/**
+ * Safe-by-default HTTP GET wrapper for web_fetch.
+ *
+ * Rails:
+ *   - scheme must be http or https
+ *   - timeout via AbortController (default 15s)
+ *   - max response bytes hard-capped (default 1 MiB); streaming is aborted
+ *     once the cap is exceeded
+ *   - redirects followed manually, at most 3; scheme re-checked at each hop
+ *   - caller passes the content-type allowlist; non-matching responses
+ *     raise so the tool layer can return a structured error
+ *
+ * No SSRF private-range blocking is performed (deliberate per user
+ * decision). Operators who care should run this behind their own egress
+ * firewall.
+ */
+const DEFAULT_ALLOWED_PREFIXES = [
+    "text/",
+    "application/xhtml+xml",
+    "application/xml",
+    "application/json",
+];
+export const SAFE_FETCH_DEFAULTS = {
+    timeoutMs: 15_000,
+    maxBytes: 1024 * 1024,
+    maxRedirects: 3,
+};
+export class SafeFetchError extends Error {
+    code;
+    status;
+    constructor(message, code, status) {
+        super(message);
+        this.code = code;
+        this.status = status;
+        this.name = "SafeFetchError";
+    }
+}
+function assertHttpScheme(url) {
+    if (url.protocol !== "http:" && url.protocol !== "https:") {
+        throw new SafeFetchError(`unsupported url scheme '${url.protocol}' (only http/https allowed)`, "bad-scheme");
+    }
+}
+function isAllowedContentType(ct, prefixes) {
+    if (!ct)
+        return false;
+    const lower = ct.toLowerCase();
+    return prefixes.some((p) => lower.startsWith(p));
+}
+/**
+ * Issue a GET, follow redirects manually, cap byte count, enforce timeout
+ * and content-type. Returns the decoded body as a UTF-8 string.
+ */
+export async function safeFetch(rawUrl, options = {}) {
+    const fetchImpl = options.fetchImpl ?? globalThis.fetch;
+    if (!fetchImpl) {
+        throw new SafeFetchError("no fetch implementation available", "no-fetch");
+    }
+    const timeoutMs = options.timeoutMs ?? SAFE_FETCH_DEFAULTS.timeoutMs;
+    const maxBytes = options.maxBytes ?? SAFE_FETCH_DEFAULTS.maxBytes;
+    const maxRedirects = options.maxRedirects ?? SAFE_FETCH_DEFAULTS.maxRedirects;
+    const allowedPrefixes = options.allowedContentTypePrefixes ?? DEFAULT_ALLOWED_PREFIXES;
+    let currentUrl;
+    try {
+        currentUrl = new URL(rawUrl);
+    }
+    catch {
+        throw new SafeFetchError(`invalid url '${rawUrl}'`, "bad-url");
+    }
+    assertHttpScheme(currentUrl);
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), timeoutMs);
+    try {
+        for (let hop = 0; hop <= maxRedirects; hop++) {
+            const response = await fetchImpl(currentUrl.toString(), {
+                method: "GET",
+                redirect: "manual",
+                signal: controller.signal,
+                headers: { "user-agent": "agentic-pi/web-search" },
+            });
+            const status = response.status;
+            if (status >= 300 && status < 400) {
+                const loc = response.headers.get("location");
+                if (!loc) {
+                    throw new SafeFetchError(`redirect (${status}) without Location header`, "bad-redirect", status);
+                }
+                if (hop === maxRedirects) {
+                    throw new SafeFetchError(`too many redirects (>${maxRedirects})`, "too-many-redirects");
+                }
+                try {
+                    currentUrl = new URL(loc, currentUrl);
+                }
+                catch {
+                    throw new SafeFetchError(`invalid redirect target '${loc}'`, "bad-url");
+                }
+                assertHttpScheme(currentUrl);
+                // Drain/close any body the redirect carried, just in case.
+                try {
+                    await response.body?.cancel();
+                }
+                catch { /* ignore */ }
+                continue;
+            }
+            if (status >= 400) {
+                try {
+                    await response.body?.cancel();
+                }
+                catch { /* ignore */ }
+                throw new SafeFetchError(`http ${status}`, "http-error", status);
+            }
+            const contentType = response.headers.get("content-type") ?? undefined;
+            if (!isAllowedContentType(contentType, allowedPrefixes)) {
+                try {
+                    await response.body?.cancel();
+                }
+                catch { /* ignore */ }
+                throw new SafeFetchError(`disallowed content-type '${contentType ?? "(none)"}'`, "bad-content-type", status);
+            }
+            const body = await readCapped(response, maxBytes);
+            return {
+                status,
+                contentType,
+                body,
+                finalUrl: currentUrl.toString(),
+            };
+        }
+        // Unreachable — the for-loop returns or throws every path.
+        throw new SafeFetchError("redirect loop fell through", "internal");
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
+async function readCapped(response, maxBytes) {
+    // Prefer streaming so we can abort when the cap is hit without buffering
+    // the entire body first.
+    if (response.body && typeof response.body.getReader === "function") {
+        const reader = response.body.getReader();
+        const chunks = [];
+        let total = 0;
+        while (true) {
+            const { done, value } = await reader.read();
+            if (done)
+                break;
+            if (!value)
+                continue;
+            total += value.byteLength;
+            if (total > maxBytes) {
+                try {
+                    await reader.cancel();
+                }
+                catch { /* ignore */ }
+                throw new SafeFetchError(`response exceeded ${maxBytes} bytes`, "too-large");
+            }
+            chunks.push(value);
+        }
+        const buf = new Uint8Array(total);
+        let offset = 0;
+        for (const c of chunks) {
+            buf.set(c, offset);
+            offset += c.byteLength;
+        }
+        return new TextDecoder("utf-8", { fatal: false }).decode(buf);
+    }
+    // Fallback: text() without streaming cap — only triggers when the
+    // injected fetch returns a stub Response.
+    const text = await response.text();
+    if (text.length > maxBytes) {
+        throw new SafeFetchError(`response exceeded ${maxBytes} bytes`, "too-large");
+    }
+    return text;
+}
+//# sourceMappingURL=safe-fetch.js.map

package/dist/extensions/web-search/safe-fetch.js.map

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

package/dist/extensions/web-search/selection.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Provider selection logic — pure, no IO, easy to unit-test.
+ *
+ * Resolution order:
+ *   1. config.webSearch === false   → skipped (disabled-by-flag).
+ *   2. Explicit provider (config.webSearchProvider OR WEB_SEARCH_PROVIDER env):
+ *        - key present → selected.
+ *        - key missing → skipped (no-credentials) naming the env var.
+ *   3. Auto: scan env keys in fixed priority Tavily → Exa → Brave.
+ *        - first hit wins; if more than one is set, attach an advisory
+ *          message so the user can override via WEB_SEARCH_PROVIDER.
+ *   4. None present → skipped (no-credentials), silent.
+ *   5. Unknown explicit provider name → throw (config error).
+ */
+import { type ProviderName, type WebSearchSkipReason } from "./types.js";
+export interface SelectionInput {
+    /** When false, force-skip with reason `disabled-by-flag`. */
+    webSearch: boolean;
+    /** Explicit provider from --web-search-provider (overrides env). */
+    webSearchProvider?: string;
+    /** Process env or test override. */
+    env: Record<string, string | undefined>;
+}
+export interface SelectedProvider {
+    status: "configured";
+    provider: ProviderName;
+    apiKey: string;
+    /** Optional advisory note (e.g. multi-key collision). */
+    message?: string;
+}
+export interface SkippedProvider {
+    status: "skipped";
+    reason: WebSearchSkipReason;
+    message?: string;
+    /** Echoed back when the user explicitly asked for one. */
+    provider?: ProviderName;
+}
+export type SelectionResult = SelectedProvider | SkippedProvider;
+/** env var name that holds each provider's key. */
+export declare const PROVIDER_ENV_VAR: Record<ProviderName, string>;
+export declare function isProviderName(s: string): s is ProviderName;
+export declare function selectProvider(input: SelectionInput): SelectionResult;

package/dist/extensions/web-search/selection.js

@@ -0,0 +1,64 @@
+/**
+ * Provider selection logic — pure, no IO, easy to unit-test.
+ *
+ * Resolution order:
+ *   1. config.webSearch === false   → skipped (disabled-by-flag).
+ *   2. Explicit provider (config.webSearchProvider OR WEB_SEARCH_PROVIDER env):
+ *        - key present → selected.
+ *        - key missing → skipped (no-credentials) naming the env var.
+ *   3. Auto: scan env keys in fixed priority Tavily → Exa → Brave.
+ *        - first hit wins; if more than one is set, attach an advisory
+ *          message so the user can override via WEB_SEARCH_PROVIDER.
+ *   4. None present → skipped (no-credentials), silent.
+ *   5. Unknown explicit provider name → throw (config error).
+ */
+import { PROVIDER_NAMES, } from "./types.js";
+/** env var name that holds each provider's key. */
+export const PROVIDER_ENV_VAR = {
+    tavily: "TAVILY_API_KEY",
+    exa: "EXA_API_KEY",
+    brave: "BRAVE_SEARCH_API_KEY",
+};
+/** Priority order for auto-detection. */
+const AUTO_PRIORITY = ["tavily", "exa", "brave"];
+export function isProviderName(s) {
+    return PROVIDER_NAMES.includes(s);
+}
+export function selectProvider(input) {
+    if (input.webSearch === false) {
+        return { status: "skipped", reason: "disabled-by-flag" };
+    }
+    const envExplicit = input.env.WEB_SEARCH_PROVIDER?.trim();
+    const explicit = input.webSearchProvider ?? envExplicit;
+    if (explicit) {
+        if (!isProviderName(explicit)) {
+            throw new Error(`Unknown web-search provider '${explicit}'. Expected one of: ${PROVIDER_NAMES.join(", ")}`);
+        }
+        const envVar = PROVIDER_ENV_VAR[explicit];
+        const apiKey = input.env[envVar]?.trim();
+        if (!apiKey) {
+            return {
+                status: "skipped",
+                reason: "no-credentials",
+                provider: explicit,
+                message: `--web-search-provider=${explicit} set but ${envVar} is empty`,
+            };
+        }
+        return { status: "configured", provider: explicit, apiKey };
+    }
+    const present = AUTO_PRIORITY.filter((p) => (input.env[PROVIDER_ENV_VAR[p]] ?? "").trim().length > 0);
+    if (present.length === 0) {
+        return { status: "skipped", reason: "no-credentials" };
+    }
+    const chosen = present[0];
+    const message = present.length > 1
+        ? `multiple provider keys present (${present.join(", ")}); using ${chosen} — set WEB_SEARCH_PROVIDER to override`
+        : undefined;
+    return {
+        status: "configured",
+        provider: chosen,
+        apiKey: input.env[PROVIDER_ENV_VAR[chosen]].trim(),
+        message,
+    };
+}
+//# sourceMappingURL=selection.js.map

package/dist/extensions/web-search/selection.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"selection.js","sourceRoot":"","sources":["../../../src/extensions/web-search/selection.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,EACL,cAAc,GAGf,MAAM,YAAY,CAAC;AA6BpB,mDAAmD;AACnD,MAAM,CAAC,MAAM,gBAAgB,GAAiC;IAC5D,MAAM,EAAE,gBAAgB;IACxB,GAAG,EAAE,aAAa;IAClB,KAAK,EAAE,sBAAsB;CAC9B,CAAC;AAEF,yCAAyC;AACzC,MAAM,aAAa,GAA4B,CAAC,QAAQ,EAAE,KAAK,EAAE,OAAO,CAAC,CAAC;AAE1E,MAAM,UAAU,cAAc,CAAC,CAAS;IACtC,OAAQ,cAAoC,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC;AAC3D,CAAC;AAED,MAAM,UAAU,cAAc,CAAC,KAAqB;IAClD,IAAI,KAAK,CAAC,SAAS,KAAK,KAAK,EAAE,CAAC;QAC9B,OAAO,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,kBAAkB,EAAE,CAAC;IAC3D,CAAC;IAED,MAAM,WAAW,GAAG,KAAK,CAAC,GAAG,CAAC,mBAAmB,EAAE,IAAI,EAAE,CAAC;IAC1D,MAAM,QAAQ,GAAG,KAAK,CAAC,iBAAiB,IAAI,WAAW,CAAC;IAExD,IAAI,QAAQ,EAAE,CAAC;QACb,IAAI,CAAC,cAAc,CAAC,QAAQ,CAAC,EAAE,CAAC;YAC9B,MAAM,IAAI,KAAK,CACb,gCAAgC,QAAQ,uBAAuB,cAAc,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAC3F,CAAC;QACJ,CAAC;QACD,MAAM,MAAM,GAAG,gBAAgB,CAAC,QAAQ,CAAC,CAAC;QAC1C,MAAM,MAAM,GAAG,KAAK,CAAC,GAAG,CAAC,MAAM,CAAC,EAAE,IAAI,EAAE,CAAC;QACzC,IAAI,CAAC,MAAM,EAAE,CAAC;YACZ,OAAO;gBACL,MAAM,EAAE,SAAS;gBACjB,MAAM,EAAE,gBAAgB;gBACxB,QAAQ,EAAE,QAAQ;gBAClB,OAAO,EAAE,yBAAyB,QAAQ,YAAY,MAAM,WAAW;aACxE,CAAC;QACJ,CAAC;QACD,OAAO,EAAE,MAAM,EAAE,YAAY,EAAE,QAAQ,EAAE,QAAQ,EAAE,MAAM,EAAE,CAAC;IAC9D,CAAC;IAED,MAAM,OAAO,GAAG,aAAa,CAAC,MAAM,CAClC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,KAAK,CAAC,GAAG,CAAC,gBAAgB,CAAC,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE,CAAC,MAAM,GAAG,CAAC,CAChE,CAAC;IAEF,IAAI,OAAO,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACzB,OAAO,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,gBAAgB,EAAE,CAAC;IACzD,CAAC;IAED,MAAM,MAAM,GAAG,OAAO,CAAC,CAAC,CAAC,CAAC;IAC1B,MAAM,OAAO,GACX,OAAO,CAAC,MAAM,GAAG,CAAC;QAChB,CAAC,CAAC,mCAAmC,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,YAAY,MAAM,wCAAwC;QACjH,CAAC,CAAC,SAAS,CAAC;IAEhB,OAAO;QACL,MAAM,EAAE,YAAY;QACpB,QAAQ,EAAE,MAAM;QAChB,MAAM,EAAE,KAAK,CAAC,GAAG,CAAC,gBAAgB,CAAC,MAAM,CAAC,CAAE,CAAC,IAAI,EAAE;QACnD,OAAO;KACR,CAAC;AACJ,CAAC"}

package/dist/extensions/web-search/tools.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Native Pi tools `web_search` and `web_fetch`.
+ *
+ * Both tools follow the GitHub-extension convention: errors return a
+ * structured JSON payload (instead of throwing) and the JSON payload is
+ * stuffed into a single text content block via `jsonContent`. The agent
+ * sees the active provider name in every result so it can attribute
+ * findings.
+ */
+import { type ToolDefinition } from "@earendil-works/pi-coding-agent";
+import type { RateLimiter } from "./rate-limit.js";
+import type { Provider } from "./types.js";
+export declare function buildWebSearchTools(provider: Provider, limiter: RateLimiter): ToolDefinition<any>[];