pi-agent-browser-native 0.9.3 → 0.9.5

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

@@ -1,568 +1,138 @@
-import { JsonSchema } from "./json-schema.js";
-import { isRecord } from "./parsing.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 { redactSensitiveText } from "./runtime.js";
-import { StringEnum as localStringEnum } from "./string-enum-schema.js";
-import { DEFAULT_WEB_SEARCH_PROVIDER, EXA_SEARCH_TYPES, WEB_SEARCH_PROVIDERS, resolvePreferredWebSearchCredential, } from "./config.js";
+import { isRecord } from "./parsing.js";
+import { isStringArray } from "./results/presentation/content.js";
+import { redactPresentationData } from "./results/presentation/diagnostic-redaction.js";
+import { isWebSearchProvider, resolvePreferredWebSearchCredential, } from "./config.js";
+import { AgentBrowserWebSearchParams, DEFAULT_SEARCH_RESULT_COUNT, MAX_SEARCH_RESULT_COUNT, } from "./web-search-schema.js";
+import { WebSearchRequestGate } from "./web-search-request.js";
+import { WebSearchLocalError, prepareWebSearchRequest } from "./web-search-providers.js";
+import { dedupeSearchResults, formatSearchResults, } from "./web-search-results.js";
+export { EXA_SEARCH_TYPES } from "./config.js";
+export { AgentBrowserWebSearchParams, createAgentBrowserWebSearchParamsSchema, } from "./web-search-schema.js";
+export { WEB_SEARCH_MIN_REQUEST_INTERVAL_MS, WebSearchRequestGate } from "./web-search-request.js";
+export { EXA_SEARCH_SYSTEM_PROMPT, buildBraveSearchUrl, buildExaSearchRequestBody, fetchBraveSearchJson, fetchExaSearchJson, } from "./web-search-providers.js";
+export { cleanSearchText, decodeHtmlEntities, normalizeBraveSearchResult, normalizeExaSearchResult, } from "./web-search-results.js";
 export const AGENT_BROWSER_WEB_SEARCH_TOOL_NAME = "agent_browser_web_search";
