pi-agent-browser-native 0.2.0 → 0.2.2

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

@@ -1,9 +1,9 @@
 /**
- * Purpose: Build safe, deterministic agent-browser invocations for the pi-agent-browser extension.
- * Responsibilities: Validate raw tool arguments, derive implicit session names from the pi session identity, resolve implicit-session timeout/state helpers, detect explicit session usage, and build the effective CLI argument list passed to the upstream agent-browser binary.
+ * Purpose: Build safe, deterministic agent-browser invocations and persisted session state for the pi-agent-browser extension.
+ * Responsibilities: Validate raw tool arguments, derive extension-managed session names from the pi session identity, restore managed-session state from persisted tool details, redact sensitive invocation text, classify browser-oriented prompts, and build the effective CLI argument list passed to the upstream agent-browser binary.
  * Scope: Pure runtime-planning helpers only; no subprocess execution or filesystem access lives here.
  * Usage: Imported by the extension entrypoint and unit tests before spawning the upstream CLI.
- * Invariants/Assumptions: The wrapper stays thin, preserves upstream command vocabulary, and only injects `--json` plus an implicit `--session` when appropriate.
+ * Invariants/Assumptions: The wrapper stays thin, preserves upstream command vocabulary, keeps plain-text inspection stateless, and only injects `--json` plus an extension-managed `--session` when appropriate.
  */
 
 import { createHash, randomUUID } from "node:crypto";
