@alexeiled/claude-router 1.6.1 → 1.7.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/config.mjs CHANGED
@@ -5,9 +5,10 @@ export const EFFORTS = ['low', 'medium', 'high', 'xhigh', 'max'];
5
5
  // What kind of work a turn does, named by what it produces. Closed: the classifier question is built for this set.
6
6
  export const ACTIVITIES = ['code', 'debug', 'explore', 'plan', 'review', 'ops', 'docs'];
7
7
  export const ACTIVITY_VALUES = [...ACTIVITIES, 'uncertain'];
8
- // `off` asks nothing new and routes as 1.5; `shadow` asks and records but keeps the 1.5 route; `on` applies overrides.
8
+ // `off` asks nothing new and routes as 1.5; `shadow` asks and records but keeps the 1.5 route; `on`, the default since
9
+ // 1.7, applies overrides.
9
10
  export const ACTIVITY_MODES = ['off', 'shadow', 'on'];
10
- const SONNET_MEDIUM = { model: 'sonnet', effort: 'medium' };
11
+ const SONNET_HIGH = { model: 'sonnet', effort: 'high' };
11
12
  export const DEFAULTS = {
12
13
  baselineTier: 'low',
13
14
  // Haiku 5.5 is the worker at `low` and `micro`: at high effort it scored above Sonnet 5.5 at low, and at xhigh near
@@ -23,22 +24,24 @@ export const DEFAULTS = {
23
24
  },
24
25
  // Sparse per-field overrides of `routes` by activity; a missing activity, tier or field inherits the tier's route.
25
26
  // Coding is where Haiku is weakest (Terminal-Bench 4.0: Haiku 5.5 39.2%, Sonnet 5.5 70.6%), so `low` work that
26
- // edits, debugs, plans or reviews runs on Sonnet. On knowledge and terminal work Sonnet 5.5 matches Opus 5.5
27
- // (GDPval-AA 1844 vs 1846; Terminal-Bench 70.6% vs 66.4%), so docs, ops and explore at `medium` run on Sonnet.
28
- // Every cell reuses Sonnet at medium: one more cache than the base routes, not one per cell.
29
- activityRouting: 'shadow',
27
+ // edits, debugs, plans or reviews runs on Sonnet. At `high`, not `medium`: on FrontierCode Main Sonnet scored ~49%
28
+ // at high and ~37% at medium, below Haiku at high (~42%). Command runs at `medium` lasted 6-11 requests at the
29
+ // median in one developer's replay, long enough for Haiku to repay its cache write (~4 requests from Opus at ~350K
30
+ // context). Haiku trails on multi-step tool work (OSWorld 2.1: ~61% at high, Opus ~79% at medium), so `high` ops
31
+ // stays on Opus, and repeated tool errors still escalate. Moving explore and docs saved nothing in the replay, and
32
+ // Haiku trails on research (HLE with tools 50.1% vs Opus 63.0%), so they keep the base routes. Two cells, one more cache (Sonnet at high) than the base routes.
33
+ activityRouting: 'on',
30
34
  activities: {
31
- code: { low: SONNET_MEDIUM },
32
- debug: { low: SONNET_MEDIUM },
33
- explore: { medium: SONNET_MEDIUM },
34
- plan: { low: SONNET_MEDIUM },
35
- review: { low: SONNET_MEDIUM },
36
- ops: { medium: SONNET_MEDIUM },
37
- docs: { low: SONNET_MEDIUM, medium: SONNET_MEDIUM },
35
+ code: { low: SONNET_HIGH },
36
+ debug: { low: SONNET_HIGH },
37
+ plan: { low: SONNET_HIGH },
38
+ review: { low: SONNET_HIGH },
39
+ ops: { medium: { model: 'haiku', effort: 'high' } },
38
40
  },
39
41
  // `id` selects the native model. List prices in USD per million tokens; `cacheRead` is absolute,
40
- // not a multiplier (Opus 5.5 reads at 0.05x input, the rest at the standard 0.1x). Haiku 5.5 lists the rates for
41
- // prompts up to 100k tokens; above that Anthropic charges 5x on input, output and cache read, so estimates run low there. A price change must also change
42
+ // not a multiplier (Opus 5.5 reads at 0.05x input, the rest at the standard 0.1x). `longContext` multiplies every
43
+ // rate of a request whose prompt (input, cache read and cache write) is over `above` tokens: Haiku 5.5 lists its
44
+ // rates for prompts up to 100,000 tokens and 5x above. A price change must also change
42
45
  // test/fixtures/list-prices.json, with its source and date. `output` feeds the shadow estimate and the downgrade tax.
43
46
  // `efforts` lists what the model accepts; an empty list means no effort field and no adaptive thinking. A change
44
47
  // must also change test/fixtures/effort-support.json, from a new probe against the real API.
@@ -66,6 +69,7 @@ export const DEFAULTS = {
66
69
  input: 0.1,
67
70
  output: 0.5,
68
71
  cacheRead: 0.01,
72
+ longContext: { above: 100_000, multiplier: 5 },
69
73
  contextWindow: 1_000_000,
70
74
  billing: 'plan',
71
75
  efforts: EFFORTS,
@@ -92,8 +96,8 @@ export const DEFAULTS = {
92
96
  // Ceiling on a cold cache write to a `credits` model. No default model bills credits, so this is
93
97
  // inert until a user adds one in router.json; a Claude Code turn starts near 100k tokens.
94
98
  cashCapUsd: 2,
95
- // An activity applies only above this probability; below it the tier's base route runs. Not tuned on any
96
- // classifier yet: calibrate from the probe set and shadow stats.
99
+ // An activity applies only above this probability; below it a new task goes back to the base route. Not tuned on any
100
+ // classifier yet: the probe results record whether the label was right, not its probability.
97
101
  activityMass: 0.6,
98
102
  },
99
103
  // The active entry of `classifiers`. `api` names the wire protocol (CLASSIFIER_APIS); a user entry without one speaks
@@ -151,7 +155,7 @@ export const DEFAULTS = {
151
155
 
152
156
  // Keys a route, a model or a classifier entry may carry. The other closed sections take their key sets from DEFAULTS.
153
157
  const ROUTE_KEYS = ['model', 'effort'];
154
- const MODEL_KEYS = ['id', 'input', 'output', 'cacheRead', 'contextWindow', 'billing', 'efforts'];
158
+ const MODEL_KEYS = ['id', 'input', 'output', 'cacheRead', 'longContext', 'contextWindow', 'billing', 'efforts'];
155
159
  const CLASSIFIER_KEYS = ['label', 'api', 'endpoint', 'model', 'keyOption', 'timeoutMs'];
156
160
  // The wire protocols a classifier can speak. Each has an adapter in classifier-apis.mjs; a test keeps the two in step.
157
161
  export const CLASSIFIER_APIS = ['system-one', 'openai-decisions', 'ollama'];
@@ -337,6 +341,7 @@ const TUNING_FIELDS = {
337
341
  downgradeVotes: ['policy', 'downgradeVotes'],
338
342
  horizon: ['policy', 'downgradeHorizonTurns'],
339
343
  cashCapUsd: ['policy', 'cashCapUsd'],
344
+ activityMass: ['policy', 'activityMass'],
340
345
  };
341
346
 
342
347
  export function tuningOf(config) {
@@ -436,7 +441,12 @@ function checkShape(file) {
436
441
  }
437
442
  if (models !== undefined) {
438
443
  checkObject(models, 'models');
439
- for (const [alias, model] of Object.entries(models)) checkObject(model, `models.${alias}`, MODEL_KEYS);
444
+ for (const [alias, model] of Object.entries(models)) {
445
+ checkObject(model, `models.${alias}`, MODEL_KEYS);
446
+ // null removes a built-in surcharge.
447
+ if (model.longContext != null)
448
+ checkObject(model.longContext, `models.${alias}.longContext`, ['above', 'multiplier']);
449
+ }
440
450
  }
441
451
  if (cache !== undefined) {
442
452
  checkObject(cache, 'cache', Object.keys(DEFAULTS.cache));
@@ -484,19 +494,7 @@ function validate(config) {
484
494
  throw new Error(`${at}.effort must be one of ${EFFORTS.join(', ')} or null`);
485
495
  }
486
496
  }
487
- for (const [alias, model] of Object.entries(config.models)) {
488
- for (const field of ['input', 'cacheRead', 'contextWindow']) {
489
- if (!Number.isFinite(model[field]) || model[field] < 0)
490
- throw new Error(`models.${alias}.${field} must be a non-negative number`);
491
- }
492
- if (model.output !== undefined && !(Number.isFinite(model.output) && model.output >= 0))
493
- throw new Error(`models.${alias}.output must be a non-negative number`);
494
- if (typeof model.id !== 'string' || !model.id) throw new Error(`models.${alias}.id is required`);
495
- if (!['plan', 'credits'].includes(model.billing))
496
- throw new Error(`models.${alias}.billing must be plan or credits`);
497
- if (!Array.isArray(model.efforts) || model.efforts.some((e) => !EFFORTS.includes(e)))
498
- throw new Error(`models.${alias}.efforts must list valid effort levels`);
499
- }
497
+ for (const [alias, model] of Object.entries(config.models)) validateModel(`models.${alias}`, model);
500
498
  if (!TIERS.includes(config.baselineTier)) throw new Error(`baselineTier must be one of ${TIERS.join(', ')}`);
501
499
  const p = config.policy;
502
500
  for (const field of ['upgradeBase', 'jumpConfidence', 'downgradeMass', 'continuationMass', 'activityMass']) {
@@ -525,6 +523,25 @@ function validate(config) {
525
523
  }
526
524
  }
527
525
 
526
+ function validateModel(at, model) {
527
+ for (const field of ['input', 'cacheRead', 'contextWindow']) {
528
+ if (!Number.isFinite(model[field]) || model[field] < 0)
529
+ throw new Error(`${at}.${field} must be a non-negative number`);
530
+ }
531
+ if (model.output !== undefined && !(Number.isFinite(model.output) && model.output >= 0))
532
+ throw new Error(`${at}.output must be a non-negative number`);
533
+ if (model.longContext != null) {
534
+ const { above, multiplier } = model.longContext;
535
+ if (!isNumber(above, 0, { above: true, integer: true }))
536
+ throw new Error(`${at}.longContext.above must be a positive integer`);
537
+ if (!isNumber(multiplier, 0, { above: true })) throw new Error(`${at}.longContext.multiplier must be positive`);
538
+ }
539
+ if (typeof model.id !== 'string' || !model.id) throw new Error(`${at}.id is required`);
540
+ if (!['plan', 'credits'].includes(model.billing)) throw new Error(`${at}.billing must be plan or credits`);
541
+ if (!Array.isArray(model.efforts) || model.efforts.some((e) => !EFFORTS.includes(e)))
542
+ throw new Error(`${at}.efforts must list valid effort levels`);
543
+ }
544
+
528
545
  function validateClassifier(at, entry) {
529
546
  for (const field of ['label', 'endpoint', 'model']) {
530
547
  if (typeof entry[field] !== 'string' || !entry[field]) throw new Error(`${at}.${field} is required`);
package/lib/cost.mjs CHANGED
@@ -11,6 +11,18 @@ export function clampEffort(wanted, supported) {
11
11
  return supported[0];
12
12
  }
13
13
 
14
+ // The one place a model's list prices become rates: per million tokens for a request whose prompt (input, cache read
15
+ // and cache write) is `promptTokens`, with the model's long-context multiplier above its threshold. Every estimate
16
+ // prices through here.
17
+ export function ratesAt(model, promptTokens) {
18
+ const k = model.longContext && promptTokens > model.longContext.above ? model.longContext.multiplier : 1;
19
+ return {
20
+ input: model.input * k,
21
+ cacheRead: model.cacheRead * k,
22
+ output: Number.isFinite(model.output) ? model.output * k : undefined,
23
+ };
24
+ }
25
+
14
26
  export function nextContextTokens(facts) {
15
27
  const previous = facts.lastRequest ? facts.lastRequest.tokens + facts.lastRequest.outputTokens : 0;
16
28
  return Math.max(previous, Number.isFinite(facts.contextTokens) ? facts.contextTokens : 0);
@@ -41,7 +53,7 @@ export function cacheState(state, now, cache) {
41
53
 
42
54
  // Bounds are scenarios, never an independent ledger. Unknown incumbent cache can still be served.
43
55
  export function inputBounds(config, route, tokens, facts, now) {
44
- const model = routeSpec(config, route);
56
+ const model = ratesAt(routeSpec(config, route), tokens);
45
57
  const state = facts.models[routeCacheKey(config, route, facts.effort)];
46
58
  const prefix = Math.min(state?.prefixTokens ?? tokens, tokens);
47
59
  const fresh = isWarm(state, now, config.cache);
@@ -53,7 +65,10 @@ export function inputBounds(config, route, tokens, facts, now) {
53
65
  }
54
66
 
55
67
  export function coldWriteUsd(config, alias, tokens) {
56
- return (config.models[alias].input * Math.max(...Object.values(config.cache.writeMultiplier)) * tokens) / 1e6;
68
+ return (
69
+ (ratesAt(config.models[alias], tokens).input * Math.max(...Object.values(config.cache.writeMultiplier)) * tokens) /
70
+ 1e6
71
+ );
57
72
  }
58
73
 
59
74
  export function switchingTaxUsd(config, candidate, incumbent, facts, now) {
@@ -69,17 +84,17 @@ export function nextTurnRange(config, candidate, incumbent, facts, now) {
69
84
  const tokens = nextContextTokens(facts);
70
85
  const proposed = inputBounds(config, candidate, tokens, facts, now);
71
86
  const current = inputBounds(config, incumbent, tokens, facts, now);
72
- const [to, from] = [routeSpec(config, candidate), routeSpec(config, incumbent)];
87
+ const [to, from] = [ratesAt(routeSpec(config, candidate), tokens), ratesAt(routeSpec(config, incumbent), tokens)];
73
88
  const outputTokens = facts.lastRequest?.outputTokens ?? 0;
74
89
  const output = to.output > 0 && from.output > 0 ? ((to.output - from.output) * outputTokens) / 1e6 : 0;
75
90
  return { minUsd: proposed.min - current.max + output, maxUsd: proposed.max - current.min + output };
76
91
  }
77
92
 
78
93
  export function shadowEconomics(config, candidate, incumbent, facts, now) {
79
- const proposed = routeSpec(config, candidate);
80
- const current = routeSpec(config, incumbent);
81
- if (!(proposed.output > 0) || !(current.output > 0)) return null;
82
94
  const tokens = nextContextTokens(facts);
95
+ const proposed = ratesAt(routeSpec(config, candidate), tokens);
96
+ const current = ratesAt(routeSpec(config, incumbent), tokens);
97
+ if (!(proposed.output > 0) || !(current.output > 0)) return null;
83
98
  const outputTokens = facts.lastRequest?.outputTokens ?? 0;
84
99
  const output = ((proposed.output - current.output) * outputTokens) / 1e6;
85
100
  const nextTurnUsd = switchingTaxUsd(config, candidate, incumbent, facts, now) + output;
package/lib/display.mjs CHANGED
@@ -8,7 +8,9 @@ import {
8
8
  routeSpec,
9
9
  sameRoute,
10
10
  } from './config.mjs';
11
+ import { ratesAt } from './cost.mjs';
11
12
  import { cellForModel, isSameModel } from './route.mjs';
13
+ import { emptyTotals, readout, readSavingsStore } from './savings.mjs';
12
14
 
13
15
  // Cost order, cheapest first, so the colors read as a scale. Hex values: every surface draws them.
14
16
  export const TIER_COLOR = { micro: '#5fd7af', low: '#5f9fe0', medium: '#d7af5f', high: '#e0708a' };
@@ -37,8 +39,10 @@ export function routeName(config, route) {
37
39
  // One letter per activity for the REPLIES strip: `docs` is `w` (writing), since `debug` has `d`.
38
40
  export const ACTIVITY_LETTER = { code: 'c', debug: 'd', explore: 'e', plan: 'p', review: 'r', ops: 'o', docs: 'w' };
39
41
 
40
- // Changes of tier between consecutive replies; a reply routing did not choose breaks no run.
41
- export const switchCount = (tiers) => tiers.slice(1).filter((tier, i) => tier && tiers[i] && tier !== tiers[i]).length;
42
+ // Changes of route between consecutive replies, from the (model, effort) each request went out with, so a move inside
43
+ // a tier counts and a later change of settings does not rewrite the count. A reply routing did not choose breaks no run.
44
+ export const switchCount = (routes) =>
45
+ routes.slice(1).filter((route, i) => route && routes[i] && route !== routes[i]).length;
42
46
 
43
47
  export const percent = (value) => `${Math.round(value * 100)}%`;
44
48
 
@@ -61,7 +65,7 @@ export const REASONS = {
61
65
  'model-unavailable': 'the requested model is not available',
62
66
  pinned: 'one-turn model pin',
63
67
  'activity-up': 'the activity needs a stronger route',
64
- 'activity-down': 'a cheaper route fits the activity and pays back its cache',
68
+ 'activity-down': 'a cheaper route fits the activity and is estimated to pay back its cache write',
65
69
  'activity-pending': 'a route for the activity does not pay back yet',
66
70
  };
67
71
 
@@ -223,7 +227,66 @@ export function storeAgreementLine(view) {
223
227
  return `Agreement across sessions: ${all}${code}`;
224
228
  }
225
229
 
230
+ // Routing vs your model: less is green, more is amber, not red: a stronger model is a purchase, not a fault.
231
+ export const SAVINGS_COLOR = { less: '#6fcf97', more: '#f0b429' };
232
+
233
+ // "$6.40"; signed for a difference or a part: "−$1.84", "+$0.47", "$0.00".
234
+ export const usd = (value) => `$${Math.abs(value).toFixed(2)}`;
235
+ export const signedUsd = (value) => (value === 0 ? '$0.00' : `${value < 0 ? '−' : '+'}${usd(value)}`);
236
+ export const savingsColor = (value) => (value < 0 ? SAVINGS_COLOR.less : value > 0 ? SAVINGS_COLOR.more : undefined);
237
+
238
+ // The difference against your model: "−22%", "+15%", or "×5.0" once routing cost twice your model or more. Null when
239
+ // it rounds to nothing or there is nothing to compare.
240
+ export function differenceShare(r) {
241
+ if (r.differenceUsd === 0 || r.share === null) return null;
242
+ if (r.ratio >= 2) return `×${r.ratio.toFixed(1)}`;
243
+ const share = Math.round(r.share * 100);
244
+ return share === 0 ? null : `${share < 0 ? '−' : '+'}${Math.abs(share)}%`;
245
+ }
246
+
247
+ // "−$1.84 (−22%)".
248
+ export const savingsAmount = (r) => {
249
+ const share = differenceShare(r);
250
+ return `${signedUsd(r.differenceUsd)}${share ? ` (${share})` : ''}`;
251
+ };
252
+
253
+ export const yourModel = (view) => routeLabel(view.nativeModel, view.nativeEffort);
254
+ export const sinceDate = (ms) => new Date(ms).toLocaleDateString('en-US', { month: 'short', day: 'numeric' });
255
+ const replyCount = (n, what = 'replies') => `${n} ${n === 1 ? what.replace(/ies$/, 'y') : what}`;
256
+
257
+ // The model most stronger replies ran on, and how many ran on stronger models.
258
+ export function strongerReplies(totals) {
259
+ const [model] = Object.entries(totals?.stronger ?? {}).sort((a, b) => b[1] - a[1])[0] ?? [];
260
+ const count = Object.values(totals?.stronger ?? {}).reduce((sum, n) => sum + n, 0);
261
+ return { model: model ?? null, count, several: Object.keys(totals?.stronger ?? {}).length > 1 };
262
+ }
263
+
264
+ // The `/router` line without a surface: this session's difference, or why there is none yet, with the saved totals
265
+ // when this session has no routed reply.
266
+ export function savingsLine(view) {
267
+ const label = `vs your model (${yourModel(view)})`;
268
+ const session = readout(view.savings ?? emptyTotals());
269
+ const store = readSavingsStore(view.savingsStore);
270
+ const across = readout(store);
271
+ if (!session.replies) {
272
+ const saved = across.early
273
+ ? ''
274
+ : `; ${savingsAmount(across)} since ${sinceDate(store.since)}, each session compared with its own model`;
275
+ return `${label}: no routed replies this session${saved}`;
276
+ }
277
+ if (session.early) return `${label}: too early, ${replyCount(session.replies, 'routed replies')}`;
278
+ const stronger = strongerReplies(view.savings);
279
+ const replies =
280
+ session.differenceUsd > 0 && stronger.count
281
+ ? `${stronger.count} of ${replyCount(session.replies)} on ${stronger.several ? 'stronger models' : modelName(stronger.model)}`
282
+ : replyCount(session.replies);
283
+ return `${label}: ${savingsAmount(session)} this session, ${replies}, est. at list prices`;
284
+ }
285
+
226
286
  export const GATEWAY_SETTINGS = 'v0.8 gateway settings remain · see /router';
287
+ // Why routing is unavailable, as the band and the pane say it: they show the gateway cleanup themselves.
288
+ export const unavailableReason = (view) =>
289
+ view.error === GATEWAY_SETTINGS ? 'v0.8 gateway settings remain' : (view.error ?? 'unknown error');
227
290
  export const GATEWAY_CLEANUP = [
228
291
  'Remove from settings.json, then restart: model jev-router[1m], its modelPicker row,',
229
292
  'env.ANTHROPIC_BASE_URL for 127.0.0.1:43170, env.CLAUDE_CODE_GATEWAY_HINT_HEADERS,',
@@ -260,8 +323,9 @@ export function usageMetrics(config, view, usage) {
260
323
  const nextContext = candidates.length ? Math.max(...candidates) : null;
261
324
  const reuse = view.inputTokens > 0 && Number.isFinite(view.cacheRead) ? view.cacheRead / view.inputTokens : null;
262
325
  const cost = Number.isFinite(usage?.cost?.usd) ? usage.cost.usd : null;
326
+ const rates = spec && ratesAt(spec, view.inputTokens ?? 0);
263
327
  const cacheBenefit =
264
- spec && Number.isFinite(view.cacheRead) ? ((spec.input - spec.cacheRead) * view.cacheRead) / 1e6 : null;
328
+ rates && Number.isFinite(view.cacheRead) ? ((rates.input - rates.cacheRead) * view.cacheRead) / 1e6 : null;
265
329
  return {
266
330
  window,
267
331
  observed,