agent-dbg 0.1.9 → 0.2.0

package/src/daemon/adapters/bun-adapter.ts

@@ -0,0 +1,190 @@
+import type Protocol from "devtools-protocol/types/protocol.js";
+import type { CdpClient } from "../../cdp/client.ts";
+import { JscClient } from "../../cdp/jsc-client.ts";
+import type { RuntimeAdapter } from "../runtime-adapter.ts";
+import type { DebugSession, ScriptInfo } from "../session.ts";
+
+/**
+ * BunAdapter handles WebKit Inspector Protocol differences from CDP.
+ *
+ * Key divergences from Node.js (CDP):
+ * - Breakpoints use Debugger.setBreakpoint (by scriptId) instead of setBreakpointByUrl
+ * - Conditions use `options: { condition }` instead of top-level `condition`
+ * - getPossibleBreakpoints → getBreakpointLocations (different API shape)
+ * - setBlackboxPatterns → setShouldBlackboxURL (per-URL instead of batch)
+ * - Inspector.enable must be called before other domains
+ * - Inspector.initialized starts JS execution (replaces runIfWaitingForDebugger)
+ */
+export class BunAdapter implements RuntimeAdapter {
+	readonly name = "bun" as const;
+	readonly internalUrlPrefix = "bun:";
+	private jsc: JscClient | null = null;
+
+	async preEnable(cdp: CdpClient): Promise<void> {
+		this.jsc = new JscClient(cdp);
+		await this.jsc.send("Inspector.enable");
+	}
+
+	/**
+	 * Pause at the entry script under Bun's --inspect-brk.
+	 *
+	 * Bun evaluates dependencies (node:, bun:) before the entry script.
+	 * We use setPauseForInternalScripts(false) to skip those, then a single
+	 * urlRegex breakpoint at line 1 to catch the entry script. Line 1
+	 * breakpoints auto-resolve to the nearest breakable location in JSC,
+	 * unlike line 0 which silently fails.
+	 */
+	async waitForBrkPause(session: DebugSession): Promise<void> {
+		if (!this.jsc) return;
+
+		await this.jsc.send("Debugger.setBreakpointsActive", { active: true });
+		await this.jsc.send("Debugger.setPauseForInternalScripts", { shouldPause: false });
+
+		const entryScript = this.resolveEntryScript(session);
+		const tempBpId = await this.setEntryBreakpoint(entryScript);
+		try {
+			const waiter = session.createPauseWaiter(5_000);
+			await this.jsc.send("Inspector.initialized");
+			await waiter;
+		} finally {
+			if (tempBpId && this.jsc.connected) {
+				try {
+					await this.jsc.send("Debugger.removeBreakpoint", { breakpointId: tempBpId });
+				} catch {
+					// Already removed or disconnected
+				}
+			}
+		}
+	}
+
+	async setBreakpointByLocation(
+		_cdp: CdpClient,
+		params: {
+			file: string;
+			line: number;
+			column?: number;
+			condition?: string;
+			url?: string;
+			urlRegex?: string;
+			scriptId?: string;
+			scripts: Map<string, ScriptInfo>;
+		},
+	): Promise<{
+		breakpointId: string;
+		location?: { scriptId: string; lineNumber: number; columnNumber?: number };
+		url?: string;
+	}> {
+		const jsc = this.ensureJsc();
+		const scriptId = params.scriptId ?? this.findScriptId(params.scripts, params.url);
+		if (!scriptId) {
+			throw new Error(`Cannot find script for "${params.file}" — ensure the script is loaded`);
+		}
+
+		const r = await jsc.send("Debugger.setBreakpoint", {
+			location: {
+				scriptId,
+				lineNumber: params.line - 1,
+				columnNumber: params.column,
+			},
+			options: params.condition ? { condition: params.condition } : undefined,
+		});
+
+		return {
+			breakpointId: r.breakpointId,
+			location: r.actualLocation,
+			url: params.url,
+		};
+	}
+
+	async getBreakableLocations(
+		_cdp: CdpClient,
+		scriptId: string,
+		startLine: number,
+		endLine: number,
+	): Promise<Array<{ line: number; column: number }>> {
+		const jsc = this.ensureJsc();
+		const r = await jsc.send("Debugger.getBreakpointLocations", {
+			start: { scriptId, lineNumber: startLine - 1 },
+			end: { scriptId, lineNumber: endLine },
+		});
+
+		return (r.locations ?? []).map((loc) => ({
+			line: loc.lineNumber + 1,
+			column: (loc.columnNumber ?? 0) + 1,
+		}));
+	}
+
+	async getProperties(
+		cdp: CdpClient,
+		params: Protocol.Runtime.GetPropertiesRequest,
+	): Promise<Protocol.Runtime.GetPropertiesResponse> {
+		const raw = (await cdp.sendRaw(
+			"Runtime.getProperties",
+			params as unknown as Record<string, unknown>,
+		)) as Record<string, unknown>;
+		// WebKit returns {properties: [...]} instead of {result: [...]}
+		if ("properties" in raw && !("result" in raw)) {
+			raw.result = raw.properties;
+			delete raw.properties;
+		}
+		return raw as unknown as Protocol.Runtime.GetPropertiesResponse;
+	}
+
+	async setBlackboxPatterns(_cdp: CdpClient, patterns: string[]): Promise<void> {
+		const jsc = this.ensureJsc();
+		for (const pattern of patterns) {
+			await jsc.send("Debugger.setShouldBlackboxURL", {
+				url: pattern,
+				caseSensitive: false,
+				shouldBlackbox: true,
+			});
+		}
+	}
+
+	// -- Private helpers --------------------------------------------------
+
+	private ensureJsc(): JscClient {
+		if (!this.jsc) throw new Error("JscClient not initialized — call preEnable first");
+		return this.jsc;
+	}
+
+	/** Set a single urlRegex breakpoint at line 1 of the entry script. */
+	private async setEntryBreakpoint(entryScript: string | null): Promise<string | null> {
+		if (!entryScript || !this.jsc) return null;
+
+		const parts = entryScript.split("/");
+		const filename = parts[parts.length - 1] ?? entryScript;
+		const urlRegex = `${escapeRegex(filename)}$`;
+
+		try {
+			const r = await this.jsc.send("Debugger.setBreakpointByUrl", {
+				urlRegex,
+				lineNumber: 1,
+			});
+			return r.breakpointId;
+		} catch {
+			return null;
+		}
+	}
+
+	private findScriptId(scripts: Map<string, ScriptInfo>, url?: string): string | undefined {
+		if (!url) return undefined;
+		for (const [sid, info] of scripts) {
+			if (info.url === url) return sid;
+		}
+		return undefined;
+	}
+
+	private resolveEntryScript(session: DebugSession): string | null {
+		if (!session.launchCommand) return null;
+		for (let i = session.launchCommand.length - 1; i >= 0; i--) {
+			const arg = session.launchCommand[i] as string;
+			if (!arg.startsWith("-")) return arg;
+		}
+		return null;
+	}
+}
+
+function escapeRegex(s: string): string {
+	return s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}

