pi-agent-browser-native 0.9.3 → 0.9.5

package/dist/extensions/agent-browser/lib/orchestration/browser-run/managed-session-daemon-policy.js

@@ -1,94 +1,147 @@
-import { rm } from "node:fs/promises";
 import { getAgentBrowserSessionIdentityKey } from "../../argv-grammar.js";
 import { inspectElectronLaunchStatus } from "../../electron/cleanup.js";
-import { acquireManagedSessionPolicyLock } from "../../managed-session-policy-lock.js";
-import { pruneOwnedManagedSessionRestoreSnapshots, resolveExplicitAutosaveInterval, withOwnedManagedSessionContext, } from "../../managed-session-restore.js";
-import { isManagedSessionRestoreKey } from "../../managed-session-storage.js";
+import { acquireManagedSessionPolicyLock, } from "../../managed-session-policy-lock.js";
+import { withOwnedManagedSessionContext, } from "../../managed-session-restore.js";
 import { isRecord } from "../../parsing.js";
-import { readProcessStartIdentity } from "../../process-identity.js";
-import { getAgentBrowserProcessEnvironment, withAgentBrowserProcessEnvironment } from "../../process-environment.js";
-import { runAgentBrowserProcess, withAttachedBrowserSessionContext } from "../../process.js";
-import { getAgentBrowserErrorText, parseAgentBrowserEnvelope } from "../../results/envelope.js";
-import { detectConfirmationRequired } from "../../results/confirmation.js";
-import { redactInvocationArgs } from "../../runtime.js";
+import { withAttachedBrowserSessionContext } from "../../process.js";
 import { runSessionCommandData } from "./session-state.js";
