@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/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
- const LONG_CONTEXT_BETA = /^context-1m-/;
15
- const LONG_CONTEXT_WINDOW = 1_000_000;
16
-
17
- // `jev-router[1m]` makes Claude Code send the 1M context beta on every request; a model with a smaller
18
- // window answers it with 400 ("The long context beta is not yet available"), so drop it for those.
19
- function withoutLongContextBeta(headers, modelId, config) {
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
- if (turn) activity.turnResumed(session);
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) withoutLongContextBeta(headers, routed.body.model, router.config);
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 || upRes.statusCode >= 300) return;
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
- try {
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 cross-site request (a foreign
158
- // Origin). Claude Code sends a loopback Host and no 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
- if (!LOOPBACK.has(hostOf(req.headers.host))) return false;
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
- function retryAfterMs(headers) {
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
- return Number.isFinite(seconds) && seconds >= 0 ? seconds * 1000 : null;
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. Only `model`, `max_tokens`,
2
- // `output_config.effort`, `thinking` and thinking edits in `context_management` change;
3
- // system, tools and messages are never touched.
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 = requestClass ? SIDE_REQUEST_CLASSES.has(requestClass) : isAuxiliaryShape(body);
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 decision = await this.decideTurn(facts, memory);
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
- fallback(body) {
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
- return { body: rewriteRequest(body, tier, this.config), tier, reason: 'error', auxiliary: true };
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
- // Without the request-class hint header: side requests (titles, classifiers) turn thinking off and ask for a schema.
240
- function isAuxiliaryShape(body) {
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 SessionStart hook: configuration and data directory from the environment.
2
- import { homedir, tmpdir } from 'node:os';
3
- import { join } from 'node:path';
4
- import { loadConfig } from './config.mjs';
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
- export function loadRuntime(env) {
8
- const configPath = env.ROUTER_CONFIG ?? join(homedir(), '.claude', 'router.json');
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: loadConfig({ env, userFile: readJsonFile(configPath) }),
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: 'ROUTER_FORCE_TIER is set',
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.6.1",
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(process.execPath, [join(dirname(fileURLToPath(import.meta.url)), 'gateway.mjs')], {
95
- detached: true,
96
- stdio: ['ignore', log, log],
97
- env: childEnv,
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) };
@@ -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
- const { config, dataDir } = loadRuntime(process.env);
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();
@@ -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
- import { loadRuntime } from '../lib/runtime.mjs';
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 { config } = loadRuntime(process.env);
7
- process.stdout.write(`${statusReport(await fetchStatus(config.gateway.port, process.argv[2]))}\n`);
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`);
@@ -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
- const { config } = loadRuntime(process.env);
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\]$/, '')),