@alexeiled/claude-router 1.23.1 → 1.24.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.
@@ -1,3 +1,4 @@
1
+ import { acceptActivity, acceptPhase } from '../lib/activity.mjs';
1
2
  import {
2
3
  ACTIVITY_CONTRACT,
3
4
  advanceDown,
@@ -20,6 +21,8 @@ import {
20
21
  storeAfterReset,
21
22
  turnActivity,
22
23
  } from '../lib/activity-stats.mjs';
24
+ import { advanceDemand, assessCandidates, initialAutoState, selectTarget } from '../lib/auto-engine.mjs';
25
+ import { autoRoute, observeAutoFallback } from '../lib/auto-route.mjs';
23
26
  import { renderBand, switchToast } from '../lib/band.mjs';
24
27
  import { ClassifierClient } from '../lib/classifier-client.mjs';
25
28
  import { resolveCredentials } from '../lib/classifier-contract.mjs';
@@ -84,6 +87,7 @@ import {
84
87
  hasImages,
85
88
  historySignature,
86
89
  observedActivity,
90
+ progressEvidence,
87
91
  promptIndex,
88
92
  routingBucket,
89
93
  stripReminders,
@@ -92,12 +96,32 @@ import { applyMode, modeLabel, readProjectMode, resolveRoutingMode } from '../li
92
96
  import { renderPanel, routeDraftOf, routingChanges } from '../lib/panel.mjs';
93
97
  import { sameTaskOf } from '../lib/policy.mjs';
94
98
  import { providerFile, providerName } from '../lib/providers.mjs';
99
+ import {
100
+ appendTrace,
101
+ bufferTrace,
102
+ mergeTraceExport,
103
+ newTrace,
104
+ readTrace,
105
+ TRACE_ACTIVE_MS,
106
+ TRACE_EXPORT_BYTES,
107
+ TRACE_PREFIX,
108
+ TRACE_SESSION_BYTES,
109
+ TRACE_STORE_BYTES,
110
+ traceAdmission,
111
+ traceBytes,
112
+ traceConfig,
113
+ traceOperation,
114
+ traceResponse,
115
+ traceVictims,
116
+ } from '../lib/replay-trace.mjs';
95
117
  import {
96
118
  canMoveUp,
97
119
  cellForModel,
98
120
  chooseRoute,
99
121
  continueRoute,
122
+ economicConfig,
100
123
  emptyLoop,
124
+ hasRoutedDecision,
101
125
  isModelAllowed,
102
126
  isNativeFallback,
103
127
  isSameModel,
@@ -235,6 +259,8 @@ const LEDGER_KINDS = Object.keys(LEDGERS);
235
259
  function createRouter(options) {
236
260
  return {
237
261
  options,
262
+ initialized: false,
263
+ initializing: null,
238
264
  config: loadConfig(),
239
265
  // Each turn's config, fixed at turn.start, so a pane save mid-turn does not change the turn.
240
266
  turnConfigs: new Map(),
@@ -259,6 +285,12 @@ function createRouter(options) {
259
285
  // `{ sessionId, record }` once read (`decisionRecord`).
260
286
  turnDecisions: new Map(),
261
287
  decisionRecord: null,
288
+ trace: null,
289
+ traceFreshSession: null,
290
+ traceClearSession: null,
291
+ traceStartedSession: null,
292
+ traceFailures: 0,
293
+ traceOperations: new Map(),
262
294
  controllers: new Set(),
263
295
  turnControllers: new Map(),
264
296
  view: null,
@@ -301,6 +333,302 @@ function createRouter(options) {
301
333
  };
302
334
  }
303
335
 
336
+ // These writes share the main-turn lifecycle with decision rows. There is no background writer.
337
+ // Quota scans fail closed; the host has no transaction spanning scans, deletes and a set.
338
+ function traceFailed(router) {
339
+ if (router.trace) {
340
+ router.trace.lostWrites++;
341
+ router.trace.reasons.add('recorder-error');
342
+ } else router.traceFailures++;
343
+ }
344
+
345
+ async function ensureTrace($, router, e, turn, loop, loaded, fresh) {
346
+ try {
347
+ if (turn.config.routingEngine !== 'shadow' || router.config.routingEngine !== 'shadow') {
348
+ if (router.trace) router.trace.reasons.add('mode-gap');
349
+ return;
350
+ }
351
+ const sessionId = await $.session.id();
352
+ if (router.trace?.sessionId === sessionId && router.trace.record) return;
353
+ const previous = router.trace?.sessionId === sessionId ? router.trace : null;
354
+ const at = Date.now();
355
+ const held = {
356
+ sessionId,
357
+ record: null,
358
+ persisted: null,
359
+ lostWrites: (previous?.lostWrites ?? 0) + router.traceFailures,
360
+ reasons: new Set(previous?.reasons ?? []),
361
+ turns: new Map(),
362
+ nextTurn: 1,
363
+ config: null,
364
+ controls: null,
365
+ };
366
+ router.trace = held;
367
+ router.traceFailures = 0;
368
+ try {
369
+ const raw = await $.store.get(`${TRACE_PREFIX}${sessionId}`);
370
+ held.record = readTrace(raw);
371
+ held.persisted = raw;
372
+ if (raw !== undefined) held.reasons.add(loaded ? 'reload' : 'resume');
373
+ } catch {
374
+ held.lostWrites++;
375
+ held.reasons.add('lost-write');
376
+ }
377
+ let freshHistory = false;
378
+ if (fresh && e.index === 0 && !loaded && held.persisted === undefined) {
379
+ // API history is normalized for this request; startup reminders are user rows, not prior assistant work.
380
+ const messages = await transcript($);
381
+ freshHistory =
382
+ Array.isArray(messages) &&
383
+ messages.length > 0 &&
384
+ messages.every(
385
+ (message) =>
386
+ message?.role === 'user' &&
387
+ Array.isArray(message.content) &&
388
+ message.content.length > 0 &&
389
+ message.content.every((block) => block && typeof block.type === 'string' && block.type.length > 0),
390
+ );
391
+ }
392
+ if (!freshHistory) held.reasons.add('mid-session');
393
+ held.record ??= newTrace(at, { configured: turn.configured, config: turn.config, loop }, [...held.reasons]);
394
+ if (traceBytes(held.record) > TRACE_SESSION_BYTES - 1024) {
395
+ held.record = {
396
+ version: 1,
397
+ startedAt: at,
398
+ updatedAt: at,
399
+ active: true,
400
+ incomplete: ['mid-session', 'store-guard'],
401
+ lostWrites: 0,
402
+ capped: { at, turns: 0, events: 0 },
403
+ events: [],
404
+ };
405
+ held.reasons.add('store-guard');
406
+ }
407
+ held.config = JSON.stringify({ configured: traceConfig(turn.configured), config: traceConfig(turn.config) });
408
+ } catch {
409
+ traceFailed(router);
410
+ }
411
+ }
412
+
413
+ function traceTurn(router, e) {
414
+ const held = router.trace;
415
+ if (!held) return null;
416
+ if (!held.turns.has(e.turnId)) held.turns.set(e.turnId, { number: held.nextTurn++, buffer: null });
417
+ return held.turns.get(e.turnId);
418
+ }
419
+
420
+ function addTrace(router, e, event) {
421
+ try {
422
+ const held = router.trace;
423
+ if (!held || router.config.routingEngine !== 'shadow') return;
424
+ const turn = traceTurn(router, e);
425
+ if (held.record.capped || turn.buffer?.excludedEvents) {
426
+ turn.buffer = { events: [], bytes: 2, excludedEvents: (turn.buffer?.excludedEvents ?? 0) + 1 };
427
+ return;
428
+ }
429
+ const remaining = Math.max(0, TRACE_SESSION_BYTES - traceBytes(held.record) - 1024);
430
+ turn.buffer = bufferTrace(turn.buffer, { ...event, turn: turn.number, index: e.index }, remaining);
431
+ } catch {
432
+ traceFailed(router);
433
+ }
434
+ }
435
+
436
+ function traceOp(router, e, cfg, kind, input, selected, messages = null) {
437
+ try {
438
+ if (cfg.routingEngine !== 'shadow' || !router.trace || router.config.routingEngine !== 'shadow') return;
439
+ if (router.trace.record.capped || traceTurn(router, e).buffer?.excludedEvents) return;
440
+ const operations = router.traceOperations.get(e.turnId) ?? [];
441
+ operations.push(
442
+ traceOperation(
443
+ kind,
444
+ input.now ?? Date.now(),
445
+ { ...input, taskProgress: messages ? progressEvidence(messages) : null },
446
+ selected,
447
+ ),
448
+ );
449
+ router.traceOperations.set(e.turnId, operations);
450
+ } catch {
451
+ traceFailed(router);
452
+ }
453
+ }
454
+
455
+ function traceRequest(router, e, turn, request, mode, loop) {
456
+ try {
457
+ if (turn.config.routingEngine !== 'shadow' || router.config.routingEngine !== 'shadow' || !router.trace) return;
458
+ const cfg = { configured: traceConfig(turn.configured), config: traceConfig(turn.config) };
459
+ const fingerprint = JSON.stringify(cfg);
460
+ if (router.trace.config !== fingerprint) {
461
+ addTrace(router, e, { type: 'config', at: Date.now(), ...cfg });
462
+ router.trace.config = fingerprint;
463
+ }
464
+ if (router.trace.controls) {
465
+ const controls = router.trace.controls;
466
+ router.trace.controls = null;
467
+ if (controls.excludedEvents) {
468
+ const active = traceTurn(router, e);
469
+ active.buffer = {
470
+ events: [],
471
+ bytes: 2,
472
+ excludedEvents: controls.excludedEvents + (active.buffer?.events.length ?? 0),
473
+ };
474
+ } else for (const event of controls.events) addTrace(router, e, event);
475
+ }
476
+ addTrace(router, e, {
477
+ type: 'request',
478
+ at: Date.now(),
479
+ model: request.model,
480
+ effort: request.effort,
481
+ engineModel: e.model,
482
+ engineEffort: e.effort,
483
+ mode,
484
+ messageCount: e.messageCount,
485
+ reviewedAt: loop.reviewedAt,
486
+ observedFrom: loop.observedFrom,
487
+ operations: router.traceOperations.get(e.turnId) ?? [],
488
+ });
489
+ router.traceOperations.delete(e.turnId);
490
+ } catch {
491
+ traceFailed(router);
492
+ }
493
+ }
494
+
495
+ function recordTraceResponse(router, e, request, response, ttl, at) {
496
+ try {
497
+ addTrace(router, e, traceResponse(at, request, response, ttl));
498
+ } catch {
499
+ traceFailed(router);
500
+ }
501
+ }
502
+
503
+ function traceReset(router, event) {
504
+ try {
505
+ router.trace.controls = bufferTrace(router.trace.controls, event, 4096);
506
+ } catch {
507
+ traceFailed(router);
508
+ }
509
+ }
510
+
511
+ function traceControl(router) {
512
+ try {
513
+ if (router.config.routingEngine !== 'shadow' || !router.trace) return;
514
+ const view = router.view;
515
+ const event = {
516
+ type: 'control',
517
+ at: Date.now(),
518
+ mode: view?.routingMode,
519
+ pin: view?.pendingPin,
520
+ enabled: view?.mode !== 'manual',
521
+ };
522
+ router.trace.controls = bufferTrace(router.trace.controls, event, 4096);
523
+ } catch {
524
+ traceFailed(router);
525
+ }
526
+ }
527
+
528
+ async function flushTrace($, router, turnId = null, ending = false) {
529
+ try {
530
+ const held = router.trace;
531
+ if (!held || router.config.routingEngine !== 'shadow') return;
532
+ const turn = held.turns.get(turnId);
533
+ held.turns.delete(turnId);
534
+ try {
535
+ const at = Date.now();
536
+ const keys = await $.store.keys();
537
+ let entries = await Promise.all(keys.map(async (key) => [key, await $.store.get(key)]));
538
+ if (entries.some(([, value]) => value === undefined)) throw new Error('store-guard');
539
+ if (traceBytes(Object.fromEntries(entries)) > TRACE_STORE_BYTES) throw new Error('store-guard');
540
+ const resetAt = entries.find(([name]) => name === SAVINGS_RESET_KEY)?.[1];
541
+ if (Number.isFinite(resetAt) && held.record.startedAt < resetAt) {
542
+ held.record = {
543
+ version: 1,
544
+ startedAt: at,
545
+ updatedAt: at,
546
+ active: true,
547
+ incomplete: ['reset', 'mid-session'],
548
+ lostWrites: 0,
549
+ capped: null,
550
+ events: [],
551
+ };
552
+ held.persisted = undefined;
553
+ held.reasons.add('reset');
554
+ }
555
+ const key = `${TRACE_PREFIX}${held.sessionId}`;
556
+ const raw = entries.find(([name]) => name === key)?.[1];
557
+ if (raw !== undefined && !readTrace(raw)) throw new Error('conflict');
558
+ if (JSON.stringify(raw) !== JSON.stringify(held.persisted)) {
559
+ held.reasons.add('conflict');
560
+ if (raw)
561
+ held.record = mergeTraceExport(null, [
562
+ [key, held.record],
563
+ [key, raw],
564
+ ]).sessions[key];
565
+ }
566
+ if (held.record.events.length === 1 && traceBytes(held.record) > TRACE_SESSION_BYTES - 1024)
567
+ throw new Error('store-guard');
568
+ const events = turn?.buffer?.events ?? [];
569
+ if (ending && held.controls && !held.controls.excludedEvents) events.push(...held.controls.events);
570
+ const candidate = appendTrace(held.record, events, at, {
571
+ lostWrites: held.lostWrites,
572
+ reasons: [...held.reasons],
573
+ excludedEvents: turn?.buffer?.excludedEvents ?? held.controls?.excludedEvents ?? 0,
574
+ });
575
+ candidate.active = !ending;
576
+ const traces = entries.filter(([name]) => name.startsWith(TRACE_PREFIX));
577
+ for (const victim of traceVictims(traces, at, key, candidate)) {
578
+ const previous = entries.find(([name]) => name === victim)?.[1];
579
+ const current = await $.store.get(victim);
580
+ if (
581
+ readTrace(current) &&
582
+ JSON.stringify(current) === JSON.stringify(previous) &&
583
+ !(current.active && at - current.updatedAt <= TRACE_ACTIVE_MS)
584
+ )
585
+ await $.store.delete(victim);
586
+ }
587
+ // Scan again after eviction: missing/unreadable values never become a quota undercount.
588
+ const after = await $.store.keys();
589
+ entries = await Promise.all(after.map(async (name) => [name, await $.store.get(name)]));
590
+ if (entries.some(([, value]) => value === undefined) || !traceAdmission(entries, key, candidate))
591
+ throw new Error('store-guard');
592
+ await $.store.set(key, candidate);
593
+ held.record = candidate;
594
+ held.persisted = candidate;
595
+ held.lostWrites = 0;
596
+ held.reasons.clear();
597
+ if (ending) held.controls = null;
598
+ } catch (error) {
599
+ held.lostWrites++;
600
+ held.reasons.add(
601
+ error.message === 'conflict' ? 'conflict' : error.message === 'store-guard' ? 'store-guard' : 'lost-write',
602
+ );
603
+ }
604
+ } catch {
605
+ traceFailed(router);
606
+ }
607
+ }
608
+
609
+ async function exportTraces($, router) {
610
+ try {
611
+ const keys = (await $.store.keys()).filter((key) => key.startsWith(TRACE_PREFIX));
612
+ const entries = await Promise.all(keys.map(async (key) => [key, await $.store.get(key)]));
613
+ const root = router.config.nativePath.slice(0, router.config.nativePath.lastIndexOf('/'));
614
+ let path = `${root}/router-traces.json`;
615
+ if ((await $.fs.exists(path)) && (await $.fs.stat(path)).isLink) throw new Error('linked export');
616
+ const previous = (await $.fs.exists(path)) ? JSON.parse(await $.fs.read(path)) : null;
617
+ let merged = mergeTraceExport(previous, entries);
618
+ if (traceBytes(merged) > TRACE_EXPORT_BYTES) {
619
+ path = `${root}/router-traces-${new Date().toISOString().replace(/[:.]/g, '-')}.json`;
620
+ if ((await $.fs.exists(path)) && (await $.fs.stat(path)).isLink) throw new Error('linked export');
621
+ const prior = (await $.fs.exists(path)) ? JSON.parse(await $.fs.read(path)) : null;
622
+ merged = mergeTraceExport(prior, entries);
623
+ }
624
+ if (traceBytes(merged) > TRACE_EXPORT_BYTES) return 'Trace export exceeds the file budget; no file changed.';
625
+ await $.fs.write(path, JSON.stringify(merged));
626
+ return `Exported ${Object.keys(merged.sessions).length} retained trace sessions to ${path}.`;
627
+ } catch {
628
+ return 'Trace export failed; retained traces and existing exports were not intentionally removed.';
629
+ }
630
+ }
631
+
304
632
  function clientOf(router, id) {
305
633
  if (!router.clients.has(id)) router.clients.set(id, new ClassifierClient());
306
634
  return router.clients.get(id);
@@ -326,10 +654,14 @@ async function modeOf($, router, fallback = 'auto') {
326
654
  }
327
655
  }
328
656
 
329
- // A saved preference wins; a fresh session starts with routing on for a model some route runs (a tier's, or in `on` an
330
- // activity override's), and off for any other.
657
+ // A saved preference wins. A fresh auto-engine session starts on for any catalog model; table/shadow require a tier
658
+ // route or, with activity routing on, an activity override. Other models start with routing off.
331
659
  async function startMode($, router, model) {
332
- const mode = await modeOf($, router, cellForModel(router.config, model) === null ? 'manual' : 'auto');
660
+ const listed =
661
+ router.config.routingEngine === 'auto'
662
+ ? Object.values(router.config.models).some((spec) => isSameModel(spec.id, model))
663
+ : cellForModel(router.config, model) !== null;
664
+ const mode = await modeOf($, router, listed ? 'auto' : 'manual');
333
665
  router.modes.set(await $.session.id(), mode);
334
666
  return mode;
335
667
  }
@@ -383,7 +715,14 @@ const sameMode = (a, b) => a?.mode === b?.mode && a?.source === b?.source;
383
715
 
384
716
  // A turn's configs when turn.start did not record them, as after a reload of the Mod mid-turn.
385
717
  async function turnConfigOf($, router) {
386
- return { config: applyMode(router.config, await routingModeOf($, router)), configured: router.config };
718
+ const routingMode = await routingModeOf($, router);
719
+ return {
720
+ config:
721
+ router.config.routingEngine === 'auto'
722
+ ? { ...router.config, routingMode }
723
+ : applyMode(router.config, routingMode),
724
+ configured: router.config,
725
+ };
387
726
  }
388
727
 
389
728
  // The turn routes on the configured routes as its routing mode moves them, fixed now so a change mid-turn waits for
@@ -410,6 +749,7 @@ async function setRoutingMode($, router, value) {
410
749
  router.routingModes.set(sessionId, value === 'default' ? null : value);
411
750
  const routingMode = await routingModeOf($, router);
412
751
  await updateView($, router, { routingMode });
752
+ if (router.config.routingEngine === 'shadow') traceControl(router);
413
753
  const unsaved =
414
754
  value === 'default'
415
755
  ? 'A resume of this session may bring the cleared mode back: the store could not be written.'
@@ -563,6 +903,30 @@ async function changeMode($, router, mode) {
563
903
  if (mode === 'manual') {
564
904
  router.afterDown = null;
565
905
  router.offSwitches += 1;
906
+ if (
907
+ router.config.routingEngine === 'auto' ||
908
+ [...router.turnConfigs.values()].some((turn) => turn.config.routingEngine === 'auto')
909
+ ) {
910
+ for (const review of router.reviews.values()) review.controller.abort();
911
+ router.reviews.clear();
912
+ router.decisions.clear();
913
+ const ref = { ...LOOP, id: 'main' };
914
+ const loaded = await $.state.get(ref);
915
+ if (loaded.value)
916
+ await $.state.set(
917
+ ref,
918
+ {
919
+ ...loaded.value,
920
+ hasRoutedDecision: hasRoutedDecision(loaded.value),
921
+ auto: null,
922
+ turnId: null,
923
+ decision: null,
924
+ route: null,
925
+ generation: loaded.value.generation + 1,
926
+ },
927
+ { ifVersion: loaded.version },
928
+ );
929
+ }
566
930
  }
567
931
  router.modes.set(await $.session.id(), mode);
568
932
  const saved = await rememberMode($, mode);
@@ -573,6 +937,7 @@ async function changeMode($, router, mode) {
573
937
  reason: mode === 'manual' ? 'routing off' : 'ready',
574
938
  ...(!saved ? { notice: 'Mode changed for this session. Resume preference could not be saved.' } : {}),
575
939
  });
940
+ if (router.config.routingEngine === 'shadow') traceControl(router);
576
941
  }
577
942
 
578
943
  async function setPin($, router, tier) {
@@ -582,6 +947,7 @@ async function setPin($, router, tier) {
582
947
  if (mode === 'manual') return 'Routing is off. Turn routing on before pinning a turn.';
583
948
  router.pinPresses += 1;
584
949
  await updateView($, router, { pendingPin: tier });
950
+ if (router.config.routingEngine === 'shadow') traceControl(router);
585
951
  return `${tier} pinned for the next turn and its tool continuations.`;
586
952
  }
587
953
 
@@ -595,6 +961,7 @@ async function routerCommand($, router, args) {
595
961
  await changeMode($, router, action === 'auto' ? 'auto' : 'manual');
596
962
  return { text: action === 'auto' ? 'Routing on.' : 'Routing off: Claude’s model is kept.' };
597
963
  }
964
+ if (action === 'trace' && value === 'export') return { text: await exportTraces($, router) };
598
965
  if (action === 'decisions') return { text: await decisionsText($, router, value) };
599
966
  if (action === 'pin')
600
967
  return { text: TIERS.includes(value) ? await setPin($, router, value) : `Choose ${TIERS.join(', ')}.` };
@@ -775,11 +1142,15 @@ async function contextOf($, loop) {
775
1142
  }
776
1143
  }
777
1144
 
778
- async function* passMain($, e, next, loop, version, nativeModel, reason, router) {
1145
+ async function* passMain($, e, next, previous, version, nativeModel, reason, router) {
779
1146
  // A turn routing did not choose is a turn on another route: it ends the watch for escalations after a cheaper
780
1147
  // activity move, including one a turn started before routing was turned off mid-turn.
781
1148
  if (reason === 'manual') router.afterDown = null;
782
1149
  const ref = { ...LOOP, id: 'main' };
1150
+ const turn = router.turnConfigs.get(e.turnId) ?? { config: router.config, configured: router.config };
1151
+ const auto = turn.config.routingEngine === 'auto';
1152
+ const loop =
1153
+ reason === 'manual' && auto ? { ...previous, auto: null, route: null, decision: null, turnId: null } : previous;
783
1154
  const context = await contextOf($, loop);
784
1155
  await updateView($, router, {
785
1156
  nativeModel,
@@ -790,32 +1161,130 @@ async function* passMain($, e, next, loop, version, nativeModel, reason, router)
790
1161
  contextKnown: context.known,
791
1162
  });
792
1163
  const sessionId = await $.session.id();
1164
+ if (turn.config.routingEngine === 'shadow')
1165
+ traceRequest(router, e, turn, e, reason === 'manual' ? 'manual' : 'auto', loop);
793
1166
  const response = yield* next(e);
794
1167
  if (!next.signal.aborted && (await $.session.id()) === sessionId) {
795
- const observed = observeResponse(router.config, loop, {
1168
+ const at = Date.now();
1169
+ const cfg = auto ? turn.config : router.config;
1170
+ let observed = observeResponse(cfg, loop, {
796
1171
  usage: response.usage,
797
1172
  requestedModel: e.model,
798
1173
  effort: e.effort ?? null,
799
1174
  stopReason: response.stopReason,
800
- now: Date.now(),
1175
+ now: at,
801
1176
  });
1177
+ if (auto && ['no-route-native', 'native-fallback'].includes(reason))
1178
+ observed = {
1179
+ ...observeAutoFallback(cfg, observed, {
1180
+ requestedModel: e.model,
1181
+ effort: e.effort,
1182
+ usage: response.usage,
1183
+ }),
1184
+ suspended: true,
1185
+ };
1186
+ if (reason === 'no-route-native' && loop.auto?.savedPin) {
1187
+ observed.switchedAt = loop.auto.savedPin.switchedAt;
1188
+ observed.servedRoute = loop.auto.savedPin.servedRoute;
1189
+ }
802
1190
  // Before routing has chosen a route, the one in use is the model serving now: /model can change it with routing
803
1191
  // off. Once a decision exists, the last routed route is kept, as for every model.
804
- if (reason === 'manual' && !loop.decision) observed.route = ownRoute(router.config, e.model);
1192
+ if (reason === 'manual' && !loop.decision && !auto) observed.route = ownRoute(router.config, e.model);
805
1193
  // Routing chose nothing here, so the reply is not counted; your model's cache still follows it.
806
- const compared = await compareYours($, router, loop, response, e.effort ?? null, nativeModel);
1194
+ const compared = await compareYours($, router, loop, response, e.effort ?? null, nativeModel, cfg);
807
1195
  if (compared) observed.yoursBy = compared.states;
808
1196
  const written = await $.state.set(ref, observed, { ifVersion: version });
1197
+ if (turn.config.routingEngine === 'shadow') {
1198
+ if (written.isSet) recordTraceResponse(router, e, e, response, compared?.ttl, at);
1199
+ else router.trace?.reasons.add('gap');
1200
+ }
809
1201
  if (written.isSet)
810
1202
  await updateView($, router, {
811
1203
  ...responseMetrics(router.view, response, null, Date.now()),
812
1204
  delegatedModel: e.model,
813
1205
  delegatedEffort: e.effort ?? null,
814
1206
  });
815
- }
1207
+ } else if (turn.config.routingEngine === 'shadow') router.trace?.reasons.add('aborted');
816
1208
  return response;
817
1209
  }
818
1210
 
1211
+ // Shadow retains demand evidence only; target selection sees the actual incumbent and cache.
1212
+ function shadowProposal(
1213
+ config,
1214
+ loop,
1215
+ selected,
1216
+ { facts, advice, pin, nativeModel, contextKnown, availableModels, now, mode, offSwitches },
1217
+ ) {
1218
+ if (config.routingEngine !== 'shadow') {
1219
+ delete selected.shadow;
1220
+ return null;
1221
+ }
1222
+ try {
1223
+ const projected = economicConfig(config, loop);
1224
+ const beforePin = loop.decision?.pinned ? loop.route : null;
1225
+ const model = loop.decision?.pinned && !beforePin ? nativeModel : (loop.decision?.model ?? nativeModel);
1226
+ const alias = Object.keys(config.models).find(
1227
+ (key) => isSameModel(config.models[key].id, model) || isSameModel(projected.models[key].id, model),
1228
+ );
1229
+ const incumbent = beforePin ?? {
1230
+ model: alias ?? model,
1231
+ effort: loop.decision?.pinned ? (facts.effort ?? null) : (loop.decision?.effort ?? facts.effort ?? null),
1232
+ };
1233
+ const initial = TIERS.indexOf(config.baselineTier);
1234
+ const state =
1235
+ loop.shadow?.generation === loop.generation && loop.shadow.offSwitches === offSwitches
1236
+ ? loop.shadow.state
1237
+ : initialAutoState({ demand: initial });
1238
+ const demand = advanceDemand({
1239
+ config,
1240
+ state,
1241
+ advice,
1242
+ facts,
1243
+ pin,
1244
+ boundedExecute:
1245
+ config.activityRouting === 'on' &&
1246
+ acceptActivity(config, advice) !== null &&
1247
+ acceptPhase(config, advice) === 'execute',
1248
+ });
1249
+ const candidates = assessCandidates({
1250
+ config: projected,
1251
+ facts: { ...facts, ineligible: loop.ineligible.map((id) => loop.resolutions[id] ?? id) },
1252
+ now,
1253
+ incumbent,
1254
+ contextKnown,
1255
+ availableModels,
1256
+ nativeModel,
1257
+ });
1258
+ const target = selectTarget({
1259
+ candidates,
1260
+ demand: demand.level,
1261
+ mode: pin ? 'balanced' : mode,
1262
+ headroom: demand.headroom,
1263
+ escalation: demand.escalated,
1264
+ });
1265
+ if (demand.escalated || demand.headroom) demand.state = { ...demand.state, headroom: target.headroom };
1266
+ const { routedDemand: _routed, routeCause: _cause, ...demandState } = pin ? state : demand.state;
1267
+ selected.shadow = { generation: loop.generation, offSwitches, state: demandState };
1268
+ return {
1269
+ demand: demand.level,
1270
+ reason: demand.reason,
1271
+ headroom: target.headroom,
1272
+ targetReason: target.reason,
1273
+ requirement: target.requirement,
1274
+ outcome: target.outcome,
1275
+ route: target.route
1276
+ ? `${target.route.model}@${typeof target.route.effort === 'string' ? target.route.effort : 'session'}`
1277
+ : null,
1278
+ capability: target.capability,
1279
+ minUsd: target.estimate?.minUsd,
1280
+ maxUsd: target.estimate?.maxUsd,
1281
+ };
1282
+ } catch {
1283
+ delete selected.shadow;
1284
+ return { reason: 'error' };
1285
+ }
1286
+ }
1287
+
819
1288
  // One turn's classification and route, written to the loop at `loopVersion`: the loop and its new version, or null
820
1289
  // when the turn was aborted, left the session or Auto, or lost the write. `signal` is the step's: its abort cancels
821
1290
  // the classifier call. The pin is the one in `view`, the view as the step read it; it is used up only once the route
@@ -823,7 +1292,7 @@ async function* passMain($, e, next, loop, version, nativeModel, reason, router)
823
1292
  async function decideTurn($, router, e, signal, step) {
824
1293
  const { sessionId, view, loop, loopVersion, context, nativeModel, availableModels } = step;
825
1294
  // A pin runs its tier's configured route: the routing mode moves only routes the router chooses.
826
- const cfg = view.pendingPin ? step.configured : step.cfg;
1295
+ const cfg = view.pendingPin && step.cfg.routingEngine !== 'auto' ? step.configured : step.cfg;
827
1296
  const ref = { ...LOOP, id: 'main' };
828
1297
  const controller = new AbortController();
829
1298
  const cancel = () => controller.abort();
@@ -886,7 +1355,7 @@ async function decideTurn($, router, e, signal, step) {
886
1355
  const previous = loop.decision;
887
1356
  if (pin)
888
1357
  router.turnConfigs.set(e.turnId, { config: { ...cfg, routingMode: step.cfg.routingMode }, configured: cfg });
889
- const selected = chooseRoute(cfg, loop, {
1358
+ const traceInput = {
890
1359
  facts,
891
1360
  advice: result.advice,
892
1361
  pin,
@@ -894,6 +1363,21 @@ async function decideTurn($, router, e, signal, step) {
894
1363
  contextKnown: context.known,
895
1364
  availableModels,
896
1365
  now: Date.now(),
1366
+ };
1367
+ const selected =
1368
+ cfg.routingEngine === 'auto'
1369
+ ? autoRoute(cfg, loop, { ...traceInput, engineModel: e.model })
1370
+ : chooseRoute(cfg, loop, traceInput);
1371
+ const alt = shadowProposal(step.configured, loop, selected, {
1372
+ facts,
1373
+ advice: result.advice,
1374
+ pin,
1375
+ nativeModel,
1376
+ contextKnown: context.known,
1377
+ availableModels,
1378
+ now: Date.now(),
1379
+ mode: step.cfg.routingMode.mode,
1380
+ offSwitches: router.offSwitches,
897
1381
  });
898
1382
  selected.engineModel = e.model;
899
1383
  const written = await $.state.set(ref, selected, { ifVersion: loopVersion });
@@ -901,6 +1385,7 @@ async function decideTurn($, router, e, signal, step) {
901
1385
  if (written.isSet && pin) router.turnPins.set(e.turnId, pinPresses);
902
1386
  // Manual, /clear and turn completion abort the controller; one may land during the write.
903
1387
  if (!written.isSet || controller.signal.aborted) return null;
1388
+ if (cfg.routingEngine === 'shadow') traceOp(router, e, cfg, 'choose', traceInput, selected, messages);
904
1389
  rememberGoal(router, e.turnId, result.advice, cfg.policy.continuationMass, messages);
905
1390
  if (previous?.model && previous.model !== selected.decision.model && !selected.decision.pinned)
906
1391
  $.ui.toast(switchToast(cfg, previous, selected.decision, selected.decision.estimate));
@@ -919,6 +1404,8 @@ async function decideTurn($, router, e, signal, step) {
919
1404
  decision: selected.decision,
920
1405
  facts,
921
1406
  sameTask: sameTaskOf(cfg, result.advice, facts),
1407
+ engine: cfg.routingEngine,
1408
+ alt,
922
1409
  }),
923
1410
  );
924
1411
  // One line per decision in Claude Code's debug log, so a later replay can compare modes. No prompt text.
@@ -1025,14 +1512,16 @@ const activityLabel = (cfg, decision) => (cfg.activityRouting === 'on' ? (decisi
1025
1512
  // tool calls after the last applied review count (`loop.observedFrom`): the review judged the ones before. The
1026
1513
  // transcript is read only when some activity's route at this tier is stronger than the running one.
1027
1514
  async function moveOnObserved($, router, cfg, loop, e, context) {
1028
- if (!canMoveUp(cfg, loop.decision, e.effort)) return loop;
1515
+ if (cfg.routingEngine === 'auto' || !canMoveUp(cfg, loop.decision, e.effort)) return loop;
1029
1516
  const messages = await transcript($);
1030
1517
  if (!messages) return loop;
1031
1518
  const facts = stepFacts(cfg, router, loop, e, messages, context);
1032
1519
  const observed = routingBucket(
1033
1520
  observedActivity(messages, Math.max(promptIndex(messages), (loop.observedFrom ?? 0) - 1)),
1034
1521
  );
1035
- const moved = observedMove(cfg, loop, { observed, facts, contextKnown: context.known, now: Date.now() });
1522
+ const traceInput = { observed, facts, contextKnown: context.known, now: Date.now() };
1523
+ const moved = observedMove(cfg, loop, traceInput);
1524
+ if (cfg.routingEngine === 'shadow') traceOp(router, e, cfg, 'observed', traceInput, moved, messages);
1036
1525
  if (moved === loop) return loop;
1037
1526
  addDecision(
1038
1527
  router,
@@ -1040,6 +1529,7 @@ async function moveOnObserved($, router, cfg, loop, e, context) {
1040
1529
  decisionRow({
1041
1530
  at: Date.now(),
1042
1531
  kind: 'observed',
1532
+ engine: cfg.routingEngine,
1043
1533
  origin: router.turnOrigins.get(e.turnId) ?? 'unknown',
1044
1534
  mode: cfg.routingMode?.mode ?? null,
1045
1535
  decision: moved.decision,
@@ -1075,7 +1565,7 @@ async function reviewMidTurn($, router, cfg, loop, e, { context, nativeModel, av
1075
1565
  const advice =
1076
1566
  messages.length === review.observedUpTo ? review.answer.advice : { ...review.answer.advice, phase: null };
1077
1567
  const facts = { ...stepFacts(cfg, router, loop, e, messages, context), midTurn: true };
1078
- const selected = chooseRoute(cfg, loop, {
1568
+ const traceInput = {
1079
1569
  facts,
1080
1570
  advice,
1081
1571
  pin: null,
@@ -1083,8 +1573,23 @@ async function reviewMidTurn($, router, cfg, loop, e, { context, nativeModel, av
1083
1573
  contextKnown: context.known,
1084
1574
  availableModels,
1085
1575
  now: Date.now(),
1086
- });
1576
+ };
1577
+ const selected =
1578
+ cfg.routingEngine === 'auto' ? autoRoute(cfg, loop, traceInput) : chooseRoute(cfg, loop, traceInput);
1579
+ if (cfg.routingEngine === 'shadow') traceOp(router, e, cfg, 'choose', traceInput, selected, messages);
1087
1580
  const previous = loop.decision;
1581
+ const configured = router.turnConfigs.get(e.turnId)?.configured ?? router.config;
1582
+ const alt = shadowProposal(configured, loop, selected, {
1583
+ facts,
1584
+ advice,
1585
+ pin: null,
1586
+ nativeModel,
1587
+ contextKnown: context.known,
1588
+ availableModels,
1589
+ now: Date.now(),
1590
+ mode: cfg.routingMode?.mode ?? DEFAULTS.mode,
1591
+ offSwitches: router.offSwitches,
1592
+ });
1088
1593
  addDecision(
1089
1594
  router,
1090
1595
  e.turnId,
@@ -1097,6 +1602,8 @@ async function reviewMidTurn($, router, cfg, loop, e, { context, nativeModel, av
1097
1602
  decision: selected.decision,
1098
1603
  facts,
1099
1604
  sameTask: sameTaskOf(cfg, advice, facts),
1605
+ engine: configured.routingEngine,
1606
+ alt,
1100
1607
  }),
1101
1608
  );
1102
1609
  if (previous && (previous.model !== selected.decision.model || previous.effort !== selected.decision.effort)) {
@@ -1198,7 +1705,7 @@ async function publishReply($, router, turnId, request, response, tier, route, r
1198
1705
  async function observeRouted($, router, { turnId, cfg, loop, loopVersion, request, response, nativeModel }) {
1199
1706
  // When the reply arrived: the awaits below can cross midnight or the hour it is kept under.
1200
1707
  const at = Date.now();
1201
- const observed = observeResponse(cfg, loop, {
1708
+ let observed = observeResponse(cfg, loop, {
1202
1709
  usage: response.usage,
1203
1710
  requestedModel: request.model,
1204
1711
  effort: request.effort ?? null,
@@ -1206,10 +1713,24 @@ async function observeRouted($, router, { turnId, cfg, loop, loopVersion, reques
1206
1713
  now: at,
1207
1714
  });
1208
1715
  if (response.stopReason === null) observed.suspended = true;
1716
+ if (cfg.routingEngine === 'auto' && response.usage?.model && !isSameModel(request.model, response.usage.model))
1717
+ observed = observeAutoFallback(cfg, observed, {
1718
+ requestedModel: request.model,
1719
+ effort: request.effort,
1720
+ usage: response.usage,
1721
+ });
1722
+ if (cfg.routingEngine === 'auto' && loop.auto?.savedPin) {
1723
+ observed.switchedAt = loop.auto.savedPin.switchedAt;
1724
+ observed.servedRoute = loop.auto.savedPin.servedRoute;
1725
+ }
1209
1726
  const compared = await compareYours($, router, loop, response, request.effort ?? null, nativeModel, cfg);
1210
1727
  if (compared) observed.yoursBy = compared.states;
1211
1728
  const written = await $.state.set({ ...LOOP, id: 'main' }, observed, { ifVersion: loopVersion });
1212
- if (!written.isSet) return;
1729
+ if (!written.isSet) {
1730
+ if (cfg.routingEngine === 'shadow') router.trace?.reasons.add('gap');
1731
+ return;
1732
+ }
1733
+ if (cfg.routingEngine === 'shadow') recordTraceResponse(router, request, request, response, compared?.ttl, at);
1213
1734
  // A substituted reply is not the tier's: the strip and trend must not count it as one.
1214
1735
  const tier = isSameModel(request.model, response.usage?.model) ? loop.decision.tier : null;
1215
1736
  const route = `${request.model}@${request.effort ?? 'session'}`;
@@ -1338,6 +1859,7 @@ async function flushUsage($, router, turnId, switched) {
1338
1859
  // its report as dialogue (progressInput); without a goal from this session it reads as before. A goal origin's prompt
1339
1860
  // becomes the goal.
1340
1861
  async function startTurn($, router, e) {
1862
+ if (!(await ensureInitialized($, router))) return;
1341
1863
  const epoch = ++router.goalEpoch;
1342
1864
  router.goalTurnId = e.turnId;
1343
1865
  await fixTurnConfig($, router, e.turnId);
@@ -1506,6 +2028,17 @@ async function pruneDecisionRecords($) {
1506
2028
  }
1507
2029
 
1508
2030
  // `/router decisions [n]`: this session's newest routing decisions, the running turn's included.
2031
+ async function paneDecisionRows($, router) {
2032
+ if (!['shadow', 'auto'].includes(router.config.routingEngine)) return [];
2033
+ const sessionId = await $.session.id();
2034
+ const record =
2035
+ router.decisionRecord?.sessionId === sessionId
2036
+ ? router.decisionRecord.record
2037
+ : readDecisions(await $.store.get(`${DECISIONS_PREFIX}${sessionId}`).catch(() => null));
2038
+ const resetAt = await $.store.get(SAVINGS_RESET_KEY).catch(() => null);
2039
+ return [...decisionsAfterReset(record, resetAt).rows, ...[...router.turnDecisions.values()].flat()];
2040
+ }
2041
+
1509
2042
  async function decisionsText($, router, value) {
1510
2043
  const n = Math.min(MAX_ROWS, Math.max(1, Number.parseInt(value, 10) || 20));
1511
2044
  try {
@@ -1679,6 +2212,7 @@ async function decideSpawn($, router, cfg, e, definition, signal) {
1679
2212
  // Claude Code uses in place of the Agent call's `model` and the agent's frontmatter. Routing off or unavailable keeps
1680
2213
  // every model Claude Code chooses, and records nothing.
1681
2214
  async function spawnAgent($, router, e, next) {
2215
+ if (!(await ensureInitialized($, router))) return next(e);
1682
2216
  const cfg = router.config;
1683
2217
  if (cfg.subagentRouting === 'off') return next(e);
1684
2218
  const view = router.view ?? (await readView($, router));
@@ -1780,6 +2314,18 @@ async function flushSubagents($, router, agents) {
1780
2314
  } catch {}
1781
2315
  }
1782
2316
 
2317
+ function traceConfigAdopted(router, loaded) {
2318
+ try {
2319
+ if (router.config.routingEngine !== 'shadow' || loaded.routingEngine === 'shadow' || !router.trace) return;
2320
+ router.trace.reasons.add('mode-gap');
2321
+ router.trace.turns.clear();
2322
+ router.traceOperations.clear();
2323
+ router.trace.controls = null;
2324
+ } catch {
2325
+ traceFailed(router);
2326
+ }
2327
+ }
2328
+
1783
2329
  // The pane's handlers. `view` is the view the pane was drawn from; a handler reads `router.view` first, which holds
1784
2330
  // any press since.
1785
2331
  function paneActions($, router, view) {
@@ -1808,7 +2354,9 @@ function paneActions($, router, view) {
1808
2354
  // an unavailable reason stays.
1809
2355
  const adopt = async (loaded) => {
1810
2356
  const switched = loaded.classifier !== router.config.classifier;
2357
+ traceConfigAdopted(router, loaded);
1811
2358
  router.config = loaded;
2359
+
1812
2360
  if (!switched) return {};
1813
2361
  clientOf(router, router.config.classifier).restore(null);
1814
2362
  const current = router.view ?? view;
@@ -1974,6 +2522,7 @@ function paneActions($, router, view) {
1974
2522
  const keys = (await $.store.keys()).filter(
1975
2523
  (key) =>
1976
2524
  key.startsWith(DECISIONS_PREFIX) ||
2525
+ key.startsWith(TRACE_PREFIX) ||
1977
2526
  key === LEGACY_STORE_PREFIX ||
1978
2527
  key.startsWith(`${LEGACY_STORE_PREFIX}:`) ||
1979
2528
  Object.values(LEDGERS).some(({ prefix, legacy }) => key.startsWith(prefix) || key === legacy),
@@ -1984,6 +2533,10 @@ function paneActions($, router, view) {
1984
2533
  return true;
1985
2534
  };
1986
2535
  const cleared = await clearRecords().catch(() => false);
2536
+ router.trace = null;
2537
+ router.traceFreshSession = null;
2538
+ router.traceClearSession = null;
2539
+ router.traceOperations.clear();
1987
2540
  // The store kept the history: this session's records start over, and its next write replaces the stored one.
1988
2541
  if (!cleared)
1989
2542
  for (const kind of LEDGER_KINDS) {
@@ -2111,68 +2664,290 @@ async function imagesOf($, config, decision) {
2111
2664
  return messages === null || hasImages(messages);
2112
2665
  }
2113
2666
 
2667
+ function startError(supported, gateway) {
2668
+ if (!supported) return 'requires Claude Code 2.1.289 or newer';
2669
+ if (gateway) return GATEWAY_SETTINGS;
2670
+ return null;
2671
+ }
2672
+
2114
2673
  function configurationError(error) {
2115
2674
  if (error.message?.endsWith(MIGRATION_HINT))
2116
2675
  return 'router.json needs migration; run the plugin scripts/migrate-config.mjs with your router.json path';
2117
2676
  return error.message === 'selected provider router file is missing' ? error.message : 'invalid router configuration';
2118
2677
  }
2119
2678
 
2120
- export function register(on, options) {
2121
- const router = createRouter(options);
2679
+ async function* sendRouted($, router, e, next, { cfg, loop, loopVersion, sessionId, nativeModel, turn }) {
2680
+ const pinPresses = router.turnPins.get(e.turnId);
2681
+ if (pinPresses !== undefined) {
2682
+ router.turnPins.delete(e.turnId);
2683
+ if (pinPresses === router.pinPresses) await updateView($, router, { pendingPin: null });
2684
+ }
2685
+ if (cfg.routingEngine === 'auto' && !loop.decision.route)
2686
+ return yield* passMain($, e, next, loop, loopVersion, nativeModel, 'no-route-native', router);
2687
+ const request = { ...e, model: loop.decision.model };
2688
+ if (loop.decision.effort === null) delete request.effort;
2689
+ else request.effort = loop.decision.effort;
2690
+ if (cfg.routingEngine === 'shadow' && !next.signal.aborted && (await $.session.id()) === sessionId)
2691
+ traceRequest(router, e, router.turnConfigs.get(e.turnId) ?? turn, request, 'auto', loop);
2692
+ const response = yield* next(request);
2693
+ if (!next.signal.aborted && (await $.session.id()) === sessionId)
2694
+ await observeRouted($, router, { turnId: e.turnId, cfg, loop, loopVersion, request, response, nativeModel });
2695
+ else if (cfg.routingEngine === 'shadow') router.trace?.reasons.add('aborted');
2696
+ return response;
2697
+ }
2122
2698
 
2123
- on('session.start', async ($, e, next) => {
2124
- router.definitions.clear();
2125
- await $.command.register({
2126
- name: 'router',
2127
- description:
2128
- 'Open the Router pane, or switch routing: auto, off, pin <tier>, activities <mode>, mode <mode>; decisions [n] lists the last routing decisions.',
2129
- argumentHint: '[auto|off|pin <tier>|activities off|on|mode cost|balanced|quality|default|decisions [n]]',
2130
- immediate: true,
2131
- });
2132
- const model = await $.session.model();
2699
+ function resetEngine(router, cfg, configured, model, messageCount, previous) {
2700
+ let loop = previous;
2701
+ // Engine state is incompatible, but physical cache/usage observations remain valid across engine changes.
2702
+ if ((cfg.routingEngine === 'auto' || loop.activeEngine === 'auto') && loop.activeEngine !== cfg.routingEngine) {
2703
+ const fresh = emptyLoop(configured, model);
2704
+ loop = {
2705
+ ...loop,
2706
+ lastRoute: fresh.lastRoute,
2707
+ lastActivity: fresh.lastActivity,
2708
+ route: fresh.route,
2709
+ state: fresh.state,
2710
+ turnId: null,
2711
+ decision: null,
2712
+ suspended: false,
2713
+ reviewedAt: loop.requests,
2714
+ observedFrom: messageCount,
2715
+ auto: null,
2716
+ shadow: undefined,
2717
+ generation: loop.generation + 1,
2718
+ activeEngine: cfg.routingEngine,
2719
+ };
2720
+ for (const review of router.reviews.values()) review.controller.abort();
2721
+ router.reviews.clear();
2722
+ router.decisions.clear();
2723
+ }
2724
+ return loop;
2725
+ }
2726
+
2727
+ async function continueAuto($, router, cfg, prior, e, context, traceInput) {
2728
+ let loop = prior;
2729
+ const messages = await transcript($);
2730
+ const facts = { ...stepFacts(cfg, router, loop, e, messages ?? [], context), midTurn: true };
2731
+ // An unreadable transcript cannot establish that an image-ineligible request is safe.
2732
+ facts.hasImages = messages ? hasImages(messages) : true;
2733
+ const observed = messages
2734
+ ? routingBucket(observedActivity(messages, Math.max(promptIndex(messages), (loop.observedFrom ?? 0) - 1)))
2735
+ : null;
2736
+ const previous = loop.decision;
2737
+ loop = autoRoute(cfg, loop, { ...traceInput, facts, now: Date.now() }, { continuation: true, observed });
2738
+ if (JSON.stringify(previous.auto) !== JSON.stringify(loop.decision.auto))
2739
+ addDecision(
2740
+ router,
2741
+ e.turnId,
2742
+ decisionRow({
2743
+ at: Date.now(),
2744
+ kind: 'observed',
2745
+ engine: 'auto',
2746
+ mode: cfg.routingMode.mode,
2747
+ decision: loop.decision,
2748
+ facts,
2749
+ }),
2750
+ );
2751
+
2752
+ return loop;
2753
+ }
2754
+
2755
+ async function traceContinuation($, router, cfg, loop, e, traceInput) {
2756
+ if (cfg.routingEngine === 'shadow') {
2757
+ // Replay's incumbent may differ from the table's: retain unconditional modality and checkpoint evidence.
2758
+ // Failure stays unknown, never a false assertion that the hypothetical route can accept this history.
2759
+ let replayMessages = null;
2760
+ let actualHasImages = null;
2133
2761
  try {
2134
- router.config = await loadNativeConfig($);
2135
- router.project = await readProject($, router.config.nativePath);
2136
- const existing = await readView($, router);
2137
- router.view = existing;
2138
- const sameClassifier = existing.health?.classifier === router.config.classifier;
2139
- clientOf(router, router.config.classifier).restore(sameClassifier ? existing.health : null);
2140
- const base = await $.env.get('ANTHROPIC_BASE_URL');
2141
- const version = await $.session.version().catch(() => null);
2142
- const supported = supportedVersion(version?.version);
2143
- const gateway =
2144
- ['jev-router', 'jev-router[1m]'].includes(model) ||
2145
- model === 'router' ||
2146
- Boolean(base?.includes('127.0.0.1:43170') || base?.includes('localhost:43170'));
2147
- await updateView($, router, {
2148
- nativeModel: model,
2149
- ...(existing.activityContract !== ACTIVITY_CONTRACT
2150
- ? { activityContract: ACTIVITY_CONTRACT, activityStats: null }
2151
- : {}),
2152
- ...(await startView($, router, model)),
2153
- phase: gateway || !supported ? 'unavailable' : 'ready',
2154
- error: !supported ? 'requires Claude Code 2.1.289 or newer' : gateway ? GATEWAY_SETTINGS : null,
2155
- ...(sameClassifier ? {} : CLEARED_READINGS),
2156
- credentials: await credentialsOf($, options, router.config),
2157
- health: healthOf(clientOf(router, router.config.classifier), router.config.classifier),
2158
- configPath: router.config.nativePath,
2159
- routingMode: await routingModeOf($, router),
2160
- projectError: router.project.error,
2161
- tuning: null,
2162
- tuningBase: null,
2163
- routeDraft: null,
2164
- lastWrite: null,
2165
- bandDetail: (await $.store.get(BAND_DETAIL).catch(() => false)) === true,
2166
- usagePeriod: await periodOf($),
2167
- ...(await storeView($, router)),
2168
- });
2169
- await pruneDecisionRecords($);
2170
- } catch (error) {
2171
- await updateView($, router, {
2172
- phase: 'unavailable',
2173
- error: configurationError(error),
2762
+ replayMessages = await transcript($);
2763
+ if (replayMessages) actualHasImages = hasImages(replayMessages);
2764
+ } catch {
2765
+ replayMessages = null;
2766
+ }
2767
+ traceOp(router, e, cfg, 'continue', { ...traceInput, actualHasImages }, loop, replayMessages);
2768
+ }
2769
+ }
2770
+
2771
+ async function* stepMain($, router, e, next) {
2772
+ if (!(await ensureInitialized($, router))) return yield* next(e);
2773
+ if (e.agentId) return yield* stepAgent($, router, e, next);
2774
+ const turn = router.turnConfigs.get(e.turnId) ?? (await turnConfigOf($, router));
2775
+ const cfg = turn.config;
2776
+ const [sessionId, nativeModel, view] = await Promise.all([$.session.id(), $.session.model(), readView($, router)]);
2777
+ const mode = await modeOf($, router, view.mode);
2778
+ const freshTrace =
2779
+ router.traceFreshSession === sessionId ||
2780
+ (router.traceClearSession !== null && router.traceClearSession !== sessionId);
2781
+ router.traceFreshSession = null;
2782
+ router.traceClearSession = null;
2783
+ if (e.index === 0) {
2784
+ const saved = await rememberMode($, mode);
2785
+ await updateView($, router, {
2786
+ mode,
2787
+ nativeEffort: e.effort ?? null,
2788
+ ...(!saved ? { notice: 'Resume preference could not be saved. Current mode remains active.' } : {}),
2789
+ });
2790
+ }
2791
+ const ref = { ...LOOP, id: 'main' };
2792
+ const loaded = await $.state.get(ref);
2793
+ let loopVersion = loaded.version;
2794
+ // The session's model names its tier in the configured routes: a mode's table can run it at another tier.
2795
+ let loop = prepareLoop(loaded.value ?? emptyLoop(turn.configured, e.model), e.messageCount);
2796
+ loop = resetEngine(router, cfg, turn.configured, e.model, e.messageCount, loop);
2797
+ if (loaded.value && loop.generation !== loaded.value.generation) clearGoal(router);
2798
+ if (cfg.routingEngine === 'shadow' && router.config.routingEngine === 'shadow') {
2799
+ await ensureTrace($, router, e, turn, loop, Boolean(loaded.value), freshTrace);
2800
+ router.traceOperations.delete(e.turnId);
2801
+ if (loaded.value && loop.generation !== loaded.value.generation)
2802
+ addTrace(router, e, { type: 'reset', at: Date.now(), cause: 'history', loop, generation: loop.generation });
2803
+ } else if (router.trace) router.trace.reasons.add('mode-gap');
2804
+ if (view.phase === 'unavailable' || mode === 'manual') {
2805
+ return yield* passMain($, e, next, loop, loopVersion, nativeModel, 'manual', router);
2806
+ }
2807
+ if (loop.turnId === e.turnId && isNativeFallback(loop, e.model)) {
2808
+ return yield* passMain($, e, next, loop, loopVersion, nativeModel, 'native-fallback', router);
2809
+ }
2810
+ const [context, settings] = await Promise.all([contextOf($, loop), $.settings.read()]);
2811
+ const availableModels = settings.availableModels;
2812
+ const key = `${sessionId}:${e.turnId}:${loop.generation}`;
2813
+ if (loop.turnId !== e.turnId) {
2814
+ let job = router.decisions.get(key);
2815
+ if (!job) {
2816
+ job = decideTurn($, router, e, next.signal, {
2817
+ sessionId,
2818
+ view,
2819
+ cfg,
2820
+ configured: turn.configured,
2821
+ loop,
2822
+ loopVersion,
2823
+ context,
2824
+ nativeModel,
2825
+ availableModels,
2174
2826
  });
2827
+ router.decisions.set(key, job);
2828
+ }
2829
+ const selected = await job;
2830
+ if (!selected) {
2831
+ if (!next.signal.aborted && (await $.session.id()) === sessionId && router.view?.activeTurnId === e.turnId) {
2832
+ const reserved = await $.state.set(ref, loop, { ifVersion: loopVersion });
2833
+ if (reserved.isSet) return yield* passMain($, e, next, loop, reserved.version, nativeModel, 'manual', router);
2834
+ }
2835
+ return yield* next(e);
2175
2836
  }
2837
+ loop = selected.loop;
2838
+ loopVersion = selected.version;
2839
+ } else {
2840
+ // A review answer applies first, so tool calls made after its snapshot can still move the route up.
2841
+ loop = await reviewMidTurn($, router, cfg, loop, e, { context, nativeModel, availableModels });
2842
+ loop = await moveOnObserved($, router, cfg, loop, e, context);
2843
+ const traceInput = {
2844
+ hasImages: cfg.routingEngine === 'auto' ? false : await imagesOf($, cfg, loop.decision),
2845
+ nativeModel,
2846
+ contextTokens: context.tokens,
2847
+ contextKnown: context.known,
2848
+ availableModels,
2849
+ effort: e.effort,
2850
+ };
2851
+ loop =
2852
+ cfg.routingEngine === 'auto'
2853
+ ? await continueAuto($, router, cfg, loop, e, context, traceInput)
2854
+ : continueRoute(cfg, loop, traceInput);
2855
+ await traceContinuation($, router, cfg, loop, e, traceInput);
2856
+ await updateView($, router, continuationView(cfg, loop.decision, context));
2857
+ }
2858
+ if (
2859
+ cfg.routingEngine === 'auto' &&
2860
+ (next.signal.aborted || (await $.session.id()) !== sessionId || (await modeOf($, router)) !== 'auto')
2861
+ )
2862
+ return yield* next(e);
2863
+ return yield* sendRouted($, router, e, next, { cfg, loop, loopVersion, sessionId, nativeModel, turn });
2864
+ }
2865
+
2866
+ async function initializeSession($, router) {
2867
+ router.definitions.clear();
2868
+ await $.command.register({
2869
+ name: 'router',
2870
+ description:
2871
+ 'Open the Router pane, or switch routing: auto, off, pin <tier>, activities <mode>, mode <mode>; decisions [n] lists the last routing decisions.',
2872
+ argumentHint:
2873
+ '[auto|off|pin <tier>|activities off|on|mode cost|balanced|quality|default|decisions [n]|trace export]',
2874
+ immediate: true,
2875
+ });
2876
+ const model = await $.session.model();
2877
+ try {
2878
+ router.config = await loadNativeConfig($);
2879
+ // A successful reload adopts this config even for the current turn; stale jobs must not route with the old engine.
2880
+ for (const controller of router.controllers) controller.abort();
2881
+ router.decisions.clear();
2882
+ router.turnConfigs.clear();
2883
+ for (const review of router.reviews.values()) review.controller.abort();
2884
+ router.reviews.clear();
2885
+ router.project = await readProject($, router.config.nativePath);
2886
+ const existing = await readView($, router);
2887
+ router.view = existing;
2888
+ const sameClassifier = existing.health?.classifier === router.config.classifier;
2889
+ clientOf(router, router.config.classifier).restore(sameClassifier ? existing.health : null);
2890
+ const base = await $.env.get('ANTHROPIC_BASE_URL');
2891
+ const version = await $.session.version().catch(() => null);
2892
+ const supported = supportedVersion(version?.version);
2893
+ const gateway =
2894
+ ['jev-router', 'jev-router[1m]'].includes(model) ||
2895
+ model === 'router' ||
2896
+ Boolean(base?.includes('127.0.0.1:43170') || base?.includes('localhost:43170'));
2897
+ await updateView($, router, {
2898
+ nativeModel: model,
2899
+ ...(existing.activityContract !== ACTIVITY_CONTRACT
2900
+ ? { activityContract: ACTIVITY_CONTRACT, activityStats: null }
2901
+ : {}),
2902
+ ...(await startView($, router, model)),
2903
+ phase: gateway || !supported ? 'unavailable' : 'ready',
2904
+ error: startError(supported, gateway),
2905
+ ...(sameClassifier ? {} : CLEARED_READINGS),
2906
+ credentials: await credentialsOf($, router.options, router.config),
2907
+ health: healthOf(clientOf(router, router.config.classifier), router.config.classifier),
2908
+ configPath: router.config.nativePath,
2909
+ routingMode: await routingModeOf($, router),
2910
+ projectError: router.project.error,
2911
+ tuning: null,
2912
+ tuningBase: null,
2913
+ routeDraft: null,
2914
+ lastWrite: null,
2915
+ bandDetail: (await $.store.get(BAND_DETAIL).catch(() => false)) === true,
2916
+ usagePeriod: await periodOf($),
2917
+ ...(await storeView($, router)),
2918
+ });
2919
+ await pruneDecisionRecords($);
2920
+ router.initialized = true;
2921
+ return true;
2922
+ } catch (error) {
2923
+ await updateView($, router, {
2924
+ phase: 'unavailable',
2925
+ error: configurationError(error),
2926
+ });
2927
+ return false;
2928
+ }
2929
+ }
2930
+
2931
+ async function ensureInitialized($, router) {
2932
+ if (router.initialized) return true;
2933
+ router.initializing ??= initializeSession($, router).finally(() => {
2934
+ router.initializing = null;
2935
+ });
2936
+ return router.initializing;
2937
+ }
2938
+
2939
+ export function register(on, options) {
2940
+ const router = createRouter(options);
2941
+
2942
+ on('session.start', async ($, e, next) => {
2943
+ const sessionId = await $.session.id();
2944
+ // Lazy profile loading is not a lifecycle signal; only a real Mod start can establish freshness.
2945
+ router.traceFreshSession = router.traceStartedSession !== sessionId ? sessionId : null;
2946
+ router.traceStartedSession = sessionId;
2947
+ router.trace = null;
2948
+ router.traceOperations.clear();
2949
+ router.initialized = false;
2950
+ await ensureInitialized($, router);
2176
2951
  return next(e);
2177
2952
  });
2178
2953
 
@@ -2210,86 +2985,7 @@ export function register(on, options) {
2210
2985
  } catch {}
2211
2986
 
2212
2987
  on('turn.step', async function* ($, e, next) {
2213
- if (e.agentId) return yield* stepAgent($, router, e, next);
2214
- const turn = router.turnConfigs.get(e.turnId) ?? (await turnConfigOf($, router));
2215
- const cfg = turn.config;
2216
- const [sessionId, nativeModel, view] = await Promise.all([$.session.id(), $.session.model(), readView($, router)]);
2217
- const mode = await modeOf($, router, view.mode);
2218
- if (e.index === 0) {
2219
- const saved = await rememberMode($, mode);
2220
- await updateView($, router, {
2221
- mode,
2222
- nativeEffort: e.effort ?? null,
2223
- ...(!saved ? { notice: 'Resume preference could not be saved. Current mode remains active.' } : {}),
2224
- });
2225
- }
2226
- const ref = { ...LOOP, id: 'main' };
2227
- const loaded = await $.state.get(ref);
2228
- let loopVersion = loaded.version;
2229
- // The session's model names its tier in the configured routes: a mode's table can run it at another tier.
2230
- let loop = prepareLoop(loaded.value ?? emptyLoop(turn.configured, e.model), e.messageCount);
2231
- if (loaded.value && loop.generation !== loaded.value.generation) clearGoal(router);
2232
- if (view.phase === 'unavailable' || mode === 'manual') {
2233
- return yield* passMain($, e, next, loop, loopVersion, nativeModel, 'manual', router);
2234
- }
2235
- if (loop.turnId === e.turnId && isNativeFallback(loop, e.model)) {
2236
- return yield* passMain($, e, next, loop, loopVersion, nativeModel, 'native-fallback', router);
2237
- }
2238
- const [context, settings] = await Promise.all([contextOf($, loop), $.settings.read()]);
2239
- const availableModels = settings.availableModels;
2240
- const key = `${sessionId}:${e.turnId}:${loop.generation}`;
2241
- if (loop.turnId !== e.turnId) {
2242
- let job = router.decisions.get(key);
2243
- if (!job) {
2244
- job = decideTurn($, router, e, next.signal, {
2245
- sessionId,
2246
- view,
2247
- cfg,
2248
- configured: turn.configured,
2249
- loop,
2250
- loopVersion,
2251
- context,
2252
- nativeModel,
2253
- availableModels,
2254
- });
2255
- router.decisions.set(key, job);
2256
- }
2257
- const selected = await job;
2258
- if (!selected) {
2259
- if (!next.signal.aborted && (await $.session.id()) === sessionId && router.view?.activeTurnId === e.turnId) {
2260
- const reserved = await $.state.set(ref, loop, { ifVersion: loopVersion });
2261
- if (reserved.isSet) return yield* passMain($, e, next, loop, reserved.version, nativeModel, 'manual', router);
2262
- }
2263
- return yield* next(e);
2264
- }
2265
- loop = selected.loop;
2266
- loopVersion = selected.version;
2267
- } else {
2268
- // A review answer applies first, so tool calls made after its snapshot can still move the route up.
2269
- loop = await reviewMidTurn($, router, cfg, loop, e, { context, nativeModel, availableModels });
2270
- loop = await moveOnObserved($, router, cfg, loop, e, context);
2271
- loop = continueRoute(cfg, loop, {
2272
- hasImages: await imagesOf($, cfg, loop.decision),
2273
- nativeModel,
2274
- contextTokens: context.tokens,
2275
- contextKnown: context.known,
2276
- availableModels,
2277
- effort: e.effort,
2278
- });
2279
- await updateView($, router, continuationView(cfg, loop.decision, context));
2280
- }
2281
- const pinPresses = router.turnPins.get(e.turnId);
2282
- if (pinPresses !== undefined) {
2283
- router.turnPins.delete(e.turnId);
2284
- if (pinPresses === router.pinPresses) await updateView($, router, { pendingPin: null });
2285
- }
2286
- const request = { ...e, model: loop.decision.model };
2287
- if (loop.decision.effort === null) delete request.effort;
2288
- else request.effort = loop.decision.effort;
2289
- const response = yield* next(request);
2290
- if (!next.signal.aborted && (await $.session.id()) === sessionId)
2291
- await observeRouted($, router, { turnId: e.turnId, cfg, loop, loopVersion, request, response, nativeModel });
2292
- return response;
2988
+ return yield* stepMain($, router, e, next);
2293
2989
  });
2294
2990
 
2295
2991
  on('turn.complete', async ($, e, next) => {
@@ -2318,6 +3014,11 @@ export function register(on, options) {
2318
3014
  } else if (turn) await recordActivity($, router, turn);
2319
3015
  if (router.turnUsage.has(e.turnId)) await flushUsage($, router, e.turnId, turn?.switched ?? null);
2320
3016
  await flushDecisions($, router, e.turnId, turn);
3017
+ if (router.config.routingEngine === 'shadow' && router.trace?.turns.has(e.turnId)) {
3018
+ addTrace(router, e, { type: 'end', at: Date.now() });
3019
+ await flushTrace($, router, e.turnId);
3020
+ }
3021
+ router.traceOperations.delete(e.turnId);
2321
3022
  return next(e);
2322
3023
  });
2323
3024
 
@@ -2325,16 +3026,40 @@ export function register(on, options) {
2325
3026
  const result = await next(e);
2326
3027
  // Only the main conversation is routed, so an agent compaction changes nothing here.
2327
3028
  if (!result.skip && e.trigger !== 'precompute' && !e.agentId) {
3029
+ if (!router.trace) {
3030
+ router.traceFreshSession = null;
3031
+ router.traceClearSession = null;
3032
+ }
2328
3033
  const ref = { ...LOOP, id: 'main' };
2329
3034
  const loop = (await $.state.get(ref)).value;
2330
- if (loop) await $.state.set(ref, resetHistory(loop));
3035
+ if (loop) {
3036
+ const reset = resetHistory(loop);
3037
+ await $.state.set(ref, reset);
3038
+ if (router.config.routingEngine === 'shadow' && router.trace) {
3039
+ const event = { type: 'reset', at: Date.now(), cause: 'compact', loop: reset, generation: reset.generation };
3040
+ traceReset(router, event);
3041
+ }
3042
+ }
2331
3043
  clearGoal(router);
2332
3044
  for (const controller of router.controllers) controller.abort();
3045
+ if (router.config.routingEngine === 'auto') {
3046
+ for (const review of router.reviews.values()) review.controller.abort();
3047
+ router.reviews.clear();
3048
+ router.decisions.clear();
3049
+ }
2333
3050
  }
2334
3051
  return result;
2335
3052
  });
2336
3053
 
2337
3054
  on('session.end', async ($, e, next) => {
3055
+ if (router.config.routingEngine === 'shadow') {
3056
+ if (router.trace?.turns.size) router.trace.reasons.add('aborted');
3057
+ await flushTrace($, router, null, true);
3058
+ }
3059
+ router.trace = null;
3060
+ router.traceOperations.clear();
3061
+ router.traceFreshSession = null;
3062
+ router.traceClearSession = e.reason === 'clear' && typeof e.sessionId === 'string' ? e.sessionId : null;
2338
3063
  await endSession($, router);
2339
3064
  return next(e);
2340
3065
  });
@@ -2391,6 +3116,7 @@ export function register(on, options) {
2391
3116
  ],
2392
3117
  });
2393
3118
  }
3119
+ view.decisionRows = await paneDecisionRows($, router);
2394
3120
  const settings = await $.settings.read().catch(() => ({}));
2395
3121
  const modelOptions = Object.keys(router.config.models).filter((alias) =>
2396
3122
  isModelAllowed(router.config.models[alias].id, settings.availableModels, view.nativeModel),