agent-dbg 0.1.0

package/package.json

@@ -0,0 +1,30 @@
+{
+  "name": "agent-dbg",
+  "version": "0.1.0",
+  "description": "Node.js Debugger CLI for AI Agents",
+  "type": "module",
+  "bin": {
+    "ndbg": "./src/main.ts"
+  },
+  "scripts": {
+    "dev": "bun run src/main.ts",
+    "build": "bun build src/main.ts --compile --outfile dist/ndbg",
+    "test": "bun test",
+    "lint": "biome check .",
+    "format": "biome check --write .",
+    "typecheck": "tsc --noEmit"
+  },
+  "devDependencies": {
+    "@biomejs/biome": "^2.3.14",
+    "@types/bun": "latest",
+    "devtools-protocol": "^0.0.1581282"
+  },
+  "peerDependencies": {
+    "typescript": "^5"
+  },
+  "dependencies": {
+    "@jridgewell/trace-mapping": "^0.3.31",
+    "zod": "^4.0.0"
+  },
+  "module": "index.ts"
+}

package/src/cdp/client.ts

@@ -0,0 +1,198 @@
+import type { ProtocolMapping } from "devtools-protocol/types/protocol-mapping.js";
+import type { CdpEvent, CdpRequest, CdpResponse } from "./types.ts";
+
+const DEFAULT_TIMEOUT_MS = 30_000;
+
+type CdpCommand = keyof ProtocolMapping.Commands;
+type CdpEventName = keyof ProtocolMapping.Events;
+
+// biome-ignore lint/suspicious/noExplicitAny: Required for handler map that stores both typed and untyped handlers
+type AnyHandler = (...args: any[]) => void;
+
+interface PendingRequest {
+	resolve: (result: unknown) => void;
+	reject: (error: Error) => void;
+	timer: ReturnType<typeof setTimeout>;
+}
+
+export class CdpClient {
+	private ws: WebSocket;
+	private nextId = 1;
+	private pending = new Map<number, PendingRequest>();
+	private listeners = new Map<string, Set<AnyHandler>>();
+	private isConnected = false;
+
+	private constructor(ws: WebSocket) {
+		this.ws = ws;
+		this.isConnected = true;
+		this.setupHandlers();
+	}
+
+	static async connect(wsUrl: string): Promise<CdpClient> {
+		return new Promise<CdpClient>((resolve, reject) => {
+			const ws = new WebSocket(wsUrl);
+
+			const onOpen = () => {
+				ws.removeEventListener("error", onError);
+				const client = new CdpClient(ws);
+				resolve(client);
+			};
+
+			const onError = (event: Event) => {
+				ws.removeEventListener("open", onOpen);
+				const message = event instanceof ErrorEvent ? event.message : "WebSocket connection failed";
+				reject(new Error(message));
+			};
+
+			ws.addEventListener("open", onOpen, { once: true });
+			ws.addEventListener("error", onError, { once: true });
+		});
+	}
+
+	async send<T extends CdpCommand>(
+		method: T,
+		...params: ProtocolMapping.Commands[T]["paramsType"]
+	): Promise<ProtocolMapping.Commands[T]["returnType"]>;
+	async send(method: string, params?: Record<string, unknown>): Promise<unknown>;
+	async send(method: string, ...args: unknown[]): Promise<unknown> {
+		if (!this.isConnected) {
+			throw new Error("CDP client is not connected");
+		}
+
+		const params = args[0] as Record<string, unknown> | undefined;
+		const id = this.nextId++;
+		const request: CdpRequest = { id, method };
+		if (params !== undefined) {
+			request.params = params;
+		}
+
+		return new Promise<unknown>((resolve, reject) => {
+			const timer = setTimeout(() => {
+				this.pending.delete(id);
+				reject(new Error(`CDP request timed out: ${method} (id=${id})`));
+			}, DEFAULT_TIMEOUT_MS);
+
+			this.pending.set(id, { resolve, reject, timer });
+			this.ws.send(JSON.stringify(request));
+		});
+	}
+
+	on<T extends CdpEventName>(event: T, handler: (...args: ProtocolMapping.Events[T]) => void): void;
+	on(event: string, handler: (params: unknown) => void): void;
+	on(event: string, handler: AnyHandler): void {
+		let handlers = this.listeners.get(event);
+		if (!handlers) {
+			handlers = new Set();
+			this.listeners.set(event, handlers);
+		}
+		handlers.add(handler);
+	}
+
+	off<T extends CdpEventName>(
+		event: T,
+		handler: (...args: ProtocolMapping.Events[T]) => void,
+	): void;
+	off(event: string, handler: (params: unknown) => void): void;
+	off(event: string, handler: AnyHandler): void {
+		const handlers = this.listeners.get(event);
+		if (handlers) {
+			handlers.delete(handler);
+			if (handlers.size === 0) {
+				this.listeners.delete(event);
+			}
+		}
+	}
+
+	async enableDomains(): Promise<void> {
+		await Promise.all([
+			this.send("Debugger.enable"),
+			this.send("Runtime.enable"),
+			this.send("Profiler.enable"),
+			this.send("HeapProfiler.enable"),
+		]);
+	}
+
+	async runIfWaitingForDebugger(): Promise<void> {
+		await this.send("Runtime.runIfWaitingForDebugger");
+	}
+
+	disconnect(): void {
+		if (!this.isConnected) {
+			return;
+		}
+		this.isConnected = false;
+
+		const error = new Error("CDP client disconnected");
+		for (const [id, pending] of this.pending) {
+			clearTimeout(pending.timer);
+			pending.reject(error);
+			this.pending.delete(id);
+		}
+
+		this.listeners.clear();
+		this.ws.close();
+	}
+
+	get connected(): boolean {
+		return this.isConnected;
+	}
+
+	/** Exposed for testing: directly handle a raw message string. */
+	handleMessage(data: string): void {
+		this.onMessage(data);
+	}
+
+	private setupHandlers(): void {
+		this.ws.addEventListener("message", (event: MessageEvent) => {
+			const data = typeof event.data === "string" ? event.data : String(event.data);
+			this.onMessage(data);
+		});
+
+		this.ws.addEventListener("close", () => {
+			this.isConnected = false;
+			const error = new Error("WebSocket connection closed");
+			for (const [id, pending] of this.pending) {
+				clearTimeout(pending.timer);
+				pending.reject(error);
+				this.pending.delete(id);
+			}
+		});
+
+		this.ws.addEventListener("error", () => {
+			// Error events are followed by close events, so cleanup happens there.
+		});
+	}
+
+	private onMessage(data: string): void {
+		let parsed: CdpResponse | CdpEvent;
+		try {
+			parsed = JSON.parse(data) as CdpResponse | CdpEvent;
+		} catch {
+			return;
+		}
+
+		if ("id" in parsed && typeof parsed.id === "number") {
+			const response = parsed as CdpResponse;
+			const pending = this.pending.get(response.id);
+			if (!pending) {
+				return;
+			}
+			this.pending.delete(response.id);
+			clearTimeout(pending.timer);
+
+			if (response.error) {
+				pending.reject(new Error(`CDP error (${response.error.code}): ${response.error.message}`));
+			} else {
+				pending.resolve(response.result);
+			}
+		} else if ("method" in parsed) {
+			const event = parsed as CdpEvent;
+			const handlers = this.listeners.get(event.method);
+			if (handlers) {
+				for (const handler of handlers) {
+					handler(event.params);
+				}
+			}
+		}
+	}
+}

