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
HTML agent-harnessagent-orchestrationagentsai-agentsautonomous-agentsclaude-codecodexcoding-agentsdesktop-appdeveloper-toolselectrongemini-cliharnessharness-engineeringlocal-firstmemorymulti-agentopencodeorchestrationtypescript
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.tsindex 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 = {}): AgentUconst 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.cjsnew file mode 100644index 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);