@dungle-scrubs/tallow 0.8.0

package/extensions/debug/__tests__/logger.test.ts

@@ -0,0 +1,202 @@
+import { afterEach, beforeEach, describe, expect, it } from "bun:test";
+import { existsSync, mkdirSync, mkdtempSync, readFileSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { DebugLogger, isDebug, resetDebugCache } from "../logger.js";
+
+let tmpDir: string;
+const savedDebug = process.env.TALLOW_DEBUG;
+
+beforeEach(() => {
+	tmpDir = mkdtempSync(join(tmpdir(), "tallow-debug-test-"));
+	// Ensure no leaked TALLOW_DEBUG from other test files
+	delete process.env.TALLOW_DEBUG;
+	resetDebugCache();
+});
+
+afterEach(() => {
+	// Restore original state before cleanup
+	if (savedDebug !== undefined) {
+		process.env.TALLOW_DEBUG = savedDebug;
+	} else {
+		delete process.env.TALLOW_DEBUG;
+	}
+	rmSync(tmpDir, { recursive: true, force: true });
+});
+
+// ── isDebug() ────────────────────────────────────────────────
+
+describe("isDebug()", () => {
+	const origEnv = { ...process.env };
+
+	afterEach(() => {
+		process.env = { ...origEnv };
+		resetDebugCache();
+	});
+
+	it("returns true when TALLOW_DEBUG=1", () => {
+		process.env.TALLOW_DEBUG = "1";
+		expect(isDebug()).toBe(true);
+	});
+
+	it("returns true when TALLOW_DEBUG=stderr", () => {
+		process.env.TALLOW_DEBUG = "stderr";
+		expect(isDebug()).toBe(true);
+	});
+
+	it("returns true when NODE_ENV=development", () => {
+		delete process.env.TALLOW_DEBUG;
+		process.env.NODE_ENV = "development";
+		expect(isDebug()).toBe(true);
+	});
+
+	it("returns false when TALLOW_DEBUG=0", () => {
+		process.env.TALLOW_DEBUG = "0";
+		delete process.env.NODE_ENV;
+		// Can't reliably test source detection in bun — force production-like
+		expect(isDebug()).toBe(false);
+	});
+
+	it("returns false when TALLOW_DEBUG=false", () => {
+		process.env.TALLOW_DEBUG = "false";
+		delete process.env.NODE_ENV;
+		expect(isDebug()).toBe(false);
+	});
+
+	it("caches result after first call", () => {
+		process.env.TALLOW_DEBUG = "1";
+		expect(isDebug()).toBe(true);
+
+		// Change env — should still return cached value
+		process.env.TALLOW_DEBUG = "0";
+		expect(isDebug()).toBe(true);
+	});
+});
+
+// ── DebugLogger.log() ────────────────────────────────────────
+
+describe("DebugLogger.log()", () => {
+	it("writes valid JSONL to file", () => {
+		const logger = new DebugLogger("test-session-1", tmpDir);
+		logger.log("tool", "call", { name: "bash", args: { command: "ls" } });
+		logger.close();
+
+		const logPath = join(tmpDir, "debug.log");
+		expect(existsSync(logPath)).toBe(true);
+
+		const lines = readFileSync(logPath, "utf-8").trim().split("\n");
+		// First line is the log_start header, second is our entry
+		expect(lines.length).toBe(2);
+
+		const header = JSON.parse(lines[0]);
+		expect(header.cat).toBe("session");
+		expect(header.evt).toBe("log_start");
+		expect(header.data.sessionId).toBe("test-session-1");
+
+		const entry = JSON.parse(lines[1]);
+		expect(entry.cat).toBe("tool");
+		expect(entry.evt).toBe("call");
+		expect(entry.data.name).toBe("bash");
+		expect(entry.data.args).toEqual({ command: "ls" });
+	});
+
+	it("includes ISO timestamp", () => {
+		const logger = new DebugLogger("test-ts", tmpDir);
+		logger.log("session", "test", { foo: "bar" });
+		logger.close();
+
+		const lines = readFileSync(join(tmpDir, "debug.log"), "utf-8").trim().split("\n");
+		const entry = JSON.parse(lines[1]);
+		// ISO 8601 format check
+		expect(entry.ts).toMatch(/^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}/);
+	});
+
+	it("truncates long string values at 500 chars", () => {
+		const logger = new DebugLogger("test-trunc", tmpDir);
+		const longString = "x".repeat(1000);
+		logger.log("tool", "result", { output: longString });
+		logger.close();
+
+		const lines = readFileSync(join(tmpDir, "debug.log"), "utf-8").trim().split("\n");
+		const entry = JSON.parse(lines[1]);
+		expect(entry.data.output.length).toBeLessThan(600);
+		expect(entry.data.output).toContain("…[1000 chars]");
+	});
+
+	it("truncates nested object string values", () => {
+		const logger = new DebugLogger("test-nested", tmpDir);
+		const longString = "y".repeat(800);
+		logger.log("tool", "call", { args: { command: longString } });
+		logger.close();
+
+		const lines = readFileSync(join(tmpDir, "debug.log"), "utf-8").trim().split("\n");
+		const entry = JSON.parse(lines[1]);
+		expect(entry.data.args.command).toContain("…[800 chars]");
+	});
+
+	it("preserves short string values intact", () => {
+		const logger = new DebugLogger("test-short", tmpDir);
+		logger.log("session", "start", { cwd: "/dev/project" });
+		logger.close();
+
+		const lines = readFileSync(join(tmpDir, "debug.log"), "utf-8").trim().split("\n");
+		const entry = JSON.parse(lines[1]);
+		expect(entry.data.cwd).toBe("/dev/project");
+	});
+});
+
+// ── DebugLogger.close() ─────────────────────────────────────
+
+describe("DebugLogger.close()", () => {
+	it("makes subsequent log() calls no-ops", () => {
+		const logger = new DebugLogger("test-close", tmpDir);
+		logger.close();
+		logger.log("session", "after_close", { should: "not appear" });
+
+		const logPath = join(tmpDir, "debug.log");
+		const lines = readFileSync(logPath, "utf-8").trim().split("\n");
+		// Only the header line from construction
+		expect(lines.length).toBe(1);
+		expect(JSON.parse(lines[0]).evt).toBe("log_start");
+	});
+});
+
+// ── DebugLogger.clear() ─────────────────────────────────────
+
+describe("DebugLogger.clear()", () => {
+	it("truncates the log file", () => {
+		const logger = new DebugLogger("test-clear", tmpDir);
+		logger.log("session", "test", { data: "will be cleared" });
+		logger.clear();
+
+		const logPath = join(tmpDir, "debug.log");
+		const content = readFileSync(logPath, "utf-8");
+		expect(content).toBe("");
+
+		logger.close();
+	});
+});
+
+// ── stderr mode ──────────────────────────────────────────────
+
+describe("stderr mode", () => {
+	const origEnv = { ...process.env };
+
+	afterEach(() => {
+		process.env = { ...origEnv };
+	});
+
+	it("does not create a file when TALLOW_DEBUG=stderr", () => {
+		process.env.TALLOW_DEBUG = "stderr";
+		const stderrDir = join(tmpDir, "stderr-test");
+		mkdirSync(stderrDir, { recursive: true });
+
+		const logger = new DebugLogger("test-stderr", stderrDir);
+		logger.log("session", "test", { mode: "stderr" });
+		logger.close();
+
+		// No log file should be created (writes go to stderr)
+		const logPath = join(stderrDir, "debug.log");
+		expect(existsSync(logPath)).toBe(false);
+	});
+});

