pi-agent-browser-native 0.2.48 → 0.2.49

package/dist/extensions/agent-browser/lib/results/snapshot-refs.js

@@ -0,0 +1,78 @@
+/**
+ * Purpose: Own canonical parsing and enrichment of refs from agent-browser snapshot payloads.
+ * Responsibilities: Read structured refs, correlate them with raw snapshot lines, and infer editable/ref role evidence once for consumers.
+ * Scope: Snapshot ref metadata only; section preview, high-value ranking, and presentation assembly live in neighboring modules.
+ * Usage: Imported by snapshot presentation and recovery diagnostics that need consistent ref/name/role/editable evidence.
+ * Invariants/Assumptions: Snapshot text parsing is best-effort and must tolerate upstream formatting changes by preserving structured ref data when line parsing fails.
+ */
+import { isRecord } from "../parsing.js";
+import { getEditableRefEvidence } from "./editable-ref-evidence.js";
+import { compareRefIds, normalizeWhitespace } from "./text.js";
+export function getSnapshotRefRecord(data) {
+    return isRecord(data) && isRecord(data.refs) ? data.refs : undefined;
+}
+export function getSnapshotLineTextByRef(data) {
+    const snapshot = isRecord(data) && typeof data.snapshot === "string" ? data.snapshot : "";
+    const lineByRef = new Map();
+    for (const line of snapshot.split("\n")) {
+        const ref = line.match(/\bref=([^,\]\s]+)/)?.[1];
+        if (!ref || lineByRef.has(ref))
+            continue;
+        lineByRef.set(ref, line);
+    }
+    return lineByRef;
+}
+export function getSnapshotRefEntries(data) {
+    const refs = getSnapshotRefRecord(data);
+    if (!refs)
+        return [];
+    return Object.entries(refs)
+        .map(([id, value]) => {
+        if (!isRecord(value)) {
+            return { id, name: "", role: "unknown" };
+        }
+        const name = typeof value.name === "string" ? normalizeWhitespace(value.name) : "";
+        const role = typeof value.role === "string" && value.role.length > 0 ? value.role : "unknown";
+        const isEditable = getEditableRefEvidence({ ref: value });
+        return { id, isEditable, name, refData: value, role };
+    })
+        .sort((a, b) => compareRefIds(a.id, b.id));
+}
+function isEditableSnapshotLine(line) {
+    const editableEvidence = getEditableRefEvidence({ text: line.raw });
+    if (editableEvidence !== undefined)
+        return editableEvidence;
+    return line.role === "searchbox" || line.role === "textbox" || line.role === "combobox" ? true : undefined;
+}
+export function getSnapshotRefRole(entry, editableEvidence) {
+    const rawRole = typeof entry.role === "string" && entry.role.length > 0 ? entry.role : "unknown";
+    const normalizedRole = rawRole.toLowerCase();
+    if ((normalizedRole === "generic" || normalizedRole === "unknown") && editableEvidence === true) {
+        return "textbox";
+    }
+    return rawRole;
+}
+export function enrichSnapshotRefEntries(refEntries, snapshotLines) {
+    const lineByRef = new Map();
+    for (const line of snapshotLines) {
+        if (!line.ref || lineByRef.has(line.ref))
+            continue;
+        lineByRef.set(line.ref, line);
+    }
+    return refEntries.map((entry) => {
+        const line = lineByRef.get(entry.id);
+        const lineRole = line && line.role !== "unknown" ? line.role : undefined;
+        const editableEvidence = getEditableRefEvidence({ ref: entry.refData, text: line?.raw });
+        const hasEditableRole = line ? isEditableSnapshotLine(line) === true && !["unknown", "generic"].includes(line.role) : false;
+        const isEditable = editableEvidence === true || (editableEvidence !== false && hasEditableRole);
+        const roleFromRefOrLine = entry.role !== "unknown" && entry.role !== "generic" ? entry.role : lineRole ?? entry.role;
+        const role = getSnapshotRefRole({ role: roleFromRefOrLine }, isEditable);
+        return {
+            ...entry,
+            isEditable,
+            lineIndex: line?.index,
+            name: entry.name.length > 0 ? entry.name : (line?.name ?? ""),
+            role,
+        };
+    });
+}

