limitcast 0.19.2 → 0.19.4

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/src/toolcheck.mjs CHANGED
@@ -9,11 +9,47 @@ import { stateDir } from './store.mjs';
9
9
 
10
10
  export const BIG_RESULT = 20_000; // estimated tokens of one result worth a notice
11
11
 
12
+ /** Grok's own names for the tools Claude Code calls Bash, Read, Grep and so on. Codex already says Bash. */
13
+ const NATIVE = /** @type {Record<string, string>} */ ({
14
+ run_terminal_command: 'Bash',
15
+ run_terminal_cmd: 'Bash',
16
+ read_file: 'Read',
17
+ grep: 'Grep',
18
+ search_replace: 'Edit',
19
+ hashline_edit: 'Edit',
20
+ web_fetch: 'WebFetch',
21
+ web_search: 'WebSearch',
22
+ });
23
+
12
24
  /**
13
- * The name a tool goes by in reports: MCP tools by server ("mcp:claude_ai_HubSpot"), the rest as they are.
25
+ * An MCP tool's server and tool name. Claude Code and Codex say `mcp__server__tool`; Grok says `server__tool` (its built-in
26
+ * tools never contain a double underscore). Null for anything else.
14
27
  * @param {string} name
28
+ * @param {'claude'|'codex'|'grok'} [host]
29
+ * @returns {{server:string, tool:string}|null}
15
30
  */
16
- export const toolKey = (name) => (name.startsWith('mcp__') ? `mcp:${name.split('__')[1]}` : name);
31
+ export function mcpParts(name, host = 'claude') {
32
+ if (name.startsWith('mcp__')) {
33
+ const [, server = '', ...rest] = name.split('__');
34
+ return server ? { server, tool: rest.join('__') } : null;
35
+ }
36
+ if (host === 'grok' && name.includes('__')) {
37
+ const [server, ...rest] = name.split('__');
38
+ return server ? { server, tool: rest.join('__') } : null;
39
+ }
40
+ return null;
41
+ }
42
+
43
+ /**
44
+ * The name a tool goes by in reports: MCP tools by server ("mcp:claude_ai_HubSpot"), the rest by the Claude Code name.
45
+ * @param {string} name
46
+ * @param {'claude'|'codex'|'grok'} [host]
47
+ */
48
+ export function toolKey(name, host = 'claude') {
49
+ const mcp = mcpParts(name, host);
50
+ if (mcp) return `mcp:${mcp.server}`;
51
+ return Object.hasOwn(NATIVE, name) ? NATIVE[name] : name;
52
+ }
17
53
 
18
54
  /**
19
55
  * What to ask for next time, or null when there is nothing to suggest (a Skill loads whole).
@@ -45,16 +81,22 @@ export function resultTokens(response) {
45
81
  * every later call). Next time: ask for fewer fields and a smaller limit." Null under the threshold.
46
82
  * @param {string} toolName
47
83
  * @param {unknown} response
48
- * @param {{fresh:number}|null|undefined} calib % of the 5-hour window per million new tokens
84
+ * @param {{fresh:number}|null|undefined} calib % of the 5-hour window per million new tokens (Claude Code only)
49
85
  * @param {number} [threshold]
86
+ * @param {'claude'|'codex'|'grok'} [host]
50
87
  */
51
- export function toolNotice(toolName, response, calib, threshold = BIG_RESULT) {
88
+ export function toolNotice(toolName, response, calib, threshold = BIG_RESULT, host = 'claude') {
52
89
  const tokens = resultTokens(response);
53
90
  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));
91
+ const mcp = mcpParts(toolName, host);
92
+ const label = mcp ? `${mcp.server.replace(/^claude_ai_/, '')} ${mcp.tool}` : toolName;
93
+ const pct =
94
+ calib && host === 'claude'
95
+ ? ` (≈${((tokens / 1e6) * calib.fresh).toFixed(2)}% of a 5-hour window to write, then re-read on every later call)`
96
+ : host === 'claude'
97
+ ? ''
98
+ : ' (written once as new tokens, then re-read on every later call)';
99
+ const tip = tipFor(toolKey(toolName, host));
58
100
  return `limitcast: that ${label} result was ≈${Math.round(tokens / 1000)}k tokens${pct}.${tip ? ` Next time: ${tip}.` : ''}`;
59
101
  }
60
102
 
