@gajae-code/coding-agent 0.1.1

package/src/tools/browser/readable.ts

@@ -0,0 +1,95 @@
+import { Readability } from "@mozilla/readability";
+import { parseHTML } from "linkedom";
+import { htmlToBasicMarkdown } from "../../web/scrapers/types";
+
+export type ReadableFormat = "text" | "markdown";
+
+export interface ReadableResult {
+	url: string;
+	title?: string;
+	byline?: string;
+	excerpt?: string;
+	contentLength: number;
+	text?: string;
+	markdown?: string;
+}
+
+/** Trim to non-empty string or undefined. */
+function normalize(text: string | null | undefined): string | undefined {
+	const trimmed = text?.trim();
+	return trimmed || undefined;
+}
+
+/**
+ * Extract readable content from raw HTML.
+ * Tries Readability (article-isolation scoring) first, then falls back to a
+ * CSS selector chain over the same pre-parsed DOM. Returns null if neither
+ * path yields usable content.
+ */
+export async function extractReadableFromHtml(
+	html: string,
+	url: string,
+	format: ReadableFormat,
+): Promise<ReadableResult | null> {
+	const { document } = parseHTML(html);
+
+	// --- Primary: Readability article extraction ---
+	const article = new Readability(document).parse();
+	if (article) {
+		const result = await toReadableResult(url, format, article.textContent, article.content, {
+			title: article.title,
+			byline: article.byline,
+			excerpt: article.excerpt,
+			length: article.length,
+		});
+		if (result) return result;
+	}
+
+	// --- Fallback: CSS selector chain ---
+	const candidates = [
+		document.querySelector("[data-pagefind-body]"),
+		document.querySelector("main article"),
+		document.querySelector("article"),
+		document.querySelector("main"),
+		document.querySelector("[role='main']"),
+		document.body,
+	];
+	for (const el of candidates) {
+		if (!el) continue;
+		const innerHTML = el.innerHTML?.trim();
+		const textContent = el.textContent?.trim();
+		if (!innerHTML || !textContent) continue;
+		const result = await toReadableResult(url, format, textContent, innerHTML, {
+			title: document.title,
+			excerpt: textContent.slice(0, 240),
+			length: textContent.length,
+		});
+		if (result) return result;
+	}
+
+	return null;
+}
+
+/** Shared builder for both extraction paths. */
+async function toReadableResult(
+	url: string,
+	format: ReadableFormat,
+	textContent: string | null | undefined,
+	htmlContent: string | null | undefined,
+	meta: { title?: string | null; byline?: string | null; excerpt?: string | null; length?: number | null },
+): Promise<ReadableResult | null> {
+	const text = normalize(textContent);
+	const markdown =
+		format === "markdown" ? (normalize(await htmlToBasicMarkdown(htmlContent ?? "")) ?? text) : undefined;
+	const normalizedText = format === "text" ? text : undefined;
+	if (!normalizedText && !markdown) return null;
+	return {
+		url,
+		title: normalize(meta.title),
+		byline: normalize(meta.byline),
+		excerpt: normalize(meta.excerpt),
+		contentLength: meta.length ?? text?.length ?? markdown?.length ?? 0,
+		text: normalizedText,
+		markdown,
+	};
+}

package/src/tools/browser/registry.ts

