@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.
Files changed (48) hide show
  1. package/.claude-plugin/plugin.json +11 -7
  2. package/CHANGELOG.md +43 -0
  3. package/README.md +55 -98
  4. package/docs/architecture.md +55 -419
  5. package/docs/configuration.md +88 -182
  6. package/docs/evaluation.md +62 -81
  7. package/docs/native-router.md +80 -0
  8. package/docs/router-band.svg +119 -0
  9. package/docs/router-pane-now.svg +85 -0
  10. package/docs/router-pane-tiers.svg +62 -0
  11. package/docs/user-guide.md +127 -172
  12. package/hooks/hooks.json +1 -26
  13. package/hooks/native-router.mjs +701 -0
  14. package/lib/config.mjs +97 -63
  15. package/lib/{facts.mjs → facts-pure.mjs} +2 -23
  16. package/lib/{jev.mjs → jev-contract.mjs} +17 -38
  17. package/lib/native-band.mjs +206 -0
  18. package/lib/native-cost.mjs +88 -0
  19. package/lib/native-display.mjs +122 -0
  20. package/lib/native-jev.mjs +125 -0
  21. package/lib/native-panel.mjs +492 -0
  22. package/lib/native-router.mjs +221 -0
  23. package/lib/policy.mjs +17 -21
  24. package/package.json +10 -8
  25. package/scripts/migrate-config.mjs +57 -0
  26. package/types/index.d.ts +112 -0
  27. package/lib/cost.mjs +0 -93
  28. package/lib/gateway.mjs +0 -221
  29. package/lib/idle.mjs +0 -41
  30. package/lib/rewrite.mjs +0 -130
  31. package/lib/router.mjs +0 -276
  32. package/lib/runtime.mjs +0 -78
  33. package/lib/sse.mjs +0 -57
  34. package/lib/status.mjs +0 -152
  35. package/lib/store.mjs +0 -76
  36. package/scripts/ensure-gateway.mjs +0 -143
  37. package/scripts/gateway.mjs +0 -81
  38. package/scripts/git-hooks/pre-commit +0 -41
  39. package/scripts/git-hooks/pre-push +0 -34
  40. package/scripts/status.mjs +0 -20
  41. package/scripts/statusline.mjs +0 -45
  42. package/scripts/transcript-models.sh +0 -4
  43. package/skills/high/SKILL.md +0 -9
  44. package/skills/low/SKILL.md +0 -7
  45. package/skills/medium/SKILL.md +0 -8
  46. package/skills/micro/SKILL.md +0 -7
  47. package/skills/setup/SKILL.md +0 -31
  48. package/skills/status/SKILL.md +0 -12
