@alexeiled/claude-router 1.10.3 → 1.11.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/.claude-plugin/plugin.json +1 -1
- package/CHANGELOG.md +35 -0
- package/README.md +4 -3
- package/docs/activity-routing.md +13 -4
- package/docs/architecture.md +13 -9
- package/docs/configuration.md +9 -6
- package/docs/evaluation.md +1 -1
- package/docs/native-router.md +2 -2
- package/docs/router-pane-classifier.svg +49 -43
- package/docs/user-guide.md +57 -37
- package/hooks/native-router.mjs +129 -0
- package/lib/activity.mjs +14 -12
- package/lib/config.mjs +17 -0
- package/lib/display.mjs +3 -3
- package/lib/facts.mjs +82 -0
- package/lib/policy.mjs +38 -14
- package/lib/route.mjs +93 -7
- package/package.json +2 -2
package/lib/policy.mjs
CHANGED
|
@@ -2,6 +2,13 @@
|
|
|
2
2
|
import { rank, resolveRoute, routeSpec, TIERS } from './config.mjs';
|
|
3
3
|
import * as nativeCosts from './cost.mjs';
|
|
4
4
|
|
|
5
|
+
// Whether an answer is about the task already running: a review inside a turn (facts.midTurn), or a new prompt the
|
|
6
|
+
// classifier scores as a continuation. On the same task either way is open, but a cheaper route waits for
|
|
7
|
+
// facts.downAllowed: the dwell since the last model change and a passed verification.
|
|
8
|
+
export function sameTaskOf(config, advice, facts) {
|
|
9
|
+
return Boolean(facts.midTurn) || (advice?.continuation ?? 0) >= config.policy.continuationMass;
|
|
10
|
+
}
|
|
11
|
+
|
|
5
12
|
export function initialState() {
|
|
6
13
|
return { turn: 0, votes: [], holdUntilTurn: 0, escalatedSignature: null };
|
|
7
14
|
}
|
|
@@ -37,7 +44,6 @@ export function decide({
|
|
|
37
44
|
}
|
|
38
45
|
if (next.turn <= next.holdUntilTurn) return stay('hold');
|
|
39
46
|
if (!advice) return stay('no-advice');
|
|
40
|
-
if (advice.continuation >= config.policy.continuationMass) return stay('continuation');
|
|
41
47
|
if (advice.choice === 'uncertain') return stay('uncertain');
|
|
42
48
|
|
|
43
49
|
const choice = advice.choice;
|
|
@@ -68,19 +74,33 @@ export function decide({
|
|
|
68
74
|
return stay('upgrade-pending', estimate);
|
|
69
75
|
}
|
|
70
76
|
|
|
71
|
-
|
|
72
|
-
|
|
73
|
-
//
|
|
74
|
-
|
|
75
|
-
const
|
|
76
|
-
|
|
77
|
-
|
|
78
|
-
|
|
79
|
-
|
|
80
|
-
const
|
|
81
|
-
|
|
77
|
+
// The move lands on the cheapest tier the answer supports as a whole: from the choice up to just below the
|
|
78
|
+
// incumbent, the first tier whose mass at or below it clears its bar. A split answer (micro 0.8, low 0.16) on high
|
|
79
|
+
// moves to low instead of waiting for micro alone to reach the bar. A pending stay reports the choice's estimate.
|
|
80
|
+
let pending = null;
|
|
81
|
+
for (const target of TIERS.filter((t) => rank(t) >= rank(choice) && rank(t) < rank(incumbent))) {
|
|
82
|
+
const support = massAtOrBelow(advice.probabilities, target);
|
|
83
|
+
const streak = trailing(next.votes, (v) => rank(v.tier) <= rank(target));
|
|
84
|
+
// A downgrade is not always cheaper this turn: a cold candidate next to a warm incumbent can pay a bigger cache
|
|
85
|
+
// write than it saves. The bar rises with that cost, net of what the next turns save, the way the upgrade bar does.
|
|
86
|
+
const tax = costs.downgradeTaxUsd(
|
|
87
|
+
config,
|
|
88
|
+
routeFor(target),
|
|
89
|
+
current,
|
|
90
|
+
facts,
|
|
91
|
+
now,
|
|
92
|
+
config.policy.downgradeHorizonTurns,
|
|
93
|
+
);
|
|
94
|
+
const threshold =
|
|
95
|
+
config.policy.downgradeMass + config.policy.downgradeSlope * (tax / (tax + config.policy.downgradePivotUsd));
|
|
96
|
+
const estimate = { downgradeMass: support, streak, taxUsd: tax, threshold };
|
|
97
|
+
pending ??= estimate;
|
|
98
|
+
if (support < threshold || streak < downgradeVotes) continue;
|
|
99
|
+
if (sameTaskOf(config, advice, facts) && !facts.downAllowed) return stay('downgrade-held', estimate);
|
|
100
|
+
const gated = cashGate(config, routeFor(target), facts, now, costs, routeFor);
|
|
101
|
+
return gated.blocked ? gatedResult(gated, incumbent, next) : result(target, 'downgrade', next, estimate);
|
|
82
102
|
}
|
|
83
|
-
return stay('downgrade-pending',
|
|
103
|
+
return stay('downgrade-pending', pending);
|
|
84
104
|
}
|
|
85
105
|
|
|
86
106
|
// Share of a model's window the next request may fill. The estimate leaves out the new prompt and tool
|
|
@@ -110,7 +130,11 @@ export function cashGate(config, route, facts, now, costs, routeFor = (tier) =>
|
|
|
110
130
|
const cold = costs.coldWriteUsd(config, route.model, costs.nextContextTokens(facts));
|
|
111
131
|
if (cold <= config.policy.cashCapUsd) return { blocked: false };
|
|
112
132
|
const fallback = [...TIERS].reverse().find((t) => routeSpec(config, routeFor(t)).billing === 'plan');
|
|
113
|
-
const estimate = {
|
|
133
|
+
const estimate = {
|
|
134
|
+
coldUsd: cold,
|
|
135
|
+
cap: config.policy.cashCapUsd,
|
|
136
|
+
cache: cacheOf(config, route, facts, now, costs),
|
|
137
|
+
};
|
|
114
138
|
return { blocked: true, fallback, estimate };
|
|
115
139
|
}
|
|
116
140
|
|
package/lib/route.mjs
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
import { chooseActivity, compareRoutes, lateralMove, sameRequest } from './activity.mjs';
|
|
2
2
|
import { ACTIVITIES, rank, resolveRoute, routeSpec, TIERS } from './config.mjs';
|
|
3
3
|
import * as costs from './cost.mjs';
|
|
4
|
-
import { clip, extractFacts } from './facts.mjs';
|
|
4
|
+
import { clip, extractFacts, verifiedSince } from './facts.mjs';
|
|
5
5
|
import { CONTEXT_FILL, decide, fitTier, initialState } from './policy.mjs';
|
|
6
6
|
|
|
7
7
|
// Exact observed API snapshot, not a rule that merges different dated versions.
|
|
@@ -52,6 +52,15 @@ export function emptyLoop(config, model) {
|
|
|
52
52
|
turnId: null,
|
|
53
53
|
decision: null,
|
|
54
54
|
ineligible: [],
|
|
55
|
+
// Routed main requests so far, the one that started on the running route (`switchedAt`: requests and message
|
|
56
|
+
// count then), and the request count at the last classifier answer (`reviewedAt`). Dwell and reviews count these.
|
|
57
|
+
requests: 0,
|
|
58
|
+
servedRoute: null,
|
|
59
|
+
switchedAt: null,
|
|
60
|
+
reviewedAt: 0,
|
|
61
|
+
// The message count at the last review applied inside a turn: tool calls before it were already judged, so only
|
|
62
|
+
// later ones can move the route up again (observedMove).
|
|
63
|
+
observedFrom: 0,
|
|
55
64
|
// Each configured model's simulated cache, by models key, for the routing-vs-your-model readout (compareModels in
|
|
56
65
|
// savings.mjs).
|
|
57
66
|
yoursBy: {},
|
|
@@ -75,15 +84,36 @@ export function resetHistory(loop) {
|
|
|
75
84
|
}
|
|
76
85
|
|
|
77
86
|
export function prepareLoop(loop, messageCount) {
|
|
78
|
-
|
|
79
|
-
|
|
87
|
+
if (loop.lastMessageCount === null || messageCount >= loop.lastMessageCount)
|
|
88
|
+
return { ...loop, lastMessageCount: messageCount };
|
|
89
|
+
// Compaction or a rewind shortened the history: message cursors past its end move to it, so checks and edits made
|
|
90
|
+
// from here on count. The request-based dwell is kept.
|
|
91
|
+
const cursor = (count) => Math.min(count ?? 0, messageCount);
|
|
92
|
+
return {
|
|
93
|
+
...resetHistory(loop),
|
|
94
|
+
lastMessageCount: messageCount,
|
|
95
|
+
switchedAt: loop.switchedAt && { ...loop.switchedAt, messageCount: cursor(loop.switchedAt.messageCount) },
|
|
96
|
+
observedFrom: cursor(loop.observedFrom),
|
|
97
|
+
};
|
|
80
98
|
}
|
|
81
99
|
|
|
82
100
|
export function nativeFacts(config, loop, { messages, prompt, effort, turnId, contextTokens }) {
|
|
83
101
|
const facts = extractFacts({ messages, output_config: { effort } }, loop, config.context);
|
|
84
102
|
if (typeof prompt === 'string') facts.prompt = clip(prompt, config.context.maxTextChars);
|
|
103
|
+
// A move down on the same task waits out the dwell and for a passed verification since the last model change.
|
|
104
|
+
const since = loop.switchedAt ?? { requests: 0, messageCount: 0 };
|
|
105
|
+
const downAllowed =
|
|
106
|
+
(loop.requests ?? 0) - since.requests >= config.policy.minDwellRequests &&
|
|
107
|
+
verifiedSince(messages, since.messageCount);
|
|
85
108
|
// A loop saved without the field counts as measured, keeping the vote streak.
|
|
86
|
-
return {
|
|
109
|
+
return {
|
|
110
|
+
...facts,
|
|
111
|
+
downAllowed,
|
|
112
|
+
pin: null,
|
|
113
|
+
contextTokens,
|
|
114
|
+
turnKey: turnId,
|
|
115
|
+
historyMeasured: loop.historyMeasured !== false,
|
|
116
|
+
};
|
|
87
117
|
}
|
|
88
118
|
|
|
89
119
|
export function isModelAllowed(id, available, nativeModel) {
|
|
@@ -119,6 +149,7 @@ export function chooseRoute(config, loop, input) {
|
|
|
119
149
|
turnId: facts.turnKey,
|
|
120
150
|
decision: applied,
|
|
121
151
|
suspended: false,
|
|
152
|
+
reviewedAt: loop.requests ?? 0,
|
|
122
153
|
};
|
|
123
154
|
}
|
|
124
155
|
|
|
@@ -135,7 +166,7 @@ function routeTurn(config, loop, { facts, advice, pin, nativeModel, contextKnown
|
|
|
135
166
|
const tier0 = TIERS.includes(facts.lastRoute) ? facts.lastRoute : config.baselineTier;
|
|
136
167
|
const incumbent = { tier: tier0, activity: last.activity, route: resolveRoute(config, tier0, last.activity) };
|
|
137
168
|
const activity =
|
|
138
|
-
pin || config.activityRouting !== 'on' ? null : chooseActivity(config, advice, incumbent, facts.effort);
|
|
169
|
+
pin || config.activityRouting !== 'on' ? null : chooseActivity(config, advice, incumbent, facts.effort, facts);
|
|
139
170
|
let result =
|
|
140
171
|
pin && TIERS.includes(pin)
|
|
141
172
|
? {
|
|
@@ -246,7 +277,52 @@ function decideCell({ config, projected, facts, advice, state, now, incumbent, a
|
|
|
246
277
|
};
|
|
247
278
|
}
|
|
248
279
|
|
|
249
|
-
//
|
|
280
|
+
// Whether some activity's route at the decision's tier is stronger than the one running: only then can the turn's own
|
|
281
|
+
// tool calls move it (observedMove), so a step on the strongest route skips reading the transcript.
|
|
282
|
+
export function canMoveUp(config, decision, effort) {
|
|
283
|
+
if (config.activityRouting !== 'on' || !decision?.tier || decision.pinned) return false;
|
|
284
|
+
const from = resolveRoute(config, decision.tier, decision.activity ?? null);
|
|
285
|
+
return ACTIVITIES.some((a) => compareRoutes(config, resolveRoute(config, decision.tier, a), from, effort) > 0);
|
|
286
|
+
}
|
|
287
|
+
|
|
288
|
+
// A move up inside a turn: the classifier labels a turn from its prompt, and a prompt that reads as ops or explore can
|
|
289
|
+
// still end up editing code. Once the turn's tool calls show an activity (observedActivity in facts.mjs) whose route at the
|
|
290
|
+
// tier is stronger, the remaining steps take that route. The tools are the evidence, so the move needs no classifier
|
|
291
|
+
// probability. At probability 1 the switching tax never holds it back (the upgrade bar tops out near 0.9): only the
|
|
292
|
+
// cash gate, priced at the context-fitted route, can. Only up: a move down comes from a classifier review, past its
|
|
293
|
+
// checks. Returns the loop, unchanged when nothing moves.
|
|
294
|
+
export function observedMove(config, loop, { observed, facts, contextKnown, now }) {
|
|
295
|
+
const decision = loop.decision;
|
|
296
|
+
if (!canMoveUp(config, decision, facts.effort) || !ACTIVITIES.includes(observed)) return loop;
|
|
297
|
+
const from = resolveRoute(config, decision.tier, decision.activity ?? null);
|
|
298
|
+
// The gates price the route that will run: the one the context fits, not the tier's first choice.
|
|
299
|
+
const routeFor = (tier) => resolveRoute(config, tier, observed);
|
|
300
|
+
const tier = fitTier(config, decision.tier, costs.nextContextTokens(facts), routeFor);
|
|
301
|
+
const to = routeFor(tier);
|
|
302
|
+
if (!(compareRoutes(config, to, from, facts.effort) > 0)) return loop;
|
|
303
|
+
// Without a reliable reading of the context, a smaller window might overflow, as in routeTurn.
|
|
304
|
+
const window = (route) => routeSpec(config, route).contextWindow;
|
|
305
|
+
if ((!contextKnown || !loop.historyMeasured) && window(to) < window(from)) return loop;
|
|
306
|
+
const projected = economicConfig(config, loop);
|
|
307
|
+
const lateral = lateralMove({ config: projected, from, to, mass: 1, hold: false, facts, now, costs });
|
|
308
|
+
if (!lateral.move) return loop;
|
|
309
|
+
return {
|
|
310
|
+
...loop,
|
|
311
|
+
lastActivity: observed,
|
|
312
|
+
decision: {
|
|
313
|
+
...decision,
|
|
314
|
+
tier,
|
|
315
|
+
activity: observed,
|
|
316
|
+
model: routeSpec(config, to).id,
|
|
317
|
+
effort: costs.routeEffort(config, to, facts.effort),
|
|
318
|
+
reason: lateral.reason,
|
|
319
|
+
estimate: lateral.estimate,
|
|
320
|
+
},
|
|
321
|
+
};
|
|
322
|
+
}
|
|
323
|
+
|
|
324
|
+
// A tool continuation keeps the turn's route and activity; only the context, the model list, or the turn's own tool
|
|
325
|
+
// calls (observedMove) can move it.
|
|
250
326
|
export function continueRoute(config, loop, { nativeModel, contextTokens, contextKnown, availableModels, effort }) {
|
|
251
327
|
if (!loop.decision) return loop;
|
|
252
328
|
let decision = loop.decision;
|
|
@@ -269,7 +345,17 @@ export function continueRoute(config, loop, { nativeModel, contextTokens, contex
|
|
|
269
345
|
}
|
|
270
346
|
|
|
271
347
|
export function observeResponse(config, loop, { usage, requestedModel, effort, stopReason, now }) {
|
|
272
|
-
|
|
348
|
+
// Every request counts toward dwell and reviews; a request on another (model, effort) than the last starts a dwell,
|
|
349
|
+
// and so does the first one this loop serves: checks from before it ran on a route the router did not choose.
|
|
350
|
+
const served = `${requestedModel}@${effort ?? 'session'}`;
|
|
351
|
+
const requests = (loop.requests ?? 0) + 1;
|
|
352
|
+
const switched = loop.servedRoute !== served;
|
|
353
|
+
let next = {
|
|
354
|
+
...loop,
|
|
355
|
+
requests,
|
|
356
|
+
servedRoute: served,
|
|
357
|
+
switchedAt: switched ? { requests, messageCount: loop.lastMessageCount ?? 0 } : (loop.switchedAt ?? null),
|
|
358
|
+
};
|
|
273
359
|
if (stopReason === 'model_context_window_exceeded') {
|
|
274
360
|
next = { ...next, ineligible: [...new Set([...next.ineligible, requestedModel])] };
|
|
275
361
|
}
|
package/package.json
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@alexeiled/claude-router",
|
|
3
|
-
"version": "1.
|
|
4
|
-
"description": "Native Claude Code Mod: model and effort routing for the main conversation, advised by Jev, Clef, Clef Flash, OpenAI or Ollama.",
|
|
3
|
+
"version": "1.11.0",
|
|
4
|
+
"description": "Native Claude Code Mod: model and effort routing for the main conversation, advised by Jev, Clef, Clef Flash, Clef Omni, OpenAI or Ollama.",
|
|
5
5
|
"license": "MIT",
|
|
6
6
|
"author": "Alexei Ledenev",
|
|
7
7
|
"repository": {
|