pi-agent-browser-native 0.2.38 → 0.2.40

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

@@ -0,0 +1,446 @@
+/**
+ * Purpose: Load pi-agent-browser-native package configuration from Pi-scoped global, project, or explicit paths.
+ * Responsibilities: Resolve config paths, validate the v1 JSON shape, merge layers, classify credential sources, resolve secrets without exposing values, and provide redacted status for tools/CLIs.
+ * Scope: Package-owned configuration only; browser command execution and web-search API calls live in focused modules.
+ * Usage: The extension reads this at startup to decide optional tool registration; scripts/config.mjs mirrors the file locations for user setup.
+ * Invariants/Assumptions: Raw project-local plaintext credentials are unsafe and rejected; command credentials are resolved lazily at execution time.
+ */
+
+import { exec as execCallback } from "node:child_process";
+import { readFileSync } from "node:fs";
+import { readFile } from "node:fs/promises";
+import { homedir } from "node:os";
+import { join, resolve } from "node:path";
+import { promisify } from "node:util";
+
+const exec = promisify(execCallback);
+
+export const AGENT_BROWSER_CONFIG_ENV = "PI_AGENT_BROWSER_CONFIG";
+export const BRAVE_API_KEY_ENV = "BRAVE_API_KEY";
+export const CONFIG_RELATIVE_PATH = [".pi", "config", "pi-agent-browser-native", "config.json"] as const;
+export const GLOBAL_CONFIG_RELATIVE_PATH = [".pi", "config", "pi-agent-browser-native", "config.json"] as const;
+export const SECRET_COMMAND_TIMEOUT_MS = 15_000;
+
+export type BrowserDefaultProfilePolicy = "explicit-only" | "authenticated-only" | "always";
+export type AgentBrowserConfigScope = "global" | "project" | "override" | "env-fallback";
+export type CredentialSourceKind = "literal" | "env" | "command";
+
+export interface BrowserDefaultProfileConfig {
+	name: string;
+	policy?: BrowserDefaultProfilePolicy;
+}
+
+export interface AgentBrowserConfig {
+	version?: 1;
+	webSearch?: {
+		braveApiKey?: string;
+	};
+	browser?: {
+		defaultProfile?: BrowserDefaultProfileConfig;
+		defaultLaunchArgs?: string[];
+	};
+}
+
+export interface ConfigLayer {
+	config: AgentBrowserConfig;
+	path: string;
+	scope: Exclude<AgentBrowserConfigScope, "env-fallback">;
+}
+
+export interface CredentialSource {
+	kind: CredentialSourceKind;
+	rawValue: string;
+	scope: AgentBrowserConfigScope;
+}
+
+export interface AgentBrowserConfigState {
+	browserDefaultProfile?: Required<BrowserDefaultProfileConfig>;
+	config: AgentBrowserConfig;
+	credentialSource?: CredentialSource;
+	errors: string[];
+	layers: ConfigLayer[];
+	paths: {
+		global: string;
+		project: string;
+		override?: string;
+	};
+	warnings: string[];
+}
+
+export interface ResolvedCredential {
+	source: CredentialSource;
+	value: string;
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function hasOwn(value: Record<string, unknown>, key: string): boolean {
+	return Object.prototype.hasOwnProperty.call(value, key);
+}
+
+export function getGlobalAgentBrowserConfigPath(env: NodeJS.ProcessEnv = process.env): string {
+	const home = env.HOME?.trim() || env.USERPROFILE?.trim() || homedir();
+	return join(home, ...GLOBAL_CONFIG_RELATIVE_PATH);
+}
+
+export function getProjectAgentBrowserConfigPath(cwd = process.cwd()): string {
+	return resolve(cwd, ...CONFIG_RELATIVE_PATH);
+}
+
+export function getAgentBrowserConfigPaths(options: { cwd?: string; env?: NodeJS.ProcessEnv } = {}) {
+	const env = options.env ?? process.env;
+	const override = env[AGENT_BROWSER_CONFIG_ENV]?.trim();
+	return {
+		global: getGlobalAgentBrowserConfigPath(env),
+		project: getProjectAgentBrowserConfigPath(options.cwd),
+		override: override ? resolve(override) : undefined,
+	};
+}
+
+function mergeConfig(base: AgentBrowserConfig, override: AgentBrowserConfig): AgentBrowserConfig {
+	return {
+		...base,
+		...override,
+		browser: {
+			...(base.browser ?? {}),
+			...(override.browser ?? {}),
+			defaultProfile: override.browser?.defaultProfile ?? base.browser?.defaultProfile,
+		},
+		webSearch: {
+			...(base.webSearch ?? {}),
+			...(override.webSearch ?? {}),
+		},
+	};
+}
+
+function validateString(value: unknown, path: string, errors: string[]): string | undefined {
+	if (value === undefined) return undefined;
+	if (typeof value !== "string") {
+		errors.push(`${path} must be a string.`);
+		return undefined;
+	}
+	return value;
+}
+
+function validateStringArray(value: unknown, path: string, errors: string[]): string[] | undefined {
+	if (value === undefined) return undefined;
+	if (!Array.isArray(value) || value.some((entry) => typeof entry !== "string")) {
+		errors.push(`${path} must be an array of strings.`);
+		return undefined;
+	}
+	return value;
+}
+
+function validateBrowserDefaultProfile(value: unknown, path: string, errors: string[]): BrowserDefaultProfileConfig | undefined {
+	if (value === undefined) return undefined;
+	if (!isRecord(value)) {
+		errors.push(`${path} must be an object.`);
+		return undefined;
+	}
+	const name = validateString(value.name, `${path}.name`, errors)?.trim();
+	if (!name) {
+		errors.push(`${path}.name must not be blank.`);
+		return undefined;
+	}
+	const rawPolicy = validateString(value.policy, `${path}.policy`, errors);
+	const policy = rawPolicy ?? "authenticated-only";
+	if (!(["explicit-only", "authenticated-only", "always"] as const).includes(policy as BrowserDefaultProfilePolicy)) {
+		errors.push(`${path}.policy must be one of explicit-only, authenticated-only, always.`);
+		return undefined;
+	}
+	return { name, policy: policy as BrowserDefaultProfilePolicy };
+}
+
+function validateConfig(value: unknown, path: string, scope: ConfigLayer["scope"], errors: string[], warnings: string[]): AgentBrowserConfig | undefined {
+	if (!isRecord(value)) {
+		errors.push(`${path} must contain a JSON object.`);
+		return undefined;
+	}
+	if (value.version !== undefined && value.version !== 1) {
+		errors.push(`${path}.version must be 1 when present.`);
+	}
+	const config: AgentBrowserConfig = value.version === 1 ? { version: 1 } : {};
+
+	if (value.webSearch !== undefined) {
+		if (!isRecord(value.webSearch)) {
+			errors.push(`${path}.webSearch must be an object.`);
+		} else {
+			const braveApiKey = validateString(value.webSearch.braveApiKey, `${path}.webSearch.braveApiKey`, errors);
+			if (braveApiKey !== undefined) {
+				config.webSearch = { braveApiKey };
+				if (scope === "project" && !isProjectSafeCredentialValue(braveApiKey)) {
+					errors.push(`${path}.webSearch.braveApiKey must be exactly $ENV_VAR or ${"${ENV_VAR}"} in project-local config; plaintext, interpolation literals, malformed env references, and command-backed project secrets are not allowed.`);
+				}
+			}
+		}
+	}
+
+	if (value.browser !== undefined) {
+		if (!isRecord(value.browser)) {
+			errors.push(`${path}.browser must be an object.`);
+		} else {
+			config.browser = {};
+			const defaultProfile = validateBrowserDefaultProfile(value.browser.defaultProfile, `${path}.browser.defaultProfile`, errors);
+			if (defaultProfile) config.browser.defaultProfile = defaultProfile;
+			const defaultLaunchArgs = validateStringArray(value.browser.defaultLaunchArgs, `${path}.browser.defaultLaunchArgs`, errors);
+			if (defaultLaunchArgs) {
+				config.browser.defaultLaunchArgs = defaultLaunchArgs;
+				warnings.push(`${path}.browser.defaultLaunchArgs is recorded for future use; current releases do not auto-inject default launch args.`);
+			}
+		}
+	}
+
+	for (const key of Object.keys(value)) {
+		if (!["version", "webSearch", "browser"].includes(key)) {
+			warnings.push(`${path}.${key} is not a recognized pi-agent-browser-native config field and was ignored.`);
+		}
+	}
+	return config;
+}
+
+function parseConfigLayer(raw: string, path: string, scope: ConfigLayer["scope"], errors: string[], warnings: string[]): ConfigLayer | undefined {
+	let parsed: unknown;
+	try {
+		parsed = JSON.parse(raw);
+	} catch (error) {
+		errors.push(`Could not parse ${scope} config ${path}: ${error instanceof Error ? error.message : String(error)}`);
+		return undefined;
+	}
+	const config = validateConfig(parsed, path, scope, errors, warnings);
+	return config ? { config, path, scope } : undefined;
+}
+
+async function readConfigLayer(path: string, scope: ConfigLayer["scope"], errors: string[], warnings: string[]): Promise<ConfigLayer | undefined> {
+	let raw: string;
+	try {
+		raw = await readFile(path, "utf8");
+	} catch (error) {
+		if (error && typeof error === "object" && "code" in error && error.code === "ENOENT") {
+			return undefined;
+		}
+		errors.push(`Could not read ${scope} config ${path}: ${error instanceof Error ? error.message : String(error)}`);
+		return undefined;
+	}
+	return parseConfigLayer(raw, path, scope, errors, warnings);
+}
+
+function readConfigLayerSync(path: string, scope: ConfigLayer["scope"], errors: string[], warnings: string[]): ConfigLayer | undefined {
+	let raw: string;
+	try {
+		raw = readFileSync(path, "utf8");
+	} catch (error) {
+		if (error && typeof error === "object" && "code" in error && error.code === "ENOENT") {
+			return undefined;
+		}
+		errors.push(`Could not read ${scope} config ${path}: ${error instanceof Error ? error.message : String(error)}`);
+		return undefined;
+	}
+	return parseConfigLayer(raw, path, scope, errors, warnings);
+}
+
+export function isPlaintextCredentialValue(rawValue: string): boolean {
+	const trimmed = rawValue.trim();
+	return Boolean(trimmed) && !trimmed.startsWith("!") && !trimmed.startsWith("$");
+}
+
+export function isProjectSafeCredentialValue(rawValue: string): boolean {
+	const trimmed = rawValue.trim();
+	return /^\$[A-Za-z_][A-Za-z0-9_]*$/.test(trimmed) || /^\$\{[A-Za-z_][A-Za-z0-9_]*\}$/.test(trimmed);
+}
+
+export function classifyCredentialSource(rawValue: string, scope: AgentBrowserConfigScope): CredentialSource | undefined {
+	const trimmed = rawValue.trim();
+	if (!trimmed) return undefined;
+	if (trimmed.startsWith("!")) return { kind: "command", rawValue: trimmed, scope };
+	if (trimmed.includes("$")) return { kind: "env", rawValue: trimmed, scope };
+	return { kind: "literal", rawValue: trimmed, scope };
+}
+
+function getBrowserDefaultProfile(config: AgentBrowserConfig): Required<BrowserDefaultProfileConfig> | undefined {
+	const profile = config.browser?.defaultProfile;
+	if (!profile?.name.trim()) return undefined;
+	return { name: profile.name.trim(), policy: profile.policy ?? "authenticated-only" };
+}
+
+function buildConfigState(options: {
+	env: NodeJS.ProcessEnv;
+	layers: ConfigLayer[];
+	mergedConfig: AgentBrowserConfig;
+	paths: AgentBrowserConfigState["paths"];
+	errors: string[];
+	warnings: string[];
+}): AgentBrowserConfigState {
+	let credentialScope: AgentBrowserConfigScope = "global";
+	for (let index = options.layers.length - 1; index >= 0; index -= 1) {
+		const layer = options.layers[index];
+		if (layer?.config.webSearch?.braveApiKey !== undefined) {
+			credentialScope = layer.scope;
+			break;
+		}
+	}
+	let credentialSource = options.mergedConfig.webSearch?.braveApiKey === undefined
+		? undefined
+		: classifyCredentialSource(options.mergedConfig.webSearch.braveApiKey, credentialScope);
+	if (!credentialSource && options.env[BRAVE_API_KEY_ENV]?.trim()) {
+		credentialSource = { kind: "literal", rawValue: options.env[BRAVE_API_KEY_ENV] ?? "", scope: "env-fallback" };
+	}
+	return {
+		browserDefaultProfile: getBrowserDefaultProfile(options.mergedConfig),
+		config: options.mergedConfig,
+		credentialSource,
+		errors: options.errors,
+		layers: options.layers,
+		paths: options.paths,
+		warnings: options.warnings,
+	};
+}
+
+export async function loadAgentBrowserConfig(options: { cwd?: string; env?: NodeJS.ProcessEnv } = {}): Promise<AgentBrowserConfigState> {
+	const env = options.env ?? process.env;
+	const paths = getAgentBrowserConfigPaths({ cwd: options.cwd, env });
+	const errors: string[] = [];
+	const warnings: string[] = [];
+	const layerCandidates = [
+		{ path: paths.global, scope: "global" as const },
+		{ path: paths.project, scope: "project" as const },
+		...(paths.override ? [{ path: paths.override, scope: "override" as const }] : []),
+	];
+	const layers: ConfigLayer[] = [];
+	let mergedConfig: AgentBrowserConfig = {};
+	for (const candidate of layerCandidates) {
+		const layer = await readConfigLayer(candidate.path, candidate.scope, errors, warnings);
+		if (!layer) continue;
+		layers.push(layer);
+		mergedConfig = mergeConfig(mergedConfig, layer.config);
+	}
+	return buildConfigState({ env, errors, layers, mergedConfig, paths, warnings });
+}
+
+export function loadAgentBrowserConfigSync(options: { cwd?: string; env?: NodeJS.ProcessEnv } = {}): AgentBrowserConfigState {
+	const env = options.env ?? process.env;
+	const paths = getAgentBrowserConfigPaths({ cwd: options.cwd, env });
+	const errors: string[] = [];
+	const warnings: string[] = [];
+	const layerCandidates = [
+		{ path: paths.global, scope: "global" as const },
+		{ path: paths.project, scope: "project" as const },
+		...(paths.override ? [{ path: paths.override, scope: "override" as const }] : []),
+	];
+	const layers: ConfigLayer[] = [];
+	let mergedConfig: AgentBrowserConfig = {};
+	for (const candidate of layerCandidates) {
+		const layer = readConfigLayerSync(candidate.path, candidate.scope, errors, warnings);
+		if (!layer) continue;
+		layers.push(layer);
+		mergedConfig = mergeConfig(mergedConfig, layer.config);
+	}
+	return buildConfigState({ env, errors, layers, mergedConfig, paths, warnings });
+}
+
+function resolveEnvInterpolations(rawValue: string, env: NodeJS.ProcessEnv): string | undefined {
+	let output = "";
+	for (let index = 0; index < rawValue.length; index += 1) {
+		const char = rawValue[index];
+		if (char !== "$") {
+			output += char;
+			continue;
+		}
+		const next = rawValue[index + 1];
+		if (next === "$") {
+			output += "$";
+			index += 1;
+			continue;
+		}
+		if (next === "!") {
+			output += "!";
+			index += 1;
+			continue;
+		}
+		let name = "";
+		if (next === "{") {
+			const end = rawValue.indexOf("}", index + 2);
+			if (end === -1) return undefined;
+			name = rawValue.slice(index + 2, end);
+			index = end;
+		} else {
+			const match = rawValue.slice(index + 1).match(/^([A-Za-z_][A-Za-z0-9_]*)/);
+			if (!match) {
+				output += "$";
+				continue;
+			}
+			name = match[1] ?? "";
+			index += name.length;
+		}
+		if (!name) return undefined;
+		const value = env[name];
+		if (value === undefined) return undefined;
+		output += value;
+	}
+	return output;
+}
+
+async function resolveCommandCredential(rawValue: string, signal?: AbortSignal): Promise<string | undefined> {
+	const command = rawValue.slice(1).trim();
+	if (!command) return undefined;
+	try {
+		const result = await exec(command, {
+			signal,
+			timeout: SECRET_COMMAND_TIMEOUT_MS,
+			maxBuffer: 1024 * 1024,
+		});
+		const value = result.stdout.trim();
+		return value.length > 0 ? value : undefined;
+	} catch (error) {
+		if (signal?.aborted) throw error;
+		throw new Error("Credential command failed without exposing command output. Check pi-agent-browser-config web-search status and the configured secret manager command.");
+	}
+}
+
+export async function resolveCredentialSource(
+	source: CredentialSource | undefined,
+	options: { env?: NodeJS.ProcessEnv; signal?: AbortSignal } = {},
+): Promise<ResolvedCredential | undefined> {
+	if (!source) return undefined;
+	let value: string | undefined;
+	if (source.kind === "command") {
+		value = await resolveCommandCredential(source.rawValue, options.signal);
+	} else if (source.kind === "env") {
+		value = resolveEnvInterpolations(source.rawValue, options.env ?? process.env)?.trim();
+	} else {
+		value = source.rawValue.trim();
+	}
+	return value ? { source, value } : undefined;
+}
+
+export async function resolveBraveApiKey(
+	state: AgentBrowserConfigState,
+	options: { env?: NodeJS.ProcessEnv; signal?: AbortSignal } = {},
+): Promise<ResolvedCredential | undefined> {
+	return resolveCredentialSource(state.credentialSource, options);
+}
+
+export function canRegisterWebSearchTool(state: AgentBrowserConfigState, env: NodeJS.ProcessEnv = process.env): boolean {
+	if (!state.credentialSource || state.errors.length > 0) return false;
+	if (state.credentialSource.kind === "command") return true;
+	if (state.credentialSource.kind === "env") return Boolean(resolveEnvInterpolations(state.credentialSource.rawValue, env)?.trim());
+	return Boolean(state.credentialSource.rawValue.trim());
+}
+
+export async function hasResolvableCredentialSource(
+	state: AgentBrowserConfigState,
+	options: { env?: NodeJS.ProcessEnv } = {},
+): Promise<boolean> {
+	if (!state.credentialSource || state.errors.length > 0) return false;
+	if (state.credentialSource.kind === "command") return true;
+	return Boolean((await resolveCredentialSource(state.credentialSource, options))?.value);
+}
+
+export function getCredentialSourceSummary(source: CredentialSource | undefined): string {
+	if (!source) return "not configured";
+	if (source.kind === "command") return `configured via command (${source.scope})`;
+	if (source.kind === "env") return `configured via environment interpolation (${source.scope})`;
+	if (source.scope === "env-fallback") return `configured via ${BRAVE_API_KEY_ENV} environment fallback`;
+	return `configured as plaintext ${source.scope} value [redacted]`;
+}

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

@@ -30,7 +30,7 @@ export const QUICK_START_GUIDELINES = [
 ] as const;
 
 export const BRAVE_SEARCH_PROMPT_GUIDELINE =
-	"When a non-empty BRAVE_API_KEY is available in the current environment, prefer the Brave Search API via bash/curl to discover specific destination URLs, then open the chosen URL with agent_browser instead of browsing a search engine results page just to find the target.";
+	"When agent_browser_web_search is available, use it for live web search when current or external web information would help; use agent_browser when the task needs browser interaction, page inspection, screenshots, authenticated/profile content, or DOM work.";
 
 export const SHARED_BROWSER_PLAYBOOK_GUIDELINES = [
 	"Standard workflow: open the page, snapshot -i, interact using current @refs from that snapshot, and re-snapshot after navigation, scrolling, rerendering, or other major DOM changes because refs are page-scoped; the wrapper fails mutation-prone stale/recycled refs before upstream can silently target a different current-page element.",
@@ -51,7 +51,7 @@ export const SHARED_BROWSER_PLAYBOOK_GUIDELINES = [
 	"For Electron desktop apps, prefer top-level electron for wrapper-owned discovery, isolated launch, status, compact probe, and cleanup: list first, treat likely-sensitive annotations as hints rather than enforcement, launch with the default snapshot handoff unless handoff: \"tabs\" is the safer diagnostic starting point, use electron.probe or snapshot -i/qa.attached for current-session state, and always cleanup the returned launchId when done. electron.launch uses an isolated temporary profile; it does not reuse the app's normal signed-in profile or attach to an already-running authenticated app. For signed-in local app state, host-launch the normal app with --remote-debugging-port when appropriate, then use raw args connect <port|url>; after connect, inspect tab list, select the stable tab id such as tab t2, then run a condition wait or snapshot -i before using refs. close commands (`close`, `quit`, or `exit`) only close the browser/CDP session; leave manually launched app shutdown, profile cleanup, and explicit artifacts to the host owner.",
 	"For provider or specialized app workflows, load version-matched upstream guidance with skills get agentcore|electron|slack|dogfood|vercel-sandbox through the native tool; add --full when you need references/templates, and use skills get --all only for broad skill audits. Provider launches such as -p ios, --provider browserbase/kernel/browseruse/browserless/agentcore, and iOS --device are upstream-owned setup paths; use sessionMode fresh when switching providers and expect external credentials or local Appium/Xcode setup to be required.",
 	"For dialogs and frames, use dialog status/accept/dismiss and frame <selector|main> through native args; when --confirm-actions produces a pending confirmation, use details.nextActions or exact confirm <id> / deny <id> calls instead of inventing ids.",
-	"If a session lands on the wrong page or tab, an interaction changes origin unexpectedly, or an open call returns blocked, blank, or otherwise unexpected results, use tab list / tab <tab-id-or-label> / snapshot -i to recover state before retrying different URLs or fallback strategies. For headed demos, put --headed on the first launch with sessionMode=fresh and verify with screenshot/tab/get-url evidence because tool success cannot prove the OS window is visible to the user. For desktop readiness, prefer real conditions first: wait --text, wait --url, wait --fn, wait --load <state>, wait --download, or qa.attached; for disappearance checks in agent-browser 0.27.0, use wait --fn predicates instead of stale upstream-help examples like wait <selector> --state hidden. Use electron.probe/status for wrapper-owned launch health or target mismatch. Fixed waits are a last resort, must stay below the wrapper IPC budget (wait 30000 is intentionally blocked), and a successful payload like \"waited\":\"timeout\" means elapsed time only—verify completion with an observed condition, fresh snapshot, or screenshot.",
+	"If a session lands on the wrong page or tab, an interaction changes origin unexpectedly, or an open call returns blocked, blank, or otherwise unexpected results, use tab list / tab <tab-id-or-label> / snapshot -i to recover state before retrying different URLs or fallback strategies. For headed demos, put --headed on the first launch with sessionMode=fresh and verify with screenshot/tab/get-url evidence because tool success cannot prove the OS window is visible to the user. For desktop readiness, prefer real conditions first: wait --text, wait --url, wait --fn, wait --load <state>, wait --download, or qa.attached; for disappearance checks in agent-browser 0.27.1, use wait --fn predicates instead of stale upstream-help examples like wait <selector> --state hidden. Use electron.probe/status for wrapper-owned launch health or target mismatch. Fixed waits are a last resort, must stay below the wrapper IPC budget (wait 30000 is intentionally blocked), and a successful payload like \"waited\":\"timeout\" means elapsed time only—verify completion with an observed condition, fresh snapshot, or screenshot.",
 	"For feed, timeline, or inbox reading tasks, focus on the main timeline/list region and read the first item there rather than unrelated composer or sidebar content.",
 	"For read-only browsing tasks, prefer extracting the answer from the current snapshot, structured ref labels, or eval --stdin on the current page before navigating away. Only click into media viewers, detail routes, or new pages when the current view does not contain the needed information.",
 	"For downloads, prefer download <selector> <path> when an element click should save a file. Do not rely on click alone when you need the downloaded file on disk.",
@@ -105,11 +105,25 @@ export const RUNTIME_PROMPT_GUIDELINES = [
 	"For extraction, prefer get title/url/text/html/value/attr/count or eval --stdin with plain expression, not console.log. Batch three or more known refs/selectors (e.g. [[\"get\",\"text\",\"@e1\"],[\"get\",\"text\",\"@e2\"]]); selector visibility warnings → visible @refs/nextActions.",
 ] as const;
 
-export function buildToolPromptGuidelines(options: { includeBraveSearch: boolean; docs?: { readmePath: string; commandReferencePath: string; toolContractPath: string } }): string[] {
+export function buildBrowserDefaultProfileGuideline(profile: { name: string; policy: "explicit-only" | "authenticated-only" | "always" } | undefined): string | undefined {
+	if (!profile || profile.policy === "explicit-only") return undefined;
+	if (profile.policy === "always") {
+		return `Agent-browser config sets browser.defaultProfile.name to ${JSON.stringify(profile.name)} with policy always; use --profile ${JSON.stringify(profile.name)} with sessionMode:fresh when a fresh browser launch should use the configured profile, and treat profile content as model-visible user data.`;
+	}
+	return `Agent-browser config sets browser.defaultProfile.name to ${JSON.stringify(profile.name)}; for signed-in/account-specific browser tasks, start with --profile ${JSON.stringify(profile.name)} plus sessionMode:fresh unless the user asks for a different profile.`;
+}
+
+export function buildToolPromptGuidelines(options: {
+	browserDefaultProfile?: { name: string; policy: "explicit-only" | "authenticated-only" | "always" };
+	docs?: { readmePath: string; commandReferencePath: string; toolContractPath: string };
+	includeBraveSearch: boolean;
+}): string[] {
+	const browserDefaultProfileGuideline = buildBrowserDefaultProfileGuideline(options.browserDefaultProfile);
 	return [
 		...TOOL_PROMPT_GUIDELINES_PREFIX,
 		...(options.docs ? [buildInstalledDocsGuideline(options.docs)] : []),
 		...RUNTIME_PROMPT_GUIDELINES,
+		...(browserDefaultProfileGuideline ? [browserDefaultProfileGuideline] : []),
 		...(options.includeBraveSearch ? [BRAVE_SEARCH_PROMPT_GUIDELINE] : []),
 		TOOL_PROMPT_GUIDELINES_SUFFIX[0],
 		TOOL_PROMPT_GUIDELINES_SUFFIX[1],

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

@@ -1,15 +1,16 @@
 /**
  * Purpose: Execute the upstream agent-browser binary for the pi-agent-browser extension.
- * Responsibilities: Spawn the agent-browser subprocess without a shell, forward a curated environment surface, stream optional stdin, bound in-memory output buffering, spill oversized stdout safely to a private temp file under a disk budget, and honor abort signals.
+ * Responsibilities: Spawn the agent-browser subprocess, forward a curated environment surface, stream optional stdin, bound in-memory output buffering, spill oversized stdout safely to a private temp file under a disk budget, and honor abort signals.
  * Scope: Process execution only; argument planning, output formatting, and pi tool registration live elsewhere.
  * Usage: Called by the extension tool after argument validation and session planning are complete.
- * Invariants/Assumptions: The binary name is always `agent-browser`, the wrapper never shells out, and callers handle semantic success/error interpretation.
+ * Invariants/Assumptions: The binary name is always `agent-browser`; Windows routes through PowerShell to invoke npm launchers with escaped argv; callers handle semantic success/error interpretation.
  */
 
 import { type ChildProcessWithoutNullStreams, spawn } from "node:child_process";
 import { chmod, mkdir } from "node:fs/promises";
 import { env as processEnv, platform as processPlatform } from "node:process";
 
+import { GLOBAL_BOOLEAN_FLAGS_WITH_OPTIONAL_VALUES, GLOBAL_VALUE_FLAGS, getFlagName } from "./argv-grammar.js";
 import { openSecureTempFile, writeSecureTempChunk } from "./temp.js";
 
 const MAX_BUFFERED_STDOUT_BYTES = 512 * 1_024;
@@ -107,6 +108,52 @@ function appendTail(text: string, addition: string, maxChars: number): string {
 	return combined.length <= maxChars ? combined : combined.slice(combined.length - maxChars);
 }
 
+function quoteWindowsPowerShellArg(value: string): string {
+	return `'${value.replace(/'/g, "''")}'`;
+}
+
+const WINDOWS_LEADING_GLOBAL_VALUE_FLAGS = new Set<string>(GLOBAL_VALUE_FLAGS);
+
+/** Exported for unit tests that lock Windows launcher argv ordering. */
+export function reorderWindowsLeadingGlobalArgs(args: string[]): string[] {
+	const leadingGlobals: string[] = [];
+	let index = 0;
+	while (index < args.length && args[index]?.startsWith("-")) {
+		const token = args[index];
+		const flagName = getFlagName(token);
+		leadingGlobals.push(token);
+		index += 1;
+		if (WINDOWS_LEADING_GLOBAL_VALUE_FLAGS.has(flagName) && !token.includes("=") && index < args.length) {
+			leadingGlobals.push(args[index]);
+			index += 1;
+			continue;
+		}
+		if (GLOBAL_BOOLEAN_FLAGS_WITH_OPTIONAL_VALUES.has(flagName) && ["true", "false"].includes(args[index] ?? "")) {
+			leadingGlobals.push(args[index]);
+			index += 1;
+		}
+	}
+	if (leadingGlobals.length === 0 || index >= args.length) return args;
+	return [args[index], ...leadingGlobals, ...args.slice(index + 1)];
+}
+
+function buildAgentBrowserSpawnCommand(args: string[]): { command: string; args: string[] } {
+	if (processPlatform !== "win32") {
+		return { command: "agent-browser", args };
+	}
+	const commandLine = ["&", "agent-browser", ...reorderWindowsLeadingGlobalArgs(args).map(quoteWindowsPowerShellArg)].join(" ");
+	return { command: "powershell.exe", args: ["-NoLogo", "-NoProfile", "-ExecutionPolicy", "Bypass", "-Command", commandLine] };
+}
+
+function terminateSpawnedChild(child: ChildProcessWithoutNullStreams, signal: NodeJS.Signals): void {
+	if (processPlatform === "win32" && child.pid) {
+		const killer = spawn("taskkill.exe", ["/PID", String(child.pid), "/T", "/F"], { stdio: "ignore" });
+		killer.on("error", () => undefined);
+		killer.unref();
+	}
+	child.kill(signal);
+}
+
 /** Exported for unit tests that lock subprocess exit-code precedence. */
 export function resolveSpawnedChildExitCode(input: {
 	closeCode?: number | null;
@@ -234,17 +281,27 @@ async function ensureAgentBrowserSocketDir(socketDir: string): Promise<boolean>
 	}
 }
 
+function getChildEnvName(name: string): string | undefined {
+	if (processPlatform === "win32") {
+		const upperName = name.toUpperCase();
+		if (INHERITED_ENV_NAMES.has(upperName)) return upperName;
+		return INHERITED_ENV_PREFIXES.some((prefix) => upperName.startsWith(prefix)) ? upperName : undefined;
+	}
+	if (INHERITED_ENV_NAMES.has(name) || INHERITED_ENV_PREFIXES.some((prefix) => name.startsWith(prefix))) {
+		return name;
+	}
+	return undefined;
+}
+
 export function buildAgentBrowserProcessEnv(
 	baseEnv: NodeJS.ProcessEnv = processEnv,
 	overrides: NodeJS.ProcessEnv | undefined = undefined,
 ): NodeJS.ProcessEnv {
 	const childEnv: NodeJS.ProcessEnv = {};
 	for (const [name, value] of Object.entries(baseEnv)) {
-		if (
-			value !== undefined &&
-			(INHERITED_ENV_NAMES.has(name) || INHERITED_ENV_PREFIXES.some((prefix) => name.startsWith(prefix)))
-		) {
-			childEnv[name] = value;
+		const childName = getChildEnvName(name);
+		if (value !== undefined && childName) {
+			childEnv[childName] = value;
 		}
 	}
 
@@ -254,10 +311,11 @@ export function buildAgentBrowserProcessEnv(
 	}
 
 	for (const [name, value] of Object.entries(overrides)) {
+		const childName = getChildEnvName(name) ?? name;
 		if (value === undefined) {
-			delete childEnv[name];
+			delete childEnv[childName];
 		} else {
-			childEnv[name] = value;
+			childEnv[childName] = value;
 		}
 	}
 	clampUpstreamDefaultTimeout(childEnv);
@@ -371,7 +429,8 @@ export async function runAgentBrowserProcess(options: {
 			});
 		};
 
-		const child = spawn("agent-browser", args, {
+		const spawnCommand = buildAgentBrowserSpawnCommand(args);
+		const child = spawn(spawnCommand.command, spawnCommand.args, {
 			cwd,
 			env: buildAgentBrowserProcessEnv(processEnv, effectiveEnv),
 			stdio: ["pipe", "pipe", "pipe"],
@@ -384,15 +443,15 @@ export async function runAgentBrowserProcess(options: {
 			} else {
 				timedOut = true;
 			}
-			child.kill("SIGTERM");
+			terminateSpawnedChild(child, "SIGTERM");
 			killTimer = setTimeout(() => {
-				child.kill("SIGKILL");
+				terminateSpawnedChild(child, "SIGKILL");
 			}, 2_000);
 		};
 		const recordStdinError = (error: unknown) => {
 			const stdinError = error instanceof Error ? error : new Error(String(error));
 			const errorCode = (stdinError as NodeJS.ErrnoException).code;
-			if (errorCode === "EPIPE" || errorCode === "ERR_STREAM_DESTROYED") {
+			if (errorCode === "EPIPE" || errorCode === "EOF" || errorCode === "ERR_STREAM_DESTROYED") {
 				return;
 			}
 			if (!spawnError) {