package/src/toollimit.mjs CHANGED
@@ -1,7 +1,7 @@
1
1
  // @ts-check
2
- import { mkdirSync, readFileSync, writeFileSync } from 'node:fs';
2
+ import { appendFileSync, mkdirSync, readFileSync, statSync, writeFileSync } from 'node:fs';
3
3
  import { join } from 'node:path';
4
- import { stateDir } from './store.mjs';
4
+ import { stateDir, writeAtomic } from './store.mjs';
5
5
  import { toolKey } from './toolcheck.mjs';
6
6
 
7
7
  // PreToolUse: a tool whose recent results are fat, and whose call sets no limit, is denied before it runs.
@@ -47,6 +47,52 @@ export function loadToolStats() {
47
47
  }
48
48
  }
49
49
 
50
+ // Codex and Grok have no per-tool attribution report to feed the stats, so the tool-check hook records the size of each
51
+ // result it sees: a tool name and a token estimate per line, never the result. The newest 1000 lines are the stats.
52
+ const LIVE_LINES = 1000;
53
+ const LIVE_PRUNE_BYTES = 120_000;
54
+ const liveFile = (/** @type {string} */ host) => join(stateDir(), `tool-sizes-${host}.jsonl`);
55
+
56
+ /**
57
+ * @param {string} host
58
+ * @param {string} key a toolKey
59
+ * @param {number} tokens estimated size of one result
60
+ * shortcut: the trim can drop a line another hook appends in that instant; it only blurs an average.
61
+ */
62
+ export function recordToolSize(host, key, tokens) {
63
+ mkdirSync(stateDir(), { recursive: true });
64
+ const file = liveFile(host);
65
+ appendFileSync(file, `${JSON.stringify({ k: key, n: Math.round(tokens) })}\n`);
66
+ if (statSync(file).size > LIVE_PRUNE_BYTES) writeAtomic(file, `${readFileSync(file, 'utf8').trim().split('\n').slice(-LIVE_LINES).join('\n')}\n`);
67
+ }
68
+
69
+ /**
70
+ * Average result size per tool for a host that records them live. Empty until the hook has seen some calls.
71
+ * @param {string} host
72
+ * @returns {Record<string, ToolStat>}
73
+ */
74
+ export function loadLiveStats(host) {
75
+ /** @type {Map<string, {tokens:number, calls:number}>} */
76
+ const sums = new Map();
77
+ try {
78
+ for (const line of readFileSync(liveFile(host), 'utf8').trim().split('\n').slice(-LIVE_LINES)) {
79
+ try {
80
+ const { k, n } = JSON.parse(line);
81
+ if (typeof k !== 'string' || !Number.isFinite(n)) continue;
82
+ const e = sums.get(k) ?? { tokens: 0, calls: 0 };
83
+ e.tokens += n;
84
+ e.calls += 1;
85
+ sums.set(k, e);
86
+ } catch {
87
+ /* a partial line */
88
+ }
89
+ }
90
+ } catch {
91
+ return {};
92
+ }
93
+ return toolStats(sums);
94
+ }
95
+
50
96
  /**
51
97
  * Limit-shaped numbers anywhere in the arguments, a few levels down (MCP tools nest them).
52
98
  * @param {unknown} input
@@ -90,10 +136,12 @@ const k = (/** @type {number} */ n) => `${Math.max(1, Math.round(n / 1000))}k`;
90
136
  * @param {string} toolName
91
137
  * @param {unknown} input
92
138
  * @param {Record<string, ToolStat>} stats
139
+ * @param {{host?:'claude'|'codex'|'grok', rewrite?:boolean}} [o] rewrite: false for a host that may not honor a rewritten
140
+ * input (Codex), so a limit that is too large is denied with the number to use instead of being lowered in place
93
141
  * @returns {{deny:string}|{updatedInput:any, reason:string}|null}
94
142
  */