@@ -0,0 +1,194 @@
+import * as path from "node:path";
+import { logger } from "@gajae-code/utils";
+import type { Subprocess } from "bun";
+import type { Browser, CDPSession } from "puppeteer-core";
+import { ToolAbortError, ToolError } from "../tool-errors";
+import { findFreeCdpPort, findReusableCdp, gracefulKillTreeOnce, killExistingByPath, waitForCdp } from "./attach";
+import { BROWSER_PROTOCOL_TIMEOUT_MS, launchHeadlessBrowser, loadPuppeteer, type UserAgentOverride } from "./launch";
+
+export type BrowserKind =
+	| { kind: "headless"; headless: boolean }
+	| { kind: "spawned"; path: string }
+	| { kind: "connected"; cdpUrl: string };
+
+export type BrowserKindTag = BrowserKind["kind"];
+
+export interface BrowserHandle {
+	key: string;
+	kind: BrowserKind;
+	browser: Browser;
+	cdpUrl?: string;
+	pid?: number;
+	subprocess?: Subprocess;
+	refCount: number;
+	stealth: { browserSession: CDPSession | null; override: UserAgentOverride | null };
+}
+
+const browsers = new Map<string, BrowserHandle>();
+
+function browserKey(kind: BrowserKind): string {
+	switch (kind.kind) {
+		case "headless":
+			return `headless:${kind.headless ? "1" : "0"}`;
+		case "spawned":
+			return `spawned:${kind.path}`;
+		case "connected":
+			return `connected:${kind.cdpUrl}`;
+	}
+}
+
+export interface AcquireBrowserOptions {
+	cwd: string;
+	viewport?: { width: number; height: number; deviceScaleFactor?: number };
+	appArgs?: string[];
+	signal?: AbortSignal;
+}
+
+export async function acquireBrowser(kind: BrowserKind, opts: AcquireBrowserOptions): Promise<BrowserHandle> {
+	const key = browserKey(kind);
+	const existing = browsers.get(key);
+	if (existing) {
+		if (existing.browser.connected) return existing;
+		browsers.delete(key);
+		await disposeBrowserHandle(existing, { kill: false });
+	}
+
+	const handle = await openBrowserHandle(kind, opts);
+	browsers.set(key, handle);
+	return handle;
+}
+
+async function openBrowserHandle(kind: BrowserKind, opts: AcquireBrowserOptions): Promise<BrowserHandle> {
+	if (kind.kind === "headless") {
+		const browser = await launchHeadlessBrowser({ headless: kind.headless, viewport: opts.viewport });
+		return {
+			key: browserKey(kind),
+			kind,
+			browser,
+			refCount: 0,
+			stealth: { browserSession: null, override: null },
+		};
+	}
+	if (kind.kind === "connected") {
+		const cdpUrl = kind.cdpUrl.replace(/\/+$/, "");
+		await waitForCdp(cdpUrl, 5_000, opts.signal);
+		const puppeteer = await loadPuppeteer();
+		const browser = await puppeteer.connect({
+			browserURL: cdpUrl,
+			defaultViewport: null,
+			protocolTimeout: BROWSER_PROTOCOL_TIMEOUT_MS,
+		});
+		return {
+			key: browserKey(kind),
+			kind,
+			browser,
+			cdpUrl,
+			refCount: 0,
+			stealth: { browserSession: null, override: null },
+		};
+	}
+
+	const exe = kind.path;
+	if (!path.isAbsolute(exe)) {
+		throw new ToolError(
+			`app.path must be absolute (got ${JSON.stringify(exe)}). Pass the binary inside Foo.app/Contents/MacOS/, not the .app bundle.`,
+		);
+	}
+	const reused = await findReusableCdp(exe, opts.signal);
+	let cdpUrl: string;
+	let pid: number;
+	let subprocess: Subprocess | undefined;
+	if (reused) {
+		logger.debug("Reusing existing CDP endpoint for attach", { exe, pid: reused.pid, cdpUrl: reused.cdpUrl });
+		cdpUrl = reused.cdpUrl;
+		pid = reused.pid;
+	} else {
+		const killed = await killExistingByPath(exe, opts.signal);
+		if (killed > 0) logger.debug("Killed existing instances before attach", { exe, killed });
+		const port = await findFreeCdpPort();
+		const launchArgs = [...(opts.appArgs ?? []), `--remote-debugging-port=${port}`];
+		const child = Bun.spawn([exe, ...launchArgs], {
+			stdout: "ignore",
+			stderr: "ignore",
+			stdin: "ignore",
+		});
+		child.unref();
+		subprocess = child;
+		pid = child.pid;
+		cdpUrl = `http://127.0.0.1:${port}`;
+		try {
+			await waitForCdp(cdpUrl, 30_000, opts.signal);
+		} catch (err) {
+			await gracefulKillTreeOnce(child.pid).catch(() => undefined);
+			if (err instanceof ToolAbortError) throw err;
+			if (err instanceof Error && err.name === "AbortError") throw err;
+			throw new ToolError(`Failed to attach to ${path.basename(exe)} on ${cdpUrl}: ${(err as Error).message}`);
+		}
+	}
+
+	const puppeteer = await loadPuppeteer();
+	let browser: Browser;
+	try {
+		browser = await puppeteer.connect({
+			browserURL: cdpUrl,
+			defaultViewport: null,
+			protocolTimeout: BROWSER_PROTOCOL_TIMEOUT_MS,
+		});
+	} catch (err) {
+		if (subprocess) await gracefulKillTreeOnce(subprocess.pid);
+		throw new ToolError(`Connected to ${cdpUrl} but puppeteer.connect failed: ${(err as Error).message}`);
+	}
+	return {
+		key: browserKey(kind),
+		kind,
+		browser,
+		cdpUrl,
+		pid,
+		subprocess,
+		refCount: 0,
+		stealth: { browserSession: null, override: null },
+	};
+}
+
+export function holdBrowser(handle: BrowserHandle): void {
+	handle.refCount++;
+}
+
+export async function releaseBrowser(handle: BrowserHandle, opts: { kill: boolean }): Promise<void> {
+	handle.refCount = Math.max(0, handle.refCount - 1);
+	if (handle.refCount === 0) {
+		browsers.delete(handle.key);
+		await disposeBrowserHandle(handle, opts);
+	}
+}
+
+async function disposeBrowserHandle(handle: BrowserHandle, opts: { kill: boolean }): Promise<void> {
+	if (handle.kind.kind === "headless") {
+		if (handle.browser.connected) {
+			try {
+				await handle.browser.close();
+			} catch (err) {
+				logger.debug("Failed to close headless browser", { error: (err as Error).message });
+			}
+		}
+		return;
+	}
+	if (handle.kind.kind === "connected") {
+		if (handle.browser.connected) {
+			try {
+				handle.browser.disconnect();
+			} catch (err) {
+				logger.debug("Failed to disconnect from remote browser", { error: (err as Error).message });
+			}
+		}
+		return;
+	}
+	if (handle.browser.connected) {
+		try {
+			handle.browser.disconnect();
+		} catch (err) {
+			logger.debug("Failed to disconnect from spawned browser", { error: (err as Error).message });
+		}
+	}
+	if (opts.kill && handle.pid !== undefined) await gracefulKillTreeOnce(handle.pid);
+}

