pi-agent-browser-native 0.9.2 → 0.9.4

package/dist/extensions/agent-browser/lib/pi-tool-rendering.js

@@ -1,14 +1,20 @@
 import { getKeybindings, Text, truncateToWidth } from "@earendil-works/pi-tui";
 import { compileAgentBrowserElectron } from "./input-modes/electron.js";
 import { compileAgentBrowserQaPreset } from "./input-modes/job.js";
-import { compileAgentBrowserNetworkSourceLookup, compileAgentBrowserSourceLookup } from "./input-modes/lookups.js";
+import { compileAgentBrowserNetworkSourceLookup, compileAgentBrowserSourceLookup, } from "./input-modes/lookups.js";
 import { compileAgentBrowserSemanticAction } from "./input-modes/semantic-action.js";
 import { isRecord } from "./parsing.js";
-import { redactInvocationArgs } from "./runtime.js";
+import { redactInvocationArgs } from "./runtime-redaction.js";
+import { isBooleanFlagEnabled } from "./argv-grammar.js";
 const TUI_INVOCATION_PREVIEW_MAX_CHARS = 160;
 const TUI_COLLAPSED_OUTPUT_MAX_LINES = 12;
-const ANSI_CONTROL_SEQUENCE_PATTERN = /\x1B(?:\][^\x07\x1B\r\n\u2028\u2029]*(?:\x07|\x1B\\)|\[[0-?]*[ -/]*[@-~]|P[^\x1B\r\n\u2028\u2029]*(?:\x1B\\)|_[^\x1B\r\n\u2028\u2029]*(?:\x1B\\)|\^[^\x1B\r\n\u2028\u2029]*(?:\x1B\\)|[@-Z\\-_])/g;
-const JSON_TOKEN_PATTERN = /"(?:\\.|[^"\\])*"(?=\s*:)|"(?:\\.|[^"\\])*"|-?\d+(?:\.\d+)?(?:[eE][+-]?\d+)?|true|false|null|[{}\[\],:]/g;
+const ANSI_CONTROL_SEQUENCE_PATTERN = 
+// Strip terminal escape/control sequences from untrusted browser text, not printable content.
+// oxlint-disable-next-line no-control-regex
+/\x1B(?:\][^\x07\x1B\r\n\u2028\u2029]*(?:\x07|\x1B\\)|\[[0-?]*[ -/]*[@-~]|P[^\x1B\r\n\u2028\u2029]*(?:\x1B\\)|_[^\x1B\r\n\u2028\u2029]*(?:\x1B\\)|\^[^\x1B\r\n\u2028\u2029]*(?:\x1B\\)|[@-Z\\-_])/g;
+const JSON_TOKEN_PATTERN = /"(?:\\.|[^"\\])*"(?=\s*:)|"(?:\\.|[^"\\])*"|-?\d+(?:\.\d+)?(?:[eE][+-]?\d+)?|true|false|null|[{}[\],:]/g;
+// Replace C0/C1 display controls so browser text cannot execute terminal controls.
+// oxlint-disable-next-line no-control-regex
 const UNSAFE_DISPLAY_CONTROL_PATTERN = /[\x00-\x08\x0B\x0C\x0E-\x1F\x7F\x80-\x9F]/g;
 const UNSAFE_DISPLAY_DIRECTIONAL_PATTERN = /[\u061C\u200E\u200F\u202A-\u202E\u2066-\u2069]/g;
 const UNSAFE_DISPLAY_ZERO_WIDTH_PATTERN = /[\u200B-\u200D\u2060\uFEFF]/g;
@@ -18,8 +24,11 @@ function sanitizeDisplayText(value, markRemovedSequences = false) {
         .replace(ANSI_CONTROL_SEQUENCE_PATTERN, markRemovedSequences ? "�" : "")
         .replace(UNSAFE_DISPLAY_CONTROL_PATTERN, "�")
         .replace(UNSAFE_DISPLAY_DIRECTIONAL_PATTERN, "�");
-    if (markRemovedSequences)
-        sanitized = sanitized.replace(/[\u2028\u2029]/g, "\n").replace(UNSAFE_DISPLAY_ZERO_WIDTH_PATTERN, "�");
+    if (markRemovedSequences) {
+        sanitized = sanitized
+            .replace(/[\u2028\u2029]/g, "\n")
+            .replace(UNSAFE_DISPLAY_ZERO_WIDTH_PATTERN, "�");
+    }
     return sanitized;
 }
 function replaceTabsForDisplay(value) {
@@ -34,8 +43,9 @@ function trimTrailingBlankLines(lines) {
 }
 function isJsonDocumentText(value) {
     const trimmed = value.trim();
-    if (!trimmed.startsWith("{") && !trimmed.startsWith("["))
+    if (!trimmed.startsWith("{") && !trimmed.startsWith("[")) {
         return false;
+    }
     try {
         JSON.parse(trimmed);
         return true;
@@ -44,20 +54,22 @@ function isJsonDocumentText(value) {
         return false;
     }
 }
+function jsonTokenColor(token, remainder) {
+    if (token.startsWith('"')) {
+        return /"\s*$/.test(token) && remainder.trimStart().startsWith(":")
+            ? "syntaxVariable"
+            : "syntaxString";
+    }
+    return /^[{}[\],:]$/.test(token) ? "syntaxPunctuation" : "syntaxType";
+}
 function colorizeJsonLine(line, theme) {
     let output = "";
     let cursor = 0;
     for (const match of line.matchAll(JSON_TOKEN_PATTERN)) {
         const token = match[0];
-        const index = match.index ?? 0;
+        const index = match.index;
         output += line.slice(cursor, index);
-        const color = token.startsWith('"')
-            ? /"\s*$/.test(token) && line.slice(index + token.length).trimStart().startsWith(":")
-                ? "syntaxVariable"
-                : "syntaxString"
-            : /^[{}\[\],:]$/.test(token)
-                ? "syntaxPunctuation"
-                : "syntaxType";
+        const color = jsonTokenColor(token, line.slice(index + token.length));
         output += theme.fg(color, token);
         cursor = index + token.length;
     }
@@ -70,15 +82,17 @@ function getPrimaryTextContent(result) {
 function colorizeToolOutputLines(outputText, theme, isError) {
     const normalizedLines = trimTrailingBlankLines(replaceTabsForDisplay(sanitizeDisplayText(outputText)).split("\n"));
     const normalizedText = normalizedLines.join("\n");
-    if (normalizedText.length === 0)
+    if (normalizedText.length === 0) {
         return [];
+    }
     const isJsonDocument = !isError && isJsonDocumentText(normalizedText);
     return normalizedLines.map((line) => {
         if (line.length === 0) {
             return "";
         }
-        if (isJsonDocument)
+        if (isJsonDocument) {
             return colorizeJsonLine(line, theme);
+        }
         return isError ? theme.fg("error", line) : theme.fg("toolOutput", line);
     });
 }
@@ -94,22 +108,45 @@ function formatVisualTruncationNotice(remainingLines, totalLines, theme, width)
     const notice = `${theme.fg("muted", `... (${remainingLines} more lines, ${totalLines} total, `)}${formatExpandHint(theme)}${theme.fg("muted", ")")}`;
     return truncateToWidth(notice, Math.max(0, width));
 }
+function compiledArgs(result) {
+    return result.compiled?.args ?? [];
+}
 function getStructuredModeInvocation(input) {
-    if (typeof input.code === "string")
+    if (typeof input.code === "string") {
         return { mode: "code", rawArgs: [], scriptSource: input.code };
-    if (Array.isArray(input.args))
-        return { rawArgs: input.args.filter((value) => typeof value === "string") };
-    if (input.semanticAction !== undefined)
-        return { mode: "semanticAction", rawArgs: compileAgentBrowserSemanticAction(input.semanticAction).compiled?.args ?? [] };
-    if (input.qa !== undefined)
-        return { mode: "qa", rawArgs: compileAgentBrowserQaPreset(input.qa).compiled?.args ?? [] };
-    if (input.sourceLookup !== undefined)
-        return { mode: "sourceLookup", rawArgs: compileAgentBrowserSourceLookup(input.sourceLookup).compiled?.args ?? [] };
-    if (input.networkSourceLookup !== undefined)
-        return { mode: "networkSourceLookup", rawArgs: compileAgentBrowserNetworkSourceLookup(input.networkSourceLookup).compiled?.args ?? [] };
+    }
+    if (Array.isArray(input.args)) {
+        return {
+            rawArgs: input.args.filter((value) => typeof value === "string"),
+        };
+    }
+    if (input.semanticAction !== undefined) {
+        return {
+            mode: "semanticAction",
+            rawArgs: compiledArgs(compileAgentBrowserSemanticAction(input.semanticAction)),
+        };
+    }
+    if (input.qa !== undefined) {
+        return { mode: "qa", rawArgs: compiledArgs(compileAgentBrowserQaPreset(input.qa)) };
+    }
+    if (input.sourceLookup !== undefined) {
+        return {
+            mode: "sourceLookup",
+            rawArgs: compiledArgs(compileAgentBrowserSourceLookup(input.sourceLookup)),
+        };
+    }
+    if (input.networkSourceLookup !== undefined) {
+        return {
+            mode: "networkSourceLookup",
+            rawArgs: compiledArgs(compileAgentBrowserNetworkSourceLookup(input.networkSourceLookup)),
+        };
+    }
     if (input.electron !== undefined) {
         const electron = compileAgentBrowserElectron(input.electron);
-        return { mode: "electron", rawArgs: electron.compiled ? ["electron", electron.compiled.action] : [] };
+        return {
+            mode: "electron",
+            rawArgs: electron.compiled ? ["electron", electron.compiled.action] : [],
+        };
     }
     return { rawArgs: [] };
 }
@@ -122,13 +159,27 @@ function formatInvocationPreview(rawArgs) {
 }
 function formatScriptSourceForDisplay(source, expanded) {
     const sanitizedSource = replaceTabsForDisplay(sanitizeDisplayText(source, true));
-    if (expanded)
+    if (expanded) {
         return sanitizedSource;
+    }
     const preview = sanitizedSource.replace(/\n/g, " ↵ ").replace(/\s+/g, " ").trim();
     return preview.length > TUI_INVOCATION_PREVIEW_MAX_CHARS
         ? `${preview.slice(0, TUI_INVOCATION_PREVIEW_MAX_CHARS - 3)}...`
         : preview;
 }
+function formatInvocationDetail(mode, preview, expandedCode, theme) {
+    let text = mode !== undefined && mode !== "code" ? ` ${theme.fg("accent", mode)}` : "";
+    if (mode !== undefined && expandedCode) {
+        return text + `\n${theme.fg("dim", "Source:")}\n${theme.fg("accent", preview)}`;
+    }
+    if (preview.length === 0) {
+        return text;
+    }
+    if (mode !== undefined) {
+        text += ` ${theme.fg("dim", "→")}`;
+    }
+    return text + ` ${theme.fg("accent", preview)}`;
+}
 export function formatAgentBrowserRenderCall(args, theme, expanded = false) {
     const input = isRecord(args) ? args : {};
     const { mode, rawArgs, scriptSource } = getStructuredModeInvocation(input);
@@ -136,19 +187,7 @@ export function formatAgentBrowserRenderCall(args, theme, expanded = false) {
         ? formatInvocationPreview(rawArgs)
         : formatScriptSourceForDisplay(scriptSource, expanded);
     let text = theme.fg("toolTitle", theme.bold(mode === "code" ? "agent_browser_code" : "agent_browser"));
-    if (mode) {
-        if (mode !== "code")
-            text += ` ${theme.fg("accent", mode)}`;
-        if (scriptSource !== undefined && expanded) {
-            text += `\n${theme.fg("dim", "Source:")}\n${theme.fg("accent", invocationPreview)}`;
-        }
-        else if (invocationPreview.length > 0) {
-            text += ` ${theme.fg("dim", "→")} ${theme.fg("accent", invocationPreview)}`;
-        }
-    }
-    else if (invocationPreview.length > 0) {
-        text += ` ${theme.fg("accent", invocationPreview)}`;
-    }
+    text += formatInvocationDetail(mode, invocationPreview, scriptSource !== undefined && expanded, theme);
     if (input.sessionMode === "fresh") {
         text += theme.fg("dim", " sessionMode=fresh");
     }
@@ -164,39 +203,46 @@ function formatAgentBrowserRenderResult(result, options, theme, isError) {
     const outputText = getPrimaryTextContent(result);
     const failureCategoryNotice = formatModelVisibleFailureCategoryNotice(result.details);
     const outputLines = colorizeToolOutputLines(outputText, theme, isError);
-    if (failureCategoryNotice && outputLines.length > 0) {
+    if (failureCategoryNotice !== undefined && outputLines.length > 0) {
         outputLines.unshift(theme.fg("error", failureCategoryNotice), "");
     }
     if (outputLines.length === 0) {
-        const details = isRecord(result.details) ? result.details : undefined;
-        const rawSummary = typeof details?.summary === "string" ? details.summary : isError ? "agent-browser failed" : "Done";
-        const sanitizedSummary = sanitizeDisplayText(rawSummary).trim();
-        const summary = sanitizedSummary.length > 0 ? sanitizedSummary : isError ? "agent-browser failed" : "Done";
-        return isError ? theme.fg("error", summary) : theme.fg("success", summary);
+        return formatEmptyResultSummary(result.details, theme, isError);
     }
     return `\n${outputLines.join("\n")}`;
 }
+function formatEmptyResultSummary(details, theme, isError) {
+    const fallback = isError ? "agent-browser failed" : "Done";
+    const rawSummary = isRecord(details) && typeof details.summary === "string" ? details.summary : fallback;
+    const sanitizedSummary = sanitizeDisplayText(rawSummary).trim();
+    const summary = sanitizedSummary.length > 0 ? sanitizedSummary : fallback;
+    return isError ? theme.fg("error", summary) : theme.fg("success", summary);
+}
 function formatModelVisibleFailureCategoryNotice(details) {
-    if (!isRecord(details) || details.resultCategory !== "failure")
+    if (!isRecord(details) || details.resultCategory !== "failure") {
         return undefined;
+    }
     const failureCategory = typeof details.failureCategory === "string" && details.failureCategory.length > 0
         ? details.failureCategory
         : undefined;
-    return `Result category: failure${failureCategory ? `; failureCategory: ${failureCategory}` : ""}; Pi tool isError: true.`;
+    return `Result category: failure${failureCategory !== undefined ? `; failureCategory: ${failureCategory}` : ""}; Pi tool isError: true.`;
 }
 function agentBrowserToolResultRequestedJson(result, input) {
     const details = isRecord(result.details) ? result.details : undefined;
     const detailArgs = Array.isArray(details?.args) ? details.args : undefined;
     const inputArgs = isRecord(input) && Array.isArray(input.args) ? input.args : undefined;
-    return detailArgs?.includes("--json") === true || inputArgs?.includes("--json") === true;
+    return (isBooleanFlagEnabled(detailArgs ?? [], "--json") ||
+        isBooleanFlagEnabled(inputArgs ?? [], "--json"));
 }
-function agentBrowserToolResultHasParseableJsonContent(content) {
-    return content.some((item) => {
-        if (item.type !== "text" || typeof item.text !== "string")
+function agentBrowserToolResultHasParseableJsonContent(result) {
+    return result.content.some((item) => {
+        if (item.type !== "text" || typeof item.text !== "string") {
             return false;
+        }
         const text = item.text.trim();
-        if (text.length === 0)
+        if (text.length === 0) {
             return false;
+        }
         try {
             JSON.parse(text);
             return true;
@@ -206,23 +252,32 @@ function agentBrowserToolResultHasParseableJsonContent(content) {
         }
     });
 }
-function appendModelVisibleFailureCategoryNotice(content, notice) {
+function appendModelVisibleFailureCategoryNotice(result, notice) {
+    const content = result.content;
     const noticeContent = { type: "text", text: notice };
     const textIndex = content.findIndex((item) => item.type === "text" && typeof item.text === "string");
-    if (textIndex === -1)
+    if (textIndex === -1) {
         return [noticeContent, ...content];
+    }
     const textItem = content[textIndex];
-    if (textItem.type !== "text" || typeof textItem.text !== "string" || textItem.text.includes(notice))
+    if (textItem.type !== "text" ||
+        typeof textItem.text !== "string" ||
+        textItem.text.includes(notice)) {
         return undefined;
-    return content.map((item, index) => index === textIndex
-        ? { ...item, text: `${textItem.text}\n\n${notice}` }
-        : item);
+    }
+    const updatedContent = [...content];
+    updatedContent[textIndex] = { ...textItem, text: `${textItem.text}\n\n${notice}` };
+    return updatedContent;
 }
 export function finalizeAgentBrowserFailure(result, input) {
-    const failed = result.isError === true || (isRecord(result.details) && result.details.resultCategory === "failure");
-    const preservesParseableJson = (isRecord(input) && "code" in input || agentBrowserToolResultRequestedJson(result, input)) && agentBrowserToolResultHasParseableJsonContent(result.content);
-    const notice = preservesParseableJson ? undefined : formatModelVisibleFailureCategoryNotice(result.details);
-    const content = notice ? appendModelVisibleFailureCategoryNotice(result.content, notice) : undefined;
+    const failed = result.isError === true ||
+        (isRecord(result.details) && result.details.resultCategory === "failure");
+    const preservesParseableJson = ((isRecord(input) && "code" in input) || agentBrowserToolResultRequestedJson(result, input)) &&
+        agentBrowserToolResultHasParseableJsonContent(result);
+    const notice = preservesParseableJson
+        ? undefined
+        : formatModelVisibleFailureCategoryNotice(result.details);
+    const content = notice !== undefined ? appendModelVisibleFailureCategoryNotice(result, notice) : undefined;
     return {
         ...result,
         content: content ?? result.content,
@@ -238,8 +293,19 @@ export class AgentBrowserResultComponent {
     setResult(result, options, theme, isError) {
         const details = isRecord(result.details) ? result.details : undefined;
         // Theme is a stable proxy in Pi; its resolved colors identify theme/terminal-color changes.
-        const key = [getPrimaryTextContent(result), details?.summary, details?.resultCategory, details?.failureCategory, options.isPartial, isError, theme, theme.colors, theme.fg];
-        if (!this.formatKey || key.some((value, index) => value !== this.formatKey[index])) {
+        const key = [
+            getPrimaryTextContent(result),
+            details?.summary,
+            details?.resultCategory,
+            details?.failureCategory,
+            options.isPartial,
+            isError,
+            theme,
+            theme.colors,
+            Reflect.get(theme, "fg"),
+        ];
+        const previousKey = this.formatKey;
+        if (!previousKey || key.some((value, index) => value !== previousKey[index])) {
             this.formatKey = key;
             this.setState(formatAgentBrowserRenderResult(result, options, theme, isError), options.expanded, theme);
         }

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

@@ -8,11 +8,11 @@ export function buildInstalledDocsGuideline(paths) {
 }
 export const QUICK_START_GUIDELINES = [
     "Choose agent_browser for one native command, native batch --bail with JSON-array stdin for a known fixed sequence, or agent_browser_code for loops, branches, and aggregation. Return to the model when a fresh observation needs judgment. Neither tool is a named recipe registry.",
-    "agent_browser takes args (argv after the binary), optional stdin, outputPath, timeoutMs, and sessionMode. Start with { args: [\"open\", \"<url>\"] }, then { args: [\"snapshot\", \"-i\"] }; act on current @refs and re-snapshot after navigation or DOM changes. Native commands, providers, plugins, profiles, auth, file access, and caller paths remain available through args.",
-    "Use { args: [\"batch\", \"--bail\"], stdin: \"[[\\\"fill\\\",\\\"@e1\\\",\\\"text\\\"],[\\\"click\\\",\\\"@e2\\\"]]\" } for same-snapshot form fields followed by submit. Split if a fill rerenders later fields. Add native condition waits after navigation-prone actions; a click alone does not prove the destination loaded. Avoid blind mutation retries after timeout.",
+    'agent_browser takes args (argv after the binary), optional stdin, outputPath, timeoutMs, and sessionMode. Start with { args: ["open", "<url>"] }, then { args: ["snapshot", "-i"] }; act on current @refs and re-snapshot after navigation or DOM changes. Native commands, providers, plugins, profiles, auth, file access, and caller paths remain available through args.',
+    'Use { args: ["batch", "--bail"], stdin: "[[\\"fill\\",\\"@e1\\",\\"text\\"],[\\"click\\",\\"@e2\\"]]" } for same-snapshot form fields followed by submit. Split if a fill rerenders later fields. Add native condition waits after navigation-prone actions; a click alone does not prove the destination loaded. Avoid blind mutation retries after timeout.',
     "agent_browser_code takes { code, session?, namespace?, timeoutMs?, outputPath? }. JavaScript globals are fresh for every call; the selected browser persists and is shared with agent_browser. Use await browser({ args, stdin?, timeoutMs? }), inspect result.success, and emit selected JSON instead of whole envelopes. Use emitImage(result.imageObservations[0]) only when image inspection is needed; image handles belong to the current code call. No imports or host filesystem/network/process APIs are exposed.",
-    "Example agent_browser_code: { code: 'const result = await browser({args:[\"get\",\"title\"]}); if (!result.success) { emit(result); } else { emit({title:result.data}); }' }. Native batch still avoids extra CLI processes for fixed segments inside code. Explicit session/namespace controls select the browser for this cell without changing the default browser.",
-    "Call agent_browser_tools with no fields for inventory, or { enable: [\"action\", \"qa\", \"electron\", \"source\", \"network\"] } for advanced native tools. It adds agent_browser_action, agent_browser_qa, agent_browser_electron, agent_browser_source, and agent_browser_network_source without disabling other tools. The browser instructions cover these capabilities; activation reveals their selected tool declarations.",
+    'Example agent_browser_code: { code: \'const result = await browser({args:["get","title"]}); if (!result.success) { emit(result); } else { emit({title:result.data}); }\' }. Native batch still avoids extra CLI processes for fixed segments inside code. Explicit session/namespace controls select the browser for this cell without changing the default browser.',
+    'Call agent_browser_tools with no fields for inventory, or { enable: ["action", "qa", "electron", "source", "network"] } for advanced native tools. It adds agent_browser_action, agent_browser_qa, agent_browser_electron, agent_browser_source, and agent_browser_network_source without disabling other tools. The browser instructions cover these capabilities; activation reveals their selected tool declarations.',
     "Use read <url> for readable web text; get title/url, get text/html/value/count <selector>, or get attr <selector> <name> for targeted state. For eval --stdin, put JavaScript in stdin and return the desired value. outputPath saves result data and must differ from screenshot/download/recording paths. Use --json only when JSON text is needed.",
     "For artifacts, verify artifactVerification and artifacts before reporting success. A pending recording is not verified output; install ffmpeg before starting and pair start with stop. Native download owns the click and saves Blob/redirect downloads. Close keeps explicitly saved files. Save promptGuard-required paths before close. Screenshot pixels are not browser CSS coordinates: use imageObservations geometry (dimensions, viewport, crop/origin, scroll and DPR) before any visual-coordinate action; full-page and element captures are not current-viewport coordinates, and Pi resizing only maps sent pixels to original image pixels. Lightpanda images are text-rendered, not graphical layout; rendering:text never supports CSS/mouse-coordinate input.",
     "Follow model-visible nextActions when present, including identity and stdin, instead of guessing commands. Treat native pending confirmations and unknown mutation outcomes as inspection boundaries. For dense snapshots, inspect Omitted high-value controls before reading a full spill.",
@@ -62,7 +62,7 @@ export const SHARED_BROWSER_PLAYBOOK_GUIDELINES = [
     "After a successful `connect`, `--cdp`, or enabled `--auto-connect` call, verify with get url and keep using the resulting session without repeating the attach flag. The wrapper remembers that attachment across active-branch reload/resume and live-checks the URL before later page reads/interactions because an attached browser can drift externally; caller config, file access, launch arguments, and environment pass through unchanged. A successful close clears the marker. When several named sessions share one Chrome, pass --pin-tab once (AGENT_BROWSER_PIN_TAB) so a closed bound tab fails as tab_gone instead of acting on a neighbor; recover with tab new or tab list. --no-pin-tab turns the sticky pin off. tab list includes each tab's CDP targetId, accepted as a tab ref.",
     `If you already used the implicit session and now need launch-scoped flags (${LAUNCH_SCOPED_FLAG_LABEL}), retry with top-level sessionMode set to fresh or pass an explicit --session for the new launch; never pass --session-mode inside args. After a successful unnamed fresh launch, later auto calls follow that new session.`,
     "Chrome is the default. Use separately installed Lightpanda only when explicitly selected with --engine lightpanda, environment or native config; --engine is launch-scoped, so use sessionMode:fresh to change a managed browser. Lightpanda text-rendered screenshots do not prove graphical layout/visibility or mouse coordinates. Chrome profiles, headed mode, multi-tab, WebGPU and native WebMCP are not parity capabilities; choose Chrome explicitly when needed, never assume automatic fallback.",
-    "For WebGPU pages, use args [\"--webgpu\", \"open\", \"<url>\"] on a fresh local browser launch; use doctor --webgpu (or --headed on Linux/Windows capture paths) to prove rendering before trusting a non-black screenshot. WebGPU cannot be combined with --cdp, --auto-connect, or provider launches unless --webgpu false overrides an enabled config/environment default.",
+    'For WebGPU pages, use args ["--webgpu", "open", "<url>"] on a fresh local browser launch; use doctor --webgpu (or --headed on Linux/Windows capture paths) to prove rendering before trusting a non-black screenshot. WebGPU cannot be combined with --cdp, --auto-connect, or provider launches unless --webgpu false overrides an enabled config/environment default.',
     "For experimental WebMCP page tools, use webmcp list, then webmcp invoke <tool> with --params and optional --frame/--detach/--timeout; use webmcp result or cancel for detached calls. Locally managed Chrome enables WebMCP by default; a positive navigation hint means the page has tools to list. --no-webmcp is launch-scoped and requires a fresh session; invoke/result/cancel can mutate or navigate, so refresh snapshot refs afterward.",
     "For --allowed-domains, use a fresh local Chrome context. Upstream rejects CDP/auto-connect, profiles, restore/state replay, direct-page providers, iOS/Safari, and startup/profile Chrome args because they cannot guarantee containment; Chromium also disables RTCPeerConnection while the allowlist is active.",
     "For React introspection, launch the page with --enable react-devtools before first navigation, then use react tree, react inspect <fiberId>, agent_browser_source candidates for local UI source hints, react renders start/stop, or react suspense; agent_browser_source is experimental and reports confidence/evidence instead of guaranteed DOM-to-file mappings. For failed fetches and APIs, agent_browser_network_source (experimental) correlates failed network requests with initiator metadata and bounded workspace URL literals—candidates only, not definitive blame. Use vitals [url] for Core Web Vitals and hydration timing, and pushstate <url> for client-side SPA navigation.",
@@ -71,17 +71,17 @@ export const SHARED_BROWSER_PLAYBOOK_GUIDELINES = [
     "Upstream restore sessions periodically autosave cookies and localStorage while the browser stays open, including page-driven background changes; AGENT_BROWSER_AUTOSAVE_INTERVAL_MS controls the interval (30000 by default; 0 disables periodic saves but keeps save-on-close), while the never value for --restore-save disables automatic saves for that restore session. For wrapper-owned headed launches, the wrapper defaults the interval to 0 because upstream 0.33.2 collects multi-origin storage through visible temporary tabs, then records and reapplies the effective launch-time value to helpers and follow-ups so daemon configuration remains stable. Native close still saves, but direct window close can lose newer state because upstream exempts headed browsers from idle shutdown; set AGENT_BROWSER_AUTOSAVE_INTERVAL_MS before launch when periodic preservation matters, because changing it on a running wrapper-owned headed session requires close plus a fresh launch.",
     "For batch chains that touch cookies, storage, auth, or other secret-bearing commands, use details.batchSteps for per-step artifacts, categories, spill paths, and full structured errors; top-level details.data on batch is only a compact redacted step matrix (success, argv-redacted command, redacted result or scrubbed error text) built from the same presentation rules as standalone calls.",
     "For non-core families, pass current upstream commands through the native tool directly: network requests, network route <url>, network har start/stop [path], diff snapshot, diff screenshot --baseline <file>, diff url <u1> <u2>, trace start, trace stop [path], profiler start, profiler stop [path], record start <path>, record stop, console/errors [--clear], highlight <selector>, inspect, clipboard read, clipboard write <text>, clipboard copy/paste, stream enable/disable/status, dashboard start/stop, device list for iOS simulator inventory, and chat <message>. For compact network requests output, prefer details.nextActions for request detail, route-mock diagnostics, actionable failed-request agent_browser_network_source, filtering, clearing the aggregate buffer before repro, or HAR capture follow-ups instead of guessing request-id syntax. Artifact-producing commands report details.artifacts and verification state; long-running starts such as stream, dashboard, trace/profiler, and record should be paired with the matching stop/disable command when the task is done; stream enable already-enabled outcomes are treated as idempotent success with status/disable follow-ups.",
-    "For Electron desktop apps, enable agent_browser_electron through agent_browser_tools for wrapper-owned discovery, isolated launch, status, compact probe, and cleanup: list first, treat likely-sensitive annotations as hints rather than enforcement, launch with the default snapshot handoff unless handoff: \"tabs\" is the safer diagnostic starting point, use agent_browser_electron probe or snapshot -i/agent_browser_qa attached:true for current-session state, and always cleanup the returned launchId when done. agent_browser_electron launch uses an isolated temporary profile; it does not reuse the app's normal signed-in profile or attach to an already-running authenticated app. For signed-in local app state, host-launch the normal app with --remote-debugging-port when appropriate, then use raw args connect <port|url>; after connect, run get url to verify the active target before page-content reads, inspect tab list, select the stable tab id such as tab t2, verify it again with get url, then run a condition wait or snapshot -i before using refs. close commands (`close`, `quit`, or `exit`) only close the browser/CDP session; leave manually launched app shutdown, profile cleanup, and explicit artifacts to the host owner.",
+    'For Electron desktop apps, enable agent_browser_electron through agent_browser_tools for wrapper-owned discovery, isolated launch, status, compact probe, and cleanup: list first, treat likely-sensitive annotations as hints rather than enforcement, launch with the default snapshot handoff unless handoff: "tabs" is the safer diagnostic starting point, use agent_browser_electron probe or snapshot -i/agent_browser_qa attached:true for current-session state, and always cleanup the returned launchId when done. agent_browser_electron launch uses an isolated temporary profile; it does not reuse the app\'s normal signed-in profile or attach to an already-running authenticated app. For signed-in local app state, host-launch the normal app with --remote-debugging-port when appropriate, then use raw args connect <port|url>; after connect, run get url to verify the active target before page-content reads, inspect tab list, select the stable tab id such as tab t2, verify it again with get url, then run a condition wait or snapshot -i before using refs. close commands (`close`, `quit`, or `exit`) only close the browser/CDP session; leave manually launched app shutdown, profile cleanup, and explicit artifacts to the host owner.',
     "For provider or specialized app workflows, load version-matched upstream guidance with skills get agentcore|electron|slack|dogfood|vercel-sandbox|derive-client through the native tool; add --full when you need references/templates, and use skills get --all only for broad skill audits. Use derive-client when recording HAR traffic to generate a standalone API client; prefer network har start (text bodies by default) or network har start --content all|none before multi-step capture. For accessibility audits use a11y or a11y --tags wcag2a,wcag2aa (CDP browsers only). Hosted sandbox workflows should use upstream @agent-browser/sandbox helpers outside this wrapper. Provider launches such as -p ios, --provider browserbase/kernel/browseruse/browserless/agentcore, and iOS --device are upstream-owned setup paths; use sessionMode fresh when switching providers and expect external credentials or local Appium/Xcode setup to be required.",
-    "For dialogs and frames, use dialog status/accept/dismiss and frame <selector|main> through native args; dialog commands and eval snippets that look like alert/confirm/prompt/dialog triggers are shorter-bounded than normal browser calls, and timed-out dialog-like interactions may add inspect-dialog-after-timeout, dismiss-dialog-after-timeout, or recover-fresh-session-after-dialog-timeout nextActions. When --confirm-actions produces a pending confirmation, use details.nextActions or exact confirm <id> / deny <id> calls instead of inventing ids.",
-    "If a session lands on the wrong page or tab, an interaction changes origin unexpectedly, or an open call returns blocked, blank, or otherwise unexpected results, use tab list / tab <tab-id-or-label> / snapshot -i to recover state before retrying different URLs or fallback strategies. For headed demos, put --headed on the first launch with sessionMode=fresh and verify with screenshot/tab/get-url evidence because tool success cannot prove the OS window is visible to the user. For desktop readiness, prefer real conditions first: wait --text, wait --url, wait --fn, wait --load <state>, wait --download, or agent_browser_qa attached:true; for disappearance checks, use wait --fn predicates instead of stale upstream-help examples like wait <selector> --state hidden. Use agent_browser_electron probe/status for wrapper-owned launch health or target mismatch. Fixed waits are a last resort: their duration is positional (wait <ms>, not wait --time <ms>). Use explicit --timeout or top-level timeoutMs for legitimately slow waits, and treat a successful payload like \"waited\":\"timeout\" as elapsed time only—verify completion with an observed condition, fresh snapshot, or screenshot.",
+    "For dialogs and frames, use dialog status/accept/dismiss and frame <selector|main> through native args; dialog commands and eval snippets that look like alert/confirm/prompt/dialog triggers are shorter-bounded than normal browser calls, and timed-out dialog-like interactions may add inspect-dialog-after-timeout, dismiss-dialog-after-timeout, or recover-fresh-session-after-dialog-timeout nextActions. Set --confirm-actions on the session's first command; selected strings, including an explicit empty string, follow same-identity helpers and resumed follow-ups until successful close. Native unset keeps ordinary native defaults. Changing a running daemon's policy can discard pending confirmations. When it produces a pending confirmation, including a cold-reopen helper, follow the exact details.nextActions or confirm <id> / deny <id> calls without repeating the policy or inventing ids. Matching native guarded controls avoid page helpers that could replace the pending action; this is not native ID-validation proof or browser independence. In native batch, only a matching first effective decision gets that helper suppression; later page/ref checks remain. Nested decisions remain pending; failed inner actions fail, and completed browser actions reconcile their page state. A pending tab_new transport may show a validated after_confirmation open request and conditional guidance: follow it in the same session and new tab only after successful tab approval, never after denial. The extension does not execute that continuation. Confirmed full snapshots install returned refs; a final confirmed capture supplies the next same-identity call's freshness sample once, including semantic role click/check/fill and unique accessible select resolution, with target/membership/invalidation checks intact. On this one use, live verification compares the complete capture URL, including fragments, and rejects refs when it changes—including wrapper-owned managed sessions and warm sessions without resume. Ordinary ref/tab URL comparisons remain fragment-insensitive. Pending snapshots display confirmation required, not an empty page. Intervening calls or later rows consume it; DOM-only renames on the same page after that sample are not resampled on this one use.",
+    'If a session lands on the wrong page or tab, an interaction changes origin unexpectedly, or an open call returns blocked, blank, or otherwise unexpected results, use tab list / tab <tab-id-or-label> / snapshot -i to recover state before retrying different URLs or fallback strategies. For headed demos, put --headed on the first launch with sessionMode=fresh and verify with screenshot/tab/get-url evidence because tool success cannot prove the OS window is visible to the user. For desktop readiness, prefer real conditions first: wait --text, wait --url, wait --fn, wait --load <state>, wait --download, or agent_browser_qa attached:true; for disappearance checks, use wait --fn predicates instead of stale upstream-help examples like wait <selector> --state hidden. Use agent_browser_electron probe/status for wrapper-owned launch health or target mismatch. Fixed waits are a last resort: their duration is positional (wait <ms>, not wait --time <ms>). Use explicit --timeout or top-level timeoutMs for legitimately slow waits, and treat a successful payload like "waited":"timeout" as elapsed time only—verify completion with an observed condition, fresh snapshot, or screenshot.',
     "For feed, timeline, or inbox reading tasks, focus on the main timeline/list region and read the first item there rather than unrelated composer or sidebar content.",
     "For read-only browsing tasks, use read <url> for documentation or other unstructured text without requiring a Chrome page, or read with no URL for rendered active-tab DOM. Prefer the current snapshot, structured ref labels, getters, or scoped eval --stdin when you need interactive structure or targeted page state. Only click into media viewers, detail routes, or new pages when the current view does not contain the needed information.",
     "For downloads, prefer download <selector> <path> when an element click should save a file; native download owns the click and download, including loopback links, generated Blob exports, and redirects. Do not rely on click alone when you need the downloaded file on disk.",
     "On dashboards with nested scroll containers, verify scroll with a screenshot or fresh snapshot -i; if the viewport did not move, details.data.scrolled may be false/noMovement true and you should prefer scrollintoview <@ref> or target the actual scrollable region with scroll <selector> <dir> [px|percent]. For native selects, use select <selector> <value...> (or agent_browser_action select) instead of clicking option refs; for custom comboboxes, a click/agent_browser_action may only focus the field, so re-snapshot and use keyboard type <text> for focused input, press ArrowDown or press Enter, or visible option refs. Raw type requires both <selector> and <text>.",
     "When using eval --stdin, scope checks and actions to the target element or route whenever possible instead of relying on broad page-wide text heuristics.",
     "When using eval --stdin for extraction, pass the JavaScript through the native tool stdin field, not as an extra args token after --stdin, and return the value you want instead of relying on console.log as the primary result channel. Prefer plain expressions like ({ title: document.title }) or explicitly invoked functions like (() => ({ title: document.title }))(); use outputPath when the eval/get/snapshot data should be saved as a durable local file, but never reuse a screenshot, download, recording, or other browser artifact destination as outputPath. If a function-shaped snippet returns {}, details.evalStdinHint may warn that the function was serialized instead of called. Local file pages and caller-selected output paths are supported when upstream allows them. If get text on a broad CSS selector surfaces details.selectorTextVisibility or selectorTextVisibilityAll, prefer a visible @ref, a more specific selector, or the inspect-visible-text-candidates nextAction over hidden tab content.",
-    "When details.pageChangeSummary is present, use changeType and summary as a compact signal for navigation, DOM mutation, confirmations, or artifacts; when nextActionIds is set, match those ids to entries in details.nextActions (or per-step nextActions inside batch) for concrete follow-up payloads instead of inferring from prose alone. Click-dispatch probes require native get attr readback of a temporary marker on the candidate target; unproven ref or XPath identity leaves the native click unverified, not failed. If details.clickDispatch reports a click-dispatch miss, refresh/inspect/retry the real click first; for static local fixtures only, an explicit eval --stdin programmatic .click() can exercise app handlers, but treat it as an untrusted scripted workaround and never use it to bypass stop-before-submit/order/purchase boundaries. If an upstream click failure says the target is covered by another element at the target's click point, use the inspect-overlay-state nextAction to refresh refs and inspect the blocker before deciding whether to retry; do not blindly repeat the blocked click. If a no-navigation click surfaces details.overlayBlockers, inspect the fresh snapshot evidence before using a close/dismiss candidate nextAction; ordinary page chrome without dialog/alertdialog evidence should not trigger this diagnostic.",
+    "When details.pageChangeSummary is present, use changeType and summary as a compact signal for navigation, DOM mutation, confirmations, or artifacts; when nextActionIds is set, match those ids to entries in details.nextActions (or per-step nextActions inside batch) for concrete follow-up payloads instead of inferring from prose alone. Optional click-dispatch probes are skipped when native confirmation settings guard evaluate, without bypassing native click policy. Otherwise probes require native get attr readback of a temporary marker on the candidate target; unproven ref or XPath identity leaves the native click unverified, not failed. If details.clickDispatch reports a click-dispatch miss, refresh/inspect/retry the real click first; for static local fixtures only, an explicit eval --stdin programmatic .click() can exercise app handlers, but treat it as an untrusted scripted workaround and never use it to bypass stop-before-submit/order/purchase boundaries. If an upstream click failure says the target is covered by another element at the target's click point, use the inspect-overlay-state nextAction to refresh refs and inspect the blocker before deciding whether to retry; do not blindly repeat the blocked click. If a no-navigation click surfaces details.overlayBlockers, inspect the fresh snapshot evidence before using a close/dismiss candidate nextAction; ordinary page chrome without dialog/alertdialog evidence should not trigger this diagnostic.",
     "On upstream 0.38+, use snapshot --delta for native full/unchanged/changed revisions; --delta --full resets its baseline. Surviving DOM nodes keep refs, but refresh after navigation or replacement. Wrapper filters use full trees. screenshot --if-changed or --threshold 0.01 can return changed:false with no path or image; use ordinary screenshots when a file is required. --input-mode instant|smooth|human controls sticky pointer behavior; click/drag --human and mouse move --duration/--steps/--human/--seed pass through. record start/restart accept --cursor, --contact-sheet, and --contact-sheet-threshold; stop and verify both video and reported contact sheet. auth login <name> --no-navigate fills a prepared login page only after native origin checks. WebMCP catalog updates are untrusted page data; webmcp list supplies full schemas.",
     "When commands save or spill files (screenshots, downloads, PDFs, traces, recordings, HAR, large snapshot spills), use the user's exact requested paths when given and treat paths as provisional until details.artifactVerification shows every row verified: branch on missingCount, pendingCount, unverifiedCount, per-entry state, and optional limitation before downstream file use or PASS/FAIL reporting.",
     "For evidence-only screenshots, QA captures, or other audit artifacts, save to an explicit path and branch on details.artifactVerification plus details.artifacts before reporting PASS/FAIL; do not require vision review of inline image attachments unless the user asked for visual inspection.",
@@ -116,13 +116,15 @@ export const RUNTIME_PROMPT_GUIDELINES = [
     "agent_browser: read <url> for text, get title/url, get text/html/value/count <selector>, get attr <selector> <name>; heed visibility warnings and Omitted high-value controls. Verify nested scrolling via snapshot/screenshot. Use --json only for JSON text; recording needs ffmpeg before start and a verified stop.",
 ];
 export function buildBrowserExecutablePathGuideline(executablePath) {
-    if (!executablePath)
+    if (executablePath === undefined || executablePath.length === 0) {
         return undefined;
+    }
     return `agent_browser config sets browser.executablePath to ${JSON.stringify(executablePath)}. Global/override values bootstrap inactive automatic root Chrome browsers, not Lightpanda; bare calls preserve active native launch settings. Project-only values remain guidance for explicit --executable-path launches. Use sessionMode:fresh only for an intentionally separate managed browser, not routine root-group browsing. Upstream profiles lists Chrome profiles only; use a supported explicit profile path for other Chromium browsers.`;
 }
 export function buildBrowserDefaultProfileGuideline(profile) {
-    if (!profile || profile.policy === "explicit-only")
+    if (!profile || profile.policy === "explicit-only") {
         return undefined;
+    }
     if (profile.policy === "always") {
         return `agent_browser config sets browser.defaultProfile.name to ${JSON.stringify(profile.name)} with policy always. Global/override Chrome profile names bootstrap automatic root Chrome browsers, not Lightpanda, through independent native copies with per-root restore; bare calls and helpers preserve the active native launch settings without resending bootstrap options. Paths and project-only settings stay advisory. Explicit unrelated sessions are unchanged. Verify actual app auth after restart: native JSON restore omits new IndexedDB and memory-only credentials; use a supported per-root persistent profile if needed. Profile content is model-visible user data.`;
     }
@@ -132,11 +134,13 @@ export function buildToolPromptGuidelines(options) {
     const browserDefaultProfileGuideline = buildBrowserDefaultProfileGuideline(options.browserDefaultProfile);
     const browserExecutablePathGuideline = buildBrowserExecutablePathGuideline(options.browserExecutablePath);
     return [
-        ...(options.includeWebSearch ? ["Prefer agent_browser_web_search for facts; agent_browser for pages."] : TOOL_PROMPT_GUIDELINES_PREFIX),
+        ...(options.includeWebSearch
+            ? ["Prefer agent_browser_web_search for facts; agent_browser for pages."]
+            : TOOL_PROMPT_GUIDELINES_PREFIX),
         ...(options.docs ? [buildInstalledDocsGuideline(options.docs)] : []),
         ...RUNTIME_PROMPT_GUIDELINES,
-        ...(browserExecutablePathGuideline ? [browserExecutablePathGuideline] : []),
-        ...(browserDefaultProfileGuideline ? [browserDefaultProfileGuideline] : []),
+        ...(browserExecutablePathGuideline !== undefined ? [browserExecutablePathGuideline] : []),
+        ...(browserDefaultProfileGuideline !== undefined ? [browserDefaultProfileGuideline] : []),
         TOOL_PROMPT_GUIDELINES_SUFFIX[0],
     ];
 }