pi-agent-browser-native 0.3.0 → 0.5.0

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

@@ -1,4 +1,4 @@
-import { GLOBAL_BOOLEAN_FLAGS_WITH_OPTIONAL_VALUES, VALUE_FLAGS, optionalGlobalValueFlagConsumesNext } from "./argv-grammar.js";
+import { GLOBAL_BOOLEAN_FLAGS_WITH_OPTIONAL_VALUES, VALUE_FLAGS, optionalGlobalValueFlagConsumesNext, stripUpstreamGlobalFlags } from "./argv-grammar.js";
 import { isOpenNavigationCommand } from "./command-taxonomy.js";
 function isBooleanLiteral(token) {
     const normalized = token?.trim().toLowerCase();
@@ -33,6 +33,33 @@ export function extractCommandTokens(args) {
     const commandStartIndex = findCommandStartIndex(args);
     return commandStartIndex === undefined ? [] : args.slice(commandStartIndex);
 }
+export function extractUpstreamCommandTokens(args) {
+    return stripUpstreamGlobalFlags(extractCommandTokens(args));
+}
+export function parseWaitCommandTokens(commandTokens) {
+    if (commandTokens[0] !== "wait")
+        return {};
+    const considered = commandTokens.slice(1).map((token, offset) => ({ index: offset + 1, token }));
+    const timeoutIndex = considered.findIndex((entry) => entry.token === "--timeout");
+    if (timeoutIndex >= 0)
+        considered.splice(timeoutIndex, Math.min(2, considered.length - timeoutIndex));
+    for (const flags of [["--url", "-u"], ["--load", "-l"], ["--fn", "-f"], ["--text", "-t"]]) {
+        const match = considered.find((entry) => flags.includes(entry.token));
+        if (match)
+            return { subcommand: match.token };
+    }
+    const download = considered.find((entry) => entry.token === "--download" || entry.token === "-d");
+    if (download) {
+        const downloadPathIndex = download.index + 1;
+        const candidate = commandTokens[downloadPathIndex];
+        return {
+            downloadPath: candidate && !candidate.startsWith("--") ? candidate : undefined,
+            downloadPathIndex: candidate && !candidate.startsWith("--") ? downloadPathIndex : undefined,
+            subcommand: download.token,
+        };
+    }
+    return { subcommand: considered[0]?.token };
+}
 function getOpenCommandTarget(commandTokens) {
     for (let index = 1; index < commandTokens.length; index += 1) {
         const token = commandTokens[index];
@@ -51,10 +78,13 @@ function getOpenCommandTarget(commandTokens) {
     return undefined;
 }
 export function parseCommandInfoFromTokens(commandTokens) {
-    const command = commandTokens[0];
+    const upstreamCommandTokens = stripUpstreamGlobalFlags(commandTokens);
+    const command = upstreamCommandTokens[0];
     return {
         command,
-        subcommand: isOpenNavigationCommand(command) ? getOpenCommandTarget(commandTokens) : commandTokens[1],
+        subcommand: isOpenNavigationCommand(command)
+            ? getOpenCommandTarget(upstreamCommandTokens)
+            : command === "wait" ? parseWaitCommandTokens(upstreamCommandTokens).subcommand : upstreamCommandTokens[1],
     };
 }
 export function parseCommandInfo(args) {
@@ -62,8 +92,10 @@ export function parseCommandInfo(args) {
 }
 export function parseArgvDescriptor(args) {
     const commandTokens = extractCommandTokens(args);
+    const upstreamCommandTokens = stripUpstreamGlobalFlags(commandTokens);
     return {
         commandInfo: parseCommandInfoFromTokens(commandTokens),
         commandTokens,
+        upstreamCommandTokens,
     };
 }

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

@@ -90,6 +90,11 @@ export const GLOBAL_BOOLEAN_FLAGS_WITH_OPTIONAL_VALUES = new Set([
     "--ignore-https-errors",
     "--json",
     "--no-auto-dialog",
+    "--no-pin-tab",
+    "--offline",
+    "--pin-tab",
+    "--quick",
+    "--fix",
     "--quiet",
     "-q",
     "--verbose",
@@ -148,7 +153,7 @@ export function canonicalizeAgentBrowserNamespace(value) {
     }
     return normalized.replace(/[-_]+$/u, "") || undefined;
 }
-function foldAgentBrowserFilesystemIdentity(value, platform) {
+export 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.
@@ -160,7 +165,11 @@ export function getAgentBrowserSessionIdentityKey(sessionName, namespace, platfo
     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 isAgentBrowserSessionIdentityKeyInNamespace(identityKey, namespace) {
+    const prefix = getAgentBrowserSessionIdentityKey("", namespace);
+    return prefix ? identityKey.startsWith(prefix) : !identityKey.includes("\0");
+}
+/** Mirror upstream 0.34.0 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) {
@@ -257,6 +266,39 @@ export function optionalGlobalValueFlagConsumesNext(flag, nextToken) {
         return false;
     return !isKnownCommandToken(nextToken);
 }
+export function projectUpstreamGlobalFlags(args) {
+    const indices = [];
+    const tokens = [];
+    let seenCommand = false;
+    for (let index = 0; index < args.length; index += 1) {
+        const token = args[index];
+        if (token.startsWith("--restore="))
+            continue;
+        if (token === "--restore") {
+            if (!seenCommand && optionalGlobalValueFlagConsumesNext(token, args[index + 1]))
+                index += 1;
+            continue;
+        }
+        if (PREVALIDATED_VALUE_FLAGS.has(token)) {
+            index += 1;
+            continue;
+        }
+        if (GLOBAL_BOOLEAN_FLAGS_WITH_OPTIONAL_VALUES.has(token)) {
+            if (["true", "false"].includes(args[index + 1] ?? ""))
+                index += 1;
+            continue;
+        }
+        tokens.push(token);
+        indices.push(index);
+        if (isKnownCommandToken(token))
+            seenCommand = true;
+    }
+    return { indices, tokens };
+}
+/** Mirror upstream 0.34.0 clean_args: remove global flags wherever they appear before command parsing. */
+export function stripUpstreamGlobalFlags(args) {
+    return projectUpstreamGlobalFlags(args).tokens;
+}
 export function stripSessionlessShapeGlobalFlags(commandTokens) {
     const stripped = [];
     for (let index = 0; index < commandTokens.length; index += 1) {

package/dist/extensions/agent-browser/lib/batch-lifecycle.js

@@ -0,0 +1,71 @@
+import { extractUpstreamCommandTokens } from "./argv-descriptor.js";
+import { isCloseAllCommand, isCloseCommand } from "./command-taxonomy.js";
+import { isRecord } from "./parsing.js";
+function getRowBrowserLaunched(row) {
+    const result = isRecord(row.result) ? row.result : isRecord(row.data) ? row.data : undefined;
+    const lifecycle = isRecord(row.lifecycle) ? row.lifecycle : isRecord(result?.lifecycle) ? result.lifecycle : undefined;
+    const effectiveLaunch = isRecord(lifecycle?.effectiveLaunch) ? lifecycle.effectiveLaunch : undefined;
+    return typeof effectiveLaunch?.browserLaunched === "boolean" ? effectiveLaunch.browserLaunched : undefined;
+}
+export function batchHasSuccessfulCloseAll(data, fallbackCommands = []) {
+    if (!Array.isArray(data))
+        return false;
+    return data.some((row, index) => {
+        if (!isRecord(row) || row.success !== true)
+            return false;
+        const rowCommand = Array.isArray(row.command) && row.command.every((token) => typeof token === "string")
+            ? row.command
+            : fallbackCommands[index];
+        return rowCommand ? isCloseAllCommand(extractUpstreamCommandTokens(rowCommand)) : false;
+    });
+}
+export function getSuccessfulBatchCloseLifecycle(rows, fallbackCommands = []) {
+    if (!Array.isArray(rows))
+        return undefined;
+    let sawClose = false;
+    let endsClosed = false;
+    let browserActiveAfterClose = false;
+    let recordingClosedAfterBatch = false;
+    let statePath;
+    for (const [index, row] of rows.entries()) {
+        if (!isRecord(row))
+            continue;
+        const stepSucceeded = row.success === true;
+        const rowCommand = Array.isArray(row.command) && row.command.every((token) => typeof token === "string")
+            ? row.command
+            : fallbackCommands[index];
+        const browserLaunched = getRowBrowserLaunched(row);
+        if (!rowCommand) {
+            if (sawClose && browserLaunched !== false) {
+                endsClosed = false;
+                browserActiveAfterClose = true;
+                recordingClosedAfterBatch = false;
+            }
+            continue;
+        }
+        const [command, subcommand] = extractUpstreamCommandTokens(rowCommand);
+        if (stepSucceeded && isCloseCommand(command)) {
+            sawClose = true;
+            endsClosed = true;
+            browserActiveAfterClose = false;
+            recordingClosedAfterBatch = true;
+            const result = isRecord(row.result) ? row.result : isRecord(row.data) ? row.data : undefined;
+            statePath = typeof result?.statePath === "string" ? result.statePath : undefined;
+        }
+        else if (sawClose && command === "record") {
+            if (browserLaunched === true || (subcommand === "stop" && browserLaunched === undefined)) {
+                endsClosed = false;
+                browserActiveAfterClose = true;
+            }
+            if (stepSucceeded && subcommand === "stop")
+                recordingClosedAfterBatch = true;
+            else if (stepSucceeded && browserActiveAfterClose && (subcommand === "start" || subcommand === "restart"))
+                recordingClosedAfterBatch = false;
+        }
+        else if (sawClose && browserLaunched !== false) {
+            endsClosed = false;
+            browserActiveAfterClose = true;
+        }
+    }
+    return sawClose ? { endsClosed, recordingClosedAfterBatch, statePath } : undefined;
+}

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

@@ -96,5 +96,5 @@ function isSessionlessCommand(commandTokens) {
     return false;
 }
 export function needsManagedSession(descriptor) {
-    return !isSessionlessCommand(descriptor.commandTokens);
+    return !isSessionlessCommand(descriptor.upstreamCommandTokens);
 }

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

@@ -61,6 +61,10 @@ const COMMAND_CAPABILITIES = [
         invalidatesBatchRefs: true,
         triggersPostMutationSnapshot: true,
     },
+    {
+        command: "diff",
+        guardsPageRefs: true,
+    },
     {
         command: "download",
         eligibleForPageChangeSummary: true,
@@ -92,6 +96,10 @@ const COMMAND_CAPABILITIES = [
         command: "find",
         eligibleForElectronHealthProbe: true,
     },
+    {
+        command: "frame",
+        guardsPageRefs: true,
+    },
     {
         command: "focus",
         guardsPageRefs: true,
@@ -104,6 +112,14 @@ const COMMAND_CAPABILITIES = [
         navigationObservable: true,
         triggersPostMutationSnapshot: true,
     },
+    {
+        command: "get",
+        guardsPageRefs: true,
+    },
+    {
+        command: "highlight",
+        guardsPageRefs: true,
+    },
     {
         command: "hover",
         eligibleForPageChangeSummary: true,
@@ -111,6 +127,10 @@ const COMMAND_CAPABILITIES = [
         invalidatesBatchRefs: true,
         triggersPostMutationSnapshot: true,
     },
+    {
+        command: "is",
+        guardsPageRefs: true,
+    },
     {
         command: "keydown",
         eligibleForElectronHealthProbe: true,
@@ -185,10 +205,12 @@ const COMMAND_CAPABILITIES = [
     {
         command: "screenshot",
         eligibleForPageChangeSummary: true,
+        guardsPageRefs: true,
     },
     {
         command: "scroll",
         eligibleForPageChangeSummary: true,
+        guardsPageRefs: true,
         invalidatesBatchRefs: true,
         triggersPostMutationSnapshot: true,
     },
@@ -281,6 +303,9 @@ export function normalizeCommandName(command) {
 export function isCloseCommand(command) {
     return hasCommandCapability(command, "closesSession");
 }
+export function isCloseAllCommand(commandTokens) {
+    return isCloseCommand(commandTokens[0]) && commandTokens.slice(1).includes("--all");
+}
 export function isOpenNavigationCommand(command) {
     return hasCommandCapability(command, "openNavigation");
 }
@@ -293,8 +318,16 @@ export function isSessionTabPinningExcludedCommand(command) {
 export function isSessionTabPostCommandCorrectionExcludedCommand(command) {
     return hasCommandCapability(command, "excludedFromPostCommandCorrection");
 }
-export function isRefInvalidatingBatchCommand(command) {
-    return hasCommandCapability(command, "invalidatesBatchRefs");
+/** Upstream 0.33.2 record start swaps to a fresh active page before its already-active check, so even a failed start can replace the page; record restart navigates the current page only when a URL operand (any fourth token, mirroring upstream's positional slot) is present. */
+export function isRecordPageTransitionCommand(tokens) {
+    if (tokens[0] !== "record")
+        return false;
+    if (tokens[1] === "start")
+        return true;
+    return tokens[1] === "restart" && tokens.length >= 4;
+}
+export function isRefInvalidatingBatchCommand(step) {
+    return hasCommandCapability(step[0], "invalidatesBatchRefs") || isRecordPageTransitionCommand(step);
 }
 export function isRefGuardedCommand(command) {
     return hasCommandCapability(command, "guardsPageRefs");

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

@@ -266,7 +266,7 @@ export function buildQaCompactPassText(options) {
         lines.push(`Page: ${pageParts.join(" — ")}`);
     lines.push(`Checks run: ${describeQaChecksRun(options.checks)} (${options.batchStepCount} batch step${options.batchStepCount === 1 ? "" : "s"})`);
     if (options.checks.diagnosticsResetAtStart && (options.checks.checkNetwork || options.checks.checkConsole || options.checks.checkErrors)) {
-        lines.push("Diagnostic reset: URL QA cleared enabled network/console/page-error buffers before opening the target; reset rows in details.batchSteps are not counted as current-page failures.");
+        lines.push("Diagnostic isolation: URL QA clears enabled network/console buffers, then snapshots any page-error residue before opening the target. Only unchanged residue is ignored because upstream page-error clear is not reliable.");
     }
     if (options.checks.attached && !options.checks.diagnosticsResetAtStart && (options.checks.checkNetwork || options.checks.checkConsole || options.checks.checkErrors)) {
         lines.push("Attached diagnostics: existing upstream session console/network/error buffers were preserved; rows may include events from before qa.attached started.");
@@ -280,6 +280,19 @@ export function buildQaCompactPassText(options) {
     lines.push("Full diagnostic matrix: see details.qaPreset and details.batchSteps.");
     return lines.join("\n");
 }
+export function buildQaCompactFailureText(options) {
+    const lines = [options.qaPreset.summary];
+    const pageParts = [options.page?.title, options.page?.url].filter((part) => typeof part === "string" && part.length > 0);
+    if (pageParts.length > 0)
+        lines.push(`Page: ${pageParts.join(" — ")}`);
+    if (options.qaPreset.failedChecks.length > 0)
+        lines.push("Failed checks:", ...options.qaPreset.failedChecks.map((failure) => `- ${failure}`));
+    if (options.qaPreset.warnings.length > 0)
+        lines.push("Warnings:", ...options.qaPreset.warnings.map((warning) => `- ${warning}`));
+    lines.push(`Checks run: ${describeQaChecksRun(options.checks)} (${options.batchStepCount} batch step${options.batchStepCount === 1 ? "" : "s"})`);
+    lines.push("Full diagnostic matrix: see details.qaPreset and details.batchSteps.");
+    return lines.join("\n");
+}
 const QA_VISIBLE_TEXT_TIMEOUT_MS = 5_000;
 function formatQaExpectedTextPreview(text) {
     return JSON.stringify(text.length > 80 ? `${text.slice(0, 77)}...` : text);
@@ -348,6 +361,34 @@ function extractQaTextAssertionResultText(item) {
     }
     return undefined;
 }
+function qaErrorSignature(error) {
+    if (typeof error === "string")
+        return error;
+    try {
+        return JSON.stringify(error);
+    }
+    catch {
+        return String(error);
+    }
+}
+function subtractQaBaselineErrors(errors, baselineErrors) {
+    const baselineCounts = new Map();
+    for (const error of baselineErrors) {
+        const signature = qaErrorSignature(error);
+        baselineCounts.set(signature, (baselineCounts.get(signature) ?? 0) + 1);
+    }
+    let ignoredCount = 0;
+    const novelErrors = errors.filter((error) => {
+        const signature = qaErrorSignature(error);
+        const count = baselineCounts.get(signature) ?? 0;
+        if (count === 0)
+            return true;
+        baselineCounts.set(signature, count - 1);
+        ignoredCount += 1;
+        return false;
+    });
+    return { ignoredCount, novelErrors };
+}
 function isDiagnosticResetCommand(item) {
     const command = item.command;
     if (!Array.isArray(command) || !command.every((token) => typeof token === "string"))
@@ -372,17 +413,29 @@ export function analyzeQaPresetResults(data, compiled) {
         return undefined;
     const failedChecks = [];
     const warnings = [];
-    for (const item of items) {
+    const baselineErrorIndex = compiled?.checks.diagnosticsResetAtStart && compiled.checks.checkErrors
+        ? compiled.steps.findIndex((step) => step.generatedFrom === "qa.errorBaselineAfterClear")
+        : -1;
+    const baselineErrorItem = baselineErrorIndex >= 0 ? items[baselineErrorIndex] : undefined;
+    const baselineErrorResult = isRecord(baselineErrorItem?.result) ? baselineErrorItem.result : undefined;
+    const baselineErrors = Array.isArray(baselineErrorResult?.errors) ? baselineErrorResult.errors : [];
+    for (const [index, item] of items.entries()) {
         if (item.success === false) {
             failedChecks.push(`${getCommandNameFromBatchItem(item) ?? "step"} failed`);
         }
+        if (index === baselineErrorIndex)
+            continue;
         const result = isRecord(item.result) ? item.result : undefined;
         const commandName = getCommandNameFromBatchItem(item);
         if (compiled?.checks.diagnosticsResetAtStart && isDiagnosticResetCommand(item)) {
             continue;
         }
         if (commandName === "errors" && Array.isArray(result?.errors) && result.errors.length > 0) {
-            failedChecks.push(`${result.errors.length} page error(s)`);
+            const { ignoredCount, novelErrors } = subtractQaBaselineErrors(result.errors, baselineErrors);
+            if (novelErrors.length > 0)
+                failedChecks.push(`${novelErrors.length} page error(s)`);
+            if (ignoredCount > 0)
+                warnings.push(`${ignoredCount} post-clear page error residue row(s) ignored as unchanged`);
         }
         if (commandName === "console" && Array.isArray(result?.messages)) {
             const errorCount = result.messages.filter((message) => isRecord(message) && /error/i.test(String(message.type ?? message.level ?? ""))).length;
@@ -477,11 +530,15 @@ export function compileAgentBrowserQaPreset(input) {
         steps.push({ action: "wait", args: ["network", "requests", "--clear"] });
     if (diagnosticsResetAtStart && checkConsole)
         steps.push({ action: "wait", args: ["console", "--clear"] });
-    if (diagnosticsResetAtStart && checkErrors)
+    if (diagnosticsResetAtStart && checkErrors) {
         steps.push({ action: "wait", args: ["errors", "--clear"] });
+        steps.push({ action: "wait", args: ["errors"], generatedFrom: "qa.errorBaselineAfterClear" });
+    }
     if (!attached && normalizedUrl)
         steps.push({ action: "open", args: ["open", normalizedUrl] });
     steps.push({ action: "wait", args: ["wait", "--load", loadState] });
+    if (checkConsole || checkErrors)
+        steps.push({ action: "wait", args: ["wait", "150"], generatedFrom: "qa.diagnosticSettle" });
     for (const text of expectedText) {
         steps.push({ action: "assertText", args: ["wait", "--fn", buildQaVisibleTextPredicate(text), "--timeout", String(QA_VISIBLE_TEXT_TIMEOUT_MS)] });
     }

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

@@ -261,8 +261,8 @@ export function compileAgentBrowserNetworkSourceLookup(input) {
         return { error: "networkSourceLookup.filter must be a non-empty string when provided." };
     if (requestId !== undefined && (typeof requestId !== "string" || requestId.trim().length === 0))
         return { error: "networkSourceLookup.requestId must be a non-empty string when provided." };
-    if (namespace !== undefined && (typeof namespace !== "string" || namespace.trim().length === 0))
-        return { error: "networkSourceLookup.namespace must be a non-empty string when provided." };
+    if (namespace !== undefined && (typeof namespace !== "string" || (namespace !== "" && namespace.trim().length === 0)))
+        return { error: "networkSourceLookup.namespace must be a non-empty string or the empty default namespace when provided." };
     if (session !== undefined && (typeof session !== "string" || session.trim().length === 0))
         return { error: "networkSourceLookup.session must be a non-empty string when provided." };
     if (url !== undefined && (typeof url !== "string" || url.trim().length === 0))

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

@@ -1,34 +1,24 @@
 import { JsonSchema } from "../json-schema.js";
 import { StringEnum as localStringEnum } from "../string-enum-schema.js";
+import { AGENT_BROWSER_SCRIPT_CODE_MAX_BYTES } from "./script.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 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"]),
-        ...targetField,
-        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({
+        script: Type.Optional(Type.String({
+            description: "One-shot JavaScript orchestration with async browser({ args, stdin?, timeoutMs? }) and emit(value); isolated session and no host access.",
+            maxLength: AGENT_BROWSER_SCRIPT_CODE_MAX_BYTES,
+        })),
         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),
-            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 })),
+            locator: Type.Optional(StringEnum(AGENT_BROWSER_SEMANTIC_LOCATORS, { description: "Locator for check/click/fill; select supports role or label." })),
+            value: Type.Optional(Type.String({ description: "Locator value or one select option; for select by label, this is the label text." })),
+            values: Type.Optional(Type.Array(Type.String(), { description: "Select options; required for select by label.", 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." })),
@@ -79,10 +69,19 @@ export function createAgentBrowserParamsSchema(Type = JsonSchema, StringEnum = l
                 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: "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(["launch"]),
+                appPath: Type.Optional(Type.String({ description: "macOS .app path.", minLength: 1 })),
+                appName: Type.Optional(Type.String({ description: "Name from electron.list.", minLength: 1 })),
+                bundleId: Type.Optional(Type.String({ description: "Bundle id from electron.list.", minLength: 1 })),
+                executablePath: Type.Optional(Type.String({ description: "Executable path.", minLength: 1 })),
+                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 }),
             Type.Object({
                 action: StringEnum(["status", "cleanup"]),
                 launchId: Type.String({ description: "Tracked launch id.", minLength: 1 }),
@@ -131,7 +130,7 @@ export function createAgentBrowserParamsSchema(Type = JsonSchema, StringEnum = l
         })),
     }, {
         additionalProperties: false,
-        description: "Choose one input mode: args, semanticAction, job, qa, sourceLookup, networkSourceLookup, or electron.",
+        description: "Choose one input mode: script, args, semanticAction, job, qa, sourceLookup, networkSourceLookup, or electron.",
     });
 }
 export const AGENT_BROWSER_PARAMS = createAgentBrowserParamsSchema();