@alexeiled/claude-router 1.7.0 → 1.7.2

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.
package/lib/panel.mjs CHANGED
@@ -1,5 +1,5 @@
1
1
  import { compareRoutes } from './activity.mjs';
2
- import { readStore, storeSummary } from './activity-stats.mjs';
2
+ import { latencyP95, mostlyOn, readMetrics, readStore, storeSummary } from './activity-stats.mjs';
3
3
  import {
4
4
  ACTIVITIES,
5
5
  ACTIVITY_MODES,
@@ -30,7 +30,7 @@ import {
30
30
  missingText,
31
31
  modelName,
32
32
  percent,
33
- REASONS,
33
+ probeText,
34
34
  routeLabel,
35
35
  routeName,
36
36
  savingsColor,
@@ -43,6 +43,7 @@ import {
43
43
  unavailableReason,
44
44
  usageMetrics,
45
45
  usd,
46
+ whyText,
46
47
  yourModel,
47
48
  } from './display.mjs';
48
49
  import { cellForModel, isSameModel } from './route.mjs';
@@ -220,7 +221,7 @@ function nowTab(ui, config, view, usage, actions) {
220
221
  reading.others.length ? ui.dim(` ${reading.others.join(' · ')}`) : null,
221
222
  )
222
223
  : null,
223
- ui.line('Why ', REASONS[view.reason] ?? view.reason ?? 'ready'),
224
+ ui.line('Why ', whyText(config, view)),
224
225
  route ? ui.line('Route ', route) : null,
225
226
  served
226
227
  ? ui.line(ui.text('Served ', { color: 'yellow' }), `${modelName(view.actualModel)} · native fallback`)
@@ -650,10 +651,11 @@ function choice(ui, key, value, format, pick) {
650
651
  function classifierTab(ui, config, view, _usage, actions) {
651
652
  const active = activeClassifier(config);
652
653
  const health = view.health ?? { failures: 0, pausedUntil: 0 };
653
- const rows = Object.entries(config.classifiers).map(([id, entry]) => {
654
+ const rows = Object.entries(config.classifiers).flatMap(([id, entry]) => {
654
655
  const isActive = id === config.classifier;
655
656
  const missing = missingCredentials(config, view, id);
656
- return ui.line(
657
+ const probe = probeText(config, id);
658
+ const row = ui.line(
657
659
  ui.Button({
658
660
  key: `classifier-${id}`,
659
661
  label: `${isActive ? '◉' : '○'} ${entry.label.padEnd(11)}`,
@@ -671,6 +673,7 @@ function classifierTab(ui, config, view, _usage, actions) {
671
673
  ? ui.dim(` ${view.adviceMs} ms`)
672
674
  : null,
673
675
  );
676
+ return probe ? [row, ui.dim(` ${probe}`)] : [row];
674
677
  });
675
678
  return [
676
679
  ui.line(ui.head('CLASSIFIER'), ui.dim(' · applies next turn · saves at once')),
@@ -764,10 +767,11 @@ function shadowLine(shadow) {
764
767
  return `${counted} · est. ${difference(shadow.minUsd)} … ${difference(shadow.maxUsd)}${some} at list prices`;
765
768
  }
766
769
 
767
- // The counts kept across sessions, read from the store as last loaded. Agreement uses the classifier's raw answer, so it
768
- // can differ from the session's.
769
- function storeUsage(ui, store) {
770
+ // The counts kept across sessions, read from the stores as last loaded. Agreement uses the classifier's raw answer, so
771
+ // it can differ from the session's.
772
+ function storeUsage(ui, config, store, metrics) {
770
773
  const summary = storeSummary(readStore(store));
774
+ const { latency, downMoves } = readMetrics(metrics);
771
775
  const out = [ui.head('ACROSS SESSIONS · since the last reset')];
772
776
  if (summary.labelled === 0) return [...out, ui.dim(' no turns recorded yet')];
773
777
  out.push(ui.text(`Labelled ${summary.labelled} turns`));
@@ -787,20 +791,37 @@ function storeUsage(ui, store) {
787
791
  );
788
792
  const { taken, refused } = summary.lateral;
789
793
  if (taken + refused > 0) out.push(ui.text(`Activity moves ${taken} taken · ${refused} refused`));
794
+ const { moves, escalations } = downMoves;
795
+ if (moves > 0)
796
+ out.push(
797
+ ui.text(`Escalations after a cheaper activity move: ${escalations} in ${moves} move${moves === 1 ? '' : 's'}`),
798
+ );
799
+ const p95 = latencyP95(Object.hasOwn(latency, config.classifier) ? latency[config.classifier] : null);
800
+ if (p95)
801
+ out.push(
802
+ ui.text(
803
+ `Latency ${classifierLabel(config)} p95 ${p95.over ? '>' : '≤'} ${p95.ms} ms · ${p95.turns} turn${p95.turns === 1 ? '' : 's'}`,
804
+ ),
805
+ );
790
806
  if (summary.shadow.turns > 0) out.push(ui.text(shadowLine(summary.shadow)));
791
807
  return out;
792
808
  }
793
809
 
794
- // Session counts by activity, the switches by cause, the tool agreement and the shadow readout, then the counts kept
810
+ // The ACTIVITY table's columns before the cost, and the cost column.
811
+ const ACTIVITY_TABLE = 45;
812
+ const ACTIVITY_COST = 11;
813
+
814
+ // Session counts by activity: turns, requests, share, the estimated list price of their replies and the route most of
815
+ // them ran on; the switches by cause, the tool agreement and the shadow readout, then the counts kept
795
816
  // across sessions. Reset is always offered: the counts kept across sessions may exist before this session has any.
796
- function activityUsage(ui, config, view, actions) {
817
+ function activityUsage(ui, config, view, actions, columns) {
797
818
  const stats = view.activityStats ?? null;
798
819
  const mode = config.activityRouting;
799
820
  const reset = ui.line(
800
821
  ui.Button({ key: 'reset-stats', label: 'Reset stats', onPress: actions.resetStats }),
801
822
  ui.dim(' clears activity stats and routing vs your model, all sessions'),
802
823
  );
803
- const across = [ui.text(' '), ...storeUsage(ui, view.activityStore)];
824
+ const across = [ui.text(' '), ...storeUsage(ui, config, view.activityStore, view.activityMetrics)];
804
825
  if (mode === 'off' && !stats)
805
826
  return [
806
827
  ui.head('ACTIVITY · activity routing off'),
@@ -813,8 +834,26 @@ function activityUsage(ui, config, view, actions) {
813
834
  if (!rows.length) out.push(ui.dim(' no activity readings yet'));
814
835
  else {
815
836
  const total = rows.reduce((sum, [, counts]) => sum + counts.turns, 0);
837
+ // A partial sum would read as the whole: a cost shows only when every reply had a price.
838
+ const cost = (counts) =>
839
+ Number.isFinite(counts.routedUsd) && counts.pricedRequests === counts.requests ? usd(counts.routedUsd) : '—';
840
+ const route = (counts) => {
841
+ const key = mostlyOn(counts);
842
+ if (!key) return '—';
843
+ const at = key.lastIndexOf('@');
844
+ const effort = key.slice(at + 1);
845
+ return routeLabel(key.slice(0, at), effort === 'session' ? null : effort);
846
+ };
847
+ // A narrow pane drops "mostly on", then the cost, before any column it had before them.
848
+ const widest = Math.max('mostly on'.length, ...rows.map(([, counts]) => route(counts).length));
849
+ const fits = (width) => !Number.isFinite(columns) || width <= columns;
850
+ const showCost = fits(ACTIVITY_TABLE + ACTIVITY_COST);
851
+ const showRoute = showCost && fits(ACTIVITY_TABLE + ACTIVITY_COST + 3 + widest);
816
852
  out.push(
817
- ui.dim(` ${''.padEnd(9)}${''.padEnd(10)}${'turns'.padStart(7)}${'requests'.padStart(10)}${'share'.padStart(7)}`),
853
+ ui.dim(
854
+ ` ${''.padEnd(9)}${''.padEnd(10)}${'turns'.padStart(7)}${'requests'.padStart(10)}${'share'.padStart(7)}` +
855
+ `${showCost ? 'est. cost'.padStart(ACTIVITY_COST) : ''}${showRoute ? ' mostly on' : ''}`,
856
+ ),
818
857
  );
819
858
  for (const [name, counts] of rows.sort((a, b) => b[1].turns - a[1].turns)) {
820
859
  const share = counts.turns / total;
@@ -822,14 +861,21 @@ function activityUsage(ui, config, view, actions) {
822
861
  ui.line(
823
862
  ` ${name.padEnd(9)}`,
824
863
  ui.text(bar(share, 1, 10).text, { color: 'cyan' }),
825
- `${String(counts.turns).padStart(7)}${String(counts.requests).padStart(10)}${percent(share).padStart(7)}`,
864
+ `${String(counts.turns).padStart(7)}${String(counts.requests).padStart(10)}${percent(share).padStart(7)}` +
865
+ `${showCost ? cost(counts).padStart(ACTIVITY_COST) : ''}${showRoute ? ` ${route(counts)}` : ''}`,
826
866
  ),
827
867
  );
828
868
  }
829
869
  }
830
870
  if (stats) {
831
871
  const { tier, activity } = stats.switches;
832
- out.push(ui.text(`Switches ${tier + activity} · ${tier} by tier · ${activity} by activity`));
872
+ // Refused moves change no route. The session counts them in `on` only, so moves from before a switch to shadow stay.
873
+ const refused = stats.lateral?.refused ?? 0;
874
+ out.push(
875
+ ui.text(
876
+ `Switches ${tier + activity} · ${tier} by tier · ${activity} by activity${refused ? ` · ${refused} refused` : ''}`,
877
+ ),
878
+ );
833
879
  const { matched, total } = stats.agreement;
834
880
  if (total > 0)
835
881
  out.push(ui.text(`Agreement classifier vs tools: ${matched} of ${total} turns (${percent(matched / total)})`));
@@ -1100,7 +1146,7 @@ function usageTab(ui, config, view, usage, actions, _modelOptions, columns) {
1100
1146
  .filter((limit) => Number.isFinite(limit.percentUsed))
1101
1147
  .map((limit) => ui.gauge(`${limit.kind.replaceAll('_', ' ').padEnd(11)}`, bar(limit.percentUsed, 100), 'used')),
1102
1148
  ui.text(' '),
1103
- ...activityUsage(ui, config, view, actions),
1149
+ ...activityUsage(ui, config, view, actions, columns),
1104
1150
  ui.text(' '),
1105
1151
  ui.head('ESTIMATES · configured list prices'),
1106
1152
  ui.text(`Cache read benefit ${dollars(metrics.cacheBenefit)}`),
@@ -0,0 +1,40 @@
1
+ // Generated by scripts/probe-results.mjs from experiments/mod-router/results/activity-probe-*.json; do not edit.
2
+ // The last checked-in activity probe per classifier id: the model it probed, correct answers of the probes, p95
3
+ // latency in ms, and the UTC date of the run.
4
+ export const PROBE_RESULTS = {
5
+ "clef-flash": {
6
+ "model": "clef-flash",
7
+ "correct": 69,
8
+ "probes": 70,
9
+ "p95Ms": 874,
10
+ "date": "2026-10-09"
11
+ },
12
+ "clef": {
13
+ "model": "clef",
14
+ "correct": 69,
15
+ "probes": 70,
16
+ "p95Ms": 883,
17
+ "date": "2026-10-09"
18
+ },
19
+ "jev": {
20
+ "model": "jev-1.13.0",
21
+ "correct": 70,
22
+ "probes": 70,
23
+ "p95Ms": 299,
24
+ "date": "2026-10-10"
25
+ },
26
+ "ollama": {
27
+ "model": "qwen3.5:9b",
28
+ "correct": 66,
29
+ "probes": 70,
30
+ "p95Ms": 3483,
31
+ "date": "2026-10-09"
32
+ },
33
+ "openai": {
34
+ "model": "gpt-6-luna",
35
+ "correct": 70,
36
+ "probes": 70,
37
+ "p95Ms": 286,
38
+ "date": "2026-10-10"
39
+ }
40
+ };
package/lib/route.mjs CHANGED
@@ -131,7 +131,7 @@ export function chooseRoute(config, loop, input) {
131
131
  facts: { ...facts, lastRoute: from.lastRoute },
132
132
  },
133
133
  );
134
- const { activity, tier, model, effort, reason } = run;
134
+ const { activity, tier, model, effort, reason, lateral } = run;
135
135
  // What the would-route's next request costs against the applied one's; a route priced against itself would
136
136
  // still give a spread, so only a different request is priced.
137
137
  const priced =
@@ -149,7 +149,7 @@ export function chooseRoute(config, loop, input) {
149
149
  input.now,
150
150
  )
151
151
  : null;
152
- wouldRoute = { activity, tier, model, effort, reason, difference };
152
+ wouldRoute = { activity, tier, model, effort, reason, lateral, difference };
153
153
  const stays = pin || !run.tier;
154
154
  would = {
155
155
  lastRoute: stays ? from.lastRoute : run.tier,
@@ -186,7 +186,14 @@ function routeTurn(config, loop, { facts, advice, pin, nativeModel, contextKnown
186
186
  pin || config.activityRouting !== 'on' ? null : chooseActivity(config, advice, incumbent, facts.effort);
187
187
  let result =
188
188
  pin && TIERS.includes(pin)
189
- ? { tier: pin, activity: null, reason: 'pinned', state: { ...loop.state, turn: loop.state.turn + 1 } }
189
+ ? {
190
+ tier: pin,
191
+ activity: null,
192
+ reason: 'pinned',
193
+ lateral: null,
194
+ escalated: false,
195
+ state: { ...loop.state, turn: loop.state.turn + 1 },
196
+ }
190
197
  : decideCell({ config, projected, facts, advice, state: loop.state, now, incumbent, activity });
191
198
  // Without a reliable reading of the context, a route with a smaller window than the last one might overflow.
192
199
  const shrinksUnmeasured = (cell) =>
@@ -203,9 +210,10 @@ function routeTurn(config, loop, { facts, advice, pin, nativeModel, contextKnown
203
210
  if (contextKnown) {
204
211
  const routeFor = (tier) => resolveRoute(config, tier, result.activity);
205
212
  const fitted = fitTier(config, result.tier, costs.nextContextTokens(facts), routeFor);
206
- if (fitted !== result.tier) result = { ...result, tier: fitted, reason: 'context-fit' };
213
+ if (fitted !== result.tier) result = { ...result, tier: fitted, reason: 'context-fit', lateral: null };
207
214
  }
208
- if (shrinksUnmeasured(result)) result = { ...result, ...last, reason: 'context-unknown' };
215
+ // A lateral outcome describes the cell the lateral rule chose; a context or availability override replaces it.
216
+ if (shrinksUnmeasured(result)) result = { ...result, ...last, reason: 'context-unknown', lateral: null };
209
217
  if (!fits(result)) {
210
218
  // A cell labelled with another activity would run, and stick, a route this turn did not choose.
211
219
  const native = cellForModel(config, nativeModel);
@@ -213,7 +221,7 @@ function routeTurn(config, loop, { facts, advice, pin, nativeModel, contextKnown
213
221
  const fallback = cells.find(
214
222
  (cell) => cell && (cell.activity === null || cell.activity === activity) && fits(cell),
215
223
  ) ?? { tier: null, activity: null };
216
- result = { ...result, ...fallback, reason: 'model-unavailable' };
224
+ result = { ...result, ...fallback, reason: 'model-unavailable', lateral: null };
217
225
  }
218
226
  const route = result.tier ? routeOf(result) : null;
219
227
  const model = route ? routeSpec(config, route).id : nativeModel;
@@ -258,9 +266,12 @@ function decideCell({ config, projected, facts, advice, state, now, incumbent, a
258
266
  incumbentRoute: incumbent.route,
259
267
  escalateTo,
260
268
  });
269
+ // `decide` takes the failure's signature whenever it escalates, before the cash gate can hold the move; a later
270
+ // context or availability override keeps the flag.
271
+ const escalated = step.state.escalatedSignature !== state.escalatedSignature;
261
272
  const route = routeFor(step.tier);
262
273
  if (step.tier !== incumbent.tier || sameRequest(config, route, incumbent.route, facts.effort))
263
- return { ...step, activity };
274
+ return { ...step, activity, lateral: null, escalated };
264
275
  const lateral = lateralMove({
265
276
  config: projected,
266
277
  from: incumbent.route,
@@ -273,7 +284,14 @@ function decideCell({ config, projected, facts, advice, state, now, incumbent, a
273
284
  costs,
274
285
  });
275
286
  const activityOf = lateral.move ? activity : incumbent.activity;
276
- return { ...step, activity: activityOf, reason: lateral.reason, estimate: lateral.estimate };
287
+ return {
288
+ ...step,
289
+ activity: activityOf,
290
+ reason: lateral.reason,
291
+ estimate: lateral.estimate,
292
+ lateral: lateral.move ? 'taken' : 'refused',
293
+ escalated,
294
+ };
277
295
  }
278
296
 
279
297
  // A tool continuation keeps the turn's route and activity; only the context or the model list can move it.
package/lib/savings.mjs CHANGED
@@ -10,6 +10,7 @@ import { HISTORY_SHRINK, isSameModel } from './route.mjs';
10
10
  // moment do not overwrite each other.
11
11
  export const SAVINGS_PREFIX = 'savings:v1:';
12
12
  // When Reset stats last ran (ms), from any session: a session may still hold its record from before and write it back.
13
+ // The activity metrics records (METRICS_PREFIX) use it too.
13
14
  export const SAVINGS_RESET_KEY = 'savings:reset:v1';
14
15
  // Fewer replies than this read "too early": one switch and its cache write dominate a short run.
15
16
  export const EARLY_REPLIES = 10;
package/lib/view.mjs CHANGED
@@ -42,6 +42,7 @@ export function initialView(model) {
42
42
  routes: [],
43
43
  activityStats: null,
44
44
  activityStore: null,
45
+ activityMetrics: null,
45
46
  // Routing vs your model: this session's totals and the totals kept across sessions as last read or written.
46
47
  savings: null,
47
48
  savingsStore: null,
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@alexeiled/claude-router",
3
- "version": "1.7.0",
3
+ "version": "1.7.2",
4
4
  "description": "Native Claude Code Mod: model and effort routing for the main conversation, advised by Jev, Clef, Clef Flash, OpenAI or Ollama.",
5
5
  "license": "MIT",
6
6
  "author": "Alexei Ledenev",
@@ -36,6 +36,7 @@
36
36
  "test:plugin": "bash scripts/plugin-test.sh",
37
37
  "format": "tools/node_modules/.bin/biome format --write .",
38
38
  "docs:images": "node scripts/render-doc-images.mjs",
39
+ "probe:results": "node scripts/probe-results.mjs",
39
40
  "pack:dry": "npm pack --dry-run",
40
41
  "prepublishOnly": "npm run check && npm test"
41
42
  }
package/types/index.d.ts CHANGED
@@ -7,6 +7,8 @@ declare module 'claude-code' {
7
7
  type RouterActivityMode = 'off' | 'shadow' | 'on';
8
8
  // A finished turn's bucket, read from its tool calls.
9
9
  type RouterObserved = 'code' | 'docs' | 'ops' | 'read' | 'talk';
10
+ // A route change inside the incumbent's tier: taken, refused (does not pay back, a hold, the cash gate), or none.
11
+ type RouterLateral = 'taken' | 'refused' | null;
10
12
  // Classifier output. `activity` is null when not asked, or missing, malformed or failed.
11
13
  interface RouterAdvice {
12
14
  choice: RouterTier | 'uncertain';
@@ -31,6 +33,7 @@ declare module 'claude-code' {
31
33
  model: string;
32
34
  effort: string | number | null;
33
35
  reason: string;
36
+ lateral: RouterLateral;
34
37
  difference: RouterUsdRange | null;
35
38
  }
36
39
  // Shadow turns, those `on` would route differently, and of those the ones with a `difference`, summed.
@@ -44,11 +47,19 @@ declare module 'claude-code' {
44
47
  requests: number;
45
48
  inputTokens: number;
46
49
  outputTokens: number;
50
+ // The list price of the priced replies (null: none had one), how many replies had a price, and routed replies by
51
+ // `model@effort`; absent in views saved by 1.7.0.
52
+ routedUsd?: number | null;
53
+ pricedRequests?: number;
54
+ routes?: Record<string, number>;
47
55
  }
48
56
  // Per-session activity stats; 'none' counts turns without an applied or accepted activity.
49
57
  interface RouterActivitySession {
50
58
  byActivity: Partial<Record<RouterActivity | 'none', RouterActivityCounts>>;
51
59
  switches: { tier: number; activity: number };
60
+ // Lateral moves taken and refused (by economics, a hold or the cash gate), outside shadow only; absent in views saved
61
+ // by 1.7.0.
62
+ lateral?: { taken: number; refused: number };
52
63
  agreement: { matched: number; total: number };
53
64
  shadow: RouterActivityShadow;
54
65
  }
@@ -61,6 +72,14 @@ declare module 'claude-code' {
61
72
  // A 1.6.0 store has `differs` and `turns` only; readStore fills the rest with zeros.
62
73
  shadow: RouterActivityShadow;
63
74
  }
75
+ // Cross-session readings under store key 'activity:metrics:v1'. Classifier wait per turn by classifier id, in
76
+ // LATENCY_BOUNDS buckets plus one above; at most 8 ids. Cheaper activity moves taken in 'on' and the escalations that
77
+ // followed one.
78
+ interface RouterActivityMetrics {
79
+ version: 1;
80
+ latency: Record<string, number[]>;
81
+ downMoves: { moves: number; escalations: number };
82
+ }
64
83
  interface RouterComparison {
65
84
  candidate: RouterTier;
66
85
  incumbent: RouterTier;
@@ -163,6 +182,7 @@ declare module 'claude-code' {
163
182
  activityStats?: RouterActivitySession | null;
164
183
  // The counts kept across sessions as last read or written.
165
184
  activityStore?: RouterActivityStore | null;
185
+ activityMetrics?: RouterActivityMetrics | null;
166
186
  savings?: RouterSavingsSession | null;
167
187
  savingsStore?: RouterSavingsStore | null;
168
188
  configPath?: string | null;
@@ -213,6 +233,9 @@ declare module 'claude-code' {
213
233
  comparison?: RouterComparison | null;
214
234
  // The applied activity; `wouldRoute` is set only in shadow mode.
215
235
  activity?: RouterActivity | null;
236
+ lateral?: RouterLateral;
237
+ // A failure asked for an escalation this turn, also one the cash gate held or context-fit replaced.
238
+ escalated?: boolean;
216
239
  wouldRoute?: RouterWouldRoute | null;
217
240
  pinned: boolean;
218
241
  requestedPin: RouterTier | null;