limitcast 0.11.5 → 0.13.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.
@@ -0,0 +1,83 @@
1
+ // @ts-check
2
+ import { mkdirSync, readFileSync, writeFileSync } from 'node:fs';
3
+ import { join } from 'node:path';
4
+ import { stateDir } from './store.mjs';
5
+
6
+ // Large tool-output notice (Pro, PostToolUse hook, installed with --alerts). A tool result enters the context once as
7
+ // new tokens and is then re-read on every later call, so a very large one is worth knowing about. The notice goes to
8
+ // the user (systemMessage), never the model, once per tool per session, with what to ask for next time.
9
+
10
+ export const BIG_RESULT = 20_000; // estimated tokens of one result worth a notice
11
+
12
+ /**
13
+ * The name a tool goes by in reports: MCP tools by server ("mcp:claude_ai_HubSpot"), the rest as they are.
14
+ * @param {string} name
15
+ */
16
+ export const toolKey = (name) => (name.startsWith('mcp__') ? `mcp:${name.split('__')[1]}` : name);
17
+
18
+ /**
19
+ * What to ask for next time, or null when there is nothing to suggest (a Skill loads whole).
20
+ * @param {string} key a toolKey
21
+ */
22
+ export function tipFor(key) {
23
+ if (key.startsWith('mcp:')) return 'ask for fewer fields and a smaller limit';
24
+ return (
25
+ /** @type {Record<string, string>} */ ({
26
+ Read: 'ask for a line range (offset and limit) instead of the whole file',
27
+ Bash: 'pipe long output through head, tail or grep',
28
+ Grep: 'narrow the pattern, or add a path or glob',
29
+ WebFetch: 'ask for one section of the page, not all of it',
30
+ })[key] ?? null
31
+ );
32
+ }
33
+
34
+ /**
35
+ * Tokens in a tool result, estimated from its size (about 4 characters each). Works on any result shape.
36
+ * @param {unknown} response
37
+ */
38
+ export function resultTokens(response) {
39
+ const text = typeof response === 'string' ? response : (JSON.stringify(response) ?? '');
40
+ return Math.round(text.length / 4);
41
+ }
42
+
43
+ /**
44
+ * "limitcast: that HubSpot get_crm_objects result was ≈25k tokens (≈0.17% of a 5-hour window to write, then re-read on
45
+ * every later call). Next time: ask for fewer fields and a smaller limit." Null under the threshold.
46
+ * @param {string} toolName
47
+ * @param {unknown} response
48
+ * @param {{fresh:number}|null|undefined} calib % of the 5-hour window per million new tokens
49
+ * @param {number} [threshold]
50
+ */
51
+ export function toolNotice(toolName, response, calib, threshold = BIG_RESULT) {
52
+ const tokens = resultTokens(response);
53
+ if (tokens < threshold) return null;
54
+ const [, server, ...rest] = toolName.startsWith('mcp__') ? toolName.split('__') : ['', toolName];
55
+ const label = toolName.startsWith('mcp__') ? `${server.replace(/^claude_ai_/, '')} ${rest.join('__')}` : toolName;
56
+ const pct = calib ? ` (≈${((tokens / 1e6) * calib.fresh).toFixed(2)}% of a 5-hour window to write, then re-read on every later call)` : '';
57
+ const tip = tipFor(toolKey(toolName));
58
+ return `limitcast: that ${label} result was ≈${Math.round(tokens / 1000)}k tokens${pct}.${tip ? ` Next time: ${tip}.` : ''}`;
59
+ }
60
+
61
+ const stateFile = () => join(stateDir(), 'tool-check.json');
62
+
63
+ /**
64
+ * True the first time a tool is flagged in a session, false after that.
65
+ * @param {string} sid
66
+ * @param {string} tool
67
+ */
68
+ export function firstFlag(sid, tool) {
69
+ /** @type {Record<string, string[]>} */
70
+ let seen = {};
71
+ try {
72
+ seen = JSON.parse(readFileSync(stateFile(), 'utf8'));
73
+ } catch {
74
+ /* first flag */
75
+ }
76
+ if (seen[sid]?.includes(tool)) return false;
77
+ const keep = Object.entries(seen)
78
+ .filter(([k]) => k !== sid)
79
+ .slice(-49); // the 49 most recent other sessions
80
+ mkdirSync(stateDir(), { recursive: true });
81
+ writeFileSync(stateFile(), JSON.stringify(Object.fromEntries([...keep, [sid, [...(seen[sid] ?? []), tool]]])));
82
+ return true;
83
+ }
package/src/usage.mjs CHANGED
@@ -8,7 +8,8 @@ import { stateDir } from './store.mjs';
8
8
  /**
9
9
  * One model response's token usage.
10
10
  * @typedef {{t:number, src:'claude'|'codex'|'grok', session:string, project:string, model:string, sidechain:boolean,
11
- * input:number, cacheWrite:number, cacheRead:number, output:number, entry?:string}} Usage entry: how Claude Code was launched (cli, sdk-py, ...)
11
+ * input:number, cacheWrite:number, cacheWrite1h?:number, cacheRead:number, output:number, entry?:string}} Usage
12
+ * entry: how Claude Code was launched (cli, sdk-py, ...); cacheWrite1h: the part of cacheWrite that used the 1-hour cache
12
13
  */
13
14
 
14
15
  export const claudeRoot = () => join(process.env.CLAUDE_CONFIG_DIR ?? join(homedir(), '.claude'), 'projects');
@@ -46,6 +47,7 @@ export function claudeUsage(line, seen, session) {
46
47
  sidechain: !!ev.isSidechain,
47
48
  input: u.input_tokens ?? 0,
48
49
  cacheWrite: u.cache_creation_input_tokens ?? 0,
50
+ cacheWrite1h: u.cache_creation?.ephemeral_1h_input_tokens ?? 0,
49
51
  cacheRead: u.cache_read_input_tokens ?? 0,
50
52
  output: u.output_tokens ?? 0,
51
53
  ...(ev.entrypoint ? { entry: String(ev.entrypoint) } : {}),
@@ -232,12 +234,14 @@ export async function readUsage(since, roots = {}, activity) {
232
234
  }
233
235
 
234
236
  const CACHE_KEEP_MS = 35 * 86400_000;
237
+ const USAGE_CACHE_VERSION = 2; // 2: records carry cacheWrite1h; an older cache is read again
235
238
  const usageCacheFile = () => join(stateDir(), 'usage-cache.json');
236
239
 
237
240
  /** @returns {Record<string, {s:number, m:number, u:Usage[], a?:{skills:string[], mcp:string[]}}>} */
238
241
  function loadUsageCache() {
239
242
  try {
240
- return JSON.parse(readFileSync(usageCacheFile(), 'utf8'));
243
+ const d = JSON.parse(readFileSync(usageCacheFile(), 'utf8'));
244
+ return d.v === USAGE_CACHE_VERSION ? d.files : {};
241
245
  } catch {
242
246
  return {};
243
247
  }
@@ -247,7 +251,7 @@ function loadUsageCache() {
247
251
  function saveUsageCache(c) {
248
252
  try {
249
253
  mkdirSync(stateDir(), { recursive: true });
250
- writeFileSync(usageCacheFile(), JSON.stringify(c));
254
+ writeFileSync(usageCacheFile(), JSON.stringify({ v: USAGE_CACHE_VERSION, files: c }));
251
255
  } catch {
252
256
  /* a cache: the next run just reads the transcripts */
253
257
  }
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
+ }