@alexeiled/claude-router 1.24.0 → 1.25.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (79) hide show
  1. package/.claude-plugin/plugin.json +1 -1
  2. package/CHANGELOG.md +74 -0
  3. package/README.md +55 -7
  4. package/docs/architecture.md +30 -4
  5. package/docs/configuration.md +23 -14
  6. package/docs/evaluation.md +3 -3
  7. package/docs/native-router.md +12 -4
  8. package/docs/router-band.svg +140 -142
  9. package/docs/router-pane-classifier.svg +48 -31
  10. package/docs/router-pane-now.svg +162 -120
  11. package/docs/router-pane-policy.svg +79 -47
  12. package/docs/router-pane-routes.svg +8 -8
  13. package/docs/router-pane-usage-whatif.svg +14 -14
  14. package/docs/router-pane-usage.svg +20 -20
  15. package/docs/routing-modes.md +10 -8
  16. package/docs/user-guide.md +151 -22
  17. package/hooks/native-router.mjs +415 -88
  18. package/lib/activity-stats.mjs +23 -4
  19. package/lib/activity.mjs +7 -5
  20. package/lib/auto-engine.mjs +13 -6
  21. package/lib/auto-route.mjs +10 -4
  22. package/lib/band.mjs +35 -440
  23. package/lib/classifier-client.mjs +12 -8
  24. package/lib/config-file.mjs +7 -2
  25. package/lib/config.mjs +24 -9
  26. package/lib/cost.mjs +5 -1
  27. package/lib/costs.mjs +4 -2
  28. package/lib/decisions.mjs +13 -9
  29. package/lib/display.mjs +71 -20
  30. package/lib/facts.mjs +3 -0
  31. package/lib/failover.mjs +55 -0
  32. package/lib/modes.mjs +8 -4
  33. package/lib/panel.mjs +75 -2167
  34. package/lib/policy.mjs +7 -6
  35. package/lib/replay-trace.mjs +5 -2
  36. package/lib/replay.mjs +7 -1
  37. package/lib/route-line.mjs +46 -0
  38. package/lib/route.mjs +51 -32
  39. package/lib/savings.mjs +14 -3
  40. package/lib/subagents.mjs +41 -11
  41. package/lib/subcommands.mjs +60 -0
  42. package/lib/ui/fallback.mjs +22 -0
  43. package/lib/ui/graphical/band.mjs +256 -0
  44. package/lib/ui/graphical/charts.mjs +163 -0
  45. package/lib/ui/graphical/classifier.mjs +153 -0
  46. package/lib/ui/graphical/frame.mjs +231 -0
  47. package/lib/ui/graphical/kit.mjs +156 -0
  48. package/lib/ui/graphical/meter.mjs +25 -0
  49. package/lib/ui/graphical/now.mjs +357 -0
  50. package/lib/ui/graphical/policy.mjs +56 -0
  51. package/lib/ui/graphical/routes.mjs +264 -0
  52. package/lib/ui/graphical/squares.mjs +29 -0
  53. package/lib/ui/graphical/usage.mjs +376 -0
  54. package/lib/ui/model/band.mjs +441 -0
  55. package/lib/ui/model/classifier.mjs +308 -0
  56. package/lib/ui/model/draft.mjs +62 -0
  57. package/lib/ui/model/format.mjs +41 -0
  58. package/lib/ui/model/frame.mjs +359 -0
  59. package/lib/ui/model/now.mjs +421 -0
  60. package/lib/ui/model/policy.mjs +194 -0
  61. package/lib/ui/model/routes.mjs +392 -0
  62. package/lib/ui/model/usage-agents.mjs +311 -0
  63. package/lib/ui/model/usage-breakdown.mjs +237 -0
  64. package/lib/ui/model/usage-shared.mjs +58 -0
  65. package/lib/ui/model/usage.mjs +330 -0
  66. package/lib/ui/terminal/band.mjs +253 -0
  67. package/lib/ui/terminal/classifier.mjs +150 -0
  68. package/lib/ui/terminal/frame.mjs +169 -0
  69. package/lib/ui/terminal/kit.mjs +162 -0
  70. package/lib/ui/terminal/now.mjs +293 -0
  71. package/lib/ui/terminal/policy.mjs +55 -0
  72. package/lib/ui/terminal/routes.mjs +167 -0
  73. package/lib/ui/terminal/usage.mjs +363 -0
  74. package/lib/ui/terminal/wrap.mjs +37 -0
  75. package/lib/ui/tokens.mjs +106 -0
  76. package/lib/usage.mjs +5 -5
  77. package/lib/view.mjs +5 -2
  78. package/package.json +4 -2
  79. package/types/index.d.ts +17 -0
