@alexeiled/claude-router 1.20.1 → 1.21.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/.claude-plugin/plugin.json +1 -1
- package/CHANGELOG.md +27 -0
- package/README.md +3 -3
- package/docs/activity-routing.md +1 -1
- package/docs/architecture.md +5 -3
- package/docs/configuration.md +9 -8
- package/docs/evaluation.md +4 -4
- package/docs/native-router.md +11 -11
- package/docs/providers.md +3 -3
- 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/user-guide.md +129 -70
- package/hooks/native-router.mjs +9 -5
- package/lib/band.mjs +254 -172
- package/lib/config.mjs +24 -15
- package/lib/cost.mjs +26 -10
- package/lib/costs.mjs +156 -0
- package/lib/display.mjs +102 -93
- package/lib/panel.mjs +486 -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'];
|
|
@@ -66,38 +67,31 @@ export const DEFAULTS = {
|
|
|
66
67
|
// The classifier's probability of `high` a task needs to run on `heavy`.
|
|
67
68
|
heavyMass: 0.8,
|
|
68
69
|
},
|
|
69
|
-
// `id` selects the native model. List prices
|
|
70
|
-
// not a multiplier (Opus 5.5
|
|
71
|
-
//
|
|
72
|
-
//
|
|
73
|
-
//
|
|
70
|
+
// `id` selects the native model. List prices (USD per million tokens) come from prices.mjs, which the price check
|
|
71
|
+
// keeps in step with each vendor's page. `cacheRead` is absolute, not a multiplier (Opus 5.5 and Sonnet 5.5 read at
|
|
72
|
+
// 0.05x input, Haiku 5.5 at the standard 0.1x). `longContext` multiplies every rate of a request whose prompt
|
|
73
|
+
// (input, cache read and cache write) is over `above` tokens; `offPeak` multiplies them outside the peak hours.
|
|
74
|
+
// `output` feeds the downgrade tax.
|
|
74
75
|
// `efforts` lists what the model accepts; an empty list means no effort field and no adaptive thinking. A change
|
|
75
76
|
// must also change test/fixtures/effort-support.json, from a new probe against the real API.
|
|
76
77
|
models: {
|
|
77
78
|
opus: {
|
|
78
79
|
id: 'claude-opus-5-5',
|
|
79
|
-
|
|
80
|
-
output: 20,
|
|
81
|
-
cacheRead: 0.2,
|
|
80
|
+
...listPrice('claude-opus-5-5'),
|
|
82
81
|
contextWindow: 1_000_000,
|
|
83
82
|
billing: 'plan',
|
|
84
83
|
efforts: EFFORTS,
|
|
85
84
|
},
|
|
86
85
|
sonnet: {
|
|
87
86
|
id: 'claude-sonnet-5-5',
|
|
88
|
-
|
|
89
|
-
output: 10,
|
|
90
|
-
cacheRead: 0.2,
|
|
87
|
+
...listPrice('claude-sonnet-5-5'),
|
|
91
88
|
contextWindow: 1_000_000,
|
|
92
89
|
billing: 'plan',
|
|
93
90
|
efforts: EFFORTS,
|
|
94
91
|
},
|
|
95
92
|
haiku: {
|
|
96
93
|
id: 'claude-haiku-5-5',
|
|
97
|
-
|
|
98
|
-
output: 0.5,
|
|
99
|
-
cacheRead: 0.01,
|
|
100
|
-
longContext: { above: 100_000, multiplier: 5 },
|
|
94
|
+
...listPrice('claude-haiku-5-5'),
|
|
101
95
|
contextWindow: 1_000_000,
|
|
102
96
|
billing: 'plan',
|
|
103
97
|
efforts: EFFORTS,
|
|
@@ -236,6 +230,7 @@ const MODEL_KEYS = [
|
|
|
236
230
|
'output',
|
|
237
231
|
'cacheRead',
|
|
238
232
|
'longContext',
|
|
233
|
+
'offPeak',
|
|
239
234
|
'contextWindow',
|
|
240
235
|
'billing',
|
|
241
236
|
'efforts',
|
|
@@ -546,6 +541,8 @@ function checkShape(file) {
|
|
|
546
541
|
// null removes a built-in surcharge.
|
|
547
542
|
if (model.longContext != null)
|
|
548
543
|
checkObject(model.longContext, `models.${alias}.longContext`, ['above', 'multiplier']);
|
|
544
|
+
if (model.offPeak != null)
|
|
545
|
+
checkObject(model.offPeak, `models.${alias}.offPeak`, ['multiplier', 'peakDays', 'peakHoursUtc']);
|
|
549
546
|
}
|
|
550
547
|
}
|
|
551
548
|
if (cache !== undefined) {
|
|
@@ -697,6 +694,18 @@ function validateModel(at, model) {
|
|
|
697
694
|
throw new Error(`${at}.longContext.above must be a positive integer`);
|
|
698
695
|
if (!isNumber(multiplier, 0, { above: true })) throw new Error(`${at}.longContext.multiplier must be positive`);
|
|
699
696
|
}
|
|
697
|
+
if (model.offPeak != null) {
|
|
698
|
+
const { multiplier, peakDays, peakHoursUtc } = model.offPeak;
|
|
699
|
+
if (!isNumber(multiplier, 0, { above: true })) throw new Error(`${at}.offPeak.multiplier must be positive`);
|
|
700
|
+
if (!Array.isArray(peakDays) || peakDays.some((d) => !isNumber(d, 0, { integer: true }) || d > 6))
|
|
701
|
+
throw new Error(`${at}.offPeak.peakDays must list UTC weekdays 0-6`);
|
|
702
|
+
const hour = (h) => isNumber(h, 0, { integer: true }) && h <= 24;
|
|
703
|
+
if (
|
|
704
|
+
!Array.isArray(peakHoursUtc) ||
|
|
705
|
+
peakHoursUtc.some((r) => !Array.isArray(r) || r.length !== 2 || !hour(r[0]) || !hour(r[1]) || r[0] >= r[1])
|
|
706
|
+
)
|
|
707
|
+
throw new Error(`${at}.offPeak.peakHoursUtc must list [from, to) UTC hour ranges`);
|
|
708
|
+
}
|
|
700
709
|
if (typeof model.id !== 'string' || !model.id) throw new Error(`${at}.id is required`);
|
|
701
710
|
if (!['plan', 'credits'].includes(model.billing)) throw new Error(`${at}.billing must be plan or credits`);
|
|
702
711
|
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,34 @@ 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]);
|
|
388
|
-
}
|
|
389
348
|
// Cache rebuilds cost more than the cheaper models saved: the switches lost money.
|
|
390
349
|
export const switchesLost = (r) => r.switchUsd > 0 && r.switchUsd > -r.cheaperUsd;
|
|
391
350
|
|
|
392
|
-
// The `/router`
|
|
393
|
-
//
|
|
394
|
-
|
|
395
|
-
|
|
396
|
-
|
|
397
|
-
|
|
398
|
-
|
|
399
|
-
|
|
400
|
-
|
|
401
|
-
|
|
402
|
-
|
|
403
|
-
|
|
404
|
-
|
|
405
|
-
|
|
406
|
-
|
|
407
|
-
|
|
408
|
-
|
|
409
|
-
|
|
410
|
-
|
|
411
|
-
|
|
412
|
-
|
|
413
|
-
|
|
351
|
+
// The `/router` lines without a surface, in the band's and pane's words and numbers: the plan windows, then this
|
|
352
|
+
// session's cost with its subagents against no routing.
|
|
353
|
+
// "3 of 20 replies have no comparison", or "no reply has a comparison" when none has.
|
|
354
|
+
export const uncomparedText = (cost) =>
|
|
355
|
+
cost.uncomparedReplies === cost.replies
|
|
356
|
+
? 'no reply has a comparison'
|
|
357
|
+
: `${cost.uncomparedReplies} of ${cost.replies} replies have no comparison`;
|
|
358
|
+
|
|
359
|
+
export function savingsLine(config, view, usage, now) {
|
|
360
|
+
const cost = sessionCost(config, view, usage, now);
|
|
361
|
+
const plan = cost.limits.map((l) => `${l.label} ${l.percent}%`).join(' · ');
|
|
362
|
+
const lines = plan ? [`Plan: ${plan}`] : [];
|
|
363
|
+
if (!cost.replies && !cost.agents) return [...lines, 'Session: no routed replies yet'].join('\n');
|
|
364
|
+
const split = cost.agents ? ` (main ${usd(cost.mainUsd)} + agents ${usd(cost.agentUsd)})` : '';
|
|
365
|
+
const credits = cost.creditsUsd ? ` · billed ${usd(cost.creditsUsd)}` : '';
|
|
366
|
+
const versus =
|
|
367
|
+
cost.diffUsd !== null
|
|
368
|
+
? ` · ${diffText(cost.diffUsd, cost.baseUsd)} vs no routing${cost.early ? ', early sample' : ''}`
|
|
369
|
+
: cost.effortOnly
|
|
370
|
+
? ` · effort ${cost.effortMix.map(([effort, n]) => `${effort} ${n}`).join(' · ')}`
|
|
371
|
+
: ` · ${uncomparedText(cost)}`;
|
|
372
|
+
lines.push(
|
|
373
|
+
`Session: ${costText(cost.totalUsd, cost.billing)} ${BILLING_WORDS[cost.billing]}${split}${credits}${versus} · ${replyCount(cost.replies)}`,
|
|
374
|
+
);
|
|
375
|
+
return lines.join('\n');
|
|
414
376
|
}
|
|
415
377
|
|
|
416
378
|
export const GATEWAY_SETTINGS = 'v0.8 gateway settings remain · see /router';
|
|
@@ -452,7 +414,6 @@ export function usageMetrics(config, view, usage) {
|
|
|
452
414
|
);
|
|
453
415
|
const nextContext = candidates.length ? Math.max(...candidates) : null;
|
|
454
416
|
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
417
|
const rates = spec && ratesAt(spec, view.inputTokens ?? 0);
|
|
457
418
|
const cacheBenefit =
|
|
458
419
|
rates && Number.isFinite(view.cacheRead) ? ((rates.input - rates.cacheRead) * view.cacheRead) / 1e6 : null;
|
|
@@ -461,7 +422,6 @@ export function usageMetrics(config, view, usage) {
|
|
|
461
422
|
observed,
|
|
462
423
|
nextContext,
|
|
463
424
|
reuse,
|
|
464
|
-
cost,
|
|
465
425
|
cacheBenefit,
|
|
466
426
|
contextBar: bar(nextContext, window),
|
|
467
427
|
cacheBar: {
|
|
@@ -480,3 +440,52 @@ export function sparkline(values) {
|
|
|
480
440
|
const span = Math.max(...values) - minimum;
|
|
481
441
|
return values.map((value) => symbols[span > 0 ? Math.round(((value - minimum) / span) * 7) : 3]).join('');
|
|
482
442
|
}
|
|
443
|
+
|
|
444
|
+
// "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
|
|
445
|
+
// version, for the pins and the Routes grid, where the tier's place already tells models apart.
|
|
446
|
+
export const shortModelName = (id) =>
|
|
447
|
+
modelName(id)
|
|
448
|
+
.split(' ')
|
|
449
|
+
.filter((word) => !/^[A-Za-z]?\d+(\.\d+)*$/.test(word))
|
|
450
|
+
.join(' ');
|
|
451
|
+
// A route as a pin labels it, "Haiku·high"; a model without efforts shows its name alone.
|
|
452
|
+
export function shortRoute(config, route) {
|
|
453
|
+
const model = config.models[route.model];
|
|
454
|
+
if (!model) return route.model;
|
|
455
|
+
const effort = model.efforts.length ? (route.effort ?? 'session') : null;
|
|
456
|
+
return `${shortModelName(model.id)}${effort ? `·${effort}` : ''}`;
|
|
457
|
+
}
|
|
458
|
+
|
|
459
|
+
// A tier as signal-strength bars, "▂▄▆" for medium: the band and pane draw the tier this way, never as a word, so the
|
|
460
|
+
// only "low" or "high" beside a model is its effort.
|
|
461
|
+
const METER = '▂▄▆█';
|
|
462
|
+
export const tierBars = (tier) => METER.slice(0, TIERS.indexOf(tier) + 1);
|
|
463
|
+
|
|
464
|
+
// Money by how it is paid: "≈$7.60" on a plan (quota, valued at API prices), "$3.76" when billed.
|
|
465
|
+
export const costText = (value, billing) => `${billing === 'billed' ? '' : '≈'}${usd(value)}`;
|
|
466
|
+
export const BILLING_WORDS = { plan: 'API value', mixed: 'API value', billed: 'billed' };
|
|
467
|
+
// "−$1.76 (−19%)", or "+$2.48 (×5.0)" past double; one format for every difference against no routing.
|
|
468
|
+
export function diffText(diff, base) {
|
|
469
|
+
const share = base > 0 ? Math.round((diff / base) * 100) : 0;
|
|
470
|
+
if (share > 100) return `${signedUsd(diff)} (×${((base + diff) / base).toFixed(1)})`;
|
|
471
|
+
return `${signedUsd(diff)}${share ? ` (${share < 0 ? '−' : '+'}${Math.abs(share)}%)` : ''}`;
|
|
472
|
+
}
|
|
473
|
+
|
|
474
|
+
// A gauge of `cells` cells for a fraction 0–1: [filled, empty].
|
|
475
|
+
export function gaugeCells(fraction, cells) {
|
|
476
|
+
// Anything above zero lights one cell, so a small reading never reads as empty.
|
|
477
|
+
const lit = Number.isFinite(fraction) && fraction > 0 ? Math.max(1, Math.round(fraction * cells)) : 0;
|
|
478
|
+
const filled = Math.min(cells, lit);
|
|
479
|
+
return ['▰'.repeat(filled), '▱'.repeat(cells - filled)];
|
|
480
|
+
}
|
|
481
|
+
// A plan window's colour by how much is used: green, then the warning colour past 75%, red past 90%.
|
|
482
|
+
export const limitColor = (percent) => (percent >= 90 ? 'red' : percent >= 75 ? SAVINGS_COLOR.more : 'green');
|
|
483
|
+
|
|
484
|
+
// This session's cost with its subagents and plan windows (costs.mjs periodCost).
|
|
485
|
+
export function sessionCost(config, view, usage, now) {
|
|
486
|
+
return periodCost(config, {
|
|
487
|
+
summary: sessionUsage(view, now),
|
|
488
|
+
agents: summarizeSubagents(readSubagentStore(view.subagentSession), { from: null, to: null }),
|
|
489
|
+
usage,
|
|
490
|
+
});
|
|
491
|
+
}
|