limitcast 0.19.4 → 0.20.1
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 +9 -8
- package/package.json +2 -2
- package/src/apply.mjs +123 -114
- package/src/codex.mjs +70 -51
- package/src/forecast.mjs +1 -1
- package/src/grok.mjs +38 -29
- package/src/guard.mjs +1 -1
- package/src/install.mjs +3 -14
- package/src/optimize-cli.mjs +52 -4
- package/src/optimize.mjs +48 -11
- package/src/store.mjs +100 -36
- package/src/toollimit.mjs +6 -5
- package/src/transaction.mjs +93 -0
- package/src/trim.mjs +20 -8
- package/src/usage.mjs +26 -10
|
@@ -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/trim.mjs
CHANGED
|
@@ -6,7 +6,11 @@ import { memoryDir } from './memory.mjs';
|
|
|
6
6
|
import { fmt } from './report.mjs';
|
|
7
7
|
|
|
8
8
|
/** @typedef {import('./usage.mjs').Usage} Usage */
|
|
9
|
-
/** @typedef {{skills:Set<string>, mcp:Set<string
|
|
9
|
+
/** @typedef {{skills:Set<string>, mcp:Set<string>, observed?:boolean, complete?:boolean}} Activity skills and MCP servers used in the period */
|
|
10
|
+
|
|
11
|
+
export const activityKnown = (/** @type {Activity} */ activity) => activity.observed !== false && activity.complete !== false;
|
|
12
|
+
export const UNKNOWN_ACTIVITY =
|
|
13
|
+
'Usage history is missing or incomplete; no configuration changes are authorized. Unverified servers and skills stay on.';
|
|
10
14
|
|
|
11
15
|
const DESC_CAP = 1536; // Claude Code's default skillListingMaxDescChars
|
|
12
16
|
|
|
@@ -129,9 +133,11 @@ const norm = (s) => s.toLowerCase().replace(/[^a-z0-9]/g, '_');
|
|
|
129
133
|
* @param {Activity} used
|
|
130
134
|
*/
|
|
131
135
|
export function savings(c, used) {
|
|
132
|
-
const unusedSkills =
|
|
136
|
+
const unusedSkills = activityKnown(used)
|
|
137
|
+
? c.skills.filter((s) => !s.hidden && !skillUsed(s.name, used.skills)).sort((a, b) => b.tokens - a.tokens)
|
|
138
|
+
: [];
|
|
133
139
|
const usedMcp = new Set([...used.mcp].map(norm));
|
|
134
|
-
const unusedMcp = c.mcp.filter((s) => !usedMcp.has(norm(s)));
|
|
140
|
+
const unusedMcp = activityKnown(used) ? c.mcp.filter((s) => !usedMcp.has(norm(s))) : [];
|
|
135
141
|
return { unusedSkills, skillTokens: unusedSkills.reduce((a, s) => a + s.tokens, 0), unusedMcp };
|
|
136
142
|
}
|
|
137
143
|
|
|
@@ -143,6 +149,7 @@ export function savings(c, used) {
|
|
|
143
149
|
* @param {boolean} [share] totals only, including when no startup transcript is available
|
|
144
150
|
*/
|
|
145
151
|
export function trimReport(base, c, used, days, share = false) {
|
|
152
|
+
if (share && !activityKnown(used)) return `${UNKNOWN_ACTIVITY}\nTotals unavailable. https://limitcast.dev`;
|
|
146
153
|
const s = savings(c, used);
|
|
147
154
|
const fileTokens = c.files.reduce((a, f) => a + f.tokens, 0);
|
|
148
155
|
const visible = c.skills.filter((k) => !k.hidden);
|
|
@@ -156,6 +163,7 @@ export function trimReport(base, c, used, days, share = false) {
|
|
|
156
163
|
'Totals only; no configuration names or paths. https://limitcast.dev',
|
|
157
164
|
].join('\n');
|
|
158
165
|
const lines = ['# limitcast trim', ''];
|
|
166
|
+
if (!activityKnown(used)) lines.push(UNKNOWN_ACTIVITY, '');
|
|
159
167
|
if (base) {
|
|
160
168
|
lines.push(
|
|
161
169
|
`Your recorded Claude Code sessions start at **${fmt(base.median)} tokens** before your first message (median of ${base.sessions} interactive sessions, max ${fmt(base.max)}).`,
|
|
@@ -172,7 +180,7 @@ export function trimReport(base, c, used, days, share = false) {
|
|
|
172
180
|
`- **Hide ${s.unusedSkills.length} skills you haven't used in ${days} days** (~${fmt(s.skillTokens)} tokens): ${names.join(', ')}${s.unusedSkills.length > 12 ? ', ...' : ''}.`,
|
|
173
181
|
' In `~/.claude/settings.json`, set each to `"user-invocable-only"` under `skillOverrides`: `/name` still works, the model just stops seeing it.',
|
|
174
182
|
);
|
|
175
|
-
} else if (visible.length) lines.push(`- Every visible skill was used in the last ${days} days.`);
|
|
183
|
+
} else if (visible.length && activityKnown(used)) lines.push(`- Every visible skill was used in the last ${days} days.`);
|
|
176
184
|
if (s.unusedMcp.length) {
|
|
177
185
|
lines.push(
|
|
178
186
|
`- **Disable ${s.unusedMcp.length} MCP servers you haven't used in ${days} days**: ${s.unusedMcp.join(', ')}.`,
|
|
@@ -210,6 +218,7 @@ const tok = (/** @type {number} */ chars) => Math.round(chars / 4);
|
|
|
210
218
|
* @param {Activity|null} [usedMonth] servers used in 30 days. When set, only servers missing here are removable.
|
|
211
219
|
*/
|
|
212
220
|
export function measuredSavings(pieces, used, keep = [], usedMonth = null) {
|
|
221
|
+
const verified = activityKnown(used) && activityKnown(usedMonth ?? used);
|
|
213
222
|
const usedMcp = new Set([...used.mcp].map(norm));
|
|
214
223
|
const month = usedMonth ? new Set([...usedMonth.mcp].map(norm)) : null;
|
|
215
224
|
// Instructions and tool names spell a server differently ("claude.ai Postman" / "claude_ai_Postman"): merge by normalized name.
|
|
@@ -227,10 +236,10 @@ export function measuredSavings(pieces, used, keep = [], usedMonth = null) {
|
|
|
227
236
|
const skills = pieces.filter((p) => p.group === 'Skill listing' && !skillUsed(p.name, used.skills)).sort((a, b) => b.chars - a.chars);
|
|
228
237
|
const kept = [...mcp.values(), ...skills].filter((x) => keep.some((k) => norm(k) === norm(x.name))).map((x) => x.name);
|
|
229
238
|
const isKept = (/** @type {{name:string}} */ x) => kept.includes(x.name);
|
|
230
|
-
const unusedMcp = [...mcp.values()].filter((m) => !isKept(m)).sort((a, b) => b.chars - a.chars);
|
|
239
|
+
const unusedMcp = verified ? [...mcp.values()].filter((m) => !isKept(m)).sort((a, b) => b.chars - a.chars) : [];
|
|
231
240
|
const standingMcp = month ? unusedMcp.filter((m) => month.has(norm(m.name))) : [];
|
|
232
|
-
const staleMcp = month ? unusedMcp.filter((m) => !month.has(norm(m.name))) : unusedMcp;
|
|
233
|
-
const unusedSkills = skills.filter((s) => !isKept(s));
|
|
241
|
+
const staleMcp = verified ? (month ? unusedMcp.filter((m) => !month.has(norm(m.name))) : unusedMcp) : [];
|
|
242
|
+
const unusedSkills = verified ? skills.filter((s) => !isKept(s)) : [];
|
|
234
243
|
const chars = staleMcp.reduce((a, m) => a + m.chars, 0) + unusedSkills.reduce((a, s) => a + s.chars, 0);
|
|
235
244
|
return { unusedMcp, standingMcp, staleMcp, unusedSkills, tokens: tok(chars), kept };
|
|
236
245
|
}
|
|
@@ -248,6 +257,7 @@ export function startupReport(base, b, used, days, keep = [], usedMonth = null)
|
|
|
248
257
|
const s = measuredSavings(b.pieces, used, keep, usedMonth);
|
|
249
258
|
const median = base?.median ?? 0;
|
|
250
259
|
const lines = ['# limitcast trim', ''];
|
|
260
|
+
if (!activityKnown(used) || !activityKnown(usedMonth ?? used)) lines.push(UNKNOWN_ACTIVITY, '');
|
|
251
261
|
if (base) {
|
|
252
262
|
lines.push(
|
|
253
263
|
`Your recorded Claude Code sessions start at **${fmt(median)} tokens** before your first message (median of ${base.sessions} interactive sessions).`,
|
|
@@ -294,7 +304,8 @@ export function startupReport(base, b, used, days, keep = [], usedMonth = null)
|
|
|
294
304
|
);
|
|
295
305
|
}
|
|
296
306
|
if (s.kept.length) lines.push(`- **Would keep ${s.kept.length} on your keep-list** (\`trim --apply\` never touches them): ${s.kept.join(', ')}.`);
|
|
297
|
-
else if (!s.unusedMcp.length && !s.unusedSkills.length
|
|
307
|
+
else if (!s.unusedMcp.length && !s.unusedSkills.length && activityKnown(used) && activityKnown(usedMonth ?? used))
|
|
308
|
+
lines.push('- Nothing unused. Everything that loads was used in the period.');
|
|
298
309
|
|
|
299
310
|
/** @type {Map<string, number>} */
|
|
300
311
|
const groups = new Map();
|
|
@@ -334,6 +345,7 @@ export function startupReport(base, b, used, days, keep = [], usedMonth = null)
|
|
|
334
345
|
* @param {Activity|null} [usedMonth] servers used in 30 days
|
|
335
346
|
*/
|
|
336
347
|
export function shareSummary(base, b, used, days, keep = [], usedMonth = null) {
|
|
348
|
+
if (!activityKnown(used) || !activityKnown(usedMonth ?? used)) return `${UNKNOWN_ACTIVITY}\nTotals unavailable. https://limitcast.dev`;
|
|
337
349
|
const s = measuredSavings(b.pieces, used, keep, usedMonth);
|
|
338
350
|
/** @type {Map<string, number>} */
|
|
339
351
|
const groups = new Map();
|
package/src/usage.mjs
CHANGED
|
@@ -61,20 +61,30 @@ export function claudeUsage(line, seen, session) {
|
|
|
61
61
|
* @param {import('./trim.mjs').Activity} act
|
|
62
62
|
*/
|
|
63
63
|
export function claudeActivity(line, act) {
|
|
64
|
-
if (line.
|
|
65
|
-
for (const m of line.matchAll(/<command-name>\/?([^<\s]+)<\/command-name>/g)) act.skills.add(m[1]);
|
|
66
|
-
}
|
|
67
|
-
if (!line.includes('"name":"Skill"') && !line.includes('"name":"mcp__')) return;
|
|
64
|
+
if (!line.trim()) return;
|
|
68
65
|
let ev;
|
|
69
66
|
try {
|
|
70
67
|
ev = JSON.parse(line);
|
|
71
68
|
} catch {
|
|
69
|
+
act.complete = false;
|
|
72
70
|
return;
|
|
73
71
|
}
|
|
74
72
|
const content = ev?.message?.content;
|
|
73
|
+
const texts =
|
|
74
|
+
typeof content === 'string'
|
|
75
|
+
? [content]
|
|
76
|
+
: Array.isArray(content)
|
|
77
|
+
? content.filter((c) => c?.type === 'text' && typeof c.text === 'string').map((c) => c.text)
|
|
78
|
+
: [];
|
|
79
|
+
for (const text of texts) for (const m of text.matchAll(/<command-name>\/?([^<\s]+)<\/command-name>/g)) act.skills.add(m[1]);
|
|
75
80
|
if (!Array.isArray(content)) return;
|
|
81
|
+
if (ev.type === 'assistant') act.observed = true;
|
|
76
82
|
for (const c of content) {
|
|
77
|
-
if (c?.type !== 'tool_use'
|
|
83
|
+
if (c?.type !== 'tool_use') continue;
|
|
84
|
+
if (typeof c.name !== 'string') {
|
|
85
|
+
act.complete = false;
|
|
86
|
+
continue;
|
|
87
|
+
}
|
|
78
88
|
if (c.name === 'Skill' && c.input?.skill) act.skills.add(String(c.input.skill));
|
|
79
89
|
else if (c.name.startsWith('mcp__')) act.mcp.add(c.name.split('__')[1] ?? '');
|
|
80
90
|
}
|
|
@@ -226,6 +236,10 @@ function summaryKind(dir) {
|
|
|
226
236
|
* @returns {Promise<Usage[]>}
|
|
227
237
|
*/
|
|
228
238
|
export async function readUsage(since, roots = {}, activity) {
|
|
239
|
+
if (activity) {
|
|
240
|
+
activity.observed = false;
|
|
241
|
+
activity.complete = true;
|
|
242
|
+
}
|
|
229
243
|
/** @type {Usage[]} */
|
|
230
244
|
const out = [];
|
|
231
245
|
// Parsed transcripts are cached by size and mtime: only new or changed ones are read again.
|
|
@@ -235,7 +249,7 @@ export async function readUsage(since, roots = {}, activity) {
|
|
|
235
249
|
const next = {};
|
|
236
250
|
/**
|
|
237
251
|
* @param {string} file
|
|
238
|
-
* @param {(file:string)=>Promise<{u:Usage[], a?:{skills:string[], mcp:string[]}}>} parse
|
|
252
|
+
* @param {(file:string)=>Promise<{u:Usage[], a?:{skills:string[], mcp:string[], observed:boolean, complete:boolean}}>} parse
|
|
239
253
|
*/
|
|
240
254
|
const cached = async (file, parse) => {
|
|
241
255
|
const st = statSync(file);
|
|
@@ -251,17 +265,19 @@ export async function readUsage(since, roots = {}, activity) {
|
|
|
251
265
|
const seen = new Set();
|
|
252
266
|
const session = basename(f, '.jsonl');
|
|
253
267
|
/** @type {import('./trim.mjs').Activity} */
|
|
254
|
-
const act = { skills: new Set(), mcp: new Set() };
|
|
268
|
+
const act = { skills: new Set(), mcp: new Set(), observed: false, complete: true };
|
|
255
269
|
const u = [];
|
|
256
270
|
for await (const line of lines(f)) {
|
|
257
271
|
claudeActivity(line, act);
|
|
258
272
|
const x = claudeUsage(line, seen, session);
|
|
259
273
|
if (x) u.push(x);
|
|
260
274
|
}
|
|
261
|
-
return { u, a: { skills: [...act.skills], mcp: [...act.mcp] } };
|
|
275
|
+
return { u, a: { skills: [...act.skills], mcp: [...act.mcp], observed: act.observed, complete: act.complete } };
|
|
262
276
|
});
|
|
263
277
|
for (const u of e.u) if (u.t >= since) out.push(u);
|
|
264
278
|
if (activity && e.a) {
|
|
279
|
+
activity.observed ||= e.a.observed === true;
|
|
280
|
+
activity.complete &&= e.a.complete === true;
|
|
265
281
|
for (const s of e.a.skills) activity.skills.add(s);
|
|
266
282
|
for (const m of e.a.mcp) activity.mcp.add(m);
|
|
267
283
|
}
|
|
@@ -296,10 +312,10 @@ export async function readUsage(since, roots = {}, activity) {
|
|
|
296
312
|
}
|
|
297
313
|
|
|
298
314
|
const CACHE_KEEP_MS = 35 * 86400_000;
|
|
299
|
-
const USAGE_CACHE_VERSION =
|
|
315
|
+
const USAGE_CACHE_VERSION = 6; // 6: text-block slash commands; 5: activity completeness. Re-read older entries before pruning.
|
|
300
316
|
const usageCacheFile = () => join(stateDir(), 'usage-cache.json');
|
|
301
317
|
|
|
302
|
-
/** @returns {Record<string, {s:number, m:number, u:Usage[], a?:{skills:string[], mcp:string[]}}>} */
|
|
318
|
+
/** @returns {Record<string, {s:number, m:number, u:Usage[], a?:{skills:string[], mcp:string[], observed:boolean, complete:boolean}}>} */
|
|
303
319
|
function loadUsageCache() {
|
|
304
320
|
try {
|
|
305
321
|
const d = JSON.parse(readFileSync(usageCacheFile(), 'utf8'));
|