pi-agent-browser-native 0.2.46 → 0.2.48

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

@@ -60,20 +60,70 @@ function getUnsupportedJobStepField(step: Record<string, unknown>, allowedFields
 	return Object.keys(step).find((field) => !allowedFields.has(field));
 }
 
-const JOB_TYPE_ALLOWED_FIELDS = new Set(["action", "delayMs", "press", "selector", "text"]);
+function getUnsupportedJobStepFieldError(step: Record<string, unknown>, action: AgentBrowserJobStepAction, allowedFields: ReadonlySet<string>): string | undefined {
+	const unsupportedField = getUnsupportedJobStepField(step, allowedFields);
+	if (!unsupportedField) return undefined;
+	const supportedFields = [...allowedFields].filter((field) => field !== "action");
+	const supportedText = supportedFields.length > 0 ? `supported fields are ${supportedFields.join(", ")}.` : "no additional fields are supported.";
+	return `job step ${action} does not support ${unsupportedField}; ${supportedText}`;
+}
+
+const JOB_STEP_ALLOWED_FIELDS = {
+	assertText: new Set(["action", "text"]),
+	assertUrl: new Set(["action", "url"]),
+	click: new Set(["action", "locator", "name", "role", "selector", "value"]),
+	fill: new Set(["action", "locator", "name", "role", "selector", "text", "value"]),
+	open: new Set(["action", "loadState", "url"]),
+	screenshot: new Set(["action", "path"]),
+	select: new Set(["action", "selector", "value", "values"]),
+	snapshot: new Set(["action"]),
+	type: new Set(["action", "delayMs", "press", "selector", "text"]),
+	wait: new Set(["action", "milliseconds"]),
+	waitForDownload: new Set(["action", "path"]),
+} satisfies Record<AgentBrowserJobStepAction, ReadonlySet<string>>;
+
+type CompileJobStepResult = {
+	args?: string[];
+	error?: string;
+	extraSteps?: CompiledAgentBrowserJobStep[];
+	generatedFrom?: string;
+};
+
+type JobStepCompiler = (step: Record<string, unknown>, index: number) => CompileJobStepResult;
+
+type JobStepDescriptor = {
+	allowedFields: ReadonlySet<string>;
+	compile: JobStepCompiler;
+};
+
+function globUrlPatternToRegexSource(pattern: string): string {
+	let source = "^";
+	for (let index = 0; index < pattern.length; index += 1) {
+		const char = pattern.charAt(index);
+		if (char === "*") {
+			let runLength = 1;
+			while (pattern[index + runLength] === "*") runLength += 1;
+			source += runLength === 1 ? "[^/]*" : ".*";
+			index += runLength - 1;
+		} else {
+			source += char.replace(/[\\^$+?.()|[\]{}]/g, "\\$&");
+		}
+	}
+	return `${source}$`;
+}
+
+function compileJobAssertUrlArgs(url: string): string[] {
+	if (!url.includes("*")) return ["wait", "--url", url];
+	return ["wait", "--fn", `new RegExp(${JSON.stringify(globUrlPatternToRegexSource(url))}).test(location.href)`];
+}
 
 function compileJobTypeSteps(step: Record<string, unknown>): { error?: string; steps?: CompiledAgentBrowserJobStep[] } {
-	const unsupportedField = getUnsupportedJobStepField(step, JOB_TYPE_ALLOWED_FIELDS);
-	if (unsupportedField) return { error: `job step type does not support ${unsupportedField}; supported fields are selector, text, delayMs, and press.` };
 	const text = getRequiredJobString(step, "text", "type");
 	if (text.error) return { error: text.error };
 	const selector = step.selector;
 	if (selector !== undefined && (typeof selector !== "string" || selector.trim().length === 0)) {
 		return { error: "job step type selector must be a non-empty string when provided." };
 	}
-	if (step.locator !== undefined || step.role !== undefined || step.name !== undefined || step.value !== undefined || step.values !== undefined) {
-		return { error: "job step type supports selector, text, delayMs, and press only; focus the target first or use click/fill semantic locator fields in a separate step." };
-	}
 	const delayMs = step.delayMs;
 	if (delayMs !== undefined && (typeof delayMs !== "number" || !Number.isInteger(delayMs) || delayMs <= 0)) {
 		return { error: "job step type delayMs must be a positive integer when provided." };
@@ -102,6 +152,82 @@ function compileJobTypeSteps(step: Record<string, unknown>): { error?: string; s
 	return { steps: compiledSteps };
 }
 
+function compileOpenJobStep(step: Record<string, unknown>, index: number): CompileJobStepResult {
+	const result = getRequiredJobString(step, "url", "open");
+	if (result.error) return { error: result.error };
+	const extraSteps: CompiledAgentBrowserJobStep[] = [];
+	if (step.loadState !== undefined) {
+		if (typeof step.loadState !== "string" || !AGENT_BROWSER_QA_LOAD_STATES.includes(step.loadState as AgentBrowserQaLoadState)) {
+			return { error: `job.steps[${index}].loadState must be one of: ${AGENT_BROWSER_QA_LOAD_STATES.join(", ")}.` };
+		}
+		extraSteps.push({ action: "wait", args: ["wait", "--load", step.loadState], generatedFrom: "open.loadState" });
+	}
+	return { args: ["open", result.value as string], extraSteps };
+}
+
+function compileClickJobStep(step: Record<string, unknown>): CompileJobStepResult {
+	return compileJobClickOrFillStep(step, "click");
+}
+
+function compileFillJobStep(step: Record<string, unknown>): CompileJobStepResult {
+	return compileJobClickOrFillStep(step, "fill");
+}
+
+function compileTypeJobStep(step: Record<string, unknown>): CompileJobStepResult {
+	const result = compileJobTypeSteps(step);
+	if (result.error) return { error: result.error };
+	const [firstStep, ...extraSteps] = result.steps as CompiledAgentBrowserJobStep[];
+	return { args: firstStep.args, extraSteps, generatedFrom: firstStep.generatedFrom };
+}
+
+function compileSelectJobStep(step: Record<string, unknown>, index: number): CompileJobStepResult {
+	const selector = getRequiredJobString(step, "selector", "select");
+	if (selector.error) return { error: selector.error };
+	const values = getSelectValues(step, `job.steps[${index}]`);
+	if (values.error) return { error: values.error };
+	return { args: ["select", selector.value as string, ...(values.values as string[])] };
+}
+
+function compileWaitJobStep(step: Record<string, unknown>): CompileJobStepResult {
+	const milliseconds = step.milliseconds;
+	if (typeof milliseconds !== "number" || !Number.isInteger(milliseconds) || milliseconds <= 0) {
+		return { error: "job step wait requires a positive integer milliseconds value." };
+	}
+	return { args: ["wait", String(milliseconds)] };
+}
+
+function compileAssertTextJobStep(step: Record<string, unknown>): CompileJobStepResult {
+	const result = getRequiredJobString(step, "text", "assertText");
+	if (result.error) return { error: result.error };
+	return { args: ["wait", "--text", result.value as string] };
+}
+
+function compileAssertUrlJobStep(step: Record<string, unknown>): CompileJobStepResult {
+	const result = getRequiredJobString(step, "url", "assertUrl");
+	if (result.error) return { error: result.error };
+	return { args: compileJobAssertUrlArgs(result.value as string) };
+}
+
+function compilePathArtifactJobStep(step: Record<string, unknown>, action: "screenshot" | "waitForDownload"): CompileJobStepResult {
+	const result = getRequiredJobString(step, "path", action);
+	if (result.error) return { error: result.error };
+	return { args: action === "waitForDownload" ? ["wait", "--download", result.value as string] : ["screenshot", result.value as string] };
+}
+
+const JOB_STEP_DESCRIPTORS: Record<AgentBrowserJobStepAction, JobStepDescriptor> = {
+	assertText: { allowedFields: JOB_STEP_ALLOWED_FIELDS.assertText, compile: compileAssertTextJobStep },
+	assertUrl: { allowedFields: JOB_STEP_ALLOWED_FIELDS.assertUrl, compile: compileAssertUrlJobStep },
+	click: { allowedFields: JOB_STEP_ALLOWED_FIELDS.click, compile: compileClickJobStep },
+	fill: { allowedFields: JOB_STEP_ALLOWED_FIELDS.fill, compile: compileFillJobStep },
+	open: { allowedFields: JOB_STEP_ALLOWED_FIELDS.open, compile: compileOpenJobStep },
+	screenshot: { allowedFields: JOB_STEP_ALLOWED_FIELDS.screenshot, compile: (step) => compilePathArtifactJobStep(step, "screenshot") },
+	select: { allowedFields: JOB_STEP_ALLOWED_FIELDS.select, compile: compileSelectJobStep },
+	snapshot: { allowedFields: JOB_STEP_ALLOWED_FIELDS.snapshot, compile: () => ({ args: ["snapshot", "-i"] }) },
+	type: { allowedFields: JOB_STEP_ALLOWED_FIELDS.type, compile: compileTypeJobStep },
+	wait: { allowedFields: JOB_STEP_ALLOWED_FIELDS.wait, compile: compileWaitJobStep },
+	waitForDownload: { allowedFields: JOB_STEP_ALLOWED_FIELDS.waitForDownload, compile: (step) => compilePathArtifactJobStep(step, "waitForDownload") },
+};
+
 export function compileAgentBrowserJob(input: unknown): { compiled?: CompiledAgentBrowserJob; error?: string } {
 	if (!isRecord(input)) {
 		return { error: "job must be an object." };
@@ -125,62 +251,12 @@ export function compileAgentBrowserJob(input: unknown): { compiled?: CompiledAge
 			return { error: `job.steps[${index}].action must be one of: ${AGENT_BROWSER_JOB_STEP_ACTIONS.join(", ")}.` };
 		}
 		const jobAction = action as AgentBrowserJobStepAction;
-		let args: string[];
-		let generatedFrom: string | undefined;
-		let extraSteps: CompiledAgentBrowserJobStep[] = [];
-		if (jobAction === "open") {
-			const result = getRequiredJobString(rawStep, "url", jobAction);
-			if (result.error) return { error: `job.steps[${index}]: ${result.error}` };
-			args = ["open", result.value as string];
-			if (rawStep.loadState !== undefined) {
-				if (typeof rawStep.loadState !== "string" || !AGENT_BROWSER_QA_LOAD_STATES.includes(rawStep.loadState as AgentBrowserQaLoadState)) {
-					return { error: `job.steps[${index}].loadState must be one of: ${AGENT_BROWSER_QA_LOAD_STATES.join(", ")}.` };
-				}
-				extraSteps = [{ action: "wait", args: ["wait", "--load", rawStep.loadState], generatedFrom: "open.loadState" }];
-			}
-		} else if (jobAction === "click" || jobAction === "fill") {
-			const result = compileJobClickOrFillStep(rawStep, jobAction);
-			if (result.error) return { error: `job.steps[${index}]: ${result.error}` };
-			args = result.args as string[];
-		} else if (jobAction === "type") {
-			const result = compileJobTypeSteps(rawStep);
-			if (result.error) return { error: `job.steps[${index}]: ${result.error}` };
-			const [firstStep, ...restSteps] = result.steps as CompiledAgentBrowserJobStep[];
-			args = firstStep.args;
-			generatedFrom = firstStep.generatedFrom;
-			extraSteps = restSteps;
-		} else if (jobAction === "select") {
-			const selector = getRequiredJobString(rawStep, "selector", jobAction);
-			if (selector.error) return { error: `job.steps[${index}]: ${selector.error}` };
-			const values = getSelectValues(rawStep, `job.steps[${index}]`);
-			if (values.error) return { error: values.error };
-			args = ["select", selector.value as string, ...(values.values as string[])];
-		} else if (jobAction === "wait") {
-			const milliseconds = rawStep.milliseconds;
-			if (typeof milliseconds !== "number" || !Number.isInteger(milliseconds) || milliseconds <= 0) {
-				return { error: `job.steps[${index}]: job step wait requires a positive integer milliseconds value.` };
-			}
-			args = ["wait", String(milliseconds)];
-		} else if (jobAction === "assertText") {
-			const result = getRequiredJobString(rawStep, "text", jobAction);
-			if (result.error) return { error: `job.steps[${index}]: ${result.error}` };
-			args = ["wait", "--text", result.value as string];
-		} else if (jobAction === "assertUrl") {
-			const result = getRequiredJobString(rawStep, "url", jobAction);
-			if (result.error) return { error: `job.steps[${index}]: ${result.error}` };
-			args = ["wait", "--url", result.value as string];
-		} else if (jobAction === "waitForDownload") {
-			const result = getRequiredJobString(rawStep, "path", jobAction);
-			if (result.error) return { error: `job.steps[${index}]: ${result.error}` };
-			args = ["wait", "--download", result.value as string];
-		} else if (jobAction === "snapshot") {
-			args = ["snapshot", "-i"];
-		} else {
-			const result = getRequiredJobString(rawStep, "path", jobAction);
-			if (result.error) return { error: `job.steps[${index}]: ${result.error}` };
-			args = ["screenshot", result.value as string];
-		}
-		steps.push({ action: jobAction, args, generatedFrom }, ...extraSteps);
+		const descriptor = JOB_STEP_DESCRIPTORS[jobAction];
+		const unsupportedFieldError = getUnsupportedJobStepFieldError(rawStep, jobAction, descriptor.allowedFields);
+		if (unsupportedFieldError) return { error: `job.steps[${index}]: ${unsupportedFieldError}` };
+		const compiledStep = descriptor.compile(rawStep, index);
+		if (compiledStep.error) return { error: compiledStep.error.startsWith(`job.steps[${index}]`) ? compiledStep.error : `job.steps[${index}]: ${compiledStep.error}` };
+		steps.push({ action: jobAction, args: compiledStep.args as string[], generatedFrom: compiledStep.generatedFrom }, ...(compiledStep.extraSteps ?? []));
 	}
 	return { compiled: { args: failFast ? ["batch", "--bail"] : ["batch"], failFast, stdin: JSON.stringify(steps.map((step) => step.args)), steps } };
 }

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;
+	}
+}