@alexeiled/claude-router 0.8.0 → 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.
- package/.claude-plugin/plugin.json +10 -6
- package/CHANGELOG.md +19 -0
- package/README.md +51 -100
- package/docs/architecture.md +55 -419
- package/docs/configuration.md +86 -182
- package/docs/evaluation.md +62 -81
- package/docs/native-router.md +79 -0
- package/docs/user-guide.md +103 -172
- package/hooks/hooks.json +1 -26
- package/hooks/native-router.mjs +635 -0
- package/lib/config.mjs +20 -58
- package/lib/{facts.mjs → facts-pure.mjs} +2 -23
- package/lib/{jev.mjs → jev-contract.mjs} +17 -38
- package/lib/native-cost.mjs +88 -0
- package/lib/native-display.mjs +75 -0
- package/lib/native-jev.mjs +125 -0
- package/lib/native-panel.mjs +150 -0
- package/lib/native-router.mjs +216 -0
- package/lib/policy.mjs +17 -21
- package/package.json +9 -8
- package/scripts/migrate-config.mjs +57 -0
- package/types/index.d.ts +95 -0
- package/lib/cost.mjs +0 -93
- package/lib/gateway.mjs +0 -221
- package/lib/idle.mjs +0 -41
- package/lib/rewrite.mjs +0 -130
- package/lib/router.mjs +0 -276
- package/lib/runtime.mjs +0 -78
- package/lib/sse.mjs +0 -57
- package/lib/status.mjs +0 -152
- package/lib/store.mjs +0 -76
- package/scripts/ensure-gateway.mjs +0 -143
- package/scripts/gateway.mjs +0 -81
- package/scripts/git-hooks/pre-commit +0 -41
- package/scripts/git-hooks/pre-push +0 -34
- package/scripts/status.mjs +0 -20
- package/scripts/statusline.mjs +0 -45
- package/scripts/transcript-models.sh +0 -4
- package/skills/high/SKILL.md +0 -9
- package/skills/low/SKILL.md +0 -7
- package/skills/medium/SKILL.md +0 -8
- package/skills/micro/SKILL.md +0 -7
- package/skills/setup/SKILL.md +0 -31
- package/skills/status/SKILL.md +0 -12
package/lib/config.mjs
CHANGED
|
@@ -2,36 +2,22 @@
|
|
|
2
2
|
|
|
3
3
|
export const TIERS = ['micro', 'low', 'medium', 'high'];
|
|
4
4
|
export const EFFORTS = ['low', 'medium', 'high', 'xhigh', 'max'];
|
|
5
|
-
// Request features that Claude Code uses with its own models and that only some models accept (a beta each):
|
|
6
|
-
// `system` messages after the prompt, per-turn control, and tool additions or removals in the history.
|
|
7
|
-
export const FEATURES = ['mid-conversation-system', 'per-turn-control', 'mid-conversation-tool-changes'];
|
|
8
|
-
|
|
9
|
-
// The alias before 0.4.2. Settings written by an older /router:setup still send it; drop it once they are rare.
|
|
10
|
-
export const LEGACY_ALIAS = 'router';
|
|
11
|
-
|
|
12
5
|
export const DEFAULTS = {
|
|
13
|
-
|
|
14
|
-
// the hooks start it again before the next prompt. Two hours outlast /loop wakeups and Monitor waits (up to one
|
|
15
|
-
// hour), which reach the gateway without a prompt. 0 keeps it running.
|
|
16
|
-
gateway: { port: 43170, alias: 'jev-router', baselineTier: 'low', auxiliaryTier: 'low', idleShutdownMs: 7_200_000 },
|
|
6
|
+
baselineTier: 'low',
|
|
17
7
|
// Sonnet 5.5 is the worker: `low` at the effort the user picked, `medium` at xhigh, so an escalation from `low`
|
|
18
8
|
// stays on Sonnet's cache instead of a cold write to Opus. `high` is Opus 5.5 at xhigh, the strongest setting this
|
|
19
|
-
// router asks for
|
|
20
|
-
// against Opus at high; the `observed` lines in decisions.jsonl are the input for that.
|
|
9
|
+
// router asks for. These are routing defaults, not a claim of equal model quality.
|
|
21
10
|
routes: {
|
|
22
11
|
high: { model: 'opus', effort: 'xhigh' },
|
|
23
12
|
medium: { model: 'sonnet', effort: 'xhigh' },
|
|
24
13
|
low: { model: 'sonnet' },
|
|
25
14
|
micro: { model: 'haiku' },
|
|
26
15
|
},
|
|
27
|
-
// `id`
|
|
16
|
+
// `id` selects the native model. List prices in USD per million tokens; `cacheRead` is absolute,
|
|
28
17
|
// not a multiplier (Opus 5.5 reads at 0.05x input, the rest at the standard 0.1x). A price change must also change
|
|
29
18
|
// test/fixtures/list-prices.json, with its source and date. `output` feeds the shadow estimate and the downgrade tax.
|
|
30
19
|
// `efforts` lists what the model accepts; an empty list means no effort field and no adaptive thinking. A change
|
|
31
20
|
// must also change test/fixtures/effort-support.json, from a new probe against the real API.
|
|
32
|
-
// `features` lists the FEATURES the model accepts; the gateway removes the others from the request. A model
|
|
33
|
-
// without the field gets none: a removed feature is lost, a feature the model rejects fails the turn. A change
|
|
34
|
-
// must also change test/fixtures/model-features.json, from a new probe.
|
|
35
21
|
models: {
|
|
36
22
|
opus: {
|
|
37
23
|
id: 'claude-opus-5-5',
|
|
@@ -41,7 +27,6 @@ export const DEFAULTS = {
|
|
|
41
27
|
contextWindow: 1_000_000,
|
|
42
28
|
billing: 'plan',
|
|
43
29
|
efforts: EFFORTS,
|
|
44
|
-
features: FEATURES,
|
|
45
30
|
},
|
|
46
31
|
sonnet: {
|
|
47
32
|
id: 'claude-sonnet-5-5',
|
|
@@ -51,19 +36,15 @@ export const DEFAULTS = {
|
|
|
51
36
|
contextWindow: 1_000_000,
|
|
52
37
|
billing: 'plan',
|
|
53
38
|
efforts: EFFORTS,
|
|
54
|
-
features: FEATURES,
|
|
55
39
|
},
|
|
56
|
-
// `maxOutput` caps `max_tokens`: Claude Code asks for 128K, Haiku 4.5 answers more than 64K with 400.
|
|
57
40
|
haiku: {
|
|
58
41
|
id: 'claude-haiku-4-5',
|
|
59
42
|
input: 1,
|
|
60
43
|
output: 5,
|
|
61
44
|
cacheRead: 0.1,
|
|
62
45
|
contextWindow: 200_000,
|
|
63
|
-
maxOutput: 64_000,
|
|
64
46
|
billing: 'plan',
|
|
65
47
|
efforts: [],
|
|
66
|
-
features: [],
|
|
67
48
|
},
|
|
68
49
|
},
|
|
69
50
|
cache: {
|
|
@@ -90,37 +71,22 @@ export const DEFAULTS = {
|
|
|
90
71
|
},
|
|
91
72
|
jev: { endpoint: 'https://api.typesafe.ai/v1/systemone', model: 'jev-1.13.0', timeoutMs: 1500 },
|
|
92
73
|
context: { recentTurns: 6, maxTextChars: 1200 },
|
|
93
|
-
log: true,
|
|
94
74
|
};
|
|
95
75
|
|
|
96
76
|
const API_KEY_VAR = 'TYPESAFE_API_KEY';
|
|
97
77
|
|
|
98
78
|
// Keys a route or a model entry may carry. The other closed sections take their key sets from DEFAULTS.
|
|
99
79
|
const ROUTE_KEYS = ['model', 'effort'];
|
|
100
|
-
const MODEL_KEYS = [
|
|
101
|
-
'id',
|
|
102
|
-
'input',
|
|
103
|
-
'output',
|
|
104
|
-
'cacheRead',
|
|
105
|
-
'contextWindow',
|
|
106
|
-
'maxOutput',
|
|
107
|
-
'billing',
|
|
108
|
-
'efforts',
|
|
109
|
-
'features',
|
|
110
|
-
];
|
|
80
|
+
const MODEL_KEYS = ['id', 'input', 'output', 'cacheRead', 'contextWindow', 'billing', 'efforts'];
|
|
111
81
|
// A JSON file can hold these as own keys; merged into a plain object they reach the prototype chain.
|
|
112
82
|
const FORBIDDEN_KEYS = new Set(['__proto__', 'constructor', 'prototype']);
|
|
113
83
|
|
|
114
|
-
|
|
115
|
-
// settings can set a hook's env, and a forced tier changes spend.
|
|
116
|
-
export function loadConfig({ env = {}, userFile = null, forcedTier = null } = {}) {
|
|
84
|
+
export function loadConfig({ env = {}, userFile = null } = {}) {
|
|
117
85
|
if (userFile !== null) checkShape(userFile);
|
|
118
86
|
const config = merge(DEFAULTS, userFile ?? {});
|
|
119
87
|
validate(config);
|
|
120
88
|
const apiKey = env[API_KEY_VAR]?.trim() || null;
|
|
121
|
-
|
|
122
|
-
throw new Error(`the forced tier must be one of ${TIERS.join(', ')}`);
|
|
123
|
-
return { ...config, apiKey, forcedTier };
|
|
89
|
+
return { ...config, apiKey };
|
|
124
90
|
}
|
|
125
91
|
|
|
126
92
|
export function rank(tier) {
|
|
@@ -142,9 +108,20 @@ function merge(base, override) {
|
|
|
142
108
|
// The raw file, before the merge: only known keys, and every section an object. Messages name the path, never the
|
|
143
109
|
// value. An open map (model aliases, cache TTL labels) takes any key but the forbidden ones.
|
|
144
110
|
function checkShape(file) {
|
|
111
|
+
if (
|
|
112
|
+
file &&
|
|
113
|
+
typeof file === 'object' &&
|
|
114
|
+
(Object.hasOwn(file, 'gateway') ||
|
|
115
|
+
Object.hasOwn(file, 'log') ||
|
|
116
|
+
Object.values(file.models ?? {}).some(
|
|
117
|
+
(model) => model && (Object.hasOwn(model, 'features') || Object.hasOwn(model, 'maxOutput')),
|
|
118
|
+
))
|
|
119
|
+
)
|
|
120
|
+
throw new Error(
|
|
121
|
+
'router.json uses gateway settings; run node scripts/migrate-config.mjs /path/to/router.json from the router plugin directory',
|
|
122
|
+
);
|
|
145
123
|
checkObject(file, 'router.json', Object.keys(DEFAULTS));
|
|
146
|
-
const {
|
|
147
|
-
if (gateway !== undefined) checkObject(gateway, 'gateway', Object.keys(DEFAULTS.gateway));
|
|
124
|
+
const { routes, models, cache, policy, jev, context } = file;
|
|
148
125
|
if (routes !== undefined) {
|
|
149
126
|
checkObject(routes, 'routes', TIERS);
|
|
150
127
|
for (const [tier, route] of Object.entries(routes)) checkObject(route, `routes.${tier}`, ROUTE_KEYS);
|
|
@@ -192,26 +169,12 @@ function validate(config) {
|
|
|
192
169
|
if (model.output !== undefined && !(Number.isFinite(model.output) && model.output >= 0))
|
|
193
170
|
throw new Error(`models.${alias}.output must be a non-negative number`);
|
|
194
171
|
if (typeof model.id !== 'string' || !model.id) throw new Error(`models.${alias}.id is required`);
|
|
195
|
-
if (model.maxOutput !== undefined && !(Number.isInteger(model.maxOutput) && model.maxOutput > 0))
|
|
196
|
-
throw new Error(`models.${alias}.maxOutput must be a positive integer`);
|
|
197
172
|
if (!['plan', 'credits'].includes(model.billing))
|
|
198
173
|
throw new Error(`models.${alias}.billing must be plan or credits`);
|
|
199
174
|
if (!Array.isArray(model.efforts) || model.efforts.some((e) => !EFFORTS.includes(e)))
|
|
200
175
|
throw new Error(`models.${alias}.efforts must list valid effort levels`);
|
|
201
|
-
if (
|
|
202
|
-
model.features !== undefined &&
|
|
203
|
-
!(Array.isArray(model.features) && model.features.every((f) => FEATURES.includes(f)))
|
|
204
|
-
)
|
|
205
|
-
throw new Error(`models.${alias}.features must list known features (${FEATURES.join(', ')})`);
|
|
206
|
-
}
|
|
207
|
-
for (const key of ['baselineTier', 'auxiliaryTier']) {
|
|
208
|
-
if (!TIERS.includes(config.gateway[key])) throw new Error(`gateway.${key} must be one of ${TIERS.join(', ')}`);
|
|
209
176
|
}
|
|
210
|
-
if (!
|
|
211
|
-
throw new Error('gateway.port must be a port number');
|
|
212
|
-
if (typeof config.gateway.alias !== 'string' || !config.gateway.alias) throw new Error('gateway.alias is required');
|
|
213
|
-
if (!(Number.isFinite(config.gateway.idleShutdownMs) && config.gateway.idleShutdownMs >= 0))
|
|
214
|
-
throw new Error('gateway.idleShutdownMs must be a non-negative number (0 keeps the gateway running)');
|
|
177
|
+
if (!TIERS.includes(config.baselineTier)) throw new Error(`baselineTier must be one of ${TIERS.join(', ')}`);
|
|
215
178
|
const p = config.policy;
|
|
216
179
|
for (const field of ['upgradeBase', 'jumpConfidence', 'downgradeMass', 'continuationMass']) {
|
|
217
180
|
if (!(isNumber(p[field], 0) && p[field] <= 1)) throw new Error(`policy.${field} must be between 0 and 1`);
|
|
@@ -238,5 +201,4 @@ function validate(config) {
|
|
|
238
201
|
for (const field of ['recentTurns', 'maxTextChars']) {
|
|
239
202
|
if (!isNumber(context[field], 1, { integer: true })) throw new Error(`context.${field} must be a positive integer`);
|
|
240
203
|
}
|
|
241
|
-
if (typeof config.log !== 'boolean') throw new Error('log must be true or false');
|
|
242
204
|
}
|
|
@@ -1,16 +1,12 @@
|
|
|
1
1
|
// Facts the policy needs, derived from one Messages request body plus what the router remembers
|
|
2
2
|
// about the conversation. Pure: body and memory in, plain object out.
|
|
3
|
-
import { createHash } from 'node:crypto';
|
|
4
3
|
|
|
5
4
|
const EDIT_TOOLS = new Set(['Edit', 'Write', 'MultiEdit', 'NotebookEdit', 'Bash']);
|
|
6
5
|
const FAILURE_WINDOW = 40;
|
|
7
6
|
const REMINDER = /<system-reminder>[\s\S]*?<\/system-reminder>/g;
|
|
8
7
|
const CLIP_MARKER = ' […] ';
|
|
9
|
-
// A typed /router:<tier> reaches the gateway as a command block at the start of a text block. Anchored, so a pasted
|
|
10
|
-
// file or quoted log that mentions the marker cannot pin a tier.
|
|
11
|
-
const PIN = /^<command-message>router:([a-z]+)<\/command-message>/;
|
|
12
8
|
|
|
13
|
-
export function
|
|
9
|
+
export function extractFacts(body, memory, { recentTurns, maxTextChars }) {
|
|
14
10
|
const messages = Array.isArray(body.messages) ? body.messages : [];
|
|
15
11
|
// Claude Code puts hook output and tool additions in `system` messages after the user message, and keeps them in
|
|
16
12
|
// the history: the turn is the last user or assistant message.
|
|
@@ -38,11 +34,6 @@ export function factsFromRequest(body, memory, { recentTurns, maxTextChars }) {
|
|
|
38
34
|
turns: turns.slice(-recentTurns),
|
|
39
35
|
prompt: current === -1 ? '' : clip(textOf(lastBlocks), maxTextChars),
|
|
40
36
|
continuation: last?.role === 'user' && lastBlocks.some((b) => b.type === 'tool_result'),
|
|
41
|
-
// The tier named by a /router:<tier> in the current message; the router checks that it is a tier.
|
|
42
|
-
pin: current === -1 ? null : pinOf(lastBlocks),
|
|
43
|
-
// The same position and the same last user message: Claude Code resent the request (429, 529, a dropped stream, or
|
|
44
|
-
// a 400 it answers by dropping a feature from the system message after it).
|
|
45
|
-
turnKey: last?.role === 'user' ? `${lastIndex + 1}:${hash(JSON.stringify(last.content))}` : null,
|
|
46
37
|
failure: repeatedFailure(errors, edits, messages.length - 1),
|
|
47
38
|
// The effort Claude Code sent: a route without its own effort keeps it, and it is part of the cache key.
|
|
48
39
|
effort: body.output_config?.effort ?? null,
|
|
@@ -66,7 +57,7 @@ function repeatedFailure(errors, edits, lastIndex) {
|
|
|
66
57
|
}
|
|
67
58
|
|
|
68
59
|
// At most `max` characters: the head and the tail of a long text, where a request and its question usually are.
|
|
69
|
-
function clip(text, max) {
|
|
60
|
+
export function clip(text, max) {
|
|
70
61
|
if (text.length <= max) return text;
|
|
71
62
|
if (max <= CLIP_MARKER.length) return text.slice(0, max);
|
|
72
63
|
const room = max - CLIP_MARKER.length;
|
|
@@ -78,10 +69,6 @@ function signatureOf(block) {
|
|
|
78
69
|
return textOf(blocks(block.content)).toLowerCase().replace(/\d+/g, '#').replace(/\s+/g, ' ').slice(0, 120);
|
|
79
70
|
}
|
|
80
71
|
|
|
81
|
-
function hash(text) {
|
|
82
|
-
return createHash('sha256').update(text).digest('hex').slice(0, 16);
|
|
83
|
-
}
|
|
84
|
-
|
|
85
72
|
function blocks(content) {
|
|
86
73
|
if (typeof content === 'string') return [{ type: 'text', text: content }];
|
|
87
74
|
return Array.isArray(content) ? content : [];
|
|
@@ -94,11 +81,3 @@ function textOf(content) {
|
|
|
94
81
|
.join('\n')
|
|
95
82
|
.trim();
|
|
96
83
|
}
|
|
97
|
-
|
|
98
|
-
function pinOf(content) {
|
|
99
|
-
for (const block of content) {
|
|
100
|
-
const match = block.type === 'text' && typeof block.text === 'string' ? PIN.exec(block.text) : null;
|
|
101
|
-
if (match) return match[1];
|
|
102
|
-
}
|
|
103
|
-
return null;
|
|
104
|
-
}
|
|
@@ -1,4 +1,4 @@
|
|
|
1
|
-
//
|
|
1
|
+
// Pure Jev wire contract: request body, answer parser and retry rules.
|
|
2
2
|
import { TIERS } from './config.mjs';
|
|
3
3
|
|
|
4
4
|
const CRITERIA = {
|
|
@@ -33,9 +33,14 @@ const ROUTE_INSTRUCTIONS = {
|
|
|
33
33
|
};
|
|
34
34
|
const CONTINUATION_INSTRUCTIONS =
|
|
35
35
|
'Is `currentRequest.text` a continuation of the task in `recentDialogue` (for example "continue", "yes", "now fix the tests"), rather than a new task?';
|
|
36
|
+
export const RETRY_DELAY_MS = 100;
|
|
37
|
+
export const JEV_FAILURES_TO_PAUSE = 3;
|
|
38
|
+
export const JEV_PAUSE_MS = 60_000;
|
|
36
39
|
const TRANSIENT = new Set([408, 429, 500, 502, 503, 504]);
|
|
37
|
-
|
|
38
|
-
|
|
40
|
+
|
|
41
|
+
export function isTransientStatus(status) {
|
|
42
|
+
return TRANSIENT.has(status);
|
|
43
|
+
}
|
|
39
44
|
|
|
40
45
|
export function buildRequest(config, prompt, turns) {
|
|
41
46
|
const criteria = {};
|
|
@@ -51,40 +56,8 @@ export function buildRequest(config, prompt, turns) {
|
|
|
51
56
|
};
|
|
52
57
|
}
|
|
53
58
|
|
|
54
|
-
// Returns { choice, confidence, probabilities, continuation } or throws. One retry on a network error or a transient
|
|
55
|
-
// status, after Retry-After when the server sends one; a wait that would not fit the budget is not taken.
|
|
56
|
-
export async function askJev({ fetchFn, config, apiKey, prompt, turns, now = Date.now, sleep = delay }) {
|
|
57
|
-
const deadline = now() + config.jev.timeoutMs;
|
|
58
|
-
const body = JSON.stringify(buildRequest(config, prompt, turns));
|
|
59
|
-
for (let attempt = 0; attempt < 2; attempt += 1) {
|
|
60
|
-
const remaining = deadline - now();
|
|
61
|
-
if (remaining <= 0) throw new Error('jev timeout');
|
|
62
|
-
let response;
|
|
63
|
-
try {
|
|
64
|
-
response = await fetchFn(config.jev.endpoint, {
|
|
65
|
-
method: 'POST',
|
|
66
|
-
headers: { Authorization: `Bearer ${apiKey}`, 'content-type': 'application/json' },
|
|
67
|
-
body,
|
|
68
|
-
signal: AbortSignal.timeout(remaining),
|
|
69
|
-
});
|
|
70
|
-
} catch (error) {
|
|
71
|
-
if (error.name === 'TimeoutError') throw new Error('jev timeout');
|
|
72
|
-
if (attempt === 1) throw new Error(`jev unreachable: ${error.message}`);
|
|
73
|
-
await sleep(RETRY_DELAY_MS);
|
|
74
|
-
continue;
|
|
75
|
-
}
|
|
76
|
-
if (response.ok) return parseAnswers(await response.json());
|
|
77
|
-
if (!TRANSIENT.has(response.status) || attempt === 1) throw new Error(`jev http ${response.status}`);
|
|
78
|
-
const wait = retryAfterMs(response.headers, now()) ?? RETRY_DELAY_MS;
|
|
79
|
-
if (wait >= deadline - now()) throw new Error(`jev http ${response.status}, retry-after beyond the budget`);
|
|
80
|
-
await sleep(wait);
|
|
81
|
-
}
|
|
82
|
-
throw new Error('jev unreachable');
|
|
83
|
-
}
|
|
84
|
-
|
|
85
59
|
// Delay-seconds or an HTTP-date (RFC 9110). Seconds first: Date.parse also reads a bare number, as a year.
|
|
86
|
-
function
|
|
87
|
-
const value = headers?.get?.('retry-after');
|
|
60
|
+
export function retryDelayMs(value, now) {
|
|
88
61
|
if (value === null || value === undefined || value.trim() === '') return null;
|
|
89
62
|
const seconds = Number(value);
|
|
90
63
|
if (Number.isFinite(seconds)) return seconds >= 0 ? seconds * 1000 : null;
|
|
@@ -94,9 +67,15 @@ function retryAfterMs(headers, now) {
|
|
|
94
67
|
|
|
95
68
|
export function parseAnswers(json) {
|
|
96
69
|
const route = json?.answers?.route;
|
|
97
|
-
if (
|
|
70
|
+
if (
|
|
71
|
+
route?.type !== 'choice' ||
|
|
72
|
+
!route.probabilities ||
|
|
73
|
+
typeof route.probabilities !== 'object' ||
|
|
74
|
+
Array.isArray(route.probabilities)
|
|
75
|
+
)
|
|
76
|
+
throw new Error('jev malformed answer');
|
|
98
77
|
const allowed = new Set([...TIERS, 'uncertain']);
|
|
99
|
-
if (!allowed.has(route.choice)) throw new Error(
|
|
78
|
+
if (!allowed.has(route.choice)) throw new Error('jev unknown choice');
|
|
100
79
|
const probabilities = {};
|
|
101
80
|
for (const key of allowed) probabilities[key] = clamp(route.probabilities[key]);
|
|
102
81
|
const continuation = json.answers.continuation?.type === 'noul' ? clamp(json.answers.continuation.noul) : null;
|
|
@@ -0,0 +1,88 @@
|
|
|
1
|
+
import { EFFORTS } from './config.mjs';
|
|
2
|
+
|
|
3
|
+
export function cacheKey(modelId, effort) {
|
|
4
|
+
return effort ? `${modelId}@${effort}` : modelId;
|
|
5
|
+
}
|
|
6
|
+
|
|
7
|
+
export function clampEffort(wanted, supported) {
|
|
8
|
+
if (!wanted || supported.length === 0) return null;
|
|
9
|
+
if (supported.includes(wanted)) return wanted;
|
|
10
|
+
for (let i = EFFORTS.indexOf(wanted); i >= 0; i -= 1) if (supported.includes(EFFORTS[i])) return EFFORTS[i];
|
|
11
|
+
return supported[0];
|
|
12
|
+
}
|
|
13
|
+
|
|
14
|
+
export function nextContextTokens(facts) {
|
|
15
|
+
const previous = facts.lastRequest ? facts.lastRequest.tokens + facts.lastRequest.outputTokens : 0;
|
|
16
|
+
return Math.max(previous, Number.isFinite(facts.contextTokens) ? facts.contextTokens : 0);
|
|
17
|
+
}
|
|
18
|
+
|
|
19
|
+
export function routeEffort(config, tier, sentEffort) {
|
|
20
|
+
const route = config.routes[tier];
|
|
21
|
+
const model = config.models[route.model];
|
|
22
|
+
if (model.efforts.length === 0) return null;
|
|
23
|
+
if (route.effort) return clampEffort(route.effort, model.efforts);
|
|
24
|
+
if (typeof sentEffort === 'number' && Number.isFinite(sentEffort)) return sentEffort;
|
|
25
|
+
return clampEffort(sentEffort, model.efforts);
|
|
26
|
+
}
|
|
27
|
+
|
|
28
|
+
export function routeCacheKey(config, tier, sentEffort) {
|
|
29
|
+
return cacheKey(config.models[config.routes[tier].model].id, routeEffort(config, tier, sentEffort));
|
|
30
|
+
}
|
|
31
|
+
|
|
32
|
+
export function isWarm(state, now, cache) {
|
|
33
|
+
return Boolean(
|
|
34
|
+
state?.prefixTokens > 0 && now >= state.lastAt && now < state.lastAt + cache.ttlMs['5m'] - cache.warmMarginMs,
|
|
35
|
+
);
|
|
36
|
+
}
|
|
37
|
+
|
|
38
|
+
export function cacheState(state, now, cache) {
|
|
39
|
+
return isWarm(state, now, cache) ? 'fresh' : 'unknown';
|
|
40
|
+
}
|
|
41
|
+
|
|
42
|
+
// Bounds are scenarios, never an independent ledger. Unknown incumbent cache can still be served.
|
|
43
|
+
export function inputBounds(config, tier, tokens, facts, now) {
|
|
44
|
+
const model = config.models[config.routes[tier].model];
|
|
45
|
+
const state = facts.models[routeCacheKey(config, tier, facts.effort)];
|
|
46
|
+
const prefix = Math.min(state?.prefixTokens ?? tokens, tokens);
|
|
47
|
+
const fresh = isWarm(state, now, config.cache);
|
|
48
|
+
const maximumWrite = model.input * Math.max(...Object.values(config.cache.writeMultiplier));
|
|
49
|
+
return {
|
|
50
|
+
min: (model.cacheRead * prefix + model.input * (tokens - prefix)) / 1e6,
|
|
51
|
+
max: fresh ? (model.cacheRead * prefix + maximumWrite * (tokens - prefix)) / 1e6 : (maximumWrite * tokens) / 1e6,
|
|
52
|
+
};
|
|
53
|
+
}
|
|
54
|
+
|
|
55
|
+
export function coldWriteUsd(config, alias, tokens) {
|
|
56
|
+
return (config.models[alias].input * Math.max(...Object.values(config.cache.writeMultiplier)) * tokens) / 1e6;
|
|
57
|
+
}
|
|
58
|
+
|
|
59
|
+
export function switchingTaxUsd(config, candidate, incumbent, facts, now) {
|
|
60
|
+
const tokens = nextContextTokens(facts);
|
|
61
|
+
return (
|
|
62
|
+
inputBounds(config, candidate, tokens, facts, now).max - inputBounds(config, incumbent, tokens, facts, now).min
|
|
63
|
+
);
|
|
64
|
+
}
|
|
65
|
+
|
|
66
|
+
export function shadowEconomics(config, candidate, incumbent, facts, now) {
|
|
67
|
+
const proposed = config.models[config.routes[candidate].model];
|
|
68
|
+
const current = config.models[config.routes[incumbent].model];
|
|
69
|
+
if (!(proposed.output > 0) || !(current.output > 0)) return null;
|
|
70
|
+
const tokens = nextContextTokens(facts);
|
|
71
|
+
const outputTokens = facts.lastRequest?.outputTokens ?? 0;
|
|
72
|
+
const output = ((proposed.output - current.output) * outputTokens) / 1e6;
|
|
73
|
+
const nextTurnUsd = switchingTaxUsd(config, candidate, incumbent, facts, now) + output;
|
|
74
|
+
const laterTurnUsd = ((proposed.cacheRead - current.cacheRead) * tokens) / 1e6 + output;
|
|
75
|
+
const paybackTurns =
|
|
76
|
+
nextTurnUsd <= 0 && laterTurnUsd <= 0
|
|
77
|
+
? 0
|
|
78
|
+
: nextTurnUsd > 0 && laterTurnUsd < 0
|
|
79
|
+
? Math.ceil(nextTurnUsd / -laterTurnUsd)
|
|
80
|
+
: null;
|
|
81
|
+
return { nextTurnUsd, laterTurnUsd, paybackTurns, outputTokens };
|
|
82
|
+
}
|
|
83
|
+
|
|
84
|
+
export function downgradeTaxUsd(config, candidate, incumbent, facts, now, turns) {
|
|
85
|
+
const estimate = shadowEconomics(config, candidate, incumbent, facts, now);
|
|
86
|
+
if (!estimate) return Math.max(0, switchingTaxUsd(config, candidate, incumbent, facts, now));
|
|
87
|
+
return Math.max(0, estimate.nextTurnUsd + (turns - 1) * estimate.laterTurnUsd);
|
|
88
|
+
}
|
|
@@ -0,0 +1,75 @@
|
|
|
1
|
+
import { tierForModel } from './native-router.mjs';
|
|
2
|
+
|
|
3
|
+
export const REASONS = {
|
|
4
|
+
ready: 'ready for the next turn',
|
|
5
|
+
'same-tier': 'the task fits the current tier',
|
|
6
|
+
'no-advice': 'keeping the current model without Jev advice',
|
|
7
|
+
continuation: 'continuing the previous task',
|
|
8
|
+
uncertain: 'Jev could not justify a change',
|
|
9
|
+
upgrade: 'enough support for a stronger model',
|
|
10
|
+
jump: 'clear need for a stronger model',
|
|
11
|
+
downgrade: 'enough support for a cheaper model',
|
|
12
|
+
'upgrade-pending': 'waiting before upgrading',
|
|
13
|
+
'downgrade-pending': 'switching is not justified yet',
|
|
14
|
+
hold: 'staying after an escalation',
|
|
15
|
+
escalation: 'repeated tool failures need a stronger model',
|
|
16
|
+
'cash-gate': 'estimated cold cache write exceeds the cap',
|
|
17
|
+
'context-fit': 'a larger context window is needed',
|
|
18
|
+
'context-unknown': 'context is not measured reliably',
|
|
19
|
+
'model-unavailable': 'the requested model is not available',
|
|
20
|
+
pinned: 'one-turn model pin',
|
|
21
|
+
};
|
|
22
|
+
|
|
23
|
+
export function formatTokens(value) {
|
|
24
|
+
if (!Number.isFinite(value)) return 'unknown';
|
|
25
|
+
if (value >= 1_000_000) return `${(value / 1_000_000).toFixed(2)}M`;
|
|
26
|
+
if (value >= 1000) return `${(value / 1000).toFixed(1)}K`;
|
|
27
|
+
return String(Math.round(value));
|
|
28
|
+
}
|
|
29
|
+
|
|
30
|
+
export function bar(value, maximum, width = 16) {
|
|
31
|
+
if (!Number.isFinite(value) || !(maximum > 0)) return { text: 'unknown', percent: null, color: 'gray' };
|
|
32
|
+
const fraction = Math.max(0, value / maximum);
|
|
33
|
+
const filled = Math.min(width, Math.round(fraction * width));
|
|
34
|
+
return {
|
|
35
|
+
text: `${'█'.repeat(filled)}${'░'.repeat(width - filled)}`,
|
|
36
|
+
percent: Math.round(fraction * 100),
|
|
37
|
+
color: fraction > 0.8 ? 'red' : fraction > 0.6 ? 'yellow' : 'green',
|
|
38
|
+
};
|
|
39
|
+
}
|
|
40
|
+
|
|
41
|
+
export function usageMetrics(config, view, usage) {
|
|
42
|
+
const model = view.actualModel ?? view.selectedModel ?? view.nativeModel;
|
|
43
|
+
const tier = tierForModel(config, model);
|
|
44
|
+
const spec = tier ? config.models[config.routes[tier].model] : null;
|
|
45
|
+
const window = spec?.contextWindow ?? null;
|
|
46
|
+
const observed = Number.isFinite(usage?.context?.tokens) ? usage.context.tokens : null;
|
|
47
|
+
const candidates = [view.contextTokens, observed === null ? null : observed + (view.outputTokens ?? 0)].filter(
|
|
48
|
+
(value) => Number.isFinite(value),
|
|
49
|
+
);
|
|
50
|
+
const nextContext = candidates.length ? Math.max(...candidates) : null;
|
|
51
|
+
const reuse = view.inputTokens > 0 && Number.isFinite(view.cacheRead) ? view.cacheRead / view.inputTokens : null;
|
|
52
|
+
const cost = Number.isFinite(usage?.cost?.usd) ? usage.cost.usd : null;
|
|
53
|
+
const cacheBenefit =
|
|
54
|
+
spec && Number.isFinite(view.cacheRead) ? ((spec.input - spec.cacheRead) * view.cacheRead) / 1e6 : null;
|
|
55
|
+
return {
|
|
56
|
+
window,
|
|
57
|
+
observed,
|
|
58
|
+
nextContext,
|
|
59
|
+
reuse,
|
|
60
|
+
cost,
|
|
61
|
+
cacheBenefit,
|
|
62
|
+
contextBar: bar(nextContext, window),
|
|
63
|
+
cacheBar: {
|
|
64
|
+
...bar(reuse, 1),
|
|
65
|
+
color: reuse === null ? 'gray' : reuse >= 0.6 ? 'green' : reuse >= 0.2 ? 'yellow' : 'gray',
|
|
66
|
+
},
|
|
67
|
+
};
|
|
68
|
+
}
|
|
69
|
+
|
|
70
|
+
export function sparkline(values) {
|
|
71
|
+
if (!values.length || !values.every(Number.isFinite)) return 'no history yet';
|
|
72
|
+
const symbols = '▁▂▃▄▅▆▇█';
|
|
73
|
+
const maximum = Math.max(...values);
|
|
74
|
+
return values.map((value) => symbols[maximum > 0 ? Math.round((value / maximum) * 7) : 0]).join('');
|
|
75
|
+
}
|
|
@@ -0,0 +1,125 @@
|
|
|
1
|
+
import {
|
|
2
|
+
buildRequest,
|
|
3
|
+
isTransientStatus,
|
|
4
|
+
JEV_FAILURES_TO_PAUSE,
|
|
5
|
+
JEV_PAUSE_MS,
|
|
6
|
+
parseAnswers,
|
|
7
|
+
RETRY_DELAY_MS,
|
|
8
|
+
retryDelayMs,
|
|
9
|
+
} from './jev-contract.mjs';
|
|
10
|
+
|
|
11
|
+
class AdviceError extends Error {
|
|
12
|
+
constructor(code) {
|
|
13
|
+
super(code);
|
|
14
|
+
this.code = code;
|
|
15
|
+
}
|
|
16
|
+
}
|
|
17
|
+
|
|
18
|
+
// Owned by one Mod activation. It survives history resets; the host cancels its work on unload.
|
|
19
|
+
export class NativeJev {
|
|
20
|
+
constructor({ now = Date.now, health = null } = {}) {
|
|
21
|
+
this.now = now;
|
|
22
|
+
this.pending = null;
|
|
23
|
+
this.active = false;
|
|
24
|
+
this.restore(health);
|
|
25
|
+
}
|
|
26
|
+
|
|
27
|
+
restore(health) {
|
|
28
|
+
this.failures =
|
|
29
|
+
Number.isInteger(health?.failures) && health.failures >= 0 ? Math.min(health.failures, JEV_FAILURES_TO_PAUSE) : 0;
|
|
30
|
+
this.pausedUntil = Number.isFinite(health?.pausedUntil) ? health.pausedUntil : 0;
|
|
31
|
+
}
|
|
32
|
+
|
|
33
|
+
snapshot() {
|
|
34
|
+
return { failures: this.failures, pausedUntil: this.pausedUntil };
|
|
35
|
+
}
|
|
36
|
+
|
|
37
|
+
async ask({ request, sleep, config, apiKey, prompt, turns, signal }) {
|
|
38
|
+
if (!apiKey) return { advice: null, error: 'missing-key' };
|
|
39
|
+
if (signal?.aborted) return { advice: null, error: 'cancelled' };
|
|
40
|
+
if (this.now() < this.pausedUntil) return { advice: null, error: 'paused' };
|
|
41
|
+
if (this.active || this.pending) return { advice: null, error: 'busy' };
|
|
42
|
+
this.active = true;
|
|
43
|
+
try {
|
|
44
|
+
const advice = await this.complete({ request, sleep, config, apiKey, prompt, turns, signal });
|
|
45
|
+
this.failures = 0;
|
|
46
|
+
this.pausedUntil = 0;
|
|
47
|
+
return { advice, error: null };
|
|
48
|
+
} catch (error) {
|
|
49
|
+
const code = signal?.aborted ? 'cancelled' : error instanceof AdviceError ? error.code : 'unreachable';
|
|
50
|
+
if (code !== 'cancelled' && code !== 'policy') {
|
|
51
|
+
this.failures = Math.min(this.failures + 1, JEV_FAILURES_TO_PAUSE);
|
|
52
|
+
if (this.failures >= JEV_FAILURES_TO_PAUSE) this.pausedUntil = this.now() + JEV_PAUSE_MS;
|
|
53
|
+
}
|
|
54
|
+
return { advice: null, error: code };
|
|
55
|
+
} finally {
|
|
56
|
+
this.active = false;
|
|
57
|
+
}
|
|
58
|
+
}
|
|
59
|
+
|
|
60
|
+
async complete({ request, sleep, config, apiKey, prompt, turns, signal }) {
|
|
61
|
+
const deadline = this.now() + config.jev.timeoutMs;
|
|
62
|
+
const body = JSON.stringify(buildRequest(config, prompt, turns));
|
|
63
|
+
for (let attempt = 0; attempt < 2; attempt += 1) {
|
|
64
|
+
const remaining = deadline - this.now();
|
|
65
|
+
if (signal?.aborted) throw new AdviceError('cancelled');
|
|
66
|
+
if (remaining <= 0) throw new AdviceError('timeout');
|
|
67
|
+
const call = Promise.resolve().then(() =>
|
|
68
|
+
request(config.jev.endpoint, {
|
|
69
|
+
method: 'POST',
|
|
70
|
+
headers: { authorization: `Bearer ${apiKey}`, 'content-type': 'application/json' },
|
|
71
|
+
body,
|
|
72
|
+
}),
|
|
73
|
+
);
|
|
74
|
+
this.pending = call;
|
|
75
|
+
const release = () => {
|
|
76
|
+
if (this.pending === call) this.pending = null;
|
|
77
|
+
};
|
|
78
|
+
call.then(release, release);
|
|
79
|
+
const timer = new AbortController();
|
|
80
|
+
const cancel = () => timer.abort();
|
|
81
|
+
signal?.addEventListener('abort', cancel, { once: true });
|
|
82
|
+
let response;
|
|
83
|
+
try {
|
|
84
|
+
response = await Promise.race([
|
|
85
|
+
call,
|
|
86
|
+
sleep(remaining, { signal: timer.signal }).then(() => {
|
|
87
|
+
throw new AdviceError('timeout');
|
|
88
|
+
}),
|
|
89
|
+
]);
|
|
90
|
+
} catch (error) {
|
|
91
|
+
if (signal?.aborted) throw new AdviceError('cancelled');
|
|
92
|
+
if (error instanceof AdviceError) throw error;
|
|
93
|
+
if (/policy|denied|(?<!conn)refus|network access|nonessential/i.test(String(error?.message)))
|
|
94
|
+
throw new AdviceError('policy');
|
|
95
|
+
if (attempt === 1) throw new AdviceError('unreachable');
|
|
96
|
+
if (RETRY_DELAY_MS >= deadline - this.now()) throw new AdviceError('timeout');
|
|
97
|
+
await sleep(RETRY_DELAY_MS, { signal });
|
|
98
|
+
continue;
|
|
99
|
+
} finally {
|
|
100
|
+
signal?.removeEventListener('abort', cancel);
|
|
101
|
+
timer.abort();
|
|
102
|
+
}
|
|
103
|
+
if (signal?.aborted) throw new AdviceError('cancelled');
|
|
104
|
+
if (this.now() >= deadline) throw new AdviceError('timeout');
|
|
105
|
+
if (response.ok) {
|
|
106
|
+
try {
|
|
107
|
+
if (typeof response.text !== 'string' || response.text.length > 16_384) throw new AdviceError('malformed');
|
|
108
|
+
const advice = parseAnswers(JSON.parse(response.text));
|
|
109
|
+
if (this.now() >= deadline) throw new AdviceError('timeout');
|
|
110
|
+
return advice;
|
|
111
|
+
} catch (error) {
|
|
112
|
+
if (error instanceof AdviceError) throw error;
|
|
113
|
+
throw new AdviceError('malformed');
|
|
114
|
+
}
|
|
115
|
+
}
|
|
116
|
+
if (response.status === 401 || response.status === 403) throw new AdviceError('auth');
|
|
117
|
+
if (!isTransientStatus(response.status) || attempt === 1) throw new AdviceError('http');
|
|
118
|
+
const value = response.headers?.['retry-after'];
|
|
119
|
+
const wait = retryDelayMs(typeof value === 'string' ? value : null, this.now()) ?? RETRY_DELAY_MS;
|
|
120
|
+
if (wait >= deadline - this.now()) throw new AdviceError('timeout');
|
|
121
|
+
await sleep(wait, { signal });
|
|
122
|
+
}
|
|
123
|
+
throw new AdviceError('unreachable');
|
|
124
|
+
}
|
|
125
|
+
}
|