pi-agent-browser-native 0.9.4 → 0.9.5

package/dist/extensions/agent-browser/lib/orchestration/browser-run/session-state-refs.js

@@ -87,7 +87,7 @@ function isSafeSameSnapshotFormBatchStep(step, refSnapshot) {
             return false;
     }
 }
-function getBatchRefInvalidationMessage(commandTokens, stdin, refSnapshot) {
+function getBatchRefInvalidationFailure(commandTokens, stdin, refSnapshot) {
     if (commandTokens[0] !== "batch") {
         return;
     }
@@ -98,7 +98,11 @@ function getBatchRefInvalidationMessage(commandTokens, stdin, refSnapshot) {
         }
         const refIds = collectRefsFromTokens(step);
         if (refIds.length > 0 && isRefGuardedCommand(step[0]) && priorStepInvalidatesRefs) {
-            return `Batch step ${step[0]} uses page-scoped ref ${refIds.map((refId) => `@${refId}`).join(", ")} after an earlier batch step can navigate or mutate the page. Split the batch, run snapshot -i after the page-changing step, then retry with current refs.`;
+            return {
+                message: `Batch step ${step[0]} uses page-scoped ref ${refIds.map((refId) => `@${refId}`).join(", ")} after an earlier batch step can navigate or mutate the page. Split the batch, run snapshot -i after the page-changing step, then retry with current refs.`,
+                refIds,
+                snapshot: refSnapshot,
+            };
         }
         if (isRefInvalidatingBatchCommand(step) &&
             !isSafeSameSnapshotFormBatchStep(step, refSnapshot)) {
@@ -151,15 +155,9 @@ export function buildStaleRefPreflight(facts) {
             })),
         ]
         : guardedRefIds;
