pi-agent-browser-native 0.3.0 → 0.5.0

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

@@ -6,10 +6,11 @@ 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 { extractExplicitSessionName, getFlagName, GLOBAL_BOOLEAN_FLAGS_WITH_OPTIONAL_VALUES, GLOBAL_VALUE_FLAGS, optionalGlobalValueFlagConsumesNext, resolveAgentBrowserNamespace, } from "./argv-grammar.js";
+import { canonicalizeOwnedManagedSessionCloseArgs, commitManagedSessionRestoreSuppression, getManagedSessionRestoreConfigEnv, getManagedSessionRestoreEnv, getOwnedManagedSessionRestoreKey, getManagedSessionRestoreProtectedEnv, getOwnedManagedSessionCompatibilityEnv, getOwnedManagedSessionNamespaceEnv, isOwnedManagedSessionTarget, shouldOmitOwnedManagedSessionRestoreEnv, validateManagedSessionRestoreContextForSpawn, } from "./managed-session-restore.js";
+import { getManagedSessionStateAccessValidationError, getManagedSessionTargetAccessValidationError, invocationMayNavigateToLocalFile, } from "./managed-session-state-policy.js";
 import { getImplicitSessionIdleTimeoutMs, isPlainTextInspectionArgs } 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;
@@ -20,16 +21,29 @@ 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 UNTRUSTED_LOCAL_FILE_SESSION_MESSAGE = "Local file navigation requires a wrapper-managed local browser because caller-owned or attached sessions can retain unsafe file-access launch flags. Omit the explicit session or attachment and retry with sessionMode fresh.";
 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", "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 +57,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 +96,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;
@@ -103,9 +129,9 @@ export function pinAgentBrowserFileAccessDisabled(args, wrapperCompatibilityUser
         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];
