pi-agent-browser-native 0.2.39 → 0.2.41

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

@@ -0,0 +1,198 @@
+/**
+ * Purpose: Load pi-agent-browser-native package configuration from Pi-scoped global, project, or explicit paths.
+ * Responsibilities: Resolve config layers, resolve secrets without exposing values, and provide redacted status for tools/CLIs.
+ * Scope: Package-owned configuration only; canonical config policy lives in config-policy.js, browser command execution and web-search API calls live in focused modules.
+ * Invariants/Assumptions: Raw project-local plaintext credentials are unsafe and rejected by the shared config policy; command credentials are resolved lazily at execution time.
+ */
+
+import { exec as execCallback } from "node:child_process";
+import { readFile } from "node:fs/promises";
+import { promisify } from "node:util";
+
+import {
+	SECRET_COMMAND_TIMEOUT_MS,
+	buildAgentBrowserConfigState,
+	getAgentBrowserConfigPaths,
+	getWebSearchCredentialSource,
+	getWebSearchProviderOrder,
+	loadAgentBrowserConfigStateSync,
+	mergeAgentBrowserConfig,
+	parseAgentBrowserConfigLayer,
+	resolveEnvInterpolations,
+} from "./config-policy.js";
+import type {
+	AgentBrowserConfig,
+	AgentBrowserConfigScope,
+	AgentBrowserConfigState,
+	BrowserDefaultProfileConfig,
+	BrowserDefaultProfilePolicy,
+	ConfigLayer,
+	CredentialSource,
+	CredentialSourceKind,
+	WebSearchProvider,
+} from "./config-policy.js";
+
+export {
+	AGENT_BROWSER_CONFIG_ENV,
+	BRAVE_API_KEY_ENV,
+	CONFIG_RELATIVE_PATH,
+	DEFAULT_WEB_SEARCH_PROVIDER,
+	EXA_API_KEY_ENV,
+	GLOBAL_CONFIG_RELATIVE_PATH,
+	SECRET_COMMAND_TIMEOUT_MS,
+	WEB_SEARCH_PROVIDER_CONFIG_KEYS,
+	WEB_SEARCH_PROVIDER_DESCRIPTORS,
+	WEB_SEARCH_PROVIDER_ENV_VARS,
+	WEB_SEARCH_PROVIDERS,
+	buildAgentBrowserConfigState,
+	buildWebSearchCredentialSources,
+	canRegisterWebSearchTool,
+	classifyCredentialSource,
+	formatBrowserExecutableStatus,
+	formatBrowserProfileStatus,
+	getAgentBrowserConfigPaths,
+	getCredentialSourceSummary,
+	getGlobalAgentBrowserConfigPath,
+	getProjectAgentBrowserConfigPath,
+	getWebSearchCredentialSource,
+	getWebSearchProviderConfigKey,
+	getWebSearchProviderDescriptor,
+	getWebSearchProviderEnvVar,
+	getWebSearchProviderLabel,
+	getWebSearchProviderOrder,
+	hasPotentialCredentialSource,
+	isPlaintextCredentialValue,
+	isProjectSafeCredentialValueForProvider,
+	isWebSearchProvider,
+	loadAgentBrowserConfigStateSync,
+	mergeAgentBrowserConfig,
+	parseAgentBrowserConfigLayer,
+	resolveEnvInterpolations,
+	summarizeConfigFiles,
+	validateAgentBrowserConfig,
+	validateWebSearchProvider,
+} from "./config-policy.js";
+export type {
+	AgentBrowserConfig,
+	AgentBrowserConfigScope,
+	AgentBrowserConfigState,
+	BrowserDefaultProfileConfig,
+	BrowserDefaultProfilePolicy,
+	ConfigLayer,
+	CredentialSource,
+	CredentialSourceKind,
+	WebSearchProvider,
+	WebSearchProviderDescriptor,
+} from "./config-policy.js";
+
+const exec = promisify(execCallback);
+
+export interface ResolvedCredential {
+	source: CredentialSource;
+	value: string;
+}
+
+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 parseAgentBrowserConfigLayer(raw, path, scope, errors, 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 = mergeAgentBrowserConfig(mergedConfig, layer.config);
+	}
+	return buildAgentBrowserConfigState({ env, errors, layers, mergedConfig, paths, warnings });
+}
+
+export function loadAgentBrowserConfigSync(options: { cwd?: string; env?: NodeJS.ProcessEnv } = {}): AgentBrowserConfigState {
+	return loadAgentBrowserConfigStateSync(options);
+}
+
+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 resolveWebSearchCredential(
+	state: AgentBrowserConfigState,
+	provider: WebSearchProvider,
+	options: { env?: NodeJS.ProcessEnv; signal?: AbortSignal } = {},
+): Promise<ResolvedCredential | undefined> {
+	return resolveCredentialSource(getWebSearchCredentialSource(state, provider), options);
+}
+
+export async function resolvePreferredWebSearchCredential(
+	state: AgentBrowserConfigState,
+	options: { env?: NodeJS.ProcessEnv; provider?: WebSearchProvider | "auto"; signal?: AbortSignal } = {},
+): Promise<{ provider: WebSearchProvider; credential: ResolvedCredential } | undefined> {
+	for (const provider of getWebSearchProviderOrder(state, options.provider)) {
+		const credential = await resolveWebSearchCredential(state, provider, options);
+		if (credential) return { provider, credential };
+	}
+	return undefined;
+}
+
+export async function hasResolvableCredentialSource(
+	state: AgentBrowserConfigState,
+	options: { env?: NodeJS.ProcessEnv } = {},
+): Promise<boolean> {
+	if (!state.webSearchEnabled || state.errors.length > 0) return false;
+	for (const provider of getWebSearchProviderOrder(state)) {
+		const source = getWebSearchCredentialSource(state, provider);
+		if (!source) continue;
+		if (source.kind === "command") return true;
+		if ((await resolveCredentialSource(source, options))?.value) return true;
+	}
+	return false;
+}

