@alexeiled/claude-router 1.20.0 → 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 +43 -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 +5 -5
- 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 +128 -71
- package/hooks/native-router.mjs +9 -5
- package/lib/band.mjs +254 -163
- package/lib/config.mjs +24 -15
- package/lib/cost.mjs +26 -10
- package/lib/costs.mjs +156 -0
- package/lib/display.mjs +114 -176
- package/lib/panel.mjs +497 -554
- 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/lib/usage.mjs +1 -2
- 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
|
+
}
|