@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,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 = { candidate: cacheOf(config, choice, facts, now), incumbent: cacheOf(config, incumbent, facts, now) };
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)) return { blocked: false };
94
- const cold = coldWriteUsd(config, alias, nextContextTokens(facts), facts);
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.8.0",
4
- "description": "Claude Code plugin: auto-picks the right model and effort for each turn using Jev routing.",
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
- "skills",
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
+ }
@@ -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
- }