@alexeiled/claude-router 1.25.1 → 1.27.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 +32 -2
- package/README.md +1 -1
- package/docs/architecture.md +3 -2
- package/docs/configuration.md +65 -1
- package/docs/providers.md +9 -0
- package/docs/user-guide.md +47 -10
- package/hooks/native-router.mjs +243 -25
- package/lib/band.mjs +7 -1
- package/lib/config.mjs +72 -1
- package/lib/decisions.mjs +46 -1
- package/lib/display.mjs +3 -2
- package/lib/failover.mjs +260 -23
- package/lib/holds.mjs +129 -0
- package/lib/providers.mjs +2 -0
- package/lib/route.mjs +217 -86
- package/lib/subcommands.mjs +8 -4
- package/lib/ui/graphical/band.mjs +1 -1
- package/lib/ui/graphical/now.mjs +44 -0
- package/lib/ui/graphical/routes.mjs +45 -0
- package/lib/ui/model/band.mjs +5 -2
- package/lib/ui/model/frame.mjs +2 -2
- package/lib/ui/model/now.mjs +35 -1
- package/lib/ui/model/routes.mjs +68 -5
- package/lib/ui/terminal/band.mjs +1 -1
- package/lib/ui/terminal/now.mjs +29 -0
- package/lib/ui/terminal/routes.mjs +31 -0
- package/lib/view.mjs +5 -0
- package/package.json +1 -1
package/hooks/native-router.mjs
CHANGED
|
@@ -38,6 +38,7 @@ import {
|
|
|
38
38
|
loadConfig,
|
|
39
39
|
MIGRATION_HINT,
|
|
40
40
|
MIN_CLAUDE_CODE,
|
|
41
|
+
PLAN_ACCOUNT,
|
|
41
42
|
ROUTING_MODES,
|
|
42
43
|
supportedVersion,
|
|
43
44
|
TIERS,
|
|
@@ -50,6 +51,7 @@ import {
|
|
|
50
51
|
withTuning,
|
|
51
52
|
} from '../lib/config.mjs';
|
|
52
53
|
import { changedLeaves, notSaved, restored, rewrittenConfig } from '../lib/config-file.mjs';
|
|
54
|
+
import { billingOf, planLimits } from '../lib/costs.mjs';
|
|
53
55
|
import {
|
|
54
56
|
addTurnRow,
|
|
55
57
|
appendDecisions,
|
|
@@ -59,6 +61,7 @@ import {
|
|
|
59
61
|
decisionRow,
|
|
60
62
|
decisionsAfterReset,
|
|
61
63
|
endRow,
|
|
64
|
+
failureRow,
|
|
62
65
|
isGoalOrigin,
|
|
63
66
|
isProgressOrigin,
|
|
64
67
|
MAX_ROWS,
|
|
@@ -96,7 +99,21 @@ import {
|
|
|
96
99
|
routingBucket,
|
|
97
100
|
stripReminders,
|
|
98
101
|
} from '../lib/facts.mjs';
|
|
99
|
-
import {
|
|
102
|
+
import {
|
|
103
|
+
accountNames,
|
|
104
|
+
accountOfModel,
|
|
105
|
+
activeHolds,
|
|
106
|
+
classifyFailure,
|
|
107
|
+
failureHold,
|
|
108
|
+
HOLDS_PREFIX,
|
|
109
|
+
holdModel,
|
|
110
|
+
holdText,
|
|
111
|
+
isActive,
|
|
112
|
+
planAccountsOf,
|
|
113
|
+
readHold,
|
|
114
|
+
releaseHold,
|
|
115
|
+
} from '../lib/failover.mjs';
|
|
116
|
+
import { heldCause, heldRows, holdsText, releaseRow } from '../lib/holds.mjs';
|
|
100
117
|
import { applyMode, modeLabel, readProjectMode, resolveRoutingMode } from '../lib/modes.mjs';
|
|
101
118
|
import { renderPanel } from '../lib/panel.mjs';
|
|
102
119
|
import { sameTaskOf } from '../lib/policy.mjs';
|
|
@@ -319,6 +336,8 @@ function createRouter(options) {
|
|
|
319
336
|
lastRoute: null,
|
|
320
337
|
// The model of the last main request sent: the one an API error that ends the turn failed on (holdFailedModel).
|
|
321
338
|
lastRequested: /** @type {string | null} */ (null),
|
|
339
|
+
// The latest main turn's id: `StopFailure` carries none, and its failure row belongs to that turn.
|
|
340
|
+
mainTurnId: /** @type {string | null} */ (null),
|
|
322
341
|
decisionRecord: null,
|
|
323
342
|
trace: /** @type {TraceHold | null} */ (null),
|
|
324
343
|
traceFreshSession: null,
|
|
@@ -931,7 +950,12 @@ async function storeView($, router) {
|
|
|
931
950
|
// A notice answers the last press in the pane, so the pane opens without one; the last write keeps its Undo in the
|
|
932
951
|
// status bar.
|
|
933
952
|
async function openPane($, router) {
|
|
934
|
-
await updateView($, router, {
|
|
953
|
+
await updateView($, router, {
|
|
954
|
+
notice: null,
|
|
955
|
+
confirmDelete: false,
|
|
956
|
+
holds: await readHolds($, router),
|
|
957
|
+
...(await storeView($, router)),
|
|
958
|
+
});
|
|
935
959
|
const opened = await $.ui.open({ id: PANE, title: PANE_TITLE, focus: true, closeOnEscape: true });
|
|
936
960
|
// The pane is open but undrawn, as where no surface places panes or the terminal is too narrow for it; saying why beats
|
|
937
961
|
// a press that shows nothing.
|
|
@@ -1009,6 +1033,10 @@ async function runSubcommand($, router, action, value) {
|
|
|
1009
1033
|
};
|
|
1010
1034
|
case 'decisions':
|
|
1011
1035
|
return { text: await decisionsText($, router, value) };
|
|
1036
|
+
case 'holds':
|
|
1037
|
+
return { text: holdsText(router.config, await readHolds($, router), Date.now()) };
|
|
1038
|
+
case 'release':
|
|
1039
|
+
return { text: await releaseCommand($, router, value) };
|
|
1012
1040
|
case 'pin':
|
|
1013
1041
|
return { text: TIERS.includes(value) ? await setPin($, router, value) : `Choose ${TIERS.join(', ')}.` };
|
|
1014
1042
|
case 'mode':
|
|
@@ -1279,6 +1307,7 @@ async function* passMain($, e, next, previous, version, nativeModel, reason, rou
|
|
|
1279
1307
|
selectedModel: e.model,
|
|
1280
1308
|
effort: e.effort ?? null,
|
|
1281
1309
|
reason,
|
|
1310
|
+
fallback: null,
|
|
1282
1311
|
contextTokens: context.tokens,
|
|
1283
1312
|
contextKnown: context.known,
|
|
1284
1313
|
});
|
|
@@ -1484,6 +1513,7 @@ async function decideTurn($, router, e, signal, step) {
|
|
|
1484
1513
|
nativeModel,
|
|
1485
1514
|
contextKnown: context.known,
|
|
1486
1515
|
availableModels,
|
|
1516
|
+
accountHolds: await accountHoldsOf($, cfg),
|
|
1487
1517
|
now: Date.now(),
|
|
1488
1518
|
};
|
|
1489
1519
|
const selected =
|
|
@@ -1509,8 +1539,19 @@ async function decideTurn($, router, e, signal, step) {
|
|
|
1509
1539
|
if (!written.isSet || controller.signal.aborted) return null;
|
|
1510
1540
|
if (cfg.routingEngine === 'shadow') traceOp(router, e, cfg, 'choose', traceInput, selected, messages);
|
|
1511
1541
|
rememberGoal(router, e.turnId, result.advice, cfg.policy.continuationMass, messages);
|
|
1542
|
+
const holds = { accounts: traceInput.accountHolds, models: selected.held ?? {} };
|
|
1512
1543
|
if (previous?.model && previous.model !== selected.decision.model && !selected.decision.pinned)
|
|
1513
|
-
$.ui.toast(
|
|
1544
|
+
$.ui.toast(
|
|
1545
|
+
switchToast(
|
|
1546
|
+
cfg,
|
|
1547
|
+
previous,
|
|
1548
|
+
selected.decision,
|
|
1549
|
+
selected.decision.estimate,
|
|
1550
|
+
selected.decision.reason === 'model-held'
|
|
1551
|
+
? heldCause(cfg, { holds, fallback: selected.decision.fallback }, Date.now())
|
|
1552
|
+
: null,
|
|
1553
|
+
),
|
|
1554
|
+
);
|
|
1514
1555
|
const activity = turnActivity(cfg, result.advice, previous, selected.decision);
|
|
1515
1556
|
const routingMode = step.cfg.routingMode;
|
|
1516
1557
|
addDecision(
|
|
@@ -1575,6 +1616,8 @@ async function decideTurn($, router, e, signal, step) {
|
|
|
1575
1616
|
tier: selected.decision.tier,
|
|
1576
1617
|
effort: selected.decision.effort,
|
|
1577
1618
|
reason: selected.decision.reason,
|
|
1619
|
+
fallback: selected.decision.fallback ?? null,
|
|
1620
|
+
holds,
|
|
1578
1621
|
activity: activity.label,
|
|
1579
1622
|
goal: selected.decision.goal,
|
|
1580
1623
|
taskPhase: selected.decision.taskPhase,
|
|
@@ -1641,7 +1684,13 @@ async function moveOnObserved($, router, cfg, loop, e, context) {
|
|
|
1641
1684
|
const observed = routingBucket(
|
|
1642
1685
|
observedActivity(messages, Math.max(promptIndex(messages), (loop.observedFrom ?? 0) - 1)),
|
|
1643
1686
|
);
|
|
1644
|
-
const traceInput = {
|
|
1687
|
+
const traceInput = {
|
|
1688
|
+
observed,
|
|
1689
|
+
facts,
|
|
1690
|
+
contextKnown: context.known,
|
|
1691
|
+
accountHolds: await accountHoldsOf($, cfg),
|
|
1692
|
+
now: Date.now(),
|
|
1693
|
+
};
|
|
1645
1694
|
const moved = observedMove(cfg, loop, traceInput);
|
|
1646
1695
|
if (cfg.routingEngine === 'shadow') traceOp(router, e, cfg, 'observed', traceInput, moved, messages);
|
|
1647
1696
|
if (moved === loop) return loop;
|
|
@@ -1694,6 +1743,7 @@ async function reviewMidTurn($, router, cfg, loop, e, { context, nativeModel, av
|
|
|
1694
1743
|
nativeModel,
|
|
1695
1744
|
contextKnown: context.known,
|
|
1696
1745
|
availableModels,
|
|
1746
|
+
accountHolds: await accountHoldsOf($, cfg),
|
|
1697
1747
|
now: Date.now(),
|
|
1698
1748
|
};
|
|
1699
1749
|
const selected =
|
|
@@ -1993,6 +2043,7 @@ async function startTurn($, router, e) {
|
|
|
1993
2043
|
if (!(await ensureInitialized($, router))) return;
|
|
1994
2044
|
const epoch = ++router.goalEpoch;
|
|
1995
2045
|
router.goalTurnId = e.turnId;
|
|
2046
|
+
router.mainTurnId = e.turnId;
|
|
1996
2047
|
await fixTurnConfig($, router, e.turnId);
|
|
1997
2048
|
const text = clip(stripReminders(e.text), router.config.context.maxTextChars);
|
|
1998
2049
|
const origin = originOfTurn(router, e.text);
|
|
@@ -2792,9 +2843,11 @@ function paneActions($, router, view) {
|
|
|
2792
2843
|
withClassifierTimeout(file, router.config.classifier, timeoutMs),
|
|
2793
2844
|
);
|
|
2794
2845
|
},
|
|
2846
|
+
release: (scope, key) => releaseKey($, router, scope, key),
|
|
2795
2847
|
undo: async () => {
|
|
2796
2848
|
const last = (router.view ?? view).lastWrite;
|
|
2797
2849
|
if (!last) return undefined;
|
|
2850
|
+
if (last.restore) return undoRelease($, router, last);
|
|
2798
2851
|
return save(
|
|
2799
2852
|
(file) => restored(file, last.leaves),
|
|
2800
2853
|
() => ({ lastWrite: null, notice: `Undid: ${last.label}.` }),
|
|
@@ -3047,6 +3100,7 @@ async function* stepMain($, router, e, next) {
|
|
|
3047
3100
|
contextKnown: context.known,
|
|
3048
3101
|
availableModels,
|
|
3049
3102
|
effort: e.effort,
|
|
3103
|
+
accountHolds: await accountHoldsOf($, cfg),
|
|
3050
3104
|
now: Date.now(),
|
|
3051
3105
|
};
|
|
3052
3106
|
loop =
|
|
@@ -3069,7 +3123,7 @@ async function initializeSession($, router) {
|
|
|
3069
3123
|
await $.command.register({
|
|
3070
3124
|
name: 'router',
|
|
3071
3125
|
description:
|
|
3072
|
-
'Open the Router pane, or switch routing: auto, off, pin <tier>, activities <mode>, mode <mode>, line <mode>; decisions [n] lists the last routing decisions.',
|
|
3126
|
+
'Open the Router pane, or switch routing: auto, off, pin <tier>, activities <mode>, mode <mode>, line <mode>; decisions [n] lists the last routing decisions; holds lists what is held out of routing, release <model|account> ends a hold.',
|
|
3073
3127
|
argumentHint: argumentHint(),
|
|
3074
3128
|
immediate: true,
|
|
3075
3129
|
});
|
|
@@ -3168,32 +3222,188 @@ async function keepChosenModel($, router, reason) {
|
|
|
3168
3222
|
}
|
|
3169
3223
|
|
|
3170
3224
|
// A main turn ended on an API error (`StopFailure`): the request is lost, and Claude Code reports neither the model nor
|
|
3171
|
-
// a retry-after.
|
|
3172
|
-
// (
|
|
3173
|
-
//
|
|
3174
|
-
|
|
3225
|
+
// a retry-after. The failure goes into the turn's decision rows with what Claude Code gave and the plan's readings, then
|
|
3226
|
+
// classifies (classifyFailure) and holds: an error that is the model's holds the model the last request ran, which can
|
|
3227
|
+
// be a stand-in, out of routing for a while in the loop; a used-up quota holds its account in $.store, where every
|
|
3228
|
+
// session and restart sees it (lib/failover.mjs). The `auto` engine routes without holds, so it gets none and no toast
|
|
3229
|
+
// claims one.
|
|
3230
|
+
async function holdFailedModel($, router, e) {
|
|
3175
3231
|
// A failed hold changes no route; the turn's result stands.
|
|
3176
3232
|
try {
|
|
3177
|
-
if (
|
|
3178
|
-
|
|
3233
|
+
if (!(await ensureInitialized($, router))) return;
|
|
3234
|
+
const { config } = router;
|
|
3179
3235
|
const model = router.lastRequested ?? (await $.session.model());
|
|
3180
|
-
const
|
|
3181
|
-
|
|
3182
|
-
|
|
3183
|
-
|
|
3184
|
-
|
|
3185
|
-
|
|
3186
|
-
|
|
3187
|
-
|
|
3188
|
-
|
|
3189
|
-
|
|
3190
|
-
|
|
3191
|
-
|
|
3192
|
-
|
|
3236
|
+
const usage = await $.session.usage().catch(() => null);
|
|
3237
|
+
const limits = planLimits(usage);
|
|
3238
|
+
const now = Date.now();
|
|
3239
|
+
const account = accountOfModel(config, model);
|
|
3240
|
+
const failure = classifyFailure({
|
|
3241
|
+
error: e.error,
|
|
3242
|
+
details: e.error_details,
|
|
3243
|
+
limits,
|
|
3244
|
+
billing: billingOf(config, usage),
|
|
3245
|
+
planAccounts: planAccountsOf(config),
|
|
3246
|
+
account,
|
|
3247
|
+
accounts: config.accounts,
|
|
3248
|
+
now,
|
|
3249
|
+
});
|
|
3250
|
+
const held =
|
|
3251
|
+
failure.kind === null || config.routingEngine === 'auto'
|
|
3252
|
+
? null
|
|
3253
|
+
: await applyHold($, router, failure, e.error, failure.scope === 'account' ? account : model, now).catch(
|
|
3254
|
+
() => null,
|
|
3255
|
+
);
|
|
3256
|
+
// A loop read later in this event sees the state from before the write, so a model hold takes the holds just written.
|
|
3257
|
+
if (held) {
|
|
3258
|
+
const read = await readHolds($, router);
|
|
3259
|
+
await updateView($, router, { holds: held.models ? { ...read, models: held.models } : read });
|
|
3193
3260
|
}
|
|
3261
|
+
const turnId = router.mainTurnId;
|
|
3262
|
+
if (turnId === null) return;
|
|
3263
|
+
addDecision(
|
|
3264
|
+
router,
|
|
3265
|
+
turnId,
|
|
3266
|
+
failureRow({
|
|
3267
|
+
at: now,
|
|
3268
|
+
error: e.error,
|
|
3269
|
+
details: e.error_details,
|
|
3270
|
+
limits,
|
|
3271
|
+
failure: held ? failure.kind : null,
|
|
3272
|
+
scope: held ? failure.scope : null,
|
|
3273
|
+
held: held?.key ?? null,
|
|
3274
|
+
}),
|
|
3275
|
+
);
|
|
3276
|
+
// A turn that already completed will not flush its rows again.
|
|
3277
|
+
if (!router.turnConfigs.has(turnId)) await flushDecisions($, router, turnId, null);
|
|
3194
3278
|
} catch {}
|
|
3195
3279
|
}
|
|
3196
3280
|
|
|
3281
|
+
// The account holds in $.store at this moment, account name to hold, for routing to skip the models they cover. A hold
|
|
3282
|
+
// that cannot be read holds nothing: a turn is never blocked on the store. The `auto` engine holds nothing.
|
|
3283
|
+
async function accountHoldsOf($, cfg) {
|
|
3284
|
+
if (cfg.routingEngine === 'auto') return {};
|
|
3285
|
+
const read = await Promise.all(
|
|
3286
|
+
accountNames(cfg).map(async (name) => [
|
|
3287
|
+
name,
|
|
3288
|
+
readHold(await $.store.get(`${HOLDS_PREFIX}${name}`).catch(() => null)),
|
|
3289
|
+
]),
|
|
3290
|
+
);
|
|
3291
|
+
return Object.fromEntries(read.filter(([, hold]) => hold));
|
|
3292
|
+
}
|
|
3293
|
+
|
|
3294
|
+
// The holds in force now, as the pane, the band and `/router holds` read them: each account's from $.store and the models'
|
|
3295
|
+
// from the loop. A read that fails shows none.
|
|
3296
|
+
async function readHolds($, router) {
|
|
3297
|
+
const loaded = await $.state.get({ ...LOOP, id: 'main' }).catch(() => null);
|
|
3298
|
+
return { accounts: await accountHoldsOf($, router.config), models: loaded?.value?.held ?? {} };
|
|
3299
|
+
}
|
|
3300
|
+
|
|
3301
|
+
// Writes the hold of an account (in $.store) or a model (in the loop), or ends it with null. A loop write that lost to a
|
|
3302
|
+
// step's own write reads the loop again. With `keepRunning`, a hold running now is not replaced: returns false then.
|
|
3303
|
+
async function writeHold($, scope, key, hold, keepRunning = false) {
|
|
3304
|
+
const runs = (current) => keepRunning && current && isActive(current, Date.now());
|
|
3305
|
+
if (scope === 'account') {
|
|
3306
|
+
const store = `${HOLDS_PREFIX}${key}`;
|
|
3307
|
+
if (runs(readHold(await $.store.get(store)))) return false;
|
|
3308
|
+
await (hold ? $.store.set(store, hold) : $.store.delete(store));
|
|
3309
|
+
return true;
|
|
3310
|
+
}
|
|
3311
|
+
const ref = { ...LOOP, id: 'main' };
|
|
3312
|
+
for (let attempt = 0; attempt < 3; attempt += 1) {
|
|
3313
|
+
const { value: loop, version } = await $.state.get(ref);
|
|
3314
|
+
if (!loop) return true;
|
|
3315
|
+
if (runs(loop.held?.[key])) return false;
|
|
3316
|
+
const held = hold ? { ...loop.held, [key]: hold } : releaseHold(loop.held, key);
|
|
3317
|
+
if ((await $.state.set(ref, { ...loop, held }, { ifVersion: version })).isSet) return true;
|
|
3318
|
+
}
|
|
3319
|
+
throw new Error('the hold changed while it was written');
|
|
3320
|
+
}
|
|
3321
|
+
|
|
3322
|
+
// Ends the hold of `row` (lib/holds.mjs) and keeps it for Undo in the pane. Returns what happened, in words.
|
|
3323
|
+
async function releaseHeld($, router, row) {
|
|
3324
|
+
try {
|
|
3325
|
+
await writeHold($, row.scope, row.key, null);
|
|
3326
|
+
} catch {
|
|
3327
|
+
return `${row.name} could not be released.`;
|
|
3328
|
+
}
|
|
3329
|
+
const notice = `Released ${row.name}: routing may use it from the next turn.`;
|
|
3330
|
+
await updateView($, router, {
|
|
3331
|
+
holds: await readHolds($, router),
|
|
3332
|
+
lastWrite: {
|
|
3333
|
+
label: `released ${row.name}`,
|
|
3334
|
+
restore: { scope: row.scope, key: row.key, hold: row.hold },
|
|
3335
|
+
},
|
|
3336
|
+
notice,
|
|
3337
|
+
});
|
|
3338
|
+
return notice;
|
|
3339
|
+
}
|
|
3340
|
+
|
|
3341
|
+
// The Now tab's Release: the hold is read again, since another session may have ended it.
|
|
3342
|
+
async function releaseKey($, router, scope, key) {
|
|
3343
|
+
const holds = await readHolds($, router);
|
|
3344
|
+
const row = heldRows(router.config, holds, Date.now()).find((one) => one.scope === scope && one.key === key);
|
|
3345
|
+
if (!row) return updateView($, router, { holds, notice: 'Already released.' });
|
|
3346
|
+
await releaseHeld($, router, row);
|
|
3347
|
+
return undefined;
|
|
3348
|
+
}
|
|
3349
|
+
|
|
3350
|
+
// Undo of a release puts the hold back as it was, unless another hold on the same name was set since.
|
|
3351
|
+
async function undoRelease($, router, last) {
|
|
3352
|
+
const { scope, key, hold } = last.restore;
|
|
3353
|
+
const outcome = await writeHold($, scope, key, hold, true).then(
|
|
3354
|
+
(written) => (written ? 'done' : 'held'),
|
|
3355
|
+
() => 'failed',
|
|
3356
|
+
);
|
|
3357
|
+
const name = last.label.replace(/^released /, '');
|
|
3358
|
+
const notices = {
|
|
3359
|
+
done: `Undid: ${last.label}.`,
|
|
3360
|
+
held: `Not undone: ${name} is held again.`,
|
|
3361
|
+
failed: `Not saved: ${last.label} could not be undone.`,
|
|
3362
|
+
};
|
|
3363
|
+
return updateView($, router, {
|
|
3364
|
+
holds: await readHolds($, router),
|
|
3365
|
+
lastWrite: outcome === 'failed' ? last : null,
|
|
3366
|
+
notice: notices[outcome],
|
|
3367
|
+
});
|
|
3368
|
+
}
|
|
3369
|
+
|
|
3370
|
+
// `/router release <model|account>`.
|
|
3371
|
+
async function releaseCommand($, router, word) {
|
|
3372
|
+
const found = releaseRow(router.config, await readHolds($, router), word, Date.now());
|
|
3373
|
+
return found.row ? releaseHeld($, router, found.row) : found.text;
|
|
3374
|
+
}
|
|
3375
|
+
|
|
3376
|
+
// Holds `key`, the account or model a failure names, and returns it, or null when nothing was held. $.store has no
|
|
3377
|
+
// atomic update, so two sessions that fail together can each write their own hold; the later write stands, and both
|
|
3378
|
+
// say the same account is out.
|
|
3379
|
+
async function applyHold($, router, failure, error, key, now) {
|
|
3380
|
+
if (failure.scope === 'account') {
|
|
3381
|
+
const store = `${HOLDS_PREFIX}${key}`;
|
|
3382
|
+
const running = readHold(await $.store.get(store)) ?? undefined;
|
|
3383
|
+
const hold = failureHold(failure, error, running, now);
|
|
3384
|
+
if (!hold) return null;
|
|
3385
|
+
if (hold !== running) await $.store.set(store, hold);
|
|
3386
|
+
if ((await modeOf($, router)) === 'auto')
|
|
3387
|
+
$.ui.toast(`${key === PLAN_ACCOUNT ? 'Claude plan' : key} held out of routing: ${holdText(hold, now)}`);
|
|
3388
|
+
return { key, models: null };
|
|
3389
|
+
}
|
|
3390
|
+
const ref = { ...LOOP, id: 'main' };
|
|
3391
|
+
// A write that lost to a step's own write reads the loop again.
|
|
3392
|
+
for (let attempt = 0; attempt < 3; attempt += 1) {
|
|
3393
|
+
const { value: loop, version } = await $.state.get(ref);
|
|
3394
|
+
if (!loop) return null;
|
|
3395
|
+
const at = Date.now();
|
|
3396
|
+
const held = holdModel(loop.held, key, failure, error, at);
|
|
3397
|
+
const written = await $.state.set(ref, { ...loop, held }, { ifVersion: version });
|
|
3398
|
+
if (!written.isSet) continue;
|
|
3399
|
+
const hold = activeHolds(held, at)[key];
|
|
3400
|
+
if (hold && (await modeOf($, router)) === 'auto')
|
|
3401
|
+
$.ui.toast(`${modelName(key)} held out of routing: ${holdText(hold, at)}`);
|
|
3402
|
+
return { key, models: held };
|
|
3403
|
+
}
|
|
3404
|
+
return null;
|
|
3405
|
+
}
|
|
3406
|
+
|
|
3197
3407
|
async function ensureInitialized($, router) {
|
|
3198
3408
|
if (router.initialized) return true;
|
|
3199
3409
|
router.initializing ??= initializeSession($, router).finally(() => {
|
|
@@ -3214,6 +3424,7 @@ export function register(on, options) {
|
|
|
3214
3424
|
router.traceOperations.clear();
|
|
3215
3425
|
router.lastRoute = null;
|
|
3216
3426
|
router.lastRequested = null;
|
|
3427
|
+
router.mainTurnId = null;
|
|
3217
3428
|
router.initialized = false;
|
|
3218
3429
|
router.noticeSurfaces.clear();
|
|
3219
3430
|
await ensureInitialized($, router);
|
|
@@ -3255,6 +3466,13 @@ export function register(on, options) {
|
|
|
3255
3466
|
on('prompt.autocomplete', async (_$, e, next) => {
|
|
3256
3467
|
const mine = routerSuggestions(e, {
|
|
3257
3468
|
describe: (name, value) => (name === 'pin' && router.view ? pinCard(router.config, value) : undefined),
|
|
3469
|
+
sources: {
|
|
3470
|
+
held: heldRows(
|
|
3471
|
+
router.config,
|
|
3472
|
+
/** @type {import('../lib/holds.mjs').HoldSet | null | undefined} */ (router.view?.holds),
|
|
3473
|
+
Date.now(),
|
|
3474
|
+
).map((row) => row.word),
|
|
3475
|
+
},
|
|
3258
3476
|
});
|
|
3259
3477
|
if (!mine.length) return next(e);
|
|
3260
3478
|
return { suggestions: [...(await next(e)).suggestions, ...mine] };
|
|
@@ -3315,7 +3533,7 @@ export function register(on, options) {
|
|
|
3315
3533
|
// A hook failure leaves the event to the hooks beneath, as without the router.
|
|
3316
3534
|
on('classic.StopFailure', async ($, e, next) => {
|
|
3317
3535
|
const result = await next(e);
|
|
3318
|
-
if (e.agent_id === undefined) await holdFailedModel($, router, e
|
|
3536
|
+
if (e.agent_id === undefined) await holdFailedModel($, router, e);
|
|
3319
3537
|
return result;
|
|
3320
3538
|
}).catch((_$, e, next) => next(e));
|
|
3321
3539
|
|
package/lib/band.mjs
CHANGED
|
@@ -39,8 +39,14 @@ export function renderRouteLine(elements, config, line, opts) {
|
|
|
39
39
|
);
|
|
40
40
|
}
|
|
41
41
|
|
|
42
|
-
|
|
42
|
+
/**
|
|
43
|
+
* The toast for a route switch. `heldBy` says who holds the model out when a fallback runs in its place: "Claude plan 5h
|
|
44
|
+
* limit · back 19:00 → GLM 5.3 · max".
|
|
45
|
+
* @param {string | null} [heldBy]
|
|
46
|
+
*/
|
|
47
|
+
export function switchToast(config, previous, next, estimate, heldBy = null) {
|
|
43
48
|
const label = (decision) => routeLabel(decision.model, decision.effort);
|
|
49
|
+
if (heldBy) return `${heldBy} → ${label(next)}`;
|
|
44
50
|
const support = supportText(config, estimate);
|
|
45
51
|
// "Model changed: Sonnet 5.5 · medium → Haiku 5.5 · high · ↓ ops"
|
|
46
52
|
const why = shortReason(next.reason, next.activity);
|
package/lib/config.mjs
CHANGED
|
@@ -256,6 +256,12 @@ export const DEFAULTS = {
|
|
|
256
256
|
},
|
|
257
257
|
},
|
|
258
258
|
context: { recentTurns: 6, maxTextChars: 1200 },
|
|
259
|
+
// Stand-ins for a model that is held out: an ordered list per source models key, each entry a models key or
|
|
260
|
+
// `key@effort`. A list is not followed through its targets' own lists. docs/plans/2026-11-19-fallback-chains.md.
|
|
261
|
+
fallbacks: {},
|
|
262
|
+
// Per account: `reset: { monthly: 1-28, tz }`, the day a calendar limit ends (midnight in `tz`). Accounts group the
|
|
263
|
+
// models that share one quota (models.*.account); see accountOf.
|
|
264
|
+
accounts: {},
|
|
259
265
|
};
|
|
260
266
|
|
|
261
267
|
// Keys a route, a model or a classifier entry may carry. The other closed sections take their key sets from DEFAULTS.
|
|
@@ -273,6 +279,8 @@ const MODEL_KEYS = [
|
|
|
273
279
|
'strength',
|
|
274
280
|
'capability',
|
|
275
281
|
'imageInput',
|
|
282
|
+
'account',
|
|
283
|
+
'requiresOwnHistory',
|
|
276
284
|
];
|
|
277
285
|
const CLASSIFIER_KEYS = ['label', 'api', 'endpoint', 'model', 'keyOption', 'timeoutMs'];
|
|
278
286
|
// The wire protocols a classifier can speak. Each has an adapter in classifier-apis.mjs; a test keeps the two in step.
|
|
@@ -289,6 +297,10 @@ export const CLASSIFIER_OPTIONS = {
|
|
|
289
297
|
const OPTION_NAMES = Object.keys(CLASSIFIER_OPTIONS);
|
|
290
298
|
// A JSON file can hold these as own keys; merged into a plain object they reach the prototype chain.
|
|
291
299
|
const FORBIDDEN_KEYS = new Set(['__proto__', 'constructor', 'prototype']);
|
|
300
|
+
// The account every model on the Claude plan shares by default: one plan quota blocks all of them.
|
|
301
|
+
export const PLAN_ACCOUNT = 'plan';
|
|
302
|
+
export const RESET_KEYS = ['monthly', 'tz'];
|
|
303
|
+
const ACCOUNT_NAME = /^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$/;
|
|
292
304
|
export const MIGRATION_HINT =
|
|
293
305
|
'run node scripts/migrate-config.mjs /path/to/router.json from the router plugin directory';
|
|
294
306
|
|
|
@@ -328,6 +340,12 @@ export function loadConfig({ userFile = null, provider = 'anthropic' } = {}) {
|
|
|
328
340
|
return config;
|
|
329
341
|
}
|
|
330
342
|
|
|
343
|
+
// The account whose quota the model under `alias` spends: its own setting, else the plan for a plan model, else itself.
|
|
344
|
+
export function accountOf(config, alias) {
|
|
345
|
+
const model = Object.hasOwn(config.models, alias) ? config.models[alias] : undefined;
|
|
346
|
+
return model?.account ?? (model?.billing === 'plan' ? PLAN_ACCOUNT : alias);
|
|
347
|
+
}
|
|
348
|
+
|
|
331
349
|
export function activeClassifier(config) {
|
|
332
350
|
return config.classifiers[config.classifier];
|
|
333
351
|
}
|
|
@@ -586,7 +604,8 @@ function checkShape(file) {
|
|
|
586
604
|
if (file && typeof file === 'object' && Object.hasOwn(file, 'jev'))
|
|
587
605
|
throw new Error(`router.json uses the 1.1 jev section; ${MIGRATION_HINT}`);
|
|
588
606
|
checkObject(file, 'router.json', Object.keys(DEFAULTS));
|
|
589
|
-
const { routes, activities, models, cache, policy, modes, classifiers, context, subagents } =
|
|
607
|
+
const { routes, activities, models, cache, policy, modes, classifiers, context, subagents, fallbacks, accounts } =
|
|
608
|
+
file;
|
|
590
609
|
if (routes !== undefined) {
|
|
591
610
|
checkObject(routes, 'routes', TIERS);
|
|
592
611
|
for (const [tier, route] of Object.entries(routes)) checkObject(route, `routes.${tier}`, ROUTE_KEYS);
|
|
@@ -634,6 +653,14 @@ function checkShape(file) {
|
|
|
634
653
|
checkObject(subagents, 'subagents', Object.keys(DEFAULTS.subagents));
|
|
635
654
|
if (subagents.types !== undefined) checkObject(subagents.types, 'subagents.types');
|
|
636
655
|
}
|
|
656
|
+
if (fallbacks !== undefined) checkObject(fallbacks, 'fallbacks');
|
|
657
|
+
if (accounts !== undefined) {
|
|
658
|
+
checkObject(accounts, 'accounts');
|
|
659
|
+
for (const [name, account] of Object.entries(accounts)) {
|
|
660
|
+
checkObject(account, `accounts.${name}`, ['reset']);
|
|
661
|
+
if (account.reset !== undefined) checkObject(account.reset, `accounts.${name}.reset`, RESET_KEYS);
|
|
662
|
+
}
|
|
663
|
+
}
|
|
637
664
|
}
|
|
638
665
|
|
|
639
666
|
// `allowed` null: an open map.
|
|
@@ -727,6 +754,46 @@ function validate(config) {
|
|
|
727
754
|
for (const field of ['recentTurns', 'maxTextChars']) {
|
|
728
755
|
if (!isNumber(context[field], 1, { integer: true })) throw new Error(`context.${field} must be a positive integer`);
|
|
729
756
|
}
|
|
757
|
+
validateFallbacks(config);
|
|
758
|
+
for (const [name, account] of Object.entries(config.accounts)) validateReset(`accounts.${name}.reset`, account.reset);
|
|
759
|
+
}
|
|
760
|
+
|
|
761
|
+
function validateFallbacks(config) {
|
|
762
|
+
for (const [source, chain] of Object.entries(config.fallbacks)) {
|
|
763
|
+
const at = `fallbacks.${source}`;
|
|
764
|
+
if (!Object.hasOwn(config.models, source)) throw new Error(`${at} is not in models`);
|
|
765
|
+
if (!Array.isArray(chain)) throw new Error(`${at} must be a list`);
|
|
766
|
+
const listed = new Set();
|
|
767
|
+
chain.forEach((entry, i) => {
|
|
768
|
+
const [alias, effort, ...extra] = typeof entry === 'string' ? entry.split('@') : [];
|
|
769
|
+
if (!alias || extra.length) throw new Error(`${at}[${i}] must be a models key or models key@effort`);
|
|
770
|
+
if (!Object.hasOwn(config.models, alias)) throw new Error(`${at}[${i}] is not in models`);
|
|
771
|
+
if (alias === source) throw new Error(`${at}[${i}] is the model it stands in for`);
|
|
772
|
+
if (listed.has(alias)) throw new Error(`${at}[${i}] is listed twice`);
|
|
773
|
+
listed.add(alias);
|
|
774
|
+
if (effort !== undefined && !config.models[alias].efforts.includes(effort))
|
|
775
|
+
throw new Error(`${at}[${i}] effort is not supported by its model`);
|
|
776
|
+
});
|
|
777
|
+
if ([source, ...listed].some((alias) => config.models[alias].requiresOwnHistory))
|
|
778
|
+
throw new Error(`${at} mixes a model that requires its own history with another model`);
|
|
779
|
+
}
|
|
780
|
+
}
|
|
781
|
+
|
|
782
|
+
function isTimeZone(value) {
|
|
783
|
+
if (typeof value !== 'string' || !value) return false;
|
|
784
|
+
try {
|
|
785
|
+
new Intl.DateTimeFormat('en-US', { timeZone: value });
|
|
786
|
+
return true;
|
|
787
|
+
} catch {
|
|
788
|
+
return false;
|
|
789
|
+
}
|
|
790
|
+
}
|
|
791
|
+
|
|
792
|
+
function validateReset(at, reset) {
|
|
793
|
+
if (reset === undefined) return;
|
|
794
|
+
if (!isNumber(reset.monthly, 1, { integer: true }) || reset.monthly > 28)
|
|
795
|
+
throw new Error(`${at}.monthly must be a day from 1 to 28`);
|
|
796
|
+
if (!isTimeZone(reset.tz)) throw new Error(`${at}.tz must be an IANA time zone`);
|
|
730
797
|
}
|
|
731
798
|
|
|
732
799
|
function validatePolicy(p, at) {
|
|
@@ -778,6 +845,10 @@ function validateModel(at, model) {
|
|
|
778
845
|
}
|
|
779
846
|
if (typeof model.id !== 'string' || !model.id) throw new Error(`${at}.id is required`);
|
|
780
847
|
if (!['plan', 'credits'].includes(model.billing)) throw new Error(`${at}.billing must be plan or credits`);
|
|
848
|
+
if (model.account !== undefined && !(typeof model.account === 'string' && ACCOUNT_NAME.test(model.account)))
|
|
849
|
+
throw new Error(`${at}.account must be a name of letters, digits, dots, dashes and underscores`);
|
|
850
|
+
if (model.requiresOwnHistory !== undefined && typeof model.requiresOwnHistory !== 'boolean')
|
|
851
|
+
throw new Error(`${at}.requiresOwnHistory must be a boolean`);
|
|
781
852
|
if (!Array.isArray(model.efforts) || model.efforts.some((e) => !EFFORTS.includes(e)))
|
|
782
853
|
throw new Error(`${at}.efforts must list valid effort levels`);
|
|
783
854
|
if (model.capability !== undefined) {
|
package/lib/decisions.mjs
CHANGED
|
@@ -13,7 +13,10 @@ export const DECISIONS_PREFIX = 'decisions:v1:';
|
|
|
13
13
|
export const MAX_ROWS = 60;
|
|
14
14
|
export const MAX_RECORDS = 20;
|
|
15
15
|
export const RETAIN_MS = 30 * 24 * 60 * 60 * 1000;
|
|
16
|
-
export const ROW_KINDS = ['start', 'review', 'observed', 'end'];
|
|
16
|
+
export const ROW_KINDS = ['start', 'review', 'observed', 'end', 'failure'];
|
|
17
|
+
// The most of an API error's text a failure row keeps, and of the plan's readings.
|
|
18
|
+
export const FAILURE_DETAILS_CHARS = 300;
|
|
19
|
+
const FAILURE_LIMITS = 4;
|
|
17
20
|
|
|
18
21
|
// Where a prompt came from, as the engine stamps it (prompt.submit's PromptOrigin.kind). Progress origins report on the
|
|
19
22
|
// running work, so their turn is the same task: the classifier judges the active goal with the report as dialogue, and a
|
|
@@ -207,6 +210,35 @@ export function endRow({ at, observed = null, requests = 0, priced = 0, unpriced
|
|
|
207
210
|
};
|
|
208
211
|
}
|
|
209
212
|
|
|
213
|
+
// An API error that ended a main turn, kept to learn what Claude Code reports (docs/plans/2026-11-19-fallback-chains.md):
|
|
214
|
+
// `err` the error word, `details` the first characters of its text when the build gives one, `limits` the plan windows
|
|
215
|
+
// at that moment (`pct`, `resets` in ms), `fail` the kind the failure classified as (null: nothing held), `scope` and
|
|
216
|
+
// `held` what it held: a model id or an account. Local record only; /router decisions shows no text.
|
|
217
|
+
export function failureRow({
|
|
218
|
+
at,
|
|
219
|
+
error = null,
|
|
220
|
+
details = /** @type {string | null | undefined} */ (null),
|
|
221
|
+
limits = /** @type {{ kind: string, percent: number, resetsAt: number | null }[]} */ ([]),
|
|
222
|
+
failure = /** @type {string | null} */ (null),
|
|
223
|
+
scope = /** @type {string | null} */ (null),
|
|
224
|
+
held = /** @type {string | null} */ (null),
|
|
225
|
+
}) {
|
|
226
|
+
return {
|
|
227
|
+
at,
|
|
228
|
+
kind: 'failure',
|
|
229
|
+
err: label(error),
|
|
230
|
+
details: typeof details === 'string' && details ? details.slice(0, FAILURE_DETAILS_CHARS) : null,
|
|
231
|
+
limits: limits.slice(0, FAILURE_LIMITS).map((limit) => ({
|
|
232
|
+
kind: label(limit.kind),
|
|
233
|
+
pct: round(limit.percent, 1),
|
|
234
|
+
resets: Number.isFinite(limit.resetsAt) ? limit.resetsAt : null,
|
|
235
|
+
})),
|
|
236
|
+
fail: label(failure),
|
|
237
|
+
scope: label(scope),
|
|
238
|
+
held: label(held),
|
|
239
|
+
};
|
|
240
|
+
}
|
|
241
|
+
|
|
210
242
|
// A turn keeps its first row (the start) and its newest others up to MAX_TURN_ROWS: a long turn reviewed every few
|
|
211
243
|
// requests must not push the session's earlier turns out of MAX_ROWS.
|
|
212
244
|
export const MAX_TURN_ROWS = 10;
|
|
@@ -236,6 +268,8 @@ export function emptyDecisions() {
|
|
|
236
268
|
}
|
|
237
269
|
|
|
238
270
|
const nullable = (check) => (v) => v === null || Boolean(check(v));
|
|
271
|
+
const isLimitReading = (v) =>
|
|
272
|
+
isRecord(v) && nullable(label)(v.kind) && nullable(Number.isFinite)(v.pct) && nullable(Number.isFinite)(v.resets);
|
|
239
273
|
const ROW_FIELDS = {
|
|
240
274
|
at: Number.isFinite,
|
|
241
275
|
kind: (v) => ROW_KINDS.includes(v),
|
|
@@ -265,6 +299,11 @@ const ROW_FIELDS = {
|
|
|
265
299
|
requests: Number.isSafeInteger,
|
|
266
300
|
priced: Number.isSafeInteger,
|
|
267
301
|
unpriced: (v) => isRecord(v) && Object.values(v).every((n) => Number.isSafeInteger(n) && n >= 0),
|
|
302
|
+
details: nullable((v) => typeof v === 'string' && v.length <= FAILURE_DETAILS_CHARS),
|
|
303
|
+
limits: (v) => Array.isArray(v) && v.length <= FAILURE_LIMITS && v.every(isLimitReading),
|
|
304
|
+
fail: nullable(label),
|
|
305
|
+
scope: nullable(label),
|
|
306
|
+
held: nullable(label),
|
|
268
307
|
};
|
|
269
308
|
|
|
270
309
|
// A row with only its known fields of the right type, or null when its time or kind does not read. A row a later
|
|
@@ -347,11 +386,17 @@ function endLine(row) {
|
|
|
347
386
|
.join(' ');
|
|
348
387
|
}
|
|
349
388
|
|
|
389
|
+
function failureLine(row) {
|
|
390
|
+
const held = row.fail ? [row.fail, 'held', row.scope, row.held] : ['held nothing'];
|
|
391
|
+
return [clock(row.at), 'failure ', row.err ?? 'unknown error', held.filter(Boolean).join(' ')].join(' ');
|
|
392
|
+
}
|
|
393
|
+
|
|
350
394
|
// The newest `n` rows as lines for `/router decisions`, oldest first.
|
|
351
395
|
export function decisionLines(rows, n = 20) {
|
|
352
396
|
if (!rows.length) return ['No routing decisions recorded in this session yet.'];
|
|
353
397
|
return rows.slice(-n).map((row) => {
|
|
354
398
|
if (row.kind === 'end') return endLine(row);
|
|
399
|
+
if (row.kind === 'failure') return failureLine(row);
|
|
355
400
|
const activity = row.act ? ` ${row.phase ? 'goal ' : ''}${row.act}${share(row.actP)}` : '';
|
|
356
401
|
const phase = row.phase ? `phase ${row.phase}${share(row.phaseP)}` : null;
|
|
357
402
|
const asked = row.cls ? `${row.cls}${share(row.p)}${activity}` : (row.err ?? 'no answer');
|
package/lib/display.mjs
CHANGED
|
@@ -203,8 +203,9 @@ export const classifierWarns = (error) => CLASSIFIER_ERRORS[error]?.warn === tru
|
|
|
203
203
|
// No error, or one outside the table, times the wait.
|
|
204
204
|
export const classifierTimed = (error) => CLASSIFIER_ERRORS[error]?.timed !== false;
|
|
205
205
|
// A glyph and at most three words for every reason: the band, the pane's Why, the switch toast and the subagent row
|
|
206
|
-
// say the same. The
|
|
207
|
-
//
|
|
206
|
+
// say the same. The exception is `model-held`: the band, Why and toast name the holder and its end instead
|
|
207
|
+
// (holds.mjs heldCause, heldWhy) when they can, and the subagent row and the route line keep this text. The glyph is
|
|
208
|
+
// the direction: ↑ stronger, ↓ cheaper, = stays, … waits, ! fault, ⏵ pin. REASONS holds the sentence /router prints.
|
|
208
209
|
export const SHORT_REASONS = {
|
|
209
210
|
ready: 'ready',
|
|
210
211
|
'same-tier': '= fits',
|