-const MANAGED_SESSION_DAEMON_INSPECTION_TIMEOUT_MS = 35_000;
-const RUNNING_HEADED_AUTOSAVE_POLICY_CHANGE_ERROR = "AGENT_BROWSER_AUTOSAVE_INTERVAL_MS cannot change a running wrapper-owned headed session's launch-time periodic autosave interval. Close that session first, then retry with sessionMode: \"fresh\" so the new daemon starts with the requested interval.";
-export function getRunningHeadedAutosavePolicyChangeError(recordedInterval, closeCommand = false) {
-    const explicitInterval = resolveExplicitAutosaveInterval(getAgentBrowserProcessEnvironment().AGENT_BROWSER_AUTOSAVE_INTERVAL_MS);
-    return recordedInterval !== undefined && !closeCommand && explicitInterval !== undefined && explicitInterval !== recordedInterval
-        ? RUNNING_HEADED_AUTOSAVE_POLICY_CHANGE_ERROR
-        : undefined;
+import { getHeadedManagedAutosaveEnv, inspectManagedSessionDaemon, } from "./managed-session-daemon-inspection.js";
+export { closeManagedSession } from "./managed-session-close.js";
+export { getRunningHeadedAutosavePolicyChangeError, inspectManagedSessionDaemon, } from "./managed-session-daemon-inspection.js";
+function hasElectronAttachmentIdentity(record) {
+    return (record.webSocketDebuggerUrl !== undefined &&
+        record.webSocketDebuggerUrl !== "" &&
+        record.sessionName !== undefined &&
+        record.sessionName !== "");
 }
-function getHeadedManagedAutosaveEnv(interval) {
-    return interval !== undefined ? { AGENT_BROWSER_AUTOSAVE_INTERVAL_MS: interval } : undefined;
-}
-export async function inspectManagedSessionDaemon(options) {
-    const processResult = await runAgentBrowserProcess({
-        args: ["--json", "--namespace", options.namespace ?? "", "--session", options.sessionName, "session", "info"],
-        cwd: options.cwd,
-        env: getHeadedManagedAutosaveEnv(options.headedManagedAutosaveInterval),
-        preserveAttachedBrowserSession: options.preserveAttachedBrowserSession,
-        signal: options.signal,
-        timeoutMs: options.timeoutMs ?? MANAGED_SESSION_DAEMON_INSPECTION_TIMEOUT_MS,
-    });
-    try {
-        if (processResult.spawnError?.code === "ENOENT")
-            return { status: "missing-binary" };
-        if (processResult.aborted || processResult.spawnError || processResult.exitCode !== 0)
-            return { status: "unknown" };
-        const parsed = await parseAgentBrowserEnvelope({ stdout: processResult.stdout, stdoutPath: processResult.stdoutSpillPath });
-        const data = parsed.parseError || parsed.envelope?.success === false ? undefined : parsed.envelope?.data;
-        if (!isRecord(data) || typeof data.active !== "boolean")
-            return { status: "unknown" };
-        if (!data.active)
-            return { status: "inactive" };
-        if (!isRecord(data.runtime))
-            return { status: "unknown" };
-        let generation;
-        if (options.includeGeneration && Number.isSafeInteger(data.runtime.backgroundPid) && Number(data.runtime.backgroundPid) > 0
-            && typeof data.runtime.socketDir === "string" && data.runtime.browserLaunched !== false) {
-            const start = await readProcessStartIdentity(Number(data.runtime.backgroundPid), process.platform, { signal: options.signal, deadline: Date.now() + (options.timeoutMs ?? 5_000) });
-            if (start)
-                generation = JSON.stringify({ pid: data.runtime.backgroundPid, start, socketDir: data.runtime.socketDir });
-        }
-        if (typeof data.runtime.restoreKey === "string" && data.runtime.restoreKey.length > 0)
-            return { restoreKey: data.runtime.restoreKey, status: "active", generation };
-        return data.runtime.restoreKey === null ? { restoreKey: null, status: "active", generation } : { status: "unknown" };
+function restoredAttachmentTarget(context, record) {
+    const cwd = context.cwd;
+    if (cwd === undefined || cwd === "" || !record || !hasElectronAttachmentIdentity(record)) {
+        return undefined;
     }
-    finally {
-        if (processResult.stdoutSpillPath)
-            await rm(processResult.stdoutSpillPath, { force: true }).catch(() => undefined);
+    if (record.cleanupState === "cleaned" ||
+        getAgentBrowserSessionIdentityKey(record.sessionName ?? "", record.namespace) !==
+            getAgentBrowserSessionIdentityKey(context.sessionName, context.namespace)) {
+        return undefined;
     }
+    return { cwd, record };
 }
-async function verifyRestoredElectronAttachment(context, record, signal, timeoutMs) {
-    const cwd = context.cwd;
-    if (!cwd || !record?.webSocketDebuggerUrl || !record.sessionName || record.cleanupState === "cleaned"
-        || getAgentBrowserSessionIdentityKey(record.sessionName, record.namespace) !== getAgentBrowserSessionIdentityKey(context.sessionName, context.namespace))
+function attachmentStatusMatches(record, status) {
+    return (status.pidAlive === true &&
+        status.userDataDirState === "present" &&
+        status.version?.webSocketDebuggerUrl === record.webSocketDebuggerUrl);
+}
+function attachmentConnectionMatches(connection, record, status) {
+    return (isRecord(connection) &&
+        typeof connection.cdpUrl === "string" &&
+        (connection.cdpUrl === record.webSocketDebuggerUrl ||
+            status.targets.some((target) => target.webSocketDebuggerUrl === connection.cdpUrl)));
+}
+async function verifyRestoredElectronAttachment(options) {
+    const { context, signal } = options;
+    const attachment = restoredAttachmentTarget(context, options.electronLaunchRecord);
+    if (!attachment) {
         return false;
-    const status = await inspectElectronLaunchStatus(record, signal);
-    if (signal?.aborted || status.pidAlive !== true || status.userDataDirState !== "present"
-        || status.version?.webSocketDebuggerUrl !== record.webSocketDebuggerUrl)
+    }
+    const status = await inspectElectronLaunchStatus(attachment.record, signal);
+    if (signal?.aborted === true || !attachmentStatusMatches(attachment.record, status)) {
         return false;
+    }
     // This metadata probe must not grant daemon provenance just by spawning.
     const connection = await withAttachedBrowserSessionContext(true, () => withOwnedManagedSessionContext(undefined, () => runSessionCommandData({
-        args: ["get", "cdp-url"], cwd, env: getHeadedManagedAutosaveEnv(context.headedManagedAutosaveInterval), namespace: context.namespace, pinNamespace: true,
-        sessionName: context.sessionName, signal, timeoutMs,
+        args: ["get", "cdp-url"],
+        cwd: attachment.cwd,
+        env: getHeadedManagedAutosaveEnv(context.headedManagedAutosaveInterval),
+        namespace: context.namespace,
+        pinNamespace: true,
+        sessionName: context.sessionName,
+        signal,
+        timeoutMs: options.electronVerificationTimeoutMs,
     })));
-    return !signal?.aborted && isRecord(connection) && typeof connection.cdpUrl === "string"
-        && (connection.cdpUrl === record.webSocketDebuggerUrl || status.targets.some((target) => target.webSocketDebuggerUrl === connection.cdpUrl));
+    return (
+    // The abort callback can change this signal during the awaited CDP read; static narrowing does not model it.
+    // oxlint-disable-next-line typescript/no-unnecessary-condition
+    !(signal?.aborted ?? false) &&
+        attachmentConnectionMatches(connection, attachment.record, status));
+}
+function reconcileDaemonReceipt(context, daemon, receipt) {
+    if (daemon.status === "inactive") {
+        context.restoreState.forgetDaemonRestoreKey(context.sessionName, context.namespace);
+    }
+    if (daemon.status !== "active" ||
+        receipt === undefined ||
+        context.restoreState.hasDaemonRestoreKey(context.sessionName, context.namespace)) {
+        return;
+    }
+    if (daemon.generation === receipt.generation && daemon.restoreKey === receipt.restoreKey) {
+        context.restoreState.recordDaemonRestoreKey(context.sessionName, context.namespace, daemon.restoreKey, daemon.generation);
+    }
+    else {
+        context.restoreState.forgetDaemonRestoreKey(context.sessionName, context.namespace);
+    }
+}
+function daemonPolicyMismatch(daemon, restoreDisabledPolicyNeedsProvenance, hasKnownDaemonRestoreKey) {
+    return {
+        cleanupOnlyReason: daemon.status === "active" &&
+            restoreDisabledPolicyNeedsProvenance &&
+            !hasKnownDaemonRestoreKey
+            ? "restore-disabled-daemon-without-provenance"
+            : undefined,
+        daemonStatus: daemon.status,
+        error: [
+            "This wrapper-owned session's live daemon does not match the requested managed-restore policy.",
+            'Close that session first, retry with sessionMode: "fresh", or use a distinct explicit --session.',
+        ].join(" "),
+    };
+}
+async function validateReusableDaemonPolicy(options, daemon) {
+    const { context } = options;
+    const stickyDisabled = context.restoreState.isDisabled(context.sessionName, context.namespace);
+    let hasKnownDaemonRestoreKey = context.restoreState.hasDaemonRestoreKey(context.sessionName, context.namespace);
+    const knownDaemonRestoreKey = context.restoreState.getDaemonRestoreKey(context.sessionName, context.namespace);
+    const requestedDaemonRestoreKey = context.restoreDecision === "enabled" && stickyDisabled
+        ? (knownDaemonRestoreKey ?? null)
+        : context.expectedDaemonRestoreKey;
+    if (daemon.status === "unknown") {
+        return {
+            error: 'The wrapper could not verify this managed session\'s live daemon restore policy. Retry, close that session, or use sessionMode: "fresh".',
+        };
+    }
+    const restoreDisabledPolicyNeedsProvenance = stickyDisabled || context.restoreDecision !== "enabled";
+    if (daemon.status === "active" &&
+        restoreDisabledPolicyNeedsProvenance &&
+        !hasKnownDaemonRestoreKey &&
+        daemon.restoreKey === requestedDaemonRestoreKey) {
+        hasKnownDaemonRestoreKey = await verifyRestoredElectronAttachment(options);
+    }
+    return finishReusableDaemonPolicy(context, daemon, {
+        restoreDisabledPolicyNeedsProvenance,
+        requestedDaemonRestoreKey,
+    }, hasKnownDaemonRestoreKey);
+}
+function finishReusableDaemonPolicy(context, daemon, policy, hasKnownDaemonRestoreKey) {
+    const activePolicyMatches = daemon.status === "active" &&
+        (!policy.restoreDisabledPolicyNeedsProvenance || hasKnownDaemonRestoreKey) &&
+        daemon.restoreKey === policy.requestedDaemonRestoreKey;
+    if (activePolicyMatches) {
+        context.restoreState.recordDaemonRestoreKey(context.sessionName, context.namespace, daemon.restoreKey);
+    }
+    return !["inactive", "missing-binary"].includes(daemon.status) && !activePolicyMatches
+        ? daemonPolicyMismatch(daemon, policy.restoreDisabledPolicyNeedsProvenance, hasKnownDaemonRestoreKey)
+        : { daemonStatus: daemon.status };
 }
 export async function acquireOwnedManagedSessionDaemonPolicy(options) {
     const { context, signal } = options;
-    if (!context.cwd)
+    if (context.cwd === undefined || context.cwd === "") {
         return { error: "Managed-session policy validation requires the wrapper-owned session cwd." };
+    }
     const lock = await acquireManagedSessionPolicyLock({
         namespace: context.namespace,
         sessionName: context.sessionName,
         signal,
     });
     if (!lock) {
-        return signal?.aborted
+        return signal?.aborted === true
             ? {}
             : {
                 error: "Managed-session policy coordination is unavailable or busy. Retry after the current operation finishes, repair the private policy-lock directory, and on POSIX verify that /bin/ps, /usr/bin/ps, or ps through PATH is available.",
@@ -98,155 +151,24 @@ export async function acquireOwnedManagedSessionDaemonPolicy(options) {
         const receipt = context.restoreState.getDaemonReceipt(context.sessionName, context.namespace);
         const daemon = await inspectManagedSessionDaemon({
             cwd: context.cwd,
-            includeGeneration: receipt !== undefined && !context.restoreState.hasDaemonRestoreKey(context.sessionName, context.namespace),
+            includeGeneration: receipt !== undefined &&
+                !context.restoreState.hasDaemonRestoreKey(context.sessionName, context.namespace),
             headedManagedAutosaveInterval: context.headedManagedAutosaveInterval,
             namespace: context.namespace,
             sessionName: context.sessionName,
             signal,
         });
-        if (daemon.status === "inactive")
-            context.restoreState.forgetDaemonRestoreKey(context.sessionName, context.namespace);
-        if (daemon.status === "active" && receipt && !context.restoreState.hasDaemonRestoreKey(context.sessionName, context.namespace)) {
-            if (daemon.generation === receipt.generation && daemon.restoreKey === receipt.restoreKey) {
-                context.restoreState.recordDaemonRestoreKey(context.sessionName, context.namespace, daemon.restoreKey, daemon.generation);
-            }
-            else
-                context.restoreState.forgetDaemonRestoreKey(context.sessionName, context.namespace);
-        }
+        reconcileDaemonReceipt(context, daemon, receipt);
         if (options.mode === "close") {
-            if (daemon.status === "active")
+            if (daemon.status === "active") {
                 context.restoreState.recordDaemonRestoreKey(context.sessionName, context.namespace, daemon.restoreKey);
+            }
             return { daemonStatus: daemon.status, lock };
         }
-        const stickyDisabled = context.restoreState.isDisabled(context.sessionName, context.namespace);
-        let hasKnownDaemonRestoreKey = context.restoreState.hasDaemonRestoreKey(context.sessionName, context.namespace);
-        const knownDaemonRestoreKey = context.restoreState.getDaemonRestoreKey(context.sessionName, context.namespace);
-        const requestedDaemonRestoreKey = context.restoreDecision === "enabled" && stickyDisabled
-            ? knownDaemonRestoreKey ?? null
-            : context.expectedDaemonRestoreKey;
-        if (daemon.status === "unknown") {
-            return {
-                error: "The wrapper could not verify this managed session's live daemon restore policy. Retry, close that session, or use sessionMode: \"fresh\".",
-                lock,
-            };
-        }
-        const restoreDisabledPolicyNeedsProvenance = stickyDisabled || context.restoreDecision !== "enabled";
-        if (daemon.status === "active" && restoreDisabledPolicyNeedsProvenance && !hasKnownDaemonRestoreKey && daemon.restoreKey === requestedDaemonRestoreKey) {
-            hasKnownDaemonRestoreKey = await verifyRestoredElectronAttachment(context, options.electronLaunchRecord, signal, options.electronVerificationTimeoutMs);
-        }
-        const activePolicyMatches = daemon.status === "active"
-            && (!restoreDisabledPolicyNeedsProvenance || hasKnownDaemonRestoreKey)
-            && daemon.restoreKey === requestedDaemonRestoreKey;
-        if (activePolicyMatches)
-            context.restoreState.recordDaemonRestoreKey(context.sessionName, context.namespace, daemon.restoreKey);
-        return !["inactive", "missing-binary"].includes(daemon.status) && !activePolicyMatches
-            ? {
-                cleanupOnlyReason: daemon.status === "active" && restoreDisabledPolicyNeedsProvenance && !hasKnownDaemonRestoreKey
-                    ? "restore-disabled-daemon-without-provenance"
-                    : undefined,
-                daemonStatus: daemon.status,
-                error: [
-                    "This wrapper-owned session's live daemon does not match the requested managed-restore policy.",
-                    "Close that session first, retry with sessionMode: \"fresh\", or use a distinct explicit --session.",
-                ].join(" "),
-                lock,
-            }
-            : { daemonStatus: daemon.status, lock };
+        return { ...(await validateReusableDaemonPolicy(options, daemon)), lock };
     }
     catch (error) {
         await lock.release();
         throw error;
     }
 }
-export async function closeManagedSession(options) {
-    return withAgentBrowserProcessEnvironment({ AGENT_BROWSER_CONFIRM_ACTIONS: options.confirmActions, ...(options.socketDir ? { PI_AGENT_BROWSER_SOCKET_DIR: options.socketDir } : {}) }, async () => {
-        const controller = new AbortController();
-        let phase = "policy coordination";
-        let phaseStartedAt = Date.now();
-        let timeoutError;
-        const timer = setTimeout(() => {
-            timeoutError = `Managed-session cleanup timed out after ${options.timeoutMs} ms during ${phase} (${Date.now() - phaseStartedAt} ms in this phase).`;
-            controller.abort();
-        }, options.timeoutMs);
-        let stdoutSpillPath;
-        const closeArgs = [...(options.namespace !== undefined ? ["--namespace", options.namespace] : []), "--session", options.sessionName, "close"];
-        const policyLock = options.policyLock ?? await acquireManagedSessionPolicyLock({
-            namespace: options.namespace,
-            sessionName: options.sessionName,
-            signal: controller.signal,
-            timeoutMs: Math.min(options.timeoutMs, 1_000),
-        });
-        if (!policyLock) {
-            clearTimeout(timer);
-            return timeoutError ?? "Managed-session policy coordination is unavailable or busy; cleanup did not run. Retry after the current operation finishes or repair the private policy-lock directory.";
-        }
-        try {
-            phase = "daemon inspection";
-            phaseStartedAt = Date.now();
-            const daemon = await inspectManagedSessionDaemon({
-                cwd: options.cwd,
-                headedManagedAutosaveInterval: options.headedManagedAutosaveInterval,
-                namespace: options.namespace,
-                preserveAttachedBrowserSession: options.preserveAttachedBrowserSession,
-                sessionName: options.sessionName,
-                signal: controller.signal,
-                timeoutMs: Math.min(options.timeoutMs, 2_000),
-            });
-            if (daemon.status === "active")
-                options.restoreState.recordDaemonRestoreKey(options.sessionName, options.namespace, daemon.restoreKey);
-            const daemonRestoreKey = options.restoreState.getDaemonRestoreKey(options.sessionName, options.namespace);
-            const ownedRestoreKey = !options.restoreState.isDisabled(options.sessionName, options.namespace)
-                && isManagedSessionRestoreKey(daemonRestoreKey) ? daemonRestoreKey : null;
-            phase = "native close";
-            phaseStartedAt = Date.now();
-            const processResult = await runAgentBrowserProcess({
-                args: closeArgs,
-                cwd: options.cwd,
-                env: { AGENT_BROWSER_JSON: "1", ...getHeadedManagedAutosaveEnv(options.headedManagedAutosaveInterval) },
-                managedSessionRestoreState: options.restoreState,
-                ownedManagedSession: true,
-                preserveAttachedBrowserSession: options.preserveAttachedBrowserSession,
-                signal: controller.signal,
-            });
-            clearTimeout(timer);
-            stdoutSpillPath = processResult.stdoutSpillPath;
-            const parsed = await parseAgentBrowserEnvelope({ stdout: processResult.stdout, stdoutPath: processResult.stdoutSpillPath });
-            if (!processResult.aborted && !processResult.spawnError && processResult.exitCode === 0) {
-                const data = parsed.envelope?.success === true && isRecord(parsed.envelope.data) && parsed.envelope.data.closed === true ? parsed.envelope.data : undefined;
-                if (data) {
-                    options.restoreState.clear(options.sessionName, options.namespace);
-                    pruneOwnedManagedSessionRestoreSnapshots({
-                        cwd: options.cwd,
-                        namespace: options.namespace,
-                        restoreKey: ownedRestoreKey,
-                        statePath: typeof data.statePath === "string" ? data.statePath : undefined,
-                    });
-                }
-            }
-            const pending = detectConfirmationRequired(parsed.envelope?.data);
-            return timeoutError ?? (pending ? `Native close requires confirmation (${pending.id}); the session remains wrapper-owned.` : getAgentBrowserErrorText({
-                aborted: processResult.aborted,
-                command: "close",
-                effectiveArgs: redactInvocationArgs(closeArgs),
-                envelope: parsed.envelope,
-                exitCode: processResult.exitCode,
-                parseError: parsed.parseError,
-                plainTextInspection: false,
-                spawnError: processResult.spawnError,
-                stderr: processResult.stderr,
-                timedOut: processResult.timedOut,
-                timeoutMs: processResult.timeoutMs,
-            }));
-        }
-        catch (error) {
-            return timeoutError ?? (error instanceof Error ? error.message : String(error));
-        }
-        finally {
-            clearTimeout(timer);
-            if (stdoutSpillPath)
-                await rm(stdoutSpillPath, { force: true }).catch(() => undefined);
-            if (!options.policyLock)
-                await policyLock.release();
-        }
-    });
-}

package/dist/extensions/agent-browser/lib/orchestration/browser-run/native-helper-observation.js

@@ -0,0 +1,65 @@
+import { getAgentBrowserSessionIdentityKey, resolveAgentBrowserNamespace, } from "../../argv-grammar.js";
+import { parseArgvDescriptor } from "../../argv-descriptor.js";
+import { isBrowserIndependentRead, needsManagedSession } from "../../command-policy.js";
+import { getAgentBrowserProcessEnvironment } from "../../process-environment.js";
+import { nextReadConfirmation, parseReadConfirmation } from "../../read-confirmation.js";
+import { nativePolicyDefinitelyUnestablished, } from "./session-state.js";
+function helperNamespace(helper) {
+    return resolveAgentBrowserNamespace([], helper.namespace ?? getAgentBrowserProcessEnvironment().AGENT_BROWSER_NAMESPACE);
+}
+function helperMayRun(helper, effects) {
+    const pending = parseReadConfirmation(effects?.readConfirmation);
+    return ((!needsManagedSession(parseArgvDescriptor(helper.args), helper.stdin) &&
+        !isBrowserIndependentRead(helper.args, helper.stdin)) ||
+        pending?.state !== "pending" ||
+        getAgentBrowserSessionIdentityKey(helper.sessionName ?? "default", helperNamespace(helper)) !==
+            getAgentBrowserSessionIdentityKey(pending.sessionName, pending.namespace));
+}
+function helperSucceeded(observation) {
+    return (observation.envelope?.success === true &&
+        observation.processResult.exitCode === 0 &&
+        !observation.processResult.aborted &&
+        !observation.processResult.timedOut);
+}
+function markPendingOpenTargetUnknown(state, update, key) {
+    const invalidation = state.sessionPageState.get(key).refSnapshotInvalidation;
+    state.sessionPageState.markTabTargetUnknown({ sessionName: key, update });
+    if (invalidation) {
+        state.sessionPageState.applyRefSnapshotInvalidation({ sessionName: key, update, invalidation });
+    }
+}
+function applyHelperConfirmation(state, update, observation) {
+    const { helper, envelope, processResult } = observation;
+    const namespace = helperNamespace(helper);
+    const sessionName = helper.sessionName ?? "default";
+    const key = getAgentBrowserSessionIdentityKey(sessionName, namespace);
+    if (key === state.confirmationPolicyIdentity &&
+        !nativePolicyDefinitelyUnestablished(processResult, envelope, helper.args)) {
+        state.confirmationPolicyMayBeEstablished = true;
+    }
+    const confirmation = nextReadConfirmation({
+        commandTokens: helper.args,
+        current: state.sessionPageState.getReadConfirmation(key),
+        data: envelope?.data,
+        namespace,
+        sessionName,
+        succeeded: helperSucceeded(observation),
+    });
+    if (!confirmation) {
+        return;
+    }
+    state.sessionPageState.applyReadConfirmation(confirmation, update);
+    if (helper.args[0] === "open" && confirmation.state === "pending") {
+        markPendingOpenTargetUnknown(state, update, key);
+    }
+    state.observedBrowserEffects = {
+        ...state.observedBrowserEffects,
+        readConfirmation: confirmation,
+    };
+}
+export function createNativeHelperObserver(state, update) {
+    return {
+        allow: (helper) => helperMayRun(helper, state.observedBrowserEffects),
+        observe: (helper, processResult, envelope) => applyHelperConfirmation(state, update, { helper, processResult, envelope }),
+    };
+}

package/dist/extensions/agent-browser/lib/orchestration/browser-run/observation-types.js

@@ -0,0 +1 @@
+export {};

package/dist/extensions/agent-browser/lib/orchestration/browser-run/overlay-diagnostics.js

@@ -0,0 +1,120 @@
+import { isRecord } from "../../parsing.js";
+import { buildInspectOverlayStateAction, withOptionalSessionArgs, } from "../../results/next-actions.js";
+import { extractRefSnapshotFromData, normalizeComparableUrl, } from "../../session-page-state.js";
+import { rawStringField } from "./diagnostic-values.js";
+import { runSessionCommandData } from "./session-state.js";
+const OVERLAY_CLOSE_NAME_PATTERN = /(?:\b(?:close|dismiss|no thanks|not now|maybe later|hide|skip|continue without|x)\b|^\s*×\s*$)/i;
+const OVERLAY_CONTEXT_ROLES = new Set(["alertdialog", "dialog"]);
+const OVERLAY_ACTION_ROLES = new Set(["button", "link", "menuitem"]);
+const OVERLAY_BLOCKER_CANDIDATE_LIMIT = 3;
+function overlayBlockerCandidate(ref, entry) {
+    if (!/^e\d+$/.test(ref) || !isRecord(entry)) {
+        return undefined;
+    }
+    const role = rawStringField(entry, "role");
+    const name = rawStringField(entry, "name");
+    if (role === undefined ||
+        role === "" ||
+        !OVERLAY_ACTION_ROLES.has(role.toLowerCase()) ||
+        name === undefined ||
+        name === "" ||
+        !OVERLAY_CLOSE_NAME_PATTERN.test(name)) {
+        return undefined;
+    }
+    return {
+        args: ["click", `@${ref}`],
+        name,
+        reason: `Visible ${role} ${JSON.stringify(name)} appears in a snapshot that also contains overlay/banner/dialog context.`,
+        ref: `@${ref}`,
+        role,
+    };
+}
+function getOverlayBlockerCandidates(snapshotData) {
+    const refs = isRecord(snapshotData) && isRecord(snapshotData.refs) ? snapshotData.refs : undefined;
+    if (!refs ||
+        !Object.values(refs).some((entry) => isRecord(entry) &&
+            OVERLAY_CONTEXT_ROLES.has((rawStringField(entry, "role") ?? "").toLowerCase()))) {
+        return [];
+    }
+    const candidates = [];
+    for (const [ref, entry] of Object.entries(refs)) {
+        const candidate = overlayBlockerCandidate(ref, entry);
+        if (candidate) {
+            candidates.push(candidate);
+        }
+        if (candidates.length >= OVERLAY_BLOCKER_CANDIDATE_LIMIT) {
+            break;
+        }
+    }
+    return candidates;
+}
+export function formatOverlayBlockerText(diagnostic) {
+    return [
+        "Possible overlay blockers:",
+        ...diagnostic.candidates.map((candidate) => {
+            const role = candidate.role !== undefined && candidate.role !== "" ? ` ${candidate.role}` : "";
+            const name = candidate.name !== undefined && candidate.name !== ""
+                ? ` ${JSON.stringify(candidate.name)}`
+                : "";
+            return `- ${candidate.ref}${role}${name}: ${candidate.reason}`;
+        }),
+    ].join("\n");
+}
+export function buildOverlayBlockerNextActions(options) {
+    return [
+        buildInspectOverlayStateAction(options.sessionName),
+        ...options.diagnostic.candidates.map((candidate, index) => ({
+            id: `try-overlay-blocker-candidate-${index + 1}`,
+            params: { args: withOptionalSessionArgs(options.sessionName, candidate.args) },
+            reason: candidate.reason,
+            safety: "Only click this if the candidate is clearly a close/dismiss control for an overlay that blocks the intended workflow.",
+            tool: "agent_browser",
+        })),
+    ];
+}
+export function collectSnapshotOverlayBlockerDiagnostic(data) {
+    const candidates = getOverlayBlockerCandidates(data);
+    const snapshot = extractRefSnapshotFromData(data);
+    return candidates.length === 0 || !snapshot
+        ? undefined
+        : {
+            candidates,
+            snapshot,
+            summary: "Snapshot contains dialog/modal context plus likely close or dismiss controls; treat covered controls as potentially obstructed until the overlay state is resolved.",
+        };
+}
+function isSnapshotRefClick(data) {
+    return (isRecord(data) &&
+        typeof data.clicked === "string" &&
+        (data.clicked.startsWith("@") || data.clicked.startsWith("ref=")));
+}
+function stationaryRefClickUrl(options) {
+    if (options.command !== "click" || !isSnapshotRefClick(options.data)) {
+        return undefined;
+    }
+    const priorUrl = normalizeComparableUrl(options.priorTarget?.url);
+    const currentUrl = normalizeComparableUrl(options.navigationSummary?.url);
+    return currentUrl !== undefined && currentUrl !== "" && currentUrl === priorUrl
+        ? currentUrl
+        : undefined;
+}
+export async function collectOverlayBlockerDiagnostic(options) {
+    const currentUrl = stationaryRefClickUrl(options);
+    if (currentUrl === undefined) {
+        return undefined;
+    }
+    const snapshotData = await runSessionCommandData({
+        args: ["snapshot", "-i"],
+        cwd: options.cwd,
+        namespace: options.namespace,
+        sessionName: options.sessionName,
+        signal: options.signal,
+    });
+    const diagnostic = collectSnapshotOverlayBlockerDiagnostic(snapshotData);
+    return diagnostic
+        ? {
+            ...diagnostic,
+            summary: `Click completed but the page stayed on ${currentUrl}; a fresh snapshot contains likely overlay close/dismiss controls.`,
+        }
+        : undefined;
+}