@alexeiled/claude-router 0.7.2 → 1.0.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 +10 -6
- package/CHANGELOG.md +43 -0
- package/README.md +51 -100
- package/docs/architecture.md +55 -414
- package/docs/configuration.md +86 -182
- package/docs/evaluation.md +62 -81
- package/docs/native-router.md +79 -0
- package/docs/user-guide.md +103 -172
- package/hooks/hooks.json +1 -26
- package/hooks/native-router.mjs +635 -0
- package/lib/config.mjs +24 -60
- package/lib/{facts.mjs → facts-pure.mjs} +2 -23
- package/lib/{jev.mjs → jev-contract.mjs} +17 -38
- package/lib/native-cost.mjs +88 -0
- package/lib/native-display.mjs +75 -0
- package/lib/native-jev.mjs +125 -0
- package/lib/native-panel.mjs +150 -0
- package/lib/native-router.mjs +216 -0
- package/lib/policy.mjs +17 -21
- package/package.json +9 -8
- package/scripts/migrate-config.mjs +57 -0
- package/types/index.d.ts +95 -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 -27
- 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,150 @@
|
|
|
1
|
+
import { TIERS } from './config.mjs';
|
|
2
|
+
import { bar, formatTokens, REASONS, sparkline, usageMetrics } from './native-display.mjs';
|
|
3
|
+
|
|
4
|
+
function label(id) {
|
|
5
|
+
return id ? id.replace(/^claude-/, '').replace(/-([0-9])-([0-9])/, ' $1.$2') : 'no response yet';
|
|
6
|
+
}
|
|
7
|
+
|
|
8
|
+
export function renderPanel({ Box, Text, Button, Select }, config, view, usage, actions) {
|
|
9
|
+
const metrics = usageMetrics(config, view, usage);
|
|
10
|
+
const heading = (text) => Text({ bold: true, color: 'cyan', children: text });
|
|
11
|
+
const row = (name, value) => Text({ children: `${name}: ${value}` });
|
|
12
|
+
const gauge = (name, value, suffix) =>
|
|
13
|
+
Text({
|
|
14
|
+
color: value.color,
|
|
15
|
+
children: `${name} ${value.text}${value.percent === null ? '' : ` ${value.percent}%`} ${suffix}`,
|
|
16
|
+
});
|
|
17
|
+
const dollars = (value) => (Number.isFinite(value) ? `$${value.toFixed(3)}` : 'not reported');
|
|
18
|
+
const difference = (value) => `${value < 0 ? '−' : '+'}$${Math.abs(value).toFixed(3)}`;
|
|
19
|
+
const tuning = view.tuning ?? {
|
|
20
|
+
timeoutMs: config.jev.timeoutMs,
|
|
21
|
+
downgradeVotes: config.policy.downgradeVotes,
|
|
22
|
+
horizon: config.policy.downgradeHorizonTurns,
|
|
23
|
+
};
|
|
24
|
+
const select = (key, name, values, value) =>
|
|
25
|
+
Select({
|
|
26
|
+
key,
|
|
27
|
+
label: name,
|
|
28
|
+
value: String(value),
|
|
29
|
+
options: values.map((n) => ({ value: String(n), label: String(n) })),
|
|
30
|
+
onSelect: (picked) => {
|
|
31
|
+
if (values.includes(Number(picked))) actions.tune(key, Number(picked));
|
|
32
|
+
},
|
|
33
|
+
});
|
|
34
|
+
return Box({
|
|
35
|
+
flexDirection: 'column',
|
|
36
|
+
children: [
|
|
37
|
+
heading(`MODEL ROUTING · ${view.mode === 'auto' ? 'Auto' : 'Manual'}`),
|
|
38
|
+
row('Last reply', label(view.actualModel)),
|
|
39
|
+
row('Selected', label(view.selectedModel)),
|
|
40
|
+
row('Requested effort', view.effort ?? 'native default'),
|
|
41
|
+
row('Why', REASONS[view.reason] ?? view.reason),
|
|
42
|
+
view.pendingPin ? row('Next turn only', view.pendingPin) : null,
|
|
43
|
+
heading('USAGE · Claude readings'),
|
|
44
|
+
row('API cost reported by Claude', dollars(metrics.cost)),
|
|
45
|
+
gauge('Context', metrics.contextBar, `~${formatTokens(metrics.nextContext)} / ${formatTokens(metrics.window)}`),
|
|
46
|
+
row('Observed / estimated input', `${formatTokens(metrics.observed)} / ${formatTokens(view.contextTokens)}`),
|
|
47
|
+
Text({ dimColor: true, children: '20% window reserve. The bar uses the routed model’s window.' }),
|
|
48
|
+
gauge('Cache reuse', metrics.cacheBar, 'last response'),
|
|
49
|
+
row('Cache read / written', `${formatTokens(view.cacheRead)} / ${formatTokens(view.cacheWrite)} tokens`),
|
|
50
|
+
row('Output', `${formatTokens(view.outputTokens)} tokens`),
|
|
51
|
+
row('Input trend', sparkline(view.history ?? [])),
|
|
52
|
+
...(usage?.rateLimits ?? [])
|
|
53
|
+
.filter((limit) => Number.isFinite(limit.percentUsed))
|
|
54
|
+
.map((limit) => gauge(limit.kind.replaceAll('_', ' '), bar(limit.percentUsed, 100), 'quota used')),
|
|
55
|
+
heading('JEV & SWITCH ESTIMATE'),
|
|
56
|
+
row('Jev', view.error ?? (view.keySet ? 'ready' : 'key not set')),
|
|
57
|
+
row(
|
|
58
|
+
'Last classification',
|
|
59
|
+
view.adviceMs === null || view.adviceMs === undefined ? 'not attempted' : `${view.adviceMs} ms`,
|
|
60
|
+
),
|
|
61
|
+
view.adviceChoice ? row('Suggested tier', view.adviceChoice) : null,
|
|
62
|
+
Number.isFinite(view.estimate?.threshold)
|
|
63
|
+
? row('Policy support required', `${Math.round(view.estimate.threshold * 100)}%`)
|
|
64
|
+
: null,
|
|
65
|
+
Number.isFinite(view.estimate?.taxUsd) ? row('Estimated switching tax', dollars(view.estimate.taxUsd)) : null,
|
|
66
|
+
...(view.comparison
|
|
67
|
+
? [
|
|
68
|
+
row('Compared tiers', `${view.comparison.incumbent} → ${view.comparison.candidate}`),
|
|
69
|
+
row(
|
|
70
|
+
'Next-turn difference',
|
|
71
|
+
`${difference(view.comparison.minUsd)} to ${difference(view.comparison.maxUsd)}`,
|
|
72
|
+
),
|
|
73
|
+
row(
|
|
74
|
+
'Conservative payback',
|
|
75
|
+
view.comparison.paybackTurns === null
|
|
76
|
+
? 'no projected payback'
|
|
77
|
+
: `${view.comparison.paybackTurns} later turns`,
|
|
78
|
+
),
|
|
79
|
+
Text({
|
|
80
|
+
dimColor: true,
|
|
81
|
+
children: `Cache scenarios use 5m–1h writes and ${formatTokens(view.comparison.outputTokens)} output tokens. Minus means cheaper.`,
|
|
82
|
+
}),
|
|
83
|
+
]
|
|
84
|
+
: []),
|
|
85
|
+
row('Cache read benefit', dollars(metrics.cacheBenefit)),
|
|
86
|
+
Text({
|
|
87
|
+
dimColor: true,
|
|
88
|
+
children: 'Cache benefit: configured-price estimate vs uncached reads, before write costs.',
|
|
89
|
+
}),
|
|
90
|
+
Text({
|
|
91
|
+
dimColor: true,
|
|
92
|
+
children: 'Routing savings are not measured. Plan prices are equivalents, not cash charges.',
|
|
93
|
+
}),
|
|
94
|
+
heading('CONTROLS'),
|
|
95
|
+
Box({
|
|
96
|
+
children: [
|
|
97
|
+
Button({
|
|
98
|
+
key: 'auto',
|
|
99
|
+
label: 'Auto routing',
|
|
100
|
+
hotkey: 'a',
|
|
101
|
+
variant: view.mode === 'auto' ? 'primary' : 'secondary',
|
|
102
|
+
onPress: () => actions.mode('auto'),
|
|
103
|
+
}),
|
|
104
|
+
Text({ children: ' ' }),
|
|
105
|
+
Button({
|
|
106
|
+
key: 'manual',
|
|
107
|
+
label: 'Manual model',
|
|
108
|
+
hotkey: 'm',
|
|
109
|
+
variant: view.mode === 'manual' ? 'primary' : 'secondary',
|
|
110
|
+
onPress: () => actions.mode('manual'),
|
|
111
|
+
}),
|
|
112
|
+
],
|
|
113
|
+
}),
|
|
114
|
+
Text({ dimColor: true, children: 'Pins affect the next turn only. Enable Auto first.' }),
|
|
115
|
+
...tierLabels(config).map(({ tier, name }) =>
|
|
116
|
+
Button({ key: `pin-${tier}`, label: name, onPress: () => actions.pin(tier) }),
|
|
117
|
+
),
|
|
118
|
+
Button({
|
|
119
|
+
key: 'key',
|
|
120
|
+
label: view.keySet ? 'Jev key configured · edit' : 'Set Jev API key',
|
|
121
|
+
hotkey: 'k',
|
|
122
|
+
onPress: actions.key,
|
|
123
|
+
}),
|
|
124
|
+
heading('TUNING · future turns'),
|
|
125
|
+
...(Select
|
|
126
|
+
? [
|
|
127
|
+
select('timeoutMs', 'Jev deadline (ms)', [500, 1000, 1500, 3000], tuning.timeoutMs),
|
|
128
|
+
select('downgradeVotes', 'Votes before cheaper tier', [1, 2, 3], tuning.downgradeVotes),
|
|
129
|
+
select('horizon', 'Payback horizon (turns)', [1, 3, 5, 10], tuning.horizon),
|
|
130
|
+
Button({ key: 'save-tuning', label: 'Save tuning', onPress: actions.save }),
|
|
131
|
+
]
|
|
132
|
+
: []),
|
|
133
|
+
row('Credits cold-write cap', `$${config.policy.cashCapUsd.toFixed(2)} · excludes output/session spend`),
|
|
134
|
+
Text({ dimColor: true, children: `Advanced: ${view.configPath ?? 'active profile router.json'}` }),
|
|
135
|
+
Text({ dimColor: true, children: 'Main conversation routing. Subagents keep Claude’s model selection.' }),
|
|
136
|
+
view.notice ? Text({ color: 'yellow', children: view.notice }) : null,
|
|
137
|
+
Button({ key: 'close', label: 'Close', hotkey: 'q', role: 'dismiss', onPress: actions.close }),
|
|
138
|
+
],
|
|
139
|
+
});
|
|
140
|
+
}
|
|
141
|
+
|
|
142
|
+
function tierLabels(config) {
|
|
143
|
+
return TIERS.map((tier) => {
|
|
144
|
+
const route = config.routes[tier];
|
|
145
|
+
return {
|
|
146
|
+
tier,
|
|
147
|
+
name: `${tier}: ${label(config.models[route.model].id)}${route.effort ? ` · ${route.effort}` : ''}`,
|
|
148
|
+
};
|
|
149
|
+
});
|
|
150
|
+
}
|
|
@@ -0,0 +1,216 @@
|
|
|
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
|
+
export function tierForModel(config, id) {
|
|
10
|
+
const order = [config.baselineTier, ...TIERS.filter((tier) => tier !== config.baselineTier)];
|
|
11
|
+
return (
|
|
12
|
+
order.find((tier) => {
|
|
13
|
+
const model = config.models[config.routes[tier].model];
|
|
14
|
+
return model.id === id || SNAPSHOTS[model.id] === id;
|
|
15
|
+
}) ?? null
|
|
16
|
+
);
|
|
17
|
+
}
|
|
18
|
+
|
|
19
|
+
export function emptyLoop(config, model) {
|
|
20
|
+
return {
|
|
21
|
+
lastRoute: tierForModel(config, model) ?? config.baselineTier,
|
|
22
|
+
state: initialState(),
|
|
23
|
+
models: {},
|
|
24
|
+
resolutions: {},
|
|
25
|
+
lastRequest: null,
|
|
26
|
+
historyMeasured: false,
|
|
27
|
+
lastMessageCount: null,
|
|
28
|
+
generation: 0,
|
|
29
|
+
turnId: null,
|
|
30
|
+
decision: null,
|
|
31
|
+
ineligible: [],
|
|
32
|
+
};
|
|
33
|
+
}
|
|
34
|
+
|
|
35
|
+
export function resetHistory(loop) {
|
|
36
|
+
return {
|
|
37
|
+
...loop,
|
|
38
|
+
generation: loop.generation + 1,
|
|
39
|
+
models: {},
|
|
40
|
+
resolutions: {},
|
|
41
|
+
historyMeasured: false,
|
|
42
|
+
state: { ...loop.state, votes: [], holdUntilTurn: 0, escalatedSignature: null },
|
|
43
|
+
// The active turn keeps its route, pin and fallback suspension; the next turn decides afresh.
|
|
44
|
+
ineligible: [],
|
|
45
|
+
};
|
|
46
|
+
}
|
|
47
|
+
|
|
48
|
+
export function prepareLoop(loop, messageCount) {
|
|
49
|
+
const next = loop.lastMessageCount !== null && messageCount < loop.lastMessageCount ? resetHistory(loop) : loop;
|
|
50
|
+
return { ...next, lastMessageCount: messageCount };
|
|
51
|
+
}
|
|
52
|
+
|
|
53
|
+
export function nativeFacts(config, loop, { messages, prompt, effort, turnId, contextTokens }) {
|
|
54
|
+
const facts = extractFacts({ messages, output_config: { effort } }, loop, config.context);
|
|
55
|
+
if (typeof prompt === 'string') facts.prompt = clip(prompt, config.context.maxTextChars);
|
|
56
|
+
return { ...facts, pin: null, contextTokens, turnKey: turnId };
|
|
57
|
+
}
|
|
58
|
+
|
|
59
|
+
export function isModelAllowed(id, available, nativeModel) {
|
|
60
|
+
if (available === undefined) return true;
|
|
61
|
+
if (!Array.isArray(available) || !available.every((v) => typeof v === 'string')) return false;
|
|
62
|
+
if (available.includes('default') && id === nativeModel) return true;
|
|
63
|
+
const family = /^claude-(opus|sonnet|haiku)-/.exec(id)?.[1];
|
|
64
|
+
const specific = available.filter((v) => family && v.startsWith(`claude-${family}-`));
|
|
65
|
+
if (specific.length) return specific.some((v) => id === v || id.startsWith(`${v}-`));
|
|
66
|
+
return available.some((v) => id === v || id.startsWith(`${v}-`) || (family && v === family));
|
|
67
|
+
}
|
|
68
|
+
|
|
69
|
+
function economicConfig(config, loop) {
|
|
70
|
+
const models = Object.fromEntries(
|
|
71
|
+
Object.entries(config.models).map(([alias, model]) => [
|
|
72
|
+
alias,
|
|
73
|
+
{ ...model, id: Object.hasOwn(loop.resolutions, model.id) ? loop.resolutions[model.id] : model.id },
|
|
74
|
+
]),
|
|
75
|
+
);
|
|
76
|
+
return { ...config, models };
|
|
77
|
+
}
|
|
78
|
+
|
|
79
|
+
export function chooseRoute(config, loop, { facts, advice, pin, nativeModel, contextKnown, availableModels, now }) {
|
|
80
|
+
const projected = economicConfig(config, loop);
|
|
81
|
+
let result =
|
|
82
|
+
pin && TIERS.includes(pin)
|
|
83
|
+
? { tier: pin, reason: 'pinned', state: { ...loop.state, turn: loop.state.turn + 1 } }
|
|
84
|
+
: decide({
|
|
85
|
+
config: projected,
|
|
86
|
+
facts,
|
|
87
|
+
advice,
|
|
88
|
+
state: loop.state,
|
|
89
|
+
baseline: config.baselineTier,
|
|
90
|
+
now,
|
|
91
|
+
costs,
|
|
92
|
+
});
|
|
93
|
+
const fits = (tier) => {
|
|
94
|
+
const model = config.models[config.routes[tier].model];
|
|
95
|
+
if (
|
|
96
|
+
(!contextKnown || !loop.historyMeasured) &&
|
|
97
|
+
model.contextWindow < config.models[config.routes[loop.lastRoute].model].contextWindow
|
|
98
|
+
)
|
|
99
|
+
return false;
|
|
100
|
+
return (
|
|
101
|
+
isModelAllowed(model.id, availableModels, nativeModel) &&
|
|
102
|
+
!loop.ineligible.includes(model.id) &&
|
|
103
|
+
(!contextKnown || costs.nextContextTokens(facts) <= model.contextWindow * 0.8)
|
|
104
|
+
);
|
|
105
|
+
};
|
|
106
|
+
if (contextKnown) {
|
|
107
|
+
const fitted = fitTier(config, result.tier, costs.nextContextTokens(facts));
|
|
108
|
+
if (fitted !== result.tier) result = { ...result, tier: fitted, reason: 'context-fit' };
|
|
109
|
+
}
|
|
110
|
+
if (
|
|
111
|
+
(!contextKnown || !loop.historyMeasured) &&
|
|
112
|
+
config.models[config.routes[result.tier].model].contextWindow <
|
|
113
|
+
config.models[config.routes[loop.lastRoute].model].contextWindow
|
|
114
|
+
) {
|
|
115
|
+
result = { ...result, tier: loop.lastRoute, reason: 'context-unknown' };
|
|
116
|
+
}
|
|
117
|
+
if (!fits(result.tier)) {
|
|
118
|
+
const fallback = [loop.lastRoute, tierForModel(config, nativeModel), ...TIERS].find((tier) => tier && fits(tier));
|
|
119
|
+
result = { ...result, tier: fallback ?? null, reason: 'model-unavailable' };
|
|
120
|
+
}
|
|
121
|
+
const model = result.tier ? config.models[config.routes[result.tier].model].id : nativeModel;
|
|
122
|
+
const effort = result.tier ? costs.routeEffort(config, result.tier, facts.effort) : facts.effort;
|
|
123
|
+
let comparison = null;
|
|
124
|
+
const candidate = pin ?? advice?.choice;
|
|
125
|
+
if (contextKnown && loop.lastRequest && TIERS.includes(candidate) && candidate !== loop.lastRoute) {
|
|
126
|
+
const tokens = costs.nextContextTokens(facts);
|
|
127
|
+
const proposed = costs.inputBounds(projected, candidate, tokens, facts, now);
|
|
128
|
+
const incumbent = costs.inputBounds(projected, loop.lastRoute, tokens, facts, now);
|
|
129
|
+
const forecast = costs.shadowEconomics(projected, candidate, loop.lastRoute, facts, now);
|
|
130
|
+
// Without both output prices, compare input only, as shadowEconomics does.
|
|
131
|
+
const output = forecast
|
|
132
|
+
? ((projected.models[projected.routes[candidate].model].output -
|
|
133
|
+
projected.models[projected.routes[loop.lastRoute].model].output) *
|
|
134
|
+
loop.lastRequest.outputTokens) /
|
|
135
|
+
1e6
|
|
136
|
+
: 0;
|
|
137
|
+
comparison = {
|
|
138
|
+
candidate,
|
|
139
|
+
incumbent: loop.lastRoute,
|
|
140
|
+
minUsd: proposed.min - incumbent.max + output,
|
|
141
|
+
maxUsd: proposed.max - incumbent.min + output,
|
|
142
|
+
paybackTurns: forecast?.paybackTurns ?? null,
|
|
143
|
+
outputTokens: loop.lastRequest.outputTokens,
|
|
144
|
+
};
|
|
145
|
+
}
|
|
146
|
+
const decision = { ...result, model, effort, comparison, pinned: Boolean(pin), requestedPin: pin ?? null };
|
|
147
|
+
return {
|
|
148
|
+
...loop,
|
|
149
|
+
state: result.state,
|
|
150
|
+
lastRoute: pin ? loop.lastRoute : (result.tier ?? loop.lastRoute),
|
|
151
|
+
turnId: facts.turnKey,
|
|
152
|
+
decision,
|
|
153
|
+
suspended: false,
|
|
154
|
+
};
|
|
155
|
+
}
|
|
156
|
+
|
|
157
|
+
export function continueRoute(config, loop, { nativeModel, contextTokens, contextKnown, availableModels, effort }) {
|
|
158
|
+
if (!loop.decision) return loop;
|
|
159
|
+
let decision = loop.decision;
|
|
160
|
+
if (contextKnown && decision.tier) {
|
|
161
|
+
const fitted = fitTier(config, decision.tier, contextTokens);
|
|
162
|
+
if (fitted !== decision.tier)
|
|
163
|
+
decision = {
|
|
164
|
+
...decision,
|
|
165
|
+
tier: fitted,
|
|
166
|
+
model: config.models[config.routes[fitted].model].id,
|
|
167
|
+
effort: costs.routeEffort(config, fitted, effort),
|
|
168
|
+
reason: 'context-fit',
|
|
169
|
+
};
|
|
170
|
+
}
|
|
171
|
+
if (!isModelAllowed(decision.model, availableModels, nativeModel) || loop.ineligible.includes(decision.model)) {
|
|
172
|
+
decision = { ...decision, tier: null, model: nativeModel, effort, reason: 'model-unavailable' };
|
|
173
|
+
}
|
|
174
|
+
return { ...loop, decision };
|
|
175
|
+
}
|
|
176
|
+
|
|
177
|
+
export function observeResponse(_config, loop, { usage, requestedModel, effort, stopReason, now }) {
|
|
178
|
+
let next = loop;
|
|
179
|
+
if (stopReason === 'model_context_window_exceeded') {
|
|
180
|
+
next = { ...next, ineligible: [...new Set([...next.ineligible, requestedModel])] };
|
|
181
|
+
}
|
|
182
|
+
if (!usage?.model) return next;
|
|
183
|
+
const sameModel = requestedModel === usage.model || SNAPSHOTS[requestedModel] === usage.model;
|
|
184
|
+
if (!sameModel) next = { ...next, suspended: true };
|
|
185
|
+
const counts = ['input_tokens', 'cache_read_input_tokens', 'cache_creation_input_tokens', 'output_tokens'];
|
|
186
|
+
if (!counts.every((key) => Number.isFinite(usage[key]) && usage[key] >= 0)) return next;
|
|
187
|
+
const tokens = usage.input_tokens + usage.cache_read_input_tokens + usage.cache_creation_input_tokens;
|
|
188
|
+
if (tokens === 0) return next;
|
|
189
|
+
const resolutions = sameModel ? { ...next.resolutions, [requestedModel]: usage.model } : { ...next.resolutions };
|
|
190
|
+
if (!sameModel) delete resolutions[requestedModel];
|
|
191
|
+
let models = next.models;
|
|
192
|
+
if (next.lastRequest && tokens < next.lastRequest.tokens * 0.8) models = {};
|
|
193
|
+
// A substituted model's effort is not reported, so do not credit its estimated cache.
|
|
194
|
+
if (sameModel)
|
|
195
|
+
models = {
|
|
196
|
+
...models,
|
|
197
|
+
[costs.cacheKey(usage.model, effort)]: {
|
|
198
|
+
lastAt: now,
|
|
199
|
+
prefixTokens: usage.cache_read_input_tokens + usage.cache_creation_input_tokens,
|
|
200
|
+
},
|
|
201
|
+
};
|
|
202
|
+
return {
|
|
203
|
+
...next,
|
|
204
|
+
historyMeasured: true,
|
|
205
|
+
models,
|
|
206
|
+
resolutions,
|
|
207
|
+
lastRequest: {
|
|
208
|
+
model: usage.model,
|
|
209
|
+
tokens,
|
|
210
|
+
outputTokens: usage.output_tokens,
|
|
211
|
+
cacheReadTokens: usage.cache_read_input_tokens,
|
|
212
|
+
cacheWriteTokens: usage.cache_creation_input_tokens,
|
|
213
|
+
at: now,
|
|
214
|
+
},
|
|
215
|
+
};
|
|
216
|
+
}
|
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": "0.
|
|
4
|
-
"description": "Claude Code
|
|
3
|
+
"version": "1.0.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,19 +17,20 @@
|
|
|
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 .",
|
|
34
35
|
"pack:dry": "npm pack --dry-run",
|
|
35
36
|
"prepublishOnly": "npm run check && npm test"
|
|
@@ -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,95 @@
|
|
|
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 RouterView {
|
|
23
|
+
phase: 'ready' | 'choosing' | 'routed' | 'manual' | 'unavailable';
|
|
24
|
+
mode: 'auto' | 'manual';
|
|
25
|
+
nativeModel: string;
|
|
26
|
+
activeTurnId?: string | null;
|
|
27
|
+
selectedModel?: string | null;
|
|
28
|
+
actualModel?: string | null;
|
|
29
|
+
tier?: RouterTier | null;
|
|
30
|
+
effort?: string | number | null;
|
|
31
|
+
reason?: string;
|
|
32
|
+
error?: string | null;
|
|
33
|
+
pendingPin?: RouterTier | null;
|
|
34
|
+
keySet?: boolean;
|
|
35
|
+
contextTokens?: number | null;
|
|
36
|
+
contextKnown?: boolean;
|
|
37
|
+
cacheRead?: number | null;
|
|
38
|
+
cacheWrite?: number | null;
|
|
39
|
+
inputTokens?: number | null;
|
|
40
|
+
outputTokens?: number | null;
|
|
41
|
+
health?: { failures: number; pausedUntil: number };
|
|
42
|
+
adviceMs?: number | null;
|
|
43
|
+
adviceChoice?: RouterTier | 'uncertain' | null;
|
|
44
|
+
estimate?: RouterEstimate | null;
|
|
45
|
+
comparison?: RouterComparison | null;
|
|
46
|
+
history?: number[];
|
|
47
|
+
configPath?: string | null;
|
|
48
|
+
tuning?: { timeoutMs: number; downgradeVotes: number; horizon: number } | null;
|
|
49
|
+
notice?: string | null;
|
|
50
|
+
}
|
|
51
|
+
interface RouterPolicyState {
|
|
52
|
+
turn: number;
|
|
53
|
+
votes: { tier: RouterTier; turn: number }[];
|
|
54
|
+
holdUntilTurn: number;
|
|
55
|
+
escalatedSignature: string | null;
|
|
56
|
+
}
|
|
57
|
+
interface RouterLoop {
|
|
58
|
+
lastRoute: RouterTier;
|
|
59
|
+
state: RouterPolicyState;
|
|
60
|
+
models: Record<string, { lastAt: number; prefixTokens: number }>;
|
|
61
|
+
resolutions: Record<string, string>;
|
|
62
|
+
lastRequest: {
|
|
63
|
+
model: string;
|
|
64
|
+
tokens: number;
|
|
65
|
+
outputTokens: number;
|
|
66
|
+
cacheReadTokens: number;
|
|
67
|
+
cacheWriteTokens: number;
|
|
68
|
+
at: number;
|
|
69
|
+
} | null;
|
|
70
|
+
lastMessageCount: number | null;
|
|
71
|
+
historyMeasured?: boolean;
|
|
72
|
+
generation: number;
|
|
73
|
+
turnId: string | null;
|
|
74
|
+
decision: {
|
|
75
|
+
tier: RouterTier | null;
|
|
76
|
+
reason: string;
|
|
77
|
+
state: RouterPolicyState;
|
|
78
|
+
model: string;
|
|
79
|
+
effort: string | number | null;
|
|
80
|
+
estimate?: RouterEstimate | null;
|
|
81
|
+
comparison?: RouterComparison | null;
|
|
82
|
+
pinned: boolean;
|
|
83
|
+
requestedPin: RouterTier | null;
|
|
84
|
+
} | null;
|
|
85
|
+
ineligible: string[];
|
|
86
|
+
engineModel?: string;
|
|
87
|
+
suspended?: boolean;
|
|
88
|
+
}
|
|
89
|
+
interface PluginState {
|
|
90
|
+
router: {
|
|
91
|
+
view: RouterView;
|
|
92
|
+
loops: StateFamily<RouterLoop>;
|
|
93
|
+
};
|
|
94
|
+
}
|
|
95
|
+
}
|