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.
- package/README.md +4 -3
- package/bin/limitcast.mjs +157 -38
- package/package.json +2 -2
- package/src/apply.mjs +96 -116
- package/src/capabilities.mjs +19 -6
- package/src/codex-trust.mjs +85 -0
- package/src/codex.mjs +115 -64
- package/src/grok.mjs +112 -67
- package/src/guard.mjs +8 -2
- package/src/inflight.mjs +7 -2
- package/src/install.mjs +34 -10
- package/src/notify.mjs +17 -0
- package/src/optimize-cli.mjs +13 -0
- package/src/overhead.mjs +39 -13
- package/src/prices.mjs +9 -2
- package/src/receipts.mjs +188 -0
- package/src/report.mjs +9 -0
- package/src/results.mjs +21 -3
- package/src/store.mjs +76 -31
- package/src/subagents.mjs +35 -4
- package/src/toolcheck.mjs +50 -8
- package/src/toollimit.mjs +63 -9
- package/src/transaction.mjs +93 -0
- package/src/usage.mjs +53 -10
- package/src/value.mjs +13 -1
package/src/receipts.mjs
ADDED
|
@@ -0,0 +1,188 @@
|
|
|
1
|
+
// @ts-check
|
|
2
|
+
import { existsSync, mkdirSync, readdirSync, readFileSync } from 'node:fs';
|
|
3
|
+
import { homedir } from 'node:os';
|
|
4
|
+
import { dirname, join } from 'node:path';
|
|
5
|
+
import { costOf } from './prices.mjs';
|
|
6
|
+
import { stateDir, writeAtomic } from './store.mjs';
|
|
7
|
+
import { logSubagent } from './subagents.mjs';
|
|
8
|
+
import { codexUsage, grokRoot, grokUsage } from './usage.mjs';
|
|
9
|
+
|
|
10
|
+
// What a finished Codex or Grok subagent used, for the SubagentStop receipt. Claude's receipt is priced from its own
|
|
11
|
+
// transcript in subagents.mjs; the other two hosts keep usage elsewhere (a Codex rollout, a Grok session ledger).
|
|
12
|
+
|
|
13
|
+
/** @typedef {{calls:number, fresh:number, read:number, usd:number|null}} HostUsage */
|
|
14
|
+
|
|
15
|
+
/**
|
|
16
|
+
* Which tool sent a SubagentStop payload. Grok writes camelCase fields; Codex and Claude write snake_case, and tell
|
|
17
|
+
* apart by `turn_id` (Codex sends one, Claude Code does not; seen in a live run) or where the transcript lives. A Codex
|
|
18
|
+
* home that is not ~/.codex has no `.codex` in its paths, which is why the payload shape is checked first.
|
|
19
|
+
* @param {any} hook
|
|
20
|
+
* @returns {'claude'|'codex'|'grok'}
|
|
21
|
+
*/
|
|
22
|
+
export function stopHost(hook) {
|
|
23
|
+
const path = String(hook?.agent_transcript_path ?? hook?.transcriptPath ?? hook?.transcript_path ?? '');
|
|
24
|
+
if (hook?.sessionId !== undefined || hook?.subagentType !== undefined || hook?.transcriptPath !== undefined) return 'grok';
|
|
25
|
+
if (hook?.turn_id !== undefined || path.includes('/.codex/') || /\/rollout-[^/]*\.jsonl$/.test(path)) return 'codex';
|
|
26
|
+
if (path.includes('/.grok/')) return 'grok';
|
|
27
|
+
return 'claude';
|
|
28
|
+
}
|
|
29
|
+
|
|
30
|
+
/** @param {import('./usage.mjs').Usage[]} usages @returns {HostUsage} */
|
|
31
|
+
function summarize(usages) {
|
|
32
|
+
const cost = costOf(usages);
|
|
33
|
+
return {
|
|
34
|
+
calls: usages.length,
|
|
35
|
+
fresh: usages.reduce((a, u) => a + u.input + u.cacheWrite + u.output, 0),
|
|
36
|
+
read: usages.reduce((a, u) => a + u.cacheRead, 0),
|
|
37
|
+
// A partial dollar figure would read as the whole, so say nothing when any of the tokens had no price.
|
|
38
|
+
usd: usages.length && cost.unpriced === 0 ? cost.total : null,
|
|
39
|
+
};
|
|
40
|
+
}
|
|
41
|
+
|
|
42
|
+
/**
|
|
43
|
+
* A Codex subagent's rollout: its token_count events carry running totals, so each model call is the increase over the last.
|
|
44
|
+
* @param {string} path
|
|
45
|
+
* @returns {HostUsage}
|
|
46
|
+
*/
|
|
47
|
+
export function codexSubagentUsage(path) {
|
|
48
|
+
const file = path.startsWith('~/') ? join(homedir(), path.slice(2)) : path;
|
|
49
|
+
const st = { prev: null, cwd: '', model: '' };
|
|
50
|
+
/** @type {import('./usage.mjs').Usage[]} */
|
|
51
|
+
const usages = [];
|
|
52
|
+
for (const line of readFileSync(file, 'utf8').split('\n')) {
|
|
53
|
+
const u = codexUsage(line, st, '');
|
|
54
|
+
if (u) usages.push(u);
|
|
55
|
+
}
|
|
56
|
+
return summarize(usages);
|
|
57
|
+
}
|
|
58
|
+
|
|
59
|
+
/** A Grok child session is a session of its own: its summary says so, and its usage.json is the ledger. @param {string} dir */
|
|
60
|
+
function subagentLedger(dir) {
|
|
61
|
+
try {
|
|
62
|
+
const kind = JSON.parse(readFileSync(join(dir, 'summary.json'), 'utf8'))?.session_kind;
|
|
63
|
+
if (kind !== 'subagent') return null;
|
|
64
|
+
return JSON.parse(readFileSync(join(dir, 'usage.json'), 'utf8'));
|
|
65
|
+
} catch {
|
|
66
|
+
return null;
|
|
67
|
+
}
|
|
68
|
+
}
|
|
69
|
+
|
|
70
|
+
/**
|
|
71
|
+
* A Grok subagent's session ledger. The hook names the subagent and a transcript; either one leads to the child
|
|
72
|
+
* session directory <root>/<project>/<child id>/. A directory that is not a subagent session (the parent's) is never used.
|
|
73
|
+
* @param {any} hook
|
|
74
|
+
* @param {string} [root]
|
|
75
|
+
* @returns {HostUsage|null}
|
|
76
|
+
*/
|
|
77
|
+
export function grokSubagentUsage(hook, root = grokRoot()) {
|
|
78
|
+
const ids = [hook?.subagentId, hook?.subagent_id, hook?.agent_id, hook?.sessionId, hook?.session_id].filter((s) => typeof s === 'string' && s);
|
|
79
|
+
const transcript = hook?.transcriptPath ?? hook?.transcript_path;
|
|
80
|
+
const dirs = typeof transcript === 'string' ? [dirname(transcript)] : [];
|
|
81
|
+
try {
|
|
82
|
+
if (existsSync(root)) {
|
|
83
|
+
for (const proj of readdirSync(root, { withFileTypes: true })) {
|
|
84
|
+
if (proj.isDirectory()) for (const id of ids) dirs.push(join(root, proj.name, id));
|
|
85
|
+
}
|
|
86
|
+
}
|
|
87
|
+
} catch {
|
|
88
|
+
/* an unreadable root: no receipt */
|
|
89
|
+
}
|
|
90
|
+
for (const dir of dirs) {
|
|
91
|
+
const ledger = subagentLedger(dir);
|
|
92
|
+
if (ledger) {
|
|
93
|
+
const usages = grokUsage(ledger, '', '');
|
|
94
|
+
if (usages.length) return { ...summarize(usages), calls: Number(ledger?.session?.modelCalls) || usages.length };
|
|
95
|
+
}
|
|
96
|
+
}
|
|
97
|
+
return null;
|
|
98
|
+
}
|
|
99
|
+
|
|
100
|
+
// Grok writes a subagent's usage after its stop hook has run (measured live: the hook fired 1.6 s before usage.json
|
|
101
|
+
// appeared), so the receipt cannot be priced at the stop. It is parked and settled by the next limitcast hook.
|
|
102
|
+
const pendingFile = () => join(stateDir(), 'pending-receipts.json');
|
|
103
|
+
const PENDING_MAX_MS = 24 * 3600_000;
|
|
104
|
+
|
|
105
|
+
/** @returns {{t:number, type:string, hook:any}[]} */
|
|
106
|
+
function loadPending() {
|
|
107
|
+
try {
|
|
108
|
+
const list = JSON.parse(readFileSync(pendingFile(), 'utf8'));
|
|
109
|
+
return Array.isArray(list) ? list : [];
|
|
110
|
+
} catch {
|
|
111
|
+
return [];
|
|
112
|
+
}
|
|
113
|
+
}
|
|
114
|
+
|
|
115
|
+
/**
|
|
116
|
+
* Park a Grok subagent's receipt until its ledger exists.
|
|
117
|
+
* @param {number} now
|
|
118
|
+
* @param {string} type
|
|
119
|
+
* @param {any} hook the SubagentStop payload
|
|
120
|
+
*/
|
|
121
|
+
export function deferReceipt(now, type, hook) {
|
|
122
|
+
const keep = (({ subagentId, sessionId, transcriptPath, session_id }) => ({ subagentId, sessionId: sessionId ?? session_id, transcriptPath }))(
|
|
123
|
+
hook ?? {},
|
|
124
|
+
);
|
|
125
|
+
mkdirSync(stateDir(), { recursive: true });
|
|
126
|
+
writeAtomic(
|
|
127
|
+
pendingFile(),
|
|
128
|
+
JSON.stringify([
|
|
129
|
+
...loadPending()
|
|
130
|
+
.filter((p) => now - p.t < PENDING_MAX_MS)
|
|
131
|
+
.slice(-49),
|
|
132
|
+
{ t: now, type, hook: keep },
|
|
133
|
+
]),
|
|
134
|
+
);
|
|
135
|
+
}
|
|
136
|
+
|
|
137
|
+
/**
|
|
138
|
+
* Log the parked receipts whose ledgers exist now; drop the ones that never appeared. Cheap when nothing is parked.
|
|
139
|
+
* @param {number} now
|
|
140
|
+
* @param {string} [root] Grok sessions root
|
|
141
|
+
* @returns {number} how many were logged
|
|
142
|
+
*/
|
|
143
|
+
export function settleReceipts(now, root = grokRoot()) {
|
|
144
|
+
if (!existsSync(pendingFile())) return 0;
|
|
145
|
+
const left = [];
|
|
146
|
+
let settled = 0;
|
|
147
|
+
for (const p of loadPending()) {
|
|
148
|
+
const usage = grokSubagentUsage(p.hook, root);
|
|
149
|
+
if (usage?.calls) {
|
|
150
|
+
logSubagent({
|
|
151
|
+
t: p.t,
|
|
152
|
+
src: 'grok',
|
|
153
|
+
id: p.hook?.subagentId,
|
|
154
|
+
sid: p.hook?.sessionId,
|
|
155
|
+
type: p.type,
|
|
156
|
+
calls: usage.calls,
|
|
157
|
+
fresh: usage.fresh,
|
|
158
|
+
read: usage.read,
|
|
159
|
+
...(usage.usd === null ? {} : { usd: usage.usd }),
|
|
160
|
+
});
|
|
161
|
+
settled++;
|
|
162
|
+
} else if (now - p.t < PENDING_MAX_MS) left.push(p);
|
|
163
|
+
}
|
|
164
|
+
if (settled || left.length !== loadPending().length) writeAtomic(pendingFile(), JSON.stringify(left));
|
|
165
|
+
return settled;
|
|
166
|
+
}
|
|
167
|
+
|
|
168
|
+
/**
|
|
169
|
+
* Usage of the subagent a SubagentStop payload describes, or null when this host's transcript cannot be read.
|
|
170
|
+
* @param {any} hook
|
|
171
|
+
* @returns {{src:'codex'|'grok', usage:HostUsage}|null}
|
|
172
|
+
*/
|
|
173
|
+
export function hostSubagentUsage(hook) {
|
|
174
|
+
const src = stopHost(hook);
|
|
175
|
+
try {
|
|
176
|
+
if (src === 'codex') {
|
|
177
|
+
const path = hook?.agent_transcript_path;
|
|
178
|
+
return typeof path === 'string' ? { src, usage: codexSubagentUsage(path) } : null;
|
|
179
|
+
}
|
|
180
|
+
if (src === 'grok') {
|
|
181
|
+
const usage = grokSubagentUsage(hook);
|
|
182
|
+
return usage ? { src, usage } : null;
|
|
183
|
+
}
|
|
184
|
+
} catch {
|
|
185
|
+
/* an unreadable transcript: no receipt */
|
|
186
|
+
}
|
|
187
|
+
return null;
|
|
188
|
+
}
|
package/src/report.mjs
CHANGED
|
@@ -45,6 +45,15 @@ export function burnReport(usage, { since, now }) {
|
|
|
45
45
|
const side = sum(claude.filter((u) => u.sidechain));
|
|
46
46
|
lines.push('', `Subagents used **${pct(side, sum(claude))}** of Claude tokens.`);
|
|
47
47
|
}
|
|
48
|
+
// Codex and Grok run a subagent as a thread of its own; its usage counts under the session that spawned it.
|
|
49
|
+
for (const [src, name] of /** @type {const} */ ([
|
|
50
|
+
['codex', 'Codex'],
|
|
51
|
+
['grok', 'Grok'],
|
|
52
|
+
])) {
|
|
53
|
+
const own = usage.filter((u) => u.src === src);
|
|
54
|
+
const side = sum(own.filter((u) => u.sidechain));
|
|
55
|
+
if (side) lines.push('', `Subagents used **${pct(side, sum(own))}** of ${name} tokens.`);
|
|
56
|
+
}
|
|
48
57
|
|
|
49
58
|
table(
|
|
50
59
|
lines,
|
package/src/results.mjs
CHANGED
|
@@ -2,6 +2,7 @@
|
|
|
2
2
|
import { appendFileSync, existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
|
|
3
3
|
import { join } from 'node:path';
|
|
4
4
|
import { claudeAccounts, forecast } from './forecast.mjs';
|
|
5
|
+
import { fmtUsd } from './prices.mjs';
|
|
5
6
|
import { stateDir } from './store.mjs';
|
|
6
7
|
|
|
7
8
|
/** @typedef {import('./forecast.mjs').Sample} Sample */
|
|
@@ -315,14 +316,31 @@ export function resultsReport({ now, days, samples, blocks, pro, saved, value =
|
|
|
315
316
|
const recent = subagents.filter((e) => e.t >= now - days * 86400_000);
|
|
316
317
|
if (recent.length || st.colds || st.coldNotices) {
|
|
317
318
|
out.push('', '## Subagents and cold caches');
|
|
318
|
-
const
|
|
319
|
-
|
|
319
|
+
const claude = recent.filter((e) => (e.src ?? 'claude') === 'claude');
|
|
320
|
+
const priced = claude.filter((e) => e.pct !== undefined).map((e) => /** @type {number} */ (e.pct));
|
|
321
|
+
const named = recent.length > claude.length; // name the tool only once another tool's subagents are listed too
|
|
322
|
+
if (claude.length)
|
|
320
323
|
out.push(
|
|
321
|
-
`${
|
|
324
|
+
`${claude.length} ${named ? 'Claude Code subagent' : 'subagent'}${claude.length === 1 ? '' : 's'} finished` +
|
|
322
325
|
(priced.length
|
|
323
326
|
? `, ≈${pctText(priced.reduce((a, b) => a + b, 0))} of a 5-hour window in all; the biggest ≈${pctText(Math.max(...priced))}.${pro ? '' : " Pro shows each one's cost when it finishes and can cap them per window."}`
|
|
324
327
|
: '.'),
|
|
325
328
|
);
|
|
329
|
+
// Codex and Grok have no 5-hour calibration, so their receipts are in API-equivalent dollars, which are not a bill.
|
|
330
|
+
for (const [host, name] of /** @type {const} */ ([
|
|
331
|
+
['codex', 'Codex'],
|
|
332
|
+
['grok', 'Grok'],
|
|
333
|
+
])) {
|
|
334
|
+
const runs = recent.filter((e) => e.src === host);
|
|
335
|
+
if (!runs.length) continue;
|
|
336
|
+
const usd = runs.filter((e) => typeof e.usd === 'number').map((e) => /** @type {number} */ (e.usd));
|
|
337
|
+
out.push(
|
|
338
|
+
`${runs.length} ${name} subagent${runs.length === 1 ? '' : 's'} finished` +
|
|
339
|
+
(usd.length
|
|
340
|
+
? `, about ${fmtUsd(usd.reduce((a, b) => a + b, 0))} at API list prices in all; the biggest ${fmtUsd(Math.max(...usd))}.`
|
|
341
|
+
: '.'),
|
|
342
|
+
);
|
|
343
|
+
}
|
|
326
344
|
if (st.colds)
|
|
327
345
|
out.push(
|
|
328
346
|
`${pro ? 'Held' : 'Pro would have held'} ${st.colds} message${st.colds === 1 ? '' : 's'} sent after the prompt cache had expired` +
|
package/src/store.mjs
CHANGED
|
@@ -1,6 +1,20 @@
|
|
|
1
1
|
// @ts-check
|
|
2
2
|
import { randomUUID } from 'node:crypto';
|
|
3
|
-
import {
|
|
3
|
+
import {
|
|
4
|
+
appendFileSync,
|
|
5
|
+
closeSync,
|
|
6
|
+
existsSync,
|
|
7
|
+
mkdirSync,
|
|
8
|
+
openSync,
|
|
9
|
+
readdirSync,
|
|
10
|
+
readFileSync,
|
|
11
|
+
renameSync,
|
|
12
|
+
rmdirSync,
|
|
13
|
+
rmSync,
|
|
14
|
+
statSync,
|
|
15
|
+
unlinkSync,
|
|
16
|
+
writeFileSync,
|
|
17
|
+
} from 'node:fs';
|
|
4
18
|
import { homedir } from 'node:os';
|
|
5
19
|
import { join } from 'node:path';
|
|
6
20
|
|
|
@@ -30,49 +44,80 @@ export function writeAtomic(/** @type {string} */ path, /** @type {string} */ te
|
|
|
30
44
|
}
|
|
31
45
|
}
|
|
32
46
|
|
|
33
|
-
const
|
|
34
|
-
|
|
47
|
+
const LOCK_WAIT_MS = 10_000;
|
|
48
|
+
|
|
49
|
+
function releaseLock(lock, owner) {
|
|
50
|
+
try {
|
|
51
|
+
unlinkSync(join(lock, owner));
|
|
52
|
+
// A contender can replace the now-empty directory with its populated lock. Never remove that lock recursively.
|
|
53
|
+
rmdirSync(lock);
|
|
54
|
+
} catch (error) {
|
|
55
|
+
if (!['ENOENT', 'ENOTEMPTY', 'EEXIST'].includes(error.code)) throw error;
|
|
56
|
+
}
|
|
57
|
+
}
|
|
58
|
+
|
|
59
|
+
/** Serialize settings and trim transactions. Publish a populated owner directory atomically; reclaim only dead owners. */
|
|
60
|
+
export function withStateLock(change) {
|
|
61
|
+
const dir = stateDir();
|
|
62
|
+
mkdirSync(dir, { recursive: true, mode: 0o700 });
|
|
63
|
+
const lock = join(dir, 'config.json.lock');
|
|
64
|
+
const owner = `${process.pid}-${randomUUID()}`;
|
|
65
|
+
const candidate = `${lock}.${owner}`;
|
|
66
|
+
mkdirSync(candidate, { mode: 0o700 });
|
|
67
|
+
let acquired = false;
|
|
68
|
+
try {
|
|
69
|
+
writeFileSync(join(candidate, owner), '', { mode: 0o600 });
|
|
70
|
+
const start = Date.now();
|
|
71
|
+
for (;;) {
|
|
72
|
+
try {
|
|
73
|
+
renameSync(candidate, lock);
|
|
74
|
+
acquired = true;
|
|
75
|
+
break;
|
|
76
|
+
} catch (error) {
|
|
77
|
+
if (!['EEXIST', 'ENOTEMPTY'].includes(error.code)) throw error;
|
|
78
|
+
}
|
|
79
|
+
try {
|
|
80
|
+
for (const other of readdirSync(lock)) {
|
|
81
|
+
const pid = /^(\d+)-[a-f0-9-]+$/.exec(other)?.[1];
|
|
82
|
+
if (!pid) continue;
|
|
83
|
+
try {
|
|
84
|
+
process.kill(Number(pid), 0);
|
|
85
|
+
} catch (error) {
|
|
86
|
+
if (error.code === 'ESRCH') releaseLock(lock, other);
|
|
87
|
+
else if (error.code !== 'EPERM') throw error;
|
|
88
|
+
}
|
|
89
|
+
}
|
|
90
|
+
} catch (error) {
|
|
91
|
+
if (error.code !== 'ENOENT') throw error;
|
|
92
|
+
}
|
|
93
|
+
if (Date.now() - start > LOCK_WAIT_MS) throw new Error('could not lock settings: another limitcast command is changing settings');
|
|
94
|
+
Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, 2 + Math.floor(Math.random() * 8));
|
|
95
|
+
}
|
|
96
|
+
return change();
|
|
97
|
+
} finally {
|
|
98
|
+
if (acquired) releaseLock(lock, owner);
|
|
99
|
+
rmSync(candidate, { recursive: true, force: true });
|
|
100
|
+
}
|
|
101
|
+
}
|
|
35
102
|
|
|
36
103
|
/**
|
|
37
104
|
* Change config.json under a lock: read it, let `change` return the new settings (or the same object to leave the file
|
|
38
105
|
* alone), write it. Without the lock, two commands that each read the file and then each write it lose one change.
|
|
39
|
-
* shortcut: two waiters that break the same stale lock in the same instant can both write; fix with a lockfile library if seen.
|
|
40
106
|
* @param {(cfg: any) => any} change
|
|
41
107
|
*/
|
|
42
108
|
export function updateConfig(change) {
|
|
43
|
-
|
|
44
|
-
|
|
45
|
-
const file = join(dir, 'config.json');
|
|
46
|
-
const lock = `${file}.lock`;
|
|
47
|
-
const start = Date.now();
|
|
48
|
-
for (;;) {
|
|
49
|
-
try {
|
|
50
|
-
mkdirSync(lock); // atomic: exactly one process creates it
|
|
51
|
-
break;
|
|
52
|
-
} catch (e) {
|
|
53
|
-
if (/** @type {NodeJS.ErrnoException} */ (e).code !== 'EEXIST') throw e;
|
|
54
|
-
try {
|
|
55
|
-
if (Date.now() - statSync(lock).mtimeMs > LOCK_STALE_MS) rmSync(lock, { recursive: true, force: true });
|
|
56
|
-
} catch {
|
|
57
|
-
/* released while we looked */
|
|
58
|
-
}
|
|
59
|
-
if (Date.now() - start > LOCK_WAIT_MS) throw new Error(`could not lock ${file}: another limitcast command is changing settings`);
|
|
60
|
-
Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, 20);
|
|
61
|
-
}
|
|
62
|
-
}
|
|
63
|
-
try {
|
|
109
|
+
return withStateLock(() => {
|
|
110
|
+
const file = join(stateDir(), 'config.json');
|
|
64
111
|
let cfg = {};
|
|
65
112
|
try {
|
|
66
113
|
cfg = JSON.parse(readFileSync(file, 'utf8'));
|
|
67
|
-
} catch {
|
|
68
|
-
|
|
114
|
+
} catch (error) {
|
|
115
|
+
if (error.code !== 'ENOENT') throw new Error('cannot read settings JSON; preserve config.json and repair it before retrying');
|
|
69
116
|
}
|
|
70
|
-
if (!cfg || typeof cfg !== 'object'
|
|
117
|
+
if (!cfg || typeof cfg !== 'object' || Array.isArray(cfg)) throw new Error('settings JSON must be an object; preserve config.json');
|
|
71
118
|
const next = change(cfg);
|
|
72
119
|
if (next !== cfg) writeAtomic(file, JSON.stringify(next));
|
|
73
|
-
}
|
|
74
|
-
rmSync(lock, { recursive: true, force: true });
|
|
75
|
-
}
|
|
120
|
+
});
|
|
76
121
|
}
|
|
77
122
|
|
|
78
123
|
/**
|
package/src/subagents.mjs
CHANGED
|
@@ -2,12 +2,15 @@
|
|
|
2
2
|
import { appendFileSync, existsSync, mkdirSync, readFileSync } from 'node:fs';
|
|
3
3
|
import { homedir } from 'node:os';
|
|
4
4
|
import { join } from 'node:path';
|
|
5
|
+
import { fmtUsd } from './prices.mjs';
|
|
5
6
|
import { stateDir, updateConfig } from './store.mjs';
|
|
6
7
|
|
|
7
8
|
// Subagent receipts and budgets. A SubagentStop hook prices each finished subagent against the 5-hour window
|
|
8
9
|
// (from the user's own calibration) and logs it; the guard holds new subagents once a window's budget is spent.
|
|
9
10
|
|
|
10
|
-
/** @typedef {{t:number, id?:string, sid?:string, type?:string, calls:number, fresh:number, read:number, pct?:number}} SubagentEntry
|
|
11
|
+
/** @typedef {{t:number, id?:string, sid?:string, type?:string, src?:'claude'|'codex'|'grok', calls:number, fresh:number, read:number, pct?:number, usd?:number}} SubagentEntry
|
|
12
|
+
* src: the tool that ran it (absent = Claude Code, before receipts covered the others); pct: % of Claude's 5-hour window;
|
|
13
|
+
* usd: API-equivalent dollars (Codex and Grok, which have no 5-hour calibration) */
|
|
11
14
|
|
|
12
15
|
const ledger = () => join(stateDir(), 'subagents.jsonl');
|
|
13
16
|
const configFile = () => join(stateDir(), 'config.json');
|
|
@@ -45,10 +48,13 @@ export function subagentUsage(path) {
|
|
|
45
48
|
* @param {string} type
|
|
46
49
|
* @param {{fresh:number, read:number, calls:number}} u
|
|
47
50
|
* @param {number|null} pct
|
|
51
|
+
* @param {number|null} [usd] API-equivalent dollars, for a tool with no 5-hour calibration
|
|
48
52
|
*/
|
|
49
|
-
export function receiptMessage(type, u, pct) {
|
|
53
|
+
export function receiptMessage(type, u, pct, usd = null) {
|
|
50
54
|
const what = type ? `that ${type} subagent` : 'that subagent';
|
|
51
55
|
const calls = `${u.calls} call${u.calls === 1 ? '' : 's'}`;
|
|
56
|
+
if (pct === null && usd !== null)
|
|
57
|
+
return `limitcast: ${what} used ${k(u.fresh + u.read)} tokens, ${k(u.fresh)} of them new (${calls}): about ${fmtUsd(usd)} at API list prices.`;
|
|
52
58
|
if (pct === null) return `limitcast: ${what} used ${k(u.fresh + u.read)} tokens, ${k(u.fresh)} of them new (${calls}).`;
|
|
53
59
|
return `limitcast: ${what} used ≈${pct < 1 ? pct.toFixed(2) : pct.toFixed(1)}% of your 5-hour window (${calls}, ${k(u.fresh)} new tokens).`;
|
|
54
60
|
}
|
|
@@ -67,9 +73,12 @@ const NOTICE_MIN_PCT = 1; // a typical run under 1% of a window is not worth a m
|
|
|
67
73
|
* @param {SubagentEntry[]} entries
|
|
68
74
|
* @param {unknown} type the subagent type about to start
|
|
69
75
|
* @param {{pct:number, verdict:string}|undefined} win the current 5-hour window
|
|
76
|
+
* @param {'claude'|'codex'|'grok'} [src] the tool about to spawn it: only its own receipts count (type names differ by tool)
|
|
70
77
|
*/
|
|
71
|
-
export function spawnNotice(entries, type, win) {
|
|
72
|
-
const
|
|
78
|
+
export function spawnNotice(entries, type, win, src = 'claude') {
|
|
79
|
+
const mine = entries.filter((e) => (e.src ?? 'claude') === src);
|
|
80
|
+
if (src !== 'claude') return dollarNotice(mine, type, win);
|
|
81
|
+
const priced = mine.filter((e) => typeof e.pct === 'number');
|
|
73
82
|
const same = typeof type === 'string' && type ? priced.filter((e) => e.type === type) : [];
|
|
74
83
|
const runs = same.length >= NOTICE_MIN_RUNS ? same : priced;
|
|
75
84
|
if (runs.length < NOTICE_MIN_RUNS) return null;
|
|
@@ -82,6 +91,28 @@ export function spawnNotice(entries, type, win) {
|
|
|
82
91
|
return `limitcast: ${who} cost you a median ≈${pct1(median)}% (max ≈${pct1(sorted.at(-1) ?? 0)}%) of a 5-hour window over ${runs.length} runs${used}.`;
|
|
83
92
|
}
|
|
84
93
|
|
|
94
|
+
const NOTICE_MIN_USD = 0.1; // the dollar counterpart of the 1% floor
|
|
95
|
+
|
|
96
|
+
/**
|
|
97
|
+
* The same hint for Codex and Grok, which have no 5-hour calibration: what that kind has cost in API-equivalent dollars.
|
|
98
|
+
* @param {SubagentEntry[]} entries receipts of the spawning tool
|
|
99
|
+
* @param {unknown} type
|
|
100
|
+
* @param {{pct:number, verdict:string}|undefined} win
|
|
101
|
+
*/
|
|
102
|
+
function dollarNotice(entries, type, win) {
|
|
103
|
+
const priced = entries.filter((e) => typeof e.usd === 'number');
|
|
104
|
+
const same = typeof type === 'string' && type ? priced.filter((e) => e.type === type) : [];
|
|
105
|
+
const runs = same.length >= NOTICE_MIN_RUNS ? same : priced;
|
|
106
|
+
if (runs.length < NOTICE_MIN_RUNS) return null;
|
|
107
|
+
const sorted = runs.map((e) => /** @type {number} */ (e.usd)).sort((a, b) => a - b);
|
|
108
|
+
const mid = sorted.length >> 1;
|
|
109
|
+
const median = sorted.length % 2 ? sorted[mid] : (sorted[mid - 1] + sorted[mid]) / 2;
|
|
110
|
+
if (median < NOTICE_MIN_USD && win?.verdict !== 'NEAR') return null;
|
|
111
|
+
const who = runs === same ? `${type} subagents have` : 'Your subagents have';
|
|
112
|
+
const used = win ? `; this window is ${Math.round(win.pct)}% used` : '';
|
|
113
|
+
return `limitcast: ${who} cost a median ≈${fmtUsd(median)} (max ≈${fmtUsd(sorted.at(-1) ?? 0)}) at API list prices over ${runs.length} runs${used}.`;
|
|
114
|
+
}
|
|
115
|
+
|
|
85
116
|
/** @param {SubagentEntry} e */
|
|
86
117
|
export function logSubagent(e) {
|
|
87
118
|
mkdirSync(stateDir(), { recursive: true });
|
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
|
-
*
|
|
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
|
|
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
|
|
55
|
-
const label =
|
|
56
|
-
const pct =
|
|
57
|
-
|
|
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,16 +1,15 @@
|
|
|
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
|
-
// PreToolUse: a
|
|
7
|
+
// PreToolUse: a native Read/Grep whose recent results are fat is bounded before it runs.
|
|
8
8
|
// Rewriting a limit that is already present but huge keeps the call and caps it. Bash and WebFetch are left
|
|
9
9
|
// alone: they have no limit argument, so a missing one is every call. Stats come from `report --why` / `--jobs`.
|
|
10
10
|
|
|
11
11
|
export const FAT_AVG = 5_000;
|
|
12
12
|
export const MIN_CALLS = 3;
|
|
13
|
-
const MCP_CAP = 100;
|
|
14
13
|
const READ_CAP = 400;
|
|
15
14
|
const LIMIT_KEYS = new Set(['limit', 'max_results', 'maxresults', 'page_size', 'pagesize', 'top_k', 'topk', 'first']);
|
|
16
15
|
|
|
@@ -47,6 +46,52 @@ export function loadToolStats() {
|
|
|
47
46
|
}
|
|
48
47
|
}
|
|
49
48
|
|
|
49
|
+
// Codex and Grok have no per-tool attribution report to feed the stats, so the tool-check hook records the size of each
|
|
50
|
+
// result it sees: a tool name and a token estimate per line, never the result. The newest 1000 lines are the stats.
|
|
51
|
+
const LIVE_LINES = 1000;
|
|
52
|
+
const LIVE_PRUNE_BYTES = 120_000;
|
|
53
|
+
const liveFile = (/** @type {string} */ host) => join(stateDir(), `tool-sizes-${host}.jsonl`);
|
|
54
|
+
|
|
55
|
+
/**
|
|
56
|
+
* @param {string} host
|
|
57
|
+
* @param {string} key a toolKey
|
|
58
|
+
* @param {number} tokens estimated size of one result
|
|
59
|
+
* shortcut: the trim can drop a line another hook appends in that instant; it only blurs an average.
|
|
60
|
+
*/
|
|
61
|
+
export function recordToolSize(host, key, tokens) {
|
|
62
|
+
mkdirSync(stateDir(), { recursive: true });
|
|
63
|
+
const file = liveFile(host);
|
|
64
|
+
appendFileSync(file, `${JSON.stringify({ k: key, n: Math.round(tokens) })}\n`);
|
|
65
|
+
if (statSync(file).size > LIVE_PRUNE_BYTES) writeAtomic(file, `${readFileSync(file, 'utf8').trim().split('\n').slice(-LIVE_LINES).join('\n')}\n`);
|
|
66
|
+
}
|
|
67
|
+
|
|
68
|
+
/**
|
|
69
|
+
* Average result size per tool for a host that records them live. Empty until the hook has seen some calls.
|
|
70
|
+
* @param {string} host
|
|
71
|
+
* @returns {Record<string, ToolStat>}
|
|
72
|
+
*/
|
|
73
|
+
export function loadLiveStats(host) {
|
|
74
|
+
/** @type {Map<string, {tokens:number, calls:number}>} */
|
|
75
|
+
const sums = new Map();
|
|
76
|
+
try {
|
|
77
|
+
for (const line of readFileSync(liveFile(host), 'utf8').trim().split('\n').slice(-LIVE_LINES)) {
|
|
78
|
+
try {
|
|
79
|
+
const { k, n } = JSON.parse(line);
|
|
80
|
+
if (typeof k !== 'string' || !Number.isFinite(n)) continue;
|
|
81
|
+
const e = sums.get(k) ?? { tokens: 0, calls: 0 };
|
|
82
|
+
e.tokens += n;
|
|
83
|
+
e.calls += 1;
|
|
84
|
+
sums.set(k, e);
|
|
85
|
+
} catch {
|
|
86
|
+
/* a partial line */
|
|
87
|
+
}
|
|
88
|
+
}
|
|
89
|
+
} catch {
|
|
90
|
+
return {};
|
|
91
|
+
}
|
|
92
|
+
return toolStats(sums);
|
|
93
|
+
}
|
|
94
|
+
|
|
50
95
|
/**
|
|
51
96
|
* Limit-shaped numbers anywhere in the arguments, a few levels down (MCP tools nest them).
|
|
52
97
|
* @param {unknown} input
|
|
@@ -90,10 +135,14 @@ const k = (/** @type {number} */ n) => `${Math.max(1, Math.round(n / 1000))}k`;
|
|
|
90
135
|
* @param {string} toolName
|
|
91
136
|
* @param {unknown} input
|
|
92
137
|
* @param {Record<string, ToolStat>} stats
|
|
138
|
+
* @param {{host?:'claude'|'codex'|'grok', rewrite?:boolean}} [o] rewrite: false for a host that may not honor a rewritten
|
|
139
|
+
* input (Codex), so a limit that is too large is denied with the number to use instead of being lowered in place
|
|
93
140
|
* @returns {{deny:string}|{updatedInput:any, reason:string}|null}
|
|
94
141
|
*/
|
|
95
|
-
export function toolLimitDecision(toolName, input, stats) {
|
|
96
|
-
const key = toolKey(toolName);
|
|
142
|
+
export function toolLimitDecision(toolName, input, stats, { host = 'claude', rewrite = true } = {}) {
|
|
143
|
+
const key = toolKey(toolName, host);
|
|
144
|
+
// MCP argument names do not establish pagination or read-only semantics. Their PostToolUse notices remain available.
|
|
145
|
+
if (toolName.startsWith('mcp__') || key.startsWith('mcp:')) return null;
|
|
97
146
|
const stat = stats?.[key];
|
|
98
147
|
if (!stat || stat.calls < MIN_CALLS || stat.avg < FAT_AVG) return null;
|
|
99
148
|
const args = typeof input === 'string' ? tryJson(input) : input;
|
|
@@ -106,12 +155,17 @@ export function toolLimitDecision(toolName, input, stats) {
|
|
|
106
155
|
deny: `limitcast: Grep results average ≈${k(stat.avg)} tokens a call over ${stat.calls} calls. Add a path or a glob, then retry. Set LIMITCAST_ALLOW=1 to run it as written.`,
|
|
107
156
|
};
|
|
108
157
|
}
|
|
109
|
-
if (toolName !== 'Read' && key !== 'Read'
|
|
110
|
-
const cap =
|
|
111
|
-
const limits = findLimits(obj);
|
|
158
|
+
if (toolName !== 'Read' && key !== 'Read') return null;
|
|
159
|
+
const cap = READ_CAP;
|
|
160
|
+
const limits = findLimits({ limit: obj.limit });
|
|
112
161
|
if (limits.some((f) => f.value > 0 && f.value <= cap)) return null;
|
|
113
162
|
const big = limits.find((f) => f.value > cap);
|
|
114
163
|
const label = toolName === 'Read' || key === 'Read' ? 'Read' : key.replace(/^mcp:/, '');
|
|
164
|
+
if (big && !rewrite) {
|
|
165
|
+
return {
|
|
166
|
+
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.`,
|
|
167
|
+
};
|
|
168
|
+
}
|
|
115
169
|
if (big) {
|
|
116
170
|
return {
|
|
117
171
|
updatedInput: setAt(obj, big.path, cap),
|