pi-agent-browser-native 0.2.1 → 0.2.2

package/CHANGELOG.md

@@ -1,5 +1,15 @@
 # Changelog
 
+## 0.2.2 - 2026-04-12
+
+### Fixed
+- plain-text inspection commands like `agent_browser --help` and `--version` now stay stateless: they no longer claim the implicit managed session or leave behind ambiguous `parseError` details on success
+- extension-managed session ownership is now reconstructed from persisted tool details on resume/reload while still preserving cwd-hash isolation across same-named checkouts and worktrees
+- echoed tool updates/details now redact sensitive invocation values and structured secret-bearing fields instead of replaying headers, proxy credentials, cookies, or auth-bearing URL params back into `pi`
+- the subprocess wrapper no longer forwards ambient parent-shell `AGENT_BROWSER_*` state into child runs, reducing surprising hidden configuration leaks from the caller environment
+- browser-specific system-prompt injection is now minimal and only added for clearly browser-oriented turns, while the full playbook stays in tool metadata where it belongs
+- published docs and changelog notes now match the current result/details contract, resume behavior, prompt behavior, and release workflow
+
 ## 0.2.1 - 2026-04-12
 
 ### Fixed
@@ -18,7 +28,7 @@
 - plain-text inspection commands like `agent_browser --help` and `--version` are now always allowed, removing the old prompt-dependent inspection gate and making the inspection contract local and predictable
 - navigation actions like `click`, `dblclick`, `back`, `forward`, and `reload` now include lightweight post-action title/url summaries when the wrapper can address the active session, reducing guess-and-check follow-up snapshots
 - compact snapshot rendering is leaner by default: fewer additional sections, fewer refs, smaller role summaries, and the raw spill path now stays in `details.fullOutputPath` instead of dominating the visible snapshot body
-- README and injected tool guidance now include a compact agent quick start with the core call shapes for `open` + `snapshot`, `click` + re-snapshot, `batch`, `eval --stdin`, and fresh profiled launches
+- README and tool prompt guidance now include a compact agent quick start with the core call shapes for `open` + `snapshot`, `click` + re-snapshot, `batch`, `eval --stdin`, and fresh profiled launches, while turn-level system-prompt injection stays minimal
 
 ### Migration notes
 - replace any use of `useActiveSession` with `sessionMode`
@@ -29,7 +39,7 @@
 ### Changed
 - hardened the implicit browser-session lifecycle so failed first launches no longer mark the convenience session active, startup-scoped flags behave correctly across launches and closes, and the highest-risk entrypoint paths now have direct automated and isolated-`pi` coverage
 - added explicit temp-root ownership markers, aggregate spill-file disk budgeting, inline image size limits, and graceful fallback behavior when large snapshot or stdout artifacts exceed temp budgets
-- consolidated the shared browser operating playbook across the injected system prompt and tool prompt guidance while adding direct extension-hook coverage for prompt injection, bash blocking, and session resets
+- consolidated the shared browser operating playbook into the tool prompt guidance while keeping turn-level system-prompt injection minimal, and added direct extension-hook coverage for prompt injection, bash blocking, and session resets
 - split the old result-rendering god module into focused envelope, presentation, shared, and snapshot modules, and made snapshot compaction fall back to a resilient outline mode when upstream raw snapshot formatting is unfamiliar
 - refactored the release-package verification script into smaller testable helpers, preserved the retired autoload-shim guard, and aligned the tarball gate with the split result-rendering module layout
 

package/README.md

@@ -181,16 +181,17 @@ Validated workflow examples:
 - run `batch` with JSON via `stdin`
 - run `eval --stdin`
 - take a screenshot with inline attachment support
-- inspect `agent_browser --help` and `--version` via the tool's plain-text inspection fallback
+- inspect `agent_browser --help` and `--version` via the tool's stateless plain-text inspection fallback
 
-Inspection commands like `agent_browser --help` and `--version` are always supported. They return plain text and are useful for debugging or capability checks, but they are not required for normal browsing workflows.
+Inspection commands like `agent_browser --help` and `--version` are always supported. They return plain text, are useful for debugging or capability checks, and stay stateless: the extension does not inject its implicit session for them and they do not consume the managed-session slot needed for a later `--profile`, `--session-name`, or `--cdp` launch.
 
 Current cautions:
 - passing `--profile` is an explicit upstream choice; this extension does not add its own profile-cloning or isolation layer
 - startup-scoped flags like `--profile`, `--session-name`, and `--cdp` are for the first command that launches a session; if the implicit session is already active, retry that call with `sessionMode: "fresh"` or provide an explicit `--session ...` for the new launch
