@alexeiled/claude-router 1.24.0 → 1.25.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 +44 -0
- package/README.md +39 -7
- package/docs/architecture.md +27 -4
- package/docs/configuration.md +23 -14
- package/docs/evaluation.md +3 -3
- package/docs/native-router.md +11 -3
- package/docs/router-band.svg +124 -133
- package/docs/router-pane-classifier.svg +24 -23
- package/docs/router-pane-now.svg +9 -7
- package/docs/router-pane-policy.svg +4 -4
- package/docs/router-pane-routes.svg +8 -8
- package/docs/router-pane-usage-whatif.svg +14 -14
- package/docs/router-pane-usage.svg +20 -20
- package/docs/routing-modes.md +10 -8
- package/docs/user-guide.md +70 -17
- package/hooks/native-router.mjs +333 -80
- package/lib/activity-stats.mjs +23 -4
- package/lib/activity.mjs +7 -5
- package/lib/auto-engine.mjs +13 -6
- package/lib/auto-route.mjs +10 -4
- package/lib/band.mjs +35 -440
- package/lib/classifier-client.mjs +12 -8
- package/lib/config-file.mjs +7 -2
- package/lib/config.mjs +24 -9
- package/lib/cost.mjs +5 -1
- package/lib/costs.mjs +4 -2
- package/lib/decisions.mjs +13 -9
- package/lib/display.mjs +69 -20
- package/lib/facts.mjs +3 -0
- package/lib/modes.mjs +8 -4
- package/lib/panel.mjs +75 -2167
- package/lib/policy.mjs +7 -6
- package/lib/replay-trace.mjs +5 -2
- package/lib/replay.mjs +7 -1
- package/lib/route-line.mjs +46 -0
- package/lib/route.mjs +21 -16
- package/lib/savings.mjs +14 -3
- package/lib/subagents.mjs +41 -11
- package/lib/subcommands.mjs +60 -0
- package/lib/ui/fallback.mjs +22 -0
- package/lib/ui/graphical/band.mjs +256 -0
- package/lib/ui/graphical/charts.mjs +163 -0
- package/lib/ui/graphical/classifier.mjs +153 -0
- package/lib/ui/graphical/frame.mjs +227 -0
- package/lib/ui/graphical/kit.mjs +156 -0
- package/lib/ui/graphical/meter.mjs +25 -0
- package/lib/ui/graphical/now.mjs +353 -0
- package/lib/ui/graphical/policy.mjs +56 -0
- package/lib/ui/graphical/routes.mjs +264 -0
- package/lib/ui/graphical/squares.mjs +29 -0
- package/lib/ui/graphical/usage.mjs +376 -0
- package/lib/ui/model/band.mjs +439 -0
- package/lib/ui/model/classifier.mjs +308 -0
- package/lib/ui/model/draft.mjs +62 -0
- package/lib/ui/model/format.mjs +41 -0
- package/lib/ui/model/frame.mjs +359 -0
- package/lib/ui/model/now.mjs +390 -0
- package/lib/ui/model/policy.mjs +194 -0
- package/lib/ui/model/routes.mjs +392 -0
- package/lib/ui/model/usage-agents.mjs +311 -0
- package/lib/ui/model/usage-breakdown.mjs +237 -0
- package/lib/ui/model/usage-shared.mjs +58 -0
- package/lib/ui/model/usage.mjs +330 -0
- package/lib/ui/terminal/band.mjs +220 -0
- package/lib/ui/terminal/classifier.mjs +142 -0
- package/lib/ui/terminal/frame.mjs +169 -0
- package/lib/ui/terminal/kit.mjs +133 -0
- package/lib/ui/terminal/now.mjs +300 -0
- package/lib/ui/terminal/policy.mjs +52 -0
- package/lib/ui/terminal/routes.mjs +167 -0
- package/lib/ui/terminal/usage.mjs +363 -0
- package/lib/ui/terminal/wrap.mjs +37 -0
- package/lib/ui/tokens.mjs +106 -0
- package/lib/usage.mjs +5 -5
- package/lib/view.mjs +5 -2
- package/package.json +3 -2
- package/types/index.d.ts +15 -0
package/lib/policy.mjs
CHANGED
|
@@ -35,15 +35,15 @@ export function decide({
|
|
|
35
35
|
const next = { ...state, turn: state.turn + 1, votes: [...state.votes] };
|
|
36
36
|
const incumbent = facts.lastRoute && TIERS.includes(facts.lastRoute) ? facts.lastRoute : baseline;
|
|
37
37
|
const current = incumbentRoute ?? routeFor(incumbent);
|
|
38
|
-
const stay = (reason, estimate = null) => result(incumbent, reason, next, estimate);
|
|
38
|
+
const stay = (reason, estimate = /** @type {object | null} */ (null)) => result(incumbent, reason, next, estimate);
|
|
39
39
|
|
|
40
|
-
const
|
|
41
|
-
if (
|
|
40
|
+
const escalated = facts.failure && facts.failure.signature !== next.escalatedSignature ? escalateTo(incumbent) : null;
|
|
41
|
+
if (escalated) {
|
|
42
42
|
next.escalatedSignature = facts.failure.signature;
|
|
43
43
|
next.holdUntilTurn = next.turn + config.policy.escalationHoldTurns;
|
|
44
44
|
next.votes = [];
|
|
45
|
-
const gated = cashGate(config, routeFor(
|
|
46
|
-
return gated.blocked ? gatedResult(gated, incumbent, next) : result(
|
|
45
|
+
const gated = cashGate(config, routeFor(escalated), facts, now, costs, routeFor);
|
|
46
|
+
return gated.blocked ? gatedResult(gated, incumbent, next) : result(escalated, 'escalation', next);
|
|
47
47
|
}
|
|
48
48
|
if (next.turn <= next.holdUntilTurn) return stay('hold');
|
|
49
49
|
if (!advice) return stay('no-advice');
|
|
@@ -80,6 +80,7 @@ export function decide({
|
|
|
80
80
|
// The move lands on the cheapest tier the answer supports as a whole: from the choice up to just below the
|
|
81
81
|
// incumbent, the first tier whose mass at or below it clears its bar. A split answer (micro 0.8, low 0.16) on high
|
|
82
82
|
// moves to low instead of waiting for micro alone to reach the bar. A pending stay reports the choice's estimate.
|
|
83
|
+
/** @type {object | null} */
|
|
83
84
|
let pending = null;
|
|
84
85
|
for (const target of TIERS.filter((t) => rank(t) >= rank(choice) && rank(t) < rank(incumbent))) {
|
|
85
86
|
const support = massAtOrBelow(advice.probabilities, target);
|
|
@@ -157,7 +158,7 @@ function trailing(votes, predicate) {
|
|
|
157
158
|
return count;
|
|
158
159
|
}
|
|
159
160
|
|
|
160
|
-
function result(tier, reason, state, estimate = null) {
|
|
161
|
+
function result(tier, reason, state, estimate = /** @type {object | null} */ (null)) {
|
|
161
162
|
return { tier, reason, state, estimate };
|
|
162
163
|
}
|
|
163
164
|
|
package/lib/replay-trace.mjs
CHANGED
|
@@ -383,7 +383,7 @@ export function appendTrace(
|
|
|
383
383
|
record,
|
|
384
384
|
events,
|
|
385
385
|
at,
|
|
386
|
-
{ lostWrites = 0, reasons = [], maxBytes = TRACE_SESSION_BYTES, excludedEvents = 0 } = {},
|
|
386
|
+
{ lostWrites = 0, reasons = /** @type {string[]} */ ([]), maxBytes = TRACE_SESSION_BYTES, excludedEvents = 0 } = {},
|
|
387
387
|
) {
|
|
388
388
|
const next = {
|
|
389
389
|
...record,
|
|
@@ -486,7 +486,10 @@ export function traceVictims(entries, at, ownKey, candidate, active = new Set())
|
|
|
486
486
|
.filter(([key]) => key !== ownKey && !victims.has(key))
|
|
487
487
|
.reduce((sum, [key, v]) => sum + traceBytes(key) + traceBytes(v) + 2, 0);
|
|
488
488
|
for (const [key, v] of others
|
|
489
|
-
.filter(
|
|
489
|
+
.filter(
|
|
490
|
+
([name, entry]) =>
|
|
491
|
+
!victims.has(name) && !(at - entry.updatedAt <= TRACE_ACTIVE_MS && (active.has(name) || entry.active)),
|
|
492
|
+
)
|
|
490
493
|
.sort((a, b) => a[1].updatedAt - b[1].updatedAt)) {
|
|
491
494
|
if (bytes <= TRACE_BUDGET_BYTES) break;
|
|
492
495
|
victims.add(key);
|
package/lib/replay.mjs
CHANGED
|
@@ -33,6 +33,7 @@ const countTurns = (events) => new Set(events.filter((e) => e.type === 'request'
|
|
|
33
33
|
|
|
34
34
|
// Validate before projecting: malformed data must not quietly turn into a successful scenario.
|
|
35
35
|
export function mergeExports(exports) {
|
|
36
|
+
/** @type {{ version: number, sessions: object } | null} */
|
|
36
37
|
let merged = null;
|
|
37
38
|
for (const value of exports) {
|
|
38
39
|
if (value?.version !== 1 || !value.sessions || Array.isArray(value.sessions) || typeof value.sessions !== 'object')
|
|
@@ -200,6 +201,7 @@ function simulatedReply(config, loop, pair, event) {
|
|
|
200
201
|
const pricedRoute = typeof route.effort === 'number' ? { ...route, effort: null } : route;
|
|
201
202
|
const bounds = costs.inputBounds(config, pricedRoute, tokens, { models, effort: pair.effort }, event.at);
|
|
202
203
|
const rates = costs.ratesAt(model, tokens, event.at);
|
|
204
|
+
if (rates.output === undefined) return { range: null, usage: null };
|
|
203
205
|
const output = (usage.output_tokens * rates.output) / 1e6;
|
|
204
206
|
const key = costs.cacheKey(config, pair.model, pair.effort);
|
|
205
207
|
const prefix =
|
|
@@ -224,7 +226,8 @@ function acceptAutoAdvice(replay, event, op) {
|
|
|
224
226
|
replay.advice = op.advice;
|
|
225
227
|
const accepted = config.activityRouting === 'on' ? acceptActivity(config, op.advice) : null;
|
|
226
228
|
const signal = routingActivity(config, op.advice);
|
|
227
|
-
if (accepted)
|
|
229
|
+
if (accepted)
|
|
230
|
+
replay.activity = signal !== null && signal.mass >= config.policy.activityMass ? signal.choice : accepted;
|
|
228
231
|
replay.boundedExecute = accepted !== null && acceptPhase(config, op.advice) === 'execute';
|
|
229
232
|
replay.observedFrom = op.facts?.midTurn
|
|
230
233
|
? Math.max(op.taskProgress?.prompt ?? 0, (event.observedFrom ?? 0) - 1)
|
|
@@ -443,6 +446,7 @@ export function replayAuto(record, tableRows) {
|
|
|
443
446
|
effort: row.pair.effort,
|
|
444
447
|
usage: substituted ? { model: event.servedModel } : simulated.usage,
|
|
445
448
|
});
|
|
449
|
+
// biome-ignore lint/suspicious/noUnnecessaryConditions: savedPin is set in another function through `replay`, which Biome cannot follow
|
|
446
450
|
if (replay.savedPin) replay.pendingFallback = external;
|
|
447
451
|
else Object.assign(replay, external);
|
|
448
452
|
}
|
|
@@ -465,7 +469,9 @@ export function replayAuto(record, tableRows) {
|
|
|
465
469
|
}
|
|
466
470
|
|
|
467
471
|
function markSwitches(rows, window) {
|
|
472
|
+
/** @type {{ from: object, to: object, turn: number, paired: boolean } | null} */
|
|
468
473
|
let prior = null;
|
|
474
|
+
/** @type {{ generation: number, pair: object } | null} */
|
|
469
475
|
let previous = null;
|
|
470
476
|
for (const row of rows) {
|
|
471
477
|
if (row.manual || row.fallback || row.external) {
|
|
@@ -0,0 +1,46 @@
|
|
|
1
|
+
// The route line: one row placed at the end of the transcript after a turn, saying which model and effort ran and why.
|
|
2
|
+
// Pure: which turns get a row, and what it records. The hook places it (`$.ui.place`) and draws it (`ui.render` on
|
|
3
|
+
// `Placed`); the words and the glyphs are the band's (ui/model/band.mjs).
|
|
4
|
+
import { reasonActivity } from './display.mjs';
|
|
5
|
+
|
|
6
|
+
export const LINE_MODES = ['off', 'moves', 'all'];
|
|
7
|
+
// `moves` says the route only when it is not the last turn's.
|
|
8
|
+
export const DEFAULT_LINE_MODE = 'moves';
|
|
9
|
+
const ID_PREFIX = 'rl-';
|
|
10
|
+
// `$.ui.place` takes 1 to 64 letters, digits, `_` and `-`.
|
|
11
|
+
const ID_MAX = 64;
|
|
12
|
+
|
|
13
|
+
export const lineModeOf = (stored) => (LINE_MODES.includes(stored) ? stored : DEFAULT_LINE_MODE);
|
|
14
|
+
|
|
15
|
+
/** The row's id for a turn: its id with anything `$.ui.place` refuses made `_`, so one turn has one row. */
|
|
16
|
+
export const lineId = (turnId) => `${ID_PREFIX}${String(turnId).replace(/[^A-Za-z0-9_-]/g, '_')}`.slice(0, ID_MAX);
|
|
17
|
+
|
|
18
|
+
/** The route a view shows: the model that served the turn, else the one chosen, and its effort; null with neither. */
|
|
19
|
+
export function routeOf(view) {
|
|
20
|
+
const model = view?.actualModel ?? view?.selectedModel ?? null;
|
|
21
|
+
return model ? { model, effort: view.effort ?? null } : null;
|
|
22
|
+
}
|
|
23
|
+
|
|
24
|
+
/** Whether a turn that ran `route` gets a row, after one that ran `previous` (null at a session's first routed turn). */
|
|
25
|
+
export function showsLine(mode, previous, route) {
|
|
26
|
+
if (mode === 'off') return false;
|
|
27
|
+
return mode === 'all' || !previous || previous.model !== route.model || previous.effort !== route.effort;
|
|
28
|
+
}
|
|
29
|
+
|
|
30
|
+
/**
|
|
31
|
+
* What the row keeps: the route, the tier it ran for, why, the activity and the policy's estimate; nothing of the
|
|
32
|
+
* prompt.
|
|
33
|
+
* @returns {{ model: string, effort: string | number | null, tier: string | null, reason: string, activity: string | null, reasonActivity: string | null, estimate: object | null }}
|
|
34
|
+
*/
|
|
35
|
+
export function lineOf(config, view, route) {
|
|
36
|
+
return {
|
|
37
|
+
model: route.model,
|
|
38
|
+
effort: route.effort,
|
|
39
|
+
tier: view.tier ?? null,
|
|
40
|
+
reason: view.reason ?? 'ready',
|
|
41
|
+
activity: view.activity ?? null,
|
|
42
|
+
// The activity the reason names, as the band words it: not the one a refused move left the turn on.
|
|
43
|
+
reasonActivity: reasonActivity(config, view),
|
|
44
|
+
estimate: view.estimate ?? null,
|
|
45
|
+
};
|
|
46
|
+
}
|
package/lib/route.mjs
CHANGED
|
@@ -38,8 +38,8 @@ export function isNativeFallback(loop, model) {
|
|
|
38
38
|
// The tier and activity whose route runs model `id`, or null when no route names it. Base routes first, baseline
|
|
39
39
|
// first; activity overrides only when they apply, with `activityRouting: on`.
|
|
40
40
|
export function cellForModel(config, id) {
|
|
41
|
-
const order = [config.baselineTier, ...TIERS.filter((
|
|
42
|
-
const runs = (
|
|
41
|
+
const order = [config.baselineTier, ...TIERS.filter((other) => other !== config.baselineTier)];
|
|
42
|
+
const runs = (candidate, kind) => isSameModel(routeSpec(config, resolveRoute(config, candidate, kind)).id, id);
|
|
43
43
|
const tier = order.find((t) => runs(t, null));
|
|
44
44
|
if (tier) return { tier, activity: null };
|
|
45
45
|
if (config.activityRouting !== 'on') return null;
|
|
@@ -219,7 +219,7 @@ function opsFloor(config, activity) {
|
|
|
219
219
|
for (const tier of TIERS) {
|
|
220
220
|
if (declared[activity]?.[tier]) continue;
|
|
221
221
|
const ops = resolveRoute(config, tier, 'ops');
|
|
222
|
-
if (
|
|
222
|
+
if ((compareRoutes(config, resolveRoute(config, tier, activity), ops) ?? 0) >= 0) continue;
|
|
223
223
|
cells[tier] = ops;
|
|
224
224
|
retained.push(tier);
|
|
225
225
|
}
|
|
@@ -247,8 +247,8 @@ function routeTurn(config, loop, { facts, advice, pin, nativeModel, contextKnown
|
|
|
247
247
|
// The incumbent runs the route in use, not the one config gives its cell now. It is rebuilt from config for a loop
|
|
248
248
|
// from before 1.15, a route whose model left the config or can no longer run, and a route kept for an activity that
|
|
249
249
|
// no longer applies (activity routing turned off).
|
|
250
|
-
const usable = (
|
|
251
|
-
const model = Object.hasOwn(config.models,
|
|
250
|
+
const usable = (held) => {
|
|
251
|
+
const model = Object.hasOwn(config.models, held.model) ? config.models[held.model] : null;
|
|
252
252
|
return Boolean(
|
|
253
253
|
model && isModelAllowed(model.id, availableModels, nativeModel) && !loop.ineligible.includes(model.id),
|
|
254
254
|
);
|
|
@@ -320,6 +320,7 @@ function routeTurn(config, loop, { facts, advice, pin, nativeModel, contextKnown
|
|
|
320
320
|
const route = result.tier ? routeOf(result) : null;
|
|
321
321
|
const model = route ? routeSpec(config, route).id : nativeModel;
|
|
322
322
|
const effort = route ? costs.routeEffort(config, route, facts.effort) : facts.effort;
|
|
323
|
+
/** @type {object | null} */
|
|
323
324
|
let comparison = null;
|
|
324
325
|
const candidate = pin ?? advice?.choice;
|
|
325
326
|
if (contextKnown && loop.lastRequest && TIERS.includes(candidate) && candidate !== loop.lastRoute) {
|
|
@@ -396,7 +397,10 @@ function decideCell({
|
|
|
396
397
|
// order against it: after a mode change the next tier's route can be the weaker one.
|
|
397
398
|
const escalates = (t) => {
|
|
398
399
|
const order = compareRoutes(config, routeFor(t), incumbent.route, facts.effort);
|
|
399
|
-
return
|
|
400
|
+
return (
|
|
401
|
+
(order !== null && order > 0) ||
|
|
402
|
+
(order === null && !sameRequest(config, routeFor(t), incumbent.route, facts.effort))
|
|
403
|
+
);
|
|
400
404
|
};
|
|
401
405
|
const escalateTo = (tier) => TIERS.slice(rank(tier) + 1).find(escalates) ?? null;
|
|
402
406
|
const step = decide({
|
|
@@ -439,10 +443,10 @@ function decideCell({
|
|
|
439
443
|
now,
|
|
440
444
|
costs,
|
|
441
445
|
});
|
|
442
|
-
const
|
|
446
|
+
const routedActivity = lateral.move ? activity : incumbent.activity;
|
|
443
447
|
return {
|
|
444
448
|
...step,
|
|
445
|
-
activity:
|
|
449
|
+
activity: routedActivity,
|
|
446
450
|
floorActivity: lateral.move ? floorActivity : incumbent.floorActivity,
|
|
447
451
|
reason: lateral.reason,
|
|
448
452
|
estimate: lateral.estimate,
|
|
@@ -462,7 +466,7 @@ const runningRoute = (config, decision) =>
|
|
|
462
466
|
export function canMoveUp(config, decision, effort) {
|
|
463
467
|
if (config.activityRouting !== 'on' || !decision?.tier || decision.pinned) return false;
|
|
464
468
|
const from = runningRoute(config, decision);
|
|
465
|
-
return ACTIVITIES.some((a) => compareRoutes(config, resolveRoute(config, decision.tier, a), from, effort) > 0);
|
|
469
|
+
return ACTIVITIES.some((a) => (compareRoutes(config, resolveRoute(config, decision.tier, a), from, effort) ?? 0) > 0);
|
|
466
470
|
}
|
|
467
471
|
|
|
468
472
|
// A move up inside a turn: the classifier labels a turn from its prompt, and a prompt that reads as ops or explore can
|
|
@@ -476,10 +480,10 @@ export function observedMove(config, loop, { observed, facts, contextKnown, now
|
|
|
476
480
|
if (!canMoveUp(config, decision, facts.effort) || !ACTIVITIES.includes(observed)) return loop;
|
|
477
481
|
const from = runningRoute(config, decision);
|
|
478
482
|
// The gates price the route that will run: the one the context fits, not the tier's first choice.
|
|
479
|
-
const routeFor = (
|
|
483
|
+
const routeFor = (candidate) => resolveRoute(config, candidate, observed);
|
|
480
484
|
const tier = fitTier(config, decision.tier, costs.nextContextTokens(facts), routeFor);
|
|
481
485
|
const to = routeFor(tier);
|
|
482
|
-
if (
|
|
486
|
+
if ((compareRoutes(config, to, from, facts.effort) ?? 0) <= 0) return loop;
|
|
483
487
|
// Without a reliable reading of the context, a smaller window might overflow, as in routeTurn.
|
|
484
488
|
const window = (route) => routeSpec(config, route).contextWindow;
|
|
485
489
|
if ((!contextKnown || !loop.historyMeasured) && window(to) < window(from)) return loop;
|
|
@@ -522,7 +526,7 @@ export function continueRoute(
|
|
|
522
526
|
const floor = opsFloor(current, work);
|
|
523
527
|
const config = floor.config;
|
|
524
528
|
const activity = work ?? decision.activity ?? null;
|
|
525
|
-
const
|
|
529
|
+
const tierActivity = (tier) => (floor.retained.includes(tier) ? 'ops' : activity);
|
|
526
530
|
if (!work && decision.floorActivity) decision = { ...decision, floorActivity: null };
|
|
527
531
|
if (contextKnown && decision.tier) {
|
|
528
532
|
// The route the turn runs, which a mode change or a held move can keep apart from config, stays while the context
|
|
@@ -536,7 +540,7 @@ export function continueRoute(
|
|
|
536
540
|
decision = {
|
|
537
541
|
...decision,
|
|
538
542
|
tier: fitted,
|
|
539
|
-
activity:
|
|
543
|
+
activity: tierActivity(fitted),
|
|
540
544
|
route,
|
|
541
545
|
model: routeSpec(config, route).id,
|
|
542
546
|
effort: costs.routeEffort(config, route, effort),
|
|
@@ -559,7 +563,7 @@ export function continueRoute(
|
|
|
559
563
|
decision = {
|
|
560
564
|
...decision,
|
|
561
565
|
tier: tier ?? null,
|
|
562
|
-
activity: tier ?
|
|
566
|
+
activity: tier ? tierActivity(tier) : null,
|
|
563
567
|
floorActivity: tier ? work : null,
|
|
564
568
|
route,
|
|
565
569
|
model: route ? routeSpec(config, route).id : nativeModel,
|
|
@@ -604,8 +608,9 @@ export function observeResponse(config, loop, { usage, requestedModel, effort, s
|
|
|
604
608
|
if (!counts.every((key) => Number.isFinite(usage[key]) && usage[key] >= 0)) return next;
|
|
605
609
|
const tokens = usage.input_tokens + usage.cache_read_input_tokens + usage.cache_creation_input_tokens;
|
|
606
610
|
if (tokens === 0) return next;
|
|
607
|
-
const resolutions = sameModel
|
|
608
|
-
|
|
611
|
+
const resolutions = sameModel
|
|
612
|
+
? { ...next.resolutions, [requestedModel]: usage.model }
|
|
613
|
+
: Object.fromEntries(Object.entries(next.resolutions).filter(([model]) => model !== requestedModel));
|
|
609
614
|
let models = next.models;
|
|
610
615
|
if (next.lastRequest && tokens < next.lastRequest.tokens * HISTORY_SHRINK) models = {};
|
|
611
616
|
// A substituted model's effort is not reported, so do not credit its estimated cache.
|
package/lib/savings.mjs
CHANGED
|
@@ -51,7 +51,8 @@ export function requestUsd(
|
|
|
51
51
|
cacheMode === 'disabled'
|
|
52
52
|
? rates.input * (input + cacheRead + cacheWrite)
|
|
53
53
|
: rates.input * (input + cacheWrite * writeMultiplier) + rates.cacheRead * cacheRead;
|
|
54
|
-
|
|
54
|
+
// An unknown output price leaves the request unpriced (NaN), which the callers' priced checks catch.
|
|
55
|
+
return (inputUsd + (rates.output ?? Number.NaN) * output) / 1e6;
|
|
55
56
|
}
|
|
56
57
|
|
|
57
58
|
// Actual observed counters can be priced without inventing the cache on another route.
|
|
@@ -111,6 +112,15 @@ const isCount = (n) => Number.isFinite(n) && n >= 0;
|
|
|
111
112
|
// negative, stronger than yours when positive) and the cache the switches cost (routed against the served model on
|
|
112
113
|
// your cache), never negative. The parts sum to the difference by construction. `reply` is null when a model has no
|
|
113
114
|
// price or `ttl` is not a known cache lifetime.
|
|
115
|
+
/**
|
|
116
|
+
* @typedef {{ routedUsd: number, yoursUsd: number, cheaperUsd: number, strongerUsd: number, switchUsd: number }} ReplyComparison
|
|
117
|
+
*/
|
|
118
|
+
|
|
119
|
+
/**
|
|
120
|
+
* @typedef {{ total: number, at: number, onYours: boolean, model: string, effort: string | null }} CacheState
|
|
121
|
+
*/
|
|
122
|
+
|
|
123
|
+
/** @returns {{ state: CacheState | null, reply: ReplyComparison | null }} */
|
|
114
124
|
export function compareReply(config, state, { usage, served, yours, ttl, now }) {
|
|
115
125
|
const counts = {
|
|
116
126
|
input: usage?.input_tokens,
|
|
@@ -194,6 +204,7 @@ export function unpricedCause(config, { usage, served, yours, ttl }) {
|
|
|
194
204
|
// model: `states` and `replies` by models key, each as compareReply returns, and `reply`, the prices against `yours`,
|
|
195
205
|
// the API model id /model selects now, or null.
|
|
196
206
|
export function compareModels(config, states, { usage, served, effort, ttl, now, yours }) {
|
|
207
|
+
/** @type {{ states: Record<string, unknown>, replies: Record<string, ReplyComparison>, reply: ReplyComparison | null }} */
|
|
197
208
|
const out = { states: {}, replies: {}, reply: null };
|
|
198
209
|
for (const [alias, model] of Object.entries(config.models)) {
|
|
199
210
|
const { state, reply } = compareReply(config, modelEntry(states, alias) ?? null, {
|
|
@@ -217,7 +228,7 @@ const SUMS = ['routedUsd', 'yoursUsd', 'cheaperUsd', 'strongerUsd', 'switchUsd']
|
|
|
217
228
|
export function emptySavingsStore() {
|
|
218
229
|
return {
|
|
219
230
|
version: 1,
|
|
220
|
-
since: null,
|
|
231
|
+
since: /** @type {number | null} */ (null),
|
|
221
232
|
replies: 0,
|
|
222
233
|
routedUsd: 0,
|
|
223
234
|
yoursUsd: 0,
|
|
@@ -266,7 +277,7 @@ const cents = (usd) => Math.round(usd * 100);
|
|
|
266
277
|
// stronger part down to 0, then the cheaper part. So no part changes sign or appears from rounding alone. `early`
|
|
267
278
|
// below EARLY_REPLIES replies. `share` is the difference against yours; `ratio` routed over yours.
|
|
268
279
|
export function readout(totals) {
|
|
269
|
-
const [routed, yours, cheaper, stronger] = [
|
|
280
|
+
const [routed = 0, yours = 0, cheaper = 0, stronger = 0] = [
|
|
270
281
|
totals.routedUsd,
|
|
271
282
|
totals.yoursUsd,
|
|
272
283
|
totals.cheaperUsd,
|
package/lib/subagents.mjs
CHANGED
|
@@ -46,7 +46,8 @@ const OWN_MODEL_BUILTINS = ['Explore', 'Plan'];
|
|
|
46
46
|
export function agentFrontmatter(text) {
|
|
47
47
|
const match = /^---\r?\n([\s\S]*?)\r?\n---/.exec(typeof text === 'string' ? text : '');
|
|
48
48
|
if (!match) return null;
|
|
49
|
-
const
|
|
49
|
+
const [, body = ''] = match;
|
|
50
|
+
const block = body.trim();
|
|
50
51
|
const fields = {};
|
|
51
52
|
if (block.startsWith('{')) {
|
|
52
53
|
try {
|
|
@@ -56,8 +57,9 @@ export function agentFrontmatter(text) {
|
|
|
56
57
|
}
|
|
57
58
|
} else
|
|
58
59
|
for (const line of block.split(/\r?\n/)) {
|
|
59
|
-
const
|
|
60
|
-
if (
|
|
60
|
+
const [, key, value] = /^([A-Za-z][\w-]*):\s*(.*?)\s*$/.exec(line) ?? [];
|
|
61
|
+
if (key !== undefined && value !== undefined)
|
|
62
|
+
fields[key] = value.replace(/\s+#.*$/, '').replace(/^(['"])(.*)\1$/, '$2');
|
|
61
63
|
}
|
|
62
64
|
const text_ = (value) => (typeof value === 'string' && value ? value : null);
|
|
63
65
|
return { name: text_(fields.name), model: text_(fields.model), modelRouting: text_(fields.modelRouting) };
|
|
@@ -73,11 +75,15 @@ const pluginOf = (spawn) => {
|
|
|
73
75
|
return typeof provider === 'string' ? provider.split('@')[0] : null;
|
|
74
76
|
};
|
|
75
77
|
|
|
78
|
+
const WORKFLOW_TYPE = 'workflow-subagent';
|
|
79
|
+
|
|
76
80
|
// What router.json lists for this spawn's type: a models key, CLASSIFY or null, or undefined when it does not list
|
|
77
81
|
// it. A key without a colon names a built-in, so it matches only the engine's own agent; a `plugin:name` key matches
|
|
78
82
|
// only that plugin's agent (provider `plugin@marketplace`).
|
|
79
83
|
function listedRoute(config, spawn) {
|
|
80
84
|
const { types } = config.subagents;
|
|
85
|
+
// A workflow agent's own type does not apply to it: it is always the engine's workflow-subagent.
|
|
86
|
+
if (spawn.workflow) return Object.hasOwn(types, WORKFLOW_TYPE) ? types[WORKFLOW_TYPE] : undefined;
|
|
81
87
|
const type = spawn.subagentType;
|
|
82
88
|
if (typeof type !== 'string' || !Object.hasOwn(types, type)) return undefined;
|
|
83
89
|
const owner = type.includes(':') ? type.slice(0, type.indexOf(':')) : 'engine';
|
|
@@ -97,15 +103,17 @@ export function typeRoute(config, spawn, definition = null) {
|
|
|
97
103
|
}
|
|
98
104
|
|
|
99
105
|
// The reason a spawn keeps the model core gives it, or null when the router may choose one. A fork reads the parent's
|
|
100
|
-
// cache on the parent's model; `model` is the Agent call's own choice; a teammate
|
|
101
|
-
//
|
|
106
|
+
// cache on the parent's model; `model` is the Agent call's own choice; a teammate is not rewritable. A workflow agent's
|
|
107
|
+
// model rewrite applies (2.1.321, checked live), but its type is not one the router knows, so it is routed only where
|
|
108
|
+
// router.json lists `workflow-subagent`, and a workflow `agent({ model })` is the script's own choice.
|
|
102
109
|
export function passReason(config, spawn, definition = null) {
|
|
103
110
|
if (spawn.fork) return 'fork';
|
|
104
111
|
// Before `explicit`: a workflow agent({ model }) arrives with `model` set, and counts as a workflow agent.
|
|
105
|
-
if (spawn.workflow) return 'workflow';
|
|
112
|
+
if (spawn.workflow && (spawn.model || listedRoute(config, spawn) === undefined)) return 'workflow';
|
|
106
113
|
if (spawn.model) return 'explicit';
|
|
107
114
|
if (spawn.isTeammate) return 'teammate';
|
|
108
|
-
|
|
115
|
+
const route = typeRoute(config, spawn, definition);
|
|
116
|
+
return 'pass' in route ? route.pass : null;
|
|
109
117
|
}
|
|
110
118
|
|
|
111
119
|
// The task text the classifier sees: the description and the prompt the parent wrote, clipped like a main turn's
|
|
@@ -129,7 +137,15 @@ export function classifiedAlias(config, advice) {
|
|
|
129
137
|
// CLAUDE_CODE_SUBAGENT_MODEL, except for the
|
|
130
138
|
// built-ins that ignore it without CLAUDE_CODE_SUBAGENT_MODEL_FORCE, else the parent's model. An estimate: it does not
|
|
131
139
|
// apply the family-alias rule or the availableModels substitution.
|
|
132
|
-
export function coreModelOf(
|
|
140
|
+
export function coreModelOf(
|
|
141
|
+
config,
|
|
142
|
+
spawn,
|
|
143
|
+
{
|
|
144
|
+
envModel = /** @type {string | null} */ (null),
|
|
145
|
+
force = false,
|
|
146
|
+
definition = /** @type {{ model?: string } | null} */ (null),
|
|
147
|
+
} = {},
|
|
148
|
+
) {
|
|
133
149
|
const idOf = (model) => (Object.hasOwn(config.models, model) ? config.models[model].id : model);
|
|
134
150
|
const pinned = definition?.model && definition.model !== 'inherit' ? definition.model : null;
|
|
135
151
|
if (pinned && !(force && envModel)) return idOf(pinned);
|
|
@@ -150,7 +166,17 @@ export function moveOf(config, routedModel, coreModel) {
|
|
|
150
166
|
// PASS_REASONS entry or null. `choice` is the models key decided, or 'core' when the decision kept core's model.
|
|
151
167
|
// `move` is moveOf the routed model against core's. `actualUsd` prices each reply on the model it ran on; `otherUsd`
|
|
152
168
|
// the same tokens on core's estimated model, none for a pass-through.
|
|
153
|
-
export function spawnRecord({
|
|
169
|
+
export function spawnRecord({
|
|
170
|
+
sessionId,
|
|
171
|
+
spawn,
|
|
172
|
+
pass,
|
|
173
|
+
choice,
|
|
174
|
+
routedModel,
|
|
175
|
+
coreModel,
|
|
176
|
+
move = /** @type {string | null} */ (null),
|
|
177
|
+
failed,
|
|
178
|
+
respawn,
|
|
179
|
+
}) {
|
|
154
180
|
return {
|
|
155
181
|
sessionId,
|
|
156
182
|
type: spawn.subagentType,
|
|
@@ -199,6 +225,9 @@ export function addAgentReply(config, agent, usage, ttl, at) {
|
|
|
199
225
|
// and their cost (`models`); a routed model also counts the agents the router moved onto it, `up` or `down` from
|
|
200
226
|
// core's, and core's estimated cost of the same tokens. A version 1 record, from before 1.14.0, has neither days nor
|
|
201
227
|
// models: it reads as `undated` totals, which only the periods without a range (session and all) count.
|
|
228
|
+
/** @typedef {{ version: number, since: number | null, days: Record<string, ReturnType<typeof emptySubagentDay>>, undated?: Record<string, number> }} SubagentStore */
|
|
229
|
+
|
|
230
|
+
/** @returns {SubagentStore} */
|
|
202
231
|
export function emptySubagentStore() {
|
|
203
232
|
return { version: 2, since: null, days: {} };
|
|
204
233
|
}
|
|
@@ -255,8 +284,8 @@ export function recordAgent(store, agent, now) {
|
|
|
255
284
|
put(day[kind], key, counts);
|
|
256
285
|
days[dayKey(now)] = day;
|
|
257
286
|
const cutoff = daysBefore(now, RETAIN_DAYS);
|
|
258
|
-
|
|
259
|
-
return { version: 2, since: store.since ?? now, days, ...(store.undated ? { undated: store.undated } : {}) };
|
|
287
|
+
const kept = Object.fromEntries(Object.entries(days).filter(([date]) => date >= cutoff));
|
|
288
|
+
return { version: 2, since: store.since ?? now, days: kept, ...(store.undated ? { undated: store.undated } : {}) };
|
|
260
289
|
}
|
|
261
290
|
|
|
262
291
|
// The record after a flush: counted once, nothing pending.
|
|
@@ -313,6 +342,7 @@ function undatedOf(value) {
|
|
|
313
342
|
|
|
314
343
|
// The stored value with its well-formed days and entries, else an empty store: a missing, hand-edited or unknown value
|
|
315
344
|
// must not break a turn or the pane.
|
|
345
|
+
/** @returns {SubagentStore} */
|
|
316
346
|
export function readSubagentStore(value) {
|
|
317
347
|
if (!isRecord(value) || !(value.since === null || Number.isFinite(value.since))) return emptySubagentStore();
|
|
318
348
|
if (value.version === 1) {
|
|
@@ -0,0 +1,60 @@
|
|
|
1
|
+
// The words `/router` takes: one table that the command, its argument hint and the prompt's typeahead all read, so a
|
|
2
|
+
// word added in one place cannot be missing in another. The handlers sit beside the command in the hook; a test runs
|
|
3
|
+
// the command with every word and value here.
|
|
4
|
+
import { ACTIVITY_MODES, ROUTING_MODES, TIERS } from './config.mjs';
|
|
5
|
+
import { LINE_MODES } from './route-line.mjs';
|
|
6
|
+
|
|
7
|
+
/**
|
|
8
|
+
* @typedef {object} Subcommand
|
|
9
|
+
* @property {string} name
|
|
10
|
+
* @property {string} description one line, drawn beside the word in the typeahead
|
|
11
|
+
* @property {string[]} [values] what may follow the word; the typeahead offers each
|
|
12
|
+
* @property {string} [hint] how the argument hint spells what follows the word; the values when absent
|
|
13
|
+
*/
|
|
14
|
+
|
|
15
|
+
/** @type {readonly Subcommand[]} */
|
|
16
|
+
export const SUBCOMMANDS = [
|
|
17
|
+
{ name: 'auto', description: 'Routing on' },
|
|
18
|
+
{ name: 'off', description: 'Routing off: Claude’s model is kept' },
|
|
19
|
+
{ name: 'pin', description: 'Pin the next turn to a tier', values: TIERS, hint: '<tier>' },
|
|
20
|
+
{ name: 'mode', description: 'Routing mode', values: [...ROUTING_MODES, 'default'], hint: '<mode>' },
|
|
21
|
+
{ name: 'activities', description: 'Activity routing', values: ACTIVITY_MODES },
|
|
22
|
+
{ name: 'line', description: 'The route line after a turn', values: LINE_MODES },
|
|
23
|
+
{ name: 'decisions', description: 'The last routing decisions', hint: '[n]' },
|
|
24
|
+
{ name: 'trace', description: 'Export the shadow traces', values: ['export'], hint: 'export' },
|
|
25
|
+
];
|
|
26
|
+
|
|
27
|
+
const slot = (sub) => sub.hint ?? (sub.values ? `<${sub.values.join('|')}>` : undefined);
|
|
28
|
+
|
|
29
|
+
/** The command's argument hint: `[auto|off|pin <tier>|…|activities <off|on>|…]`. */
|
|
30
|
+
export const argumentHint = () =>
|
|
31
|
+
`[${SUBCOMMANDS.map((sub) => (slot(sub) ? `${sub.name} ${slot(sub)}` : sub.name)).join('|')}]`;
|
|
32
|
+
|
|
33
|
+
// A word is taken as its token followed by a space where more is expected, so the box asks again for the value.
|
|
34
|
+
const takes = (sub) => Boolean(sub.values?.length);
|
|
35
|
+
|
|
36
|
+
/**
|
|
37
|
+
* The typeahead rows for the token at the cursor: the words after `/router `, or the values after a word that takes
|
|
38
|
+
* them. Nothing when the token is not in an argument of `/router`, or nothing matches.
|
|
39
|
+
* @param {{ text: string, start: number, token: string }} input
|
|
40
|
+
* @param {{ describe?: (name: string, value: string) => string | undefined }} [options]
|
|
41
|
+
* @returns {{ text: string, label?: string, description?: string }[]}
|
|
42
|
+
*/
|
|
43
|
+
export function routerSuggestions({ text, start, token }, { describe } = {}) {
|
|
44
|
+
const lead = text.slice(0, start).match(/^\/router\s+(?:(\S+)\s+)?$/);
|
|
45
|
+
if (!lead) return [];
|
|
46
|
+
const typed = token.toLowerCase();
|
|
47
|
+
const matching = (candidate) => candidate.toLowerCase().startsWith(typed);
|
|
48
|
+
if (!lead[1])
|
|
49
|
+
return SUBCOMMANDS.filter((sub) => matching(sub.name)).map((sub) => ({
|
|
50
|
+
text: takes(sub) ? `${sub.name} ` : sub.name,
|
|
51
|
+
label: slot(sub) ? `${sub.name} ${slot(sub)}` : sub.name,
|
|
52
|
+
description: sub.description,
|
|
53
|
+
}));
|
|
54
|
+
const word = SUBCOMMANDS.find((item) => item.name === lead[1]);
|
|
55
|
+
if (!word) return [];
|
|
56
|
+
return (word.values ?? []).filter(matching).map((value) => {
|
|
57
|
+
const description = describe?.(word.name, value);
|
|
58
|
+
return { text: value, label: value, ...(description ? { description } : {}) };
|
|
59
|
+
});
|
|
60
|
+
}
|
|
@@ -0,0 +1,22 @@
|
|
|
1
|
+
import { isGraphical } from './tokens.mjs';
|
|
2
|
+
|
|
3
|
+
/**
|
|
4
|
+
* Draws with `draw(surface)`. On a graphical surface with an `onFallback`, a throw is handed to it and the terminal
|
|
5
|
+
* tree is drawn instead, which is what those surfaces drew before the graphical renderers. With no `onFallback` the
|
|
6
|
+
* throw propagates, so a broken graphical renderer cannot pass as the terminal tree. The terminal's own throw is never
|
|
7
|
+
* caught: there is nothing under it.
|
|
8
|
+
* @template T
|
|
9
|
+
* @param {string | undefined} surface
|
|
10
|
+
* @param {(surface: string | undefined) => T} draw
|
|
11
|
+
* @param {((error: unknown) => void) | undefined} onFallback
|
|
12
|
+
* @returns {T}
|
|
13
|
+
*/
|
|
14
|
+
export function orTerminal(surface, draw, onFallback) {
|
|
15
|
+
if (!isGraphical(surface) || !onFallback) return draw(surface);
|
|
16
|
+
try {
|
|
17
|
+
return draw(surface);
|
|
18
|
+
} catch (error) {
|
|
19
|
+
onFallback(error);
|
|
20
|
+
return draw('terminal');
|
|
21
|
+
}
|
|
22
|
+
}
|