@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.
@@ -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 { activeHolds, holdModel, holdMs, holdText } from '../lib/failover.mjs';
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, { notice: null, confirmDelete: false, ...(await storeView($, 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(switchToast(cfg, previous, selected.decision, selected.decision.estimate));
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 = { observed, facts, contextKnown: context.known, now: Date.now() };
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. An error that is the model's holds the model the last request ran out of routing for a while
3172
- // (lib/failover.mjs), so the next turn runs another; the hold lives in the loop, which the table and shadow engines
3173
- // read. The `auto` engine routes without holds, so it gets none and no toast claims one.
3174
- async function holdFailedModel($, router, error) {
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 (holdMs(error) === null || !(await ensureInitialized($, router))) return;
3178
- if (router.config.routingEngine === 'auto') return;
3233
+ if (!(await ensureInitialized($, router))) return;
3234
+ const { config } = router;
3179
3235
  const model = router.lastRequested ?? (await $.session.model());
3180
- const ref = { ...LOOP, id: 'main' };
3181
- // A write that lost to a step's own write reads the loop again.
3182
- for (let attempt = 0; attempt < 3; attempt += 1) {
3183
- const { value: loop, version } = await $.state.get(ref);
3184
- if (!loop) return;
3185
- const now = Date.now();
3186
- const held = holdModel(loop.held, model, error, now);
3187
- const written = await $.state.set(ref, { ...loop, held }, { ifVersion: version });
3188
- if (!written.isSet) continue;
3189
- const hold = activeHolds(held, now)[model];
3190
- if (hold && (await modeOf($, router)) === 'auto')
3191
- $.ui.toast(`${modelName(model)} held out of routing: ${holdText(hold, now)}`);
3192
- return;
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.error);
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
- export function switchToast(config, previous, next, estimate) {
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 } = file;
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 glyph is the direction: ↑ stronger, ↓ cheaper, = stays, … waits, ! fault, ⏵ pin. REASONS holds the
207
- // sentence /router prints.
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',