package/extensions/debug/__tests__/query-log.test.ts

@@ -0,0 +1,180 @@
+import { afterEach, beforeEach, describe, expect, it } from "bun:test";
+import { mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { DebugLogger, queryLog } from "../logger.js";
+
+let tmpDir: string;
+let logPath: string;
+
+const savedDebug = process.env.TALLOW_DEBUG;
+
+beforeEach(() => {
+	tmpDir = mkdtempSync(join(tmpdir(), "tallow-debug-query-test-"));
+	logPath = join(tmpDir, "debug.log");
+	delete process.env.TALLOW_DEBUG;
+});
+
+afterEach(() => {
+	if (savedDebug !== undefined) {
+		process.env.TALLOW_DEBUG = savedDebug;
+	} else {
+		delete process.env.TALLOW_DEBUG;
+	}
+	rmSync(tmpDir, { recursive: true, force: true });
+});
+
+/**
+ * Writes a pre-built log with diverse entries for query testing.
+ * @returns The logger (already closed) and its log path
+ */
+function seedLog(): string {
+	const logger = new DebugLogger("query-test", tmpDir);
+
+	logger.log("tool", "call", { name: "bash", toolCallId: "tc_1" });
+	logger.log("tool", "result", { name: "bash", toolCallId: "tc_1", durationMs: 120, ok: true });
+	logger.log("tool", "call", { name: "read", toolCallId: "tc_2" });
+	logger.log("tool", "result", { name: "read", toolCallId: "tc_2", durationMs: 5, ok: true });
+	logger.log("error", "uncaught_exception", {
+		message: "ENOENT: no such file",
+		stack: "at fs.readFile",
+	});
+	logger.log("turn", "start", { turnIndex: 0 });
+	logger.log("turn", "end", { turnIndex: 0, toolResultCount: 2 });
+	logger.log("subagent", "start", { agentId: "sub_1", agentType: "single", task: "review code" });
+	logger.log("subagent", "stop", { agentId: "sub_1", agentType: "single", exitCode: 0 });
+	logger.log("model", "select", { provider: "anthropic", modelId: "claude-sonnet-4" });
+
+	logger.close();
+	return logger.logPath;
+}
+
+// ── queryLog() ───────────────────────────────────────────────
+
+describe("queryLog()", () => {
+	it("returns empty array for nonexistent file", () => {
+		const result = queryLog("/tmp/does-not-exist-ever.log");
+		expect(result).toEqual([]);
+	});
+
+	it("returns all entries when no filters specified", () => {
+		const path = seedLog();
+		// seedLog writes 10 entries + 1 log_start header = 11
+		const result = queryLog(path);
+		expect(result.length).toBe(11);
+	});
+
+	it("returns entries newest-first", () => {
+		const path = seedLog();
+		const result = queryLog(path);
+		// First result should be the last entry written (model/select)
+		expect(result[0].cat).toBe("model");
+		expect(result[0].evt).toBe("select");
+		// Last result should be log_start header
+		expect(result[result.length - 1].cat).toBe("session");
+		expect(result[result.length - 1].evt).toBe("log_start");
+	});
+
+	it("filters by category", () => {
+		const path = seedLog();
+		const tools = queryLog(path, { category: "tool" });
+		expect(tools.length).toBe(4);
+		for (const entry of tools) {
+			expect(entry.cat).toBe("tool");
+		}
+	});
+
+	it("filters by event type", () => {
+		const path = seedLog();
+		const calls = queryLog(path, { eventType: "call" });
+		expect(calls.length).toBe(2);
+		for (const entry of calls) {
+			expect(entry.evt).toBe("call");
+		}
+	});
+
+	it("combines category and event type filters", () => {
+		const path = seedLog();
+		const toolCalls = queryLog(path, { category: "tool", eventType: "result" });
+		expect(toolCalls.length).toBe(2);
+		for (const entry of toolCalls) {
+			expect(entry.cat).toBe("tool");
+			expect(entry.evt).toBe("result");
+		}
+	});
+
+	it("applies limit", () => {
+		const path = seedLog();
+		const limited = queryLog(path, { limit: 3 });
+		expect(limited.length).toBe(3);
+		// Should be the 3 newest entries
+		expect(limited[0].cat).toBe("model");
+	});
+
+	it("filters by since timestamp", () => {
+		// Write entries with known timestamps by writing raw JSONL
+		const ts1 = "2026-01-01T00:00:00.000Z";
+		const ts2 = "2026-01-02T00:00:00.000Z";
+		const ts3 = "2026-01-03T00:00:00.000Z";
+
+		const lines = [
+			JSON.stringify({ ts: ts1, cat: "tool", evt: "call", data: { name: "old" } }),
+			JSON.stringify({ ts: ts2, cat: "tool", evt: "call", data: { name: "mid" } }),
+			JSON.stringify({ ts: ts3, cat: "tool", evt: "call", data: { name: "new" } }),
+		].join("\n");
+
+		writeFileSync(logPath, lines);
+
+		// Only entries after Jan 2
+		const result = queryLog(logPath, { since: "2026-01-02T00:00:00.000Z" });
+		expect(result.length).toBe(2);
+		expect(result[0].data.name).toBe("new");
+		expect(result[1].data.name).toBe("mid");
+	});
+
+	it("searches across data fields", () => {
+		const path = seedLog();
+		const result = queryLog(path, { search: "ENOENT" });
+		expect(result.length).toBe(1);
+		expect(result[0].cat).toBe("error");
+	});
+
+	it("searches event names", () => {
+		const path = seedLog();
+		const result = queryLog(path, { search: "uncaught" });
+		expect(result.length).toBe(1);
+		expect(result[0].evt).toBe("uncaught_exception");
+	});
+
+	it("search is case-insensitive", () => {
+		const path = seedLog();
+		const result = queryLog(path, { search: "enoent" });
+		expect(result.length).toBe(1);
+	});
+
+	it("skips malformed JSONL lines", () => {
+		writeFileSync(
+			logPath,
+			[
+				'{"ts":"2026-01-01T00:00:00Z","cat":"tool","evt":"call","data":{"name":"bash"}}',
+				"this is not json",
+				'{"ts":"2026-01-01T00:01:00Z","cat":"tool","evt":"result","data":{"name":"bash"}}',
+			].join("\n")
+		);
+
+		const result = queryLog(logPath);
+		expect(result.length).toBe(2);
+	});
+
+	it("combines all filters", () => {
+		const path = seedLog();
+		const result = queryLog(path, {
+			category: "tool",
+			eventType: "result",
+			search: "bash",
+			limit: 1,
+		});
+		expect(result.length).toBe(1);
+		expect(result[0].data.name).toBe("bash");
+	});
+});

package/extensions/debug/analysis.ts

@@ -0,0 +1,294 @@
+/**
+ * Log analysis utilities for the debug extension.
+ *
+ * Transforms raw JSONL log entries into human-readable summaries:
+ * tool timing histograms, error grouping, and turn efficiency metrics.
+ * All output is markdown-formatted for model consumption.
+ */
+
+import type { LogEntry } from "./logger.js";
+
+// ── Tool Timing Analysis ─────────────────────────────────────
+
+/** Aggregated timing statistics for a single tool. */
+interface ToolTimingStats {
+	name: string;
+	callCount: number;
+	totalMs: number;
+	minMs: number;
+	maxMs: number;
+	avgMs: number;
+	p50Ms: number;
+	p95Ms: number;
+}
+
+/**
+ * Computes a specific percentile from a sorted array of numbers.
+ *
+ * @param sorted - Pre-sorted numeric array (ascending)
+ * @param p - Percentile to compute (0–100)
+ * @returns The value at the given percentile
+ */
+function percentile(sorted: number[], p: number): number {
+	if (sorted.length === 0) return 0;
+	const idx = Math.ceil((p / 100) * sorted.length) - 1;
+	return sorted[Math.max(0, idx)];
+}
+
+/**
+ * Computes per-tool timing statistics from tool result log entries.
+ *
+ * Only considers entries with a valid `durationMs` field. Tools with
+ * no timing data are excluded from results.
+ *
+ * @param entries - Log entries (pre-filtered to category "tool" recommended)
+ * @returns Array of timing stats sorted by total time descending
+ */
+export function summarizeToolTimings(entries: LogEntry[]): ToolTimingStats[] {
+	const timingsByTool = new Map<string, number[]>();
+
+	for (const entry of entries) {
+		if (entry.cat !== "tool" || entry.evt !== "result") continue;
+		const { name, durationMs } = entry.data as { name?: string; durationMs?: number };
+		if (!name || durationMs == null) continue;
+
+		const existing = timingsByTool.get(name);
+		if (existing) {
+			existing.push(durationMs);
+		} else {
+			timingsByTool.set(name, [durationMs]);
+		}
+	}
+
+	const stats: ToolTimingStats[] = [];
+	for (const [name, durations] of timingsByTool) {
+		durations.sort((a, b) => a - b);
+		const totalMs = durations.reduce((sum, d) => sum + d, 0);
+
+		stats.push({
+			name,
+			callCount: durations.length,
+			totalMs,
+			minMs: durations[0],
+			maxMs: durations[durations.length - 1],
+			avgMs: Math.round(totalMs / durations.length),
+			p50Ms: percentile(durations, 50),
+			p95Ms: percentile(durations, 95),
+		});
+	}
+
+	// Sort by total time descending — slowest tools first
+	stats.sort((a, b) => b.totalMs - a.totalMs);
+	return stats;
+}
+
+/**
+ * Formats tool timing stats as a markdown table.
+ *
+ * @param stats - Tool timing statistics from summarizeToolTimings()
+ * @returns Markdown table string, or a "no data" message
+ */
+export function formatToolTimings(stats: ToolTimingStats[]): string {
+	if (stats.length === 0) return "No tool timing data found.";
+
+	const lines = [
+		"| Tool | Calls | Total (ms) | Avg (ms) | p50 (ms) | p95 (ms) | Max (ms) |",
+		"|------|-------|------------|----------|----------|----------|----------|",
+	];
+
+	for (const s of stats) {
+		lines.push(
+			`| ${s.name} | ${s.callCount} | ${s.totalMs} | ${s.avgMs} | ${s.p50Ms} | ${s.p95Ms} | ${s.maxMs} |`
+		);
+	}
+
+	return lines.join("\n");
+}
+
+// ── Error Grouping ───────────────────────────────────────────
+
+/** A group of similar errors deduplicated by message. */
+interface ErrorGroup {
+	message: string;
+	count: number;
+	firstSeen: string;
+	lastSeen: string;
+	eventTypes: string[];
+	/** First stack trace in the group (if available). */
+	stack?: string;
+}
+
+/**
+ * Groups error log entries by message similarity.
+ *
+ * Errors are deduplicated by their `message` field. Each group tracks
+ * occurrence count, time range, and the distinct event types that produced it.
+ *
+ * @param entries - Log entries (pre-filtered to category "error" recommended)
+ * @returns Array of error groups sorted by count descending
+ */
+export function groupErrors(entries: LogEntry[]): ErrorGroup[] {
+	const groups = new Map<string, ErrorGroup>();
+
+	for (const entry of entries) {
+		if (entry.cat !== "error") continue;
+		const { message, stack } = entry.data as { message?: string; stack?: string };
+		const msg = message ?? "Unknown error";
+
+		const existing = groups.get(msg);
+		if (existing) {
+			existing.count++;
+			existing.lastSeen = entry.ts;
+			if (!existing.eventTypes.includes(entry.evt)) {
+				existing.eventTypes.push(entry.evt);
+			}
+		} else {
+			groups.set(msg, {
+				message: msg,
+				count: 1,
+				firstSeen: entry.ts,
+				lastSeen: entry.ts,
+				eventTypes: [entry.evt],
+				stack: stack?.split("\n").slice(0, 5).join("\n"),
+			});
+		}
+	}
+
+	return [...groups.values()].sort((a, b) => b.count - a.count);
+}
+
+/**
+ * Formats error groups as a markdown summary.
+ *
+ * @param groups - Error groups from groupErrors()
+ * @returns Markdown string with error details
+ */
+export function formatErrors(groups: ErrorGroup[]): string {
+	if (groups.length === 0) return "No errors found in the log.";
+
+	const lines: string[] = [`**${groups.length} distinct error(s):**\n`];
+
+	for (const g of groups) {
+		lines.push(`- **${g.message}** (×${g.count})`);
+		lines.push(`  - Events: ${g.eventTypes.join(", ")}`);
+		lines.push(`  - First: ${g.firstSeen}, Last: ${g.lastSeen}`);
+		if (g.stack) {
+			lines.push(`  - Stack:\n    \`\`\`\n    ${g.stack}\n    \`\`\``);
+		}
+	}
+
+	return lines.join("\n");
+}
+
+// ── Turn Efficiency Metrics ──────────────────────────────────
+
+/** Session-level turn efficiency metrics. */
+interface TurnMetrics {
+	totalTurns: number;
+	totalToolCalls: number;
+	avgToolsPerTurn: number;
+	avgTurnDurationMs: number;
+	/** Turns with zero tool calls. */
+	emptyTurns: number;
+}
+
+/**
+ * Calculates turn efficiency metrics from log entries.
+ *
+ * Correlates turn_start/turn_end events with tool calls to compute
+ * per-turn tool usage and timing.
+ *
+ * @param entries - All log entries (unfiltered — needs both turn and tool events)
+ * @returns Aggregated turn metrics
+ */
+export function calculateTurnMetrics(entries: LogEntry[]): TurnMetrics {
+	// Entries arrive newest-first from queryLog; reverse to chronological
+	const chronological = [...entries].reverse();
+
+	let totalTurns = 0;
+	let totalToolCalls = 0;
+	let totalTurnDurationMs = 0;
+	let emptyTurns = 0;
+
+	let currentTurnStart: string | null = null;
+	let currentTurnToolCount = 0;
+
+	for (const entry of chronological) {
+		if (entry.cat === "turn" && entry.evt === "start") {
+			currentTurnStart = entry.ts;
+			currentTurnToolCount = 0;
+			totalTurns++;
+		} else if (entry.cat === "turn" && entry.evt === "end") {
+			if (currentTurnStart) {
+				const durationMs = new Date(entry.ts).getTime() - new Date(currentTurnStart).getTime();
+				totalTurnDurationMs += durationMs;
+			}
+			if (currentTurnToolCount === 0) emptyTurns++;
+			currentTurnStart = null;
+		} else if (entry.cat === "tool" && entry.evt === "call") {
+			totalToolCalls++;
+			currentTurnToolCount++;
+		}
+	}
+
+	return {
+		totalTurns,
+		totalToolCalls,
+		avgToolsPerTurn: totalTurns > 0 ? Math.round((totalToolCalls / totalTurns) * 10) / 10 : 0,
+		avgTurnDurationMs: totalTurns > 0 ? Math.round(totalTurnDurationMs / totalTurns) : 0,
+		emptyTurns,
+	};
+}
+
+/**
+ * Formats turn metrics as a markdown summary.
+ *
+ * @param metrics - Turn metrics from calculateTurnMetrics()
+ * @returns Markdown string with metrics
+ */
+export function formatTurnMetrics(metrics: TurnMetrics): string {
+	if (metrics.totalTurns === 0) return "No turn data found.";
+
+	return [
+		`**Turn Efficiency:**`,
+		`- Total turns: ${metrics.totalTurns}`,
+		`- Total tool calls: ${metrics.totalToolCalls}`,
+		`- Avg tools/turn: ${metrics.avgToolsPerTurn}`,
+		`- Avg turn duration: ${metrics.avgTurnDurationMs}ms`,
+		`- Empty turns (no tools): ${metrics.emptyTurns}`,
+	].join("\n");
+}
+
+// ── Generic Entry Formatter ──────────────────────────────────
+
+/**
+ * Formats raw log entries as a human-readable markdown list.
+ *
+ * Each entry is rendered as a single line with timestamp, category/event,
+ * and a compact representation of key data fields.
+ *
+ * @param entries - Log entries to format
+ * @returns Markdown-formatted string
+ */
+export function formatEntries(entries: LogEntry[]): string {
+	if (entries.length === 0) return "No matching log entries found.";
+
+	const lines: string[] = [`**${entries.length} log entries:**\n`];
+
+	for (const entry of entries) {
+		const data = entry.data;
+		// Pick interesting fields for compact display
+		const highlights: string[] = [];
+		if (data.name) highlights.push(`name=${data.name}`);
+		if (data.durationMs != null) highlights.push(`${data.durationMs}ms`);
+		if (data.ok !== undefined) highlights.push(data.ok ? "ok" : "FAILED");
+		if (data.message) highlights.push(`"${String(data.message).slice(0, 80)}"`);
+		if (data.agentId) highlights.push(`agent=${data.agentId}`);
+		if (data.exitCode !== undefined) highlights.push(`exit=${data.exitCode}`);
+
+		const detail = highlights.length > 0 ? ` — ${highlights.join(", ")}` : "";
+		lines.push(`- \`[${entry.ts}]\` **${entry.cat}/${entry.evt}**${detail}`);
+	}
+
+	return lines.join("\n");
+}

package/extensions/debug/extension.json

@@ -0,0 +1,21 @@
+{
+	"name": "debug",
+	"version": "0.1.0",
+	"description": "Structured diagnostic logging and interactive troubleshooting — tool timings, error analysis, turn metrics",
+	"category": "utility",
+	"tags": ["debug", "diagnostics", "logging", "troubleshooting"],
+	"files": ["index.ts", "logger.ts", "analysis.ts"],
+	"relationships": [
+		{
+			"name": "hooks",
+			"kind": "enhances",
+			"reason": "Logs hooks:merge events for diagnostic visibility"
+		},
+		{
+			"name": "subagent-tool",
+			"kind": "enhances",
+			"reason": "Logs subagent start/stop events"
+		}
+	],
+	"npmDependencies": {}
+}