agent-dbg 0.1.2 → 0.1.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-dbg",
-  "version": "0.1.2",
+  "version": "0.1.3",
   "description": "Node.js Debugger CLI for AI Agents",
   "type": "module",
   "bin": {

package/src/commands/attach.ts

@@ -1,6 +1,6 @@
 import { registerCommand } from "../cli/registry.ts";
 import { DaemonClient } from "../daemon/client.ts";
-import { spawnDaemon } from "../daemon/spawn.ts";
+import { ensureDaemon } from "../daemon/spawn.ts";
 
 registerCommand("attach", async (args) => {
 	const session = args.global.session;
@@ -12,17 +12,17 @@ registerCommand("attach", async (args) => {
 		return 1;
 	}
 
-	// Check if daemon already running
+	// Check if daemon already running (PID-aware — stale sockets won't block)
 	if (DaemonClient.isRunning(session)) {
 		console.error(`Session "${session}" is already active`);
 		console.error(`  -> Try: agent-dbg stop --session ${session}`);
 		return 1;
 	}
 
-	// Spawn daemon
+	// Ensure daemon is running — auto-cleans stale sockets if daemon is dead
 	const timeout =
 		typeof args.flags.timeout === "string" ? parseInt(args.flags.timeout, 10) : undefined;
-	await spawnDaemon(session, { timeout });
+	await ensureDaemon(session, { timeout });
 
 	// Send attach command
 	const client = new DaemonClient(session);

package/src/commands/launch.ts

@@ -1,6 +1,6 @@
 import { registerCommand } from "../cli/registry.ts";
 import { DaemonClient } from "../daemon/client.ts";
-import { spawnDaemon } from "../daemon/spawn.ts";
+import { ensureDaemon } from "../daemon/spawn.ts";
 import { shortPath } from "../formatter/path.ts";
 
 registerCommand("launch", async (args) => {
@@ -23,10 +23,8 @@ registerCommand("launch", async (args) => {
 		return 1;
 	}
 
-	// Spawn daemon if not already running (e.g. started externally for debugging)
-	if (!DaemonClient.isRunning(session)) {
-		await spawnDaemon(session, { timeout });
-	}
+	// Ensure daemon is running — auto-cleans stale sockets if daemon is dead
+	await ensureDaemon(session, { timeout });
 
 	// Send launch command to daemon
 	const client = new DaemonClient(session);

package/src/commands/logs.ts

@@ -10,10 +10,11 @@ import {
 } from "node:fs";
 import type { CdpLogEntry } from "../cdp/logger.ts";
 import { registerCommand } from "../cli/registry.ts";
-import { getLogPath } from "../daemon/paths.ts";
-import { formatLogEntry } from "../formatter/logs.ts";
+import type { DaemonLogEntry } from "../daemon/logger.ts";
+import { getDaemonLogPath, getLogPath } from "../daemon/paths.ts";
+import { formatDaemonLogEntry, formatLogEntry } from "../formatter/logs.ts";
 
-function parseEntries(text: string): CdpLogEntry[] {
+function parseCdpEntries(text: string): CdpLogEntry[] {
 	const entries: CdpLogEntry[] = [];
 	for (const line of text.split("\n")) {
 		if (!line.trim()) continue;
@@ -26,11 +27,28 @@ function parseEntries(text: string): CdpLogEntry[] {
 	return entries;
 }
 
+function parseDaemonEntries(text: string): DaemonLogEntry[] {
+	const entries: DaemonLogEntry[] = [];
+	for (const line of text.split("\n")) {
+		if (!line.trim()) continue;
+		try {
+			entries.push(JSON.parse(line) as DaemonLogEntry);
+		} catch {
+			// skip malformed lines
+		}
+	}
+	return entries;
+}
+
 function filterByDomain(entries: CdpLogEntry[], domain: string): CdpLogEntry[] {
 	return entries.filter((e) => e.method.startsWith(`${domain}.`));
 }
 
-function printEntries(entries: CdpLogEntry[], json: boolean): void {
+function filterByLevel(entries: DaemonLogEntry[], level: string): DaemonLogEntry[] {
+	return entries.filter((e) => e.level === level);
+}
+
+function printCdpEntries(entries: CdpLogEntry[], json: boolean): void {
 	for (const entry of entries) {
 		if (json) {
 			console.log(JSON.stringify(entry));
@@ -40,40 +58,58 @@ function printEntries(entries: CdpLogEntry[], json: boolean): void {
 	}
 }
 
+function printDaemonEntries(entries: DaemonLogEntry[], json: boolean): void {
+	for (const entry of entries) {
+		if (json) {
+			console.log(JSON.stringify(entry));
+		} else {
+			console.log(formatDaemonLogEntry(entry));
+		}
+	}
+}
+
 registerCommand("logs", async (args) => {
 	const session = args.global.session;
-	const logPath = getLogPath(session);
+	const isDaemon = args.flags.daemon === true;
+	const logPath = isDaemon ? getDaemonLogPath(session) : getLogPath(session);
 
 	// --clear: truncate log file
 	if (args.flags.clear === true) {
 		if (existsSync(logPath)) {
 			writeFileSync(logPath, "");
-			console.log("Log cleared");
+			console.log(`${isDaemon ? "Daemon log" : "Log"} cleared`);
 		} else {
-			console.log("No log file to clear");
+			console.log(`No ${isDaemon ? "daemon " : ""}log file to clear`);
 		}
 		return 0;
 	}
 
 	if (!existsSync(logPath)) {
-		console.error(`No log file for session "${session}"`);
+		console.error(`No ${isDaemon ? "daemon " : ""}log file for session "${session}"`);
 		console.error("  -> Try: agent-dbg launch --brk node app.js");
 		return 1;
 	}
 
 	const isJson = args.global.json;
 	const domain = typeof args.flags.domain === "string" ? args.flags.domain : undefined;
+	const level = typeof args.flags.level === "string" ? args.flags.level : undefined;
 	const limit = typeof args.flags.limit === "string" ? parseInt(args.flags.limit, 10) : 50;
 	const follow = args.flags.follow === true;
 
 	// Read existing entries
 	const content = readFileSync(logPath, "utf-8");
-	let entries = parseEntries(content);
-	if (domain) entries = filterByDomain(entries, domain);
 
-	// Apply limit (show last N) — in follow mode, show all existing
-	const sliced = follow ? entries : entries.slice(-limit);
-	printEntries(sliced, isJson);
+	if (isDaemon) {
+		let entries = parseDaemonEntries(content);
+		if (level) entries = filterByLevel(entries, level);
+		const sliced = follow ? entries : entries.slice(-limit);
+		printDaemonEntries(sliced, isJson);
+	} else {
+		let entries = parseCdpEntries(content);
+		if (domain) entries = filterByDomain(entries, domain);
+		const sliced = follow ? entries : entries.slice(-limit);
+		printCdpEntries(sliced, isJson);
+	}
 
 	if (!follow) return 0;
 
@@ -92,9 +128,15 @@ registerCommand("logs", async (args) => {
 			closeSync(fd);
 			offset = size;
 
-			let newEntries = parseEntries(buf.toString("utf-8"));
-			if (domain) newEntries = filterByDomain(newEntries, domain);
-			printEntries(newEntries, isJson);
+			if (isDaemon) {
+				let newEntries = parseDaemonEntries(buf.toString("utf-8"));
+				if (level) newEntries = filterByLevel(newEntries, level);
+				printDaemonEntries(newEntries, isJson);
+			} else {
+				let newEntries = parseCdpEntries(buf.toString("utf-8"));
+				if (domain) newEntries = filterByDomain(newEntries, domain);
+				printCdpEntries(newEntries, isJson);
+			}
 		} catch {
 			// File may have been truncated or removed
 		}

package/src/daemon/client.ts

@@ -1,6 +1,6 @@
-import { existsSync, readdirSync } from "node:fs";
+import { existsSync, readFileSync, readdirSync, unlinkSync } from "node:fs";
 import { type DaemonResponse, DaemonResponseSchema } from "../protocol/messages.ts";
-import { getSocketDir, getSocketPath } from "./paths.ts";
+import { getLockPath, getSocketDir, getSocketPath } from "./paths.ts";
 
 const DEFAULT_TIMEOUT_MS = 30_000;
 
@@ -107,21 +107,43 @@ export class DaemonClient {
 		});
 	}
 
+	/**
+	 * Check if a daemon is running for the given session.
+	 * Uses PID liveness check (Docker-style): reads the lock file PID
+	 * and verifies the process is actually alive via kill(pid, 0).
+	 */
 	static isRunning(session: string): boolean {
 		const socketPath = getSocketPath(session);
 		if (!existsSync(socketPath)) {
 			return false;
 		}
-		// Try connecting to verify the daemon is actually alive
+
+		const lockPath = getLockPath(session);
+		if (!existsSync(lockPath)) {
+			// Socket exists but no lock file — stale
+			return false;
+		}
+
 		try {
-			// Use a sync approach: check if socket file exists
-			// A true liveness check requires async connection, so we check the file
+			const pid = parseInt(readFileSync(lockPath, "utf-8"), 10);
+			if (Number.isNaN(pid)) return false;
+			process.kill(pid, 0); // signal 0 = liveness check
 			return true;
 		} catch {
 			return false;
 		}
 	}
 
+	/**
+	 * Remove stale socket and lock files for a session whose daemon is no longer alive.
+	 */
+	static cleanStaleFiles(session: string): void {
+		const socketPath = getSocketPath(session);
+		const lockPath = getLockPath(session);
+		if (existsSync(socketPath)) unlinkSync(socketPath);
+		if (existsSync(lockPath)) unlinkSync(lockPath);
+	}
+
 	static async isAlive(session: string): Promise<boolean> {
 		const socketPath = getSocketPath(session);
 		if (!existsSync(socketPath)) {

package/src/daemon/entry.ts

@@ -1,4 +1,6 @@
 import type { DaemonRequest, DaemonResponse } from "../protocol/messages.ts";
+import { DaemonLogger } from "./logger.ts";
+import { ensureSocketDir, getDaemonLogPath } from "./paths.ts";
 import { DaemonServer } from "./server.ts";
 import { DebugSession } from "./session.ts";
 
@@ -22,8 +24,16 @@ if (timeoutIdx !== -1) {
 	}
 }
 
-const server = new DaemonServer(session, { idleTimeout: timeout });
-const debugSession = new DebugSession(session);
+ensureSocketDir();
+const daemonLogger = new DaemonLogger(getDaemonLogPath(session));
+daemonLogger.info("daemon.start", `Daemon starting for session "${session}"`, {
+	pid: process.pid,
+	session,
+	timeout,
+});
+
+const server = new DaemonServer(session, { idleTimeout: timeout, logger: daemonLogger });
+const debugSession = new DebugSession(session, { daemonLogger });
 
 server.onRequest(async (req: DaemonRequest): Promise<DaemonResponse> => {
 	switch (req.cmd) {

package/src/daemon/logger.ts

@@ -0,0 +1,51 @@
+import { appendFileSync, writeFileSync } from "node:fs";
+
+export interface DaemonLogEntry {
+	ts: number;
+	level: "info" | "warn" | "error" | "debug";
+	event: string;
+	message: string;
+	data?: Record<string, unknown>;
+}
+
+export class DaemonLogger {
+	private logPath: string;
+
+	constructor(logPath: string) {
+		this.logPath = logPath;
+		writeFileSync(logPath, "");
+	}
+
+	info(event: string, message: string, data?: Record<string, unknown>): void {
+		this.write("info", event, message, data);
+	}
+
+	warn(event: string, message: string, data?: Record<string, unknown>): void {
+		this.write("warn", event, message, data);
+	}
+
+	error(event: string, message: string, data?: Record<string, unknown>): void {
+		this.write("error", event, message, data);
+	}
+
+	debug(event: string, message: string, data?: Record<string, unknown>): void {
+		this.write("debug", event, message, data);
+	}
+
+	clear(): void {
+		writeFileSync(this.logPath, "");
+	}
+
+	private write(
+		level: DaemonLogEntry["level"],
+		event: string,
+		message: string,
+		data?: Record<string, unknown>,
+	): void {
+		const entry: DaemonLogEntry = { ts: Date.now(), level, event, message };
+		if (data !== undefined) {
+			entry.data = data;
+		}
+		appendFileSync(this.logPath, `${JSON.stringify(entry)}\n`);
+	}
+}

package/src/daemon/paths.ts

@@ -22,6 +22,10 @@ export function getLogPath(session: string): string {
 	return join(getSocketDir(), `${session}.cdp.log`);
 }
 
+export function getDaemonLogPath(session: string): string {
+	return join(getSocketDir(), `${session}.daemon.log`);
+}
+
 export function ensureSocketDir(): void {
 	const dir = getSocketDir();
 	if (!existsSync(dir)) {

package/src/daemon/server.ts

@@ -4,6 +4,7 @@ import {
 	DaemonRequestSchema,
 	type DaemonResponse,
 } from "../protocol/messages.ts";
+import type { DaemonLogger } from "./logger.ts";
 import { ensureSocketDir, getLockPath, getSocketPath } from "./paths.ts";
 
 type RequestHandler = (req: DaemonRequest) => Promise<DaemonResponse>;
@@ -16,12 +17,14 @@ export class DaemonServer {
 	private listener: ReturnType<typeof Bun.listen> | null = null;
 	private socketPath: string;
 	private lockPath: string;
+	private logger: DaemonLogger | null;
 
-	constructor(session: string, options: { idleTimeout: number }) {
+	constructor(session: string, options: { idleTimeout: number; logger?: DaemonLogger }) {
 		this.session = session;
 		this.idleTimeout = options.idleTimeout;
 		this.socketPath = getSocketPath(session);
 		this.lockPath = getLockPath(session);
+		this.logger = options.logger ?? null;
 	}
 
 	onRequest(handler: RequestHandler): void {
@@ -72,6 +75,7 @@ export class DaemonServer {
 				},
 				close() {},
 				error(_socket, error) {
+					server.logger?.error("socket.error", error.message);
 					console.error(`[daemon] socket error: ${error.message}`);
 				},
 			},
@@ -149,6 +153,10 @@ export class DaemonServer {
 		}
 		if (this.idleTimeout > 0) {
 			this.idleTimer = setTimeout(() => {
+				this.logger?.info(
+					"daemon.idle",
+					`Idle timeout reached (${this.idleTimeout}s), shutting down`,
+				);
 				this.stop();
 			}, this.idleTimeout * 1000);
 		}

package/src/daemon/session.ts

@@ -6,7 +6,8 @@ import type { RemoteObject } from "../formatter/values.ts";
 import { formatValue } from "../formatter/values.ts";
 import { RefTable } from "../refs/ref-table.ts";
 import { SourceMapResolver } from "../sourcemap/resolver.ts";
-import { ensureSocketDir, getLogPath } from "./paths.ts";
+import { DaemonLogger } from "./logger.ts";
+import { ensureSocketDir, getDaemonLogPath, getLogPath } from "./paths.ts";
 import {
 	addBlackbox as addBlackboxImpl,
 	listBlackbox as listBlackboxImpl,
@@ -140,7 +141,7 @@ export class DebugSession {
 	cdp: CdpClient | null = null;
 	refs: RefTable = new RefTable();
 	sourceMapResolver: SourceMapResolver = new SourceMapResolver();
-	childProcess: Subprocess<"ignore", "pipe", "pipe"> | null = null;
+	childProcess: Subprocess<"ignore", "ignore", "pipe"> | null = null;
 	state: "idle" | "running" | "paused" = "idle";
 	pauseInfo: PauseInfo | null = null;
 	pausedCallFrames: Protocol.Debugger.CallFrame[] = [];
@@ -157,11 +158,14 @@ export class DebugSession {
 	launchCommand: string[] | null = null;
 	launchOptions: { brk?: boolean; port?: number } | null = null;
 	cdpLogger: CdpLogger;
+	daemonLogger: DaemonLogger;
 
-	constructor(session: string) {
+	constructor(session: string, options?: { daemonLogger?: DaemonLogger }) {
 		this.session = session;
 		ensureSocketDir();
 		this.cdpLogger = new CdpLogger(getLogPath(session));
+		this.daemonLogger =
+			options?.daemonLogger ?? new DaemonLogger(getDaemonLogPath(session));
 	}
 
 	// ── Session lifecycle ─────────────────────────────────────────────
@@ -192,11 +196,16 @@ export class DebugSession {
 
 		const proc = Bun.spawn(spawnArgs, {
 			stdin: "ignore",
-			stdout: "pipe",
+			stdout: "ignore",
 			stderr: "pipe",
 		});
 		this.childProcess = proc;
 
+		this.daemonLogger.info("child.spawn", `Spawned process pid=${proc.pid}`, {
+			pid: proc.pid,
+			command: spawnArgs,
+		});
+
 		// Monitor child process exit in the background
 		this.monitorProcessExit(proc);
 
@@ -204,6 +213,10 @@ export class DebugSession {
 		const wsUrl = await this.readInspectorUrl(proc.stderr);
 		this.wsUrl = wsUrl;
 
+		this.daemonLogger.info("inspector.detected", `Inspector URL: ${wsUrl}`, {
+			wsUrl,
+		});
+
 		// Connect CDP
 		await this.connectCdp(wsUrl);
 
@@ -741,8 +754,10 @@ export class DebugSession {
 	}
 
 	private async connectCdp(wsUrl: string): Promise<void> {
+		this.daemonLogger.debug("cdp.connecting", `Connecting to ${wsUrl}`);
 		const cdp = await CdpClient.connect(wsUrl, this.cdpLogger);
 		this.cdp = cdp;
+		this.daemonLogger.info("cdp.connected", `CDP connected to ${wsUrl}`);
 
 		// Set up event handlers before enabling domains so we don't miss any events
 		this.setupCdpEventHandlers(cdp);
@@ -871,9 +886,13 @@ export class DebugSession {
 		});
 	}
 
-	private monitorProcessExit(proc: Subprocess<"ignore", "pipe", "pipe">): void {
+	private monitorProcessExit(proc: Subprocess<"ignore", "ignore", "pipe">): void {
 		proc.exited
-			.then(() => {
+			.then((exitCode) => {
+				this.daemonLogger.info("child.exit", `Process exited with code ${exitCode ?? "unknown"}`, {
+					pid: proc.pid,
+					exitCode: exitCode ?? null,
+				});
 				// Child process has exited
 				this.childProcess = null;
 				if (this.cdp) {
@@ -884,7 +903,10 @@ export class DebugSession {
 				this.pauseInfo = null;
 				this.onProcessExit?.();
 			})
-			.catch(() => {
+			.catch((err) => {
+				this.daemonLogger.error("child.exit.error", `Error waiting for process exit: ${err}`, {
+					pid: proc.pid,
+				});
 				// Error waiting for exit, treat as exited
 				this.childProcess = null;
 				this.state = "idle";
@@ -907,13 +929,16 @@ export class DebugSession {
 				if (done) {
 					break;
 				}
-				accumulated += decoder.decode(value, { stream: true });
+				const chunk = decoder.decode(value, { stream: true });
+				accumulated += chunk;
+				this.daemonLogger.debug("child.stderr", chunk.trimEnd());
 
 				const match = INSPECTOR_URL_REGEX.exec(accumulated);
 				if (match?.[1]) {
 					clearTimeout(timeout);
-					// Release the reader so the stream is not locked
-					reader.releaseLock();
+					// Continue draining stderr in the background so proc.exited
+					// can resolve (Bun requires all piped streams to be consumed).
+					this.drainReader(reader);
 					return match[1];
 				}
 			}
@@ -922,6 +947,10 @@ export class DebugSession {
 		}
 
 		clearTimeout(timeout);
+		this.daemonLogger.error("inspector.failed", "Failed to detect inspector URL", {
+			stderr: accumulated.slice(0, 2000),
+			timeoutMs: INSPECTOR_TIMEOUT_MS,
+		});
 		throw new Error(
 			`Failed to detect inspector URL within ${INSPECTOR_TIMEOUT_MS}ms. Stderr: ${accumulated.slice(0, 500)}`,
 		);
@@ -955,4 +984,13 @@ export class DebugSession {
 
 		return wsUrl;
 	}
+
+	private drainReader(reader: { read(): Promise<{ done: boolean; value?: Uint8Array }> }): void {
+		const pump = (): void => {
+			reader.read().then(({ done }) => {
+				if (!done) pump();
+			}).catch(() => {});
+		};
+		pump();
+	}
 }

package/src/daemon/spawn.ts

@@ -1,5 +1,6 @@
-import { existsSync } from "node:fs";
-import { getSocketPath } from "./paths.ts";
+import { existsSync, openSync } from "node:fs";
+import { DaemonClient } from "./client.ts";
+import { ensureSocketDir, getDaemonLogPath, getSocketPath } from "./paths.ts";
 
 const POLL_INTERVAL_MS = 50;
 const SPAWN_TIMEOUT_MS = 5000;
@@ -30,11 +31,16 @@ export async function spawnDaemon(
 		spawnArgs.push("--timeout", String(options.timeout));
 	}
 
+	// Redirect daemon stdout/stderr to daemon log file so crashes are captured
+	// even before the DaemonLogger initializes inside the child process.
+	ensureSocketDir();
+	const logFd = openSync(getDaemonLogPath(session), "a");
+
 	const proc = Bun.spawn(spawnArgs, {
 		detached: true,
 		stdin: "ignore",
-		stdout: "ignore",
-		stderr: "ignore",
+		stdout: logFd,
+		stderr: logFd,
 	});
 
 	// Unref so the parent process can exit
@@ -51,3 +57,20 @@ export async function spawnDaemon(
 
 	throw new Error(`Daemon for session "${session}" failed to start within ${SPAWN_TIMEOUT_MS}ms`);
 }
+
+/**
+ * Ensure a daemon is running for the session. If the socket exists but the
+ * daemon process is dead (stale), cleans up and respawns automatically.
+ */
+export async function ensureDaemon(
+	session: string,
+	options?: { port?: number; timeout?: number },
+): Promise<void> {
+	if (DaemonClient.isRunning(session)) return;
+
+	// Clean up stale socket/lock files before spawning, otherwise
+	// spawnDaemon's poll loop would see the old socket and return immediately.
+	DaemonClient.cleanStaleFiles(session);
+
+	await spawnDaemon(session, options);
+}

package/src/formatter/logs.ts

@@ -1,4 +1,5 @@
 import type { CdpLogEntry } from "../cdp/logger.ts";
+import type { DaemonLogEntry } from "../daemon/logger.ts";
 
 function formatTime(ts: number): string {
 	const d = new Date(ts);
@@ -108,3 +109,17 @@ export function formatLogEntry(entry: CdpLogEntry): string {
 	const summary = summarizer ? summarizer(entry) : summarizeParams(entry);
 	return `${time}  <- ${entry.method}${summary ? `  ${summary}` : ""}`;
 }
+
+const levelColors: Record<string, string> = {
+	info: "INFO ",
+	warn: "WARN ",
+	error: "ERROR",
+	debug: "DEBUG",
+};
+
+export function formatDaemonLogEntry(entry: DaemonLogEntry): string {
+	const time = `[${formatTime(entry.ts)}]`;
+	const level = levelColors[entry.level] ?? entry.level.toUpperCase();
+	const data = entry.data ? `  ${truncate(JSON.stringify(entry.data), 120)}` : "";
+	return `${time} ${level} ${entry.event}: ${entry.message}${data}`;
+}