@alexeiled/claude-router 1.23.1 → 1.25.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/.claude-plugin/plugin.json +1 -1
- package/CHANGELOG.md +62 -1
- package/README.md +39 -7
- package/docs/architecture.md +27 -4
- package/docs/auto-engine.md +152 -0
- package/docs/configuration.md +47 -3
- package/docs/evaluation.md +222 -3
- package/docs/native-router.md +11 -3
- package/docs/providers.md +28 -0
- package/docs/router-band.svg +124 -133
- package/docs/router-pane-classifier.svg +24 -23
- package/docs/router-pane-now.svg +9 -7
- package/docs/router-pane-policy.svg +4 -4
- package/docs/router-pane-routes.svg +8 -8
- package/docs/router-pane-usage-whatif.svg +14 -14
- package/docs/router-pane-usage.svg +20 -20
- package/docs/routing-modes.md +13 -4
- package/docs/user-guide.md +79 -19
- package/hooks/native-router.mjs +1194 -215
- package/lib/activity-stats.mjs +23 -4
- package/lib/activity.mjs +7 -5
- package/lib/auto-engine.mjs +414 -0
- package/lib/auto-route.mjs +253 -0
- package/lib/band.mjs +35 -440
- package/lib/classifier-client.mjs +12 -8
- package/lib/config-file.mjs +7 -2
- package/lib/config.mjs +64 -15
- package/lib/cost.mjs +5 -1
- package/lib/costs.mjs +4 -2
- package/lib/decisions.mjs +80 -5
- package/lib/display.mjs +69 -20
- package/lib/facts.mjs +30 -0
- package/lib/modes.mjs +8 -4
- package/lib/panel.mjs +75 -2163
- package/lib/policy.mjs +7 -6
- package/lib/providers.mjs +7 -0
- package/lib/replay-trace.mjs +550 -0
- package/lib/replay.mjs +718 -0
- package/lib/route-line.mjs +46 -0
- package/lib/route.mjs +35 -21
- package/lib/savings.mjs +14 -3
- package/lib/subagents.mjs +41 -11
- package/lib/subcommands.mjs +60 -0
- package/lib/ui/fallback.mjs +22 -0
- package/lib/ui/graphical/band.mjs +256 -0
- package/lib/ui/graphical/charts.mjs +163 -0
- package/lib/ui/graphical/classifier.mjs +153 -0
- package/lib/ui/graphical/frame.mjs +227 -0
- package/lib/ui/graphical/kit.mjs +156 -0
- package/lib/ui/graphical/meter.mjs +25 -0
- package/lib/ui/graphical/now.mjs +353 -0
- package/lib/ui/graphical/policy.mjs +56 -0
- package/lib/ui/graphical/routes.mjs +264 -0
- package/lib/ui/graphical/squares.mjs +29 -0
- package/lib/ui/graphical/usage.mjs +376 -0
- package/lib/ui/model/band.mjs +439 -0
- package/lib/ui/model/classifier.mjs +308 -0
- package/lib/ui/model/draft.mjs +62 -0
- package/lib/ui/model/format.mjs +41 -0
- package/lib/ui/model/frame.mjs +359 -0
- package/lib/ui/model/now.mjs +390 -0
- package/lib/ui/model/policy.mjs +194 -0
- package/lib/ui/model/routes.mjs +392 -0
- package/lib/ui/model/usage-agents.mjs +311 -0
- package/lib/ui/model/usage-breakdown.mjs +237 -0
- package/lib/ui/model/usage-shared.mjs +58 -0
- package/lib/ui/model/usage.mjs +330 -0
- package/lib/ui/terminal/band.mjs +220 -0
- package/lib/ui/terminal/classifier.mjs +142 -0
- package/lib/ui/terminal/frame.mjs +169 -0
- package/lib/ui/terminal/kit.mjs +133 -0
- package/lib/ui/terminal/now.mjs +300 -0
- package/lib/ui/terminal/policy.mjs +52 -0
- package/lib/ui/terminal/routes.mjs +167 -0
- package/lib/ui/terminal/usage.mjs +363 -0
- package/lib/ui/terminal/wrap.mjs +37 -0
- package/lib/ui/tokens.mjs +106 -0
- package/lib/usage.mjs +5 -5
- package/lib/view.mjs +5 -2
- package/package.json +3 -2
- package/types/index.d.ts +15 -0
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "router",
|
|
3
3
|
"displayName": "Router",
|
|
4
|
-
"version": "1.
|
|
4
|
+
"version": "1.25.0",
|
|
5
5
|
"description": "Native model and effort routing within your provider. Anthropic, DeepSeek, z.ai, MiniMax, MiMo and Kimi defaults, custom provider profiles, classifier advice and one model per subagent.",
|
|
6
6
|
"author": {
|
|
7
7
|
"name": "Alexei Ledenev",
|
package/CHANGELOG.md
CHANGED
|
@@ -1,5 +1,66 @@
|
|
|
1
1
|
# Changelog
|
|
2
2
|
|
|
3
|
+
## 1.25.0 (2026-11-18)
|
|
4
|
+
|
|
5
|
+
### Summary
|
|
6
|
+
|
|
7
|
+
The router's band and pane are now drawn natively in the Claude desktop app, VS Code and mobile instead of as terminal text. Running subagents show in the band, a quiet route line follows each turn, `/router` completes in the prompt, and workflow agents are routed. Claude Code 2.1.321 or newer is required.
|
|
8
|
+
|
|
9
|
+
### Upgrade
|
|
10
|
+
|
|
11
|
+
1. Update Claude Code to 2.1.321 or newer before you update the router (it was 2.1.289). Older builds refuse the new pane and band: routing stays off and the band says why.
|
|
12
|
+
2. Workflow agents are now classified like `general-purpose` agents: Haiku for exploration, Opus for clearly hard tasks, Sonnet for the rest. To keep Claude Code's pick for them, set `subagents.types['workflow-subagent']` to `null` in `router.json`. A workflow `agent({ model })` call keeps the script's model.
|
|
13
|
+
3. Terminal colours follow your Claude Code theme. Tiers, models and activities keep their colours.
|
|
14
|
+
|
|
15
|
+
### Added
|
|
16
|
+
|
|
17
|
+
- **Desktop app, VS Code and mobile:** the band is one fixed row (tier meter, route, reason; readings, a **Pin next turn** dropdown and **Router**), and all five pane tabs (Now, Routes, Policy, Classifier, Usage) are laid out as cards. **Set up** and **Edit credentials** show a copyable terminal line that saves the key with `claude plugin configure … --values-stdin`, because these surfaces cannot open the plugin settings dialog.
|
|
18
|
+
- **Subagents in the band:** while subagents run, a row lists them (three, then `+N`). Pressing one opens its transcript, and `◂ main` or **← Main** returns.
|
|
19
|
+
- **Route line:** one quiet row after a turn with the model, effort and why, such as `▂▄▆█ Sonnet 5.5 · high ↓ cheaper fits code`. By default it appears only when the route moved; `/router line all` shows every turn and `/router line off` hides it. It is not restored by `--resume`.
|
|
20
|
+
- **`/router` completion:** type `/router a` and the matching words appear (`auto`, `off`, `pin <tier>`, `mode <mode>`, `activities`, `line`, `decisions`, `trace export`), then their values.
|
|
21
|
+
- **Unavailable toast:** a session that starts with routing unavailable shows the reason once, at most once a day per cause.
|
|
22
|
+
- **Undrawable pane:** a **Router** press that opens a pane the surface cannot draw says why instead of showing nothing.
|
|
23
|
+
- **Workflow agents are routed** (see Upgrade). Claude Code 2.1.321 applies a model rewrite to them; this was checked live.
|
|
24
|
+
|
|
25
|
+
### Changed
|
|
26
|
+
|
|
27
|
+
- **Terminal layout:** warnings sit in one slot under the tab row on every tab; a pending pin shows on its pin button (press again to unpin); the band's hover controls draw on its own row instead of adding a line; a tab row too wide drops its digits before it squeezes. Details are in the [user guide](docs/user-guide.md).
|
|
28
|
+
- A resumed subagent is left alone: it keeps the model and record of its first spawn.
|
|
29
|
+
- **Contributing:** CI runs Lint, Types, Unit tests and Plugin as separate jobs with annotations on the changed lines. A maintainer can request an AI review with the `ai-review` label. Biome warnings and `tsc` strict null checks now fail the check.
|
|
30
|
+
|
|
31
|
+
### Fixed
|
|
32
|
+
|
|
33
|
+
- A pin's label names what pressing it runs: the tier's configured route on `table` and `shadow` in every routing mode (the dropdown, the pending-pin chip, the Now tab and the `/router pin` completion used to show the mode's adjusted route), and the tier alone on `auto`, which picks the model when the turn runs.
|
|
34
|
+
- A subagent's start no longer takes over the main turn's goal. Claude Code 2.1.321 raises that event for subagent loops too.
|
|
35
|
+
- Two turns that end together no longer lose each other's decision rows, two view updates at session start no longer drop one another, and a later turn no longer reads its origin as `unknown`.
|
|
36
|
+
- The pane no longer writes state while it draws, and a graphical render failure reaches the debug log instead of disappearing.
|
|
37
|
+
- The Set up command quotes the plugin id.
|
|
38
|
+
|
|
39
|
+
### Thanks
|
|
40
|
+
|
|
41
|
+
Thanks to @spark2ignite for the native band and pane for the desktop app, VS Code and mobile (#92), the largest change in this release.
|
|
42
|
+
|
|
43
|
+
### Notes
|
|
44
|
+
|
|
45
|
+
- A person has not yet checked light mode, VS Code, mobile, or the Usage tab's data views on screen, and the docs show terminal pictures only.
|
|
46
|
+
|
|
47
|
+
## 1.24.0 (2026-11-17)
|
|
48
|
+
|
|
49
|
+
### Added
|
|
50
|
+
|
|
51
|
+
- Opt in to stateful main-turn routing with `routingEngine: "auto"`. The default `table` behavior is unchanged; opt-in `shadow` records proposals while the table routes. Auto evaluation and default cutover remain pending. See [configuration](docs/configuration.md#routing-engine).
|
|
52
|
+
- Per-effort capability declarations guide auto and shadow. Anthropic seeds four balanced base-route pairs: Haiku 5.5 medium 0 and high 1; Opus 5.5 medium 2 and xhigh 3. These are user-derived policy judgments, not quality calibration. Other pairs and provider presets remain unknown. A supplied map replaces the preset; changing a model ID clears inherited capability. See [providers](docs/providers.md#capability-evidence).
|
|
53
|
+
- Shadow collects bounded, text-free replay inputs. Traces exclude prompts, tool results, filesystem-path fields, classifier endpoints and credentials, but retain routing aliases and model IDs, including path-shaped IDs. `/router trace export` merges retained traces into JSON, overwriting the previous export and rolling over near 3 MiB. **Delete history** does not delete exported files. See [trace limits and privacy](docs/evaluation.md#replay-trace-recorder).
|
|
54
|
+
- Offline replay from a checkout checks table fidelity before simulating auto. Coverage and exposure gates remain unavailable or not established; costs are conditional estimates, not savings or quality evidence. The recorded benchmark smoke checks harness mechanics on installed Router 1.23.1 only, not this checkout or an engine comparison. See [evaluation](docs/evaluation.md#offline-automatic-engine-replay).
|
|
55
|
+
|
|
56
|
+
### Changed
|
|
57
|
+
|
|
58
|
+
- Equal-cost auto candidates favor the incumbent, then the lower sufficient declared capability. Estimates do not model unseen effort-dependent thinking tokens; mode margin supplies headroom. See [selection](docs/auto-engine.md#demand-target-and-move).
|
|
59
|
+
|
|
60
|
+
### Upgrade
|
|
61
|
+
|
|
62
|
+
Restart Claude Code after updating. Auto and shadow require explicit opt-in.
|
|
63
|
+
|
|
3
64
|
## 1.23.1 (2026-11-15)
|
|
4
65
|
|
|
5
66
|
### Fixed
|
|
@@ -323,7 +384,7 @@ The Now tab shows this session and today instead of the last 30 replies, a windo
|
|
|
323
384
|
|
|
324
385
|
## 1.12.0 (2026-10-13)
|
|
325
386
|
|
|
326
|
-
The Usage tab now shows any period, not only this session and the time since the last reset. See [Compare routing with
|
|
387
|
+
The Usage tab now shows any period, not only this session and the time since the last reset. See [Compare routing with no routing](docs/user-guide.md#compare-routing-with-no-routing).
|
|
327
388
|
|
|
328
389
|
### Added
|
|
329
390
|
|
package/README.md
CHANGED
|
@@ -52,7 +52,15 @@ Jev 1.14 is the default; a configured model override stays in force. [Configurat
|
|
|
52
52
|
|
|
53
53
|
The band above the prompt shows the tier, activity, model, and reason for each turn. `/router` opens a pane to pin a tier, edit the model and effort of each tier, and tune the policy. See the [user guide](docs/user-guide.md#read-the-status-band).
|
|
54
54
|
|
|
55
|
-
|
|
55
|
+
In the desktop app, VS Code and mobile, the band is one fixed row with nothing revealed on hover: a tier meter icon, the route, activity and reason on the left; the readings, a **Pin next turn** dropdown and **Router** on the right. The pane has a header, five tabs (Now, Routes, Policy, Classifier, Usage), one warnings slot and a save bar. Colours follow the app's theme. These surfaces cannot open the plugin settings dialog, so **Set up** shows a card with the command that saves the classifier's key from a terminal.
|
|
56
|
+
|
|
57
|
+
<!-- TODO: capture desktop screenshots: band, Now, Routes, Policy, Classifier, Usage, key card (dark and light) -->
|
|
58
|
+
|
|
59
|
+
In the terminal, the picture above shows the band, whose controls appear on its own row on hover; the colours follow your Claude Code theme. The pane's warnings share one slot under the tab row, and a pending pin shows on its pin button (press it again to unpin).
|
|
60
|
+
|
|
61
|
+
On every surface, a row under the band lists running subagents (press one to open its transcript; **Back** returns), `/router` completes its words as you type where the prompt box offers completions, and a quiet route line after a turn says which model ran and why (`/router line off|moves|all`; by default only when the route moved). A session that starts with routing unavailable shows one toast with the reason, at most once a day.
|
|
62
|
+
|
|
63
|
+
The router needs Claude Code 2.1.321 or newer. Savings are not measured. The pane's Usage tab estimates what routing cost against no routing (your own model on the main thread, Claude Code's pick for each subagent) for the same tokens at configured list prices, for this session, today, 7 or 30 days, this month or all; it is not a bill and does not judge answer quality. See the [evaluation](docs/evaluation.md).
|
|
56
64
|
|
|
57
65
|
## How it works
|
|
58
66
|
|
|
@@ -81,7 +89,7 @@ sequenceDiagram
|
|
|
81
89
|
Mod-->>Dev: Status band and router pane
|
|
82
90
|
```
|
|
83
91
|
|
|
84
|
-
The active classifier labels each new logical turn
|
|
92
|
+
The active classifier labels each new logical turn. With `table` or `shadow`, the router checks tier and activity routes as the task runs: a turn labelled `ops` that edits code can move up to the `code` route, and a background classifier review can move the tier or activity. With `auto`, it keeps its own demand and route state instead of using activity route-table moves. A cheaper route on the same task waits for a dwell and a checkpoint its work can show: a passed test, build or lint run, or for commands, docs and read-only work the success the router can see. A notification is treated as progress, but cannot justify a downgrade because it may belong to an older task. `/router decisions` lists why each turn ran where it did. See [Changes during a task](docs/user-guide.md#changes-during-a-task). A local policy applies vote, context, failure, and cache-cost rules before the Mod changes the next step. Claude Code owns request construction, model credentials, tools, streaming, and the API cost ledger.
|
|
85
93
|
|
|
86
94
|
With the Anthropic profile, the base routes are:
|
|
87
95
|
|
|
@@ -107,20 +115,28 @@ The Anthropic profile uses these activity defaults. Other profiles have [their o
|
|
|
107
115
|
|
|
108
116
|
`/router activities off` stops asking and keeps the base routes. [Activity routing](docs/activity-routing.md) explains each cell and how to change it. The label is optional: on `uncertain` or a weak label the base route is used if the move passes the cache check, when the activity answer fails the running activity stays and the tier answer still applies, and when the classifier fails the running route stays. See [Route by activity](docs/user-guide.md#route-by-activity), and [Evaluation](docs/evaluation.md#activity-routing) for how it is checked. Its default overrides rest on published vendor results and a list-price replay of one developer's sessions, not measured savings.
|
|
109
117
|
|
|
110
|
-
|
|
118
|
+
## Choose a routing engine
|
|
119
|
+
|
|
120
|
+
Set `routingEngine` in the selected profile file: `table` (default), `shadow` or `auto`. For example, use `{"routingEngine":"shadow"}` or `{"routingEngine":"auto"}`; omit it for `table`. `/router auto` turns routing on for the session; it does not select the engine. `/router off` turns it off, while `/router mode cost|balanced|quality` selects the routing mode.
|
|
121
|
+
|
|
122
|
+
- **`table` (default):** uses deterministic tier-by-activity routes. The routing mode transforms those routes before the table policy.
|
|
123
|
+
- **`shadow`:** table requests remain unchanged. `/router decisions` shows one-step `alt` proposals. `/router trace export` writes bounded replay inputs; for the work profile (`CLAUDE_CONFIG_DIR=~/.claude-team`), from a source checkout, replay `~/.claude-team/router-traces.json` and any dated rollover files with `node scripts/replay-traces.mjs`.
|
|
124
|
+
- **`auto`:** selects a model and effort from declared per-effort capabilities, classifier demand, mode margins and hard/cache constraints. Configure a classifier credential when its provider requires a key; Ollama needs none. Without classifier advice, demand cannot be updated, but a qualifying startup move may still occur. Capability declarations determine whether candidate adequacy is known. Evaluation and cutover remain pending.
|
|
125
|
+
|
|
126
|
+
See [routing engines](docs/configuration.md#routing-engine) for startup, fallback and pin behavior, and [routing modes](docs/routing-modes.md) for mode effects.
|
|
111
127
|
|
|
112
128
|
For mixed Anthropic and DeepSeek sessions, use the explicit [model-proxy profile](docs/providers.md#mix-anthropic-and-deepseek-with-model-proxy) with a separately started local proxy. No built-in mixed-provider defaults are installed.
|
|
113
129
|
|
|
114
130
|
## Install
|
|
115
131
|
|
|
116
|
-
You need Claude Code 2.1.
|
|
132
|
+
You need Claude Code 2.1.321 or newer and credentials for one [supported classifier](#supported-classifiers).
|
|
117
133
|
|
|
118
134
|
```sh
|
|
119
135
|
claude plugin marketplace add alexei-led/claude-router
|
|
120
136
|
claude plugin install router@alexei-led-claude-router
|
|
121
137
|
```
|
|
122
138
|
|
|
123
|
-
For the default Anthropic profile, start on
|
|
139
|
+
For the default Anthropic profile, start on a catalog model such as `claude --model claude-haiku-5-5`. For other providers, [select a provider profile](docs/providers.md#select-a-provider). Run `/plugin configure router` and save credentials for the active classifier, or run `ollama serve` with a pulled local model and select Ollama. With `table` or `shadow`, a new session starts with routing on only when its model is used by a tier or enabled activity override. With `auto`, any model in the selected catalog starts with routing on. `/router auto` turns routing on for the selected engine; see [engine selection](docs/configuration.md#routing-engine).
|
|
124
140
|
|
|
125
141
|
Claude Code updates the plugin at startup when auto-update is on for this marketplace. Otherwise run `claude plugin marketplace update alexei-led-claude-router`, then `claude plugin update router@alexei-led-claude-router`.
|
|
126
142
|
|
|
@@ -136,7 +152,7 @@ claude --plugin-dir "$PWD" --model claude-haiku-5-5
|
|
|
136
152
|
|
|
137
153
|
In Claude Code, run `/plugin configure router` and save your classifier key in the sensitive plugin option. The Mod adds its status band and `/router` pane. No status-line setup or gateway environment variables are needed.
|
|
138
154
|
|
|
139
|
-
Run `/router` to open the pane
|
|
155
|
+
Run `/router` to open the pane. `/router auto` turns routing on for the session; `/router off` turns it off, and `/router mode cost|balanced|quality` selects the routing mode. None changes `routingEngine`, which stays in the selected profile file. Run `/model` to select a model (which turns routing off). See the [user guide](docs/user-guide.md).
|
|
140
156
|
|
|
141
157
|
Before a push, run the same checks as CI. `npm run setup` installs Biome and TypeScript into `tools/`; the plugin root keeps no lockfile, so Claude Code installs nothing with the plugin. `npm run validate` and `npm run test:plugin` need the `claude` CLI: they load the Mod in the Claude Code engine, which refuses some faults that lint and unit tests miss.
|
|
142
158
|
|
|
@@ -145,6 +161,22 @@ npm run setup
|
|
|
145
161
|
npm run check && npm run typecheck && npm test && npm run validate && npm run test:plugin
|
|
146
162
|
```
|
|
147
163
|
|
|
164
|
+
## Contributing
|
|
165
|
+
|
|
166
|
+
Pull requests from forks run CI automatically (a maintainer may have to approve the first run). Each check is its own job, and failures show as annotations on the changed lines: `Lint (biome)`, `Types (tsc)`, `Unit tests (node --test)`, and `Plugin (validate and engine tests)`. Run them locally before pushing:
|
|
167
|
+
|
|
168
|
+
```sh
|
|
169
|
+
npm run setup
|
|
170
|
+
npm run check && npm run typecheck && npm test && npm run validate && npm run test:plugin
|
|
171
|
+
```
|
|
172
|
+
|
|
173
|
+
`npm test` runs the unit tests; CI runs the same files as `npm run test:ci`, which adds a reporter that annotates failures on the changed lines. `npm run format` fixes biome formatting. A maintainer can request an AI review by adding the `ai-review` label.
|
|
174
|
+
|
|
175
|
+
### Code quality
|
|
176
|
+
|
|
177
|
+
- `npm run check` is Biome with `--error-on-warnings`, so a warning fails like an error. Besides the recommended rules it catches unawaited or misused promises, an `await` on a non-promise, an incomplete `switch` over a union, unused imports and variables, import cycles, throws of non-Error values, a lost `cause` when an error is rethrown, shadowed bindings, conditions the types prove constant, and read-modify-write updates split by an `await` (`useAtomicUpdates`). Use `biome-ignore` only with a one-line reason for code that is deliberate.
|
|
178
|
+
- `npm run typecheck` is `tsc` over `lib` and `hooks` with `strictNullChecks`, `noUncheckedIndexedAccess`, `useUnknownInCatchVariables`, `strictFunctionTypes`, `noImplicitReturns`, `noFallthroughCasesInSwitch`, `noUnusedLocals`/`noUnusedParameters`, `verbatimModuleSyntax` and `erasableSyntaxOnly`.
|
|
179
|
+
|
|
148
180
|
## Documentation
|
|
149
181
|
|
|
150
182
|
- [User guide](docs/user-guide.md): install, use the controls, read the panel, and troubleshoot.
|
|
@@ -154,5 +186,5 @@ npm run check && npm run typecheck && npm test && npm run validate && npm run te
|
|
|
154
186
|
- [Activity routing](docs/activity-routing.md): the default matrix by activity, why each cell, and how to change or turn it off.
|
|
155
187
|
- [Routing modes](docs/routing-modes.md): `cost`, `balanced` and `quality`, where the mode comes from, and every decision per mode.
|
|
156
188
|
- [Native router details](docs/native-router.md): panel semantics, tuning, and accepted limits.
|
|
157
|
-
- [Evaluation](docs/evaluation.md):
|
|
189
|
+
- [Evaluation](docs/evaluation.md): limits, text-free trace export and replay, and the paired benchmark proposal.
|
|
158
190
|
- [Changelog](CHANGELOG.md): user-visible changes by version.
|
package/docs/architecture.md
CHANGED
|
@@ -64,14 +64,37 @@ Claude Code builds each request for the model the Mod selects, so no request rew
|
|
|
64
64
|
| [Prices](../lib/prices.mjs) | Built-in list prices with each vendor's page and check date; rewritten by `scripts/check-prices.mjs`. |
|
|
65
65
|
| [Router view](../lib/view.mjs) | The view's initial shape and the usage readings each reply adds to it. |
|
|
66
66
|
| [Config file](../lib/config-file.mjs) | Pane writes to `router.json`: the validated rewrite and what Undo restores. |
|
|
67
|
-
| [Panel](../lib/panel.mjs) |
|
|
68
|
-
| [Router band](../lib/band.mjs) |
|
|
67
|
+
| [Panel](../lib/panel.mjs) | The tab table (id, hotkey, label, model, renderers) and `renderPanel`, which draws the pane for the surface. |
|
|
68
|
+
| [Router band](../lib/band.mjs) | `renderBand` and `renderRouteLine`, which draw the band and the route line for the surface, and route-change toasts. |
|
|
69
|
+
| [UI](../lib/ui/) | What the band and the pane show: models (plain data), one renderer per surface kind, and every colour. See [UI layout](#ui-layout). |
|
|
69
70
|
| Claude Code | API requests, tools, authentication, stream output, and usage ledger. |
|
|
70
71
|
|
|
71
72
|
Every function that takes the engine interface `$` lives in the hooks module: the engine does not follow `$` across an import, so the modules in `lib/` stay pure.
|
|
72
73
|
|
|
73
74
|
Node.js is not part of routing. It is used for development, the optional configuration migration, and the classifier probe.
|
|
74
75
|
|
|
76
|
+
## UI layout
|
|
77
|
+
|
|
78
|
+
The band, the pane and the route line are built in three steps: the router state becomes a model, a renderer turns the model into elements, and the host draws them. All of it is under `lib/ui/`, with two entry points, `renderPanel` in `lib/panel.mjs` and `renderBand` (and `renderRouteLine`) in `lib/band.mjs`.
|
|
79
|
+
|
|
80
|
+
```
|
|
81
|
+
lib/ui/tokens.mjs every colour, by tone, and the surface helpers (isGraphical, toneColor)
|
|
82
|
+
lib/ui/fallback.mjs orTerminal: the terminal tree when a graphical renderer throws
|
|
83
|
+
lib/ui/model/ plain data, no elements and no widths: now, routes, policy, classifier, usage (with
|
|
84
|
+
usage-breakdown, usage-agents, usage-shared), frame (notices, save bar, help, key help),
|
|
85
|
+
draft (the Routes and Policy draft), band (segments, fitting, agent rows), format
|
|
86
|
+
lib/ui/terminal/ kit.mjs, frame.mjs, band.mjs, wrap.mjs and one renderer per tab
|
|
87
|
+
lib/ui/graphical/ kit.mjs, frame.mjs, band.mjs, charts.mjs, meter.mjs, squares.mjs and one renderer per tab
|
|
88
|
+
```
|
|
89
|
+
|
|
90
|
+
**Surface dispatch.** Every `ui.render` event carries `e.surface`, which the hook passes on. `terminal`, or no surface, picks the terminal tree. `desktop`, `vscode` and `mobile` pick the graphical tree, which is one tree for all three. If a graphical renderer throws and the caller passed `onFallback`, `orTerminal` hands it the error and draws the terminal tree; the hook's callback writes the error to the debug log. Without `onFallback` the throw propagates, so a test sees a broken renderer instead of the terminal tree standing in for it. The terminal's own throw is never caught.
|
|
91
|
+
|
|
92
|
+
**Data flow.** `renderPanel` builds a context from the config, the stored view, the usage readings and `e.surface`. The selected tab's `modelOf` turns it into a model in which every condition, word and number format is already decided; where the words differ by surface the model holds a `{ terminal, graphical }` pair. The renderer only lays the model out with its kit. A tab renderer never reads `view` or the config; if it needs a fact, the model carries it. The frame (header, tabs, notices slot, save bar) has its own model, `frameOf`, and its own renderer per surface kind. The band follows the same idea with less separation: `lib/ui/model/band.mjs` returns segments of parts with a priority (`bandSegments`, `sessionSegments`, `agentSegments`, `routeLineSegments`), and `fitSegments` drops them by priority to fit `columns`. The terminal band draws the segments, adds the hover controls as absolutely placed Boxes, and still takes `config` and `view` for those controls; the graphical band splits the segments into a left group that shrinks and a right group that never does. A graphical band never adds anything on hover.
|
|
93
|
+
|
|
94
|
+
**State.** `lib/ui/` keeps no module state. A function takes the elements it draws with (`$.ui.resolve(e)` in the hook), the model, and the actions it binds to a `Button` or `Select`; the hook owns the view, the config and every host call.
|
|
95
|
+
|
|
96
|
+
**Colour.** `lib/ui/tokens.mjs` is the one place a colour is written. A model names a tone (`primary`, `muted`, `accent`, `success`, `warning`, `danger`, `activity`, `tier:<tier>` or `model:<family>`); the kit turns it into a colour with `toneColor(tone, surface)`. The terminal and the graphical surfaces draw the six theme tones as Claude Code theme keys (`text`, `subtle`, `suggestion`, `success`, `warning`, `error`), so the person's theme, light or dark, decides them. Tiers, model families and the activity have no theme key and are hexes, with a mid-lightness set on a graphical surface so each reads on a white and a dark ground. An `Svg` cannot take a theme key, so its colours are hexes from the same file (`svgColor`). A renderer that wrote its own colour would escape the theme and the contrast checks in `test/ui-tokens.test.mjs`.
|
|
97
|
+
|
|
75
98
|
## Decision and context
|
|
76
99
|
|
|
77
100
|
A logical turn is classified at its first step, and again every `reviewEveryRequests` requests in the background (see Review inside a turn below). Other tool continuations reuse the decision and add no votes. Before each step, the controller checks whether the selected model still fits after new tool output.
|
|
@@ -174,10 +197,10 @@ prune unreadable newer records.
|
|
|
174
197
|
A subagent's model is chosen once, in the `agent.spawn` hook, before its cache exists. Its `turn.step` events pass through unchanged: a subagent runs on the 5-minute cache lifetime by default, and a switch between its steps would rewrite a 50,000–300,000-token context cold. The facts below are from the Claude Code 2.1.296 types (`AgentSpawnInput`, `HookBudget`) and a probe Mod's observed events, `experiments/mod-router/results/agent-spawn-probe.json`. The [plan](plans/2026-10-10-subagent-routing-plan.md#2-verified-facts) cites each one.
|
|
175
198
|
|
|
176
199
|
- A model the hook sets beats the agent's `model:` frontmatter and `CLAUDE_CODE_SUBAGENT_MODEL`. Frontmatter is not in the spawn input. The Agent call's own `model` is, as `e.model`.
|
|
177
|
-
- Workflow `agent()` calls raise `agent.spawn` with `e.workflow`,
|
|
200
|
+
- Workflow `agent()` calls raise `agent.spawn` with `e.workflow`, and a model rewrite there applies (2.1.321, checked live). A resumed subagent raises it with `e.resume`; a hook can only refuse that, so `spawnAgent` returns `next(e)` at once.
|
|
178
201
|
- The hook has 10 seconds of its own time. `$` calls do not count against it, but a `$.clock.sleep` does.
|
|
179
202
|
|
|
180
|
-
`spawnAgent` in `hooks/native-router.mjs` passes the spawn through unchanged for a fork, a workflow agent (before the explicit
|
|
203
|
+
`spawnAgent` in `hooks/native-router.mjs` passes the spawn through unchanged for a resume, a fork, a workflow agent that sets its own model (checked before the explicit test, since a workflow `agent({ model })` has `e.model` set) or whose `workflow-subagent` entry in `subagents.types` is `null`, which is routed by default, an explicit `e.model`, or a teammate (`passReason` in `lib/subagents.mjs`). Then `typeRoute` decides. A `subagents.types` entry wins; a key without a colon matches only the engine's built-in of that name. An unlisted built-in passes (`unlisted`), since its definition is not on disk. Any other agent is routed by its definition. `agentDefinition` finds the file once per provider and type in a session; a read that fails is tried again at the next spawn of the type. A plugin agent's `provider.plugin` is `plugin@marketplace`, the key of `<profile>/plugins/installed_plugins.json`, whose `installPath` entries hold `agents/*.md`. Other agents are looked up under the session's `.claude/agents`, then `<profile>/agents`. `agentFrontmatter` reads `name`, `model` and `modelRouting` from YAML or a one-line JSON object. No model, `inherit`, or `modelRouting: auto` is routed; any other model passes (`pinned`); a file not found, unreadable, or matches that disagree pass (`unknown`). A routed agent's type uses its models key, or for `classify` the active classifier is asked with the description and prompt alone, clipped to `context.maxTextChars`, with no history and no tool results. The answer maps to `subagents.heavy` when `P(high) ≥ heavyMass`, to `light` for an `explore` activity above `activityMass` or tier `micro`, else to `standard`. The spawn path has its own classifier client per classifier: its own failure count and pause, and no in-flight slot, so parallel spawns each get an answer and spawn failures never pause main-turn routing. Its deadline is the classifier's, capped at 3 seconds. That bounds how long a subagent waits to start. No advice, a missing key, a model `availableModels` blocks, or settings that cannot be read keep core's model. The router sends the configured full id, never an alias, because a family alias resolves to the parent's exact model when the families match. A `.catch` runs `next(e)`, so a failing hook spawns the agent as Claude Code would. Routing off (`/router off`, `/model`) or unavailable passes every spawn through and records nothing.
|
|
181
204
|
|
|
182
205
|
Every spawn in `on` gets a record keyed by `agentId`, from `next(e)`'s answer. Its replies are priced in `turn.step` (`addAgentReply`), on the model they ran on and on core's model as `coreModelOf` estimates it (the definition's own model, else `CLAUDE_CODE_SUBAGENT_MODEL` except for Explore and Plan without `CLAUDE_CODE_SUBAGENT_MODEL_FORCE`, else `parentModel`). Cache writes are priced at the subagent lifetime (`subagentCacheTtl`). The spawn record also keeps `move` (`moveOf`): `up` or `down` when the routed model's declared strength rank is above or below core's, `moved` when either rank is unknown or both are equal, null for the same model. The record's counts go to this session's `$.store` key `subagents:v1:<session id>` at each of the agent's `turn.complete`s, and at session end for agents still running. Since 1.14.0 the value is version 2, by local calendar day like the usage records, and days past 400 leave it when it is written: per day, per type and per pass-through reason, the agents, requests, priced requests, respawns (a spawn of the type its parent loop finished one of in the last 10 minutes) and classifier failures, and per model id the agents ran on, the agents, the agents moved, up and down, the routed cost and core's. An agent counts on the day of its first flush; its later requests and cost on the day of each flush. A version 1 value has no days or models: it reads as `undated` agents and cost, which only the Session and All periods add. The records follow the usage records: one writer per key, the view's `subagentStore` is every session's sum and `subagentSession` this session's, and the same reset marker applies. **Delete history** clears them too. The view's `subagentsRunning` counts the agents with a record between a spawn or a step and their turn's end; it is in memory, so a reload starts it over. The band in a subagent's transcript reads the agent's record from memory too.
|
|
183
206
|
|
|
@@ -0,0 +1,152 @@
|
|
|
1
|
+
# Pure automatic routing engine
|
|
2
|
+
|
|
3
|
+
`lib/auto-engine.mjs` implements the [automatic routing design](plans/2026-11-16-auto-routing-design.md).
|
|
4
|
+
It has no I/O. Opt-in `routingEngine: "auto"` uses the stateful adapter `lib/auto-route.mjs` in the main-turn hook; the default table engine is unchanged. Shadow remains a one-step proposal and offline replay has its own state. Evaluation and default cutover remain pending.
|
|
5
|
+
|
|
6
|
+
## Inputs
|
|
7
|
+
|
|
8
|
+
All functions take one object. Pass the original validated config, including its catalog, cache settings and
|
|
9
|
+
base `policy`. Do not pass `applyMode(config, mode)`: per-mode policy patches belong to the table engine only.
|
|
10
|
+
The automatic mode changes only the capability requirement.
|
|
11
|
+
|
|
12
|
+
A route is `{ model: alias, effort: string | number | null }`. Generated candidates use only supported strings,
|
|
13
|
+
or `null` for a model with `efforts: []`. A real native incumbent with an unresolved null or finite numeric effort
|
|
14
|
+
is valid but has unknown capability. An unsupported explicit string is not silently clamped.
|
|
15
|
+
Capability comes only from `models[alias].capability[effort]`, or `capability.default` on a no-effort model.
|
|
16
|
+
No declaration means unknown, not zero. Anthropic includes user-derived balanced base-route policy seeds, not
|
|
17
|
+
measured quality; all other pairs remain unknown. Users can replace them as described in
|
|
18
|
+
[Providers](providers.md#capability-evidence).
|
|
19
|
+
|
|
20
|
+
The facts object uses the existing controller shapes:
|
|
21
|
+
|
|
22
|
+
- `contextTokens`, `historyMeasured`, `hasImages`;
|
|
23
|
+
- `models`: cache key → `{ prefixTokens, lastAt, ... }`;
|
|
24
|
+
- `effort`: native session effort, and `lastRequest: { tokens, outputTokens, ... }`;
|
|
25
|
+
- `ineligible`: model IDs excluded for this history;
|
|
26
|
+
- `dwellAllowed`: a separate boolean for physical downgrades, required even on a new task. Set it to
|
|
27
|
+
`requests - switchedAt.requests >= config.policy.minDwellRequests`, using the actual route's last switch and
|
|
28
|
+
request counter. At session start, before any request/switch exists, set it to true. Missing means false.
|
|
29
|
+
- `downAllowed`: the existing combined dwell/checkpoint fact, required in addition to `dwellAllowed` only on the
|
|
30
|
+
same task; `midTurn`, `progress` and advice continuation identify that task. Off the same task no checkpoint
|
|
31
|
+
is required. Upgrades, forced refits, escalation and explicit stronger mode/catalog moves bypass dwell.
|
|
32
|
+
- `failure: { signature, index }` or null. The same signature at a new index is a new occurrence.
|
|
33
|
+
Re-reading the same occurrence does not escalate again. History reset must reset engine state.
|
|
34
|
+
|
|
35
|
+
Advice uses the existing `{ choice, probabilities, continuation, ... }` classifier shape, or null.
|
|
36
|
+
`now` is the caller's timestamp in milliseconds. `availableModels` and `nativeModel` use the existing
|
|
37
|
+
`isModelAllowed` semantics. Pass the active provider's cache configuration, including effort-cache separation.
|
|
38
|
+
If the host has resolved a configured model ID to a response ID, project those IDs into the supplied catalog
|
|
39
|
+
before assessing cache state, as the table controller's economic config does.
|
|
40
|
+
|
|
41
|
+
## Demand, target and move
|
|
42
|
+
|
|
43
|
+
| Export | Input | Output |
|
|
44
|
+
| ----------------------- | ---------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------- |
|
|
45
|
+
| `initialAutoState` | `{ demand = 2, routedDemand = demand, cause = 'classifier' }` | Initial state |
|
|
46
|
+
| `initialIncumbentState` | `{ config, incumbent, facts }` | Baseline demand with actual known incumbent capability as routed demand |
|
|
47
|
+
| `advanceDemand` | `{ config, state, advice = null, facts, pin = null, boundedExecute = false }` | `{ raw, level, reason, headroom, escalated, state }` |
|
|
48
|
+
| `assessCandidates` | `{ config, facts, now, incumbent, contextKnown = Number.isFinite(facts.contextTokens), availableModels, nativeModel }` | Candidate facts array |
|
|
49
|
+
| `selectTarget` | `{ candidates, demand, mode = 'balanced', headroom = false, escalation = false }` | `{ outcome, route, capability, requirement, estimate, reason, headroom }` |
|
|
50
|
+
| `decideMove` | `{ config, state, demandResult, target, candidates, advice = null, facts, now, changeCause = null, startup = false }` | `{ move, route, reason, evidence, estimate, state }` |
|
|
51
|
+
| `proposeAutoRoute` | Combined inputs above, using `incumbent` and optional `state` | `{ demand, candidates, target, move, state }` |
|
|
52
|
+
|
|
53
|
+
The facade initializes missing state with `initialIncumbentState`. Raw demand starts at `config.baselineTier`;
|
|
54
|
+
routed demand starts at the actual incumbent's declared capability for its supported/resolved native effort.
|
|
55
|
+
Unknown capability, an unlisted model, or unresolved/unsupported effort conservatively keeps baseline routed
|
|
56
|
+
demand; it is never inferred from a route table, mode offset or a guessed effort. Runtime and replay use the
|
|
57
|
+
same initializer. `initialAutoState` remains available for callers supplying explicit state.
|
|
58
|
+
State includes integer `demand`, `turn`, `votes`, `holdUntilTurn`, `escalatedSignature`, `escalatedIndex`,
|
|
59
|
+
`headroom`, `demandCause`, `routedDemand` and `routeCause`.
|
|
60
|
+
`raw` is integer demand; `level` is effective demand after the noncumulative half-step bounded-execute discount.
|
|
61
|
+
The caller supplies `boundedExecute: true` only for an already accepted bounded execute/ops phase, never
|
|
62
|
+
for a goal label alone or verify/report phases. An escalation hold protects the raised demand.
|
|
63
|
+
|
|
64
|
+
Each candidate has `route`, `requestKey` (canonical physical identity), `capability` (number or null), `eligible`, `reasons`, `incumbent`, `selectable`,
|
|
65
|
+
`cache`, `coldWriteUsd` and `estimate`. The incumbent is assessed even if it left the catalog.
|
|
66
|
+
A native unresolved effort is included in normal target comparison so it wins equal estimates, but cannot be
|
|
67
|
+
nominated as a new non-incumbent route. Declared-below-demand candidates still precede an unknown incumbent.
|
|
68
|
+
On a no-effort model, numeric native effort and the generated null-effort candidate have the same request key.
|
|
69
|
+
|
|
70
|
+
All availability, context, image, effort and cold-write cash constraints run before fallback.
|
|
71
|
+
An invalid incumbent and no eligible candidate produce explicit `no-route`, never an invented native route.
|
|
72
|
+
Target outcomes are `meets-demand`, `declared-below-demand`, `unknown-only`, `incumbent` and `no-route`.
|
|
73
|
+
|
|
74
|
+
Estimates are absolute next-turn `{ minUsd, maxUsd }` ranges: `cost.inputBounds` plus the last reply's output
|
|
75
|
+
length at `cost.ratesAt` prices. This estimate is effort-blind; it does not model additional thinking tokens.
|
|
76
|
+
Selection uses the conservative `maxUsd` bound, then the incumbent, lower sufficient declared capability and
|
|
77
|
+
config order. The mode margin supplies headroom through the requirement, not a tie preference. Automatic prefix
|
|
78
|
+
caches have no assumed TTL or warm-cache exemption.
|
|
79
|
+
Switch gates use the existing route-to-route `switchingTaxUsd` and `downgradeTaxUsd` math.
|
|
80
|
+
These are conditional estimates, not expected costs or measured savings.
|
|
81
|
+
|
|
82
|
+
## State ownership
|
|
83
|
+
|
|
84
|
+
Shadow needs only `advanceDemand → assessCandidates → selectTarget`. Retain the returned demand state and
|
|
85
|
+
always assess the real incumbent/cache; do not retain a hypothetical target as route history.
|
|
86
|
+
Pass `escalation: demand.escalated` and `headroom: demand.headroom` to `selectTarget`. After either escalation or
|
|
87
|
+
pending-headroom selection, copy `target.headroom` back to the returned demand state's `headroom` field.
|
|
88
|
+
It is true only on exhausted escalation, permitting retry if a stronger candidate becomes eligible.
|
|
89
|
+
Target reasons are null, `escalation`, `escalation-unknown` (unknown capability) and `escalation-exhausted`.
|
|
90
|
+
A declared stronger eligible request precedes unknown alternatives; neither search can return the same physical
|
|
91
|
+
request via another alias. The facade performs this headroom feedback automatically.
|
|
92
|
+
|
|
93
|
+
Stateful replay/auto compares effective demand with `state.routedDemand`, not the previous turn's demand.
|
|
94
|
+
A physical move updates routed demand and route cause. A `same-route` selection instead accepts the current
|
|
95
|
+
effective demand (including zero) as routed demand without a switch: `move: false`, route cause, hold, votes
|
|
96
|
+
and failure markers remain unchanged. Canonically identical physical requests under different aliases count
|
|
97
|
+
as same-route. Pins, no-route, exhausted escalation and blocked moves do not adopt demand.
|
|
98
|
+
The facade returns accepted state in `result.state` and `result.move.state`; its demand-only state remains in
|
|
99
|
+
`result.demand.state`. A held proposal leaves routed demand and cause unchanged, so it remains pending.
|
|
100
|
+
Runtime and offline replay use the same `decideMove` transition.
|
|
101
|
+
`changeCause` is null, `mode` or `catalog`; it cannot relabel a demand change as an explicit configuration move.
|
|
102
|
+
The separate `startup` input defaults to false and must come from genuine per-history routing evidence,
|
|
103
|
+
never `state.turn === 0` or the physical request count. A first tier pin consumes eligibility even though its
|
|
104
|
+
demand state remains unchanged. Manual/off native requests do not consume it; their cache and dwell observations
|
|
105
|
+
still count normally. The loop persists `hasRoutedDecision` with the same state write as the routed decision,
|
|
106
|
+
including table decisions and pins. Reload, off/on, engine changes and compaction preserve it; a new session or
|
|
107
|
+
`/clear` new history starts false. Legacy unmarked histories with request, decision or auto-state evidence
|
|
108
|
+
conservatively count as consumed. This adds no configuration flag or state version.
|
|
109
|
+
Startup qualification uses the selector's existing `target.requirement`: effective demand after any accepted
|
|
110
|
+
bounded-execute discount plus the mode margin. It does not cancel that discount or invent an undiscounted floor.
|
|
111
|
+
Only a declared known incumbent below that requirement and a declared target meeting it can qualify; unknown
|
|
112
|
+
capability never grants startup evidence. After unchanged demand voting, qualifying startup movement takes
|
|
113
|
+
priority over classifier upgrade/downgrade movement and uses mass 1 through the same base-policy explicit-up
|
|
114
|
+
switch-tax gate. All candidate hard constraints and the cash cap still apply; this is not a forced move.
|
|
115
|
+
A blocked first decision consumes the chance, so there is no second-turn startup retry. For example, native
|
|
116
|
+
capability 0, baseline 1 and first low probability 0.57 can move with startup mass 1; the same probability on an
|
|
117
|
+
ordinary later demand upgrade still needs the unchanged classifier mass gate. Fresh micro advice that reduces
|
|
118
|
+
effective demand to 0 does not authorize startup when capability 0 already meets the resulting requirement.
|
|
119
|
+
Startup move reason and route cause are `startup`, not `mode`. Replay compares accepted automatic mode/catalog
|
|
120
|
+
evidence rather than treating table-only pin config snapshots as catalog edits; genuine edits survive pins.
|
|
121
|
+
The live adapter and replay fingerprint the actual allowed configured aliases, including native `default` resolution.
|
|
122
|
+
An allowlist expansion is catalog evidence; reordering it, cache warmth and routine response-ID resolution are not.
|
|
123
|
+
|
|
124
|
+
Tier pins accept a tier string or integer 0..3. They are one-turn overrides: no mode margin and no move gates,
|
|
125
|
+
but normal candidate constraints, outcome precedence and incumbent ties. The facade returns the pinned route
|
|
126
|
+
with `move: false`, reason `pinned` and unchanged state. The caller resumes the pre-pin incumbent and state on
|
|
127
|
+
the next unpinned turn. With the lower-level API, pass `mode: 'balanced'` to `selectTarget` for a pinned demand.
|
|
128
|
+
Exact model/effort pins remain the controller's separate responsibility.
|
|
129
|
+
|
|
130
|
+
An observed native fallback records `incumbentOrigin: 'external-fallback'` and rebases the physical incumbent without
|
|
131
|
+
resetting demand, votes, hold or routed demand. Substituted effort remains unknown. The current turn stays native;
|
|
132
|
+
on the next turn, `decideMove` takes `incumbentOrigin` and permits `reentry` to a different eligible target without
|
|
133
|
+
mass, dwell or payback gates. Hard constraints and the cash cap still apply. Re-entry sets routed demand and cause
|
|
134
|
+
`reentry`, retaining the escalation hold; an equal physical target accepts current effective demand and clears
|
|
135
|
+
origin without changing route cause or counting a switch. Pinned fallbacks retain normal state and
|
|
136
|
+
apply the physical fallback provenance after restoring the pin. Replay counts external requests separately.
|
|
137
|
+
|
|
138
|
+
## Reloads
|
|
139
|
+
|
|
140
|
+
Before routing after a Mod reload without `session.start`, the hook lazily loads and validates the selected
|
|
141
|
+
provider profile and project mode. Constructor defaults never choose a main-turn route. A failed load marks
|
|
142
|
+
routing unavailable and passes the native request unchanged, without resetting persisted auto state to table.
|
|
143
|
+
A real repeated `session.start` invalidates old turn-config and classifier/review jobs before using the reloaded
|
|
144
|
+
profile. Compatible persisted automatic state survives; an actual engine change resets incompatible engine state.
|
|
145
|
+
Lazy profile loading is not a fresh-session signal: shadow recording remains explicitly incomplete mid-session.
|
|
146
|
+
|
|
147
|
+
## Checks
|
|
148
|
+
|
|
149
|
+
Run `node --test test/auto-engine.test.mjs` for the design's §5.4 invariants and §3.3 move-evidence cases.
|
|
150
|
+
The tests also cover failure occurrence deduplication, raw/effective demand, pins, native efforts, cache semantics,
|
|
151
|
+
range/cash/context boundaries and a capability-monotonicity matrix across sparse catalogs and differing prices.
|
|
152
|
+
No paid API calls or classifier calls are needed.
|
package/docs/configuration.md
CHANGED
|
@@ -6,7 +6,7 @@ Select a [provider profile](providers.md), then configure the key of the classif
|
|
|
6
6
|
|
|
7
7
|
| Item | Where it lives | How to change it |
|
|
8
8
|
| ---------------------------------- | ----------------------------------------------- | ----------------------------------------------------------------------------------------------- |
|
|
9
|
-
| Jev API key | Sensitive plugin option `typesafe_api_key` | Run `/plugin configure router`, or use **Set up** or **Credentials → Edit** in the router pane. |
|
|
9
|
+
| Jev API key | Sensitive plugin option `typesafe_api_key` | Run `/plugin configure router`, or use **Set up** or **Credentials → Edit** in the router pane (on the desktop app, VS Code and mobile they show the command to run in a terminal). |
|
|
10
10
|
| Cloudflare API token | Sensitive plugin option `cloudflare_api_token` | The same dialog. Used by Clef, Clef Flash and Clef Omni. |
|
|
11
11
|
| Cloudflare account ID | Plugin option `cloudflare_account_id` | The same dialog, or the config menu row. Not a secret. |
|
|
12
12
|
| OpenAI API key | Sensitive plugin option `openai_api_key` | The same dialog. Used only by the OpenAI classifier. Ollama needs no key. |
|
|
@@ -37,6 +37,25 @@ See [Providers](providers.md) for selection examples, built-in defaults and comp
|
|
|
37
37
|
The same schema applies to every router file. This reference uses `router.json` as shorthand for the selected file.
|
|
38
38
|
A non-Anthropic file must exist and validate. It never falls back to `router.json` or inherits settings from it.
|
|
39
39
|
|
|
40
|
+
### Model capability declarations
|
|
41
|
+
|
|
42
|
+
`models.<alias>.capability` is an optional map of supported efforts to adequacy levels: 0 (micro),
|
|
43
|
+
1 (low), 2 (medium), or 3 (high), with half-steps allowed. For example:
|
|
44
|
+
|
|
45
|
+
```json
|
|
46
|
+
{ "models": { "sonnet": { "capability": { "medium": 1.5, "high": 2 } } } }
|
|
47
|
+
```
|
|
48
|
+
|
|
49
|
+
These example values illustrate the shape, not measured model performance. Anthropic has user-derived built-in
|
|
50
|
+
policy seeds; see [Providers](providers.md#capability-evidence). Users may replace or clear them. Missing maps and entries are
|
|
51
|
+
unknown, not 0. For a model with `efforts: []`, use only `"default"` for its no-effort candidate. Other keys,
|
|
52
|
+
unsupported efforts, non-numbers and values outside 0–3 or between half-steps are invalid.
|
|
53
|
+
|
|
54
|
+
A user-supplied map replaces the preset map in full; `{}` clears it. Replacing a model ID clears inherited
|
|
55
|
+
capability, even if the same alias is kept; the `[1m]` context hint alone does not change identity. Changing
|
|
56
|
+
`efforts` prunes unsupported inherited entries; unsupported explicitly supplied entries are rejected. Capability
|
|
57
|
+
is separate from `strength`, which still controls the current table routing. Capability declarations affect `auto` and `shadow`; the default `table` uses strength. Built-in declarations and their evidence limits are listed in [Providers](providers.md#capability-evidence).
|
|
58
|
+
|
|
40
59
|
### Provider prices
|
|
41
60
|
|
|
42
61
|
All non-Anthropic built-in model windows are at least 1M tokens.
|
|
@@ -106,6 +125,24 @@ The router never substitutes zero savings or invents another route's cache hit r
|
|
|
106
125
|
Models with `efforts: []`, including MiMo, ignore session effort in the comparison identity.
|
|
107
126
|
Missing counters remain unknown. See [provider acceptance checks](evaluation.md#provider-profiles).
|
|
108
127
|
|
|
128
|
+
## Routing engine
|
|
129
|
+
|
|
130
|
+
Set `routingEngine` in the selected profile file (`router.json` or `<provider>-router.json`); the default is `table`.
|
|
131
|
+
For example, set `{"routingEngine":"shadow"}` or `{"routingEngine":"auto"}`; omit the key to use `table`.
|
|
132
|
+
The engine is selected in this file, not by a `/router` command.
|
|
133
|
+
|
|
134
|
+
- **`table` (default):** the deterministic tier-by-activity routes are used. Routing modes transform those routes before the table policy.
|
|
135
|
+
- **`shadow`:** the table still sends every request. The automatic engine records one-step proposals against the real incumbent and cache, without keeping a separate route history or asking the classifier again. The Now pane and `/router decisions` show demand, target, capability (or unknown), outcome and a next-turn estimate. While shadow is enabled, the main-turn hook also records bounded replay traces. Export with `/router trace export`; for the work profile (`CLAUDE_CONFIG_DIR=~/.claude-team`) the file is `~/.claude-team/router-traces.json`. Retain all incremental export and rollover files. From a source checkout, run `node scripts/replay-traces.mjs ~/.claude-team/router-traces.json`, adding every rollover file as another argument. The export lives beside the selected profile config; the replay CLI is not included in the npm package. Replay checks table fidelity first; evaluation and exposure gates remain unestablished. See [evaluation](evaluation.md#replay-trace-recorder).
|
|
136
|
+
- **`auto`:** the stateful engine selects each main-turn model and effort from the configured catalog using classifier demand, a mode margin, and hard/cache constraints. It does not use route tables or mode policy patches. Tier pins set exact demand for one turn, without a mode margin, and still obey hard constraints. A first routed decision can move from a known below-requirement native model to a declared qualifying candidate under the normal switch-tax and cash gates; failures can escalate to stronger eligible candidates. Demand, votes, holds and routed demand persist across turns. If no eligible candidate fits, the native request is kept with reason `no-route-native`; after an observed provider fallback, the rest of that turn stays native, and the next turn can re-enter an eligible route.
|
|
137
|
+
|
|
138
|
+
Auto asks the active classifier for demand. Configure a classifier credential when the provider requires a key; local Ollama needs no key. Without classifier advice, the engine cannot detect demand and holds the startup route; a qualifying startup capability move based on the prompt tier may still occur.
|
|
139
|
+
|
|
140
|
+
Useful auto routing depends on the profile's per-effort `models.<alias>.capability` declarations: unknown is not zero or proof of adequacy. Without declarations, auto cannot identify a known adequate target. Built-in Haiku declares `medium: 0` and `high: 1`; Opus declares `medium: 2` and `xhigh: 3`. These are policy seeds, not measured quality. Other efforts and provider presets remain unknown. Capability maps replace inherited maps atomically; changing a model ID clears stale inherited capabilities. See [capability evidence](providers.md#capability-evidence).
|
|
141
|
+
|
|
142
|
+
Auto decision rows show demand, target, outcome and move reasons such as `startup`, `upgrade`, `escalation`, `same-route`, `reentry` and `no-route-native`.
|
|
143
|
+
|
|
144
|
+
`/router auto` turns routing on for the session; `/router off` turns it off. Neither changes `routingEngine`. `/router mode cost|balanced|quality` selects the mode, and `/router pin <tier>` pins one turn. Evaluation and default cutover remain pending; see [evaluation](evaluation.md). Engine values are case-sensitive.
|
|
145
|
+
|
|
109
146
|
## Built-in defaults
|
|
110
147
|
|
|
111
148
|
The default baseline is tier `low`. Each route refers to an alias in `models`.
|
|
@@ -305,7 +342,8 @@ These agents always keep their model:
|
|
|
305
342
|
- a fork;
|
|
306
343
|
- an Agent call that names a `model`;
|
|
307
344
|
- a teammate;
|
|
308
|
-
- a workflow `agent()`:
|
|
345
|
+
- a workflow `agent({ model })`: the script chose it. A workflow `agent()` without a model is classified like `general-purpose`, unless you set `workflow-subagent` to `null` under `subagents.types`;
|
|
346
|
+
- a resumed subagent: it runs on the model of its first spawn, and Claude Code lets a hook only refuse a resume;
|
|
309
347
|
- a built-in agent other than Explore, Plan and general-purpose: its definition is not on disk.
|
|
310
348
|
|
|
311
349
|
```json
|
|
@@ -323,6 +361,12 @@ These agents always keep their model:
|
|
|
323
361
|
|
|
324
362
|
The values above are the defaults.
|
|
325
363
|
|
|
364
|
+
Workflow agents are routed by default, classified like `general-purpose`. The key is the engine's own name for them, `workflow-subagent` (whatever type the script gives an agent does not apply to it); its value is a models key, `classify`, or `null` to keep Claude Code's pick:
|
|
365
|
+
|
|
366
|
+
```json
|
|
367
|
+
{ "subagents": { "types": { "workflow-subagent": null } } }
|
|
368
|
+
```
|
|
369
|
+
|
|
326
370
|
- `types` overrides the rule for an agent type: a models key, `classify`, or `null` to never route it. A user file adds to the defaults. A key without a colon matches only Claude Code's built-in of that name, such as `Explore`; a project agent named `Explore` replaces the built-in and follows its own definition. A `plugin:name` key matches only that plugin's agent. A listed type is routed even if its definition pins a model.
|
|
327
371
|
- `classify` asks the active classifier, once, with the task's description and prompt. It sends no history and no tool results. The task runs on `heavy` when the classifier gives `high` at least `heavyMass`. It runs on `light` for exploration (the `explore` activity above `policy.activityMass`) or the `micro` tier. Everything else runs on `standard`. Every routed agent not listed in `types` is classified. In `on` the spawn waits up to the classifier's `timeoutMs`, at most 3 seconds.
|
|
328
372
|
- A classifier failure or a missing key keeps the model Claude Code gives the agent, and so does a model that `availableModels` blocks, or settings the router cannot read. So does routing off: `/router off`, or a `/model` choice.
|
|
@@ -351,7 +395,7 @@ The Mod validates the whole file. Unknown keys and invalid values make routing u
|
|
|
351
395
|
| `mode` | `cost`, `balanced`, `quality` ([Routing modes](routing-modes.md)) | `balanced` |
|
|
352
396
|
| `modes.<cost\|quality>.policy` | any `policy` field, used while that mode is active | [Routing modes](routing-modes.md#policy-per-mode); not tuned |
|
|
353
397
|
| `activities.<activity>.<tier>` | optional `model` and `effort`, as in `routes` | The overrides in [Activity routing](#activity-routing) |
|
|
354
|
-
| `models.<alias>` | `id`, `input`, optional `output`, `cacheRead`, optional `longContext` (`above`, `multiplier`, or `null`), optional `offPeak` (`multiplier`, `peakDays` as UTC weekdays 0–6 from Sunday, `peakHoursUtc` as `[from, to)` hour ranges, or `null`), `contextWindow`, `billing`, `efforts`, optional `strength`, `imageInput` | Three defaults above |
|
|
398
|
+
| `models.<alias>` | `id`, `input`, optional `output`, `cacheRead`, optional `longContext` (`above`, `multiplier`, or `null`), optional `offPeak` (`multiplier`, `peakDays` as UTC weekdays 0–6 from Sunday, `peakHoursUtc` as `[from, to)` hour ranges, or `null`), `contextWindow`, `billing`, `efforts`, optional `strength`, optional `capability`, `imageInput` | Three defaults above |
|
|
355
399
|
| `cache` | `mode`, `effortScope`, `writeMultiplier`, `ttlMs`, `warmMarginMs` | `5m: 1.25`, `1h: 2`; `300000` / `3600000` ms; `30000` ms |
|
|
356
400
|
| `policy` | Fields below | Values below |
|
|
357
401
|
| `classifier` | An id in `classifiers` | `jev` |
|