@alexeiled/claude-router 1.8.1 → 1.9.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 +10 -0
- package/README.md +7 -3
- package/docs/activity-routing.md +5 -4
- package/docs/architecture.md +13 -3
- package/docs/configuration.md +62 -2
- package/docs/evaluation.md +39 -3
- package/docs/native-router.md +3 -3
- package/docs/router-pane-routing.svg +3 -4
- package/docs/router-pane-usage.svg +12 -9
- package/docs/user-guide.md +3 -3
- package/hooks/native-router.mjs +339 -33
- package/lib/band.mjs +10 -1
- package/lib/classifier-client.mjs +6 -3
- package/lib/config.mjs +37 -1
- package/lib/cost.mjs +14 -3
- package/lib/panel.mjs +84 -10
- package/lib/route.mjs +2 -2
- package/lib/savings.mjs +11 -3
- package/lib/subagents.mjs +280 -0
- package/package.json +1 -1
- package/types/index.d.ts +29 -0
package/lib/panel.mjs
CHANGED
|
@@ -13,7 +13,7 @@ import {
|
|
|
13
13
|
TIERS,
|
|
14
14
|
tuningOf,
|
|
15
15
|
} from './config.mjs';
|
|
16
|
-
import { routeEffort } from './cost.mjs';
|
|
16
|
+
import { effortSharesCache, routeEffort } from './cost.mjs';
|
|
17
17
|
import {
|
|
18
18
|
ACTIVITY_LETTER,
|
|
19
19
|
activityReading,
|
|
@@ -57,6 +57,7 @@ import {
|
|
|
57
57
|
readout,
|
|
58
58
|
readSavingsStore,
|
|
59
59
|
} from './savings.mjs';
|
|
60
|
+
import { PASS_REASONS, readSubagentStore } from './subagents.mjs';
|
|
60
61
|
|
|
61
62
|
const TABS = [
|
|
62
63
|
['now', '1', 'Now'],
|
|
@@ -79,6 +80,12 @@ const ACTIVITY_MODE_HINT = {
|
|
|
79
80
|
shadow: 'shows what on would do; base routes run',
|
|
80
81
|
on: 'an override runs when the activity has one',
|
|
81
82
|
};
|
|
83
|
+
// What `subagentRouting` does, under the router.json path: it is set in the file, not in the pane.
|
|
84
|
+
const SUBAGENT_LINE = {
|
|
85
|
+
off: 'Subagents keep their own model (subagentRouting off).',
|
|
86
|
+
shadow: 'Subagents: shadow. A model is chosen at spawn and recorded, not applied.',
|
|
87
|
+
on: 'Subagents: on. Agents that pin no model get one at spawn, kept for every step.',
|
|
88
|
+
};
|
|
82
89
|
const EFFORT_SHORT = { low: 'low', medium: 'med', high: 'high', xhigh: 'xh', max: 'max' };
|
|
83
90
|
|
|
84
91
|
// The route draft the Routing tab edits: the saved routes, activity overrides and mode until the person changes one.
|
|
@@ -438,7 +445,7 @@ function routingTab(ui, config, view, _usage, actions, modelOptions) {
|
|
|
438
445
|
),
|
|
439
446
|
ui.text(' '),
|
|
440
447
|
ui.head('SWITCH COST · from these routes'),
|
|
441
|
-
...switchCost(ui, draft.routes),
|
|
448
|
+
...switchCost(ui, config, draft.routes),
|
|
442
449
|
ui.Button({ key: 'reset-routes', label: 'Reset routes to defaults', hotkey: 'r', onPress: actions.resetRoutes }),
|
|
443
450
|
ui.dim('A new model ID needs router.json → models: price, window, efforts.'),
|
|
444
451
|
ui.text(' '),
|
|
@@ -463,12 +470,12 @@ function routingTab(ui, config, view, _usage, actions, modelOptions) {
|
|
|
463
470
|
`File ${view.configPath ?? 'profile router.json'} `,
|
|
464
471
|
view.configPath ? ui.Button({ key: 'copy-path', label: 'copy', onPress: actions.copyPath }) : null,
|
|
465
472
|
),
|
|
466
|
-
ui.dim(
|
|
473
|
+
ui.dim(SUBAGENT_LINE[config.subagentRouting]),
|
|
467
474
|
);
|
|
468
475
|
return out;
|
|
469
476
|
}
|
|
470
477
|
|
|
471
|
-
function switchCost(ui, routes) {
|
|
478
|
+
function switchCost(ui, config, routes) {
|
|
472
479
|
return LADDER.slice(0, -1).map((upperTier, i) => {
|
|
473
480
|
const upper = routes[upperTier];
|
|
474
481
|
const lower = routes[LADDER[i + 1]];
|
|
@@ -476,7 +483,13 @@ function switchCost(ui, routes) {
|
|
|
476
483
|
if (sameRoute(upper, lower))
|
|
477
484
|
return ui.line(ui.text('! ', { color: 'yellow' }), pair, 'identical: this step changes nothing');
|
|
478
485
|
if (upper.model === lower.model)
|
|
479
|
-
return ui.line(
|
|
486
|
+
return ui.line(
|
|
487
|
+
ui.dim('· '),
|
|
488
|
+
pair,
|
|
489
|
+
sharesEffort(config, upper)
|
|
490
|
+
? 'same model, new effort: keeps its cache'
|
|
491
|
+
: 'same model, new effort: priced as a new cache',
|
|
492
|
+
);
|
|
480
493
|
return ui.line(ui.dim('· '), pair, 'model change: priced as a cold cache write');
|
|
481
494
|
});
|
|
482
495
|
}
|
|
@@ -488,6 +501,9 @@ function shortRoute(config, route) {
|
|
|
488
501
|
return `${modelName(model.id)[0]}${effort}`;
|
|
489
502
|
}
|
|
490
503
|
const routeKey = (route) => `${route.model}@${route.effort ?? ''}`;
|
|
504
|
+
const sharesEffort = (config, route) => effortSharesCache(config, config.models[route.model]?.id);
|
|
505
|
+
// The cache a route runs on: one per model on a model that keeps one cache across efforts, else one per route.
|
|
506
|
+
const cacheOf = (config, route) => (sharesEffort(config, route) ? route.model : routeKey(route));
|
|
491
507
|
|
|
492
508
|
// Why an override may be a mistake: no effect, a route above the next tier's, or a pair no other cell runs.
|
|
493
509
|
function overrideWarnings(config, uses, activity, tier) {
|
|
@@ -496,7 +512,9 @@ function overrideWarnings(config, uses, activity, tier) {
|
|
|
496
512
|
const above = config.routes[TIERS[TIERS.indexOf(tier) + 1]];
|
|
497
513
|
return [
|
|
498
514
|
above && compareRoutes(config, route, above) > 0 ? 'stronger than the tier above' : null,
|
|
499
|
-
uses.get(
|
|
515
|
+
uses.get(cacheOf(config, route)) === 1
|
|
516
|
+
? `${sharesEffort(config, route) ? 'new model' : 'new (model, effort) pair'}: one more cache`
|
|
517
|
+
: null,
|
|
500
518
|
].filter(Boolean);
|
|
501
519
|
}
|
|
502
520
|
|
|
@@ -505,9 +523,13 @@ function activitySections(ui, config, view, changes, actions, modelOptions) {
|
|
|
505
523
|
const draft = { ...config, ...changes.draft };
|
|
506
524
|
const mode = draft.activityRouting;
|
|
507
525
|
const cellRoutes = ACTIVITIES.flatMap((activity) => TIERS.map((tier) => resolveRoute(draft, tier, activity)));
|
|
526
|
+
// Uses per cache, for the one-more-cache warning, and the distinct routes.
|
|
508
527
|
const uses = new Map();
|
|
509
|
-
|
|
510
|
-
|
|
528
|
+
const routeKeys = new Set();
|
|
529
|
+
for (const route of [...TIERS.map((tier) => draft.routes[tier]), ...cellRoutes]) {
|
|
530
|
+
uses.set(cacheOf(draft, route), (uses.get(cacheOf(draft, route)) ?? 0) + 1);
|
|
531
|
+
routeKeys.add(routeKey(route));
|
|
532
|
+
}
|
|
511
533
|
// Activities with the same row share it, so the matrix stays as short as the overrides are few.
|
|
512
534
|
const rows = new Map();
|
|
513
535
|
for (const activity of ACTIVITIES) {
|
|
@@ -518,7 +540,7 @@ function activitySections(ui, config, view, changes, actions, modelOptions) {
|
|
|
518
540
|
const row = rows.get(cells.join()) ?? { names: [], cells };
|
|
519
541
|
rows.set(cells.join(), { ...row, names: [...row.names, activity] });
|
|
520
542
|
}
|
|
521
|
-
const distinct = uses.size;
|
|
543
|
+
const [distinct, caches] = [routeKeys.size, uses.size];
|
|
522
544
|
const matrixRow = (name, cells) => ui.text(` ${name.padEnd(30)}${cells.map((c) => c.padEnd(9)).join('')}`);
|
|
523
545
|
// The mode leads the section: it decides whether the matrix below runs or is only shown.
|
|
524
546
|
const out = [
|
|
@@ -546,7 +568,7 @@ function activitySections(ui, config, view, changes, actions, modelOptions) {
|
|
|
546
568
|
),
|
|
547
569
|
...[...rows.values()].map(({ names, cells }) => matrixRow(names.join(' '), cells)),
|
|
548
570
|
ui.dim(
|
|
549
|
-
` ${distinct} distinct route${distinct === 1 ? '' : 's'}
|
|
571
|
+
` ${distinct} distinct route${distinct === 1 ? '' : 's'} · ${caches} cache${caches === 1 ? '' : 's'}` +
|
|
550
572
|
`${mode === 'on' ? '' : ' once activity routing is on'}`,
|
|
551
573
|
),
|
|
552
574
|
ui.text(' '),
|
|
@@ -1144,6 +1166,56 @@ function savingsSection(ui, config, view, columns) {
|
|
|
1144
1166
|
return [...out, ...notes()];
|
|
1145
1167
|
}
|
|
1146
1168
|
|
|
1169
|
+
// Prices summed over the priced requests, and how many were not priced (a model without a price in router.json).
|
|
1170
|
+
const pricedText = (text, counts) =>
|
|
1171
|
+
counts.pricedRequests < counts.requests ? `${text} (${counts.requests - counts.pricedRequests} unpriced)` : text;
|
|
1172
|
+
|
|
1173
|
+
// Subagent routing across sessions since the last reset. Per routed type: agents, how many the decision moved off
|
|
1174
|
+
// core's model, requests per agent and respawns (the retry proxies), and core's cost against the routed one at list
|
|
1175
|
+
// prices. Shadow and on count apart: shadow prices the decision on the agent's own tokens, on applies it and estimates
|
|
1176
|
+
// core's model. Then the spawns that passed through, by reason, priced on the model they ran on.
|
|
1177
|
+
function subagentUsage(ui, config, view, columns) {
|
|
1178
|
+
const mode = config.subagentRouting;
|
|
1179
|
+
const store = readSubagentStore(view.subagentStore);
|
|
1180
|
+
const out = [ui.line(ui.head('SUBAGENTS · across sessions'), ui.dim(` subagent routing ${mode}`))];
|
|
1181
|
+
const sections = ['shadow', 'on']
|
|
1182
|
+
.map((m) => ({ m, rows: Object.entries(store.routed[m]).filter(([, counts]) => counts.agents > 0) }))
|
|
1183
|
+
.filter(({ rows }) => rows.length);
|
|
1184
|
+
const passed = PASS_REASONS.filter((reason) => store.passed[reason]?.agents > 0);
|
|
1185
|
+
if (!sections.length && !passed.length)
|
|
1186
|
+
return [
|
|
1187
|
+
...out,
|
|
1188
|
+
ui.dim(
|
|
1189
|
+
mode === 'off' ? ' Not recorded. Set subagentRouting to shadow or on in router.json.' : ' no subagents yet',
|
|
1190
|
+
),
|
|
1191
|
+
];
|
|
1192
|
+
for (const { m, rows } of sections) {
|
|
1193
|
+
out.push(
|
|
1194
|
+
ui.dim(m === 'shadow' ? ' shadow: core’s model → the decided one' : ' on: core’s model (est.) → routed'),
|
|
1195
|
+
);
|
|
1196
|
+
for (const [type, c] of rows.sort((a, b) => b[1].agents - a[1].agents)) {
|
|
1197
|
+
const cost = pricedText(`${usd(c.coreUsd)} → ${usd(c.routedUsd)}`, c);
|
|
1198
|
+
out.push(
|
|
1199
|
+
ui.text(
|
|
1200
|
+
` ${type} ${c.agents} agent${c.agents === 1 ? '' : 's'} · ${c.differs} moved · ${(c.requests / c.agents).toFixed(1)} req/agent · ${c.respawns} respawns · ${cost}`,
|
|
1201
|
+
),
|
|
1202
|
+
);
|
|
1203
|
+
const choices = Object.entries(c.choices).map(([choice, n]) => `${choice} ${n}`);
|
|
1204
|
+
if (c.failures) choices.push(`${c.failures} classifier failures`);
|
|
1205
|
+
out.push(...dimLines(ui, ` ${choices.join(' · ')}`, columns));
|
|
1206
|
+
}
|
|
1207
|
+
}
|
|
1208
|
+
if (passed.length) {
|
|
1209
|
+
const sum = (field) => passed.reduce((total, reason) => total + store.passed[reason][field], 0);
|
|
1210
|
+
const total = { requests: sum('requests'), pricedRequests: sum('pricedRequests') };
|
|
1211
|
+
out.push(
|
|
1212
|
+
ui.text(` Not routed ${passed.map((reason) => `${reason} ${store.passed[reason].agents}`).join(' · ')}`),
|
|
1213
|
+
ui.dim(` ${pricedText(`${usd(sum('usd'))} on the model they ran on`, total)}`),
|
|
1214
|
+
);
|
|
1215
|
+
}
|
|
1216
|
+
return out;
|
|
1217
|
+
}
|
|
1218
|
+
|
|
1147
1219
|
function usageTab(ui, config, view, usage, actions, _modelOptions, columns) {
|
|
1148
1220
|
const metrics = usageMetrics(config, view, usage);
|
|
1149
1221
|
const history = view.history ?? [];
|
|
@@ -1178,6 +1250,8 @@ function usageTab(ui, config, view, usage, actions, _modelOptions, columns) {
|
|
|
1178
1250
|
ui.text(' '),
|
|
1179
1251
|
...activityUsage(ui, config, view, actions, columns),
|
|
1180
1252
|
ui.text(' '),
|
|
1253
|
+
...subagentUsage(ui, config, view, columns),
|
|
1254
|
+
ui.text(' '),
|
|
1181
1255
|
ui.head('ESTIMATES · configured list prices'),
|
|
1182
1256
|
ui.text(`Cache hits saved ${dollars(metrics.cacheBenefit)}`),
|
|
1183
1257
|
Number.isFinite(view.estimate?.taxUsd) ? ui.text(`Switch cost ${dollars(view.estimate.taxUsd)}`) : null,
|
package/lib/route.mjs
CHANGED
|
@@ -317,7 +317,7 @@ export function continueRoute(config, loop, { nativeModel, contextTokens, contex
|
|
|
317
317
|
return { ...loop, decision };
|
|
318
318
|
}
|
|
319
319
|
|
|
320
|
-
export function observeResponse(loop, { usage, requestedModel, effort, stopReason, now }) {
|
|
320
|
+
export function observeResponse(config, loop, { usage, requestedModel, effort, stopReason, now }) {
|
|
321
321
|
let next = loop;
|
|
322
322
|
if (stopReason === 'model_context_window_exceeded') {
|
|
323
323
|
next = { ...next, ineligible: [...new Set([...next.ineligible, requestedModel])] };
|
|
@@ -337,7 +337,7 @@ export function observeResponse(loop, { usage, requestedModel, effort, stopReaso
|
|
|
337
337
|
if (sameModel)
|
|
338
338
|
models = {
|
|
339
339
|
...models,
|
|
340
|
-
[costs.cacheKey(usage.model, effort)]: {
|
|
340
|
+
[costs.cacheKey(config, usage.model, effort)]: {
|
|
341
341
|
lastAt: now,
|
|
342
342
|
prefixTokens: usage.cache_read_input_tokens + usage.cache_creation_input_tokens,
|
|
343
343
|
},
|
package/lib/savings.mjs
CHANGED
|
@@ -2,7 +2,7 @@
|
|
|
2
2
|
// the same tokens on the session's own model and effort ("your model"). Counts and dollars only, never text. Pure:
|
|
3
3
|
// the hook feeds each reply and keeps the totals in the view and, per session, in $.store under SAVINGS_PREFIX.
|
|
4
4
|
|
|
5
|
-
import { ratesAt } from './cost.mjs';
|
|
5
|
+
import { effortSharesCache, ratesAt } from './cost.mjs';
|
|
6
6
|
import { HISTORY_SHRINK, isSameModel } from './route.mjs';
|
|
7
7
|
|
|
8
8
|
// Each session keeps its own record under this prefix and its session id: $.store has no atomic update, and Claude
|
|
@@ -59,6 +59,12 @@ export function sessionCacheTtl({ force5m, envTtl, settingTtl, enable1h, subscri
|
|
|
59
59
|
return '5m';
|
|
60
60
|
}
|
|
61
61
|
|
|
62
|
+
// A subagent's prompt-cache lifetime, by Claude Code's rule for requests outside the main conversation: the same order
|
|
63
|
+
// with CLAUDE_CODE_SUBAGENT_PROMPT_CACHE_TTL and `subagentPromptCacheTtl`, and five minutes on a subscription too.
|
|
64
|
+
// Limit: an agent's `experimental.cacheTtl` frontmatter is not visible to a Mod.
|
|
65
|
+
export const subagentCacheTtl = ({ force5m, envTtl, settingTtl, enable1h }) =>
|
|
66
|
+
sessionCacheTtl({ force5m, envTtl, settingTtl, enable1h, subscriber: false });
|
|
67
|
+
|
|
62
68
|
const isCount = (n) => Number.isFinite(n) && n >= 0;
|
|
63
69
|
|
|
64
70
|
// One main reply. `state` is your model's simulated cache: `{ total, at, onYours, model, effort }` after a reply, or
|
|
@@ -87,11 +93,13 @@ export function compareReply(config, state, { usage, served, yours, ttl, now })
|
|
|
87
93
|
const total = counts.input + counts.cacheRead + counts.cacheWrite;
|
|
88
94
|
const [servedSpec, yoursSpec] = [modelSpec(config, served.model), modelSpec(config, yours.model)];
|
|
89
95
|
const sameModel = servedSpec ? servedSpec === yoursSpec : served.model === yours.model;
|
|
90
|
-
const onYours = sameModel && (served.effort ?? null) === (yours.effort ?? null);
|
|
91
96
|
const identity = { model: yoursSpec?.id ?? yours.model, effort: yours.effort ?? null };
|
|
97
|
+
// On a model that keeps one cache across efforts (effortSharesCache), an effort-only difference is the same cache.
|
|
98
|
+
const sharedEffort = effortSharesCache(config, identity.model);
|
|
99
|
+
const onYours = sameModel && (sharedEffort || (served.effort ?? null) === identity.effort);
|
|
92
100
|
const next = { total, at: now, onYours, ...identity };
|
|
93
101
|
// A cache simulated for another model or effort of yours is none of this one's: the new one starts cold.
|
|
94
|
-
const prior = state?.model === identity.model && state.effort === identity.effort ? state : null;
|
|
102
|
+
const prior = state?.model === identity.model && (sharedEffort || state.effort === identity.effort) ? state : null;
|
|
95
103
|
const write = config.cache.writeMultiplier[ttl];
|
|
96
104
|
if (
|
|
97
105
|
!servedSpec ||
|
|
@@ -0,0 +1,280 @@
|
|
|
1
|
+
// Subagent routing: one model per subagent, chosen at agent.spawn before its cache exists, and the counts that show
|
|
2
|
+
// what that choice saves. Pure: the hook passes the spawn input, the classifier's advice and each reply's usage, and
|
|
3
|
+
// keeps the totals in the view and, per session, in $.store under SUBAGENT_PREFIX.
|
|
4
|
+
|
|
5
|
+
import { CLASSIFY } from './config.mjs';
|
|
6
|
+
import { clip } from './facts.mjs';
|
|
7
|
+
import { modelSpec, requestUsd } from './savings.mjs';
|
|
8
|
+
|
|
9
|
+
export const SUBAGENT_PREFIX = 'subagents:v1:';
|
|
10
|
+
// The longest a spawn waits for the classifier. The wait delays the subagent's start, and the client's deadline race
|
|
11
|
+
// sleeps on $.clock, which counts against the hook's 10 s budget (HookBudget in the build types).
|
|
12
|
+
export const SPAWN_DEADLINE_MS = 3000;
|
|
13
|
+
// A spawn of a type its parent loop finished one of this recently counts as a respawn: a proxy for a retry.
|
|
14
|
+
export const RESPAWN_WINDOW_MS = 600_000;
|
|
15
|
+
// Why a spawn passes through unchanged, in the order they are checked.
|
|
16
|
+
// `unlisted`: a built-in router.json does not list, or a type it lists as null. `pinned`: the agent's definition names a
|
|
17
|
+
// model and does not set `modelRouting: auto`. `unknown`: its definition could not be found or read.
|
|
18
|
+
export const PASS_REASONS = ['fork', 'workflow', 'explicit', 'teammate', 'unlisted', 'pinned', 'unknown'];
|
|
19
|
+
// Built-ins that ignore CLAUDE_CODE_SUBAGENT_MODEL unless CLAUDE_CODE_SUBAGENT_MODEL_FORCE is set.
|
|
20
|
+
const OWN_MODEL_BUILTINS = ['Explore', 'Plan'];
|
|
21
|
+
|
|
22
|
+
// The agent definition frontmatter the router reads: `name`, `model` and `modelRouting`, from a YAML block or the
|
|
23
|
+
// one-line JSON object some plugin builds write. Null when the text has no frontmatter. Only top-level scalars are read.
|
|
24
|
+
export function agentFrontmatter(text) {
|
|
25
|
+
const match = /^---\r?\n([\s\S]*?)\r?\n---/.exec(typeof text === 'string' ? text : '');
|
|
26
|
+
if (!match) return null;
|
|
27
|
+
const block = match[1].trim();
|
|
28
|
+
const fields = {};
|
|
29
|
+
if (block.startsWith('{')) {
|
|
30
|
+
try {
|
|
31
|
+
Object.assign(fields, JSON.parse(block));
|
|
32
|
+
} catch {
|
|
33
|
+
return null;
|
|
34
|
+
}
|
|
35
|
+
} else
|
|
36
|
+
for (const line of block.split(/\r?\n/)) {
|
|
37
|
+
const pair = /^([A-Za-z][\w-]*):\s*(.*?)\s*$/.exec(line);
|
|
38
|
+
if (pair) fields[pair[1]] = pair[2].replace(/\s+#.*$/, '').replace(/^(['"])(.*)\1$/, '$2');
|
|
39
|
+
}
|
|
40
|
+
const text_ = (value) => (typeof value === 'string' && value ? value : null);
|
|
41
|
+
return { name: text_(fields.name), model: text_(fields.model), modelRouting: text_(fields.modelRouting) };
|
|
42
|
+
}
|
|
43
|
+
|
|
44
|
+
// Whether a definition lets the router choose its model: no model, `inherit` (the main conversation's model, which
|
|
45
|
+
// the router routes too), or `modelRouting: auto`, where `model` is only what runs without the router.
|
|
46
|
+
export const routableDefinition = (definition) =>
|
|
47
|
+
!definition.model || definition.model === 'inherit' || definition.modelRouting === 'auto';
|
|
48
|
+
|
|
49
|
+
const pluginOf = (spawn) => {
|
|
50
|
+
const provider = spawn.provider?.plugin;
|
|
51
|
+
return typeof provider === 'string' ? provider.split('@')[0] : null;
|
|
52
|
+
};
|
|
53
|
+
|
|
54
|
+
// What router.json lists for this spawn's type: a models key, CLASSIFY or null, or undefined when it does not list
|
|
55
|
+
// it. A key without a colon names a built-in, so it matches only the engine's own agent; a `plugin:name` key matches
|
|
56
|
+
// only that plugin's agent (provider `plugin@marketplace`).
|
|
57
|
+
function listedRoute(config, spawn) {
|
|
58
|
+
const { types } = config.subagents;
|
|
59
|
+
const type = spawn.subagentType;
|
|
60
|
+
if (typeof type !== 'string' || !Object.hasOwn(types, type)) return undefined;
|
|
61
|
+
const owner = type.includes(':') ? type.slice(0, type.indexOf(':')) : 'engine';
|
|
62
|
+
return pluginOf(spawn) === owner ? types[type] : undefined;
|
|
63
|
+
}
|
|
64
|
+
|
|
65
|
+
// How the router may route this spawn's type: `{ route }`, a models key or CLASSIFY, or `{ pass }`, a PASS_REASONS
|
|
66
|
+
// entry. router.json's `types` decide first, a null there excluding the type. An unlisted built-in passes, since its
|
|
67
|
+
// definition is not readable. Any other agent is classified when its `definition` (agentFrontmatter of its file) is
|
|
68
|
+
// routable, and passes when it pins a model or could not be read.
|
|
69
|
+
export function typeRoute(config, spawn, definition = null) {
|
|
70
|
+
const listed = listedRoute(config, spawn);
|
|
71
|
+
if (listed !== undefined) return listed === null ? { pass: 'unlisted' } : { route: listed };
|
|
72
|
+
if (pluginOf(spawn) === 'engine') return { pass: 'unlisted' };
|
|
73
|
+
if (!definition) return { pass: 'unknown' };
|
|
74
|
+
return routableDefinition(definition) ? { route: CLASSIFY } : { pass: 'pinned' };
|
|
75
|
+
}
|
|
76
|
+
|
|
77
|
+
// The reason a spawn keeps the model core gives it, or null when the router may choose one. A fork reads the parent's
|
|
78
|
+
// cache on the parent's model; `model` is the Agent call's own choice; a teammate and a workflow agent are not
|
|
79
|
+
// rewritable (a workflow agent's model rewrite is ignored, experiments/mod-router/results/agent-spawn-probe.json).
|
|
80
|
+
export function passReason(config, spawn, definition = null) {
|
|
81
|
+
if (spawn.fork) return 'fork';
|
|
82
|
+
// Before `explicit`: a workflow agent({ model }) arrives with `model` set, and counts as a workflow agent.
|
|
83
|
+
if (spawn.workflow) return 'workflow';
|
|
84
|
+
if (spawn.model) return 'explicit';
|
|
85
|
+
if (spawn.isTeammate) return 'teammate';
|
|
86
|
+
return typeRoute(config, spawn, definition).pass ?? null;
|
|
87
|
+
}
|
|
88
|
+
|
|
89
|
+
// The task text the classifier sees: the description and the prompt the parent wrote, clipped like a main turn's
|
|
90
|
+
// prompt. Never tool results or history.
|
|
91
|
+
export const spawnPrompt = (config, spawn) =>
|
|
92
|
+
clip(`${spawn.description ?? ''}\n${spawn.prompt ?? ''}`.trim(), config.context.maxTextChars);
|
|
93
|
+
|
|
94
|
+
// The models key a `classify` type runs on from the classifier's advice, or null (no advice: core's model). `heavy`
|
|
95
|
+
// only for a clearly hard task, `light` for exploration or the smallest tier, `standard` for the rest.
|
|
96
|
+
export function classifiedAlias(config, advice) {
|
|
97
|
+
if (!advice) return null;
|
|
98
|
+
const { light, standard, heavy, heavyMass } = config.subagents;
|
|
99
|
+
if ((advice.probabilities?.high ?? 0) >= heavyMass) return heavy;
|
|
100
|
+
const activity = advice.activity;
|
|
101
|
+
const explores =
|
|
102
|
+
activity?.choice === 'explore' && (activity.probabilities?.explore ?? 0) >= config.policy.activityMass;
|
|
103
|
+
return explores || advice.choice === 'micro' ? light : standard;
|
|
104
|
+
}
|
|
105
|
+
|
|
106
|
+
// The model core runs an agent on when the router sets none: its definition's model unless that is `inherit`, else
|
|
107
|
+
// CLAUDE_CODE_SUBAGENT_MODEL, except for the
|
|
108
|
+
// built-ins that ignore it without CLAUDE_CODE_SUBAGENT_MODEL_FORCE, else the parent's model. An estimate: it does not
|
|
109
|
+
// apply the family-alias rule or the availableModels substitution.
|
|
110
|
+
export function coreModelOf(config, spawn, { envModel = null, force = false, definition = null } = {}) {
|
|
111
|
+
const idOf = (model) => (Object.hasOwn(config.models, model) ? config.models[model].id : model);
|
|
112
|
+
const pinned = definition?.model && definition.model !== 'inherit' ? definition.model : null;
|
|
113
|
+
if (pinned && !(force && envModel)) return idOf(pinned);
|
|
114
|
+
const usesEnv = envModel && envModel !== 'inherit' && (force || !OWN_MODEL_BUILTINS.includes(spawn.subagentType));
|
|
115
|
+
return usesEnv ? idOf(envModel) : spawn.parentModel;
|
|
116
|
+
}
|
|
117
|
+
|
|
118
|
+
// One spawn's record while its agent runs: what was decided and the priced replies since the last flush. `pass` is a
|
|
119
|
+
// PASS_REASONS entry or null. `choice` is the models key decided, or 'core' when the decision kept core's model.
|
|
120
|
+
// `actualUsd` prices each reply on the model it ran on; `otherUsd` the same tokens on the other side of the
|
|
121
|
+
// comparison: the decided model in shadow, core's estimated model in on. Null for a pass-through.
|
|
122
|
+
export function spawnRecord({ sessionId, mode, spawn, pass, choice, routedModel, coreModel, failed, respawn }) {
|
|
123
|
+
return {
|
|
124
|
+
sessionId,
|
|
125
|
+
mode,
|
|
126
|
+
type: spawn.subagentType,
|
|
127
|
+
pass,
|
|
128
|
+
choice,
|
|
129
|
+
routedModel,
|
|
130
|
+
coreModel,
|
|
131
|
+
failed: Boolean(failed),
|
|
132
|
+
respawn: Boolean(respawn),
|
|
133
|
+
counted: false,
|
|
134
|
+
requests: 0,
|
|
135
|
+
pricedRequests: 0,
|
|
136
|
+
actualUsd: 0,
|
|
137
|
+
otherUsd: 0,
|
|
138
|
+
};
|
|
139
|
+
}
|
|
140
|
+
|
|
141
|
+
const isCount = (n) => Number.isFinite(n) && n >= 0;
|
|
142
|
+
|
|
143
|
+
// The record with one reply added. A reply is priced only when both its model and the comparison's have a price.
|
|
144
|
+
export function addAgentReply(config, agent, usage, ttl) {
|
|
145
|
+
const counts = {
|
|
146
|
+
input: usage?.input_tokens,
|
|
147
|
+
cacheRead: usage?.cache_read_input_tokens,
|
|
148
|
+
cacheWrite: usage?.cache_creation_input_tokens,
|
|
149
|
+
output: usage?.output_tokens,
|
|
150
|
+
};
|
|
151
|
+
const next = { ...agent, requests: agent.requests + 1 };
|
|
152
|
+
const write = config.cache.writeMultiplier[ttl];
|
|
153
|
+
const actual = modelSpec(config, usage?.model);
|
|
154
|
+
const other = agent.pass ? null : modelSpec(config, agent.mode === 'shadow' ? agent.routedModel : agent.coreModel);
|
|
155
|
+
const priced = (spec) => spec && Number.isFinite(spec.output);
|
|
156
|
+
if (!Object.values(counts).every(isCount) || !Number.isFinite(write) || !priced(actual)) return next;
|
|
157
|
+
if (!agent.pass && !priced(other)) return next;
|
|
158
|
+
next.pricedRequests += 1;
|
|
159
|
+
next.actualUsd += requestUsd(actual, counts, write);
|
|
160
|
+
if (other) next.otherUsd += requestUsd(other, counts, write);
|
|
161
|
+
return next;
|
|
162
|
+
}
|
|
163
|
+
|
|
164
|
+
// A record kept across sessions, one session's or their sum, since `since` (ms), the first agent after a reset.
|
|
165
|
+
// `routed[mode][type]` counts the routed types; `passed[reason]` the pass-throughs, priced on the model they ran on.
|
|
166
|
+
export function emptySubagentStore() {
|
|
167
|
+
return { version: 1, since: null, routed: { shadow: {}, on: {} }, passed: {} };
|
|
168
|
+
}
|
|
169
|
+
|
|
170
|
+
const ROUTED_SUMS = ['agents', 'differs', 'requests', 'pricedRequests', 'coreUsd', 'routedUsd', 'respawns', 'failures'];
|
|
171
|
+
const PASSED_SUMS = ['agents', 'requests', 'pricedRequests', 'usd'];
|
|
172
|
+
const isRecord = (value) => value !== null && typeof value === 'object' && !Array.isArray(value);
|
|
173
|
+
|
|
174
|
+
const emptyRouted = () => ({ ...Object.fromEntries(ROUTED_SUMS.map((sum) => [sum, 0])), choices: {} });
|
|
175
|
+
const emptyPassed = () => Object.fromEntries(PASSED_SUMS.map((sum) => [sum, 0]));
|
|
176
|
+
|
|
177
|
+
// The finished turn's counts of one agent added to a store at `now`: the agent once, on its first flush, then its
|
|
178
|
+
// requests and prices since the last flush.
|
|
179
|
+
export function recordAgent(store, agent, now) {
|
|
180
|
+
if (!agent.requests && agent.counted) return store;
|
|
181
|
+
const first = agent.counted ? 0 : 1;
|
|
182
|
+
const next = { ...store, since: store.since ?? now, routed: { ...store.routed }, passed: { ...store.passed } };
|
|
183
|
+
if (agent.pass) {
|
|
184
|
+
const counts = { ...(next.passed[agent.pass] ?? emptyPassed()) };
|
|
185
|
+
counts.agents += first;
|
|
186
|
+
counts.requests += agent.requests;
|
|
187
|
+
counts.pricedRequests += agent.pricedRequests;
|
|
188
|
+
counts.usd += agent.actualUsd;
|
|
189
|
+
next.passed[agent.pass] = counts;
|
|
190
|
+
return next;
|
|
191
|
+
}
|
|
192
|
+
const byType = { ...next.routed[agent.mode] };
|
|
193
|
+
const counts = { ...(byType[agent.type] ?? emptyRouted()), choices: { ...byType[agent.type]?.choices } };
|
|
194
|
+
const shadow = agent.mode === 'shadow';
|
|
195
|
+
counts.agents += first;
|
|
196
|
+
counts.differs += first && agent.routedModel !== agent.coreModel ? 1 : 0;
|
|
197
|
+
counts.respawns += first && agent.respawn ? 1 : 0;
|
|
198
|
+
counts.failures += first && agent.failed ? 1 : 0;
|
|
199
|
+
if (first) counts.choices[agent.choice] = (counts.choices[agent.choice] ?? 0) + 1;
|
|
200
|
+
counts.requests += agent.requests;
|
|
201
|
+
counts.pricedRequests += agent.pricedRequests;
|
|
202
|
+
counts.coreUsd += shadow ? agent.actualUsd : agent.otherUsd;
|
|
203
|
+
counts.routedUsd += shadow ? agent.otherUsd : agent.actualUsd;
|
|
204
|
+
byType[agent.type] = counts;
|
|
205
|
+
next.routed[agent.mode] = byType;
|
|
206
|
+
return next;
|
|
207
|
+
}
|
|
208
|
+
|
|
209
|
+
// The record after a flush: counted once, nothing pending.
|
|
210
|
+
export const flushedAgent = (agent) => ({
|
|
211
|
+
...agent,
|
|
212
|
+
counted: true,
|
|
213
|
+
requests: 0,
|
|
214
|
+
pricedRequests: 0,
|
|
215
|
+
actualUsd: 0,
|
|
216
|
+
otherUsd: 0,
|
|
217
|
+
});
|
|
218
|
+
|
|
219
|
+
function readCounts(value, sums, withChoices) {
|
|
220
|
+
if (!isRecord(value) || !sums.every((sum) => isCount(value[sum]))) return null;
|
|
221
|
+
const out = Object.fromEntries(sums.map((sum) => [sum, value[sum]]));
|
|
222
|
+
if (!withChoices) return out;
|
|
223
|
+
const choices = isRecord(value.choices) ? value.choices : {};
|
|
224
|
+
out.choices = Object.fromEntries(Object.entries(choices).filter(([, n]) => Number.isSafeInteger(n) && n >= 0));
|
|
225
|
+
return out;
|
|
226
|
+
}
|
|
227
|
+
|
|
228
|
+
function readMap(value, sums, withChoices) {
|
|
229
|
+
const out = {};
|
|
230
|
+
if (!isRecord(value)) return out;
|
|
231
|
+
for (const [key, counts] of Object.entries(value)) {
|
|
232
|
+
const read = readCounts(counts, sums, withChoices);
|
|
233
|
+
if (read) out[key] = read;
|
|
234
|
+
}
|
|
235
|
+
return out;
|
|
236
|
+
}
|
|
237
|
+
|
|
238
|
+
// The stored value with its well-formed entries, else an empty store: a missing, hand-edited or unknown value must not
|
|
239
|
+
// break a turn or the pane.
|
|
240
|
+
export function readSubagentStore(value) {
|
|
241
|
+
if (!isRecord(value) || value.version !== 1 || !(value.since === null || Number.isFinite(value.since)))
|
|
242
|
+
return emptySubagentStore();
|
|
243
|
+
return {
|
|
244
|
+
version: 1,
|
|
245
|
+
since: value.since,
|
|
246
|
+
routed: {
|
|
247
|
+
shadow: readMap(value.routed?.shadow, ROUTED_SUMS, true),
|
|
248
|
+
on: readMap(value.routed?.on, ROUTED_SUMS, true),
|
|
249
|
+
},
|
|
250
|
+
passed: readMap(value.passed, PASSED_SUMS, false),
|
|
251
|
+
};
|
|
252
|
+
}
|
|
253
|
+
|
|
254
|
+
// A record whose first agent came before the last reset at `resetAt` (ms) reads as empty.
|
|
255
|
+
export function subagentsAfterReset(record, resetAt) {
|
|
256
|
+
return Number.isFinite(resetAt) && record.since !== null && record.since < resetAt ? emptySubagentStore() : record;
|
|
257
|
+
}
|
|
258
|
+
|
|
259
|
+
function addInto(target, source, sums, withChoices) {
|
|
260
|
+
for (const [key, counts] of Object.entries(source)) {
|
|
261
|
+
const into = target[key] ?? (withChoices ? emptyRouted() : emptyPassed());
|
|
262
|
+
for (const sum of sums) into[sum] += counts[sum];
|
|
263
|
+
if (withChoices)
|
|
264
|
+
for (const [choice, n] of Object.entries(counts.choices)) into.choices[choice] = (into.choices[choice] ?? 0) + n;
|
|
265
|
+
target[key] = into;
|
|
266
|
+
}
|
|
267
|
+
}
|
|
268
|
+
|
|
269
|
+
// Every session's record since the last reset added up, since the earliest.
|
|
270
|
+
export function mergeSubagentStores(values, resetAt = null) {
|
|
271
|
+
const merged = emptySubagentStore();
|
|
272
|
+
for (const one of values.map((value) => subagentsAfterReset(readSubagentStore(value), resetAt))) {
|
|
273
|
+
const since = [merged.since, one.since].filter(Number.isFinite);
|
|
274
|
+
merged.since = since.length ? Math.min(...since) : null;
|
|
275
|
+
addInto(merged.routed.shadow, one.routed.shadow, ROUTED_SUMS, true);
|
|
276
|
+
addInto(merged.routed.on, one.routed.on, ROUTED_SUMS, true);
|
|
277
|
+
addInto(merged.passed, one.passed, PASSED_SUMS, false);
|
|
278
|
+
}
|
|
279
|
+
return merged;
|
|
280
|
+
}
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@alexeiled/claude-router",
|
|
3
|
-
"version": "1.
|
|
3
|
+
"version": "1.9.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
|
@@ -140,6 +140,34 @@ declare module 'claude-code' {
|
|
|
140
140
|
version: 1;
|
|
141
141
|
since: number | null;
|
|
142
142
|
}
|
|
143
|
+
// Subagent routing counts for one agent type in one mode (lib/subagents.mjs). `differs`: agents the decision moved off
|
|
144
|
+
// core's model; `choices`: agents by models key decided, or 'core'. USD over the priced requests.
|
|
145
|
+
interface RouterSubagentCounts {
|
|
146
|
+
agents: number;
|
|
147
|
+
differs: number;
|
|
148
|
+
requests: number;
|
|
149
|
+
pricedRequests: number;
|
|
150
|
+
coreUsd: number;
|
|
151
|
+
routedUsd: number;
|
|
152
|
+
respawns: number;
|
|
153
|
+
failures: number;
|
|
154
|
+
choices: Record<string, number>;
|
|
155
|
+
}
|
|
156
|
+
// Spawns that passed through for one reason, priced on the model they ran on.
|
|
157
|
+
interface RouterSubagentPassed {
|
|
158
|
+
agents: number;
|
|
159
|
+
requests: number;
|
|
160
|
+
pricedRequests: number;
|
|
161
|
+
usd: number;
|
|
162
|
+
}
|
|
163
|
+
// Kept across sessions, one per session under store key 'subagents:v1:<session id>' or their sum in the view, since
|
|
164
|
+
// the first agent after the last reset (ms).
|
|
165
|
+
interface RouterSubagentStore {
|
|
166
|
+
version: 1;
|
|
167
|
+
since: number | null;
|
|
168
|
+
routed: { shadow: Record<string, RouterSubagentCounts>; on: Record<string, RouterSubagentCounts> };
|
|
169
|
+
passed: Partial<Record<'fork' | 'explicit' | 'teammate' | 'workflow' | 'unlisted', RouterSubagentPassed>>;
|
|
170
|
+
}
|
|
143
171
|
interface RouterView {
|
|
144
172
|
phase: 'ready' | 'choosing' | 'routed' | 'manual' | 'unavailable';
|
|
145
173
|
mode: 'auto' | 'manual';
|
|
@@ -185,6 +213,7 @@ declare module 'claude-code' {
|
|
|
185
213
|
activityMetrics?: RouterActivityMetrics | null;
|
|
186
214
|
savings?: RouterSavingsSession | null;
|
|
187
215
|
savingsStore?: RouterSavingsStore | null;
|
|
216
|
+
subagentStore?: RouterSubagentStore | null;
|
|
188
217
|
configPath?: string | null;
|
|
189
218
|
tuning?: Partial<RouterTuning> | null;
|
|
190
219
|
tuningBase?: RouterTuning | null;
|