@alexeiled/claude-router 1.26.0 → 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/lib/route.mjs CHANGED
@@ -11,7 +11,7 @@ import {
11
11
  import { ACTIVITIES, rank, resolveRoute, routeSpec, sameRoute, TIERS } from './config.mjs';
12
12
  import * as costs from './cost.mjs';
13
13
  import { clip, completedSince, extractFacts, stripReminders } from './facts.mjs';
14
- import { heldModels } from './failover.mjs';
14
+ import { clearedModel, heldIds } from './failover.mjs';
15
15
  import { CONTEXT_FILL, decide, fitTier, initialState, sameTaskOf } from './policy.mjs';
16
16
  import { canonicalModel } from './providers.mjs';
17
17
 
@@ -241,36 +241,73 @@ function opsFloor(config, activity) {
241
241
  // the mode changed: `off` is the 1.5 decision.
242
242
  const activityOf = (config, loop) => (config.activityRouting === 'on' ? (loop.lastActivity ?? null) : null);
243
243
 
244
- // A model an API error held out of routing at `now` (failover.mjs).
245
- const isHeld = (loop, id, now) => heldModels(loop.held, now).some((model) => isSameModel(model, id));
244
+ // The ids of the models held out at `now`: an API error held the model, or its account (failover.mjs). `accountHolds`
245
+ // are the stored account holds, read by the caller.
246
+ const heldOf = (config, loop, accountHolds, now) => heldIds(config, loop.held, accountHolds, now);
247
+ const isHeld = (held, id) => held.some((model) => isSameModel(model, id));
246
248
  // A model this turn cannot send to: one whose context window a request exceeded, or a held-out one.
247
- const withheld = (loop, id, now) => loop.ineligible.includes(id) || isHeld(loop, id, now);
249
+ const withheld = (loop, held, id) => loop.ineligible.includes(id) || isHeld(held, id);
250
+ // Whether a model reads only its own thinking history: a switch into or out of it from another model would break it.
251
+ const needsOwnHistory = (config, id) =>
252
+ Object.values(config.models).some((model) => model.requiresOwnHistory && isSameModel(model.id, id));
253
+ const crossesOwnHistory = (config, from, to) =>
254
+ !isSameModel(from, to) && (needsOwnHistory(config, from) || needsOwnHistory(config, to));
248
255
  // Every tier, nearest to `tier` first; of two as near, the stronger.
249
256
  const nearestTiers = (tier) =>
250
257
  [...TIERS].sort((a, b) => Math.abs(rank(a) - rank(tier)) - Math.abs(rank(b) - rank(tier)) || rank(b) - rank(a));
251
258
 
259
+ // The first target of `source`'s fallback chain that `usable` accepts, as the route and effort it runs and the step it
260
+ // is, or null. A bare entry takes the source's effort, an `alias@effort` entry its own.
261
+ function chainStandIn(config, source, sentEffort, usable) {
262
+ const chain = config.fallbacks?.[source.model] ?? [];
263
+ const wanted = costs.routeEffort(config, source, sentEffort);
264
+ for (const [index, entry] of chain.entries()) {
265
+ const [alias, named = null] = entry.split('@');
266
+ const route = { model: alias, effort: named };
267
+ if (usable(routeSpec(config, route)))
268
+ return {
269
+ route,
270
+ effort: costs.routeEffort(config, route, wanted),
271
+ fallback: { from: source.model, step: index + 1, of: chain.length },
272
+ };
273
+ }
274
+ return null;
275
+ }
276
+
277
+ // The incumbent runs the route in use, not the one config gives its cell now. It is rebuilt from config for a loop from
278
+ // before 1.15, a route whose model left the config or can no longer run (`usable`), and a route kept for an activity
279
+ // that no longer applies (activity routing turned off).
280
+ function incumbentOf(config, loop, facts, last, usable) {
281
+ const tier = TIERS.includes(facts.lastRoute) ? facts.lastRoute : config.baselineTier;
282
+ const inUse = loop.route && usable(loop.route) && (loop.lastActivity ?? null) === last.activity ? loop.route : null;
283
+ return {
284
+ tier,
285
+ activity: last.activity,
286
+ floorActivity: last.floorActivity,
287
+ route: inUse ?? resolveRoute(config, tier, last.activity),
288
+ };
289
+ }
290
+
291
+ const NO_CELL = { tier: null, activity: null, floorActivity: null };
292
+
252
293
  // One decision (plan §5.2) for the cell `{ tier, activity }` it lands on. Outside `on` the activity is null throughout.
253
- function routeTurn(config, loop, { facts, advice, pin, nativeModel, contextKnown, availableModels, now }) {
294
+ function routeTurn(
295
+ config,
296
+ loop,
297
+ { facts, advice, pin, nativeModel, contextKnown, availableModels, accountHolds, now },
298
+ ) {
299
+ const heldNow = heldOf(config, loop, accountHolds, now);
254
300
  const last = {
255
301
  tier: loop.lastRoute,
256
302
  activity: activityOf(config, loop),
257
303
  floorActivity: config.activityRouting === 'on' ? (loop.decision?.floorActivity ?? null) : null,
258
304
  };
259
- const tier0 = TIERS.includes(facts.lastRoute) ? facts.lastRoute : config.baselineTier;
260
- // The incumbent runs the route in use, not the one config gives its cell now. It is rebuilt from config for a loop
261
- // from before 1.15, a route whose model left the config or can no longer run, and a route kept for an activity that
262
- // no longer applies (activity routing turned off).
263
- const usable = (held) => {
305
+ const incumbent = incumbentOf(config, loop, facts, last, (held) => {
264
306
  const model = Object.hasOwn(config.models, held.model) ? config.models[held.model] : null;
265
- return Boolean(model && isModelAllowed(model.id, availableModels, nativeModel) && !withheld(loop, model.id, now));
266
- };
267
- const inUse = loop.route && usable(loop.route) && (loop.lastActivity ?? null) === last.activity ? loop.route : null;
268
- const incumbent = {
269
- tier: tier0,
270
- activity: last.activity,
271
- floorActivity: last.floorActivity,
272
- route: inUse ?? resolveRoute(config, tier0, last.activity),
273
- };
307
+ return Boolean(
308
+ model && isModelAllowed(model.id, availableModels, nativeModel) && !withheld(loop, heldNow, model.id),
309
+ );
310
+ });
274
311
  let result = chooseCell(config, loop, { facts, advice, pin, now }, incumbent);
275
312
  // Restoring last/native provenance can change the floor again, so each candidate resolves its own projection.
276
313
  const preferredRoute = (cell) => resolveRoute(opsFloor(config, cell.floorActivity).config, cell.tier, cell.activity);
@@ -287,68 +324,101 @@ function routeTurn(config, loop, { facts, advice, pin, nativeModel, contextKnown
287
324
  // the first decision the session's own model ran, not the mode's route for its cell.
288
325
  const lastSpec =
289
326
  (!loop.decision && Object.values(config.models).find((m) => isSameModel(m.id, nativeModel))) || specOf(last);
290
- const shrinksUnmeasured = (cell) =>
291
- (!contextKnown || !loop.historyMeasured) && specOf(cell).contextWindow < lastSpec.contextWindow;
292
- const runs = (cell) => {
293
- const model = specOf(cell);
294
- return (
295
- !shrinksUnmeasured(cell) &&
296
- (!facts.hasImages || model.imageInput !== false) &&
297
- isModelAllowed(model.id, availableModels, nativeModel) &&
298
- !withheld(loop, model.id, now)
299
- );
300
- };
301
- const heldOut = (cell) => isHeld(loop, specOf(cell).id, now);
302
- const roomFor = (cell) =>
303
- !contextKnown || costs.nextContextTokens(facts) <= specOf(cell).contextWindow * CONTEXT_FILL;
327
+ const shrinks = (spec) => (!contextKnown || !loop.historyMeasured) && spec.contextWindow < lastSpec.contextWindow;
328
+ const shrinksUnmeasured = (cell) => shrinks(specOf(cell));
329
+ const takes = (spec) =>
330
+ !shrinks(spec) &&
331
+ (!facts.hasImages || spec.imageInput !== false) &&
332
+ isModelAllowed(spec.id, availableModels, nativeModel) &&
333
+ !withheld(loop, heldNow, spec.id);
334
+ const room = (spec) => !contextKnown || costs.nextContextTokens(facts) <= spec.contextWindow * CONTEXT_FILL;
335
+ const runs = (cell) => takes(specOf(cell));
336
+ const heldOut = (cell) => isHeld(heldNow, specOf(cell).id);
337
+ const roomFor = (cell) => room(specOf(cell));
304
338
  const fits = (cell) => runs(cell) && roomFor(cell);
305
- if (contextKnown) {
306
- const cell = result;
307
- const acceptedActivity = cell.floorActivity ?? cell.activity;
308
- const routeFor = (tier) =>
309
- tier === cell.tier ? routeOf(cell) : preferredRoute({ ...cell, tier, activity: acceptedActivity });
310
- const fitted = fitTier(config, result.tier, costs.nextContextTokens(facts), routeFor);
311
- if (fitted !== result.tier)
312
- result = { ...result, tier: fitted, activity: acceptedActivity, reason: 'context-fit', lateral: null };
313
- }
339
+ if (contextKnown) result = fitContext(config, facts, result, { routeOf, preferredRoute });
314
340
  // A lateral outcome describes the cell the lateral rule chose; a context or availability override replaces it.
315
341
  if (shrinksUnmeasured(result)) result = { ...result, ...last, reason: 'context-unknown', lateral: null };
342
+ // The route that stands in for a held-out cell's model this turn: a fallback chain's target, which need not be in any
343
+ // tier. The cell stays the intended one, so the stand-in never becomes `loop.route`.
344
+ /** @type {ReturnType<typeof chainStandIn>} */
345
+ let standIn = null;
346
+ let kept = null;
316
347
  if (!fits(result)) {
317
348
  // A cell labelled with another activity would run, and stick, a route this turn did not choose.
318
349
  const native = cellForModel(config, nativeModel);
319
350
  const acceptedActivity = result.floorActivity ?? result.activity;
320
351
  const tierCell = (tier) => ({ tier, activity: acceptedActivity, floorActivity: result.floorActivity });
321
- // A held-out model is back soon: the nearest tier stands in for it, not the last or the cheapest route.
322
- const cells = heldOut(result)
323
- ? nearestTiers(result.tier).map(tierCell)
324
- : [last, native && { ...native, floorActivity: null }, ...TIERS.map(tierCell)];
325
- const fallback = cells.find(
326
- (cell) => cell && (cell.activity === null || cell.activity === acceptedActivity) && fits(cell),
327
- ) ?? { tier: null, activity: null, floorActivity: null };
328
- // Only the window failed: no route is withheld, the conversation is just too full for every one of them.
329
- const reason = runs(result) ? 'context-full' : heldOut(result) ? 'model-held' : 'model-unavailable';
330
- result = { ...result, ...fallback, reason, lateral: null };
352
+ const source = heldOut(result) ? routeOf(result) : null;
353
+ standIn = source && chainStandIn(config, source, facts.effort, (spec) => takes(spec) && room(spec));
354
+ if (standIn) result = { ...result, reason: 'model-held', lateral: null };
355
+ else {
356
+ const sourceId = source && routeSpec(config, source).id;
357
+ // A held-out model is back soon: the nearest tier stands in for it, not the last or the cheapest route. A model
358
+ // that reads only its own history is neither stood in for nor a stand-in.
359
+ const cells = source
360
+ ? nearestTiers(result.tier)
361
+ .map(tierCell)
362
+ .filter((cell) => !crossesOwnHistory(config, sourceId, specOf(cell).id))
363
+ : [last, native && { ...native, floorActivity: null }, ...TIERS.map(tierCell)];
364
+ const fallback = cells.find(
365
+ (cell) => cell && (cell.activity === null || cell.activity === acceptedActivity) && fits(cell),
366
+ );
367
+ // With no cell to fit, the session model cannot take over a history only the held route reads: it stays.
368
+ if (!fallback && source && crossesOwnHistory(config, sourceId, nativeModel)) kept = source;
369
+ // Only the window failed: no route is withheld, the conversation is just too full for every one of them.
370
+ const reason = runs(result) ? 'context-full' : source ? 'model-held' : 'model-unavailable';
371
+ result = { ...result, ...(fallback ?? NO_CELL), reason, lateral: null };
372
+ }
331
373
  }
332
- const route = result.tier ? routeOf(result) : null;
333
- const model = route ? routeSpec(config, route).id : nativeModel;
334
- const effort = route ? costs.routeEffort(config, route, facts.effort) : facts.effort;
335
- /** @type {object | null} */
336
- let comparison = null;
374
+ const sent = standIn?.route ?? kept ?? (result.tier ? routeOf(result) : null);
375
+ const effort = standIn?.effort ?? (sent ? costs.routeEffort(config, sent, facts.effort) : facts.effort);
337
376
  const candidate = pin ?? advice?.choice;
338
- if (contextKnown && loop.lastRequest && TIERS.includes(candidate) && candidate !== loop.lastRoute) {
339
- const to = preferredRoute({ ...result, tier: candidate, activity: result.floorActivity ?? result.activity });
340
- const from = incumbent.route;
341
- const projected = economicConfig(opsFloor(config, result.floorActivity).config, loop);
342
- const forecast = costs.switchEconomics(projected, to, from, facts, now);
343
- comparison = {
344
- candidate,
345
- incumbent: loop.lastRoute,
346
- ...costs.nextTurnRange(projected, to, from, facts, now),
347
- paybackTurns: forecast?.paybackTurns ?? null,
348
- outputTokens: loop.lastRequest.outputTokens,
349
- };
350
- }
351
- return { ...result, route, model, effort, comparison, pinned: Boolean(pin), requestedPin: pin ?? null };
377
+ const comparison =
378
+ contextKnown && loop.lastRequest && TIERS.includes(candidate) && candidate !== loop.lastRoute
379
+ ? compareSwitch(config, loop, {
380
+ candidate,
381
+ result,
382
+ to: preferredRoute({ ...result, tier: candidate, activity: result.floorActivity ?? result.activity }),
383
+ from: incumbent.route,
384
+ facts,
385
+ now,
386
+ })
387
+ : null;
388
+ return {
389
+ ...result,
390
+ route: sent,
391
+ model: sent ? routeSpec(config, sent).id : nativeModel,
392
+ effort,
393
+ comparison,
394
+ pinned: Boolean(pin),
395
+ requestedPin: pin ?? null,
396
+ ...(standIn ? { fallback: standIn.fallback } : {}),
397
+ };
398
+ }
399
+
400
+ // The cell, moved to the tier whose route the conversation fits when its own does not.
401
+ function fitContext(config, facts, cell, { routeOf, preferredRoute }) {
402
+ const acceptedActivity = cell.floorActivity ?? cell.activity;
403
+ const routeFor = (tier) =>
404
+ tier === cell.tier ? routeOf(cell) : preferredRoute({ ...cell, tier, activity: acceptedActivity });
405
+ const fitted = fitTier(config, cell.tier, costs.nextContextTokens(facts), routeFor);
406
+ return fitted === cell.tier
407
+ ? cell
408
+ : { ...cell, tier: fitted, activity: acceptedActivity, reason: 'context-fit', lateral: null };
409
+ }
410
+
411
+ // What a move to the candidate tier's route `to` would cost and save against the route `from` in use.
412
+ function compareSwitch(config, loop, { candidate, result, to, from, facts, now }) {
413
+ const projected = economicConfig(opsFloor(config, result.floorActivity).config, loop);
414
+ const forecast = costs.switchEconomics(projected, to, from, facts, now);
415
+ return {
416
+ candidate,
417
+ incumbent: loop.lastRoute,
418
+ ...costs.nextTurnRange(projected, to, from, facts, now),
419
+ paybackTurns: forecast?.paybackTurns ?? null,
420
+ outputTokens: loop.lastRequest.outputTokens,
421
+ };
352
422
  }
353
423
 
354
424
  // Nomination carries its source into the gates; only their accepted outcome owns future refit intent.
@@ -487,7 +557,7 @@ export function canMoveUp(config, decision, effort) {
487
557
  // probability. At probability 1 the switching tax never holds it back (the upgrade bar tops out near 0.9): only the
488
558
  // cash gate, priced at the context-fitted route, can. Only up: a move down comes from a classifier review, past its
489
559
  // checks. Returns the loop, unchanged when nothing moves.
490
- export function observedMove(config, loop, { observed, facts, contextKnown, now }) {
560
+ export function observedMove(config, loop, { observed, facts, contextKnown, accountHolds, now }) {
491
561
  const decision = loop.decision;
492
562
  if (!canMoveUp(config, decision, facts.effort) || !ACTIVITIES.includes(observed)) return loop;
493
563
  const from = runningRoute(config, decision);
@@ -497,7 +567,7 @@ export function observedMove(config, loop, { observed, facts, contextKnown, now
497
567
  const to = routeFor(tier);
498
568
  if ((compareRoutes(config, to, from, facts.effort) ?? 0) <= 0) return loop;
499
569
  // A held-out model stays out for the rest of the turn too: routeTurn already kept the turn off it.
500
- if (isHeld(loop, routeSpec(config, to).id, now)) return loop;
570
+ if (isHeld(heldOf(config, loop, accountHolds, now), routeSpec(config, to).id)) return loop;
501
571
  // Without a reliable reading of the context, a smaller window might overflow, as in routeTurn.
502
572
  const window = (route) => routeSpec(config, route).contextWindow;
503
573
  if ((!contextKnown || !loop.historyMeasured) && window(to) < window(from)) return loop;
@@ -528,9 +598,10 @@ export function observedMove(config, loop, { observed, facts, contextKnown, now
528
598
  export function continueRoute(
529
599
  current,
530
600
  loop,
531
- { nativeModel, contextTokens, contextKnown, availableModels, effort, hasImages = false, now },
601
+ { nativeModel, contextTokens, contextKnown, availableModels, effort, hasImages = false, accountHolds, now },
532
602
  ) {
533
603
  if (!loop.decision) return loop;
604
+ const held = heldOf(current, loop, accountHolds, now);
534
605
  // A fit to another tier serves this turn only: `loop.route` stays the route of `lastRoute`, as the tier does.
535
606
  let decision = loop.decision;
536
607
  const work =
@@ -569,7 +640,7 @@ export function continueRoute(
569
640
  return (
570
641
  model.imageInput !== false &&
571
642
  isModelAllowed(model.id, availableModels, nativeModel) &&
572
- !withheld(loop, model.id, now) &&
643
+ !withheld(loop, held, model.id) &&
573
644
  (contextKnown ? contextTokens <= model.contextWindow * CONTEXT_FILL : model.contextWindow >= runningWindow)
574
645
  );
575
646
  });
@@ -585,21 +656,76 @@ export function continueRoute(
585
656
  reason: 'model-unavailable',
586
657
  };
587
658
  }
588
- if (!isModelAllowed(decision.model, availableModels, nativeModel) || withheld(loop, decision.model, now)) {
589
- decision = {
590
- ...decision,
591
- tier: null,
592
- activity: null,
593
- floorActivity: null,
594
- route: null,
595
- model: nativeModel,
596
- effort,
597
- reason: 'model-unavailable',
598
- };
659
+ if (!isModelAllowed(decision.model, availableModels, nativeModel) || withheld(loop, held, decision.model)) {
660
+ const heldOnly = isHeld(held, decision.model) && isModelAllowed(decision.model, availableModels, nativeModel);
661
+ const nativeUsable = !isHeld(held, nativeModel) && !crossesOwnHistory(config, decision.model, nativeModel);
662
+ // Without a reliable reading, a stand-in with a smaller window than the running model's might overflow (as at a
663
+ // turn's start).
664
+ const runningWindow = routeSpec(config, runningRoute(config, decision))?.contextWindow ?? 0;
665
+ const fitsContext = (spec) =>
666
+ contextKnown && loop.historyMeasured
667
+ ? contextTokens <= spec.contextWindow * CONTEXT_FILL
668
+ : spec.contextWindow >= runningWindow;
669
+ const standIn = heldOnly
670
+ ? heldReplacement(config, decision, effort, {
671
+ usable: (spec) =>
672
+ isModelAllowed(spec.id, availableModels, nativeModel) &&
673
+ !withheld(loop, held, spec.id) &&
674
+ !crossesOwnHistory(config, decision.model, spec.id) &&
675
+ (!hasImages || spec.imageInput !== false) &&
676
+ fitsContext(spec),
677
+ tierRoute: (tier) => resolveRoute(config, tier, tierActivity(tier)),
678
+ })
679
+ : null;
680
+ if (standIn) decision = standIn;
681
+ // A held model nothing can replace, and no session model to move the history to, keeps the turn.
682
+ else if (!heldOnly || nativeUsable)
683
+ decision = {
684
+ ...decision,
685
+ tier: null,
686
+ activity: null,
687
+ floorActivity: null,
688
+ route: null,
689
+ model: nativeModel,
690
+ effort,
691
+ reason: 'model-unavailable',
692
+ fallback: undefined,
693
+ };
599
694
  }
600
695
  return { ...loop, decision };
601
696
  }
602
697
 
698
+ // The decision for a turn whose running model became held mid-turn, or null when no route can stand in: the source
699
+ // route's fallback chain, then the nearest tier that runs.
700
+ function heldReplacement(config, decision, effort, { usable, tierRoute }) {
701
+ const source =
702
+ decision.route && Object.hasOwn(config.models, decision.route.model)
703
+ ? decision.route
704
+ : decision.tier && tierRoute(decision.tier);
705
+ const chained = source && chainStandIn(config, source, effort, usable);
706
+ if (chained)
707
+ return {
708
+ ...decision,
709
+ route: chained.route,
710
+ model: routeSpec(config, chained.route).id,
711
+ effort: chained.effort,
712
+ reason: 'model-held',
713
+ fallback: chained.fallback,
714
+ };
715
+ const tier = nearestTiers(decision.tier ?? config.baselineTier).find((t) => usable(routeSpec(config, tierRoute(t))));
716
+ if (!tier) return null;
717
+ const route = tierRoute(tier);
718
+ return {
719
+ ...decision,
720
+ tier,
721
+ route,
722
+ model: routeSpec(config, route).id,
723
+ effort: costs.routeEffort(config, route, effort),
724
+ reason: 'model-held',
725
+ fallback: undefined,
726
+ };
727
+ }
728
+
603
729
  export function observeResponse(config, loop, { usage, requestedModel, effort, stopReason, now }) {
604
730
  // Every request counts toward dwell and reviews; a request on another (model, effort) than the last starts a dwell,
605
731
  // and so does the first one this loop serves: checks from before it ran on a route the router did not choose.
@@ -622,6 +748,11 @@ export function observeResponse(config, loop, { usage, requestedModel, effort, s
622
748
  if (!counts.every((key) => Number.isFinite(usage[key]) && usage[key] >= 0)) return next;
623
749
  const tokens = usage.input_tokens + usage.cache_read_input_tokens + usage.cache_creation_input_tokens;
624
750
  if (tokens === 0) return next;
751
+ // A real reply from the model ends its run of failed retries (failover.mjs).
752
+ if (sameModel) {
753
+ const held = clearedModel(next.held, requestedModel);
754
+ if (held !== next.held) next = { ...next, held };
755
+ }
625
756
  const resolutions = sameModel
626
757
  ? { ...next.resolutions, [requestedModel]: usage.model }
627
758
  : Object.fromEntries(Object.entries(next.resolutions).filter(([model]) => model !== requestedModel));
@@ -9,6 +9,7 @@ import { LINE_MODES } from './route-line.mjs';
9
9
  * @property {string} name
10
10
  * @property {string} description one line, drawn beside the word in the typeahead
11
11
  * @property {string[]} [values] what may follow the word; the typeahead offers each
12
+ * @property {string} [source] a name for values that are not fixed: the hook gives the typeahead the ones that apply now
12
13
  * @property {string} [hint] how the argument hint spells what follows the word; the values when absent
13
14
  */
14
15
 
@@ -21,6 +22,8 @@ export const SUBCOMMANDS = [
21
22
  { name: 'activities', description: 'Activity routing', values: ACTIVITY_MODES },
22
23
  { name: 'line', description: 'The route line after a turn', values: LINE_MODES },
23
24
  { name: 'decisions', description: 'The last routing decisions', hint: '[n]' },
25
+ { name: 'holds', description: 'The models and accounts held out of routing' },
26
+ { name: 'release', description: 'End a hold early', source: 'held', hint: '<model|account>' },
24
27
  { name: 'trace', description: 'Export the shadow traces', values: ['export'], hint: 'export' },
25
28
  ];
26
29
 
@@ -31,16 +34,17 @@ export const argumentHint = () =>
31
34
  `[${SUBCOMMANDS.map((sub) => (slot(sub) ? `${sub.name} ${slot(sub)}` : sub.name)).join('|')}]`;
32
35
 
33
36
  // 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);
37
+ const takes = (sub) => Boolean(sub.values?.length || sub.source);
35
38
 
36
39
  /**
37
40
  * The typeahead rows for the token at the cursor: the words after `/router `, or the values after a word that takes
38
41
  * them. Nothing when the token is not in an argument of `/router`, or nothing matches.
39
42
  * @param {{ text: string, start: number, token: string }} input
40
- * @param {{ describe?: (name: string, value: string) => string | undefined }} [options]
43
+ * @param {{ describe?: (name: string, value: string) => string | undefined, sources?: Record<string, string[]> }} [options]
44
+ * `sources` holds the values of each `source` word that apply now
41
45
  * @returns {{ text: string, label?: string, description?: string }[]}
42
46
  */
43
- export function routerSuggestions({ text, start, token }, { describe } = {}) {
47
+ export function routerSuggestions({ text, start, token }, { describe, sources } = {}) {
44
48
  const lead = text.slice(0, start).match(/^\/router\s+(?:(\S+)\s+)?$/);
45
49
  if (!lead) return [];
46
50
  const typed = token.toLowerCase();
@@ -53,7 +57,7 @@ export function routerSuggestions({ text, start, token }, { describe } = {}) {
53
57
  }));
54
58
  const word = SUBCOMMANDS.find((item) => item.name === lead[1]);
55
59
  if (!word) return [];
56
- return (word.values ?? []).filter(matching).map((value) => {
60
+ return (word.values ?? (word.source ? sources?.[word.source] : undefined) ?? []).filter(matching).map((value) => {
57
61
  const description = describe?.(word.name, value);
58
62
  return { text: value, label: value, ...(description ? { description } : {}) };
59
63
  });
@@ -178,7 +178,7 @@ export function renderGraphicalBand(elements, config, view, usage, opts, actions
178
178
  // to cancel it. Mobile always hands a Select, but an app that did not name it in `draws` is sent an empty Box for
179
179
  // it, and a hook cannot tell which: there the text and ✕ stay beside the Select.
180
180
  const keepsUnpin = !pin || surface === 'mobile';
181
- const all = bandSegments(config, view, usage, actions)
181
+ const all = bandSegments(config, view, usage, actions, now)
182
182
  .filter((s) => keepsUnpin || !s.parts.some((p) => p.button?.key === 'band-unpin'))
183
183
  .map((s) => (s.right ? withoutGauge(s) : s));
184
184
  const segments = fitSegments(all, width);
@@ -34,6 +34,7 @@ export function graphicalNow(ui, model, { columns, now }) {
34
34
  gap: 'lg',
35
35
  children: [
36
36
  nextCard(ui, model.next),
37
+ model.held ? heldCard(ui, model.held) : null,
37
38
  pair,
38
39
  sessionCard(ui, model.session, columns, now),
39
40
  model.decisions.length
@@ -48,6 +49,49 @@ export function graphicalNow(ui, model, { columns, now }) {
48
49
  ];
49
50
  }
50
51
 
52
+ /**
53
+ * @param {any} ui
54
+ * @param {import('../model/now.mjs').HeldOutModel} held
55
+ */
56
+ // HELD OUT: a row per hold with its cause and end in the warning tone, the models it covers under it, and its Release.
57
+ function heldCard(ui, held) {
58
+ const { Box } = ui;
59
+ return ui.section('Held out', { hint: ui.say(held.note) }, [
60
+ ...held.rows.map((row) =>
61
+ Box({
62
+ flexDirection: 'row',
63
+ alignItems: 'center',
64
+ justifyContent: 'space-between',
65
+ gap: 'md',
66
+ children: [
67
+ Box({
68
+ flexDirection: 'column',
69
+ gap: 'xs',
70
+ flexShrink: 1,
71
+ children: [
72
+ Box({
73
+ flexDirection: 'row',
74
+ flexWrap: 'wrap',
75
+ gap: 'sm',
76
+ children: [
77
+ ui.text(row.name, { weight: 'semibold' }),
78
+ ui.text(row.text, { color: ui.color('warning'), tabular: true }),
79
+ ],
80
+ }),
81
+ row.covers ? ui.muted(`Covers ${row.covers}`, { size: 'footnote', wrap: 'wrap' }) : null,
82
+ ].filter(Boolean),
83
+ }),
84
+ Box({
85
+ flexShrink: 0,
86
+ children: [ui.Button({ key: row.release.key, label: row.release.label, onPress: row.release.press })],
87
+ }),
88
+ ],
89
+ }),
90
+ ),
91
+ ui.muted(ui.say(held.footer), { size: 'footnote', wrap: 'wrap' }),
92
+ ]);
93
+ }
94
+
51
95
  /**
52
96
  * @param {any} ui
53
97
  * @param {import('../model/now.mjs').NextModel} next
@@ -21,6 +21,7 @@ export function graphicalRoutes(ui, model, { columns }) {
21
21
  children: [
22
22
  routesCard(ui, model, columns),
23
23
  model.editor ? editorCard(ui, model.editor, model.unsaved) : null,
24
+ model.fallbacks ? fallbacksCard(ui, model.fallbacks) : null,
24
25
  ui.section('Prompt caches', {}, [ui.muted(ui.say(model.cache.text), { wrap: 'wrap' })]),
25
26
  ].filter(Boolean),
26
27
  }),
@@ -224,6 +225,50 @@ function listRows(ui, model) {
224
225
  );
225
226
  }
226
227
 
228
+ /**
229
+ * @param {any} ui
230
+ * @param {import('../model/routes.mjs').FallbacksModel} fallbacks
231
+ */
232
+ // Fallbacks: a card with a row per model that has a chain: its status, then its targets in the order they are tried, a
233
+ // held one ✕ and the one standing in ◀ runs. Read-only.
234
+ function fallbacksCard(ui, fallbacks) {
235
+ const { Box } = ui;
236
+ return ui.section(
237
+ 'Fallbacks',
238
+ { hint: ui.say(fallbacks.note) },
239
+ fallbacks.rows.map((row) =>
240
+ Box({
241
+ flexDirection: 'column',
242
+ gap: 'xs',
243
+ children: [
244
+ Box({
245
+ flexDirection: 'row',
246
+ flexWrap: 'wrap',
247
+ alignItems: 'center',
248
+ gap: 'sm',
249
+ children: [
250
+ ui.text(row.model, { weight: 'semibold' }),
251
+ ui.text(row.status.text, { color: ui.color(row.status.tone), wrap: 'wrap' }),
252
+ ],
253
+ }),
254
+ Box({
255
+ flexDirection: 'row',
256
+ flexWrap: 'wrap',
257
+ alignItems: 'center',
258
+ gap: 'sm',
259
+ children: row.targets.map((target, index) =>
260
+ ui.text(`${index + 1} ${target.label}${target.held ? ' ✕' : ''}${target.runs ? ' ◀ runs' : ''}`, {
261
+ color: ui.color(target.runs ? 'accent' : target.held ? 'warning' : 'primary'),
262
+ tabular: true,
263
+ }),
264
+ ),
265
+ }),
266
+ ],
267
+ }),
268
+ ),
269
+ );
270
+ }
271
+
227
272
  /**
228
273
  * @param {any} ui
229
274
  * @param {import('../model/routes.mjs').RouteEditor} editor
@@ -26,6 +26,7 @@ import {
26
26
  usageMetrics,
27
27
  usd,
28
28
  } from '../../display.mjs';
29
+ import { heldCause } from '../../holds.mjs';
29
30
  import { isSameModel } from '../../route.mjs';
30
31
  import { PASS_WHY } from '../../subagents.mjs';
31
32
  import { isRouting } from '../../view.mjs';
@@ -165,7 +166,7 @@ function gauges(config, view, usage) {
165
166
  return out;
166
167
  }
167
168
 
168
- export function bandSegments(config, view, usage, actions) {
169
+ export function bandSegments(config, view, usage, actions, now = Date.now()) {
169
170
  const native = () => routeParts(view.nativeModel, view.nativeEffort);
170
171
  if (view.phase === 'unavailable')
171
172
  return [
@@ -230,7 +231,9 @@ export function bandSegments(config, view, usage, actions) {
230
231
  ((view.goal && (view.taskPhase || view.goal !== view.activity)) || !reasonNamesActivity(view.reason))
231
232
  ? segment(2, part(activityText, { tone: 'activity', italic: true }))
232
233
  : null;
233
- const reason = segment(1, dim(shortReason(view.reason, reasonActivity(config, view))));
234
+ // A model held out names who holds it and until when, where the reason alone says it failed.
235
+ const held = view.reason === 'model-held' ? heldCause(config, view, now) : null;
236
+ const reason = segment(1, dim(held ? `↷ ${held}` : shortReason(view.reason, reasonActivity(config, view))));
234
237
  // The warning leads and the route yields: when the band is narrow, what to fix matters more than the model kept.
235
238
  if (classifierWarns(view.error))
236
239
  return [
@@ -183,7 +183,7 @@ function unsavedTabs(config, view) {
183
183
  // Success for a write or its undo, danger for a refused write, warning for everything else that needs a look.
184
184
  /** @returns {import('../tokens.mjs').Tone} */
185
185
  const noticeTone = (notice) =>
186
- /^Not saved/.test(notice) ? 'danger' : /^(Saved|Undid|Path copied)/.test(notice) ? 'success' : 'warning';
186
+ /^Not saved/.test(notice) ? 'danger' : /^(Saved|Released|Undid|Path copied)/.test(notice) ? 'success' : 'warning';
187
187
 
188
188
  /**
189
189
  * What each pane tab's model and the frame read: the config, the router view and its usage, the pane's actions, the
@@ -242,7 +242,7 @@ function saveBarOf({ config, view, actions }, tab) {
242
242
  row(field, label, format(changes.saved[key]), format(changes.tuning[key]));
243
243
  const { count } = changes;
244
244
  const listed = DRAFT_TABS.includes(tab);
245
- const confirms = Boolean(view.lastWrite && view.notice?.startsWith('Saved'));
245
+ const confirms = Boolean(view.lastWrite && /^(Saved|Released)/.test(view.notice ?? ''));
246
246
  return {
247
247
  count,
248
248
  // On Routes and Policy the changes are listed; elsewhere only counted.