pi-agent-browser-native 0.1.4 → 0.1.6

package/CHANGELOG.md

@@ -1,5 +1,20 @@
 # Changelog
 
+## 0.1.6 - 2026-04-12
+
+### Changed
+- hardened the implicit browser-session lifecycle so failed first launches no longer mark the convenience session active, startup-scoped flags behave correctly across launches and closes, and the highest-risk entrypoint paths now have direct automated and isolated-`pi` coverage
+- added explicit temp-root ownership markers, aggregate spill-file disk budgeting, inline image size limits, and graceful fallback behavior when large snapshot or stdout artifacts exceed temp budgets
+- consolidated the shared browser operating playbook across the injected system prompt and tool prompt guidance while adding direct extension-hook coverage for prompt injection, bash blocking, and session resets
+- split the old result-rendering god module into focused envelope, presentation, shared, and snapshot modules, and made snapshot compaction fall back to a resilient outline mode when upstream raw snapshot formatting is unfamiliar
+- refactored the release-package verification script into smaller testable helpers, preserved the retired autoload-shim guard, and aligned the tarball gate with the split result-rendering module layout
+
+## 0.1.5 - 2026-04-12
+
+### Changed
+- pinned the transitive `basic-ftp` dependency to `5.2.2` via `overrides` so local development and GitHub install flows no longer pull the vulnerable `5.2.1` version through `@mariozechner/pi-coding-agent`
+- kept the 0.1.4 startup fix and metadata updates intact while clearing the audit failure that surfaced during release verification
+
 ## 0.1.4 - 2026-04-12
 
 ### Changed

package/docs/RELEASE.md

@@ -31,7 +31,7 @@ npm run verify:release
 - no repo-local `.pi/extensions/agent-browser.ts` autoload shim is present
 - `LICENSE` exists in the repo and the packed tarball
 - canonical published docs are present
-- extension source files are present
+- extension source files are present, including the split result-rendering modules required by the published facade
 - agent-only and superseded docs are absent from the tarball
 
 Current forbidden packed files include:

package/extensions/agent-browser/index.ts

@@ -18,15 +18,15 @@ import {
 	buildPromptPolicy,
 	createEphemeralSessionSeed,
 	createImplicitSessionName,
+	getImplicitSessionCloseTimeoutMs,
+	getImplicitSessionIdleTimeoutMs,
 	getLatestUserPrompt,
 	hasUsableBraveApiKey,
+	resolveImplicitSessionActiveState,
 	validateToolArgs,
 } from "./lib/runtime.js";
 import { cleanupSecureTempArtifacts } from "./lib/temp.js";
 
