pi-agent-browser-native 0.2.33 → 0.2.35

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

@@ -4,6 +4,7 @@
  * Scope: Presentation shaping only; upstream stdout parsing and snapshot compaction internals live in separate modules.
  */
 
+import type { CompiledAgentBrowserSemanticAction } from "../input-modes/types.js";
 import { isRecord } from "../parsing.js";
 import type { CommandInfo } from "../runtime.js";
 import type { PersistentSessionArtifactStore } from "../temp.js";
@@ -43,6 +44,7 @@ import { buildErrorPresentation } from "./presentation/errors.js";
 import { compactLargePresentationOutput } from "./presentation/large-output.js";
 import { buildPageChangeSummary } from "./presentation/navigation.js";
 import { formatPresentationContentText, formatPresentationSummary } from "./presentation/registry.js";
+import { resolvePresentationCommandInfo } from "./presentation/semantic-action.js";
 
 function sanitizeModelFacingPresentation(presentation: ToolPresentation): ToolPresentation {
 	presentation.content = presentation.content.map((item) => {
@@ -65,6 +67,7 @@ export async function buildToolPresentation(options: {
 	artifactRequest?: ArtifactRequestContext;
 	batchArtifactRequests?: Array<ArtifactRequestContext | undefined>;
 	commandInfo: CommandInfo;
+	compiledSemanticAction?: CompiledAgentBrowserSemanticAction;
 	cwd: string;
 	envelope?: AgentBrowserEnvelope;
 	errorText?: string;
@@ -76,12 +79,14 @@ export async function buildToolPresentation(options: {
 		artifactManifest,
 		artifactRequest,
 		commandInfo,
+		compiledSemanticAction,
 		cwd,
 		envelope,
 		errorText,
 		persistentArtifactStore,
 		sessionName,
 	} = options;
+	const presentationCommandInfo = resolvePresentationCommandInfo(commandInfo, compiledSemanticAction);
 
 	if (errorText) {
 		return buildErrorPresentation({ args, commandInfo, errorText, sessionName });
@@ -89,10 +94,10 @@ export async function buildToolPresentation(options: {
 
 	const data = enrichStreamStatusData(commandInfo, envelope?.data);
 	const presentationData = redactPresentationData(commandInfo, data);
-	const artifacts = await extractFileArtifacts({ artifactRequest, commandInfo, cwd, data, sessionName });
+	const artifacts = await extractFileArtifacts({ artifactRequest, commandInfo: presentationCommandInfo, cwd, data, sessionName });
 	const artifactVerification = buildArtifactVerificationSummary(artifacts);
 	const artifactSummary = formatArtifactSummary(artifacts);
-	const summary = artifactSummary ?? formatPresentationSummary(commandInfo, data);
+	const summary = artifactSummary ?? formatPresentationSummary(commandInfo, data, compiledSemanticAction);
 	const artifactText = artifacts.length > 0 ? formatArtifactMetadataLines(artifacts).join("\n") : undefined;
 
 	let presentation: ToolPresentation;
@@ -113,7 +118,7 @@ export async function buildToolPresentation(options: {
 		presentation = {
 			artifactVerification,
 			artifacts: artifacts.length > 0 ? artifacts : undefined,
-			content: [{ type: "text", text: artifactText ?? formatPresentationContentText(commandInfo, data) }],
+			content: [{ type: "text", text: artifactText ?? formatPresentationContentText(commandInfo, data, compiledSemanticAction) }],
 			data: presentationData,
 			summary,
 		};
@@ -159,7 +164,7 @@ export async function buildToolPresentation(options: {
 	if (!presentationWithManifest.resultCategory) {
 		const categoryDetails = buildAgentBrowserResultCategoryDetails({
 			artifacts: presentationWithManifest.artifacts,
-			command: commandInfo.command,
+			command: presentationCommandInfo.command,
 			confirmationRequired: confirmationRequired !== undefined,
 			errorText: envelope?.success === false ? presentationWithManifest.summary : undefined,
 			savedFile: presentationWithManifest.savedFile,
@@ -186,7 +191,7 @@ export async function buildToolPresentation(options: {
 	const genericNextActions = presentationWithManifest.nextActions ? undefined : buildAgentBrowserNextActions({
 		artifacts: presentationWithManifest.artifacts,
 		args,
-		command: commandInfo.command,
+		command: presentationCommandInfo.command,
 		confirmationId: confirmationRequired?.id,
 		failureCategory: presentationWithManifest.failureCategory,
 		resultCategory: presentationWithManifest.resultCategory ?? "success",
@@ -203,7 +208,7 @@ export async function buildToolPresentation(options: {
 	);
 	presentationWithManifest.pageChangeSummary = presentationWithManifest.pageChangeSummary ?? buildPageChangeSummary({
 		artifacts: presentationWithManifest.artifacts,
-		commandInfo,
+		commandInfo: presentationCommandInfo,
 		data,
 		nextActions: presentationWithManifest.nextActions,
 		savedFilePath: presentationWithManifest.savedFilePath,

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

@@ -11,6 +11,23 @@
 import { createHash, randomUUID } from "node:crypto";
 import { basename } from "node:path";
 
+import {
+	extractCommandTokens,
+	findCommandStartIndex,
+	parseArgvDescriptor,
+	parseCommandInfo,
+	type CommandInfo,
+} from "./argv-descriptor.js";
+import {
+	GLOBAL_VALUE_FLAGS_ALLOWING_DASH_VALUE,
+	PREVALIDATED_VALUE_FLAGS,
+} from "./argv-grammar.js";
+import { needsManagedSession } from "./command-policy.js";
+import { isCloseCommand, isOpenNavigationCommand } from "./command-taxonomy.js";
+
+export type { CommandInfo } from "./argv-descriptor.js";
+export { extractCommandTokens, findCommandStartIndex, parseArgvDescriptor, parseCommandInfo } from "./argv-descriptor.js";
+
 import { isRecord } from "./parsing.js";
 
 /**
@@ -81,7 +98,6 @@ const LAUNCH_SCOPED_FLAG_LABEL = LAUNCH_SCOPED_FLAG_DEFINITIONS.map((definition)
  * tab-correction (the `tab list` + re-select cycle).
  */
 const LAUNCH_SCOPED_TAB_CORRECTION_FLAGS = new Set(["--profile", "--session-name", "--state"] as const);
-const OPEN_COMMANDS = new Set(["goto", "navigate", "open"]);
 const OPENAI_HEADLESS_COMPAT_HOSTS = new Set(["chat.com", "chat.openai.com", "chatgpt.com"]);
 const BRAVE_API_KEY_ENV = "BRAVE_API_KEY";
 const AGENT_BROWSER_IDLE_TIMEOUT_ENV = "AGENT_BROWSER_IDLE_TIMEOUT_MS";
@@ -89,99 +105,13 @@ const IMPLICIT_SESSION_IDLE_TIMEOUT_ENV = "PI_AGENT_BROWSER_IMPLICIT_SESSION_IDL
 const IMPLICIT_SESSION_CLOSE_TIMEOUT_ENV = "PI_AGENT_BROWSER_IMPLICIT_SESSION_CLOSE_TIMEOUT_MS";
 const DEFAULT_IMPLICIT_SESSION_IDLE_TIMEOUT_MS = 15 * 60 * 1000;
 const DEFAULT_IMPLICIT_SESSION_CLOSE_TIMEOUT_MS = 5_000;
-const LEGACY_BASH_ALLOW_PATTERNS = [
-	/\b(?:bash-oriented workflow|bash workflow)\b/i,
-	/\b(?:use|via|through|with)\s+bash\b/i,
-	/\bnpx\s+agent-browser\b/i,
-	/\bagent-browser\s+--(?:help|version)\b/i,
-	/\bdebug(?:ging)?\b.*\b(?:agent[_ -]?browser|agent_browser|browser integration)\b/i,
-];
-const BROWSER_PROMPT_PATTERNS = [
-	/\b(?:agent[_ -]?browser|browser automation|eval\s+--stdin|screenshot|snapshot|tab\s+list)\b/i,
-	/\b(?:react\s+(?:tree|inspect|renders|suspense)|web\s+vitals|core\s+web\s+vitals|pushstate)\b/i,
-	/\b(?:live\s+docs?|online\s+research|research\s+(?:online|the\s+web)|search\s+(?:online|the\s+web)|web\s+research)\b/i,
-	/\bbrowser\b.*\b(?:automation|click|fill|navigate|open|page|screenshot|site|snapshot|tab|url|visit|web(?:site| page)?)\b/i,
-	/\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(["--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",
-	"--annotate",
-	"--auto-connect",
-	"--confirm-interactive",
-	"--content-boundaries",
-	"--debug",
-	"--headed",
-	"--ignore-https-errors",
-	"--json",
-	"--no-auto-dialog",
-	"--quiet",
-	"-q",
-	"--verbose",
-	"-v",
-]);
 const SENSITIVE_QUERY_PARAM_PATTERN =
 	/^(?:access(?:_|-)?token|api(?:_|-)?key|auth|authorization|bearer|client(?:_|-)?secret|code|cookie|id(?:_|-)?token|key|pass(?:word)?|refresh(?:_|-)?token|secret|sentry(?:_|-)?key|session(?:_|-)?id|sig(?:nature)?|token|write(?:_|-)?key)$/i;
 const SENSITIVE_FIELD_NAME_PATTERN =
 	/^(?:access(?:_|-)?token|api(?:_|-)?key|auth(?:orization)?|bearer|client(?:_|-)?secret|cookie|id(?:_|-)?token|pass(?:word)?|proxy(?:_|-)?authorization|refresh(?:_|-)?token|secret|sentry(?:_|-)?key|session(?:_|-)?id|set(?:_|-)?cookie|sig(?:nature)?|token|write(?:_|-)?key|x(?:_|-)?api(?:_|-)?key)$/i;
 
-const VALUE_FLAGS = new Set([
-	"--session",
-	"--cdp",
-	"--config",
-	"--profile",
-	"--session-name",
-	"--proxy",
-	"--proxy-bypass",
-	"--headers",
-	"--executable-path",
-	"--extension",
-	"--init-script",
-	"--enable",
-	"--provider",
-	"-p",
-	"--engine",
-	"--state",
-	"--download-path",
-	"--screenshot-dir",
-	"--screenshot-format",
-	"--screenshot-quality",
-	"--color-scheme",
-	"--device",
-	"--port",
-	"--args",
-	"--user-agent",
-	"--allowed-domains",
-	"--action-policy",
-	"--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",
 	linux: "Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/146.0.0.0 Safari/537.36",
@@ -194,11 +124,6 @@ const MAX_PROJECT_SLUG_LENGTH = 24;
 const SESSION_NAME_CWD_HASH_LENGTH = 8;
 const SESSION_NAME_SESSION_ID_LENGTH = 12;
 
-export interface CommandInfo {
-	command?: string;
-	subcommand?: string;
-}
-
 export type SessionMode = "auto" | "fresh";
 
 export interface SessionRecoveryHint {
@@ -248,13 +173,10 @@ export interface ManagedSessionState {
 }
 
 export interface RestoredManagedSessionState extends ManagedSessionState {
+	closedSessionName?: string;
 	freshSessionOrdinal: number;
 }
 
-export interface PromptPolicy {
-	allowLegacyAgentBrowserBash: boolean;
-}
-
 function isStringArray(value: unknown): value is string[] {
 	return Array.isArray(value) && value.every((item) => typeof item === "string");
 }
@@ -504,22 +426,10 @@ export function redactInvocationArgs(args: string[]): string[] {
 	return redacted;
 }
 
-export function shouldAppendBrowserSystemPrompt(prompt: string): boolean {
-	const normalizedPrompt = prompt.trim();
-	if (normalizedPrompt.length === 0) {
-		return false;
-	}
-	return BROWSER_PROMPT_PATTERNS.some((pattern) => pattern.test(normalizedPrompt));
-}
-
 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;
 }
@@ -556,7 +466,7 @@ export function resolveManagedSessionState(options: {
 	if (!managedSessionName) {
 		return { active: priorActive, sessionName: priorSessionName };
 	}
-	if (command === "close" && managedSessionName === priorSessionName) {
+	if (isCloseCommand(command) && managedSessionName === priorSessionName) {
 		return { active: succeeded ? false : priorActive, sessionName: priorSessionName };
 	}
 	if (!succeeded) {
@@ -594,6 +504,29 @@ function getManagedSessionRestoreRank(options: {
 	return nextRank;
 }
 
+function getRestorableManagedSessionName(value: unknown, fallbackSessionName: string): string | undefined {
+	return typeof value === "string" && isRestorableManagedSessionName(value, fallbackSessionName) ? value : undefined;
+}
+
+function getElectronCleanupClosedManagedSessionNames(details: Record<string, unknown>, fallbackSessionName: string): string[] {
+	const electron = isRecord(details.electron) ? details.electron : undefined;
+	const cleanup = isRecord(electron?.cleanup) ? electron.cleanup : undefined;
+	const results = Array.isArray(cleanup?.results) ? cleanup.results : [];
+	const closedSessionNames = new Set<string>();
+	for (const result of results) {
+		if (!isRecord(result) || !Array.isArray(result.steps)) continue;
+		const record = isRecord(result.record) ? result.record : undefined;
+		for (const step of result.steps) {
+			if (!isRecord(step) || step.resource !== "managed-session") continue;
+			if (step.state !== "removed" && step.state !== "already-gone") continue;
+			const sessionName = getRestorableManagedSessionName(step.sessionName, fallbackSessionName)
+				?? getRestorableManagedSessionName(record?.sessionName, fallbackSessionName);
+			if (sessionName) closedSessionNames.add(sessionName);
+		}
+	}
+	return [...closedSessionNames];
+}
+
 export function restoreManagedSessionStateFromBranch(
 	branch: unknown[],
 	fallbackSessionName: string,
@@ -603,9 +536,21 @@ export function restoreManagedSessionStateFromBranch(
 		sessionName: fallbackSessionName,
 	};
 	let activeRestoreRank = 0;
+	let closedSessionName: string | undefined;
 	let freshSessionOrdinal = 0;
 	const freshSessionRanks = new Map<string, number>();
 
+	const applyManagedClose = (sessionName: string): void => {
+		const restoreRank = getManagedSessionRestoreRank({
+			fallbackSessionName,
+			freshSessionRanks,
+			sessionName,
+		});
+		if (restoreRank === undefined || sessionName !== restoredState.sessionName) return;
+		restoredState = { active: false, sessionName: restoredState.sessionName };
+		closedSessionName = sessionName;
+	};
+
 	for (const entry of branch) {
 		if (!isRecord(entry) || entry.type !== "message") {
 			continue;
@@ -623,17 +568,35 @@ export function restoreManagedSessionStateFromBranch(
 			continue;
 		}
 
+		for (const sessionName of getElectronCleanupClosedManagedSessionNames(details, fallbackSessionName)) {
+			applyManagedClose(sessionName);
+		}
+
 		const explicitSessionName = extractExplicitSessionName(args);
 		const sessionName = typeof details.sessionName === "string" ? details.sessionName : undefined;
 		const sessionMode = details.sessionMode === "fresh" || details.sessionMode === "auto" ? details.sessionMode : undefined;
 		const usedImplicitSession = details.usedImplicitSession === true;
+		const command = typeof details.command === "string" ? details.command : parseCommandInfo(args).command;
+		const commandClosesSession = isCloseCommand(command);
+		const outcome = typeof details.managedSessionOutcome === "object" && details.managedSessionOutcome !== null ? details.managedSessionOutcome as Record<string, unknown> : undefined;
+		const outcomeStatus = typeof outcome?.status === "string" ? outcome.status : undefined;
+		const outcomeCurrentSessionName = typeof outcome?.currentSessionName === "string" ? outcome.currentSessionName : undefined;
+		const outcomeAttemptedSessionName = getRestorableManagedSessionName(outcome?.attemptedSessionName, fallbackSessionName);
+		const outcomeClosedSessionName = outcomeStatus === "closed" && outcome?.succeeded === true
+			? outcomeAttemptedSessionName ?? getRestorableManagedSessionName(outcomeCurrentSessionName, fallbackSessionName) ?? getRestorableManagedSessionName(sessionName, fallbackSessionName)
+			: undefined;
+		const restorableDetailSessionName = getRestorableManagedSessionName(sessionName, fallbackSessionName);
+		const explicitCloseSessionName = commandClosesSession && explicitSessionName && restorableDetailSessionName === explicitSessionName
+			? restorableDetailSessionName
+			: undefined;
 		const managedSessionName =
 			!explicitSessionName &&
-			sessionName &&
-			isRestorableManagedSessionName(sessionName, fallbackSessionName) &&
+			restorableDetailSessionName &&
 			(usedImplicitSession || sessionMode === "fresh")
-				? sessionName
-				: undefined;
+				? restorableDetailSessionName
+				: commandClosesSession
+					? outcomeClosedSessionName ?? explicitCloseSessionName
+					: undefined;
 		if (!managedSessionName) {
 			continue;
 		}
@@ -646,25 +609,19 @@ export function restoreManagedSessionStateFromBranch(
 		if (restoreRank === undefined) {
 			continue;
 		}
+		freshSessionOrdinal = Math.max(freshSessionOrdinal, restoreRank);
 
 		const messageIsError = typeof message.isError === "boolean" ? message.isError : undefined;
 		const exitCode = typeof details.exitCode === "number" ? details.exitCode : undefined;
-		const outcome = typeof details.managedSessionOutcome === "object" && details.managedSessionOutcome !== null ? details.managedSessionOutcome as Record<string, unknown> : undefined;
-		const outcomeStatus = typeof outcome?.status === "string" ? outcome.status : undefined;
-		const outcomeCurrentSessionName = typeof outcome?.currentSessionName === "string" ? outcome.currentSessionName : undefined;
 		const outcomeActiveAfter = outcome?.activeAfter === true;
 		const outcomeRepresentsActiveCurrentSession = outcomeActiveAfter && outcomeCurrentSessionName === managedSessionName && (outcomeStatus === "created" || outcomeStatus === "replaced" || outcomeStatus === "unchanged");
 		const succeeded = outcomeRepresentsActiveCurrentSession ? true : messageIsError === undefined ? exitCode === undefined || exitCode === 0 : !messageIsError;
-		const command = typeof details.command === "string" ? details.command : parseCommandInfo(args).command;
-		if ((succeeded || outcomeRepresentsActiveCurrentSession) && sessionMode === "fresh") {
-			freshSessionOrdinal += 1;
-		}
-		const staleCompletion = succeeded && command !== "close" && restoreRank < activeRestoreRank;
-		if (staleCompletion) {
+		if (commandClosesSession) {
+			if (succeeded) applyManagedClose(managedSessionName);
 			continue;
 		}
-		const staleClose = command === "close" && restoredState.active && managedSessionName !== restoredState.sessionName;
-		if (staleClose) {
+		const staleCompletion = succeeded && restoreRank < activeRestoreRank;
+		if (staleCompletion) {
 			continue;
 		}
 
@@ -675,13 +632,15 @@ export function restoreManagedSessionStateFromBranch(
 			priorSessionName: restoredState.sessionName,
 			succeeded,
 		});
-		if (succeeded && command !== "close" && restoredState.active) {
+		if (succeeded && restoredState.active) {
 			activeRestoreRank = restoreRank;
+			closedSessionName = undefined;
 		}
 	}
 
 	return {
 		...restoredState,
+		...(closedSessionName ? { closedSessionName } : {}),
 		freshSessionOrdinal,
 	};
 }
@@ -739,11 +698,6 @@ export function validateToolArgs(args: string[]): string | undefined {
 	return undefined;
 }
 
-function isBooleanLiteral(token: string | undefined): boolean {
-	const normalized = token?.trim().toLowerCase();
-	return normalized === "true" || normalized === "false";
-}
-
 function getInvalidValueFlagDetails(args: string[]): InvalidValueFlagDetails | undefined {
 	for (let index = 0; index < args.length; index += 1) {
 		const token = args[index];
@@ -751,7 +705,7 @@ function getInvalidValueFlagDetails(args: string[]): InvalidValueFlagDetails | u
 			continue;
 		}
 		const normalizedToken = token.split("=", 1)[0] ?? token;
-		if (!VALUE_FLAGS.has(normalizedToken)) {
+		if (!PREVALIDATED_VALUE_FLAGS.has(normalizedToken)) {
 			continue;
 		}
 		if (token.includes("=")) {
@@ -876,7 +830,7 @@ function getDefaultHeadlessCompatUserAgent(platform: NodeJS.Platform = process.p
 }
 
 function getCompatibilityWorkaround(args: string[], commandInfo: CommandInfo): CompatibilityWorkaround | undefined {
-	if (!commandInfo.command || !OPEN_COMMANDS.has(commandInfo.command) || !commandInfo.subcommand) {
+	if (!commandInfo.command || !isOpenNavigationCommand(commandInfo.command) || !commandInfo.subcommand) {
 		return undefined;
 	}
 	if (hasFlagToken(args, "--user-agent")) {
@@ -947,40 +901,6 @@ export function hasLaunchScopedTabCorrectionFlag(args: string[]): boolean {
 	});
 }
 
-export function buildPromptPolicy(prompt: string): PromptPolicy {
-	return {
-		allowLegacyAgentBrowserBash: LEGACY_BASH_ALLOW_PATTERNS.some((pattern) => pattern.test(prompt)),
-	};
-}
-
-function getMessageText(content: unknown): string {
-	if (typeof content === "string") return content;
-	if (!Array.isArray(content)) return "";
-
-	return content
-		.map((item) => {
-			if (typeof item !== "object" || item === null) return "";
-			return item.type === "text" && typeof item.text === "string" ? item.text : "";
-		})
-		.filter((text) => text.length > 0)
-		.join("\n");
-}
-
-export function getLatestUserPrompt(branch: unknown[]): string {
-	for (let index = branch.length - 1; index >= 0; index -= 1) {
-		const entry = branch[index];
-		if (typeof entry !== "object" || entry === null || !("type" in entry) || entry.type !== "message") {
-			continue;
-		}
-		const message = "message" in entry ? entry.message : undefined;
-		if (typeof message !== "object" || message === null || !("role" in message) || message.role !== "user") {
-			continue;
-		}
-		return getMessageText("content" in message ? message.content : undefined);
-	}
-	return "";
-}
-
 export function buildExecutionPlan(
 	args: string[],
 	options: {
@@ -993,8 +913,10 @@ export function buildExecutionPlan(
 	const invalidValueFlag = getInvalidValueFlagDetails(args);
 	const startupScopedFlags = getStartupScopedFlags(args);
 	const plainTextInspection = isPlainTextInspectionArgs(args);
-	const commandInfo = parseCommandInfo(args);
-	const statelessInspection = plainTextInspection || isStatelessInspectionCommand(commandInfo);
+	const argvDescriptor = parseArgvDescriptor(args);
+	const commandTokens = argvDescriptor.commandTokens;
+	const commandInfo = argvDescriptor.commandInfo;
+	const commandNeedsManagedSession = !plainTextInspection && needsManagedSession(argvDescriptor);
 	const effectiveArgs = plainTextInspection ? [...args] : args.includes("--json") ? [] : ["--json"];
 	if (invalidValueFlag) {
 		return {
@@ -1020,7 +942,7 @@ export function buildExecutionPlan(
 
 	const explicitSessionName = extractExplicitSessionName(args);
 	const shouldCreateFreshManagedSession =
-		!explicitSessionName && options.sessionMode === "fresh" && commandInfo.command !== undefined && commandInfo.command !== "close";
+		!explicitSessionName && options.sessionMode === "fresh" && commandInfo.command !== undefined && !isCloseCommand(commandInfo.command);
 	const compatibilityWorkaround = getCompatibilityWorkaround(args, commandInfo);
 	let managedSessionName: string | undefined;
 	let recoveryHint: SessionRecoveryHint | undefined;
@@ -1028,7 +950,7 @@ export function buildExecutionPlan(
 	let usedImplicitSession = false;
 	let validationError: string | undefined;
 
-	if (!explicitSessionName && options.sessionMode === "auto" && !statelessInspection) {
+	if (!explicitSessionName && options.sessionMode === "auto" && commandNeedsManagedSession) {
 		if (options.managedSessionActive && startupScopedFlags.length > 0) {
 			recoveryHint = {
 				exampleArgs: args,
@@ -1047,7 +969,7 @@ export function buildExecutionPlan(
 			sessionName = options.managedSessionName;
 			usedImplicitSession = true;
 		}
-	} else if (shouldCreateFreshManagedSession && !statelessInspection) {
+	} else if (shouldCreateFreshManagedSession && commandNeedsManagedSession) {
 		effectiveArgs.push("--session", options.freshSessionName);
 		managedSessionName = options.freshSessionName;
 		sessionName = options.freshSessionName;
@@ -1116,59 +1038,3 @@ export function chooseOpenResultTabCorrection(options: {
 		}
 		: undefined;
 }
-
-function getOpenCommandTarget(commandTokens: string[]): string | undefined {
-	for (let index = 1; index < commandTokens.length; index += 1) {
-		const token = commandTokens[index];
-		if (token === "--init-script" || token === "--enable") {
-			index += 1;
-			continue;
-		}
-		if (token.startsWith("--init-script=") || token.startsWith("--enable=")) {
-			continue;
-		}
-		if (token.startsWith("-")) {
-			continue;
-		}
-		return token;
-	}
-	return undefined;
-}
-
-export function parseCommandInfo(args: string[]): CommandInfo {
-	const commandTokens = extractCommandTokens(args);
-	const command = commandTokens[0];
-	return {
-		command,
-		subcommand: command && OPEN_COMMANDS.has(command) ? getOpenCommandTarget(commandTokens) : commandTokens[1],
-	};
-}
-
-function findCommandStartIndex(args: string[]): number | undefined {
-	for (let index = 0; index < args.length; index += 1) {
-		const token = args[index];
-		if (token.startsWith("--session=")) {
-			continue;
-		}
-		if (token.startsWith("-")) {
-			const normalizedToken = token.split("=", 1)[0] ?? token;
-			if (VALUE_FLAGS.has(normalizedToken) && !token.includes("=")) {
-				index += 1;
-			} else if (
-				GLOBAL_BOOLEAN_FLAGS_WITH_OPTIONAL_VALUES.has(normalizedToken) &&
-				!token.includes("=") &&
-				isBooleanLiteral(args[index + 1])
-			) {
-				index += 1;
-			}
-			continue;
-		}
-		return index;
-	}
-	return undefined;
-}
-
-export function extractCommandTokens(args: string[]): string[] {
-	const commandStartIndex = findCommandStartIndex(args);
-	return commandStartIndex === undefined ? [] : args.slice(commandStartIndex);
-}