@jjanczur/tyran 0.1.17 → 0.1.18

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,811 @@
1
+ #!/usr/bin/env node
2
+ /**
3
+ * cost — what the work cost, in tokens the platform itself reported.
4
+ *
5
+ * Claude Code already writes every number this needs. Each assistant record in
6
+ * a session transcript carries `message.usage` (input, cache write, cache read,
7
+ * output) and `message.model`; each subagent gets its own transcript under
8
+ * `<session>/subagents/` beside a `.meta.json` naming its agent type and the
9
+ * description the conductor gave it. So this reads, it never instruments: no
10
+ * hook, no probe, no new event type, and nothing to keep in sync.
11
+ *
12
+ * THREE PROPERTIES THIS FILE EXISTS TO HOLD.
13
+ *
14
+ * 1. Tokens are facts; money is an opinion. Only tokens are counted here.
15
+ * Money is derived at the very end from an operator-written rate card, and
16
+ * the card's NAME travels with every amount — two people quoting different
17
+ * cards get different money from one set of tokens, and a figure that
18
+ * cannot say which card produced it is not a measurement.
19
+ *
20
+ * 2. This is NOT a projection. Its inputs live in ~/.claude, are machine-local
21
+ * and differ per clone, so it is never byte-compared, never committed, and
22
+ * never enters `board.json` — the sidecar it writes joins the overnight
23
+ * runtime files that `.tyran/.gitignore` excludes. Putting spend into a
24
+ * committed, byte-checked artefact would make two people with the same
25
+ * journal disagree.
26
+ *
27
+ * 3. Gaps are reported, never zeroed. A model with no rate is `unpriced`, an
28
+ * agent whose ticket cannot be read is `unattributed`, a transcript that
29
+ * will not parse is `unreadable`, and the conductor's own spend — measured
30
+ * at roughly two thirds of a real session — is its own line rather than
31
+ * being spread across tickets or quietly dropped. An operator uses these
32
+ * numbers to decide where to spend the next agent; a total that is low by
33
+ * an unknown amount produces confident wrong routing, which is worse than
34
+ * no number at all.
35
+ *
36
+ * CLI:
37
+ * node cost.mjs [--dir <.tyran>] [--session <id>] [--json] [--projects <dir>]
38
+ * Exit: 0 ok · 2 usage/IO
39
+ */
40
+ import { closeSync, existsSync, mkdirSync, openSync, readdirSync, readFileSync, readSync, realpathSync, renameSync, statSync, writeFileSync } from 'node:fs';
41
+ import { homedir } from 'node:os';
42
+ import { basename, dirname, join, resolve, sep } from 'node:path';
43
+ import { StringDecoder } from 'node:string_decoder';
44
+ import { fileURLToPath } from 'node:url';
45
+ import { parse } from './yaml-lite.mjs';
46
+ import { pricingOf, PRICING_RATE_KEYS } from './schema.mjs';
47
+ import { jsonEscapeInvisible } from './invisible.mjs';
48
+
49
+ export const COST_FILE = 'cost.json';
50
+ export const COST_SCHEMA = 1;
51
+
52
+ /** Read buffer for the chunked line reader. Transcripts reach tens of MB. */
53
+ const CHUNK_BYTES = 1 << 20;
54
+
55
+ /**
56
+ * A single line longer than this is abandoned rather than accumulated. One
57
+ * pathological record must not turn a reader into an out-of-memory crash on
58
+ * the operator's machine; the line is counted as skipped and says so.
59
+ */
60
+ const MAX_LINE_BYTES = 8 << 20;
61
+
62
+ /** Transcripts above this are refused loudly rather than read. */
63
+ const MAX_TRANSCRIPT_BYTES = 512 << 20;
64
+
65
+ /** The conductor's own transcript is one file; agents are the rest. */
66
+ export const CONDUCTOR = 'conductor';
67
+
68
+ /** A ticket id at the head of a Task description, which is how a subagent's
69
+ * spend reaches a ticket without any change to the journal or the event set.
70
+ * The conductor writes the id; a description that omits it lands the agent in
71
+ * `unattributed`, visibly, rather than being guessed at. */
72
+ export const TICKET_IN_DESCRIPTION_RE = /^\s*\[?(T-\d+)\b/;
73
+
74
+ class UsageError extends Error {}
75
+
76
+ /** A fresh counter set. Kept flat so accumulation is a loop, not a schema. */
77
+ export function emptyCounters() {
78
+ return { requests: 0, input: 0, cache_write: 0, cache_read: 0, output: 0 };
79
+ }
80
+
81
+ const COUNTER_KEYS = Object.freeze(['requests', 'input', 'cache_write', 'cache_read', 'output']);
82
+
83
+ /** b into a, in place. */
84
+ export function addCounters(a, b) {
85
+ for (const key of COUNTER_KEYS) a[key] += b[key] ?? 0;
86
+ return a;
87
+ }
88
+
89
+ /** Total tokens billed, whatever the rate. Requests are not tokens. */
90
+ export function tokensOf(counters) {
91
+ return counters.input + counters.cache_write + counters.cache_read + counters.output;
92
+ }
93
+
94
+ /** Own-property read on a prototype-free view of foreign JSON. */
95
+ function field(obj, name) {
96
+ return obj !== null && typeof obj === 'object' && Object.prototype.hasOwnProperty.call(obj, name)
97
+ ? obj[name]
98
+ : undefined;
99
+ }
100
+
101
+ function finiteCount(value) {
102
+ return typeof value === 'number' && Number.isFinite(value) && value >= 0 ? value : 0;
103
+ }
104
+
105
+ /**
106
+ * What one request cost, in dollars, or null when the model has no rate.
107
+ * Null is not zero and callers must not treat it as zero — that distinction
108
+ * is the whole of property 3 above.
109
+ */
110
+ export function costOf(model, counters, models) {
111
+ const rates = Object.prototype.hasOwnProperty.call(models, model) ? models[model] : undefined;
112
+ if (rates === undefined) return null;
113
+ let total = 0;
114
+ for (const key of PRICING_RATE_KEYS) total += (counters[key] ?? 0) * rates[key];
115
+ return total / 1e6;
116
+ }
117
+
118
+ /**
119
+ * Sum a per-model table to dollars, counting only the models that have a rate.
120
+ *
121
+ * Null means "nothing here is priced at all" — a row that renders as an em
122
+ * dash. It deliberately does NOT mean "one model is missing a rate": a real
123
+ * rate card always misses something (`<synthetic>` appears in live data and
124
+ * cannot be priced by anyone), and nulling the grand total over one absent
125
+ * row would leave every amount on the page blank forever. Partial pricing is
126
+ * therefore a partial sum, and `unpriced` names what was left out of it —
127
+ * useful and honest, where an em dash would be honest and useless.
128
+ */
129
+ export function costOfTable(byModel, models) {
130
+ let total = 0;
131
+ let priced = 0;
132
+ for (const [model, counters] of Object.entries(byModel)) {
133
+ const one = costOf(model, counters, models);
134
+ if (one === null) continue;
135
+ priced += 1;
136
+ total += one;
137
+ }
138
+ return priced === 0 ? null : total;
139
+ }
140
+
141
+ /**
142
+ * Every complete line of a file, as a string, without holding the file in
143
+ * memory. Sync to match the rest of this codebase; chunked because a
144
+ * transcript is routinely tens of megabytes and occasionally hundreds.
145
+ */
146
+ export function forEachLine(path, onLine, { maxBytes = Infinity } = {}) {
147
+ const size = statSync(path).size;
148
+ if (size > MAX_TRANSCRIPT_BYTES) {
149
+ throw new UsageError(`cost: transcript larger than ${MAX_TRANSCRIPT_BYTES} bytes: ${path}`);
150
+ }
151
+ const fd = openSync(path, 'r');
152
+ const buffer = Buffer.allocUnsafe(CHUNK_BYTES);
153
+ // A StringDecoder rather than buffer.toString(): a multi-byte character
154
+ // straddling a chunk boundary decodes to replacement characters otherwise,
155
+ // and one of the things read out of these files is a repo path compared for
156
+ // equality — a mangled non-ASCII path silently reports "no transcripts".
157
+ const decoder = new StringDecoder('utf8');
158
+ let rest = '';
159
+ let skipped = 0;
160
+ let readBytes = 0;
161
+ // Set when an over-long record was abandoned: everything up to that
162
+ // record's OWN terminating newline still has to be thrown away. Without
163
+ // this, the tail of the discarded record is handed to the caller as if it
164
+ // were a record of its own — and a tail that happens to parse is spend the
165
+ // reader INVENTS. Measured: one 9 MB line ending in a well-formed fragment
166
+ // billed 777 777 tokens against a model that never existed, with the gap
167
+ // counters reading clean.
168
+ let resync = false;
169
+ try {
170
+ for (;;) {
171
+ const read = readSync(fd, buffer, 0, CHUNK_BYTES, null);
172
+ if (read === 0) break;
173
+ readBytes += read;
174
+ rest += decoder.write(buffer.subarray(0, read));
175
+ if (resync) {
176
+ const nl = rest.indexOf('\n');
177
+ if (nl === -1) {
178
+ rest = '';
179
+ if (readBytes >= maxBytes) return skipped;
180
+ continue;
181
+ }
182
+ rest = rest.slice(nl + 1);
183
+ resync = false;
184
+ }
185
+ let at;
186
+ let stop = false;
187
+ while ((at = rest.indexOf('\n')) !== -1) {
188
+ const line = rest.slice(0, at);
189
+ rest = rest.slice(at + 1);
190
+ // A callback that says it is done ends the read. Without this the
191
+ // directory probe reads every candidate file to EOF after it has
192
+ // already matched on line one — 83 ms on a 200 MB transcript, paid
193
+ // per file, per request.
194
+ if (onLine(line) === false) {
195
+ stop = true;
196
+ break;
197
+ }
198
+ }
199
+ if (stop) return skipped;
200
+ if (rest.length > MAX_LINE_BYTES) {
201
+ skipped += 1;
202
+ rest = '';
203
+ resync = true;
204
+ }
205
+ if (readBytes >= maxBytes) return skipped;
206
+ }
207
+ rest += decoder.end();
208
+ // A file ending mid-discard has no tail worth delivering.
209
+ if (rest !== '' && !resync) onLine(rest);
210
+ } finally {
211
+ closeSync(fd);
212
+ }
213
+ return skipped;
214
+ }
215
+
216
+ /**
217
+ * One transcript folded to per-model counters.
218
+ *
219
+ * Deduplicated by `requestId`: the platform writes one record per content
220
+ * block, and every record of a request repeats that request's CUMULATIVE
221
+ * usage. Counting them all inflates every number in this file, so the first
222
+ * record of each request wins and the rest are dropped.
223
+ */
224
+ export function scanTranscript(path) {
225
+ const byModel = Object.create(null);
226
+ const seen = new Set();
227
+ let malformed = 0;
228
+ let firstTs = null;
229
+ let lastTs = null;
230
+ const skippedLines = forEachLine(path, (line) => {
231
+ if (line === '' || line.charCodeAt(0) !== 123 /* { */) return;
232
+ let event;
233
+ try {
234
+ event = JSON.parse(line);
235
+ } catch {
236
+ malformed += 1;
237
+ return;
238
+ }
239
+ const ts = field(event, 'timestamp');
240
+ if (typeof ts === 'string') {
241
+ if (firstTs === null || ts < firstTs) firstTs = ts;
242
+ if (lastTs === null || ts > lastTs) lastTs = ts;
243
+ }
244
+ if (field(event, 'type') !== 'assistant') return;
245
+ const message = field(event, 'message');
246
+ const usage = field(message, 'usage');
247
+ if (usage === null || typeof usage !== 'object') return;
248
+ const key = field(event, 'requestId') ?? field(event, 'uuid');
249
+ if (typeof key === 'string') {
250
+ if (seen.has(key)) return;
251
+ seen.add(key);
252
+ }
253
+ const model = typeof field(message, 'model') === 'string' ? field(message, 'model') : 'unknown';
254
+ if (byModel[model] === undefined) byModel[model] = emptyCounters();
255
+ const into = byModel[model];
256
+ into.requests += 1;
257
+ into.input += finiteCount(field(usage, 'input_tokens'));
258
+ into.cache_write += finiteCount(field(usage, 'cache_creation_input_tokens'));
259
+ into.cache_read += finiteCount(field(usage, 'cache_read_input_tokens'));
260
+ into.output += finiteCount(field(usage, 'output_tokens'));
261
+ });
262
+ return { byModel, malformed, skippedLines, firstTs, lastTs };
263
+ }
264
+
265
+ /**
266
+ * Where this repo's transcripts live.
267
+ *
268
+ * The directory name is the repo path with separators replaced by dashes —
269
+ * a rule read off the filesystem, not out of documentation, so it is checked
270
+ * and then verified rather than trusted: if the computed directory is absent,
271
+ * every project directory is opened and matched on the `cwd` its records
272
+ * carry. A guess about the platform that cannot be confirmed is exactly the
273
+ * kind of assumption this project refuses to build a control on.
274
+ */
275
+ const dirCache = new Map();
276
+
277
+ /**
278
+ * How far into a candidate transcript the fallback reads before giving up on
279
+ * it. Every record carries `cwd`, so the answer is on line one.
280
+ *
281
+ * The bound is checked after a whole 1 MiB read, so in practice it stops a
282
+ * miss at one chunk per candidate rather than at this number exactly — which
283
+ * is the point: a miss costs a megabyte per file instead of a whole
284
+ * transcript, across a project directory nobody has ever pruned.
285
+ */
286
+ const PROBE_BYTES = 64 * 1024;
287
+
288
+ export function transcriptDirFor(repoRoot, projectsRoot) {
289
+ const want = resolve(repoRoot);
290
+ // Memoised for the life of the process, negative results included. The
291
+ // board server re-renders per request and refreshes every 30 s; without
292
+ // this, a repo whose slug does not match pays the full scan every time,
293
+ // forever.
294
+ const key = want + '::' + projectsRoot;
295
+ if (dirCache.has(key)) return dirCache.get(key);
296
+ const found = findTranscriptDir(want, projectsRoot);
297
+ // A HIT is cached forever — a project directory does not move. A MISS is
298
+ // not cached at all: the board is the page an operator leaves open
299
+ // overnight, and it is routinely started in a repo whose first session has
300
+ // not run yet. Remembering "no transcripts" for the life of that process
301
+ // would keep the Spend section hidden after the transcripts appear, with
302
+ // nothing on the page saying why.
303
+ if (found !== null) dirCache.set(key, found);
304
+ return found;
305
+ }
306
+
307
+ function findTranscriptDir(want, projectsRoot) {
308
+ const direct = join(projectsRoot, want.split(sep).join('-'));
309
+ if (existsSync(direct)) return direct;
310
+ if (!existsSync(projectsRoot)) return null;
311
+ for (const entry of readdirSync(projectsRoot, { withFileTypes: true })) {
312
+ if (!entry.isDirectory()) continue;
313
+ const dir = join(projectsRoot, entry.name);
314
+ let sessions;
315
+ try {
316
+ sessions = readdirSync(dir).filter((f) => f.endsWith('.jsonl'));
317
+ } catch {
318
+ continue;
319
+ }
320
+ for (const session of sessions) {
321
+ let matched = false;
322
+ try {
323
+ forEachLine(
324
+ join(dir, session),
325
+ (line) => {
326
+ if (line === '' || line.charCodeAt(0) !== 123) return true;
327
+ try {
328
+ if (field(JSON.parse(line), 'cwd') === want) {
329
+ matched = true;
330
+ return false; // stop reading this file
331
+ }
332
+ } catch {
333
+ /* a malformed line is not a reason to reject the directory */
334
+ }
335
+ return true;
336
+ },
337
+ { maxBytes: PROBE_BYTES }
338
+ );
339
+ } catch {
340
+ continue;
341
+ }
342
+ if (matched) return dir;
343
+ }
344
+ }
345
+ return null;
346
+ }
347
+
348
+ /** Every transcript belonging to this repo: the sessions and their agents. */
349
+ export function listSources(transcriptDir, sessionFilter) {
350
+ const out = [];
351
+ let sessions;
352
+ try {
353
+ sessions = readdirSync(transcriptDir).filter((f) => f.endsWith('.jsonl'));
354
+ } catch {
355
+ return out;
356
+ }
357
+ for (const file of sessions.sort()) {
358
+ const id = basename(file, '.jsonl');
359
+ if (sessionFilter && id !== sessionFilter) continue;
360
+ out.push({ kind: CONDUCTOR, session: id, path: join(transcriptDir, file) });
361
+ const agentDir = join(transcriptDir, id, 'subagents');
362
+ let agents;
363
+ try {
364
+ agents = readdirSync(agentDir).filter((f) => f.endsWith('.jsonl'));
365
+ } catch {
366
+ continue;
367
+ }
368
+ for (const agentFile of agents.sort()) {
369
+ const agentId = basename(agentFile, '.jsonl');
370
+ let meta = {};
371
+ try {
372
+ meta = JSON.parse(readFileSync(join(agentDir, `${agentId}.meta.json`), 'utf8'));
373
+ } catch {
374
+ /* an agent with no meta is still spend; it just cannot be attributed */
375
+ }
376
+ const description = typeof field(meta, 'description') === 'string' ? field(meta, 'description') : '';
377
+ const ticketMatch = TICKET_IN_DESCRIPTION_RE.exec(description);
378
+ out.push({
379
+ kind: 'agent',
380
+ session: id,
381
+ path: join(agentDir, agentFile),
382
+ agent_id: agentId,
383
+ agent_type: typeof field(meta, 'agentType') === 'string' ? field(meta, 'agentType') : 'unknown',
384
+ ticket: ticketMatch === null ? null : ticketMatch[1],
385
+ });
386
+ }
387
+ }
388
+ return out;
389
+ }
390
+
391
+ /**
392
+ * Scan every source, reusing the previous run's numbers for files whose size
393
+ * and mtime are unchanged.
394
+ *
395
+ * This is the difference between a page that refreshes every thirty seconds
396
+ * and a page that re-reads sixty megabytes every thirty seconds. A finished
397
+ * agent's transcript never changes again, so in practice only the running
398
+ * session's own file is ever re-read.
399
+ */
400
+ export function scanAll(sources, cache) {
401
+ const previous = new Map();
402
+ for (const entry of cache?.sources ?? []) previous.set(entry.path, entry);
403
+ const scanned = [];
404
+ let unreadable = 0;
405
+ let reused = 0;
406
+ for (const source of sources) {
407
+ let stat;
408
+ try {
409
+ stat = statSync(source.path);
410
+ } catch {
411
+ unreadable += 1;
412
+ continue;
413
+ }
414
+ const before = previous.get(source.path);
415
+ if (before && before.mtime_ms === stat.mtimeMs && before.size === stat.size && before.by_model) {
416
+ reused += 1;
417
+ scanned.push({
418
+ ...source,
419
+ mtime_ms: stat.mtimeMs,
420
+ size: stat.size,
421
+ by_model: before.by_model,
422
+ last_ts: before.last_ts ?? null,
423
+ // Carried through the cache too: a damaged transcript stays damaged,
424
+ // and a gap that disappears on the second render is worse than one
425
+ // that was never reported.
426
+ malformed: before.malformed ?? 0,
427
+ skipped_lines: before.skipped_lines ?? 0,
428
+ });
429
+ continue;
430
+ }
431
+ let result;
432
+ try {
433
+ result = scanTranscript(source.path);
434
+ } catch {
435
+ unreadable += 1;
436
+ continue;
437
+ }
438
+ scanned.push({
439
+ ...source,
440
+ mtime_ms: stat.mtimeMs,
441
+ size: stat.size,
442
+ by_model: result.byModel,
443
+ last_ts: result.lastTs,
444
+ malformed: result.malformed,
445
+ skipped_lines: result.skippedLines,
446
+ });
447
+ }
448
+ return { scanned, unreadable, reused };
449
+ }
450
+
451
+ function bucket(table, key) {
452
+ if (table[key] === undefined) table[key] = { byModel: Object.create(null), counters: emptyCounters() };
453
+ return table[key];
454
+ }
455
+
456
+ function intoBucket(target, model, counters) {
457
+ if (target.byModel[model] === undefined) target.byModel[model] = emptyCounters();
458
+ addCounters(target.byModel[model], counters);
459
+ addCounters(target.counters, counters);
460
+ }
461
+
462
+ /** Sorted rows, biggest first, with a stable name tiebreak for byte-equal runs. */
463
+ function rows(table, nameKey, models) {
464
+ return Object.entries(table)
465
+ .map(([name, entry]) => ({
466
+ [nameKey]: name,
467
+ ...entry.counters,
468
+ tokens: tokensOf(entry.counters),
469
+ usd: costOfTable(entry.byModel, models),
470
+ }))
471
+ .sort((a, b) => b.tokens - a.tokens || String(a[nameKey]).localeCompare(String(b[nameKey])));
472
+ }
473
+
474
+ /**
475
+ * The report, from scanned sources and a rate card. Pure — every input is an
476
+ * argument, so the shape is testable without touching a filesystem.
477
+ */
478
+ export function rollup(scanned, pricing, extra = {}) {
479
+ const { models, rate_card: rateCard } = pricing;
480
+ const totals = emptyCounters();
481
+ const totalsByModel = Object.create(null);
482
+ const conductor = { byModel: Object.create(null), counters: emptyCounters() };
483
+ const byModel = Object.create(null);
484
+ const byAgentType = Object.create(null);
485
+ const byTicket = Object.create(null);
486
+ const unpriced = new Set();
487
+ let agentTranscripts = 0;
488
+ let attributed = 0;
489
+ let newestTs = null;
490
+ let malformed = 0;
491
+ let skippedLines = 0;
492
+
493
+ for (const source of scanned) {
494
+ malformed += source.malformed ?? 0;
495
+ skippedLines += source.skipped_lines ?? 0;
496
+ if (source.kind === 'agent') agentTranscripts += 1;
497
+ if (source.kind === 'agent' && source.ticket !== null) attributed += 1;
498
+ if (typeof source.last_ts === 'string' && (newestTs === null || source.last_ts > newestTs)) {
499
+ newestTs = source.last_ts;
500
+ }
501
+ for (const [model, counters] of Object.entries(source.by_model)) {
502
+ addCounters(totals, counters);
503
+ if (totalsByModel[model] === undefined) totalsByModel[model] = emptyCounters();
504
+ addCounters(totalsByModel[model], counters);
505
+ // Only a model that actually billed something is worth naming: the
506
+ // platform emits `<synthetic>` records carrying zero tokens, and a
507
+ // permanent warning about a model that cannot cost anything is noise
508
+ // that teaches operators to ignore the line.
509
+ if (!Object.prototype.hasOwnProperty.call(models, model) && tokensOf(counters) > 0) unpriced.add(model);
510
+ intoBucket(bucket(byModel, model), model, counters);
511
+ if (source.kind === CONDUCTOR) {
512
+ intoBucket(conductor, model, counters);
513
+ intoBucket(bucket(byAgentType, CONDUCTOR), model, counters);
514
+ intoBucket(bucket(byTicket, CONDUCTOR), model, counters);
515
+ } else {
516
+ intoBucket(bucket(byAgentType, source.agent_type), model, counters);
517
+ intoBucket(bucket(byTicket, source.ticket ?? 'unattributed'), model, counters);
518
+ }
519
+ }
520
+ }
521
+
522
+ const conductorUsd = costOfTable(conductor.byModel, models);
523
+ const totalUsd = costOfTable(totalsByModel, models);
524
+ return {
525
+ schema: COST_SCHEMA,
526
+ rate_card: rateCard,
527
+ as_of: newestTs,
528
+ totals: {
529
+ ...totals,
530
+ tokens: tokensOf(totals),
531
+ usd: totalUsd,
532
+ // The share an operator must see next to any per-ticket figure: the
533
+ // conductor's own context is not attributable to a ticket, and omitting
534
+ // it silently would present a fraction of the bill as the cost of the
535
+ // work.
536
+ //
537
+ // Measured in TOKENS, never dollars, and not as a matter of taste: a
538
+ // partial rate card prices only some models, so a dollar share is a
539
+ // ratio over whichever subset happened to be priced. The same tree
540
+ // reported 86% by tokens and 99% by dollars while one model lacked a
541
+ // rate. Tokens are always complete, so the number never moves for a
542
+ // reason that has nothing to do with the work.
543
+ conductor_token_share:
544
+ tokensOf(totals) > 0 ? Math.round((tokensOf(conductor.counters) / tokensOf(totals)) * 100) : 0,
545
+ conductor_usd: conductorUsd,
546
+ },
547
+ composition: PRICING_RATE_KEYS.map((key) => ({
548
+ kind: key,
549
+ tokens: totals[key],
550
+ usd: costOfTable(
551
+ Object.fromEntries(
552
+ Object.entries(totalsByModel).map(([model, counters]) => [
553
+ model,
554
+ { ...emptyCounters(), [key]: counters[key] },
555
+ ])
556
+ ),
557
+ models
558
+ ),
559
+ })),
560
+ by_model: rows(byModel, 'model', models),
561
+ by_agent_type: rows(byAgentType, 'agent_type', models),
562
+ by_ticket: rows(byTicket, 'ticket', models),
563
+ unpriced: [...unpriced].sort(),
564
+ coverage: {
565
+ agent_transcripts: agentTranscripts,
566
+ attributed,
567
+ unattributed: agentTranscripts - attributed,
568
+ unreadable: extra.unreadable ?? 0,
569
+ // Records the reader saw and could not use. These were counted from the
570
+ // first version and then dropped on the floor between the scanner and
571
+ // the report — which made every failure mode of a half-written
572
+ // transcript invisible, in the one feature whose stated property is
573
+ // that gaps are reported rather than zeroed. A live conductor's own
574
+ // file is appended to WHILE it is read, so a truncated tail is the
575
+ // normal case, not an exotic one.
576
+ malformed,
577
+ skipped_lines: skippedLines,
578
+ reused_from_cache: extra.reused ?? 0,
579
+ },
580
+ };
581
+ }
582
+
583
+ /* ------------------------------- rendering ------------------------------- */
584
+
585
+ /** An amount that rounds to nothing still cost something; say so rather than
586
+ * printing `$0.00`, which reads as free. */
587
+ const money = (usd) => (usd === null ? '—' : usd > 0 && usd < 0.01 ? '<$0.01' : `$${usd.toFixed(2)}`);
588
+
589
+ function tokens(n) {
590
+ if (n >= 1e9) return `${(n / 1e9).toFixed(2)} B`;
591
+ if (n >= 1e6) return `${(n / 1e6).toFixed(1)} M`;
592
+ if (n >= 1e3) return `${(n / 1e3).toFixed(1)} k`;
593
+ return String(n);
594
+ }
595
+
596
+ function table(headers, body) {
597
+ const widths = headers.map((h, i) => Math.max(h.length, ...body.map((r) => String(r[i]).length)));
598
+ const line = (cells) =>
599
+ ' ' + cells.map((c, i) => (i === 0 ? String(c).padEnd(widths[i]) : String(c).padStart(widths[i]))).join(' ');
600
+ return [line(headers), ...body.map(line)].join('\n');
601
+ }
602
+
603
+ /** The human report. */
604
+ export function renderReport(report) {
605
+ const out = [];
606
+ const card = report.rate_card === null ? 'no rate card — tokens only' : `rate card ${report.rate_card}`;
607
+ out.push(`Spend — ${tokens(report.totals.tokens)} tokens, ${money(report.totals.usd)} (${card})`);
608
+ out.push('');
609
+ out.push(
610
+ table(
611
+ ['what', 'tokens', 'usd'],
612
+ report.composition.map((c) => [c.kind.replace('_', ' '), tokens(c.tokens), money(c.usd)])
613
+ )
614
+ );
615
+ for (const [title, key, rowsOf] of [
616
+ ['By model', 'model', report.by_model],
617
+ ['By agent type', 'agent_type', report.by_agent_type],
618
+ ['By ticket', 'ticket', report.by_ticket],
619
+ ]) {
620
+ out.push('');
621
+ out.push(title);
622
+ out.push(
623
+ table(
624
+ [key.replace('_', ' '), 'requests', 'tokens', 'usd'],
625
+ rowsOf.map((r) => [r[key], String(r.requests), tokens(r.tokens), money(r.usd)])
626
+ )
627
+ );
628
+ }
629
+ out.push('');
630
+ const c = report.coverage;
631
+ out.push(
632
+ `Coverage: ${c.attributed} of ${c.agent_transcripts} agent transcripts carry a ticket; ` +
633
+ `${c.unattributed} unattributed, ${c.unreadable} unreadable.`
634
+ );
635
+ if ((c.malformed ?? 0) > 0 || (c.skipped_lines ?? 0) > 0) {
636
+ out.push(
637
+ `Records this reader could not use: ${c.malformed ?? 0} unparseable, ${c.skipped_lines ?? 0} over the line cap. ` +
638
+ 'Their tokens are missing from every number above — a transcript being appended to while it is read ends in a partial record.'
639
+ );
640
+ }
641
+ out.push(
642
+ `Conductor overhead: ${report.totals.conductor_token_share}% of tokens — not attributable to any ticket.`
643
+ );
644
+ if (report.unpriced.length > 0) {
645
+ out.push(`Unpriced models (counted in tokens, absent from every amount): ${report.unpriced.join(', ')}`);
646
+ }
647
+ return out.join('\n') + '\n';
648
+ }
649
+
650
+ /** The sidecar bytes: invisibles escaped, never removed, exactly like board.json. */
651
+ export function costJson(report) {
652
+ return jsonEscapeInvisible(JSON.stringify(report, null, 2)) + '\n';
653
+ }
654
+
655
+ /* ---------------------------------- CLI ---------------------------------- */
656
+
657
+ function loadPricing(tyranDir) {
658
+ try {
659
+ return pricingOf(parse(readFileSync(join(tyranDir, 'config.yaml'), 'utf8')));
660
+ } catch {
661
+ // A config that will not parse is doctor's problem to report, not this
662
+ // reader's problem to refuse over: tokens are still worth counting.
663
+ return { rate_card: null, models: Object.create(null) };
664
+ }
665
+ }
666
+
667
+ function readCache(path) {
668
+ try {
669
+ const cached = JSON.parse(readFileSync(path, 'utf8'));
670
+ return cached && cached.schema === COST_SCHEMA ? cached : null;
671
+ } catch {
672
+ return null;
673
+ }
674
+ }
675
+
676
+ function writeAtomic(path, text) {
677
+ mkdirSync(dirname(path), { recursive: true });
678
+ // The temp name carries the pid: two writers sharing one fixed `.tmp` can
679
+ // rename a half-written file over the real one, and the board server and a
680
+ // hand-run CLI are exactly two writers.
681
+ const tmp = path + '.' + String(process.pid) + '.tmp';
682
+ writeFileSync(tmp, text);
683
+ renameSync(tmp, path);
684
+ }
685
+
686
+ /** Build the report for a repo. Exported so the board server reuses it. */
687
+ export function costReport({ tyranDir, projectsRoot, session = null, repoRoot = null } = {}) {
688
+ const root = repoRoot ?? resolve(tyranDir, '..');
689
+ const dir = transcriptDirFor(root, projectsRoot ?? join(homedir(), '.claude', 'projects'));
690
+ const pricing = loadPricing(tyranDir);
691
+ if (dir === null) {
692
+ const empty = rollup([], pricing, {});
693
+ empty.transcripts_found = false;
694
+ return empty;
695
+ }
696
+ const cachePath = join(tyranDir, 'state', COST_FILE);
697
+ const { scanned, unreadable, reused } = scanAll(listSources(dir, session), readCache(cachePath));
698
+ const report = rollup(scanned, pricing, { unreadable, reused });
699
+ report.transcripts_found = true;
700
+ report.session = session;
701
+ report.sources = scanned.map((s) => ({
702
+ path: s.path,
703
+ kind: s.kind,
704
+ mtime_ms: s.mtime_ms,
705
+ size: s.size,
706
+ agent_type: s.agent_type ?? null,
707
+ ticket: s.ticket ?? null,
708
+ last_ts: s.last_ts ?? null,
709
+ malformed: s.malformed ?? 0,
710
+ skipped_lines: s.skipped_lines ?? 0,
711
+ by_model: s.by_model,
712
+ }));
713
+ // Persisting is the whole point of the cache, and it has to happen HERE
714
+ // rather than only in the `--json` branch: the board server calls this per
715
+ // request and refreshes every 30 s, so a cache only the CLI ever wrote left
716
+ // the served page re-reading every transcript forever — measured at 1.15 s
717
+ // per request, with `reused_from_cache` stuck at zero. A filtered run is
718
+ // never persisted: it would poison the full report with a partial one.
719
+ // `cache_written` is reported rather than swallowed. For the SERVED page a
720
+ // failed write is only a slow report, but `--json`'s entire contract is
721
+ // "the sidecar now exists, here is its path" — printing that path over a
722
+ // file that was never written, and exiting 0, turns a permission error into
723
+ // a downstream failure with a healthy-looking upstream.
724
+ report.cache_written = false;
725
+ if (session === null) {
726
+ // Set BEFORE serialising, so the field is true of the file that ends up
727
+ // on disk. Setting it afterwards left every persisted copy reading
728
+ // `false` on a cache that had written perfectly well — a diagnostic that
729
+ // lies to whoever opens the file.
730
+ report.cache_written = true;
731
+ try {
732
+ writeAtomic(cachePath, costJson(report));
733
+ } catch (err) {
734
+ report.cache_written = false;
735
+ report.cache_error = String(err?.message ?? err);
736
+ }
737
+ }
738
+ return report;
739
+ }
740
+
741
+ function parseArgs(argv) {
742
+ const flags = { dir: '.tyran', session: null, projects: null, json: false };
743
+ for (let i = 0; i < argv.length; i += 1) {
744
+ const arg = argv[i];
745
+ if (arg === '--json') flags.json = true;
746
+ else if (arg === '--dir' || arg === '--session' || arg === '--projects') {
747
+ const value = argv[i + 1];
748
+ if (value === undefined || value.startsWith('--')) throw new UsageError(`${arg} needs a value`);
749
+ flags[arg.slice(2)] = value;
750
+ i += 1;
751
+ } else throw new UsageError(`unknown argument: ${arg}`);
752
+ }
753
+ return flags;
754
+ }
755
+
756
+ function main(argv) {
757
+ let flags;
758
+ try {
759
+ flags = parseArgs(argv);
760
+ } catch (err) {
761
+ console.error(String(err.message ?? err));
762
+ console.error('usage: cost.mjs [--dir <.tyran>] [--session <id>] [--projects <dir>] [--json]');
763
+ return 2;
764
+ }
765
+ const tyranDir = resolve(flags.dir);
766
+ if (!existsSync(tyranDir)) {
767
+ console.error(`cost: no such directory: ${tyranDir}`);
768
+ return 2;
769
+ }
770
+ const report = costReport({ tyranDir, projectsRoot: flags.projects, session: flags.session });
771
+ if (report.transcripts_found === false) {
772
+ console.error(
773
+ 'cost: no transcripts found for this repo under the Claude Code projects directory.\n' +
774
+ 'Spend is read from the transcripts the platform writes; nothing here estimates it.'
775
+ );
776
+ return 2;
777
+ }
778
+ if (flags.json) {
779
+ // Refused rather than written: the sidecar is what the board reads, and a
780
+ // one-session file carrying `totals: 0` would overwrite the full report
781
+ // with a measurement that looks complete and is not.
782
+ if (flags.session !== null) {
783
+ console.error('cost: --session cannot be combined with --json — the sidecar must cover every session.');
784
+ return 2;
785
+ }
786
+ if (report.cache_written !== true) {
787
+ console.error(`cost: could not write the sidecar: ${report.cache_error ?? 'unknown error'}`);
788
+ return 2;
789
+ }
790
+ console.log(join(tyranDir, 'state', COST_FILE));
791
+ } else {
792
+ process.stdout.write(renderReport(report));
793
+ }
794
+ return 0;
795
+ }
796
+
797
+ function canonicalPath(path) {
798
+ const abs = resolve(path);
799
+ try {
800
+ return realpathSync(abs);
801
+ } catch {
802
+ return abs;
803
+ }
804
+ }
805
+
806
+ function isMainModule(moduleUrl) {
807
+ if (!process.argv[1]) return false;
808
+ return canonicalPath(process.argv[1]) === canonicalPath(fileURLToPath(moduleUrl));
809
+ }
810
+
811
+ if (isMainModule(import.meta.url)) process.exit(main(process.argv.slice(2)));