@alexeiled/claude-router 1.23.1 → 1.25.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.
Files changed (81) hide show
  1. package/.claude-plugin/plugin.json +1 -1
  2. package/CHANGELOG.md +62 -1
  3. package/README.md +39 -7
  4. package/docs/architecture.md +27 -4
  5. package/docs/auto-engine.md +152 -0
  6. package/docs/configuration.md +47 -3
  7. package/docs/evaluation.md +222 -3
  8. package/docs/native-router.md +11 -3
  9. package/docs/providers.md +28 -0
  10. package/docs/router-band.svg +124 -133
  11. package/docs/router-pane-classifier.svg +24 -23
  12. package/docs/router-pane-now.svg +9 -7
  13. package/docs/router-pane-policy.svg +4 -4
  14. package/docs/router-pane-routes.svg +8 -8
  15. package/docs/router-pane-usage-whatif.svg +14 -14
  16. package/docs/router-pane-usage.svg +20 -20
  17. package/docs/routing-modes.md +13 -4
  18. package/docs/user-guide.md +79 -19
  19. package/hooks/native-router.mjs +1194 -215
  20. package/lib/activity-stats.mjs +23 -4
  21. package/lib/activity.mjs +7 -5
  22. package/lib/auto-engine.mjs +414 -0
  23. package/lib/auto-route.mjs +253 -0
  24. package/lib/band.mjs +35 -440
  25. package/lib/classifier-client.mjs +12 -8
  26. package/lib/config-file.mjs +7 -2
  27. package/lib/config.mjs +64 -15
  28. package/lib/cost.mjs +5 -1
  29. package/lib/costs.mjs +4 -2
  30. package/lib/decisions.mjs +80 -5
  31. package/lib/display.mjs +69 -20
  32. package/lib/facts.mjs +30 -0
  33. package/lib/modes.mjs +8 -4
  34. package/lib/panel.mjs +75 -2163
  35. package/lib/policy.mjs +7 -6
  36. package/lib/providers.mjs +7 -0
  37. package/lib/replay-trace.mjs +550 -0
  38. package/lib/replay.mjs +718 -0
  39. package/lib/route-line.mjs +46 -0
  40. package/lib/route.mjs +35 -21
  41. package/lib/savings.mjs +14 -3
  42. package/lib/subagents.mjs +41 -11
  43. package/lib/subcommands.mjs +60 -0
  44. package/lib/ui/fallback.mjs +22 -0
  45. package/lib/ui/graphical/band.mjs +256 -0
  46. package/lib/ui/graphical/charts.mjs +163 -0
  47. package/lib/ui/graphical/classifier.mjs +153 -0
  48. package/lib/ui/graphical/frame.mjs +227 -0
  49. package/lib/ui/graphical/kit.mjs +156 -0
  50. package/lib/ui/graphical/meter.mjs +25 -0
  51. package/lib/ui/graphical/now.mjs +353 -0
  52. package/lib/ui/graphical/policy.mjs +56 -0
  53. package/lib/ui/graphical/routes.mjs +264 -0
  54. package/lib/ui/graphical/squares.mjs +29 -0
  55. package/lib/ui/graphical/usage.mjs +376 -0
  56. package/lib/ui/model/band.mjs +439 -0
  57. package/lib/ui/model/classifier.mjs +308 -0
  58. package/lib/ui/model/draft.mjs +62 -0
  59. package/lib/ui/model/format.mjs +41 -0
  60. package/lib/ui/model/frame.mjs +359 -0
  61. package/lib/ui/model/now.mjs +390 -0
  62. package/lib/ui/model/policy.mjs +194 -0
  63. package/lib/ui/model/routes.mjs +392 -0
  64. package/lib/ui/model/usage-agents.mjs +311 -0
  65. package/lib/ui/model/usage-breakdown.mjs +237 -0
  66. package/lib/ui/model/usage-shared.mjs +58 -0
  67. package/lib/ui/model/usage.mjs +330 -0
  68. package/lib/ui/terminal/band.mjs +220 -0
  69. package/lib/ui/terminal/classifier.mjs +142 -0
  70. package/lib/ui/terminal/frame.mjs +169 -0
  71. package/lib/ui/terminal/kit.mjs +133 -0
  72. package/lib/ui/terminal/now.mjs +300 -0
  73. package/lib/ui/terminal/policy.mjs +52 -0
  74. package/lib/ui/terminal/routes.mjs +167 -0
  75. package/lib/ui/terminal/usage.mjs +363 -0
  76. package/lib/ui/terminal/wrap.mjs +37 -0
  77. package/lib/ui/tokens.mjs +106 -0
  78. package/lib/usage.mjs +5 -5
  79. package/lib/view.mjs +5 -2
  80. package/package.json +3 -2
  81. package/types/index.d.ts +15 -0
