pi-agent-browser-native 0.2.47 → 0.2.48

package/extensions/agent-browser/lib/orchestration/browser-run/prepare.ts

@@ -1,12 +1,16 @@
-import { copyFile, mkdir, stat, writeFile } from "node:fs/promises";
-import { dirname, extname, isAbsolute, resolve } from "node:path";
+import { copyFile, mkdir } from "node:fs/promises";
+import { dirname, resolve } from "node:path";
 
 import { launchElectronApp, type ElectronLaunchSuccess } from "../../electron/launch.js";
 import { pathExists } from "../../fs-utils.js";
 import { getCompiledSemanticActionSessionPrefix, type CompiledAgentBrowserSemanticAction } from "../../input-modes.js";
-import { SAFE_AGENT_BROWSER_OPERATION_TIMEOUT_MS } from "../../process.js";
+import { tryDirectAnchorDownload } from "./prepare/direct-anchor-download.js";
+import { tryNetworkRequestsPageFilter } from "./prepare/network-page-filter.js";
+import { tryContainerScroll, tryPageScrollTo } from "./prepare/scroll-shims.js";
+import { trySnapshotFilter } from "./prepare/snapshot-filter.js";
+import { getWaitAwareProcessTimeoutMs } from "./prepare/wait-timeouts.js";
+import { getPersistentSessionArtifactStore } from "./session-artifacts.js";
 import { buildAgentBrowserResultCategoryDetails } from "../../results.js";
-import { buildSnapshotPresentation } from "../../results/snapshot.js";
 import { buildSessionAwareStaleRefNextActions, buildSessionTabRecoveryNextActions } from "../../results/recovery-next-actions.js";
 import { resolveVisibleRefActionFromSnapshot } from "../../results/selector-recovery.js";
 import { extractRefSnapshotFromData, type SessionRefSnapshot, type SessionTabTarget } from "../../session-page-state.js";
@@ -30,17 +34,18 @@ import {
 	runSessionCommandData,
 	shouldPinSessionTabForCommand,
 } from "./session-state.js";
-import { isRecord } from "../../parsing.js";
 import { parseBatchStdinJsonArray, parseValidBatchStepEntries } from "../batch-stdin.js";
 import { buildElectronHostFailureResult, getElectronLaunchFailureCategory, redactRecoveryHint } from "./final-result.js";
 import { prepareClickDispatchProbe } from "./click-dispatch.js";
