agentic-pi 0.2.2 → 0.2.4

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>[];

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

@@ -0,0 +1,136 @@
+/**
+ * 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 } from "@sinclair/typebox";
+import { defineTool } from "@earendil-works/pi-coding-agent";
+import { extractTitle, htmlToText } from "./extract.js";
+import { safeFetch, SafeFetchError } from "./safe-fetch.js";
+const MAX_RESULTS = 10;
+const DEFAULT_RESULTS = 5;
+function jsonContent(data) {
+    return {
+        content: [{ type: "text", text: JSON.stringify(data, null, 2) }],
+        details: {},
+    };
+}
+function errorPayload(provider, err, hint) {
+    const e = err;
+    return {
+        error: e?.message ?? String(err),
+        provider,
+        code: e?.code,
+        status: e?.status,
+        hint: hint ?? null,
+    };
+}
+function rateLimitPayload(provider) {
+    return {
+        error: "web-search rate limit reached for this run",
+        provider,
+        code: "rate-limited",
+        hint: "Increase the budget with --web-search-max-calls (CLI) or webSearchMaxCalls (run options), " +
+            "or summarize earlier findings instead of searching again.",
+    };
+}
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export function buildWebSearchTools(provider, limiter) {
+    const searchSchema = Type.Object({
+        query: Type.String({ description: "Search query", minLength: 1 }),
+        max_results: Type.Optional(Type.Integer({
+            description: `Max results to return (1-${MAX_RESULTS}, default ${DEFAULT_RESULTS}).`,
+            minimum: 1,
+            maximum: MAX_RESULTS,
+        })),
+        include_domains: Type.Optional(Type.Array(Type.String(), {
+            description: "Only return results whose URL host matches one of these domains.",
+        })),
+        exclude_domains: Type.Optional(Type.Array(Type.String(), {
+            description: "Drop results whose URL host matches any of these domains.",
+        })),
+        search_depth: Type.Optional(Type.Union([Type.Literal("basic"), Type.Literal("advanced")], {
+            description: "Advisory: providers that support a depth knob honor it; Brave ignores.",
+        })),
+        include_content: Type.Optional(Type.Boolean({
+            description: "Ask the provider to return extracted page content inline when supported (Tavily, Exa). Brave ignores.",
+        })),
+    });
+    const fetchSchema = Type.Object({
+        url: Type.String({
+            description: "Absolute http:// or https:// URL to download and extract readable text from.",
+        }),
+    });
+    const searchTool = defineTool({
+        name: "web_search",
+        label: "web_search",
+        description: `Search the web via ${provider.name}. Returns a ranked list of {title, url, snippet, ...} ` +
+            `entries plus (for some providers) an optional 'answer' summary. Use this when you need ` +
+            `external context not available in the local workspace.`,
+        parameters: searchSchema,
+        async execute(_id, params) {
+            if (!limiter.consume()) {
+                return jsonContent(rateLimitPayload(provider.name));
+            }
+            const max = Math.min(MAX_RESULTS, params.max_results ?? DEFAULT_RESULTS);
+            try {
+                const result = await provider.search({
+                    query: params.query,
+                    maxResults: max,
+                    includeDomains: params.include_domains,
+                    excludeDomains: params.exclude_domains,
+                    searchDepth: params.search_depth,
+                    includeContent: params.include_content,
+                });
+                return jsonContent(result);
+            }
+            catch (err) {
+                return jsonContent(errorPayload(provider.name, err));
+            }
+        },
+    });
+    const fetchTool = defineTool({
+        name: "web_fetch",
+        label: "web_fetch",
+        description: `Download a single web page (http/https only) and return its extracted readable text. ` +
+            `Uses ${provider.fetch ? `${provider.name}'s content endpoint` : "a generic safe-fetch with HTML stripping"}. ` +
+            `Body is capped at ~1 MiB and extracted text at ~200 KiB.`,
+        parameters: fetchSchema,
+        async execute(_id, params) {
+            if (!limiter.consume()) {
+                return jsonContent(rateLimitPayload(provider.name));
+            }
+            try {
+                if (provider.fetch) {
+                    const result = await provider.fetch({ url: params.url });
+                    return jsonContent(result);
+                }
+                const r = await safeFetch(params.url);
+                const text = htmlToText(r.body);
+                const title = extractTitle(r.body);
+                return jsonContent({
+                    provider: "safe-fetch",
+                    url: params.url,
+                    resolvedUrl: r.finalUrl,
+                    status: r.status,
+                    contentType: r.contentType,
+                    title,
+                    text,
+                });
+            }
+            catch (err) {
+                const code = err instanceof SafeFetchError ? err.code : undefined;
+                return jsonContent({
+                    ...errorPayload(provider.name, err),
+                    code: code ?? err?.code,
+                });
+            }
+        },
+    });
+    return [searchTool, fetchTool];
+}
+//# sourceMappingURL=tools.js.map

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

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

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

@@ -0,0 +1,65 @@
+/**
+ * Shared types for the web-search extension.
+ *
+ * The same `Provider` interface is implemented by tavily / brave / exa.
+ * Callers of the extension treat all three uniformly: the tool layer never
+ * branches on provider name except to surface `provider` in the result
+ * payload.
+ */
+export type ProviderName = "tavily" | "brave" | "exa";
+export declare const PROVIDER_NAMES: readonly ProviderName[];
+export interface SearchParams {
+    query: string;
+    /** Hard-capped at 10 by the tool layer. */
+    maxResults: number;
+    includeDomains?: string[];
+    excludeDomains?: string[];
+    /** Advisory: providers that have a "depth" knob map this; Brave ignores. */
+    searchDepth?: "basic" | "advanced";
+    /** Advisory: providers that can return extracted content do; Brave ignores. */
+    includeContent?: boolean;
+}
+export interface SearchResultItem {
+    title: string;
+    url: string;
+    snippet?: string;
+    content?: string;
+    score?: number;
+    publishedDate?: string;
+}
+export interface NormalizedSearchResult {
+    provider: ProviderName;
+    query: string;
+    results: SearchResultItem[];
+    /** Optional provider-supplied summary answer (Tavily can return this). */
+    answer?: string;
+}
+export interface FetchParams {
+    url: string;
+}
+export interface NormalizedFetchResult {
+    provider: ProviderName | "safe-fetch";
+    url: string;
+    /** Final URL after redirects (when known). */
+    resolvedUrl?: string;
+    status?: number;
+    contentType?: string;
+    /** Extracted readable text. Capped at ~200 KiB upstream. */
+    text: string;
+    title?: string;
+}
+/** Minimal fetch signature used by providers and safe-fetch for DI in tests. */
+export type FetchImpl = (input: string | URL, init?: RequestInit) => Promise<Response>;
+export interface Provider {
+    readonly name: ProviderName;
+    /** True if the provider's search endpoint can return extracted page content inline. */
+    readonly supportsExtractedContent: boolean;
+    search(params: SearchParams): Promise<NormalizedSearchResult>;
+    /**
+     * Optional native fetch endpoint. Tavily has /extract; Exa has /contents;
+     * Brave has nothing here. When omitted, the tool layer falls back to
+     * `safeFetch` + the HTML extractor.
+     */
+    fetch?(params: FetchParams): Promise<NormalizedFetchResult>;
+}
+export type WebSearchSkipReason = "disabled-by-flag" | "no-credentials" | "invalid-config";

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

