pi-agent-browser-native 0.2.77 → 0.5.0

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,13 +1,6 @@
-/**
- * Purpose: Build generic nextAction recommendations from result categories, artifacts, Electron lifecycle state, and recovery context.
- * Responsibilities: Preserve stable action ids/order while keeping recommendation policy out of generic shared helpers.
- * Scope: Generic result-level recommendations only; feature-specific diagnostics append their own actions in the extension entrypoint.
- * Usage: Called by presentation and extension result assembly.
- * Invariants/Assumptions: Action ids are public machine-readable contracts; preserve first-observed order.
- */
 import { isOpenNavigationCommand, isPageMutationCommand } from "../command-taxonomy.js";
-import { isPendingRecordingArtifact } from "./artifact-state.js";
-import { buildNextToolAction } from "./next-actions.js";
+import { isPendingRecordingArtifact } from "./artifact-manifest.js";
+import { applySessionToNextActions, buildNextToolAction } from "./next-actions.js";
 import { AGENT_BROWSER_RECOVERY_NEXT_ACTION_IDS, buildRecoveryNextActions, } from "./recovery-actions.js";
 function buildArtifactAction(path) {
     return {
@@ -127,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({
@@ -153,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({
@@ -203,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;
@@ -216,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);
 }

package/dist/extensions/agent-browser/lib/results/artifact-manifest.js

@@ -1,11 +1,11 @@
-/**
- * Purpose: Own persistent session artifact manifest merge, retention, and validation logic.
- * Responsibilities: Parse manifest bounds, recognize manifest entries, merge new artifact rows, and format retention summaries.
- * Scope: Manifest accounting only; artifact detection and presentation live in presentation modules.
- * Usage: Imported by presentation and snapshot artifact persistence paths.
- * Invariants/Assumptions: Explicit-path artifacts are host-owned while persistent-session spill files are bounded by the manifest cap.
- */
+import { getAgentBrowserSessionIdentityKey } from "../argv-grammar.js";
 import { isRecord } from "../parsing.js";
+export function isPendingRecordingCommand(command, subcommand, kind) {
+    return command === "record" && (subcommand === "start" || subcommand === "restart") && kind === "video";
+}
+export function isPendingRecordingArtifact(artifact) {
+    return isPendingRecordingCommand(artifact.command, artifact.subcommand, artifact.kind);
+}
 export const SESSION_ARTIFACT_MANIFEST_VERSION = 1;
 export const SESSION_ARTIFACT_MANIFEST_MAX_ENTRIES_ENV = "PI_AGENT_BROWSER_SESSION_ARTIFACT_MANIFEST_MAX_ENTRIES";
 export const DEFAULT_SESSION_ARTIFACT_MANIFEST_MAX_ENTRIES = 100;
@@ -33,6 +33,16 @@ function isManifestEntry(value) {
         return false;
     if (typeof value.kind !== "string" || value.kind.trim().length === 0)
         return false;
+    for (const key of ["absolutePath", "command", "cwd", "extension", "mediaType", "namespace", "requestedPath", "session", "subcommand"]) {
+        if (value[key] !== undefined && typeof value[key] !== "string")
+            return false;
+    }
+    if (value.evictedAtMs !== undefined && (typeof value.evictedAtMs !== "number" || !Number.isFinite(value.evictedAtMs)))
+        return false;
+    if (value.exists !== undefined && typeof value.exists !== "boolean")
+        return false;
+    if (value.sizeBytes !== undefined && (typeof value.sizeBytes !== "number" || !Number.isFinite(value.sizeBytes) || value.sizeBytes < 0))
+        return false;
     return true;
 }
 export function isSessionArtifactManifest(value) {
@@ -74,7 +84,34 @@ export function formatSessionArtifactRetentionSummary(manifest) {
     return `Session artifacts: ${parts.join(", ")} (${manifest.entries.length}/${manifest.maxEntries} recent).`;
 }
 export function getSessionArtifactManifestEntryKey(entry) {
-    return entry.storageScope === "explicit-path" && entry.absolutePath ? `${entry.storageScope}:${entry.absolutePath}` : `${entry.storageScope}:${entry.path}`;
+    const pathKey = entry.storageScope === "explicit-path" && entry.absolutePath ? `${entry.storageScope}:${entry.absolutePath}` : `${entry.storageScope}:${entry.path}`;
+    const recordingSessionKey = entry.command === "record" && entry.kind === "video" && entry.session
+        ? getAgentBrowserSessionIdentityKey(entry.session, entry.namespace)
+        : undefined;
+    return recordingSessionKey ? `${pathKey}\0${recordingSessionKey}` : pathKey;
+}
+export function retirePendingRecordingManifestEntries(manifest, sessionName, namespace, nowMs = Date.now()) {
+    let changed = false;
+    const sessionKey = sessionName ? getAgentBrowserSessionIdentityKey(sessionName, namespace) : undefined;
+    const entries = manifest.entries.map((entry) => {
+        if (!sessionKey
+            || !entry.session
+            || getAgentBrowserSessionIdentityKey(entry.session, entry.namespace) !== sessionKey
+            || entry.kind !== "video"
+            || !isPendingRecordingCommand(entry.command, entry.subcommand, entry.kind))
+            return entry;
+        changed = true;
+        return { ...entry, retentionState: "missing", subcommand: "close-abandoned" };
+    });
+    if (!changed)
+        return manifest;
+    return {
+        ...manifest,
+        entries,
+        evictedCount: entries.filter((entry) => entry.retentionState === "evicted").length,
+        liveCount: entries.filter((entry) => entry.retentionState === "live").length,
+        updatedAtMs: nowMs,
+    };
 }
 export function mergeSessionArtifactManifest(options) {
     const nowMs = options.nowMs ?? Date.now();
@@ -83,13 +120,31 @@ export function mergeSessionArtifactManifest(options) {
     for (const entry of options.base?.entries ?? []) {
         byPath.set(getSessionArtifactManifestEntryKey(entry), entry);
     }
-    for (const entry of options.entries ?? []) {
+    const orderedEntries = (options.entries ?? [])
+        .map((entry, index) => ({ entry, index }))
+        .sort((left, right) => left.entry.createdAtMs - right.entry.createdAtMs || left.index - right.index)
+        .map(({ entry }) => entry);
+    for (const entry of orderedEntries) {
         const key = getSessionArtifactManifestEntryKey(entry);
+        if (entry.command === "record" && entry.kind === "video") {
+            const entrySessionKey = entry.session ? getAgentBrowserSessionIdentityKey(entry.session, entry.namespace) : undefined;
+            for (const [candidateKey, candidate] of byPath) {
+                const sameRecordingSession = entrySessionKey === undefined
+                    ? candidate.session === undefined
+                    : candidate.session !== undefined && getAgentBrowserSessionIdentityKey(candidate.session, candidate.namespace) === entrySessionKey;
+                if (candidateKey !== key
+                    && sameRecordingSession
+                    && candidate.kind === "video"
+                    && isPendingRecordingCommand(candidate.command, candidate.subcommand, candidate.kind)) {
+                    byPath.delete(candidateKey);
+                }
+            }
+        }
         const existing = byPath.get(key);
         byPath.set(key, {
             ...existing,
             ...entry,
-            createdAtMs: existing?.createdAtMs ?? entry.createdAtMs,
+            createdAtMs: entry.command === "record" && entry.kind === "video" ? entry.createdAtMs : existing?.createdAtMs ?? entry.createdAtMs,
             evictedAtMs: entry.retentionState === "evicted" ? (entry.evictedAtMs ?? nowMs) : entry.evictedAtMs,
         });
     }
@@ -99,7 +154,9 @@ export function mergeSessionArtifactManifest(options) {
         .sort((left, right) => {
         const leftTime = left.evictedAtMs ?? left.createdAtMs;
         const rightTime = right.evictedAtMs ?? right.createdAtMs;
-        return rightTime - leftTime || left.path.localeCompare(right.path);
+        return rightTime - leftTime
+            || Number(isPendingRecordingCommand(right.command, right.subcommand, right.kind)) - Number(isPendingRecordingCommand(left.command, left.subcommand, left.kind))
+            || left.path.localeCompare(right.path);
     })
         .slice(0, maxEntries);
     return {

package/dist/extensions/agent-browser/lib/results/categories.js

@@ -1,17 +1,12 @@
-/**
- * Purpose: Classify successful and failed agent-browser outcomes into stable result categories.
- * Responsibilities: Map artifacts, inspection calls, errors, refs, selectors, downloads, drift, and timeouts to small enums.
- * Scope: Category policy only; next-action recommendations and presentation formatting live elsewhere.
- * Usage: Called by presentation and extension result assembly before details are exposed to Pi.
- * Invariants/Assumptions: Category strings are public machine-readable contracts covered by tests and docs.
- */
-import { isPendingRecordingArtifact } from "./artifact-state.js";
+import { isPendingRecordingArtifact } from "./artifact-manifest.js";
 function hasUnverifiedFileArtifact(artifacts) {
     return (artifacts ?? []).some((artifact) => !isPendingRecordingArtifact(artifact) && artifact.exists !== true);
 }
 export function classifyAgentBrowserSuccessCategory(options) {
     if (options.inspection)
         return "inspection";
+    if ((options.artifacts ?? []).some(isPendingRecordingArtifact))
+        return "artifact-pending";
     if ((options.artifacts ?? []).length > 0)
         return hasUnverifiedFileArtifact(options.artifacts) ? "artifact-unverified" : "artifact-saved";
     if (options.savedFile)
@@ -26,6 +21,9 @@ export function classifyAgentBrowserFailureCategory(options) {
     // missed control named "Confirmation required" still gets selector recovery.
     if (options.confirmationRequired)
         return "confirmation-required";
+    // Canonical upstream prefix first: lastUrl can contain aborted / policy-blocked / about:blank.
+    if (/\btab_gone:/i.test(text))
+        return "tab-gone";
     // Upstream 0.32.4+ locator misses keep detail and may echo getByRole/getByText or Names seen lists.
     // Evaluate before text-derived timeout/confirmation so accessible-name substrings cannot suppress recovery.
     const isUpstreamLocatorMiss = /\bNo element found:\s*(?:getBy[A-Za-z]+|role=|text=|label=|placeholder=|alt=|title=|testid=)/i.test(text) ||
@@ -55,7 +53,7 @@ export function classifyAgentBrowserFailureCategory(options) {
         return "policy-blocked";
     if (/cleanup failed|cleanup.*partial|partial cleanup|remaining resources/i.test(text))
         return "cleanup-failed";
-    if (options.validationError)
+    if (options.validationError || /Agent-browser Unix socket path would be|Agent-browser socket storage .* is unusable/i.test(text))
         return "validation-error";
     if (options.tabDrift || /could not re-select the intended tab|about:blank|selected tab looks wrong|tab drift|tab.*wrong/i.test(text))
         return "tab-drift";

package/dist/extensions/agent-browser/lib/results/confirmation.js

@@ -1,10 +1,3 @@
-/**
- * Purpose: Detect upstream guarded-action confirmation-needed result shapes without creating wrapper-owned confirmation state.
- * Responsibilities: Recognize confirmation-required markers, extract the pending upstream confirmation id, and optionally surface a short upstream action label.
- * Scope: Pure result-shape detection shared by presentation and error derivation; command execution, approval state, and redaction stay in their existing modules.
- * Usage: Imported by result presentation to render recovery commands and by envelope error handling to avoid hiding actionable confirmation payloads behind generic failure text.
- * Invariants/Assumptions: Detection must be conservative: a confirmation marker and a non-empty upstream id are both required before a result is treated as actionable.
- */
 import { isRecord } from "../parsing.js";
 const CONFIRMATION_REQUIRED_FIELD_NAMES = [
     "confirmation_required",

package/dist/extensions/agent-browser/lib/results/contracts.js

@@ -1,8 +1 @@
-/**
- * Purpose: Define stable result-rendering data contracts shared across focused result modules.
- * Responsibilities: Keep upstream envelope, presentation, artifact, category, and network shapes in one type-only surface.
- * Scope: Types only; runtime classifiers, manifests, network rules, and text helpers live in neighboring modules.
- * Usage: Imported with `import type` by result modules and re-exported by the public results facade.
- * Invariants/Assumptions: This file has no runtime policy so adding fields cannot hide behavior in a catch-all module.
- */
 export {};

package/dist/extensions/agent-browser/lib/results/editable-ref-evidence.js

@@ -1,10 +1,3 @@
-/**
- * Purpose: Detect whether upstream ref metadata or snapshot text proves an element is editable.
- * Responsibilities: Parse structured ref flags and snapshot-line contenteditable/editable markers into a conservative boolean/unknown signal.
- * Scope: Editable evidence only; callers decide how to rank controls or build recovery actions from the signal.
- * Usage: Imported by snapshot compaction and selector/fill recovery diagnostics.
- * Invariants/Assumptions: Explicit false evidence wins over positive hints; unknown remains undefined.
- */
 const EDITABLE_REF_EVIDENCE_KEYS = ["editable", "contentEditable", "contenteditable", "isContentEditable"];
 const EDITABLE_FALSE_TEXT_PATTERN = /\b(?:contenteditable|editable)\s*=\s*["']?(?:false|0)["']?/i;
 const EDITABLE_ASSIGNMENT_TEXT_PATTERN = /\b(contenteditable|editable)\s*=\s*("[^"]*"|'[^']*'|[^\s,\]]+)/gi;

package/dist/extensions/agent-browser/lib/results/envelope.js

@@ -1,10 +1,3 @@
-/**
- * Purpose: Parse upstream agent-browser output and turn failure envelopes into actionable error text.
- * Responsibilities: Read inline or spilled stdout, parse observed JSON envelope shapes, normalize batch arrays, and extract the most useful error text from nested upstream failures.
- * Scope: Envelope parsing and error derivation only; content rendering and snapshot compaction live in separate modules.
- * Usage: Imported by the public `lib/results.ts` facade and by tests through that facade.
- * Invariants/Assumptions: Upstream `agent-browser --json` responses follow the observed `{ success, data, error }` envelope shape or the array shape returned by `batch --json`.
- */
 import { readFile } from "node:fs/promises";
 import { isRecord } from "../parsing.js";
 import { detectConfirmationRequired } from "./confirmation.js";

package/dist/extensions/agent-browser/lib/results/network.js

@@ -1,10 +1,3 @@
-/**
- * Purpose: Classify failed network requests into actionable vs benign diagnostics.
- * Responsibilities: Recognize failed request rows, de-prioritize browser icon misses, and summarize failure counts.
- * Scope: Network diagnostic classification only.
- * Usage: QA preset analysis and presentation network summaries.
- * Invariants/Assumptions: Browser favicon/apple-touch icon misses are warnings; API/document/script failures are actionable.
- */
 import { isRecord } from "../parsing.js";
 export function getStringRecordField(value, key) {
     const field = value[key];

package/dist/extensions/agent-browser/lib/results/next-actions.js

@@ -1,22 +1,15 @@
-/**
- * Purpose: Own machine-readable agent_browser next-action contracts and merge policy.
- * Responsibilities: Define the stable nextAction shape, build basic argv follow-ups, and provide deterministic action-list collection helpers.
- * Scope: Result follow-up action mechanics only; command-specific recovery and artifact policies live in neighboring modules.
- * Usage: Imported by result presentation helpers and the extension entrypoint when attaching details.nextActions.
- * Invariants/Assumptions: Action ids are stable machine-readable contracts; dedupe preserves first occurrence order.
- */
 export function withOptionalNamespaceArgs(namespace, args) {
-    return namespace && args[0] !== "--namespace" ? ["--namespace", namespace, ...args] : args;
+    return namespace !== undefined && args[0] !== "--namespace" ? ["--namespace", namespace, ...args] : args;
 }
 export function withOptionalSessionArgs(sessionName, args) {
-    if (!sessionName || args[0] === "--session")
+    if (!sessionName || args[0] === "--session" || (args[0] === "--namespace" && args[2] === "--session"))
         return args;
-    if (args[0] === "--namespace" && args[1] && args[2] !== "--session")
+    if (args[0] === "--namespace" && args.length >= 2)
         return [args[0], args[1], "--session", sessionName, ...args.slice(2)];
     return ["--session", sessionName, ...args];
 }
 export function applyNamespaceToNextActions(actions, namespace) {
-    if (!namespace || !actions)
+    if (namespace === undefined || !actions)
         return actions;
     return actions.map((action) => {
         const args = action.params?.args;
@@ -26,6 +19,18 @@ export function applyNamespaceToNextActions(actions, namespace) {
         return networkSourceLookup ? { ...action, params: { ...action.params, networkSourceLookup: { ...networkSourceLookup, namespace } } } : action;
     });
 }
+export function applySessionToNextActions(actions, sessionName) {
+    if (!sessionName || !actions)
+        return actions;
+    return actions.map((action) => {
+        // Fresh-session actions deliberately target a new session; the planner ignores sessionMode when an
+        // explicit --session is present, so prefixing one here would silently downgrade them to reuse.
+        if (action.params?.sessionMode === "fresh")
+            return action;
+        const args = action.params?.args;
+        return args ? { ...action, params: { ...action.params, args: withOptionalSessionArgs(sessionName, args) } } : action;
+    });
+}
 export function buildNextToolAction(options) {
     return {
         id: options.id,
@@ -55,7 +60,9 @@ export function isStandaloneSnapshotNextAction(action) {
     const args = action.params?.args;
     if (!args || action.params?.stdin)
         return false;
-    const commandIndex = args[0] === "--session" ? 2 : 0;
+    let commandIndex = args[0] === "--namespace" ? 2 : 0;
+    if (args[commandIndex] === "--session")
+        commandIndex += 2;
     return args[commandIndex] === "snapshot";
 }
 export function alignPageChangeSummaryNextActionIds(summary, nextActions) {
@@ -65,26 +72,3 @@ export function alignPageChangeSummaryNextActionIds(summary, nextActions) {
     const alignedIds = summary.nextActionIds.filter((id) => nextActionIds.has(id));
     return alignedIds.length > 0 ? { ...summary, nextActionIds: alignedIds } : { ...summary, nextActionIds: undefined };
 }
-export class AgentBrowserNextActionCollector {
-    actions;
-    constructor(initialActions = undefined) {
-        this.actions = initialActions ? [...initialActions] : [];
-    }
-    append(actions) {
-        if (!actions || actions.length === 0)
-            return;
-        this.actions.push(...actions);
-    }
-    appendUnique(actions) {
-        appendUniqueAgentBrowserNextActions(this.actions, actions);
-    }
-    replace(actions) {
-        this.actions = actions ? [...actions] : [];
-    }
-    removeWhere(predicate) {
-        this.actions = this.actions.filter((action) => !predicate(action));
-    }
-    toArray() {
-        return this.actions.length > 0 ? [...this.actions] : undefined;
-    }
-}