@gajae-code/coding-agent 0.12.21 → 0.13.0

package/src/tools/browser/runtime-diagnostics.ts

@@ -0,0 +1,249 @@
+import { createHash } from "node:crypto";
+import type { CDPSession, Page } from "puppeteer-core";
+
+const MAX_RUNTIME_DIAGNOSTICS = 20;
+
+/** Hard cap on the `url` field (chars). Truncation is visible: the value ends in `…`. */
+const MAX_RUNTIME_DIAGNOSTIC_URL_CHARS = 256;
+
+/** Hard cap on the serialized diagnostics block (UTF-8 bytes) emitted into tool results. */
+const MAX_RUNTIME_DIAGNOSTICS_BLOCK_BYTES = 4 * 1024;
+
+/**
+ * Fixed allowlist of built-in error class names. Page-controlled class names (anything
+ * defined by page scripts, e.g. `CustomerAlice123`) are never echoed: a diagnostic's
+ * `class` field is emitted only when it matches one of these fixed names.
+ */
+const ERROR_CLASS_ALLOWLIST = new Set([
+	"Error",
+	"EvalError",
+	"RangeError",
+	"ReferenceError",
+	"SyntaxError",
+	"TypeError",
+	"URIError",
+	"AggregateError",
+	"InternalError",
+	"DOMException",
+	"AbortError",
+	"CompileError",
+	"DataError",
+	"EncodingError",
+	"HierarchyRequestError",
+	"IndexSizeError",
+	"InvalidAccessError",
+	"InvalidCharacterError",
+	"InvalidModificationError",
+	"InvalidNodeTypeError",
+	"InvalidStateError",
+	"LinkError",
+	"NamespaceError",
+	"NetworkError",
+	"NoModificationAllowedError",
+	"NotFoundError",
+	"NotReadableError",
+	"NotSupportedError",
+	"OperationError",
+	"QuotaExceededError",
+	"ReadOnlyError",
+	"RuntimeError",
+	"SecurityError",
+	"TimeoutError",
+	"TransactionInactiveError",
+	"VersionError",
+	"WrongDocumentError",
+]);
+
+/**
+ * Fixed, page-uncontrollable script-URL literals that V8 reports in stack frames and
+ * exception details. These are safe to surface verbatim; anything else that is not a
+ * parseable URL is emitted as an irreversible hash so a raw path/token cannot leak.
+ */
+const SAFE_NON_URL_LITERALS = new Set([
+	"",
+	"eval",
+	"anonymous",
+	"script",
+	"[native code]",
+	"__puppeteer_evaluation_script__",
+]);
+
+/** `about:` paths are page-navigable, so keep only browser-fixed safe names. */
+const SAFE_ABOUT_PATH = /^[A-Za-z0-9._-]{1,32}$/;
+
+export interface BrowserRuntimeDiagnostic {
+	kind: "pageerror" | "console-error";
+	at: string;
+	url: string;
+	line?: number;
+	column?: number;
+	class?: string;
+}
+
+interface ExceptionThrownEvent {
+	exceptionDetails?: {
+		url?: string;
+		lineNumber?: number;
+		columnNumber?: number;
+		exception?: { className?: string };
+	};
+}
+
+interface ConsoleCalledEvent {
+	type?: string;
+	stackTrace?: { callFrames?: Array<{ url?: string; lineNumber?: number; columnNumber?: number }> };
+}
+
+function sha256Hex(value: string): string {
+	return createHash("sha256").update(value).digest("hex");
+}
+
+/**
+ * Reduce a runtime-event URL to a persisted-safe location.
+ *
+ * http(s) URLs are emitted origin-only: path segments routinely carry tokens (signed
+ * URLs, invite/reset links, per-tenant identifiers), and diagnostics end up in tool
+ * results that are persisted and shareable. Non-parseable values are never echoed
+ * verbatim — known engine literals pass through, everything else becomes an
+ * irreversible bounded hash so entries stay correlatable without leaking.
+ */
+export function maskBrowserRuntimeUrl(value: string): string {
+	let url: URL | undefined;
+	try {
+		url = new URL(value);
+	} catch {
+		url = undefined;
+	}
+	if (url) {
+		if (url.protocol === "http:" || url.protocol === "https:") {
+			return boundUrlField(url.origin);
+		}
+		if (url.protocol === "about:") {
+			const path = url.pathname && SAFE_ABOUT_PATH.test(url.pathname) ? `about:${url.pathname}` : "about:…";
+			return boundUrlField(path);
+		}
+		return boundUrlField(`${url.protocol}…`);
+	}
+	if (SAFE_NON_URL_LITERALS.has(value)) return value;
+	return `[non-url:${sha256Hex(value).slice(0, 8)}]`;
+}
+
+function finite(value: unknown): number | undefined {
+	return typeof value === "number" && Number.isFinite(value) ? value : undefined;
+}
+
+export function pageErrorDiagnostic(event: ExceptionThrownEvent, fallbackUrl: string): BrowserRuntimeDiagnostic {
+	const details = event.exceptionDetails;
+	const className = details?.exception?.className;
+	return {
+		kind: "pageerror",
+		at: new Date().toISOString(),
+		url: maskBrowserRuntimeUrl(details?.url || fallbackUrl),
+		...(finite(details?.lineNumber) === undefined ? {} : { line: details?.lineNumber }),
+		...(finite(details?.columnNumber) === undefined ? {} : { column: details?.columnNumber }),
+		...(typeof className === "string" && ERROR_CLASS_ALLOWLIST.has(className) ? { class: className } : {}),
+	};
+}
+
+export function consoleErrorDiagnostic(
+	event: ConsoleCalledEvent,
+	fallbackUrl: string,
+): BrowserRuntimeDiagnostic | undefined {
+	if (event.type !== "error") return undefined;
+	const frame = event.stackTrace?.callFrames?.[0];
+	return {
+		kind: "console-error",
+		at: new Date().toISOString(),
+		url: maskBrowserRuntimeUrl(frame?.url || fallbackUrl),
+		...(finite(frame?.lineNumber) === undefined ? {} : { line: frame?.lineNumber }),
+		...(finite(frame?.columnNumber) === undefined ? {} : { column: frame?.columnNumber }),
+	};
+}
+
+function boundUrlField(url: string): string {
+	if (url.length <= MAX_RUNTIME_DIAGNOSTIC_URL_CHARS) return url;
+	return `${url.slice(0, MAX_RUNTIME_DIAGNOSTIC_URL_CHARS - 1)}…`;
+}
+
+/**
+ * Serialize a drained mailbox into the tool-result text block.
+ *
+ * - Per-field: `url` is capped with a visible `…` marker; every other field is
+ *   structurally bounded (ISO timestamp, finite integers, allowlisted class).
+ * - Total: the serialized block is capped at `MAX_RUNTIME_DIAGNOSTICS_BLOCK_BYTES`.
+ *   When the budget is tight the oldest entries are shed (newest survive) and the
+ *   block carries an explicit `runtimeDiagnosticsTruncated: true` — truncation is
+ *   never silent.
+ */
+export function serializeRuntimeDiagnostics(drained: {
+	runtimeDiagnostics: BrowserRuntimeDiagnostic[];
+	runtimeDiagnosticsDropped: number;
+}): string {
+	const { runtimeDiagnostics, runtimeDiagnosticsDropped } = drained;
+	const bounded = runtimeDiagnostics.map(entry => ({ ...entry, url: boundUrlField(entry.url) }));
+	const encoder = new TextEncoder();
+	const render = (entries: BrowserRuntimeDiagnostic[], truncated: boolean): string =>
+		JSON.stringify(
+			{
+				runtimeDiagnostics: entries,
+				runtimeDiagnosticsDropped,
+				...(truncated ? { runtimeDiagnosticsTruncated: true } : {}),
+			},
+			null,
+			2,
+		);
+	let kept = bounded;
+	let text = render(kept, false);
+	while (encoder.encode(text).byteLength > MAX_RUNTIME_DIAGNOSTICS_BLOCK_BYTES && kept.length > 1) {
+		kept = kept.slice(1);
+		text = render(kept, true);
+	}
+	// A single entry can exceed the budget only on type-violating input (every field is
+	// structurally bounded); the block still surfaces the entry, but truncation is
+	// never silent — flag the over-budget block explicitly.
+	if (encoder.encode(text).byteLength > MAX_RUNTIME_DIAGNOSTICS_BLOCK_BYTES) {
+		text = render(kept, true);
+	}
+	return text;
+}
+
+export class BrowserRuntimeDiagnosticsMailbox {
+	#entries: BrowserRuntimeDiagnostic[] = [];
+	#dropped = 0;
+
+	push(entry: BrowserRuntimeDiagnostic): void {
+		if (this.#entries.length === MAX_RUNTIME_DIAGNOSTICS) {
+			this.#entries.shift();
+			this.#dropped += 1;
+		}
+		this.#entries.push(entry);
+	}
+
+	drain(): { runtimeDiagnostics: BrowserRuntimeDiagnostic[]; runtimeDiagnosticsDropped: number } {
+		const runtimeDiagnostics = this.#entries.splice(0);
+		const runtimeDiagnosticsDropped = this.#dropped;
+		this.#dropped = 0;
+		return { runtimeDiagnostics, runtimeDiagnosticsDropped };
+	}
+}
+
+export async function instrumentBrowserRuntimeDiagnostics(
+	page: Page,
+	mailbox: BrowserRuntimeDiagnosticsMailbox,
+): Promise<CDPSession> {
+	const session = await page.target().createCDPSession();
+	session.on("Runtime.exceptionThrown", event => {
+		mailbox.push(pageErrorDiagnostic(event, page.url()));
+	});
+	session.on("Runtime.consoleAPICalled", event => {
+		const diagnostic = consoleErrorDiagnostic(event, page.url());
+		if (diagnostic) mailbox.push(diagnostic);
+	});
+	try {
+		await session.send("Runtime.enable");
+		return session;
+	} catch (error) {
+		await session.detach().catch(() => undefined);
+		throw error;
+	}
+}

