pi-agent-browser-native 0.3.0 → 0.6.5

package/dist/extensions/agent-browser/lib/session-page-state.js

@@ -1,5 +1,7 @@
-import { getAgentBrowserSessionIdentityKey } from "./argv-grammar.js";
-import { isCloseCommand, isReadOnlyDiagnosticSessionTargetCommand, isUnverifiedPageTransitionCommand } from "./command-taxonomy.js";
+import { extractUpstreamCommandTokens } from "./argv-descriptor.js";
+import { getAgentBrowserSessionIdentityKey, isAgentBrowserSessionIdentityKeyInNamespace } from "./argv-grammar.js";
+import { batchHasSuccessfulCloseAll, getSuccessfulBatchCloseLifecycle } from "./batch-lifecycle.js";
+import { isCloseAllCommand, isCloseCommand, isReadOnlyDiagnosticSessionTargetCommand, isRecordPageTransitionCommand, isUnverifiedPageTransitionCommand, isWebMcpPageMutationCommand } from "./command-taxonomy.js";
 import { isRecord } from "./parsing.js";
 import { getEditableRefEvidence } from "./results/editable-ref-evidence.js";
 import { enrichSnapshotRefEntries, getSnapshotRefEntries } from "./results/snapshot-refs.js";
@@ -93,6 +95,11 @@ export function extractSessionTabTargetFromBatchResults(data) {
         }
         const [name, subcommand] = extractBatchResultCommand(item);
         const result = item.result;
+        if (isCloseCommand(name)) {
+            currentTarget = undefined;
+            pendingTitle = undefined;
+            continue;
+        }
         if (name === "get" && subcommand === "title") {
             pendingTitle = extractStringResultField(result, "title");
             continue;
@@ -197,6 +204,20 @@ export function buildNoActivePageRefSnapshotInvalidation() {
         summary: "The latest snapshot for this session reported No active page. Old page-scoped refs are invalid until snapshot -i succeeds.",
     };
 }
+export function buildPageTransitionRefSnapshotInvalidation(summary) {
+    return {
+        reason: "page-transition",
+        summary: summary ?? "A recording command (record start, or record restart with a URL) replaced or navigated the active page and invalidated the prior snapshot. Run snapshot -i before using page-scoped refs.",
+    };
+}
+export function getCommandRefSnapshotInvalidation(commandTokens) {
+    if (isRecordPageTransitionCommand(commandTokens))
+        return buildPageTransitionRefSnapshotInvalidation();
+    if (isWebMcpPageMutationCommand(commandTokens)) {
+        return buildPageTransitionRefSnapshotInvalidation("A WebMCP invoke, result, or cancel command can mutate, rerender, or navigate the page, so the prior snapshot refs were invalidated. Run snapshot -i before using page-scoped refs.");
+    }
+    return undefined;
+}
 export function isNoActivePageSnapshotFailure(command, text) {
     return command === "snapshot" && /\bno active page\b/i.test(text ?? "");
 }