-import { buildScrollNoopNextActions, collectScrollPositionSnapshot, validateQaAttachedPrecondition } from "./diagnostics.js";
+import { collectScrollPositionSnapshot, validateQaAttachedPrecondition } from "./diagnostics.js";
+import { getScreenshotPathTokenIndex } from "./artifact-paths.js";
 import { findRequestedArtifactCloseViolation } from "./prompt-guards.js";
 
 import type {
 	AgentBrowserToolResult,
 	BrowserRunInputFields,
 	BrowserRunOptions,
+	BrowserRunStatePatch,
 	PreparedAgentBrowserArgs,
 	PreparedBrowserRun,
 	PrepareBrowserRunResult,
@@ -50,10 +55,6 @@ import type {
 	StaleRefPreflight,
 } from "./types.js";
 
-const DIRECT_ANCHOR_DOWNLOAD_MAX_BYTES = 2 * 1024 * 1024;
-const SCREENSHOT_VALUE_FLAGS = new Set(["--screenshot-dir", "--screenshot-format", "--screenshot-quality"]);
-const SCREENSHOT_IMAGE_EXTENSIONS = new Set([".jpeg", ".jpg", ".png", ".webp"]);
-
 export function normalizeRunInput(input: BrowserRunOptions["input"]): BrowserRunInputFields {
 	const base = { redactedArgs: input.redactedArgs, toolArgs: input.toolArgs, toolStdin: input.toolStdin };
 	switch (input.kind) {
@@ -79,46 +80,6 @@ export function buildInvocationPreview(effectiveArgs: string[]): string {
 	return preview.length > 120 ? `${preview.slice(0, 117)}...` : preview;
 }
 
-function isImagePathToken(token: string): boolean {
-	const extension = extname(token).toLowerCase();
-	return SCREENSHOT_IMAGE_EXTENSIONS.has(extension);
-}
-
-export function getScreenshotPathTokenIndex(commandTokens: string[]): number | undefined {
-	if (commandTokens[0] !== "screenshot") {
-		return undefined;
-	}
-
-	const positionalIndices: number[] = [];
-	for (let index = 1; index < commandTokens.length; index += 1) {
-		const token = commandTokens[index];
-		if (token === "--") {
-			for (let positionalIndex = index + 1; positionalIndex < commandTokens.length; positionalIndex += 1) {
-				positionalIndices.push(positionalIndex);
-			}
-			break;
-		}
-		if (token.startsWith("-")) {
-			const normalizedToken = token.split("=", 1)[0] ?? token;
-			if (SCREENSHOT_VALUE_FLAGS.has(normalizedToken) && !token.includes("=")) {
-				index += 1;
-			}
-			continue;
-		}
-		positionalIndices.push(index);
-	}
-
-	if (positionalIndices.length === 0) {
-		return undefined;
-	}
-	const candidateIndex = positionalIndices[positionalIndices.length - 1];
-	const candidate = commandTokens[candidateIndex];
-	if (positionalIndices.length >= 2 || isImagePathToken(candidate) || isAbsolute(candidate) || candidate.startsWith("./") || candidate.startsWith("../")) {
-		return candidateIndex;
-	}
-	return undefined;
-}
-
 function getArtifactParentPathTokenIndex(commandTokens: string[]): number | undefined {
 	if (commandTokens[0] === "download" && commandTokens.length >= 3) return 2;
 	if (commandTokens[0] === "pdf" && commandTokens.length >= 2) return 1;
@@ -139,123 +100,6 @@ async function ensureArtifactParentDirectory(commandTokens: string[], cwd: strin
 	await mkdir(dirname(resolve(cwd, requestedPath)), { recursive: true });
 }
 
-function getDirectDownloadRequest(commandTokens: string[]): { path: string; selector: string } | undefined {
-	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: string): string {
-	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: URL): boolean {
-	return (url.protocol === "http:" || url.protocol === "https:") && (url.hostname === "localhost" || url.hostname === "127.0.0.1" || url.hostname === "::1" || url.hostname === "[::1]");
-}
-
-async function tryDirectAnchorDownload(options: {
-	commandTokens: string[];
-	compatibilityWorkaround?: CompatibilityWorkaround;
-	cwd: string;
-	effectiveArgs: string[];
-	redactedArgs: string[];
-	sessionMode: "auto" | "fresh";
-	sessionName?: string;
-	signal?: AbortSignal;
-	usedImplicitSession: boolean;
-}): Promise<AgentBrowserToolResult | undefined> {
-	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 artifact = {
-			absolutePath,
-			artifactType: "download" as const,
-			command: "download",
-			cwd: options.cwd,
-			exists: true,
-			kind: "download" as const,
-			mediaType,
-			path: absolutePath,
-			requestedPath: request.path,
-			session: options.sessionName,
-			sizeBytes: fileStat.size,
-			status: "saved" as const,
-		};
-		const artifactVerification = {
-			artifacts: [{
-				absolutePath,
-				exists: true,
-				kind: "download" as const,
-				mediaType,
-				path: absolutePath,
-				requestedPath: request.path,
-				sizeBytes: fileStat.size,
-				state: "verified" as const,
-				status: "saved" as const,
-			}],
-			missingCount: 0,
-			pendingCount: 0,
-			unverifiedCount: 0,
-			verified: true,
-			verifiedCount: 1,
-		};
-		const savedFile = { command: "download" as const, kind: "download" as const, metadata: { download: probe.download, href: redactSensitiveText(href.href), method: "direct-anchor-fetch" }, path: absolutePath };
-		return {
-			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,
-				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;
-	}
-}
-
 async function normalizeScreenshotPathInTokens(commandTokens: string[], cwd: string): Promise<{
 	request?: ScreenshotPathRequest;
 	tokens: string[];
@@ -377,60 +221,6 @@ async function repairScreenshotData(options: {
 
 export { repairScreenshotData };
 
-function parseMillisecondsToken(token: string | undefined): number | undefined {
-	if (token === undefined || !/^\d+$/.test(token)) {
-		return undefined;
-	}
-	const parsed = Number(token);
-	return Number.isSafeInteger(parsed) ? parsed : undefined;
-}
-
-function findWaitTimeoutMs(commandTokens: string[]): { timeoutMs: number; source: string } | undefined {
-	if (commandTokens[0] !== "wait") {
-		return undefined;
-	}
-	for (let index = 1; index < commandTokens.length; index += 1) {
-		const token = commandTokens[index];
-		if (token === "--timeout") {
-			const timeoutMs = parseMillisecondsToken(commandTokens[index + 1]);
-			return timeoutMs === undefined ? undefined : { source: "wait --timeout", timeoutMs };
-		}
-		if (token.startsWith("--timeout=")) {
-			const timeoutMs = parseMillisecondsToken(token.slice("--timeout=".length));
-			return timeoutMs === undefined ? undefined : { source: "wait --timeout", timeoutMs };
-		}
-		if (!token.startsWith("-")) {
-			const timeoutMs = parseMillisecondsToken(token);
-			if (timeoutMs !== undefined) {
-				return { source: "wait", timeoutMs };
-			}
-		}
-	}
-	return undefined;
-}
-
-function buildIpcUnsafeWaitError(source: string, timeoutMs: number, batchStep?: number): string {
-	const location = batchStep === undefined ? source : `batch step ${batchStep + 1} (${source})`;
-	return `${location} requests ${timeoutMs}ms, but upstream agent-browser CLI calls must stay under its 30s IPC read timeout. Use ${SAFE_AGENT_BROWSER_OPERATION_TIMEOUT_MS}ms or less per wait, split long waits into multiple tool calls, or use a page-specific shorter condition.`;
-}
-
-export function validateWaitIpcTimeoutContract(commandTokens: string[], stdin: string | undefined): string | undefined {
-	const directWaitTimeout = findWaitTimeoutMs(commandTokens);
-	if (directWaitTimeout && directWaitTimeout.timeoutMs > SAFE_AGENT_BROWSER_OPERATION_TIMEOUT_MS) {
-		return buildIpcUnsafeWaitError(directWaitTimeout.source, directWaitTimeout.timeoutMs);
-	}
-	if (commandTokens[0] !== "batch" || stdin === undefined) {
-		return undefined;
-	}
-	for (const { index, step } of parseValidBatchStepEntries(stdin)) {
-		const waitTimeout = findWaitTimeoutMs(step);
-		if (waitTimeout && waitTimeout.timeoutMs > SAFE_AGENT_BROWSER_OPERATION_TIMEOUT_MS) {
-			return buildIpcUnsafeWaitError(waitTimeout.source, waitTimeout.timeoutMs, index);
-		}
-	}
-	return undefined;
-}
-
 const DIALOG_COMMAND_PROCESS_TIMEOUT_MS = 5_000;
 const DIALOG_COMMAND_PROCESS_TIMEOUT_ENV = "PI_AGENT_BROWSER_DIALOG_PROCESS_TIMEOUT_MS";
 const LIKELY_DIALOG_TRIGGER_PROCESS_TIMEOUT_MS = 8_000;
@@ -518,416 +308,6 @@ async function collectSamePageRefFreshnessPreflight(options: {
 	return { message: mismatch.message, refIds: mismatch.refIds, snapshot: snapshotWithTarget };
 }
 
-const SCROLL_CONTAINER_DIRECTIONS = new Set(["down", "left", "right", "up"]);
-
-function getContainerScrollRequest(commandTokens: string[]): { amount?: string; direction: string; selector: string } | undefined {
-	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: { amount?: string; direction: string; selector: string }): string {
-	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: {
-	command: "scroll";
-	compatibilityWorkaround?: CompatibilityWorkaround;
-	effectiveArgs: string[];
-	message: string;
-	redactedArgs: string[];
-	result: Record<string, unknown>;
-	scrollField: "scrollContainer" | "scrollPage";
-	scrollValue: unknown;
-	sessionMode: "auto" | "fresh";
-	sessionName?: string;
-	succeeded: boolean;
-	usedImplicitSession: boolean;
-}): AgentBrowserToolResult {
-	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,
-	};
-}
-
-async function tryContainerScroll(options: {
-	commandTokens: string[];
-	compatibilityWorkaround?: CompatibilityWorkaround;
-	cwd: string;
-	effectiveArgs: string[];
-	redactedArgs: string[];
-	sessionMode: "auto" | "fresh";
-	sessionName?: string;
-	signal?: AbortSignal;
-	usedImplicitSession: boolean;
-}): Promise<AgentBrowserToolResult | undefined> {
-	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: string[]): { target: "end" | "top" } | undefined {
-	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: { target: "end" | "top" }): string {
-	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 };
-})()`;
-}
-
-async function tryPageScrollTo(options: {
-	commandTokens: string[];
-	compatibilityWorkaround?: CompatibilityWorkaround;
-	cwd: string;
-	effectiveArgs: string[];
-	redactedArgs: string[];
-	sessionMode: "auto" | "fresh";
-	sessionName?: string;
-	signal?: AbortSignal;
-	usedImplicitSession: boolean;
-}): Promise<AgentBrowserToolResult | undefined> {
-	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 });
-}
-
-interface SnapshotFilterRequest {
-	cleanArgs: string[];
-	diff?: boolean;
-	role?: string;
-	search?: string;
-	viewport?: boolean;
-}
-
-function parseSnapshotFilterRequest(commandTokens: string[]): SnapshotFilterRequest | undefined {
-	if (commandTokens[0] !== "snapshot") return undefined;
-	const cleanArgs: string[] = [];
-	let role: string | undefined;
-	let search: string | undefined;
-	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 };
-}
-
-interface SnapshotDiffSummary {
-	addedRefs: string[];
-	changedRefs: string[];
-	removedRefs: string[];
-	summary: string;
-	unchangedRefs: number;
-}
-
-function buildSnapshotDiff(previous: SessionRefSnapshot | undefined, current: SessionRefSnapshot | undefined): SnapshotDiffSummary | undefined {
-	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: string[] = [];
-	const removedRefs: string[] = [];
-	const changedRefs: string[] = [];
-	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: unknown, request: SnapshotFilterRequest): { data: Record<string, unknown>; matchedRefs: number; totalRefs: number; totalLines: number; visibleLines: number } | undefined {
-	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<string>();
-	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 is string => 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,
-	};
-}
-
-async function trySnapshotFilter(options: {
-	commandTokens: string[];
-	compatibilityWorkaround?: CompatibilityWorkaround;
-	cwd: string;
-	effectiveArgs: string[];
-	redactedArgs: string[];
-	previousRefSnapshot?: SessionRefSnapshot;
-	sessionMode: "auto" | "fresh";
-	sessionName?: string;
-	sessionPageState: BrowserRunOptions["state"]["sessionPageState"];
-	sessionPageStateUpdate: ReturnType<BrowserRunOptions["state"]["sessionPageState"]["beginUpdate"]>;
-	signal?: AbortSignal;
-	usedImplicitSession: boolean;
-}): Promise<AgentBrowserToolResult | undefined> {
-	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);
-	const summary = request.role || request.search
-		? `Snapshot filter: ${filtered.matchedRefs}/${filtered.totalRefs} refs matched${request.role ? ` role=${request.role}` : ""}${request.search ? ` search ${JSON.stringify(request.search)}` : ""}.`
-		: 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 is string => 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 {
-		content: presentation.content,
-		details: {
-			args: options.redactedArgs,
-			command: "snapshot",
-			compatibilityWorkaround: options.compatibilityWorkaround,
-			data: presentation.data,
-			effectiveArgs: options.effectiveArgs,
-			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,
-	};
-}
-
-interface NetworkRequestsPageFilterRequest {
-	cleanArgs: string[];
-	mode: "origin" | "url";
-}
-
-function parseNetworkRequestsPageFilterRequest(commandTokens: string[]): NetworkRequestsPageFilterRequest | undefined {
-	if (commandTokens[0] !== "network" || commandTokens[1] !== "requests") return undefined;
-	const cleanArgs: string[] = [];
-	let mode: NetworkRequestsPageFilterRequest["mode"] | undefined;
-	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: unknown): string | undefined {
-	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: unknown): string | undefined {
-	if (!isRecord(row)) return undefined;
-	const candidate = row.url ?? row.requestUrl ?? row.href;
-	return typeof candidate === "string" ? candidate : undefined;
-}
-
-function requestMatchesCurrentPage(row: unknown, currentUrl: string, mode: NetworkRequestsPageFilterRequest["mode"]): boolean {
-	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: unknown, currentUrl: string, request: NetworkRequestsPageFilterRequest): { data: Record<string, unknown>; matchedRows: number; totalRows: number; rows: unknown[] } | undefined {
-	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: unknown): string {
-	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}`);
-}
-
-async function tryNetworkRequestsPageFilter(options: {
-	commandTokens: string[];
-	compatibilityWorkaround?: CompatibilityWorkaround;
-	cwd: string;
-	effectiveArgs: string[];
-	redactedArgs: string[];
-	sessionMode: "auto" | "fresh";
-	sessionName?: string;
-	signal?: AbortSignal;
-	usedImplicitSession: boolean;
-}): Promise<AgentBrowserToolResult | undefined> {
-	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,
-	};
-}
-
 function isPasswordStdinAuthSave(options: { command?: string; commandTokens: string[] }): boolean {
 	return options.command === "auth" && options.commandTokens[1] === "save" && options.commandTokens.includes("--password-stdin");
 }
@@ -1049,7 +429,7 @@ export async function prepareBrowserRun(options: BrowserRunOptions): Promise<Pre
 	const redactedEffectiveArgs = redactInvocationArgs(executionPlan.effectiveArgs);
 	const redactedRecoveryHint = redactRecoveryHint(executionPlan.recoveryHint);
 	const compatibilityWorkaround: CompatibilityWorkaround | undefined = executionPlan.compatibilityWorkaround;
-	const statePatch = executionPlan.managedSessionName === freshSessionName
+	const statePatch: BrowserRunStatePatch = executionPlan.managedSessionName === freshSessionName
 		? { freshSessionOrdinal: freshSessionOrdinal + 1 }
 		: {};
 	if (executionPlan.managedSessionName === freshSessionName) {
@@ -1126,24 +506,6 @@ export async function prepareBrowserRun(options: BrowserRunOptions): Promise<Pre
 			isError: true,
 		} };
 	}
