pi-agent-browser-native 0.3.0 → 0.6.5

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

@@ -4,32 +4,43 @@ import { lstat, mkdir, readdir } from "node:fs/promises";
 import { dirname, isAbsolute, join } from "node:path";
 import { env as processEnv, platform as processPlatform } from "node:process";
 import { parseArgvDescriptor } from "./argv-descriptor.js";
-import { needsManagedSession } from "./command-policy.js";
 import { isKnownCommandToken } from "./command-taxonomy.js";
-import { getFlagName, GLOBAL_BOOLEAN_FLAGS_WITH_OPTIONAL_VALUES, GLOBAL_VALUE_FLAGS, optionalGlobalValueFlagConsumesNext, } from "./argv-grammar.js";
-import { canonicalizeOwnedManagedSessionCloseArgs, commitManagedSessionRestoreSuppression, getManagedSessionRestoreConfigEnv, getManagedSessionRestoreEnv, getManagedSessionRestoreProtectedEnv, getOwnedManagedSessionCompatibilityEnv, getOwnedManagedSessionNamespaceEnv, isOwnedManagedSessionTarget, shouldOmitOwnedManagedSessionRestoreEnv, validateManagedSessionRestoreContextForSpawn, } from "./managed-session-restore.js";
-import { getManagedSessionStateAccessValidationError, getManagedSessionTargetAccessValidationError, } from "./managed-session-state-policy.js";
-import { getImplicitSessionIdleTimeoutMs, isPlainTextInspectionArgs } from "./runtime.js";
+import { extractExplicitSessionName, getFlagName, GLOBAL_BOOLEAN_FLAGS_WITH_OPTIONAL_VALUES, GLOBAL_VALUE_FLAGS, optionalGlobalValueFlagConsumesNext, resolveAgentBrowserNamespace, } from "./argv-grammar.js";
+import { commitManagedSessionRestoreSuppression, getManagedSessionRestoreEnv, getManagedSessionRestoreProtectedEnv, getOwnedManagedSessionCompatibilityEnv, getOwnedManagedSessionNamespaceEnv, isOwnedManagedSessionTarget, validateManagedSessionRestoreContextForSpawn, } from "./managed-session-restore.js";
+import { getPageTargetValidationError, } from "./page-target-validation.js";
+import { getImplicitSessionIdleTimeoutMs } from "./runtime.js";
+import { getAgentBrowserProcessEnvironment } from "./process-environment.js";
 import { openSecureTempFile, writeSecureTempChunk } from "./temp.js";
 const MAX_BUFFERED_STDOUT_BYTES = 512 * 1_024;
 const MAX_BUFFERED_STDERR_CHARS = 32_000;
 const MAX_BUFFERED_STDOUT_TAIL_CHARS = 32_000;
 const PROCESS_STDOUT_SPILL_FILE_PREFIX = "process-stdout";
 const AGENT_BROWSER_SOCKET_DIR_ENV = "AGENT_BROWSER_SOCKET_DIR";
-const AGENT_BROWSER_ARGS_ENV = "AGENT_BROWSER_ARGS";
 const AGENT_BROWSER_DEFAULT_TIMEOUT_ENV = "AGENT_BROWSER_DEFAULT_TIMEOUT";
 const AGENT_BROWSER_IDLE_TIMEOUT_ENV = "AGENT_BROWSER_IDLE_TIMEOUT_MS";
 const PI_AGENT_BROWSER_PROCESS_TIMEOUT_ENV = "PI_AGENT_BROWSER_PROCESS_TIMEOUT_MS";
+const PI_AGENT_BROWSER_SOCKET_DIR_ENV = "PI_AGENT_BROWSER_SOCKET_DIR";
 const DEFAULT_AGENT_BROWSER_SOCKET_DIR_PREFIX = "/tmp/piab";
+const TERMUX_PACKAGE_NAME_PATTERN = /^[A-Za-z0-9_]+(?:\.[A-Za-z0-9_]+)+$/;
 export const SAFE_AGENT_BROWSER_OPERATION_TIMEOUT_MS = 25_000;
 const DEFAULT_AGENT_BROWSER_PROCESS_TIMEOUT_MS = 35_000;
 /** Grace period after `exit` before resolving when `close` is delayed by inherited stdio handles. */
 const EXIT_STDIO_GRACE_MS = 100;
 const WINDOWS_AGENT_BROWSER_MISSING_MARKER = "PI_AGENT_BROWSER_COMMAND_NOT_FOUND:agent-browser.cmd";
 const attachedBrowserSessionContext = new AsyncLocalStorage();
