pi-agent-browser-native 0.2.42 → 0.2.43

package/extensions/agent-browser/lib/orchestration/browser-run/process-output.ts

@@ -3,6 +3,7 @@ import { readFile, rm } from "node:fs/promises";
 import { isCloseCommand, isOpenNavigationCommand } from "../../command-taxonomy.js";
 import { cleanupElectronLaunchResources, inspectElectronLaunchStatus, type ElectronCleanupResult } from "../../electron/cleanup.js";
 import type { ElectronLaunchRecord } from "../../electron/launch.js";
+import { getAllowedDomainsViolation, parseAllowedDomainsPolicyFromArgs } from "../../navigation-policy.js";
 import {
 	analyzeNetworkSourceLookupResults,
 	analyzeQaPresetResults,
@@ -12,6 +13,8 @@ import {
 	redactNetworkSourceLookupAnalysis,
 } from "../../input-modes.js";
 import {
+	applyNetworkRouteRecords,
+	buildNetworkRouteDiagnostics,
 	buildToolPresentation,
 	getAgentBrowserErrorText,
 	parseAgentBrowserEnvelope,
@@ -22,7 +25,8 @@ import {
 	formatSessionArtifactRetentionSummary,
 	mergeSessionArtifactManifest,
 } from "../../results/artifact-manifest.js";
-import type { SessionArtifactManifest } from "../../results/contracts.js";
+import type { NetworkRouteRecord, SessionArtifactManifest } from "../../results/contracts.js";
+import { getClipboardWritePayloadCandidates, redactClipboardPermissionEcho, redactClipboardPermissionErrorValue } from "../../results/presentation/errors.js";
 import { shouldCaptureSemanticActionNavigationSummary } from "../../results/presentation/semantic-action.js";
 import {
 	commandExplicitlyTargetsAboutBlank,
@@ -39,7 +43,7 @@ import {
 import type { PersistentSessionArtifactEviction, PersistentSessionArtifactStore } from "../../temp.js";
 import { writePersistentSessionArtifactFile, writeSecureTempFile } from "../../temp.js";
 import { isRecord } from "../../parsing.js";
-import { createFreshSessionName, hasLaunchScopedTabCorrectionFlag, resolveManagedSessionState } from "../../runtime.js";
+import { createFreshSessionName, extractCommandTokens, hasLaunchScopedTabCorrectionFlag, resolveManagedSessionState } from "../../runtime.js";
 import {
 	applyOpenResultTabCorrection,
 	buildAboutBlankRecoveryHint,
@@ -142,6 +146,44 @@ async function repairBatchScreenshotArtifacts(options: {
 	return { envelope: { ...envelope, data: repairedData }, requests: repairedRequests };
 }
 
+function getEnvelopeErrorString(envelope: AgentBrowserEnvelope | undefined): string | undefined {
+	if (!envelope?.error) return undefined;
+	if (typeof envelope.error === "string") return envelope.error;
+	if (isRecord(envelope.error) && typeof envelope.error.message === "string") return envelope.error.message;
+	return String(envelope.error);
+}
+
+function isStreamEnableAlreadyEnabledNoop(options: { command: string | undefined; envelope: AgentBrowserEnvelope | undefined; processSucceeded: boolean; subcommand: string | undefined }): boolean {
+	if (!options.processSucceeded || options.command !== "stream" || options.subcommand !== "enable" || options.envelope?.success !== false) return false;
+	const message = (getEnvelopeErrorString(options.envelope) ?? "").trim().replace(/[.!]+$/, "").toLowerCase();
+	return message === "streaming is already enabled for this session" || message === "streaming is already enabled" || message === "stream already enabled";
+}
+
+function setNetworkRouteState(options: { routes?: NetworkRouteRecord[]; routesBySession: Map<string, NetworkRouteRecord[]>; sessionName: string | undefined }): Map<string, NetworkRouteRecord[]> {
+	if (!options.sessionName) return options.routesBySession;
+	const previousRoutes = options.routesBySession.get(options.sessionName);
+	if (options.routes === previousRoutes) return options.routesBySession;
+	const next = new Map(options.routesBySession);
+	if (options.routes && options.routes.length > 0) next.set(options.sessionName, options.routes);
+	else next.delete(options.sessionName);
+	return next;
+}
+
+function applyNetworkRouteState(options: { commandTokens: string[]; routesBySession: Map<string, NetworkRouteRecord[]>; sessionName: string | undefined; succeeded: boolean }): Map<string, NetworkRouteRecord[]> {
+	const routes = options.sessionName ? applyNetworkRouteRecords(options.routesBySession.get(options.sessionName), options.commandTokens, options.succeeded) : undefined;
+	return setNetworkRouteState({ routes, routesBySession: options.routesBySession, sessionName: options.sessionName });
+}
+
+function applyBatchNetworkRouteState(options: { data: unknown; routesBySession: Map<string, NetworkRouteRecord[]>; sessionName: string | undefined; succeeded: boolean }): Map<string, NetworkRouteRecord[]> {
+	if (!options.succeeded || !options.sessionName || !Array.isArray(options.data)) return options.routesBySession;
+	let routes = options.routesBySession.get(options.sessionName);
+	for (const item of options.data) {
+		if (!isRecord(item) || !Array.isArray(item.command) || !item.command.every((token) => typeof token === "string")) continue;
+		routes = applyNetworkRouteRecords(routes, extractCommandTokens(item.command as string[]), item.success !== false);
+	}
+	return setNetworkRouteState({ routes, routesBySession: options.routesBySession, sessionName: options.sessionName });
+}
+
 export async function preserveParseFailureOutput(options: {
 	artifactManifest?: SessionArtifactManifest;
 	exactSensitiveValues?: string[];
@@ -180,11 +222,13 @@ export async function processBrowserOutput(input: ProcessBrowserOutputInput): Pr
 	const { ctx, cwd, electronPostCommandStatusSettleMs, implicitSessionCloseTimeoutMs, sessionPageStateUpdate, signal, state } = input;
 	const { prepared, processResult } = input;
 	const { electronChildProcesses, electronLaunchRecords, sessionPageState, traceOwners } = state;
+	let allowedDomainsBySession = state.allowedDomainsBySession;
 	let artifactManifest = state.artifactManifest;
 	let freshSessionOrdinal = state.freshSessionOrdinal;
 	let managedSessionActive = state.managedSessionActive;
 	let managedSessionCwd = state.managedSessionCwd;
 	let managedSessionName = state.managedSessionName;
+	let networkRoutesBySession = state.networkRoutesBySession;
 	try {
 		const persistentArtifactStore = getPersistentSessionArtifactStore(ctx);
 		const parsed = await parseAgentBrowserEnvelope({ stdout: processResult.stdout, stdoutPath: processResult.stdoutSpillPath });
@@ -208,6 +252,9 @@ export async function processBrowserOutput(input: ProcessBrowserOutputInput): Pr
 		const processSucceeded = !processResult.aborted && !processResult.spawnError && processResult.exitCode === 0;
 		const plainTextInspection = prepared.executionPlan.plainTextInspection && processSucceeded;
 		const parseSucceeded = plainTextInspection || parseError === undefined;
+		if (isStreamEnableAlreadyEnabledNoop({ command: prepared.executionPlan.commandInfo.command, envelope: presentationEnvelope, processSucceeded, subcommand: prepared.executionPlan.commandInfo.subcommand })) {
+			presentationEnvelope = { success: true, data: { alreadyEnabled: true, enabled: true, message: getEnvelopeErrorString(presentationEnvelope) ?? "Stream already enabled" } };
+		}
 		const envelopeSuccess = plainTextInspection ? true : presentationEnvelope?.success !== false;
 		let succeeded = processSucceeded && parseSucceeded && envelopeSuccess;
 		const inspectionText = plainTextInspection ? processResult.stdout.trim() : undefined;
@@ -222,15 +269,21 @@ export async function processBrowserOutput(input: ProcessBrowserOutputInput): Pr
 			}
 		}
 
+		const parsedAllowedDomainsPolicy = parseAllowedDomainsPolicyFromArgs(prepared.runtimeToolArgs);
+		const sessionAllowedDomainsPolicy = prepared.executionPlan.sessionName
+			? parsedAllowedDomainsPolicy ?? allowedDomainsBySession.get(prepared.executionPlan.sessionName)
+			: parsedAllowedDomainsPolicy;
+		const shouldCaptureAllowedDomainNavigationSummary = prepared.executionPlan.commandInfo.command === "batch" && sessionAllowedDomainsPolicy !== undefined;
 		if (
 			succeeded &&
 			!navigationSummary &&
 			(shouldCaptureNavigationSummary(prepared.executionPlan.commandInfo.command, presentationEnvelope?.data) ||
-				shouldCaptureSemanticActionNavigationSummary(prepared.compiledSemanticAction, presentationEnvelope?.data))
+				shouldCaptureSemanticActionNavigationSummary(prepared.compiledSemanticAction, presentationEnvelope?.data) ||
+				shouldCaptureAllowedDomainNavigationSummary)
 		) {
 			navigationSummary = await collectNavigationSummary({ cwd, sessionName: prepared.executionPlan.sessionName, signal });
 		}
-		if (navigationSummary && presentationEnvelope) presentationEnvelope = { ...presentationEnvelope, data: mergeNavigationSummaryIntoData(presentationEnvelope.data, navigationSummary) };
+		if (navigationSummary && presentationEnvelope && !Array.isArray(presentationEnvelope.data)) presentationEnvelope = { ...presentationEnvelope, data: mergeNavigationSummaryIntoData(presentationEnvelope.data, navigationSummary) };
 		let overlayBlockerDiagnostic: Awaited<ReturnType<typeof collectOverlayBlockerDiagnostic>>;
 
 		let openResultTabCorrection: Awaited<ReturnType<typeof collectOpenResultTabCorrection>>;
@@ -270,6 +323,19 @@ export async function processBrowserOutput(input: ProcessBrowserOutputInput): Pr
 				if (appliedPostCommandCorrection && !sessionTabCorrection) sessionTabCorrection = appliedPostCommandCorrection;
 			}
 		}
+		if (succeeded && prepared.executionPlan.sessionName && parsedAllowedDomainsPolicy) {
+			allowedDomainsBySession = new Map(allowedDomainsBySession);
+			allowedDomainsBySession.set(prepared.executionPlan.sessionName, parsedAllowedDomainsPolicy);
+		}
+		const allowedDomainsViolation = succeeded ? getAllowedDomainsViolation({
+			policy: sessionAllowedDomainsPolicy,
+			url: currentSessionTabTarget?.url ?? observedSessionTabTarget?.url ?? navigationSummary?.url,
+		}) : undefined;
+		if (allowedDomainsViolation) {
+			succeeded = false;
+			presentationEnvelope = { ...(presentationEnvelope ?? {}), error: allowedDomainsViolation.summary, success: false };
+		}
+
 		const electronRecordForCommand = findElectronLaunchRecordForSession(prepared.executionPlan.sessionName, electronLaunchRecords);
 		if (succeeded && electronRecordForCommand && shouldInspectElectronPostCommandHealth(prepared.executionPlan.commandInfo.command)) {
 			electronStatusAfterCommand ??= await inspectElectronLaunchStatus(electronRecordForCommand);
@@ -292,8 +358,13 @@ export async function processBrowserOutput(input: ProcessBrowserOutputInput): Pr
 		if (succeeded && !sessionTabCorrection && !aboutBlankSessionMismatch && !electronRecordForCommand && !clickDispatchDiagnostic) overlayBlockerDiagnostic = await collectOverlayBlockerDiagnostic({ command: prepared.executionPlan.commandInfo.command, cwd, data: presentationEnvelope?.data, navigationSummary, priorTarget: prepared.priorSessionTabTarget, sessionName: prepared.executionPlan.sessionName, signal });
 		if (succeeded) {
 			selectorTextVisibilityDiagnostics = await collectSelectorTextVisibilityDiagnostics({ commandInfo: prepared.executionPlan.commandInfo, commandTokens: prepared.commandTokens, cwd, data: presentationEnvelope?.data, sessionName: prepared.executionPlan.sessionName, signal });
-			electronBroadGetTextScopeDiagnostics = collectElectronBroadGetTextScopeDiagnostics({ commandInfo: prepared.executionPlan.commandInfo, commandTokens: prepared.commandTokens, currentTarget: currentSessionTabTarget, data: presentationEnvelope?.data, electronLaunchRecords, priorTarget: prepared.priorSessionTabTarget, sessionName: prepared.executionPlan.sessionName });
+			if (electronRecordForCommand) electronBroadGetTextScopeDiagnostics = collectElectronBroadGetTextScopeDiagnostics({ commandInfo: prepared.executionPlan.commandInfo, commandTokens: prepared.commandTokens, currentTarget: currentSessionTabTarget, data: presentationEnvelope?.data, electronLaunchRecords, priorTarget: prepared.priorSessionTabTarget, sessionName: prepared.executionPlan.sessionName });
 		}
+		const activeNetworkRoutes = prepared.executionPlan.sessionName ? networkRoutesBySession.get(prepared.executionPlan.sessionName) : undefined;
+		const networkRouteDiagnostics = succeeded && prepared.executionPlan.commandInfo.command === "network" && prepared.executionPlan.commandInfo.subcommand === "requests" && prepared.executionPlan.sessionName
+			? buildNetworkRouteDiagnostics(presentationEnvelope?.data, activeNetworkRoutes)
+			: undefined;
+		networkRoutesBySession = applyNetworkRouteState({ commandTokens: prepared.commandTokens, routesBySession: networkRoutesBySession, sessionName: prepared.executionPlan.sessionName, succeeded });
 		const comboboxFocusDiagnostic = succeeded ? await collectComboboxFocusDiagnostic({ command: prepared.executionPlan.commandInfo.command, commandTokens: prepared.commandTokens, cwd, semanticAction: prepared.compiledSemanticAction, sessionName: prepared.executionPlan.sessionName, signal }) : undefined;
 		const recordingDependencyWarning = await collectRecordingDependencyWarning({ command: prepared.executionPlan.commandInfo.command, commandTokens: prepared.commandTokens, succeeded });
 		const scrollNoopDiagnostic = succeeded && prepared.shouldProbeScrollNoop ? buildScrollNoopDiagnostic(prepared.scrollPositionBefore, await collectScrollPositionSnapshot({ cwd, sessionName: prepared.executionPlan.sessionName, signal })) : undefined;
@@ -302,6 +373,10 @@ export async function processBrowserOutput(input: ProcessBrowserOutputInput): Pr
 		const batchRefSnapshotState = prepared.executionPlan.commandInfo.command === "batch" ? extractLatestRefSnapshotStateFromBatchResults(presentationEnvelope?.data) : undefined;
 		if (prepared.executionPlan.sessionName) {
 			if (isCloseCommand(prepared.executionPlan.commandInfo.command) && succeeded) {
+				allowedDomainsBySession = new Map(allowedDomainsBySession);
+				allowedDomainsBySession.delete(prepared.executionPlan.sessionName);
+				networkRoutesBySession = new Map(networkRoutesBySession);
+				networkRoutesBySession.delete(prepared.executionPlan.sessionName);
 				sessionPageState.clearSession(prepared.executionPlan.sessionName);
 				state.closedManagedSessionNames.add(prepared.executionPlan.sessionName);
 			} else if (currentSessionTabTarget) {
@@ -327,7 +402,9 @@ export async function processBrowserOutput(input: ProcessBrowserOutputInput): Pr
 		const managedCloseSessionName = commandClosesSession && succeeded && prepared.executionPlan.sessionName === priorManagedSessionName
 			? prepared.executionPlan.sessionName
 			: prepared.executionPlan.managedSessionName;
-		const managedSessionState = resolveManagedSessionState({ command: prepared.executionPlan.commandInfo.command, managedSessionName: managedCloseSessionName, priorActive: priorManagedSessionActive, priorSessionName: priorManagedSessionName, succeeded });
+		const policyBlockedFreshManagedSession = allowedDomainsViolation !== undefined && prepared.sessionMode === "fresh" && prepared.executionPlan.managedSessionName === prepared.executionPlan.sessionName;
+		const managedTransitionSucceeded = succeeded || policyBlockedFreshManagedSession;
+		const managedSessionState = resolveManagedSessionState({ command: prepared.executionPlan.commandInfo.command, managedSessionName: managedCloseSessionName, priorActive: priorManagedSessionActive, priorSessionName: priorManagedSessionName, succeeded: managedTransitionSucceeded });
 		const replacedManagedSessionName = managedSessionState.replacedSessionName;
 		managedSessionActive = managedSessionState.active;
 		managedSessionName = managedSessionState.sessionName;
@@ -335,13 +412,17 @@ export async function processBrowserOutput(input: ProcessBrowserOutputInput): Pr
 			freshSessionOrdinal += 1;
 			managedSessionName = createFreshSessionName(state.managedSessionBaseName, state.ephemeralSessionSeed, freshSessionOrdinal);
 		}
-		let managedSessionOutcome = buildManagedSessionOutcome({ activeAfter: managedSessionActive, activeBefore: priorManagedSessionActive, attemptedSessionName: managedCloseSessionName, command: prepared.executionPlan.commandInfo.command, currentSessionName: managedSessionName, previousSessionName: priorManagedSessionName, replacedSessionName: replacedManagedSessionName, sessionMode: prepared.sessionMode, succeeded });
+		let managedSessionOutcome = buildManagedSessionOutcome({ activeAfter: managedSessionActive, activeBefore: priorManagedSessionActive, attemptedSessionName: managedCloseSessionName, command: prepared.executionPlan.commandInfo.command, currentSessionName: managedSessionName, previousSessionName: priorManagedSessionName, replacedSessionName: replacedManagedSessionName, sessionMode: prepared.sessionMode, succeeded: managedTransitionSucceeded });
 		if (prepared.executionPlan.managedSessionName && succeeded) managedSessionCwd = cwd;
 		if (prepared.executionPlan.sessionName && succeeded) {
 			if (openResultTabCorrection || sessionTabCorrection || aboutBlankSessionMismatch?.recoveryApplied) sessionPageState.markPinning(prepared.executionPlan.sessionName, "drift");
 			else if (prepared.sessionTabPinningReason === "restore") sessionPageState.clearRestorePinning(prepared.executionPlan.sessionName);
 		}
 		if (replacedManagedSessionName) {
+			allowedDomainsBySession = new Map(allowedDomainsBySession);
+			allowedDomainsBySession.delete(replacedManagedSessionName);
+			networkRoutesBySession = new Map(networkRoutesBySession);
+			networkRoutesBySession.delete(replacedManagedSessionName);
 			sessionPageState.clearSession(replacedManagedSessionName);
 			const replacedCloseError = await closeManagedSession({ cwd: priorManagedSessionCwd, sessionName: replacedManagedSessionName, timeoutMs: implicitSessionCloseTimeoutMs });
 			if (!replacedCloseError) state.closedManagedSessionNames.add(replacedManagedSessionName);
@@ -373,8 +454,18 @@ export async function processBrowserOutput(input: ProcessBrowserOutputInput): Pr
 			}
 		}
 
-		const errorText = getAgentBrowserErrorText({ aborted: processResult.aborted, command: prepared.executionPlan.commandInfo.command, effectiveArgs: prepared.redactedProcessArgs, envelope: presentationEnvelope, exitCode: processResult.exitCode, parseError, plainTextInspection, staleRefArgs: getStaleRefArgs(prepared.commandTokens, prepared.runtimeToolStdin), spawnError: processResult.spawnError, stderr: processResult.stderr, timedOut: processResult.timedOut, timeoutMs: processResult.timeoutMs, wrapperRecoveryHint: buildWrapperRecoveryHint({ pinnedBatchUnwrapMode: prepared.pinnedBatchUnwrapMode, sessionTabCorrection }) });
-		const presentation = plainTextInspection ? { artifacts: undefined, batchFailure: undefined, batchSteps: undefined, content: [{ type: "text" as const, text: inspectionText ?? "" }], data: undefined, fullOutputPath: undefined, fullOutputPaths: undefined, imagePath: undefined, imagePaths: undefined, savedFile: undefined, savedFilePath: undefined, summary: `${prepared.redactedArgs.join(" ")} completed` } : await buildToolPresentation({ args: prepared.redactedProcessArgs, artifactManifest, artifactRequest: screenshotArtifactRequest, batchArtifactRequests: batchScreenshotArtifactRequests, commandInfo: prepared.executionPlan.commandInfo, compiledSemanticAction: prepared.compiledSemanticAction, cwd, envelope: presentationEnvelope, errorText, persistentArtifactStore, sessionName: prepared.executionPlan.sessionName });
+		let errorText = getAgentBrowserErrorText({ aborted: processResult.aborted, command: prepared.executionPlan.commandInfo.command, effectiveArgs: prepared.redactedProcessArgs, envelope: presentationEnvelope, exitCode: processResult.exitCode, parseError, plainTextInspection, staleRefArgs: getStaleRefArgs(prepared.commandTokens, prepared.runtimeToolStdin), spawnError: processResult.spawnError, stderr: processResult.stderr, timedOut: processResult.timedOut, timeoutMs: processResult.timeoutMs, wrapperRecoveryHint: buildWrapperRecoveryHint({ pinnedBatchUnwrapMode: prepared.pinnedBatchUnwrapMode, sessionTabCorrection }) });
+		if (errorText) {
+			const clipboardWritePayloadCandidates = getClipboardWritePayloadCandidates(prepared.commandTokens);
+			errorText = redactClipboardPermissionEcho(prepared.executionPlan.commandInfo, errorText);
+			if (presentationEnvelope?.error !== undefined) presentationEnvelope = { ...presentationEnvelope, error: redactClipboardPermissionErrorValue(prepared.executionPlan.commandInfo, presentationEnvelope.error, clipboardWritePayloadCandidates) };
+		}
+		const presentation = plainTextInspection ? { artifacts: undefined, batchFailure: undefined, batchSteps: undefined, content: [{ type: "text" as const, text: inspectionText ?? "" }], data: undefined, fullOutputPath: undefined, fullOutputPaths: undefined, imagePath: undefined, imagePaths: undefined, savedFile: undefined, savedFilePath: undefined, summary: `${prepared.redactedArgs.join(" ")} completed` } : await buildToolPresentation({ args: prepared.redactedProcessArgs, artifactManifest, artifactRequest: screenshotArtifactRequest, batchArtifactRequests: batchScreenshotArtifactRequests, commandInfo: prepared.executionPlan.commandInfo, compiledSemanticAction: prepared.compiledSemanticAction, cwd, envelope: presentationEnvelope, errorText, networkRouteDiagnostics, networkRoutes: activeNetworkRoutes, persistentArtifactStore, sessionName: prepared.executionPlan.sessionName });
+		networkRoutesBySession = applyBatchNetworkRouteState({ data: presentationEnvelope?.data, routesBySession: networkRoutesBySession, sessionName: prepared.executionPlan.sessionName, succeeded });
+		if (presentation.failureCategory === "artifact-missing") {
+			succeeded = false;
+			presentationEnvelope = { ...(presentationEnvelope ?? {}), error: presentation.summary, success: false };
+		}
 		if (parseFailureOutput.artifactManifest) { presentation.artifactManifest = parseFailureOutput.artifactManifest; presentation.artifactRetentionSummary = parseFailureOutput.artifactRetentionSummary; }
 		if (parseFailureOutput.fullOutputPath || parseFailureOutput.fullOutputUnavailable) {
 			const existingText = presentation.content[0]?.type === "text" ? presentation.content[0].text : "";
@@ -394,13 +485,13 @@ export async function processBrowserOutput(input: ProcessBrowserOutputInput): Pr
 		else if (networkSourceLookup) presentation.content.unshift({ type: "text", text: networkSourceLookup.summary });
 		if (sourceLookup && presentation.content[0]?.type === "text") presentation.content[0] = { ...presentation.content[0], text: `${sourceLookup.summary}\n\n${presentation.content[0].text}` };
 		else if (sourceLookup) presentation.content.unshift({ type: "text", text: sourceLookup.summary });
-		if (qaPreset && !qaPreset.passed) {
+		if (qaPreset && !qaPreset.passed && presentation.failureCategory !== "artifact-missing") {
 			succeeded = false;
 			presentation.failureCategory = "qa-failure";
 			presentation.summary = qaPreset.summary;
 			if (presentation.content[0]?.type === "text") presentation.content[0] = { ...presentation.content[0], text: `${qaPreset.summary}\n\n${presentation.content[0].text}` };
 			else presentation.content.unshift({ type: "text", text: qaPreset.summary });
-		} else if (qaPreset?.passed && prepared.compiledQaPreset) {
+		} else if (qaPreset?.passed && prepared.compiledQaPreset && succeeded) {
 			const compactText = buildQaCompactPassText({
 				artifactVerification: presentation.artifactVerification,
 				batchStepCount: presentation.batchSteps?.length ?? prepared.compiledQaPreset.steps.length,
@@ -434,7 +525,7 @@ export async function processBrowserOutput(input: ProcessBrowserOutputInput): Pr
 		currentRefSnapshot = finalRecoveryState.currentRefSnapshot;
 		currentRefSnapshotInvalidation = finalRecoveryState.currentRefSnapshotInvalidation;
 		const result = buildFinalAgentBrowserToolResult({ aboutBlankSessionMismatch, artifactCleanup, categoryDetails: finalRecoveryState.categoryDetails, clickDispatchDiagnostic, commandTokens: prepared.commandTokens, comboboxFocusDiagnostic, compiledNetworkSourceLookup: prepared.compiledNetworkSourceLookup, compiledSemanticAction: prepared.compiledSemanticAction, compatibilityWorkaround: prepared.compatibilityWorkaround, currentRefSnapshot, currentRefSnapshotInvalidation, currentSessionTabTarget, electronBroadGetTextScopeDiagnostics, electronFailedConnectCleanup, electronHandoff, electronLaunch: prepared.electronLaunch, electronLaunchRecord, electronLaunchRecords, electronPostCommandHealth, electronProfileIsolationDetails: input.electronProfileIsolationDetails, electronRefFreshnessDiagnostic, electronSessionMismatch, errorText, evalResultWarning, evalStdinHint, exactSensitiveValues: prepared.exactSensitiveValues, executionPlan: prepared.executionPlan, fillVerificationDiagnostic, inspectionText, managedSessionOutcome, navigationSummary, networkSourceLookup, noActivePageSnapshotFailure: finalRecoveryState.noActivePageSnapshotFailure, openResultTabCorrection, overlayBlockerDiagnostic, parseError, parseFailureOutput, parseSucceeded, plainTextInspection, presentation, presentationEnvelope, priorSessionTabTarget: prepared.priorSessionTabTarget, processResult, qaAttachedTarget, qaPreset, recordingDependencyWarning, redactedArgs: prepared.redactedArgs, redactedCompiledElectron: prepared.redactedCompiledElectron, redactedCompiledJob: prepared.redactedCompiledJob, redactedCompiledNetworkSourceLookup: prepared.redactedCompiledNetworkSourceLookup, redactedCompiledQaPreset: prepared.redactedCompiledQaPreset, redactedCompiledSemanticAction: prepared.redactedCompiledSemanticAction, redactedCompiledSourceLookup: prepared.redactedCompiledSourceLookup, redactedContent, redactedProcessArgs: prepared.redactedProcessArgs, redactedRecoveryHint: prepared.redactedRecoveryHint, resultArtifactManifest, richInputRecoveryDiagnostic: finalRecoveryState.richInputRecoveryDiagnostic, scrollNoopDiagnostic, selectorTextVisibilityDiagnostics, sessionMode: prepared.sessionMode, sessionTabCorrection, sourceLookup, succeeded, timeoutPartialProgress, userRequestedJson: prepared.userRequestedJson, visibleRefFallbackDiagnostic: finalRecoveryState.visibleRefFallbackDiagnostic, visibleRefFallbackSessionName: finalRecoveryState.visibleRefFallbackSessionName });
-		const statePatch: BrowserRunStatePatch = { artifactManifest, freshSessionOrdinal, managedSessionActive, managedSessionCwd, managedSessionName };
+		const statePatch: BrowserRunStatePatch = { allowedDomainsBySession, artifactManifest, freshSessionOrdinal, managedSessionActive, managedSessionCwd, managedSessionName, networkRoutesBySession };
 		return { result, statePatch };
 	} finally {
 		if (processResult.stdoutSpillPath) await rm(processResult.stdoutSpillPath, { force: true }).catch(() => undefined);

package/extensions/agent-browser/lib/orchestration/browser-run/session-state.ts

@@ -50,11 +50,13 @@ export const NAVIGATION_SUMMARY_EVAL = `({ title: document.title, url: location.
 
 export function applyBrowserRunStatePatch(state: BrowserRunState, patch: BrowserRunStatePatch | undefined): void {
 	if (!patch) return;
+	if (patch.allowedDomainsBySession) state.allowedDomainsBySession = patch.allowedDomainsBySession;
 	if ("artifactManifest" in patch) state.artifactManifest = patch.artifactManifest;
 	if (patch.freshSessionOrdinal !== undefined) state.freshSessionOrdinal = patch.freshSessionOrdinal;
 	if (patch.managedSessionActive !== undefined) state.managedSessionActive = patch.managedSessionActive;
 	if (patch.managedSessionCwd !== undefined) state.managedSessionCwd = patch.managedSessionCwd;
 	if (patch.managedSessionName !== undefined) state.managedSessionName = patch.managedSessionName;
+	if (patch.networkRoutesBySession) state.networkRoutesBySession = patch.networkRoutesBySession;
 }
 
 export function buildSessionDetailFields(sessionName: string | undefined, usedImplicitSession: boolean): Record<string, unknown> {
@@ -321,7 +323,22 @@ export function getGuardedRefUsage(commandTokens: string[], stdin?: string, opti
 	return refsBeforeInBatchSnapshot;
 }
 
-function getBatchRefInvalidationMessage(commandTokens: string[], stdin?: string): string | undefined {
+function getSnapshotRefRole(refSnapshot: SessionRefSnapshot | undefined, refId: string): string | undefined {
+	return refSnapshot?.refs?.[refId]?.role?.toLowerCase();
+}
+
+function isSafeSameSnapshotFormBatchStep(step: string[], refSnapshot: SessionRefSnapshot | undefined): boolean {
+	const command = step[0];
+	const refIds = collectRefsFromTokens(step);
+	if (refIds.length === 0 || !refSnapshot) return false;
+	const roles = refIds.map((refId) => getSnapshotRefRole(refSnapshot, refId));
+	if (roles.some((role) => role === undefined)) return false;
+	if (command === "check" || command === "uncheck") return roles.every((role) => role === "checkbox" || role === "radio");
+	if (command === "select") return roles.every((role) => role === "combobox");
+	return false;
+}
+
+function getBatchRefInvalidationMessage(commandTokens: string[], stdin?: string, refSnapshot?: SessionRefSnapshot): string | undefined {
 	if (commandTokens[0] !== "batch" || stdin === undefined) return undefined;
 	const parsed = parseUserBatchStdin(stdin);
 	if (parsed.error || parsed.steps === undefined) return undefined;
@@ -334,7 +351,7 @@ function getBatchRefInvalidationMessage(commandTokens: string[], stdin?: string)
 		if (refIds.length > 0 && isRefGuardedCommand(step[0]) && priorStepInvalidatesRefs) {
 			return `Batch step ${step[0]} uses page-scoped ref ${refIds.map((refId) => `@${refId}`).join(", ")} after an earlier batch step can navigate or mutate the page. Split the batch, run snapshot -i after the page-changing step, then retry with current refs.`;
 		}
-		if (isRefInvalidatingBatchCommand(step[0])) {
+		if (isRefInvalidatingBatchCommand(step[0]) && !isSafeSameSnapshotFormBatchStep(step, refSnapshot)) {
 			priorStepInvalidatesRefs = true;
 		}
 	}
@@ -352,7 +369,7 @@ export function buildStaleRefPreflight(options: {
 	const usedRefIds = options.refSnapshotInvalidation
 		? [...new Set(getGuardedRefUsage(options.commandTokens, options.stdin, { includeRefsAfterBatchSnapshot: true }))]
 		: guardedRefIds;
-	const batchInvalidationMessage = getBatchRefInvalidationMessage(options.commandTokens, options.stdin);
+	const batchInvalidationMessage = getBatchRefInvalidationMessage(options.commandTokens, options.stdin, options.refSnapshot);
 	if (batchInvalidationMessage && guardedRefIds.length > 0) {
 		return {
 			message: batchInvalidationMessage,

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

@@ -16,10 +16,11 @@ import type {
 } from "../../input-modes.js";
 import type { runAgentBrowserProcess } from "../../process.js";
 import type { AgentBrowserEnvelope, AgentBrowserNextAction, buildAgentBrowserResultCategoryDetails, buildToolPresentation } from "../../results.js";
-import type { SessionArtifactManifest } from "../../results/contracts.js";
+import type { NetworkRouteRecord, SessionArtifactManifest } from "../../results/contracts.js";
 import type { RichInputRecoveryDiagnostic, VisibleRefFallbackDiagnostic } from "../../results/selector-recovery.js";
 import type { SessionPageState, SessionRefSnapshot, SessionRefSnapshotInvalidation, SessionTabTarget } from "../../session-page-state.js";
 import type { buildExecutionPlan, CompatibilityWorkaround, OpenResultTabCorrection } from "../../runtime.js";
+import type { AllowedDomainsPolicy } from "../../navigation-policy.js";
 import type { PromptPolicy } from "../../prompt-policy.js";
 import type { AgentBrowserExecuteParams, ResolvedAgentBrowserValidInput } from "../input-plan.js";
 import type { BatchCommandStep } from "../batch-stdin.js";
@@ -62,6 +63,7 @@ export interface BrowserRunInputFields {
 }
 
 export interface BrowserRunState {
+	allowedDomainsBySession: Map<string, AllowedDomainsPolicy>;
 	artifactManifest?: SessionArtifactManifest;
 	closedManagedSessionNames: Set<string>;
 	electronChildProcesses: Map<string, ChildProcess>;
@@ -72,16 +74,19 @@ export interface BrowserRunState {
 	managedSessionBaseName: string;
 	managedSessionCwd: string;
 	managedSessionName: string;
+	networkRoutesBySession: Map<string, NetworkRouteRecord[]>;
 	sessionPageState: SessionPageState;
 	traceOwners: Map<string, TraceOwner>;
 }
 
 export interface BrowserRunStatePatch {
+	allowedDomainsBySession?: Map<string, AllowedDomainsPolicy>;
 	artifactManifest?: SessionArtifactManifest;
 	freshSessionOrdinal?: number;
 	managedSessionActive?: boolean;
 	managedSessionCwd?: string;
 	managedSessionName?: string;
+	networkRoutesBySession?: Map<string, NetworkRouteRecord[]>;
 }
 
 export interface BrowserRunOptions {

package/extensions/agent-browser/lib/playbook.ts

@@ -23,7 +23,7 @@ export const QUICK_START_GUIDELINES = [
 	`Quick start mental model: use exactly one of args (exact agent-browser CLI args after the binary), semanticAction (a thin shorthand compiled to find argv for locator actions or select argv for native dropdowns), job (a constrained short-workflow schema compiled to batch), qa (a lightweight QA preset built on job/batch, including qa.attached for current sessions), electron (desktop Electron list/launch/status/cleanup/probe), or the experimental sourceLookup / networkSourceLookup helpers (candidates only; each compiled to batch); stdin is only for batch, eval --stdin, auth save --password-stdin, and wrapper-generated batch stdin from job, qa, sourceLookup, or networkSourceLookup, and is rejected with electron; sessionMode=fresh switches the extension-managed pi-scoped session to a fresh upstream launch when you need new launch-scoped flags (${LAUNCH_SCOPED_FLAG_LABEL}) to apply. Do not pass --json in args; the wrapper injects it.`,
 	"There is no first-class reusable named browser recipe runtime above top-level job, the qa preset, and raw batch stdin; keep recurring flows in documentation examples or those inputs (closed RQ-0068; see docs/ARCHITECTURE.md#no-reusable-recipe-layer-yet).",
 	"Common first calls (first-call recipe): { args: [\"open\", \"<url>\"] } → { args: [\"snapshot\", \"-i\"] } → { args: [\"click\", \"@eN\"] } or { args: [\"fill\", \"@eN\", \"<text>\"] } using @refs and visible labels from that snapshot, then { args: [\"snapshot\", \"-i\"] } after navigation or DOM changes. On https://example.com/ the main link label is Learn more (use exact snapshot text, not guessed link copy).",
-	"Locator-first clicks/fills and native select changes without hand-building argv: { semanticAction: { action: \"click\", locator: \"text\", value: \"Close\" } }, { semanticAction: { action: \"fill\", locator: \"label\", value: \"Email\", text: \"user@example.com\" } }, or { semanticAction: { action: \"select\", selector: \"#flavor\", value: \"chocolate\" } }; add semanticAction.session when targeting a named upstream browser session; details.compiledSemanticAction shows the semantic target, while details.effectiveArgs may show a resolved current @ref for active-session role/name click/check/uncheck actions to avoid hidden duplicate matches; selector-not-found failures may append bounded click try-*-candidate next actions or, for fill misses with current editable refs, details.richInputRecovery with focus/click actions that do not copy fill text; stale-ref failures can return retry-semantic-action-after-stale-ref for compiled find actions when retry safety is provable.",
+	"Locator-first clicks/fills and native select changes without hand-building argv: { semanticAction: { action: \"click\", locator: \"text\", value: \"Close\" } }, { semanticAction: { action: \"fill\", locator: \"label\", value: \"Email\", text: \"user@example.com\" } }, or { semanticAction: { action: \"select\", selector: \"#flavor\", value: \"chocolate\" } }; add semanticAction.session when targeting a named upstream browser session; details.compiledSemanticAction shows the semantic target, while details.effectiveArgs may show a resolved current @ref for active-session role/name click/check/fill actions to avoid hidden duplicate matches; semanticAction does not expose uncheck while upstream find ... uncheck is not runtime-supported, so use raw uncheck with a stable selector or current ref; selector-not-found failures may append bounded click try-*-candidate next actions or, for fill misses with current editable refs, details.richInputRecovery with focus/click actions that do not copy fill text; stale-ref failures can return retry-semantic-action-after-stale-ref for compiled find actions when retry safety is provable.",
 	`Common advanced calls: { args: ["batch"], stdin: "[[\"open\",\"https://example.com\"],[\"snapshot\",\"-i\"]]" }, { job: { steps: [{ action: "open", url: "https://example.com" }, { action: "assertText", text: "Example Domain" }, { action: "screenshot", path: ".dogfood/example.png" }] } }, { qa: { url: "https://example.com", expectedText: "Example Domain", screenshotPath: ".dogfood/qa-example.png" } } (example.com smoke only; elsewhere match exact visible text from snapshot -i), { electron: { action: "list", query: "code" } }, { electron: { action: "launch", appName: "Visual Studio Code", handoff: "snapshot" } }, { electron: { action: "probe" } }, { qa: { attached: true, expectedText: "Explorer" } }, { args: ["eval", "--stdin"], stdin: "document.title" }, { args: ["auth", "save", "name", "--password-stdin"], stdin: "<password from user-approved secret source>" }, { args: ["--profile", "Default", "open", "https://example.com/account"], sessionMode: "fresh" }, and { args: ["open", "--enable", "react-devtools", "https://example.com"], sessionMode: "fresh" }. For app pages with a native dropdown, job steps can include { action: "select", selector: "#flavor", value: "chocolate" } before the dependent assertion.`, 
 	"Constrained job navigation is explicit only: click (and select/submit flows that may navigate) does not prove the next page loaded; add assertUrl and/or assertText after navigation-prone steps before screenshot or later interactions. Example: { job: { steps: [{ action: \"open\", url: \"https://shop.example/checkout\" }, { action: \"fill\", selector: \"#email\", text: \"user@example.com\" }, { action: \"click\", selector: \"#continue\" }, { action: \"assertUrl\", url: \"**/shipping\" }, { action: \"assertText\", text: \"Shipping address\" }, { action: \"screenshot\", path: \".dogfood/shipping.png\" }] } }. Top-level click may add navigationSummary hints, but job never auto-inserts post-click asserts.",
 	"High-value command reference: click <selector> --new-tab opens link-like targets in a new tab; select <selector> <value...> changes native dropdown values; scroll <dir> [px] --selector <sel> targets nested scrollers; download <selector> <path> saves a file triggered by a click; get title/url/text/html/value/attr/count reads page state; screenshot [selector] [path] captures a page or element image; pdf <path> saves a PDF; tab list and tab <tab-id-or-label> inspect or recover the active tab; react tree/inspect/renders/suspense introspect React after --enable react-devtools; vitals [url] measures Core Web Vitals; pushstate <url> performs SPA navigation; tap <selector> and swipe <direction> [distance] support iOS/provider touch flows.",
@@ -48,9 +48,9 @@ export const SHARED_BROWSER_PLAYBOOK_GUIDELINES = [
 	`If you already used the implicit session and now need launch-scoped flags (${LAUNCH_SCOPED_FLAG_LABEL}), retry with top-level sessionMode set to fresh or pass an explicit --session for the new launch; never pass --session-mode inside args. After a successful unnamed fresh launch, later auto calls follow that new session.`,
 	"For React introspection, launch the page with --enable react-devtools before first navigation, then use react tree, react inspect <fiberId>, sourceLookup candidates for local UI source hints, react renders start/stop, or react suspense; sourceLookup is experimental and reports confidence/evidence instead of guaranteed DOM-to-file mappings. For failed fetches and APIs, networkSourceLookup (experimental) correlates failed network requests with initiator metadata and bounded workspace URL literals—candidates only, not definitive blame. Use vitals [url] for Core Web Vitals and hydration timing, and pushstate <url> for client-side SPA navigation.",
 	"For first-navigation setup, use open without a URL plus network route --resource-type <csv>, cookies set --curl <file>, or --init-script/--enable before navigate/opening the target page.",
-	"For stateful browser context work, prefer purpose-specific page actions before dumping browser data: use auth save --password-stdin with the tool stdin field for credentials, auth list/show/delete/remove for local auth-profile maintenance, auth login when you need the browser to fill a saved profile, state save/load for portable test state, state list/show/rename/clear/clear -a/clean for saved-state lifecycle cleanup, cookies get/set/clear and storage local|session only when the task needs those values, and expect cookie/storage/auth/state summaries to redact credential-like fields.",
+	"For stateful browser context work, prefer purpose-specific page actions before dumping browser data: use auth save --password-stdin with the tool stdin field for credentials, auth list/show/delete/remove for local auth-profile maintenance, auth login when you need the browser to fill a saved profile, state save/load for portable test state, state list/show/rename/clear/clear -a/clean for saved-state lifecycle cleanup, cookies get/set/clear and storage local|session only when the task needs those values, and expect cookie/storage/auth/state summaries to redact credential-like fields while allowing benign primitive storage values when useful for local QA.",
 	"For batch chains that touch cookies, storage, auth, or other secret-bearing commands, use details.batchSteps for per-step artifacts, categories, spill paths, and full structured errors; top-level details.data on batch is only a compact redacted step matrix (success, argv-redacted command, redacted result or scrubbed error text) built from the same presentation rules as standalone calls.",
-	"For non-core families, pass current upstream commands through the native tool directly: network route/requests/har (including request filters like --type/--method/--status), diff snapshot/screenshot/url with scoped/baseline options, trace/profiler/record, console/errors/highlight/inspect/clipboard, stream enable/disable/status, dashboard start/stop, device list for iOS simulator inventory, and chat. For compact network requests output, prefer details.nextActions for request detail, actionable failed-request networkSourceLookup, filtering, or HAR capture follow-ups instead of guessing request-id syntax. Artifact-producing commands report details.artifacts and verification state; long-running starts such as stream, dashboard, trace/profiler, and record should be paired with the matching stop/disable command when the task is done.",
+	"For non-core families, pass current upstream commands through the native tool directly: network route/requests/har (including request filters like --type/--method/--status), diff snapshot/screenshot/url with scoped/baseline options, trace/profiler/record, console/errors/highlight/inspect/clipboard, stream enable/disable/status, dashboard start/stop, device list for iOS simulator inventory, and chat. For compact network requests output, prefer details.nextActions for request detail, route-mock diagnostics, actionable failed-request networkSourceLookup, filtering, or HAR capture follow-ups instead of guessing request-id syntax. Artifact-producing commands report details.artifacts and verification state; long-running starts such as stream, dashboard, trace/profiler, and record should be paired with the matching stop/disable command when the task is done; stream enable already-enabled outcomes are treated as idempotent success with status/disable follow-ups.",
 	"For Electron desktop apps, prefer top-level electron for wrapper-owned discovery, isolated launch, status, compact probe, and cleanup: list first, treat likely-sensitive annotations as hints rather than enforcement, launch with the default snapshot handoff unless handoff: \"tabs\" is the safer diagnostic starting point, use electron.probe or snapshot -i/qa.attached for current-session state, and always cleanup the returned launchId when done. electron.launch uses an isolated temporary profile; it does not reuse the app's normal signed-in profile or attach to an already-running authenticated app. For signed-in local app state, host-launch the normal app with --remote-debugging-port when appropriate, then use raw args connect <port|url>; after connect, inspect tab list, select the stable tab id such as tab t2, then run a condition wait or snapshot -i before using refs. close commands (`close`, `quit`, or `exit`) only close the browser/CDP session; leave manually launched app shutdown, profile cleanup, and explicit artifacts to the host owner.",
 	"For provider or specialized app workflows, load version-matched upstream guidance with skills get agentcore|electron|slack|dogfood|vercel-sandbox through the native tool; add --full when you need references/templates, and use skills get --all only for broad skill audits. Provider launches such as -p ios, --provider browserbase/kernel/browseruse/browserless/agentcore, and iOS --device are upstream-owned setup paths; use sessionMode fresh when switching providers and expect external credentials or local Appium/Xcode setup to be required.",
 	"For dialogs and frames, use dialog status/accept/dismiss and frame <selector|main> through native args; when --confirm-actions produces a pending confirmation, use details.nextActions or exact confirm <id> / deny <id> calls instead of inventing ids.",
@@ -101,7 +101,7 @@ export function buildSharedBrowserPlaybookGuidelines(options: { includeWebSearch
 /** Tier A: always-on tool promptGuidelines (keep small; Tier B lives in SHARED_BROWSER_PLAYBOOK_GUIDELINES and docs). */
 export const RUNTIME_PROMPT_GUIDELINES = [
 	"Use exactly one input mode: args, semanticAction, job, qa, sourceLookup/networkSourceLookup, or electron. stdin only for batch/eval/auth or wrapper batch; electron rejects stdin. Do not pass --json in args; wrapper injects it.",
-	"Common flow: open, snapshot -i, use current @refs or semanticAction, then re-snapshot after navigation/scroll/rerender/DOM change. Batch same-snapshot fills unless they may submit/navigate/rerender. Respect explicit stop boundaries: stop before order/post/purchase/submit.",
+	"Common flow: open, snapshot -i, use current @refs or semanticAction, then re-snapshot after navigation/scroll/rerender/DOM change. Batch same-snapshot forms unless they may submit/navigate/rerender. Respect explicit stop boundaries: stop before order/post/purchase/submit.",
 	"Use top-level sessionMode=fresh for launch-scoped flags; never put --session-mode in args. For signed-in/account-specific content, use requested/configured profiles, never assume --profile Default; on profile failures, run profiles/doctor and tell the user what to configure. Use --executable-path for configured Chromium. Profile content is model-visible.",
 	"For artifacts, save the exact user path and verify details.artifactVerification/details.artifacts before claiming success. If close is blocked by details.promptGuard, save the required artifact first. record stop needs ffmpeg; close does not delete saved files; waited:timeout is not proof.",
 	"When details.nextActions is present, prefer exact payloads over prose/guessed selectors. For dense snapshots, check Omitted high-value controls/details.data.highValueControlRefIds. For dashboards, verify scroll with screenshot/snapshot; if nothing moved, target the real scroll region.",

package/extensions/agent-browser/lib/results/action-recommendations.ts

@@ -192,6 +192,21 @@ export function buildAgentBrowserNextActions(options: {
 		}
 	} else {
 		switch (options.failureCategory) {
+			case "artifact-missing":
+				for (const artifact of options.artifacts ?? []) {
+					if (isPendingRecordingArtifact(artifact) || artifact.exists !== false) continue;
+					if (artifact.kind === "download") {
+						actions.push(buildNextToolAction({
+							args: ["wait", "--download", artifact.path],
+							id: "wait-for-download",
+							reason: "The requested download artifact was not found on disk after upstream reported completion.",
+							safety: "Use a bounded wait timeout that stays below the native wrapper IPC budget.",
+						}));
+					} else {
+						actions.push(buildArtifactVerificationAction(artifact));
+					}
+				}
+				break;
 			case "confirmation-required":
 				if (options.confirmationId) {
 					actions.push(

package/extensions/agent-browser/lib/results/contracts.ts

@@ -29,6 +29,7 @@ export type AgentBrowserSuccessCategory = "artifact-saved" | "artifact-unverifie
 
 export type AgentBrowserFailureCategory =
 	| "aborted"
+	| "artifact-missing"
 	| "cleanup-failed"
 	| "confirmation-required"
 	| "download-not-verified"
@@ -161,6 +162,7 @@ export interface BatchStepPresentationDetails {
 	imagePath?: string;
 	imagePaths?: string[];
 	index: number;
+	networkRouteDiagnostics?: NetworkRouteDiagnostic[];
 	nextActions?: AgentBrowserNextAction[];
 	pageChangeSummary?: AgentBrowserPageChangeSummary;
 	resultCategory: AgentBrowserResultCategory;
@@ -193,6 +195,7 @@ export interface ToolPresentation {
 	fullOutputPaths?: string[];
 	imagePath?: string;
 	imagePaths?: string[];
+	networkRouteDiagnostics?: NetworkRouteDiagnostic[];
 	nextActions?: AgentBrowserNextAction[];
 	pageChangeSummary?: AgentBrowserPageChangeSummary;
 	resultCategory?: AgentBrowserResultCategory;
@@ -218,3 +221,17 @@ export interface NetworkFailureSummary {
 	failures: NetworkFailureClassification[];
 	totalCount: number;
 }
+
+export interface NetworkRouteRecord {
+	mode: "abort" | "body" | "handler" | "unknown";
+	pattern: string;
+}
+
+export interface NetworkRouteDiagnostic {
+	mode: NetworkRouteRecord["mode"];
+	reason: "pending-routed-request" | "cors-likely-routed-request";
+	requestId?: string;
+	requestUrl?: string;
+	routePattern: string;
+	summary: string;
+}

package/extensions/agent-browser/lib/results/network-routes.ts

@@ -0,0 +1,80 @@
+import { isRecord } from "../parsing.js";
+import { redactSensitiveText } from "../runtime.js";
+import type { NetworkRouteDiagnostic, NetworkRouteRecord } from "./contracts.js";
+import { getStringRecordField, isApiLikeNetworkRequest } from "./network.js";
+
+function getArrayField(data: Record<string, unknown>, key: string): unknown[] | undefined {
+	const value = data[key];
+	return Array.isArray(value) ? value : undefined;
+}
+
+function networkRoutePatternMatchesUrl(pattern: string, url: string): boolean {
+	if (pattern === url) return true;
+	if (pattern.includes("*")) {
+		const escaped = pattern.replace(/[.+?^${}()|[\]\\]/g, "\\$&").replace(/\*/g, ".*");
+		return new RegExp(`^${escaped}$`).test(url);
+	}
+	return pattern.length >= 4 && url.includes(pattern);
+}
+
+function getSafeRequestId(item: Record<string, unknown>): string | undefined {
+	const requestId = getStringRecordField(item, "requestId") ?? getStringRecordField(item, "id");
+	if (!requestId || redactSensitiveText(requestId) !== requestId) return undefined;
+	return requestId;
+}
+
+function getRouteDiagnosticReason(item: Record<string, unknown>): NetworkRouteDiagnostic["reason"] | undefined {
+	const statusMissing = typeof item.status !== "number";
+	const error = getStringRecordField(item, "error") ?? getStringRecordField(item, "failureText") ?? getStringRecordField(item, "errorText");
+	if (error && /(?:cors|cross-origin|preflight|access-control-allow-origin)/i.test(error)) return "cors-likely-routed-request";
+	if (statusMissing && isApiLikeNetworkRequest(item)) return "pending-routed-request";
+	return undefined;
+}
+
+export function getNetworkRouteMode(args: string[]): NetworkRouteRecord["mode"] {
+	if (args.includes("--abort")) return "abort";
+	if (args.includes("--body")) return "body";
+	return "handler";
+}
+
+export function applyNetworkRouteRecords(routes: NetworkRouteRecord[] | undefined, commandTokens: string[] | undefined, succeeded: boolean): NetworkRouteRecord[] | undefined {
+	if (!succeeded || commandTokens?.[0] !== "network") return routes;
+	const subcommand = commandTokens[1];
+	if (subcommand !== "route" && subcommand !== "unroute") return routes;
+	const existing = routes ?? [];
+	const pattern = commandTokens[2];
+	if (subcommand === "route" && pattern) return [...existing.filter((route) => route.pattern !== pattern), { mode: getNetworkRouteMode(commandTokens), pattern }];
+	if (!pattern) return undefined;
+	const next = existing.filter((route) => route.pattern !== pattern);
+	return next.length > 0 ? next : undefined;
+}
+
+export function buildNetworkRouteDiagnostics(data: unknown, routes: NetworkRouteRecord[] | undefined): NetworkRouteDiagnostic[] | undefined {
+	if (!routes || routes.length === 0 || !isRecord(data)) return undefined;
+	const requests = getArrayField(data, "requests");
+	if (!requests) return undefined;
+	const diagnostics: NetworkRouteDiagnostic[] = [];
+	for (const item of requests) {
+		if (!isRecord(item)) continue;
+		const url = getStringRecordField(item, "url");
+		if (!url) continue;
+		const reason = getRouteDiagnosticReason(item);
+		if (!reason) continue;
+		const route = routes.find((candidate) => networkRoutePatternMatchesUrl(candidate.pattern, url));
+		if (!route) continue;
+		const requestId = getSafeRequestId(item);
+		const requestUrl = redactSensitiveText(url);
+		const routePattern = redactSensitiveText(route.pattern);
+		diagnostics.push({
+			mode: route.mode,
+			reason,
+			...(requestId ? { requestId } : {}),
+			requestUrl,
+			routePattern,
+			summary: reason === "cors-likely-routed-request"
+				? `Routed request ${requestId ?? requestUrl} looks CORS/preflight-related for route ${routePattern}.`
+				: `Routed request ${requestId ?? requestUrl} is still pending/no-status for route ${routePattern}.`,
+		});
+	}
+	return diagnostics.length > 0 ? diagnostics.slice(0, 5) : undefined;
+}

package/extensions/agent-browser/lib/results/network.ts

@@ -9,12 +9,12 @@
 import { isRecord } from "../parsing.js";
 import type { NetworkFailureClassification, NetworkFailureSummary } from "./contracts.js";
 
-function getStringRecordField(value: Record<string, unknown>, key: string): string | undefined {
+export function getStringRecordField(value: Record<string, unknown>, key: string): string | undefined {
 	const field = value[key];
 	return typeof field === "string" && field.trim().length > 0 ? field.trim() : undefined;
 }
 
-function getNetworkRequestUrlPath(url: string | undefined): string | undefined {
+export function getNetworkRequestUrlPath(url: string | undefined): string | undefined {
 	if (!url) return undefined;
 	try {
 		return new URL(url).pathname;
@@ -37,6 +37,14 @@ function isBenignAssetFailure(request: Record<string, unknown>, url: string | un
 		&& (!normalizedResourceType || ["image", "img", "other"].includes(normalizedResourceType) || normalizedResourceType.startsWith("image/"));
 }
 
+export function isApiLikeNetworkRequest(request: Record<string, unknown>): boolean {
+	const method = (getStringRecordField(request, "method") ?? "GET").toUpperCase();
+	const resourceType = (getStringRecordField(request, "resourceType") ?? "").toLowerCase();
+	const mimeType = (getStringRecordField(request, "mimeType") ?? "").toLowerCase();
+	const path = getNetworkRequestUrlPath(getStringRecordField(request, "url")) ?? "";
+	return resourceType === "fetch" || resourceType === "xhr" || mimeType.includes("json") || /\/(?:api|graphql|rpc)(?:\/|$)/i.test(path) || !["GET", "HEAD"].includes(method);
+}
+
 export function classifyNetworkRequestFailure(request: Record<string, unknown>): NetworkFailureClassification | undefined {
 	if (!isFailedNetworkRequest(request)) return undefined;
 	const url = getStringRecordField(request, "url");

package/extensions/agent-browser/lib/results/presentation/artifacts.ts

@@ -340,6 +340,20 @@ export function buildArtifactVerificationSummary(
 	};
 }
 
+export function hasMissingFileArtifact(artifacts: FileArtifactMetadata[] | undefined): boolean {
+	return (artifacts ?? []).some((artifact) => !isPendingRecordingArtifact(artifact) && artifact.exists === false);
+}
+
+export function formatMissingArtifactFailureText(artifacts: FileArtifactMetadata[] | undefined): string | undefined {
+	const missingArtifacts = (artifacts ?? []).filter((artifact) => !isPendingRecordingArtifact(artifact) && artifact.exists === false);
+	if (missingArtifacts.length === 0) return undefined;
+	if (missingArtifacts.length === 1) {
+		const artifact = missingArtifacts[0];
+		return `Artifact verification failed: requested ${artifact.kind} was not found at ${artifact.absolutePath}.`;
+	}
+	return `Artifact verification failed: ${missingArtifacts.length} requested artifacts were not found on disk.`;
+}
+
 export function classifyPresentationSuccessCategory(options: {
 	artifactVerification?: ArtifactVerificationSummary;
 	artifacts?: FileArtifactMetadata[];