@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/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
|
|
41
|
-
if (
|
|
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(
|
|
46
|
-
return gated.blocked ? gatedResult(gated, incumbent, next) : result(
|
|
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
|
+
}
|