pi-agent-browser-native 0.2.48 → 0.2.49

package/dist/extensions/agent-browser/lib/orchestration/browser-run/prepare/direct-anchor-download.js

@@ -0,0 +1,141 @@
+import { mkdir, stat, writeFile } from "node:fs/promises";
+import { dirname, resolve } from "node:path";
+import { isRecord } from "../../../parsing.js";
+import { buildAgentBrowserResultCategoryDetails } from "../../../results.js";
+import { formatSessionArtifactRetentionSummary, mergeSessionArtifactManifest } from "../../../results/artifact-manifest.js";
+import { redactSensitiveText } from "../../../runtime.js";
+import { buildSessionDetailFields, runSessionCommandData } from "../session-state.js";
+const DIRECT_ANCHOR_DOWNLOAD_MAX_BYTES = 2 * 1024 * 1024;
+function getDirectDownloadRequest(commandTokens) {
+    if (commandTokens[0] !== "download" || commandTokens.length !== 3)
+        return undefined;
+    const selector = commandTokens[1];
+    const path = commandTokens[2];
+    if (!selector || !path || selector.startsWith("@"))
+        return undefined;
+    return { path, selector };
+}
+function buildAnchorDownloadProbe(selector) {
+    return `(async () => {\n  const selector = ${JSON.stringify(selector)};\n  const maxBytes = ${DIRECT_ANCHOR_DOWNLOAD_MAX_BYTES};\n  const isLoopbackHttpUrl = (url) => (url.protocol === "http:" || url.protocol === "https:") && (url.hostname === "localhost" || url.hostname === "127.0.0.1" || url.hostname === "::1" || url.hostname === "[::1]");\n  const element = document.querySelector(selector);\n  const anchor = element?.closest?.("a[href]");\n  const pageUrl = location.href;\n  const page = new URL(pageUrl);\n  if (!anchor) return { status: "no-anchor", pageUrl };\n  const href = anchor.href;\n  const anchorUrl = new URL(href, pageUrl);\n  if (!isLoopbackHttpUrl(page)) return { download: anchor.getAttribute("download") || "", href, pageUrl, status: "not-loopback-page" };\n  if (anchorUrl.origin !== page.origin) return { download: anchor.getAttribute("download") || "", href, pageUrl, status: "not-same-origin" };\n  if (!isLoopbackHttpUrl(anchorUrl)) return { download: anchor.getAttribute("download") || "", href, pageUrl, status: "not-loopback-href" };\n  const response = await fetch(anchorUrl.href, { credentials: "include", redirect: "manual" });\n  if (!response.ok) return { download: anchor.getAttribute("download") || "", href, pageUrl, responseUrl: response.url, status: "fetch-failed", statusCode: response.status };\n  const responseUrl = new URL(response.url);\n  if (!isLoopbackHttpUrl(responseUrl) || responseUrl.origin !== page.origin) return { download: anchor.getAttribute("download") || "", href, pageUrl, responseUrl: response.url, status: "not-loopback-response" };\n  const buffer = await response.arrayBuffer();\n  if (buffer.byteLength > maxBytes) return { download: anchor.getAttribute("download") || "", href, pageUrl, responseUrl: response.url, sizeBytes: buffer.byteLength, status: "too-large" };\n  const bytes = new Uint8Array(buffer);\n  let binary = "";\n  for (let index = 0; index < bytes.length; index += 32768) binary += String.fromCharCode(...bytes.subarray(index, index + 32768));\n  return { bodyBase64: btoa(binary), contentType: response.headers.get("content-type") || "", download: anchor.getAttribute("download") || "", href, pageUrl, responseUrl: response.url, sizeBytes: buffer.byteLength, status: "fetched-anchor" };\n})()`;
+}
+function isLoopbackHttpUrl(url) {
+    return (url.protocol === "http:" || url.protocol === "https:") && (url.hostname === "localhost" || url.hostname === "127.0.0.1" || url.hostname === "::1" || url.hostname === "[::1]");
+}
+export async function tryDirectAnchorDownload(options) {
+    const request = getDirectDownloadRequest(options.commandTokens);
+    if (!request || !options.sessionName)
+        return undefined;
+    try {
+        const probeData = await runSessionCommandData({
+            args: ["eval", "--stdin"],
+            cwd: options.cwd,
+            sessionName: options.sessionName,
+            signal: options.signal,
+            stdin: buildAnchorDownloadProbe(request.selector),
+        });
+        const probe = isRecord(probeData) && isRecord(probeData.result) ? probeData.result : probeData;
+        if (!isRecord(probe) || probe.status !== "fetched-anchor" || typeof probe.href !== "string" || typeof probe.pageUrl !== "string" || typeof probe.bodyBase64 !== "string")
+            return undefined;
+        const href = new URL(probe.href);
+        const pageUrl = new URL(probe.pageUrl);
+        const responseUrl = typeof probe.responseUrl === "string" ? new URL(probe.responseUrl) : href;
+        if (!isLoopbackHttpUrl(pageUrl) || !isLoopbackHttpUrl(href) || !isLoopbackHttpUrl(responseUrl) || href.origin !== pageUrl.origin || responseUrl.origin !== pageUrl.origin)
+            return undefined;
+        const body = Buffer.from(probe.bodyBase64, "base64");
+        if (body.byteLength > DIRECT_ANCHOR_DOWNLOAD_MAX_BYTES)
+            return undefined;
+        if (typeof probe.sizeBytes === "number" && probe.sizeBytes !== body.byteLength)
+            return undefined;
+        const absolutePath = resolve(options.cwd, request.path);
+        await mkdir(dirname(absolutePath), { recursive: true });
+        await writeFile(absolutePath, body);
+        const fileStat = await stat(absolutePath);
+        const mediaType = typeof probe.contentType === "string" && probe.contentType.length > 0 ? probe.contentType : undefined;
+        const manifestEntry = {
+            absolutePath,
+            command: "download",
+            createdAtMs: Date.now(),
+            cwd: options.cwd,
+            exists: true,
+            kind: "download",
+            mediaType,
+            path: absolutePath,
+            requestedPath: request.path,
+            retentionState: "live",
+            session: options.sessionName,
+            sizeBytes: fileStat.size,
+            storageScope: "explicit-path",
+        };
+        const artifactManifest = mergeSessionArtifactManifest({ base: options.artifactManifest, entries: [manifestEntry] });
+        const artifactRetentionSummary = artifactManifest ? formatSessionArtifactRetentionSummary(artifactManifest) : undefined;
+        const artifact = {
+            absolutePath,
+            artifactType: "download",
+            command: "download",
+            cwd: options.cwd,
+            exists: true,
+            kind: "download",
+            mediaType,
+            path: absolutePath,
+            requestedPath: request.path,
+            session: options.sessionName,
+            sizeBytes: fileStat.size,
+            status: "saved",
+        };
+        const artifactVerification = {
+            artifacts: [{
+                    absolutePath,
+                    exists: true,
+                    kind: "download",
+                    mediaType,
+                    path: absolutePath,
+                    requestedPath: request.path,
+                    sizeBytes: fileStat.size,
+                    state: "verified",
+                    status: "saved",
+                }],
+            missingCount: 0,
+            pendingCount: 0,
+            unverifiedCount: 0,
+            verified: true,
+            verifiedCount: 1,
+        };
+        const savedFile = { command: "download", kind: "download", metadata: { download: probe.download, href: redactSensitiveText(href.href), method: "direct-anchor-fetch" }, path: absolutePath };
+        return {
+            artifactManifest,
+            result: {
+                content: [{
+                        type: "text",
+                        text: [
+                            `Download completed: ${absolutePath}`,
+                            `Requested path: ${request.path}`,
+                            `Source: ${redactSensitiveText(href.href)}`,
+                            `Size: ${fileStat.size} bytes`,
+                            "Method: direct anchor fetch before upstream download fallback.",
+                        ].join("\n"),
+                    }],
+                details: {
+                    args: options.redactedArgs,
+                    artifactManifest,
+                    artifactRetentionSummary,
+                    artifacts: [artifact],
+                    artifactVerification,
+                    command: "download",
+                    compatibilityWorkaround: options.compatibilityWorkaround,
+                    downloadRecovery: { href: redactSensitiveText(href.href), method: "direct-anchor-fetch", selector: request.selector },
+                    effectiveArgs: options.effectiveArgs,
+                    savedFile,
+                    savedFilePath: absolutePath,
+                    sessionMode: options.sessionMode,
+                    ...buildAgentBrowserResultCategoryDetails({ artifacts: [artifact], args: options.effectiveArgs, command: "download", savedFile, succeeded: true }),
+                    ...buildSessionDetailFields(options.sessionName, options.usedImplicitSession),
+                    summary: `Download completed: ${absolutePath}`,
+                },
+                isError: false,
+            },
+        };
+    }
+    catch {
+        return undefined;
+    }
+}

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

