@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
package/lib/gateway.mjs DELETED
@@ -1,221 +0,0 @@
1
- // Local Anthropic Messages gateway: byte-for-byte passthrough, except a routed request gets its
2
- // model, effort and thinking rewritten. Never re-serializes responses; reads usage on a tee.
3
- // Upstream errors (429, 529, 5xx) pass through unchanged: Claude Code owns retries and backoff.
4
- import { createServer, request as httpRequest } from 'node:http';
5
- import { request as httpsRequest } from 'node:https';
6
- import { pipeline } from 'node:stream';
7
- import { IdleTracker } from './idle.mjs';
8
- import { adaptBetas } from './rewrite.mjs';
9
- import { isSideRequest } from './router.mjs';
10
- import { UsageReader } from './sse.mjs';
11
- import { ROUTER_DISPLAY_NAME, STATUS_PATH, statusSnapshot } from './status.mjs';
12
-
13
- const HOP_BY_HOP = new Set(['host', 'connection', 'content-length', 'accept-encoding', 'transfer-encoding']);
14
- const LOOPBACK = new Set(['127.0.0.1', 'localhost', '[::1]']);
15
- const MESSAGES_PATH = '/v1/messages';
16
-
17
- // The betas the routed model accepts: rewrite.mjs owns what each model takes.
18
- function withSupportedBetas(headers, modelId, config) {
19
- if (typeof headers['anthropic-beta'] !== 'string') return;
20
- const kept = adaptBetas(headers['anthropic-beta'], modelId, config);
21
- if (kept) headers['anthropic-beta'] = kept;
22
- else delete headers['anthropic-beta'];
23
- }
24
-
25
- export function createGateway({
26
- router,
27
- upstream = 'https://api.anthropic.com',
28
- onError = () => {},
29
- activity = new IdleTracker(),
30
- }) {
31
- const target = new URL(upstream);
32
- const send = target.protocol === 'https:' ? httpsRequest : httpRequest;
33
-
34
- return createServer((req, res) => {
35
- activity.requestStarted();
36
- res.once('close', () => activity.requestEnded());
37
- if (!isLocalClient(req))
38
- return reply(res, 403, errorBody('permission_error', 'router: the gateway serves local clients only'));
39
- if (req.method === 'GET' && req.url.startsWith('/v1/models')) return discovery(router, res);
40
- if (req.method === 'GET' && req.url.startsWith(STATUS_PATH)) return status(router, req, res);
41
- let up = null;
42
- let closedEarly = false;
43
- // The client left before its response was complete (Esc in Claude Code, a client timeout). Before the upstream
44
- // answers, abort the upstream request here; after, pipeline() below does it. Either way the model stops generating.
45
- res.on('close', () => {
46
- if (res.writableFinished) return;
47
- closedEarly = true;
48
- if (!res.headersSent) up?.destroy();
49
- });
50
- const chunks = [];
51
- req.on('data', (c) => chunks.push(c));
52
- req.on('end', async () => {
53
- try {
54
- let body = Buffer.concat(chunks);
55
- const parsed = parseJson(body);
56
- const session = sessionKey(req, parsed);
57
- const turn = isMessagesCall(req);
58
- // Only the conversation itself waits for tool results; a side request on the same session says nothing about it.
59
- // Only the hint header decides here: by body shape a turn with thinking off looks like a side request, and
60
- // keeping a wait too long costs less than exiting under a permission prompt.
61
- const { requestClass } = routingHints(req);
62
- const side = Boolean(requestClass) && isSideRequest(parsed ?? {}, requestClass);
63
- if (turn && !side) activity.turnResumed(session);
64
- let routed = null;
65
- if (parsed && router.isRouted(parsed)) {
66
- if (turn) {
67
- try {
68
- routed = await router.route(parsed, { sessionId: session, ...routingHints(req) });
69
- } catch (error) {
70
- onError(error);
71
- routed = router.fallback(parsed, session, routingHints(req)); // never forward the alias upstream
72
- }
73
- } else routed = router.resolveModel(parsed, session);
74
- body = Buffer.from(JSON.stringify(routed.body));
75
- }
76
- if (closedEarly) return; // the client left while the route was decided
77
- const headers = {};
78
- for (const [name, value] of Object.entries(req.headers)) if (!HOP_BY_HOP.has(name)) headers[name] = value;
79
- headers.host = target.host;
80
- headers['content-length'] = String(body.length);
81
- if (routed) withSupportedBetas(headers, routed.body.model, router.config);
82
- up = send(
83
- { host: target.hostname, port: target.port || undefined, path: req.url, method: req.method, headers },
84
- (upRes) => relay(upRes, res, { routed, session, turn, clientLeft: () => closedEarly }),
85
- );
86
- up.on('error', (error) => {
87
- if (closedEarly) return; // aborted above because the client left
88
- fail(res, new Error(`upstream: ${error.message}`));
89
- });
90
- up.end(body);
91
- } catch (error) {
92
- fail(res, error);
93
- }
94
- });
95
- });
96
-
97
- function relay(upRes, res, { routed, session, turn, clientLeft }) {
98
- const reader = turn ? new UsageReader() : null;
99
- // pipeline() reports ECONNRESET for both kinds of failure; only the side that closed first says whose it was.
100
- let upstreamBroke = false;
101
- upRes.once('close', () => {
102
- upstreamBroke = !upRes.complete && !clientLeft();
103
- });
104
- res.writeHead(upRes.statusCode, upRes.headers);
105
- if (reader) upRes.on('data', (c) => reader.feed(c.toString('utf8')));
106
- // pipeline() tears down both sides on failure. An upstream reset reaches the client as a reset it retries at once,
107
- // where pipe() left it waiting for bytes that never came; a client that leaves stops the upstream response.
108
- pipeline(upRes, res, (error) => {
109
- if (error) {
110
- if (upstreamBroke) onError(new Error(`upstream stream: ${error.message}`));
111
- return;
112
- }
113
- if (!reader) return;
114
- if (upRes.statusCode >= 300) {
115
- if (routed) tryRecord(() => router.recordFailure(session, routed, upRes.statusCode));
116
- return;
117
- }
118
- const usage = reader.end();
119
- if (reader.stopReason === 'tool_use') activity.turnPaused(session);
120
- if (!routed || routed.auxiliary) return;
121
- tryRecord(() => router.recordResponse(session, routed.tier, usage, routed.effort));
122
- });
123
- }
124
-
125
- function tryRecord(record) {
126
- try {
127
- record();
128
- } catch (error) {
129
- onError(error);
130
- }
131
- }
132
-
133
- function fail(res, error) {
134
- onError(error);
135
- if (!res.headersSent) res.writeHead(502);
136
- res.end();
137
- }
138
- }
139
-
140
- // Claude Code sends its session id as a header; the metadata field is the fallback. A subagent's requests carry
141
- // its agent id too: it gets its own routing memory, so its turns do not mix with the main conversation's.
142
- export function sessionKey(req, body) {
143
- const agent = req.headers['x-claude-code-agent-id'];
144
- const session = sessionOf(req, body);
145
- return agent ? `${session}.${agent}` : session;
146
- }
147
-
148
- function sessionOf(req, body) {
149
- const header = req.headers['x-claude-code-session-id'];
150
- if (header) return String(header);
151
- try {
152
- return JSON.parse(body?.metadata?.user_id ?? '{}').session_id ?? 'unknown';
153
- } catch {
154
- return 'unknown';
155
- }
156
- }
157
-
158
- // Gateway hint headers, sent when CLAUDE_CODE_GATEWAY_HINT_HEADERS=1. Without them the router falls back to the body.
159
- function routingHints(req) {
160
- return {
161
- requestClass: req.headers['x-claude-code-request-class'] ?? null,
162
- agentType: req.headers['x-claude-code-agent-type'] ?? null,
163
- contextCompacted: req.headers['x-claude-code-context-compacted'] ?? null,
164
- };
165
- }
166
-
167
- // A web page can reach a loopback port too: by DNS rebinding (a foreign Host) or by a request from a page, which
168
- // always carries an Origin, even one served from another loopback port. Claude Code sends a loopback Host and no Origin.
169
- function isLocalClient(req) {
170
- return LOOPBACK.has(hostOf(req.headers.host)) && req.headers.origin === undefined;
171
- }
172
-
173
- function hostOf(host = '') {
174
- return host.replace(/:\d+$/, '').toLowerCase();
175
- }
176
-
177
- // Only a Messages call is a turn. Side endpoints such as count_tokens carry the alias too, but no decision.
178
- function isMessagesCall(req) {
179
- return req.method === 'POST' && req.url.split('?')[0] === MESSAGES_PATH;
180
- }
181
-
182
- function parseJson(buffer) {
183
- if (!buffer.length) return null;
184
- try {
185
- return JSON.parse(buffer.toString('utf8'));
186
- } catch {
187
- return null;
188
- }
189
- }
190
-
191
- function discovery(router, res) {
192
- const { alias } = router.config.gateway;
193
- reply(res, 200, {
194
- data: [{ id: alias, display_name: ROUTER_DISPLAY_NAME, description: routesDescription(router.config) }],
195
- });
196
- }
197
-
198
- function status(router, req, res) {
199
- const session = new URL(req.url, 'http://localhost').searchParams.get('session');
200
- const pausedUntil = router.jevPausedUntil > router.now() ? new Date(router.jevPausedUntil).toISOString() : null;
201
- reply(res, 200, {
202
- ...statusSnapshot(router.config, session ? router.memory(session) : null),
203
- pid: process.pid,
204
- jevPausedUntil: pausedUntil,
205
- });
206
- }
207
-
208
- function reply(res, statusCode, payload) {
209
- res.writeHead(statusCode, { 'content-type': 'application/json' });
210
- res.end(JSON.stringify(payload));
211
- }
212
-
213
- function errorBody(type, message) {
214
- return { type: 'error', error: { type, message } };
215
- }
216
-
217
- // "Picks claude-opus-5-5 / claude-sonnet-5-5 / claude-haiku-4-5 and the effort for each turn"
218
- export function routesDescription(config) {
219
- const ids = [...new Set(Object.values(config.routes).map((r) => config.models[r.model].id))];
220
- return `Picks ${ids.join(' / ')} and the effort for each turn`;
221
- }
package/lib/idle.mjs DELETED
@@ -1,41 +0,0 @@
1
- // When the gateway may exit on its own. Claude Code holds no connection open between requests, so an idle session
2
- // and a closed one look the same here: the signal is time without requests. Two cases must still keep the gateway:
3
- // a request in flight, and a turn that waits for a tool result (a permission prompt or a question nobody answered
4
- // yet), whose next request comes without a prompt and so without the hook that would start a gateway again.
5
- // A session killed mid-turn stops counting after TURN_WAIT_MS.
6
- export const TURN_WAIT_MS = 24 * 3_600_000;
7
-
8
- export class IdleTracker {
9
- constructor({ now = Date.now } = {}) {
10
- this.now = now;
11
- this.inFlight = 0;
12
- this.lastActive = now();
13
- this.waiting = new Map(); // session -> when its last response asked for a tool
14
- }
15
-
16
- requestStarted() {
17
- this.inFlight += 1;
18
- this.lastActive = this.now();
19
- }
20
-
21
- requestEnded() {
22
- this.inFlight -= 1;
23
- this.lastActive = this.now();
24
- }
25
-
26
- // A Messages request for the session: whatever it waited for has arrived.
27
- turnResumed(session) {
28
- this.waiting.delete(session);
29
- }
30
-
31
- turnPaused(session) {
32
- this.waiting.set(session, this.now());
33
- }
34
-
35
- idle(idleMs) {
36
- const now = this.now();
37
- if (this.inFlight > 0 || now - this.lastActive < idleMs) return false;
38
- for (const [session, at] of this.waiting) if (now - at >= TURN_WAIT_MS) this.waiting.delete(session);
39
- return this.waiting.size === 0;
40
- }
41
- }
package/lib/rewrite.mjs DELETED
@@ -1,130 +0,0 @@
1
- // Turn a request for the router alias into a request for a concrete model. `model`, `max_tokens`,
2
- // `output_config.effort`, `thinking` and thinking edits in `context_management` change. For a model without a
3
- // request feature that Claude Code uses (config FEATURES), the messages and the beta header lose that feature,
4
- // as Claude Code itself does when the model answers 400; system prompt and tools are never touched.
5
- import { EFFORTS } from './config.mjs';
6
-
7
- const TOOL_CHANGE_BLOCKS = new Set(['tool_addition', 'tool_removal']);
8
- const LONG_CONTEXT_BETA = /^context-1m-/;
9
- const LONG_CONTEXT_WINDOW = 1_000_000;
10
- // Each feature is a beta; a model without the feature answers the beta with 400.
11
- const FEATURE_BETAS = {
12
- 'mid-conversation-system': /^mid-conversation-system-/,
13
- 'per-turn-control': /^per-turn-control-/,
14
- 'mid-conversation-tool-changes': /^mid-conversation-tool-changes-/,
15
- };
16
-
17
- export function rewriteRequest(body, tier, config) {
18
- const route = config.routes[tier];
19
- const model = config.models[route.model];
20
- const out = { ...body, model: model.id };
21
- // A route's own effort also goes into per-turn control, which overrides the request's effort on the model.
22
- const routeEffort = route.effort ? clampEffort(route.effort, model.efforts) : null;
23
- if (Array.isArray(body.messages)) out.messages = adaptMessages(body.messages, model.features ?? [], routeEffort);
24
- if (model.maxOutput && out.max_tokens > model.maxOutput) out.max_tokens = model.maxOutput;
25
- if (model.efforts.length === 0) return withoutThinking(out, body.output_config);
26
- const effort = clampEffort(route.effort ?? body.output_config?.effort, model.efforts);
27
- if (effort) out.output_config = { ...(body.output_config ?? {}), effort };
28
- return out;
29
- }
30
-
31
- // The `anthropic-beta` header for the routed model, or null when nothing is left. `jev-router[1m]` makes Claude Code
32
- // send the 1M context beta on every request; a model with a smaller window answers it with 400.
33
- export function adaptBetas(beta, modelId, config) {
34
- const model = Object.values(config.models).find((m) => m.id === modelId);
35
- if (!model) return beta;
36
- const features = model.features ?? [];
37
- const dropped = Object.entries(FEATURE_BETAS)
38
- .filter(([feature]) => !features.includes(feature))
39
- .map(([, pattern]) => pattern);
40
- if (model.contextWindow < LONG_CONTEXT_WINDOW) dropped.push(LONG_CONTEXT_BETA);
41
- const kept = beta.split(',').filter((flag) => !dropped.some((pattern) => pattern.test(flag.trim())));
42
- return kept.length ? kept.join(',') : null;
43
- }
44
-
45
- // Pure and deterministic: the same history adapts the same way on every turn, so the cached prefix holds.
46
- function adaptMessages(messages, features, routeEffort) {
47
- let out = messages;
48
- if (!features.includes('per-turn-control')) out = out.map(withoutTurnControl).filter(Boolean);
49
- else if (routeEffort && out.some((m) => turnEffortOf(m) && turnEffortOf(m) !== routeEffort))
50
- out = out.map((m) => (turnEffortOf(m) ? { ...m, output_config: { ...m.output_config, effort: routeEffort } } : m));
51
- if (!features.includes('mid-conversation-tool-changes')) out = out.map(withoutToolChanges).filter(Boolean);
52
- if (!features.includes('mid-conversation-system')) out = foldSystemMessages(out);
53
- return out;
54
- }
55
-
56
- // Per-turn control is an `output_config` (the turn's effort) on a message, usually the system message after the prompt.
57
- // A message that carried only that is dropped: the API rejects empty content.
58
- function withoutTurnControl(message) {
59
- if (!message || !Object.hasOwn(message, 'output_config')) return message;
60
- const { output_config: _turn, ...rest } = message;
61
- return Array.isArray(rest.content) && rest.content.length === 0 ? null : rest;
62
- }
63
-
64
- function turnEffortOf(message) {
65
- return message?.output_config?.effort ?? null;
66
- }
67
-
68
- // Drops tool_addition and tool_removal blocks. A dropped block's cache breakpoint moves to the block before it, or the
69
- // turn loses its last breakpoint; a message left empty is dropped.
70
- function withoutToolChanges(message) {
71
- if (!Array.isArray(message.content) || !message.content.some((b) => TOOL_CHANGE_BLOCKS.has(b?.type))) return message;
72
- const content = [];
73
- for (const block of message.content) {
74
- if (!TOOL_CHANGE_BLOCKS.has(block?.type)) content.push(block);
75
- else if (block.cache_control && content.length && !content.at(-1).cache_control)
76
- content[content.length - 1] = { ...content.at(-1), cache_control: block.cache_control };
77
- }
78
- return content.length ? { ...message, content } : null;
79
- }
80
-
81
- // A `system` message becomes text in the user message next to it, wrapped as a system reminder: the form Claude Code
82
- // uses for hook output when the model takes no system messages.
83
- function foldSystemMessages(messages) {
84
- const out = [];
85
- let lastFolded = false;
86
- for (const message of messages) {
87
- const folded = message.role === 'system';
88
- const next = folded ? { role: 'user', content: blocks(message.content).map(asReminder) } : message;
89
- const prev = out.at(-1);
90
- if (prev?.role === 'user' && next.role === 'user' && (folded || lastFolded))
91
- out[out.length - 1] = { ...prev, content: [...blocks(prev.content), ...next.content] };
92
- else out.push(next);
93
- lastFolded = folded;
94
- }
95
- return out;
96
- }
97
-
98
- function blocks(content) {
99
- if (typeof content === 'string') return [{ type: 'text', text: content }];
100
- return Array.isArray(content) ? content : [];
101
- }
102
-
103
- function asReminder(block) {
104
- return block?.type === 'text' ? { ...block, text: `<system-reminder>\n${block.text}\n</system-reminder>` } : block;
105
- }
106
-
107
- // Highest supported level at or below the wanted one, as Claude Code does for its own models.
108
- export function clampEffort(wanted, supported) {
109
- if (!wanted || supported.length === 0) return null;
110
- if (supported.includes(wanted)) return wanted;
111
- for (let i = EFFORTS.indexOf(wanted); i >= 0; i -= 1) if (supported.includes(EFFORTS[i])) return EFFORTS[i];
112
- return supported[0];
113
- }
114
-
115
- // A family with no effort control has no adaptive thinking either: omit both and run without thinking.
116
- // The API rejects a clear_thinking edit without thinking, so drop those edits too.
117
- function withoutThinking(out, outputConfig) {
118
- delete out.thinking;
119
- const edits = out.context_management?.edits;
120
- if (edits) {
121
- const kept = edits.filter((e) => !e.type?.startsWith('clear_thinking'));
122
- if (kept.length) out.context_management = { ...out.context_management, edits: kept };
123
- else delete out.context_management;
124
- }
125
- if (!outputConfig) return out;
126
- const { effort: _dropped, ...rest } = outputConfig;
127
- if (Object.keys(rest).length) out.output_config = rest;
128
- else delete out.output_config;
129
- return out;
130
- }
package/lib/router.mjs DELETED
@@ -1,276 +0,0 @@
1
- // Per-request orchestration: facts -> advice -> policy -> rewritten body. Knows nothing about HTTP.
2
- import { LEGACY_ALIAS, TIERS } from './config.mjs';
3
- import { cacheKey, nextContextTokens, shadowEconomics } from './cost.mjs';
4
- import { factsFromRequest } from './facts.mjs';
5
- import { askJev } from './jev.mjs';
6
- import { decide, fitTier, initialState } from './policy.mjs';
7
- import { rewriteRequest } from './rewrite.mjs';
8
- import { appendLog, loadMemory, saveMemory } from './store.mjs';
9
-
10
- const COMPACTION_SHRINK = 0.8;
11
- // Jev down: after this many failures in a row, new turns skip it for the cooldown instead of waiting out its timeout.
12
- export const JEV_FAILURES_TO_PAUSE = 3;
13
- export const JEV_PAUSE_MS = 60_000;
14
- // Reasons that reuse the route of the turn and must not replace the reason that chose it.
15
- const REUSED_ROUTE = new Set(['tool-continuation', 'retry']);
16
- // `x-claude-code-request-class` values that are side requests. `main`, `subagent` and `workflow` carry a conversation.
17
- const SIDE_REQUEST_CLASSES = new Set(['auxiliary', 'compaction']);
18
-
19
- export function emptyMemory() {
20
- return {
21
- lastRoute: null,
22
- lastReason: null,
23
- lastEstimate: null,
24
- lastEffort: null,
25
- lastRequest: null,
26
- lastTurnKey: null,
27
- lastMessageCount: null,
28
- models: {},
29
- state: null,
30
- // Set by a pinned turn: the route to decide the next prompt from.
31
- pin: null,
32
- };
33
- }
34
-
35
- // The history the gateway saw is gone: a compaction or a rewind. The cached prefixes are unknown, and the votes and
36
- // the escalation hold were about turns that are no longer in it. The route stays until the next decision.
37
- // `lastRequest` stays: until the next response it is the only size there is, and as an upper bound it errs safe.
38
- // A rewind can keep most of a long context, and a size of zero would let context-fit send it to a small window.
39
- function restartHistory(memory) {
40
- memory.models = {};
41
- if (memory.state) memory.state = { ...memory.state, votes: [], holdUntilTurn: 0, escalatedSignature: null };
42
- }
43
-
44
- export class Router {
45
- constructor({ config, fetchFn, dataDir, now = Date.now, onError = () => {} }) {
46
- this.config = config;
47
- this.fetchFn = fetchFn;
48
- this.dataDir = dataDir;
49
- this.now = now;
50
- this.onError = onError;
51
- this.memories = new Map();
52
- this.jevFailures = 0;
53
- this.jevPausedUntil = 0;
54
- }
55
-
56
- isRouted(body) {
57
- return body?.model === this.config.gateway.alias || body?.model === LEGACY_ALIAS;
58
- }
59
-
60
- // Returns { body, tier, reason, auxiliary }. The caller forwards `body` and records the response
61
- // usage only when `auxiliary` is false: side requests carry their own context sizes.
62
- // The hints come from Claude Code's gateway headers (CLAUDE_CODE_GATEWAY_HINT_HEADERS=1); each may be missing.
63
- async route(body, { sessionId, requestClass = null, agentType = null, contextCompacted = null }) {
64
- const memory = this.memory(sessionId);
65
- const auxiliary = isSideRequest(body, requestClass);
66
- // Messages only grow within one history. Fewer than the last main request: Claude Code compacted the conversation
67
- // or the user rewound it. Context editing clears tool results but keeps the messages, so it is not a break.
68
- const messageCount = Array.isArray(body.messages) ? body.messages.length : 0;
69
- const rewound = !auxiliary && memory.lastMessageCount !== null && messageCount < memory.lastMessageCount;
70
- if (contextCompacted || rewound) {
71
- restartHistory(memory);
72
- this.log({ session: sessionId, historyBreak: contextCompacted ? 'compaction' : 'shorter-history' });
73
- }
74
- const facts = factsFromRequest(body, memory, this.config.context);
75
- let decision;
76
- if (auxiliary) decision = { tier: this.config.gateway.auxiliaryTier, reason: 'auxiliary', state: memory.state };
77
- else if (facts.continuation && memory.lastRoute)
78
- decision = { tier: memory.lastRoute, reason: 'tool-continuation', state: memory.state };
79
- else if (facts.turnKey && facts.turnKey === memory.lastTurnKey && memory.lastRoute)
80
- decision = { tier: memory.lastRoute, reason: 'retry', state: memory.state };
81
- else {
82
- // A pin serves its turn and the turn's tool calls; the next prompt is decided from the route before the pin.
83
- if (memory.pin) {
84
- memory.lastRoute = memory.pin.returnTo;
85
- facts.lastRoute = memory.pin.returnTo;
86
- memory.pin = null;
87
- }
88
- decision = await this.decideTurn(facts, memory);
89
- }
90
- const pinnedTurn = decision.reason === 'pinned';
91
- // Main turns and compaction carry the main conversation; other side requests have their own, unknown size.
92
- if (!auxiliary || requestClass === 'compaction') {
93
- const tier = fitTier(this.config, decision.tier, nextContextTokens(facts));
94
- if (tier !== decision.tier) decision = { ...decision, tier, reason: 'context-fit' };
95
- }
96
- const rewritten = rewriteRequest(body, decision.tier, this.config);
97
- const effort = rewritten.output_config?.effort ?? null;
98
- if (!auxiliary) {
99
- if (pinnedTurn) memory.pin = { returnTo: memory.lastRoute };
100
- memory.lastRoute = decision.tier;
101
- memory.lastEffort = effort;
102
- memory.lastTurnKey = facts.turnKey;
103
- memory.lastMessageCount = messageCount;
104
- if (!REUSED_ROUTE.has(decision.reason)) {
105
- memory.lastReason = decision.reason;
106
- memory.lastEstimate = decision.estimate ?? null;
107
- }
108
- memory.state = decision.state;
109
- this.persist(sessionId, memory);
110
- }
111
- this.log({
112
- session: sessionId,
113
- requestClass,
114
- agentType,
115
- tier: decision.tier,
116
- model: rewritten.model,
117
- effort,
118
- reason: decision.reason,
119
- estimate: decision.estimate ?? null,
120
- shadow: decision.shadow ?? null,
121
- advice: decision.advice ?? null,
122
- adviceError: decision.adviceError ?? null,
123
- contextTokens: memory.lastRequest?.tokens ?? 0,
124
- });
125
- return {
126
- body: rewritten,
127
- tier: decision.tier,
128
- effort,
129
- reason: decision.reason,
130
- auxiliary,
131
- };
132
- }
133
-
134
- // Used when routing itself failed: the alias must never reach Anthropic. The log line has the reason only: an
135
- // error message can quote the request.
136
- fallback(body, sessionId, { requestClass = null } = {}) {
137
- const tier = this.config.gateway.baselineTier;
138
- const rewritten = rewriteRequest(body, tier, this.config);
139
- const effort = rewritten.output_config?.effort ?? null;
140
- this.log({ session: sessionId, requestClass, tier, model: rewritten.model, effort, reason: 'error' });
141
- return { body: rewritten, tier, effort, reason: 'error', auxiliary: true };
142
- }
143
-
144
- // A routed turn that Anthropic answered with an error status: no usage to record, but the turn is visible.
145
- recordFailure(sessionId, routed, status) {
146
- this.log({
147
- session: sessionId,
148
- failed: { status, tier: routed.tier, model: routed.body.model, effort: routed.effort ?? null },
149
- });
150
- }
151
-
152
- // Side endpoints (count_tokens) name the alias too. They get the session's current model: no Jev call, no vote.
153
- resolveModel(body, sessionId) {
154
- const tier = this.memory(sessionId).lastRoute ?? this.config.gateway.baselineTier;
155
- return { body: rewriteRequest(body, tier, this.config), tier, reason: 'side-endpoint', auxiliary: true };
156
- }
157
-
158
- async decideTurn(facts, memory) {
159
- const state = memory.state ?? initialState();
160
- const { forcedTier, apiKey, gateway } = this.config;
161
- if (forcedTier) return { tier: forcedTier, reason: 'forced', state: { ...state, turn: state.turn + 1 } };
162
- // A typed /router:<tier> pins this turn. Claude Code no longer switches the model from the skill's frontmatter.
163
- if (TIERS.includes(facts.pin))
164
- return { tier: facts.pin, reason: 'pinned', state: { ...state, turn: state.turn + 1 } };
165
- let advice = null;
166
- let adviceError = null;
167
- if (apiKey && facts.prompt) {
168
- if (this.now() < this.jevPausedUntil) adviceError = 'jev paused after repeated failures';
169
- else {
170
- try {
171
- advice = await askJev({
172
- fetchFn: this.fetchFn,
173
- config: this.config,
174
- apiKey,
175
- prompt: facts.prompt,
176
- turns: facts.turns,
177
- now: this.now,
178
- });
179
- this.jevSucceeded();
180
- } catch (error) {
181
- adviceError = error.message;
182
- this.jevFailed(error);
183
- }
184
- }
185
- }
186
- const now = this.now();
187
- const decision = decide({ config: this.config, facts, advice, state, baseline: gateway.baselineTier, now });
188
- // Shadow only: what following Jev's choice instead of staying would cost at list prices. The policy does not read
189
- // this record; the downgrade tax computes its own from the same function.
190
- const incumbent = TIERS.includes(facts.lastRoute) ? facts.lastRoute : gateway.baselineTier;
191
- const shadow =
192
- TIERS.includes(advice?.choice) && advice.choice !== incumbent
193
- ? shadowEconomics(this.config, advice.choice, incumbent, facts, now)
194
- : null;
195
- return { ...decision, advice, adviceError, shadow };
196
- }
197
-
198
- jevSucceeded() {
199
- if (this.jevFailures >= JEV_FAILURES_TO_PAUSE) this.onError(new Error('jev answers again, routing resumed'));
200
- this.jevFailures = 0;
201
- this.jevPausedUntil = 0;
202
- }
203
-
204
- // The count stays at or above the threshold while Jev keeps failing: after a pause, one failed try pauses again.
205
- jevFailed(error) {
206
- this.jevFailures += 1;
207
- if (this.jevFailures < JEV_FAILURES_TO_PAUSE) return;
208
- this.jevPausedUntil = this.now() + JEV_PAUSE_MS;
209
- if (this.jevFailures === JEV_FAILURES_TO_PAUSE)
210
- this.onError(
211
- new Error(
212
- `jev failed ${JEV_FAILURES_TO_PAUSE} times in a row (${error.message}): new turns use the baseline, one try every ${JEV_PAUSE_MS / 1000}s`,
213
- ),
214
- );
215
- }
216
-
217
- // Called with the usage the gateway read from a forwarded main-conversation response, and the effort the gateway
218
- // sent with that request: the cache is keyed by both.
219
- recordResponse(sessionId, tier, usage, effort = null) {
220
- if (!usage) return;
221
- const memory = this.memory(sessionId);
222
- const modelId = usage.model ?? this.config.models[this.config.routes[tier].model].id;
223
- const at = this.now();
224
- // A context that shrank by more than a fifth: a compaction, or context editing that cleared old tool results.
225
- // Either way the cached prefixes no longer match. The votes stay: a shorter history in messages resets them.
226
- if (memory.lastRequest && usage.tokens < memory.lastRequest.tokens * COMPACTION_SHRINK) {
227
- memory.models = {};
228
- this.log({ session: sessionId, cacheReset: 'context-shrink' });
229
- }
230
- memory.lastRequest = {
231
- model: modelId,
232
- tokens: usage.tokens,
233
- cacheReadTokens: usage.cacheReadTokens,
234
- outputTokens: usage.outputTokens,
235
- ttl: usage.ttl,
236
- at,
237
- };
238
- memory.models[cacheKey(modelId, effort)] = {
239
- lastAt: at,
240
- prefixTokens: usage.tokens + usage.outputTokens,
241
- ttl: usage.ttl,
242
- };
243
- this.persist(sessionId, memory);
244
- this.log({ session: sessionId, observed: { ...usage, model: modelId, tier, effort } });
245
- }
246
-
247
- memory(sessionId) {
248
- if (!this.memories.has(sessionId)) this.memories.set(sessionId, loadMemory(this.dataDir, sessionId, emptyMemory()));
249
- return this.memories.get(sessionId);
250
- }
251
-
252
- // Disk trouble (full, read-only) must not cost the routing decision: the in-memory state stays authoritative.
253
- persist(sessionId, memory) {
254
- try {
255
- saveMemory(this.dataDir, sessionId, memory);
256
- } catch (error) {
257
- this.onError(error);
258
- }
259
- }
260
-
261
- log(entry) {
262
- if (!this.config.log) return;
263
- try {
264
- appendLog(this.dataDir, { at: new Date(this.now()).toISOString(), ...entry });
265
- } catch (error) {
266
- this.onError(error);
267
- }
268
- }
269
- }
270
-
271
- // A request outside the conversation (title, classifier, compaction), by the request-class hint header. Without the
272
- // header: side requests turn thinking off or ask for a schema.
273
- export function isSideRequest(body, requestClass) {
274
- if (requestClass) return SIDE_REQUEST_CLASSES.has(requestClass);
275
- return body.thinking?.type === 'disabled' || Boolean(body.output_config?.format);
276
- }