-const BRAVE_SEARCH_ENDPOINT = "https://api.search.brave.com/res/v1/web/search";
-const EXA_SEARCH_ENDPOINT = "https://api.exa.ai/search";
-const DEFAULT_SEARCH_RESULT_COUNT = 5;
-const MAX_SEARCH_RESULT_COUNT = 10;
-const SEARCH_REQUEST_TIMEOUT_MS = 15_000;
-const EXA_DEEP_LITE_SEARCH_REQUEST_TIMEOUT_MS = 45_000;
-const EXA_DEEP_SEARCH_REQUEST_TIMEOUT_MS = 60_000;
-const EXA_DEEP_REASONING_SEARCH_REQUEST_TIMEOUT_MS = 90_000;
-const EXA_DYNAMIC_HIGHLIGHTS_BETA = "dynamic-highlights-2026-08-28";
-export const WEB_SEARCH_MIN_REQUEST_INTERVAL_MS = 1_100;
-export const EXA_SEARCH_SYSTEM_PROMPT = "Prefer primary, official sources. Respect any requested version or date. Avoid duplicate or equivalent results.";
-export { EXA_SEARCH_TYPES };
-const WEB_SEARCH_PROVIDER_PARAM_VALUES = ["auto", ...WEB_SEARCH_PROVIDERS];
-const EXA_SEARCH_CATEGORIES = ["company", "people", "publication", "news", "personal site", "financial report"];
-const MAX_EXA_DOMAIN_FILTERS = 20;
-const MAX_EXA_ADDITIONAL_QUERIES = 10;
-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: "Exa mode; omitted uses webSearch.defaultSearchType, then auto. instant (~250ms) is only for trivial lookups; fast (~450ms) favors latency; auto (~1s) is balanced. Pass searchType: deep-lite (~4s) for research before implementation unless config already defaults it; do not assume auto is deep enough. deep (4–15s) handles hard multi-source research; deep-reasoning (12–40s) is only for the hardest work. Brave ignores this field.",
-        })),
-        includeDomains: Type.Optional(Type.Array(Type.String({ minLength: 1 }), {
-            minItems: 1,
-            maxItems: MAX_EXA_DOMAIN_FILTERS,
-            description: `Exa only. Limit results to 1–${MAX_EXA_DOMAIN_FILTERS} hostnames, path prefixes (exa.ai/docs), or wildcard subdomains (*.substack.com).`,
-        })),
-        excludeDomains: Type.Optional(Type.Array(Type.String({ minLength: 1 }), {
-            minItems: 1,
-            maxItems: MAX_EXA_DOMAIN_FILTERS,
-            description: `Exa only. Exclude 1–${MAX_EXA_DOMAIN_FILTERS} hostnames, path prefixes, or wildcard subdomains. Not compatible with category company or people.`,
-        })),
-        category: Type.Optional(StringEnum(EXA_SEARCH_CATEGORIES, {
-            description: "Exa-only result category. company and people cannot be combined with freshness or excludeDomains.",
-        })),
-        additionalQueries: Type.Optional(Type.Array(Type.String({ minLength: 1 }), {
-            minItems: 1,
-            maxItems: MAX_EXA_ADDITIONAL_QUERIES,
-            description: `Exa only. Add 1–${MAX_EXA_ADDITIONAL_QUERIES} query variations when the effective searchType is deep-lite, deep, or deep-reasoning.`,
-        })),
-        highlightsDynamic: Type.Optional(Type.Boolean({
-            description: "Exa-only research preview. Allocate one highlight budget across all results; the wrapper sends the required Exa-Beta header. Regular per-page highlights remain the default.",
-        })),
-        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);
+function buildMissingCredentialError(provider) {
+    if (provider === "brave") {
+        return "agent_browser_web_search provider brave was requested but no BRAVE_API_KEY/config credential resolved.";
     }
-    catch {
-        return `&${entity};`;
+    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 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()}…`;
-}
-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();
+function validateRuntimeConfig(state) {
+    if (state.errors.length > 0) {
+        throw new WebSearchLocalError(`agent_browser_web_search config is invalid: ${state.errors.join("; ")}`);
     }
-    catch {
-        return undefined;
+    if (!state.webSearchEnabled) {
+        throw new WebSearchLocalError("agent_browser_web_search is disabled by pi-agent-browser-native config.");
     }
 }
-function getHostname(url) {
-    try {
-        return new URL(url).hostname;
+function validateProviderParams(provider, params) {
+    if (provider !== "brave") {
+        return;
     }
-    catch {
-        return undefined;
+    const exaOnlyFields = [
+        params.includeDomains ? "includeDomains" : undefined,
+        params.excludeDomains ? "excludeDomains" : undefined,
+        params.category !== undefined ? "category" : undefined,
+        params.additionalQueries ? "additionalQueries" : undefined,
+        params.highlightsDynamic === true ? "highlightsDynamic" : undefined,
+    ].filter((field) => field !== undefined);
+    if (exaOnlyFields.length > 0) {
+        throw new WebSearchLocalError(`${exaOnlyFields.join(", ")} ${exaOnlyFields.length === 1 ? "requires" : "require"} provider exa; resolved provider was brave.`);
     }
 }
-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;
-    const pageDate = cleanSearchText(result.page_age, 80);
-    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),
-        ...(pageDate ? { pageDate } : {}),
-        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);
-    const pageDate = cleanSearchText(result.publishedDate, 80);
-    return {
-        title,
-        url,
-        description: cleanSearchText(result.summary, 320) ?? highlights?.[0] ?? cleanSearchText(result.text, 320),
-        highlights,
-        source: cleanSearchText(result.author, 120) ?? cleanSearchText(getHostname(url), 120),
-        ...(pageDate ? { pageDate } : {}),
-    };
-}
-function getProviderLabel(provider) {
-    return provider === "exa" ? "Exa" : "Brave";
-}
-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.pageDate)
-            lines.push(`   ${provider === "exa" ? "Published" : "Page date"}: ${result.pageDate}`);
-        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("");
+async function runWebSearch(state, params, gate, signal) {
+    validateRuntimeConfig(state);
+    const requestedProvider = params.provider ?? "auto";
+    const resolved = await resolvePreferredWebSearchCredential(state, {
+        provider: requestedProvider,
+        signal,
     });
-    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 searchType = params.searchType ?? "auto";
-    if (params.additionalQueries?.length && !searchType.startsWith("deep")) {
-        throw new WebSearchLocalError(`additionalQueries requires deep-lite, deep, or deep-reasoning; received ${searchType}.`);
+    if (!resolved) {
+        throw new WebSearchLocalError(buildMissingCredentialError(requestedProvider));
     }
-    if ((params.category === "company" || params.category === "people") && (params.freshness || params.excludeDomains?.length)) {
-        throw new WebSearchLocalError(`category ${params.category} cannot be combined with freshness or excludeDomains.`);
+    validateProviderParams(resolved.provider, params);
+    const query = params.query.trim();
+    if (query.length === 0) {
+        throw new WebSearchLocalError("query must not be blank");
     }
-    const body = {
-        query: params.query,
-        type: searchType,
-        numResults: Math.min(params.count + params.offset, 100),
-        contents: { highlights: params.highlightsDynamic ? { dynamic: true } : true },
-        systemPrompt: EXA_SEARCH_SYSTEM_PROMPT,
+    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 executionParams = {
+        additionalQueries: params.additionalQueries,
+        category: params.category,
+        country: params.country,
+        count,
+        excludeDomains: params.excludeDomains,
+        freshness: params.freshness,
+        highlightsDynamic: params.highlightsDynamic,
+        includeDomains: params.includeDomains,
+        offset,
+        query,
+        safesearch: params.safesearch,
+        searchLang: params.searchLang,
+        searchType: params.searchType ?? state.config.webSearch?.defaultSearchType ?? "auto",
+    };
+    const request = prepareWebSearchRequest(resolved.provider, executionParams, resolved.credential.value, signal);
+    const normalized = await gate.run(signal, request);
+    const results = dedupeSearchResults(normalized.results);
+    const duplicatesRemoved = normalized.results.length - results.length;
+    return {
+        provider: resolved.provider,
+        query,
+        returnedQuery: normalized.returnedQuery,
+        count,
+        offset,
+        ...normalized.extraDetails,
+        fetchedAt: new Date().toISOString(),
+        results,
+        duplicatesRemoved: duplicatesRemoved > 0 ? duplicatesRemoved : undefined,
     };
-    if (params.category)
-        body.category = params.category;
-    if (params.country)
-        body.userLocation = params.country.toUpperCase();
-    if (params.includeDomains?.length)
-        body.includeDomains = params.includeDomains;
-    if (params.excludeDomains?.length)
-        body.excludeDomains = params.excludeDomains;
-    if (params.additionalQueries?.length)
-        body.additionalQueries = params.additionalQueries;
-    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);
+async function presentSearchSuccess(rawDetails, params) {
+    const details = redactPresentationData({ command: "web-search" }, rawDetails);
+    if (!isRecord(details) ||
+        !isWebSearchProvider(details.provider) ||
+        typeof details.returnedQuery !== "string" ||
+        !Array.isArray(details.results) ||
+        !details.results.every(isNormalizedSearchResult)) {
+        throw new Error("Web search presentation has invalid result structure.");
     }
-    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,
+    const duplicateNotice = typeof details.duplicatesRemoved === "number"
+        ? `\n\nDuplicate URLs removed: ${details.duplicatesRemoved}.`
+        : "";
+    const result = await finalizeAgentBrowserNativeResult({
+        content: [
+            {
+                type: "text",
+                text: `${formatSearchResults(details.provider, details.returnedQuery, details.results)}${duplicateNotice}`,
             },
-        },
-        invalidJsonMessage: "Brave search returned invalid JSON",
-        provider: "brave",
-        request: url,
-        signal,
-        timeoutMessage: "Brave search timed out",
-        timeoutMs: SEARCH_REQUEST_TIMEOUT_MS,
-    });
-}
-function getExaRequestTimeoutMs(searchType) {
-    if (searchType === "deep-lite")
-        return EXA_DEEP_LITE_SEARCH_REQUEST_TIMEOUT_MS;
-    if (searchType === "deep")
-        return EXA_DEEP_SEARCH_REQUEST_TIMEOUT_MS;
-    if (searchType === "deep-reasoning")
-        return EXA_DEEP_REASONING_SEARCH_REQUEST_TIMEOUT_MS;
-    return SEARCH_REQUEST_TIMEOUT_MS;
-}
-function usesDynamicHighlights(body) {
-    const contents = body.contents;
-    if (!contents || typeof contents !== "object" || Array.isArray(contents))
+        ],
+        details: { data: details },
+    }, params);
+    // Keep the finalized spill receipt while flattening the documented search details shape.
+    const finalizedManifest = result.details.artifactManifest;
+    return finalizedManifest === undefined
+        ? { ...result, details }
+        : { ...result, details: { ...details, artifactManifest: finalizedManifest } };
+}
+function isNormalizedSearchResult(value) {
+    if (!isRecord(value) || typeof value.title !== "string" || typeof value.url !== "string") {
         return false;
-    const highlights = contents.highlights;
-    return Boolean(highlights && typeof highlights === "object" && !Array.isArray(highlights) && highlights.dynamic === true);
-}
-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,
-                ...(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,
-    });
-}
-const BRAVE_WEB_SEARCH_ADAPTER = {
-    provider: "brave",
-    buildRequest(params) {
-        return buildBraveSearchUrl({
-            query: params.query,
-            // Brave offsets count pages; fetch the prefix and slice by result like Exa.
-            count: params.count + params.offset,
-            offset: 0,
-            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))
-                .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) {
-        const searchType = params.searchType ?? "auto";
-        return {
-            body: buildExaSearchRequestBody(params),
-            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,
-            },
-            results: (response.results ?? [])
-                .map(normalizeExaSearchResult)
-                .filter((result) => Boolean(result))
-                .slice(params.offset, params.offset + params.count),
-            returnedQuery: params.query,
-        };
-    },
-};
-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 dedupeSearchResults(results) {
-    const seen = new Set();
-    return results.filter((result) => {
-        if (seen.has(result.url))
-            return false;
-        seen.add(result.url);
-        return true;
-    });
-}
-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.";
+    }
+    return (["description", "source", "age", "pageDate", "language"].every((field) => value[field] === undefined || typeof value[field] === "string") &&
+        (value.highlights === undefined || isStringArray(value.highlights)));
 }
-/** Local validation/config failures, not provider outages; reported as `validation-error`. */
-class WebSearchLocalError extends Error {
+function failureCategory(error, signal) {
+    if (signal?.aborted === true) {
+        return "aborted";
+    }
+    return error instanceof WebSearchLocalError ? "validation-error" : "upstream-error";
 }
 export function createAgentBrowserWebSearchTool(configState, options = {}) {
     const requestGate = new WebSearchRequestGate();
@@ -576,79 +146,19 @@ export function createAgentBrowserWebSearchTool(configState, options = {}) {
         parameters: AgentBrowserWebSearchParams,
         async execute(_toolCallId, params, signal, _onUpdate, ctx) {
             try {
-                const runtimeConfigState = ctx ? options.loadConfigState?.(ctx) ?? configState : configState;
-                if (runtimeConfigState.errors.length > 0) {
-                    throw new WebSearchLocalError(`agent_browser_web_search config is invalid: ${runtimeConfigState.errors.join("; ")}`);
-                }
-                if (!runtimeConfigState.webSearchEnabled) {
-                    throw new WebSearchLocalError("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 WebSearchLocalError(buildMissingCredentialError(requestedProvider));
-                if (resolved.provider === "brave") {
-                    const exaOnlyFields = [
-                        params.includeDomains ? "includeDomains" : undefined,
-                        params.excludeDomains ? "excludeDomains" : undefined,
-                        params.category ? "category" : undefined,
-                        params.additionalQueries ? "additionalQueries" : undefined,
-                        params.highlightsDynamic ? "highlightsDynamic" : undefined,
-                    ].filter((field) => Boolean(field));
-                    if (exaOnlyFields.length > 0) {
-                        throw new WebSearchLocalError(`${exaOnlyFields.join(", ")} ${exaOnlyFields.length === 1 ? "requires" : "require"} provider exa; resolved provider was brave.`);
-                    }
-                }
-                const query = params.query.trim();
-                if (!query)
-                    throw new WebSearchLocalError("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 = {
-                    additionalQueries: params.additionalQueries,
-                    category: params.category,
-                    country: params.country,
-                    count,
-                    excludeDomains: params.excludeDomains,
-                    freshness: params.freshness,
-                    highlightsDynamic: params.highlightsDynamic,
-                    includeDomains: params.includeDomains,
-                    offset,
-                    query,
-                    safesearch: params.safesearch,
-                    searchLang: params.searchLang,
-                    searchType: params.searchType ?? runtimeConfigState.config.webSearch?.defaultSearchType ?? "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 results = dedupeSearchResults(normalized.results);
-                const duplicatesRemoved = normalized.results.length - results.length;
-                const details = {
-                    provider: adapter.provider,
-                    query,
-                    returnedQuery: normalized.returnedQuery,
-                    count,
-                    offset,
-                    ...normalized.extraDetails,
-                    fetchedAt: new Date().toISOString(),
-                    results,
-                    duplicatesRemoved: duplicatesRemoved || undefined,
-                };
-                const result = await finalizeAgentBrowserNativeResult({
-                    content: [{ type: "text", text: `${formatSearchResults(adapter.provider, normalized.returnedQuery, results)}${duplicatesRemoved ? `\n\nDuplicate URLs removed: ${duplicatesRemoved}.` : ""}` }],
-                    details: { data: details },
-                }, params);
-                // Keep the finalized spill's invocation artifact receipt while flattening the documented search details shape.
-                const finalizedManifest = isRecord(result.details) ? result.details.artifactManifest : undefined;
-                return finalizedManifest === undefined ? { ...result, details } : { ...result, details: { ...details, artifactManifest: finalizedManifest } };
+                const state = ctx ? (options.loadConfigState?.(ctx) ?? configState) : configState;
+                const details = await runWebSearch(state, params, requestGate, signal);
+                return await presentSearchSuccess(details, params);
             }
             catch (error) {
-                const message = redactSensitiveText(error instanceof Error ? error.message : String(error)).slice(0, 1_000);
+                const message = redactSensitiveText(error instanceof Error ? error.message : "Unknown web search failure").slice(0, 1_000);
                 return finalizeAgentBrowserNativeResult({
                     content: [{ type: "text", text: message }],
-                    details: { error: message, resultCategory: "failure", failureCategory: signal?.aborted ? "aborted" : error instanceof WebSearchLocalError ? "validation-error" : "upstream-error" },
+                    details: {
+                        error: message,
+                        resultCategory: "failure",
+                        failureCategory: failureCategory(error, signal),
+                    },
                     isError: true,
                 }, params);
             }