-	const waitIpcTimeoutError = validateWaitIpcTimeoutContract(commandTokens, runtimeToolStdin);
-	if (waitIpcTimeoutError) {
-		return { kind: "early-result", statePatch, result: {
-			content: [{ type: "text", text: waitIpcTimeoutError }],
-			details: {
-				args: redactedArgs,
-				command: executionPlan.commandInfo.command,
-				compatibilityWorkaround,
-				effectiveArgs: redactedEffectiveArgs,
-				sessionMode,
-				...buildAgentBrowserResultCategoryDetails({ args: redactedEffectiveArgs, command: executionPlan.commandInfo.command, errorText: waitIpcTimeoutError, succeeded: false, timedOut: true, validationError: waitIpcTimeoutError }),
-				validationError: waitIpcTimeoutError,
-				...buildSessionDetailFields(executionPlan.sessionName, executionPlan.usedImplicitSession),
-			},
-			isError: true,
-		} };
-	}
-
 	const priorSessionPageState = sessionPageState.get(executionPlan.sessionName);
 	const priorSessionTabTarget = priorSessionPageState.tabTarget;
 	const sessionTabPinningReason = priorSessionPageState.pinningReason;
@@ -1252,11 +614,14 @@ export async function prepareBrowserRun(options: BrowserRunOptions): Promise<Pre
 		}
 	}
 
