@alexeiled/claude-router 0.7.2 → 1.0.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 (44) hide show
  1. package/.claude-plugin/plugin.json +10 -6
  2. package/CHANGELOG.md +43 -0
  3. package/README.md +51 -100
  4. package/docs/architecture.md +55 -414
  5. package/docs/configuration.md +86 -182
  6. package/docs/evaluation.md +62 -81
  7. package/docs/native-router.md +79 -0
  8. package/docs/user-guide.md +103 -172
  9. package/hooks/hooks.json +1 -26
  10. package/hooks/native-router.mjs +635 -0
  11. package/lib/config.mjs +24 -60
  12. package/lib/{facts.mjs → facts-pure.mjs} +2 -23
  13. package/lib/{jev.mjs → jev-contract.mjs} +17 -38
  14. package/lib/native-cost.mjs +88 -0
  15. package/lib/native-display.mjs +75 -0
  16. package/lib/native-jev.mjs +125 -0
  17. package/lib/native-panel.mjs +150 -0
  18. package/lib/native-router.mjs +216 -0
  19. package/lib/policy.mjs +17 -21
  20. package/package.json +9 -8
  21. package/scripts/migrate-config.mjs +57 -0
  22. package/types/index.d.ts +95 -0
  23. package/lib/cost.mjs +0 -93
  24. package/lib/gateway.mjs +0 -221
  25. package/lib/idle.mjs +0 -41
  26. package/lib/rewrite.mjs +0 -130
  27. package/lib/router.mjs +0 -276
  28. package/lib/runtime.mjs +0 -78
  29. package/lib/sse.mjs +0 -57
  30. package/lib/status.mjs +0 -152
  31. package/lib/store.mjs +0 -76
  32. package/scripts/ensure-gateway.mjs +0 -143
  33. package/scripts/gateway.mjs +0 -81
  34. package/scripts/git-hooks/pre-commit +0 -27
  35. package/scripts/git-hooks/pre-push +0 -34
  36. package/scripts/status.mjs +0 -20
  37. package/scripts/statusline.mjs +0 -45
  38. package/scripts/transcript-models.sh +0 -4
  39. package/skills/high/SKILL.md +0 -9
  40. package/skills/low/SKILL.md +0 -7
  41. package/skills/medium/SKILL.md +0 -8
  42. package/skills/micro/SKILL.md +0 -7
  43. package/skills/setup/SKILL.md +0 -31
  44. package/skills/status/SKILL.md +0 -12
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
- }
package/lib/runtime.mjs DELETED
@@ -1,78 +0,0 @@
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';
10
- import { readJsonFile } from './store.mjs';
11
-
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
- }
72
- return {
73
- config,
74
- dataDir: env.CLAUDE_PLUGIN_DATA || join(tmpdir(), 'router'),
75
- configPath: path,
76
- warning,
77
- };
78
- }
package/lib/sse.mjs DELETED
@@ -1,57 +0,0 @@
1
- // Incremental usage and stop-reason reader for a Messages response: streaming SSE or a plain JSON body.
2
- export class UsageReader {
3
- constructor() {
4
- this.buffer = '';
5
- this.usage = null;
6
- this.model = null;
7
- this.stopReason = null;
8
- }
9
-
10
- feed(chunk) {
11
- this.buffer += chunk;
12
- for (let at = this.buffer.indexOf('\n'); at >= 0; at = this.buffer.indexOf('\n')) {
13
- const line = this.buffer.slice(0, at).trim();
14
- this.buffer = this.buffer.slice(at + 1);
15
- if (line.startsWith('data:')) this.take(line.slice(5).trim());
16
- }
17
- }
18
-
19
- end() {
20
- const rest = this.buffer.trim();
21
- if (rest.startsWith('{')) this.take(rest);
22
- this.buffer = '';
23
- return this.result();
24
- }
25
-
26
- take(json) {
27
- let event;
28
- try {
29
- event = JSON.parse(json);
30
- } catch {
31
- return;
32
- }
33
- const message = event.type === 'message_start' ? event.message : event.type === 'message' ? event : null;
34
- if (message?.usage) {
35
- this.model = message.model ?? this.model;
36
- this.usage = { ...(this.usage ?? {}), ...message.usage };
37
- }
38
- if (message?.stop_reason) this.stopReason = message.stop_reason;
39
- if (event.type === 'message_delta') {
40
- if (event.usage) this.usage = { ...(this.usage ?? {}), ...event.usage };
41
- if (event.delta?.stop_reason) this.stopReason = event.delta.stop_reason;
42
- }
43
- }
44
-
45
- result() {
46
- if (!this.usage) return null;
47
- const u = this.usage;
48
- const tokens = (u.input_tokens ?? 0) + (u.cache_read_input_tokens ?? 0) + (u.cache_creation_input_tokens ?? 0);
49
- return {
50
- model: this.model,
51
- tokens,
52
- cacheReadTokens: u.cache_read_input_tokens ?? 0,
53
- outputTokens: u.output_tokens ?? 0,
54
- ttl: (u.cache_creation?.ephemeral_1h_input_tokens ?? 0) > 0 ? '1h' : '5m',
55
- };
56
- }
57
- }
package/lib/status.mjs DELETED
@@ -1,152 +0,0 @@
1
- // Router status: the snapshot the gateway serves at GET /router/status, and its text forms for the
2
- // status line and /router:status. The snapshot never carries the API key, only whether one is set.
3
- import { createRequire } from 'node:module';
4
- import { TIERS } from './config.mjs';
5
- import { clampEffort } from './rewrite.mjs';
6
-
7
- const _require = createRequire(import.meta.url);
8
- export const ROUTER_VERSION = _require('../package.json').version;
9
-
10
- // True when `running` is older than `current`. Gateways before 0.3.0 report no version: they count as older.
11
- export function isOlderVersion(running, current) {
12
- const parse = (v) => (/^\d+\.\d+\.\d+/.test(v ?? '') ? v.split('.').map((n) => Number.parseInt(n, 10)) : [0, 0, 0]);
13
- const [a, b] = [parse(running), parse(current)];
14
- for (let i = 0; i < 3; i += 1) if (a[i] !== b[i]) return a[i] < b[i];
15
- return false;
16
- }
17
-
18
- export const STATUS_PATH = '/router/status';
19
- // The name of the alias in the /model picker and in discovery.
20
- export const ROUTER_DISPLAY_NAME = 'Jev Router (auto)';
21
- const FETCH_TIMEOUT_MS = 300;
22
-
23
- export function statusSnapshot(config, memory) {
24
- const { alias, port, baselineTier } = config.gateway;
25
- return {
26
- version: ROUTER_VERSION,
27
- alias,
28
- port,
29
- keySet: Boolean(config.apiKey),
30
- forcedTier: config.forcedTier ?? null,
31
- baselineTier,
32
- routes: TIERS.map((tier) => routeRow(config, tier)),
33
- session: memory?.lastRoute
34
- ? {
35
- tier: memory.lastRoute,
36
- reason: memory.lastReason ?? null,
37
- estimate: memory.lastEstimate ?? null,
38
- effort: memory.lastEffort ?? null,
39
- model: memory.lastRequest?.model ?? null,
40
- tokens: memory.lastRequest?.tokens ?? null,
41
- cacheReadTokens: memory.lastRequest?.cacheReadTokens ?? null,
42
- at: memory.lastRequest?.at ?? null,
43
- }
44
- : null,
45
- };
46
- }
47
-
48
- function routeRow(config, tier) {
49
- const route = config.routes[tier];
50
- const model = config.models[route.model];
51
- const effort = model.efforts.length === 0 ? 'none' : (clampEffort(route.effort, model.efforts) ?? 'as sent');
52
- return { tier, model: model.id, effort };
53
- }
54
-
55
- // Why the route of the last turn is what it is, for /router:status.
56
- const REASONS = {
57
- upgrade: 'Jev voted above the current tier often enough, with enough mass for the switching tax',
58
- jump: 'Jev was confident enough to skip a tier and the vote delay',
59
- downgrade: 'Jev voted for a lower tier often enough, with enough mass',
60
- 'upgrade-pending': 'Jev asked for a higher tier; the route stays until the votes and the mass are enough',
61
- 'downgrade-pending': 'Jev asked for a lower tier; the route stays until the votes and the mass are enough',
62
- 'same-tier': 'Jev agreed with the current tier',
63
- continuation: 'the prompt continues the task, so the route stays',
64
- uncertain: 'Jev abstained, so the route stays',
65
- 'no-advice': 'no Jev answer (no key, a failure or a pause), so the route stays',
66
- escalation: 'the same error came back after an edit: one tier up',
67
- hold: 'the tier stays up for a few turns after an escalation',
68
- 'cash-gate':
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
- 'context-fit': "the chosen model's window does not hold the context",
71
- forced: 'the gateway was started with --force-tier',
72
- pinned: 'you pinned this turn with /router:<tier>',
73
- };
74
-
75
- // One status-line segment, e.g. "router ▸ opus-5-5 · xhigh · upgrade".
76
- export function statusSegment(status) {
77
- if (!status) return 'router: gateway off, the next prompt starts it';
78
- const last = status.session;
79
- if (!last) return `${status.alias}: no turn yet`;
80
- const model = shortModel(last.model ?? status.routes.find((r) => r.tier === last.tier)?.model);
81
- return [`${status.alias} ▸ ${model}`, last.effort, last.reason].filter(Boolean).join(' · ');
82
- }
83
-
84
- // Markdown for /router:status.
85
- export function statusReport(status) {
86
- if (!status)
87
- return 'The router gateway is not running. The next prompt starts it. If it does not start, read `gateway.log` in the plugin data directory.';
88
- const lines = [
89
- `Router v${status.version}, gateway: http://127.0.0.1:${status.port}, alias \`${status.alias}\`.`,
90
- `Jev routing: ${jevState(status)}.`,
91
- `Default tier: ${status.baselineTier}.${status.forcedTier ? ` Forced tier: ${status.forcedTier}.` : ''}`,
92
- '',
93
- '| Tier | Model | Effort |',
94
- '| ---- | ----- | ------ |',
95
- ...status.routes.map((r) => `| ${r.tier} | ${r.model} | ${r.effort} |`),
96
- '',
97
- ];
98
- const last = status.session;
99
- if (!last) lines.push('No routed turn in this session yet.');
100
- else {
101
- const model = last.model ?? status.routes.find((r) => r.tier === last.tier)?.model;
102
- const effort = last.effort ? ` at ${last.effort}` : '';
103
- const context = last.tokens ? `, context ${last.tokens} tokens, cache reads ${last.cacheReadTokens}` : '';
104
- lines.push(`Last turn: ${last.tier} → ${model}${effort}, reason ${last.reason ?? 'unknown'}${context}.`);
105
- if (REASONS[last.reason]) lines.push(`Why: ${REASONS[last.reason]}.`);
106
- const estimate = describeEstimate(last.estimate);
107
- if (estimate) lines.push(`Estimate: ${estimate}.`);
108
- }
109
- return lines.join('\n');
110
- }
111
-
112
- // Dollars are list prices: for `plan` models a list-price equivalent, not a charge. `unknown` cache: no response for
113
- // that cache since the session started or its history broke.
114
- function describeEstimate(e) {
115
- if (!e) return null;
116
- const usd = (n) => `$${n.toFixed(2)}`;
117
- const parts = [];
118
- if (e.upgradeMass !== undefined)
119
- parts.push(
120
- `upgrade mass ${e.upgradeMass.toFixed(2)} against a bar of ${e.threshold.toFixed(2)}`,
121
- `switching tax ${usd(e.taxUsd)} at list prices`,
122
- );
123
- if (e.downgradeMass !== undefined) parts.push(`downgrade mass ${e.downgradeMass.toFixed(2)}`);
124
- if (e.coldUsd !== undefined) parts.push(`cold write ${usd(e.coldUsd)} against the cap of ${usd(e.cap)}`);
125
- if (e.streak !== undefined) parts.push(`${e.streak} vote(s) in a row`);
126
- if (e.cache?.candidate) parts.push(`cache: candidate ${e.cache.candidate}, current ${e.cache.incumbent}`);
127
- else if (typeof e.cache === 'string') parts.push(`cache ${e.cache}`);
128
- return parts.join(', ');
129
- }
130
-
131
- // null when the gateway does not answer in time.
132
- export async function fetchStatus(port, sessionId) {
133
- const query = sessionId ? `?session=${encodeURIComponent(sessionId)}` : '';
134
- try {
135
- const res = await fetch(`http://127.0.0.1:${port}${STATUS_PATH}${query}`, {
136
- signal: AbortSignal.timeout(FETCH_TIMEOUT_MS),
137
- });
138
- return res.ok ? await res.json() : null;
139
- } catch {
140
- return null;
141
- }
142
- }
143
-
144
- function jevState(status) {
145
- if (!status.keySet) return 'inactive, no key: every turn runs on the default tier';
146
- if (status.jevPausedUntil) return `paused after repeated failures, next try at ${status.jevPausedUntil}`;
147
- return 'active';
148
- }
149
-
150
- function shortModel(id) {
151
- return id ? id.replace(/^claude-/, '') : 'unknown';
152
- }
package/lib/store.mjs DELETED
@@ -1,76 +0,0 @@
1
- // Files: user config, per-session memory and the decision log. The only module that touches the filesystem.
2
- import {
3
- appendFileSync,
4
- mkdirSync,
5
- readdirSync,
6
- readFileSync,
7
- renameSync,
8
- rmSync,
9
- statSync,
10
- writeFileSync,
11
- } from 'node:fs';
12
- import { join } from 'node:path';
13
-
14
- export const LOG_LIMIT_BYTES = 20 * 1024 * 1024;
15
- const SESSION_TTL_MS = 30 * 24 * 3_600_000;
16
-
17
- // A JSON syntax error says only that: V8's message quotes the text around the bad token, and the hook prints it.
18
- export function readJsonFile(path) {
19
- try {
20
- return JSON.parse(readFileSync(path, 'utf8'));
21
- } catch (error) {
22
- if (error.code === 'ENOENT') return null;
23
- throw new Error(`cannot read ${path}: ${error instanceof SyntaxError ? 'not valid JSON' : error.message}`);
24
- }
25
- }
26
-
27
- export function loadMemory(dir, sessionId, fallback) {
28
- try {
29
- return { ...fallback, ...JSON.parse(readFileSync(memoryPath(dir, sessionId), 'utf8')) };
30
- } catch {
31
- return fallback;
32
- }
33
- }
34
-
35
- export function saveMemory(dir, sessionId, memory) {
36
- mkdirSync(join(dir, 'sessions'), { recursive: true });
37
- const path = memoryPath(dir, sessionId);
38
- writeFileSync(`${path}.tmp`, JSON.stringify(memory));
39
- renameSync(`${path}.tmp`, path);
40
- }
41
-
42
- export function appendLog(dir, entry) {
43
- mkdirSync(dir, { recursive: true });
44
- appendFileSync(join(dir, 'decisions.jsonl'), `${JSON.stringify(entry)}\n`);
45
- }
46
-
47
- // Keeps one previous generation: `<file>.1`. Only for files written by path, not held open.
48
- export function rotate(path, limitBytes = LOG_LIMIT_BYTES) {
49
- try {
50
- if (statSync(path).size > limitBytes) renameSync(path, `${path}.1`);
51
- } catch (error) {
52
- if (error.code !== 'ENOENT') throw error;
53
- }
54
- }
55
-
56
- // Bounds the data directory of a long-running gateway: the decision log and a month of session memory.
57
- // gateway.log is the daemon's open stderr, so the hook that starts the daemon rotates it instead.
58
- export function housekeeping(dir, now = Date.now()) {
59
- rotate(join(dir, 'decisions.jsonl'));
60
- const sessions = join(dir, 'sessions');
61
- let names;
62
- try {
63
- names = readdirSync(sessions);
64
- } catch (error) {
65
- if (error.code === 'ENOENT') return;
66
- throw error;
67
- }
68
- for (const name of names) {
69
- const path = join(sessions, name);
70
- if (now - statSync(path).mtimeMs > SESSION_TTL_MS) rmSync(path, { force: true });
71
- }
72
- }
73
-
74
- function memoryPath(dir, sessionId) {
75
- return join(dir, 'sessions', `${String(sessionId).replace(/[^\w.-]/g, '_')}.json`);
76
- }