@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/.claude-plugin/plugin.json +1 -1
- package/CHANGELOG.md +31 -0
- package/README.md +3 -0
- package/docs/architecture.md +10 -0
- package/docs/configuration.md +6 -2
- package/docs/native-router.md +1 -0
- package/docs/router-band.svg +30 -8
- package/docs/router-pane-now.svg +133 -131
- package/docs/router-pane-policy.svg +47 -43
- package/docs/routing-modes.md +139 -0
- package/docs/user-guide.md +4 -0
- package/hooks/native-router.mjs +144 -16
- package/lib/activity.mjs +8 -2
- package/lib/band.mjs +7 -1
- package/lib/config.mjs +69 -17
- package/lib/cost.mjs +3 -0
- package/lib/display.mjs +17 -2
- package/lib/modes.mjs +98 -0
- package/lib/panel.mjs +38 -3
- package/lib/route.mjs +80 -23
- package/lib/usage.mjs +31 -19
- package/package.json +2 -1
- package/types/index.d.ts +15 -2
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
|
|
38
|
-
// either.
|
|
39
|
-
const
|
|
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/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.
|
|
@@ -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|
|
|
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>;
|