pi-agent-browser-native 0.1.1

package/docs/TOOL_CONTRACT.md

@@ -0,0 +1,168 @@
+# Tool contract
+
+Related docs:
+- [`../README.md`](../README.md)
+- [`REQUIREMENTS.md`](REQUIREMENTS.md)
+- [`ARCHITECTURE.md`](ARCHITECTURE.md)
+
+## V1 tool
+
+V1 should expose one primary native tool:
+
+- `agent_browser`
+
+## Why this tool shape
+
+This keeps the integration:
+- thin
+- powerful
+- low-drift
+- low-maintenance
+- close to upstream `agent-browser`
+
+It also keeps the main UX where it belongs: the agent invokes the tool directly instead of relying on bash or a large manual command surface.
+
+The tool guidance should be written for task discovery first, not wrapper implementation first. That means the description should emphasize browser use cases like web research, reading live docs, clicking, filling, screenshots, extraction, and authenticated/profile-based workflows. Low-level wrapper details like `stdin` and exact CLI args belong in the schema and guidelines, not the lead description.
+
+The tool also needs an operating playbook, not just a capability list. The model should not have to rediscover basics each session. Guidance should explicitly encode the normal browser workflow (`open` -> `snapshot -i` -> interact -> re-snapshot), the authenticated-content workflow (prefer `--profile Default` on the first browser call and let the implicit session carry continuity; use `--auto-connect` as a fallback when profile reuse is unavailable), and the preferred recovery path when a session opens on the wrong tab, an action changes origin unexpectedly, or an `open` call returns blocked/blank/unexpected results (`tab list` / `tab <n>` / `snapshot -i` before retrying different URLs or fallback strategies). It should also discourage inventing fixed explicit session names for routine tasks, because those names leak stale browser state across otherwise unrelated `pi` sessions. For read-only browsing tasks, guidance should prefer answering from the current page state first: use the current snapshot, structured ref labels, or `eval --stdin` on the current page before navigating into media viewers, detail routes, or other new pages unless the current view lacks 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 intended value instead of relying on `console.log` as the primary result channel.
+
+## Parameters
+
+```json
+{
+  "args": ["open", "https://example.com"],
+  "stdin": "optional raw stdin content",
+  "useActiveSession": true
+}
+```
+
+### `args`
+
+- type: `string[]`
+- required
+- exact CLI args passed after `agent-browser`
+- no shell operators
+- do not include the binary name
+
+Examples:
+
+```json
+{ "args": ["open", "https://example.com"] }
+{ "args": ["snapshot", "-i"] }
+{ "args": ["click", "@e2"] }
+{ "args": ["tab", "list"] }
+```
+
+### `stdin`
+
+- type: `string`
+- optional
+- raw stdin for commands like `eval --stdin` and `batch`
+
+Examples:
+
+```json
+{ "args": ["eval", "--stdin"], "stdin": "document.title" }
+```
+
+```json
+{ "args": ["batch"], "stdin": "[[\"open\",\"https://example.com\"],[\"snapshot\",\"-i\"]]" }
+```
+
+### `useActiveSession`
+
+- type: `boolean`
+- optional
+- default: `true`
+
+Behavior:
+- if `args` already include `--session`, upstream session choice wins
+- otherwise the extension prepends its implicit active session when `useActiveSession` is `true`
+
+## Wrapper behavior
+
+The extension should:
+- inject `--json`
+- invoke `agent-browser` directly, not through a shell
+- parse JSON output into tool details
+- handle observed JSON result shapes, including the array returned by `batch --json`
+- allow plain-text fallback for inspection commands like `--help` and `--version`
+- discourage exploratory inspection calls unless the user explicitly asks or debugging requires them
+- deflect normal-task `--help` inspection back into the standard browser workflow instead of letting the model relearn the tool from scratch each session
+- surface stderr and non-zero exits clearly
+- attach images when the result points to a screenshot-like artifact
+
+## Result shape
+
+### Content
+
+Primary content should be:
+- useful result text for the model, not just a status line
+- an image attachment when relevant
+- browser-aware compacting for oversized snapshots so the model gets a concise actionable view before raw page noise
+- compact snapshots should be main-content-first: prefer the primary content block and nearby sections over top-of-page chrome, ads, or unrelated sidebars when those can be distinguished from the snapshot tree
+
+Examples:
+- small `snapshot` results should include the actual snapshot text
+- oversized `snapshot` results should switch to a compact view that preserves the primary content, nearby sections, high-value refs, and a path to the spilled full raw snapshot
+- `tab list` should include a readable tab summary
+- `screenshot` should include the saved-path summary plus the inline image attachment when available
+
+### Details
+
+Recommended details:
+
+```json
+{
+  "args": ["snapshot", "-i"],
+  "effectiveArgs": ["--session", "pi-abc123", "--json", "snapshot", "-i"],
+  "sessionName": "pi-abc123",
+  "usedImplicitSession": true,
+  "data": {
+    "origin": "https://example.com/",
+    "refs": {
+      "e1": { "name": "Example Domain", "role": "heading" }
+    },
+    "snapshot": "- heading \"Example Domain\" [level=1, ref=e1]"
+  }
+}
+```
+
+For oversized snapshots, details should switch to a compact metadata object and include `fullOutputPath` pointing at a private temp JSON spill file with the full upstream snapshot payload.
+
+## High-value result rendering
+
+"Rendering" here means how results appear inside `pi`, not embedding a browser UI.
+
+Worth doing in v1:
+- screenshots → inline image attachment
+- snapshots → origin + ref count + main-content-first compact preview, with full raw snapshot spill files when the inline result would otherwise be too large
+- tab lists → compact summary/table
+- stream status → enabled/connected/port summary
+
+## Missing binary behavior
+
+If `agent-browser` is not on `PATH`, fail with a message that:
+- says `agent-browser` is required
+- says this project does not bundle it
+- points to upstream install/docs
+
+## Session behavior
+
+- maintain one implicit active session per `pi` session for the common path
+- derive that implicit session from the official `pi` session id
+- respect explicit upstream `--session` with minimal interference
+- treat the implicit session as extension-managed convenience state
+- on normal `pi` shutdown, best-effort close the implicit session
+- set an idle timeout on implicit sessions so abandoned daemons eventually self-clean
+- clean up private temp spill artifacts owned by the implicit session on shutdown
+- treat explicit upstream session choices like `--session`, `--profile`, `--session-name`, and `--cdp` as user-managed
+- pass explicit `--profile` straight through to upstream `agent-browser`; no profile-cloning or isolation layer is added in v1
+- if startup-scoped flags like `--profile`, `--session-name`, or `--cdp` are supplied after the implicit session is already active, return a validation error instead of silently relying on upstream to ignore them
+
+## Non-goals
+
+- no giant action enum mirroring the whole upstream CLI
+- no support for older `agent-browser` versions
+- no compatibility shims
+- no embedded browser UI inside `pi`

