@alexeiled/claude-router 1.26.0 → 1.27.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 +19 -0
- package/README.md +1 -1
- package/docs/architecture.md +3 -2
- package/docs/configuration.md +65 -1
- package/docs/providers.md +9 -0
- package/docs/user-guide.md +47 -10
- package/hooks/native-router.mjs +243 -25
- package/lib/band.mjs +7 -1
- package/lib/config.mjs +72 -1
- package/lib/decisions.mjs +46 -1
- package/lib/display.mjs +3 -2
- package/lib/failover.mjs +260 -23
- package/lib/holds.mjs +129 -0
- package/lib/providers.mjs +2 -0
- package/lib/route.mjs +217 -86
- package/lib/subcommands.mjs +8 -4
- package/lib/ui/graphical/band.mjs +1 -1
- package/lib/ui/graphical/now.mjs +44 -0
- package/lib/ui/graphical/routes.mjs +45 -0
- package/lib/ui/model/band.mjs +5 -2
- package/lib/ui/model/frame.mjs +2 -2
- package/lib/ui/model/now.mjs +35 -1
- package/lib/ui/model/routes.mjs +68 -5
- package/lib/ui/terminal/band.mjs +1 -1
- package/lib/ui/terminal/now.mjs +29 -0
- package/lib/ui/terminal/routes.mjs +31 -0
- package/lib/view.mjs +5 -0
- package/package.json +1 -1
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "router",
|
|
3
3
|
"displayName": "Router",
|
|
4
|
-
"version": "1.
|
|
4
|
+
"version": "1.27.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,24 @@
|
|
|
1
1
|
# Changelog
|
|
2
2
|
|
|
3
|
+
## 1.27.0 (2026-11-19)
|
|
4
|
+
|
|
5
|
+
### Summary
|
|
6
|
+
|
|
7
|
+
When a model fails, the router now tells an outage from a used-up limit, runs the fallback models you list for it, and returns on its own when the provider recovers or the limit resets. A used-up Claude plan window holds every plan model until its reset, in every session. The Now tab shows what is held with Release and Undo, and Routes lists the fallback chains. No upgrade steps; Claude Code 2.1.321 or newer is still required.
|
|
8
|
+
|
|
9
|
+
### Added
|
|
10
|
+
|
|
11
|
+
- **Fallback chains:** `fallbacks` in `router.json` lists, per model, the models that run its turns while it is held out, such as `"opus": ["glm@max", "deepseek@max"]`. A bare entry takes the source's effort, an `alias@effort` entry its own. When no target fits, the nearest tier's route applies as before. The stand-in serves the turn and never becomes the running route, so routing returns to the model after the hold.
|
|
12
|
+
- **Failure kinds and account holds:** the router now tells an availability failure (the model is held for a time that doubles on each failed retry, up to an hour) from a used-up 5-hour or 7-day plan window, a monthly spend limit and an empty balance. These hold the whole account, the Claude plan for plan models, until the limit's reset or a release. A used-up window holds the plan even when other models pay credits, so Opus on the plan falls back to a credits model such as GLM; with plan models in two accounts the readings cannot name one, and it stays an availability hold. Account holds are kept in the plugin's store, so a new session sees them. A `billing_error` used to hold nothing; it now holds its account until released.
|
|
13
|
+
- **`accounts` and model keys:** `models.<alias>.account` groups models for one quota, `accounts.<name>.reset` (`monthly` day 1-28 and `tz`) sets when a spend limit resets, and `models.<alias>.requiresOwnHistory` marks a model that reads only its own thinking history, which the Kimi preset sets. A chain cannot mix such a model with another, and the nearest-tier rule never switches into or out of it from another model. See [Configuration](docs/configuration.md#accounts-and-fallback-chains).
|
|
14
|
+
- **`/router holds` and `/router release <model|account>`** list the holds and end one early. The prompt offers the words held now.
|
|
15
|
+
- **Pane:** a **HELD OUT** section on Now shows each hold with its cause, end and covered models, and **Release** with **Undo**; **why** reads `↷ Opus 5.5 held · fallback 1 of 2`. Routes shows a read-only **FALLBACKS** list and marks a held cell `↷`. The band and the switch toast name the cause and the end, such as `Claude plan 5h limit · back 19:00 → GLM 5.3 · max`.
|
|
16
|
+
- **Decisions:** every main-turn failure adds a `failure` row with the error word, the first 300 characters of Claude Code's error details, the plan readings, the kind and what was held.
|
|
17
|
+
|
|
18
|
+
### Notes
|
|
19
|
+
|
|
20
|
+
- Not checked live: what Claude Code's `error_details` holds on a real failure (it is optional, and every path works without it), a real 5-hour limit reading at 100%, a real `overloaded`, and a chain run on a provider that has to read another model's thinking history.
|
|
21
|
+
|
|
3
22
|
## 1.26.0 (2026-11-18)
|
|
4
23
|
|
|
5
24
|
### Summary
|
package/README.md
CHANGED
|
@@ -116,7 +116,7 @@ sequenceDiagram
|
|
|
116
116
|
Mod-->>Dev: Status band and router pane
|
|
117
117
|
```
|
|
118
118
|
|
|
119
|
-
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.
|
|
119
|
+
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. When a model fails with an API error, the router holds it, or its whole account for a used-up plan window, spend limit or balance, out of routing, and runs a fallback chain you configure or the nearest tier on another model; `/router holds` and `/router release` show and end holds. See [When a model fails](docs/user-guide.md#when-a-model-fails). 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.
|
|
120
120
|
|
|
121
121
|
With the Anthropic profile, the base routes are:
|
|
122
122
|
|
package/docs/architecture.md
CHANGED
|
@@ -54,7 +54,8 @@ Claude Code builds each request for the model the Mod selects, so no request rew
|
|
|
54
54
|
| [Classifier contract](../lib/classifier-contract.mjs) | Route criteria and instructions shared by every protocol, credentials and endpoint filling, and retry rules. |
|
|
55
55
|
| [Classifier APIs](../lib/classifier-apis.mjs) | One adapter per wire protocol: request payload, answer validation, and the shared advice shape. |
|
|
56
56
|
| [Classifier client](../lib/classifier-client.mjs) | Classifier HTTP, deadline, in-flight admission, and circuit breaker. |
|
|
57
|
-
| [Failover](../lib/failover.mjs) |
|
|
57
|
+
| [Failover](../lib/failover.mjs) | What an API failure is (availability, window, calendar, balance), what it holds, for how long, and which holds still run. |
|
|
58
|
+
| [Holds](../lib/holds.mjs) | The running holds as rows for the pane, the band, the toast and `/router holds` and `/router release`. |
|
|
58
59
|
| [Router controller](../lib/route.mjs) | Context fit, model identity, engine fallback, cache observations, one-turn pins, and the tier-and-activity cell. |
|
|
59
60
|
| [Activity rules](../lib/activity.mjs) | Which activity applies, how two routes compare, and when a route change inside a tier is worth it. |
|
|
60
61
|
| [Activity stats](../lib/activity-stats.mjs) | Session and stored activity counts, the tool-agreement table, and the per-turn record. |
|
|
@@ -108,7 +109,7 @@ A move to a smaller context window needs a main-response measurement from the cu
|
|
|
108
109
|
|
|
109
110
|
An explicit context-window failure marks that model ineligible until the next history reset. An engine fallback suspends rewriting for the rest of the turn. The router does not retry an Anthropic request.
|
|
110
111
|
|
|
111
|
-
A main turn that ends on an API error (`classic.StopFailure`) holds the model of the last main request
|
|
112
|
+
A main turn that ends on an API error (`classic.StopFailure`) is classified (`classifyFailure`, `lib/failover.mjs`) from the plan readings, the error details when Claude Code gives them, and the error word, into one of four kinds. An `availability` failure (`overloaded`, `server_error`, `model_not_found`, a `rate_limit` with no quota signal) holds the model of the last main request in `loop.held` for a fixed time that doubles per consecutive failed retry, to an hour. A `window` needs the failed model on the plan account and every plan-billed model in that one account (`planAccountsOf`), since only the Claude plan reports window readings; a session that also pays credits qualifies. A `window`, `calendar` or `balance` failure holds the model's account instead, written to `$.store` under `holds/<account>` so a new session and a restart see it; the hook reads these holds at turn start and `lib/` receives them as data. Other errors are not the model's and hold nothing. The event carries neither the model nor a retry-after, so the hook keeps the last request's model. At the next turn a cell whose route runs a held model (or a model of a held account) takes the first usable target of its `fallbacks` chain, a route that need not be in any tier; with no chain, or every target skipped, it falls back to the nearest tier, the stronger of two as near, at the turn's activity, skipping any switch into or out of a `requiresOwnHistory` model. The reason is `model-held`, and a chain's step is recorded in `decision.fallback`. That fallback serves the turn only, as a pin does: `lastRoute` and `loop.route` keep the held route, so the turn after the hold runs it again with no switching gate. That is so only when the cell's configured route runs a held model too. A held `loop.route` is not usable, so `routeTurn` rebuilds the incumbent from config; where `loop.route` was kept apart from config (a routing-mode change or a route edit since it was chosen, or `ownRoute` for a session model no tier routes to) and the configured route runs another model, the turn runs that route with its usual reason, `chooseRoute` stores it as `loop.route`, and the held route does not come back. The policy state also stays as it was, only the turn counted, so a failure whose escalation the hold turned away still escalates once it ends. A compaction keeps the holds. Inside a turn no move lands on a held model: `observedMove` keeps the running route, and `continueRoute` skips a held route for a context fit or an image tier as it skips an ineligible one. The `auto` engine does not read holds, so with it the hook writes none and shows no toast.
|
|
112
113
|
|
|
113
114
|
## Activity routing
|
|
114
115
|
|
package/docs/configuration.md
CHANGED
|
@@ -395,7 +395,9 @@ The Mod validates the whole file. Unknown keys and invalid values make routing u
|
|
|
395
395
|
| `mode` | `cost`, `balanced`, `quality` ([Routing modes](routing-modes.md)) | `balanced` |
|
|
396
396
|
| `modes.<cost\|quality>.policy` | any `policy` field, used while that mode is active | [Routing modes](routing-modes.md#policy-per-mode); not tuned |
|
|
397
397
|
| `activities.<activity>.<tier>` | optional `model` and `effort`, as in `routes` | The overrides in [Activity routing](#activity-routing) |
|
|
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 |
|
|
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`, optional `account`, optional `requiresOwnHistory` | Three defaults above |
|
|
399
|
+
| `fallbacks.<alias>` | A list of `alias` or `alias@effort` entries: the models that stand in when `<alias>` is held out | `{}` (none) |
|
|
400
|
+
| `accounts.<name>.reset` | `monthly` (day 1-28) and `tz` (an IANA time zone) | `{}` (none) |
|
|
399
401
|
| `cache` | `mode`, `effortScope`, `writeMultiplier`, `ttlMs`, `warmMarginMs` | `5m: 1.25`, `1h: 2`; `300000` / `3600000` ms; `30000` ms |
|
|
400
402
|
| `policy` | Fields below | Values below |
|
|
401
403
|
| `classifier` | An id in `classifiers` | `jev` |
|
|
@@ -433,6 +435,68 @@ Opus 5.5, Sonnet 5.5, Haiku 5.5, Fable 5.1 and Fable 5.2 keep one prompt cache a
|
|
|
433
435
|
|
|
434
436
|
Native cache freshness is unknown after 270 seconds or after a history reset. Claude usage does not report the cache TTL. The policy evaluates price bounds for five-minute and one-hour writes, but the one-hour case is not observed fact. See the [architecture](architecture.md#cache-and-cost) for the estimate rules.
|
|
435
437
|
|
|
438
|
+
### Accounts and fallback chains
|
|
439
|
+
|
|
440
|
+
When a model is held out of routing ([When a model fails](user-guide.md#when-a-model-fails)), its turn can run a stand-in you choose. Four settings describe it. This file is valid on the default Anthropic profile as it stands, because each added model is defined in full (`id`, prices, `contextWindow`, `billing`, `efforts`). Under a provider profile that already defines `glm` or `kimi`, a shorter entry such as `"glm": { "account": "zai" }` is enough:
|
|
441
|
+
|
|
442
|
+
```json
|
|
443
|
+
{
|
|
444
|
+
"fallbacks": {
|
|
445
|
+
"opus": ["glm@max", "sonnet"],
|
|
446
|
+
"sonnet": ["glm@high"]
|
|
447
|
+
},
|
|
448
|
+
"models": {
|
|
449
|
+
"glm": {
|
|
450
|
+
"id": "glm-5.3[1m]",
|
|
451
|
+
"input": 1.4,
|
|
452
|
+
"output": 4.4,
|
|
453
|
+
"cacheRead": 0.26,
|
|
454
|
+
"contextWindow": 1000000,
|
|
455
|
+
"billing": "credits",
|
|
456
|
+
"efforts": ["low", "high", "max"],
|
|
457
|
+
"account": "zai"
|
|
458
|
+
},
|
|
459
|
+
"kimi": {
|
|
460
|
+
"id": "kimi-k3.1-pro[1m]",
|
|
461
|
+
"input": 2,
|
|
462
|
+
"output": 10,
|
|
463
|
+
"cacheRead": 0.2,
|
|
464
|
+
"contextWindow": 1048576,
|
|
465
|
+
"billing": "credits",
|
|
466
|
+
"efforts": ["low", "high", "max"],
|
|
467
|
+
"requiresOwnHistory": true
|
|
468
|
+
}
|
|
469
|
+
},
|
|
470
|
+
"accounts": {
|
|
471
|
+
"zai": { "reset": { "monthly": 1, "tz": "UTC" } }
|
|
472
|
+
}
|
|
473
|
+
}
|
|
474
|
+
```
|
|
475
|
+
|
|
476
|
+
- **`fallbacks`:** per source model key, an ordered list of targets; the router takes the first one that is allowed and not held. An entry is `alias` or `alias@effort`; the effort must be one of the target's `efforts`. A bare `alias` runs at the source's effort; one the target does not support moves down to the nearest it does, or to its lowest when none is below. A target is a route of its own and need not appear in any tier. The list is not followed through: a target's own chain is not used. Subagents and the `auto` engine use no chains.
|
|
477
|
+
- **`models.<alias>.account`:** the quota account the model belongs to, a name of letters, digits, dots, dashes and underscores. A model with `billing: "plan"` is on the account `plan` by default; any other model is its own account, named by its key. Models that share an account are held out together when its quota is used up.
|
|
478
|
+
- **`accounts.<name>.reset`:** `{ "monthly": <1-28>, "tz": "<IANA zone>" }`, the day a monthly spend limit resets. Only a failure that says "spend limit" uses it; without it that hold lasts 24 hours and the next turn tries again. The reset is midnight in `tz` on that day.
|
|
479
|
+
- **`models.<alias>.requiresOwnHistory`:** `true` for a model that reads only its own thinking history. The Kimi preset sets it ([providers](providers.md#kimi-and-history)). The router never switches into or out of it from another model in a fallback or nearest-tier stand-in.
|
|
480
|
+
|
|
481
|
+
Each of these makes the file invalid, and routing unavailable, until fixed. The message names the setting, never its value:
|
|
482
|
+
|
|
483
|
+
| Message | Cause |
|
|
484
|
+
| ----------------------------------------------------------------------- | ---------------------------------------------------------------- |
|
|
485
|
+
| `fallbacks.<alias> is not in models` | The source key is not a model. |
|
|
486
|
+
| `fallbacks.<alias> must be a list` | The value is not a list. |
|
|
487
|
+
| `fallbacks.<alias>[i] must be a models key or models key@effort` | An entry is not a string of that shape. |
|
|
488
|
+
| `fallbacks.<alias>[i] is not in models` | A target key is not a model. |
|
|
489
|
+
| `fallbacks.<alias>[i] is the model it stands in for` | A model lists itself. |
|
|
490
|
+
| `fallbacks.<alias>[i] is listed twice` | A target appears twice in one chain. |
|
|
491
|
+
| `fallbacks.<alias>[i] effort is not supported by its model` | The effort is not in the target's `efforts`. |
|
|
492
|
+
| `fallbacks.<alias> mixes a model that requires its own history with another model` | A chain holds such a model together with another. |
|
|
493
|
+
| `models.<alias>.account must be a name of letters, digits, dots, dashes and underscores` | A bad account name. |
|
|
494
|
+
| `models.<alias>.requiresOwnHistory must be a boolean` | Not `true` or `false`. |
|
|
495
|
+
| `accounts.<name>.reset.monthly must be a day from 1 to 28` | The day is not a whole number from 1 to 28. |
|
|
496
|
+
| `accounts.<name>.reset.tz must be an IANA time zone` | The zone is missing or unknown. |
|
|
497
|
+
|
|
498
|
+
The pane reads these settings but does not write them: **Routes** shows the chains in **FALLBACKS**, **Now** shows what is held. Edit the file directly.
|
|
499
|
+
|
|
436
500
|
## Convert an older `router.json`
|
|
437
501
|
|
|
438
502
|
Router 1.1 kept the Jev settings in a `jev` section. The current version reads `classifiers.jev` instead and makes routing unavailable while a `jev` section remains. Run the migration command below on the file. It moves `jev.endpoint`, `jev.model`, and `jev.timeoutMs` to `classifiers.jev`, keeps everything else, and writes an exact-byte `router.json.v1.1.backup`. A file without a `jev` section needs no change.
|
package/docs/providers.md
CHANGED
|
@@ -115,6 +115,15 @@ When migrating Kimi, start a **fresh conversation**. Its preserved thinking/sign
|
|
|
115
115
|
resuming another model's history into K3-family models is not a supported migration.
|
|
116
116
|
The default Kimi ladder uses one model throughout, not a K2/K3 mixture.
|
|
117
117
|
|
|
118
|
+
### Kimi and history
|
|
119
|
+
|
|
120
|
+
The Kimi preset sets `requiresOwnHistory: true` on `k3`. A model that reads only its own thinking history cannot take over a session that another model ran, and another model cannot take over its session. The router therefore:
|
|
121
|
+
|
|
122
|
+
- rejects a `fallbacks` chain that holds `k3`, as source or target, together with another model;
|
|
123
|
+
- never uses the nearest-tier rule to switch into or out of `k3` from another model when a model is held out.
|
|
124
|
+
|
|
125
|
+
Cross-provider history is a caveat for every other chain too. Claude Code resends the same history to the stand-in, and thinking blocks and signatures belong to the model that wrote them. A chain from an Anthropic model to GLM or DeepSeek is allowed because you choose it. Not checked live: how each provider handles another model's thinking history in a fallback turn. Set `requiresOwnHistory` on any model you find that needs it ([Configuration](configuration.md#accounts-and-fallback-chains)).
|
|
126
|
+
|
|
118
127
|
### Model IDs
|
|
119
128
|
|
|
120
129
|
| Profile | Alias | Model ID |
|
package/docs/user-guide.md
CHANGED
|
@@ -414,18 +414,53 @@ On Claude Code 2.1.322 an effort that the router changed inside a turn was not s
|
|
|
414
414
|
|
|
415
415
|
### When a model fails
|
|
416
416
|
|
|
417
|
-
When a turn ends on an API error that is the model's fault, the router holds
|
|
417
|
+
When a turn ends on an API error that is the model's fault, the router holds something out of routing for a while, so the next turns run another model. A toast says so once, such as `Opus 5.5 held out of routing: overloaded, 5 min` or `Claude plan held out of routing: usage limit, 4 h`.
|
|
418
418
|
|
|
419
|
-
|
|
420
|
-
| ------------------------- | ------------ |
|
|
421
|
-
| `rate_limit` | 5 minutes |
|
|
422
|
-
| `overloaded` | 5 minutes |
|
|
423
|
-
| `server_error` | 2 minutes |
|
|
424
|
-
| `model_not_found` | 1 hour |
|
|
419
|
+
The router sorts each failure into one of four kinds, from the plan's usage readings first, then the error's text when Claude Code gives it, then the error word:
|
|
425
420
|
|
|
426
|
-
|
|
421
|
+
| Kind | Recognised by | Held out | Ends |
|
|
422
|
+
| -------------- | ------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------- | ------------------------------------------------------------------------ |
|
|
423
|
+
| `availability` | `overloaded`, `server_error`, `model_not_found`, or `rate_limit` with no sign of a used-up quota | The model | After a fixed time, doubled on each failed retry (see below) |
|
|
424
|
+
| `window` | `rate_limit` while a `five_hour` or `seven_day` plan reading is at 100% or more and resets later | The account, which is the Claude plan for plan models | The latest reset time plus 1 minute, at most 7 days away |
|
|
425
|
+
| `calendar` | `rate_limit` whose text says "spend limit" | The account | The account's configured monthly reset, or 24 hours when none is set |
|
|
426
|
+
| `balance` | `billing_error`, or a `rate_limit` whose text names a balance, a recharge or credit | The account | A release (`/router release`) |
|
|
427
427
|
|
|
428
|
-
|
|
428
|
+
An authentication or request error (`authentication_failed`, `oauth_org_not_allowed`, `account_on_hold`, `invalid_request`), a cut-off answer and an unknown error hold nothing: another model would not help. Claude Code reports no retry-after, so an availability hold uses a fixed time.
|
|
429
|
+
|
|
430
|
+
| Error Claude Code reports | First hold |
|
|
431
|
+
| ------------------------- | ---------- |
|
|
432
|
+
| `rate_limit` | 5 minutes |
|
|
433
|
+
| `overloaded` | 5 minutes |
|
|
434
|
+
| `server_error` | 2 minutes |
|
|
435
|
+
| `model_not_found` | 1 hour |
|
|
436
|
+
|
|
437
|
+
- **Availability, retries:** when the model fails again with the same error right after a hold ended, the next hold is twice as long, to at most 60 minutes. `overloaded` goes 5, 10, 20, 40, 60. A failure while a hold is still running is not a retry. A reply from that model clears the count.
|
|
438
|
+
- **A window needs one plan account.** Only the Claude plan reports `five_hour` and `seven_day` readings. A window applies when the failed model is on the plan account and every model with `billing: "plan"` is on that one account, so a session that also pays through a proxy or credits holds the plan, and a chain such as `opus → glm` moves to the credits model. When plan models sit in two or more accounts (`models.<alias>.account`), the readings cannot say which account is out, so a `rate_limit` is an availability failure there.
|
|
439
|
+
- **An account holds every model on it.** A model with `billing: "plan"` is on the account `plan`; any other model is its own account unless `models.<alias>.account` groups it with others ([Configuration](configuration.md#accounts-and-fallback-chains)). A quota failure of a model that no configured model ran holds nothing.
|
|
440
|
+
- **Account holds are kept in the plugin's store** (`holds/<account>`), so another session sees them and a restart keeps them. Model holds stay in the session. If two sessions write the same account hold at once, one write can be lost; both say the same account is out.
|
|
441
|
+
- **A hold ending changes nothing by itself.** The failed request is not sent again, and nothing probes the model: the next turn routes as usual, and a model that was held out can run again.
|
|
442
|
+
|
|
443
|
+
While a model is held out, a turn whose route runs it, a pinned turn too, runs a stand-in:
|
|
444
|
+
|
|
445
|
+
1. The model's **fallback chain**, if `fallbacks` in `router.json` lists one: the first target that is allowed, not held (itself or through its account), not excluded this turn, able to take the turn's images and large enough for the context. While the context is unmeasured, a target with a smaller window than the last route is skipped. A bare target runs at the source's effort; an effort the target does not support moves down to the nearest one it does, or to its lowest when none is below (Opus at `medium` into GLM runs `low`, because the z.ai preset's GLM has `low`, `high` and `max`; write `glm@high` to pin it). `alias@effort` runs at its own effort. A target need not be in any tier.
|
|
446
|
+
2. When every target is skipped, or there is no chain, the nearest tier's route on another model at the turn's activity; of two tiers as near, the stronger.
|
|
447
|
+
|
|
448
|
+
The nearest-tier rule never switches into or out of a model that requires its own history (`requiresOwnHistory`, such as Kimi K3) from another model, and a chain cannot mix such a model with another.
|
|
449
|
+
|
|
450
|
+
The stand-in serves the turn and its tool calls, and never becomes the running route, so it does not stick: when the hold ends, the next turn returns to the route it held out without waiting for votes or a checkpoint. A route that is not its tier's configured route, kept from before a routing mode change or a route edit, or your own model when no tier routes to it, is the exception: when the tier's configured route runs another model, that route takes over at once and stays after the hold. The route line shows `! held out`. The band names who holds and until when, `↷ Claude plan 5h limit · back 19:00`, and the switch toast names the holder and the stand-in, `Claude plan 5h limit · back 19:00 → GLM 5.3 · max`; either falls back to `! held out` when no one hold can be named. If the stand-in fails, it gets the hold, not the model it stood in for. A subagent's failure holds nothing. A compaction keeps the holds; a new session starts without model holds and keeps account holds. With `"routingEngine": "auto"` no model or account is held and no toast shows: that engine does not route around holds.
|
|
451
|
+
|
|
452
|
+
Every main-turn failure also adds a `failure` row to the decision record: the error word, the first 300 characters of Claude Code's `error_details` (empty when it gives none), the plan readings at that moment, the kind, and what was held. `/router decisions` lists the row without the text.
|
|
453
|
+
|
|
454
|
+
**HELD OUT on Now.** A **HELD OUT** section after **NEXT TURN** shows while something is held, and also when routing is off, because an account hold outlives routing being off. Each row names the holder, the cause and the end (`5h limit · back 19:00`, `no balance · until released`, `overloaded ×2 · back 14:32`), the models it covers, and a **Release** button. Release applies on click and **Undo** puts the hold back. The footer names `router.json → fallbacks` and `/router holds`. When the turn runs a chain target, **why** reads `↷ Opus 5.5 held · fallback 1 of 2`.
|
|
455
|
+
|
|
456
|
+
**FALLBACKS on Routes.** A read-only **FALLBACKS** section under the grid lists each model that has a chain: its status and its targets in order, a held target marked `✕`, and the one running `◀ runs`. A held model's cell in the grid gets `↷`. The pane has no chain editor; edit `fallbacks` in `router.json`.
|
|
457
|
+
|
|
458
|
+
**Commands.**
|
|
459
|
+
|
|
460
|
+
- `/router holds` lists each hold with its scope (`account` or `model`), kind, cause, end and, for an account, the models it holds out: `plan (account) · window: 5h limit · back 19:00 · holds out …`.
|
|
461
|
+
- `/router release <model|account>` ends one early: an account name, a model's key in `router.json` or a model id. A model held only through its account is not released alone; the reply points to `/router release plan`. The prompt offers the words held now. Releasing is not a fix: if the model still fails, it is held again.
|
|
462
|
+
|
|
463
|
+
Not yet checked live: what `error_details` holds on a real failure (the `calendar` and `balance` text rules depend on it, and every path also works when it is absent), a real `rate_limit` at a 5h limit with a plan reading at 100% (the window kind relies on it), and a real `overloaded`. Tests use the shapes found in local transcripts.
|
|
429
464
|
|
|
430
465
|
### Read the activity on the pane
|
|
431
466
|
|
|
@@ -449,6 +484,8 @@ On the **Classifier** tab, **ACROSS SESSIONS · since the last reset** shows the
|
|
|
449
484
|
| `/router activities <off\|on>` | Set the [activity routing](#route-by-activity) mode. Saved to `router.json` at once; **Undo** reverts it. |
|
|
450
485
|
| `/router mode <cost\|balanced\|quality>` | Set this session's [routing mode](routing-modes.md) from the next turn. A resume keeps it. |
|
|
451
486
|
| `/router mode default` | Clear the session's mode: the project's or the profile's applies again. |
|
|
487
|
+
| `/router holds` | List the models and accounts held out of routing, with the cause and the end. See [When a model fails](#when-a-model-fails). |
|
|
488
|
+
| `/router release <model\|account>` | End a hold early. **Release** on the Now tab does the same, with **Undo**. |
|
|
452
489
|
| `/router decisions [n]` | Print this session's last `n` routing decisions, 20 by default. See [Routing decisions](#routing-decisions). |
|
|
453
490
|
| `/router line <off\|moves\|all>` | Choose when a turn leaves a [route line](#the-route-line) in the transcript. `moves` is the default. Kept across sessions. |
|
|
454
491
|
| `/model <name>` | Select a model and turn routing off. Use `/router auto` to turn it back on. The model picker and a model set from the SDK, an IDE or Remote Control do the same. |
|
|
@@ -456,7 +493,7 @@ On the **Classifier** tab, **ACROSS SESSIONS · since the last reset** shows the
|
|
|
456
493
|
| **on** / **off** on the pane (`o` / `f`) | The same as `/router auto` and `/router off`. |
|
|
457
494
|
| **pin** on the Now tab | Pin that tier for the next turn. Routing on must already be enabled. |
|
|
458
495
|
|
|
459
|
-
Type `/router` and a space, then a letter, and the prompt offers the words that start with it (`auto`, `off`, `pin <tier>`, `mode <mode>`, `activities <off|on>`, `line <off|moves|all>`, `decisions [n]`, `trace export`). After `pin `, `mode `, `activities ` or `line ` it offers the values; `pin` names the model each tier runs. The rows come after Claude Code's own. They are drawn by the surface's prompt box, so a surface that does not raise the typeahead shows none.
|
|
496
|
+
Type `/router` and a space, then a letter, and the prompt offers the words that start with it (`auto`, `off`, `pin <tier>`, `mode <mode>`, `activities <off|on>`, `line <off|moves|all>`, `holds`, `release <model|account>`, `decisions [n]`, `trace export`). After `pin `, `mode `, `activities ` or `line ` it offers the values, and after `release ` the models and accounts held now; `pin` names the model each tier runs. The rows come after Claude Code's own. They are drawn by the surface's prompt box, so a surface that does not raise the typeahead shows none.
|
|
460
497
|
|
|
461
498
|
With `table` or `shadow`, a routing mode moves each tier's route one step toward cost or quality; pins and `micro` turns are not moved. With opt-in `auto`, the mode changes the demand margin instead, and a tier pin uses exact demand without a margin. The band and the Now tab show the mode and where it comes from, such as `cost (session)`. When the mode kept the cell's model and changed only its effort, as `cost` does for Opus at `high`, the band adds `effort only`: the cost estimates price the same tokens on both routes, so that change shows no difference there, though real output length can differ. A change applies from the next turn, and the route in use moves only through the usual checks, so on a running task a cheaper route can wait a few requests and for a checkpoint. **Mode** on the Policy tab sets the profile's mode. See [Routing modes](routing-modes.md).
|
|
462
499
|
|