@alexeiled/claude-router 1.23.1 → 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 (81) hide show
  1. package/.claude-plugin/plugin.json +1 -1
  2. package/CHANGELOG.md +62 -1
  3. package/README.md +39 -7
  4. package/docs/architecture.md +27 -4
  5. package/docs/auto-engine.md +152 -0
  6. package/docs/configuration.md +47 -3
  7. package/docs/evaluation.md +222 -3
  8. package/docs/native-router.md +11 -3
  9. package/docs/providers.md +28 -0
  10. package/docs/router-band.svg +124 -133
  11. package/docs/router-pane-classifier.svg +24 -23
  12. package/docs/router-pane-now.svg +9 -7
  13. package/docs/router-pane-policy.svg +4 -4
  14. package/docs/router-pane-routes.svg +8 -8
  15. package/docs/router-pane-usage-whatif.svg +14 -14
  16. package/docs/router-pane-usage.svg +20 -20
  17. package/docs/routing-modes.md +13 -4
  18. package/docs/user-guide.md +79 -19
  19. package/hooks/native-router.mjs +1194 -215
  20. package/lib/activity-stats.mjs +23 -4
  21. package/lib/activity.mjs +7 -5
  22. package/lib/auto-engine.mjs +414 -0
  23. package/lib/auto-route.mjs +253 -0
  24. package/lib/band.mjs +35 -440
  25. package/lib/classifier-client.mjs +12 -8
  26. package/lib/config-file.mjs +7 -2
  27. package/lib/config.mjs +64 -15
  28. package/lib/cost.mjs +5 -1
  29. package/lib/costs.mjs +4 -2
  30. package/lib/decisions.mjs +80 -5
  31. package/lib/display.mjs +69 -20
  32. package/lib/facts.mjs +30 -0
  33. package/lib/modes.mjs +8 -4
  34. package/lib/panel.mjs +75 -2163
  35. package/lib/policy.mjs +7 -6
  36. package/lib/providers.mjs +7 -0
  37. package/lib/replay-trace.mjs +550 -0
  38. package/lib/replay.mjs +718 -0
  39. package/lib/route-line.mjs +46 -0
  40. package/lib/route.mjs +35 -21
  41. package/lib/savings.mjs +14 -3
  42. package/lib/subagents.mjs +41 -11
  43. package/lib/subcommands.mjs +60 -0
  44. package/lib/ui/fallback.mjs +22 -0
  45. package/lib/ui/graphical/band.mjs +256 -0
  46. package/lib/ui/graphical/charts.mjs +163 -0
  47. package/lib/ui/graphical/classifier.mjs +153 -0
  48. package/lib/ui/graphical/frame.mjs +227 -0
  49. package/lib/ui/graphical/kit.mjs +156 -0
  50. package/lib/ui/graphical/meter.mjs +25 -0
  51. package/lib/ui/graphical/now.mjs +353 -0
  52. package/lib/ui/graphical/policy.mjs +56 -0
  53. package/lib/ui/graphical/routes.mjs +264 -0
  54. package/lib/ui/graphical/squares.mjs +29 -0
  55. package/lib/ui/graphical/usage.mjs +376 -0
  56. package/lib/ui/model/band.mjs +439 -0
  57. package/lib/ui/model/classifier.mjs +308 -0
  58. package/lib/ui/model/draft.mjs +62 -0
  59. package/lib/ui/model/format.mjs +41 -0
  60. package/lib/ui/model/frame.mjs +359 -0
  61. package/lib/ui/model/now.mjs +390 -0
  62. package/lib/ui/model/policy.mjs +194 -0
  63. package/lib/ui/model/routes.mjs +392 -0
  64. package/lib/ui/model/usage-agents.mjs +311 -0
  65. package/lib/ui/model/usage-breakdown.mjs +237 -0
  66. package/lib/ui/model/usage-shared.mjs +58 -0
  67. package/lib/ui/model/usage.mjs +330 -0
  68. package/lib/ui/terminal/band.mjs +220 -0
  69. package/lib/ui/terminal/classifier.mjs +142 -0
  70. package/lib/ui/terminal/frame.mjs +169 -0
  71. package/lib/ui/terminal/kit.mjs +133 -0
  72. package/lib/ui/terminal/now.mjs +300 -0
  73. package/lib/ui/terminal/policy.mjs +52 -0
  74. package/lib/ui/terminal/routes.mjs +167 -0
  75. package/lib/ui/terminal/usage.mjs +363 -0
  76. package/lib/ui/terminal/wrap.mjs +37 -0
  77. package/lib/ui/tokens.mjs +106 -0
  78. package/lib/usage.mjs +5 -5
  79. package/lib/view.mjs +5 -2
  80. package/package.json +3 -2
  81. package/types/index.d.ts +15 -0
@@ -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;
@@ -58,7 +58,7 @@ export function ownRoute(config, model) {
58
58
  }
59
59
 
