pi-agent-browser-native 0.9.3 → 0.9.5

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

@@ -1,22 +1,68 @@
 import { isRecord } from "../../parsing.js";
 import { LIGHTPANDA_IMAGE_REASON } from "../../results/presentation/common.js";
-import { getScreenshotPathTokenIndex, getScreenshotPositionalIndices } from "./artifact-paths.js";
+import { getScreenshotCapture } from "./screenshot-capture.js";
+export { getScreenshotCapture } from "./screenshot-capture.js";
 import { runSessionCommandData } from "./session-state.js";
-export function getScreenshotCapture(command) {
-    if (command[0] !== "screenshot")
-        return { kind: "unknown" };
-    if (command.includes("--full") || command.includes("-f"))
-        return { kind: "full-page" };
-    const positional = getScreenshotPositionalIndices(command);
-    const selectorIndex = positional.find(index => index !== getScreenshotPathTokenIndex(command));
-    return selectorIndex === undefined ? { kind: "viewport" } : { kind: "element", selector: command[selectorIndex] };
-}
 function finiteRecord(value, keys) {
-    return isRecord(value) && keys.every(key => typeof value[key] === "number" && Number.isFinite(value[key]));
+    return (isRecord(value) &&
+        keys.every((key) => typeof value[key] === "number" && Number.isFinite(value[key])));
+}
+function parseSampleIdentity(sample) {
+    if ((sample.rendering !== undefined && sample.rendering !== "text") ||
+        typeof sample.url !== "string" ||
+        (sample.frame !== "main" && sample.frame !== "child")) {
+        return undefined;
+    }
+    return {
+        url: sample.url,
+        frame: sample.frame,
+        ...(sample.rendering === "text" ? { rendering: "text" } : {}),
+    };
+}
+function parseSampleScale(sample) {
+    if (typeof sample.childFrameCount !== "number" ||
+        !Number.isInteger(sample.childFrameCount) ||
+        sample.childFrameCount < 0 ||
+        typeof sample.dpr !== "number" ||
+        !Number.isFinite(sample.dpr) ||
+        sample.dpr <= 0) {
+        return undefined;
+    }
+    return { dpr: sample.dpr, childFrameCount: sample.childFrameCount };
+}
+function parseSampleMeasurements(value) {
+    if (!finiteRecord(value.viewport, ["width", "height"]) ||
+        !finiteRecord(value.document, ["width", "height"]) ||
+        !finiteRecord(value.scroll, ["x", "y"]) ||
+        !finiteRecord(value.visualViewport, ["x", "y", "scale"])) {
+        return undefined;
+    }
+    if (value.element !== undefined && !finiteRecord(value.element, ["x", "y", "width", "height"])) {
+        return undefined;
+    }
+    return {
+        viewport: value.viewport,
+        document: value.document,
+        scroll: value.scroll,
+        visualViewport: value.visualViewport,
+        ...(value.element !== undefined ? { element: value.element } : {}),
+    };
+}
+function parseScreenshotSample(value) {
+    if (!isRecord(value)) {
+        return undefined;
+    }
+    const identity = parseSampleIdentity(value);
+    const scale = parseSampleScale(value);
+    const measurements = parseSampleMeasurements(value);
+    return identity && scale && measurements
+        ? { ...value, ...identity, ...scale, ...measurements }
+        : undefined;
 }
 export async function collectScreenshotSample(options) {
-    if (options.command[0] !== "screenshot" || options.signal?.aborted)
+    if (options.command[0] !== "screenshot" || options.signal?.aborted === true) {
         return undefined;
+    }
     const { selector } = getScreenshotCapture(options.command);
     const script = `(() => {
 		const root = document.documentElement, body = document.body, v = window.visualViewport;
@@ -37,47 +83,124 @@ export async function collectScreenshotSample(options) {
 			visualViewport: { x: v?.offsetLeft ?? 0, y: v?.offsetTop ?? 0, scale: v?.scale ?? 1 }, element };
 	})()`;
     try {
-        const data = await runSessionCommandData({ ...options, args: ["eval", "--stdin"], stdin: script, timeoutMs: 2_000 });
-        const sample = isRecord(data) ? data.result : undefined;
-        if (!isRecord(sample) || (sample.rendering !== undefined && sample.rendering !== "text") || typeof sample.url !== "string" || !["main", "child"].includes(String(sample.frame))
-            || !finiteRecord(sample.viewport, ["width", "height"]) || !finiteRecord(sample.document, ["width", "height"])
-            || !finiteRecord(sample.scroll, ["x", "y"]) || !finiteRecord(sample.visualViewport, ["x", "y", "scale"])
-            || typeof sample.childFrameCount !== "number" || !Number.isInteger(sample.childFrameCount) || sample.childFrameCount < 0
-            || typeof sample.dpr !== "number" || !Number.isFinite(sample.dpr) || sample.dpr <= 0
-            || (sample.element !== undefined && !finiteRecord(sample.element, ["x", "y", "width", "height"])))
-            return undefined;
-        return sample;
+        const data = await runSessionCommandData({
+            ...options,
+            args: ["eval", "--stdin"],
+            stdin: script,
+            timeoutMs: 2_000,
+        });
+        return parseScreenshotSample(isRecord(data) ? data.result : undefined);
     }
     catch {
         return undefined;
     }
 }
