@alexeiled/claude-router 1.10.5 → 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/.claude-plugin/plugin.json +1 -1
- package/CHANGELOG.md +29 -0
- package/README.md +3 -2
- package/docs/activity-routing.md +3 -3
- package/docs/architecture.md +7 -7
- package/docs/configuration.md +3 -2
- package/docs/evaluation.md +8 -8
- package/docs/native-router.md +7 -7
- package/docs/router-pane-classifier.svg +49 -43
- package/docs/router-pane-now.svg +6 -4
- package/docs/router-pane-usage-whatif.svg +133 -0
- package/docs/router-pane-usage.svg +100 -87
- package/docs/user-guide.md +53 -28
- package/hooks/native-router.mjs +142 -33
- package/lib/config.mjs +8 -0
- package/lib/display.mjs +5 -4
- package/lib/panel.mjs +525 -376
- package/lib/savings.mjs +8 -23
- package/lib/usage.mjs +399 -0
- package/lib/view.mjs +11 -0
- package/package.json +2 -2
- package/types/index.d.ts +34 -7
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
|
|
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
|
|
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
|
|
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
|
|
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
|
|
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
|
|
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
|
|
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,7 +1,7 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@alexeiled/claude-router",
|
|
3
|
-
"version": "1.
|
|
4
|
-
"description": "Native Claude Code Mod: model and effort routing for the main conversation, advised by Jev, Clef, Clef Flash, OpenAI or Ollama.",
|
|
3
|
+
"version": "1.12.0",
|
|
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",
|
|
7
7
|
"repository": {
|
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
|
|
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
|
|
115
|
-
//
|
|
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
|
|
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;
|