pi-agent-browser-native 0.9.2 → 0.9.4

package/dist/extensions/agent-browser/lib/orchestration/browser-run/prepare/snapshot-filter-data.js

@@ -0,0 +1,150 @@
+import { isRecord } from "../../../parsing.js";
+export function hasSnapshotText(value) {
+    return value !== undefined && value !== "";
+}
+function filterOperand(tokens, index) {
+    const token = tokens[index];
+    if (token !== "--search" && token !== "--filter") {
+        return undefined;
+    }
+    const value = tokens.at(index + 1);
+    if (value === undefined || value.startsWith("-")) {
+        return undefined;
+    }
+    if (token === "--search") {
+        return { search: value };
+    }
+    const role = /^role=(.+)$/i.exec(value.trim())?.at(1);
+    return hasSnapshotText(role) ? { role: role.trim().toLowerCase() } : {};
+}
+export function snapshotHasTextFilters(request) {
+    return hasSnapshotText(request.role) || hasSnapshotText(request.search);
+}
+export function parseSnapshotFilterRequest(commandTokens) {
+    if (commandTokens[0] !== "snapshot") {
+        return undefined;
+    }
+    const cleanArgs = [];
+    let role;
+    let search;
+    for (let index = 0; index < commandTokens.length; index += 1) {
+        const token = commandTokens[index];
+        // Wrapper filters require the complete native tree, never a revision-relative patch.
+        if (["--delta", "--full", "--viewport", "--diff"].includes(token)) {
+            continue;
+        }
+        const operand = filterOperand(commandTokens, index);
+        if (operand) {
+            if (operand.search !== undefined) {
+                search = operand.search;
+            }
+            if (operand.role !== undefined) {
+                role = operand.role;
+            }
+            index += 1;
+        }
+        else {
+            cleanArgs.push(token);
+        }
+    }
+    const viewport = commandTokens.includes("--viewport");
+    const diff = commandTokens.includes("--diff");
+    return snapshotHasTextFilters({ role, search }) || viewport || diff
+        ? { cleanArgs, diff, role, search, viewport }
+        : undefined;
+}
+export function buildSnapshotDiff(previous, current) {
+    if (!current) {
+        return undefined;
+    }
+    const currentRefs = new Map(Object.entries(current.refs ?? {}));
+    const previousRefs = new Map(Object.entries(previous?.refs ?? {}));
+    if (!previous) {
+        return {
+            addedRefs: [...currentRefs.keys()],
+            changedRefs: [],
+            removedRefs: [],
+            summary: `Snapshot diff: no previous snapshot; ${currentRefs.size} current refs recorded.`,
+            unchangedRefs: 0,
+        };
+    }
+    const addedRefs = [];
+    const changedRefs = [];
+    let unchangedRefs = 0;
+    for (const [refId, currentRef] of currentRefs) {
+        const previousRef = previousRefs.get(refId);
+        if (!previousRef) {
+            addedRefs.push(refId);
+        }
+        else if (previousRef.role !== currentRef.role || previousRef.name !== currentRef.name) {
+            changedRefs.push(refId);
+        }
+        else {
+            unchangedRefs += 1;
+        }
+    }
+    const removedRefs = [...previousRefs.keys()].filter((refId) => !currentRefs.has(refId));
+    return {
+        addedRefs,
+        changedRefs,
+        removedRefs,
+        summary: `Snapshot diff: +${addedRefs.length} / -${removedRefs.length} / Δ${changedRefs.length} refs versus previous snapshot.`,
+        unchangedRefs,
+    };
+}
+function refMatches(value, request) {
+    if (!isRecord(value)) {
+        return false;
+    }
+    const role = typeof value.role === "string" ? value.role.toLowerCase() : "";
+    const name = typeof value.name === "string" ? value.name : "";
+    const search = request.search?.trim().toLowerCase();
+    return ((!hasSnapshotText(request.role) || role === request.role) &&
+        (!hasSnapshotText(search) || `${role} ${name}`.toLowerCase().includes(search)));
+}
+function snapshotLineMatches(line, refs, search) {
+    return ((hasSnapshotText(search) && line.toLowerCase().includes(search)) ||
+        [...refs].some((refId) => line.includes(`[ref=${refId}]`) || line.includes(`ref=${refId}`)));
+}
+function filterDescription(request) {
+    return [
+        hasSnapshotText(request.role) ? `role=${request.role}` : undefined,
+        hasSnapshotText(request.search) ? `search=${JSON.stringify(request.search)}` : undefined,
+    ]
+        .filter((part) => part !== undefined)
+        .join(", ");
+}
+export function filterSnapshotData(data, request) {
+    if (!isRecord(data)) {
+        return undefined;
+    }
+    const refs = isRecord(data.refs) ? data.refs : {};
+    const snapshot = typeof data.snapshot === "string" ? data.snapshot : "";
+    const lines = snapshot.split(/\r?\n/);
+    if (!hasSnapshotText(request.role) && !hasSnapshotText(request.search)) {
+        const totalLines = lines.filter((line) => line.length > 0).length;
+        return {
+            data,
+            matchedRefs: Object.keys(refs).length,
+            totalRefs: Object.keys(refs).length,
+            totalLines,
+            visibleLines: totalLines,
+        };
+    }
+    const matchingRefs = Object.entries(refs).filter(([, value]) => refMatches(value, request));
+    const ids = new Set(matchingRefs.map(([id]) => id));
+    const visibleLines = lines.filter((line) => snapshotLineMatches(line, ids, request.search?.trim().toLowerCase()));
+    return {
+        data: {
+            ...data,
+            refs: Object.fromEntries(matchingRefs),
+            snapshot: visibleLines.length > 0
+                ? visibleLines.join("\n")
+                : `(no snapshot lines matched ${filterDescription(request)})`,
+        },
+        matchedRefs: matchingRefs.length,
+        totalRefs: Object.keys(refs).length,
+        totalLines: lines.filter((line) => line.length > 0).length,
+        visibleLines: visibleLines.length,
+    };
+}