package/src/cdp/types.ts

@@ -0,0 +1,16 @@
+export interface CdpRequest {
+	id: number;
+	method: string;
+	params?: Record<string, unknown>;
+}
+
+export interface CdpResponse {
+	id: number;
+	result?: unknown;
+	error?: { code: number; message: string };
+}
+
+export interface CdpEvent {
+	method: string;
+	params?: unknown;
+}

package/src/cli/parser.ts

@@ -0,0 +1,287 @@
+import { registry } from "./registry.ts";
+import type { GlobalFlags, ParsedArgs } from "./types.ts";
+
+const GLOBAL_FLAGS = new Set(["session", "json", "color", "help-agent", "help"]);
+const BOOLEAN_FLAGS = new Set([
+	"json",
+	"color",
+	"help-agent",
+	"help",
+	"brk",
+	"compact",
+	"all-scopes",
+	"vars",
+	"stack",
+	"breakpoints",
+	"code",
+	"own",
+	"private",
+	"internal",
+	"regex",
+	"case-sensitive",
+	"detailed",
+	"follow",
+	"clear",
+	"uncovered",
+	"include-gc",
+	"silent",
+	"side-effect-free",
+	"sourcemap",
+	"dry-run",
+	"continue",
+	"all",
+	"cleanup",
+	"disable",
+	"generated",
+]);
+
+export function parseArgs(argv: string[]): ParsedArgs {
+	const flags: Record<string, string | boolean> = {};
+	const positionals: string[] = [];
+	let command = "";
+	let subcommand: string | null = null;
+
+	let i = 0;
+
+	// Extract command (first non-flag argument)
+	while (i < argv.length) {
+		const arg = argv[i];
+		if (arg === undefined) break;
+		if (arg.startsWith("-")) break;
+		if (!command) {
+			command = arg;
+		} else if (!subcommand) {
+			subcommand = arg;
+		} else {
+			positionals.push(arg);
+		}
+		i++;
+	}
+
+	// Parse remaining arguments
+	while (i < argv.length) {
+		const arg = argv[i];
+		if (arg === undefined) {
+			i++;
+			continue;
+		}
+
+		if (arg === "--") {
+			// Everything after -- is positional
+			i++;
+			while (i < argv.length) {
+				const rest = argv[i];
+				if (rest !== undefined) positionals.push(rest);
+				i++;
+			}
+			break;
+		}
+
+		if (arg.startsWith("--")) {
+			const key = arg.slice(2);
+			if (BOOLEAN_FLAGS.has(key)) {
+				flags[key] = true;
+			} else {
+				const next = argv[i + 1];
+				if (next !== undefined && !next.startsWith("-")) {
+					flags[key] = next;
+					i++;
+				} else {
+					flags[key] = true;
+				}
+			}
+		} else if (arg.startsWith("-") && arg.length === 2) {
+			// Short flags
+			const key = arg.slice(1);
+			const shortMap: Record<string, string> = {
+				v: "vars",
+				s: "stack",
+				b: "breakpoints",
+				c: "code",
+			};
+			const mapped = shortMap[key];
+			if (mapped) {
+				flags[mapped] = true;
+			} else {
+				flags[key] = true;
+			}
+		} else {
+			positionals.push(arg);
+		}
+		i++;
+	}
+
+	const global: GlobalFlags = {
+		session: typeof flags.session === "string" ? flags.session : "default",
+		json: flags.json === true,
+		color: flags.color === true,
+		helpAgent: flags["help-agent"] === true,
+		help: flags.help === true,
+	};
+
+	// Remove global flags from flags map
+	for (const key of GLOBAL_FLAGS) {
+		delete flags[key];
+	}
+
+	return { command, subcommand, positionals, flags, global };
+}
+
+export async function run(args: ParsedArgs): Promise<number> {
+	if (args.global.helpAgent) {
+		printHelpAgent();
+		return 0;
+	}
+
+	if (!args.command || args.global.help) {
+		printHelp();
+		return args.command ? 0 : 1;
+	}
+
+	const handler = registry.get(args.command);
+	if (!handler) {
+		console.error(`✗ Unknown command: ${args.command}`);
+		console.error("  → Try: ndbg --help");
+		return 1;
+	}
+
+	try {
+		return await handler(args);
+	} catch (err) {
+		const message = err instanceof Error ? err.message : String(err);
+		console.error(`✗ ${message}`);
+		return 1;
+	}
+}
+
+function printHelp(): void {
+	console.log(`ndbg — Node.js debugger CLI for AI agents
+
+Usage: ndbg <command> [options]
+
+Session:
+  launch [--brk] <command...>      Start + attach debugger
+  attach <pid|ws-url|port>         Attach to running process
+  stop                             Kill process + daemon
+  sessions [--cleanup]             List active sessions
+  status                           Session info
+
+Execution (returns state automatically):
+  continue                         Resume execution
+  step [over|into|out]             Step one statement
+  run-to <file>:<line>             Continue to location
+  pause                            Interrupt running process
+  restart-frame [@fN]              Re-execute frame from beginning
+
+Inspection:
+  state [-v|-s|-b|-c]              Debug state snapshot
+    [--depth N] [--lines N] [--frame @fN] [--all-scopes] [--compact] [--generated]
+  vars [name...]                   Show local variables
+    [--frame @fN] [--all-scopes]
+  stack [--async-depth N]          Show call stack
+    [--generated]
+  eval <expression>                Evaluate expression
+    [--frame @fN] [--silent] [--timeout MS] [--side-effect-free]
+  props <@ref>                     Expand object properties
+    [--own] [--depth N] [--private] [--internal]
+  source [--lines N]               Show source code
+    [--file <path>] [--all] [--generated]
+  search <query>                   Search loaded scripts
+    [--regex] [--case-sensitive] [--file <id>]
+  scripts [--filter <pattern>]     List loaded scripts
+  console [--since N] [--level]    Console output
+    [--clear]
+  exceptions [--since N]           Captured exceptions
+
+Breakpoints:
+  break <file>:<line>              Set breakpoint
+    [--condition <expr>] [--hit-count <n>] [--continue] [--pattern <regex>:<line>]
+  break-rm <BP#|all>               Remove breakpoint
+  break-ls                         List breakpoints
+  break-toggle <BP#|all>           Enable/disable breakpoints
+  breakable <file>:<start>-<end>   List valid breakpoint locations
+  logpoint <file>:<line> <tpl>     Set logpoint
+    [--condition <expr>]
+  catch [all|uncaught|caught|none] Pause on exceptions
+
+Mutation:
+  set <@ref|name> <value>          Change variable value
+  set-return <value>               Change return value (at return point)
+  hotpatch <file> [--dry-run]      Live-edit script source
+
+Blackboxing:
+  blackbox <pattern...>            Skip stepping into matching scripts
+  blackbox-ls                      List current patterns
+  blackbox-rm <pattern|all>        Remove patterns
+
+Source Maps:
+  sourcemap [file]                 Show source map info
+  sourcemap --disable              Disable resolution globally
+
+Global flags:
+  --session NAME                   Target session (default: "default")
+  --json                           JSON output
+  --color                          ANSI colors
+  --help-agent                     LLM reference card
+  --help                           Show this help`);
+}
+
+function printHelpAgent(): void {
+	console.log(`ndbg — Node.js debugger CLI for AI agents
+
+CORE LOOP:
+  1. ndbg launch --brk "node app.js"    → pauses at first line, returns state
+  2. ndbg break src/file.ts:42          → set breakpoint
+  3. ndbg continue                      → run to breakpoint, returns state
+  4. Inspect: ndbg vars, ndbg eval, ndbg props @v1
+  5. Mutate/fix: ndbg set @v1 value, ndbg hotpatch src/file.ts
+  6. Repeat from 3
+
+REFS: Every output assigns @refs. Use them everywhere:
+  @v1..@vN  variables    |  ndbg props @v1, ndbg set @v2 true
+  @f0..@fN  stack frames |  ndbg eval --frame @f1
+  BP#1..N   breakpoints  |  ndbg break-rm BP#1, ndbg break-toggle BP#1
+
+EXECUTION (all return state automatically):
+  ndbg continue              Resume to next breakpoint
+  ndbg step [over|into|out]  Step one statement
+  ndbg run-to file:line      Continue to location
+  ndbg pause                 Interrupt running process
+  ndbg restart-frame [@fN]   Re-run frame from beginning
+
+BREAKPOINTS:
+  ndbg break file:line [--condition expr] [--hit-count N] [--continue]
+  ndbg break --pattern "regex":line
+  ndbg break-rm <BP#|all>    Remove breakpoints
+  ndbg break-ls              List breakpoints
+  ndbg break-toggle <BP#|all>  Enable/disable breakpoints
+  ndbg breakable file:start-end  Valid breakpoint locations
+  ndbg logpoint file:line "template \${var}" [--condition expr]
+  ndbg catch [all|uncaught|caught|none]
+
+INSPECTION:
+  ndbg state [-v|-s|-b|-c] [--depth N] [--lines N] [--frame @fN] [--all-scopes] [--compact] [--generated]
+  ndbg vars [name...] [--frame @fN] [--all-scopes]
+  ndbg stack [--async-depth N] [--generated]
+  ndbg eval <expr> [--frame @fN] [--silent] [--timeout MS] [--side-effect-free]
+  ndbg props @ref [--own] [--depth N] [--private] [--internal]
+  ndbg source [--lines N] [--file path] [--all] [--generated]
+  ndbg search "query" [--regex] [--case-sensitive] [--file id]
+  ndbg scripts [--filter pattern]
+  ndbg console [--since N] [--level type] [--clear]
+  ndbg exceptions [--since N]
+
+MUTATION:
+  ndbg set <@ref|name> <value>   Change variable
+  ndbg set-return <value>        Change return value (at return point)
+  ndbg hotpatch <file> [--dry-run]  Live-edit code (no restart!)
+
+BLACKBOXING:
+  ndbg blackbox <pattern...>     Skip stepping into matching scripts
+  ndbg blackbox-ls               List current patterns
+  ndbg blackbox-rm <pattern|all> Remove patterns
+
+SOURCE MAPS:
+  ndbg sourcemap [file]          Show source map info
+  ndbg sourcemap --disable       Disable resolution globally`);
+}

