pi-agent-browser-native 0.2.77 → 0.5.0

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

@@ -1,23 +1,17 @@
-/**
- * Purpose: Build safe, deterministic agent-browser invocations and persisted session state for the pi-agent-browser extension.
- * Responsibilities: Validate raw tool arguments, derive extension-managed session names from the pi session identity, restore managed-session state from persisted tool details, redact sensitive invocation text, classify browser-oriented prompts, and build the effective CLI argument list passed to the upstream agent-browser binary.
- * Scope: Runtime-planning helpers only; no subprocess execution or filesystem access.
- * Usage: Imported by the extension entrypoint and unit tests before spawning the upstream CLI.
- * Invariants/Assumptions: The wrapper stays thin, preserves upstream command vocabulary, keeps plain-text inspection stateless,
- * and only injects wrapper-owned flags: `--json`, an extension-managed `--session` when appropriate, the narrow
- * site-specific headless compatibility `--user-agent` when that workaround applies.
- */
 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, 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_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";
@@ -37,6 +31,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;
@@ -320,7 +315,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;
@@ -342,7 +337,7 @@ function getUnsupportedLeadingIdentityAssignment(args) {
     }
     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) {
@@ -368,7 +363,7 @@ export function resolveManagedSessionState(options) {
         sessionName: managedSessionName,
     };
 }
-function isRestorableManagedSessionName(sessionName, fallbackSessionName) {
+export function isRestorableManagedSessionName(sessionName, fallbackSessionName) {
     return sessionName === fallbackSessionName || sessionName.startsWith(`${fallbackSessionName}-fresh-`);
 }
 function getManagedSessionRestoreRank(options) {
@@ -390,15 +385,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;
@@ -406,11 +404,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();
@@ -450,16 +449,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;
@@ -468,6 +474,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;
@@ -476,13 +490,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;
         }
@@ -499,9 +513,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);
             }
@@ -538,15 +554,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")
@@ -563,7 +588,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;
@@ -573,13 +598,19 @@ 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.";
 }
