@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/band.mjs
CHANGED
|
@@ -11,6 +11,7 @@ import {
|
|
|
11
11
|
percentPair,
|
|
12
12
|
reasonActivity,
|
|
13
13
|
routeLabel,
|
|
14
|
+
routingModeText,
|
|
14
15
|
SAVINGS_COLOR,
|
|
15
16
|
shortReason,
|
|
16
17
|
TIER_COLOR,
|
|
@@ -162,7 +163,11 @@ export function bandSegments(config, view, usage, actions) {
|
|
|
162
163
|
)
|
|
163
164
|
: null;
|
|
164
165
|
if (!view.tier && view.phase === 'ready' && !view.actualModel)
|
|
165
|
-
return [
|
|
166
|
+
return [
|
|
167
|
+
segment(0, meter(null, true), part(' Routing on · ready', { dimColor: true })),
|
|
168
|
+
pin,
|
|
169
|
+
segment(5, part(routingModeText(view), { dimColor: true })),
|
|
170
|
+
].filter(Boolean);
|
|
166
171
|
const main = segment(
|
|
167
172
|
0,
|
|
168
173
|
// The space after the pill keeps its background off the next word.
|
|
@@ -193,6 +198,7 @@ export function bandSegments(config, view, usage, actions) {
|
|
|
193
198
|
main,
|
|
194
199
|
pin,
|
|
195
200
|
segment(1, part(shortReason(view.reason, reasonActivity(config, view)), { dimColor: true })),
|
|
201
|
+
segment(5, part(routingModeText(view), { dimColor: true })),
|
|
196
202
|
support ? segment(4, part(support, { dimColor: true })) : null,
|
|
197
203
|
Number.isFinite(switchUsd) && switchUsd >= 0.005
|
|
198
204
|
? segment(4, part(`switch cost ≈ ${usd(switchUsd)}`, { dimColor: true }))
|
package/lib/config.mjs
CHANGED
|
@@ -16,6 +16,10 @@ const withoutShadow = (file) =>
|
|
|
16
16
|
Object.fromEntries(Object.entries(file).filter(([key, value]) => !(value === 'shadow' && MODE_KEYS.includes(key))));
|
|
17
17
|
// A `subagents.types` value that asks the classifier instead of naming a model.
|
|
18
18
|
export const CLASSIFY = 'classify';
|
|
19
|
+
// The routing mode trades cost against answer quality (lib/modes.mjs). Not the session's auto|manual mode.
|
|
20
|
+
export const ROUTING_MODES = ['cost', 'balanced', 'quality'];
|
|
21
|
+
// The modes that patch the policy; `balanced` is the base policy itself.
|
|
22
|
+
const PATCHED_MODES = ['cost', 'quality'];
|
|
19
23
|
const SONNET_HIGH = { model: 'sonnet', effort: 'high' };
|
|
20
24
|
export const DEFAULTS = {
|
|
21
25
|
baselineTier: 'low',
|
|
@@ -128,6 +132,34 @@ export const DEFAULTS = {
|
|
|
128
132
|
// classifier yet: the probe results record whether the label was right, not its probability.
|
|
129
133
|
activityMass: 0.6,
|
|
130
134
|
},
|
|
135
|
+
// `cost` uses a cheaper route where the turn allows it, `quality` a stronger one; `balanced` routes as 1.14. The
|
|
136
|
+
// routes stay as configured: the mode moves a tier's route one step (lib/modes.mjs). Each mode's `policy` replaces
|
|
137
|
+
// those fields of `policy` while it is active. The values are codex-router's presets, not tuned on this router.
|
|
138
|
+
mode: 'balanced',
|
|
139
|
+
modes: {
|
|
140
|
+
cost: {
|
|
141
|
+
policy: {
|
|
142
|
+
upgradeVotes: 3,
|
|
143
|
+
upgradeBase: 0.85,
|
|
144
|
+
jumpConfidence: 0.98,
|
|
145
|
+
downgradeVotes: 1,
|
|
146
|
+
downgradeMass: 0.8,
|
|
147
|
+
minDwellRequests: 4,
|
|
148
|
+
escalationHoldTurns: 1,
|
|
149
|
+
},
|
|
150
|
+
},
|
|
151
|
+
quality: {
|
|
152
|
+
policy: {
|
|
153
|
+
upgradeVotes: 1,
|
|
154
|
+
upgradeBase: 0.6,
|
|
155
|
+
jumpConfidence: 0.9,
|
|
156
|
+
downgradeVotes: 3,
|
|
157
|
+
downgradeMass: 0.95,
|
|
158
|
+
minDwellRequests: 16,
|
|
159
|
+
escalationHoldTurns: 4,
|
|
160
|
+
},
|
|
161
|
+
},
|
|
162
|
+
},
|
|
131
163
|
// The active entry of `classifiers`. `api` names the wire protocol (CLASSIFIER_APIS); a user entry without one speaks
|
|
132
164
|
// `system-one`. `keyOption` names the plugin option that holds the bearer key, or null for no key (a local server);
|
|
133
165
|
// a `{name}` in `endpoint` is filled from the plugin option of that name. Both must be in CLASSIFIER_OPTIONS.
|
|
@@ -372,6 +404,12 @@ export function withActivities(file, draft) {
|
|
|
372
404
|
};
|
|
373
405
|
}
|
|
374
406
|
|
|
407
|
+
// The router.json `file` with the profile's routing mode; the default is written as no key.
|
|
408
|
+
export function withMode(file, mode) {
|
|
409
|
+
const { mode: _, ...rest } = file;
|
|
410
|
+
return mode === DEFAULTS.mode ? rest : { ...rest, mode };
|
|
411
|
+
}
|
|
412
|
+
|
|
375
413
|
// The pane's policy controls and the router.json fields they stand for. The classifier deadline saves on its own.
|
|
376
414
|
const TUNING_FIELDS = {
|
|
377
415
|
downgradeVotes: ['policy', 'downgradeVotes'],
|
|
@@ -462,7 +500,7 @@ function checkShape(file) {
|
|
|
462
500
|
if (file && typeof file === 'object' && Object.hasOwn(file, 'jev'))
|
|
463
501
|
throw new Error(`router.json uses the 1.1 jev section; ${MIGRATION_HINT}`);
|
|
464
502
|
checkObject(file, 'router.json', Object.keys(DEFAULTS));
|
|
465
|
-
const { routes, activities, models, cache, policy, classifiers, context, subagents } = file;
|
|
503
|
+
const { routes, activities, models, cache, policy, modes, classifiers, context, subagents } = file;
|
|
466
504
|
if (routes !== undefined) {
|
|
467
505
|
checkObject(routes, 'routes', TIERS);
|
|
468
506
|
for (const [tier, route] of Object.entries(routes)) checkObject(route, `routes.${tier}`, ROUTE_KEYS);
|
|
@@ -490,6 +528,13 @@ function checkShape(file) {
|
|
|
490
528
|
if (cache[map] !== undefined) checkObject(cache[map], `cache.${map}`);
|
|
491
529
|
}
|
|
492
530
|
if (policy !== undefined) checkObject(policy, 'policy', Object.keys(DEFAULTS.policy));
|
|
531
|
+
if (modes !== undefined) {
|
|
532
|
+
checkObject(modes, 'modes', PATCHED_MODES);
|
|
533
|
+
for (const [mode, entry] of Object.entries(modes)) {
|
|
534
|
+
checkObject(entry, `modes.${mode}`, ['policy']);
|
|
535
|
+
if (entry.policy !== undefined) checkObject(entry.policy, `modes.${mode}.policy`, Object.keys(DEFAULTS.policy));
|
|
536
|
+
}
|
|
537
|
+
}
|
|
493
538
|
if (classifiers !== undefined) {
|
|
494
539
|
checkObject(classifiers, 'classifiers');
|
|
495
540
|
for (const [id, entry] of Object.entries(classifiers)) checkObject(entry, `classifiers.${id}`, CLASSIFIER_KEYS);
|
|
@@ -536,22 +581,11 @@ function validate(config) {
|
|
|
536
581
|
}
|
|
537
582
|
for (const [alias, model] of Object.entries(config.models)) validateModel(`models.${alias}`, model);
|
|
538
583
|
if (!TIERS.includes(config.baselineTier)) throw new Error(`baselineTier must be one of ${TIERS.join(', ')}`);
|
|
539
|
-
|
|
540
|
-
|
|
541
|
-
|
|
542
|
-
|
|
543
|
-
|
|
544
|
-
if (!isNumber(p[field], 1, { integer: true })) throw new Error(`policy.${field} must be a positive integer`);
|
|
545
|
-
}
|
|
546
|
-
for (const field of ['reviewEveryRequests', 'minDwellRequests']) {
|
|
547
|
-
if (!isNumber(p[field], 0, { integer: true })) throw new Error(`policy.${field} must be a non-negative integer`);
|
|
548
|
-
}
|
|
549
|
-
// The pivot divides: tax / (tax + pivot). Zero makes a free switch NaN and silently stops that switch.
|
|
550
|
-
for (const side of ['upgrade', 'downgrade']) {
|
|
551
|
-
if (!isNumber(p[`${side}Slope`], 0)) throw new Error(`policy.${side}Slope must be a non-negative number`);
|
|
552
|
-
if (!isNumber(p[`${side}PivotUsd`], 0, { above: true })) throw new Error(`policy.${side}PivotUsd must be positive`);
|
|
553
|
-
}
|
|
554
|
-
if (!isNumber(p.cashCapUsd, 0)) throw new Error('policy.cashCapUsd must be a non-negative number');
|
|
584
|
+
validatePolicy(config.policy, 'policy');
|
|
585
|
+
if (!ROUTING_MODES.includes(config.mode)) throw new Error(`mode must be one of ${ROUTING_MODES.join(', ')}`);
|
|
586
|
+
// A patch is checked as the policy it makes; the base passed already, so an error is the patch's field.
|
|
587
|
+
for (const mode of PATCHED_MODES)
|
|
588
|
+
validatePolicy({ ...config.policy, ...config.modes[mode]?.policy }, `modes.${mode}.policy`);
|
|
555
589
|
const { cache, context } = config;
|
|
556
590
|
for (const map of ['writeMultiplier', 'ttlMs']) {
|
|
557
591
|
for (const [ttl, value] of Object.entries(cache[map]))
|
|
@@ -579,6 +613,24 @@ function validate(config) {
|
|
|
579
613
|
}
|
|
580
614
|
}
|
|
581
615
|
|
|
616
|
+
function validatePolicy(p, at) {
|
|
617
|
+
for (const field of ['upgradeBase', 'jumpConfidence', 'downgradeMass', 'continuationMass', 'activityMass']) {
|
|
618
|
+
if (!(isNumber(p[field], 0) && p[field] <= 1)) throw new Error(`${at}.${field} must be between 0 and 1`);
|
|
619
|
+
}
|
|
620
|
+
for (const field of ['upgradeVotes', 'downgradeVotes', 'downgradeHorizonTurns', 'escalationHoldTurns']) {
|
|
621
|
+
if (!isNumber(p[field], 1, { integer: true })) throw new Error(`${at}.${field} must be a positive integer`);
|
|
622
|
+
}
|
|
623
|
+
for (const field of ['reviewEveryRequests', 'minDwellRequests']) {
|
|
624
|
+
if (!isNumber(p[field], 0, { integer: true })) throw new Error(`${at}.${field} must be a non-negative integer`);
|
|
625
|
+
}
|
|
626
|
+
// The pivot divides: tax / (tax + pivot). Zero makes a free switch NaN and silently stops that switch.
|
|
627
|
+
for (const side of ['upgrade', 'downgrade']) {
|
|
628
|
+
if (!isNumber(p[`${side}Slope`], 0)) throw new Error(`${at}.${side}Slope must be a non-negative number`);
|
|
629
|
+
if (!isNumber(p[`${side}PivotUsd`], 0, { above: true })) throw new Error(`${at}.${side}PivotUsd must be positive`);
|
|
630
|
+
}
|
|
631
|
+
if (!isNumber(p.cashCapUsd, 0)) throw new Error(`${at}.cashCapUsd must be a non-negative number`);
|
|
632
|
+
}
|
|
633
|
+
|
|
582
634
|
function validateModel(at, model) {
|
|
583
635
|
for (const field of ['input', 'cacheRead', 'contextWindow']) {
|
|
584
636
|
if (!Number.isFinite(model[field]) || model[field] < 0)
|
package/lib/cost.mjs
CHANGED
|
@@ -82,7 +82,10 @@ export function coldWriteUsd(config, alias, tokens) {
|
|
|
82
82
|
);
|
|
83
83
|
}
|
|
84
84
|
|
|
85
|
+
// Routes that share a cache key (one model at two efforts, where effort keeps the cache) write the same new tokens
|
|
86
|
+
// to the same cache: switching between them costs no write. Bounding them apart would charge the new tokens as a tax.
|
|
85
87
|
export function switchingTaxUsd(config, candidate, incumbent, facts, now) {
|
|
88
|
+
if (routeCacheKey(config, candidate, facts.effort) === routeCacheKey(config, incumbent, facts.effort)) return 0;
|
|
86
89
|
const tokens = nextContextTokens(facts);
|
|
87
90
|
return (
|
|
88
91
|
inputBounds(config, candidate, tokens, facts, now).max - inputBounds(config, incumbent, tokens, facts, now).min
|
package/lib/display.mjs
CHANGED
|
@@ -9,6 +9,7 @@ import {
|
|
|
9
9
|
sameRoute,
|
|
10
10
|
} from './config.mjs';
|
|
11
11
|
import { ratesAt } from './cost.mjs';
|
|
12
|
+
import { applyMode, modeLabel } from './modes.mjs';
|
|
12
13
|
import { PROBE_RESULTS } from './probe-results.mjs';
|
|
13
14
|
import { cellForModel } from './route.mjs';
|
|
14
15
|
import { emptyTotals, readout } from './savings.mjs';
|
|
@@ -21,6 +22,14 @@ const MODEL_COLOR = { haiku: '#c3e88d', sonnet: '#f78c6c', opus: '#c792ea', fabl
|
|
|
21
22
|
export const modelColor = (id) =>
|
|
22
23
|
Object.entries(MODEL_COLOR).find(([family]) => String(id ?? '').includes(family))?.[1] ?? null;
|
|
23
24
|
|
|
25
|
+
// The config as the view's routing mode routes it: the route texts name what runs, not the configured route. A view
|
|
26
|
+
// from before 1.15 has no mode and reads as balanced.
|
|
27
|
+
export const DEFAULT_ROUTING_MODE = { mode: 'balanced', source: 'default' };
|
|
28
|
+
export const routingModeOf = (view) => view.routingMode ?? DEFAULT_ROUTING_MODE;
|
|
29
|
+
export const shownConfig = (config, view) => applyMode(config, routingModeOf(view));
|
|
30
|
+
// `cost (session)`; the status band and the Now tab show it while routing is on.
|
|
31
|
+
export const routingModeText = (view) => modeLabel(routingModeOf(view));
|
|
32
|
+
|
|
24
33
|
// Why routing starts off: the session's model is no tier's model. Set at session start, read by the band.
|
|
25
34
|
export const NOT_A_TIER_REASON = 'not a routing tier';
|
|
26
35
|
|
|
@@ -191,7 +200,8 @@ export function activityReading(view) {
|
|
|
191
200
|
}
|
|
192
201
|
|
|
193
202
|
// The route the turn's cell resolves to, against the tier's base route. Null outside `on`, or before a turn has a tier.
|
|
194
|
-
function activityRouteText(
|
|
203
|
+
function activityRouteText(configured, view) {
|
|
204
|
+
const config = shownConfig(configured, view);
|
|
195
205
|
if (config.activityRouting !== 'on' || !view.tier) return null;
|
|
196
206
|
const cell = `${view.tier}${view.activity ? ` + ${view.activity}` : ''}`;
|
|
197
207
|
const route = resolveRoute(config, view.tier, view.activity ?? null);
|
|
@@ -207,7 +217,8 @@ const STAYED = ['ready', 'same-tier', 'no-advice', 'uncertain', 'downgrade-held'
|
|
|
207
217
|
// The Now tab's Why. In `on`, an activity move, or a stay on an override cell, says the cell plainly: "coding at low
|
|
208
218
|
// runs on Sonnet 5.5 · high", or for a move to no activity "low runs on its base route, Haiku 5.5 · high".
|
|
209
219
|
// Every other decision keeps its reason: a refusal, a hold or a tier move says more than the cell.
|
|
210
|
-
export function whyText(
|
|
220
|
+
export function whyText(configured, view) {
|
|
221
|
+
const config = shownConfig(configured, view);
|
|
211
222
|
const reason = REASONS[view.reason] ?? view.reason ?? 'ready';
|
|
212
223
|
if (config.activityRouting !== 'on' || !view.tier) return reason;
|
|
213
224
|
const activity = view.activity ?? null;
|
|
@@ -215,6 +226,10 @@ export function whyText(config, view) {
|
|
|
215
226
|
const override = activity !== null && !sameRoute(route, resolveRoute(config, view.tier));
|
|
216
227
|
const moved = view.reason === 'activity-up' || view.reason === 'activity-down';
|
|
217
228
|
if (!moved && !(override && STAYED.includes(view.reason ?? 'ready'))) return reason;
|
|
229
|
+
// A held move keeps the route in use, which a routing mode may have moved off this cell's route: say only why.
|
|
230
|
+
const runs =
|
|
231
|
+
routeSpec(config, route).id === view.selectedModel && (route.effort === null || route.effort === view.effort);
|
|
232
|
+
if (!moved && view.selectedModel && !runs) return reason;
|
|
218
233
|
return activity
|
|
219
234
|
? `${activityVerb(activity)} at ${view.tier} runs on ${routeName(config, route)}`
|
|
220
235
|
: `${view.tier} runs on its base route, ${routeName(config, route)}`;
|
package/lib/modes.mjs
ADDED
|
@@ -0,0 +1,98 @@
|
|
|
1
|
+
// Routing modes (docs/plans/2026-10-21-routing-modes.md): one setting that trades cost against answer quality. The
|
|
2
|
+
// classifier and the configured routes stay as they are; the mode moves each tier's route by one fixed step. Pure.
|
|
3
|
+
import { ACTIVITIES, DEFAULTS, EFFORTS, ROUTING_MODES, rank, resolveRoute, sameRoute, TIERS } from './config.mjs';
|
|
4
|
+
import { clampEffort } from './cost.mjs';
|
|
5
|
+
|
|
6
|
+
// `wanted` on a model that lists `supported`: itself, else the next higher listed, else the highest lower one.
|
|
7
|
+
export function projectEffort(supported, wanted) {
|
|
8
|
+
if (supported.includes(wanted)) return wanted;
|
|
9
|
+
const at = EFFORTS.indexOf(wanted);
|
|
10
|
+
return (
|
|
11
|
+
EFFORTS.slice(at + 1).find((e) => supported.includes(e)) ??
|
|
12
|
+
EFFORTS.slice(0, at)
|
|
13
|
+
.reverse()
|
|
14
|
+
.find((e) => supported.includes(e)) ??
|
|
15
|
+
null
|
|
16
|
+
);
|
|
17
|
+
}
|
|
18
|
+
|
|
19
|
+
// The route's effort one level up (`step` 1) or down (-1), on what the model lists; null when it cannot move that
|
|
20
|
+
// way: a null effort (the session's), a model without efforts, or no listed level in that direction. The model's
|
|
21
|
+
// lowest listed level is the floor, so a route never loses its effort.
|
|
22
|
+
function steppedEffort(config, route, step) {
|
|
23
|
+
const supported = config.models[route.model].efforts;
|
|
24
|
+
const from = clampEffort(route.effort, supported);
|
|
25
|
+
if (!from) return null;
|
|
26
|
+
const wanted = EFFORTS[EFFORTS.indexOf(from) + step];
|
|
27
|
+
const effort = wanted ? projectEffort(supported, wanted) : null;
|
|
28
|
+
return effort && Math.sign(EFFORTS.indexOf(effort) - EFFORTS.indexOf(from)) === step ? effort : null;
|
|
29
|
+
}
|
|
30
|
+
|
|
31
|
+
// The route `mode` runs for tier and activity, always from the configured routes. `cost` takes the tier below (never
|
|
32
|
+
// below `low`) when it runs a model with a lower input price, else one effort level less; `quality` one effort level
|
|
33
|
+
// more, else the tier above. One lever per decision: cost pays mostly for input and cache tokens, which effort does
|
|
34
|
+
// not lower, and quality keeps the model and its cache. `micro` and `balanced` keep the configured route.
|
|
35
|
+
export function modeRoute(config, mode, tier, activity = null) {
|
|
36
|
+
const routeAt = (t) => resolveRoute(config, t, activity);
|
|
37
|
+
const route = routeAt(tier);
|
|
38
|
+
if (mode === 'balanced' || tier === 'micro') return route;
|
|
39
|
+
if (mode === 'cost') {
|
|
40
|
+
const below = routeAt(TIERS[Math.max(rank('low'), rank(tier) - 1)]);
|
|
41
|
+
if (below.model !== route.model && config.models[below.model].input < config.models[route.model].input)
|
|
42
|
+
return below;
|
|
43
|
+
const effort = steppedEffort(config, route, -1);
|
|
44
|
+
return effort ? { model: route.model, effort } : route;
|
|
45
|
+
}
|
|
46
|
+
const effort = steppedEffort(config, route, 1);
|
|
47
|
+
return effort ? { model: route.model, effort } : routeAt(TIERS[Math.min(TIERS.length - 1, rank(tier) + 1)]);
|
|
48
|
+
}
|
|
49
|
+
|
|
50
|
+
// The config a turn routes on in `routingMode` ({ mode, source }): every tier's and activity's route as modeRoute
|
|
51
|
+
// gives it, and the mode's policy fields over `policy`. `config` must be the configured one (router.config), never a
|
|
52
|
+
// result of this function: the transform starts from the configured routes, so repeated turns never step twice.
|
|
53
|
+
// `balanced` keeps the routes object as configured.
|
|
54
|
+
export function applyMode(config, routingMode) {
|
|
55
|
+
const { mode } = routingMode;
|
|
56
|
+
const policy = { ...config.policy, ...config.modes[mode]?.policy };
|
|
57
|
+
if (mode === 'balanced') return { ...config, policy, routingMode };
|
|
58
|
+
const routes = Object.fromEntries(TIERS.map((tier) => [tier, modeRoute(config, mode, tier)]));
|
|
59
|
+
const activities = {};
|
|
60
|
+
for (const activity of ACTIVITIES)
|
|
61
|
+
for (const tier of TIERS) {
|
|
62
|
+
const route = modeRoute(config, mode, tier, activity);
|
|
63
|
+
if (!sameRoute(route, routes[tier])) activities[activity] = { ...activities[activity], [tier]: route };
|
|
64
|
+
}
|
|
65
|
+
return { ...config, routes, activities, policy, routingMode };
|
|
66
|
+
}
|
|
67
|
+
|
|
68
|
+
// The active mode and its source: a session override, then the project file, then the profile router.json.
|
|
69
|
+
export function resolveRoutingMode({ session = null, project = null, profile = DEFAULTS.mode } = {}) {
|
|
70
|
+
if (ROUTING_MODES.includes(session)) return { mode: session, source: 'session' };
|
|
71
|
+
if (ROUTING_MODES.includes(project)) return { mode: project, source: 'project' };
|
|
72
|
+
if (profile !== DEFAULTS.mode) return { mode: profile, source: 'profile' };
|
|
73
|
+
return { mode: DEFAULTS.mode, source: 'default' };
|
|
74
|
+
}
|
|
75
|
+
|
|
76
|
+
// `cost (session)`.
|
|
77
|
+
export const modeLabel = ({ mode, source }) => `${mode} (${source})`;
|
|
78
|
+
|
|
79
|
+
// A project's `.claude/router.json`, which may hold only `mode`: the repo chooses among routes the user configured,
|
|
80
|
+
// never the routes, models or classifier. Returns { mode, error }: a file that does not read is ignored, with a reason
|
|
81
|
+
// that names the key, never its value. No file: { mode: null, error: null }.
|
|
82
|
+
export function readProjectMode(text) {
|
|
83
|
+
if (text === null) return { mode: null, error: null };
|
|
84
|
+
let file;
|
|
85
|
+
try {
|
|
86
|
+
file = JSON.parse(text);
|
|
87
|
+
} catch {
|
|
88
|
+
return { mode: null, error: 'project .claude/router.json is not valid JSON' };
|
|
89
|
+
}
|
|
90
|
+
if (typeof file !== 'object' || file === null || Array.isArray(file))
|
|
91
|
+
return { mode: null, error: 'project .claude/router.json must be an object' };
|
|
92
|
+
const other = Object.keys(file).find((key) => key !== 'mode');
|
|
93
|
+
if (other !== undefined) return { mode: null, error: `project .claude/router.json may only set mode, not ${other}` };
|
|
94
|
+
if (!Object.hasOwn(file, 'mode')) return { mode: null, error: null };
|
|
95
|
+
if (!ROUTING_MODES.includes(file.mode))
|
|
96
|
+
return { mode: null, error: `project .claude/router.json mode must be one of ${ROUTING_MODES.join(', ')}` };
|
|
97
|
+
return { mode: file.mode, error: null };
|
|
98
|
+
}
|
package/lib/panel.mjs
CHANGED
|
@@ -7,6 +7,7 @@ import {
|
|
|
7
7
|
DEFAULTS,
|
|
8
8
|
effectiveActivities,
|
|
9
9
|
effectiveRoutes,
|
|
10
|
+
ROUTING_MODES,
|
|
10
11
|
resolveRoute,
|
|
11
12
|
sameCell,
|
|
12
13
|
sameRoute,
|
|
@@ -32,7 +33,10 @@ import {
|
|
|
32
33
|
probeOf,
|
|
33
34
|
routeLabel,
|
|
34
35
|
routeName,
|
|
36
|
+
routingModeOf,
|
|
37
|
+
routingModeText,
|
|
35
38
|
savingsColor,
|
|
39
|
+
shownConfig,
|
|
36
40
|
signedUsd,
|
|
37
41
|
sparkline,
|
|
38
42
|
TIER_COLOR,
|
|
@@ -279,10 +283,11 @@ function nowTab(ui, config, view, usage, actions, _modelOptions, columns, now) {
|
|
|
279
283
|
const served = view.actualModel && current && !isSameModel(current, view.actualModel);
|
|
280
284
|
const mode = config.activityRouting;
|
|
281
285
|
const reading = mode === 'off' ? null : activityReading(view);
|
|
282
|
-
// In `on` an override names the tier's own model.
|
|
283
|
-
const
|
|
286
|
+
// In `on` an override names the tier's own model, as the routing mode runs it.
|
|
287
|
+
const shown = shownConfig(config, view);
|
|
288
|
+
const base = view.tier ? resolveRoute(shown, view.tier) : null;
|
|
284
289
|
const override =
|
|
285
|
-
mode === 'on' && view.activity && base && !sameRoute(resolveRoute(
|
|
290
|
+
mode === 'on' && view.activity && base && !sameRoute(resolveRoute(shown, view.tier, view.activity), base);
|
|
286
291
|
const support = auto ? supportText(label, view.estimate) : null;
|
|
287
292
|
const out = [
|
|
288
293
|
ui.line(
|
|
@@ -304,6 +309,12 @@ function nowTab(ui, config, view, usage, actions, _modelOptions, columns, now) {
|
|
|
304
309
|
: null,
|
|
305
310
|
ui.line('Why ', whyText(config, view)),
|
|
306
311
|
support ? ui.dim(` ${support}`) : null,
|
|
312
|
+
ui.line(
|
|
313
|
+
'Mode ',
|
|
314
|
+
routingModeText(view),
|
|
315
|
+
routingModeOf(view).source === 'session' ? ui.dim(' /router mode default clears it') : null,
|
|
316
|
+
),
|
|
317
|
+
view.projectError ? ui.text(` Ignored: ${view.projectError}`, { color: 'yellow' }) : null,
|
|
307
318
|
served
|
|
308
319
|
? ui.line(ui.text('Served ', { color: 'yellow' }), `${modelName(view.actualModel)} · native fallback`)
|
|
309
320
|
: null,
|
|
@@ -926,6 +937,13 @@ function choice(ui, key, value, format, pick) {
|
|
|
926
937
|
|
|
927
938
|
// The Policy tab: each control inside the sentence it completes, its default named when the value differs. One Save
|
|
928
939
|
// writes it with the Routes draft.
|
|
940
|
+
// What the profile's routing mode does, under its control on the Policy tab.
|
|
941
|
+
const MODE_HINT = {
|
|
942
|
+
cost: 'a cheaper model or one effort level less where a turn allows',
|
|
943
|
+
balanced: 'each tier runs its route as configured',
|
|
944
|
+
quality: 'one effort level more, or the tier above, where a turn allows',
|
|
945
|
+
};
|
|
946
|
+
|
|
929
947
|
function policyTab(ui, config, view, _usage, actions) {
|
|
930
948
|
const changes = routingChanges(config, view);
|
|
931
949
|
const { draft, tuning, policy } = changes;
|
|
@@ -939,9 +957,26 @@ function policyTab(ui, config, view, _usage, actions) {
|
|
|
939
957
|
];
|
|
940
958
|
const { upgradeBase, upgradeSlope } = config.policy;
|
|
941
959
|
const credits = Object.values(config.models).some((model) => model.billing === 'credits');
|
|
960
|
+
const active = routingModeOf(view);
|
|
942
961
|
return [
|
|
943
962
|
ui.line(ui.head('POLICY'), ui.dim(' · how readily the router changes models · edit, then Save')),
|
|
944
963
|
ui.text(' '),
|
|
964
|
+
ui.line(
|
|
965
|
+
ui.cell(13, ui.text('Mode', { bold: true })),
|
|
966
|
+
ui.Select
|
|
967
|
+
? ui.Select({
|
|
968
|
+
key: 'routing-mode',
|
|
969
|
+
value: config.mode,
|
|
970
|
+
options: ROUTING_MODES.map((mode) => ({ value: mode, label: mode })),
|
|
971
|
+
onSelect: (mode) => actions.routingMode(mode),
|
|
972
|
+
})
|
|
973
|
+
: config.mode,
|
|
974
|
+
ui.dim(' saved at once'),
|
|
975
|
+
),
|
|
976
|
+
ui.dim(`${pad}${MODE_HINT[config.mode]}`),
|
|
977
|
+
active.source === 'session' || active.source === 'project'
|
|
978
|
+
? ui.text(`${pad}this session runs ${routingModeText(view)}`, { color: 'yellow' })
|
|
979
|
+
: null,
|
|
945
980
|
ui.line(
|
|
946
981
|
ui.cell(13, ui.text('Start', { bold: true })),
|
|
947
982
|
'at ',
|
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
4
|
import { clip, extractFacts, verifiedSince } from './facts.mjs';
|
|
5
|
-
import { CONTEXT_FILL, decide, fitTier, initialState } from './policy.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: {},
|
|
@@ -146,6 +149,7 @@ export function chooseRoute(config, loop, input) {
|
|
|
146
149
|
state: applied.state,
|
|
147
150
|
lastRoute: kept ? loop.lastRoute : applied.tier,
|
|
148
151
|
lastActivity: kept ? activityOf(config, loop) : applied.activity,
|
|
152
|
+
route: kept ? (loop.route ?? null) : applied.route,
|
|
149
153
|
turnId: facts.turnKey,
|
|
150
154
|
decision: applied,
|
|
151
155
|
suspended: false,
|
|
@@ -160,11 +164,32 @@ const activityOf = (config, loop) => (config.activityRouting === 'on' ? (loop.la
|
|
|
160
164
|
// One decision (plan §5.2) for the cell `{ tier, activity }` it lands on. Outside `on` the activity is null throughout.
|
|
161
165
|
function routeTurn(config, loop, { facts, advice, pin, nativeModel, contextKnown, availableModels, now }) {
|
|
162
166
|
const projected = economicConfig(config, loop);
|
|
163
|
-
const routeOf = (cell) => resolveRoute(config, cell.tier, cell.activity);
|
|
164
|
-
const specOf = (cell) => routeSpec(config, routeOf(cell));
|
|
165
167
|
const last = { tier: loop.lastRoute, activity: activityOf(config, loop) };
|
|
166
168
|
const tier0 = TIERS.includes(facts.lastRoute) ? facts.lastRoute : config.baselineTier;
|
|
167
|
-
|
|
169
|
+
// The incumbent runs the route in use, not the one config gives its cell now. It is rebuilt from config for a loop
|
|
170
|
+
// from before 1.15, a route whose model left the config or can no longer run, and a route kept for an activity that
|
|
171
|
+
// no longer applies (activity routing turned off).
|
|
172
|
+
const usable = (route) => {
|
|
173
|
+
const model = Object.hasOwn(config.models, route.model) ? config.models[route.model] : null;
|
|
174
|
+
return Boolean(
|
|
175
|
+
model && isModelAllowed(model.id, availableModels, nativeModel) && !loop.ineligible.includes(model.id),
|
|
176
|
+
);
|
|
177
|
+
};
|
|
178
|
+
const inUse = loop.route && usable(loop.route) && (loop.lastActivity ?? null) === last.activity ? loop.route : null;
|
|
179
|
+
const incumbent = {
|
|
180
|
+
tier: tier0,
|
|
181
|
+
activity: last.activity,
|
|
182
|
+
route: inUse ?? resolveRoute(config, tier0, last.activity),
|
|
183
|
+
};
|
|
184
|
+
// A decision that stays on the incumbent's cell keeps running its route; only a taken lateral move or a pin runs the
|
|
185
|
+
// cell's route from config. So a mode change reaches the request only through the gates.
|
|
186
|
+
const stays = (cell) =>
|
|
187
|
+
cell.tier === incumbent.tier &&
|
|
188
|
+
(cell.activity ?? null) === incumbent.activity &&
|
|
189
|
+
cell.lateral !== 'taken' &&
|
|
190
|
+
cell.reason !== 'pinned';
|
|
191
|
+
const routeOf = (cell) => (stays(cell) ? incumbent.route : resolveRoute(config, cell.tier, cell.activity));
|
|
192
|
+
const specOf = (cell) => routeSpec(config, routeOf(cell));
|
|
168
193
|
const activity =
|
|
169
194
|
pin || config.activityRouting !== 'on' ? null : chooseActivity(config, advice, incumbent, facts.effort, facts);
|
|
170
195
|
let result =
|
|
@@ -178,9 +203,12 @@ function routeTurn(config, loop, { facts, advice, pin, nativeModel, contextKnown
|
|
|
178
203
|
state: { ...loop.state, turn: loop.state.turn + 1 },
|
|
179
204
|
}
|
|
180
205
|
: 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.
|
|
206
|
+
// Without a reliable reading of the context, a route with a smaller window than the last one might overflow. Before
|
|
207
|
+
// the first decision the session's own model ran, not the mode's route for its cell.
|
|
208
|
+
const lastSpec =
|
|
209
|
+
(!loop.decision && Object.values(config.models).find((m) => isSameModel(m.id, nativeModel))) || specOf(last);
|
|
182
210
|
const shrinksUnmeasured = (cell) =>
|
|
183
|
-
(!contextKnown || !loop.historyMeasured) && specOf(cell).contextWindow <
|
|
211
|
+
(!contextKnown || !loop.historyMeasured) && specOf(cell).contextWindow < lastSpec.contextWindow;
|
|
184
212
|
const fits = (cell) => {
|
|
185
213
|
const model = specOf(cell);
|
|
186
214
|
return (
|
|
@@ -191,7 +219,8 @@ function routeTurn(config, loop, { facts, advice, pin, nativeModel, contextKnown
|
|
|
191
219
|
);
|
|
192
220
|
};
|
|
193
221
|
if (contextKnown) {
|
|
194
|
-
const
|
|
222
|
+
const cell = result;
|
|
223
|
+
const routeFor = (tier) => (tier === cell.tier ? routeOf(cell) : resolveRoute(config, tier, cell.activity));
|
|
195
224
|
const fitted = fitTier(config, result.tier, costs.nextContextTokens(facts), routeFor);
|
|
196
225
|
if (fitted !== result.tier) result = { ...result, tier: fitted, reason: 'context-fit', lateral: null };
|
|
197
226
|
}
|
|
@@ -212,7 +241,7 @@ function routeTurn(config, loop, { facts, advice, pin, nativeModel, contextKnown
|
|
|
212
241
|
let comparison = null;
|
|
213
242
|
const candidate = pin ?? advice?.choice;
|
|
214
243
|
if (contextKnown && loop.lastRequest && TIERS.includes(candidate) && candidate !== loop.lastRoute) {
|
|
215
|
-
const [to, from] = [resolveRoute(config, candidate, activity),
|
|
244
|
+
const [to, from] = [resolveRoute(config, candidate, activity), incumbent.route];
|
|
216
245
|
const forecast = costs.switchEconomics(projected, to, from, facts, now);
|
|
217
246
|
comparison = {
|
|
218
247
|
candidate,
|
|
@@ -222,7 +251,7 @@ function routeTurn(config, loop, { facts, advice, pin, nativeModel, contextKnown
|
|
|
222
251
|
outputTokens: loop.lastRequest.outputTokens,
|
|
223
252
|
};
|
|
224
253
|
}
|
|
225
|
-
return { ...result, model, effort, comparison, pinned: Boolean(pin), requestedPin: pin ?? null };
|
|
254
|
+
return { ...result, route, model, effort, comparison, pinned: Boolean(pin), requestedPin: pin ?? null };
|
|
226
255
|
}
|
|
227
256
|
|
|
228
257
|
// 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 +259,13 @@ function routeTurn(config, loop, { facts, advice, pin, nativeModel, contextKnown
|
|
|
230
259
|
// never switch: a label alone decides nothing.
|
|
231
260
|
function decideCell({ config, projected, facts, advice, state, now, incumbent, activity }) {
|
|
232
261
|
const routeFor = (tier) => resolveRoute(config, tier, activity);
|
|
233
|
-
//
|
|
234
|
-
// order against it
|
|
262
|
+
// Failures move to the lowest tier whose route is stronger than the one running, or another request that does not
|
|
263
|
+
// order against it: after a mode change the next tier's route can be the weaker one.
|
|
235
264
|
const escalates = (t) => {
|
|
236
265
|
const order = compareRoutes(config, routeFor(t), incumbent.route, facts.effort);
|
|
237
266
|
return order > 0 || (order === null && !sameRequest(config, routeFor(t), incumbent.route, facts.effort));
|
|
238
267
|
};
|
|
239
|
-
const escalateTo =
|
|
268
|
+
const escalateTo = (tier) => TIERS.slice(rank(tier) + 1).find(escalates) ?? null;
|
|
240
269
|
const step = decide({
|
|
241
270
|
config: projected,
|
|
242
271
|
facts,
|
|
@@ -253,15 +282,18 @@ function decideCell({ config, projected, facts, advice, state, now, incumbent, a
|
|
|
253
282
|
// context or availability override keeps the flag.
|
|
254
283
|
const escalated = step.state.escalatedSignature !== state.escalatedSignature;
|
|
255
284
|
const route = routeFor(step.tier);
|
|
256
|
-
|
|
285
|
+
// Without a classifier answer the running route stays, whatever the mode's route for the cell, during a hold too.
|
|
286
|
+
if (!advice || step.tier !== incumbent.tier || sameRequest(config, route, incumbent.route, facts.effort))
|
|
257
287
|
return { ...step, activity, lateral: null, escalated };
|
|
258
288
|
const lateral = lateralMove({
|
|
259
289
|
config: projected,
|
|
260
290
|
from: incumbent.route,
|
|
261
291
|
to: route,
|
|
262
|
-
// Returning to the base route needs no evidence
|
|
263
|
-
|
|
292
|
+
// Returning to the base route needs no evidence, nor does the incumbent's own cell whose configured route changed
|
|
293
|
+
// (a routing mode, a route edit): the label is not what moves.
|
|
294
|
+
mass: activity === null || activity === incumbent.activity ? 1 : (advice?.activity?.probabilities?.[activity] ?? 0),
|
|
264
295
|
hold: step.reason === 'hold',
|
|
296
|
+
sameTask: sameTaskOf(config, advice, facts),
|
|
265
297
|
facts,
|
|
266
298
|
now,
|
|
267
299
|
costs,
|
|
@@ -277,11 +309,17 @@ function decideCell({ config, projected, facts, advice, state, now, incumbent, a
|
|
|
277
309
|
};
|
|
278
310
|
}
|
|
279
311
|
|
|
312
|
+
// The route a decision runs: the one it recorded, or for a decision from before 1.15 its cell's route in config.
|
|
313
|
+
const runningRoute = (config, decision) =>
|
|
314
|
+
decision.route && Object.hasOwn(config.models, decision.route.model)
|
|
315
|
+
? decision.route
|
|
316
|
+
: resolveRoute(config, decision.tier, decision.activity ?? null);
|
|
317
|
+
|
|
280
318
|
// Whether some activity's route at the decision's tier is stronger than the one running: only then can the turn's own
|
|
281
319
|
// tool calls move it (observedMove), so a step on the strongest route skips reading the transcript.
|
|
282
320
|
export function canMoveUp(config, decision, effort) {
|
|
283
321
|
if (config.activityRouting !== 'on' || !decision?.tier || decision.pinned) return false;
|
|
284
|
-
const from =
|
|
322
|
+
const from = runningRoute(config, decision);
|
|
285
323
|
return ACTIVITIES.some((a) => compareRoutes(config, resolveRoute(config, decision.tier, a), from, effort) > 0);
|
|
286
324
|
}
|
|
287
325
|
|
|
@@ -294,7 +332,7 @@ export function canMoveUp(config, decision, effort) {
|
|
|
294
332
|
export function observedMove(config, loop, { observed, facts, contextKnown, now }) {
|
|
295
333
|
const decision = loop.decision;
|
|
296
334
|
if (!canMoveUp(config, decision, facts.effort) || !ACTIVITIES.includes(observed)) return loop;
|
|
297
|
-
const from =
|
|
335
|
+
const from = runningRoute(config, decision);
|
|
298
336
|
// The gates price the route that will run: the one the context fits, not the tier's first choice.
|
|
299
337
|
const routeFor = (tier) => resolveRoute(config, tier, observed);
|
|
300
338
|
const tier = fitTier(config, decision.tier, costs.nextContextTokens(facts), routeFor);
|
|
@@ -309,10 +347,13 @@ export function observedMove(config, loop, { observed, facts, contextKnown, now
|
|
|
309
347
|
return {
|
|
310
348
|
...loop,
|
|
311
349
|
lastActivity: observed,
|
|
350
|
+
// The route in use belongs to `lastRoute`: a move the context fitted to another tier leaves it to be rebuilt.
|
|
351
|
+
route: tier === loop.lastRoute ? to : null,
|
|
312
352
|
decision: {
|
|
313
353
|
...decision,
|
|
314
354
|
tier,
|
|
315
355
|
activity: observed,
|
|
356
|
+
route: to,
|
|
316
357
|
model: routeSpec(config, to).id,
|
|
317
358
|
effort: costs.routeEffort(config, to, facts.effort),
|
|
318
359
|
reason: lateral.reason,
|
|
@@ -325,21 +366,37 @@ export function observedMove(config, loop, { observed, facts, contextKnown, now
|
|
|
325
366
|
// calls (observedMove) can move it.
|
|
326
367
|
export function continueRoute(config, loop, { nativeModel, contextTokens, contextKnown, availableModels, effort }) {
|
|
327
368
|
if (!loop.decision) return loop;
|
|
369
|
+
// A fit to another tier serves this turn only: `loop.route` stays the route of `lastRoute`, as the tier does.
|
|
328
370
|
let decision = loop.decision;
|
|
329
371
|
if (contextKnown && decision.tier) {
|
|
372
|
+
// The route the turn runs, which a mode change or a held move can keep apart from config, stays while the context
|
|
373
|
+
// fits it; past that, the routes config gives each tier, its own tier's first.
|
|
374
|
+
const running = runningRoute(config, decision);
|
|
330
375
|
const routeOf = (tier) => resolveRoute(config, tier, decision.activity ?? null);
|
|
331
|
-
const
|
|
332
|
-
|
|
376
|
+
const fits = contextTokens <= routeSpec(config, running).contextWindow * CONTEXT_FILL;
|
|
377
|
+
const fitted = fits ? decision.tier : fitTier(config, decision.tier, contextTokens, routeOf);
|
|
378
|
+
if (!fits && !sameRoute(routeOf(fitted), running)) {
|
|
379
|
+
const route = routeOf(fitted);
|
|
333
380
|
decision = {
|
|
334
381
|
...decision,
|
|
335
382
|
tier: fitted,
|
|
336
|
-
|
|
337
|
-
|
|
383
|
+
route,
|
|
384
|
+
model: routeSpec(config, route).id,
|
|
385
|
+
effort: costs.routeEffort(config, route, effort),
|
|
338
386
|
reason: 'context-fit',
|
|
339
387
|
};
|
|
388
|
+
}
|
|
340
389
|
}
|
|
341
390
|
if (!isModelAllowed(decision.model, availableModels, nativeModel) || loop.ineligible.includes(decision.model)) {
|
|
342
|
-
decision = {
|
|
391
|
+
decision = {
|
|
392
|
+
...decision,
|
|
393
|
+
tier: null,
|
|
394
|
+
activity: null,
|
|
395
|
+
route: null,
|
|
396
|
+
model: nativeModel,
|
|
397
|
+
effort,
|
|
398
|
+
reason: 'model-unavailable',
|
|
399
|
+
};
|
|
343
400
|
}
|
|
344
401
|
return { ...loop, decision };
|
|
345
402
|
}
|