pi-agent-browser-native 0.2.48 → 0.2.50

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

@@ -0,0 +1,562 @@
+/**
+ * Purpose: Provide the optional provider-backed `agent_browser_web_search` companion tool.
+ * Responsibilities: Define strict search input schema, resolve configured Brave/Exa credentials lazily, call the selected search API with cancellation/timeout, normalize compact results, and keep secrets out of content/details.
+ * Scope: Live web search only; browser automation remains in the `agent_browser` tool.
+ */
+import { JsonSchema } from "./json-schema.js";
+import { StringEnum as localStringEnum } from "./string-enum-schema.js";
+import { DEFAULT_WEB_SEARCH_PROVIDER, WEB_SEARCH_PROVIDERS, resolvePreferredWebSearchCredential, } from "./config.js";
+export const AGENT_BROWSER_WEB_SEARCH_TOOL_NAME = "agent_browser_web_search";
+export const BRAVE_SEARCH_ENDPOINT = "https://api.search.brave.com/res/v1/web/search";
+export const EXA_SEARCH_ENDPOINT = "https://api.exa.ai/search";
+export const DEFAULT_SEARCH_RESULT_COUNT = 5;
+export const MAX_SEARCH_RESULT_COUNT = 10;
+export const SEARCH_REQUEST_TIMEOUT_MS = 15_000;
+export const EXA_DEEP_SEARCH_REQUEST_TIMEOUT_MS = 45_000;
+export const WEB_SEARCH_MIN_REQUEST_INTERVAL_MS = 1_100;
+export const EXA_SEARCH_TYPES = ["auto", "fast", "instant", "deep-lite", "deep", "deep-reasoning"];
+export const WEB_SEARCH_PROVIDER_PARAM_VALUES = ["auto", ...WEB_SEARCH_PROVIDERS];
+export function createAgentBrowserWebSearchParamsSchema(Type = JsonSchema, StringEnum = localStringEnum) {
+    return Type.Object({
+        query: Type.String({
+            minLength: 1,
+            description: "Search query to run with the configured Exa or Brave web search provider.",
+        }),
+        provider: Type.Optional(StringEnum(WEB_SEARCH_PROVIDER_PARAM_VALUES, {
+            description: `Optional provider override. auto uses configured keys and preferredProvider; when both Exa and Brave are available, the default preferred provider is ${DEFAULT_WEB_SEARCH_PROVIDER}.`,
+        })),
+        searchType: Type.Optional(StringEnum(EXA_SEARCH_TYPES, {
+            description: "Optional Exa search type. Defaults to auto; ignored by Brave. Use deep/deep-reasoning only for harder research because they are slower.",
+        })),
+        count: Type.Optional(Type.Integer({
+            minimum: 1,
+            maximum: MAX_SEARCH_RESULT_COUNT,
+            description: `Number of web results to return. Defaults to ${DEFAULT_SEARCH_RESULT_COUNT}; max ${MAX_SEARCH_RESULT_COUNT}.`,
+        })),
+        offset: Type.Optional(Type.Integer({
+            minimum: 0,
+            maximum: 9,
+            description: "Zero-based result offset for pagination. Defaults to 0.",
+        })),
+        country: Type.Optional(Type.String({
+            pattern: "^[A-Za-z]{2}$",
+            description: "Optional 2-letter country code, such as US or GB.",
+        })),
+        searchLang: Type.Optional(Type.String({
+            minLength: 2,
+            maxLength: 8,
+            description: "Optional Brave search language code, such as en or en-US.",
+        })),
+        safesearch: Type.Optional(StringEnum(["off", "moderate", "strict"], {
+            description: "Optional search safety setting. Brave forwards this as safesearch; Exa maps moderate/strict to moderation=true.",
+        })),
+        freshness: Type.Optional(StringEnum(["pd", "pw", "pm", "py"], {
+            description: "Optional freshness window: pd=past day, pw=past week, pm=past month, py=past year.",
+        })),
+    }, { additionalProperties: false });
+}
+export const AgentBrowserWebSearchParams = createAgentBrowserWebSearchParamsSchema();
+const HTML_ENTITY_REPLACEMENTS = {
+    amp: "&",
+    apos: "'",
+    gt: ">",
+    lt: "<",
+    nbsp: " ",
+    quot: '"',
+};
+const HTML_TAG_NAMES_TO_STRIP = new Set([
+    "a",
+    "abbr",
+    "address",
+    "article",
+    "aside",
+    "audio",
+    "b",
+    "base",
+    "blockquote",
+    "body",
+    "br",
+    "button",
+    "canvas",
+    "code",
+    "div",
+    "em",
+    "embed",
+    "footer",
+    "form",
+    "h1",
+    "h2",
+    "h3",
+    "h4",
+    "h5",
+    "h6",
+    "head",
+    "header",
+    "html",
+    "i",
+    "iframe",
+    "img",
+    "input",
+    "li",
+    "link",
+    "main",
+    "mark",
+    "math",
+    "meta",
+    "nav",
+    "object",
+    "ol",
+    "option",
+    "p",
+    "pre",
+    "script",
+    "section",
+    "select",
+    "source",
+    "span",
+    "strong",
+    "style",
+    "svg",
+    "table",
+    "tbody",
+    "td",
+    "textarea",
+    "tfoot",
+    "th",
+    "thead",
+    "tr",
+    "u",
+    "ul",
+    "video",
+]);
+function decodeHtmlEntity(entity) {
+    const named = HTML_ENTITY_REPLACEMENTS[entity.toLowerCase()];
+    if (named !== undefined)
+        return named;
+    const decimalMatch = /^#(\d+)$/.exec(entity);
+    const hexMatch = /^#x([0-9a-f]+)$/i.exec(entity);
+    const codePoint = decimalMatch ? Number.parseInt(decimalMatch[1] ?? "", 10) : hexMatch ? Number.parseInt(hexMatch[1] ?? "", 16) : undefined;
+    if (codePoint === undefined || !Number.isFinite(codePoint))
+        return `&${entity};`;
+    try {
+        return String.fromCodePoint(codePoint);
+    }
+    catch {
+        return `&${entity};`;
+    }
+}
+export function decodeHtmlEntities(value) {
+    return value.replace(/&([a-z][a-z0-9]+|#\d+|#x[0-9a-f]+);/gi, (_match, entity) => decodeHtmlEntity(entity));
+}
+function stripDecodedHtmlTags(value) {
+    return value.replace(/<(script|style)\b[^>]*>[\s\S]*?<\/\1>/gi, " ").replace(/<\/?([a-z][a-z0-9-]*)(\s[^>]*)?>/gi, (match, tagName, attributes) => {
+        if (attributes || match.startsWith("</") || HTML_TAG_NAMES_TO_STRIP.has(tagName.toLowerCase()))
+            return " ";
+        return match;
+    });
+}
+export function cleanSearchText(value, maxLength = 500) {
+    if (typeof value !== "string")
+        return undefined;
+    const cleaned = stripDecodedHtmlTags(decodeHtmlEntities(value.replace(/<[^>]*>/g, " ")))
+        .replace(/\s+/g, " ")
+        .trim();
+    if (!cleaned)
+        return undefined;
+    if (cleaned.length <= maxLength)
+        return cleaned;
+    return `${cleaned.slice(0, Math.max(0, maxLength - 1)).trimEnd()}…`;
+}
+export function normalizeSearchUrl(value) {
+    if (typeof value !== "string")
+        return undefined;
+    try {
+        const url = new URL(value);
+        if (url.protocol !== "http:" && url.protocol !== "https:")
+            return undefined;
+        return url.toString();
+    }
+    catch {
+        return undefined;
+    }
+}
+function getHostname(url) {
+    try {
+        return new URL(url).hostname;
+    }
+    catch {
+        return undefined;
+    }
+}
+function normalizeHighlightList(value) {
+    if (!Array.isArray(value))
+        return undefined;
+    const highlights = value
+        .map((entry) => cleanSearchText(entry, 320))
+        .filter((entry) => Boolean(entry))
+        .slice(0, 3);
+    return highlights.length > 0 ? highlights : undefined;
+}
+export function normalizeBraveSearchResult(result) {
+    const title = cleanSearchText(result.title, 180);
+    const url = normalizeSearchUrl(result.url);
+    if (!title || !url)
+        return undefined;
+    return {
+        title,
+        url,
+        description: cleanSearchText(result.description, 320),
+        source: cleanSearchText(result.profile?.name, 120) ?? cleanSearchText(result.meta_url?.hostname, 120),
+        age: cleanSearchText(result.age, 80),
+        language: cleanSearchText(result.language, 40),
+    };
+}
+export function normalizeExaSearchResult(result) {
+    const title = cleanSearchText(result.title, 180);
+    const url = normalizeSearchUrl(result.url);
+    if (!title || !url)
+        return undefined;
+    const highlights = normalizeHighlightList(result.highlights);
+    return {
+        title,
+        url,
+        description: cleanSearchText(result.summary, 320) ?? highlights?.[0] ?? cleanSearchText(result.text, 320),
+        highlights,
+        source: cleanSearchText(result.author, 120) ?? cleanSearchText(getHostname(url), 120),
+        age: cleanSearchText(result.publishedDate, 80),
+    };
+}
+function getProviderLabel(provider) {
+    return provider === "exa" ? "Exa" : "Brave";
+}
+export function formatSearchResults(provider, query, results) {
+    const providerLabel = getProviderLabel(provider);
+    if (results.length === 0) {
+        return `No ${providerLabel} web results found for: ${query}`;
+    }
+    const lines = [`${providerLabel} web search results for: ${query}`, ""];
+    results.forEach((result, index) => {
+        lines.push(`${index + 1}. ${result.title}`);
+        lines.push(`   URL: ${result.url}`);
+        if (result.source)
+            lines.push(`   Source: ${result.source}`);
+        if (result.age)
+            lines.push(`   Age: ${result.age}`);
+        if (result.description)
+            lines.push(`   Summary: ${result.description}`);
+        if (result.highlights && result.highlights.length > 1) {
+            lines.push("   Highlights:");
+            for (const highlight of result.highlights)
+                lines.push(`   - ${highlight}`);
+        }
+        lines.push("");
+    });
+    return lines.join("\n").trimEnd();
+}
+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)
+        url.searchParams.set("country", params.country.toUpperCase());
+    if (params.searchLang)
+        url.searchParams.set("search_lang", params.searchLang);
+    if (params.safesearch)
+        url.searchParams.set("safesearch", params.safesearch);
+    if (params.freshness)
+        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)
+        return undefined;
+    const days = FRESHNESS_DAYS[freshness];
+    return new Date(now().getTime() - days * 24 * 60 * 60 * 1000).toISOString();
+}
+export function buildExaSearchRequestBody(params, now = () => new Date()) {
+    const body = {
+        query: params.query,
+        type: params.searchType ?? "auto",
+        numResults: Math.min(params.count + params.offset, 100),
+        contents: { highlights: true },
+    };
+    if (params.country)
+        body.userLocation = params.country.toUpperCase();
+    if (params.safesearch && params.safesearch !== "off")
+        body.moderation = true;
+    const startPublishedDate = getStartPublishedDate(params.freshness, now);
+    if (startPublishedDate)
+        body.startPublishedDate = startPublishedDate;
+    return body;
+}
+function redactSearchSecret(text, apiKey) {
+    return apiKey ? text.split(apiKey).join("[REDACTED]") : text;
+}
+function sleepWithAbort(ms, signal) {
+    if (ms <= 0)
+        return Promise.resolve();
+    if (signal?.aborted)
+        return Promise.reject(signal.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();
+            reject(signal?.reason ?? new Error("Web search cancelled"));
+        };
+        signal?.addEventListener("abort", abort, { once: true });
+    });
+}
+export class WebSearchRequestGate {
+    now;
+    sleep;
+    lastRequestStartedAt = 0;
+    tail = Promise.resolve();
+    constructor(now = Date.now, sleep = sleepWithAbort) {
+        this.now = now;
+        this.sleep = sleep;
+    }
+    run(signal, task) {
+        const runTask = async () => {
+            const elapsedMs = this.lastRequestStartedAt === 0 ? WEB_SEARCH_MIN_REQUEST_INTERVAL_MS : this.now() - this.lastRequestStartedAt;
+            const waitMs = Math.max(0, WEB_SEARCH_MIN_REQUEST_INTERVAL_MS - elapsedMs);
+            if (waitMs > 0)
+                await this.sleep(waitMs, signal);
+            if (signal?.aborted)
+                throw signal.reason ?? new Error("Web search cancelled");
+            this.lastRequestStartedAt = this.now();
+            return task();
+        };
+        const result = this.tail.then(runTask, runTask);
+        this.tail = result.catch(() => undefined);
+        return result;
+    }
+}
+function formatSearchHttpError(provider, status, statusText, body, apiKey) {
+    const providerLabel = getProviderLabel(provider);
+    const errorPreview = cleanSearchText(redactSearchSecret(body, apiKey), 300);
+    if (status === 429) {
+        const preview = errorPreview ? ` Upstream details: ${redactSearchSecret(errorPreview, apiKey)}` : "";
+        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.${preview}`;
+    }
+    return `${providerLabel} search failed with HTTP ${status}: ${errorPreview ? redactSearchSecret(errorPreview, apiKey) : statusText}`;
+}
+async function fetchSearchJson(options) {
+    if (options.signal?.aborted) {
+        throw options.signal.reason ?? new Error(options.cancelMessage);
+    }
+    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,
+        });
+        const text = await response.text();
+        if (!response.ok) {
+            throw new Error(formatSearchHttpError(options.provider, response.status, response.statusText, text, options.apiKey));
+        }
+        try {
+            return JSON.parse(text);
+        }
+        catch (error) {
+            throw new Error(`${options.invalidJsonMessage}: ${error instanceof Error ? error.message : String(error)}`);
+        }
+    }
+    finally {
+        clearTimeout(timeout);
+        options.signal?.removeEventListener("abort", abort);
+    }
+}
+export async function fetchBraveSearchJson(url, apiKey, signal) {
+    return fetchSearchJson({
+        apiKey,
+        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,
+    });
+}
+function getExaRequestTimeoutMs(searchType) {
+    return searchType?.startsWith("deep") ? EXA_DEEP_SEARCH_REQUEST_TIMEOUT_MS : SEARCH_REQUEST_TIMEOUT_MS;
+}
+export async function fetchExaSearchJson(body, apiKey, signal, timeoutMs = SEARCH_REQUEST_TIMEOUT_MS) {
+    return fetchSearchJson({
+        apiKey,
+        cancelMessage: "Exa search cancelled",
+        init: {
+            body: JSON.stringify(body),
+            headers: {
+                Accept: "application/json",
+                "Content-Type": "application/json",
+                "x-api-key": apiKey,
+            },
+            method: "POST",
+        },
+        invalidJsonMessage: "Exa search returned invalid JSON",
+        provider: "exa",
+        request: EXA_SEARCH_ENDPOINT,
+        signal,
+        timeoutMessage: "Exa search timed out",
+        timeoutMs,
+    });
+}
+const BRAVE_WEB_SEARCH_ADAPTER = {
+    provider: "brave",
+    buildRequest(params) {
+        return buildBraveSearchUrl({
+            query: params.query,
+            count: params.count,
+            offset: params.offset,
+            country: params.country,
+            searchLang: params.searchLang,
+            safesearch: params.safesearch,
+            freshness: params.freshness,
+        });
+    },
+    fetchJson(request, apiKey, signal) {
+        return fetchBraveSearchJson(request, apiKey, signal);
+    },
+    normalizeResponse(response, params) {
+        return {
+            results: (response.web?.results ?? [])
+                .map(normalizeBraveSearchResult)
+                .filter((result) => Boolean(result)),
+            returnedQuery: cleanSearchText(response.query?.altered, 300) ?? cleanSearchText(response.query?.original, 300) ?? params.query,
+        };
+    },
+};
+const EXA_WEB_SEARCH_ADAPTER = {
+    provider: "exa",
+    buildRequest(params) {
+        const searchType = params.searchType ?? "auto";
+        return {
+            body: buildExaSearchRequestBody({
+                query: params.query,
+                count: params.count,
+                offset: params.offset,
+                country: params.country,
+                safesearch: params.safesearch,
+                freshness: params.freshness,
+                searchType,
+            }),
+            timeoutMs: getExaRequestTimeoutMs(searchType),
+        };
+    },
+    fetchJson(request, apiKey, signal) {
+        return fetchExaSearchJson(request.body, apiKey, signal, request.timeoutMs);
+    },
+    normalizeResponse(response, params) {
+        const searchType = params.searchType ?? "auto";
+        return {
+            extraDetails: {
+                requestId: cleanSearchText(response.requestId, 120),
+                searchType: cleanSearchText(response.searchType, 80) ?? searchType,
+            },
+            results: (response.results ?? [])
+                .map(normalizeExaSearchResult)
+                .filter((result) => Boolean(result))
+                .slice(params.offset, params.offset + params.count),
+            returnedQuery: params.query,
+        };
+    },
+};
+export const WEB_SEARCH_PROVIDER_ADAPTERS = {
+    exa: EXA_WEB_SEARCH_ADAPTER,
+    brave: BRAVE_WEB_SEARCH_ADAPTER,
+};
+export function getWebSearchProviderAdapter(provider) {
+    return WEB_SEARCH_PROVIDER_ADAPTERS[provider];
+}
+function buildMissingCredentialError(provider) {
+    if (provider === "brave")
+        return "agent_browser_web_search provider brave was requested but no BRAVE_API_KEY/config credential resolved.";
+    if (provider === "exa")
+        return "agent_browser_web_search provider exa was requested but no EXA_API_KEY/config credential resolved.";
+    return "No Exa or Brave web search credential resolved. Configure webSearch.exaApiKey or webSearch.braveApiKey, or load EXA_API_KEY/BRAVE_API_KEY in the runtime environment.";
+}
+export function createAgentBrowserWebSearchTool(configState, options = {}) {
+    const requestGate = new WebSearchRequestGate();
+    return {
+        name: AGENT_BROWSER_WEB_SEARCH_TOOL_NAME,
+        label: "Agent Browser Web Search",
+        description: `Search the web with Exa or Brave when configured. Returns up to ${MAX_SEARCH_RESULT_COUNT} concise web results.`,
+        promptSnippet: "Search the live web with Exa or Brave for current or external information.",
+        promptGuidelines: [
+            "Use agent_browser_web_search when live web search would help answer the task, find current external information, or discover candidate URLs for agent_browser.",
+            "agent_browser_web_search chooses Exa or Brave from configured keys; when both are available, Exa is preferred by default unless webSearch.preferredProvider says otherwise. Use provider only when the user/config calls for a specific provider.",
+            "Prefer agent_browser_web_search over opening a search engine results page with agent_browser when a quick result list is enough; use agent_browser for interaction, DOM, screenshots, or auth.",
+            "Do not issue parallel or repeated agent_browser_web_search calls; use one high-signal query, inspect the results, then only run a focused follow-up if needed. If the provider returns HTTP 429, stop searching and tell the user the API plan/rate limit needs time or a plan change.",
+            "After using agent_browser_web_search, cite result URLs in the final answer when web evidence informed the answer.",
+        ],
+        parameters: AgentBrowserWebSearchParams,
+        async execute(_toolCallId, params, signal, _onUpdate, ctx) {
+            const runtimeConfigState = ctx ? options.loadConfigState?.(ctx) ?? configState : configState;
+            if (runtimeConfigState.errors.length > 0) {
+                throw new Error(`agent_browser_web_search config is invalid: ${runtimeConfigState.errors.join("; ")}`);
+            }
+            if (!runtimeConfigState.webSearchEnabled) {
+                throw new Error("agent_browser_web_search is disabled by pi-agent-browser-native config.");
+            }
+            const requestedProvider = params.provider ?? "auto";
+            const resolved = await resolvePreferredWebSearchCredential(runtimeConfigState, { provider: requestedProvider, signal });
+            if (!resolved)
+                throw new Error(buildMissingCredentialError(requestedProvider));
+            const query = params.query.trim();
+            if (!query)
+                throw new Error("query must not be blank");
+            const count = Math.min(Math.max(params.count ?? DEFAULT_SEARCH_RESULT_COUNT, 1), MAX_SEARCH_RESULT_COUNT);
+            const offset = Math.max(params.offset ?? 0, 0);
+            const adapter = getWebSearchProviderAdapter(resolved.provider);
+            const executionParams = {
+                country: params.country,
+                count,
+                freshness: params.freshness,
+                offset,
+                query,
+                safesearch: params.safesearch,
+                searchLang: params.searchLang,
+                searchType: params.searchType ?? "auto",
+            };
+            const request = adapter.buildRequest(executionParams);
+            const data = await requestGate.run(signal, () => adapter.fetchJson(request, resolved.credential.value, signal));
+            const normalized = adapter.normalizeResponse(data, executionParams);
+            const details = {
+                provider: adapter.provider,
+                query,
+                returnedQuery: normalized.returnedQuery,
+                count,
+                offset,
+                ...normalized.extraDetails,
+                fetchedAt: new Date().toISOString(),
+                results: normalized.results,
+            };
+            return {
+                content: [{ type: "text", text: formatSearchResults(adapter.provider, normalized.returnedQuery, normalized.results) }],
+                details,
+            };
+        },
+    };
+}

package/docs/ARCHITECTURE.md

@@ -23,7 +23,7 @@ V1 exposes one native browser tool:
 
 It may also expose one optional companion tool:
 
-- `agent_browser_web_search`, registered only when an Exa or Brave Search credential source is configured or resolvable and `webSearch.enabled` is not false
+- `agent_browser_web_search`, available when an Exa or Brave Search credential source is configured or resolvable from startup config or trusted session config and runtime `webSearch.enabled` is not false
 
 Why:
 - keeps browser automation centered on `agent_browser`
@@ -68,11 +68,11 @@ Pi docs use `settings.json` for package/resource loading and filtering, not arbi
 - project-local: `.pi/config/pi-agent-browser-native/config.json`
 - explicit override: `PI_AGENT_BROWSER_CONFIG=/path/to/config.json`
 
-Config layers merge in that order: global, project, override. The shared policy module (`extensions/agent-browser/lib/config-policy.js`) owns provider descriptors, environment variable names, config keys, project-local credential safety, developer-trusted project layer inclusion, layer validation/merge, redacted status projection, and credential summaries for both runtime config loading and the package config helper. Under Pi 0.79+, globally installed or CLI-loaded extensions are developer-trusted code, so this extension reads `.pi/config/pi-agent-browser-native/config.json` by default and skips that project layer when Pi reports the project is untrusted or when launched with `--no-approve`. Global config and explicit `PI_AGENT_BROWSER_CONFIG` overrides remain available either way. The config reader accepts v1 fields for `webSearch.enabled`, `webSearch.preferredProvider`, `webSearch.exaApiKey`, `webSearch.braveApiKey`, and conservative browser defaults such as `browser.defaultProfile` and `browser.executablePath`. Web-search key fields follow Pi model/provider-style value resolution for trusted global/override config: literal values, `$ENV_VAR` / `${ENV_VAR}` interpolation, escapes (`$$`, `$!`), and leading `!command` resolved at request time. Project-local plaintext, interpolation-literal, malformed, and command-backed web-search keys are rejected because project config can be copied, committed, or supplied by a repository; project config may use only the matching provider env ref (`$EXA_API_KEY` / `${EXA_API_KEY}` for Exa, `$BRAVE_API_KEY` / `${BRAVE_API_KEY}` for Brave), so a repository cannot redirect search credentials to arbitrary host env vars. `EXA_API_KEY` and `BRAVE_API_KEY` remain environment fallbacks when no config credential source exists for that provider. Browser default values keep their source scope; profile/executable prompt guidance is emitted only from trusted global or explicit override config, not from project-local config that could steer host profile or executable choices.
+Config layers merge in that order: global, project, override. The shared policy module (`extensions/agent-browser/lib/config-policy.js`) owns provider descriptors, environment variable names, config keys, credential source parsing, developer-trusted project layer inclusion, layer validation/merge, redacted status projection, and credential summaries for both runtime config loading and the package config helper. Under Pi 0.79+, globally installed or CLI-loaded extensions are developer-trusted code, so this extension reads `.pi/config/pi-agent-browser-native/config.json` by default and skips that project layer when Pi reports the project is untrusted or when launched with `--no-approve`. Global config and explicit `PI_AGENT_BROWSER_CONFIG` overrides remain available either way. The config reader accepts v1 fields for `webSearch.enabled`, `webSearch.preferredProvider`, `webSearch.exaApiKey`, `webSearch.braveApiKey`, and conservative browser defaults such as `browser.defaultProfile` and `browser.executablePath`. Web-search key fields follow Pi model/provider-style value resolution from any loaded layer: literal values, `$ENV_VAR` / `${ENV_VAR}` interpolation, escapes (`$$`, `$!`), and leading `!command` resolved at request time. `EXA_API_KEY` and `BRAVE_API_KEY` remain environment fallbacks when no config credential source exists for that provider. Browser default values keep their source scope; prompt guidance is emitted from the highest-priority loaded layer, including project config when Pi trust/loading allows it.
 
-`agent_browser_web_search` registration is conditional. `webSearch.enabled: false` disables registration even when environment keys are present, but it is evaluated after the available config layers merge. A global disable is the normal user default and can still be overridden by project config or `PI_AGENT_BROWSER_CONFIG`; a project disable applies to one repo; an explicit `PI_AGENT_BROWSER_CONFIG` file with `webSearch.enabled: false` is the highest-priority hard disable for that run. Literal and env-backed sources must resolve at startup; command-backed sources are considered configured without running the command until tool execution, so secret managers do not slow startup or prompt unexpectedly. The tool resolves the selected key lazily, chooses Exa or Brave from available credentials (preferring Exa by default unless `webSearch.preferredProvider` says otherwise), then follows one provider-agnostic execution path through provider adapters for request building, HTTP JSON fetch, response normalization, and provider-specific detail fields. It calls Exa `/search` with highlights or Brave Search and returns compact result details without exposing keys.
+`agent_browser_web_search` availability is conditional. Startup registration uses global, override, and environment fallback config without reading project-local config before Pi trust context exists; trusted project config can register the companion tool on `session_start`, and every execution reloads the final session config so `webSearch.enabled: false` still prevents a request even if a startup credential made the tool visible. A global disable is the normal user default and can still be overridden by project config or `PI_AGENT_BROWSER_CONFIG`; a project disable applies to one repo; an explicit `PI_AGENT_BROWSER_CONFIG` file with `webSearch.enabled: false` is the highest-priority hard disable for that run. Literal and env-backed sources must resolve before they make the tool available; command-backed sources are considered configured without running the command until tool execution, so secret managers do not slow startup or prompt unexpectedly. The tool resolves the selected key lazily, chooses Exa or Brave from available credentials (preferring Exa by default unless `webSearch.preferredProvider` says otherwise), then follows one provider-agnostic execution path through provider adapters for request building, HTTP JSON fetch, response normalization, and provider-specific detail fields. It calls Exa `/search` with highlights or Brave Search and returns compact result details without exposing keys.
 
-Browser default config is intentionally conservative. It can add prompt guidance for signed-in/account-specific tasks and alternate Chromium-compatible executables, but current releases do not auto-inject `--profile` or `--executable-path` into every launch. Project-local browser config is status-only for launch guidance unless the profile policy is `explicit-only`; executable guidance must come from global or explicit override config. Automatic launch-default mutation would affect privacy, browser state, and host executable choice, so it needs a separate explicit design and test pass.
+Browser default config is intentionally advisory. It can add prompt guidance for signed-in/account-specific tasks and alternate Chromium-compatible executables, but current releases do not auto-inject `--profile` or `--executable-path` into every launch. Loaded project config can provide the same guidance as global and override config; Pi/project trust decides whether that project layer is loaded. Automatic launch-default mutation would affect privacy, browser state, and host executable choice, so it needs a separate explicit design and test pass.
 
 ### Prompt guidance budget
 
@@ -199,7 +199,7 @@ This keeps the product centered on native tool usage instead of auxiliary skill
 ### `pi-agent-browser-native` owns
 
 - tool registration and schema (including the optional `semanticAction` compilation path to upstream `find` or `select`)
-- subprocess execution and JSON parsing through a filtered child environment (`buildAgentBrowserProcessEnv` in `extensions/agent-browser/lib/process.ts`): copies an allowlisted inherited-name set plus every parent `AGENT_BROWSER_*` variable and provider-related prefixes (`AGENTCORE_*`, `AI_GATEWAY_*`, `BROWSERBASE_*`, `BROWSERLESS_*`, `BROWSER_USE_*`, `KERNEL_*`, `XDG_*`) instead of cloning the full parent process environment
+- subprocess execution and JSON parsing through `buildAgentBrowserProcessEnv` in `extensions/agent-browser/lib/process.ts`: copies the parent process environment so user-approved provider credentials and other runtime variables reach upstream, then applies wrapper overrides such as the managed socket directory and clamped default operation timeout
 - clear missing-binary errors
 - compact result summaries, including presentation-time redaction: stateful browser-context commands (`auth`, `cookies`, `storage`, `dialog`, `frame`, `state`) use field-aware value redaction and compact formatters, while other structured upstream JSON (for example `network`, `diff`, `trace` / `profiler` / `record`, `console` / `errors` / `highlight` / `inspect` / `clipboard`, `stream`, `dashboard`, and `chat`) is passed through `redactPresentationData` in `extensions/agent-browser/lib/results/presentation.ts` so model-facing `details.data` and batch roll-ups stay compact and do not echo bearer tokens, proxy passwords, or similar fields verbatim; `redactInvocationArgs` in `extensions/agent-browser/lib/runtime.ts` masks trailing values for sensitive global flags such as `--body`, `--headers`, `--password`, and `--proxy`, preserves positional rules for `cookies set` and `storage local|session set`, and nested `batch` steps use the same argv and error-body scrubbing before echoing commands or errors
 - bounded machine-readable outcome metadata on tool `details` (`resultCategory`, `successCategory`, `failureCategory`, optional `nextActions`, optional `pageChangeSummary` with per-step summaries on `batch`, optional `artifactVerification` with the same shape on each successful `batchSteps[]` row) so agents can branch without parsing prose; enums, classifier precedence, and generic follow-up payloads are implemented under `extensions/agent-browser/lib/results/` in focused modules (`contracts.ts` for shared types, `categories.ts` for `classifyAgentBrowserSuccessCategory` / `classifyAgentBrowserFailureCategory` / `buildAgentBrowserResultCategoryDetails`, `action-recommendations.ts` for `buildAgentBrowserNextActions`, `next-actions.ts` for the `AgentBrowserNextAction` shape and merge helpers, `recovery-actions.ts` for recovery id registries and `buildRecoveryNextActions`, `network.ts` for `classifyNetworkRequestFailure` / `summarizeNetworkFailures`, and related helpers; `shared.ts` in that directory is a **re-export-only** barrel so historical `./results/shared.js` imports keep working without growing a monolith). Per-session tab target, `refSnapshot` alignment, invalidation, and tab pinning observations flow through `extensions/agent-browser/lib/session-page-state.ts` from `extensions/agent-browser/index.ts`. Compact page-change summaries and artifact verification rollups are built in `extensions/agent-browser/lib/results/presentation.ts` (`buildPageChangeSummary`, `buildArtifactVerificationSummary`), and the human contract lives in [`TOOL_CONTRACT.md`](TOOL_CONTRACT.md#details). Real Pi custom tools otherwise only mark a row failed when `execute` throws, so the extension also registers `pi.on("tool_result", …)` and patches `agent_browser` results whose `details.resultCategory` is `failure` to set `isError: true`. Prose results also receive a short category notice, while caller-requested `--json` results with parseable JSON content keep that text unchanged so JSONL transcripts, UI affordances, and the machine-readable contract stay aligned for wrapper-side reclassifications such as `qa-failure` (`buildAgentBrowserToolResultPatch` in `extensions/agent-browser/lib/pi-tool-rendering.ts`; transcript semantics in the same contract doc)

package/docs/COMMAND_REFERENCE.md

@@ -748,7 +748,7 @@ npm exec --yes --package pi-agent-browser-native@latest -- pi-agent-browser-conf
 npm exec --yes --package pi-agent-browser-native@latest -- pi-agent-browser-config browser executable set "/Applications/Brave Browser.app/Contents/MacOS/Brave Browser"
 ```
 
-The optional `agent_browser_web_search` tool is registered only when Exa or Brave credentials are available and the final available config has not set `webSearch.enabled` to `false`. It is a separate custom tool, not an `agent_browser` input mode, and does not launch a browser. Use it when current/live external web information would help; use `agent_browser` for browser interaction, screenshots, authenticated/profile pages, and DOM inspection. Disable scope is explicit: `web-search disable --global` sets the normal user default, `web-search disable --project` disables it for one repo, and a `PI_AGENT_BROWSER_CONFIG` override containing `{ "version": 1, "webSearch": { "enabled": false } }` wins over both for a hard per-run disable. Project-local plaintext, custom env aliases, interpolation-literal, malformed, and command-backed web-search keys are refused; project config may only use the matching provider env refs (`$EXA_API_KEY` / `${EXA_API_KEY}` for Exa and `$BRAVE_API_KEY` / `${BRAVE_API_KEY}` for Brave). `web-search set-key`, `set-command`, and `clear` require `--provider`; `set-env` infers Exa/Brave from `EXA_API_KEY` or `BRAVE_API_KEY` unless you pass `--provider`. For Exa, the tool defaults to `searchType: "auto"` with `contents.highlights: true`; use `fast`, `instant`, `deep-lite`, `deep`, or `deep-reasoning` only when the task needs that latency/depth tradeoff.
+The optional `agent_browser_web_search` tool is available when Exa or Brave credentials are visible from startup config or trusted session config and the runtime config has not set `webSearch.enabled` to `false`. It is a separate custom tool, not an `agent_browser` input mode, and does not launch a browser. Use it when current/live external web information would help; use `agent_browser` for browser interaction, screenshots, authenticated/profile pages, and DOM inspection. Disable scope is explicit: `web-search disable --global` sets the normal user default, `web-search disable --project` disables it for one repo, and a `PI_AGENT_BROWSER_CONFIG` override containing `{ "version": 1, "webSearch": { "enabled": false } }` wins over both for a hard per-run disable. Loaded config may use plaintext, custom env aliases, interpolation literals, malformed-or-late-bound `$` values, and command-backed web-search keys; the resolved secret reaches the provider request while model-facing tool output and status text stay redacted. `web-search set-key`, `set-command`, and `clear` require `--provider`; `set-env` infers Exa/Brave from `EXA_API_KEY` or `BRAVE_API_KEY` unless you pass `--provider`. For Exa, the tool defaults to `searchType: "auto"` with `contents.highlights: true`; use `fast`, `instant`, `deep-lite`, `deep`, or `deep-reasoning` only when the task needs that latency/depth tradeoff.
 
 Example config:
 
@@ -771,7 +771,7 @@ Example config:
 }
 ```
 
-Browser default config is conservative: it adds agent guidance for signed-in/account-specific tasks and alternate Chromium-compatible executables; current releases do not auto-inject `--profile` or `--executable-path` for every launch. Configure profile/executable guidance globally or through `PI_AGENT_BROWSER_CONFIG`; project-local browser config is loaded by default but is never trusted to steer host executable/profile prompt guidance. Ask the agent to run `profiles` and `doctor` when profile resolution fails, then use the reported Chrome profile directory name, a full profile/user-data directory path if upstream accepts one, or the configured `browser.executablePath` with top-level `sessionMode: "fresh"`.
+Browser default config is conservative: it adds agent guidance for signed-in/account-specific tasks and alternate Chromium-compatible executables; current releases do not auto-inject `--profile` or `--executable-path` for every launch. Configure profile/executable guidance globally, in trusted project config, or through `PI_AGENT_BROWSER_CONFIG`. Ask the agent to run `profiles` and `doctor` when profile resolution fails, then use the reported Chrome profile directory name, a full profile/user-data directory path if upstream accepts one, or the configured `browser.executablePath` with top-level `sessionMode: "fresh"`.
 
 ## Important global flags, config, and environment
 
@@ -819,7 +819,7 @@ Browser default config is conservative: it adds agent guidance for signed-in/acc
 - `--confirm-interactive`: interactive confirmations; auto-denies when stdin is not a TTY. Environment: `AGENT_BROWSER_CONFIRM_INTERACTIVE`.
 - `-p, --provider <name>`: provider such as `ios`, `browserbase`, `kernel`, `browseruse`, `browserless`, or `agentcore`. Environment: `AGENT_BROWSER_PROVIDER`.
 - `--device <name>`: iOS device name. Environment: `AGENT_BROWSER_IOS_DEVICE`.
-- Provider-specific iOS examples from upstream include `agent-browser -p ios device list`, `agent-browser -p ios swipe up`, and `agent-browser -p ios tap @e1`; in pi, pass those tokens through `args` rather than bash. iOS requires external Xcode/Appium setup, and cloud providers (`browserbase`, `kernel`, `browseruse`, `browserless`, `agentcore`) require their upstream accounts, credentials, and provider-specific environment variables. Common forwarded provider variables include `BROWSERBASE_API_KEY`, `BROWSERBASE_PROJECT_ID`, `BROWSERLESS_API_KEY`, `BROWSERLESS_API_URL`, `BROWSERLESS_BROWSER_TYPE`, `BROWSERLESS_STEALTH`, `BROWSERLESS_TTL`, `BROWSER_USE_API_KEY`, `KERNEL_API_KEY`, `KERNEL_HEADLESS`, `KERNEL_STEALTH`, `KERNEL_TIMEOUT_SECONDS`, `KERNEL_PROFILE_NAME`, `AGENTCORE_API_KEY`, `AGENTCORE_REGION`, `AGENTCORE_BROWSER_ID`, `AGENTCORE_PROFILE_ID`, `AGENTCORE_SESSION_TIMEOUT`, plus AWS names used by AgentCore such as `AWS_PROFILE`, `AWS_ACCESS_KEY_ID`, `AWS_SECRET_ACCESS_KEY`, `AWS_SESSION_TOKEN`, `AWS_REGION`, and `AWS_DEFAULT_REGION`. The wrapper forwards provider flags/env and stays thin; it does not emulate provider setup or cloud browser behavior.
+- Provider-specific iOS examples from upstream include `agent-browser -p ios device list`, `agent-browser -p ios swipe up`, and `agent-browser -p ios tap @e1`; in pi, pass those tokens through `args` rather than bash. iOS requires external Xcode/Appium setup, and cloud providers (`browserbase`, `kernel`, `browseruse`, `browserless`, `agentcore`) require their upstream accounts, credentials, and provider-specific environment variables. Common provider variables include `BROWSERBASE_API_KEY`, `BROWSERBASE_PROJECT_ID`, `BROWSERLESS_API_KEY`, `BROWSERLESS_API_URL`, `BROWSERLESS_BROWSER_TYPE`, `BROWSERLESS_STEALTH`, `BROWSERLESS_TTL`, `BROWSER_USE_API_KEY`, `KERNEL_API_KEY`, `KERNEL_HEADLESS`, `KERNEL_STEALTH`, `KERNEL_TIMEOUT_SECONDS`, `KERNEL_PROFILE_NAME`, `AGENTCORE_API_KEY`, `AGENTCORE_REGION`, `AGENTCORE_BROWSER_ID`, `AGENTCORE_PROFILE_ID`, `AGENTCORE_SESSION_TIMEOUT`, plus AWS names used by AgentCore such as `AWS_PROFILE`, `AWS_ACCESS_KEY_ID`, `AWS_SECRET_ACCESS_KEY`, `AWS_SESSION_TOKEN`, `AWS_REGION`, and `AWS_DEFAULT_REGION`. The wrapper forwards parent environment variables plus provider flags and stays thin; it does not emulate provider setup or cloud browser behavior.
 - `--model <name>`: AI model for `chat`. Environment: `AI_GATEWAY_MODEL`.
 - `-v, --verbose`: show tool commands and raw output.
 - `-q, --quiet`: show only AI text responses.
@@ -837,7 +837,7 @@ Browser default config is conservative: it adds agent guidance for signed-in/acc
 
 Use `--config <path>` to load a specific config file. Boolean flags accept optional `true` or `false` values, such as `--headed false`, to override config. Browser extensions from user and project configs are merged rather than replaced.
 
-Other useful environment variables include `AGENT_BROWSER_DEFAULT_TIMEOUT`, `AGENT_BROWSER_STREAM_PORT`, `AGENT_BROWSER_IDLE_TIMEOUT_MS`, `AGENT_BROWSER_ENCRYPTION_KEY`, `AGENT_BROWSER_STATE_EXPIRE_DAYS`, `AGENT_BROWSER_IOS_DEVICE`, `AGENT_BROWSER_IOS_UDID`, `AI_GATEWAY_URL`, `AI_GATEWAY_API_KEY`, the provider credential names listed above, and AWS credential names when using AgentCore. The upstream child also receives every parent variable whose name starts with `AGENT_BROWSER_`, `AGENTCORE_`, `AI_GATEWAY_`, `BROWSERBASE_`, `BROWSERLESS_`, `BROWSER_USE_`, `KERNEL_`, or `XDG_`, plus the explicit inherited-name allowlist in `buildAgentBrowserProcessEnv` (`extensions/agent-browser/lib/process.ts`).
+Other useful environment variables include `AGENT_BROWSER_DEFAULT_TIMEOUT`, `AGENT_BROWSER_STREAM_PORT`, `AGENT_BROWSER_IDLE_TIMEOUT_MS`, `AGENT_BROWSER_ENCRYPTION_KEY`, `AGENT_BROWSER_STATE_EXPIRE_DAYS`, `AGENT_BROWSER_IOS_DEVICE`, `AGENT_BROWSER_IOS_UDID`, `AI_GATEWAY_URL`, `AI_GATEWAY_API_KEY`, provider credential names, and AWS credential names when using AgentCore. The upstream child receives the parent environment plus wrapper overrides such as the managed socket directory and clamped default operation timeout (`buildAgentBrowserProcessEnv` in `extensions/agent-browser/lib/process.ts`). Model-facing output still redacts recognized secret values.
 
 ## Wrapper-specific behavior worth knowing