@alexeiled/claude-router 1.5.1 → 1.6.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/panel.mjs CHANGED
@@ -1,5 +1,21 @@
1
- import { activeClassifier, effectiveRoutes, sameRoute, TIERS, tuningOf } from './config.mjs';
1
+ import { compareRoutes } from './activity.mjs';
2
2
  import {
3
+ ACTIVITIES,
4
+ ACTIVITY_MODES,
5
+ activeClassifier,
6
+ DEFAULTS,
7
+ effectiveActivities,
8
+ effectiveRoutes,
9
+ resolveRoute,
10
+ sameCell,
11
+ sameRoute,
12
+ TIERS,
13
+ tuningOf,
14
+ } from './config.mjs';
15
+ import {
16
+ ACTIVITY_LETTER,
17
+ activityReading,
18
+ activityRouteText,
3
19
  bar,
4
20
  classifierLabel,
5
21
  classifierStatus,
@@ -13,6 +29,7 @@ import {
13
29
  percent,
14
30
  REASONS,
15
31
  routeLabel,
32
+ routeName,
16
33
  sparkline,
17
34
  switchCount,
18
35
  TIER_COLOR,
@@ -35,15 +52,22 @@ const TUNING_CHOICES = {
35
52
  const LADDER = [...TIERS].reverse();
36
53
  const SESSION_EFFORT = 'session';
37
54
 
38
- function routeName(config, route) {
39
- const model = config.models[route.model];
40
- return `${modelName(model.id)}${model.efforts.length ? ` · ${route.effort ?? SESSION_EFFORT}` : ''}`;
41
- }
55
+ const ACTIVITY_MODE_HINT = {
56
+ off: 'asks nothing new; tier routes only',
57
+ shadow: 'asks and shows what on would do; tier routes run',
58
+ on: 'activity overrides run',
59
+ };
60
+ const EFFORT_SHORT = { low: 'low', medium: 'med', high: 'high', xhigh: 'xh', max: 'max' };
42
61
 
43
- // The route draft the Routing tab edits: the saved routes until the person changes one.
62
+ // The route draft the Routing tab edits: the saved routes, activity overrides and mode until the person changes one.
44
63
  export function routeDraftOf(config, view) {
45
64
  if (view.routeDraft) return view.routeDraft;
46
- const base = structuredClone({ routes: config.routes, baselineTier: config.baselineTier });
65
+ const base = structuredClone({
66
+ routes: config.routes,
67
+ baselineTier: config.baselineTier,
68
+ activities: config.activities,
69
+ activityRouting: config.activityRouting,
70
+ });
47
71
  return { ...structuredClone(base), base };
48
72
  }
49
73
 
@@ -163,15 +187,25 @@ function nowTab(ui, config, view, usage, actions) {
163
187
  const label = classifierLabel(config);
164
188
  const missing = missingCredentials(config, view, config.classifier);
165
189
  const served = view.actualModel && current && !isSameModel(current, view.actualModel);
190
+ const reading = config.activityRouting === 'off' ? null : activityReading(view);
191
+ const route = activityRouteText(config, view);
166
192
  const out = [
167
- ui.line('Now ', view.tier ? ui.tier(view.tier, `▌${view.tier} `) : null, routeLabel(current, view.effort)),
168
- ui.line('Why ', REASONS[view.reason] ?? view.reason ?? 'ready'),
193
+ ui.line('Now ', view.tier ? ui.tier(view.tier, `▌${view.tier} `) : null, routeLabel(current, view.effort)),
194
+ reading
195
+ ? ui.line(
196
+ 'Activity ',
197
+ `${reading.choice}${reading.share ? ` ${reading.share}` : ''}`,
198
+ reading.others.length ? ui.dim(` ${reading.others.join(' · ')}`) : null,
199
+ )
200
+ : null,
201
+ ui.line('Why ', REASONS[view.reason] ?? view.reason ?? 'ready'),
202
+ route ? ui.line('Route ', route) : null,
169
203
  served
170
- ? ui.line(ui.text('Served ', { color: 'yellow' }), `${modelName(view.actualModel)} · native fallback`)
204
+ ? ui.line(ui.text('Served ', { color: 'yellow' }), `${modelName(view.actualModel)} · native fallback`)
171
205
  : null,
172
206
  view.pendingPin
173
207
  ? ui.line(
174
- ui.text('Pinned ', { color: 'yellow' }),
208
+ ui.text('Pinned ', { color: 'yellow' }),
175
209
  'next turn → ',
176
210
  ui.tier(view.pendingPin),
177
211
  ' ',
@@ -236,10 +270,13 @@ function nowTab(ui, config, view, usage, actions) {
236
270
  }
237
271
 
238
272
  // One cell per reply, colored by the tier that served it; a dot where routing did not choose (routing off, fallback).
273
+ // Under it, the reply's activity letter, aligned from the end: a view from before 1.6 has fewer activities.
239
274
  function replies(ui, view) {
240
275
  const tiers = view.tiers ?? [];
241
276
  if (!tiers.length) return [ui.head('REPLIES'), ui.dim(' no replies yet')];
242
277
  const switches = switchCount(tiers);
278
+ const activities = view.activities ?? [];
279
+ const letters = tiers.map((_, i) => activities[activities.length - tiers.length + i] ?? null);
243
280
  return [
244
281
  ui.head(`REPLIES · last ${tiers.length}`),
245
282
  ui.line(
@@ -247,7 +284,13 @@ function replies(ui, view) {
247
284
  ...tiers.map((tier) => (tier ? ui.tier(tier, '█') : ui.dim('·'))),
248
285
  ui.dim(` ${switches} switch${switches === 1 ? '' : 'es'}`),
249
286
  ),
287
+ ...(letters.some(Boolean)
288
+ ? [ui.line(' ', ...letters.map((activity) => (activity ? ui.text(ACTIVITY_LETTER[activity]) : ui.dim('·'))))]
289
+ : []),
250
290
  ui.line(' ', ...TIERS.flatMap((tier) => [ui.tier(tier, '■ '), `${tier} `])),
291
+ ...(letters.some(Boolean)
292
+ ? [ui.dim(` ${ACTIVITIES.map((activity) => `${ACTIVITY_LETTER[activity]} ${activity}`).join(' ')}`)]
293
+ : []),
251
294
  ];
252
295
  }
253
296
 
@@ -259,19 +302,27 @@ const POLICY_ROWS = [
259
302
  ['cashCapUsd', 'Credits cap', (v) => `$${v.toFixed(2)}`, 'max cold write on credits', 'policy.cashCapUsd'],
260
303
  ];
261
304
 
262
- // What the Routing tab changed and has not saved: tiers and baseline against the saved routes, policy values against
263
- // the values the draft started from.
305
+ // What the Routing tab changed and has not saved: tiers, baseline, activity cells and mode against the saved config,
306
+ // policy values against the values the draft started from. `cells` lists [activity, tier] pairs.
264
307
  export function routingChanges(config, view) {
265
- const draft = effectiveRoutes(routeDraftOf(config, view), config);
308
+ const raw = routeDraftOf(config, view);
309
+ const draft = { ...effectiveRoutes(raw, config), ...effectiveActivities(raw, config) };
266
310
  const saved = tuningOf(config);
267
311
  const base = view.tuningBase ?? saved;
268
312
  const tuning = { ...saved, ...view.tuning };
269
313
  const tiers = TIERS.filter((tier) => !sameRoute(draft.routes[tier], config.routes[tier]));
270
314
  const baseline = draft.baselineTier !== config.baselineTier;
315
+ const cells = ACTIVITIES.flatMap((activity) =>
316
+ TIERS.filter((tier) => !sameCell(draft.activities[activity]?.[tier], config.activities[activity]?.[tier])).map(
317
+ (tier) => [activity, tier],
318
+ ),
319
+ );
320
+ const mode = draft.activityRouting !== config.activityRouting;
271
321
  const policy = POLICY_ROWS.map(([key]) => key).filter(
272
322
  (key) => Object.hasOwn(view.tuning ?? {}, key) && view.tuning[key] !== base[key],
273
323
  );
274
- return { draft, saved, tuning, tiers, baseline, policy, count: tiers.length + Number(baseline) + policy.length };
324
+ const count = tiers.length + Number(baseline) + cells.length + Number(mode) + policy.length;
325
+ return { draft, saved, tuning, tiers, baseline, cells, mode, policy, count };
275
326
  }
276
327
 
277
328
  const marker = (ui, changed) => ui.cell(2, changed ? ui.text('●', { color: 'yellow' }) : '');
@@ -279,7 +330,8 @@ const marker = (ui, changed) => ui.cell(2, changed ? ui.text('●', { color: 'ye
279
330
  // Routes and policy are edited as one set: the switch-cost lines read the whole ladder, so nothing here is written
280
331
  // until Save in the status bar.
281
332
  function routingTab(ui, config, view, _usage, actions, modelOptions) {
282
- const { draft, tuning, tiers, baseline, policy } = routingChanges(config, view);
333
+ const changes = routingChanges(config, view);
334
+ const { draft, tuning, tiers, baseline, policy } = changes;
283
335
  const out = [
284
336
  ui.line(ui.head('ROUTES'), ui.dim(' · applies next turn · edit, then Save')),
285
337
  ui.dim(`${'tier'.padEnd(8)}${'model'.padEnd(14)}${'effort'.padEnd(14)}${'$/M in · out'.padEnd(14)}window`),
@@ -340,21 +392,12 @@ function routingTab(ui, config, view, _usage, actions, modelOptions) {
340
392
  ),
341
393
  ui.text(' '),
342
394
  ui.head('SWITCH COST · from these routes'),
343
- );
344
- for (let i = 0; i < LADDER.length - 1; i += 1) {
345
- const upper = draft.routes[LADDER[i]];
346
- const lower = draft.routes[LADDER[i + 1]];
347
- const pair = `${LADDER[i + 1]} → ${LADDER[i]}`.padEnd(16);
348
- if (sameRoute(upper, lower))
349
- out.push(ui.line(ui.text('! ', { color: 'yellow' }), pair, 'identical: this step changes nothing'));
350
- else if (upper.model === lower.model)
351
- out.push(ui.line(ui.dim('· '), pair, 'same model, new effort: priced as a new cache'));
352
- else out.push(ui.line(ui.dim('· '), pair, 'model change: priced as a cold cache write'));
353
- }
354
- out.push(
395
+ ...switchCost(ui, draft.routes),
355
396
  ui.Button({ key: 'reset-routes', label: 'Reset routes to defaults', hotkey: 'r', onPress: actions.resetRoutes }),
356
397
  ui.dim('A new model ID needs router.json → models: price, window, efforts.'),
357
398
  ui.text(' '),
399
+ ...activitySections(ui, config, changes, actions, modelOptions),
400
+ ui.text(' '),
358
401
  ui.line(ui.head('POLICY'), ui.dim(' · applies next turn · edit, then Save')),
359
402
  ...POLICY_ROWS.map(([key, label, format, hint]) =>
360
403
  ui.line(
@@ -379,6 +422,162 @@ function routingTab(ui, config, view, _usage, actions, modelOptions) {
379
422
  return out;
380
423
  }
381
424
 
425
+ function switchCost(ui, routes) {
426
+ return LADDER.slice(0, -1).map((upperTier, i) => {
427
+ const upper = routes[upperTier];
428
+ const lower = routes[LADDER[i + 1]];
429
+ const pair = `${LADDER[i + 1]} → ${upperTier}`.padEnd(16);
430
+ if (sameRoute(upper, lower))
431
+ return ui.line(ui.text('! ', { color: 'yellow' }), pair, 'identical: this step changes nothing');
432
+ if (upper.model === lower.model)
433
+ return ui.line(ui.dim('· '), pair, 'same model, new effort: priced as a new cache');
434
+ return ui.line(ui.dim('· '), pair, 'model change: priced as a cold cache write');
435
+ });
436
+ }
437
+
438
+ // "S·med": the model's initial and a short effort, for the matrix.
439
+ function shortRoute(config, route) {
440
+ const model = config.models[route.model];
441
+ const effort = model.efforts.length ? `·${EFFORT_SHORT[route.effort] ?? 'ses'}` : '';
442
+ return `${modelName(model.id)[0]}${effort}`;
443
+ }
444
+ const routeKey = (route) => `${route.model}@${route.effort ?? ''}`;
445
+
446
+ // Why an override may be a mistake: no effect, a route above the next tier's, or a pair no other cell runs.
447
+ function overrideWarnings(config, uses, activity, tier) {
448
+ const route = resolveRoute(config, tier, activity);
449
+ if (sameRoute(route, config.routes[tier])) return ['same as base: no effect'];
450
+ const above = config.routes[TIERS[TIERS.indexOf(tier) + 1]];
451
+ return [
452
+ above && compareRoutes(config, route, above) > 0 ? 'stronger than the tier above' : null,
453
+ uses.get(routeKey(route)) === 1 ? 'new (model, effort) pair: one more cache' : null,
454
+ ].filter(Boolean);
455
+ }
456
+
457
+ // ACTIVITIES, the effective matrix of the draft, and OVERRIDES, its editable cells. Both join the routing draft.
458
+ function activitySections(ui, config, changes, actions, modelOptions) {
459
+ const draft = { ...config, ...changes.draft };
460
+ const mode = draft.activityRouting;
461
+ const cellRoutes = ACTIVITIES.flatMap((activity) => TIERS.map((tier) => resolveRoute(draft, tier, activity)));
462
+ const uses = new Map();
463
+ for (const route of [...TIERS.map((tier) => draft.routes[tier]), ...cellRoutes])
464
+ uses.set(routeKey(route), (uses.get(routeKey(route)) ?? 0) + 1);
465
+ // Activities with the same row share it, so the matrix stays as short as the overrides are few.
466
+ const rows = new Map();
467
+ for (const activity of ACTIVITIES) {
468
+ const cells = TIERS.map((tier) => {
469
+ const route = resolveRoute(draft, tier, activity);
470
+ return sameRoute(route, draft.routes[tier]) ? '·' : shortRoute(draft, route);
471
+ });
472
+ const row = rows.get(cells.join()) ?? { names: [], cells };
473
+ rows.set(cells.join(), { ...row, names: [...row.names, activity] });
474
+ }
475
+ const distinct = uses.size;
476
+ const matrixRow = (name, cells) => ui.text(` ${name.padEnd(30)}${cells.map((c) => c.padEnd(9)).join('')}`);
477
+ const out = [
478
+ ui.line(ui.cell(32, ui.head(`ACTIVITIES · routing ${mode}`)), ui.dim(TIERS.map((t) => t.padEnd(9)).join(''))),
479
+ matrixRow(
480
+ 'base',
481
+ TIERS.map((tier) => shortRoute(draft, draft.routes[tier])),
482
+ ),
483
+ ...[...rows.values()].map(({ names, cells }) => matrixRow(names.join(' '), cells)),
484
+ ui.dim(
485
+ ` ${distinct} distinct route${distinct === 1 ? '' : 's'} = ${distinct} cache${distinct === 1 ? '' : 's'}` +
486
+ `${mode === 'on' ? '' : ' once activity routing is on'}`,
487
+ ),
488
+ ui.text(' '),
489
+ ui.line(ui.head('OVERRIDES'), ui.dim(' · applies next turn · edit, then Save')),
490
+ ui.line(
491
+ ui.cell(
492
+ 26,
493
+ ui.Select
494
+ ? ui.Select({
495
+ key: 'activity-mode',
496
+ label: 'Activity routing',
497
+ value: mode,
498
+ options: ACTIVITY_MODES.map((m) => ({ value: m, label: m })),
499
+ onSelect: (m) => actions.activityMode(m),
500
+ })
501
+ : `Activity routing: ${mode}`,
502
+ ),
503
+ marker(ui, changes.mode),
504
+ ui.dim(ACTIVITY_MODE_HINT[mode]),
505
+ ),
506
+ ];
507
+ const free = [];
508
+ for (const activity of ACTIVITIES) {
509
+ for (const tier of TIERS) {
510
+ const edited = changes.cells.some(([a, t]) => a === activity && t === tier);
511
+ const route = resolveRoute(draft, tier, activity);
512
+ // A built-in override set to the tier's route is how a removal is saved: it lists as free, not as no effect.
513
+ const removed =
514
+ sameRoute(route, draft.routes[tier]) && DEFAULTS.activities[activity]?.[tier] !== undefined && !edited;
515
+ if (!draft.activities[activity]?.[tier] || removed) {
516
+ free.push([activity, tier]);
517
+ continue;
518
+ }
519
+ out.push(overrideRow(ui, draft, route, activity, tier, edited, actions, modelOptions, uses));
520
+ }
521
+ }
522
+ if (ui.Select && free.length)
523
+ out.push(
524
+ ui.Select({
525
+ key: 'activity-add',
526
+ value: '',
527
+ options: [
528
+ { value: '', label: 'add an override…' },
529
+ ...free.map(([activity, tier]) => ({ value: `${activity}.${tier}`, label: `${activity} at ${tier}` })),
530
+ ],
531
+ onSelect: (picked) => {
532
+ const [activity, tier] = picked.split('.');
533
+ return tier ? actions.addActivity(activity, tier) : undefined;
534
+ },
535
+ }),
536
+ );
537
+ return out;
538
+ }
539
+
540
+ function overrideRow(ui, draft, route, activity, tier, edited, actions, modelOptions, uses) {
541
+ const model = draft.models[route.model];
542
+ const aliases = modelOptions.includes(route.model) ? modelOptions : [route.model, ...modelOptions];
543
+ const warnings = overrideWarnings(draft, uses, activity, tier);
544
+ return ui.line(
545
+ ui.cell(10, activity),
546
+ ui.cell(8, ui.tier(tier)),
547
+ ui.cell(
548
+ 14,
549
+ ui.Select
550
+ ? ui.Select({
551
+ key: `activity-model-${activity}-${tier}`,
552
+ value: route.model,
553
+ options: aliases.map((alias) => ({ value: alias, label: modelName(draft.models[alias].id) })),
554
+ onSelect: (alias) => actions.activityModel(activity, tier, alias),
555
+ })
556
+ : modelName(model.id),
557
+ ),
558
+ ui.cell(
559
+ 12,
560
+ !model.efforts.length
561
+ ? ui.dim('none')
562
+ : ui.Select
563
+ ? ui.Select({
564
+ key: `activity-effort-${activity}-${tier}`,
565
+ value: route.effort ?? SESSION_EFFORT,
566
+ options: [SESSION_EFFORT, ...model.efforts].map((effort) => ({ value: effort, label: effort })),
567
+ onSelect: (effort) => actions.activityEffort(activity, tier, effort === SESSION_EFFORT ? null : effort),
568
+ })
569
+ : (route.effort ?? SESSION_EFFORT),
570
+ ),
571
+ marker(ui, edited),
572
+ ui.Button({
573
+ key: `activity-remove-${activity}-${tier}`,
574
+ label: 'remove',
575
+ onPress: () => actions.removeActivity(activity, tier),
576
+ }),
577
+ warnings.length ? ui.text(` ${warnings.join(' · ')}`, { color: 'yellow' }) : null,
578
+ );
579
+ }
580
+
382
581
  // A Select over TUNING_CHOICES[key], with a saved value outside them kept as the first option.
383
582
  function choice(ui, key, value, format, pick) {
384
583
  if (!ui.Select) return format(value);
@@ -467,6 +666,14 @@ function statusBar(ui, config, view, actions) {
467
666
  ),
468
667
  );
469
668
  if (changes.baseline) out.push(...diff('baselineTier', config.baselineTier, changes.draft.baselineTier));
669
+ const draft = { ...config, ...changes.draft };
670
+ const cellName = (c, activity, tier) =>
671
+ c.activities[activity]?.[tier] ? routeName(c, resolveRoute(c, tier, activity)) : 'no override';
672
+ for (const [activity, tier] of changes.cells)
673
+ out.push(
674
+ ...diff(`activities.${activity}.${tier}`, cellName(config, activity, tier), cellName(draft, activity, tier)),
675
+ );
676
+ if (changes.mode) out.push(...diff('activityRouting', config.activityRouting, changes.draft.activityRouting));
470
677
  for (const [key, , format, , field] of POLICY_ROWS.filter(([key]) => changes.policy.includes(key)))
471
678
  out.push(...diff(field, format(changes.saved[key]), format(changes.tuning[key])));
472
679
  out.push(
@@ -493,7 +700,56 @@ function statusBar(ui, config, view, actions) {
493
700
  return out;
494
701
  }
495
702
 
496
- function usageTab(ui, config, view, usage) {
703
+ // Session counts by activity, the switches by cause, the tool agreement and the shadow readout. Counts only: what the
704
+ // would-route turns cost is not recorded, so no dollar figure is shown. Reset is always offered: the counts kept
705
+ // across sessions may exist before this session has any.
706
+ function activityUsage(ui, config, view, actions) {
707
+ const stats = view.activityStats ?? null;
708
+ const mode = config.activityRouting;
709
+ const reset = ui.Button({
710
+ key: 'reset-activity-stats',
711
+ label: 'Reset activity stats',
712
+ onPress: actions.resetActivityStats,
713
+ });
714
+ if (mode === 'off' && !stats)
715
+ return [
716
+ ui.head('ACTIVITY · routing off'),
717
+ ui.dim(' Not asked. Set activity routing to shadow or on in the Routing tab.'),
718
+ reset,
719
+ ];
720
+ const out = [ui.line(ui.head('ACTIVITY · this session'), ui.dim(` routing ${mode}`))];
721
+ const rows = Object.entries(stats?.byActivity ?? {}).filter(([, counts]) => counts?.turns > 0);
722
+ if (!rows.length) out.push(ui.dim(' no activity readings yet'));
723
+ else {
724
+ const total = rows.reduce((sum, [, counts]) => sum + counts.turns, 0);
725
+ out.push(
726
+ ui.dim(` ${''.padEnd(9)}${''.padEnd(10)}${'turns'.padStart(7)}${'requests'.padStart(10)}${'share'.padStart(7)}`),
727
+ );
728
+ for (const [name, counts] of rows.sort((a, b) => b[1].turns - a[1].turns)) {
729
+ const share = counts.turns / total;
730
+ out.push(
731
+ ui.line(
732
+ ` ${name.padEnd(9)}`,
733
+ ui.text(bar(share, 1, 10).text, { color: 'cyan' }),
734
+ `${String(counts.turns).padStart(7)}${String(counts.requests).padStart(10)}${percent(share).padStart(7)}`,
735
+ ),
736
+ );
737
+ }
738
+ }
739
+ if (stats) {
740
+ const { tier, activity } = stats.switches;
741
+ out.push(ui.text(`Switches ${tier + activity} · ${tier} by tier · ${activity} by activity`));
742
+ const { matched, total } = stats.agreement;
743
+ if (total > 0)
744
+ out.push(ui.text(`Agreement classifier vs tools: ${matched} of ${total} turns (${percent(matched / total)})`));
745
+ if (mode === 'shadow' || stats.shadow.turns > 0)
746
+ out.push(ui.text(`Shadow on would route ${stats.shadow.differs} of ${stats.shadow.turns} turns differently`));
747
+ }
748
+ out.push(reset);
749
+ return out;
750
+ }
751
+
752
+ function usageTab(ui, config, view, usage, actions) {
497
753
  const metrics = usageMetrics(config, view, usage);
498
754
  const history = view.history ?? [];
499
755
  const tiers = view.tiers ?? [];
@@ -523,6 +779,8 @@ function usageTab(ui, config, view, usage) {
523
779
  .filter((limit) => Number.isFinite(limit.percentUsed))
524
780
  .map((limit) => ui.gauge(`${limit.kind.replaceAll('_', ' ').padEnd(11)}`, bar(limit.percentUsed, 100), 'used')),
525
781
  ui.text(' '),
782
+ ...activityUsage(ui, config, view, actions),
783
+ ui.text(' '),
526
784
  ui.head('ESTIMATES · configured list prices'),
527
785
  ui.text(`Cache read benefit ${dollars(metrics.cacheBenefit)}`),
528
786
  Number.isFinite(view.estimate?.taxUsd) ? ui.text(`Switch tax ${dollars(view.estimate.taxUsd)}`) : null,
package/lib/policy.mjs CHANGED
@@ -1,23 +1,38 @@
1
1
  // Switching policy v0 (docs/architecture.md): stickiness, escalation floor, cost-gated votes.
2
- import { rank, routeModel, TIERS } from './config.mjs';
2
+ import { rank, resolveRoute, routeSpec, TIERS } from './config.mjs';
3
3
  import * as nativeCosts from './cost.mjs';
4
4
 
5
5
  export function initialState() {
6
6
  return { turn: 0, votes: [], holdUntilTurn: 0, escalatedSignature: null };
7
7
  }
8
8
 
9
- // Returns { tier, reason, state, estimate }. `baseline` is the tier used when nothing argues otherwise.
10
- export function decide({ config, facts, advice, state, baseline, now, costs = nativeCosts }) {
9
+ // Returns { tier, reason, state, estimate }. `baseline` is the tier used when nothing argues otherwise. Tiers rank the
10
+ // choice; prices come from routes: each candidate tier at `routeFor(tier)`, the incumbent at the route it runs on.
11
+ // `escalateTo(incumbent)` names the tier repeated failures move to, or null when no tier helps: then the failure
12
+ // signature is not consumed.
13
+ export function decide({
14
+ config,
15
+ facts,
16
+ advice,
17
+ state,
18
+ baseline,
19
+ now,
20
+ costs = nativeCosts,
21
+ routeFor = (tier) => resolveRoute(config, tier),
22
+ incumbentRoute = null,
23
+ escalateTo = (tier) => TIERS[rank(tier) + 1] ?? null,
24
+ }) {
11
25
  const next = { ...state, turn: state.turn + 1, votes: [...state.votes] };
12
26
  const incumbent = facts.lastRoute && TIERS.includes(facts.lastRoute) ? facts.lastRoute : baseline;
27
+ const current = incumbentRoute ?? routeFor(incumbent);
13
28
  const stay = (reason, estimate = null) => result(incumbent, reason, next, estimate);
14
29
 
15
- if (facts.failure && facts.failure.signature !== next.escalatedSignature && rank(incumbent) < TIERS.length - 1) {
30
+ const target = facts.failure && facts.failure.signature !== next.escalatedSignature ? escalateTo(incumbent) : null;
31
+ if (target) {
16
32
  next.escalatedSignature = facts.failure.signature;
17
33
  next.holdUntilTurn = next.turn + config.policy.escalationHoldTurns;
18
34
  next.votes = [];
19
- const target = TIERS[rank(incumbent) + 1];
20
- const gated = cashGate(config, target, facts, now, costs);
35
+ const gated = cashGate(config, routeFor(target), facts, now, costs, routeFor);
21
36
  return gated.blocked ? gatedResult(gated, incumbent, next) : result(target, 'escalation', next);
22
37
  }
23
38
  if (next.turn <= next.holdUntilTurn) return stay('hold');
@@ -28,22 +43,27 @@ export function decide({ config, facts, advice, state, baseline, now, costs = na
28
43
  const choice = advice.choice;
29
44
  next.votes = [...next.votes.slice(-2), { tier: choice, turn: next.turn }];
30
45
  if (rank(choice) === rank(incumbent)) return stay('same-tier');
46
+ // Before the first measured reply of a history there is no cache it built, so staying protects nothing and one
47
+ // vote is enough. Facts without the field keep the streak.
48
+ const fresh = facts.historyMeasured === false;
49
+ const upgradeVotes = fresh ? 1 : config.policy.upgradeVotes;
50
+ const downgradeVotes = fresh ? 1 : config.policy.downgradeVotes;
31
51
 
32
52
  if (rank(choice) > rank(incumbent)) {
33
53
  const upgrade = massAbove(advice.probabilities, incumbent);
34
- const gated = cashGate(config, choice, facts, now, costs);
54
+ const gated = cashGate(config, routeFor(choice), facts, now, costs, routeFor);
35
55
  if (gated.blocked) return gatedResult(gated, incumbent, next);
36
- const tax = Math.max(0, costs.switchingTaxUsd(config, choice, incumbent, facts, now));
56
+ const tax = Math.max(0, costs.switchingTaxUsd(config, routeFor(choice), current, facts, now));
37
57
  const threshold =
38
58
  config.policy.upgradeBase + config.policy.upgradeSlope * (tax / (tax + config.policy.upgradePivotUsd));
39
59
  const jump = rank(choice) - rank(incumbent) >= 2 && upgrade >= config.policy.jumpConfidence;
40
60
  const streak = trailing(next.votes, (v) => rank(v.tier) > rank(incumbent));
41
61
  const cache = {
42
- candidate: cacheOf(config, choice, facts, now, costs),
43
- incumbent: cacheOf(config, incumbent, facts, now, costs),
62
+ candidate: cacheOf(config, routeFor(choice), facts, now, costs),
63
+ incumbent: cacheOf(config, current, facts, now, costs),
44
64
  };
45
65
  const estimate = { taxUsd: tax, threshold, upgradeMass: upgrade, streak, cache };
46
- if (jump || (streak >= config.policy.upgradeVotes && upgrade >= threshold))
66
+ if (jump || (streak >= upgradeVotes && upgrade >= threshold))
47
67
  return result(choice, jump ? 'jump' : 'upgrade', next, estimate);
48
68
  return stay('upgrade-pending', estimate);
49
69
  }
@@ -52,12 +72,12 @@ export function decide({ config, facts, advice, state, baseline, now, costs = na
52
72
  const streak = trailing(next.votes, (v) => rank(v.tier) <= rank(choice));
53
73
  // A downgrade is not always cheaper this turn: a cold candidate next to a warm incumbent can pay a bigger cache
54
74
  // write than it saves. The bar rises with that cost, net of what the next turns save, the way the upgrade bar does.
55
- const tax = costs.downgradeTaxUsd(config, choice, incumbent, facts, now, config.policy.downgradeHorizonTurns);
75
+ const tax = costs.downgradeTaxUsd(config, routeFor(choice), current, facts, now, config.policy.downgradeHorizonTurns);
56
76
  const threshold =
57
77
  config.policy.downgradeMass + config.policy.downgradeSlope * (tax / (tax + config.policy.downgradePivotUsd));
58
78
  const estimate = { downgradeMass: support, streak, taxUsd: tax, threshold };
59
- if (support >= threshold && streak >= config.policy.downgradeVotes) {
60
- const gated = cashGate(config, choice, facts, now, costs);
79
+ if (support >= threshold && streak >= downgradeVotes) {
80
+ const gated = cashGate(config, routeFor(choice), facts, now, costs, routeFor);
61
81
  return gated.blocked ? gatedResult(gated, incumbent, next) : result(choice, 'downgrade', next, estimate);
62
82
  }
63
83
  return stay('downgrade-pending', estimate);
@@ -69,8 +89,8 @@ export const CONTEXT_FILL = 0.8;
69
89
 
70
90
  // The lowest tier at or above `tier` whose model fits `tokens` of context. Routes need not grow in window
71
91
  // with rank, so the search falls back to any tier that fits, then to the largest window, keeping `tier` on a tie.
72
- export function fitTier(config, tier, tokens) {
73
- const windowOf = (t) => routeModel(config, t).contextWindow;
92
+ export function fitTier(config, tier, tokens, routeFor = (t) => resolveRoute(config, t)) {
93
+ const windowOf = (t) => routeSpec(config, routeFor(t)).contextWindow;
74
94
  const fits = (t) => tokens <= windowOf(t) * CONTEXT_FILL;
75
95
  if (fits(tier)) return tier;
76
96
  return (
@@ -80,18 +100,17 @@ export function fitTier(config, tier, tokens) {
80
100
  );
81
101
  }
82
102
 
83
- // Cold-write guard: an automatic route (upgrade, downgrade or escalation) to a credits-billed model whose cache is not warm must not start with a cache
103
+ // Cold-write guard: an automatic route (upgrade, downgrade, escalation or activity move) to a credits-billed model whose cache is not warm must not start with a cache
84
104
  // write above `cashCapUsd`. It bounds that one estimated write, not the spend of the turn: a warm cache passes, and
85
105
  // output is not counted.
86
- function cashGate(config, tier, facts, now, costs) {
87
- const alias = config.routes[tier].model;
88
- if (config.models[alias].billing !== 'credits') return { blocked: false };
89
- if (costs.isWarm(facts.models[costs.routeCacheKey(config, tier, facts.effort)], now, config.cache))
106
+ export function cashGate(config, route, facts, now, costs, routeFor = (tier) => resolveRoute(config, tier)) {
107
+ if (routeSpec(config, route).billing !== 'credits') return { blocked: false };
108
+ if (costs.isWarm(facts.models[costs.routeCacheKey(config, route, facts.effort)], now, config.cache))
90
109
  return { blocked: false };
91
- const cold = costs.coldWriteUsd(config, alias, costs.nextContextTokens(facts));
110
+ const cold = costs.coldWriteUsd(config, route.model, costs.nextContextTokens(facts));
92
111
  if (cold <= config.policy.cashCapUsd) return { blocked: false };
93
- const fallback = [...TIERS].reverse().find((t) => routeModel(config, t).billing === 'plan');
94
- const estimate = { coldUsd: cold, cap: config.policy.cashCapUsd, cache: cacheOf(config, tier, facts, now, costs) };
112
+ const fallback = [...TIERS].reverse().find((t) => routeSpec(config, routeFor(t)).billing === 'plan');
113
+ const estimate = { coldUsd: cold, cap: config.policy.cashCapUsd, cache: cacheOf(config, route, facts, now, costs) };
95
114
  return { blocked: true, fallback, estimate };
96
115
  }
97
116
 
@@ -101,8 +120,8 @@ function gatedResult(gated, incumbent, state) {
101
120
  return result(tier, 'cash-gate', state, gated.estimate);
102
121
  }
103
122
 
104
- function cacheOf(config, tier, facts, now, costs) {
105
- return costs.cacheState(facts.models[costs.routeCacheKey(config, tier, facts.effort)], now, config.cache);
123
+ function cacheOf(config, route, facts, now, costs) {
124
+ return costs.cacheState(facts.models[costs.routeCacheKey(config, route, facts.effort)], now, config.cache);
106
125
  }
107
126
 
108
127
  function trailing(votes, predicate) {