Skip to content

an open-source alternative to the dots, bots and muses of the world, run an office of claude code/codex like agents on your laptop, sandboxes or anywhere, uses your existing subscriptions

perf(usage): incremental per-file transcript cache (~350x on warm reads) (#111)

Quentin Schmick68df5b88f937
diff --git a/src/main/transcript.ts b/src/main/transcript.ts
index 02f56b45..e4630ad8 100644
--- a/src/main/transcript.ts
+++ b/src/main/transcript.ts
@@ -114,13 +114,120 @@ export interface ReadUsageOptions {
sessionId?: string;
}
+/** Per-file incremental parse state for the usage cache. Transcripts are
+ * append-only JSONL, so a parsed byte range's totals never change — repeat
+ * reads only stat the file and parse the appended tail. Keyed by
+ * dir|file|sessionFilter since the filter changes what a range sums to. */
+interface FileUsageEntry {
+ size: number;
+ mtimeMs: number;
+ /** Bytes parsed so far — always ends on a newline boundary, so a torn
+ * trailing line is simply re-read once the writer completes it. */
+ offset: number;
+ totals: AgentUsage;
+}
+
+const usageCache = new Map<string, FileUsageEntry>();
+/** Soft bound; when crossed, the oldest-inserted half is dropped (entries
+ * rebuild on demand). Real fleets have tens of transcripts, not thousands. */
+const USAGE_CACHE_MAX = 2048;
+
+/** Parse complete JSONL lines into `acc` (the shared per-record logic). */
+function parseUsageLines(text: string, sessionId: string | undefined, acc: AgentUsage): void {
+ for (const line of text.split('\n')) {
+ const trimmed = line.trim();
+ if (!trimmed) continue;
+ let rec: {
+ type?: unknown;
+ sessionId?: unknown;
+ message?: { model?: unknown; usage?: Record<string, unknown> };
+ };
+ try {
+ rec = JSON.parse(trimmed);
+ } catch {
+ continue;
+ }
+ if (rec.type !== 'assistant') continue;
+ // Session filter: skip records that aren't this agent's session.
+ if (sessionId && rec.sessionId !== sessionId) continue;
+ const u = rec.message?.usage;
+ if (!u) continue;
+ const model = typeof rec.message?.model === 'string' ? normalizeModel(rec.message.model) : undefined;
+ if (model) acc.model = model;
+ const rIn = num(u.input_tokens);
+ const rOut = num(u.output_tokens);
+ const rCacheWrite = num(u.cache_creation_input_tokens);
+ const rCacheRead = num(u.cache_read_input_tokens);
+ acc.inputTokens += rIn;
+ acc.outputTokens += rOut;
+ acc.cacheWriteTokens += rCacheWrite;
+ acc.cacheReadTokens += rCacheRead;
+ // Price THIS record by its own model, then accumulate — so a mixed-model
+ // agent (rare) is still costed correctly rather than at one flat rate.
+ acc.estimatedCostUsd += estimateCostUsd(model, {
+ inputTokens: rIn,
+ outputTokens: rOut,
+ cacheReadTokens: rCacheRead,
+ cacheWriteTokens: rCacheWrite
+ });
+ }
+}
+
+/** Cached totals for one transcript file, refreshed incrementally: unchanged
+ * size+mtime → cache hit (no read at all); grown → parse only the appended
+ * tail; shrunk (rewritten) → full re-parse. Null when the file vanished. */
+function readFileUsage(dir: string, file: string, sessionId: string | undefined): FileUsageEntry | null {
+ const key = `${dir}|${file}|${sessionId ?? '*'}`;
+ const full = path.join(dir, file);
+ let st: { size: number; mtimeMs: number };
+ try { st = statSync(full); } catch { usageCache.delete(key); return null; }
+ const cached = usageCache.get(key);
+ if (cached && cached.size === st.size && cached.mtimeMs === st.mtimeMs) return cached;
+ const fromScratch = !cached || st.size < cached.offset;
+ const entry: FileUsageEntry = fromScratch
+ ? { size: st.size, mtimeMs: st.mtimeMs, offset: 0, totals: zero() }
+ : { size: st.size, mtimeMs: st.mtimeMs, offset: cached!.offset, totals: { ...cached!.totals } };
+ try {
+ const fd = openSync(full, 'r');
+ try {
+ const len = st.size - entry.offset;
+ if (len > 0) {
+ const buf = Buffer.alloc(len);
+ const read = readSync(fd, buf, 0, len, entry.offset);
+ const text = buf.subarray(0, read).toString('utf8');
+ // Consume only up to the last complete line; a torn trailing line
+ // stays unparsed (offset holds at the newline) until the writer
+ // finishes it — it is then counted exactly once.
+ const lastNl = text.lastIndexOf('\n');
+ if (lastNl !== -1) {
+ const complete = text.slice(0, lastNl + 1);
+ parseUsageLines(complete, sessionId, entry.totals);
+ entry.offset += Buffer.byteLength(complete, 'utf8');
+ }
+ }
+ } finally { closeSync(fd); }
+ } catch {
+ // Unreadable right now — keep what we have; totals refresh on the next call.
+ }
+ usageCache.set(key, entry);
+ if (usageCache.size > USAGE_CACHE_MAX) {
+ let drop = usageCache.size - USAGE_CACHE_MAX / 2;
+ for (const k of usageCache.keys()) { if (drop-- <= 0) break; usageCache.delete(k); }
+ }
+ return entry;
+}
+
/** Sum real token usage across Claude Code transcripts for `cwd`, pricing each
* assistant record by ITS OWN model (fixes cost bug #1 — no more Sonnet for
* everyone) via the fallback price table. Optionally filtered to one session
* (fixes bug #2). Resilient by design: any unreadable file or malformed line is
* skipped, and any unexpected failure yields a zeroed result rather than
* throwing into the IPC handler. This is the OFFLINE reconciler / fallback —
- * the live source is the OTel collector (`telemetry.ts`). */
+ * the live source is the OTel collector (`telemetry.ts`).
+ *
+ * Called from the ~30s breaker/cost beat for every agent without live OTel, so
+ * it must stay cheap on multi-MB transcript dirs: per-file incremental caching
+ * above means a steady-state call is a readdir + one stat per file. */
export function readAgentUsage(cwd: string, opts: ReadUsageOptions = {}): AgentUsage {
const usage = zero();
try {
@@ -129,48 +236,14 @@ export function readAgentUsage(cwd: string, opts: ReadUsageOptions = {}): AgentU
const files = readdirSync(dir).filter((f) => f.endsWith('.jsonl'));
let lastModel: string | undefined;
for (const file of files) {
- try {
- const text = readFileSync(path.join(dir, file), 'utf8');
- for (const line of text.split('\n')) {
- const trimmed = line.trim();
- if (!trimmed) continue;
- let rec: {
- type?: unknown;
- sessionId?: unknown;
- message?: { model?: unknown; usage?: Record<string, unknown> };
- };
- try {
- rec = JSON.parse(trimmed);
- } catch {
- continue;
- }
- if (rec.type !== 'assistant') continue;
- // Session filter: skip records that aren't this agent's session.
- if (opts.sessionId && rec.sessionId !== opts.sessionId) continue;
- const u = rec.message?.usage;
- if (!u) continue;
- const model = typeof rec.message?.model === 'string' ? normalizeModel(rec.message.model) : undefined;
- if (model) lastModel = model;
- const rIn = num(u.input_tokens);
- const rOut = num(u.output_tokens);
- const rCacheWrite = num(u.cache_creation_input_tokens);
- const rCacheRead = num(u.cache_read_input_tokens);
- usage.inputTokens += rIn;
- usage.outputTokens += rOut;
- usage.cacheWriteTokens += rCacheWrite;
- usage.cacheReadTokens += rCacheRead;
- // Price THIS record by its own model, then accumulate — so a mixed-model
- // agent (rare) is still costed correctly rather than at one flat rate.
- usage.estimatedCostUsd += estimateCostUsd(model, {
- inputTokens: rIn,
- outputTokens: rOut,
- cacheReadTokens: rCacheRead,
- cacheWriteTokens: rCacheWrite
- });
- }
- } catch {
- // Skip this file; keep accumulating across the rest.
- }
+ const entry = readFileUsage(dir, file, opts.sessionId);
+ if (!entry) continue;
+ usage.inputTokens += entry.totals.inputTokens;
+ usage.outputTokens += entry.totals.outputTokens;
+ usage.cacheWriteTokens += entry.totals.cacheWriteTokens;
+ usage.cacheReadTokens += entry.totals.cacheReadTokens;
+ usage.estimatedCostUsd += entry.totals.estimatedCostUsd;
+ if (entry.totals.model) lastModel = entry.totals.model;
}
if (lastModel) usage.model = lastModel;
return usage;
diff --git a/test/transcript-usage.test.cjs b/test/transcript-usage.test.cjs
new file mode 100644
index 00000000..ae0e54f0
--- /dev/null
+++ b/test/transcript-usage.test.cjs
@@ -0,0 +1,148 @@
+'use strict';
+/**
+ * readAgentUsage incremental-cache tests. Self-contained, no framework — run
+ * with `node test/transcript-usage.test.cjs` (mirrors test/breaker.test.cjs).
+ * transcript.ts + its dependency pricing.ts are transpiled with the bundled
+ * `typescript` compiler.
+ *
+ * The breaker/cost beat calls readAgentUsage every ~30s per agent (transcript
+ * fallback); it used to re-read and re-JSON.parse EVERY transcript in the
+ * project dir each call. These tests pin the cached implementation to the same
+ * observable results across appends, partial writes, rewrites, and session
+ * filters — correctness of the incremental path, not just speed.
+ */
+
+const assert = require('node:assert');
+const fs = require('node:fs');
+const os = require('node:os');
+const path = require('node:path');
+const ts = require('typescript');
+
+// Sandbox HOME so projectDir() maps into a throwaway dir, never the user's
+// real ~/.claude/projects. os.homedir() reads $HOME/$USERPROFILE per call.
+const FAKE_HOME = fs.mkdtempSync(path.join(os.tmpdir(), 'home-'));
+process.env.HOME = FAKE_HOME;
+process.env.USERPROFILE = FAKE_HOME;
+
+const SRC = path.join(__dirname, '..', 'src', 'main');
+const out = fs.mkdtempSync(path.join(os.tmpdir(), 'transcript-'));
+for (const name of ['pricing', 'transcript']) {
+ const js = ts.transpileModule(fs.readFileSync(path.join(SRC, `${name}.ts`), 'utf8'), {
+ compilerOptions: { module: ts.ModuleKind.CommonJS, target: ts.ScriptTarget.ES2020, esModuleInterop: true }
+ }).outputText;
+ fs.writeFileSync(path.join(out, `${name}.js`), js, 'utf8');
+}
+const { readAgentUsage, projectDir } = require(path.join(out, 'transcript.js'));
+
+/** A fake cwd whose projectDir we can write transcripts into. */
+function makeProject() {
+ const cwd = fs.mkdtempSync(path.join(os.tmpdir(), 'proj-'));
+ const dir = projectDir(cwd);
+ fs.mkdirSync(dir, { recursive: true });
+ return { cwd, dir };
+}
+
+function rec(output, opts = {}) {
+ return JSON.stringify({
+ type: 'assistant',
+ sessionId: opts.sessionId ?? 's1',
+ message: {
+ model: opts.model ?? 'claude-haiku-4-5',
+ usage: { input_tokens: opts.input ?? 10, output_tokens: output, cache_read_input_tokens: 0, cache_creation_input_tokens: 0 }
+ }
+ });
+}
+
+let failures = 0;
+function test(name, fn) {
+ try { fn(); console.log(` ok ${name}`); }
+ catch (e) { failures++; console.error(`FAIL ${name}\n ${e.message}`); }
+}
+
+test('sums usage across records and files', () => {
+ const { cwd, dir } = makeProject();
+ fs.writeFileSync(path.join(dir, 'a.jsonl'), rec(100) + '\n' + rec(200) + '\n');
+ fs.writeFileSync(path.join(dir, 'b.jsonl'), rec(50) + '\n');
+ const u = readAgentUsage(cwd);
+ assert.equal(u.outputTokens, 350);
+ assert.equal(u.inputTokens, 30);
+ assert.ok(u.estimatedCostUsd > 0);
+});
+
+test('appended records are picked up (incremental tail parse)', () => {
+ const { cwd, dir } = makeProject();
+ const f = path.join(dir, 'a.jsonl');
+ fs.writeFileSync(f, rec(100) + '\n');
+ assert.equal(readAgentUsage(cwd).outputTokens, 100); // primes the cache
+ fs.appendFileSync(f, rec(25) + '\n' + rec(75) + '\n');
+ assert.equal(readAgentUsage(cwd).outputTokens, 200);
+});
+
+test('repeat reads with no change are stable', () => {
+ const { cwd, dir } = makeProject();
+ fs.writeFileSync(path.join(dir, 'a.jsonl'), rec(100) + '\n');
+ const a = readAgentUsage(cwd);
+ const b = readAgentUsage(cwd);
+ assert.deepEqual(b, a);
+});
+
+test('a partial trailing line is not counted until completed', () => {
+ const { cwd, dir } = makeProject();
+ const f = path.join(dir, 'a.jsonl');
+ const full = rec(500);
+ fs.writeFileSync(f, rec(100) + '\n' + full.slice(0, 40)); // torn mid-write
+ assert.equal(readAgentUsage(cwd).outputTokens, 100);
+ fs.appendFileSync(f, full.slice(40) + '\n'); // writer finishes the line
+ assert.equal(readAgentUsage(cwd).outputTokens, 600, 'completed line counts exactly once');
+});
+
+test('a rewritten (shrunk) file is re-parsed from scratch', () => {
+ const { cwd, dir } = makeProject();
+ const f = path.join(dir, 'a.jsonl');
+ fs.writeFileSync(f, rec(100) + '\n' + rec(200) + '\n');
+ assert.equal(readAgentUsage(cwd).outputTokens, 300);
+ fs.writeFileSync(f, rec(40) + '\n'); // smaller rewrite
+ assert.equal(readAgentUsage(cwd).outputTokens, 40);
+});
+
+test('a deleted file drops out of the totals', () => {
+ const { cwd, dir } = makeProject();
+ fs.writeFileSync(path.join(dir, 'a.jsonl'), rec(100) + '\n');
+ fs.writeFileSync(path.join(dir, 'b.jsonl'), rec(50) + '\n');
+ assert.equal(readAgentUsage(cwd).outputTokens, 150);
+ fs.rmSync(path.join(dir, 'b.jsonl'));
+ assert.equal(readAgentUsage(cwd).outputTokens, 100);
+});
+
+test('sessionId filter sums only that session, incrementally too', () => {
+ const { cwd, dir } = makeProject();
+ const f = path.join(dir, 'a.jsonl');
+ fs.writeFileSync(f, rec(100, { sessionId: 's1' }) + '\n' + rec(999, { sessionId: 's2' }) + '\n');
+ assert.equal(readAgentUsage(cwd, { sessionId: 's1' }).outputTokens, 100);
+ fs.appendFileSync(f, rec(11, { sessionId: 's1' }) + '\n' + rec(888, { sessionId: 's2' }) + '\n');
+ assert.equal(readAgentUsage(cwd, { sessionId: 's1' }).outputTokens, 111);
+ assert.equal(readAgentUsage(cwd, { sessionId: 's2' }).outputTokens, 1887);
+ assert.equal(readAgentUsage(cwd).outputTokens, 1998, 'unfiltered still sums everything');
+});
+
+test('malformed lines and non-assistant records are skipped', () => {
+ const { cwd, dir } = makeProject();
+ fs.writeFileSync(path.join(dir, 'a.jsonl'),
+ 'not json\n' + JSON.stringify({ type: 'user' }) + '\n' + rec(70) + '\n\n');
+ assert.equal(readAgentUsage(cwd).outputTokens, 70);
+});
+
+test('model is the last one seen (per current semantics)', () => {
+ const { cwd, dir } = makeProject();
+ fs.writeFileSync(path.join(dir, 'a.jsonl'),
+ rec(1, { model: 'claude-haiku-4-5' }) + '\n' + rec(2, { model: 'claude-opus-4-8' }) + '\n');
+ assert.equal(readAgentUsage(cwd).model, 'claude-opus-4-8');
+});
+
+test('missing project dir yields zeros', () => {
+ const u = readAgentUsage('/nonexistent/cwd/for/testing');
+ assert.equal(u.outputTokens, 0);
+ assert.equal(u.estimatedCostUsd, 0);
+});
+
+process.exit(failures ? 1 : 0);