pi-agent-browser-native 0.9.3 → 0.9.5

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

@@ -0,0 +1,133 @@
+import { isRecord } from "../parsing.js";
+function finiteNonnegative(value) {
+    return typeof value === "number" && Number.isFinite(value) && value >= 0;
+}
+function safeCount(value) {
+    return finiteNonnegative(value) && Number.isSafeInteger(value);
+}
+function optionalStrings(value, keys) {
+    return keys.every((key) => value[key] === undefined || typeof value[key] === "string");
+}
+function nullableStrings(value, keys) {
+    return keys.every((key) => value[key] === null || typeof value[key] === "string");
+}
+function nullableNumbers(value, keys) {
+    return keys.every((key) => value[key] === null || finiteNonnegative(value[key]));
+}
+function nullableBoolean(value) {
+    return value === null || typeof value === "boolean";
+}
+function captureIsValid(value) {
+    return (nullableStrings(value, [
+        "startedAt",
+        "endedAt",
+        "firstFrameAt",
+        "lastFrameAt",
+        "timestampSource",
+    ]) &&
+        nullableNumbers(value, [
+            "durationMs",
+            "firstFrameAfterMs",
+            "lastFrameAfterMs",
+            "averageFps",
+            "maxFrameGapMs",
+        ]));
+}
+function outputIsValid(value) {
+    return (nullableStrings(value, ["durationSource"]) &&
+        nullableNumbers(value, [
+            "frames",
+            "fps",
+            "encodedFrames",
+            "durationMs",
+            "heldFrames",
+            "droppedFrames",
+            "skippedFrames",
+        ]) &&
+        nullableBoolean(value.encoderSucceeded));
+}
+function recordingIsValid(value) {
+    if (!isRecord(value) ||
+        !isRecord(value.capture) ||
+        !isRecord(value.output) ||
+        !isRecord(value.file)) {
+        return false;
+    }
+    return (recordingScalarsAreValid(value) &&
+        captureIsValid(value.capture) &&
+        outputIsValid(value.output) &&
+        nullableBoolean(value.file.exists) &&
+        nullableNumbers(value.file, ["sizeBytes"]));
+}
+function recordingScalarsAreValid(value) {
+    return (typeof value.warning === "string" &&
+        typeof value.path === "string" &&
+        nullableStrings(value, ["recordingId", "error"]) &&
+        nullableBoolean(value.success) &&
+        nullableNumbers(value, ["frames", "capturedFrames", "fps"]));
+}
+function optionalNumbersAreValid(value) {
+    return (["evictedAtMs", "recordingStartedAtMs"].every((key) => value[key] === undefined || (typeof value[key] === "number" && Number.isFinite(value[key]))) &&
+        (value.sizeBytes === undefined || finiteNonnegative(value.sizeBytes)));
+}
+function optionalRecordingIsValid(value) {
+    return ((value.recordingState === undefined || value.recordingState === "openRecording") &&
+        (value.recording === undefined || recordingIsValid(value.recording)) &&
+        (value.status === undefined ||
+            [
+                "failed",
+                "missing",
+                "pending",
+                "repaired-from-temp",
+                "saved",
+                "stale",
+                "unverified",
+                "upstream-temp-only",
+            ].some((status) => status === value.status)));
+}
+function optionalEvidenceIsValid(value) {
+    return (optionalStrings(value, [
+        "absolutePath",
+        "command",
+        "cwd",
+        "extension",
+        "mediaType",
+        "namespace",
+        "requestedPath",
+        "session",
+        "subcommand",
+    ]) &&
+        (value.exists === undefined || typeof value.exists === "boolean") &&
+        optionalNumbersAreValid(value) &&
+        optionalRecordingIsValid(value));
+}
+function isManifestEntry(value) {
+    if (!isRecord(value)) {
+        return false;
+    }
+    return (typeof value.path === "string" &&
+        value.path.trim().length > 0 &&
+        typeof value.createdAtMs === "number" &&
+        Number.isFinite(value.createdAtMs) &&
+        ["evicted", "ephemeral", "live", "missing"].some((state) => state === value.retentionState) &&
+        ["explicit-path", "persistent-session", "process-temp"].some((scope) => scope === value.storageScope) &&
+        ["download", "file", "har", "image", "pdf", "profile", "trace", "video", "spill"].some((kind) => kind === value.kind) &&
+        optionalEvidenceIsValid(value));
+}
+function manifestCountsAreValid(value) {
+    return (safeCount(value.maxEntries) &&
+        value.maxEntries !== 0 &&
+        safeCount(value.liveCount) &&
+        safeCount(value.evictedCount));
+}
+export function isSessionArtifactManifest(value) {
+    if (!isRecord(value)) {
+        return false;
+    }
+    return (value.version === 1 &&
+        Array.isArray(value.entries) &&
+        value.entries.every(isManifestEntry) &&
+        typeof value.updatedAtMs === "number" &&
+        Number.isFinite(value.updatedAtMs) &&
+        manifestCountsAreValid(value));
+}

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

