@alexeiled/claude-router 1.16.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.
@@ -9,6 +9,9 @@ claude plugin marketplace add alexei-led/claude-router
9
9
  claude plugin install router@alexei-led-claude-router
10
10
  ```
11
11
 
12
+ For another execution provider, follow [Providers](providers.md). That guide covers profile names, defaults and custom files.
13
+ The following startup example uses the default Anthropic profile.
14
+
12
15
  Start with the full baseline model so routing has a known starting point:
13
16
 
14
17
  ```sh
@@ -26,7 +29,10 @@ In Claude Code:
26
29
  3. To use another classifier, open the pane's **Classifier** tab and select its row. See [Choose the classifier](#choose-the-classifier).
27
30
  4. Check the band above the prompt: `Routing on · ready`. On a model that no tier routes to, and that no activity override uses with activity routing `on`, the session starts with routing off and the band says why; run `/router auto` to route.
28
31
 
29
- Keys are stored as sensitive plugin options. Do not paste them into a model conversation. The [configuration guide](configuration.md) covers optional settings and migrations.
32
+ Keys are stored as sensitive plugin options. Do not paste them into a model conversation. The [configuration guide](configuration.md) covers settings and migrations.
33
+
34
+ In this guide, `router.json` means the selected router file. For example, with `CLAUDE_ROUTER_PROVIDER=zai`, edits go to `zai-router.json`.
35
+ The pane shows its provider and file path.
30
36
 
31
37
  ## Read the status band
32
38
 
@@ -52,14 +58,14 @@ Read the first line of the picture from left to right:
52
58
  | `⚠ Clef: no account ID · keeping model` | Clef has its API token but no Cloudflare account ID. **Set up** opens the dialog. |
53
59
  | `⚠ Jev timed out · keeping model` | The classifier failed: timed out, unreachable, rejected the key, or paused. |
54
60
  | `○ Routing off [ Turn on ] · every turn uses …` | Routing is off: Claude's model answers every turn. **Turn on** turns it back on. The footer also shows `routing off`. |
55
- | `✕ Routing unavailable` | Nothing routes: an old Claude Code or leftover v0.8 settings. **Fix** opens the pane. |
61
+ | `✕ Routing unavailable` | Nothing routes: a missing/invalid provider file, an old Claude Code, or leftover v0.8 settings. **Fix** opens the pane. |
56
62
  | `○ Router · ■ Haiku 5.5 · moved down by the router` | You are viewing a subagent's transcript. The model it runs on, and who picked it; see below. |
57
63
 
58
64
  The band shows one routing control at a time. While routing is on, hover over the band for a second row: pin a tier for the next turn, **Turn off** routing, or show two rows. While routing is off, **Turn on** sits on the first line next to `Routing off` and stays at any width: a narrow band drops the explanation and the model first. On a narrow band the hover row drops `routing on`, then **2 rows**, then `pin next turn`, then the pins; it keeps **Turn off**, and **1 row** when the band shows two. The hover row needs a pointer: from the keyboard, run `/router off`, or open the pane and press `f`. The two-row band adds this session against your model, the one `/model` selects now: `session saved $1.84 (22%) vs Opus 5.5 · xhigh · 64 replies · cold-cache writes +$0.47`, or `session extra $2.48 (×5.0) vs Haiku 5.5 · high · 41 replies · stronger models +$2.31` when routing cost more. The last part names the larger of the two costs behind the result, when there is one. After a `/model` change the row shows the whole session against the new model. Before the tenth routed reply it reads `session 3 replies · too early to compare`. When the row is short, the cost part drops first, then the reply count. Router remembers that choice across sessions. When Router changes the model between turns, a toast reads `Model changed: old → new · reason`. A pin does not raise one, and neither does a change of effort alone.
59
65
 
60
66
  The band steps aside while a survey needs the space.
61
67
 
