@alexeiled/claude-router 1.20.1 → 1.21.1

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/lib/config.mjs CHANGED
@@ -1,5 +1,6 @@
1
1
  // Defaults, user overrides and validation. Pure: callers pass env and the parsed user file.
2
2
 
3
+ import { listPrice } from './prices.mjs';
3
4
  import { executionDefaults, providerName } from './providers.mjs';
4
5
 
5
6
  export const TIERS = ['micro', 'low', 'medium', 'high'];
@@ -28,7 +29,8 @@ export const DEFAULTS = {
28
29
  // Haiku 5.5 is the worker at `low` and `micro`: at high effort it scored above Sonnet 5.5 at low, and at xhigh near
29
30
  // Sonnet at medium, for a fraction of the cost per attempt (Anthropic's OSWorld 2.1 effort chart: computer use, not
30
31
  // coding). Opus 5.5 at medium matched or beat Sonnet 5.5 at xhigh at 25-50% lower cost per task on Terminal-Bench
31
- // 4.0, FrontierCode v1.1 and CursorBench 4.0 (anthropic.com/claude-sonnet-5-5). `high` is Opus 5.5 at xhigh, the
32
+ // 4.0, FrontierCode v1.1 and CursorBench 4.0 (anthropic.com/claude-sonnet-5-5); Artificial Analysis v5.0.1 puts it
33
+ // just below (index 48.2 vs 49.9) at 60% of the cost per task, and Opus at high above. `high` is Opus 5.5 at xhigh, the
32
34
  // strongest setting this router asks for. These are routing defaults, not a claim of equal model quality.
33
35
  routes: {
34
36
  high: { model: 'opus', effort: 'xhigh' },
@@ -66,38 +68,31 @@ export const DEFAULTS = {
66
68
  // The classifier's probability of `high` a task needs to run on `heavy`.
67
69
  heavyMass: 0.8,
68
70
  },
69
- // `id` selects the native model. List prices in USD per million tokens; `cacheRead` is absolute,
70
- // not a multiplier (Opus 5.5 reads at 0.05x input, the rest at the standard 0.1x). `longContext` multiplies every
71
- // rate of a request whose prompt (input, cache read and cache write) is over `above` tokens: Haiku 5.5 lists its
72
- // rates for prompts up to 100,000 tokens and 5x above. A price change must also change
73
- // test/fixtures/list-prices.json, with its source and date. `output` feeds the downgrade tax.
71
+ // `id` selects the native model. List prices (USD per million tokens) come from prices.mjs, which the price check
72
+ // keeps in step with each vendor's page. `cacheRead` is absolute, not a multiplier (Opus 5.5 and Sonnet 5.5 read at
73
+ // 0.05x input, Haiku 5.5 at the standard 0.1x). `longContext` multiplies every rate of a request whose prompt
74
+ // (input, cache read and cache write) is over `above` tokens; `offPeak` multiplies them outside the peak hours.
75
+ // `output` feeds the downgrade tax.
74
76
  // `efforts` lists what the model accepts; an empty list means no effort field and no adaptive thinking. A change
75
77
  // must also change test/fixtures/effort-support.json, from a new probe against the real API.
76
78
  models: {
77
79
  opus: {
78
80
  id: 'claude-opus-5-5',
79
- input: 4,
80
- output: 20,
81
- cacheRead: 0.2,
81
+ ...listPrice('claude-opus-5-5'),
82
82
  contextWindow: 1_000_000,
83
83
  billing: 'plan',
84
84
  efforts: EFFORTS,
85
85
  },
86
86
  sonnet: {
87
87
  id: 'claude-sonnet-5-5',
88
- input: 2,
89
- output: 10,
90
- cacheRead: 0.2,
88
+ ...listPrice('claude-sonnet-5-5'),
91
89
  contextWindow: 1_000_000,
92
90
  billing: 'plan',
93
91
  efforts: EFFORTS,
94
92
  },
95
93
  haiku: {
96
94
  id: 'claude-haiku-5-5',
97
- input: 0.1,
98
- output: 0.5,
99
- cacheRead: 0.01,
100
- longContext: { above: 100_000, multiplier: 5 },
95
+ ...listPrice('claude-haiku-5-5'),
101
96
  contextWindow: 1_000_000,
102
97
  billing: 'plan',
103
98
  efforts: EFFORTS,
@@ -141,7 +136,12 @@ export const DEFAULTS = {
141
136
  // those fields of `policy` while it is active. The values started as codex-router's presets. 1.16 sets cost's upgrade
142
137
  // bar to balanced's (2 votes from 0.75): from 3 votes at 0.85 the bar, raised by the cache write of a cold stronger
143
138
  // model, sat at 0.92 from 60k tokens and 0.97 at 254k, so a cost turn on Haiku kept a task the classifier scored
144
- // hard at 90%. Cost still moves down sooner. Not tuned on outcomes yet.
139
+ // hard at 90%. Cost still moves down sooner. 1.21.1 lowers cost's downgrade bar: in 578 recorded cost decisions
140
+ // (one developer, Clef and Jev, ~430k-token contexts) the classifier chose `high` on 33% of answers but the router ran
141
+ // `high` on 58%, because none of the 136 answers for a lower tier cleared the ~0.87 bar a cold cheaper cache set.
142
+ // 0.65, not 0.6: an upgrade counts all mass above the incumbent, so a near-tie that moved two tiers up must not drop
143
+ // straight back to a warm cheaper cache.
144
+ // Not tuned on outcomes yet.
145
145
  mode: 'balanced',
146
146
  modes: {
147
147
  cost: {
@@ -150,7 +150,7 @@ export const DEFAULTS = {
150
150
  upgradeBase: 0.75,
151
151
  jumpConfidence: 0.98,
152
152
  downgradeVotes: 1,
153
- downgradeMass: 0.8,
153
+ downgradeMass: 0.65,
154
154
  minDwellRequests: 4,
155
155
  escalationHoldTurns: 1,
156
156
  },
@@ -236,6 +236,7 @@ const MODEL_KEYS = [
236
236
  'output',
237
237
  'cacheRead',
238
238
  'longContext',
239
+ 'offPeak',
239
240
  'contextWindow',
240
241
  'billing',
241
242
  'efforts',
@@ -546,6 +547,8 @@ function checkShape(file) {
546
547
  // null removes a built-in surcharge.
547
548
  if (model.longContext != null)
548
549
  checkObject(model.longContext, `models.${alias}.longContext`, ['above', 'multiplier']);
550
+ if (model.offPeak != null)
551
+ checkObject(model.offPeak, `models.${alias}.offPeak`, ['multiplier', 'peakDays', 'peakHoursUtc']);
549
552
  }
550
553
  }
551
554
  if (cache !== undefined) {
@@ -697,6 +700,18 @@ function validateModel(at, model) {
697
700
  throw new Error(`${at}.longContext.above must be a positive integer`);
698
701
  if (!isNumber(multiplier, 0, { above: true })) throw new Error(`${at}.longContext.multiplier must be positive`);
699
702
  }
703
+ if (model.offPeak != null) {
704
+ const { multiplier, peakDays, peakHoursUtc } = model.offPeak;
705
+ if (!isNumber(multiplier, 0, { above: true })) throw new Error(`${at}.offPeak.multiplier must be positive`);
706
+ if (!Array.isArray(peakDays) || peakDays.some((d) => !isNumber(d, 0, { integer: true }) || d > 6))
707
+ throw new Error(`${at}.offPeak.peakDays must list UTC weekdays 0-6`);
708
+ const hour = (h) => isNumber(h, 0, { integer: true }) && h <= 24;
709
+ if (
710
+ !Array.isArray(peakHoursUtc) ||
711
+ peakHoursUtc.some((r) => !Array.isArray(r) || r.length !== 2 || !hour(r[0]) || !hour(r[1]) || r[0] >= r[1])
712
+ )
713
+ throw new Error(`${at}.offPeak.peakHoursUtc must list [from, to) UTC hour ranges`);
714
+ }
700
715
  if (typeof model.id !== 'string' || !model.id) throw new Error(`${at}.id is required`);
701
716
  if (!['plan', 'credits'].includes(model.billing)) throw new Error(`${at}.billing must be plan or credits`);
702
717
  if (!Array.isArray(model.efforts) || model.efforts.some((e) => !EFFORTS.includes(e)))
package/lib/cost.mjs CHANGED
@@ -27,10 +27,23 @@ export function clampEffort(wanted, supported) {
27
27
  }
28
28
 
29
29
  // The one place a model's list prices become rates: per million tokens for a request whose prompt (input, cache read
30
- // and cache write) is `promptTokens`, with the model's long-context multiplier above its threshold. Every estimate
31
- // prices through here.
32
- export function ratesAt(model, promptTokens) {
33
- const k = model.longContext && promptTokens > model.longContext.above ? model.longContext.multiplier : 1;
30
+ // and cache write) is `promptTokens` at time `at`, with the model's long-context multiplier above its threshold and
31
+ // its off-peak multiplier outside peak hours. Every estimate prices through here.
32
+ // True when `at` (ms) falls outside the model's peak hours. An unknown time is peak: the higher bound.
33
+ export function isOffPeak(model, at) {
34
+ if (!model.offPeak || !Number.isFinite(at)) return false;
35
+ const time = new Date(at);
36
+ const hour = time.getUTCHours();
37
+ const peak =
38
+ model.offPeak.peakDays.includes(time.getUTCDay()) &&
39
+ model.offPeak.peakHoursUtc.some(([from, to]) => hour >= from && hour < to);
40
+ return !peak;
41
+ }
42
+
43
+ export function ratesAt(model, promptTokens, at) {
44
+ const k =
45
+ (model.longContext && promptTokens > model.longContext.above ? model.longContext.multiplier : 1) *
46
+ (isOffPeak(model, at) ? model.offPeak.multiplier : 1);
34
47
  return {
35
48
  input: model.input * k,
36
49
  cacheRead: model.cacheRead * k,
@@ -69,7 +82,7 @@ export function cacheState(state, now, cache) {
69
82
 
70
83
  // Bounds are scenarios, never an independent ledger. Unknown incumbent cache can still be served.
71
84
  export function inputBounds(config, route, tokens, facts, now) {
72
- const model = ratesAt(routeSpec(config, route), tokens);
85
+ const model = ratesAt(routeSpec(config, route), tokens, now);
73
86
  const state = facts.models[routeCacheKey(config, route, facts.effort)];
74
87
  const prefix = Math.min(state?.prefixTokens ?? tokens, tokens);
75
88
  const fresh = isWarm(state, now, config.cache);
@@ -87,9 +100,9 @@ export function inputBounds(config, route, tokens, facts, now) {
87
100
  };
88
101
  }
89
102
 
90
- export function coldWriteUsd(config, alias, tokens) {
103
+ export function coldWriteUsd(config, alias, tokens, now) {
91
104
  return (
92
- (ratesAt(config.models[alias], tokens).input *
105
+ (ratesAt(config.models[alias], tokens, now).input *
93
106
  (config.cache.mode === 'explicit' ? Math.max(...Object.values(config.cache.writeMultiplier)) : 1) *
94
107
  tokens) /
95
108
  1e6
@@ -112,7 +125,10 @@ export function nextTurnRange(config, candidate, incumbent, facts, now) {
112
125
  const tokens = nextContextTokens(facts);
113
126
  const proposed = inputBounds(config, candidate, tokens, facts, now);
114
127
  const current = inputBounds(config, incumbent, tokens, facts, now);
115
- const [to, from] = [ratesAt(routeSpec(config, candidate), tokens), ratesAt(routeSpec(config, incumbent), tokens)];
128
+ const [to, from] = [
129
+ ratesAt(routeSpec(config, candidate), tokens, now),
130
+ ratesAt(routeSpec(config, incumbent), tokens, now),
131
+ ];
116
132
  const outputTokens = facts.lastRequest?.outputTokens ?? 0;
117
133
  const output = to.output > 0 && from.output > 0 ? ((to.output - from.output) * outputTokens) / 1e6 : 0;
118
134
  return { minUsd: proposed.min - current.max + output, maxUsd: proposed.max - current.min + output };
@@ -121,8 +137,8 @@ export function nextTurnRange(config, candidate, incumbent, facts, now) {
121
137
  export function switchEconomics(config, candidate, incumbent, facts, now) {
122
138
  if (config.cache.mode === 'automatic') return null;
123
139
  const tokens = nextContextTokens(facts);
124
- const proposed = ratesAt(routeSpec(config, candidate), tokens);
125
- const current = ratesAt(routeSpec(config, incumbent), tokens);
140
+ const proposed = ratesAt(routeSpec(config, candidate), tokens, now);
141
+ const current = ratesAt(routeSpec(config, incumbent), tokens, now);
126
142
  if (!(proposed.output > 0) || !(current.output > 0)) return null;
127
143
  const outputTokens = facts.lastRequest?.outputTokens ?? 0;
128
144
  const output = ((proposed.output - current.output) * outputTokens) / 1e6;
package/lib/costs.mjs ADDED
@@ -0,0 +1,156 @@
1
+ // What a session cost and how it is paid, as one value the band, the pane and /router all read, so they show the same
2
+ // numbers at the same moment. Pure: the inputs are the period's usage summary (usage.mjs), its subagent summary
3
+ // (subagents.mjs), the configured models and Claude Code's plan windows.
4
+ //
5
+ // Every dollar is tokens at the router file's list prices. How that dollar is paid decides its label: on a Claude plan
6
+ // it is quota, an "API value" shown with ≈; with an API key or a provider's credits it is billed. "No routing" is what
7
+ // the same tokens cost without the router: your model on the main thread, Claude Code's pick for each subagent.
8
+
9
+ import { EFFORTS, TIERS } from './config.mjs';
10
+ import { modelSpec, readout } from './savings.mjs';
11
+ import { dayKey } from './usage.mjs';
12
+
13
+ // The plan windows Claude Code reports, in the order shown. `spend_limit` is a gateway's cap on billed spend, not a
14
+ // plan's quota.
15
+ const WINDOWS = [
16
+ ['five_hour', '5h'],
17
+ ['seven_day', '7d'],
18
+ ['spend_limit', 'spend'],
19
+ ];
20
+ const QUOTA = ['five_hour', 'seven_day'];
21
+
22
+ // The windows with a reading, `{ kind, label, percent, resetsAt }` (resetsAt in ms, or null), in WINDOWS order.
23
+ export function planLimits(usage) {
24
+ const limits = Array.isArray(usage?.rateLimits) ? usage.rateLimits : [];
25
+ return WINDOWS.flatMap(([kind, label]) => {
26
+ const limit = limits.find((l) => l?.kind === kind && Number.isFinite(l.percentUsed));
27
+ if (!limit) return [];
28
+ const resetsAt = Date.parse(limit.resetsAt ?? '');
29
+ return [{ kind, label, percent: limit.percentUsed, resetsAt: Number.isFinite(resetsAt) ? resetsAt : null }];
30
+ });
31
+ }
32
+
33
+ // How the session pays: `plan` (Claude plan quota), `mixed` (plan quota and provider credits), or `billed` (API key,
34
+ // gateway or credits). A plan shows itself only through its windows, which Claude Code reads from the first reply on:
35
+ // before that a plan session reads as billed, with nothing spent yet.
36
+ export function billingOf(config, usage) {
37
+ const models = Object.values(config.models);
38
+ const credits = models.some((m) => m.billing === 'credits');
39
+ const plan = models.some((m) => m.billing === 'plan');
40
+ if (!plan || !planLimits(usage).some((l) => QUOTA.includes(l.kind))) return 'billed';
41
+ return credits ? 'mixed' : 'plan';
42
+ }
43
+
44
+ // Whether every route runs one model, so routing only moves the effort. The savings estimate holds output length
45
+ // constant and cannot price an effort change, so such a profile shows its effort mix instead of a saving.
46
+ export function isEffortOnly(config) {
47
+ const cells = [
48
+ ...TIERS.map((tier) => config.routes[tier]),
49
+ ...(config.activityRouting === 'off' ? [] : Object.values(config.activities ?? {}).flatMap(Object.values)),
50
+ ].filter(Boolean);
51
+ return new Set(cells.map((route) => route.model)).size === 1;
52
+ }
53
+
54
+ const cents = (usd) => Math.round(usd * 100) / 100;
55
+ // A cell key ends with the route `id@effort` (usage.mjs replyEntry).
56
+ const routeOfCell = (key) => {
57
+ const route = key.slice(key.lastIndexOf('|') + 1);
58
+ const at = route.lastIndexOf('@');
59
+ return at < 0 ? { id: route, effort: null } : { id: route.slice(0, at), effort: route.slice(at + 1) || null };
60
+ };
61
+
62
+ // Replies by effort, in effort order: [[effort, replies]].
63
+ function effortMix(cells) {
64
+ const counts = {};
65
+ for (const [key, sums] of Object.entries(cells)) {
66
+ const { effort } = routeOfCell(key);
67
+ const name = effort ?? 'default';
68
+ counts[name] = (counts[name] ?? 0) + sums[0];
69
+ }
70
+ const rank = (e) => (EFFORTS.includes(e) ? EFFORTS.indexOf(e) : EFFORTS.length);
71
+ return Object.entries(counts)
72
+ .filter(([, n]) => n > 0)
73
+ .sort((a, b) => rank(a[0]) - rank(b[0]));
74
+ }
75
+
76
+ // Subagents in a period: how many ran, what they cost, and what the same tokens cost on Claude Code's picks. A
77
+ // pass-through ran on Claude Code's pick, so it costs the same with and without routing. A record from before 1.14.0
78
+ // keeps undated totals without a pick price: they count as unrouted.
79
+ export function agentCosts(config, summary) {
80
+ const out = { agents: 0, moved: 0, usd: 0, baseUsd: 0, creditsUsd: 0 };
81
+ for (const kind of ['routed', 'passed'])
82
+ for (const counts of Object.values(summary?.[kind] ?? {})) {
83
+ out.agents += counts.agents;
84
+ for (const [id, model] of Object.entries(counts.models)) {
85
+ out.usd += model.usd;
86
+ out.baseUsd += kind === 'routed' ? model.coreUsd : model.usd;
87
+ out.moved += model.moved ?? 0;
88
+ if (modelSpec(config, id)?.billing === 'credits') out.creditsUsd += model.usd;
89
+ }
90
+ }
91
+ if (summary?.undated) {
92
+ out.agents += summary.undated.agents;
93
+ out.usd += summary.undated.usd;
94
+ out.baseUsd += summary.undated.usd;
95
+ }
96
+ return out;
97
+ }
98
+
99
+ // The period's cost: `summary` from usage.mjs summarize, `agents` from subagents.mjs summarizeSubagents. `usage` is
100
+ // Claude Code's session usage: its plan windows tell how every period is paid.
101
+ export function periodCost(config, { summary, agents, usage = null }) {
102
+ const a = agentCosts(config, agents);
103
+ const r = readout(summary);
104
+ const effortOnly = isEffortOnly(config);
105
+ // A saving needs every main reply compared; effort-only profiles have none to show. Agents alone compare too: each
106
+ // has Claude Code's pick to price against.
107
+ const comparable = !effortOnly && (summary.replies > 0 || a.agents > 0) && !summary.observed.uncomparedReplies;
108
+ const mainUsd = cents(summary.observed.routedUsd);
109
+ const agentUsd = cents(a.usd);
110
+ const agentBaseUsd = cents(a.baseUsd);
111
+ const totalUsd = cents(mainUsd + agentUsd);
112
+ const mainDiff = comparable ? r.differenceUsd : null;
113
+ const agentDiff = cents(agentUsd - agentBaseUsd);
114
+ const baseUsd = comparable ? cents(r.yoursUsd + agentBaseUsd) : null;
115
+ const diffUsd = comparable ? cents(mainDiff + agentDiff) : null;
116
+ const billing = billingOf(config, usage);
117
+ let creditsUsd = null;
118
+ if (billing === 'mixed') {
119
+ let main = 0;
120
+ for (const [key, sums] of Object.entries(summary.observed.cells))
121
+ if (modelSpec(config, routeOfCell(key).id)?.billing === 'credits') main += sums[1];
122
+ creditsUsd = cents(main + a.creditsUsd);
123
+ }
124
+ return {
125
+ billing,
126
+ replies: summary.observed.replies,
127
+ agents: a.agents,
128
+ moved: a.moved,
129
+ mainUsd,
130
+ agentUsd,
131
+ agentBaseUsd,
132
+ totalUsd,
133
+ mainDiff,
134
+ agentDiff: agentUsd || agentBaseUsd ? agentDiff : null,
135
+ baseUsd,
136
+ diffUsd,
137
+ share: baseUsd > 0 ? diffUsd / baseUsd : null,
138
+ // A sample of main replies: agents alone are each priced against their own pick, not sampled.
139
+ early: r.early && summary.replies > 0,
140
+ readout: r,
141
+ comparable,
142
+ uncomparedReplies: summary.observed.uncomparedReplies,
143
+ effortOnly,
144
+ effortMix: effortMix(summary.observed.cells),
145
+ creditsUsd,
146
+ limits: planLimits(usage),
147
+ };
148
+ }
149
+
150
+ // "17:00" today, "Thu 09:00" on another day; null once the reset has passed, as the reading is then stale.
151
+ export function resetText(ms, now) {
152
+ if (!Number.isFinite(ms) || ms <= now) return null;
153
+ const date = new Date(ms);
154
+ const time = date.toLocaleTimeString('en-GB', { hour: '2-digit', minute: '2-digit' });
155
+ return dayKey(ms) === dayKey(now) ? time : `${date.toLocaleDateString('en-US', { weekday: 'short' })} ${time}`;
156
+ }
package/lib/display.mjs CHANGED
@@ -10,11 +10,13 @@ import {
10
10
  TIERS,
11
11
  } from './config.mjs';
12
12
  import { ratesAt } from './cost.mjs';
13
+ import { periodCost } from './costs.mjs';
13
14
  import { applyMode, modeLabel, modeRoute } from './modes.mjs';
14
15
  import { PROBE_RESULTS } from './probe-results.mjs';
15
16
  import { cellForModel } from './route.mjs';
16
- import { modelSpec, readout } from './savings.mjs';
17
- import { allTime, periodRange, readUsage, summarize, withReplies } from './usage.mjs';
17
+ import { modelSpec } from './savings.mjs';
18
+ import { readSubagentStore, summarizeSubagents } from './subagents.mjs';
19
+ import { periodRange, readUsage, summarize, withReplies } from './usage.mjs';
18
20
 
19
21
  // Cost order, cheapest first, so the colors read as a scale. Hex values: every surface draws them.
20
22
  export const TIER_COLOR = { micro: '#5fd7af', low: '#5f9fe0', medium: '#d7af5f', high: '#e0708a' };
@@ -178,48 +180,42 @@ const CLASSIFIER_ERRORS = {
178
180
  export const classifierWarns = (error) => CLASSIFIER_ERRORS[error]?.warn === true;
179
181
  // No error, or one outside the table, times the wait.
180
182
  export const classifierTimed = (error) => CLASSIFIER_ERRORS[error]?.timed !== false;
181
- // One or two words for the band; REASONS holds the sentence the pane shows.
183
+ // A glyph and at most three words for every reason: the band, the pane's Why, the switch toast and the subagent row
184
+ // say the same. The glyph is the direction: ↑ stronger, ↓ cheaper, = stays, … waits, ! fault, ⏵ pin. REASONS holds the
185
+ // sentence /router prints.
182
186
  export const SHORT_REASONS = {
183
187
  ready: 'ready',
184
188
  'same-tier': '= fits',
185
189
  'no-advice': '= no advice',
186
- uncertain: '= uncertain',
187
- upgrade: '↑ upgrade',
188
- jump: '↑ jump',
189
- downgrade: '↓ downgrade',
190
- 'upgrade-pending': '… waiting to go up',
191
- 'downgrade-pending': '… waiting to go down',
192
- 'downgrade-held': '… down after a checkpoint',
193
- hold: '= holding',
190
+ uncertain: '= unsure',
191
+ upgrade: '↑ needs stronger',
192
+ jump: '↑ clearly stronger',
193
+ downgrade: '↓ cheaper fits',
194
+ 'upgrade-pending': '… stronger, waiting',
195
+ 'downgrade-pending': '… cheaper, waiting',
196
+ 'downgrade-held': '… cheaper after a check',
197
+ hold: '= holding after ↑',
194
198
  escalation: '↑ tool errors',
195
- 'cash-gate': '= cash cap',
196
- 'context-fit': '↑ context',
199
+ 'cash-gate': '= cache cap',
200
+ 'context-fit': '↑ needs context',
197
201
  'context-unknown': '= context unknown',
198
202
  'context-full': '! context full',
199
203
  'model-unavailable': '! model unavailable',
200
204
  'native-fallback': '! fallback',
201
205
  pinned: '⏵ pinned',
202
- interrupted: 'interrupted',
203
- 'activity-up': '↗ {activity}',
204
- 'activity-down': '↘ {activity}',
205
- 'activity-pending': '… {activity}: not worth a switch',
206
+ manual: '= routing skipped',
207
+ 'routing off': 'routing off',
208
+ interrupted: '! interrupted',
209
+ 'activity-up': '↑ {activity}',
210
+ 'activity-down': '↓ {activity}',
211
+ 'activity-pending': '… {activity}, not worth a switch',
206
212
  };
207
213
 
208
- // What the band calls each activity: the verb for the work, as Claude Code names a turn's action.
209
- const ACTIVITY_VERB = {
210
- code: 'coding',
211
- debug: 'debugging',
212
- explore: 'exploring',
213
- plan: 'planning',
214
- review: 'reviewing',
215
- ops: 'running',
216
- docs: 'documenting',
217
- };
218
- export const activityVerb = (activity) => ACTIVITY_VERB[activity] ?? activity;
219
-
214
+ // Whether the band's words for `reason` already name the activity, so the activity is not said twice.
215
+ export const reasonNamesActivity = (reason) => SHORT_REASONS[reason]?.includes('{activity}') ?? false;
220
216
  // The band's words for `reason`; an activity move names the activity it is about, `base` for the tier's own route.
221
217
  export const shortReason = (reason, activity) =>
222
- (SHORT_REASONS[reason] ?? reason ?? '').replace('{activity}', activity ? activityVerb(activity) : 'base');
218
+ (SHORT_REASONS[reason] ?? reason ?? '').replace('{activity}', activity ?? 'base');
223
219
 
224
220
  // The activity a reason is about: the applied one for a move, and for a refused move the classifier's activity when
225
221
  // it carries enough mass to apply, else null (the tier's base route).
@@ -277,7 +273,7 @@ export function whyText(configured, view) {
277
273
  routeSpec(config, route).id === view.selectedModel && (route.effort === null || route.effort === view.effort);
278
274
  if (!moved && view.selectedModel && !runs) return reason;
279
275
  return activity
280
- ? `${activityVerb(activity)} at ${view.tier} runs on ${routeName(config, route)}`
276
+ ? `${activity} at ${view.tier} runs on ${routeName(config, route)}`
281
277
  : `${view.tier} runs on its base route, ${routeName(config, route)}`;
282
278
  }
283
279
 
@@ -321,7 +317,7 @@ export function probeText(config, id) {
321
317
  return `activity probe ${probe.correct}/${probe.probes} · p95 ${probe.p95Ms} ms · ${day}`;
322
318
  }
323
319
 
324
- // Routing vs your model: less is green, more is amber, not red: a stronger model is a purchase, not a fault.
320
+ // Routing vs no routing: less is green, more is amber, not red: a stronger model is a purchase, not a fault.
325
321
  export const SAVINGS_COLOR = { less: '#6fcf97', more: '#f0b429' };
326
322
 
327
323
  // "$6.40"; signed for a difference or a part: "−$1.84", "+$0.47", "$0.00".
@@ -329,23 +325,7 @@ export const usd = (value) => `$${Math.abs(value).toFixed(2)}`;
329
325
  export const signedUsd = (value) => (value === 0 ? '$0.00' : `${value < 0 ? '−' : '+'}${usd(value)}`);
330
326
  export const savingsColor = (value) => (value < 0 ? SAVINGS_COLOR.less : value > 0 ? SAVINGS_COLOR.more : undefined);
331
327
 
332
- // The difference against your model: "−22%", "+15%", or "×5.0" once routing cost twice your model or more. Null when
333
- // it rounds to nothing or there is nothing to compare.
334
- export function differenceShare(r) {
335
- if (r.differenceUsd === 0 || r.share === null) return null;
336
- if (r.ratio >= 2) return `×${r.ratio.toFixed(1)}`;
337
- const share = Math.round(r.share * 100);
338
- return share === 0 ? null : `${share < 0 ? '−' : '+'}${Math.abs(share)}%`;
339
- }
340
-
341
- // "−$1.84 (−22%)".
342
- export const savingsAmount = (r) => {
343
- const share = differenceShare(r);
344
- return `${signedUsd(r.differenceUsd)}${share ? ` (${share})` : ''}`;
345
- };
346
-
347
328
  export const yourModel = (view) => routeLabel(view.nativeModel, view.nativeEffort);
348
- export const sinceDate = (ms) => new Date(ms).toLocaleDateString('en-US', { month: 'short', day: 'numeric' });
349
329
  const replyCount = (n, what = 'replies') => `${n} ${n === 1 ? what.replace(/ies$/, 'y') : what}`;
350
330
 
351
331
  // A usage record with the running turns' replies (view.usageLive) added, which every readout counts: the band, the
@@ -354,13 +334,6 @@ export const liveUsage = (view, record) => withReplies(readUsage(record), view.u
354
334
  // This session's routed replies, the running turns' included.
355
335
  export const sessionUsage = (view, now) => summarize(liveUsage(view, view.usageSession), periodRange('session', now));
356
336
 
357
- // Every dollar amount is a reply's tokens at the router.json list prices, as if paid per token: on a Claude plan it
358
- // shows quota use in the same dollars as credits, so plan and credit models add up and compare.
359
- export const spentText = (value) => `${usd(value)} at API prices`;
360
- // What the replies cost is known even when a counterfactual cache history cannot be priced.
361
- export const observedUsageText = (observed) =>
362
- `${spentText(observed.routedUsd)} · ${replyCount(observed.replies)} · comparison unavailable`;
363
-
364
337
  // The models a session's replies were priced against, when they are not the one `/model` selects now: after a
365
338
  // `/model` change the record keeps each reply against the model selected when it ran. Null when they are.
366
339
  export function recordedModels(config, view, summary) {
@@ -372,45 +345,48 @@ export function recordedModels(config, view, summary) {
372
345
  // record kept them against.
373
346
  export const comparedModel = (config, view, summary) => recordedModels(config, view, summary) ?? yourModel(view);
374
347
 
375
- // The words every readout uses. Routing against your model: "routing −$1.84 (−22%)", minus less than your model, plus
376
- // more; then the parts that add up to it.
377
- export const routingAnswer = (r) => `routing ${savingsAmount(r)}`;
378
- export const COST_PART = { cheaper: 'cheaper models', stronger: 'stronger models', switches: 'cache rebuilds' };
379
- // The parts of a readout that are not zero, as [signed amount, words]: "−$2.31", "cheaper models".
380
- export function costParts(r) {
381
- return [
382
- [r.cheaperUsd, COST_PART.cheaper],
383
- [r.strongerUsd, COST_PART.stronger],
384
- [r.switchUsd, COST_PART.switches],
385
- ]
386
- .filter(([value]) => value !== 0)
387
- .map(([value, words]) => [signedUsd(value), words, value]);
348
+ // What the cost is compared with, the same word on the band, the pane and /router: the one model the main replies
349
+ // were priced against (the one `/model` selected when they ran), else `unrouted` (after a `/model` change, or with
350
+ // subagents, which are priced against Claude Code's pick).
351
+ export const UNROUTED = 'unrouted';
352
+ export function baselineName(view, summary, cost) {
353
+ const ids = Object.keys(summary.yours ?? {});
354
+ const id = ids.length ? ids[0] : view.nativeModel;
355
+ return cost.agents || ids.length > 1 || !id ? UNROUTED : modelName(id);
388
356
  }
357
+ // Under EARLY_REPLIES main replies one model switch and its cache write can decide the difference: "9 replies so far".
358
+ export const repliesText = (cost) =>
359
+ `${replyCount(cost.replies)}${cost.early && cost.diffUsd !== null ? ' so far' : ''}`;
360
+ export const EARLY_NOTE = 'one model switch can still move this a lot';
361
+
389
362
  // Cache rebuilds cost more than the cheaper models saved: the switches lost money.
390
363
  export const switchesLost = (r) => r.switchUsd > 0 && r.switchUsd > -r.cheaperUsd;
391
364
 
392
- // The `/router` line without a surface: this session's readout, or why there is none yet, with the saved totals
393
- // when this session has no routed reply.
394
- export function savingsLine(config, view, now) {
395
- const summary = sessionUsage(view, now);
396
- const session = readout(summary);
397
- if (summary.observed.uncomparedReplies)
398
- return `Session: ${observedUsageText(summary.observed)}${session.replies ? `; ${replyCount(session.replies)} comparable only: ${routingAnswer(session)}` : ''}`;
399
- const label = `vs ${comparedModel(config, view, summary)}`;
400
- if (!session.replies) {
401
- const kept = allTime(view.usageStore, view.savingsStore);
402
- const across = readout(kept.totals);
403
- if (kept.observed.uncomparedReplies)
404
- return `Session ${label}: no routed replies yet; across sessions ${observedUsageText(kept.observed)}`;
405
- const saved = across.early
406
- ? ''
407
- : `; ${routingAnswer(across)} since ${sinceDate(kept.since)}, each session against its own model`;
408
- return `Session ${label}: no routed replies yet${saved}`;
409
- }
410
- if (session.early)
411
- return `Session: ${routingAnswer(session)} ${label}, ${spentText(session.routedUsd)}, ${replyCount(session.replies)}, early sample`;
412
- const parts = costParts(session).map(([amount, words]) => `${amount} ${words}`);
413
- return `Session: ${routingAnswer(session)} ${label}${parts.length ? ` = ${parts.join(' ')}` : ''}, ${spentText(session.routedUsd)}, ${replyCount(session.replies)}`;
365
+ // The `/router` lines without a surface, in the band's and pane's words and numbers: the plan windows, then this
366
+ // session's cost with its subagents against no routing.
367
+ // "3 of 20 replies have no comparison", or "no reply has a comparison" when none has.
368
+ export const uncomparedText = (cost) =>
369
+ cost.uncomparedReplies === cost.replies
370
+ ? 'no reply has a comparison'
371
+ : `${cost.uncomparedReplies} of ${cost.replies} replies have no comparison`;
372
+
373
+ export function savingsLine(config, view, usage, now) {
374
+ const cost = sessionCost(config, view, usage, now);
375
+ const plan = cost.limits.map((l) => `${l.label} ${l.percent}%`).join(' · ');
376
+ const lines = plan ? [`Plan: ${plan}`] : [];
377
+ if (!cost.replies && !cost.agents) return [...lines, 'Session: no routed replies yet'].join('\n');
378
+ const split = cost.agents ? ` (main ${usd(cost.mainUsd)} + agents ${usd(cost.agentUsd)})` : '';
379
+ const credits = cost.creditsUsd ? ` · billed ${usd(cost.creditsUsd)}` : '';
380
+ const versus =
381
+ cost.diffUsd !== null
382
+ ? ` · ${diffText(cost.diffUsd, cost.baseUsd)} vs ${baselineName(view, sessionUsage(view, now), cost)} ${costText(cost.baseUsd, cost.billing)}`
383
+ : cost.effortOnly
384
+ ? ` · effort ${cost.effortMix.map(([effort, n]) => `${effort} ${n}`).join(' · ')}`
385
+ : ` · ${uncomparedText(cost)}`;
386
+ lines.push(
387
+ `Session: ${costText(cost.totalUsd, cost.billing)} ${BILLING_WORDS[cost.billing]}${split}${credits}${versus} · ${repliesText(cost)}`,
388
+ );
389
+ return lines.join('\n');
414
390
  }
415
391
 
416
392
  export const GATEWAY_SETTINGS = 'v0.8 gateway settings remain · see /router';
@@ -452,7 +428,6 @@ export function usageMetrics(config, view, usage) {
452
428
  );
453
429
  const nextContext = candidates.length ? Math.max(...candidates) : null;
454
430
  const reuse = view.inputTokens > 0 && Number.isFinite(view.cacheRead) ? view.cacheRead / view.inputTokens : null;
455
- const cost = Number.isFinite(usage?.cost?.usd) ? usage.cost.usd : null;
456
431
  const rates = spec && ratesAt(spec, view.inputTokens ?? 0);
457
432
  const cacheBenefit =
458
433
  rates && Number.isFinite(view.cacheRead) ? ((rates.input - rates.cacheRead) * view.cacheRead) / 1e6 : null;
@@ -461,7 +436,6 @@ export function usageMetrics(config, view, usage) {
461
436
  observed,
462
437
  nextContext,
463
438
  reuse,
464
- cost,
465
439
  cacheBenefit,
466
440
  contextBar: bar(nextContext, window),
467
441
  cacheBar: {
@@ -480,3 +454,52 @@ export function sparkline(values) {
480
454
  const span = Math.max(...values) - minimum;
481
455
  return values.map((value) => symbols[span > 0 ? Math.round(((value - minimum) / span) * 7) : 3]).join('');
482
456
  }
457
+
458
+ // "Haiku" for Haiku 5.5, "GLM Flash" for GLM 5.3 Flash, "Kimi Pro" for Kimi K3.1 Pro: a model's name without its
459
+ // version, for the pins and the Routes grid, where the tier's place already tells models apart.
460
+ export const shortModelName = (id) =>
461
+ modelName(id)
462
+ .split(' ')
463
+ .filter((word) => !/^[A-Za-z]?\d+(\.\d+)*$/.test(word))
464
+ .join(' ');
465
+ // A route as a pin labels it, "Haiku·high"; a model without efforts shows its name alone.
466
+ export function shortRoute(config, route) {
467
+ const model = config.models[route.model];
468
+ if (!model) return route.model;
469
+ const effort = model.efforts.length ? (route.effort ?? 'session') : null;
470
+ return `${shortModelName(model.id)}${effort ? `·${effort}` : ''}`;
471
+ }
472
+
473
+ // A tier as signal-strength bars, "▂▄▆" for medium: the band and pane draw the tier this way, never as a word, so the
474
+ // only "low" or "high" beside a model is its effort.
475
+ const METER = '▂▄▆█';
476
+ export const tierBars = (tier) => METER.slice(0, TIERS.indexOf(tier) + 1);
477
+
478
+ // Money by how it is paid: "≈$7.60" on a plan (quota, valued at API prices), "$3.76" when billed.
479
+ export const costText = (value, billing) => `${billing === 'billed' ? '' : '≈'}${usd(value)}`;
480
+ export const BILLING_WORDS = { plan: 'API value', mixed: 'API value', billed: 'billed' };
481
+ // "−$1.76 (−19%)", or "+$2.48 (×5.0)" past double; one format for every difference against no routing.
482
+ export function diffText(diff, base) {
483
+ const share = base > 0 ? Math.round((diff / base) * 100) : 0;
484
+ if (share > 100) return `${signedUsd(diff)} (×${((base + diff) / base).toFixed(1)})`;
485
+ return `${signedUsd(diff)}${share ? ` (${share < 0 ? '−' : '+'}${Math.abs(share)}%)` : ''}`;
486
+ }
487
+
488
+ // A gauge of `cells` cells for a fraction 0–1: [filled, empty].
489
+ export function gaugeCells(fraction, cells) {
490
+ // Anything above zero lights one cell, so a small reading never reads as empty.
491
+ const lit = Number.isFinite(fraction) && fraction > 0 ? Math.max(1, Math.round(fraction * cells)) : 0;
492
+ const filled = Math.min(cells, lit);
493
+ return ['▰'.repeat(filled), '▱'.repeat(cells - filled)];
494
+ }
495
+ // A plan window's colour by how much is used: green, then the warning colour past 75%, red past 90%.
496
+ export const limitColor = (percent) => (percent >= 90 ? 'red' : percent >= 75 ? SAVINGS_COLOR.more : 'green');
497
+
498
+ // This session's cost with its subagents and plan windows (costs.mjs periodCost).
499
+ export function sessionCost(config, view, usage, now) {
500
+ return periodCost(config, {
501
+ summary: sessionUsage(view, now),
502
+ agents: summarizeSubagents(readSubagentStore(view.subagentSession), { from: null, to: null }),
503
+ usage,
504
+ });
505
+ }