package/extensions/agent-browser/index.ts

@@ -0,0 +1,297 @@
+/**
+ * Purpose: Register the native agent_browser tool for pi so agents can invoke agent-browser without going through bash.
+ * Responsibilities: Define the tool schema, inject thin wrapper behavior around the upstream CLI, manage implicit session convenience, and return pi-friendly content/details.
+ * Scope: Native tool registration and orchestration only; the wrapper intentionally stays close to the upstream agent-browser CLI.
+ * Usage: Loaded by pi through the package manifest or the local `.pi/extensions/agent-browser.ts` development entrypoint.
+ * Invariants/Assumptions: agent-browser is installed separately on PATH, the wrapper targets the current locally installed upstream version only, and no backward-compatibility shims are provided.
+ */
+
+import { rm } from "node:fs/promises";
+
+import { isToolCallEventType, type ExtensionAPI } from "@mariozechner/pi-coding-agent";
+import { Type } from "@sinclair/typebox";
+
+import { runAgentBrowserProcess } from "./lib/process.js";
+import { buildToolPresentation, getAgentBrowserErrorText, parseAgentBrowserEnvelope } from "./lib/results.js";
+import {
+	buildExecutionPlan,
+	buildPromptPolicy,
+	createEphemeralSessionSeed,
+	createImplicitSessionName,
+	getLatestUserPrompt,
+	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.",
+		minItems: 1,
+	}),
+	stdin: Type.Optional(Type.String({ description: "Optional raw stdin content for commands like eval --stdin or batch." })),
+	useActiveSession: Type.Optional(
+		Type.Boolean({
+			description: "When true and no explicit --session is present, inject the implicit session for this pi session.",
+			default: true,
+		}),
+	),
+});
+
+function buildMissingBinaryMessage(): string {
+	return [
+		"agent-browser is required but was not found on PATH.",
+		"This project does not bundle agent-browser.",
+		"Install it using the upstream docs:",
+		"- https://agent-browser.dev/",
+		"- https://github.com/vercel-labs/agent-browser",
+	].join("\n");
+}
+
+function buildInvocationPreview(effectiveArgs: string[]): string {
+	const preview = effectiveArgs.join(" ");
+	return preview.length > 120 ? `${preview.slice(0, 117)}...` : preview;
+}
+
+function looksLikeDirectAgentBrowserBash(command: string): boolean {
+	return /(^|[\s;&|])(npx\s+)?agent-browser(\s|$)/.test(command);
+}
+
+function isHarmlessAgentBrowserInspectionCommand(command: string): boolean {
+	return /(command\s+-v|which)\s+agent-browser\b/.test(command) || /(^|\s)agent-browser\s+--(help|version)\b/.test(command);
+}
+
+function isPlainTextInspectionArgs(args: string[]): boolean {
+	return args.includes("--help") || args.includes("-h") || args.includes("--version") || args.includes("-V");
+}
+
+function buildInspectionDeflectionMessage(): string {
+	return [
+		"Do not inspect agent_browser help for a normal browser task.",
+		"Use the workflow directly:",
+		"1. open the target URL",
+		"2. snapshot -i",
+		"3. interact using refs and re-snapshot after navigation or major DOM changes",
+		"For authenticated or user-specific content like feeds, inboxes, dashboards, or accounts, start with an authenticated strategy such as --profile Default on the first browser call and let the implicit session carry continuity. Use --auto-connect only if profile-based reuse is unavailable.",
+	].join("\n");
+}
+
+export default function agentBrowserExtension(pi: ExtensionAPI) {
+	const ephemeralSessionSeed = createEphemeralSessionSeed();
+	let implicitSessionActive = false;
+	let implicitSessionName = createImplicitSessionName(undefined, process.cwd(), ephemeralSessionSeed);
+	let implicitSessionCwd = process.cwd();
+
+	pi.on("session_start", async (_event, ctx) => {
+		implicitSessionActive = false;
+		implicitSessionName = createImplicitSessionName(ctx.sessionManager.getSessionId(), ctx.cwd, ephemeralSessionSeed);
+		implicitSessionCwd = ctx.cwd;
+	});
+
+	pi.on("session_shutdown", async () => {
+		implicitSessionActive = false;
+		const controller = new AbortController();
+		const timer = setTimeout(() => controller.abort(), IMPLICIT_SESSION_CLOSE_TIMEOUT_MS);
+		try {
+			await runAgentBrowserProcess({
+				args: ["--session", implicitSessionName, "close"],
+				cwd: implicitSessionCwd,
+				signal: controller.signal,
+			});
+		} catch {
+			// Best-effort cleanup only.
+		} finally {
+			clearTimeout(timer);
+			await cleanupSecureTempArtifacts();
+		}
+	});
+
+	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.",
+		};
+	});
+
+	pi.on("tool_call", async (event, ctx) => {
+		const promptPolicy = buildPromptPolicy(getLatestUserPrompt(ctx.sessionManager.getBranch()));
+		if (
+			isToolCallEventType("bash", event) &&
+			!promptPolicy.allowLegacyAgentBrowserBash &&
+			looksLikeDirectAgentBrowserBash(event.input.command) &&
+			!isHarmlessAgentBrowserInspectionCommand(event.input.command)
+		) {
+			return {
+				block: true,
+				reason: "Use the native agent_browser tool instead of bash for agent-browser in this environment.",
+			};
+		}
+	});
+
+	pi.registerTool({
+		name: "agent_browser",
+		label: "Agent Browser",
+		description:
+			"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.",
+			"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.",
+		],
+		parameters: AGENT_BROWSER_PARAMS,
+		async execute(_toolCallId, params, signal, onUpdate, ctx) {
+			const promptPolicy = buildPromptPolicy(getLatestUserPrompt(ctx.sessionManager.getBranch()));
+			if (!promptPolicy.allowAgentBrowserInspection && isPlainTextInspectionArgs(params.args)) {
+				const errorText = buildInspectionDeflectionMessage();
+				return {
+					content: [{ type: "text", text: errorText }],
+					details: { args: params.args, inspectionBlocked: true },
+					isError: true,
+				};
+			}
+
+			const validationError = validateToolArgs(params.args);
+			if (validationError) {
+				return {
+					content: [{ type: "text", text: validationError }],
+					details: { args: params.args, validationError },
+					isError: true,
+				};
+			}
+
+			const executionPlan = buildExecutionPlan(params.args, {
+				implicitSessionActive,
+				implicitSessionName,
+				useActiveSession: params.useActiveSession ?? true,
+			});
+
+			if (executionPlan.validationError) {
+				return {
+					content: [{ type: "text", text: executionPlan.validationError }],
+					details: {
+						args: params.args,
+						startupScopedFlags: executionPlan.startupScopedFlags,
+						validationError: executionPlan.validationError,
+					},
+					isError: true,
+				};
+			}
+
+			onUpdate?.({
+				content: [{ type: "text", text: `Running agent-browser ${buildInvocationPreview(executionPlan.effectiveArgs)}` }],
+				details: {
+					effectiveArgs: executionPlan.effectiveArgs,
+					sessionName: executionPlan.sessionName,
+					usedImplicitSession: executionPlan.usedImplicitSession,
+				},
+			});
+
+			const processResult = await runAgentBrowserProcess({
+				args: executionPlan.effectiveArgs,
+				cwd: ctx.cwd,
+				env: executionPlan.usedImplicitSession
+					? { AGENT_BROWSER_IDLE_TIMEOUT_MS: IMPLICIT_SESSION_IDLE_TIMEOUT_MS }
+					: 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 {
+					content: [{ type: "text", text: errorText }],
+					details: {
+						args: params.args,
+						effectiveArgs: executionPlan.effectiveArgs,
+						spawnError: processResult.spawnError.message,
+					},
+					isError: true,
+				};
+			}
+
+			try {
+				const parsed = await parseAgentBrowserEnvelope({
+					stdout: processResult.stdout,
+					stdoutPath: processResult.stdoutSpillPath,
+				});
+				const processSucceeded = !processResult.aborted && !processResult.spawnError && processResult.exitCode === 0;
+				const plainTextInspection = isPlainTextInspectionArgs(params.args) && processSucceeded && parsed.parseError !== undefined;
+				const envelopeSuccess = plainTextInspection ? true : parsed.envelope?.success !== false;
+				const parseSucceeded = plainTextInspection || parsed.parseError === undefined;
+				const succeeded = processSucceeded && parseSucceeded && envelopeSuccess;
+
+				const errorText = getAgentBrowserErrorText({
+					aborted: processResult.aborted,
+					envelope: parsed.envelope,
+					exitCode: processResult.exitCode,
+					parseError: parsed.parseError,
+					plainTextInspection,
+					spawnError: processResult.spawnError,
+					stderr: processResult.stderr,
+				});
+
+				const presentation = plainTextInspection
+					? {
+						content: [{ type: "text" as const, text: processResult.stdout.trim() }],
+						imagePath: undefined,
+						summary: `${params.args.join(" ")} completed`,
+					  }
+					: await buildToolPresentation({
+							commandInfo: executionPlan.commandInfo,
+							cwd: ctx.cwd,
+							envelope: parsed.envelope,
+							errorText,
+					  });
+
+				return {
+					content: presentation.content,
+					details: {
+						args: params.args,
+						command: executionPlan.commandInfo.command,
+						subcommand: executionPlan.commandInfo.subcommand,
+						data: presentation.data,
+						error: parsed.envelope?.error,
+						effectiveArgs: executionPlan.effectiveArgs,
+						exitCode: processResult.exitCode,
+						fullOutputPath: presentation.fullOutputPath,
+						imagePath: presentation.imagePath,
+						parseError: parsed.parseError,
+						sessionName: executionPlan.sessionName,
+						startupScopedFlags: executionPlan.startupScopedFlags,
+						stderr: processResult.stderr || undefined,
+						stdout: parseSucceeded ? undefined : processResult.stdout,
+						summary: presentation.summary,
+						usedImplicitSession: executionPlan.usedImplicitSession,
+					},
+					isError: !succeeded,
+				};
+			} finally {
+				if (processResult.stdoutSpillPath) {
+					await rm(processResult.stdoutSpillPath, { force: true }).catch(() => undefined);
+				}
+			}
+		},
+	});
+}

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