package/src/daemon/adapters/index.ts

@@ -0,0 +1,13 @@
+import type { RuntimeAdapter } from "../runtime-adapter.ts";
+import { BunAdapter } from "./bun-adapter.ts";
+import { NodeAdapter } from "./node-adapter.ts";
+
+export function createAdapter(command: string[]): RuntimeAdapter {
+	const bin = command[0]?.split("/").pop();
+	if (bin === "bun" || bin === "bunx") return new BunAdapter();
+	// Default to NodeAdapter for "node", "nodejs", and unknown runtimes
+	return new NodeAdapter();
+}
+
+export { BunAdapter } from "./bun-adapter.ts";
+export { NodeAdapter } from "./node-adapter.ts";

package/src/daemon/adapters/node-adapter.ts

@@ -0,0 +1,121 @@
+import type Protocol from "devtools-protocol/types/protocol.js";
+import type { CdpClient } from "../../cdp/client.ts";
+import type { RuntimeAdapter } from "../runtime-adapter.ts";
+import type { DebugSession, ScriptInfo } from "../session.ts";
+
+export class NodeAdapter implements RuntimeAdapter {
+	readonly name = "node" as const;
+	readonly internalUrlPrefix = "node:";
+
+	async preEnable(_cdp: CdpClient): Promise<void> {
+		// Node.js doesn't need anything before enableDomains()
+	}
+
+	async waitForBrkPause(session: DebugSession): Promise<void> {
+		// Give the Debugger.paused event a moment to arrive (older Node.js)
+		if (!session.isPaused()) {
+			await Bun.sleep(100);
+		}
+		// On Node.js v24+, --inspect-brk does not emit Debugger.paused when the
+		// debugger connects after the process is already paused. We request an
+		// explicit pause and then signal Runtime.runIfWaitingForDebugger so the
+		// process starts execution and immediately hits our pause request.
+		if (!session.isPaused() && session.cdp) {
+			await session.cdp.send("Debugger.pause");
+			await session.cdp.send("Runtime.runIfWaitingForDebugger");
+			const deadline = Date.now() + 2_000;
+			while (!session.isPaused() && Date.now() < deadline) {
+				await Bun.sleep(50);
+			}
+		}
+		// On Node.js v24+, the initial --inspect-brk pause lands in an internal
+		// bootstrap module (node:internal/...) rather than the user script.
+		// Resume past internal pauses until we reach user code.
+		await this.skipInternalPauses(session);
+	}
+
+	async setBreakpointByLocation(
+		cdp: CdpClient,
+		params: {
+			file: string;
+			line: number;
+			column?: number;
+			condition?: string;
+			url?: string;
+			urlRegex?: string;
+			scriptId?: string;
+			scripts: Map<string, ScriptInfo>;
+		},
+	): Promise<{
+		breakpointId: string;
+		location?: { scriptId: string; lineNumber: number; columnNumber?: number };
+		url?: string;
+	}> {
+		const bpParams: Protocol.Debugger.SetBreakpointByUrlRequest = {
+			lineNumber: params.line - 1, // CDP uses 0-based lines
+		};
+		if (params.column !== undefined) {
+			bpParams.columnNumber = params.column;
+		}
+		if (params.urlRegex) {
+			bpParams.urlRegex = params.urlRegex;
+		} else if (params.url) {
+			bpParams.url = params.url;
+		}
+		if (params.condition) {
+			bpParams.condition = params.condition;
+		}
+
+		const r = await cdp.send("Debugger.setBreakpointByUrl", bpParams);
+		const loc = r.locations[0];
+		return {
+			breakpointId: r.breakpointId,
+			location: loc
+				? { scriptId: loc.scriptId, lineNumber: loc.lineNumber, columnNumber: loc.columnNumber }
+				: undefined,
+			url: params.url,
+		};
+	}
+
+	async getBreakableLocations(
+		cdp: CdpClient,
+		scriptId: string,
+		startLine: number,
+		endLine: number,
+	): Promise<Array<{ line: number; column: number }>> {
+		const r = await cdp.send("Debugger.getPossibleBreakpoints", {
+			start: { scriptId, lineNumber: startLine - 1 },
+			end: { scriptId, lineNumber: endLine },
+		});
+		return r.locations.map((loc) => ({
+			line: loc.lineNumber + 1,
+			column: (loc.columnNumber ?? 0) + 1,
+		}));
+	}
+
+	async getProperties(
+		cdp: CdpClient,
+		params: Protocol.Runtime.GetPropertiesRequest,
+	): Promise<Protocol.Runtime.GetPropertiesResponse> {
+		return cdp.send("Runtime.getProperties", params);
+	}
+
+	async setBlackboxPatterns(cdp: CdpClient, patterns: string[]): Promise<void> {
+		await cdp.send("Debugger.setBlackboxPatterns", { patterns });
+	}
+
+	private async skipInternalPauses(session: DebugSession): Promise<void> {
+		let skips = 0;
+		while (
+			session.isPaused() &&
+			session.cdp &&
+			session.pauseInfo?.url?.startsWith(this.internalUrlPrefix) &&
+			skips < 5
+		) {
+			skips++;
+			const waiter = session.createPauseWaiter(5_000);
+			await session.cdp.send("Debugger.resume");
+			await waiter;
+		}
+	}
+}