package/lib/policy.mjs CHANGED
@@ -35,15 +35,15 @@ export function decide({
35
35
  const next = { ...state, turn: state.turn + 1, votes: [...state.votes] };
36
36
  const incumbent = facts.lastRoute && TIERS.includes(facts.lastRoute) ? facts.lastRoute : baseline;
37
37
  const current = incumbentRoute ?? routeFor(incumbent);
38
- const stay = (reason, estimate = null) => result(incumbent, reason, next, estimate);
38
+ const stay = (reason, estimate = /** @type {object | null} */ (null)) => result(incumbent, reason, next, estimate);
39
39
 
40
- const target = facts.failure && facts.failure.signature !== next.escalatedSignature ? escalateTo(incumbent) : null;
41
- if (target) {
40
+ const escalated = facts.failure && facts.failure.signature !== next.escalatedSignature ? escalateTo(incumbent) : null;
41
+ if (escalated) {
42
42
  next.escalatedSignature = facts.failure.signature;
43
43
  next.holdUntilTurn = next.turn + config.policy.escalationHoldTurns;
44
44
  next.votes = [];
45
- const gated = cashGate(config, routeFor(target), facts, now, costs, routeFor);
46
- return gated.blocked ? gatedResult(gated, incumbent, next) : result(target, 'escalation', next);
45
+ const gated = cashGate(config, routeFor(escalated), facts, now, costs, routeFor);
46
+ return gated.blocked ? gatedResult(gated, incumbent, next) : result(escalated, 'escalation', next);
47
47
  }
48
48
  if (next.turn <= next.holdUntilTurn) return stay('hold');
49
49
  if (!advice) return stay('no-advice');
@@ -80,6 +80,7 @@ export function decide({
80
80
  // The move lands on the cheapest tier the answer supports as a whole: from the choice up to just below the
81
81
  // incumbent, the first tier whose mass at or below it clears its bar. A split answer (micro 0.8, low 0.16) on high
82
82
  // moves to low instead of waiting for micro alone to reach the bar. A pending stay reports the choice's estimate.
83
+ /** @type {object | null} */
83
84
  let pending = null;
84
85
  for (const target of TIERS.filter((t) => rank(t) >= rank(choice) && rank(t) < rank(incumbent))) {
85
86
  const support = massAtOrBelow(advice.probabilities, target);
@@ -157,7 +158,7 @@ function trailing(votes, predicate) {
157
158
  return count;
158
159
  }
159
160
 
160
- function result(tier, reason, state, estimate = null) {
161
+ function result(tier, reason, state, estimate = /** @type {object | null} */ (null)) {
161
162
  return { tier, reason, state, estimate };
162
163
  }
163
164
 
package/lib/providers.mjs CHANGED
@@ -29,6 +29,7 @@ export const PROVIDER_DEFAULTS = {
29
29
  billing: 'credits',
30
30
  // xhigh is documented but some Claude Code versions serialize it as high; use max instead.
31
31
  efforts: ['low', 'medium', 'high', 'max'],
32
+ capability: {},
32
33
  strength: 1,
33
34
  imageInput: true,
34
35
  },
@@ -54,6 +55,7 @@ export const PROVIDER_DEFAULTS = {
54
55
  billing: 'credits',
55
56
  // The Anthropic endpoint documents binary thinking, not granular effort. Keep its default thinking.
56
57
  efforts: [],
58
+ capability: {},
57
59
  strength: 1,
58
60
  imageInput: true,
59
61
  },
@@ -63,6 +65,7 @@ export const PROVIDER_DEFAULTS = {
63
65
  contextWindow: 1_000_000,
64
66
  billing: 'credits',
65
67
  efforts: [],
68
+ capability: {},
66
69
  strength: 2,
67
70
  imageInput: true,
68
71
  },
@@ -86,6 +89,7 @@ export const PROVIDER_DEFAULTS = {
86
89
  contextWindow: 1_048_576,
87
90
  billing: 'credits',
88
91
  efforts: EFFORTS,
92
+ capability: {},
89
93
  strength: 1,
90
94
  imageInput: true,
91
95
  },
@@ -108,6 +112,7 @@ export const PROVIDER_DEFAULTS = {
108
112
  contextWindow: 1_000_000,
109
113
  billing: 'credits',
110
114
  efforts: EFFORTS,
115
+ capability: {},
111
116
  strength: 1,
112
117
  imageInput: true,
113
118
  },
@@ -132,6 +137,7 @@ export const PROVIDER_DEFAULTS = {
132
137
  contextWindow: 1_000_000,
133
138
  billing: 'credits',
134
139
  efforts: EFFORTS,
140
+ capability: {},
135
141
  strength: 1,
136
142
  imageInput: true,
137
143
  },
@@ -141,6 +147,7 @@ export const PROVIDER_DEFAULTS = {
141
147
  contextWindow: 1_000_000,
142
148
  billing: 'credits',
143
149
  efforts: EFFORTS,
150
+ capability: {},
144
151
  strength: 2,
145
152
  imageInput: false,
146
153
  },
@@ -0,0 +1,550 @@
1
+ // Narrow replay inputs, not transcripts. Host I/O belongs in hooks/native-router.mjs.
2
+ import { PHASE_VALUES } from './classifier-contract.mjs';
3
+ import { ACTIVITIES, EFFORTS, ROUTING_MODES, TIERS } from './config.mjs';
4
+
5
+ export const TRACE_PREFIX = 'trace:v1:';
6
+ export const TRACE_SESSION_BYTES = 128 * 1024;
7
+ export const TRACE_BUDGET_BYTES = 1024 * 1024;
8
+ export const TRACE_STORE_BYTES = 3 * 1024 * 1024;
9
+ export const TRACE_EXPORT_BYTES = 3 * 1024 * 1024;
10
+ export const TRACE_RETAIN_MS = 30 * 86400_000;
11
+ export const TRACE_ACTIVE_MS = 60 * 60 * 1000;
12
+ const REASONS = [
13
+ 'mid-session',
14
+ 'resume',
15
+ 'reload',
16
+ 'lost-write',
17
+ 'recorder-error',
18
+ 'store-guard',
19
+ 'gap',
20
+ 'conflict',
21
+ 'reset',
22
+ 'mode-gap',
23
+ 'aborted',
24
+ ];
25
+ const number = (v) => (Number.isFinite(v) ? v : null);
26
+ const oneOf = (v, values) => (values.includes(v) ? v : null);
27
+ // Validated routing identifiers may contain spaces, Unicode and provider-specific punctuation.
28
+ const identifier = (v) => (typeof v === 'string' ? v : null);
29
+ const effort = (v) => (Number.isFinite(v) ? v : oneOf(v, EFFORTS));
30
+ const signature = (v) => (typeof v === 'string' && /^[a-f0-9]{1,16}$/.test(v) ? v : null);
31
+ const numbers = (object, keys) =>
32
+ Object.fromEntries(keys.filter((key) => Number.isFinite(object?.[key])).map((key) => [key, object[key]]));
33
+ const strings = (values) => (Array.isArray(values) ? values.map(identifier).filter(Boolean) : []);
34
+ const mapOf = (object, project) =>
35
+ Object.fromEntries(Object.entries(object ?? {}).map(([key, value]) => [key, project(value)]));
36
+ export const traceBytes = (value) => new TextEncoder().encode(JSON.stringify(value)).length;
37
+ const pair = (v) =>
38
+ v && {
39
+ ...(Object.hasOwn(v, 'model') ? { model: identifier(v.model) } : {}),
40
+ ...(Object.hasOwn(v, 'effort') ? { effort: effort(v.effort) } : {}),
41
+ };
42
+ const routingMode = (v) =>
43
+ v && { mode: oneOf(v.mode, ROUTING_MODES), source: oneOf(v.source, ['session', 'project', 'profile', 'default']) };
44
+ const routeTable = (v) => Object.fromEntries(TIERS.filter((tier) => v?.[tier]).map((tier) => [tier, pair(v[tier])]));
45
+ const activities = (v) => Object.fromEntries(ACTIVITIES.filter((a) => v?.[a]).map((a) => [a, routeTable(v[a])]));
46
+ const policyKeys = [
47
+ 'upgradeVotes',
48
+ 'upgradeBase',
49
+ 'upgradeSlope',
50
+ 'upgradePivotUsd',
51
+ 'jumpConfidence',
52
+ 'downgradeVotes',
53
+ 'downgradeMass',
54
+ 'downgradeSlope',
55
+ 'downgradePivotUsd',
56
+ 'downgradeHorizonTurns',
57
+ 'continuationMass',
58
+ 'escalationHoldTurns',
59
+ 'reviewEveryRequests',
60
+ 'minDwellRequests',
61
+ 'cashCapUsd',
62
+ 'activityMass',
63
+ ];
64
+
65
+ function model(v) {
66
+ return {
67
+ id: identifier(v?.id),
68
+ ...numbers(v, ['strength', 'contextWindow', 'input', 'cacheRead', 'output']),
69
+ billing: oneOf(v?.billing, ['plan', 'credits']),
70
+ efforts: (v?.efforts ?? []).map((e) => oneOf(e, EFFORTS)).filter(Boolean),
71
+ capability: Object.fromEntries(
72
+ [...EFFORTS, 'default'].filter((e) => Number.isFinite(v?.capability?.[e])).map((e) => [e, v.capability[e]]),
73
+ ),
74
+ ...(typeof v?.imageInput === 'boolean' ? { imageInput: v.imageInput } : {}),
75
+ ...(v?.longContext ? { longContext: numbers(v.longContext, ['above', 'multiplier']) } : {}),
76
+ ...(v?.offPeak
77
+ ? {
78
+ offPeak: {
79
+ ...numbers(v.offPeak, ['multiplier']),
80
+ peakDays: (v.offPeak.peakDays ?? []).filter((n) => Number.isInteger(n) && n >= 0 && n <= 6),
81
+ peakHoursUtc: (v.offPeak.peakHoursUtc ?? [])
82
+ .filter((p) => Array.isArray(p) && p.length === 2 && p.every(Number.isFinite))
83
+ .map((p) => [...p]),
84
+ },
85
+ }
86
+ : {}),
87
+ };
88
+ }
89
+
90
+ // Configuration paths, classifier URLs/options/keys and source notes are deliberately not copied.
91
+ // Prices are frozen on each model, including configured overrides and time/context-dependent rates.
92
+ export function traceConfig(v) {
93
+ return {
94
+ provider: identifier(v?.provider) ?? 'anthropic',
95
+ routingEngine: oneOf(v?.routingEngine, ['table', 'shadow', 'auto']),
96
+ baselineTier: oneOf(v?.baselineTier, TIERS),
97
+ routes: routeTable(v?.routes),
98
+ activities: activities(v?.activities),
99
+ configuredActivities: activities(v?.configuredActivities ?? v?.activities),
100
+ activityRouting: oneOf(v?.activityRouting, ['off', 'on']),
101
+ mode: oneOf(v?.mode, ROUTING_MODES),
102
+ routingMode: routingMode(v?.routingMode),
103
+ modes: Object.fromEntries(
104
+ ROUTING_MODES.filter((m) => v?.modes?.[m]).map((m) => [m, { policy: numbers(v.modes[m].policy, policyKeys) }]),
105
+ ),
106
+ policy: numbers(v?.policy, policyKeys),
107
+ models: mapOf(v?.models, model),
108
+ effortSplitsCache: Boolean(v?.effortSplitsCache),
109
+ cache: {
110
+ mode: oneOf(v?.cache?.mode, ['explicit', 'automatic', 'disabled']),
111
+ effortScope: oneOf(v?.cache?.effortScope, ['auto', 'shared', 'separate', 'unknown']),
112
+ writeMultiplier: numbers(v?.cache?.writeMultiplier, Object.keys(v?.cache?.writeMultiplier ?? {})),
113
+ ttlMs: numbers(v?.cache?.ttlMs, Object.keys(v?.cache?.ttlMs ?? {})),
114
+ ...numbers(v?.cache, ['warmMarginMs']),
115
+ },
116
+ context: numbers(v?.context, ['recentTurns', 'maxTextChars']),
117
+ };
118
+ }
119
+
120
+ const lastRequest = (v) =>
121
+ v && {
122
+ model: identifier(v.model),
123
+ ...numbers(v, ['tokens', 'outputTokens', 'cacheReadTokens', 'cacheWriteTokens', 'at']),
124
+ };
125
+ const cache = (v) => mapOf(v, (entry) => numbers(entry, ['lastAt', 'prefixTokens']));
126
+ const state = (v) => ({
127
+ ...numbers(v, ['turn', 'holdUntilTurn']),
128
+ votes: (v?.votes ?? []).map((vote) => ({ tier: oneOf(vote.tier, TIERS), turn: number(vote.turn) })),
129
+ escalatedSignature: signature(v?.escalatedSignature),
130
+ });
131
+
132
+ export function traceDecision(v) {
133
+ return (
134
+ v && {
135
+ tier: oneOf(v.tier, TIERS),
136
+ activity: oneOf(v.activity, ACTIVITIES),
137
+ floorActivity: oneOf(v.floorActivity, ACTIVITIES),
138
+ goal: oneOf(v.goal, [...ACTIVITIES, 'uncertain']),
139
+ taskPhase: oneOf(v.taskPhase, PHASE_VALUES),
140
+ model: identifier(v.model),
141
+ effort: effort(v.effort),
142
+ route: pair(v.route),
143
+ pinned: Boolean(v.pinned),
144
+ reason: identifier(v.reason),
145
+ }
146
+ );
147
+ }
148
+
149
+ export function traceLoop(v) {
150
+ return {
151
+ lastRoute: oneOf(v?.lastRoute, TIERS),
152
+ lastActivity: oneOf(v?.lastActivity, ACTIVITIES),
153
+ route: pair(v?.route),
154
+ state: state(v?.state),
155
+ models: cache(v?.models),
156
+ resolutions: mapOf(v?.resolutions, identifier),
157
+ lastRequest: lastRequest(v?.lastRequest),
158
+ historyMeasured: Boolean(v?.historyMeasured),
159
+ ...(typeof v?.hasRoutedDecision === 'boolean' ? { hasRoutedDecision: v.hasRoutedDecision } : {}),
160
+ ...numbers(v, ['lastMessageCount', 'generation', 'requests', 'reviewedAt', 'observedFrom']),
161
+ switchedAt: v?.switchedAt ? numbers(v.switchedAt, ['requests', 'messageCount']) : null,
162
+ ineligible: strings(v?.ineligible),
163
+ suspended: Boolean(v?.suspended),
164
+ engineModel: identifier(v?.engineModel),
165
+ servedRoute: identifier(v?.servedRoute),
166
+ decision: traceDecision(v?.decision),
167
+ };
168
+ }
169
+
170
+ const vector = (v, labels) =>
171
+ v && {
172
+ choice: oneOf(v.choice, labels),
173
+ probabilities: numbers(v.probabilities, labels),
174
+ };
175
+ export const traceAdvice = (v) =>
176
+ v && {
177
+ ...vector(v, [...TIERS, 'uncertain']),
178
+ confidence: number(v.confidence),
179
+ continuation: number(v.continuation),
180
+ activity: vector(v.activity, [...ACTIVITIES, 'uncertain']),
181
+ phase: vector(v.phase, PHASE_VALUES),
182
+ };
183
+
184
+ export function traceFacts(v) {
185
+ return {
186
+ hasImages: Boolean(v?.hasImages),
187
+ continuation: Boolean(v?.continuation),
188
+ downAllowed: Boolean(v?.downAllowed),
189
+ progress: Boolean(v?.progress),
190
+ midTurn: Boolean(v?.midTurn),
191
+ effort: effort(v?.effort),
192
+ contextTokens: number(v?.contextTokens),
193
+ failure: v?.failure ? { signature: signature(v.failure.signature), index: number(v.failure.index) } : null,
194
+ };
195
+ }
196
+
197
+ const checkpoint = (v) => v && { index: number(v.index), ok: Boolean(v.ok) };
198
+ export function traceProgress(v) {
199
+ return (
200
+ v && {
201
+ check: checkpoint(v.check),
202
+ edit: checkpoint(v.edit),
203
+ run: checkpoint(v.run),
204
+ ...numbers(v, ['delegate', 'anyCheck', 'nonDocEdit', 'prompt', 'lastTool']),
205
+ result: v.result ? { index: number(v.result.index), error: Boolean(v.result.error) } : null,
206
+ }
207
+ );
208
+ }
209
+
210
+ // Same priority as routingBucket(observedActivity), evaluated against the caller's own cursor.
211
+ export function observedFromTrace(v, from) {
212
+ if (v.nonDocEdit > from) return 'code';
213
+ if (v.edit?.index > from) return 'docs';
214
+ if (v.run?.index > from || v.anyCheck > from) return 'ops';
215
+ return v.lastTool > from ? 'read' : 'talk';
216
+ }
217
+
218
+ export function completedFromTrace(v, from, activity) {
219
+ const since = Math.max(0, from);
220
+ if (v?.check && v.check.index >= since && v.check.ok) return true;
221
+ if (!v || v.delegate >= since || v.anyCheck >= since) return false;
222
+ const edited = v.edit && v.edit.index >= since;
223
+ const ran = v.run && v.run.index >= since;
224
+ if (activity === 'ops') return !edited && Boolean(ran && v.run.ok);
225
+ if (activity === 'docs') return !ran && Boolean(edited && v.edit.ok && v.nonDocEdit < since);
226
+ if (['explore', 'plan', 'review'].includes(activity))
227
+ return !edited && !ran && v.prompt >= from && from >= 0 && !(v.result?.index >= since && v.result.error);
228
+ return false;
229
+ }
230
+
231
+ export function traceOperation(kind, at, input, result) {
232
+ return {
233
+ kind: oneOf(kind, ['choose', 'observed', 'continue']),
234
+ at,
235
+ taskProgress: traceProgress(input.taskProgress),
236
+ facts: input.facts ? traceFacts(input.facts) : null,
237
+ advice: traceAdvice(input.advice),
238
+ pin: oneOf(input.pin, TIERS),
239
+ nativeModel: identifier(input.nativeModel),
240
+ ...(input.availableModels !== undefined
241
+ ? { availableModels: Array.isArray(input.availableModels) ? strings(input.availableModels) : null }
242
+ : {}),
243
+ contextKnown: Boolean(input.contextKnown),
244
+ contextTokens: number(input.contextTokens),
245
+ hasImages: Boolean(input.hasImages),
246
+ ...(Object.hasOwn(input, 'actualHasImages')
247
+ ? { actualHasImages: typeof input.actualHasImages === 'boolean' ? input.actualHasImages : null }
248
+ : {}),
249
+ effort: effort(input.effort),
250
+ observed: oneOf(input.observed, [...ACTIVITIES, 'read', 'talk']),
251
+ expected: traceDecision(result?.decision),
252
+ };
253
+ }
254
+
255
+ export function traceResponse(at, request, response, ttl) {
256
+ return {
257
+ type: 'response',
258
+ at,
259
+ requestedModel: identifier(request.model),
260
+ effort: effort(request.effort),
261
+ servedModel: identifier(response.usage?.model),
262
+ usage: response.usage
263
+ ? numbers(response.usage, [
264
+ 'input_tokens',
265
+ 'cache_read_input_tokens',
266
+ 'cache_creation_input_tokens',
267
+ 'output_tokens',
268
+ ])
269
+ : null,
270
+ stopReason:
271
+ response.stopReason === null
272
+ ? null
273
+ : (oneOf(response.stopReason, [
274
+ 'end_turn',
275
+ 'tool_use',
276
+ 'max_tokens',
277
+ 'stop_sequence',
278
+ 'model_context_window_exceeded',
279
+ 'refusal',
280
+ 'pause_turn',
281
+ ]) ?? 'other'),
282
+ ttl: oneOf(ttl, ['5m', '1h']),
283
+ };
284
+ }
285
+
286
+ export function traceEvent(v) {
287
+ const common = {
288
+ type: v.type,
289
+ at: number(v.at),
290
+ ...numbers(v, ['seq', 'turn', 'index', 'messageCount', 'generation', 'requestSeq']),
291
+ };
292
+ switch (v.type) {
293
+ case 'initial':
294
+ return {
295
+ ...common,
296
+ configured: traceConfig(v.configured),
297
+ config: traceConfig(v.config),
298
+ loop: traceLoop(v.loop),
299
+ };
300
+ case 'config':
301
+ return { ...common, configured: traceConfig(v.configured), config: traceConfig(v.config) };
302
+ case 'request':
303
+ return {
304
+ ...common,
305
+ model: identifier(v.model),
306
+ effort: effort(v.effort),
307
+ mode: oneOf(v.mode, ['auto', 'manual']),
308
+ engineModel: identifier(v.engineModel),
309
+ engineEffort: effort(v.engineEffort),
310
+ ...numbers(v, ['reviewedAt', 'observedFrom']),
311
+ operations: (v.operations ?? []).map((op) => traceOperation(op.kind, op.at, op, { decision: op.expected })),
312
+ };
313
+ case 'response':
314
+ return {
315
+ ...common,
316
+ ...traceResponse(
317
+ v.at,
318
+ { model: v.requestedModel, effort: v.effort },
319
+ { usage: v.usage && { ...v.usage, model: v.servedModel }, stopReason: v.stopReason },
320
+ v.ttl,
321
+ ),
322
+ };
323
+ case 'reset':
324
+ return {
325
+ ...common,
326
+ cause: oneOf(v.cause, ['clear', 'compact', 'rewind', 'history', 'delete-history']),
327
+ loop: traceLoop(v.loop),
328
+ };
329
+ case 'control':
330
+ return { ...common, mode: routingMode(v.mode), pin: oneOf(v.pin, TIERS), enabled: Boolean(v.enabled) };
331
+ case 'end':
332
+ return common;
333
+ default:
334
+ throw new Error('unknown trace event');
335
+ }
336
+ }
337
+
338
+ export function readTrace(v) {
339
+ if (v?.version !== 1 || !Array.isArray(v.events) || !Number.isFinite(v.startedAt) || !Number.isFinite(v.updatedAt))
340
+ return null;
341
+ try {
342
+ const record = {
343
+ version: 1,
344
+ startedAt: v.startedAt,
345
+ updatedAt: v.updatedAt,
346
+ active: v.active === true,
347
+ incomplete: Array.isArray(v.incomplete) ? v.incomplete.map((r) => oneOf(r, REASONS) ?? 'gap') : ['gap'],
348
+ lostWrites: Number.isSafeInteger(v.lostWrites) && v.lostWrites >= 0 ? v.lostWrites : 1,
349
+ capped: v.capped ? numbers(v.capped, ['at', 'turns', 'events']) : null,
350
+ events: v.events.map(traceEvent),
351
+ };
352
+ const problems = traceProblems(record);
353
+ return { ...record, incomplete: [...new Set([...record.incomplete, ...problems])] };
354
+ } catch {
355
+ return null;
356
+ }
357
+ }
358
+
359
+ export function newTrace(at, snapshot, incomplete = []) {
360
+ return {
361
+ version: 1,
362
+ startedAt: at,
363
+ updatedAt: at,
364
+ active: true,
365
+ incomplete: incomplete.filter((r) => REASONS.includes(r)),
366
+ lostWrites: 0,
367
+ capped: null,
368
+ events: [traceEvent({ type: 'initial', seq: 1, at, ...snapshot })],
369
+ };
370
+ }
371
+
372
+ export function bufferTrace(buffer, event, maxBytes = TRACE_SESSION_BYTES) {
373
+ const held = buffer ?? { events: [], bytes: 2, excludedEvents: 0 };
374
+ if (held.excludedEvents) return { ...held, excludedEvents: held.excludedEvents + 1 };
375
+ const projected = traceEvent(event);
376
+ const bytes = held.bytes + traceBytes(projected) + 1;
377
+ if (bytes > maxBytes) return { events: [], bytes: 2, excludedEvents: held.events.length + 1 };
378
+ return { events: [...held.events, projected], bytes, excludedEvents: 0 };
379
+ }
380
+
381
+ // Append complete turn batches. A cap keeps the prior, usable prefix, never half a turn.
382
+ export function appendTrace(
383
+ record,
384
+ events,
385
+ at,
386
+ { lostWrites = 0, reasons = /** @type {string[]} */ ([]), maxBytes = TRACE_SESSION_BYTES, excludedEvents = 0 } = {},
387
+ ) {
388
+ const next = {
389
+ ...record,
390
+ updatedAt: at,
391
+ lostWrites: record.lostWrites + lostWrites,
392
+ incomplete: [
393
+ ...new Set([
394
+ ...record.incomplete,
395
+ ...reasons.filter((r) => REASONS.includes(r)),
396
+ ...(lostWrites ? ['lost-write'] : []),
397
+ ]),
398
+ ],
399
+ };
400
+ const capped = () => ({
401
+ ...next,
402
+ capped: {
403
+ at: next.capped?.at ?? at,
404
+ turns: (next.capped?.turns ?? 0) + 1,
405
+ events: (next.capped?.events ?? 0) + events.length + excludedEvents,
406
+ },
407
+ });
408
+ if (excludedEvents) return capped();
409
+ if (!events.length) return next;
410
+ if (record.capped) return capped();
411
+ const added = events.map((event, i) => ({ ...traceEvent(event), seq: record.events.length + i + 1 }));
412
+ const all = [...record.events];
413
+ for (const event of added) {
414
+ if (event.type === 'response') {
415
+ const request = all.findLast((e) => e.type === 'request' && e.turn === event.turn && e.index === event.index);
416
+ if (request) event.requestSeq = request.seq;
417
+ else next.incomplete = [...new Set([...next.incomplete, 'gap'])];
418
+ }
419
+ all.push(event);
420
+ }
421
+ const appended = { ...next, events: all };
422
+ appended.incomplete = [...new Set([...appended.incomplete, ...traceProblems(appended)])];
423
+ return traceBytes(appended) > maxBytes ? capped() : appended;
424
+ }
425
+
426
+ export function traceProblems(record) {
427
+ if (
428
+ record?.version !== 1 ||
429
+ !Array.isArray(record.events) ||
430
+ record.events[0]?.type !== 'initial' ||
431
+ !record.events[0]?.configured ||
432
+ !record.events[0]?.config ||
433
+ !record.events[0]?.loop ||
434
+ !Number.isFinite(record.events[0]?.loop?.state?.turn) ||
435
+ ![record.events[0]?.configured, record.events[0]?.config].every(
436
+ (config) =>
437
+ config &&
438
+ TIERS.includes(config.baselineTier) &&
439
+ TIERS.every((tier) => config.routes?.[tier]?.model && config.models?.[config.routes[tier].model]?.id),
440
+ )
441
+ )
442
+ return ['mid-session'];
443
+ return [
444
+ ...new Set([
445
+ ...(Array.isArray(record.incomplete) ? record.incomplete : ['gap']),
446
+ ...(record.lostWrites > 0 ? ['lost-write'] : []),
447
+ ...(record.events.every((event, i) => event.seq === i + 1 && Number.isFinite(event.at)) ? [] : ['gap']),
448
+ ...(record.events.every(
449
+ (event) =>
450
+ event.type !== 'request' ||
451
+ record.events.some((response) => response.type === 'response' && response.requestSeq === event.seq),
452
+ )
453
+ ? []
454
+ : ['gap']),
455
+ ...(record.events.every(
456
+ (event) =>
457
+ event.type !== 'response' ||
458
+ record.events.some(
459
+ (request) =>
460
+ request.type === 'request' &&
461
+ request.seq === event.requestSeq &&
462
+ request.seq < event.seq &&
463
+ request.turn === event.turn &&
464
+ request.index === event.index,
465
+ ),
466
+ )
467
+ ? []
468
+ : ['gap']),
469
+ ]),
470
+ ];
471
+ }
472
+
473
+ export const usableTrace = (record) => traceProblems(record).length === 0;
474
+
475
+ // No record-count limit. Whole inactive records leave by age or oldest first for the byte budget.
476
+ // A recent active lease protects writers; stale activity never defeats day retention.
477
+ export function traceVictims(entries, at, ownKey, candidate, active = new Set()) {
478
+ const others = entries.filter(([key, v]) => key !== ownKey && v?.version === 1 && Number.isFinite(v.updatedAt));
479
+ const expired = others.filter(([, v]) => at - v.updatedAt > TRACE_RETAIN_MS);
480
+ const victims = new Set(expired.map(([key]) => key));
481
+ let bytes =
482
+ traceBytes(ownKey) +
483
+ traceBytes(candidate) +
484
+ 2 +
485
+ entries
486
+ .filter(([key]) => key !== ownKey && !victims.has(key))
487
+ .reduce((sum, [key, v]) => sum + traceBytes(key) + traceBytes(v) + 2, 0);
488
+ for (const [key, v] of others
489
+ .filter(
490
+ ([name, entry]) =>
491
+ !victims.has(name) && !(at - entry.updatedAt <= TRACE_ACTIVE_MS && (active.has(name) || entry.active)),
492
+ )
493
+ .sort((a, b) => a[1].updatedAt - b[1].updatedAt)) {
494
+ if (bytes <= TRACE_BUDGET_BYTES) break;
495
+ victims.add(key);
496
+ bytes -= traceBytes(key) + traceBytes(v) + 2;
497
+ }
498
+ return [...victims];
499
+ }
500
+
501
+ export function traceAdmission(entries, key, candidate) {
502
+ const total = traceBytes(Object.fromEntries(entries));
503
+ const projected = traceBytes({ ...Object.fromEntries(entries), [key]: candidate });
504
+ const traces = entries.filter(([name]) => name.startsWith(TRACE_PREFIX) && name !== key);
505
+ const traceTotal =
506
+ traceBytes(candidate) +
507
+ traceBytes(key) +
508
+ 2 +
509
+ traces.reduce((n, [name, value]) => n + traceBytes(name) + traceBytes(value) + 2, 0);
510
+ return total <= TRACE_STORE_BYTES && projected <= TRACE_STORE_BYTES && traceTotal <= TRACE_BUDGET_BYTES;
511
+ }
512
+
513
+ export function mergeTraceExport(previous, entries) {
514
+ if (
515
+ previous !== null &&
516
+ (previous?.version !== 1 || typeof previous.sessions !== 'object' || Array.isArray(previous.sessions))
517
+ )
518
+ throw new Error('invalid trace export');
519
+ const sessions = {};
520
+ for (const [key, value] of [...Object.entries(previous?.sessions ?? {}), ...entries]) {
521
+ if (!key.startsWith(TRACE_PREFIX)) throw new Error('invalid trace key');
522
+ const projected = readTrace(value);
523
+ if (!projected) throw new Error('invalid trace record');
524
+ const old = sessions[key];
525
+ if (!old) {
526
+ sessions[key] = projected;
527
+ continue;
528
+ }
529
+ const selected =
530
+ projected.events.length > old.events.length || projected.updatedAt > old.updatedAt ? projected : old;
531
+ const conflict = old.events
532
+ .slice(0, Math.min(old.events.length, projected.events.length))
533
+ .some((event, index) => JSON.stringify(event) !== JSON.stringify(projected.events[index]));
534
+ const caps = [old.capped, projected.capped].filter(Boolean);
535
+ sessions[key] = {
536
+ ...selected,
537
+ updatedAt: Math.max(old.updatedAt, projected.updatedAt),
538
+ incomplete: [...new Set([...old.incomplete, ...projected.incomplete, ...(conflict ? ['conflict'] : [])])],
539
+ lostWrites: Math.max(old.lostWrites, projected.lostWrites),
540
+ capped: caps.length
541
+ ? {
542
+ at: Math.min(...caps.map((cap) => cap.at)),
543
+ turns: Math.max(...caps.map((cap) => cap.turns)),
544
+ events: Math.max(...caps.map((cap) => cap.events)),
545
+ }
546
+ : null,
547
+ };
548
+ }
549
+ return { version: 1, sessions };
550
+ }