@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/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 in USD per million tokens; `cacheRead` is absolute,
70
- // not a multiplier (Opus 5.5 reads at 0.05x input, the rest at the standard 0.1x). `longContext` multiplies every
71
- // rate of a request whose prompt (input, cache read and cache write) is over `above` tokens: Haiku 5.5 lists its
72
- // rates for prompts up to 100,000 tokens and 5x above. A price change must also change
73
- // test/fixtures/list-prices.json, with its source and date. `output` feeds the downgrade tax.
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
- input: 4,
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
- input: 2,
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
- input: 0.1,
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. Every estimate
31
- // prices through here.
32
- export function ratesAt(model, promptTokens) {
33
- const k = model.longContext && promptTokens > model.longContext.above ? model.longContext.multiplier : 1;
30
+ // and cache write) is `promptTokens` at time `at`, with the model's long-context multiplier above its threshold and
31
+ // its off-peak multiplier outside peak hours. Every estimate prices through here.
32
+ // True when `at` (ms) falls outside the model's peak hours. An unknown time is peak: the higher bound.
33
+ export function isOffPeak(model, at) {
34
+ if (!model.offPeak || !Number.isFinite(at)) return false;
35
+ const time = new Date(at);
36
+ const hour = time.getUTCHours();
37
+ const peak =
38
+ model.offPeak.peakDays.includes(time.getUTCDay()) &&
39
+ model.offPeak.peakHoursUtc.some(([from, to]) => hour >= from && hour < to);
40
+ return !peak;
41
+ }
42
+
43
+ export function ratesAt(model, promptTokens, at) {
44
+ const k =
45
+ (model.longContext && promptTokens > model.longContext.above ? model.longContext.multiplier : 1) *
46
+ (isOffPeak(model, at) ? model.offPeak.multiplier : 1);
34
47
  return {
35
48
  input: model.input * k,
36
49
  cacheRead: model.cacheRead * k,
@@ -69,7 +82,7 @@ export function cacheState(state, now, cache) {
69
82
 
70
83
  // Bounds are scenarios, never an independent ledger. Unknown incumbent cache can still be served.
71
84
  export function inputBounds(config, route, tokens, facts, now) {
72
- const model = ratesAt(routeSpec(config, route), tokens);
85
+ const model = ratesAt(routeSpec(config, route), tokens, now);
73
86
  const state = facts.models[routeCacheKey(config, route, facts.effort)];
74
87
  const prefix = Math.min(state?.prefixTokens ?? tokens, tokens);
75
88
  const fresh = isWarm(state, now, config.cache);
@@ -87,9 +100,9 @@ export function inputBounds(config, route, tokens, facts, now) {
87
100
  };
88
101
  }
89
102
 
90
- export function coldWriteUsd(config, alias, tokens) {
103
+ export function coldWriteUsd(config, alias, tokens, now) {
91
104
  return (
92
- (ratesAt(config.models[alias], tokens).input *
105
+ (ratesAt(config.models[alias], tokens, now).input *
93
106
  (config.cache.mode === 'explicit' ? Math.max(...Object.values(config.cache.writeMultiplier)) : 1) *
94
107
  tokens) /
95
108
  1e6
@@ -112,7 +125,10 @@ export function nextTurnRange(config, candidate, incumbent, facts, now) {
112
125
  const tokens = nextContextTokens(facts);
113
126
  const proposed = inputBounds(config, candidate, tokens, facts, now);
114
127
  const current = inputBounds(config, incumbent, tokens, facts, now);
115
- const [to, from] = [ratesAt(routeSpec(config, candidate), tokens), ratesAt(routeSpec(config, incumbent), tokens)];
128
+ const [to, from] = [
129
+ ratesAt(routeSpec(config, candidate), tokens, now),
130
+ ratesAt(routeSpec(config, incumbent), tokens, now),
131
+ ];
116
132
  const outputTokens = facts.lastRequest?.outputTokens ?? 0;
117
133
  const output = to.output > 0 && from.output > 0 ? ((to.output - from.output) * outputTokens) / 1e6 : 0;
118
134
  return { minUsd: proposed.min - current.max + output, maxUsd: proposed.max - current.min + output };
@@ -121,8 +137,8 @@ export function nextTurnRange(config, candidate, incumbent, facts, now) {
121
137
  export function switchEconomics(config, candidate, incumbent, facts, now) {
122
138
  if (config.cache.mode === 'automatic') return null;
123
139
  const tokens = nextContextTokens(facts);
124
- const proposed = ratesAt(routeSpec(config, candidate), tokens);
125
- const current = ratesAt(routeSpec(config, incumbent), tokens);
140
+ const proposed = ratesAt(routeSpec(config, candidate), tokens, now);
141
+ const current = ratesAt(routeSpec(config, incumbent), tokens, now);
126
142
  if (!(proposed.output > 0) || !(current.output > 0)) return null;
127
143
  const outputTokens = facts.lastRequest?.outputTokens ?? 0;
128
144
  const output = ((proposed.output - current.output) * outputTokens) / 1e6;
package/lib/costs.mjs ADDED
@@ -0,0 +1,156 @@
1
+ // What a session cost and how it is paid, as one value the band, the pane and /router all read, so they show the same
2
+ // numbers at the same moment. Pure: the inputs are the period's usage summary (usage.mjs), its subagent summary
3
+ // (subagents.mjs), the configured models and Claude Code's plan windows.
4
+ //
5
+ // Every dollar is tokens at the router file's list prices. How that dollar is paid decides its label: on a Claude plan
6
+ // it is quota, an "API value" shown with ≈; with an API key or a provider's credits it is billed. "No routing" is what
7
+ // the same tokens cost without the router: your model on the main thread, Claude Code's pick for each subagent.
8
+
9
+ import { EFFORTS, TIERS } from './config.mjs';
10
+ import { modelSpec, readout } from './savings.mjs';
11
+ import { dayKey } from './usage.mjs';
12
+
13
+ // The plan windows Claude Code reports, in the order shown. `spend_limit` is a gateway's cap on billed spend, not a
14
+ // plan's quota.
15
+ const WINDOWS = [
16
+ ['five_hour', '5h'],
17
+ ['seven_day', '7d'],
18
+ ['spend_limit', 'spend'],
19
+ ];
20
+ const QUOTA = ['five_hour', 'seven_day'];
21
+
22
+ // The windows with a reading, `{ kind, label, percent, resetsAt }` (resetsAt in ms, or null), in WINDOWS order.
23
+ export function planLimits(usage) {
24
+ const limits = Array.isArray(usage?.rateLimits) ? usage.rateLimits : [];
25
+ return WINDOWS.flatMap(([kind, label]) => {
26
+ const limit = limits.find((l) => l?.kind === kind && Number.isFinite(l.percentUsed));
27
+ if (!limit) return [];
28
+ const resetsAt = Date.parse(limit.resetsAt ?? '');
29
+ return [{ kind, label, percent: limit.percentUsed, resetsAt: Number.isFinite(resetsAt) ? resetsAt : null }];
30
+ });
31
+ }
32
+
33
+ // How the session pays: `plan` (Claude plan quota), `mixed` (plan quota and provider credits), or `billed` (API key,
34
+ // gateway or credits). A plan shows itself only through its windows, which Claude Code reads from the first reply on:
35
+ // before that a plan session reads as billed, with nothing spent yet.
36
+ export function billingOf(config, usage) {
37
+ const models = Object.values(config.models);
38
+ const credits = models.some((m) => m.billing === 'credits');
39
+ const plan = models.some((m) => m.billing === 'plan');
40
+ if (!plan || !planLimits(usage).some((l) => QUOTA.includes(l.kind))) return 'billed';
41
+ return credits ? 'mixed' : 'plan';
42
+ }
43
+
44
+ // Whether every route runs one model, so routing only moves the effort. The savings estimate holds output length
45
+ // constant and cannot price an effort change, so such a profile shows its effort mix instead of a saving.
46
+ export function isEffortOnly(config) {
47
+ const cells = [
48
+ ...TIERS.map((tier) => config.routes[tier]),
49
+ ...(config.activityRouting === 'off' ? [] : Object.values(config.activities ?? {}).flatMap(Object.values)),
50
+ ].filter(Boolean);
51
+ return new Set(cells.map((route) => route.model)).size === 1;
52
+ }
53
+
54
+ const cents = (usd) => Math.round(usd * 100) / 100;
55
+ // A cell key ends with the route `id@effort` (usage.mjs replyEntry).
56
+ const routeOfCell = (key) => {
57
+ const route = key.slice(key.lastIndexOf('|') + 1);
58
+ const at = route.lastIndexOf('@');
59
+ return at < 0 ? { id: route, effort: null } : { id: route.slice(0, at), effort: route.slice(at + 1) || null };
60
+ };
61
+
62
+ // Replies by effort, in effort order: [[effort, replies]].
63
+ function effortMix(cells) {
64
+ const counts = {};
65
+ for (const [key, sums] of Object.entries(cells)) {
66
+ const { effort } = routeOfCell(key);
67
+ const name = effort ?? 'default';
68
+ counts[name] = (counts[name] ?? 0) + sums[0];
69
+ }
70
+ const rank = (e) => (EFFORTS.includes(e) ? EFFORTS.indexOf(e) : EFFORTS.length);
71
+ return Object.entries(counts)
72
+ .filter(([, n]) => n > 0)
73
+ .sort((a, b) => rank(a[0]) - rank(b[0]));
74
+ }
75
+
76
+ // Subagents in a period: how many ran, what they cost, and what the same tokens cost on Claude Code's picks. A
77
+ // pass-through ran on Claude Code's pick, so it costs the same with and without routing. A record from before 1.14.0
78
+ // keeps undated totals without a pick price: they count as unrouted.
79
+ export function agentCosts(config, summary) {
80
+ const out = { agents: 0, moved: 0, usd: 0, baseUsd: 0, creditsUsd: 0 };
81
+ for (const kind of ['routed', 'passed'])
82
+ for (const counts of Object.values(summary?.[kind] ?? {})) {
83
+ out.agents += counts.agents;
84
+ for (const [id, model] of Object.entries(counts.models)) {
85
+ out.usd += model.usd;
86
+ out.baseUsd += kind === 'routed' ? model.coreUsd : model.usd;
87
+ out.moved += model.moved ?? 0;
88
+ if (modelSpec(config, id)?.billing === 'credits') out.creditsUsd += model.usd;
89
+ }
90
+ }
91
+ if (summary?.undated) {
92
+ out.agents += summary.undated.agents;
93
+ out.usd += summary.undated.usd;
94
+ out.baseUsd += summary.undated.usd;
95
+ }
96
+ return out;
97
+ }
98
+
99
+ // The period's cost: `summary` from usage.mjs summarize, `agents` from subagents.mjs summarizeSubagents. `usage` is
100
+ // Claude Code's session usage: its plan windows tell how every period is paid.
101
+ export function periodCost(config, { summary, agents, usage = null }) {
102
+ const a = agentCosts(config, agents);
103
+ const r = readout(summary);
104
+ const effortOnly = isEffortOnly(config);
105
+ // A saving needs every main reply compared; effort-only profiles have none to show. Agents alone compare too: each
106
+ // has Claude Code's pick to price against.
107
+ const comparable = !effortOnly && (summary.replies > 0 || a.agents > 0) && !summary.observed.uncomparedReplies;
108
+ const mainUsd = cents(summary.observed.routedUsd);
109
+ const agentUsd = cents(a.usd);
110
+ const agentBaseUsd = cents(a.baseUsd);
111
+ const totalUsd = cents(mainUsd + agentUsd);
112
+ const mainDiff = comparable ? r.differenceUsd : null;
113
+ const agentDiff = cents(agentUsd - agentBaseUsd);
114
+ const baseUsd = comparable ? cents(r.yoursUsd + agentBaseUsd) : null;
115
+ const diffUsd = comparable ? cents(mainDiff + agentDiff) : null;
116
+ const billing = billingOf(config, usage);
117
+ let creditsUsd = null;
118
+ if (billing === 'mixed') {
119
+ let main = 0;
120
+ for (const [key, sums] of Object.entries(summary.observed.cells))
121
+ if (modelSpec(config, routeOfCell(key).id)?.billing === 'credits') main += sums[1];
122
+ creditsUsd = cents(main + a.creditsUsd);
123
+ }
124
+ return {
125
+ billing,
126
+ replies: summary.observed.replies,
127
+ agents: a.agents,
128
+ moved: a.moved,
129
+ mainUsd,
130
+ agentUsd,
131
+ agentBaseUsd,
132
+ totalUsd,
133
+ mainDiff,
134
+ agentDiff: agentUsd || agentBaseUsd ? agentDiff : null,
135
+ baseUsd,
136
+ diffUsd,
137
+ share: baseUsd > 0 ? diffUsd / baseUsd : null,
138
+ // A sample of main replies: agents alone are each priced against their own pick, not sampled.
139
+ early: r.early && summary.replies > 0,
140
+ readout: r,
141
+ comparable,
142
+ uncomparedReplies: summary.observed.uncomparedReplies,
143
+ effortOnly,
144
+ effortMix: effortMix(summary.observed.cells),
145
+ creditsUsd,
146
+ limits: planLimits(usage),
147
+ };
148
+ }
149
+
150
+ // "17:00" today, "Thu 09:00" on another day; null once the reset has passed, as the reading is then stale.
151
+ export function resetText(ms, now) {
152
+ if (!Number.isFinite(ms) || ms <= now) return null;
153
+ const date = new Date(ms);
154
+ const time = date.toLocaleTimeString('en-GB', { hour: '2-digit', minute: '2-digit' });
155
+ return dayKey(ms) === dayKey(now) ? time : `${date.toLocaleDateString('en-US', { weekday: 'short' })} ${time}`;
156
+ }