package/src/daemon/runtime-adapter.ts

@@ -0,0 +1,50 @@
+import type Protocol from "devtools-protocol/types/protocol.js";
+import type { CdpClient } from "../cdp/client.ts";
+import type { DebugSession, ScriptInfo } from "./session.ts";
+
+export interface RuntimeAdapter {
+	readonly name: "node" | "bun" | "unknown";
+	readonly internalUrlPrefix: string;
+
+	/** Pre-enable hook: called after CDP connects, before enableDomains() */
+	preEnable(cdp: CdpClient): Promise<void>;
+
+	/** Handle --inspect-brk initial pause for this runtime */
+	waitForBrkPause(session: DebugSession): Promise<void>;
+
+	/** Get properties of a remote object, handling runtime-specific API differences */
+	getProperties(
+		cdp: CdpClient,
+		params: Protocol.Runtime.GetPropertiesRequest,
+	): Promise<Protocol.Runtime.GetPropertiesResponse>;
+
+	/** Set a breakpoint at a specific location, handling runtime-specific API differences */
+	setBreakpointByLocation(
+		cdp: CdpClient,
+		params: {
+			file: string;
+			line: number;
+			column?: number;
+			condition?: string;
+			url?: string;
+			urlRegex?: string;
+			scriptId?: string;
+			scripts: Map<string, ScriptInfo>;
+		},
+	): Promise<{
+		breakpointId: string;
+		location?: { scriptId: string; lineNumber: number; columnNumber?: number };
+		url?: string;
+	}>;
+
+	/** Get possible breakpoint locations in a script range */
+	getBreakableLocations(
+		cdp: CdpClient,
+		scriptId: string,
+		startLine: number,
+		endLine: number,
+	): Promise<Array<{ line: number; column: number }>>;
+
+	/** Apply blackbox patterns to the debugger */
+	setBlackboxPatterns(cdp: CdpClient, patterns: string[]): Promise<void>;
+}

