pi-agent-browser-native 0.2.32 → 0.2.33

package/extensions/agent-browser/lib/orchestration/input-plan.ts

@@ -0,0 +1,338 @@
+import { validateToolArgs, redactInvocationArgs, redactSensitiveText } from "../runtime.js";
+import { buildAgentBrowserResultCategoryDetails } from "../results/categories.js";
+import {
+	compileAgentBrowserElectron,
+	compileAgentBrowserJob,
+	compileAgentBrowserNetworkSourceLookup,
+	compileAgentBrowserQaPreset,
+	compileAgentBrowserSemanticAction,
+	compileAgentBrowserSourceLookup,
+	redactNetworkSourceLookupArgs,
+	redactNetworkSourceLookupUrl,
+	type CompiledAgentBrowserElectron,
+	type CompiledAgentBrowserJob,
+	type CompiledAgentBrowserNetworkSourceLookup,
+	type CompiledAgentBrowserQaPreset,
+	type CompiledAgentBrowserSemanticAction,
+	type CompiledAgentBrowserSourceLookup,
+} from "../input-modes.js";
+
+export interface AgentBrowserExecuteParams {
+	args?: string[];
+	electron?: unknown;
+	job?: unknown;
+	networkSourceLookup?: unknown;
+	qa?: unknown;
+	semanticAction?: unknown;
+	sessionMode?: "auto" | "fresh";
+	sourceLookup?: unknown;
+	stdin?: string;
+}
+
+export type ResolvedAgentBrowserInputKind = "args" | "electron" | "job" | "networkSourceLookup" | "qa" | "semanticAction" | "sourceLookup";
+
+type ResolvedAgentBrowserInputModeFields = {
+	compiledElectron?: CompiledAgentBrowserElectron;
+	compiledGeneratedBatch?: CompiledAgentBrowserJob | CompiledAgentBrowserNetworkSourceLookup | CompiledAgentBrowserSourceLookup;
+	compiledJob?: CompiledAgentBrowserJob;
+	compiledNetworkSourceLookup?: CompiledAgentBrowserNetworkSourceLookup;
+	compiledQaPreset?: CompiledAgentBrowserQaPreset;
+	compiledSemanticAction?: CompiledAgentBrowserSemanticAction;
+	compiledSourceLookup?: CompiledAgentBrowserSourceLookup;
+	redactedCompiledElectron?: CompiledAgentBrowserElectron;
+	redactedCompiledJob?: CompiledAgentBrowserJob;
+	redactedCompiledNetworkSourceLookup?: CompiledAgentBrowserNetworkSourceLookup;
+	redactedCompiledQaPreset?: CompiledAgentBrowserQaPreset;
+	redactedCompiledSemanticAction?: CompiledAgentBrowserSemanticAction;
+	redactedCompiledSourceLookup?: CompiledAgentBrowserSourceLookup;
+};
+
+interface ResolvedAgentBrowserInputBase {
+	redactedArgs: string[];
+	toolArgs: string[];
+	toolStdin?: string;
+}
+
+interface ResolvedAgentBrowserValidInputBase extends ResolvedAgentBrowserInputBase {
+	status: "valid";
+	validationError?: undefined;
+}
+
+export interface ResolvedAgentBrowserInvalidInput extends ResolvedAgentBrowserInputBase, ResolvedAgentBrowserInputModeFields {
+	attemptedKind?: ResolvedAgentBrowserInputKind;
+	kind: "invalid";
+	status: "invalid";
+	validationError: string;
+}
+
+export type ResolvedAgentBrowserValidInput =
+	| (ResolvedAgentBrowserValidInputBase & {
+		kind: "args";
+	})
+	| (ResolvedAgentBrowserValidInputBase & {
+		compiledElectron: CompiledAgentBrowserElectron;
+		kind: "electron";
+		redactedCompiledElectron: CompiledAgentBrowserElectron;
+	})
+	| (ResolvedAgentBrowserValidInputBase & {
+		compiledGeneratedBatch: CompiledAgentBrowserJob;
+		compiledJob: CompiledAgentBrowserJob;
+		kind: "job";
+		redactedCompiledJob: CompiledAgentBrowserJob;
+	})
+	| (ResolvedAgentBrowserValidInputBase & {
+		compiledGeneratedBatch: CompiledAgentBrowserNetworkSourceLookup;
+		compiledNetworkSourceLookup: CompiledAgentBrowserNetworkSourceLookup;
+		kind: "networkSourceLookup";
+		redactedCompiledNetworkSourceLookup: CompiledAgentBrowserNetworkSourceLookup;
+	})
+	| (ResolvedAgentBrowserValidInputBase & {
+		compiledGeneratedBatch: CompiledAgentBrowserQaPreset;
+		compiledJob: CompiledAgentBrowserQaPreset;
+		compiledQaPreset: CompiledAgentBrowserQaPreset;
+		kind: "qa";
+		redactedCompiledJob: CompiledAgentBrowserJob;
+		redactedCompiledQaPreset: CompiledAgentBrowserQaPreset;
+	})
+	| (ResolvedAgentBrowserValidInputBase & {
+		compiledSemanticAction: CompiledAgentBrowserSemanticAction;
+		kind: "semanticAction";
+		redactedCompiledSemanticAction: CompiledAgentBrowserSemanticAction;
+	})
+	| (ResolvedAgentBrowserValidInputBase & {
+		compiledGeneratedBatch: CompiledAgentBrowserSourceLookup;
+		compiledSourceLookup: CompiledAgentBrowserSourceLookup;
+		kind: "sourceLookup";
+		redactedCompiledSourceLookup: CompiledAgentBrowserSourceLookup;
+	});
+
+export type ResolvedAgentBrowserInput = ResolvedAgentBrowserInvalidInput | ResolvedAgentBrowserValidInput;
+
+function redactCompiledElectron(compiled: CompiledAgentBrowserElectron | undefined): CompiledAgentBrowserElectron | undefined {
+	if (!compiled) return undefined;
+	if (compiled.action === "list") {
+		return { ...compiled, query: compiled.query ? redactSensitiveText(compiled.query) : undefined };
+	}
+	if (compiled.action === "launch") {
+		return { ...compiled, appArgs: compiled.appArgs ? redactInvocationArgs(compiled.appArgs) : undefined };
+	}
+	return { ...compiled };
+}
+
+function redactCompiledJob(compiled: CompiledAgentBrowserJob | undefined): CompiledAgentBrowserJob | undefined {
+	const redactedSteps = compiled?.steps.map((step) => ({ ...step, args: redactInvocationArgs(step.args) }));
+	return compiled && redactedSteps
+		? { ...compiled, stdin: JSON.stringify(redactedSteps.map((step) => step.args)), steps: redactedSteps }
+		: undefined;
+}
+
+function redactCompiledSourceLookup(compiled: CompiledAgentBrowserSourceLookup | undefined): CompiledAgentBrowserSourceLookup | undefined {
+	const redactedSteps = compiled?.steps.map((step) => ({ ...step, args: redactInvocationArgs(step.args) }));
+	return compiled && redactedSteps
+		? { ...compiled, stdin: JSON.stringify(redactedSteps.map((step) => step.args)), steps: redactedSteps }
+		: undefined;
+}
+
+function redactCompiledNetworkSourceLookup(compiled: CompiledAgentBrowserNetworkSourceLookup | undefined): CompiledAgentBrowserNetworkSourceLookup | undefined {
+	const redactedSteps = compiled?.steps.map((step) => ({ ...step, args: redactNetworkSourceLookupArgs(step.args) }));
+	return compiled && redactedSteps
+		? {
+			...compiled,
+			args: redactNetworkSourceLookupArgs(compiled.args),
+			query: {
+				...compiled.query,
+				filter: redactNetworkSourceLookupUrl(compiled.query.filter),
+				url: redactNetworkSourceLookupUrl(compiled.query.url),
+			},
+			stdin: JSON.stringify(redactedSteps.map((step) => step.args)),
+			steps: redactedSteps,
+		}
+		: undefined;
+}
+
+export function resolveAgentBrowserInput(options: {
+	getBatchAnnotateValidationError: (args: string[], stdin: string | undefined) => string | undefined;
+	managedSessionActive: boolean;
+	params: AgentBrowserExecuteParams;
+}): ResolvedAgentBrowserInput {
+	const { getBatchAnnotateValidationError, managedSessionActive, params } = options;
+	const semanticActionResult = params.semanticAction === undefined ? {} : compileAgentBrowserSemanticAction(params.semanticAction);
+	const jobResult = params.job === undefined ? {} : compileAgentBrowserJob(params.job);
+	const qaResult = params.qa === undefined ? {} : compileAgentBrowserQaPreset(params.qa);
+	const sourceLookupResult = params.sourceLookup === undefined ? {} : compileAgentBrowserSourceLookup(params.sourceLookup);
+	const networkSourceLookupResult = params.networkSourceLookup === undefined ? {} : compileAgentBrowserNetworkSourceLookup(params.networkSourceLookup);
+	const electronResult = params.electron === undefined ? {} : compileAgentBrowserElectron(params.electron);
+
+	const hasExplicitArgs = Array.isArray(params.args);
+	const explicitInputModes = [
+		hasExplicitArgs,
+		Boolean(semanticActionResult.compiled),
+		Boolean(jobResult.compiled),
+		Boolean(qaResult.compiled),
+		Boolean(sourceLookupResult.compiled),
+		Boolean(networkSourceLookupResult.compiled),
+		Boolean(electronResult.compiled),
+	].filter(Boolean).length;
+	const inputModeError = explicitInputModes !== 1
+		? "Provide exactly one of args, semanticAction, job, qa, sourceLookup, networkSourceLookup, or electron."
+		: undefined;
+
+	const compiledSemanticAction = semanticActionResult.compiled;
+	const compiledQaPreset = qaResult.compiled;
+	const compiledSourceLookup = sourceLookupResult.compiled;
+	const compiledNetworkSourceLookup = networkSourceLookupResult.compiled;
+	const compiledElectron = electronResult.compiled;
+	const compiledJob = jobResult.compiled ?? compiledQaPreset;
+	const compiledGeneratedBatch = compiledNetworkSourceLookup ?? compiledSourceLookup ?? compiledJob;
+	const toolArgs = compiledElectron ? [] : compiledSemanticAction?.args ?? compiledGeneratedBatch?.args ?? params.args ?? [];
+	const toolStdin = compiledGeneratedBatch?.stdin ?? params.stdin;
+	const redactedArgs = redactInvocationArgs(toolArgs);
+	const generatedStdinError = params.stdin !== undefined
+		? compiledGeneratedBatch
+			? "Do not provide stdin with job, qa, sourceLookup, or networkSourceLookup; those modes generate their own batch stdin."
+			: compiledElectron
+				? "Do not provide stdin with electron; electron mode is host-only or manages its own input."
+				: undefined
+		: undefined;
+	const attachedQaSessionError = compiledQaPreset?.checks.attached
+		? params.sessionMode === "fresh"
+			? "qa.attached cannot be used with sessionMode=fresh; attach or launch a session first, then run qa.attached with the current session."
+			: !managedSessionActive
+				? "qa.attached requires an active attached session. Run electron.launch or connect to an Electron debug port first."
+				: undefined
+		: undefined;
+	const validationError = semanticActionResult.error
+		?? jobResult.error
+		?? qaResult.error
+		?? sourceLookupResult.error
+		?? networkSourceLookupResult.error
+		?? electronResult.error
+		?? inputModeError
+		?? generatedStdinError
+		?? attachedQaSessionError
+		?? (compiledElectron ? undefined : validateToolArgs(toolArgs) ?? getBatchAnnotateValidationError(toolArgs, toolStdin));
+	const redactedCompiledJob = redactCompiledJob(compiledJob);
+	const redactedCompiledSemanticAction = compiledSemanticAction
+		? { ...compiledSemanticAction, args: redactInvocationArgs(compiledSemanticAction.args) }
+		: undefined;
+	const attemptedKind: ResolvedAgentBrowserInputKind | undefined = compiledElectron
+		? "electron"
+		: compiledNetworkSourceLookup
+			? "networkSourceLookup"
+			: compiledSourceLookup
+				? "sourceLookup"
+				: compiledQaPreset
+					? "qa"
+					: jobResult.compiled
+						? "job"
+						: compiledSemanticAction
+							? "semanticAction"
+							: hasExplicitArgs
+								? "args"
+								: undefined;
+
+	const redactedCompiledElectron = redactCompiledElectron(compiledElectron);
+	const redactedCompiledNetworkSourceLookup = redactCompiledNetworkSourceLookup(compiledNetworkSourceLookup);
+	const redactedCompiledQaPreset = compiledQaPreset && redactedCompiledJob ? { ...redactedCompiledJob, checks: compiledQaPreset.checks } : undefined;
+	const redactedCompiledSourceLookup = redactCompiledSourceLookup(compiledSourceLookup);
+	const resolvedBase: ResolvedAgentBrowserInputBase = { redactedArgs, toolArgs, toolStdin };
+	if (validationError) {
+		return {
+			...resolvedBase,
+			attemptedKind,
+			compiledElectron,
+			compiledGeneratedBatch,
+			compiledJob,
+			compiledNetworkSourceLookup,
+			compiledQaPreset,
+			compiledSemanticAction,
+			compiledSourceLookup,
+			kind: "invalid",
+			redactedCompiledElectron,
+			redactedCompiledJob,
+			redactedCompiledNetworkSourceLookup,
+			redactedCompiledQaPreset,
+			redactedCompiledSemanticAction,
+			redactedCompiledSourceLookup,
+			status: "invalid",
+			validationError,
+		};
+	}
+	if (compiledElectron && redactedCompiledElectron) {
+		return { ...resolvedBase, compiledElectron, kind: "electron", redactedCompiledElectron, status: "valid" };
+	}
+	if (compiledNetworkSourceLookup && redactedCompiledNetworkSourceLookup) {
+		return {
+			...resolvedBase,
+			compiledGeneratedBatch: compiledNetworkSourceLookup,
+			compiledNetworkSourceLookup,
+			kind: "networkSourceLookup",
+			redactedCompiledNetworkSourceLookup,
+			status: "valid",
+		};
+	}
+	if (compiledSourceLookup && redactedCompiledSourceLookup) {
+		return {
+			...resolvedBase,
+			compiledGeneratedBatch: compiledSourceLookup,
+			compiledSourceLookup,
+			kind: "sourceLookup",
+			redactedCompiledSourceLookup,
+			status: "valid",
+		};
+	}
+	if (compiledQaPreset && redactedCompiledJob && redactedCompiledQaPreset) {
+		return {
+			...resolvedBase,
+			compiledGeneratedBatch: compiledQaPreset,
+			compiledJob: compiledQaPreset,
+			compiledQaPreset,
+			kind: "qa",
+			redactedCompiledJob,
+			redactedCompiledQaPreset,
+			status: "valid",
+		};
+	}
+	if (jobResult.compiled && redactedCompiledJob) {
+		return {
+			...resolvedBase,
+			compiledGeneratedBatch: jobResult.compiled,
+			compiledJob: jobResult.compiled,
+			kind: "job",
+			redactedCompiledJob,
+			status: "valid",
+		};
+	}
+	if (compiledSemanticAction && redactedCompiledSemanticAction) {
+		return { ...resolvedBase, compiledSemanticAction, kind: "semanticAction", redactedCompiledSemanticAction, status: "valid" };
+	}
+	return { ...resolvedBase, kind: "args", status: "valid" };
+}
+
+export function buildValidationFailureResult(input: ResolvedAgentBrowserInvalidInput): {
+	content: Array<{ text: string; type: "text" }>;
+	details: Record<string, unknown>;
+	isError: true;
+} {
+	const validationError = input.validationError ?? "Invalid agent_browser input.";
+	return {
+		content: [{ type: "text", text: validationError }],
+		details: {
+			args: input.redactedArgs,
+			compiledElectron: input.redactedCompiledElectron,
+			compiledJob: input.redactedCompiledJob,
+			compiledQaPreset: input.redactedCompiledQaPreset,
+			compiledSourceLookup: input.redactedCompiledSourceLookup,
+			compiledNetworkSourceLookup: input.redactedCompiledNetworkSourceLookup,
+			compiledSemanticAction: input.redactedCompiledSemanticAction,
+			...buildAgentBrowserResultCategoryDetails({
+				args: input.redactedArgs,
+				errorText: validationError,
+				succeeded: false,
+				validationError,
+			}),
+			validationError,
+		},
+		isError: true,
+	};
+}

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

