pi-agent-browser-native 0.2.71 → 0.2.74

package/dist/extensions/agent-browser/lib/argv-grammar.js

@@ -45,6 +45,7 @@ export const COMMAND_VALUE_FLAGS = [
     "--baseline",
     "--body",
     "--categories",
+    "--content",
     "--curl",
     "--depth",
     "-d",
@@ -68,6 +69,7 @@ export const COMMAND_VALUE_FLAGS = [
     "--selector",
     "-s",
     "--status",
+    "--tags",
     "--text",
     "--threshold",
     "--timeout",
@@ -89,6 +91,7 @@ export const GLOBAL_BOOLEAN_FLAGS_WITH_OPTIONAL_VALUES = new Set([
     "--content-boundaries",
     "--debug",
     "--headed",
+    "--hide-scrollbars",
     "--ignore-https-errors",
     "--json",
     "--no-auto-dialog",
@@ -98,6 +101,127 @@ export const GLOBAL_BOOLEAN_FLAGS_WITH_OPTIONAL_VALUES = new Set([
     "-v",
     "--webgpu",
 ]);
+const SESSION_COMPONENT_ALPHANUMERIC = /^[\p{Alphabetic}\p{Number}]$/u;
+/** Match upstream's last-wins, case-sensitive boolean semantics; only exact `false` disables a present flag. */
+export function isBooleanFlagEnabled(args, flag) {
+    let enabled = false;
+    for (let index = 0; index < args.length; index += 1) {
+        const token = args[index];
+        if (token === flag) {
+            enabled = args[index + 1] !== "false";
+            if (["true", "false"].includes(args[index + 1] ?? ""))
+                index += 1;
+            continue;
+        }
+        if (PREVALIDATED_VALUE_FLAGS.has(token)) {
+            index += 1;
+            continue;
+        }
+        if (GLOBAL_BOOLEAN_FLAGS_WITH_OPTIONAL_VALUES.has(token) && ["true", "false"].includes(args[index + 1] ?? ""))
+            index += 1;
+    }
+    return enabled;
+}
+/** Mirror upstream sanitize_session_component for namespace/socket/state identity. */
+export function canonicalizeAgentBrowserNamespace(value) {
+    if (value === undefined)
+        return undefined;
+    let normalized = "";
+    let lastWasSeparator = false;
+    for (const character of value) {
+        if (SESSION_COMPONENT_ALPHANUMERIC.test(character)) {
+            normalized += character.toLowerCase();
+            lastWasSeparator = false;
+        }
+        else if (character === "-" || character === "_") {
+            if (normalized && !lastWasSeparator) {
+                normalized += character;
+                lastWasSeparator = true;
+            }
+        }
+        else if (normalized && !lastWasSeparator) {
+            normalized += "-";
+            lastWasSeparator = true;
+        }
+    }
+    return normalized.replace(/[-_]+$/u, "") || undefined;
+}
+function foldAgentBrowserFilesystemIdentity(value, platform) {
+    if (platform !== "darwin" && platform !== "win32")
+        return value;
+    // APFS aliases include full Unicode folds such as ß/SS and ς/Σ, not just ASCII case.
+    return value.normalize("NFC").toLowerCase().toUpperCase().toLowerCase().normalize("NFC");
+}
+export function getAgentBrowserSessionIdentityKey(sessionName, namespace, platform = process.platform) {
+    const canonicalNamespace = canonicalizeAgentBrowserNamespace(namespace);
+    const identityNamespace = canonicalNamespace ? foldAgentBrowserFilesystemIdentity(canonicalNamespace, platform) : undefined;
+    const canonicalSessionName = foldAgentBrowserFilesystemIdentity(sessionName, platform);
+    return identityNamespace ? `${identityNamespace}\0${canonicalSessionName}` : canonicalSessionName;
+}
+/** Mirror upstream 0.33.2 global parsing: full argv, no `--` sentinel, and only global value payloads are skipped. */
+export function scanUpstreamGlobalFlagOccurrences(args, targetFlag) {
+    const occurrences = [];
+    for (let index = 0; index < args.length; index += 1) {
+        const token = args[index];
+        if (token === targetFlag) {
+            occurrences.push({ index, value: args[index + 1] });
+            index += 1;
+            continue;
+        }
+        if (PREVALIDATED_VALUE_FLAGS.has(token)) {
+            index += 1;
+            continue;
+        }
+        if (GLOBAL_BOOLEAN_FLAGS_WITH_OPTIONAL_VALUES.has(token) && ["true", "false"].includes(args[index + 1] ?? ""))
+            index += 1;
+    }
+    return occurrences;
+}
+export function extractExplicitSessionName(args) {
+    return scanUpstreamGlobalFlagOccurrences(args, "--session").at(-1)?.value;
+}
+export function extractExplicitNamespace(args) {
+    return canonicalizeAgentBrowserNamespace(scanUpstreamGlobalFlagOccurrences(args, "--namespace").at(-1)?.value);
+}
+export function resolveAgentBrowserNamespace(args, envValue) {
+    const occurrences = scanUpstreamGlobalFlagOccurrences(args, "--namespace");
+    if (occurrences.length > 0)
+        return canonicalizeAgentBrowserNamespace(occurrences.at(-1)?.value) ?? "";
+    return canonicalizeAgentBrowserNamespace(envValue);
+}
+/** Mirror upstream's optional restore value and full-argv last-wins parsing. */
+export function extractRequestedRestoreKey(args, sessionName, envValue) {
+    let restoreKey = envValue || null;
+    let seenCommand = false;
+    for (let index = 0; index < args.length; index += 1) {
+        const token = args[index];
+        if (token.startsWith("--restore=")) {
+            restoreKey = token.slice("--restore=".length) || sessionName;
+            continue;
+        }
+        if (token === "--restore") {
+            if (!seenCommand && optionalGlobalValueFlagConsumesNext(token, args[index + 1])) {
+                restoreKey = args[index + 1];
+                index += 1;
+            }
+            else {
+                restoreKey = sessionName;
+            }
+            continue;
+        }
+        if (PREVALIDATED_VALUE_FLAGS.has(token)) {
+            index += 1;
+            continue;
+        }
+        if (GLOBAL_BOOLEAN_FLAGS_WITH_OPTIONAL_VALUES.has(token) && ["true", "false"].includes(args[index + 1] ?? "")) {
+            index += 1;
+            continue;
+        }
+        if (isKnownCommandToken(token))
+            seenCommand = true;
+    }
+    return restoreKey;
+}
 export function getFlagName(token) {
     return token.split("=", 1)[0] ?? token;
 }

package/dist/extensions/agent-browser/lib/command-taxonomy.js

@@ -5,7 +5,7 @@
  * Scope: Static command capability taxonomy only; command-shape parsing, spawning, and formatting live elsewhere.
  */
 const ADDITIONAL_COMMAND_TOKENS = [
-    "auth", "chat", "clipboard", "confirm", "connect", "dashboard", "deny", "device", "dialog", "diff", "doctor", "errors", "eval", "find", "frame", "get", "highlight", "inspect", "install", "is", "mcp", "plugin", "plugins", "profiles", "profiler", "react", "record", "removeinitscript", "session", "set", "skills", "snapshot", "state", "stream", "trace", "upgrade", "vitals", "wait", "web-vitals", "window",
+    "a11y", "auth", "chat", "clipboard", "confirm", "connect", "dashboard", "deny", "device", "dialog", "diff", "doctor", "errors", "eval", "find", "frame", "get", "highlight", "inspect", "install", "is", "mcp", "plugin", "plugins", "profiles", "profiler", "react", "record", "removeinitscript", "session", "set", "skills", "snapshot", "state", "stream", "trace", "upgrade", "vitals", "wait", "web-vitals", "window",
 ];
 const COMMAND_CAPABILITIES = [
     {
@@ -81,6 +81,12 @@ const COMMAND_CAPABILITIES = [
         command: "errors",
         readOnlyDiagnosticSessionTarget: true,
     },
+    {
+        command: "eval",
+        invalidatesBatchRefs: true,
+        navigationObservable: true,
+        triggersPostMutationSnapshot: true,
+    },
     {
         command: "fill",
         eligibleForElectronHealthProbe: true,
@@ -305,6 +311,11 @@ export function isElectronPostCommandHealthCommand(command) {
 export function isNavigationObservableCommandName(command) {
     return hasCommandCapability(command, "navigationObservable");
 }
+export function isUnverifiedPageTransitionCommand(command, subcommand) {
+    return ["back", "connect", "eval", "forward", "reload"].includes(command ?? "")
+        || (command === "state" && subcommand === "load")
+        || (command === "tab" && subcommand !== undefined && !["list", "new"].includes(subcommand));
+}
 export function isPageMutationCommand(command) {
     return hasCommandCapability(command, "triggersPostMutationSnapshot");
 }

package/dist/extensions/agent-browser/lib/electron/cdp.js

@@ -33,11 +33,11 @@ export function parseCdpTargets(value) {
         webSocketDebuggerUrl: asString(target.webSocketDebuggerUrl),
     }));
 }
-export async function fetchCdpJson(url) {
+export async function fetchCdpJson(url, signal) {
     const controller = new AbortController();
     const timeout = setTimeout(() => controller.abort(), ELECTRON_CDP_FETCH_TIMEOUT_MS);
     try {
-        const response = await fetch(url, { signal: controller.signal });
+        const response = await fetch(url, { signal: signal ? AbortSignal.any([signal, controller.signal]) : controller.signal });
         if (!response.ok)
             return undefined;
         return await response.json();

package/dist/extensions/agent-browser/lib/electron/launch.js

@@ -3,7 +3,7 @@
  * Responsibilities: Resolve Electron targets, enforce caller-owned allow/deny policy, create isolated userDataDir profiles, launch with remote debugging on an OS-chosen port, poll DevToolsActivePort, and read bounded CDP version/target metadata.
  * Scope: Host-side Electron lifecycle setup only; upstream agent-browser attach/presentation stays in the extension entrypoint.
  * Usage: Called by the agent_browser electron.launch shorthand before routing through upstream `connect`.
- * Invariants/Assumptions: The wrapper only launches targets with Electron framework evidence, always uses an isolated temp profile, and never accepts a caller-supplied remote debugging port.
+ * Invariants/Assumptions: The wrapper only launches targets with Electron framework evidence, always uses an isolated temp profile, never accepts a caller-supplied remote debugging port, and cleans any spawned process/profile when cancellation interrupts readiness.
  */
 import { spawn } from "node:child_process";
 import { randomUUID } from "node:crypto";
@@ -24,8 +24,18 @@ function normalizeTimeoutMs(timeoutMs) {
         return ELECTRON_LAUNCH_DEFAULT_TIMEOUT_MS;
     return Math.min(timeoutMs, ELECTRON_LAUNCH_MAX_TIMEOUT_MS);
 }
-function sleep(ms) {
-    return new Promise((resolve) => setTimeout(resolve, ms));
+function sleep(ms, signal) {
+    if (signal?.aborted)
+        return Promise.resolve();
+    return new Promise((resolve) => {
+        const timer = setTimeout(done, ms);
+        function done() {
+            clearTimeout(timer);
+            signal?.removeEventListener("abort", done);
+            resolve();
+        }
+        signal?.addEventListener("abort", done, { once: true });
+    });
 }
 function normalizeIdentifier(value) {
     const trimmed = value?.trim().toLowerCase();
@@ -110,6 +120,8 @@ async function readDevToolsActivePort(userDataDir) {
 async function pollDevToolsActivePort(options) {
     let devToolsActivePort;
     while (Date.now() <= options.deadlineMs) {
+        if (options.signal?.aborted)
+            return { devToolsActivePort, failure: "aborted" };
         const spawnError = options.getSpawnError();
         if (spawnError)
             return { devToolsActivePort, failure: "spawn-error", spawnError };
@@ -120,20 +132,24 @@ async function pollDevToolsActivePort(options) {
         if (exit.code !== null || exit.signal !== null) {
             return { devToolsActivePort, failure: exit.code === 0 ? "single-instance-conflict" : "spawn-error" };
         }
-        await sleep(ELECTRON_DEVTOOLS_POLL_INTERVAL_MS);
+        await sleep(ELECTRON_DEVTOOLS_POLL_INTERVAL_MS, options.signal);
     }
     return { devToolsActivePort, failure: "timeout" };
 }
-async function pollCdpMetadata(port, deadlineMs) {
+async function pollCdpMetadata(port, deadlineMs, signal) {
     while (Date.now() <= deadlineMs) {
-        const version = parseCdpVersion(await fetchCdpJson(`http://127.0.0.1:${port}/json/version`));
+        if (signal?.aborted)
+            return { aborted: true };
+        const version = parseCdpVersion(await fetchCdpJson(`http://127.0.0.1:${port}/json/version`, signal));
+        if (signal?.aborted)
+            return { aborted: true };
         if (version) {
-            const targets = parseCdpTargets(await fetchCdpJson(`http://127.0.0.1:${port}/json/list`));
-            return { targets, version };
+            const targets = parseCdpTargets(await fetchCdpJson(`http://127.0.0.1:${port}/json/list`, signal));
+            return signal?.aborted ? { aborted: true } : { aborted: false, metadata: { targets, version } };
         }
-        await sleep(ELECTRON_DEVTOOLS_POLL_INTERVAL_MS);
+        await sleep(ELECTRON_DEVTOOLS_POLL_INTERVAL_MS, signal);
     }
-    return undefined;
+    return { aborted: false };
 }
 function buildLaunchArgs(userDataDir, appArgs) {
     return [
@@ -210,6 +226,8 @@ function buildLaunchRecord(options) {
 function launchFailureMessage(reason, target, detail) {
     const label = target ? `${target.name} (${target.appPath ?? target.executablePath})` : "target";
     switch (reason) {
+        case "aborted":
+            return `Electron launch was aborted${target ? ` before ${label} finished starting` : " before the app started"}.`;
         case "non-electron-target":
             return `Electron launch rejected: ${label} does not have Electron framework evidence.`;
         case "policy-blocked":
@@ -226,7 +244,11 @@ function launchFailureMessage(reason, target, detail) {
 }
 export async function launchElectronApp(options) {
     const appArgs = options.appArgs ?? [];
+    if (options.signal?.aborted)
+        return { ok: false, failure: { appArgs, error: launchFailureMessage("aborted", undefined), reason: "aborted" } };
     const target = await resolveElectronLaunchTarget(options);
+    if (options.signal?.aborted)
+        return { ok: false, failure: { appArgs, error: launchFailureMessage("aborted", target), reason: "aborted", target } };
     if (!target) {
         return {
             ok: false,
@@ -254,6 +276,16 @@ export async function launchElectronApp(options) {
     const startedAtMs = Date.now();
     const deadlineMs = startedAtMs + timeoutMs;
     const userDataDir = await createSecureTempDirectory(ELECTRON_PROFILE_DIR_PREFIX);
+    if (options.signal?.aborted) {
+        let cleanupError;
+        try {
+            await rm(userDataDir, { force: true, recursive: true });
+        }
+        catch (error) {
+            cleanupError = error instanceof Error ? error.message : String(error);
+        }
+        return { ok: false, failure: { appArgs, cleanupError, error: launchFailureMessage("aborted", target), reason: "aborted", target, userDataDir } };
+    }
     let cleanupError;
     let spawnError;
     let exitCode = null;
@@ -312,15 +344,19 @@ export async function launchElectronApp(options) {
         deadlineMs,
         getChildExit: () => ({ code: exitCode, signal: exitSignal }),
         getSpawnError: () => spawnError,
+        signal: options.signal,
         userDataDir,
     });
     if (!portResult.port) {
         return fail(portResult.failure ?? "timeout", portResult.spawnError?.message, { devToolsActivePort: portResult.devToolsActivePort });
     }
-    const metadata = await pollCdpMetadata(portResult.port, deadlineMs);
-    if (!metadata) {
+    const metadataResult = await pollCdpMetadata(portResult.port, deadlineMs, options.signal);
+    if (metadataResult.aborted)
+        return fail("aborted", undefined, { devToolsActivePort: portResult.devToolsActivePort, port: portResult.port });
+    if (!metadataResult.metadata) {
         return fail("port-not-found", undefined, { cdpVersionReached: false, devToolsActivePort: portResult.devToolsActivePort, port: portResult.port });
     }
+    const metadata = metadataResult.metadata;
     const record = buildLaunchRecord({
         createdAtMs: Date.now(),
         pid: child.pid,

package/dist/extensions/agent-browser/lib/input-modes/params.js

@@ -7,138 +7,136 @@ import { JsonSchema } from "../json-schema.js";
 import { StringEnum as localStringEnum } from "../string-enum-schema.js";
 import { ELECTRON_DISCOVERY_DEFAULT_MAX_RESULTS, ELECTRON_DISCOVERY_MAX_RESULTS, } from "../electron/discovery.js";
 import { AGENT_BROWSER_ELECTRON_HANDOFFS, AGENT_BROWSER_ELECTRON_TARGET_TYPES, AGENT_BROWSER_JOB_STEP_ACTIONS, AGENT_BROWSER_JOB_TYPE_DELAYED_TEXT_MAX_CHARACTERS, AGENT_BROWSER_QA_LOAD_STATES, AGENT_BROWSER_SEMANTIC_ACTIONS, AGENT_BROWSER_SEMANTIC_LOCATORS, DEFAULT_SESSION_MODE, SOURCE_LOOKUP_MAX_WORKSPACE_FILES, } from "./types.js";
+// Keep descriptions terse: Pi sends this schema every turn; workflows belong in prompt guidance and docs.
 // ponytail: the four electron.launch variants differ only in their single target field
-// (appPath/appName/bundleId/executablePath); the action literal and the shared optional
-// launch fields are identical, so a helper keeps the duplicate schema blocks in sync.
+// (appPath/appName/bundleId/executablePath); the action literal and shared launch fields
+// are identical, so this helper keeps the schema variants in sync.
 function electronLaunchVariant(Type, StringEnum, targetField) {
     return Type.Object({
-        action: StringEnum(["launch"], { description: "Launch an Electron app with an isolated wrapper-owned profile." }),
+        action: StringEnum(["launch"]),
         ...targetField,
-        appArgs: Type.Optional(Type.Array(Type.String({ description: "Argument passed to the Electron application.", minLength: 1 }), { description: "Optional Electron app argv. Wrapper-owned lifecycle/debug flags are rejected." })),
-        handoff: Type.Optional(StringEnum(AGENT_BROWSER_ELECTRON_HANDOFFS, { description: "Post-launch handoff depth. Defaults to snapshot." })),
-        targetType: Type.Optional(StringEnum(AGENT_BROWSER_ELECTRON_TARGET_TYPES, { description: "Preferred CDP target type. Defaults to page." })),
-        timeoutMs: Type.Optional(Type.Integer({ description: "Bounded launch timeout in milliseconds.", minimum: 1 })),
-        allow: Type.Optional(Type.Array(Type.String({ description: "App identifier allowed by the caller for electron.launch.", minLength: 1 }), { description: "Optional caller-owned allow list for electron.launch policy checks." })),
-        deny: Type.Optional(Type.Array(Type.String({ description: "App identifier denied by the caller for electron.launch.", minLength: 1 }), { description: "Optional caller-owned deny list for electron.launch policy checks; deny wins over allow." })),
+        appArgs: Type.Optional(Type.Array(Type.String({ minLength: 1 }))),
+        handoff: Type.Optional(StringEnum(AGENT_BROWSER_ELECTRON_HANDOFFS)),
+        targetType: Type.Optional(StringEnum(AGENT_BROWSER_ELECTRON_TARGET_TYPES)),
+        timeoutMs: Type.Optional(Type.Integer({ minimum: 1 })),
+        allow: Type.Optional(Type.Array(Type.String({ minLength: 1 }))),
+        deny: Type.Optional(Type.Array(Type.String({ minLength: 1 }))),
     }, { additionalProperties: false });
 }
 export function createAgentBrowserParamsSchema(Type = JsonSchema, StringEnum = localStringEnum) {
     return Type.Object({
-        args: Type.Optional(Type.Array(Type.String({ description: "Exact agent-browser CLI arguments, excluding the binary name. Do not pass --json; the wrapper injects it. First-call recipe: open → snapshot -i → click/fill @eN → snapshot -i." }), {
-            description: "Exact agent-browser CLI arguments, excluding the binary name and any shell operators. Required unless semanticAction, job, qa, sourceLookup, networkSourceLookup, or electron is provided. Do not include --json (wrapper injects it). Typical first calls: open, snapshot -i, click/fill current @refs, then snapshot -i again after navigation or DOM changes.",
+        args: Type.Optional(Type.Array(Type.String(), {
+            description: "Raw agent-browser argv only: no binary, shell operators, or --json. Start with open → snapshot -i → act on current @refs; re-snapshot after page changes.",
             minItems: 1,
         })),
         semanticAction: Type.Optional(Type.Object({
-            action: StringEnum(AGENT_BROWSER_SEMANTIC_ACTIONS, {
-                description: "Intent action to compile to an existing agent-browser find command, direct selector/ref command, or upstream select when action=select.",
-            }),
-            locator: Type.Optional(StringEnum(AGENT_BROWSER_SEMANTIC_LOCATORS, {
-                description: "Upstream find locator family to use for check/click/fill actions.",
-            })),
-            value: Type.Optional(Type.String({ description: "Locator value for find actions, or a single option value for select actions. For locator=role, role may be supplied instead." })),
-            values: Type.Optional(Type.Array(Type.String({ description: "Option value for select actions." }), { description: "One or more option values for select actions.", minItems: 1 })),
-            selector: Type.Optional(Type.String({ description: "Selector or @ref for direct click/check/fill actions, or for select actions compiled to select <selector> <value...>." })),
-            text: Type.Optional(Type.String({ description: "Text/value argument for fill actions." })),
-            role: Type.Optional(Type.String({ description: "Role locator value for locator=role. May be used instead of value; when both are set they must match." })),
-            name: Type.Optional(Type.String({ description: "Accessible name filter for locator=role; compiles to --name <name>." })),
-            session: Type.Optional(Type.String({ description: "Optional upstream session name; prepends --session <name> before the compiled command." })),
-        }, { additionalProperties: false })),
+            action: StringEnum(AGENT_BROWSER_SEMANTIC_ACTIONS),
+            locator: Type.Optional(StringEnum(AGENT_BROWSER_SEMANTIC_LOCATORS, { description: "Locator for check/click/fill." })),
+            value: Type.Optional(Type.String({ description: "Locator value, or one select option." })),
+            values: Type.Optional(Type.Array(Type.String(), { description: "Select options.", minItems: 1 })),
+            selector: Type.Optional(Type.String({ description: "Direct selector or @ref." })),
+            text: Type.Optional(Type.String({ description: "Fill text." })),
+            role: Type.Optional(Type.String({ description: "Role locator; alternative to value." })),
+            name: Type.Optional(Type.String({ description: "Accessible name." })),
+            session: Type.Optional(Type.String({ description: "Upstream session name." })),
+        }, { additionalProperties: false, description: "Stable locator or direct-selector action." })),
         qa: Type.Optional(Type.Union([
             Type.Object({
-                attached: Type.Literal(true, { description: "Run the QA preset against the currently attached session instead of opening qa.url." }),
-                expectedText: Type.Optional(Type.Union([Type.String(), Type.Array(Type.String())], { description: "Text that must appear on the page." })),
-                expectedSelector: Type.Optional(Type.String({ description: "Selector or @ref that must appear on the page." })),
-                screenshotPath: Type.Optional(Type.String({ description: "Optional evidence screenshot path captured at the end of the QA preset." })),
-                checkConsole: Type.Optional(Type.Boolean({ description: "Whether to inspect console messages and fail on console errors. Defaults to false for qa.attached because upstream buffers may predate the check." })),
-                checkErrors: Type.Optional(Type.Boolean({ description: "Whether to inspect page errors and fail when errors are present. Defaults to false for qa.attached because upstream buffers may predate the check." })),
-                checkNetwork: Type.Optional(Type.Boolean({ description: "Whether to inspect network requests and fail on actionable request failures; benign icon misses warn. Defaults to false for qa.attached because upstream buffers may predate the check." })),
-                loadState: Type.Optional(StringEnum(AGENT_BROWSER_QA_LOAD_STATES, { description: "Page readiness state for the QA preset before assertions and diagnostics. Defaults to domcontentloaded; use networkidle only for pages without long-lived background requests." })),
+                attached: Type.Literal(true),
+                expectedText: Type.Optional(Type.Union([Type.String(), Type.Array(Type.String())])),
+                expectedSelector: Type.Optional(Type.String()),
+                screenshotPath: Type.Optional(Type.String()),
+                checkConsole: Type.Optional(Type.Boolean()),
+                checkErrors: Type.Optional(Type.Boolean()),
+                checkNetwork: Type.Optional(Type.Boolean()),
+                loadState: Type.Optional(StringEnum(AGENT_BROWSER_QA_LOAD_STATES)),
             }, { additionalProperties: false }),
             Type.Object({
-                url: Type.String({ description: "URL to open for a lightweight QA preset." }),
-                attached: Type.Optional(Type.Literal(false, { description: "When omitted or false, qa.url is required and opened before checks." })),
-                expectedText: Type.Optional(Type.Union([Type.String(), Type.Array(Type.String())], { description: "Text that must appear on the page." })),
-                expectedSelector: Type.Optional(Type.String({ description: "Selector or @ref that must appear on the page." })),
-                screenshotPath: Type.Optional(Type.String({ description: "Optional evidence screenshot path captured at the end of the QA preset." })),
-                checkConsole: Type.Optional(Type.Boolean({ description: "Whether to fail on console error messages. Defaults to true." })),
-                checkErrors: Type.Optional(Type.Boolean({ description: "Whether to fail on page errors. Defaults to true." })),
-                checkNetwork: Type.Optional(Type.Boolean({ description: "Whether to inspect network requests and fail on actionable request failures; benign icon misses warn. Defaults to true." })),
-                loadState: Type.Optional(StringEnum(AGENT_BROWSER_QA_LOAD_STATES, { description: "Page readiness state for the QA preset before assertions and diagnostics. Defaults to domcontentloaded; use networkidle only for pages without long-lived background requests." })),
+                url: Type.String(),
+                attached: Type.Optional(Type.Literal(false)),
+                expectedText: Type.Optional(Type.Union([Type.String(), Type.Array(Type.String())])),
+                expectedSelector: Type.Optional(Type.String()),
+                screenshotPath: Type.Optional(Type.String()),
+                checkConsole: Type.Optional(Type.Boolean()),
+                checkErrors: Type.Optional(Type.Boolean()),
+                checkNetwork: Type.Optional(Type.Boolean()),
+                loadState: Type.Optional(StringEnum(AGENT_BROWSER_QA_LOAD_STATES)),
             }, { additionalProperties: false }),
-        ], { description: "Lightweight QA preset. Use qa.url to open a URL, or qa.attached=true to check the current attached session without opening a URL." })),
+        ], { description: "QA a URL or current session (attached=true). Default readiness: domcontentloaded; use networkidle only without long-lived requests. URL diagnostics default on, attached diagnostics off." })),
         sourceLookup: Type.Optional(Type.Object({
-            selector: Type.Optional(Type.String({ description: "Visible selector or @ref whose DOM metadata should be inspected for source hints." })),
-            reactFiberId: Type.Optional(Type.String({ description: "React fiber id to inspect with upstream react inspect. Requires a session opened with --enable react-devtools." })),
-            componentName: Type.Optional(Type.String({ description: "Component name to correlate with react tree output and bounded local workspace search." })),
-            includeDomHints: Type.Optional(Type.Boolean({ description: "Whether selector lookups should inspect DOM HTML attributes for source-like metadata. Defaults to true." })),
-            maxWorkspaceFiles: Type.Optional(Type.Number({ description: "Maximum local source files to scan when componentName is provided. Defaults to 2000 and cannot exceed 5000.", minimum: 1, maximum: SOURCE_LOOKUP_MAX_WORKSPACE_FILES })),
-        }, { additionalProperties: false, description: "EXPERIMENTAL: local UI-to-source candidates only (confidence/evidence, not guaranteed mappings). Compiles to batch; mutually exclusive with other input modes." })),
+            selector: Type.Optional(Type.String({ description: "Visible selector or @ref." })),
+            reactFiberId: Type.Optional(Type.String({ description: "React fiber id; requires --enable react-devtools." })),
+            componentName: Type.Optional(Type.String({ description: "Component for local source search." })),
+            includeDomHints: Type.Optional(Type.Boolean({ description: "Inspect DOM source hints; default true." })),
+            maxWorkspaceFiles: Type.Optional(Type.Number({ description: "Source scan cap; default 2000.", minimum: 1, maximum: SOURCE_LOOKUP_MAX_WORKSPACE_FILES })),
+        }, { additionalProperties: false, description: "EXPERIMENTAL UI-to-source candidates; not guaranteed mappings." })),
         networkSourceLookup: Type.Optional(Type.Object({
-            filter: Type.Optional(Type.String({ description: "Optional upstream network requests filter pattern." })),
-            namespace: Type.Optional(Type.String({ description: "Optional upstream namespace; prepends --namespace <name> before the generated batch." })),
-            requestId: Type.Optional(Type.String({ description: "Optional network request id to inspect with network request <id>." })),
-            session: Type.Optional(Type.String({ description: "Optional upstream session name; prepends --session <name> before the generated batch." })),
-            url: Type.Optional(Type.String({ description: "Optional failed request URL or URL fragment to correlate with local source." })),
-            maxWorkspaceFiles: Type.Optional(Type.Number({ description: "Maximum local source files to scan for URL literals. Defaults to 2000 and cannot exceed 5000.", minimum: 1, maximum: SOURCE_LOOKUP_MAX_WORKSPACE_FILES })),
-        }, { additionalProperties: false, description: "EXPERIMENTAL: failed-request-to-source candidates only (initiator metadata and bounded workspace URL literals; not definitive blame). Compiles to batch; mutually exclusive with other input modes." })),
+            filter: Type.Optional(Type.String({ description: "Network request filter." })),
+            namespace: Type.Optional(Type.String()),
+            requestId: Type.Optional(Type.String({ description: "Request id to inspect." })),
+            session: Type.Optional(Type.String()),
+            url: Type.Optional(Type.String({ description: "Failed URL or fragment." })),
+            maxWorkspaceFiles: Type.Optional(Type.Number({ description: "Source scan cap; default 2000.", minimum: 1, maximum: SOURCE_LOOKUP_MAX_WORKSPACE_FILES })),
+        }, { additionalProperties: false, description: "EXPERIMENTAL failed-request-to-source candidates; not proof." })),
         electron: Type.Optional(Type.Union([
             Type.Object({
-                action: StringEnum(["list"], { description: "List discovered Electron apps." }),
-                query: Type.Optional(Type.String({ description: "Optional case-insensitive substring filter for electron.list across app name, bundle id, desktop id, and paths.", minLength: 1 })),
-                maxResults: Type.Optional(Type.Integer({ description: `Maximum electron.list apps to return. Defaults to ${ELECTRON_DISCOVERY_DEFAULT_MAX_RESULTS}; values above ${ELECTRON_DISCOVERY_MAX_RESULTS} are clamped.`, minimum: 1 })),
+                action: StringEnum(["list"]),
+                query: Type.Optional(Type.String({ description: "Case-insensitive app filter.", minLength: 1 })),
+                maxResults: Type.Optional(Type.Integer({ description: `Result cap; default ${ELECTRON_DISCOVERY_DEFAULT_MAX_RESULTS}, values over ${ELECTRON_DISCOVERY_MAX_RESULTS} are clamped.`, minimum: 1 })),
             }, { additionalProperties: false }),
-            electronLaunchVariant(Type, StringEnum, { appPath: Type.String({ description: "Electron launch target: macOS .app bundle path. Exactly one launch target is required for electron.launch.", minLength: 1 }) }),
-            electronLaunchVariant(Type, StringEnum, { appName: Type.String({ description: "Electron launch target: app display name discovered by electron.list. Exactly one launch target is required for electron.launch.", minLength: 1 }) }),
-            electronLaunchVariant(Type, StringEnum, { bundleId: Type.String({ description: "Electron launch target: macOS bundle identifier discovered by electron.list. Exactly one launch target is required for electron.launch.", minLength: 1 }) }),
-            electronLaunchVariant(Type, StringEnum, { executablePath: Type.String({ description: "Electron launch target: executable path. Discovery is not required when this is provided. Exactly one launch target is required for electron.launch.", minLength: 1 }) }),
+            electronLaunchVariant(Type, StringEnum, { appPath: Type.String({ description: "macOS .app path.", minLength: 1 }) }),
+            electronLaunchVariant(Type, StringEnum, { appName: Type.String({ description: "Name from electron.list.", minLength: 1 }) }),
+            electronLaunchVariant(Type, StringEnum, { bundleId: Type.String({ description: "Bundle id from electron.list.", minLength: 1 }) }),
+            electronLaunchVariant(Type, StringEnum, { executablePath: Type.String({ description: "Executable path.", minLength: 1 }) }),
             Type.Object({
-                action: StringEnum(["status", "cleanup"], { description: "Inspect or cleanup one wrapper-tracked Electron launch by launchId." }),
-                launchId: Type.String({ description: "Wrapper launch id for electron.status and electron.cleanup.", minLength: 1 }),
-                timeoutMs: Type.Optional(Type.Integer({ description: "Bounded status/cleanup timeout in milliseconds.", minimum: 1 })),
+                action: StringEnum(["status", "cleanup"]),
+                launchId: Type.String({ description: "Tracked launch id.", minLength: 1 }),
+                timeoutMs: Type.Optional(Type.Integer({ minimum: 1 })),
             }, { additionalProperties: false }),
             Type.Object({
-                action: StringEnum(["status", "cleanup"], { description: "Inspect or cleanup all wrapper-tracked Electron launches." }),
-                all: Type.Literal(true, { description: "Apply electron.status or electron.cleanup to all wrapper-owned launches." }),
-                timeoutMs: Type.Optional(Type.Integer({ description: "Bounded status/cleanup timeout in milliseconds.", minimum: 1 })),
+                action: StringEnum(["status", "cleanup"]),
+                all: Type.Literal(true),
+                timeoutMs: Type.Optional(Type.Integer({ minimum: 1 })),
             }, { additionalProperties: false }),
             Type.Object({
-                action: StringEnum(["status", "cleanup"], { description: "Inspect or cleanup the only active wrapper-tracked Electron launch." }),
-                timeoutMs: Type.Optional(Type.Integer({ description: "Bounded status/cleanup timeout in milliseconds.", minimum: 1 })),
+                action: StringEnum(["status", "cleanup"]),
+                timeoutMs: Type.Optional(Type.Integer({ minimum: 1 })),
             }, { additionalProperties: false }),
             Type.Object({
-                action: StringEnum(["probe"], { description: "Probe the current attached Electron managed session; launchId is accepted for launch-scoped follow-up actions." }),
-                launchId: Type.Optional(Type.String({ description: "Wrapper launch id for electron.probe follow-up targeting.", minLength: 1 })),
-                timeoutMs: Type.Optional(Type.Integer({ description: "Bounded probe timeout in milliseconds.", minimum: 1 })),
+                action: StringEnum(["probe"]),
+                launchId: Type.Optional(Type.String({ description: "Tracked launch id.", minLength: 1 })),
+                timeoutMs: Type.Optional(Type.Integer({ minimum: 1 })),
             }, { additionalProperties: false }),
-        ], { description: "Electron wrapper action. Fields are action-specific and unsupported fields are rejected." })),
+        ], { description: "Electron discovery, isolated-profile launch, status, probe, or cleanup. Launch defaults: handoff=snapshot, targetType=page; deny wins over allow; lifecycle/debug appArgs rejected." })),
         job: Type.Optional(Type.Object({
-            failFast: Type.Optional(Type.Boolean({ description: "Stop the compiled batch on the first failed job step. Defaults to true so later mutating steps do not run after setup/assertion failures." })),
+            failFast: Type.Optional(Type.Boolean({ description: "Stop on first failure; default true." })),
             steps: Type.Array(Type.Object({
-                action: StringEnum(AGENT_BROWSER_JOB_STEP_ACTIONS, {
-                    description: "Constrained one-call job step compiled to existing upstream batch commands.",
-                }),
-                url: Type.Optional(Type.String({ description: "URL for open steps; exact URL or * / ** glob-style URL pattern for assertUrl steps." })),
-                loadState: Type.Optional(StringEnum(AGENT_BROWSER_QA_LOAD_STATES, { description: "Optional readiness wait to insert immediately after an open step; use domcontentloaded/load/networkidle when the next job step needs page hydration evidence before clicking or reading." })),
-                selector: Type.Optional(Type.String({ description: "Selector or @ref for click/fill/type/select-like steps; omit when using semantic locator fields on click/fill steps." })),
-                locator: Type.Optional(StringEnum(AGENT_BROWSER_SEMANTIC_LOCATORS, { description: "Semantic locator for click/fill steps when selector is omitted." })),
-                role: Type.Optional(Type.String({ description: "Role locator value for click/fill steps when locator is role." })),
-                name: Type.Optional(Type.String({ description: "Accessible name filter for role locator click/fill steps." })),
-                text: Type.Optional(Type.String({ description: "Text for fill steps or visible text for assertText steps." })),
-                value: Type.Optional(Type.String({ description: "Single option value for select steps, or locator value for semantic click/fill steps." })),
-                values: Type.Optional(Type.Array(Type.String({ description: "Option value for select steps." }), { description: "One or more option values for select steps.", minItems: 1 })),
-                path: Type.Optional(Type.String({ description: "Artifact/download path for waitForDownload or screenshot steps." })),
-                delayMs: Type.Optional(Type.Integer({ description: `Optional per-character delay for type steps; when set, the job compiles to focus/keyboard type/wait steps instead of instant fill-like typing, capped at ${AGENT_BROWSER_JOB_TYPE_DELAYED_TEXT_MAX_CHARACTERS} characters.`, minimum: 1 })),
-                press: Type.Optional(Type.String({ description: "Optional key to press after a type step, for example Enter." })),
-                milliseconds: Type.Optional(Type.Number({ description: "Milliseconds for wait steps." })),
+                action: StringEnum(AGENT_BROWSER_JOB_STEP_ACTIONS),
+                url: Type.Optional(Type.String({ description: "Open URL or assertUrl glob." })),
+                loadState: Type.Optional(StringEnum(AGENT_BROWSER_QA_LOAD_STATES, { description: "Readiness wait after open." })),
+                selector: Type.Optional(Type.String({ description: "Selector or @ref." })),
+                locator: Type.Optional(StringEnum(AGENT_BROWSER_SEMANTIC_LOCATORS, { description: "Locator when selector is omitted." })),
+                role: Type.Optional(Type.String({ description: "Role locator." })),
+                name: Type.Optional(Type.String({ description: "Accessible name." })),
+                text: Type.Optional(Type.String({ description: "Fill text or assertText target." })),
+                value: Type.Optional(Type.String({ description: "Select option or locator value." })),
+                values: Type.Optional(Type.Array(Type.String(), { description: "Select options.", minItems: 1 })),
+                path: Type.Optional(Type.String({ description: "Download or screenshot path." })),
+                delayMs: Type.Optional(Type.Integer({ description: `Per-character type delay; text is capped at ${AGENT_BROWSER_JOB_TYPE_DELAYED_TEXT_MAX_CHARACTERS} characters.`, minimum: 1 })),
+                press: Type.Optional(Type.String({ description: "Key to press after typing." })),
+                milliseconds: Type.Optional(Type.Number({ description: "Wait duration in milliseconds." })),
             }, { additionalProperties: false }), { minItems: 1 }),
-        }, { additionalProperties: false })),
-        stdin: Type.Optional(Type.String({ description: "Optional raw stdin content; only supported for batch, eval --stdin, auth save --password-stdin, and is generated internally by job, qa, sourceLookup, or networkSourceLookup mode. Do not use with electron mode." })),
-        outputPath: Type.Optional(Type.String({ description: "Optional workspace-relative or absolute file path that receives the model-facing command data/result after the browser command completes. Useful for eval/get/snapshot captures that should become durable local artifacts.", minLength: 1 })),
-        timeoutMs: Type.Optional(Type.Integer({ description: "Optional per-call wrapper subprocess watchdog in milliseconds for browser CLI args/job/qa/source lookup calls. Use for long opens or large output captures; explicit long wait steps are forwarded, so set timeoutMs above the wait duration plus a small grace window when overriding the derived watchdog. Electron actions use electron.timeoutMs instead.", minimum: 1 })),
+        }, { additionalProperties: false, description: "Constrained multi-step batch." })),
+        stdin: Type.Optional(Type.String({ description: "Raw stdin for batch, eval --stdin, or auth save --password-stdin; unavailable with structured modes and electron." })),
+        outputPath: Type.Optional(Type.String({ description: "Workspace-relative or absolute result path.", minLength: 1 })),
+        timeoutMs: Type.Optional(Type.Integer({ description: "Wrapper timeout in ms; exceed explicit waits. Electron uses electron.timeoutMs.", minimum: 1 })),
         sessionMode: Type.Optional(StringEnum(["auto", "fresh"], {
-            description: "Session handling mode. `auto` reuses the extension-managed pi-scoped session when possible. `fresh` switches that managed session to a fresh upstream launch so launch-scoped flags like --namespace, --restore, --restore-save, restore check flags, --profile, --executable-path, --webgpu, --session-name, --cdp, --state, --auto-connect, --init-script, --enable, -p/--provider, or iOS --device apply and later auto calls follow the new browser.",
+            description: "auto reuses the managed session; fresh starts one for launch-only flags, then makes it the managed session.",
             default: DEFAULT_SESSION_MODE,
         })),
-    }, { additionalProperties: false });
+    }, {
+        additionalProperties: false,
+        description: "Choose one input mode: args, semanticAction, job, qa, sourceLookup, networkSourceLookup, or electron.",
+    });
 }
 export const AGENT_BROWSER_PARAMS = createAgentBrowserParamsSchema();