@alexeiled/claude-router 0.6.1 → 0.7.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 +1 -1
- package/CHANGELOG.md +90 -0
- package/README.md +94 -78
- package/docs/architecture.md +414 -291
- package/docs/configuration.md +151 -162
- package/docs/evaluation.md +83 -0
- package/docs/tier-share.svg +73 -44
- package/docs/user-guide.md +176 -114
- package/lib/config.mjs +98 -13
- package/lib/facts.mjs +35 -6
- package/lib/gateway.mjs +33 -30
- package/lib/jev.mjs +7 -4
- package/lib/rewrite.mjs +93 -3
- package/lib/router.mjs +41 -8
- package/lib/runtime.mjs +72 -7
- package/lib/status.mjs +2 -1
- package/lib/store.mjs +2 -1
- package/package.json +3 -2
- package/scripts/ensure-gateway.mjs +34 -8
- package/scripts/gateway.mjs +12 -2
- package/scripts/status.mjs +16 -3
- package/scripts/statusline.mjs +6 -2
package/lib/gateway.mjs
CHANGED
|
@@ -5,23 +5,20 @@ import { createServer, request as httpRequest } from 'node:http';
|
|
|
5
5
|
import { request as httpsRequest } from 'node:https';
|
|
6
6
|
import { pipeline } from 'node:stream';
|
|
7
7
|
import { IdleTracker } from './idle.mjs';
|
|
8
|
+
import { adaptBetas } from './rewrite.mjs';
|
|
9
|
+
import { isSideRequest } from './router.mjs';
|
|
8
10
|
import { UsageReader } from './sse.mjs';
|
|
9
11
|
import { ROUTER_DISPLAY_NAME, STATUS_PATH, statusSnapshot } from './status.mjs';
|
|
10
12
|
|
|
11
13
|
const HOP_BY_HOP = new Set(['host', 'connection', 'content-length', 'accept-encoding', 'transfer-encoding']);
|
|
12
14
|
const LOOPBACK = new Set(['127.0.0.1', 'localhost', '[::1]']);
|
|
13
15
|
const MESSAGES_PATH = '/v1/messages';
|
|
14
|
-
|
|
15
|
-
|
|
16
|
-
|
|
17
|
-
|
|
18
|
-
|
|
19
|
-
|
|
20
|
-
const model = Object.values(config.models).find((m) => m.id === modelId);
|
|
21
|
-
const beta = headers['anthropic-beta'];
|
|
22
|
-
if (!model || model.contextWindow >= LONG_CONTEXT_WINDOW || typeof beta !== 'string') return;
|
|
23
|
-
const kept = beta.split(',').filter((flag) => !LONG_CONTEXT_BETA.test(flag.trim()));
|
|
24
|
-
if (kept.length) headers['anthropic-beta'] = kept.join(',');
|
|
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;
|
|
25
22
|
else delete headers['anthropic-beta'];
|
|
26
23
|
}
|
|
27
24
|
|
|
@@ -58,7 +55,12 @@ export function createGateway({
|
|
|
58
55
|
const parsed = parseJson(body);
|
|
59
56
|
const session = sessionKey(req, parsed);
|
|
60
57
|
const turn = isMessagesCall(req);
|
|
61
|
-
|
|
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);
|
|
62
64
|
let routed = null;
|
|
63
65
|
if (parsed && router.isRouted(parsed)) {
|
|
64
66
|
if (turn) {
|
|
@@ -66,7 +68,7 @@ export function createGateway({
|
|
|
66
68
|
routed = await router.route(parsed, { sessionId: session, ...routingHints(req) });
|
|
67
69
|
} catch (error) {
|
|
68
70
|
onError(error);
|
|
69
|
-
routed = router.fallback(parsed); // never forward the alias upstream
|
|
71
|
+
routed = router.fallback(parsed, session, routingHints(req)); // never forward the alias upstream
|
|
70
72
|
}
|
|
71
73
|
} else routed = router.resolveModel(parsed, session);
|
|
72
74
|
body = Buffer.from(JSON.stringify(routed.body));
|
|
@@ -76,7 +78,7 @@ export function createGateway({
|
|
|
76
78
|
for (const [name, value] of Object.entries(req.headers)) if (!HOP_BY_HOP.has(name)) headers[name] = value;
|
|
77
79
|
headers.host = target.host;
|
|
78
80
|
headers['content-length'] = String(body.length);
|
|
79
|
-
if (routed)
|
|
81
|
+
if (routed) withSupportedBetas(headers, routed.body.model, router.config);
|
|
80
82
|
up = send(
|
|
81
83
|
{ host: target.hostname, port: target.port || undefined, path: req.url, method: req.method, headers },
|
|
82
84
|
(upRes) => relay(upRes, res, { routed, session, turn, clientLeft: () => closedEarly }),
|
|
@@ -108,18 +110,26 @@ export function createGateway({
|
|
|
108
110
|
if (upstreamBroke) onError(new Error(`upstream stream: ${error.message}`));
|
|
109
111
|
return;
|
|
110
112
|
}
|
|
111
|
-
if (!reader
|
|
113
|
+
if (!reader) return;
|
|
114
|
+
if (upRes.statusCode >= 300) {
|
|
115
|
+
if (routed) tryRecord(() => router.recordFailure(session, routed, upRes.statusCode));
|
|
116
|
+
return;
|
|
117
|
+
}
|
|
112
118
|
const usage = reader.end();
|
|
113
119
|
if (reader.stopReason === 'tool_use') activity.turnPaused(session);
|
|
114
120
|
if (!routed || routed.auxiliary) return;
|
|
115
|
-
|
|
116
|
-
router.recordResponse(session, routed.tier, usage, routed.effort);
|
|
117
|
-
} catch (recordError) {
|
|
118
|
-
onError(recordError);
|
|
119
|
-
}
|
|
121
|
+
tryRecord(() => router.recordResponse(session, routed.tier, usage, routed.effort));
|
|
120
122
|
});
|
|
121
123
|
}
|
|
122
124
|
|
|
125
|
+
function tryRecord(record) {
|
|
126
|
+
try {
|
|
127
|
+
record();
|
|
128
|
+
} catch (error) {
|
|
129
|
+
onError(error);
|
|
130
|
+
}
|
|
131
|
+
}
|
|
132
|
+
|
|
123
133
|
function fail(res, error) {
|
|
124
134
|
onError(error);
|
|
125
135
|
if (!res.headersSent) res.writeHead(502);
|
|
@@ -154,17 +164,10 @@ function routingHints(req) {
|
|
|
154
164
|
};
|
|
155
165
|
}
|
|
156
166
|
|
|
157
|
-
// A web page can reach a loopback port too: by DNS rebinding (a foreign Host) or by a
|
|
158
|
-
// Origin
|
|
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.
|
|
159
169
|
function isLocalClient(req) {
|
|
160
|
-
|
|
161
|
-
const origin = req.headers.origin;
|
|
162
|
-
if (origin === undefined) return true;
|
|
163
|
-
try {
|
|
164
|
-
return LOOPBACK.has(new URL(origin).hostname);
|
|
165
|
-
} catch {
|
|
166
|
-
return false;
|
|
167
|
-
}
|
|
170
|
+
return LOOPBACK.has(hostOf(req.headers.host)) && req.headers.origin === undefined;
|
|
168
171
|
}
|
|
169
172
|
|
|
170
173
|
function hostOf(host = '') {
|
package/lib/jev.mjs
CHANGED
|
@@ -75,18 +75,21 @@ export async function askJev({ fetchFn, config, apiKey, prompt, turns, now = Dat
|
|
|
75
75
|
}
|
|
76
76
|
if (response.ok) return parseAnswers(await response.json());
|
|
77
77
|
if (!TRANSIENT.has(response.status) || attempt === 1) throw new Error(`jev http ${response.status}`);
|
|
78
|
-
const wait = retryAfterMs(response.headers) ?? RETRY_DELAY_MS;
|
|
78
|
+
const wait = retryAfterMs(response.headers, now()) ?? RETRY_DELAY_MS;
|
|
79
79
|
if (wait >= deadline - now()) throw new Error(`jev http ${response.status}, retry-after beyond the budget`);
|
|
80
80
|
await sleep(wait);
|
|
81
81
|
}
|
|
82
82
|
throw new Error('jev unreachable');
|
|
83
83
|
}
|
|
84
84
|
|
|
85
|
-
|
|
85
|
+
// Delay-seconds or an HTTP-date (RFC 9110). Seconds first: Date.parse also reads a bare number, as a year.
|
|
86
|
+
function retryAfterMs(headers, now) {
|
|
86
87
|
const value = headers?.get?.('retry-after');
|
|
87
|
-
if (value === null || value === undefined || value === '') return null;
|
|
88
|
+
if (value === null || value === undefined || value.trim() === '') return null;
|
|
88
89
|
const seconds = Number(value);
|
|
89
|
-
|
|
90
|
+
if (Number.isFinite(seconds)) return seconds >= 0 ? seconds * 1000 : null;
|
|
91
|
+
const at = Date.parse(value);
|
|
92
|
+
return Number.isFinite(at) ? Math.max(0, at - now) : null;
|
|
90
93
|
}
|
|
91
94
|
|
|
92
95
|
export function parseAnswers(json) {
|
package/lib/rewrite.mjs
CHANGED
|
@@ -1,12 +1,26 @@
|
|
|
1
|
-
// Turn a request for the router alias into a request for a concrete model.
|
|
2
|
-
// `output_config.effort`, `thinking` and thinking edits in `context_management` change
|
|
3
|
-
//
|
|
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.
|
|
4
5
|
import { EFFORTS } from './config.mjs';
|
|
5
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
|
+
|
|
6
17
|
export function rewriteRequest(body, tier, config) {
|
|
7
18
|
const route = config.routes[tier];
|
|
8
19
|
const model = config.models[route.model];
|
|
9
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);
|
|
10
24
|
if (model.maxOutput && out.max_tokens > model.maxOutput) out.max_tokens = model.maxOutput;
|
|
11
25
|
if (model.efforts.length === 0) return withoutThinking(out, body.output_config);
|
|
12
26
|
const effort = clampEffort(route.effort ?? body.output_config?.effort, model.efforts);
|
|
@@ -14,6 +28,82 @@ export function rewriteRequest(body, tier, config) {
|
|
|
14
28
|
return out;
|
|
15
29
|
}
|
|
16
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
|
+
|
|
17
107
|
// Highest supported level at or below the wanted one, as Claude Code does for its own models.
|
|
18
108
|
export function clampEffort(wanted, supported) {
|
|
19
109
|
if (!wanted || supported.length === 0) return null;
|
package/lib/router.mjs
CHANGED
|
@@ -27,11 +27,15 @@ export function emptyMemory() {
|
|
|
27
27
|
lastMessageCount: null,
|
|
28
28
|
models: {},
|
|
29
29
|
state: null,
|
|
30
|
+
// Set by a pinned turn: the route to decide the next prompt from.
|
|
31
|
+
pin: null,
|
|
30
32
|
};
|
|
31
33
|
}
|
|
32
34
|
|
|
33
35
|
// The history the gateway saw is gone: a compaction or a rewind. The cached prefixes are unknown, and the votes and
|
|
34
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.
|
|
35
39
|
function restartHistory(memory) {
|
|
36
40
|
memory.models = {};
|
|
37
41
|
if (memory.state) memory.state = { ...memory.state, votes: [], holdUntilTurn: 0, escalatedSignature: null };
|
|
@@ -58,7 +62,7 @@ export class Router {
|
|
|
58
62
|
// The hints come from Claude Code's gateway headers (CLAUDE_CODE_GATEWAY_HINT_HEADERS=1); each may be missing.
|
|
59
63
|
async route(body, { sessionId, requestClass = null, agentType = null, contextCompacted = null }) {
|
|
60
64
|
const memory = this.memory(sessionId);
|
|
61
|
-
const auxiliary =
|
|
65
|
+
const auxiliary = isSideRequest(body, requestClass);
|
|
62
66
|
// Messages only grow within one history. Fewer than the last main request: Claude Code compacted the conversation
|
|
63
67
|
// or the user rewound it. Context editing clears tool results but keeps the messages, so it is not a break.
|
|
64
68
|
const messageCount = Array.isArray(body.messages) ? body.messages.length : 0;
|
|
@@ -74,7 +78,16 @@ export class Router {
|
|
|
74
78
|
decision = { tier: memory.lastRoute, reason: 'tool-continuation', state: memory.state };
|
|
75
79
|
else if (facts.turnKey && facts.turnKey === memory.lastTurnKey && memory.lastRoute)
|
|
76
80
|
decision = { tier: memory.lastRoute, reason: 'retry', state: memory.state };
|
|
77
|
-
else
|
|
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';
|
|
78
91
|
// Main turns and compaction carry the main conversation; other side requests have their own, unknown size.
|
|
79
92
|
if (!auxiliary || requestClass === 'compaction') {
|
|
80
93
|
const tier = fitTier(this.config, decision.tier, nextContextTokens(facts));
|
|
@@ -83,6 +96,7 @@ export class Router {
|
|
|
83
96
|
const rewritten = rewriteRequest(body, decision.tier, this.config);
|
|
84
97
|
const effort = rewritten.output_config?.effort ?? null;
|
|
85
98
|
if (!auxiliary) {
|
|
99
|
+
if (pinnedTurn) memory.pin = { returnTo: memory.lastRoute };
|
|
86
100
|
memory.lastRoute = decision.tier;
|
|
87
101
|
memory.lastEffort = effort;
|
|
88
102
|
memory.lastTurnKey = facts.turnKey;
|
|
@@ -99,6 +113,8 @@ export class Router {
|
|
|
99
113
|
requestClass,
|
|
100
114
|
agentType,
|
|
101
115
|
tier: decision.tier,
|
|
116
|
+
model: rewritten.model,
|
|
117
|
+
effort,
|
|
102
118
|
reason: decision.reason,
|
|
103
119
|
estimate: decision.estimate ?? null,
|
|
104
120
|
shadow: decision.shadow ?? null,
|
|
@@ -115,10 +131,22 @@ export class Router {
|
|
|
115
131
|
};
|
|
116
132
|
}
|
|
117
133
|
|
|
118
|
-
// Used when routing itself failed: the alias must never reach Anthropic.
|
|
119
|
-
|
|
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 } = {}) {
|
|
120
137
|
const tier = this.config.gateway.baselineTier;
|
|
121
|
-
|
|
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
|
+
});
|
|
122
150
|
}
|
|
123
151
|
|
|
124
152
|
// Side endpoints (count_tokens) name the alias too. They get the session's current model: no Jev call, no vote.
|
|
@@ -131,6 +159,9 @@ export class Router {
|
|
|
131
159
|
const state = memory.state ?? initialState();
|
|
132
160
|
const { forcedTier, apiKey, gateway } = this.config;
|
|
133
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 } };
|
|
134
165
|
let advice = null;
|
|
135
166
|
let adviceError = null;
|
|
136
167
|
if (apiKey && facts.prompt) {
|
|
@@ -209,7 +240,7 @@ export class Router {
|
|
|
209
240
|
ttl: usage.ttl,
|
|
210
241
|
};
|
|
211
242
|
this.persist(sessionId, memory);
|
|
212
|
-
this.log({ session: sessionId, observed: { ...usage, model: modelId, tier } });
|
|
243
|
+
this.log({ session: sessionId, observed: { ...usage, model: modelId, tier, effort } });
|
|
213
244
|
}
|
|
214
245
|
|
|
215
246
|
memory(sessionId) {
|
|
@@ -236,7 +267,9 @@ export class Router {
|
|
|
236
267
|
}
|
|
237
268
|
}
|
|
238
269
|
|
|
239
|
-
//
|
|
240
|
-
|
|
270
|
+
// A request outside the conversation (title, classifier, compaction), by the request-class hint header. Without the
|
|
271
|
+
// header: side requests turn thinking off or ask for a schema.
|
|
272
|
+
export function isSideRequest(body, requestClass) {
|
|
273
|
+
if (requestClass) return SIDE_REQUEST_CLASSES.has(requestClass);
|
|
241
274
|
return body.thinking?.type === 'disabled' || Boolean(body.output_config?.format);
|
|
242
275
|
}
|
package/lib/runtime.mjs
CHANGED
|
@@ -1,13 +1,78 @@
|
|
|
1
|
-
// Process bootstrap shared by the daemon and the
|
|
2
|
-
|
|
3
|
-
|
|
4
|
-
|
|
1
|
+
// Process bootstrap shared by the daemon and the hooks: configuration and data directory from the environment.
|
|
2
|
+
// A project's `.claude/settings.json` can set process env for a plugin hook (ROUTER_CONFIG, HOME, ...). `home`
|
|
3
|
+
// comes from the OS user database (`os.userInfo().homedir`), never from `$HOME`, so a project cannot redirect it.
|
|
4
|
+
// A `ROUTER_CONFIG` env value is honored only when it resolves inside `<home>/.claude/`; anywhere else it is
|
|
5
|
+
// ignored (with a warning that names the variable, never the rejected path) and the default file is used instead.
|
|
6
|
+
import { execFileSync } from 'node:child_process';
|
|
7
|
+
import { tmpdir, userInfo } from 'node:os';
|
|
8
|
+
import { isAbsolute, join, relative, resolve } from 'node:path';
|
|
9
|
+
import { loadConfig, TIERS } from './config.mjs';
|
|
5
10
|
import { readJsonFile } from './store.mjs';
|
|
6
11
|
|
|
7
|
-
|
|
8
|
-
|
|
12
|
+
// null for a UID without a passwd entry (`docker run --user <uid>`, devcontainers), where userInfo() throws. There
|
|
13
|
+
// the only home is $HOME, which a project can set, so there is no trusted home at all.
|
|
14
|
+
export function userHome(info = userInfo) {
|
|
15
|
+
try {
|
|
16
|
+
return info().homedir;
|
|
17
|
+
} catch {
|
|
18
|
+
return null;
|
|
19
|
+
}
|
|
20
|
+
}
|
|
21
|
+
|
|
22
|
+
// Pure path resolution: no file access. `configPath` is an explicit `--config` value (unrestricted: it comes
|
|
23
|
+
// from a hook's own argv, which a project's settings cannot change) and wins over `env.ROUTER_CONFIG`.
|
|
24
|
+
// Without a trusted home the gateway runs on the defaults: starting beats an outage, and a project chooses nothing.
|
|
25
|
+
export function resolveConfigPath(env, { home = userHome(), configPath = null } = {}) {
|
|
26
|
+
if (configPath) return { path: resolve(configPath), warning: null };
|
|
27
|
+
if (!home) return { path: null, warning: 'no OS user account entry: router.json ignored, defaults used' };
|
|
28
|
+
const fallback = join(home, '.claude', 'router.json');
|
|
29
|
+
const requested = env.ROUTER_CONFIG;
|
|
30
|
+
if (!requested) return { path: fallback, warning: null };
|
|
31
|
+
const resolved = resolve(requested);
|
|
32
|
+
const rel = relative(join(home, '.claude'), resolved);
|
|
33
|
+
const inside = rel === '' || (!rel.startsWith('..') && !isAbsolute(rel));
|
|
34
|
+
if (inside) return { path: resolved, warning: null };
|
|
35
|
+
return { path: fallback, warning: 'ROUTER_CONFIG ignored: not under ~/.claude' };
|
|
36
|
+
}
|
|
37
|
+
|
|
38
|
+
// Whatever answers on the gateway port reports a pid; the hook signals it only if that pid runs this plugin's daemon.
|
|
39
|
+
// pid 0 or -1 would signal a process group or every process of the user, so neither reaches `ps` or `kill`.
|
|
40
|
+
export function isRouterGateway(pid, run = execFileSync) {
|
|
41
|
+
if (!Number.isInteger(pid) || pid <= 1) return false;
|
|
42
|
+
try {
|
|
43
|
+
return /scripts\/gateway\.mjs\b/.test(run('ps', ['-o', 'command=', '-p', String(pid)], { encoding: 'utf8' }));
|
|
44
|
+
} catch {
|
|
45
|
+
return false; // no such process, or no ps: do not signal
|
|
46
|
+
}
|
|
47
|
+
}
|
|
48
|
+
|
|
49
|
+
// `--flag value` from argv (e.g. `process.argv`). null when the flag is absent.
|
|
50
|
+
export function cliArg(argv, flag) {
|
|
51
|
+
const i = argv.indexOf(flag);
|
|
52
|
+
return i === -1 ? null : (argv[i + 1] ?? null);
|
|
53
|
+
}
|
|
54
|
+
|
|
55
|
+
// The --config for a gateway that a hook starts. spawn() turns null into "null", a path relative to the project the
|
|
56
|
+
// hook runs in, so no resolved path means no flag: the gateway then resolves the same way the hook did.
|
|
57
|
+
export function configArgs(configPath) {
|
|
58
|
+
return configPath ? ['--config', configPath] : [];
|
|
59
|
+
}
|
|
60
|
+
|
|
61
|
+
export function loadRuntime(env, { home = userHome(), configPath = null, forceTier = null } = {}) {
|
|
62
|
+
if (forceTier !== null && !TIERS.includes(forceTier))
|
|
63
|
+
throw new Error(`--force-tier must be one of ${TIERS.join(', ')}`);
|
|
64
|
+
const { path, warning } = resolveConfigPath(env, { home, configPath });
|
|
65
|
+
const userFile = path ? readJsonFile(path) : null; // its own errors name the file
|
|
66
|
+
let config;
|
|
67
|
+
try {
|
|
68
|
+
config = loadConfig({ env, userFile, forcedTier: forceTier });
|
|
69
|
+
} catch (error) {
|
|
70
|
+
throw new Error(`${path}: ${error.message}`);
|
|
71
|
+
}
|
|
9
72
|
return {
|
|
10
|
-
config
|
|
73
|
+
config,
|
|
11
74
|
dataDir: env.CLAUDE_PLUGIN_DATA || join(tmpdir(), 'router'),
|
|
75
|
+
configPath: path,
|
|
76
|
+
warning,
|
|
12
77
|
};
|
|
13
78
|
}
|
package/lib/status.mjs
CHANGED
|
@@ -68,7 +68,8 @@ const REASONS = {
|
|
|
68
68
|
'cash-gate':
|
|
69
69
|
'cold-write guard: the first cache write on a credits model would cost more than policy.cashCapUsd, so the strongest plan tier served',
|
|
70
70
|
'context-fit': "the chosen model's window does not hold the context",
|
|
71
|
-
forced: '
|
|
71
|
+
forced: 'the gateway was started with --force-tier',
|
|
72
|
+
pinned: 'you pinned this turn with /router:<tier>',
|
|
72
73
|
};
|
|
73
74
|
|
|
74
75
|
// One status-line segment, e.g. "router ▸ opus-5-5 · xhigh · upgrade".
|
package/lib/store.mjs
CHANGED
|
@@ -14,12 +14,13 @@ import { join } from 'node:path';
|
|
|
14
14
|
export const LOG_LIMIT_BYTES = 20 * 1024 * 1024;
|
|
15
15
|
const SESSION_TTL_MS = 30 * 24 * 3_600_000;
|
|
16
16
|
|
|
17
|
+
// A JSON syntax error says only that: V8's message quotes the text around the bad token, and the hook prints it.
|
|
17
18
|
export function readJsonFile(path) {
|
|
18
19
|
try {
|
|
19
20
|
return JSON.parse(readFileSync(path, 'utf8'));
|
|
20
21
|
} catch (error) {
|
|
21
22
|
if (error.code === 'ENOENT') return null;
|
|
22
|
-
throw new Error(`cannot read ${path}: ${error.message}`);
|
|
23
|
+
throw new Error(`cannot read ${path}: ${error instanceof SyntaxError ? 'not valid JSON' : error.message}`);
|
|
23
24
|
}
|
|
24
25
|
}
|
|
25
26
|
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@alexeiled/claude-router",
|
|
3
|
-
"version": "0.
|
|
3
|
+
"version": "0.7.0",
|
|
4
4
|
"description": "Claude Code plugin: auto-picks the right model and effort for each turn using Jev routing.",
|
|
5
5
|
"license": "MIT",
|
|
6
6
|
"author": "Alexei Ledenev",
|
|
@@ -20,7 +20,8 @@
|
|
|
20
20
|
"scripts",
|
|
21
21
|
"skills",
|
|
22
22
|
"docs",
|
|
23
|
-
"README.md"
|
|
23
|
+
"README.md",
|
|
24
|
+
"CHANGELOG.md"
|
|
24
25
|
],
|
|
25
26
|
"publishConfig": {
|
|
26
27
|
"access": "public"
|
|
@@ -8,7 +8,7 @@ import { mkdirSync, openSync } from 'node:fs';
|
|
|
8
8
|
import { connect } from 'node:net';
|
|
9
9
|
import { dirname, join } from 'node:path';
|
|
10
10
|
import { fileURLToPath } from 'node:url';
|
|
11
|
-
import { loadRuntime } from '../lib/runtime.mjs';
|
|
11
|
+
import { cliArg, configArgs, isRouterGateway, loadRuntime } from '../lib/runtime.mjs';
|
|
12
12
|
import { isOlderVersion, ROUTER_VERSION, STATUS_PATH } from '../lib/status.mjs';
|
|
13
13
|
import { rotate } from '../lib/store.mjs';
|
|
14
14
|
|
|
@@ -18,13 +18,31 @@ const STATUS_TIMEOUT_MS = 500;
|
|
|
18
18
|
|
|
19
19
|
const env = process.env;
|
|
20
20
|
const quiet = process.argv.includes('--quiet');
|
|
21
|
-
const { config, dataDir } = loadRuntime(env);
|
|
22
|
-
const port = config.gateway.port;
|
|
23
21
|
|
|
24
22
|
function say(message) {
|
|
25
23
|
if (!quiet) process.stdout.write(`router: ${message}\n`);
|
|
26
24
|
}
|
|
27
25
|
|
|
26
|
+
let config;
|
|
27
|
+
let dataDir;
|
|
28
|
+
let configPath;
|
|
29
|
+
let configWarning;
|
|
30
|
+
try {
|
|
31
|
+
({
|
|
32
|
+
config,
|
|
33
|
+
dataDir,
|
|
34
|
+
configPath,
|
|
35
|
+
warning: configWarning,
|
|
36
|
+
} = loadRuntime(env, {
|
|
37
|
+
configPath: cliArg(process.argv, '--config'),
|
|
38
|
+
}));
|
|
39
|
+
} catch (error) {
|
|
40
|
+
say(`invalid configuration (${error.message}); the next prompt tries again`);
|
|
41
|
+
process.exit(0);
|
|
42
|
+
}
|
|
43
|
+
if (configWarning) say(configWarning);
|
|
44
|
+
const port = config.gateway.port;
|
|
45
|
+
|
|
28
46
|
function probe() {
|
|
29
47
|
return new Promise((resolve) => {
|
|
30
48
|
const socket = connect({ host: '127.0.0.1', port });
|
|
@@ -66,6 +84,10 @@ async function retire(running) {
|
|
|
66
84
|
);
|
|
67
85
|
return false;
|
|
68
86
|
}
|
|
87
|
+
if (!isRouterGateway(running.pid)) {
|
|
88
|
+
say(`port ${port} answers as gateway ${from}, but pid ${running.pid} is not a router gateway: left alone`);
|
|
89
|
+
return false;
|
|
90
|
+
}
|
|
69
91
|
try {
|
|
70
92
|
process.kill(running.pid, 'SIGTERM');
|
|
71
93
|
} catch (error) {
|
|
@@ -91,11 +113,15 @@ async function start() {
|
|
|
91
113
|
...env,
|
|
92
114
|
TYPESAFE_API_KEY: env.TYPESAFE_API_KEY || env.CLAUDE_PLUGIN_OPTION_TYPESAFE_API_KEY || '',
|
|
93
115
|
};
|
|
94
|
-
const child = spawn(
|
|
95
|
-
|
|
96
|
-
|
|
97
|
-
|
|
98
|
-
|
|
116
|
+
const child = spawn(
|
|
117
|
+
process.execPath,
|
|
118
|
+
[join(dirname(fileURLToPath(import.meta.url)), 'gateway.mjs'), ...configArgs(configPath)],
|
|
119
|
+
{
|
|
120
|
+
detached: true,
|
|
121
|
+
stdio: ['ignore', log, log],
|
|
122
|
+
env: childEnv,
|
|
123
|
+
},
|
|
124
|
+
);
|
|
99
125
|
child.unref();
|
|
100
126
|
// Wait for the listener so the session's first request finds it.
|
|
101
127
|
return { pid: child.pid, up: await waitFor(true) };
|
package/scripts/gateway.mjs
CHANGED
|
@@ -3,7 +3,7 @@
|
|
|
3
3
|
import { createGateway } from '../lib/gateway.mjs';
|
|
4
4
|
import { IdleTracker } from '../lib/idle.mjs';
|
|
5
5
|
import { Router } from '../lib/router.mjs';
|
|
6
|
-
import { loadRuntime } from '../lib/runtime.mjs';
|
|
6
|
+
import { cliArg, loadRuntime } from '../lib/runtime.mjs';
|
|
7
7
|
import { ROUTER_VERSION } from '../lib/status.mjs';
|
|
8
8
|
import { housekeeping } from '../lib/store.mjs';
|
|
9
9
|
|
|
@@ -21,7 +21,17 @@ const onError = (error) => log(error.message);
|
|
|
21
21
|
process.on('uncaughtException', (error) => log(`uncaught exception: ${error.stack ?? error.message}`));
|
|
22
22
|
process.on('unhandledRejection', (reason) => log(`unhandled rejection: ${reason?.stack ?? reason}`));
|
|
23
23
|
|
|
24
|
-
|
|
24
|
+
let config;
|
|
25
|
+
let dataDir;
|
|
26
|
+
try {
|
|
27
|
+
({ config, dataDir } = loadRuntime(process.env, {
|
|
28
|
+
configPath: cliArg(process.argv, '--config'),
|
|
29
|
+
forceTier: cliArg(process.argv, '--force-tier'),
|
|
30
|
+
}));
|
|
31
|
+
} catch (error) {
|
|
32
|
+
log(`invalid configuration: ${error.message}`);
|
|
33
|
+
process.exit(1);
|
|
34
|
+
}
|
|
25
35
|
const { port, alias, idleShutdownMs } = config.gateway;
|
|
26
36
|
const router = new Router({ config, fetchFn: globalThis.fetch, dataDir, onError });
|
|
27
37
|
const activity = new IdleTracker();
|
package/scripts/status.mjs
CHANGED
|
@@ -1,7 +1,20 @@
|
|
|
1
1
|
#!/usr/bin/env node
|
|
2
2
|
// /router:status: routes, key state and the last routed turn of a session, as markdown.
|
|
3
|
-
|
|
3
|
+
// Usage: status.mjs [session id] [--config <path>]. It reads the configuration and starts nothing, so it is also
|
|
4
|
+
// the way to see why a router.json does not load.
|
|
5
|
+
import { cliArg, loadRuntime } from '../lib/runtime.mjs';
|
|
4
6
|
import { fetchStatus, statusReport } from '../lib/status.mjs';
|
|
5
7
|
|
|
6
|
-
const
|
|
7
|
-
|
|
8
|
+
const argv = process.argv.slice(2);
|
|
9
|
+
const configPath = cliArg(argv, '--config');
|
|
10
|
+
const session = argv.find((arg, i) => !arg.startsWith('--') && argv[i - 1] !== '--config');
|
|
11
|
+
|
|
12
|
+
let config;
|
|
13
|
+
try {
|
|
14
|
+
({ config } = loadRuntime(process.env, { configPath }));
|
|
15
|
+
} catch (error) {
|
|
16
|
+
// Exit 0: /router:status injects this output into a skill, and Claude Code drops a skill whose command fails.
|
|
17
|
+
process.stdout.write(`router: invalid configuration: ${error.message}\n`);
|
|
18
|
+
process.exit(0);
|
|
19
|
+
}
|
|
20
|
+
process.stdout.write(`${statusReport(await fetchStatus(config.gateway.port, session))}\n`);
|
package/scripts/statusline.mjs
CHANGED
|
@@ -10,13 +10,17 @@ import { fetchStatus, ROUTER_DISPLAY_NAME, statusSegment } from '../lib/status.m
|
|
|
10
10
|
|
|
11
11
|
const input = await text(process.stdin);
|
|
12
12
|
const [command, ...args] = process.argv.slice(2);
|
|
13
|
-
|
|
13
|
+
// A broken router.json must not break the status line: skip the router segment, still run a wrapped command.
|
|
14
|
+
let config = null;
|
|
15
|
+
try {
|
|
16
|
+
({ config } = loadRuntime(process.env));
|
|
17
|
+
} catch {}
|
|
14
18
|
let payload = {};
|
|
15
19
|
try {
|
|
16
20
|
payload = JSON.parse(input);
|
|
17
21
|
} catch {}
|
|
18
22
|
|
|
19
|
-
const names = [config.gateway.alias, LEGACY_ALIAS, ROUTER_DISPLAY_NAME];
|
|
23
|
+
const names = config ? [config.gateway.alias, LEGACY_ALIAS, ROUTER_DISPLAY_NAME] : [];
|
|
20
24
|
// `jev-router[1m]`: the suffix only tells Claude Code the window size.
|
|
21
25
|
const routed = [payload.model?.id, payload.model?.display_name].some((name) =>
|
|
22
26
|
names.includes(name?.replace(/\[1m\]$/, '')),
|