@alexeiled/claude-router 1.15.0 → 1.17.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -6,7 +6,9 @@ import { acceptActivity } from './activity.mjs';
6
6
  import { ACTIVITIES, ACTIVITY_VALUES } from './config.mjs';
7
7
  import { afterResetOf, earlierSince, isRecord } from './records.mjs';
8
8
 
9
- export const OBSERVED = ['code', 'docs', 'ops', 'read', 'talk'];
9
+ // A turn's bucket from its tools (observedActivity in facts.mjs). `shell` and `check` came in 1.16: a version before
10
+ // reads a store that holds them as empty.
11
+ export const OBSERVED = ['code', 'docs', 'shell', 'ops', 'check', 'read', 'talk'];
10
12
  // The one stats key every session shared before 1.10.3: it reads as another session's record until a reset deletes it.
11
13
  export const STORE_KEY = 'activity:stats:v1';
12
14
  // Each session keeps its own stats under this prefix and its session id, as the metrics do.
@@ -16,16 +18,17 @@ export const STORE_PREFIX = 'activity:stats:v1:';
16
18
  export const METRICS_PREFIX = 'activity:metrics:v1:';
17
19
 
18
20
  // The observed buckets each predicted activity allows. A weak oracle: it tells code from ops and explore, and cannot
19
- // separate plan from review. That is enough to catch a cheap route on a coding turn.
21
+ // separate plan from review. That is enough to catch a cheap route on a coding turn. A `shell` write is a candidate
22
+ // for code, docs or routine work, so each of them allows it; a `check` run fits a review, a debug session or ops.
20
23
  export const ALLOWED = {
21
- code: ['code'],
22
- debug: ['code', 'ops', 'read'],
24
+ code: ['code', 'shell'],
25
+ debug: ['code', 'shell', 'ops', 'check', 'read'],
23
26
  explore: ['read', 'talk'],
24
27
  plan: ['talk', 'read', 'docs'],
25
- review: ['read', 'talk'],
28
+ review: ['read', 'talk', 'check'],
26
29
  // git status or a test listing is still running commands: a read-only Bash turn is ops too.
27
- ops: ['ops', 'read'],
28
- docs: ['docs'],
30
+ ops: ['ops', 'shell', 'check', 'read'],
31
+ docs: ['docs', 'shell'],
29
32
  };
30
33
 
31
34
  // An answer without an allowed set (uncertain, none) never agrees; callers count agreement only for activities.
