@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/.claude-plugin/plugin.json +1 -1
- package/CHANGELOG.md +41 -0
- package/README.md +3 -3
- package/docs/activity-routing.md +1 -1
- package/docs/architecture.md +6 -4
- package/docs/configuration.md +9 -8
- package/docs/evaluation.md +4 -4
- package/docs/native-router.md +11 -11
- package/docs/providers.md +5 -6
- package/docs/router-band.svg +158 -137
- package/docs/router-pane-classifier.svg +21 -23
- package/docs/router-pane-now.svg +138 -173
- package/docs/router-pane-policy.svg +21 -23
- package/docs/router-pane-routes.svg +32 -34
- package/docs/router-pane-usage-whatif.svg +139 -157
- package/docs/router-pane-usage.svg +165 -165
- package/docs/routing-modes.md +22 -20
- package/docs/user-guide.md +130 -71
- package/hooks/native-router.mjs +9 -5
- package/lib/band.mjs +254 -171
- package/lib/config.mjs +33 -18
- package/lib/cost.mjs +26 -10
- package/lib/costs.mjs +156 -0
- package/lib/display.mjs +115 -92
- package/lib/modes.mjs +8 -7
- package/lib/panel.mjs +487 -445
- package/lib/policy.mjs +1 -1
- package/lib/prices.mjs +113 -0
- package/lib/providers.mjs +9 -21
- package/lib/route.mjs +1 -1
- package/lib/savings.mjs +14 -8
- package/lib/subagents.mjs +3 -3
- package/package.json +2 -1
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)
|
|
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
|
|
70
|
-
// not a multiplier (Opus 5.5
|
|
71
|
-
//
|
|
72
|
-
//
|
|
73
|
-
//
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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.
|
|
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.
|
|
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
|
|
31
|
-
// prices through here.
|
|
32
|
-
|
|
33
|
-
|
|
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] = [
|
|
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
|
|
17
|
-
import {
|
|
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
|
-
//
|
|
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: '=
|
|
187
|
-
upgrade: '↑
|
|
188
|
-
jump: '↑
|
|
189
|
-
downgrade: '↓
|
|
190
|
-
'upgrade-pending': '… waiting
|
|
191
|
-
'downgrade-pending': '… waiting
|
|
192
|
-
'downgrade-held': '…
|
|
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': '=
|
|
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
|
-
|
|
203
|
-
'
|
|
204
|
-
|
|
205
|
-
'activity-
|
|
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
|
-
//
|
|
209
|
-
const
|
|
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
|
|
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
|
-
? `${
|
|
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
|
|
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
|
-
//
|
|
376
|
-
//
|
|
377
|
-
|
|
378
|
-
export const
|
|
379
|
-
|
|
380
|
-
|
|
381
|
-
|
|
382
|
-
|
|
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`
|
|
393
|
-
//
|
|
394
|
-
|
|
395
|
-
|
|
396
|
-
|
|
397
|
-
|
|
398
|
-
|
|
399
|
-
|
|
400
|
-
|
|
401
|
-
|
|
402
|
-
|
|
403
|
-
|
|
404
|
-
|
|
405
|
-
|
|
406
|
-
|
|
407
|
-
|
|
408
|
-
|
|
409
|
-
|
|
410
|
-
|
|
411
|
-
|
|
412
|
-
|
|
413
|
-
|
|
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
|
+
}
|