package/src/tools/browser/tab-protocol.ts

@@ -51,6 +51,8 @@ export type WorkerInitPayload =
 			url?: string;
 			waitUntil?: "load" | "domcontentloaded" | "networkidle0" | "networkidle2";
 			timeoutMs: number;
+			/** Opt-in bounded page runtime diagnostics (extra CDP session + Runtime events). */
+			runtimeDiagnostics?: boolean;
 	  }
 	| {
 			mode: "attach";
@@ -58,6 +60,8 @@ export type WorkerInitPayload =
 			safeDir: string;
 			targetId: string;
 			dialogs?: "accept" | "dismiss";
+			/** Opt-in bounded page runtime diagnostics (extra CDP session + Runtime events). */
+			runtimeDiagnostics?: boolean;
 	  };
 
 export type ToolReply = { ok: true; value: unknown } | { ok: false; error: RunErrorPayload };

package/src/tools/browser/tab-supervisor.ts

@@ -81,6 +81,8 @@ export interface AcquireTabOptions {
 	dialogs?: DialogPolicy;
 	/** Owning session id so dispose can release only this session's tabs (F13). */
 	ownerId?: string;
+	/** Opt-in bounded page runtime diagnostics (extra CDP session + Runtime events per tab). */
+	runtimeDiagnostics?: boolean;
 	/** Internal recovery-only target id; makes a headless replacement attach, not open a page. */
 	recoveryTargetId?: string;
 	/** Recovery fence: replacement must not overwrite a tab installed after dead teardown. */
@@ -666,6 +668,7 @@ async function buildInitPayload(browser: BrowserHandle, opts: AcquireTabOptions)
 			safeDir,
 			targetId: opts.recoveryTargetId,
 			dialogs: opts.dialogs,
+			...(opts.runtimeDiagnostics ? { runtimeDiagnostics: true } : {}),
 		};
 	}
 	if (browser.kind.kind === "headless") {
@@ -679,6 +682,7 @@ async function buildInitPayload(browser: BrowserHandle, opts: AcquireTabOptions)
 			url: opts.url,
 			waitUntil: opts.waitUntil,
 			timeoutMs: opts.timeoutMs,
+			...(opts.runtimeDiagnostics ? { runtimeDiagnostics: true } : {}),
 		};
 	}
 	const page = await pickElectronTarget(browser.browser, opts.target);