package/dist/extensions/agent-browser/lib/orchestration/browser-run/prepare/snapshot-filter.js

@@ -1,280 +1,165 @@
-import { isRecord } from "../../../parsing.js";
 import { buildAgentBrowserResultCategoryDetails } from "../../../results/categories.js";
 import { buildSnapshotPresentation } from "../../../results/snapshot.js";
-import { extractRefSnapshotFromData } from "../../../session-page-state.js";
-import { redactSensitiveText, redactSensitiveValue } from "../../../runtime.js";
-import { collectScrollPositionSnapshot } from "../diagnostics.js";
+import { extractRefSnapshotFromData, } from "../../../session-page-state.js";
+import { redactSensitiveValue } from "../../../runtime-redaction.js";
+import { collectScrollPositionSnapshot } from "../interaction-diagnostics.js";
 import { buildSessionDetailFields, runSessionCommandData } from "../session-state.js";
-function parseSnapshotFilterRequest(commandTokens) {
-    if (commandTokens[0] !== "snapshot")
+import { attachRenderedTextMatchRefs, buildRenderedTextSearchEval, extractRenderedTextSearchResult, formatRenderedTextSearchMatches, } from "./snapshot-rendered-text.js";
+import { buildSnapshotDiff, filterSnapshotData, hasSnapshotText, parseSnapshotFilterRequest, } from "./snapshot-filter-data.js";
+async function collectRenderedText(options, request, snapshotData) {
+    if (!hasSnapshotText(request.search)) {
         return undefined;
-    const cleanArgs = [];
-    let role;
-    let search;
-    for (let index = 0; index < commandTokens.length; index += 1) {
-        const token = commandTokens[index];
-        // Wrapper filters need a full native tree, not a revision-relative patch.
-        if (token === "--delta" || token === "--full")
-            continue;
-        if (token === "--viewport")
-            continue;
-        if (token === "--diff")
-            continue;
-        if (token === "--search") {
-            const value = commandTokens[index + 1];
-            if (typeof value === "string" && !value.startsWith("-")) {
-                search = value;
-                index += 1;
-                continue;
-            }
-        }
-        if (token === "--filter") {
-            const value = commandTokens[index + 1];
-            if (typeof value === "string" && !value.startsWith("-")) {
-                const roleMatch = /^role=(.+)$/i.exec(value.trim());
-                if (roleMatch?.[1])
-                    role = roleMatch[1].trim().toLowerCase();
-                index += 1;
-                continue;
-            }
-        }
-        cleanArgs.push(token);
     }
-    const viewport = commandTokens.includes("--viewport");
-    const diff = commandTokens.includes("--diff");
-    if (!search && !role && !viewport && !diff)
-        return undefined;
-    return { cleanArgs, diff, role, search, viewport };
+    const data = await runSessionCommandData({
+        ...options,
+        args: ["eval", "--stdin"],
+        stdin: buildRenderedTextSearchEval(request.search),
+    });
+    const result = extractRenderedTextSearchResult(data);
+    return result
+        ? { ...result, matches: attachRenderedTextMatchRefs(result.matches, snapshotData) }
+        : undefined;
 }
-const RENDERED_TEXT_SEARCH_MAX_MATCHES = 8;
-function buildRenderedTextSearchEval(search) {
-    return `(() => {
-  const query = ${JSON.stringify(search.trim().toLowerCase())};
-  const limit = ${RENDERED_TEXT_SEARCH_MAX_MATCHES};
-  const normalize = (value) => String(value ?? "").replace(/\\s+/g, " ").trim();
-  const attributeTextOf = (element) => [element.getAttribute("aria-label"), element.getAttribute("title"), element.getAttribute("placeholder")].filter(Boolean).join(" ");
-  const searchableTextOf = (element) => normalize([attributeTextOf(element), element.textContent].filter(Boolean).join(" "));
-  const renderedTextOf = (element) => normalize([attributeTextOf(element), element instanceof HTMLElement ? element.innerText : element.textContent].filter(Boolean).join(" "));
-  const isRendered = (element) => {
-    if (!(element instanceof Element) || element.getClientRects().length === 0) return false;
-    const visibility = getComputedStyle(element).visibility;
-    if (visibility === "hidden" || visibility === "collapse") return false;
-    for (let current = element; current; current = current.parentElement) {
-      if (Number(getComputedStyle(current).opacity) === 0) return false;
+async function collectSnapshotEvidence(options, request) {
+    const snapshotData = await runSessionCommandData({
+        args: request.cleanArgs,
+        cwd: options.cwd,
+        namespace: options.namespace,
+        sessionName: options.sessionName,
+        signal: options.signal,
+    });
+    const filtered = filterSnapshotData(snapshotData, request);
+    if (!filtered) {
+        return undefined;
     }
-    return true;
-  };
-  const validationPattern = /(?:^|[-_\\s])(?:error|invalid|validation|warning)(?:$|[-_\\s])/i;
-  const validationAncestor = (element) => {
-    for (let current = element; current && current !== document.body; current = current.parentElement) {
-      const role = current.getAttribute("role");
-      const live = current.getAttribute("aria-live");
-      const descriptor = [current.id, current.className, current.getAttribute("data-testid")].map(normalize).join(" ");
-      if (["alert", "alertdialog", "status"].includes(role || "") || current.getAttribute("aria-invalid") === "true" || (live && live !== "off") || validationPattern.test(descriptor)) return current;
+    const renderedTextSearch = await collectRenderedText({
+        cwd: options.cwd,
+        namespace: options.namespace,
+        sessionName: options.sessionName,
+        signal: options.signal,
+    }, request, snapshotData);
+    const viewport = request.viewport
+        ? await collectScrollPositionSnapshot({
+            cwd: options.cwd,
+            namespace: options.namespace,
+            sessionName: options.sessionName,
+            signal: options.signal,
+        })
+        : undefined;
+    const fullSnapshot = extractRefSnapshotFromData(snapshotData);
+    const diff = request.diff
+        ? buildSnapshotDiff(options.previousRefSnapshot, fullSnapshot)
+        : undefined;
+    if (fullSnapshot) {
+        options.sessionPageState.applyRefSnapshot({
+            sessionName: options.sessionStateKey ?? options.sessionName,
+            snapshot: fullSnapshot,
+            update: options.sessionPageStateUpdate,
+        });
     }
-    return null;
-  };
-  const candidates = Array.from(document.querySelectorAll("body *")).filter((element) => searchableTextOf(element).toLowerCase().includes(query));
-  const candidateSet = new Set(candidates);
-  const minimal = candidates.filter((element) => !Array.from(element.children).some((child) => candidateSet.has(child)));
-  const rendered = minimal.filter((element) => isRendered(element) && renderedTextOf(element).toLowerCase().includes(query));
-  const matches = rendered.map((element, index) => {
-    const semantic = validationAncestor(element);
-    const source = semantic || element;
-    const text = renderedTextOf(element);
-    const matchIndex = text.toLowerCase().indexOf(query);
-    const start = Math.max(0, matchIndex - 80);
-    const snippet = text.slice(start, start + 240);
-    const rect = element.getBoundingClientRect();
-    const name = normalize(element.getAttribute("aria-label") || element.getAttribute("title") || element.getAttribute("placeholder")) || undefined;
-    return {
-      index,
-      kind: semantic ? "validation" : "text",
-      name,
-      offscreen: rect.bottom < 0 || rect.right < 0 || rect.top > innerHeight || rect.left > innerWidth,
-      role: source.getAttribute("role") || undefined,
-      tagName: element.tagName.toLowerCase(),
-      text: snippet,
-    };
-  }).sort((left, right) => (left.kind === right.kind ? left.index - right.index : left.kind === "validation" ? -1 : 1));
-  const unique = [];
-  const seen = new Set();
-  for (const match of matches) {
-    const key = [match.kind, match.role, match.name, match.text].join("\\n");
-    if (seen.has(key)) continue;
-    seen.add(key);
-    const { index, ...visible } = match;
-    unique.push(visible);
-  }
-  return { matches: unique.slice(0, limit), totalMatches: unique.length, truncated: unique.length > limit };
-})()`;
+    return { filtered, renderedTextSearch, viewport, fullSnapshot, diff };
 }
-function extractRenderedTextSearchResult(data) {
-    const result = isRecord(data) && isRecord(data.result) ? data.result : data;
-    if (!isRecord(result) || !Array.isArray(result.matches))
-        return undefined;
-    const matches = result.matches.flatMap((value) => {
-        if (!isRecord(value) || (value.kind !== "text" && value.kind !== "validation") || typeof value.offscreen !== "boolean" || typeof value.tagName !== "string" || typeof value.text !== "string")
-            return [];
-        return [{
-                kind: value.kind,
-                ...(typeof value.name === "string" ? { name: redactSensitiveText(value.name) } : {}),
-                offscreen: value.offscreen,
-                ...(typeof value.role === "string" ? { role: value.role } : {}),
-                tagName: value.tagName,
-                text: redactSensitiveText(value.text),
-            }];
-    }).slice(0, RENDERED_TEXT_SEARCH_MAX_MATCHES);
-    const totalMatches = typeof result.totalMatches === "number" && Number.isInteger(result.totalMatches) && result.totalMatches >= matches.length ? result.totalMatches : matches.length;
-    return { matches, totalMatches, truncated: result.truncated === true || totalMatches > matches.length };
+function snapshotFilterSummary(request, evidence) {
+    if (hasSnapshotText(request.role) || hasSnapshotText(request.search)) {
+        const role = hasSnapshotText(request.role) ? ` role=${request.role}` : "";
+        const search = hasSnapshotText(request.search)
+            ? ` search ${JSON.stringify(request.search)}`
+            : "";
+        return `Snapshot filter: ${evidence.filtered.matchedRefs}/${evidence.filtered.totalRefs} direct refs matched${role}${search}; ${evidence.filtered.visibleLines} surrounding snapshot line${evidence.filtered.visibleLines === 1 ? "" : "s"} shown.`;
+    }
+    return request.diff
+        ? (evidence.diff?.summary ?? "Snapshot diff unavailable.")
+        : "Snapshot viewport metadata collected.";
 }
-function attachRenderedTextMatchRefs(matches, snapshotData) {
-    if (!isRecord(snapshotData) || !isRecord(snapshotData.refs))
-        return matches;
-    const refs = snapshotData.refs;
-    return matches.map((match) => {
-        if (!match.name)
-            return match;
-        const normalizedName = match.name.replace(/\s+/g, " ").trim().toLowerCase();
-        const candidates = Object.entries(refs).filter(([, value]) => {
-            if (!isRecord(value) || typeof value.name !== "string")
-                return false;
-            const nameMatches = value.name.replace(/\s+/g, " ").trim().toLowerCase() === normalizedName;
-            return nameMatches && (!match.role || typeof value.role !== "string" || value.role.toLowerCase() === match.role.toLowerCase());
-        });
-        return candidates.length === 1 ? { ...match, ref: candidates[0][0] } : match;
-    });
+function viewportText(viewport) {
+    return viewport
+        ? `Viewport: ${viewport.innerWidth}×${viewport.innerHeight}, scroll ${viewport.scrollX},${viewport.scrollY}, document ${viewport.scrollWidth}×${viewport.scrollHeight}, sampled scroll containers ${viewport.containers.length}/${viewport.containerCount}.`
+        : undefined;
 }
-function formatRenderedTextSearchMatches(result) {
-    if (!result || result.matches.length === 0)
-        return undefined;
-    const lines = result.matches.map((match) => {
-        const context = [match.kind === "validation" ? "validation" : undefined, match.offscreen ? "outside viewport" : undefined, match.role, match.tagName, match.ref ? `@${match.ref}` : undefined].filter(Boolean).join(", ");
-        return `- ${JSON.stringify(match.text)}${context ? ` (${context})` : ""}`;
-    });
-    if (result.truncated)
-        lines.push(`- ... (${result.totalMatches - result.matches.length} additional rendered-text matches omitted)`);
-    return ["Rendered page text matches:", ...lines].join("\n");
+function snapshotPrefix(request, evidence, summary) {
+    const diffText = hasSnapshotText(request.role) || hasSnapshotText(request.search)
+        ? evidence.diff?.summary
+        : undefined;
+    return [
+        summary,
+        formatRenderedTextSearchMatches(evidence.renderedTextSearch),
+        diffText,
+        viewportText(evidence.viewport),
+    ]
+        .filter((line) => line !== undefined)
+        .join("\n\n");
 }
-function buildSnapshotDiff(previous, current) {
-    if (!current)
-        return undefined;
-    const currentRefs = current.refs ?? {};
-    const previousRefs = previous?.refs ?? {};
-    if (!previous)
-        return { addedRefs: Object.keys(currentRefs), changedRefs: [], removedRefs: [], summary: `Snapshot diff: no previous snapshot; ${Object.keys(currentRefs).length} current refs recorded.`, unchangedRefs: 0 };
-    const addedRefs = [];
-    const removedRefs = [];
-    const changedRefs = [];
-    let unchangedRefs = 0;
-    for (const refId of Object.keys(currentRefs)) {
-        const currentRef = currentRefs[refId];
-        const previousRef = previousRefs[refId];
-        if (!previousRef) {
-            addedRefs.push(refId);
-            continue;
-        }
-        if (previousRef.role !== currentRef.role || previousRef.name !== currentRef.name)
-            changedRefs.push(refId);
-        else
-            unchangedRefs += 1;
+async function presentSnapshotFilter(options, evidence, prefix) {
+    const presentation = options.modelVisible === false
+        ? { content: [], data: redactSensitiveValue(evidence.filtered.data), summary: "Snapshot" }
+        : await buildSnapshotPresentation(evidence.filtered.data, options.persistentArtifactStore, options.artifactManifest);
+    const first = presentation.content.at(0);
+    const content = [...presentation.content];
+    if (first?.type === "text") {
+        content[0] = { ...first, text: `${prefix}\n\n${first.text}` };
     }
-    for (const refId of Object.keys(previousRefs))
-        if (!currentRefs[refId])
-            removedRefs.push(refId);
-    return { addedRefs, changedRefs, removedRefs, summary: `Snapshot diff: +${addedRefs.length} / -${removedRefs.length} / Δ${changedRefs.length} refs versus previous snapshot.`, unchangedRefs };
+    return { ...presentation, content };
 }
-function filterSnapshotData(data, request) {
-    if (!isRecord(data))
+function snapshotFilterDetails(request, evidence) {
+    if (!hasSnapshotText(request.role) && !hasSnapshotText(request.search)) {
         return undefined;
-    const refs = isRecord(data.refs) ? data.refs : {};
-    const snapshot = typeof data.snapshot === "string" ? data.snapshot : "";
-    const normalizedSearch = request.search?.trim().toLowerCase();
-    const matchingRefIds = new Set();
-    for (const [refId, refValue] of Object.entries(refs)) {
-        if (!isRecord(refValue))
-            continue;
-        const role = typeof refValue.role === "string" ? refValue.role.toLowerCase() : "";
-        const name = typeof refValue.name === "string" ? refValue.name : "";
-        const roleMatches = request.role ? role === request.role : true;
-        const searchMatches = normalizedSearch ? `${role} ${name}`.toLowerCase().includes(normalizedSearch) : true;
-        if (roleMatches && searchMatches)
-            matchingRefIds.add(refId);
     }
-    const lines = snapshot.split(/\r?\n/);
-    const visibleLines = lines.filter((line) => {
-        const normalizedLine = line.toLowerCase();
-        if (normalizedSearch && normalizedLine.includes(normalizedSearch))
-            return true;
-        return [...matchingRefIds].some((refId) => line.includes(`[ref=${refId}]`) || line.includes(`ref=${refId}`));
-    });
-    const filteredRefs = Object.fromEntries(Object.entries(refs).filter(([refId]) => matchingRefIds.has(refId)));
-    const description = [request.role ? `role=${request.role}` : undefined, request.search ? `search=${JSON.stringify(request.search)}` : undefined].filter((part) => part !== undefined).join(", ");
-    const filteredSnapshot = visibleLines.length > 0 ? visibleLines.join("\n") : `(no snapshot lines matched ${description})`;
     return {
-        data: { ...data, refs: filteredRefs, snapshot: filteredSnapshot },
-        matchedRefs: Object.keys(filteredRefs).length,
-        totalRefs: Object.keys(refs).length,
-        totalLines: lines.filter((line) => line.length > 0).length,
-        visibleLines: visibleLines.length,
+        cleanArgs: request.cleanArgs,
+        matchedRefs: evidence.filtered.matchedRefs,
+        renderedTextMatches: evidence.renderedTextSearch?.matches,
+        renderedTextTotalMatches: evidence.renderedTextSearch?.totalMatches,
+        renderedTextTruncated: evidence.renderedTextSearch?.truncated,
+        role: request.role,
+        search: request.search,
+        totalLines: evidence.filtered.totalLines,
+        totalRefs: evidence.filtered.totalRefs,
+        visibleLines: evidence.filtered.visibleLines,
+    };
+}
+function snapshotToolResult(options, request, evidence, presentation) {
+    const summary = snapshotFilterSummary(request, evidence);
+    return {
+        content: [...presentation.content],
+        details: {
+            args: options.redactedArgs,
+            artifactManifest: presentation.artifactManifest,
+            artifactRetentionSummary: presentation.artifactRetentionSummary,
+            command: "snapshot",
+            compatibilityWorkaround: options.compatibilityWorkaround,
+            data: presentation.data,
+            effectiveArgs: options.effectiveArgs,
+            fullOutputPath: presentation.fullOutputPath,
+            fullOutputPaths: presentation.fullOutputPaths,
+            refSnapshot: evidence.fullSnapshot,
+            sessionMode: options.sessionMode,
+            snapshotDiff: evidence.diff,
+            snapshotFilter: snapshotFilterDetails(request, evidence),
+            snapshotViewport: evidence.viewport,
+            ...buildAgentBrowserResultCategoryDetails({
+                args: options.effectiveArgs,
+                command: "snapshot",
+                succeeded: true,
+            }),
+            ...buildSessionDetailFields(options.sessionName, options.usedImplicitSession, options.namespace, options.managedSessionRestoreDisabled()),
+            summary,
+        },
+        isError: false,
     };
 }
 export async function trySnapshotFilter(options) {
     const request = parseSnapshotFilterRequest(options.commandTokens);
-    if (!request || !options.sessionName)
+    if (!request || !hasSnapshotText(options.sessionName)) {
         return undefined;
-    const snapshotData = await runSessionCommandData({ args: request.cleanArgs, cwd: options.cwd, namespace: options.namespace, sessionName: options.sessionName, signal: options.signal });
-    const filtered = request.role || request.search ? filterSnapshotData(snapshotData, request) : isRecord(snapshotData) ? { data: snapshotData, matchedRefs: isRecord(snapshotData.refs) ? Object.keys(snapshotData.refs).length : 0, totalLines: typeof snapshotData.snapshot === "string" ? snapshotData.snapshot.split(/\r?\n/).filter((line) => line.length > 0).length : 0, totalRefs: isRecord(snapshotData.refs) ? Object.keys(snapshotData.refs).length : 0, visibleLines: typeof snapshotData.snapshot === "string" ? snapshotData.snapshot.split(/\r?\n/).filter((line) => line.length > 0).length : 0 } : undefined;
-    if (!filtered)
+    }
+    const evidence = await collectSnapshotEvidence({ ...options, sessionName: options.sessionName }, request);
+    if (!evidence) {
         return undefined;
-    const renderedTextSearch = request.search
-        ? extractRenderedTextSearchResult(await runSessionCommandData({ args: ["eval", "--stdin"], cwd: options.cwd, namespace: options.namespace, sessionName: options.sessionName, signal: options.signal, stdin: buildRenderedTextSearchEval(request.search) }))
-        : undefined;
-    if (renderedTextSearch)
-        renderedTextSearch.matches = attachRenderedTextMatchRefs(renderedTextSearch.matches, snapshotData);
-    const viewport = request.viewport ? await collectScrollPositionSnapshot({ cwd: options.cwd, namespace: options.namespace, sessionName: options.sessionName, signal: options.signal }) : undefined;
-    const fullSnapshot = extractRefSnapshotFromData(snapshotData);
-    const diff = request.diff ? buildSnapshotDiff(options.previousRefSnapshot, fullSnapshot) : undefined;
-    if (fullSnapshot)
-        options.sessionPageState.applyRefSnapshot({ sessionName: options.sessionStateKey ?? options.sessionName, snapshot: fullSnapshot, update: options.sessionPageStateUpdate });
-    const presentation = options.modelVisible === false
-        ? { content: [], data: redactSensitiveValue(filtered.data), summary: "Snapshot" }
-        : await buildSnapshotPresentation(filtered.data, options.persistentArtifactStore, options.artifactManifest);
-    const summary = request.role || request.search
-        ? `Snapshot filter: ${filtered.matchedRefs}/${filtered.totalRefs} direct refs matched${request.role ? ` role=${request.role}` : ""}${request.search ? ` search ${JSON.stringify(request.search)}` : ""}; ${filtered.visibleLines} surrounding snapshot line${filtered.visibleLines === 1 ? "" : "s"} shown.`
-        : request.diff
-            ? diff?.summary ?? "Snapshot diff unavailable."
-            : "Snapshot viewport metadata collected.";
-    const viewportText = viewport ? `Viewport: ${viewport.innerWidth}×${viewport.innerHeight}, scroll ${viewport.scrollX},${viewport.scrollY}, document ${viewport.scrollWidth}×${viewport.scrollHeight}, sampled scroll containers ${viewport.containers.length}/${viewport.containerCount}.` : undefined;
-    const diffText = diff && (request.role || request.search) ? diff.summary : undefined;
-    const renderedTextSearchText = formatRenderedTextSearchMatches(renderedTextSearch);
-    const prefix = [summary, renderedTextSearchText, diffText, viewportText].filter((line) => line !== undefined).join("\n\n");
-    if (presentation.content[0]?.type === "text")
-        presentation.content[0] = { ...presentation.content[0], text: `${prefix}\n\n${presentation.content[0].text}` };
+    }
+    const summary = snapshotFilterSummary(request, evidence);
+    const presentation = await presentSnapshotFilter(options, evidence, snapshotPrefix(request, evidence, summary));
     return {
         artifactManifest: presentation.artifactManifest,
-        result: {
-            content: presentation.content,
-            details: {
-                args: options.redactedArgs,
-                artifactManifest: presentation.artifactManifest,
-                artifactRetentionSummary: presentation.artifactRetentionSummary,
-                command: "snapshot",
-                compatibilityWorkaround: options.compatibilityWorkaround,
-                data: presentation.data,
-                effectiveArgs: options.effectiveArgs,
-                fullOutputPath: presentation.fullOutputPath,
-                fullOutputPaths: presentation.fullOutputPaths,
-                refSnapshot: fullSnapshot,
-                sessionMode: options.sessionMode,
-                snapshotDiff: diff,
-                snapshotFilter: request.role || request.search ? { cleanArgs: request.cleanArgs, matchedRefs: filtered.matchedRefs, renderedTextMatches: renderedTextSearch?.matches, renderedTextTotalMatches: renderedTextSearch?.totalMatches, renderedTextTruncated: renderedTextSearch?.truncated, role: request.role, search: request.search, totalLines: filtered.totalLines, totalRefs: filtered.totalRefs, visibleLines: filtered.visibleLines } : undefined,
-                snapshotViewport: viewport,
-                ...buildAgentBrowserResultCategoryDetails({ args: options.effectiveArgs, command: "snapshot", succeeded: true }),
-                ...buildSessionDetailFields(options.sessionName, options.usedImplicitSession, options.namespace, options.managedSessionRestoreDisabled()),
-                summary,
-            },
-            isError: false,
-        },
+        result: snapshotToolResult(options, request, evidence, presentation),
     };
 }