@alexeiled/claude-router 0.8.0 → 1.1.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 +11 -7
- package/CHANGELOG.md +43 -0
- package/README.md +55 -98
- package/docs/architecture.md +55 -419
- package/docs/configuration.md +88 -182
- package/docs/evaluation.md +62 -81
- package/docs/native-router.md +80 -0
- package/docs/router-band.svg +119 -0
- package/docs/router-pane-now.svg +85 -0
- package/docs/router-pane-tiers.svg +62 -0
- package/docs/user-guide.md +127 -172
- package/hooks/hooks.json +1 -26
- package/hooks/native-router.mjs +701 -0
- package/lib/config.mjs +97 -63
- package/lib/{facts.mjs → facts-pure.mjs} +2 -23
- package/lib/{jev.mjs → jev-contract.mjs} +17 -38
- package/lib/native-band.mjs +206 -0
- package/lib/native-cost.mjs +88 -0
- package/lib/native-display.mjs +122 -0
- package/lib/native-jev.mjs +125 -0
- package/lib/native-panel.mjs +492 -0
- package/lib/native-router.mjs +221 -0
- package/lib/policy.mjs +17 -21
- package/package.json +10 -8
- package/scripts/migrate-config.mjs +57 -0
- package/types/index.d.ts +112 -0
- package/lib/cost.mjs +0 -93
- package/lib/gateway.mjs +0 -221
- package/lib/idle.mjs +0 -41
- package/lib/rewrite.mjs +0 -130
- package/lib/router.mjs +0 -276
- package/lib/runtime.mjs +0 -78
- package/lib/sse.mjs +0 -57
- package/lib/status.mjs +0 -152
- package/lib/store.mjs +0 -76
- package/scripts/ensure-gateway.mjs +0 -143
- package/scripts/gateway.mjs +0 -81
- package/scripts/git-hooks/pre-commit +0 -41
- package/scripts/git-hooks/pre-push +0 -34
- package/scripts/status.mjs +0 -20
- package/scripts/statusline.mjs +0 -45
- package/scripts/transcript-models.sh +0 -4
- package/skills/high/SKILL.md +0 -9
- package/skills/low/SKILL.md +0 -7
- package/skills/medium/SKILL.md +0 -8
- package/skills/micro/SKILL.md +0 -7
- package/skills/setup/SKILL.md +0 -31
- package/skills/status/SKILL.md +0 -12
|
@@ -0,0 +1,221 @@
|
|
|
1
|
+
import { TIERS } from './config.mjs';
|
|
2
|
+
import { clip, extractFacts } from './facts-pure.mjs';
|
|
3
|
+
import * as costs from './native-cost.mjs';
|
|
4
|
+
import { decide, fitTier, initialState } from './policy.mjs';
|
|
5
|
+
|
|
6
|
+
// Exact observed API snapshot, not a rule that merges different dated versions.
|
|
7
|
+
export const SNAPSHOTS = { 'claude-haiku-4-5': 'claude-haiku-4-5-20251001' };
|
|
8
|
+
|
|
9
|
+
// Whether the engine served the requested model, allowing for a dated snapshot of it.
|
|
10
|
+
export function isSameModel(requested, served) {
|
|
11
|
+
return requested === served || SNAPSHOTS[requested] === served;
|
|
12
|
+
}
|
|
13
|
+
|
|
14
|
+
export function tierForModel(config, id) {
|
|
15
|
+
const order = [config.baselineTier, ...TIERS.filter((tier) => tier !== config.baselineTier)];
|
|
16
|
+
return (
|
|
17
|
+
order.find((tier) => {
|
|
18
|
+
const model = config.models[config.routes[tier].model];
|
|
19
|
+
return isSameModel(model.id, id);
|
|
20
|
+
}) ?? null
|
|
21
|
+
);
|
|
22
|
+
}
|
|
23
|
+
|
|
24
|
+
export function emptyLoop(config, model) {
|
|
25
|
+
return {
|
|
26
|
+
lastRoute: tierForModel(config, model) ?? config.baselineTier,
|
|
27
|
+
state: initialState(),
|
|
28
|
+
models: {},
|
|
29
|
+
resolutions: {},
|
|
30
|
+
lastRequest: null,
|
|
31
|
+
historyMeasured: false,
|
|
32
|
+
lastMessageCount: null,
|
|
33
|
+
generation: 0,
|
|
34
|
+
turnId: null,
|
|
35
|
+
decision: null,
|
|
36
|
+
ineligible: [],
|
|
37
|
+
};
|
|
38
|
+
}
|
|
39
|
+
|
|
40
|
+
export function resetHistory(loop) {
|
|
41
|
+
return {
|
|
42
|
+
...loop,
|
|
43
|
+
generation: loop.generation + 1,
|
|
44
|
+
models: {},
|
|
45
|
+
resolutions: {},
|
|
46
|
+
historyMeasured: false,
|
|
47
|
+
state: { ...loop.state, votes: [], holdUntilTurn: 0, escalatedSignature: null },
|
|
48
|
+
// The active turn keeps its route, pin and fallback suspension; the next turn decides afresh.
|
|
49
|
+
ineligible: [],
|
|
50
|
+
};
|
|
51
|
+
}
|
|
52
|
+
|
|
53
|
+
export function prepareLoop(loop, messageCount) {
|
|
54
|
+
const next = loop.lastMessageCount !== null && messageCount < loop.lastMessageCount ? resetHistory(loop) : loop;
|
|
55
|
+
return { ...next, lastMessageCount: messageCount };
|
|
56
|
+
}
|
|
57
|
+
|
|
58
|
+
export function nativeFacts(config, loop, { messages, prompt, effort, turnId, contextTokens }) {
|
|
59
|
+
const facts = extractFacts({ messages, output_config: { effort } }, loop, config.context);
|
|
60
|
+
if (typeof prompt === 'string') facts.prompt = clip(prompt, config.context.maxTextChars);
|
|
61
|
+
return { ...facts, pin: null, contextTokens, turnKey: turnId };
|
|
62
|
+
}
|
|
63
|
+
|
|
64
|
+
export function isModelAllowed(id, available, nativeModel) {
|
|
65
|
+
if (available === undefined) return true;
|
|
66
|
+
if (!Array.isArray(available) || !available.every((v) => typeof v === 'string')) return false;
|
|
67
|
+
if (available.includes('default') && id === nativeModel) return true;
|
|
68
|
+
const family = /^claude-(opus|sonnet|haiku)-/.exec(id)?.[1];
|
|
69
|
+
const specific = available.filter((v) => family && v.startsWith(`claude-${family}-`));
|
|
70
|
+
if (specific.length) return specific.some((v) => id === v || id.startsWith(`${v}-`));
|
|
71
|
+
return available.some((v) => id === v || id.startsWith(`${v}-`) || (family && v === family));
|
|
72
|
+
}
|
|
73
|
+
|
|
74
|
+
function economicConfig(config, loop) {
|
|
75
|
+
const models = Object.fromEntries(
|
|
76
|
+
Object.entries(config.models).map(([alias, model]) => [
|
|
77
|
+
alias,
|
|
78
|
+
{ ...model, id: Object.hasOwn(loop.resolutions, model.id) ? loop.resolutions[model.id] : model.id },
|
|
79
|
+
]),
|
|
80
|
+
);
|
|
81
|
+
return { ...config, models };
|
|
82
|
+
}
|
|
83
|
+
|
|
84
|
+
export function chooseRoute(config, loop, { facts, advice, pin, nativeModel, contextKnown, availableModels, now }) {
|
|
85
|
+
const projected = economicConfig(config, loop);
|
|
86
|
+
let result =
|
|
87
|
+
pin && TIERS.includes(pin)
|
|
88
|
+
? { tier: pin, reason: 'pinned', state: { ...loop.state, turn: loop.state.turn + 1 } }
|
|
89
|
+
: decide({
|
|
90
|
+
config: projected,
|
|
91
|
+
facts,
|
|
92
|
+
advice,
|
|
93
|
+
state: loop.state,
|
|
94
|
+
baseline: config.baselineTier,
|
|
95
|
+
now,
|
|
96
|
+
costs,
|
|
97
|
+
});
|
|
98
|
+
const fits = (tier) => {
|
|
99
|
+
const model = config.models[config.routes[tier].model];
|
|
100
|
+
if (
|
|
101
|
+
(!contextKnown || !loop.historyMeasured) &&
|
|
102
|
+
model.contextWindow < config.models[config.routes[loop.lastRoute].model].contextWindow
|
|
103
|
+
)
|
|
104
|
+
return false;
|
|
105
|
+
return (
|
|
106
|
+
isModelAllowed(model.id, availableModels, nativeModel) &&
|
|
107
|
+
!loop.ineligible.includes(model.id) &&
|
|
108
|
+
(!contextKnown || costs.nextContextTokens(facts) <= model.contextWindow * 0.8)
|
|
109
|
+
);
|
|
110
|
+
};
|
|
111
|
+
if (contextKnown) {
|
|
112
|
+
const fitted = fitTier(config, result.tier, costs.nextContextTokens(facts));
|
|
113
|
+
if (fitted !== result.tier) result = { ...result, tier: fitted, reason: 'context-fit' };
|
|
114
|
+
}
|
|
115
|
+
if (
|
|
116
|
+
(!contextKnown || !loop.historyMeasured) &&
|
|
117
|
+
config.models[config.routes[result.tier].model].contextWindow <
|
|
118
|
+
config.models[config.routes[loop.lastRoute].model].contextWindow
|
|
119
|
+
) {
|
|
120
|
+
result = { ...result, tier: loop.lastRoute, reason: 'context-unknown' };
|
|
121
|
+
}
|
|
122
|
+
if (!fits(result.tier)) {
|
|
123
|
+
const fallback = [loop.lastRoute, tierForModel(config, nativeModel), ...TIERS].find((tier) => tier && fits(tier));
|
|
124
|
+
result = { ...result, tier: fallback ?? null, reason: 'model-unavailable' };
|
|
125
|
+
}
|
|
126
|
+
const model = result.tier ? config.models[config.routes[result.tier].model].id : nativeModel;
|
|
127
|
+
const effort = result.tier ? costs.routeEffort(config, result.tier, facts.effort) : facts.effort;
|
|
128
|
+
let comparison = null;
|
|
129
|
+
const candidate = pin ?? advice?.choice;
|
|
130
|
+
if (contextKnown && loop.lastRequest && TIERS.includes(candidate) && candidate !== loop.lastRoute) {
|
|
131
|
+
const tokens = costs.nextContextTokens(facts);
|
|
132
|
+
const proposed = costs.inputBounds(projected, candidate, tokens, facts, now);
|
|
133
|
+
const incumbent = costs.inputBounds(projected, loop.lastRoute, tokens, facts, now);
|
|
134
|
+
const forecast = costs.shadowEconomics(projected, candidate, loop.lastRoute, facts, now);
|
|
135
|
+
// Without both output prices, compare input only, as shadowEconomics does.
|
|
136
|
+
const output = forecast
|
|
137
|
+
? ((projected.models[projected.routes[candidate].model].output -
|
|
138
|
+
projected.models[projected.routes[loop.lastRoute].model].output) *
|
|
139
|
+
loop.lastRequest.outputTokens) /
|
|
140
|
+
1e6
|
|
141
|
+
: 0;
|
|
142
|
+
comparison = {
|
|
143
|
+
candidate,
|
|
144
|
+
incumbent: loop.lastRoute,
|
|
145
|
+
minUsd: proposed.min - incumbent.max + output,
|
|
146
|
+
maxUsd: proposed.max - incumbent.min + output,
|
|
147
|
+
paybackTurns: forecast?.paybackTurns ?? null,
|
|
148
|
+
outputTokens: loop.lastRequest.outputTokens,
|
|
149
|
+
};
|
|
150
|
+
}
|
|
151
|
+
const decision = { ...result, model, effort, comparison, pinned: Boolean(pin), requestedPin: pin ?? null };
|
|
152
|
+
return {
|
|
153
|
+
...loop,
|
|
154
|
+
state: result.state,
|
|
155
|
+
lastRoute: pin ? loop.lastRoute : (result.tier ?? loop.lastRoute),
|
|
156
|
+
turnId: facts.turnKey,
|
|
157
|
+
decision,
|
|
158
|
+
suspended: false,
|
|
159
|
+
};
|
|
160
|
+
}
|
|
161
|
+
|
|
162
|
+
export function continueRoute(config, loop, { nativeModel, contextTokens, contextKnown, availableModels, effort }) {
|
|
163
|
+
if (!loop.decision) return loop;
|
|
164
|
+
let decision = loop.decision;
|
|
165
|
+
if (contextKnown && decision.tier) {
|
|
166
|
+
const fitted = fitTier(config, decision.tier, contextTokens);
|
|
167
|
+
if (fitted !== decision.tier)
|
|
168
|
+
decision = {
|
|
169
|
+
...decision,
|
|
170
|
+
tier: fitted,
|
|
171
|
+
model: config.models[config.routes[fitted].model].id,
|
|
172
|
+
effort: costs.routeEffort(config, fitted, effort),
|
|
173
|
+
reason: 'context-fit',
|
|
174
|
+
};
|
|
175
|
+
}
|
|
176
|
+
if (!isModelAllowed(decision.model, availableModels, nativeModel) || loop.ineligible.includes(decision.model)) {
|
|
177
|
+
decision = { ...decision, tier: null, model: nativeModel, effort, reason: 'model-unavailable' };
|
|
178
|
+
}
|
|
179
|
+
return { ...loop, decision };
|
|
180
|
+
}
|
|
181
|
+
|
|
182
|
+
export function observeResponse(_config, loop, { usage, requestedModel, effort, stopReason, now }) {
|
|
183
|
+
let next = loop;
|
|
184
|
+
if (stopReason === 'model_context_window_exceeded') {
|
|
185
|
+
next = { ...next, ineligible: [...new Set([...next.ineligible, requestedModel])] };
|
|
186
|
+
}
|
|
187
|
+
if (!usage?.model) return next;
|
|
188
|
+
const sameModel = isSameModel(requestedModel, usage.model);
|
|
189
|
+
if (!sameModel) next = { ...next, suspended: true };
|
|
190
|
+
const counts = ['input_tokens', 'cache_read_input_tokens', 'cache_creation_input_tokens', 'output_tokens'];
|
|
191
|
+
if (!counts.every((key) => Number.isFinite(usage[key]) && usage[key] >= 0)) return next;
|
|
192
|
+
const tokens = usage.input_tokens + usage.cache_read_input_tokens + usage.cache_creation_input_tokens;
|
|
193
|
+
if (tokens === 0) return next;
|
|
194
|
+
const resolutions = sameModel ? { ...next.resolutions, [requestedModel]: usage.model } : { ...next.resolutions };
|
|
195
|
+
if (!sameModel) delete resolutions[requestedModel];
|
|
196
|
+
let models = next.models;
|
|
197
|
+
if (next.lastRequest && tokens < next.lastRequest.tokens * 0.8) models = {};
|
|
198
|
+
// A substituted model's effort is not reported, so do not credit its estimated cache.
|
|
199
|
+
if (sameModel)
|
|
200
|
+
models = {
|
|
201
|
+
...models,
|
|
202
|
+
[costs.cacheKey(usage.model, effort)]: {
|
|
203
|
+
lastAt: now,
|
|
204
|
+
prefixTokens: usage.cache_read_input_tokens + usage.cache_creation_input_tokens,
|
|
205
|
+
},
|
|
206
|
+
};
|
|
207
|
+
return {
|
|
208
|
+
...next,
|
|
209
|
+
historyMeasured: true,
|
|
210
|
+
models,
|
|
211
|
+
resolutions,
|
|
212
|
+
lastRequest: {
|
|
213
|
+
model: usage.model,
|
|
214
|
+
tokens,
|
|
215
|
+
outputTokens: usage.output_tokens,
|
|
216
|
+
cacheReadTokens: usage.cache_read_input_tokens,
|
|
217
|
+
cacheWriteTokens: usage.cache_creation_input_tokens,
|
|
218
|
+
at: now,
|
|
219
|
+
},
|
|
220
|
+
};
|
|
221
|
+
}
|
package/lib/policy.mjs
CHANGED
|
@@ -1,21 +1,13 @@
|
|
|
1
1
|
// Switching policy v0 (docs/architecture.md): stickiness, escalation floor, cost-gated votes.
|
|
2
2
|
import { rank, TIERS } from './config.mjs';
|
|
3
|
-
import
|
|
4
|
-
cacheState,
|
|
5
|
-
coldWriteUsd,
|
|
6
|
-
downgradeTaxUsd,
|
|
7
|
-
isWarm,
|
|
8
|
-
nextContextTokens,
|
|
9
|
-
routeCacheKey,
|
|
10
|
-
switchingTaxUsd,
|
|
11
|
-
} from './cost.mjs';
|
|
3
|
+
import * as nativeCosts from './native-cost.mjs';
|
|
12
4
|
|
|
13
5
|
export function initialState() {
|
|
14
6
|
return { turn: 0, votes: [], holdUntilTurn: 0, escalatedSignature: null };
|
|
15
7
|
}
|
|
16
8
|
|
|
17
9
|
// Returns { tier, reason, state, estimate }. `baseline` is the tier used when nothing argues otherwise.
|
|
18
|
-
export function decide({ config, facts, advice, state, baseline, now }) {
|
|
10
|
+
export function decide({ config, facts, advice, state, baseline, now, costs = nativeCosts }) {
|
|
19
11
|
const next = { ...state, turn: state.turn + 1, votes: [...state.votes] };
|
|
20
12
|
const incumbent = facts.lastRoute && TIERS.includes(facts.lastRoute) ? facts.lastRoute : baseline;
|
|
21
13
|
const stay = (reason, estimate = null) => result(incumbent, reason, next, estimate);
|
|
@@ -37,17 +29,20 @@ export function decide({ config, facts, advice, state, baseline, now }) {
|
|
|
37
29
|
|
|
38
30
|
if (rank(choice) > rank(incumbent)) {
|
|
39
31
|
const upgrade = massAbove(advice.probabilities, incumbent);
|
|
40
|
-
const gated = cashGate(config, choice, facts, now);
|
|
32
|
+
const gated = cashGate(config, choice, facts, now, costs);
|
|
41
33
|
if (gated.blocked) {
|
|
42
|
-
if (rank(gated.fallback) <= rank(incumbent)) return stay('cash-gate', gated.estimate);
|
|
34
|
+
if (!gated.fallback || rank(gated.fallback) <= rank(incumbent)) return stay('cash-gate', gated.estimate);
|
|
43
35
|
return result(gated.fallback, 'cash-gate', next, gated.estimate);
|
|
44
36
|
}
|
|
45
|
-
const tax = Math.max(0, switchingTaxUsd(config, choice, incumbent, facts, now));
|
|
37
|
+
const tax = Math.max(0, costs.switchingTaxUsd(config, choice, incumbent, facts, now));
|
|
46
38
|
const threshold =
|
|
47
39
|
config.policy.upgradeBase + config.policy.upgradeSlope * (tax / (tax + config.policy.upgradePivotUsd));
|
|
48
40
|
const jump = rank(choice) - rank(incumbent) >= 2 && upgrade >= config.policy.jumpConfidence;
|
|
49
41
|
const streak = trailing(next.votes, (v) => rank(v.tier) > rank(incumbent));
|
|
50
|
-
const cache = {
|
|
42
|
+
const cache = {
|
|
43
|
+
candidate: cacheOf(config, choice, facts, now, costs),
|
|
44
|
+
incumbent: cacheOf(config, incumbent, facts, now, costs),
|
|
45
|
+
};
|
|
51
46
|
const estimate = { taxUsd: tax, threshold, upgradeMass: upgrade, streak, cache };
|
|
52
47
|
if (jump || (streak >= config.policy.upgradeVotes && upgrade >= threshold))
|
|
53
48
|
return result(choice, jump ? 'jump' : 'upgrade', next, estimate);
|
|
@@ -58,7 +53,7 @@ export function decide({ config, facts, advice, state, baseline, now }) {
|
|
|
58
53
|
const streak = trailing(next.votes, (v) => rank(v.tier) <= rank(choice));
|
|
59
54
|
// A downgrade is not always cheaper this turn: a cold candidate next to a warm incumbent can pay a bigger cache
|
|
60
55
|
// write than it saves. The bar rises with that cost, net of what the next turns save, the way the upgrade bar does.
|
|
61
|
-
const tax = downgradeTaxUsd(config, choice, incumbent, facts, now, config.policy.downgradeHorizonTurns);
|
|
56
|
+
const tax = costs.downgradeTaxUsd(config, choice, incumbent, facts, now, config.policy.downgradeHorizonTurns);
|
|
62
57
|
const threshold =
|
|
63
58
|
config.policy.downgradeMass + config.policy.downgradeSlope * (tax / (tax + config.policy.downgradePivotUsd));
|
|
64
59
|
const estimate = { downgradeMass: support, streak, taxUsd: tax, threshold };
|
|
@@ -87,19 +82,20 @@ export function fitTier(config, tier, tokens) {
|
|
|
87
82
|
// Cold-write guard: an automatic route to a credits-billed model whose cache is not warm must not start with a cache
|
|
88
83
|
// write above `cashCapUsd`. It bounds that one estimated write, not the spend of the turn: a warm cache passes, and
|
|
89
84
|
// output is not counted.
|
|
90
|
-
function cashGate(config, tier, facts, now) {
|
|
85
|
+
function cashGate(config, tier, facts, now, costs) {
|
|
91
86
|
const alias = config.routes[tier].model;
|
|
92
87
|
if (config.models[alias].billing !== 'credits') return { blocked: false };
|
|
93
|
-
if (isWarm(facts.models[routeCacheKey(config, tier, facts.effort)], now, config.cache))
|
|
94
|
-
|
|
88
|
+
if (costs.isWarm(facts.models[costs.routeCacheKey(config, tier, facts.effort)], now, config.cache))
|
|
89
|
+
return { blocked: false };
|
|
90
|
+
const cold = costs.coldWriteUsd(config, alias, costs.nextContextTokens(facts), facts);
|
|
95
91
|
if (cold <= config.policy.cashCapUsd) return { blocked: false };
|
|
96
92
|
const fallback = [...TIERS].reverse().find((t) => config.models[config.routes[t].model].billing === 'plan');
|
|
97
|
-
const estimate = { coldUsd: cold, cap: config.policy.cashCapUsd, cache: cacheOf(config, tier, facts, now) };
|
|
93
|
+
const estimate = { coldUsd: cold, cap: config.policy.cashCapUsd, cache: cacheOf(config, tier, facts, now, costs) };
|
|
98
94
|
return { blocked: true, fallback, estimate };
|
|
99
95
|
}
|
|
100
96
|
|
|
101
|
-
function cacheOf(config, tier, facts, now) {
|
|
102
|
-
return cacheState(facts.models[routeCacheKey(config, tier, facts.effort)], now, config.cache);
|
|
97
|
+
function cacheOf(config, tier, facts, now, costs) {
|
|
98
|
+
return costs.cacheState(facts.models[costs.routeCacheKey(config, tier, facts.effort)], now, config.cache);
|
|
103
99
|
}
|
|
104
100
|
|
|
105
101
|
function trailing(votes, predicate) {
|
package/package.json
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@alexeiled/claude-router",
|
|
3
|
-
"version": "
|
|
4
|
-
"description": "Claude Code
|
|
3
|
+
"version": "1.1.0",
|
|
4
|
+
"description": "Native Claude Code Mod: Jev model and effort routing for the main conversation.",
|
|
5
5
|
"license": "MIT",
|
|
6
6
|
"author": "Alexei Ledenev",
|
|
7
7
|
"repository": {
|
|
@@ -17,20 +17,22 @@
|
|
|
17
17
|
".claude-plugin/plugin.json",
|
|
18
18
|
"hooks",
|
|
19
19
|
"lib",
|
|
20
|
-
"scripts",
|
|
21
|
-
"
|
|
22
|
-
"docs",
|
|
20
|
+
"scripts/migrate-config.mjs",
|
|
21
|
+
"docs/*.md",
|
|
22
|
+
"docs/*.svg",
|
|
23
23
|
"README.md",
|
|
24
|
-
"CHANGELOG.md"
|
|
24
|
+
"CHANGELOG.md",
|
|
25
|
+
"types"
|
|
25
26
|
],
|
|
26
27
|
"publishConfig": {
|
|
27
28
|
"access": "public"
|
|
28
29
|
},
|
|
29
30
|
"scripts": {
|
|
30
31
|
"test": "node --test --test-timeout=8000 test/*.test.mjs",
|
|
31
|
-
"check": "biome check .",
|
|
32
|
-
"validate": "claude plugin validate .",
|
|
32
|
+
"check": "biome check lib scripts test hooks types .claude-plugin package.json package-lock.json biome.json experiments/mod-router",
|
|
33
|
+
"validate": "claude plugin validate .claude-plugin/plugin.json && claude plugin validate .claude-plugin/marketplace.json",
|
|
33
34
|
"format": "biome format --write .",
|
|
35
|
+
"docs:images": "node scripts/render-doc-images.mjs",
|
|
34
36
|
"pack:dry": "npm pack --dry-run",
|
|
35
37
|
"prepublishOnly": "npm run check && npm test"
|
|
36
38
|
},
|
|
@@ -0,0 +1,57 @@
|
|
|
1
|
+
import { readFile, writeFile } from 'node:fs/promises';
|
|
2
|
+
import { resolve } from 'node:path';
|
|
3
|
+
import { pathToFileURL } from 'node:url';
|
|
4
|
+
import { loadConfig } from '../lib/config.mjs';
|
|
5
|
+
|
|
6
|
+
// Convert only retired gateway keys. All routing, pricing, cache and policy overrides survive unchanged.
|
|
7
|
+
export function migrateConfig(file) {
|
|
8
|
+
if (!file || typeof file !== 'object' || Array.isArray(file)) throw new Error('router.json must be an object');
|
|
9
|
+
const next = structuredClone(file);
|
|
10
|
+
if (Object.hasOwn(next, 'gateway')) {
|
|
11
|
+
const gateway = next.gateway;
|
|
12
|
+
if (!gateway || typeof gateway !== 'object' || Array.isArray(gateway)) throw new Error('gateway must be an object');
|
|
13
|
+
const keys = ['port', 'alias', 'baselineTier', 'auxiliaryTier', 'idleShutdownMs'];
|
|
14
|
+
for (const key of Object.keys(gateway))
|
|
15
|
+
if (!keys.includes(key)) throw new Error(`gateway.${key} is not a known key`);
|
|
16
|
+
if (gateway.baselineTier !== undefined) {
|
|
17
|
+
if (next.baselineTier !== undefined && next.baselineTier !== gateway.baselineTier)
|
|
18
|
+
throw new Error('baselineTier conflicts with gateway.baselineTier');
|
|
19
|
+
next.baselineTier = gateway.baselineTier;
|
|
20
|
+
}
|
|
21
|
+
delete next.gateway;
|
|
22
|
+
}
|
|
23
|
+
delete next.log;
|
|
24
|
+
if (next.models && typeof next.models === 'object' && !Array.isArray(next.models)) {
|
|
25
|
+
for (const model of Object.values(next.models)) {
|
|
26
|
+
if (model && typeof model === 'object' && !Array.isArray(model)) {
|
|
27
|
+
delete model.features;
|
|
28
|
+
delete model.maxOutput;
|
|
29
|
+
}
|
|
30
|
+
}
|
|
31
|
+
}
|
|
32
|
+
loadConfig({ userFile: next });
|
|
33
|
+
return next;
|
|
34
|
+
}
|
|
35
|
+
|
|
36
|
+
export async function migrateFile(path) {
|
|
37
|
+
const original = await readFile(path, 'utf8');
|
|
38
|
+
const file = JSON.parse(original);
|
|
39
|
+
const next = migrateConfig(file);
|
|
40
|
+
if (JSON.stringify(file) === JSON.stringify(next)) return null;
|
|
41
|
+
const backup = `${path}.v0.8.backup`;
|
|
42
|
+
await writeFile(backup, original, { flag: 'wx', mode: 0o600 });
|
|
43
|
+
await writeFile(path, `${JSON.stringify(next, null, 2)}\n`);
|
|
44
|
+
return backup;
|
|
45
|
+
}
|
|
46
|
+
|
|
47
|
+
if (process.argv[1] && import.meta.url === pathToFileURL(resolve(process.argv[1])).href) {
|
|
48
|
+
try {
|
|
49
|
+
if (process.argv.length !== 3) throw new Error('usage: node scripts/migrate-config.mjs /path/to/router.json');
|
|
50
|
+
const path = resolve(process.argv[2]);
|
|
51
|
+
const backup = await migrateFile(path);
|
|
52
|
+
console.log(backup ? `Migrated ${path}; backup: ${backup}` : `Already native: ${path}`);
|
|
53
|
+
} catch (error) {
|
|
54
|
+
console.error(error.message);
|
|
55
|
+
process.exitCode = 1;
|
|
56
|
+
}
|
|
57
|
+
}
|
package/types/index.d.ts
ADDED
|
@@ -0,0 +1,112 @@
|
|
|
1
|
+
declare module 'claude-code' {
|
|
2
|
+
type RouterTier = 'micro' | 'low' | 'medium' | 'high';
|
|
3
|
+
type RouterCacheState = 'fresh' | 'unknown';
|
|
4
|
+
interface RouterComparison {
|
|
5
|
+
candidate: RouterTier;
|
|
6
|
+
incumbent: RouterTier;
|
|
7
|
+
minUsd: number;
|
|
8
|
+
maxUsd: number;
|
|
9
|
+
paybackTurns: number | null;
|
|
10
|
+
outputTokens: number;
|
|
11
|
+
}
|
|
12
|
+
interface RouterEstimate {
|
|
13
|
+
taxUsd?: number;
|
|
14
|
+
threshold?: number;
|
|
15
|
+
upgradeMass?: number;
|
|
16
|
+
downgradeMass?: number;
|
|
17
|
+
streak?: number;
|
|
18
|
+
coldUsd?: number;
|
|
19
|
+
cap?: number;
|
|
20
|
+
cache?: RouterCacheState | { candidate: RouterCacheState; incumbent: RouterCacheState };
|
|
21
|
+
}
|
|
22
|
+
interface RouterTuning {
|
|
23
|
+
timeoutMs: number;
|
|
24
|
+
downgradeVotes: number;
|
|
25
|
+
horizon: number;
|
|
26
|
+
cashCapUsd: number;
|
|
27
|
+
}
|
|
28
|
+
interface RouterRoutes {
|
|
29
|
+
routes: Record<RouterTier, { model: string; effort?: string | null }>;
|
|
30
|
+
baselineTier: RouterTier;
|
|
31
|
+
}
|
|
32
|
+
interface RouterView {
|
|
33
|
+
phase: 'ready' | 'choosing' | 'routed' | 'manual' | 'unavailable';
|
|
34
|
+
mode: 'auto' | 'manual';
|
|
35
|
+
nativeModel: string;
|
|
36
|
+
activeTurnId?: string | null;
|
|
37
|
+
selectedModel?: string | null;
|
|
38
|
+
actualModel?: string | null;
|
|
39
|
+
tier?: RouterTier | null;
|
|
40
|
+
effort?: string | number | null;
|
|
41
|
+
reason?: string;
|
|
42
|
+
error?: string | null;
|
|
43
|
+
pendingPin?: RouterTier | null;
|
|
44
|
+
keySet?: boolean;
|
|
45
|
+
contextTokens?: number | null;
|
|
46
|
+
contextKnown?: boolean;
|
|
47
|
+
cacheRead?: number | null;
|
|
48
|
+
cacheWrite?: number | null;
|
|
49
|
+
inputTokens?: number | null;
|
|
50
|
+
outputTokens?: number | null;
|
|
51
|
+
health?: { failures: number; pausedUntil: number };
|
|
52
|
+
adviceMs?: number | null;
|
|
53
|
+
adviceChoice?: RouterTier | 'uncertain' | null;
|
|
54
|
+
estimate?: RouterEstimate | null;
|
|
55
|
+
comparison?: RouterComparison | null;
|
|
56
|
+
probabilities?: Partial<Record<RouterTier | 'uncertain', number>> | null;
|
|
57
|
+
history?: number[];
|
|
58
|
+
tiers?: (RouterTier | null)[];
|
|
59
|
+
configPath?: string | null;
|
|
60
|
+
tuning?: Partial<RouterTuning> | null;
|
|
61
|
+
tuningBase?: RouterTuning | null;
|
|
62
|
+
routeDraft?: (RouterRoutes & { base: RouterRoutes }) | null;
|
|
63
|
+
tab?: 'now' | 'tiers' | 'tuning' | 'usage';
|
|
64
|
+
help?: boolean;
|
|
65
|
+
bandDetail?: boolean;
|
|
66
|
+
notice?: string | null;
|
|
67
|
+
}
|
|
68
|
+
interface RouterPolicyState {
|
|
69
|
+
turn: number;
|
|
70
|
+
votes: { tier: RouterTier; turn: number }[];
|
|
71
|
+
holdUntilTurn: number;
|
|
72
|
+
escalatedSignature: string | null;
|
|
73
|
+
}
|
|
74
|
+
interface RouterLoop {
|
|
75
|
+
lastRoute: RouterTier;
|
|
76
|
+
state: RouterPolicyState;
|
|
77
|
+
models: Record<string, { lastAt: number; prefixTokens: number }>;
|
|
78
|
+
resolutions: Record<string, string>;
|
|
79
|
+
lastRequest: {
|
|
80
|
+
model: string;
|
|
81
|
+
tokens: number;
|
|
82
|
+
outputTokens: number;
|
|
83
|
+
cacheReadTokens: number;
|
|
84
|
+
cacheWriteTokens: number;
|
|
85
|
+
at: number;
|
|
86
|
+
} | null;
|
|
87
|
+
lastMessageCount: number | null;
|
|
88
|
+
historyMeasured?: boolean;
|
|
89
|
+
generation: number;
|
|
90
|
+
turnId: string | null;
|
|
91
|
+
decision: {
|
|
92
|
+
tier: RouterTier | null;
|
|
93
|
+
reason: string;
|
|
94
|
+
state: RouterPolicyState;
|
|
95
|
+
model: string;
|
|
96
|
+
effort: string | number | null;
|
|
97
|
+
estimate?: RouterEstimate | null;
|
|
98
|
+
comparison?: RouterComparison | null;
|
|
99
|
+
pinned: boolean;
|
|
100
|
+
requestedPin: RouterTier | null;
|
|
101
|
+
} | null;
|
|
102
|
+
ineligible: string[];
|
|
103
|
+
engineModel?: string;
|
|
104
|
+
suspended?: boolean;
|
|
105
|
+
}
|
|
106
|
+
interface PluginState {
|
|
107
|
+
router: {
|
|
108
|
+
view: RouterView;
|
|
109
|
+
loops: StateFamily<RouterLoop>;
|
|
110
|
+
};
|
|
111
|
+
}
|
|
112
|
+
}
|
package/lib/cost.mjs
DELETED
|
@@ -1,93 +0,0 @@
|
|
|
1
|
-
// Cache-aware cost of the next request. Pure arithmetic over configured prices and the gateway's memory.
|
|
2
|
-
import { clampEffort } from './rewrite.mjs';
|
|
3
|
-
|
|
4
|
-
// The prompt cache belongs to a model, and its messages part to the effort too: a top-level effort change rewrites
|
|
5
|
-
// the messages cache. Sonnet at `high` and Sonnet at `xhigh` are two caches, not one.
|
|
6
|
-
export function cacheKey(modelId, effort) {
|
|
7
|
-
return effort ? `${modelId}@${effort}` : modelId;
|
|
8
|
-
}
|
|
9
|
-
|
|
10
|
-
// The cache a request routed to `tier` uses. `sentEffort` is what Claude Code sent, for a route that keeps it.
|
|
11
|
-
export function routeCacheKey(config, tier, sentEffort) {
|
|
12
|
-
const model = modelOf(config, tier);
|
|
13
|
-
return cacheKey(model.id, clampEffort(config.routes[tier].effort ?? sentEffort, model.efforts));
|
|
14
|
-
}
|
|
15
|
-
|
|
16
|
-
export function isWarm(modelState, now, cache) {
|
|
17
|
-
if (!modelState) return false;
|
|
18
|
-
return now < modelState.lastAt + cache.ttlMs[modelState.ttl] - cache.warmMarginMs;
|
|
19
|
-
}
|
|
20
|
-
|
|
21
|
-
// For the logs: `unknown` means no response for this cache since the session started or its history broke. The cost
|
|
22
|
-
// arithmetic treats `unknown` and `expired` alike, as a full write.
|
|
23
|
-
export function cacheState(modelState, now, cache) {
|
|
24
|
-
if (!modelState) return 'unknown';
|
|
25
|
-
return isWarm(modelState, now, cache) ? 'warm' : 'expired';
|
|
26
|
-
}
|
|
27
|
-
|
|
28
|
-
function modelOf(config, tier) {
|
|
29
|
-
return config.models[config.routes[tier].model];
|
|
30
|
-
}
|
|
31
|
-
|
|
32
|
-
function ttlFor(config, alias, facts) {
|
|
33
|
-
if (config.models[alias].billing === 'credits') return '5m';
|
|
34
|
-
return facts.lastRequest?.ttl ?? '5m';
|
|
35
|
-
}
|
|
36
|
-
|
|
37
|
-
// USD for the input side of one request routed to `tier` with `tokens` of context.
|
|
38
|
-
export function inputCostUsd(config, tier, tokens, facts, now) {
|
|
39
|
-
const alias = config.routes[tier].model;
|
|
40
|
-
const model = config.models[alias];
|
|
41
|
-
const state = facts.models[routeCacheKey(config, tier, facts.effort)];
|
|
42
|
-
const reusable = isWarm(state, now, config.cache) ? Math.min(state.prefixTokens, tokens) : 0;
|
|
43
|
-
const write = model.input * config.cache.writeMultiplier[ttlFor(config, alias, facts)];
|
|
44
|
-
return (model.cacheRead * reusable + write * (tokens - reusable)) / 1e6;
|
|
45
|
-
}
|
|
46
|
-
|
|
47
|
-
export function coldWriteUsd(config, alias, tokens, facts) {
|
|
48
|
-
const model = config.models[alias];
|
|
49
|
-
return (model.input * config.cache.writeMultiplier[ttlFor(config, alias, facts)] * tokens) / 1e6;
|
|
50
|
-
}
|
|
51
|
-
|
|
52
|
-
// Estimated context of the next request: last request plus its output. Tool results and the new prompt are not counted.
|
|
53
|
-
export function nextContextTokens(facts) {
|
|
54
|
-
const last = facts.lastRequest;
|
|
55
|
-
return last ? last.tokens + last.outputTokens : 0;
|
|
56
|
-
}
|
|
57
|
-
|
|
58
|
-
export function switchingTaxUsd(config, candidateTier, incumbentTier, facts, now) {
|
|
59
|
-
const tokens = nextContextTokens(facts);
|
|
60
|
-
return (
|
|
61
|
-
inputCostUsd(config, candidateTier, tokens, facts, now) - inputCostUsd(config, incumbentTier, tokens, facts, now)
|
|
62
|
-
);
|
|
63
|
-
}
|
|
64
|
-
|
|
65
|
-
// Shadow estimate for the decision log; the downgrade tax nets it over a horizon. At list prices, so for `plan` models
|
|
66
|
-
// it is a list-price equivalent, not a charge. Output uses the last observed output size for both routes, although
|
|
67
|
-
// effort changes how much a model writes.
|
|
68
|
-
// - nextTurnUsd: candidate minus incumbent for the next request, input at the current cache state plus output.
|
|
69
|
-
// - laterTurnUsd: the same difference for each later turn, once both caches are warm.
|
|
70
|
-
// - paybackTurns: 0 when the switch is cheaper at once, n when later turns repay it after n turns, null when never.
|
|
71
|
-
export function shadowEconomics(config, candidateTier, incumbentTier, facts, now) {
|
|
72
|
-
const candidate = modelOf(config, candidateTier);
|
|
73
|
-
const incumbent = modelOf(config, incumbentTier);
|
|
74
|
-
if (candidate.output === undefined || incumbent.output === undefined) return null;
|
|
75
|
-
const tokens = nextContextTokens(facts);
|
|
76
|
-
const outputTokens = facts.lastRequest?.outputTokens ?? 0;
|
|
77
|
-
const outputUsd = ((candidate.output - incumbent.output) * outputTokens) / 1e6;
|
|
78
|
-
const nextTurnUsd = switchingTaxUsd(config, candidateTier, incumbentTier, facts, now) + outputUsd;
|
|
79
|
-
const laterTurnUsd = ((candidate.cacheRead - incumbent.cacheRead) * tokens) / 1e6 + outputUsd;
|
|
80
|
-
let paybackTurns = null;
|
|
81
|
-
if (nextTurnUsd <= 0 && laterTurnUsd <= 0) paybackTurns = 0;
|
|
82
|
-
else if (nextTurnUsd > 0 && laterTurnUsd < 0) paybackTurns = Math.ceil(nextTurnUsd / -laterTurnUsd);
|
|
83
|
-
return { nextTurnUsd, laterTurnUsd, paybackTurns, outputTokens };
|
|
84
|
-
}
|
|
85
|
-
|
|
86
|
-
// A downgrade's tax over `turns` turns: the next one plus the later ones, output included. A missing or zero output
|
|
87
|
-
// price is unknown, not free, so the tax then falls back to the next request's input alone.
|
|
88
|
-
export function downgradeTaxUsd(config, candidateTier, incumbentTier, facts, now, turns) {
|
|
89
|
-
const priced = [candidateTier, incumbentTier].every((tier) => modelOf(config, tier).output > 0);
|
|
90
|
-
if (!priced) return Math.max(0, switchingTaxUsd(config, candidateTier, incumbentTier, facts, now));
|
|
91
|
-
const { nextTurnUsd, laterTurnUsd } = shadowEconomics(config, candidateTier, incumbentTier, facts, now);
|
|
92
|
-
return Math.max(0, nextTurnUsd + (turns - 1) * laterTurnUsd);
|
|
93
|
-
}
|