@alexeiled/claude-router 1.6.0 → 1.7.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 +47 -0
- package/README.md +14 -4
- package/docs/activity-routing.md +254 -0
- package/docs/architecture.md +9 -3
- package/docs/configuration.md +56 -44
- package/docs/evaluation.md +37 -6
- package/docs/native-router.md +17 -13
- package/docs/router-band.svg +78 -80
- package/docs/router-pane-classifier.svg +7 -7
- package/docs/router-pane-now.svg +9 -9
- package/docs/router-pane-routing.svg +73 -87
- package/docs/router-pane-usage.svg +123 -0
- package/docs/user-guide.md +79 -53
- package/hooks/native-router.mjs +236 -39
- package/lib/activity-stats.mjs +87 -21
- package/lib/band.mjs +82 -55
- package/lib/config.mjs +49 -32
- package/lib/cost.mjs +32 -5
- package/lib/display.mjs +79 -4
- package/lib/panel.mjs +389 -67
- package/lib/route.mjs +27 -12
- package/lib/savings.mjs +237 -0
- package/lib/view.mjs +10 -1
- package/package.json +1 -1
- package/types/index.d.ts +51 -3
package/lib/route.mjs
CHANGED
|
@@ -9,7 +9,7 @@ const SNAPSHOTS = { 'claude-haiku-4-5': 'claude-haiku-4-5-20251001' };
|
|
|
9
9
|
|
|
10
10
|
// A request this much smaller than the last means the history was compacted or rewound: the cached prefixes the
|
|
11
11
|
// observations describe are gone, so they are dropped rather than priced as warm.
|
|
12
|
-
const HISTORY_SHRINK = 0.8;
|
|
12
|
+
export const HISTORY_SHRINK = 0.8;
|
|
13
13
|
|
|
14
14
|
// Whether the engine served the requested model, allowing for a dated snapshot of it.
|
|
15
15
|
export function isSameModel(requested, served) {
|
|
@@ -53,6 +53,8 @@ export function emptyLoop(config, model) {
|
|
|
53
53
|
turnId: null,
|
|
54
54
|
decision: null,
|
|
55
55
|
ineligible: [],
|
|
56
|
+
// Your model's simulated cache for the routing-vs-your-model readout (compareReply in savings.mjs).
|
|
57
|
+
yours: null,
|
|
56
58
|
};
|
|
57
59
|
}
|
|
58
60
|
|
|
@@ -69,6 +71,7 @@ export function resetHistory(loop) {
|
|
|
69
71
|
would: loop.would ? { ...loop.would, state: freshState(loop.would.state) } : null,
|
|
70
72
|
// The active turn keeps its route, pin and fallback suspension; the next turn decides afresh.
|
|
71
73
|
ineligible: [],
|
|
74
|
+
yours: null,
|
|
72
75
|
};
|
|
73
76
|
}
|
|
74
77
|
|
|
@@ -129,7 +132,24 @@ export function chooseRoute(config, loop, input) {
|
|
|
129
132
|
},
|
|
130
133
|
);
|
|
131
134
|
const { activity, tier, model, effort, reason } = run;
|
|
132
|
-
|
|
135
|
+
// What the would-route's next request costs against the applied one's; a route priced against itself would
|
|
136
|
+
// still give a spread, so only a different request is priced.
|
|
137
|
+
const priced =
|
|
138
|
+
input.contextKnown &&
|
|
139
|
+
loop.lastRequest &&
|
|
140
|
+
run.tier &&
|
|
141
|
+
applied.tier &&
|
|
142
|
+
(run.model !== applied.model || run.effort !== applied.effort);
|
|
143
|
+
const difference = priced
|
|
144
|
+
? costs.nextTurnRange(
|
|
145
|
+
economicConfig(config, loop),
|
|
146
|
+
resolveRoute(config, run.tier, run.activity),
|
|
147
|
+
resolveRoute(config, applied.tier, applied.activity ?? null),
|
|
148
|
+
facts,
|
|
149
|
+
input.now,
|
|
150
|
+
)
|
|
151
|
+
: null;
|
|
152
|
+
wouldRoute = { activity, tier, model, effort, reason, difference };
|
|
133
153
|
const stays = pin || !run.tier;
|
|
134
154
|
would = {
|
|
135
155
|
lastRoute: stays ? from.lastRoute : run.tier,
|
|
@@ -187,9 +207,12 @@ function routeTurn(config, loop, { facts, advice, pin, nativeModel, contextKnown
|
|
|
187
207
|
}
|
|
188
208
|
if (shrinksUnmeasured(result)) result = { ...result, ...last, reason: 'context-unknown' };
|
|
189
209
|
if (!fits(result)) {
|
|
210
|
+
// A cell labelled with another activity would run, and stick, a route this turn did not choose.
|
|
190
211
|
const native = cellForModel(config, nativeModel);
|
|
191
212
|
const cells = [last, native, ...TIERS.map((tier) => ({ tier, activity }))];
|
|
192
|
-
const fallback = cells.find(
|
|
213
|
+
const fallback = cells.find(
|
|
214
|
+
(cell) => cell && (cell.activity === null || cell.activity === activity) && fits(cell),
|
|
215
|
+
) ?? { tier: null, activity: null };
|
|
193
216
|
result = { ...result, ...fallback, reason: 'model-unavailable' };
|
|
194
217
|
}
|
|
195
218
|
const route = result.tier ? routeOf(result) : null;
|
|
@@ -198,20 +221,12 @@ function routeTurn(config, loop, { facts, advice, pin, nativeModel, contextKnown
|
|
|
198
221
|
let comparison = null;
|
|
199
222
|
const candidate = pin ?? advice?.choice;
|
|
200
223
|
if (contextKnown && loop.lastRequest && TIERS.includes(candidate) && candidate !== loop.lastRoute) {
|
|
201
|
-
const tokens = costs.nextContextTokens(facts);
|
|
202
224
|
const [to, from] = [resolveRoute(config, candidate, activity), routeOf(last)];
|
|
203
|
-
const proposed = costs.inputBounds(projected, to, tokens, facts, now);
|
|
204
|
-
const incumbentBounds = costs.inputBounds(projected, from, tokens, facts, now);
|
|
205
225
|
const forecast = costs.shadowEconomics(projected, to, from, facts, now);
|
|
206
|
-
// Without both output prices, compare input only, as shadowEconomics does.
|
|
207
|
-
const output = forecast
|
|
208
|
-
? ((routeSpec(projected, to).output - routeSpec(projected, from).output) * loop.lastRequest.outputTokens) / 1e6
|
|
209
|
-
: 0;
|
|
210
226
|
comparison = {
|
|
211
227
|
candidate,
|
|
212
228
|
incumbent: loop.lastRoute,
|
|
213
|
-
|
|
214
|
-
maxUsd: proposed.max - incumbentBounds.min + output,
|
|
229
|
+
...costs.nextTurnRange(projected, to, from, facts, now),
|
|
215
230
|
paybackTurns: forecast?.paybackTurns ?? null,
|
|
216
231
|
outputTokens: loop.lastRequest.outputTokens,
|
|
217
232
|
};
|
package/lib/savings.mjs
ADDED
|
@@ -0,0 +1,237 @@
|
|
|
1
|
+
// Routing vs your model: what each main reply cost at configured list prices on the model that served it, against
|
|
2
|
+
// the same tokens on the session's own model and effort ("your model"). Counts and dollars only, never text. Pure:
|
|
3
|
+
// the hook feeds each reply and keeps the totals in the view and, per session, in $.store under SAVINGS_PREFIX.
|
|
4
|
+
|
|
5
|
+
import { ratesAt } from './cost.mjs';
|
|
6
|
+
import { HISTORY_SHRINK, isSameModel } from './route.mjs';
|
|
7
|
+
|
|
8
|
+
// Each session keeps its own record under this prefix and its session id: $.store has no atomic update, and Claude
|
|
9
|
+
// Code 2.1.296 writes one key under a file lock (observed, not in the types), so sessions finishing turns at the same
|
|
10
|
+
// moment do not overwrite each other.
|
|
11
|
+
export const SAVINGS_PREFIX = 'savings:v1:';
|
|
12
|
+
// When Reset stats last ran (ms), from any session: a session may still hold its record from before and write it back.
|
|
13
|
+
export const SAVINGS_RESET_KEY = 'savings:reset:v1';
|
|
14
|
+
// Fewer replies than this read "too early": one switch and its cache write dominate a short run.
|
|
15
|
+
export const EARLY_REPLIES = 10;
|
|
16
|
+
const TTLS = ['5m', '1h'];
|
|
17
|
+
|
|
18
|
+
// The model entry an API model id runs on: its configured id, a dated snapshot of it, or the id with a context
|
|
19
|
+
// suffix such as `[1m]`. Null when no entry prices it.
|
|
20
|
+
export function modelSpec(config, id) {
|
|
21
|
+
if (typeof id !== 'string') return null;
|
|
22
|
+
const bare = id.replace(/\[[^\]]*\]$/, '');
|
|
23
|
+
const dated = (model) => bare.startsWith(model.id) && /^-\d{8}$/.test(bare.slice(model.id.length));
|
|
24
|
+
return Object.values(config.models).find((model) => isSameModel(model.id, bare) || dated(model)) ?? null;
|
|
25
|
+
}
|
|
26
|
+
|
|
27
|
+
// One request's list price in USD: `counts` are its uncached input, cache read, cache write and output tokens, the
|
|
28
|
+
// writes at `writeMultiplier` times input. Long-context rates follow the whole prompt.
|
|
29
|
+
export function requestUsd(model, { input, cacheRead, cacheWrite, output }, writeMultiplier) {
|
|
30
|
+
const rates = ratesAt(model, input + cacheRead + cacheWrite);
|
|
31
|
+
return (
|
|
32
|
+
(rates.input * (input + cacheWrite * writeMultiplier) + rates.cacheRead * cacheRead + rates.output * output) / 1e6
|
|
33
|
+
);
|
|
34
|
+
}
|
|
35
|
+
|
|
36
|
+
const truthy = (value) => /^(1|true|yes|on)$/i.test(String(value ?? '').trim());
|
|
37
|
+
|
|
38
|
+
// The prompt-cache lifetime Claude Code gives the main conversation, by its own rule as of 2.1.296: FORCE_PROMPT_CACHING_5M,
|
|
39
|
+
// then CLAUDE_CODE_PROMPT_CACHE_TTL, then the `promptCacheTtl` setting, then ENABLE_PROMPT_CACHING_1H, then one hour
|
|
40
|
+
// for a Claude plan subscriber and five minutes otherwise. Its usage reports carry no 5m/1h split, so this is how the
|
|
41
|
+
// writes are priced. Limit: a subscriber billed as overage gets five minutes, which this cannot see.
|
|
42
|
+
export function sessionCacheTtl({ force5m, envTtl, settingTtl, enable1h, subscriber }) {
|
|
43
|
+
if (truthy(force5m)) return '5m';
|
|
44
|
+
if (TTLS.includes(envTtl)) return envTtl;
|
|
45
|
+
if (TTLS.includes(settingTtl)) return settingTtl;
|
|
46
|
+
if (truthy(enable1h) || subscriber) return '1h';
|
|
47
|
+
return '5m';
|
|
48
|
+
}
|
|
49
|
+
|
|
50
|
+
const isCount = (n) => Number.isFinite(n) && n >= 0;
|
|
51
|
+
|
|
52
|
+
// One main reply. `state` is your model's simulated cache: `{ total, at, onYours, model, effort }` after a reply, or
|
|
53
|
+
// null at the session start and after a compaction, which counts as on your model with nothing cached; a state of
|
|
54
|
+
// another model or effort (after `/model` or an effort change) counts as null. `served` is the route the
|
|
55
|
+
// reply ran on, `{ model, effort }` with the API's model id; `yours` the session's model and effort.
|
|
56
|
+
//
|
|
57
|
+
// Routed is the reply's usage on the served model. Yours is the same tokens on your model: while this reply and the
|
|
58
|
+
// one before it both ran on your route, the usage itself, so equal routes differ by exactly 0. Otherwise a single
|
|
59
|
+
// cache that never switched: it reads the previous prompt, up to this one less its uncached input, if that is inside
|
|
60
|
+
// the cache lifetime and no compaction shrank the history, and never less than the API actually read (a shared
|
|
61
|
+
// system-prompt cache, a lifetime longer than assumed); it writes the rest. Output tokens stay the same.
|
|
62
|
+
//
|
|
63
|
+
// The difference splits into the model price (the served model on your cache, against yours: cheaper models when
|
|
64
|
+
// negative, stronger than yours when positive) and the cache the switches cost (routed against the served model on
|
|
65
|
+
// your cache), never negative. The parts sum to the difference by construction. `reply` is null when a model has no
|
|
66
|
+
// price or `ttl` is not a known cache lifetime.
|
|
67
|
+
export function compareReply(config, state, { usage, served, yours, ttl, now }) {
|
|
68
|
+
const counts = {
|
|
69
|
+
input: usage?.input_tokens,
|
|
70
|
+
cacheRead: usage?.cache_read_input_tokens,
|
|
71
|
+
cacheWrite: usage?.cache_creation_input_tokens,
|
|
72
|
+
output: usage?.output_tokens,
|
|
73
|
+
};
|
|
74
|
+
if (!Object.values(counts).every(isCount)) return { state, reply: null };
|
|
75
|
+
const total = counts.input + counts.cacheRead + counts.cacheWrite;
|
|
76
|
+
const [servedSpec, yoursSpec] = [modelSpec(config, served.model), modelSpec(config, yours.model)];
|
|
77
|
+
const sameModel = servedSpec ? servedSpec === yoursSpec : served.model === yours.model;
|
|
78
|
+
const onYours = sameModel && (served.effort ?? null) === (yours.effort ?? null);
|
|
79
|
+
const identity = { model: yoursSpec?.id ?? yours.model, effort: yours.effort ?? null };
|
|
80
|
+
const next = { total, at: now, onYours, ...identity };
|
|
81
|
+
// A cache simulated for another model or effort of yours is none of this one's: the new one starts cold.
|
|
82
|
+
const prior = state?.model === identity.model && state.effort === identity.effort ? state : null;
|
|
83
|
+
const write = config.cache.writeMultiplier[ttl];
|
|
84
|
+
if (
|
|
85
|
+
!servedSpec ||
|
|
86
|
+
!yoursSpec ||
|
|
87
|
+
!Number.isFinite(servedSpec.output) ||
|
|
88
|
+
!Number.isFinite(yoursSpec.output) ||
|
|
89
|
+
!Number.isFinite(write)
|
|
90
|
+
)
|
|
91
|
+
return { state: next, reply: null };
|
|
92
|
+
const routedUsd = requestUsd(servedSpec, counts, write);
|
|
93
|
+
let yoursUsd = routedUsd;
|
|
94
|
+
let servedOnYoursUsd = routedUsd;
|
|
95
|
+
if (!(onYours && (prior?.onYours ?? true))) {
|
|
96
|
+
const warm =
|
|
97
|
+
prior && now - prior.at < config.cache.ttlMs[ttl] && total >= prior.total * HISTORY_SHRINK && prior.total > 0;
|
|
98
|
+
const cacheRead = Math.max(counts.cacheRead, warm ? Math.min(prior.total, total - counts.input) : 0);
|
|
99
|
+
const single = { ...counts, cacheRead, cacheWrite: total - counts.input - cacheRead };
|
|
100
|
+
yoursUsd = requestUsd(yoursSpec, single, write);
|
|
101
|
+
servedOnYoursUsd = requestUsd(servedSpec, single, write);
|
|
102
|
+
}
|
|
103
|
+
const modelUsd = servedOnYoursUsd - yoursUsd;
|
|
104
|
+
return {
|
|
105
|
+
state: next,
|
|
106
|
+
reply: {
|
|
107
|
+
routedUsd,
|
|
108
|
+
yoursUsd,
|
|
109
|
+
cheaperUsd: Math.min(0, modelUsd),
|
|
110
|
+
strongerUsd: Math.max(0, modelUsd),
|
|
111
|
+
switchUsd: routedUsd - servedOnYoursUsd,
|
|
112
|
+
// The model a stronger reply ran on, for "9 replies on Opus 5.5".
|
|
113
|
+
strongerModel: modelUsd > 0 ? servedSpec.id : null,
|
|
114
|
+
},
|
|
115
|
+
};
|
|
116
|
+
}
|
|
117
|
+
|
|
118
|
+
const SUMS = ['routedUsd', 'yoursUsd', 'cheaperUsd', 'strongerUsd', 'switchUsd'];
|
|
119
|
+
|
|
120
|
+
// A session's totals: replies, the five sums, and per tier (`none`: not chosen by routing) the replies and their
|
|
121
|
+
// routed cost, which the pane's bar and share line draw. `stronger` counts replies by the stronger model they ran on.
|
|
122
|
+
export function emptyTotals() {
|
|
123
|
+
return {
|
|
124
|
+
replies: 0,
|
|
125
|
+
routedUsd: 0,
|
|
126
|
+
yoursUsd: 0,
|
|
127
|
+
cheaperUsd: 0,
|
|
128
|
+
strongerUsd: 0,
|
|
129
|
+
switchUsd: 0,
|
|
130
|
+
tiers: {},
|
|
131
|
+
tierUsd: {},
|
|
132
|
+
stronger: {},
|
|
133
|
+
};
|
|
134
|
+
}
|
|
135
|
+
|
|
136
|
+
export function addReply(totals, reply, tier) {
|
|
137
|
+
const key = tier ?? 'none';
|
|
138
|
+
const next = { ...totals, replies: totals.replies + 1 };
|
|
139
|
+
for (const sum of SUMS) next[sum] = totals[sum] + reply[sum];
|
|
140
|
+
next.tiers = { ...totals.tiers, [key]: (totals.tiers[key] ?? 0) + 1 };
|
|
141
|
+
next.tierUsd = { ...totals.tierUsd, [key]: (totals.tierUsd[key] ?? 0) + reply.routedUsd };
|
|
142
|
+
if (reply.strongerModel)
|
|
143
|
+
next.stronger = { ...totals.stronger, [reply.strongerModel]: (totals.stronger[reply.strongerModel] ?? 0) + 1 };
|
|
144
|
+
return next;
|
|
145
|
+
}
|
|
146
|
+
|
|
147
|
+
// A record kept across sessions, one session's or their sum: replies and the five sums since `since` (ms), the first
|
|
148
|
+
// reply after a reset.
|
|
149
|
+
export function emptySavingsStore() {
|
|
150
|
+
return {
|
|
151
|
+
version: 1,
|
|
152
|
+
since: null,
|
|
153
|
+
replies: 0,
|
|
154
|
+
routedUsd: 0,
|
|
155
|
+
yoursUsd: 0,
|
|
156
|
+
cheaperUsd: 0,
|
|
157
|
+
strongerUsd: 0,
|
|
158
|
+
switchUsd: 0,
|
|
159
|
+
};
|
|
160
|
+
}
|
|
161
|
+
|
|
162
|
+
const STORE_KEYS = Object.keys(emptySavingsStore());
|
|
163
|
+
|
|
164
|
+
// The stored value if it has the known shape, else an empty store: a missing, hand-edited or unknown value must not
|
|
165
|
+
// break a turn or the pane.
|
|
166
|
+
export function readSavingsStore(value) {
|
|
167
|
+
const ok =
|
|
168
|
+
value !== null &&
|
|
169
|
+
typeof value === 'object' &&
|
|
170
|
+
!Array.isArray(value) &&
|
|
171
|
+
Object.keys(value).length === STORE_KEYS.length &&
|
|
172
|
+
STORE_KEYS.every((key) => Object.hasOwn(value, key)) &&
|
|
173
|
+
value.version === 1 &&
|
|
174
|
+
(value.since === null || Number.isFinite(value.since)) &&
|
|
175
|
+
Number.isSafeInteger(value.replies) &&
|
|
176
|
+
value.replies >= 0 &&
|
|
177
|
+
SUMS.every((sum) => Number.isFinite(value[sum]));
|
|
178
|
+
return ok ? { ...value } : emptySavingsStore();
|
|
179
|
+
}
|
|
180
|
+
|
|
181
|
+
// A record whose first reply came before the last reset at `resetAt` (ms) reads as empty.
|
|
182
|
+
export function afterReset(record, resetAt) {
|
|
183
|
+
return Number.isFinite(resetAt) && record.since !== null && record.since < resetAt ? emptySavingsStore() : record;
|
|
184
|
+
}
|
|
185
|
+
|
|
186
|
+
// The totals kept across sessions: every session's record since the last reset added up, since the earliest.
|
|
187
|
+
export function mergeSavingsStores(values, resetAt = null) {
|
|
188
|
+
const merged = emptySavingsStore();
|
|
189
|
+
for (const one of values.map((value) => afterReset(readSavingsStore(value), resetAt))) {
|
|
190
|
+
const since = [merged.since, one.since].filter(Number.isFinite);
|
|
191
|
+
merged.since = since.length ? Math.min(...since) : null;
|
|
192
|
+
merged.replies += one.replies;
|
|
193
|
+
for (const sum of SUMS) merged[sum] += one[sum];
|
|
194
|
+
}
|
|
195
|
+
return merged;
|
|
196
|
+
}
|
|
197
|
+
|
|
198
|
+
// A finished turn's totals added to the store at `now`.
|
|
199
|
+
export function recordSavingsStore(store, totals, now) {
|
|
200
|
+
if (!totals.replies) return store;
|
|
201
|
+
const next = { ...store, since: store.since ?? now, replies: store.replies + totals.replies };
|
|
202
|
+
for (const sum of SUMS) next[sum] = store[sum] + totals[sum];
|
|
203
|
+
return next;
|
|
204
|
+
}
|
|
205
|
+
|
|
206
|
+
const cents = (usd) => Math.round(usd * 100);
|
|
207
|
+
|
|
208
|
+
// What the UI shows for a set of totals, in whole cents so the shown parts add up: the difference is routed less
|
|
209
|
+
// yours as shown, and the switch part takes the rounding remainder. A surplus goes to the switch part if the totals
|
|
210
|
+
// have one, else to the stronger part if they have one, else to the cheaper part toward 0. A shortfall comes off the
|
|
211
|
+
// stronger part down to 0, then the cheaper part. So no part changes sign or appears from rounding alone. `early`
|
|
212
|
+
// below EARLY_REPLIES replies. `share` is the difference against yours; `ratio` routed over yours.
|
|
213
|
+
export function readout(totals) {
|
|
214
|
+
const [routed, yours, cheaper, stronger] = [
|
|
215
|
+
totals.routedUsd,
|
|
216
|
+
totals.yoursUsd,
|
|
217
|
+
totals.cheaperUsd,
|
|
218
|
+
totals.strongerUsd,
|
|
219
|
+
].map(cents);
|
|
220
|
+
const difference = routed - yours;
|
|
221
|
+
const rest = difference - cheaper - stronger;
|
|
222
|
+
const switches = totals.switchUsd ? Math.max(0, rest) : 0;
|
|
223
|
+
const surplus = !totals.switchUsd && totals.strongerUsd ? Math.max(0, rest) : 0;
|
|
224
|
+
const strongerShown = Math.max(0, stronger + Math.min(0, rest)) + surplus;
|
|
225
|
+
return {
|
|
226
|
+
replies: totals.replies,
|
|
227
|
+
early: totals.replies < EARLY_REPLIES,
|
|
228
|
+
routedUsd: routed / 100,
|
|
229
|
+
yoursUsd: yours / 100,
|
|
230
|
+
differenceUsd: difference / 100,
|
|
231
|
+
cheaperUsd: (difference - strongerShown - switches) / 100,
|
|
232
|
+
strongerUsd: strongerShown / 100,
|
|
233
|
+
switchUsd: switches / 100,
|
|
234
|
+
share: yours > 0 ? difference / yours : null,
|
|
235
|
+
ratio: yours > 0 ? routed / yours : null,
|
|
236
|
+
};
|
|
237
|
+
}
|
package/lib/view.mjs
CHANGED
|
@@ -10,6 +10,8 @@ export function initialView(model) {
|
|
|
10
10
|
activeTurnId: null,
|
|
11
11
|
mode: 'auto',
|
|
12
12
|
nativeModel: model,
|
|
13
|
+
// The effort Claude Code sent on the turn's first request, before routing: with nativeModel, "your model".
|
|
14
|
+
nativeEffort: null,
|
|
13
15
|
selectedModel: null,
|
|
14
16
|
actualModel: null,
|
|
15
17
|
tier: null,
|
|
@@ -37,7 +39,12 @@ export function initialView(model) {
|
|
|
37
39
|
history: [],
|
|
38
40
|
tiers: [],
|
|
39
41
|
activities: [],
|
|
42
|
+
routes: [],
|
|
40
43
|
activityStats: null,
|
|
44
|
+
activityStore: null,
|
|
45
|
+
// Routing vs your model: this session's totals and the totals kept across sessions as last read or written.
|
|
46
|
+
savings: null,
|
|
47
|
+
savingsStore: null,
|
|
41
48
|
configPath: null,
|
|
42
49
|
tuning: null,
|
|
43
50
|
tuningBase: null,
|
|
@@ -78,7 +85,8 @@ export function continuationView(config, decision, context) {
|
|
|
78
85
|
|
|
79
86
|
// The view patch for a main reply's usage. `tier` is the routed tier that served it, else null; `activity` the
|
|
80
87
|
// turn's activity as the view labels it, else null.
|
|
81
|
-
|
|
88
|
+
// `route` is the (model, effort) the request went out with, so the switch count reads what served each reply.
|
|
89
|
+
export function responseMetrics(view, response, tier, activity = null, route = null) {
|
|
82
90
|
const usage = response.usage;
|
|
83
91
|
const counters = usage ? [usage.input_tokens, usage.cache_read_input_tokens, usage.cache_creation_input_tokens] : [];
|
|
84
92
|
const inputTokens =
|
|
@@ -95,6 +103,7 @@ export function responseMetrics(view, response, tier, activity = null) {
|
|
|
95
103
|
history: [...(view?.history ?? []), inputTokens].slice(-HISTORY),
|
|
96
104
|
tiers: [...(view?.tiers ?? []), tier ?? null].slice(-HISTORY),
|
|
97
105
|
activities: [...(view?.activities ?? []), activity ?? null].slice(-HISTORY),
|
|
106
|
+
routes: [...(view?.routes ?? []), route ?? null].slice(-HISTORY),
|
|
98
107
|
}
|
|
99
108
|
: {}),
|
|
100
109
|
};
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@alexeiled/claude-router",
|
|
3
|
-
"version": "1.
|
|
3
|
+
"version": "1.7.0",
|
|
4
4
|
"description": "Native Claude Code Mod: model and effort routing for the main conversation, advised by Jev, Clef, Clef Flash, OpenAI or Ollama.",
|
|
5
5
|
"license": "MIT",
|
|
6
6
|
"author": "Alexei Ledenev",
|
package/types/index.d.ts
CHANGED
|
@@ -18,13 +18,26 @@ declare module 'claude-code' {
|
|
|
18
18
|
probabilities: Record<RouterActivityAnswer, number>;
|
|
19
19
|
} | null;
|
|
20
20
|
}
|
|
21
|
-
//
|
|
21
|
+
// A next-request cost difference in USD at configured list prices; negative is cheaper.
|
|
22
|
+
interface RouterUsdRange {
|
|
23
|
+
minUsd: number;
|
|
24
|
+
maxUsd: number;
|
|
25
|
+
}
|
|
26
|
+
// What `on` would do, computed in `shadow`. `model` is a model id, as `decision.model`. `difference` prices its next
|
|
27
|
+
// request against the applied route's; null when the routes match or there is no measured request yet.
|
|
22
28
|
interface RouterWouldRoute {
|
|
23
29
|
activity: RouterActivity | null;
|
|
24
30
|
tier: RouterTier | null;
|
|
25
31
|
model: string;
|
|
26
32
|
effort: string | number | null;
|
|
27
33
|
reason: string;
|
|
34
|
+
difference: RouterUsdRange | null;
|
|
35
|
+
}
|
|
36
|
+
// Shadow turns, those `on` would route differently, and of those the ones with a `difference`, summed.
|
|
37
|
+
interface RouterActivityShadow extends RouterUsdRange {
|
|
38
|
+
differs: number;
|
|
39
|
+
turns: number;
|
|
40
|
+
estimated: number;
|
|
28
41
|
}
|
|
29
42
|
interface RouterActivityCounts {
|
|
30
43
|
turns: number;
|
|
@@ -37,7 +50,7 @@ declare module 'claude-code' {
|
|
|
37
50
|
byActivity: Partial<Record<RouterActivity | 'none', RouterActivityCounts>>;
|
|
38
51
|
switches: { tier: number; activity: number };
|
|
39
52
|
agreement: { matched: number; total: number };
|
|
40
|
-
shadow:
|
|
53
|
+
shadow: RouterActivityShadow;
|
|
41
54
|
}
|
|
42
55
|
// Cross-session counts under store key 'activity:stats:v1'. `runs` buckets run lengths 1, 2, 3, 4, 5+.
|
|
43
56
|
interface RouterActivityStore {
|
|
@@ -45,7 +58,8 @@ declare module 'claude-code' {
|
|
|
45
58
|
confusion: Partial<Record<RouterActivityAnswer | 'none', Partial<Record<RouterObserved, number>>>>;
|
|
46
59
|
runs: Partial<Record<RouterActivity, [number, number, number, number, number]>>;
|
|
47
60
|
lateral: { taken: number; refused: number };
|
|
48
|
-
|
|
61
|
+
// A 1.6.0 store has `differs` and `turns` only; readStore fills the rest with zeros.
|
|
62
|
+
shadow: RouterActivityShadow;
|
|
49
63
|
}
|
|
50
64
|
interface RouterComparison {
|
|
51
65
|
candidate: RouterTier;
|
|
@@ -84,10 +98,35 @@ declare module 'claude-code' {
|
|
|
84
98
|
>;
|
|
85
99
|
activityRouting?: RouterActivityMode;
|
|
86
100
|
}
|
|
101
|
+
// Routing vs your model at configured list prices, in USD: routed replies, the same tokens on your model, and the
|
|
102
|
+
// difference's parts (cheaper models, stronger than yours, cache writes from switches), which sum to it.
|
|
103
|
+
interface RouterSavingsSums {
|
|
104
|
+
replies: number;
|
|
105
|
+
routedUsd: number;
|
|
106
|
+
yoursUsd: number;
|
|
107
|
+
cheaperUsd: number;
|
|
108
|
+
strongerUsd: number;
|
|
109
|
+
switchUsd: number;
|
|
110
|
+
}
|
|
111
|
+
// A session's totals; per tier ('none': not chosen by routing) its replies and their routed cost, and replies by the
|
|
112
|
+
// stronger model they ran on.
|
|
113
|
+
interface RouterSavingsSession extends RouterSavingsSums {
|
|
114
|
+
tiers: Partial<Record<RouterTier | 'none', number>>;
|
|
115
|
+
tierUsd: Partial<Record<RouterTier | 'none', number>>;
|
|
116
|
+
stronger: Record<string, number>;
|
|
117
|
+
}
|
|
118
|
+
// Totals kept across sessions, one per session under store key 'savings:v1:<session id>' or their sum in the view,
|
|
119
|
+
// since the first reply after the last reset (ms).
|
|
120
|
+
interface RouterSavingsStore extends RouterSavingsSums {
|
|
121
|
+
version: 1;
|
|
122
|
+
since: number | null;
|
|
123
|
+
}
|
|
87
124
|
interface RouterView {
|
|
88
125
|
phase: 'ready' | 'choosing' | 'routed' | 'manual' | 'unavailable';
|
|
89
126
|
mode: 'auto' | 'manual';
|
|
90
127
|
nativeModel: string;
|
|
128
|
+
// The effort Claude Code sent on the turn's first request, before routing.
|
|
129
|
+
nativeEffort?: string | number | null;
|
|
91
130
|
activeTurnId?: string | null;
|
|
92
131
|
selectedModel?: string | null;
|
|
93
132
|
actualModel?: string | null;
|
|
@@ -119,7 +158,13 @@ declare module 'claude-code' {
|
|
|
119
158
|
tiers?: (RouterTier | null)[];
|
|
120
159
|
// Aligned with `history` and `tiers`.
|
|
121
160
|
activities?: (RouterActivity | null)[];
|
|
161
|
+
// The (model, effort) each reply's request went out with, aligned with tiers; null where routing did not choose.
|
|
162
|
+
routes?: (string | null)[];
|
|
122
163
|
activityStats?: RouterActivitySession | null;
|
|
164
|
+
// The counts kept across sessions as last read or written.
|
|
165
|
+
activityStore?: RouterActivityStore | null;
|
|
166
|
+
savings?: RouterSavingsSession | null;
|
|
167
|
+
savingsStore?: RouterSavingsStore | null;
|
|
123
168
|
configPath?: string | null;
|
|
124
169
|
tuning?: Partial<RouterTuning> | null;
|
|
125
170
|
tuningBase?: RouterTuning | null;
|
|
@@ -173,6 +218,9 @@ declare module 'claude-code' {
|
|
|
173
218
|
requestedPin: RouterTier | null;
|
|
174
219
|
} | null;
|
|
175
220
|
ineligible: string[];
|
|
221
|
+
// Your model's simulated cache for routing vs your model: the last prompt's tokens, when, whether that reply ran
|
|
222
|
+
// on your route, and the model and effort it was kept for. Null at the start and after a compaction.
|
|
223
|
+
yours?: { total: number; at: number; onYours: boolean; model: string; effort: string | null } | null;
|
|
176
224
|
engineModel?: string;
|
|
177
225
|
suspended?: boolean;
|
|
178
226
|
}
|