@@ -0,0 +1,88 @@
1
+ import { EFFORTS } from './config.mjs';
2
+
3
+ export function cacheKey(modelId, effort) {
4
+ return effort ? `${modelId}@${effort}` : modelId;
5
+ }
6
+
7
+ export function clampEffort(wanted, supported) {
8
+ if (!wanted || supported.length === 0) return null;
9
+ if (supported.includes(wanted)) return wanted;
10
+ for (let i = EFFORTS.indexOf(wanted); i >= 0; i -= 1) if (supported.includes(EFFORTS[i])) return EFFORTS[i];
11
+ return supported[0];
12
+ }
13
+
14
+ export function nextContextTokens(facts) {
15
+ const previous = facts.lastRequest ? facts.lastRequest.tokens + facts.lastRequest.outputTokens : 0;
16
+ return Math.max(previous, Number.isFinite(facts.contextTokens) ? facts.contextTokens : 0);
17
+ }
18
+
19
+ export function routeEffort(config, tier, sentEffort) {
20
+ const route = config.routes[tier];
21
+ const model = config.models[route.model];
22
+ if (model.efforts.length === 0) return null;
23
+ if (route.effort) return clampEffort(route.effort, model.efforts);
24
+ if (typeof sentEffort === 'number' && Number.isFinite(sentEffort)) return sentEffort;
25
+ return clampEffort(sentEffort, model.efforts);
26
+ }
27
+
28
+ export function routeCacheKey(config, tier, sentEffort) {
29
+ return cacheKey(config.models[config.routes[tier].model].id, routeEffort(config, tier, sentEffort));
30
+ }
31
+
32
+ export function isWarm(state, now, cache) {
33
+ return Boolean(
34
+ state?.prefixTokens > 0 && now >= state.lastAt && now < state.lastAt + cache.ttlMs['5m'] - cache.warmMarginMs,
35
+ );
36
+ }
37
+
38
+ export function cacheState(state, now, cache) {
39
+ return isWarm(state, now, cache) ? 'fresh' : 'unknown';
40
+ }
41
+
42
+ // Bounds are scenarios, never an independent ledger. Unknown incumbent cache can still be served.
43
+ export function inputBounds(config, tier, tokens, facts, now) {
44
+ const model = config.models[config.routes[tier].model];
45
+ const state = facts.models[routeCacheKey(config, tier, facts.effort)];
46
+ const prefix = Math.min(state?.prefixTokens ?? tokens, tokens);
47
+ const fresh = isWarm(state, now, config.cache);
48
+ const maximumWrite = model.input * Math.max(...Object.values(config.cache.writeMultiplier));
49
+ return {
50
+ min: (model.cacheRead * prefix + model.input * (tokens - prefix)) / 1e6,
51
+ max: fresh ? (model.cacheRead * prefix + maximumWrite * (tokens - prefix)) / 1e6 : (maximumWrite * tokens) / 1e6,
52
+ };
53
+ }
54
+
55
+ export function coldWriteUsd(config, alias, tokens) {
56
+ return (config.models[alias].input * Math.max(...Object.values(config.cache.writeMultiplier)) * tokens) / 1e6;
57
+ }
58
+
59
+ export function switchingTaxUsd(config, candidate, incumbent, facts, now) {
60
+ const tokens = nextContextTokens(facts);
61
+ return (
62
+ inputBounds(config, candidate, tokens, facts, now).max - inputBounds(config, incumbent, tokens, facts, now).min
63
+ );
64
+ }
65
+
66
+ export function shadowEconomics(config, candidate, incumbent, facts, now) {
67
+ const proposed = config.models[config.routes[candidate].model];
68
+ const current = config.models[config.routes[incumbent].model];
69
+ if (!(proposed.output > 0) || !(current.output > 0)) return null;
70
+ const tokens = nextContextTokens(facts);
71
+ const outputTokens = facts.lastRequest?.outputTokens ?? 0;
72
+ const output = ((proposed.output - current.output) * outputTokens) / 1e6;
73
+ const nextTurnUsd = switchingTaxUsd(config, candidate, incumbent, facts, now) + output;
74
+ const laterTurnUsd = ((proposed.cacheRead - current.cacheRead) * tokens) / 1e6 + output;
75
+ const paybackTurns =
76
+ nextTurnUsd <= 0 && laterTurnUsd <= 0
77
+ ? 0
78
+ : nextTurnUsd > 0 && laterTurnUsd < 0
79
+ ? Math.ceil(nextTurnUsd / -laterTurnUsd)
80
+ : null;
81
+ return { nextTurnUsd, laterTurnUsd, paybackTurns, outputTokens };
82
+ }
83
+
84
+ export function downgradeTaxUsd(config, candidate, incumbent, facts, now, turns) {
85
+ const estimate = shadowEconomics(config, candidate, incumbent, facts, now);
86
+ if (!estimate) return Math.max(0, switchingTaxUsd(config, candidate, incumbent, facts, now));
87
+ return Math.max(0, estimate.nextTurnUsd + (turns - 1) * estimate.laterTurnUsd);
88
+ }
@@ -0,0 +1,122 @@
1
+ import { tierForModel } from './native-router.mjs';
2
+
3
+ export const REASONS = {
4
+ ready: 'ready for the next turn',
5
+ 'same-tier': 'the task fits the current tier',
6
+ 'no-advice': 'keeping the current model without classifier advice',
7
+ continuation: 'continuing the previous task',
8
+ uncertain: 'the classifier could not justify a change',
9
+ upgrade: 'enough support for a stronger model',
10
+ jump: 'clear need for a stronger model',
11
+ downgrade: 'enough support for a cheaper model',
12
+ 'upgrade-pending': 'waiting before upgrading',
13
+ 'downgrade-pending': 'switching is not justified yet',
14
+ hold: 'staying after an escalation',
15
+ escalation: 'repeated tool failures need a stronger model',
16
+ 'cash-gate': 'estimated cold cache write exceeds the cap',
17
+ 'context-fit': 'a larger context window is needed',
18
+ 'context-unknown': 'context is not measured reliably',
19
+ 'model-unavailable': 'the requested model is not available',
20
+ pinned: 'one-turn model pin',
21
+ };
22
+
23
+ // The decision model behind the router. Named in the UI only where it explains a reading or a failure.
24
+ export const CLASSIFIER = 'Jev';
25
+ export const CLASSIFIER_ERRORS = {
26
+ 'missing-key': 'key not set',
27
+ paused: 'paused after failures',
28
+ timeout: 'timed out',
29
+ auth: 'rejected the key',
30
+ http: 'request failed',
31
+ unreachable: 'unreachable',
32
+ policy: 'blocked by network policy',
33
+ malformed: 'sent a bad answer',
34
+ busy: 'busy',
35
+ cancelled: 'cancelled',
36
+ };
37
+ // One or two words for the band; REASONS holds the sentence the pane shows.
38
+ export const SHORT_REASONS = {
39
+ ready: 'ready',
40
+ 'same-tier': '= fits',
41
+ 'no-advice': '= no advice',
42
+ continuation: '→ continuing',
43
+ uncertain: '= uncertain',
44
+ upgrade: '↑ upgrade',
45
+ jump: '↑ jump',
46
+ downgrade: '↓ downgrade',
47
+ 'upgrade-pending': '… waiting to go up',
48
+ 'downgrade-pending': '… waiting to go down',
49
+ hold: '= holding',
50
+ escalation: '↑ tool errors',
51
+ 'cash-gate': '= cash cap',
52
+ 'context-fit': '↑ context',
53
+ 'context-unknown': '= context unknown',
54
+ 'model-unavailable': '! model unavailable',
55
+ 'native-fallback': '! fallback',
56
+ pinned: '⏵ pinned',
57
+ interrupted: 'interrupted',
58
+ };
59
+
60
+ export const GATEWAY_SETTINGS = 'v0.8 gateway settings remain · see /router';
61
+ export const GATEWAY_CLEANUP = [
62
+ 'Remove from settings.json, then restart: model jev-router[1m], its modelPicker row,',
63
+ 'env.ANTHROPIC_BASE_URL for 127.0.0.1:43170, env.CLAUDE_CODE_GATEWAY_HINT_HEADERS,',
64
+ 'and a statusLine that runs the router scripts/statusline.mjs.',
65
+ ];
66
+
67
+ export function formatTokens(value) {
68
+ if (!Number.isFinite(value)) return 'unknown';
69
+ if (value >= 1_000_000) return `${(value / 1_000_000).toFixed(2)}M`;
70
+ if (value >= 1000) return `${(value / 1000).toFixed(1)}K`;
71
+ return String(Math.round(value));
72
+ }
73
+
74
+ export function bar(value, maximum, width = 16) {
75
+ if (!Number.isFinite(value) || !(maximum > 0)) return { text: 'unknown', percent: null, color: 'gray' };
76
+ const fraction = Math.max(0, value / maximum);
77
+ const filled = Math.min(width, Math.round(fraction * width));
78
+ return {
79
+ text: `${'█'.repeat(filled)}${'░'.repeat(width - filled)}`,
80
+ percent: Math.round(fraction * 100),
81
+ color: fraction > 0.8 ? 'red' : fraction > 0.6 ? 'yellow' : 'green',
82
+ };
83
+ }
84
+
85
+ export function usageMetrics(config, view, usage) {
86
+ const model = view.actualModel ?? view.selectedModel ?? view.nativeModel;
87
+ const tier = tierForModel(config, model);
88
+ const spec = tier ? config.models[config.routes[tier].model] : null;
89
+ const window = spec?.contextWindow ?? null;
90
+ const observed = Number.isFinite(usage?.context?.tokens) ? usage.context.tokens : null;
91
+ const candidates = [view.contextTokens, observed === null ? null : observed + (view.outputTokens ?? 0)].filter(
92
+ (value) => Number.isFinite(value),
93
+ );
94
+ const nextContext = candidates.length ? Math.max(...candidates) : null;
95
+ const reuse = view.inputTokens > 0 && Number.isFinite(view.cacheRead) ? view.cacheRead / view.inputTokens : null;
96
+ const cost = Number.isFinite(usage?.cost?.usd) ? usage.cost.usd : null;
97
+ const cacheBenefit =
98
+ spec && Number.isFinite(view.cacheRead) ? ((spec.input - spec.cacheRead) * view.cacheRead) / 1e6 : null;
99
+ return {
100
+ window,
101
+ observed,
102
+ nextContext,
103
+ reuse,
104
+ cost,
105
+ cacheBenefit,
106
+ contextBar: bar(nextContext, window),
107
+ cacheBar: {
108
+ ...bar(reuse, 1),
109
+ color: reuse === null ? 'gray' : reuse >= 0.6 ? 'green' : reuse >= 0.2 ? 'yellow' : 'gray',
110
+ },
111
+ };
112
+ }
113
+
114
+ // Scaled from the lowest to the highest reading: a long session's inputs sit close together, and a scale from zero
115
+ // draws them all as full blocks. Equal readings draw a flat middle line.
116
+ export function sparkline(values) {
117
+ if (!values.length || !values.every(Number.isFinite)) return 'no history yet';
118
+ const symbols = '▁▂▃▄▅▆▇█';
119
+ const minimum = Math.min(...values);
120
+ const span = Math.max(...values) - minimum;
121
+ return values.map((value) => symbols[span > 0 ? Math.round(((value - minimum) / span) * 7) : 3]).join('');
122
+ }
@@ -0,0 +1,125 @@
1
+ import {
2
+ buildRequest,
3
+ isTransientStatus,
4
+ JEV_FAILURES_TO_PAUSE,
5
+ JEV_PAUSE_MS,
6
+ parseAnswers,
7
+ RETRY_DELAY_MS,
8
+ retryDelayMs,
9
+ } from './jev-contract.mjs';
10
+
11
+ class AdviceError extends Error {
12
+ constructor(code) {
13
+ super(code);
14
+ this.code = code;
15
+ }
16
+ }
17
+
18
+ // Owned by one Mod activation. It survives history resets; the host cancels its work on unload.
19
+ export class NativeJev {
20
+ constructor({ now = Date.now, health = null } = {}) {
21
+ this.now = now;
22
+ this.pending = null;
23
+ this.active = false;
24
+ this.restore(health);
25
+ }
26
+
27
+ restore(health) {
28
+ this.failures =
29
+ Number.isInteger(health?.failures) && health.failures >= 0 ? Math.min(health.failures, JEV_FAILURES_TO_PAUSE) : 0;
30
+ this.pausedUntil = Number.isFinite(health?.pausedUntil) ? health.pausedUntil : 0;
31
+ }
32
+
33
+ snapshot() {
34
+ return { failures: this.failures, pausedUntil: this.pausedUntil };
35
+ }
36
+
37
+ async ask({ request, sleep, config, apiKey, prompt, turns, signal }) {
38
+ if (!apiKey) return { advice: null, error: 'missing-key' };
39
+ if (signal?.aborted) return { advice: null, error: 'cancelled' };
40
+ if (this.now() < this.pausedUntil) return { advice: null, error: 'paused' };
41
+ if (this.active || this.pending) return { advice: null, error: 'busy' };
42
+ this.active = true;
43
+ try {
44
+ const advice = await this.complete({ request, sleep, config, apiKey, prompt, turns, signal });
45
+ this.failures = 0;
46
+ this.pausedUntil = 0;
47
+ return { advice, error: null };
48
+ } catch (error) {
49
+ const code = signal?.aborted ? 'cancelled' : error instanceof AdviceError ? error.code : 'unreachable';
50
+ if (code !== 'cancelled' && code !== 'policy') {
51
+ this.failures = Math.min(this.failures + 1, JEV_FAILURES_TO_PAUSE);
52
+ if (this.failures >= JEV_FAILURES_TO_PAUSE) this.pausedUntil = this.now() + JEV_PAUSE_MS;
53
+ }
54
+ return { advice: null, error: code };
55
+ } finally {
56
+ this.active = false;
57
+ }
58
+ }
59
+
60
+ async complete({ request, sleep, config, apiKey, prompt, turns, signal }) {
61
+ const deadline = this.now() + config.jev.timeoutMs;
62
+ const body = JSON.stringify(buildRequest(config, prompt, turns));
63
+ for (let attempt = 0; attempt < 2; attempt += 1) {
64
+ const remaining = deadline - this.now();
65
+ if (signal?.aborted) throw new AdviceError('cancelled');
66
+ if (remaining <= 0) throw new AdviceError('timeout');
67
+ const call = Promise.resolve().then(() =>
68
+ request(config.jev.endpoint, {
69
+ method: 'POST',
70
+ headers: { authorization: `Bearer ${apiKey}`, 'content-type': 'application/json' },
71
+ body,
72
+ }),
73
+ );
74
+ this.pending = call;
75
+ const release = () => {
76
+ if (this.pending === call) this.pending = null;
77
+ };
78
+ call.then(release, release);
79
+ const timer = new AbortController();
80
+ const cancel = () => timer.abort();
81
+ signal?.addEventListener('abort', cancel, { once: true });
82
+ let response;
83
+ try {
84
+ response = await Promise.race([
85
+ call,
86
+ sleep(remaining, { signal: timer.signal }).then(() => {
87
+ throw new AdviceError('timeout');
88
+ }),
89
+ ]);
90
+ } catch (error) {
91
+ if (signal?.aborted) throw new AdviceError('cancelled');
92
+ if (error instanceof AdviceError) throw error;
93
+ if (/policy|denied|(?<!conn)refus|network access|nonessential/i.test(String(error?.message)))
94
+ throw new AdviceError('policy');
95
+ if (attempt === 1) throw new AdviceError('unreachable');
96
+ if (RETRY_DELAY_MS >= deadline - this.now()) throw new AdviceError('timeout');
97
+ await sleep(RETRY_DELAY_MS, { signal });
98
+ continue;
99
+ } finally {
100
+ signal?.removeEventListener('abort', cancel);
101
+ timer.abort();
102
+ }
103
+ if (signal?.aborted) throw new AdviceError('cancelled');
104
+ if (this.now() >= deadline) throw new AdviceError('timeout');
105
+ if (response.ok) {
106
+ try {
107
+ if (typeof response.text !== 'string' || response.text.length > 16_384) throw new AdviceError('malformed');
108
+ const advice = parseAnswers(JSON.parse(response.text));
109
+ if (this.now() >= deadline) throw new AdviceError('timeout');
110
+ return advice;
111
+ } catch (error) {
112
+ if (error instanceof AdviceError) throw error;
113
+ throw new AdviceError('malformed');
114
+ }
115
+ }
116
+ if (response.status === 401 || response.status === 403) throw new AdviceError('auth');
117
+ if (!isTransientStatus(response.status) || attempt === 1) throw new AdviceError('http');
118
+ const value = response.headers?.['retry-after'];
119
+ const wait = retryDelayMs(typeof value === 'string' ? value : null, this.now()) ?? RETRY_DELAY_MS;
120
+ if (wait >= deadline - this.now()) throw new AdviceError('timeout');
121
+ await sleep(wait, { signal });
122
+ }
123
+ throw new AdviceError('unreachable');
124
+ }
125
+ }