@@ -21,7 +21,7 @@ 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 (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.",
 	"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: { args: [\"open\", \"https://example.com\"] } then { args: [\"snapshot\", \"-i\"] }; after navigation, use { args: [\"click\", \"@e2\"] } then { args: [\"snapshot\", \"-i\"] }.",
-	"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 try-*-candidate next actions (and an Agent-browser candidate fallbacks prose block) for specific placeholder/text/label shapes, and stale-ref failures can return retry-semantic-action-after-stale-ref for compiled find actions when retry safety is provable.",
+	"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.",
 	"Common advanced calls: { args: [\"batch\"], stdin: \"[[\\\"open\\\",\\\"https://example.com\\\"],[\\\"snapshot\\\",\\\"-i\\\"]]\" }, { job: { steps: [{ action: \"open\", url: \"https://example.com\" }, { action: \"assertText\", text: \"Example Domain\" }, { action: \"screenshot\", path: \".dogfood/example.png\" }] } }, { qa: { url: \"https://example.com\", expectedText: \"Example Domain\", screenshotPath: \".dogfood/qa-example.png\" } }, { electron: { action: \"list\", query: \"code\" } }, { electron: { action: \"launch\", appName: \"Visual Studio Code\", handoff: \"snapshot\" } }, { electron: { action: \"probe\" } }, { qa: { attached: true, expectedText: \"Explorer\" } }, { args: [\"eval\", \"--stdin\"], stdin: \"document.title\" }, { args: [\"auth\", \"save\", \"name\", \"--password-stdin\"], stdin: \"<password from user-approved secret source>\" }, { args: [\"--profile\", \"Default\", \"open\", \"https://example.com/account\"], sessionMode: \"fresh\" }, and { args: [\"open\", \"--enable\", \"react-devtools\", \"https://example.com\"], sessionMode: \"fresh\" }. For app pages with a native dropdown, job steps can include { action: \"select\", selector: \"#flavor\", value: \"chocolate\" } before the dependent assertion.",
 	"High-value command reference: select <selector> <value...> changes native dropdown values; download <selector> <path> saves a file triggered by a click; get title/url/text/html/value/attr/count reads page state; screenshot [path] captures an image; pdf <path> saves a PDF; tab list and tab <tab-id-or-label> inspect or recover the active tab; react tree/inspect/renders/suspense introspect React after --enable react-devtools; vitals [url] measures Core Web Vitals; pushstate <url> performs SPA navigation.",
 	"For artifact-producing commands, read the visible artifact block and details.artifactVerification before using files: check requested path, absolute path, existence, size bytes, artifact kind, optional mediaType, status, optional limitation, and verified/missing/pending/unverified counts. details.artifacts contains per-file metadata. Browser close does not delete explicit saved files; if close reports details.artifactCleanup, use host file tools to remove paths listed in explicitArtifactPaths (when non-empty) after inspection. For annotated screenshots inside batch, put --annotate in top-level args (for example { args: [\"--annotate\", \"batch\"], stdin: \"[[\\\"screenshot\\\",\\\"/tmp/page.png\\\"]]\" }) rather than inside the screenshot step.",
@@ -36,6 +36,7 @@ export const SHARED_BROWSER_PLAYBOOK_GUIDELINES = [
 	"For ordinary forms from one snapshot, batch multiple fill @refs before the submit/click step to avoid serial tool calls; if a fill may autosubmit, navigate, or rerender later fields, split the flow and refresh refs first.",
 	"When snapshot -i compacts because the tree is oversized, scan visible output for Omitted high-value controls and optional details.data.highValueControlRefIds before opening the spill file: those list bounded searchboxes, textboxes, comboboxes, buttons, tabs, checkboxes, radios, options, and menuitems that did not fit the key/other ref previews.",
 	"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.",
 	"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.",
@@ -46,10 +47,10 @@ export const SHARED_BROWSER_PLAYBOOK_GUIDELINES = [
 	"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, state save/load for portable test state, 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.",
 	"For batch chains that touch cookies, storage, auth, or other secret-bearing commands, use details.batchSteps for per-step artifacts, categories, spill paths, and full structured errors; top-level details.data on batch is only a compact redacted step matrix (success, argv-redacted command, redacted result or scrubbed error text) built from the same presentation rules as standalone calls.",
 	"For non-core families, pass current upstream commands through the native tool directly: network route/requests/har, diff snapshot/screenshot/url, trace/profiler/record, console/errors/highlight/inspect/clipboard, stream enable/disable/status, dashboard start/stop, and chat. For compact network requests output, prefer details.nextActions for request detail, actionable failed-request networkSourceLookup, filtering, or HAR capture follow-ups instead of guessing request-id syntax. Artifact-producing commands report details.artifacts and verification state; long-running starts such as stream, dashboard, trace/profiler, and record should be paired with the matching stop/disable command when the task is done.",
-	"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>; leave shutdown/profile cleanup to the host owner.",
+	"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 only closes 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. 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. Only use wait with an explicit argument like milliseconds, --load <state>, --url <matcher>, --fn <js>, or --text <matcher>.",
+	"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 desktop readiness, prefer real conditions first: wait --text, wait --url, wait --fn, wait --load <state>, wait --download, or qa.attached; 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.",
@@ -79,7 +80,7 @@ export const WRAPPER_TAB_RECOVERY_BEHAVIOR = [
 	"After launch-scoped open/goto/navigate calls that can restore existing tabs (for example --profile, --session-name, or --state), agent_browser best-effort re-selects the tab whose URL matches the returned page when restored tabs steal focus during launch.",
 	"After the wrapper observes tab-drift risk for a session (for example profile restore correction, overlapping stale opens, or resumed session state), later active-tab commands best-effort pin that tab inside the same upstream invocation. Routine same-session commands are not preflighted with tab list just because a target tab is known.",
 	"For sessions with observed tab-drift risk, after a successful command on a known target tab, agent_browser also best-effort restores that intended tab if a restored/background tab steals focus after the command completes. Routine same-session commands skip this post-command tab-list probe.",
-	"If a known session target unexpectedly reports about:blank, agent_browser preserves the prior intended target, best-effort re-selects it when it still exists, and reports exact recovery guidance when it cannot be re-selected.",
+	"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[] {
@@ -92,14 +93,14 @@ export function buildSharedBrowserPlaybookGuidelines(options: { includeBraveSear
 
 const RUNTIME_PROMPT_GUIDELINES = [
 	"Use exactly one input mode: args, semanticAction, job, qa, sourceLookup, networkSourceLookup, or electron. Use stdin only for batch, eval --stdin, auth save --password-stdin, or wrapper-generated batch modes; electron rejects caller stdin.",
-	"Common flow: open, snapshot -i, interact with current @refs or semanticAction, then re-snapshot after navigation, scrolling, rerenders, or DOM changes. For ordinary forms, batch same-snapshot fill @refs before the submit/click step; split if a fill may autosubmit, navigate, or rerender later fields. Respect explicit stop boundaries: if the user says to stop before order/post/purchase/submit, do not click that final action.",
-	"Prefer stable locators for visible text/names: semanticAction or upstream find with role/text/label/placeholder/alt/title/testid. For native selects, prefer select <selector> <value...> or semanticAction/job select over clicking option refs. Use current @refs only from the latest same-page snapshot.",
-	"For signed-in/account-specific content on the web, start with --profile Default plus sessionMode=fresh unless asked otherwise; visible content is model-visible. For desktop/local Electron apps, use electron.list first, not web open; electron.launch is isolated. For signed-in desktop content, if not running, host-launch with --remote-debugging-port then agent_browser connect; if running without a port, ask before relaunch. Use sessionMode=fresh for other launch-scoped state; otherwise keep implicit continuity.",
-	"For requested screenshots, recordings, downloads, PDFs, or HARs, save the exact user path and read details.artifactVerification before claiming success; report unavailable/missing artifacts instead of silently substituting paths. record stop needs ffmpeg on PATH. close does not delete saved files; cleanup is host-owned. Electron cleanup only covers wrapper-launched Electron processes/profiles for the returned launchId, not explicit artifacts or externally launched apps.",
-	"When details.nextActions is present, prefer those exact follow-up payloads over prose or guessed selectors; network request diagnostics may include request-detail, actionable failed-request networkSourceLookup, filter, or HAR-capture follow-ups, and Electron lifecycle results may include status/cleanup/tab/snapshot actions keyed to the wrapper launchId/session.",
+	"Common flow: open, snapshot -i, interact with current @refs or semanticAction, then re-snapshot after navigation, scrolling, rerenders, or DOM changes. Batch same-snapshot form fills unless a fill may submit, navigate, or rerender. If semanticAction fill misses on a rich host input, use richInputRecovery/current editable refs, focus/click, then keyboard inserttext/type; do not auto-submit. Respect explicit stop boundaries: if the user says to stop before order/post/purchase/submit, do not click that final action.",
+	"Prefer stable locators for visible text/names: semanticAction or find role/text/label/placeholder/alt/title/testid. For native selects, use select <selector> <value...> or semanticAction/job select. Use current @refs only from the latest same-page snapshot.",
+	"For signed-in/account-specific content on the web, start with --profile Default plus sessionMode=fresh unless asked otherwise; visible content is model-visible. For desktop/Electron apps, use electron.list first. electron.launch is isolated; for signed-in desktop content, host-launch with --remote-debugging-port, connect, tab list, select the stable tab id, then condition-wait or snapshot -i. Use sessionMode=fresh for other launch-scoped state; otherwise keep implicit continuity.",
+	"For screenshots, recordings, downloads, PDFs, or HARs, save the exact user path and check details.artifactVerification before claiming success. record stop needs ffmpeg on PATH. close does not delete saved files; cleanup is host-owned. Electron cleanup only covers wrapper-launched launchIds. For desktop readiness, prefer condition waits, qa.attached, electron.probe/status, tab list/tab tN, snapshot, or screenshot; wait 30000 is blocked, and \"waited\":\"timeout\" is not completion evidence.",
+	"When details.nextActions is present, prefer those exact follow-up payloads over prose or guessed selectors; diagnostics may include request detail, networkSourceLookup, HAR capture, Electron status/cleanup, tab selection, rich-input focus/click recovery, or snapshot actions.",
 	"For dense snapshots, check Omitted high-value controls and details.data.highValueControlRefIds before opening large spill files.",
-	"For dashboards, verify scroll with screenshot/snapshot; if nothing moved, use scrollintoview <@ref> or target the real scroll region. For native selects use select/semanticAction/job select instead of option refs; custom combobox clicks may only focus, so re-snapshot and fall back to type, Enter/arrows, or visible option refs.",
-	"For extraction, prefer get title/url/text/html/value/attr/count or eval --stdin with a plain expression in the tool stdin field; do not rely on console.log. When reading several known refs/selectors, use batch with JSON-array stdin (for example [[\"get\",\"text\",\"@e1\"]]) or eval --stdin instead of many serial get calls. If selector visibility warnings appear, prefer visible @refs or nextActions.",
+	"For dashboards, verify scroll with screenshot/snapshot; if nothing moved, use scrollintoview <@ref> or target the real scroll region. Native selects need select/semanticAction/job select; custom comboboxes may need re-snapshot, type, Enter/arrows, or visible option refs.",
+	"For extraction, prefer get title/url/text/html/value/attr/count or eval --stdin with a plain expression; do not rely on console.log. When reading several known refs/selectors, use batch JSON-array stdin (for example [[\"get\",\"text\",\"@e1\"]]) or eval --stdin instead of many serial gets. If selector visibility warnings appear, prefer visible @refs or nextActions.",
 	"For non-core debugging, pass upstream commands through args: network, diff, trace/profiler/record, console/errors, stream, dashboard, chat, react, vitals, pushstate, dialog, frame, tab.",
 ] as const;
 

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

@@ -6,7 +6,7 @@
  * Invariants/Assumptions: The binary name is always `agent-browser`, the wrapper never shells out, and callers handle semantic success/error interpretation.
  */
 
-import { spawn } from "node:child_process";
+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";
 
@@ -22,6 +22,8 @@ const PI_AGENT_BROWSER_PROCESS_TIMEOUT_ENV = "PI_AGENT_BROWSER_PROCESS_TIMEOUT_M
 const DEFAULT_AGENT_BROWSER_SOCKET_DIR_PREFIX = "/tmp/piab";
 export const SAFE_AGENT_BROWSER_OPERATION_TIMEOUT_MS = 25_000;
 const DEFAULT_AGENT_BROWSER_PROCESS_TIMEOUT_MS = 28_000;
+/** Grace period after `exit` before resolving when `close` is delayed by inherited stdio handles. */
+const EXIT_STDIO_GRACE_MS = 100;
 const httpProxyEnvName = "http_proxy";
 const httpsProxyEnvName = "https_proxy";
 const allProxyEnvName = "all_proxy";
@@ -105,6 +107,94 @@ function appendTail(text: string, addition: string, maxChars: number): string {
 	return combined.length <= maxChars ? combined : combined.slice(combined.length - maxChars);
 }
 
+/** Exported for unit tests that lock subprocess exit-code precedence. */
+export function resolveSpawnedChildExitCode(input: {
+	closeCode?: number | null;
+	exitCode?: number | null;
+	useExitFallback: boolean;
+	timedOut: boolean;
+	spawnError?: Error;
+}): number {
+	// Precedence: observed `close` code when present, then wrapper timeout (124), then
+	// post-`exit` fallback when inherited stdio delays `close`, then spawn failure (127).
+	if (input.closeCode !== null && input.closeCode !== undefined) {
+		return input.closeCode;
+	}
+	if (input.timedOut) {
+		return 124;
+	}
+	if (input.useExitFallback && input.exitCode !== null && input.exitCode !== undefined) {
+		return input.exitCode;
+	}
+	return input.spawnError ? 127 : 0;
+}
+
+interface SpawnedChildCompletionWatcher {
+	clear: () => void;
+}
+
+function watchSpawnedChildCompletion(
+	child: ChildProcessWithoutNullStreams,
+	options: {
+		graceMs: number;
+		onComplete: (exitCode: number) => void;
+		getContext: () => { timedOut: boolean; spawnError?: Error };
+	},
+): SpawnedChildCompletionWatcher {
+	let exited = false;
+	let exitCode: number | null = null;
+	let postExitTimer: NodeJS.Timeout | undefined;
+	// `completed` suppresses duplicate exit/close callbacks; `settled` in `finish` guards async spill cleanup.
+	let completed = false;
+
+	const complete = (closeCode?: number | null) => {
+		if (completed) return;
+		completed = true;
+		if (postExitTimer) {
+			clearTimeout(postExitTimer);
+			postExitTimer = undefined;
+		}
+		const context = options.getContext();
+		options.onComplete(
+			resolveSpawnedChildExitCode({
+				closeCode,
+				exitCode,
+				useExitFallback: exited,
+				timedOut: context.timedOut,
+				spawnError: context.spawnError,
+			}),
+		);
+	};
+
+	child.once("exit", (code) => {
+		exited = true;
+		exitCode = code;
+		postExitTimer = setTimeout(() => {
+			destroySpawnedChildStreams(child);
+			complete(undefined);
+		}, options.graceMs);
+		postExitTimer.unref?.();
+	});
+	child.once("close", (code) => {
+		complete(code);
+	});
+
+	return {
+		clear: () => {
+			if (postExitTimer) {
+				clearTimeout(postExitTimer);
+				postExitTimer = undefined;
+			}
+		},
+	};
+}
+
+function destroySpawnedChildStreams(child: ChildProcessWithoutNullStreams): void {
+	child.stdin?.destroy();
+	child.stdout?.destroy();
+	child.stderr?.destroy();
+}
+
 function parsePositiveIntegerEnv(value: string | undefined): number | undefined {
 	if (value === undefined || !/^\d+$/.test(value.trim())) {
 		return undefined;
@@ -207,6 +297,7 @@ export async function runAgentBrowserProcess(options: {
 		let timeoutTimer: NodeJS.Timeout | undefined;
 		let abortListener: (() => void) | undefined;
 		let timedOut = false;
+		let completionWatcher: SpawnedChildCompletionWatcher | undefined;
 
 		const queueStdoutChunk = (buffer: Buffer) => {
 			stdoutTail = appendTail(stdoutTail, buffer.toString("utf8"), MAX_BUFFERED_STDOUT_TAIL_CHARS);
@@ -258,12 +349,15 @@ export async function runAgentBrowserProcess(options: {
 				if (timeoutTimer) {
 					clearTimeout(timeoutTimer);
 				}
+				completionWatcher?.clear();
 				if (stdoutSpillHandle) {
 					await stdoutSpillHandle.close().catch(() => undefined);
 				}
 				if (!spawnError && stdoutSpillError) {
 					spawnError = stdoutSpillError;
 				}
+				// Idempotent teardown: streams may already be destroyed by the post-`exit` fallback.
+				destroySpawnedChildStreams(child);
 				resolve({
 					aborted,
 					exitCode,
@@ -324,10 +418,18 @@ export async function runAgentBrowserProcess(options: {
 		child.stdin.on("error", recordStdinError);
 		child.once("error", (error) => {
 			spawnError = error instanceof Error ? error : new Error(String(error));
-			finish(127);
+			finish(
+				resolveSpawnedChildExitCode({
+					useExitFallback: false,
+					timedOut,
+					spawnError,
+				}),
+			);
 		});
-		child.once("close", (code) => {
-			finish(code ?? (timedOut ? 124 : spawnError ? 127 : 0));
+		completionWatcher = watchSpawnedChildCompletion(child, {
+			graceMs: EXIT_STDIO_GRACE_MS,
+			onComplete: finish,
+			getContext: () => ({ timedOut, spawnError }),
 		});
 		child.stdout.on("data", (chunk: Buffer | string) => {
 			queueStdoutChunk(Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk));