pi-agent-browser-native 0.2.48 → 0.2.49

package/dist/extensions/agent-browser/lib/prompt-policy.js

@@ -0,0 +1,91 @@
+/**
+ * Purpose: Derive operator prompt constraints for browser-run preflight guards and legacy bash policy.
+ * Responsibilities: Parse the latest user message into requested artifact paths and legacy bash allowance.
+ * Scope: Pure prompt-text policy; enforcement lives in orchestration prompt-guards and the extension entrypoint.
+ */
+const BROWSER_PROMPT_PATTERNS = [
+    /\b(?:agent[_ -]?browser|browser automation|eval\s+--stdin|screenshot|snapshot|tab\s+list)\b/i,
+    /\b(?:react\s+(?:tree|inspect|renders|suspense)|web\s+vitals|core\s+web\s+vitals|pushstate)\b/i,
+    /\b(?:live\s+docs?|online\s+research|research\s+(?:online|the\s+web)|search\s+(?:online|the\s+web)|web\s+research)\b/i,
+    /\bbrowser\b.*\b(?:automation|click|fill|navigate|open|page|screenshot|site|snapshot|tab|url|visit|web(?:site| page)?)\b/i,
+    /\b(?:browse|click|fill|login|navigate|open|visit)\b.*\b(?:https?:\/\/\S+|page|site|tab|url|web(?:site| page)?)\b/i,
+];
+const LEGACY_BASH_ALLOW_PATTERNS = [
+    /\b(?:bash-oriented workflow|bash workflow)\b/i,
+    /\b(?:use|via|through|with)\s+bash\b/i,
+    /\bnpx\s+agent-browser\b/i,
+    /\bagent-browser\s+--(?:help|version)\b/i,
+    /\bdebug(?:ging)?\b.*\b(?:agent[_ -]?browser|agent_browser|browser integration)\b/i,
+];
+const PROMPT_ARTIFACT_PATH_PATTERN = /(?:^|[\s"'`(:])((?:\/[^\s"'`),;]+|[A-Za-z]:[\\/][^\s"'`),;]+|\.{1,2}[\\/][^\s"'`),;]+|[^\s"'`),;:\\/]+(?:[\\/][^\s"'`),;]+)+|[^\s"'`),;:\\/]+)\.(?:png|jpe?g|webp|gif|webm|mp4|har|pdf|trace|json))(?:[\s"'`),;.]|$)/gi;
+function extractPromptRequestedArtifacts(prompt) {
+    const artifacts = [];
+    const seen = new Set();
+    for (const line of prompt.split(/\r?\n/)) {
+        const lowerLine = line.toLowerCase();
+        const kind = lowerLine.includes("screenshot")
+            ? "screenshot"
+            : /\b(?:screen\s+recording|recording|webm|video)\b/.test(lowerLine)
+                ? "recording"
+                : undefined;
+        if (!kind)
+            continue;
+        PROMPT_ARTIFACT_PATH_PATTERN.lastIndex = 0;
+        for (const match of line.matchAll(PROMPT_ARTIFACT_PATH_PATTERN)) {
+            const path = match[1]?.trim();
+            if (!path)
+                continue;
+            const key = `${kind}:${path}`;
+            if (seen.has(key))
+                continue;
+            seen.add(key);
+            artifacts.push({
+                kind,
+                path,
+                required: kind === "screenshot" || !/\b(?:if|when)\s+(?:recording\s+)?(?:is\s+)?available\b/i.test(line),
+            });
+        }
+    }
+    return artifacts;
+}
+export function buildPromptPolicy(prompt) {
+    return {
+        allowLegacyAgentBrowserBash: LEGACY_BASH_ALLOW_PATTERNS.some((pattern) => pattern.test(prompt)),
+        requestedArtifacts: extractPromptRequestedArtifacts(prompt),
+    };
+}
+function getMessageText(content) {
+    if (typeof content === "string")
+        return content;
+    if (!Array.isArray(content))
+        return "";
+    return content
+        .map((item) => {
+        if (typeof item !== "object" || item === null)
+            return "";
+        return item.type === "text" && typeof item.text === "string" ? item.text : "";
+    })
+        .filter((text) => text.length > 0)
+        .join("\n");
+}
+export function shouldAppendBrowserSystemPrompt(prompt) {
+    const normalizedPrompt = prompt.trim();
+    if (normalizedPrompt.length === 0) {
+        return false;
+    }
+    return BROWSER_PROMPT_PATTERNS.some((pattern) => pattern.test(normalizedPrompt));
+}
+export function getLatestUserPrompt(branch) {
+    for (let index = branch.length - 1; index >= 0; index -= 1) {
+        const entry = branch[index];
+        if (typeof entry !== "object" || entry === null || !("type" in entry) || entry.type !== "message") {
+            continue;
+        }
+        const message = "message" in entry ? entry.message : undefined;
+        if (typeof message !== "object" || message === null || !("role" in message) || message.role !== "user") {
+            continue;
+        }
+        return getMessageText("content" in message ? message.content : undefined);
+    }
+    return "";
+}

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

@@ -0,0 +1,220 @@
+/**
+ * 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 { AGENT_BROWSER_RECOVERY_NEXT_ACTION_IDS, buildRecoveryNextActions, } from "./recovery-actions.js";
+function buildArtifactAction(path) {
+    return {
+        artifactPath: path,
+        id: "use-saved-artifact",
+        reason: "Use the saved artifact path from the structured result instead of scraping it from text.",
+        safety: "Verify artifact metadata such as exists/status before treating the file as durable.",
+        tool: "agent_browser",
+    };
+}
+function buildArtifactVerificationAction(artifact) {
+    return {
+        artifactPath: artifact.path,
+        id: "verify-artifact-path",
+        reason: "The wrapper has artifact metadata but did not verify this file as present on disk.",
+        safety: "Check details.artifactVerification and the filesystem before treating the artifact as durable.",
+        tool: "agent_browser",
+    };
+}
+function buildElectronToolAction(options) {
+    return {
+        id: options.id,
+        params: { electron: { action: options.action, launchId: options.launchId } },
+        reason: options.reason,
+        ...(options.safety ? { safety: options.safety } : {}),
+        tool: "agent_browser",
+    };
+}
+function getDownloadRetryPath(args, fallback) {
+    if (fallback)
+        return fallback;
+    if (!args || args.length === 0)
+        return undefined;
+    const downloadFlagIndex = args.indexOf("--download");
+    if (downloadFlagIndex >= 0) {
+        const candidate = args[downloadFlagIndex + 1];
+        return candidate && !candidate.startsWith("-") ? candidate : undefined;
+    }
+    const downloadCommandIndex = args.indexOf("download");
+    if (downloadCommandIndex >= 0 && args.length > downloadCommandIndex + 2) {
+        return args[args.length - 1];
+    }
+    return undefined;
+}
+export function buildAgentBrowserNextActions(options) {
+    const actions = [];
+    if (options.recovery) {
+        actions.push(...buildRecoveryNextActions(options.recovery));
+    }
+    if (options.electron?.launchId) {
+        const { launchId, sessionName, status } = options.electron;
+        if (options.resultCategory === "success" && status !== "cleaned") {
+            actions.push(buildElectronToolAction({
+                action: "status",
+                id: "status-electron-launch",
+                launchId,
+                reason: "Check the wrapper-tracked Electron launch liveness and current CDP targets without mutating the app.",
+            }), buildElectronToolAction({
+                action: "probe",
+                id: "probe-electron-launch",
+                launchId,
+                reason: "Probe the attached Electron managed session and carry the wrapper launchId for follow-up diagnostics.",
+            }), buildElectronToolAction({
+                action: "cleanup",
+                id: "cleanup-electron-launch",
+                launchId,
+                reason: "Clean the wrapper-owned Electron process and isolated userDataDir when the run is complete.",
+                safety: "Only operates on the launchId created by electron.launch; explicit artifacts and manually launched apps remain host-owned.",
+            }));
+            if (sessionName) {
+                actions.push(buildNextToolAction({
+                    args: ["--session", sessionName, "tab", "list"],
+                    id: "list-electron-tabs",
+                    reason: "Inspect attached Electron page/webview targets before choosing the active tab.",
+                }), buildNextToolAction({
+                    args: ["--session", sessionName, "snapshot", "-i"],
+                    id: "snapshot-electron-session",
+                    reason: "Refresh interactive refs for the attached Electron session.",
+                    safety: "Use current Electron refs only after a fresh snapshot for this session.",
+                }));
+            }
+        }
+        else if (options.resultCategory === "failure" && options.failureCategory === "cleanup-failed") {
+            actions.push(buildElectronToolAction({
+                action: "status",
+                id: "status-electron-launch",
+                launchId,
+                reason: "Inspect which wrapper-tracked Electron resources remain after partial cleanup.",
+            }), buildElectronToolAction({
+                action: "cleanup",
+                id: "retry-electron-cleanup",
+                launchId,
+                reason: "Retry cleanup for the same wrapper-owned Electron launch after reviewing remaining resources.",
+                safety: "Only retry for the same launchId; do not use cleanup for manually launched Electron apps.",
+            }));
+        }
+    }
+    if (options.resultCategory === "success") {
+        if (isOpenNavigationCommand(options.command)) {
+            actions.push(buildNextToolAction({
+                args: ["snapshot", "-i"],
+                id: "inspect-opened-page",
+                reason: "Inspect the opened page before choosing interactive refs.",
+            }));
+        }
+        else if (isPageMutationCommand(options.command)) {
+            actions.push(buildNextToolAction({
+                args: ["snapshot", "-i"],
+                id: "inspect-after-mutation",
+                reason: "Refresh interactive refs after a browser mutation, navigation, scroll, or rerender.",
+                safety: "Do not reuse prior @refs until a fresh snapshot confirms they still exist.",
+            }));
+        }
+        const artifacts = options.artifacts ?? [];
+        const savedFileArtifact = options.savedFilePath ? artifacts.find((artifact) => artifact.path === options.savedFilePath) : undefined;
+        if (options.savedFilePath && savedFileArtifact?.exists !== false) {
+            actions.push(buildArtifactAction(options.savedFilePath));
+        }
+        for (const artifact of artifacts) {
+            if (isPendingRecordingArtifact(artifact)) {
+                continue;
+            }
+            if (artifact.exists === false) {
+                if (artifact.kind === "download") {
+                    actions.push(buildNextToolAction({
+                        args: ["wait", "--download", artifact.path],
+                        id: "wait-for-download",
+                        reason: "Upstream reported a download path, but the wrapper did not verify the file on disk.",
+                        safety: "Use an explicit wait timeout; if you set top-level timeoutMs, keep it above the wait duration plus a small grace window.",
+                    }));
+                }
+                else {
+                    actions.push(buildArtifactVerificationAction(artifact));
+                }
+                continue;
+            }
+            if (artifact.path !== options.savedFilePath) {
+                actions.push(buildArtifactAction(artifact.path));
+            }
+        }
+    }
+    else {
+        switch (options.failureCategory) {
+            case "artifact-missing":
+                for (const artifact of options.artifacts ?? []) {
+                    if (isPendingRecordingArtifact(artifact) || artifact.exists !== false)
+                        continue;
+                    if (artifact.kind === "download") {
+                        actions.push(buildNextToolAction({
+                            args: ["wait", "--download", artifact.path],
+                            id: "wait-for-download",
+                            reason: "The requested download artifact was not found on disk after upstream reported completion.",
+                            safety: "Use an explicit wait timeout; if you set top-level timeoutMs, keep it above the wait duration plus a small grace window.",
+                        }));
+                    }
+                    else {
+                        actions.push(buildArtifactVerificationAction(artifact));
+                    }
+                }
+                break;
+            case "confirmation-required":
+                if (options.confirmationId) {
+                    actions.push(buildNextToolAction({
+                        args: ["confirm", options.confirmationId],
+                        id: "approve-confirmation",
+                        reason: "Approve the pending upstream confirmation when the requested action is safe.",
+                        safety: "Only confirm after reviewing the guarded action shown in the result.",
+                    }), buildNextToolAction({
+                        args: ["deny", options.confirmationId],
+                        id: "deny-confirmation",
+                        reason: "Deny the pending upstream confirmation when the guarded action is unsafe or unintended.",
+                    }));
+                }
+                break;
+            case "stale-ref":
+            case "selector-not-found":
+            case "selector-unsupported":
+                actions.push(buildNextToolAction({
+                    args: ["snapshot", "-i"],
+                    id: "refresh-interactive-refs",
+                    reason: "Get current interactive refs before retrying the element action.",
+                    safety: "Prefer a current @ref or a stable find locator; do not retry stale refs blindly.",
+                }));
+                break;
+            case "download-not-verified":
+                {
+                    const retryPath = getDownloadRetryPath(options.args, options.savedFilePath);
+                    actions.push(buildNextToolAction({
+                        args: retryPath ? ["wait", "--download", retryPath] : ["wait", "--download"],
+                        id: "wait-for-download",
+                        reason: "Wait for the browser download and let the wrapper verify saved-file metadata.",
+                        safety: "Use an explicit wait timeout; if you set top-level timeoutMs, keep it above the wait duration plus a small grace window.",
+                    }));
+                }
+                break;
+            case "tab-drift":
+                if (options.recovery?.kind === "about-blank" || options.recovery?.kind === "tab-drift") {
+                    break;
+                }
+                actions.push(buildNextToolAction({
+                    args: ["tab", "list"],
+                    id: AGENT_BROWSER_RECOVERY_NEXT_ACTION_IDS.genericTabDriftListTabs,
+                    reason: "Inspect available tabs before selecting the intended target.",
+                    safety: "Read-only. Retry snapshot only after selecting or confirming the intended stable tab.",
+                }));
+                break;
+        }
+    }
+    return actions.length > 0 ? actions : undefined;
+}

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

@@ -0,0 +1,111 @@
+/**
+ * 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 { isRecord } from "../parsing.js";
+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;
+function parsePositiveSafeInteger(value) {
+    if (value === undefined)
+        return undefined;
+    const parsed = Number(value);
+    if (!Number.isSafeInteger(parsed) || parsed <= 0)
+        return undefined;
+    return parsed;
+}
+export function getSessionArtifactManifestMaxEntries(env = process.env) {
+    return parsePositiveSafeInteger(env[SESSION_ARTIFACT_MANIFEST_MAX_ENTRIES_ENV]) ?? DEFAULT_SESSION_ARTIFACT_MANIFEST_MAX_ENTRIES;
+}
+function isManifestEntry(value) {
+    if (!isRecord(value))
+        return false;
+    if (typeof value.path !== "string" || value.path.trim().length === 0)
+        return false;
+    if (typeof value.createdAtMs !== "number" || !Number.isFinite(value.createdAtMs))
+        return false;
+    if (!["evicted", "ephemeral", "live", "missing"].includes(String(value.retentionState)))
+        return false;
+    if (!["explicit-path", "persistent-session", "process-temp"].includes(String(value.storageScope)))
+        return false;
+    if (typeof value.kind !== "string" || value.kind.trim().length === 0)
+        return false;
+    return true;
+}
+export function isSessionArtifactManifest(value) {
+    if (!isRecord(value))
+        return false;
+    if (value.version !== SESSION_ARTIFACT_MANIFEST_VERSION)
+        return false;
+    if (!Array.isArray(value.entries) || !value.entries.every(isManifestEntry))
+        return false;
+    if (typeof value.updatedAtMs !== "number" || !Number.isFinite(value.updatedAtMs))
+        return false;
+    if (typeof value.maxEntries !== "number" || !Number.isSafeInteger(value.maxEntries) || value.maxEntries <= 0)
+        return false;
+    if (typeof value.liveCount !== "number" || !Number.isSafeInteger(value.liveCount) || value.liveCount < 0)
+        return false;
+    if (typeof value.evictedCount !== "number" || !Number.isSafeInteger(value.evictedCount) || value.evictedCount < 0)
+        return false;
+    return true;
+}
+export function buildEvictedSessionArtifactEntries(evictedArtifacts, nowMs) {
+    return evictedArtifacts.map((artifact) => ({
+        createdAtMs: artifact.mtimeMs,
+        evictedAtMs: nowMs,
+        kind: "spill",
+        path: artifact.path,
+        retentionState: "evicted",
+        sizeBytes: artifact.sizeBytes,
+        storageScope: "persistent-session",
+    }));
+}
+export function formatSessionArtifactRetentionSummary(manifest) {
+    const ephemeralCount = manifest.entries.filter((entry) => entry.retentionState === "ephemeral").length;
+    const missingCount = manifest.entries.filter((entry) => entry.retentionState === "missing").length;
+    const parts = [`${manifest.liveCount} live`, `${manifest.evictedCount} evicted`];
+    if (ephemeralCount > 0)
+        parts.push(`${ephemeralCount} ephemeral`);
+    if (missingCount > 0)
+        parts.push(`${missingCount} missing`);
+    return `Session artifacts: ${parts.join(", ")} (${manifest.entries.length}/${manifest.maxEntries} recent).`;
+}
+export function mergeSessionArtifactManifest(options) {
+    const nowMs = options.nowMs ?? Date.now();
+    const maxEntries = getSessionArtifactManifestMaxEntries();
+    const getEntryKey = (entry) => entry.storageScope === "explicit-path" && entry.absolutePath ? `${entry.storageScope}:${entry.absolutePath}` : `${entry.storageScope}:${entry.path}`;
+    const byPath = new Map();
+    for (const entry of options.base?.entries ?? []) {
+        byPath.set(getEntryKey(entry), entry);
+    }
+    for (const entry of options.entries ?? []) {
+        const key = getEntryKey(entry);
+        const existing = byPath.get(key);
+        byPath.set(key, {
+            ...existing,
+            ...entry,
+            createdAtMs: existing?.createdAtMs ?? entry.createdAtMs,
+            evictedAtMs: entry.retentionState === "evicted" ? (entry.evictedAtMs ?? nowMs) : entry.evictedAtMs,
+        });
+    }
+    if (byPath.size === 0)
+        return undefined;
+    const entries = [...byPath.values()]
+        .sort((left, right) => {
+        const leftTime = left.evictedAtMs ?? left.createdAtMs;
+        const rightTime = right.evictedAtMs ?? right.createdAtMs;
+        return rightTime - leftTime || left.path.localeCompare(right.path);
+    })
+        .slice(0, maxEntries);
+    return {
+        entries,
+        evictedCount: entries.filter((entry) => entry.retentionState === "evicted").length,
+        liveCount: entries.filter((entry) => entry.retentionState === "live").length,
+        maxEntries,
+        updatedAtMs: nowMs,
+        version: SESSION_ARTIFACT_MANIFEST_VERSION,
+    };
+}

package/{extensions/agent-browser/lib/results/artifact-state.ts → dist/extensions/agent-browser/lib/results/artifact-state.js}

@@ -5,13 +5,9 @@
  * Usage: Imported by categories, action recommendations, and presentation to avoid divergent artifact-state rules.
  * Invariants/Assumptions: `record start` / `record restart` video artifacts are pending and should not be treated like verified saved files.
  */