@@ -23,6 +23,17 @@ const LEGACY_BASH_ALLOW_PATTERNS = [
 	/\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,
+	/\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(["--headers", "--proxy"]);
+const SENSITIVE_QUERY_PARAM_PATTERN =
+	/^(?:access(?:_|-)?token|api(?:_|-)?key|auth|authorization|bearer|client(?:_|-)?secret|code|cookie|id(?:_|-)?token|key|pass(?:word)?|refresh(?:_|-)?token|secret|session(?:_|-)?id|sig(?:nature)?|token)$/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|session(?:_|-)?id|set(?:_|-)?cookie|sig(?:nature)?|token|x(?:_|-)?api(?:_|-)?key)$/i;
 
 const GLOBAL_FLAGS_WITH_VALUES = new Set([
 	"--session",
@@ -49,6 +60,8 @@ const GLOBAL_FLAGS_WITH_VALUES = new Set([
 ]);
 const SHELL_OPERATOR_TOKENS = new Set(["&&", "||", "|", ";", ">", ">>", "<"]);
 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;
@@ -64,9 +77,19 @@ export interface SessionRecoveryHint {
 	recommendedSessionMode: "fresh";
 }
 
+export interface InvalidValueFlagDetails {
+	flag: string;
+	index: number;
+	reason: "missing-value" | "unexpected-flag";
+	receivedToken?: string;
+}
+
 export interface ExecutionPlan {
 	commandInfo: CommandInfo;
 	effectiveArgs: string[];
+	invalidValueFlag?: InvalidValueFlagDetails;
+	managedSessionName?: string;
+	plainTextInspection: boolean;
 	recoveryHint?: SessionRecoveryHint;
 	sessionName?: string;
 	startupScopedFlags: string[];
@@ -74,10 +97,152 @@ export interface ExecutionPlan {
 	validationError?: string;
 }
 
+export interface ManagedSessionState {
+	active: boolean;
+	replacedSessionName?: string;
+	sessionName: string;
+}
+
+export interface RestoredManagedSessionState extends ManagedSessionState {
+	freshSessionOrdinal: number;
+}
+
 export interface PromptPolicy {
 	allowLegacyAgentBrowserBash: boolean;
 }
 
+function isRecord(value: unknown): value is Record<string, unknown> {
+	return typeof value === "object" && value !== null;
+}
+
+function isStringArray(value: unknown): value is string[] {
+	return Array.isArray(value) && value.every((item) => typeof item === "string");
+}
+
+function shouldRedactQueryParam(name: string): boolean {
+	return SENSITIVE_QUERY_PARAM_PATTERN.test(name);
+}
+
+function redactUrlToken(token: string): string {
+	let parsed: URL;
+	try {
+		parsed = new URL(token);
+	} catch {
+		return token;
+	}
+
+	if (!["http:", "https:", "ws:", "wss:"].includes(parsed.protocol)) {
+		return token;
+	}
+
+	if (parsed.username.length > 0) {
+		parsed.username = "[REDACTED]";
+	}
+	if (parsed.password.length > 0) {
+		parsed.password = "[REDACTED]";
+	}
+
+	for (const [name] of parsed.searchParams) {
+		if (shouldRedactQueryParam(name)) {
+			parsed.searchParams.set(name, "[REDACTED]");
+		}
+	}
+
+	const hashText = parsed.hash.startsWith("#") ? parsed.hash.slice(1) : parsed.hash;
+	if (hashText.includes("=")) {
+		const hashParams = new URLSearchParams(hashText);
+		let mutated = false;
+		for (const [name] of hashParams) {
+			if (shouldRedactQueryParam(name)) {
+				hashParams.set(name, "[REDACTED]");
+				mutated = true;
+			}
+		}
+		if (mutated) {
+			parsed.hash = `#${hashParams.toString()}`;
+		}
+	}
+
+	return parsed.toString();
+}
+
+function redactLooseUrlMatches(text: string): string {
+	return text.replace(/\b(?:https?|wss?):\/\/[^\s"'`<>\])]+/g, (match) => redactUrlToken(match));
+}
+
+export function redactSensitiveText(text: string): string {
+	return redactLooseUrlMatches(text)
+		.replace(/\b(Bearer)\s+[^\s",]+/gi, "$1 [REDACTED]")
+		.replace(/\b(Basic)\s+[^\s",]+/gi, "$1 [REDACTED]");
+}
+
+export function redactSensitiveValue(value: unknown): unknown {
+	if (typeof value === "string") {
+		return redactSensitiveText(value);
+	}
+	if (Array.isArray(value)) {
+		return value.map((item) => redactSensitiveValue(item));
+	}
+	if (!isRecord(value)) {
+		return value;
+	}
+	return Object.fromEntries(
+		Object.entries(value).map(([key, entryValue]) => {
+			if (SENSITIVE_FIELD_NAME_PATTERN.test(key)) {
+				return [key, "[REDACTED]"];
+			}
+			return [key, redactSensitiveValue(entryValue)];
+		}),
+	);
+}
+
+function redactFlagValue(flag: string, value: string): string {
+	if (SENSITIVE_VALUE_FLAGS.has(flag)) {
+		return "[REDACTED]";
+	}
+	return redactUrlToken(value);
+}
+
+export function redactInvocationArgs(args: string[]): string[] {
+	const redacted: string[] = [];
+	let pendingValueFlag: string | undefined;
+
+	for (const token of args) {
+		if (pendingValueFlag) {
+			redacted.push(redactFlagValue(pendingValueFlag, token));
+			pendingValueFlag = undefined;
+			continue;
+		}
+
+		const normalizedToken = token.split("=", 1)[0] ?? token;
+		if (SENSITIVE_VALUE_FLAGS.has(normalizedToken)) {
+			if (token.includes("=")) {
+				redacted.push(`${normalizedToken}=[REDACTED]`);
+			} else {
+				redacted.push(token);
+				pendingValueFlag = normalizedToken;
+			}
+			continue;
+		}
+
+		redacted.push(redactUrlToken(token));
+	}
+
+	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));
+}
+
 export function hasUsableBraveApiKey(apiKey: string | null | undefined = process.env[BRAVE_API_KEY_ENV]): boolean {
 	return typeof apiKey === "string" && apiKey.trim().length > 0;
 }
@@ -105,25 +270,106 @@ export function getImplicitSessionCloseTimeoutMs(env: NodeJS.ProcessEnv = proces
 	return parseTimeoutMs(env[IMPLICIT_SESSION_CLOSE_TIMEOUT_ENV], 0) ?? DEFAULT_IMPLICIT_SESSION_CLOSE_TIMEOUT_MS;
 }
 
-export function resolveImplicitSessionActiveState(options: {
+export function resolveManagedSessionState(options: {
 	command?: string;
+	managedSessionName?: string;
 	priorActive: boolean;
+	priorSessionName: string;
 	succeeded: boolean;
-	usedImplicitSession: boolean;
-}): boolean {
-	const { command, priorActive, succeeded, usedImplicitSession } = options;
-	if (!usedImplicitSession) return priorActive;
-	if (command === "close") {
-		return succeeded ? false : priorActive;
+}): ManagedSessionState {
+	const { command, managedSessionName, priorActive, priorSessionName, succeeded } = options;
+	if (!managedSessionName) {
+		return { active: priorActive, sessionName: priorSessionName };
+	}
+	if (command === "close" && managedSessionName === priorSessionName) {
+		return { active: succeeded ? false : priorActive, sessionName: priorSessionName };
+	}
+	if (!succeeded) {
+		return { active: priorActive, sessionName: priorSessionName };
+	}
+	return {
+		active: true,
+		replacedSessionName: priorActive && priorSessionName !== managedSessionName ? priorSessionName : undefined,
+		sessionName: managedSessionName,
+	};
+}
+
+function isRestorableManagedSessionName(sessionName: string, fallbackSessionName: string): boolean {
+	return sessionName === fallbackSessionName || sessionName.startsWith(`${fallbackSessionName}-fresh-`);
+}
+
+export function restoreManagedSessionStateFromBranch(
+	branch: unknown[],
+	fallbackSessionName: string,
+): RestoredManagedSessionState {
+	let restoredState: ManagedSessionState = {
+		active: false,
+		sessionName: fallbackSessionName,
+	};
+	let freshSessionOrdinal = 0;
+
+	for (const entry of branch) {
+		if (!isRecord(entry) || entry.type !== "message") {
+			continue;
+		}
+		const message = isRecord(entry.message) ? entry.message : undefined;
+		if (!message || message.toolName !== "agent_browser") {
+			continue;
+		}
+		const details = isRecord(message.details) ? message.details : undefined;
+		if (!details) {
+			continue;
+		}
+		const args = isStringArray(details.args) ? details.args : [];
+		if (isPlainTextInspectionArgs(args)) {
+			continue;
+		}
+
+		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 managedSessionName =
+			!explicitSessionName &&
+			sessionName &&
+			isRestorableManagedSessionName(sessionName, fallbackSessionName) &&
+			(usedImplicitSession || sessionMode === "fresh")
+				? sessionName
+				: undefined;
+		if (!managedSessionName) {
+			continue;
+		}
+
+		const messageIsError = typeof message.isError === "boolean" ? message.isError : undefined;
+		const exitCode = typeof details.exitCode === "number" ? details.exitCode : undefined;
+		const succeeded = messageIsError === undefined ? exitCode === undefined || exitCode === 0 : !messageIsError;
+		const command = typeof details.command === "string" ? details.command : parseCommandInfo(args).command;
+		restoredState = resolveManagedSessionState({
+			command,
+			managedSessionName,
+			priorActive: restoredState.active,
+			priorSessionName: restoredState.sessionName,
+			succeeded,
+		});
+		if (succeeded && sessionMode === "fresh") {
+			freshSessionOrdinal += 1;
+		}
 	}
-	if (!command) return priorActive;
-	return priorActive || succeeded;
+
+	return {
+		...restoredState,
+		freshSessionOrdinal,
+	};
 }
 
 export function createEphemeralSessionSeed(): string {
 	return randomUUID();
 }
 
+function createCwdHash(cwd: string): string {
+	return createHash("sha256").update(`cwd:${cwd}`).digest("hex").slice(0, SESSION_NAME_CWD_HASH_LENGTH);
+}
+
 export function createImplicitSessionName(
 	sessionId: string | undefined,
 	cwd: string,
@@ -135,13 +381,25 @@ export function createImplicitSessionName(
 			.replace(/[^a-z0-9]+/g, "-")
 			.replace(/^-+|-+$/g, "")
 			.slice(0, MAX_PROJECT_SLUG_LENGTH) || "project";
-	const stableSessionId = sessionId?.replace(/-/g, "").slice(0, 12);
+	const cwdHash = createCwdHash(cwd);
+	const stableSessionId = sessionId?.replace(/-/g, "").slice(0, SESSION_NAME_SESSION_ID_LENGTH);
 	if (stableSessionId && stableSessionId.length > 0) {
-		return `piab-${slug}-${stableSessionId}`;
+		return `piab-${slug}-${stableSessionId}-${cwdHash}`;
 	}
 
-	const digest = createHash("sha256").update(`ephemeral:${cwd}:${ephemeralSeed}`).digest("hex").slice(0, 12);
-	return `piab-${slug}-${digest}`;
+	const digest = createHash("sha256")
+		.update(`ephemeral:${cwd}:${ephemeralSeed}`)
+		.digest("hex")
+		.slice(0, SESSION_NAME_SESSION_ID_LENGTH);
+	return `piab-${slug}-${digest}-${cwdHash}`;
+}
+
+export function createFreshSessionName(baseSessionName: string, ephemeralSeed: string, ordinal: number): string {
+	const suffix = createHash("sha256")
+		.update(`fresh:${baseSessionName}:${ephemeralSeed}:${ordinal}`)
+		.digest("hex")
+		.slice(0, 10);
+	return `${baseSessionName}-fresh-${suffix}`;
 }
 
 export function validateToolArgs(args: string[]): string | undefined {
@@ -157,6 +415,54 @@ export function validateToolArgs(args: string[]): string | undefined {
 	return undefined;
 }
 
+function getInvalidValueFlagDetails(args: string[]): InvalidValueFlagDetails | undefined {
+	for (const [index, token] of args.entries()) {
+		if (!token.startsWith("-")) {
+			continue;
+		}
+		const normalizedToken = token.split("=", 1)[0] ?? token;
+		if (!GLOBAL_FLAGS_WITH_VALUES.has(normalizedToken)) {
+			continue;
+		}
+		if (token.includes("=")) {
+			const value = token.slice(token.indexOf("=") + 1).trim();
+			if (value.length === 0) {
+				return {
+					flag: normalizedToken,
+					index,
+					reason: "missing-value",
+				};
+			}
+			continue;
+		}
+		const receivedToken = args[index + 1];
+		if (receivedToken === undefined) {
+			return {
+				flag: normalizedToken,
+				index,
+				reason: "missing-value",
+			};
+		}
+		if (receivedToken.startsWith("-")) {
+			return {
+				flag: normalizedToken,
+				index,
+				reason: "unexpected-flag",
+				receivedToken,
+			};
+		}
+		continue;
+	}
+	return undefined;
+}
+
+function formatInvalidValueFlagError(details: InvalidValueFlagDetails): string {
+	if (details.reason === "unexpected-flag" && details.receivedToken) {
+		return `Flag \`${details.flag}\` requires a value, but received \`${details.receivedToken}\` instead. Pass a non-flag value immediately after \`${details.flag}\`.`;
+	}
+	return `Flag \`${details.flag}\` requires a value immediately after it. Pass a non-flag token like \`${details.flag} demo\`.`;
+}
+
 function hasFlagToken(args: string[], flag: string): boolean {
 	return args.some((token) => token === flag || token.startsWith(`${flag}=`));
 }
@@ -213,35 +519,72 @@ export function getLatestUserPrompt(branch: unknown[]): string {
 
 export function buildExecutionPlan(
 	args: string[],
-	options: { implicitSessionActive: boolean; implicitSessionName: string; sessionMode: SessionMode },
+	options: {
+		freshSessionName: string;
+		managedSessionActive: boolean;
+		managedSessionName: string;
+		sessionMode: SessionMode;
+	},
 ): ExecutionPlan {
+	const invalidValueFlag = getInvalidValueFlagDetails(args);
+	const startupScopedFlags = getStartupScopedFlags(args);
+	const plainTextInspection = isPlainTextInspectionArgs(args);
 	const commandInfo = parseCommandInfo(args);
+	const effectiveArgs = plainTextInspection ? [...args] : args.includes("--json") ? [] : ["--json"];
+	if (invalidValueFlag) {
+		return {
+			commandInfo: {},
+			effectiveArgs,
+			invalidValueFlag,
+			plainTextInspection: false,
+			startupScopedFlags: [],
+			usedImplicitSession: false,
+			validationError: formatInvalidValueFlagError(invalidValueFlag),
+		};
+	}
+
+	if (plainTextInspection) {
+		return {
+			commandInfo,
+			effectiveArgs,
+			plainTextInspection,
+			startupScopedFlags,
+			usedImplicitSession: false,
+		};
+	}
+
 	const explicitSessionName = extractExplicitSessionName(args);
-	const startupScopedFlags = getStartupScopedFlags(args);
-	const effectiveArgs = args.includes("--json") ? [] : ["--json"];
+	const shouldCreateFreshManagedSession =
+		!explicitSessionName && options.sessionMode === "fresh" && commandInfo.command !== undefined && commandInfo.command !== "close";
+	let managedSessionName: string | undefined;
 	let recoveryHint: SessionRecoveryHint | undefined;
 	let sessionName = explicitSessionName;
 	let usedImplicitSession = false;
 	let validationError: string | undefined;
 
 	if (!explicitSessionName && options.sessionMode === "auto") {
-		if (options.implicitSessionActive && startupScopedFlags.length > 0) {
+		if (options.managedSessionActive && startupScopedFlags.length > 0) {
 			recoveryHint = {
 				exampleArgs: args,
 				exampleParams: { args, sessionMode: "fresh" },
 				reason:
-					"Startup-scoped flags like --profile, --session-name, and --cdp need a fresh upstream launch once the implicit session is already active.",
+					"Startup-scoped flags like --profile, --session-name, and --cdp need a fresh upstream launch once the extension-managed session is already active.",
 				recommendedSessionMode: "fresh",
 			};
 			validationError = [
-				`The current implicit agent-browser session is already running, so startup-scoped flags ${startupScopedFlags.join(", ")} would be ignored by upstream agent-browser.`,
+				`The current extension-managed agent-browser session is already running, so startup-scoped flags ${startupScopedFlags.join(", ")} would be ignored by upstream agent-browser.`,
 				"Retry this call with `sessionMode: \"fresh\"` to force a fresh upstream launch, or pass an explicit `--session ...` if you want to name the new session yourself.",
 			].join(" ");
 		} else {
-			effectiveArgs.push("--session", options.implicitSessionName);
-			sessionName = options.implicitSessionName;
+			effectiveArgs.push("--session", options.managedSessionName);
+			managedSessionName = options.managedSessionName;
+			sessionName = options.managedSessionName;
 			usedImplicitSession = true;
 		}
+	} else if (shouldCreateFreshManagedSession) {
+		effectiveArgs.push("--session", options.freshSessionName);
+		managedSessionName = options.freshSessionName;
+		sessionName = options.freshSessionName;
 	}
 
 	effectiveArgs.push(...args);
@@ -249,6 +592,8 @@ export function buildExecutionPlan(
 	return {
 		commandInfo,
 		effectiveArgs,
+		managedSessionName,
+		plainTextInspection,
 		recoveryHint,
 		sessionName,
 		startupScopedFlags,
@@ -280,4 +625,3 @@ export function parseCommandInfo(args: string[]): CommandInfo {
 
 	return { command: commands[0], subcommand: commands[1] };
 }
-

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-agent-browser-native",
-  "version": "0.2.0",
+  "version": "0.2.2",
   "description": "pi extension that exposes agent-browser as a native tool for browser automation",
   "type": "module",
   "author": "Mitch Fultz (https://github.com/fitchmultz)",