-const IMPLICIT_SESSION_IDLE_TIMEOUT_MS = "900000";
-const IMPLICIT_SESSION_CLOSE_TIMEOUT_MS = 5_000;
-
 const AGENT_BROWSER_PARAMS = Type.Object({
 	args: Type.Array(Type.String({ description: "Exact agent-browser CLI arguments, excluding the binary name." }), {
 		description: "Exact agent-browser CLI arguments, excluding the binary name and any shell operators.",
@@ -40,6 +40,30 @@ const AGENT_BROWSER_PARAMS = Type.Object({
 		}),
 	),
 });
+const PROJECT_RULE_PROMPT =
+	"Project rule: when browser automation is needed, prefer the native `agent_browser` tool. Do not run direct `agent-browser` bash commands unless the user explicitly asks for a bash-oriented workflow or browser-integration debugging.";
+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.";
+const SHARED_BROWSER_PLAYBOOK_GUIDELINES = [
+	"Standard workflow: open the page, snapshot -i, interact using refs, and re-snapshot after navigation or major DOM changes.",
+	"For authenticated or user-specific content like feeds, inboxes, dashboards, and accounts, prefer --profile Default on the first browser call and let the implicit session carry continuity. 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.",
+	"When using --profile, --session-name, or --cdp, 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 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 <n> / snapshot -i to recover state before retrying different URLs or fallback strategies. Only use wait with an explicit argument like milliseconds, --load, --url, --fn, or --text.",
+	"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.",
+	"When using eval --stdin, scope checks and actions to the target element or route whenever possible instead of relying on broad page-wide text heuristics.",
+	"When using eval --stdin for extraction, return the value you want instead of relying on console.log as the primary result channel.",
+	"Do not call --help or other exploratory inspection commands unless the user explicitly asks for them or debugging the browser integration is necessary.",
+] as const;
+const TOOL_PROMPT_GUIDELINES_PREFIX = ["Use this tool whenever the task requires a real browser or live web content."] as const;
+const TOOL_PROMPT_GUIDELINES_SUFFIX = [
+	"Prefer this tool over bash for opening sites, reading docs on the web, clicking, filling, screenshots, eval, and batch workflows.",
+	"Do not fall back to osascript, AppleScript, or generic browser-driving bash commands when this tool can do the job.",
+	"Pass exact agent-browser CLI arguments in args, excluding the binary name.",
+	"Use stdin for commands like eval --stdin and batch instead of shell heredocs.",
+	"Let the implicit session handle the common path unless you explicitly need upstream flags like --session, --profile, or --cdp.",
+] as const;
 
 function buildMissingBinaryMessage(): string {
 	return [
@@ -79,14 +103,38 @@ function buildInspectionDeflectionMessage(): string {
 	].join("\n");
 }
 
-function buildBraveSearchGuidance(hasBraveApiKey: boolean): string {
-	if (!hasBraveApiKey) return "";
-	return "\n- A non-empty `BRAVE_API_KEY` is available in the current environment. For web search or URL discovery, prefer the Brave Search API via `bash`/`curl` to find the destination URL, then open that URL with `agent_browser` instead of using browser automation to drive Google or another search engine results page. If the Brave request fails, fall back to the normal workflow.";
+function buildSharedBrowserPlaybookGuidelines(hasBraveApiKey: boolean): string[] {
+	return [
+		SHARED_BROWSER_PLAYBOOK_GUIDELINES[0],
+		...(hasBraveApiKey ? [BRAVE_SEARCH_PROMPT_GUIDELINE] : []),
+		...SHARED_BROWSER_PLAYBOOK_GUIDELINES.slice(1),
+	];
+}
+
+function buildBrowserSystemPromptAppendix(hasBraveApiKey: boolean): string {
+	return [
+		PROJECT_RULE_PROMPT,
+		"",
+		"Browser operating playbook:",
+		...buildSharedBrowserPlaybookGuidelines(hasBraveApiKey).map((guideline) => `- ${guideline}`),
+	].join("\n");
+}
+
+function buildToolPromptGuidelines(hasBraveApiKey: boolean): string[] {
+	return [
+		...TOOL_PROMPT_GUIDELINES_PREFIX,
+		...buildSharedBrowserPlaybookGuidelines(hasBraveApiKey),
+		...TOOL_PROMPT_GUIDELINES_SUFFIX,
+	];
 }
 
 export default function agentBrowserExtension(pi: ExtensionAPI) {
 	const ephemeralSessionSeed = createEphemeralSessionSeed();
-	const braveSearchGuidance = buildBraveSearchGuidance(hasUsableBraveApiKey());
+	const hasBraveApiKey = hasUsableBraveApiKey();
+	const browserSystemPromptAppendix = buildBrowserSystemPromptAppendix(hasBraveApiKey);
+	const toolPromptGuidelines = buildToolPromptGuidelines(hasBraveApiKey);
+	const implicitSessionIdleTimeoutMs = getImplicitSessionIdleTimeoutMs();
+	const implicitSessionCloseTimeoutMs = getImplicitSessionCloseTimeoutMs();
 	let implicitSessionActive = false;
 	let implicitSessionName = createImplicitSessionName(undefined, process.cwd(), ephemeralSessionSeed);
 	let implicitSessionCwd = process.cwd();
@@ -100,7 +148,7 @@ export default function agentBrowserExtension(pi: ExtensionAPI) {
 	pi.on("session_shutdown", async () => {
 		implicitSessionActive = false;
 		const controller = new AbortController();
-		const timer = setTimeout(() => controller.abort(), IMPLICIT_SESSION_CLOSE_TIMEOUT_MS);
+		const timer = setTimeout(() => controller.abort(), implicitSessionCloseTimeoutMs);
 		try {
 			await runAgentBrowserProcess({
 				args: ["--session", implicitSessionName, "close"],
@@ -117,10 +165,7 @@ export default function agentBrowserExtension(pi: ExtensionAPI) {
 
 	pi.on("before_agent_start", async (event) => {
 		return {
-			systemPrompt:
-				event.systemPrompt +
-				"\n\nProject rule: when browser automation is needed, prefer the native `agent_browser` tool. Do not run direct `agent-browser` bash commands unless the user explicitly asks for a bash-oriented workflow or browser-integration debugging.\n\nBrowser operating playbook:\n- Standard workflow: open the page, then snapshot -i, then interact via refs, then re-snapshot after navigation or major DOM changes.\n- For user-specific or authenticated content like feeds, inboxes, dashboards, and accounts, start with an authenticated browser strategy instead of public browsing. Prefer `--profile Default` on the first browser call and let the current implicit session carry continuity. Use `--auto-connect` only if profile-based reuse is unavailable or the task is specifically about attaching to a running debug-enabled browser.\n- 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.\n- When using startup-scoped flags like `--profile`, `--session-name`, or `--cdp`, 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.\n- 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 <n>`, and `snapshot -i` to recover state before retrying different URLs or fallback strategies. Only use `wait` with an explicit argument like milliseconds, `--load`, `--url`, `--fn`, or `--text`.\n- 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.\n- 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.\n- When using `eval --stdin`, scope checks and actions to the target element or route whenever possible instead of relying on broad page-wide text heuristics.\n- When using `eval --stdin` for extraction, return the value you want instead of relying on `console.log` as the primary result channel.\n- Do not use `agent_browser --help` for normal browsing tasks." +
-				braveSearchGuidance,
+			systemPrompt: `${event.systemPrompt}\n\n${browserSystemPromptAppendix}`,
 		};
 	});
 
@@ -146,29 +191,7 @@ export default function agentBrowserExtension(pi: ExtensionAPI) {
 			"Browse and interact with websites using agent-browser. Use this for web research, reading live docs, opening pages, taking snapshots or screenshots, clicking links, filling forms, extracting page content, and authenticated/profile-based browser work.",
 		promptSnippet:
 			"Browse websites, read live docs, click and fill pages, extract browser content, take screenshots, and automate real web workflows.",
-		promptGuidelines: [
-			"Use this tool whenever the task requires a real browser or live web content.",
-			"Standard workflow: open the page, snapshot -i, interact using refs, and re-snapshot after navigation or major DOM changes.",
-			...(braveSearchGuidance
-				? [
-					"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.",
-				  ]
-				: []),
-			"For authenticated or user-specific content like feeds, inboxes, dashboards, and accounts, prefer --profile Default on the first browser call and let the implicit session carry continuity. 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.",
-			"When using --profile, --session-name, or --cdp, 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 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 <n> / snapshot -i to recover state before retrying different URLs or fallback strategies. Only use wait with an explicit argument like milliseconds, --load, --url, --fn, or --text.",
-			"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.",
-			"When using eval --stdin, scope checks and actions to the target element or route whenever possible instead of relying on broad page-wide text heuristics.",
-			"When using eval --stdin for extraction, return the value you want instead of relying on console.log as the primary result channel.",
-			"Prefer this tool over bash for opening sites, reading docs on the web, clicking, filling, screenshots, eval, and batch workflows.",
-			"Do not call --help or other exploratory inspection commands unless the user explicitly asks for them or debugging the browser integration is necessary.",
-			"Do not fall back to osascript, AppleScript, or generic browser-driving bash commands when this tool can do the job.",
-			"Pass exact agent-browser CLI arguments in args, excluding the binary name.",
-			"Use stdin for commands like eval --stdin and batch instead of shell heredocs.",
-			"Let the implicit session handle the common path unless you explicitly need upstream flags like --session, --profile, or --cdp.",
-		],
+		promptGuidelines: toolPromptGuidelines,
 		parameters: AGENT_BROWSER_PARAMS,
 		async execute(_toolCallId, params, signal, onUpdate, ctx) {
 			const promptPolicy = buildPromptPolicy(getLatestUserPrompt(ctx.sessionManager.getBranch()));
@@ -221,16 +244,12 @@ export default function agentBrowserExtension(pi: ExtensionAPI) {
 				args: executionPlan.effectiveArgs,
 				cwd: ctx.cwd,
 				env: executionPlan.usedImplicitSession
-					? { AGENT_BROWSER_IDLE_TIMEOUT_MS: IMPLICIT_SESSION_IDLE_TIMEOUT_MS }
+					? { AGENT_BROWSER_IDLE_TIMEOUT_MS: implicitSessionIdleTimeoutMs }
 					: undefined,
 				signal,
 				stdin: params.stdin,
 			});
 
-			if (executionPlan.usedImplicitSession && !processResult.aborted && !processResult.spawnError) {
-				implicitSessionActive = executionPlan.commandInfo.command !== "close";
-			}
-
 			if (processResult.spawnError?.message.includes("ENOENT")) {
 				const errorText = buildMissingBinaryMessage();
 				return {
@@ -255,6 +274,13 @@ export default function agentBrowserExtension(pi: ExtensionAPI) {
 				const parseSucceeded = plainTextInspection || parsed.parseError === undefined;
 				const succeeded = processSucceeded && parseSucceeded && envelopeSuccess;
 
+				implicitSessionActive = resolveImplicitSessionActiveState({
+					command: executionPlan.commandInfo.command,
+					priorActive: implicitSessionActive,
+					succeeded,
+					usedImplicitSession: executionPlan.usedImplicitSession,
+				});
+
 				const errorText = getAgentBrowserErrorText({
 					aborted: processResult.aborted,
 					envelope: parsed.envelope,

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

@@ -1,6 +1,6 @@
 /**
  * Purpose: Execute the upstream agent-browser binary for the pi-agent-browser extension.
- * Responsibilities: Spawn the agent-browser subprocess without a shell, stream optional stdin, bound in-memory output buffering, spill oversized stdout safely to a private temp file, and honor abort signals.
+ * 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.
  * 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.
@@ -9,12 +9,63 @@
 import { spawn } from "node:child_process";
 import { env as processEnv } from "node:process";
 
-import { openSecureTempFile } from "./temp.js";
+import { openSecureTempFile, writeSecureTempChunk } from "./temp.js";
 
 const MAX_BUFFERED_STDOUT_BYTES = 512 * 1_024;
 const MAX_BUFFERED_STDERR_CHARS = 32_000;
 const MAX_BUFFERED_STDOUT_TAIL_CHARS = 32_000;
 const PROCESS_STDOUT_SPILL_FILE_PREFIX = "process-stdout";
+const httpProxyEnvName = "http_proxy";
+const httpsProxyEnvName = "https_proxy";
+const allProxyEnvName = "all_proxy";
+const noProxyEnvName = "no_proxy";
+const INHERITED_ENV_NAMES = new Set([
+	"ALL_PROXY",
+	"APPDATA",
+	"CI",
+	"COLORTERM",
+	"COMSPEC",
+	"DBUS_SESSION_BUS_ADDRESS",
+	"DISPLAY",
+	"FORCE_COLOR",
+	"HOME",
+	"HOMEDRIVE",
+	"HOMEPATH",
+	"HTTPS_PROXY",
+	"HTTP_PROXY",
+	"LANG",
+	"LC_ALL",
+	"LC_CTYPE",
+	"LOCALAPPDATA",
+	"LOGNAME",
+	"NO_COLOR",
+	"NO_PROXY",
+	"NODE_EXTRA_CA_CERTS",
+	"NODE_TLS_REJECT_UNAUTHORIZED",
+	"OS",
+	"PATH",
+	"PATHEXT",
+	"PWD",
+	"SHELL",
+	"SSL_CERT_DIR",
+	"SSL_CERT_FILE",
+	"SYSTEMROOT",
+	"TEMP",
+	"TERM",
+	"TMP",
+	"TMPDIR",
+	"TZ",
+	"USER",
+	"USERNAME",
+	"USERPROFILE",
+	"WAYLAND_DISPLAY",
+	"XAUTHORITY",
+	httpProxyEnvName,
+	httpsProxyEnvName,
+	allProxyEnvName,
+	noProxyEnvName,
+]);
+const INHERITED_ENV_PREFIXES = ["AGENT_BROWSER_", "AI_GATEWAY_", "XDG_"] as const;
 
 export interface ProcessRunResult {
 	aborted: boolean;
@@ -30,6 +81,34 @@ function appendTail(text: string, addition: string, maxChars: number): string {
 	return combined.length <= maxChars ? combined : combined.slice(combined.length - maxChars);
 }
 
+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;
+		}
+	}
+
+	if (!overrides) {
+		return childEnv;
+	}
+
+	for (const [name, value] of Object.entries(overrides)) {
+		if (value === undefined) {
+			delete childEnv[name];
+		} else {
+			childEnv[name] = value;
+		}
+	}
+	return childEnv;
+}
+
 export async function runAgentBrowserProcess(options: {
 	args: string[];
 	cwd: string;
@@ -55,6 +134,7 @@ export async function runAgentBrowserProcess(options: {
 
 		const queueStdoutChunk = (buffer: Buffer) => {
 			stdoutTail = appendTail(stdoutTail, buffer.toString("utf8"), MAX_BUFFERED_STDOUT_TAIL_CHARS);
+			if (stdoutSpillError) return;
 			if (!stdoutSpillPath && stdoutBufferedBytes + buffer.length <= MAX_BUFFERED_STDOUT_BYTES) {
 				stdoutBuffers.push(buffer);
 				stdoutBufferedBytes += buffer.length;
@@ -63,17 +143,22 @@ export async function runAgentBrowserProcess(options: {
 
 			pendingStdoutWrite = pendingStdoutWrite
 				.then(async () => {
-					if (!stdoutSpillHandle) {
+					if (stdoutSpillError) return;
+					if (!stdoutSpillHandle || !stdoutSpillPath) {
 						const tempFile = await openSecureTempFile(PROCESS_STDOUT_SPILL_FILE_PREFIX, ".json");
 						stdoutSpillHandle = tempFile.fileHandle;
 						stdoutSpillPath = tempFile.path;
 						if (stdoutBuffers.length > 0) {
-							await stdoutSpillHandle.writeFile(Buffer.concat(stdoutBuffers));
+							await writeSecureTempChunk({
+								content: Buffer.concat(stdoutBuffers),
+								fileHandle: stdoutSpillHandle,
+								path: stdoutSpillPath,
+							});
 							stdoutBuffers = [];
 							stdoutBufferedBytes = 0;
 						}
 					}
-					await stdoutSpillHandle.writeFile(buffer);
+					await writeSecureTempChunk({ content: buffer, fileHandle: stdoutSpillHandle, path: stdoutSpillPath });
 				})
 				.catch((error) => {
 					stdoutSpillError = error instanceof Error ? error : new Error(String(error));
@@ -106,7 +191,7 @@ export async function runAgentBrowserProcess(options: {
 
 		const child = spawn("agent-browser", args, {
 			cwd,
-			env: { ...processEnv, ...env },
+			env: buildAgentBrowserProcessEnv(processEnv, env),
 			stdio: ["pipe", "pipe", "pipe"],
 		});
 

package/extensions/agent-browser/lib/results/envelope.ts

@@ -0,0 +1,102 @@
+/**
+ * Purpose: Parse upstream agent-browser output and turn failure envelopes into actionable error text.
+ * Responsibilities: Read inline or spilled stdout, parse observed JSON envelope shapes, normalize batch arrays, and extract the most useful error text from nested upstream failures.
+ * Scope: Envelope parsing and error derivation only; content rendering and snapshot compaction live in separate modules.
+ * Usage: Imported by the public `lib/results.ts` facade and by tests through that facade.
+ * Invariants/Assumptions: Upstream `agent-browser --json` responses follow the observed `{ success, data, error }` envelope shape or the array shape returned by `batch --json`.
+ */
+
+import { readFile } from "node:fs/promises";
+
+import { type AgentBrowserBatchResult, type AgentBrowserEnvelope, isRecord, stringifyUnknown } from "./shared.js";
+
+async function readEnvelopeSource(options: { stdout: string; stdoutPath?: string }): Promise<string> {
+	if (!options.stdoutPath) {
+		return options.stdout;
+	}
+
+	try {
+		return await readFile(options.stdoutPath, "utf8");
+	} catch (error) {
+		const message = error instanceof Error ? error.message : String(error);
+		throw new Error(`agent-browser output spill file could not be read: ${message}`);
+	}
+}
+
+function extractEnvelopeErrorText(error: unknown): string | undefined {
+	if (typeof error === "string") {
+		return error.trim() || undefined;
+	}
+	if (typeof error === "number" || typeof error === "boolean") {
+		return String(error);
+	}
+	if (Array.isArray(error)) {
+		const parts = error.map((item) => extractEnvelopeErrorText(item) ?? stringifyUnknown(item)).filter((item) => item.length > 0);
+		return parts.length > 0 ? parts.join("\n") : undefined;
+	}
+	if (!isRecord(error)) {
+		return error == null ? undefined : stringifyUnknown(error);
+	}
+
+	for (const key of ["message", "error", "details", "cause", "stderr"] as const) {
+		const value = extractEnvelopeErrorText(error[key]);
+		if (value) return value;
+	}
+
+	const fallback = stringifyUnknown(error).trim();
+	return fallback.length > 0 && fallback !== "{}" ? fallback : undefined;
+}
+
+export async function parseAgentBrowserEnvelope(options: string | { stdout: string; stdoutPath?: string }): Promise<{
+	envelope?: AgentBrowserEnvelope;
+	parseError?: string;
+}> {
+	let stdout: string;
+	try {
+		stdout = typeof options === "string" ? options : await readEnvelopeSource(options);
+	} catch (error) {
+		return { parseError: error instanceof Error ? error.message : String(error) };
+	}
+
+	const trimmed = stdout.trim();
+	if (trimmed.length === 0) {
+		return { parseError: "agent-browser returned no JSON output." };
+	}
+
+	try {
+		const parsed = JSON.parse(trimmed) as AgentBrowserEnvelope | AgentBrowserBatchResult[];
+		if (Array.isArray(parsed)) {
+			return { envelope: { success: parsed.every((item) => !isRecord(item) || item.success !== false), data: parsed } };
+		}
+		if (!isRecord(parsed)) {
+			return { parseError: "agent-browser returned JSON, but it was not an object envelope." };
+		}
+		return { envelope: parsed };
+	} catch (error) {
+		const message = error instanceof Error ? error.message : String(error);
+		return { parseError: `agent-browser returned invalid JSON: ${message}` };
+	}
+}
+
+export function getAgentBrowserErrorText(options: {
+	aborted: boolean;
+	envelope?: AgentBrowserEnvelope;
+	exitCode: number;
+	parseError?: string;
+	plainTextInspection: boolean;
+	spawnError?: Error;
+	stderr: string;
+}): string | undefined {
+	const { aborted, envelope, exitCode, parseError, plainTextInspection, spawnError, stderr } = options;
+	if (plainTextInspection) return undefined;
+	if (aborted) return "agent-browser was aborted.";
+	if (spawnError) return spawnError.message;
+	if (parseError) return parseError;
+	if (envelope?.success === false) {
+		return extractEnvelopeErrorText(envelope.error) ?? (stderr.trim() || `agent-browser reported failure${exitCode !== 0 ? ` (exit code ${exitCode})` : "."}`);
+	}
+	if (exitCode !== 0) {
+		return stderr.trim() || `agent-browser exited with code ${exitCode}.`;
+	}
+	return undefined;
+}