claude-agent-ledger 0.4.0 → 0.7.0

package/src/parser.ts

@@ -5,6 +5,9 @@ import type { SessionTurn, TokenUsage } from './types.ts';
 
 const CLAUDE_PROJECTS_DIR = join(homedir(), '.claude', 'projects');
 
+// Limit concurrent file reads so we don't exhaust fd on huge setups.
+const CONCURRENCY = 8;
+
 export interface ParseOptions {
 	from?: Date;
 	to?: Date;
@@ -15,16 +18,9 @@ interface LogFile {
 	path: string;
 	projectId: string;
 	subagentType: string | undefined;
+	parentSessionId?: string | undefined; // for subagent logs, the parent session
 }
 
-// Walk the projects directory and yield every JSONL log.
-// Real Claude Code layout (as of 2026-04):
-//   ~/.claude/projects/<encoded-project>/<session-uuid>.jsonl             (main session)
-//   ~/.claude/projects/<encoded-project>/<session-uuid>/subagents/agent-<hash>.jsonl  (subagent)
-//   ~/.claude/projects/<encoded-project>/<session-uuid>/subagents/agent-<hash>.meta.json
-//
-// The .meta.json next to each subagent .jsonl carries { "agentType": "...", "description": "..." }.
-// We read it to attribute the subagent by its real name (e.g. "Reality Checker") rather than an opaque hash.
 export async function* findSessionLogs(
 	projectsDir: string = CLAUDE_PROJECTS_DIR,
 ): AsyncGenerator<LogFile> {
@@ -34,11 +30,22 @@ export async function* findSessionLogs(
 	} catch {
 		return;
 	}
-	for (const project of projects) {
-		yield* walkForJsonl(join(projectsDir, project), project);
+	// Parallelize the project-level walks; collect LogFiles via streaming queue.
+	const walkers = projects.map((project) =>
+		collectWalk(join(projectsDir, project), project),
+	);
+	const settled = await Promise.all(walkers);
+	for (const list of settled) {
+		for (const lf of list) yield lf;
 	}
 }
 
+async function collectWalk(dir: string, projectId: string): Promise<LogFile[]> {
+	const out: LogFile[] = [];
+	for await (const lf of walkForJsonl(dir, projectId)) out.push(lf);
+	return out;
+}
+
 async function* walkForJsonl(dir: string, projectId: string): AsyncGenerator<LogFile> {
 	let entries: string[] = [];
 	try {
@@ -46,6 +53,9 @@ async function* walkForJsonl(dir: string, projectId: string): AsyncGenerator<Log
 	} catch {
 		return;
 	}
+	// If this directory IS named 'subagents', its parent session is one level up.
+	// e.g. .../<session-uuid>/subagents/agent-XXX.jsonl → parent = <session-uuid>
+	const parentSession = basename(dir) === 'subagents' ? basename(dirname(dir)) : undefined;
 	for (const name of entries) {
 		if (name.startsWith('.') || name === 'memory') continue;
 		const full = join(dir, name);
@@ -60,13 +70,18 @@ async function* walkForJsonl(dir: string, projectId: string): AsyncGenerator<Log
 			continue;
 		}
 		if (name.endsWith('.jsonl')) {
-			yield { path: full, projectId, subagentType: await resolveSubagentType(full) };
+			const subagentType = await resolveSubagentType(full);
+			yield {
+				path: full,
+				projectId,
+				subagentType,
+				parentSessionId: parentSession,
+			};
 		}
 	}
 }
 
 async function resolveSubagentType(jsonlPath: string): Promise<string | undefined> {
-	// Subagent logs live under `.../subagents/agent-<hash>.jsonl` with a sibling `.meta.json`.
 	if (basename(dirname(jsonlPath)) !== 'subagents') return undefined;
 	const metaPath = jsonlPath.replace(/\.jsonl$/, '.meta.json');
 	try {
@@ -78,26 +93,51 @@ async function resolveSubagentType(jsonlPath: string): Promise<string | undefine
 	}
 }
 
-// Stream-parse one JSONL file. Skips malformed lines rather than aborting.
+// Streaming line reader — does NOT buffer the whole file.
+// Handles partial lines across chunk boundaries. Skips malformed JSON.
 export async function* parseFile(
 	path: string,
 	subagentType?: string,
 	projectId?: string,
+	parentSessionId?: string,
 ): AsyncGenerator<SessionTurn> {
-	const file = Bun.file(path);
-	const text = await file.text();
 	const sessionId = basename(path).replace('.jsonl', '');
-
-	for (const line of text.split('\n')) {
-		if (!line.trim()) continue;
-		let obj: Record<string, unknown>;
-		try {
-			obj = JSON.parse(line);
-		} catch {
-			continue;
+	const stream = Bun.file(path).stream();
+	const decoder = new TextDecoder('utf-8', { fatal: false });
+	let buffer = '';
+	for await (const chunk of stream) {
+		buffer += decoder.decode(chunk, { stream: true });
+		let nl: number;
+		while ((nl = buffer.indexOf('\n')) !== -1) {
+			const line = buffer.slice(0, nl);
+			buffer = buffer.slice(nl + 1);
+			if (!line.trim()) continue;
+			const turn = tryParseLine(line, sessionId, subagentType, projectId, parentSessionId);
+			if (turn) yield turn;
 		}
-		yield extractTurn(obj, sessionId, subagentType, projectId);
 	}
+	// Flush any trailing partial line.
+	buffer += decoder.decode();
+	if (buffer.trim()) {
+		const turn = tryParseLine(buffer, sessionId, subagentType, projectId, parentSessionId);
+		if (turn) yield turn;
+	}
+}
+
+function tryParseLine(
+	line: string,
+	sessionId: string,
+	subagentType: string | undefined,
+	projectId: string | undefined,
+	parentSessionId: string | undefined,
+): SessionTurn | undefined {
+	let obj: Record<string, unknown>;
+	try {
+		obj = JSON.parse(line);
+	} catch {
+		return undefined;
+	}
+	return extractTurn(obj, sessionId, subagentType, projectId, parentSessionId);
 }
 
 function extractTurn(
@@ -105,14 +145,29 @@ function extractTurn(
 	sessionId: string,
 	subagentType: string | undefined,
 	projectId: string | undefined,
+	parentSessionId: string | undefined,
 ): SessionTurn {
 	const msg = (obj.message ?? {}) as Record<string, unknown>;
 	const usage = (msg.usage ?? undefined) as TokenUsage | undefined;
 	const model = (msg.model ?? undefined) as string | undefined;
-	// If the raw turn carries its own subagentType (our fixture format), prefer it;
-	// otherwise fall back to the directory-derived one.
 	const perTurnSubagent = ((obj.subagentType as string) ?? undefined) || undefined;
 	const perTurnProject = ((obj.projectId as string) ?? undefined) || undefined;
+	const perTurnParent = ((obj.parentSessionId as string) ?? undefined) || undefined;
+
+	// Extract tool_use blocks from the assistant message content (if any).
+	// Used by the --by tool aggregator and subagent-graph attribution.
+	const toolUses: string[] = [];
+	const content = msg.content;
+	if (Array.isArray(content)) {
+		for (const block of content) {
+			if (block && typeof block === 'object') {
+				const b = block as Record<string, unknown>;
+				if (b.type === 'tool_use' && typeof b.name === 'string') {
+					toolUses.push(b.name);
+				}
+			}
+		}
+	}
 
 	return {
 		type: ((obj.type as string) ?? 'assistant') as SessionTurn['type'],
@@ -120,20 +175,43 @@ function extractTurn(
 		sessionId,
 		projectId: perTurnProject ?? projectId,
 		subagentType: perTurnSubagent ?? subagentType,
+		parentSessionId: perTurnParent ?? parentSessionId,
 		model,
 		usage,
+		toolUses: toolUses.length > 0 ? toolUses : undefined,
 		raw: obj,
 	};
 }
 
-// Convenience: stream every turn across every log under ~/.claude/projects.
+// Parallelized, streaming. Does not materialize all turns — caller iterates
+// once and dispatches to aggregators. Reads up to CONCURRENCY files at a time.
 export async function* parseAll(opts: ParseOptions = {}): AsyncGenerator<SessionTurn> {
 	const dir = opts.projectsDir ?? CLAUDE_PROJECTS_DIR;
-	for await (const file of findSessionLogs(dir)) {
-		for await (const turn of parseFile(file.path, file.subagentType, file.projectId)) {
-			if (opts.from && new Date(turn.timestamp) < opts.from) continue;
-			if (opts.to && new Date(turn.timestamp) > opts.to) continue;
-			yield turn;
+	const files: LogFile[] = [];
+	for await (const f of findSessionLogs(dir)) files.push(f);
+
+	// Fan out file reads in batches of CONCURRENCY, yield turns in arrival order.
+	for (let i = 0; i < files.length; i += CONCURRENCY) {
+		const batch = files.slice(i, i + CONCURRENCY);
+		const streams = batch.map((f) =>
+			collectBatch(parseFile(f.path, f.subagentType, f.projectId, f.parentSessionId), opts),
+		);
+		const results = await Promise.all(streams);
+		for (const turns of results) {
+			for (const t of turns) yield t;
 		}
 	}
 }
+
+async function collectBatch(
+	gen: AsyncGenerator<SessionTurn>,
+	opts: ParseOptions,
+): Promise<SessionTurn[]> {
+	const out: SessionTurn[] = [];
+	for await (const t of gen) {
+		if (opts.from && new Date(t.timestamp) < opts.from) continue;
+		if (opts.to && new Date(t.timestamp) > opts.to) continue;
+		out.push(t);
+	}
+	return out;
+}

package/src/tree.ts

@@ -0,0 +1,107 @@
+// ASCII tree renderer for subagent graph (the MOAT feature).
+// Helicone/Langfuse observe API calls; only Claude Code knows that
+// orchestrator → 3×researcher + 6×swift-dev. We render that tree.
+
+import type { SubagentTreeNode } from './types.ts';
+
+const fmtUsd = (n: number): string => {
+	if (n < 0.01) return '$' + n.toFixed(4);
+	return '$' + n.toFixed(2);
+};
+
+const dim = (s: string): string =>
+	process.env.NO_COLOR || !process.stdout.isTTY ? s : `\x1b[2m${s}\x1b[0m`;
+
+const bold = (s: string): string =>
+	process.env.NO_COLOR || !process.stdout.isTTY ? s : `\x1b[1m${s}\x1b[0m`;
+
+const amber = (s: string): string =>
+	process.env.NO_COLOR || !process.stdout.isTTY ? s : `\x1b[38;5;215m${s}\x1b[0m`;
+
+export function formatTree(roots: SubagentTreeNode[], totalCost: number): string {
+	if (roots.length === 0) return dim('No subagent graphs found in this period.');
+
+	const lines: string[] = [];
+	lines.push(
+		bold('Subagent graphs') +
+			dim('  · top ') +
+			roots.length +
+			dim(' orchestrators by total cost · grand-total ') +
+			amber(fmtUsd(totalCost)),
+	);
+	lines.push('');
+	for (const root of roots) {
+		renderNode(root, '', true, lines, totalCost, true);
+		lines.push('');
+	}
+	return lines.join('\n');
+}
+
+function renderNode(
+	node: SubagentTreeNode,
+	prefix: string,
+	isLast: boolean,
+	lines: string[],
+	grandTotal: number,
+	isRoot: boolean,
+): void {
+	const connector = isRoot ? '' : isLast ? '└─ ' : '├─ ';
+	const sessionShort = dim(node.sessionId.slice(0, 8));
+	const pct = grandTotal > 0 ? ((node.totalCost / grandTotal) * 100).toFixed(1) + '%' : '—';
+	const turns = dim(`${node.turnCount} turns`);
+
+	if (isRoot) {
+		const childCount = countDescendants(node);
+		const childInfo = childCount > 0 ? dim(` (${childCount} children)`) : '';
+		lines.push(
+			`${bold(node.label)} ${sessionShort}${childInfo}  ${amber(fmtUsd(node.totalCost))}  ${dim(`(${pct})`)}`,
+		);
+	} else {
+		const selfNote =
+			node.children.length > 0
+				? dim(`  self ${fmtUsd(node.selfCost)}`)
+				: '';
+		lines.push(
+			`${dim(prefix)}${connector}${node.label} ${sessionShort}  ${amber(fmtUsd(node.totalCost))}${selfNote}  ${turns}`,
+		);
+	}
+
+	const childPrefix = prefix + (isRoot ? '' : isLast ? '   ' : '│  ');
+	node.children.forEach((child, idx) => {
+		const last = idx === node.children.length - 1;
+		renderNode(child, childPrefix, last, lines, grandTotal, false);
+	});
+}
+
+function countDescendants(node: SubagentTreeNode): number {
+	let n = node.children.length;
+	for (const c of node.children) n += countDescendants(c);
+	return n;
+}
+
+// Markdown variant — same data, GH-friendly nested list.
+export function formatTreeMarkdown(roots: SubagentTreeNode[], totalCost: number): string {
+	const lines: string[] = ['# Subagent graphs', ''];
+	lines.push(`Top ${roots.length} orchestrators by total cost. Grand total: **${fmtUsd(totalCost)}**.`);
+	lines.push('');
+	for (const root of roots) {
+		const childCount = countDescendants(root);
+		lines.push(
+			`## ${root.label} \`${root.sessionId.slice(0, 8)}\` — ${fmtUsd(root.totalCost)} (${childCount} children, ${root.turnCount} turns)`,
+		);
+		mdNode(root, lines, 0);
+		lines.push('');
+	}
+	return lines.join('\n');
+}
+
+function mdNode(node: SubagentTreeNode, lines: string[], depth: number): void {
+	for (const child of node.children) {
+		const indent = '  '.repeat(depth);
+		const self = child.children.length > 0 ? ` _self ${fmtUsd(child.selfCost)}_` : '';
+		lines.push(
+			`${indent}- **${child.label}** \`${child.sessionId.slice(0, 8)}\` — ${fmtUsd(child.totalCost)} (${child.turnCount} turns)${self}`,
+		);
+		mdNode(child, lines, depth + 1);
+	}
+}

package/src/types.ts

@@ -1,8 +1,15 @@
-export type ModelId =
-	| 'claude-opus-4-7'
-	| 'claude-sonnet-4-6'
-	| 'claude-haiku-4-5-20251001'
-	| string;
+// Known model ids — kept narrow for documentation. Use `string` at the boundary.
+export const KNOWN_MODELS = [
+	'claude-opus-4-7',
+	'claude-sonnet-4-6',
+	'claude-haiku-4-5-20251001',
+	'claude-opus-4-6',
+	'claude-opus-4-5',
+	'claude-sonnet-4-5',
+	'claude-haiku-4-0',
+] as const;
+
+export type ModelId = string;
 
 export type TurnType = 'user' | 'assistant' | 'summary' | 'system';
 
@@ -19,12 +26,9 @@ export interface ServerToolUse {
 export interface TokenUsage {
 	input_tokens: number;
 	output_tokens: number;
-	// Legacy flat counter. Real logs also carry `cache_creation` with TTL split; if present,
-	// prefer that for accurate pricing.
 	cache_creation_input_tokens?: number;
 	cache_read_input_tokens?: number;
 	cache_creation?: CacheCreationDetail;
-	// Anthropic server-side tool use (web_search, web_fetch). Priced per request, not per token.
 	server_tool_use?: ServerToolUse;
 }
 
@@ -34,8 +38,10 @@ export interface SessionTurn {
 	sessionId: string;
 	projectId?: string | undefined;
 	subagentType?: string | undefined;
+	parentSessionId?: string | undefined;
 	model?: ModelId | undefined;
 	usage?: TokenUsage | undefined;
+	toolUses?: string[] | undefined; // tool names invoked in this assistant turn
 	raw: unknown;
 }
 
@@ -67,3 +73,15 @@ export interface LedgerReport {
 	rows: AggregatedRow[];
 	total: AggregatedRow;
 }
+
+// Subagent-graph node — the MOAT feature.
+// Represents one parent session's tree-rooted cost attribution:
+// the parent's own cost + all child subagent costs, recursively.
+export interface SubagentTreeNode {
+	sessionId: string;
+	label: string; // subagentType or '(orchestrator)'
+	selfCost: number;
+	totalCost: number; // self + children
+	children: SubagentTreeNode[];
+	turnCount: number;
+}

package/test/property.test.ts

@@ -0,0 +1,188 @@
+// Property tests — invariants that must hold for ANY input, not just fixtures.
+// (Backend audit recommendation: cover pricing math + aggregator math.)
+
+import { describe, expect, test } from 'bun:test';
+import * as fc from 'fast-check';
+import { Aggregator, SubagentGraph } from '../src/aggregator.ts';
+import { costFor } from '../src/pricing.ts';
+import type { SessionTurn, TokenUsage } from '../src/types.ts';
+
+// Bounded-positive token counter — Anthropic emits non-negative integers.
+const arbTokens = (): fc.Arbitrary<number> => fc.integer({ min: 0, max: 10_000_000 });
+
+// Realistic Anthropic models that should price correctly.
+const arbModel = (): fc.Arbitrary<string> =>
+	fc.constantFrom(
+		'claude-opus-4-7',
+		'claude-sonnet-4-6',
+		'claude-haiku-4-5-20251001',
+		'claude-opus-4-6',
+		'claude-sonnet-4-5',
+	);
+
+const arbUsage = (): fc.Arbitrary<TokenUsage> =>
+	fc.record({
+		input_tokens: arbTokens(),
+		output_tokens: arbTokens(),
+		cache_read_input_tokens: fc.option(arbTokens(), { nil: undefined }),
+		cache_creation: fc.option(
+			fc.record({
+				ephemeral_5m_input_tokens: fc.option(arbTokens(), { nil: undefined }),
+				ephemeral_1h_input_tokens: fc.option(arbTokens(), { nil: undefined }),
+			}),
+			{ nil: undefined },
+		),
+	});
+
+const arbAssistantTurn = (): fc.Arbitrary<SessionTurn> =>
+	fc
+		.record({
+			usage: arbUsage(),
+			model: arbModel(),
+			sessionId: fc.string({ minLength: 8, maxLength: 36 }),
+			timestamp: fc.integer({ min: 1735689600000, max: 1798800000000 }).map(
+				(ms) => new Date(ms).toISOString(),
+			),
+			subagentType: fc.option(fc.string({ minLength: 1, maxLength: 20 }), { nil: undefined }),
+			projectId: fc.option(fc.string({ minLength: 1, maxLength: 30 }), { nil: undefined }),
+			parentSessionId: fc.option(fc.string({ minLength: 8, maxLength: 36 }), { nil: undefined }),
+			toolUses: fc.option(fc.array(fc.string({ minLength: 1, maxLength: 10 }), { maxLength: 5 }), {
+				nil: undefined,
+			}),
+		})
+		.map((r) => ({
+			type: 'assistant' as const,
+			...r,
+			raw: r,
+		}));
+
+describe('costFor() invariants', () => {
+	test('cost is non-negative for any valid usage + model', () => {
+		fc.assert(
+			fc.property(arbUsage(), arbModel(), (usage, model) => {
+				const c = costFor(usage, model);
+				expect(c.totalCost).toBeGreaterThanOrEqual(0);
+				expect(c.inputCost).toBeGreaterThanOrEqual(0);
+				expect(c.outputCost).toBeGreaterThanOrEqual(0);
+				expect(c.cacheReadCost).toBeGreaterThanOrEqual(0);
+			}),
+			{ numRuns: 200 },
+		);
+	});
+
+	test('totalCost equals sum of components', () => {
+		fc.assert(
+			fc.property(arbUsage(), arbModel(), (usage, model) => {
+				const c = costFor(usage, model);
+				const sum =
+					c.inputCost +
+					c.outputCost +
+					c.cacheCreation5mCost +
+					c.cacheCreation1hCost +
+					c.cacheReadCost +
+					c.serverToolUseCost;
+				// Floating point — allow tiny epsilon.
+				expect(Math.abs(c.totalCost - sum)).toBeLessThan(1e-9);
+			}),
+			{ numRuns: 200 },
+		);
+	});
+
+	test('cache_read is always cheaper than the same input as fresh tokens', () => {
+		fc.assert(
+			fc.property(arbTokens(), arbModel(), (n, model) => {
+				const fresh = costFor({ input_tokens: n, output_tokens: 0 }, model).totalCost;
+				const cached = costFor(
+					{ input_tokens: 0, output_tokens: 0, cache_read_input_tokens: n },
+					model,
+				).totalCost;
+				// Cached should be ≤ fresh (90% discount).
+				expect(cached).toBeLessThanOrEqual(fresh + 1e-9);
+			}),
+			{ numRuns: 100 },
+		);
+	});
+
+	test('cache_creation_1h is always more expensive than cache_creation_5m for same tokens', () => {
+		fc.assert(
+			fc.property(fc.integer({ min: 1, max: 1_000_000 }), arbModel(), (n, model) => {
+				const fiveMin = costFor(
+					{
+						input_tokens: 0,
+						output_tokens: 0,
+						cache_creation: { ephemeral_5m_input_tokens: n },
+					},
+					model,
+				).totalCost;
+				const oneH = costFor(
+					{
+						input_tokens: 0,
+						output_tokens: 0,
+						cache_creation: { ephemeral_1h_input_tokens: n },
+					},
+					model,
+				).totalCost;
+				expect(oneH).toBeGreaterThanOrEqual(fiveMin - 1e-9);
+			}),
+			{ numRuns: 100 },
+		);
+	});
+});
+
+describe('Aggregator invariants', () => {
+	test('total.cost equals sum of row.cost across any group key', () => {
+		fc.assert(
+			fc.property(fc.array(arbAssistantTurn(), { minLength: 0, maxLength: 50 }), (turns) => {
+				const agg = new Aggregator(
+					'subagent',
+					new Date('2025-01-01'),
+					new Date('2027-01-01'),
+				);
+				for (const t of turns) agg.add(t);
+				const report = agg.finalize();
+				const rowSum = report.rows.reduce((s, r) => s + r.cost.totalCost, 0);
+				expect(Math.abs(report.total.cost.totalCost - rowSum)).toBeLessThan(1e-6);
+			}),
+			{ numRuns: 100 },
+		);
+	});
+
+	test('non-assistant turns are ignored (no cost contribution)', () => {
+		fc.assert(
+			fc.property(arbUsage(), arbModel(), (usage, model) => {
+				const userTurn: SessionTurn = {
+					type: 'user',
+					usage,
+					model,
+					sessionId: 'sess',
+					timestamp: '2026-04-23T00:00:00Z',
+					raw: {},
+				};
+				const agg = new Aggregator('subagent', new Date('2025-01-01'), new Date('2027-01-01'));
+				agg.add(userTurn);
+				const report = agg.finalize();
+				expect(report.total.cost.totalCost).toBe(0);
+			}),
+			{ numRuns: 50 },
+		);
+	});
+});
+
+describe('SubagentGraph invariants', () => {
+	test('parent totalCost ≥ self cost (children only add)', () => {
+		fc.assert(
+			fc.property(
+				fc.array(arbAssistantTurn(), { minLength: 1, maxLength: 30 }),
+				(turns) => {
+					const graph = new SubagentGraph();
+					for (const t of turns) graph.add(t);
+					const roots = graph.finalize(50);
+					for (const r of roots) {
+						expect(r.totalCost).toBeGreaterThanOrEqual(r.selfCost - 1e-9);
+					}
+				},
+			),
+			{ numRuns: 50 },
+		);
+	});
+});