@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/hooks/native-router.mjs
CHANGED
|
@@ -21,6 +21,7 @@ import { resolveCredentials } from '../lib/classifier-contract.mjs';
|
|
|
21
21
|
import {
|
|
22
22
|
ACTIVITY_MODES,
|
|
23
23
|
activeClassifier,
|
|
24
|
+
CLASSIFY,
|
|
24
25
|
DEFAULTS,
|
|
25
26
|
editActivity,
|
|
26
27
|
effectiveActivities,
|
|
@@ -79,7 +80,27 @@ import {
|
|
|
79
80
|
SAVINGS_PREFIX,
|
|
80
81
|
SAVINGS_RESET_KEY,
|
|
81
82
|
sessionCacheTtl,
|
|
83
|
+
subagentCacheTtl,
|
|
82
84
|
} from '../lib/savings.mjs';
|
|
85
|
+
import {
|
|
86
|
+
addAgentReply,
|
|
87
|
+
agentFrontmatter,
|
|
88
|
+
classifiedAlias,
|
|
89
|
+
coreModelOf,
|
|
90
|
+
emptySubagentStore,
|
|
91
|
+
flushedAgent,
|
|
92
|
+
mergeSubagentStores,
|
|
93
|
+
passReason,
|
|
94
|
+
RESPAWN_WINDOW_MS,
|
|
95
|
+
readSubagentStore,
|
|
96
|
+
recordAgent,
|
|
97
|
+
SPAWN_DEADLINE_MS,
|
|
98
|
+
SUBAGENT_PREFIX,
|
|
99
|
+
spawnPrompt,
|
|
100
|
+
spawnRecord,
|
|
101
|
+
subagentsAfterReset,
|
|
102
|
+
typeRoute,
|
|
103
|
+
} from '../lib/subagents.mjs';
|
|
83
104
|
import { CLEARED_READINGS, continuationView, healthOf, initialView, responseMetrics } from '../lib/view.mjs';
|
|
84
105
|
|
|
85
106
|
// The engine follows $ only into functions declared in this file, never across an import: every helper that takes $
|
|
@@ -91,6 +112,7 @@ const PANE = 'jev-router';
|
|
|
91
112
|
const PANE_TITLE = 'Router';
|
|
92
113
|
const BAND_DETAIL = 'band:detail';
|
|
93
114
|
const MODE_PREFIX = 'mode:';
|
|
115
|
+
const isSet = (value) => /^(1|true|yes|on)$/i.test(String(value ?? '').trim());
|
|
94
116
|
|
|
95
117
|
// Everything the hooks change between events, in one object `register()` creates and passes to its helpers. Module
|
|
96
118
|
// variables, not $.state: a reload starts them over, and the view is written through to $.state as it changes.
|
|
@@ -129,6 +151,14 @@ function createRouter(options) {
|
|
|
129
151
|
metricsOthers: null,
|
|
130
152
|
// Bumped by Reset activity stats, so a store write that read the counts before the reset skips.
|
|
131
153
|
statsResets: 0,
|
|
154
|
+
// Each spawned agent's record by agentId (spawnRecord), and when each parent loop last finished an agent of a type,
|
|
155
|
+
// for respawns. The subagent totals kept across sessions, held as the savings records are.
|
|
156
|
+
agents: new Map(),
|
|
157
|
+
finished: new Map(),
|
|
158
|
+
// Each agent type's definition frontmatter by provider and type, read once per session (agentDefinition).
|
|
159
|
+
definitions: new Map(),
|
|
160
|
+
subagentsOwn: null,
|
|
161
|
+
subagentsOthers: null,
|
|
132
162
|
};
|
|
133
163
|
}
|
|
134
164
|
|
|
@@ -231,6 +261,32 @@ async function otherMetrics($, sessionId, resetAt) {
|
|
|
231
261
|
return mergeMetrics(await Promise.all(keys.map((key) => $.store.get(key))), resetAt);
|
|
232
262
|
}
|
|
233
263
|
|
|
264
|
+
// This session's subagent record and the last reset, as ownSavings: Reset stats clears it with the same marker.
|
|
265
|
+
async function ownSubagents($, router) {
|
|
266
|
+
const sessionId = await $.session.id();
|
|
267
|
+
const resetAt = await $.store.get(SAVINGS_RESET_KEY);
|
|
268
|
+
if (router.subagentsOwn?.sessionId !== sessionId) {
|
|
269
|
+
const record = readSubagentStore(await $.store.get(`${SUBAGENT_PREFIX}${sessionId}`));
|
|
270
|
+
if (router.subagentsOwn?.sessionId !== sessionId) router.subagentsOwn = { sessionId, record };
|
|
271
|
+
}
|
|
272
|
+
router.subagentsOwn.record = subagentsAfterReset(router.subagentsOwn.record, resetAt);
|
|
273
|
+
return { own: router.subagentsOwn, resetAt };
|
|
274
|
+
}
|
|
275
|
+
|
|
276
|
+
// Every other session's subagent record since the last reset, added up.
|
|
277
|
+
async function otherSubagents($, sessionId, resetAt) {
|
|
278
|
+
const own = `${SUBAGENT_PREFIX}${sessionId}`;
|
|
279
|
+
const keys = (await $.store.keys()).filter((key) => key.startsWith(SUBAGENT_PREFIX) && key !== own);
|
|
280
|
+
return mergeSubagentStores(await Promise.all(keys.map((key) => $.store.get(key))), resetAt);
|
|
281
|
+
}
|
|
282
|
+
|
|
283
|
+
// The view's subagent totals, this session's and the others', from what the router holds; nothing until a read
|
|
284
|
+
// succeeded.
|
|
285
|
+
const subagentView = (router) =>
|
|
286
|
+
router.subagentsOthers
|
|
287
|
+
? { subagentStore: mergeSubagentStores([router.subagentsOthers, router.subagentsOwn?.record]) }
|
|
288
|
+
: {};
|
|
289
|
+
|
|
234
290
|
const metricsView = (router) => mergeMetrics([router.metricsOthers, router.metricsOwn?.record]);
|
|
235
291
|
|
|
236
292
|
// The view's totals kept across sessions, from what the router holds; nothing until a read succeeded.
|
|
@@ -254,6 +310,11 @@ async function storeView($, router) {
|
|
|
254
310
|
const { own, resetAt } = await ownSavings($, router);
|
|
255
311
|
router.savingsOthers = await otherSavings($, own.sessionId, resetAt);
|
|
256
312
|
} catch {}
|
|
313
|
+
try {
|
|
314
|
+
const { own, resetAt } = await ownSubagents($, router);
|
|
315
|
+
router.subagentsOthers = await otherSubagents($, own.sessionId, resetAt);
|
|
316
|
+
Object.assign(out, subagentView(router));
|
|
317
|
+
} catch {}
|
|
257
318
|
return out;
|
|
258
319
|
}
|
|
259
320
|
|
|
@@ -371,6 +432,19 @@ function openKeySettings($) {
|
|
|
371
432
|
$.clock.after(0, () => $.command.run({ command: 'plugin', args: `configure ${$.plugin.name}` }).catch(() => {}));
|
|
372
433
|
}
|
|
373
434
|
|
|
435
|
+
// Whether this session's provider gives each effort its own prompt cache (effortSharesCache in lib/cost.mjs): Amazon
|
|
436
|
+
// Bedrock, Google Cloud, Microsoft Foundry, a custom ANTHROPIC_BASE_URL (it may be a Claude apps gateway) or
|
|
437
|
+
// CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS. A HIPAA configuration is not visible to a Mod. $.env.get takes literal names.
|
|
438
|
+
async function effortSplitsCacheOf($) {
|
|
439
|
+
const flags = [
|
|
440
|
+
await $.env.get('CLAUDE_CODE_USE_BEDROCK'),
|
|
441
|
+
await $.env.get('CLAUDE_CODE_USE_VERTEX'),
|
|
442
|
+
await $.env.get('CLAUDE_CODE_USE_FOUNDRY'),
|
|
443
|
+
await $.env.get('CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS'),
|
|
444
|
+
];
|
|
445
|
+
return flags.some(isSet) || Boolean(await $.env.get('ANTHROPIC_BASE_URL'));
|
|
446
|
+
}
|
|
447
|
+
|
|
374
448
|
async function loadNativeConfig($) {
|
|
375
449
|
for (const source of ['project', 'local']) {
|
|
376
450
|
const settings = await $.settings.read({ source });
|
|
@@ -381,7 +455,7 @@ async function loadNativeConfig($) {
|
|
|
381
455
|
const profile = (await $.env.get('CLAUDE_CONFIG_DIR')) ?? `${home}/.claude`;
|
|
382
456
|
const path = `${profile}/router.json`;
|
|
383
457
|
const userFile = (await $.fs.exists(path)) ? JSON.parse(await $.fs.read(path)) : null;
|
|
384
|
-
return { ...loadConfig({ userFile }), nativePath: path };
|
|
458
|
+
return { ...loadConfig({ userFile }), nativePath: path, effortSplitsCache: await effortSplitsCacheOf($) };
|
|
385
459
|
}
|
|
386
460
|
|
|
387
461
|
// Writes router.json through `change(previousFile)` once the result validates. Returns the new config or an error
|
|
@@ -392,7 +466,7 @@ async function saveConfig($, path, change) {
|
|
|
392
466
|
return { error: 'Not saved: router.json is a symlink. Edit its maintained source instead.' };
|
|
393
467
|
const { config, text } = rewrittenConfig((await $.fs.exists(path)) ? await $.fs.read(path) : null, change);
|
|
394
468
|
await $.fs.write(path, text);
|
|
395
|
-
return { config: { ...config, nativePath: path } };
|
|
469
|
+
return { config: { ...config, nativePath: path, effortSplitsCache: await effortSplitsCacheOf($) } };
|
|
396
470
|
} catch (error) {
|
|
397
471
|
return { error: notSaved(error) };
|
|
398
472
|
}
|
|
@@ -456,7 +530,7 @@ async function* passMain($, e, next, loop, version, nativeModel, reason, router)
|
|
|
456
530
|
const sessionId = await $.session.id();
|
|
457
531
|
const response = yield* next(e);
|
|
458
532
|
if (!next.signal.aborted && (await $.session.id()) === sessionId) {
|
|
459
|
-
const observed = observeResponse(loop, {
|
|
533
|
+
const observed = observeResponse(router.config, loop, {
|
|
460
534
|
usage: response.usage,
|
|
461
535
|
requestedModel: e.model,
|
|
462
536
|
effort: e.effort ?? null,
|
|
@@ -616,7 +690,7 @@ async function publishReply($, router, turnId, response, tier, route, routedUsd)
|
|
|
616
690
|
// A routed reply written to the loop at `loopVersion`, then published: the view's metrics and the routing-vs-your-model
|
|
617
691
|
// totals. A lost write publishes nothing.
|
|
618
692
|
async function observeRouted($, router, { turnId, cfg, loop, loopVersion, request, response, nativeModel }) {
|
|
619
|
-
const observed = observeResponse(loop, {
|
|
693
|
+
const observed = observeResponse(cfg, loop, {
|
|
620
694
|
usage: response.usage,
|
|
621
695
|
requestedModel: request.model,
|
|
622
696
|
effort: request.effort ?? null,
|
|
@@ -789,6 +863,210 @@ async function flushRun($, run) {
|
|
|
789
863
|
} catch {}
|
|
790
864
|
}
|
|
791
865
|
|
|
866
|
+
// The frontmatter of the agent file a spawn starts (agentFrontmatter), or null when it cannot be found or read. Read
|
|
867
|
+
// once per provider and type in a session, and never for a built-in, whose definition is not on disk.
|
|
868
|
+
async function agentDefinition($, router, e) {
|
|
869
|
+
const plugin = e.provider?.plugin;
|
|
870
|
+
if (typeof plugin !== 'string' || plugin === 'engine' || typeof e.subagentType !== 'string') return null;
|
|
871
|
+
const key = `${plugin} ${e.subagentType}`;
|
|
872
|
+
if (!router.definitions.has(key)) router.definitions.set(key, await findDefinition($, plugin, e.subagentType));
|
|
873
|
+
return router.definitions.get(key);
|
|
874
|
+
}
|
|
875
|
+
|
|
876
|
+
// A plugin agent (provider `plugin@marketplace`) is looked up under each install path installed_plugins.json gives
|
|
877
|
+
// that plugin, the files Claude Code itself loads; any other agent under the session's .claude/agents, then the
|
|
878
|
+
// profile's agents. Every match must agree on the model, or the definition is unknown. Limit: a plugin that keeps its
|
|
879
|
+
// agents outside `agents/` reads as unknown, so its agents pass through.
|
|
880
|
+
async function findDefinition($, plugin, type) {
|
|
881
|
+
try {
|
|
882
|
+
const home = await $.env.get('HOME');
|
|
883
|
+
const profile = (await $.env.get('CLAUDE_CONFIG_DIR')) ?? `${home}/.claude`;
|
|
884
|
+
const name = type.slice(type.indexOf(':') + 1);
|
|
885
|
+
const fromPlugin = plugin.includes('@');
|
|
886
|
+
const dirs = fromPlugin
|
|
887
|
+
? (JSON.parse(await $.fs.read(`${profile}/plugins/installed_plugins.json`)).plugins?.[plugin] ?? []).map(
|
|
888
|
+
(entry) => `${entry.installPath}/agents`,
|
|
889
|
+
)
|
|
890
|
+
: [`${await $.session.cwd()}/.claude/agents`, `${profile}/agents`];
|
|
891
|
+
const found = [];
|
|
892
|
+
for (const dir of dirs) {
|
|
893
|
+
if (!(await $.fs.exists(dir))) continue;
|
|
894
|
+
for (const entry of await $.fs.list(dir)) {
|
|
895
|
+
if (entry.kind === 'dir' || !entry.name.endsWith('.md')) continue;
|
|
896
|
+
const definition = agentFrontmatter(await $.fs.read(`${dir}/${entry.name}`));
|
|
897
|
+
if (definition && (definition.name ?? entry.name.slice(0, -3)) === name) found.push(definition);
|
|
898
|
+
}
|
|
899
|
+
// A project agent replaces a user agent of the same name.
|
|
900
|
+
if (found.length && !fromPlugin) break;
|
|
901
|
+
}
|
|
902
|
+
const agree = found.every((d) => d.model === found[0].model && d.modelRouting === found[0].modelRouting);
|
|
903
|
+
return found.length && agree ? found[0] : null;
|
|
904
|
+
} catch {
|
|
905
|
+
return null;
|
|
906
|
+
}
|
|
907
|
+
}
|
|
908
|
+
|
|
909
|
+
// The spawn path's classifier client: a breaker of its own, so spawn failures never pause main-turn routing, and no
|
|
910
|
+
// in-flight slot, so a parent that spawns several agents at once gets an answer for each.
|
|
911
|
+
function spawnClientOf(router, id) {
|
|
912
|
+
const key = `spawn:${id}`;
|
|
913
|
+
if (!router.clients.has(key)) router.clients.set(key, new ClassifierClient({ exclusive: false }));
|
|
914
|
+
return router.clients.get(key);
|
|
915
|
+
}
|
|
916
|
+
|
|
917
|
+
// A listed spawn's model: the models key its type names, or the classifier's pick for a `classify` type from the task
|
|
918
|
+
// text alone. `choice: 'core'` keeps core's model: no advice (`failed`), or a model availableModels blocks.
|
|
919
|
+
async function decideSpawn($, router, cfg, e, definition, signal) {
|
|
920
|
+
let alias = typeRoute(cfg, e, definition).route;
|
|
921
|
+
let failed = false;
|
|
922
|
+
if (alias === CLASSIFY) {
|
|
923
|
+
const entry = activeClassifier(cfg);
|
|
924
|
+
const credentials = await resolveCredentials(entry, (name) => settingOf($, router.options, name));
|
|
925
|
+
// The wait delays the subagent's start, so it is the classifier's deadline capped at SPAWN_DEADLINE_MS.
|
|
926
|
+
const timeoutMs = Math.min(entry.timeoutMs, SPAWN_DEADLINE_MS);
|
|
927
|
+
const result = await spawnClientOf(router, cfg.classifier).ask({
|
|
928
|
+
request: (url, init) => $.http.fetch(url, init),
|
|
929
|
+
sleep: (ms, args) => $.clock.sleep(ms, args),
|
|
930
|
+
config: { ...cfg, classifiers: { ...cfg.classifiers, [cfg.classifier]: { ...entry, timeoutMs } } },
|
|
931
|
+
apiKey: credentials.apiKey,
|
|
932
|
+
endpoint: credentials.endpoint,
|
|
933
|
+
prompt: spawnPrompt(cfg, e),
|
|
934
|
+
turns: [],
|
|
935
|
+
signal,
|
|
936
|
+
});
|
|
937
|
+
alias = classifiedAlias(cfg, result.advice);
|
|
938
|
+
failed = !result.advice;
|
|
939
|
+
}
|
|
940
|
+
// The full id, not an alias: a family alias would resolve to the parent's exact model when the families match.
|
|
941
|
+
const model = alias ? cfg.models[alias].id : null;
|
|
942
|
+
const settings = await $.settings.read().catch(() => ({}));
|
|
943
|
+
if (!model || !isModelAllowed(model, settings.availableModels, e.parentModel))
|
|
944
|
+
return { choice: 'core', model: null, failed };
|
|
945
|
+
return { choice: alias, model, failed };
|
|
946
|
+
}
|
|
947
|
+
|
|
948
|
+
// One model per subagent, chosen before its cache exists. `on` waits for the decision and sends its model, which
|
|
949
|
+
// Claude Code uses in place of the Agent call's `model` and the agent's frontmatter. `shadow` spawns as Claude Code
|
|
950
|
+
// would at once and records the decision once it is in, so it never delays an agent's start. Routing off or
|
|
951
|
+
// unavailable keeps every model Claude Code chooses, and records nothing.
|
|
952
|
+
async function spawnAgent($, router, e, next) {
|
|
953
|
+
const cfg = router.config;
|
|
954
|
+
const mode = cfg.subagentRouting;
|
|
955
|
+
if (mode === 'off') return next(e);
|
|
956
|
+
const view = router.view ?? (await readView($, router));
|
|
957
|
+
if (view.phase === 'unavailable' || (await modeOf($, router, view.mode)) === 'manual') return next(e);
|
|
958
|
+
const definition = await agentDefinition($, router, e);
|
|
959
|
+
const pass = passReason(cfg, e, definition);
|
|
960
|
+
const deciding = pass ? null : decideSpawn($, router, cfg, e, definition, next.signal).catch(() => null);
|
|
961
|
+
const decided = mode === 'on' ? await deciding : null;
|
|
962
|
+
const routed = Boolean(decided?.model);
|
|
963
|
+
const result = await next(routed ? { ...e, model: decided.model } : e);
|
|
964
|
+
if (!result.agentId) return result;
|
|
965
|
+
// In shadow the agent may reply, and even finish, before the decision lands: a pending entry keeps its replies.
|
|
966
|
+
if (mode !== 'on' && deciding !== null)
|
|
967
|
+
router.agents.set(result.agentId, { pending: true, usages: [], finished: false });
|
|
968
|
+
try {
|
|
969
|
+
const decision = mode === 'on' ? decided : await deciding;
|
|
970
|
+
if (pass || decision) await noteSpawn($, router, { cfg, mode, e, pass, decision, routed, result, definition });
|
|
971
|
+
else router.agents.delete(result.agentId);
|
|
972
|
+
} catch {
|
|
973
|
+
if (router.agents.get(result.agentId)?.pending) router.agents.delete(result.agentId);
|
|
974
|
+
}
|
|
975
|
+
return result;
|
|
976
|
+
}
|
|
977
|
+
|
|
978
|
+
// The spawn's record, kept until the session ends. In `on` core's model is an estimate (coreModelOf); otherwise it is
|
|
979
|
+
// the model the agent started on.
|
|
980
|
+
async function noteSpawn($, router, { cfg, mode, e, pass, decision, routed, result, definition }) {
|
|
981
|
+
const parentKey = `${e.parentAgentId ?? 'main'} ${e.subagentType}`;
|
|
982
|
+
const finishedAt = router.finished.get(parentKey);
|
|
983
|
+
const ttl = await subagentTtlOf($).catch(() => null);
|
|
984
|
+
const coreModel = routed
|
|
985
|
+
? coreModelOf(cfg, e, {
|
|
986
|
+
envModel: await $.env.get('CLAUDE_CODE_SUBAGENT_MODEL'),
|
|
987
|
+
force: isSet(await $.env.get('CLAUDE_CODE_SUBAGENT_MODEL_FORCE')),
|
|
988
|
+
definition,
|
|
989
|
+
})
|
|
990
|
+
: result.model;
|
|
991
|
+
const record = spawnRecord({
|
|
992
|
+
sessionId: await $.session.id(),
|
|
993
|
+
mode,
|
|
994
|
+
spawn: e,
|
|
995
|
+
pass,
|
|
996
|
+
choice: decision?.choice ?? null,
|
|
997
|
+
routedModel: decision?.model ?? result.model,
|
|
998
|
+
coreModel,
|
|
999
|
+
failed: decision?.failed,
|
|
1000
|
+
respawn: Number.isFinite(finishedAt) && Date.now() - finishedAt < RESPAWN_WINDOW_MS,
|
|
1001
|
+
});
|
|
1002
|
+
// Read after the last await, so no reply lands in the pending entry after its replay.
|
|
1003
|
+
const pending = router.agents.get(result.agentId);
|
|
1004
|
+
const replies = pending?.pending ? pending.usages : [];
|
|
1005
|
+
router.agents.set(
|
|
1006
|
+
result.agentId,
|
|
1007
|
+
replies.reduce((agent, usage) => addAgentReply(cfg, agent, usage, ttl), { ...record, parentKey }),
|
|
1008
|
+
);
|
|
1009
|
+
if (pending?.finished) await finishAgent($, router, result.agentId);
|
|
1010
|
+
}
|
|
1011
|
+
|
|
1012
|
+
// A subagent's prompt-cache lifetime, by Claude Code's rule for requests outside the main conversation.
|
|
1013
|
+
async function subagentTtlOf($) {
|
|
1014
|
+
const settings = await $.settings.read();
|
|
1015
|
+
return subagentCacheTtl({
|
|
1016
|
+
force5m: await $.env.get('FORCE_PROMPT_CACHING_5M'),
|
|
1017
|
+
envTtl: await $.env.get('CLAUDE_CODE_SUBAGENT_PROMPT_CACHE_TTL'),
|
|
1018
|
+
settingTtl: settings.subagentPromptCacheTtl,
|
|
1019
|
+
enable1h: await $.env.get('ENABLE_PROMPT_CACHING_1H'),
|
|
1020
|
+
});
|
|
1021
|
+
}
|
|
1022
|
+
|
|
1023
|
+
// A subagent's step runs exactly as Claude Code sent it: a model switch between its steps would rewrite its context
|
|
1024
|
+
// cold. Its reply is added to its spawn record; the record never breaks the step.
|
|
1025
|
+
async function* stepAgent($, router, e, next) {
|
|
1026
|
+
const response = yield* next(e);
|
|
1027
|
+
if (router.agents.has(e.agentId) && response?.usage) {
|
|
1028
|
+
try {
|
|
1029
|
+
const ttl = await subagentTtlOf($);
|
|
1030
|
+
const agent = router.agents.get(e.agentId);
|
|
1031
|
+
if (agent?.pending) agent.usages.push(response.usage);
|
|
1032
|
+
else if (agent) router.agents.set(e.agentId, addAgentReply(router.config, agent, response.usage, ttl));
|
|
1033
|
+
} catch {}
|
|
1034
|
+
}
|
|
1035
|
+
return response;
|
|
1036
|
+
}
|
|
1037
|
+
|
|
1038
|
+
// A subagent's turn ended: its counts since the last flush go to this session's record kept across sessions.
|
|
1039
|
+
async function finishAgent($, router, agentId) {
|
|
1040
|
+
const agent = router.agents.get(agentId);
|
|
1041
|
+
if (!agent) return;
|
|
1042
|
+
// A pending agent is flushed when its decision lands (noteSpawn).
|
|
1043
|
+
if (agent.pending) {
|
|
1044
|
+
agent.finished = true;
|
|
1045
|
+
return;
|
|
1046
|
+
}
|
|
1047
|
+
router.finished.set(agent.parentKey, Date.now());
|
|
1048
|
+
router.agents.set(agentId, flushedAgent(agent));
|
|
1049
|
+
await flushSubagents($, router, [agent]);
|
|
1050
|
+
}
|
|
1051
|
+
|
|
1052
|
+
// Agents' counts added to this session's record, with the guard flushSavings uses: counts read before a reset are not
|
|
1053
|
+
// written back. Stats never break a turn: a failed read or write loses these counts.
|
|
1054
|
+
async function flushSubagents($, router, agents) {
|
|
1055
|
+
try {
|
|
1056
|
+
const resets = router.statsResets;
|
|
1057
|
+
const { own, resetAt } = await ownSubagents($, router);
|
|
1058
|
+
const mine = agents.filter((agent) => agent.sessionId === own.sessionId);
|
|
1059
|
+
if (!mine.length) return;
|
|
1060
|
+
if (!router.subagentsOthers || subagentsAfterReset(router.subagentsOthers, resetAt) !== router.subagentsOthers)
|
|
1061
|
+
router.subagentsOthers = await otherSubagents($, own.sessionId, resetAt);
|
|
1062
|
+
if (router.statsResets !== resets) return;
|
|
1063
|
+
const now = Date.now();
|
|
1064
|
+
own.record = mine.reduce((record, agent) => recordAgent(record, agent, now), own.record);
|
|
1065
|
+
await $.store.set(`${SUBAGENT_PREFIX}${own.sessionId}`, own.record);
|
|
1066
|
+
if (router.statsResets === resets) await updateView($, router, subagentView(router));
|
|
1067
|
+
} catch {}
|
|
1068
|
+
}
|
|
1069
|
+
|
|
792
1070
|
// The pane's handlers. `view` is the view the pane was drawn from; a handler reads `router.view` first, which holds
|
|
793
1071
|
// any press since.
|
|
794
1072
|
function paneActions($, router, view) {
|
|
@@ -944,6 +1222,7 @@ function paneActions($, router, view) {
|
|
|
944
1222
|
router.run = null;
|
|
945
1223
|
router.afterDown = null;
|
|
946
1224
|
router.turnSavings.clear();
|
|
1225
|
+
for (const [id, agent] of router.agents) if (!agent.pending) router.agents.set(id, flushedAgent(agent));
|
|
947
1226
|
const clear = (key, value) =>
|
|
948
1227
|
$.store
|
|
949
1228
|
.set(key, value)
|
|
@@ -954,14 +1233,16 @@ function paneActions($, router, view) {
|
|
|
954
1233
|
// Written first, so a session still holding its record from before the reset drops it, unless that record's
|
|
955
1234
|
// first reading has the reset's millisecond or the clock moved back across the reset.
|
|
956
1235
|
await $.store.set(SAVINGS_RESET_KEY, Date.now());
|
|
957
|
-
const keys = (await $.store.keys()).filter(
|
|
958
|
-
|
|
1236
|
+
const keys = (await $.store.keys()).filter((key) =>
|
|
1237
|
+
[SAVINGS_PREFIX, METRICS_PREFIX, SUBAGENT_PREFIX].some((prefix) => key.startsWith(prefix)),
|
|
959
1238
|
);
|
|
960
1239
|
await Promise.all(keys.map((key) => $.store.delete(key)));
|
|
961
1240
|
router.savingsOwn = null;
|
|
962
1241
|
router.savingsOthers = emptySavingsStore();
|
|
963
1242
|
router.metricsOwn = null;
|
|
964
1243
|
router.metricsOthers = emptyMetrics();
|
|
1244
|
+
router.subagentsOwn = null;
|
|
1245
|
+
router.subagentsOthers = emptySubagentStore();
|
|
965
1246
|
return true;
|
|
966
1247
|
};
|
|
967
1248
|
const [stats, records] = await Promise.all([clear(STORE_KEY, emptyStore()), clearRecords().catch(() => false)]);
|
|
@@ -969,7 +1250,9 @@ function paneActions($, router, view) {
|
|
|
969
1250
|
activityStats: null,
|
|
970
1251
|
savingsBy: {},
|
|
971
1252
|
...(stats ? { activityStore: emptyStore() } : {}),
|
|
972
|
-
...(records
|
|
1253
|
+
...(records
|
|
1254
|
+
? { activityMetrics: emptyMetrics(), savingsStore: emptySavingsStore(), subagentStore: emptySubagentStore() }
|
|
1255
|
+
: {}),
|
|
973
1256
|
notice:
|
|
974
1257
|
stats && records
|
|
975
1258
|
? 'Stats reset: activity and routing vs your model, this session and saved.'
|
|
@@ -1027,10 +1310,47 @@ function paneActions($, router, view) {
|
|
|
1027
1310
|
};
|
|
1028
1311
|
}
|
|
1029
1312
|
|
|
1313
|
+
// The session's turns, open run and running agents end with it; the view starts the next session from the counts kept
|
|
1314
|
+
// across sessions.
|
|
1315
|
+
async function endSession($, router) {
|
|
1316
|
+
for (const controller of router.controllers) controller.abort();
|
|
1317
|
+
router.decisions.clear();
|
|
1318
|
+
router.prompts.clear();
|
|
1319
|
+
router.turnConfigs.clear();
|
|
1320
|
+
router.turnActivities.clear();
|
|
1321
|
+
router.turnSavings.clear();
|
|
1322
|
+
const run = router.run;
|
|
1323
|
+
router.run = null;
|
|
1324
|
+
router.afterDown = null;
|
|
1325
|
+
if (run) await flushRun($, run);
|
|
1326
|
+
// Agents still running when the session ends: what they did so far is counted.
|
|
1327
|
+
const agents = [...router.agents.values()];
|
|
1328
|
+
router.agents.clear();
|
|
1329
|
+
router.finished.clear();
|
|
1330
|
+
await flushSubagents($, router, agents);
|
|
1331
|
+
router.view = {
|
|
1332
|
+
...initialView(router.view?.nativeModel ?? ''),
|
|
1333
|
+
// The effort carries over /clear until the next turn reads it again, so "your model" keeps its effort.
|
|
1334
|
+
nativeEffort: router.view?.nativeEffort ?? null,
|
|
1335
|
+
mode: 'auto',
|
|
1336
|
+
credentials: router.view?.credentials ?? null,
|
|
1337
|
+
// Counts kept across sessions: the next session starts from them.
|
|
1338
|
+
activityStore: router.view?.activityStore ?? null,
|
|
1339
|
+
activityMetrics: router.view?.activityMetrics ?? null,
|
|
1340
|
+
savingsStore: router.view?.savingsStore ?? null,
|
|
1341
|
+
subagentStore: router.view?.subagentStore ?? null,
|
|
1342
|
+
health: healthOf(clientOf(router, router.config.classifier), router.config.classifier),
|
|
1343
|
+
configPath: router.config.nativePath,
|
|
1344
|
+
phase: router.view?.phase === 'unavailable' ? 'unavailable' : 'ready',
|
|
1345
|
+
error: router.view?.phase === 'unavailable' ? router.view.error : null,
|
|
1346
|
+
};
|
|
1347
|
+
}
|
|
1348
|
+
|
|
1030
1349
|
export function register(on, options) {
|
|
1031
1350
|
const router = createRouter(options);
|
|
1032
1351
|
|
|
1033
1352
|
on('session.start', async ($, e, next) => {
|
|
1353
|
+
router.definitions.clear();
|
|
1034
1354
|
await $.command.register({
|
|
1035
1355
|
name: 'router',
|
|
1036
1356
|
description: 'Open the Router pane, or switch routing: auto, off, pin <tier>, activities <mode>.',
|
|
@@ -1105,8 +1425,14 @@ export function register(on, options) {
|
|
|
1105
1425
|
return next(e);
|
|
1106
1426
|
});
|
|
1107
1427
|
|
|
1428
|
+
// A hook failure spawns the agent as Claude Code would; next(e) replays a spawn already made. agent.spawn and a
|
|
1429
|
+
// catchable on() are in the 2.1.293 build types, not checked on 2.1.289: an engine without them still loads routing.
|
|
1430
|
+
try {
|
|
1431
|
+
on('agent.spawn', ($, e, next) => spawnAgent($, router, e, next)).catch((_$, e, next) => next(e));
|
|
1432
|
+
} catch {}
|
|
1433
|
+
|
|
1108
1434
|
on('turn.step', async function* ($, e, next) {
|
|
1109
|
-
if (e.agentId) return yield*
|
|
1435
|
+
if (e.agentId) return yield* stepAgent($, router, e, next);
|
|
1110
1436
|
const cfg = router.turnConfigs.get(e.turnId) ?? router.config;
|
|
1111
1437
|
const sessionId = await $.session.id();
|
|
1112
1438
|
const nativeModel = await $.session.model();
|
|
@@ -1179,6 +1505,10 @@ export function register(on, options) {
|
|
|
1179
1505
|
});
|
|
1180
1506
|
|
|
1181
1507
|
on('turn.complete', async ($, e, next) => {
|
|
1508
|
+
if (e.agentId) {
|
|
1509
|
+
await finishAgent($, router, e.agentId);
|
|
1510
|
+
return next(e);
|
|
1511
|
+
}
|
|
1182
1512
|
router.turnConfigs.delete(e.turnId);
|
|
1183
1513
|
router.turnControllers.get(e.turnId)?.abort();
|
|
1184
1514
|
if (router.view?.activeTurnId === e.turnId && router.view.phase === 'choosing') {
|
|
@@ -1214,31 +1544,7 @@ export function register(on, options) {
|
|
|
1214
1544
|
});
|
|
1215
1545
|
|
|
1216
1546
|
on('session.end', async ($, e, next) => {
|
|
1217
|
-
|
|
1218
|
-
router.decisions.clear();
|
|
1219
|
-
router.prompts.clear();
|
|
1220
|
-
router.turnConfigs.clear();
|
|
1221
|
-
router.turnActivities.clear();
|
|
1222
|
-
router.turnSavings.clear();
|
|
1223
|
-
const run = router.run;
|
|
1224
|
-
router.run = null;
|
|
1225
|
-
router.afterDown = null;
|
|
1226
|
-
if (run) await flushRun($, run);
|
|
1227
|
-
router.view = {
|
|
1228
|
-
...initialView(router.view?.nativeModel ?? ''),
|
|
1229
|
-
// The effort carries over /clear until the next turn reads it again, so "your model" keeps its effort.
|
|
1230
|
-
nativeEffort: router.view?.nativeEffort ?? null,
|
|
1231
|
-
mode: 'auto',
|
|
1232
|
-
credentials: router.view?.credentials ?? null,
|
|
1233
|
-
// Counts kept across sessions: the next session starts from them.
|
|
1234
|
-
activityStore: router.view?.activityStore ?? null,
|
|
1235
|
-
activityMetrics: router.view?.activityMetrics ?? null,
|
|
1236
|
-
savingsStore: router.view?.savingsStore ?? null,
|
|
1237
|
-
health: healthOf(clientOf(router, router.config.classifier), router.config.classifier),
|
|
1238
|
-
configPath: router.config.nativePath,
|
|
1239
|
-
phase: router.view?.phase === 'unavailable' ? 'unavailable' : 'ready',
|
|
1240
|
-
error: router.view?.phase === 'unavailable' ? router.view.error : null,
|
|
1241
|
-
};
|
|
1547
|
+
await endSession($, router);
|
|
1242
1548
|
return next(e);
|
|
1243
1549
|
});
|
|
1244
1550
|
|
package/lib/band.mjs
CHANGED
|
@@ -271,7 +271,16 @@ function hoverSegments(view, actions, routing) {
|
|
|
271
271
|
export function renderBand({ Box, Text, Button }, config, view, usage, { columns, agentId }, actions) {
|
|
272
272
|
const draw = (p) => (p.button ? Button(p.button) : Text({ ...p.style, children: p.text }));
|
|
273
273
|
const row = (parts) => Box({ children: parts.map(draw) });
|
|
274
|
-
|
|
274
|
+
// A subagent's model is chosen once, at spawn, and never changes between its steps.
|
|
275
|
+
if (agentId)
|
|
276
|
+
return row([
|
|
277
|
+
part(
|
|
278
|
+
config.subagentRouting === 'on'
|
|
279
|
+
? '○ Router · subagent model chosen at spawn'
|
|
280
|
+
: '○ Router · subagents keep their own model',
|
|
281
|
+
{ dimColor: true },
|
|
282
|
+
),
|
|
283
|
+
]);
|
|
275
284
|
const kept = fitSegments(bandSegments(config, view, usage, actions), Math.max(0, columns - ROUTER_BUTTON));
|
|
276
285
|
const line = kept.flatMap((s, i) => (i ? [part(SEPARATOR, { dimColor: true }), ...s.parts] : s.parts));
|
|
277
286
|
line.push(part(' '), button({ key: 'details', label: 'Router', plain: true, onPress: actions.open }));
|
|
@@ -19,10 +19,13 @@ class AdviceError extends Error {
|
|
|
19
19
|
}
|
|
20
20
|
}
|
|
21
21
|
|
|
22
|
-
// Owned by one Mod activation. It survives history resets; the host cancels its work on unload.
|
|
22
|
+
// Owned by one Mod activation. It survives history resets; the host cancels its work on unload. An exclusive client
|
|
23
|
+
// (the main turn's) answers `busy` while a request is in flight, so a late answer never overlaps the next turn's; the
|
|
24
|
+
// spawn path's client is not exclusive, so a parent that spawns several agents at once gets an answer for each.
|
|
23
25
|
export class ClassifierClient {
|
|
24
|
-
constructor({ now = Date.now, health = null } = {}) {
|
|
26
|
+
constructor({ now = Date.now, health = null, exclusive = true } = {}) {
|
|
25
27
|
this.now = now;
|
|
28
|
+
this.exclusive = exclusive;
|
|
26
29
|
this.pending = null;
|
|
27
30
|
this.active = false;
|
|
28
31
|
this.restore(health);
|
|
@@ -43,7 +46,7 @@ export class ClassifierClient {
|
|
|
43
46
|
if (!endpoint) return { advice: null, error: 'missing-account' };
|
|
44
47
|
if (signal?.aborted) return { advice: null, error: 'cancelled' };
|
|
45
48
|
if (this.now() < this.pausedUntil) return { advice: null, error: 'paused' };
|
|
46
|
-
if (this.active || this.pending) return { advice: null, error: 'busy' };
|
|
49
|
+
if (this.exclusive && (this.active || this.pending)) return { advice: null, error: 'busy' };
|
|
47
50
|
this.active = true;
|
|
48
51
|
try {
|
|
49
52
|
const advice = await this.complete({ request, sleep, config, apiKey, endpoint, prompt, turns, signal });
|
package/lib/config.mjs
CHANGED
|
@@ -8,6 +8,11 @@ export const ACTIVITY_VALUES = [...ACTIVITIES, 'uncertain'];
|
|
|
8
8
|
// `off` asks nothing new and routes as 1.5; `shadow` asks and records but keeps the 1.5 route; `on`, the default since
|
|
9
9
|
// 1.7, applies overrides.
|
|
10
10
|
export const ACTIVITY_MODES = ['off', 'shadow', 'on'];
|
|
11
|
+
// `subagentRouting` takes the same modes: `off` asks and records nothing, `shadow` decides and records but keeps core's
|
|
12
|
+
// model, `on` applies the decision at agent.spawn.
|
|
13
|
+
export const SUBAGENT_MODES = ACTIVITY_MODES;
|
|
14
|
+
// A `subagents.types` value that asks the classifier instead of naming a model.
|
|
15
|
+
export const CLASSIFY = 'classify';
|
|
11
16
|
const SONNET_HIGH = { model: 'sonnet', effort: 'high' };
|
|
12
17
|
export const DEFAULTS = {
|
|
13
18
|
baselineTier: 'low',
|
|
@@ -38,6 +43,20 @@ export const DEFAULTS = {
|
|
|
38
43
|
review: { low: SONNET_HIGH },
|
|
39
44
|
ops: { medium: { model: 'haiku', effort: 'high' } },
|
|
40
45
|
},
|
|
46
|
+
// Subagents get one model at agent.spawn, never between their steps. An agent whose definition names no model, says
|
|
47
|
+
// `inherit`, or sets `modelRouting: auto` gets `light`, `standard` or `heavy` from the classifier; a pinned one keeps
|
|
48
|
+
// its model. `types` overrides by agent type: a models key, `classify`, or null to never route it. A key without a
|
|
49
|
+
// colon matches only the built-in of that name, whose definition is not readable, so only the listed built-ins route.
|
|
50
|
+
// A listed type is routed even if it pins a model. docs/plans/2026-10-10-subagent-routing-plan.md.
|
|
51
|
+
subagentRouting: 'on',
|
|
52
|
+
subagents: {
|
|
53
|
+
types: { Explore: 'haiku', Plan: CLASSIFY, 'general-purpose': CLASSIFY },
|
|
54
|
+
light: 'haiku',
|
|
55
|
+
standard: 'sonnet',
|
|
56
|
+
heavy: 'opus',
|
|
57
|
+
// The classifier's probability of `high` a task needs to run on `heavy`.
|
|
58
|
+
heavyMass: 0.8,
|
|
59
|
+
},
|
|
41
60
|
// `id` selects the native model. List prices in USD per million tokens; `cacheRead` is absolute,
|
|
42
61
|
// not a multiplier (Opus 5.5 reads at 0.05x input, the rest at the standard 0.1x). `longContext` multiplies every
|
|
43
62
|
// rate of a request whose prompt (input, cache read and cache write) is over `above` tokens: Haiku 5.5 lists its
|
|
@@ -426,7 +445,7 @@ function checkShape(file) {
|
|
|
426
445
|
if (file && typeof file === 'object' && Object.hasOwn(file, 'jev'))
|
|
427
446
|
throw new Error(`router.json uses the 1.1 jev section; ${MIGRATION_HINT}`);
|
|
428
447
|
checkObject(file, 'router.json', Object.keys(DEFAULTS));
|
|
429
|
-
const { routes, activities, models, cache, policy, classifiers, context } = file;
|
|
448
|
+
const { routes, activities, models, cache, policy, classifiers, context, subagents } = file;
|
|
430
449
|
if (routes !== undefined) {
|
|
431
450
|
checkObject(routes, 'routes', TIERS);
|
|
432
451
|
for (const [tier, route] of Object.entries(routes)) checkObject(route, `routes.${tier}`, ROUTE_KEYS);
|
|
@@ -459,6 +478,10 @@ function checkShape(file) {
|
|
|
459
478
|
for (const [id, entry] of Object.entries(classifiers)) checkObject(entry, `classifiers.${id}`, CLASSIFIER_KEYS);
|
|
460
479
|
}
|
|
461
480
|
if (context !== undefined) checkObject(context, 'context', Object.keys(DEFAULTS.context));
|
|
481
|
+
if (subagents !== undefined) {
|
|
482
|
+
checkObject(subagents, 'subagents', Object.keys(DEFAULTS.subagents));
|
|
483
|
+
if (subagents.types !== undefined) checkObject(subagents.types, 'subagents.types');
|
|
484
|
+
}
|
|
462
485
|
}
|
|
463
486
|
|
|
464
487
|
// `allowed` null: an open map.
|
|
@@ -518,6 +541,19 @@ function validate(config) {
|
|
|
518
541
|
for (const [id, entry] of Object.entries(config.classifiers)) validateClassifier(`classifiers.${id}`, entry);
|
|
519
542
|
if (typeof config.classifier !== 'string' || !Object.hasOwn(config.classifiers, config.classifier))
|
|
520
543
|
throw new Error('classifier is not in classifiers');
|
|
544
|
+
if (!SUBAGENT_MODES.includes(config.subagentRouting))
|
|
545
|
+
throw new Error(`subagentRouting must be one of ${SUBAGENT_MODES.join(', ')}`);
|
|
546
|
+
const { subagents } = config;
|
|
547
|
+
for (const [type, route] of Object.entries(subagents.types)) {
|
|
548
|
+
if (route !== null && route !== CLASSIFY && !(typeof route === 'string' && Object.hasOwn(config.models, route)))
|
|
549
|
+
throw new Error(`subagents.types.${type} must be a models key, ${CLASSIFY} or null`);
|
|
550
|
+
}
|
|
551
|
+
for (const field of ['light', 'standard', 'heavy']) {
|
|
552
|
+
if (!(typeof subagents[field] === 'string' && Object.hasOwn(config.models, subagents[field])))
|
|
553
|
+
throw new Error(`subagents.${field} is not in models`);
|
|
554
|
+
}
|
|
555
|
+
if (!(isNumber(subagents.heavyMass, 0) && subagents.heavyMass <= 1))
|
|
556
|
+
throw new Error('subagents.heavyMass must be between 0 and 1');
|
|
521
557
|
for (const field of ['recentTurns', 'maxTextChars']) {
|
|
522
558
|
if (!isNumber(context[field], 1, { integer: true })) throw new Error(`context.${field} must be a positive integer`);
|
|
523
559
|
}
|
package/lib/cost.mjs
CHANGED
|
@@ -1,7 +1,18 @@
|
|
|
1
1
|
import { EFFORTS, routeSpec } from './config.mjs';
|
|
2
2
|
|
|
3
|
-
|
|
4
|
-
|
|
3
|
+
// Models that keep one prompt cache across effort levels with an API key or a Claude subscription
|
|
4
|
+
// (code.claude.com/docs/en/prompt-caching, "Changing effort level"). A dated snapshot or a `[1m]` suffix is the same
|
|
5
|
+
// model. `config.effortSplitsCache`, set by the hook from the session's provider, gives every effort its own cache.
|
|
6
|
+
const EFFORT_SHARED_CACHE = ['claude-opus-5-5', 'claude-sonnet-5-5', 'claude-haiku-5-5', 'claude-fable-5-1'];
|
|
7
|
+
|
|
8
|
+
export function effortSharesCache(config, modelId) {
|
|
9
|
+
if (config.effortSplitsCache || typeof modelId !== 'string') return false;
|
|
10
|
+
const bare = modelId.replace(/\[[^\]]*\]$/, '').replace(/-\d{8}$/, '');
|
|
11
|
+
return EFFORT_SHARED_CACHE.includes(bare);
|
|
12
|
+
}
|
|
13
|
+
|
|
14
|
+
export function cacheKey(config, modelId, effort) {
|
|
15
|
+
return effort && !effortSharesCache(config, modelId) ? `${modelId}@${effort}` : modelId;
|
|
5
16
|
}
|
|
6
17
|
|
|
7
18
|
export function clampEffort(wanted, supported) {
|
|
@@ -38,7 +49,7 @@ export function routeEffort(config, route, sentEffort) {
|
|
|
38
49
|
}
|
|
39
50
|
|
|
40
51
|
export function routeCacheKey(config, route, sentEffort) {
|
|
41
|
-
return cacheKey(routeSpec(config, route).id, routeEffort(config, route, sentEffort));
|
|
52
|
+
return cacheKey(config, routeSpec(config, route).id, routeEffort(config, route, sentEffort));
|
|
42
53
|
}
|
|
43
54
|
|
|
44
55
|
export function isWarm(state, now, cache) {
|