claude-agent-ledger 0.4.1 → 0.7.1

package/package.json

@@ -1,15 +1,21 @@
 {
   "name": "claude-agent-ledger",
-  "version": "0.4.1",
+  "version": "0.7.1",
   "description": "See exactly where your Claude Code budget goes — per subagent, per task.",
   "type": "module",
   "bin": {
-    "agent-ledger": "./bin/agent-ledger.ts"
+    "agent-ledger": "bin/agent-ledger.ts"
   },
+  "files": [
+    "bin",
+    "src",
+    "LICENSE",
+    "README.md"
+  ],
   "scripts": {
     "dev": "bun run bin/agent-ledger.ts",
     "test": "bun test",
-    "build": "bun build bin/agent-ledger.ts --target=node --outdir dist",
+    "build": "bun build bin/agent-ledger.ts --target=bun --outdir dist",
     "typecheck": "tsc --noEmit"
   },
   "engines": {
@@ -27,10 +33,15 @@
   "license": "MIT",
   "repository": {
     "type": "git",
-    "url": "https://github.com/XJM-free/claude-agent-ledger.git"
+    "url": "git+https://github.com/XJM-free/claude-agent-ledger.git"
+  },
+  "homepage": "https://github.com/XJM-free/claude-agent-ledger#readme",
+  "bugs": {
+    "url": "https://github.com/XJM-free/claude-agent-ledger/issues"
   },
   "devDependencies": {
     "@types/bun": "latest",
+    "fast-check": "^4.7.0",
     "typescript": "^5.6.0"
   }
 }

package/src/aggregator.ts

@@ -1,26 +1,21 @@
 import { costFor } from './pricing.ts';
-import type { AggregatedRow, LedgerReport, SessionTurn } from './types.ts';
+import type { AggregatedRow, LedgerReport, SessionTurn, SubagentTreeNode } from './types.ts';
 
 const MAIN_AGENT_LABEL = '(main)';
 const UNKNOWN_MODEL_LABEL = '(no-model)';
 const UNKNOWN_PROJECT_LABEL = '(no-project)';
+const UNKNOWN_TOOL_LABEL = '(no-tool)';
 
-export type GroupKey = 'subagent' | 'model' | 'day' | 'project' | 'session';
+export type GroupKey = 'subagent' | 'model' | 'day' | 'project' | 'session' | 'tool';
 
 // Decode Claude Code's project directory name to something readable.
-// Encoding rule: absolute path with `/` replaced by `-` (leading `-` for root).
-//   "-Users-xiangjie-clawbot"             → "~/clawbot"
-//   "-Users-xiangjie-newlive-agent-ledger" → "~/newlive/agent-ledger"  (best-effort; ambiguous on dirs containing '-')
-// We special-case the "$HOME" prefix (`-Users-<user>-`) to render `~` and skip the rest of the
-// "-" → "/" conversion, since that's the only place we can be sure of segment boundaries.
+//   "-Users-xiangjie-clawbot" → "~/clawbot"
 export function decodeProjectId(encoded: string): string {
 	if (!encoded.startsWith('-')) return encoded;
-	const parts = encoded.slice(1).split('-'); // drop leading '-'
-	// Match common $HOME pattern: ['Users', '<user>', ...rest]
+	const parts = encoded.slice(1).split('-');
 	if (parts.length >= 3 && parts[0] === 'Users') {
 		return '~/' + parts.slice(2).join('-');
 	}
-	// Fallback: just convert all - to /
 	return '/' + parts.join('/');
 }
 
@@ -59,83 +54,190 @@ function splitCache(turn: SessionTurn): { fiveMin: number; oneHour: number } {
 	return { fiveMin: usage.cache_creation_input_tokens ?? 0, oneHour: 0 };
 }
 
-function keyOf(turn: SessionTurn, group: GroupKey): string {
-	if (group === 'model') return turn.model ?? UNKNOWN_MODEL_LABEL;
-	if (group === 'day') return turn.timestamp.slice(0, 10);
-	if (group === 'project') return decodeProjectId(turn.projectId ?? UNKNOWN_PROJECT_LABEL);
-	if (group === 'session') return turn.sessionId.slice(0, 8);
-	return turn.subagentType ?? MAIN_AGENT_LABEL;
+// Returns the keys this turn contributes to. Most groupings yield a single key,
+// but 'tool' yields one key per tool_use block (so a turn that reads + greps
+// counts toward both Read and Grep).
+function keysOf(turn: SessionTurn, group: GroupKey): string[] {
+	if (group === 'model') return [turn.model ?? UNKNOWN_MODEL_LABEL];
+	if (group === 'day') return [turn.timestamp.slice(0, 10)];
+	if (group === 'project') return [decodeProjectId(turn.projectId ?? UNKNOWN_PROJECT_LABEL)];
+	if (group === 'session') return [turn.sessionId.slice(0, 8)];
+	if (group === 'tool') {
+		// Attribute the assistant turn's cost equally across every tool it invoked.
+		// If the turn invoked no tools, attribute to (no-tool).
+		return turn.toolUses && turn.toolUses.length > 0 ? turn.toolUses : [UNKNOWN_TOOL_LABEL];
+	}
+	return [turn.subagentType ?? MAIN_AGENT_LABEL];
 }
 
 function sortKey(group: GroupKey): (a: AggregatedRow, b: AggregatedRow) => number {
-	// For day groupings users want chronological; otherwise descend by cost.
 	if (group === 'day') return (a, b) => (a.subagent < b.subagent ? -1 : a.subagent > b.subagent ? 1 : 0);
 	return (a, b) => b.cost.totalCost - a.cost.totalCost;
 }
 
+// Streaming aggregator. add() per turn, finalize() at end.
+// Suitable for fan-out: one parser stream → N aggregators in parallel.
+export class Aggregator {
+	private rowsByKey = new Map<string, AggregatedRow>();
+	private sessionsByKey = new Map<string, Set<string>>();
+
+	constructor(
+		private readonly group: GroupKey,
+		private readonly from: Date,
+		private readonly to: Date,
+	) {}
+
+	add(turn: SessionTurn): void {
+		if (turn.type !== 'assistant' || !turn.usage) return;
+
+		const cost = costFor(turn.usage, turn.model);
+		const { fiveMin, oneHour } = splitCache(turn);
+		const usage = turn.usage;
+		const keys = keysOf(turn, this.group);
+		// Distribute the turn's contributions evenly across all keys (relevant only for 'tool').
+		const share = 1 / keys.length;
+
+		for (const key of keys) {
+			let row = this.rowsByKey.get(key);
+			if (!row) {
+				row = emptyRow(key);
+				this.rowsByKey.set(key, row);
+			}
+			row.inputTokens += usage.input_tokens * share;
+			row.outputTokens += usage.output_tokens * share;
+			row.cacheCreation5mTokens += fiveMin * share;
+			row.cacheCreation1hTokens += oneHour * share;
+			row.cacheReadTokens += (usage.cache_read_input_tokens ?? 0) * share;
+			row.webSearchRequests += (usage.server_tool_use?.web_search_requests ?? 0) * share;
+			row.webFetchRequests += (usage.server_tool_use?.web_fetch_requests ?? 0) * share;
+			row.cost.inputCost += cost.inputCost * share;
+			row.cost.outputCost += cost.outputCost * share;
+			row.cost.cacheCreation5mCost += cost.cacheCreation5mCost * share;
+			row.cost.cacheCreation1hCost += cost.cacheCreation1hCost * share;
+			row.cost.cacheReadCost += cost.cacheReadCost * share;
+			row.cost.serverToolUseCost += cost.serverToolUseCost * share;
+			row.cost.totalCost += cost.totalCost * share;
+
+			let sessions = this.sessionsByKey.get(key);
+			if (!sessions) {
+				sessions = new Set<string>();
+				this.sessionsByKey.set(key, sessions);
+			}
+			sessions.add(turn.sessionId);
+		}
+	}
+
+	finalize(): LedgerReport {
+		for (const [key, row] of this.rowsByKey) {
+			row.sessionCount = this.sessionsByKey.get(key)?.size ?? 0;
+		}
+		const rows = [...this.rowsByKey.values()].sort(sortKey(this.group));
+		const total = rows.reduce<AggregatedRow>((acc, row) => {
+			acc.sessionCount += row.sessionCount;
+			acc.inputTokens += row.inputTokens;
+			acc.outputTokens += row.outputTokens;
+			acc.cacheCreation5mTokens += row.cacheCreation5mTokens;
+			acc.cacheCreation1hTokens += row.cacheCreation1hTokens;
+			acc.cacheReadTokens += row.cacheReadTokens;
+			acc.webSearchRequests += row.webSearchRequests;
+			acc.webFetchRequests += row.webFetchRequests;
+			acc.cost.inputCost += row.cost.inputCost;
+			acc.cost.outputCost += row.cost.outputCost;
+			acc.cost.cacheCreation5mCost += row.cost.cacheCreation5mCost;
+			acc.cost.cacheCreation1hCost += row.cost.cacheCreation1hCost;
+			acc.cost.cacheReadCost += row.cost.cacheReadCost;
+			acc.cost.serverToolUseCost += row.cost.serverToolUseCost;
+			acc.cost.totalCost += row.cost.totalCost;
+			return acc;
+		}, emptyRow('total'));
+		return { period: { from: this.from, to: this.to }, rows, total };
+	}
+}
+
+// Backwards-compat: the old async function-based API.
 export async function aggregate(
 	turns: AsyncIterable<SessionTurn>,
 	from: Date,
 	to: Date,
 	group: GroupKey = 'subagent',
 ): Promise<LedgerReport> {
-	const rowsByKey = new Map<string, AggregatedRow>();
-	const sessionsByKey = new Map<string, Set<string>>();
-
-	for await (const turn of turns) {
-		if (turn.type !== 'assistant' || !turn.usage) continue;
-
-		const key = keyOf(turn, group);
-		const row = rowsByKey.get(key) ?? emptyRow(key);
+	const agg = new Aggregator(group, from, to);
+	for await (const turn of turns) agg.add(turn);
+	return agg.finalize();
+}
 
-		const cost = costFor(turn.usage, turn.model);
-		const { fiveMin, oneHour } = splitCache(turn);
+// MOAT feature: subagent-graph cost attribution.
+// Walks every parent session and recursively sums children to produce a tree
+// rooted at the orchestrator. Helicone/Langfuse cannot do this — they observe
+// API calls, not Claude Code's orchestration tree.
+interface SessionAccum {
+	sessionId: string;
+	label: string;
+	selfCost: number;
+	turnCount: number;
+	parentSessionId?: string | undefined;
+}
 
-		row.inputTokens += turn.usage.input_tokens;
-		row.outputTokens += turn.usage.output_tokens;
-		row.cacheCreation5mTokens += fiveMin;
-		row.cacheCreation1hTokens += oneHour;
-		row.cacheReadTokens += turn.usage.cache_read_input_tokens ?? 0;
-		row.webSearchRequests += turn.usage.server_tool_use?.web_search_requests ?? 0;
-		row.webFetchRequests += turn.usage.server_tool_use?.web_fetch_requests ?? 0;
-		row.cost.inputCost += cost.inputCost;
-		row.cost.outputCost += cost.outputCost;
-		row.cost.cacheCreation5mCost += cost.cacheCreation5mCost;
-		row.cost.cacheCreation1hCost += cost.cacheCreation1hCost;
-		row.cost.cacheReadCost += cost.cacheReadCost;
-		row.cost.serverToolUseCost += cost.serverToolUseCost;
-		row.cost.totalCost += cost.totalCost;
-
-		const sessions = sessionsByKey.get(key) ?? new Set<string>();
-		sessions.add(turn.sessionId);
-		sessionsByKey.set(key, sessions);
-
-		rowsByKey.set(key, row);
+export class SubagentGraph {
+	private accums = new Map<string, SessionAccum>();
+
+	add(turn: SessionTurn): void {
+		if (turn.type !== 'assistant' || !turn.usage) return;
+		const cost = costFor(turn.usage, turn.model).totalCost;
+		let acc = this.accums.get(turn.sessionId);
+		if (!acc) {
+			acc = {
+				sessionId: turn.sessionId,
+				label: turn.subagentType ?? '(orchestrator)',
+				selfCost: 0,
+				turnCount: 0,
+				parentSessionId: turn.parentSessionId,
+			};
+			this.accums.set(turn.sessionId, acc);
+		}
+		acc.selfCost += cost;
+		acc.turnCount += 1;
+		// Children's parentSessionId may not appear until after the parent;
+		// keep the earliest non-undefined seen.
+		if (turn.parentSessionId && !acc.parentSessionId) {
+			acc.parentSessionId = turn.parentSessionId;
+		}
 	}
 
-	for (const [key, row] of rowsByKey) {
-		row.sessionCount = sessionsByKey.get(key)?.size ?? 0;
+	// Build the trees. Each root has parentSessionId === undefined.
+	// Returns roots sorted by total cost (descending), top N only by default.
+	finalize(topN = 20): SubagentTreeNode[] {
+		const childrenOf = new Map<string, string[]>();
+		for (const acc of this.accums.values()) {
+			if (acc.parentSessionId) {
+				const list = childrenOf.get(acc.parentSessionId) ?? [];
+				list.push(acc.sessionId);
+				childrenOf.set(acc.parentSessionId, list);
+			}
+		}
+		const buildNode = (sessionId: string): SubagentTreeNode => {
+			const acc = this.accums.get(sessionId);
+			if (!acc) {
+				return { sessionId, label: '(missing)', selfCost: 0, totalCost: 0, children: [], turnCount: 0 };
+			}
+			const childIds = childrenOf.get(sessionId) ?? [];
+			const children = childIds.map((id) => buildNode(id));
+			children.sort((a, b) => b.totalCost - a.totalCost);
+			const childTotal = children.reduce((s, c) => s + c.totalCost, 0);
+			return {
+				sessionId,
+				label: acc.label,
+				selfCost: acc.selfCost,
+				totalCost: acc.selfCost + childTotal,
+				children,
+				turnCount: acc.turnCount,
+			};
+		};
+		const roots = [...this.accums.values()]
+			.filter((a) => !a.parentSessionId)
+			.map((a) => buildNode(a.sessionId))
+			.sort((a, b) => b.totalCost - a.totalCost)
+			.slice(0, topN);
+		return roots;
 	}
-
-	const rows = [...rowsByKey.values()].sort(sortKey(group));
-	const total = rows.reduce<AggregatedRow>((acc, row) => {
-		acc.sessionCount += row.sessionCount;
-		acc.inputTokens += row.inputTokens;
-		acc.outputTokens += row.outputTokens;
-		acc.cacheCreation5mTokens += row.cacheCreation5mTokens;
-		acc.cacheCreation1hTokens += row.cacheCreation1hTokens;
-		acc.cacheReadTokens += row.cacheReadTokens;
-		acc.webSearchRequests += row.webSearchRequests;
-		acc.webFetchRequests += row.webFetchRequests;
-		acc.cost.inputCost += row.cost.inputCost;
-		acc.cost.outputCost += row.cost.outputCost;
-		acc.cost.cacheCreation5mCost += row.cost.cacheCreation5mCost;
-		acc.cost.cacheCreation1hCost += row.cost.cacheCreation1hCost;
-		acc.cost.cacheReadCost += row.cost.cacheReadCost;
-		acc.cost.serverToolUseCost += row.cost.serverToolUseCost;
-		acc.cost.totalCost += row.cost.totalCost;
-		return acc;
-	}, emptyRow('total'));
-
-	return { period: { from, to }, rows, total };
 }

package/src/explain.ts

@@ -0,0 +1,209 @@
+// `agent-ledger explain <sessionId>` — root-cause why a session was expensive.
+//
+// Two-mode design:
+// 1. Heuristic mode (always works, no API key): top-3 most expensive turns +
+//    tool-call breakdown + cache-reuse stats.
+// 2. LLM mode (set ANTHROPIC_API_KEY): pipes the same evidence into
+//    Haiku 4.5 for a 4-bullet verdict ("prompt bloat", "Opus mis-selection",
+//    "no cache reuse", "tool output overflow"). Typically costs <$0.005/run.
+
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import { Glob } from 'bun';
+import { parseFile } from './parser.ts';
+import { costFor } from './pricing.ts';
+import type { SessionTurn } from './types.ts';
+
+interface TurnAnalysis {
+	turnIndex: number;
+	timestamp: string;
+	model: string | undefined;
+	cost: number;
+	inputTokens: number;
+	outputTokens: number;
+	cacheCreate5m: number;
+	cacheCreate1h: number;
+	cacheRead: number;
+	tools: string[];
+}
+
+interface SessionAnalysis {
+	sessionId: string;
+	subagentType: string | undefined;
+	totalCost: number;
+	turnCount: number;
+	models: Map<string, number>; // model → cost
+	tools: Map<string, number>; // tool → invocation count
+	cacheReuseRatio: number; // reads / writes
+	topTurns: TurnAnalysis[];
+}
+
+const CLAUDE_PROJECTS_DIR = join(homedir(), '.claude', 'projects');
+
+async function findSessionFile(sessionPrefix: string): Promise<string | undefined> {
+	// Sessions are named `<uuid>.jsonl`. Match either full id or 8-char prefix.
+	const pattern = new Glob(`**/${sessionPrefix}*.jsonl`);
+	for await (const path of pattern.scan({ cwd: CLAUDE_PROJECTS_DIR, absolute: true })) {
+		return path;
+	}
+	return undefined;
+}
+
+export async function analyzeSession(sessionPrefix: string): Promise<SessionAnalysis | undefined> {
+	const path = await findSessionFile(sessionPrefix);
+	if (!path) return undefined;
+	const turns: SessionTurn[] = [];
+	for await (const t of parseFile(path)) turns.push(t);
+	return analyze(turns, sessionPrefix);
+}
+
+function analyze(turns: SessionTurn[], sessionPrefix: string): SessionAnalysis {
+	const analyses: TurnAnalysis[] = [];
+	const models = new Map<string, number>();
+	const tools = new Map<string, number>();
+	let totalCost = 0;
+	let totalCacheRead = 0;
+	let totalCacheWrite = 0;
+	let subagentType: string | undefined;
+
+	turns.forEach((turn, i) => {
+		if (turn.subagentType && !subagentType) subagentType = turn.subagentType;
+		if (turn.type !== 'assistant' || !turn.usage) return;
+		const c = costFor(turn.usage, turn.model).totalCost;
+		totalCost += c;
+		const m = turn.model ?? '(no-model)';
+		models.set(m, (models.get(m) ?? 0) + c);
+		for (const t of turn.toolUses ?? []) {
+			tools.set(t, (tools.get(t) ?? 0) + 1);
+		}
+		const fiveMin = turn.usage.cache_creation?.ephemeral_5m_input_tokens ?? turn.usage.cache_creation_input_tokens ?? 0;
+		const oneH = turn.usage.cache_creation?.ephemeral_1h_input_tokens ?? 0;
+		totalCacheRead += turn.usage.cache_read_input_tokens ?? 0;
+		totalCacheWrite += fiveMin + oneH;
+		analyses.push({
+			turnIndex: i,
+			timestamp: turn.timestamp,
+			model: turn.model,
+			cost: c,
+			inputTokens: turn.usage.input_tokens,
+			outputTokens: turn.usage.output_tokens,
+			cacheCreate5m: fiveMin,
+			cacheCreate1h: oneH,
+			cacheRead: turn.usage.cache_read_input_tokens ?? 0,
+			tools: turn.toolUses ?? [],
+		});
+	});
+
+	analyses.sort((a, b) => b.cost - a.cost);
+	const cacheReuseRatio = totalCacheWrite > 0 ? totalCacheRead / totalCacheWrite : 0;
+
+	return {
+		sessionId: sessionPrefix,
+		subagentType,
+		totalCost,
+		turnCount: analyses.length,
+		models,
+		tools,
+		cacheReuseRatio,
+		topTurns: analyses.slice(0, 3),
+	};
+}
+
+const fmtUsd = (n: number): string => '$' + n.toFixed(n < 0.01 ? 4 : 2);
+const fmtToken = (n: number): string => {
+	if (n >= 1e6) return (n / 1e6).toFixed(2) + 'M';
+	if (n >= 1e3) return (n / 1e3).toFixed(1) + 'K';
+	return String(Math.round(n));
+};
+
+export function formatHeuristic(s: SessionAnalysis): string {
+	const lines: string[] = [];
+	lines.push(`# Session ${s.sessionId} — heuristic root-cause`);
+	lines.push('');
+	lines.push(`- Subagent: \`${s.subagentType ?? '(orchestrator)'}\``);
+	lines.push(`- Total cost: **${fmtUsd(s.totalCost)}** across ${s.turnCount} assistant turns`);
+	lines.push(`- Models used:`);
+	[...s.models.entries()]
+		.sort((a, b) => b[1] - a[1])
+		.forEach(([m, c]) => lines.push(`    - \`${m}\` — ${fmtUsd(c)}`));
+	lines.push('');
+	lines.push(`## Top tools by invocation count`);
+	const topTools = [...s.tools.entries()].sort((a, b) => b[1] - a[1]).slice(0, 8);
+	if (topTools.length === 0) {
+		lines.push('  _(no tool_use blocks found in this session)_');
+	} else {
+		for (const [t, n] of topTools) lines.push(`  - \`${t}\` × ${n}`);
+	}
+	lines.push('');
+	lines.push(`## Top 3 most expensive turns`);
+	for (const t of s.topTurns) {
+		lines.push(
+			`- **Turn ${t.turnIndex}** at ${t.timestamp} — ${fmtUsd(t.cost)}\n  - model: \`${t.model ?? '(no-model)'}\`\n  - input: ${fmtToken(t.inputTokens)}, output: ${fmtToken(t.outputTokens)}, cache 5m: ${fmtToken(t.cacheCreate5m)}, cache 1h: ${fmtToken(t.cacheCreate1h)}, cache read: ${fmtToken(t.cacheRead)}\n  - tools: ${t.tools.join(', ') || '(none)'}`,
+		);
+	}
+	lines.push('');
+	lines.push(
+		`## Cache reuse — ${s.cacheReuseRatio.toFixed(1)}× (reads/writes)`,
+	);
+	if (s.cacheReuseRatio < 5) {
+		lines.push(
+			`  ⚠️  **Below 5×.** This session creates cache faster than it reuses. Consider: shorter system prompt, fewer dynamic context injections per turn.`,
+		);
+	} else if (s.cacheReuseRatio < 20) {
+		lines.push(`  ✅ Acceptable but could be higher. Aim for >20× on long sessions.`);
+	} else {
+		lines.push(`  ✅ Good — cache is doing its job.`);
+	}
+
+	return lines.join('\n');
+}
+
+interface AnthropicMsgRes {
+	content: Array<{ type: string; text?: string }>;
+	usage?: { input_tokens: number; output_tokens: number };
+}
+
+export async function llmExplain(s: SessionAnalysis): Promise<string | undefined> {
+	const apiKey = process.env.ANTHROPIC_API_KEY;
+	if (!apiKey) return undefined;
+	// The session identifier is useful locally but adds no analytical value to
+	// the API request, so keep it off the network.
+	const evidence = formatHeuristic({ ...s, sessionId: '[redacted]' });
+	const prompt = `You are a Claude Code cost-optimization expert. A user's session burned ${fmtUsd(s.totalCost)} across ${s.turnCount} turns. Below is the per-turn breakdown:
+
+${evidence}
+
+In ≤4 bullets, identify the SPECIFIC root cause (not generic advice) and ONE concrete action the user can take to cut this session's cost by 50%+. Be terse. Cite turn numbers from the breakdown.`;
+	try {
+		const res = await fetch('https://api.anthropic.com/v1/messages', {
+			method: 'POST',
+			headers: {
+				'Content-Type': 'application/json',
+				'x-api-key': apiKey,
+				'anthropic-version': '2023-06-01',
+			},
+			body: JSON.stringify({
+				model: 'claude-haiku-4-5-20251001',
+				max_tokens: 600,
+				messages: [{ role: 'user', content: prompt }],
+			}),
+		});
+		if (!res.ok) {
+			console.error(`agent-ledger explain: API ${res.status} — falling back to heuristic`);
+			return undefined;
+		}
+		const data = (await res.json()) as AnthropicMsgRes;
+		const text = data.content.find((b) => b.type === 'text')?.text;
+		if (!text) return undefined;
+		const cost = data.usage
+			? costFor(
+					{ input_tokens: data.usage.input_tokens, output_tokens: data.usage.output_tokens },
+					'claude-haiku-4-5-20251001',
+				).totalCost
+			: 0;
+		return `## LLM root-cause analysis (Haiku 4.5, ${fmtUsd(cost)})\n\n${text.trim()}`;
+	} catch (err) {
+		console.error('agent-ledger explain: LLM call failed —', err);
+		return undefined;
+	}
+}