@@ -0,0 +1,108 @@
+import { isRecord } from "../../../parsing.js";
+import { buildAgentBrowserResultCategoryDetails } from "../../../results.js";
+import { redactSensitiveText } from "../../../runtime.js";
+import { buildSessionDetailFields, runSessionCommandData } from "../session-state.js";
+function parseNetworkRequestsPageFilterRequest(commandTokens) {
+    if (commandTokens[0] !== "network" || commandTokens[1] !== "requests")
+        return undefined;
+    const cleanArgs = [];
+    let mode;
+    for (const token of commandTokens) {
+        if (token === "--current-page" || token === "--current-origin") {
+            mode = "origin";
+            continue;
+        }
+        if (token === "--current-url") {
+            mode = "url";
+            continue;
+        }
+        cleanArgs.push(token);
+    }
+    if (!mode)
+        return undefined;
+    return { cleanArgs, mode };
+}
+function extractCurrentUrl(data) {
+    if (typeof data === "string")
+        return data;
+    if (!isRecord(data))
+        return undefined;
+    const candidates = [data.url, data.currentUrl, data.href, data.result];
+    for (const candidate of candidates)
+        if (typeof candidate === "string" && candidate.length > 0)
+            return candidate;
+    return undefined;
+}
+function getRequestUrl(row) {
+    if (!isRecord(row))
+        return undefined;
+    const candidate = row.url ?? row.requestUrl ?? row.href;
+    return typeof candidate === "string" ? candidate : undefined;
+}
+function requestMatchesCurrentPage(row, currentUrl, mode) {
+    const requestUrl = getRequestUrl(row);
+    if (!requestUrl)
+        return false;
+    try {
+        const current = new URL(currentUrl);
+        const request = new URL(requestUrl, current);
+        if (mode === "origin")
+            return current.origin === request.origin;
+        const currentComparable = `${current.origin}${current.pathname}`;
+        const requestComparable = `${request.origin}${request.pathname}`;
+        return requestComparable === currentComparable;
+    }
+    catch {
+        return mode === "url" ? requestUrl === currentUrl : requestUrl.startsWith(currentUrl);
+    }
+}
+function filterNetworkRequestsData(data, currentUrl, request) {
+    if (!isRecord(data))
+        return undefined;
+    const requestRows = Array.isArray(data.requests) ? data.requests : Array.isArray(data.items) ? data.items : Array.isArray(data.entries) ? data.entries : undefined;
+    if (!requestRows)
+        return undefined;
+    const rows = requestRows.filter((row) => requestMatchesCurrentPage(row, currentUrl, request.mode));
+    const key = Array.isArray(data.requests) ? "requests" : Array.isArray(data.items) ? "items" : "entries";
+    return { data: { ...data, [key]: rows }, matchedRows: rows.length, rows, totalRows: requestRows.length };
+}
+function formatNetworkRequestRow(row) {
+    if (!isRecord(row))
+        return redactSensitiveText(String(row));
+    const status = row.status ?? row.statusCode ?? row.responseStatus ?? "?";
+    const method = typeof row.method === "string" ? row.method : typeof row.requestMethod === "string" ? row.requestMethod : "?";
+    const id = typeof row.id === "string" ? ` id=${row.id}` : typeof row.requestId === "string" ? ` id=${row.requestId}` : "";
+    const url = getRequestUrl(row) ?? "(no url)";
+    return redactSensitiveText(`- ${status} ${method}${id} ${url}`);
+}
+export async function tryNetworkRequestsPageFilter(options) {
+    const request = parseNetworkRequestsPageFilterRequest(options.commandTokens);
+    if (!request || !options.sessionName)
+        return undefined;
+    const currentUrl = extractCurrentUrl(await runSessionCommandData({ args: ["get", "url"], cwd: options.cwd, sessionName: options.sessionName, signal: options.signal }));
+    if (!currentUrl)
+        return undefined;
+    const networkData = await runSessionCommandData({ args: request.cleanArgs, cwd: options.cwd, sessionName: options.sessionName, signal: options.signal });
+    const filtered = filterNetworkRequestsData(networkData, currentUrl, request);
+    if (!filtered)
+        return undefined;
+    const summary = `Network requests filtered to current ${request.mode === "origin" ? "origin" : "URL"}: ${filtered.matchedRows}/${filtered.totalRows} rows matched.`;
+    const preview = filtered.rows.slice(0, 12).map(formatNetworkRequestRow);
+    const omitted = filtered.rows.length > preview.length ? [`- …${filtered.rows.length - preview.length} more matching rows omitted`] : [];
+    return {
+        content: [{ type: "text", text: [redactSensitiveText(summary), `Current page: ${redactSensitiveText(currentUrl)}`, ...preview, ...omitted].join("\n") }],
+        details: {
+            args: options.redactedArgs,
+            command: "network",
+            compatibilityWorkaround: options.compatibilityWorkaround,
+            data: filtered.data,
+            effectiveArgs: options.effectiveArgs,
+            networkRequestsPageFilter: { cleanArgs: request.cleanArgs, currentUrl: redactSensitiveText(currentUrl), matchedRows: filtered.matchedRows, mode: request.mode, totalRows: filtered.totalRows },
+            sessionMode: options.sessionMode,
+            ...buildAgentBrowserResultCategoryDetails({ args: options.effectiveArgs, command: "network", succeeded: true }),
+            ...buildSessionDetailFields(options.sessionName, options.usedImplicitSession),
+            summary,
+        },
+        isError: false,
+    };
+}

