@alexeiled/claude-router 1.24.0 → 1.25.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.
Files changed (78) hide show
  1. package/.claude-plugin/plugin.json +1 -1
  2. package/CHANGELOG.md +44 -0
  3. package/README.md +39 -7
  4. package/docs/architecture.md +27 -4
  5. package/docs/configuration.md +23 -14
  6. package/docs/evaluation.md +3 -3
  7. package/docs/native-router.md +11 -3
  8. package/docs/router-band.svg +124 -133
  9. package/docs/router-pane-classifier.svg +24 -23
  10. package/docs/router-pane-now.svg +9 -7
  11. package/docs/router-pane-policy.svg +4 -4
  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 +70 -17
  17. package/hooks/native-router.mjs +333 -80
  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 +69 -20
  30. package/lib/facts.mjs +3 -0
  31. package/lib/modes.mjs +8 -4
  32. package/lib/panel.mjs +75 -2167
  33. package/lib/policy.mjs +7 -6
  34. package/lib/replay-trace.mjs +5 -2
  35. package/lib/replay.mjs +7 -1
  36. package/lib/route-line.mjs +46 -0
  37. package/lib/route.mjs +21 -16
  38. package/lib/savings.mjs +14 -3
  39. package/lib/subagents.mjs +41 -11
  40. package/lib/subcommands.mjs +60 -0
  41. package/lib/ui/fallback.mjs +22 -0
  42. package/lib/ui/graphical/band.mjs +256 -0
  43. package/lib/ui/graphical/charts.mjs +163 -0
  44. package/lib/ui/graphical/classifier.mjs +153 -0
  45. package/lib/ui/graphical/frame.mjs +227 -0
  46. package/lib/ui/graphical/kit.mjs +156 -0
  47. package/lib/ui/graphical/meter.mjs +25 -0
  48. package/lib/ui/graphical/now.mjs +353 -0
  49. package/lib/ui/graphical/policy.mjs +56 -0
  50. package/lib/ui/graphical/routes.mjs +264 -0
  51. package/lib/ui/graphical/squares.mjs +29 -0
  52. package/lib/ui/graphical/usage.mjs +376 -0
  53. package/lib/ui/model/band.mjs +439 -0
  54. package/lib/ui/model/classifier.mjs +308 -0
  55. package/lib/ui/model/draft.mjs +62 -0
  56. package/lib/ui/model/format.mjs +41 -0
  57. package/lib/ui/model/frame.mjs +359 -0
  58. package/lib/ui/model/now.mjs +390 -0
  59. package/lib/ui/model/policy.mjs +194 -0
  60. package/lib/ui/model/routes.mjs +392 -0
  61. package/lib/ui/model/usage-agents.mjs +311 -0
  62. package/lib/ui/model/usage-breakdown.mjs +237 -0
  63. package/lib/ui/model/usage-shared.mjs +58 -0
  64. package/lib/ui/model/usage.mjs +330 -0
  65. package/lib/ui/terminal/band.mjs +220 -0
  66. package/lib/ui/terminal/classifier.mjs +142 -0
  67. package/lib/ui/terminal/frame.mjs +169 -0
  68. package/lib/ui/terminal/kit.mjs +133 -0
  69. package/lib/ui/terminal/now.mjs +300 -0
  70. package/lib/ui/terminal/policy.mjs +52 -0
  71. package/lib/ui/terminal/routes.mjs +167 -0
  72. package/lib/ui/terminal/usage.mjs +363 -0
  73. package/lib/ui/terminal/wrap.mjs +37 -0
  74. package/lib/ui/tokens.mjs +106 -0
  75. package/lib/usage.mjs +5 -5
  76. package/lib/view.mjs +5 -2
  77. package/package.json +3 -2
  78. package/types/index.d.ts +15 -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
@@ -38,8 +38,8 @@ export function isNativeFallback(loop, model) {
38
38
  // The tier and activity whose route runs model `id`, or null when no route names it. Base routes first, baseline
39
39
  // first; activity overrides only when they apply, with `activityRouting: on`.
40
40
  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);
41
+ const order = [config.baselineTier, ...TIERS.filter((other) => other !== config.baselineTier)];
42
+ const runs = (candidate, kind) => isSameModel(routeSpec(config, resolveRoute(config, candidate, kind)).id, id);
43
43
  const tier = order.find((t) => runs(t, null));
44
44
  if (tier) return { tier, activity: null };
45
45
  if (config.activityRouting !== 'on') return null;