package/src/tools/browser/render.ts

@@ -0,0 +1,212 @@
+/**
+ * TUI renderer for the browser tool.
+ *
+ * Mirrors the `eval` tool look: each `run` invocation is shown as a JS code
+ * cell with status icon, optional output, and expand/collapse handling. `open`
+ * and `close` actions render as compact status lines.
+ */
+import type { Component } from "@gajae-code/tui";
+import { Text } from "@gajae-code/tui";
+import type { RenderResultOptions } from "../../extensibility/custom-tools/types";
+import type { Theme } from "../../modes/theme/theme";
+import { Hasher, renderCodeCell, renderStatusLine } from "../../tui";
+import type { BrowserToolDetails } from "../browser";
+import { formatStyledTruncationWarning, stripOutputNotice } from "../output-meta";
+import { replaceTabs, shortenPath } from "../render-utils";
+
+const BROWSER_DEFAULT_PREVIEW_LINES = 10;
+
+interface BrowserRenderArgs {
+	action?: "open" | "close" | "run";
+	name?: string;
+	url?: string;
+	code?: string;
+	all?: boolean;
+	kill?: boolean;
+	app?: { path?: string; cdp_url?: string; target?: string };
+	viewport?: { width: number; height: number; scale?: number };
+	timeout?: number;
+}
+
+interface BrowserRenderContext {
+	expanded?: boolean;
+	previewLines?: number;
+}
+
+function describeBrowser(args: BrowserRenderArgs, details: BrowserToolDetails | undefined): string | undefined {
+	if (args.app?.cdp_url) return `connected ${args.app.cdp_url}`;
+	if (args.app?.path) return `spawned ${shortenPath(args.app.path)}`;
+	switch (details?.browser) {
+		case "headless":
+			return "headless";
+		case "spawned":
+			return "spawned";
+		case "connected":
+			return "connected";
+		default:
+			return undefined;
+	}
+}
+
+function tabLabel(args: BrowserRenderArgs, details: BrowserToolDetails | undefined): string {
+	const name = details?.name ?? args.name ?? "main";
+	return `tab ${JSON.stringify(name)}`;
+}
+
+function cellStatus(isPartial: boolean, isError: boolean): "pending" | "running" | "complete" | "error" {
+	if (isPartial) return "running";
+	if (isError) return "error";
+	return "complete";
+}
+
+function dropTrailingBlankLines(text: string): string {
+	return text.replace(/\s+$/, "");
+}
+
+function appendLine(component: Component, line: string | undefined): Component {
+	if (!line) return component;
+	return {
+		render: (width: number): string[] => {
+			const base = component.render(width);
+			return [...base, line];
+		},
+		invalidate: () => component.invalidate?.(),
+	};
+}
+
+function renderRunCell(
+	args: BrowserRenderArgs,
+	details: BrowserToolDetails | undefined,
+	options: RenderResultOptions & { renderContext?: BrowserRenderContext },
+	output: string,
+	isError: boolean,
+	theme: Theme,
+): Component {
+	const code = dropTrailingBlankLines(args.code ?? "");
+	const status = cellStatus(options.isPartial, isError);
+
+	const titleParts: string[] = [tabLabel(args, details)];
+	const url = details?.url ?? args.url;
+	if (url) titleParts.push(shortenPath(url));
+	const browserDesc = describeBrowser(args, details);
+	if (browserDesc) titleParts.push(browserDesc);
+	const title = titleParts.join(" · ");
+
+	let cached: { key: bigint; width: number; lines: string[] } | undefined;
+	return {
+		render: (width: number): string[] => {
+			const expanded = options.renderContext?.expanded ?? options.expanded;
+			const previewLines = options.renderContext?.previewLines ?? BROWSER_DEFAULT_PREVIEW_LINES;
+			const key = new Hasher()
+				.bool(expanded)
+				.bool(isError)
+				.u32(previewLines)
+				.u32(options.spinnerFrame ?? 0)
+				.str(status)
+				.str(title)
+				.str(code)
+				.str(output)
+				.digest();
+			if (cached && cached.width === width && cached.key === key) {
+				return cached.lines;
+			}
+			const lines = renderCodeCell(
+				{
+					code,
+					language: "javascript",
+					title,
+					status,
+					spinnerFrame: options.spinnerFrame,
+					output: output.length > 0 ? output : undefined,
+					outputMaxLines: expanded ? Number.POSITIVE_INFINITY : previewLines,
+					codeMaxLines: expanded ? Number.POSITIVE_INFINITY : previewLines,
+					expanded,
+					width,
+				},
+				theme,
+			);
+			cached = { key, width, lines };
+			return lines;
+		},
+		invalidate: () => {
+			cached = undefined;
+		},
+	};
+}
+
+function renderOpenOrCloseLine(
+	args: BrowserRenderArgs,
+	details: BrowserToolDetails | undefined,
+	isPartial: boolean,
+	isError: boolean,
+	output: string,
+	theme: Theme,
+): Component {
+	const action = (details?.action ?? args.action ?? "open") as "open" | "close" | "run";
+	const status = cellStatus(isPartial, isError);
+	const icon =
+		status === "complete" ? "success" : status === "error" ? "error" : status === "running" ? "running" : "pending";
+
+	let title: string;
+	if (action === "close") {
+		const all = args.all === true || (args.name === undefined && details?.name === undefined);
+		title = all ? "Close all tabs" : `Close ${tabLabel(args, details)}`;
+		if (args.kill) title += " (kill)";
+	} else {
+		title = `Open ${tabLabel(args, details)}`;
+	}
+
+	const meta: string[] = [];
+	const browserDesc = describeBrowser(args, details);
+	if (browserDesc) meta.push(browserDesc);
+	const url = details?.url ?? args.url;
+	if (url) meta.push(shortenPath(url));
+
+	const header = renderStatusLine({ icon, title, meta }, theme);
+	if (!output) return new Text(header, 0, 0);
+	const outputLines = output.split("\n").map(line => theme.fg("toolOutput", replaceTabs(line)));
+	return new Text([header, ...outputLines].join("\n"), 0, 0);
+}
+
+function extractTextOutput(content: Array<{ type: string; text?: string }> | undefined): string {
+	if (!content) return "";
+	const text = content
+		.filter(c => c.type === "text")
+		.map(c => c.text ?? "")
+		.join("\n");
+	return dropTrailingBlankLines(text);
+}
+
+export const browserToolRenderer = {
+	renderCall(args: BrowserRenderArgs, options: RenderResultOptions, theme: Theme): Component {
+		const action = args.action;
+		if (action === "run") {
+			return renderRunCell(args, undefined, options, "", false, theme);
+		}
+		return renderOpenOrCloseLine(args, undefined, options.isPartial, false, "", theme);
+	},
+	renderResult(
+		result: { content: Array<{ type: string; text?: string }>; details?: BrowserToolDetails; isError?: boolean },
+		options: RenderResultOptions & { renderContext?: BrowserRenderContext },
+		theme: Theme,
+		args?: BrowserRenderArgs,
+	): Component {
+		const argsObj = args ?? {};
+		const details = result.details;
+		const action = details?.action ?? argsObj.action;
+		const isError = result.isError === true;
+		const output = stripOutputNotice(extractTextOutput(result.content), details?.meta);
+
+		if (action === "run") {
+			let component = renderRunCell(argsObj, details, options, output, isError, theme);
+			const truncationWarning = details?.meta?.truncation
+				? (formatStyledTruncationWarning(details.meta, theme) ?? undefined)
+				: undefined;
+			component = appendLine(component, truncationWarning);
+			return component;
+		}
+		return renderOpenOrCloseLine(argsObj, details, options.isPartial, isError, output, theme);
+	},
+	mergeCallAndResult: true,
+	inline: true,
+};

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