@@ -0,0 +1,10 @@
+/**
+ * Shared types for the web-search extension.
+ *
+ * The same `Provider` interface is implemented by tavily / brave / exa.
+ * Callers of the extension treat all three uniformly: the tool layer never
+ * branches on provider name except to surface `provider` in the result
+ * payload.
+ */
+export const PROVIDER_NAMES = ["tavily", "brave", "exa"];
+//# sourceMappingURL=types.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../../src/extensions/web-search/types.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAIH,MAAM,CAAC,MAAM,cAAc,GAA4B,CAAC,QAAQ,EAAE,OAAO,EAAE,KAAK,CAAC,CAAC"}

package/dist/run.d.ts

@@ -71,6 +71,36 @@ export interface RunOptions {
      * Ignored when `sandbox: "none"`.
      */
     allowedHttpHosts?: string[] | null;
+    /**
+     * Web-search extension toggle. Default: `true` (auto-enables when a
+     * provider API key env var is present). Set to `false` to suppress the
+     * `web_search` / `web_fetch` tools entirely.
+     */
+    webSearch?: boolean;
+    /**
+     * Force a specific web-search provider: `"tavily" | "brave" | "exa"`.
+     * Overrides env-var-based auto-detection. The matching API key env var
+     * (`TAVILY_API_KEY`, `BRAVE_SEARCH_API_KEY`, `EXA_API_KEY`) must still
+     * be present; otherwise the extension skips with a warning.
+     */
+    webSearchProvider?: "tavily" | "brave" | "exa";
+    /**
+     * Per-run cap on combined `web_search` + `web_fetch` calls. Default: 30.
+     * Once exceeded, further calls return a structured rate-limit error
+     * payload (the agent can recover).
+     */
+    webSearchMaxCalls?: number;
+    /**
+     * File-search extension (FFF) toggle. Default: `true` — bundled and
+     * enabled for every run. Set to `false` to fall back to Pi's built-in
+     * `find`/`grep`.
+     */
+    fileSearch?: boolean;
+    /**
+     * FFF mode. Default: `"override"` (FFF replaces built-in `find`/`grep`
+     * under the same names). The `PI_FFF_MODE` env var, if set, wins.
+     */
+    fileSearchMode?: "override" | "tools-only" | "tools-and-ui";
     /**
      * Called for every emitted JSONL record in order. Same shape that the
      * CLI writes to stdout, with `sessionId` and `timestamp` already injected.
@@ -143,6 +173,21 @@ export interface RunResult {
         profile?: string;
         toolCount: number;
     };
+    webSearch?: {
+        status: "configured" | "skipped";
+        reason?: string;
+        message?: string;
+        provider?: string;
+        toolCount: number;
+        maxCalls?: number;
+    };
+    fileSearch?: {
+        status: "configured" | "skipped";
+        reason?: string;
+        message?: string;
+        mode?: string;
+        toolCount: number;
+    };
     /** Every JSONL record the run emitted, in order. */
     records: EmitterRecord[];
     /** Warnings that would have gone to stderr in CLI mode. */