@alexeiled/claude-router 1.24.0 → 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 (78) hide show
  1. package/.claude-plugin/plugin.json +1 -1
  2. package/CHANGELOG.md +44 -0
  3. package/README.md +39 -7
  4. package/docs/architecture.md +27 -4
  5. package/docs/configuration.md +23 -14
  6. package/docs/evaluation.md +3 -3
  7. package/docs/native-router.md +11 -3
  8. package/docs/router-band.svg +124 -133
  9. package/docs/router-pane-classifier.svg +24 -23
  10. package/docs/router-pane-now.svg +9 -7
  11. package/docs/router-pane-policy.svg +4 -4
  12. package/docs/router-pane-routes.svg +8 -8
  13. package/docs/router-pane-usage-whatif.svg +14 -14
  14. package/docs/router-pane-usage.svg +20 -20
  15. package/docs/routing-modes.md +10 -8
  16. package/docs/user-guide.md +70 -17
  17. package/hooks/native-router.mjs +333 -80
  18. package/lib/activity-stats.mjs +23 -4
  19. package/lib/activity.mjs +7 -5
  20. package/lib/auto-engine.mjs +13 -6
  21. package/lib/auto-route.mjs +10 -4
  22. package/lib/band.mjs +35 -440
  23. package/lib/classifier-client.mjs +12 -8
  24. package/lib/config-file.mjs +7 -2
  25. package/lib/config.mjs +24 -9
  26. package/lib/cost.mjs +5 -1
  27. package/lib/costs.mjs +4 -2
  28. package/lib/decisions.mjs +13 -9
  29. package/lib/display.mjs +69 -20
  30. package/lib/facts.mjs +3 -0
  31. package/lib/modes.mjs +8 -4
  32. package/lib/panel.mjs +75 -2167
  33. package/lib/policy.mjs +7 -6
  34. package/lib/replay-trace.mjs +5 -2
  35. package/lib/replay.mjs +7 -1
  36. package/lib/route-line.mjs +46 -0
  37. package/lib/route.mjs +21 -16
  38. package/lib/savings.mjs +14 -3
  39. package/lib/subagents.mjs +41 -11
  40. package/lib/subcommands.mjs +60 -0
  41. package/lib/ui/fallback.mjs +22 -0
  42. package/lib/ui/graphical/band.mjs +256 -0
  43. package/lib/ui/graphical/charts.mjs +163 -0
  44. package/lib/ui/graphical/classifier.mjs +153 -0
  45. package/lib/ui/graphical/frame.mjs +227 -0
  46. package/lib/ui/graphical/kit.mjs +156 -0
  47. package/lib/ui/graphical/meter.mjs +25 -0
  48. package/lib/ui/graphical/now.mjs +353 -0
  49. package/lib/ui/graphical/policy.mjs +56 -0
  50. package/lib/ui/graphical/routes.mjs +264 -0
  51. package/lib/ui/graphical/squares.mjs +29 -0
  52. package/lib/ui/graphical/usage.mjs +376 -0
  53. package/lib/ui/model/band.mjs +439 -0
  54. package/lib/ui/model/classifier.mjs +308 -0
  55. package/lib/ui/model/draft.mjs +62 -0
  56. package/lib/ui/model/format.mjs +41 -0
  57. package/lib/ui/model/frame.mjs +359 -0
  58. package/lib/ui/model/now.mjs +390 -0
  59. package/lib/ui/model/policy.mjs +194 -0
  60. package/lib/ui/model/routes.mjs +392 -0
  61. package/lib/ui/model/usage-agents.mjs +311 -0
  62. package/lib/ui/model/usage-breakdown.mjs +237 -0
  63. package/lib/ui/model/usage-shared.mjs +58 -0
  64. package/lib/ui/model/usage.mjs +330 -0
  65. package/lib/ui/terminal/band.mjs +220 -0
  66. package/lib/ui/terminal/classifier.mjs +142 -0
  67. package/lib/ui/terminal/frame.mjs +169 -0
  68. package/lib/ui/terminal/kit.mjs +133 -0
  69. package/lib/ui/terminal/now.mjs +300 -0
  70. package/lib/ui/terminal/policy.mjs +52 -0
  71. package/lib/ui/terminal/routes.mjs +167 -0
  72. package/lib/ui/terminal/usage.mjs +363 -0
  73. package/lib/ui/terminal/wrap.mjs +37 -0
  74. package/lib/ui/tokens.mjs +106 -0
  75. package/lib/usage.mjs +5 -5
  76. package/lib/view.mjs +5 -2
  77. package/package.json +3 -2
  78. package/types/index.d.ts +15 -0