+	const persistentArtifactStore = getPersistentSessionArtifactStore(options.ctx);
 	const snapshotFilter = await trySnapshotFilter({
+		artifactManifest: state.artifactManifest,
 		commandTokens,
 		compatibilityWorkaround,
 		cwd,
 		effectiveArgs: redactedEffectiveArgs,
+		persistentArtifactStore,
 		previousRefSnapshot: priorRefSnapshotState,
 		redactedArgs,
 		sessionMode,
@@ -1266,7 +631,7 @@ export async function prepareBrowserRun(options: BrowserRunOptions): Promise<Pre
 		signal,
 		usedImplicitSession: executionPlan.usedImplicitSession,
 	});
-	if (snapshotFilter) return { kind: "early-result", statePatch, result: snapshotFilter };
+	if (snapshotFilter) return { kind: "early-result", statePatch: { ...statePatch, artifactManifest: snapshotFilter.artifactManifest ?? statePatch.artifactManifest }, result: snapshotFilter.result };
 
 	const networkRequestsPageFilter = await tryNetworkRequestsPageFilter({
 		commandTokens,
@@ -1307,6 +672,7 @@ export async function prepareBrowserRun(options: BrowserRunOptions): Promise<Pre
 	if (pageScrollTo) return { kind: "early-result", statePatch, result: pageScrollTo };
 
 	const directAnchorDownload = await tryDirectAnchorDownload({
+		artifactManifest: state.artifactManifest,
 		commandTokens,
 		compatibilityWorkaround,
 		cwd,
@@ -1317,7 +683,7 @@ export async function prepareBrowserRun(options: BrowserRunOptions): Promise<Pre
 		signal,
 		usedImplicitSession: executionPlan.usedImplicitSession,
 	});
-	if (directAnchorDownload) return { kind: "early-result", statePatch, result: directAnchorDownload };
+	if (directAnchorDownload) return { kind: "early-result", statePatch: { ...statePatch, artifactManifest: directAnchorDownload.artifactManifest ?? statePatch.artifactManifest }, result: directAnchorDownload.result };
 
 	let pinnedBatchUnwrapMode: PreparedBrowserRun["pinnedBatchUnwrapMode"];
 	let includePinnedNavigationSummary = false;
@@ -1418,7 +784,7 @@ export async function prepareBrowserRun(options: BrowserRunOptions): Promise<Pre
 	const clickDispatchProbe = pinnedBatchUnwrapMode === undefined && compiledElectron === undefined
 		? await prepareClickDispatchProbe({ commandTokens, cwd, refSnapshot: promptRefSnapshot, sessionName: executionPlan.sessionName, signal })
 		: undefined;
-	const processTimeoutMs = options.params.timeoutMs ?? getDialogAwareProcessTimeoutMs(commandTokens, promptRefSnapshot, processStdin);
+	const processTimeoutMs = options.params.timeoutMs ?? getDialogAwareProcessTimeoutMs(commandTokens, promptRefSnapshot, processStdin) ?? getWaitAwareProcessTimeoutMs(commandTokens, processStdin);
 	const redactedProcessArgs = redactInvocationArgs(processArgs);
 	const shouldProbeScrollNoop = executionPlan.commandInfo.command === "scroll" && executionPlan.startupScopedFlags.length === 0;
 	const scrollPositionBefore = shouldProbeScrollNoop