pi-agent-browser-native 0.2.23 → 0.2.25

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

@@ -19,6 +19,55 @@ export interface AgentBrowserBatchResult {
 	success?: boolean;
 }
 
+export type AgentBrowserResultCategory = "failure" | "success";
+
+export type AgentBrowserSuccessCategory = "artifact-saved" | "artifact-unverified" | "completed" | "inspection";
+
+export type AgentBrowserFailureCategory =
+	| "aborted"
+	| "confirmation-required"
+	| "download-not-verified"
+	| "missing-binary"
+	| "parse-failure"
+	| "qa-failure"
+	| "selector-not-found"
+	| "selector-unsupported"
+	| "stale-ref"
+	| "tab-drift"
+	| "timeout"
+	| "upstream-error"
+	| "validation-error";
+
+export interface AgentBrowserResultCategoryDetails {
+	failureCategory?: AgentBrowserFailureCategory;
+	resultCategory: AgentBrowserResultCategory;
+	successCategory?: AgentBrowserSuccessCategory;
+}
+
+export interface AgentBrowserPageChangeSummary {
+	artifactCount?: number;
+	changeType: "artifact" | "confirmation" | "mutation" | "navigation";
+	command?: string;
+	nextActionIds?: string[];
+	savedFilePath?: string;
+	summary: string;
+	title?: string;
+	url?: string;
+}
+
+export interface AgentBrowserNextAction {
+	artifactPath?: string;
+	id: string;
+	params?: {
+		args: string[];
+		sessionMode?: "auto" | "fresh";
+		stdin?: string;
+	};
+	reason: string;
+	safety?: string;
+	tool: "agent_browser";
+}
+
 export type FileArtifactKind = "download" | "file" | "har" | "image" | "pdf" | "profile" | "trace" | "video";
 
 export type FileArtifactStatus = "missing" | "repaired-from-temp" | "saved" | "upstream-temp-only";
@@ -41,6 +90,32 @@ export interface FileArtifactMetadata {
 	tempPath?: string;
 }
 