60
60
  export function emptyLoop(config, model) {
61
- const cell = cellForModel(config, model);
61
+ const cell = config.routingEngine === 'auto' ? null : cellForModel(config, model);
62
62
  return {
63
63
  lastRoute: cell?.tier ?? config.baselineTier,
64
64
  lastActivity: cell?.activity ?? null,
@@ -66,7 +66,7 @@ export function emptyLoop(config, model) {
66
66
  // a route edit changes the config, never the route in use. Null until the first decision, except on a session
67
67
  // model no route names (ownRoute): it starts at the baseline tier but keeps running until a decision moves it.
68
68
  // Taken as the baseline's route, repeated failures on it "escalated" to a weaker model.
69
- route: ownRoute(config, model),
69
+ route: config.routingEngine === 'auto' ? null : ownRoute(config, model),
70
70
  state: initialState(),
71
71
  models: {},
72
72
  resolutions: {},
@@ -74,6 +74,7 @@ export function emptyLoop(config, model) {
74
74
  historyMeasured: false,
75
75
  lastMessageCount: null,
76
76
  generation: 0,
77
+ hasRoutedDecision: false,
77
78
  turnId: null,
78
79
  decision: null,
79
80
  ineligible: [],
@@ -109,14 +110,21 @@ export function resetHistory(loop) {
109
110
  };
110
111
  }
111
112
 
113
+ // Legacy physical observations cannot prove a manual-only prefix. Never regrant startup on ambiguous history.
114
+ export const hasRoutedDecision = (loop) =>
115
+ typeof loop.hasRoutedDecision === 'boolean'
116
+ ? loop.hasRoutedDecision
117
+ : Boolean(loop.decision || loop.auto || loop.requests > 0);
118
+
112
119
  export function prepareLoop(loop, messageCount) {
120
+ const prepared = { ...loop, hasRoutedDecision: hasRoutedDecision(loop) };
113
121
  if (loop.lastMessageCount === null || messageCount >= loop.lastMessageCount)
114
- return { ...loop, lastMessageCount: messageCount };
122
+ return { ...prepared, lastMessageCount: messageCount };
115
123
  // Compaction or a rewind shortened the history: message cursors past its end move to it, so checks and edits made
116
124
  // from here on count. The request-based dwell is kept.
117
125
  const cursor = (count) => Math.min(count ?? 0, messageCount);
118
126
  return {
119
- ...resetHistory(loop),
127
+ ...resetHistory(prepared),
120
128
  lastMessageCount: messageCount,
121
129
  switchedAt: loop.switchedAt && { ...loop.switchedAt, messageCount: cursor(loop.switchedAt.messageCount) },
122
130
  observedFrom: cursor(loop.observedFrom),
@@ -160,7 +168,7 @@ export function isModelAllowed(requested, allowed, native) {
160
168
  );
161
169
  }
162
170
 
163
- function economicConfig(config, loop) {
171
+ export function economicConfig(config, loop) {
164
172
  const models = Object.fromEntries(
165
173
  Object.entries(config.models).map(([alias, model]) => [
166
174
  alias,
@@ -185,6 +193,7 @@ export function chooseRoute(config, loop, input) {
185
193
  return {
186
194
  ...loop,
187
195
  state: applied.state,
196
+ hasRoutedDecision: true,
188
197
  lastRoute: kept ? loop.lastRoute : applied.tier,
189
198
  lastActivity: kept ? activityOf(config, loop) : applied.activity,
190
199
  route: kept ? (loop.route ?? null) : applied.route,
@@ -210,7 +219,7 @@ function opsFloor(config, activity) {
210
219
  for (const tier of TIERS) {
211
220
  if (declared[activity]?.[tier]) continue;
212
221
  const ops = resolveRoute(config, tier, 'ops');
213
- if (!(compareRoutes(config, resolveRoute(config, tier, activity), ops) < 0)) continue;
222
+ if ((compareRoutes(config, resolveRoute(config, tier, activity), ops) ?? 0) >= 0) continue;
214
223
  cells[tier] = ops;
215
224
  retained.push(tier);
216
225
  }
@@ -238,8 +247,8 @@ function routeTurn(config, loop, { facts, advice, pin, nativeModel, contextKnown
238
247
  // The incumbent runs the route in use, not the one config gives its cell now. It is rebuilt from config for a loop
239
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
240
249
  // no longer applies (activity routing turned off).
241
- const usable = (route) => {
242
- 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;
243
252
  return Boolean(
244
253
  model && isModelAllowed(model.id, availableModels, nativeModel) && !loop.ineligible.includes(model.id),
245
254
  );
@@ -311,6 +320,7 @@ function routeTurn(config, loop, { facts, advice, pin, nativeModel, contextKnown
311
320
  const route = result.tier ? routeOf(result) : null;
312
321
  const model = route ? routeSpec(config, route).id : nativeModel;
313
322
  const effort = route ? costs.routeEffort(config, route, facts.effort) : facts.effort;
323
+ /** @type {object | null} */
314
324
  let comparison = null;
315
325
  const candidate = pin ?? advice?.choice;
316
326
  if (contextKnown && loop.lastRequest && TIERS.includes(candidate) && candidate !== loop.lastRoute) {
@@ -387,7 +397,10 @@ function decideCell({
387
397
  // order against it: after a mode change the next tier's route can be the weaker one.
388
398
  const escalates = (t) => {
389
399
  const order = compareRoutes(config, routeFor(t), incumbent.route, facts.effort);
390
- 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
+ );
391
404
  };
392
405
  const escalateTo = (tier) => TIERS.slice(rank(tier) + 1).find(escalates) ?? null;
393
406
  const step = decide({
@@ -430,10 +443,10 @@ function decideCell({
430
443
  now,
431
444
  costs,
432
445
  });
433
- const activityOf = lateral.move ? activity : incumbent.activity;
446
+ const routedActivity = lateral.move ? activity : incumbent.activity;
434
447
  return {
435
448
  ...step,
436
- activity: activityOf,
449
+ activity: routedActivity,
437
450
  floorActivity: lateral.move ? floorActivity : incumbent.floorActivity,
438
451
  reason: lateral.reason,
439
452
  estimate: lateral.estimate,
@@ -453,7 +466,7 @@ const runningRoute = (config, decision) =>
453
466
  export function canMoveUp(config, decision, effort) {
454
467
  if (config.activityRouting !== 'on' || !decision?.tier || decision.pinned) return false;
455
468
  const from = runningRoute(config, decision);
456
- 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);
457
470
  }
458
471
 
459
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
@@ -467,10 +480,10 @@ export function observedMove(config, loop, { observed, facts, contextKnown, now
467
480
  if (!canMoveUp(config, decision, facts.effort) || !ACTIVITIES.includes(observed)) return loop;
468
481
  const from = runningRoute(config, decision);
469
482
  // The gates price the route that will run: the one the context fits, not the tier's first choice.
470
- const routeFor = (tier) => resolveRoute(config, tier, observed);
483
+ const routeFor = (candidate) => resolveRoute(config, candidate, observed);
471
484
  const tier = fitTier(config, decision.tier, costs.nextContextTokens(facts), routeFor);
472
485
  const to = routeFor(tier);
473
- if (!(compareRoutes(config, to, from, facts.effort) > 0)) return loop;
486
+ if ((compareRoutes(config, to, from, facts.effort) ?? 0) <= 0) return loop;
474
487
  // Without a reliable reading of the context, a smaller window might overflow, as in routeTurn.
475
488
  const window = (route) => routeSpec(config, route).contextWindow;
476
489
  if ((!contextKnown || !loop.historyMeasured) && window(to) < window(from)) return loop;
@@ -513,7 +526,7 @@ export function continueRoute(
513
526
  const floor = opsFloor(current, work);
514
527
  const config = floor.config;
515
528
  const activity = work ?? decision.activity ?? null;
516
- const activityOf = (tier) => (floor.retained.includes(tier) ? 'ops' : activity);
529
+ const tierActivity = (tier) => (floor.retained.includes(tier) ? 'ops' : activity);
517
530
  if (!work && decision.floorActivity) decision = { ...decision, floorActivity: null };
518
531
  if (contextKnown && decision.tier) {
519
532
  // The route the turn runs, which a mode change or a held move can keep apart from config, stays while the context
@@ -527,7 +540,7 @@ export function continueRoute(
527
540
  decision = {
528
541
  ...decision,
529
542
  tier: fitted,
530
- activity: activityOf(fitted),
543
+ activity: tierActivity(fitted),
531
544
  route,
532
545
  model: routeSpec(config, route).id,
533
546
  effort: costs.routeEffort(config, route, effort),
@@ -550,7 +563,7 @@ export function continueRoute(
550
563
  decision = {
551
564
  ...decision,
552
565
  tier: tier ?? null,
553
- activity: tier ? activityOf(tier) : null,
566
+ activity: tier ? tierActivity(tier) : null,
554
567
  floorActivity: tier ? work : null,
555
568
  route,
556
569
  model: route ? routeSpec(config, route).id : nativeModel,
@@ -595,8 +608,9 @@ export function observeResponse(config, loop, { usage, requestedModel, effort, s
595
608
  if (!counts.every((key) => Number.isFinite(usage[key]) && usage[key] >= 0)) return next;
596
609
  const tokens = usage.input_tokens + usage.cache_read_input_tokens + usage.cache_creation_input_tokens;
597
610
  if (tokens === 0) return next;
598
- const resolutions = sameModel ? { ...next.resolutions, [requestedModel]: usage.model } : { ...next.resolutions };
599
- 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));
600
614
  let models = next.models;
601
615
  if (next.lastRequest && tokens < next.lastRequest.tokens * HISTORY_SHRINK) models = {};
602
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
+ }