limitcast 0.15.0 → 0.17.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/src/pilot.mjs ADDED
@@ -0,0 +1,92 @@
1
+ // @ts-check
2
+ const DAY = 86400_000;
3
+
4
+ /** Local operator-entered evidence only. Missing follow-up is unknown, never invented churn.
5
+ * @param {unknown} input
6
+ * @param {number} now
7
+ */
8
+ export function pilotMetrics(input, now) {
9
+ if (!Array.isArray(input) || !Number.isFinite(now)) throw new Error('Expected a participant array and a valid as-of timestamp.');
10
+ const ids = new Set();
11
+ const date = (value, field) => {
12
+ if (value === undefined || value === null) return null;
13
+ if (typeof value !== 'string' || !/^\d{4}-\d{2}-\d{2}T.*Z$/.test(value) || !Number.isFinite(Date.parse(value)))
14
+ throw new Error(`Invalid UTC timestamp: ${field}`);
15
+ const parsed = Date.parse(value);
16
+ if (new Date(parsed).toISOString().slice(0, 10) !== value.slice(0, 10)) throw new Error(`Invalid UTC timestamp: ${field}`);
17
+ return parsed;
18
+ };
19
+ const people = [];
20
+ for (const p of input) {
21
+ if (!p || typeof p !== 'object' || typeof p.id !== 'string' || !p.id || ids.has(p.id))
22
+ throw new Error('Each participant needs a unique nonempty id.');
23
+ ids.add(p.id);
24
+ if (p.consent !== true) continue;
25
+ const invited = date(p.invitedAt, 'invitedAt');
26
+ if (invited === null) throw new Error('A consenting participant needs invitedAt.');
27
+ const activated = date(p.activatedAt, 'activatedAt');
28
+ const paid = date(p.paidAt, 'paidAt');
29
+ const due = date(p.renewalDueAt, 'renewalDueAt');
30
+ const renewed = date(p.renewedAt, 'renewedAt');
31
+ if (activated !== null && activated < invited) throw new Error('activatedAt precedes invitedAt.');
32
+ if (due !== null && (paid === null || due <= paid)) throw new Error('renewalDueAt needs an earlier paidAt.');
33
+ if (renewed !== null && (due === null || renewed < due)) throw new Error('renewedAt needs a reached renewalDueAt.');
34
+ if (p.checkIns !== undefined && !Array.isArray(p.checkIns)) throw new Error('checkIns must be an array.');
35
+ const checks = (p.checkIns ?? [])
36
+ .map((c) => {
37
+ if (!c || typeof c !== 'object' || typeof c.active !== 'boolean' || typeof c.protectionEnabled !== 'boolean' || typeof c.useful !== 'boolean')
38
+ throw new Error('Each check-in needs active, protectionEnabled and useful booleans.');
39
+ const at = date(c.at, 'checkIns.at');
40
+ if (at === null || activated === null || at < activated) throw new Error('A check-in needs an activation and a later timestamp.');
41
+ return { ...c, at };
42
+ })
43
+ .filter((c) => c.at <= now)
44
+ .sort((a, b) => b.at - a.at);
45
+ if (invited <= now)
46
+ people.push({
47
+ activated: activated !== null && activated <= now ? activated : null,
48
+ paid: p.paymentVerified === true && paid !== null && paid <= now,
49
+ due,
50
+ renewed: p.renewalVerified === true && renewed !== null && renewed <= now,
51
+ checks,
52
+ });
53
+ }
54
+ const retention = (day) => {
55
+ const eligible = people.filter((p) => p.activated !== null && now >= p.activated + day * DAY);
56
+ let retained = 0;
57
+ let inactive = 0;
58
+ for (const p of eligible) {
59
+ const c = p.checks.find((c) => c.at >= p.activated + day * DAY && c.at < p.activated + (day + 7) * DAY);
60
+ if (c?.active === true) retained++;
61
+ if (c?.active === false) inactive++;
62
+ }
63
+ return {
64
+ eligible: eligible.length,
65
+ retained,
66
+ inactive,
67
+ unknown: eligible.length - retained - inactive,
68
+ confirmedFraction: eligible.length ? retained / eligible.length : null,
69
+ };
70
+ };
71
+ const recent = people.flatMap((p) => (p.checks[0]?.at >= now - 7 * DAY ? [p.checks[0]] : []));
72
+ const renewals = people.filter((p) => p.paid && p.due !== null && p.due <= now);
73
+ return {
74
+ asOf: new Date(now).toISOString(),
75
+ consentingInvited: people.length,
76
+ activated: people.filter((p) => p.activated !== null).length,
77
+ verifiedPaid: people.filter((p) => p.paid).length,
78
+ day7: retention(7),
79
+ day30: retention(30),
80
+ recentCheckIns: {
81
+ observed: recent.length,
82
+ protectionEnabled: recent.filter((c) => c.protectionEnabled).length,
83
+ useful: recent.filter((c) => c.useful).length,
84
+ },
85
+ renewals: {
86
+ eligible: renewals.length,
87
+ verified: renewals.filter((p) => p.renewed).length,
88
+ unconfirmed: renewals.filter((p) => !p.renewed).length,
89
+ },
90
+ note: 'Operator-recorded, consenting cohort only. Unknown follow-up is not churn; unconfirmed renewal is not a verified cancellation. Small cohorts do not establish market-wide demand.',
91
+ };
92
+ }
package/src/results.mjs CHANGED
@@ -5,7 +5,7 @@ import { claudeAccounts, forecast } from './forecast.mjs';
5
5
  import { stateDir } from './store.mjs';