95
- export function toolLimitDecision(toolName, input, stats) {
96
- const key = toolKey(toolName);
143
+ export function toolLimitDecision(toolName, input, stats, { host = 'claude', rewrite = true } = {}) {
144
+ const key = toolKey(toolName, host);
97
145
  const stat = stats?.[key];
98
146
  if (!stat || stat.calls < MIN_CALLS || stat.avg < FAT_AVG) return null;
99
147
  const args = typeof input === 'string' ? tryJson(input) : input;
@@ -112,6 +160,11 @@ export function toolLimitDecision(toolName, input, stats) {
112
160
  if (limits.some((f) => f.value > 0 && f.value <= cap)) return null;
113
161
  const big = limits.find((f) => f.value > cap);
114
162
  const label = toolName === 'Read' || key === 'Read' ? 'Read' : key.replace(/^mcp:/, '');
163
+ if (big && !rewrite) {
164
+ return {
165
+ deny: `limitcast: ${label} results average ≈${k(stat.avg)} tokens a call over ${stat.calls} calls. Use a limit of ${cap} or fewer (this call asked for ${big.value}), then retry. Set LIMITCAST_ALLOW=1 to run it as written.`,
166
+ };
167
+ }
115
168
  if (big) {
116
169
  return {
117
170
  updatedInput: setAt(obj, big.path, cap),
package/src/usage.mjs CHANGED
@@ -8,8 +8,9 @@ import { stateDir, writeAtomic } 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, 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
11
+ * input:number, cacheWrite:number, cacheWrite1h?:number, cacheRead:number, output:number, entry?:string, costUsd?:number}} Usage
12
+ * entry: how Claude Code was launched (cli, sdk-py, ...); cacheWrite1h: the part of cacheWrite that used the 1-hour cache;
13
+ * costUsd: dollars the tool itself recorded for this record (Grok's costUsdTicks), preferred over re-pricing it
13
14
  */
14
15
 
15
16
  export const claudeRoot = () => join(process.env.CLAUDE_CONFIG_DIR ?? join(homedir(), '.claude'), 'projects');
@@ -82,7 +83,7 @@ export function claudeActivity(line, act) {
82
83
  /**
83
84
  * Codex rollout lines → usage. token_count events carry a running total, so emit the increase since the last one.
84
85
  * @param {string} line
85
- * @param {{prev:any, cwd:string, model:string}} st per-file state
86
+ * @param {{prev:any, cwd:string, model:string, sidechain?:boolean, parent?:string}} st per-file state
86
87
  * @param {string} session
87
88
  * @returns {Usage|null}
88
89
  */
@@ -96,6 +97,11 @@ export function codexUsage(line, st, session) {
96
97
  }
97
98
  st.cwd = ev?.payload?.cwd ?? st.cwd;
98
99
  st.model = ev?.payload?.model ?? st.model;
100
+ if (ev?.type === 'session_meta' && (ev.payload?.thread_source === 'subagent' || ev.payload?.source?.subagent)) {
101
+ // A subagent is a forked thread with a rollout of its own: its usage belongs to the thread that spawned it.
102
+ st.sidechain = true;
103
+ st.parent = ev.payload?.parent_thread_id ?? ev.payload?.source?.subagent?.thread_spawn?.parent_thread_id;
104
+ }
99
105
  return null;
100
106
  }
101
107
  if (!line.includes('"total_token_usage"')) return null;
@@ -113,7 +119,18 @@ export function codexUsage(line, st, session) {
113
119
  const input = (tot.input_tokens ?? 0) - (p.input_tokens ?? 0) - cached;
114
120
  const output = (tot.output_tokens ?? 0) - (p.output_tokens ?? 0);
115
121
  if (input + cached + output <= 0) return null;
116
- return { t, src: 'codex', session, project: st.cwd, model: st.model, sidechain: false, input, cacheWrite: 0, cacheRead: cached, output };
122
+ return {
123
+ t,
124
+ src: 'codex',
125
+ session: st.sidechain && st.parent ? st.parent : session,
126
+ project: st.cwd,
127
+ model: st.model,
128
+ sidechain: Boolean(st.sidechain),
129
+ input,
130
+ cacheWrite: 0,
131
+ cacheRead: cached,
132
+ output,
133
+ };
117
134
  }
118
135
 
119
136
  /**
@@ -121,9 +138,10 @@ export function codexUsage(line, st, session) {
121
138
  * @param {any} ledger parsed usage.json
122
139
  * @param {string} session
123
140
  * @param {string} project
141
+ * @param {boolean} [sidechain] the ledger of a subagent's child session
124
142
  * @returns {Usage[]}
125
143
  */
126
- export function grokUsage(ledger, session, project) {
144
+ export function grokUsage(ledger, session, project, sidechain = false) {
127
145
  /** @type {Usage[]} */
128
146
  const out = [];
129
147
  for (const turn of Array.isArray(ledger?.turns) ? ledger.turns : []) {
@@ -134,7 +152,22 @@ export function grokUsage(ledger, session, project) {
134
152
  const input = Math.max(0, (turn.inputTokens ?? 0) - cacheRead - cacheWrite);
135
153
  const output = turn.outputTokens ?? 0;
136
154
  const model = turn.primaryModelId ?? Object.keys(turn.modelUsage ?? {})[0] ?? '';
137
- out.push({ t, src: 'grok', session, project, model, sidechain: false, input, cacheWrite, cacheRead, output });
155
+ // A Grok record is a whole turn (up to dozens of model calls). Re-pricing its summed tokens would apply the
156
+ // above-200k long-context tier to the turn, overstating cost by about 1.8x, so carry Grok's own recorded cost.
157
+ const ticks = Number(turn.costUsdTicks);
158
+ out.push({
159
+ t,
160
+ src: 'grok',
161
+ session,
162
+ project,
163
+ model,
164
+ sidechain,
165
+ input,
166
+ cacheWrite,
167
+ cacheRead,
168
+ output,
169
+ ...(Number.isFinite(ticks) && ticks >= 0 ? { costUsd: ticks / 1e10 } : {}),
170
+ });
138
171
  }
139
172
  return out;
140
173
  }
@@ -146,17 +179,43 @@ export function grokUsage(ledger, session, project) {
146
179
  */
147
180
  function grokLedgers(root, since) {
148
181
  if (!existsSync(root)) return [];
182
+ /** @type {{file:string, session:string, project:string, sidechain:boolean, parent?:string}[]} */
149
183
  const out = [];
184
+ // A subagent runs as a child session of its own; the parent's subagents/<id>/meta.json names the pair.
185
+ /** @type {Map<string, string>} */
186
+ const parentOf = new Map();
150
187
  for (const proj of readdirSync(root, { withFileTypes: true })) {
151
188
  if (!proj.isDirectory()) continue;
152
189
  for (const sess of readdirSync(join(root, proj.name), { withFileTypes: true })) {
153
- const file = join(root, proj.name, sess.name, 'usage.json');
190
+ const dir = join(root, proj.name, sess.name);
191
+ const file = join(dir, 'usage.json');
154
192
  if (sess.isDirectory() && existsSync(file) && statSync(file).mtimeMs >= since) {
155
- out.push({ file, session: sess.name, project: safeDecode(proj.name) });
193
+ out.push({ file, session: sess.name, project: safeDecode(proj.name), sidechain: summaryKind(dir) === 'subagent' });
194
+ }
195
+ const sub = join(dir, 'subagents');
196
+ if (sess.isDirectory() && existsSync(sub) && statSync(sub).mtimeMs >= since) {
197
+ for (const child of readdirSync(sub, { withFileTypes: true })) {
198
+ try {
199
+ const meta = JSON.parse(readFileSync(join(sub, child.name, 'meta.json'), 'utf8'));
200
+ if (typeof meta?.child_session_id === 'string' && typeof meta?.parent_session_id === 'string')
201
+ parentOf.set(meta.child_session_id, meta.parent_session_id);
202
+ } catch {
203
+ /* a subagent still being written, or not a directory */
204
+ }
205
+ }
156
206
  }
157
207
  }
158
208
  }
159
- return out;
209
+ return out.map((e) => ({ ...e, sidechain: e.sidechain || parentOf.has(e.session), parent: parentOf.get(e.session) }));
210
+ }
211
+
212
+ /** @param {string} dir a Grok session directory @returns {string|undefined} */
213
+ function summaryKind(dir) {
214
+ try {
215
+ return JSON.parse(readFileSync(join(dir, 'summary.json'), 'utf8'))?.session_kind;
216
+ } catch {
217
+ return undefined;
218
+ }
160
219
  }
161
220
 
162
221
  /**
@@ -224,20 +283,20 @@ export async function readUsage(since, roots = {}, activity) {
224
283
  // Keep entries for files this run didn't need (another period) while they are recent; drop the rest.
225
284
  for (const [f, e] of Object.entries(cache)) if (!next[f] && e.m >= Date.now() - CACHE_KEEP_MS && existsSync(f)) next[f] = e;
226
285
  if (dirty || Object.keys(next).length !== Object.keys(cache).length) saveUsageCache(next);
227
- for (const { file, session, project } of grokLedgers(roots.grok ?? grokRoot(), since)) {
286
+ for (const { file, session, project, sidechain, parent } of grokLedgers(roots.grok ?? grokRoot(), since)) {
228
287
  let ledger;
229
288
  try {
230
289
  ledger = JSON.parse(readFileSync(file, 'utf8'));
231
290
  } catch {
232
291
  continue; // being written right now; picked up next run
233
292
  }
234
- for (const u of grokUsage(ledger, session, project)) if (u.t >= since) out.push(u);
293
+ for (const u of grokUsage(ledger, sidechain && parent ? parent : session, project, sidechain)) if (u.t >= since) out.push(u);
235
294
  }
236
295
  return out;
237
296
  }
238
297
 
239
298
  const CACHE_KEEP_MS = 35 * 86400_000;
240
- const USAGE_CACHE_VERSION = 2; // 2: records carry cacheWrite1h; an older cache is read again
299
+ const USAGE_CACHE_VERSION = 4; // 4: Codex subagent rollouts are sidechain usage of their parent thread; 3: Grok records carry costUsd; 2: records carry cacheWrite1h. An older cache is read again
241
300
  const usageCacheFile = () => join(stateDir(), 'usage-cache.json');
242
301
 
243
302
  /** @returns {Record<string, {s:number, m:number, u:Usage[], a?:{skills:string[], mcp:string[]}}>} */
package/src/value.mjs CHANGED
@@ -16,10 +16,11 @@ import { claudeUsage } from './usage.mjs';
16
16
  /** @typedef {{at:number, turns:number, savedPerTurn:number, calls?:number[]}} SessionValue calls: main-thread timestamps; absent in legacy records */
17
17
  /** @typedef {{src:string, win:string, at:number, lead:number|null, unseen:boolean}} HitValue lead: minutes of warning */
18
18
  /** @typedef {{t:number, src:string, win:string, shadow:boolean, outcome:string}} BlockValue */
19
- /** @typedef {{since:number, contextSince?:number, scanned:number, sessions:Record<string, SessionValue>, hits:Record<string, HitValue>, blocks:Record<string, BlockValue>, switches?:Record<string, {shadow:boolean}>, calib?:{fresh:number, read:number, n:number, at:number}, calibHistory?:{fresh:number, read:number, n:number, at:number}[], limitChange?:{from:number, to:number, at:number}}} Value
19
+ /** @typedef {{since:number, contextSince?:number, scanned:number, sessions:Record<string, SessionValue>, hits:Record<string, HitValue>, blocks:Record<string, BlockValue>, switches?:Record<string, {shadow:boolean}>, calib?:{fresh:number, read:number, n:number, at:number}, calibHistory?:{fresh:number, read:number, n:number, at:number}[], limitChange?:{from:number, to:number, at:number}, outcomesVersion?:number}} Value
20
20
  * calibHistory: one calibration of the last 3 days per day, to notice limit changes */
21
21
 
22
22
  const file = () => join(stateDir(), 'value.json');
23
+ const OUTCOMES_VERSION = 2;
23
24
  const tok = (/** @type {number} */ chars) => Math.round(chars / 4);
24
25
 
25
26
  /** @returns {Value} */
@@ -62,6 +63,17 @@ export function saveValue(v) {
62
63
  */
63
64
  export function foldEvents(v, { now, samples, blocks, start }) {
64
65
  v.since ||= start ?? Math.min(now, ...samples.map((s) => s.t));
66
+ if ((v.outcomesVersion ?? 1) < OUTCOMES_VERSION) {
67
+ // Through 0.19.2 a Grok block was judged against no Grok readings, so every one that had reset was recorded as "under".
68
+ // Judge the ones the block log still holds again; the rest cannot be, so they say so instead of keeping a guess.
69
+ const live = new Set(blocks.filter((x) => !x.kind).map((x) => String(x.t)));
70
+ for (const [key, b] of Object.entries(v.blocks)) {
71
+ if (b.src !== 'grok' || b.outcome === 'hit') continue;
72
+ if (live.has(key)) delete v.blocks[key];
73
+ else b.outcome = 'unknown';
74
+ }
75
+ v.outcomesVersion = OUTCOMES_VERSION;
76
+ }
65
77
  // As readings age out (8 days), a later look sees less: keep what was recorded while they all existed.
66
78
  // Limits before limitcast was watching (Codex logs reach back further) are replays, not warnings you got.
67
79
  for (const h of limitHits(samples).filter((x) => x.at >= v.since)) {