@alexeiled/claude-router 0.8.0 → 1.1.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 (48) hide show
  1. package/.claude-plugin/plugin.json +11 -7
  2. package/CHANGELOG.md +43 -0
  3. package/README.md +55 -98
  4. package/docs/architecture.md +55 -419
  5. package/docs/configuration.md +88 -182
  6. package/docs/evaluation.md +62 -81
  7. package/docs/native-router.md +80 -0
  8. package/docs/router-band.svg +119 -0
  9. package/docs/router-pane-now.svg +85 -0
  10. package/docs/router-pane-tiers.svg +62 -0
  11. package/docs/user-guide.md +127 -172
  12. package/hooks/hooks.json +1 -26
  13. package/hooks/native-router.mjs +701 -0
  14. package/lib/config.mjs +97 -63
  15. package/lib/{facts.mjs → facts-pure.mjs} +2 -23
  16. package/lib/{jev.mjs → jev-contract.mjs} +17 -38
  17. package/lib/native-band.mjs +206 -0
  18. package/lib/native-cost.mjs +88 -0
  19. package/lib/native-display.mjs +122 -0
  20. package/lib/native-jev.mjs +125 -0
  21. package/lib/native-panel.mjs +492 -0
  22. package/lib/native-router.mjs +221 -0
  23. package/lib/policy.mjs +17 -21
  24. package/package.json +10 -8
  25. package/scripts/migrate-config.mjs +57 -0
  26. package/types/index.d.ts +112 -0
  27. package/lib/cost.mjs +0 -93
  28. package/lib/gateway.mjs +0 -221
  29. package/lib/idle.mjs +0 -41
  30. package/lib/rewrite.mjs +0 -130
  31. package/lib/router.mjs +0 -276
  32. package/lib/runtime.mjs +0 -78
  33. package/lib/sse.mjs +0 -57
  34. package/lib/status.mjs +0 -152
  35. package/lib/store.mjs +0 -76
  36. package/scripts/ensure-gateway.mjs +0 -143
  37. package/scripts/gateway.mjs +0 -81
  38. package/scripts/git-hooks/pre-commit +0 -41
  39. package/scripts/git-hooks/pre-push +0 -34
  40. package/scripts/status.mjs +0 -20
  41. package/scripts/statusline.mjs +0 -45
  42. package/scripts/transcript-models.sh +0 -4
  43. package/skills/high/SKILL.md +0 -9
  44. package/skills/low/SKILL.md +0 -7
  45. package/skills/medium/SKILL.md +0 -8
  46. package/skills/micro/SKILL.md +0 -7
  47. package/skills/setup/SKILL.md +0 -31
  48. package/skills/status/SKILL.md +0 -12