+export type ArtifactVerificationState = "missing" | "pending" | "unverified" | "verified";
+
+export interface ArtifactVerificationEntry {
+	absolutePath?: string;
+	exists?: boolean;
+	kind: FileArtifactKind | "spill";
+	limitation?: string;
+	mediaType?: string;
+	path: string;
+	requestedPath?: string;
+	retentionState?: ArtifactRetentionState;
+	sizeBytes?: number;
+	state: ArtifactVerificationState;
+	status?: FileArtifactStatus;
+	storageScope?: ArtifactStorageScope;
+}
+
+export interface ArtifactVerificationSummary {
+	artifacts: ArtifactVerificationEntry[];
+	missingCount: number;
+	pendingCount: number;
+	unverifiedCount: number;
+	verified: boolean;
+	verifiedCount: number;
+}
+
 export interface SavedFilePresentationDetails {
 	command: "download" | "pdf" | "wait";
 	kind: "download" | "pdf";
@@ -187,18 +262,24 @@ export function mergeSessionArtifactManifest(options: {
 }
 
 export interface BatchStepPresentationDetails {
+	artifactVerification?: ArtifactVerificationSummary;
 	artifacts?: FileArtifactMetadata[];
 	command?: string[];
 	commandText: string;
 	data?: unknown;
+	failureCategory?: AgentBrowserFailureCategory;
+	nextActions?: AgentBrowserNextAction[];
+	pageChangeSummary?: AgentBrowserPageChangeSummary;
 	fullOutputPath?: string;
 	fullOutputPaths?: string[];
 	imagePath?: string;
 	imagePaths?: string[];
 	index: number;
+	resultCategory: AgentBrowserResultCategory;
 	savedFile?: SavedFilePresentationDetails;
 	savedFilePath?: string;
 	success: boolean;
+	successCategory?: AgentBrowserSuccessCategory;
 	summary: string;
 	text: string;
 }
@@ -213,20 +294,304 @@ export interface BatchFailurePresentationDetails {
 export interface ToolPresentation {
 	artifactManifest?: SessionArtifactManifest;
 	artifactRetentionSummary?: string;
+	artifactVerification?: ArtifactVerificationSummary;
 	artifacts?: FileArtifactMetadata[];
 	batchFailure?: BatchFailurePresentationDetails;
 	batchSteps?: BatchStepPresentationDetails[];
 	content: Array<{ text: string; type: "text" } | { data: string; mimeType: string; type: "image" }>;
 	data?: unknown;
+	failureCategory?: AgentBrowserFailureCategory;
 	fullOutputPath?: string;
 	fullOutputPaths?: string[];
 	imagePath?: string;
 	imagePaths?: string[];
+	nextActions?: AgentBrowserNextAction[];
+	pageChangeSummary?: AgentBrowserPageChangeSummary;
+	resultCategory?: AgentBrowserResultCategory;
 	savedFile?: SavedFilePresentationDetails;
 	savedFilePath?: string;
+	successCategory?: AgentBrowserSuccessCategory;
 	summary: string;
 }
 
+function isPendingFileArtifact(artifact: FileArtifactMetadata): boolean {
+	return artifact.command === "record" && artifact.subcommand === "start" && artifact.kind === "video";
+}
+
+function hasUnverifiedFileArtifact(artifacts: FileArtifactMetadata[] | undefined): boolean {
+	return (artifacts ?? []).some((artifact) => !isPendingFileArtifact(artifact) && artifact.exists !== true);
+}
+
+export function classifyAgentBrowserSuccessCategory(options: {
+	artifacts?: FileArtifactMetadata[];
+	inspection?: boolean;
+	savedFile?: SavedFilePresentationDetails;
+}): AgentBrowserSuccessCategory {
+	if (options.inspection) return "inspection";
+	if ((options.artifacts ?? []).length > 0) return hasUnverifiedFileArtifact(options.artifacts) ? "artifact-unverified" : "artifact-saved";
+	if (options.savedFile) return "artifact-saved";
+	return "completed";
+}
+
+export function classifyAgentBrowserFailureCategory(options: {
+	args?: string[];
+	command?: string;
+	confirmationRequired?: boolean;
+	errorText?: string;
+	parseError?: string;
+	spawnError?: string;
+	stderr?: string;
+	tabDrift?: boolean;
+	timedOut?: boolean;
+	validationError?: string;
+}): AgentBrowserFailureCategory {
+	const text = [options.errorText, options.validationError, options.parseError, options.spawnError, options.stderr].filter(Boolean).join("\n");
+	const command = options.command ?? "";
+	const usedRef = options.args?.some((arg) => /^@e\d+\b/.test(arg)) ?? false;
+	if (options.confirmationRequired || /confirmation required|pending confirmation|requires confirmation/i.test(text)) return "confirmation-required";
+	if (options.timedOut || /timeout|timed out|watchdog|IPC read timeout|must stay under its 30s IPC read timeout/i.test(text)) return "timeout";
+	if (/ENOENT|not found on PATH|could not find.*agent-browser|agent-browser is required but was not found/i.test(text)) return "missing-binary";
+	if (options.parseError || /invalid JSON|missing boolean success|success field must be boolean|returned no JSON output/i.test(text)) return "parse-failure";
+	if (/aborted/i.test(text)) return "aborted";
+	if (options.tabDrift || /could not re-select the intended tab|about:blank|selected tab looks wrong|tab drift|tab.*wrong/i.test(text)) return "tab-drift";
+	if (/\bUnknown ref\b|\bstale ref\b|@ref may be stale|\bref\b.*\b(?:not found|missing|expired)\b/i.test(text)) return "stale-ref";
+	if (usedRef && /could not locate element|element not found|no element/i.test(text)) return "stale-ref";
+	const mentionsPlaywrightSelectorDialect = /(?:\btext=|:has-text\(|\bgetByRole\b|\bgetByText\b)/i.test(text);
+	const reportsSelectorMatchFailure =
+		/\b(?:no elements? found|failed to find|could not find|unable to find)\b.*\b(?:selector|locator)\b/i.test(text) ||
+		/\b(?:selector|locator)\b.*\b(?:no elements? found|not found|missing|failed to find|could not find|unable to find)\b/i.test(text);
+	if (
+		/\b(?:unsupported|unknown|invalid)\s+(?:selector|locator)\b/i.test(text) ||
+		/\bfailed to parse selector\b/i.test(text) ||
+		/\bselector\b.*\b(?:parse|syntax|unsupported|invalid)\b/i.test(text) ||
+		(mentionsPlaywrightSelectorDialect && reportsSelectorMatchFailure)
+	) {
+		return "selector-unsupported";
+	}
+	if (reportsSelectorMatchFailure) return "selector-not-found";
+	if ((command === "download" || text.includes("wait --download") || /\bdownload\b/i.test(text)) && /missing|not verified|not found|failed|timeout|timed out/i.test(text)) {
+		return "download-not-verified";
+	}
+	if (options.validationError) return "validation-error";
+	return "upstream-error";
+}
+
+function buildNextToolAction(options: {
+	args: string[];
+	id: string;
+	reason: string;
+	safety?: string;
+	sessionMode?: "auto" | "fresh";
+	stdin?: string;
+}): AgentBrowserNextAction {
+	return {
+		id: options.id,
+		params: {
+			args: options.args,
+			...(options.sessionMode ? { sessionMode: options.sessionMode } : {}),
+			...(options.stdin ? { stdin: options.stdin } : {}),
+		},
+		reason: options.reason,
+		...(options.safety ? { safety: options.safety } : {}),
+		tool: "agent_browser",
+	};
+}
+
+function buildArtifactAction(path: string): AgentBrowserNextAction {
+	return {
+		artifactPath: path,
+		id: "use-saved-artifact",
+		reason: "Use the saved artifact path from the structured result instead of scraping it from text.",
+		safety: "Verify artifact metadata such as exists/status before treating the file as durable.",
+		tool: "agent_browser",
+	};
+}
+
+function buildArtifactVerificationAction(artifact: FileArtifactMetadata): AgentBrowserNextAction {
+	return {
+		artifactPath: artifact.path,
+		id: "verify-artifact-path",
+		reason: "The wrapper has artifact metadata but did not verify this file as present on disk.",
+		safety: "Check details.artifactVerification and the filesystem before treating the artifact as durable.",
+		tool: "agent_browser",
+	};
+}
+
+const MUTATING_COMMANDS = new Set([
+	"back",
+	"check",
+	"click",
+	"dblclick",
+	"dialog",
+	"fill",
+	"forward",
+	"hover",
+	"press",
+	"pushstate",
+	"reload",
+	"scroll",
+	"scrollintoview",
+	"select",
+	"swipe",
+	"tap",
+	"type",
+	"uncheck",
+]);
+
+function getDownloadRetryPath(args: string[] | undefined, fallback: string | undefined): string | undefined {
+	if (fallback) return fallback;
+	if (!args || args.length === 0) return undefined;
+	const downloadFlagIndex = args.indexOf("--download");
+	if (downloadFlagIndex >= 0) {
+		const candidate = args[downloadFlagIndex + 1];
+		return candidate && !candidate.startsWith("-") ? candidate : undefined;
+	}
+	const downloadCommandIndex = args.indexOf("download");
+	if (downloadCommandIndex >= 0 && args.length > downloadCommandIndex + 2) {
+		return args[args.length - 1];
+	}
+	return undefined;
+}
+
+export function buildAgentBrowserNextActions(options: {
+	artifacts?: FileArtifactMetadata[];
+	args?: string[];
+	command?: string;
+	confirmationId?: string;
+	failureCategory?: AgentBrowserFailureCategory;
+	resultCategory: AgentBrowserResultCategory;
+	savedFilePath?: string;
+	successCategory?: AgentBrowserSuccessCategory;
+}): AgentBrowserNextAction[] | undefined {
+	const actions: AgentBrowserNextAction[] = [];
+	if (options.resultCategory === "success") {
+		if (options.command === "open") {
+			actions.push(buildNextToolAction({
+				args: ["snapshot", "-i"],
+				id: "inspect-opened-page",
+				reason: "Inspect the opened page before choosing interactive refs.",
+			}));
+		} else if (options.command && MUTATING_COMMANDS.has(options.command)) {
+			actions.push(buildNextToolAction({
+				args: ["snapshot", "-i"],
+				id: "inspect-after-mutation",
+				reason: "Refresh interactive refs after a browser mutation, navigation, scroll, or rerender.",
+				safety: "Do not reuse prior @refs until a fresh snapshot confirms they still exist.",
+			}));
+		}
+		const artifacts = options.artifacts ?? [];
+		const savedFileArtifact = options.savedFilePath ? artifacts.find((artifact) => artifact.path === options.savedFilePath) : undefined;
+		if (options.savedFilePath && savedFileArtifact?.exists !== false) {
+			actions.push(buildArtifactAction(options.savedFilePath));
+		}
+		for (const artifact of artifacts) {
+			if (isPendingFileArtifact(artifact)) {
+				continue;
+			}
+			if (artifact.exists === false) {
+				if (artifact.kind === "download") {
+					actions.push(buildNextToolAction({
+						args: ["wait", "--download", artifact.path],
+						id: "wait-for-download",
+						reason: "Upstream reported a download path, but the wrapper did not verify the file on disk.",
+						safety: "Use a bounded wait timeout that stays below the native wrapper IPC budget.",
+					}));
+				} else {
+					actions.push(buildArtifactVerificationAction(artifact));
+				}
+				continue;
+			}
+			if (artifact.path !== options.savedFilePath) {
+				actions.push(buildArtifactAction(artifact.path));
+			}
+		}
+	} else {
+		switch (options.failureCategory) {
+			case "confirmation-required":
+				if (options.confirmationId) {
+					actions.push(
+						buildNextToolAction({
+							args: ["confirm", options.confirmationId],
+							id: "approve-confirmation",
+							reason: "Approve the pending upstream confirmation when the requested action is safe.",
+							safety: "Only confirm after reviewing the guarded action shown in the result.",
+						}),
+						buildNextToolAction({
+							args: ["deny", options.confirmationId],
+							id: "deny-confirmation",
+							reason: "Deny the pending upstream confirmation when the guarded action is unsafe or unintended.",
+						}),
+					);
+				}
+				break;
+			case "stale-ref":
+			case "selector-not-found":
+			case "selector-unsupported":
+				actions.push(buildNextToolAction({
+					args: ["snapshot", "-i"],
+					id: "refresh-interactive-refs",
+					reason: "Get current interactive refs before retrying the element action.",
+					safety: "Prefer a current @ref or a stable find locator; do not retry stale refs blindly.",
+				}));
+				break;
+			case "download-not-verified":
+				{
+					const retryPath = getDownloadRetryPath(options.args, options.savedFilePath);
+					actions.push(buildNextToolAction({
+						args: retryPath ? ["wait", "--download", retryPath] : ["wait", "--download"],
+						id: "wait-for-download",
+						reason: "Wait for the browser download and let the wrapper verify saved-file metadata.",
+						safety: "Use a bounded wait timeout that stays below the native wrapper IPC budget.",
+					}));
+				}
+				break;
+			case "tab-drift":
+				actions.push(
+					buildNextToolAction({
+						args: ["tab", "list"],
+						id: "list-tabs-for-recovery",
+						reason: "Inspect available tabs before selecting the intended target.",
+					}),
+					buildNextToolAction({
+						args: ["snapshot", "-i"],
+						id: "inspect-current-tab",
+						reason: "Inspect the currently selected tab after tab recovery.",
+					}),
+				);
+				break;
+		}
+	}
+	return actions.length > 0 ? actions : undefined;
+}
+
+export function buildAgentBrowserResultCategoryDetails(options: {
+	artifacts?: FileArtifactMetadata[];
+	args?: string[];
+	command?: string;
+	confirmationRequired?: boolean;
+	errorText?: string;
+	failureCategory?: AgentBrowserFailureCategory;
+	inspection?: boolean;
+	parseError?: string;
+	savedFile?: SavedFilePresentationDetails;
+	spawnError?: string;
+	succeeded: boolean;
+	tabDrift?: boolean;
+	timedOut?: boolean;
+	validationError?: string;
+}): AgentBrowserResultCategoryDetails {
+	if (options.succeeded) {
+		return {
+			resultCategory: "success",
+			successCategory: classifyAgentBrowserSuccessCategory(options),
+		};
+	}
+	return {
+		failureCategory: options.failureCategory ?? classifyAgentBrowserFailureCategory(options),
+		resultCategory: "failure",
+	};
+}
+
 export function stringifyUnknown(value: unknown): string {
 	if (typeof value === "string") return value;
 	if (typeof value === "number" || typeof value === "boolean") return String(value);

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

@@ -8,9 +8,21 @@
 
 export { getAgentBrowserErrorText, parseAgentBrowserEnvelope } from "./results/envelope.js";
 export { buildToolPresentation } from "./results/presentation.js";
+export {
+	buildAgentBrowserNextActions,
+	buildAgentBrowserResultCategoryDetails,
+	classifyAgentBrowserFailureCategory,
+	classifyAgentBrowserSuccessCategory,
+} from "./results/shared.js";
 export type {
 	AgentBrowserBatchResult,
 	AgentBrowserEnvelope,
+	AgentBrowserFailureCategory,
+	AgentBrowserResultCategory,
+	AgentBrowserNextAction,
+	AgentBrowserPageChangeSummary,
+	AgentBrowserResultCategoryDetails,
+	AgentBrowserSuccessCategory,
 	FileArtifactKind,
 	FileArtifactMetadata,
 	ToolPresentation,

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

@@ -47,10 +47,22 @@ const LAUNCH_SCOPED_FLAG_DEFINITIONS = [
 		flag: "--init-script",
 		reason: "registers page init scripts before the upstream browser session is launched",
 	},
+	{
+		flag: "--device",
+		reason: "selects the provider device for the upstream launch",
+	},
 	{
 		flag: "--profile",
 		reason: "selects Chrome profile state for the upstream launch",
 	},
+	{
+		flag: "--provider",
+		reason: "selects the upstream browser provider for the launch",
+	},
+	{
+		flag: "-p",
+		reason: "selects the upstream browser provider for the launch",
+	},
 	{
 		flag: "--session-name",
 		reason: "selects upstream saved auth/session state for the launch",
@@ -92,7 +104,7 @@ const BROWSER_PROMPT_PATTERNS = [
 	/\b(?:browse|click|fill|login|navigate|open|visit)\b.*\b(?:https?:\/\/\S+|page|site|tab|url|web(?:site| page)?)\b/i,
 ];
 const INSPECTION_FLAGS = new Set(["--help", "-h", "--version", "-V"]);
-const SENSITIVE_VALUE_FLAGS = new Set(["--headers", "--password", "--proxy"]);
+const SENSITIVE_VALUE_FLAGS = new Set(["--body", "--headers", "--password", "--proxy"]);
 const GLOBAL_VALUE_FLAGS_ALLOWING_DASH_VALUE = new Set(["--args"]);
 const GLOBAL_BOOLEAN_FLAGS_WITH_OPTIONAL_VALUES = new Set([
 	"--allow-file-access",
@@ -115,7 +127,7 @@ const SENSITIVE_QUERY_PARAM_PATTERN =
 const SENSITIVE_FIELD_NAME_PATTERN =
 	/^(?:access(?:_|-)?token|api(?:_|-)?key|auth(?:orization)?|bearer|client(?:_|-)?secret|cookie|id(?:_|-)?token|pass(?:word)?|proxy(?:_|-)?authorization|refresh(?:_|-)?token|secret|session(?:_|-)?id|set(?:_|-)?cookie|sig(?:nature)?|token|x(?:_|-)?api(?:_|-)?key)$/i;
 
-const GLOBAL_FLAGS_WITH_VALUES = new Set([
+const VALUE_FLAGS = new Set([
 	"--session",
 	"--cdp",
 	"--config",
@@ -146,6 +158,29 @@ const GLOBAL_FLAGS_WITH_VALUES = new Set([
 	"--confirm-actions",
 	"--max-output",
 	"--model",
+	"--baseline",
+	"--body",
+	"--categories",
+	"--curl",
+	"--depth",
+	"-d",
+	"--domain",
+	"--expires",
+	"--filter",
+	"--fn",
+	"--label",
+	"--load",
+	"--name",
+	"--path",
+	"--resource-type",
+	"--sameSite",
+	"--selector",
+	"-s",
+	"--text",
+	"--timeout",
+	"--url",
+	"--username",
+	"--password",
 ]);
 const DEFAULT_HEADLESS_COMPAT_USER_AGENT_BY_PLATFORM: Partial<Record<NodeJS.Platform, string>> = {
 	darwin: "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/146.0.0.0 Safari/537.36",
@@ -440,7 +475,7 @@ export function redactInvocationArgs(args: string[]): string[] {
 			continue;
 		}
 
-		redacted.push(redactUrlToken(token));
+		redacted.push(redactSensitiveText(redactUrlToken(token)));
 	}
 
 	const commandStartIndex = findCommandStartIndex(args);
@@ -452,6 +487,20 @@ export function redactInvocationArgs(args: string[]): string[] {
 		}
 	}
 
+	if (commandStartIndex !== undefined && args[commandStartIndex] === "cookies" && args[commandStartIndex + 1] === "set" && redacted[commandStartIndex + 3] !== undefined) {
+		redacted[commandStartIndex + 3] = "[REDACTED]";
+	}
+
+	if (
+		commandStartIndex !== undefined
+		&& args[commandStartIndex] === "storage"
+		&& ["local", "session"].includes(args[commandStartIndex + 1] ?? "")
+		&& args[commandStartIndex + 2] === "set"
+		&& redacted[commandStartIndex + 4] !== undefined
+	) {
+		redacted[commandStartIndex + 4] = "[REDACTED]";
+	}
+
 	return redacted;
 }
 
@@ -467,6 +516,10 @@ export function isPlainTextInspectionArgs(args: string[]): boolean {
 	return args.some((token) => INSPECTION_FLAGS.has(token));
 }
 
+function isStatelessInspectionCommand(commandInfo: CommandInfo): boolean {
+	return commandInfo.command === "skills" && ["list", "get", "path"].includes(commandInfo.subcommand ?? "");
+}
+
 export function hasUsableBraveApiKey(apiKey: string | null | undefined = process.env[BRAVE_API_KEY_ENV]): boolean {
 	return typeof apiKey === "string" && apiKey.trim().length > 0;
 }
@@ -693,7 +746,7 @@ function getInvalidValueFlagDetails(args: string[]): InvalidValueFlagDetails | u
 			continue;
 		}
 		const normalizedToken = token.split("=", 1)[0] ?? token;
-		if (!GLOBAL_FLAGS_WITH_VALUES.has(normalizedToken)) {
+		if (!VALUE_FLAGS.has(normalizedToken)) {
 			continue;
 		}
 		if (token.includes("=")) {
@@ -861,10 +914,23 @@ export function extractExplicitSessionName(args: string[]): string | undefined {
 	return undefined;
 }
 
+function hasLaunchScopedFlagToken(args: string[], flag: string): boolean {
+	const commandStartIndex = findCommandStartIndex(args);
+	const command = commandStartIndex === undefined ? undefined : args[commandStartIndex];
+	return args.some((token, index) => {
+		if (token !== flag && !token.startsWith(`${flag}=`)) return false;
+		if (flag === "--auto-connect") return isBooleanFlagEnabled(args, flag);
+		if (flag === "--state" && command === "wait" && commandStartIndex !== undefined && index > commandStartIndex) {
+			return false;
+		}
+		return true;
+	});
+}
+
 export function getStartupScopedFlags(args: string[]): string[] {
 	return LAUNCH_SCOPED_FLAG_DEFINITIONS
 		.map((definition) => definition.flag)
-		.filter((flag) => flag === "--auto-connect" ? isBooleanFlagEnabled(args, flag) : hasFlagToken(args, flag));
+		.filter((flag) => hasLaunchScopedFlagToken(args, flag));
 }
 
 export function hasLaunchScopedTabCorrectionFlag(args: string[]): boolean {
@@ -923,6 +989,7 @@ export function buildExecutionPlan(
 	const startupScopedFlags = getStartupScopedFlags(args);
 	const plainTextInspection = isPlainTextInspectionArgs(args);
 	const commandInfo = parseCommandInfo(args);
+	const statelessInspection = plainTextInspection || isStatelessInspectionCommand(commandInfo);
 	const effectiveArgs = plainTextInspection ? [...args] : args.includes("--json") ? [] : ["--json"];
 	if (invalidValueFlag) {
 		return {
@@ -956,7 +1023,7 @@ export function buildExecutionPlan(
 	let usedImplicitSession = false;
 	let validationError: string | undefined;
 
-	if (!explicitSessionName && options.sessionMode === "auto") {
+	if (!explicitSessionName && options.sessionMode === "auto" && !statelessInspection) {
 		if (options.managedSessionActive && startupScopedFlags.length > 0) {
 			recoveryHint = {
 				exampleArgs: args,
@@ -975,7 +1042,7 @@ export function buildExecutionPlan(
 			sessionName = options.managedSessionName;
 			usedImplicitSession = true;
 		}
-	} else if (shouldCreateFreshManagedSession) {
+	} else if (shouldCreateFreshManagedSession && !statelessInspection) {
 		effectiveArgs.push("--session", options.freshSessionName);
 		managedSessionName = options.freshSessionName;
 		sessionName = options.freshSessionName;
@@ -1080,7 +1147,7 @@ function findCommandStartIndex(args: string[]): number | undefined {
 		}
 		if (token.startsWith("-")) {
 			const normalizedToken = token.split("=", 1)[0] ?? token;
-			if (GLOBAL_FLAGS_WITH_VALUES.has(normalizedToken) && !token.includes("=")) {
+			if (VALUE_FLAGS.has(normalizedToken) && !token.includes("=")) {
 				index += 1;
 			} else if (
 				GLOBAL_BOOLEAN_FLAGS_WITH_OPTIONAL_VALUES.has(normalizedToken) &&

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-agent-browser-native",
-  "version": "0.2.23",
+  "version": "0.2.25",
   "description": "pi extension that exposes agent-browser as a native tool for browser automation",
   "type": "module",
   "author": "Mitch Fultz (https://github.com/fitchmultz)",
@@ -40,6 +40,7 @@
     "docs/COMMAND_REFERENCE.md",
     "docs/RELEASE.md",
     "docs/REQUIREMENTS.md",
+    "docs/SUPPORT_MATRIX.md",
     "docs/TOOL_CONTRACT.md"
   ],
   "pi": {
@@ -66,9 +67,10 @@
   "scripts": {
     "docs": "node ./scripts/project.mjs docs",
     "doctor": "node ./scripts/doctor.mjs",
+    "benchmark:agent-browser": "node ./scripts/agent-browser-efficiency-benchmark.mjs",
     "test": "tsx --test test/**/*.test.ts",
     "verify": "node ./scripts/project.mjs verify",
-    "prepublishOnly": "npm run verify && npm pack --dry-run"
+    "prepublishOnly": "npm run verify -- release && npm pack --dry-run"
   },
   "packageManager": "npm@11.14.0"
 }