package/dist/extensions/agent-browser/lib/orchestration/browser-run/prepare/scroll-shims.js

@@ -0,0 +1,112 @@
+import { isRecord } from "../../../parsing.js";
+import { buildAgentBrowserResultCategoryDetails } from "../../../results.js";
+import { buildScrollNoopNextActions } from "../diagnostics.js";
+import { buildSessionDetailFields, runSessionCommandData } from "../session-state.js";
+const SCROLL_CONTAINER_DIRECTIONS = new Set(["down", "left", "right", "up"]);
+function getContainerScrollRequest(commandTokens) {
+    if (commandTokens[0] !== "scroll" || commandTokens.length < 3)
+        return undefined;
+    const selector = commandTokens[1];
+    const direction = commandTokens[2]?.toLowerCase();
+    if (!selector || selector.startsWith("-") || selector.startsWith("@") || SCROLL_CONTAINER_DIRECTIONS.has(selector.toLowerCase()))
+        return undefined;
+    if (!SCROLL_CONTAINER_DIRECTIONS.has(direction))
+        return undefined;
+    return { amount: commandTokens[3], direction, selector };
+}
+function buildContainerScrollScript(request) {
+    return `(() => {
+  const selector = ${JSON.stringify(request.selector)};
+  const direction = ${JSON.stringify(request.direction)};
+  const amountToken = ${JSON.stringify(request.amount ?? "")};
+  let element;
+  try { element = document.querySelector(selector); } catch (error) { return { status: "invalid-selector", selector, error: String(error && error.message || error) }; }
+  if (!(element instanceof HTMLElement)) return { status: "not-found", selector };
+  const axis = direction === "left" || direction === "right" ? "x" : "y";
+  const before = { scrollLeft: element.scrollLeft, scrollTop: element.scrollTop, scrollHeight: element.scrollHeight, scrollWidth: element.scrollWidth, clientHeight: element.clientHeight, clientWidth: element.clientWidth };
+  const parseAmount = () => {
+    const token = String(amountToken || "").trim().toLowerCase();
+    const extent = axis === "x" ? element.clientWidth : element.clientHeight;
+    if (!token) return Math.max(1, Math.floor(extent * 0.8));
+    if (token.endsWith("%")) {
+      const value = Number(token.slice(0, -1));
+      return Number.isFinite(value) ? Math.max(1, Math.floor(extent * value / 100)) : Math.max(1, Math.floor(extent * 0.8));
+    }
+    const pixels = Number(token.replace(/px$/, ""));
+    return Number.isFinite(pixels) && pixels > 0 ? Math.floor(pixels) : Math.max(1, Math.floor(extent * 0.8));
+  };
+  const delta = parseAmount() * (direction === "up" || direction === "left" ? -1 : 1);
+  if (axis === "x") element.scrollLeft += delta;
+  else element.scrollTop += delta;
+  const after = { scrollLeft: element.scrollLeft, scrollTop: element.scrollTop, scrollHeight: element.scrollHeight, scrollWidth: element.scrollWidth, clientHeight: element.clientHeight, clientWidth: element.clientWidth };
+  const moved = before.scrollLeft !== after.scrollLeft || before.scrollTop !== after.scrollTop;
+  return { status: moved ? "scrolled" : "no-movement", selector, direction, amount: amountToken || undefined, before, after };
+})()`;
+}
+function buildScrollResult(options) {
+    return {
+        content: [{ type: "text", text: options.message }],
+        details: {
+            args: options.redactedArgs,
+            command: options.command,
+            compatibilityWorkaround: options.compatibilityWorkaround,
+            data: options.result,
+            effectiveArgs: options.effectiveArgs,
+            nextActions: options.succeeded ? undefined : buildScrollNoopNextActions(options.sessionName),
+            [options.scrollField]: options.scrollValue,
+            sessionMode: options.sessionMode,
+            ...buildAgentBrowserResultCategoryDetails({ args: options.effectiveArgs, command: options.command, errorText: options.succeeded ? undefined : options.message, succeeded: options.succeeded, validationError: options.succeeded ? undefined : options.message }),
+            ...buildSessionDetailFields(options.sessionName, options.usedImplicitSession),
+            summary: options.message,
+            validationError: options.succeeded ? undefined : options.message,
+        },
+        isError: !options.succeeded,
+    };
+}
+export async function tryContainerScroll(options) {
+    const request = getContainerScrollRequest(options.commandTokens);
+    if (!request || !options.sessionName)
+        return undefined;
+    const data = await runSessionCommandData({ args: ["eval", "--stdin"], cwd: options.cwd, sessionName: options.sessionName, signal: options.signal, stdin: buildContainerScrollScript(request) });
+    const result = isRecord(data) && isRecord(data.result) ? data.result : data;
+    if (!isRecord(result) || typeof result.status !== "string")
+        return undefined;
+    const succeeded = result.status === "scrolled";
+    const message = succeeded
+        ? `Scrolled container ${request.selector} ${request.direction}${request.amount ? ` by ${request.amount}` : ""}.`
+        : `Scroll container ${request.selector} did not move (${result.status}).`;
+    return buildScrollResult({ ...options, command: "scroll", message, result, scrollField: "scrollContainer", scrollValue: { request, result }, succeeded });
+}
+function getPageScrollToRequest(commandTokens) {
+    if (commandTokens[0] !== "scroll" || commandTokens[1]?.toLowerCase() !== "to")
+        return undefined;
+    const target = commandTokens[2]?.toLowerCase();
+    return target === "end" || target === "top" ? { target } : undefined;
+}
+function buildPageScrollToScript(request) {
+    return `(() => {
+  const target = ${JSON.stringify(request.target)};
+  const scroller = document.scrollingElement || document.documentElement || document.body;
+  if (!scroller) return { status: "no-scroller", target };
+  const before = { scrollLeft: scroller.scrollLeft, scrollTop: scroller.scrollTop, scrollHeight: scroller.scrollHeight, scrollWidth: scroller.scrollWidth, clientHeight: scroller.clientHeight, clientWidth: scroller.clientWidth };
+  const nextTop = target === "top" ? 0 : Math.max(0, scroller.scrollHeight - scroller.clientHeight);
+  const nextLeft = scroller.scrollLeft;
+  scroller.scrollTop = nextTop;
+  window.scrollTo(nextLeft, nextTop);
+  const after = { scrollLeft: scroller.scrollLeft, scrollTop: scroller.scrollTop, scrollHeight: scroller.scrollHeight, scrollWidth: scroller.scrollWidth, clientHeight: scroller.clientHeight, clientWidth: scroller.clientWidth };
+  const moved = before.scrollLeft !== after.scrollLeft || before.scrollTop !== after.scrollTop;
+  return { status: moved ? "scrolled" : "no-movement", target, before, after };
+})()`;
+}
+export async function tryPageScrollTo(options) {
+    const request = getPageScrollToRequest(options.commandTokens);
+    if (!request || !options.sessionName)
+        return undefined;
+    const data = await runSessionCommandData({ args: ["eval", "--stdin"], cwd: options.cwd, sessionName: options.sessionName, signal: options.signal, stdin: buildPageScrollToScript(request) });
+    const result = isRecord(data) && isRecord(data.result) ? data.result : data;
+    if (!isRecord(result) || typeof result.status !== "string")
+        return undefined;
+    const succeeded = result.status === "scrolled";
+    const message = succeeded ? `Scrolled page to ${request.target}.` : `Scroll to ${request.target} completed with no observed movement (${result.status}).`;
+    return buildScrollResult({ ...options, command: "scroll", message, result, scrollField: "scrollPage", scrollValue: { request, result }, succeeded });
+}

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