+function getMeasuredCrop(capture, before) {
+    if (capture === "viewport") {
+        return { ...before.scroll, ...before.viewport };
+    }
+    if (capture === "full-page") {
+        return { x: 0, y: 0, ...before.document };
+    }
+    if (capture === "element" &&
+        before.element &&
+        before.childFrameCount === 0 &&
+        before.scroll.x === 0 &&
+        before.scroll.y === 0) {
+        return before.element;
+    }
+    return undefined;
+}
+function pixelsMatchCrop(crop, pixels, dpr) {
+    return (crop.width > 0 &&
+        crop.height > 0 &&
+        crop.x >= 0 &&
+        crop.y >= 0 &&
+        Object.values(crop).every(Number.isInteger) &&
+        pixels.width === crop.width * dpr &&
+        pixels.height === crop.height * dpr);
+}
+function sampleFrameFailure(before) {
+    if (before.frame !== "main") {
+        return "Probe observed a child frame; its relation to the captured page is unknown.";
+    }
+    if (before.visualViewport.scale !== 1 ||
+        before.visualViewport.x !== 0 ||
+        before.visualViewport.y !== 0) {
+        return "Visual viewport is zoomed or offset; capture origin is unknown.";
+    }
+    return undefined;
+}
+function geometrySampleFailure(options) {
+    const { before, after } = options;
+    if (options.rendering === "text" || before?.rendering === "text" || after?.rendering === "text") {
+        return LIGHTPANDA_IMAGE_REASON;
+    }
+    if (!before || !after) {
+        return "Capture was not bracketed by browser geometry samples; coordinates are unknown.";
+    }
+    if (JSON.stringify(before) !== JSON.stringify(after)) {
+        return "Browser geometry changed across capture; no coordinate mapping is asserted.";
+    }
+    return sampleFrameFailure(before);
+}
 export function buildScreenshotGeometry(options) {
     const { before, after, capture, pixels } = options;
-    const unknown = (reason) => ({ status: "unknown", reason, before, after });
-    if (options.rendering === "text" || before?.rendering === "text" || after?.rendering === "text")
-        return unknown(LIGHTPANDA_IMAGE_REASON);
-    if (!before || !after)
-        return unknown("Capture was not bracketed by browser geometry samples; coordinates are unknown.");
-    if (JSON.stringify(before) !== JSON.stringify(after))
-        return unknown("Browser geometry changed across capture; no coordinate mapping is asserted.");
-    if (before.frame !== "main")
-        return unknown("Probe observed a child frame; its relation to the captured page is unknown.");
-    if (before.visualViewport.scale !== 1 || before.visualViewport.x !== 0 || before.visualViewport.y !== 0)
-        return unknown("Visual viewport is zoomed or offset; capture origin is unknown.");
-    let crop;
-    if (capture === "viewport")
-        crop = { ...before.scroll, ...before.viewport };
-    else if (capture === "full-page")
-        crop = { x: 0, y: 0, ...before.document };
-    else if (capture === "element" && before.element && before.childFrameCount === 0 && before.scroll.x === 0 && before.scroll.y === 0)
-        crop = before.element;
-    else
+    const unknown = (reason) => ({
+        status: "unknown",
+        reason,
+        before,
+        after,
+    });
+    const sampleFailure = geometrySampleFailure(options);
+    if (sampleFailure !== undefined || !before || !after) {
+        return unknown(sampleFailure ??
+            "Capture was not bracketed by browser geometry samples; coordinates are unknown.");
+    }
+    const crop = getMeasuredCrop(capture, before);
+    if (!crop) {
         return unknown("Element crop/frame provenance is unverified (scrolled page, child frames, non-CSS selector, or ambiguous target).");
-    if (!pixels || crop.width <= 0 || crop.height <= 0 || crop.x < 0 || crop.y < 0
-        || !Object.values(crop).every(Number.isInteger)
-        || pixels.width !== crop.width * before.dpr || pixels.height !== crop.height * before.dpr)
+    }
+    if (!pixels || !pixelsMatchCrop(crop, pixels, before.dpr)) {
         return unknown("Image dimensions do not establish the sampled CSS crop at this DPR.");
-    return { status: "measured", before, after, crop, pixelsPerCssPixel: { x: pixels.width / crop.width, y: pixels.height / crop.height },
-        reason: "Matching pre/post samples, not an atomic capture guarantee. Pixels map to CSS document coordinates within crop; native mouse uses current viewport CSS coordinates. Recheck scroll/frame before input." };
+    }
+    return {
+        status: "measured",
+        before,
+        after,
+        crop,
+        pixelsPerCssPixel: { x: pixels.width / crop.width, y: pixels.height / crop.height },
+        reason: "Matching pre/post samples, not an atomic capture guarantee. Pixels map to CSS document coordinates within crop; native mouse uses current viewport CSS coordinates. Recheck scroll/frame before input.",
+    };
+}
+function observationCapture(value) {
+    switch (value) {
+        case "viewport":
+        case "full-page":
+        case "element":
+            return value;
+        default:
+            return "unknown";
+    }
+}
+export function annotateScreenshotImageObservations(observations, samples) {
+    const images = [];
+    for (const image of observations) {
+        if (!isRecord(image)) {
+            images.push(image);
+            continue;
+        }
+        const rendering = image.rendering ?? samples.before?.rendering ?? samples.after?.rendering;
+        images.push({
+            ...image,
+            ...(rendering !== undefined ? { rendering } : {}),
+            geometry: buildScreenshotGeometry({
+                rendering: rendering === "text" ? rendering : undefined,
+                capture: observationCapture(image.capture),
+                pixels: finiteRecord(image.pixels, ["width", "height"]) ? image.pixels : undefined,
+                ...samples,
+            }),
+        });
+    }
+    return images;
 }

