@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.
@@ -72,16 +72,14 @@ import {
72
72
  } from '../lib/route.mjs';
73
73
  import {
74
74
  addReplies,
75
- addReply,
76
75
  afterReset,
77
76
  compareModels,
78
77
  emptySavingsStore,
79
- emptyTotals,
80
78
  mergeSavingsStores,
81
79
  modelAlias,
82
80
  modelEntry,
81
+ modelSpec,
83
82
  readSavingsStore,
84
- recordSavingsStore,
85
83
  SAVINGS_PREFIX,
86
84
  SAVINGS_RESET_KEY,
87
85
  sessionCacheTtl,
@@ -106,6 +104,18 @@ import {
106
104
  subagentsAfterReset,
107
105
  typeRoute,
108
106
  } from '../lib/subagents.mjs';
107
+ import {
108
+ emptyUsage,
109
+ mergeUsage,
110
+ PERIOD_KEY,
111
+ PERIODS,
112
+ prunedUsage,
113
+ readUsage,
114
+ recordUsage,
115
+ replyEntry,
116
+ USAGE_PREFIX,
117
+ usageAfterReset,
118
+ } from '../lib/usage.mjs';
109
119
  import { CLEARED_READINGS, continuationView, healthOf, initialView, responseMetrics } from '../lib/view.mjs';
110
120
 
111
121
  // The engine follows $ only into functions declared in this file, never across an import: every helper that takes $
@@ -121,9 +131,21 @@ const isSet = (value) => /^(1|true|yes|on)$/i.test(String(value ?? '').trim());
121
131
 
122
132
  // The counts kept across sessions: each session writes only its own record of a kind, `prefix` and its session id,
123
133
  // because $.store has no atomic update; the view's `field` shows every session's record since the last reset added
124
- // up. One marker, SAVINGS_RESET_KEY, resets them all. `legacy` is the key all sessions shared before 1.10.3: it counts
125
- // as another session's record until a reset deletes it.
134
+ // up, and `ownField`, where a kind has one, this session's alone. One marker, SAVINGS_RESET_KEY, resets them all.
135
+ // `legacy` is the key all sessions shared before 1.10.3: it counts as another session's record until a reset deletes
136
+ // it. Another session's records that `prune` names are deleted when read. `savings` is no longer written: its records
137
+ // are the undated totals from before `usage`, which the All period adds.
126
138
  const LEDGERS = {
139
+ usage: {
140
+ prefix: USAGE_PREFIX,
141
+ field: 'usageStore',
142
+ ownField: 'usageSession',
143
+ read: readUsage,
144
+ afterReset: usageAfterReset,
145
+ merge: mergeUsage,
146
+ empty: emptyUsage,
147
+ prune: prunedUsage,
148
+ },
127
149
  savings: {
128
150
  prefix: SAVINGS_PREFIX,
129
151
  field: 'savingsStore',
@@ -187,8 +209,8 @@ function createRouter(options) {
187
209
  afterDown: null,
188
210
  // Counts every switch to routing off; a turn compares it with its own start to see routing went off meanwhile.
189
211
  offSwitches: 0,
190
- // Each turn's routing-vs-your-model totals until turn.complete adds them to the store.
191
- turnSavings: new Map(),
212
+ // Each turn's routed replies (replyEntry) until turn.complete adds them to the session's usage record.
213
+ turnUsage: new Map(),
192
214
  // The counts kept across sessions, by LEDGERS kind: this session's record (`own`, `{ sessionId, record }`), held
193
215
  // here so a refresh never reads it back from the store while a write of it is pending, and the sum of every other
194
216
  // session's (`others`), read on refresh. The view shows their sum.
@@ -251,6 +273,12 @@ async function startView($, router, model) {
251
273
  return fresh && mode === 'manual' ? { mode, reason: NOT_A_TIER_REASON } : { mode };
252
274
  }
253
275
 
276
+ // The Usage tab's period as last chosen in any session; Session when none was or the store cannot be read.
277
+ async function periodOf($) {
278
+ const saved = await $.store.get(PERIOD_KEY).catch(() => null);
279
+ return PERIODS.includes(saved) ? saved : 'session';
280
+ }
281
+
254
282
  async function rememberMode($, mode) {
255
283
  try {
256
284
  await $.store.set(`${MODE_PREFIX}${await $.session.id()}`, mode);
@@ -288,10 +316,36 @@ async function ownRecord($, router, kind) {
288
316
 
289
317
  // Every other session's record of `kind` since the last reset, added up and held. `keys` is one $.store.keys() listing.
290
318
  async function readOthers($, router, kind, { sessionId, resetAt, keys }) {
291
- const { prefix, legacy, merge } = LEDGERS[kind];
319
+ const { prefix, legacy, merge, prune } = LEDGERS[kind];
292
320
  const own = `${prefix}${sessionId}`;
293
321
  const names = keys.filter((key) => (key.startsWith(prefix) && key !== own) || key === legacy);
294
- const others = merge(await Promise.all(names.map((key) => $.store.get(key))), resetAt);
322
+ let values = await Promise.all(names.map((key) => $.store.get(key)));
323
+ if (prune) {
324
+ // An expired record holds nothing a period shows, a capped one only the oldest days; a session still running
325
+ // writes its own again at its next turn.
326
+ const gone = prune(
327
+ names.map((key, i) => [key, values[i]]),
328
+ Date.now(),
329
+ );
330
+ // Read again just before deleting: a session that wrote its record since keeps it, and it counts as written. The
331
+ // window between the read and the delete stays, as $.store has no conditional delete; it needs that session's write
332
+ // inside it. A record whose delete failed still counts.
333
+ const deleted = new Set();
334
+ // Every check settles before the merge, a failed read or delete included.
335
+ await Promise.allSettled(
336
+ [...gone].map(async (key) => {
337
+ const i = names.indexOf(key);
338
+ const current = await $.store.get(key);
339
+ if (JSON.stringify(current) !== JSON.stringify(values[i])) values[i] = current;
340
+ else {
341
+ await $.store.delete(key);
342
+ deleted.add(key);
343
+ }
344
+ }),
345
+ );
346
+ values = values.filter((_, i) => !deleted.has(names[i]));
347
+ }
348
+ const others = merge(values, resetAt);
295
349
  router.ledgers[kind] = { ...router.ledgers[kind], others, othersResetAt: resetAt ?? null };
296
350
  }
297
351
 
@@ -301,7 +355,10 @@ function ledgerView(router, kinds = LEDGER_KINDS) {
301
355
  const patch = {};
302
356
  for (const kind of kinds) {
303
357
  const { others, own } = router.ledgers[kind];
304
- if (others) patch[LEDGERS[kind].field] = LEDGERS[kind].merge([others, own?.record]);
358
+ const { field, ownField, merge, empty } = LEDGERS[kind];
359
+ if (!others) continue;
360
+ patch[field] = merge([others, own?.record]);
361
+ if (ownField) patch[ownField] = own?.record ?? empty();
305
362
  }
306
363
  return patch;
307
364
  }
@@ -348,7 +405,7 @@ async function storeView($, router) {
348
405
  // A notice answers the last press in the pane, so the pane opens without one; the last write keeps its Undo in the
349
406
  // status bar.
350
407
  async function openPane($, router) {
351
- await updateView($, router, { notice: null, ...(await storeView($, router)) });
408
+ await updateView($, router, { notice: null, confirmDelete: false, ...(await storeView($, router)) });
352
409
  await $.ui.open({ id: PANE, title: PANE_TITLE, focus: true, closeOnEscape: true });
353
410
  }
354
411
 
@@ -840,12 +897,14 @@ async function publishReply($, router, turnId, response, tier, route, routedUsd)
840
897
  // A routed reply written to the loop at `loopVersion`, then published: the view's metrics and the routing-vs-your-model
841
898
  // totals. A lost write publishes nothing.
842
899
  async function observeRouted($, router, { turnId, cfg, loop, loopVersion, request, response, nativeModel }) {
900
+ // When the reply arrived: the awaits below can cross midnight or the hour it is kept under.
901
+ const at = Date.now();
843
902
  const observed = observeResponse(cfg, loop, {
844
903
  usage: response.usage,
845
904
  requestedModel: request.model,
846
905
  effort: request.effort ?? null,
847
906
  stopReason: response.stopReason,
848
- now: Date.now(),
907
+ now: at,
849
908
  });
850
909
  if (response.stopReason === null) observed.suspended = true;
851
910
  const compared = await compareYours($, router, loop, response, request.effort ?? null, nativeModel, cfg);
@@ -856,7 +915,20 @@ async function observeRouted($, router, { turnId, cfg, loop, loopVersion, reques
856
915
  const tier = isSameModel(request.model, response.usage?.model) ? loop.decision.tier : null;
857
916
  const route = `${request.model}@${request.effort ?? 'session'}`;
858
917
  await publishReply($, router, turnId, response, tier, route, compared?.reply?.routedUsd ?? null);
859
- if (compared) await addSavings($, router, turnId, compared, tier);
918
+ // Kept by model id, under the model that served it: a substitute's cost is not the requested model's, and a models
919
+ // key can name another model later.
920
+ const idOf = (model) => modelSpec(cfg, model)?.id ?? model;
921
+ if (compared)
922
+ await addSavings($, router, {
923
+ turnId,
924
+ compared,
925
+ tier,
926
+ route: `${idOf(response.usage?.model ?? request.model)}@${request.effort ?? 'session'}`,
927
+ yours: idOf(nativeModel),
928
+ byId: Object.fromEntries(Object.entries(compared.replies).map(([alias, r]) => [cfg.models[alias].id, r])),
929
+ usage: response.usage,
930
+ at,
931
+ });
860
932
  }
861
933
 
862
934
  // The main conversation's prompt-cache lifetime by Claude Code's rule (sessionCacheTtl), or null when a reading
@@ -899,22 +971,35 @@ async function compareYours($, router, loop, response, servedEffort, nativeModel
899
971
  }
900
972
  }
901
973
 
902
- // A routed reply's prices added to each model's session totals in the view, and its prices against your model now to
903
- // the turn's totals for the store.
904
- async function addSavings($, router, turnId, compared, tier) {
974
+ // A routed reply's prices added to each model's session totals in the view, and the reply, priced against your model
975
+ // now, to the turn's replies for the usage record. `route` is the served model's `id@effort`, `yours` your model's id,
976
+ // `byId` the reply priced against each model as yours, keyed by model id; `at` when the reply arrived (ms).
977
+ async function addSavings($, router, { turnId, compared, tier, route, yours, byId, usage, at }) {
905
978
  try {
906
979
  const view = router.view ?? (await readView($, router));
907
- if (compared.reply)
908
- router.turnSavings.set(turnId, addReply(router.turnSavings.get(turnId) ?? emptyTotals(), compared.reply, tier));
909
- await updateView($, router, { savingsBy: addReplies(view.savingsBy ?? {}, compared.replies, tier) });
980
+ if (compared.reply) {
981
+ const turn = router.turnActivities.get(turnId);
982
+ const entry = replyEntry({
983
+ at,
984
+ activity: tier ? (turn?.label ?? null) : null,
985
+ tier,
986
+ route,
987
+ yours,
988
+ reply: compared.reply,
989
+ replies: byId,
990
+ usage,
991
+ });
992
+ router.turnUsage.set(turnId, [...(router.turnUsage.get(turnId) ?? []), entry]);
993
+ }
994
+ await updateView($, router, { savingsBy: addReplies(view.savingsBy ?? {}, compared.replies) });
910
995
  } catch {}
911
996
  }
912
997
 
913
- // A finished turn's totals added to this session's record kept across sessions.
914
- async function flushSavings($, router, totals) {
998
+ // A finished turn's replies, and the switch that started it, added to this session's usage record.
999
+ async function flushUsage($, router, entries, switched) {
915
1000
  try {
916
- if (await addToLedger($, router, 'savings', (record, now) => recordSavingsStore(record, totals, now)))
917
- await updateView($, router, ledgerView(router, ['savings']));
1001
+ if (await addToLedger($, router, 'usage', (record, now) => recordUsage(record, entries, { switched, now })))
1002
+ await updateView($, router, ledgerView(router, ['usage']));
918
1003
  } catch {}
919
1004
  }
920
1005
 
@@ -1241,7 +1326,7 @@ function paneActions($, router, view) {
1241
1326
  };
1242
1327
  return {
1243
1328
  mode: (mode) => changeMode($, router, mode),
1244
- tab: (tab) => updateView($, router, { tab, notice: null }),
1329
+ tab: (tab) => updateView($, router, { tab, notice: null, confirmDelete: false }),
1245
1330
  help: () => updateView($, router, { help: !(router.view ?? view).help }),
1246
1331
  pin: async (tier) => {
1247
1332
  await updateView($, router, { notice: await setPin($, router, tier) });
@@ -1297,6 +1382,18 @@ function paneActions($, router, view) {
1297
1382
  removeActivity: (activity, tier) => editCell(activity, tier, 'remove'),
1298
1383
  selectCell: (cell) => updateView($, router, { routeCell: cell, notice: null }),
1299
1384
  usageDetail: () => updateView($, router, { usageDetail: !(router.view ?? view).usageDetail }),
1385
+ // The Usage tab's period, kept across sessions; a failed save keeps it for this session.
1386
+ period: async (period) => {
1387
+ if (!PERIODS.includes(period)) return;
1388
+ await $.store.set(PERIOD_KEY, period).catch(() => {});
1389
+ await updateView($, router, { usagePeriod: period, usageOpen: null });
1390
+ },
1391
+ usageGroup: (group) => updateView($, router, { usageGroup: group, usageOpen: null }),
1392
+ usageCompare: () => updateView($, router, { usageCompare: !(router.view ?? view).usageCompare }),
1393
+ usageOpen: (row) => updateView($, router, { usageOpen: row }),
1394
+ // An insight's link: the Routes tab with the grid cell it names open.
1395
+ openRoute: (cell) => updateView($, router, { tab: 'routes', routeCell: cell, notice: null }),
1396
+ confirmDelete: (asked) => updateView($, router, { confirmDelete: asked }),
1300
1397
  // `/router activities <mode>`: the mode alone, saved at once like a classifier press, with Undo.
1301
1398
  activityRouting: (mode) => {
1302
1399
  const from = router.config.activityRouting;
@@ -1305,12 +1402,13 @@ function paneActions($, router, view) {
1305
1402
  withActivities(file, { base: { activityRouting: from }, activityRouting: mode }),
1306
1403
  );
1307
1404
  },
1308
- // One reset for both readouts: activity stats and routing vs your model, this session's and the saved ones.
1405
+ // Delete history: every record kept across sessions (usage, the undated savings, activity stats and metrics,
1406
+ // subagents) and this session's counts.
1309
1407
  resetStats: async () => {
1310
1408
  router.statsResets += 1;
1311
1409
  router.run = null;
1312
1410
  router.afterDown = null;
1313
- router.turnSavings.clear();
1411
+ router.turnUsage.clear();
1314
1412
  for (const [id, agent] of router.agents) router.agents.set(id, flushedAgent(agent));
1315
1413
  // Every session's records. The marker is written first, so a session still holding its record from before the
1316
1414
  // reset drops it, unless that record's first count has the reset's millisecond or the clock moved back across
@@ -1327,13 +1425,21 @@ function paneActions($, router, view) {
1327
1425
  return true;
1328
1426
  };
1329
1427
  const cleared = await clearRecords().catch(() => false);
1428
+ // The store kept the history: this session's records start over, and its next write replaces the stored one.
1429
+ if (!cleared)
1430
+ for (const kind of LEDGER_KINDS) {
1431
+ const held = router.ledgers[kind];
1432
+ if (held.own) held.own = { ...held.own, record: LEDGERS[kind].empty() };
1433
+ }
1330
1434
  await updateView($, router, {
1331
1435
  activityStats: null,
1332
1436
  savingsBy: {},
1333
- ...(cleared ? ledgerView(router) : {}),
1437
+ confirmDelete: false,
1438
+ usageOpen: null,
1439
+ ...ledgerView(router),
1334
1440
  notice: cleared
1335
- ? 'Stats reset: activity and routing vs your model, this session and saved.'
1336
- : 'This session’s stats reset. Saved stats could not be cleared.',
1441
+ ? 'History deleted: usage, activity and subagent records of every session.'
1442
+ : 'This session’s counts cleared. The saved history could not be deleted.',
1337
1443
  });
1338
1444
  },
1339
1445
  discardRouting: () => updateView($, router, { routeDraft: null, tuning: null, tuningBase: null, notice: null }),
@@ -1398,7 +1504,7 @@ async function endSession($, router) {
1398
1504
  router.turnActivities.clear();
1399
1505
  for (const review of router.reviews.values()) review.controller.abort();
1400
1506
  router.reviews.clear();
1401
- router.turnSavings.clear();
1507
+ router.turnUsage.clear();
1402
1508
  const run = router.run;
1403
1509
  router.run = null;
1404
1510
  router.afterDown = null;
@@ -1419,6 +1525,8 @@ async function endSession($, router) {
1419
1525
  activityMetrics: router.view?.activityMetrics ?? null,
1420
1526
  savingsStore: router.view?.savingsStore ?? null,
1421
1527
  subagentStore: router.view?.subagentStore ?? null,
1528
+ usageStore: router.view?.usageStore ?? null,
1529
+ usagePeriod: router.view?.usagePeriod ?? 'session',
1422
1530
  health: healthOf(clientOf(router, router.config.classifier), router.config.classifier),
1423
1531
  configPath: router.config.nativePath,
1424
1532
  phase: router.view?.phase === 'unavailable' ? 'unavailable' : 'ready',
@@ -1465,6 +1573,7 @@ export function register(on, options) {
1465
1573
  routeDraft: null,
1466
1574
  lastWrite: null,
1467
1575
  bandDetail: (await $.store.get(BAND_DETAIL).catch(() => false)) === true,
1576
+ usagePeriod: await periodOf($),
1468
1577
  ...(await storeView($, router)),
1469
1578
  });
1470
1579
  } catch (error) {
@@ -1612,9 +1721,9 @@ export function register(on, options) {
1612
1721
  if (turn?.mode === 'off') {
1613
1722
  if ((await $.session.id()) === turn.sessionId) router.afterDown = advanceDown(router.afterDown, turn).after;
1614
1723
  } else if (turn) await recordActivity($, router, turn);
1615
- const savings = router.turnSavings.get(e.turnId);
1616
- router.turnSavings.delete(e.turnId);
1617
- if (savings) await flushSavings($, router, savings);
1724
+ const entries = router.turnUsage.get(e.turnId);
1725
+ router.turnUsage.delete(e.turnId);
1726
+ if (entries) await flushUsage($, router, entries, turn?.switched ?? null);
1618
1727
  return next(e);
1619
1728
  });
1620
1729
 
package/lib/display.mjs CHANGED
@@ -11,7 +11,8 @@ import {
11
11
  import { ratesAt } from './cost.mjs';
12
12
  import { PROBE_RESULTS } from './probe-results.mjs';
13
13
  import { cellForModel } from './route.mjs';
14
- import { emptyTotals, readout, readSavingsStore } from './savings.mjs';
14
+ import { emptyTotals, readout } from './savings.mjs';
15
+ import { allTime } from './usage.mjs';
15
16
 
16
17
  // Cost order, cheapest first, so the colors read as a scale. Hex values: every surface draws them.
17
18
  export const TIER_COLOR = { micro: '#5fd7af', low: '#5f9fe0', medium: '#d7af5f', high: '#e0708a' };
@@ -299,12 +300,12 @@ export function strongerReplies(totals) {
299
300
  export function savingsLine(view) {
300
301
  const label = `vs your model (${yourModel(view)})`;
301
302
  const session = readout(view.savings ?? emptyTotals());
302
- const store = readSavingsStore(view.savingsStore);
303
- const across = readout(store);
303
+ const kept = allTime(view.usageStore, view.savingsStore);
304
+ const across = readout(kept.totals);
304
305
  if (!session.replies) {
305
306
  const saved = across.early
306
307
  ? ''
307
- : `; ${savingsAmount(across)} since ${sinceDate(store.since)}, each session compared with its own model`;
308
+ : `; ${savingsAmount(across)} since ${sinceDate(kept.since)}, each session compared with its own model`;
308
309
  return `${label}: no routed replies this session${saved}`;
309
310
  }
310
311
  if (session.early) return `${label}: too early, ${replyCount(session.replies, 'routed replies')}`;