package/dist/extensions/agent-browser/lib/results/snapshot-segments.js

@@ -0,0 +1,331 @@
+/**
+ * Purpose: Parse raw agent-browser snapshot text into previewable sections.
+ * Responsibilities: Identify signal lines, rank content segments, build structured previews, and provide raw-outline fallback previews.
+ * Scope: Snapshot text/section planning only; ref enrichment, high-value control ranking, spill files, and final presentation live elsewhere.
+ * Usage: Snapshot presentation uses this module before selecting displayed refs.
+ * Invariants/Assumptions: Parsing is best-effort and must stay resilient to upstream snapshot text format changes.
+ */
+import { normalizeWhitespace, truncateText } from "./text.js";
+const SNAPSHOT_MAX_ADDITIONAL_SECTIONS = 2;
+const SNAPSHOT_FALLBACK_PREVIEW_MAX_LINES = 12;
+const SNAPSHOT_LINE_MAX_CHARS = 140;
+const SNAPSHOT_SIGNAL_ROLES = new Set([
+    "article",
+    "banner",
+    "button",
+    "checkbox",
+    "combobox",
+    "dialog",
+    "gridcell",
+    "heading",
+    "link",
+    "listitem",
+    "main",
+    "menu",
+    "menuitem",
+    "navigation",
+    "option",
+    "radio",
+    "region",
+    "row",
+    "searchbox",
+    "tab",
+    "textbox",
+]);
+const SNAPSHOT_SEGMENT_ROOT_ROLES = new Set(["article", "dialog", "heading", "main", "menu", "region"]);
+const SNAPSHOT_ROLE_PRIORITY = {
+    article: 0,
+    main: 1,
+    dialog: 2,
+    menu: 3,
+    region: 4,
+    heading: 5,
+    searchbox: 6,
+    textbox: 7,
+    combobox: 8,
+    button: 9,
+    checkbox: 10,
+    radio: 11,
+    tab: 12,
+    option: 13,
+    link: 14,
+    listitem: 14,
+    row: 15,
+    gridcell: 16,
+    navigation: 17,
+    generic: 99,
+    unknown: 100,
+};
+const SNAPSHOT_NOISE_NAME_PATTERNS = [
+    /^skip to /i,
+    /^ad$/i,
+    /^don't want to see ads\??$/i,
+    /keyboard shortcuts/i,
+    /\bpromoted\b/i,
+    /\bsponsored\b/i,
+];
+const SNAPSHOT_CHROME_SECTION_PATTERNS = [
+    /^primary$/i,
+    /^footer$/i,
+    /^navigation$/i,
+    /\bwhat['’]?s happening\b/i,
+    /\brelevant people\b/i,
+    /\btrending\b/i,
+    /\brelated\b/i,
+    /\brecommended\b/i,
+    /\bsuggested\b/i,
+];
+export function getSnapshotRolePriority(role) {
+    return SNAPSHOT_ROLE_PRIORITY[role] ?? 50;
+}
+export function parseSnapshotLines(snapshot) {
+    return snapshot
+        .split("\n")
+        .filter((line) => line.length > 0)
+        .map((raw, index) => {
+        const trimmed = raw.trimStart();
+        const depth = Math.floor(((raw.match(/^\s*/) ?? [""])[0].length ?? 0) / 2);
+        const role = trimmed.match(/^[-*]\s+([^\s"]+)/)?.[1] ?? "unknown";
+        const name = normalizeWhitespace(trimmed.match(/"([^"]*)"/)?.[1] ?? "");
+        const ref = trimmed.match(/\bref=([^,\]\s]+)/)?.[1];
+        const headingLevel = trimmed.match(/\blevel=(\d+)/)?.[1];
+        return {
+            depth,
+            headingLevel: headingLevel ? Number(headingLevel) : undefined,
+            index,
+            name,
+            raw,
+            ref,
+            role,
+        };
+    });
+}
+export function isNoiseName(name) {
+    return SNAPSHOT_NOISE_NAME_PATTERNS.some((pattern) => pattern.test(name));
+}
+export function isChromeSectionName(name) {
+    return SNAPSHOT_CHROME_SECTION_PATTERNS.some((pattern) => pattern.test(name));
+}
+function isNoiseSnapshotLine(line) {
+    if (line.name.length > 0 && isNoiseName(line.name))
+        return true;
+    const loweredRaw = line.raw.toLowerCase();
+    return loweredRaw.includes("promoted") || loweredRaw.includes("sponsored");
+}
+function isPotentialSegmentRootLine(line) {
+    if (!SNAPSHOT_SEGMENT_ROOT_ROLES.has(line.role))
+        return false;
+    if (isNoiseSnapshotLine(line))
+        return false;
+    if (line.role === "heading") {
+        return line.name.length > 0 && (line.headingLevel ?? 99) <= 3;
+    }
+    if (line.role === "region") {
+        return line.name.length > 0;
+    }
+    return true;
+}
+function scoreSegment(segment) {
+    const { root } = segment;
+    const distinctRefs = new Set(segment.lines.flatMap((line) => (line.ref ? [line.ref] : []))).size;
+    let score = 0;
+    score += 120 - getSnapshotRolePriority(root.role) * 8;
+    score += Math.min(distinctRefs, 16);
+    score += Math.min(segment.lines.length, 12);
+    score -= Math.min(root.index, 60) / 3;
+    score -= root.depth * 6;
+    if (root.role === "heading") {
+        if (root.headingLevel === 1)
+            score += 40;
+        else if (root.headingLevel === 2)
+            score += 22;
+        else if (root.headingLevel === 3)
+            score += 12;
+    }
+    if (root.name.length > 0)
+        score += 10;
+    if (root.name.length <= 2)
+        score -= 18;
+    if (isChromeSectionName(root.name))
+        score -= 45;
+    if (isNoiseName(root.name))
+        score -= 1000;
+    return score;
+}
+export function buildSnapshotSegments(snapshotLines) {
+    const roots = [];
+    const stack = [];
+    for (const line of snapshotLines) {
+        stack.length = line.depth;
+        if (isPotentialSegmentRootLine(line)) {
+            const normalizedName = normalizeWhitespace(line.name.toLowerCase());
+            let duplicateAncestor;
+            for (let index = stack.length - 1; index >= 0; index -= 1) {
+                const ancestor = stack[index];
+                if (normalizedName.length > 0 &&
+                    normalizeWhitespace(ancestor.name.toLowerCase()) === normalizedName &&
+                    SNAPSHOT_SEGMENT_ROOT_ROLES.has(ancestor.role)) {
+                    duplicateAncestor = ancestor;
+                    break;
+                }
+            }
+            if (!duplicateAncestor) {
+                roots.push(line);
+            }
+        }
+        stack[line.depth] = line;
+    }
+    return roots.map((root, index) => {
+        let endIndexExclusive = snapshotLines.length;
+        for (let nextIndex = index + 1; nextIndex < roots.length; nextIndex += 1) {
+            const candidate = roots[nextIndex];
+            if (candidate.depth <= root.depth) {
+                endIndexExclusive = candidate.index;
+                break;
+            }
+        }
+        const lines = snapshotLines.slice(root.index, endIndexExclusive);
+        const segment = {
+            endIndexExclusive,
+            lines,
+            root,
+            score: 0,
+            startIndex: root.index,
+        };
+        segment.score = scoreSegment(segment);
+        return segment;
+    });
+}
+export function choosePrimarySegment(segments) {
+    if (segments.length === 0)
+        return undefined;
+    return (segments.find((segment) => segment.root.role === "main" || segment.root.role === "article") ??
+        segments.find((segment) => segment.root.role === "heading" && segment.root.headingLevel === 1) ??
+        segments.find((segment) => segment.score >= 90) ??
+        [...segments].sort((left, right) => right.score - left.score || left.startIndex - right.startIndex)[0]);
+}
+export function chooseAdditionalSegments(segments, primary) {
+    if (!primary)
+        return [];
+    const seenNames = new Set([normalizeWhitespace(primary.root.name.toLowerCase())]);
+    const rankedCandidates = segments
+        .filter((segment) => segment !== primary && segment.score >= 45)
+        .sort((left, right) => {
+        const leftDistance = Math.abs(left.startIndex - primary.startIndex);
+        const rightDistance = Math.abs(right.startIndex - primary.startIndex);
+        if (leftDistance !== rightDistance)
+            return leftDistance - rightDistance;
+        if (right.score !== left.score)
+            return right.score - left.score;
+        return left.startIndex - right.startIndex;
+    });
+    const chosen = [];
+    for (const segment of rankedCandidates) {
+        if (chosen.length >= SNAPSHOT_MAX_ADDITIONAL_SECTIONS)
+            break;
+        if (isChromeSectionName(segment.root.name))
+            continue;
+        if (segment.root.role === "heading" && segment.root.name.length <= 2)
+            continue;
+        const nameKey = normalizeWhitespace(segment.root.name.toLowerCase());
+        if (nameKey && seenNames.has(nameKey))
+            continue;
+        chosen.push(segment);
+        if (nameKey)
+            seenNames.add(nameKey);
+    }
+    return chosen.sort((left, right) => left.startIndex - right.startIndex);
+}
+export function getMeaningfulSegmentLines(segment) {
+    return segment.lines.filter((line) => {
+        if (isNoiseSnapshotLine(line))
+            return false;
+        if (line.role === "generic" && !line.ref && line.name.length === 0)
+            return false;
+        if (line.role === "link" && line.name.length === 0)
+            return false;
+        return true;
+    });
+}
+function formatPreviewLine(line, baseDepth) {
+    const leadingWhitespace = (line.raw.match(/^\s*/) ?? [""])[0].length;
+    const stripChars = Math.min(leadingWhitespace, Math.max(0, baseDepth) * 2);
+    return truncateText(line.raw.slice(stripChars), SNAPSHOT_LINE_MAX_CHARS);
+}
+export function buildSegmentPreview(segment, maxLines) {
+    const meaningfulLines = getMeaningfulSegmentLines(segment);
+    if (meaningfulLines.length === 0) {
+        return { omittedCount: 0, refIds: [], lines: [] };
+    }
+    const previewLines = [];
+    const previewRefIds = new Set();
+    const seenPreviewKeys = new Set();
+    const rootDepth = segment.root.depth;
+    for (const line of meaningfulLines) {
+        if (previewLines.length >= maxLines)
+            break;
+        if (line !== segment.root) {
+            const relativeDepth = line.depth - rootDepth;
+            if (segment.root.role !== "heading" && relativeDepth > 2)
+                continue;
+            if (segment.root.name.length > 0 && line.name === segment.root.name && (line.role === "heading" || line.role === "link")) {
+                continue;
+            }
+        }
+        const key = `${line.role}:${line.name}:${line.ref ?? ""}:${line.depth}`;
+        if (seenPreviewKeys.has(key))
+            continue;
+        seenPreviewKeys.add(key);
+        previewLines.push(line);
+        if (line.ref)
+            previewRefIds.add(line.ref);
+    }
+    return {
+        omittedCount: Math.max(0, meaningfulLines.length - previewLines.length),
+        refIds: [...previewRefIds],
+        lines: previewLines.map((line) => formatPreviewLine(line, rootDepth)),
+    };
+}
+export function buildFallbackSnapshotOutline(snapshotLines) {
+    const selected = new Set();
+    for (let index = 0; index < snapshotLines.length && selected.size < 4; index += 1) {
+        if (!isNoiseSnapshotLine(snapshotLines[index]))
+            selected.add(index);
+    }
+    for (let index = 0; index < snapshotLines.length && selected.size < SNAPSHOT_FALLBACK_PREVIEW_MAX_LINES; index += 1) {
+        const line = snapshotLines[index];
+        if (isNoiseSnapshotLine(line))
+            continue;
+        if (SNAPSHOT_SIGNAL_ROLES.has(line.role) || line.ref || line.name.length > 0) {
+            selected.add(index);
+        }
+    }
+    const chosenLines = [...selected]
+        .sort((left, right) => left - right)
+        .slice(0, SNAPSHOT_FALLBACK_PREVIEW_MAX_LINES)
+        .map((index) => snapshotLines[index]);
+    return {
+        omittedCount: Math.max(0, snapshotLines.length - chosenLines.length),
+        refIds: chosenLines.flatMap((line) => (line.ref ? [line.ref] : [])),
+        lines: chosenLines.map((line) => truncateText(line.raw, SNAPSHOT_LINE_MAX_CHARS)),
+    };
+}
+export function buildRefLineOrderMap(snapshotLines) {
+    const map = new Map();
+    for (const line of snapshotLines) {
+        if (!line.ref || map.has(line.ref))
+            continue;
+        map.set(line.ref, line.index);
+    }
+    return map;
+}
+export function canUseStructuredSnapshotPreview(snapshotLines, refEntries) {
+    if (snapshotLines.length === 0)
+        return false;
+    const linesWithRecognizedRoles = snapshotLines.filter((line) => line.role !== "unknown").length;
+    const linesWithNames = snapshotLines.filter((line) => line.name.length > 0).length;
+    const parsedRefIds = new Set(snapshotLines.flatMap((line) => (line.ref ? [line.ref] : [])));
+    return (linesWithRecognizedRoles >= Math.min(snapshotLines.length, 3) ||
+        linesWithNames >= Math.min(snapshotLines.length, 3) ||
+        parsedRefIds.size >= Math.min(refEntries.length, 3));
+}

package/dist/extensions/agent-browser/lib/results/snapshot-spill.js

@@ -0,0 +1,40 @@
+/**
+ * Purpose: Persist full compacted snapshot payloads when model-facing output is shortened.
+ * Responsibilities: Write persistent or secure-temp snapshot spill files and merge spill retention metadata into the session artifact manifest.
+ * Scope: Snapshot spill artifact lifecycle only; preview planning and presentation text live in snapshot.ts and sibling modules.
+ * Usage: Snapshot presentation calls these helpers after deciding a snapshot is too large for inline output.
+ * Invariants/Assumptions: Explicit full-output paths are reported but not deleted here; retention state mirrors the backing storage scope.
+ */
+import { writePersistentSessionArtifactFile, writeSecureTempFile } from "../temp.js";
+import { buildEvictedSessionArtifactEntries, formatSessionArtifactRetentionSummary, mergeSessionArtifactManifest, } from "./artifact-manifest.js";
+const SNAPSHOT_SPILL_FILE_PREFIX = "pi-agent-browser-snapshot";
+export async function writeSnapshotSpillFile(data, persistentArtifactStore) {
+    const options = {
+        content: JSON.stringify(data, null, 2),
+        prefix: SNAPSHOT_SPILL_FILE_PREFIX,
+        suffix: ".json",
+    };
+    if (persistentArtifactStore) {
+        const result = await writePersistentSessionArtifactFile({ ...options, store: persistentArtifactStore });
+        return { ...result, storageScope: "persistent-session" };
+    }
+    return { evictedArtifacts: [], path: await writeSecureTempFile(options), storageScope: "process-temp" };
+}
+export function applySnapshotArtifactManifest(options) {
+    if (!options.fullOutputPath || !options.spill)
+        return {};
+    const nowMs = Date.now();
+    const entries = [
+        {
+            command: options.command,
+            createdAtMs: nowMs,
+            kind: "spill",
+            path: options.fullOutputPath,
+            retentionState: options.spill.storageScope === "persistent-session" ? "live" : "ephemeral",
+            storageScope: options.spill.storageScope,
+        },
+        ...buildEvictedSessionArtifactEntries(options.spill.evictedArtifacts, nowMs),
+    ];
+    const artifactManifest = mergeSessionArtifactManifest({ base: options.baseManifest, entries, nowMs });
+    return artifactManifest ? { artifactManifest, artifactRetentionSummary: formatSessionArtifactRetentionSummary(artifactManifest) } : {};
+}