package/src/daemon/session-blackbox.ts

@@ -11,9 +11,7 @@ export async function addBlackbox(session: DebugSession, patterns: string[]): Pr
 		}
 	}
 
-	await session.cdp.send("Debugger.setBlackboxPatterns", {
-		patterns: session.blackboxPatterns,
-	});
+	await session.adapter.setBlackboxPatterns(session.cdp, session.blackboxPatterns);
 
 	return [...session.blackboxPatterns];
 }
@@ -33,9 +31,7 @@ export async function removeBlackbox(session: DebugSession, patterns: string[]):
 		session.blackboxPatterns = session.blackboxPatterns.filter((p) => !patterns.includes(p));
 	}
 
-	await session.cdp.send("Debugger.setBlackboxPatterns", {
-		patterns: session.blackboxPatterns,
-	});
+	await session.adapter.setBlackboxPatterns(session.cdp, session.blackboxPatterns);
 
 	return [...session.blackboxPatterns];
 }

package/src/daemon/session-breakpoints.ts

@@ -1,4 +1,3 @@
-import type Protocol from "devtools-protocol/types/protocol.js";
 import type { DebugSession } from "./session.ts";
 
 export async function setBreakpoint(
@@ -20,6 +19,7 @@ export async function setBreakpoint(
 	let actualColumn: number | undefined =
 		options?.column !== undefined ? options.column - 1 : undefined; // user column is 1-based
 	let actualFile = file;
+	let generatedScriptId: string | null = null;
 
 	if (!options?.urlRegex) {
 		const generated = session.sourceMapResolver.toGenerated(file, line, actualColumn ?? 0);
@@ -28,6 +28,7 @@ export async function setBreakpoint(
 			originalLine = line;
 			actualLine = generated.line;
 			actualColumn = generated.column;
+			generatedScriptId = generated.scriptId;
 			// Find the URL of the generated script
 			const scriptInfo = session.scripts.get(generated.scriptId);
 			if (scriptInfo) {
@@ -36,33 +37,32 @@ export async function setBreakpoint(
 		}
 	}
 
-	const params: Protocol.Debugger.SetBreakpointByUrlRequest = {
-		lineNumber: actualLine - 1, // CDP uses 0-based lines
-	};
-	if (actualColumn !== undefined) {
-		params.columnNumber = actualColumn;
-	}
-
 	let url: string | null = null;
+	let urlRegex: string | undefined;
 	if (options?.urlRegex) {
-		// Use urlRegex directly without resolving file path
-		params.urlRegex = options.urlRegex;
+		urlRegex = options.urlRegex;
 	} else {
 		url = session.findScriptUrl(actualFile);
-		if (url) {
-			params.url = url;
-		} else {
-			// Fall back to urlRegex to match partial paths
-			params.urlRegex = `${actualFile.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}$`;
+		if (!url && !generatedScriptId) {
+			urlRegex = `${actualFile.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}$`;
 		}
 	}
-	if (condition) {
-		params.condition = condition;
-	}
 
-	const r = await session.cdp.send("Debugger.setBreakpointByUrl", params);
+	const r = await session.adapter.setBreakpointByLocation(session.cdp, {
+		file,
+		line: actualLine,
+		column: actualColumn,
+		condition,
+		url: url ?? undefined,
+		urlRegex,
+		scriptId: generatedScriptId ?? undefined,
+		scripts: session.scripts,
+	});
+
+	const breakpointId = r.breakpointId;
+	const loc = r.location;
+	if (!url) url = r.url ?? session.findScriptUrl(actualFile);
 
-	const loc = r.locations[0];
 	const resolvedUrl = originalFile ?? url ?? file;
 	const resolvedLine = originalLine ?? (loc ? loc.lineNumber + 1 : line); // Convert back to 1-based
 	const resolvedColumn = loc?.columnNumber;
@@ -90,7 +90,7 @@ export async function setBreakpoint(
 		meta.urlRegex = options.urlRegex;
 	}
 
-	const ref = session.refs.addBreakpoint(r.breakpointId, meta);
+	const ref = session.refs.addBreakpoint(breakpointId, meta);
 
 	const location: { url: string; line: number; column?: number } = {
 		url: resolvedUrl,
@@ -333,21 +333,26 @@ async function reEnableBreakpoint(
 
 	const builtCondition = session.buildBreakpointCondition(condition, hitCount);
 
-	const bpParams: Protocol.Debugger.SetBreakpointByUrlRequest = {
-		lineNumber: line - 1,
-	};
-
-	if (urlRegex) {
-		bpParams.urlRegex = urlRegex;
-	} else if (url) {
-		bpParams.url = url;
-	}
-
-	if (builtCondition) {
-		bpParams.condition = builtCondition;
+	// Find scriptId for Bun adapter which needs it
+	let scriptId: string | undefined;
+	if (url) {
+		for (const [sid, info] of session.scripts) {
+			if (info.url === url) {
+				scriptId = sid;
+				break;
+			}
+		}
 	}
 
-	const r = await session.cdp.send("Debugger.setBreakpointByUrl", bpParams);
+	const r = await session.adapter.setBreakpointByLocation(session.cdp, {
+		file: (url ?? urlRegex ?? "") as string,
+		line,
+		condition: builtCondition,
+		url,
+		urlRegex,
+		scriptId,
+		scripts: session.scripts,
+	});
 
 	// Re-create the ref entry in the ref table
 	const type = (meta.type as string) === "LP" ? "LP" : "BP";
@@ -390,15 +395,7 @@ export async function getBreakableLocations(
 		throw new Error(`No scriptId found for "${file}"`);
 	}
 
-	const r = await session.cdp.send("Debugger.getPossibleBreakpoints", {
-		start: { scriptId, lineNumber: startLine - 1 },
-		end: { scriptId, lineNumber: endLine },
-	});
-
-	return r.locations.map((loc) => ({
-		line: loc.lineNumber + 1, // Convert to 1-based
-		column: (loc.columnNumber ?? 0) + 1, // Convert to 1-based
-	}));
+	return session.adapter.getBreakableLocations(session.cdp, scriptId, startLine, endLine);
 }
 
 export async function setLogpoint(
@@ -423,19 +420,33 @@ export async function setLogpoint(
 		logExpr = `${logExpr}, false`;
 	}
 
-	const lpParams: Protocol.Debugger.SetBreakpointByUrlRequest = {
-		lineNumber: line - 1, // CDP uses 0-based lines
-		condition: logExpr,
-	};
+	let urlRegex: string | undefined;
+	if (!url) {
+		urlRegex = `${file.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}$`;
+	}
+
+	// Find scriptId for Bun adapter
+	let scriptId: string | undefined;
 	if (url) {
-		lpParams.url = url;
-	} else {
-		lpParams.urlRegex = `${file.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}$`;
+		for (const [sid, info] of session.scripts) {
+			if (info.url === url) {
+				scriptId = sid;
+				break;
+			}
+		}
 	}
 
-	const r = await session.cdp.send("Debugger.setBreakpointByUrl", lpParams);
+	const r = await session.adapter.setBreakpointByLocation(session.cdp, {
+		file,
+		line,
+		condition: logExpr,
+		url: url ?? undefined,
+		urlRegex,
+		scriptId,
+		scripts: session.scripts,
+	});
 
-	const loc = r.locations[0];
+	const loc = r.location;
 	const resolvedUrl = url ?? file;
 	const resolvedLine = loc ? loc.lineNumber + 1 : line;
 	const resolvedColumn = loc?.columnNumber;
@@ -478,7 +489,7 @@ export async function setExceptionPause(
 
 	// CDP only supports "none", "all", and "uncaught".
 	// Map "caught" to "all" since CDP does not have a "caught-only" mode.
-	let cdpState: Protocol.Debugger.SetPauseOnExceptionsRequest["state"];
+	let cdpState: "none" | "all" | "uncaught";
 	switch (mode) {
 		case "all":
 			cdpState = "all";

package/src/daemon/session-inspection.ts

@@ -188,7 +188,7 @@ export async function getVars(
 			const objectId = scopeObj.objectId;
 			if (!objectId) continue;
 
-			const propsResult = await session.cdp.send("Runtime.getProperties", {
+			const propsResult = await session.adapter.getProperties(session.cdp, {
 				objectId,
 				ownProperties: true,
 				generatePreview: true,
@@ -274,7 +274,7 @@ export async function getProps(
 		propsParams.accessorPropertiesOnly = false;
 	}
 
-	const propsResult = await session.cdp.send("Runtime.getProperties", propsParams);
+	const propsResult = await session.adapter.getProperties(session.cdp, propsParams);
 	const properties = propsResult.result ?? [];
 	const internalProps = options.internal ? (propsResult.internalProperties ?? []) : [];
 

package/src/daemon/session-state.ts

@@ -209,7 +209,7 @@ export async function buildState(
 						const objectId = scopeObj.objectId;
 						if (!objectId) continue;
 
-						const propsResult = await session.cdp.send("Runtime.getProperties", {
+						const propsResult = await session.adapter.getProperties(session.cdp, {
 							objectId,
 							ownProperties: true,
 							generatePreview: true,