package/dist/extensions/agent-browser/lib/orchestration/browser-run/session-state-commands.js

@@ -0,0 +1,130 @@
+import { AsyncLocalStorage } from "node:async_hooks";
+import { rm } from "node:fs/promises";
+import { parseArgvDescriptor } from "../../argv-descriptor.js";
+import { isBrowserIndependentRead, needsManagedSession } from "../../command-policy.js";
+import { isRecord } from "../../parsing.js";
+import { runAgentBrowserProcess } from "../../process.js";
+import { detectConfirmationRequired } from "../../results/confirmation.js";
+import { parseAgentBrowserEnvelope } from "../../results/envelope.js";
+import { observeNativeWebMcp } from "../../webmcp-observation.js";
+const sessionCommandObservation = new AsyncLocalStorage();
+export function withSessionCommandObservation(observer, run) {
+    return sessionCommandObservation.run(observer, run);
+}
+function isNativeParseFailure(envelope) {
+    if (envelope?.success !== false ||
+        !isRecord(envelope.data) ||
+        Object.keys(envelope.data).length !== 1) {
+        return false;
+    }
+    return (typeof envelope.data.type === "string" &&
+        [
+            "unknown_command",
+            "unknown_subcommand",
+            "missing_arguments",
+            "invalid_value",
+            "invalid_session_name",
+        ].includes(envelope.data.type));
+}
+function isSessionlessLocalCommand(commandTokens) {
+    return (commandTokens !== undefined &&
+        !needsManagedSession(parseArgvDescriptor(commandTokens)) &&
+        !isBrowserIndependentRead(commandTokens));
+}
+export function nativePolicyDefinitelyUnestablished(result, envelope, commandTokens) {
+    if (isSessionlessLocalCommand(commandTokens)) {
+        return true;
+    }
+    if (!result.agentBrowserStarted) {
+        return true;
+    }
+    if (result.aborted ||
+        result.timedOut ||
+        result.spawnError !== undefined ||
+        result.exitCode !== 1) {
+        return false;
+    }
+    // Native CLI parse/config failures precede ensure_daemon; a failed executed action does not.
+    return (isNativeParseFailure(envelope) ||
+        (result.stdout.trim() === "" &&
+            /config file not found:|failed to load config from /.test(result.stderr)));
+}
+function processFailureReason(result) {
+    if (result.aborted) {
+        return "command was aborted";
+    }
+    if (result.spawnError !== undefined) {
+        return "process could not start";
+    }
+    if (result.exitCode !== 0) {
+        return `process exited with code ${result.exitCode}`;
+    }
+    return;
+}
+function structuredFailureReason(parsed) {
+    if ((parsed.parseError?.length ?? 0) > 0) {
+        return "returned invalid structured output";
+    }
+    if (parsed.envelope?.success === false || detectConfirmationRequired(parsed.envelope?.data)) {
+        return "reported failure or requires confirmation";
+    }
+    return;
+}
+async function readSessionCommandResult(options, processResult) {
+    options.onProcessResult?.(processResult);
+    const parsed = await parseAgentBrowserEnvelope({
+        stdout: processResult.stdout,
+        stdoutPath: processResult.stdoutSpillPath,
+    });
+    sessionCommandObservation.getStore()?.observe(options, processResult, parsed.envelope);
+    const failure = processFailureReason(processResult) ?? structuredFailureReason(parsed);
+    if (failure !== undefined) {
+        if (options.throwOnFailure === true) {
+            throw new Error(`agent-browser ${failure}`);
+        }
+        return;
+    }
+    observeNativeWebMcp(parsed.envelope?.data);
+    return parsed.envelope?.data;
+}
+async function removeCommandSpill(path) {
+    if (path === undefined || path.length === 0) {
+        return;
+    }
+    try {
+        await rm(path, { force: true });
+    }
+    catch {
+        // The command result/parse error is authoritative. A private temporary stdout spill
+        // is disposable; failing to unlink it must not turn success into failure or mask
+        // the original exception. The process temp-root lifecycle also owns stale spills.
+    }
+}
+export async function runSessionCommandData(options) {
+    const { args, cwd, env, namespace, pinNamespace, sessionName, signal, stdin, timeoutMs } = options;
+    if (sessionName === undefined ||
+        sessionName.length === 0 ||
+        sessionCommandObservation.getStore()?.allow(options) === false) {
+        return;
+    }
+    const processResult = await runAgentBrowserProcess({
+        args: [
+            "--json",
+            ...(namespace !== undefined || pinNamespace === true ? ["--namespace", namespace ?? ""] : []),
+            "--session",
+            sessionName,
+            ...args,
+        ],
+        cwd,
+        env,
+        signal,
+        stdin,
+        timeoutMs,
+    });
+    try {
+        return await readSessionCommandResult(options, processResult);
+    }
+    finally {
+        await removeCommandSpill(processResult.stdoutSpillPath);
+    }
+}