@@ -219,7 +219,7 @@ function opsFloor(config, activity) {
219
219
  for (const tier of TIERS) {
220
220
  if (declared[activity]?.[tier]) continue;
221
221
  const ops = resolveRoute(config, tier, 'ops');
222
- if (!(compareRoutes(config, resolveRoute(config, tier, activity), ops) < 0)) continue;
222
+ if ((compareRoutes(config, resolveRoute(config, tier, activity), ops) ?? 0) >= 0) continue;
223
223
  cells[tier] = ops;
224
224
  retained.push(tier);
225
225
  }
@@ -247,8 +247,8 @@ function routeTurn(config, loop, { facts, advice, pin, nativeModel, contextKnown
247
247
  // The incumbent runs the route in use, not the one config gives its cell now. It is rebuilt from config for a loop
248
248
  // 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
249
  // 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;
250
+ const usable = (held) => {
251
+ const model = Object.hasOwn(config.models, held.model) ? config.models[held.model] : null;
252
252
  return Boolean(
253
253
  model && isModelAllowed(model.id, availableModels, nativeModel) && !loop.ineligible.includes(model.id),
254
254
  );
@@ -320,6 +320,7 @@ function routeTurn(config, loop, { facts, advice, pin, nativeModel, contextKnown
320
320
  const route = result.tier ? routeOf(result) : null;
321
321
  const model = route ? routeSpec(config, route).id : nativeModel;
322
322
  const effort = route ? costs.routeEffort(config, route, facts.effort) : facts.effort;
323
+ /** @type {object | null} */
323
324
  let comparison = null;
324
325
  const candidate = pin ?? advice?.choice;
325
326
  if (contextKnown && loop.lastRequest && TIERS.includes(candidate) && candidate !== loop.lastRoute) {
@@ -396,7 +397,10 @@ function decideCell({
396
397
  // order against it: after a mode change the next tier's route can be the weaker one.
397
398
  const escalates = (t) => {
398
399
  const order = compareRoutes(config, routeFor(t), incumbent.route, facts.effort);
399
- return order > 0 || (order === null && !sameRequest(config, routeFor(t), incumbent.route, facts.effort));
400
+ return (
401
+ (order !== null && order > 0) ||
402
+ (order === null && !sameRequest(config, routeFor(t), incumbent.route, facts.effort))
403
+ );
400
404
  };
401
405
  const escalateTo = (tier) => TIERS.slice(rank(tier) + 1).find(escalates) ?? null;
402
406
  const step = decide({
@@ -439,10 +443,10 @@ function decideCell({
439
443
  now,
440
444
  costs,
441
445
  });
442
- const activityOf = lateral.move ? activity : incumbent.activity;
446
+ const routedActivity = lateral.move ? activity : incumbent.activity;
443
447
  return {
444
448
  ...step,
445
- activity: activityOf,
449
+ activity: routedActivity,
446
450
  floorActivity: lateral.move ? floorActivity : incumbent.floorActivity,
447
451
  reason: lateral.reason,
448
452
  estimate: lateral.estimate,
@@ -462,7 +466,7 @@ const runningRoute = (config, decision) =>
462
466
  export function canMoveUp(config, decision, effort) {
463
467
  if (config.activityRouting !== 'on' || !decision?.tier || decision.pinned) return false;
464
468
  const from = runningRoute(config, decision);
465
- return ACTIVITIES.some((a) => compareRoutes(config, resolveRoute(config, decision.tier, a), from, effort) > 0);
469
+ return ACTIVITIES.some((a) => (compareRoutes(config, resolveRoute(config, decision.tier, a), from, effort) ?? 0) > 0);
466
470
  }
467
471
 
468
472
  // 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 +480,10 @@ export function observedMove(config, loop, { observed, facts, contextKnown, now
476
480
  if (!canMoveUp(config, decision, facts.effort) || !ACTIVITIES.includes(observed)) return loop;
477
481
  const from = runningRoute(config, decision);
478
482
  // 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);
483
+ const routeFor = (candidate) => resolveRoute(config, candidate, observed);
480
484
  const tier = fitTier(config, decision.tier, costs.nextContextTokens(facts), routeFor);
481
485
  const to = routeFor(tier);
482
- if (!(compareRoutes(config, to, from, facts.effort) > 0)) return loop;
486
+ if ((compareRoutes(config, to, from, facts.effort) ?? 0) <= 0) return loop;
483
487
  // Without a reliable reading of the context, a smaller window might overflow, as in routeTurn.
484
488
  const window = (route) => routeSpec(config, route).contextWindow;
485
489
  if ((!contextKnown || !loop.historyMeasured) && window(to) < window(from)) return loop;
@@ -522,7 +526,7 @@ export function continueRoute(
522
526
  const floor = opsFloor(current, work);
523
527
  const config = floor.config;
524
528
  const activity = work ?? decision.activity ?? null;
525
- const activityOf = (tier) => (floor.retained.includes(tier) ? 'ops' : activity);
529
+ const tierActivity = (tier) => (floor.retained.includes(tier) ? 'ops' : activity);
526
530
  if (!work && decision.floorActivity) decision = { ...decision, floorActivity: null };
527
531
  if (contextKnown && decision.tier) {
528
532
  // The route the turn runs, which a mode change or a held move can keep apart from config, stays while the context
@@ -536,7 +540,7 @@ export function continueRoute(
536
540
  decision = {
537
541
  ...decision,
538
542
  tier: fitted,
539
- activity: activityOf(fitted),
543
+ activity: tierActivity(fitted),
540
544
  route,
541
545
  model: routeSpec(config, route).id,
542
546
  effort: costs.routeEffort(config, route, effort),
@@ -559,7 +563,7 @@ export function continueRoute(
559
563
  decision = {
560
564
  ...decision,
561
565
  tier: tier ?? null,
562
- activity: tier ? activityOf(tier) : null,
566
+ activity: tier ? tierActivity(tier) : null,
563
567
  floorActivity: tier ? work : null,
564
568
  route,
565
569
  model: route ? routeSpec(config, route).id : nativeModel,
@@ -604,8 +608,9 @@ export function observeResponse(config, loop, { usage, requestedModel, effort, s
604
608
  if (!counts.every((key) => Number.isFinite(usage[key]) && usage[key] >= 0)) return next;
605
609
  const tokens = usage.input_tokens + usage.cache_read_input_tokens + usage.cache_creation_input_tokens;
606
610
  if (tokens === 0) return next;
607
- const resolutions = sameModel ? { ...next.resolutions, [requestedModel]: usage.model } : { ...next.resolutions };
608
- if (!sameModel) delete resolutions[requestedModel];
611
+ const resolutions = sameModel
612
+ ? { ...next.resolutions, [requestedModel]: usage.model }
613
+ : Object.fromEntries(Object.entries(next.resolutions).filter(([model]) => model !== requestedModel));
609
614
  let models = next.models;
610
615
  if (next.lastRequest && tokens < next.lastRequest.tokens * HISTORY_SHRINK) models = {};
611
616
  // 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
+ }