@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/.claude-plugin/plugin.json +1 -1
- package/CHANGELOG.md +46 -0
- package/README.md +3 -0
- package/docs/architecture.md +11 -1
- package/docs/configuration.md +6 -2
- package/docs/evaluation.md +8 -7
- package/docs/native-router.md +2 -1
- package/docs/router-band.svg +30 -8
- package/docs/router-pane-now.svg +134 -111
- package/docs/router-pane-policy.svg +47 -43
- package/docs/router-pane-usage-whatif.svg +75 -12
- package/docs/router-pane-usage.svg +79 -13
- package/docs/routing-modes.md +139 -0
- package/docs/user-guide.md +11 -5
- package/hooks/native-router.mjs +170 -23
- package/lib/activity.mjs +8 -2
- package/lib/band.mjs +43 -11
- package/lib/config.mjs +69 -17
- package/lib/cost.mjs +3 -0
- package/lib/display.mjs +21 -2
- package/lib/modes.mjs +98 -0
- package/lib/panel.mjs +338 -45
- package/lib/route.mjs +80 -23
- package/lib/subagents.mjs +182 -64
- package/lib/usage.mjs +32 -20
- package/lib/view.mjs +3 -0
- package/package.json +2 -1
- package/types/index.d.ts +34 -10
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
|
|
38
|
-
// either.
|
|
39
|
-
const
|
|
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:
|
|
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); `
|
|
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:
|
|
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(([
|
|
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
|
-
|
|
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
|
|
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:
|
|
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
|
|
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('|',
|
|
288
|
-
const route = key.slice(activity.length + tier.length +
|
|
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.
|
|
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
|
|
118
|
-
//
|
|
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
|
-
|
|
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,
|
|
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:
|
|
155
|
+
version: 2;
|
|
141
156
|
since: number | null;
|
|
142
|
-
|
|
143
|
-
|
|
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|
|
|
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>;
|