@@ -0,0 +1,105 @@
+import type { ImageContent, TextContent } from "@gajae-code/ai";
+
+export type Transferable = Bun.Transferable;
+
+export interface ObservationEntry {
+	id: number;
+	role: string;
+	name?: string;
+	value?: string | number;
+	description?: string;
+	keyshortcuts?: string;
+	states: string[];
+}
+
+export interface Observation {
+	url: string;
+	title?: string;
+	viewport: { width: number; height: number; deviceScaleFactor?: number };
+	scroll: {
+		x: number;
+		y: number;
+		width: number;
+		height: number;
+		scrollWidth: number;
+		scrollHeight: number;
+	};
+	elements: ObservationEntry[];
+}
+
+export interface ScreenshotResult {
+	dest: string;
+	mimeType: string;
+	bytes: number;
+	width: number;
+	height: number;
+}
+
+export interface SessionSnapshot {
+	cwd: string;
+	browserScreenshotDir?: string;
+}
+
+export type WorkerInitPayload =
+	| {
+			mode: "headless";
+			browserWSEndpoint: string;
+			safeDir: string;
+			viewport?: { width: number; height: number; deviceScaleFactor?: number };
+			dialogs?: "accept" | "dismiss";
+			url?: string;
+			waitUntil?: "load" | "domcontentloaded" | "networkidle0" | "networkidle2";
+			timeoutMs: number;
+	  }
+	| {
+			mode: "attach";
+			browserWSEndpoint: string;
+			safeDir: string;
+			targetId: string;
+			dialogs?: "accept" | "dismiss";
+	  };
+
+export type ToolReply = { ok: true; value: unknown } | { ok: false; error: RunErrorPayload };
+
+export type WorkerInbound =
+	| { type: "init"; payload: WorkerInitPayload }
+	| { type: "run"; id: string; name: string; code: string; timeoutMs: number; session: SessionSnapshot }
+	| { type: "abort"; id: string }
+	| { type: "tool-reply"; id: string; reply: ToolReply }
+	| { type: "close" };
+
+export interface ReadyInfo {
+	url: string;
+	title?: string;
+	viewport: { width: number; height: number; deviceScaleFactor?: number };
+	targetId: string;
+}
+
+export interface RunResultOk {
+	displays: Array<TextContent | ImageContent>;
+	returnValue: unknown;
+	screenshots: ScreenshotResult[];
+}
+
+export interface RunErrorPayload {
+	name: string;
+	message: string;
+	stack?: string;
+	isToolError: boolean;
+	isAbort: boolean;
+}
+
+export type WorkerOutbound =
+	| { type: "ready"; info: ReadyInfo }
+	| { type: "init-failed"; error: RunErrorPayload }
+	| { type: "result"; id: string; ok: true; payload: RunResultOk }
+	| { type: "result"; id: string; ok: false; error: RunErrorPayload }
+	| { type: "tool-call"; id: string; runId: string; name: string; args: unknown }
+	| { type: "log"; level: "debug" | "warn" | "error"; msg: string; meta?: Record<string, unknown> }
+	| { type: "closed" };
+
+export interface Transport {
+	send(msg: WorkerOutbound | WorkerInbound, transferList?: Transferable[]): void;
+	onMessage(handler: (msg: WorkerOutbound | WorkerInbound) => void): () => void;
+	close(): void;
+}