@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
@@ -0,0 +1,253 @@
1
+ // Stateful main-turn adapter. Table/shadow never enter this path.
2
+ import { acceptActivity, acceptPhase, routingActivity } from './activity.mjs';
3
+ import { assessCandidates, decideMove, initialIncumbentState, proposeAutoRoute, selectTarget } from './auto-engine.mjs';
4
+ import { TIERS } from './config.mjs';
5
+ import { economicConfig, hasRoutedDecision, isModelAllowed, isSameModel } from './route.mjs';
6
+
7
+ const aliasRoute = (config, model, effort) => ({
8
+ model:
9
+ Object.keys(config.models).find(
10
+ (key) => isSameModel(config.models[key].id, model) || isSameModel(model, config.models[key].id),
11
+ ) ?? model,
12
+ effort: effort ?? null,
13
+ });
14
+ // An external response owns physical incumbent identity, but never changes demand evidence.
15
+ // A substituted response does not report the actual effort; null is unknown, not an inferred preset.
16
+ export function externalIncumbent(config, { requestedModel, effort, usage }) {
17
+ const served = usage?.model ?? requestedModel;
18
+ const actualEffort = isSameModel(requestedModel, served) ? (effort ?? null) : null;
19
+ return {
20
+ incumbent: aliasRoute(config, served, actualEffort),
21
+ incumbentId: served,
22
+ incumbentOrigin: 'external-fallback',
23
+ };
24
+ }
25
+
26
+ export function observeAutoFallback(config, loop, response) {
27
+ if (!loop.auto) return loop;
28
+ const external = externalIncumbent(config, response);
29
+ return {
30
+ ...loop,
31
+ auto: loop.auto.savedPin
32
+ ? { ...loop.auto, fallback: { ...external, switchedAt: loop.switchedAt, servedRoute: loop.servedRoute } }
33
+ : { ...loop.auto, ...external },
34
+ };
35
+ }
36
+
37
+ // Availability is operator catalog evidence; cache warmth, failures and the clock are not.
38
+ // Fingerprint allowed aliases, not raw allowlist order or routine response-ID resolutions.
39
+ export function autoCatalogKey(config, { availableModels, nativeModel, models = config.models }) {
40
+ const allowed = Object.keys(models).filter((alias) => isModelAllowed(models[alias].id, availableModels, nativeModel));
41
+ return JSON.stringify([config.models, config.policy, config.cache, config.activityRouting, allowed]);
42
+ }
43
+ const level = (n) => Number.isFinite(n) && n >= 0 && n <= 3 && Number.isInteger(n * 2);
44
+
45
+ const validSwitch = (value) =>
46
+ value === null ||
47
+ (Number.isSafeInteger(value?.requests) &&
48
+ value.requests >= 0 &&
49
+ Number.isSafeInteger(value.messageCount) &&
50
+ value.messageCount >= 0);
51
+ const validServed = (value) => value === null || typeof value === 'string';
52
+ const validPin = (value) =>
53
+ value == null || (TIERS.includes(value.pin) && validSwitch(value.switchedAt) && validServed(value.servedRoute));
54
+ const validFallback = (value) =>
55
+ value == null ||
56
+ (typeof value.incumbent?.model === 'string' &&
57
+ typeof value.incumbentId === 'string' &&
58
+ value.incumbentOrigin === 'external-fallback' &&
59
+ validSwitch(value.switchedAt) &&
60
+ validServed(value.servedRoute));
61
+
62
+ function validAuto(saved) {
63
+ const s = saved?.state;
64
+ return (
65
+ saved?.version === 1 &&
66
+ level(s?.demand) &&
67
+ Number.isInteger(s.demand) &&
68
+ level(s.routedDemand) &&
69
+ Number.isSafeInteger(s.turn) &&
70
+ s.turn >= 0 &&
71
+ Number.isSafeInteger(s.holdUntilTurn) &&
72
+ Array.isArray(s.votes) &&
73
+ s.votes.every((n) => level(n) && Number.isInteger(n)) &&
74
+ typeof saved.incumbent?.model === 'string' &&
75
+ typeof saved.incumbentId === 'string' &&
76
+ validPin(saved.savedPin) &&
77
+ validFallback(saved.fallback)
78
+ );
79
+ }
80
+
81
+ function stateFor(projected, loop, input, mode, catalog) {
82
+ const valid = validAuto(loop.auto);
83
+ if (valid && loop.auto.generation === loop.generation) return { ...loop.auto };
84
+ // A history reset preserves a running pin's underlying incumbent, not its temporary request.
85
+ const restore = valid && loop.auto.savedPin;
86
+ const model = loop.decision?.model ?? input.engineModel ?? input.nativeModel;
87
+ const incumbent = restore
88
+ ? loop.auto.incumbent
89
+ : aliasRoute(projected, model, loop.decision?.effort ?? input.facts.effort);
90
+ return {
91
+ version: 1,
92
+ generation: loop.generation,
93
+ state: initialIncumbentState({ config: projected, incumbent, facts: input.facts }),
94
+ incumbent,
95
+ incumbentId: restore ? loop.auto.incumbentId : model,
96
+ advice: null,
97
+ boundedExecute: false,
98
+ activity: null,
99
+ demandResult: null,
100
+ savedPin: restore ? loop.auto.savedPin : null,
101
+ fallback: restore ? loop.auto.fallback : null,
102
+ mode,
103
+ catalog,
104
+ };
105
+ }
106
+
107
+ function continueProposal(args, auto) {
108
+ const { state } = auto;
109
+ const discount = auto.boundedExecute && !state.headroom && state.turn > state.holdUntilTurn ? 0.5 : 0;
110
+ const demand = {
111
+ ...auto.demandResult,
112
+ level: Math.max(0, state.demand - discount),
113
+ state,
114
+ escalated: false,
115
+ headroom: state.headroom,
116
+ };
117
+ const candidates = assessCandidates(args);
118
+ const target = selectTarget({ candidates, demand: demand.level, mode: args.mode, headroom: state.headroom });
119
+ const next = state.headroom ? { ...state, headroom: target.headroom } : state;
120
+ const move = decideMove({ ...args, state: next, demandResult: demand, candidates, target });
121
+ return { demand, target, move, state: move.state };
122
+ }
123
+
124
+ function decisionFor(config, auto, input, proposal, pin) {
125
+ const { demand, target, move } = proposal;
126
+ const route = move.route;
127
+ const model = route ? (config.models[route.model]?.id ?? route.model) : (input.engineModel ?? input.nativeModel);
128
+ // Candidate effort is already native: do not clamp numeric effort or invent a declaration for null.
129
+ const effort = route
130
+ ? (route.effort ?? (config.models[route.model]?.efforts.length ? (input.facts.effort ?? null) : null))
131
+ : (input.facts.effort ?? null);
132
+ const reason = route ? move.reason : 'no-route-native';
133
+ return {
134
+ tier: TIERS[demand.raw ?? auto.state.demand],
135
+ route,
136
+ model,
137
+ effort,
138
+ reason,
139
+ pinned: Boolean(pin),
140
+ requestedPin: pin ?? null,
141
+ escalated: !pin && (demand.escalated || (move.move && ['escalation', 'escalation-unknown'].includes(move.reason))),
142
+ activity: pin ? null : auto.activity,
143
+ goal: pin ? null : acceptActivity(config, auto.advice),
144
+ taskPhase: pin ? null : acceptPhase(config, auto.advice),
145
+ comparison: null,
146
+ estimate: null,
147
+ auto: {
148
+ demand: demand.level,
149
+ reason: demand.reason,
150
+ headroom: target.headroom,
151
+ targetReason: target.reason,
152
+ requirement: target.requirement,
153
+ outcome: target.outcome,
154
+ route: target.route ? `${target.route.model}@${target.route.effort ?? 'session'}` : null,
155
+ capability: target.capability,
156
+ minUsd: target.estimate?.minUsd,
157
+ maxUsd: target.estimate?.maxUsd,
158
+ move: reason,
159
+ },
160
+ };
161
+ }
162
+
163
+ // Only versioned state is authoritative; resets never restore old demand votes or pending moves.
164
+ // Cache and resolution observations belong to the shared physical loop, not the engine state.
165
+ export function autoRoute(
166
+ config,
167
+ previous,
168
+ input,
169
+ { continuation = false, observed = /** @type {string | null} */ (null) } = {},
170
+ ) {
171
+ const { facts, now, nativeModel, availableModels, contextKnown } = input;
172
+ const mode = config.routingMode?.mode ?? config.mode ?? 'balanced';
173
+ const projected = economicConfig(config, previous);
174
+ const catalog = autoCatalogKey(config, { availableModels, nativeModel, models: projected.models });
175
+ const auto = stateFor(projected, previous, input, mode, catalog);
176
+ let loop = previous;
177
+ if (!continuation && loop.turnId !== facts.turnKey && auto.savedPin) {
178
+ loop = { ...loop, switchedAt: auto.savedPin.switchedAt, servedRoute: auto.savedPin.servedRoute };
179
+ auto.savedPin = null;
180
+ if (auto.fallback) {
181
+ const { switchedAt, servedRoute, ...external } = auto.fallback;
182
+ loop = { ...loop, switchedAt, servedRoute };
183
+ Object.assign(auto, external);
184
+ auto.fallback = null;
185
+ }
186
+ }
187
+ // An alias edit must not silently replace the incumbent with the alias's newly assigned model.
188
+ const id = projected.models[auto.incumbent.model]?.id;
189
+ if (!isSameModel(id, auto.incumbentId) && !isSameModel(auto.incumbentId, id))
190
+ auto.incumbent = aliasRoute(projected, auto.incumbentId, auto.incumbent.effort);
191
+ const changeCause = mode !== auto.mode ? 'mode' : catalog !== auto.catalog ? 'catalog' : (auto.changeCause ?? null);
192
+ const pin = continuation ? (auto.savedPin?.pin ?? null) : input.pin;
193
+ if (!pin && !continuation) {
194
+ auto.advice = input.advice;
195
+ const accepted = config.activityRouting === 'on' ? acceptActivity(config, input.advice) : null;
196
+ const signal = routingActivity(config, input.advice);
197
+ if (accepted)
198
+ auto.activity = signal !== null && signal.mass >= config.policy.activityMass ? signal.choice : accepted;
199
+ auto.boundedExecute = accepted !== null && acceptPhase(config, input.advice) === 'execute';
200
+ }
201
+ if (!pin && observed !== null && ['code', 'docs', 'ops'].includes(observed)) auto.activity = observed;
202
+ if (!pin && observed !== null && ['code', 'docs'].includes(observed)) auto.boundedExecute = false;
203
+ const args = {
204
+ config: projected,
205
+ facts: {
206
+ ...facts,
207
+ ...(auto.incumbentOrigin === 'external-fallback' && auto.incumbent.effort === null ? { effort: null } : {}),
208
+ ineligible: loop.ineligible.map((model) => loop.resolutions[model] ?? model),
209
+ dwellAllowed: !loop.switchedAt || loop.requests - loop.switchedAt.requests >= config.policy.minDwellRequests,
210
+ },
211
+ now,
212
+ nativeModel,
213
+ availableModels,
214
+ contextKnown,
215
+ incumbent: continuation && pin ? aliasRoute(projected, loop.decision.model, loop.decision.effort) : auto.incumbent,
216
+ state: auto.state,
217
+ advice: auto.advice,
218
+ mode,
219
+ changeCause,
220
+ startup: !hasRoutedDecision(previous),
221
+ pin,
222
+ boundedExecute: auto.boundedExecute,
223
+ incumbentOrigin: !continuation && !facts.midTurn ? auto.incumbentOrigin : null,
224
+ };
225
+ const proposal = !continuation || pin ? proposeAutoRoute(args) : continueProposal(args, auto);
226
+ const { demand, move } = proposal;
227
+ if (pin) auto.savedPin ??= { pin, switchedAt: loop.switchedAt, servedRoute: loop.servedRoute };
228
+ else {
229
+ auto.state = proposal.state;
230
+ auto.demandResult = demand;
231
+ if (['reentry', 'same-route'].includes(move.reason) && args.incumbentOrigin) auto.incumbentOrigin = null;
232
+ if (move.route) {
233
+ auto.incumbent = move.route;
234
+ auto.incumbentId = projected.models[move.route.model]?.id ?? move.route.model;
235
+ }
236
+ auto.mode = mode;
237
+ auto.catalog = catalog;
238
+ auto.changeCause =
239
+ !move.move && move.reason !== 'same-route' && demand.level === auto.state.routedDemand ? changeCause : null;
240
+ }
241
+ return {
242
+ ...loop,
243
+ hasRoutedDecision: true,
244
+ auto,
245
+ turnId: facts.turnKey,
246
+ suspended: false,
247
+ route: auto.incumbent,
248
+ lastRoute: pin ? loop.lastRoute : TIERS[auto.state.demand],
249
+ lastActivity: pin ? loop.lastActivity : auto.activity,
250
+ reviewedAt: continuation ? loop.reviewedAt : loop.requests,
251
+ decision: decisionFor(config, auto, input, proposal, pin),
252
+ };
253
+ }