@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.
- package/.claude-plugin/marketplace.json +1 -1
- package/.claude-plugin/plugin.json +1 -1
- package/CHANGELOG.md +74 -0
- package/README.md +6 -1
- package/bin/tyran.mjs +4 -0
- package/package.json +1 -1
- package/scripts/board-html.mjs +194 -0
- package/scripts/board.mjs +31 -2
- package/scripts/cost.mjs +811 -0
- package/scripts/doctor.mjs +4 -0
- package/scripts/scan-repo.mjs +5 -0
- package/scripts/schema.mjs +89 -1
- package/templates/config.yaml +21 -0
package/scripts/cost.mjs
ADDED
|
@@ -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)));
|