package/extensions/agent-browser/lib/input-modes/params.ts

@@ -181,7 +181,7 @@ export const AGENT_BROWSER_PARAMS = Type.Object({
 	sessionMode: Type.Optional(
 		StringEnum(["auto", "fresh"] as const, {
 			description:
-				"Session handling mode. `auto` reuses the extension-managed pi-scoped session when possible. `fresh` switches that managed session to a fresh upstream launch so launch-scoped flags like --profile, --session-name, --cdp, --state, --auto-connect, --init-script, --enable, -p/--provider, or iOS --device apply and later auto calls follow the new browser.",
+				"Session handling mode. `auto` reuses the extension-managed pi-scoped session when possible. `fresh` switches that managed session to a fresh upstream launch so launch-scoped flags like --profile, --executable-path, --session-name, --cdp, --state, --auto-connect, --init-script, --enable, -p/--provider, or iOS --device apply and later auto calls follow the new browser.",
 			default: DEFAULT_SESSION_MODE,
 		}),
 	),

package/extensions/agent-browser/lib/launch-scoped-flags.ts

@@ -0,0 +1,67 @@
+/**
+ * Purpose: Canonical launch-scoped agent-browser flag metadata shared by runtime planning and agent-facing guidance.
+ * Responsibilities: Define which upstream flags require a fresh launch, explain why, and expose stable guidance labels.
+ * Scope: Metadata only; argv parsing and execution planning live in runtime.ts.
+ */
+
+export interface LaunchScopedFlagDefinition {
+	flag: string;
+	reason: string;
+}
+
+export const LAUNCH_SCOPED_FLAG_DEFINITIONS = [
+	{
+		flag: "--auto-connect",
+		reason: "attaches to an already-running browser at launch time instead of reusing an existing named session",
+	},
+	{
+		flag: "--cdp",
+		reason: "selects the browser/CDP endpoint used when an upstream session is launched",
+	},
+	{
+		flag: "--enable",
+		reason: "selects built-in page init scripts before the upstream browser session is launched",
+	},
+	{
+		flag: "--executable-path",
+		reason: "selects the browser executable used for the upstream launch",
+	},
+	{
+		flag: "--init-script",
+		reason: "registers page init scripts before the upstream browser session is launched",
+	},
+	{
+		flag: "--device",
+		reason: "selects the provider device for the upstream launch",
+	},
+	{
+		flag: "--profile",
+		reason: "selects Chrome profile state for the upstream launch",
+	},
+	{
+		flag: "--provider",
+		reason: "selects the upstream browser provider for the launch",
+	},
+	{
+		flag: "-p",
+		reason: "selects the upstream browser provider for the launch",
+	},
+	{
+		flag: "--session-name",
+		reason: "selects upstream saved auth/session state for the launch",
+	},
+	{
+		flag: "--state",
+		reason: "loads persisted upstream browser/auth state at launch time",
+	},
+] as const satisfies readonly LaunchScopedFlagDefinition[];
+
+export const LAUNCH_SCOPED_FLAGS = LAUNCH_SCOPED_FLAG_DEFINITIONS.map((definition) => definition.flag);
+export const LAUNCH_SCOPED_FLAG_LABEL = LAUNCH_SCOPED_FLAGS.join(", ");
+
+/**
+ * The subset of launch-scoped flags that can restore browser/auth state with pre-existing tabs
+ * and are plausible wrong-active-tab sources after a fresh launch. These trigger post-open
+ * tab-correction (the `tab list` + re-select cycle).
+ */
+export const LAUNCH_SCOPED_TAB_CORRECTION_FLAGS = new Set(["--profile", "--session-name", "--state"] as const);

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

@@ -1,3 +1,5 @@
+import { LAUNCH_SCOPED_FLAG_LABEL } from "./launch-scoped-flags.js";
+
 /**
  * Purpose: Provide the canonical agent_browser operating playbook shared by runtime prompt metadata and generated documentation fragments.
  * Responsibilities: Define stable guidance bullets, native tool-call examples, and wrapper-behavior notes without importing runtime/browser process code.
@@ -18,7 +20,7 @@ export function buildInstalledDocsGuideline(paths: { readmePath: string; command
 }
 
 export const QUICK_START_GUIDELINES = [
-	"Quick start mental model: use exactly one of args (exact agent-browser CLI args after the binary), semanticAction (a thin shorthand compiled to find argv for locator actions or select argv for native dropdowns), job (a constrained short-workflow schema compiled to batch), qa (a lightweight QA preset built on job/batch, including qa.attached for current sessions), electron (desktop Electron list/launch/status/cleanup/probe), or the experimental sourceLookup / networkSourceLookup helpers (candidates only; each compiled to batch); stdin is only for batch, eval --stdin, auth save --password-stdin, and wrapper-generated batch stdin from job, qa, sourceLookup, or networkSourceLookup, and is rejected with electron; sessionMode=fresh switches the extension-managed pi-scoped session to a fresh upstream launch when you need new --profile, --session-name, --cdp, --state, --auto-connect, --init-script, --enable, -p/--provider, or iOS --device state. Do not pass --json in args; the wrapper injects it.",
+	`Quick start mental model: use exactly one of args (exact agent-browser CLI args after the binary), semanticAction (a thin shorthand compiled to find argv for locator actions or select argv for native dropdowns), job (a constrained short-workflow schema compiled to batch), qa (a lightweight QA preset built on job/batch, including qa.attached for current sessions), electron (desktop Electron list/launch/status/cleanup/probe), or the experimental sourceLookup / networkSourceLookup helpers (candidates only; each compiled to batch); stdin is only for batch, eval --stdin, auth save --password-stdin, and wrapper-generated batch stdin from job, qa, sourceLookup, or networkSourceLookup, and is rejected with electron; sessionMode=fresh switches the extension-managed pi-scoped session to a fresh upstream launch when you need new launch-scoped flags (${LAUNCH_SCOPED_FLAG_LABEL}) to apply. Do not pass --json in args; the wrapper injects it.`,
 	"There is no first-class reusable named browser recipe runtime above top-level job, the qa preset, and raw batch stdin; keep recurring flows in documentation examples or those inputs (closed RQ-0068; see docs/ARCHITECTURE.md#no-reusable-recipe-layer-yet).",
 	"Common first calls (first-call recipe): { args: [\"open\", \"<url>\"] } → { args: [\"snapshot\", \"-i\"] } → { args: [\"click\", \"@eN\"] } or { args: [\"fill\", \"@eN\", \"<text>\"] } using @refs and visible labels from that snapshot, then { args: [\"snapshot\", \"-i\"] } after navigation or DOM changes. On https://example.com/ the main link label is Learn more (use exact snapshot text, not guessed link copy).",
 	"Locator-first clicks/fills and native select changes without hand-building argv: { semanticAction: { action: \"click\", locator: \"text\", value: \"Close\" } }, { semanticAction: { action: \"fill\", locator: \"label\", value: \"Email\", text: \"user@example.com\" } }, or { semanticAction: { action: \"select\", selector: \"#flavor\", value: \"chocolate\" } }; add semanticAction.session when targeting a named upstream browser session; details.compiledSemanticAction shows the semantic target, while details.effectiveArgs may show a resolved current @ref for active-session role/name click/check/uncheck actions to avoid hidden duplicate matches; selector-not-found failures may append bounded click try-*-candidate next actions or, for fill misses with current editable refs, details.richInputRecovery with focus/click actions that do not copy fill text; stale-ref failures can return retry-semantic-action-after-stale-ref for compiled find actions when retry safety is provable.",
@@ -29,8 +31,9 @@ export const QUICK_START_GUIDELINES = [
 	"When details.nextActions is present, prefer those exact native agent_browser follow-up payloads over prose guidance; they may include args, stdin, sessionMode, networkSourceLookup, safety notes, or artifactPath for saved files.",
 ] as const;
 
-export const BRAVE_SEARCH_PROMPT_GUIDELINE =
-	"With BRAVE_API_KEY set, use Brave Search via bash/curl to find exact destination URLs, then open the chosen URL with agent_browser; do not browse search results just to locate a target.";
+export const WEB_SEARCH_PROMPT_GUIDELINE =
+	"Use agent_browser_web_search for quick live search/URL discovery; it chooses Exa or Brave, preferring Exa unless configured otherwise. Use agent_browser for interaction/DOM/screenshots/auth. Do not run parallel searches: one good query, inspect results, then one follow-up max; on HTTP 429 stop and report provider limits.";
+
 
 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.",
@@ -39,10 +42,10 @@ export const SHARED_BROWSER_PLAYBOOK_GUIDELINES = [
 	"When a visible text or accessible-name target should survive ref churn, prefer find locators such as role, text, label, placeholder, alt, title, or testid with the intended action instead of guessing a CSS selector.",
 	"For desktop or host-controlled rich inputs, if semanticAction fill misses, refresh refs and prefer a current editable @ref from details.richInputRecovery or the latest snapshot; focus or click that ref, then use keyboard inserttext or keyboard type with the intended text. Do not auto-submit with Enter or a submit button unless the user flow explicitly calls for it.",
 	"Do not assume Playwright selector dialects such as text=Close or button:has-text('Close') are supported wrapper syntax unless current upstream agent-browser behavior has been verified.",
-	"For authenticated or user-specific content explicitly requested by the user, such as feeds, inboxes, account pages, or private dashboards, prefer --profile Default on the first browser call and let the implicit session carry continuity. Do not use a real profile for public pages just because they are dashboards. Treat visible page content from real profiles as model-visible transcript data; use --auto-connect only if profile-based reuse is unavailable or the task is specifically about attaching to a running debug-enabled browser.",
+	"For authenticated or user-specific content explicitly requested by the user, such as feeds, inboxes, account pages, or private dashboards, use a real profile only when the user/config asks for it or profiles have been inspected; do not assume --profile Default exists on every machine. Do not use a real profile for public pages just because they are dashboards. Treat visible page content from real profiles as model-visible transcript data; use --auto-connect only if profile-based reuse is unavailable or the task is specifically about attaching to a running debug-enabled browser. If profile/user-data-dir resolution fails, stop retrying opens, run profiles and/or doctor through agent_browser, then report what the user needs to configure.",
 	"Do not invent fixed explicit session names for routine tasks. Use the implicit session unless you truly need multiple isolated browser sessions in the same conversation.",
-	"When using --profile, --session-name, --cdp, --state, --auto-connect, --init-script, --enable, -p/--provider, or iOS --device, put them on the first command for that session. If you intentionally use an explicit --session, keep using that same explicit session for follow-ups.",
-	"If you already used the implicit session and now need launch-scoped flags like --profile, --session-name, --cdp, --state, --auto-connect, --init-script, --enable, -p/--provider, or iOS --device, retry with sessionMode set to fresh or pass an explicit --session for the new launch. After a successful unnamed fresh launch, later auto calls follow that new session.",
+	`When using launch-scoped flags (${LAUNCH_SCOPED_FLAG_LABEL}), put them on the first command for that session. If you intentionally use an explicit --session, keep using that same explicit session for follow-ups.`,
+	`If you already used the implicit session and now need launch-scoped flags (${LAUNCH_SCOPED_FLAG_LABEL}), retry with top-level sessionMode set to fresh or pass an explicit --session for the new launch; never pass --session-mode inside args. After a successful unnamed fresh launch, later auto calls follow that new session.`,
 	"For React introspection, launch the page with --enable react-devtools before first navigation, then use react tree, react inspect <fiberId>, sourceLookup candidates for local UI source hints, react renders start/stop, or react suspense; sourceLookup is experimental and reports confidence/evidence instead of guaranteed DOM-to-file mappings. For failed fetches and APIs, networkSourceLookup (experimental) correlates failed network requests with initiator metadata and bounded workspace URL literals—candidates only, not definitive blame. Use vitals [url] for Core Web Vitals and hydration timing, and pushstate <url> for client-side SPA navigation.",
 	"For first-navigation setup, use open without a URL plus network route --resource-type <csv>, cookies set --curl <file>, or --init-script/--enable before navigate/opening the target page.",
 	"For stateful browser context work, prefer purpose-specific page actions before dumping browser data: use auth save --password-stdin with the tool stdin field for credentials, auth list/show/delete/remove for local auth-profile maintenance, auth login when you need the browser to fill a saved profile, state save/load for portable test state, state list/show/rename/clear/clear -a/clean for saved-state lifecycle cleanup, cookies get/set/clear and storage local|session only when the task needs those values, and expect cookie/storage/auth/state summaries to redact credential-like fields.",
@@ -67,12 +70,12 @@ export const SHARED_BROWSER_PLAYBOOK_GUIDELINES = [
 ] as const;
 
 export const TOOL_PROMPT_GUIDELINES_SUFFIX = [
-	"Prefer agent_browser over bash for opening sites, reading docs on the web, clicking, filling, screenshots, eval, and batch workflows.",
+	"Prefer agent_browser over bash for opening sites, docs, clicking, filling, screenshots, eval, and batch workflows.",
 	"Do not fall back to osascript, AppleScript, or generic browser-driving bash commands when agent_browser can do the job.",
 	"Pass exact agent-browser CLI arguments in args when you are not using semanticAction, job, or qa, excluding the binary name and --json (the wrapper injects --json automatically).",
 	"Use stdin only for eval --stdin, batch, auth save --password-stdin, or wrapper-generated job/qa batches instead of shell heredocs or password args; other command/stdin combinations are rejected before launch.",
-	"Let the extension-managed session handle the common path unless you explicitly need a fresh launch for upstream flags like --profile, --session-name, --cdp, --state, --auto-connect, --init-script, --enable, -p/--provider, or iOS --device.",
-	"Use sessionMode=fresh when switching from an existing implicit session to a new profile/debug/init-script/provider launch without inventing a fixed explicit session name; later auto calls will follow that new session.",
+	`Let the extension-managed session handle the common path unless you explicitly need a fresh launch for launch-scoped flags (${LAUNCH_SCOPED_FLAG_LABEL}).`,
+	"Use sessionMode=fresh when switching from an existing implicit session to a new profile/browser executable/debug/init-script/provider launch without inventing a fixed explicit session name; later auto calls will follow that new session.",
 ] as const;
 
 export const INSPECTION_TOOL_CALL_EXAMPLES = [
@@ -87,30 +90,52 @@ export const WRAPPER_TAB_RECOVERY_BEHAVIOR = [
 	"If a known session target unexpectedly reports about:blank, agent_browser best-effort re-selects the prior intended target when it still exists; if recovery fails, it records the observed about:blank target and reports exact recovery guidance instead of treating the prior page as active.",
 ] as const;
 
-export function buildSharedBrowserPlaybookGuidelines(options: { includeBraveSearch: boolean }): string[] {
+export function buildSharedBrowserPlaybookGuidelines(options: { includeWebSearch: boolean }): string[] {
 	return [
 		SHARED_BROWSER_PLAYBOOK_GUIDELINES[0],
-		...(options.includeBraveSearch ? [BRAVE_SEARCH_PROMPT_GUIDELINE] : []),
+		...(options.includeWebSearch ? [WEB_SEARCH_PROMPT_GUIDELINE] : []),
 		...SHARED_BROWSER_PLAYBOOK_GUIDELINES.slice(1),
 	];
 }
 
 /** Tier A: always-on tool promptGuidelines (keep small; Tier B lives in SHARED_BROWSER_PLAYBOOK_GUIDELINES and docs). */
 export const RUNTIME_PROMPT_GUIDELINES = [
-	"Use exactly one input mode: args (open→snapshot -i→@refs), semanticAction, job, qa, sourceLookup/networkSourceLookup (candidate hints), or electron. stdin only for batch/eval/auth or wrapper batch; electron rejects stdin. Do not pass --json in args; wrapper injects it.",
-	"Common flow: open, snapshot -i, use current @refs or semanticAction, then re-snapshot after navigation/scroll/rerender/DOM change. Batch same-snapshot fills unless they may submit/navigate/rerender. Respect explicit stop boundaries: if the user says stop before order/post/purchase/submit, do not click the final action.",
-	"Use sessionMode=fresh for launch-scoped flags on an active implicit session. For signed-in/account-specific content, start with --profile Default plus sessionMode=fresh unless asked otherwise; visible content is model-visible.",
-	"For artifacts, save the exact user path and check details.artifactVerification/details.artifacts before claiming success. If close is blocked by details.promptGuard, save the required artifact first. record stop needs ffmpeg on PATH; close does not delete saved files; \"waited\":\"timeout\" is not proof.",
+	"Use exactly one input mode: args, semanticAction, job, qa, sourceLookup/networkSourceLookup, or electron. stdin only for batch/eval/auth or wrapper batch; electron rejects stdin. Do not pass --json in args; wrapper injects it.",
+	"Common flow: open, snapshot -i, use current @refs or semanticAction, then re-snapshot after navigation/scroll/rerender/DOM change. Batch same-snapshot fills unless they may submit/navigate/rerender. Respect explicit stop boundaries: stop before order/post/purchase/submit.",
+	"Use top-level sessionMode=fresh for launch-scoped flags; never put --session-mode in args. For signed-in/account-specific content, use requested/configured profiles, never assume --profile Default; on profile failures, run profiles/doctor and tell the user what to configure. Use --executable-path for configured Chromium. Profile content is model-visible.",
+	"For artifacts, save the exact user path and verify details.artifactVerification/details.artifacts before claiming success. If close is blocked by details.promptGuard, save the required artifact first. record stop needs ffmpeg; close does not delete saved files; waited:timeout is not proof.",
 	"When details.nextActions is present, prefer exact payloads over prose/guessed selectors. For dense snapshots, check Omitted high-value controls/details.data.highValueControlRefIds. For dashboards, verify scroll with screenshot/snapshot; if nothing moved, target the real scroll region.",
 	"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 buildBrowserExecutablePathGuideline(executablePath: string | undefined): string | undefined {
+	if (!executablePath) return undefined;
+	return `Agent-browser config sets browser.executablePath to ${JSON.stringify(executablePath)}; for fresh browser launches that should use that Chromium-compatible executable, add --executable-path ${JSON.stringify(executablePath)} with sessionMode:fresh. The upstream profiles command still lists Chrome profiles only; for non-Chrome Chromium login state, ask the user for an explicit profile/user-data directory path or inspect local setup with profiles/doctor before recommending a profile value.`;
+}
+
+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" };
+	browserExecutablePath?: string;
+	docs?: { readmePath: string; commandReferencePath: string; toolContractPath: string };
+	includeWebSearch: boolean;
+}): string[] {
+	const browserDefaultProfileGuideline = buildBrowserDefaultProfileGuideline(options.browserDefaultProfile);
+	const browserExecutablePathGuideline = buildBrowserExecutablePathGuideline(options.browserExecutablePath);
 	return [
 		...TOOL_PROMPT_GUIDELINES_PREFIX,
 		...(options.docs ? [buildInstalledDocsGuideline(options.docs)] : []),
 		...RUNTIME_PROMPT_GUIDELINES,
-		...(options.includeBraveSearch ? [BRAVE_SEARCH_PROMPT_GUIDELINE] : []),
+		...(browserExecutablePathGuideline ? [browserExecutablePathGuideline] : []),
+		...(browserDefaultProfileGuideline ? [browserDefaultProfileGuideline] : []),
+		...(options.includeWebSearch ? [WEB_SEARCH_PROMPT_GUIDELINE] : []),
 		TOOL_PROMPT_GUIDELINES_SUFFIX[0],
 		TOOL_PROMPT_GUIDELINES_SUFFIX[1],
 	];

package/extensions/agent-browser/lib/results/presentation/browser-profile-recovery.ts

@@ -0,0 +1,67 @@
+/**
+ * Purpose: Build browser profile/config recovery hints for launch/setup failures.
+ * Responsibilities: Recognize local Chrome/profile setup errors, avoid self-loop diagnostics, and emit canonical next actions.
+ * Scope: Error presentation only; upstream profile discovery and doctor execution remain normal agent_browser commands.
+ */
+
+import { isOpenNavigationCommand } from "../../command-taxonomy.js";
+import { getStartupScopedFlags, type CommandInfo } from "../../runtime.js";
+import type { AgentBrowserNextAction } from "../contracts.js";
+import { buildNextToolAction } from "../next-actions.js";
+
+const BROWSER_PROFILE_CONFIG_HINT = [
+	"Agent-browser profile/config hint: this looks like a local browser profile or Chrome user-data-dir setup problem, not a page-specific failure.",
+	"Do not keep retrying the same open/profile call. Run `profiles` and/or `doctor` through agent_browser, then tell the user whether Chrome/Chromium is installed, which Chrome profile directory names are available, or whether they need to configure a full profile/user-data directory path, a non-default Chromium-compatible `--executable-path`, or remove the profile requirement for public-page browsing.",
+	"Use the top-level `sessionMode: \"fresh\"` field for launch-scoped profile/debug/provider flags; do not pass `--session-mode` inside args.",
+].join(" ");
+
+function looksLikeBrowserProfileConfigError(errorText: string): boolean {
+	return /\b(?:No Chrome user data directory found|Cannot resolve profile name|Chrome user data directory|Chrome profile\s+.+?\s+not found|Available profiles|If you meant a directory path)\b/i.test(errorText);
+}
+
+function isLaunchOrSetupContext(args: string[] | undefined, commandInfo: CommandInfo): boolean {
+	const command = commandInfo.command;
+	if (command === "profiles" || command === "doctor") return true;
+	if (command && isOpenNavigationCommand(command)) return true;
+	return (args ? getStartupScopedFlags(args) : []).length > 0;
+}
+
+function buildBrowserProfileConfigActions(commandInfo: CommandInfo): AgentBrowserNextAction[] {
+	const actions: AgentBrowserNextAction[] = [];
+	if (commandInfo.command !== "profiles") {
+		actions.push(buildNextToolAction({
+			args: ["profiles"],
+			id: "inspect-browser-profiles",
+			reason: "List browser profiles/user-data-dir candidates before retrying profile-based launch.",
+			safety: "Read-only local setup inspection; does not open a page or mutate browser state.",
+		}));
+	}
+	if (commandInfo.command !== "doctor") {
+		actions.push(buildNextToolAction({
+			args: ["doctor"],
+			id: "run-agent-browser-doctor",
+			reason: "Inspect local agent-browser browser installation/configuration before retrying.",
+			safety: "Read-only local diagnostics; report findings to the user before changing setup.",
+		}));
+	}
+	return actions;
+}
+
+export interface BrowserProfileConfigRecovery {
+	actions?: AgentBrowserNextAction[];
+	hint: string;
+}
+
+export function buildBrowserProfileConfigRecovery(options: {
+	args?: string[];
+	commandInfo: CommandInfo;
+	errorText: string;
+}): BrowserProfileConfigRecovery | undefined {
+	if (!looksLikeBrowserProfileConfigError(options.errorText)) return undefined;
+	if (!isLaunchOrSetupContext(options.args, options.commandInfo)) return undefined;
+	const actions = buildBrowserProfileConfigActions(options.commandInfo);
+	return {
+		actions: actions.length > 0 ? actions : undefined,
+		hint: BROWSER_PROFILE_CONFIG_HINT,
+	};
+}

package/extensions/agent-browser/lib/results/presentation/errors.ts

@@ -1,5 +1,6 @@
 import { isOpenNavigationCommand } from "../../command-taxonomy.js";
 import type { CommandInfo } from "../../runtime.js";
+import { buildBrowserProfileConfigRecovery } from "./browser-profile-recovery.js";
 import { redactModelFacingText } from "./common.js";
 import { buildAgentBrowserNextActions } from "../action-recommendations.js";
 import { buildAgentBrowserResultCategoryDetails } from "../categories.js";
@@ -119,10 +120,12 @@ export function buildErrorPresentation(options: {
 	const selectorHintedErrorText = appendSelectorRecoveryHint(safeErrorText);
 	const unknownCommandSuggestions = getUnknownCommandSuggestions(commandInfo.command, safeErrorText);
 	const unknownCommandSuggestionText = formatUnknownCommandSuggestionText(unknownCommandSuggestions);
+	const browserProfileConfigRecovery = buildBrowserProfileConfigRecovery({ args, commandInfo, errorText: safeErrorText });
 	const localhostNavigationHint = getLocalhostNavigationHint(commandInfo, safeErrorText);
 	const hintedErrorParts = [
 		selectorHintedErrorText,
 		unknownCommandSuggestionText && !selectorHintedErrorText.includes("Agent-browser hint:") ? unknownCommandSuggestionText : undefined,
+		browserProfileConfigRecovery?.hint,
 		localhostNavigationHint,
 	].filter((part): part is string => Boolean(part));
 	const hintedErrorText = hintedErrorParts.join("\n\n");
@@ -134,6 +137,7 @@ export function buildErrorPresentation(options: {
 	});
 	const nextActions = [
 		...(buildUnknownCommandSuggestionActions(unknownCommandSuggestions, sessionName) ?? []),
+		...(browserProfileConfigRecovery?.actions ?? []),
 		...(buildAgentBrowserNextActions({
 			args,
 			command: commandInfo.command,

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

@@ -24,82 +24,14 @@ import {
 } from "./argv-grammar.js";
 import { needsManagedSession } from "./command-policy.js";
 import { isCloseCommand, isOpenNavigationCommand } from "./command-taxonomy.js";
+import { LAUNCH_SCOPED_FLAG_DEFINITIONS, LAUNCH_SCOPED_FLAG_LABEL, LAUNCH_SCOPED_TAB_CORRECTION_FLAGS } from "./launch-scoped-flags.js";
 
 export type { CommandInfo } from "./argv-descriptor.js";
 export { extractCommandTokens, findCommandStartIndex, parseArgvDescriptor, parseCommandInfo } from "./argv-descriptor.js";
 
 import { isRecord } from "./parsing.js";
 
-/**
- * Launch-scoped flags that select the upstream browser session/auth mechanism at launch time.
- *
- * These flags must not be silently appended after an already-active extension-managed session
- * because upstream ignores or conflicts with them once a session is reused. Every flag here
- * participates in implicit-session validation blocking and recovery-hint generation.
- *
- * Intentionally excluded from the tab-correction subset:
- * - `--auto-connect` attaches to a running browser but is a general-purpose debug/attach mode,
- *   not a state-restore mechanism that typically leaves restored tabs stealing focus.
- * - `--cdp` connects to an arbitrary endpoint; similar reasoning to `--auto-connect`.
- *
- * Other flags like `--headed`, `--engine`, `--executable-path`, `--user-agent`, and
- * `--download-path` are first-launch-sensitive but not alternate session/auth attach
- * mechanisms and do not inject pre-page JavaScript, so they are intentionally excluded
- * from the full launch-scoped set.
- */
-const LAUNCH_SCOPED_FLAG_DEFINITIONS = [
-	{
-		flag: "--auto-connect",
-		reason: "attaches to an already-running browser at launch time instead of reusing an existing named session",
-	},
-	{
-		flag: "--cdp",
-		reason: "selects the browser/CDP endpoint used when an upstream session is launched",
-	},
-	{
-		flag: "--enable",
-		reason: "selects built-in page init scripts before the upstream browser session is launched",
-	},
-	{
-		flag: "--init-script",
-		reason: "registers page init scripts before the upstream browser session is launched",
-	},
-	{
-		flag: "--device",
-		reason: "selects the provider device for the upstream launch",
-	},
-	{
-		flag: "--profile",
-		reason: "selects Chrome profile state for the upstream launch",
-	},
-	{
-		flag: "--provider",
-		reason: "selects the upstream browser provider for the launch",
-	},
-	{
-		flag: "-p",
-		reason: "selects the upstream browser provider for the launch",
-	},
-	{
-		flag: "--session-name",
-		reason: "selects upstream saved auth/session state for the launch",
-	},
-	{
-		flag: "--state",
-		reason: "loads persisted upstream browser/auth state at launch time",
-	},
-] as const;
-
-const LAUNCH_SCOPED_FLAG_LABEL = LAUNCH_SCOPED_FLAG_DEFINITIONS.map((definition) => definition.flag).join(", ");
-
-/**
- * The subset of launch-scoped flags that can restore browser/auth state with pre-existing tabs
- * and are plausible wrong-active-tab sources after a fresh launch. These trigger post-open
- * tab-correction (the `tab list` + re-select cycle).
- */
-const LAUNCH_SCOPED_TAB_CORRECTION_FLAGS = new Set(["--profile", "--session-name", "--state"] as const);
 const OPENAI_HEADLESS_COMPAT_HOSTS = new Set(["chat.com", "chat.openai.com", "chatgpt.com"]);
-const BRAVE_API_KEY_ENV = "BRAVE_API_KEY";
 const AGENT_BROWSER_IDLE_TIMEOUT_ENV = "AGENT_BROWSER_IDLE_TIMEOUT_MS";
 const IMPLICIT_SESSION_IDLE_TIMEOUT_ENV = "PI_AGENT_BROWSER_IMPLICIT_SESSION_IDLE_TIMEOUT_MS";
 const IMPLICIT_SESSION_CLOSE_TIMEOUT_ENV = "PI_AGENT_BROWSER_IMPLICIT_SESSION_CLOSE_TIMEOUT_MS";
@@ -430,10 +362,6 @@ 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;
-}
-
 function parseTimeoutMs(rawValue: string | undefined, minimumValue: number): number | undefined {
 	if (typeof rawValue !== "string") return undefined;
 	const normalizedValue = rawValue.trim();
@@ -695,6 +623,11 @@ export function validateToolArgs(args: string[]): string | undefined {
 		return `Do not pass shell operators like \`${shellOperator}\`. Pass exact agent-browser CLI arguments only.`;
 	}
 
+	const sessionModeArg = args.find((token) => token === "--session-mode" || token.startsWith("--session-mode="));
+	if (sessionModeArg) {
+		return "Do not pass `--session-mode` in args. Use the top-level agent_browser `sessionMode` field instead, for example { args: [\"--profile\", \"Default\", \"open\", \"https://example.com\"], sessionMode: \"fresh\" }.";
+	}
+
 	return undefined;
 }