@alexeiled/claude-router 1.10.2 → 1.10.5

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.
@@ -6,6 +6,7 @@ import {
6
6
  emptyStore,
7
7
  METRICS_PREFIX,
8
8
  mergeMetrics,
9
+ mergeStores,
9
10
  metricsAfterReset,
10
11
  readMetrics,
11
12
  readStore,
@@ -13,6 +14,8 @@ import {
13
14
  recordStore,
14
15
  recordTurn,
15
16
  STORE_KEY,
17
+ STORE_PREFIX,
18
+ storeAfterReset,
16
19
  turnActivity,
17
20
  } from '../lib/activity-stats.mjs';
18
21
  import { renderBand, switchToast } from '../lib/band.mjs';
@@ -53,6 +56,7 @@ import {
53
56
  import { clip, observedActivity, promptIndex } from '../lib/facts.mjs';
54
57
  import { renderPanel, routeDraftOf, routingChanges } from '../lib/panel.mjs';
55
58
  import {
59
+ canMoveUp,
56
60
  cellForModel,
57
61
  chooseRoute,
58
62
  continueRoute,
@@ -61,6 +65,7 @@ import {
61
65
  isNativeFallback,
62
66
  isSameModel,
63
67
  nativeFacts,
68
+ observedMove,
64
69
  observeResponse,
65
70
  prepareLoop,
66
71
  resetHistory,
@@ -114,6 +119,47 @@ const BAND_DETAIL = 'band:detail';
114
119
  const MODE_PREFIX = 'mode:';
115
120
  const isSet = (value) => /^(1|true|yes|on)$/i.test(String(value ?? '').trim());
116
121
 
122
+ // The counts kept across sessions: each session writes only its own record of a kind, `prefix` and its session id,
123
+ // because $.store has no atomic update; the view's `field` shows every session's record since the last reset added
124
+ // up. One marker, SAVINGS_RESET_KEY, resets them all. `legacy` is the key all sessions shared before 1.10.3: it counts
125
+ // as another session's record until a reset deletes it.
126
+ const LEDGERS = {
127
+ savings: {
128
+ prefix: SAVINGS_PREFIX,
129
+ field: 'savingsStore',
130
+ read: readSavingsStore,
131
+ afterReset,
132
+ merge: mergeSavingsStores,
133
+ empty: emptySavingsStore,
134
+ },
135
+ metrics: {
136
+ prefix: METRICS_PREFIX,
137
+ field: 'activityMetrics',
138
+ read: readMetrics,
139
+ afterReset: metricsAfterReset,
140
+ merge: mergeMetrics,
141
+ empty: emptyMetrics,
142
+ },
143
+ subagents: {
144
+ prefix: SUBAGENT_PREFIX,
145
+ field: 'subagentStore',
146
+ read: readSubagentStore,
147
+ afterReset: subagentsAfterReset,
148
+ merge: mergeSubagentStores,
149
+ empty: emptySubagentStore,
150
+ },
151
+ activity: {
152
+ prefix: STORE_PREFIX,
153
+ legacy: STORE_KEY,
154
+ field: 'activityStore',
155
+ read: readStore,
156
+ afterReset: storeAfterReset,
157
+ merge: mergeStores,
158
+ empty: emptyStore,
159
+ },
160
+ };
161
+ const LEDGER_KINDS = Object.keys(LEDGERS);
162
+
117
163
  // Everything the hooks change between events, in one object `register()` creates and passes to its helpers. Module
118
164
  // variables, not $.state: a reload starts them over, and the view is written through to $.state as it changes.
119
165
  function createRouter(options) {
@@ -134,6 +180,8 @@ function createRouter(options) {
134
180
  // Each routed turn's activity record until turn.complete adds it to the stats, and the session's open run of
135
181
  // one activity, flushed to the store when it ends.
136
182
  turnActivities: new Map(),
183
+ // Each turn's classifier review in flight or answered (reviewMidTurn): `{ controller, generation, observedUpTo, answer }`.
184
+ reviews: new Map(),
137
185
  run: null,
138
186
  // The route a cheaper activity move went to, while the turns stay on it (advanceDown); else null.
139
187
  afterDown: null,
@@ -141,24 +189,25 @@ function createRouter(options) {
141
189
  offSwitches: 0,
142
190
  // Each turn's routing-vs-your-model totals until turn.complete adds them to the store.
143
191
  turnSavings: new Map(),
144
- // The totals kept across sessions: this session's record (`{ sessionId, record }`), held here so a refresh never
145
- // reads it back from the store while a write of it is pending, and the sum of every other session's, read on
146
- // refresh. The view shows their sum.
147
- savingsOwn: null,
148
- savingsOthers: null,
149
- // The activity metrics kept across sessions, held the same way: this session's record and the others' sum.
150
- metricsOwn: null,
151
- metricsOthers: null,
192
+ // The counts kept across sessions, by LEDGERS kind: this session's record (`own`, `{ sessionId, record }`), held
193
+ // here so a refresh never reads it back from the store while a write of it is pending, and the sum of every other
194
+ // session's (`others`), read on refresh. The view shows their sum.
195
+ // `othersResetAt` is the reset marker the others were read under: a newer one means they are read again.
196
+ ledgers: Object.fromEntries(
197
+ Object.keys(LEDGERS).map((kind) => [kind, { own: null, others: null, othersResetAt: null }]),
198
+ ),
152
199
  // Bumped by Reset activity stats, so a store write that read the counts before the reset skips.
153
200
  statsResets: 0,
201
+ // Bumped by each pin press, and each pinned turn's count when its route was written: the pin is used up when the
202
+ // first request goes out on that route, unless it was pressed again meanwhile.
203
+ pinPresses: 0,
204
+ turnPins: new Map(),
154
205
  // Each spawned agent's record by agentId (spawnRecord), and when each parent loop last finished an agent of a type,
155
- // for respawns. The subagent totals kept across sessions, held as the savings records are.
206
+ // for respawns.
156
207
  agents: new Map(),
157
208
  finished: new Map(),
158
209
  // Each agent type's definition frontmatter by provider and type, read once per session (agentDefinition).
159
210
  definitions: new Map(),
160
- subagentsOwn: null,
161
- subagentsOthers: null,
162
211
  };
163
212
  }
164
213
 
@@ -221,107 +270,85 @@ async function updateView($, router, patch) {
221
270
  await $.state.set(VIEW, router.view);
222
271
  }
223
272
 
224
- // This session's record kept across sessions, read from the store once per session, and the last reset (ms) from
225
- // any session, read each time: a Reset in another session empties a record held from before it.
226
- async function ownSavings($, router) {
273
+ // This session's record of `kind`, read from the store once per session, and the last reset (ms) from any session,
274
+ // read each time: a Reset in another session empties a record held from before it.
275
+ async function ownRecord($, router, kind) {
276
+ const { prefix, read, afterReset } = LEDGERS[kind];
277
+ const held = router.ledgers[kind];
227
278
  const sessionId = await $.session.id();
228
279
  const resetAt = await $.store.get(SAVINGS_RESET_KEY);
229
- if (router.savingsOwn?.sessionId !== sessionId) {
230
- const record = readSavingsStore(await $.store.get(`${SAVINGS_PREFIX}${sessionId}`));
280
+ if (held.own?.sessionId !== sessionId) {
281
+ const record = read(await $.store.get(`${prefix}${sessionId}`));
231
282
  // Another call may have read it meanwhile and a turn added to it: that one stands.
232
- if (router.savingsOwn?.sessionId !== sessionId) router.savingsOwn = { sessionId, record };
283
+ if (held.own?.sessionId !== sessionId) held.own = { sessionId, record };
233
284
  }
234
- router.savingsOwn.record = afterReset(router.savingsOwn.record, resetAt);
235
- return { own: router.savingsOwn, resetAt };
285
+ held.own.record = afterReset(held.own.record, resetAt);
286
+ return { own: held.own, resetAt };
236
287
  }
237
288
 
238
- // Every other session's record since the last reset, added up.
239
- async function otherSavings($, sessionId, resetAt) {
240
- const own = `${SAVINGS_PREFIX}${sessionId}`;
241
- const keys = (await $.store.keys()).filter((key) => key.startsWith(SAVINGS_PREFIX) && key !== own);
242
- return mergeSavingsStores(await Promise.all(keys.map((key) => $.store.get(key))), resetAt);
289
+ // Every other session's record of `kind` since the last reset, added up and held. `keys` is one $.store.keys() listing.
290
+ async function readOthers($, router, kind, { sessionId, resetAt, keys }) {
291
+ const { prefix, legacy, merge } = LEDGERS[kind];
292
+ const own = `${prefix}${sessionId}`;
293
+ const names = keys.filter((key) => (key.startsWith(prefix) && key !== own) || key === legacy);
294
+ const others = merge(await Promise.all(names.map((key) => $.store.get(key))), resetAt);
295
+ router.ledgers[kind] = { ...router.ledgers[kind], others, othersResetAt: resetAt ?? null };
243
296
  }
244
297
 
245
- // This session's metrics record and the last reset, as ownSavings: Reset stats clears both with one marker.
246
- async function ownMetrics($, router) {
247
- const sessionId = await $.session.id();
248
- const resetAt = await $.store.get(SAVINGS_RESET_KEY);
249
- if (router.metricsOwn?.sessionId !== sessionId) {
250
- const record = readMetrics(await $.store.get(`${METRICS_PREFIX}${sessionId}`));
251
- if (router.metricsOwn?.sessionId !== sessionId) router.metricsOwn = { sessionId, record };
298
+ // The view's sums of `kinds`, this session's record and the others', from what the router holds; a kind whose others
299
+ // were never read gives nothing.
300
+ function ledgerView(router, kinds = LEDGER_KINDS) {
301
+ const patch = {};
302
+ for (const kind of kinds) {
303
+ const { others, own } = router.ledgers[kind];
304
+ if (others) patch[LEDGERS[kind].field] = LEDGERS[kind].merge([others, own?.record]);
252
305
  }
253
- router.metricsOwn.record = metricsAfterReset(router.metricsOwn.record, resetAt);
254
- return { own: router.metricsOwn, resetAt };
255
- }
256
-
257
- // Every other session's metrics since the last reset, added up.
258
- async function otherMetrics($, sessionId, resetAt) {
259
- const own = `${METRICS_PREFIX}${sessionId}`;
260
- const keys = (await $.store.keys()).filter((key) => key.startsWith(METRICS_PREFIX) && key !== own);
261
- return mergeMetrics(await Promise.all(keys.map((key) => $.store.get(key))), resetAt);
306
+ return patch;
262
307
  }
263
308
 
264
- // This session's subagent record and the last reset, as ownSavings: Reset stats clears it with the same marker.
265
- async function ownSubagents($, router) {
266
- const sessionId = await $.session.id();
267
- const resetAt = await $.store.get(SAVINGS_RESET_KEY);
268
- if (router.subagentsOwn?.sessionId !== sessionId) {
269
- const record = readSubagentStore(await $.store.get(`${SUBAGENT_PREFIX}${sessionId}`));
270
- if (router.subagentsOwn?.sessionId !== sessionId) router.subagentsOwn = { sessionId, record };
309
+ // Adds to this session's record of `kind` (`add(record, now)` returns the record itself when it adds nothing) and
310
+ // writes it. A record read before a Reset is never written back: the reset counter is compared after the reads. The
311
+ // record is added to in memory before the write, so a refresh during the write counts it once. True when the view
312
+ // may show the new sums: no reset ran meanwhile.
313
+ async function addToLedger($, router, kind, add) {
314
+ const resets = router.statsResets;
315
+ const { own, resetAt } = await ownRecord($, router, kind);
316
+ const held = router.ledgers[kind];
317
+ // The others held from before a reset in another session are read again: a record from before 1.10.3 has no
318
+ // `since` to tell.
319
+ if (!held.others || held.othersResetAt !== (resetAt ?? null))
320
+ await readOthers($, router, kind, { sessionId: own.sessionId, resetAt, keys: await $.store.keys() });
321
+ if (router.statsResets !== resets) return false;
322
+ const record = add(own.record, Date.now());
323
+ if (record !== own.record) {
324
+ own.record = record;
325
+ await $.store.set(`${LEDGERS[kind].prefix}${own.sessionId}`, record);
271
326
  }
272
- router.subagentsOwn.record = subagentsAfterReset(router.subagentsOwn.record, resetAt);
273
- return { own: router.subagentsOwn, resetAt };
274
- }
275
-
276
- // Every other session's subagent record since the last reset, added up.
277
- async function otherSubagents($, sessionId, resetAt) {
278
- const own = `${SUBAGENT_PREFIX}${sessionId}`;
279
- const keys = (await $.store.keys()).filter((key) => key.startsWith(SUBAGENT_PREFIX) && key !== own);
280
- return mergeSubagentStores(await Promise.all(keys.map((key) => $.store.get(key))), resetAt);
327
+ return router.statsResets === resets;
281
328
  }
282
329
 
283
- // The view's subagent totals, this session's and the others', from what the router holds; nothing until a read
284
- // succeeded.
285
- const subagentView = (router) =>
286
- router.subagentsOthers
287
- ? { subagentStore: mergeSubagentStores([router.subagentsOthers, router.subagentsOwn?.record]) }
288
- : {};
289
-
290
- const metricsView = (router) => mergeMetrics([router.metricsOthers, router.metricsOwn?.record]);
291
-
292
- // The view's totals kept across sessions, from what the router holds; nothing until a read succeeded.
293
- const savedView = (router) =>
294
- router.savingsOthers ? { savingsStore: mergeSavingsStores([router.savingsOthers, router.savingsOwn?.record]) } : {};
295
-
296
330
  // The counts kept across sessions for the view, read when the session starts and the pane opens: another session
297
- // may have added to them. A failed read keeps what the view has; it never breaks a turn or a render. The saved
298
- // totals are taken from the router after the reads, so a turn that finished meanwhile counts once.
331
+ // may have added to them. A failed read keeps what the view has; it never breaks a turn or a render. The sums are
332
+ // taken from the router after the reads, so a turn that finished meanwhile counts once; a Reset meanwhile gives
333
+ // nothing, as the reset view stands.
299
334
  async function storeView($, router) {
300
- const out = {};
301
- try {
302
- out.activityStore = readStore(await $.store.get(STORE_KEY));
303
- } catch {}
304
- try {
305
- const { own, resetAt } = await ownMetrics($, router);
306
- router.metricsOthers = await otherMetrics($, own.sessionId, resetAt);
307
- out.activityMetrics = metricsView(router);
308
- } catch {}
309
- try {
310
- const { own, resetAt } = await ownSavings($, router);
311
- router.savingsOthers = await otherSavings($, own.sessionId, resetAt);
312
- } catch {}
335
+ const resets = router.statsResets;
313
336
  try {
314
- const { own, resetAt } = await ownSubagents($, router);
315
- router.subagentsOthers = await otherSubagents($, own.sessionId, resetAt);
316
- Object.assign(out, subagentView(router));
337
+ const keys = await $.store.keys();
338
+ for (const kind of LEDGER_KINDS) {
339
+ try {
340
+ const { own, resetAt } = await ownRecord($, router, kind);
341
+ await readOthers($, router, kind, { sessionId: own.sessionId, resetAt, keys });
342
+ } catch {}
343
+ }
317
344
  } catch {}
318
- return out;
345
+ return router.statsResets === resets ? ledgerView(router) : {};
319
346
  }
320
347
 
321
348
  // A notice answers the last press in the pane, so the pane opens without one; the last write keeps its Undo in the
322
349
  // status bar.
323
350
  async function openPane($, router) {
324
- await updateView($, router, { notice: null, ...(await storeView($, router)), ...savedView(router) });
351
+ await updateView($, router, { notice: null, ...(await storeView($, router)) });
325
352
  await $.ui.open({ id: PANE, title: PANE_TITLE, focus: true, closeOnEscape: true });
326
353
  }
327
354
 
@@ -349,6 +376,7 @@ async function setPin($, router, tier) {
349
376
  if (view.phase === 'unavailable') return unavailableText(view);
350
377
  const mode = await modeOf($, router, view.mode);
351
378
  if (mode === 'manual') return 'Routing is off. Turn routing on before pinning a turn.';
379
+ router.pinPresses += 1;
352
380
  await updateView($, router, { pendingPin: tier });
353
381
  return `${tier} pinned for the next turn and its tool continuations.`;
354
382
  }
@@ -548,7 +576,8 @@ async function* passMain($, e, next, loop, version, nativeModel, reason, router)
548
576
 
549
577
  // One turn's classification and route, written to the loop at `loopVersion`: the loop and its new version, or null
550
578
  // when the turn was aborted, left the session or Auto, or lost the write. `signal` is the step's: its abort cancels
551
- // the classifier call. The pin is the one in `view`, the view as the step read it.
579
+ // 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
580
+ // is written, so a turn interrupted before then leaves it for the next.
552
581
  async function decideTurn($, router, e, signal, step) {
553
582
  const { sessionId, view, cfg, loop, loopVersion, context, nativeModel, availableModels } = step;
554
583
  const ref = { ...LOOP, id: 'main' };
@@ -560,8 +589,11 @@ async function decideTurn($, router, e, signal, step) {
560
589
  const live = async () => !controller.signal.aborted && (await $.session.id()) === sessionId;
561
590
  try {
562
591
  const pin = view.pendingPin;
563
- const credentials = await resolveCredentials(activeClassifier(cfg), (name) => settingOf($, router.options, name));
564
- const messages = await $.session.messages({ as: 'api' });
592
+ const pinPresses = router.pinPresses;
593
+ const [credentials, messages] = await Promise.all([
594
+ resolveCredentials(activeClassifier(cfg), (name) => settingOf($, router.options, name)),
595
+ $.session.messages({ as: 'api' }),
596
+ ]);
565
597
  if (!(await live())) return null;
566
598
  const facts = nativeFacts(cfg, loop, {
567
599
  messages,
@@ -574,7 +606,6 @@ async function decideTurn($, router, e, signal, step) {
574
606
  phase: 'choosing',
575
607
  activeTurnId: e.turnId,
576
608
  nativeModel,
577
- pendingPin: null,
578
609
  credentials: { ...router.view?.credentials, [cfg.classifier]: credentials.missing },
579
610
  });
580
611
  const adviceStarted = Date.now();
@@ -606,6 +637,8 @@ async function decideTurn($, router, e, signal, step) {
606
637
  });
607
638
  selected.engineModel = e.model;
608
639
  const written = await $.state.set(ref, selected, { ifVersion: loopVersion });
640
+ // The written route serves the turn's next steps, even if an abort lands now.
641
+ if (written.isSet && pin) router.turnPins.set(e.turnId, pinPresses);
609
642
  // Manual, /clear and turn completion abort the controller; one may land during the write.
610
643
  if (!written.isSet || controller.signal.aborted) return null;
611
644
  if (previous?.model && previous.model !== selected.decision.model && !selected.decision.pinned)
@@ -662,6 +695,124 @@ async function decideTurn($, router, e, signal, step) {
662
695
  }
663
696
  }
664
697
 
698
+ // Facts for a step of the running turn, read from the transcript as it is now.
699
+ function stepFacts(cfg, router, loop, e, messages, context) {
700
+ return nativeFacts(cfg, loop, {
701
+ messages,
702
+ prompt: router.prompts.get(e.turnId),
703
+ effort: e.effort,
704
+ turnId: e.turnId,
705
+ contextTokens: context.tokens,
706
+ });
707
+ }
708
+
709
+ // The transcript, or null when it cannot be read: a continuation then keeps its route.
710
+ async function transcript($) {
711
+ try {
712
+ return await $.session.messages({ as: 'api' });
713
+ } catch {
714
+ return null;
715
+ }
716
+ }
717
+
718
+ // A tool continuation whose turn shows stronger work than its route was chosen for moves up once (observedMove). Only
719
+ // tool calls after the last applied review count (`loop.observedFrom`): the review judged the ones before. The
720
+ // transcript is read only when some activity's route at this tier is stronger than the running one.
721
+ async function moveOnObserved($, router, cfg, loop, e, context) {
722
+ if (!canMoveUp(cfg, loop.decision, e.effort)) return loop;
723
+ const messages = await transcript($);
724
+ if (!messages) return loop;
725
+ const facts = stepFacts(cfg, router, loop, e, messages, context);
726
+ const observed = observedActivity(messages, Math.max(promptIndex(messages), (loop.observedFrom ?? 0) - 1));
727
+ const moved = observedMove(cfg, loop, { observed, facts, contextKnown: context.known, now: Date.now() });
728
+ if (moved === loop) return loop;
729
+ $.ui.toast(switchToast(cfg, loop.decision, moved.decision, moved.decision.estimate));
730
+ // Replies from here on are labelled with the moved activity; the classifier's answer stays as recorded.
731
+ const turn = router.turnActivities.get(e.turnId);
732
+ if (turn) router.turnActivities.set(e.turnId, { ...turn, label: moved.decision.activity });
733
+ await updateView($, router, { estimate: moved.decision.estimate ?? null, comparison: null });
734
+ return moved;
735
+ }
736
+
737
+ // Inside a turn the classifier is asked again every `policy.reviewEveryRequests` requests, in the background: a step
738
+ // never waits for it. The answer applies at the first step after it arrives, as a decision on the same task
739
+ // (sameTaskOf), so the tier and the activity can move either way: up on the usual votes, down only past the dwell and a
740
+ // passed verification. Pinned turns and a native fallback are left alone; a failed read or ask changes nothing.
741
+ async function reviewMidTurn($, router, cfg, loop, e, { context, nativeModel, availableModels }) {
742
+ const review = router.reviews.get(e.turnId);
743
+ if (review?.answer) {
744
+ router.reviews.delete(e.turnId);
745
+ // An answer about a history that compaction or a rewind replaced is dropped.
746
+ if (!review.answer.advice || loop.decision?.pinned || review.generation !== loop.generation) return loop;
747
+ // Only the advice is from the review; the checkpoint, context and cache facts are read now.
748
+ const messages = await transcript($);
749
+ if (!messages) return loop;
750
+ const advice = review.answer.advice;
751
+ const facts = { ...stepFacts(cfg, router, loop, e, messages, context), midTurn: true };
752
+ const selected = chooseRoute(cfg, loop, {
753
+ facts,
754
+ advice,
755
+ pin: null,
756
+ nativeModel,
757
+ contextKnown: context.known,
758
+ availableModels,
759
+ now: Date.now(),
760
+ });
761
+ const previous = loop.decision;
762
+ if (previous && (previous.model !== selected.decision.model || previous.effort !== selected.decision.effort)) {
763
+ $.ui.toast(switchToast(cfg, previous, selected.decision, selected.decision.estimate));
764
+ const turn = router.turnActivities.get(e.turnId);
765
+ if (turn) router.turnActivities.set(e.turnId, { ...turn, label: selected.decision.activity ?? null });
766
+ }
767
+ // The pane shows the readings behind the route; a review by a classifier the pane no longer labels keeps them off.
768
+ if (cfg.classifier === router.config.classifier)
769
+ await updateView($, router, {
770
+ comparison: selected.decision.comparison,
771
+ adviceChoice: advice.choice ?? null,
772
+ probabilities: advice.probabilities ?? null,
773
+ estimate: selected.decision.estimate ?? null,
774
+ activityChoice: advice.activity?.choice ?? null,
775
+ activityProbabilities: advice.activity?.probabilities ?? null,
776
+ });
777
+ // Tool calls up to the review's snapshot were judged by it; later ones can still move the route up.
778
+ return { ...selected, observedFrom: review.observedUpTo };
779
+ }
780
+ const every = cfg.policy.reviewEveryRequests;
781
+ if (review || every === 0 || !loop.decision?.tier || loop.decision.pinned) return loop;
782
+ if ((loop.requests ?? 0) - (loop.reviewedAt ?? 0) < every) return loop;
783
+ const job = { controller: new AbortController(), generation: loop.generation, observedUpTo: 0, answer: null };
784
+ router.reviews.set(e.turnId, job);
785
+ try {
786
+ const [credentials, messages] = await Promise.all([
787
+ resolveCredentials(activeClassifier(cfg), (name) => settingOf($, router.options, name)),
788
+ $.session.messages({ as: 'api' }),
789
+ ]);
790
+ job.observedUpTo = messages.length;
791
+ const facts = stepFacts(cfg, router, loop, e, messages, context);
792
+ clientOf(router, cfg.classifier)
793
+ .ask({
794
+ request: (url, init) => $.http.fetch(url, init),
795
+ sleep: (ms, args) => $.clock.sleep(ms, args),
796
+ config: cfg,
797
+ apiKey: credentials.apiKey,
798
+ endpoint: credentials.endpoint,
799
+ prompt: facts.prompt,
800
+ turns: facts.turns,
801
+ signal: job.controller.signal,
802
+ })
803
+ .then((answer) => {
804
+ if (router.reviews.get(e.turnId) === job) job.answer = answer;
805
+ })
806
+ .catch(() => {
807
+ if (router.reviews.get(e.turnId) === job) router.reviews.delete(e.turnId);
808
+ });
809
+ } catch {
810
+ router.reviews.delete(e.turnId);
811
+ return loop;
812
+ }
813
+ return { ...loop, reviewedAt: loop.requests ?? 0 };
814
+ }
815
+
665
816
  // A routed reply's metrics in the view, labelled with the turn's activity when its tier served it, and added to the
666
817
  // turn's activity record with its list price (`routedUsd`, null when unpriced) and, when its tier served it, its route.
667
818
  async function publishReply($, router, turnId, response, tier, route, routedUsd) {
@@ -759,20 +910,11 @@ async function addSavings($, router, turnId, compared, tier) {
759
910
  } catch {}
760
911
  }
761
912
 
762
- // A finished turn's totals added to this session's record kept across sessions, with the guard recordActivity uses:
763
- // totals read before a reset are not written back. The record is added to in memory before the write, so a refresh
764
- // during the write counts the turn once.
913
+ // A finished turn's totals added to this session's record kept across sessions.
765
914
  async function flushSavings($, router, totals) {
766
915
  try {
767
- const resets = router.statsResets;
768
- const { own, resetAt } = await ownSavings($, router);
769
- // The others held from before a reset in another session are read again.
770
- if (!router.savingsOthers || afterReset(router.savingsOthers, resetAt) !== router.savingsOthers)
771
- router.savingsOthers = await otherSavings($, own.sessionId, resetAt);
772
- if (router.statsResets !== resets) return;
773
- own.record = recordSavingsStore(own.record, totals, Date.now());
774
- await $.store.set(`${SAVINGS_PREFIX}${own.sessionId}`, own.record);
775
- if (router.statsResets === resets) await updateView($, router, savedView(router));
916
+ if (await addToLedger($, router, 'savings', (record, now) => recordSavingsStore(record, totals, now)))
917
+ await updateView($, router, ledgerView(router, ['savings']));
776
918
  } catch {}
777
919
  }
778
920
 
@@ -814,90 +956,72 @@ async function recordActivity($, router, turn) {
814
956
  lateral: turn.lateral,
815
957
  }),
816
958
  });
817
- const resets = router.statsResets;
818
- const store = readStore(await $.store.get(STORE_KEY));
819
- const { own, resetAt } = await ownMetrics($, router);
820
- // The others held from before a reset in another session are read again.
821
- if (!router.metricsOthers || metricsAfterReset(router.metricsOthers, resetAt) !== router.metricsOthers)
822
- router.metricsOthers = await otherMetrics($, own.sessionId, resetAt);
823
- // Writing counts read before a reset would bring them back; this turn's are lost instead.
824
- if (router.statsResets !== resets) return;
825
- const written = recordStore(store, {
826
- predicted: turn.predicted,
827
- observed,
828
- runEnded: ended,
829
- lateral: turn.lateral,
830
- });
831
- const measured = recordMetrics(own.record, {
832
- classifier: turn.classifier,
833
- adviceMs: turn.adviceMs,
834
- downMove: down.event,
835
- now: Date.now(),
836
- });
837
- // Added to in memory before the write, so a refresh during the write counts the turn once.
838
- const changed = measured !== own.record;
839
- own.record = measured;
840
- // Both writes start before any reset can run between them.
841
- await Promise.all([
842
- $.store.set(STORE_KEY, written),
843
- changed ? $.store.set(`${METRICS_PREFIX}${own.sessionId}`, measured) : null,
959
+ // Writing counts read before a reset would bring them back; this turn's are lost instead. A reset during a write
960
+ // empties the view; these counts are older than it. Each record is written on its own: a failed write of one
961
+ // keeps the other.
962
+ const stats = { predicted: turn.predicted, observed, runEnded: ended, lateral: turn.lateral };
963
+ const metrics = { classifier: turn.classifier, adviceMs: turn.adviceMs, downMove: down.event };
964
+ const shown = await Promise.all([
965
+ addToLedger($, router, 'activity', (record, now) => recordStore(record, stats, now)).catch(() => false),
966
+ addToLedger($, router, 'metrics', (record, now) => recordMetrics(record, { ...metrics, now })).catch(() => false),
844
967
  ]);
845
- // A reset during the write emptied the view; these counts are older than it.
846
- if (router.statsResets === resets)
847
- await updateView($, router, { activityStore: written, activityMetrics: metricsView(router) });
968
+ const kinds = ['activity', 'metrics'].filter((_, i) => shown[i]);
969
+ if (kinds.length) await updateView($, router, ledgerView(router, kinds));
848
970
  } catch {}
849
971
  }
850
972
 
851
973
  // The session's open run ends with it; without this flush it is never counted.
852
- async function flushRun($, run) {
974
+ async function flushRun($, router, run) {
853
975
  try {
854
- const store = readStore(await $.store.get(STORE_KEY));
855
976
  const ended = { predicted: null, observed: null, runEnded: run, lateral: null };
856
- await $.store.set(STORE_KEY, recordStore(store, ended));
977
+ await addToLedger($, router, 'activity', (record, now) => recordStore(record, ended, now));
857
978
  } catch {}
858
979
  }
859
980
 
860
981
  // The frontmatter of the agent file a spawn starts (agentFrontmatter), or null when it cannot be found or read. Read
861
- // once per provider and type in a session, and never for a built-in, whose definition is not on disk.
982
+ // once per provider and type in a session, and never for a built-in, whose definition is not on disk. A read that
983
+ // failed is not kept: the next spawn of the type reads again.
862
984
  async function agentDefinition($, router, e) {
863
985
  const plugin = e.provider?.plugin;
864
986
  if (typeof plugin !== 'string' || plugin === 'engine' || typeof e.subagentType !== 'string') return null;
865
987
  const key = `${plugin} ${e.subagentType}`;
866
- if (!router.definitions.has(key)) router.definitions.set(key, await findDefinition($, plugin, e.subagentType));
988
+ if (!router.definitions.has(key)) {
989
+ try {
990
+ router.definitions.set(key, await findDefinition($, plugin, e.subagentType));
991
+ } catch {
992
+ return null;
993
+ }
994
+ }
867
995
  return router.definitions.get(key);
868
996
  }
869
997
 
870
998
  // A plugin agent (provider `plugin@marketplace`) is looked up under each install path installed_plugins.json gives
871
999
  // that plugin, the files Claude Code itself loads; any other agent under the session's .claude/agents, then the
872
1000
  // profile's agents. Every match must agree on the model, or the definition is unknown. Limit: a plugin that keeps its
873
- // agents outside `agents/` reads as unknown, so its agents pass through.
1001
+ // agents outside `agents/` reads as unknown, so its agents pass through. Throws when a file cannot be read.
874
1002
  async function findDefinition($, plugin, type) {
875
- try {
876
- const home = await $.env.get('HOME');
877
- const profile = (await $.env.get('CLAUDE_CONFIG_DIR')) ?? `${home}/.claude`;
878
- const name = type.slice(type.indexOf(':') + 1);
879
- const fromPlugin = plugin.includes('@');
880
- const dirs = fromPlugin
881
- ? (JSON.parse(await $.fs.read(`${profile}/plugins/installed_plugins.json`)).plugins?.[plugin] ?? []).map(
882
- (entry) => `${entry.installPath}/agents`,
883
- )
884
- : [`${await $.session.cwd()}/.claude/agents`, `${profile}/agents`];
885
- const found = [];
886
- for (const dir of dirs) {
887
- if (!(await $.fs.exists(dir))) continue;
888
- for (const entry of await $.fs.list(dir)) {
889
- if (entry.kind === 'dir' || !entry.name.endsWith('.md')) continue;
890
- const definition = agentFrontmatter(await $.fs.read(`${dir}/${entry.name}`));
891
- if (definition && (definition.name ?? entry.name.slice(0, -3)) === name) found.push(definition);
892
- }
893
- // A project agent replaces a user agent of the same name.
894
- if (found.length && !fromPlugin) break;
1003
+ const home = await $.env.get('HOME');
1004
+ const profile = (await $.env.get('CLAUDE_CONFIG_DIR')) ?? `${home}/.claude`;
1005
+ const name = type.slice(type.indexOf(':') + 1);
1006
+ const fromPlugin = plugin.includes('@');
1007
+ const dirs = fromPlugin
1008
+ ? (JSON.parse(await $.fs.read(`${profile}/plugins/installed_plugins.json`)).plugins?.[plugin] ?? []).map(
1009
+ (entry) => `${entry.installPath}/agents`,
1010
+ )
1011
+ : [`${await $.session.cwd()}/.claude/agents`, `${profile}/agents`];
1012
+ const found = [];
1013
+ for (const dir of dirs) {
1014
+ if (!(await $.fs.exists(dir))) continue;
1015
+ for (const entry of await $.fs.list(dir)) {
1016
+ if (entry.kind === 'dir' || !entry.name.endsWith('.md')) continue;
1017
+ const definition = agentFrontmatter(await $.fs.read(`${dir}/${entry.name}`));
1018
+ if (definition && (definition.name ?? entry.name.slice(0, -3)) === name) found.push(definition);
895
1019
  }
896
- const agree = found.every((d) => d.model === found[0].model && d.modelRouting === found[0].modelRouting);
897
- return found.length && agree ? found[0] : null;
898
- } catch {
899
- return null;
1020
+ // A project agent replaces a user agent of the same name.
1021
+ if (found.length && !fromPlugin) break;
900
1022
  }
1023
+ const agree = found.every((d) => d.model === found[0].model && d.modelRouting === found[0].modelRouting);
1024
+ return found.length && agree ? found[0] : null;
901
1025
  }
902
1026
 
903
1027
  // The spawn path's classifier client: a breaker of its own, so spawn failures never pause main-turn routing, and no
@@ -933,8 +1057,9 @@ async function decideSpawn($, router, cfg, e, definition, signal) {
933
1057
  }
934
1058
  // The full id, not an alias: a family alias would resolve to the parent's exact model when the families match.
935
1059
  const model = alias ? cfg.models[alias].id : null;
936
- const settings = await $.settings.read().catch(() => ({}));
937
- if (!model || !isModelAllowed(model, settings.availableModels, e.parentModel))
1060
+ // Settings that cannot be read may hold an availableModels list, so the model is not sent.
1061
+ const settings = await $.settings.read().catch(() => null);
1062
+ if (!model || !settings || !isModelAllowed(model, settings.availableModels, e.parentModel))
938
1063
  return { choice: 'core', model: null, failed };
939
1064
  return { choice: alias, model, failed };
940
1065
  }
@@ -1016,21 +1141,15 @@ async function finishAgent($, router, agentId) {
1016
1141
  await flushSubagents($, router, [agent]);
1017
1142
  }
1018
1143
 
1019
- // Agents' counts added to this session's record, with the guard flushSavings uses: counts read before a reset are not
1020
- // written back. Stats never break a turn: a failed read or write loses these counts.
1144
+ // This session's agents' counts added to its record kept across sessions. Stats never break a turn: a failed read or
1145
+ // write loses these counts.
1021
1146
  async function flushSubagents($, router, agents) {
1022
1147
  try {
1023
- const resets = router.statsResets;
1024
- const { own, resetAt } = await ownSubagents($, router);
1025
- const mine = agents.filter((agent) => agent.sessionId === own.sessionId);
1148
+ const sessionId = await $.session.id();
1149
+ const mine = agents.filter((agent) => agent.sessionId === sessionId);
1026
1150
  if (!mine.length) return;
1027
- if (!router.subagentsOthers || subagentsAfterReset(router.subagentsOthers, resetAt) !== router.subagentsOthers)
1028
- router.subagentsOthers = await otherSubagents($, own.sessionId, resetAt);
1029
- if (router.statsResets !== resets) return;
1030
- const now = Date.now();
1031
- own.record = mine.reduce((record, agent) => recordAgent(record, agent, now), own.record);
1032
- await $.store.set(`${SUBAGENT_PREFIX}${own.sessionId}`, own.record);
1033
- if (router.statsResets === resets) await updateView($, router, subagentView(router));
1151
+ const add = (record, now) => mine.reduce((sum, agent) => recordAgent(sum, agent, now), record);
1152
+ if (await addToLedger($, router, 'subagents', add)) await updateView($, router, ledgerView(router, ['subagents']));
1034
1153
  } catch {}
1035
1154
  }
1036
1155
 
@@ -1193,40 +1312,28 @@ function paneActions($, router, view) {
1193
1312
  router.afterDown = null;
1194
1313
  router.turnSavings.clear();
1195
1314
  for (const [id, agent] of router.agents) router.agents.set(id, flushedAgent(agent));
1196
- const clear = (key, value) =>
1197
- $.store
1198
- .set(key, value)
1199
- .then(() => true)
1200
- .catch(() => false);
1201
- // The per-session records: savings and activity metrics.
1315
+ // Every session's records. The marker is written first, so a session still holding its record from before the
1316
+ // reset drops it, unless that record's first count has the reset's millisecond or the clock moved back across
1317
+ // the reset.
1202
1318
  const clearRecords = async () => {
1203
- // Written first, so a session still holding its record from before the reset drops it, unless that record's
1204
- // first reading has the reset's millisecond or the clock moved back across the reset.
1205
- await $.store.set(SAVINGS_RESET_KEY, Date.now());
1319
+ const resetAt = Date.now();
1320
+ await $.store.set(SAVINGS_RESET_KEY, resetAt);
1206
1321
  const keys = (await $.store.keys()).filter((key) =>
1207
- [SAVINGS_PREFIX, METRICS_PREFIX, SUBAGENT_PREFIX].some((prefix) => key.startsWith(prefix)),
1322
+ Object.values(LEDGERS).some(({ prefix, legacy }) => key.startsWith(prefix) || key === legacy),
1208
1323
  );
1209
1324
  await Promise.all(keys.map((key) => $.store.delete(key)));
1210
- router.savingsOwn = null;
1211
- router.savingsOthers = emptySavingsStore();
1212
- router.metricsOwn = null;
1213
- router.metricsOthers = emptyMetrics();
1214
- router.subagentsOwn = null;
1215
- router.subagentsOthers = emptySubagentStore();
1325
+ for (const kind of LEDGER_KINDS)
1326
+ router.ledgers[kind] = { own: null, others: LEDGERS[kind].empty(), othersResetAt: resetAt };
1216
1327
  return true;
1217
1328
  };
1218
- const [stats, records] = await Promise.all([clear(STORE_KEY, emptyStore()), clearRecords().catch(() => false)]);
1329
+ const cleared = await clearRecords().catch(() => false);
1219
1330
  await updateView($, router, {
1220
1331
  activityStats: null,
1221
1332
  savingsBy: {},
1222
- ...(stats ? { activityStore: emptyStore() } : {}),
1223
- ...(records
1224
- ? { activityMetrics: emptyMetrics(), savingsStore: emptySavingsStore(), subagentStore: emptySubagentStore() }
1225
- : {}),
1226
- notice:
1227
- stats && records
1228
- ? 'Stats reset: activity and routing vs your model, this session and saved.'
1229
- : 'This session’s stats reset. Saved stats could not be cleared.',
1333
+ ...(cleared ? ledgerView(router) : {}),
1334
+ notice: cleared
1335
+ ? 'Stats reset: activity and routing vs your model, this session and saved.'
1336
+ : 'This session’s stats reset. Saved stats could not be cleared.',
1230
1337
  });
1231
1338
  },
1232
1339
  discardRouting: () => updateView($, router, { routeDraft: null, tuning: null, tuningBase: null, notice: null }),
@@ -1287,12 +1394,15 @@ async function endSession($, router) {
1287
1394
  router.decisions.clear();
1288
1395
  router.prompts.clear();
1289
1396
  router.turnConfigs.clear();
1397
+ router.turnPins.clear();
1290
1398
  router.turnActivities.clear();
1399
+ for (const review of router.reviews.values()) review.controller.abort();
1400
+ router.reviews.clear();
1291
1401
  router.turnSavings.clear();
1292
1402
  const run = router.run;
1293
1403
  router.run = null;
1294
1404
  router.afterDown = null;
1295
- if (run) await flushRun($, run);
1405
+ if (run) await flushRun($, router, run);
1296
1406
  // Agents still running when the session ends: what they did so far is counted.
1297
1407
  const agents = [...router.agents.values()];
1298
1408
  router.agents.clear();
@@ -1356,7 +1466,6 @@ export function register(on, options) {
1356
1466
  lastWrite: null,
1357
1467
  bandDetail: (await $.store.get(BAND_DETAIL).catch(() => false)) === true,
1358
1468
  ...(await storeView($, router)),
1359
- ...savedView(router),
1360
1469
  });
1361
1470
  } catch (error) {
1362
1471
  await updateView($, router, {
@@ -1404,9 +1513,7 @@ export function register(on, options) {
1404
1513
  on('turn.step', async function* ($, e, next) {
1405
1514
  if (e.agentId) return yield* stepAgent($, router, e, next);
1406
1515
  const cfg = router.turnConfigs.get(e.turnId) ?? router.config;
1407
- const sessionId = await $.session.id();
1408
- const nativeModel = await $.session.model();
1409
- const view = await readView($, router);
1516
+ const [sessionId, nativeModel, view] = await Promise.all([$.session.id(), $.session.model(), readView($, router)]);
1410
1517
  const mode = await modeOf($, router, view.mode);
1411
1518
  if (e.index === 0) {
1412
1519
  const saved = await rememberMode($, mode);
@@ -1426,8 +1533,7 @@ export function register(on, options) {
1426
1533
  if (loop.turnId === e.turnId && isNativeFallback(loop, e.model)) {
1427
1534
  return yield* passMain($, e, next, loop, loopVersion, nativeModel, 'native-fallback', router);
1428
1535
  }
1429
- const context = await contextOf($, loop);
1430
- const settings = await $.settings.read();
1536
+ const [context, settings] = await Promise.all([contextOf($, loop), $.settings.read()]);
1431
1537
  const availableModels = settings.availableModels;
1432
1538
  const key = `${sessionId}:${e.turnId}:${loop.generation}`;
1433
1539
  if (loop.turnId !== e.turnId) {
@@ -1456,6 +1562,9 @@ export function register(on, options) {
1456
1562
  loop = selected.loop;
1457
1563
  loopVersion = selected.version;
1458
1564
  } else {
1565
+ // A review answer applies first, so tool calls made after its snapshot can still move the route up.
1566
+ loop = await reviewMidTurn($, router, cfg, loop, e, { context, nativeModel, availableModels });
1567
+ loop = await moveOnObserved($, router, cfg, loop, e, context);
1459
1568
  loop = continueRoute(cfg, loop, {
1460
1569
  nativeModel,
1461
1570
  contextTokens: context.tokens,
@@ -1465,6 +1574,11 @@ export function register(on, options) {
1465
1574
  });
1466
1575
  await updateView($, router, continuationView(cfg, loop.decision, context));
1467
1576
  }
1577
+ const pinPresses = router.turnPins.get(e.turnId);
1578
+ if (pinPresses !== undefined) {
1579
+ router.turnPins.delete(e.turnId);
1580
+ if (pinPresses === router.pinPresses) await updateView($, router, { pendingPin: null });
1581
+ }
1468
1582
  const request = { ...e, model: loop.decision.model };
1469
1583
  if (loop.decision.effort === null) delete request.effort;
1470
1584
  else request.effort = loop.decision.effort;
@@ -1480,6 +1594,9 @@ export function register(on, options) {
1480
1594
  return next(e);
1481
1595
  }
1482
1596
  router.turnConfigs.delete(e.turnId);
1597
+ router.turnPins.delete(e.turnId);
1598
+ router.reviews.get(e.turnId)?.controller.abort();
1599
+ router.reviews.delete(e.turnId);
1483
1600
  router.turnControllers.get(e.turnId)?.abort();
1484
1601
  if (router.view?.activeTurnId === e.turnId && router.view.phase === 'choosing') {
1485
1602
  router.view = { ...router.view, activeTurnId: null };