-- implicit `piab-*` sessions are extension-managed convenience sessions; they are best-effort closed on `pi` shutdown, get an idle timeout to reduce stale background daemons, and clean up private temp spill artifacts on shutdown
+- implicit `piab-*` sessions are extension-managed convenience sessions; they are best-effort closed on `pi` shutdown, get an idle timeout to reduce stale background daemons, clean up private temp spill artifacts on shutdown, and are reconstructed from persisted tool details on resume/reload so later default calls keep following the active managed browser
 - `sessionMode: "fresh"` without an explicit `--session` rotates that extension-managed session to the new browser so later auto calls keep using it
 - explicit caller-provided `--session` values are treated as user-managed and are not auto-closed by the extension
+- tool progress/details redact sensitive invocation values such as `--headers`, proxy credentials, and auth-bearing URL parameters before echoing them back into Pi
 
 ### Switching from public browsing to a fresh profile/debug launch
 

package/docs/ARCHITECTURE.md

@@ -84,6 +84,7 @@ Practical policy:
 - on normal `pi` shutdown, best-effort close the current extension-managed session
 - also set an idle timeout on extension-managed sessions so abandoned daemons self-clean after inactivity
 - clean up private temp spill artifacts owned by the extension-managed session on shutdown
+- reconstruct the current extension-managed session from persisted tool details on resume/reload so later default calls keep following the active managed browser
 - if an unnamed fresh launch replaces an active extension-managed session, best-effort close the old managed session after the switch succeeds
 - leave explicit caller-provided `--session` choices alone unless the caller closes them explicitly
 

package/docs/REQUIREMENTS.md

@@ -84,7 +84,7 @@ The design should comfortably support workflows such as:
 - web research
 - using browser UIs for other LLMs such as ChatGPT, Grok, Gemini, and Claude
 - isolated authenticated browser sessions
-- cloned-profile workflows similar to the patterns used in `pi-oracle`
+- upstream profile/debug workflows without adding a local profile-cloning layer in this package
 
 ## Implications for the implementation
 

package/docs/TOOL_CONTRACT.md

@@ -121,7 +121,8 @@ Recommended details:
 ```json
 {
   "args": ["snapshot", "-i"],
-  "effectiveArgs": ["--session", "pi-abc123", "--json", "snapshot", "-i"],
+  "effectiveArgs": ["--json", "--session", "pi-abc123", "snapshot", "-i"],
+  "command": "snapshot",
   "sessionMode": "auto",
   "sessionName": "pi-abc123",
   "usedImplicitSession": true,
@@ -131,10 +132,21 @@ Recommended details:
       "e1": { "name": "Example Domain", "role": "heading" }
     },
     "snapshot": "- heading \"Example Domain\" [level=1, ref=e1]"
-  }
+  },
+  "summary": "Snapshot: 1 refs on https://example.com/"
 }
 ```
 
+Additional structured fields can appear when relevant:
+- `batchFailure` and `batchSteps` for `batch` rendering, including mixed-success runs
+- `navigationSummary` for navigation-style commands like `click`, `back`, `forward`, and `reload`
+- `imagePath` / `imagePaths` for screenshots and batched image outputs
+- `fullOutputPath` / `fullOutputPaths` when large snapshot output is compacted and spilled to a private temp file
+- `sessionRecoveryHint` when startup-scoped flags need `sessionMode: "fresh"`
+- `inspection: true` plus `stdout` for successful plain-text inspection commands like `--help` and `--version`
+
+When the tool echoes `args` or `effectiveArgs` back into Pi, sensitive values such as `--headers`, proxy credentials, and auth-bearing URL parameters should be redacted first.
+
 For oversized snapshots, details should switch to a compact metadata object and include `fullOutputPath` pointing at a private temp JSON spill file with the full upstream snapshot payload.
 
 ## High-value result rendering
