@alexeiled/claude-router 1.6.1 → 1.7.1

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.
@@ -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
@@ -9,7 +9,7 @@ const SNAPSHOTS = { 'claude-haiku-4-5': 'claude-haiku-4-5-20251001' };
9
9
 
10
10
  // A request this much smaller than the last means the history was compacted or rewound: the cached prefixes the
11
11
  // observations describe are gone, so they are dropped rather than priced as warm.
12
- const HISTORY_SHRINK = 0.8;
12
+ export const HISTORY_SHRINK = 0.8;
13
13
 
14
14
  // Whether the engine served the requested model, allowing for a dated snapshot of it.
15
15
  export function isSameModel(requested, served) {
@@ -53,6 +53,8 @@ export function emptyLoop(config, model) {
53
53
  turnId: null,
54
54
  decision: null,
55
55
  ineligible: [],
56
+ // Your model's simulated cache for the routing-vs-your-model readout (compareReply in savings.mjs).
57
+ yours: null,
56
58
  };
57
59
  }
58
60
 
@@ -69,6 +71,7 @@ export function resetHistory(loop) {
69
71
  would: loop.would ? { ...loop.would, state: freshState(loop.would.state) } : null,
70
72
  // The active turn keeps its route, pin and fallback suspension; the next turn decides afresh.
71
73
  ineligible: [],
74
+ yours: null,
72
75
  };
73
76
  }
74
77
 
@@ -128,7 +131,7 @@ export function chooseRoute(config, loop, input) {
128
131
  facts: { ...facts, lastRoute: from.lastRoute },
129
132
  },
130
133
  );
131
- const { activity, tier, model, effort, reason } = run;
134
+ const { activity, tier, model, effort, reason, lateral } = run;
132
135
  // What the would-route's next request costs against the applied one's; a route priced against itself would
133
136
  // still give a spread, so only a different request is priced.
134
137
  const priced =
@@ -146,7 +149,7 @@ export function chooseRoute(config, loop, input) {
146
149
  input.now,
147
150
  )
148
151
  : null;
149
- wouldRoute = { activity, tier, model, effort, reason, difference };
152
+ wouldRoute = { activity, tier, model, effort, reason, lateral, difference };
150
153
  const stays = pin || !run.tier;
