pi-agent-browser-native 0.2.47 → 0.2.48

package/extensions/agent-browser/lib/input-modes/params.ts

@@ -171,7 +171,7 @@ export function createAgentBrowserParamsSchema(
 					action: StringEnum(AGENT_BROWSER_JOB_STEP_ACTIONS, {
 						description: "Constrained one-call job step compiled to existing upstream batch commands.",
 					}),
-					url: Type.Optional(Type.String({ description: "URL for open steps, or URL pattern for assertUrl steps." })),
+					url: Type.Optional(Type.String({ description: "URL for open steps; exact URL or * / ** glob-style URL pattern for assertUrl steps." })),
 					loadState: Type.Optional(StringEnum(AGENT_BROWSER_QA_LOAD_STATES, { description: "Optional readiness wait to insert immediately after an open step; use domcontentloaded/load/networkidle when the next job step needs page hydration evidence before clicking or reading." })),
 					selector: Type.Optional(Type.String({ description: "Selector or @ref for click/fill/type/select-like steps; omit when using semantic locator fields on click/fill steps." })),
 					locator: Type.Optional(StringEnum(AGENT_BROWSER_SEMANTIC_LOCATORS, { description: "Semantic locator for click/fill steps when selector is omitted." })),
@@ -191,7 +191,7 @@ export function createAgentBrowserParamsSchema(
 	),
 	stdin: Type.Optional(Type.String({ description: "Optional raw stdin content; only supported for batch, eval --stdin, auth save --password-stdin, and is generated internally by job, qa, sourceLookup, or networkSourceLookup mode. Do not use with electron mode." })),
 	outputPath: Type.Optional(Type.String({ description: "Optional workspace-relative or absolute file path that receives the model-facing command data/result after the browser command completes. Useful for eval/get/snapshot captures that should become durable local artifacts.", minLength: 1 })),
-	timeoutMs: Type.Optional(Type.Integer({ description: "Optional per-call wrapper subprocess watchdog in milliseconds for browser CLI args/job/qa/source lookup calls. Use for long opens or large output captures; fixed wait steps still must stay below the upstream IPC wait budget. Electron actions use electron.timeoutMs instead.", minimum: 1 })),
+	timeoutMs: Type.Optional(Type.Integer({ description: "Optional per-call wrapper subprocess watchdog in milliseconds for browser CLI args/job/qa/source lookup calls. Use for long opens or large output captures; explicit long wait steps are forwarded, so set timeoutMs above the wait duration plus a small grace window when overriding the derived watchdog. Electron actions use electron.timeoutMs instead.", minimum: 1 })),
 	sessionMode: Type.Optional(
 		StringEnum(["auto", "fresh"] as const, {
 			description:

package/extensions/agent-browser/lib/orchestration/browser-run/artifact-paths.ts

@@ -0,0 +1,44 @@
+import { extname, isAbsolute } from "node:path";
+
+const SCREENSHOT_VALUE_FLAGS = new Set(["--screenshot-dir", "--screenshot-format", "--screenshot-quality"]);
+const SCREENSHOT_IMAGE_EXTENSIONS = new Set([".jpeg", ".jpg", ".png", ".webp"]);
+
+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;
+}

package/extensions/agent-browser/lib/orchestration/browser-run/click-dispatch.ts

@@ -15,6 +15,23 @@ function parseClickRefId(selector: string): string | undefined {
 	return /^e\d+$/.test(candidate) ? candidate : undefined;
 }
 
+function normalizeAccessibleName(name: string): string {
+	return name.replace(/\s+/g, " ").trim().toLowerCase();
+}
+
+function getAccessibleRefDuplicateIndex(refSnapshot: SessionRefSnapshot | undefined, refId: string, role: string, name: string): number | undefined {
+	if (!refSnapshot?.refs) return undefined;
+	const normalizedRole = role.toLowerCase();
+	const normalizedName = normalizeAccessibleName(name);
+	const matchingRefIds = refSnapshot.refIds.filter((candidateRefId) => {
+		const candidate = refSnapshot.refs?.[candidateRefId];
+		return candidate?.role.toLowerCase() === normalizedRole && normalizeAccessibleName(candidate.name) === normalizedName;
+	});
+	if (matchingRefIds.length <= 1) return undefined;
+	const duplicateIndex = matchingRefIds.indexOf(refId);
+	return duplicateIndex >= 0 ? duplicateIndex : undefined;
+}
+
 function getClickDispatchProbeTarget(commandTokens: string[], refSnapshot?: SessionRefSnapshot): ClickDispatchProbeTarget | undefined {
 	if (commandTokens[0] !== "click" || commandTokens.includes("--new-tab")) return undefined;
 	const selector = commandTokens[1];
@@ -23,7 +40,8 @@ function getClickDispatchProbeTarget(commandTokens: string[], refSnapshot?: Sess
 	if (refId) {
 		const ref = refSnapshot?.refs?.[refId];
 		if (!ref || !ACCESSIBLE_REF_CLICK_DISPATCH_ROLES.has(ref.role)) return undefined;
-		return { kind: "accessible", name: ref.name, refId, role: ref.role };
+		const duplicateIndex = getAccessibleRefDuplicateIndex(refSnapshot, refId, ref.role, ref.name);
+		return { ...(duplicateIndex === undefined ? {} : { duplicateIndex }), kind: "accessible", name: ref.name, refId, role: ref.role };
 	}
 	if (selector.startsWith("xpath=")) return { kind: "xpath", selector: selector.slice("xpath=".length) };
 	return { kind: "selector", selector };
@@ -43,6 +61,7 @@ function buildClickDispatchProbeInstallScript(probe: ClickDispatchProbe): string
   const normalize = (value) => String(value ?? "").replace(/\\s+/g, " ").trim();
   const expectedRole = ${JSON.stringify(target.role)};
   const expectedName = normalize(${JSON.stringify(target.name)});
+  const duplicateIndex = ${JSON.stringify(target.duplicateIndex)};
   const inferRole = (element) => {
     const explicit = element.getAttribute("role");
     if (explicit) return explicit;
@@ -65,6 +84,7 @@ function buildClickDispatchProbeInstallScript(probe: ClickDispatchProbe): string
     return element.getClientRects().length > 0;
   };
   const candidates = Array.from(document.querySelectorAll("button,a[href],input,select,textarea,summary,[role],[onclick],[tabindex]")).filter((element) => inferRole(element) === expectedRole && inferName(element) === expectedName && isVisible(element));
+  if (typeof duplicateIndex === "number") return candidates[duplicateIndex] || null;
   return candidates.length === 1 ? candidates[0] : null;
 })()`;
 	return `(() => {
@@ -94,22 +114,24 @@ const getSelector = (node) => {
   return parts.length > 0 ? parts.join(" > ") : undefined;
 };
 const rectInfo = (rect) => ({ bottom: rect.bottom, left: rect.left, right: rect.right, top: rect.top });
-const targetRect = element.getBoundingClientRect();
-const targetOutsideViewport = targetRect.bottom < 0 || targetRect.right < 0 || targetRect.top > window.innerHeight || targetRect.left > window.innerWidth;
+const targetRect = element ? element.getBoundingClientRect() : undefined;
+const targetOutsideViewport = targetRect ? targetRect.bottom < 0 || targetRect.right < 0 || targetRect.top > window.innerHeight || targetRect.left > window.innerWidth : undefined;
 let nearestScrollContainer;
-for (let current = element.parentElement; current && current !== document.body; current = current.parentElement) {
-  if (current.scrollHeight > current.clientHeight + 1 || current.scrollWidth > current.clientWidth + 1) {
-    const containerRect = current.getBoundingClientRect();
-    nearestScrollContainer = {
-      selector: getSelector(current),
-      tagName: current.tagName.toLowerCase(),
-      targetOutsideContainer: targetRect.bottom < containerRect.top || targetRect.top > containerRect.bottom || targetRect.right < containerRect.left || targetRect.left > containerRect.right,
-      targetOutsideViewport,
-      rect: rectInfo(containerRect),
-      scrollLeft: current.scrollLeft,
-      scrollTop: current.scrollTop,
-    };
-    break;
+if (element && targetRect) {
+  for (let current = element.parentElement; current && current !== document.body; current = current.parentElement) {
+    if (current.scrollHeight > current.clientHeight + 1 || current.scrollWidth > current.clientWidth + 1) {
+      const containerRect = current.getBoundingClientRect();
+      nearestScrollContainer = {
+        selector: getSelector(current),
+        tagName: current.tagName.toLowerCase(),
+        targetOutsideContainer: targetRect.bottom < containerRect.top || targetRect.top > containerRect.bottom || targetRect.right < containerRect.left || targetRect.left > containerRect.right,
+        targetOutsideViewport,
+        rect: rectInfo(containerRect),
+        scrollLeft: current.scrollLeft,
+        scrollTop: current.scrollTop,
+      };
+      break;
+    }
   }
 }
 const state = { events: [], target: { tagName: element.tagName.toLowerCase(), nearestScrollContainer, rect: rectInfo(targetRect), targetOutsideViewport } };
@@ -168,7 +190,7 @@ export function formatClickDispatchDiagnosticText(diagnostic: ClickDispatchDiagn
 }
 
 export function buildClickDispatchNextActions(options: { commandTokens: string[]; diagnostic?: ClickDispatchDiagnostic; sessionName?: string }): AgentBrowserNextAction[] {
-	const retryArgs = options.commandTokens[0] === "click" ? options.commandTokens : ["click", ...options.commandTokens];
+	const retryArgs = options.commandTokens[0] === "click" || options.commandTokens[0] === "find" ? options.commandTokens : ["click", ...options.commandTokens];
 	const actions: AgentBrowserNextAction[] = [
 		{
 			id: "inspect-click-dispatch-miss",
@@ -232,9 +254,10 @@ export async function collectClickDispatchDiagnostic(options: { cwd: string; pro
 	if (status !== "no-native-event-observed") return undefined;
 	const nativeEventCount = typeof result.nativeEventCount === "number" ? result.nativeEventCount : 0;
 	const scrollContainer = getClickDispatchScrollContainerDiagnostic(result);
+	const targetLabel = "no trusted DOM event reached the selected element";
 	const summary = scrollContainer
-		? `Upstream click reported success but no trusted DOM event reached the selected element. ${scrollContainer.summary}`
-		: "Upstream click reported success but no trusted DOM event reached the selected element. Gather evidence with snapshot or page-change checks, then retry upstream click or report the workflow issue; the wrapper does not replay clicks in-page.";
+		? `Upstream click reported success but ${targetLabel}. ${scrollContainer.summary}`
+		: `Upstream click reported success but ${targetLabel}. Gather evidence with snapshot or page-change checks, then retry upstream click or report the workflow issue; the wrapper does not replay clicks in-page.`;
 	return {
 		nativeEventCount,
 		reason: "native-click-produced-no-target-dom-event",

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

@@ -23,7 +23,7 @@ import {
 	runSessionCommandData,
 } from "./session-state.js";
 import { parseValidBatchStepEntries } from "../batch-stdin.js";
-import { getScreenshotPathTokenIndex } from "./prepare.js";
+import { getScreenshotPathTokenIndex } from "./artifact-paths.js";
 import type {
 	ArtifactCleanupGuidance,
 	ComboboxFocusDiagnostic,
@@ -511,9 +511,11 @@ export async function getArtifactCleanupGuidance(options: { command?: string; cw
 
 export function formatArtifactCleanupGuidanceText(guidance: ArtifactCleanupGuidance | undefined): string | undefined {
 	if (!guidance) return undefined;
-	const lines = ["Artifact lifecycle:", `- ${guidance.summary}`, `- ${guidance.note}`];
-	if (guidance.explicitArtifactPaths.length > 0) lines.push(`- Explicit artifact paths to review: ${guidance.explicitArtifactPaths.join(", ")}`);
-	return lines.join("\n");
+	const explicitCount = guidance.explicitArtifactPaths.length;
+	const explicitSummary = explicitCount === 0
+		? "No existing explicit artifact paths were found in the recent manifest."
+		: `${explicitCount} explicit artifact${explicitCount === 1 ? "" : "s"} remain${explicitCount === 1 ? "s" : ""}; expand or inspect details.artifactCleanup.explicitArtifactPaths for paths.`;
+	return `Artifact lifecycle: ${explicitSummary} Browser close does not delete explicit screenshots, downloads, PDFs, traces, HAR files, or recordings; use host file tools for cleanup.`;
 }
 
 async function collectManagedSessionCommandData(options: { args: string[]; cwd: string; sessionName: string; signal?: AbortSignal; timeoutMs?: number }): Promise<{ data?: unknown; error?: string }> {

package/extensions/agent-browser/lib/orchestration/browser-run/final-result.ts

@@ -303,18 +303,27 @@ export async function prepareFinalResultRecoveryState(options: {
 
 function buildTimeoutPartialProgressNextActions(options: FinalResultInput): AgentBrowserNextAction[] {
 	const retryArgs = options.timeoutPartialProgress?.retryStep?.retry?.args;
-	if (!retryArgs) return [];
 	const stepIndex = options.timeoutPartialProgress?.retryStep?.index;
 	const freshSessionAbandoned = options.sessionMode === "fresh" && options.timeoutPartialProgress?.liveUrlRecovered !== true;
+	if (retryArgs) {
+		return [{
+			id: "retry-timeout-step",
+			params: freshSessionAbandoned
+				? { args: retryArgs, sessionMode: "fresh" }
+				: { args: withOptionalSessionArgs(options.executionPlan.sessionName, retryArgs) },
+			reason: freshSessionAbandoned
+				? `Retry the first incomplete timed-out step${stepIndex === undefined ? "" : ` ${stepIndex}`} in a fresh browser session because the timed-out fresh session was not proven live.`
+				: `Retry the first incomplete timed-out step${stepIndex === undefined ? "" : ` ${stepIndex}`} against the current browser session.`,
+			safety: "Only read-only or idempotent timeout steps get executable retry args; inspect current page/artifact state before using the action.",
+			tool: "agent_browser" as const,
+		}];
+	}
+	if (!options.timeoutPartialProgress || freshSessionAbandoned || !options.executionPlan.sessionName) return [];
 	return [{
-		id: "retry-timeout-step",
-		params: freshSessionAbandoned
-			? { args: retryArgs, sessionMode: "fresh" }
-			: { args: withOptionalSessionArgs(options.executionPlan.sessionName, retryArgs) },
-		reason: freshSessionAbandoned
-			? `Retry the first incomplete timed-out step${stepIndex === undefined ? "" : ` ${stepIndex}`} in a fresh browser session because the timed-out fresh session was not proven live.`
-			: `Retry the first incomplete timed-out step${stepIndex === undefined ? "" : ` ${stepIndex}`} against the current browser session.`,
-		safety: "Only read-only or idempotent timeout steps get executable retry args; inspect current page/artifact state before using the action.",
+		id: "inspect-current-page-after-timeout",
+		params: { args: withOptionalSessionArgs(options.executionPlan.sessionName, ["snapshot", "-i"]) },
+		reason: `Inspect the current page after timeout before deciding how to resume${stepIndex === undefined ? "" : ` from incomplete step ${stepIndex}`}.`,
+		safety: "Read details.timeoutPartialProgress first. Do not blindly retry mutating steps such as clicks, fills, key presses, selects, or checks; split the remaining flow into shorter batches around the next navigation or DOM mutation boundary.",
 		tool: "agent_browser" as const,
 	}];
 }

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

@@ -0,0 +1,158 @@
+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 type { SessionArtifactManifest, SessionArtifactManifestEntry } from "../../../results/contracts.js";
+import { redactSensitiveText, type CompatibilityWorkaround } from "../../../runtime.js";
+import { buildSessionDetailFields, runSessionCommandData } from "../session-state.js";
+
+import type { AgentBrowserToolResult } from "../types.js";
+
+export interface DirectAnchorDownloadResult {
+	artifactManifest?: SessionArtifactManifest;
+	result: AgentBrowserToolResult;
+}
+
+const DIRECT_ANCHOR_DOWNLOAD_MAX_BYTES = 2 * 1024 * 1024;
+
+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]");
+}
+
+export async function tryDirectAnchorDownload(options: {
+	artifactManifest?: SessionArtifactManifest;
+	commandTokens: string[];
+	compatibilityWorkaround?: CompatibilityWorkaround;
+	cwd: string;
+	effectiveArgs: string[];
+	redactedArgs: string[];
+	sessionMode: "auto" | "fresh";
+	sessionName?: string;
+	signal?: AbortSignal;
+	usedImplicitSession: boolean;
+}): Promise<DirectAnchorDownloadResult | 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 manifestEntry: SessionArtifactManifestEntry = {
+			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" 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 {
+			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/extensions/agent-browser/lib/orchestration/browser-run/prepare/network-page-filter.ts

@@ -0,0 +1,116 @@
+import { isRecord } from "../../../parsing.js";
+import { buildAgentBrowserResultCategoryDetails } from "../../../results.js";
+import { redactSensitiveText, type CompatibilityWorkaround } from "../../../runtime.js";
+import { buildSessionDetailFields, runSessionCommandData } from "../session-state.js";
+
+import type { AgentBrowserToolResult } from "../types.js";
+
+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}`);
+}
+
+export 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,
+	};
+}