@@ -689,6 +693,7 @@ async function buildInitPayload(browser: BrowserHandle, opts: AcquireTabOptions)
 		safeDir,
 		targetId,
 		dialogs: opts.dialogs,
+		...(opts.runtimeDiagnostics ? { runtimeDiagnostics: true } : {}),
 	};
 }
 export async function buildInitPayloadForTest(

package/src/tools/browser/tab-worker.ts

@@ -7,6 +7,7 @@ import { Snowflake } from "@gajae-code/utils/snowflake";
 import type { HTMLElement } from "linkedom";
 import type {
 	Browser,
+	CDPSession,
 	Dialog,
 	ElementHandle,
 	HTTPResponse,
@@ -27,6 +28,11 @@ import {
 	loadPuppeteerInWorker,
 } from "./launch";
 import { extractReadableFromHtml, type ReadableFormat, type ReadableResult } from "./readable";
+import {
+	BrowserRuntimeDiagnosticsMailbox,
+	instrumentBrowserRuntimeDiagnostics,
+	serializeRuntimeDiagnostics,
+} from "./runtime-diagnostics";
 import { formatScreenshot } from "./screenshot-format";
 import type {
 	Observation,
@@ -75,6 +81,16 @@ const INTERACTIVE_AX_ROLES = new Set([
 
 const LEGACY_SELECTOR_PREFIXES = ["p-aria/", "p-text/", "p-xpath/", "p-pierce/"] as const;
 
+/**
+ * Test seam: override the worker's puppeteer loader so WorkerCore-level tests can
+ * inject a fake browser/page without a live Chromium. Mirrors the supervisor's
+ * `__setAcquireTabWorkerDepsForTest` pattern.
+ */
+let loadPuppeteerInWorkerForTest: typeof loadPuppeteerInWorker | undefined;
+export function __setLoadPuppeteerInWorkerForTest(loader: typeof loadPuppeteerInWorker | undefined): void {
+	loadPuppeteerInWorkerForTest = loader;
+}
+
 type DialogPolicy = "accept" | "dismiss";
 type DragTarget = string | { readonly x: number; readonly y: number };
 type ActionabilityResult = { ok: true; x: number; y: number } | { ok: false; reason: string };
@@ -398,6 +414,8 @@ export class WorkerCore {
 	#transport: Transport;
 	#browser?: Browser;
 	#page?: Page;
+	#runtimeDiagnostics = new BrowserRuntimeDiagnosticsMailbox();
+	#runtimeDiagnosticsSession?: CDPSession;
 	#targetId?: string;
 	#elementCache = new Map<number, ElementHandle>();
 	#elementCounter = 0;
@@ -447,7 +465,7 @@ export class WorkerCore {
 	async #init(payload: WorkerInitPayload): Promise<void> {
 		try {
 			this.#mode = payload.mode;
-			const puppeteer = await loadPuppeteerInWorker(payload.safeDir);
+			const puppeteer = await (loadPuppeteerInWorkerForTest ?? loadPuppeteerInWorker)(payload.safeDir);
 			this.#browser = await puppeteer.connect({
 				browserWSEndpoint: payload.browserWSEndpoint,
 				defaultViewport: null,
@@ -457,6 +475,7 @@ export class WorkerCore {
 				this.#page = await this.#browser.newPage();
 				await applyStealthPatches(this.#browser, this.#page, { browserSession: null, override: null }, payload.geo);
 				await applyViewport(this.#page, payload.viewport);
+				if (payload.runtimeDiagnostics) await this.#instrumentRuntimeDiagnostics(this.#page);
 				if (payload.dialogs) this.#applyDialogPolicy(payload.dialogs);
 				if (payload.url) {
 					await this.#page.goto(payload.url, {
@@ -467,6 +486,7 @@ export class WorkerCore {
 				}
 			} else {
 				this.#page = await this.#findAttachedPage(payload.targetId);
+				if (payload.runtimeDiagnostics) await this.#instrumentRuntimeDiagnostics(this.#page);
 				if (payload.dialogs) this.#applyDialogPolicy(payload.dialogs);
 			}
 			this.#targetId = await targetIdForPage(this.#page);
@@ -517,6 +537,16 @@ export class WorkerCore {
 		this.#dialogHandler = handler;
 	}
 
+	async #instrumentRuntimeDiagnostics(page: Page): Promise<void> {
+		try {
+			this.#runtimeDiagnosticsSession = await instrumentBrowserRuntimeDiagnostics(page, this.#runtimeDiagnostics);
+		} catch (error) {
+			this.#log("debug", "Failed to instrument browser runtime diagnostics", {
+				error: error instanceof Error ? error.message : String(error),
+			});
+		}
+	}
+
 	async #postReadyInfo(): Promise<void> {
 		try {
 			this.#transport.send({ type: "ready", info: await this.#currentReadyInfo() });
@@ -581,6 +611,10 @@ export class WorkerCore {
 					cancelRejection,
 				]);
 				await this.#postReadyInfo();
+				const drained = this.#runtimeDiagnostics.drain();
+				if (drained.runtimeDiagnostics.length || drained.runtimeDiagnosticsDropped) {
+					displays.push({ type: "text", text: serializeRuntimeDiagnostics(drained) });
+				}
 				this.#transport.send({
 					type: "result",
 					id: msg.id,
@@ -1034,6 +1068,7 @@ export class WorkerCore {
 		this.#clearElementCache();
 		const page = this.#page;
 		if (this.#dialogHandler && page && !page.isClosed()) page.off("dialog", this.#dialogHandler);
+		await this.#runtimeDiagnosticsSession?.detach().catch(() => undefined);
 		if (this.#mode === "headless" && page && !page.isClosed()) await page.close().catch(() => undefined);
 		if (this.#browser?.connected) this.#browser.disconnect();
 		this.#transport.send({ type: "closed" });

package/src/tools/browser.ts

@@ -87,6 +87,12 @@ const browserSchema = z.object({
 		.enum(["accept", "dismiss"] as const)
 		.describe("auto-handle dialogs")
 		.optional(),
+	diagnostics: z
+		.boolean()
+		.describe(
+			"opt-in: capture bounded page runtime diagnostics (page exceptions and console.error metadata) in the next successful run/act response",
+		)
+		.optional(),
 	code: z.string().describe("js body to run in tab").optional(),
 	actions: z.array(actionStepSchema).describe("structured action steps for action 'act'").optional(),
 	timeout: z.number().default(30).describe("timeout in seconds (default 30, max 300)").optional(),
@@ -258,6 +264,7 @@ export class BrowserTool implements AgentTool<typeof browserSchema, BrowserToolD
 				target: params.app?.target,
 				timeoutMs,
 				dialogs: params.dialogs,
+				runtimeDiagnostics: params.diagnostics === true,
 				signal,
 			}),
 		);