@@ -164,10 +176,12 @@ If `agent-browser` is not on `PATH`, fail with a message that:
 - on normal `pi` shutdown, best-effort close the current extension-managed session
 - set an idle timeout on extension-managed sessions so abandoned daemons eventually self-clean
 - clean up private temp spill artifacts owned by the extension-managed session on shutdown
+- reconstruct the current extension-managed session from persisted tool details on resume/reload so later default calls keep following the active managed browser
 - when an unnamed `sessionMode: "fresh"` launch succeeds, make it the new extension-managed session so later default calls keep using it
 - if that unnamed fresh launch replaced an already-active managed session, best-effort close the old managed session after the switch succeeds
 - treat explicit caller-provided `--session` choices as user-managed
 - pass explicit `--profile` straight through to upstream `agent-browser`; no profile-cloning or isolation layer is added in v1
+- treat successful plain-text inspection commands like `--help` and `--version` as stateless: do not inject the implicit managed session and do not let those calls claim the managed-session slot
 - if startup-scoped flags like `--profile`, `--session-name`, or `--cdp` are supplied after the implicit session is already active while `sessionMode` is `"auto"`, return a validation error with a structured recovery hint that recommends `sessionMode: "fresh"`
 
 ## Non-goals

package/extensions/agent-browser/index.ts

@@ -23,7 +23,12 @@ import {
 	getImplicitSessionIdleTimeoutMs,
 	getLatestUserPrompt,
 	hasUsableBraveApiKey,
+	redactInvocationArgs,
+	redactSensitiveText,
+	redactSensitiveValue,
+	restoreManagedSessionStateFromBranch,
 	resolveManagedSessionState,
+	shouldAppendBrowserSystemPrompt,
 	validateToolArgs,
 } from "./lib/runtime.js";
 import { cleanupSecureTempArtifacts } from "./lib/temp.js";
@@ -106,10 +111,6 @@ function isHarmlessAgentBrowserInspectionCommand(command: string): boolean {
 	return HARMLESS_AGENT_BROWSER_INSPECTION_PATTERN.test(command);
 }
 
-function isPlainTextInspectionArgs(args: string[]): boolean {
-	return args.includes("--help") || args.includes("-h") || args.includes("--version") || args.includes("-V");
-}
-
 const NAVIGATION_SUMMARY_COMMANDS = new Set(["back", "click", "dblclick", "forward", "reload"]);
 
 interface NavigationSummary {
@@ -195,18 +196,6 @@ function buildSharedBrowserPlaybookGuidelines(hasBraveApiKey: boolean): string[]
 	];
 }
 