6
6
 
7
7
  /** @typedef {import('./forecast.mjs').Sample} Sample */
8
- /** @typedef {{t:number, src:string, win:string, pct:number, wall:number, reset:number, sid?:string, shadow?:boolean, kind?:string, from?:string, to?:string, type?:string, tokens?:number}} Block t, wall, reset: epoch ms; shadow: a free install's preview, not acted on; kind "switch": a subagent moved to Sonnet instead of blocked, "budget": a subagent held over the budget, "cold": a message held after the prompt cache expired (pct: its cost, tokens: context re-sent), "today": a subagent held once today's share of a weekly window was used up (pct: used today); no kind: a forecast block */
8
+ /** @typedef {{t:number, src:string, win:string, pct:number, wall:number, reset:number, sid?:string, operation?:string, shadow?:boolean, kind?:string, from?:string, to?:string, type?:string, tokens?:number}} Block t, wall, reset: epoch ms; shadow: a free install's preview, not acted on; operation: host-supplied tool call ID when available; kind "switch": a subagent moved to Sonnet instead of blocked, "budget": a subagent held over the budget, "cold": a message held after the prompt cache expired (pct: its cost, tokens: context re-sent), "today": a subagent held once today's share of a weekly window was used up (pct: used today); no kind: a forecast block */
9
9
 
10
10
  const JITTER_MS = 120_000; // Codex resets_at drifts by seconds between events
11
11
  const NAMES = { claude: 'Claude', codex: 'Codex', grok: 'Grok' };
