@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.
package/lib/route.mjs CHANGED
@@ -1,8 +1,8 @@
1
1
  import { chooseActivity, compareRoutes, lateralMove, sameRequest } from './activity.mjs';
2
- import { ACTIVITIES, rank, resolveRoute, routeSpec, TIERS } from './config.mjs';
2
+ import { ACTIVITIES, rank, resolveRoute, routeSpec, sameRoute, TIERS } from './config.mjs';
3
3
  import * as costs from './cost.mjs';
4
- import { clip, extractFacts, verifiedSince } from './facts.mjs';
5
- import { CONTEXT_FILL, decide, fitTier, initialState } from './policy.mjs';
4
+ import { clip, completedSince, extractFacts } from './facts.mjs';
5
+ import { CONTEXT_FILL, decide, fitTier, initialState, sameTaskOf } from './policy.mjs';
6
6
 
7
7
  // Exact observed API snapshot, not a rule that merges different dated versions.
8
8
  const SNAPSHOTS = { 'claude-haiku-4-5': 'claude-haiku-4-5-20251001' };
@@ -42,6 +42,9 @@ export function emptyLoop(config, model) {
42
42
  return {
43
43
  lastRoute: cell?.tier ?? config.baselineTier,
44
44
  lastActivity: cell?.activity ?? null,
45
+ // The route (models key, effort) the last routed decision ran for `lastRoute`, kept as it ran: a routing mode or
46
+ // a route edit changes the config, never the route in use. Null until the first decision.
47
+ route: null,
45
48
  state: initialState(),
46
49
  models: {},
47
50
  resolutions: {},
@@ -100,11 +103,12 @@ export function prepareLoop(loop, messageCount) {
100
103
  export function nativeFacts(config, loop, { messages, prompt, effort, turnId, contextTokens }) {
101
104
  const facts = extractFacts({ messages, output_config: { effort } }, loop, config.context);
102
105
  if (typeof prompt === 'string') facts.prompt = clip(prompt, config.context.maxTextChars);
103
- // A move down on the same task waits out the dwell and for a passed verification since the last model change.
106
+ // A move down on the same task waits out the dwell and for a checkpoint since the last model change: a passed check,
107
+ // or the success the running route's activity can show (completedSince).
104
108
  const since = loop.switchedAt ?? { requests: 0, messageCount: 0 };
105
109
  const downAllowed =
106
110
  (loop.requests ?? 0) - since.requests >= config.policy.minDwellRequests &&
107
- verifiedSince(messages, since.messageCount);
111
+ completedSince(messages, since.messageCount, activityOf(config, loop));
108
112
  // A loop saved without the field counts as measured, keeping the vote streak.
109
113
  return {
110
114
  ...facts,
@@ -146,6 +150,7 @@ export function chooseRoute(config, loop, input) {
146
150
  state: applied.state,
147
151
  lastRoute: kept ? loop.lastRoute : applied.tier,
148
152
  lastActivity: kept ? activityOf(config, loop) : applied.activity,
153
+ route: kept ? (loop.route ?? null) : applied.route,
149
154
  turnId: facts.turnKey,
150
155
  decision: applied,
151
156
  suspended: false,
@@ -160,11 +165,32 @@ const activityOf = (config, loop) => (config.activityRouting === 'on' ? (loop.la
160
165
  // One decision (plan §5.2) for the cell `{ tier, activity }` it lands on. Outside `on` the activity is null throughout.
161
166
  function routeTurn(config, loop, { facts, advice, pin, nativeModel, contextKnown, availableModels, now }) {
162
167
  const projected = economicConfig(config, loop);
163
- const routeOf = (cell) => resolveRoute(config, cell.tier, cell.activity);
164
- const specOf = (cell) => routeSpec(config, routeOf(cell));
165
168
  const last = { tier: loop.lastRoute, activity: activityOf(config, loop) };
166
169
  const tier0 = TIERS.includes(facts.lastRoute) ? facts.lastRoute : config.baselineTier;
167
- const incumbent = { tier: tier0, activity: last.activity, route: resolveRoute(config, tier0, last.activity) };
170
+ // The incumbent runs the route in use, not the one config gives its cell now. It is rebuilt from config for a loop
171
+ // from before 1.15, a route whose model left the config or can no longer run, and a route kept for an activity that
172
+ // no longer applies (activity routing turned off).
173
+ const usable = (route) => {
174
+ const model = Object.hasOwn(config.models, route.model) ? config.models[route.model] : null;
175
+ return Boolean(
176
+ model && isModelAllowed(model.id, availableModels, nativeModel) && !loop.ineligible.includes(model.id),
177
+ );
178
+ };
179
+ const inUse = loop.route && usable(loop.route) && (loop.lastActivity ?? null) === last.activity ? loop.route : null;
180
+ const incumbent = {
181
+ tier: tier0,
182
+ activity: last.activity,
183
+ route: inUse ?? resolveRoute(config, tier0, last.activity),
184
+ };
185
+ // A decision that stays on the incumbent's cell keeps running its route; only a taken lateral move or a pin runs the
186
+ // cell's route from config. So a mode change reaches the request only through the gates.
187
+ const stays = (cell) =>
188
+ cell.tier === incumbent.tier &&
189
+ (cell.activity ?? null) === incumbent.activity &&
190
+ cell.lateral !== 'taken' &&
191
+ cell.reason !== 'pinned';
192
+ const routeOf = (cell) => (stays(cell) ? incumbent.route : resolveRoute(config, cell.tier, cell.activity));
193
+ const specOf = (cell) => routeSpec(config, routeOf(cell));
168
194
  const activity =
169
195
  pin || config.activityRouting !== 'on' ? null : chooseActivity(config, advice, incumbent, facts.effort, facts);
170
196
  let result =
@@ -178,9 +204,12 @@ function routeTurn(config, loop, { facts, advice, pin, nativeModel, contextKnown
178
204
  state: { ...loop.state, turn: loop.state.turn + 1 },
179
205
  }
180
206
  : decideCell({ config, projected, facts, advice, state: loop.state, now, incumbent, activity });
181
- // Without a reliable reading of the context, a route with a smaller window than the last one might overflow.
207
+ // Without a reliable reading of the context, a route with a smaller window than the last one might overflow. Before
208
+ // the first decision the session's own model ran, not the mode's route for its cell.
209
+ const lastSpec =
210
+ (!loop.decision && Object.values(config.models).find((m) => isSameModel(m.id, nativeModel))) || specOf(last);
182
211
  const shrinksUnmeasured = (cell) =>
183
- (!contextKnown || !loop.historyMeasured) && specOf(cell).contextWindow < specOf(last).contextWindow;
212
+ (!contextKnown || !loop.historyMeasured) && specOf(cell).contextWindow < lastSpec.contextWindow;
184
213
  const fits = (cell) => {
185
214
  const model = specOf(cell);
186
215
  return (
@@ -191,7 +220,8 @@ function routeTurn(config, loop, { facts, advice, pin, nativeModel, contextKnown
191
220
  );
192
221
  };
193
222
  if (contextKnown) {
194
- const routeFor = (tier) => resolveRoute(config, tier, result.activity);
223
+ const cell = result;
224
+ const routeFor = (tier) => (tier === cell.tier ? routeOf(cell) : resolveRoute(config, tier, cell.activity));
195
225
  const fitted = fitTier(config, result.tier, costs.nextContextTokens(facts), routeFor);
196
226
  if (fitted !== result.tier) result = { ...result, tier: fitted, reason: 'context-fit', lateral: null };
197
227
  }
@@ -212,7 +242,7 @@ function routeTurn(config, loop, { facts, advice, pin, nativeModel, contextKnown
212
242
  let comparison = null;
213
243
  const candidate = pin ?? advice?.choice;
214
244
  if (contextKnown && loop.lastRequest && TIERS.includes(candidate) && candidate !== loop.lastRoute) {
215
- const [to, from] = [resolveRoute(config, candidate, activity), routeOf(last)];
245
+ const [to, from] = [resolveRoute(config, candidate, activity), incumbent.route];
216
246
  const forecast = costs.switchEconomics(projected, to, from, facts, now);
217
247
  comparison = {
218
248
  candidate,
@@ -222,7 +252,7 @@ function routeTurn(config, loop, { facts, advice, pin, nativeModel, contextKnown
222
252
  outputTokens: loop.lastRequest.outputTokens,
223
253
  };
224
254
  }
225
- return { ...result, model, effort, comparison, pinned: Boolean(pin), requestedPin: pin ?? null };
255
+ return { ...result, route, model, effort, comparison, pinned: Boolean(pin), requestedPin: pin ?? null };
226
256
  }
227
257
 
228
258
  // Steps 3-6 of plan §5.2: the tier as `decide` picks it, every candidate priced at its route for `activity` and the
@@ -230,13 +260,13 @@ function routeTurn(config, loop, { facts, advice, pin, nativeModel, contextKnown
230
260
  // never switch: a label alone decides nothing.
231
261
  function decideCell({ config, projected, facts, advice, state, now, incumbent, activity }) {
232
262
  const routeFor = (tier) => resolveRoute(config, tier, activity);
233
- // With an activity, failures move to the lowest tier whose route is stronger, or another request that does not
234
- // order against it; with none, one tier up as before.
263
+ // Failures move to the lowest tier whose route is stronger than the one running, or another request that does not
264
+ // order against it: after a mode change the next tier's route can be the weaker one.
235
265
  const escalates = (t) => {
236
266
  const order = compareRoutes(config, routeFor(t), incumbent.route, facts.effort);
237
267
  return order > 0 || (order === null && !sameRequest(config, routeFor(t), incumbent.route, facts.effort));
238
268
  };
239
- const escalateTo = activity === null ? undefined : (tier) => TIERS.slice(rank(tier) + 1).find(escalates) ?? null;
269
+ const escalateTo = (tier) => TIERS.slice(rank(tier) + 1).find(escalates) ?? null;
240
270
  const step = decide({
241
271
  config: projected,
242
272
  facts,
@@ -253,15 +283,18 @@ function decideCell({ config, projected, facts, advice, state, now, incumbent, a
253
283
  // context or availability override keeps the flag.
254
284
  const escalated = step.state.escalatedSignature !== state.escalatedSignature;
255
285
  const route = routeFor(step.tier);
256
- if (step.tier !== incumbent.tier || sameRequest(config, route, incumbent.route, facts.effort))
286
+ // Without a classifier answer the running route stays, whatever the mode's route for the cell, during a hold too.
287
+ if (!advice || step.tier !== incumbent.tier || sameRequest(config, route, incumbent.route, facts.effort))
257
288
  return { ...step, activity, lateral: null, escalated };
258
289
  const lateral = lateralMove({
259
290
  config: projected,
260
291
  from: incumbent.route,
261
292
  to: route,
262
- // Returning to the base route needs no evidence.
263
- mass: activity === null ? 1 : (advice?.activity?.probabilities?.[activity] ?? 0),
293
+ // Returning to the base route needs no evidence, nor does the incumbent's own cell whose configured route changed
294
+ // (a routing mode, a route edit): the label is not what moves.
295
+ mass: activity === null || activity === incumbent.activity ? 1 : (advice?.activity?.probabilities?.[activity] ?? 0),
264
296
  hold: step.reason === 'hold',
297
+ sameTask: sameTaskOf(config, advice, facts),
265
298
  facts,
266
299
  now,
267
300
  costs,
@@ -277,11 +310,17 @@ function decideCell({ config, projected, facts, advice, state, now, incumbent, a
277
310
  };
278
311
  }
279
312
 
313
+ // The route a decision runs: the one it recorded, or for a decision from before 1.15 its cell's route in config.
314
+ const runningRoute = (config, decision) =>
315
+ decision.route && Object.hasOwn(config.models, decision.route.model)
316
+ ? decision.route
317
+ : resolveRoute(config, decision.tier, decision.activity ?? null);
318
+
280
319
  // Whether some activity's route at the decision's tier is stronger than the one running: only then can the turn's own
281
320
  // tool calls move it (observedMove), so a step on the strongest route skips reading the transcript.
282
321
  export function canMoveUp(config, decision, effort) {
283
322
  if (config.activityRouting !== 'on' || !decision?.tier || decision.pinned) return false;
284
- const from = resolveRoute(config, decision.tier, decision.activity ?? null);
323
+ const from = runningRoute(config, decision);
285
324
  return ACTIVITIES.some((a) => compareRoutes(config, resolveRoute(config, decision.tier, a), from, effort) > 0);
286
325
  }
287
326
 
@@ -294,7 +333,7 @@ export function canMoveUp(config, decision, effort) {
294
333
  export function observedMove(config, loop, { observed, facts, contextKnown, now }) {
295
334
  const decision = loop.decision;
296
335
  if (!canMoveUp(config, decision, facts.effort) || !ACTIVITIES.includes(observed)) return loop;
297
- const from = resolveRoute(config, decision.tier, decision.activity ?? null);
336
+ const from = runningRoute(config, decision);
298
337
  // The gates price the route that will run: the one the context fits, not the tier's first choice.
299
338
  const routeFor = (tier) => resolveRoute(config, tier, observed);
300
339
  const tier = fitTier(config, decision.tier, costs.nextContextTokens(facts), routeFor);
@@ -309,10 +348,13 @@ export function observedMove(config, loop, { observed, facts, contextKnown, now
309
348
  return {
310
349
  ...loop,
311
350
  lastActivity: observed,
351
+ // The route in use belongs to `lastRoute`: a move the context fitted to another tier leaves it to be rebuilt.
352
+ route: tier === loop.lastRoute ? to : null,
312
353
  decision: {
313
354
  ...decision,
314
355
  tier,
315
356
  activity: observed,
357
+ route: to,
316
358
  model: routeSpec(config, to).id,
317
359
  effort: costs.routeEffort(config, to, facts.effort),
318
360
  reason: lateral.reason,
@@ -325,21 +367,37 @@ export function observedMove(config, loop, { observed, facts, contextKnown, now
325
367
  // calls (observedMove) can move it.
326
368
  export function continueRoute(config, loop, { nativeModel, contextTokens, contextKnown, availableModels, effort }) {
327
369
  if (!loop.decision) return loop;
370
+ // A fit to another tier serves this turn only: `loop.route` stays the route of `lastRoute`, as the tier does.
328
371
  let decision = loop.decision;
329
372
  if (contextKnown && decision.tier) {
373
+ // The route the turn runs, which a mode change or a held move can keep apart from config, stays while the context
374
+ // fits it; past that, the routes config gives each tier, its own tier's first.
375
+ const running = runningRoute(config, decision);
330
376
  const routeOf = (tier) => resolveRoute(config, tier, decision.activity ?? null);
331
- const fitted = fitTier(config, decision.tier, contextTokens, routeOf);
332
- if (fitted !== decision.tier)
377
+ const fits = contextTokens <= routeSpec(config, running).contextWindow * CONTEXT_FILL;
378
+ const fitted = fits ? decision.tier : fitTier(config, decision.tier, contextTokens, routeOf);
379
+ if (!fits && !sameRoute(routeOf(fitted), running)) {
380
+ const route = routeOf(fitted);
333
381
  decision = {
334
382
  ...decision,
335
383
  tier: fitted,
336
- model: routeSpec(config, routeOf(fitted)).id,
337
- effort: costs.routeEffort(config, routeOf(fitted), effort),
384
+ route,
385
+ model: routeSpec(config, route).id,
386
+ effort: costs.routeEffort(config, route, effort),
338
387
  reason: 'context-fit',
339
388
  };
389
+ }
340
390
  }
341
391
  if (!isModelAllowed(decision.model, availableModels, nativeModel) || loop.ineligible.includes(decision.model)) {
342
- decision = { ...decision, tier: null, activity: null, model: nativeModel, effort, reason: 'model-unavailable' };
392
+ decision = {
393
+ ...decision,
394
+ tier: null,
395
+ activity: null,
396
+ route: null,
397
+ model: nativeModel,
398
+ effort,
399
+ reason: 'model-unavailable',
400
+ };
343
401
  }
344
402
  return { ...loop, decision };
345
403
  }
package/lib/savings.mjs CHANGED
@@ -135,6 +135,23 @@ export function compareReply(config, state, { usage, served, yours, ttl, now })
135
135
  };
136
136
  }
137
137
 
138
+ // Why a routed reply gets no price, by compareReply's checks in its order, or null when it prices it: the usage or its
139
+ // model id is missing or its counts do not read (`usage`; the hook drops a usage without a model before compareReply), the served model or your model has no configured price (`model`), or the cache
140
+ // lifetime is unknown (`ttl`). The usage record keeps priced replies only; this names what it leaves out.
141
+ export function unpricedCause(config, { usage, served, yours, ttl }) {
142
+ const counts = [
143
+ usage?.input_tokens,
144
+ usage?.cache_read_input_tokens,
145
+ usage?.cache_creation_input_tokens,
146
+ usage?.output_tokens,
147
+ ];
148
+ if (!usage?.model || !counts.every(isCount)) return 'usage';
149
+ const [servedSpec, yoursSpec] = [modelSpec(config, served.model), modelSpec(config, yours.model)];
150
+ if (!servedSpec || !yoursSpec || !Number.isFinite(servedSpec.output) || !Number.isFinite(yoursSpec.output))
151
+ return 'model';
152
+ return Number.isFinite(config.cache.writeMultiplier[ttl]) ? null : 'ttl';
153
+ }
154
+
138
155
  // One main reply against every configured model as yours, at your effort, so the session readout can follow a
139
156
  // `/model` change without replaying the session: `states` and `replies` by models key, each as compareReply returns,
140
157
  // and `reply`, the prices against `yours`, the API model id /model selects now, or null.
package/lib/usage.mjs CHANGED
@@ -34,9 +34,12 @@ export const CELL_SUMS = [
34
34
  const USD = new Set(['routedUsd', 'yoursUsd', 'cheaperUsd', 'strongerUsd', 'switchUsd']);
35
35
  const IS_USD = CELL_SUMS.map((sum) => USD.has(sum));
36
36
  export const DAY = /^\d{4}-\d{2}-\d{2}$/;
37
- // `activity|tier|id@effort`: activity and tier never hold a `|`, and an effort never an `@`, so a model id may hold
38
- // either.
39
- const CELL_KEY = /^[^|]+\|[^|]+\|.+@[^@]+$/;
37
+ // `mode|activity|tier|id@effort`: mode, activity and tier never hold a `|`, and an effort never an `@`, so a model id
38
+ // may hold either. Version 1 records, from before routing modes, had no mode: every reply then ran `balanced`.
39
+ export const USAGE_VERSION = 2;
40
+ const CELL_KEY = /^[^|]+\|[^|]+\|[^|]+\|.+@[^@]+$/;
41
+ const V1_CELL_KEY = /^[^|]+\|[^|]+\|.+@[^@]+$/;
42
+ const V1_MODE = 'balanced';
40
43
  const HOUR = /^(1?\d|2[0-3])$/;
41
44
  // Sums are kept to a millionth of a dollar: enough for a cent-exact readout over many replies, and short in JSON.
42
45
  const microUsd = (usd) => Math.round(usd * 1e6) / 1e6;
@@ -60,21 +63,22 @@ export function daysBefore(ms, days) {
60
63
  }
61
64
 
62
65
  export function emptyUsage() {
63
- return { version: 1, since: null, days: {} };
66
+ return { version: USAGE_VERSION, since: null, days: {} };
64
67
  }
65
68
 
66
69
  const emptyDay = () => ({ cells: {}, whatIf: {}, yours: {}, hours: {}, turns: 0, switches: { tier: 0, activity: 0 } });
67
70
 
68
- // One routed main reply as its turn collects it. `at` is when it arrived (ms); `activity` the turn's activity and
71
+ // One routed main reply as its turn collects it. `at` is when it arrived (ms); `mode` the turn's routing mode;
72
+ // `activity` the turn's activity and
69
73
  // `tier` the tier that served it (null: none); `route` the model id that served it and the request's effort,
70
74
  // `id@effort` (`session` for no effort); `yours` your model's id; `reply` its prices against your model, and `replies`
71
75
  // against each model as yours keyed by model id, from compareModels; `usage` the API usage, whose counts compareReply
72
76
  // already checked. Model ids, not models keys: a models key can name another model later.
73
- export function replyEntry({ at, activity, tier, route, yours, reply, replies, usage }) {
77
+ export function replyEntry({ at, mode, activity, tier, route, yours, reply, replies, usage }) {
74
78
  const input = usage.input_tokens + usage.cache_read_input_tokens + usage.cache_creation_input_tokens;
75
79
  return {
76
80
  at,
77
- cell: `${activity ?? 'none'}|${tier ?? 'none'}|${route}`,
81
+ cell: `${mode}|${activity ?? 'none'}|${tier ?? 'none'}|${route}`,
78
82
  sums: [
79
83
  1,
80
84
  reply.routedUsd,
@@ -118,7 +122,7 @@ export function recordUsage(record, entries, { switched = null, now }) {
118
122
  days[dayKey(now)] = ended;
119
123
  const cutoff = daysBefore(now, RETAIN_DAYS);
120
124
  for (const key of Object.keys(days)) if (key < cutoff) delete days[key];
121
- return { version: 1, since: record.since ?? now, days };
125
+ return { version: USAGE_VERSION, since: record.since ?? now, days };
122
126
  }
123
127
 
124
128
  const isCount = (n) => Number.isSafeInteger(n) && n >= 0;
@@ -131,11 +135,12 @@ const isSums = (v) =>
131
135
  v.length === CELL_SUMS.length &&
132
136
  v.every((n, i) => Number.isFinite(n) && (i === CHEAPER ? n <= 0 : n >= 0));
133
137
 
134
- function readDay(day) {
138
+ function readDay(day, version) {
139
+ const key = version === 1 ? V1_CELL_KEY : CELL_KEY;
135
140
  const ok =
136
141
  isRecord(day) &&
137
142
  isRecord(day.cells) &&
138
- Object.entries(day.cells).every(([key, sums]) => CELL_KEY.test(key) && isSums(sums)) &&
143
+ Object.entries(day.cells).every(([cell, sums]) => key.test(cell) && isSums(sums)) &&
139
144
  isRecord(day.whatIf) &&
140
145
  Object.values(day.whatIf).every(isPair) &&
141
146
  isRecord(day.yours) &&
@@ -147,20 +152,27 @@ function readDay(day) {
147
152
  Object.keys(day.switches).length === 2 &&
148
153
  isCount(day.switches.tier) &&
149
154
  isCount(day.switches.activity);
150
- return ok ? day : null;
155
+ if (!ok) return null;
156
+ return version === 1
157
+ ? {
158
+ ...day,
159
+ cells: Object.fromEntries(Object.entries(day.cells).map(([cell, sums]) => [`${V1_MODE}|${cell}`, sums])),
160
+ }
161
+ : day;
151
162
  }
152
163
 
153
164
  // The stored value read day by day: a missing or unknown record is empty, and a day that does not read is dropped
154
- // while the others stay, so a hand edit never breaks a turn or the pane.
165
+ // while the others stay, so a hand edit never breaks a turn or the pane. A version 1 record reads as version 2, its
166
+ // replies under `balanced`; the session's next write stores it as version 2 under the same key.
155
167
  export function readUsage(value) {
156
- if (!isRecord(value) || value.version !== 1 || !isRecord(value.days)) return emptyUsage();
168
+ if (!isRecord(value) || ![1, USAGE_VERSION].includes(value.version) || !isRecord(value.days)) return emptyUsage();
157
169
  if (!(value.since === null || Number.isFinite(value.since))) return emptyUsage();
158
170
  const days = {};
159
171
  for (const [key, day] of Object.entries(value.days)) {
160
- const read = DAY.test(key) ? readDay(day) : null;
172
+ const read = DAY.test(key) ? readDay(day, value.version) : null;
161
173
  if (read) days[key] = read;
162
174
  }
163
- return { version: 1, since: value.since, days };
175
+ return { version: USAGE_VERSION, since: value.since, days };
164
176
  }
165
177
 
166
178
  // A record whose first reply came before the last reset at `resetAt` (ms) reads as empty.
@@ -282,11 +294,11 @@ export function allTime(usageStore, savingsStore) {
282
294
  };
283
295
  }
284
296
 
285
- // A cell key's parts, split at its first two `|` and its route's last `@` (CELL_KEY).
297
+ // A cell key's parts, split at its first three `|` and its route's last `@` (CELL_KEY).
286
298
  function cellParts(key) {
287
- const [activity, tier] = key.split('|', 2);
288
- const route = key.slice(activity.length + tier.length + 2);
289
- return { activity, tier, route, model: route.slice(0, route.lastIndexOf('@')) };
299
+ const [mode, activity, tier] = key.split('|', 3);
300
+ const route = key.slice(mode.length + activity.length + tier.length + 3);
301
+ return { mode, activity, tier, route, model: route.slice(0, route.lastIndexOf('@')) };
290
302
  }
291
303
  // The part of a cell key a breakdown groups by, and the part it lists under each group.
292
304
  const keyPart = (key, by) => cellParts(key)[by];
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@alexeiled/claude-router",
3
- "version": "1.14.0",
3
+ "version": "1.16.0",
4
4
  "description": "Native Claude Code Mod: model and effort routing for the main conversation, advised by Jev, Clef, Clef Flash, Clef Omni, 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
+ "docs:modes": "node scripts/mode-matrix.mjs",
39
40
  "probe:results": "node scripts/probe-results.mjs",
40
41
  "pack:dry": "npm pack --dry-run",
41
42
  "prepublishOnly": "npm run check && npm test"
package/types/index.d.ts CHANGED
@@ -5,6 +5,12 @@ declare module 'claude-code' {
5
5
  type RouterActivity = 'code' | 'debug' | 'explore' | 'plan' | 'review' | 'ops' | 'docs';
6
6
  type RouterActivityAnswer = RouterActivity | 'uncertain';
7
7
  type RouterActivityMode = 'off' | 'on';
8
+ // The routing mode (lib/modes.mjs) and where it comes from, strongest first.
9
+ type RouterRoutingModeName = 'cost' | 'balanced' | 'quality';
10
+ interface RouterRoutingMode {
11
+ mode: RouterRoutingModeName;
12
+ source: 'session' | 'project' | 'profile' | 'default';
13
+ }
8
14
  // A finished turn's bucket, read from its tool calls.
9
15
  type RouterObserved = 'code' | 'docs' | 'ops' | 'read' | 'talk';
10
16
  // A route change inside the incumbent's tier: taken, refused (does not pay back, a hold, the cash gate), or none.
@@ -151,7 +157,8 @@ declare module 'claude-code' {
151
157
  days: Record<string, RouterSubagentDay>;
152
158
  undated?: RouterSubagentDay;
153
159
  }
154
- // One local calendar day of routed replies (lib/usage.mjs). `cells` by 'activity|tier|modelId@effort' hold, in order,
160
+ // One local calendar day of routed replies (lib/usage.mjs). `cells` by 'mode|activity|tier|id@effort' (version 1:
161
+ // 'activity|tier|id@effort', read as balanced) hold, in order, the sums:
155
162
  // replies, routedUsd, yoursUsd, cheaperUsd, strongerUsd, switchUsd, inputTokens, cacheReadTokens, outputTokens.
156
163
  // `whatIf` is [replies, USD] of the same tokens on each model id as yours; `yours` replies by your model's id;
157
164
  // `hours` routed USD by local hour; `turns` and `switches` count turns on the day they ended.
@@ -166,7 +173,7 @@ declare module 'claude-code' {
166
173
  // Kept across sessions, one per session under store key 'usage:v1:<session id>' or their sum in the view, by day
167
174
  // ('2026-10-13'), since its first turn written after the last reset (ms).
168
175
  interface RouterUsageStore {
169
- version: 1;
176
+ version: 1 | 2;
170
177
  since: number | null;
171
178
  days: Record<string, RouterUsageDay>;
172
179
  }
@@ -174,6 +181,10 @@ declare module 'claude-code' {
174
181
  interface RouterView {
175
182
  phase: 'ready' | 'choosing' | 'routed' | 'manual' | 'unavailable';
176
183
  mode: 'auto' | 'manual';
184
+ // The routing mode the next turn starts with; absent in views saved before 1.15.
185
+ routingMode?: RouterRoutingMode;
186
+ // Why the project's .claude/router.json was ignored, or null.
187
+ projectError?: string | null;
177
188
  nativeModel: string;
178
189
  // The effort Claude Code sent on the turn's first request, before routing.
179
190
  nativeEffort?: string | number | null;
@@ -260,6 +271,8 @@ declare module 'claude-code' {
260
271
  lastRoute: RouterTier;
261
272
  // The activity of the route running now; absent in loops saved before 1.6.
262
273
  lastActivity?: RouterActivity | null;
274
+ // The route (models key, effort) the last routed decision ran for lastRoute; absent in loops saved before 1.15.
275
+ route?: RouterRoute | null;
263
276
  state: RouterPolicyState;
264
277
  models: Record<string, { lastAt: number; prefixTokens: number }>;
265
278
  resolutions: Record<string, string>;