pi-agent-browser-native 0.3.0 → 0.6.5

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

@@ -1,14 +1,16 @@
 import { createHash, randomUUID } from "node:crypto";
 import { basename } from "node:path";
-import { findCommandStartIndex, parseArgvDescriptor, parseCommandInfo, } from "./argv-descriptor.js";
-import { canonicalizeAgentBrowserNamespace, extractExplicitNamespace, extractExplicitSessionName, getAgentBrowserSessionIdentityKey, getBooleanFlagValue, GLOBAL_VALUE_FLAGS_ALLOWING_DASH_VALUE, isUpstreamEnvFlagEnabled, PREVALIDATED_VALUE_FLAGS, resolveAgentBrowserNamespace, scanUpstreamGlobalFlagOccurrences, } from "./argv-grammar.js";
+import { extractUpstreamCommandTokens, findCommandStartIndex, parseArgvDescriptor, parseCommandInfo, } from "./argv-descriptor.js";
+import { batchHasSuccessfulCloseAll, getSuccessfulBatchCloseLifecycle } from "./batch-lifecycle.js";
+import { canonicalizeAgentBrowserNamespace, extractExplicitNamespace, extractExplicitSessionName, getAgentBrowserSessionIdentityKey, getBooleanFlagValue, GLOBAL_BOOLEAN_FLAGS_WITH_OPTIONAL_VALUES, GLOBAL_VALUE_FLAGS_ALLOWING_DASH_VALUE, isAgentBrowserSessionIdentityKeyInNamespace, isUpstreamEnvFlagEnabled, PREVALIDATED_VALUE_FLAGS, resolveAgentBrowserNamespace, scanUpstreamGlobalFlagOccurrences, } from "./argv-grammar.js";
 import { needsManagedSession } from "./command-policy.js";
-import { isWrapperManagedSessionName, redactManagedSessionRestoreKeys } from "./managed-session-capabilities.js";
-import { isCloseCommand, isOpenNavigationCommand } from "./command-taxonomy.js";
+import { isCloseAllCommand, isCloseCommand, isOpenNavigationCommand } from "./command-taxonomy.js";
 import { hasLaunchScopedFlagToken, LAUNCH_SCOPED_FLAG_DEFINITIONS, LAUNCH_SCOPED_FLAG_LABEL, } from "./launch-scoped-flags.js";
 import { MANAGED_SESSION_NAME_PREFIX, } from "./managed-session-restore.js";
-export { extractCommandTokens, findCommandStartIndex, parseArgvDescriptor, parseCommandInfo } from "./argv-descriptor.js";
+export { extractCommandTokens, extractUpstreamCommandTokens, findCommandStartIndex, parseArgvDescriptor, parseCommandInfo, parseWaitCommandTokens } from "./argv-descriptor.js";
 import { isRecord } from "./parsing.js";
+import { getAgentBrowserProcessEnvironment } from "./process-environment.js";
+import { TARGET_AGENT_BROWSER_VERSION } from "./upstream-version.js";
 const OPENAI_HEADLESS_COMPAT_HOSTS = new Set(["chat.com", "chat.openai.com", "chatgpt.com"]);
 const CLOUDFLARE_HEADLESS_COMPAT_HOST = "dash.cloudflare.com";
 const AGENT_BROWSER_IDLE_TIMEOUT_ENV = "AGENT_BROWSER_IDLE_TIMEOUT_MS";
@@ -18,7 +20,9 @@ const DEFAULT_IMPLICIT_SESSION_IDLE_TIMEOUT_MS = 15 * 60 * 1000;
 const DEFAULT_IMPLICIT_SESSION_CLOSE_TIMEOUT_MS = 5_000;
 const INSPECTION_FLAGS = new Set(["--help", "-h", "--version", "-V"]);
 const SENSITIVE_VALUE_FLAGS = new Set(["--body", "--headers", "--password", "--proxy"]);
