@alexeiled/claude-router 1.14.0 → 1.15.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/usage.mjs CHANGED
@@ -34,9 +34,12 @@ export const CELL_SUMS = [
34
34
  const USD = new Set(['routedUsd', 'yoursUsd', 'cheaperUsd', 'strongerUsd', 'switchUsd']);
35
35
  const IS_USD = CELL_SUMS.map((sum) => USD.has(sum));
36
36
  export 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 = /^[^|]+\|[^|]+\|.+@[^@]+$/;
37
+ // `mode|activity|tier|id@effort`: mode, activity and tier never hold a `|`, and an effort never an `@`, so a model id
38
+ // may hold either. Version 1 records, from before routing modes, had no mode: every reply then ran `balanced`.
39
+ export const USAGE_VERSION = 2;
40
+ const CELL_KEY = /^[^|]+\|[^|]+\|[^|]+\|.+@[^@]+$/;
41
+ const V1_CELL_KEY = /^[^|]+\|[^|]+\|.+@[^@]+$/;
42
+ const V1_MODE = 'balanced';
40
43
  const HOUR = /^(1?\d|2[0-3])$/;
41
44
  // Sums are kept to a millionth of a dollar: enough for a cent-exact readout over many replies, and short in JSON.
42
45
  const microUsd = (usd) => Math.round(usd * 1e6) / 1e6;
@@ -60,21 +63,22 @@ export function daysBefore(ms, days) {
60
63
  }
61
64
 
62
65
  export function emptyUsage() {
63
- return { version: 1, since: null, days: {} };
66
+ return { version: USAGE_VERSION, since: null, days: {} };
64
67
  }
65
68
 
66
69
  const emptyDay = () => ({ cells: {}, whatIf: {}, yours: {}, hours: {}, turns: 0, switches: { tier: 0, activity: 0 } });
67
70
 
68
- // One routed main reply as its turn collects it. `at` is when it arrived (ms); `activity` the turn's activity and
71
+ // One routed main reply as its turn collects it. `at` is when it arrived (ms); `mode` the turn's routing mode;
72
+ // `activity` the turn's activity and
69
73
  // `tier` the tier that served it (null: none); `route` the model id that served it and the request's effort,
70
74
  // `id@effort` (`session` for no effort); `yours` your model's id; `reply` its prices against your model, and `replies`
71
75
  // against each model as yours keyed by model id, from compareModels; `usage` the API usage, whose counts compareReply
72
76
  // 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 }) {
77
+ export function replyEntry({ at, mode, activity, tier, route, yours, reply, replies, usage }) {
74
78
  const input = usage.input_tokens + usage.cache_read_input_tokens + usage.cache_creation_input_tokens;
75
79
  return {
76
80
  at,
77
- cell: `${activity ?? 'none'}|${tier ?? 'none'}|${route}`,
81
+ cell: `${mode}|${activity ?? 'none'}|${tier ?? 'none'}|${route}`,
78
82
  sums: [
79
83
  1,
80
84
  reply.routedUsd,
@@ -118,7 +122,7 @@ export function recordUsage(record, entries, { switched = null, now }) {
118
122
  days[dayKey(now)] = ended;
119
123
  const cutoff = daysBefore(now, RETAIN_DAYS);
120
124
  for (const key of Object.keys(days)) if (key < cutoff) delete days[key];
121
- return { version: 1, since: record.since ?? now, days };
125
+ return { version: USAGE_VERSION, since: record.since ?? now, days };
122
126
  }
123
127
 
124
128
  const isCount = (n) => Number.isSafeInteger(n) && n >= 0;
@@ -131,11 +135,12 @@ const isSums = (v) =>
131
135
  v.length === CELL_SUMS.length &&
132
136
  v.every((n, i) => Number.isFinite(n) && (i === CHEAPER ? n <= 0 : n >= 0));
133
137
 
134
- function readDay(day) {
138
+ function readDay(day, version) {
139
+ const key = version === 1 ? V1_CELL_KEY : CELL_KEY;
135
140
  const ok =
136
141
  isRecord(day) &&
137
142
  isRecord(day.cells) &&
138
- Object.entries(day.cells).every(([key, sums]) => CELL_KEY.test(key) && isSums(sums)) &&
143
+ Object.entries(day.cells).every(([cell, sums]) => key.test(cell) && isSums(sums)) &&
139
144
  isRecord(day.whatIf) &&
140
145
  Object.values(day.whatIf).every(isPair) &&
141
146
  isRecord(day.yours) &&
@@ -147,20 +152,27 @@ function readDay(day) {
147
152
  Object.keys(day.switches).length === 2 &&
148
153
  isCount(day.switches.tier) &&
149
154
  isCount(day.switches.activity);
150
- return ok ? day : null;
155
+ if (!ok) return null;
156
+ return version === 1
157
+ ? {
158
+ ...day,
159
+ cells: Object.fromEntries(Object.entries(day.cells).map(([cell, sums]) => [`${V1_MODE}|${cell}`, sums])),
160
+ }
161
+ : day;
151
162
  }
152
163
 
153
164
  // 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.
165
+ // while the others stay, so a hand edit never breaks a turn or the pane. A version 1 record reads as version 2, its
166
+ // replies under `balanced`; the session's next write stores it as version 2 under the same key.
155
167
  export function readUsage(value) {
156
- if (!isRecord(value) || value.version !== 1 || !isRecord(value.days)) return emptyUsage();
168
+ if (!isRecord(value) || ![1, USAGE_VERSION].includes(value.version) || !isRecord(value.days)) return emptyUsage();
157
169
  if (!(value.since === null || Number.isFinite(value.since))) return emptyUsage();
158
170
  const days = {};
159
171
  for (const [key, day] of Object.entries(value.days)) {
160
- const read = DAY.test(key) ? readDay(day) : null;
172
+ const read = DAY.test(key) ? readDay(day, value.version) : null;
161
173
  if (read) days[key] = read;
162
174
  }
163
- return { version: 1, since: value.since, days };
175
+ return { version: USAGE_VERSION, since: value.since, days };
164
176
  }
165
177
 
166
178
  // A record whose first reply came before the last reset at `resetAt` (ms) reads as empty.
@@ -282,11 +294,11 @@ export function allTime(usageStore, savingsStore) {
282
294
  };
283
295
  }
284
296
 
285
- // A cell key's parts, split at its first two `|` and its route's last `@` (CELL_KEY).
297
+ // A cell key's parts, split at its first three `|` and its route's last `@` (CELL_KEY).
286
298
  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('@')) };
299
+ const [mode, activity, tier] = key.split('|', 3);
300
+ const route = key.slice(mode.length + activity.length + tier.length + 3);
301
+ return { mode, activity, tier, route, model: route.slice(0, route.lastIndexOf('@')) };
290
302
  }
291
303
  // The part of a cell key a breakdown groups by, and the part it lists under each group.
292
304
  const keyPart = (key, by) => cellParts(key)[by];
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@alexeiled/claude-router",
3
- "version": "1.14.0",
3
+ "version": "1.15.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",
@@ -36,6 +36,7 @@
36
36
  "test:plugin": "bash scripts/plugin-test.sh",
37
37
  "format": "tools/node_modules/.bin/biome format --write .",
38
38
  "docs:images": "node scripts/render-doc-images.mjs",
39
+ "docs:modes": "node scripts/mode-matrix.mjs",
39
40
  "probe:results": "node scripts/probe-results.mjs",
40
41
  "pack:dry": "npm pack --dry-run",
41
42
  "prepublishOnly": "npm run check && npm test"
package/types/index.d.ts CHANGED
@@ -5,6 +5,12 @@ declare module 'claude-code' {
5
5
  type RouterActivity = 'code' | 'debug' | 'explore' | 'plan' | 'review' | 'ops' | 'docs';
6
6
  type RouterActivityAnswer = RouterActivity | 'uncertain';
7
7
  type RouterActivityMode = 'off' | 'on';
8
+ // The routing mode (lib/modes.mjs) and where it comes from, strongest first.
9
+ type RouterRoutingModeName = 'cost' | 'balanced' | 'quality';
10
+ interface RouterRoutingMode {
11
+ mode: RouterRoutingModeName;
12
+ source: 'session' | 'project' | 'profile' | 'default';
13
+ }
8
14
  // A finished turn's bucket, read from its tool calls.
9
15
  type RouterObserved = 'code' | 'docs' | 'ops' | 'read' | 'talk';
10
16
  // A route change inside the incumbent's tier: taken, refused (does not pay back, a hold, the cash gate), or none.
@@ -151,7 +157,8 @@ declare module 'claude-code' {
151
157
  days: Record<string, RouterSubagentDay>;
152
158
  undated?: RouterSubagentDay;
153
159
  }
154
- // One local calendar day of routed replies (lib/usage.mjs). `cells` by 'activity|tier|modelId@effort' hold, in order,
160
+ // One local calendar day of routed replies (lib/usage.mjs). `cells` by 'mode|activity|tier|id@effort' (version 1:
161
+ // 'activity|tier|id@effort', read as balanced) hold, in order, the sums:
155
162
  // replies, routedUsd, yoursUsd, cheaperUsd, strongerUsd, switchUsd, inputTokens, cacheReadTokens, outputTokens.
156
163
  // `whatIf` is [replies, USD] of the same tokens on each model id as yours; `yours` replies by your model's id;
157
164
  // `hours` routed USD by local hour; `turns` and `switches` count turns on the day they ended.
@@ -166,7 +173,7 @@ declare module 'claude-code' {
166
173
  // Kept across sessions, one per session under store key 'usage:v1:<session id>' or their sum in the view, by day
167
174
  // ('2026-10-13'), since its first turn written after the last reset (ms).
168
175
  interface RouterUsageStore {
169
- version: 1;
176
+ version: 1 | 2;
170
177
  since: number | null;
171
178
  days: Record<string, RouterUsageDay>;
172
179
  }
@@ -174,6 +181,10 @@ declare module 'claude-code' {
174
181
  interface RouterView {
175
182
  phase: 'ready' | 'choosing' | 'routed' | 'manual' | 'unavailable';
176
183
  mode: 'auto' | 'manual';
184
+ // The routing mode the next turn starts with; absent in views saved before 1.15.
185
+ routingMode?: RouterRoutingMode;
186
+ // Why the project's .claude/router.json was ignored, or null.
187
+ projectError?: string | null;
177
188
  nativeModel: string;
178
189
  // The effort Claude Code sent on the turn's first request, before routing.
179
190
  nativeEffort?: string | number | null;
@@ -260,6 +271,8 @@ declare module 'claude-code' {
260
271
  lastRoute: RouterTier;
261
272
  // The activity of the route running now; absent in loops saved before 1.6.
262
273
  lastActivity?: RouterActivity | null;
274
+ // The route (models key, effort) the last routed decision ran for lastRoute; absent in loops saved before 1.15.
275
+ route?: RouterRoute | null;
263
276
  state: RouterPolicyState;
264
277
  models: Record<string, { lastAt: number; prefixTokens: number }>;
265
278
  resolutions: Record<string, string>;