@alexeiled/claude-router 1.14.0 → 1.16.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -31,16 +31,36 @@ import {
31
31
  effectiveRoutes,
32
32
  loadConfig,
33
33
  MIGRATION_HINT,
34
+ ROUTING_MODES,
34
35
  supportedVersion,
35
36
  TIERS,
36
37
  tuningOf,
37
38
  withActivities,
38
39
  withClassifier,
39
40
  withClassifierTimeout,
41
+ withMode,
40
42
  withRoutes,
41
43
  withTuning,
42
44
  } from '../lib/config.mjs';
43
45
  import { changedLeaves, notSaved, restored, rewrittenConfig } from '../lib/config-file.mjs';
46
+ import {
47
+ addTurnRow,
48
+ appendDecisions,
49
+ DECISIONS_PREFIX,
50
+ decisionLines,
51
+ decisionRow,
52
+ decisionsAfterReset,
53
+ endRow,
54
+ isGoalOrigin,
55
+ isProgressOrigin,
56
+ MAX_ROWS,
57
+ originKind,
58
+ progressInput,
59
+ prunedDecisions,
60
+ queueOrigin,
61
+ readDecisions,
62
+ takeOrigin,
63
+ } from '../lib/decisions.mjs';
44
64
  import {
45
65
  activityDetailLines,
46
66
  classifierStatus,
@@ -52,9 +72,12 @@ import {
52
72
  savingsLine,
53
73
  storeAgreementLine,
54
74
  unavailableReason,
75
+ unpricedLine,
55
76
  } from '../lib/display.mjs';
56
- import { clip, observedActivity, promptIndex } from '../lib/facts.mjs';
77
+ import { clip, observedActivity, promptIndex, routingBucket } from '../lib/facts.mjs';
78
+ import { applyMode, modeLabel, readProjectMode, resolveRoutingMode } from '../lib/modes.mjs';
57
79
  import { renderPanel, routeDraftOf, routingChanges } from '../lib/panel.mjs';
80
+ import { sameTaskOf } from '../lib/policy.mjs';
58
81
  import {
59
82
  canMoveUp,
60
83
  cellForModel,
@@ -84,6 +107,7 @@ import {
84
107
  SAVINGS_RESET_KEY,
85
108
  sessionCacheTtl,
86
109
  subagentCacheTtl,
110
+ unpricedCause,
87
111
  } from '../lib/savings.mjs';
88
112
  import {
89
113
  addAgentReply,
@@ -135,6 +159,8 @@ const PANE = 'jev-router';
135
159
  const PANE_TITLE = 'Router';
136
160
  const BAND_DETAIL = 'band:detail';
137
161
  const MODE_PREFIX = 'mode:';
162
+ // The session's routing mode override (lib/modes.mjs), apart from its auto|manual MODE_PREFIX.
163
+ const ROUTING_MODE_PREFIX = 'routing-mode:';
138
164
  const isSet = (value) => /^(1|true|yes|on)$/i.test(String(value ?? '').trim());
139
165
 
140
166
  // The counts kept across sessions: each session writes only its own record of a kind, `prefix` and its session id,
@@ -204,10 +230,27 @@ function createRouter(options) {
204
230
  clients: new Map(),
205
231
  prompts: new Map(),
206
232
  decisions: new Map(),
233
+ // Where each turn's prompt came from (originKind), matched at turn.start: the submission running its prompt.submit
234
+ // (`submitting`), else the oldest queued one with the turn's text (`origins`, queueOrigin).
235
+ submitting: null,
236
+ origins: [],
237
+ turnOrigins: new Map(),
238
+ // The session's active goal, the last prompt from a goal origin, clipped, `{ sessionId, text }`, in memory only;
239
+ // and each progress turn's report (`progressNotes`), which the classifier reads as dialogue (progressInput).
240
+ goal: null,
241
+ progressNotes: new Map(),
242
+ // Each turn's decision rows until turn.complete writes them, with the turn's end, to the session's record, held as
243
+ // `{ sessionId, record }` once read (`decisionRecord`).
244
+ turnDecisions: new Map(),
245
+ decisionRecord: null,
207
246
  controllers: new Set(),
208
247
  turnControllers: new Map(),
209
248
  view: null,
210
249
  modes: new Map(),
250
+ // Each session's routing mode override (null: none), as read from or written to the store.
251
+ routingModes: new Map(),
252
+ // The project's `.claude/router.json` mode, read at session.start: { mode, error }.
253
+ project: { mode: null, error: null },
211
254
  // Each routed turn's activity record until turn.complete adds it to the stats, and the session's open run of
212
255
  // one activity, flushed to the store when it ends.
213
256
  turnActivities: new Map(),
@@ -297,6 +340,84 @@ async function rememberMode($, mode) {
297
340
  }
298
341
  }
299
342
 
343
+ // The routing mode a turn starts with and where it comes from. A store that cannot be read counts as no override.
344
+ async function routingModeOf($, router) {
345
+ const sessionId = await $.session.id();
346
+ if (!router.routingModes.has(sessionId)) {
347
+ const saved = await $.store.get(`${ROUTING_MODE_PREFIX}${sessionId}`).catch(() => null);
348
+ router.routingModes.set(sessionId, ROUTING_MODES.includes(saved) ? saved : null);
349
+ }
350
+ return resolveRoutingMode({
351
+ session: router.routingModes.get(sessionId),
352
+ project: router.project.mode,
353
+ profile: router.config.mode,
354
+ });
355
+ }
356
+
357
+ // The prompt footer's word for the router: paused or broken routing, or a routing mode other than balanced, which
358
+ // changes what every routed turn costs. Null for none.
359
+ async function footerLabel($, router, view) {
360
+ if (view.phase === 'unavailable') return 'routing unavailable';
361
+ if ((await modeOf($, router, view.mode)) === 'manual') return 'routing off';
362
+ const routingMode = view.routingMode;
363
+ return routingMode && routingMode.mode !== 'balanced' ? `${routingMode.mode} mode (${routingMode.source})` : null;
364
+ }
365
+
366
+ const sameMode = (a, b) => a?.mode === b?.mode && a?.source === b?.source;
367
+
368
+ // A turn's configs when turn.start did not record them, as after a reload of the Mod mid-turn.
369
+ async function turnConfigOf($, router) {
370
+ return { config: applyMode(router.config, await routingModeOf($, router)), configured: router.config };
371
+ }
372
+
373
+ // The turn routes on the configured routes as its routing mode moves them, fixed now so a change mid-turn waits for
374
+ // the next turn; a pin uses `configured` (decideTurn).
375
+ async function fixTurnConfig($, router, turnId) {
376
+ const turn = await turnConfigOf($, router);
377
+ router.turnConfigs.set(turnId, turn);
378
+ const { routingMode } = turn.config;
379
+ if (router.view && !sameMode(router.view.routingMode, routingMode)) await updateView($, router, { routingMode });
380
+ }
381
+
382
+ // `/router mode <mode|default>`: the session's override, kept for a resume of this session only. It changes the
383
+ // preferred route from the next turn; the route in use moves through the gates. No turn is aborted.
384
+ async function setRoutingMode($, router, value) {
385
+ const sessionId = await $.session.id();
386
+ const key = `${ROUTING_MODE_PREFIX}${sessionId}`;
387
+ let saved = true;
388
+ try {
389
+ if (value === 'default') await $.store.delete(key);
390
+ else await $.store.set(key, value);
391
+ } catch {
392
+ saved = false;
393
+ }
394
+ router.routingModes.set(sessionId, value === 'default' ? null : value);
395
+ const routingMode = await routingModeOf($, router);
396
+ await updateView($, router, { routingMode });
397
+ const unsaved =
398
+ value === 'default'
399
+ ? 'A resume of this session may bring the cleared mode back: the store could not be written.'
400
+ : 'A resume of this session will not keep it: the store could not be written.';
401
+ return [`Routing mode: ${modeLabel(routingMode)}, from the next turn.`, ...(saved ? [] : [unsaved])].join(' ');
402
+ }
403
+
404
+ // A project's `.claude/router.json`, which may set only `mode`. Never a profile's own file: not the active profile's,
405
+ // and not in the home directory, whose `.claude` is the default profile. A repo controls this file, so a symlink, which
406
+ // could reach a file outside it, is refused as the profile's is. A file that does not read is ignored, with the reason
407
+ // for the pane.
408
+ async function readProject($, profilePath) {
409
+ try {
410
+ const cwd = await $.session.cwd();
411
+ const path = `${cwd}/.claude/router.json`;
412
+ const home = await $.env.get('HOME');
413
+ if (path === profilePath || cwd === home || !(await $.fs.exists(path))) return { mode: null, error: null };
414
+ if ((await $.fs.stat(path)).isLink) return { mode: null, error: 'project .claude/router.json is a symlink' };
415
+ return readProjectMode(await $.fs.read(path));
416
+ } catch {
417
+ return { mode: null, error: 'project .claude/router.json could not be read' };
418
+ }
419
+ }
420
+
300
421
  async function updateView($, router, patch) {
301
422
  const value = router.view ?? (await readView($, router));
302
423
  router.view = { ...value, ...patch };
@@ -447,7 +568,8 @@ async function setPin($, router, tier) {
447
568
  return `${tier} pinned for the next turn and its tool continuations.`;
448
569
  }
449
570
 
450
- // `/router [auto|off|pin <tier>|activities <mode>]`; with no action, the pane, or the status text without a surface.
571
+ // `/router [auto|off|pin <tier>|activities <mode>|mode <mode>]`; with no action, the pane, or the status text without
572
+ // a surface.
451
573
  async function routerCommand($, router, args) {
452
574
  const [action, value] = args.trim().split(/\s+/);
453
575
  if (action === 'auto' || action === 'off') {
@@ -456,8 +578,15 @@ async function routerCommand($, router, args) {
456
578
  await changeMode($, router, action === 'auto' ? 'auto' : 'manual');
457
579
  return { text: action === 'auto' ? 'Routing on.' : 'Routing off: Claude’s model is kept.' };
458
580
  }
581
+ if (action === 'decisions') return { text: await decisionsText($, router, value) };
459
582
  if (action === 'pin')
460
583
  return { text: TIERS.includes(value) ? await setPin($, router, value) : `Choose ${TIERS.join(', ')}.` };
584
+ if (action === 'mode')
585
+ return {
586
+ text: [...ROUTING_MODES, 'default'].includes(value)
587
+ ? await setRoutingMode($, router, value)
588
+ : `Choose mode ${[...ROUTING_MODES, 'default'].join(', ')}.`,
589
+ };
461
590
  if (action === 'activities')
462
591
  return {
463
592
  text: ACTIVITY_MODES.includes(value)
@@ -578,12 +707,15 @@ function detailText(config, view) {
578
707
  const missing = missingCredentials(config, view, config.classifier);
579
708
  return [
580
709
  `Router — routing ${view.mode === 'auto' ? 'on' : 'off'}`,
710
+ ...(view.routingMode ? [`Mode: ${modeLabel(view.routingMode)}`] : []),
711
+ ...(view.projectError ? [`Ignored: ${view.projectError}`] : []),
581
712
  `Native model: ${view.nativeModel}`,
582
713
  `Selected: ${view.selectedModel ?? 'not selected'}`,
583
714
  `Observed: ${view.actualModel ?? 'no response yet'}`,
584
715
  `Reason: ${view.reason}`,
585
716
  ...activityDetailLines(config, view),
586
717
  storeAgreementLine(view),
718
+ ...[unpricedLine(view.activityMetrics)].filter(Boolean),
587
719
  savingsLine(view),
588
720
  view.error || missing ? classifierStatus(config, view.error ?? missing) : `${activeClassifier(config).label} ready`,
589
721
  `Context: ${view.contextKnown ? `${view.contextTokens} tokens (estimate)` : 'unknown'}`,
@@ -645,7 +777,9 @@ async function* passMain($, e, next, loop, version, nativeModel, reason, router)
645
777
  // the classifier call. The pin is the one in `view`, the view as the step read it; it is used up only once the route
646
778
  // is written, so a turn interrupted before then leaves it for the next.
647
779
  async function decideTurn($, router, e, signal, step) {
648
- const { sessionId, view, cfg, loop, loopVersion, context, nativeModel, availableModels } = step;
780
+ const { sessionId, view, loop, loopVersion, context, nativeModel, availableModels } = step;
781
+ // A pin runs its tier's configured route: the routing mode moves only routes the router chooses.
782
+ const cfg = view.pendingPin ? step.configured : step.cfg;
649
783
  const ref = { ...LOOP, id: 'main' };
650
784
  const controller = new AbortController();
651
785
  const cancel = () => controller.abort();
@@ -661,13 +795,23 @@ async function decideTurn($, router, e, signal, step) {
661
795
  $.session.messages({ as: 'api' }),
662
796
  ]);
663
797
  if (!(await live())) return null;
664
- const facts = nativeFacts(cfg, loop, {
665
- messages,
666
- prompt: router.prompts.get(e.turnId),
667
- effort: e.effort,
668
- turnId: e.turnId,
669
- contextTokens: context.tokens,
670
- });
798
+ const origin = router.turnOrigins.get(e.turnId) ?? 'unknown';
799
+ // A progress turn is the same task (sameTaskOf).
800
+ const facts = {
801
+ ...nativeFacts(cfg, loop, {
802
+ messages,
803
+ prompt: router.prompts.get(e.turnId),
804
+ effort: e.effort,
805
+ turnId: e.turnId,
806
+ contextTokens: context.tokens,
807
+ }),
808
+ progress: isProgressOrigin(origin),
809
+ };
810
+ const asked = progressInput(
811
+ facts,
812
+ { goal: router.prompts.get(e.turnId), note: router.progressNotes.get(e.turnId) },
813
+ cfg.context.recentTurns,
814
+ );
671
815
  await updateView($, router, {
672
816
  phase: 'choosing',
673
817
  activeTurnId: e.turnId,
@@ -683,8 +827,8 @@ async function decideTurn($, router, e, signal, step) {
683
827
  config: cfg,
684
828
  apiKey: credentials.apiKey,
685
829
  endpoint: credentials.endpoint,
686
- prompt: facts.prompt,
687
- turns: facts.turns,
830
+ prompt: asked.prompt,
831
+ turns: asked.turns,
688
832
  signal: controller.signal,
689
833
  });
690
834
  // The wait for advice alone, comparable with the activity probe's p95; the routing after it is not the classifier's.
@@ -692,6 +836,8 @@ async function decideTurn($, router, e, signal, step) {
692
836
  if (controller.signal.aborted || (await $.session.id()) !== sessionId || (await modeOf($, router)) !== 'auto')
693
837
  return null;
694
838
  const previous = loop.decision;
839
+ if (pin)
840
+ router.turnConfigs.set(e.turnId, { config: { ...cfg, routingMode: step.cfg.routingMode }, configured: cfg });
695
841
  const selected = chooseRoute(cfg, loop, {
696
842
  facts,
697
843
  advice: result.advice,
@@ -710,12 +856,45 @@ async function decideTurn($, router, e, signal, step) {
710
856
  if (previous?.model && previous.model !== selected.decision.model && !selected.decision.pinned)
711
857
  $.ui.toast(switchToast(cfg, previous, selected.decision, selected.decision.estimate));
712
858
  const activity = turnActivity(cfg, result.advice, previous, selected.decision);
859
+ const routingMode = step.cfg.routingMode;
860
+ addDecision(
861
+ router,
862
+ e.turnId,
863
+ decisionRow({
864
+ at: Date.now(),
865
+ kind: 'start',
866
+ origin,
867
+ mode: pin ? null : routingMode.mode,
868
+ advice: result.advice,
869
+ error: result.error,
870
+ decision: selected.decision,
871
+ facts,
872
+ sameTask: sameTaskOf(cfg, result.advice, facts),
873
+ }),
874
+ );
875
+ // One line per decision in Claude Code's debug log, so a later replay can compare modes. No prompt text.
876
+ $.ui.log(
877
+ `router decision ${JSON.stringify({
878
+ mode: routingMode.mode,
879
+ modeSource: routingMode.source,
880
+ origin,
881
+ classified: result.advice?.choice ?? null,
882
+ tier: selected.decision.tier,
883
+ reason: selected.decision.reason,
884
+ route: `${selected.decision.model}@${selected.decision.effort ?? 'session'}`,
885
+ pinned: selected.decision.pinned,
886
+ })}`,
887
+ { to: 'debug' },
888
+ );
713
889
  router.turnActivities.set(e.turnId, {
714
890
  ...activity,
715
891
  reason: selected.decision.reason,
716
892
  escalated: Boolean(selected.decision.escalated),
717
893
  pinned: selected.decision.pinned,
718
894
  route: `${selected.decision.model}@${selected.decision.effort ?? 'session'}`,
895
+ // A pinned turn ran the configured routes, which balanced runs: its replies count there.
896
+ routingMode: pin ? DEFAULTS.mode : routingMode.mode,
897
+ modeSource: pin ? 'pin' : routingMode.source,
719
898
  classifier: cfg.classifier,
720
899
  offSwitches: router.offSwitches,
721
900
  adviceMs,
@@ -725,11 +904,14 @@ async function decideTurn($, router, e, signal, step) {
725
904
  outputTokens: 0,
726
905
  routedUsd: null,
727
906
  pricedRequests: 0,
907
+ unpriced: {},
728
908
  routes: {},
729
909
  });
730
910
  await updateView($, router, {
731
911
  ...(activity.switched ? switchView(previous, selected.decision, activity.label, Date.now()) : {}),
732
912
  phase: 'routed',
913
+ // The session's mode, not this turn's: a `/router mode` sent while the classifier answered names the next turn.
914
+ routingMode: await routingModeOf($, router),
733
915
  selectedModel: selected.decision.model,
734
916
  actualModel: null,
735
917
  tier: selected.decision.tier,
@@ -793,9 +975,23 @@ async function moveOnObserved($, router, cfg, loop, e, context) {
793
975
  const messages = await transcript($);
794
976
  if (!messages) return loop;
795
977
  const facts = stepFacts(cfg, router, loop, e, messages, context);
796
- const observed = observedActivity(messages, Math.max(promptIndex(messages), (loop.observedFrom ?? 0) - 1));
978
+ const observed = routingBucket(
979
+ observedActivity(messages, Math.max(promptIndex(messages), (loop.observedFrom ?? 0) - 1)),
980
+ );
797
981
  const moved = observedMove(cfg, loop, { observed, facts, contextKnown: context.known, now: Date.now() });
798
982
  if (moved === loop) return loop;
983
+ addDecision(
984
+ router,
985
+ e.turnId,
986
+ decisionRow({
987
+ at: Date.now(),
988
+ kind: 'observed',
989
+ origin: router.turnOrigins.get(e.turnId) ?? 'unknown',
990
+ mode: cfg.routingMode?.mode ?? null,
991
+ decision: moved.decision,
992
+ facts,
993
+ }),
994
+ );
799
995
  $.ui.toast(switchToast(cfg, loop.decision, moved.decision, moved.decision.estimate));
800
996
  // Replies from here on are labelled with the moved activity; the classifier's answer stays as recorded.
801
997
  const turn = router.turnActivities.get(e.turnId);
@@ -811,7 +1007,7 @@ async function moveOnObserved($, router, cfg, loop, e, context) {
811
1007
  // Inside a turn the classifier is asked again every `policy.reviewEveryRequests` requests, in the background: a step
812
1008
  // never waits for it. The answer applies at the first step after it arrives, as a decision on the same task
813
1009
  // (sameTaskOf), so the tier and the activity can move either way: up on the usual votes, down only past the dwell and a
814
- // passed verification. Pinned turns and a native fallback are left alone; a failed read or ask changes nothing.
1010
+ // checkpoint (completedSince). Pinned turns and a native fallback are left alone; a failed read or ask changes nothing.
815
1011
  async function reviewMidTurn($, router, cfg, loop, e, { context, nativeModel, availableModels }) {
816
1012
  const review = router.reviews.get(e.turnId);
817
1013
  if (review?.answer) {
@@ -833,6 +1029,20 @@ async function reviewMidTurn($, router, cfg, loop, e, { context, nativeModel, av
833
1029
  now: Date.now(),
834
1030
  });
835
1031
  const previous = loop.decision;
1032
+ addDecision(
1033
+ router,
1034
+ e.turnId,
1035
+ decisionRow({
1036
+ at: Date.now(),
1037
+ kind: 'review',
1038
+ origin: router.turnOrigins.get(e.turnId) ?? 'unknown',
1039
+ mode: cfg.routingMode?.mode ?? null,
1040
+ advice,
1041
+ decision: selected.decision,
1042
+ facts,
1043
+ sameTask: sameTaskOf(cfg, advice, facts),
1044
+ }),
1045
+ );
836
1046
  if (previous && (previous.model !== selected.decision.model || previous.effort !== selected.decision.effort)) {
837
1047
  $.ui.toast(switchToast(cfg, previous, selected.decision, selected.decision.estimate));
838
1048
  const turn = router.turnActivities.get(e.turnId);
@@ -893,7 +1103,7 @@ async function reviewMidTurn($, router, cfg, loop, e, { context, nativeModel, av
893
1103
  }
894
1104
 
895
1105
  // A routed reply's metrics in the view, with the tier that served it, and added to the turn's activity record with its list price (`routedUsd`, null when unpriced) and, when its tier served it, its route.
896
- async function publishReply($, router, turnId, response, tier, route, routedUsd) {
1106
+ async function publishReply($, router, turnId, response, tier, route, routedUsd, cause = null) {
897
1107
  const turn = router.turnActivities.get(turnId);
898
1108
  const metrics = responseMetrics(router.view, response, tier, Date.now());
899
1109
  await updateView($, router, metrics);
@@ -905,6 +1115,7 @@ async function publishReply($, router, turnId, response, tier, route, routedUsd)
905
1115
  outputTokens: turn.outputTokens + (metrics.outputTokens ?? 0),
906
1116
  routedUsd: Number.isFinite(routedUsd) ? (turn.routedUsd ?? 0) + routedUsd : turn.routedUsd,
907
1117
  pricedRequests: turn.pricedRequests + (Number.isFinite(routedUsd) ? 1 : 0),
1118
+ unpriced: cause ? { ...turn.unpriced, [cause]: (turn.unpriced?.[cause] ?? 0) + 1 } : turn.unpriced,
908
1119
  routes: tier ? { ...turn.routes, [route]: (turn.routes[route] ?? 0) + 1 } : turn.routes,
909
1120
  });
910
1121
  }
@@ -929,7 +1140,20 @@ async function observeRouted($, router, { turnId, cfg, loop, loopVersion, reques
929
1140
  // A substituted reply is not the tier's: the strip and trend must not count it as one.
930
1141
  const tier = isSameModel(request.model, response.usage?.model) ? loop.decision.tier : null;
931
1142
  const route = `${request.model}@${request.effort ?? 'session'}`;
932
- await publishReply($, router, turnId, response, tier, route, compared?.reply?.routedUsd ?? null);
1143
+ // Why the usage record leaves this reply out, when it does (UNPRICED_CAUSES).
1144
+ const cause = !compared
1145
+ ? response.usage?.model
1146
+ ? 'error'
1147
+ : 'usage'
1148
+ : compared.reply
1149
+ ? null
1150
+ : (unpricedCause(cfg, {
1151
+ usage: response.usage,
1152
+ served: { model: response.usage.model, effort: request.effort ?? null },
1153
+ yours: { model: nativeModel },
1154
+ ttl: compared.ttl,
1155
+ }) ?? 'error');
1156
+ await publishReply($, router, turnId, response, tier, route, compared?.reply?.routedUsd ?? null, cause);
933
1157
  // Kept by model id, under the model that served it: a substitute's cost is not the requested model's, and a models
934
1158
  // key can name another model later.
935
1159
  const idOf = (model) => modelSpec(cfg, model)?.id ?? model;
@@ -973,14 +1197,16 @@ async function compareYours($, router, loop, response, servedEffort, nativeModel
973
1197
  try {
974
1198
  if (!response.usage?.model) return null;
975
1199
  const view = router.view ?? (await readView($, router));
976
- return compareModels(cfg, loop.yoursBy ?? {}, {
1200
+ const ttl = await cacheTtlOf($);
1201
+ const compared = compareModels(cfg, loop.yoursBy ?? {}, {
977
1202
  usage: response.usage,
978
1203
  served: { model: response.usage.model, effort: servedEffort },
979
1204
  effort: view.nativeEffort ?? null,
980
- ttl: await cacheTtlOf($),
1205
+ ttl,
981
1206
  now: Date.now(),
982
1207
  yours: nativeModel,
983
1208
  });
1209
+ return { ...compared, ttl };
984
1210
  } catch {
985
1211
  return null;
986
1212
  }
@@ -996,6 +1222,7 @@ async function addSavings($, router, { turnId, compared, tier, route, yours, byI
996
1222
  const turn = router.turnActivities.get(turnId);
997
1223
  const entry = replyEntry({
998
1224
  at,
1225
+ mode: turn?.routingMode ?? view.routingMode?.mode ?? DEFAULTS.mode,
999
1226
  activity: tier ? (turn?.label ?? null) : null,
1000
1227
  tier,
1001
1228
  route,
@@ -1018,6 +1245,140 @@ async function flushUsage($, router, entries, switched) {
1018
1245
  } catch {}
1019
1246
  }
1020
1247
 
1248
+ // A turn's prompt, its origin and the classifier's request text. A progress turn asks about the goal it serves, with
1249
+ // its report as dialogue (progressInput); without a goal from this session it reads as before. A goal origin's prompt
1250
+ // becomes the goal.
1251
+ async function startTurn($, router, e) {
1252
+ const text = clip(e.text, router.config.context.maxTextChars);
1253
+ const origin = originOfTurn(router, e.text);
1254
+ router.turnOrigins.set(e.turnId, origin);
1255
+ const sessionId = await $.session.id();
1256
+ if (isProgressOrigin(origin) && router.goal?.sessionId === sessionId) {
1257
+ router.prompts.set(e.turnId, router.goal.text);
1258
+ router.progressNotes.set(e.turnId, text);
1259
+ return;
1260
+ }
1261
+ router.prompts.set(e.turnId, text);
1262
+ if (isGoalOrigin(origin)) router.goal = { sessionId, text };
1263
+ }
1264
+
1265
+ // The engine stamps each prompt with where it came from (PromptOrigin); turn.start does not carry it. An idle
1266
+ // submission starts its turn inside next(e), so the turn takes `submitting`; one queued behind a running turn starts
1267
+ // later, or is delivered into it, and waits in `origins` under the text that entered. Bookkeeping only: the prompt
1268
+ // passes on unchanged, and nothing here throws after next(e).
1269
+ async function submitPrompt(router, e, next) {
1270
+ const entry = { kind: originKind(e.origin), started: false };
1271
+ const outer = router.submitting;
1272
+ router.submitting = entry;
1273
+ try {
1274
+ const result = await next(e);
1275
+ if (!entry.started && typeof result?.text === 'string' && !result.drop)
1276
+ router.origins = queueOrigin(router.origins, { kind: entry.kind, text: result.text, at: Date.now() });
1277
+ return result;
1278
+ } finally {
1279
+ router.submitting = outer;
1280
+ }
1281
+ }
1282
+
1283
+ // One decision row added to the turn's, bounded per turn (addTurnRow).
1284
+ function addDecision(router, turnId, row) {
1285
+ router.turnDecisions.set(turnId, addTurnRow(router.turnDecisions.get(turnId) ?? [], row));
1286
+ }
1287
+
1288
+ // The origin of a turn starting with `text`: the submission whose next(e) is running, once, else the oldest queued one
1289
+ // with that text, else 'unknown'.
1290
+ function originOfTurn(router, text) {
1291
+ if (router.submitting && !router.submitting.started) {
1292
+ router.submitting.started = true;
1293
+ return router.submitting.kind;
1294
+ }
1295
+ const taken = takeOrigin(router.origins, text, Date.now());
1296
+ router.origins = taken.queue;
1297
+ return taken.kind;
1298
+ }
1299
+
1300
+ // A finished turn's decision rows and its end row, added to this session's record. Telemetry never breaks a turn: a
1301
+ // failed read or write loses this turn's rows. A record from before the last reset reads as empty, and rows read
1302
+ // before a Reset in this session are not written back.
1303
+ async function flushDecisions($, router, turnId, turn) {
1304
+ const rows = router.turnDecisions.get(turnId) ?? [];
1305
+ router.turnDecisions.delete(turnId);
1306
+ router.turnOrigins.delete(turnId);
1307
+ router.progressNotes.delete(turnId);
1308
+ if (!rows.length) return;
1309
+ try {
1310
+ const resets = router.statsResets;
1311
+ const sessionId = await $.session.id();
1312
+ if (turn && turn.sessionId !== sessionId) return;
1313
+ const key = `${DECISIONS_PREFIX}${sessionId}`;
1314
+ const resetAt = await $.store.get(SAVINGS_RESET_KEY);
1315
+ if (router.decisionRecord?.sessionId !== sessionId)
1316
+ router.decisionRecord = { sessionId, record: readDecisions(await $.store.get(key)) };
1317
+ const held = router.decisionRecord;
1318
+ const now = Date.now();
1319
+ const end = turn
1320
+ ? [
1321
+ endRow({
1322
+ at: now,
1323
+ // With activity routing off recordActivity does not run, so the bucket is read here.
1324
+ observed: turn.observed ?? (await turnBucket($)),
1325
+ requests: turn.requests,
1326
+ priced: turn.pricedRequests,
1327
+ unpriced: turn.unpriced,
1328
+ }),
1329
+ ]
1330
+ : [];
1331
+ const record = appendDecisions(decisionsAfterReset(held.record, resetAt), [...rows, ...end], now);
1332
+ if (router.statsResets !== resets || router.decisionRecord !== held) return;
1333
+ held.record = record;
1334
+ await $.store.set(key, record);
1335
+ } catch {}
1336
+ }
1337
+
1338
+ // The bucket of the turn the transcript ends with (observedActivity), or null when it cannot be read.
1339
+ async function turnBucket($) {
1340
+ const messages = await transcript($);
1341
+ const start = messages ? promptIndex(messages) : -1;
1342
+ return start < 0 ? null : observedActivity(messages, start);
1343
+ }
1344
+
1345
+ // Other sessions' decision records past their retention or the record bound (prunedDecisions), each read again just
1346
+ // before its delete, so a session that wrote meanwhile keeps its record.
1347
+ async function pruneDecisionRecords($) {
1348
+ try {
1349
+ const own = `${DECISIONS_PREFIX}${await $.session.id()}`;
1350
+ const keys = (await $.store.keys()).filter((key) => key.startsWith(DECISIONS_PREFIX) && key !== own);
1351
+ const values = await Promise.all(keys.map((key) => $.store.get(key)));
1352
+ const gone = prunedDecisions(
1353
+ keys.map((key, i) => [key, values[i]]),
1354
+ Date.now(),
1355
+ );
1356
+ await Promise.allSettled(
1357
+ [...gone].map(async (key) => {
1358
+ const current = await $.store.get(key);
1359
+ if (JSON.stringify(current) === JSON.stringify(values[keys.indexOf(key)])) await $.store.delete(key);
1360
+ }),
1361
+ );
1362
+ } catch {}
1363
+ }
1364
+
1365
+ // `/router decisions [n]`: this session's newest routing decisions, the running turn's included.
1366
+ async function decisionsText($, router, value) {
1367
+ const n = Math.min(MAX_ROWS, Math.max(1, Number.parseInt(value, 10) || 20));
1368
+ try {
1369
+ const sessionId = await $.session.id();
1370
+ const stored =
1371
+ router.decisionRecord?.sessionId === sessionId
1372
+ ? router.decisionRecord.record
1373
+ : readDecisions(await $.store.get(`${DECISIONS_PREFIX}${sessionId}`));
1374
+ const resetAt = await $.store.get(SAVINGS_RESET_KEY);
1375
+ const pending = [...router.turnDecisions.values()].flat();
1376
+ return decisionLines([...decisionsAfterReset(stored, resetAt).rows, ...pending], n).join('\n');
1377
+ } catch {
1378
+ return 'Routing decisions could not be read.';
1379
+ }
1380
+ }
1381
+
1021
1382
  // A finished turn's activity stats: the session counts in the view and the counts kept across sessions. Stats never
1022
1383
  // break a turn: a failed read or write loses this turn's counts. Readings already in the session's metrics record stay
1023
1384
  // in memory after a failed write and go out with the next turn that adds a reading.
@@ -1028,6 +1389,8 @@ async function recordActivity($, router, turn) {
1028
1389
  const start = promptIndex(messages);
1029
1390
  if (start < 0) return;
1030
1391
  const observed = observedActivity(messages, start);
1392
+ // The turn's end row reads it (flushDecisions).
1393
+ turn.observed = observed;
1031
1394
  const view = router.view ?? (await readView($, router));
1032
1395
  const manual = (await modeOf($, router)) === 'manual';
1033
1396
  // The session may have changed during the reads; this turn is not the new session's.
@@ -1060,7 +1423,12 @@ async function recordActivity($, router, turn) {
1060
1423
  // empties the view; these counts are older than it. Each record is written on its own: a failed write of one
1061
1424
  // keeps the other.
1062
1425
  const stats = { predicted: turn.predicted, observed, runEnded: ended, lateral: turn.lateral };
1063
- const metrics = { classifier: turn.classifier, adviceMs: turn.adviceMs, downMove: down.event };
1426
+ const metrics = {
1427
+ classifier: turn.classifier,
1428
+ adviceMs: turn.adviceMs,
1429
+ downMove: down.event,
1430
+ unpriced: turn.unpriced,
1431
+ };
1064
1432
  const shown = await Promise.all([
1065
1433
  addToLedger($, router, 'activity', (record, now) => recordStore(record, stats, now)).catch(() => false),
1066
1434
  addToLedger($, router, 'metrics', (record, now) => recordMetrics(record, { ...metrics, now })).catch(() => false),
@@ -1325,7 +1693,9 @@ function paneActions($, router, view) {
1325
1693
  if (result.error) return updateView($, router, { notice: result.error });
1326
1694
  const drafts = router.view ?? view;
1327
1695
  const reset = await adopt(result.config);
1328
- return updateView($, router, { ...reset, ...rebased(drafts), ...saved(router.config) });
1696
+ // A saved or undone profile mode changes the mode shown, unless a session or project mode wins.
1697
+ const routingMode = await routingModeOf($, router);
1698
+ return updateView($, router, { ...reset, ...rebased(drafts), ...saved(router.config), routingMode });
1329
1699
  };
1330
1700
  // Defaults go into the routing draft like any edit; the notice says whether Save has anything of that section left
1331
1701
  // to write.
@@ -1425,6 +1795,12 @@ function paneActions($, router, view) {
1425
1795
  // An insight's link: the Routes tab with the grid cell it names open.
1426
1796
  openRoute: (cell) => updateView($, router, { tab: 'routes', routeCell: cell, notice: null }),
1427
1797
  confirmDelete: (asked) => updateView($, router, { confirmDelete: asked }),
1798
+ // The profile's routing mode, saved at once with Undo. A session or project mode still wins over it.
1799
+ routingMode: async (mode) => {
1800
+ const from = router.config.mode;
1801
+ if (mode === from || !ROUTING_MODES.includes(mode)) return undefined;
1802
+ return write(`routing mode ${from} → ${mode}`, (file) => withMode(file, mode));
1803
+ },
1428
1804
  // `/router activities <mode>`: the mode alone, saved at once like a classifier press, with Undo.
1429
1805
  activityRouting: (mode) => {
1430
1806
  const from = router.config.activityRouting;
@@ -1440,6 +1816,8 @@ function paneActions($, router, view) {
1440
1816
  router.run = null;
1441
1817
  router.afterDown = null;
1442
1818
  router.turnUsage.clear();
1819
+ router.turnDecisions.clear();
1820
+ router.decisionRecord = null;
1443
1821
  for (const [id, agent] of router.agents) router.agents.set(id, flushedAgent(agent));
1444
1822
  // Every session's records. The marker is written first, so a session still holding its record from before the
1445
1823
  // reset drops it, unless that record's first count has the reset's millisecond or the clock moved back across
@@ -1447,8 +1825,10 @@ function paneActions($, router, view) {
1447
1825
  const clearRecords = async () => {
1448
1826
  const resetAt = Date.now();
1449
1827
  await $.store.set(SAVINGS_RESET_KEY, resetAt);
1450
- const keys = (await $.store.keys()).filter((key) =>
1451
- Object.values(LEDGERS).some(({ prefix, legacy }) => key.startsWith(prefix) || key === legacy),
1828
+ const keys = (await $.store.keys()).filter(
1829
+ (key) =>
1830
+ key.startsWith(DECISIONS_PREFIX) ||
1831
+ Object.values(LEDGERS).some(({ prefix, legacy }) => key.startsWith(prefix) || key === legacy),
1452
1832
  );
1453
1833
  await Promise.all(keys.map((key) => $.store.delete(key)));
1454
1834
  for (const kind of LEDGER_KINDS)
@@ -1530,6 +1910,13 @@ async function endSession($, router) {
1530
1910
  for (const controller of router.controllers) controller.abort();
1531
1911
  router.decisions.clear();
1532
1912
  router.prompts.clear();
1913
+ router.turnOrigins.clear();
1914
+ router.progressNotes.clear();
1915
+ router.turnDecisions.clear();
1916
+ router.origins = [];
1917
+ router.submitting = null;
1918
+ router.goal = null;
1919
+ router.decisionRecord = null;
1533
1920
  router.turnConfigs.clear();
1534
1921
  router.turnPins.clear();
1535
1922
  router.turnActivities.clear();
@@ -1572,13 +1959,15 @@ export function register(on, options) {
1572
1959
  router.definitions.clear();
1573
1960
  await $.command.register({
1574
1961
  name: 'router',
1575
- description: 'Open the Router pane, or switch routing: auto, off, pin <tier>, activities <mode>.',
1576
- argumentHint: '[auto|off|pin <tier>|activities off|on]',
1962
+ description:
1963
+ 'Open the Router pane, or switch routing: auto, off, pin <tier>, activities <mode>, mode <mode>; decisions [n] lists the last routing decisions.',
1964
+ argumentHint: '[auto|off|pin <tier>|activities off|on|mode cost|balanced|quality|default|decisions [n]]',
1577
1965
  immediate: true,
1578
1966
  });
1579
1967
  const model = await $.session.model();
1580
1968
  try {
1581
1969
  router.config = await loadNativeConfig($);
1970
+ router.project = await readProject($, router.config.nativePath);
1582
1971
  const existing = await readView($, router);
1583
1972
  router.view = existing;
1584
1973
  const sameClassifier = existing.health?.classifier === router.config.classifier;
@@ -1599,6 +1988,8 @@ export function register(on, options) {
1599
1988
  credentials: await credentialsOf($, options, router.config),
1600
1989
  health: healthOf(clientOf(router, router.config.classifier), router.config.classifier),
1601
1990
  configPath: router.config.nativePath,
1991
+ routingMode: await routingModeOf($, router),
1992
+ projectError: router.project.error,
1602
1993
  tuning: null,
1603
1994
  tuningBase: null,
1604
1995
  routeDraft: null,
@@ -1607,6 +1998,7 @@ export function register(on, options) {
1607
1998
  usagePeriod: await periodOf($),
1608
1999
  ...(await storeView($, router)),
1609
2000
  });
2001
+ await pruneDecisionRecords($);
1610
2002
  } catch (error) {
1611
2003
  await updateView($, router, {
1612
2004
  phase: 'unavailable',
@@ -1638,12 +2030,14 @@ export function register(on, options) {
1638
2030
 
1639
2031
  on('command.run', { command: 'router' }, ($, e) => routerCommand($, router, e.args));
1640
2032
 
1641
- on('turn.start', (_$, e, next) => {
1642
- router.turnConfigs.set(e.turnId, router.config);
1643
- router.prompts.set(e.turnId, clip(e.text, router.config.context.maxTextChars));
2033
+ on('turn.start', async ($, e, next) => {
2034
+ await fixTurnConfig($, router, e.turnId);
2035
+ await startTurn($, router, e);
1644
2036
  return next(e);
1645
2037
  });
1646
2038
 
2039
+ on('prompt.submit', (_$, e, next) => submitPrompt(router, e, next));
2040
+
1647
2041
  // A hook failure spawns the agent as Claude Code would; next(e) replays a spawn already made. agent.spawn and a
1648
2042
  // catchable on() are in the 2.1.293 build types, not checked on 2.1.289: an engine without them still loads routing.
1649
2043
  try {
@@ -1652,7 +2046,8 @@ export function register(on, options) {
1652
2046
 
1653
2047
  on('turn.step', async function* ($, e, next) {
1654
2048
  if (e.agentId) return yield* stepAgent($, router, e, next);
1655
- const cfg = router.turnConfigs.get(e.turnId) ?? router.config;
2049
+ const turn = router.turnConfigs.get(e.turnId) ?? (await turnConfigOf($, router));
2050
+ const cfg = turn.config;
1656
2051
  const [sessionId, nativeModel, view] = await Promise.all([$.session.id(), $.session.model(), readView($, router)]);
1657
2052
  const mode = await modeOf($, router, view.mode);
1658
2053
  if (e.index === 0) {
@@ -1666,7 +2061,8 @@ export function register(on, options) {
1666
2061
  const ref = { ...LOOP, id: 'main' };
1667
2062
  const loaded = await $.state.get(ref);
1668
2063
  let loopVersion = loaded.version;
1669
- let loop = prepareLoop(loaded.value ?? emptyLoop(cfg, e.model), e.messageCount);
2064
+ // The session's model names its tier in the configured routes: a mode's table can run it at another tier.
2065
+ let loop = prepareLoop(loaded.value ?? emptyLoop(turn.configured, e.model), e.messageCount);
1670
2066
  if (view.phase === 'unavailable' || mode === 'manual') {
1671
2067
  return yield* passMain($, e, next, loop, loopVersion, nativeModel, 'manual', router);
1672
2068
  }
@@ -1683,6 +2079,7 @@ export function register(on, options) {
1683
2079
  sessionId,
1684
2080
  view,
1685
2081
  cfg,
2082
+ configured: turn.configured,
1686
2083
  loop,
1687
2084
  loopVersion,
1688
2085
  context,
@@ -1755,6 +2152,7 @@ export function register(on, options) {
1755
2152
  const entries = router.turnUsage.get(e.turnId);
1756
2153
  router.turnUsage.delete(e.turnId);
1757
2154
  if (entries) await flushUsage($, router, entries, turn?.switched ?? null);
2155
+ await flushDecisions($, router, e.turnId, turn);
1758
2156
  return next(e);
1759
2157
  });
1760
2158
 
@@ -1784,13 +2182,7 @@ export function register(on, options) {
1784
2182
 
1785
2183
  // Paused or broken routing stays visible in the prompt footer even when the band is collapsed.
1786
2184
  on('ui.render', { component: 'SessionMode' }, async ($, e, next) => {
1787
- const view = await readView($, router);
1788
- const label =
1789
- view.phase === 'unavailable'
1790
- ? 'routing unavailable'
1791
- : (await modeOf($, router, view.mode)) === 'manual'
1792
- ? 'routing off'
1793
- : null;
2185
+ const label = await footerLabel($, router, await readView($, router));
1794
2186
  return label ? next({ ...e, props: { ...e.props, modes: [...e.props.modes, label] } }) : next(e);
1795
2187
  });
1796
2188