@alexeiled/claude-router 1.10.3 → 1.11.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.
@@ -20,7 +20,7 @@ In Claude Code:
20
20
  1. Run `/plugin configure router`.
21
21
  2. Enter the credentials of the classifier you use, and save them:
22
22
  - **Jev** (the default): the Jev API key from typesafe.ai.
23
- - **Clef** or **Clef Flash** on Cloudflare Workers AI: the Cloudflare API token and the Cloudflare account ID. One token covers both models.
23
+ - **Clef**, **Clef Flash** or **Clef Omni** on Cloudflare Workers AI: the Cloudflare API token and the Cloudflare account ID. One token covers all three models.
24
24
  - **OpenAI**: an OpenAI API key. The prompt text goes to OpenAI.
25
25
  - **Ollama**: no credential. Run `ollama serve` and pull the model; the prompt text stays on this machine.
26
26
  3. To use another classifier, open the pane's **Classifier** tab and select its row. See [Choose the classifier](#choose-the-classifier).
@@ -43,35 +43,35 @@ Read the first line of the picture from left to right:
43
43
  - **Switch cost**: `switch cost ≈ $0.37`, the policy's price for the switch it weighed this turn, mostly the prompt cache the other model must write. For a move to a cheaper model it is net of what that model saves over the next turns. The higher the cost, the higher the bar a stronger model must clear.
44
44
  - **ctx** and **cache hit**: context use and the share of input read from the cache on the last reply. They turn yellow at 60% context and red at 80%.
45
45
 
46
- | Band shows | Meaning |
47
- | ----------------------------------------------- | --------------------------------------------------------------------------------------------------------------------- |
48
- | `Routing on · ready` | Routing is on and ready for a new turn. |
49
- | `choosing for this turn…` | The classifier and local policy are running. The spinner says `Choosing model`. |
50
- | `⏵ next turn: high ✕` | A pin is set. **✕** cancels it. |
51
- | `⚠ Jev: no API key · keeping model` | The active classifier lacks a setting. **Set up** opens the secure plugin dialog. |
52
- | `⚠ Clef: no account ID · keeping model` | Clef has its API token but no Cloudflare account ID. **Set up** opens the dialog. |
53
- | `⚠ Jev timed out · keeping model` | The classifier failed: timed out, unreachable, rejected the key, or paused. |
54
- | `○ Routing off [ Turn on ] · every turn uses …` | Routing is off: Claude's model answers every turn. **Turn on** turns it back on. The footer also shows `routing off`. |
55
- | `✕ Routing unavailable` | Nothing routes: an old Claude Code or leftover v0.8 settings. **Fix** opens the pane. |
46
+ | Band shows | Meaning |
47
+ | ----------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------- |
48
+ | `Routing on · ready` | Routing is on and ready for a new turn. |
49
+ | `choosing for this turn…` | The classifier and local policy are running. The spinner says `Choosing model`. |
50
+ | `⏵ next turn: high ✕` | A pin is set. **✕** cancels it. |
51
+ | `⚠ Jev: no API key · keeping model` | The active classifier lacks a setting. **Set up** opens the secure plugin dialog. |
52
+ | `⚠ Clef: no account ID · keeping model` | Clef has its API token but no Cloudflare account ID. **Set up** opens the dialog. |
53
+ | `⚠ Jev timed out · keeping model` | The classifier failed: timed out, unreachable, rejected the key, or paused. |
54
+ | `○ Routing off [ Turn on ] · every turn uses …` | Routing is off: Claude's model answers every turn. **Turn on** turns it back on. The footer also shows `routing off`. |
55
+ | `✕ Routing unavailable` | Nothing routes: an old Claude Code or leftover v0.8 settings. **Fix** opens the pane. |
56
56
  | `○ Router · subagents keep their own model` | You are viewing a subagent's transcript. Its steps are not routed; in `on` the band reads `subagent model chosen at spawn`. |
57
57
 
58
58
  The band shows one routing control at a time. While routing is on, hover over the band for a second row: pin a tier for the next turn, **Turn off** routing, or show two rows. While routing is off, **Turn on** sits on the first line next to `Routing off` and stays at any width: a narrow band drops the explanation and the model first. On a narrow band the hover row drops `routing on`, then **2 rows**, then `pin next turn`, then the pins; it keeps **Turn off**, and **1 row** when the band shows two. The hover row needs a pointer: from the keyboard, run `/router off`, or open the pane and press `f`. The two-row band adds this session against your model, the one `/model` selects now: `session saved $1.84 (22%) vs Opus 5.5 · xhigh · 64 replies · cold-cache writes +$0.47`, or `session extra $2.48 (×5.0) vs Haiku 5.5 · high · 41 replies · stronger models +$2.31` when routing cost more. The last part names the larger of the two costs behind the result, when there is one. After a `/model` change the row shows the whole session against the new model. Before the tenth routed reply it reads `session 3 replies · too early to compare`. When the row is short, the cost part drops first, then the reply count. Router remembers that choice across sessions. When Router changes the model between turns, a toast reads `Model changed: old → new · reason`. A pin does not raise one, and neither does a change of effort alone.
59
59
 
60
60
  The band steps aside while a survey needs the space.
61
61
 
