pi-agent-browser-native 0.9.3 → 0.9.5

package/dist/extensions/agent-browser/lib/tool-surface.js

@@ -1,24 +1,40 @@
 import { Text } from "@earendil-works/pi-tui";
 import { formatAgentBrowserRenderCall } from "./pi-tool-rendering.js";
 import { JsonSchema } from "./json-schema.js";
-import { AGENT_BROWSER_NAMESPACE, AGENT_BROWSER_OUTPUT_SCHEMA, finalizeAgentBrowserNativeResult } from "./native-output.js";
+import { AGENT_BROWSER_NAMESPACE, AGENT_BROWSER_OUTPUT_SCHEMA, finalizeAgentBrowserNativeResult, } from "./native-output.js";
 import { AGENT_BROWSER_PARAMS, AGENT_BROWSER_CODE_PARAMS, AGENT_BROWSER_ACTION_PARAMS, AGENT_BROWSER_QA_PARAMS, AGENT_BROWSER_ELECTRON_PARAMS, AGENT_BROWSER_SOURCE_PARAMS, AGENT_BROWSER_NETWORK_SOURCE_PARAMS, AGENT_BROWSER_TOOLS_PARAMS, } from "./input-modes/params.js";
 export const AGENT_BROWSER_TOOL_INVENTORY = {
-    action: { name: "agent_browser_action", description: "Click, check, fill, or select a unique accessible target using stable locators or current refs." },
-    qa: { name: "agent_browser_qa", description: "Check a URL or attached page with visible assertions and a diagnostic pass/fail verdict." },
-    electron: { name: "agent_browser_electron", description: "Discover, launch, probe, and clean up owned Electron desktop applications." },
-    source: { name: "agent_browser_source", description: "Find experimental DOM/React/local-source candidates with a bounded workspace scan." },
-    network: { name: "agent_browser_network_source", description: "Correlate failed requests with initiator and local-source candidates." },
+    action: {
+        name: "agent_browser_action",
+        description: "Click, check, fill, or select a unique accessible target using stable locators or current refs.",
+    },
+    qa: {
+        name: "agent_browser_qa",
+        description: "Check a URL or attached page with visible assertions and a diagnostic pass/fail verdict.",
+    },
+    electron: {
+        name: "agent_browser_electron",
+        description: "Discover, launch, probe, and clean up owned Electron desktop applications.",
+    },
+    source: {
+        name: "agent_browser_source",
+        description: "Find experimental DOM/React/local-source candidates with a bounded workspace scan.",
+    },
+    network: {
+        name: "agent_browser_network_source",
+        description: "Correlate failed requests with initiator and local-source candidates.",
+    },
 };
 export const AGENT_BROWSER_INSTRUCTION_GROUP = {
     name: "browser",
     description: "Search the web, browse and interact with pages, verify browser UI, and inspect Electron apps.",
 };
 const advancedNames = new Set(Object.values(AGENT_BROWSER_TOOL_INVENTORY).map(({ name }) => name));