@@ -0,0 +1,148 @@
+/**
+ * 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.
+ * 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.
+ */
+
+import { spawn } from "node:child_process";
+import { env as processEnv } from "node:process";
+
+import { openSecureTempFile } 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";
+
+export interface ProcessRunResult {
+	aborted: boolean;
+	exitCode: number;
+	spawnError?: Error;
+	stderr: string;
+	stdout: string;
+	stdoutSpillPath?: string;
+}
+
+function appendTail(text: string, addition: string, maxChars: number): string {
+	const combined = text + addition;
+	return combined.length <= maxChars ? combined : combined.slice(combined.length - maxChars);
+}
+
+export async function runAgentBrowserProcess(options: {
+	args: string[];
+	cwd: string;
+	env?: NodeJS.ProcessEnv;
+	signal?: AbortSignal;
+	stdin?: string;
+}): Promise<ProcessRunResult> {
+	const { args, cwd, env, signal, stdin } = options;
+
+	return await new Promise<ProcessRunResult>((resolve) => {
+		let aborted = false;
+		let settled = false;
+		let spawnError: Error | undefined;
+		let stderr = "";
+		let stdoutBuffers: Buffer[] = [];
+		let stdoutBufferedBytes = 0;
+		let stdoutTail = "";
+		let stdoutSpillHandle: Awaited<ReturnType<typeof openSecureTempFile>>["fileHandle"] | undefined;
+		let stdoutSpillPath: string | undefined;
+		let pendingStdoutWrite = Promise.resolve();
+		let stdoutSpillError: Error | undefined;
+		let killTimer: NodeJS.Timeout | undefined;
+
+		const queueStdoutChunk = (buffer: Buffer) => {
+			stdoutTail = appendTail(stdoutTail, buffer.toString("utf8"), MAX_BUFFERED_STDOUT_TAIL_CHARS);
+			if (!stdoutSpillPath && stdoutBufferedBytes + buffer.length <= MAX_BUFFERED_STDOUT_BYTES) {
+				stdoutBuffers.push(buffer);
+				stdoutBufferedBytes += buffer.length;
+				return;
+			}
+
+			pendingStdoutWrite = pendingStdoutWrite
+				.then(async () => {
+					if (!stdoutSpillHandle) {
+						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));
+							stdoutBuffers = [];
+							stdoutBufferedBytes = 0;
+						}
+					}
+					await stdoutSpillHandle.writeFile(buffer);
+				})
+				.catch((error) => {
+					stdoutSpillError = error instanceof Error ? error : new Error(String(error));
+				});
+		};
+
+		const finish = (exitCode: number) => {
+			if (settled) return;
+			settled = true;
+			void pendingStdoutWrite.finally(async () => {
+				if (killTimer) {
+					clearTimeout(killTimer);
+				}
+				if (stdoutSpillHandle) {
+					await stdoutSpillHandle.close().catch(() => undefined);
+				}
+				if (!spawnError && stdoutSpillError) {
+					spawnError = stdoutSpillError;
+				}
+				resolve({
+					aborted,
+					exitCode,
+					spawnError,
+					stderr,
+					stdout: stdoutSpillPath ? stdoutTail : Buffer.concat(stdoutBuffers).toString("utf8"),
+					stdoutSpillPath,
+				});
+			});
+		};
+
+		const child = spawn("agent-browser", args, {
+			cwd,
+			env: { ...processEnv, ...env },
+			stdio: ["pipe", "pipe", "pipe"],
+		});
+
+		const abortChild = () => {
+			aborted = true;
+			child.kill("SIGTERM");
+			killTimer = setTimeout(() => {
+				child.kill("SIGKILL");
+			}, 2_000);
+		};
+
+		child.once("error", (error) => {
+			spawnError = error instanceof Error ? error : new Error(String(error));
+			finish(127);
+		});
+		child.once("close", (code) => {
+			finish(code ?? (spawnError ? 127 : 0));
+		});
+		child.stdout.on("data", (chunk: Buffer | string) => {
+			queueStdoutChunk(Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk));
+		});
+		child.stderr.on("data", (chunk: Buffer | string) => {
+			stderr = appendTail(stderr, chunk.toString(), MAX_BUFFERED_STDERR_CHARS);
+		});
+
+		if (signal) {
+			if (signal.aborted) {
+				abortChild();
+			} else {
+				signal.addEventListener("abort", abortChild, { once: true });
+			}
+		}
+
+		if (stdin) {
+			child.stdin.write(stdin);
+		}
+		child.stdin.end();
+	});
+}