@alexeiled/claude-router 1.6.1 → 1.7.1
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 +53 -0
- package/README.md +14 -4
- package/docs/activity-routing.md +254 -0
- package/docs/architecture.md +11 -5
- package/docs/configuration.md +56 -44
- package/docs/evaluation.md +34 -7
- package/docs/native-router.md +17 -14
- package/docs/router-band.svg +78 -80
- package/docs/router-pane-classifier.svg +46 -41
- package/docs/router-pane-now.svg +9 -9
- package/docs/router-pane-routing.svg +73 -87
- package/docs/router-pane-usage.svg +134 -0
- package/docs/user-guide.md +81 -57
- package/hooks/native-router.mjs +316 -44
- package/lib/activity-stats.mjs +165 -11
- package/lib/band.mjs +82 -55
- package/lib/config.mjs +49 -32
- package/lib/cost.mjs +21 -6
- package/lib/display.mjs +101 -4
- package/lib/panel.mjs +409 -77
- package/lib/probe-results.mjs +40 -0
- package/lib/route.mjs +34 -10
- package/lib/savings.mjs +238 -0
- package/lib/view.mjs +10 -1
- package/package.json +2 -1
- package/types/index.d.ts +55 -0
|
@@ -0,0 +1,40 @@
|
|
|
1
|
+
// Generated by scripts/probe-results.mjs from experiments/mod-router/results/activity-probe-*.json; do not edit.
|
|
2
|
+
// The last checked-in activity probe per classifier id: the model it probed, correct answers of the probes, p95
|
|
3
|
+
// latency in ms, and the UTC date of the run.
|
|
4
|
+
export const PROBE_RESULTS = {
|
|
5
|
+
"clef-flash": {
|
|
6
|
+
"model": "clef-flash",
|
|
7
|
+
"correct": 69,
|
|
8
|
+
"probes": 70,
|
|
9
|
+
"p95Ms": 874,
|
|
10
|
+
"date": "2026-10-09"
|
|
11
|
+
},
|
|
12
|
+
"clef": {
|
|
13
|
+
"model": "clef",
|
|
14
|
+
"correct": 69,
|
|
15
|
+
"probes": 70,
|
|
16
|
+
"p95Ms": 883,
|
|
17
|
+
"date": "2026-10-09"
|
|
18
|
+
},
|
|
19
|
+
"jev": {
|
|
20
|
+
"model": "jev-1.13.0",
|
|
21
|
+
"correct": 70,
|
|
22
|
+
"probes": 70,
|
|
23
|
+
"p95Ms": 299,
|
|
24
|
+
"date": "2026-10-10"
|
|
25
|
+
},
|
|
26
|
+
"ollama": {
|
|
27
|
+
"model": "qwen3.5:9b",
|
|
28
|
+
"correct": 66,
|
|
29
|
+
"probes": 70,
|
|
30
|
+
"p95Ms": 3483,
|
|
31
|
+
"date": "2026-10-09"
|
|
32
|
+
},
|
|
33
|
+
"openai": {
|
|
34
|
+
"model": "gpt-6-luna",
|
|
35
|
+
"correct": 70,
|
|
36
|
+
"probes": 70,
|
|
37
|
+
"p95Ms": 286,
|
|
38
|
+
"date": "2026-10-10"
|
|
39
|
+
}
|
|
40
|
+
};
|
package/lib/route.mjs
CHANGED
|
@@ -9,7 +9,7 @@ const SNAPSHOTS = { 'claude-haiku-4-5': 'claude-haiku-4-5-20251001' };
|
|
|
9
9
|
|
|
10
10
|
// A request this much smaller than the last means the history was compacted or rewound: the cached prefixes the
|
|
11
11
|
// observations describe are gone, so they are dropped rather than priced as warm.
|
|
12
|
-
const HISTORY_SHRINK = 0.8;
|
|
12
|
+
export const HISTORY_SHRINK = 0.8;
|
|
13
13
|
|
|
14
14
|
// Whether the engine served the requested model, allowing for a dated snapshot of it.
|
|
15
15
|
export function isSameModel(requested, served) {
|
|
@@ -53,6 +53,8 @@ export function emptyLoop(config, model) {
|
|
|
53
53
|
turnId: null,
|
|
54
54
|
decision: null,
|
|
55
55
|
ineligible: [],
|
|
56
|
+
// Your model's simulated cache for the routing-vs-your-model readout (compareReply in savings.mjs).
|
|
57
|
+
yours: null,
|
|
56
58
|
};
|
|
57
59
|
}
|
|
58
60
|
|
|
@@ -69,6 +71,7 @@ export function resetHistory(loop) {
|
|
|
69
71
|
would: loop.would ? { ...loop.would, state: freshState(loop.would.state) } : null,
|
|
70
72
|
// The active turn keeps its route, pin and fallback suspension; the next turn decides afresh.
|
|
71
73
|
ineligible: [],
|
|
74
|
+
yours: null,
|
|
72
75
|
};
|
|
73
76
|
}
|
|
74
77
|
|
|
@@ -128,7 +131,7 @@ export function chooseRoute(config, loop, input) {
|
|
|
128
131
|
facts: { ...facts, lastRoute: from.lastRoute },
|
|
129
132
|
},
|
|
130
133
|
);
|
|
131
|
-
const { activity, tier, model, effort, reason } = run;
|
|
134
|
+
const { activity, tier, model, effort, reason, lateral } = run;
|
|
132
135
|
// What the would-route's next request costs against the applied one's; a route priced against itself would
|
|
133
136
|
// still give a spread, so only a different request is priced.
|
|
134
137
|
const priced =
|
|
@@ -146,7 +149,7 @@ export function chooseRoute(config, loop, input) {
|
|
|
146
149
|
input.now,
|
|
147
150
|
)
|
|
148
151
|
: null;
|
|
149
|
-
wouldRoute = { activity, tier, model, effort, reason, difference };
|
|
152
|
+
wouldRoute = { activity, tier, model, effort, reason, lateral, difference };
|
|
150
153
|
const stays = pin || !run.tier;
|
|
151
154
|
would = {
|
|
152
155
|
lastRoute: stays ? from.lastRoute : run.tier,
|
|
@@ -183,7 +186,14 @@ function routeTurn(config, loop, { facts, advice, pin, nativeModel, contextKnown
|
|
|
183
186
|
pin || config.activityRouting !== 'on' ? null : chooseActivity(config, advice, incumbent, facts.effort);
|
|
184
187
|
let result =
|
|
185
188
|
pin && TIERS.includes(pin)
|
|
186
|
-
? {
|
|
189
|
+
? {
|
|
190
|
+
tier: pin,
|
|
191
|
+
activity: null,
|
|
192
|
+
reason: 'pinned',
|
|
193
|
+
lateral: null,
|
|
194
|
+
escalated: false,
|
|
195
|
+
state: { ...loop.state, turn: loop.state.turn + 1 },
|
|
196
|
+
}
|
|
187
197
|
: decideCell({ config, projected, facts, advice, state: loop.state, now, incumbent, activity });
|
|
188
198
|
// Without a reliable reading of the context, a route with a smaller window than the last one might overflow.
|
|
189
199
|
const shrinksUnmeasured = (cell) =>
|
|
@@ -200,14 +210,18 @@ function routeTurn(config, loop, { facts, advice, pin, nativeModel, contextKnown
|
|
|
200
210
|
if (contextKnown) {
|
|
201
211
|
const routeFor = (tier) => resolveRoute(config, tier, result.activity);
|
|
202
212
|
const fitted = fitTier(config, result.tier, costs.nextContextTokens(facts), routeFor);
|
|
203
|
-
if (fitted !== result.tier) result = { ...result, tier: fitted, reason: 'context-fit' };
|
|
213
|
+
if (fitted !== result.tier) result = { ...result, tier: fitted, reason: 'context-fit', lateral: null };
|
|
204
214
|
}
|
|
205
|
-
|
|
215
|
+
// A lateral outcome describes the cell the lateral rule chose; a context or availability override replaces it.
|
|
216
|
+
if (shrinksUnmeasured(result)) result = { ...result, ...last, reason: 'context-unknown', lateral: null };
|
|
206
217
|
if (!fits(result)) {
|
|
218
|
+
// A cell labelled with another activity would run, and stick, a route this turn did not choose.
|
|
207
219
|
const native = cellForModel(config, nativeModel);
|
|
208
220
|
const cells = [last, native, ...TIERS.map((tier) => ({ tier, activity }))];
|
|
209
|
-
const fallback = cells.find(
|
|
210
|
-
|
|
221
|
+
const fallback = cells.find(
|
|
222
|
+
(cell) => cell && (cell.activity === null || cell.activity === activity) && fits(cell),
|
|
223
|
+
) ?? { tier: null, activity: null };
|
|
224
|
+
result = { ...result, ...fallback, reason: 'model-unavailable', lateral: null };
|
|
211
225
|
}
|
|
212
226
|
const route = result.tier ? routeOf(result) : null;
|
|
213
227
|
const model = route ? routeSpec(config, route).id : nativeModel;
|
|
@@ -252,9 +266,12 @@ function decideCell({ config, projected, facts, advice, state, now, incumbent, a
|
|
|
252
266
|
incumbentRoute: incumbent.route,
|
|
253
267
|
escalateTo,
|
|
254
268
|
});
|
|
269
|
+
// `decide` takes the failure's signature whenever it escalates, before the cash gate can hold the move; a later
|
|
270
|
+
// context or availability override keeps the flag.
|
|
271
|
+
const escalated = step.state.escalatedSignature !== state.escalatedSignature;
|
|
255
272
|
const route = routeFor(step.tier);
|
|
256
273
|
if (step.tier !== incumbent.tier || sameRequest(config, route, incumbent.route, facts.effort))
|
|
257
|
-
return { ...step, activity };
|
|
274
|
+
return { ...step, activity, lateral: null, escalated };
|
|
258
275
|
const lateral = lateralMove({
|
|
259
276
|
config: projected,
|
|
260
277
|
from: incumbent.route,
|
|
@@ -267,7 +284,14 @@ function decideCell({ config, projected, facts, advice, state, now, incumbent, a
|
|
|
267
284
|
costs,
|
|
268
285
|
});
|
|
269
286
|
const activityOf = lateral.move ? activity : incumbent.activity;
|
|
270
|
-
return {
|
|
287
|
+
return {
|
|
288
|
+
...step,
|
|
289
|
+
activity: activityOf,
|
|
290
|
+
reason: lateral.reason,
|
|
291
|
+
estimate: lateral.estimate,
|
|
292
|
+
lateral: lateral.move ? 'taken' : 'refused',
|
|
293
|
+
escalated,
|
|
294
|
+
};
|
|
271
295
|
}
|
|
272
296
|
|
|
273
297
|
// A tool continuation keeps the turn's route and activity; only the context or the model list can move it.
|
package/lib/savings.mjs
ADDED
|
@@ -0,0 +1,238 @@
|
|
|
1
|
+
// Routing vs your model: what each main reply cost at configured list prices on the model that served it, against
|
|
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 and keeps the totals in the view and, per session, in $.store under SAVINGS_PREFIX.
|
|
4
|
+
|
|
5
|
+
import { ratesAt } from './cost.mjs';
|
|
6
|
+
import { HISTORY_SHRINK, isSameModel } from './route.mjs';
|
|
7
|
+
|
|
8
|
+
// Each session keeps its own record under this prefix and its session id: $.store has no atomic update, and Claude
|
|
9
|
+
// Code 2.1.296 writes one key under a file lock (observed, not in the types), so sessions finishing turns at the same
|
|
10
|
+
// moment do not overwrite each other.
|
|
11
|
+
export const SAVINGS_PREFIX = 'savings:v1:';
|
|
12
|
+
// When Reset stats last ran (ms), from any session: a session may still hold its record from before and write it back.
|
|
13
|
+
// The activity metrics records (METRICS_PREFIX) use it too.
|
|
14
|
+
export const SAVINGS_RESET_KEY = 'savings:reset:v1';
|
|
15
|
+
// Fewer replies than this read "too early": one switch and its cache write dominate a short run.
|
|
16
|
+
export const EARLY_REPLIES = 10;
|
|
17
|
+
const TTLS = ['5m', '1h'];
|
|
18
|
+
|
|
19
|
+
// The model entry an API model id runs on: its configured id, a dated snapshot of it, or the id with a context
|
|
20
|
+
// suffix such as `[1m]`. Null when no entry prices it.
|
|
21
|
+
export function modelSpec(config, id) {
|
|
22
|
+
if (typeof id !== 'string') return null;
|
|
23
|
+
const bare = id.replace(/\[[^\]]*\]$/, '');
|
|
24
|
+
const dated = (model) => bare.startsWith(model.id) && /^-\d{8}$/.test(bare.slice(model.id.length));
|
|
25
|
+
return Object.values(config.models).find((model) => isSameModel(model.id, bare) || dated(model)) ?? null;
|
|
26
|
+
}
|
|
27
|
+
|
|
28
|
+
// One request's list price in USD: `counts` are its uncached input, cache read, cache write and output tokens, the
|
|
29
|
+
// writes at `writeMultiplier` times input. Long-context rates follow the whole prompt.
|
|
30
|
+
export function requestUsd(model, { input, cacheRead, cacheWrite, output }, writeMultiplier) {
|
|
31
|
+
const rates = ratesAt(model, input + cacheRead + cacheWrite);
|
|
32
|
+
return (
|
|
33
|
+
(rates.input * (input + cacheWrite * writeMultiplier) + rates.cacheRead * cacheRead + rates.output * output) / 1e6
|
|
34
|
+
);
|
|
35
|
+
}
|
|
36
|
+
|
|
37
|
+
const truthy = (value) => /^(1|true|yes|on)$/i.test(String(value ?? '').trim());
|
|
38
|
+
|
|
39
|
+
// The prompt-cache lifetime Claude Code gives the main conversation, by its own rule as of 2.1.296: FORCE_PROMPT_CACHING_5M,
|
|
40
|
+
// then CLAUDE_CODE_PROMPT_CACHE_TTL, then the `promptCacheTtl` setting, then ENABLE_PROMPT_CACHING_1H, then one hour
|
|
41
|
+
// for a Claude plan subscriber and five minutes otherwise. Its usage reports carry no 5m/1h split, so this is how the
|
|
42
|
+
// writes are priced. Limit: a subscriber billed as overage gets five minutes, which this cannot see.
|
|
43
|
+
export function sessionCacheTtl({ force5m, envTtl, settingTtl, enable1h, subscriber }) {
|
|
44
|
+
if (truthy(force5m)) return '5m';
|
|
45
|
+
if (TTLS.includes(envTtl)) return envTtl;
|
|
46
|
+
if (TTLS.includes(settingTtl)) return settingTtl;
|
|
47
|
+
if (truthy(enable1h) || subscriber) return '1h';
|
|
48
|
+
return '5m';
|
|
49
|
+
}
|
|
50
|
+
|
|
51
|
+
const isCount = (n) => Number.isFinite(n) && n >= 0;
|
|
52
|
+
|
|
53
|
+
// One main reply. `state` is your model's simulated cache: `{ total, at, onYours, model, effort }` after a reply, or
|
|
54
|
+
// null at the session start and after a compaction, which counts as on your model with nothing cached; a state of
|
|
55
|
+
// another model or effort (after `/model` or an effort change) counts as null. `served` is the route the
|
|
56
|
+
// reply ran on, `{ model, effort }` with the API's model id; `yours` the session's model and effort.
|
|
57
|
+
//
|
|
58
|
+
// Routed is the reply's usage on the served model. Yours is the same tokens on your model: while this reply and the
|
|
59
|
+
// one before it both ran on your route, the usage itself, so equal routes differ by exactly 0. Otherwise a single
|
|
60
|
+
// cache that never switched: it reads the previous prompt, up to this one less its uncached input, if that is inside
|
|
61
|
+
// the cache lifetime and no compaction shrank the history, and never less than the API actually read (a shared
|
|
62
|
+
// system-prompt cache, a lifetime longer than assumed); it writes the rest. Output tokens stay the same.
|
|
63
|
+
//
|
|
64
|
+
// The difference splits into the model price (the served model on your cache, against yours: cheaper models when
|
|
65
|
+
// negative, stronger than yours when positive) and the cache the switches cost (routed against the served model on
|
|
66
|
+
// your cache), never negative. The parts sum to the difference by construction. `reply` is null when a model has no
|
|
67
|
+
// price or `ttl` is not a known cache lifetime.
|
|
68
|
+
export function compareReply(config, state, { usage, served, yours, ttl, now }) {
|
|
69
|
+
const counts = {
|
|
70
|
+
input: usage?.input_tokens,
|
|
71
|
+
cacheRead: usage?.cache_read_input_tokens,
|
|
72
|
+
cacheWrite: usage?.cache_creation_input_tokens,
|
|
73
|
+
output: usage?.output_tokens,
|
|
74
|
+
};
|
|
75
|
+
if (!Object.values(counts).every(isCount)) return { state, reply: null };
|
|
76
|
+
const total = counts.input + counts.cacheRead + counts.cacheWrite;
|
|
77
|
+
const [servedSpec, yoursSpec] = [modelSpec(config, served.model), modelSpec(config, yours.model)];
|
|
78
|
+
const sameModel = servedSpec ? servedSpec === yoursSpec : served.model === yours.model;
|
|
79
|
+
const onYours = sameModel && (served.effort ?? null) === (yours.effort ?? null);
|
|
80
|
+
const identity = { model: yoursSpec?.id ?? yours.model, effort: yours.effort ?? null };
|
|
81
|
+
const next = { total, at: now, onYours, ...identity };
|
|
82
|
+
// A cache simulated for another model or effort of yours is none of this one's: the new one starts cold.
|
|
83
|
+
const prior = state?.model === identity.model && state.effort === identity.effort ? state : null;
|
|
84
|
+
const write = config.cache.writeMultiplier[ttl];
|
|
85
|
+
if (
|
|
86
|
+
!servedSpec ||
|
|
87
|
+
!yoursSpec ||
|
|
88
|
+
!Number.isFinite(servedSpec.output) ||
|
|
89
|
+
!Number.isFinite(yoursSpec.output) ||
|
|
90
|
+
!Number.isFinite(write)
|
|
91
|
+
)
|
|
92
|
+
return { state: next, reply: null };
|
|
93
|
+
const routedUsd = requestUsd(servedSpec, counts, write);
|
|
94
|
+
let yoursUsd = routedUsd;
|
|
95
|
+
let servedOnYoursUsd = routedUsd;
|
|
96
|
+
if (!(onYours && (prior?.onYours ?? true))) {
|
|
97
|
+
const warm =
|
|
98
|
+
prior && now - prior.at < config.cache.ttlMs[ttl] && total >= prior.total * HISTORY_SHRINK && prior.total > 0;
|
|
99
|
+
const cacheRead = Math.max(counts.cacheRead, warm ? Math.min(prior.total, total - counts.input) : 0);
|
|
100
|
+
const single = { ...counts, cacheRead, cacheWrite: total - counts.input - cacheRead };
|
|
101
|
+
yoursUsd = requestUsd(yoursSpec, single, write);
|
|
102
|
+
servedOnYoursUsd = requestUsd(servedSpec, single, write);
|
|
103
|
+
}
|
|
104
|
+
const modelUsd = servedOnYoursUsd - yoursUsd;
|
|
105
|
+
return {
|
|
106
|
+
state: next,
|
|
107
|
+
reply: {
|
|
108
|
+
routedUsd,
|
|
109
|
+
yoursUsd,
|
|
110
|
+
cheaperUsd: Math.min(0, modelUsd),
|
|
111
|
+
strongerUsd: Math.max(0, modelUsd),
|
|
112
|
+
switchUsd: routedUsd - servedOnYoursUsd,
|
|
113
|
+
// The model a stronger reply ran on, for "9 replies on Opus 5.5".
|
|
114
|
+
strongerModel: modelUsd > 0 ? servedSpec.id : null,
|
|
115
|
+
},
|
|
116
|
+
};
|
|
117
|
+
}
|
|
118
|
+
|
|
119
|
+
const SUMS = ['routedUsd', 'yoursUsd', 'cheaperUsd', 'strongerUsd', 'switchUsd'];
|
|
120
|
+
|
|
121
|
+
// A session's totals: replies, the five sums, and per tier (`none`: not chosen by routing) the replies and their
|
|
122
|
+
// routed cost, which the pane's bar and share line draw. `stronger` counts replies by the stronger model they ran on.
|
|
123
|
+
export function emptyTotals() {
|
|
124
|
+
return {
|
|
125
|
+
replies: 0,
|
|
126
|
+
routedUsd: 0,
|
|
127
|
+
yoursUsd: 0,
|
|
128
|
+
cheaperUsd: 0,
|
|
129
|
+
strongerUsd: 0,
|
|
130
|
+
switchUsd: 0,
|
|
131
|
+
tiers: {},
|
|
132
|
+
tierUsd: {},
|
|
133
|
+
stronger: {},
|
|
134
|
+
};
|
|
135
|
+
}
|
|
136
|
+
|
|
137
|
+
export function addReply(totals, reply, tier) {
|
|
138
|
+
const key = tier ?? 'none';
|
|
139
|
+
const next = { ...totals, replies: totals.replies + 1 };
|
|
140
|
+
for (const sum of SUMS) next[sum] = totals[sum] + reply[sum];
|
|
141
|
+
next.tiers = { ...totals.tiers, [key]: (totals.tiers[key] ?? 0) + 1 };
|
|
142
|
+
next.tierUsd = { ...totals.tierUsd, [key]: (totals.tierUsd[key] ?? 0) + reply.routedUsd };
|
|
143
|
+
if (reply.strongerModel)
|
|
144
|
+
next.stronger = { ...totals.stronger, [reply.strongerModel]: (totals.stronger[reply.strongerModel] ?? 0) + 1 };
|
|
145
|
+
return next;
|
|
146
|
+
}
|
|
147
|
+
|
|
148
|
+
// A record kept across sessions, one session's or their sum: replies and the five sums since `since` (ms), the first
|
|
149
|
+
// reply after a reset.
|
|
150
|
+
export function emptySavingsStore() {
|
|
151
|
+
return {
|
|
152
|
+
version: 1,
|
|
153
|
+
since: null,
|
|
154
|
+
replies: 0,
|
|
155
|
+
routedUsd: 0,
|
|
156
|
+
yoursUsd: 0,
|
|
157
|
+
cheaperUsd: 0,
|
|
158
|
+
strongerUsd: 0,
|
|
159
|
+
switchUsd: 0,
|
|
160
|
+
};
|
|
161
|
+
}
|
|
162
|
+
|
|
163
|
+
const STORE_KEYS = Object.keys(emptySavingsStore());
|
|
164
|
+
|
|
165
|
+
// The stored value if it has the known shape, else an empty store: a missing, hand-edited or unknown value must not
|
|
166
|
+
// break a turn or the pane.
|
|
167
|
+
export function readSavingsStore(value) {
|
|
168
|
+
const ok =
|
|
169
|
+
value !== null &&
|
|
170
|
+
typeof value === 'object' &&
|
|
171
|
+
!Array.isArray(value) &&
|
|
172
|
+
Object.keys(value).length === STORE_KEYS.length &&
|
|
173
|
+
STORE_KEYS.every((key) => Object.hasOwn(value, key)) &&
|
|
174
|
+
value.version === 1 &&
|
|
175
|
+
(value.since === null || Number.isFinite(value.since)) &&
|
|
176
|
+
Number.isSafeInteger(value.replies) &&
|
|
177
|
+
value.replies >= 0 &&
|
|
178
|
+
SUMS.every((sum) => Number.isFinite(value[sum]));
|
|
179
|
+
return ok ? { ...value } : emptySavingsStore();
|
|
180
|
+
}
|
|
181
|
+
|
|
182
|
+
// A record whose first reply came before the last reset at `resetAt` (ms) reads as empty.
|
|
183
|
+
export function afterReset(record, resetAt) {
|
|
184
|
+
return Number.isFinite(resetAt) && record.since !== null && record.since < resetAt ? emptySavingsStore() : record;
|
|
185
|
+
}
|
|
186
|
+
|
|
187
|
+
// The totals kept across sessions: every session's record since the last reset added up, since the earliest.
|
|
188
|
+
export function mergeSavingsStores(values, resetAt = null) {
|
|
189
|
+
const merged = emptySavingsStore();
|
|
190
|
+
for (const one of values.map((value) => afterReset(readSavingsStore(value), resetAt))) {
|
|
191
|
+
const since = [merged.since, one.since].filter(Number.isFinite);
|
|
192
|
+
merged.since = since.length ? Math.min(...since) : null;
|
|
193
|
+
merged.replies += one.replies;
|
|
194
|
+
for (const sum of SUMS) merged[sum] += one[sum];
|
|
195
|
+
}
|
|
196
|
+
return merged;
|
|
197
|
+
}
|
|
198
|
+
|
|
199
|
+
// A finished turn's totals added to the store at `now`.
|
|
200
|
+
export function recordSavingsStore(store, totals, now) {
|
|
201
|
+
if (!totals.replies) return store;
|
|
202
|
+
const next = { ...store, since: store.since ?? now, replies: store.replies + totals.replies };
|
|
203
|
+
for (const sum of SUMS) next[sum] = store[sum] + totals[sum];
|
|
204
|
+
return next;
|
|
205
|
+
}
|
|
206
|
+
|
|
207
|
+
const cents = (usd) => Math.round(usd * 100);
|
|
208
|
+
|
|
209
|
+
// What the UI shows for a set of totals, in whole cents so the shown parts add up: the difference is routed less
|
|
210
|
+
// yours as shown, and the switch part takes the rounding remainder. A surplus goes to the switch part if the totals
|
|
211
|
+
// have one, else to the stronger part if they have one, else to the cheaper part toward 0. A shortfall comes off the
|
|
212
|
+
// stronger part down to 0, then the cheaper part. So no part changes sign or appears from rounding alone. `early`
|
|
213
|
+
// below EARLY_REPLIES replies. `share` is the difference against yours; `ratio` routed over yours.
|
|
214
|
+
export function readout(totals) {
|
|
215
|
+
const [routed, yours, cheaper, stronger] = [
|
|
216
|
+
totals.routedUsd,
|
|
217
|
+
totals.yoursUsd,
|
|
218
|
+
totals.cheaperUsd,
|
|
219
|
+
totals.strongerUsd,
|
|
220
|
+
].map(cents);
|
|
221
|
+
const difference = routed - yours;
|
|
222
|
+
const rest = difference - cheaper - stronger;
|
|
223
|
+
const switches = totals.switchUsd ? Math.max(0, rest) : 0;
|
|
224
|
+
const surplus = !totals.switchUsd && totals.strongerUsd ? Math.max(0, rest) : 0;
|
|
225
|
+
const strongerShown = Math.max(0, stronger + Math.min(0, rest)) + surplus;
|
|
226
|
+
return {
|
|
227
|
+
replies: totals.replies,
|
|
228
|
+
early: totals.replies < EARLY_REPLIES,
|
|
229
|
+
routedUsd: routed / 100,
|
|
230
|
+
yoursUsd: yours / 100,
|
|
231
|
+
differenceUsd: difference / 100,
|
|
232
|
+
cheaperUsd: (difference - strongerShown - switches) / 100,
|
|
233
|
+
strongerUsd: strongerShown / 100,
|
|
234
|
+
switchUsd: switches / 100,
|
|
235
|
+
share: yours > 0 ? difference / yours : null,
|
|
236
|
+
ratio: yours > 0 ? routed / yours : null,
|
|
237
|
+
};
|
|
238
|
+
}
|
package/lib/view.mjs
CHANGED
|
@@ -10,6 +10,8 @@ export function initialView(model) {
|
|
|
10
10
|
activeTurnId: null,
|
|
11
11
|
mode: 'auto',
|
|
12
12
|
nativeModel: model,
|
|
13
|
+
// The effort Claude Code sent on the turn's first request, before routing: with nativeModel, "your model".
|
|
14
|
+
nativeEffort: null,
|
|
13
15
|
selectedModel: null,
|
|
14
16
|
actualModel: null,
|
|
15
17
|
tier: null,
|
|
@@ -37,8 +39,13 @@ export function initialView(model) {
|
|
|
37
39
|
history: [],
|
|
38
40
|
tiers: [],
|
|
39
41
|
activities: [],
|
|
42
|
+
routes: [],
|
|
40
43
|
activityStats: null,
|
|
41
44
|
activityStore: null,
|
|
45
|
+
activityMetrics: null,
|
|
46
|
+
// Routing vs your model: this session's totals and the totals kept across sessions as last read or written.
|
|
47
|
+
savings: null,
|
|
48
|
+
savingsStore: null,
|
|
42
49
|
configPath: null,
|
|
43
50
|
tuning: null,
|
|
44
51
|
tuningBase: null,
|
|
@@ -79,7 +86,8 @@ export function continuationView(config, decision, context) {
|
|
|
79
86
|
|
|
80
87
|
// The view patch for a main reply's usage. `tier` is the routed tier that served it, else null; `activity` the
|
|
81
88
|
// turn's activity as the view labels it, else null.
|
|
82
|
-
|
|
89
|
+
// `route` is the (model, effort) the request went out with, so the switch count reads what served each reply.
|
|
90
|
+
export function responseMetrics(view, response, tier, activity = null, route = null) {
|
|
83
91
|
const usage = response.usage;
|
|
84
92
|
const counters = usage ? [usage.input_tokens, usage.cache_read_input_tokens, usage.cache_creation_input_tokens] : [];
|
|
85
93
|
const inputTokens =
|
|
@@ -96,6 +104,7 @@ export function responseMetrics(view, response, tier, activity = null) {
|
|
|
96
104
|
history: [...(view?.history ?? []), inputTokens].slice(-HISTORY),
|
|
97
105
|
tiers: [...(view?.tiers ?? []), tier ?? null].slice(-HISTORY),
|
|
98
106
|
activities: [...(view?.activities ?? []), activity ?? null].slice(-HISTORY),
|
|
107
|
+
routes: [...(view?.routes ?? []), route ?? null].slice(-HISTORY),
|
|
99
108
|
}
|
|
100
109
|
: {}),
|
|
101
110
|
};
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@alexeiled/claude-router",
|
|
3
|
-
"version": "1.
|
|
3
|
+
"version": "1.7.1",
|
|
4
4
|
"description": "Native Claude Code Mod: model and effort routing for the main conversation, advised by Jev, Clef, Clef Flash, 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
|
+
"probe:results": "node scripts/probe-results.mjs",
|
|
39
40
|
"pack:dry": "npm pack --dry-run",
|
|
40
41
|
"prepublishOnly": "npm run check && npm test"
|
|
41
42
|
}
|
package/types/index.d.ts
CHANGED
|
@@ -7,6 +7,8 @@ declare module 'claude-code' {
|
|
|
7
7
|
type RouterActivityMode = 'off' | 'shadow' | 'on';
|
|
8
8
|
// A finished turn's bucket, read from its tool calls.
|
|
9
9
|
type RouterObserved = 'code' | 'docs' | 'ops' | 'read' | 'talk';
|
|
10
|
+
// A route change inside the incumbent's tier: taken, refused (does not pay back, a hold, the cash gate), or none.
|
|
11
|
+
type RouterLateral = 'taken' | 'refused' | null;
|
|
10
12
|
// Classifier output. `activity` is null when not asked, or missing, malformed or failed.
|
|
11
13
|
interface RouterAdvice {
|
|
12
14
|
choice: RouterTier | 'uncertain';
|
|
@@ -31,6 +33,7 @@ declare module 'claude-code' {
|
|
|
31
33
|
model: string;
|
|
32
34
|
effort: string | number | null;
|
|
33
35
|
reason: string;
|
|
36
|
+
lateral: RouterLateral;
|
|
34
37
|
difference: RouterUsdRange | null;
|
|
35
38
|
}
|
|
36
39
|
// Shadow turns, those `on` would route differently, and of those the ones with a `difference`, summed.
|
|
@@ -44,11 +47,19 @@ declare module 'claude-code' {
|
|
|
44
47
|
requests: number;
|
|
45
48
|
inputTokens: number;
|
|
46
49
|
outputTokens: number;
|
|
50
|
+
// The list price of the priced replies (null: none had one), how many replies had a price, and routed replies by
|
|
51
|
+
// `model@effort`; absent in views saved by 1.7.0.
|
|
52
|
+
routedUsd?: number | null;
|
|
53
|
+
pricedRequests?: number;
|
|
54
|
+
routes?: Record<string, number>;
|
|
47
55
|
}
|
|
48
56
|
// Per-session activity stats; 'none' counts turns without an applied or accepted activity.
|
|
49
57
|
interface RouterActivitySession {
|
|
50
58
|
byActivity: Partial<Record<RouterActivity | 'none', RouterActivityCounts>>;
|
|
51
59
|
switches: { tier: number; activity: number };
|
|
60
|
+
// Lateral moves taken and refused (by economics, a hold or the cash gate), outside shadow only; absent in views saved
|
|
61
|
+
// by 1.7.0.
|
|
62
|
+
lateral?: { taken: number; refused: number };
|
|
52
63
|
agreement: { matched: number; total: number };
|
|
53
64
|
shadow: RouterActivityShadow;
|
|
54
65
|
}
|
|
@@ -61,6 +72,14 @@ declare module 'claude-code' {
|
|
|
61
72
|
// A 1.6.0 store has `differs` and `turns` only; readStore fills the rest with zeros.
|
|
62
73
|
shadow: RouterActivityShadow;
|
|
63
74
|
}
|
|
75
|
+
// Cross-session readings under store key 'activity:metrics:v1'. Classifier wait per turn by classifier id, in
|
|
76
|
+
// LATENCY_BOUNDS buckets plus one above; at most 8 ids. Cheaper activity moves taken in 'on' and the escalations that
|
|
77
|
+
// followed one.
|
|
78
|
+
interface RouterActivityMetrics {
|
|
79
|
+
version: 1;
|
|
80
|
+
latency: Record<string, number[]>;
|
|
81
|
+
downMoves: { moves: number; escalations: number };
|
|
82
|
+
}
|
|
64
83
|
interface RouterComparison {
|
|
65
84
|
candidate: RouterTier;
|
|
66
85
|
incumbent: RouterTier;
|
|
@@ -98,10 +117,35 @@ declare module 'claude-code' {
|
|
|
98
117
|
>;
|
|
99
118
|
activityRouting?: RouterActivityMode;
|
|
100
119
|
}
|
|
120
|
+
// Routing vs your model at configured list prices, in USD: routed replies, the same tokens on your model, and the
|
|
121
|
+
// difference's parts (cheaper models, stronger than yours, cache writes from switches), which sum to it.
|
|
122
|
+
interface RouterSavingsSums {
|
|
123
|
+
replies: number;
|
|
124
|
+
routedUsd: number;
|
|
125
|
+
yoursUsd: number;
|
|
126
|
+
cheaperUsd: number;
|
|
127
|
+
strongerUsd: number;
|
|
128
|
+
switchUsd: number;
|
|
129
|
+
}
|
|
130
|
+
// A session's totals; per tier ('none': not chosen by routing) its replies and their routed cost, and replies by the
|
|
131
|
+
// stronger model they ran on.
|
|
132
|
+
interface RouterSavingsSession extends RouterSavingsSums {
|
|
133
|
+
tiers: Partial<Record<RouterTier | 'none', number>>;
|
|
134
|
+
tierUsd: Partial<Record<RouterTier | 'none', number>>;
|
|
135
|
+
stronger: Record<string, number>;
|
|
136
|
+
}
|
|
137
|
+
// Totals kept across sessions, one per session under store key 'savings:v1:<session id>' or their sum in the view,
|
|
138
|
+
// since the first reply after the last reset (ms).
|
|
139
|
+
interface RouterSavingsStore extends RouterSavingsSums {
|
|
140
|
+
version: 1;
|
|
141
|
+
since: number | null;
|
|
142
|
+
}
|
|
101
143
|
interface RouterView {
|
|
102
144
|
phase: 'ready' | 'choosing' | 'routed' | 'manual' | 'unavailable';
|
|
103
145
|
mode: 'auto' | 'manual';
|
|
104
146
|
nativeModel: string;
|
|
147
|
+
// The effort Claude Code sent on the turn's first request, before routing.
|
|
148
|
+
nativeEffort?: string | number | null;
|
|
105
149
|
activeTurnId?: string | null;
|
|
106
150
|
selectedModel?: string | null;
|
|
107
151
|
actualModel?: string | null;
|
|
@@ -133,9 +177,14 @@ declare module 'claude-code' {
|
|
|
133
177
|
tiers?: (RouterTier | null)[];
|
|
134
178
|
// Aligned with `history` and `tiers`.
|
|
135
179
|
activities?: (RouterActivity | null)[];
|
|
180
|
+
// The (model, effort) each reply's request went out with, aligned with tiers; null where routing did not choose.
|
|
181
|
+
routes?: (string | null)[];
|
|
136
182
|
activityStats?: RouterActivitySession | null;
|
|
137
183
|
// The counts kept across sessions as last read or written.
|
|
138
184
|
activityStore?: RouterActivityStore | null;
|
|
185
|
+
activityMetrics?: RouterActivityMetrics | null;
|
|
186
|
+
savings?: RouterSavingsSession | null;
|
|
187
|
+
savingsStore?: RouterSavingsStore | null;
|
|
139
188
|
configPath?: string | null;
|
|
140
189
|
tuning?: Partial<RouterTuning> | null;
|
|
141
190
|
tuningBase?: RouterTuning | null;
|
|
@@ -184,11 +233,17 @@ declare module 'claude-code' {
|
|
|
184
233
|
comparison?: RouterComparison | null;
|
|
185
234
|
// The applied activity; `wouldRoute` is set only in shadow mode.
|
|
186
235
|
activity?: RouterActivity | null;
|
|
236
|
+
lateral?: RouterLateral;
|
|
237
|
+
// A failure asked for an escalation this turn, also one the cash gate held or context-fit replaced.
|
|
238
|
+
escalated?: boolean;
|
|
187
239
|
wouldRoute?: RouterWouldRoute | null;
|
|
188
240
|
pinned: boolean;
|
|
189
241
|
requestedPin: RouterTier | null;
|
|
190
242
|
} | null;
|
|
191
243
|
ineligible: string[];
|
|
244
|
+
// Your model's simulated cache for routing vs your model: the last prompt's tokens, when, whether that reply ran
|
|
245
|
+
// on your route, and the model and effort it was kept for. Null at the start and after a compaction.
|
|
246
|
+
yours?: { total: number; at: number; onYours: boolean; model: string; effort: string | null } | null;
|
|
192
247
|
engineModel?: string;
|
|
193
248
|
suspended?: boolean;
|
|
194
249
|
}
|