@alexeiled/claude-router 1.13.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.
@@ -31,12 +31,14 @@ import {
31
31
  effectiveRoutes,
32
32
  loadConfig,
33
33
  MIGRATION_HINT,
34
+ ROUTING_MODES,
34
35
  supportedVersion,
35
36
  TIERS,
36
37
  tuningOf,
37
38
  withActivities,
38
39
  withClassifier,
39
40
  withClassifierTimeout,
41
+ withMode,
40
42
  withRoutes,
41
43
  withTuning,
42
44
  } from '../lib/config.mjs';
@@ -54,6 +56,7 @@ import {
54
56
  unavailableReason,
55
57
  } from '../lib/display.mjs';
56
58
  import { clip, observedActivity, promptIndex } from '../lib/facts.mjs';
59
+ import { applyMode, modeLabel, readProjectMode, resolveRoutingMode } from '../lib/modes.mjs';
57
60
  import { renderPanel, routeDraftOf, routingChanges } from '../lib/panel.mjs';
58
61
  import {
59
62
  canMoveUp,
@@ -93,6 +96,7 @@ import {
93
96
  emptySubagentStore,
94
97
  flushedAgent,
95
98
  mergeSubagentStores,
99
+ moveOf,
96
100
  passReason,
97
101
  RESPAWN_WINDOW_MS,
98
102
  readSubagentStore,
@@ -134,6 +138,8 @@ const PANE = 'jev-router';
134
138
  const PANE_TITLE = 'Router';
135
139
  const BAND_DETAIL = 'band:detail';
136
140
  const MODE_PREFIX = 'mode:';
141
+ // The session's routing mode override (lib/modes.mjs), apart from its auto|manual MODE_PREFIX.
142
+ const ROUTING_MODE_PREFIX = 'routing-mode:';
137
143
  const isSet = (value) => /^(1|true|yes|on)$/i.test(String(value ?? '').trim());
138
144
 
139
145
  // The counts kept across sessions: each session writes only its own record of a kind, `prefix` and its session id,
@@ -172,6 +178,7 @@ const LEDGERS = {
172
178
  subagents: {
173
179
  prefix: SUBAGENT_PREFIX,
174
180
  field: 'subagentStore',
181
+ ownField: 'subagentSession',
175
182
  read: readSubagentStore,
176
183
  afterReset: subagentsAfterReset,
177
184
  merge: mergeSubagentStores,
@@ -206,6 +213,10 @@ function createRouter(options) {
206
213
  turnControllers: new Map(),
207
214
  view: null,
208
215
  modes: new Map(),
216
+ // Each session's routing mode override (null: none), as read from or written to the store.
217
+ routingModes: new Map(),
218
+ // The project's `.claude/router.json` mode, read at session.start: { mode, error }.
219
+ project: { mode: null, error: null },
209
220
  // Each routed turn's activity record until turn.complete adds it to the stats, and the session's open run of
210
221
  // one activity, flushed to the store when it ends.
211
222
  turnActivities: new Map(),
@@ -231,8 +242,8 @@ function createRouter(options) {
231
242
  // first request goes out on that route, unless it was pressed again meanwhile.
232
243
  pinPresses: 0,
233
244
  turnPins: new Map(),
234
- // Each spawned agent's record by agentId (spawnRecord), and when each parent loop last finished an agent of a type,
235
- // for respawns.
245
+ // Each spawned agent's record by agentId (spawnRecord, `running` between its steps and its turn's end), and when
246
+ // each parent loop last finished an agent of a type, for respawns.
236
247
  agents: new Map(),
237
248
  finished: new Map(),
238
249
  // Each agent type's definition frontmatter by provider and type, read once per session (agentDefinition).
@@ -295,6 +306,84 @@ async function rememberMode($, mode) {
295
306
  }
296
307
  }
297
308
 
309
+ // The routing mode a turn starts with and where it comes from. A store that cannot be read counts as no override.
310
+ async function routingModeOf($, router) {
311
+ const sessionId = await $.session.id();
312
+ if (!router.routingModes.has(sessionId)) {
313
+ const saved = await $.store.get(`${ROUTING_MODE_PREFIX}${sessionId}`).catch(() => null);
314
+ router.routingModes.set(sessionId, ROUTING_MODES.includes(saved) ? saved : null);
315
+ }
316
+ return resolveRoutingMode({
317
+ session: router.routingModes.get(sessionId),
318
+ project: router.project.mode,
319
+ profile: router.config.mode,
320
+ });
321
+ }
322
+
323
+ // The prompt footer's word for the router: paused or broken routing, or a routing mode other than balanced, which
324
+ // changes what every routed turn costs. Null for none.
325
+ async function footerLabel($, router, view) {
326
+ if (view.phase === 'unavailable') return 'routing unavailable';
327
+ if ((await modeOf($, router, view.mode)) === 'manual') return 'routing off';
328
+ const routingMode = view.routingMode;
329
+ return routingMode && routingMode.mode !== 'balanced' ? `${routingMode.mode} mode (${routingMode.source})` : null;
330
+ }
331
+
332
+ const sameMode = (a, b) => a?.mode === b?.mode && a?.source === b?.source;
333
+
334
+ // A turn's configs when turn.start did not record them, as after a reload of the Mod mid-turn.
335
+ async function turnConfigOf($, router) {
336
+ return { config: applyMode(router.config, await routingModeOf($, router)), configured: router.config };
337
+ }
338
+
339
+ // The turn routes on the configured routes as its routing mode moves them, fixed now so a change mid-turn waits for
340
+ // the next turn; a pin uses `configured` (decideTurn).
341
+ async function fixTurnConfig($, router, turnId) {
342
+ const turn = await turnConfigOf($, router);
343
+ router.turnConfigs.set(turnId, turn);
344
+ const { routingMode } = turn.config;
345
+ if (router.view && !sameMode(router.view.routingMode, routingMode)) await updateView($, router, { routingMode });
346
+ }
347
+
348
+ // `/router mode <mode|default>`: the session's override, kept for a resume of this session only. It changes the
349
+ // preferred route from the next turn; the route in use moves through the gates. No turn is aborted.
350
+ async function setRoutingMode($, router, value) {
351
+ const sessionId = await $.session.id();
352
+ const key = `${ROUTING_MODE_PREFIX}${sessionId}`;
353
+ let saved = true;
354
+ try {
355
+ if (value === 'default') await $.store.delete(key);
356
+ else await $.store.set(key, value);
357
+ } catch {
358
+ saved = false;
359
+ }
360
+ router.routingModes.set(sessionId, value === 'default' ? null : value);
361
+ const routingMode = await routingModeOf($, router);
362
+ await updateView($, router, { routingMode });
363
+ const unsaved =
364
+ value === 'default'
365
+ ? 'A resume of this session may bring the cleared mode back: the store could not be written.'
366
+ : 'A resume of this session will not keep it: the store could not be written.';
367
+ return [`Routing mode: ${modeLabel(routingMode)}, from the next turn.`, ...(saved ? [] : [unsaved])].join(' ');
368
+ }
369
+
370
+ // A project's `.claude/router.json`, which may set only `mode`. Never a profile's own file: not the active profile's,
371
+ // and not in the home directory, whose `.claude` is the default profile. A repo controls this file, so a symlink, which
372
+ // could reach a file outside it, is refused as the profile's is. A file that does not read is ignored, with the reason
373
+ // for the pane.
374
+ async function readProject($, profilePath) {
375
+ try {
376
+ const cwd = await $.session.cwd();
377
+ const path = `${cwd}/.claude/router.json`;
378
+ const home = await $.env.get('HOME');
379
+ if (path === profilePath || cwd === home || !(await $.fs.exists(path))) return { mode: null, error: null };
380
+ if ((await $.fs.stat(path)).isLink) return { mode: null, error: 'project .claude/router.json is a symlink' };
381
+ return readProjectMode(await $.fs.read(path));
382
+ } catch {
383
+ return { mode: null, error: 'project .claude/router.json could not be read' };
384
+ }
385
+ }
386
+
298
387
  async function updateView($, router, patch) {
299
388
  const value = router.view ?? (await readView($, router));
300
389
  router.view = { ...value, ...patch };
@@ -445,7 +534,8 @@ async function setPin($, router, tier) {
445
534
  return `${tier} pinned for the next turn and its tool continuations.`;
446
535
  }
447
536
 
448
- // `/router [auto|off|pin <tier>|activities <mode>]`; with no action, the pane, or the status text without a surface.
537
+ // `/router [auto|off|pin <tier>|activities <mode>|mode <mode>]`; with no action, the pane, or the status text without
538
+ // a surface.
449
539
  async function routerCommand($, router, args) {
450
540
  const [action, value] = args.trim().split(/\s+/);
451
541
  if (action === 'auto' || action === 'off') {
@@ -456,6 +546,12 @@ async function routerCommand($, router, args) {
456
546
  }
457
547
  if (action === 'pin')
458
548
  return { text: TIERS.includes(value) ? await setPin($, router, value) : `Choose ${TIERS.join(', ')}.` };
549
+ if (action === 'mode')
550
+ return {
551
+ text: [...ROUTING_MODES, 'default'].includes(value)
552
+ ? await setRoutingMode($, router, value)
553
+ : `Choose mode ${[...ROUTING_MODES, 'default'].join(', ')}.`,
554
+ };
459
555
  if (action === 'activities')
460
556
  return {
461
557
  text: ACTIVITY_MODES.includes(value)
@@ -576,6 +672,8 @@ function detailText(config, view) {
576
672
  const missing = missingCredentials(config, view, config.classifier);
577
673
  return [
578
674
  `Router — routing ${view.mode === 'auto' ? 'on' : 'off'}`,
675
+ ...(view.routingMode ? [`Mode: ${modeLabel(view.routingMode)}`] : []),
676
+ ...(view.projectError ? [`Ignored: ${view.projectError}`] : []),
579
677
  `Native model: ${view.nativeModel}`,
580
678
  `Selected: ${view.selectedModel ?? 'not selected'}`,
581
679
  `Observed: ${view.actualModel ?? 'no response yet'}`,
@@ -643,7 +741,9 @@ async function* passMain($, e, next, loop, version, nativeModel, reason, router)
643
741
  // the classifier call. The pin is the one in `view`, the view as the step read it; it is used up only once the route
644
742
  // is written, so a turn interrupted before then leaves it for the next.
645
743
  async function decideTurn($, router, e, signal, step) {
646
- const { sessionId, view, cfg, loop, loopVersion, context, nativeModel, availableModels } = step;
744
+ const { sessionId, view, loop, loopVersion, context, nativeModel, availableModels } = step;
745
+ // A pin runs its tier's configured route: the routing mode moves only routes the router chooses.
746
+ const cfg = view.pendingPin ? step.configured : step.cfg;
647
747
  const ref = { ...LOOP, id: 'main' };
648
748
  const controller = new AbortController();
649
749
  const cancel = () => controller.abort();
@@ -690,6 +790,8 @@ async function decideTurn($, router, e, signal, step) {
690
790
  if (controller.signal.aborted || (await $.session.id()) !== sessionId || (await modeOf($, router)) !== 'auto')
691
791
  return null;
692
792
  const previous = loop.decision;
793
+ if (pin)
794
+ router.turnConfigs.set(e.turnId, { config: { ...cfg, routingMode: step.cfg.routingMode }, configured: cfg });
693
795
  const selected = chooseRoute(cfg, loop, {
694
796
  facts,
695
797
  advice: result.advice,
@@ -708,12 +810,29 @@ async function decideTurn($, router, e, signal, step) {
708
810
  if (previous?.model && previous.model !== selected.decision.model && !selected.decision.pinned)
709
811
  $.ui.toast(switchToast(cfg, previous, selected.decision, selected.decision.estimate));
710
812
  const activity = turnActivity(cfg, result.advice, previous, selected.decision);
813
+ const routingMode = step.cfg.routingMode;
814
+ // One line per decision in Claude Code's debug log, so a later replay can compare modes. No prompt text.
815
+ $.ui.log(
816
+ `router decision ${JSON.stringify({
817
+ mode: routingMode.mode,
818
+ modeSource: routingMode.source,
819
+ classified: result.advice?.choice ?? null,
820
+ tier: selected.decision.tier,
821
+ reason: selected.decision.reason,
822
+ route: `${selected.decision.model}@${selected.decision.effort ?? 'session'}`,
823
+ pinned: selected.decision.pinned,
824
+ })}`,
825
+ { to: 'debug' },
826
+ );
711
827
  router.turnActivities.set(e.turnId, {
712
828
  ...activity,
713
829
  reason: selected.decision.reason,
714
830
  escalated: Boolean(selected.decision.escalated),
715
831
  pinned: selected.decision.pinned,
716
832
  route: `${selected.decision.model}@${selected.decision.effort ?? 'session'}`,
833
+ // A pinned turn ran the configured routes, which balanced runs: its replies count there.
834
+ routingMode: pin ? DEFAULTS.mode : routingMode.mode,
835
+ modeSource: pin ? 'pin' : routingMode.source,
717
836
  classifier: cfg.classifier,
718
837
  offSwitches: router.offSwitches,
719
838
  adviceMs,
@@ -728,6 +847,8 @@ async function decideTurn($, router, e, signal, step) {
728
847
  await updateView($, router, {
729
848
  ...(activity.switched ? switchView(previous, selected.decision, activity.label, Date.now()) : {}),
730
849
  phase: 'routed',
850
+ // The session's mode, not this turn's: a `/router mode` sent while the classifier answered names the next turn.
851
+ routingMode: await routingModeOf($, router),
731
852
  selectedModel: selected.decision.model,
732
853
  actualModel: null,
733
854
  tier: selected.decision.tier,
@@ -994,6 +1115,7 @@ async function addSavings($, router, { turnId, compared, tier, route, yours, byI
994
1115
  const turn = router.turnActivities.get(turnId);
995
1116
  const entry = replyEntry({
996
1117
  at,
1118
+ mode: turn?.routingMode ?? view.routingMode?.mode ?? DEFAULTS.mode,
997
1119
  activity: tier ? (turn?.label ?? null) : null,
998
1120
  tier,
999
1121
  route,
@@ -1192,17 +1314,27 @@ async function noteSpawn($, router, { cfg, e, pass, decision, routed, result, de
1192
1314
  definition,
1193
1315
  })
1194
1316
  : result.model;
1317
+ const routedModel = decision?.model ?? result.model;
1195
1318
  const record = spawnRecord({
1196
1319
  sessionId: await $.session.id(),
1197
1320
  spawn: e,
1198
1321
  pass,
1199
1322
  choice: decision?.choice ?? null,
1200
- routedModel: decision?.model ?? result.model,
1323
+ routedModel,
1201
1324
  coreModel,
1325
+ move: routed ? moveOf(cfg, routedModel, coreModel) : null,
1202
1326
  failed: decision?.failed,
1203
1327
  respawn: Number.isFinite(finishedAt) && Date.now() - finishedAt < RESPAWN_WINDOW_MS,
1204
1328
  });
1205
- router.agents.set(result.agentId, { ...record, parentKey });
1329
+ router.agents.set(result.agentId, { ...record, parentKey, running: true });
1330
+ await showRunning($, router);
1331
+ }
1332
+
1333
+ // How many of the agents with a record are between their start or a step and their turn's end, in the view when it
1334
+ // changes. An agent spawned with routing off has no record and is not counted.
1335
+ async function showRunning($, router) {
1336
+ const running = [...router.agents.values()].filter((agent) => agent.running).length;
1337
+ if ((router.view?.subagentsRunning ?? 0) !== running) await updateView($, router, { subagentsRunning: running });
1206
1338
  }
1207
1339
 
1208
1340
  // A subagent's prompt-cache lifetime, by Claude Code's rule for requests outside the main conversation.
@@ -1224,7 +1356,9 @@ async function* stepAgent($, router, e, next) {
1224
1356
  try {
1225
1357
  const ttl = await subagentTtlOf($);
1226
1358
  const agent = router.agents.get(e.agentId);
1227
- if (agent) router.agents.set(e.agentId, addAgentReply(router.config, agent, response.usage, ttl));
1359
+ if (agent)
1360
+ router.agents.set(e.agentId, { ...addAgentReply(router.config, agent, response.usage, ttl), running: true });
1361
+ if (agent && !agent.running) await showRunning($, router);
1228
1362
  } catch {}
1229
1363
  }
1230
1364
  return response;
@@ -1235,7 +1369,8 @@ async function finishAgent($, router, agentId) {
1235
1369
  const agent = router.agents.get(agentId);
1236
1370
  if (!agent) return;
1237
1371
  router.finished.set(agent.parentKey, Date.now());
1238
- router.agents.set(agentId, flushedAgent(agent));
1372
+ router.agents.set(agentId, { ...flushedAgent(agent), running: false });
1373
+ await showRunning($, router).catch(() => {});
1239
1374
  await flushSubagents($, router, [agent]);
1240
1375
  }
1241
1376
 
@@ -1310,7 +1445,9 @@ function paneActions($, router, view) {
1310
1445
  if (result.error) return updateView($, router, { notice: result.error });
1311
1446
  const drafts = router.view ?? view;
1312
1447
  const reset = await adopt(result.config);
1313
- return updateView($, router, { ...reset, ...rebased(drafts), ...saved(router.config) });
1448
+ // A saved or undone profile mode changes the mode shown, unless a session or project mode wins.
1449
+ const routingMode = await routingModeOf($, router);
1450
+ return updateView($, router, { ...reset, ...rebased(drafts), ...saved(router.config), routingMode });
1314
1451
  };
1315
1452
  // Defaults go into the routing draft like any edit; the notice says whether Save has anything of that section left
1316
1453
  // to write.
@@ -1410,6 +1547,12 @@ function paneActions($, router, view) {
1410
1547
  // An insight's link: the Routes tab with the grid cell it names open.
1411
1548
  openRoute: (cell) => updateView($, router, { tab: 'routes', routeCell: cell, notice: null }),
1412
1549
  confirmDelete: (asked) => updateView($, router, { confirmDelete: asked }),
1550
+ // The profile's routing mode, saved at once with Undo. A session or project mode still wins over it.
1551
+ routingMode: async (mode) => {
1552
+ const from = router.config.mode;
1553
+ if (mode === from || !ROUTING_MODES.includes(mode)) return undefined;
1554
+ return write(`routing mode ${from} → ${mode}`, (file) => withMode(file, mode));
1555
+ },
1413
1556
  // `/router activities <mode>`: the mode alone, saved at once like a classifier press, with Undo.
1414
1557
  activityRouting: (mode) => {
1415
1558
  const from = router.config.activityRouting;
@@ -1557,13 +1700,14 @@ export function register(on, options) {
1557
1700
  router.definitions.clear();
1558
1701
  await $.command.register({
1559
1702
  name: 'router',
1560
- description: 'Open the Router pane, or switch routing: auto, off, pin <tier>, activities <mode>.',
1561
- argumentHint: '[auto|off|pin <tier>|activities off|on]',
1703
+ description: 'Open the Router pane, or switch routing: auto, off, pin <tier>, activities <mode>, mode <mode>.',
1704
+ argumentHint: '[auto|off|pin <tier>|activities off|on|mode cost|balanced|quality|default]',
1562
1705
  immediate: true,
1563
1706
  });
1564
1707
  const model = await $.session.model();
1565
1708
  try {
1566
1709
  router.config = await loadNativeConfig($);
1710
+ router.project = await readProject($, router.config.nativePath);
1567
1711
  const existing = await readView($, router);
1568
1712
  router.view = existing;
1569
1713
  const sameClassifier = existing.health?.classifier === router.config.classifier;
@@ -1584,6 +1728,8 @@ export function register(on, options) {
1584
1728
  credentials: await credentialsOf($, options, router.config),
1585
1729
  health: healthOf(clientOf(router, router.config.classifier), router.config.classifier),
1586
1730
  configPath: router.config.nativePath,
1731
+ routingMode: await routingModeOf($, router),
1732
+ projectError: router.project.error,
1587
1733
  tuning: null,
1588
1734
  tuningBase: null,
1589
1735
  routeDraft: null,
@@ -1623,8 +1769,8 @@ export function register(on, options) {
1623
1769
 
1624
1770
  on('command.run', { command: 'router' }, ($, e) => routerCommand($, router, e.args));
1625
1771
 
1626
- on('turn.start', (_$, e, next) => {
1627
- router.turnConfigs.set(e.turnId, router.config);
1772
+ on('turn.start', async ($, e, next) => {
1773
+ await fixTurnConfig($, router, e.turnId);
1628
1774
  router.prompts.set(e.turnId, clip(e.text, router.config.context.maxTextChars));
1629
1775
  return next(e);
1630
1776
  });
@@ -1637,7 +1783,8 @@ export function register(on, options) {
1637
1783
 
1638
1784
  on('turn.step', async function* ($, e, next) {
1639
1785
  if (e.agentId) return yield* stepAgent($, router, e, next);
1640
- const cfg = router.turnConfigs.get(e.turnId) ?? router.config;
1786
+ const turn = router.turnConfigs.get(e.turnId) ?? (await turnConfigOf($, router));
1787
+ const cfg = turn.config;
1641
1788
  const [sessionId, nativeModel, view] = await Promise.all([$.session.id(), $.session.model(), readView($, router)]);
1642
1789
  const mode = await modeOf($, router, view.mode);
1643
1790
  if (e.index === 0) {
@@ -1651,7 +1798,8 @@ export function register(on, options) {
1651
1798
  const ref = { ...LOOP, id: 'main' };
1652
1799
  const loaded = await $.state.get(ref);
1653
1800
  let loopVersion = loaded.version;
1654
- let loop = prepareLoop(loaded.value ?? emptyLoop(cfg, e.model), e.messageCount);
1801
+ // The session's model names its tier in the configured routes: a mode's table can run it at another tier.
1802
+ let loop = prepareLoop(loaded.value ?? emptyLoop(turn.configured, e.model), e.messageCount);
1655
1803
  if (view.phase === 'unavailable' || mode === 'manual') {
1656
1804
  return yield* passMain($, e, next, loop, loopVersion, nativeModel, 'manual', router);
1657
1805
  }
@@ -1668,6 +1816,7 @@ export function register(on, options) {
1668
1816
  sessionId,
1669
1817
  view,
1670
1818
  cfg,
1819
+ configured: turn.configured,
1671
1820
  loop,
1672
1821
  loopVersion,
1673
1822
  context,
@@ -1769,13 +1918,7 @@ export function register(on, options) {
1769
1918
 
1770
1919
  // Paused or broken routing stays visible in the prompt footer even when the band is collapsed.
1771
1920
  on('ui.render', { component: 'SessionMode' }, async ($, e, next) => {
1772
- const view = await readView($, router);
1773
- const label =
1774
- view.phase === 'unavailable'
1775
- ? 'routing unavailable'
1776
- : (await modeOf($, router, view.mode)) === 'manual'
1777
- ? 'routing off'
1778
- : null;
1921
+ const label = await footerLabel($, router, await readView($, router));
1779
1922
  return label ? next({ ...e, props: { ...e.props, modes: [...e.props.modes, label] } }) : next(e);
1780
1923
  });
1781
1924
 
@@ -1797,7 +1940,11 @@ export function register(on, options) {
1797
1940
  router.config,
1798
1941
  view,
1799
1942
  usage,
1800
- { columns: e.props.bodyColumns, agentId: e.props.view?.agentId },
1943
+ {
1944
+ columns: e.props.bodyColumns,
1945
+ agentId: e.props.view?.agentId,
1946
+ agent: router.agents.get(e.props.view?.agentId) ?? null,
1947
+ },
1801
1948
  {
1802
1949
  open: () => openPane($, router),
1803
1950
  mode: (mode) => changeMode($, router, mode),
package/lib/activity.mjs CHANGED
@@ -54,15 +54,21 @@ export function chooseActivity(config, advice, incumbent, sentEffort, facts = {}
54
54
  // the base route), must clear the tier upgrade bar for this switching tax. Down on economics: the move must pay back
55
55
  // its cache write within the downgrade horizon. A pair that does not order (an unpriced model, a numeric effort, two
56
56
  // models at one price) counts as up: it needs evidence, and the base route is always reachable. Labels alone never
57
- // switch, so one vote is enough. During an escalation hold only a stronger route may be taken. Returns
57
+ // switch, so one vote is enough. During an escalation hold only a stronger route may be taken. A cheaper route on the
58
+ // same task (`sameTask`) waits for facts.downAllowed, as a tier downgrade does: a routing mode changes the route
59
+ // without a new label, and a free switch must still wait out the dwell. A model with a lower input price also counts
60
+ // as cheaper there, whatever its output price: that is the order the cost mode picks by. Returns
58
61
  // { move, reason, estimate }.
59
- export function lateralMove({ config, from, to, mass, hold, facts, now, costs }) {
62
+ export function lateralMove({ config, from, to, mass, hold, sameTask = false, facts, now, costs }) {
60
63
  const order = compareRoutes(config, to, from, facts.effort);
61
64
  if (hold && !(order > 0)) return { move: false, reason: 'hold', estimate: null };
62
65
  const p = config.policy;
63
66
  let estimate;
67
+ if (order !== -1 && sameTask && !facts.downAllowed && routeSpec(config, to).input < routeSpec(config, from).input)
68
+ return { move: false, reason: 'downgrade-held', estimate: null };
64
69
  if (order === -1) {
65
70
  estimate = { taxUsd: costs.downgradeTaxUsd(config, to, from, facts, now, p.downgradeHorizonTurns) };
71
+ if (sameTask && !facts.downAllowed) return { move: false, reason: 'downgrade-held', estimate };
66
72
  // Before the first measured reply no cache of this history exists, though the tax prices an unknown one as warm:
67
73
  // staying protects nothing.
68
74
  const fresh = facts.historyMeasured === false;
package/lib/band.mjs CHANGED
@@ -5,11 +5,13 @@ import {
5
5
  classifierStatus,
6
6
  classifierWarns,
7
7
  differenceShare,
8
+ modelColor,
8
9
  modelName,
9
10
  NOT_A_TIER_REASON,
10
11
  percentPair,
11
12
  reasonActivity,
12
13
  routeLabel,
14
+ routingModeText,
13
15
  SAVINGS_COLOR,
14
16
  shortReason,
15
17
  TIER_COLOR,
@@ -20,6 +22,7 @@ import {
20
22
  } from './display.mjs';
21
23
  import { isSameModel } from './route.mjs';
22
24
  import { emptyTotals, modelSpec, readout } from './savings.mjs';
25
+ import { PASS_WHY } from './subagents.mjs';
23
26
 
24
27
  const BARS = '▂▄▆█';
25
28
  const SEPARATOR = ' · ';
@@ -160,7 +163,11 @@ export function bandSegments(config, view, usage, actions) {
160
163
  )
161
164
  : null;
162
165
  if (!view.tier && view.phase === 'ready' && !view.actualModel)
163
- 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);
164
171
  const main = segment(
165
172
  0,
166
173
  // The space after the pill keeps its background off the next word.
@@ -191,6 +198,7 @@ export function bandSegments(config, view, usage, actions) {
191
198
  main,
192
199
  pin,
193
200
  segment(1, part(shortReason(view.reason, reasonActivity(config, view)), { dimColor: true })),
201
+ segment(5, part(routingModeText(view), { dimColor: true })),
194
202
  support ? segment(4, part(support, { dimColor: true })) : null,
195
203
  Number.isFinite(switchUsd) && switchUsd >= 0.005
196
204
  ? segment(4, part(`switch cost ≈ ${usd(switchUsd)}`, { dimColor: true }))
@@ -265,19 +273,43 @@ function hoverSegments(view, actions, routing) {
265
273
  ].filter(Boolean);
266
274
  }
267
275
 
268
- export function renderBand({ Box, Text, Button }, config, view, usage, { columns, agentId }, actions) {
276
+ // A subagent's model and who chose it, as the Usage tab's squares show it: filled when the router moved it off
277
+ // Claude Code's pick. Claude Code's model goes first in a narrow band.
278
+ function agentParts(agent, columns) {
279
+ const color = modelColor(agent.routedModel);
280
+ const moved = !agent.pass && agent.move;
281
+ const name = part(`${moved ? '■' : '□'} ${modelName(agent.routedModel)}`, color ? { color } : {});
282
+ const why = agent.pass
283
+ ? `Claude Code’s pick: ${PASS_WHY[agent.pass]}`
284
+ : moved
285
+ ? `moved ${agent.move === 'moved' ? '' : `${agent.move} `}by the router`
286
+ : agent.choice === 'core'
287
+ ? `Claude Code’s pick: ${agent.failed ? 'classifier did not answer' : 'the router sent no model'}`
288
+ : 'the router kept Claude Code’s pick';
289
+ const parts = [part('○ Router · ', { dimColor: true }), name, part(` · ${why}`, { dimColor: true })];
290
+ const pick = part(` · Claude Code: ${modelName(agent.coreModel)}`, { dimColor: true });
291
+ const width = parts.reduce((sum, p) => sum + p.text.length, 0) + pick.text.length;
292
+ return moved && agent.coreModel && !(Number.isFinite(columns) && width > columns) ? [...parts, pick] : parts;
293
+ }
294
+
295
+ export function renderBand({ Box, Text, Button }, config, view, usage, { columns, agentId, agent = null }, actions) {
269
296
  const draw = (p) => (p.button ? Button(p.button) : Text({ ...p.style, children: p.text }));
270
297
  const row = (parts) => Box({ children: parts.map(draw) });
271
- // A subagent's model is chosen once, at spawn, and never changes between its steps.
298
+ // A subagent's model is chosen once, at spawn, and never changes between its steps. Without its record (routing
299
+ // off, or the router reloaded since the spawn) only the mode is known.
272
300
  if (agentId)
273
- return row([
274
- part(
275
- config.subagentRouting === 'on'
276
- ? '○ Router · subagent model chosen at spawn'
277
- : '○ Router · subagents keep their own model',
278
- { dimColor: true },
279
- ),
280
- ]);
301
+ return row(
302
+ agent
303
+ ? agentParts(agent, columns)
304
+ : [
305
+ part(
306
+ config.subagentRouting === 'on'
307
+ ? '○ Router · subagent model chosen at spawn'
308
+ : '○ Router · subagents keep their own model',
309
+ { dimColor: true },
310
+ ),
311
+ ],
312
+ );
281
313
  const kept = fitSegments(bandSegments(config, view, usage, actions), Math.max(0, columns - ROUTER_BUTTON));
282
314
  const line = kept.flatMap((s, i) => (i ? [part(SEPARATOR, { dimColor: true }), ...s.parts] : s.parts));
283
315
  line.push(part(' '), button({ key: 'details', label: 'Router', plain: true, onPress: actions.open }));
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)