62
- Inside a turn the router checks the route again as the work changes; see [Changes during a task](#changes-during-a-task). A subagent gets at most one model, when it starts, and keeps it for every step: Haiku for exploration, Opus for clearly hard tasks, Sonnet for the rest. An agent that pins a model in its definition keeps it, unless it sets `modelRouting: auto`. The Usage tab's **SUBAGENTS** section shows what each agent type ran on and cost, and the Now tab shows this session's agents. See [Subagent routing](configuration.md#subagent-routing).
68
+ Inside a turn the router checks the route again as the work changes; see [Changes during a task](#changes-during-a-task). A subagent gets at most one model, when it starts, and keeps it for every step: For the Anthropic profile, these are Haiku for exploration, Opus for clearly hard tasks, and Sonnet for the rest. Other profiles have [their own defaults](providers.md#activity-overrides). An agent that pins a model in its definition keeps it, unless it sets `modelRouting: auto`. The Usage tab's **SUBAGENTS** section shows what each agent type ran on and cost, and the Now tab shows this session's agents. See [Subagent routing](configuration.md#subagent-routing).
63
69
 
64
70
  In a subagent's transcript the band names the model the agent runs on and who picked it. `■ Haiku 5.5 · moved down by the router · Claude Code: Opus 5.5` means the router chose a cheaper model than Claude Code would have; `up` means a stronger one. `□ Sonnet 5.5 · the router kept Claude Code’s pick` means the router agreed. `□ Opus 5.5 · Claude Code’s pick: the workflow sets it` means the router did not route the agent, and says why. A narrow band drops the `Claude Code:` part first. The band falls back to `subagent model chosen at spawn` when the router has no record of the agent, such as after a plugin reload, and to `subagents keep their own model` with subagent routing off.
65
71
 
@@ -262,7 +268,11 @@ The model list comes from the aliases in `router.json` `models`, limited by the
262
268
 
263
269
  **Activity routing** at the top sets `off` or `on`, and says what the mode does. A yellow line says when the overrides do not run: activity routing `off`, or routing off or unavailable.
264
270
 
265
- Under the grid, `3 prompt caches in use` counts the caches the grid can run on. Opus 5.5, Sonnet 5.5, Haiku 5.5 and Fable 5.1 keep one cache per model across efforts with an API key or a Claude subscription; on Amazon Bedrock, Google Cloud, Microsoft Foundry or a custom `ANTHROPIC_BASE_URL`, each (model, effort) pair has its own. Moving to a model without a warm cache writes the whole conversation into a new cache, which is the switch cost on the Now tab. More caches mean more of those writes. A yellow line flags two neighbouring tiers that run the same model and effort, since that step changes nothing.
271
+ The Routes tab describes the selected profile's cache policy. With Anthropic explicit caching, it counts the cache identities used by the routes. A model switch can require a cold write of the conversation.
272
+
273
+ Automatic-cache profiles, including DeepSeek and z.ai, do not assume a fixed lifetime or guaranteed sharing across efforts. They use hit/miss input prices without a separate write premium. See [cache settings](configuration.md#provider-cache-behavior).
274
+
275
+ A yellow line flags neighbouring tiers with the same model and effort. That step changes nothing.
266
276
 
267
277
  **Reset routes to defaults** (`r`) loads the built-in tier routes and start tier into the draft; **Save** then removes your route overrides from `router.json`. Activity edits and the mode stay in the draft.
268
278
 
@@ -315,7 +325,9 @@ The routing policy thresholds were tuned against Jev's probabilities. Clef's, Op
315
325
 
316
326
  ### Use Ollama
317
327
 
318
- Ollama runs the classifier on this machine, so the prompt text does not leave it. It needs no key.
328
+ This section configures Ollama as the **classifier**, not the model that answers your prompts. To route coding models on Ollama, use a [custom execution-provider profile](providers.md#add-another-provider).
329
+
330
+ Ollama runs the classifier on this machine, so classification text stays local. It needs no key.
319
331
 
320
332
  1. Install Ollama and pull a model: `ollama pull qwen3.5:9b`.
321
333
  2. Start the server: `ollama serve`. The router calls `http://127.0.0.1:11434`.
@@ -348,7 +360,9 @@ To stop routing for a session, run `/router off`. To keep tier routing but stop
348
360
  | Status says `no account ID` | Clef, Clef Flash or Clef Omni is active without the Cloudflare account ID. | Run `/plugin configure router` and save the Cloudflare account ID. |
349
361
  | Route stays on the current model | The classifier timed out, failed, is paused, or network policy refused it. | Read the status band and the pane header. Network policy refusal is not bypassed. |
350
362
  | `/model` changed but routing stopped | Choosing a model turns routing off. | Run `/router auto` to turn routing back on. |
351
- | Router reports invalid configuration | `router.json` is invalid, or project/local settings redirect the router profile. | Inspect `router.json`, remove project/local `HOME` or `CLAUDE_CONFIG_DIR` overrides, or run the [migration command](configuration.md#convert-an-older-routerjson). |
363
+ | Selected provider file is missing | The provider name selects a file that does not exist. | Create that file in the active Claude Code profile directory. Use `{}` only for built-in profiles. See [Providers](providers.md). |
364
+ | A custom profile containing `{}` fails | No built-in model catalog exists for that provider name. | Define all four routes and their model entries. See the [custom profile example](providers.md#add-another-provider). |
365
+ | Router reports invalid configuration | The selected file is invalid, or project/local settings redirect the profile. | Inspect the file shown in the pane. Remove project/local `HOME`, `CLAUDE_CONFIG_DIR`, or `CLAUDE_ROUTER_PROVIDER` overrides. |
352
366
  | Router says old settings need migration | `router.json` still contains v0.8 gateway keys or the 1.1 `jev` section. | Run the [migration command](configuration.md#convert-an-older-routerjson). |
353
367
  | `⚠ OpenAI rejected the key · keeping model` | The OpenAI key is wrong, revoked, or lacks access to `gpt-6-luna`. | Run `/plugin configure router` and save a valid OpenAI API key. |
354
368
  | `⚠ Ollama unreachable · keeping model` | No Ollama server listens on `127.0.0.1:11434`. | Run `ollama serve`, then start a new turn. |
@@ -26,6 +26,7 @@ import {
26
26
  activeClassifier,
27
27
  CLASSIFY,
28
28
  DEFAULTS,
29
+ defaultsFor,
29
30
  editActivity,
30
31
  effectiveActivities,
31
32
  effectiveRoutes,
@@ -74,10 +75,11 @@ import {
74
75
  unavailableReason,
75
76
  unpricedLine,
76
77
  } from '../lib/display.mjs';
77
- import { clip, observedActivity, promptIndex, routingBucket } from '../lib/facts.mjs';
78
+ import { clip, hasImages, observedActivity, promptIndex, routingBucket } from '../lib/facts.mjs';
78
79
  import { applyMode, modeLabel, readProjectMode, resolveRoutingMode } from '../lib/modes.mjs';
79
80
  import { renderPanel, routeDraftOf, routingChanges } from '../lib/panel.mjs';
80
81
  import { sameTaskOf } from '../lib/policy.mjs';
82
+ import { providerFile, providerName } from '../lib/providers.mjs';
81
83
  import {
82
84
  canMoveUp,
83
85
  cellForModel,
@@ -102,6 +104,7 @@ import {
102
104
  modelAlias,
103
105
  modelEntry,
104
106
  modelSpec,
107
+ observedReplyUsd,
105
108
  readSavingsStore,
106
109
  SAVINGS_PREFIX,
107
110
  SAVINGS_RESET_KEY,
@@ -671,27 +674,41 @@ async function effortSplitsCacheOf($) {
671
674
  async function loadNativeConfig($) {
672
675
  for (const source of ['project', 'local']) {
673
676
  const settings = await $.settings.read({ source });
674
- if (settings.env && ['HOME', 'CLAUDE_CONFIG_DIR'].some((key) => Object.hasOwn(settings.env, key)))
677
+ if (
678
+ settings.env &&
679
+ ['HOME', 'CLAUDE_CONFIG_DIR', 'CLAUDE_ROUTER_PROVIDER'].some((key) => Object.hasOwn(settings.env, key))
680
+ )
675
681
  throw new Error('project settings cannot redirect the router profile');
676
682
  }
677
683
  const home = await $.env.get('HOME');
678
684
  const profile = (await $.env.get('CLAUDE_CONFIG_DIR')) ?? `${home}/.claude`;
679
- const path = `${profile}/router.json`;
685
+ const provider = providerName(await $.env.get('CLAUDE_ROUTER_PROVIDER'));
686
+ const path = `${profile}/${providerFile(provider)}`;
687
+ if (provider !== 'anthropic' && !(await $.fs.exists(path)))
688
+ throw new Error('selected provider router file is missing');
680
689
  const userFile = (await $.fs.exists(path)) ? JSON.parse(await $.fs.read(path)) : null;
681
- return { ...loadConfig({ userFile }), nativePath: path, effortSplitsCache: await effortSplitsCacheOf($) };
690
+ return { ...loadConfig({ userFile, provider }), nativePath: path, effortSplitsCache: await effortSplitsCacheOf($) };
682
691
  }
683
692
 
684
693
  // Writes router.json through `change(previousFile)` once the result validates. Returns the new config or an error
685
694
  // line for the pane; a failure leaves the file untouched.
686
- async function saveConfig($, path, change) {
695
+ async function saveConfig($, active, change) {
696
+ const path = active.nativePath;
697
+ const filename = path?.split('/').at(-1) ?? 'router.json';
687
698
  try {
699
+ if (active.provider !== 'anthropic' && !(await $.fs.exists(path)))
700
+ throw new Error('selected provider router file is missing');
688
701
  if ((await $.fs.exists(path)) && (await $.fs.stat(path)).isLink)
689
- return { error: 'Not saved: router.json is a symlink. Edit its maintained source instead.' };
690
- const { config, text } = rewrittenConfig((await $.fs.exists(path)) ? await $.fs.read(path) : null, change);
702
+ return { error: `Not saved: ${filename} is a symlink. Edit its maintained source instead.` };
703
+ const { config, text } = rewrittenConfig(
704
+ (await $.fs.exists(path)) ? await $.fs.read(path) : null,
705
+ change,
706
+ active.provider,
707
+ );
691
708
  await $.fs.write(path, text);
692
- return { config: { ...config, nativePath: path, effortSplitsCache: await effortSplitsCacheOf($) } };
709
+ return { config: { ...config, nativePath: path, effortSplitsCache: active.effortSplitsCache } };
693
710
  } catch (error) {
694
- return { error: notSaved(error) };
711
+ return { error: notSaved(error, filename) };
695
712
  }
696
713
  }
697
714
 
@@ -707,6 +724,7 @@ function detailText(config, view) {
707
724
  const missing = missingCredentials(config, view, config.classifier);
708
725
  return [
709
726
  `Router — routing ${view.mode === 'auto' ? 'on' : 'off'}`,
727
+ ...(config.provider !== 'anthropic' ? [`Provider: ${config.provider} · ${config.nativePath}`] : []),
710
728
  ...(view.routingMode ? [`Mode: ${modeLabel(view.routingMode)}`] : []),
711
729
  ...(view.projectError ? [`Ignored: ${view.projectError}`] : []),
712
730
  `Native model: ${view.nativeModel}`,
@@ -1141,19 +1159,22 @@ async function observeRouted($, router, { turnId, cfg, loop, loopVersion, reques
1141
1159
  const tier = isSameModel(request.model, response.usage?.model) ? loop.decision.tier : null;
1142
1160
  const route = `${request.model}@${request.effort ?? 'session'}`;
1143
1161
  // Why the usage record leaves this reply out, when it does (UNPRICED_CAUSES).
1162
+ const observedUsd = compared?.reply?.routedUsd ?? observedReplyUsd(cfg, response.usage, compared?.ttl);
1144
1163
  const cause = !compared
1145
1164
  ? response.usage?.model
1146
1165
  ? 'error'
1147
1166
  : 'usage'
1148
1167
  : compared.reply
1149
1168
  ? null
1150
- : (unpricedCause(cfg, {
1151
- usage: response.usage,
1152
- served: { model: response.usage.model, effort: request.effort ?? null },
1153
- yours: { model: nativeModel },
1154
- ttl: compared.ttl,
1155
- }) ?? 'error');
1156
- await publishReply($, router, turnId, response, tier, route, compared?.reply?.routedUsd ?? null, cause);
1169
+ : observedUsd !== null
1170
+ ? 'comparison'
1171
+ : (unpricedCause(cfg, {
1172
+ usage: response.usage,
1173
+ served: { model: response.usage.model, effort: request.effort ?? null },
1174
+ yours: { model: nativeModel },
1175
+ ttl: compared.ttl,
1176
+ }) ?? 'error');
1177
+ await publishReply($, router, turnId, response, tier, route, observedUsd, cause);
1157
1178
  // Kept by model id, under the model that served it: a substitute's cost is not the requested model's, and a models
1158
1179
  // key can name another model later.
1159
1180
  const idOf = (model) => modelSpec(cfg, model)?.id ?? model;
@@ -1689,7 +1710,7 @@ function paneActions($, router, view) {
1689
1710
  };
1690
1711
  };
1691
1712
  const save = async (change, saved) => {
1692
- const result = await saveConfig($, router.config.nativePath, change);
1713
+ const result = await saveConfig($, router.config, change);
1693
1714
  if (result.error) return updateView($, router, { notice: result.error });
1694
1715
  const drafts = router.view ?? view;
1695
1716
  const reset = await adopt(result.config);
@@ -1705,7 +1726,7 @@ function paneActions($, router, view) {
1705
1726
  return updateView($, router, {
1706
1727
  ...patch,
1707
1728
  notice: pending
1708
- ? `${what === 'route' ? 'Route' : 'Policy'} defaults loaded. Save removes your ${what} overrides from router.json.`
1729
+ ? `${what === 'route' ? 'Route' : 'Policy'} defaults loaded. Save removes your ${what} overrides from ${router.config.nativePath?.split('/').at(-1) ?? 'router.json'}.`
1709
1730
  : `${what === 'route' ? 'Routes' : 'Policy'} already at defaults.`,
1710
1731
  });
1711
1732
  };
@@ -1856,16 +1877,21 @@ function paneActions($, router, view) {
1856
1877
  discardRouting: () => updateView($, router, { routeDraft: null, tuning: null, tuningBase: null, notice: null }),
1857
1878
  // Routes only: pending activity edits and the mode stay in the draft.
1858
1879
  resetRoutes: () =>
1859
- loadDefaults(
1860
- {
1861
- routeDraft: {
1862
- ...routeDraftOf(router.config, router.view ?? view),
1863
- ...structuredClone({ routes: DEFAULTS.routes, baselineTier: DEFAULTS.baselineTier }),
1864
- base: routeDraftOf(router.config, {}).base,
1865
- },
1866
- },
1867
- 'route',
1868
- ),
1880
+ !Object.keys(defaultsFor(router.config.provider).routes).length
1881
+ ? updateView($, router, { notice: 'No built-in route defaults for this provider.' })
1882
+ : loadDefaults(
1883
+ {
1884
+ routeDraft: {
1885
+ ...routeDraftOf(router.config, router.view ?? view),
1886
+ ...structuredClone({
1887
+ routes: defaultsFor(router.config.provider).routes,
1888
+ baselineTier: defaultsFor(router.config.provider).baselineTier,
1889
+ }),
1890
+ base: routeDraftOf(router.config, {}).base,
1891
+ },
1892
+ },
1893
+ 'route',
1894
+ ),
1869
1895
  tune: (key, value) =>
1870
1896
  updateView($, router, {
1871
1897
  tuning: { ...(router.view ?? view).tuning, [key]: value },
@@ -1875,7 +1901,7 @@ function paneActions($, router, view) {
1875
1901
  resetPolicy: () =>
1876
1902
  loadDefaults(
1877
1903
  // The draft is replaced whole, so it starts from the saved values, not from an older draft's base.
1878
- { tuning: tuningOf(DEFAULTS), tuningBase: tuningOf(router.config) },
1904
+ { tuning: tuningOf(defaultsFor(router.config.provider)), tuningBase: tuningOf(router.config) },
1879
1905
  'policy',
1880
1906
  ),
1881
1907
  classifier: (id) => {
@@ -1952,6 +1978,18 @@ async function endSession($, router) {
1952
1978
  };
1953
1979
  }
1954
1980
 
1981
+ async function imagesOf($, config, decision) {
1982
+ if (modelSpec(config, decision?.model)?.imageInput !== false) return false;
1983
+ const messages = await transcript($);
1984
+ return messages === null || hasImages(messages);
1985
+ }
1986
+
1987
+ function configurationError(error) {
1988
+ if (error.message?.endsWith(MIGRATION_HINT))
1989
+ return 'router.json needs migration; run the plugin scripts/migrate-config.mjs with your router.json path';
1990
+ return error.message === 'selected provider router file is missing' ? error.message : 'invalid router configuration';
1991
+ }
1992
+
1955
1993
  export function register(on, options) {
1956
1994
  const router = createRouter(options);
1957
1995
 
@@ -2002,9 +2040,7 @@ export function register(on, options) {
2002
2040
  } catch (error) {
2003
2041
  await updateView($, router, {
2004
2042
  phase: 'unavailable',
2005
- error: error.message?.endsWith(MIGRATION_HINT)
2006
- ? 'router.json needs migration; run the plugin scripts/migrate-config.mjs with your router.json path'
2007
- : 'invalid router configuration',
2043
+ error: configurationError(error),
2008
2044
  });
2009
2045
  }
2010
2046
  return next(e);
@@ -2103,6 +2139,7 @@ export function register(on, options) {
2103
2139
  loop = await reviewMidTurn($, router, cfg, loop, e, { context, nativeModel, availableModels });
2104
2140
  loop = await moveOnObserved($, router, cfg, loop, e, context);
2105
2141
  loop = continueRoute(cfg, loop, {
2142
+ hasImages: await imagesOf($, cfg, loop.decision),
2106
2143
  nativeModel,
2107
2144
  contextTokens: context.tokens,
2108
2145
  contextKnown: context.known,
@@ -232,8 +232,9 @@ export function emptyMetrics() {
232
232
 
233
233
  // Why a routed main reply was left out of the usage record (unpricedCause in savings.mjs): its usage did not read
234
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`). Kept beside the stats from 1.16; a record from before reads as none.
236
- export const UNPRICED_CAUSES = ['usage', 'model', 'ttl', 'error'];
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'];
237
238
  const emptyUnpriced = () => Object.fromEntries(UNPRICED_CAUSES.map((cause) => [cause, 0]));
238
239
 
239
240
  const isLatency = (v) =>
@@ -246,12 +247,13 @@ const isLatency = (v) =>
246
247
  export function readMetrics(value) {
247
248
  const empty = emptyMetrics();
248
249
  if (!isRecord(value) || value.version !== 1) return empty;
250
+ const unpriced = isRecord(value.unpriced) ? { comparison: 0, ...value.unpriced } : null;
249
251
  return {
250
252
  version: 1,
251
253
  since: Number.isFinite(value.since) ? value.since : null,
252
254
  latency: isLatency(value.latency) ? value.latency : empty.latency,
253
255
  downMoves: exactCountsOf(value.downMoves, ['moves', 'escalations']) ? value.downMoves : empty.downMoves,
254
- unpriced: exactCountsOf(value.unpriced, UNPRICED_CAUSES) ? value.unpriced : empty.unpriced,
256
+ unpriced: exactCountsOf(unpriced, UNPRICED_CAUSES) ? unpriced : empty.unpriced,
255
257
  };
256
258
  }
257
259
 
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;
@@ -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,
@@ -226,7 +230,18 @@ export const DEFAULTS = {
226
230
 
227
231
  // Keys a route, a model or a classifier entry may carry. The other closed sections take their key sets from DEFAULTS.
228
232
  const ROUTE_KEYS = ['model', 'effort'];
229
- 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
+ ];
230
245
  const CLASSIFIER_KEYS = ['label', 'api', 'endpoint', 'model', 'keyOption', 'timeoutMs'];
231
246
  // The wire protocols a classifier can speak. Each has an adapter in classifier-apis.mjs; a test keeps the two in step.
232
247
  export const CLASSIFIER_APIS = ['system-one', 'openai-decisions', 'ollama'];
@@ -245,12 +260,16 @@ const FORBIDDEN_KEYS = new Set(['__proto__', 'constructor', 'prototype']);
245
260
  export const MIGRATION_HINT =
246
261
  'run node scripts/migrate-config.mjs /path/to/router.json from the router plugin directory';
247
262
 
248
- 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);
249
267
  if (userFile !== null) checkShape(userFile);
250
- const merged = merge(DEFAULTS, withoutShadow(userFile ?? {}));
268
+ const merged = merge(structuredClone(defaultsFor(provider)), withoutShadow(userFile ?? {}));
251
269
  // A user entry without `api` speaks the System One protocol that every entry spoke before 1.5.
252
270
  const config = {
253
271
  ...merged,
272
+ provider,
254
273
  classifiers: Object.fromEntries(
255
274
  Object.entries(merged.classifiers).map(([id, entry]) => [id, { api: 'system-one', ...entry }]),
256
275
  ),
@@ -297,6 +316,7 @@ export function effectiveRoutes(draft, current) {
297
316
  // change of a default still reaches tiers the user never edited; a route equal to the default is removed.
298
317
  export function withRoutes(file, draft) {
299
318
  const { base } = draft;
319
+ const defaults = defaultsFor(base.provider);
300
320
  const { routes: kept = {}, baselineTier: keptBaseline, ...rest } = file;
301
321
  const routes = {};
302
322
  for (const tier of TIERS) {
@@ -306,14 +326,14 @@ export function withRoutes(file, draft) {
306
326
  continue;
307
327
  }
308
328
  const { model, effort = null } = draft.routes[tier];
309
- const preset = DEFAULTS.routes[tier];
310
- 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;
311
331
  routes[tier] = { model, effort };
312
332
  }
313
333
  const baseline =
314
334
  draft.baselineTier === base.baselineTier
315
335
  ? keptBaseline
316
- : draft.baselineTier === DEFAULTS.baselineTier
336
+ : draft.baselineTier === defaults.baselineTier
317
337
  ? undefined
318
338
  : draft.baselineTier;
319
339
  return {
@@ -362,7 +382,9 @@ export function editActivity(draft, current, activity, tier, kind, value = null)
362
382
  let cell = {
363
383
  model: () => ({ model: value, effort: config.models[value]?.efforts.includes(route.effort) ? route.effort : null }),
364
384
  effort: () => ({ model: route.model, effort: value }),
365
- add: () => ({ ...(cellOf(DEFAULTS.activities, activity, tier) ?? resolveRoute(config, tier)) }),
385
+ add: () => ({
386
+ ...(cellOf(defaultsFor(current.provider).activities, activity, tier) ?? resolveRoute(config, tier)),
387
+ }),
366
388
  remove: () => null,
367
389
  }[kind]();
368
390
  const saved = cellOf(draft.base.activities, activity, tier);
@@ -377,18 +399,19 @@ export function editActivity(draft, current, activity, tier, kind, value = null)
377
399
  // route in `file` (the merge would bring the built-in back otherwise), so call this after withRoutes.
378
400
  export function withActivities(file, draft) {
379
401
  const { base } = draft;
402
+ const defaults = defaultsFor(base.provider);
380
403
  const { activities: kept = {}, activityRouting: keptMode, ...rest } = withoutShadow(file);
381
404
  const activities = {};
382
405
  for (const activity of ACTIVITIES) {
383
406
  for (const tier of TIERS) {
384
407
  const cell = cellOf(draft.activities, activity, tier);
385
- const preset = cellOf(DEFAULTS.activities, activity, tier);
408
+ const preset = cellOf(defaults.activities, activity, tier);
386
409
  let written;
387
410
  if (!draft.activities || sameCell(cell, cellOf(base.activities, activity, tier)))
388
411
  written = cellOf(kept, activity, tier);
389
412
  else if (cell) written = sameCell(cell, preset) ? undefined : cell;
390
413
  else if (preset) {
391
- const route = { ...DEFAULTS.routes[tier], ...file.routes?.[tier] };
414
+ const route = { ...defaults.routes[tier], ...file.routes?.[tier] };
392
415
  written = { model: route.model, effort: route.effort ?? null };
393
416
  }
394
417
  if (written) activities[activity] = { ...activities[activity], [tier]: written };
@@ -397,7 +420,7 @@ export function withActivities(file, draft) {
397
420
  const mode =
398
421
  draft.activityRouting === undefined || draft.activityRouting === base.activityRouting
399
422
  ? keptMode
400
- : draft.activityRouting === DEFAULTS.activityRouting
423
+ : draft.activityRouting === defaults.activityRouting
401
424
  ? undefined
402
425
  : draft.activityRouting;
403
426
  return {
@@ -583,6 +606,15 @@ function validate(config) {
583
606
  }
584
607
  }
585
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
+ }
586
618
  if (!TIERS.includes(config.baselineTier)) throw new Error(`baselineTier must be one of ${TIERS.join(', ')}`);
587
619
  validatePolicy(config.policy, 'policy');
588
620
  if (!ROUTING_MODES.includes(config.mode)) throw new Error(`mode must be one of ${ROUTING_MODES.join(', ')}`);
@@ -590,6 +622,15 @@ function validate(config) {
590
622
  for (const mode of PATCHED_MODES)
591
623
  validatePolicy({ ...config.policy, ...config.modes[mode]?.policy }, `modes.${mode}.policy`);
592
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');
593
634
  for (const map of ['writeMultiplier', 'ttlMs']) {
594
635
  for (const [ttl, value] of Object.entries(cache[map]))
595
636
  if (!isNumber(value, 0, { above: true })) throw new Error(`cache.${map}.${ttl} must be positive`);
@@ -606,7 +647,12 @@ function validate(config) {
606
647
  throw new Error(`subagents.types.${type} must be a models key, ${CLASSIFY} or null`);
607
648
  }
608
649
  for (const field of ['light', 'standard', 'heavy']) {
609
- 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
+ )
610
656
  throw new Error(`subagents.${field} is not in models`);
611
657
  }
612
658
  if (!(isNumber(subagents.heavyMass, 0) && subagents.heavyMass <= 1))
@@ -635,6 +681,10 @@ function validatePolicy(p, at) {
635
681
  }
636
682
 
637
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`);
638
688
  for (const field of ['input', 'cacheRead', 'contextWindow']) {
639
689
  if (!Number.isFinite(model[field]) || model[field] < 0)
640
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);
package/lib/decisions.mjs CHANGED
@@ -215,7 +215,9 @@ const clock = (ms) => {
215
215
  const share = (p) => (Number.isFinite(p) ? ` ${Math.round(p * 100)}%` : '');
216
216
 
217
217
  function endLine(row) {
218
- const unpriced = Object.entries(row.unpriced ?? {}).map(([cause, k]) => `${cause} ${k}`);
218
+ const unpriced = Object.entries(row.unpriced ?? {})
219
+ .filter(([cause]) => cause !== 'comparison')
220
+ .map(([cause, k]) => `${cause} ${k}`);
219
221
  return [
220
222
  clock(row.at),
221
223
  'end ',
@@ -223,6 +225,7 @@ function endLine(row) {
223
225
  `${row.requests} request${row.requests === 1 ? '' : 's'}`,
224
226
  `${row.priced} priced`,
225
227
  unpriced.length ? `unpriced ${unpriced.join(', ')}` : null,
228
+ row.unpriced?.comparison ? `comparison unavailable ${row.unpriced.comparison}` : null,
226
229
  ]
227
230
  .filter(Boolean)
228
231
  .join(' ');