151
154
  would = {
152
155
  lastRoute: stays ? from.lastRoute : run.tier,
@@ -183,7 +186,14 @@ function routeTurn(config, loop, { facts, advice, pin, nativeModel, contextKnown
183
186
  pin || config.activityRouting !== 'on' ? null : chooseActivity(config, advice, incumbent, facts.effort);
184
187
  let result =
185
188
  pin && TIERS.includes(pin)
186
- ? { 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
+ }
187
197
  : decideCell({ config, projected, facts, advice, state: loop.state, now, incumbent, activity });
188
198
  // Without a reliable reading of the context, a route with a smaller window than the last one might overflow.
189
199
  const shrinksUnmeasured = (cell) =>
@@ -200,14 +210,18 @@ function routeTurn(config, loop, { facts, advice, pin, nativeModel, contextKnown
200
210
  if (contextKnown) {
201
211
  const routeFor = (tier) => resolveRoute(config, tier, result.activity);
202
212
  const fitted = fitTier(config, result.tier, costs.nextContextTokens(facts), routeFor);
203
- 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 };
204
214
  }
205
- 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 };
206
217
  if (!fits(result)) {
218
+ // A cell labelled with another activity would run, and stick, a route this turn did not choose.
207
219
  const native = cellForModel(config, nativeModel);
208
220
  const cells = [last, native, ...TIERS.map((tier) => ({ tier, activity }))];
209
- const fallback = cells.find((cell) => cell && fits(cell)) ?? { tier: null, activity: null };
210
- result = { ...result, ...fallback, reason: 'model-unavailable' };
221
+ const fallback = cells.find(
222
+ (cell) => cell && (cell.activity === null || cell.activity === activity) && fits(cell),
223
+ ) ?? { tier: null, activity: null };
224
+ result = { ...result, ...fallback, reason: 'model-unavailable', lateral: null };
211
225
  }
212
226
  const route = result.tier ? routeOf(result) : null;
213
227
  const model = route ? routeSpec(config, route).id : nativeModel;
@@ -252,9 +266,12 @@ function decideCell({ config, projected, facts, advice, state, now, incumbent, a
252
266
  incumbentRoute: incumbent.route,
253
267
  escalateTo,
254
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;
255
272
  const route = routeFor(step.tier);
256
273
  if (step.tier !== incumbent.tier || sameRequest(config, route, incumbent.route, facts.effort))
257
- return { ...step, activity };
274
+ return { ...step, activity, lateral: null, escalated };
258
275
  const lateral = lateralMove({
259
276
  config: projected,
260
277
  from: incumbent.route,
@@ -267,7 +284,14 @@ function decideCell({ config, projected, facts, advice, state, now, incumbent, a
267
284
  costs,
268
285
  });
269
286
  const activityOf = lateral.move ? activity : incumbent.activity;
270
- 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
+ };
271
295
  }
272
296
 
273
297
  // A tool continuation keeps the turn's route and activity; only the context or the model list can move it.
@@ -0,0 +1,238 @@
1
+ // Routing vs your model: what each main reply cost at configured list prices on the model that served it, against
2
+ // the same tokens on the session's own model and effort ("your model"). Counts and dollars only, never text. Pure:
3
+ // the hook feeds each reply and keeps the totals in the view and, per session, in $.store under SAVINGS_PREFIX.
4
+
5
+ import { ratesAt } from './cost.mjs';
6
+ import { HISTORY_SHRINK, isSameModel } from './route.mjs';
7
+
8
+ // Each session keeps its own record under this prefix and its session id: $.store has no atomic update, and Claude
9
+ // Code 2.1.296 writes one key under a file lock (observed, not in the types), so sessions finishing turns at the same
10
+ // moment do not overwrite each other.
11
+ export const SAVINGS_PREFIX = 'savings:v1:';
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.
14
+ export const SAVINGS_RESET_KEY = 'savings:reset:v1';
15
+ // Fewer replies than this read "too early": one switch and its cache write dominate a short run.
16
+ export const EARLY_REPLIES = 10;
17
+ const TTLS = ['5m', '1h'];
18
+
19
+ // The model entry an API model id runs on: its configured id, a dated snapshot of it, or the id with a context
20
+ // suffix such as `[1m]`. Null when no entry prices it.
21
+ export function modelSpec(config, id) {
22
+ if (typeof id !== 'string') return null;
23
+ const bare = id.replace(/\[[^\]]*\]$/, '');
24
+ const dated = (model) => bare.startsWith(model.id) && /^-\d{8}$/.test(bare.slice(model.id.length));
25
+ return Object.values(config.models).find((model) => isSameModel(model.id, bare) || dated(model)) ?? null;
26
+ }
27
+
28
+ // One request's list price in USD: `counts` are its uncached input, cache read, cache write and output tokens, the
29
+ // writes at `writeMultiplier` times input. Long-context rates follow the whole prompt.
30
+ export function requestUsd(model, { input, cacheRead, cacheWrite, output }, writeMultiplier) {
31
+ const rates = ratesAt(model, input + cacheRead + cacheWrite);
32
+ return (
33
+ (rates.input * (input + cacheWrite * writeMultiplier) + rates.cacheRead * cacheRead + rates.output * output) / 1e6
34
+ );
35
+ }
36
+
37
+ const truthy = (value) => /^(1|true|yes|on)$/i.test(String(value ?? '').trim());
38
+
39
+ // The prompt-cache lifetime Claude Code gives the main conversation, by its own rule as of 2.1.296: FORCE_PROMPT_CACHING_5M,
40
+ // then CLAUDE_CODE_PROMPT_CACHE_TTL, then the `promptCacheTtl` setting, then ENABLE_PROMPT_CACHING_1H, then one hour
41
+ // for a Claude plan subscriber and five minutes otherwise. Its usage reports carry no 5m/1h split, so this is how the
42
+ // writes are priced. Limit: a subscriber billed as overage gets five minutes, which this cannot see.
43
+ export function sessionCacheTtl({ force5m, envTtl, settingTtl, enable1h, subscriber }) {
44
+ if (truthy(force5m)) return '5m';
45
+ if (TTLS.includes(envTtl)) return envTtl;
46
+ if (TTLS.includes(settingTtl)) return settingTtl;
47
+ if (truthy(enable1h) || subscriber) return '1h';
48
+ return '5m';
49
+ }
50
+
51
+ const isCount = (n) => Number.isFinite(n) && n >= 0;
52
+
53
+ // One main reply. `state` is your model's simulated cache: `{ total, at, onYours, model, effort }` after a reply, or
54
+ // null at the session start and after a compaction, which counts as on your model with nothing cached; a state of
55
+ // another model or effort (after `/model` or an effort change) counts as null. `served` is the route the
56
+ // reply ran on, `{ model, effort }` with the API's model id; `yours` the session's model and effort.
57
+ //
58
+ // Routed is the reply's usage on the served model. Yours is the same tokens on your model: while this reply and the
59
+ // one before it both ran on your route, the usage itself, so equal routes differ by exactly 0. Otherwise a single
60
+ // cache that never switched: it reads the previous prompt, up to this one less its uncached input, if that is inside
61
+ // the cache lifetime and no compaction shrank the history, and never less than the API actually read (a shared
62
+ // system-prompt cache, a lifetime longer than assumed); it writes the rest. Output tokens stay the same.
63
+ //
64
+ // The difference splits into the model price (the served model on your cache, against yours: cheaper models when
65
+ // negative, stronger than yours when positive) and the cache the switches cost (routed against the served model on
66
+ // your cache), never negative. The parts sum to the difference by construction. `reply` is null when a model has no
67
+ // price or `ttl` is not a known cache lifetime.
68
+ export function compareReply(config, state, { usage, served, yours, ttl, now }) {
69
+ const counts = {
70
+ input: usage?.input_tokens,
71
+ cacheRead: usage?.cache_read_input_tokens,
72
+ cacheWrite: usage?.cache_creation_input_tokens,
73
+ output: usage?.output_tokens,
74
+ };
75
+ if (!Object.values(counts).every(isCount)) return { state, reply: null };
76
+ const total = counts.input + counts.cacheRead + counts.cacheWrite;
77
+ const [servedSpec, yoursSpec] = [modelSpec(config, served.model), modelSpec(config, yours.model)];
78
+ const sameModel = servedSpec ? servedSpec === yoursSpec : served.model === yours.model;
79
+ const onYours = sameModel && (served.effort ?? null) === (yours.effort ?? null);
80
+ const identity = { model: yoursSpec?.id ?? yours.model, effort: yours.effort ?? null };
81
+ const next = { total, at: now, onYours, ...identity };
82
+ // A cache simulated for another model or effort of yours is none of this one's: the new one starts cold.
83
+ const prior = state?.model === identity.model && state.effort === identity.effort ? state : null;
84
+ const write = config.cache.writeMultiplier[ttl];
85
+ if (
86
+ !servedSpec ||
87
+ !yoursSpec ||
88
+ !Number.isFinite(servedSpec.output) ||
89
+ !Number.isFinite(yoursSpec.output) ||
90
+ !Number.isFinite(write)
91
+ )
92
+ return { state: next, reply: null };
93
+ const routedUsd = requestUsd(servedSpec, counts, write);
94
+ let yoursUsd = routedUsd;
95
+ let servedOnYoursUsd = routedUsd;
96
+ if (!(onYours && (prior?.onYours ?? true))) {
97
+ const warm =
98
+ prior && now - prior.at < config.cache.ttlMs[ttl] && total >= prior.total * HISTORY_SHRINK && prior.total > 0;
99
+ const cacheRead = Math.max(counts.cacheRead, warm ? Math.min(prior.total, total - counts.input) : 0);
100
+ const single = { ...counts, cacheRead, cacheWrite: total - counts.input - cacheRead };
101
+ yoursUsd = requestUsd(yoursSpec, single, write);
102
+ servedOnYoursUsd = requestUsd(servedSpec, single, write);
103
+ }
104
+ const modelUsd = servedOnYoursUsd - yoursUsd;
105
+ return {
106
+ state: next,
107
+ reply: {
108
+ routedUsd,
109
+ yoursUsd,
110
+ cheaperUsd: Math.min(0, modelUsd),
111
+ strongerUsd: Math.max(0, modelUsd),
112
+ switchUsd: routedUsd - servedOnYoursUsd,
113
+ // The model a stronger reply ran on, for "9 replies on Opus 5.5".
114
+ strongerModel: modelUsd > 0 ? servedSpec.id : null,
115
+ },
116
+ };
117
+ }
118
+
119
+ const SUMS = ['routedUsd', 'yoursUsd', 'cheaperUsd', 'strongerUsd', 'switchUsd'];
120
+
121
+ // A session's totals: replies, the five sums, and per tier (`none`: not chosen by routing) the replies and their
122
+ // routed cost, which the pane's bar and share line draw. `stronger` counts replies by the stronger model they ran on.
123
+ export function emptyTotals() {
124
+ return {
125
+ replies: 0,
126
+ routedUsd: 0,
127
+ yoursUsd: 0,
128
+ cheaperUsd: 0,
129
+ strongerUsd: 0,
130
+ switchUsd: 0,
131
+ tiers: {},
132
+ tierUsd: {},
133
+ stronger: {},
134
+ };
135
+ }
136
+
137
+ export function addReply(totals, reply, tier) {
138
+ const key = tier ?? 'none';
139
+ const next = { ...totals, replies: totals.replies + 1 };
140
+ for (const sum of SUMS) next[sum] = totals[sum] + reply[sum];
141
+ next.tiers = { ...totals.tiers, [key]: (totals.tiers[key] ?? 0) + 1 };
142
+ next.tierUsd = { ...totals.tierUsd, [key]: (totals.tierUsd[key] ?? 0) + reply.routedUsd };
143
+ if (reply.strongerModel)
144
+ next.stronger = { ...totals.stronger, [reply.strongerModel]: (totals.stronger[reply.strongerModel] ?? 0) + 1 };
145
+ return next;
146
+ }
147
+
148
+ // A record kept across sessions, one session's or their sum: replies and the five sums since `since` (ms), the first
149
+ // reply after a reset.
150
+ export function emptySavingsStore() {
151
+ return {
152
+ version: 1,
153
+ since: null,
154
+ replies: 0,
155
+ routedUsd: 0,
156
+ yoursUsd: 0,
157
+ cheaperUsd: 0,
158
+ strongerUsd: 0,
159
+ switchUsd: 0,
160
+ };
161
+ }
162
+
163
+ const STORE_KEYS = Object.keys(emptySavingsStore());
164
+
165
+ // The stored value if it has the known shape, else an empty store: a missing, hand-edited or unknown value must not
166
+ // break a turn or the pane.
167
+ export function readSavingsStore(value) {
168
+ const ok =
169
+ value !== null &&
170
+ typeof value === 'object' &&
171
+ !Array.isArray(value) &&
172
+ Object.keys(value).length === STORE_KEYS.length &&
173
+ STORE_KEYS.every((key) => Object.hasOwn(value, key)) &&
174
+ value.version === 1 &&
175
+ (value.since === null || Number.isFinite(value.since)) &&
176
+ Number.isSafeInteger(value.replies) &&
177
+ value.replies >= 0 &&
178
+ SUMS.every((sum) => Number.isFinite(value[sum]));
179
+ return ok ? { ...value } : emptySavingsStore();
180
+ }
181
+
182
+ // A record whose first reply came before the last reset at `resetAt` (ms) reads as empty.
183
+ export function afterReset(record, resetAt) {
184
+ return Number.isFinite(resetAt) && record.since !== null && record.since < resetAt ? emptySavingsStore() : record;
185
+ }
186
+
187
+ // The totals kept across sessions: every session's record since the last reset added up, since the earliest.
188
+ export function mergeSavingsStores(values, resetAt = null) {
189
+ const merged = emptySavingsStore();
190
+ for (const one of values.map((value) => afterReset(readSavingsStore(value), resetAt))) {
191
+ const since = [merged.since, one.since].filter(Number.isFinite);
192
+ merged.since = since.length ? Math.min(...since) : null;
193
+ merged.replies += one.replies;
194
+ for (const sum of SUMS) merged[sum] += one[sum];
195
+ }
196
+ return merged;
197
+ }
198
+
199
+ // A finished turn's totals added to the store at `now`.
200
+ export function recordSavingsStore(store, totals, now) {
201
+ if (!totals.replies) return store;
202
+ const next = { ...store, since: store.since ?? now, replies: store.replies + totals.replies };
203
+ for (const sum of SUMS) next[sum] = store[sum] + totals[sum];
204
+ return next;
205
+ }
206
+
207
+ const cents = (usd) => Math.round(usd * 100);
208
+
209
+ // What the UI shows for a set of totals, in whole cents so the shown parts add up: the difference is routed less
210
+ // yours as shown, and the switch part takes the rounding remainder. A surplus goes to the switch part if the totals
211
+ // have one, else to the stronger part if they have one, else to the cheaper part toward 0. A shortfall comes off the
212
+ // stronger part down to 0, then the cheaper part. So no part changes sign or appears from rounding alone. `early`
213
+ // below EARLY_REPLIES replies. `share` is the difference against yours; `ratio` routed over yours.
214
+ export function readout(totals) {
215
+ const [routed, yours, cheaper, stronger] = [
216
+ totals.routedUsd,
217
+ totals.yoursUsd,
218
+ totals.cheaperUsd,
219
+ totals.strongerUsd,
220
+ ].map(cents);
221
+ const difference = routed - yours;
222
+ const rest = difference - cheaper - stronger;
223
+ const switches = totals.switchUsd ? Math.max(0, rest) : 0;
224
+ const surplus = !totals.switchUsd && totals.strongerUsd ? Math.max(0, rest) : 0;
225
+ const strongerShown = Math.max(0, stronger + Math.min(0, rest)) + surplus;
226
+ return {
227
+ replies: totals.replies,
228
+ early: totals.replies < EARLY_REPLIES,
229
+ routedUsd: routed / 100,
230
+ yoursUsd: yours / 100,
231
+ differenceUsd: difference / 100,
232
+ cheaperUsd: (difference - strongerShown - switches) / 100,
233
+ strongerUsd: strongerShown / 100,
234
+ switchUsd: switches / 100,
235
+ share: yours > 0 ? difference / yours : null,
236
+ ratio: yours > 0 ? routed / yours : null,
237
+ };
238
+ }
package/lib/view.mjs CHANGED
@@ -10,6 +10,8 @@ export function initialView(model) {
10
10
  activeTurnId: null,
11
11
  mode: 'auto',
12
12
  nativeModel: model,
13
+ // The effort Claude Code sent on the turn's first request, before routing: with nativeModel, "your model".
14
+ nativeEffort: null,
13
15
  selectedModel: null,
14
16
  actualModel: null,
15
17
  tier: null,
@@ -37,8 +39,13 @@ export function initialView(model) {
37
39
  history: [],
38
40
  tiers: [],
39
41
  activities: [],
42
+ routes: [],
40
43
  activityStats: null,
41
44
  activityStore: null,
45
+ activityMetrics: null,
46
+ // Routing vs your model: this session's totals and the totals kept across sessions as last read or written.
47
+ savings: null,
48
+ savingsStore: null,
42
49
  configPath: null,
43
50
  tuning: null,
44
51
  tuningBase: null,
@@ -79,7 +86,8 @@ export function continuationView(config, decision, context) {
79
86
 
80
87
  // The view patch for a main reply's usage. `tier` is the routed tier that served it, else null; `activity` the
81
88
  // turn's activity as the view labels it, else null.
82
- export function responseMetrics(view, response, tier, activity = null) {
89
+ // `route` is the (model, effort) the request went out with, so the switch count reads what served each reply.
90
+ export function responseMetrics(view, response, tier, activity = null, route = null) {
83
91
  const usage = response.usage;
84
92
  const counters = usage ? [usage.input_tokens, usage.cache_read_input_tokens, usage.cache_creation_input_tokens] : [];
85
93
  const inputTokens =
@@ -96,6 +104,7 @@ export function responseMetrics(view, response, tier, activity = null) {
96
104
  history: [...(view?.history ?? []), inputTokens].slice(-HISTORY),
97
105
  tiers: [...(view?.tiers ?? []), tier ?? null].slice(-HISTORY),
98
106
  activities: [...(view?.activities ?? []), activity ?? null].slice(-HISTORY),
107
+ routes: [...(view?.routes ?? []), route ?? null].slice(-HISTORY),
99
108
  }
100
109
  : {}),
101
110
  };
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@alexeiled/claude-router",
3
- "version": "1.6.1",
3
+ "version": "1.7.1",
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;
@@ -98,10 +117,35 @@ declare module 'claude-code' {
98
117
  >;
99
118
  activityRouting?: RouterActivityMode;
100
119
  }
120
+ // Routing vs your model at configured list prices, in USD: routed replies, the same tokens on your model, and the
121
+ // difference's parts (cheaper models, stronger than yours, cache writes from switches), which sum to it.
122
+ interface RouterSavingsSums {
123
+ replies: number;
124
+ routedUsd: number;
125
+ yoursUsd: number;
126
+ cheaperUsd: number;
127
+ strongerUsd: number;
128
+ switchUsd: number;
129
+ }
130
+ // A session's totals; per tier ('none': not chosen by routing) its replies and their routed cost, and replies by the
131
+ // stronger model they ran on.
132
+ interface RouterSavingsSession extends RouterSavingsSums {
133
+ tiers: Partial<Record<RouterTier | 'none', number>>;
134
+ tierUsd: Partial<Record<RouterTier | 'none', number>>;
135
+ stronger: Record<string, number>;
136
+ }
137
+ // Totals kept across sessions, one per session under store key 'savings:v1:<session id>' or their sum in the view,
138
+ // since the first reply after the last reset (ms).
139
+ interface RouterSavingsStore extends RouterSavingsSums {
140
+ version: 1;
141
+ since: number | null;
142
+ }
101
143
  interface RouterView {
102
144
  phase: 'ready' | 'choosing' | 'routed' | 'manual' | 'unavailable';
103
145
  mode: 'auto' | 'manual';
104
146
  nativeModel: string;
147
+ // The effort Claude Code sent on the turn's first request, before routing.
148
+ nativeEffort?: string | number | null;
105
149
  activeTurnId?: string | null;
106
150
  selectedModel?: string | null;
107
151
  actualModel?: string | null;
@@ -133,9 +177,14 @@ declare module 'claude-code' {
133
177
  tiers?: (RouterTier | null)[];
134
178
  // Aligned with `history` and `tiers`.
135
179
  activities?: (RouterActivity | null)[];
180
+ // The (model, effort) each reply's request went out with, aligned with tiers; null where routing did not choose.
181
+ routes?: (string | null)[];
136
182
  activityStats?: RouterActivitySession | null;
137
183
  // The counts kept across sessions as last read or written.
138
184
  activityStore?: RouterActivityStore | null;
185
+ activityMetrics?: RouterActivityMetrics | null;
186
+ savings?: RouterSavingsSession | null;
187
+ savingsStore?: RouterSavingsStore | null;
139
188
  configPath?: string | null;
140
189
  tuning?: Partial<RouterTuning> | null;
141
190
  tuningBase?: RouterTuning | null;
@@ -184,11 +233,17 @@ declare module 'claude-code' {
184
233
  comparison?: RouterComparison | null;
185
234
  // The applied activity; `wouldRoute` is set only in shadow mode.
186
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;
187
239
  wouldRoute?: RouterWouldRoute | null;
188
240
  pinned: boolean;
189
241
  requestedPin: RouterTier | null;
190
242
  } | null;
191
243
  ineligible: string[];
244
+ // Your model's simulated cache for routing vs your model: the last prompt's tokens, when, whether that reply ran
245
+ // on your route, and the model and effort it was kept for. Null at the start and after a compaction.
246
+ yours?: { total: number; at: number; onYours: boolean; model: string; effort: string | null } | null;
192
247
  engineModel?: string;
193
248
  suspended?: boolean;
194
249
  }