@@ -0,0 +1,158 @@
+import { isRecord } from "../../../parsing.js";
+import { buildAgentBrowserResultCategoryDetails } from "../../../results.js";
+import { buildSnapshotPresentation } from "../../../results/snapshot.js";
+import { extractRefSnapshotFromData } from "../../../session-page-state.js";
+import { collectScrollPositionSnapshot } from "../diagnostics.js";
+import { buildSessionDetailFields, runSessionCommandData } from "../session-state.js";
+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];
+        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 };
+}
+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;
+    }
+    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 };
+}
+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 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,
+    };
+}
+export async function trySnapshotFilter(options) {
+    const request = parseSnapshotFilterRequest(options.commandTokens);
+    if (!request || !options.sessionName)
+        return undefined;
+    const snapshotData = await runSessionCommandData({ args: request.cleanArgs, cwd: options.cwd, 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)
+        return undefined;
+    const viewport = request.viewport ? await collectScrollPositionSnapshot({ cwd: options.cwd, 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.sessionName, snapshot: fullSnapshot, update: options.sessionPageStateUpdate });
+    const presentation = 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 prefix = [summary, diffText, viewportText].filter((line) => line !== undefined).join("\n");
+    if (presentation.content[0]?.type === "text")
+        presentation.content[0] = { ...presentation.content[0], text: `${prefix}\n\n${presentation.content[0].text}` };
+    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, 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),
+                summary,
+            },
+            isError: false,
+        },
+    };
+}