package/lib/policy.mjs CHANGED
@@ -35,15 +35,15 @@ export function decide({
35
35
  const next = { ...state, turn: state.turn + 1, votes: [...state.votes] };
36
36
  const incumbent = facts.lastRoute && TIERS.includes(facts.lastRoute) ? facts.lastRoute : baseline;
37
37
  const current = incumbentRoute ?? routeFor(incumbent);
38
- const stay = (reason, estimate = null) => result(incumbent, reason, next, estimate);
38
+ const stay = (reason, estimate = /** @type {object | null} */ (null)) => result(incumbent, reason, next, estimate);
39
39
 
40
- const target = facts.failure && facts.failure.signature !== next.escalatedSignature ? escalateTo(incumbent) : null;
41
- if (target) {
40
+ const escalated = facts.failure && facts.failure.signature !== next.escalatedSignature ? escalateTo(incumbent) : null;
41
+ if (escalated) {
42
42
  next.escalatedSignature = facts.failure.signature;
43
43
  next.holdUntilTurn = next.turn + config.policy.escalationHoldTurns;
44
44
  next.votes = [];
45
- const gated = cashGate(config, routeFor(target), facts, now, costs, routeFor);
46
- return gated.blocked ? gatedResult(gated, incumbent, next) : result(target, 'escalation', next);
45
+ const gated = cashGate(config, routeFor(escalated), facts, now, costs, routeFor);
46
+ return gated.blocked ? gatedResult(gated, incumbent, next) : result(escalated, 'escalation', next);
47
47
  }
48
48
  if (next.turn <= next.holdUntilTurn) return stay('hold');
49
49
  if (!advice) return stay('no-advice');
@@ -80,6 +80,7 @@ export function decide({
80
80
  // The move lands on the cheapest tier the answer supports as a whole: from the choice up to just below the
81
81
  // incumbent, the first tier whose mass at or below it clears its bar. A split answer (micro 0.8, low 0.16) on high
82
82
  // moves to low instead of waiting for micro alone to reach the bar. A pending stay reports the choice's estimate.
83
+ /** @type {object | null} */
83
84
  let pending = null;
84
85
  for (const target of TIERS.filter((t) => rank(t) >= rank(choice) && rank(t) < rank(incumbent))) {
85
86
  const support = massAtOrBelow(advice.probabilities, target);
@@ -157,7 +158,7 @@ function trailing(votes, predicate) {
157
158
  return count;
158
159
  }
159
160
 
160
- function result(tier, reason, state, estimate = null) {
161
+ function result(tier, reason, state, estimate = /** @type {object | null} */ (null)) {
161
162
  return { tier, reason, state, estimate };
162
163
  }
163
164
 
@@ -383,7 +383,7 @@ export function appendTrace(
383
383
  record,
384
384
  events,
385
385
  at,
386
- { lostWrites = 0, reasons = [], maxBytes = TRACE_SESSION_BYTES, excludedEvents = 0 } = {},
386
+ { lostWrites = 0, reasons = /** @type {string[]} */ ([]), maxBytes = TRACE_SESSION_BYTES, excludedEvents = 0 } = {},
387
387
  ) {
388
388
  const next = {
389
389
  ...record,
@@ -486,7 +486,10 @@ export function traceVictims(entries, at, ownKey, candidate, active = new Set())
486
486
  .filter(([key]) => key !== ownKey && !victims.has(key))
487
487
  .reduce((sum, [key, v]) => sum + traceBytes(key) + traceBytes(v) + 2, 0);
488
488
  for (const [key, v] of others
489
- .filter(([key, v]) => !victims.has(key) && !(at - v.updatedAt <= TRACE_ACTIVE_MS && (active.has(key) || v.active)))
489
+ .filter(
490
+ ([name, entry]) =>
491
+ !victims.has(name) && !(at - entry.updatedAt <= TRACE_ACTIVE_MS && (active.has(name) || entry.active)),
492
+ )
490
493
  .sort((a, b) => a[1].updatedAt - b[1].updatedAt)) {
491
494
  if (bytes <= TRACE_BUDGET_BYTES) break;
492
495
  victims.add(key);
package/lib/replay.mjs CHANGED
@@ -33,6 +33,7 @@ const countTurns = (events) => new Set(events.filter((e) => e.type === 'request'
33
33
 
34
34
  // Validate before projecting: malformed data must not quietly turn into a successful scenario.
35
35
  export function mergeExports(exports) {
36
+ /** @type {{ version: number, sessions: object } | null} */
36
37
  let merged = null;
37
38
  for (const value of exports) {
38
39
  if (value?.version !== 1 || !value.sessions || Array.isArray(value.sessions) || typeof value.sessions !== 'object')
@@ -200,6 +201,7 @@ function simulatedReply(config, loop, pair, event) {
200
201
  const pricedRoute = typeof route.effort === 'number' ? { ...route, effort: null } : route;
201
202
  const bounds = costs.inputBounds(config, pricedRoute, tokens, { models, effort: pair.effort }, event.at);
202
203
  const rates = costs.ratesAt(model, tokens, event.at);
204
+ if (rates.output === undefined) return { range: null, usage: null };
203
205
  const output = (usage.output_tokens * rates.output) / 1e6;
204
206
  const key = costs.cacheKey(config, pair.model, pair.effort);
205
207
  const prefix =
@@ -224,7 +226,8 @@ function acceptAutoAdvice(replay, event, op) {
224
226
  replay.advice = op.advice;
225
227
  const accepted = config.activityRouting === 'on' ? acceptActivity(config, op.advice) : null;
226
228
  const signal = routingActivity(config, op.advice);
227
- if (accepted) replay.activity = signal?.mass >= config.policy.activityMass ? signal.choice : accepted;
229
+ if (accepted)
230
+ replay.activity = signal !== null && signal.mass >= config.policy.activityMass ? signal.choice : accepted;
228
231
  replay.boundedExecute = accepted !== null && acceptPhase(config, op.advice) === 'execute';
229
232
  replay.observedFrom = op.facts?.midTurn
230
233
  ? Math.max(op.taskProgress?.prompt ?? 0, (event.observedFrom ?? 0) - 1)
@@ -443,6 +446,7 @@ export function replayAuto(record, tableRows) {
443
446
  effort: row.pair.effort,
444
447
  usage: substituted ? { model: event.servedModel } : simulated.usage,
445
448
  });
449
+ // biome-ignore lint/suspicious/noUnnecessaryConditions: savedPin is set in another function through `replay`, which Biome cannot follow
446
450
  if (replay.savedPin) replay.pendingFallback = external;
447
451
  else Object.assign(replay, external);
448
452
  }
@@ -465,7 +469,9 @@ export function replayAuto(record, tableRows) {
465
469
  }
466
470
 
467
471
  function markSwitches(rows, window) {
472
+ /** @type {{ from: object, to: object, turn: number, paired: boolean } | null} */
468
473
  let prior = null;
474
+ /** @type {{ generation: number, pair: object } | null} */
469
475
  let previous = null;
470
476
  for (const row of rows) {
471
477
  if (row.manual || row.fallback || row.external) {
@@ -0,0 +1,46 @@
1
+ // The route line: one row placed at the end of the transcript after a turn, saying which model and effort ran and why.
2
+ // Pure: which turns get a row, and what it records. The hook places it (`$.ui.place`) and draws it (`ui.render` on
3
+ // `Placed`); the words and the glyphs are the band's (ui/model/band.mjs).
4
+ import { reasonActivity } from './display.mjs';
5
+
6
+ export const LINE_MODES = ['off', 'moves', 'all'];
7
+ // `moves` says the route only when it is not the last turn's.
8
+ export const DEFAULT_LINE_MODE = 'moves';
9
+ const ID_PREFIX = 'rl-';
10
+ // `$.ui.place` takes 1 to 64 letters, digits, `_` and `-`.
11
+ const ID_MAX = 64;
12
+
13
+ export const lineModeOf = (stored) => (LINE_MODES.includes(stored) ? stored : DEFAULT_LINE_MODE);
14
+
15
+ /** The row's id for a turn: its id with anything `$.ui.place` refuses made `_`, so one turn has one row. */
16
+ export const lineId = (turnId) => `${ID_PREFIX}${String(turnId).replace(/[^A-Za-z0-9_-]/g, '_')}`.slice(0, ID_MAX);
17
+
18
+ /** The route a view shows: the model that served the turn, else the one chosen, and its effort; null with neither. */
19
+ export function routeOf(view) {
20
+ const model = view?.actualModel ?? view?.selectedModel ?? null;
21
+ return model ? { model, effort: view.effort ?? null } : null;
22
+ }
23
+
24
+ /** Whether a turn that ran `route` gets a row, after one that ran `previous` (null at a session's first routed turn). */
25
+ export function showsLine(mode, previous, route) {
26
+ if (mode === 'off') return false;
27
+ return mode === 'all' || !previous || previous.model !== route.model || previous.effort !== route.effort;
28
+ }
29
+
30
+ /**
31
+ * What the row keeps: the route, the tier it ran for, why, the activity and the policy's estimate; nothing of the
32
+ * prompt.
33
+ * @returns {{ model: string, effort: string | number | null, tier: string | null, reason: string, activity: string | null, reasonActivity: string | null, estimate: object | null }}
34
+ */
35
+ export function lineOf(config, view, route) {
36
+ return {
37
+ model: route.model,
38
+ effort: route.effort,
39
+ tier: view.tier ?? null,
40
+ reason: view.reason ?? 'ready',
41
+ activity: view.activity ?? null,
42
+ // The activity the reason names, as the band words it: not the one a refused move left the turn on.
43
+ reasonActivity: reasonActivity(config, view),
44
+ estimate: view.estimate ?? null,
45
+ };
46
+ }
package/lib/route.mjs CHANGED
@@ -11,6 +11,7 @@ import {
11
11
  import { ACTIVITIES, rank, resolveRoute, routeSpec, sameRoute, TIERS } from './config.mjs';
12
12
  import * as costs from './cost.mjs';
13
13
  import { clip, completedSince, extractFacts, stripReminders } from './facts.mjs';
14
+ import { heldModels } from './failover.mjs';
14
15
  import { CONTEXT_FILL, decide, fitTier, initialState, sameTaskOf } from './policy.mjs';
15
16
  import { canonicalModel } from './providers.mjs';
16
17
 
@@ -38,8 +39,8 @@ export function isNativeFallback(loop, model) {
38
39
  // The tier and activity whose route runs model `id`, or null when no route names it. Base routes first, baseline
39
40
  // first; activity overrides only when they apply, with `activityRouting: on`.
40
41
  export function cellForModel(config, id) {
41
- const order = [config.baselineTier, ...TIERS.filter((tier) => tier !== config.baselineTier)];
42
- const runs = (tier, activity) => isSameModel(routeSpec(config, resolveRoute(config, tier, activity)).id, id);
42
+ const order = [config.baselineTier, ...TIERS.filter((other) => other !== config.baselineTier)];
43
+ const runs = (candidate, kind) => isSameModel(routeSpec(config, resolveRoute(config, candidate, kind)).id, id);
43
44
  const tier = order.find((t) => runs(t, null));
44
45
  if (tier) return { tier, activity: null };
45
46
  if (config.activityRouting !== 'on') return null;
@@ -189,10 +190,14 @@ export function chooseRoute(config, loop, input) {
189
190
  sameRoute(applied.route, resolveRoute(config, applied.tier, 'ops'))
190
191
  )
191
192
  applied.activity = 'ops';
192
- const kept = pin || !applied.tier;
193
+ // A route standing in for a held-out model serves this turn only, as a pin does: once the hold ends, the next turn
194
+ // runs the route it held out without passing a switching gate. Nor does the turn keep the votes or the escalation
195
+ // `decide` recorded for the held route, which never ran: the same failure still escalates once the hold ends.
196
+ const heldOut = applied.reason === 'model-held';
197
+ const kept = pin || !applied.tier || heldOut;
193
198
  return {
194
199
  ...loop,
195
- state: applied.state,
200
+ state: heldOut ? { ...loop.state, turn: loop.state.turn + 1 } : applied.state,
196
201
  hasRoutedDecision: true,
197
202
  lastRoute: kept ? loop.lastRoute : applied.tier,
198
203
  lastActivity: kept ? activityOf(config, loop) : applied.activity,
@@ -219,7 +224,7 @@ function opsFloor(config, activity) {
219
224
  for (const tier of TIERS) {
220
225
  if (declared[activity]?.[tier]) continue;
221
226
  const ops = resolveRoute(config, tier, 'ops');
222
- if (!(compareRoutes(config, resolveRoute(config, tier, activity), ops) < 0)) continue;
227
+ if ((compareRoutes(config, resolveRoute(config, tier, activity), ops) ?? 0) >= 0) continue;
223
228
  cells[tier] = ops;
224
229
  retained.push(tier);
225
230
  }
@@ -236,6 +241,14 @@ function opsFloor(config, activity) {
236
241
  // the mode changed: `off` is the 1.5 decision.
237
242
  const activityOf = (config, loop) => (config.activityRouting === 'on' ? (loop.lastActivity ?? null) : null);
238
243
 
244
+ // A model an API error held out of routing at `now` (failover.mjs).
245
+ const isHeld = (loop, id, now) => heldModels(loop.held, now).some((model) => isSameModel(model, id));
246
+ // A model this turn cannot send to: one whose context window a request exceeded, or a held-out one.
247
+ const withheld = (loop, id, now) => loop.ineligible.includes(id) || isHeld(loop, id, now);
248
+ // Every tier, nearest to `tier` first; of two as near, the stronger.
249
+ const nearestTiers = (tier) =>
250
+ [...TIERS].sort((a, b) => Math.abs(rank(a) - rank(tier)) - Math.abs(rank(b) - rank(tier)) || rank(b) - rank(a));
251
+
239
252
  // One decision (plan §5.2) for the cell `{ tier, activity }` it lands on. Outside `on` the activity is null throughout.
240
253
  function routeTurn(config, loop, { facts, advice, pin, nativeModel, contextKnown, availableModels, now }) {
241
254
  const last = {
@@ -247,11 +260,9 @@ function routeTurn(config, loop, { facts, advice, pin, nativeModel, contextKnown
247
260
  // The incumbent runs the route in use, not the one config gives its cell now. It is rebuilt from config for a loop
248
261
  // from before 1.15, a route whose model left the config or can no longer run, and a route kept for an activity that
249
262
  // no longer applies (activity routing turned off).
250
- const usable = (route) => {
251
- const model = Object.hasOwn(config.models, route.model) ? config.models[route.model] : null;
252
- return Boolean(
253
- model && isModelAllowed(model.id, availableModels, nativeModel) && !loop.ineligible.includes(model.id),
254
- );
263
+ const usable = (held) => {
264
+ const model = Object.hasOwn(config.models, held.model) ? config.models[held.model] : null;
265
+ return Boolean(model && isModelAllowed(model.id, availableModels, nativeModel) && !withheld(loop, model.id, now));
255
266
  };
256
267
  const inUse = loop.route && usable(loop.route) && (loop.lastActivity ?? null) === last.activity ? loop.route : null;
257
268
  const incumbent = {
@@ -284,9 +295,10 @@ function routeTurn(config, loop, { facts, advice, pin, nativeModel, contextKnown
284
295
  !shrinksUnmeasured(cell) &&
285
296
  (!facts.hasImages || model.imageInput !== false) &&
286
297
  isModelAllowed(model.id, availableModels, nativeModel) &&
287
- !loop.ineligible.includes(model.id)
298
+ !withheld(loop, model.id, now)
288
299
  );
289
300
  };
301
+ const heldOut = (cell) => isHeld(loop, specOf(cell).id, now);
290
302
  const roomFor = (cell) =>
291
303
  !contextKnown || costs.nextContextTokens(facts) <= specOf(cell).contextWindow * CONTEXT_FILL;
292
304
  const fits = (cell) => runs(cell) && roomFor(cell);
@@ -305,21 +317,22 @@ function routeTurn(config, loop, { facts, advice, pin, nativeModel, contextKnown
305
317
  // A cell labelled with another activity would run, and stick, a route this turn did not choose.
306
318
  const native = cellForModel(config, nativeModel);
307
319
  const acceptedActivity = result.floorActivity ?? result.activity;
308
- const cells = [
309
- last,
310
- native && { ...native, floorActivity: null },
311
- ...TIERS.map((tier) => ({ tier, activity: acceptedActivity, floorActivity: result.floorActivity })),
312
- ];
320
+ const tierCell = (tier) => ({ tier, activity: acceptedActivity, floorActivity: result.floorActivity });
321
+ // A held-out model is back soon: the nearest tier stands in for it, not the last or the cheapest route.
322
+ const cells = heldOut(result)
323
+ ? nearestTiers(result.tier).map(tierCell)
324
+ : [last, native && { ...native, floorActivity: null }, ...TIERS.map(tierCell)];
313
325
  const fallback = cells.find(
314
326
  (cell) => cell && (cell.activity === null || cell.activity === acceptedActivity) && fits(cell),
315
327
  ) ?? { tier: null, activity: null, floorActivity: null };
316
328
  // Only the window failed: no route is withheld, the conversation is just too full for every one of them.
317
- const reason = runs(result) ? 'context-full' : 'model-unavailable';
329
+ const reason = runs(result) ? 'context-full' : heldOut(result) ? 'model-held' : 'model-unavailable';
318
330
  result = { ...result, ...fallback, reason, lateral: null };
319
331
  }
320
332
  const route = result.tier ? routeOf(result) : null;
321
333
  const model = route ? routeSpec(config, route).id : nativeModel;
322
334
  const effort = route ? costs.routeEffort(config, route, facts.effort) : facts.effort;
335
+ /** @type {object | null} */
323
336
  let comparison = null;
324
337
  const candidate = pin ?? advice?.choice;
325
338
  if (contextKnown && loop.lastRequest && TIERS.includes(candidate) && candidate !== loop.lastRoute) {
@@ -396,7 +409,10 @@ function decideCell({
396
409
  // order against it: after a mode change the next tier's route can be the weaker one.
397
410
  const escalates = (t) => {
398
411
  const order = compareRoutes(config, routeFor(t), incumbent.route, facts.effort);
399
- return order > 0 || (order === null && !sameRequest(config, routeFor(t), incumbent.route, facts.effort));
412
+ return (
413
+ (order !== null && order > 0) ||
414
+ (order === null && !sameRequest(config, routeFor(t), incumbent.route, facts.effort))
415
+ );
400
416
  };
401
417
  const escalateTo = (tier) => TIERS.slice(rank(tier) + 1).find(escalates) ?? null;
402
418
  const step = decide({
@@ -439,10 +455,10 @@ function decideCell({
439
455
  now,
440
456
  costs,
441
457
  });
442
- const activityOf = lateral.move ? activity : incumbent.activity;
458
+ const routedActivity = lateral.move ? activity : incumbent.activity;
443
459
  return {
444
460
  ...step,
445
- activity: activityOf,
461
+ activity: routedActivity,
446
462
  floorActivity: lateral.move ? floorActivity : incumbent.floorActivity,
447
463
  reason: lateral.reason,
448
464
  estimate: lateral.estimate,
@@ -462,7 +478,7 @@ const runningRoute = (config, decision) =>
462
478
  export function canMoveUp(config, decision, effort) {
463
479
  if (config.activityRouting !== 'on' || !decision?.tier || decision.pinned) return false;
464
480
  const from = runningRoute(config, decision);
465
- return ACTIVITIES.some((a) => compareRoutes(config, resolveRoute(config, decision.tier, a), from, effort) > 0);
481
+ return ACTIVITIES.some((a) => (compareRoutes(config, resolveRoute(config, decision.tier, a), from, effort) ?? 0) > 0);
466
482
  }
467
483
 
468
484
  // A move up inside a turn: the classifier labels a turn from its prompt, and a prompt that reads as ops or explore can
@@ -476,10 +492,12 @@ export function observedMove(config, loop, { observed, facts, contextKnown, now
476
492
  if (!canMoveUp(config, decision, facts.effort) || !ACTIVITIES.includes(observed)) return loop;
477
493
  const from = runningRoute(config, decision);
478
494
  // The gates price the route that will run: the one the context fits, not the tier's first choice.
479
- const routeFor = (tier) => resolveRoute(config, tier, observed);
495
+ const routeFor = (candidate) => resolveRoute(config, candidate, observed);
480
496
  const tier = fitTier(config, decision.tier, costs.nextContextTokens(facts), routeFor);
481
497
  const to = routeFor(tier);
482
- if (!(compareRoutes(config, to, from, facts.effort) > 0)) return loop;
498
+ if ((compareRoutes(config, to, from, facts.effort) ?? 0) <= 0) return loop;
499
+ // A held-out model stays out for the rest of the turn too: routeTurn already kept the turn off it.
500
+ if (isHeld(loop, routeSpec(config, to).id, now)) return loop;
483
501
  // Without a reliable reading of the context, a smaller window might overflow, as in routeTurn.
484
502
  const window = (route) => routeSpec(config, route).contextWindow;
485
503
  if ((!contextKnown || !loop.historyMeasured) && window(to) < window(from)) return loop;
@@ -506,11 +524,11 @@ export function observedMove(config, loop, { observed, facts, contextKnown, now
506
524
  }
507
525
 
508
526
  // A tool continuation keeps the turn's route and activity; only the context, the model list, or the turn's own tool
509
- // calls (observedMove) can move it.
527
+ // calls (observedMove) can move it. A move never lands on a model held out at `now`.
510
528
  export function continueRoute(
511
529
  current,
512
530
  loop,
513
- { nativeModel, contextTokens, contextKnown, availableModels, effort, hasImages = false },
531
+ { nativeModel, contextTokens, contextKnown, availableModels, effort, hasImages = false, now },
514
532
  ) {
515
533
  if (!loop.decision) return loop;
516
534
  // A fit to another tier serves this turn only: `loop.route` stays the route of `lastRoute`, as the tier does.
@@ -522,7 +540,7 @@ export function continueRoute(
522
540
  const floor = opsFloor(current, work);
523
541
  const config = floor.config;
524
542
  const activity = work ?? decision.activity ?? null;
525
- const activityOf = (tier) => (floor.retained.includes(tier) ? 'ops' : activity);
543
+ const tierActivity = (tier) => (floor.retained.includes(tier) ? 'ops' : activity);
526
544
  if (!work && decision.floorActivity) decision = { ...decision, floorActivity: null };
527
545
  if (contextKnown && decision.tier) {
528
546
  // The route the turn runs, which a mode change or a held move can keep apart from config, stays while the context
@@ -536,7 +554,7 @@ export function continueRoute(
536
554
  decision = {
537
555
  ...decision,
538
556
  tier: fitted,
539
- activity: activityOf(fitted),
557
+ activity: tierActivity(fitted),
540
558
  route,
541
559
  model: routeSpec(config, route).id,
542
560
  effort: costs.routeEffort(config, route, effort),
@@ -551,7 +569,7 @@ export function continueRoute(
551
569
  return (
552
570
  model.imageInput !== false &&
553
571
  isModelAllowed(model.id, availableModels, nativeModel) &&
554
- !loop.ineligible.includes(model.id) &&
572
+ !withheld(loop, model.id, now) &&
555
573
  (contextKnown ? contextTokens <= model.contextWindow * CONTEXT_FILL : model.contextWindow >= runningWindow)
556
574
  );
557
575
  });
@@ -559,7 +577,7 @@ export function continueRoute(
559
577
  decision = {
560
578
  ...decision,
561
579
  tier: tier ?? null,
562
- activity: tier ? activityOf(tier) : null,
580
+ activity: tier ? tierActivity(tier) : null,
563
581
  floorActivity: tier ? work : null,
564
582
  route,
565
583
  model: route ? routeSpec(config, route).id : nativeModel,
@@ -567,7 +585,7 @@ export function continueRoute(
567
585
  reason: 'model-unavailable',
568
586
  };
569
587
  }
570
- if (!isModelAllowed(decision.model, availableModels, nativeModel) || loop.ineligible.includes(decision.model)) {
588
+ if (!isModelAllowed(decision.model, availableModels, nativeModel) || withheld(loop, decision.model, now)) {
571
589
  decision = {
572
590
  ...decision,
573
591
  tier: null,
@@ -604,8 +622,9 @@ export function observeResponse(config, loop, { usage, requestedModel, effort, s
604
622
  if (!counts.every((key) => Number.isFinite(usage[key]) && usage[key] >= 0)) return next;
605
623
  const tokens = usage.input_tokens + usage.cache_read_input_tokens + usage.cache_creation_input_tokens;
606
624
  if (tokens === 0) return next;
607
- const resolutions = sameModel ? { ...next.resolutions, [requestedModel]: usage.model } : { ...next.resolutions };
608
- if (!sameModel) delete resolutions[requestedModel];
625
+ const resolutions = sameModel
626
+ ? { ...next.resolutions, [requestedModel]: usage.model }
627
+ : Object.fromEntries(Object.entries(next.resolutions).filter(([model]) => model !== requestedModel));
609
628
  let models = next.models;
610
629
  if (next.lastRequest && tokens < next.lastRequest.tokens * HISTORY_SHRINK) models = {};
611
630
  // A substituted model's effort is not reported, so do not credit its estimated cache.
package/lib/savings.mjs CHANGED
@@ -51,7 +51,8 @@ export function requestUsd(
51
51
  cacheMode === 'disabled'
52
52
  ? rates.input * (input + cacheRead + cacheWrite)
53
53
  : rates.input * (input + cacheWrite * writeMultiplier) + rates.cacheRead * cacheRead;
54
- return (inputUsd + rates.output * output) / 1e6;
54
+ // An unknown output price leaves the request unpriced (NaN), which the callers' priced checks catch.
55
+ return (inputUsd + (rates.output ?? Number.NaN) * output) / 1e6;
55
56
  }
56
57
 
57
58
  // Actual observed counters can be priced without inventing the cache on another route.
@@ -111,6 +112,15 @@ const isCount = (n) => Number.isFinite(n) && n >= 0;
111
112
  // negative, stronger than yours when positive) and the cache the switches cost (routed against the served model on
112
113
  // your cache), never negative. The parts sum to the difference by construction. `reply` is null when a model has no
113
114
  // price or `ttl` is not a known cache lifetime.
115
+ /**
116
+ * @typedef {{ routedUsd: number, yoursUsd: number, cheaperUsd: number, strongerUsd: number, switchUsd: number }} ReplyComparison
117
+ */
118
+
119
+ /**
120
+ * @typedef {{ total: number, at: number, onYours: boolean, model: string, effort: string | null }} CacheState
121
+ */
122
+
123
+ /** @returns {{ state: CacheState | null, reply: ReplyComparison | null }} */
114
124
  export function compareReply(config, state, { usage, served, yours, ttl, now }) {
115
125
  const counts = {
116
126
  input: usage?.input_tokens,
@@ -194,6 +204,7 @@ export function unpricedCause(config, { usage, served, yours, ttl }) {
194
204
  // model: `states` and `replies` by models key, each as compareReply returns, and `reply`, the prices against `yours`,
195
205
  // the API model id /model selects now, or null.
196
206
  export function compareModels(config, states, { usage, served, effort, ttl, now, yours }) {
207
+ /** @type {{ states: Record<string, unknown>, replies: Record<string, ReplyComparison>, reply: ReplyComparison | null }} */
197
208
  const out = { states: {}, replies: {}, reply: null };
198
209
  for (const [alias, model] of Object.entries(config.models)) {
199
210
  const { state, reply } = compareReply(config, modelEntry(states, alias) ?? null, {
@@ -217,7 +228,7 @@ const SUMS = ['routedUsd', 'yoursUsd', 'cheaperUsd', 'strongerUsd', 'switchUsd']
217
228
  export function emptySavingsStore() {
218
229
  return {
219
230
  version: 1,
220
- since: null,
231
+ since: /** @type {number | null} */ (null),
221
232
  replies: 0,
222
233
  routedUsd: 0,
223
234
  yoursUsd: 0,
@@ -266,7 +277,7 @@ const cents = (usd) => Math.round(usd * 100);
266
277
  // stronger part down to 0, then the cheaper part. So no part changes sign or appears from rounding alone. `early`
267
278
  // below EARLY_REPLIES replies. `share` is the difference against yours; `ratio` routed over yours.
268
279
  export function readout(totals) {
269
- const [routed, yours, cheaper, stronger] = [
280
+ const [routed = 0, yours = 0, cheaper = 0, stronger = 0] = [
270
281
  totals.routedUsd,
271
282
  totals.yoursUsd,
272
283
  totals.cheaperUsd,
package/lib/subagents.mjs CHANGED
@@ -46,7 +46,8 @@ const OWN_MODEL_BUILTINS = ['Explore', 'Plan'];
46
46
  export function agentFrontmatter(text) {
47
47
  const match = /^---\r?\n([\s\S]*?)\r?\n---/.exec(typeof text === 'string' ? text : '');
48
48
  if (!match) return null;
49
- const block = match[1].trim();
49
+ const [, body = ''] = match;
50
+ const block = body.trim();
50
51
  const fields = {};
51
52
  if (block.startsWith('{')) {
52
53
  try {
@@ -56,8 +57,9 @@ export function agentFrontmatter(text) {
56
57
  }
57
58
  } else
58
59
  for (const line of block.split(/\r?\n/)) {
59
- const pair = /^([A-Za-z][\w-]*):\s*(.*?)\s*$/.exec(line);
60
- if (pair) fields[pair[1]] = pair[2].replace(/\s+#.*$/, '').replace(/^(['"])(.*)\1$/, '$2');
60
+ const [, key, value] = /^([A-Za-z][\w-]*):\s*(.*?)\s*$/.exec(line) ?? [];
61
+ if (key !== undefined && value !== undefined)
62
+ fields[key] = value.replace(/\s+#.*$/, '').replace(/^(['"])(.*)\1$/, '$2');
61
63
  }
62
64
  const text_ = (value) => (typeof value === 'string' && value ? value : null);
63
65
  return { name: text_(fields.name), model: text_(fields.model), modelRouting: text_(fields.modelRouting) };
@@ -73,11 +75,15 @@ const pluginOf = (spawn) => {
73
75
  return typeof provider === 'string' ? provider.split('@')[0] : null;
74
76
  };
75
77
 
78
+ const WORKFLOW_TYPE = 'workflow-subagent';
79
+
76
80
  // What router.json lists for this spawn's type: a models key, CLASSIFY or null, or undefined when it does not list
77
81
  // it. A key without a colon names a built-in, so it matches only the engine's own agent; a `plugin:name` key matches
78
82
  // only that plugin's agent (provider `plugin@marketplace`).
79
83
  function listedRoute(config, spawn) {
80
84
  const { types } = config.subagents;
85
+ // A workflow agent's own type does not apply to it: it is always the engine's workflow-subagent.
86
+ if (spawn.workflow) return Object.hasOwn(types, WORKFLOW_TYPE) ? types[WORKFLOW_TYPE] : undefined;
81
87
  const type = spawn.subagentType;
82
88
  if (typeof type !== 'string' || !Object.hasOwn(types, type)) return undefined;
83
89
  const owner = type.includes(':') ? type.slice(0, type.indexOf(':')) : 'engine';
@@ -97,15 +103,17 @@ export function typeRoute(config, spawn, definition = null) {
97
103
  }
98
104
 
99
105
  // The reason a spawn keeps the model core gives it, or null when the router may choose one. A fork reads the parent's
100
- // cache on the parent's model; `model` is the Agent call's own choice; a teammate and a workflow agent are not
101
- // rewritable (a workflow agent's model rewrite is ignored, experiments/mod-router/results/agent-spawn-probe.json).
106
+ // cache on the parent's model; `model` is the Agent call's own choice; a teammate is not rewritable. A workflow agent's
107
+ // model rewrite applies (2.1.321, checked live), but its type is not one the router knows, so it is routed only where
108
+ // router.json lists `workflow-subagent`, and a workflow `agent({ model })` is the script's own choice.
102
109
  export function passReason(config, spawn, definition = null) {
103
110
  if (spawn.fork) return 'fork';
104
111
  // Before `explicit`: a workflow agent({ model }) arrives with `model` set, and counts as a workflow agent.
105
- if (spawn.workflow) return 'workflow';
112
+ if (spawn.workflow && (spawn.model || listedRoute(config, spawn) === undefined)) return 'workflow';
106
113
  if (spawn.model) return 'explicit';
107
114
  if (spawn.isTeammate) return 'teammate';
108
- return typeRoute(config, spawn, definition).pass ?? null;
115
+ const route = typeRoute(config, spawn, definition);
116
+ return 'pass' in route ? route.pass : null;
109
117
  }
110
118
 
111
119
  // The task text the classifier sees: the description and the prompt the parent wrote, clipped like a main turn's
@@ -129,7 +137,15 @@ export function classifiedAlias(config, advice) {
129
137
  // CLAUDE_CODE_SUBAGENT_MODEL, except for the
130
138
  // built-ins that ignore it without CLAUDE_CODE_SUBAGENT_MODEL_FORCE, else the parent's model. An estimate: it does not
131
139
  // apply the family-alias rule or the availableModels substitution.
132
- export function coreModelOf(config, spawn, { envModel = null, force = false, definition = null } = {}) {
140
+ export function coreModelOf(
141
+ config,
142
+ spawn,
143
+ {
144
+ envModel = /** @type {string | null} */ (null),
145
+ force = false,
146
+ definition = /** @type {{ model?: string } | null} */ (null),
147
+ } = {},
148
+ ) {
133
149
  const idOf = (model) => (Object.hasOwn(config.models, model) ? config.models[model].id : model);
134
150
  const pinned = definition?.model && definition.model !== 'inherit' ? definition.model : null;
135
151
  if (pinned && !(force && envModel)) return idOf(pinned);
@@ -150,7 +166,17 @@ export function moveOf(config, routedModel, coreModel) {
150
166
  // PASS_REASONS entry or null. `choice` is the models key decided, or 'core' when the decision kept core's model.
151
167
  // `move` is moveOf the routed model against core's. `actualUsd` prices each reply on the model it ran on; `otherUsd`
152
168
  // the same tokens on core's estimated model, none for a pass-through.
153
- export function spawnRecord({ sessionId, spawn, pass, choice, routedModel, coreModel, move = null, failed, respawn }) {
169
+ export function spawnRecord({
170
+ sessionId,
171
+ spawn,
172
+ pass,
173
+ choice,
174
+ routedModel,
175
+ coreModel,
176
+ move = /** @type {string | null} */ (null),
177
+ failed,
178
+ respawn,
179
+ }) {
154
180
  return {
155
181
  sessionId,
156
182
  type: spawn.subagentType,
@@ -199,6 +225,9 @@ export function addAgentReply(config, agent, usage, ttl, at) {
199
225
  // and their cost (`models`); a routed model also counts the agents the router moved onto it, `up` or `down` from
200
226
  // core's, and core's estimated cost of the same tokens. A version 1 record, from before 1.14.0, has neither days nor
201
227
  // models: it reads as `undated` totals, which only the periods without a range (session and all) count.
228
+ /** @typedef {{ version: number, since: number | null, days: Record<string, ReturnType<typeof emptySubagentDay>>, undated?: Record<string, number> }} SubagentStore */
229
+
230
+ /** @returns {SubagentStore} */
202
231
  export function emptySubagentStore() {
203
232
  return { version: 2, since: null, days: {} };
204
233
  }
@@ -255,8 +284,8 @@ export function recordAgent(store, agent, now) {
255
284
  put(day[kind], key, counts);
256
285
  days[dayKey(now)] = day;
257
286
  const cutoff = daysBefore(now, RETAIN_DAYS);
258
- for (const old of Object.keys(days)) if (old < cutoff) delete days[old];
259
- return { version: 2, since: store.since ?? now, days, ...(store.undated ? { undated: store.undated } : {}) };
287
+ const kept = Object.fromEntries(Object.entries(days).filter(([date]) => date >= cutoff));
288
+ return { version: 2, since: store.since ?? now, days: kept, ...(store.undated ? { undated: store.undated } : {}) };
260
289
  }
261
290
 
262
291
  // The record after a flush: counted once, nothing pending.
@@ -313,6 +342,7 @@ function undatedOf(value) {
313
342
 
314
343
  // The stored value with its well-formed days and entries, else an empty store: a missing, hand-edited or unknown value
315
344
  // must not break a turn or the pane.
345
+ /** @returns {SubagentStore} */
316
346
  export function readSubagentStore(value) {
317
347
  if (!isRecord(value) || !(value.since === null || Number.isFinite(value.since))) return emptySubagentStore();
318
348
  if (value.version === 1) {
@@ -0,0 +1,60 @@
1
+ // The words `/router` takes: one table that the command, its argument hint and the prompt's typeahead all read, so a
2
+ // word added in one place cannot be missing in another. The handlers sit beside the command in the hook; a test runs
3
+ // the command with every word and value here.
4
+ import { ACTIVITY_MODES, ROUTING_MODES, TIERS } from './config.mjs';
5
+ import { LINE_MODES } from './route-line.mjs';
6
+
7
+ /**
8
+ * @typedef {object} Subcommand
9
+ * @property {string} name
10
+ * @property {string} description one line, drawn beside the word in the typeahead
11
+ * @property {string[]} [values] what may follow the word; the typeahead offers each
12
+ * @property {string} [hint] how the argument hint spells what follows the word; the values when absent
13
+ */
14
+
15
+ /** @type {readonly Subcommand[]} */
16
+ export const SUBCOMMANDS = [
17
+ { name: 'auto', description: 'Routing on' },
18
+ { name: 'off', description: 'Routing off: Claude’s model is kept' },
19
+ { name: 'pin', description: 'Pin the next turn to a tier', values: TIERS, hint: '<tier>' },
20
+ { name: 'mode', description: 'Routing mode', values: [...ROUTING_MODES, 'default'], hint: '<mode>' },
21
+ { name: 'activities', description: 'Activity routing', values: ACTIVITY_MODES },
22
+ { name: 'line', description: 'The route line after a turn', values: LINE_MODES },
23
+ { name: 'decisions', description: 'The last routing decisions', hint: '[n]' },
24
+ { name: 'trace', description: 'Export the shadow traces', values: ['export'], hint: 'export' },
25
+ ];
26
+
27
+ const slot = (sub) => sub.hint ?? (sub.values ? `<${sub.values.join('|')}>` : undefined);
28
+
29
+ /** The command's argument hint: `[auto|off|pin <tier>|…|activities <off|on>|…]`. */
30
+ export const argumentHint = () =>
31
+ `[${SUBCOMMANDS.map((sub) => (slot(sub) ? `${sub.name} ${slot(sub)}` : sub.name)).join('|')}]`;
32
+
33
+ // A word is taken as its token followed by a space where more is expected, so the box asks again for the value.
34
+ const takes = (sub) => Boolean(sub.values?.length);
35
+
36
+ /**
37
+ * The typeahead rows for the token at the cursor: the words after `/router `, or the values after a word that takes
38
+ * them. Nothing when the token is not in an argument of `/router`, or nothing matches.
39
+ * @param {{ text: string, start: number, token: string }} input
40
+ * @param {{ describe?: (name: string, value: string) => string | undefined }} [options]
41
+ * @returns {{ text: string, label?: string, description?: string }[]}
42
+ */
43
+ export function routerSuggestions({ text, start, token }, { describe } = {}) {
44
+ const lead = text.slice(0, start).match(/^\/router\s+(?:(\S+)\s+)?$/);
45
+ if (!lead) return [];
46
+ const typed = token.toLowerCase();
47
+ const matching = (candidate) => candidate.toLowerCase().startsWith(typed);
48
+ if (!lead[1])
49
+ return SUBCOMMANDS.filter((sub) => matching(sub.name)).map((sub) => ({
50
+ text: takes(sub) ? `${sub.name} ` : sub.name,
51
+ label: slot(sub) ? `${sub.name} ${slot(sub)}` : sub.name,
52
+ description: sub.description,
53
+ }));
54
+ const word = SUBCOMMANDS.find((item) => item.name === lead[1]);
55
+ if (!word) return [];
56
+ return (word.values ?? []).filter(matching).map((value) => {
57
+ const description = describe?.(word.name, value);
58
+ return { text: value, label: value, ...(description ? { description } : {}) };
59
+ });
60
+ }
@@ -0,0 +1,22 @@
1
+ import { isGraphical } from './tokens.mjs';
2
+
3
+ /**
4
+ * Draws with `draw(surface)`. On a graphical surface with an `onFallback`, a throw is handed to it and the terminal
5
+ * tree is drawn instead, which is what those surfaces drew before the graphical renderers. With no `onFallback` the
6
+ * throw propagates, so a broken graphical renderer cannot pass as the terminal tree. The terminal's own throw is never
7
+ * caught: there is nothing under it.
8
+ * @template T
9
+ * @param {string | undefined} surface
10
+ * @param {(surface: string | undefined) => T} draw
11
+ * @param {((error: unknown) => void) | undefined} onFallback
12
+ * @returns {T}
13
+ */
14
+ export function orTerminal(surface, draw, onFallback) {
15
+ if (!isGraphical(surface) || !onFallback) return draw(surface);
16
+ try {
17
+ return draw(surface);
18
+ } catch (error) {
19
+ onFallback(error);
20
+ return draw('terminal');
21
+ }
22
+ }