limitcast 0.19.3 → 0.20.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,93 @@
1
+ import { lstatSync, readFileSync, unlinkSync } from 'node:fs';
2
+ import { writeAtomic } from './store.mjs';
3
+
4
+ export function readText(path) {
5
+ try {
6
+ if (!lstatSync(path).isFile()) throw new Error('refusing non-file configuration or recovery record');
7
+ return readFileSync(path, 'utf8');
8
+ } catch (error) {
9
+ if (error.code === 'ENOENT') return null;
10
+ throw error;
11
+ }
12
+ }
13
+
14
+ export function readLedger(path) {
15
+ const text = readText(path);
16
+ if (text === null) return [];
17
+ try {
18
+ const entries = JSON.parse(text);
19
+ if (Array.isArray(entries) && entries.every((e) => e && typeof e === 'object' && !Array.isArray(e))) return entries;
20
+ } catch {
21
+ /* preserve invalid recovery evidence */
22
+ }
23
+ throw new Error('invalid trim ledger; preserve it and repair before retrying');
24
+ }
25
+
26
+ export function editText(path, edit) {
27
+ const before = readText(path);
28
+ return { path, before, after: edit(before) };
29
+ }
30
+
31
+ export function editJson(path, edit) {
32
+ return editText(path, (before) => {
33
+ let cfg;
34
+ try {
35
+ cfg = JSON.parse(before ?? '{}');
36
+ } catch {
37
+ throw new Error('invalid configuration JSON; original bytes preserved');
38
+ }
39
+ if (!cfg || typeof cfg !== 'object' || Array.isArray(cfg)) throw new Error('configuration must be an object');
40
+ edit(cfg);
41
+ return `${JSON.stringify(cfg, null, 2)}\n`;
42
+ });
43
+ }
44
+
45
+ const write = (path, text) => (text === null ? unlinkSync(path) : writeAtomic(path, text));
46
+
47
+ /** Called under the state lock. Resolve a fully committed operation, or roll back a partial one without overwriting edits. */
48
+ export function recoverTransaction(ledger) {
49
+ const journal = `${ledger}.pending.json`;
50
+ const text = readText(journal);
51
+ if (text === null) return;
52
+ let tx;
53
+ try {
54
+ tx = JSON.parse(text);
55
+ } catch {
56
+ throw new Error('invalid trim recovery record; preserve it for manual recovery');
57
+ }
58
+ if (
59
+ tx.version !== 1 ||
60
+ !Array.isArray(tx.changes) ||
61
+ !tx.changes.length ||
62
+ tx.changes.at(-1)?.path !== ledger ||
63
+ tx.changes.some((c) => !c || typeof c.path !== 'string' || ![c.before, c.after].every((v) => v === null || typeof v === 'string'))
64
+ )
65
+ throw new Error('unsupported trim recovery record; preserve it for manual recovery');
66
+ const current = tx.changes.map((c) => readText(c.path));
67
+ if (tx.changes.some((c, i) => current[i] !== c.before && current[i] !== c.after))
68
+ throw new Error('configuration changed after interrupted trim; recovery record retained, reconcile manually');
69
+ if (!tx.changes.every((c, i) => current[i] === c.after)) {
70
+ for (const c of tx.changes.toReversed()) {
71
+ if (readText(c.path) === c.after && c.before !== c.after) write(c.path, c.before);
72
+ }
73
+ }
74
+ unlinkSync(journal);
75
+ }
76
+
77
+ /** Journal all original bytes before the first write, including the undo ledger. Caller holds the state lock. */
78
+ export function commitTransaction(ledger, entries, updates) {
79
+ const changes = [...updates, editText(ledger, () => `${JSON.stringify(entries, null, 2)}\n`)];
80
+ if (changes.some((c) => readText(c.path) !== c.before)) throw new Error('configuration changed during trim; retry after reviewing it');
81
+ const journal = `${ledger}.pending.json`;
82
+ writeAtomic(journal, JSON.stringify({ version: 1, changes }));
83
+ try {
84
+ for (const c of changes) {
85
+ if (readText(c.path) !== c.before) throw new Error('configuration changed during trim');
86
+ if (c.before !== c.after) write(c.path, c.after);
87
+ }
88
+ unlinkSync(journal);
89
+ } catch (error) {
90
+ recoverTransaction(ledger);
91
+ throw error;
92
+ }
93
+ }
package/src/usage.mjs CHANGED
@@ -83,7 +83,7 @@ export function claudeActivity(line, act) {
83
83
  /**
84
84
  * Codex rollout lines → usage. token_count events carry a running total, so emit the increase since the last one.
85
85
  * @param {string} line
86
- * @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
87
87
  * @param {string} session
88
88
  * @returns {Usage|null}
89
89
  */
@@ -97,6 +97,11 @@ export function codexUsage(line, st, session) {
97
97
  }
98
98
  st.cwd = ev?.payload?.cwd ?? st.cwd;
99
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
+ }
100
105
  return null;
