@alexeiled/claude-router 1.5.0 → 1.6.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 +2 -2
- package/CHANGELOG.md +37 -0
- package/README.md +16 -14
- package/docs/architecture.md +62 -20
- package/docs/configuration.md +86 -32
- package/docs/evaluation.md +52 -1
- package/docs/native-router.md +37 -28
- package/docs/router-band.svg +116 -58
- package/docs/router-pane-classifier.svg +24 -7
- package/docs/router-pane-now.svg +112 -74
- package/docs/router-pane-routing.svg +117 -33
- package/docs/user-guide.md +90 -44
- package/hooks/native-router.mjs +212 -40
- package/lib/activity-stats.mjs +179 -0
- package/lib/activity.mjs +77 -0
- package/lib/band.mjs +71 -28
- package/lib/classifier-apis.mjs +133 -69
- package/lib/classifier-client.mjs +63 -28
- package/lib/classifier-contract.mjs +48 -0
- package/lib/config.mjs +138 -4
- package/lib/cost.mjs +11 -11
- package/lib/display.mjs +92 -4
- package/lib/facts.mjs +48 -0
- package/lib/panel.mjs +297 -37
- package/lib/policy.mjs +45 -26
- package/lib/route.mjs +156 -51
- package/lib/view.mjs +34 -4
- package/package.json +1 -1
- package/types/index.d.ts +72 -1
package/lib/route.mjs
CHANGED
|
@@ -1,4 +1,5 @@
|
|
|
1
|
-
import {
|
|
1
|
+
import { chooseActivity, compareRoutes, lateralMove, sameRequest } from './activity.mjs';
|
|
2
|
+
import { ACTIVITIES, rank, resolveRoute, routeSpec, TIERS } from './config.mjs';
|
|
2
3
|
import * as costs from './cost.mjs';
|
|
3
4
|
import { clip, extractFacts } from './facts.mjs';
|
|
4
5
|
import { CONTEXT_FILL, decide, fitTier, initialState } from './policy.mjs';
|
|
@@ -22,14 +23,26 @@ export function isNativeFallback(loop, model) {
|
|
|
22
23
|
return known.length > 0 && !known.some((id) => isSameModel(id, model));
|
|
23
24
|
}
|
|
24
25
|
|
|
25
|
-
|
|
26
|
+
// The tier and activity whose route runs model `id`, or null when no route names it. Base routes first, baseline
|
|
27
|
+
// first; activity overrides only when they apply, with `activityRouting: on`.
|
|
28
|
+
export function cellForModel(config, id) {
|
|
26
29
|
const order = [config.baselineTier, ...TIERS.filter((tier) => tier !== config.baselineTier)];
|
|
27
|
-
|
|
30
|
+
const runs = (tier, activity) => isSameModel(routeSpec(config, resolveRoute(config, tier, activity)).id, id);
|
|
31
|
+
const tier = order.find((t) => runs(t, null));
|
|
32
|
+
if (tier) return { tier, activity: null };
|
|
33
|
+
if (config.activityRouting !== 'on') return null;
|
|
34
|
+
for (const t of order)
|
|
35
|
+
for (const activity of ACTIVITIES)
|
|
36
|
+
if (config.activities[activity]?.[t] && runs(t, activity)) return { tier: t, activity };
|
|
37
|
+
return null;
|
|
28
38
|
}
|
|
29
39
|
|
|
30
40
|
export function emptyLoop(config, model) {
|
|
41
|
+
const cell = cellForModel(config, model);
|
|
31
42
|
return {
|
|
32
|
-
lastRoute:
|
|
43
|
+
lastRoute: cell?.tier ?? config.baselineTier,
|
|
44
|
+
lastActivity: cell?.activity ?? null,
|
|
45
|
+
would: null,
|
|
33
46
|
state: initialState(),
|
|
34
47
|
models: {},
|
|
35
48
|
resolutions: {},
|
|
@@ -43,6 +56,8 @@ export function emptyLoop(config, model) {
|
|
|
43
56
|
};
|
|
44
57
|
}
|
|
45
58
|
|
|
59
|
+
const freshState = (state) => ({ ...state, votes: [], holdUntilTurn: 0, escalatedSignature: null });
|
|
60
|
+
|
|
46
61
|
export function resetHistory(loop) {
|
|
47
62
|
return {
|
|
48
63
|
...loop,
|
|
@@ -50,7 +65,8 @@ export function resetHistory(loop) {
|
|
|
50
65
|
models: {},
|
|
51
66
|
resolutions: {},
|
|
52
67
|
historyMeasured: false,
|
|
53
|
-
state:
|
|
68
|
+
state: freshState(loop.state),
|
|
69
|
+
would: loop.would ? { ...loop.would, state: freshState(loop.would.state) } : null,
|
|
54
70
|
// The active turn keeps its route, pin and fallback suspension; the next turn decides afresh.
|
|
55
71
|
ineligible: [],
|
|
56
72
|
};
|
|
@@ -64,7 +80,8 @@ export function prepareLoop(loop, messageCount) {
|
|
|
64
80
|
export function nativeFacts(config, loop, { messages, prompt, effort, turnId, contextTokens }) {
|
|
65
81
|
const facts = extractFacts({ messages, output_config: { effort } }, loop, config.context);
|
|
66
82
|
if (typeof prompt === 'string') facts.prompt = clip(prompt, config.context.maxTextChars);
|
|
67
|
-
|
|
83
|
+
// A loop saved without the field counts as measured, keeping the vote streak.
|
|
84
|
+
return { ...facts, pin: null, contextTokens, turnKey: turnId, historyMeasured: loop.historyMeasured !== false };
|
|
68
85
|
}
|
|
69
86
|
|
|
70
87
|
export function isModelAllowed(id, available, nativeModel) {
|
|
@@ -87,93 +104,181 @@ function economicConfig(config, loop) {
|
|
|
87
104
|
return { ...config, models };
|
|
88
105
|
}
|
|
89
106
|
|
|
90
|
-
|
|
107
|
+
// `activityRouting` decides which activity the applied route may use: none in `off`, none in `shadow`, which runs the
|
|
108
|
+
// decision a second time as `on` for `decision.wouldRoute` only, and the chosen one in `on`. Shadow keeps its own cell
|
|
109
|
+
// and policy state in `loop.would`, so each would-route continues from the previous one, as `on` would. Its limit: the
|
|
110
|
+
// would-route never runs, so its cache is never observed and an unobserved incumbent is priced as `inputBounds`
|
|
111
|
+
// prices any unknown cache.
|
|
112
|
+
export function chooseRoute(config, loop, input) {
|
|
113
|
+
const { pin, facts } = input;
|
|
114
|
+
const applied = routeTurn(config, loop, input);
|
|
115
|
+
let wouldRoute = null;
|
|
116
|
+
let would = null;
|
|
117
|
+
if (config.activityRouting === 'shadow') {
|
|
118
|
+
const from = loop.would ?? {
|
|
119
|
+
lastRoute: loop.lastRoute,
|
|
120
|
+
lastActivity: loop.lastActivity ?? null,
|
|
121
|
+
state: loop.state,
|
|
122
|
+
};
|
|
123
|
+
const run = routeTurn(
|
|
124
|
+
{ ...config, activityRouting: 'on' },
|
|
125
|
+
{ ...loop, ...from },
|
|
126
|
+
{
|
|
127
|
+
...input,
|
|
128
|
+
facts: { ...facts, lastRoute: from.lastRoute },
|
|
129
|
+
},
|
|
130
|
+
);
|
|
131
|
+
const { activity, tier, model, effort, reason } = run;
|
|
132
|
+
wouldRoute = { activity, tier, model, effort, reason };
|
|
133
|
+
const stays = pin || !run.tier;
|
|
134
|
+
would = {
|
|
135
|
+
lastRoute: stays ? from.lastRoute : run.tier,
|
|
136
|
+
lastActivity: stays ? from.lastActivity : run.activity,
|
|
137
|
+
state: run.state,
|
|
138
|
+
};
|
|
139
|
+
}
|
|
140
|
+
const kept = pin || !applied.tier;
|
|
141
|
+
return {
|
|
142
|
+
...loop,
|
|
143
|
+
state: applied.state,
|
|
144
|
+
lastRoute: kept ? loop.lastRoute : applied.tier,
|
|
145
|
+
lastActivity: kept ? activityOf(config, loop) : applied.activity,
|
|
146
|
+
would,
|
|
147
|
+
turnId: facts.turnKey,
|
|
148
|
+
decision: { ...applied, wouldRoute },
|
|
149
|
+
suspended: false,
|
|
150
|
+
};
|
|
151
|
+
}
|
|
152
|
+
|
|
153
|
+
// The activity of the route running now. Outside `on` there is none, even one a turn in `on` left in the loop before
|
|
154
|
+
// the mode changed: `off` and the applied `shadow` decision are the 1.5 decision.
|
|
155
|
+
const activityOf = (config, loop) => (config.activityRouting === 'on' ? (loop.lastActivity ?? null) : null);
|
|
156
|
+
|
|
157
|
+
// One decision (plan §5.2) for the cell `{ tier, activity }` it lands on. Outside `on` the activity is null throughout.
|
|
158
|
+
function routeTurn(config, loop, { facts, advice, pin, nativeModel, contextKnown, availableModels, now }) {
|
|
91
159
|
const projected = economicConfig(config, loop);
|
|
160
|
+
const routeOf = (cell) => resolveRoute(config, cell.tier, cell.activity);
|
|
161
|
+
const specOf = (cell) => routeSpec(config, routeOf(cell));
|
|
162
|
+
const last = { tier: loop.lastRoute, activity: activityOf(config, loop) };
|
|
163
|
+
const tier0 = TIERS.includes(facts.lastRoute) ? facts.lastRoute : config.baselineTier;
|
|
164
|
+
const incumbent = { tier: tier0, activity: last.activity, route: resolveRoute(config, tier0, last.activity) };
|
|
165
|
+
const activity =
|
|
166
|
+
pin || config.activityRouting !== 'on' ? null : chooseActivity(config, advice, incumbent, facts.effort);
|
|
92
167
|
let result =
|
|
93
168
|
pin && TIERS.includes(pin)
|
|
94
|
-
? { tier: pin, reason: 'pinned', state: { ...loop.state, turn: loop.state.turn + 1 } }
|
|
95
|
-
:
|
|
96
|
-
|
|
97
|
-
|
|
98
|
-
|
|
99
|
-
|
|
100
|
-
|
|
101
|
-
now,
|
|
102
|
-
costs,
|
|
103
|
-
});
|
|
104
|
-
// Without a reliable reading of the context, a tier with a smaller window than the last route's might overflow.
|
|
105
|
-
const shrinksUnmeasured = (tier) =>
|
|
106
|
-
(!contextKnown || !loop.historyMeasured) &&
|
|
107
|
-
routeModel(config, tier).contextWindow < routeModel(config, loop.lastRoute).contextWindow;
|
|
108
|
-
const fits = (tier) => {
|
|
109
|
-
const model = routeModel(config, tier);
|
|
169
|
+
? { tier: pin, activity: null, reason: 'pinned', state: { ...loop.state, turn: loop.state.turn + 1 } }
|
|
170
|
+
: decideCell({ config, projected, facts, advice, state: loop.state, now, incumbent, activity });
|
|
171
|
+
// Without a reliable reading of the context, a route with a smaller window than the last one might overflow.
|
|
172
|
+
const shrinksUnmeasured = (cell) =>
|
|
173
|
+
(!contextKnown || !loop.historyMeasured) && specOf(cell).contextWindow < specOf(last).contextWindow;
|
|
174
|
+
const fits = (cell) => {
|
|
175
|
+
const model = specOf(cell);
|
|
110
176
|
return (
|
|
111
|
-
!shrinksUnmeasured(
|
|
177
|
+
!shrinksUnmeasured(cell) &&
|
|
112
178
|
isModelAllowed(model.id, availableModels, nativeModel) &&
|
|
113
179
|
!loop.ineligible.includes(model.id) &&
|
|
114
180
|
(!contextKnown || costs.nextContextTokens(facts) <= model.contextWindow * CONTEXT_FILL)
|
|
115
181
|
);
|
|
116
182
|
};
|
|
117
183
|
if (contextKnown) {
|
|
118
|
-
const
|
|
184
|
+
const routeFor = (tier) => resolveRoute(config, tier, result.activity);
|
|
185
|
+
const fitted = fitTier(config, result.tier, costs.nextContextTokens(facts), routeFor);
|
|
119
186
|
if (fitted !== result.tier) result = { ...result, tier: fitted, reason: 'context-fit' };
|
|
120
187
|
}
|
|
121
|
-
if (shrinksUnmeasured(result
|
|
122
|
-
if (!fits(result
|
|
123
|
-
const
|
|
124
|
-
|
|
188
|
+
if (shrinksUnmeasured(result)) result = { ...result, ...last, reason: 'context-unknown' };
|
|
189
|
+
if (!fits(result)) {
|
|
190
|
+
const native = cellForModel(config, nativeModel);
|
|
191
|
+
const cells = [last, native, ...TIERS.map((tier) => ({ tier, activity }))];
|
|
192
|
+
const fallback = cells.find((cell) => cell && fits(cell)) ?? { tier: null, activity: null };
|
|
193
|
+
result = { ...result, ...fallback, reason: 'model-unavailable' };
|
|
125
194
|
}
|
|
126
|
-
const
|
|
127
|
-
const
|
|
195
|
+
const route = result.tier ? routeOf(result) : null;
|
|
196
|
+
const model = route ? routeSpec(config, route).id : nativeModel;
|
|
197
|
+
const effort = route ? costs.routeEffort(config, route, facts.effort) : facts.effort;
|
|
128
198
|
let comparison = null;
|
|
129
199
|
const candidate = pin ?? advice?.choice;
|
|
130
200
|
if (contextKnown && loop.lastRequest && TIERS.includes(candidate) && candidate !== loop.lastRoute) {
|
|
131
201
|
const tokens = costs.nextContextTokens(facts);
|
|
132
|
-
const
|
|
133
|
-
const
|
|
134
|
-
const
|
|
202
|
+
const [to, from] = [resolveRoute(config, candidate, activity), routeOf(last)];
|
|
203
|
+
const proposed = costs.inputBounds(projected, to, tokens, facts, now);
|
|
204
|
+
const incumbentBounds = costs.inputBounds(projected, from, tokens, facts, now);
|
|
205
|
+
const forecast = costs.shadowEconomics(projected, to, from, facts, now);
|
|
135
206
|
// Without both output prices, compare input only, as shadowEconomics does.
|
|
136
207
|
const output = forecast
|
|
137
|
-
? ((
|
|
138
|
-
loop.lastRequest.outputTokens) /
|
|
139
|
-
1e6
|
|
208
|
+
? ((routeSpec(projected, to).output - routeSpec(projected, from).output) * loop.lastRequest.outputTokens) / 1e6
|
|
140
209
|
: 0;
|
|
141
210
|
comparison = {
|
|
142
211
|
candidate,
|
|
143
212
|
incumbent: loop.lastRoute,
|
|
144
|
-
minUsd: proposed.min -
|
|
145
|
-
maxUsd: proposed.max -
|
|
213
|
+
minUsd: proposed.min - incumbentBounds.max + output,
|
|
214
|
+
maxUsd: proposed.max - incumbentBounds.min + output,
|
|
146
215
|
paybackTurns: forecast?.paybackTurns ?? null,
|
|
147
216
|
outputTokens: loop.lastRequest.outputTokens,
|
|
148
217
|
};
|
|
149
218
|
}
|
|
150
|
-
|
|
151
|
-
|
|
152
|
-
|
|
153
|
-
|
|
154
|
-
|
|
155
|
-
|
|
156
|
-
|
|
157
|
-
|
|
219
|
+
return { ...result, model, effort, comparison, pinned: Boolean(pin), requestedPin: pin ?? null };
|
|
220
|
+
}
|
|
221
|
+
|
|
222
|
+
// Steps 3-6 of plan §5.2: the tier as `decide` picks it, every candidate priced at its route for `activity` and the
|
|
223
|
+
// incumbent at the route it runs; then, when the tier stays and the route would change, the lateral rule. Equal routes
|
|
224
|
+
// never switch: a label alone decides nothing.
|
|
225
|
+
function decideCell({ config, projected, facts, advice, state, now, incumbent, activity }) {
|
|
226
|
+
const routeFor = (tier) => resolveRoute(config, tier, activity);
|
|
227
|
+
// With an activity, failures move to the lowest tier whose route is stronger, or another request that does not
|
|
228
|
+
// order against it; with none, one tier up as before.
|
|
229
|
+
const escalates = (t) => {
|
|
230
|
+
const order = compareRoutes(config, routeFor(t), incumbent.route, facts.effort);
|
|
231
|
+
return order > 0 || (order === null && !sameRequest(config, routeFor(t), incumbent.route, facts.effort));
|
|
158
232
|
};
|
|
233
|
+
const escalateTo = activity === null ? undefined : (tier) => TIERS.slice(rank(tier) + 1).find(escalates) ?? null;
|
|
234
|
+
const step = decide({
|
|
235
|
+
config: projected,
|
|
236
|
+
facts,
|
|
237
|
+
advice,
|
|
238
|
+
state,
|
|
239
|
+
baseline: config.baselineTier,
|
|
240
|
+
now,
|
|
241
|
+
costs,
|
|
242
|
+
routeFor,
|
|
243
|
+
incumbentRoute: incumbent.route,
|
|
244
|
+
escalateTo,
|
|
245
|
+
});
|
|
246
|
+
const route = routeFor(step.tier);
|
|
247
|
+
if (step.tier !== incumbent.tier || sameRequest(config, route, incumbent.route, facts.effort))
|
|
248
|
+
return { ...step, activity };
|
|
249
|
+
const lateral = lateralMove({
|
|
250
|
+
config: projected,
|
|
251
|
+
from: incumbent.route,
|
|
252
|
+
to: route,
|
|
253
|
+
// Returning to the base route needs no evidence.
|
|
254
|
+
mass: activity === null ? 1 : (advice?.activity?.probabilities?.[activity] ?? 0),
|
|
255
|
+
hold: step.reason === 'hold',
|
|
256
|
+
facts,
|
|
257
|
+
now,
|
|
258
|
+
costs,
|
|
259
|
+
});
|
|
260
|
+
const activityOf = lateral.move ? activity : incumbent.activity;
|
|
261
|
+
return { ...step, activity: activityOf, reason: lateral.reason, estimate: lateral.estimate };
|
|
159
262
|
}
|
|
160
263
|
|
|
264
|
+
// A tool continuation keeps the turn's route and activity; only the context or the model list can move it.
|
|
161
265
|
export function continueRoute(config, loop, { nativeModel, contextTokens, contextKnown, availableModels, effort }) {
|
|
162
266
|
if (!loop.decision) return loop;
|
|
163
267
|
let decision = loop.decision;
|
|
164
268
|
if (contextKnown && decision.tier) {
|
|
165
|
-
const
|
|
269
|
+
const routeOf = (tier) => resolveRoute(config, tier, decision.activity ?? null);
|
|
270
|
+
const fitted = fitTier(config, decision.tier, contextTokens, routeOf);
|
|
166
271
|
if (fitted !== decision.tier)
|
|
167
272
|
decision = {
|
|
168
273
|
...decision,
|
|
169
274
|
tier: fitted,
|
|
170
|
-
model:
|
|
171
|
-
effort: costs.routeEffort(config, fitted, effort),
|
|
275
|
+
model: routeSpec(config, routeOf(fitted)).id,
|
|
276
|
+
effort: costs.routeEffort(config, routeOf(fitted), effort),
|
|
172
277
|
reason: 'context-fit',
|
|
173
278
|
};
|
|
174
279
|
}
|
|
175
280
|
if (!isModelAllowed(decision.model, availableModels, nativeModel) || loop.ineligible.includes(decision.model)) {
|
|
176
|
-
decision = { ...decision, tier: null, model: nativeModel, effort, reason: 'model-unavailable' };
|
|
281
|
+
decision = { ...decision, tier: null, activity: null, model: nativeModel, effort, reason: 'model-unavailable' };
|
|
177
282
|
}
|
|
178
283
|
return { ...loop, decision };
|
|
179
284
|
}
|
package/lib/view.mjs
CHANGED
|
@@ -30,8 +30,14 @@ export function initialView(model) {
|
|
|
30
30
|
estimate: null,
|
|
31
31
|
comparison: null,
|
|
32
32
|
probabilities: null,
|
|
33
|
+
activity: null,
|
|
34
|
+
activityChoice: null,
|
|
35
|
+
activityProbabilities: null,
|
|
36
|
+
wouldRoute: null,
|
|
33
37
|
history: [],
|
|
34
38
|
tiers: [],
|
|
39
|
+
activities: [],
|
|
40
|
+
activityStats: null,
|
|
35
41
|
configPath: null,
|
|
36
42
|
tuning: null,
|
|
37
43
|
tuningBase: null,
|
|
@@ -46,10 +52,33 @@ export function initialView(model) {
|
|
|
46
52
|
// Failures and a pause belong to the classifier that earned them.
|
|
47
53
|
export const healthOf = (client, id) => ({ ...client.snapshot(), classifier: id });
|
|
48
54
|
// The last classification's readings, cleared when another classifier takes over so no label claims them.
|
|
49
|
-
export const CLEARED_READINGS = {
|
|
55
|
+
export const CLEARED_READINGS = {
|
|
56
|
+
adviceMs: null,
|
|
57
|
+
adviceChoice: null,
|
|
58
|
+
probabilities: null,
|
|
59
|
+
estimate: null,
|
|
60
|
+
activityChoice: null,
|
|
61
|
+
activityProbabilities: null,
|
|
62
|
+
wouldRoute: null,
|
|
63
|
+
};
|
|
50
64
|
|
|
51
|
-
// The view patch for a
|
|
52
|
-
|
|
65
|
+
// The view patch for a tool continuation's route. In `on` the activity label is the route's, which a fallback to the
|
|
66
|
+
// native model drops; in `shadow` it stays the classifier's.
|
|
67
|
+
export function continuationView(config, decision, context) {
|
|
68
|
+
return {
|
|
69
|
+
selectedModel: decision.model,
|
|
70
|
+
effort: decision.effort,
|
|
71
|
+
tier: decision.tier,
|
|
72
|
+
reason: decision.reason,
|
|
73
|
+
contextTokens: context.tokens,
|
|
74
|
+
contextKnown: context.known,
|
|
75
|
+
...(config.activityRouting === 'on' ? { activity: decision.activity ?? null } : {}),
|
|
76
|
+
};
|
|
77
|
+
}
|
|
78
|
+
|
|
79
|
+
// The view patch for a main reply's usage. `tier` is the routed tier that served it, else null; `activity` the
|
|
80
|
+
// turn's activity as the view labels it, else null.
|
|
81
|
+
export function responseMetrics(view, response, tier, activity = null) {
|
|
53
82
|
const usage = response.usage;
|
|
54
83
|
const counters = usage ? [usage.input_tokens, usage.cache_read_input_tokens, usage.cache_creation_input_tokens] : [];
|
|
55
84
|
const inputTokens =
|
|
@@ -60,11 +89,12 @@ export function responseMetrics(view, response, tier) {
|
|
|
60
89
|
cacheWrite: usage?.cache_creation_input_tokens ?? null,
|
|
61
90
|
inputTokens,
|
|
62
91
|
outputTokens: usage?.output_tokens ?? null,
|
|
63
|
-
// Appended together so the Usage trend can color each reading by its tier.
|
|
92
|
+
// Appended together so the Usage trend can color each reading by its tier, and REPLIES letter it by activity.
|
|
64
93
|
...(Number.isFinite(inputTokens)
|
|
65
94
|
? {
|
|
66
95
|
history: [...(view?.history ?? []), inputTokens].slice(-HISTORY),
|
|
67
96
|
tiers: [...(view?.tiers ?? []), tier ?? null].slice(-HISTORY),
|
|
97
|
+
activities: [...(view?.activities ?? []), activity ?? null].slice(-HISTORY),
|
|
68
98
|
}
|
|
69
99
|
: {}),
|
|
70
100
|
};
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@alexeiled/claude-router",
|
|
3
|
-
"version": "1.
|
|
3
|
+
"version": "1.6.0",
|
|
4
4
|
"description": "Native Claude Code Mod: model and effort routing for the main conversation, advised by Jev, Clef, Clef Flash, OpenAI or Ollama.",
|
|
5
5
|
"license": "MIT",
|
|
6
6
|
"author": "Alexei Ledenev",
|
package/types/index.d.ts
CHANGED
|
@@ -1,6 +1,52 @@
|
|
|
1
1
|
declare module 'claude-code' {
|
|
2
2
|
type RouterTier = 'micro' | 'low' | 'medium' | 'high';
|
|
3
3
|
type RouterCacheState = 'fresh' | 'unknown';
|
|
4
|
+
// What kind of work a turn does (ACTIVITIES in lib/config.mjs); 'uncertain' only as a classifier answer.
|
|
5
|
+
type RouterActivity = 'code' | 'debug' | 'explore' | 'plan' | 'review' | 'ops' | 'docs';
|
|
6
|
+
type RouterActivityAnswer = RouterActivity | 'uncertain';
|
|
7
|
+
type RouterActivityMode = 'off' | 'shadow' | 'on';
|
|
8
|
+
// A finished turn's bucket, read from its tool calls.
|
|
9
|
+
type RouterObserved = 'code' | 'docs' | 'ops' | 'read' | 'talk';
|
|
10
|
+
// Classifier output. `activity` is null when not asked, or missing, malformed or failed.
|
|
11
|
+
interface RouterAdvice {
|
|
12
|
+
choice: RouterTier | 'uncertain';
|
|
13
|
+
confidence: number;
|
|
14
|
+
probabilities: Record<RouterTier | 'uncertain', number>;
|
|
15
|
+
continuation: number | null;
|
|
16
|
+
activity?: {
|
|
17
|
+
choice: RouterActivityAnswer;
|
|
18
|
+
probabilities: Record<RouterActivityAnswer, number>;
|
|
19
|
+
} | null;
|
|
20
|
+
}
|
|
21
|
+
// What `on` would do, computed in `shadow`. `model` is a model id, as `decision.model`.
|
|
22
|
+
interface RouterWouldRoute {
|
|
23
|
+
activity: RouterActivity | null;
|
|
24
|
+
tier: RouterTier | null;
|
|
25
|
+
model: string;
|
|
26
|
+
effort: string | number | null;
|
|
27
|
+
reason: string;
|
|
28
|
+
}
|
|
29
|
+
interface RouterActivityCounts {
|
|
30
|
+
turns: number;
|
|
31
|
+
requests: number;
|
|
32
|
+
inputTokens: number;
|
|
33
|
+
outputTokens: number;
|
|
34
|
+
}
|
|
35
|
+
// Per-session activity stats; 'none' counts turns without an applied or accepted activity.
|
|
36
|
+
interface RouterActivitySession {
|
|
37
|
+
byActivity: Partial<Record<RouterActivity | 'none', RouterActivityCounts>>;
|
|
38
|
+
switches: { tier: number; activity: number };
|
|
39
|
+
agreement: { matched: number; total: number };
|
|
40
|
+
shadow: { differs: number; turns: number };
|
|
41
|
+
}
|
|
42
|
+
// Cross-session counts under store key 'activity:stats:v1'. `runs` buckets run lengths 1, 2, 3, 4, 5+.
|
|
43
|
+
interface RouterActivityStore {
|
|
44
|
+
version: 1;
|
|
45
|
+
confusion: Partial<Record<RouterActivityAnswer | 'none', Partial<Record<RouterObserved, number>>>>;
|
|
46
|
+
runs: Partial<Record<RouterActivity, [number, number, number, number, number]>>;
|
|
47
|
+
lateral: { taken: number; refused: number };
|
|
48
|
+
shadow: { differs: number; turns: number };
|
|
49
|
+
}
|
|
4
50
|
interface RouterComparison {
|
|
5
51
|
candidate: RouterTier;
|
|
6
52
|
incumbent: RouterTier;
|
|
@@ -24,9 +70,19 @@ declare module 'claude-code' {
|
|
|
24
70
|
horizon: number;
|
|
25
71
|
cashCapUsd: number;
|
|
26
72
|
}
|
|
73
|
+
// A model alias and the effort it runs at: what Claude Code receives and what owns a cache.
|
|
74
|
+
interface RouterRoute {
|
|
75
|
+
model: string;
|
|
76
|
+
effort?: string | null;
|
|
77
|
+
}
|
|
27
78
|
interface RouterRoutes {
|
|
28
|
-
routes: Record<RouterTier,
|
|
79
|
+
routes: Record<RouterTier, RouterRoute>;
|
|
29
80
|
baselineTier: RouterTier;
|
|
81
|
+
// The Routing tab's activity edits; a draft without them edits none. A null cell is a removed override.
|
|
82
|
+
activities?: Partial<
|
|
83
|
+
Record<RouterActivity, Partial<Record<RouterTier, { model?: string; effort?: string | null } | null>>>
|
|
84
|
+
>;
|
|
85
|
+
activityRouting?: RouterActivityMode;
|
|
30
86
|
}
|
|
31
87
|
interface RouterView {
|
|
32
88
|
phase: 'ready' | 'choosing' | 'routed' | 'manual' | 'unavailable';
|
|
@@ -54,8 +110,16 @@ declare module 'claude-code' {
|
|
|
54
110
|
estimate?: RouterEstimate | null;
|
|
55
111
|
comparison?: RouterComparison | null;
|
|
56
112
|
probabilities?: Partial<Record<RouterTier | 'uncertain', number>> | null;
|
|
113
|
+
// The turn's activity: the applied one in 'on', the classifier's accepted label in 'shadow'.
|
|
114
|
+
activity?: RouterActivity | null;
|
|
115
|
+
activityChoice?: RouterActivityAnswer | null;
|
|
116
|
+
activityProbabilities?: Partial<Record<RouterActivityAnswer, number>> | null;
|
|
117
|
+
wouldRoute?: RouterWouldRoute | null;
|
|
57
118
|
history?: number[];
|
|
58
119
|
tiers?: (RouterTier | null)[];
|
|
120
|
+
// Aligned with `history` and `tiers`.
|
|
121
|
+
activities?: (RouterActivity | null)[];
|
|
122
|
+
activityStats?: RouterActivitySession | null;
|
|
59
123
|
configPath?: string | null;
|
|
60
124
|
tuning?: Partial<RouterTuning> | null;
|
|
61
125
|
tuningBase?: RouterTuning | null;
|
|
@@ -75,6 +139,10 @@ declare module 'claude-code' {
|
|
|
75
139
|
}
|
|
76
140
|
interface RouterLoop {
|
|
77
141
|
lastRoute: RouterTier;
|
|
142
|
+
// The activity of the route running now; absent in loops saved before 1.6.
|
|
143
|
+
lastActivity?: RouterActivity | null;
|
|
144
|
+
// Shadow mode only: the cell and policy state `on` would run with, so each would-route continues the last one.
|
|
145
|
+
would?: { lastRoute: RouterTier; lastActivity: RouterActivity | null; state: RouterPolicyState } | null;
|
|
78
146
|
state: RouterPolicyState;
|
|
79
147
|
models: Record<string, { lastAt: number; prefixTokens: number }>;
|
|
80
148
|
resolutions: Record<string, string>;
|
|
@@ -98,6 +166,9 @@ declare module 'claude-code' {
|
|
|
98
166
|
effort: string | number | null;
|
|
99
167
|
estimate?: RouterEstimate | null;
|
|
100
168
|
comparison?: RouterComparison | null;
|
|
169
|
+
// The applied activity; `wouldRoute` is set only in shadow mode.
|
|
170
|
+
activity?: RouterActivity | null;
|
|
171
|
+
wouldRoute?: RouterWouldRoute | null;
|
|
101
172
|
pinned: boolean;
|
|
102
173
|
requestedPin: RouterTier | null;
|
|
103
174
|
} | null;
|