+        ? ["--args", `--user-agent=${wrapperCompatibilityUserAgent.replaceAll(/[\r\n,]/g, "")}`]
+        : [];
+    return [...browserArgs, "--allow-file-access", "false", ...filtered];
 }
 export function buildAgentBrowserSpawnCommand(args, platform = processPlatform) {
     if (platform !== "win32") {
@@ -216,33 +242,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 +309,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)) {
@@ -325,6 +397,7 @@ function getManagedPreSpawnPolicyError(options, effectiveEnv, allowManagedSessio
         currentPageUrl,
         cwd: options.cwd,
         env: effectiveEnv ?? options.env,
+        managedSessionRestoreKey: getOwnedManagedSessionRestoreKey(),
         pageUrlUnknown,
         parentEnv: effectiveEnv ? {} : options.parentEnv ?? processEnv,
         stdin: options.stdin,
@@ -348,11 +421,24 @@ export async function runAgentBrowserProcess(options) {
     if (signal?.aborted) {
         return { aborted: true, agentBrowserStarted: false, exitCode: 1, stderr: "", stdout: "", timedOut: false };
     }
+    if (invocationMayNavigateToLocalFile(args, stdin) && (!ownedManagedSession || preserveAttachedBrowserSession)) {
+        return {
+            aborted: false,
+            agentBrowserStarted: false,
+            exitCode: 1,
+            spawnError: new Error(UNTRUSTED_LOCAL_FILE_SESSION_MESSAGE),
+            stderr: "",
+            stdout: "",
+            timedOut: false,
+        };
+    }
+    const parentEnv = getAgentBrowserProcessEnvironment();
     const managedSessionRestoreOptions = {
         args,
         cwd,
         env,
         ownedManagedSession,
+        parentEnv,
         restoreState: managedSessionRestoreState,
         stdin,
     };
@@ -391,6 +477,7 @@ export async function runAgentBrowserProcess(options) {
         ...managedSessionRestoreConfigEnv,
         ...getManagedSessionRestoreProtectedEnv(managedSessionRestoreOptions, managedSessionRestoreEnv),
         ...getOwnedManagedSessionNamespaceEnv(managedSessionRestoreOptions),
+        ...getWindowsExplicitDefaultNamespaceEnv(args, parentEnv.AGENT_BROWSER_NAMESPACE),
         ...ownedManagedSessionCompatibilityEnv,
         AGENT_BROWSER_ALLOW_FILE_ACCESS: undefined,
         [AGENT_BROWSER_ARGS_ENV]: undefined,
@@ -399,18 +486,21 @@ export async function runAgentBrowserProcess(options) {
     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,
@@ -521,7 +611,7 @@ export async function runAgentBrowserProcess(options) {
                 });
             });
         };
-        const childEnv = buildAgentBrowserProcessEnv(processEnv, effectiveEnv);
+        const childEnv = buildAgentBrowserProcessEnv(parentEnv, effectiveEnv);
         const spawnPolicyError = getManagedPreSpawnPolicyError(managedSessionRestoreOptions, childEnv, allowManagedSessionTarget, managedStateCurrentPageUrl, managedStatePageUrlUnknown, trustedFirstBatchTabSelection, managedSessionRestoreConfigEnv.AGENT_BROWSER_CONFIG !== undefined);
         if (spawnPolicyError) {
             resolve({ aborted: false, agentBrowserStarted: false, exitCode: 1, spawnError: new Error(spawnPolicyError), stderr: "", stdout: "", timedOut: false });

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

@@ -0,0 +1,183 @@
+import { extractUpstreamCommandTokens } from "./argv-descriptor.js";
+import { getAgentBrowserSessionIdentityKey, isAgentBrowserSessionIdentityKeyInNamespace } from "./argv-grammar.js";
+import { batchHasSuccessfulCloseAll, getSuccessfulBatchCloseLifecycle } from "./batch-lifecycle.js";
+import { isCloseAllCommand, isCloseCommand } from "./command-taxonomy.js";
+import { isRecord } from "./parsing.js";
+import { isPendingRecordingArtifact, isPendingRecordingCommand, isSessionArtifactManifest } 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))
+            continue;
+        if (entry.type === "custom" && entry.customType === RECORDING_RESERVATION_ENTRY_TYPE) {
+            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);
+            }
+            continue;
+        }
+        if (entry.type !== "message")
+            continue;
+        const message = isRecord(entry.message) ? entry.message : undefined;
+        const details = message?.toolName === "agent_browser" && isRecord(message.details) ? message.details : undefined;
+        if (!details)
+            continue;
+        if (isSessionArtifactManifest(details.artifactManifest)) {
+            const artifacts = [...details.artifactManifest.entries]
+                .sort((left, right) => left.createdAtMs - right.createdAtMs
+                || Number(isPendingRecordingCommand(left.command, left.subcommand, left.kind)) - Number(isPendingRecordingCommand(right.command, right.subcommand, right.kind))
+                || left.path.localeCompare(right.path))
+                .filter((manifestEntry) => manifestEntry.command === "record" && manifestEntry.kind === "video" && manifestEntry.session)
+                .map((manifestEntry) => ({
+                absolutePath: manifestEntry.absolutePath ?? manifestEntry.path,
+                command: manifestEntry.command,
+                cwd: manifestEntry.cwd,
+                kind: "video",
+                namespace: manifestEntry.namespace,
+                path: manifestEntry.path,
+                session: manifestEntry.session,
+                status: isPendingRecordingCommand(manifestEntry.command, manifestEntry.subcommand, "video") ? "pending" : "saved",
+                subcommand: manifestEntry.subcommand,
+            }));
+            for (const artifact of artifacts) {
+                const reservation = getArtifactReservation(artifact);
+                if (!reservation)
+                    continue;
+                const key = getReservationKey(reservation);
+                applyRecordingArtifactsToReservations(reservations, [artifact]);
+                if (isPendingRecordingArtifact(artifact))
+                    terminal.delete(key);
+                else
+                    terminal.set(key, reservation);
+            }
+        }
+        const messageSucceeded = typeof message?.isError === "boolean"
+            ? !message.isError
+            : typeof details.exitCode !== "number" || details.exitCode === 0;
+        const args = Array.isArray(details.args) && details.args.every((arg) => typeof arg === "string") ? details.args : [];
+        const namespace = typeof details.namespace === "string" ? details.namespace : undefined;
+        const closeAllApplied = details.closeAllApplied === true
+            || (messageSucceeded && isCloseAllCommand(extractUpstreamCommandTokens(args)))
+            || batchHasSuccessfulCloseAll(details.batchSteps);
+        if (closeAllApplied) {
+            for (const [key, reservation] of reservations) {
+                if (!isAgentBrowserSessionIdentityKeyInNamespace(key, namespace))
+                    continue;
+                terminal.set(key, reservation);
+                reservations.delete(key);
+            }
+            continue;
+        }
+        const directCloseSucceeded = messageSucceeded && isCloseCommand(typeof details.command === "string" ? details.command : undefined);
+        const batchRecordingClosed = getSuccessfulBatchCloseLifecycle(details.batchSteps)?.recordingClosedAfterBatch === true;
+        if ((directCloseSucceeded || batchRecordingClosed) && typeof details.sessionName === "string") {
+            const key = getAgentBrowserSessionIdentityKey(details.sessionName, namespace);
+            const reservation = reservations.get(key);
+            if (reservation)
+                terminal.set(key, reservation);
+            reservations.delete(key);
+        }
+    }
+    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 {
@@ -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);
 }