package/dist/extensions/agent-browser/lib/orchestration/browser-run/prepare/wait-timeouts.js

@@ -0,0 +1,54 @@
+import { getAgentBrowserProcessTimeoutMs } from "../../../process.js";
+import { parseValidBatchStepEntries } from "../../batch-stdin.js";
+const WAIT_PROCESS_TIMEOUT_GRACE_MS = 5_000;
+function parseMillisecondsToken(token) {
+    if (token === undefined || !/^\d+$/.test(token)) {
+        return undefined;
+    }
+    const parsed = Number(token);
+    return Number.isSafeInteger(parsed) ? parsed : undefined;
+}
+function findWaitTimeoutMs(commandTokens) {
+    if (commandTokens[0] !== "wait") {
+        return undefined;
+    }
+    for (let index = 1; index < commandTokens.length; index += 1) {
+        const token = commandTokens[index];
+        if (token === "--timeout") {
+            return parseMillisecondsToken(commandTokens[index + 1]);
+        }
+        if (token.startsWith("--timeout=")) {
+            return parseMillisecondsToken(token.slice("--timeout=".length));
+        }
+    }
+    const firstWaitArgument = commandTokens[1];
+    if (firstWaitArgument && !firstWaitArgument.startsWith("-")) {
+        return parseMillisecondsToken(firstWaitArgument);
+    }
+    return undefined;
+}
+function findWaitTimeoutBudgetMs(commandTokens, stdin) {
+    const directWaitTimeout = findWaitTimeoutMs(commandTokens);
+    if (directWaitTimeout !== undefined) {
+        return directWaitTimeout;
+    }
+    if (commandTokens[0] !== "batch" || stdin === undefined) {
+        return undefined;
+    }
+    let batchWaitTimeoutTotal = 0;
+    for (const { step } of parseValidBatchStepEntries(stdin)) {
+        const waitTimeout = findWaitTimeoutMs(step);
+        if (waitTimeout !== undefined) {
+            batchWaitTimeoutTotal += waitTimeout;
+        }
+    }
+    return batchWaitTimeoutTotal === 0 ? undefined : batchWaitTimeoutTotal;
+}
+export function getWaitAwareProcessTimeoutMs(commandTokens, stdin) {
+    const waitTimeoutBudgetMs = findWaitTimeoutBudgetMs(commandTokens, stdin);
+    if (waitTimeoutBudgetMs === undefined)
+        return undefined;
+    const neededTimeoutMs = waitTimeoutBudgetMs + WAIT_PROCESS_TIMEOUT_GRACE_MS;
+    const defaultProcessTimeoutMs = getAgentBrowserProcessTimeoutMs();
+    return neededTimeoutMs > defaultProcessTimeoutMs ? neededTimeoutMs : undefined;
+}