+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) {
     if (args.length === 0) {
         return "`args` must contain at least one agent-browser command token.";
@@ -592,7 +623,7 @@ 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);
+    return getBareMcpValidationError(args) ?? getSingleKeyCommandValidationError(args) ?? getUnsupportedInlineWaitDownloadError(args);
 }
 function getInvalidValueFlagDetails(args) {
     for (let index = 0; index < args.length; index += 1) {
@@ -616,7 +647,7 @@ function getInvalidValueFlagDetails(args) {
             continue;
         }
         const receivedToken = args[index + 1];
-        if (receivedToken === undefined) {
+        if (receivedToken === undefined || (normalizedToken === "--args" && receivedToken.length === 0)) {
             return {
                 flag: normalizedToken,
                 index,
@@ -692,16 +723,15 @@ 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"))
         return false;
     if (env.AGENT_BROWSER_USER_AGENT !== undefined || env.AGENT_BROWSER_ARGS !== undefined || env.AGENT_BROWSER_CDP !== undefined || env.AGENT_BROWSER_PROVIDER !== undefined)
         return false;
-    const envFlagEnabled = (value) => value !== undefined && !["", "0", "false", "no"].includes(value.toLowerCase());
-    if ((getBooleanFlagValue(args, "--headed") ?? envFlagEnabled(env.AGENT_BROWSER_HEADED))
-        || (getBooleanFlagValue(args, "--auto-connect") ?? envFlagEnabled(env.AGENT_BROWSER_AUTO_CONNECT)))
+    if ((getBooleanFlagValue(args, "--headed") ?? isUpstreamEnvFlagEnabled(env.AGENT_BROWSER_HEADED))
+        || (getBooleanFlagValue(args, "--auto-connect") ?? isUpstreamEnvFlagEnabled(env.AGENT_BROWSER_AUTO_CONNECT)))
         return false;
     const engine = scanUpstreamGlobalFlagOccurrences(args, "--engine").at(-1)?.value ?? env.AGENT_BROWSER_ENGINE;
     return !engine || engine === "chrome";
@@ -726,6 +756,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")) {
@@ -751,7 +789,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,
@@ -780,7 +818,7 @@ export function buildExecutionPlan(args, options) {
             plainTextInspection: false,
             startupScopedFlags: [],
             usedImplicitSession: false,
-            validationError: `${unsupportedIdentityAssignment}=... is not supported by agent-browser 0.33.2. Pass ${unsupportedIdentityAssignment} and its value as separate arguments.`,
+            validationError: `${unsupportedIdentityAssignment}=... is not supported by agent-browser ${TARGET_AGENT_BROWSER_VERSION}. Pass ${unsupportedIdentityAssignment} and its value as separate arguments.`,
         };
     }
     for (const flag of ["--session", "--namespace"]) {
@@ -797,7 +835,7 @@ export function buildExecutionPlan(args, options) {
     }
     const explicitSessionName = extractExplicitSessionName(args);
     if (explicitSessionName && !isWrapperManagedSessionName(explicitSessionName)) {
-        namespace = resolveAgentBrowserNamespace(args, process.env.AGENT_BROWSER_NAMESPACE);
+        namespace = resolveAgentBrowserNamespace(args, getAgentBrowserProcessEnvironment().AGENT_BROWSER_NAMESPACE);
     }
     const shouldCreateFreshManagedSession = !explicitSessionName && options.sessionMode === "fresh" && commandInfo.command !== undefined && !isCloseCommand(commandInfo.command);
     let argsToAppend = args;
@@ -826,8 +864,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)
@@ -838,7 +876,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)
@@ -846,14 +884,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);

package/dist/extensions/agent-browser/lib/session-page-state.js

@@ -1,12 +1,7 @@
-/**
- * Purpose: Own wrapper-known per-session browser page target, ref snapshot, invalidation, and pinning state.
- * Responsibilities: Restore state from persisted tool details, apply ordered tab/ref updates atomically, and expose order-free public state views to the extension entrypoint.
- * Scope: Session page state only; browser process execution, tab probing, and presentation policies stay in the extension entrypoint.
- * Usage: `index.ts` creates one store per Pi session lifecycle and records observations through update tokens.
- * Invariants/Assumptions: One tool-call update token must govern all page-state observations from that invocation; stale overlapping updates must not overwrite newer state.
- */
-import { getAgentBrowserSessionIdentityKey } from "./argv-grammar.js";
-import { isCloseCommand, isReadOnlyDiagnosticSessionTargetCommand, isUnverifiedPageTransitionCommand } from "./command-taxonomy.js";
+import { extractUpstreamCommandTokens } from "./argv-descriptor.js";
+import { getAgentBrowserSessionIdentityKey, isAgentBrowserSessionIdentityKeyInNamespace } from "./argv-grammar.js";
+import { batchHasSuccessfulCloseAll, getSuccessfulBatchCloseLifecycle } from "./batch-lifecycle.js";
+import { isCloseAllCommand, isCloseCommand, isReadOnlyDiagnosticSessionTargetCommand, isRecordPageTransitionCommand, isUnverifiedPageTransitionCommand } from "./command-taxonomy.js";
 import { isRecord } from "./parsing.js";
 import { getEditableRefEvidence } from "./results/editable-ref-evidence.js";
 import { enrichSnapshotRefEntries, getSnapshotRefEntries } from "./results/snapshot-refs.js";
@@ -100,6 +95,11 @@ export function extractSessionTabTargetFromBatchResults(data) {
         }
         const [name, subcommand] = extractBatchResultCommand(item);
         const result = item.result;
+        if (isCloseCommand(name)) {
+            currentTarget = undefined;
+            pendingTitle = undefined;
+            continue;
+        }
         if (name === "get" && subcommand === "title") {
             pendingTitle = extractStringResultField(result, "title");
             continue;
@@ -204,6 +204,12 @@ export function buildNoActivePageRefSnapshotInvalidation() {
         summary: "The latest snapshot for this session reported No active page. Old page-scoped refs are invalid until snapshot -i succeeds.",
     };
 }
+export function buildPageTransitionRefSnapshotInvalidation(summary) {
+    return {
+        reason: "page-transition",
+        summary: summary ?? "A recording command (record start, or record restart with a URL) replaced or navigated the active page and invalidated the prior snapshot. Run snapshot -i before using page-scoped refs.",
+    };
+}
 export function isNoActivePageSnapshotFailure(command, text) {
     return command === "snapshot" && /\bno active page\b/i.test(text ?? "");
 }
@@ -214,7 +220,16 @@ export function extractLatestRefSnapshotStateFromBatchResults(data) {
     for (const item of data) {
         if (!isRecord(item))
             continue;
-        const [name] = extractBatchResultCommand(item);
+        const commandTokens = extractBatchResultCommand(item);
+        const [name] = commandTokens;
+        if (item.success !== false && isCloseCommand(name)) {
+            latestState = undefined;
+            continue;
+        }
+        if (isRecordPageTransitionCommand(commandTokens)) {
+            latestState = { invalidation: buildPageTransitionRefSnapshotInvalidation() };
+            continue;
+        }
         if (name !== "snapshot")
             continue;
         if (item.success === false) {
@@ -232,9 +247,10 @@ export function extractLatestRefSnapshotStateFromBatchResults(data) {
 }
 function getRestoredRefSnapshotInvalidation(details, command) {
     const invalidation = isRecord(details.refSnapshotInvalidation) ? details.refSnapshotInvalidation : undefined;
-    if (invalidation && invalidation.reason === "no-active-page") {
+    if (invalidation?.reason === "no-active-page")
         return buildNoActivePageRefSnapshotInvalidation();
-    }
+    if (invalidation?.reason === "page-transition")
+        return buildPageTransitionRefSnapshotInvalidation(typeof invalidation.summary === "string" ? invalidation.summary : undefined);
     const errorText = typeof details.error === "string"
         ? details.error
         : typeof details.summary === "string"
@@ -323,14 +339,27 @@ export class SessionPageState {
             const sessionName = typeof details.sessionName === "string" ? details.sessionName : undefined;
             const namespace = typeof details.namespace === "string" ? details.namespace : undefined;
             const sessionKey = getSessionPageStateKey(sessionName, namespace);
+            const args = Array.isArray(details.args) && details.args.every((arg) => typeof arg === "string") ? details.args : [];
+            const commandTokens = extractUpstreamCommandTokens(args);
+            const command = typeof details.command === "string" ? details.command : commandTokens[0];
+            const subcommand = typeof details.subcommand === "string" ? details.subcommand : commandTokens[1];
+            const batchCloseLifecycle = getSuccessfulBatchCloseLifecycle(details.batchSteps);
+            const closeAllApplied = details.closeAllApplied === true
+                || (message.isError !== true && isCloseAllCommand(commandTokens))
+                || batchHasSuccessfulCloseAll(details.batchSteps);
+            if (closeAllApplied) {
+                restoredOrder += 1;
+                state.clearNamespace(namespace);
+                if (isCloseCommand(command) || batchCloseLifecycle?.endsClosed === true)
+                    continue;
+            }
             if (!sessionKey)
                 continue;
-            const command = typeof details.command === "string" ? details.command : undefined;
-            const subcommand = typeof details.subcommand === "string" ? details.subcommand : undefined;
-            if (isCloseCommand(command) && message.isError !== true) {
+            if (!closeAllApplied && ((isCloseCommand(command) && message.isError !== true) || batchCloseLifecycle)) {
                 restoredOrder += 1;
                 state.clearSession(sessionKey);
-                continue;
+                if (isCloseCommand(command) || batchCloseLifecycle?.endsClosed === true)
+                    continue;
             }
             const tabTarget = getRestoredSessionTabTarget(details, command, subcommand);
             const tabTargetUnknown = details.sessionTabTargetUnknown === true;
@@ -340,8 +369,11 @@ export class SessionPageState {
                 continue;
             restoredOrder += 1;
             if (tabTargetUnknown) {
-                state.refSnapshotInvalidations.delete(sessionKey);
                 state.refSnapshots.delete(sessionKey);
+                if (refSnapshotInvalidation)
+                    state.refSnapshotInvalidations.set(sessionKey, { ...refSnapshotInvalidation, order: restoredOrder });
+                else
+                    state.refSnapshotInvalidations.delete(sessionKey);
                 state.tabTargets.delete(sessionKey);
                 state.tabTargetUnknownOrders.set(sessionKey, restoredOrder);
                 continue;
@@ -438,6 +470,19 @@ export class SessionPageState {
         this.tabTargetUnknownOrders.delete(sessionName);
         this.tabTargets.delete(sessionName);
     }
+    clearNamespace(namespace) {
+        const sessionKeys = new Set([
+            ...this.refSnapshotInvalidations.keys(),
+            ...this.refSnapshots.keys(),
+            ...this.tabPinningReasons.keys(),
+            ...this.tabTargetUnknownOrders.keys(),
+            ...this.tabTargets.keys(),
+        ]);
+        for (const sessionKey of sessionKeys) {
+            if (isAgentBrowserSessionIdentityKeyInNamespace(sessionKey, namespace))
+                this.clearSession(sessionKey);
+        }
+    }
     markPinning(sessionName, reason) {
         this.tabPinningReasons.set(sessionName, reason);
     }

package/dist/extensions/agent-browser/lib/string-enum-schema.js

@@ -1,8 +1,3 @@
-/**
- * Purpose: Build compact JSON-schema string enums without importing pi runtime helpers.
- * Responsibilities: Mirror pi-ai StringEnum's `{ type: "string", enum: [...] }` shape while keeping extension startup imports light.
- * Scope: Schema construction only.
- */
 import { JsonSchema } from "./json-schema.js";
 export function StringEnum(values, options) {
     return JsonSchema.Unsafe({

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

@@ -1,10 +1,3 @@
-/**
- * Purpose: Create private temporary and persisted spill files for the pi-agent-browser extension without leaking artifacts broadly on disk.
- * Responsibilities: Maintain a process-private temp root, stamp explicit ownership/protected-child markers, enforce an aggregate temp-artifact disk budget, create securely permissioned temp files, create session-scoped persisted spill files for resumable sessions, prune explicitly owned stale temp roots from prior runs without deleting protected children, and best-effort clean all owned roots on process exit.
- * Scope: Artifact lifecycle helpers only; callers decide what data to write and when to delete or retain long-lived references.
- * Usage: Imported by result/process helpers when they need secure spill files instead of world-readable shared tmp paths.
- * Invariants/Assumptions: Temp artifacts live under the OS temp directory, each active run uses a dedicated 0700 directory, files are created with exclusive 0600 permissions, session-scoped persisted artifacts stay under the pi session directory, and stale pruning only touches roots with an explicit pi-agent-browser ownership marker.
- */
 import { randomBytes } from "node:crypto";
 import { existsSync, readdirSync, rmSync } from "node:fs";
 import { chmod, mkdir, mkdtemp, open, readFile, readdir, rm, stat, writeFile } from "node:fs/promises";

package/dist/extensions/agent-browser/lib/upstream-version.js

@@ -0,0 +1,14 @@
+import { TARGET_AGENT_BROWSER_VERSION, TARGET_AGENT_BROWSER_VERSION_LABEL } from "../../../scripts/agent-browser-target.mjs";
+export { TARGET_AGENT_BROWSER_VERSION, TARGET_AGENT_BROWSER_VERSION_LABEL };
+export function parseAgentBrowserVersionOutput(stdout) {
+    const match = stdout.trim().match(/^agent-browser\s+(\S+)$/);
+    return match?.[1];
+}
+export function getAgentBrowserVersionValidationError(stdout) {
+    const observed = parseAgentBrowserVersionOutput(stdout);
+    if (observed === TARGET_AGENT_BROWSER_VERSION)
+        return undefined;
+    return observed
+        ? `Installed agent-browser ${observed} does not match this extension's exact ${TARGET_AGENT_BROWSER_VERSION} capability baseline. Install ${TARGET_AGENT_BROWSER_VERSION_LABEL}, run pi-agent-browser-doctor, then reload Pi.`
+        : `agent-browser --version returned an unrecognized value; expected exactly ${JSON.stringify(TARGET_AGENT_BROWSER_VERSION_LABEL)}. Run pi-agent-browser-doctor and install the exact supported upstream version.`;
+}

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

@@ -1,8 +1,3 @@
-/**
- * Purpose: Provide the optional provider-backed `agent_browser_web_search` companion tool.
- * Responsibilities: Define strict search input schema, resolve configured Brave/Exa credentials lazily, call the selected search API with cancellation/timeout, normalize compact results, and keep secrets out of content/details.
- * Scope: Live web search only; browser automation remains in the `agent_browser` tool.
- */
 import { JsonSchema } from "./json-schema.js";
 import { WEB_SEARCH_PROMPT_GUIDELINE } from "./playbook.js";
 import { StringEnum as localStringEnum } from "./string-enum-schema.js";