@@ -224,9 +227,16 @@ export function mergeStores(values, resetAt = null) {
224
227
  // classifier id, and the cheaper activity moves taken in `on` with the escalations that followed one, since `since`
225
228
  // (ms), the first reading after a reset.
226
229
  export function emptyMetrics() {
227
- return { version: 1, since: null, latency: {}, downMoves: { moves: 0, escalations: 0 } };
230
+ return { version: 1, since: null, latency: {}, downMoves: { moves: 0, escalations: 0 }, unpriced: emptyUnpriced() };
228
231
  }
229
232
 
233
+ // Why a routed main reply was left out of the usage record (unpricedCause in savings.mjs): its usage did not read
234
+ // (`usage`), a model in the comparison had no price (`model`), the cache lifetime could not be read (`ttl`), or the
235
+ // comparison failed (`error`), or its observed cost is known but the counterfactual is not (`comparison`).
236
+ // Kept beside the stats from 1.16; older records have no missing comparisons.
237
+ export const UNPRICED_CAUSES = ['usage', 'model', 'ttl', 'error', 'comparison'];
238
+ const emptyUnpriced = () => Object.fromEntries(UNPRICED_CAUSES.map((cause) => [cause, 0]));
239
+
230
240
  const isLatency = (v) =>
231
241
  isRecord(v) &&
232
242
  Object.keys(v).length <= LATENCY_CLASSIFIERS &&
@@ -237,24 +247,37 @@ const isLatency = (v) =>
237
247
  export function readMetrics(value) {
238
248
  const empty = emptyMetrics();
239
249
  if (!isRecord(value) || value.version !== 1) return empty;
250
+ const unpriced = isRecord(value.unpriced) ? { comparison: 0, ...value.unpriced } : null;
240
251
  return {
241
252
  version: 1,
242
253
  since: Number.isFinite(value.since) ? value.since : null,
243
254
  latency: isLatency(value.latency) ? value.latency : empty.latency,
244
255
  downMoves: exactCountsOf(value.downMoves, ['moves', 'escalations']) ? value.downMoves : empty.downMoves,
256
+ unpriced: exactCountsOf(unpriced, UNPRICED_CAUSES) ? unpriced : empty.unpriced,
245
257
  };
246
258
  }
247
259
 
248
- // One finished turn at `now`: `adviceMs` how long `classifier` took (null: not timed), and `downMove` 'moved' or
249
- // 'escalated' (advanceDown). A turn that adds nothing returns `metrics` itself.
250
- export function recordMetrics(metrics, { classifier = null, adviceMs = null, downMove = null, now = null }) {
260
+ // One finished turn at `now`: `adviceMs` how long `classifier` took (null: not timed), `downMove` 'moved' or
261
+ // 'escalated' (advanceDown), and `unpriced` the turn's routed replies left unpriced, by cause. A turn that adds nothing
262
+ // returns `metrics` itself.
263
+ export function recordMetrics(
264
+ metrics,
265
+ { classifier = null, adviceMs = null, downMove = null, unpriced = {}, now = null },
266
+ ) {
251
267
  const next = {
252
268
  version: 1,
253
269
  since: metrics.since ?? now,
254
270
  latency: { ...metrics.latency },
255
271
  downMoves: { ...metrics.downMoves },
272
+ unpriced: { ...emptyUnpriced(), ...metrics.unpriced },
256
273
  };
257
274
  let counted = downMove === 'moved' || downMove === 'escalated';
275
+ for (const cause of UNPRICED_CAUSES) {
276
+ const n = count(unpriced?.[cause]);
277
+ if (!n) continue;
278
+ next.unpriced[cause] += n;
279
+ counted = true;
280
+ }
258
281
  const known = Object.hasOwn(next.latency, classifier);
259
282
  if (
260
283
  typeof classifier === 'string' &&
@@ -293,6 +316,7 @@ export function mergeMetrics(values, resetAt = null) {
293
316
  moves: merged.downMoves.moves + one.downMoves.moves,
294
317
  escalations: merged.downMoves.escalations + one.downMoves.escalations,
295
318
  };
319
+ for (const cause of UNPRICED_CAUSES) merged.unpriced[cause] += one.unpriced[cause];
296
320
  }
297
321
  return merged;
298
322
  }
package/lib/activity.mjs CHANGED
@@ -13,14 +13,19 @@ export function acceptActivity(config, advice) {
13
13
  }
14
14
 
15
15
  // 1 when route `a` is stronger than `b`, -1 when cheaper, 0 when equal in strength, null when they cannot be ordered.
16
- // Models order by configured output price, then effort. A null effort is `sentEffort`, the one Claude Code sends, as
16
+ // Models with explicit strength order by that rank; otherwise by configured output price, then effort. A null effort is `sentEffort`, the one Claude Code sends, as
17
17
  // the request would carry it; without a named effort on both sides (none sent, or a numeric budget) two different
18
18
  // efforts do not order. A missing output price orders only against the same model.
19
19
  export function compareRoutes(config, a, b, sentEffort) {
20
20
  if (a.model !== b.model) {
21
21
  const [pa, pb] = [routeSpec(config, a).output, routeSpec(config, b).output];
22
- if (!Number.isFinite(pa) || !Number.isFinite(pb)) return null;
23
- if (pa !== pb) return Math.sign(pa - pb);
22
+ const [sa, sb] = [routeSpec(config, a).strength, routeSpec(config, b).strength];
23
+ if (Number.isFinite(sa) && Number.isFinite(sb)) {
24
+ if (sa !== sb) return Math.sign(sa - sb);
25
+ } else {
26
+ if (!Number.isFinite(pa) || !Number.isFinite(pb)) return null;
27
+ if (pa !== pb) return Math.sign(pa - pb);
28
+ }
24
29
  }
25
30
  const [ea, eb] = [routeEffort(config, a, sentEffort), routeEffort(config, b, sentEffort)];
26
31
  if (ea === eb) return 0;
@@ -34,10 +39,10 @@ export const sameRequest = (config, a, b, sentEffort) =>
34
39
 
35
40
  // The activity a turn runs with, given the incumbent cell `{ tier, activity }` and its resolved `route`. Without
36
41
  // advice, or without an activity answer (a skipped, failed or malformed activity step), the incumbent's activity
37
- // stays: a flaky step must not move the route every turn. On the same task (sameTaskOf: a review inside a turn, or a
38
- // continuation prompt) a stronger label is taken at once (explore, then code), and a weaker one only with at least
39
- // `downgradeMass` probability once facts.downAllowed holds: the dwell has passed and a verification passed since the
40
- // last model change. An unclear label keeps the running activity.
42
+ // stays: a flaky step must not move the route every turn. On the same task (sameTaskOf: a review inside a turn, a turn
43
+ // with a progress origin, or a continuation prompt) a stronger label is taken at once (explore, then code), and a weaker
44
+ // one only with at least `downgradeMass` probability once facts.downAllowed holds: the dwell has passed and a checkpoint
45
+ // (completedSince) since the last model change. An unclear label keeps the running activity.
41
46
  export function chooseActivity(config, advice, incumbent, sentEffort, facts = {}) {
42
47
  if (!advice?.activity) return incumbent.activity;
43
48
  if (!sameTaskOf(config, advice, facts)) return acceptActivity(config, advice);
package/lib/band.mjs CHANGED
@@ -5,6 +5,7 @@ import {
5
5
  classifierStatus,
6
6
  classifierWarns,
7
7
  differenceShare,
8
+ modeLever,
8
9
  modelColor,
9
10
  modelName,
10
11
  NOT_A_TIER_REASON,
@@ -198,7 +199,7 @@ export function bandSegments(config, view, usage, actions) {
198
199
  main,
199
200
  pin,
200
201
  segment(1, part(shortReason(view.reason, reasonActivity(config, view)), { dimColor: true })),
201
- segment(5, part(routingModeText(view), { dimColor: true })),
202
+ segment(5, part([routingModeText(view), modeLever(config, view)].filter(Boolean).join(' · '), { dimColor: true })),
202
203
  support ? segment(4, part(support, { dimColor: true })) : null,
203
204
  Number.isFinite(switchUsd) && switchUsd >= 0.005
204
205
  ? segment(4, part(`switch cost ≈ ${usd(switchUsd)}`, { dimColor: true }))
@@ -6,16 +6,16 @@ const isRecord = (value) => typeof value === 'object' && value !== null && !Arra
6
6
 
7
7
  // The router.json text after `change(previousFile)` and the config it loads, from the file's text or null when there
8
8
  // is none. Throws when the old text is not JSON or the result does not validate.
9
- export function rewrittenConfig(text, change) {
9
+ export function rewrittenConfig(text, change, provider = 'anthropic') {
10
10
  const file = change(text === null ? {} : JSON.parse(text));
11
- return { config: loadConfig({ userFile: file }), text: `${JSON.stringify(file, null, 2)}\n` };
11
+ return { config: loadConfig({ userFile: file, provider }), text: `${JSON.stringify(file, null, 2)}\n` };
12
12
  }
13
13
 
14
14
  // The pane line for a write that failed.
15
- export function notSaved(error) {
15
+ export function notSaved(error, filename = 'router.json') {
16
16
  // A JSON parse message quotes the file; the loadConfig messages name the setting only.
17
- const reason = error instanceof SyntaxError ? 'router.json is not valid JSON' : error.message;
18
- return `Not saved: ${reason}. router.json is unchanged.`;
17
+ const reason = error instanceof SyntaxError ? `${filename} is not valid JSON` : error.message;
18
+ return `Not saved: ${reason}. ${filename} is unchanged.`;
19
19
  }
20
20
 
21
21
  // The leaves where router.json `after` differs from `before`, each with its value in `before`, or no `value` where it
package/lib/config.mjs CHANGED
@@ -1,5 +1,7 @@
1
1
  // Defaults, user overrides and validation. Pure: callers pass env and the parsed user file.
2
2
 
3
+ import { executionDefaults, providerName } from './providers.mjs';
4
+
3
5
  export const TIERS = ['micro', 'low', 'medium', 'high'];
4
6
  export const EFFORTS = ['low', 'medium', 'high', 'xhigh', 'max'];
5
7
  // What kind of work a turn does, named by what it produces. Closed: the classifier question is built for this set.
@@ -102,6 +104,8 @@ export const DEFAULTS = {
102
104
  },
103
105
  },
104
106
  cache: {
107
+ mode: 'explicit',
108
+ effortScope: 'auto',
105
109
  writeMultiplier: { '5m': 1.25, '1h': 2 },
106
110
  ttlMs: { '5m': 300_000, '1h': 3_600_000 },
107
111
  warmMarginMs: 30_000,
@@ -134,13 +138,16 @@ export const DEFAULTS = {
134
138
  },
135
139
  // `cost` uses a cheaper route where the turn allows it, `quality` a stronger one; `balanced` routes as 1.14. The
136
140
  // routes stay as configured: the mode moves a tier's route one step (lib/modes.mjs). Each mode's `policy` replaces
137
- // those fields of `policy` while it is active. The values are codex-router's presets, not tuned on this router.
141
+ // those fields of `policy` while it is active. The values started as codex-router's presets. 1.16 sets cost's upgrade
142
+ // bar to balanced's (2 votes from 0.75): from 3 votes at 0.85 the bar, raised by the cache write of a cold stronger
143
+ // model, sat at 0.92 from 60k tokens and 0.97 at 254k, so a cost turn on Haiku kept a task the classifier scored
144
+ // hard at 90%. Cost still moves down sooner. Not tuned on outcomes yet.
138
145
  mode: 'balanced',
139
146
  modes: {
140
147
  cost: {
141
148
  policy: {
142
- upgradeVotes: 3,
143
- upgradeBase: 0.85,
149
+ upgradeVotes: 2,
150
+ upgradeBase: 0.75,
144
151
  jumpConfidence: 0.98,
145
152
  downgradeVotes: 1,
146
153
  downgradeMass: 0.8,
@@ -223,7 +230,18 @@ export const DEFAULTS = {
223
230
 
224
231
  // Keys a route, a model or a classifier entry may carry. The other closed sections take their key sets from DEFAULTS.
225
232
  const ROUTE_KEYS = ['model', 'effort'];
226
- const MODEL_KEYS = ['id', 'input', 'output', 'cacheRead', 'longContext', 'contextWindow', 'billing', 'efforts'];
233
+ const MODEL_KEYS = [
234
+ 'id',
235
+ 'input',
236
+ 'output',
237
+ 'cacheRead',
238
+ 'longContext',
239
+ 'contextWindow',
240
+ 'billing',
241
+ 'efforts',
242
+ 'strength',
243
+ 'imageInput',
244
+ ];
227
245
  const CLASSIFIER_KEYS = ['label', 'api', 'endpoint', 'model', 'keyOption', 'timeoutMs'];
228
246
  // The wire protocols a classifier can speak. Each has an adapter in classifier-apis.mjs; a test keeps the two in step.
229
247
  export const CLASSIFIER_APIS = ['system-one', 'openai-decisions', 'ollama'];
@@ -242,12 +260,16 @@ const FORBIDDEN_KEYS = new Set(['__proto__', 'constructor', 'prototype']);
242
260
  export const MIGRATION_HINT =
243
261
  'run node scripts/migrate-config.mjs /path/to/router.json from the router plugin directory';
244
262
 
245
- export function loadConfig({ userFile = null } = {}) {
263
+ export const defaultsFor = (provider = 'anthropic') => executionDefaults(providerName(provider), DEFAULTS);
264
+
265
+ export function loadConfig({ userFile = null, provider = 'anthropic' } = {}) {
266
+ provider = providerName(provider);
246
267
  if (userFile !== null) checkShape(userFile);
247
- const merged = merge(DEFAULTS, withoutShadow(userFile ?? {}));
268
+ const merged = merge(structuredClone(defaultsFor(provider)), withoutShadow(userFile ?? {}));
248
269
  // A user entry without `api` speaks the System One protocol that every entry spoke before 1.5.
249
270
  const config = {
250
271
  ...merged,
272
+ provider,
251
273
  classifiers: Object.fromEntries(
252
274
  Object.entries(merged.classifiers).map(([id, entry]) => [id, { api: 'system-one', ...entry }]),
253
275
  ),
@@ -294,6 +316,7 @@ export function effectiveRoutes(draft, current) {
294
316
  // change of a default still reaches tiers the user never edited; a route equal to the default is removed.
295
317
  export function withRoutes(file, draft) {
296
318
  const { base } = draft;
319
+ const defaults = defaultsFor(base.provider);
297
320
  const { routes: kept = {}, baselineTier: keptBaseline, ...rest } = file;
298
321
  const routes = {};
299
322
  for (const tier of TIERS) {
@@ -303,14 +326,14 @@ export function withRoutes(file, draft) {
303
326
  continue;
304
327
  }
305
328
  const { model, effort = null } = draft.routes[tier];
306
- const preset = DEFAULTS.routes[tier];
307
- if (model === preset.model && effort === (preset.effort ?? null)) continue;
329
+ const preset = defaults.routes[tier];
330
+ if (preset && model === preset.model && effort === (preset.effort ?? null)) continue;
308
331
  routes[tier] = { model, effort };
309
332
  }
310
333
  const baseline =
311
334
  draft.baselineTier === base.baselineTier
312
335
  ? keptBaseline
313
- : draft.baselineTier === DEFAULTS.baselineTier
336
+ : draft.baselineTier === defaults.baselineTier
314
337
  ? undefined
315
338
  : draft.baselineTier;
316
339
  return {
@@ -359,7 +382,9 @@ export function editActivity(draft, current, activity, tier, kind, value = null)
359
382
  let cell = {
360
383
  model: () => ({ model: value, effort: config.models[value]?.efforts.includes(route.effort) ? route.effort : null }),
361
384
  effort: () => ({ model: route.model, effort: value }),
362
- add: () => ({ ...(cellOf(DEFAULTS.activities, activity, tier) ?? resolveRoute(config, tier)) }),
385
+ add: () => ({
386
+ ...(cellOf(defaultsFor(current.provider).activities, activity, tier) ?? resolveRoute(config, tier)),
387
+ }),
363
388
  remove: () => null,
364
389
  }[kind]();
365
390
  const saved = cellOf(draft.base.activities, activity, tier);
@@ -374,18 +399,19 @@ export function editActivity(draft, current, activity, tier, kind, value = null)
374
399
  // route in `file` (the merge would bring the built-in back otherwise), so call this after withRoutes.
375
400
  export function withActivities(file, draft) {
376
401
  const { base } = draft;
402
+ const defaults = defaultsFor(base.provider);
377
403
  const { activities: kept = {}, activityRouting: keptMode, ...rest } = withoutShadow(file);
378
404
  const activities = {};
379
405
  for (const activity of ACTIVITIES) {
380
406
  for (const tier of TIERS) {
381
407
  const cell = cellOf(draft.activities, activity, tier);
382
- const preset = cellOf(DEFAULTS.activities, activity, tier);
408
+ const preset = cellOf(defaults.activities, activity, tier);
383
409
  let written;
384
410
  if (!draft.activities || sameCell(cell, cellOf(base.activities, activity, tier)))
385
411
  written = cellOf(kept, activity, tier);
386
412
  else if (cell) written = sameCell(cell, preset) ? undefined : cell;
387
413
  else if (preset) {
388
- const route = { ...DEFAULTS.routes[tier], ...file.routes?.[tier] };
414
+ const route = { ...defaults.routes[tier], ...file.routes?.[tier] };
389
415
  written = { model: route.model, effort: route.effort ?? null };
390
416
  }
391
417
  if (written) activities[activity] = { ...activities[activity], [tier]: written };
@@ -394,7 +420,7 @@ export function withActivities(file, draft) {
394
420
  const mode =
395
421
  draft.activityRouting === undefined || draft.activityRouting === base.activityRouting
396
422
  ? keptMode
397
- : draft.activityRouting === DEFAULTS.activityRouting
423
+ : draft.activityRouting === defaults.activityRouting
398
424
  ? undefined
399
425
  : draft.activityRouting;
400
426
  return {
@@ -580,6 +606,15 @@ function validate(config) {
580
606
  }
581
607
  }
582
608
  for (const [alias, model] of Object.entries(config.models)) validateModel(`models.${alias}`, model);
609
+ if (config.provider !== 'anthropic') {
610
+ for (const tier of TIERS)
611
+ for (const activity of [null, ...ACTIVITIES]) {
612
+ const route = resolveRoute(config, tier, activity);
613
+ const model = routeSpec(config, route);
614
+ if (route.effort && !model.efforts.includes(route.effort))
615
+ throw new Error('provider route effort is not supported by its model');
616
+ }
617
+ }
583
618
  if (!TIERS.includes(config.baselineTier)) throw new Error(`baselineTier must be one of ${TIERS.join(', ')}`);
584
619
  validatePolicy(config.policy, 'policy');
585
620
  if (!ROUTING_MODES.includes(config.mode)) throw new Error(`mode must be one of ${ROUTING_MODES.join(', ')}`);
@@ -587,6 +622,15 @@ function validate(config) {
587
622
  for (const mode of PATCHED_MODES)
588
623
  validatePolicy({ ...config.policy, ...config.modes[mode]?.policy }, `modes.${mode}.policy`);
589
624
  const { cache, context } = config;
625
+ if (!['explicit', 'automatic', 'disabled'].includes(cache.mode))
626
+ throw new Error('cache.mode must be explicit, automatic or disabled');
627
+ if (!['auto', 'shared', 'separate', 'unknown'].includes(cache.effortScope))
628
+ throw new Error('cache.effortScope must be auto, shared, separate or unknown');
629
+ if (
630
+ cache.mode === 'explicit' &&
631
+ ['5m', '1h'].some((ttl) => !Object.hasOwn(cache.writeMultiplier, ttl) || !Object.hasOwn(cache.ttlMs, ttl))
632
+ )
633
+ throw new Error('explicit cache requires 5m and 1h prices and lifetimes');
590
634
  for (const map of ['writeMultiplier', 'ttlMs']) {
591
635
  for (const [ttl, value] of Object.entries(cache[map]))
592
636
  if (!isNumber(value, 0, { above: true })) throw new Error(`cache.${map}.${ttl} must be positive`);
@@ -603,7 +647,12 @@ function validate(config) {
603
647
  throw new Error(`subagents.types.${type} must be a models key, ${CLASSIFY} or null`);
604
648
  }
605
649
  for (const field of ['light', 'standard', 'heavy']) {
606
- if (!(typeof subagents[field] === 'string' && Object.hasOwn(config.models, subagents[field])))
650
+ if (
651
+ !(
652
+ typeof subagents[field] === 'string' &&
653
+ (config.subagentRouting === 'off' || Object.hasOwn(config.models, subagents[field]))
654
+ )
655
+ )
607
656
  throw new Error(`subagents.${field} is not in models`);
608
657
  }
609
658
  if (!(isNumber(subagents.heavyMass, 0) && subagents.heavyMass <= 1))
@@ -632,6 +681,10 @@ function validatePolicy(p, at) {
632
681
  }
633
682
 
634
683
  function validateModel(at, model) {
684
+ if (model.strength !== undefined && !isNumber(model.strength, 0))
685
+ throw new Error(`${at}.strength must be a non-negative number`);
686
+ if (model.imageInput !== undefined && typeof model.imageInput !== 'boolean')
687
+ throw new Error(`${at}.imageInput must be a boolean`);
635
688
  for (const field of ['input', 'cacheRead', 'contextWindow']) {
636
689
  if (!Number.isFinite(model[field]) || model[field] < 0)
637
690
  throw new Error(`${at}.${field} must be a non-negative number`);
package/lib/cost.mjs CHANGED
@@ -1,4 +1,5 @@
1
1
  import { EFFORTS, routeSpec } from './config.mjs';
2
+ import { canonicalModel } from './providers.mjs';
2
3
 
3
4
  // Models that keep one prompt cache across effort levels with an API key or a Claude subscription
4
5
  // (code.claude.com/docs/en/prompt-caching, "Changing effort level"). A dated snapshot or a `[1m]` suffix is the same
@@ -6,13 +7,16 @@ import { EFFORTS, routeSpec } from './config.mjs';
6
7
  const EFFORT_SHARED_CACHE = ['claude-opus-5-5', 'claude-sonnet-5-5', 'claude-haiku-5-5', 'claude-fable-5-1'];
7
8
 
8
9
  export function effortSharesCache(config, modelId) {
9
- if (config.effortSplitsCache || typeof modelId !== 'string') return false;
10
- const bare = modelId.replace(/\[[^\]]*\]$/, '').replace(/-\d{8}$/, '');
10
+ if (typeof modelId !== 'string' || config.cache.mode === 'disabled') return false;
11
+ if (config.cache.effortScope === 'shared') return true;
12
+ if (['separate', 'unknown'].includes(config.cache.effortScope) || config.effortSplitsCache) return false;
13
+ const bare = canonicalModel(modelId).replace(/-\d{8}$/, '');
11
14
  return EFFORT_SHARED_CACHE.includes(bare);
12
15
  }
13
16
 
14
17
  export function cacheKey(config, modelId, effort) {
15
- return effort && !effortSharesCache(config, modelId) ? `${modelId}@${effort}` : modelId;
18
+ const id = canonicalModel(modelId);
19
+ return effort && !effortSharesCache(config, modelId) ? `${id}@${effort}` : id;
16
20
  }
17
21
 
18
22
  export function clampEffort(wanted, supported) {
@@ -53,6 +57,7 @@ export function routeCacheKey(config, route, sentEffort) {
53
57
  }
54
58
 
55
59
  export function isWarm(state, now, cache) {
60
+ if (cache.mode && cache.mode !== 'explicit') return false;
56
61
  return Boolean(
57
62
  state?.prefixTokens > 0 && now >= state.lastAt && now < state.lastAt + cache.ttlMs['5m'] - cache.warmMarginMs,
58
63
  );
@@ -68,6 +73,13 @@ export function inputBounds(config, route, tokens, facts, now) {
68
73
  const state = facts.models[routeCacheKey(config, route, facts.effort)];
69
74
  const prefix = Math.min(state?.prefixTokens ?? tokens, tokens);
70
75
  const fresh = isWarm(state, now, config.cache);
76
+ if (config.cache.mode === 'disabled') return { min: (model.input * tokens) / 1e6, max: (model.input * tokens) / 1e6 };
77
+ if (config.cache.mode === 'automatic')
78
+ return {
79
+ // A miss can construct a prefix for the next request; last request's hits do not bound future hits.
80
+ min: (model.cacheRead * tokens) / 1e6,
81
+ max: (model.input * tokens) / 1e6,
82
+ };
71
83
  const maximumWrite = model.input * Math.max(...Object.values(config.cache.writeMultiplier));
72
84
  return {
73
85
  min: (model.cacheRead * prefix + model.input * (tokens - prefix)) / 1e6,
@@ -77,7 +89,9 @@ export function inputBounds(config, route, tokens, facts, now) {
77
89
 
78
90
  export function coldWriteUsd(config, alias, tokens) {
79
91
  return (
80
- (ratesAt(config.models[alias], tokens).input * Math.max(...Object.values(config.cache.writeMultiplier)) * tokens) /
92
+ (ratesAt(config.models[alias], tokens).input *
93
+ (config.cache.mode === 'explicit' ? Math.max(...Object.values(config.cache.writeMultiplier)) : 1) *
94
+ tokens) /
81
95
  1e6
82
96
  );
83
97
  }
@@ -105,6 +119,7 @@ export function nextTurnRange(config, candidate, incumbent, facts, now) {
105
119
  }
106
120
 
107
121
  export function switchEconomics(config, candidate, incumbent, facts, now) {
122
+ if (config.cache.mode === 'automatic') return null;
108
123
  const tokens = nextContextTokens(facts);
109
124
  const proposed = ratesAt(routeSpec(config, candidate), tokens);
110
125
  const current = ratesAt(routeSpec(config, incumbent), tokens);
@@ -123,6 +138,13 @@ export function switchEconomics(config, candidate, incumbent, facts, now) {
123
138
  }
124
139
 
125
140
  export function downgradeTaxUsd(config, candidate, incumbent, facts, now, turns) {
141
+ // Same-model effort changes trade generated tokens and latency, not per-token rates. Input-only payback cannot
142
+ // evaluate that saving. Keep votes, dwell and the cold-input cap; the displayed cache bounds still allow a miss.
143
+ if (
144
+ config.cache.mode === 'automatic' &&
145
+ canonicalModel(routeSpec(config, candidate).id) === canonicalModel(routeSpec(config, incumbent).id)
146
+ )
147
+ return 0;
126
148
  const estimate = switchEconomics(config, candidate, incumbent, facts, now);
127
149
  if (!estimate) return Math.max(0, switchingTaxUsd(config, candidate, incumbent, facts, now));
128
150
  return Math.max(0, estimate.nextTurnUsd + (turns - 1) * estimate.laterTurnUsd);