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.
@@ -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>}} Activity skills and MCP servers used in the period */
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 = c.skills.filter((s) => !s.hidden && !skillUsed(s.name, used.skills)).sort((a, b) => b.tokens - a.tokens);
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) lines.push('- Nothing unused. Everything that loads was used in the period.');
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.includes('<command-name>')) {
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' || typeof c.name !== 'string') continue;
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 = 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
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'));