@@ -207,7 +228,17 @@ export function extractLatestRefSnapshotStateFromBatchResults(data) {
     for (const item of data) {
         if (!isRecord(item))
             continue;
-        const [name] = extractBatchResultCommand(item);
+        const commandTokens = extractBatchResultCommand(item);
+        const [name] = commandTokens;
+        if (item.success !== false && isCloseCommand(name)) {
+            latestState = undefined;
+            continue;
+        }
+        const transitionInvalidation = getCommandRefSnapshotInvalidation(commandTokens);
+        if (transitionInvalidation) {
+            latestState = { invalidation: transitionInvalidation };
+            continue;
+        }
         if (name !== "snapshot")
             continue;
         if (item.success === false) {
@@ -225,9 +256,10 @@ export function extractLatestRefSnapshotStateFromBatchResults(data) {
 }
 function getRestoredRefSnapshotInvalidation(details, command) {
     const invalidation = isRecord(details.refSnapshotInvalidation) ? details.refSnapshotInvalidation : undefined;
-    if (invalidation && invalidation.reason === "no-active-page") {
+    if (invalidation?.reason === "no-active-page")
         return buildNoActivePageRefSnapshotInvalidation();
-    }
+    if (invalidation?.reason === "page-transition")
+        return buildPageTransitionRefSnapshotInvalidation(typeof invalidation.summary === "string" ? invalidation.summary : undefined);
     const errorText = typeof details.error === "string"
         ? details.error
         : typeof details.summary === "string"
@@ -316,14 +348,27 @@ export class SessionPageState {
             const sessionName = typeof details.sessionName === "string" ? details.sessionName : undefined;
             const namespace = typeof details.namespace === "string" ? details.namespace : undefined;
             const sessionKey = getSessionPageStateKey(sessionName, namespace);
+            const args = Array.isArray(details.args) && details.args.every((arg) => typeof arg === "string") ? details.args : [];
+            const commandTokens = extractUpstreamCommandTokens(args);
+            const command = typeof details.command === "string" ? details.command : commandTokens[0];
+            const subcommand = typeof details.subcommand === "string" ? details.subcommand : commandTokens[1];
+            const batchCloseLifecycle = getSuccessfulBatchCloseLifecycle(details.batchSteps);
+            const closeAllApplied = details.closeAllApplied === true
+                || (message.isError !== true && isCloseAllCommand(commandTokens))
+                || batchHasSuccessfulCloseAll(details.batchSteps);
+            if (closeAllApplied) {
+                restoredOrder += 1;
+                state.clearNamespace(namespace);
+                if (isCloseCommand(command) || batchCloseLifecycle?.endsClosed === true)
+                    continue;
+            }
             if (!sessionKey)
                 continue;
-            const command = typeof details.command === "string" ? details.command : undefined;
-            const subcommand = typeof details.subcommand === "string" ? details.subcommand : undefined;
-            if (isCloseCommand(command) && message.isError !== true) {
+            if (!closeAllApplied && ((isCloseCommand(command) && message.isError !== true) || batchCloseLifecycle)) {
                 restoredOrder += 1;
                 state.clearSession(sessionKey);
-                continue;
+                if (isCloseCommand(command) || batchCloseLifecycle?.endsClosed === true)
+                    continue;
             }
             const tabTarget = getRestoredSessionTabTarget(details, command, subcommand);
             const tabTargetUnknown = details.sessionTabTargetUnknown === true;
@@ -333,8 +378,11 @@ export class SessionPageState {
                 continue;
             restoredOrder += 1;
             if (tabTargetUnknown) {
-                state.refSnapshotInvalidations.delete(sessionKey);
                 state.refSnapshots.delete(sessionKey);
+                if (refSnapshotInvalidation)
+                    state.refSnapshotInvalidations.set(sessionKey, { ...refSnapshotInvalidation, order: restoredOrder });
+                else
+                    state.refSnapshotInvalidations.delete(sessionKey);
                 state.tabTargets.delete(sessionKey);
                 state.tabTargetUnknownOrders.set(sessionKey, restoredOrder);
                 continue;
@@ -431,6 +479,19 @@ export class SessionPageState {
         this.tabTargetUnknownOrders.delete(sessionName);
         this.tabTargets.delete(sessionName);
     }
+    clearNamespace(namespace) {
+        const sessionKeys = new Set([
+            ...this.refSnapshotInvalidations.keys(),
+            ...this.refSnapshots.keys(),
+            ...this.tabPinningReasons.keys(),
+            ...this.tabTargetUnknownOrders.keys(),
+            ...this.tabTargets.keys(),
+        ]);
+        for (const sessionKey of sessionKeys) {
+            if (isAgentBrowserSessionIdentityKeyInNamespace(sessionKey, namespace))
+                this.clearSession(sessionKey);
+        }
+    }
     markPinning(sessionName, reason) {
         this.tabPinningReasons.set(sessionName, reason);
     }

package/dist/extensions/agent-browser/lib/temp.js

@@ -8,7 +8,6 @@ import { processStartIdentitiesMatch, readProcessStartIdentity } from "./process
 const TEMP_ROOT_PREFIX = "pi-agent-browser-";
 const TEMP_ROOT_MARKER_FILE_NAME = ".pi-agent-browser-owner.json";
 const TEMP_ROOT_MARKER_KIND = "pi-agent-browser-temp-root";
-const TEMP_ROOT_LEGACY_MARKER_VERSION = 1;
 const TEMP_ROOT_MARKER_VERSION = 2;
 const STALE_TEMP_ROOT_MAX_AGE_MS = 24 * 60 * 60 * 1_000;
 const TEMP_ROOT_MAX_BYTES_ENV = "PI_AGENT_BROWSER_TEMP_ROOT_MAX_BYTES";
@@ -39,7 +38,7 @@ function isProtectedTempChildName(value) {
 function isTempRootOwnershipRecord(value) {
     if (!isRecord(value))
         return false;
-    if (value.kind !== TEMP_ROOT_MARKER_KIND || ![TEMP_ROOT_LEGACY_MARKER_VERSION, TEMP_ROOT_MARKER_VERSION].includes(value.version))
+    if (value.kind !== TEMP_ROOT_MARKER_KIND || value.version !== TEMP_ROOT_MARKER_VERSION)
         return false;
     if (!isPositiveFiniteNumber(value.createdAtMs))
         return false;

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

@@ -0,0 +1,14 @@
+import { MINIMUM_AGENT_BROWSER_VERSION, MINIMUM_AGENT_BROWSER_VERSION_LABEL, SUPPORTED_AGENT_BROWSER_VERSION_LABEL, TARGET_AGENT_BROWSER_VERSION, TARGET_AGENT_BROWSER_VERSION_LABEL, isSupportedAgentBrowserVersion, } from "../../../scripts/agent-browser-target.mjs";
+export { MINIMUM_AGENT_BROWSER_VERSION, MINIMUM_AGENT_BROWSER_VERSION_LABEL, SUPPORTED_AGENT_BROWSER_VERSION_LABEL, TARGET_AGENT_BROWSER_VERSION, TARGET_AGENT_BROWSER_VERSION_LABEL, isSupportedAgentBrowserVersion, };
+export function parseAgentBrowserVersionOutput(stdout) {
+    const match = stdout.trim().match(/^agent-browser\s+(\S+)$/);
+    return match?.[1];
+}
+export function getAgentBrowserVersionValidationError(stdout) {
+    const observed = parseAgentBrowserVersionOutput(stdout);
+    if (observed && isSupportedAgentBrowserVersion(observed))
+        return undefined;
+    return observed
+        ? `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.js

@@ -1,17 +1,24 @@
 import { JsonSchema } from "./json-schema.js";
 import { WEB_SEARCH_PROMPT_GUIDELINE } from "./playbook.js";
 import { StringEnum as localStringEnum } from "./string-enum-schema.js";
-import { DEFAULT_WEB_SEARCH_PROVIDER, WEB_SEARCH_PROVIDERS, resolvePreferredWebSearchCredential, } from "./config.js";
+import { DEFAULT_WEB_SEARCH_PROVIDER, EXA_SEARCH_TYPES, 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 EXA_DEEP_LITE_SEARCH_REQUEST_TIMEOUT_MS = 45_000;
+export const EXA_DEEP_SEARCH_REQUEST_TIMEOUT_MS = 60_000;
+export const EXA_DEEP_REASONING_SEARCH_REQUEST_TIMEOUT_MS = 90_000;
+export const EXA_DYNAMIC_HIGHLIGHTS_BETA = "dynamic-highlights-2026-08-28";
 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 EXA_SEARCH_SYSTEM_PROMPT = "Prefer primary, official sources. Respect any requested version or date. Avoid duplicate or equivalent results.";
+export { EXA_SEARCH_TYPES };
 export const WEB_SEARCH_PROVIDER_PARAM_VALUES = ["auto", ...WEB_SEARCH_PROVIDERS];
+export 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({
@@ -22,7 +29,28 @@ export function createAgentBrowserWebSearchParamsSchema(Type = JsonSchema, Strin
             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.",
+            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,
@@ -198,12 +226,14 @@ export function normalizeBraveSearchResult(result) {
     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),
     };
 }
@@ -213,13 +243,14 @@ export function normalizeExaSearchResult(result) {
     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),
-        age: cleanSearchText(result.publishedDate, 80),
+        ...(pageDate ? { pageDate } : {}),
     };
 }
 function getProviderLabel(provider) {
@@ -236,6 +267,8 @@ export function formatSearchResults(provider, query, results) {
         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)
@@ -277,14 +310,30 @@ function getStartPublishedDate(freshness, now) {
     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 Error(`additionalQueries requires deep-lite, deep, or deep-reasoning; received ${searchType}.`);
+    }
+    if ((params.category === "company" || params.category === "people") && (params.freshness || params.excludeDomains?.length)) {
+        throw new Error(`category ${params.category} cannot be combined with freshness or excludeDomains.`);
+    }
     const body = {
         query: params.query,
-        type: params.searchType ?? "auto",
+        type: searchType,
         numResults: Math.min(params.count + params.offset, 100),
-        contents: { highlights: true },
+        contents: { highlights: params.highlightsDynamic ? { dynamic: true } : true },
+        systemPrompt: EXA_SEARCH_SYSTEM_PROMPT,
     };
+    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);
@@ -396,7 +445,20 @@ export async function fetchBraveSearchJson(url, apiKey, signal) {
     });
 }
 function getExaRequestTimeoutMs(searchType) {
-    return searchType?.startsWith("deep") ? EXA_DEEP_SEARCH_REQUEST_TIMEOUT_MS : SEARCH_REQUEST_TIMEOUT_MS;
+    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))
+        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({
@@ -408,6 +470,7 @@ export async function fetchExaSearchJson(body, apiKey, signal, timeoutMs = SEARC
                 Accept: "application/json",
                 "Content-Type": "application/json",
                 "x-api-key": apiKey,
+                ...(usesDynamicHighlights(body) ? { "Exa-Beta": EXA_DYNAMIC_HIGHLIGHTS_BETA } : {}),
             },
             method: "POST",
         },
@@ -449,15 +512,7 @@ const EXA_WEB_SEARCH_ADAPTER = {
     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,
-            }),
+            body: buildExaSearchRequestBody(params),
             timeoutMs: getExaRequestTimeoutMs(searchType),
         };
     },
@@ -469,7 +524,7 @@ const EXA_WEB_SEARCH_ADAPTER = {
         return {
             extraDetails: {
                 requestId: cleanSearchText(response.requestId, 120),
-                searchType: cleanSearchText(response.searchType, 80) ?? searchType,
+                searchType,
             },
             results: (response.results ?? [])
                 .map(normalizeExaSearchResult)
@@ -486,6 +541,15 @@ export const WEB_SEARCH_PROVIDER_ADAPTERS = {
 export function getWebSearchProviderAdapter(provider) {
     return WEB_SEARCH_PROVIDER_ADAPTERS[provider];
 }
+export 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.";
@@ -498,13 +562,13 @@ export function createAgentBrowserWebSearchTool(configState, options = {}) {
     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.`,
+        description: `Search the live web with Exa or Brave for current or external information. For Exa research tasks, use searchType deep-lite or deeper. 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: [
             WEB_SEARCH_PROMPT_GUIDELINE,
             "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 or typing into public search engine result pages with agent_browser when a quick result list is enough; browser-automated search forms are often anti-bot/CAPTCHA-gated, and this tool is the fallback for discovery rather than a CAPTCHA bypass.",
-            "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.",
+            "Use Exa deep only when deep-lite may miss angles, and deep-reasoning only for exhaustive or still-thin research. Do not run parallel agent_browser_web_search calls; make one high-signal query, inspect its results, then at most one follow-up.",
+            "If agent_browser_web_search 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,
@@ -520,6 +584,18 @@ export function createAgentBrowserWebSearchTool(configState, options = {}) {
             const resolved = await resolvePreferredWebSearchCredential(runtimeConfigState, { provider: requestedProvider, signal });
             if (!resolved)
                 throw new Error(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 Error(`${exaOnlyFields.join(", ")} ${exaOnlyFields.length === 1 ? "requires" : "require"} provider exa; resolved provider was brave.`);
+                }
+            }
             const query = params.query.trim();
             if (!query)
                 throw new Error("query must not be blank");
@@ -527,18 +603,25 @@ export function createAgentBrowserWebSearchTool(configState, options = {}) {
             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 ?? "auto",
+                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,
@@ -547,10 +630,11 @@ export function createAgentBrowserWebSearchTool(configState, options = {}) {
                 offset,
                 ...normalized.extraDetails,
                 fetchedAt: new Date().toISOString(),
-                results: normalized.results,
+                results,
+                duplicatesRemoved: duplicatesRemoved || undefined,
             };
             return {
-                content: [{ type: "text", text: formatSearchResults(adapter.provider, normalized.returnedQuery, normalized.results) }],
+                content: [{ type: "text", text: `${formatSearchResults(adapter.provider, normalized.returnedQuery, results)}${duplicatesRemoved ? `\n\nDuplicate URLs removed: ${duplicatesRemoved}.` : ""}` }],
                 details,
             };
         },

package/dist/extensions/agent-browser/script-worker.js

@@ -0,0 +1,169 @@
+import { randomBytes } from "node:crypto";
+import { createContext, runInContext, Script } from "node:vm";
+function parseLimit(value, label) {
+    const parsed = Number(value);
+    if (!Number.isSafeInteger(parsed) || parsed <= 0)
+        throw new Error(`Invalid ${label}.`);
+    return parsed;
+}
+const maxMessageBytes = parseLimit(process.argv[2], "script IPC message limit");
+const maxCumulativeBytes = parseLimit(process.argv[3], "script IPC cumulative limit");
+let cumulativeBytes = 0;
+let inputBuffer = Buffer.alloc(0);
+let started = false;
+const sandbox = Object.create(null);
+const context = createContext(sandbox, {
+    codeGeneration: { strings: false, wasm: false },
+    name: "agent-browser-script",
+});
+const bridgeKey = `__piab_send_${randomBytes(16).toString("hex")}`;
+const stateName = `__piab_state_${randomBytes(16).toString("hex")}`;
+const hostSend = (json) => {
+    if (typeof json !== "string")
+        return false;
+    const bytes = Buffer.byteLength(json, "utf8") + 1;
+    if (bytes > maxMessageBytes || cumulativeBytes + bytes > maxCumulativeBytes)
+        return false;
+    cumulativeBytes += bytes;
+    try {
+        process.stdout.write(`${json}\n`);
+        return true;
+    }
+    catch {
+        return false;
+    }
+};
+Object.setPrototypeOf(hostSend, null);
+Object.freeze(hostSend);
+sandbox[bridgeKey] = hostSend;
+runInContext("const " + stateName + " = (() => {\n" +
+    "  'use strict';\n" +
+    "  const send = globalThis[" + JSON.stringify(bridgeKey) + "];\n" +
+    "  delete globalThis[" + JSON.stringify(bridgeKey) + "];\n" +
+    "  for (const name of ['console','process','require','Buffer','fetch','WebSocket','setTimeout','setInterval','setImmediate','queueMicrotask','clearTimeout','clearInterval','clearImmediate']) Object.defineProperty(globalThis, name, { value: undefined, writable: false, configurable: false });\n" +
+    "  const NativePromise = Promise;\n" +
+    "  const promiseThen = Promise.prototype.then;\n" +
+    "  const reflectApply = Reflect.apply;\n" +
+    "  const pending = new Map();\n" +
+    "  let nextId = 0;\n" +
+    "  const encode = (value) => { const json = JSON.stringify(value); if (typeof json !== 'string') throw new TypeError('Value must be JSON-serializable.'); return json; };\n" +
+    "  const sendValue = (value) => { const json = encode(value); if (json.length + 1 > " + maxMessageBytes + " || send(json) !== true) throw new RangeError('Script IPC limit exceeded.'); };\n" +
+    "  const browser = function browser(params) {\n" +
+    "    return new NativePromise((resolve, reject) => {\n" +
+    "      const id = ++nextId;\n" +
+    "      pending.set(id, { resolve, reject });\n" +
+    "      try { sendValue({ type: 'call', id, params }); } catch (error) { pending.delete(id); reject(error); }\n" +
+    "    });\n" +
+    "  };\n" +
+    "  const emit = function emit(value) { sendValue({ type: 'emit', value }); };\n" +
+    "  Object.setPrototypeOf(browser, null);\n" +
+    "  Object.setPrototypeOf(emit, null);\n" +
+    "  Object.freeze(browser);\n" +
+    "  Object.freeze(emit);\n" +
+    "  Object.defineProperties(globalThis, { browser: { value: browser, writable: false, configurable: false }, emit: { value: emit, writable: false, configurable: false } });\n" +
+    "  const complete = (ok, value) => {\n" +
+    "    if (ok) {\n" +
+    "      try { sendValue(value === undefined ? { type: 'complete', hasValue: false } : { type: 'complete', hasValue: true, value }); }\n" +
+    "      catch { sendValue({ type: 'complete', error: { name: 'RangeError', message: 'Final script value is not serializable or exceeds the IPC limit.' } }); }\n" +
+    "      return;\n" +
+    "    }\n" +
+    "    let name = 'Error'; let message = 'Script execution failed.';\n" +
+    "    try { if (value && typeof value.name === 'string') name = value.name.slice(0, 80); } catch {}\n" +
+    "    try { if (value && typeof value.message === 'string') message = value.message.replace(/[\\r\\n]+/g, ' ').slice(0, 400); } catch {}\n" +
+    "    sendValue({ type: 'complete', error: { name, message } });\n" +
+    "  };\n" +
+    "  return Object.freeze({\n" +
+    "    deliver(json) {\n" +
+    "      const message = JSON.parse(json);\n" +
+    "      const target = pending.get(message.id);\n" +
+    "      if (!target) return;\n" +
+    "      pending.delete(message.id);\n" +
+    "      target.resolve(message.envelope);\n" +
+    "    },\n" +
+    "    run(thunk) {\n" +
+    "      let promise;\n" +
+    "      try { promise = reflectApply(thunk, undefined, []); } catch (error) { complete(false, error); return; }\n" +
+    "      reflectApply(promiseThen, promise, [value => complete(true, value), error => complete(false, error)]);\n" +
+    "    }\n" +
+    "  });\n" +
+    "})();", context, { timeout: 1_000 });
+const deliver = runInContext(`${stateName}.deliver`, context, { timeout: 1_000 });
+function fail(name, message) {
+    hostSend(JSON.stringify({ type: "complete", error: { name, message } }));
+}
+function describeError(error, fallback) {
+    if (!error || typeof error !== "object")
+        return { message: fallback, name: "Error" };
+    const candidate = error;
+    return {
+        message: typeof candidate.message === "string" ? candidate.message.replace(/[\r\n]+/g, " ").slice(0, 400) : fallback,
+        name: typeof candidate.name === "string" ? candidate.name.slice(0, 80) : "Error",
+    };
+}
+function handleLine(line) {
+    const bytes = Buffer.byteLength(line, "utf8") + 1;
+    if (bytes > maxMessageBytes || cumulativeBytes + bytes > maxCumulativeBytes) {
+        fail("RangeError", "Script IPC limit exceeded.");
+        return;
+    }
+    cumulativeBytes += bytes;
+    let message;
+    try {
+        message = JSON.parse(line);
+    }
+    catch {
+        fail("Error", "Invalid parent IPC message.");
+        return;
+    }
+    if (!started) {
+        if (!message || typeof message !== "object" || message.type !== "start" || typeof message.code !== "string") {
+            fail("Error", "Invalid script start message.");
+            return;
+        }
+        started = true;
+        try {
+            const source = `'use strict';\n${stateName}.run(async function () {\n'use strict';\n${message.code}\n});`;
+            const script = new Script(source, {
+                filename: "agent-browser-script.js",
+                importModuleDynamically() {
+                    process.exit(70);
+                },
+            });
+            script.runInContext(context, { timeout: undefined });
+        }
+        catch (error) {
+            const described = describeError(error, "Script compilation failed.");
+            fail(described.name, described.message);
+        }
+        return;
+    }
+    if (!message || typeof message !== "object" || message.type !== "response") {
+        fail("Error", "Invalid parent IPC response.");
+        return;
+    }
+    try {
+        deliver(line);
+    }
+    catch {
+        fail("Error", "Invalid browser response envelope.");
+    }
+}
+process.stdin.on("data", (rawChunk) => {
+    const chunk = Buffer.isBuffer(rawChunk) ? rawChunk : Buffer.from(rawChunk);
+    inputBuffer = Buffer.concat([inputBuffer, chunk]);
+    if (inputBuffer.length > maxMessageBytes) {
+        fail("RangeError", "Script IPC message limit exceeded.");
+        process.stdin.pause();
+        return;
+    }
+    for (;;) {
+        const newline = inputBuffer.indexOf(10);
+        if (newline < 0)
+            break;
+        const line = inputBuffer.subarray(0, newline).toString("utf8");
+        inputBuffer = inputBuffer.subarray(newline + 1);
+        handleLine(line);
+    }
+});
+process.stdin.on("error", () => undefined);
+hostSend(JSON.stringify({ type: "ready" }));

package/dist/scripts/agent-browser-target.mjs

@@ -0,0 +1,21 @@
+export const TARGET_AGENT_BROWSER_SOURCE = "scripts/agent-browser-target.mjs";
+export const TARGET_AGENT_BROWSER_VERSION = "0.36.0";
+export const TARGET_AGENT_BROWSER_VERSION_LABEL = `agent-browser ${TARGET_AGENT_BROWSER_VERSION}`;
+export const MINIMUM_AGENT_BROWSER_VERSION = "0.35.0";
+export const MINIMUM_AGENT_BROWSER_VERSION_LABEL = `agent-browser ${MINIMUM_AGENT_BROWSER_VERSION}`;
+export const SUPPORTED_AGENT_BROWSER_VERSION_LABEL = `${MINIMUM_AGENT_BROWSER_VERSION_LABEL} or newer`;
+function stableVersionParts(version) {
+    const match = /^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)$/.exec(version);
+    return match?.slice(1).map(Number);
+}
+export function isSupportedAgentBrowserVersion(version) {
+    const actual = stableVersionParts(version);
+    const minimum = stableVersionParts(MINIMUM_AGENT_BROWSER_VERSION);
+    if (!actual || !minimum)
+        return false;
+    for (let index = 0; index < minimum.length; index += 1) {
+        if (actual[index] !== minimum[index])
+            return actual[index] > minimum[index];
+    }
+    return true;
+}