pi-agent-browser-native 0.1.6 → 0.2.1

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.
+ * Responsibilities: Validate raw tool arguments, derive extension-managed session names from the pi session identity, resolve managed-session timeout/state helpers, detect explicit session usage, 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, and only injects `--json` plus an extension-managed `--session` when appropriate.
  */
 
 import { createHash, randomUUID } from "node:crypto";
@@ -16,13 +16,6 @@ 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 INSPECTION_ALLOW_PATTERNS = [
-	/\bagent[_ -]?browser\s+--(?:help|version)\b/i,
-	/\bagent[_ -]?browser\b.*\b(?:help|version|docs?|documentation|tool contract|tool guidance|tool description)\b/i,
-	/\b(?:help|version|docs?|documentation|tool contract|tool guidance|tool description)\b.*\bagent[_ -]?browser\b/i,
-	/\bdebug(?:ging)?\b.*\b(?:agent[_ -]?browser|agent_browser|browser integration)\b/i,
-	/\bwhy\s+(?:isn't|is not|doesn't|does not)\b.*\b(?:agent[_ -]?browser|agent_browser)\b/i,
-];
 const LEGACY_BASH_ALLOW_PATTERNS = [
 	/\b(?:bash-oriented workflow|bash workflow)\b/i,
 	/\b(?:use|via|through|with)\s+bash\b/i,
@@ -56,23 +49,49 @@ 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;
 	subcommand?: string;
 }
 
+export type SessionMode = "auto" | "fresh";
+
+export interface SessionRecoveryHint {
+	exampleArgs: string[];
+	exampleParams: { args: string[]; sessionMode: "fresh" };
+	reason: string;
+	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;
+	recoveryHint?: SessionRecoveryHint;
 	sessionName?: string;
 	startupScopedFlags: string[];
 	usedImplicitSession: boolean;
 	validationError?: string;
 }
 
+export interface ManagedSessionState {
+	active: boolean;
+	replacedSessionName?: string;
+	sessionName: string;
+}
+
 export interface PromptPolicy {
-	allowAgentBrowserInspection: boolean;
 	allowLegacyAgentBrowserBash: boolean;
 }
 
@@ -103,25 +122,38 @@ 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) return priorActive;
-	return priorActive || succeeded;
+	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,
+	};
 }
 
 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,
@@ -133,13 +165,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 {
@@ -155,6 +199,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}=`));
 }
@@ -177,7 +269,6 @@ export function getStartupScopedFlags(args: string[]): string[] {
 
 export function buildPromptPolicy(prompt: string): PromptPolicy {
 	return {
-		allowAgentBrowserInspection: INSPECTION_ALLOW_PATTERNS.some((pattern) => pattern.test(prompt)),
 		allowLegacyAgentBrowserBash: LEGACY_BASH_ALLOW_PATTERNS.some((pattern) => pattern.test(prompt)),
 	};
 }
@@ -212,27 +303,60 @@ export function getLatestUserPrompt(branch: unknown[]): string {
 
 export function buildExecutionPlan(
 	args: string[],
-	options: { implicitSessionActive: boolean; implicitSessionName: string; useActiveSession: boolean },
+	options: {
+		freshSessionName: string;
+		managedSessionActive: boolean;
+		managedSessionName: string;
+		sessionMode: SessionMode;
+	},
 ): ExecutionPlan {
+	const effectiveArgs = args.includes("--json") ? [] : ["--json"];
+	const invalidValueFlag = getInvalidValueFlagDetails(args);
+	if (invalidValueFlag) {
+		return {
+			commandInfo: {},
+			effectiveArgs,
+			invalidValueFlag,
+			startupScopedFlags: [],
+			usedImplicitSession: false,
+			validationError: formatInvalidValueFlagError(invalidValueFlag),
+		};
+	}
+
 	const commandInfo = parseCommandInfo(args);
 	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.useActiveSession) {
-		if (options.implicitSessionActive && startupScopedFlags.length > 0) {
+	if (!explicitSessionName && options.sessionMode === "auto") {
+		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 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.`,
-				"Reuse the existing implicit session without those flags, or start a fresh upstream session explicitly with `--session ...` (or `useActiveSession: false`) for a new launch.",
+				`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);
@@ -240,6 +364,8 @@ export function buildExecutionPlan(
 	return {
 		commandInfo,
 		effectiveArgs,
+		managedSessionName,
+		recoveryHint,
 		sessionName,
 		startupScopedFlags,
 		usedImplicitSession,

package/package.json

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