@alexeiled/claude-router 1.11.0 → 1.12.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/lib/savings.mjs CHANGED
@@ -1,16 +1,15 @@
1
1
  // Routing vs your model: what each main reply cost at configured list prices on the model that served it, against
2
2
  // the same tokens on the session's own model and effort ("your model"). Counts and dollars only, never text. Pure:
3
- // the hook feeds each reply and keeps the totals in the view and, per session, in $.store under SAVINGS_PREFIX.
3
+ // the hook feeds each reply, keeps the session totals in the view, and keeps each reply by day in usage.mjs's
4
+ // records. The records under SAVINGS_PREFIX are undated history from before those, read and never written.
4
5
 
5
6
  import { effortSharesCache, ratesAt } from './cost.mjs';
6
7
  import { afterResetOf, earlierSince, isRecord } from './records.mjs';
7
8
  import { HISTORY_SHRINK, isSameModel } from './route.mjs';
8
9
 
9
- // Each session keeps its own record under this prefix and its session id: $.store has no atomic update, and Claude
10
- // Code 2.1.296 writes one key under a file lock (observed, not in the types), so sessions finishing turns at the same
11
- // moment do not overwrite each other.
10
+ // Each session kept its own record under this prefix and its session id, as usage.mjs's records are now kept.
12
11
  export const SAVINGS_PREFIX = 'savings:v1:';
13
- // When Reset stats last ran (ms), from any session: a session may still hold its record from before and write it back.
12
+ // When Delete history last ran (ms), from any session: a session may still hold its record from before and write it back.
14
13
  // The activity metrics records (METRICS_PREFIX) use it too.
15
14
  export const SAVINGS_RESET_KEY = 'savings:reset:v1';
16
15
  // Fewer replies than this read "too early": one switch and its cache write dominate a short run.