101
106
  }
102
107
  if (!line.includes('"total_token_usage"')) return null;
@@ -114,7 +119,18 @@ export function codexUsage(line, st, session) {
114
119
  const input = (tot.input_tokens ?? 0) - (p.input_tokens ?? 0) - cached;
115
120
  const output = (tot.output_tokens ?? 0) - (p.output_tokens ?? 0);
116
121
  if (input + cached + output <= 0) return null;
117
- 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
+ };
118
134
  }
119
135
 
120
136
  /**
@@ -122,9 +138,10 @@ export function codexUsage(line, st, session) {
122
138
  * @param {any} ledger parsed usage.json
123
139
  * @param {string} session
124
140
  * @param {string} project
141
+ * @param {boolean} [sidechain] the ledger of a subagent's child session
125
142
  * @returns {Usage[]}
126
143
  */
127
- export function grokUsage(ledger, session, project) {
144
+ export function grokUsage(ledger, session, project, sidechain = false) {
128
145
  /** @type {Usage[]} */
129
146
  const out = [];
130
147
  for (const turn of Array.isArray(ledger?.turns) ? ledger.turns : []) {
@@ -144,7 +161,7 @@ export function grokUsage(ledger, session, project) {
144
161
  session,
145
162
  project,
146
163
  model,
147
- sidechain: false,
164
+ sidechain,
148
165
  input,
149
166
  cacheWrite,
150
167
  cacheRead,
@@ -162,17 +179,43 @@ export function grokUsage(ledger, session, project) {
162
179
  */
163
180
  function grokLedgers(root, since) {
164
181
  if (!existsSync(root)) return [];
182
+ /** @type {{file:string, session:string, project:string, sidechain:boolean, parent?:string}[]} */
165
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();
166
187
  for (const proj of readdirSync(root, { withFileTypes: true })) {
167
188
  if (!proj.isDirectory()) continue;
168
189
  for (const sess of readdirSync(join(root, proj.name), { withFileTypes: true })) {
169
- 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');
170
192
  if (sess.isDirectory() && existsSync(file) && statSync(file).mtimeMs >= since) {
171
- 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
+ }
172
206
  }
173
207
  }
174
208
  }
175
- 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
+ }
176
219
  }
177
220
 
178
221
  /**
@@ -240,20 +283,20 @@ export async function readUsage(since, roots = {}, activity) {
240
283
  // Keep entries for files this run didn't need (another period) while they are recent; drop the rest.
241
284
  for (const [f, e] of Object.entries(cache)) if (!next[f] && e.m >= Date.now() - CACHE_KEEP_MS && existsSync(f)) next[f] = e;
242
285
  if (dirty || Object.keys(next).length !== Object.keys(cache).length) saveUsageCache(next);
243
- 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)) {
244
287
  let ledger;
245
288
  try {
246
289
  ledger = JSON.parse(readFileSync(file, 'utf8'));
247
290
  } catch {
248
291
  continue; // being written right now; picked up next run
249
292
  }
250
- 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);
251
294
  }
252
295
  return out;
253
296
  }
254
297
 
255
298
  const CACHE_KEEP_MS = 35 * 86400_000;
256
- const USAGE_CACHE_VERSION = 3; // 3: Grok records carry costUsd; 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
257
300
  const usageCacheFile = () => join(stateDir(), 'usage-cache.json');
258
301
 
259
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)) {