limitcast 0.11.4 → 0.12.0
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/LICENSE +95 -21
- package/README.md +11 -6
- package/bin/limitcast.mjs +170 -35
- package/package.json +2 -2
- package/src/grok.mjs +585 -0
- package/src/guard.mjs +15 -5
- package/src/install.mjs +17 -4
- package/src/report.mjs +15 -8
- package/src/subagents.mjs +27 -0
- package/src/toolcheck.mjs +83 -0
- package/src/where.mjs +445 -0
package/src/where.mjs
ADDED
|
@@ -0,0 +1,445 @@
|
|
|
1
|
+
// @ts-check
|
|
2
|
+
import { createReadStream, existsSync, mkdirSync, readFileSync, statSync, writeFileSync } from 'node:fs';
|
|
3
|
+
import { homedir } from 'node:os';
|
|
4
|
+
import { join } from 'node:path';
|
|
5
|
+
import { createInterface } from 'node:readline';
|
|
6
|
+
import { fmt } from './report.mjs';
|
|
7
|
+
import { stateDir } from './store.mjs';
|
|
8
|
+
import { BIG_RESULT, tipFor, toolKey } from './toolcheck.mjs';
|
|
9
|
+
import { jsonlFiles } from './usage.mjs';
|
|
10
|
+
|
|
11
|
+
// `limitcast report --why` (Pro): where the new tokens went, which is what moves the limit (cached reads barely count).
|
|
12
|
+
// A model call's new tokens are input + cache writes + output. The input of call i is what entered the context since
|
|
13
|
+
// call i-1: its own output (written to the cache) plus the tool results it asked for plus your messages. So the input
|
|
14
|
+
// of call i, less call i-1's output, is attributed to the tools call i-1 used. Claude Code transcripts only.
|
|
15
|
+
|
|
16
|
+
/** @typedef {{t:number, input:number, cacheWrite:number, cacheRead:number, output:number, tools:string[], side:boolean, entry:string, project:string, model?:string, prompt?:string, agentType?:string}} Call
|
|
17
|
+
* prompt: first words of the session's first message, on its first main-thread call; agentType: a subagent transcript's type, on its first call */
|
|
18
|
+
|
|
19
|
+
const COLD_MIN = 100_000; // prompt size from which a missed cache is called a rebuild after idle
|
|
20
|
+
const NO_TOOL = '(your messages)';
|
|
21
|
+
const TIP_MIN_PER_CALL = 2000; // a tip is only worth showing for a source whose results average at least this many new tokens
|
|
22
|
+
|
|
23
|
+
/**
|
|
24
|
+
* The first words of a transcript line that is the session's own first message, else undefined.
|
|
25
|
+
* @param {string} line
|
|
26
|
+
*/
|
|
27
|
+
function firstPrompt(line) {
|
|
28
|
+
try {
|
|
29
|
+
const ev = JSON.parse(line);
|
|
30
|
+
if (ev?.type !== 'user' || ev.isSidechain || ev.isMeta) return undefined;
|
|
31
|
+
const c = ev.message?.content;
|
|
32
|
+
const text = typeof c === 'string' ? c : Array.isArray(c) ? c.map((b) => (b?.type === 'text' ? b.text : '')).join(' ') : '';
|
|
33
|
+
return text.replace(/\s+/g, ' ').trim().slice(0, 80) || undefined;
|
|
34
|
+
} catch {
|
|
35
|
+
return undefined;
|
|
36
|
+
}
|
|
37
|
+
}
|
|
38
|
+
|
|
39
|
+
/**
|
|
40
|
+
* One transcript's model calls in order. A call's usage repeats on every content block it streamed, so calls are
|
|
41
|
+
* merged by message id and their tool_use names collected. The first main-thread call also carries the session's
|
|
42
|
+
* first words (`prompt`), which tell a scheduled job's runs apart.
|
|
43
|
+
* @param {string} file
|
|
44
|
+
* @returns {Promise<Call[]>}
|
|
45
|
+
*/
|
|
46
|
+
export async function readCalls(file) {
|
|
47
|
+
/** @type {Map<string, Call>} */
|
|
48
|
+
const calls = new Map();
|
|
49
|
+
/** @type {string|undefined} */
|
|
50
|
+
let prompt;
|
|
51
|
+
for await (const line of createInterface({ input: createReadStream(file), crlfDelay: Infinity })) {
|
|
52
|
+
if (prompt === undefined && line.includes('"type":"user"')) prompt = firstPrompt(line);
|
|
53
|
+
if (!line.includes('"usage"')) continue;
|
|
54
|
+
let ev;
|
|
55
|
+
try {
|
|
56
|
+
ev = JSON.parse(line);
|
|
57
|
+
} catch {
|
|
58
|
+
continue;
|
|
59
|
+
}
|
|
60
|
+
const m = ev?.message;
|
|
61
|
+
const u = m?.usage;
|
|
62
|
+
const t = Date.parse(ev?.timestamp);
|
|
63
|
+
if (ev?.type !== 'assistant' || !u || !Number.isFinite(t)) continue;
|
|
64
|
+
const id = `${m.id ?? ''}:${ev.requestId ?? ''}`;
|
|
65
|
+
let c = calls.get(id);
|
|
66
|
+
if (!c || id === ':') {
|
|
67
|
+
c = {
|
|
68
|
+
t,
|
|
69
|
+
input: u.input_tokens ?? 0,
|
|
70
|
+
cacheWrite: u.cache_creation_input_tokens ?? 0,
|
|
71
|
+
cacheRead: u.cache_read_input_tokens ?? 0,
|
|
72
|
+
output: u.output_tokens ?? 0,
|
|
73
|
+
tools: [],
|
|
74
|
+
side: !!ev.isSidechain,
|
|
75
|
+
entry: String(ev.entrypoint ?? ''),
|
|
76
|
+
project: ev.cwd ?? '',
|
|
77
|
+
model: String(m.model ?? ''),
|
|
78
|
+
};
|
|
79
|
+
calls.set(id === ':' ? `line${calls.size}` : id, c);
|
|
80
|
+
}
|
|
81
|
+
for (const b of Array.isArray(m.content) ? m.content : []) {
|
|
82
|
+
if (b?.type === 'tool_use' && typeof b.name === 'string' && !c.tools.includes(toolKey(b.name))) c.tools.push(toolKey(b.name));
|
|
83
|
+
}
|
|
84
|
+
}
|
|
85
|
+
const all = [...calls.values()];
|
|
86
|
+
const first = all.find((c) => !c.side);
|
|
87
|
+
if (first && prompt) first.prompt = prompt;
|
|
88
|
+
// A subagent's transcript has its type in a file next to it: agent-<id>.jsonl and agent-<id>.meta.json.
|
|
89
|
+
if (all.length && file.includes('/subagents/')) {
|
|
90
|
+
try {
|
|
91
|
+
const type = JSON.parse(readFileSync(file.replace(/\.jsonl$/, '.meta.json'), 'utf8')).agentType;
|
|
92
|
+
if (typeof type === 'string') all[0].agentType = type;
|
|
93
|
+
} catch {
|
|
94
|
+
/* no meta file: the type stays unknown */
|
|
95
|
+
}
|
|
96
|
+
}
|
|
97
|
+
return all;
|
|
98
|
+
}
|
|
99
|
+
|
|
100
|
+
/**
|
|
101
|
+
* Sort a week of calls into categories. The categories add up to `total` exactly.
|
|
102
|
+
* @param {Call[][]} sessions one entry per transcript, calls in order
|
|
103
|
+
* @param {number} since epoch ms; earlier calls are skipped (they still serve as the previous call)
|
|
104
|
+
*/
|
|
105
|
+
export function attribute(sessions, since = 0) {
|
|
106
|
+
const r = {
|
|
107
|
+
total: 0,
|
|
108
|
+
subagents: 0,
|
|
109
|
+
startInteractive: 0,
|
|
110
|
+
startHeadless: 0,
|
|
111
|
+
sessionsInteractive: 0,
|
|
112
|
+
sessionsHeadless: 0,
|
|
113
|
+
rebuilds: 0,
|
|
114
|
+
output: 0,
|
|
115
|
+
other: 0,
|
|
116
|
+
/** @type {Map<string, {tokens:number, calls:number}>} */
|
|
117
|
+
tools: new Map(),
|
|
118
|
+
/** @type {{tokens:number, tool:string, t:number, project:string}[]} */
|
|
119
|
+
steps: [],
|
|
120
|
+
/** @type {{t:number, tokens:number, size:number, calls:number, prompt:string, project:string, entry:string}[]} headless session starts: when, new tokens, and the whole starting prompt (cached or not) */
|
|
121
|
+
starts: [],
|
|
122
|
+
/** @type {Map<string, number>} every new token, by model */
|
|
123
|
+
byModel: new Map(),
|
|
124
|
+
/** @type {Map<string, {type:string, model:string, tokens:number, runs:number}>} subagent new tokens, by type and model */
|
|
125
|
+
subagentsBy: new Map(),
|
|
126
|
+
};
|
|
127
|
+
/** @param {Call} c */
|
|
128
|
+
const byModel = (c) => {
|
|
129
|
+
const k = c.model || '(unknown)';
|
|
130
|
+
r.byModel.set(k, (r.byModel.get(k) ?? 0) + c.input + c.cacheWrite + c.output);
|
|
131
|
+
};
|
|
132
|
+
for (const calls of sessions) {
|
|
133
|
+
const main = calls.filter((c) => !c.side);
|
|
134
|
+
const type = calls.find((c) => c.agentType)?.agentType ?? '(unknown)';
|
|
135
|
+
const counted = new Set(); // one run per transcript for each type and model
|
|
136
|
+
for (const c of calls.filter((x) => x.side && x.t >= since)) {
|
|
137
|
+
const n = c.input + c.cacheWrite + c.output;
|
|
138
|
+
r.total += n;
|
|
139
|
+
r.subagents += n;
|
|
140
|
+
byModel(c);
|
|
141
|
+
const k = `${type}\0${c.model || '(unknown)'}`;
|
|
142
|
+
const e = r.subagentsBy.get(k) ?? { type, model: c.model || '(unknown)', tokens: 0, runs: 0 };
|
|
143
|
+
e.tokens += n;
|
|
144
|
+
if (!counted.has(k)) {
|
|
145
|
+
counted.add(k);
|
|
146
|
+
e.runs++;
|
|
147
|
+
}
|
|
148
|
+
r.subagentsBy.set(k, e);
|
|
149
|
+
}
|
|
150
|
+
main.forEach((c, i) => {
|
|
151
|
+
if (c.t < since) return;
|
|
152
|
+
r.total += c.input + c.cacheWrite + c.output;
|
|
153
|
+
byModel(c);
|
|
154
|
+
r.output += c.output;
|
|
155
|
+
if (i === 0) {
|
|
156
|
+
const interactive = c.entry === 'cli';
|
|
157
|
+
r[interactive ? 'startInteractive' : 'startHeadless'] += c.input + c.cacheWrite;
|
|
158
|
+
r[interactive ? 'sessionsInteractive' : 'sessionsHeadless']++;
|
|
159
|
+
if (!interactive) {
|
|
160
|
+
r.starts.push({
|
|
161
|
+
t: c.t,
|
|
162
|
+
tokens: c.input + c.cacheWrite,
|
|
163
|
+
size: c.input + c.cacheWrite + c.cacheRead,
|
|
164
|
+
calls: main.filter((x) => x.t >= since).length,
|
|
165
|
+
prompt: c.prompt ?? '',
|
|
166
|
+
project: c.project,
|
|
167
|
+
entry: c.entry,
|
|
168
|
+
});
|
|
169
|
+
}
|
|
170
|
+
return;
|
|
171
|
+
}
|
|
172
|
+
const p = main[i - 1];
|
|
173
|
+
r.output += p.output; // the previous call's output, written to the cache again as this call's input
|
|
174
|
+
const added = c.input + c.cacheWrite - p.output;
|
|
175
|
+
const prompt = p.input + p.cacheRead + p.cacheWrite;
|
|
176
|
+
if (added <= 0) r.other += added;
|
|
177
|
+
else if (prompt > COLD_MIN && c.cacheRead < prompt / 2) r.rebuilds += added;
|
|
178
|
+
else {
|
|
179
|
+
const tool = p.tools.length > 1 ? 'several tools in one step' : (p.tools[0] ?? NO_TOOL);
|
|
180
|
+
const e = r.tools.get(tool) ?? { tokens: 0, calls: 0 };
|
|
181
|
+
e.tokens += added;
|
|
182
|
+
e.calls++;
|
|
183
|
+
r.tools.set(tool, e);
|
|
184
|
+
r.steps.push({ tokens: added, tool, t: c.t, project: c.project });
|
|
185
|
+
}
|
|
186
|
+
});
|
|
187
|
+
}
|
|
188
|
+
return r;
|
|
189
|
+
}
|
|
190
|
+
|
|
191
|
+
/**
|
|
192
|
+
* Markdown: where the new tokens went, tool results by source, the largest single steps.
|
|
193
|
+
* @param {ReturnType<typeof attribute>} r
|
|
194
|
+
* @param {{since:number, now:number, calib?:{fresh:number}|null}} o calib.fresh: % of a 5-hour window per million new tokens
|
|
195
|
+
*/
|
|
196
|
+
export function whyReport(r, { since, now, calib }) {
|
|
197
|
+
const day = (/** @type {number} */ t) => new Date(t).toLocaleDateString('sv-SE');
|
|
198
|
+
const lines = ['# limitcast: where your new tokens went', '', `${day(since)} to ${day(now)} · Claude Code only`, ''];
|
|
199
|
+
if (!r.total) return [...lines, 'No Claude Code usage in this period.'].join('\n');
|
|
200
|
+
const toolTokens = [...r.tools.values()].reduce((a, e) => a + e.tokens, 0);
|
|
201
|
+
const windows = (/** @type {number} */ n) => {
|
|
202
|
+
if (!calib) return '';
|
|
203
|
+
const w = ((n / 1e6) * calib.fresh) / 100;
|
|
204
|
+
return ` | ≈${w < 10 ? w.toFixed(1) : Math.round(w)}`;
|
|
205
|
+
};
|
|
206
|
+
const share = (/** @type {number} */ n) => `${Math.round((n / r.total) * 100)}%`;
|
|
207
|
+
const rows = /** @type {[string, number][]} */ ([
|
|
208
|
+
['Subagents', r.subagents],
|
|
209
|
+
[`Session starts, interactive (${r.sessionsInteractive})`, r.startInteractive],
|
|
210
|
+
[`Session starts, headless runs (${r.sessionsHeadless})`, r.startHeadless],
|
|
211
|
+
['Cache rebuilds after an idle pause', r.rebuilds],
|
|
212
|
+
['Tool results', toolTokens],
|
|
213
|
+
['Model output (generated, then cached on the next call)', r.output],
|
|
214
|
+
['Other', r.other],
|
|
215
|
+
])
|
|
216
|
+
.filter(([, n]) => n > 0)
|
|
217
|
+
.sort((a, b) => b[1] - a[1]);
|
|
218
|
+
lines.push(`${fmt(r.total)} new tokens (input, cache writes and output; cached reads are left out).`, '');
|
|
219
|
+
lines.push(`| where | new tokens | share${calib ? ' | 5-hour windows' : ''} |`, `|---|---:|---:${calib ? '|---:' : ''}|`);
|
|
220
|
+
for (const [k, n] of rows) lines.push(`| ${k} | ${fmt(n)} | ${share(n)}${windows(n)} |`);
|
|
221
|
+
if (r.starts.length) lines.push('', 'Headless runs by job: `limitcast report --jobs`.');
|
|
222
|
+
|
|
223
|
+
if (r.subagentsBy.size) {
|
|
224
|
+
lines.push(
|
|
225
|
+
'',
|
|
226
|
+
'## Subagents by type and model',
|
|
227
|
+
'',
|
|
228
|
+
'| type | model | runs | new tokens | share of subagent tokens | per run |',
|
|
229
|
+
'|---|---|---:|---:|---:|---:|',
|
|
230
|
+
);
|
|
231
|
+
for (const e of [...r.subagentsBy.values()].sort((a, b) => b.tokens - a.tokens).slice(0, 8)) {
|
|
232
|
+
lines.push(
|
|
233
|
+
`| ${e.type} | ${e.model} | ${e.runs} | ${fmt(e.tokens)} | ${Math.round((e.tokens / r.subagents) * 100)}% | ${fmt(Math.round(e.tokens / e.runs))} |`,
|
|
234
|
+
);
|
|
235
|
+
}
|
|
236
|
+
}
|
|
237
|
+
if (r.byModel.size > 1) {
|
|
238
|
+
lines.push('', '## New tokens by model', '', '| model | new tokens | share |', '|---|---:|---:|');
|
|
239
|
+
for (const [k, n] of [...r.byModel].sort((a, b) => b[1] - a[1]).slice(0, 6)) lines.push(`| ${k} | ${fmt(n)} | ${share(n)} |`);
|
|
240
|
+
lines.push(
|
|
241
|
+
'',
|
|
242
|
+
'Models may count differently against your limit; limitcast cannot tell them apart, so these are token counts, not window shares.',
|
|
243
|
+
);
|
|
244
|
+
}
|
|
245
|
+
|
|
246
|
+
if (r.tools.size) {
|
|
247
|
+
lines.push('', '## Tool results by source', '', '| tool | new tokens | calls | per call |', '|---|---:|---:|---:|');
|
|
248
|
+
for (const [k, e] of [...r.tools].sort((a, b) => b[1].tokens - a[1].tokens).slice(0, 8)) {
|
|
249
|
+
lines.push(`| ${k} | ${fmt(e.tokens)} | ${e.calls} | ${fmt(Math.round(e.tokens / e.calls))} |`);
|
|
250
|
+
}
|
|
251
|
+
lines.push('', '## Largest single steps', '', '| new tokens | tool | project | day |', '|---:|---|---|---|');
|
|
252
|
+
for (const s of [...r.steps].sort((a, b) => b.tokens - a.tokens).slice(0, 5)) {
|
|
253
|
+
lines.push(`| ${fmt(s.tokens)} | ${s.tool} | ${s.project.replace(homedir(), '~') || '(unknown)'} | ${day(s.t)} |`);
|
|
254
|
+
}
|
|
255
|
+
const big = r.steps.filter((s) => s.tokens >= BIG_RESULT);
|
|
256
|
+
const tips = [...r.tools]
|
|
257
|
+
.sort((a, b) => b[1].tokens - a[1].tokens)
|
|
258
|
+
.filter(([k, e]) => tipFor(k) && e.tokens / e.calls >= TIP_MIN_PER_CALL)
|
|
259
|
+
.slice(0, 3);
|
|
260
|
+
if (big.length || tips.length) {
|
|
261
|
+
lines.push('', '## What to try', '');
|
|
262
|
+
if (big.length) {
|
|
263
|
+
const bigTokens = big.reduce((a, s) => a + s.tokens, 0);
|
|
264
|
+
const by = new Map();
|
|
265
|
+
for (const s of big) by.set(s.tool, (by.get(s.tool) ?? 0) + s.tokens);
|
|
266
|
+
const top = [...by].sort((a, b) => b[1] - a[1])[0][0];
|
|
267
|
+
lines.push(
|
|
268
|
+
`- ${big.length} single steps added over ${fmt(BIG_RESULT)} new tokens each: ${Math.round((bigTokens / toolTokens) * 100)}% of all tool-result tokens, mostly ${top}.`,
|
|
269
|
+
);
|
|
270
|
+
}
|
|
271
|
+
for (const [k, e] of tips) lines.push(`- ${k} (${fmt(e.tokens)}, ${fmt(Math.round(e.tokens / e.calls))} per call): ${tipFor(k)}.`);
|
|
272
|
+
}
|
|
273
|
+
}
|
|
274
|
+
lines.push(
|
|
275
|
+
'',
|
|
276
|
+
'_Estimated from your local transcripts: a step is the new tokens that entered the context after a model call, assigned to the tools that call used._',
|
|
277
|
+
);
|
|
278
|
+
return lines.join('\n');
|
|
279
|
+
}
|
|
280
|
+
|
|
281
|
+
/**
|
|
282
|
+
* A start is cold when most of its prompt was new tokens, so the prompt cache did not have it.
|
|
283
|
+
* @param {{tokens:number, size:number}} s
|
|
284
|
+
*/
|
|
285
|
+
const isCold = (s) => s.tokens * 2 > s.size;
|
|
286
|
+
|
|
287
|
+
const GAPS = /** @type {[string, number][]} */ ([
|
|
288
|
+
['within 5 min', 5],
|
|
289
|
+
['5 to 60 min', 60],
|
|
290
|
+
['over 60 min', Number.POSITIVE_INFINITY],
|
|
291
|
+
]);
|
|
292
|
+
|
|
293
|
+
/**
|
|
294
|
+
* "Cold starts": how many runs started without the cache, what that cost beyond the same job's warm runs, and how
|
|
295
|
+
* the gap since the job's previous run decides it (so you can see how close together runs must be).
|
|
296
|
+
* @param {number} runs
|
|
297
|
+
* @param {{runs:number, tokens:number, size:number, cold:number, coldTokens:number, warmTokens:number, starts:{t:number, tokens:number, size:number}[]}[]} jobs
|
|
298
|
+
*/
|
|
299
|
+
function coldSection(runs, jobs) {
|
|
300
|
+
const cold = jobs.reduce((a, j) => a + j.cold, 0);
|
|
301
|
+
const lines = ['', '## Cold starts', ''];
|
|
302
|
+
// Only a job with both kinds of start can say what a cold one costs extra: cold runs times the difference.
|
|
303
|
+
const extra = jobs.reduce((a, j) => {
|
|
304
|
+
const warm = j.runs - j.cold;
|
|
305
|
+
return j.cold && warm ? a + j.cold * Math.max(0, j.coldTokens / j.cold - j.warmTokens / warm) : a;
|
|
306
|
+
}, 0);
|
|
307
|
+
const newTokens = jobs.reduce((a, j) => a + j.tokens, 0);
|
|
308
|
+
const prompts = jobs.reduce((a, j) => a + j.size, 0);
|
|
309
|
+
lines.push(
|
|
310
|
+
`${cold} of ${runs} runs (${Math.round((cold / runs) * 100)}%) started cold: more than half of their starting prompt was new tokens, not served from the prompt cache. ` +
|
|
311
|
+
`On average ${Math.round((1 - newTokens / prompts) * 100)}% of a starting prompt came from the cache.` +
|
|
312
|
+
(extra >= 1000 ? ` Against the warm runs of the same jobs, the cold ones cost about ${fmt(Math.round(extra))} more new tokens.` : ''),
|
|
313
|
+
);
|
|
314
|
+
const bucket = GAPS.map(() => ({ runs: 0, cold: 0 }));
|
|
315
|
+
for (const j of jobs) {
|
|
316
|
+
const sorted = [...j.starts].sort((a, b) => a.t - b.t);
|
|
317
|
+
for (let i = 1; i < sorted.length; i++) {
|
|
318
|
+
const gap = (sorted[i].t - sorted[i - 1].t) / 60_000;
|
|
319
|
+
if (!Number.isFinite(gap)) continue;
|
|
320
|
+
const b = bucket[GAPS.findIndex(([, max]) => gap <= max)];
|
|
321
|
+
b.runs++;
|
|
322
|
+
if (isCold(sorted[i])) b.cold++;
|
|
323
|
+
}
|
|
324
|
+
}
|
|
325
|
+
if (bucket.some((b) => b.runs)) {
|
|
326
|
+
lines.push('', '| time since the same job last ran | runs | started cold |', '|---|---:|---:|');
|
|
327
|
+
GAPS.forEach(([label], i) => {
|
|
328
|
+
if (bucket[i].runs) lines.push(`| ${label} | ${bucket[i].runs} | ${Math.round((bucket[i].cold / bucket[i].runs) * 100)}% |`);
|
|
329
|
+
});
|
|
330
|
+
const near = bucket[0];
|
|
331
|
+
if (near.runs >= 5) {
|
|
332
|
+
lines.push(
|
|
333
|
+
'',
|
|
334
|
+
near.cold / near.runs > 0.5
|
|
335
|
+
? "Even runs within 5 minutes of the same job's previous run mostly started cold, so running them closer together is unlikely to help: the cached prompt is not being reused between runs. Look for anything near the start of a run's prompt that changes every time, such as hook output with a date or counts."
|
|
336
|
+
: "Runs close behind the same job's previous run mostly started warm, so running a job's work in batches lets later runs reuse the first one's cached prompt.",
|
|
337
|
+
);
|
|
338
|
+
}
|
|
339
|
+
}
|
|
340
|
+
return lines;
|
|
341
|
+
}
|
|
342
|
+
|
|
343
|
+
/**
|
|
344
|
+
* Markdown: the scheduled (headless) jobs whose runs spent the most new tokens just starting. A run's start is what
|
|
345
|
+
* it loads before reading its prompt: settings, plugins, hooks, MCP servers, skills and instruction files.
|
|
346
|
+
* @param {ReturnType<typeof attribute>} r
|
|
347
|
+
* @param {{since:number, now:number}} o
|
|
348
|
+
*/
|
|
349
|
+
export function jobsReport(r, { since, now }) {
|
|
350
|
+
const day = (/** @type {number} */ t) => new Date(t).toLocaleDateString('sv-SE');
|
|
351
|
+
const lines = [
|
|
352
|
+
'# limitcast: heaviest scheduled-job starts',
|
|
353
|
+
'',
|
|
354
|
+
`${day(since)} to ${day(now)} · headless runs (started by scripts and tools, not from the CLI) · Claude Code only`,
|
|
355
|
+
'',
|
|
356
|
+
];
|
|
357
|
+
if (!r.starts.length) return [...lines, 'No headless runs in this period.'].join('\n');
|
|
358
|
+
/** @type {Map<string, {runs:number, tokens:number, size:number, calls:number, cold:number, coldTokens:number, warmTokens:number, starts:typeof r.starts}>} */
|
|
359
|
+
const jobs = new Map();
|
|
360
|
+
for (const s of r.starts) {
|
|
361
|
+
const k = s.prompt.slice(0, 45) || s.project || '(unknown)';
|
|
362
|
+
const j = jobs.get(k) ?? { runs: 0, tokens: 0, size: 0, calls: 0, cold: 0, coldTokens: 0, warmTokens: 0, starts: [] };
|
|
363
|
+
j.runs++;
|
|
364
|
+
j.tokens += s.tokens;
|
|
365
|
+
j.size += s.size;
|
|
366
|
+
j.calls += s.calls;
|
|
367
|
+
if (isCold(s)) {
|
|
368
|
+
j.cold++;
|
|
369
|
+
j.coldTokens += s.tokens;
|
|
370
|
+
} else j.warmTokens += s.tokens;
|
|
371
|
+
j.starts.push(s);
|
|
372
|
+
jobs.set(k, j);
|
|
373
|
+
}
|
|
374
|
+
const share = (/** @type {number} */ n) => `${Math.round((n / r.total) * 100)}%`;
|
|
375
|
+
lines.push(
|
|
376
|
+
`${r.starts.length} headless runs spent ${fmt(r.startHeadless)} new tokens just starting: ${share(r.startHeadless)} of all new tokens.`,
|
|
377
|
+
'',
|
|
378
|
+
);
|
|
379
|
+
lines.push(
|
|
380
|
+
'| job (first words of its prompt) | runs | new tokens at start | starting prompt | total start | share of all new | cold starts | calls per run |',
|
|
381
|
+
'|---|---:|---:|---:|---:|---:|---:|---:|',
|
|
382
|
+
);
|
|
383
|
+
const ranked = [...jobs].sort((a, b) => b[1].tokens - a[1].tokens);
|
|
384
|
+
const avg = (/** @type {number} */ n, /** @type {{runs:number}} */ j) => fmt(Math.round(n / j.runs));
|
|
385
|
+
for (const [k, j] of ranked.slice(0, 10)) {
|
|
386
|
+
lines.push(
|
|
387
|
+
`| ${k.replace(/\|/g, '/')} | ${j.runs} | ${avg(j.tokens, j)} | ${avg(j.size, j)} | ${fmt(j.tokens)} | ${share(j.tokens)} | ${Math.round((j.cold / j.runs) * 100)}% | ${(j.calls / j.runs).toFixed(1)} |`,
|
|
388
|
+
);
|
|
389
|
+
}
|
|
390
|
+
lines.push(...coldSection(r.starts.length, [...jobs.values()]));
|
|
391
|
+
const [leanJob, lean] = [...jobs].sort((a, b) => a[1].size / a[1].runs - b[1].size / b[1].runs)[0];
|
|
392
|
+
lines.push(
|
|
393
|
+
'',
|
|
394
|
+
'## Why a run starts this big',
|
|
395
|
+
'',
|
|
396
|
+
`Every run loads your settings, plugins, hooks, MCP servers, skills and instruction files before it reads its prompt. "New tokens at start" is what counts against your limit; "starting prompt" is the whole context, cached or not. The smallest starting prompt among these jobs averages ${avg(lean.size, lean)} (${leanJob.replace(/\|/g, '/')}); the heaviest job's averages ${avg(ranked[0][1].size, ranked[0][1])}.`,
|
|
397
|
+
'',
|
|
398
|
+
'A job that does not need all of that can leave it out: launch it with `claude -p --setting-sources "" --strict-mcp-config`, plus `--mcp-config` for the servers it uses. That also drops hooks, plugins and permission rules, so pass `--model` and `--permission-mode` and check the job still does what it should.',
|
|
399
|
+
'',
|
|
400
|
+
'_Estimated from your local transcripts. A job is its first 45 characters of prompt, so runs of the same job group together._',
|
|
401
|
+
);
|
|
402
|
+
return lines.join('\n');
|
|
403
|
+
}
|
|
404
|
+
|
|
405
|
+
const CACHE_VERSION = 3; // 2: the first call carries the session's first words; 3: model per call, subagent type
|
|
406
|
+
const CACHE_KEEP_MS = 35 * 86400_000;
|
|
407
|
+
const cacheFile = () => join(stateDir(), 'where-cache.json');
|
|
408
|
+
|
|
409
|
+
/** @returns {Record<string, {s:number, m:number, c:Call[]}>} the parsed calls of each transcript, by path */
|
|
410
|
+
function loadCache() {
|
|
411
|
+
try {
|
|
412
|
+
const d = JSON.parse(readFileSync(cacheFile(), 'utf8'));
|
|
413
|
+
return d.v === CACHE_VERSION ? d.files : {};
|
|
414
|
+
} catch {
|
|
415
|
+
return {};
|
|
416
|
+
}
|
|
417
|
+
}
|
|
418
|
+
|
|
419
|
+
/**
|
|
420
|
+
* The calls of every Claude Code transcript touched since `since`. Parsed transcripts are cached by size and mtime,
|
|
421
|
+
* so only new or changed ones are read again (a few GB of transcripts took 3 to 43 seconds uncached).
|
|
422
|
+
* @param {string} root
|
|
423
|
+
* @param {number} since
|
|
424
|
+
* @returns {Promise<Call[][]>}
|
|
425
|
+
*/
|
|
426
|
+
export async function whySessions(root, since) {
|
|
427
|
+
const cache = loadCache();
|
|
428
|
+
/** @type {typeof cache} */
|
|
429
|
+
const next = {};
|
|
430
|
+
const files = jsonlFiles(root, since, () => true);
|
|
431
|
+
for (const f of files) {
|
|
432
|
+
const st = statSync(f);
|
|
433
|
+
const hit = cache[f];
|
|
434
|
+
next[f] = hit && hit.s === st.size && hit.m === st.mtimeMs ? hit : { s: st.size, m: st.mtimeMs, c: await readCalls(f) };
|
|
435
|
+
}
|
|
436
|
+
// Keep entries this run didn't need (another period) while they are recent; drop the rest.
|
|
437
|
+
for (const [f, e] of Object.entries(cache)) if (!next[f] && e.m >= Date.now() - CACHE_KEEP_MS && existsSync(f)) next[f] = e;
|
|
438
|
+
try {
|
|
439
|
+
mkdirSync(stateDir(), { recursive: true });
|
|
440
|
+
writeFileSync(cacheFile(), JSON.stringify({ v: CACHE_VERSION, files: next }));
|
|
441
|
+
} catch {
|
|
442
|
+
/* a cache: the next run just reads the transcripts */
|
|
443
|
+
}
|
|
444
|
+
return files.map((f) => next[f].c);
|
|
445
|
+
}
|