-const SENSITIVE_QUERY_PARAM_PATTERN = /^(?:access(?:_|-)?token|api(?:_|-)?key|auth|authorization|bearer|client(?:_|-)?secret|code|cookie|id(?:_|-)?token|key|pass(?:word)?|refresh(?:_|-)?token|secret|sentry(?:_|-)?key|session(?:_|-)?id|sig(?:nature)?|token|write(?:_|-)?key)$/i;
+const SENSITIVE_QUERY_PARAM_PATTERN = /^(?:access(?:_|-)?token|api(?:_|-)?key|auth|authorization|bearer|client(?:_|-)?secret|code|cookie|id(?:_|-)?token|key|pass(?:word)?|refresh(?:_|-)?token|relay(?:_|-)?state|saml(?:_|-)?request|saml(?:_|-)?response|secret|sentry(?:_|-)?key|session(?:_|-)?id|sig(?:nature)?|token|write(?:_|-)?key)$/i;
+const AUTH_STATE_QUERY_PARAM_PATTERN = /^(?:nonce|state)$/i;
+const AUTH_URL_CONTEXT_PATTERN = /(?:^|[./_-])(?:auth|authorize|callback|login|oauth2?|oidc|saml|sso)(?:[./?#_-]|$)/i;
 const SENSITIVE_FIELD_NAME_PATTERN = /^(?:[A-Za-z0-9_-]*(?:api[_-]?key|access[_-]?key|private[_-]?key|secret(?:[_-]?(?:key|access[_-]?key))?|token|password|passwd|credentials?|database[_-]?url|db[_-]?url|connection[_-]?string|mongo(?:db)?[_-]?uri|redis[_-]?url)|[A-Za-z0-9]*(?:apiKey|ApiKey|apikey|privateKey|PrivateKey|databaseUrl|DatabaseUrl|dbUrl|DbUrl|connectionString|ConnectionString|mongoUri|MongoUri|mongodbUri|MongodbUri|mongoDbUri|MongoDbUri|redisUrl|RedisUrl|Token|Secret|Password|Credential|Credentials)|auth(?:orization)?|bearer|client(?:_|-)?secret|cookie|id(?:_|-)?token|pass(?:word)?|proxy(?:_|-)?authorization|refresh(?:_|-)?token|sentry(?:_|-)?key|session(?:_|-)?id|set(?:_|-)?cookie|sig(?:nature)?|write(?:_|-)?key|x(?:_|-)?api(?:_|-)?key)$/i;
 const ENV_SECRET_ASSIGNMENT_PATTERN = /\b((?:export\s+)?([A-Za-z_][A-Za-z0-9_-]*)(\s*[:=]\s*))(?:"(?:\\.|[^"\\])*"|'(?:\\.|[^'\\])*'|[^\s,;]+)/g;
 const DEFAULT_HEADLESS_COMPAT_USER_AGENT_BY_PLATFORM = {
@@ -28,6 +32,7 @@ const DEFAULT_HEADLESS_COMPAT_USER_AGENT_BY_PLATFORM = {
 };
 const FALLBACK_HEADLESS_COMPAT_USER_AGENT = "Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/146.0.0.0 Safari/537.36";
 const SHELL_OPERATOR_TOKENS = new Set(["&&", "||", "|", ";", ">", ">>", "<"]);
+const ANDROID_SESSION_NAME_IDENTITY_LENGTH = 20;
 const MAX_PROJECT_SLUG_LENGTH = 24;
 const SESSION_NAME_CWD_HASH_LENGTH = 8;
 const SESSION_NAME_SESSION_ID_LENGTH = 12;
@@ -45,48 +50,57 @@ function redactUrlToken(token) {
     catch {
         return token;
     }
-    let mutated = false;
-    if (parsed.username.length > 0) {
+    if (parsed.username.length > 0)
         parsed.username = "[REDACTED]";
-        mutated = true;
-    }
-    if (parsed.password.length > 0) {
+    if (parsed.password.length > 0)
         parsed.password = "[REDACTED]";
-        mutated = true;
-    }
+    const hashText = parsed.hash.startsWith("#") ? parsed.hash.slice(1) : parsed.hash;
+    const hashParams = hashText.includes("=") ? new URLSearchParams(hashText) : undefined;
+    const authContext = AUTH_URL_CONTEXT_PATTERN.test(`${parsed.hostname}${parsed.pathname}`)
+        || [...parsed.searchParams.keys(), ...(hashParams?.keys() ?? [])].some(shouldRedactQueryParam);
     for (const [name] of parsed.searchParams) {
-        if (shouldRedactQueryParam(name)) {
+        if (shouldRedactQueryParam(name) || (authContext && AUTH_STATE_QUERY_PARAM_PATTERN.test(name))) {
             parsed.searchParams.set(name, "[REDACTED]");
-            mutated = true;
         }
     }
-    const hashText = parsed.hash.startsWith("#") ? parsed.hash.slice(1) : parsed.hash;
-    if (hashText.includes("=")) {
-        const hashParams = new URLSearchParams(hashText);
+    if (hashParams) {
+        let hashMutated = false;
         for (const [name] of hashParams) {
-            if (shouldRedactQueryParam(name)) {
+            if (shouldRedactQueryParam(name) || (authContext && AUTH_STATE_QUERY_PARAM_PATTERN.test(name))) {
                 hashParams.set(name, "[REDACTED]");
-                mutated = true;
+                hashMutated = true;
             }
         }
-        if (mutated) {
+        if (hashMutated)
             parsed.hash = `#${hashParams.toString()}`;
-        }
     }
     return parsed.toString();
 }
 function redactLooseUrlParameterText(text) {
-    return text.replace(/([?#&])([^=&#\s]+)=([^&#\s]*)/g, (match, separator, rawName) => {
-        let name = rawName;
-        try {
-            name = decodeURIComponent(rawName.replace(/\+/g, " "));
-        }
-        catch {
-            // Keep the raw name when percent decoding fails.
-        }
-        if (!shouldRedactQueryParam(name))
-            return match;
-        return `${separator}${rawName}=[REDACTED]`;
+    return text.replace(/(?<![^\s"'`<>\])}])[^\s"'`<>\])}]*[?#&][^\s"'`<>\])}]*/g, (token) => {
+        const queryNames = [...token.matchAll(/[?#&]([^=&#\s"'`<>\])}]+)=/g)].map((match) => {
+            try {
+                return decodeURIComponent((match[1] ?? "").replace(/\+/g, " "));
+            }
+            catch {
+                return match[1] ?? "";
+            }
+        });
+        const authContext = AUTH_URL_CONTEXT_PATTERN.test(token) || queryNames.some(shouldRedactQueryParam);
+        return token.replace(/([?#&])([^=&#\s"'`<>\])}]+)=([^&#\s"'`<>\])}]*)/g, (match, separator, rawName, rawValue) => {
+            if (rawValue === "[REDACTED" || rawValue === "[REDACTED]" || /%5Bredacted%5D/i.test(rawValue))
+                return match;
+            let name = rawName;
+            try {
+                name = decodeURIComponent(rawName.replace(/\+/g, " "));
+            }
+            catch {
+                // Keep the raw name when percent decoding fails.
+            }
+            if (!shouldRedactQueryParam(name) && !(authContext && AUTH_STATE_QUERY_PARAM_PATTERN.test(name)))
+                return match;
+            return `${separator}${rawName}=[REDACTED]`;
+        });
     });
 }
 function redactLooseUrlUserinfo(text) {
@@ -222,7 +236,7 @@ function redactEnvSecretAssignments(text) {
     });
 }
 export function redactSensitiveText(text) {
-    return redactEmbeddedStructuredText(redactEnvSecretAssignments(redactStandaloneBasicCredential(redactBearerCredentials(redactLooseUrlUserinfo(redactLooseUrlMatches(redactManagedSessionRestoreKeys(text))))
+    return redactEmbeddedStructuredText(redactEnvSecretAssignments(redactStandaloneBasicCredential(redactBearerCredentials(redactLooseUrlParameterText(redactLooseUrlUserinfo(redactLooseUrlMatches(text))))
         .replace(/\b(Authorization\s*:\s*Basic)\s+[^\s",]+/gi, "$1 [REDACTED]")
         .replace(/\b(Cookie|Set-Cookie)\s*:\s*[^\n\r"]+/gi, "$1: [REDACTED]"))));
 }
@@ -311,7 +325,7 @@ function parseTimeoutMs(rawValue, minimumValue) {
     }
     return parsedValue;
 }
-export function getImplicitSessionIdleTimeoutMs(env = process.env) {
+export function getImplicitSessionIdleTimeoutMs(env = getAgentBrowserProcessEnvironment()) {
     return parseTimeoutMs(env[IMPLICIT_SESSION_IDLE_TIMEOUT_ENV], 0) ??
         parseTimeoutMs(env[AGENT_BROWSER_IDLE_TIMEOUT_ENV], 0) ??
         DEFAULT_IMPLICIT_SESSION_IDLE_TIMEOUT_MS;
@@ -319,21 +333,7 @@ export function getImplicitSessionIdleTimeoutMs(env = process.env) {
 function countExplicitGlobalFlags(args, targetFlag) {
     return scanUpstreamGlobalFlagOccurrences(args, targetFlag).length;
 }
-function getUnsupportedLeadingIdentityAssignment(args) {
-    const commandStartIndex = findCommandStartIndex(args) ?? args.length;
-    for (let index = 0; index < commandStartIndex; index += 1) {
-        const token = args[index];
-        if (token.startsWith("--session="))
-            return "--session";
-        if (token.startsWith("--namespace="))
-            return "--namespace";
-        const flag = token.split("=", 1)[0] ?? token;
-        if (!token.includes("=") && PREVALIDATED_VALUE_FLAGS.has(flag))
-            index += 1;
-    }
-    return undefined;
-}
-export function getImplicitSessionCloseTimeoutMs(env = process.env) {
+export function getImplicitSessionCloseTimeoutMs(env = getAgentBrowserProcessEnvironment()) {
     return parseTimeoutMs(env[IMPLICIT_SESSION_CLOSE_TIMEOUT_ENV], 0) ?? DEFAULT_IMPLICIT_SESSION_CLOSE_TIMEOUT_MS;
 }
 export function resolveManagedSessionState(options) {
@@ -381,15 +381,18 @@ function getManagedSessionRestoreRank(options) {
 function getRestorableManagedSessionName(value, fallbackSessionName) {
     return typeof value === "string" && isRestorableManagedSessionName(value, fallbackSessionName) ? value : undefined;
 }
-function getElectronCleanupClosedManagedSessionNames(details, fallbackSessionName) {
+function getElectronCleanupClosedManagedSessions(details, fallbackSessionName) {
     const electron = isRecord(details.electron) ? details.electron : undefined;
     const cleanup = isRecord(electron?.cleanup) ? electron.cleanup : undefined;
     const results = Array.isArray(cleanup?.results) ? cleanup.results : [];
-    const closedSessionNames = new Set();
+    const closedSessions = [];
     for (const result of results) {
         if (!isRecord(result) || !Array.isArray(result.steps))
             continue;
         const record = isRecord(result.record) ? result.record : undefined;
+        const fallbackNamespace = typeof record?.namespace === "string"
+            ? record.namespace
+            : typeof details.namespace === "string" ? details.namespace : undefined;
         for (const step of result.steps) {
             if (!isRecord(step) || step.resource !== "managed-session")
                 continue;
@@ -397,11 +400,12 @@ function getElectronCleanupClosedManagedSessionNames(details, fallbackSessionNam
                 continue;
             const sessionName = getRestorableManagedSessionName(step.sessionName, fallbackSessionName)
                 ?? getRestorableManagedSessionName(record?.sessionName, fallbackSessionName);
+            const namespace = typeof step.namespace === "string" ? step.namespace : fallbackNamespace;
             if (sessionName)
-                closedSessionNames.add(sessionName);
+                closedSessions.push({ namespace, sessionName });
         }
     }
-    return [...closedSessionNames];
+    return closedSessions;
 }
 export function restoreManagedSessionStateFromBranch(branch, fallbackSessionName) {
     const restoreDisabledIdentities = new Map();
@@ -441,16 +445,23 @@ export function restoreManagedSessionStateFromBranch(branch, fallbackSessionName
         if (isPlainTextInspectionArgs(args)) {
             continue;
         }
-        for (const sessionName of getElectronCleanupClosedManagedSessionNames(details, fallbackSessionName)) {
-            applyManagedClose(sessionName);
+        for (const cleanupSession of getElectronCleanupClosedManagedSessions(details, fallbackSessionName)) {
+            applyManagedClose(cleanupSession.sessionName, cleanupSession.namespace);
         }
         const explicitSessionName = extractExplicitSessionName(args);
         const sessionName = typeof details.sessionName === "string" ? details.sessionName : undefined;
         const namespace = canonicalizeAgentBrowserNamespace(typeof details.namespace === "string" ? details.namespace : undefined);
         const sessionMode = details.sessionMode === "fresh" || details.sessionMode === "auto" ? details.sessionMode : undefined;
         const usedImplicitSession = details.usedImplicitSession === true;
+        const commandTokens = extractUpstreamCommandTokens(args);
         const command = typeof details.command === "string" ? details.command : parseCommandInfo(args).command;
-        const commandClosesSession = isCloseCommand(command);
+        const batchCloseLifecycle = getSuccessfulBatchCloseLifecycle(details.batchSteps);
+        const nestedBatchEndsClosed = batchCloseLifecycle?.endsClosed === true;
+        const nestedBatchRemainsActive = batchCloseLifecycle?.endsClosed === false;
+        const closeAllApplied = details.closeAllApplied === true
+            || (message.isError !== true && isCloseAllCommand(commandTokens))
+            || batchHasSuccessfulCloseAll(details.batchSteps);
+        const commandClosesSession = isCloseCommand(command) || nestedBatchEndsClosed;
         const outcome = typeof details.managedSessionOutcome === "object" && details.managedSessionOutcome !== null ? details.managedSessionOutcome : undefined;
         const outcomeStatus = typeof outcome?.status === "string" ? outcome.status : undefined;
         const outcomeCurrentSessionName = typeof outcome?.currentSessionName === "string" ? outcome.currentSessionName : undefined;
@@ -459,6 +470,14 @@ export function restoreManagedSessionStateFromBranch(branch, fallbackSessionName
             ? outcomeAttemptedSessionName ?? getRestorableManagedSessionName(outcomeCurrentSessionName, fallbackSessionName) ?? getRestorableManagedSessionName(sessionName, fallbackSessionName)
             : undefined;
         const restorableDetailSessionName = getRestorableManagedSessionName(sessionName, fallbackSessionName);
+        if (closeAllApplied && restoredState.active) {
+            const restoredKey = getAgentBrowserSessionIdentityKey(restoredState.sessionName, restoredState.namespace);
+            const resultKey = restorableDetailSessionName ? getAgentBrowserSessionIdentityKey(restorableDetailSessionName, namespace) : undefined;
+            const retainsCurrentSession = nestedBatchRemainsActive && resultKey === restoredKey;
+            if (isAgentBrowserSessionIdentityKeyInNamespace(restoredKey, namespace) && !retainsCurrentSession) {
+                applyManagedClose(restoredState.sessionName, restoredState.namespace);
+            }
+        }
         const explicitCloseSessionName = commandClosesSession && explicitSessionName && restorableDetailSessionName === explicitSessionName
             ? restorableDetailSessionName
             : undefined;
@@ -467,13 +486,13 @@ export function restoreManagedSessionStateFromBranch(branch, fallbackSessionName
         if (details.managedSessionRestoreDisabled === true && typeof sessionName === "string") {
             restoreDisabledIdentities.set(getAgentBrowserSessionIdentityKey(sessionName, namespace), { namespace, sessionName });
         }
-        const managedSessionName = !explicitSessionName &&
+        const managedSessionName = outcomeClosedSessionName ?? (!explicitSessionName &&
             restorableDetailSessionName &&
             (usedImplicitSession || sessionMode === "fresh")
             ? restorableDetailSessionName
             : commandClosesSession
-                ? outcomeClosedSessionName ?? explicitCloseSessionName
-                : undefined;
+                ? explicitCloseSessionName
+                : undefined);
         if (!managedSessionName) {
             continue;
         }
@@ -490,9 +509,11 @@ export function restoreManagedSessionStateFromBranch(branch, fallbackSessionName
         const exitCode = typeof details.exitCode === "number" ? details.exitCode : undefined;
         const outcomeActiveAfter = outcome?.activeAfter === true;
         const outcomeRepresentsActiveCurrentSession = outcomeActiveAfter && outcomeCurrentSessionName === managedSessionName && (outcomeStatus === "created" || outcomeStatus === "replaced" || outcomeStatus === "unchanged");
-        const succeeded = outcomeRepresentsActiveCurrentSession ? true : messageIsError === undefined ? exitCode === undefined || exitCode === 0 : !messageIsError;
-        if (commandClosesSession) {
-            if (succeeded) {
+        const succeeded = outcomeRepresentsActiveCurrentSession || nestedBatchRemainsActive
+            ? true
+            : messageIsError === undefined ? exitCode === undefined || exitCode === 0 : !messageIsError;
+        if (commandClosesSession || outcomeClosedSessionName) {
+            if (nestedBatchEndsClosed || outcomeClosedSessionName || succeeded) {
                 restoreDisabledIdentities.delete(getAgentBrowserSessionIdentityKey(managedSessionName, namespace));
                 applyManagedClose(managedSessionName, namespace);
             }
@@ -529,15 +550,24 @@ export function createEphemeralSessionSeed() {
 function createCwdHash(cwd) {
     return createHash("sha256").update(`cwd:${cwd}`).digest("hex").slice(0, SESSION_NAME_CWD_HASH_LENGTH);
 }
-export function createImplicitSessionName(sessionId, cwd, ephemeralSeed) {
+export function createImplicitSessionName(sessionId, cwd, ephemeralSeed, platform = process.platform) {
+    const normalizedSessionId = sessionId?.replaceAll("-", "").toLowerCase();
+    if (platform === "android") {
+        const identity = normalizedSessionId ? `session:${normalizedSessionId}:cwd:${cwd}` : `ephemeral:${cwd}:${ephemeralSeed}`;
+        const digest = createHash("sha256").update(identity).digest("hex").slice(0, ANDROID_SESSION_NAME_IDENTITY_LENGTH);
+        return `${MANAGED_SESSION_NAME_PREFIX}${digest}`;
+    }
     const slug = basename(cwd)
         .toLowerCase()
         .replace(/[^a-z0-9]+/g, "-")
         .replace(/^-+|-+$/g, "")
         .slice(0, MAX_PROJECT_SLUG_LENGTH) || "project";
     const cwdHash = createCwdHash(cwd);
-    const stableSessionId = sessionId?.replace(/-/g, "").slice(0, SESSION_NAME_SESSION_ID_LENGTH);
-    if (stableSessionId && stableSessionId.length > 0) {
+    if (normalizedSessionId) {
+        const stableSessionId = createHash("sha256")
+            .update(`session:${normalizedSessionId}`)
+            .digest("hex")
+            .slice(0, SESSION_NAME_SESSION_ID_LENGTH);
         return `${MANAGED_SESSION_NAME_PREFIX}${slug}-${stableSessionId}-${cwdHash}`;
     }
     const digest = createHash("sha256")
@@ -554,7 +584,7 @@ export function createFreshSessionName(baseSessionName, ephemeralSeed, ordinal)
     return `${baseSessionName}-fresh-${suffix}`;
 }
 function getSingleKeyCommandValidationError(args) {
-    const { commandInfo, commandTokens } = parseArgvDescriptor(args);
+    const { commandInfo, upstreamCommandTokens: commandTokens } = parseArgvDescriptor(args);
     const command = commandInfo.command;
     if (command !== "press" && command !== "key" && command !== "keydown" && command !== "keyup")
         return undefined;
@@ -564,14 +594,20 @@ function getSingleKeyCommandValidationError(args) {
     return `agent-browser ${label} accepts exactly one key argument. Do not pass a selector or ref to ${label}; focus or click the target first, then run ${command} <key> (for example: focus @e1, then press Enter).`;
 }
 function getBareMcpValidationError(args) {
-    const { commandInfo, commandTokens } = parseArgvDescriptor(args);
+    const { commandInfo, upstreamCommandTokens: commandTokens } = parseArgvDescriptor(args);
     if (commandInfo.command !== "mcp")
         return undefined;
     if (commandTokens.includes("--help") || commandTokens.includes("-h"))
         return undefined;
     return "agent-browser mcp starts a stdio MCP server for external MCP clients, not a one-shot native agent_browser tool workflow. Use the native agent_browser tool modes directly, or configure an MCP client to launch `agent-browser mcp`. Use `mcp --help` for help.";
 }
-export function validateToolArgs(args) {
+function getUnsupportedInlineWaitDownloadError(args) {
+    const descriptor = parseArgvDescriptor(args);
+    if (descriptor.commandInfo.command !== "wait" || !descriptor.upstreamCommandTokens.some((token) => token.startsWith("--download=")))
+        return undefined;
+    return `agent-browser ${TARGET_AGENT_BROWSER_VERSION} does not support \`wait --download=<path>\`. Pass the optional path as a separate argument: \`wait --download <path>\` (or \`wait -d <path>\`).`;
+}
+export function validateToolArgs(args, options = {}) {
     if (args.length === 0) {
         return "`args` must contain at least one agent-browser command token.";
     }
@@ -583,31 +619,34 @@ export function validateToolArgs(args) {
     if (sessionModeArg) {
         return "Do not pass `--session-mode` in args. Use the top-level agent_browser `sessionMode` field instead, for example { args: [\"--profile\", \"Default\", \"open\", \"https://example.com\"], sessionMode: \"fresh\" }.";
     }
-    return getBareMcpValidationError(args) ?? getSingleKeyCommandValidationError(args);
+    const inspection = !options.batchStep && isPlainTextInspectionArgs(args);
+    const invalidValueFlag = inspection ? undefined : getInvalidValueFlagDetails(args, !options.batchStep);
+    if (invalidValueFlag?.reason === "unsupported-assignment")
+        return formatInvalidValueFlagError(invalidValueFlag, options.batchStep);
+    return getBareMcpValidationError(args) ?? getSingleKeyCommandValidationError(args) ?? getUnsupportedInlineWaitDownloadError(args);
 }
-function getInvalidValueFlagDetails(args) {
+function getInvalidValueFlagDetails(args, allowRestoreAssignment = true) {
     for (let index = 0; index < args.length; index += 1) {
         const token = args[index];
         if (!token.startsWith("-")) {
             continue;
         }
         const normalizedToken = token.split("=", 1)[0] ?? token;
-        if (!PREVALIDATED_VALUE_FLAGS.has(normalizedToken)) {
-            continue;
+        if (token.includes("=")
+            && (PREVALIDATED_VALUE_FLAGS.has(normalizedToken)
+                || GLOBAL_BOOLEAN_FLAGS_WITH_OPTIONAL_VALUES.has(normalizedToken)
+                || (!allowRestoreAssignment && normalizedToken === "--restore"))) {
+            return {
+                flag: normalizedToken,
+                index,
+                reason: "unsupported-assignment",
+            };
         }
-        if (token.includes("=")) {
-            const value = token.slice(token.indexOf("=") + 1).trim();
-            if (value.length === 0) {
-                return {
-                    flag: normalizedToken,
-                    index,
-                    reason: "missing-value",
-                };
-            }
+        if (!PREVALIDATED_VALUE_FLAGS.has(normalizedToken)) {
             continue;
         }
         const receivedToken = args[index + 1];
-        if (receivedToken === undefined) {
+        if (receivedToken === undefined || (normalizedToken === "--args" && receivedToken.length === 0)) {
             return {
                 flag: normalizedToken,
                 index,
@@ -626,7 +665,15 @@ function getInvalidValueFlagDetails(args) {
     }
     return undefined;
 }
-function formatInvalidValueFlagError(details) {
+function formatInvalidValueFlagError(details, batchStep = false) {
+    if (details.reason === "unsupported-assignment") {
+        if (batchStep) {
+            return details.flag === "--restore"
+                ? "Global `--restore=<key>` belongs before `batch` in top-level args, not inside a batch step."
+                : `Global \`${details.flag}=<value>\` is not supported inside a batch step. Move \`${details.flag}\` and its value before \`batch\` as separate top-level args.`;
+        }
+        return `agent-browser ${TARGET_AGENT_BROWSER_VERSION} does not support \`${details.flag}=<value>\`. Pass \`${details.flag}\` and its value as separate arguments.`;
+    }
     if (details.reason === "unexpected-flag" && details.receivedToken) {
         return `Flag \`${details.flag}\` requires a value, but received \`${details.receivedToken}\` instead. Pass a non-flag value immediately after \`${details.flag}\`.`;
     }
@@ -683,7 +730,7 @@ function parseComparableNavigationUrl(url) {
 export function getDefaultHeadlessCompatUserAgent(platform = process.platform) {
     return DEFAULT_HEADLESS_COMPAT_USER_AGENT_BY_PLATFORM[platform] ?? FALLBACK_HEADLESS_COMPAT_USER_AGENT;
 }
-export function canUseHeadlessCompatibilityUserAgent(args, env = process.env) {
+export function canUseHeadlessCompatibilityUserAgent(args, env = getAgentBrowserProcessEnvironment()) {
     if (hasFlagToken(args, "--user-agent") || hasFlagToken(args, "--args"))
         return false;
     if (hasFlagToken(args, "--cdp") || hasFlagToken(args, "--provider") || hasFlagToken(args, "-p"))
@@ -716,6 +763,14 @@ function getCompatibilityWorkaround(args, commandInfo) {
         reason: "OpenAI web properties currently challenge the default headless Chrome user agent; inject a normal Chrome user agent to preserve the default headless workflow without requiring headed mode or auto-connect.",
     };
 }
+function stripExplicitSessionArgs(args) {
+    const sessionTokenIndexes = new Set();
+    for (const occurrence of scanUpstreamGlobalFlagOccurrences(args, "--session")) {
+        sessionTokenIndexes.add(occurrence.index);
+        sessionTokenIndexes.add(occurrence.index + 1);
+    }
+    return args.filter((_token, index) => !sessionTokenIndexes.has(index));
+}
 function stripExplicitNamespaceArgs(args) {
     const namespaceTokenIndexes = new Set();
     for (const occurrence of scanUpstreamGlobalFlagOccurrences(args, "--namespace")) {
@@ -731,7 +786,6 @@ export function getStartupScopedFlags(args) {
 }
 export function buildExecutionPlan(args, options) {
     const invalidValueFlag = getInvalidValueFlagDetails(args);
-    const unsupportedIdentityAssignment = getUnsupportedLeadingIdentityAssignment(args);
     const explicitNamespacePresent = scanUpstreamGlobalFlagOccurrences(args, "--namespace").length > 0;
     const explicitNamespace = extractExplicitNamespace(args);
     const managedSessionNamespace = canonicalizeAgentBrowserNamespace(options.managedSessionNamespace);
@@ -741,7 +795,7 @@ export function buildExecutionPlan(args, options) {
     const commandInfo = argvDescriptor.commandInfo;
     const commandNeedsManagedSession = !plainTextInspection && needsManagedSession(argvDescriptor);
     const effectiveArgs = plainTextInspection ? [...args] : args.includes("--json") ? [] : ["--json"];
-    let namespace = explicitNamespace;
+    let namespace = explicitNamespacePresent ? explicitNamespace ?? "" : undefined;
     if (plainTextInspection) {
         return {
             commandInfo,
@@ -763,16 +817,6 @@ export function buildExecutionPlan(args, options) {
             validationError: formatInvalidValueFlagError(invalidValueFlag),
         };
     }
-    if (unsupportedIdentityAssignment) {
-        return {
-            commandInfo: {},
-            effectiveArgs,
-            plainTextInspection: false,
-            startupScopedFlags: [],
-            usedImplicitSession: false,
-            validationError: `${unsupportedIdentityAssignment}=... is not supported by agent-browser 0.33.2. Pass ${unsupportedIdentityAssignment} and its value as separate arguments.`,
-        };
-    }
     for (const flag of ["--session", "--namespace"]) {
         if (countExplicitGlobalFlags(args, flag) <= 1)
             continue;
@@ -786,8 +830,13 @@ export function buildExecutionPlan(args, options) {
         };
     }
     const explicitSessionName = extractExplicitSessionName(args);
-    if (explicitSessionName && !isWrapperManagedSessionName(explicitSessionName)) {
-        namespace = resolveAgentBrowserNamespace(args, process.env.AGENT_BROWSER_NAMESPACE);
+    if (explicitSessionName && !explicitNamespacePresent) {
+        const targetsCurrentManagedSession = options.managedSessionActive
+            && getAgentBrowserSessionIdentityKey(explicitSessionName, managedSessionNamespace)
+                === getAgentBrowserSessionIdentityKey(options.managedSessionName, managedSessionNamespace);
+        namespace = targetsCurrentManagedSession
+            ? managedSessionNamespace
+            : resolveAgentBrowserNamespace(args, getAgentBrowserProcessEnvironment().AGENT_BROWSER_NAMESPACE);
     }
     const shouldCreateFreshManagedSession = !explicitSessionName && options.sessionMode === "fresh" && commandInfo.command !== undefined && !isCloseCommand(commandInfo.command);
     let argsToAppend = args;
@@ -816,8 +865,8 @@ export function buildExecutionPlan(args, options) {
             ].join(" ");
         }
         else {
-            namespace = explicitNamespacePresent ? explicitNamespace : managedSessionNamespace;
-            if (namespace)
+            namespace = explicitNamespacePresent ? explicitNamespace ?? "" : managedSessionNamespace;
+            if (namespace !== undefined)
                 effectiveArgs.push("--namespace", namespace);
             effectiveArgs.push("--session", options.managedSessionName);
             if (explicitNamespacePresent)
@@ -828,7 +877,7 @@ export function buildExecutionPlan(args, options) {
         }
     }
     else if (shouldCreateFreshManagedSession && commandNeedsManagedSession) {
-        if (namespace)
+        if (namespace !== undefined)
             effectiveArgs.push("--namespace", namespace);
         effectiveArgs.push("--session", options.freshSessionName);
         if (explicitNamespacePresent)
@@ -836,14 +885,43 @@ export function buildExecutionPlan(args, options) {
         managedSessionName = options.freshSessionName;
         sessionName = options.freshSessionName;
     }
-    if (!compatibilityWorkaround
-        && canUseHeadlessCompatibilityUserAgent(args)
-        && options.managedSessionActive
+    const targetsActiveManagedSession = options.managedSessionActive
         && sessionName
-        && getAgentBrowserSessionIdentityKey(sessionName, namespace) === getAgentBrowserSessionIdentityKey(options.managedSessionName, options.managedSessionNamespace)) {
-        compatibilityWorkaround = options.managedSessionCompatibilityWorkaround;
+        && getAgentBrowserSessionIdentityKey(sessionName, namespace) === getAgentBrowserSessionIdentityKey(options.managedSessionName, options.managedSessionNamespace);
+    if (targetsActiveManagedSession && startupScopedFlags.length > 0 && !isCloseCommand(commandInfo.command) && !validationError) {
+        const recoveryArgs = explicitSessionName ? stripExplicitSessionArgs(args) : args;
+        recoveryHint = {
+            exampleArgs: recoveryArgs,
+            exampleParams: { args: recoveryArgs, sessionMode: "fresh" },
+            reason: `Launch-scoped flags (${LAUNCH_SCOPED_FLAG_LABEL}) need a fresh upstream launch once the extension-managed session is already active.`,
+            recommendedSessionMode: "fresh",
+        };
+        validationError = [
+            `The current extension-managed agent-browser session is already running, so launch-scoped flags ${startupScopedFlags.join(", ")} would replace or be ignored by upstream agent-browser.`,
+            explicitSessionName
+                ? "Remove the explicit `--session` and retry with `sessionMode: \"fresh\"` to force a fresh upstream launch."
+                : "Retry this call with `sessionMode: \"fresh\"` to force a fresh upstream launch.",
+        ].join(" ");
+    }
+    if (targetsActiveManagedSession && canUseHeadlessCompatibilityUserAgent(args)) {
+        if (requestedCompatibilityWorkaround && !options.managedSessionCompatibilityWorkaround && !validationError) {
+            compatibilityWorkaround = undefined;
+            const recoveryArgs = explicitSessionName ? stripExplicitSessionArgs(args) : args;
+            recoveryHint = {
+                exampleArgs: recoveryArgs,
+                exampleParams: { args: recoveryArgs, sessionMode: "fresh" },
+                reason: "The requested site compatibility user agent is launch-scoped and needs a fresh browser session.",
+                recommendedSessionMode: "fresh",
+            };
+            validationError = explicitSessionName
+                ? "The current extension-managed agent-browser session is already running without the user agent required by this site. Remove the explicit `--session` and retry with `sessionMode: \"fresh\"` so the compatibility user agent is applied at launch."
+                : "The current extension-managed agent-browser session is already running without the user agent required by this site. Retry this call with `sessionMode: \"fresh\"` so the compatibility user agent is applied at launch.";
+        }
+        else {
+            compatibilityWorkaround = requestedCompatibilityWorkaround ?? options.managedSessionCompatibilityWorkaround;
+        }
     }
-    if (compatibilityWorkaround) {
+    if (compatibilityWorkaround && !targetsActiveManagedSession) {
         effectiveArgs.push("--user-agent", getDefaultHeadlessCompatUserAgent());
     }
     effectiveArgs.push(...argsToAppend);