@@ -1,67 +1,30 @@
 import { getAgentBrowserSessionIdentityKey } from "../argv-grammar.js";
-import { isRecord } from "../parsing.js";
+export { isSessionArtifactManifest } from "./artifact-manifest-validation.js";
 export function isPendingRecordingCommand(command, subcommand, kind) {
-    return command === "record" && (subcommand === "start" || subcommand === "restart") && kind === "video";
+    return (command === "record" && (subcommand === "start" || subcommand === "restart") && kind === "video");
 }
 export function isPendingRecordingArtifact(artifact) {
-    return artifact.recordingState === "openRecording" || artifact.status === "pending"
-        || (artifact.status === undefined && isPendingRecordingCommand(artifact.command, artifact.subcommand, artifact.kind));
+    return (artifact.recordingState === "openRecording" ||
+        artifact.status === "pending" ||
+        (artifact.status === undefined &&
+            isPendingRecordingCommand(artifact.command, artifact.subcommand, artifact.kind)));
 }
 const SESSION_ARTIFACT_MANIFEST_VERSION = 1;
 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)
+    if (value === undefined) {
         return undefined;
+    }
     const parsed = Number(value);
-    if (!Number.isSafeInteger(parsed) || parsed <= 0)
+    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;
-    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) {
-    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;
+    return (parsePositiveSafeInteger(env[SESSION_ARTIFACT_MANIFEST_MAX_ENTRIES_ENV]) ??
+        DEFAULT_SESSION_ARTIFACT_MANIFEST_MAX_ENTRIES);
 }
 export function buildEvictedSessionArtifactEntries(evictedArtifacts, nowMs) {
     return evictedArtifacts.map((artifact) => ({
@@ -78,34 +41,54 @@ 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)
+    if (ephemeralCount > 0) {
         parts.push(`${ephemeralCount} ephemeral`);
-    if (missingCount > 0)
+    }
+    if (missingCount > 0) {
         parts.push(`${missingCount} missing`);
+    }
     return `Session artifacts: ${parts.join(", ")} (${manifest.entries.length}/${manifest.maxEntries} recent).`;
 }
 export function getSessionArtifactManifestEntryKey(entry) {
-    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
+    const pathKey = entry.storageScope === "explicit-path" &&
+        entry.absolutePath !== undefined &&
+        entry.absolutePath.length > 0
+        ? `${entry.storageScope}:${entry.absolutePath}`
+        : `${entry.storageScope}:${entry.path}`;
+    const recordingSessionKey = entry.command === "record" &&
+        entry.kind === "video" &&
+        entry.session !== undefined &&
+        entry.session.length > 0
         ? getAgentBrowserSessionIdentityKey(entry.session, entry.namespace)
         : undefined;
-    return recordingSessionKey ? `${pathKey}\0${recordingSessionKey}` : pathKey;
+    return recordingSessionKey !== undefined && recordingSessionKey.length > 0
+        ? `${pathKey}\0${recordingSessionKey}`
+        : pathKey;
 }
 export function retirePendingRecordingManifestEntries(manifest, sessionName, namespace, nowMs = Date.now()) {
-    let changed = false;
-    const sessionKey = sessionName ? getAgentBrowserSessionIdentityKey(sessionName, namespace) : undefined;
+    const sessionKey = sessionName !== undefined && sessionName.length > 0
+        ? getAgentBrowserSessionIdentityKey(sessionName, namespace)
+        : undefined;
     const entries = manifest.entries.map((entry) => {
-        if (!sessionKey
-            || !entry.session
-            || getAgentBrowserSessionIdentityKey(entry.session, entry.namespace) !== sessionKey
-            || entry.kind !== "video"
-            || !isPendingRecordingArtifact(entry))
+        if (sessionKey === undefined ||
+            sessionKey.length === 0 ||
+            entry.session === undefined ||
+            entry.session.length === 0 ||
+            getAgentBrowserSessionIdentityKey(entry.session, entry.namespace) !== sessionKey ||
+            entry.kind !== "video" ||
+            !isPendingRecordingArtifact(entry)) {
             return entry;
-        changed = true;
-        return { ...entry, recordingState: undefined, status: "unverified", subcommand: "close-abandoned" };
+        }
+        return {
+            ...entry,
+            recordingState: undefined,
+            status: "unverified",
+            subcommand: "close-abandoned",
+        };
     });
-    if (!changed)
+    if (entries.every((entry, index) => entry === manifest.entries[index])) {
         return manifest;
+    }
     return {
         ...manifest,
         entries,
@@ -114,6 +97,45 @@ export function retirePendingRecordingManifestEntries(manifest, sessionName, nam
         updatedAtMs: nowMs,
     };
 }
+function getSupersededRecordingKeys(candidates, entry, key) {
+    if (entry.command !== "record" || entry.kind !== "video") {
+        return [];
+    }
+    const entrySessionKey = entry.session !== undefined && entry.session.length > 0
+        ? getAgentBrowserSessionIdentityKey(entry.session, entry.namespace)
+        : undefined;
+    return candidates
+        .filter(([candidateKey, candidate]) => {
+        const sameRecordingSession = entrySessionKey === undefined
+            ? candidate.session === undefined
+            : candidate.session !== undefined &&
+                getAgentBrowserSessionIdentityKey(candidate.session, candidate.namespace) ===
+                    entrySessionKey;
+        return (candidateKey !== key &&
+            sameRecordingSession &&
+            candidate.kind === "video" &&
+            isPendingRecordingArtifact(candidate));
+    })
+        .map(([candidateKey]) => candidateKey);
+}
+function mergeManifestEntry(existing, entry, nowMs) {
+    return {
+        ...existing,
+        ...entry,
+        createdAtMs: entry.command === "record" && entry.kind === "video"
+            ? entry.createdAtMs
+            : (existing?.createdAtMs ?? entry.createdAtMs),
+        evictedAtMs: entry.retentionState === "evicted" ? (entry.evictedAtMs ?? nowMs) : entry.evictedAtMs,
+    };
+}
+function compareManifestEntries(left, right) {
+    const difference = (right.evictedAtMs ?? right.createdAtMs) - (left.evictedAtMs ?? left.createdAtMs);
+    if (difference !== 0 && !Number.isNaN(difference)) {
+        return difference;
+    }
+    const pendingDifference = Number(isPendingRecordingArtifact(right)) - Number(isPendingRecordingArtifact(left));
+    return pendingDifference !== 0 ? pendingDifference : left.path.localeCompare(right.path);
+}
 export function mergeSessionArtifactManifest(options) {
     const nowMs = options.nowMs ?? Date.now();
     const maxEntries = getSessionArtifactManifestMaxEntries();
@@ -123,43 +145,23 @@ export function mergeSessionArtifactManifest(options) {
     }
     const orderedEntries = (options.entries ?? [])
         .map((entry, index) => ({ entry, index }))
-        .sort((left, right) => left.entry.createdAtMs - right.entry.createdAtMs || left.index - right.index)
+        .sort((left, right) => {
+        const difference = left.entry.createdAtMs - right.entry.createdAtMs;
+        return difference !== 0 && !Number.isNaN(difference) ? difference : 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"
-                    && isPendingRecordingArtifact(candidate)) {
-                    byPath.delete(candidateKey);
-                }
-            }
+        for (const candidateKey of getSupersededRecordingKeys([...byPath], entry, key)) {
+            byPath.delete(candidateKey);
         }
         const existing = byPath.get(key);
-        byPath.set(key, {
-            ...existing,
-            ...entry,
-            createdAtMs: entry.command === "record" && entry.kind === "video" ? entry.createdAtMs : existing?.createdAtMs ?? entry.createdAtMs,
-            evictedAtMs: entry.retentionState === "evicted" ? (entry.evictedAtMs ?? nowMs) : entry.evictedAtMs,
-        });
+        byPath.set(key, mergeManifestEntry(existing, entry, nowMs));
     }
-    if (byPath.size === 0)
+    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
-            || Number(isPendingRecordingArtifact(right)) - Number(isPendingRecordingArtifact(left))
-            || left.path.localeCompare(right.path);
-    })
-        .slice(0, maxEntries);
+    }
+    const entries = [...byPath.values()].sort(compareManifestEntries).slice(0, maxEntries);
     return {
         entries,
         evictedCount: entries.filter((entry) => entry.retentionState === "evicted").length,

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

@@ -0,0 +1,73 @@
+import { isPendingRecordingArtifact } from "./artifact-manifest.js";
+import { buildNextToolAction } from "./next-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 buildMissingArtifactAction(artifact, afterFailure) {
+    if (artifact.kind !== "download") {
+        return buildArtifactVerificationAction(artifact);
+    }
+    return buildNextToolAction({
+        args: ["wait", "--download", artifact.path],
+        id: "wait-for-download",
+        reason: afterFailure
+            ? "The requested download artifact was not found on disk after upstream reported completion."
+            : "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.",
+    });
+}
+export function buildSavedArtifactNextActions(options) {
+    const artifacts = options.artifacts ?? [];
+    const savedFilePath = options.savedFilePath;
+    const actions = [];
+    if (savedFilePath !== undefined &&
+        savedFilePath.length > 0 &&
+        artifacts.find((artifact) => artifact.path === savedFilePath)?.exists !== false) {
+        actions.push(buildArtifactAction(savedFilePath));
+    }
+    for (const artifact of artifacts) {
+        if (isPendingRecordingArtifact(artifact)) {
+            continue;
+        }
+        if (artifact.exists === false) {
+            actions.push(buildMissingArtifactAction(artifact, false));
+        }
+        else if (artifact.path !== savedFilePath) {
+            actions.push(buildArtifactAction(artifact.path));
+        }
+    }
+    return actions;
+}
+export function buildMissingArtifactNextActions(artifacts) {
+    return (artifacts ?? [])
+        .filter((artifact) => !isPendingRecordingArtifact(artifact) &&
+        (artifact.exists === false || artifact.status === "stale"))
+        .map((artifact) => buildMissingArtifactAction(artifact, true));
+}
+export function buildPendingRecordingNextActions(artifacts) {
+    return (artifacts ?? []).some(isPendingRecordingArtifact)
+        ? [
+            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.",
+            }),
+        ]
+        : [];
+}

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