+const WINDOWS_COMMANDS_WITH_ADJACENT_SUBCOMMAND = new Set([
+    "auth", "clipboard", "cookies", "dashboard", "device", "dialog", "diff", "find", "get", "is", "keyboard",
+    "mouse", "network", "plugin", "profiler", "react", "record", "session", "set", "skills", "state", "storage",
+    "stream", "tab", "trace", "webmcp", "window",
+]);
 export function withAttachedBrowserSessionContext(preserve, run) {
     return attachedBrowserSessionContext.run(preserve || attachedBrowserSessionContext.getStore() === true, run);
 }
+export function getWindowsExplicitDefaultNamespaceEnv(args, parentNamespace, platform = processPlatform) {
+    return platform === "win32" && resolveAgentBrowserNamespace(args, parentNamespace) === ""
+        ? { AGENT_BROWSER_NAMESPACE: "" }
+        : {};
+}
 function appendTail(text, addition, maxChars) {
     const combined = text + addition;
     return combined.length <= maxChars ? combined : combined.slice(combined.length - maxChars);
@@ -43,7 +54,12 @@ export function reorderWindowsLeadingGlobalArgs(args) {
     for (let index = 0; index < args.length; index += 1) {
         const token = args[index];
         if (isKnownCommandToken(token)) {
-            return index === 0 ? args : [token, ...leadingGlobals, ...args.slice(index + 1)];
+            if (index === 0)
+                return args;
+            const firstPositional = args[index + 1];
+            return WINDOWS_COMMANDS_WITH_ADJACENT_SUBCOMMAND.has(token) && firstPositional && !firstPositional.startsWith("-")
+                ? [token, firstPositional, ...leadingGlobals, ...args.slice(index + 2)]
+                : [token, ...leadingGlobals, ...args.slice(index + 1)];
         }
         if (!token.startsWith("-"))
             return args;
@@ -77,6 +93,13 @@ export function reorderWindowsLeadingGlobalArgs(args) {
             const value = args[index + 1];
             if (value === undefined)
                 return args;
+            // PowerShell -> .cmd drops empty argv values. Planning rejects empty
+            // caller --args; keep this defensive skip so an unexpected empty value
+            // cannot turn the next flag into its accidental value on native Windows.
+            if (value === "" && (flag === "--args" || flag === "--namespace")) {
+                index += 1;
+                continue;
+            }
             leadingGlobals.push(token, value);
             index += 1;
             continue;
@@ -85,27 +108,10 @@ export function reorderWindowsLeadingGlobalArgs(args) {
     }
     return args;
 }
-export function pinAgentBrowserFileAccessDisabled(args, wrapperCompatibilityUserAgent, preserveAttachedBrowserSession = false) {
-    const filtered = [];
-    for (let index = 0; index < args.length; index += 1) {
-        const token = args[index];
-        if (token.startsWith("--allow-file-access="))
-            continue;
-        if (token === "--allow-file-access") {
-            if (["false", "true"].includes(args[index + 1] ?? ""))
-                index += 1;
-            continue;
-        }
-        filtered.push(token);
-    }
-    // These are launch-only controls. Sending them on an attached-session follow-up makes upstream replace the CDP connection with a local browser.
-    if (preserveAttachedBrowserSession)
-        return filtered;
-    // Upstream's flag overrides only the active CDP target; the Chrome arg covers new tabs. Its --args parser splits commas/newlines.
-    const browserArgs = wrapperCompatibilityUserAgent
-        ? `--user-agent=${wrapperCompatibilityUserAgent.replaceAll(/[\r\n,]/g, "")}`
-        : "";
-    return ["--args", browserArgs, "--allow-file-access", "false", ...filtered];
+export function prepareAgentBrowserSpawnArgs(args, wrapperCompatibilityUserAgent, preserveAttachedBrowserSession = false) {
+    if (preserveAttachedBrowserSession || !wrapperCompatibilityUserAgent)
+        return args;
+    return ["--args", `--user-agent=${wrapperCompatibilityUserAgent.replaceAll(/[\r\n,]/g, "")}`, ...args];
 }
 export function buildAgentBrowserSpawnCommand(args, platform = processPlatform) {
     if (platform !== "win32") {
@@ -216,33 +222,43 @@ function clampUpstreamDefaultTimeout(childEnv) {
 export function getAgentBrowserProcessTimeoutMs(env = processEnv) {
     return parsePositiveIntegerEnv(env[PI_AGENT_BROWSER_PROCESS_TIMEOUT_ENV]) ?? DEFAULT_AGENT_BROWSER_PROCESS_TIMEOUT_MS;
 }
-export function getAgentBrowserSocketDir(platform = processPlatform, uid = typeof process.getuid === "function" ? process.getuid() : undefined) {
+export function getAgentBrowserSocketDir(platform = processPlatform, uid = typeof process.getuid === "function" ? process.getuid() : undefined, termuxPackageName = processEnv.TERMUX_APP__PACKAGE_NAME) {
     if (platform === "win32") {
         return undefined;
     }
-    const prefix = platform === "darwin" ? "/private/tmp/piab" : DEFAULT_AGENT_BROWSER_SOCKET_DIR_PREFIX;
-    return `${prefix}${typeof uid === "number" ? `-${uid}` : ""}`;
+    const termuxAppRoot = platform === "android" && termuxPackageName && TERMUX_PACKAGE_NAME_PATTERN.test(termuxPackageName);
+    const prefix = platform === "darwin"
+        ? "/private/tmp/piab"
+        : termuxAppRoot
+            ? `/data/data/${termuxPackageName}/piab`
+            : DEFAULT_AGENT_BROWSER_SOCKET_DIR_PREFIX;
+    return `${prefix}${!termuxAppRoot && typeof uid === "number" ? `-${uid}` : ""}`;
+}
+export function isTrustedAndroidAppDataRoot(path, metadata, uid, platform = processPlatform) {
+    if (platform !== "android" || metadata.uid !== uid || metadata.isSymbolicLink() || !metadata.isDirectory() || (metadata.mode & 0o777) !== 0o700)
+        return false;
+    const parent = dirname(path);
+    return parent === "/data/data" || /^\/data\/user\/\d+$/.test(parent);
+}
+export function isTrustedSocketDirAncestor(metadata, uid, platform = processPlatform) {
+    if (metadata.isSymbolicLink())
+        return metadata.uid === 0;
+    if (!metadata.isDirectory())
+        return false;
+    const mode = metadata.mode & 0o7777;
+    if (platform === "android" && uid !== 0 && metadata.uid === uid && metadata.gid === uid)
+        return (mode & 0o002) === 0;
+    if (metadata.uid === uid && uid !== 0)
+        return (mode & 0o022) === 0;
+    return metadata.uid === 0 && ((mode & 0o022) === 0 || (mode & 0o1000) !== 0);
 }
 async function hasTrustedSocketDirAncestry(socketDir, uid) {
     for (let current = dirname(socketDir);;) {
         const metadata = await lstat(current);
-        if (metadata.isSymbolicLink()) {
-            if (metadata.uid !== 0)
-                return false;
-        }
-        else if (!metadata.isDirectory()) {
+        if (isTrustedAndroidAppDataRoot(current, metadata, uid))
+            return true;
+        if (!isTrustedSocketDirAncestor(metadata, uid))
             return false;
-        }
-        if (!metadata.isSymbolicLink()) {
-            const mode = metadata.mode & 0o7777;
-            if (metadata.uid === uid) {
-                if ((mode & 0o022) !== 0)
-                    return false;
-            }
-            else if (metadata.uid !== 0 || ((mode & 0o022) !== 0 && (mode & 0o1000) === 0)) {
-                return false;
-            }
-        }
         const parent = dirname(current);
         if (parent === current)
             return true;
@@ -273,28 +289,64 @@ async function socketDirEntriesAreOwned(socketDir, uid, visited = { count: 0 })
     }
     return true;
 }
-export async function ensureAgentBrowserSocketDir(socketDir, uid = typeof process.getuid === "function" ? process.getuid() : undefined) {
-    if (!isAbsolute(socketDir) || typeof uid !== "number")
-        return false;
+export async function getAgentBrowserSocketDirValidationError(socketDir, uid = typeof process.getuid === "function" ? process.getuid() : undefined) {
+    if (!isAbsolute(socketDir))
+        return "the path is not absolute";
+    if (typeof uid !== "number")
+        return "POSIX ownership metadata is unavailable";
     try {
         if (!await hasTrustedSocketDirAncestry(socketDir, uid))
-            return false;
+            return "an ancestor is writable, foreign-owned, a non-directory, or an untrusted symlink";
         try {
             await mkdir(socketDir, { mode: 0o700 });
         }
         catch (error) {
             if (error.code !== "EEXIST")
-                return false;
+                return `the directory could not be created (${error.code ?? "unknown error"})`;
         }
         const metadata = await lstat(socketDir);
-        if (!metadata.isDirectory() || metadata.isSymbolicLink() || metadata.uid !== uid || (metadata.mode & 0o777) !== 0o700)
-            return false;
-        return await hasTrustedSocketDirAncestry(socketDir, uid) && await socketDirEntriesAreOwned(socketDir, uid);
+        if (!metadata.isDirectory())
+            return "the path is not a directory";
+        if (metadata.isSymbolicLink())
+            return "the directory is a symlink";
+        if (metadata.uid !== uid)
+            return `the directory is owned by uid ${metadata.uid}, not uid ${uid}`;
+        if ((metadata.mode & 0o777) !== 0o700)
+            return `the directory mode is ${(metadata.mode & 0o777).toString(8)}, not 700`;
+        if (!await hasTrustedSocketDirAncestry(socketDir, uid))
+            return "an ancestor became untrusted during validation";
+        if (!await socketDirEntriesAreOwned(socketDir, uid))
+            return "the directory contains a foreign-owned, symlink, special, or excessively deep entry";
+        return undefined;
     }
-    catch {
-        return false;
+    catch (error) {
+        return `the directory could not be inspected (${error.code ?? "unknown error"})`;
     }
 }
+export async function ensureAgentBrowserSocketDir(socketDir, uid = typeof process.getuid === "function" ? process.getuid() : undefined) {
+    return await getAgentBrowserSocketDirValidationError(socketDir, uid) === undefined;
+}
+export function getAgentBrowserSocketPathValidationError(options) {
+    if ((options.platform ?? processPlatform) === "win32")
+        return undefined;
+    const descriptor = parseArgvDescriptor(options.args);
+    const { command } = descriptor.commandInfo;
+    // Preflight commands that can start or navigate a browser. Follow-up reads and
+    // cleanup may target a daemon created by an earlier wrapper version, so let
+    // upstream inspect those identities instead of rejecting them from path math.
+    if (!command || !["batch", "connect", "goto", "navigate", "open", "visit"].includes(command))
+        return undefined;
+    const sessionName = extractExplicitSessionName(options.args);
+    if (!sessionName)
+        return undefined;
+    const namespace = resolveAgentBrowserNamespace(options.args, options.env?.AGENT_BROWSER_NAMESPACE);
+    const socketRoot = namespace ? join(options.socketDir, "namespaces", namespace, "run") : options.socketDir;
+    const socketPath = join(socketRoot, `${sessionName}.sock`);
+    const pathBytes = Buffer.byteLength(socketPath);
+    if (pathBytes <= 103)
+        return undefined;
+    return `Agent-browser Unix socket path would be ${pathBytes} bytes (max 103) for session ${JSON.stringify(sessionName)} under ${JSON.stringify(options.socketDir)}. Set PI_AGENT_BROWSER_SOCKET_DIR to a shorter absolute private directory such as /tmp/piab-<uid> with mode 0700; retrying sessionMode \"fresh\" cannot shorten this configured root.`;
+}
 export function buildAgentBrowserProcessEnv(baseEnv = processEnv, overrides = undefined) {
     const childEnv = {};
     for (const [name, value] of Object.entries(baseEnv)) {
@@ -312,51 +364,38 @@ export function buildAgentBrowserProcessEnv(baseEnv = processEnv, overrides = un
     clampUpstreamDefaultTimeout(childEnv);
     return childEnv;
 }
-function getManagedPreSpawnPolicyError(options, effectiveEnv, allowManagedSessionTarget = false, currentPageUrl, pageUrlUnknown = false, trustedFirstBatchTabSelection = false, trustedPinnedEmptyConfig = false) {
-    const policyEnv = effectiveEnv ?? { ...(options.parentEnv ?? processEnv), ...options.env };
-    const managedSessionTargetError = getManagedSessionTargetAccessValidationError(options.args, allowManagedSessionTarget || options.ownedManagedSession === true || isOwnedManagedSessionTarget(options.args), policyEnv);
-    if (managedSessionTargetError)
-        return managedSessionTargetError;
+function getManagedPreSpawnPolicyError(options, currentPageUrl, pageUrlUnknown = false, trustedFirstBatchTabSelection = false) {
     if (!validateManagedSessionRestoreContextForSpawn(options)) {
         return "Managed session restore policy, storage, or checkout identity changed after planning; refusing to start agent-browser.";
     }
-    return getManagedSessionStateAccessValidationError({
+    return getPageTargetValidationError({
         args: options.args,
         currentPageUrl,
-        cwd: options.cwd,
-        env: effectiveEnv ?? options.env,
         pageUrlUnknown,
-        parentEnv: effectiveEnv ? {} : options.parentEnv ?? processEnv,
         stdin: options.stdin,
         trustedFirstBatchTabSelection,
-        trustedPinnedEmptyConfig,
     });
 }
 export async function runAgentBrowserProcess(options) {
-    const { allowManagedSessionTarget, cwd, env, managedSessionRestoreState, managedStateCurrentPageUrl, managedStatePageUrlUnknown, signal, stdin, trustedFirstBatchTabSelection } = options;
+    const { cwd, env, managedSessionRestoreState, managedStateCurrentPageUrl, managedStatePageUrlUnknown, signal, stdin, trustedFirstBatchTabSelection } = options;
     const preserveAttachedBrowserSession = options.preserveAttachedBrowserSession === true || attachedBrowserSessionContext.getStore() === true;
     const ownedManagedSession = options.ownedManagedSession === true || isOwnedManagedSessionTarget(options.args);
-    const args = canonicalizeOwnedManagedSessionCloseArgs({
-        args: options.args,
-        cwd,
-        env,
-        ownedManagedSession,
-        restoreState: managedSessionRestoreState,
-        stdin,
-    });
+    const args = options.args;
     const timeoutMs = options.timeoutMs ?? getAgentBrowserProcessTimeoutMs();
     if (signal?.aborted) {
         return { aborted: true, agentBrowserStarted: false, exitCode: 1, stderr: "", stdout: "", timedOut: false };
     }
+    const parentEnv = getAgentBrowserProcessEnvironment();
     const managedSessionRestoreOptions = {
         args,
         cwd,
         env,
         ownedManagedSession,
+        parentEnv,
         restoreState: managedSessionRestoreState,
         stdin,
     };
-    const planningPolicyError = getManagedPreSpawnPolicyError(managedSessionRestoreOptions, undefined, allowManagedSessionTarget, managedStateCurrentPageUrl, managedStatePageUrlUnknown, trustedFirstBatchTabSelection);
+    const planningPolicyError = getManagedPreSpawnPolicyError(managedSessionRestoreOptions, managedStateCurrentPageUrl, managedStatePageUrlUnknown, trustedFirstBatchTabSelection);
     if (planningPolicyError) {
         return {
             aborted: false,
@@ -369,48 +408,33 @@ export async function runAgentBrowserProcess(options) {
         };
     }
     const managedSessionRestoreEnv = getManagedSessionRestoreEnv(managedSessionRestoreOptions);
-    const ownedManagedSessionClose = shouldOmitOwnedManagedSessionRestoreEnv(managedSessionRestoreOptions);
-    const browserConfigPinRequired = !isPlainTextInspectionArgs(args) && needsManagedSession(parseArgvDescriptor(args));
-    const managedSessionRestoreConfigEnv = await getManagedSessionRestoreConfigEnv(managedSessionRestoreEnv, ownedManagedSessionClose || browserConfigPinRequired);
-    if (managedSessionRestoreConfigEnv === undefined) {
-        return {
-            aborted: false,
-            agentBrowserStarted: false,
-            exitCode: 1,
-            spawnError: new Error("Browser-backed agent-browser commands require a protected empty config, but secure temp storage was unavailable."),
-            stderr: "",
-            stdout: "",
-            timedOut: false,
-        };
-    }
     const ownedManagedSessionCompatibilityEnv = getOwnedManagedSessionCompatibilityEnv(managedSessionRestoreOptions);
     const processOverrides = {
         [AGENT_BROWSER_IDLE_TIMEOUT_ENV]: String(getImplicitSessionIdleTimeoutMs()),
         ...managedSessionRestoreEnv,
         ...env,
-        ...managedSessionRestoreConfigEnv,
         ...getManagedSessionRestoreProtectedEnv(managedSessionRestoreOptions, managedSessionRestoreEnv),
         ...getOwnedManagedSessionNamespaceEnv(managedSessionRestoreOptions),
+        ...getWindowsExplicitDefaultNamespaceEnv(args, parentEnv.AGENT_BROWSER_NAMESPACE),
         ...ownedManagedSessionCompatibilityEnv,
-        AGENT_BROWSER_ALLOW_FILE_ACCESS: undefined,
-        [AGENT_BROWSER_ARGS_ENV]: undefined,
     };
     const explicitSocketDir = processOverrides[AGENT_BROWSER_SOCKET_DIR_ENV];
     let effectiveEnv = explicitSocketDir === undefined ? { ...processOverrides, [AGENT_BROWSER_SOCKET_DIR_ENV]: undefined } : processOverrides;
-    if (ownedManagedSessionClose)
-        effectiveEnv = { ...effectiveEnv, AGENT_BROWSER_RESTORE: undefined };
-    const requestedSocketDir = explicitSocketDir ?? getAgentBrowserSocketDir();
+    const requestedSocketDir = explicitSocketDir ?? parentEnv[PI_AGENT_BROWSER_SOCKET_DIR_ENV] ?? getAgentBrowserSocketDir();
     if (requestedSocketDir !== undefined) {
-        const socketDirIsSecure = requestedSocketDir.length > 0 && await ensureAgentBrowserSocketDir(requestedSocketDir);
+        const socketDirError = requestedSocketDir.length > 0
+            ? await getAgentBrowserSocketDirValidationError(requestedSocketDir)
+            : "the configured path is empty";
         if (signal?.aborted) {
             return { aborted: true, agentBrowserStarted: false, exitCode: 1, stderr: "", stdout: "", timedOut: false };
         }
-        if (!socketDirIsSecure) {
+        const socketPathError = socketDirError ? undefined : getAgentBrowserSocketPathValidationError({ args, env: effectiveEnv, socketDir: requestedSocketDir });
+        if (socketDirError || socketPathError) {
             return {
                 aborted: false,
                 agentBrowserStarted: false,
                 exitCode: 1,
-                spawnError: new Error("Agent-browser socket storage must be an absolute, non-symlink directory owned by the current user with mode 0700."),
+                spawnError: new Error(socketPathError ?? `Agent-browser socket storage ${JSON.stringify(requestedSocketDir)} is unusable: ${socketDirError}. Use an absolute directory owned by the current uid with mode 0700 and remove foreign, symlink, or special entries.`),
                 stderr: "",
                 stdout: "",
                 timedOut: false,
@@ -432,6 +456,7 @@ export async function runAgentBrowserProcess(options) {
         let stdoutTail = "";
         let stdoutSpillHandle;
         let stdoutSpillPath;
+        let stdoutSpillPending = false;
         let pendingStdoutWrite = Promise.resolve();
         let stdoutSpillError;
         let killTimer;
@@ -443,11 +468,12 @@ export async function runAgentBrowserProcess(options) {
             stdoutTail = appendTail(stdoutTail, buffer.toString("utf8"), MAX_BUFFERED_STDOUT_TAIL_CHARS);
             if (stdoutSpillError)
                 return;
-            if (!stdoutSpillPath && stdoutBufferedBytes + buffer.length <= MAX_BUFFERED_STDOUT_BYTES) {
+            if (!stdoutSpillPending && !stdoutSpillPath && stdoutBufferedBytes + buffer.length <= MAX_BUFFERED_STDOUT_BYTES) {
                 stdoutBuffers.push(buffer);
                 stdoutBufferedBytes += buffer.length;
                 return;
             }
+            stdoutSpillPending = true;
             pendingStdoutWrite = pendingStdoutWrite
                 .then(async () => {
                 if (stdoutSpillError)
@@ -521,13 +547,13 @@ export async function runAgentBrowserProcess(options) {
                 });
             });
         };
-        const childEnv = buildAgentBrowserProcessEnv(processEnv, effectiveEnv);
-        const spawnPolicyError = getManagedPreSpawnPolicyError(managedSessionRestoreOptions, childEnv, allowManagedSessionTarget, managedStateCurrentPageUrl, managedStatePageUrlUnknown, trustedFirstBatchTabSelection, managedSessionRestoreConfigEnv.AGENT_BROWSER_CONFIG !== undefined);
+        const childEnv = buildAgentBrowserProcessEnv(parentEnv, effectiveEnv);
+        const spawnPolicyError = getManagedPreSpawnPolicyError(managedSessionRestoreOptions, managedStateCurrentPageUrl, managedStatePageUrlUnknown, trustedFirstBatchTabSelection);
         if (spawnPolicyError) {
             resolve({ aborted: false, agentBrowserStarted: false, exitCode: 1, spawnError: new Error(spawnPolicyError), stderr: "", stdout: "", timedOut: false });
             return;
         }
-        const spawnCommand = buildAgentBrowserSpawnCommand(pinAgentBrowserFileAccessDisabled(args, ownedManagedSessionCompatibilityEnv.AGENT_BROWSER_USER_AGENT, preserveAttachedBrowserSession));
+        const spawnCommand = buildAgentBrowserSpawnCommand(prepareAgentBrowserSpawnArgs(args, ownedManagedSessionCompatibilityEnv.AGENT_BROWSER_USER_AGENT, preserveAttachedBrowserSession));
         const child = spawn(spawnCommand.command, spawnCommand.args, {
             cwd,
             env: childEnv,

package/dist/extensions/agent-browser/lib/recording-reservations.js

@@ -0,0 +1,116 @@
+import { getAgentBrowserSessionIdentityKey } from "./argv-grammar.js";
+import { isRecord } from "./parsing.js";
+import { isPendingRecordingArtifact } from "./results/artifact-manifest.js";
+export const RECORDING_RESERVATION_ENTRY_TYPE = "agent-browser-recording-reservation";
+function getReservationKey(reservation) {
+    return getAgentBrowserSessionIdentityKey(reservation.sessionName, reservation.namespace);
+}
+function getArtifactReservation(artifact) {
+    if (!artifact.session || artifact.command !== "record" || artifact.kind !== "video")
+        return undefined;
+    return {
+        absolutePath: artifact.absolutePath,
+        cwd: artifact.cwd ?? process.cwd(),
+        namespace: artifact.namespace,
+        path: artifact.path,
+        sessionName: artifact.session,
+    };
+}
+export function applyRecordingArtifactsToReservations(reservations, artifacts) {
+    const pendingBySession = new Map();
+    const terminalBySession = new Map();
+    for (const artifact of artifacts) {
+        const reservation = getArtifactReservation(artifact);
+        if (!reservation)
+            continue;
+        const key = getReservationKey(reservation);
+        if (isPendingRecordingArtifact(artifact))
+            pendingBySession.set(key, reservation);
+        else
+            terminalBySession.set(key, reservation);
+    }
+    const transitions = [];
+    for (const key of terminalBySession.keys()) {
+        if (pendingBySession.has(key))
+            continue;
+        const existing = reservations.get(key);
+        if (!existing)
+            continue;
+        reservations.delete(key);
+        transitions.push({ reservation: existing, state: "closed" });
+    }
+    for (const [key, pending] of pendingBySession) {
+        const existing = reservations.get(key);
+        reservations.set(key, pending);
+        if (!existing || existing.absolutePath !== pending.absolutePath || existing.cwd !== pending.cwd) {
+            transitions.push({ reservation: pending, state: "active" });
+        }
+    }
+    return transitions;
+}
+export function retireRecordingReservation(reservations, sessionName, namespace) {
+    const key = getAgentBrowserSessionIdentityKey(sessionName, namespace);
+    const reservation = reservations.get(key);
+    if (reservation)
+        reservations.delete(key);
+    return reservation;
+}
+export function appendRecordingReservationTransition(pi, transition) {
+    const { reservation, state } = transition;
+    pi.appendEntry(RECORDING_RESERVATION_ENTRY_TYPE, {
+        absolutePath: state === "active" ? reservation.absolutePath : undefined,
+        cwd: state === "active" ? reservation.cwd : undefined,
+        namespace: reservation.namespace,
+        path: state === "active" ? reservation.path : undefined,
+        sessionName: reservation.sessionName,
+        state,
+        version: 1,
+    });
+}
+function parseReservationTransition(data) {
+    if (!isRecord(data) || data.version !== 1 || (data.state !== "active" && data.state !== "closed"))
+        return undefined;
+    if (typeof data.sessionName !== "string" || data.sessionName.length === 0)
+        return undefined;
+    if (data.namespace !== undefined && typeof data.namespace !== "string")
+        return undefined;
+    if (data.state === "closed") {
+        return {
+            reservation: { absolutePath: "", cwd: "", namespace: data.namespace, path: "", sessionName: data.sessionName },
+            state: "closed",
+        };
+    }
+    if (typeof data.absolutePath !== "string" || typeof data.cwd !== "string" || typeof data.path !== "string")
+        return undefined;
+    return {
+        reservation: {
+            absolutePath: data.absolutePath,
+            cwd: data.cwd,
+            namespace: data.namespace,
+            path: data.path,
+            sessionName: data.sessionName,
+        },
+        state: "active",
+    };
+}
+export function restoreRecordingReservationStateFromBranch(branch) {
+    const reservations = new Map();
+    const terminal = new Map();
+    for (const entry of branch) {
+        if (!isRecord(entry) || entry.type !== "custom" || entry.customType !== RECORDING_RESERVATION_ENTRY_TYPE)
+            continue;
+        const transition = parseReservationTransition(entry.data);
+        if (!transition)
+            continue;
+        const key = getReservationKey(transition.reservation);
+        if (transition.state === "active") {
+            reservations.set(key, transition.reservation);
+            terminal.delete(key);
+        }
+        else {
+            reservations.delete(key);
+            terminal.set(key, transition.reservation);
+        }
+    }
+    return { active: reservations, terminal };
+}

package/dist/extensions/agent-browser/lib/results/action-recommendations.js

@@ -1,6 +1,6 @@
 import { isOpenNavigationCommand, isPageMutationCommand } from "../command-taxonomy.js";
 import { isPendingRecordingArtifact } from "./artifact-manifest.js";
-import { buildNextToolAction } from "./next-actions.js";
+import { applySessionToNextActions, buildNextToolAction } from "./next-actions.js";
 import { AGENT_BROWSER_RECOVERY_NEXT_ACTION_IDS, buildRecoveryNextActions, } from "./recovery-actions.js";
 function buildArtifactAction(path) {
     return {
@@ -106,7 +106,7 @@ export function buildAgentBrowserNextActions(options) {
                 reason: "Inspect the opened page before choosing interactive refs.",
             }));
         }
-        else if (isPageMutationCommand(options.command)) {
+        else if (isPageMutationCommand(options.command, options.subcommand)) {
             actions.push(buildNextToolAction({
                 args: ["snapshot", "-i"],
                 id: "inspect-after-mutation",
@@ -120,9 +120,8 @@ export function buildAgentBrowserNextActions(options) {
             actions.push(buildArtifactAction(options.savedFilePath));
         }
         for (const artifact of artifacts) {
-            if (isPendingRecordingArtifact(artifact)) {
+            if (isPendingRecordingArtifact(artifact))
                 continue;
-            }
             if (artifact.exists === false) {
                 if (artifact.kind === "download") {
                     actions.push(buildNextToolAction({
@@ -146,7 +145,7 @@ export function buildAgentBrowserNextActions(options) {
         switch (options.failureCategory) {
             case "artifact-missing":
                 for (const artifact of options.artifacts ?? []) {
-                    if (isPendingRecordingArtifact(artifact) || artifact.exists !== false)
+                    if (isPendingRecordingArtifact(artifact) || (artifact.exists !== false && artifact.status !== "stale"))
                         continue;
                     if (artifact.kind === "download") {
                         actions.push(buildNextToolAction({
@@ -196,6 +195,56 @@ export function buildAgentBrowserNextActions(options) {
                     }));
                 }
                 break;
+            case "timeout":
+                {
+                    const textAssertion = options.command === "wait" && options.args?.includes("--text") === true;
+                    const urlAssertion = options.command === "wait" && options.args?.includes("--url") === true;
+                    actions.push(buildNextToolAction({
+                        args: ["snapshot", "-i"],
+                        id: textAssertion ? "inspect-after-text-assertion-failure" : "inspect-after-timeout",
+                        reason: textAssertion
+                            ? "Inspect the current page after the text assertion failed before concluding the expected text is absent."
+                            : options.command === "wait"
+                                ? "Inspect the current page after the wait condition timed out before retrying with a different selector or timeout."
+                                : "Inspect the current page after the timed-out browser operation.",
+                        safety: textAssertion
+                            ? "Read-only snapshot; use current refs or visible text from this page before retrying the assertion."
+                            : "Read-only snapshot; do not assume the timed-out interaction completed.",
+                    }));
+                    if (urlAssertion) {
+                        actions.push(buildNextToolAction({
+                            args: ["open", "about:blank"],
+                            id: "fresh-session-after-url-wait-timeout",
+                            reason: "If a preceding click or form submit reported success but the page never navigated, upstream click dispatch may have silently missed (observed with agent-browser 0.34 after many spaced commands); replace about:blank with the target URL and replay the flow as one batch in a fresh session instead of retrying the wait.",
+                            safety: "Abandons the current browser session; capture page evidence with the inspect action first, and only abandon when the wait target is not simply wrong or slow.",
+                            sessionMode: "fresh",
+                        }));
+                    }
+                }
+                break;
+            case "upstream-error":
+                if (isOpenNavigationCommand(options.command)) {
+                    actions.push(buildNextToolAction({
+                        args: ["get", "url"],
+                        id: "inspect-page-after-navigation-error",
+                        reason: "Check which page, if any, remains active after the navigation or network error.",
+                        safety: "Read-only URL inspection; verify connectivity and the target URL before retrying navigation.",
+                    }));
+                }
+                break;
+            case "tab-gone":
+                actions.push(buildNextToolAction({
+                    args: ["tab", "list"],
+                    id: AGENT_BROWSER_RECOVERY_NEXT_ACTION_IDS.tabGoneListTabs,
+                    reason: "The pinned bound tab is gone; inspect remaining tabs before acting on a neighbor.",
+                    safety: "Read-only. Prefer a listed tab id, label, or CDP targetId, or open a new tab to rebind.",
+                }), buildNextToolAction({
+                    args: ["tab", "new"],
+                    id: AGENT_BROWSER_RECOVERY_NEXT_ACTION_IDS.tabGoneNewTab,
+                    reason: "Bind a fresh tab after tab_gone instead of continuing on another session's page.",
+                    safety: "Opens a new tab in this session and rebinds the pin; pass a URL if you know the intended page.",
+                }));
+                break;
             case "tab-drift":
                 if (options.recovery?.kind === "about-blank" || options.recovery?.kind === "tab-drift") {
                     break;
@@ -209,5 +258,13 @@ export function buildAgentBrowserNextActions(options) {
                 break;
         }
     }
-    return actions.length > 0 ? actions : undefined;
+    if ((options.artifacts ?? []).some(isPendingRecordingArtifact)) {
+        actions.push(buildNextToolAction({
+            args: ["record", "stop"],
+            id: "stop-pending-recording",
+            reason: "Stop the active recording so the requested video can be finalized and verified on disk.",
+            safety: "The file remains pending until record stop succeeds; verify details.artifactVerification afterward.",
+        }));
+    }
+    return applySessionToNextActions(actions.length > 0 ? actions : undefined, options.sessionName);
 }