pi-agent-browser-native 0.1.5 → 0.2.0

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;
+}