@alexeiled/claude-router 1.13.0 → 1.15.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 +46 -0
- package/README.md +3 -0
- package/docs/architecture.md +11 -1
- package/docs/configuration.md +6 -2
- package/docs/evaluation.md +8 -7
- package/docs/native-router.md +2 -1
- package/docs/router-band.svg +30 -8
- package/docs/router-pane-now.svg +134 -111
- package/docs/router-pane-policy.svg +47 -43
- package/docs/router-pane-usage-whatif.svg +75 -12
- package/docs/router-pane-usage.svg +79 -13
- package/docs/routing-modes.md +139 -0
- package/docs/user-guide.md +11 -5
- package/hooks/native-router.mjs +170 -23
- package/lib/activity.mjs +8 -2
- package/lib/band.mjs +43 -11
- package/lib/config.mjs +69 -17
- package/lib/cost.mjs +3 -0
- package/lib/display.mjs +21 -2
- package/lib/modes.mjs +98 -0
- package/lib/panel.mjs +338 -45
- package/lib/route.mjs +80 -23
- package/lib/subagents.mjs +182 -64
- package/lib/usage.mjs +32 -20
- package/lib/view.mjs +3 -0
- package/package.json +2 -1
- package/types/index.d.ts +34 -10
package/hooks/native-router.mjs
CHANGED
|
@@ -31,12 +31,14 @@ import {
|
|
|
31
31
|
effectiveRoutes,
|
|
32
32
|
loadConfig,
|
|
33
33
|
MIGRATION_HINT,
|
|
34
|
+
ROUTING_MODES,
|
|
34
35
|
supportedVersion,
|
|
35
36
|
TIERS,
|
|
36
37
|
tuningOf,
|
|
37
38
|
withActivities,
|
|
38
39
|
withClassifier,
|
|
39
40
|
withClassifierTimeout,
|
|
41
|
+
withMode,
|
|
40
42
|
withRoutes,
|
|
41
43
|
withTuning,
|
|
42
44
|
} from '../lib/config.mjs';
|
|
@@ -54,6 +56,7 @@ import {
|
|
|
54
56
|
unavailableReason,
|
|
55
57
|
} from '../lib/display.mjs';
|
|
56
58
|
import { clip, observedActivity, promptIndex } from '../lib/facts.mjs';
|
|
59
|
+
import { applyMode, modeLabel, readProjectMode, resolveRoutingMode } from '../lib/modes.mjs';
|
|
57
60
|
import { renderPanel, routeDraftOf, routingChanges } from '../lib/panel.mjs';
|
|
58
61
|
import {
|
|
59
62
|
canMoveUp,
|
|
@@ -93,6 +96,7 @@ import {
|
|
|
93
96
|
emptySubagentStore,
|
|
94
97
|
flushedAgent,
|
|
95
98
|
mergeSubagentStores,
|
|
99
|
+
moveOf,
|
|
96
100
|
passReason,
|
|
97
101
|
RESPAWN_WINDOW_MS,
|
|
98
102
|
readSubagentStore,
|
|
@@ -134,6 +138,8 @@ const PANE = 'jev-router';
|
|
|
134
138
|
const PANE_TITLE = 'Router';
|
|
135
139
|
const BAND_DETAIL = 'band:detail';
|
|
136
140
|
const MODE_PREFIX = 'mode:';
|
|
141
|
+
// The session's routing mode override (lib/modes.mjs), apart from its auto|manual MODE_PREFIX.
|
|
142
|
+
const ROUTING_MODE_PREFIX = 'routing-mode:';
|
|
137
143
|
const isSet = (value) => /^(1|true|yes|on)$/i.test(String(value ?? '').trim());
|
|
138
144
|
|
|
139
145
|
// The counts kept across sessions: each session writes only its own record of a kind, `prefix` and its session id,
|
|
@@ -172,6 +178,7 @@ const LEDGERS = {
|
|
|
172
178
|
subagents: {
|
|
173
179
|
prefix: SUBAGENT_PREFIX,
|
|
174
180
|
field: 'subagentStore',
|
|
181
|
+
ownField: 'subagentSession',
|
|
175
182
|
read: readSubagentStore,
|
|
176
183
|
afterReset: subagentsAfterReset,
|
|
177
184
|
merge: mergeSubagentStores,
|
|
@@ -206,6 +213,10 @@ function createRouter(options) {
|
|
|
206
213
|
turnControllers: new Map(),
|
|
207
214
|
view: null,
|
|
208
215
|
modes: new Map(),
|
|
216
|
+
// Each session's routing mode override (null: none), as read from or written to the store.
|
|
217
|
+
routingModes: new Map(),
|
|
218
|
+
// The project's `.claude/router.json` mode, read at session.start: { mode, error }.
|
|
219
|
+
project: { mode: null, error: null },
|
|
209
220
|
// Each routed turn's activity record until turn.complete adds it to the stats, and the session's open run of
|
|
210
221
|
// one activity, flushed to the store when it ends.
|
|
211
222
|
turnActivities: new Map(),
|
|
@@ -231,8 +242,8 @@ function createRouter(options) {
|
|
|
231
242
|
// first request goes out on that route, unless it was pressed again meanwhile.
|
|
232
243
|
pinPresses: 0,
|
|
233
244
|
turnPins: new Map(),
|
|
234
|
-
// Each spawned agent's record by agentId (spawnRecord
|
|
235
|
-
// for respawns.
|
|
245
|
+
// Each spawned agent's record by agentId (spawnRecord, `running` between its steps and its turn's end), and when
|
|
246
|
+
// each parent loop last finished an agent of a type, for respawns.
|
|
236
247
|
agents: new Map(),
|
|
237
248
|
finished: new Map(),
|
|
238
249
|
// Each agent type's definition frontmatter by provider and type, read once per session (agentDefinition).
|
|
@@ -295,6 +306,84 @@ async function rememberMode($, mode) {
|
|
|
295
306
|
}
|
|
296
307
|
}
|
|
297
308
|
|
|
309
|
+
// The routing mode a turn starts with and where it comes from. A store that cannot be read counts as no override.
|
|
310
|
+
async function routingModeOf($, router) {
|
|
311
|
+
const sessionId = await $.session.id();
|
|
312
|
+
if (!router.routingModes.has(sessionId)) {
|
|
313
|
+
const saved = await $.store.get(`${ROUTING_MODE_PREFIX}${sessionId}`).catch(() => null);
|
|
314
|
+
router.routingModes.set(sessionId, ROUTING_MODES.includes(saved) ? saved : null);
|
|
315
|
+
}
|
|
316
|
+
return resolveRoutingMode({
|
|
317
|
+
session: router.routingModes.get(sessionId),
|
|
318
|
+
project: router.project.mode,
|
|
319
|
+
profile: router.config.mode,
|
|
320
|
+
});
|
|
321
|
+
}
|
|
322
|
+
|
|
323
|
+
// The prompt footer's word for the router: paused or broken routing, or a routing mode other than balanced, which
|
|
324
|
+
// changes what every routed turn costs. Null for none.
|
|
325
|
+
async function footerLabel($, router, view) {
|
|
326
|
+
if (view.phase === 'unavailable') return 'routing unavailable';
|
|
327
|
+
if ((await modeOf($, router, view.mode)) === 'manual') return 'routing off';
|
|
328
|
+
const routingMode = view.routingMode;
|
|
329
|
+
return routingMode && routingMode.mode !== 'balanced' ? `${routingMode.mode} mode (${routingMode.source})` : null;
|
|
330
|
+
}
|
|
331
|
+
|
|
332
|
+
const sameMode = (a, b) => a?.mode === b?.mode && a?.source === b?.source;
|
|
333
|
+
|
|
334
|
+
// A turn's configs when turn.start did not record them, as after a reload of the Mod mid-turn.
|
|
335
|
+
async function turnConfigOf($, router) {
|
|
336
|
+
return { config: applyMode(router.config, await routingModeOf($, router)), configured: router.config };
|
|
337
|
+
}
|
|
338
|
+
|
|
339
|
+
// The turn routes on the configured routes as its routing mode moves them, fixed now so a change mid-turn waits for
|
|
340
|
+
// the next turn; a pin uses `configured` (decideTurn).
|
|
341
|
+
async function fixTurnConfig($, router, turnId) {
|
|
342
|
+
const turn = await turnConfigOf($, router);
|
|
343
|
+
router.turnConfigs.set(turnId, turn);
|
|
344
|
+
const { routingMode } = turn.config;
|
|
345
|
+
if (router.view && !sameMode(router.view.routingMode, routingMode)) await updateView($, router, { routingMode });
|
|
346
|
+
}
|
|
347
|
+
|
|
348
|
+
// `/router mode <mode|default>`: the session's override, kept for a resume of this session only. It changes the
|
|
349
|
+
// preferred route from the next turn; the route in use moves through the gates. No turn is aborted.
|
|
350
|
+
async function setRoutingMode($, router, value) {
|
|
351
|
+
const sessionId = await $.session.id();
|
|
352
|
+
const key = `${ROUTING_MODE_PREFIX}${sessionId}`;
|
|
353
|
+
let saved = true;
|
|
354
|
+
try {
|
|
355
|
+
if (value === 'default') await $.store.delete(key);
|
|
356
|
+
else await $.store.set(key, value);
|
|
357
|
+
} catch {
|
|
358
|
+
saved = false;
|
|
359
|
+
}
|
|
360
|
+
router.routingModes.set(sessionId, value === 'default' ? null : value);
|
|
361
|
+
const routingMode = await routingModeOf($, router);
|
|
362
|
+
await updateView($, router, { routingMode });
|
|
363
|
+
const unsaved =
|
|
364
|
+
value === 'default'
|
|
365
|
+
? 'A resume of this session may bring the cleared mode back: the store could not be written.'
|
|
366
|
+
: 'A resume of this session will not keep it: the store could not be written.';
|
|
367
|
+
return [`Routing mode: ${modeLabel(routingMode)}, from the next turn.`, ...(saved ? [] : [unsaved])].join(' ');
|
|
368
|
+
}
|
|
369
|
+
|
|
370
|
+
// A project's `.claude/router.json`, which may set only `mode`. Never a profile's own file: not the active profile's,
|
|
371
|
+
// and not in the home directory, whose `.claude` is the default profile. A repo controls this file, so a symlink, which
|
|
372
|
+
// could reach a file outside it, is refused as the profile's is. A file that does not read is ignored, with the reason
|
|
373
|
+
// for the pane.
|
|
374
|
+
async function readProject($, profilePath) {
|
|
375
|
+
try {
|
|
376
|
+
const cwd = await $.session.cwd();
|
|
377
|
+
const path = `${cwd}/.claude/router.json`;
|
|
378
|
+
const home = await $.env.get('HOME');
|
|
379
|
+
if (path === profilePath || cwd === home || !(await $.fs.exists(path))) return { mode: null, error: null };
|
|
380
|
+
if ((await $.fs.stat(path)).isLink) return { mode: null, error: 'project .claude/router.json is a symlink' };
|
|
381
|
+
return readProjectMode(await $.fs.read(path));
|
|
382
|
+
} catch {
|
|
383
|
+
return { mode: null, error: 'project .claude/router.json could not be read' };
|
|
384
|
+
}
|
|
385
|
+
}
|
|
386
|
+
|
|
298
387
|
async function updateView($, router, patch) {
|
|
299
388
|
const value = router.view ?? (await readView($, router));
|
|
300
389
|
router.view = { ...value, ...patch };
|
|
@@ -445,7 +534,8 @@ async function setPin($, router, tier) {
|
|
|
445
534
|
return `${tier} pinned for the next turn and its tool continuations.`;
|
|
446
535
|
}
|
|
447
536
|
|
|
448
|
-
// `/router [auto|off|pin <tier>|activities <mode>]`; with no action, the pane, or the status text without
|
|
537
|
+
// `/router [auto|off|pin <tier>|activities <mode>|mode <mode>]`; with no action, the pane, or the status text without
|
|
538
|
+
// a surface.
|
|
449
539
|
async function routerCommand($, router, args) {
|
|
450
540
|
const [action, value] = args.trim().split(/\s+/);
|
|
451
541
|
if (action === 'auto' || action === 'off') {
|
|
@@ -456,6 +546,12 @@ async function routerCommand($, router, args) {
|
|
|
456
546
|
}
|
|
457
547
|
if (action === 'pin')
|
|
458
548
|
return { text: TIERS.includes(value) ? await setPin($, router, value) : `Choose ${TIERS.join(', ')}.` };
|
|
549
|
+
if (action === 'mode')
|
|
550
|
+
return {
|
|
551
|
+
text: [...ROUTING_MODES, 'default'].includes(value)
|
|
552
|
+
? await setRoutingMode($, router, value)
|
|
553
|
+
: `Choose mode ${[...ROUTING_MODES, 'default'].join(', ')}.`,
|
|
554
|
+
};
|
|
459
555
|
if (action === 'activities')
|
|
460
556
|
return {
|
|
461
557
|
text: ACTIVITY_MODES.includes(value)
|
|
@@ -576,6 +672,8 @@ function detailText(config, view) {
|
|
|
576
672
|
const missing = missingCredentials(config, view, config.classifier);
|
|
577
673
|
return [
|
|
578
674
|
`Router — routing ${view.mode === 'auto' ? 'on' : 'off'}`,
|
|
675
|
+
...(view.routingMode ? [`Mode: ${modeLabel(view.routingMode)}`] : []),
|
|
676
|
+
...(view.projectError ? [`Ignored: ${view.projectError}`] : []),
|
|
579
677
|
`Native model: ${view.nativeModel}`,
|
|
580
678
|
`Selected: ${view.selectedModel ?? 'not selected'}`,
|
|
581
679
|
`Observed: ${view.actualModel ?? 'no response yet'}`,
|
|
@@ -643,7 +741,9 @@ async function* passMain($, e, next, loop, version, nativeModel, reason, router)
|
|
|
643
741
|
// the classifier call. The pin is the one in `view`, the view as the step read it; it is used up only once the route
|
|
644
742
|
// is written, so a turn interrupted before then leaves it for the next.
|
|
645
743
|
async function decideTurn($, router, e, signal, step) {
|
|
646
|
-
const { sessionId, view,
|
|
744
|
+
const { sessionId, view, loop, loopVersion, context, nativeModel, availableModels } = step;
|
|
745
|
+
// A pin runs its tier's configured route: the routing mode moves only routes the router chooses.
|
|
746
|
+
const cfg = view.pendingPin ? step.configured : step.cfg;
|
|
647
747
|
const ref = { ...LOOP, id: 'main' };
|
|
648
748
|
const controller = new AbortController();
|
|
649
749
|
const cancel = () => controller.abort();
|
|
@@ -690,6 +790,8 @@ async function decideTurn($, router, e, signal, step) {
|
|
|
690
790
|
if (controller.signal.aborted || (await $.session.id()) !== sessionId || (await modeOf($, router)) !== 'auto')
|
|
691
791
|
return null;
|
|
692
792
|
const previous = loop.decision;
|
|
793
|
+
if (pin)
|
|
794
|
+
router.turnConfigs.set(e.turnId, { config: { ...cfg, routingMode: step.cfg.routingMode }, configured: cfg });
|
|
693
795
|
const selected = chooseRoute(cfg, loop, {
|
|
694
796
|
facts,
|
|
695
797
|
advice: result.advice,
|
|
@@ -708,12 +810,29 @@ async function decideTurn($, router, e, signal, step) {
|
|
|
708
810
|
if (previous?.model && previous.model !== selected.decision.model && !selected.decision.pinned)
|
|
709
811
|
$.ui.toast(switchToast(cfg, previous, selected.decision, selected.decision.estimate));
|
|
710
812
|
const activity = turnActivity(cfg, result.advice, previous, selected.decision);
|
|
813
|
+
const routingMode = step.cfg.routingMode;
|
|
814
|
+
// One line per decision in Claude Code's debug log, so a later replay can compare modes. No prompt text.
|
|
815
|
+
$.ui.log(
|
|
816
|
+
`router decision ${JSON.stringify({
|
|
817
|
+
mode: routingMode.mode,
|
|
818
|
+
modeSource: routingMode.source,
|
|
819
|
+
classified: result.advice?.choice ?? null,
|
|
820
|
+
tier: selected.decision.tier,
|
|
821
|
+
reason: selected.decision.reason,
|
|
822
|
+
route: `${selected.decision.model}@${selected.decision.effort ?? 'session'}`,
|
|
823
|
+
pinned: selected.decision.pinned,
|
|
824
|
+
})}`,
|
|
825
|
+
{ to: 'debug' },
|
|
826
|
+
);
|
|
711
827
|
router.turnActivities.set(e.turnId, {
|
|
712
828
|
...activity,
|
|
713
829
|
reason: selected.decision.reason,
|
|
714
830
|
escalated: Boolean(selected.decision.escalated),
|
|
715
831
|
pinned: selected.decision.pinned,
|
|
716
832
|
route: `${selected.decision.model}@${selected.decision.effort ?? 'session'}`,
|
|
833
|
+
// A pinned turn ran the configured routes, which balanced runs: its replies count there.
|
|
834
|
+
routingMode: pin ? DEFAULTS.mode : routingMode.mode,
|
|
835
|
+
modeSource: pin ? 'pin' : routingMode.source,
|
|
717
836
|
classifier: cfg.classifier,
|
|
718
837
|
offSwitches: router.offSwitches,
|
|
719
838
|
adviceMs,
|
|
@@ -728,6 +847,8 @@ async function decideTurn($, router, e, signal, step) {
|
|
|
728
847
|
await updateView($, router, {
|
|
729
848
|
...(activity.switched ? switchView(previous, selected.decision, activity.label, Date.now()) : {}),
|
|
730
849
|
phase: 'routed',
|
|
850
|
+
// The session's mode, not this turn's: a `/router mode` sent while the classifier answered names the next turn.
|
|
851
|
+
routingMode: await routingModeOf($, router),
|
|
731
852
|
selectedModel: selected.decision.model,
|
|
732
853
|
actualModel: null,
|
|
733
854
|
tier: selected.decision.tier,
|
|
@@ -994,6 +1115,7 @@ async function addSavings($, router, { turnId, compared, tier, route, yours, byI
|
|
|
994
1115
|
const turn = router.turnActivities.get(turnId);
|
|
995
1116
|
const entry = replyEntry({
|
|
996
1117
|
at,
|
|
1118
|
+
mode: turn?.routingMode ?? view.routingMode?.mode ?? DEFAULTS.mode,
|
|
997
1119
|
activity: tier ? (turn?.label ?? null) : null,
|
|
998
1120
|
tier,
|
|
999
1121
|
route,
|
|
@@ -1192,17 +1314,27 @@ async function noteSpawn($, router, { cfg, e, pass, decision, routed, result, de
|
|
|
1192
1314
|
definition,
|
|
1193
1315
|
})
|
|
1194
1316
|
: result.model;
|
|
1317
|
+
const routedModel = decision?.model ?? result.model;
|
|
1195
1318
|
const record = spawnRecord({
|
|
1196
1319
|
sessionId: await $.session.id(),
|
|
1197
1320
|
spawn: e,
|
|
1198
1321
|
pass,
|
|
1199
1322
|
choice: decision?.choice ?? null,
|
|
1200
|
-
routedModel
|
|
1323
|
+
routedModel,
|
|
1201
1324
|
coreModel,
|
|
1325
|
+
move: routed ? moveOf(cfg, routedModel, coreModel) : null,
|
|
1202
1326
|
failed: decision?.failed,
|
|
1203
1327
|
respawn: Number.isFinite(finishedAt) && Date.now() - finishedAt < RESPAWN_WINDOW_MS,
|
|
1204
1328
|
});
|
|
1205
|
-
router.agents.set(result.agentId, { ...record, parentKey });
|
|
1329
|
+
router.agents.set(result.agentId, { ...record, parentKey, running: true });
|
|
1330
|
+
await showRunning($, router);
|
|
1331
|
+
}
|
|
1332
|
+
|
|
1333
|
+
// How many of the agents with a record are between their start or a step and their turn's end, in the view when it
|
|
1334
|
+
// changes. An agent spawned with routing off has no record and is not counted.
|
|
1335
|
+
async function showRunning($, router) {
|
|
1336
|
+
const running = [...router.agents.values()].filter((agent) => agent.running).length;
|
|
1337
|
+
if ((router.view?.subagentsRunning ?? 0) !== running) await updateView($, router, { subagentsRunning: running });
|
|
1206
1338
|
}
|
|
1207
1339
|
|
|
1208
1340
|
// A subagent's prompt-cache lifetime, by Claude Code's rule for requests outside the main conversation.
|
|
@@ -1224,7 +1356,9 @@ async function* stepAgent($, router, e, next) {
|
|
|
1224
1356
|
try {
|
|
1225
1357
|
const ttl = await subagentTtlOf($);
|
|
1226
1358
|
const agent = router.agents.get(e.agentId);
|
|
1227
|
-
if (agent)
|
|
1359
|
+
if (agent)
|
|
1360
|
+
router.agents.set(e.agentId, { ...addAgentReply(router.config, agent, response.usage, ttl), running: true });
|
|
1361
|
+
if (agent && !agent.running) await showRunning($, router);
|
|
1228
1362
|
} catch {}
|
|
1229
1363
|
}
|
|
1230
1364
|
return response;
|
|
@@ -1235,7 +1369,8 @@ async function finishAgent($, router, agentId) {
|
|
|
1235
1369
|
const agent = router.agents.get(agentId);
|
|
1236
1370
|
if (!agent) return;
|
|
1237
1371
|
router.finished.set(agent.parentKey, Date.now());
|
|
1238
|
-
router.agents.set(agentId, flushedAgent(agent));
|
|
1372
|
+
router.agents.set(agentId, { ...flushedAgent(agent), running: false });
|
|
1373
|
+
await showRunning($, router).catch(() => {});
|
|
1239
1374
|
await flushSubagents($, router, [agent]);
|
|
1240
1375
|
}
|
|
1241
1376
|
|
|
@@ -1310,7 +1445,9 @@ function paneActions($, router, view) {
|
|
|
1310
1445
|
if (result.error) return updateView($, router, { notice: result.error });
|
|
1311
1446
|
const drafts = router.view ?? view;
|
|
1312
1447
|
const reset = await adopt(result.config);
|
|
1313
|
-
|
|
1448
|
+
// A saved or undone profile mode changes the mode shown, unless a session or project mode wins.
|
|
1449
|
+
const routingMode = await routingModeOf($, router);
|
|
1450
|
+
return updateView($, router, { ...reset, ...rebased(drafts), ...saved(router.config), routingMode });
|
|
1314
1451
|
};
|
|
1315
1452
|
// Defaults go into the routing draft like any edit; the notice says whether Save has anything of that section left
|
|
1316
1453
|
// to write.
|
|
@@ -1410,6 +1547,12 @@ function paneActions($, router, view) {
|
|
|
1410
1547
|
// An insight's link: the Routes tab with the grid cell it names open.
|
|
1411
1548
|
openRoute: (cell) => updateView($, router, { tab: 'routes', routeCell: cell, notice: null }),
|
|
1412
1549
|
confirmDelete: (asked) => updateView($, router, { confirmDelete: asked }),
|
|
1550
|
+
// The profile's routing mode, saved at once with Undo. A session or project mode still wins over it.
|
|
1551
|
+
routingMode: async (mode) => {
|
|
1552
|
+
const from = router.config.mode;
|
|
1553
|
+
if (mode === from || !ROUTING_MODES.includes(mode)) return undefined;
|
|
1554
|
+
return write(`routing mode ${from} → ${mode}`, (file) => withMode(file, mode));
|
|
1555
|
+
},
|
|
1413
1556
|
// `/router activities <mode>`: the mode alone, saved at once like a classifier press, with Undo.
|
|
1414
1557
|
activityRouting: (mode) => {
|
|
1415
1558
|
const from = router.config.activityRouting;
|
|
@@ -1557,13 +1700,14 @@ export function register(on, options) {
|
|
|
1557
1700
|
router.definitions.clear();
|
|
1558
1701
|
await $.command.register({
|
|
1559
1702
|
name: 'router',
|
|
1560
|
-
description: 'Open the Router pane, or switch routing: auto, off, pin <tier>, activities <mode>.',
|
|
1561
|
-
argumentHint: '[auto|off|pin <tier>|activities off|on]',
|
|
1703
|
+
description: 'Open the Router pane, or switch routing: auto, off, pin <tier>, activities <mode>, mode <mode>.',
|
|
1704
|
+
argumentHint: '[auto|off|pin <tier>|activities off|on|mode cost|balanced|quality|default]',
|
|
1562
1705
|
immediate: true,
|
|
1563
1706
|
});
|
|
1564
1707
|
const model = await $.session.model();
|
|
1565
1708
|
try {
|
|
1566
1709
|
router.config = await loadNativeConfig($);
|
|
1710
|
+
router.project = await readProject($, router.config.nativePath);
|
|
1567
1711
|
const existing = await readView($, router);
|
|
1568
1712
|
router.view = existing;
|
|
1569
1713
|
const sameClassifier = existing.health?.classifier === router.config.classifier;
|
|
@@ -1584,6 +1728,8 @@ export function register(on, options) {
|
|
|
1584
1728
|
credentials: await credentialsOf($, options, router.config),
|
|
1585
1729
|
health: healthOf(clientOf(router, router.config.classifier), router.config.classifier),
|
|
1586
1730
|
configPath: router.config.nativePath,
|
|
1731
|
+
routingMode: await routingModeOf($, router),
|
|
1732
|
+
projectError: router.project.error,
|
|
1587
1733
|
tuning: null,
|
|
1588
1734
|
tuningBase: null,
|
|
1589
1735
|
routeDraft: null,
|
|
@@ -1623,8 +1769,8 @@ export function register(on, options) {
|
|
|
1623
1769
|
|
|
1624
1770
|
on('command.run', { command: 'router' }, ($, e) => routerCommand($, router, e.args));
|
|
1625
1771
|
|
|
1626
|
-
on('turn.start', (
|
|
1627
|
-
router
|
|
1772
|
+
on('turn.start', async ($, e, next) => {
|
|
1773
|
+
await fixTurnConfig($, router, e.turnId);
|
|
1628
1774
|
router.prompts.set(e.turnId, clip(e.text, router.config.context.maxTextChars));
|
|
1629
1775
|
return next(e);
|
|
1630
1776
|
});
|
|
@@ -1637,7 +1783,8 @@ export function register(on, options) {
|
|
|
1637
1783
|
|
|
1638
1784
|
on('turn.step', async function* ($, e, next) {
|
|
1639
1785
|
if (e.agentId) return yield* stepAgent($, router, e, next);
|
|
1640
|
-
const
|
|
1786
|
+
const turn = router.turnConfigs.get(e.turnId) ?? (await turnConfigOf($, router));
|
|
1787
|
+
const cfg = turn.config;
|
|
1641
1788
|
const [sessionId, nativeModel, view] = await Promise.all([$.session.id(), $.session.model(), readView($, router)]);
|
|
1642
1789
|
const mode = await modeOf($, router, view.mode);
|
|
1643
1790
|
if (e.index === 0) {
|
|
@@ -1651,7 +1798,8 @@ export function register(on, options) {
|
|
|
1651
1798
|
const ref = { ...LOOP, id: 'main' };
|
|
1652
1799
|
const loaded = await $.state.get(ref);
|
|
1653
1800
|
let loopVersion = loaded.version;
|
|
1654
|
-
|
|
1801
|
+
// The session's model names its tier in the configured routes: a mode's table can run it at another tier.
|
|
1802
|
+
let loop = prepareLoop(loaded.value ?? emptyLoop(turn.configured, e.model), e.messageCount);
|
|
1655
1803
|
if (view.phase === 'unavailable' || mode === 'manual') {
|
|
1656
1804
|
return yield* passMain($, e, next, loop, loopVersion, nativeModel, 'manual', router);
|
|
1657
1805
|
}
|
|
@@ -1668,6 +1816,7 @@ export function register(on, options) {
|
|
|
1668
1816
|
sessionId,
|
|
1669
1817
|
view,
|
|
1670
1818
|
cfg,
|
|
1819
|
+
configured: turn.configured,
|
|
1671
1820
|
loop,
|
|
1672
1821
|
loopVersion,
|
|
1673
1822
|
context,
|
|
@@ -1769,13 +1918,7 @@ export function register(on, options) {
|
|
|
1769
1918
|
|
|
1770
1919
|
// Paused or broken routing stays visible in the prompt footer even when the band is collapsed.
|
|
1771
1920
|
on('ui.render', { component: 'SessionMode' }, async ($, e, next) => {
|
|
1772
|
-
const
|
|
1773
|
-
const label =
|
|
1774
|
-
view.phase === 'unavailable'
|
|
1775
|
-
? 'routing unavailable'
|
|
1776
|
-
: (await modeOf($, router, view.mode)) === 'manual'
|
|
1777
|
-
? 'routing off'
|
|
1778
|
-
: null;
|
|
1921
|
+
const label = await footerLabel($, router, await readView($, router));
|
|
1779
1922
|
return label ? next({ ...e, props: { ...e.props, modes: [...e.props.modes, label] } }) : next(e);
|
|
1780
1923
|
});
|
|
1781
1924
|
|
|
@@ -1797,7 +1940,11 @@ export function register(on, options) {
|
|
|
1797
1940
|
router.config,
|
|
1798
1941
|
view,
|
|
1799
1942
|
usage,
|
|
1800
|
-
{
|
|
1943
|
+
{
|
|
1944
|
+
columns: e.props.bodyColumns,
|
|
1945
|
+
agentId: e.props.view?.agentId,
|
|
1946
|
+
agent: router.agents.get(e.props.view?.agentId) ?? null,
|
|
1947
|
+
},
|
|
1801
1948
|
{
|
|
1802
1949
|
open: () => openPane($, router),
|
|
1803
1950
|
mode: (mode) => changeMode($, router, mode),
|
package/lib/activity.mjs
CHANGED
|
@@ -54,15 +54,21 @@ export function chooseActivity(config, advice, incumbent, sentEffort, facts = {}
|
|
|
54
54
|
// the base route), must clear the tier upgrade bar for this switching tax. Down on economics: the move must pay back
|
|
55
55
|
// its cache write within the downgrade horizon. A pair that does not order (an unpriced model, a numeric effort, two
|
|
56
56
|
// models at one price) counts as up: it needs evidence, and the base route is always reachable. Labels alone never
|
|
57
|
-
// switch, so one vote is enough. During an escalation hold only a stronger route may be taken.
|
|
57
|
+
// switch, so one vote is enough. During an escalation hold only a stronger route may be taken. A cheaper route on the
|
|
58
|
+
// same task (`sameTask`) waits for facts.downAllowed, as a tier downgrade does: a routing mode changes the route
|
|
59
|
+
// without a new label, and a free switch must still wait out the dwell. A model with a lower input price also counts
|
|
60
|
+
// as cheaper there, whatever its output price: that is the order the cost mode picks by. Returns
|
|
58
61
|
// { move, reason, estimate }.
|
|
59
|
-
export function lateralMove({ config, from, to, mass, hold, facts, now, costs }) {
|
|
62
|
+
export function lateralMove({ config, from, to, mass, hold, sameTask = false, facts, now, costs }) {
|
|
60
63
|
const order = compareRoutes(config, to, from, facts.effort);
|
|
61
64
|
if (hold && !(order > 0)) return { move: false, reason: 'hold', estimate: null };
|
|
62
65
|
const p = config.policy;
|
|
63
66
|
let estimate;
|
|
67
|
+
if (order !== -1 && sameTask && !facts.downAllowed && routeSpec(config, to).input < routeSpec(config, from).input)
|
|
68
|
+
return { move: false, reason: 'downgrade-held', estimate: null };
|
|
64
69
|
if (order === -1) {
|
|
65
70
|
estimate = { taxUsd: costs.downgradeTaxUsd(config, to, from, facts, now, p.downgradeHorizonTurns) };
|
|
71
|
+
if (sameTask && !facts.downAllowed) return { move: false, reason: 'downgrade-held', estimate };
|
|
66
72
|
// Before the first measured reply no cache of this history exists, though the tax prices an unknown one as warm:
|
|
67
73
|
// staying protects nothing.
|
|
68
74
|
const fresh = facts.historyMeasured === false;
|
package/lib/band.mjs
CHANGED
|
@@ -5,11 +5,13 @@ import {
|
|
|
5
5
|
classifierStatus,
|
|
6
6
|
classifierWarns,
|
|
7
7
|
differenceShare,
|
|
8
|
+
modelColor,
|
|
8
9
|
modelName,
|
|
9
10
|
NOT_A_TIER_REASON,
|
|
10
11
|
percentPair,
|
|
11
12
|
reasonActivity,
|
|
12
13
|
routeLabel,
|
|
14
|
+
routingModeText,
|
|
13
15
|
SAVINGS_COLOR,
|
|
14
16
|
shortReason,
|
|
15
17
|
TIER_COLOR,
|
|
@@ -20,6 +22,7 @@ import {
|
|
|
20
22
|
} from './display.mjs';
|
|
21
23
|
import { isSameModel } from './route.mjs';
|
|
22
24
|
import { emptyTotals, modelSpec, readout } from './savings.mjs';
|
|
25
|
+
import { PASS_WHY } from './subagents.mjs';
|
|
23
26
|
|
|
24
27
|
const BARS = '▂▄▆█';
|
|
25
28
|
const SEPARATOR = ' · ';
|
|
@@ -160,7 +163,11 @@ export function bandSegments(config, view, usage, actions) {
|
|
|
160
163
|
)
|
|
161
164
|
: null;
|
|
162
165
|
if (!view.tier && view.phase === 'ready' && !view.actualModel)
|
|
163
|
-
return [
|
|
166
|
+
return [
|
|
167
|
+
segment(0, meter(null, true), part(' Routing on · ready', { dimColor: true })),
|
|
168
|
+
pin,
|
|
169
|
+
segment(5, part(routingModeText(view), { dimColor: true })),
|
|
170
|
+
].filter(Boolean);
|
|
164
171
|
const main = segment(
|
|
165
172
|
0,
|
|
166
173
|
// The space after the pill keeps its background off the next word.
|
|
@@ -191,6 +198,7 @@ export function bandSegments(config, view, usage, actions) {
|
|
|
191
198
|
main,
|
|
192
199
|
pin,
|
|
193
200
|
segment(1, part(shortReason(view.reason, reasonActivity(config, view)), { dimColor: true })),
|
|
201
|
+
segment(5, part(routingModeText(view), { dimColor: true })),
|
|
194
202
|
support ? segment(4, part(support, { dimColor: true })) : null,
|
|
195
203
|
Number.isFinite(switchUsd) && switchUsd >= 0.005
|
|
196
204
|
? segment(4, part(`switch cost ≈ ${usd(switchUsd)}`, { dimColor: true }))
|
|
@@ -265,19 +273,43 @@ function hoverSegments(view, actions, routing) {
|
|
|
265
273
|
].filter(Boolean);
|
|
266
274
|
}
|
|
267
275
|
|
|
268
|
-
|
|
276
|
+
// A subagent's model and who chose it, as the Usage tab's squares show it: filled when the router moved it off
|
|
277
|
+
// Claude Code's pick. Claude Code's model goes first in a narrow band.
|
|
278
|
+
function agentParts(agent, columns) {
|
|
279
|
+
const color = modelColor(agent.routedModel);
|
|
280
|
+
const moved = !agent.pass && agent.move;
|
|
281
|
+
const name = part(`${moved ? '■' : '□'} ${modelName(agent.routedModel)}`, color ? { color } : {});
|
|
282
|
+
const why = agent.pass
|
|
283
|
+
? `Claude Code’s pick: ${PASS_WHY[agent.pass]}`
|
|
284
|
+
: moved
|
|
285
|
+
? `moved ${agent.move === 'moved' ? '' : `${agent.move} `}by the router`
|
|
286
|
+
: agent.choice === 'core'
|
|
287
|
+
? `Claude Code’s pick: ${agent.failed ? 'classifier did not answer' : 'the router sent no model'}`
|
|
288
|
+
: 'the router kept Claude Code’s pick';
|
|
289
|
+
const parts = [part('○ Router · ', { dimColor: true }), name, part(` · ${why}`, { dimColor: true })];
|
|
290
|
+
const pick = part(` · Claude Code: ${modelName(agent.coreModel)}`, { dimColor: true });
|
|
291
|
+
const width = parts.reduce((sum, p) => sum + p.text.length, 0) + pick.text.length;
|
|
292
|
+
return moved && agent.coreModel && !(Number.isFinite(columns) && width > columns) ? [...parts, pick] : parts;
|
|
293
|
+
}
|
|
294
|
+
|
|
295
|
+
export function renderBand({ Box, Text, Button }, config, view, usage, { columns, agentId, agent = null }, actions) {
|
|
269
296
|
const draw = (p) => (p.button ? Button(p.button) : Text({ ...p.style, children: p.text }));
|
|
270
297
|
const row = (parts) => Box({ children: parts.map(draw) });
|
|
271
|
-
// A subagent's model is chosen once, at spawn, and never changes between its steps.
|
|
298
|
+
// A subagent's model is chosen once, at spawn, and never changes between its steps. Without its record (routing
|
|
299
|
+
// off, or the router reloaded since the spawn) only the mode is known.
|
|
272
300
|
if (agentId)
|
|
273
|
-
return row(
|
|
274
|
-
|
|
275
|
-
|
|
276
|
-
|
|
277
|
-
|
|
278
|
-
|
|
279
|
-
|
|
280
|
-
|
|
301
|
+
return row(
|
|
302
|
+
agent
|
|
303
|
+
? agentParts(agent, columns)
|
|
304
|
+
: [
|
|
305
|
+
part(
|
|
306
|
+
config.subagentRouting === 'on'
|
|
307
|
+
? '○ Router · subagent model chosen at spawn'
|
|
308
|
+
: '○ Router · subagents keep their own model',
|
|
309
|
+
{ dimColor: true },
|
|
310
|
+
),
|
|
311
|
+
],
|
|
312
|
+
);
|
|
281
313
|
const kept = fitSegments(bandSegments(config, view, usage, actions), Math.max(0, columns - ROUTER_BUTTON));
|
|
282
314
|
const line = kept.flatMap((s, i) => (i ? [part(SEPARATOR, { dimColor: true }), ...s.parts] : s.parts));
|
|
283
315
|
line.push(part(' '), button({ key: 'details', label: 'Router', plain: true, onPress: actions.open }));
|
package/lib/config.mjs
CHANGED
|
@@ -16,6 +16,10 @@ const withoutShadow = (file) =>
|
|
|
16
16
|
Object.fromEntries(Object.entries(file).filter(([key, value]) => !(value === 'shadow' && MODE_KEYS.includes(key))));
|
|
17
17
|
// A `subagents.types` value that asks the classifier instead of naming a model.
|
|
18
18
|
export const CLASSIFY = 'classify';
|
|
19
|
+
// The routing mode trades cost against answer quality (lib/modes.mjs). Not the session's auto|manual mode.
|
|
20
|
+
export const ROUTING_MODES = ['cost', 'balanced', 'quality'];
|
|
21
|
+
// The modes that patch the policy; `balanced` is the base policy itself.
|
|
22
|
+
const PATCHED_MODES = ['cost', 'quality'];
|
|
19
23
|
const SONNET_HIGH = { model: 'sonnet', effort: 'high' };
|
|
20
24
|
export const DEFAULTS = {
|
|
21
25
|
baselineTier: 'low',
|
|
@@ -128,6 +132,34 @@ export const DEFAULTS = {
|
|
|
128
132
|
// classifier yet: the probe results record whether the label was right, not its probability.
|
|
129
133
|
activityMass: 0.6,
|
|
130
134
|
},
|
|
135
|
+
// `cost` uses a cheaper route where the turn allows it, `quality` a stronger one; `balanced` routes as 1.14. The
|
|
136
|
+
// routes stay as configured: the mode moves a tier's route one step (lib/modes.mjs). Each mode's `policy` replaces
|
|
137
|
+
// those fields of `policy` while it is active. The values are codex-router's presets, not tuned on this router.
|
|
138
|
+
mode: 'balanced',
|
|
139
|
+
modes: {
|
|
140
|
+
cost: {
|
|
141
|
+
policy: {
|
|
142
|
+
upgradeVotes: 3,
|
|
143
|
+
upgradeBase: 0.85,
|
|
144
|
+
jumpConfidence: 0.98,
|
|
145
|
+
downgradeVotes: 1,
|
|
146
|
+
downgradeMass: 0.8,
|
|
147
|
+
minDwellRequests: 4,
|
|
148
|
+
escalationHoldTurns: 1,
|
|
149
|
+
},
|
|
150
|
+
},
|
|
151
|
+
quality: {
|
|
152
|
+
policy: {
|
|
153
|
+
upgradeVotes: 1,
|
|
154
|
+
upgradeBase: 0.6,
|
|
155
|
+
jumpConfidence: 0.9,
|
|
156
|
+
downgradeVotes: 3,
|
|
157
|
+
downgradeMass: 0.95,
|
|
158
|
+
minDwellRequests: 16,
|
|
159
|
+
escalationHoldTurns: 4,
|
|
160
|
+
},
|
|
161
|
+
},
|
|
162
|
+
},
|
|
131
163
|
// The active entry of `classifiers`. `api` names the wire protocol (CLASSIFIER_APIS); a user entry without one speaks
|
|
132
164
|
// `system-one`. `keyOption` names the plugin option that holds the bearer key, or null for no key (a local server);
|
|
133
165
|
// a `{name}` in `endpoint` is filled from the plugin option of that name. Both must be in CLASSIFIER_OPTIONS.
|
|
@@ -372,6 +404,12 @@ export function withActivities(file, draft) {
|
|
|
372
404
|
};
|
|
373
405
|
}
|
|
374
406
|
|
|
407
|
+
// The router.json `file` with the profile's routing mode; the default is written as no key.
|
|
408
|
+
export function withMode(file, mode) {
|
|
409
|
+
const { mode: _, ...rest } = file;
|
|
410
|
+
return mode === DEFAULTS.mode ? rest : { ...rest, mode };
|
|
411
|
+
}
|
|
412
|
+
|
|
375
413
|
// The pane's policy controls and the router.json fields they stand for. The classifier deadline saves on its own.
|
|
376
414
|
const TUNING_FIELDS = {
|
|
377
415
|
downgradeVotes: ['policy', 'downgradeVotes'],
|
|
@@ -462,7 +500,7 @@ function checkShape(file) {
|
|
|
462
500
|
if (file && typeof file === 'object' && Object.hasOwn(file, 'jev'))
|
|
463
501
|
throw new Error(`router.json uses the 1.1 jev section; ${MIGRATION_HINT}`);
|
|
464
502
|
checkObject(file, 'router.json', Object.keys(DEFAULTS));
|
|
465
|
-
const { routes, activities, models, cache, policy, classifiers, context, subagents } = file;
|
|
503
|
+
const { routes, activities, models, cache, policy, modes, classifiers, context, subagents } = file;
|
|
466
504
|
if (routes !== undefined) {
|
|
467
505
|
checkObject(routes, 'routes', TIERS);
|
|
468
506
|
for (const [tier, route] of Object.entries(routes)) checkObject(route, `routes.${tier}`, ROUTE_KEYS);
|
|
@@ -490,6 +528,13 @@ function checkShape(file) {
|
|
|
490
528
|
if (cache[map] !== undefined) checkObject(cache[map], `cache.${map}`);
|
|
491
529
|
}
|
|
492
530
|
if (policy !== undefined) checkObject(policy, 'policy', Object.keys(DEFAULTS.policy));
|
|
531
|
+
if (modes !== undefined) {
|
|
532
|
+
checkObject(modes, 'modes', PATCHED_MODES);
|
|
533
|
+
for (const [mode, entry] of Object.entries(modes)) {
|
|
534
|
+
checkObject(entry, `modes.${mode}`, ['policy']);
|
|
535
|
+
if (entry.policy !== undefined) checkObject(entry.policy, `modes.${mode}.policy`, Object.keys(DEFAULTS.policy));
|
|
536
|
+
}
|
|
537
|
+
}
|
|
493
538
|
if (classifiers !== undefined) {
|
|
494
539
|
checkObject(classifiers, 'classifiers');
|
|
495
540
|
for (const [id, entry] of Object.entries(classifiers)) checkObject(entry, `classifiers.${id}`, CLASSIFIER_KEYS);
|
|
@@ -536,22 +581,11 @@ function validate(config) {
|
|
|
536
581
|
}
|
|
537
582
|
for (const [alias, model] of Object.entries(config.models)) validateModel(`models.${alias}`, model);
|
|
538
583
|
if (!TIERS.includes(config.baselineTier)) throw new Error(`baselineTier must be one of ${TIERS.join(', ')}`);
|
|
539
|
-
|
|
540
|
-
|
|
541
|
-
|
|
542
|
-
|
|
543
|
-
|
|
544
|
-
if (!isNumber(p[field], 1, { integer: true })) throw new Error(`policy.${field} must be a positive integer`);
|
|
545
|
-
}
|
|
546
|
-
for (const field of ['reviewEveryRequests', 'minDwellRequests']) {
|
|
547
|
-
if (!isNumber(p[field], 0, { integer: true })) throw new Error(`policy.${field} must be a non-negative integer`);
|
|
548
|
-
}
|
|
549
|
-
// The pivot divides: tax / (tax + pivot). Zero makes a free switch NaN and silently stops that switch.
|
|
550
|
-
for (const side of ['upgrade', 'downgrade']) {
|
|
551
|
-
if (!isNumber(p[`${side}Slope`], 0)) throw new Error(`policy.${side}Slope must be a non-negative number`);
|
|
552
|
-
if (!isNumber(p[`${side}PivotUsd`], 0, { above: true })) throw new Error(`policy.${side}PivotUsd must be positive`);
|
|
553
|
-
}
|
|
554
|
-
if (!isNumber(p.cashCapUsd, 0)) throw new Error('policy.cashCapUsd must be a non-negative number');
|
|
584
|
+
validatePolicy(config.policy, 'policy');
|
|
585
|
+
if (!ROUTING_MODES.includes(config.mode)) throw new Error(`mode must be one of ${ROUTING_MODES.join(', ')}`);
|
|
586
|
+
// A patch is checked as the policy it makes; the base passed already, so an error is the patch's field.
|
|
587
|
+
for (const mode of PATCHED_MODES)
|
|
588
|
+
validatePolicy({ ...config.policy, ...config.modes[mode]?.policy }, `modes.${mode}.policy`);
|
|
555
589
|
const { cache, context } = config;
|
|
556
590
|
for (const map of ['writeMultiplier', 'ttlMs']) {
|
|
557
591
|
for (const [ttl, value] of Object.entries(cache[map]))
|
|
@@ -579,6 +613,24 @@ function validate(config) {
|
|
|
579
613
|
}
|
|
580
614
|
}
|
|
581
615
|
|
|
616
|
+
function validatePolicy(p, at) {
|
|
617
|
+
for (const field of ['upgradeBase', 'jumpConfidence', 'downgradeMass', 'continuationMass', 'activityMass']) {
|
|
618
|
+
if (!(isNumber(p[field], 0) && p[field] <= 1)) throw new Error(`${at}.${field} must be between 0 and 1`);
|
|
619
|
+
}
|
|
620
|
+
for (const field of ['upgradeVotes', 'downgradeVotes', 'downgradeHorizonTurns', 'escalationHoldTurns']) {
|
|
621
|
+
if (!isNumber(p[field], 1, { integer: true })) throw new Error(`${at}.${field} must be a positive integer`);
|
|
622
|
+
}
|
|
623
|
+
for (const field of ['reviewEveryRequests', 'minDwellRequests']) {
|
|
624
|
+
if (!isNumber(p[field], 0, { integer: true })) throw new Error(`${at}.${field} must be a non-negative integer`);
|
|
625
|
+
}
|
|
626
|
+
// The pivot divides: tax / (tax + pivot). Zero makes a free switch NaN and silently stops that switch.
|
|
627
|
+
for (const side of ['upgrade', 'downgrade']) {
|
|
628
|
+
if (!isNumber(p[`${side}Slope`], 0)) throw new Error(`${at}.${side}Slope must be a non-negative number`);
|
|
629
|
+
if (!isNumber(p[`${side}PivotUsd`], 0, { above: true })) throw new Error(`${at}.${side}PivotUsd must be positive`);
|
|
630
|
+
}
|
|
631
|
+
if (!isNumber(p.cashCapUsd, 0)) throw new Error(`${at}.cashCapUsd must be a non-negative number`);
|
|
632
|
+
}
|
|
633
|
+
|
|
582
634
|
function validateModel(at, model) {
|
|
583
635
|
for (const field of ['input', 'cacheRead', 'contextWindow']) {
|
|
584
636
|
if (!Number.isFinite(model[field]) || model[field] < 0)
|