pi-agent-browser-native 0.2.34 → 0.2.36

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

@@ -43,6 +43,7 @@ import {
 } from "../../session-page-state.js";
 import { extractExplicitSessionName, redactInvocationArgs, redactSensitiveText, redactSensitiveValue, type OpenResultTabCorrection } from "../../runtime.js";
 import { isRecord } from "../../parsing.js";
+import { buildClickDispatchNextActions, formatClickDispatchDiagnosticText } from "./click-dispatch.js";
 import {
 	buildComboboxFocusNextActions,
 	buildElectronBroadGetTextScopeNextActions,
@@ -55,6 +56,7 @@ import {
 	formatArtifactCleanupGuidanceText,
 	formatComboboxFocusDiagnosticText,
 	formatElectronBroadGetTextScopeText,
+	formatEvalResultWarningText,
 	formatEvalStdinHintText,
 	formatFillVerificationText,
 	formatOverlayBlockerText,
@@ -68,6 +70,7 @@ import {
 	buildElectronLifecycleNextActions,
 	buildElectronMismatchNextActions,
 	buildElectronRefFreshnessNextActions,
+	buildManagedSessionFreshFailureNextActions,
 	buildManagedSessionOutcome,
 	buildSessionDetailFields,
 	formatElectronPostCommandHealthText,
@@ -212,7 +215,7 @@ export function buildElectronHostFailureResult(options: {
 	return { content: [{ type: "text", text: redactSensitiveText(text) }], details: redactToolDetails(details, []), isError: true };
 }
 
-function formatElectronTargetLines(targets: ElectronCdpTarget[], limit = 8): string[] {
+export function formatElectronTargetLines(targets: ElectronCdpTarget[], limit = 8): string[] {
 	const shownTargets = targets.slice(0, limit);
 	const lines = shownTargets.map((target) => {
 		const label = [target.type, target.title].filter(Boolean).join(" ") || target.id || "target";
@@ -319,8 +322,10 @@ function buildResultNextActions(options: FinalResultInput): AgentBrowserNextActi
 	if (options.selectorTextVisibilityDiagnostics.length > 0) nextActionCollector.append(buildSelectorTextVisibilityNextActions({ diagnostics: options.selectorTextVisibilityDiagnostics, sessionName: options.executionPlan.sessionName }));
 	if (options.electronBroadGetTextScopeDiagnostics.length > 0) nextActionCollector.append(buildElectronBroadGetTextScopeNextActions({ diagnostics: options.electronBroadGetTextScopeDiagnostics, sessionName: options.executionPlan.sessionName }));
 	if (options.sourceLookup?.electronContext) nextActionCollector.appendUnique(buildSourceLookupElectronNextActions(options.sourceLookup));
+	if (options.clickDispatchDiagnostic) nextActionCollector.append(buildClickDispatchNextActions({ commandTokens: options.commandTokens, sessionName: options.executionPlan.sessionName }));
 	if (options.scrollNoopDiagnostic) nextActionCollector.append(buildScrollNoopNextActions(options.executionPlan.sessionName));
 	if (options.comboboxFocusDiagnostic) nextActionCollector.append(buildComboboxFocusNextActions(options.executionPlan.sessionName));
+	if (options.managedSessionOutcome) nextActionCollector.appendUnique(buildManagedSessionFreshFailureNextActions(options.managedSessionOutcome));
 	if (options.categoryDetails.failureCategory === "stale-ref" && options.redactedCompiledSemanticAction && isCompiledSemanticActionFindCommand(options.compiledSemanticAction)) nextActionCollector.append([{ id: "retry-semantic-action-after-stale-ref", params: { args: options.redactedCompiledSemanticAction.args }, reason: "Retry the same semantic target via its compiled find command after the upstream stale-ref failure proves the prior action did not execute.", safety: "Use only for the same intended target; direct stale @refs still require a fresh snapshot or stable locator before retrying.", tool: "agent_browser" as const }]);
 	if (options.electronLaunchRecord) nextActionCollector.append(buildAgentBrowserNextActions({ electron: { launchId: options.electronLaunchRecord.launchId, sessionName: options.electronLaunchRecord.sessionName, status: options.electronLaunchRecord.cleanupState }, failureCategory: options.categoryDetails.failureCategory, resultCategory: options.categoryDetails.resultCategory, successCategory: options.categoryDetails.successCategory }));
 	return nextActionCollector.toArray();
@@ -369,6 +374,7 @@ function buildAgentBrowserResultDetails(options: FinalResultInput, nextActions:
 		imagePaths: options.presentation.imagePaths,
 		nextActions,
 		pageChangeSummary,
+		clickDispatch: options.clickDispatchDiagnostic,
 		overlayBlockers: options.overlayBlockerDiagnostic,
 		fillVerification: options.fillVerificationDiagnostic,
 		visibleRefFallback: publicVisibleRefFallbackDiagnostic,
@@ -383,6 +389,7 @@ function buildAgentBrowserResultDetails(options: FinalResultInput, nextActions:
 		selectorTextVisibility: options.selectorTextVisibilityDiagnostics[0],
 		selectorTextVisibilityAll: options.selectorTextVisibilityDiagnostics.length > 1 ? options.selectorTextVisibilityDiagnostics : undefined,
 		evalStdinHint: options.evalStdinHint,
+		evalResultWarning: options.evalResultWarning,
 		timeoutPartialProgress: options.timeoutPartialProgress,
 		parseError: options.plainTextInspection ? undefined : options.parseError,
 		savedFile: options.presentation.savedFile,
@@ -411,6 +418,7 @@ export function buildFinalAgentBrowserToolResult(options: FinalResultInput): Age
 	const visibleRefFallbackText = formatVisibleRefFallbackText(options.visibleRefFallbackDiagnostic);
 	const richInputRecoveryText = formatRichInputRecoveryText(options.richInputRecoveryDiagnostic);
 	const semanticActionCandidateText = nextActions ? formatSemanticActionCandidateText(nextActions) : undefined;
+	const clickDispatchText = options.clickDispatchDiagnostic ? formatClickDispatchDiagnosticText(options.clickDispatchDiagnostic) : undefined;
 	const overlayBlockerText = options.overlayBlockerDiagnostic ? formatOverlayBlockerText(options.overlayBlockerDiagnostic) : undefined;
 	const fillVerificationText = formatFillVerificationText(options.fillVerificationDiagnostic);
 	const electronRefFreshnessText = formatElectronRefFreshnessText(options.electronRefFreshnessDiagnostic);
@@ -420,10 +428,11 @@ export function buildFinalAgentBrowserToolResult(options: FinalResultInput): Age
 	const comboboxFocusDiagnosticText = formatComboboxFocusDiagnosticText(options.comboboxFocusDiagnostic);
 	const recordingDependencyWarningText = formatRecordingDependencyWarningText(options.recordingDependencyWarning);
 	const evalStdinHintText = formatEvalStdinHintText(options.evalStdinHint);
+	const evalResultWarningText = formatEvalResultWarningText(options.evalResultWarning);
 	const artifactCleanupText = formatArtifactCleanupGuidanceText(options.artifactCleanup);
 	const timeoutPartialProgressText = options.timeoutPartialProgress ? formatTimeoutPartialProgressText(options.timeoutPartialProgress) : undefined;
 	const managedSessionOutcomeText = formatManagedSessionOutcomeText(options.managedSessionOutcome);
-	const rawAppendedDiagnosticText = [visibleRefFallbackText, richInputRecoveryText, semanticActionCandidateText, overlayBlockerText, fillVerificationText, electronRefFreshnessText, selectorTextVisibilityText, electronBroadGetTextScopeText, scrollNoopDiagnosticText, comboboxFocusDiagnosticText, recordingDependencyWarningText, evalStdinHintText, artifactCleanupText, timeoutPartialProgressText, managedSessionOutcomeText].filter((item): item is string => item !== undefined).join("\n\n");
+	const rawAppendedDiagnosticText = [visibleRefFallbackText, richInputRecoveryText, semanticActionCandidateText, clickDispatchText, overlayBlockerText, fillVerificationText, electronRefFreshnessText, selectorTextVisibilityText, electronBroadGetTextScopeText, scrollNoopDiagnosticText, comboboxFocusDiagnosticText, recordingDependencyWarningText, evalStdinHintText, evalResultWarningText, artifactCleanupText, timeoutPartialProgressText, managedSessionOutcomeText].filter((item): item is string => item !== undefined).join("\n\n");
 	const appendedDiagnosticText = redactSensitiveText(redactExactSensitiveText(rawAppendedDiagnosticText, options.exactSensitiveValues));
 	const shouldAppendDiagnosticText = appendedDiagnosticText.length > 0 && (!options.userRequestedJson || options.plainTextInspection);
 	let content = shouldAppendDiagnosticText && options.redactedContent[0]?.type === "text" ? [{ ...options.redactedContent[0], text: `${options.redactedContent[0].text}\n\n${appendedDiagnosticText}` }, ...options.redactedContent.slice(1)] : options.redactedContent;
@@ -439,6 +448,7 @@ export async function buildMissingBinaryFailureResult(options: { compatibilityWo
 	const errorText = buildMissingBinaryMessage();
 	const managedSessionOutcome = buildManagedSessionOutcome({ activeAfter: options.managedSessionActive, activeBefore: options.managedSessionActive, attemptedSessionName: options.executionPlan.managedSessionName, command: options.executionPlan.commandInfo.command, currentSessionName: options.managedSessionName, previousSessionName: options.managedSessionName, sessionMode: options.sessionMode, succeeded: false });
 	const managedSessionOutcomeText = formatManagedSessionOutcomeText(managedSessionOutcome);
+	const managedSessionRecoveryNextActions = buildManagedSessionFreshFailureNextActions(managedSessionOutcome);
 	let missingBinaryElectronCleanup: ElectronCleanupResult | undefined;
 	let missingBinaryElectronRecord: ElectronLaunchRecord | undefined;
 	if (options.electronLaunch) {
@@ -446,5 +456,5 @@ export async function buildMissingBinaryFailureResult(options: { compatibilityWo
 		missingBinaryElectronRecord = missingBinaryElectronCleanup.record;
 	}
 	const textParts = [errorText, managedSessionOutcomeText, missingBinaryElectronCleanup ? `Electron cleanup after failed attach: ${missingBinaryElectronCleanup.summary}` : undefined].filter((part): part is string => part !== undefined && part.length > 0);
-	return { content: [{ type: "text", text: textParts.join("\n\n") }], details: { args: options.redactedArgs, compatibilityWorkaround: options.compatibilityWorkaround, effectiveArgs: options.redactedProcessArgs, electron: missingBinaryElectronRecord ? { action: "launch" as const, cleanup: missingBinaryElectronCleanup, launch: missingBinaryElectronRecord, status: "failed" as const, targets: options.electronLaunch?.targets, version: options.electronLaunch?.version } : undefined, managedSessionOutcome, sessionMode: options.sessionMode, sessionTabCorrection: options.sessionTabCorrection, ...buildAgentBrowserResultCategoryDetails({ args: options.redactedProcessArgs, command: options.executionPlan.commandInfo.command, errorText, failureCategory: "missing-binary", spawnError: options.processResult.spawnError.message, succeeded: false }), spawnError: options.processResult.spawnError.message }, isError: true };
+	return { content: [{ type: "text", text: textParts.join("\n\n") }], details: { args: options.redactedArgs, compatibilityWorkaround: options.compatibilityWorkaround, effectiveArgs: options.redactedProcessArgs, electron: missingBinaryElectronRecord ? { action: "launch" as const, cleanup: missingBinaryElectronCleanup, launch: missingBinaryElectronRecord, status: "failed" as const, targets: options.electronLaunch?.targets, version: options.electronLaunch?.version } : undefined, managedSessionOutcome, nextActions: managedSessionRecoveryNextActions.length > 0 ? managedSessionRecoveryNextActions : undefined, sessionMode: options.sessionMode, sessionTabCorrection: options.sessionTabCorrection, ...buildAgentBrowserResultCategoryDetails({ args: options.redactedProcessArgs, command: options.executionPlan.commandInfo.command, errorText, failureCategory: "missing-binary", spawnError: options.processResult.spawnError.message, succeeded: false }), spawnError: options.processResult.spawnError.message }, isError: true };
 }

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

@@ -1,11 +1,13 @@
 import { runAgentBrowserProcess } from "../../process.js";
+import { cleanupClickDispatchProbe } from "./click-dispatch.js";
 import { applyBrowserRunStatePatch } from "./session-state.js";
 import { buildMissingBinaryFailureResult } from "./final-result.js";
 import { prepareBrowserRun } from "./prepare.js";
 import { processBrowserOutput } from "./process-output.js";
 import type { AgentBrowserToolResult, BrowserRunOptions } from "./types.js";
 
-export type { BrowserRunOptions, BrowserRunState } from "./types.js";
+export { closeManagedSession } from "./session-state.js";
+export type { AgentBrowserToolResult, BrowserRunOptions, BrowserRunState, TraceOwner } from "./types.js";
 
 export async function runAgentBrowserTool(options: BrowserRunOptions): Promise<AgentBrowserToolResult> {
 	const preparedResult = await prepareBrowserRun(options);
@@ -15,32 +17,36 @@ export async function runAgentBrowserTool(options: BrowserRunOptions): Promise<A
 	}
 
 	const { prepared } = preparedResult;
-	const processResult = await runAgentBrowserProcess({
-		args: prepared.processArgs,
-		cwd: options.cwd,
-		env: prepared.executionPlan.managedSessionName ? { AGENT_BROWSER_IDLE_TIMEOUT_MS: options.implicitSessionIdleTimeoutMs } : undefined,
-		signal: options.signal,
-		stdin: prepared.processStdin,
-	});
+	try {
+		const processResult = await runAgentBrowserProcess({
+			args: prepared.processArgs,
+			cwd: options.cwd,
+			env: prepared.executionPlan.managedSessionName ? { AGENT_BROWSER_IDLE_TIMEOUT_MS: options.implicitSessionIdleTimeoutMs } : undefined,
+			signal: options.signal,
+			stdin: prepared.processStdin,
+		});
 
-	const missingBinaryResult = await buildMissingBinaryFailureResult({
-		compatibilityWorkaround: prepared.compatibilityWorkaround,
-		electronLaunch: prepared.electronLaunch,
-		executionPlan: prepared.executionPlan,
-		implicitSessionCloseTimeoutMs: options.implicitSessionCloseTimeoutMs,
-		managedSessionActive: options.state.managedSessionActive,
-		managedSessionName: options.state.managedSessionName,
-		processResult,
-		redactedArgs: prepared.redactedArgs,
-		redactedProcessArgs: prepared.redactedProcessArgs,
-		sessionMode: prepared.sessionMode,
-		sessionTabCorrection: prepared.sessionTabCorrection,
-	});
-	if (missingBinaryResult) {
-		return missingBinaryResult;
-	}
+		const missingBinaryResult = await buildMissingBinaryFailureResult({
+			compatibilityWorkaround: prepared.compatibilityWorkaround,
+			electronLaunch: prepared.electronLaunch,
+			executionPlan: prepared.executionPlan,
+			implicitSessionCloseTimeoutMs: options.implicitSessionCloseTimeoutMs,
+			managedSessionActive: options.state.managedSessionActive,
+			managedSessionName: options.state.managedSessionName,
+			processResult,
+			redactedArgs: prepared.redactedArgs,
+			redactedProcessArgs: prepared.redactedProcessArgs,
+			sessionMode: prepared.sessionMode,
+			sessionTabCorrection: prepared.sessionTabCorrection,
+		});
+		if (missingBinaryResult) {
+			return missingBinaryResult;
+		}
 
-	const output = await processBrowserOutput({ ...options, prepared, processResult });
-	applyBrowserRunStatePatch(options.state, output.statePatch);
-	return output.result;
+		const output = await processBrowserOutput({ ...options, prepared, processResult });
+		applyBrowserRunStatePatch(options.state, output.statePatch);
+		return output.result;
+	} finally {
+		await cleanupClickDispatchProbe({ cwd: options.cwd, probe: prepared.clickDispatchProbe, sessionName: prepared.executionPlan.sessionName });
+	}
 }

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

@@ -26,8 +26,11 @@ import {
 	runSessionCommandData,
 	shouldPinSessionTabForCommand,
 } from "./session-state.js";
+import { parseBatchStdinJsonArray, parseValidBatchStepEntries } from "../batch-stdin.js";
 import { buildElectronHostFailureResult, getElectronLaunchFailureCategory, redactRecoveryHint } from "./final-result.js";
+import { prepareClickDispatchProbe } from "./click-dispatch.js";
 import { collectScrollPositionSnapshot, validateQaAttachedPrecondition } from "./diagnostics.js";
+import { findRequestedArtifactCloseViolation, findStopBoundaryViolation } from "./prompt-guards.js";
 import type {
 	BrowserRunInputFields,
 	BrowserRunOptions,
@@ -141,19 +144,14 @@ async function prepareBatchScreenshotPaths(args: string[], stdin: string | undef
 	if (commandTokens[0] !== "batch" || stdin === undefined) {
 		return undefined;
 	}
-	let steps: unknown;
-	try {
-		steps = JSON.parse(stdin);
-	} catch {
-		return undefined;
-	}
-	if (!Array.isArray(steps)) {
+	const parsed = parseBatchStdinJsonArray(stdin);
+	if (parsed.error || parsed.steps === undefined) {
 		return undefined;
 	}
 
 	let changed = false;
 	const batchScreenshotPathRequests: Array<ScreenshotPathRequest | undefined> = [];
-	const preparedSteps = await Promise.all(steps.map(async (step, index) => {
+	const preparedSteps = await Promise.all(parsed.steps.map(async (step, index) => {
 		if (!Array.isArray(step) || !step.every((item) => typeof item === "string") || step[0] !== "screenshot") {
 			return step;
 		}
@@ -282,20 +280,7 @@ export function validateWaitIpcTimeoutContract(commandTokens: string[], stdin: s
 	if (commandTokens[0] !== "batch" || stdin === undefined) {
 		return undefined;
 	}
-	let steps: unknown;
-	try {
-		steps = JSON.parse(stdin);
-	} catch {
-		return undefined;
-	}
-	if (!Array.isArray(steps)) {
-		return undefined;
-	}
-	for (let index = 0; index < steps.length; index += 1) {
-		const step = steps[index];
-		if (!Array.isArray(step) || !step.every((item) => typeof item === "string")) {
-			continue;
-		}
+	for (const { index, step } of parseValidBatchStepEntries(stdin)) {
 		const waitTimeout = findWaitTimeoutMs(step);
 		if (waitTimeout && waitTimeout.timeoutMs > SAFE_AGENT_BROWSER_OPERATION_TIMEOUT_MS) {
 			return buildIpcUnsafeWaitError(waitTimeout.source, waitTimeout.timeoutMs, index);
@@ -528,6 +513,43 @@ export async function prepareBrowserRun(options: BrowserRunOptions): Promise<Pre
 	const resolvedSemanticActionRefSnapshot: SessionRefSnapshot | undefined = semanticActionVisibleRefResolution?.snapshot
 		? { ...semanticActionVisibleRefResolution.snapshot, target: semanticActionVisibleRefResolution.snapshot.target ?? priorSessionTabTarget }
 		: undefined;
+	const promptRefSnapshot = resolvedSemanticActionRefSnapshot ?? priorRefSnapshotState;
+	const stopBoundaryViolation = findStopBoundaryViolation({ commandTokens, promptPolicy: options.promptPolicy, refSnapshot: promptRefSnapshot, stdin: runtimeToolStdin });
+	if (stopBoundaryViolation) {
+		return { kind: "early-result", statePatch, result: {
+			content: [{ type: "text", text: stopBoundaryViolation.message }],
+			details: {
+				args: redactedArgs,
+				command: executionPlan.commandInfo.command,
+				compatibilityWorkaround,
+				effectiveArgs: redactedEffectiveArgs,
+				promptGuard: stopBoundaryViolation,
+				sessionMode,
+				...buildAgentBrowserResultCategoryDetails({ args: redactedEffectiveArgs, command: executionPlan.commandInfo.command, errorText: stopBoundaryViolation.message, failureCategory: "policy-blocked", succeeded: false, validationError: stopBoundaryViolation.message }),
+				validationError: stopBoundaryViolation.message,
+				...buildSessionDetailFields(executionPlan.sessionName, executionPlan.usedImplicitSession),
+			},
+			isError: true,
+		} };
+	}
+	const requestedArtifactCloseViolation = await findRequestedArtifactCloseViolation({ artifactManifest: state.artifactManifest, command: executionPlan.commandInfo.command, cwd, promptPolicy: options.promptPolicy });
+	if (requestedArtifactCloseViolation) {
+		return { kind: "early-result", statePatch, result: {
+			content: [{ type: "text", text: requestedArtifactCloseViolation.message }],
+			details: {
+				args: redactedArgs,
+				command: executionPlan.commandInfo.command,
+				compatibilityWorkaround,
+				effectiveArgs: redactedEffectiveArgs,
+				promptGuard: requestedArtifactCloseViolation,
+				sessionMode,
+				...buildAgentBrowserResultCategoryDetails({ args: redactedEffectiveArgs, command: executionPlan.commandInfo.command, errorText: requestedArtifactCloseViolation.message, failureCategory: "policy-blocked", succeeded: false, validationError: requestedArtifactCloseViolation.message }),
+				validationError: requestedArtifactCloseViolation.message,
+				...buildSessionDetailFields(executionPlan.sessionName, executionPlan.usedImplicitSession),
+			},
+			isError: true,
+		} };
+	}
 	const staleRefPreflight = buildStaleRefPreflight({
 		commandTokens,
 		currentTarget: priorSessionTabTarget,
@@ -676,6 +698,9 @@ export async function prepareBrowserRun(options: BrowserRunOptions): Promise<Pre
 			}
 		}
 	}
+	const clickDispatchProbe = pinnedBatchUnwrapMode === undefined && compiledElectron === undefined
+		? await prepareClickDispatchProbe({ commandTokens, cwd, sessionName: executionPlan.sessionName, signal })
+		: undefined;
 	const redactedProcessArgs = redactInvocationArgs(processArgs);
 	const shouldProbeScrollNoop = executionPlan.commandInfo.command === "scroll" && executionPlan.startupScopedFlags.length === 0;
 	const scrollPositionBefore = shouldProbeScrollNoop
@@ -702,6 +727,7 @@ export async function prepareBrowserRun(options: BrowserRunOptions): Promise<Pre
 		compiledSemanticAction,
 		compiledSourceLookup,
 		compatibilityWorkaround,
+		clickDispatchProbe,
 		electronLaunch,
 		exactSensitiveValues,
 		executionPlan,

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

@@ -1,5 +1,6 @@
 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 {
@@ -38,7 +39,7 @@ import {
 import type { PersistentSessionArtifactEviction, PersistentSessionArtifactStore } from "../../temp.js";
 import { writePersistentSessionArtifactFile, writeSecureTempFile } from "../../temp.js";
 import { isRecord } from "../../parsing.js";
-import { hasLaunchScopedTabCorrectionFlag, resolveManagedSessionState } from "../../runtime.js";
+import { createFreshSessionName, hasLaunchScopedTabCorrectionFlag, resolveManagedSessionState } from "../../runtime.js";
 import {
 	applyOpenResultTabCorrection,
 	buildAboutBlankRecoveryHint,
@@ -50,6 +51,7 @@ import {
 	closeManagedSession,
 	collectOpenResultTabCorrection,
 	collectSessionTabSelection,
+	extractNavigationSummaryFromData,
 	extractStringResultField,
 	findElectronLaunchRecordForSession,
 	formatElectronPostCommandHealthText,
@@ -62,6 +64,7 @@ import {
 	unwrapPinnedSessionBatchEnvelope,
 	updateTraceOwnerState,
 } from "./session-state.js";
+import { collectClickDispatchDiagnostic } from "./click-dispatch.js";
 import {
 	buildScrollNoopDiagnostic,
 	collectComboboxFocusDiagnostic,
@@ -77,6 +80,7 @@ import {
 	collectTimeoutPartialProgress,
 	formatQaAttachedTargetText,
 	getArtifactCleanupGuidance,
+	getEvalResultWarning,
 	getEvalStdinHint,
 	getSourceLookupElectronContext,
 	sleepMs,
@@ -177,6 +181,7 @@ export async function processBrowserOutput(input: ProcessBrowserOutputInput): Pr
 	const { prepared, processResult } = input;
 	const { electronChildProcesses, electronLaunchRecords, sessionPageState, traceOwners } = state;
 	let artifactManifest = state.artifactManifest;
+	let freshSessionOrdinal = state.freshSessionOrdinal;
 	let managedSessionActive = state.managedSessionActive;
 	let managedSessionCwd = state.managedSessionCwd;
 	let managedSessionName = state.managedSessionName;
@@ -208,6 +213,15 @@ export async function processBrowserOutput(input: ProcessBrowserOutputInput): Pr
 		const inspectionText = plainTextInspection ? processResult.stdout.trim() : undefined;
 		updateTraceOwnerState({ command: prepared.executionPlan.commandInfo.command, sessionName: prepared.executionPlan.sessionName, subcommand: prepared.executionPlan.commandInfo.subcommand, succeeded, traceOwners });
 
+		let clickDispatchDiagnostic: Awaited<ReturnType<typeof collectClickDispatchDiagnostic>>;
+		if (succeeded && prepared.clickDispatchProbe) {
+			clickDispatchDiagnostic = await collectClickDispatchDiagnostic({ cwd, probe: prepared.clickDispatchProbe, sessionName: prepared.executionPlan.sessionName, signal });
+			if (clickDispatchDiagnostic) {
+				succeeded = false;
+				presentationEnvelope = { ...(presentationEnvelope ?? {}), error: clickDispatchDiagnostic.summary, success: false };
+			}
+		}
+
 		if (
 			succeeded &&
 			!navigationSummary &&
@@ -220,7 +234,7 @@ export async function processBrowserOutput(input: ProcessBrowserOutputInput): Pr
 		let overlayBlockerDiagnostic: Awaited<ReturnType<typeof collectOverlayBlockerDiagnostic>>;
 
 		let openResultTabCorrection: Awaited<ReturnType<typeof collectOpenResultTabCorrection>>;
-		if (succeeded && prepared.executionPlan.sessionName && hasLaunchScopedTabCorrectionFlag(prepared.runtimeToolArgs) && ["goto", "navigate", "open"].includes(prepared.executionPlan.commandInfo.command ?? "")) {
+		if (succeeded && prepared.executionPlan.sessionName && hasLaunchScopedTabCorrectionFlag(prepared.runtimeToolArgs) && isOpenNavigationCommand(prepared.executionPlan.commandInfo.command)) {
 			const targetTitle = extractStringResultField(presentationEnvelope?.data, "title");
 			const targetUrl = extractStringResultField(presentationEnvelope?.data, "url");
 			const plannedTabCorrection = await collectOpenResultTabCorrection({ cwd, sessionName: prepared.executionPlan.sessionName, signal, targetTitle, targetUrl });
@@ -275,7 +289,7 @@ export async function processBrowserOutput(input: ProcessBrowserOutputInput): Pr
 			fillVerificationDiagnostic = await collectFillVerificationDiagnostic({ commandTokens: prepared.commandTokens, cwd, sessionName: prepared.executionPlan.sessionName, signal });
 			electronRefFreshnessDiagnostic = buildElectronRefFreshnessDiagnostic({ command: prepared.executionPlan.commandInfo.command, commandTokens: prepared.commandTokens, record: electronRecordForCommand, sessionName: prepared.executionPlan.sessionName, stdin: prepared.runtimeToolStdin });
 		}
-		if (succeeded && !sessionTabCorrection && !aboutBlankSessionMismatch && !electronRecordForCommand) overlayBlockerDiagnostic = await collectOverlayBlockerDiagnostic({ command: prepared.executionPlan.commandInfo.command, cwd, data: presentationEnvelope?.data, navigationSummary, priorTarget: prepared.priorSessionTabTarget, sessionName: prepared.executionPlan.sessionName, signal });
+		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 });
@@ -287,8 +301,10 @@ export async function processBrowserOutput(input: ProcessBrowserOutputInput): Pr
 		let currentRefSnapshotInvalidation: SessionRefSnapshotInvalidation | undefined;
 		const batchRefSnapshotState = prepared.executionPlan.commandInfo.command === "batch" ? extractLatestRefSnapshotStateFromBatchResults(presentationEnvelope?.data) : undefined;
 		if (prepared.executionPlan.sessionName) {
-			if (prepared.executionPlan.commandInfo.command === "close" && succeeded) sessionPageState.clearSession(prepared.executionPlan.sessionName);
-			else if (currentSessionTabTarget) {
+			if (isCloseCommand(prepared.executionPlan.commandInfo.command) && succeeded) {
+				sessionPageState.clearSession(prepared.executionPlan.sessionName);
+				state.closedManagedSessionNames.add(prepared.executionPlan.sessionName);
+			} else if (currentSessionTabTarget) {
 				const tabUpdate = sessionPageState.applyTabTarget({ sessionName: prepared.executionPlan.sessionName, target: currentSessionTabTarget, update: sessionPageStateUpdate });
 				if (!tabUpdate.applied && succeeded) sessionPageState.markPinning(prepared.executionPlan.sessionName, "drift");
 			}
@@ -307,11 +323,19 @@ export async function processBrowserOutput(input: ProcessBrowserOutputInput): Pr
 		const priorManagedSessionActive = managedSessionActive;
 		const priorManagedSessionCwd = managedSessionCwd;
 		const priorManagedSessionName = managedSessionName;
-		const managedSessionState = resolveManagedSessionState({ command: prepared.executionPlan.commandInfo.command, managedSessionName: prepared.executionPlan.managedSessionName, priorActive: priorManagedSessionActive, priorSessionName: priorManagedSessionName, succeeded });
+		const commandClosesSession = isCloseCommand(prepared.executionPlan.commandInfo.command);
+		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 replacedManagedSessionName = managedSessionState.replacedSessionName;
 		managedSessionActive = managedSessionState.active;
 		managedSessionName = managedSessionState.sessionName;
-		let managedSessionOutcome = buildManagedSessionOutcome({ activeAfter: managedSessionActive, activeBefore: priorManagedSessionActive, attemptedSessionName: prepared.executionPlan.managedSessionName, command: prepared.executionPlan.commandInfo.command, currentSessionName: managedSessionName, previousSessionName: priorManagedSessionName, replacedSessionName: replacedManagedSessionName, sessionMode: prepared.sessionMode, succeeded });
+		if (commandClosesSession && succeeded && managedCloseSessionName === priorManagedSessionName && !managedSessionActive) {
+			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 });
 		if (prepared.executionPlan.managedSessionName && succeeded) managedSessionCwd = cwd;
 		if (prepared.executionPlan.sessionName && succeeded) {
 			if (openResultTabCorrection || sessionTabCorrection || aboutBlankSessionMismatch?.recoveryApplied) sessionPageState.markPinning(prepared.executionPlan.sessionName, "drift");
@@ -319,7 +343,8 @@ export async function processBrowserOutput(input: ProcessBrowserOutputInput): Pr
 		}
 		if (replacedManagedSessionName) {
 			sessionPageState.clearSession(replacedManagedSessionName);
-			await closeManagedSession({ cwd: priorManagedSessionCwd, sessionName: replacedManagedSessionName, timeoutMs: implicitSessionCloseTimeoutMs });
+			const replacedCloseError = await closeManagedSession({ cwd: priorManagedSessionCwd, sessionName: replacedManagedSessionName, timeoutMs: implicitSessionCloseTimeoutMs });
+			if (!replacedCloseError) state.closedManagedSessionNames.add(replacedManagedSessionName);
 		}
 
 		let electronLaunchRecord: ElectronLaunchRecord | undefined;
@@ -396,7 +421,11 @@ export async function processBrowserOutput(input: ProcessBrowserOutputInput): Pr
 		if (!skipAttachedTargetBanner && qaAttachedTargetText && presentation.content[0]?.type === "text") presentation.content[0] = { ...presentation.content[0], text: `${qaAttachedTargetText}\n\n${presentation.content[0].text}` };
 		else if (!skipAttachedTargetBanner && qaAttachedTargetText) presentation.content.unshift({ type: "text", text: qaAttachedTargetText });
 		if (managedSessionOutcome && managedSessionOutcome.succeeded !== succeeded) managedSessionOutcome = { ...managedSessionOutcome, succeeded };
+		const evalNavigationSummary = navigationSummary ?? extractNavigationSummaryFromData(presentationEnvelope?.data);
+		const evalSessionTabUrl = prepared.executionPlan.sessionName ? sessionPageState.get(prepared.executionPlan.sessionName).tabTarget?.url : undefined;
+		const evalPageUrl = evalNavigationSummary?.url ?? currentSessionTabTarget?.url ?? prepared.priorSessionTabTarget?.url ?? evalSessionTabUrl;
 		const evalStdinHint = getEvalStdinHint({ command: prepared.executionPlan.commandInfo.command, data: presentationEnvelope?.data, stdin: prepared.runtimeToolStdin });
+		const evalResultWarning = getEvalResultWarning({ command: prepared.executionPlan.commandInfo.command, data: presentationEnvelope?.data, navigationSummary: evalNavigationSummary, pageUrl: evalPageUrl, stdin: prepared.runtimeToolStdin });
 		const resultArtifactManifest = presentation.artifactManifest ?? artifactManifest;
 		const artifactCleanup = await getArtifactCleanupGuidance({ command: prepared.executionPlan.commandInfo.command, cwd, manifest: resultArtifactManifest, succeeded });
 		const warningText = electronPostCommandHealth ? formatElectronPostCommandHealthText(electronPostCommandHealth) : electronSessionMismatch ? formatElectronSessionMismatchText(electronSessionMismatch) : aboutBlankSessionMismatch ? buildAboutBlankWarning(aboutBlankSessionMismatch) : undefined;
@@ -404,8 +433,8 @@ export async function processBrowserOutput(input: ProcessBrowserOutputInput): Pr
 		const finalRecoveryState = await prepareFinalResultRecoveryState({ aboutBlankSessionMismatch, batchRefSnapshotState, commandTokens: prepared.commandTokens, compiledSemanticAction: prepared.compiledSemanticAction, currentRefSnapshot, currentRefSnapshotInvalidation, currentSessionTabTarget, cwd, electronPostCommandHealth, errorText, executionPlan: prepared.executionPlan, parseError, plainTextInspection, presentation, processResult, redactedProcessArgs: prepared.redactedProcessArgs, runtimeToolArgs: prepared.runtimeToolArgs, sessionPageState, sessionPageStateUpdate, sessionTabCorrection, signal, succeeded });
 		currentRefSnapshot = finalRecoveryState.currentRefSnapshot;
 		currentRefSnapshotInvalidation = finalRecoveryState.currentRefSnapshotInvalidation;
-		const result = buildFinalAgentBrowserToolResult({ aboutBlankSessionMismatch, artifactCleanup, categoryDetails: finalRecoveryState.categoryDetails, 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, 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, managedSessionActive, managedSessionCwd, managedSessionName };
+		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 };
 		return { result, statePatch };
 	} finally {
 		if (processResult.stdoutSpillPath) await rm(processResult.stdoutSpillPath, { force: true }).catch(() => undefined);

package/extensions/agent-browser/lib/orchestration/browser-run/prompt-guards.ts

@@ -0,0 +1,93 @@
+import { isAbsolute, resolve } from "node:path";
+
+import { isCloseCommand } from "../../command-taxonomy.js";
+import { executableExistsOnPath } from "../../executable-path.js";
+import type { SessionArtifactManifest } from "../../results/contracts.js";
+import type { PromptPolicy, PromptRequestedArtifact } from "../../prompt-policy.js";
+import type { SessionRefSnapshot } from "../../session-page-state.js";
+import { findBlockedFinalizingAction, STOP_BOUNDARY_GUARD_SCOPE, type BrowserFinalizingAction } from "./browser-action-model.js";
+
+export interface StopBoundaryViolation {
+	action: BrowserFinalizingAction;
+	command: string[];
+	message: string;
+	reason: "explicit-user-stop-boundary";
+	stepIndex?: number;
+	target?: string;
+}
+
+export interface RequestedArtifactCloseViolation {
+	message: string;
+	missingArtifacts: PromptRequestedArtifact[];
+	reason: "requested-artifacts-missing-before-close";
+}
+
+function formatStopBoundaryActionPhrase(action: BrowserFinalizingAction): string {
+	if (action.kind === "keyboard-submit") return "keyboard submit (Enter/Return)";
+	return "click-like action";
+}
+
+export function findStopBoundaryViolation(options: { commandTokens: string[]; promptPolicy: PromptPolicy; refSnapshot?: SessionRefSnapshot; stdin?: string }): StopBoundaryViolation | undefined {
+	if (!options.promptPolicy.stopBoundary) return undefined;
+	const blocked = findBlockedFinalizingAction({
+		commandTokens: options.commandTokens,
+		refSnapshot: options.refSnapshot,
+		stdin: options.stdin,
+	});
+	if (!blocked) return undefined;
+	const target = blocked.targetLabel;
+	const actionPhrase = formatStopBoundaryActionPhrase(blocked);
+	const scopeNote = `Best-effort guard scope covers ${STOP_BOUNDARY_GUARD_SCOPE.covered.join(", ")}; it does not block ${STOP_BOUNDARY_GUARD_SCOPE.excluded.join(", ")}.`;
+	if (blocked.stepIndex === undefined) {
+		return {
+			action: blocked,
+			command: blocked.command,
+			message: `Blocked likely final submit/order ${actionPhrase} (${target}) because the latest user prompt set an explicit stop boundary. Gather evidence on the current page instead of activating the final action. ${scopeNote}`,
+			reason: "explicit-user-stop-boundary",
+			target,
+		};
+	}
+	return {
+		action: blocked,
+		command: blocked.command,
+		message: `Blocked likely final submit/order ${actionPhrase} in batch step ${blocked.stepIndex + 1} (${target}) because the latest user prompt set an explicit stop boundary. Gather evidence on the current page instead of activating the final action. ${scopeNote}`,
+		reason: "explicit-user-stop-boundary",
+		stepIndex: blocked.stepIndex,
+		target,
+	};
+}
+
+function resolveArtifactPath(cwd: string, path: string): string {
+	return isAbsolute(path) ? path : resolve(cwd, path);
+}
+
+function manifestContainsArtifact(manifest: SessionArtifactManifest | undefined, cwd: string, artifact: PromptRequestedArtifact): boolean {
+	if (!manifest) return false;
+	const requestedAbsolutePath = resolveArtifactPath(cwd, artifact.path);
+	const expectedKind = artifact.kind === "screenshot" ? "image" : "video";
+	return manifest.entries.some((entry) => {
+		const entryAbsolutePath = entry.absolutePath ?? resolveArtifactPath(cwd, entry.path);
+		return entry.storageScope === "explicit-path" && entry.kind === expectedKind && entryAbsolutePath === requestedAbsolutePath && entry.retentionState === "live" && entry.exists === true;
+	});
+}
+
+async function isArtifactRequired(artifact: PromptRequestedArtifact): Promise<boolean> {
+	if (artifact.required) return true;
+	return artifact.kind === "recording" && await executableExistsOnPath("ffmpeg");
+}
+
+export async function findRequestedArtifactCloseViolation(options: { artifactManifest?: SessionArtifactManifest; command: string | undefined; cwd: string; promptPolicy: PromptPolicy }): Promise<RequestedArtifactCloseViolation | undefined> {
+	if (!isCloseCommand(options.command)) return undefined;
+	const missingArtifacts: PromptRequestedArtifact[] = [];
+	for (const artifact of options.promptPolicy.requestedArtifacts) {
+		if (!await isArtifactRequired(artifact)) continue;
+		if (!manifestContainsArtifact(options.artifactManifest, options.cwd, artifact)) missingArtifacts.push(artifact);
+	}
+	if (missingArtifacts.length === 0) return undefined;
+	const missingList = missingArtifacts.map((artifact) => `${artifact.kind}: ${artifact.path}`).join(", ");
+	return {
+		message: `Blocked browser close because requested artifact path${missingArtifacts.length === 1 ? " is" : "s are"} missing or unverified: ${missingList}. Save the requested artifact path first, or report why an optional artifact is unavailable before closing.`,
+		missingArtifacts,
+		reason: "requested-artifacts-missing-before-close",
+	};
+}