@@ -0,0 +1,492 @@
1
+ import { effectiveRoutes, sameRoute, TIERS, tuningOf } from './config.mjs';
2
+ import {
3
+ bar,
4
+ CLASSIFIER,
5
+ CLASSIFIER_ERRORS,
6
+ formatTokens,
7
+ GATEWAY_CLEANUP,
8
+ GATEWAY_SETTINGS,
9
+ REASONS,
10
+ sparkline,
11
+ usageMetrics,
12
+ } from './native-display.mjs';
13
+
14
+ export const TABS = [
15
+ ['now', '1', 'Now'],
16
+ ['tiers', '2', 'Tiers'],
17
+ ['tuning', '3', 'Tuning'],
18
+ ['usage', '4', 'Usage'],
19
+ ];
20
+ export const TUNING_CHOICES = {
21
+ timeoutMs: [500, 1000, 1500, 3000],
22
+ downgradeVotes: [1, 2, 3],
23
+ horizon: [1, 3, 5, 10],
24
+ cashCapUsd: [0.5, 1, 2, 5],
25
+ };
26
+ // Cost order, cheapest first, so the colors read as a scale. Hex values: every surface draws them.
27
+ export const TIER_COLOR = { micro: '#5fd7af', low: '#5f9fe0', medium: '#d7af5f', high: '#e0708a' };
28
+ const LADDER = [...TIERS].reverse();
29
+ const SESSION_EFFORT = 'session';
30
+
31
+ export function modelName(id) {
32
+ if (!id) return 'no response yet';
33
+ return id
34
+ .replace(/^claude-/, '')
35
+ .replace(/-([0-9])-([0-9])(-\d{8})?$/, ' $1.$2')
36
+ .replace(/^./, (c) => c.toUpperCase());
37
+ }
38
+
39
+ export function routeName(config, route) {
40
+ const model = config.models[route.model];
41
+ return `${modelName(model.id)}${model.efforts.length ? ` · ${route.effort ?? SESSION_EFFORT}` : ''}`;
42
+ }
43
+
44
+ // The draft the Tiers tab edits: the saved routes until the person changes one.
45
+ export function routeDraftOf(config, view) {
46
+ if (view.routeDraft) return view.routeDraft;
47
+ const base = structuredClone({ routes: config.routes, baselineTier: config.baselineTier });
48
+ return { ...structuredClone(base), base };
49
+ }
50
+
51
+ const dollars = (value) => (Number.isFinite(value) ? `$${value.toFixed(3)}` : 'not reported');
52
+ const difference = (value) => `${value < 0 ? '−' : '+'}$${Math.abs(value).toFixed(3)}`;
53
+ const percent = (value) => `${Math.round(value * 100)}%`;
54
+ const windowSize = (tokens) => (tokens >= 1e6 ? `${tokens / 1e6}M` : `${Math.round(tokens / 1e3)}K`);
55
+ const contextSuffix = (metrics) =>
56
+ Number.isFinite(metrics.nextContext)
57
+ ? `~${formatTokens(metrics.nextContext)} / ${formatTokens(metrics.window)}`
58
+ : 'no reading yet';
59
+
60
+ function kit({ Box, Text, Button, Select }) {
61
+ const text = (children, style = {}) => Text({ ...style, children });
62
+ return {
63
+ Box,
64
+ Button,
65
+ Select,
66
+ text,
67
+ dim: (children) => text(children, { dimColor: true }),
68
+ head: (children) => text(children, { bold: true, color: 'cyan' }),
69
+ tier: (tier, children = tier) => text(children, { bold: true, color: TIER_COLOR[tier] }),
70
+ // One row of mixed parts; strings become plain Text, nulls are dropped.
71
+ line: (...parts) =>
72
+ Box({
73
+ children: parts
74
+ .filter((part) => part !== null && part !== '')
75
+ .map((p) => (typeof p === 'string' ? text(p) : p)),
76
+ }),
77
+ // A fixed-width column, so controls of different widths still line up.
78
+ cell: (width, part) => Box({ width, children: [typeof part === 'string' ? text(part) : part] }),
79
+ gauge: (name, value, suffix) =>
80
+ text(`${name}${value.text}${value.percent === null ? '' : ` ${String(value.percent).padStart(3)}%`} ${suffix}`, {
81
+ color: value.color,
82
+ }),
83
+ };
84
+ }
85
+
86
+ export function renderPanel(
87
+ elements,
88
+ config,
89
+ view,
90
+ usage,
91
+ actions,
92
+ { modelOptions = Object.keys(config.models) } = {},
93
+ ) {
94
+ const ui = kit(elements);
95
+ const tab = TABS.some(([id]) => id === view.tab) ? view.tab : 'now';
96
+ const body = { now: nowTab, tiers: tiersTab, tuning: tuningTab, usage: usageTab }[tab];
97
+ return ui.Box({
98
+ flexDirection: 'column',
99
+ children: [
100
+ ...header(ui, view, actions),
101
+ ...body(ui, config, view, usage, actions, modelOptions),
102
+ ...(view.help ? helpLines(ui) : []),
103
+ view.notice ? ui.text(view.notice, { color: 'yellow' }) : null,
104
+ ui.Button({ key: 'close', label: 'Close', hotkey: 'q', role: 'dismiss', onPress: actions.close }),
105
+ ],
106
+ });
107
+ }
108
+
109
+ function header(ui, view, actions) {
110
+ const auto = view.mode === 'auto';
111
+ const jev =
112
+ view.phase === 'unavailable'
113
+ ? ui.text('Routing unavailable', { color: 'yellow' })
114
+ : view.error
115
+ ? ui.text(`${CLASSIFIER} ${CLASSIFIER_ERRORS[view.error] ?? view.error}`, { color: 'yellow' })
116
+ : view.keySet
117
+ ? ui.text(`${CLASSIFIER} ready${Number.isFinite(view.adviceMs) ? ` · ${view.adviceMs} ms` : ''}`, {
118
+ color: 'green',
119
+ })
120
+ : ui.text(`${CLASSIFIER} key not set`, { color: 'yellow' });
121
+ return [
122
+ ui.line(ui.head(`ROUTER · ${auto ? 'Auto' : 'Manual'}`), ' ', jev),
123
+ view.phase === 'unavailable' && view.error ? ui.text(view.error, { color: 'yellow' }) : null,
124
+ ...(view.error === GATEWAY_SETTINGS ? GATEWAY_CLEANUP.map((line) => ui.text(line, { color: 'yellow' })) : []),
125
+ ui.line(
126
+ ui.Button({
127
+ key: 'auto',
128
+ label: 'Auto',
129
+ hotkey: 'a',
130
+ variant: auto ? 'primary' : 'secondary',
131
+ onPress: () => actions.mode('auto'),
132
+ }),
133
+ ' ',
134
+ ui.Button({
135
+ key: 'manual',
136
+ label: 'Manual: keep /model',
137
+ hotkey: 'm',
138
+ variant: auto ? 'secondary' : 'primary',
139
+ onPress: () => actions.mode('manual'),
140
+ }),
141
+ ),
142
+ ui.line(
143
+ ...TABS.flatMap(([id, hotkey, label]) => [
144
+ ui.Button({
145
+ key: `tab-${id}`,
146
+ label,
147
+ hotkey,
148
+ variant: (view.tab ?? 'now') === id ? 'primary' : 'secondary',
149
+ onPress: () => actions.tab(id),
150
+ }),
151
+ ' ',
152
+ ]),
153
+ ui.Button({ key: 'help', label: '?', variant: view.help ? 'primary' : 'secondary', onPress: actions.help }),
154
+ ),
155
+ ui.text(' '),
156
+ ];
157
+ }
158
+
159
+ function nowTab(ui, config, view, usage, actions) {
160
+ const metrics = usageMetrics(config, view, usage);
161
+ const auto = view.mode === 'auto';
162
+ const current = view.selectedModel ?? view.nativeModel;
163
+ const served =
164
+ view.actualModel && current && view.actualModel !== current && !view.actualModel.startsWith(`${current}-`);
165
+ const out = [
166
+ ui.line(
167
+ 'Now ',
168
+ view.tier ? ui.tier(view.tier, `▌${view.tier} `) : null,
169
+ `${modelName(current)}${view.effort === null || view.effort === undefined ? '' : ` · ${view.effort}`}`,
170
+ ),
171
+ ui.line('Why ', REASONS[view.reason] ?? view.reason ?? 'ready'),
172
+ served
173
+ ? ui.line(ui.text('Served ', { color: 'yellow' }), `${modelName(view.actualModel)} · native fallback`)
174
+ : null,
175
+ view.pendingPin
176
+ ? ui.line(
177
+ ui.text('Pinned ', { color: 'yellow' }),
178
+ 'next turn → ',
179
+ ui.tier(view.pendingPin),
180
+ ' ',
181
+ ui.Button({ key: 'unpin', label: 'unpin', onPress: actions.unpin }),
182
+ )
183
+ : null,
184
+ view.keySet
185
+ ? null
186
+ : ui.line(
187
+ ui.text('Jev key not set: keeping the model ', { color: 'yellow' }),
188
+ ui.Button({ key: 'key', label: 'Set Jev key', hotkey: 'k', onPress: actions.key }),
189
+ ),
190
+ ui.text(' '),
191
+ ui.head('TIERS · next turn'),
192
+ ui.dim(` ${'tier'.padEnd(8)}${'route'.padEnd(22)}Jev support`),
193
+ ];
194
+ for (const tier of LADDER) {
195
+ const support = view.probabilities?.[tier];
196
+ const meter = Number.isFinite(support) ? bar(support, 1, 10) : null;
197
+ out.push(
198
+ ui.line(
199
+ view.tier === tier ? ui.tier(tier, '▶ ') : ' ',
200
+ ui.tier(tier, tier.padEnd(8)),
201
+ routeName(config, config.routes[tier]).padEnd(22),
202
+ meter ? ui.text(meter.text, { color: TIER_COLOR[tier] }) : ui.dim('—'.padEnd(10)),
203
+ meter ? ` ${percent(support).padStart(4)} ` : ' ',
204
+ ui.Button({
205
+ key: `pin-${tier}`,
206
+ label: 'pin',
207
+ dimColor: !auto,
208
+ onPress: () => actions.pin(tier),
209
+ }),
210
+ ),
211
+ );
212
+ }
213
+ const estimate = view.estimate;
214
+ if (Number.isFinite(estimate?.threshold)) {
215
+ const [direction, mass] = Number.isFinite(estimate.upgradeMass)
216
+ ? ['up', estimate.upgradeMass]
217
+ : ['down', estimate.downgradeMass];
218
+ out.push(
219
+ ui.dim(
220
+ ` switch needs ${percent(estimate.threshold)} · Jev gave ${Number.isFinite(mass) ? percent(mass) : '—'} ${direction}` +
221
+ `${Number.isFinite(estimate.taxUsd) ? ` · tax ≈ $${estimate.taxUsd.toFixed(2)}` : ''}`,
222
+ ),
223
+ );
224
+ }
225
+ out.push(ui.dim(auto ? ' Pins serve the next turn only.' : ' Pins need Auto. Manual keeps the /model choice.'));
226
+ out.push(ui.text(' '), ...replies(ui, view));
227
+ out.push(
228
+ ui.text(' '),
229
+ ui.gauge('Context ', metrics.contextBar, contextSuffix(metrics)),
230
+ ui.gauge(
231
+ 'Cache ',
232
+ metrics.cacheBar,
233
+ metrics.cacheBar.percent === null ? 'no reply yet' : 'reused on the last reply',
234
+ ),
235
+ ui.line(
236
+ `Cost ${dollars(metrics.cost)} `,
237
+ ui.dim('by Claude'),
238
+ Number.isFinite(metrics.cacheBenefit) ? ` · cache saved ≈ $${metrics.cacheBenefit.toFixed(2)}` : '',
239
+ ),
240
+ );
241
+ return out;
242
+ }
243
+
244
+ // One cell per reply, colored by the tier that served it; a dot where routing did not choose (Manual, fallback).
245
+ function replies(ui, view) {
246
+ const tiers = view.tiers ?? [];
247
+ if (!tiers.length) return [ui.head('REPLIES'), ui.dim(' no replies yet')];
248
+ const switches = tiers.slice(1).filter((tier, i) => tier && tiers[i] && tier !== tiers[i]).length;
249
+ return [
250
+ ui.head(`REPLIES · last ${tiers.length}`),
251
+ ui.line(
252
+ ' ',
253
+ ...tiers.map((tier) => (tier ? ui.tier(tier, '█') : ui.dim('·'))),
254
+ ui.dim(` ${switches} switch${switches === 1 ? '' : 'es'}`),
255
+ ),
256
+ ui.line(' ', ...TIERS.flatMap((tier) => [ui.tier(tier, '■ '), `${tier} `])),
257
+ ];
258
+ }
259
+
260
+ function tiersTab(ui, config, view, _usage, actions, modelOptions) {
261
+ const draft = effectiveRoutes(routeDraftOf(config, view), config);
262
+ const out = [
263
+ ui.head('ROUTES · future turns'),
264
+ ui.dim(`${'tier'.padEnd(8)}${'model'.padEnd(14)}${'effort'.padEnd(12)}${'$/M in · out'.padEnd(14)}window`),
265
+ ];
266
+ for (const tier of LADDER) {
267
+ const route = draft.routes[tier];
268
+ const model = config.models[route.model];
269
+ const changed = !sameRoute(route, config.routes[tier]);
270
+ const aliases = modelOptions.includes(route.model) ? modelOptions : [route.model, ...modelOptions];
271
+ out.push(
272
+ ui.line(
273
+ ui.cell(8, ui.tier(tier)),
274
+ ui.cell(
275
+ 14,
276
+ ui.Select
277
+ ? ui.Select({
278
+ key: `route-model-${tier}`,
279
+ value: route.model,
280
+ options: aliases.map((alias) => ({ value: alias, label: modelName(config.models[alias].id) })),
281
+ onSelect: (alias) => actions.routeModel(tier, alias),
282
+ })
283
+ : modelName(model.id),
284
+ ),
285
+ ui.cell(
286
+ 12,
287
+ !model.efforts.length
288
+ ? ui.dim('none')
289
+ : ui.Select
290
+ ? ui.Select({
291
+ key: `route-effort-${tier}`,
292
+ value: route.effort ?? SESSION_EFFORT,
293
+ options: [SESSION_EFFORT, ...model.efforts].map((effort) => ({ value: effort, label: effort })),
294
+ onSelect: (effort) => actions.routeEffort(tier, effort === SESSION_EFFORT ? null : effort),
295
+ })
296
+ : (route.effort ?? SESSION_EFFORT),
297
+ ),
298
+ ui.cell(14, `${model.input} · ${model.output ?? '?'}`),
299
+ windowSize(model.contextWindow),
300
+ changed ? ui.text(' ●', { color: 'yellow' }) : null,
301
+ ),
302
+ );
303
+ }
304
+ out.push(
305
+ ui.line(
306
+ ui.Select
307
+ ? ui.Select({
308
+ key: 'baseline',
309
+ label: 'Baseline tier',
310
+ value: draft.baselineTier,
311
+ options: TIERS.map((tier) => ({ value: tier, label: tier })),
312
+ onSelect: (tier) => actions.baseline(tier),
313
+ })
314
+ : `Baseline tier: ${draft.baselineTier}`,
315
+ ui.dim(' start here, fall back here'),
316
+ ),
317
+ ui.text(' '),
318
+ ui.head('SWITCH COST · from these routes'),
319
+ );
320
+ for (let i = 0; i < LADDER.length - 1; i += 1) {
321
+ const upper = draft.routes[LADDER[i]];
322
+ const lower = draft.routes[LADDER[i + 1]];
323
+ const pair = `${LADDER[i + 1]} → ${LADDER[i]}`.padEnd(16);
324
+ if (sameRoute(upper, lower))
325
+ out.push(ui.line(ui.text('! ', { color: 'yellow' }), pair, 'identical: this step changes nothing'));
326
+ else if (upper.model === lower.model)
327
+ out.push(ui.line(ui.dim('· '), pair, 'same model, new effort: priced as a new cache'));
328
+ else out.push(ui.line(ui.dim('· '), pair, 'model change: priced as a cold cache write'));
329
+ }
330
+ const changes = TIERS.filter((tier) => !sameRoute(draft.routes[tier], config.routes[tier]));
331
+ const baselineChanged = draft.baselineTier !== config.baselineTier;
332
+ const dirty = changes.length > 0 || baselineChanged;
333
+ out.push(ui.text(' '));
334
+ if (dirty) {
335
+ out.push(ui.dim('router.json changes:'));
336
+ for (const tier of changes) {
337
+ out.push(ui.text(`- routes.${tier.padEnd(7)} ${routeName(config, config.routes[tier])}`, { color: 'red' }));
338
+ out.push(ui.text(`+ routes.${tier.padEnd(7)} ${routeName(config, draft.routes[tier])}`, { color: 'green' }));
339
+ }
340
+ if (baselineChanged) {
341
+ out.push(ui.text(`- baselineTier ${config.baselineTier}`, { color: 'red' }));
342
+ out.push(ui.text(`+ baselineTier ${draft.baselineTier}`, { color: 'green' }));
343
+ }
344
+ } else out.push(ui.dim('No changes. Pick a model or an effort above.'));
345
+ out.push(
346
+ ui.line(
347
+ ui.Button({
348
+ key: 'save-routes',
349
+ label: 'Save routes',
350
+ hotkey: 's',
351
+ variant: dirty ? 'primary' : 'secondary',
352
+ dimColor: !dirty,
353
+ onPress: actions.saveRoutes,
354
+ }),
355
+ ' ',
356
+ ui.Button({ key: 'discard-routes', label: 'Discard', dimColor: !dirty, onPress: actions.discardRoutes }),
357
+ ' ',
358
+ ui.Button({ key: 'reset-routes', label: 'Reset to defaults', hotkey: 'r', onPress: actions.resetRoutes }),
359
+ ),
360
+ ui.dim('A new model ID needs router.json → models: price, window, efforts.'),
361
+ );
362
+ return out;
363
+ }
364
+
365
+ function tuningTab(ui, config, view, _usage, actions) {
366
+ const saved = tuningOf(config);
367
+ const draft = { ...saved, ...view.tuning };
368
+ const base = view.tuningBase ?? saved;
369
+ const edited = (key) => Object.hasOwn(view.tuning ?? {}, key) && view.tuning[key] !== base[key];
370
+ const rows = [
371
+ ['timeoutMs', 'Jev deadline', (v) => `${v} ms`, 'then keep the model'],
372
+ ['downgradeVotes', 'Votes to go down', String, 'agreeing turns before cheaper'],
373
+ ['horizon', 'Payback horizon', (v) => `${v} turns`, 'a switch repays its cache'],
374
+ ['cashCapUsd', 'Credits cap', (v) => `$${v.toFixed(2)}`, 'max cold write on credits'],
375
+ ];
376
+ const dirty = rows.some(([key]) => edited(key));
377
+ const health = view.health ?? { failures: 0, pausedUntil: 0 };
378
+ return [
379
+ ui.head('POLICY · future turns'),
380
+ ...rows.map(([key, label, format, hint]) => {
381
+ const values = TUNING_CHOICES[key].includes(draft[key])
382
+ ? TUNING_CHOICES[key]
383
+ : [draft[key], ...TUNING_CHOICES[key]];
384
+ return ui.line(
385
+ ui.cell(18, label),
386
+ ui.cell(
387
+ 12,
388
+ ui.Select
389
+ ? ui.Select({
390
+ key,
391
+ value: String(draft[key]),
392
+ options: values.map((value) => ({ value: String(value), label: format(value) })),
393
+ onSelect: (picked) => {
394
+ if (TUNING_CHOICES[key].includes(Number(picked))) actions.tune(key, Number(picked));
395
+ },
396
+ })
397
+ : format(draft[key]),
398
+ ),
399
+ ui.cell(2, edited(key) ? ui.text('●', { color: 'yellow' }) : ''),
400
+ ui.dim(hint),
401
+ );
402
+ }),
403
+ ui.line(
404
+ ui.Button({
405
+ key: 'save-tuning',
406
+ label: 'Save tuning',
407
+ variant: dirty ? 'primary' : 'secondary',
408
+ dimColor: !dirty,
409
+ onPress: actions.saveTuning,
410
+ }),
411
+ ' ',
412
+ ui.Button({ key: 'reset-tuning', label: 'Discard', dimColor: !dirty, onPress: actions.resetTuning }),
413
+ ),
414
+ ui.text(' '),
415
+ ui.head('JEV'),
416
+ ui.line(
417
+ 'Key ',
418
+ view.keySet ? ui.text('● configured ', { color: 'green' }) : ui.text('● not set ', { color: 'yellow' }),
419
+ ui.Button({ key: 'key', label: view.keySet ? 'Edit key' : 'Set Jev key', hotkey: 'k', onPress: actions.key }),
420
+ ),
421
+ ui.text(
422
+ `Health ${health.pausedUntil > Date.now() ? `paused until ${new Date(health.pausedUntil).toLocaleTimeString()}` : 'active'} · ${health.failures} recent failure${health.failures === 1 ? '' : 's'}`,
423
+ ),
424
+ ui.text(' '),
425
+ ui.head('CONFIG'),
426
+ ui.line(
427
+ `File ${view.configPath ?? 'profile router.json'} `,
428
+ view.configPath ? ui.Button({ key: 'copy-path', label: 'copy', onPress: actions.copyPath }) : null,
429
+ ),
430
+ ui.dim('Main conversation only. Subagents keep their own model.'),
431
+ ];
432
+ }
433
+
434
+ function usageTab(ui, config, view, usage) {
435
+ const metrics = usageMetrics(config, view, usage);
436
+ const history = view.history ?? [];
437
+ const tiers = view.tiers ?? [];
438
+ const glyphs = sparkline(history);
439
+ const trend = history.length
440
+ ? ui.line(
441
+ ' ',
442
+ ...[...glyphs].map((glyph, i) => {
443
+ const tier = tiers[tiers.length - history.length + i];
444
+ return tier ? ui.tier(tier, glyph) : ui.text(glyph);
445
+ }),
446
+ ui.dim(` ${formatTokens(Math.min(...history))} … ${formatTokens(Math.max(...history))}`),
447
+ )
448
+ : ui.dim(' no replies yet');
449
+ return [
450
+ ui.head('USAGE · Claude readings'),
451
+ ui.line(`Cost ${dollars(metrics.cost)} `, ui.dim('reported by Claude')),
452
+ ui.gauge('Context ', metrics.contextBar, contextSuffix(metrics)),
453
+ ui.dim(` observed ${formatTokens(metrics.observed)} · estimated ${formatTokens(view.contextTokens)}`),
454
+ ui.gauge('Cache ', metrics.cacheBar, metrics.cacheBar.percent === null ? 'no reply yet' : 'last reply'),
455
+ ui.dim(` read ${formatTokens(view.cacheRead)} · written ${formatTokens(view.cacheWrite)} tokens`),
456
+ ui.text(`Output ${formatTokens(view.outputTokens)} tokens on the last reply`),
457
+ ui.text(' '),
458
+ ui.head('INPUT PER REPLY · lowest to highest'),
459
+ trend,
460
+ ...(usage?.rateLimits ?? [])
461
+ .filter((limit) => Number.isFinite(limit.percentUsed))
462
+ .map((limit) => ui.gauge(`${limit.kind.replaceAll('_', ' ').padEnd(11)}`, bar(limit.percentUsed, 100), 'used')),
463
+ ui.text(' '),
464
+ ui.head('ESTIMATES · configured list prices'),
465
+ ui.text(`Cache read benefit ${dollars(metrics.cacheBenefit)}`),
466
+ Number.isFinite(view.estimate?.taxUsd) ? ui.text(`Switch tax ${dollars(view.estimate.taxUsd)}`) : null,
467
+ ...(view.comparison
468
+ ? [
469
+ ui.text(`Compared tiers ${view.comparison.incumbent} → ${view.comparison.candidate}`),
470
+ ui.text(
471
+ `Next-turn difference ${difference(view.comparison.minUsd)} to ${difference(view.comparison.maxUsd)}`,
472
+ ),
473
+ ui.text(
474
+ `Payback ${view.comparison.paybackTurns === null ? 'none projected' : `${view.comparison.paybackTurns} later turns`}`,
475
+ ),
476
+ ]
477
+ : []),
478
+ ui.dim('Press ? for what these estimates leave out.'),
479
+ ];
480
+ }
481
+
482
+ function helpLines(ui) {
483
+ return [
484
+ ui.text(' '),
485
+ ui.head('ABOUT THESE NUMBERS'),
486
+ ui.dim('Cost, context and cache are Claude readings. $ estimates use the'),
487
+ ui.dim('list prices in router.json; plan prices are equivalents, not cash.'),
488
+ ui.dim('Routing savings are not measured. Cache benefit is before writes.'),
489
+ ui.dim('The context bar uses the routed model’s window, 20% in reserve.'),
490
+ ui.dim('A switch estimate prices 5m–1h cache writes; minus means cheaper.'),
491
+ ];
492
+ }