package/dist/extensions/agent-browser/lib/orchestration/browser-run/session-state-electron.js

@@ -0,0 +1,212 @@
+import { getAgentBrowserSessionIdentityKey } from "../../argv-grammar.js";
+import { isElectronPostCommandHealthCommand } from "../../command-taxonomy.js";
+import { buildAgentBrowserNextActions } from "../../results/action-recommendations.js";
+import { isAboutBlankUrl, normalizeComparableUrl, } from "../../session-page-state.js";
+import { getGuardedRefUsage } from "./session-state-refs.js";
+import { presentElectronManagedSessionTarget } from "./final-result-electron.js";
+export function isLiveElectronRendererTarget(target) {
+    const normalizedUrl = normalizeComparableUrl(target.url);
+    if (normalizedUrl === undefined ||
+        normalizedUrl.length === 0 ||
+        normalizedUrl === "about:blank" ||
+        normalizedUrl.startsWith("devtools://")) {
+        return false;
+    }
+    return target.type === undefined || target.type === "page" || target.type === "webview";
+}
+export function getLiveElectronRendererTargets(targets) {
+    return targets.filter(isLiveElectronRendererTarget);
+}
+export function electronTargetLabel(target) {
+    if (!target) {
+        return "unknown target";
+    }
+    return ([target.title, target.url, target.id].find((value) => typeof value === "string" && value.trim().length > 0) ?? "unknown target");
+}
+export function getActiveElectronRecords(records) {
+    return [...records.values()].filter((record) => ["active", "dead", "partial", "failed"].includes(record.cleanupState));
+}
+export function findElectronLaunchRecordForSession(sessionName, records, namespace) {
+    if (sessionName === undefined || sessionName.length === 0) {
+        return;
+    }
+    const sessionKey = getAgentBrowserSessionIdentityKey(sessionName, namespace);
+    return getActiveElectronRecords(records).find((record) => (record.sessionName?.length ?? 0) > 0 &&
+        getAgentBrowserSessionIdentityKey(record.sessionName ?? "", record.namespace) === sessionKey);
+}
+function buildElectronReattachNextAction(record, liveTarget) {
+    const endpoint = liveTarget?.webSocketDebuggerUrl ?? record.webSocketDebuggerUrl ?? String(record.port);
+    return {
+        id: "reattach-electron-launch",
+        params: { args: ["connect", endpoint], sessionMode: "fresh" },
+        reason: "Attach a fresh managed session to the same wrapper-tracked Electron debug endpoint when the current session no longer matches the live renderer.",
+        safety: "Creates a new managed browser session; it does not mutate the Electron app. Keep the launchId for later status and cleanup.",
+        tool: "agent_browser",
+    };
+}
+export function buildElectronLifecycleNextActions(record) {
+    return (buildAgentBrowserNextActions({
+        electron: {
+            launchId: record.launchId,
+            sessionName: record.sessionName,
+            status: record.cleanupState,
+        },
+        resultCategory: "success",
+        successCategory: "completed",
+    }) ?? []);
+}
+export function buildElectronMismatchNextActions(record, liveTarget) {
+    const reattachAction = buildElectronReattachNextAction(record, liveTarget);
+    const actions = [];
+    for (const action of buildElectronLifecycleNextActions(record)) {
+        actions.push(action);
+        if (action.id === "probe-electron-launch") {
+            actions.push(reattachAction);
+        }
+    }
+    if (!actions.some((action) => action.id === reattachAction.id)) {
+        actions.push(reattachAction);
+    }
+    return actions;
+}
+function getElectronMismatchReason(managedSession, recordSessionName) {
+    if (isAboutBlankUrl(managedSession.url)) {
+        return "managed-session-about-blank-while-launch-target-live";
+    }
+    if ((recordSessionName?.length ?? 0) > 0 && recordSessionName !== managedSession.sessionName) {
+        return "launch-session-not-current";
+    }
+    if ((normalizeComparableUrl(managedSession.url)?.length ?? 0) > 0) {
+        return "managed-session-target-not-in-launch-status";
+    }
+    return;
+}
+function describeElectronMismatch(managedSession, record, liveTarget, reason) {
+    const managedDescription = managedSession.url ?? managedSession.title ?? managedSession.sessionName;
+    const liveDescription = electronTargetLabel(liveTarget);
+    return reason === "launch-session-not-current"
+        ? `Electron session mismatch: current managed session ${managedSession.sessionName} is not the wrapper launch session ${record.sessionName ?? "unknown"}, while launch ${record.launchId} still has live target ${liveDescription}.`
+        : `Electron session mismatch: managed session ${managedSession.sessionName} is on ${managedDescription}, but launch ${record.launchId} still has live target ${liveDescription}.`;
+}
+export function buildElectronSessionMismatch(options) {
+    const liveTargets = getLiveElectronRendererTargets(options.statusTargets);
+    if (liveTargets.length === 0) {
+        return;
+    }
+    const managedUrl = normalizeComparableUrl(options.managedSession.url);
+    const matchingLiveTarget = (managedUrl?.length ?? 0) > 0
+        ? liveTargets.find((target) => normalizeComparableUrl(target.url) === managedUrl)
+        : undefined;
+    if (matchingLiveTarget) {
+        return;
+    }
+    const liveTarget = liveTargets[0];
+    const reason = getElectronMismatchReason(options.managedSession, options.record.sessionName);
+    if (reason === undefined) {
+        return;
+    }
+    const nextActions = buildElectronMismatchNextActions(options.record, liveTarget);
+    const managedSession = presentElectronManagedSessionTarget(options.managedSession);
+    return {
+        launchId: options.record.launchId,
+        liveTarget,
+        managedSession,
+        nextActionIds: nextActions.map((action) => action.id),
+        reason,
+        sessionName: options.record.sessionName,
+        statusTargets: options.statusTargets,
+        summary: describeElectronMismatch(managedSession, options.record, liveTarget, reason),
+    };
+}
+export function formatElectronSessionMismatchText(mismatch) {
+    return `${mismatch.summary}\nNext: run electron.status/electron.probe with launchId ${mismatch.launchId}, reattach with the reattach-electron-launch nextAction if needed, or cleanup when finished.`;
+}
+export function shouldInspectElectronPostCommandHealth(command) {
+    return isElectronPostCommandHealthCommand(command);
+}
+function getElectronHealthReason(status, targetUrl) {
+    if (status.pidAlive === false) {
+        return "process-dead";
+    }
+    if (!status.portAlive) {
+        return "debug-port-dead";
+    }
+    if (isAboutBlankUrl(targetUrl) && getLiveElectronRendererTargets(status.targets).length === 0) {
+        return "about-blank-no-live-target";
+    }
+    return;
+}
+function formatElectronHealthStatus(status) {
+    const portText = status.portAlive ? "debug port alive" : "debug port dead";
+    if (status.pidAlive === undefined) {
+        return portText;
+    }
+    return `${portText}${status.pidAlive ? ", pid alive" : ", pid dead"}`;
+}
+export function buildElectronPostCommandHealthDiagnostic(options) {
+    const reason = getElectronHealthReason(options.status, options.target?.url);
+    if (reason === undefined) {
+        return;
+    }
+    const nextActions = buildElectronLifecycleNextActions(options.record);
+    const commandText = (options.command?.length ?? 0) > 0 ? `${options.command ?? ""} command` : "command";
+    return {
+        appName: options.record.appName,
+        command: options.command,
+        launchId: options.record.launchId,
+        nextActionIds: nextActions.map((action) => action.id),
+        reason,
+        sessionName: options.record.sessionName,
+        status: options.status,
+        summary: `Electron lifecycle warning: ${commandText} completed, but launch ${options.record.launchId} is no longer healthy (${formatElectronHealthStatus(options.status)}).`,
+        target: options.target,
+    };
+}
+export function formatElectronPostCommandHealthText(diagnostic) {
+    if (!diagnostic) {
+        return;
+    }
+    const lines = [diagnostic.summary];
+    if ((diagnostic.target?.url.length ?? 0) > 0) {
+        lines.push(`Current browser session target: ${diagnostic.target?.url ?? ""}.`);
+    }
+    lines.push(`Status: ${formatElectronHealthStatus(diagnostic.status)}; ${diagnostic.status.targets.length} CDP target(s).`, `Next: run electron.status/electron.probe with launchId ${diagnostic.launchId}, cleanup the wrapper-owned launch if dead, or relaunch the app.`);
+    return lines.join("\n");
+}
+export function buildElectronIdentifiers(record) {
+    return { appName: record.appName, launchId: record.launchId, sessionName: record.sessionName };
+}
+export function buildElectronRefFreshnessNextActions(sessionName) {
+    return [
+        {
+            id: "refresh-electron-refs-after-rerender",
+            params: {
+                args: (sessionName?.length ?? 0) > 0
+                    ? ["--session", sessionName ?? "", "snapshot", "-i"]
+                    : ["snapshot", "-i"],
+            },
+            reason: "Electron UIs often rerender without changing URL; refresh refs before using old @e handles again.",
+            safety: "Read-only snapshot; avoids stale same-URL refs after quick-pick, modal, theme, or editor rerenders.",
+            tool: "agent_browser",
+        },
+    ];
+}
+export function buildElectronRefFreshnessDiagnostic(options) {
+    if (!options.record || !shouldInspectElectronPostCommandHealth(options.command)) {
+        return;
+    }
+    if (getGuardedRefUsage(options.commandTokens, options.stdin).length === 0) {
+        return;
+    }
+    const nextActions = buildElectronRefFreshnessNextActions(options.sessionName);
+    return {
+        command: options.command,
+        launchId: options.record.launchId,
+        nextActionIds: nextActions.map((action) => action.id),
+        sessionName: options.sessionName,
+        summary: `Electron ref freshness: ${options.command ?? "mutation"} used page-scoped refs in an Electron UI. Re-run snapshot -i before reusing old @e refs, even if the URL did not change.`,
+    };
+}
+export function formatElectronRefFreshnessText(diagnostic) {
+    return diagnostic?.summary;
+}

