@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.
- package/.claude-plugin/plugin.json +1 -1
- package/CHANGELOG.md +62 -1
- package/README.md +39 -7
- package/docs/architecture.md +27 -4
- package/docs/auto-engine.md +152 -0
- package/docs/configuration.md +47 -3
- package/docs/evaluation.md +222 -3
- package/docs/native-router.md +11 -3
- package/docs/providers.md +28 -0
- package/docs/router-band.svg +124 -133
- package/docs/router-pane-classifier.svg +24 -23
- package/docs/router-pane-now.svg +9 -7
- package/docs/router-pane-policy.svg +4 -4
- package/docs/router-pane-routes.svg +8 -8
- package/docs/router-pane-usage-whatif.svg +14 -14
- package/docs/router-pane-usage.svg +20 -20
- package/docs/routing-modes.md +13 -4
- package/docs/user-guide.md +79 -19
- package/hooks/native-router.mjs +1194 -215
- package/lib/activity-stats.mjs +23 -4
- package/lib/activity.mjs +7 -5
- package/lib/auto-engine.mjs +414 -0
- package/lib/auto-route.mjs +253 -0
- package/lib/band.mjs +35 -440
- package/lib/classifier-client.mjs +12 -8
- package/lib/config-file.mjs +7 -2
- package/lib/config.mjs +64 -15
- package/lib/cost.mjs +5 -1
- package/lib/costs.mjs +4 -2
- package/lib/decisions.mjs +80 -5
- package/lib/display.mjs +69 -20
- package/lib/facts.mjs +30 -0
- package/lib/modes.mjs +8 -4
- package/lib/panel.mjs +75 -2163
- package/lib/policy.mjs +7 -6
- package/lib/providers.mjs +7 -0
- package/lib/replay-trace.mjs +550 -0
- package/lib/replay.mjs +718 -0
- package/lib/route-line.mjs +46 -0
- package/lib/route.mjs +35 -21
- package/lib/savings.mjs +14 -3
- package/lib/subagents.mjs +41 -11
- package/lib/subcommands.mjs +60 -0
- package/lib/ui/fallback.mjs +22 -0
- package/lib/ui/graphical/band.mjs +256 -0
- package/lib/ui/graphical/charts.mjs +163 -0
- package/lib/ui/graphical/classifier.mjs +153 -0
- package/lib/ui/graphical/frame.mjs +227 -0
- package/lib/ui/graphical/kit.mjs +156 -0
- package/lib/ui/graphical/meter.mjs +25 -0
- package/lib/ui/graphical/now.mjs +353 -0
- package/lib/ui/graphical/policy.mjs +56 -0
- package/lib/ui/graphical/routes.mjs +264 -0
- package/lib/ui/graphical/squares.mjs +29 -0
- package/lib/ui/graphical/usage.mjs +376 -0
- package/lib/ui/model/band.mjs +439 -0
- package/lib/ui/model/classifier.mjs +308 -0
- package/lib/ui/model/draft.mjs +62 -0
- package/lib/ui/model/format.mjs +41 -0
- package/lib/ui/model/frame.mjs +359 -0
- package/lib/ui/model/now.mjs +390 -0
- package/lib/ui/model/policy.mjs +194 -0
- package/lib/ui/model/routes.mjs +392 -0
- package/lib/ui/model/usage-agents.mjs +311 -0
- package/lib/ui/model/usage-breakdown.mjs +237 -0
- package/lib/ui/model/usage-shared.mjs +58 -0
- package/lib/ui/model/usage.mjs +330 -0
- package/lib/ui/terminal/band.mjs +220 -0
- package/lib/ui/terminal/classifier.mjs +142 -0
- package/lib/ui/terminal/frame.mjs +169 -0
- package/lib/ui/terminal/kit.mjs +133 -0
- package/lib/ui/terminal/now.mjs +300 -0
- package/lib/ui/terminal/policy.mjs +52 -0
- package/lib/ui/terminal/routes.mjs +167 -0
- package/lib/ui/terminal/usage.mjs +363 -0
- package/lib/ui/terminal/wrap.mjs +37 -0
- package/lib/ui/tokens.mjs +106 -0
- package/lib/usage.mjs +5 -5
- package/lib/view.mjs +5 -2
- package/package.json +3 -2
- package/types/index.d.ts +15 -0
package/lib/activity-stats.mjs
CHANGED
|
@@ -128,7 +128,13 @@ const LATENCY_CLASSIFIERS = 8;
|
|
|
128
128
|
|
|
129
129
|
// `since` (ms) is the first count after a reset; null in a record from before 1.10.3.
|
|
130
130
|
export function emptyStore() {
|
|
131
|
-
return {
|
|
131
|
+
return {
|
|
132
|
+
version: 1,
|
|
133
|
+
since: /** @type {number | null} */ (null),
|
|
134
|
+
confusion: {},
|
|
135
|
+
runs: {},
|
|
136
|
+
lateral: { taken: 0, refused: 0 },
|
|
137
|
+
};
|
|
132
138
|
}
|
|
133
139
|
|
|
134
140
|
// The p95 of a latency histogram: the upper bound of its bucket in ms, `over` when it lies above the last bound, and
|
|
@@ -229,7 +235,13 @@ export function mergeStores(values, resetAt = null) {
|
|
|
229
235
|
// classifier id, and the cheaper activity moves taken in `on` with the escalations that followed one, since `since`
|
|
230
236
|
// (ms), the first reading after a reset.
|
|
231
237
|
export function emptyMetrics() {
|
|
232
|
-
return {
|
|
238
|
+
return {
|
|
239
|
+
version: 1,
|
|
240
|
+
since: /** @type {number | null} */ (null),
|
|
241
|
+
latency: {},
|
|
242
|
+
downMoves: { moves: 0, escalations: 0 },
|
|
243
|
+
unpriced: emptyUnpriced(),
|
|
244
|
+
};
|
|
233
245
|
}
|
|
234
246
|
|
|
235
247
|
// Why a routed main reply was left out of the usage record (unpricedCause in savings.mjs): its usage did not read
|
|
@@ -264,7 +276,13 @@ export function readMetrics(value) {
|
|
|
264
276
|
// returns `metrics` itself.
|
|
265
277
|
export function recordMetrics(
|
|
266
278
|
metrics,
|
|
267
|
-
{
|
|
279
|
+
{
|
|
280
|
+
classifier = /** @type {string | null} */ (null),
|
|
281
|
+
adviceMs = /** @type {number | null} */ (null),
|
|
282
|
+
downMove = /** @type {string | null} */ (null),
|
|
283
|
+
unpriced = {},
|
|
284
|
+
now = /** @type {number | null} */ (null),
|
|
285
|
+
},
|
|
268
286
|
) {
|
|
269
287
|
const next = {
|
|
270
288
|
version: 1,
|
|
@@ -280,9 +298,10 @@ export function recordMetrics(
|
|
|
280
298
|
next.unpriced[cause] += n;
|
|
281
299
|
counted = true;
|
|
282
300
|
}
|
|
283
|
-
const known = Object.hasOwn(next.latency, classifier);
|
|
301
|
+
const known = typeof classifier === 'string' && Object.hasOwn(next.latency, classifier);
|
|
284
302
|
if (
|
|
285
303
|
typeof classifier === 'string' &&
|
|
304
|
+
typeof adviceMs === 'number' &&
|
|
286
305
|
Number.isFinite(adviceMs) &&
|
|
287
306
|
adviceMs >= 0 &&
|
|
288
307
|
(known || Object.keys(next.latency).length < LATENCY_CLASSIFIERS)
|
package/lib/activity.mjs
CHANGED
|
@@ -46,7 +46,9 @@ export function routingActivity(config, advice) {
|
|
|
46
46
|
|
|
47
47
|
const acceptRoutingActivity = (config, advice) => {
|
|
48
48
|
const signal = routingActivity(config, advice);
|
|
49
|
-
return ACTIVITIES.includes(signal
|
|
49
|
+
return signal !== null && ACTIVITIES.includes(signal.choice) && signal.mass >= config.policy.activityMass
|
|
50
|
+
? signal.choice
|
|
51
|
+
: null;
|
|
50
52
|
};
|
|
51
53
|
|
|
52
54
|
// 1 when route `a` is stronger than `b`, -1 when weaker, 0 when equal in declared strength, null when unordered.
|
|
@@ -83,10 +85,10 @@ export function chooseActivity(config, advice, incumbent, sentEffort, facts = {}
|
|
|
83
85
|
if (!sameTaskOf(config, advice, facts)) return nominate(acceptRoutingActivity(config, advice));
|
|
84
86
|
const signal = routingActivity(config, advice);
|
|
85
87
|
const label = signal?.choice;
|
|
86
|
-
if (!ACTIVITIES.includes(label)) return stay;
|
|
88
|
+
if (!signal || !ACTIVITIES.includes(label)) return stay;
|
|
87
89
|
const candidate = resolveRoute(config, incumbent.tier, label);
|
|
88
90
|
const order = compareRoutes(config, candidate, incumbent.route, sentEffort);
|
|
89
|
-
if (order > 0) return nominate(label);
|
|
91
|
+
if (order !== null && order > 0) return nominate(label);
|
|
90
92
|
// An explicitly declared ops work floor may be nominated without inventing a physical-model ranking.
|
|
91
93
|
// The lateral confidence/cache/hold/cash gates still decide; inherited generic cells get no exception.
|
|
92
94
|
// Equal requests can adopt the semantic work preference without a model/effort switch. Higher tiers may differ.
|
|
@@ -94,7 +96,7 @@ export function chooseActivity(config, advice, incumbent, sentEffort, facts = {}
|
|
|
94
96
|
const declared = config.configuredActivities ?? config.activities;
|
|
95
97
|
if (order === null && label === floor && declared[label]?.[incumbent.tier]) return nominate(label);
|
|
96
98
|
const mass = signal.mass;
|
|
97
|
-
if (order < 0 && facts.downAllowed && mass >= config.policy.downgradeMass) return nominate(label);
|
|
99
|
+
if (order !== null && order < 0 && facts.downAllowed && mass >= config.policy.downgradeMass) return nominate(label);
|
|
98
100
|
return stay;
|
|
99
101
|
}
|
|
100
102
|
|
|
@@ -109,7 +111,7 @@ export function chooseActivity(config, advice, incumbent, sentEffort, facts = {}
|
|
|
109
111
|
// { move, reason, estimate }.
|
|
110
112
|
export function lateralMove({ config, from, to, mass, hold, sameTask = false, facts, now, costs }) {
|
|
111
113
|
const order = compareRoutes(config, to, from, facts.effort);
|
|
112
|
-
if (hold && !(order > 0)) return { move: false, reason: 'hold', estimate: null };
|
|
114
|
+
if (hold && !(order !== null && order > 0)) return { move: false, reason: 'hold', estimate: null };
|
|
113
115
|
const p = config.policy;
|
|
114
116
|
let estimate;
|
|
115
117
|
if (order !== -1 && sameTask && !facts.downAllowed && cheaperPerTurn(routeSpec(config, to), routeSpec(config, from)))
|
|
@@ -0,0 +1,414 @@
|
|
|
1
|
+
// Pure demand → target → move engine. No controller or host calls; table routing does not import this module.
|
|
2
|
+
import { TIERS } from './config.mjs';
|
|
3
|
+
import * as costs from './cost.mjs';
|
|
4
|
+
import { CONTEXT_FILL, sameTaskOf } from './policy.mjs';
|
|
5
|
+
import { canonicalModel } from './providers.mjs';
|
|
6
|
+
import { isModelAllowed } from './route.mjs';
|
|
7
|
+
|
|
8
|
+
const MODES = { cost: -0.5, balanced: 0, quality: 0.5 };
|
|
9
|
+
const clamp = (n) => Math.max(0, Math.min(3, n));
|
|
10
|
+
const sameRoute = (a, b) => a?.model === b?.model && a?.effort === b?.effort;
|
|
11
|
+
const samePhysical = (a, b) =>
|
|
12
|
+
a.requestKey && b.requestKey ? a.requestKey === b.requestKey : sameRoute(a.route, b.route);
|
|
13
|
+
const validLevel = (n) => Number.isFinite(n) && n >= 0 && n <= 3 && Number.isInteger(n * 2);
|
|
14
|
+
|
|
15
|
+
export function initialAutoState({ demand = 2, routedDemand = demand, cause = 'classifier' } = {}) {
|
|
16
|
+
if (!Number.isInteger(demand) || !validLevel(demand) || !validLevel(routedDemand))
|
|
17
|
+
throw new RangeError('demand must be an integer 0..3; routedDemand must be a half-step 0..3');
|
|
18
|
+
return {
|
|
19
|
+
demand,
|
|
20
|
+
routedDemand,
|
|
21
|
+
routeCause: cause,
|
|
22
|
+
demandCause: 'classifier',
|
|
23
|
+
turn: 0,
|
|
24
|
+
votes: [],
|
|
25
|
+
holdUntilTurn: 0,
|
|
26
|
+
escalatedSignature: null,
|
|
27
|
+
escalatedIndex: null,
|
|
28
|
+
headroom: false,
|
|
29
|
+
};
|
|
30
|
+
}
|
|
31
|
+
|
|
32
|
+
const massAbove = (p, level) => TIERS.reduce((sum, tier, i) => sum + (i > level ? (p?.[tier] ?? 0) : 0), 0);
|
|
33
|
+
const massAtOrBelow = (p, level) => TIERS.reduce((sum, tier, i) => sum + (i <= level ? (p?.[tier] ?? 0) : 0), 0);
|
|
34
|
+
function trailing(votes, predicate) {
|
|
35
|
+
let count = 0;
|
|
36
|
+
for (let i = votes.length - 1; i >= 0 && predicate(votes[i]); i -= 1) count += 1;
|
|
37
|
+
return count;
|
|
38
|
+
}
|
|
39
|
+
|
|
40
|
+
// Only vote/hold policy fields are read here: no route, cache, price, checkpoint or dwell evidence.
|
|
41
|
+
// Raw demand is integer; the accepted bounded execute discount never accumulates or discounts a pin/escalation.
|
|
42
|
+
export function advanceDemand({
|
|
43
|
+
config,
|
|
44
|
+
state,
|
|
45
|
+
advice = /** @type {{ choice: string, probabilities: Record<string, number> } | null} */ (null),
|
|
46
|
+
facts,
|
|
47
|
+
pin = null,
|
|
48
|
+
boundedExecute = false,
|
|
49
|
+
}) {
|
|
50
|
+
const pinned = pin === null ? null : typeof pin === 'string' ? TIERS.indexOf(pin) : pin;
|
|
51
|
+
if (pinned !== null && (!Number.isInteger(pinned) || !validLevel(pinned)))
|
|
52
|
+
throw new RangeError('pin must name a tier or integer demand 0..3');
|
|
53
|
+
if (pinned !== null)
|
|
54
|
+
return { raw: pinned, level: pinned, reason: 'pinned', headroom: false, escalated: false, state };
|
|
55
|
+
const next = { ...state, turn: state.turn + 1, votes: [...state.votes] };
|
|
56
|
+
let reason = 'same-demand';
|
|
57
|
+
let escalated = false;
|
|
58
|
+
const failure = facts.failure;
|
|
59
|
+
const freshFailure =
|
|
60
|
+
failure && (failure.signature !== next.escalatedSignature || (failure.index ?? null) !== next.escalatedIndex);
|
|
61
|
+
if (freshFailure) {
|
|
62
|
+
next.escalatedSignature = failure.signature;
|
|
63
|
+
next.escalatedIndex = failure.index ?? null;
|
|
64
|
+
next.headroom = next.demand === 3;
|
|
65
|
+
next.demand = Math.min(3, next.demand + 1);
|
|
66
|
+
next.demandCause = 'escalation';
|
|
67
|
+
next.holdUntilTurn = next.turn + config.policy.escalationHoldTurns;
|
|
68
|
+
next.votes = [];
|
|
69
|
+
reason = 'escalation';
|
|
70
|
+
escalated = true;
|
|
71
|
+
} else if (next.turn <= next.holdUntilTurn) {
|
|
72
|
+
reason = 'hold';
|
|
73
|
+
} else if (!advice || !TIERS.includes(advice.choice)) {
|
|
74
|
+
reason = advice ? 'uncertain' : 'no-advice';
|
|
75
|
+
} else {
|
|
76
|
+
const choice = TIERS.indexOf(advice.choice);
|
|
77
|
+
next.votes = [...next.votes, choice].slice(-Math.max(config.policy.upgradeVotes, config.policy.downgradeVotes));
|
|
78
|
+
const fresh = facts.historyMeasured === false;
|
|
79
|
+
if (choice > next.demand) {
|
|
80
|
+
const mass = massAbove(advice.probabilities, next.demand);
|
|
81
|
+
const jump = choice - next.demand >= 2 && mass >= config.policy.jumpConfidence;
|
|
82
|
+
const votes = fresh ? 1 : config.policy.upgradeVotes;
|
|
83
|
+
if (jump || (trailing(next.votes, (v) => v > next.demand) >= votes && mass >= config.policy.upgradeBase)) {
|
|
84
|
+
next.demand = choice;
|
|
85
|
+
next.demandCause = 'classifier';
|
|
86
|
+
next.headroom = false;
|
|
87
|
+
reason = jump ? 'jump' : 'upgrade';
|
|
88
|
+
} else reason = 'upgrade-pending';
|
|
89
|
+
} else if (choice < next.demand) {
|
|
90
|
+
reason = 'downgrade-pending';
|
|
91
|
+
for (let target = choice; target < next.demand; target += 1) {
|
|
92
|
+
const votes = fresh ? 1 : config.policy.downgradeVotes;
|
|
93
|
+
if (
|
|
94
|
+
massAtOrBelow(advice.probabilities, target) < config.policy.downgradeMass ||
|
|
95
|
+
trailing(next.votes, (v) => v <= target) < votes
|
|
96
|
+
)
|
|
97
|
+
continue;
|
|
98
|
+
next.demand = target;
|
|
99
|
+
next.demandCause = 'classifier';
|
|
100
|
+
next.headroom = false;
|
|
101
|
+
reason = 'downgrade';
|
|
102
|
+
break;
|
|
103
|
+
}
|
|
104
|
+
}
|
|
105
|
+
}
|
|
106
|
+
const protectedDemand = escalated || next.turn <= next.holdUntilTurn || next.headroom;
|
|
107
|
+
const discount = boundedExecute && !protectedDemand ? 0.5 : 0;
|
|
108
|
+
return {
|
|
109
|
+
raw: next.demand,
|
|
110
|
+
level: clamp(next.demand - discount),
|
|
111
|
+
reason,
|
|
112
|
+
headroom: next.headroom,
|
|
113
|
+
escalated,
|
|
114
|
+
state: next,
|
|
115
|
+
};
|
|
116
|
+
}
|
|
117
|
+
|
|
118
|
+
function effectiveIncumbent(config, incumbent, facts) {
|
|
119
|
+
const model = config.models[incumbent.model];
|
|
120
|
+
if (!model) return incumbent;
|
|
121
|
+
// An unresolved native null effort is legal but unknown. Never silently clamp an unsupported explicit effort.
|
|
122
|
+
if (incumbent.effort == null && (model.efforts.includes(facts.effort) || Number.isFinite(facts.effort)))
|
|
123
|
+
return { ...incumbent, effort: facts.effort };
|
|
124
|
+
return { ...incumbent, effort: incumbent.effort ?? null };
|
|
125
|
+
}
|
|
126
|
+
|
|
127
|
+
// cost.routeEffort represents native numeric effort through sentEffort, not the configured effort slot.
|
|
128
|
+
const pricedRoute = (route) => (typeof route.effort === 'number' ? { ...route, effort: null } : route);
|
|
129
|
+
const pricedFacts = (route, facts) => (typeof route.effort === 'number' ? { ...facts, effort: route.effort } : facts);
|
|
130
|
+
|
|
131
|
+
function capabilityOf(model, route) {
|
|
132
|
+
const key = route.effort === null && model.efforts.length === 0 ? 'default' : route.effort;
|
|
133
|
+
const value = key === null ? undefined : model.capability?.[key];
|
|
134
|
+
return validLevel(value) ? value : null;
|
|
135
|
+
}
|
|
136
|
+
|
|
137
|
+
// Only the actual supported effort can establish accepted startup demand; unknown capability keeps the baseline.
|
|
138
|
+
export function initialIncumbentState({ config, incumbent, facts }) {
|
|
139
|
+
const demand = TIERS.indexOf(config.baselineTier);
|
|
140
|
+
const current = effectiveIncumbent(config, incumbent, facts);
|
|
141
|
+
const model = config.models[current.model];
|
|
142
|
+
const capability =
|
|
143
|
+
model && (current.effort === null || model.efforts.includes(current.effort)) ? capabilityOf(model, current) : null;
|
|
144
|
+
return initialAutoState({ demand, routedDemand: capability ?? demand });
|
|
145
|
+
}
|
|
146
|
+
|
|
147
|
+
// Each supported pair is assessed independently before any fallback. The incumbent is also assessed, even if its
|
|
148
|
+
// model/effort left the catalog; an unresolved native effort can only be retained, never nominated as a new candidate.
|
|
149
|
+
export function assessCandidates({
|
|
150
|
+
config,
|
|
151
|
+
facts,
|
|
152
|
+
now,
|
|
153
|
+
incumbent,
|
|
154
|
+
contextKnown = Number.isFinite(facts.contextTokens),
|
|
155
|
+
availableModels,
|
|
156
|
+
nativeModel,
|
|
157
|
+
}) {
|
|
158
|
+
const current = effectiveIncumbent(config, incumbent, facts);
|
|
159
|
+
const currentSpec = config.models[current.model];
|
|
160
|
+
const routes = Object.entries(config.models).flatMap(([model, spec]) =>
|
|
161
|
+
(spec.efforts.length ? spec.efforts : [null]).map((effort) => ({ model, effort })),
|
|
162
|
+
);
|
|
163
|
+
const listed = routes.some((route) => sameRoute(route, current));
|
|
164
|
+
if (!listed) routes.push(current);
|
|
165
|
+
const tokens = costs.nextContextTokens(facts);
|
|
166
|
+
return routes.map((route, index) => {
|
|
167
|
+
const model = config.models[route.model];
|
|
168
|
+
const reasons = [];
|
|
169
|
+
const isIncumbent = sameRoute(route, current);
|
|
170
|
+
const selectable = index < routes.length - (listed ? 0 : 1);
|
|
171
|
+
if (!model)
|
|
172
|
+
return {
|
|
173
|
+
route,
|
|
174
|
+
capability: null,
|
|
175
|
+
eligible: false,
|
|
176
|
+
reasons: ['model-missing'],
|
|
177
|
+
incumbent: isIncumbent,
|
|
178
|
+
selectable,
|
|
179
|
+
cache: 'unknown',
|
|
180
|
+
coldWriteUsd: null,
|
|
181
|
+
estimate: null,
|
|
182
|
+
};
|
|
183
|
+
if (
|
|
184
|
+
route.effort !== null &&
|
|
185
|
+
!model.efforts.includes(route.effort) &&
|
|
186
|
+
!(isIncumbent && Number.isFinite(route.effort))
|
|
187
|
+
)
|
|
188
|
+
reasons.push('effort-unsupported');
|
|
189
|
+
if (
|
|
190
|
+
!isModelAllowed(model.id, availableModels, nativeModel) ||
|
|
191
|
+
(facts.ineligible ?? []).some((id) => canonicalModel(id) === canonicalModel(model.id))
|
|
192
|
+
)
|
|
193
|
+
reasons.push('unavailable');
|
|
194
|
+
// A missing fresh estimate does not erase the observed transcript's token lower bound.
|
|
195
|
+
if (tokens > model.contextWindow * CONTEXT_FILL) reasons.push('context-full');
|
|
196
|
+
if (
|
|
197
|
+
(!contextKnown || facts.historyMeasured === false) &&
|
|
198
|
+
currentSpec &&
|
|
199
|
+
model.contextWindow < currentSpec.contextWindow
|
|
200
|
+
)
|
|
201
|
+
reasons.push('context-unknown');
|
|
202
|
+
if (facts.hasImages && model.imageInput === false) reasons.push('images');
|
|
203
|
+
const pricingFacts = pricedFacts(route, facts);
|
|
204
|
+
const pricingRoute = pricedRoute(route);
|
|
205
|
+
const cache = costs.cacheState(
|
|
206
|
+
facts.models[costs.routeCacheKey(config, pricingRoute, pricingFacts.effort)],
|
|
207
|
+
now,
|
|
208
|
+
config.cache,
|
|
209
|
+
);
|
|
210
|
+
const coldWriteUsd = costs.coldWriteUsd(config, route.model, tokens, now);
|
|
211
|
+
if (model.billing === 'credits' && cache !== 'fresh' && coldWriteUsd > config.policy.cashCapUsd)
|
|
212
|
+
reasons.push('cash-cap');
|
|
213
|
+
const input = costs.inputBounds(config, pricingRoute, tokens, pricingFacts, now);
|
|
214
|
+
const output = ((costs.ratesAt(model, tokens, now).output ?? 0) * (facts.lastRequest?.outputTokens ?? 0)) / 1e6;
|
|
215
|
+
return {
|
|
216
|
+
route,
|
|
217
|
+
requestKey: JSON.stringify([canonicalModel(model.id), model.efforts.length ? route.effort : null]),
|
|
218
|
+
capability: capabilityOf(model, route),
|
|
219
|
+
eligible: reasons.length === 0,
|
|
220
|
+
reasons,
|
|
221
|
+
incumbent: isIncumbent,
|
|
222
|
+
selectable,
|
|
223
|
+
cache,
|
|
224
|
+
coldWriteUsd,
|
|
225
|
+
estimate: { minUsd: input.min + output, maxUsd: input.max + output },
|
|
226
|
+
};
|
|
227
|
+
});
|
|
228
|
+
}
|
|
229
|
+
|
|
230
|
+
// Uniform ordering is essential: mode changes only the required capability, never the incumbent tie preference.
|
|
231
|
+
export function selectTarget({ candidates, demand, mode = 'balanced', headroom = false, escalation = false }) {
|
|
232
|
+
if (!validLevel(demand)) throw new RangeError('demand must be a half-step 0..3');
|
|
233
|
+
if (!Object.hasOwn(MODES, mode)) throw new RangeError('unknown automatic routing mode');
|
|
234
|
+
const requirement = clamp(demand + MODES[mode]);
|
|
235
|
+
const eligible = candidates.filter(
|
|
236
|
+
(candidate) => candidate.eligible && (candidate.selectable || candidate.incumbent),
|
|
237
|
+
);
|
|
238
|
+
const current = candidates.find((candidate) => candidate.incumbent);
|
|
239
|
+
const escalating = (escalation || headroom) && current?.eligible;
|
|
240
|
+
const choices = escalating ? eligible.filter((candidate) => !samePhysical(candidate, current)) : eligible;
|
|
241
|
+
const declared = choices.filter(
|
|
242
|
+
(candidate) =>
|
|
243
|
+
candidate.capability !== null &&
|
|
244
|
+
(!escalating ||
|
|
245
|
+
(current.capability === null
|
|
246
|
+
? candidate.capability >= requirement
|
|
247
|
+
: candidate.capability > current.capability)),
|
|
248
|
+
);
|
|
249
|
+
let pool = declared.filter((candidate) => candidate.capability >= requirement);
|
|
250
|
+
let outcome = 'meets-demand';
|
|
251
|
+
let reason = escalating ? 'escalation' : null;
|
|
252
|
+
if (!pool.length) {
|
|
253
|
+
if (declared.length) {
|
|
254
|
+
const highest = Math.max(...declared.map((candidate) => candidate.capability));
|
|
255
|
+
pool = declared.filter((candidate) => candidate.capability === highest);
|
|
256
|
+
outcome = highest >= requirement ? 'meets-demand' : 'declared-below-demand';
|
|
257
|
+
} else {
|
|
258
|
+
pool = choices.filter((candidate) => candidate.capability === null);
|
|
259
|
+
outcome = 'unknown-only';
|
|
260
|
+
if (escalating) reason = pool.length ? 'escalation-unknown' : 'escalation-exhausted';
|
|
261
|
+
}
|
|
262
|
+
}
|
|
263
|
+
pool = [...pool].sort(
|
|
264
|
+
(a, b) =>
|
|
265
|
+
a.estimate.maxUsd - b.estimate.maxUsd ||
|
|
266
|
+
Number(b.incumbent) - Number(a.incumbent) ||
|
|
267
|
+
(a.capability ?? -1) - (b.capability ?? -1),
|
|
268
|
+
);
|
|
269
|
+
const winner = pool[0] ?? (current?.eligible ? current : null);
|
|
270
|
+
if (!winner)
|
|
271
|
+
return {
|
|
272
|
+
outcome: 'no-route',
|
|
273
|
+
route: null,
|
|
274
|
+
capability: null,
|
|
275
|
+
requirement,
|
|
276
|
+
estimate: null,
|
|
277
|
+
reason: null,
|
|
278
|
+
headroom: false,
|
|
279
|
+
};
|
|
280
|
+
if (!pool.length) outcome = 'incumbent';
|
|
281
|
+
return {
|
|
282
|
+
outcome,
|
|
283
|
+
route: winner.route,
|
|
284
|
+
capability: winner.capability,
|
|
285
|
+
requirement,
|
|
286
|
+
estimate: winner.estimate,
|
|
287
|
+
reason,
|
|
288
|
+
headroom: reason === 'escalation-exhausted',
|
|
289
|
+
};
|
|
290
|
+
}
|
|
291
|
+
|
|
292
|
+
function bar(base, slope, tax, pivot) {
|
|
293
|
+
return base + slope * (tax / (tax + pivot));
|
|
294
|
+
}
|
|
295
|
+
|
|
296
|
+
// Demand votes are NOT read here. Pending moves compare against the demand accepted by the incumbent.
|
|
297
|
+
export function decideMove({
|
|
298
|
+
config,
|
|
299
|
+
state,
|
|
300
|
+
demandResult,
|
|
301
|
+
target,
|
|
302
|
+
candidates,
|
|
303
|
+
advice = /** @type {{ choice: string, probabilities: Record<string, number> } | null} */ (null),
|
|
304
|
+
facts,
|
|
305
|
+
now,
|
|
306
|
+
changeCause = /** @type {string | null} */ (null),
|
|
307
|
+
startup = false,
|
|
308
|
+
incumbentOrigin = null,
|
|
309
|
+
}) {
|
|
310
|
+
const current = candidates.find((candidate) => candidate.incumbent);
|
|
311
|
+
const proposed = candidates.find((candidate) => sameRoute(candidate.route, target.route));
|
|
312
|
+
const stay = (reason, evidence = /** @type {object | null} */ (null)) => ({
|
|
313
|
+
move: false,
|
|
314
|
+
route: current?.eligible ? current.route : null,
|
|
315
|
+
reason,
|
|
316
|
+
evidence,
|
|
317
|
+
estimate: target.estimate,
|
|
318
|
+
// The selected physical request can accept new demand without a switch or new route provenance.
|
|
319
|
+
state: reason === 'same-route' ? { ...state, routedDemand: demandResult.level } : state,
|
|
320
|
+
});
|
|
321
|
+
const move = (reason, cause, evidence = /** @type {object | null} */ (null)) => ({
|
|
322
|
+
move: true,
|
|
323
|
+
route: target.route,
|
|
324
|
+
reason,
|
|
325
|
+
evidence,
|
|
326
|
+
estimate: target.estimate,
|
|
327
|
+
state: { ...state, routedDemand: demandResult.level, routeCause: cause },
|
|
328
|
+
});
|
|
329
|
+
if (!target.route || !proposed?.eligible) return stay('no-route');
|
|
330
|
+
if (incumbentOrigin === 'external-fallback')
|
|
331
|
+
return current && samePhysical(current, proposed) ? stay('same-route') : move('reentry', 'reentry');
|
|
332
|
+
if (!current?.eligible) return move('forced', 'forced');
|
|
333
|
+
if (target.reason === 'escalation-exhausted') return stay('escalation-exhausted');
|
|
334
|
+
if (samePhysical(current, proposed)) return stay('same-route');
|
|
335
|
+
if (
|
|
336
|
+
demandResult.escalated ||
|
|
337
|
+
demandResult.headroom ||
|
|
338
|
+
target.reason === 'escalation' ||
|
|
339
|
+
target.reason === 'escalation-unknown'
|
|
340
|
+
)
|
|
341
|
+
return move(target.reason === 'escalation-unknown' ? 'escalation-unknown' : 'escalation', 'escalation');
|
|
342
|
+
const p = config.policy;
|
|
343
|
+
const from = pricedRoute(current.route);
|
|
344
|
+
const to = pricedRoute(target.route);
|
|
345
|
+
const pricingFacts = pricedFacts(current.route, facts);
|
|
346
|
+
const stronger =
|
|
347
|
+
target.capability !== null && (current.capability === null || target.capability > current.capability);
|
|
348
|
+
const upgrade = (mass, reason, cause) => {
|
|
349
|
+
const taxUsd = Math.max(0, costs.switchingTaxUsd(config, to, from, pricingFacts, now));
|
|
350
|
+
const threshold = bar(p.upgradeBase, p.upgradeSlope, taxUsd, p.upgradePivotUsd);
|
|
351
|
+
const evidence = { mass, threshold, taxUsd };
|
|
352
|
+
return mass >= threshold ? move(reason, cause, evidence) : stay('upgrade-pending', evidence);
|
|
353
|
+
};
|
|
354
|
+
// Startup fits a native route the user never selected, before classifier move evidence; demand votes are unchanged.
|
|
355
|
+
if (
|
|
356
|
+
startup &&
|
|
357
|
+
current.capability !== null &&
|
|
358
|
+
current.capability < target.requirement &&
|
|
359
|
+
target.capability !== null &&
|
|
360
|
+
target.capability >= target.requirement
|
|
361
|
+
)
|
|
362
|
+
return upgrade(1, 'startup', 'startup');
|
|
363
|
+
if (demandResult.level > state.routedDemand)
|
|
364
|
+
return upgrade(massAbove(advice?.probabilities, state.routedDemand), 'upgrade', 'classifier');
|
|
365
|
+
if (demandResult.level < state.routedDemand) {
|
|
366
|
+
const taxUsd = costs.downgradeTaxUsd(config, to, from, pricingFacts, now, p.downgradeHorizonTurns);
|
|
367
|
+
const threshold = bar(p.downgradeMass, p.downgradeSlope, taxUsd, p.downgradePivotUsd);
|
|
368
|
+
const mass = massAtOrBelow(advice?.probabilities, demandResult.level);
|
|
369
|
+
const evidence = { mass, threshold, taxUsd };
|
|
370
|
+
if (mass < threshold) return stay('downgrade-pending', evidence);
|
|
371
|
+
if (!facts.dwellAllowed) return stay('dwell-held', evidence);
|
|
372
|
+
if (sameTaskOf(config, advice, facts) && !facts.downAllowed) return stay('downgrade-held', evidence);
|
|
373
|
+
return move('downgrade', 'classifier', evidence);
|
|
374
|
+
}
|
|
375
|
+
if (stronger || (target.capability === null && current.capability !== null)) {
|
|
376
|
+
if (changeCause !== 'mode' && changeCause !== 'catalog') return stay('no-evidence');
|
|
377
|
+
return upgrade(1, 'explicit-up', changeCause);
|
|
378
|
+
}
|
|
379
|
+
if (target.estimate.maxUsd < current.estimate.maxUsd) {
|
|
380
|
+
if (state.turn <= state.holdUntilTurn) return stay('hold');
|
|
381
|
+
const taxUsd = costs.downgradeTaxUsd(config, to, from, pricingFacts, now, p.downgradeHorizonTurns);
|
|
382
|
+
const evidence = { taxUsd };
|
|
383
|
+
if (!facts.dwellAllowed) return stay('dwell-held', evidence);
|
|
384
|
+
if (sameTaskOf(config, advice, facts) && !facts.downAllowed) return stay('downgrade-held', evidence);
|
|
385
|
+
if (taxUsd > 0 && facts.historyMeasured !== false) return stay('economics-pending', evidence);
|
|
386
|
+
return move('cheaper', changeCause ?? 'classifier', evidence);
|
|
387
|
+
}
|
|
388
|
+
return stay('no-evidence');
|
|
389
|
+
}
|
|
390
|
+
|
|
391
|
+
// Shadow uses demand/filter/target helpers only and retains demand.state (not proposal route history). Stateful
|
|
392
|
+
// replay/auto consumes accepted same-route demand too, without counting a move. Pins are one-turn overrides;
|
|
393
|
+
// the caller restores both pre-pin incumbent and state afterwards. This function never performs a physical move.
|
|
394
|
+
export function proposeAutoRoute(input) {
|
|
395
|
+
const state = input.state ?? initialIncumbentState(input);
|
|
396
|
+
const demand = advanceDemand({ ...input, state });
|
|
397
|
+
const candidates = assessCandidates(input);
|
|
398
|
+
const pinned = input.pin != null;
|
|
399
|
+
const target = selectTarget({
|
|
400
|
+
candidates,
|
|
401
|
+
demand: demand.level,
|
|
402
|
+
mode: pinned ? 'balanced' : input.mode,
|
|
403
|
+
headroom: demand.headroom,
|
|
404
|
+
escalation: demand.escalated,
|
|
405
|
+
});
|
|
406
|
+
if (!pinned && (demand.escalated || demand.headroom)) {
|
|
407
|
+
demand.headroom = target.headroom;
|
|
408
|
+
demand.state = { ...demand.state, headroom: target.headroom };
|
|
409
|
+
}
|
|
410
|
+
const move = pinned
|
|
411
|
+
? { move: false, route: target.route, reason: 'pinned', evidence: null, estimate: target.estimate, state }
|
|
412
|
+
: decideMove({ ...input, state: demand.state, demandResult: demand, target, candidates });
|
|
413
|
+
return { state: move.state, demand, candidates, target, move };
|
|
414
|
+
}
|