-    const batchInvalidationMessage = getBatchRefInvalidationMessage(facts.commandTokens, facts.stdin, facts.refSnapshot);
-    if (batchInvalidationMessage !== undefined &&
-        batchInvalidationMessage.length > 0 &&
-        guardedRefIds.length > 0) {
-        return {
-            message: batchInvalidationMessage,
-            refIds: guardedRefIds,
-            snapshot: facts.refSnapshot,
-        };
+    const batchInvalidationFailure = getBatchRefInvalidationFailure(facts.commandTokens, facts.stdin, facts.refSnapshot);
+    if (batchInvalidationFailure) {
+        return batchInvalidationFailure;
     }
     if (usedRefIds.length === 0) {
         return;

package/dist/extensions/agent-browser/lib/orchestration/electron-host/branch.js

@@ -21,6 +21,7 @@ function hasValidOptionalFields(value) {
         "packageSource",
         "platform",
         "sessionName",
+        "startIdentity",
         "webSocketDebuggerUrl",
     ];
     return (strings.every((field) => value[field] === undefined || typeof value[field] === "string") &&

package/dist/extensions/agent-browser/lib/orchestration/electron-host/probe-collection.js

@@ -17,9 +17,6 @@ function probeCommandError(result, label) {
         ? `${label}: ${result.error}`
         : undefined;
 }
-function probeString(data, field, limit) {
-    return boundElectronProbeString(extractStringResultField(data, "result") ?? extractStringResultField(data, field), limit);
-}
 export async function collectElectronProbe(options) {
     // Each read completes before the next: native session commands share a pending
     // slot, and the final snapshot owns the refs published by this probe.
@@ -28,8 +25,9 @@ export async function collectElectronProbe(options) {
     if (urlError !== undefined) {
         throw new Error(urlError);
     }
-    const url = probeString(urlResult.data, "url", 300);
-    if (url === undefined || url.length === 0) {
+    const url = extractStringResultField(urlResult.data, "result") ??
+        extractStringResultField(urlResult.data, "url");
+    if (url === undefined || url.trim().length === 0) {
         throw new Error("get url returned no active page URL.");
     }
     const titleResult = await runElectronProbeCommandData({ ...options, args: ["get", "title"] });
@@ -62,7 +60,8 @@ export async function collectElectronProbe(options) {
         snapshot,
         status: errors.length === 0 ? "succeeded" : "partial",
         tabs,
-        title: probeString(titleResult.data, "title", 160),
+        title: boundElectronProbeString(extractStringResultField(titleResult.data, "result") ??
+            extractStringResultField(titleResult.data, "title"), 160),
         url,
     };
     return { ...probe, summary: getElectronProbeSummary(probe) };

package/dist/extensions/agent-browser/lib/orchestration/electron-host/probe-data.js

@@ -92,7 +92,7 @@ export function extractElectronProbeTabs(data) {
         tabId: getTrimmedString(tab.tabId) ?? getTrimmedString(tab.id),
         title: getTrimmedString(tab.title) ?? getTrimmedString(tab.label),
         type: getTrimmedString(tab.type),
-        url: getTrimmedString(tab.url),
+        url: typeof tab.url === "string" ? tab.url : undefined,
     }));
     if (allTabs.length === 0) {
         return {};
@@ -156,7 +156,9 @@ export function summarizeElectronProbeSnapshot(data) {
 export function getElectronProbeSummary(probe) {
     const parts = [
         probe.title !== undefined && probe.title.length > 0 ? `title "${probe.title}"` : undefined,
-        probe.url !== undefined && probe.url.length > 0 ? `url ${probe.url}` : undefined,
+        probe.url !== undefined && probe.url.length > 0
+            ? `url ${boundElectronProbeString(probe.url, 300) ?? ""}`
+            : undefined,
         probe.focusedElement ? "focused element" : undefined,
         probe.tabs ? `${probe.tabs.total} tab(s)` : undefined,
         probe.snapshot ? `${probe.snapshot.refCount} ref(s)` : undefined,

package/dist/extensions/agent-browser/lib/orchestration/electron-host/probe-presentation.js

@@ -1,3 +1,4 @@
+import { boundElectronProbeString } from "../../electron/cdp.js";
 import { buildAgentBrowserNextActions } from "../../results/action-recommendations.js";
 import { buildAgentBrowserResultCategoryDetails } from "../../results/categories.js";
 import { appendUniqueAgentBrowserNextActions } from "../../results/next-actions.js";
@@ -5,6 +6,17 @@ import { redactSensitiveText } from "../../runtime-redaction.js";
 import { isAboutBlankUrl } from "../../session-page-state.js";
 import { redactToolDetails } from "../browser-run/final-result.js";
 import { buildElectronIdentifiers, buildElectronMismatchNextActions, formatElectronSessionMismatchText, getLiveElectronRendererTargets, } from "../browser-run/session-state.js";
+function presentProbeTab(tab) {
+    return { ...tab, url: boundElectronProbeString(tab.url) };
+}
+function presentProbe(probe) {
+    return {
+        ...probe,
+        activeTab: probe.activeTab ? presentProbeTab(probe.activeTab) : undefined,
+        tabs: probe.tabs ? { ...probe.tabs, shown: probe.tabs.shown.map(presentProbeTab) } : undefined,
+        url: boundElectronProbeString(probe.url, 300),
+    };
+}
 function presentStrings(values) {
     return values.filter((value) => value !== undefined && value.length > 0);
 }
@@ -130,7 +142,8 @@ function probeNextActions(options) {
         : appendUniqueAgentBrowserNextActions([...base], mismatch);
 }
 export function buildElectronProbeResult(options) {
-    const { refSnapshot: _refSnapshot, ...boundedProbe } = options.probe;
+    const probe = presentProbe(options.probe);
+    const { refSnapshot: _refSnapshot, ...boundedProbe } = probe;
     const nextActions = probeNextActions(options);
     const details = {
         args: [],
@@ -157,7 +170,12 @@ export function buildElectronProbeResult(options) {
         usedImplicitSession: options.probeContext.mode === "current-managed-session",
     };
     return {
-        content: [{ type: "text", text: redactSensitiveText(formatElectronProbeVisibleText(options)) }],
+        content: [
+            {
+                type: "text",
+                text: redactSensitiveText(formatElectronProbeVisibleText({ ...options, probe })),
+            },
+        ],
         details: redactToolDetails(details, []),
         isError: false,
     };

package/dist/extensions/agent-browser/lib/orchestration/electron-host/status.js

@@ -9,6 +9,7 @@ import { buildElectronHostFailureResult, formatElectronTargetLines, redactToolDe
 import { buildElectronIdentifiers, buildElectronMismatchNextActions, buildElectronSessionMismatch, formatElectronSessionMismatchText, } from "../browser-run/session-state.js";
 import { selectElectronRecords } from "./branch.js";
 import { collectOwnedElectronManagedSessionTarget } from "./policy.js";
+import { presentElectronManagedSessionTarget } from "../browser-run/final-result-electron.js";
 function pidStatusText(pidAlive) {
     if (pidAlive === undefined) {
         return "";
@@ -72,6 +73,7 @@ function statusNextActions(options) {
 }
 function buildElectronStatusResult(options) {
     const nextActions = statusNextActions(options);
+    const managedSessions = options.managedSessions.map(presentElectronManagedSessionTarget);
     const soleRecord = options.records.length === 1 ? options.records[0] : undefined;
     const details = {
         args: [],
@@ -81,8 +83,8 @@ function buildElectronStatusResult(options) {
             identifierList: options.records.length > 1 ? options.records.map(buildElectronIdentifiers) : undefined,
             identifiers: soleRecord ? buildElectronIdentifiers(soleRecord) : undefined,
             launches: options.records,
-            managedSession: options.managedSessions.length === 1 ? options.managedSessions[0] : undefined,
-            managedSessions: options.managedSessions.length > 0 ? options.managedSessions : undefined,
+            managedSession: managedSessions.length === 1 ? managedSessions[0] : undefined,
+            managedSessions: managedSessions.length > 0 ? managedSessions : undefined,
             sessionMismatch: options.mismatches.length === 1 ? options.mismatches[0] : undefined,
             sessionMismatches: options.mismatches.length > 1 ? options.mismatches : undefined,
             status: "succeeded",

package/dist/extensions/agent-browser/lib/orchestration/execution-queue.js

@@ -54,7 +54,7 @@ export class KeyedAsyncExecutionQueue {
     async run(key, namespace, work, signal) {
         const entry = this.entries.get(key) ?? { queue: new AsyncExecutionQueue(), users: 0 };
         if (entry.queue.isCurrent()) {
-            return work();
+            return entry.queue.run(work, signal);
         }
         const barrier = this.barriers.get(getAgentBrowserSessionIdentityKey("", namespace)) ?? Promise.resolve();
         entry.users += 1;

package/dist/extensions/agent-browser/lib/results/presentation/skills.js

@@ -33,6 +33,7 @@ function getSkillContent(data) {
 class SkillShellWords {
     words = [];
     current = "";
+    wordStarted = false;
     quote;
     index = 0;
     input;
@@ -40,9 +41,10 @@ class SkillShellWords {
         this.input = input;
     }
     flush() {
-        if (this.current.length > 0) {
+        if (this.wordStarted) {
             this.words.push(this.current);
             this.current = "";
+            this.wordStarted = false;
         }
     }
     appendEscape() {
@@ -68,18 +70,21 @@ class SkillShellWords {
     }
     consumeUnquoted(char) {
         if (char === "'" || char === '"') {
+            this.wordStarted = true;
             this.quote = char === "'" ? "single" : "double";
         }
         else if (char === "\\") {
+            this.wordStarted = true;
             this.appendEscape();
         }
-        else if (char === "#" && this.current.length === 0) {
+        else if (char === "#" && !this.wordStarted) {
             return false;
         }
         else if (/\s/.test(char)) {
             this.flush();
         }
         else {
+            this.wordStarted = true;
             this.current += char;
         }
         return true;

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

@@ -67,7 +67,10 @@ export async function prunePersistentSessionArtifactsToBudget(sessionArtifactDir
         }
         // Evict oldest first and stop immediately once the required budget is available.
         // oxlint-disable-next-line no-await-in-loop
-        await rm(file.path, { force: true }).catch(() => undefined);
+        const removed = await rm(file.path, { force: true }).then(() => true, () => false);
+        if (!removed) {
+            continue;
+        }
         evictedArtifacts.push({ mtimeMs: file.mtimeMs, path: file.path, sizeBytes: file.size });
         totalBytes -= file.size;
         if (totalBytes + additionalBytes <= maxBytes) {

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

@@ -161,19 +161,29 @@ export async function cleanupSecureTempArtifacts(options = {}) {
         });
     });
 }
-export async function getSessionTempRoot() {
-    if (!sessionTempRootPromise) {
-        sessionTempRootPromise = (async () => {
-            const tempRoot = await mkdtemp(join(tmpdir(), TEMP_ROOT_PREFIX));
-            await chmod(tempRoot, 0o700).catch(() => {
-                /* mkdtemp already creates a private root. */
-            });
-            await writeSecureTempRootOwnershipMarker(tempRoot);
-            ownedTempRoots.add(tempRoot);
-            registerExitCleanup();
-            return tempRoot;
-        })();
+async function allocateSessionTempRoot() {
+    const tempRoot = await mkdtemp(join(tmpdir(), TEMP_ROOT_PREFIX));
+    try {
+        await chmod(tempRoot, 0o700).catch(() => {
+            /* mkdtemp already creates a private root. */
+        });
+        await writeSecureTempRootOwnershipMarker(tempRoot);
+        ownedTempRoots.add(tempRoot);
+        registerExitCleanup();
+        return tempRoot;
+    }
+    catch (error) {
+        await rm(tempRoot, { force: true, recursive: true }).catch(() => {
+            /* Preserve the allocation failure if private-root cleanup also fails. */
+        });
+        throw error;
     }
+}
+export async function getSessionTempRoot() {
+    sessionTempRootPromise ??= allocateSessionTempRoot().catch((error) => {
+        sessionTempRootPromise = undefined;
+        throw error;
+    });
     const tempRoot = await sessionTempRootPromise;
     await refreshSecureTempRootLease(tempRoot).catch(() => {
         /* A failed refresh leaves the existing marker. */
@@ -199,9 +209,3 @@ export async function getSecureTempChildDirectoryValidationError(path, childPref
     }
     return undefined;
 }
-export async function getSecureTempDebugState() {
-    return {
-        currentTempRoot: await sessionTempRootPromise?.catch(() => undefined),
-        ownedTempRoots: [...ownedTempRoots].sort(),
-    };
-}

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

@@ -4,7 +4,7 @@ import { dirname, join } from "node:path";
 import { enqueueTempMutation } from "./temp-mutation-queue.js";
 import { getSessionTempRoot, refreshSecureTempRootLease } from "./temp-root.js";
 import { assertSecureTempRootBudget, getTempArtifactByteLength, prunePersistentSessionArtifactsToBudget, } from "./temp-artifact-budget.js";
-export { cleanupSecureTempArtifacts, getSecureTempChildDirectoryValidationError, getSecureTempDebugState, preserveSecureTempDirectory, writeSecureTempRootOwnershipMarker, } from "./temp-root.js";
+export { cleanupSecureTempArtifacts, getSecureTempChildDirectoryValidationError, preserveSecureTempDirectory, writeSecureTempRootOwnershipMarker, } from "./temp-root.js";
 export { getPersistentSessionArtifactMaxBytes, getSecureTempRootMaxBytes, } from "./temp-artifact-budget.js";
 async function ensurePersistentSessionArtifactDir(store) {
     const rootDir = join(store.sessionDir, ".pi-agent-browser-artifacts");

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

@@ -76,7 +76,6 @@ export function buildExaSearchRequestBody(params, now = () => new Date()) {
 }
 export async function fetchBraveSearchJson(url, apiKey, signal) {
     const data = await fetchSearchJson({
-        apiKey,
         cancelMessage: "Brave search cancelled",
         init: { headers: { Accept: "application/json", "X-Subscription-Token": apiKey } },
         invalidJsonMessage: "Brave search returned invalid JSON",
@@ -113,7 +112,6 @@ function usesDynamicHighlights(body) {
 }
 export async function fetchExaSearchJson(body, apiKey, signal, timeoutMs = SEARCH_REQUEST_TIMEOUT_MS) {
     const data = await fetchSearchJson({
-        apiKey,
         cancelMessage: "Exa search cancelled",
         init: {
             body: JSON.stringify(body),
@@ -178,40 +176,6 @@ const EXA_WEB_SEARCH_ADAPTER = {
         };
     },
 };
-// Dynamic public callers supply unknown inputs; validate them before entering typed providers.
-const WEB_SEARCH_PROVIDER_ADAPTERS = {
-    brave: {
-        provider: "brave",
-        buildRequest: BRAVE_WEB_SEARCH_ADAPTER.buildRequest,
-        fetchJson(request, apiKey, signal) {
-            if (!(request instanceof URL)) {
-                throw new Error("Brave search request must be a URL");
-            }
-            return BRAVE_WEB_SEARCH_ADAPTER.fetchJson(request, apiKey, signal);
-        },
-        normalizeResponse(response, params) {
-            return BRAVE_WEB_SEARCH_ADAPTER.normalizeResponse(parseBraveSearchResponse(response), params);
-        },
-    },
-    exa: {
-        provider: "exa",
-        buildRequest: EXA_WEB_SEARCH_ADAPTER.buildRequest,
-        fetchJson(request, apiKey, signal) {
-            if (!isRecord(request) ||
-                !isRecord(request.body) ||
-                typeof request.timeoutMs !== "number") {
-                throw new Error("Exa search request must contain a body and timeout");
-            }
-            return fetchExaSearchJson(request.body, apiKey, signal, request.timeoutMs);
-        },
-        normalizeResponse(response, params) {
-            return EXA_WEB_SEARCH_ADAPTER.normalizeResponse(parseExaSearchResponse(response), params);
-        },
-    },
-};
-export function getWebSearchProviderAdapter(provider) {
-    return WEB_SEARCH_PROVIDER_ADAPTERS[provider];
-}
 /** Build before queueing so local validation fails without consuming a request slot. */
 export function prepareWebSearchRequest(provider, params, apiKey, signal) {
     if (provider === "exa") {

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

@@ -1,4 +1,4 @@
-import { cleanSearchText, getProviderLabel } from "./web-search-results.js";
+import { getProviderLabel } from "./web-search-results.js";
 export const SEARCH_REQUEST_TIMEOUT_MS = 15_000;
 export const WEB_SEARCH_MIN_REQUEST_INTERVAL_MS = 1_100;
 function sleepWithAbort(ms, signal) {
@@ -29,27 +29,21 @@ function sleepWithAbort(ms, signal) {
     });
 }
 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;
+                : Date.now() - this.lastRequestStartedAt;
             const waitMs = Math.max(0, WEB_SEARCH_MIN_REQUEST_INTERVAL_MS - elapsedMs);
             if (waitMs > 0) {
-                await this.sleep(waitMs, signal);
+                await sleepWithAbort(waitMs, signal);
             }
             if (signal?.aborted === true) {
                 signal.throwIfAborted();
             }
-            this.lastRequestStartedAt = this.now();
+            this.lastRequestStartedAt = Date.now();
             return task();
         };
         const result = this.tail.then(runTask, runTask);
@@ -59,20 +53,19 @@ export class WebSearchRequestGate {
         return result;
     }
 }
-function redactSearchSecret(text, apiKey) {
-    return apiKey.length > 0 ? text.split(apiKey).join("[REDACTED]") : text;
-}
 function formatSearchHttpError(options) {
-    const { provider, status, statusText, body, apiKey } = options;
+    const { provider, status } = options;
     const providerLabel = getProviderLabel(provider);
-    const errorPreview = cleanSearchText(redactSearchSecret(body, apiKey), 300);
     if (status === 429) {
-        const preview = errorPreview !== undefined
-            ? ` 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 rate limit exceeded (HTTP 429). Do not issue parallel or repeated agent_browser_web_search calls; use one high-signal query, inspect those results, then wait before retrying or ask the user to adjust their ${providerLabel} API plan/limits.`;
+    }
+    if (status === 401 || status === 403) {
+        return `${providerLabel} search failed with HTTP ${status}: Check your API credential and permissions.`;
     }
-    return `${providerLabel} search failed with HTTP ${status}: ${errorPreview !== undefined ? redactSearchSecret(errorPreview, apiKey) : statusText}`;
+    if (status >= 500) {
+        return `${providerLabel} search failed with HTTP ${status}: Provider unavailable; retry later.`;
+    }
+    return `${providerLabel} search failed with HTTP ${status}: Request rejected; check the search parameters.`;
 }
 export async function fetchSearchJson(options) {
     if (options.signal?.aborted === true) {
@@ -84,21 +77,22 @@ export async function fetchSearchJson(options) {
     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) {
+            await response.body?.cancel().catch(() => {
+                // Disposal errors must not replace the source-free HTTP diagnostic.
+            });
             throw new Error(formatSearchHttpError({
                 provider: options.provider,
                 status: response.status,
-                statusText: response.statusText,
-                body: text,
-                apiKey: options.apiKey,
             }));
         }
+        const text = await response.text();
         try {
             return JSON.parse(text);
         }
-        catch (error) {
-            throw new Error(`${options.invalidJsonMessage}: ${error instanceof Error ? error.message : "Unknown JSON parse failure"}`, { cause: error });
+        catch {
+            // Parser messages and causes can include partial credentials from the response body.
+            throw new Error(options.invalidJsonMessage);
         }
     }
     finally {

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

@@ -1,5 +1,5 @@
-import { JsonSchema } from "./json-schema.js";
-import { StringEnum as localStringEnum } from "./string-enum-schema.js";
+import { JsonSchema as Type } from "./json-schema.js";
+import { StringEnum } from "./string-enum-schema.js";
 import { DEFAULT_WEB_SEARCH_PROVIDER, EXA_SEARCH_TYPES, WEB_SEARCH_PROVIDERS, } from "./config.js";
 export const DEFAULT_SEARCH_RESULT_COUNT = 5;
 export const MAX_SEARCH_RESULT_COUNT = 10;
@@ -14,7 +14,7 @@ const EXA_SEARCH_CATEGORIES = [
 ];
 const MAX_EXA_DOMAIN_FILTERS = 20;
 const MAX_EXA_ADDITIONAL_QUERIES = 10;
-function createExaFilterProperties(Type, StringEnum) {
+function createExaFilterProperties() {
     return {
         includeDomains: Type.Optional(Type.Array(Type.String({ minLength: 1 }), {
             minItems: 1,
@@ -39,7 +39,7 @@ function createExaFilterProperties(Type, StringEnum) {
         })),
     };
 }
-export function createAgentBrowserWebSearchParamsSchema(Type = JsonSchema, StringEnum = localStringEnum) {
+export function createAgentBrowserWebSearchParamsSchema() {
     return Type.Object({
         query: Type.String({
             minLength: 1,
@@ -51,7 +51,7 @@ export function createAgentBrowserWebSearchParamsSchema(Type = JsonSchema, Strin
         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.",
         })),
-        ...createExaFilterProperties(Type, StringEnum),
+        ...createExaFilterProperties(),
         count: Type.Optional(Type.Integer({
             minimum: 1,
             maximum: MAX_SEARCH_RESULT_COUNT,

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

@@ -1,6 +1,9 @@
 import { AGENT_BROWSER_NAMESPACE, AGENT_BROWSER_OUTPUT_SCHEMA, finalizeAgentBrowserNativeResult, } from "./native-output.js";
 import { redactSensitiveText } from "./runtime.js";
-import { 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";
@@ -8,7 +11,7 @@ import { dedupeSearchResults, formatSearchResults, } from "./web-search-results.
 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, getWebSearchProviderAdapter, } from "./web-search-providers.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";
 function buildMissingCredentialError(provider) {
@@ -91,8 +94,16 @@ async function runWebSearch(state, params, gate, signal) {
         duplicatesRemoved: duplicatesRemoved > 0 ? duplicatesRemoved : undefined,
     };
 }
-async function presentSearchSuccess(details, params) {
-    const duplicateNotice = details.duplicatesRemoved !== undefined
+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 duplicateNotice = typeof details.duplicatesRemoved === "number"
         ? `\n\nDuplicate URLs removed: ${details.duplicatesRemoved}.`
         : "";
     const result = await finalizeAgentBrowserNativeResult({
@@ -110,6 +121,13 @@ async function presentSearchSuccess(details, params) {
         ? { ...result, details }
         : { ...result, details: { ...details, artifactManifest: finalizedManifest } };
 }
+function isNormalizedSearchResult(value) {
+    if (!isRecord(value) || typeof value.title !== "string" || typeof value.url !== "string") {
+        return false;
+    }
+    return (["description", "source", "age", "pageDate", "language"].every((field) => value[field] === undefined || typeof value[field] === "string") &&
+        (value.highlights === undefined || isStringArray(value.highlights)));
+}
 function failureCategory(error, signal) {
     if (signal?.aborted === true) {
         return "aborted";

package/docs/ARCHITECTURE.md

@@ -197,6 +197,7 @@ Practical policy:
 - record successful `connect`, `--cdp`, enabled `--auto-connect`, environment-configured CDP/auto-connect, and wrapper Electron attachment identities in branch-visible state. First-use and later content-bearing calls live-check `get url` because attached targets can drift outside Pi. Caller config, file access, launch arguments, and environment pass through unchanged; only wrapper-injected compatibility launch arguments are omitted on active attachments. A terminal successful close removes the marker; a close followed by a later step whose lifecycle reports a browser launch preserves it, while a non-launching diagnostic such as `stream status` leaves the close terminal
 - when a successful close targets the current extension-managed session, including an explicit `--session <current> close` or an `electron.cleanup` managed-session step, clear page/ref state, mark that session inactive, untrack cleanup ownership, and rotate the next default auto call to a fresh wrapper-generated session name rather than reusing the closed name
 - on non-quit shutdown such as `/reload`, close off-branch owned managed sessions and off-branch owned Electron launches before clearing process-local ownership, but preserve the current branch-visible active managed session and Electron launch plus that launch's isolated `userDataDir` so reload continuity still works from the active transcript branch. First reuse of a restored Electron attachment checks the recorded namespace/session, live PID/profile presence, and exact browser WebSocket identity against current CDP metadata, then uses upstream `get cdp-url` to verify that the named daemon still targets that browser or one of its current pages. The metadata probe cannot commit daemon provenance merely by spawning; only a matching result permits the existing policy to record it. Ordinary calls, status, and probe share this path under the existing lock. Generic restore-disabled sessions, mismatched connections, quit, and off-branch cleanup are unchanged
+- require a nonempty, non-whitespace `Browser`/`browser` string in `/json/version` for Electron CDP readiness and debug-port liveness; other version metadata is optional. Before signaling a live restored Electron PID without a tracked child handle, require the process start identity recorded at launch to match the live process (the same `process-identity.ts` PID-reuse proof used for execution claims and temp-root ownership); a missing, unreadable, or mismatched identity retains the process/profile
 - expose still-owned off-branch Electron launch records to `electron.status { launchId }`, `electron.status { all: true }`, `electron.probe { launchId }`, and `electron.cleanup`, while leaving default `electron.probe` scoped to the current managed session
 - if an unnamed fresh launch replaces an active extension-managed session, best-effort close the old managed session after the switch succeeds; `managedSessionOutcome.replacedSessionClosed` records whether that cleanup succeeded, and a failed close keeps the older identity wrapper-owned across transcript resume for explicit follow-up or cleanup
 - expose `details.browserWindow` and one visible login handoff only when a successful first/fresh local wrapper-managed headed result, including `batch`, is not an attachment and has upstream `lifecycle.effectiveLaunch.browserLaunched: true` and a `created`/`replaced` managed-session outcome. Keep `visibility: "unverified"`: this is launch evidence, never a claim about the user's OS desktop
@@ -205,12 +206,12 @@ Practical policy:
 - once the wrapper observes tab-drift risk for a session (profile restore correction, overlapping stale opens, or restored session state), later active-tab commands verify the intended tab under the existing session queue before semantic/ref helpers and user commands. Targets retain native CDP `targetId` across transcript replay; exact identity distinguishes duplicate URL/title tabs, while older targets without an ID keep URL-based matching. A cold managed reopen replaces the old ID. Native selection runs only when the intended tab is not already active, because upstream selection clears refs and frame scope even on same-tab reselection. Missing targets, failed selection, and post-selection target mismatches fail before user commands. Caller argv/stdin and native `--pin-tab` / `--no-pin-tab` preferences remain unchanged. Local commands, live `get url`, explicit HTTP `read <url>` (including its flags), URL `a11y`/`vitals`/`web-vitals`, `diff url`, `window new`, URL-bearing recording commands, and explicit tab/navigation/`connect`/`state load` recovery do not require the old target; history back/forward/reload, `pushstate`, and page-content operations still do. The same classifier scans effective batch rows past non-page prefixes until a page dependency or explicit context change, without rewriting user rows or changing bail behavior. For `window new` and `diff url`, observe the resulting URL instead of retaining the old target or treating the requested second URL as redirect evidence. Fold only reached native batch rows when available, discard targets before failed navigation/context transitions and live-verify the final page, discard observations and refs from before window/diff transitions, and let later successful snapshots rebuild refs even when another batch row fails. Retain an observed blank destination after either command instead of recovering the old page; if no final target is observed, use the existing unknown-target state. Caller batch arguments, stdin and bail behavior stay unchanged. Successful batches containing navigation-observable actions use the same final live page/identity observation as direct actions, so same-address popup tabs replace the pre-batch target before later pinning. Terminal batch closes do not trigger a page probe, and pending WebMCP targets remain unknown. Routine same-session commands avoid `tab list` preflights
 - for sessions with observed tab-drift risk, after a successful command on a known tab target, the wrapper may best-effort restore that same target again if restored/background tabs steal focus after the command returns; routine same-session commands skip focus correction, while observed pages without a returned native ID use `tab list` to establish current identity rather than inheriting an earlier tab's ID
 - after successful tab creation, selection, or close, including dispatched native batch rows, read the now-active URL and fresh non-blank title—even when two tabs share a URL—before updating per-session page state; retain the deliberate blank target instead of treating it as accidental drift
-- keep a per-session `refSnapshot` aligned with the last successful `snapshot` (including refs merged from a successful `batch` by taking the last successful `snapshot` step in batch result order): restore its once-stored ancestral definition when reloading, resuming, or moving to a different Pi session-tree branch, retain full membership and accessible metadata from that capture for wrapper-side diagnostics, drop it on successful close commands (`close`, `quit`, or `exit`), replace it with a persisted `page-transition` invalidation after any upstream-executed `record start` attempt (direct or batch; older supported natives can swap the page before their already-active check, so failed starts count; the warning and persisted summary explicitly describe conservative ref invalidation, not an observed page change), a `record restart` with a URL operand, `window new`, `diff url`, or WebMCP `invoke` / `result` / `cancel` (these page-provided tools can mutate, rerender, or navigate; when a spawned `batch` yields no parseable result rows, for example after a wrapper timeout, planned transition steps still record the invalidation), or after a failed transition command (`eval`, `back`, `forward`, `reload`, `connect`, `state load`, `tab` selection), including reached batch transitions and failed batch `open` rows whose live URL re-verification probe observed the page (a failed transition can still have mutated or replaced the document before throwing, so keeping the verified URL must not keep the prior refs; transcript replay preserves the persisted invalidation summary), and refuse page-scoped `@e…` argv before spawn when the active tab URL no longer matches the snapshot URL, when a ref id was never in that snapshot, when the snapshot state is invalidated, or when a `batch` step would reuse `@e…` on a guarded getter or mutation step after an earlier invalidating step (including `record start`, URL-bearing `record restart`, and WebMCP `invoke` / `result` / `cancel`) without a later `snapshot` step in the same plan; batch steps come from the source upstream actually executes (raw batch argument strings exclusively when any exist — filtering only the exact `--bail` token like upstream — stdin only otherwise, via `getUpstreamEffectiveBatchSteps` in `extensions/agent-browser/lib/orchestration/batch-stdin.ts`); tab recovery (which leaves user argv/stdin and continue-on-error control flow unchanged), artifact/recording preflight, batch screenshot path preparation (parent directories are created for effective raw rows too, without rewriting raw strings), and stale-ref echo args use that same selection so pinning and preflights cannot act on upstream-ignored stdin, while the pre-spawn state-policy validator deliberately keeps scanning parseable stdin alongside argv as a fail-closed content superset and treats stdin parse failures as fatal only when upstream would actually read stdin (its raw-token filter also uses the exact `--bail` token only). Same-snapshot `fill @e…` rows are guarded but do not themselves set that invalidation latch, so ordinary form fills can precede a click/submit row in one batch—see [`TOOL_CONTRACT.md`](TOOL_CONTRACT.md#details) for the agent-visible contract and failure text; typed per-session tab/ref/pinning state lives in `extensions/agent-browser/lib/session-page-state.ts` and is updated by `orchestration/extension-observation.ts` after each tool result
+- keep a per-session `refSnapshot` aligned with the last successful `snapshot` (including refs merged from a successful `batch` by taking the last successful `snapshot` step in batch result order): restore its once-stored ancestral definition when reloading, resuming, or moving to a different Pi session-tree branch, retain full membership and accessible metadata from that capture for wrapper-side diagnostics, drop it on successful close commands (`close`, `quit`, or `exit`), replace it with a persisted `page-transition` invalidation after any upstream-executed `record start` attempt (direct or batch; older supported natives can swap the page before their already-active check, so failed starts count; the warning and persisted summary explicitly describe conservative ref invalidation, not an observed page change), a `record restart` with a URL operand, `window new`, `diff url`, or WebMCP `invoke` / `result` / `cancel` (these page-provided tools can mutate, rerender, or navigate; when a spawned `batch` yields no parseable result rows, for example after a wrapper timeout, planned transition steps still record the invalidation), or after a failed transition command (`eval`, `back`, `forward`, `reload`, `connect`, `state load`, `tab` selection), including reached batch transitions and failed batch `open` rows whose live URL re-verification probe observed the page (a failed transition can still have mutated or replaced the document before throwing, so keeping the verified URL must not keep the prior refs; transcript replay preserves the persisted invalidation summary), and refuse page-scoped `@e…` argv before spawn when the active tab URL no longer matches the snapshot URL, when a ref id was never in that snapshot, when the snapshot state is invalidated, or when a `batch` step would reuse `@e…` on a guarded getter or mutation step after an earlier invalidating step (including `record start`, URL-bearing `record restart`, and WebMCP `invoke` / `result` / `cancel`) without a later `snapshot` step in the same plan; the latch scan covers the whole plan, including rows after its first snapshot even when no earlier refs exist, so a non-form click between snapshot and ref getter still requires another snapshot. Batch steps come from the source upstream actually executes (raw batch argument strings exclusively when any exist — filtering only the exact `--bail` token like upstream — stdin only otherwise, via `getUpstreamEffectiveBatchSteps` in `extensions/agent-browser/lib/orchestration/batch-stdin.ts`); tab recovery (which leaves user argv/stdin and continue-on-error control flow unchanged), artifact/recording preflight, batch screenshot path preparation (parent directories are created for effective raw rows too, without rewriting raw strings), and stale-ref echo args use that same selection so pinning and preflights cannot act on upstream-ignored stdin, while the pre-spawn state-policy validator deliberately keeps scanning parseable stdin alongside argv as a fail-closed content superset and treats stdin parse failures as fatal only when upstream would actually read stdin (its raw-token filter also uses the exact `--bail` token only). Same-snapshot `fill @e…` rows are guarded but do not themselves set that invalidation latch, so ordinary form fills can precede a click/submit row in one batch—see [`TOOL_CONTRACT.md`](TOOL_CONTRACT.md#details) for the agent-visible contract and failure text; typed per-session tab/ref/pinning state lives in `extensions/agent-browser/lib/session-page-state.ts` and is updated by `orchestration/extension-observation.ts` after each tool result
 - native 0.37 owns first-document setup inheritance for new tabs; the wrapper does not copy headers, user agents or other browser setup itself. The page-summary formatter displays native positive WebMCP availability while retaining raw details; it adds no discovery probe
 - when a direct or batched WebMCP call returns `status: "pending"`, or `result` / `cancel` fails while that target is unknown, keep its tab target unknown and discard same-call snapshot evidence instead of treating an immediate post-dispatch URL probe as stable; `webmcp result` / `cancel`, `get url`, and explicit navigation remain available while unknown; replace the generic blocked snapshot action with `verify-page-target-after-pending-webmcp` (`get url`), and let a completed `batch --bail` use that verification before `snapshot -i` to re-establish both target and refs
 - for top-level non-Electron direct `click` commands with an eligible target, install a bounded in-page target-specific event probe before upstream runs; if upstream reports success but no trusted pointer/mouse/click event reached the resolved target, fail the tool and report `details.clickDispatch` with explicit retry/inspect next actions (the wrapper does not replay clicks in-page). The probe covers `xpath=` targets and current `@e…` / `ref=` refs whose latest stored `refSnapshot.refs` role is `button`, `checkbox`, `menuitem`, `radio`, `switch`, or `tab`; it requires a unique role/name in the saved snapshot and the live candidates instead of taking a fresh pre-click snapshot that could recycle upstream refs. Ref and XPath candidates must additionally prove identity through a per-probe temporary DOM attribute read back by native `get attr <original-selector> <marker>`. Missing or mismatched identity, including XPath/frame scope mismatches, cleans up the probe and lets native click run without dispatch verification; candidate naming heuristics alone are never proof. Duplicate-name refs pass through without a probe: their old ordinal is not target identity. The probe is intentionally skipped when the effective native confirmation list guards `evaluate`, avoiding an optional-eval approval loop without bypassing native click policy. Dynamic action-policy files stay native-owned. It is also skipped for CSS selector clicks, unresolved `find … click` locators, and `batch`/`qa` click steps
 - skip unrelated tools and harmless Bash inspections before building prompt policy. Seed the latest raw user message on start/tree, update it on user `message_end`, and re-read its current content before parsing policy so native content replacement cannot leave stale intent. Capture that policy at queued admission without a whole-branch scan on every event. Derive narrow prompt guards only for concrete evidence invariants: explicitly requested screenshot/recording output paths block browser close until the artifact manifest verifies those paths, while bare inbound attachment paths remain inputs. The wrapper intentionally does not infer broad business/user intent from prompt text such as order/payment/post boundaries; agents must follow those instructions themselves. The artifact guard is bounded preflight policy (`details.promptGuard`, `failureCategory: "policy-blocked"`), not a reusable browser recipe layer
-- keep the existing page/selector scroll API; explicit CSS-container movement uses `Element.scrollBy` with `behavior: "instant"` before measuring offsets so smooth-scroll CSS cannot cause a premature no-movement failure
+- keep the existing page/selector scroll API; shims intercept only complete recognized shapes (`scroll to end|top` with exactly three tokens, or CSS-container scroll with three/four), passing surplus operands through to native execution without dropping them. Explicit CSS-container movement uses `Element.scrollBy` with `behavior: "instant"` before measuring offsets so smooth-scroll CSS cannot cause a premature no-movement failure
 - reject direct and effective batch `scrollintoview text=...` / `scrollinto text=...` before dispatch because current upstream can falsely report success without movement, while leaving help forms untouched; return only native recovery (`find text ... hover` or fresh snapshot/ref), leaving CSS, XPath, and current-ref behavior upstream-owned
 - after successful `get text` on a qualifying non-ref CSS selector, optionally issue one read-only `eval --stdin` probe per selector when multiple DOM matches or a hidden first match with visible peers could misread tabbed or off-screen content; simple id selectors and sensitive-looking literals skip this probe. Merge `details.selectorTextVisibility` / `selectorTextVisibilityAll`, visible warning lines, and `inspect-visible-text-candidates*` next actions as documented in [`TOOL_CONTRACT.md`](TOOL_CONTRACT.md#details) and `RQ-0074` in [`SUPPORT_MATRIX.md`](SUPPORT_MATRIX.md)
 - caller-owned sessions honor native `AGENT_BROWSER_SOCKET_DIR` unless `PI_AGENT_BROWSER_SOCKET_DIR` overrides it, with the same socket integrity checks. For other local Unix launches, set a short private socket directory so extension-generated session names do not fail on the upstream Unix socket-path length limit; require the selected path to be absolute, owned by the current uid, mode `0700`, under checked ancestry, and free of symlink, foreign-owner, or special planted entries; reject pre-existing unsafe modes instead of repairing them, then recheck before spawn. The actual filesystem root `/` is supplied by the trusted operating environment: a directory without group/other write bits is accepted regardless of its reported owner, which can be unmapped in a Linux user namespace. Existing root-owned sticky-directory acceptance is unchanged. This boundary does not protect against whoever controls the root filesystem. Every non-root ancestor still needs trusted ownership and permissions, including the destination ancestry of root-owned aliases; a matching overflow UID is not trusted. Android/Termux uses `/data/data/<package>/piab`, treats the owner-only app-data directory as the trust anchor, permits the app's matching private uid/gid ancestry, compacts generated managed identities to one 80-bit digest so ordinary namespace plus fresh-session paths remain within the limit, and places policy-lock coordination under `os.tmpdir()` because Android `/tmp` is shell-owned and inaccessible