package/dist/extensions/agent-browser/lib/orchestration/browser-run/session-state-observations.js

@@ -0,0 +1,61 @@
+import { isNavigationObservableCommandName } from "../../command-taxonomy.js";
+import { isRecord } from "../../parsing.js";
+export function extractStringResultField(data, fieldName) {
+    if (typeof data === "string") {
+        if (fieldName === "value") {
+            return data;
+        }
+        const text = data.trim();
+        return text.length > 0 ? text : undefined;
+    }
+    if (!isRecord(data) || typeof data[fieldName] !== "string") {
+        return;
+    }
+    if (fieldName === "value") {
+        return data[fieldName];
+    }
+    const text = data[fieldName].trim();
+    return text.length > 0 ? text : undefined;
+}
+export function extractNavigationSummaryFromData(data) {
+    const result = isRecord(data) && isRecord(data.result) ? data.result : data;
+    const title = extractStringResultField(result, "title");
+    const url = extractStringResultField(result, "url");
+    const urlChanged = isRecord(result) && typeof result.urlChanged === "boolean" ? result.urlChanged : undefined;
+    return Boolean(title) || Boolean(url) ? { title, url, urlChanged } : undefined;
+}
+function isConfirmedNavigationWithoutUrl(data) {
+    return (isRecord(data) &&
+        data.confirmed === true &&
+        data.action === "navigate" &&
+        isRecord(data.result) &&
+        data.result.success === true &&
+        extractStringResultField(data.result.data, "url") === undefined);
+}
+export function shouldCaptureNavigationSummary(command, data, subcommand) {
+    if (command === "eval") {
+        return true;
+    }
+    // A completed compound action may navigate without returning a URL (e.g. recording restart).
+    if (command === "confirm" && isConfirmedNavigationWithoutUrl(data)) {
+        return true;
+    }
+    return (isNavigationObservableCommandName(command, subcommand) &&
+        (!isRecord(data) || (typeof data.title !== "string" && typeof data.url !== "string")));
+}
+export function mergeNavigationSummaryIntoData(data, navigationSummary) {
+    return isRecord(data) ? { ...data, navigationSummary } : { navigationSummary, result: data };
+}
+export function buildAboutBlankRecoveryHint() {
+    return "agent_browser detected that the active tab became about:blank while this session still had a prior intended tab. Run tab list for this session and re-select the intended tab, or retry with sessionMode=fresh if the tab is gone.";
+}
+export function buildAboutBlankWarning(mismatch) {
+    return `Warning: agent_browser detected that this session returned about:blank while the prior intended tab was ${mismatch.targetUrl}. ${mismatch.recoveryApplied ? "The wrapper re-selected the intended tab for the session." : "No matching tab could be re-selected; run tab list for the same session or retry with sessionMode=fresh."}`;
+}
+export function extractBatchResultCommand(item) {
+    if (!Array.isArray(item.command)) {
+        return [];
+    }
+    const tokens = item.command;
+    return tokens.filter((token) => typeof token === "string");
+}