@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/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 [segment(0, meter(null, true), part(' Routing on · ready', { dimColor: true })), pin].filter(Boolean);
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
- const p = config.policy;
540
- for (const field of ['upgradeBase', 'jumpConfidence', 'downgradeMass', 'continuationMass', 'activityMass']) {
541
- if (!(isNumber(p[field], 0) && p[field] <= 1)) throw new Error(`policy.${field} must be between 0 and 1`);
542
- }
543
- for (const field of ['upgradeVotes', 'downgradeVotes', 'downgradeHorizonTurns', 'escalationHoldTurns']) {
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(config, view) {
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(config, view) {
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 base = view.tier ? resolveRoute(config, view.tier) : null;
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(config, view.tier, view.activity), base);
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
- const incumbent = { tier: tier0, activity: last.activity, route: resolveRoute(config, tier0, last.activity) };
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 < specOf(last).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 routeFor = (tier) => resolveRoute(config, tier, result.activity);
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), routeOf(last)];
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
- // With an activity, failures move to the lowest tier whose route is stronger, or another request that does not
234
- // order against it; with none, one tier up as before.
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 = activity === null ? undefined : (tier) => TIERS.slice(rank(tier) + 1).find(escalates) ?? null;
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
- if (step.tier !== incumbent.tier || sameRequest(config, route, incumbent.route, facts.effort))
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
- mass: activity === null ? 1 : (advice?.activity?.probabilities?.[activity] ?? 0),
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 = resolveRoute(config, decision.tier, decision.activity ?? null);
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 = resolveRoute(config, decision.tier, decision.activity ?? null);
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 fitted = fitTier(config, decision.tier, contextTokens, routeOf);
332
- if (fitted !== decision.tier)
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
- model: routeSpec(config, routeOf(fitted)).id,
337
- effort: costs.routeEffort(config, routeOf(fitted), effort),
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 = { ...decision, tier: null, activity: null, model: nativeModel, effort, reason: 'model-unavailable' };
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
  }