pi-agent-browser-native 0.2.34 → 0.2.35

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

package/extensions/agent-browser/lib/session-page-state.ts

@@ -6,6 +6,7 @@
  * Invariants/Assumptions: One tool-call update token must govern all page-state observations from that invocation; stale overlapping updates must not overwrite newer state.
  */
 
+import { isCloseCommand, isReadOnlyDiagnosticSessionTargetCommand } from "./command-taxonomy.js";
 import { isRecord } from "./parsing.js";
 
 export interface SessionTabTarget {
@@ -20,6 +21,7 @@ interface OrderedSessionTabTarget {
 
 export interface SessionRefSnapshot {
 	refIds: string[];
+	refs?: Record<string, { name: string; role: string }>;
 	target?: SessionTabTarget;
 }
 
@@ -132,12 +134,6 @@ function extractBatchResultCommand(item: Record<string, unknown>): string[] {
 	return Array.isArray(item.command) ? item.command.filter((token): token is string => typeof token === "string") : [];
 }
 
-const READ_ONLY_DIAGNOSTIC_SESSION_TARGET_COMMANDS = new Set(["console", "cookies", "errors", "network", "storage"]);
-
-function isReadOnlyDiagnosticSessionTargetCommand(command: string | undefined, _subcommand: string | undefined): boolean {
-	return command !== undefined && READ_ONLY_DIAGNOSTIC_SESSION_TARGET_COMMANDS.has(command);
-}
-
 export function extractSessionTabTargetFromCommandData(commandTokens: string[], data: unknown): SessionTabTarget | undefined {
 	const [command, subcommand] = commandTokens;
 	return isReadOnlyDiagnosticSessionTargetCommand(command, subcommand) ? undefined : extractSessionTabTargetFromData(data);
@@ -186,7 +182,7 @@ export function deriveSessionTabTarget(options: {
 	previousTarget?: SessionTabTarget;
 	subcommand?: string;
 }): SessionTabTarget | undefined {
-	if (options.command === "close") {
+	if (isCloseCommand(options.command)) {
 		return undefined;
 	}
 	const commandDataTarget = isReadOnlyDiagnosticSessionTargetCommand(options.command, options.subcommand)
@@ -234,10 +230,21 @@ function getRestoredSessionTabTarget(details: Record<string, unknown>, command:
 	return storedTarget;
 }
 
+function extractRefSnapshotRefs(data: unknown): Record<string, { name: string; role: string }> | undefined {
+	if (!isRecord(data) || !isRecord(data.refs)) return undefined;
+	const refs = Object.fromEntries(Object.entries(data.refs).flatMap(([refId, entry]) => {
+		if (!/^e\d+$/.test(refId) || !isRecord(entry) || typeof entry.name !== "string" || typeof entry.role !== "string") return [];
+		return [[refId, { name: entry.name, role: entry.role }] as const];
+	}));
+	return Object.keys(refs).length > 0 ? refs : undefined;
+}
+
 export function extractRefSnapshotFromData(data: unknown): SessionRefSnapshot | undefined {
 	if (!isRecord(data)) return undefined;
+	const refs = extractRefSnapshotRefs(data);
 	return {
 		refIds: isRecord(data.refs) ? Object.keys(data.refs).filter((refId) => /^e\d+$/.test(refId)) : [],
+		...(refs ? { refs } : {}),
 		target: extractSessionTabTargetFromData(data),
 	};
 }
@@ -295,14 +302,24 @@ function getRestoredRefSnapshotInvalidation(details: Record<string, unknown>, co
 }
 
 function getRestoredRefSnapshot(details: Record<string, unknown>): SessionRefSnapshot | undefined {
-	if (!isRecord(details.refSnapshot) || !Array.isArray(details.refSnapshot.refIds)) return undefined;
-	const refIds = details.refSnapshot.refIds.filter((refId): refId is string => typeof refId === "string" && /^e\d+$/.test(refId));
+	const refSnapshot = isRecord(details.refSnapshot) ? details.refSnapshot : undefined;
+	if (!refSnapshot || !Array.isArray(refSnapshot.refIds)) return undefined;
+	const refIds = refSnapshot.refIds.filter((refId): refId is string => typeof refId === "string" && /^e\d+$/.test(refId));
+	const refRecord = isRecord(refSnapshot.refs) ? refSnapshot.refs : undefined;
+	const refEntries = refRecord
+		? Object.fromEntries(refIds.flatMap((refId) => {
+			const entry = refRecord[refId];
+			if (!isRecord(entry) || typeof entry.name !== "string" || typeof entry.role !== "string") return [];
+			return [[refId, { name: entry.name, role: entry.role }] as const];
+		}))
+		: undefined;
 	return {
 		refIds,
-		target: isRecord(details.refSnapshot.target)
+		...(refEntries && Object.keys(refEntries).length > 0 ? { refs: refEntries } : {}),
+		target: isRecord(refSnapshot.target)
 			? normalizeSessionTabTarget({
-				title: typeof details.refSnapshot.target.title === "string" ? details.refSnapshot.target.title : undefined,
-				url: typeof details.refSnapshot.target.url === "string" ? details.refSnapshot.target.url : undefined,
+				title: typeof refSnapshot.target.title === "string" ? refSnapshot.target.title : undefined,
+				url: typeof refSnapshot.target.url === "string" ? refSnapshot.target.url : undefined,
 			  })
 			: undefined,
 	};
@@ -340,7 +357,7 @@ function shouldApplyRefStateUpdate(options: {
 }
 
 function stripRefSnapshotOrder(snapshot: OrderedSessionRefSnapshot | SessionRefSnapshot | undefined): SessionRefSnapshot | undefined {
-	return snapshot ? { refIds: snapshot.refIds, target: snapshot.target } : undefined;
+	return snapshot ? { refIds: snapshot.refIds, ...(snapshot.refs ? { refs: snapshot.refs } : {}), target: snapshot.target } : undefined;
 }
 
 function stripRefSnapshotInvalidationOrder(invalidation: OrderedSessionRefSnapshotInvalidation | SessionRefSnapshotInvalidation | undefined): SessionRefSnapshotInvalidation | undefined {
@@ -367,7 +384,7 @@ export class SessionPageState {
 			if (!sessionName) continue;
 			const command = typeof details.command === "string" ? details.command : undefined;
 			const subcommand = typeof details.subcommand === "string" ? details.subcommand : undefined;
-			if (command === "close" && message.isError !== true) {
+			if (isCloseCommand(command) && message.isError !== true) {
 				restoredOrder += 1;
 				state.clearSession(sessionName);
 				continue;