@alexeiled/claude-router 1.14.0 → 1.16.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 +61 -0
- package/README.md +4 -1
- package/docs/architecture.md +17 -3
- package/docs/configuration.md +6 -2
- package/docs/evaluation.md +15 -11
- package/docs/native-router.md +2 -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 +143 -0
- package/docs/user-guide.md +17 -2
- package/hooks/native-router.mjs +428 -36
- package/lib/activity-stats.mjs +33 -11
- package/lib/activity.mjs +12 -6
- package/lib/band.mjs +8 -1
- package/lib/config.mjs +72 -17
- package/lib/cost.mjs +3 -0
- package/lib/decisions.mjs +252 -0
- package/lib/display.mjs +46 -5
- package/lib/facts.mjs +125 -4
- package/lib/modes.mjs +98 -0
- package/lib/panel.mjs +41 -3
- package/lib/policy.mjs +7 -4
- package/lib/route.mjs +84 -26
- package/lib/savings.mjs +17 -0
- package/lib/usage.mjs +31 -19
- package/package.json +2 -1
- package/types/index.d.ts +15 -2
package/lib/route.mjs
CHANGED
|
@@ -1,8 +1,8 @@
|
|
|
1
1
|
import { chooseActivity, compareRoutes, lateralMove, sameRequest } from './activity.mjs';
|
|
2
|
-
import { ACTIVITIES, rank, resolveRoute, routeSpec, TIERS } from './config.mjs';
|
|
2
|
+
import { ACTIVITIES, rank, resolveRoute, routeSpec, sameRoute, TIERS } from './config.mjs';
|
|
3
3
|
import * as costs from './cost.mjs';
|
|
4
|
-
import { clip,
|
|
5
|
-
import { CONTEXT_FILL, decide, fitTier, initialState } from './policy.mjs';
|
|
4
|
+
import { clip, completedSince, extractFacts } from './facts.mjs';
|
|
5
|
+
import { CONTEXT_FILL, decide, fitTier, initialState, sameTaskOf } from './policy.mjs';
|
|
6
6
|
|
|
7
7
|
// Exact observed API snapshot, not a rule that merges different dated versions.
|
|
8
8
|
const SNAPSHOTS = { 'claude-haiku-4-5': 'claude-haiku-4-5-20251001' };
|
|
@@ -42,6 +42,9 @@ export function emptyLoop(config, model) {
|
|
|
42
42
|
return {
|
|
43
43
|
lastRoute: cell?.tier ?? config.baselineTier,
|
|
44
44
|
lastActivity: cell?.activity ?? null,
|
|
45
|
+
// The route (models key, effort) the last routed decision ran for `lastRoute`, kept as it ran: a routing mode or
|
|
46
|
+
// a route edit changes the config, never the route in use. Null until the first decision.
|
|
47
|
+
route: null,
|
|
45
48
|
state: initialState(),
|
|
46
49
|
models: {},
|
|
47
50
|
resolutions: {},
|
|
@@ -100,11 +103,12 @@ export function prepareLoop(loop, messageCount) {
|
|
|
100
103
|
export function nativeFacts(config, loop, { messages, prompt, effort, turnId, contextTokens }) {
|
|
101
104
|
const facts = extractFacts({ messages, output_config: { effort } }, loop, config.context);
|
|
102
105
|
if (typeof prompt === 'string') facts.prompt = clip(prompt, config.context.maxTextChars);
|
|
103
|
-
// A move down on the same task waits out the dwell and for a
|
|
106
|
+
// A move down on the same task waits out the dwell and for a checkpoint since the last model change: a passed check,
|
|
107
|
+
// or the success the running route's activity can show (completedSince).
|
|
104
108
|
const since = loop.switchedAt ?? { requests: 0, messageCount: 0 };
|
|
105
109
|
const downAllowed =
|
|
106
110
|
(loop.requests ?? 0) - since.requests >= config.policy.minDwellRequests &&
|
|
107
|
-
|
|
111
|
+
completedSince(messages, since.messageCount, activityOf(config, loop));
|
|
108
112
|
// A loop saved without the field counts as measured, keeping the vote streak.
|
|
109
113
|
return {
|
|
110
114
|
...facts,
|
|
@@ -146,6 +150,7 @@ export function chooseRoute(config, loop, input) {
|
|
|
146
150
|
state: applied.state,
|
|
147
151
|
lastRoute: kept ? loop.lastRoute : applied.tier,
|
|
148
152
|
lastActivity: kept ? activityOf(config, loop) : applied.activity,
|
|
153
|
+
route: kept ? (loop.route ?? null) : applied.route,
|
|
149
154
|
turnId: facts.turnKey,
|
|
150
155
|
decision: applied,
|
|
151
156
|
suspended: false,
|
|
@@ -160,11 +165,32 @@ const activityOf = (config, loop) => (config.activityRouting === 'on' ? (loop.la
|
|
|
160
165
|
// One decision (plan §5.2) for the cell `{ tier, activity }` it lands on. Outside `on` the activity is null throughout.
|
|
161
166
|
function routeTurn(config, loop, { facts, advice, pin, nativeModel, contextKnown, availableModels, now }) {
|
|
162
167
|
const projected = economicConfig(config, loop);
|
|
163
|
-
const routeOf = (cell) => resolveRoute(config, cell.tier, cell.activity);
|
|
164
|
-
const specOf = (cell) => routeSpec(config, routeOf(cell));
|
|
165
168
|
const last = { tier: loop.lastRoute, activity: activityOf(config, loop) };
|
|
166
169
|
const tier0 = TIERS.includes(facts.lastRoute) ? facts.lastRoute : config.baselineTier;
|
|
167
|
-
|
|
170
|
+
// The incumbent runs the route in use, not the one config gives its cell now. It is rebuilt from config for a loop
|
|
171
|
+
// from before 1.15, a route whose model left the config or can no longer run, and a route kept for an activity that
|
|
172
|
+
// no longer applies (activity routing turned off).
|
|
173
|
+
const usable = (route) => {
|
|
174
|
+
const model = Object.hasOwn(config.models, route.model) ? config.models[route.model] : null;
|
|
175
|
+
return Boolean(
|
|
176
|
+
model && isModelAllowed(model.id, availableModels, nativeModel) && !loop.ineligible.includes(model.id),
|
|
177
|
+
);
|
|
178
|
+
};
|
|
179
|
+
const inUse = loop.route && usable(loop.route) && (loop.lastActivity ?? null) === last.activity ? loop.route : null;
|
|
180
|
+
const incumbent = {
|
|
181
|
+
tier: tier0,
|
|
182
|
+
activity: last.activity,
|
|
183
|
+
route: inUse ?? resolveRoute(config, tier0, last.activity),
|
|
184
|
+
};
|
|
185
|
+
// A decision that stays on the incumbent's cell keeps running its route; only a taken lateral move or a pin runs the
|
|
186
|
+
// cell's route from config. So a mode change reaches the request only through the gates.
|
|
187
|
+
const stays = (cell) =>
|
|
188
|
+
cell.tier === incumbent.tier &&
|
|
189
|
+
(cell.activity ?? null) === incumbent.activity &&
|
|
190
|
+
cell.lateral !== 'taken' &&
|
|
191
|
+
cell.reason !== 'pinned';
|
|
192
|
+
const routeOf = (cell) => (stays(cell) ? incumbent.route : resolveRoute(config, cell.tier, cell.activity));
|
|
193
|
+
const specOf = (cell) => routeSpec(config, routeOf(cell));
|
|
168
194
|
const activity =
|
|
169
195
|
pin || config.activityRouting !== 'on' ? null : chooseActivity(config, advice, incumbent, facts.effort, facts);
|
|
170
196
|
let result =
|
|
@@ -178,9 +204,12 @@ function routeTurn(config, loop, { facts, advice, pin, nativeModel, contextKnown
|
|
|
178
204
|
state: { ...loop.state, turn: loop.state.turn + 1 },
|
|
179
205
|
}
|
|
180
206
|
: decideCell({ config, projected, facts, advice, state: loop.state, now, incumbent, activity });
|
|
181
|
-
// Without a reliable reading of the context, a route with a smaller window than the last one might overflow.
|
|
207
|
+
// Without a reliable reading of the context, a route with a smaller window than the last one might overflow. Before
|
|
208
|
+
// the first decision the session's own model ran, not the mode's route for its cell.
|
|
209
|
+
const lastSpec =
|
|
210
|
+
(!loop.decision && Object.values(config.models).find((m) => isSameModel(m.id, nativeModel))) || specOf(last);
|
|
182
211
|
const shrinksUnmeasured = (cell) =>
|
|
183
|
-
(!contextKnown || !loop.historyMeasured) && specOf(cell).contextWindow <
|
|
212
|
+
(!contextKnown || !loop.historyMeasured) && specOf(cell).contextWindow < lastSpec.contextWindow;
|
|
184
213
|
const fits = (cell) => {
|
|
185
214
|
const model = specOf(cell);
|
|
186
215
|
return (
|
|
@@ -191,7 +220,8 @@ function routeTurn(config, loop, { facts, advice, pin, nativeModel, contextKnown
|
|
|
191
220
|
);
|
|
192
221
|
};
|
|
193
222
|
if (contextKnown) {
|
|
194
|
-
const
|
|
223
|
+
const cell = result;
|
|
224
|
+
const routeFor = (tier) => (tier === cell.tier ? routeOf(cell) : resolveRoute(config, tier, cell.activity));
|
|
195
225
|
const fitted = fitTier(config, result.tier, costs.nextContextTokens(facts), routeFor);
|
|
196
226
|
if (fitted !== result.tier) result = { ...result, tier: fitted, reason: 'context-fit', lateral: null };
|
|
197
227
|
}
|
|
@@ -212,7 +242,7 @@ function routeTurn(config, loop, { facts, advice, pin, nativeModel, contextKnown
|
|
|
212
242
|
let comparison = null;
|
|
213
243
|
const candidate = pin ?? advice?.choice;
|
|
214
244
|
if (contextKnown && loop.lastRequest && TIERS.includes(candidate) && candidate !== loop.lastRoute) {
|
|
215
|
-
const [to, from] = [resolveRoute(config, candidate, activity),
|
|
245
|
+
const [to, from] = [resolveRoute(config, candidate, activity), incumbent.route];
|
|
216
246
|
const forecast = costs.switchEconomics(projected, to, from, facts, now);
|
|
217
247
|
comparison = {
|
|
218
248
|
candidate,
|
|
@@ -222,7 +252,7 @@ function routeTurn(config, loop, { facts, advice, pin, nativeModel, contextKnown
|
|
|
222
252
|
outputTokens: loop.lastRequest.outputTokens,
|
|
223
253
|
};
|
|
224
254
|
}
|
|
225
|
-
return { ...result, model, effort, comparison, pinned: Boolean(pin), requestedPin: pin ?? null };
|
|
255
|
+
return { ...result, route, model, effort, comparison, pinned: Boolean(pin), requestedPin: pin ?? null };
|
|
226
256
|
}
|
|
227
257
|
|
|
228
258
|
// Steps 3-6 of plan §5.2: the tier as `decide` picks it, every candidate priced at its route for `activity` and the
|
|
@@ -230,13 +260,13 @@ function routeTurn(config, loop, { facts, advice, pin, nativeModel, contextKnown
|
|
|
230
260
|
// never switch: a label alone decides nothing.
|
|
231
261
|
function decideCell({ config, projected, facts, advice, state, now, incumbent, activity }) {
|
|
232
262
|
const routeFor = (tier) => resolveRoute(config, tier, activity);
|
|
233
|
-
//
|
|
234
|
-
// order against it
|
|
263
|
+
// Failures move to the lowest tier whose route is stronger than the one running, or another request that does not
|
|
264
|
+
// order against it: after a mode change the next tier's route can be the weaker one.
|
|
235
265
|
const escalates = (t) => {
|
|
236
266
|
const order = compareRoutes(config, routeFor(t), incumbent.route, facts.effort);
|
|
237
267
|
return order > 0 || (order === null && !sameRequest(config, routeFor(t), incumbent.route, facts.effort));
|
|
238
268
|
};
|
|
239
|
-
const escalateTo =
|
|
269
|
+
const escalateTo = (tier) => TIERS.slice(rank(tier) + 1).find(escalates) ?? null;
|
|
240
270
|
const step = decide({
|
|
241
271
|
config: projected,
|
|
242
272
|
facts,
|
|
@@ -253,15 +283,18 @@ function decideCell({ config, projected, facts, advice, state, now, incumbent, a
|
|
|
253
283
|
// context or availability override keeps the flag.
|
|
254
284
|
const escalated = step.state.escalatedSignature !== state.escalatedSignature;
|
|
255
285
|
const route = routeFor(step.tier);
|
|
256
|
-
|
|
286
|
+
// Without a classifier answer the running route stays, whatever the mode's route for the cell, during a hold too.
|
|
287
|
+
if (!advice || step.tier !== incumbent.tier || sameRequest(config, route, incumbent.route, facts.effort))
|
|
257
288
|
return { ...step, activity, lateral: null, escalated };
|
|
258
289
|
const lateral = lateralMove({
|
|
259
290
|
config: projected,
|
|
260
291
|
from: incumbent.route,
|
|
261
292
|
to: route,
|
|
262
|
-
// Returning to the base route needs no evidence
|
|
263
|
-
|
|
293
|
+
// Returning to the base route needs no evidence, nor does the incumbent's own cell whose configured route changed
|
|
294
|
+
// (a routing mode, a route edit): the label is not what moves.
|
|
295
|
+
mass: activity === null || activity === incumbent.activity ? 1 : (advice?.activity?.probabilities?.[activity] ?? 0),
|
|
264
296
|
hold: step.reason === 'hold',
|
|
297
|
+
sameTask: sameTaskOf(config, advice, facts),
|
|
265
298
|
facts,
|
|
266
299
|
now,
|
|
267
300
|
costs,
|
|
@@ -277,11 +310,17 @@ function decideCell({ config, projected, facts, advice, state, now, incumbent, a
|
|
|
277
310
|
};
|
|
278
311
|
}
|
|
279
312
|
|
|
313
|
+
// The route a decision runs: the one it recorded, or for a decision from before 1.15 its cell's route in config.
|
|
314
|
+
const runningRoute = (config, decision) =>
|
|
315
|
+
decision.route && Object.hasOwn(config.models, decision.route.model)
|
|
316
|
+
? decision.route
|
|
317
|
+
: resolveRoute(config, decision.tier, decision.activity ?? null);
|
|
318
|
+
|
|
280
319
|
// Whether some activity's route at the decision's tier is stronger than the one running: only then can the turn's own
|
|
281
320
|
// tool calls move it (observedMove), so a step on the strongest route skips reading the transcript.
|
|
282
321
|
export function canMoveUp(config, decision, effort) {
|
|
283
322
|
if (config.activityRouting !== 'on' || !decision?.tier || decision.pinned) return false;
|
|
284
|
-
const from =
|
|
323
|
+
const from = runningRoute(config, decision);
|
|
285
324
|
return ACTIVITIES.some((a) => compareRoutes(config, resolveRoute(config, decision.tier, a), from, effort) > 0);
|
|
286
325
|
}
|
|
287
326
|
|
|
@@ -294,7 +333,7 @@ export function canMoveUp(config, decision, effort) {
|
|
|
294
333
|
export function observedMove(config, loop, { observed, facts, contextKnown, now }) {
|
|
295
334
|
const decision = loop.decision;
|
|
296
335
|
if (!canMoveUp(config, decision, facts.effort) || !ACTIVITIES.includes(observed)) return loop;
|
|
297
|
-
const from =
|
|
336
|
+
const from = runningRoute(config, decision);
|
|
298
337
|
// The gates price the route that will run: the one the context fits, not the tier's first choice.
|
|
299
338
|
const routeFor = (tier) => resolveRoute(config, tier, observed);
|
|
300
339
|
const tier = fitTier(config, decision.tier, costs.nextContextTokens(facts), routeFor);
|
|
@@ -309,10 +348,13 @@ export function observedMove(config, loop, { observed, facts, contextKnown, now
|
|
|
309
348
|
return {
|
|
310
349
|
...loop,
|
|
311
350
|
lastActivity: observed,
|
|
351
|
+
// The route in use belongs to `lastRoute`: a move the context fitted to another tier leaves it to be rebuilt.
|
|
352
|
+
route: tier === loop.lastRoute ? to : null,
|
|
312
353
|
decision: {
|
|
313
354
|
...decision,
|
|
314
355
|
tier,
|
|
315
356
|
activity: observed,
|
|
357
|
+
route: to,
|
|
316
358
|
model: routeSpec(config, to).id,
|
|
317
359
|
effort: costs.routeEffort(config, to, facts.effort),
|
|
318
360
|
reason: lateral.reason,
|
|
@@ -325,21 +367,37 @@ export function observedMove(config, loop, { observed, facts, contextKnown, now
|
|
|
325
367
|
// calls (observedMove) can move it.
|
|
326
368
|
export function continueRoute(config, loop, { nativeModel, contextTokens, contextKnown, availableModels, effort }) {
|
|
327
369
|
if (!loop.decision) return loop;
|
|
370
|
+
// A fit to another tier serves this turn only: `loop.route` stays the route of `lastRoute`, as the tier does.
|
|
328
371
|
let decision = loop.decision;
|
|
329
372
|
if (contextKnown && decision.tier) {
|
|
373
|
+
// The route the turn runs, which a mode change or a held move can keep apart from config, stays while the context
|
|
374
|
+
// fits it; past that, the routes config gives each tier, its own tier's first.
|
|
375
|
+
const running = runningRoute(config, decision);
|
|
330
376
|
const routeOf = (tier) => resolveRoute(config, tier, decision.activity ?? null);
|
|
331
|
-
const
|
|
332
|
-
|
|
377
|
+
const fits = contextTokens <= routeSpec(config, running).contextWindow * CONTEXT_FILL;
|
|
378
|
+
const fitted = fits ? decision.tier : fitTier(config, decision.tier, contextTokens, routeOf);
|
|
379
|
+
if (!fits && !sameRoute(routeOf(fitted), running)) {
|
|
380
|
+
const route = routeOf(fitted);
|
|
333
381
|
decision = {
|
|
334
382
|
...decision,
|
|
335
383
|
tier: fitted,
|
|
336
|
-
|
|
337
|
-
|
|
384
|
+
route,
|
|
385
|
+
model: routeSpec(config, route).id,
|
|
386
|
+
effort: costs.routeEffort(config, route, effort),
|
|
338
387
|
reason: 'context-fit',
|
|
339
388
|
};
|
|
389
|
+
}
|
|
340
390
|
}
|
|
341
391
|
if (!isModelAllowed(decision.model, availableModels, nativeModel) || loop.ineligible.includes(decision.model)) {
|
|
342
|
-
decision = {
|
|
392
|
+
decision = {
|
|
393
|
+
...decision,
|
|
394
|
+
tier: null,
|
|
395
|
+
activity: null,
|
|
396
|
+
route: null,
|
|
397
|
+
model: nativeModel,
|
|
398
|
+
effort,
|
|
399
|
+
reason: 'model-unavailable',
|
|
400
|
+
};
|
|
343
401
|
}
|
|
344
402
|
return { ...loop, decision };
|
|
345
403
|
}
|
package/lib/savings.mjs
CHANGED
|
@@ -135,6 +135,23 @@ export function compareReply(config, state, { usage, served, yours, ttl, now })
|
|
|
135
135
|
};
|
|
136
136
|
}
|
|
137
137
|
|
|
138
|
+
// Why a routed reply gets no price, by compareReply's checks in its order, or null when it prices it: the usage or its
|
|
139
|
+
// model id is missing or its counts do not read (`usage`; the hook drops a usage without a model before compareReply), the served model or your model has no configured price (`model`), or the cache
|
|
140
|
+
// lifetime is unknown (`ttl`). The usage record keeps priced replies only; this names what it leaves out.
|
|
141
|
+
export function unpricedCause(config, { usage, served, yours, ttl }) {
|
|
142
|
+
const counts = [
|
|
143
|
+
usage?.input_tokens,
|
|
144
|
+
usage?.cache_read_input_tokens,
|
|
145
|
+
usage?.cache_creation_input_tokens,
|
|
146
|
+
usage?.output_tokens,
|
|
147
|
+
];
|
|
148
|
+
if (!usage?.model || !counts.every(isCount)) return 'usage';
|
|
149
|
+
const [servedSpec, yoursSpec] = [modelSpec(config, served.model), modelSpec(config, yours.model)];
|
|
150
|
+
if (!servedSpec || !yoursSpec || !Number.isFinite(servedSpec.output) || !Number.isFinite(yoursSpec.output))
|
|
151
|
+
return 'model';
|
|
152
|
+
return Number.isFinite(config.cache.writeMultiplier[ttl]) ? null : 'ttl';
|
|
153
|
+
}
|
|
154
|
+
|
|
138
155
|
// One main reply against every configured model as yours, at your effort, so the session readout can follow a
|
|
139
156
|
// `/model` change without replaying the session: `states` and `replies` by models key, each as compareReply returns,
|
|
140
157
|
// and `reply`, the prices against `yours`, the API model id /model selects now, or null.
|
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.16.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>;
|