package/src/cli/registry.ts

@@ -0,0 +1,7 @@
+import type { CommandHandler } from "./types.ts";
+
+export const registry = new Map<string, CommandHandler>();
+
+export function registerCommand(name: string, handler: CommandHandler): void {
+	registry.set(name, handler);
+}

package/src/cli/types.ts

@@ -0,0 +1,24 @@
+export interface GlobalFlags {
+	session: string;
+	json: boolean;
+	color: boolean;
+	helpAgent: boolean;
+	help: boolean;
+}
+
+export interface ParsedArgs {
+	command: string;
+	subcommand: string | null;
+	positionals: string[];
+	flags: Record<string, string | boolean>;
+	global: GlobalFlags;
+}
+
+export type CommandHandler = (args: ParsedArgs) => Promise<number>;
+
+export interface CommandDef {
+	name: string;
+	description: string;
+	usage: string;
+	handler: CommandHandler;
+}

package/src/commands/attach.ts

@@ -0,0 +1,47 @@
+import { registerCommand } from "../cli/registry.ts";
+import { DaemonClient } from "../daemon/client.ts";
+import { spawnDaemon } from "../daemon/spawn.ts";
+
+registerCommand("attach", async (args) => {
+	const session = args.global.session;
+	const target = args.subcommand ?? args.positionals[0];
+
+	if (!target) {
+		console.error("No target specified");
+		console.error("  -> Try: ndbg attach <ws-url | port>");
+		return 1;
+	}
+
+	// Check if daemon already running
+	if (DaemonClient.isRunning(session)) {
+		console.error(`Session "${session}" is already active`);
+		console.error(`  -> Try: ndbg stop --session ${session}`);
+		return 1;
+	}
+
+	// Spawn daemon
+	const timeout =
+		typeof args.flags.timeout === "string" ? parseInt(args.flags.timeout, 10) : undefined;
+	await spawnDaemon(session, { timeout });
+
+	// Send attach command
+	const client = new DaemonClient(session);
+	const response = await client.request("attach", { target });
+
+	if (!response.ok) {
+		console.error(`${response.error}`);
+		if (response.suggestion) console.error(`  ${response.suggestion}`);
+		return 1;
+	}
+
+	const data = response.data as { wsUrl: string };
+
+	if (args.global.json) {
+		console.log(JSON.stringify(data, null, 2));
+	} else {
+		console.log(`Session "${session}" attached`);
+		console.log(`Connected to ${data.wsUrl}`);
+	}
+
+	return 0;
+});

package/src/commands/blackbox-ls.ts

@@ -0,0 +1,38 @@
+import { registerCommand } from "../cli/registry.ts";
+import { DaemonClient } from "../daemon/client.ts";
+
+registerCommand("blackbox-ls", async (args) => {
+	const session = args.global.session;
+
+	if (!DaemonClient.isRunning(session)) {
+		console.error(`No active session "${session}"`);
+		console.error("  -> Try: ndbg launch --brk node app.js");
+		return 1;
+	}
+
+	const client = new DaemonClient(session);
+	const response = await client.request("blackbox-ls");
+
+	if (!response.ok) {
+		console.error(`${response.error}`);
+		if (response.suggestion) console.error(`  ${response.suggestion}`);
+		return 1;
+	}
+
+	const data = response.data as string[];
+
+	if (args.global.json) {
+		console.log(JSON.stringify(data, null, 2));
+	} else {
+		if (data.length === 0) {
+			console.log("No blackbox patterns set");
+		} else {
+			console.log("Blackbox patterns:");
+			for (const p of data) {
+				console.log(`  ${p}`);
+			}
+		}
+	}
+
+	return 0;
+});