-/** Register once; advanced calls adapt only their input shape and reuse the ordinary executor. */
-export function registerAgentBrowserToolSurface(pi, options) {
-    const execute = async (id, params, signal, onUpdate, ctx) => finalizeAgentBrowserNativeResult(await options.execute(id, params, signal, onUpdate, ctx), params);
-    const nativeOutput = { namespace: AGENT_BROWSER_NAMESPACE, outputSchema: AGENT_BROWSER_OUTPUT_SCHEMA };
+const nativeOutput = {
+    namespace: AGENT_BROWSER_NAMESPACE,
+    outputSchema: AGENT_BROWSER_OUTPUT_SCHEMA,
+};
+function registerCoreTools(pi, options, execute) {
     pi.registerTool({
         name: "agent_browser",
         ...nativeOutput,
@@ -47,6 +63,8 @@ export function registerAgentBrowserToolSurface(pi, options) {
         },
         renderResult: options.renderResult,
     });
+}
+function registerActionTool(pi, options, execute) {
     pi.registerTool({
         ...AGENT_BROWSER_TOOL_INVENTORY.action,
         ...nativeOutput,
@@ -59,6 +77,8 @@ export function registerAgentBrowserToolSurface(pi, options) {
             return execute(id, { semanticAction, outputPath, timeoutMs }, signal, onUpdate, ctx);
         },
     });
+}
+function registerQaTool(pi, options, execute) {
     pi.registerTool({
         ...AGENT_BROWSER_TOOL_INVENTORY.qa,
         ...nativeOutput,
@@ -71,6 +91,8 @@ export function registerAgentBrowserToolSurface(pi, options) {
             return execute(id, { qa, outputPath, timeoutMs, sessionMode }, signal, onUpdate, ctx);
         },
     });
+}
+function registerElectronTool(pi, options, execute) {
     pi.registerTool({
         ...AGENT_BROWSER_TOOL_INVENTORY.electron,
         ...nativeOutput,
@@ -83,6 +105,8 @@ export function registerAgentBrowserToolSurface(pi, options) {
             return execute(id, { electron, outputPath }, signal, onUpdate, ctx);
         },
     });
+}
+function registerSourceTools(pi, options, execute) {
     pi.registerTool({
         ...AGENT_BROWSER_TOOL_INVENTORY.source,
         ...nativeOutput,
@@ -107,13 +131,24 @@ export function registerAgentBrowserToolSurface(pi, options) {
             return execute(id, { networkSourceLookup, outputPath, timeoutMs, sessionMode }, signal, onUpdate, ctx);
         },
     });
+}
+function toolStatus(available, active) {
+    if (!available) {
+        return "unavailable in this Pi tool selection";
+    }
+    return active ? "active" : "inactive";
+}
+function registerToolLoader(pi) {
     pi.registerTool({
         name: "agent_browser_tools",
         namespace: AGENT_BROWSER_NAMESPACE,
         outputSchema: JsonSchema.Object({
             inventory: JsonSchema.Array(JsonSchema.Object({
-                key: JsonSchema.String(), name: JsonSchema.String(), description: JsonSchema.String(),
-                available: JsonSchema.Boolean(), active: JsonSchema.Boolean(),
+                key: JsonSchema.String(),
+                name: JsonSchema.String(),
+                description: JsonSchema.String(),
+                available: JsonSchema.Boolean(),
+                active: JsonSchema.Boolean(),
             })),
             added: JsonSchema.Array(JsonSchema.String()),
         }),
@@ -124,46 +159,81 @@ export function registerAgentBrowserToolSurface(pi, options) {
         async execute(_id, params) {
             const available = new Set(pi.getAllTools().map(({ name }) => name));
             const active = new Set(pi.getActiveTools());
-            const added = (params.enable ?? []).map((key) => AGENT_BROWSER_TOOL_INVENTORY[key].name)
+            const added = (params.enable ?? [])
+                .map((key) => AGENT_BROWSER_TOOL_INVENTORY[key].name)
                 .filter((name) => available.has(name) && !active.has(name));
-            if (added.length > 0)
+            if (added.length > 0) {
                 pi.setActiveTools([...new Set([...active, ...added])]);
+            }
             const current = new Set(pi.getActiveTools());
             const inventory = Object.entries(AGENT_BROWSER_TOOL_INVENTORY).map(([key, tool]) => ({
-                key, ...tool, available: available.has(tool.name), active: current.has(tool.name),
+                key,
+                name: tool.name,
+                description: tool.description,
+                available: available.has(tool.name),
+                active: current.has(tool.name),
             }));
             return {
-                content: [{ type: "text", text: inventory.map((tool) => `${tool.key}: ${tool.name} (${!tool.available ? "unavailable in this Pi tool selection" : tool.active ? "active" : "inactive"}) — ${tool.description}`).join("\n") }],
+                content: [
+                    {
+                        type: "text",
+                        text: inventory
+                            .map((tool) => `${tool.key}: ${tool.name} (${toolStatus(tool.available, tool.active)}) — ${tool.description}`)
+                            .join("\n"),
+                    },
+                ],
                 details: { inventory, added: [...new Set(added)] },
                 structuredContent: { inventory, added: [...new Set(added)] },
             };
         },
     });
+}
+function hasExplicitToolSelection() {
+    const argv = process.argv.slice(2);
+    const delimiter = argv.indexOf("--");
+    return (delimiter < 0 ? argv : argv.slice(0, delimiter)).some((arg) => arg === "--tools" || arg === "-t");
+}
+function registerAdvancedToolReplay(pi) {
     pi.on("session_start", async (_event, ctx) => {
         // ponytail: official 1.0 SDK supplies initialActiveToolNames on resume, bypassing
         // native transcript restoration. Remove this additive fallback once the supported SDK restores it.
-        const argv = process.argv.slice(2);
-        const delimiter = argv.indexOf("--");
-        if ((delimiter < 0 ? argv : argv.slice(0, delimiter)).some((arg) => arg === "--tools" || arg === "-t"))
+        if (hasExplicitToolSelection()) {
             return;
+        }
         // A host-filtered catalog is an explicit selection, not our default surface.
         const available = new Set(pi.getAllTools().map(({ name }) => name));
-        if (!["agent_browser", "agent_browser_code", "agent_browser_tools", ...advancedNames].every(name => available.has(name)))
+        if (!["agent_browser", "agent_browser_code", "agent_browser_tools", ...advancedNames].every((name) => available.has(name))) {
             return;
+        }
         // Native dynamic imports bypass Pi's host-package aliases in consumer installs.
         // Only tool names are needed; replay native deltas without requiring the optional pi-ai peer.
         const restored = new Set();
         for (const message of ctx.sessionManager.buildSessionProjection().messages) {
-            if (message.role !== "system")
+            if (message.role !== "system") {
                 continue;
-            for (const removed of message.toolsRemoved ?? [])
+            }
+            for (const removed of message.toolsRemoved ?? []) {
                 restored.delete(removed.name);
-            for (const added of message.toolsAdded ?? [])
+            }
+            for (const added of message.toolsAdded ?? []) {
                 restored.add(added.name);
+            }
         }
         const active = new Set(pi.getActiveTools());
         const added = [...restored].filter((name) => advancedNames.has(name) && available.has(name) && !active.has(name));
-        if (added.length > 0)
+        if (added.length > 0) {
             pi.setActiveTools([...active, ...added]);
+        }
     });
 }
+/** Register once; adapters retain native execution, output, activation, and replay contracts. */
+export function registerAgentBrowserToolSurface(pi, options) {
+    const execute = async (id, params, signal, onUpdate, ctx) => finalizeAgentBrowserNativeResult(await options.execute(id, params, signal, onUpdate, ctx), params);
+    registerCoreTools(pi, options, execute);
+    registerActionTool(pi, options, execute);
+    registerQaTool(pi, options, execute);
+    registerElectronTool(pi, options, execute);
+    registerSourceTools(pi, options, execute);
+    registerToolLoader(pi);
+    registerAdvancedToolReplay(pi);
+}

package/dist/extensions/agent-browser/lib/upstream-version.js

@@ -6,9 +6,10 @@ export function parseAgentBrowserVersionOutput(stdout) {
 }
 export function getAgentBrowserVersionValidationError(stdout) {
     const observed = parseAgentBrowserVersionOutput(stdout);
-    if (observed && isSupportedAgentBrowserVersion(observed))
+    if (observed !== undefined && isSupportedAgentBrowserVersion(observed)) {
         return undefined;
-    return observed
+    }
+    return observed !== undefined
         ? `Installed agent-browser ${observed} is unsupported; stable versions must be at least ${MINIMUM_AGENT_BROWSER_VERSION_LABEL}. Install ${TARGET_AGENT_BROWSER_VERSION_LABEL} (recommended), run pi-agent-browser-doctor, then reload Pi.`
         : `agent-browser --version returned an unrecognized value; expected ${SUPPORTED_AGENT_BROWSER_VERSION_LABEL}. Run pi-agent-browser-doctor and install a supported upstream version.`;
 }

package/dist/extensions/agent-browser/lib/web-search-providers.js

@@ -0,0 +1,193 @@
+import { isRecord } from "./parsing.js";
+import { fetchSearchJson, SEARCH_REQUEST_TIMEOUT_MS } from "./web-search-request.js";
+import { cleanSearchText, normalizeBraveSearchResult, normalizeExaSearchResult, parseBraveSearchResponse, parseExaSearchResponse, } from "./web-search-results.js";
+const BRAVE_SEARCH_ENDPOINT = "https://api.search.brave.com/res/v1/web/search";
+const EXA_SEARCH_ENDPOINT = "https://api.exa.ai/search";
+const EXA_DYNAMIC_HIGHLIGHTS_BETA = "dynamic-highlights-2026-08-28";
+export const EXA_SEARCH_SYSTEM_PROMPT = "Prefer primary, official sources. Respect any requested version or date. Avoid duplicate or equivalent results.";
+/** Local validation/config failures, not provider outages; reported as `validation-error`. */
+export class WebSearchLocalError extends Error {
+}
+export function buildBraveSearchUrl(params) {
+    const url = new URL(BRAVE_SEARCH_ENDPOINT);
+    url.searchParams.set("q", params.query);
+    url.searchParams.set("count", String(params.count));
+    url.searchParams.set("offset", String(params.offset));
+    if (params.country !== undefined && params.country.length > 0) {
+        url.searchParams.set("country", params.country.toUpperCase());
+    }
+    if (params.searchLang !== undefined && params.searchLang.length > 0) {
+        url.searchParams.set("search_lang", params.searchLang);
+    }
+    if (params.safesearch !== undefined) {
+        url.searchParams.set("safesearch", params.safesearch);
+    }
+    if (params.freshness !== undefined) {
+        url.searchParams.set("freshness", params.freshness);
+    }
+    return url;
+}
+const FRESHNESS_DAYS = { pd: 1, pw: 7, pm: 31, py: 365 };
+function getStartPublishedDate(freshness, now) {
+    if (freshness === undefined) {
+        return;
+    }
+    return new Date(now().getTime() - FRESHNESS_DAYS[freshness] * 24 * 60 * 60 * 1000).toISOString();
+}
+function hasEntries(values) {
+    return values !== undefined && values.length > 0;
+}
+function validateExaFilters(params, searchType) {
+    if (hasEntries(params.additionalQueries) && !searchType.startsWith("deep")) {
+        throw new WebSearchLocalError(`additionalQueries requires deep-lite, deep, or deep-reasoning; received ${searchType}.`);
+    }
+    if ((params.category === "company" || params.category === "people") &&
+        (params.freshness !== undefined || hasEntries(params.excludeDomains))) {
+        throw new WebSearchLocalError(`category ${params.category} cannot be combined with freshness or excludeDomains.`);
+    }
+}
+function exaContentFilters(params) {
+    return {
+        ...(hasEntries(params.includeDomains) ? { includeDomains: params.includeDomains } : {}),
+        ...(hasEntries(params.excludeDomains) ? { excludeDomains: params.excludeDomains } : {}),
+        ...(hasEntries(params.additionalQueries)
+            ? { additionalQueries: params.additionalQueries }
+            : {}),
+        ...(params.safesearch !== undefined && params.safesearch !== "off" ? { moderation: true } : {}),
+    };
+}
+export function buildExaSearchRequestBody(params, now = () => new Date()) {
+    const searchType = params.searchType ?? "auto";
+    validateExaFilters(params, searchType);
+    const startPublishedDate = getStartPublishedDate(params.freshness, now);
+    return {
+        query: params.query,
+        type: searchType,
+        numResults: Math.min(params.count + params.offset, 100),
+        contents: { highlights: params.highlightsDynamic === true ? { dynamic: true } : true },
+        systemPrompt: EXA_SEARCH_SYSTEM_PROMPT,
+        ...(params.category !== undefined ? { category: params.category } : {}),
+        ...(params.country !== undefined && params.country.length > 0
+            ? { userLocation: params.country.toUpperCase() }
+            : {}),
+        ...exaContentFilters(params),
+        ...(startPublishedDate !== undefined ? { startPublishedDate } : {}),
+    };
+}
+export async function fetchBraveSearchJson(url, apiKey, signal) {
+    const data = await fetchSearchJson({
+        cancelMessage: "Brave search cancelled",
+        init: { headers: { Accept: "application/json", "X-Subscription-Token": apiKey } },
+        invalidJsonMessage: "Brave search returned invalid JSON",
+        provider: "brave",
+        request: url,
+        signal,
+        timeoutMessage: "Brave search timed out",
+        timeoutMs: SEARCH_REQUEST_TIMEOUT_MS,
+    });
+    return parseBraveSearchResponse(data);
+}
+function getExaRequestTimeoutMs(searchType) {
+    switch (searchType) {
+        case "deep-lite":
+            return 45_000;
+        case "deep":
+            return 60_000;
+        case "deep-reasoning":
+            return 90_000;
+        case "auto":
+        case "fast":
+        case "instant":
+        case undefined:
+            return SEARCH_REQUEST_TIMEOUT_MS;
+    }
+}
+function usesDynamicHighlights(body) {
+    const contents = body.contents;
+    return (isRecord(contents) &&
+        !Array.isArray(contents) &&
+        isRecord(contents.highlights) &&
+        !Array.isArray(contents.highlights) &&
+        contents.highlights.dynamic === true);
+}
+export async function fetchExaSearchJson(body, apiKey, signal, timeoutMs = SEARCH_REQUEST_TIMEOUT_MS) {
+    const data = await fetchSearchJson({
+        cancelMessage: "Exa search cancelled",
+        init: {
+            body: JSON.stringify(body),
+            headers: {
+                Accept: "application/json",
+                "Content-Type": "application/json",
+                "x-api-key": apiKey,
+                ...(usesDynamicHighlights(body) ? { "Exa-Beta": EXA_DYNAMIC_HIGHLIGHTS_BETA } : {}),
+            },
+            method: "POST",
+        },
+        invalidJsonMessage: "Exa search returned invalid JSON",
+        provider: "exa",
+        request: EXA_SEARCH_ENDPOINT,
+        signal,
+        timeoutMessage: "Exa search timed out",
+        timeoutMs,
+    });
+    return parseExaSearchResponse(data);
+}
+const BRAVE_WEB_SEARCH_ADAPTER = {
+    provider: "brave",
+    buildRequest(params) {
+        // Brave offsets count pages; fetch the prefix and slice by result like Exa.
+        return buildBraveSearchUrl({ ...params, count: params.count + params.offset, offset: 0 });
+    },
+    fetchJson: fetchBraveSearchJson,
+    normalizeResponse(response, params) {
+        return {
+            results: (response.web?.results ?? [])
+                .map(normalizeBraveSearchResult)
+                .filter((result) => result !== undefined)
+                .slice(params.offset, params.offset + params.count),
+            returnedQuery: cleanSearchText(response.query?.altered, 300) ??
+                cleanSearchText(response.query?.original, 300) ??
+                params.query,
+        };
+    },
+};
+const EXA_WEB_SEARCH_ADAPTER = {
+    provider: "exa",
+    buildRequest(params) {
+        return {
+            body: buildExaSearchRequestBody(params),
+            timeoutMs: getExaRequestTimeoutMs(params.searchType ?? "auto"),
+        };
+    },
+    fetchJson(request, apiKey, signal) {
+        return fetchExaSearchJson(request.body, apiKey, signal, request.timeoutMs);
+    },
+    normalizeResponse(response, params) {
+        return {
+            extraDetails: {
+                requestId: cleanSearchText(response.requestId, 120),
+                searchType: params.searchType ?? "auto",
+            },
+            results: (response.results ?? [])
+                .map(normalizeExaSearchResult)
+                .filter((result) => result !== undefined)
+                .slice(params.offset, params.offset + params.count),
+            returnedQuery: params.query,
+        };
+    },
+};
+/** Build before queueing so local validation fails without consuming a request slot. */
+export function prepareWebSearchRequest(provider, params, apiKey, signal) {
+    if (provider === "exa") {
+        const request = EXA_WEB_SEARCH_ADAPTER.buildRequest(params);
+        return async () => {
+            const response = await EXA_WEB_SEARCH_ADAPTER.fetchJson(request, apiKey, signal);
+            return EXA_WEB_SEARCH_ADAPTER.normalizeResponse(response, params);
+        };
+    }
+    const request = BRAVE_WEB_SEARCH_ADAPTER.buildRequest(params);
+    return async () => {
+        const response = await BRAVE_WEB_SEARCH_ADAPTER.fetchJson(request, apiKey, signal);
+        return BRAVE_WEB_SEARCH_ADAPTER.normalizeResponse(response, params);
+    };
+}

package/dist/extensions/agent-browser/lib/web-search-request.js

@@ -0,0 +1,102 @@
+import { getProviderLabel } from "./web-search-results.js";
+export const SEARCH_REQUEST_TIMEOUT_MS = 15_000;
+export const WEB_SEARCH_MIN_REQUEST_INTERVAL_MS = 1_100;
+function sleepWithAbort(ms, signal) {
+    if (ms <= 0) {
+        return Promise.resolve();
+    }
+    if (signal?.aborted === true) {
+        const reason = signal.reason;
+        // A caller-owned abort reason may be non-Error; preserve the original reason.
+        // oxlint-disable-next-line typescript/prefer-promise-reject-errors
+        return Promise.reject(reason ?? new Error("Web search cancelled"));
+    }
+    return new Promise((resolve, reject) => {
+        const cleanup = () => signal?.removeEventListener("abort", abort);
+        const timeout = setTimeout(() => {
+            cleanup();
+            resolve();
+        }, ms);
+        const abort = () => {
+            clearTimeout(timeout);
+            cleanup();
+            const reason = signal?.reason;
+            // A caller-owned abort reason may be non-Error; preserve the original reason.
+            // oxlint-disable-next-line typescript/prefer-promise-reject-errors
+            reject(reason ?? new Error("Web search cancelled"));
+        };
+        signal?.addEventListener("abort", abort, { once: true });
+    });
+}
+export class WebSearchRequestGate {
+    lastRequestStartedAt = 0;
+    tail = Promise.resolve();
+    run(signal, task) {
+        const runTask = async () => {
+            const elapsedMs = this.lastRequestStartedAt === 0
+                ? WEB_SEARCH_MIN_REQUEST_INTERVAL_MS
+                : Date.now() - this.lastRequestStartedAt;
+            const waitMs = Math.max(0, WEB_SEARCH_MIN_REQUEST_INTERVAL_MS - elapsedMs);
+            if (waitMs > 0) {
+                await sleepWithAbort(waitMs, signal);
+            }
+            if (signal?.aborted === true) {
+                signal.throwIfAborted();
+            }
+            this.lastRequestStartedAt = Date.now();
+            return task();
+        };
+        const result = this.tail.then(runTask, runTask);
+        this.tail = result.catch(() => {
+            /* Failed requests release the queue; callers retain the original rejection. */
+        });
+        return result;
+    }
+}
+function formatSearchHttpError(options) {
+    const { provider, status } = options;
+    const providerLabel = getProviderLabel(provider);
+    if (status === 429) {
+        return `${providerLabel} search rate limit exceeded (HTTP 429). Do not issue parallel or repeated agent_browser_web_search calls; use one high-signal query, inspect those results, then wait before retrying or ask the user to adjust their ${providerLabel} API plan/limits.`;
+    }
+    if (status === 401 || status === 403) {
+        return `${providerLabel} search failed with HTTP ${status}: Check your API credential and permissions.`;
+    }
+    if (status >= 500) {
+        return `${providerLabel} search failed with HTTP ${status}: Provider unavailable; retry later.`;
+    }
+    return `${providerLabel} search failed with HTTP ${status}: Request rejected; check the search parameters.`;
+}
+export async function fetchSearchJson(options) {
+    if (options.signal?.aborted === true) {
+        options.signal.throwIfAborted();
+    }
+    const controller = new AbortController();
+    const timeout = setTimeout(() => controller.abort(new Error(options.timeoutMessage)), options.timeoutMs);
+    const abort = () => controller.abort(options.signal?.reason ?? new Error(options.cancelMessage));
+    options.signal?.addEventListener("abort", abort, { once: true });
+    try {
+        const response = await fetch(options.request, { ...options.init, signal: controller.signal });
+        if (!response.ok) {
+            await response.body?.cancel().catch(() => {
+                // Disposal errors must not replace the source-free HTTP diagnostic.
+            });
+            throw new Error(formatSearchHttpError({
+                provider: options.provider,
+                status: response.status,
+            }));
+        }
+        const text = await response.text();
+        try {
+            return JSON.parse(text);
+        }
+        catch {
+            // Parser messages and causes can include partial credentials from the response body.
+            throw new Error(options.invalidJsonMessage);
+        }
+    }
+    finally {
+        clearTimeout(timeout);
+        options.signal?.removeEventListener("abort", abort);
+    }
+}