-function buildBrowserSystemPromptAppendix(hasBraveApiKey: boolean): string {
-	return [
-		PROJECT_RULE_PROMPT,
-		"",
-		"Quick start:",
-		...QUICK_START_GUIDELINES.map((guideline) => `- ${guideline}`),
-		"",
-		"Browser operating playbook:",
-		...buildSharedBrowserPlaybookGuidelines(hasBraveApiKey).map((guideline) => `- ${guideline}`),
-	].join("\n");
-}
-
 function buildToolPromptGuidelines(hasBraveApiKey: boolean): string[] {
 	return [
 		...TOOL_PROMPT_GUIDELINES_PREFIX,
@@ -216,6 +205,30 @@ function buildToolPromptGuidelines(hasBraveApiKey: boolean): string[] {
 	];
 }
 
+function buildSessionDetailFields(sessionName: string | undefined, usedImplicitSession: boolean): Record<string, unknown> {
+	return sessionName ? { sessionName, usedImplicitSession } : {};
+}
+
+function redactRecoveryHint(recoveryHint: {
+	exampleArgs: string[];
+	exampleParams: { args: string[]; sessionMode: "fresh" };
+	reason: string;
+	recommendedSessionMode: "fresh";
+} | undefined): typeof recoveryHint {
+	if (!recoveryHint) {
+		return undefined;
+	}
+	const exampleArgs = redactInvocationArgs(recoveryHint.exampleArgs);
+	return {
+		...recoveryHint,
+		exampleArgs,
+		exampleParams: {
+			...recoveryHint.exampleParams,
+			args: exampleArgs,
+		},
+	};
+}
+
 async function closeManagedSession(options: { cwd: string; sessionName: string; timeoutMs: number }): Promise<void> {
 	const controller = new AbortController();
 	const timer = setTimeout(() => controller.abort(), options.timeoutMs);
@@ -235,7 +248,6 @@ async function closeManagedSession(options: { cwd: string; sessionName: string;
 export default function agentBrowserExtension(pi: ExtensionAPI) {
 	const ephemeralSessionSeed = createEphemeralSessionSeed();
 	const hasBraveApiKey = hasUsableBraveApiKey();
-	const browserSystemPromptAppendix = buildBrowserSystemPromptAppendix(hasBraveApiKey);
 	const toolPromptGuidelines = buildToolPromptGuidelines(hasBraveApiKey);
 	const implicitSessionIdleTimeoutMs = getImplicitSessionIdleTimeoutMs();
 	const implicitSessionCloseTimeoutMs = getImplicitSessionCloseTimeoutMs();
@@ -246,26 +258,32 @@ export default function agentBrowserExtension(pi: ExtensionAPI) {
 	let freshSessionOrdinal = 0;
 
 	pi.on("session_start", async (_event, ctx) => {
-		managedSessionActive = false;
 		managedSessionBaseName = createImplicitSessionName(ctx.sessionManager.getSessionId(), ctx.cwd, ephemeralSessionSeed);
-		managedSessionName = managedSessionBaseName;
+		const restoredState = restoreManagedSessionStateFromBranch(ctx.sessionManager.getBranch(), managedSessionBaseName);
+		managedSessionActive = restoredState.active;
+		managedSessionName = restoredState.sessionName;
 		managedSessionCwd = ctx.cwd;
-		freshSessionOrdinal = 0;
+		freshSessionOrdinal = restoredState.freshSessionOrdinal;
 	});
 
 	pi.on("session_shutdown", async () => {
+		if (managedSessionActive) {
+			await closeManagedSession({
+				cwd: managedSessionCwd,
+				sessionName: managedSessionName,
+				timeoutMs: implicitSessionCloseTimeoutMs,
+			});
+		}
 		managedSessionActive = false;
-		await closeManagedSession({
-			cwd: managedSessionCwd,
-			sessionName: managedSessionName,
-			timeoutMs: implicitSessionCloseTimeoutMs,
-		});
 		await cleanupSecureTempArtifacts();
 	});
 
 	pi.on("before_agent_start", async (event) => {
+		if (!shouldAppendBrowserSystemPrompt(event.prompt)) {
+			return undefined;
+		}
 		return {
-			systemPrompt: `${event.systemPrompt}\n\n${browserSystemPromptAppendix}`,
+			systemPrompt: `${event.systemPrompt}\n\n${PROJECT_RULE_PROMPT}`,
 		};
 	});
 
@@ -294,11 +312,12 @@ export default function agentBrowserExtension(pi: ExtensionAPI) {
 		promptGuidelines: toolPromptGuidelines,
 		parameters: AGENT_BROWSER_PARAMS,
 		async execute(_toolCallId, params, signal, onUpdate, ctx) {
+			const redactedArgs = redactInvocationArgs(params.args);
 			const validationError = validateToolArgs(params.args);
 			if (validationError) {
 				return {
 					content: [{ type: "text", text: validationError }],
-					details: { args: params.args, validationError },
+					details: { args: redactedArgs, validationError },
 					isError: true,
 				};
 			}
@@ -311,6 +330,8 @@ export default function agentBrowserExtension(pi: ExtensionAPI) {
 				managedSessionName,
 				sessionMode,
 			});
+			const redactedEffectiveArgs = redactInvocationArgs(executionPlan.effectiveArgs);
+			const redactedRecoveryHint = redactRecoveryHint(executionPlan.recoveryHint);
 			if (executionPlan.managedSessionName === freshSessionName) {
 				freshSessionOrdinal += 1;
 			}
@@ -319,10 +340,10 @@ export default function agentBrowserExtension(pi: ExtensionAPI) {
 				return {
 					content: [{ type: "text", text: executionPlan.validationError }],
 					details: {
-						args: params.args,
+						args: redactedArgs,
 						invalidValueFlag: executionPlan.invalidValueFlag,
 						sessionMode,
-						sessionRecoveryHint: executionPlan.recoveryHint,
+						sessionRecoveryHint: redactedRecoveryHint,
 						startupScopedFlags: executionPlan.startupScopedFlags,
 						validationError: executionPlan.validationError,
 					},
@@ -331,12 +352,11 @@ export default function agentBrowserExtension(pi: ExtensionAPI) {
 			}
 
 			onUpdate?.({
-				content: [{ type: "text", text: `Running agent-browser ${buildInvocationPreview(executionPlan.effectiveArgs)}` }],
+				content: [{ type: "text", text: `Running agent-browser ${buildInvocationPreview(redactedEffectiveArgs)}` }],
 				details: {
-					effectiveArgs: executionPlan.effectiveArgs,
+					effectiveArgs: redactedEffectiveArgs,
 					sessionMode,
-					sessionName: executionPlan.sessionName,
-					usedImplicitSession: executionPlan.usedImplicitSession,
+					...buildSessionDetailFields(executionPlan.sessionName, executionPlan.usedImplicitSession),
 				},
 			});
 
@@ -353,8 +373,8 @@ export default function agentBrowserExtension(pi: ExtensionAPI) {
 				return {
 					content: [{ type: "text", text: errorText }],
 					details: {
-						args: params.args,
-						effectiveArgs: executionPlan.effectiveArgs,
+						args: redactedArgs,
+						effectiveArgs: redactedEffectiveArgs,
 						sessionMode,
 						spawnError: processResult.spawnError.message,
 					},
@@ -369,10 +389,11 @@ export default function agentBrowserExtension(pi: ExtensionAPI) {
 				});
 				let presentationEnvelope = parsed.envelope;
 				const processSucceeded = !processResult.aborted && !processResult.spawnError && processResult.exitCode === 0;
-				const plainTextInspection = isPlainTextInspectionArgs(params.args) && processSucceeded && parsed.parseError !== undefined;
-				const envelopeSuccess = plainTextInspection ? true : parsed.envelope?.success !== false;
+				const plainTextInspection = executionPlan.plainTextInspection && processSucceeded;
 				const parseSucceeded = plainTextInspection || parsed.parseError === undefined;
+				const envelopeSuccess = plainTextInspection ? true : parsed.envelope?.success !== false;
 				const succeeded = processSucceeded && parseSucceeded && envelopeSuccess;
+				const inspectionText = plainTextInspection ? processResult.stdout.trim() : undefined;
 
 				let navigationSummary: NavigationSummary | undefined;
 				if (succeeded && shouldCaptureNavigationSummary(executionPlan.commandInfo.command, parsed.envelope?.data)) {
@@ -423,9 +444,15 @@ export default function agentBrowserExtension(pi: ExtensionAPI) {
 
 				const presentation = plainTextInspection
 					? {
-						content: [{ type: "text" as const, text: processResult.stdout.trim() }],
+						batchFailure: undefined,
+						batchSteps: undefined,
+						content: [{ type: "text" as const, text: inspectionText ?? "" }],
+						data: undefined,
+						fullOutputPath: undefined,
+						fullOutputPaths: undefined,
 						imagePath: undefined,
-						summary: `${params.args.join(" ")} completed`,
+						imagePaths: undefined,
+						summary: `${redactedArgs.join(" ")} completed`,
 					  }
 					: await buildToolPresentation({
 							commandInfo: executionPlan.commandInfo,
@@ -433,33 +460,40 @@ export default function agentBrowserExtension(pi: ExtensionAPI) {
 							envelope: presentationEnvelope,
 							errorText,
 					  });
+				const redactedContent = presentation.content.map((item) =>
+					item.type === "text" ? { ...item, text: redactSensitiveText(item.text) } : item,
+				);
 
 				return {
-					content: presentation.content,
+					content: redactedContent,
 					details: {
-						args: params.args,
-						batchFailure: presentation.batchFailure,
-						batchSteps: presentation.batchSteps,
+						args: redactedArgs,
+						batchFailure: redactSensitiveValue(presentation.batchFailure),
+						batchSteps: redactSensitiveValue(presentation.batchSteps),
 						command: executionPlan.commandInfo.command,
 						subcommand: executionPlan.commandInfo.subcommand,
-						data: presentation.data,
-						error: parsed.envelope?.error,
-						navigationSummary,
-						effectiveArgs: executionPlan.effectiveArgs,
+						data: redactSensitiveValue(presentation.data),
+						error: plainTextInspection ? undefined : redactSensitiveValue(parsed.envelope?.error),
+						inspection: plainTextInspection || undefined,
+						navigationSummary: redactSensitiveValue(navigationSummary),
+						effectiveArgs: redactedEffectiveArgs,
 						exitCode: processResult.exitCode,
 						fullOutputPath: presentation.fullOutputPath,
 						fullOutputPaths: presentation.fullOutputPaths,
 						imagePath: presentation.imagePath,
 						imagePaths: presentation.imagePaths,
-						parseError: parsed.parseError,
+						parseError: plainTextInspection ? undefined : parsed.parseError,
 						sessionMode,
-						sessionName: executionPlan.sessionName,
-						sessionRecoveryHint: executionPlan.recoveryHint,
+						...buildSessionDetailFields(executionPlan.sessionName, executionPlan.usedImplicitSession),
+						sessionRecoveryHint: redactedRecoveryHint,
 						startupScopedFlags: executionPlan.startupScopedFlags,
-						stderr: processResult.stderr || undefined,
-						stdout: parseSucceeded ? undefined : processResult.stdout,
-						summary: presentation.summary,
-						usedImplicitSession: executionPlan.usedImplicitSession,
+						stderr: processResult.stderr ? redactSensitiveText(processResult.stderr) : undefined,
+						stdout: plainTextInspection
+							? redactSensitiveText(inspectionText ?? "")
+							: parseSucceeded
+								? undefined
+								: redactSensitiveText(processResult.stdout),
+						summary: redactSensitiveText(presentation.summary),
 					},
 					isError: !succeeded,
 				};

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

@@ -65,7 +65,7 @@ const INHERITED_ENV_NAMES = new Set([
 	allProxyEnvName,
 	noProxyEnvName,
 ]);
-const INHERITED_ENV_PREFIXES = ["AGENT_BROWSER_", "AI_GATEWAY_", "XDG_"] as const;
+const INHERITED_ENV_PREFIXES = ["AI_GATEWAY_", "XDG_"] as const;
 
 export interface ProcessRunResult {
 	aborted: boolean;

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 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.
+ * 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 extension-managed `--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",
@@ -78,6 +89,7 @@ export interface ExecutionPlan {
 	effectiveArgs: string[];
 	invalidValueFlag?: InvalidValueFlagDetails;
 	managedSessionName?: string;
+	plainTextInspection: boolean;
 	recoveryHint?: SessionRecoveryHint;
 	sessionName?: string;
 	startupScopedFlags: string[];
@@ -91,10 +103,146 @@ export interface ManagedSessionState {
 	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;
 }
@@ -146,6 +294,74 @@ export function resolveManagedSessionState(options: {
 	};
 }
 
+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;
+		}
+	}
+
+	return {
+		...restoredState,
+		freshSessionOrdinal,
+	};
+}
+
 export function createEphemeralSessionSeed(): string {
 	return randomUUID();
 }
@@ -310,22 +526,34 @@ export function buildExecutionPlan(
 		sessionMode: SessionMode;
 	},
 ): ExecutionPlan {
-	const effectiveArgs = args.includes("--json") ? [] : ["--json"];
 	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),
 		};
 	}
 
-	const commandInfo = parseCommandInfo(args);
+	if (plainTextInspection) {
+		return {
+			commandInfo,
+			effectiveArgs,
+			plainTextInspection,
+			startupScopedFlags,
+			usedImplicitSession: false,
+		};
+	}
+
 	const explicitSessionName = extractExplicitSessionName(args);
-	const startupScopedFlags = getStartupScopedFlags(args);
 	const shouldCreateFreshManagedSession =
 		!explicitSessionName && options.sessionMode === "fresh" && commandInfo.command !== undefined && commandInfo.command !== "close";
 	let managedSessionName: string | undefined;
@@ -365,6 +593,7 @@ export function buildExecutionPlan(
 		commandInfo,
 		effectiveArgs,
 		managedSessionName,
+		plainTextInspection,
 		recoveryHint,
 		sessionName,
 		startupScopedFlags,
@@ -396,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.1",
+  "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)",