62
- Tool continuations do not trigger another classification. A subagent gets at most one model, when it starts, and keeps it for every step: Haiku for exploration, Opus for clearly hard tasks, Sonnet for the rest. An agent that pins a model in its definition keeps it, unless it sets `modelRouting: auto`. The Usage tab's **SUBAGENTS** section shows what each agent type ran on and cost. See [Subagent routing](configuration.md#subagent-routing).
62
+ Inside a turn the router checks the route again as the work changes; see [Changes during a task](#changes-during-a-task). A subagent gets at most one model, when it starts, and keeps it for every step: Haiku for exploration, Opus for clearly hard tasks, Sonnet for the rest. An agent that pins a model in its definition keeps it, unless it sets `modelRouting: auto`. The Usage tab's **SUBAGENTS** section shows what each agent type ran on and cost. See [Subagent routing](configuration.md#subagent-routing).
63
63
 
64
64
  ## Open the router pane
65
65
 
66
66
  Run `/router` or select **Router** above the prompt. Without a UI surface, as in `claude -p`, `/router` prints a short status instead. The pane has five tabs. Select a tab or press its digit while the pane has focus.
67
67
 
68
- | Tab | What it answers |
69
- | ------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- |
70
- | 1 Now | What runs next turn, and why: tier, model, activity, the reason with the support it weighed; classifier support per tier with **pin**; the last 30 replies. |
71
- | 2 Routes | Which model runs: one grid of tiers by activities, the activity routing mode, and an editor for the selected cell. |
72
- | 3 Policy | How readily the router changes models: the start tier, going down, going up, the activity threshold, the credits cap; the `router.json` path. |
73
- | 4 Classifier | Which classifier to ask: one row per classifier to compare, the active one's deadline, wait, health and credentials, and the counts kept across sessions. |
74
- | 5 Usage | What routing cost: routing vs your model, plan quota, this session by activity, and Claude's readings with the estimates behind **details**. |
68
+ | Tab | What it answers |
69
+ | ------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------- |
70
+ | 1 Now | What runs next turn, and why: tier, model, activity, the reason with the support it weighed; classifier support per tier with **pin**; the last 30 replies. |
71
+ | 2 Routes | Which model runs: one grid of tiers by activities, the activity routing mode, and an editor for the selected cell. |
72
+ | 3 Policy | How readily the router changes models: the start tier, going down, going up, the activity threshold, the credits cap; the `router.json` path. |
73
+ | 4 Classifier | Which classifier to ask: one row per classifier to compare, the active one's deadline, wait, health and credentials, and the counts kept across sessions. |
74
+ | 5 Usage | What routing cost: routing vs your model, plan quota, this session by activity, and Claude's readings with the estimates behind **details**. |
75
75
 
76
76
  The top line of every tab, `ROUTING [ ◉ on ] [ ○ off ] Jev ready · 347 ms`, shows the routing mode, switches it, and says whether the classifier is ready. Press `o` or `f` while the pane has focus. **?** shows what the estimates leave out. When routing is unavailable, the top line reads `ROUTING unavailable Claude’s model is kept` with the reason under it, and offers no on or off: see [Troubleshooting](#troubleshooting).
77
77
 
@@ -97,7 +97,7 @@ The Usage tab opens with the answer, such as `Routing saved $1.84 (22%) this ses
97
97
  | Line | What it is |
98
98
  | -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- |
99
99
  | Routed replies | What the routed replies cost on the models that served them. |
100
- | Same tokens on your model | What the same input and output tokens cost on your model, with one cache that never switched. |
100
+ | Same tokens on your model | What the same input and output tokens cost on your model, with one cache that never switched. |
101
101
  | Difference | Routed minus yours. Green with a percentage when routing cost less; amber with `+$` when it cost more, `×N` once it is twice yours or more. |
102
102
  | cheaper models | The part from replies on models cheaper than yours. |
103
103
  | stronger than yours | The part from replies on stronger models, with how many replies ran on them. |
@@ -141,10 +141,10 @@ A mixed turn such as "fix it and commit" takes the hardest part, here `code`. Th
141
141
 
142
142
  The mode decides what happens with the label:
143
143
 
144
- | Mode | What the router does |
145
- | -------- | ---------------------------------------------------------------------------------------------------- |
146
- | `on` | The default. Applies the activity overrides. |
147
- | `off` | Does not ask the activity: the classifier is asked for the tier only. The base routes run. |
144
+ | Mode | What the router does |
145
+ | ----- | ------------------------------------------------------------------------------------------ |
146
+ | `on` | The default. Applies the activity overrides. |
147
+ | `off` | Does not ask the activity: the classifier is asked for the tier only. The base routes run. |
148
148
 
149
149
  To turn activity routing off, run `/router activities off`, or set **Activity routing** at the top of the Routes tab and press **Save**. Routing itself stays on: only the activity overrides stop. Upgrading from 1.6, which asked the activity but ran the base routes, run `/router activities off` to keep 1.6's routes. A `router.json` that still sets `"shadow"`, for activity or subagent routing, is read as not setting it, so the default, `on`, runs.
150
150
 
@@ -154,13 +154,30 @@ How the router moves inside a tier:
154
154
 
155
155
  - It compares routes, not labels. If the new activity resolves to the route already running, nothing switches.
156
156
  - A move to a stronger route needs the classifier's support, as an upgrade between tiers does. A move to a cheaper one must pay back its cache write within the payback horizon. One vote is enough for either, because the activity is a fact about this turn.
157
- - An activity applies only when the classifier gives it at least 60% probability (`policy.activityMass`). Below that, or on `uncertain`, a new task goes back to its base route if the move passes the same checks; a continuation of the running task keeps its activity, or moves to the classifier's activity when that route is stronger. Tool continuations inside a turn keep the turn's route. When the classifier sees a new prompt as a continuation of the task, the activity may only move to a stronger route: `explore` can become `code`, but not the other way. Ollama does not answer the continuation question, so this rule does not apply to it.
157
+ - An activity applies only when the classifier gives it at least 60% probability (`policy.activityMass`). Below that, or on `uncertain`, a new task goes back to its base route if the move passes the same checks. On the running task the activity can move either way while the turn runs; see [Changes during a task](#changes-during-a-task).
158
158
  - A pinned turn uses the pin's base route and shows no activity.
159
159
  - When the classifier gives no answer at all (a timeout, a failure, a pause, or a missing key), the running route stays. When it answers the tier but gives no usable activity, only the running activity stays: the tier answer still applies, so the turn can change tier and keeps its activity there. In `off` the base route always runs.
160
160
  - A fresh session starts with routing on when the session model is a tier's route. With activity routing `on`, a model that only an activity override uses also counts: Sonnet 5.5 on the defaults. In `off` it does not.
161
161
 
162
162
  The band's activity label appears only when the activity applies, so a weak or `uncertain` answer shows none. The two-row band and the **Replies** strip show the activities of recent replies.
163
163
 
164
+ ### Changes during a task
165
+
166
+ The classifier labels a turn from its prompt, and the work can change after that: a brief that reads as `ops` may turn into an hour of coding, and a hard fix may end in routine commands. The router therefore checks the route again while a task runs, for the tier and the activity, in both directions.
167
+
168
+ - **On every later step of a turn** it reads the turn's tool calls. A turn labelled `ops` or `explore` that edits a code file moves at once to the tier's `code` route (`docs` when it edits only Markdown or `docs/` files). The tools are the evidence, so this needs no classifier support, and the cache cost does not hold it back; only the cash cap on a credits-billed model can. This move only goes up. The toast and the band show it as `↗ coding`.
169
+ - **Every 4 requests inside a turn** (`policy.reviewEveryRequests`) it asks the classifier again, in the background, with the turn's prompt and the recent dialogue. A step never waits for the answer: it applies at the first step after it arrives. Each review sends the classifier the same kind of text a new turn does. `0` turns reviews off.
170
+ - **A new prompt that continues the task**, such as a task notification, a message from another agent, or "go on", is decided the same way as a review.
171
+
172
+ On the running task:
173
+
174
+ - A stronger tier takes the usual votes: two agreeing answers, or one for a clear two-tier jump. A stronger activity takes one answer whose probability clears the cache check. Repeated tool errors still escalate at once.
175
+ - A cheaper tier or activity also waits for a checkpoint: at least 8 requests since the last model change (`policy.minDwellRequests`), and the last test, build, lint or type-check command since then passed. A check is a test runner, type checker or linter (`pytest`, `tsc`, `eslint`), or a launcher running one (`npm test`, `go test`, `make lint`), alone or after `&&`. A check piped into another command (`npm test | tail`), followed by `;` or `|| true`, or sent to the background does not count, because its exit status can hide a failure or is not known yet. While none ran, or the last one failed, the route stays: for a tier the band shows `… down after a passed check`; a held activity keeps the running one and shows `= fits`. A cheaper activity also needs 90% probability (`policy.downgradeMass`).
176
+ - A cheaper tier lands where the answer as a whole points: when the classifier says `micro` 63% and `low` 30%, the turn moves to `low`, which 93% of the answer supports, instead of staying until `micro` alone reaches 90%.
177
+ - A pinned turn does not move. A new task, a prompt the classifier does not score as a continuation, is routed as a fresh turn. Ollama does not answer the continuation question, so every prompt is a new task to it; reviews inside a turn still apply.
178
+
179
+ These thresholds are starting values. They are not tuned on data yet.
180
+
164
181
  ### Read the activity on the pane
165
182
 
166
183
  - **Now**: the **Activity** line names the classifier's choice as a verb with its share, the two next-best answers, and the threshold at which an activity applies, such as `coding 84% debugging 8% · planning 5% applies at 60%+`. An `uncertain` answer is shown dim: it applies no activity. In `on`, **Why** names the cell when the activity moved the route or the route is an override, such as `coding at low runs on Sonnet 5.5 · high`, or `low runs on its base route, Haiku 5.5 · high` for a move without an activity; a refused move, a hold, or a tier change keeps its reason. **Last replies** counts the replies per activity under the strip.
@@ -179,7 +196,7 @@ On the **Classifier** tab, **ACROSS SESSIONS · since the last reset** shows the
179
196
  | `/router auto` | Resume automatic routing. |
180
197
  | `/router off` | Turn routing off and keep Claude's selected model. |
181
198
  | `/router pin <micro\|low\|medium\|high>` | Pin the next turn and its tool continuations. Routing on must already be enabled. |
182
- | `/router activities <off\|on>` | Set the [activity routing](#route-by-activity) mode. Saved to `router.json` at once; **Undo** reverts it. |
199
+ | `/router activities <off\|on>` | Set the [activity routing](#route-by-activity) mode. Saved to `router.json` at once; **Undo** reverts it. |
183
200
  | `/model <name>` | Select a model and turn routing off. Use `/router auto` to turn it back on. |
184
201
  | **Turn on** / **Turn off** on the band | The same as `/router auto` and `/router off`. |
185
202
  | **on** / **off** on the pane (`o` / `f`) | The same as `/router auto` and `/router off`. |
@@ -217,22 +234,25 @@ The **Policy** tab writes each control inside the sentence it completes, and nam
217
234
  - **Start** at a tier: the tier a session starts from when its model is no tier's model (`baselineTier`).
218
235
  - **Going down** after 1, 2, or 3 agreeing turns in a row, and only if a cache write pays back within 1, 3, 5, or 10 later turns. A new or reset history needs one vote.
219
236
  - **Going up** needs the classifier's support at 75%, raised up to 90% as the switch costs more. Read-only here; see [Configuration](configuration.md).
220
- - **Activities** apply at 50%, 60%, 70%, or 80% certainty or more. Below it a new task runs its tier's model, and a continuation keeps its activity, or moves to a stronger route the classifier names. See [Activity routing](activity-routing.md#change-a-cell).
237
+ - **Activities** apply at 50%, 60%, 70%, or 80% certainty or more. Below it a new task runs its tier's model; the running task follows [Changes during a task](#changes-during-a-task). See [Activity routing](activity-routing.md#change-a-cell).
221
238
  - **Credits** caps one cold cache write on a `credits` model at $0.50, $1, $2, or $5. With no `credits` model in `router.json`, the tab says the cap has no effect.
222
239
 
223
240
  **Reset policy to defaults** loads the built-in values; **Save** then removes your policy overrides. The current turn keeps the settings it started with. A save preserves unrelated `router.json` keys and refuses to write through a symlink. When validation fails, the pane names the setting and leaves the file unchanged. The tab ends with the `router.json` path, a **copy** button, and the [subagent routing](configuration.md#subagent-routing) mode, which is set in `router.json`.
224
241
 
225
242
  ## Choose the classifier
226
243
 
227
- Router asks one classifier per turn. Five are built in:
244
+ Router asks one classifier per turn. Six are built in:
245
+
246
+ | Classifier | Service | Credentials | Deadline |
247
+ | ---------- | ------------------------------ | ---------------------------------------------- | -------: |
248
+ | Jev | typesafe.ai | Jev API key | 1,500 ms |
249
+ | Clef | Cloudflare Workers AI, 27B | Cloudflare API token and Cloudflare account ID | 3,000 ms |
250
+ | Clef Flash | Cloudflare Workers AI, 9B | Cloudflare API token and Cloudflare account ID | 3,000 ms |
251
+ | Clef Omni | Cloudflare Workers AI, 30B MoE | Cloudflare API token and Cloudflare account ID | 3,000 ms |
252
+ | OpenAI | OpenAI, `gpt-6-luna` | OpenAI API key | 3,000 ms |
253
+ | Ollama | Local Ollama, `qwen3.5:9b` | None | 5,000 ms |
228
254
 
229
- | Classifier | Service | Credentials | Deadline |
230
- | ---------- | -------------------------- | ---------------------------------------------- | -------: |
231
- | Jev | typesafe.ai | Jev API key | 1,500 ms |
232
- | Clef | Cloudflare Workers AI, 27B | Cloudflare API token and Cloudflare account ID | 3,000 ms |
233
- | Clef Flash | Cloudflare Workers AI, 9B | Cloudflare API token and Cloudflare account ID | 3,000 ms |
234
- | OpenAI | OpenAI, `gpt-6-luna` | OpenAI API key | 3,000 ms |
235
- | Ollama | Local Ollama, `qwen3.5:9b` | None | 5,000 ms |
255
+ The three Clef models take the same request and the same Cloudflare credentials, so a switch between them changes only cost, speed and answers. Cloudflare bills input tokens only, per million: Clef Flash $0.038, Clef Omni $0.15, Clef $0.24 (list prices on 2026-10-13). A routing request is a few thousand tokens. In Cloudflare's own benchmarks no one model wins every task: Clef Omni leads on intent classification (BANKING77, CLINC150 with out-of-scope prompts), Clef on most of TypeSafe's workflow evals, and Clef Flash on tool-call tasks. Router has not measured Clef Omni on its own prompts yet. Clef Omni also reads images, audio and video; Router sends it text only.
236
256
 
237
257
  ![The Classifier tab: one row per classifier with where the prompt goes, its activity probe, its p95 wait and its status, a missing Jev API key with Set up; the active classifier's deadline against its wait, the host that receives the prompt, health and credentials; the agreement with tools across sessions; and Undo after a switch](router-pane-classifier.svg)
238
258
 
@@ -246,7 +266,7 @@ Under the rows, a block for the active classifier:
246
266
  - **Sends** names the service that receives prompt text. **Health** shows a pause, recent failures, and the last wait.
247
267
  - **Credentials**: **Edit** opens Claude Code's secure plugin configuration, where you enter them.
248
268
 
249
- With activity routing `on`, the activity question goes in the same request as the tier question (Ollama makes a second call), with the same text and nothing more. **Sends** names the service that receives the prompt and recent dialogue. With Clef or Clef Flash that is Cloudflare, not typesafe.ai; with OpenAI it is OpenAI; with Ollama it stays on this machine. Give the Cloudflare token Workers AI permissions only.
269
+ With activity routing `on`, the activity question goes in the same request as the tier question (Ollama makes a second call), with the same text and nothing more. **Sends** names the service that receives the prompt and recent dialogue. With Clef, Clef Flash or Clef Omni that is Cloudflare, not typesafe.ai; with OpenAI it is OpenAI; with Ollama it stays on this machine. Give the Cloudflare token Workers AI permissions only.
250
270
 
251
271
  The routing policy thresholds were tuned against Jev's probabilities. Clef's, OpenAI's, and Ollama's probabilities have not been compared with Jev's, so the same prompt can switch tiers at a different point. Watch **Classifier support** for a few sessions before you rely on a new classifier.
252
272
 
@@ -282,7 +302,7 @@ To stop routing for a session, run `/router off`. To keep tier routing but stop
282
302
  | Symptom | Cause | Fix |
283
303
  | ------------------------------------------- | ----------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
284
304
  | Status says `no API key` or `no API token` | The active classifier's plugin option is unset or unavailable to this process. | Select **Set up** in the pane, or run `/plugin configure router`. Save the option and start a new turn. |
285
- | Status says `no account ID` | Clef or Clef Flash is active without the Cloudflare account ID. | Run `/plugin configure router` and save the Cloudflare account ID. |
305
+ | Status says `no account ID` | Clef, Clef Flash or Clef Omni is active without the Cloudflare account ID. | Run `/plugin configure router` and save the Cloudflare account ID. |
286
306
  | Route stays on the current model | The classifier timed out, failed, is paused, or network policy refused it. | Read the status band and the pane header. Network policy refusal is not bypassed. |
287
307
  | `/model` changed but routing stopped | Choosing a model turns routing off. | Run `/router auto` to turn routing back on. |
288
308
  | Router reports invalid configuration | `router.json` is invalid, or project/local settings redirect the router profile. | Inspect `router.json`, remove project/local `HOME` or `CLAUDE_CONFIG_DIR` overrides, or run the [migration command](configuration.md#convert-an-older-routerjson). |
@@ -56,6 +56,7 @@ import {
56
56
  import { clip, observedActivity, promptIndex } from '../lib/facts.mjs';
57
57
  import { renderPanel, routeDraftOf, routingChanges } from '../lib/panel.mjs';
58
58
  import {
59
+ canMoveUp,
59
60
  cellForModel,
60
61
  chooseRoute,
61
62
  continueRoute,
@@ -64,6 +65,7 @@ import {
64
65
  isNativeFallback,
65
66
  isSameModel,
66
67
  nativeFacts,
68
+ observedMove,
67
69
  observeResponse,
68
70
  prepareLoop,
69
71
  resetHistory,
@@ -178,6 +180,8 @@ function createRouter(options) {
178
180
  // Each routed turn's activity record until turn.complete adds it to the stats, and the session's open run of
179
181
  // one activity, flushed to the store when it ends.
180
182
  turnActivities: new Map(),
183
+ // Each turn's classifier review in flight or answered (reviewMidTurn): `{ controller, generation, observedUpTo, answer }`.
184
+ reviews: new Map(),
181
185
  run: null,
182
186
  // The route a cheaper activity move went to, while the turns stay on it (advanceDown); else null.
183
187
  afterDown: null,
@@ -691,6 +695,124 @@ async function decideTurn($, router, e, signal, step) {
691
695
  }
692
696
  }
693
697
 
698
+ // Facts for a step of the running turn, read from the transcript as it is now.
699
+ function stepFacts(cfg, router, loop, e, messages, context) {
700
+ return nativeFacts(cfg, loop, {
701
+ messages,
702
+ prompt: router.prompts.get(e.turnId),
703
+ effort: e.effort,
704
+ turnId: e.turnId,
705
+ contextTokens: context.tokens,
706
+ });
707
+ }
708
+
709
+ // The transcript, or null when it cannot be read: a continuation then keeps its route.
710
+ async function transcript($) {
711
+ try {
712
+ return await $.session.messages({ as: 'api' });
713
+ } catch {
714
+ return null;
715
+ }
716
+ }
717
+
718
+ // A tool continuation whose turn shows stronger work than its route was chosen for moves up once (observedMove). Only
719
+ // tool calls after the last applied review count (`loop.observedFrom`): the review judged the ones before. The
720
+ // transcript is read only when some activity's route at this tier is stronger than the running one.
721
+ async function moveOnObserved($, router, cfg, loop, e, context) {
722
+ if (!canMoveUp(cfg, loop.decision, e.effort)) return loop;
723
+ const messages = await transcript($);
724
+ if (!messages) return loop;
725
+ const facts = stepFacts(cfg, router, loop, e, messages, context);
726
+ const observed = observedActivity(messages, Math.max(promptIndex(messages), (loop.observedFrom ?? 0) - 1));
727
+ const moved = observedMove(cfg, loop, { observed, facts, contextKnown: context.known, now: Date.now() });
728
+ if (moved === loop) return loop;
729
+ $.ui.toast(switchToast(cfg, loop.decision, moved.decision, moved.decision.estimate));
730
+ // Replies from here on are labelled with the moved activity; the classifier's answer stays as recorded.
731
+ const turn = router.turnActivities.get(e.turnId);
732
+ if (turn) router.turnActivities.set(e.turnId, { ...turn, label: moved.decision.activity });
733
+ await updateView($, router, { estimate: moved.decision.estimate ?? null, comparison: null });
734
+ return moved;
735
+ }
736
+
737
+ // Inside a turn the classifier is asked again every `policy.reviewEveryRequests` requests, in the background: a step
738
+ // never waits for it. The answer applies at the first step after it arrives, as a decision on the same task
739
+ // (sameTaskOf), so the tier and the activity can move either way: up on the usual votes, down only past the dwell and a
740
+ // passed verification. Pinned turns and a native fallback are left alone; a failed read or ask changes nothing.
741
+ async function reviewMidTurn($, router, cfg, loop, e, { context, nativeModel, availableModels }) {
742
+ const review = router.reviews.get(e.turnId);
743
+ if (review?.answer) {
744
+ router.reviews.delete(e.turnId);
745
+ // An answer about a history that compaction or a rewind replaced is dropped.
746
+ if (!review.answer.advice || loop.decision?.pinned || review.generation !== loop.generation) return loop;
747
+ // Only the advice is from the review; the checkpoint, context and cache facts are read now.
748
+ const messages = await transcript($);
749
+ if (!messages) return loop;
750
+ const advice = review.answer.advice;
751
+ const facts = { ...stepFacts(cfg, router, loop, e, messages, context), midTurn: true };
752
+ const selected = chooseRoute(cfg, loop, {
753
+ facts,
754
+ advice,
755
+ pin: null,
756
+ nativeModel,
757
+ contextKnown: context.known,
758
+ availableModels,
759
+ now: Date.now(),
760
+ });
761
+ const previous = loop.decision;
762
+ if (previous && (previous.model !== selected.decision.model || previous.effort !== selected.decision.effort)) {
763
+ $.ui.toast(switchToast(cfg, previous, selected.decision, selected.decision.estimate));
764
+ const turn = router.turnActivities.get(e.turnId);
765
+ if (turn) router.turnActivities.set(e.turnId, { ...turn, label: selected.decision.activity ?? null });
766
+ }
767
+ // The pane shows the readings behind the route; a review by a classifier the pane no longer labels keeps them off.
768
+ if (cfg.classifier === router.config.classifier)
769
+ await updateView($, router, {
770
+ comparison: selected.decision.comparison,
771
+ adviceChoice: advice.choice ?? null,
772
+ probabilities: advice.probabilities ?? null,
773
+ estimate: selected.decision.estimate ?? null,
774
+ activityChoice: advice.activity?.choice ?? null,
775
+ activityProbabilities: advice.activity?.probabilities ?? null,
776
+ });
777
+ // Tool calls up to the review's snapshot were judged by it; later ones can still move the route up.
778
+ return { ...selected, observedFrom: review.observedUpTo };
779
+ }
780
+ const every = cfg.policy.reviewEveryRequests;
781
+ if (review || every === 0 || !loop.decision?.tier || loop.decision.pinned) return loop;
782
+ if ((loop.requests ?? 0) - (loop.reviewedAt ?? 0) < every) return loop;
783
+ const job = { controller: new AbortController(), generation: loop.generation, observedUpTo: 0, answer: null };
784
+ router.reviews.set(e.turnId, job);
785
+ try {
786
+ const [credentials, messages] = await Promise.all([
787
+ resolveCredentials(activeClassifier(cfg), (name) => settingOf($, router.options, name)),
788
+ $.session.messages({ as: 'api' }),
789
+ ]);
790
+ job.observedUpTo = messages.length;
791
+ const facts = stepFacts(cfg, router, loop, e, messages, context);
792
+ clientOf(router, cfg.classifier)
793
+ .ask({
794
+ request: (url, init) => $.http.fetch(url, init),
795
+ sleep: (ms, args) => $.clock.sleep(ms, args),
796
+ config: cfg,
797
+ apiKey: credentials.apiKey,
798
+ endpoint: credentials.endpoint,
799
+ prompt: facts.prompt,
800
+ turns: facts.turns,
801
+ signal: job.controller.signal,
802
+ })
803
+ .then((answer) => {
804
+ if (router.reviews.get(e.turnId) === job) job.answer = answer;
805
+ })
806
+ .catch(() => {
807
+ if (router.reviews.get(e.turnId) === job) router.reviews.delete(e.turnId);
808
+ });
809
+ } catch {
810
+ router.reviews.delete(e.turnId);
811
+ return loop;
812
+ }
813
+ return { ...loop, reviewedAt: loop.requests ?? 0 };
814
+ }
815
+
694
816
  // A routed reply's metrics in the view, labelled with the turn's activity when its tier served it, and added to the
695
817
  // turn's activity record with its list price (`routedUsd`, null when unpriced) and, when its tier served it, its route.
696
818
  async function publishReply($, router, turnId, response, tier, route, routedUsd) {
@@ -1274,6 +1396,8 @@ async function endSession($, router) {
1274
1396
  router.turnConfigs.clear();
1275
1397
  router.turnPins.clear();
1276
1398
  router.turnActivities.clear();
1399
+ for (const review of router.reviews.values()) review.controller.abort();
1400
+ router.reviews.clear();
1277
1401
  router.turnSavings.clear();
1278
1402
  const run = router.run;
1279
1403
  router.run = null;
@@ -1438,6 +1562,9 @@ export function register(on, options) {
1438
1562
  loop = selected.loop;
1439
1563
  loopVersion = selected.version;
1440
1564
  } else {
1565
+ // A review answer applies first, so tool calls made after its snapshot can still move the route up.
1566
+ loop = await reviewMidTurn($, router, cfg, loop, e, { context, nativeModel, availableModels });
1567
+ loop = await moveOnObserved($, router, cfg, loop, e, context);
1441
1568
  loop = continueRoute(cfg, loop, {
1442
1569
  nativeModel,
1443
1570
  contextTokens: context.tokens,
@@ -1468,6 +1595,8 @@ export function register(on, options) {
1468
1595
  }
1469
1596
  router.turnConfigs.delete(e.turnId);
1470
1597
  router.turnPins.delete(e.turnId);
1598
+ router.reviews.get(e.turnId)?.controller.abort();
1599
+ router.reviews.delete(e.turnId);
1471
1600
  router.turnControllers.get(e.turnId)?.abort();
1472
1601
  if (router.view?.activeTurnId === e.turnId && router.view.phase === 'choosing') {
1473
1602
  router.view = { ...router.view, activeTurnId: null };
package/lib/activity.mjs CHANGED
@@ -2,7 +2,7 @@
2
2
  // compare, and when a route change inside one tier is worth it. Pure.
3
3
  import { ACTIVITIES, EFFORTS, resolveRoute, routeSpec } from './config.mjs';
4
4
  import { routeEffort } from './cost.mjs';
5
- import { cashGate } from './policy.mjs';
5
+ import { cashGate, sameTaskOf } from './policy.mjs';
6
6
 
7
7
  // The classifier's activity when it names one with at least `policy.activityMass`, else null: uncertain, a weak
8
8
  // label, or no answer resolve to the tier's base route.
@@ -34,18 +34,20 @@ export const sameRequest = (config, a, b, sentEffort) =>
34
34
 
35
35
  // The activity a turn runs with, given the incumbent cell `{ tier, activity }` and its resolved `route`. Without
36
36
  // advice, or without an activity answer (a skipped, failed or malformed activity step), the incumbent's activity
37
- // stays: a flaky step must not move the route every turn. A tool continuation keeps one route per task, but may move
38
- // up (explore, then code): a weaker label never takes over mid-task.
39
- export function chooseActivity(config, advice, incumbent, sentEffort) {
37
+ // stays: a flaky step must not move the route every turn. On the same task (sameTaskOf: a review inside a turn, or a
38
+ // continuation prompt) a stronger label is taken at once (explore, then code), and a weaker one only with at least
39
+ // `downgradeMass` probability once facts.downAllowed holds: the dwell has passed and a verification passed since the
40
+ // last model change. An unclear label keeps the running activity.
41
+ export function chooseActivity(config, advice, incumbent, sentEffort, facts = {}) {
40
42
  if (!advice?.activity) return incumbent.activity;
41
- if (advice.continuation >= config.policy.continuationMass) {
42
- const label = advice.activity.choice;
43
- const stronger =
44
- ACTIVITIES.includes(label) &&
45
- compareRoutes(config, resolveRoute(config, incumbent.tier, label), incumbent.route, sentEffort) > 0;
46
- return stronger ? label : incumbent.activity;
47
- }
48
- return acceptActivity(config, advice);
43
+ if (!sameTaskOf(config, advice, facts)) return acceptActivity(config, advice);
44
+ const label = advice.activity.choice;
45
+ if (!ACTIVITIES.includes(label)) return incumbent.activity;
46
+ const order = compareRoutes(config, resolveRoute(config, incumbent.tier, label), incumbent.route, sentEffort);
47
+ if (order > 0) return label;
48
+ const mass = advice.activity.probabilities?.[label] ?? 0;
49
+ if (order < 0 && facts.downAllowed && mass >= config.policy.downgradeMass) return label;
50
+ return incumbent.activity;
49
51
  }
50
52
 
51
53
  // A route change inside the incumbent's tier, `from` → `to`. Up on evidence: `mass`, the label's probability (1 for
package/lib/config.mjs CHANGED
@@ -115,6 +115,12 @@ export const DEFAULTS = {
115
115
  downgradeHorizonTurns: 5, // turns whose output and read savings offset a downgrade's cache write
116
116
  continuationMass: 0.7,
117
117
  escalationHoldTurns: 2,
118
+ // Inside a turn the classifier is asked again every this many requests, in the background; 0 turns it off. The
119
+ // answer applies at a later step, so a step never waits for it. Not tuned yet.
120
+ reviewEveryRequests: 4,
121
+ // A move to a cheaper route on the same task waits this many requests after the last model change, and for a
122
+ // verification command (tests, build, lint) that passed since then. Not tuned yet.
123
+ minDwellRequests: 8,
118
124
  // Ceiling on a cold cache write to a `credits` model. No default model bills credits, so this is
119
125
  // inert until a user adds one in router.json; a Claude Code turn starts near 100k tokens.
120
126
  cashCapUsd: 2,
@@ -153,6 +159,14 @@ export const DEFAULTS = {
153
159
  keyOption: 'cloudflare_api_token',
154
160
  timeoutMs: 3000,
155
161
  },
162
+ 'clef-omni': {
163
+ label: 'Clef Omni',
164
+ api: 'system-one',
165
+ endpoint: 'https://api.cloudflare.com/client/v4/accounts/{cloudflare_account_id}/ai/run/@cf/cloudflare/clef-omni',
166
+ model: 'clef-omni',
167
+ keyOption: 'cloudflare_api_token',
168
+ timeoutMs: 3000,
169
+ },
156
170
  openai: {
157
171
  label: 'OpenAI',
158
172
  api: 'openai-decisions',
@@ -529,6 +543,9 @@ function validate(config) {
529
543
  for (const field of ['upgradeVotes', 'downgradeVotes', 'downgradeHorizonTurns', 'escalationHoldTurns']) {
530
544
  if (!isNumber(p[field], 1, { integer: true })) throw new Error(`policy.${field} must be a positive integer`);
531
545
  }
546
+ for (const field of ['reviewEveryRequests', 'minDwellRequests']) {
547
+ if (!isNumber(p[field], 0, { integer: true })) throw new Error(`policy.${field} must be a non-negative integer`);
548
+ }
532
549
  // The pivot divides: tax / (tax + pivot). Zero makes a free switch NaN and silently stops that switch.
533
550
  for (const side of ['upgrade', 'downgrade']) {
534
551
  if (!isNumber(p[`${side}Slope`], 0)) throw new Error(`policy.${side}Slope must be a non-negative number`);
package/lib/display.mjs CHANGED
@@ -59,13 +59,13 @@ export const REASONS = {
59
59
  ready: 'ready for the next turn',
60
60
  'same-tier': 'the task fits the current tier',
61
61
  'no-advice': 'keeping the current model without classifier advice',
62
- continuation: 'continuing the previous task',
63
62
  uncertain: 'the classifier could not justify a change',
64
63
  upgrade: 'enough support for a stronger model',
65
64
  jump: 'clear need for a stronger model',
66
65
  downgrade: 'enough support for a cheaper model',
67
66
  'upgrade-pending': 'waiting before upgrading',
68
67
  'downgrade-pending': 'switching is not justified yet',
68
+ 'downgrade-held': 'a cheaper model waits for a passed check on this task',
69
69
  hold: 'staying after an escalation',
70
70
  escalation: 'repeated tool failures need a stronger model',
71
71
  'cash-gate': 'estimated cold cache write exceeds the cap',
@@ -129,13 +129,13 @@ export const SHORT_REASONS = {
129
129
  ready: 'ready',
130
130
  'same-tier': '= fits',
131
131
  'no-advice': '= no advice',
132
- continuation: '→ continuing',
133
132
  uncertain: '= uncertain',
134
133
  upgrade: '↑ upgrade',
135
134
  jump: '↑ jump',
136
135
  downgrade: '↓ downgrade',
137
136
  'upgrade-pending': '… waiting to go up',
138
137
  'downgrade-pending': '… waiting to go down',
138
+ 'downgrade-held': '… down after a passed check',
139
139
  hold: '= holding',
140
140
  escalation: '↑ tool errors',
141
141
  'cash-gate': '= cash cap',
@@ -202,7 +202,7 @@ function activityRouteText(config, view) {
202
202
  }
203
203
 
204
204
  // Reasons that only say the route stayed: on an override cell they leave out why it is not the tier's base route.
205
- const STAYED = ['ready', 'same-tier', 'no-advice', 'continuation', 'uncertain'];
205
+ const STAYED = ['ready', 'same-tier', 'no-advice', 'uncertain', 'downgrade-held'];
206
206
 
207
207
  // The Now tab's Why. In `on`, an activity move, or a stay on an override cell, says the cell plainly: "coding at low
208
208
  // runs on Sonnet 5.5 · high", or for a move to no activity "low runs on its base route, Haiku 5.5 · high".
package/lib/facts.mjs CHANGED
@@ -147,3 +147,85 @@ function readsOnly(command) {
147
147
  return name === 'git' ? READ_GIT.has(sub) : READ_COMMANDS.has(name);
148
148
  });
149
149
  }
150
+
151
+ // A command whose success shows that a check passed: a checker run, or a launcher whose subcommand names a check
152
+ // (`npm test`, `npm run lint`, `go test`, `make lint`, `uv run pytest`, `python -m pytest`, `node --test`), alone or in an
153
+ // `&&` list, so the command's status is the check's. A pipeline, `;`, `||` or background job can hide a failed check,
154
+ // so none of them counts. Neither do package names, paths and file names: `npm install -D vitest`, `git diff test/x.mjs`.
155
+ const CHECKERS = new Set(['pytest', 'jest', 'vitest', 'mocha', 'tsc', 'eslint', 'biome', 'ruff', 'mypy', 'pyright']);
156
+ const LAUNCHERS = new Set([
157
+ 'npm',
158
+ 'pnpm',
159
+ 'yarn',
160
+ 'bun',
161
+ 'npx',
162
+ 'bunx',
163
+ 'uv',
164
+ 'uvx',
165
+ 'poetry',
166
+ 'cargo',
167
+ 'go',
168
+ 'make',
169
+ 'just',
170
+ 'gradle',
171
+ 'gradlew',
172
+ 'mvn',
173
+ 'dotnet',
174
+ 'swift',
175
+ 'deno',
176
+ 'node',
177
+ 'python',
178
+ 'python3',
179
+ 'tox',
180
+ ]);
181
+ const RUNS = new Set(['run', 'exec', 'x', 'dlx']);
182
+ const CHECK_WORD =
183
+ /\b(?:test|tests|pytest|jest|vitest|mocha|tsc|typecheck|lint|eslint|biome|ruff|mypy|pyright|clippy|build|check|validate)\b/;
184
+
185
+ function verifies(command) {
186
+ if (typeof command !== 'string') return false;
187
+ const bare = command.replace(/'[^']*'|"[^"]*"/g, '""').replace(/\d?>\s*&\d|\d?>\s*\/dev\/null/g, '');
188
+ const steps = bare.split('&&');
189
+ if (steps.some((step) => /\|\||[;|&\n]/.test(step))) return false;
190
+ return steps.some((step) => runsCheck(step.trim().split(/\s+/)));
191
+ }
192
+
193
+ // A version or help request runs no check.
194
+ const INFO = /^(?:--version|-V|--help|-h|help|version)$/;
195
+
196
+ // An option before the subcommand may take a value (`npm --prefix test install`), so the subcommand must come first;
197
+ // `python -m` is the one option form read. Anything else unrecognised does not count.
198
+ function runsCheck(words) {
199
+ while (words.length > 1 && /^\w+=/.test(words[0])) words.shift();
200
+ const [first, ...rest] = words;
201
+ const name = first.split('/').pop();
202
+ if (rest.some((w) => INFO.test(w))) return false;
203
+ if (CHECKERS.has(name)) return true;
204
+ if (!LAUNCHERS.has(name)) return false;
205
+ if (rest.some((w) => /^--test\b/.test(w))) return true;
206
+ let args = (name === 'python' || name === 'python3') && rest[0] === '-m' ? rest.slice(1) : rest;
207
+ if (RUNS.has(args[0])) args = args.slice(1);
208
+ const sub = args[0] ?? '';
209
+ return !sub.startsWith('-') && !sub.includes('/') && !/\.\w+$/.test(sub) && CHECK_WORD.test(sub);
210
+ }
211
+
212
+ // Whether the last verification command at or after message `fromIndex` passed: the progress checkpoint a move to a
213
+ // cheaper route on the same task waits for. False when none ran since, or the last one failed (an unresolved failure),
214
+ // or it went to the background, by request or after a timeout: its result reports the launch, not the check.
215
+ export function verifiedSince(messages, fromIndex) {
216
+ let last = null;
217
+ for (let i = Math.max(0, fromIndex); i < messages.length; i += 1)
218
+ if (messages[i]?.role === 'assistant')
219
+ for (const block of blocks(messages[i].content))
220
+ if (block.type === 'tool_use' && block.name === 'Bash' && verifies(block.input?.command))
221
+ last = { id: block.id, index: i, background: block.input?.run_in_background === true };
222
+ if (!last || last.background) return false;
223
+ for (let i = last.index + 1; i < messages.length; i += 1)
224
+ for (const block of blocks(messages[i]?.content))
225
+ if (block.type === 'tool_result' && block.tool_use_id === last.id)
226
+ return !block.is_error && !BACKGROUNDED.test(textOf(blocks(block.content)));
227
+ return false;
228
+ }
229
+
230
+ // What Claude Code's Bash tool returns for a command it moved to the background.
231
+ const BACKGROUNDED = /running in background|moved to the background/i;