@@ -0,0 +1,376 @@
1
+ // The Usage tab as cards for desktop, VS Code and mobile, drawn from the model in ui/model/usage.mjs: the period control and its scope; Summary with the headline figure and the ledger; Trend; Breakdown with
2
+ // What if; Worth a look; Subagents; About these numbers; then Delete history on its own row. Layout only: every word,
3
+ // figure and tone is the model's.
4
+ import { isFiniteNumber } from '../tokens.mjs';
5
+ import { squares } from './squares.mjs';
6
+
7
+ // The tables' fixed columns, in cells; a column without a width takes what is left.
8
+ const SUMMARY = {
9
+ label: { align: 'left' },
10
+ amount: { align: 'right', width: 9 },
11
+ diff: { align: 'right', width: 12 },
12
+ base: { align: 'right', width: 10 },
13
+ };
14
+ const BREAKDOWN = {
15
+ name: { align: 'left' },
16
+ replies: { align: 'right', width: 7 },
17
+ cost: { align: 'right', width: 9 },
18
+ diff: { align: 'right', width: 12 },
19
+ share: { align: 'left', width: 22 },
20
+ };
21
+ const WHAT_IF = {
22
+ label: { align: 'left' },
23
+ bar: { align: 'left', width: 30 },
24
+ cost: { align: 'right', width: 9 },
25
+ diff: { align: 'right', width: 12 },
26
+ };
27
+ const AGENTS = {
28
+ name: { align: 'left' },
29
+ squares: { align: 'left', width: 14 },
30
+ agents: { align: 'right', width: 6 },
31
+ cost: { align: 'right', width: 9 },
32
+ pick: { align: 'right', width: 14 },
33
+ };
34
+ // The tables drop their wide-only columns below this many columns.
35
+ const WIDE = 80;
36
+ // An open row's children and notes sit in from its name.
37
+ const INDENT = 4;
38
+
39
+ const figure = (ui, text, extra = {}) => ui.text(text, { tabular: true, wrap: 'truncate-end', ...extra });
40
+ const toned = (ui, one) => figure(ui, one.text, { color: ui.color(one.tone) });
41
+ const footnote = (ui, words) => ui.muted(words, { size: 'footnote', tabular: true, wrap: 'wrap' });
42
+ const subheading = (ui, words) => ui.muted(words, { size: 'footnote', weight: 'semibold' });
43
+ const wrapRow = (ui, children, extra = {}) =>
44
+ ui.Box({ flexDirection: 'row', flexWrap: 'wrap', alignItems: 'center', gap: 'sm', ...extra, children });
45
+ const columnsOf = (spec, keys, labels = {}) => keys.map((key) => ({ key, label: labels[key] ?? '', ...spec[key] }));
46
+ const chevron = (ui, row) => ui.Button({ key: row.key, label: row.open ? '▾' : '▸', plain: true, onPress: row.toggle });
47
+ const indented = (ui, children) =>
48
+ ui.Box({ flexDirection: 'row', alignItems: 'center', gap: 'xs', paddingLeft: INDENT, children });
49
+
50
+ /**
51
+ * @param {any} ui the graphical kit
52
+ * @param {import('../model/usage.mjs').UsageModel} source
53
+ * @param {{ columns: number | null }} opts
54
+ */
55
+ export function graphicalUsage(ui, source, { columns }) {
56
+ // A pane narrower than this, or one that reports no width, drops each table's wide-only columns for its narrow ones.
57
+ const wide = isFiniteNumber(columns) && columns >= WIDE;
58
+ const fit = (list = []) => list.filter(({ show }) => !show || (show === 'wide') === wide).map(({ key }) => key);
59
+ const model = {
60
+ ...source,
61
+ summary: { ...source.summary, columns: fit(source.summary.columns) },
62
+ breakdown: source.breakdown && { ...source.breakdown, columns: fit(source.breakdown.columns) },
63
+ compare: source.compare && { ...source.compare, columns: fit(source.compare.columns) },
64
+ agents: { ...source.agents, columns: fit(source.agents.columns) },
65
+ };
66
+ return [
67
+ ui.Box({
68
+ flexDirection: 'column',
69
+ gap: 'lg',
70
+ children: [
71
+ periodBlock(ui, model),
72
+ summaryCard(ui, model.summary, model.stats),
73
+ model.trend?.chart ? trendCard(ui, model.trend) : null,
74
+ model.breakdown ? breakdownCard(ui, model.breakdown, model.compare) : null,
75
+ model.insights ? insightsCard(ui, model.insights) : null,
76
+ agentsCard(ui, model.agents),
77
+ ui.section(
78
+ model.notes.title,
79
+ {},
80
+ model.notes.lines.map((line) => footnote(ui, line)),
81
+ ),
82
+ deleteRow(ui, model.delete),
83
+ ].filter(Boolean),
84
+ }),
85
+ ];
86
+ }
87
+
88
+ // The period Buttons, then which replies they hold and against what.
89
+ function periodBlock(ui, { period, scope }) {
90
+ return ui.Box({
91
+ flexDirection: 'column',
92
+ gap: 'sm',
93
+ children: [
94
+ ui.choice({
95
+ key: 'period',
96
+ options: period.options.map((option) => ({
97
+ value: option.value,
98
+ key: option.key,
99
+ label: option.label,
100
+ ...(option.hotkey ? { hotkey: option.hotkey } : {}),
101
+ })),
102
+ selected: period.value,
103
+ onPick: period.pick,
104
+ gap: 'sm',
105
+ }),
106
+ ui.muted(scope.graphical, { wrap: 'wrap' }),
107
+ ],
108
+ });
109
+ }
110
+
111
+ // The headline figure and its saving, the ledger, the tokens and the notes that apply.
112
+ function summaryCard(ui, summary, stats) {
113
+ if (summary.empty) return ui.section('Summary', {}, [ui.text(summary.empty.graphical, { wrap: 'wrap' })]);
114
+ const { headline } = summary;
115
+ const record = (one) => ({
116
+ label:
117
+ one.kind === 'part'
118
+ ? indented(ui, [ui.muted(one.graphical), one.note ? footnote(ui, one.note.graphical) : null].filter(Boolean))
119
+ : ui.text(one.graphical, { wrap: 'truncate-end', ...(one.strong ? { weight: 'semibold' } : {}) }),
120
+ amount: one.amount ? figure(ui, one.amount, one.strong ? { weight: 'semibold' } : {}) : '',
121
+ diff: one.diff ? toned(ui, one.diff) : '',
122
+ base: one.base ? figure(ui, one.base, { color: ui.color('muted') }) : '',
123
+ });
124
+ return ui.section(
125
+ 'Summary',
126
+ {},
127
+ [
128
+ headline.compared
129
+ ? ui.stat({
130
+ value: summary.stat.value,
131
+ caption: summary.stat.caption,
132
+ delta: headline.delta,
133
+ tone: headline.tone,
134
+ })
135
+ : ui.stat({ value: summary.stat.value, caption: summary.stat.caption }),
136
+ headline.compared ? null : ui.muted(headline.text, { wrap: 'wrap' }),
137
+ headline.compared && headline.early
138
+ ? ui.text(headline.early, { size: 'footnote', color: ui.color('warning'), wrap: 'wrap' })
139
+ : null,
140
+ ui.table(
141
+ columnsOf(SUMMARY, summary.columns, summary.labels),
142
+ [...summary.rows, summary.total, summary.credits].filter(Boolean).map(record),
143
+ ),
144
+ stats ? footnote(ui, stats.text) : null,
145
+ summary.legacy ? footnote(ui, summary.legacy.graphical) : null,
146
+ summary.lost
147
+ ? ui.notice(
148
+ 'warning',
149
+ summary.lost.text,
150
+ ui.Button({ key: summary.lost.button.key, label: summary.lost.button.label, onPress: summary.lost.press }),
151
+ )
152
+ : null,
153
+ ].filter(Boolean),
154
+ );
155
+ }
156
+
157
+ function trendCard(ui, trend) {
158
+ return ui.section(trend.title, { hint: trend.hint }, [ui.trend(trend.chart), footnote(ui, trend.peak.graphical)]);
159
+ }
160
+
161
+ // A breakdown row's name: an activity in its tone, a tier as its bars and name, a model or route by name.
162
+ function nameParts(ui, name) {
163
+ if (name.kind === 'none') return [ui.muted(name.graphical)];
164
+ if (name.kind === 'activity') return [ui.text(name.graphical, { color: ui.color('activity'), wrap: 'truncate-end' })];
165
+ if (name.kind === 'tier')
166
+ return [ui.tierMeter(name.text, 'lit', { inButton: true }), ui.text(name.graphical, { wrap: 'truncate-end' })];
167
+ return [ui.text(name.graphical, { wrap: 'truncate-end' })];
168
+ }
169
+
170
+ // The grouping and What if over the cost by activity, model or tier, each row a bar of its share; an open row's
171
+ // children and cost parts in the same card; What if's rows under them when it is on.
172
+ function breakdownCard(ui, breakdown, compare) {
173
+ const { group } = breakdown;
174
+ const controls = wrapRow(
175
+ ui,
176
+ [
177
+ ui.choice({
178
+ key: 'group',
179
+ options: group.options.map((option) => ({
180
+ value: option.value,
181
+ key: option.key,
182
+ label: option.label.graphical,
183
+ ...(option.hotkey ? { hotkey: option.hotkey } : {}),
184
+ })),
185
+ selected: group.value,
186
+ onPick: group.pick,
187
+ gap: 'sm',
188
+ }),
189
+ ui.Button({
190
+ key: compare.toggle.key,
191
+ label: compare.toggle.label.graphical,
192
+ hotkey: compare.toggle.hotkey,
193
+ variant: compare.on ? 'primary' : 'secondary',
194
+ onPress: compare.toggle.press,
195
+ }),
196
+ ],
197
+ { justifyContent: 'space-between', gap: 'md' },
198
+ );
199
+ if (breakdown.empty)
200
+ return ui.section(breakdown.title, {}, [
201
+ controls,
202
+ ui.muted(breakdown.empty.graphical, { wrap: 'wrap' }),
203
+ ...(compare.on ? whatIf(ui, compare) : []),
204
+ ]);
205
+ const numbers = (one) => ({
206
+ replies: figure(ui, one.replies),
207
+ cost: figure(ui, one.cost),
208
+ diff: one.diff ? toned(ui, one.diff) : '',
209
+ });
210
+ const records = breakdown.rows.flatMap((row) => [
211
+ {
212
+ name: ui.Box({
213
+ flexDirection: 'row',
214
+ alignItems: 'center',
215
+ gap: 'xs',
216
+ children: [chevron(ui, row), ...nameParts(ui, row.name)],
217
+ }),
218
+ ...numbers(row),
219
+ share: ui.meter({ value: row.share.value, tone: 'accent', text: row.share.text }),
220
+ },
221
+ ...row.children.map((child) => ({ name: indented(ui, nameParts(ui, child.name)), ...numbers(child), share: '' })),
222
+ ...(row.note ? [{ span: indented(ui, [footnote(ui, row.note.graphical)]) }] : []),
223
+ ]);
224
+ return ui.section(breakdown.title, {}, [
225
+ controls,
226
+ ui.table(columnsOf(BREAKDOWN, breakdown.columns, breakdown.labels), records),
227
+ ...(compare.on ? whatIf(ui, compare) : []),
228
+ ]);
229
+ }
230
+
231
+ // What the same tokens cost on each model alone, each a bar with its cost beside it, against your model.
232
+ function whatIf(ui, compare) {
233
+ const head = wrapRow(ui, [subheading(ui, compare.title), footnote(ui, compare.hint.graphical)]);
234
+ if (compare.unavailable) return [head, ui.muted(compare.unavailable, { wrap: 'wrap' })];
235
+ const records = compare.rows.map((row) => ({
236
+ label: ui.text(row.label, { wrap: 'truncate-end', ...(row.strong ? { weight: 'semibold' } : {}) }),
237
+ bar: ui.meter({ value: row.fill, tone: row.tone, text: row.cost }),
238
+ cost: figure(ui, row.cost),
239
+ diff: row.diff ? toned(ui, row.diff) : '',
240
+ }));
241
+ return [
242
+ head,
243
+ ui.table(columnsOf(WHAT_IF, compare.columns, compare.labels), records),
244
+ footnote(ui, compare.note.graphical),
245
+ ];
246
+ }
247
+
248
+ function insightsCard(ui, insights) {
249
+ const button = (b) => (b ? ui.Button({ key: b.key, label: b.label, onPress: b.press }) : null);
250
+ return ui.section(
251
+ insights.title,
252
+ { hint: insights.hint.graphical },
253
+ insights.items.map((item) =>
254
+ item.kind === 'switch'
255
+ ? wrapRow(ui, [ui.text(item.graphical, { wrap: 'wrap' }), button(item.button)])
256
+ : wrapRow(
257
+ ui,
258
+ [
259
+ item.activity ? ui.text(item.activity, { color: ui.color('activity') }) : null,
260
+ item.activity ? ui.muted('·') : null,
261
+ ...(item.tier
262
+ ? [ui.tierMeter(item.tier, 'lit', { inButton: true }), ui.text(item.tierLabel)]
263
+ : [ui.muted(item.notRouted.graphical)]),
264
+ ui.text(item.text, { wrap: 'wrap' }),
265
+ item.route ? ui.muted(item.route, { wrap: 'wrap' }) : null,
266
+ button(item.button),
267
+ ].filter(Boolean),
268
+ ),
269
+ ),
270
+ );
271
+ }
272
+
273
+ // Every agent by model, what the router moved and how routing paid off; then the routed types and the pass-throughs,
274
+ // each opening to its models.
275
+ function agentsCard(ui, agents) {
276
+ if (agents.empty)
277
+ return ui.section(
278
+ agents.title,
279
+ { hint: agents.hint },
280
+ [
281
+ ui.text(agents.empty.graphical, { wrap: 'wrap' }),
282
+ agents.undated ? footnote(ui, agents.undated.graphical) : null,
283
+ agents.older ? footnote(ui, agents.older) : null,
284
+ ].filter(Boolean),
285
+ );
286
+ const { summary } = agents;
287
+ const group = (one) => {
288
+ const records = one.rows.flatMap((row) => [
289
+ {
290
+ name: ui.Box({
291
+ flexDirection: 'row',
292
+ alignItems: 'center',
293
+ gap: 'xs',
294
+ children: [chevron(ui, row), ui.text(row.name.graphical, { wrap: 'truncate-end' })],
295
+ }),
296
+ squares: ui.Box({
297
+ flexDirection: 'row',
298
+ alignItems: 'center',
299
+ gap: 'xs',
300
+ children: [
301
+ squares(ui, row.squares, row.alt),
302
+ row.squares.rest ? footnote(ui, row.squares.rest) : null,
303
+ ].filter(Boolean),
304
+ }),
305
+ agents: figure(ui, row.agents),
306
+ cost: toned(ui, row.cost),
307
+ pick: row.pick ? toned(ui, row.pick) : '',
308
+ },
309
+ // Why Claude Code picked a pass-through's model, under its row.
310
+ ...(row.why ? [{ span: indented(ui, [footnote(ui, row.why.graphical)]) }] : []),
311
+ ...row.children.map((child) => ({
312
+ name: indented(ui, [ui.text(child.name, { color: ui.color(child.tone), wrap: 'truncate-end' })]),
313
+ squares: ui.muted(child.detail),
314
+ agents: '',
315
+ cost: toned(ui, child.cost),
316
+ pick: child.pick ? toned(ui, child.pick) : '',
317
+ })),
318
+ ...(row.notes ? [{ span: indented(ui, [footnote(ui, row.notes.graphical)]) }] : []),
319
+ ]);
320
+ return ui.Box({
321
+ flexDirection: 'column',
322
+ gap: 'xs',
323
+ children: [
324
+ wrapRow(ui, [subheading(ui, one.title), footnote(ui, one.hint.graphical)]),
325
+ ui.table(columnsOf(AGENTS, agents.columns, one.labels), records),
326
+ ],
327
+ });
328
+ };
329
+ return ui.section(
330
+ agents.title,
331
+ { hint: agents.hint },
332
+ [
333
+ wrapRow(
334
+ ui,
335
+ [
336
+ squares(ui, summary.strip, summary.alt),
337
+ ...summary.names.map((name) => ui.text(name.graphical, { tabular: true, color: ui.color(name.tone) })),
338
+ ],
339
+ { gap: 'md' },
340
+ ),
341
+ wrapRow(ui, [ui.muted(summary.total), ui.muted(summary.moved.graphical), ui.muted(summary.kept.graphical)], {
342
+ gap: 'md',
343
+ }),
344
+ summary.verdict
345
+ ? summary.verdict.priced
346
+ ? ui.text(summary.verdict.graphical, { tabular: true, wrap: 'wrap', color: ui.color(summary.verdict.tone) })
347
+ : ui.muted(summary.verdict.graphical, { wrap: 'wrap' })
348
+ : null,
349
+ agents.trend
350
+ ? ui.Box({
351
+ flexDirection: 'column',
352
+ gap: 'xs',
353
+ children: [
354
+ subheading(ui, agents.trend.title),
355
+ ui.trend(agents.trend.chart),
356
+ footnote(ui, agents.trend.peak.graphical),
357
+ ],
358
+ })
359
+ : null,
360
+ agents.undated ? footnote(ui, agents.undated.graphical) : null,
361
+ ...agents.groups.map(group),
362
+ ...agents.legend.map((one) => footnote(ui, one.graphical)),
363
+ ].filter(Boolean),
364
+ );
365
+ }
366
+
367
+ // Delete history alone on its row; pressed, the question with Delete and Keep.
368
+ function deleteRow(ui, del) {
369
+ if (!del.confirming)
370
+ return wrapRow(ui, [ui.Button({ key: del.ask.key, label: del.ask.label, onPress: del.ask.press })]);
371
+ return wrapRow(ui, [
372
+ ui.text(del.question, { color: ui.color('warning'), wrap: 'wrap' }),
373
+ ui.Button({ key: del.yes.key, label: del.yes.label, variant: 'primary', onPress: del.yes.press }),
374
+ ui.Button({ key: del.no.key, label: del.no.label, onPress: del.no.press }),
375
+ ]);
376
+ }