@@ -1,85 +1,142 @@
 import { isPendingRecordingArtifact } from "./artifact-manifest.js";
 function hasUnverifiedFileArtifact(artifacts) {
-    return (artifacts ?? []).some((artifact) => !isPendingRecordingArtifact(artifact) && (artifact.exists !== true || ["failed", "stale", "unverified"].includes(artifact.status ?? "")));
+    return (artifacts ?? []).some((artifact) => !isPendingRecordingArtifact(artifact) &&
+        (artifact.exists !== true ||
+            ["failed", "stale", "unverified"].includes(artifact.status ?? "")));
 }
 export function classifyAgentBrowserSuccessCategory(options) {
-    if (options.inspection)
+    if (options.inspection === true) {
         return "inspection";
-    if (hasUnverifiedFileArtifact(options.artifacts))
+    }
+    if (hasUnverifiedFileArtifact(options.artifacts)) {
         return "artifact-unverified";
-    if ((options.artifacts ?? []).some(isPendingRecordingArtifact))
+    }
+    if ((options.artifacts ?? []).some(isPendingRecordingArtifact)) {
         return "artifact-pending";
-    if ((options.artifacts ?? []).length > 0)
-        return "artifact-saved";
-    if (options.savedFile)
-        return "artifact-saved";
-    return "completed";
+    }
+    return (options.artifacts ?? []).length > 0 || options.savedFile !== undefined
+        ? "artifact-saved"
+        : "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;
-    // Explicit confirmation flag wins. Text-derived confirmation phrases come after locator-miss detection so a
-    // 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) ||
-        // No trailing \b after ":" — colon is non-word, so "Element not found: text=…" would not match.
+function hasScopedNamesSeen(text, command) {
+    return (/\bNames seen:/i.test(text) &&
+        (command === "find" || /\belement has role\b|\bnone match name\b|\bgetByRole\b/i.test(text)));
+}
+function isUpstreamLocatorMiss(text, command) {
+    return (/\bNo element found:\s*(?:getBy[A-Za-z]+|role=|text=|label=|placeholder=|alt=|title=|testid=)/i.test(text) ||
         (/\bElement not found:/i.test(text) && /\bVerify the selector, role, or name\b/i.test(text)) ||
         /\bnone match name\b/i.test(text) ||
-        // Scope Names seen to role/name miss context (or find) so unrelated prose cannot trip selector-not-found.
-        (/\bNames seen:/i.test(text) && (command === "find" || /\belement has role\b|\bnone match name\b|\bgetByRole\b/i.test(text))) ||
-        /\belement has role\b[\s\S]*\bnone match\b/i.test(text);
-    if (isUpstreamLocatorMiss)
+        hasScopedNamesSeen(text, command) ||
+        /\belement has role\b[\s\S]*\bnone match\b/i.test(text));
+}
+function classifyNativeFailure(context) {
+    const { options, text, command } = context;
+    // Explicit native flags and prefixes win over accessible-name text and lastUrl substrings.
+    if (options.confirmationRequired === true) {
+        return "confirmation-required";
+    }
+    if (/\btab_gone:/i.test(text)) {
+        return "tab-gone";
+    }
+    if (isUpstreamLocatorMiss(text, command)) {
         return "selector-not-found";
-    if (/confirmation required|pending confirmation|requires confirmation/i.test(text))
+    }
+    if (/confirmation required|pending confirmation|requires confirmation/i.test(text)) {
         return "confirmation-required";
-    // Match real timeout phrasing only. Do not treat bare "timeout" as a hit — accessible names can include that word,
-    // and `timed?\s*out` would also match the substring "timeout" as time+out.
-    if (options.timedOut ||
+    }
+    return undefined;
+}
+function classifyProcessFailure(context) {
+    const { options, text } = context;
+    // Bare "timeout" may be an accessible name; require actual timeout phrasing.
+    if (options.timedOut === true ||
         /\b(?:timed\s+out|timeout exceeded|watchdog|IPC read timeout)\b|must stay under its 30s IPC read timeout|Operation timed out/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))
+    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))
+    }
+    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))
+    }
+    if (/aborted/i.test(text)) {
         return "aborted";
-    if (/policy[- ]blocked|blocked by caller policy|caller deny policy|caller allow policy/i.test(text))
+    }
+    return undefined;
+}
+function classifyLifecycleFailure(context) {
+    const { options, text } = context;
+    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))
+    }
+    if (/cleanup failed|cleanup.*partial|partial cleanup|remaining resources/i.test(text)) {
         return "cleanup-failed";
-    if (options.validationError || /Agent-browser Unix socket path would be|Agent-browser socket storage .* is unusable/i.test(text))
+    }
+    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))
+    }
+    if (options.tabDrift === true ||
+        /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) ||
+    }
+    return undefined;
+}
+function reportsSelectorMatchFailure(text) {
+    return (/\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));
+}
+function reportsUnsupportedSelector(text) {
+    return (/\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)) {
+        (/(?:\btext=|:has-text\(|\bgetByRole\b|\bgetByText\b)/i.test(text) &&
+            reportsSelectorMatchFailure(text)));
+}
+function classifySelectorFailure(context) {
+    const { options, text, command } = context;
+    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";
+    }
+    const usedRef = options.args?.some((arg) => /^@e\d+\b/.test(arg)) ?? false;
+    if (usedRef && /could not locate element|element not found|no element/i.test(text)) {
+        return "stale-ref";
+    }
+    if (reportsUnsupportedSelector(text)) {
         return "selector-unsupported";
     }
-    if (command === "find" && /could not locate element|element not found|no elements? found|unable to find/i.test(text))
+    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";
+    return reportsSelectorMatchFailure(text) ? "selector-not-found" : undefined;
+}
+function classifyDownloadFailure(context) {
+    const { text, command } = context;
+    return (command === "download" ||
+        text.includes("wait --download") ||
+        /\bdownload\b/i.test(text)) &&
+        /missing|not verified|not found|failed|timeout|timed out/i.test(text)
+        ? "download-not-verified"
+        : "upstream-error";
+}
+export function classifyAgentBrowserFailureCategory(options) {
+    const text = [
+        options.errorText,
+        options.validationError,
+        options.parseError,
+        options.spawnError,
+        options.stderr,
+    ]
+        .filter(Boolean)
+        .join("\n");
+    const context = { options, text, command: options.command ?? "" };
+    return (classifyNativeFailure(context) ??
+        classifyProcessFailure(context) ??
+        classifyLifecycleFailure(context) ??
+        classifySelectorFailure(context) ??
+        classifyDownloadFailure(context));
 }
 export function buildAgentBrowserResultCategoryDetails(options) {
     if (options.succeeded) {