@alexeiled/claude-router 1.15.0 → 1.17.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.
@@ -26,6 +26,7 @@ import {
26
26
  activeClassifier,
27
27
  CLASSIFY,
28
28
  DEFAULTS,
29
+ defaultsFor,
29
30
  editActivity,
30
31
  effectiveActivities,
31
32
  effectiveRoutes,
@@ -43,6 +44,24 @@ import {
43
44
  withTuning,
44
45
  } from '../lib/config.mjs';
45
46
  import { changedLeaves, notSaved, restored, rewrittenConfig } from '../lib/config-file.mjs';
47
+ import {
48
+ addTurnRow,
49
+ appendDecisions,
50
+ DECISIONS_PREFIX,
51
+ decisionLines,
52
+ decisionRow,
53
+ decisionsAfterReset,
54
+ endRow,
55
+ isGoalOrigin,
56
+ isProgressOrigin,
57
+ MAX_ROWS,
58
+ originKind,
59
+ progressInput,
60
+ prunedDecisions,
61
+ queueOrigin,
62
+ readDecisions,
63
+ takeOrigin,
64
+ } from '../lib/decisions.mjs';
46
65
  import {
47
66
  activityDetailLines,
48
67
  classifierStatus,
@@ -54,10 +73,13 @@ import {
54
73
  savingsLine,
55
74
  storeAgreementLine,
56
75
  unavailableReason,
76
+ unpricedLine,
57
77
  } from '../lib/display.mjs';
58
- import { clip, observedActivity, promptIndex } from '../lib/facts.mjs';
78
+ import { clip, hasImages, observedActivity, promptIndex, routingBucket } from '../lib/facts.mjs';
59
79
  import { applyMode, modeLabel, readProjectMode, resolveRoutingMode } from '../lib/modes.mjs';
60
80
  import { renderPanel, routeDraftOf, routingChanges } from '../lib/panel.mjs';
81
+ import { sameTaskOf } from '../lib/policy.mjs';
82
+ import { providerFile, providerName } from '../lib/providers.mjs';
61
83
  import {
62
84
  canMoveUp,
63
85
  cellForModel,
@@ -82,11 +104,13 @@ import {
82
104
  modelAlias,
83
105
  modelEntry,
84
106
  modelSpec,
107
+ observedReplyUsd,
85
108
  readSavingsStore,
86
109
  SAVINGS_PREFIX,
87
110
  SAVINGS_RESET_KEY,
88
111
  sessionCacheTtl,
89
112
  subagentCacheTtl,
113
+ unpricedCause,
90
114
  } from '../lib/savings.mjs';
91
115
  import {
92
116
  addAgentReply,
@@ -209,6 +233,19 @@ function createRouter(options) {
209
233
  clients: new Map(),
210
234
  prompts: new Map(),
211
235
  decisions: new Map(),
236
+ // Where each turn's prompt came from (originKind), matched at turn.start: the submission running its prompt.submit
237
+ // (`submitting`), else the oldest queued one with the turn's text (`origins`, queueOrigin).
238
+ submitting: null,
239
+ origins: [],
240
+ turnOrigins: new Map(),
241
+ // The session's active goal, the last prompt from a goal origin, clipped, `{ sessionId, text }`, in memory only;
242
+ // and each progress turn's report (`progressNotes`), which the classifier reads as dialogue (progressInput).
243
+ goal: null,
244
+ progressNotes: new Map(),
245
+ // Each turn's decision rows until turn.complete writes them, with the turn's end, to the session's record, held as
246
+ // `{ sessionId, record }` once read (`decisionRecord`).
247
+ turnDecisions: new Map(),
248
+ decisionRecord: null,
212
249
  controllers: new Set(),
213
250
  turnControllers: new Map(),
214
251
  view: null,
@@ -544,6 +581,7 @@ async function routerCommand($, router, args) {
544
581
  await changeMode($, router, action === 'auto' ? 'auto' : 'manual');
545
582
  return { text: action === 'auto' ? 'Routing on.' : 'Routing off: Claude’s model is kept.' };
546
583
  }
584
+ if (action === 'decisions') return { text: await decisionsText($, router, value) };
547
585
  if (action === 'pin')
548
586
  return { text: TIERS.includes(value) ? await setPin($, router, value) : `Choose ${TIERS.join(', ')}.` };
549
587
  if (action === 'mode')
@@ -636,27 +674,41 @@ async function effortSplitsCacheOf($) {
636
674
  async function loadNativeConfig($) {
637
675
  for (const source of ['project', 'local']) {
638
676
  const settings = await $.settings.read({ source });
639
- if (settings.env && ['HOME', 'CLAUDE_CONFIG_DIR'].some((key) => Object.hasOwn(settings.env, key)))
677
+ if (
678
+ settings.env &&
679
+ ['HOME', 'CLAUDE_CONFIG_DIR', 'CLAUDE_ROUTER_PROVIDER'].some((key) => Object.hasOwn(settings.env, key))
680
+ )
640
681
  throw new Error('project settings cannot redirect the router profile');
641
682
  }
642
683
  const home = await $.env.get('HOME');
643
684
  const profile = (await $.env.get('CLAUDE_CONFIG_DIR')) ?? `${home}/.claude`;
644
- const path = `${profile}/router.json`;
685
+ const provider = providerName(await $.env.get('CLAUDE_ROUTER_PROVIDER'));
686
+ const path = `${profile}/${providerFile(provider)}`;
687
+ if (provider !== 'anthropic' && !(await $.fs.exists(path)))
688
+ throw new Error('selected provider router file is missing');
645
689
  const userFile = (await $.fs.exists(path)) ? JSON.parse(await $.fs.read(path)) : null;
646
- return { ...loadConfig({ userFile }), nativePath: path, effortSplitsCache: await effortSplitsCacheOf($) };
690
+ return { ...loadConfig({ userFile, provider }), nativePath: path, effortSplitsCache: await effortSplitsCacheOf($) };
647
691
  }
648
692
 
649
693
  // Writes router.json through `change(previousFile)` once the result validates. Returns the new config or an error
650
694
  // line for the pane; a failure leaves the file untouched.
651
- async function saveConfig($, path, change) {
695
+ async function saveConfig($, active, change) {
696
+ const path = active.nativePath;
697
+ const filename = path?.split('/').at(-1) ?? 'router.json';
652
698
  try {
699
+ if (active.provider !== 'anthropic' && !(await $.fs.exists(path)))
700
+ throw new Error('selected provider router file is missing');
653
701
  if ((await $.fs.exists(path)) && (await $.fs.stat(path)).isLink)
654
- return { error: 'Not saved: router.json is a symlink. Edit its maintained source instead.' };
655
- const { config, text } = rewrittenConfig((await $.fs.exists(path)) ? await $.fs.read(path) : null, change);
702
+ return { error: `Not saved: ${filename} is a symlink. Edit its maintained source instead.` };
703
+ const { config, text } = rewrittenConfig(
704
+ (await $.fs.exists(path)) ? await $.fs.read(path) : null,
705
+ change,
706
+ active.provider,
707
+ );
656
708
  await $.fs.write(path, text);
657
- return { config: { ...config, nativePath: path, effortSplitsCache: await effortSplitsCacheOf($) } };
709
+ return { config: { ...config, nativePath: path, effortSplitsCache: active.effortSplitsCache } };
658
710
  } catch (error) {
659
- return { error: notSaved(error) };
711
+ return { error: notSaved(error, filename) };
660
712
  }
661
713
  }
662
714
 
@@ -672,6 +724,7 @@ function detailText(config, view) {
672
724
  const missing = missingCredentials(config, view, config.classifier);
673
725
  return [
674
726
  `Router — routing ${view.mode === 'auto' ? 'on' : 'off'}`,
727
+ ...(config.provider !== 'anthropic' ? [`Provider: ${config.provider} · ${config.nativePath}`] : []),
675
728
  ...(view.routingMode ? [`Mode: ${modeLabel(view.routingMode)}`] : []),
676
729
  ...(view.projectError ? [`Ignored: ${view.projectError}`] : []),
677
730
  `Native model: ${view.nativeModel}`,
@@ -680,6 +733,7 @@ function detailText(config, view) {
680
733
  `Reason: ${view.reason}`,
681
734
  ...activityDetailLines(config, view),
682
735
  storeAgreementLine(view),
736
+ ...[unpricedLine(view.activityMetrics)].filter(Boolean),
683
737
  savingsLine(view),
684
738
  view.error || missing ? classifierStatus(config, view.error ?? missing) : `${activeClassifier(config).label} ready`,
685
739
  `Context: ${view.contextKnown ? `${view.contextTokens} tokens (estimate)` : 'unknown'}`,
@@ -759,13 +813,23 @@ async function decideTurn($, router, e, signal, step) {
759
813
  $.session.messages({ as: 'api' }),
760
814
  ]);
761
815
  if (!(await live())) return null;
762
- const facts = nativeFacts(cfg, loop, {
763
- messages,
764
- prompt: router.prompts.get(e.turnId),
765
- effort: e.effort,
766
- turnId: e.turnId,
767
- contextTokens: context.tokens,
768
- });
816
+ const origin = router.turnOrigins.get(e.turnId) ?? 'unknown';
817
+ // A progress turn is the same task (sameTaskOf).
818
+ const facts = {
819
+ ...nativeFacts(cfg, loop, {
820
+ messages,
821
+ prompt: router.prompts.get(e.turnId),
822
+ effort: e.effort,
823
+ turnId: e.turnId,
824
+ contextTokens: context.tokens,
825
+ }),
826
+ progress: isProgressOrigin(origin),
827
+ };
828
+ const asked = progressInput(
829
+ facts,
830
+ { goal: router.prompts.get(e.turnId), note: router.progressNotes.get(e.turnId) },
831
+ cfg.context.recentTurns,
832
+ );
769
833
  await updateView($, router, {
770
834
  phase: 'choosing',
771
835
  activeTurnId: e.turnId,
@@ -781,8 +845,8 @@ async function decideTurn($, router, e, signal, step) {
781
845
  config: cfg,
782
846
  apiKey: credentials.apiKey,
783
847
  endpoint: credentials.endpoint,
784
- prompt: facts.prompt,
785
- turns: facts.turns,
848
+ prompt: asked.prompt,
849
+ turns: asked.turns,
786
850
  signal: controller.signal,
787
851
  });
788
852
  // The wait for advice alone, comparable with the activity probe's p95; the routing after it is not the classifier's.
@@ -811,11 +875,27 @@ async function decideTurn($, router, e, signal, step) {
811
875
  $.ui.toast(switchToast(cfg, previous, selected.decision, selected.decision.estimate));
812
876
  const activity = turnActivity(cfg, result.advice, previous, selected.decision);
813
877
  const routingMode = step.cfg.routingMode;
878
+ addDecision(
879
+ router,
880
+ e.turnId,
881
+ decisionRow({
882
+ at: Date.now(),
883
+ kind: 'start',
884
+ origin,
885
+ mode: pin ? null : routingMode.mode,
886
+ advice: result.advice,
887
+ error: result.error,
888
+ decision: selected.decision,
889
+ facts,
890
+ sameTask: sameTaskOf(cfg, result.advice, facts),
891
+ }),
892
+ );
814
893
  // One line per decision in Claude Code's debug log, so a later replay can compare modes. No prompt text.
815
894
  $.ui.log(
816
895
  `router decision ${JSON.stringify({
817
896
  mode: routingMode.mode,
818
897
  modeSource: routingMode.source,
898
+ origin,
819
899
  classified: result.advice?.choice ?? null,
820
900
  tier: selected.decision.tier,
821
901
  reason: selected.decision.reason,
@@ -842,6 +922,7 @@ async function decideTurn($, router, e, signal, step) {
842
922
  outputTokens: 0,
843
923
  routedUsd: null,
844
924
  pricedRequests: 0,
925
+ unpriced: {},
845
926
  routes: {},
846
927
  });
847
928
  await updateView($, router, {
@@ -912,9 +993,23 @@ async function moveOnObserved($, router, cfg, loop, e, context) {
912
993
  const messages = await transcript($);
913
994
  if (!messages) return loop;
914
995
  const facts = stepFacts(cfg, router, loop, e, messages, context);
915
- const observed = observedActivity(messages, Math.max(promptIndex(messages), (loop.observedFrom ?? 0) - 1));
996
+ const observed = routingBucket(
997
+ observedActivity(messages, Math.max(promptIndex(messages), (loop.observedFrom ?? 0) - 1)),
998
+ );
916
999
  const moved = observedMove(cfg, loop, { observed, facts, contextKnown: context.known, now: Date.now() });
917
1000
  if (moved === loop) return loop;
1001
+ addDecision(
1002
+ router,
1003
+ e.turnId,
1004
+ decisionRow({
1005
+ at: Date.now(),
1006
+ kind: 'observed',
1007
+ origin: router.turnOrigins.get(e.turnId) ?? 'unknown',
1008
+ mode: cfg.routingMode?.mode ?? null,
1009
+ decision: moved.decision,
1010
+ facts,
1011
+ }),
1012
+ );
918
1013
  $.ui.toast(switchToast(cfg, loop.decision, moved.decision, moved.decision.estimate));
919
1014
  // Replies from here on are labelled with the moved activity; the classifier's answer stays as recorded.
920
1015
  const turn = router.turnActivities.get(e.turnId);
@@ -930,7 +1025,7 @@ async function moveOnObserved($, router, cfg, loop, e, context) {
930
1025
  // Inside a turn the classifier is asked again every `policy.reviewEveryRequests` requests, in the background: a step
931
1026
  // never waits for it. The answer applies at the first step after it arrives, as a decision on the same task
932
1027
  // (sameTaskOf), so the tier and the activity can move either way: up on the usual votes, down only past the dwell and a
933
- // passed verification. Pinned turns and a native fallback are left alone; a failed read or ask changes nothing.
1028
+ // checkpoint (completedSince). Pinned turns and a native fallback are left alone; a failed read or ask changes nothing.
934
1029
  async function reviewMidTurn($, router, cfg, loop, e, { context, nativeModel, availableModels }) {
935
1030
  const review = router.reviews.get(e.turnId);
936
1031
  if (review?.answer) {
@@ -952,6 +1047,20 @@ async function reviewMidTurn($, router, cfg, loop, e, { context, nativeModel, av
952
1047
  now: Date.now(),
953
1048
  });
954
1049
  const previous = loop.decision;
1050
+ addDecision(
1051
+ router,
1052
+ e.turnId,
1053
+ decisionRow({
1054
+ at: Date.now(),
1055
+ kind: 'review',
1056
+ origin: router.turnOrigins.get(e.turnId) ?? 'unknown',
1057
+ mode: cfg.routingMode?.mode ?? null,
1058
+ advice,
1059
+ decision: selected.decision,
1060
+ facts,
1061
+ sameTask: sameTaskOf(cfg, advice, facts),
1062
+ }),
1063
+ );
955
1064
  if (previous && (previous.model !== selected.decision.model || previous.effort !== selected.decision.effort)) {
956
1065
  $.ui.toast(switchToast(cfg, previous, selected.decision, selected.decision.estimate));
957
1066
  const turn = router.turnActivities.get(e.turnId);
@@ -1012,7 +1121,7 @@ async function reviewMidTurn($, router, cfg, loop, e, { context, nativeModel, av
1012
1121
  }
1013
1122
 
1014
1123
  // 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.
1015
- async function publishReply($, router, turnId, response, tier, route, routedUsd) {
1124
+ async function publishReply($, router, turnId, response, tier, route, routedUsd, cause = null) {
1016
1125
  const turn = router.turnActivities.get(turnId);
1017
1126
  const metrics = responseMetrics(router.view, response, tier, Date.now());
1018
1127
  await updateView($, router, metrics);
@@ -1024,6 +1133,7 @@ async function publishReply($, router, turnId, response, tier, route, routedUsd)
1024
1133
  outputTokens: turn.outputTokens + (metrics.outputTokens ?? 0),
1025
1134
  routedUsd: Number.isFinite(routedUsd) ? (turn.routedUsd ?? 0) + routedUsd : turn.routedUsd,
1026
1135
  pricedRequests: turn.pricedRequests + (Number.isFinite(routedUsd) ? 1 : 0),
1136
+ unpriced: cause ? { ...turn.unpriced, [cause]: (turn.unpriced?.[cause] ?? 0) + 1 } : turn.unpriced,
1027
1137
  routes: tier ? { ...turn.routes, [route]: (turn.routes[route] ?? 0) + 1 } : turn.routes,
1028
1138
  });
1029
1139
  }
@@ -1048,7 +1158,23 @@ async function observeRouted($, router, { turnId, cfg, loop, loopVersion, reques
1048
1158
  // A substituted reply is not the tier's: the strip and trend must not count it as one.
1049
1159
  const tier = isSameModel(request.model, response.usage?.model) ? loop.decision.tier : null;
1050
1160
  const route = `${request.model}@${request.effort ?? 'session'}`;
1051
- await publishReply($, router, turnId, response, tier, route, compared?.reply?.routedUsd ?? null);
1161
+ // Why the usage record leaves this reply out, when it does (UNPRICED_CAUSES).
1162
+ const observedUsd = compared?.reply?.routedUsd ?? observedReplyUsd(cfg, response.usage, compared?.ttl);
1163
+ const cause = !compared
1164
+ ? response.usage?.model
1165
+ ? 'error'
1166
+ : 'usage'
1167
+ : compared.reply
1168
+ ? null
1169
+ : observedUsd !== null
1170
+ ? 'comparison'
1171
+ : (unpricedCause(cfg, {
1172
+ usage: response.usage,
1173
+ served: { model: response.usage.model, effort: request.effort ?? null },
1174
+ yours: { model: nativeModel },
1175
+ ttl: compared.ttl,
1176
+ }) ?? 'error');
1177
+ await publishReply($, router, turnId, response, tier, route, observedUsd, cause);
1052
1178
  // Kept by model id, under the model that served it: a substitute's cost is not the requested model's, and a models
1053
1179
  // key can name another model later.
1054
1180
  const idOf = (model) => modelSpec(cfg, model)?.id ?? model;
@@ -1092,14 +1218,16 @@ async function compareYours($, router, loop, response, servedEffort, nativeModel
1092
1218
  try {
1093
1219
  if (!response.usage?.model) return null;
1094
1220
  const view = router.view ?? (await readView($, router));
1095
- return compareModels(cfg, loop.yoursBy ?? {}, {
1221
+ const ttl = await cacheTtlOf($);
1222
+ const compared = compareModels(cfg, loop.yoursBy ?? {}, {
1096
1223
  usage: response.usage,
1097
1224
  served: { model: response.usage.model, effort: servedEffort },
1098
1225
  effort: view.nativeEffort ?? null,
1099
- ttl: await cacheTtlOf($),
1226
+ ttl,
1100
1227
  now: Date.now(),
1101
1228
  yours: nativeModel,
1102
1229
  });
1230
+ return { ...compared, ttl };
1103
1231
  } catch {
1104
1232
  return null;
1105
1233
  }
@@ -1138,6 +1266,140 @@ async function flushUsage($, router, entries, switched) {
1138
1266
  } catch {}
1139
1267
  }
1140
1268
 
1269
+ // A turn's prompt, its origin and the classifier's request text. A progress turn asks about the goal it serves, with
1270
+ // its report as dialogue (progressInput); without a goal from this session it reads as before. A goal origin's prompt
1271
+ // becomes the goal.
1272
+ async function startTurn($, router, e) {
1273
+ const text = clip(e.text, router.config.context.maxTextChars);
1274
+ const origin = originOfTurn(router, e.text);
1275
+ router.turnOrigins.set(e.turnId, origin);
1276
+ const sessionId = await $.session.id();
1277
+ if (isProgressOrigin(origin) && router.goal?.sessionId === sessionId) {
1278
+ router.prompts.set(e.turnId, router.goal.text);
1279
+ router.progressNotes.set(e.turnId, text);
1280
+ return;
1281
+ }
1282
+ router.prompts.set(e.turnId, text);
1283
+ if (isGoalOrigin(origin)) router.goal = { sessionId, text };
1284
+ }
1285
+
1286
+ // The engine stamps each prompt with where it came from (PromptOrigin); turn.start does not carry it. An idle
1287
+ // submission starts its turn inside next(e), so the turn takes `submitting`; one queued behind a running turn starts
1288
+ // later, or is delivered into it, and waits in `origins` under the text that entered. Bookkeeping only: the prompt
1289
+ // passes on unchanged, and nothing here throws after next(e).
1290
+ async function submitPrompt(router, e, next) {
1291
+ const entry = { kind: originKind(e.origin), started: false };
1292
+ const outer = router.submitting;
1293
+ router.submitting = entry;
1294
+ try {
1295
+ const result = await next(e);
1296
+ if (!entry.started && typeof result?.text === 'string' && !result.drop)
1297
+ router.origins = queueOrigin(router.origins, { kind: entry.kind, text: result.text, at: Date.now() });
1298
+ return result;
1299
+ } finally {
1300
+ router.submitting = outer;
1301
+ }
1302
+ }
1303
+
1304
+ // One decision row added to the turn's, bounded per turn (addTurnRow).
1305
+ function addDecision(router, turnId, row) {
1306
+ router.turnDecisions.set(turnId, addTurnRow(router.turnDecisions.get(turnId) ?? [], row));
1307
+ }
1308
+
1309
+ // The origin of a turn starting with `text`: the submission whose next(e) is running, once, else the oldest queued one
1310
+ // with that text, else 'unknown'.
1311
+ function originOfTurn(router, text) {
1312
+ if (router.submitting && !router.submitting.started) {
1313
+ router.submitting.started = true;
1314
+ return router.submitting.kind;
1315
+ }
1316
+ const taken = takeOrigin(router.origins, text, Date.now());
1317
+ router.origins = taken.queue;
1318
+ return taken.kind;
1319
+ }
1320
+
1321
+ // A finished turn's decision rows and its end row, added to this session's record. Telemetry never breaks a turn: a
1322
+ // failed read or write loses this turn's rows. A record from before the last reset reads as empty, and rows read
1323
+ // before a Reset in this session are not written back.
1324
+ async function flushDecisions($, router, turnId, turn) {
1325
+ const rows = router.turnDecisions.get(turnId) ?? [];
1326
+ router.turnDecisions.delete(turnId);
1327
+ router.turnOrigins.delete(turnId);
1328
+ router.progressNotes.delete(turnId);
1329
+ if (!rows.length) return;
1330
+ try {
1331
+ const resets = router.statsResets;
1332
+ const sessionId = await $.session.id();
1333
+ if (turn && turn.sessionId !== sessionId) return;
1334
+ const key = `${DECISIONS_PREFIX}${sessionId}`;
1335
+ const resetAt = await $.store.get(SAVINGS_RESET_KEY);
1336
+ if (router.decisionRecord?.sessionId !== sessionId)
1337
+ router.decisionRecord = { sessionId, record: readDecisions(await $.store.get(key)) };
1338
+ const held = router.decisionRecord;
1339
+ const now = Date.now();
1340
+ const end = turn
1341
+ ? [
1342
+ endRow({
1343
+ at: now,
1344
+ // With activity routing off recordActivity does not run, so the bucket is read here.
1345
+ observed: turn.observed ?? (await turnBucket($)),
1346
+ requests: turn.requests,
1347
+ priced: turn.pricedRequests,
1348
+ unpriced: turn.unpriced,
1349
+ }),
1350
+ ]
1351
+ : [];
1352
+ const record = appendDecisions(decisionsAfterReset(held.record, resetAt), [...rows, ...end], now);
1353
+ if (router.statsResets !== resets || router.decisionRecord !== held) return;
1354
+ held.record = record;
1355
+ await $.store.set(key, record);
1356
+ } catch {}
1357
+ }
1358
+
1359
+ // The bucket of the turn the transcript ends with (observedActivity), or null when it cannot be read.
1360
+ async function turnBucket($) {
1361
+ const messages = await transcript($);
1362
+ const start = messages ? promptIndex(messages) : -1;
1363
+ return start < 0 ? null : observedActivity(messages, start);
1364
+ }
1365
+
1366
+ // Other sessions' decision records past their retention or the record bound (prunedDecisions), each read again just
1367
+ // before its delete, so a session that wrote meanwhile keeps its record.
1368
+ async function pruneDecisionRecords($) {
1369
+ try {
1370
+ const own = `${DECISIONS_PREFIX}${await $.session.id()}`;
1371
+ const keys = (await $.store.keys()).filter((key) => key.startsWith(DECISIONS_PREFIX) && key !== own);
1372
+ const values = await Promise.all(keys.map((key) => $.store.get(key)));
1373
+ const gone = prunedDecisions(
1374
+ keys.map((key, i) => [key, values[i]]),
1375
+ Date.now(),
1376
+ );
1377
+ await Promise.allSettled(
1378
+ [...gone].map(async (key) => {
1379
+ const current = await $.store.get(key);
1380
+ if (JSON.stringify(current) === JSON.stringify(values[keys.indexOf(key)])) await $.store.delete(key);
1381
+ }),
1382
+ );
1383
+ } catch {}
1384
+ }
1385
+
1386
+ // `/router decisions [n]`: this session's newest routing decisions, the running turn's included.
1387
+ async function decisionsText($, router, value) {
1388
+ const n = Math.min(MAX_ROWS, Math.max(1, Number.parseInt(value, 10) || 20));
1389
+ try {
1390
+ const sessionId = await $.session.id();
1391
+ const stored =
1392
+ router.decisionRecord?.sessionId === sessionId
1393
+ ? router.decisionRecord.record
1394
+ : readDecisions(await $.store.get(`${DECISIONS_PREFIX}${sessionId}`));
1395
+ const resetAt = await $.store.get(SAVINGS_RESET_KEY);
1396
+ const pending = [...router.turnDecisions.values()].flat();
1397
+ return decisionLines([...decisionsAfterReset(stored, resetAt).rows, ...pending], n).join('\n');
1398
+ } catch {
1399
+ return 'Routing decisions could not be read.';
1400
+ }
1401
+ }
1402
+
1141
1403
  // A finished turn's activity stats: the session counts in the view and the counts kept across sessions. Stats never
1142
1404
  // break a turn: a failed read or write loses this turn's counts. Readings already in the session's metrics record stay
1143
1405
  // in memory after a failed write and go out with the next turn that adds a reading.
@@ -1148,6 +1410,8 @@ async function recordActivity($, router, turn) {
1148
1410
  const start = promptIndex(messages);
1149
1411
  if (start < 0) return;
1150
1412
  const observed = observedActivity(messages, start);
1413
+ // The turn's end row reads it (flushDecisions).
1414
+ turn.observed = observed;
1151
1415
  const view = router.view ?? (await readView($, router));
1152
1416
  const manual = (await modeOf($, router)) === 'manual';
1153
1417
  // The session may have changed during the reads; this turn is not the new session's.
@@ -1180,7 +1444,12 @@ async function recordActivity($, router, turn) {
1180
1444
  // empties the view; these counts are older than it. Each record is written on its own: a failed write of one
1181
1445
  // keeps the other.
1182
1446
  const stats = { predicted: turn.predicted, observed, runEnded: ended, lateral: turn.lateral };
1183
- const metrics = { classifier: turn.classifier, adviceMs: turn.adviceMs, downMove: down.event };
1447
+ const metrics = {
1448
+ classifier: turn.classifier,
1449
+ adviceMs: turn.adviceMs,
1450
+ downMove: down.event,
1451
+ unpriced: turn.unpriced,
1452
+ };
1184
1453
  const shown = await Promise.all([
1185
1454
  addToLedger($, router, 'activity', (record, now) => recordStore(record, stats, now)).catch(() => false),
1186
1455
  addToLedger($, router, 'metrics', (record, now) => recordMetrics(record, { ...metrics, now })).catch(() => false),
@@ -1441,7 +1710,7 @@ function paneActions($, router, view) {
1441
1710
  };
1442
1711
  };
1443
1712
  const save = async (change, saved) => {
1444
- const result = await saveConfig($, router.config.nativePath, change);
1713
+ const result = await saveConfig($, router.config, change);
1445
1714
  if (result.error) return updateView($, router, { notice: result.error });
1446
1715
  const drafts = router.view ?? view;
1447
1716
  const reset = await adopt(result.config);
@@ -1457,7 +1726,7 @@ function paneActions($, router, view) {
1457
1726
  return updateView($, router, {
1458
1727
  ...patch,
1459
1728
  notice: pending
1460
- ? `${what === 'route' ? 'Route' : 'Policy'} defaults loaded. Save removes your ${what} overrides from router.json.`
1729
+ ? `${what === 'route' ? 'Route' : 'Policy'} defaults loaded. Save removes your ${what} overrides from ${router.config.nativePath?.split('/').at(-1) ?? 'router.json'}.`
1461
1730
  : `${what === 'route' ? 'Routes' : 'Policy'} already at defaults.`,
1462
1731
  });
1463
1732
  };
@@ -1568,6 +1837,8 @@ function paneActions($, router, view) {
1568
1837
  router.run = null;
1569
1838
  router.afterDown = null;
1570
1839
  router.turnUsage.clear();
1840
+ router.turnDecisions.clear();
1841
+ router.decisionRecord = null;
1571
1842
  for (const [id, agent] of router.agents) router.agents.set(id, flushedAgent(agent));
1572
1843
  // Every session's records. The marker is written first, so a session still holding its record from before the
1573
1844
  // reset drops it, unless that record's first count has the reset's millisecond or the clock moved back across
@@ -1575,8 +1846,10 @@ function paneActions($, router, view) {
1575
1846
  const clearRecords = async () => {
1576
1847
  const resetAt = Date.now();
1577
1848
  await $.store.set(SAVINGS_RESET_KEY, resetAt);
1578
- const keys = (await $.store.keys()).filter((key) =>
1579
- Object.values(LEDGERS).some(({ prefix, legacy }) => key.startsWith(prefix) || key === legacy),
1849
+ const keys = (await $.store.keys()).filter(
1850
+ (key) =>
1851
+ key.startsWith(DECISIONS_PREFIX) ||
1852
+ Object.values(LEDGERS).some(({ prefix, legacy }) => key.startsWith(prefix) || key === legacy),
1580
1853
  );
1581
1854
  await Promise.all(keys.map((key) => $.store.delete(key)));
1582
1855
  for (const kind of LEDGER_KINDS)
@@ -1604,16 +1877,21 @@ function paneActions($, router, view) {
1604
1877
  discardRouting: () => updateView($, router, { routeDraft: null, tuning: null, tuningBase: null, notice: null }),
1605
1878
  // Routes only: pending activity edits and the mode stay in the draft.
1606
1879
  resetRoutes: () =>
1607
- loadDefaults(
1608
- {
1609
- routeDraft: {
1610
- ...routeDraftOf(router.config, router.view ?? view),
1611
- ...structuredClone({ routes: DEFAULTS.routes, baselineTier: DEFAULTS.baselineTier }),
1612
- base: routeDraftOf(router.config, {}).base,
1613
- },
1614
- },
1615
- 'route',
1616
- ),
1880
+ !Object.keys(defaultsFor(router.config.provider).routes).length
1881
+ ? updateView($, router, { notice: 'No built-in route defaults for this provider.' })
1882
+ : loadDefaults(
1883
+ {
1884
+ routeDraft: {
1885
+ ...routeDraftOf(router.config, router.view ?? view),
1886
+ ...structuredClone({
1887
+ routes: defaultsFor(router.config.provider).routes,
1888
+ baselineTier: defaultsFor(router.config.provider).baselineTier,
1889
+ }),
1890
+ base: routeDraftOf(router.config, {}).base,
1891
+ },
1892
+ },
1893
+ 'route',
1894
+ ),
1617
1895
  tune: (key, value) =>
1618
1896
  updateView($, router, {
1619
1897
  tuning: { ...(router.view ?? view).tuning, [key]: value },
@@ -1623,7 +1901,7 @@ function paneActions($, router, view) {
1623
1901
  resetPolicy: () =>
1624
1902
  loadDefaults(
1625
1903
  // The draft is replaced whole, so it starts from the saved values, not from an older draft's base.
1626
- { tuning: tuningOf(DEFAULTS), tuningBase: tuningOf(router.config) },
1904
+ { tuning: tuningOf(defaultsFor(router.config.provider)), tuningBase: tuningOf(router.config) },
1627
1905
  'policy',
1628
1906
  ),
1629
1907
  classifier: (id) => {
@@ -1658,6 +1936,13 @@ async function endSession($, router) {
1658
1936
  for (const controller of router.controllers) controller.abort();
1659
1937
  router.decisions.clear();
1660
1938
  router.prompts.clear();
1939
+ router.turnOrigins.clear();
1940
+ router.progressNotes.clear();
1941
+ router.turnDecisions.clear();
1942
+ router.origins = [];
1943
+ router.submitting = null;
1944
+ router.goal = null;
1945
+ router.decisionRecord = null;
1661
1946
  router.turnConfigs.clear();
1662
1947
  router.turnPins.clear();
1663
1948
  router.turnActivities.clear();
@@ -1693,6 +1978,18 @@ async function endSession($, router) {
1693
1978
  };
1694
1979
  }
1695
1980
 
1981
+ async function imagesOf($, config, decision) {
1982
+ if (modelSpec(config, decision?.model)?.imageInput !== false) return false;
1983
+ const messages = await transcript($);
1984
+ return messages === null || hasImages(messages);
1985
+ }
1986
+
1987
+ function configurationError(error) {
1988
+ if (error.message?.endsWith(MIGRATION_HINT))
1989
+ return 'router.json needs migration; run the plugin scripts/migrate-config.mjs with your router.json path';
1990
+ return error.message === 'selected provider router file is missing' ? error.message : 'invalid router configuration';
1991
+ }
1992
+
1696
1993
  export function register(on, options) {
1697
1994
  const router = createRouter(options);
1698
1995
 
@@ -1700,8 +1997,9 @@ export function register(on, options) {
1700
1997
  router.definitions.clear();
1701
1998
  await $.command.register({
1702
1999
  name: 'router',
1703
- description: 'Open the Router pane, or switch routing: auto, off, pin <tier>, activities <mode>, mode <mode>.',
1704
- argumentHint: '[auto|off|pin <tier>|activities off|on|mode cost|balanced|quality|default]',
2000
+ description:
2001
+ 'Open the Router pane, or switch routing: auto, off, pin <tier>, activities <mode>, mode <mode>; decisions [n] lists the last routing decisions.',
2002
+ argumentHint: '[auto|off|pin <tier>|activities off|on|mode cost|balanced|quality|default|decisions [n]]',
1705
2003
  immediate: true,
1706
2004
  });
1707
2005
  const model = await $.session.model();
@@ -1738,12 +2036,11 @@ export function register(on, options) {
1738
2036
  usagePeriod: await periodOf($),
1739
2037
  ...(await storeView($, router)),
1740
2038
  });
2039
+ await pruneDecisionRecords($);
1741
2040
  } catch (error) {
1742
2041
  await updateView($, router, {
1743
2042
  phase: 'unavailable',
1744
- error: error.message?.endsWith(MIGRATION_HINT)
1745
- ? 'router.json needs migration; run the plugin scripts/migrate-config.mjs with your router.json path'
1746
- : 'invalid router configuration',
2043
+ error: configurationError(error),
1747
2044
  });
1748
2045
  }
1749
2046
  return next(e);
@@ -1771,10 +2068,12 @@ export function register(on, options) {
1771
2068
 
1772
2069
  on('turn.start', async ($, e, next) => {
1773
2070
  await fixTurnConfig($, router, e.turnId);
1774
- router.prompts.set(e.turnId, clip(e.text, router.config.context.maxTextChars));
2071
+ await startTurn($, router, e);
1775
2072
  return next(e);
1776
2073
  });
1777
2074
 
2075
+ on('prompt.submit', (_$, e, next) => submitPrompt(router, e, next));
2076
+
1778
2077
  // A hook failure spawns the agent as Claude Code would; next(e) replays a spawn already made. agent.spawn and a
1779
2078
  // catchable on() are in the 2.1.293 build types, not checked on 2.1.289: an engine without them still loads routing.
1780
2079
  try {
@@ -1840,6 +2139,7 @@ export function register(on, options) {
1840
2139
  loop = await reviewMidTurn($, router, cfg, loop, e, { context, nativeModel, availableModels });
1841
2140
  loop = await moveOnObserved($, router, cfg, loop, e, context);
1842
2141
  loop = continueRoute(cfg, loop, {
2142
+ hasImages: await imagesOf($, cfg, loop.decision),
1843
2143
  nativeModel,
1844
2144
  contextTokens: context.tokens,
1845
2145
  contextKnown: context.known,
@@ -1889,6 +2189,7 @@ export function register(on, options) {
1889
2189
  const entries = router.turnUsage.get(e.turnId);
1890
2190
  router.turnUsage.delete(e.turnId);
1891
2191
  if (entries) await flushUsage($, router, entries, turn?.switched ?? null);
2192
+ await flushDecisions($, router, e.turnId, turn);
1892
2193
  return next(e);
1893
2194
  });
1894
2195