-
-import type { FileArtifactKind, FileArtifactMetadata } from "./contracts.js";
-
-export function isPendingRecordingCommand(command: string | undefined, subcommand: string | undefined, kind: FileArtifactKind | undefined): boolean {
-	return command === "record" && (subcommand === "start" || subcommand === "restart") && kind === "video";
+export function isPendingRecordingCommand(command, subcommand, kind) {
+    return command === "record" && (subcommand === "start" || subcommand === "restart") && kind === "video";
 }
-
-export function isPendingRecordingArtifact(artifact: FileArtifactMetadata): boolean {
-	return isPendingRecordingCommand(artifact.command, artifact.subcommand, artifact.kind);
+export function isPendingRecordingArtifact(artifact) {
+    return isPendingRecordingCommand(artifact.command, artifact.subcommand, artifact.kind);
 }

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

@@ -0,0 +1,76 @@
+/**
+ * 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";
+function hasUnverifiedFileArtifact(artifacts) {
+    return (artifacts ?? []).some((artifact) => !isPendingRecordingArtifact(artifact) && artifact.exists !== true);
+}
+export function classifyAgentBrowserSuccessCategory(options) {
+    if (options.inspection)
+        return "inspection";
+    if ((options.artifacts ?? []).length > 0)
+        return hasUnverifiedFileArtifact(options.artifacts) ? "artifact-unverified" : "artifact-saved";
+    if (options.savedFile)
+        return "artifact-saved";
+    return "completed";
+}
+export function classifyAgentBrowserFailureCategory(options) {
+    const text = [options.errorText, options.validationError, options.parseError, options.spawnError, options.stderr].filter(Boolean).join("\n");
+    const command = options.command ?? "";
+    const usedRef = options.args?.some((arg) => /^@e\d+\b/.test(arg)) ?? false;
+    if (options.confirmationRequired || /confirmation required|pending confirmation|requires confirmation/i.test(text))
+        return "confirmation-required";
+    if (options.timedOut || /timeout|timed out|watchdog|IPC read timeout|must stay under its 30s IPC read timeout/i.test(text))
+        return "timeout";
+    if (/ENOENT|not found on PATH|could not find.*agent-browser|agent-browser is required but was not found/i.test(text))
+        return "missing-binary";
+    if (options.parseError || /invalid JSON|missing boolean success|success field must be boolean|returned no JSON output/i.test(text))
+        return "parse-failure";
+    if (/aborted/i.test(text))
+        return "aborted";
+    if (/policy[- ]blocked|blocked by caller policy|caller deny policy|caller allow policy/i.test(text))
+        return "policy-blocked";
+    if (/cleanup failed|cleanup.*partial|partial cleanup|remaining resources/i.test(text))
+        return "cleanup-failed";
+    if (options.validationError)
+        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";
+    if (/\bUnknown ref\b|\bstale ref\b|@ref may be stale|\bref\b.*\b(?:not found|missing|expired)\b/i.test(text))
+        return "stale-ref";
+    if (usedRef && /could not locate element|element not found|no element/i.test(text))
+        return "stale-ref";
+    const mentionsPlaywrightSelectorDialect = /(?:\btext=|:has-text\(|\bgetByRole\b|\bgetByText\b)/i.test(text);
+    const reportsSelectorMatchFailure = /\b(?:no elements? found|failed to find|could not find|unable to find)\b.*\b(?:selector|locator)\b/i.test(text) ||
+        /\b(?:selector|locator)\b.*\b(?:no elements? found|not found|missing|failed to find|could not find|unable to find)\b/i.test(text);
+    if (/\b(?:unsupported|unknown|invalid)\s+(?:selector|locator)\b/i.test(text) ||
+        /\bfailed to parse selector\b/i.test(text) ||
+        /\bselector\b.*\b(?:parse|syntax|unsupported|invalid)\b/i.test(text) ||
+        (mentionsPlaywrightSelectorDialect && reportsSelectorMatchFailure)) {
+        return "selector-unsupported";
+    }
+    if (command === "find" && /could not locate element|element not found|no elements? found|unable to find/i.test(text))
+        return "selector-not-found";
+    if (reportsSelectorMatchFailure)
+        return "selector-not-found";
+    if ((command === "download" || text.includes("wait --download") || /\bdownload\b/i.test(text)) && /missing|not verified|not found|failed|timeout|timed out/i.test(text)) {
+        return "download-not-verified";
+    }
+    return "upstream-error";
+}
+export function buildAgentBrowserResultCategoryDetails(options) {
+    if (options.succeeded) {
+        return {
+            resultCategory: "success",
+            successCategory: classifyAgentBrowserSuccessCategory(options),
+        };
+    }
+    return {
+        failureCategory: options.failureCategory ?? classifyAgentBrowserFailureCategory(options),
+        resultCategory: "failure",
+    };
+}

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

@@ -0,0 +1,63 @@
+/**
+ * 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",
+    "confirmationRequired",
+    "requires_confirmation",
+    "requiresConfirmation",
+];
+const CONFIRMATION_REQUIRED_RECORD_FIELD_NAMES = ["confirmation", "pendingConfirmation", "pending_confirmation"];
+const CONFIRMATION_ID_FIELD_NAMES = ["confirmation_id", "confirmationId", "id"];
+const CONFIRMATION_ACTION_TEXT_FIELD_NAMES = ["action", "description", "message", "summary"];
+const CONFIRMATION_REQUIRED_MARKER = "confirmation_required";
+function getTrimmedStringField(data, fieldNames) {
+    for (const fieldName of fieldNames) {
+        const value = data[fieldName];
+        if (typeof value === "string" && value.trim().length > 0) {
+            return value.trim();
+        }
+    }
+    return undefined;
+}
+function hasConfirmationRequiredMarker(data) {
+    return CONFIRMATION_REQUIRED_FIELD_NAMES.some((fieldName) => data[fieldName] === true)
+        || data.type === CONFIRMATION_REQUIRED_MARKER
+        || data.status === CONFIRMATION_REQUIRED_MARKER
+        || data.kind === CONFIRMATION_REQUIRED_MARKER;
+}
+function getNestedConfirmationRecord(data) {
+    for (const fieldName of CONFIRMATION_REQUIRED_RECORD_FIELD_NAMES) {
+        const value = data[fieldName];
+        if (isRecord(value)) {
+            return value;
+        }
+    }
+    return undefined;
+}
+export function detectConfirmationRequired(data) {
+    if (!isRecord(data)) {
+        return undefined;
+    }
+    const nestedRecord = getNestedConfirmationRecord(data);
+    const candidateRecords = nestedRecord ? [data, nestedRecord] : [data];
+    if (!candidateRecords.some(hasConfirmationRequiredMarker)) {
+        return undefined;
+    }
+    for (const record of candidateRecords) {
+        const id = getTrimmedStringField(record, CONFIRMATION_ID_FIELD_NAMES);
+        if (!id) {
+            continue;
+        }
+        return {
+            actionText: getTrimmedStringField(record, CONFIRMATION_ACTION_TEXT_FIELD_NAMES),
+            id,
+        };
+    }
+    return undefined;
+}

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

@@ -0,0 +1,8 @@
+/**
+ * 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

@@ -0,0 +1,74 @@
+/**
+ * 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;
+const EDITABLE_BARE_TEXT_PATTERN = /\b(?:contenteditable|editable)\b(?!\s*=)/i;
+function parseEditableEvidenceValue(value) {
+    if (typeof value === "boolean")
+        return value;
+    if (typeof value === "number") {
+        if (value === 1)
+            return true;
+        if (value === 0)
+            return false;
+        return undefined;
+    }
+    if (typeof value !== "string")
+        return undefined;
+    const normalized = value.trim().replace(/^["']|["']$/g, "").toLowerCase();
+    if (["false", "0", "no"].includes(normalized))
+        return false;
+    if (["", "true", "1", "yes", "plaintext-only"].includes(normalized))
+        return true;
+    return undefined;
+}
+function stripLeadingSnapshotAccessibleName(text) {
+    return text.replace(/^(\s*[-*]\s+\S+\s+)(?:"[^"]*"|'[^']*')/, "$1");
+}
+function parseEditableEvidenceText(text) {
+    if (!text)
+        return undefined;
+    const markerText = stripLeadingSnapshotAccessibleName(text);
+    if (EDITABLE_FALSE_TEXT_PATTERN.test(markerText))
+        return false;
+    let hasPositiveAssignment = false;
+    for (const match of markerText.matchAll(EDITABLE_ASSIGNMENT_TEXT_PATTERN)) {
+        const key = match[1]?.toLowerCase();
+        const evidence = parseEditableEvidenceValue(match[2]);
+        if (evidence === false)
+            return false;
+        if (evidence === true && (key === "contenteditable" || key === "editable")) {
+            hasPositiveAssignment = true;
+        }
+    }
+    if (hasPositiveAssignment)
+        return true;
+    return EDITABLE_BARE_TEXT_PATTERN.test(markerText) ? true : undefined;
+}
+export function getEditableRefEvidence(options) {
+    let hasPositiveEvidence = false;
+    if (options.ref) {
+        for (const key of EDITABLE_REF_EVIDENCE_KEYS) {
+            const evidence = parseEditableEvidenceValue(options.ref[key]);
+            if (evidence === false)
+                return false;
+            if (evidence === true)
+                hasPositiveEvidence = true;
+        }
+    }
+    const textEvidence = parseEditableEvidenceText(options.text);
+    if (textEvidence === false)
+        return false;
+    if (textEvidence === true)
+        hasPositiveEvidence = true;
+    return hasPositiveEvidence ? true : undefined;
+}
+export function hasPositiveEditableRefEvidence(options) {
+    return getEditableRefEvidence(options) === true;
+}