@@ -157,17 +156,16 @@ export function compareModels(config, states, { usage, served, effort, ttl, now,
157
156
  }
158
157
 
159
158
  // Each model's session totals with this reply's prices added; models without a price for it keep theirs.
160
- export function addReplies(byModel, replies, tier) {
159
+ export function addReplies(byModel, replies) {
161
160
  const next = { ...byModel };
162
161
  for (const [alias, reply] of Object.entries(replies))
163
- next[alias] = addReply(modelEntry(next, alias) ?? emptyTotals(), reply, tier);
162
+ next[alias] = addReply(modelEntry(next, alias) ?? emptyTotals(), reply);
164
163
  return next;
165
164
  }
166
165
 
167
166
  const SUMS = ['routedUsd', 'yoursUsd', 'cheaperUsd', 'strongerUsd', 'switchUsd'];
168
167
 
169
- // A session's totals: replies, the five sums, and per tier (`none`: not chosen by routing) the replies and their
170
- // routed cost, which the pane's bar and share line draw. `stronger` counts replies by the stronger model they ran on.
168
+ // A session's totals: replies and the five sums. `stronger` counts replies by the stronger model they ran on.
171
169
  export function emptyTotals() {
172
170
  return {
173
171
  replies: 0,
@@ -176,18 +174,13 @@ export function emptyTotals() {
176
174
  cheaperUsd: 0,
177
175
  strongerUsd: 0,
178
176
  switchUsd: 0,
179
- tiers: {},
180
- tierUsd: {},
181
177
  stronger: {},
182
178
  };
183
179
  }
184
180
 
185
- export function addReply(totals, reply, tier) {
186
- const key = tier ?? 'none';
181
+ export function addReply(totals, reply) {
187
182
  const next = { ...totals, replies: totals.replies + 1 };
188
183
  for (const sum of SUMS) next[sum] = totals[sum] + reply[sum];
189
- next.tiers = { ...totals.tiers, [key]: (totals.tiers[key] ?? 0) + 1 };
190
- next.tierUsd = { ...totals.tierUsd, [key]: (totals.tierUsd[key] ?? 0) + reply.routedUsd };
191
184
  if (reply.strongerModel)
192
185
  next.stronger = { ...totals.stronger, [reply.strongerModel]: (totals.stronger[reply.strongerModel] ?? 0) + 1 };
193
186
  return next;
@@ -239,14 +232,6 @@ export function mergeSavingsStores(values, resetAt = null) {
239
232
  return merged;
240
233
  }
241
234
 
242
- // A finished turn's totals added to the store at `now`.
243
- export function recordSavingsStore(store, totals, now) {
244
- if (!totals.replies) return store;
245
- const next = { ...store, since: store.since ?? now, replies: store.replies + totals.replies };
246
- for (const sum of SUMS) next[sum] = store[sum] + totals[sum];
247
- return next;
248
- }
249
-
250
235
  const cents = (usd) => Math.round(usd * 100);
251
236
 
252
237
  // What the UI shows for a set of totals, in whole cents so the shown parts add up: the difference is routed less
package/lib/usage.mjs ADDED
@@ -0,0 +1,399 @@
1
+ // Routed usage kept across sessions by local calendar day, so the Usage tab can show any period: each routed main
2
+ // reply's prices against your model (compareModels), its tokens, and the activity, tier and route it ran on. Counts and
3
+ // dollars only, never text. Pure: the hook adds each finished turn to the session's own record in $.store under
4
+ // USAGE_PREFIX, as it did the savings record (SAVINGS_PREFIX), which is now kept only as undated history.
5
+
6
+ import { afterResetOf, earlierSince, isRecord } from './records.mjs';
7
+ import { readSavingsStore } from './savings.mjs';
8
+
9
+ export const USAGE_PREFIX = 'usage:v1:';
10
+ // The period the Usage tab shows, kept across sessions.
11
+ export const PERIOD_KEY = 'usage:period';
12
+ export const PERIODS = ['session', 'today', '7d', '30d', 'month', 'all'];
13
+ // $.store holds 4 MiB of JSON for all keys together. A session-day takes about 1–2 KB, so days older than this leave a
14
+ // session's record when it is written, and other sessions' records with no newer day are deleted; past MAX_RECORDS
15
+ // sessions, the ones whose last day is oldest go too, so many short sessions cannot fill the store. Upgrade trigger:
16
+ // All needs more than a year of days, or the cap drops days a period shows: roll old days into monthly totals.
17
+ export const RETAIN_DAYS = 400;
18
+ export const MAX_RECORDS = 1000;
19
+ // Insights need this many replies in the period: fewer, and one switch or one long reply decides them.
20
+ export const INSIGHT_REPLIES = 20;
21
+
22
+ // A cell's sums, in this order; an array keeps a record small. The USD sums are compareReply's parts.
23
+ export const CELL_SUMS = [
24
+ 'replies',
25
+ 'routedUsd',
26
+ 'yoursUsd',
27
+ 'cheaperUsd',
28
+ 'strongerUsd',
29
+ 'switchUsd',
30
+ 'inputTokens',
31
+ 'cacheReadTokens',
32
+ 'outputTokens',
33
+ ];
34
+ const USD = new Set(['routedUsd', 'yoursUsd', 'cheaperUsd', 'strongerUsd', 'switchUsd']);
35
+ const IS_USD = CELL_SUMS.map((sum) => USD.has(sum));
36
+ const DAY = /^\d{4}-\d{2}-\d{2}$/;
37
+ // `activity|tier|id@effort`: activity and tier never hold a `|`, and an effort never an `@`, so a model id may hold
38
+ // either.
39
+ const CELL_KEY = /^[^|]+\|[^|]+\|.+@[^@]+$/;
40
+ const HOUR = /^(1?\d|2[0-3])$/;
41
+ // Sums are kept to a millionth of a dollar: enough for a cent-exact readout over many replies, and short in JSON.
42
+ const microUsd = (usd) => Math.round(usd * 1e6) / 1e6;
43
+
44
+ // A key read from router.json, such as a model id `toString` or `__proto__`, must neither answer from the prototype
45
+ // nor set it.
46
+ const own = (object, key) => (Object.hasOwn(object, key) ? object[key] : undefined);
47
+ const put = (object, key, value) =>
48
+ Object.defineProperty(object, key, { value, enumerable: true, writable: true, configurable: true });
49
+
50
+ const pad2 = (n) => String(n).padStart(2, '0');
51
+ // The local calendar day of `ms`, `2026-10-13`.
52
+ export function dayKey(ms) {
53
+ const d = new Date(ms);
54
+ return `${d.getFullYear()}-${pad2(d.getMonth() + 1)}-${pad2(d.getDate())}`;
55
+ }
56
+ // The day `days` before `ms`'s, counted on the calendar, so a daylight saving change never skips or repeats one.
57
+ export function daysBefore(ms, days) {
58
+ const d = new Date(ms);
59
+ return dayKey(new Date(d.getFullYear(), d.getMonth(), d.getDate() - days).getTime());
60
+ }
61
+
62
+ export function emptyUsage() {
63
+ return { version: 1, since: null, days: {} };
64
+ }
65
+
66
+ const emptyDay = () => ({ cells: {}, whatIf: {}, yours: {}, hours: {}, turns: 0, switches: { tier: 0, activity: 0 } });
67
+
68
+ // One routed main reply as its turn collects it. `at` is when it arrived (ms); `activity` the turn's activity and
69
+ // `tier` the tier that served it (null: none); `route` the model id that served it and the request's effort,
70
+ // `id@effort` (`session` for no effort); `yours` your model's id; `reply` its prices against your model, and `replies`
71
+ // against each model as yours keyed by model id, from compareModels; `usage` the API usage, whose counts compareReply
72
+ // already checked. Model ids, not models keys: a models key can name another model later.
73
+ export function replyEntry({ at, activity, tier, route, yours, reply, replies, usage }) {
74
+ const input = usage.input_tokens + usage.cache_read_input_tokens + usage.cache_creation_input_tokens;
75
+ return {
76
+ at,
77
+ cell: `${activity ?? 'none'}|${tier ?? 'none'}|${route}`,
78
+ sums: [
79
+ 1,
80
+ reply.routedUsd,
81
+ reply.yoursUsd,
82
+ reply.cheaperUsd,
83
+ reply.strongerUsd,
84
+ reply.switchUsd,
85
+ input,
86
+ usage.cache_read_input_tokens,
87
+ usage.output_tokens,
88
+ ],
89
+ whatIf: Object.fromEntries(Object.entries(replies).map(([model, r]) => [model, r.yoursUsd])),
90
+ yours,
91
+ };
92
+ }
93
+
94
+ const addSums = (a, b) => a.map((value, i) => (IS_USD[i] ? microUsd(value + b[i]) : value + b[i]));
95
+
96
+ // A finished turn's replies added to the session's record at `now`: each on the day and hour it arrived, the turn and
97
+ // the route switch that started it (`switched`: 'tier', 'activity' or null) on the day it ended. Days past
98
+ // RETAIN_DAYS leave the record. A turn without replies returns `record` itself.
99
+ export function recordUsage(record, entries, { switched = null, now }) {
100
+ if (!entries.length) return record;
101
+ const days = structuredClone(record.days);
102
+ for (const entry of entries) {
103
+ const key = dayKey(entry.at);
104
+ const day = days[key] ?? emptyDay();
105
+ day.cells[entry.cell] = day.cells[entry.cell] ? addSums(day.cells[entry.cell], entry.sums) : [...entry.sums];
106
+ for (const [model, usd] of Object.entries(entry.whatIf)) {
107
+ const [n, sum] = own(day.whatIf, model) ?? [0, 0];
108
+ put(day.whatIf, model, [n + 1, microUsd(sum + usd)]);
109
+ }
110
+ if (entry.yours) addInto(day.yours, entry.yours, 1);
111
+ const hour = String(new Date(entry.at).getHours());
112
+ day.hours[hour] = microUsd((day.hours[hour] ?? 0) + entry.sums[1]);
113
+ days[key] = day;
114
+ }
115
+ const ended = days[dayKey(now)] ?? emptyDay();
116
+ ended.turns += 1;
117
+ if (switched === 'tier' || switched === 'activity') ended.switches[switched] += 1;
118
+ days[dayKey(now)] = ended;
119
+ const cutoff = daysBefore(now, RETAIN_DAYS);
120
+ for (const key of Object.keys(days)) if (key < cutoff) delete days[key];
121
+ return { version: 1, since: record.since ?? now, days };
122
+ }
123
+
124
+ const isCount = (n) => Number.isSafeInteger(n) && n >= 0;
125
+ const isUsd = (n) => Number.isFinite(n) && n >= 0;
126
+ const isPair = (v) => Array.isArray(v) && v.length === 2 && isCount(v[0]) && isUsd(v[1]);
127
+ // Every sum is a count or a cost of at least 0, except the cheaper part, which is at most 0.
128
+ const CHEAPER = CELL_SUMS.indexOf('cheaperUsd');
129
+ const isSums = (v) =>
130
+ Array.isArray(v) &&
131
+ v.length === CELL_SUMS.length &&
132
+ v.every((n, i) => Number.isFinite(n) && (i === CHEAPER ? n <= 0 : n >= 0));
133
+
134
+ function readDay(day) {
135
+ const ok =
136
+ isRecord(day) &&
137
+ isRecord(day.cells) &&
138
+ Object.entries(day.cells).every(([key, sums]) => CELL_KEY.test(key) && isSums(sums)) &&
139
+ isRecord(day.whatIf) &&
140
+ Object.values(day.whatIf).every(isPair) &&
141
+ isRecord(day.yours) &&
142
+ Object.values(day.yours).every(isCount) &&
143
+ isRecord(day.hours) &&
144
+ Object.entries(day.hours).every(([hour, usd]) => HOUR.test(hour) && isUsd(usd)) &&
145
+ isCount(day.turns) &&
146
+ isRecord(day.switches) &&
147
+ Object.keys(day.switches).length === 2 &&
148
+ isCount(day.switches.tier) &&
149
+ isCount(day.switches.activity);
150
+ return ok ? day : null;
151
+ }
152
+
153
+ // The stored value read day by day: a missing or unknown record is empty, and a day that does not read is dropped
154
+ // while the others stay, so a hand edit never breaks a turn or the pane.
155
+ export function readUsage(value) {
156
+ if (!isRecord(value) || value.version !== 1 || !isRecord(value.days)) return emptyUsage();
157
+ if (!(value.since === null || Number.isFinite(value.since))) return emptyUsage();
158
+ const days = {};
159
+ for (const [key, day] of Object.entries(value.days)) {
160
+ const read = DAY.test(key) ? readDay(day) : null;
161
+ if (read) days[key] = read;
162
+ }
163
+ return { version: 1, since: value.since, days };
164
+ }
165
+
166
+ // A record whose first reply came before the last reset at `resetAt` (ms) reads as empty.
167
+ export const usageAfterReset = (record, resetAt) => afterResetOf(record, resetAt, emptyUsage);
168
+
169
+ // The last day of a stored value that reads whole, or null for one that does not, such as one a later release wrote:
170
+ // it may hold days this one skips, so it is never deleted.
171
+ function lastDay(value) {
172
+ const record = readUsage(value);
173
+ if (record.since === null) return null;
174
+ const keys = Object.keys(value.days);
175
+ if (keys.length !== Object.keys(record.days).length) return null;
176
+ return keys.sort().at(-1) ?? '';
177
+ }
178
+
179
+ // Which of the stored `[key, value]` records the store can let go at `now`: those with no day inside RETAIN_DAYS,
180
+ // then, past `max` records, those whose last day is oldest.
181
+ export function prunedUsage(entries, now, max = MAX_RECORDS) {
182
+ const cutoff = daysBefore(now, RETAIN_DAYS);
183
+ const dated = entries.map(([key, value]) => [key, lastDay(value)]).filter(([, day]) => day !== null);
184
+ const gone = new Set(dated.filter(([, day]) => day < cutoff).map(([key]) => key));
185
+ const over = entries.length - gone.size - max;
186
+ if (over > 0)
187
+ for (const [key] of dated
188
+ .filter(([key]) => !gone.has(key))
189
+ .sort(([, a], [, b]) => (a < b ? -1 : a > b ? 1 : 0))
190
+ .slice(0, over))
191
+ gone.add(key);
192
+ return gone;
193
+ }
194
+
195
+ function addInto(into, key, value) {
196
+ put(into, key, (own(into, key) ?? 0) + value);
197
+ }
198
+
199
+ function mergeDay(a, b) {
200
+ const day = structuredClone(a);
201
+ for (const [key, sums] of Object.entries(b.cells))
202
+ day.cells[key] = day.cells[key] ? addSums(day.cells[key], sums) : [...sums];
203
+ for (const [model, [n, usd]] of Object.entries(b.whatIf)) {
204
+ const [m, sum] = own(day.whatIf, model) ?? [0, 0];
205
+ put(day.whatIf, model, [m + n, microUsd(sum + usd)]);
206
+ }
207
+ for (const [model, n] of Object.entries(b.yours)) addInto(day.yours, model, n);
208
+ for (const [hour, usd] of Object.entries(b.hours)) day.hours[hour] = microUsd((day.hours[hour] ?? 0) + usd);
209
+ day.turns += b.turns;
210
+ day.switches = { tier: day.switches.tier + b.switches.tier, activity: day.switches.activity + b.switches.activity };
211
+ return day;
212
+ }
213
+
214
+ // The records kept across sessions added up day by day, each since the last reset, since the earliest.
215
+ export function mergeUsage(values, resetAt = null) {
216
+ const merged = emptyUsage();
217
+ for (const one of values.map((value) => usageAfterReset(readUsage(value), resetAt))) {
218
+ merged.since = earlierSince(merged.since, one.since);
219
+ for (const [key, day] of Object.entries(one.days))
220
+ merged.days[key] = merged.days[key] ? mergeDay(merged.days[key], day) : structuredClone(day);
221
+ }
222
+ return merged;
223
+ }
224
+
225
+ // The days a period covers at `now`, as day keys, both ends included; null ends for the whole record (`session`,
226
+ // which is the session's own record, and `all`). 7d is today and the six days before it.
227
+ export function periodRange(period, now) {
228
+ const to = dayKey(now);
229
+ if (period === 'today') return { from: to, to };
230
+ if (period === '7d') return { from: daysBefore(now, 6), to };
231
+ if (period === '30d') return { from: daysBefore(now, 29), to };
232
+ if (period === 'month') return { from: `${to.slice(0, 7)}-01`, to };
233
+ return { from: null, to: null };
234
+ }
235
+
236
+ // A record's days inside `range`, added up: the readout sums (as `readout` in lib/savings.mjs takes them), tokens,
237
+ // turns and switches, what the same tokens cost on each model as yours, your model's replies by model id, the cells,
238
+ // and the days themselves, oldest first.
239
+ export function summarize(record, { from, to }) {
240
+ const days = Object.keys(record.days)
241
+ .filter((key) => (from === null || key >= from) && (to === null || key <= to))
242
+ .sort()
243
+ .map((key) => [key, record.days[key]]);
244
+ const total = emptyDay();
245
+ for (const [, day] of days) Object.assign(total, mergeDay(total, day));
246
+ const [replies, routedUsd, yoursUsd, cheaperUsd, strongerUsd, switchUsd, inputTokens, cacheReadTokens, outputTokens] =
247
+ Object.values(total.cells).reduce(
248
+ addSums,
249
+ CELL_SUMS.map(() => 0),
250
+ );
251
+ return {
252
+ replies,
253
+ routedUsd,
254
+ yoursUsd,
255
+ cheaperUsd,
256
+ strongerUsd,
257
+ switchUsd,
258
+ inputTokens,
259
+ cacheReadTokens,
260
+ outputTokens,
261
+ turns: total.turns,
262
+ switches: total.switches,
263
+ whatIf: total.whatIf,
264
+ yours: total.yours,
265
+ cells: total.cells,
266
+ days,
267
+ };
268
+ }
269
+
270
+ const READOUT_SUMS = ['replies', 'routedUsd', 'yoursUsd', 'cheaperUsd', 'strongerUsd', 'switchUsd'];
271
+
272
+ // Every routed reply kept: the usage records' days and the undated savings totals from before them, as `readout`
273
+ // takes them, and since when (ms; null without any).
274
+ export function allTime(usageStore, savingsStore) {
275
+ const record = readUsage(usageStore);
276
+ const summary = summarize(record, { from: null, to: null });
277
+ const legacy = readSavingsStore(savingsStore);
278
+ return {
279
+ totals: Object.fromEntries(READOUT_SUMS.map((key) => [key, summary[key] + legacy[key]])),
280
+ since: earlierSince(record.since, legacy.since),
281
+ legacy,
282
+ };
283
+ }
284
+
285
+ // A cell key's parts, split at its first two `|` and its route's last `@` (CELL_KEY).
286
+ function cellParts(key) {
287
+ const [activity, tier] = key.split('|', 2);
288
+ const route = key.slice(activity.length + tier.length + 2);
289
+ return { activity, tier, route, model: route.slice(0, route.lastIndexOf('@')) };
290
+ }
291
+ // The part of a cell key a breakdown groups by, and the part it lists under each group.
292
+ const keyPart = (key, by) => cellParts(key)[by];
293
+ const CHILD = { activity: 'route', model: 'activity', tier: 'activity' };
294
+
295
+ // The cells grouped `by` activity, model or tier: each group's sums and its cells grouped again (routes under an
296
+ // activity, activities under a model or a tier), the groups by routed cost, most first; ties keep name order.
297
+ export function breakdown(cells, by) {
298
+ const groups = new Map();
299
+ for (const [key, sums] of Object.entries(cells)) {
300
+ const name = keyPart(key, by);
301
+ const group = groups.get(name) ?? { name, sums: CELL_SUMS.map(() => 0), children: new Map() };
302
+ group.sums = addSums(group.sums, sums);
303
+ const child = keyPart(key, CHILD[by]);
304
+ group.children.set(child, addSums(group.children.get(child) ?? CELL_SUMS.map(() => 0), sums));
305
+ groups.set(name, group);
306
+ }
307
+ const byCost = (a, b) => b.sums[1] - a.sums[1] || (a.name < b.name ? -1 : 1);
308
+ return [...groups.values()]
309
+ .map((group) => ({
310
+ name: group.name,
311
+ sums: group.sums,
312
+ children: [...group.children].map(([name, sums]) => ({ name, sums })).sort(byCost),
313
+ }))
314
+ .sort(byCost);
315
+ }
316
+
317
+ // The cells whose `by` part (activity, model or tier) is `name`.
318
+ export const cellsWhere = (cells, by, name) =>
319
+ Object.fromEntries(Object.entries(cells).filter(([key]) => keyPart(key, by) === name));
320
+
321
+ // The route most of these cells' replies ran on, `id@effort`; ties go to the first in name order. Null without any.
322
+ export function mostlyOn(cells) {
323
+ const routes = new Map();
324
+ for (const [key, sums] of Object.entries(cells))
325
+ routes.set(keyPart(key, 'route'), (routes.get(keyPart(key, 'route')) ?? 0) + sums[0]);
326
+ const [top] = [...routes].sort((a, b) => b[1] - a[1] || (a[0] < b[0] ? -1 : 1));
327
+ return top?.[0] ?? null;
328
+ }
329
+
330
+ // Routed cost per bucket of the period: per hour of `today` for the session and today, per week once a period spans
331
+ // more than WEEKLY_AFTER days, else per day, with zero for a bucket without replies. `unit` names the bucket.
332
+ const WEEKLY_AFTER = 45;
333
+ export function trend(summary, period, now) {
334
+ if (period === 'session' || period === 'today') {
335
+ const day = summary.days.find(([key]) => key === dayKey(now))?.[1];
336
+ const hours = Object.keys(day?.hours ?? {}).map(Number);
337
+ if (!hours.length) return { unit: 'hour', values: [] };
338
+ const values = [];
339
+ for (let h = Math.min(...hours); h <= Math.max(...hours); h += 1) values.push(day.hours[String(h)] ?? 0);
340
+ return { unit: 'hour', values, from: Math.min(...hours) };
341
+ }
342
+ if (!summary.days.length) return { unit: 'day', values: [] };
343
+ const first = summary.days[0][0];
344
+ const start = periodRange(period, now).from ?? first;
345
+ const routed = new Map(
346
+ summary.days.map(([key, day]) => [key, Object.values(day.cells).reduce((s, c) => s + c[1], 0)]),
347
+ );
348
+ const values = [];
349
+ const [y, m, d] = start.split('-').map(Number);
350
+ for (let i = 0; ; i += 1) {
351
+ const key = dayKey(new Date(y, m - 1, d + i).getTime());
352
+ if (key > dayKey(now)) break;
353
+ values.push(routed.get(key) ?? 0);
354
+ }
355
+ if (values.length <= WEEKLY_AFTER) return { unit: 'day', values, from: start };
356
+ const weeks = [];
357
+ for (let i = 0; i < values.length; i += 7) weeks.push(values.slice(i, i + 7).reduce((s, v) => s + v, 0));
358
+ return { unit: 'week', values: weeks, from: start };
359
+ }
360
+
361
+ // What the period's numbers point at, evidence only: answer quality is not measured, so no line says which model to
362
+ // use. The (activity, tier) cell that carried a quarter or more of the cost, the switch writes that ate 15% or more of
363
+ // the cheaper-model saving, and the cell that ran most above your model. None below INSIGHT_REPLIES replies.
364
+ export function insights(summary) {
365
+ if (summary.replies < INSIGHT_REPLIES || !(summary.routedUsd > 0)) return [];
366
+ const cells = new Map();
367
+ for (const [key, sums] of Object.entries(summary.cells)) {
368
+ const { activity, tier } = cellParts(key);
369
+ const id = `${activity}|${tier}`;
370
+ const cell = cells.get(id) ?? { activity, tier, sums: CELL_SUMS.map(() => 0), cells: {} };
371
+ cell.sums = addSums(cell.sums, sums);
372
+ cell.cells[key] = sums;
373
+ cells.set(id, cell);
374
+ }
375
+ const out = [];
376
+ const costliest = [...cells.values()].sort((a, b) => b.sums[1] - a.sums[1])[0];
377
+ const share = costliest.sums[1] / summary.routedUsd;
378
+ if (share >= 0.25 && cells.size > 1)
379
+ out.push({
380
+ kind: 'cost',
381
+ activity: costliest.activity,
382
+ tier: costliest.tier,
383
+ share,
384
+ route: mostlyOn(costliest.cells),
385
+ });
386
+ const saving = -summary.cheaperUsd;
387
+ if (saving > 0 && summary.switchUsd / saving >= 0.15)
388
+ out.push({ kind: 'switch', share: summary.switchUsd / saving, usd: summary.switchUsd });
389
+ const stronger = [...cells.values()].sort((a, b) => b.sums[4] - a.sums[4])[0];
390
+ if (stronger.sums[4] >= 0.005)
391
+ out.push({
392
+ kind: 'stronger',
393
+ activity: stronger.activity,
394
+ tier: stronger.tier,
395
+ usd: stronger.sums[4],
396
+ route: mostlyOn(stronger.cells),
397
+ });
398
+ return out;
399
+ }
package/lib/view.mjs CHANGED
@@ -46,7 +46,18 @@ export function initialView(model) {
46
46
  // Routing vs each configured model this session, by models key; `savings` is the one /model selects now.
47
47
  savingsBy: {},
48
48
  savings: null,
49
+ // The undated savings totals from before the usage records, added to the All period.
49
50
  savingsStore: null,
51
+ // Routed usage by day: every session's records as last read or written, and this session's own.
52
+ usageStore: null,
53
+ usageSession: null,
54
+ // The Usage tab's controls: the period (kept across sessions), the breakdown, the what-if view, the open row
55
+ // (`<group>:<name>`), and whether Delete history waits for its confirmation.
56
+ usagePeriod: 'session',
57
+ usageGroup: 'activity',
58
+ usageCompare: false,
59
+ usageOpen: null,
60
+ confirmDelete: false,
50
61
  configPath: null,
51
62
  tuning: null,
52
63
  tuningBase: null,
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@alexeiled/claude-router",
3
- "version": "1.11.0",
3
+ "version": "1.12.0",
4
4
  "description": "Native Claude Code Mod: model and effort routing for the main conversation, advised by Jev, Clef, Clef Flash, Clef Omni, OpenAI or Ollama.",
5
5
  "license": "MIT",
6
6
  "author": "Alexei Ledenev",
package/types/index.d.ts CHANGED
@@ -104,15 +104,12 @@ declare module 'claude-code' {
104
104
  strongerUsd: number;
105
105
  switchUsd: number;
106
106
  }
107
- // A session's totals; per tier ('none': not chosen by routing) its replies and their routed cost, and replies by the
108
- // stronger model they ran on.
107
+ // A session's totals, and replies by the stronger model they ran on.
109
108
  interface RouterSavingsSession extends RouterSavingsSums {
110
- tiers: Partial<Record<RouterTier | 'none', number>>;
111
- tierUsd: Partial<Record<RouterTier | 'none', number>>;
112
109
  stronger: Record<string, number>;
113
110
  }
114
- // Totals kept across sessions, one per session under store key 'savings:v1:<session id>' or their sum in the view,
115
- // since the first reply after the last reset (ms).
111
+ // Totals one session kept under store key 'savings:v1:<session id>' before the usage records, or their sum in the
112
+ // view: no longer written, added to the Usage tab's All period as undated history.
116
113
  interface RouterSavingsStore extends RouterSavingsSums {
117
114
  version: 1;
118
115
  since: number | null;
@@ -145,6 +142,26 @@ declare module 'claude-code' {
145
142
  routed: { on: Record<string, RouterSubagentCounts> };
146
143
  passed: Partial<Record<'fork' | 'explicit' | 'teammate' | 'workflow' | 'unlisted', RouterSubagentPassed>>;
147
144
  }
145
+ // One local calendar day of routed replies (lib/usage.mjs). `cells` by 'activity|tier|modelId@effort' hold, in order,
146
+ // replies, routedUsd, yoursUsd, cheaperUsd, strongerUsd, switchUsd, inputTokens, cacheReadTokens, outputTokens.
147
+ // `whatIf` is [replies, USD] of the same tokens on each model id as yours; `yours` replies by your model's id;
148
+ // `hours` routed USD by local hour; `turns` and `switches` count turns on the day they ended.
149
+ interface RouterUsageDay {
150
+ cells: Record<string, number[]>;
151
+ whatIf: Record<string, [number, number]>;
152
+ yours: Record<string, number>;
153
+ hours: Record<string, number>;
154
+ turns: number;
155
+ switches: { tier: number; activity: number };
156
+ }
157
+ // Kept across sessions, one per session under store key 'usage:v1:<session id>' or their sum in the view, by day
158
+ // ('2026-10-13'), since its first turn written after the last reset (ms).
159
+ interface RouterUsageStore {
160
+ version: 1;
161
+ since: number | null;
162
+ days: Record<string, RouterUsageDay>;
163
+ }
164
+ type RouterUsagePeriod = 'session' | 'today' | '7d' | '30d' | 'month' | 'all';
148
165
  interface RouterView {
149
166
  phase: 'ready' | 'choosing' | 'routed' | 'manual' | 'unavailable';
150
167
  mode: 'auto' | 'manual';
@@ -190,6 +207,16 @@ declare module 'claude-code' {
190
207
  savings?: RouterSavingsSession | null;
191
208
  savingsStore?: RouterSavingsStore | null;
192
209
  subagentStore?: RouterSubagentStore | null;
210
+ // Every session's usage records as last read or written, and this session's own.
211
+ usageStore?: RouterUsageStore | null;
212
+ usageSession?: RouterUsageStore | null;
213
+ // The Usage tab: its period (kept across sessions under store key 'usage:period'), breakdown, What if, the open
214
+ // row ('<group>:<name>'), and whether Delete history waits for its confirmation.
215
+ usagePeriod?: RouterUsagePeriod;
216
+ usageGroup?: 'activity' | 'model' | 'tier';
217
+ usageCompare?: boolean;
218
+ usageOpen?: string | null;
219
+ confirmDelete?: boolean;
193
220
  configPath?: string | null;
194
221
  tuning?: Partial<RouterTuning> | null;
195
222
  tuningBase?: RouterTuning | null;
@@ -199,7 +226,7 @@ declare module 'claude-code' {
199
226
  tab?: 'now' | 'routes' | 'policy' | 'classifier' | 'usage';
200
227
  // The Routes grid cell whose editor is open: '<activity>.<tier>', or 'tier.<tier>' for a tier's own route.
201
228
  routeCell?: string | null;
202
- // Whether the Usage tab shows Claude's readings in detail, with the estimates.
229
+ // Whether the Now tab shows Claude's readings in detail, with the estimates.
203
230
  usageDetail?: boolean;
204
231
  help?: boolean;
205
232
  bandDetail?: boolean;