agent-dbg 0.1.3 → 0.1.4

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-dbg",
-  "version": "0.1.3",
+  "version": "0.1.4",
   "description": "Node.js Debugger CLI for AI Agents",
   "type": "module",
   "bin": {
@@ -9,6 +9,7 @@
   "scripts": {
     "dev": "bun run src/main.ts",
     "build": "bun build src/main.ts --outdir dist --target=bun",
+    "publish": "bun publish",
     "test": "bun test",
     "lint": "biome check .",
     "format": "biome check --write .",
@@ -17,6 +18,7 @@
   "devDependencies": {
     "@biomejs/biome": "^2.3.14",
     "@types/bun": "latest",
+    "@vscode/debugprotocol": "^1.68.0",
     "devtools-protocol": "^0.0.1581282"
   },
   "peerDependencies": {

package/src/commands/attach.ts

@@ -5,6 +5,7 @@ import { ensureDaemon } from "../daemon/spawn.ts";
 registerCommand("attach", async (args) => {
 	const session = args.global.session;
 	const target = args.subcommand ?? args.positionals[0];
+	const runtime = typeof args.flags.runtime === "string" ? args.flags.runtime : undefined;
 
 	if (!target) {
 		console.error("No target specified");
@@ -26,7 +27,7 @@ registerCommand("attach", async (args) => {
 
 	// Send attach command
 	const client = new DaemonClient(session);
-	const response = await client.request("attach", { target });
+	const response = await client.request("attach", { target, runtime });
 
 	if (!response.ok) {
 		console.error(`${response.error}`);

package/src/commands/break-fn.ts

@@ -0,0 +1,41 @@
+import { registerCommand } from "../cli/registry.ts";
+import { DaemonClient } from "../daemon/client.ts";
+
+registerCommand("break-fn", async (args) => {
+	const session = args.global.session;
+
+	if (!DaemonClient.isRunning(session)) {
+		console.error(`No active session "${session}"`);
+		console.error("  -> Try: agent-dbg launch --brk --runtime lldb ./program");
+		return 1;
+	}
+
+	const name = args.subcommand;
+	if (!name) {
+		console.error("Usage: agent-dbg break-fn <function-name>");
+		console.error("  Example: agent-dbg break-fn __assert_rtn");
+		console.error("  Example: agent-dbg break-fn 'yoga::Style::operator=='");
+		return 1;
+	}
+
+	const condition = typeof args.flags.condition === "string" ? args.flags.condition : undefined;
+
+	const client = new DaemonClient(session);
+	const response = await client.request("break-fn", { name, condition });
+
+	if (!response.ok) {
+		console.error(`${response.error}`);
+		if (response.suggestion) console.error(`  ${response.suggestion}`);
+		return 1;
+	}
+
+	const data = response.data as { ref: string };
+
+	if (args.global.json) {
+		console.log(JSON.stringify(data, null, 2));
+	} else {
+		console.log(`${data.ref}  fn:${name}`);
+	}
+
+	return 0;
+});

package/src/commands/launch.ts

@@ -9,6 +9,7 @@ registerCommand("launch", async (args) => {
 	const port = typeof args.flags.port === "string" ? parseInt(args.flags.port, 10) : undefined;
 	const timeout =
 		typeof args.flags.timeout === "string" ? parseInt(args.flags.timeout, 10) : undefined;
+	const runtime = typeof args.flags.runtime === "string" ? args.flags.runtime : undefined;
 
 	// Reconstruct the full command from subcommand + positionals.
 	// The parser treats the second non-flag word as subcommand, but for launch
@@ -28,7 +29,7 @@ registerCommand("launch", async (args) => {
 
 	// Send launch command to daemon
 	const client = new DaemonClient(session);
-	const response = await client.request("launch", { command, brk, port });
+	const response = await client.request("launch", { command, brk, port, runtime });
 
 	if (!response.ok) {
 		console.error(`${response.error}`);

package/src/daemon/client.ts

@@ -1,4 +1,4 @@
-import { existsSync, readFileSync, readdirSync, unlinkSync } from "node:fs";
+import { existsSync, readdirSync, readFileSync, unlinkSync } from "node:fs";
 import { type DaemonResponse, DaemonResponseSchema } from "../protocol/messages.ts";
 import { getLockPath, getSocketDir, getSocketPath } from "./paths.ts";
 

package/src/daemon/entry.ts

@@ -1,3 +1,4 @@
+import { DapSession } from "../dap/session.ts";
 import type { DaemonRequest, DaemonResponse } from "../protocol/messages.ts";
 import { DaemonLogger } from "./logger.ts";
 import { ensureSocketDir, getDaemonLogPath } from "./paths.ts";
@@ -33,7 +34,17 @@ daemonLogger.info("daemon.start", `Daemon starting for session "${session}"`, {
 });
 
 const server = new DaemonServer(session, { idleTimeout: timeout, logger: daemonLogger });
-const debugSession = new DebugSession(session, { daemonLogger });
+const cdpSession = new DebugSession(session, { daemonLogger });
+let dapSession: DapSession | null = null;
+
+function isDapRuntime(runtime: string | undefined): runtime is string {
+	return runtime !== undefined && runtime !== "node";
+}
+
+/** Return the active session — DapSession if one was launched, otherwise the CDP session. */
+function activeSession(): DebugSession | DapSession {
+	return dapSession ?? cdpSession;
+}
 
 server.onRequest(async (req: DaemonRequest): Promise<DaemonResponse> => {
 	switch (req.cmd) {
@@ -41,54 +52,64 @@ server.onRequest(async (req: DaemonRequest): Promise<DaemonResponse> => {
 			return { ok: true, data: "pong" };
 
 		case "launch": {
-			const { command, brk = true, port } = req.args;
-			const result = await debugSession.launch(command, { brk, port });
+			const { command, brk = true, port, runtime } = req.args;
+			if (isDapRuntime(runtime)) {
+				dapSession = new DapSession(session, runtime);
+				const result = await dapSession.launch(command, { brk });
+				return { ok: true, data: result };
+			}
+			const result = await cdpSession.launch(command, { brk, port });
 			return { ok: true, data: result };
 		}
 
 		case "attach": {
-			const { target } = req.args;
-			const result = await debugSession.attach(target);
+			const { target, runtime } = req.args;
+			if (isDapRuntime(runtime)) {
+				dapSession = new DapSession(session, runtime);
+				const result = await dapSession.attach(target);
+				return { ok: true, data: result };
+			}
+			const result = await cdpSession.attach(target);
 			return { ok: true, data: result };
 		}
 
 		case "status":
-			return { ok: true, data: debugSession.getStatus() };
+			return { ok: true, data: activeSession().getStatus() };
 
 		case "state": {
-			const stateResult = await debugSession.buildState(req.args);
+			const stateResult = await activeSession().buildState(req.args);
 			return { ok: true, data: stateResult };
 		}
 
 		case "continue": {
-			await debugSession.continue();
-			const stateAfter = await debugSession.buildState();
+			await activeSession().continue();
+			const stateAfter = await activeSession().buildState();
 			return { ok: true, data: stateAfter };
 		}
 
 		case "step": {
 			const { mode = "over" } = req.args;
-			await debugSession.step(mode);
-			const stateAfter = await debugSession.buildState();
+			await activeSession().step(mode);
+			const stateAfter = await activeSession().buildState();
 			return { ok: true, data: stateAfter };
 		}
 
 		case "pause": {
-			await debugSession.pause();
-			const stateAfter = await debugSession.buildState();
+			await activeSession().pause();
+			const stateAfter = await activeSession().buildState();
 			return { ok: true, data: stateAfter };
 		}
 
 		case "run-to": {
 			const { file, line } = req.args;
-			await debugSession.runTo(file, line);
-			const stateAfter = await debugSession.buildState();
+			await activeSession().runTo(file, line);
+			const stateAfter = await activeSession().buildState();
 			return { ok: true, data: stateAfter };
 		}
 
 		case "break": {
 			const { file, line, condition, hitCount, urlRegex, column } = req.args;
-			const bpResult = await debugSession.setBreakpoint(file, line, {
+			const bpResult = await activeSession().setBreakpoint(file, line, {
 				condition,
 				hitCount,
 				urlRegex,
@@ -97,22 +118,38 @@ server.onRequest(async (req: DaemonRequest): Promise<DaemonResponse> => {
 			return { ok: true, data: bpResult };
 		}
 
+		case "break-fn": {
+			const session = activeSession();
+			if (!("setFunctionBreakpoint" in session)) {
+				return {
+					ok: false,
+					error: "Function breakpoints are only supported with DAP runtimes (e.g. --runtime lldb)",
+					suggestion: "Use 'break <file>:<line>' for CDP sessions",
+				};
+			}
+			const { name, condition } = req.args;
+			const bpResult = await (session as DapSession).setFunctionBreakpoint(name, {
+				condition,
+			});
+			return { ok: true, data: bpResult };
+		}
+
 		case "break-rm": {
 			const { ref } = req.args;
 			if (ref === "all") {
-				await debugSession.removeAllBreakpoints();
+				await activeSession().removeAllBreakpoints();
 				return { ok: true, data: "all removed" };
 			}
-			await debugSession.removeBreakpoint(ref);
+			await activeSession().removeBreakpoint(ref);
 			return { ok: true, data: "removed" };
 		}
 
 		case "break-ls":
-			return { ok: true, data: debugSession.listBreakpoints() };
+			return { ok: true, data: activeSession().listBreakpoints() };
 
 		case "logpoint": {
 			const { file, line, template, condition, maxEmissions } = req.args;
-			const lpResult = await debugSession.setLogpoint(file, line, template, {
+			const lpResult = await activeSession().setLogpoint(file, line, template, {
 				condition,
 				maxEmissions,
 			});
@@ -121,136 +158,137 @@ server.onRequest(async (req: DaemonRequest): Promise<DaemonResponse> => {
 
 		case "catch": {
 			const { mode } = req.args;
-			await debugSession.setExceptionPause(mode);
+			await activeSession().setExceptionPause(mode);
 			return { ok: true, data: mode };
 		}
 
 		case "source": {
-			const sourceResult = await debugSession.getSource(req.args);
+			const sourceResult = await activeSession().getSource(req.args);
 			return { ok: true, data: sourceResult };
 		}
 
 		case "scripts": {
 			const { filter } = req.args;
-			const scriptsResult = debugSession.getScripts(filter);
+			const scriptsResult = activeSession().getScripts(filter);
 			return { ok: true, data: scriptsResult };
 		}
 
 		case "stack": {
-			const stackResult = debugSession.getStack(req.args);
+			const stackResult = activeSession().getStack(req.args);
 			return { ok: true, data: stackResult };
 		}
 
 		case "search": {
 			const { query, ...searchOptions } = req.args;
-			const searchResult = await debugSession.searchInScripts(query, searchOptions);
+			const searchResult = await activeSession().searchInScripts(query, searchOptions);
 			return { ok: true, data: searchResult };
 		}
 
 		case "console": {
-			const consoleResult = debugSession.getConsoleMessages(req.args);
+			const consoleResult = activeSession().getConsoleMessages(req.args);
 			return { ok: true, data: consoleResult };
 		}
 
 		case "exceptions": {
-			const exceptionsResult = debugSession.getExceptions(req.args);
+			const exceptionsResult = activeSession().getExceptions(req.args);
 			return { ok: true, data: exceptionsResult };
 		}
 
 		case "eval": {
 			const { expression, ...evalOptions } = req.args;
-			const evalResult = await debugSession.eval(expression, evalOptions);
+			const evalResult = await activeSession().eval(expression, evalOptions);
 			return { ok: true, data: evalResult };
 		}
 
 		case "vars": {
-			const varsResult = await debugSession.getVars(req.args);
+			const varsResult = await activeSession().getVars(req.args);
 			return { ok: true, data: varsResult };
 		}
 
 		case "props": {
 			const { ref, ...propsOptions } = req.args;
-			const propsResult = await debugSession.getProps(ref, propsOptions);
+			const propsResult = await activeSession().getProps(ref, propsOptions);
 			return { ok: true, data: propsResult };
 		}
 
 		case "blackbox": {
 			const { patterns } = req.args;
-			const result = await debugSession.addBlackbox(patterns);
+			const result = await activeSession().addBlackbox(patterns);
 			return { ok: true, data: result };
 		}
 
 		case "blackbox-ls": {
-			return { ok: true, data: debugSession.listBlackbox() };
+			return { ok: true, data: activeSession().listBlackbox() };
 		}
 
 		case "blackbox-rm": {
 			const { patterns } = req.args;
-			const result = await debugSession.removeBlackbox(patterns);
+			const result = await activeSession().removeBlackbox(patterns);
 			return { ok: true, data: result };
 		}
 
 		case "set": {
 			const { name, value, frame } = req.args;
-			const result = await debugSession.setVariable(name, value, { frame });
+			const result = await activeSession().setVariable(name, value, { frame });
 			return { ok: true, data: result };
 		}
 
 		case "set-return": {
 			const { value } = req.args;
-			const result = await debugSession.setReturnValue(value);
+			const result = await activeSession().setReturnValue(value);
 			return { ok: true, data: result };
 		}
 
 		case "hotpatch": {
 			const { file, source, dryRun } = req.args;
-			const result = await debugSession.hotpatch(file, source, { dryRun });
+			const result = await activeSession().hotpatch(file, source, { dryRun });
 			return { ok: true, data: result };
 		}
 
 		case "break-toggle": {
 			const { ref } = req.args;
-			const toggleResult = await debugSession.toggleBreakpoint(ref);
+			const toggleResult = await activeSession().toggleBreakpoint(ref);
 			return { ok: true, data: toggleResult };
 		}
 
 		case "breakable": {
 			const { file, startLine, endLine } = req.args;
-			const breakableResult = await debugSession.getBreakableLocations(file, startLine, endLine);
+			const breakableResult = await activeSession().getBreakableLocations(file, startLine, endLine);
 			return { ok: true, data: breakableResult };
 		}
 
 		case "restart-frame": {
 			const { frameRef } = req.args;
-			const restartResult = await debugSession.restartFrame(frameRef);
+			const restartResult = await activeSession().restartFrame(frameRef);
 			return { ok: true, data: restartResult };
 		}
 
 		case "sourcemap": {
 			const { file: smFile } = req.args;
 			if (smFile) {
-				const match = debugSession.sourceMapResolver.findScriptForSource(smFile);
+				const match = activeSession().sourceMapResolver.findScriptForSource(smFile);
 				if (match) {
-					const info = debugSession.sourceMapResolver.getInfo(match.scriptId);
+					const info = activeSession().sourceMapResolver.getInfo(match.scriptId);
 					return { ok: true, data: info ? [info] : [] };
 				}
 				return { ok: true, data: [] };
 			}
-			return { ok: true, data: debugSession.sourceMapResolver.getAllInfos() };
+			return { ok: true, data: activeSession().sourceMapResolver.getAllInfos() };
 		}
 
 		case "sourcemap-disable": {
-			debugSession.sourceMapResolver.setDisabled(true);
+			activeSession().sourceMapResolver.setDisabled(true);
 			return { ok: true, data: "disabled" };
 		}
 
 		case "restart": {
-			const result = await debugSession.restart();
+			const result = await activeSession().restart();
 			return { ok: true, data: result };
 		}
 
 		case "stop":
-			await debugSession.stop();
+			await activeSession().stop();
+			dapSession = null;
 			setTimeout(() => {
 				server.stop();
 				process.exit(0);

package/src/daemon/server.ts

@@ -56,11 +56,15 @@ export class DaemonServer {
 
 		const server = this;
 
-		this.listener = Bun.listen<{ buffer: string }>({
+		this.listener = Bun.listen<{
+			buffer: string;
+			pendingWrite: Buffer | null;
+			pendingOffset: number;
+		}>({
 			unix: this.socketPath,
 			socket: {
 				open(socket) {
-					socket.data = { buffer: "" };
+					socket.data = { buffer: "", pendingWrite: null, pendingOffset: 0 };
 					server.resetIdleTimer();
 				},
 				data(socket, data) {
@@ -73,6 +77,10 @@ export class DaemonServer {
 
 					server.handleMessage(socket, line);
 				},
+				drain(socket) {
+					// Continue writing any pending data
+					server.flushPending(socket);
+				},
 				close() {},
 				error(_socket, error) {
 					server.logger?.error("socket.error", error.message);
@@ -84,20 +92,49 @@ export class DaemonServer {
 		this.resetIdleTimer();
 	}
 
-	private handleMessage(
-		socket: { write(data: string | Buffer | Uint8Array): number; end(): void },
-		line: string,
-	): void {
+	// biome-ignore lint/suspicious/noExplicitAny: Bun socket type
+	private flushPending(socket: any): void {
+		const data = socket.data as {
+			pendingWrite: Buffer | null;
+			pendingOffset: number;
+		};
+		if (!data.pendingWrite) return;
+
+		while (data.pendingOffset < data.pendingWrite.length) {
+			const written = socket.write(data.pendingWrite.subarray(data.pendingOffset));
+			if (written === 0) {
+				// Still full — drain will call us again
+				return;
+			}
+			data.pendingOffset += written;
+		}
+
+		// All data flushed
+		data.pendingWrite = null;
+		data.pendingOffset = 0;
+		socket.end();
+	}
+
+	// biome-ignore lint/suspicious/noExplicitAny: Bun socket type
+	private sendResponse(socket: any, response: DaemonResponse): void {
+		const payload = Buffer.from(`${JSON.stringify(response)}\n`);
+		const written = socket.write(payload);
+		if (written < payload.length) {
+			// Partial write — store remainder for drain
+			socket.data.pendingWrite = payload;
+			socket.data.pendingOffset = written;
+		} else {
+			socket.end();
+		}
+	}
+
+	// biome-ignore lint/suspicious/noExplicitAny: Bun socket type
+	private handleMessage(socket: any, line: string): void {
 		let json: unknown;
 		try {
 			json = JSON.parse(line);
 		} catch {
-			const errResponse: DaemonResponse = {
-				ok: false,
-				error: "Invalid JSON",
-			};
-			socket.write(`${JSON.stringify(errResponse)}\n`);
-			socket.end();
+			this.sendResponse(socket, { ok: false, error: "Invalid JSON" });
 			return;
 		}
 
@@ -106,44 +143,40 @@ export class DaemonServer {
 			const obj = json as Record<string, unknown> | null;
 			const cmd =
 				obj && typeof obj === "object" && typeof obj.cmd === "string" ? obj.cmd : undefined;
-			const errResponse: DaemonResponse = cmd
-				? {
-						ok: false,
-						error: `Unknown command: ${cmd}`,
-						suggestion: "-> Try: agent-dbg --help",
-					}
-				: {
-						ok: false,
-						error: "Invalid request: must have { cmd: string, args: object }",
-					};
-			socket.write(`${JSON.stringify(errResponse)}\n`);
-			socket.end();
+			this.sendResponse(
+				socket,
+				cmd
+					? {
+							ok: false,
+							error: `Unknown command: ${cmd}`,
+							suggestion: "-> Try: agent-dbg --help",
+						}
+					: {
+							ok: false,
+							error: "Invalid request: must have { cmd: string, args: object }",
+						},
+			);
 			return;
 		}
 		const request: DaemonRequest = parsed.data;
 
 		if (!this.handler) {
-			const errResponse: DaemonResponse = {
+			this.sendResponse(socket, {
 				ok: false,
 				error: "No request handler registered",
-			};
-			socket.write(`${JSON.stringify(errResponse)}\n`);
-			socket.end();
+			});
 			return;
 		}
 
 		this.handler(request)
 			.then((response) => {
-				socket.write(`${JSON.stringify(response)}\n`);
-				socket.end();
+				this.sendResponse(socket, response);
 			})
 			.catch((err) => {
-				const errResponse: DaemonResponse = {
+				this.sendResponse(socket, {
 					ok: false,
 					error: err instanceof Error ? err.message : String(err),
-				};
-				socket.write(`${JSON.stringify(errResponse)}\n`);
-				socket.end();
+				});
 			});
 	}
 

package/src/daemon/session-breakpoints.ts

@@ -17,7 +17,8 @@ export async function setBreakpoint(
 	let originalFile: string | null = null;
 	let originalLine: number | null = null;
 	let actualLine = line;
-	let actualColumn: number | undefined = options?.column !== undefined ? options.column - 1 : undefined; // user column is 1-based
+	let actualColumn: number | undefined =
+		options?.column !== undefined ? options.column - 1 : undefined; // user column is 1-based
 	let actualFile = file;
 
 	if (!options?.urlRegex) {

package/src/daemon/session-mutation.ts

@@ -176,6 +176,7 @@ export async function hotpatch(
 	const setSourceParams: Protocol.Debugger.SetScriptSourceRequest = {
 		scriptId,
 		scriptSource: newSource,
+		allowTopFrameEditing: true,
 	};
 	if (options.dryRun) {
 		setSourceParams.dryRun = true;

package/src/daemon/session.ts

@@ -164,8 +164,7 @@ export class DebugSession {
 		this.session = session;
 		ensureSocketDir();
 		this.cdpLogger = new CdpLogger(getLogPath(session));
-		this.daemonLogger =
-			options?.daemonLogger ?? new DaemonLogger(getDaemonLogPath(session));
+		this.daemonLogger = options?.daemonLogger ?? new DaemonLogger(getDaemonLogPath(session));
 	}
 
 	// ── Session lifecycle ─────────────────────────────────────────────
@@ -987,9 +986,12 @@ export class DebugSession {
 
 	private drainReader(reader: { read(): Promise<{ done: boolean; value?: Uint8Array }> }): void {
 		const pump = (): void => {
-			reader.read().then(({ done }) => {
-				if (!done) pump();
-			}).catch(() => {});
+			reader
+				.read()
+				.then(({ done }) => {
+					if (!done) pump();
+				})
+				.catch(() => {});
 		};
 		pump();
 	}

package/src/daemon/spawn.ts

@@ -1,4 +1,4 @@
-import { existsSync, openSync } from "node:fs";
+import { existsSync, openSync, readFileSync } from "node:fs";
 import { DaemonClient } from "./client.ts";
 import { ensureSocketDir, getDaemonLogPath, getSocketPath } from "./paths.ts";
 
@@ -18,9 +18,9 @@ export async function spawnDaemon(
 	const execPath = process.execPath;
 	const scriptPath = process.argv[1];
 
-	// If argv[1] exists and is a .ts file, we're running via `bun run src/main.ts`
-	// Otherwise we're running as a compiled binary
-	if (scriptPath && scriptPath.endsWith(".ts")) {
+	// If argv[1] exists and is a script file (.ts or .js), we're running via
+	// `bun run src/main.ts` or `bun dist/main.js`. Otherwise we're a compiled binary.
+	if (scriptPath && (scriptPath.endsWith(".ts") || scriptPath.endsWith(".js"))) {
 		spawnArgs.push(execPath, "run", scriptPath);
 	} else {
 		spawnArgs.push(execPath);
@@ -55,7 +55,23 @@ export async function spawnDaemon(
 		await Bun.sleep(POLL_INTERVAL_MS);
 	}
 
-	throw new Error(`Daemon for session "${session}" failed to start within ${SPAWN_TIMEOUT_MS}ms`);
+	// Read daemon log to surface the actual error
+	const logPath = getDaemonLogPath(session);
+	let logTail = "";
+	try {
+		const log = readFileSync(logPath, "utf-8");
+		const lines = log.trimEnd().split("\n");
+		logTail = lines.slice(-20).join("\n");
+	} catch {}
+
+	const details = [
+		`Daemon for session "${session}" failed to start within ${SPAWN_TIMEOUT_MS}ms`,
+		`Spawn command: ${spawnArgs.join(" ")}`,
+		`Socket path: ${socketPath}`,
+		logTail ? `Daemon log (last 20 lines):\n${logTail}` : `No daemon log at ${logPath}`,
+	].join("\n");
+
+	throw new Error(details);
 }
 
 /**