@@ -25,16 +25,32 @@ export function logBlock(b) {
25
25
  /** @param {number} since epoch ms @returns {Block[]} */
26
26
  export function loadBlocks(since) {
27
27
  if (!existsSync(blockFile())) return [];
28
- return readFileSync(blockFile(), 'utf8')
29
- .split('\n')
30
- .flatMap((line) => {
31
- try {
32
- const b = JSON.parse(line);
33
- return b.t >= since ? [b] : [];
34
- } catch {
35
- return [];
36
- }
37
- });
28
+ return distinctBlocks(
29
+ readFileSync(blockFile(), 'utf8')
30
+ .split('\n')
31
+ .flatMap((line) => {
32
+ try {
33
+ const b = JSON.parse(line);
34
+ return b.t >= since ? [b] : [];
35
+ } catch {
36
+ return [];
37
+ }
38
+ }),
39
+ );
40
+ }
41
+
42
+ /** Keep one decision per host operation and tier; unidentified legacy attempts remain visible.
43
+ * @param {Block[]} blocks
44
+ */
45
+ export function distinctBlocks(blocks) {
46
+ const seen = new Set();
47
+ return blocks.filter((b) => {
48
+ if (!b.operation) return true;
49
+ const key = JSON.stringify([b.src, b.sid, b.operation, Boolean(b.shadow)]);
50
+ if (seen.has(key)) return false;
51
+ seen.add(key);
52
+ return true;
53
+ });
38
54
  }
39
55
 
40
56
  /**
@@ -121,7 +137,7 @@ export function resultsStats({ now, days, samples, blocks, pro }) {
121
137
  const hits = limitHits(samples.filter((s) => s.t >= since));
122
138
  const watched = hits.filter((h) => !h.unseen);
123
139
  const leads = hits.flatMap((h) => (h.warnedAt === null ? [] : [Math.round((h.at - h.warnedAt) / 60_000)]));
124
- const mine = blocks.filter((b) => b.t >= since && Boolean(b.shadow) === !pro);
140
+ const mine = distinctBlocks(blocks).filter((b) => b.t >= since && b.t <= now && Boolean(b.shadow) === !pro);
125
141
  const outcomes = blockOutcomes(
126
142
  mine.filter((b) => !b.kind),
127
143
  samples,
@@ -162,7 +178,7 @@ export function resultsShare(st, { days, pro, savedPerSession, notResent = 0 })
162
178
  if (st.switches) parts.push(`${pro ? 'moved' : 'would have moved'} ${st.switches} subagent${st.switches === 1 ? '' : 's'} to Sonnet`);
163
179
  if (st.defaults) parts.push(`${pro ? 'ran' : 'would have run'} ${st.defaults} on the model you set for their type`);
164
180
  if (savedPerSession && savedPerSession > 0) parts.push(`starting context ${fmtK(savedPerSession)} tokens smaller per session`);
165
- if (notResent > 0) parts.push(`${fmtK(notResent)} tokens not re-sent since install`);
181
+ if (pro && notResent > 0) parts.push(`estimated ${fmtK(notResent)} context tokens not re-sent since install vs baseline`);
166
182
  return `${parts[0]} ${parts.slice(1).join('; ')}. https://limitcast.dev`;
167
183
  }
168
184
 
@@ -174,7 +190,7 @@ export function resultsShare(st, { days, pro, savedPerSession, notResent = 0 })
174
190
  */
175
191
  export function weeklyLine(st, savedPerSession, notResent = 0) {
176
192
  const parts = [`${st.hits.length} limit${st.hits.length === 1 ? '' : 's'} reached`];
177
- if (st.leads.length) parts.push(`warned ahead on ${st.leads.length} (avg ${avg(st.leads)} min)`);
193
+ if (st.leads.length) parts.push(`forecast risk on ${st.leads.length} (avg ${avg(st.leads)} min)`);
178
194
  parts.push(`guard blocked ${st.outcomes.length} subagent${st.outcomes.length === 1 ? '' : 's'}`);
179
195
  if (st.switches) parts.push(`moved ${st.switches} to Sonnet`);
180
196
  if (st.defaults) parts.push(`ran ${st.defaults} on their set model`);
@@ -182,7 +198,7 @@ export function weeklyLine(st, savedPerSession, notResent = 0) {
182
198
  if (st.todays) parts.push(`held ${st.todays} once today's share was used`);
183
199
  if (st.colds) parts.push(`caught ${st.colds} cold-cache message${st.colds === 1 ? '' : 's'}`);
184
200
  if (savedPerSession && savedPerSession > 0) parts.push(`starting context ${fmtK(savedPerSession)} tokens smaller`);
185
- if (notResent > 0) parts.push(`${fmtK(notResent)} tokens not re-sent`);
201
+ if (notResent > 0) parts.push(`estimated ${fmtK(notResent)} context tokens not re-sent vs baseline`);
186
202
  return `limitcast this week: ${parts.join(', ')}. Details: limitcast results`;
187
203
  }
188
204
 
package/src/trim.mjs CHANGED
@@ -149,14 +149,14 @@ export function trimReport(base, c, used, days) {
149
149
  const lines = ['# limitcast trim', ''];
150
150
  if (base) {
151
151
  lines.push(
152
- `Every Claude Code session starts at **${fmt(base.median)} tokens** before your first message (median of ${base.sessions} interactive sessions, max ${fmt(base.max)}).`,
152
+ `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)}).`,
153
153
  'That context is re-sent on every turn and to every subagent, so every token you cut stretches your limit windows.',
154
154
  '',
155
155
  );
156
156
  } else lines.push('No interactive Claude Code sessions in the period yet.', '');
157
157
 
158
158
  const pct = base && s.skillTokens ? ` (${Math.round((s.skillTokens / base.median) * 100)}% of your fixed overhead)` : '';
159
- lines.push(`## Measured savings: ~${fmt(s.skillTokens)} tokens per session${pct}`, '');
159
+ lines.push(`## Estimated removable context: ~${fmt(s.skillTokens)} tokens per session${pct}`, '');
160
160
  if (s.unusedSkills.length) {
161
161
  const names = s.unusedSkills.slice(0, 12).map((k) => k.name);
162
162
  lines.push(
@@ -236,13 +236,18 @@ export function startupReport(base, b, used, days, keep = []) {
236
236
  const lines = ['# limitcast trim', ''];
237
237
  if (base) {
238
238
  lines.push(
239
- `Every Claude Code session starts at **${fmt(median)} tokens** before your first message (median of ${base.sessions} interactive sessions).`,
239
+ `Your recorded Claude Code sessions start at **${fmt(median)} tokens** before your first message (median of ${base.sessions} interactive sessions).`,
240
240
  'That context is re-sent on every turn and to every subagent, so every token you cut stretches your limit windows.',
241
241
  '',
242
242
  );
243
243
  }
244
244
  const pct = median ? ` (${Math.round((s.tokens / median) * 100)}% of your starting context)` : '';
245
- lines.push(`## Measured savings: ~${fmt(s.tokens)} tokens per session${pct}`, '', `From things you haven't used in the last ${days} days:`, '');
245
+ lines.push(
246
+ `## Estimated removable context: ~${fmt(s.tokens)} tokens per session${pct}`,
247
+ '',
248
+ `From things you haven't used in the last ${days} days:`,
249
+ '',
250
+ );
246
251
  if (s.unusedMcp.length) {
247
252
  const total = s.unusedMcp.reduce((a, m) => a + m.chars, 0);
248
253
  lines.push(
package/src/value.mjs CHANGED
@@ -13,10 +13,10 @@ import { claudeUsage } from './usage.mjs';
13
13
 
14
14
  /** @typedef {import('./forecast.mjs').Sample} Sample */
15
15
  /** @typedef {import('./results.mjs').Block} Block */
16
- /** @typedef {{at:number, turns:number, savedPerTurn:number}} SessionValue savedPerTurn: tokens below the first measured start */
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, 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}}} 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');
@@ -102,13 +102,13 @@ export async function sessionValue(path, baselineChars) {
102
102
  if (b.entry !== 'cli' || !b.pieces.length) return null;
103
103
  const chars = b.pieces.reduce((a, p) => a + p.chars, 0);
104
104
  const seen = new Set();
105
- let turns = 0;
105
+ const calls = [];
106
106
  const rl = createInterface({ input: createReadStream(path), crlfDelay: Infinity });
107
107
  for await (const line of rl) {
108
108
  const u = claudeUsage(line, seen, '');
109
- if (u && !u.sidechain) turns++;
109
+ if (u && !u.sidechain) calls.push(u.t);
110
110
  }
111
- return { at: b.at, turns, savedPerTurn: Math.max(0, tok(baselineChars - chars)) };
111
+ return { at: b.at, turns: calls.length, savedPerTurn: Math.max(0, tok(baselineChars - chars)), calls };
112
112
  }
113
113
 
114
114
  /**
@@ -118,6 +118,7 @@ export async function sessionValue(path, baselineChars) {
118
118
  */
119
119
  export async function scanSessions(v, { root, baseline, now }) {
120
120
  if (!baseline) return v;
121
+ v.contextSince ??= baseline.at;
121
122
  try {
122
123
  for (const proj of readdirSync(root, { withFileTypes: true })) {
123
124
  if (!proj.isDirectory()) continue;
@@ -125,9 +126,11 @@ export async function scanSessions(v, { root, baseline, now }) {
125
126
  if (!f.isFile() || !f.name.endsWith('.jsonl')) continue;
126
127
  const p = join(root, proj.name, f.name);
127
128
  const st = statSync(p);
128
- if (st.mtimeMs < Math.max(baseline.at, v.scanned) || (st.birthtimeMs || st.mtimeMs) < baseline.at - 86400_000) continue;
129
+ const id = f.name.replace(/\.jsonl$/, '');
130
+ const legacy = v.sessions[id] && !Array.isArray(v.sessions[id].calls);
131
+ if ((!legacy && st.mtimeMs < Math.max(baseline.at, v.scanned)) || (st.birthtimeMs || st.mtimeMs) < baseline.at - 86400_000) continue;
129
132
  const s = await sessionValue(p, baseline.chars);
130
- if (s && s.at >= baseline.at) v.sessions[f.name.replace(/\.jsonl$/, '')] = s;
133
+ if (s && s.at >= baseline.at) v.sessions[id] = s;
131
134
  }
132
135
  }
133
136
  } catch {
@@ -168,6 +171,29 @@ export function valueTotals(v) {
168
171
  };
169
172
  }
170
173
 
174
+ /** Activity in an exact half-open period; never assign an entire session to its start week.
175
+ * @param {Value} v
176
+ * @param {number} since
177
+ * @param {number} until
178
+ */
179
+ export function valuePeriod(v, since, until) {
180
+ let calls = 0;
181
+ let tokens = 0;
182
+ let sessions = 0;
183
+ let legacy = 0;
184
+ for (const s of Object.values(v.sessions)) {
185
+ if (!Array.isArray(s.calls)) {
186
+ if (s.at < until) legacy++;
187
+ continue;
188
+ }
189
+ const n = s.calls.filter((t) => t >= since && t < until).length;
190
+ if (n) sessions++;
191
+ calls += n;
192
+ tokens += n * s.savedPerTurn;
193
+ }
194
+ return { calls, tokens, sessions, legacy };
195
+ }
196
+
171
197
  /**
172
198
  * The "since you installed" section at the top of `limitcast results`.
173
199
  * @param {ReturnType<typeof valueTotals>} t
@@ -177,21 +203,21 @@ export function valueSection(t, { now, pro }) {
177
203
  if (!t.since) return '';
178
204
  const days = Math.max(1, Math.round((now - t.since) / 86400_000));
179
205
  const out = [`## Since limitcast started watching (${new Date(t.since).toLocaleDateString()}, ${days} day${days === 1 ? '' : 's'})`];
180
- if (t.tokens > 0) {
206
+ if (pro && t.tokens > 0) {
181
207
  out.push(
182
- `- **${fmtBig(t.tokens)} tokens not re-sent.** Your sessions now start smaller than the first one limitcast measured, and Claude Code re-sends the starting context on every model call: ${t.turns.toLocaleString()} calls across ${t.sessions} sessions. (Most of it would have been cached input.)`,
208
+ `- **Estimated ${fmtBig(t.tokens)} context tokens not re-sent.** Compared with your first recorded Claude Code starting context: ${t.turns.toLocaleString()} calls across ${t.sessions} sessions. Estimated from characters / 4; most would have been cached input. Project or manual configuration changes can also change this baseline; this is not a causal savings measurement.`,
183
209
  );
184
210
  if (t.windowPct !== null && t.calib)
185
211
  out.push(
186
212
  ` Against your limit: **≈ ${t.windowPct < 1 ? t.windowPct.toFixed(2) : t.windowPct.toFixed(1)}% of a 5-hour window.** From your own readings, 1% of it is about ${fmtBig(Math.round(1e6 / t.calib.fresh))} new tokens or ${fmtBig(Math.round(1e6 / t.calib.read))} cached ones, so cached context is cheap and new tokens (long sessions, subagents) are what run you out.`,
187
213
  );
188
- } else if (t.sessions) {
214
+ } else if (pro && t.sessions) {
189
215
  out.push(`- Starting context: no smaller than when limitcast first measured it. \`limitcast trim\` shows what to cut.`);
190
216
  }
191
217
  if (t.hits) {
192
218
  const avg = t.leads.length ? `, on average ${fmtMin(t.leads.reduce((a, b) => a + b, 0) / t.leads.length)} ahead` : '';
193
219
  out.push(
194
- `- **Warned you before ${t.leads.length} of the ${t.watched} limits it watched you approach**${avg}. (${t.hits} limits reached in all.)`,
220
+ `- **Forecast risk before ${t.leads.length} of the ${t.watched} limits it watched you approach**${avg}. (${t.hits} limits reached in all; replayed from recorded readings, not proof a notification was delivered.)`,
195
221
  );
196
222
  } else out.push('- No limit reached yet.');
197
223
  if (pro) {