@alexeiled/claude-router 1.13.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
@@ -33,10 +33,13 @@ export const CELL_SUMS = [
33
33
  ];
34
34
  const USD = new Set(['routedUsd', 'yoursUsd', 'cheaperUsd', 'strongerUsd', 'switchUsd']);
35
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 = /^[^|]+\|[^|]+\|.+@[^@]+$/;
36
+ export const DAY = /^\d{4}-\d{2}-\d{2}$/;
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/lib/view.mjs CHANGED
@@ -56,6 +56,9 @@ export function initialView(model) {
56
56
  // Routed usage by day: every session's records as last read or written, and this session's own.
57
57
  usageStore: null,
58
58
  usageSession: null,
59
+ // Subagents by day: every session's records as last read or written, and this session's own.
60
+ subagentStore: null,
61
+ subagentSession: null,
59
62
  // The Usage tab's controls: the period (kept across sessions), the breakdown, the what-if view, the open row
60
63
  // (`<group>:<name>`), and whether Delete history waits for its confirmation.
61
64
  usagePeriod: 'session',
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@alexeiled/claude-router",
3
- "version": "1.13.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.
@@ -114,8 +120,8 @@ declare module 'claude-code' {
114
120
  version: 1;
115
121
  since: number | null;
116
122
  }
117
- // Subagent routing counts for one agent type in one mode (lib/subagents.mjs). `differs`: agents the decision moved off
118
- // core's model; `choices`: agents by models key decided, or 'core'. USD over the priced requests.
123
+ // Subagent routing counts for one agent type (lib/subagents.mjs). `differs`: agents the decision moved off core's
124
+ // model. USD over the priced requests.
119
125
  interface RouterSubagentCounts {
120
126
  agents: number;
121
127
  differs: number;
@@ -125,7 +131,8 @@ declare module 'claude-code' {
125
131
  routedUsd: number;
126
132
  respawns: number;
127
133
  failures: number;
128
- choices: Record<string, number>;
134
+ // Agents by the model id they ran on; in `undated`, by the models key decided ('core': Claude Code's model).
135
+ models: Record<string, number>;
129
136
  }
130
137
  // Spawns that passed through for one reason, priced on the model they ran on.
131
138
  interface RouterSubagentPassed {
@@ -133,16 +140,25 @@ declare module 'claude-code' {
133
140
  requests: number;
134
141
  pricedRequests: number;
135
142
  usd: number;
143
+ models: Record<string, number>;
144
+ }
145
+ // One local calendar day of subagents: routed types and pass-throughs by reason.
146
+ interface RouterSubagentDay {
147
+ routed: Record<string, RouterSubagentCounts>;
148
+ passed: Partial<
149
+ Record<'fork' | 'workflow' | 'explicit' | 'teammate' | 'unlisted' | 'pinned' | 'unknown', RouterSubagentPassed>
150
+ >;
136
151
  }
137
- // Kept across sessions, one per session under store key 'subagents:v1:<session id>' or their sum in the view, since
138
- // the first agent after the last reset (ms).
152
+ // Kept across sessions, one per session under store key 'subagents:v1:<session id>' or their sum in the view, by day
153
+ // ('2026-10-13'), since the first agent after the last reset (ms). `undated` holds a record from before 1.14.0.
139
154
  interface RouterSubagentStore {
140
- version: 1;
155
+ version: 2;
141
156
  since: number | null;
142
- routed: { on: Record<string, RouterSubagentCounts> };
143
- passed: Partial<Record<'fork' | 'explicit' | 'teammate' | 'workflow' | 'unlisted', RouterSubagentPassed>>;
157
+ days: Record<string, RouterSubagentDay>;
158
+ undated?: RouterSubagentDay;
144
159
  }
145
- // 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:
146
162
  // replies, routedUsd, yoursUsd, cheaperUsd, strongerUsd, switchUsd, inputTokens, cacheReadTokens, outputTokens.
147
163
  // `whatIf` is [replies, USD] of the same tokens on each model id as yours; `yours` replies by your model's id;
148
164
  // `hours` routed USD by local hour; `turns` and `switches` count turns on the day they ended.
@@ -157,7 +173,7 @@ declare module 'claude-code' {
157
173
  // Kept across sessions, one per session under store key 'usage:v1:<session id>' or their sum in the view, by day
158
174
  // ('2026-10-13'), since its first turn written after the last reset (ms).
159
175
  interface RouterUsageStore {
160
- version: 1;
176
+ version: 1 | 2;
161
177
  since: number | null;
162
178
  days: Record<string, RouterUsageDay>;
163
179
  }
@@ -165,6 +181,10 @@ declare module 'claude-code' {
165
181
  interface RouterView {
166
182
  phase: 'ready' | 'choosing' | 'routed' | 'manual' | 'unavailable';
167
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;
168
188
  nativeModel: string;
169
189
  // The effort Claude Code sent on the turn's first request, before routing.
170
190
  nativeEffort?: string | number | null;
@@ -213,7 +233,9 @@ declare module 'claude-code' {
213
233
  activityMetrics?: RouterActivityMetrics | null;
214
234
  savings?: RouterSavingsSession | null;
215
235
  savingsStore?: RouterSavingsStore | null;
236
+ // Every session's subagent records as last read or written, and this session's own.
216
237
  subagentStore?: RouterSubagentStore | null;
238
+ subagentSession?: RouterSubagentStore | null;
217
239
  // Every session's usage records as last read or written, and this session's own.
218
240
  usageStore?: RouterUsageStore | null;
219
241
  usageSession?: RouterUsageStore | null;
@@ -249,6 +271,8 @@ declare module 'claude-code' {
249
271
  lastRoute: RouterTier;
250
272
  // The activity of the route running now; absent in loops saved before 1.6.
251
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;
252
276
  state: RouterPolicyState;
253
277
  models: Record<string, { lastAt: number; prefixTokens: number }>;
254
278
  resolutions: Record<string, string>;