@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,227 @@
1
+ // The pane on desktop, VS Code and mobile, drawn from the models in ui/model/frame.mjs: the title row (Router, the
2
+ // classifier's state, On | Off), the tab row, one notices slot, the body, and the save bar last, which is an Unsaved
3
+ // changes card with its table, then the last notice and Undo. The About the router card behind `?` and the provider
4
+ // profile's footnote are in the body.
5
+
6
+ /**
7
+ * The save bar's elements; none when nothing is unsaved, noticed or undoable.
8
+ * @param {any} ui the graphical kit
9
+ * @param {any} bar the save bar model (ui/model/frame.mjs saveBarOf)
10
+ */
11
+ function graphicalSaveBar(ui, bar) {
12
+ const { Box, Button } = ui;
13
+ const out = [];
14
+ if (bar.count) {
15
+ const { columns } = bar;
16
+ const table = bar.listed
17
+ ? ui.table(
18
+ [
19
+ { key: 'label', label: columns.label },
20
+ { key: 'before', label: columns.before },
21
+ { key: 'after', label: columns.after },
22
+ ],
23
+ bar.rows.map((row) => ({
24
+ label: row.label,
25
+ before: ui.muted(ui.say(row.before)),
26
+ after: ui.text(ui.say(row.after), { color: ui.color('accent'), wrap: 'truncate-end' }),
27
+ })),
28
+ )
29
+ : null;
30
+ const buttons = Box({
31
+ flexDirection: 'row',
32
+ flexWrap: 'wrap',
33
+ alignItems: 'center',
34
+ gap: 'sm',
35
+ children: [
36
+ Button({
37
+ key: bar.discard.key,
38
+ label: bar.discard.label,
39
+ hotkey: bar.discard.hotkey,
40
+ variant: 'secondary',
41
+ onPress: bar.discard.press,
42
+ }),
43
+ Button({
44
+ key: bar.save.key,
45
+ label: bar.save.label,
46
+ hotkey: bar.save.hotkey,
47
+ variant: 'primary',
48
+ onPress: bar.save.press,
49
+ }),
50
+ ],
51
+ });
52
+ out.push(ui.section(bar.title, { hint: bar.hint }, [table, buttons].filter(Boolean)));
53
+ }
54
+ const { undo } = bar;
55
+ const undoButton = undo
56
+ ? Button({ key: undo.key, label: undo.label, hotkey: undo.hotkey, onPress: undo.press })
57
+ : null;
58
+ if (bar.notice) out.push(ui.notice(bar.notice.tone, bar.notice.text, undo?.confirms ? undoButton : null));
59
+ if (undo && !undo.confirms) out.push(ui.notice('muted', undo.last, undoButton));
60
+ return out;
61
+ }
62
+
63
+ /**
64
+ * The About the router card: the help's sentences as wrapped text, the tier sentence with the tiers' meters.
65
+ * @param {any} ui the graphical kit
66
+ * @param {{ title: string, paragraphs: { text: import('../model/format.mjs').Words, tiers?: string[] }[] }} help
67
+ */
68
+ function graphicalHelp(ui, help) {
69
+ const { Box } = ui;
70
+ return ui.section(
71
+ help.title,
72
+ {},
73
+ help.paragraphs.map((paragraph) =>
74
+ paragraph.tiers
75
+ ? Box({
76
+ flexDirection: 'column',
77
+ gap: 'xs',
78
+ children: [
79
+ ui.text(ui.say(paragraph.text), { wrap: 'wrap' }),
80
+ Box({
81
+ flexDirection: 'row',
82
+ alignItems: 'center',
83
+ gap: 'sm',
84
+ children: paragraph.tiers.map((tier) => ui.tierMeter(tier, 'lit')),
85
+ }),
86
+ ],
87
+ })
88
+ : ui.text(ui.say(paragraph.text), { wrap: 'wrap' }),
89
+ ),
90
+ );
91
+ }
92
+
93
+ /**
94
+ * The provider profile and its file as a muted footnote.
95
+ * @param {any} ui the graphical kit
96
+ * @param {import('../model/format.mjs').Words} profile
97
+ */
98
+ const graphicalProfile = (ui, profile) => ui.muted(ui.say(profile), { size: 'footnote' });
99
+
100
+ /**
101
+ * How to add a classifier's credentials where `/plugin configure` cannot open: a card with the sentence, the command
102
+ * to copy (Code where the surface has it, else monospaced text), the alternative and the reload, then Copy command
103
+ * and Done.
104
+ * @param {any} ui the graphical kit
105
+ * @param {any} help the key help model (ui/model/frame.mjs keyHelpCardOf)
106
+ */
107
+ function graphicalKeyHelp(ui, help) {
108
+ const { Box, Button, Code } = ui;
109
+ return ui.section(help.title, {}, [
110
+ ui.text(help.sentence, { wrap: 'wrap' }),
111
+ Code ? Code({ source: help.command, language: 'bash' }) : ui.text(help.command, { mono: true, wrap: 'wrap' }),
112
+ ui.muted(help.alternative, { wrap: 'wrap' }),
113
+ help.note ? ui.muted(help.note, { wrap: 'wrap' }) : null,
114
+ ui.muted(help.reload, { wrap: 'wrap' }),
115
+ Box({
116
+ flexDirection: 'row',
117
+ gap: 'sm',
118
+ children: [
119
+ Button({ key: help.copy.key, label: help.copy.label, variant: 'primary', onPress: help.copy.press }),
120
+ Button({ key: help.done.key, label: help.done.label, onPress: help.done.press }),
121
+ ],
122
+ }),
123
+ ]);
124
+ }
125
+
126
+ /**
127
+ * The pane on desktop, VS Code and mobile: the title row, the tab row, the warnings, the tab's cards, the save bar.
128
+ * @param {any} ui the graphical kit
129
+ * @param {ReturnType<typeof import('../model/frame.mjs').frameOf>} frame
130
+ * @param {{ id: string, key: string, label: string }[]} tabs
131
+ * @param {string} tab the shown tab's id
132
+ * @param {any} actions
133
+ * @param {object[]} content the tab's elements
134
+ */
135
+ export function graphicalFrame(ui, frame, tabs, tab, actions, content) {
136
+ const { status, unsaved } = frame;
137
+ const { Box, Button } = ui;
138
+ const notices = [
139
+ ...(frame.keyHelp ? [graphicalKeyHelp(ui, frame.keyHelp)] : []),
140
+ ...frame.notices.map((notice) =>
141
+ ui.notice(
142
+ notice.tone,
143
+ notice.text,
144
+ notice.action
145
+ ? Button({
146
+ key: notice.action.key,
147
+ label: notice.action.label,
148
+ hotkey: notice.action.hotkey,
149
+ onPress: notice.action.press,
150
+ })
151
+ : null,
152
+ ),
153
+ ),
154
+ ];
155
+ const body = [
156
+ ...(frame.help ? [graphicalHelp(ui, frame.help)] : []),
157
+ ...(frame.profile ? [graphicalProfile(ui, frame.profile)] : []),
158
+ ...content,
159
+ ];
160
+ const bar = graphicalSaveBar(ui, frame.bar);
161
+ const title = Box({
162
+ flexDirection: 'row',
163
+ flexWrap: 'nowrap',
164
+ alignItems: 'center',
165
+ justifyContent: 'space-between',
166
+ gap: 'md',
167
+ children: [
168
+ Box({
169
+ flexShrink: 0,
170
+ children: [ui.text('Router', { size: 'heading', weight: 'semibold' })],
171
+ }),
172
+ Box({
173
+ flexDirection: 'row',
174
+ alignItems: 'center',
175
+ gap: 'xs',
176
+ flexShrink: 1,
177
+ overflow: 'hidden',
178
+ children: [
179
+ ui.text('●', { size: 'footnote', color: ui.color(status.tone) }),
180
+ ui.text(status.text, { size: 'footnote', color: ui.color('muted'), wrap: 'truncate-end' }),
181
+ ],
182
+ }),
183
+ // While routing is unavailable, on and off would change nothing: the status says why instead.
184
+ frame.unavailable
185
+ ? null
186
+ : ui.choice({
187
+ key: 'power',
188
+ options: [
189
+ { value: 'auto', label: 'On', key: 'auto', hotkey: 'o' },
190
+ { value: 'manual', label: 'Off', key: 'manual', hotkey: 'f' },
191
+ ],
192
+ selected: frame.mode,
193
+ onPick: actions.mode,
194
+ }),
195
+ ].filter(Boolean),
196
+ });
197
+ const tabRow = Box({
198
+ flexDirection: 'row',
199
+ flexWrap: 'wrap',
200
+ alignItems: 'center',
201
+ gap: 'sm',
202
+ children: [
203
+ ...tabs.map(({ id, key, label }) =>
204
+ Button({
205
+ key: `tab-${id}`,
206
+ label: `${label}${unsaved[id] ? ' ●' : ''}`,
207
+ hotkey: key,
208
+ variant: tab === id ? 'primary' : 'secondary',
209
+ onPress: () => actions.tab(id),
210
+ }),
211
+ ),
212
+ Button({ key: 'help', label: '?', variant: frame.helpOpen ? 'primary' : 'secondary', onPress: actions.help }),
213
+ ],
214
+ });
215
+ return Box({
216
+ flexDirection: 'column',
217
+ gap: 'md',
218
+ padding: 'md',
219
+ children: [
220
+ title,
221
+ tabRow,
222
+ notices.length ? Box({ key: 'notices', flexDirection: 'column', gap: 'xs', children: notices }) : null,
223
+ Box({ key: 'body', flexDirection: 'column', children: body }),
224
+ bar.length ? Box({ key: 'save-bar', flexDirection: 'column', gap: 'sm', children: bar }) : null,
225
+ ].filter(Boolean),
226
+ });
227
+ }
@@ -0,0 +1,156 @@
1
+ // What the graphical renderers draw with on desktop, VS Code and mobile: the element constructors, text and colour, and
2
+ // section, field, notice, choice and table natively; meter, strip, trend and stat through charts.mjs. Every surface
3
+ // that draws graphically has Svg, Select and Code (Elements['desktop' | 'vscode' | 'mobile']).
4
+ import { tierBars } from '../../display.mjs';
5
+ import { toneColor } from '../tokens.mjs';
6
+
7
+ import { charts } from './charts.mjs';
8
+ import { tierMeter } from './meter.mjs';
9
+
10
+ // The label column of a field: wide enough for the longest label, fixed so every row's control starts together.
11
+ const LABEL_WIDTH = 22;
12
+ // A figure on its own, with its unit: set in the mono face so digits line up. Ids and prose stay proportional.
13
+ const FIGURE = /^[~≈−+-]?\$?\d[\d.,]*(?:[KMB%]|\s?(?:ms|s|min|h|d))?$/;
14
+
15
+ /** @param {string} name a tone */
16
+ const color = (name) => toneColor(/** @type {any} */ (name), 'graphical');
17
+
18
+ /** @param {any} elements */
19
+ export function graphicalKit(elements) {
20
+ const { Box, Text, Button, Select, Svg, Code } = elements;
21
+ const text = (children, style = {}) => Text({ ...style, children });
22
+ const say = (words) => (typeof words === 'string' ? words : words.graphical);
23
+ const caption = (children, extra = {}) => Text({ size: 'footnote', color: color('muted'), ...extra, children });
24
+ const part = (one) =>
25
+ typeof one === 'string' ? Text({ children: one, ...(FIGURE.test(one) ? { mono: true, tabular: true } : {}) }) : one;
26
+ const row = (children, extra = {}) =>
27
+ Box({ flexDirection: 'row', alignItems: 'center', gap: 'sm', ...extra, children: children.filter(Boolean) });
28
+ return {
29
+ Box,
30
+ Button,
31
+ Select,
32
+ Svg,
33
+ Code,
34
+ text,
35
+ say,
36
+ // A tone's colour: a Claude Code theme key, or a mid-lightness hex where no key reads as the tone.
37
+ color,
38
+ // A Select over a control's options in a card's words.
39
+ select: (control) =>
40
+ Select({
41
+ key: control.key,
42
+ value: control.value,
43
+ options: control.options.map(({ value, label }) => ({ value, label: say(label) })),
44
+ onSelect: control.pick,
45
+ }),
46
+ // Muted secondary text, cut at the end unless `extra` says how it wraps.
47
+ muted: (words, extra = {}) => Text({ color: color('muted'), wrap: 'truncate-end', ...extra, children: words }),
48
+ ...charts(elements, { row, caption, color }),
49
+ // Four rising bars as an Svg, lit to the tier, with its alt. Inside a Button, which holds only Text, the tier's
50
+ // bars as glyphs in its colour.
51
+ tierMeter: (name, state, /** @type {{ inButton?: boolean }} */ { inButton = false } = {}) =>
52
+ inButton && name && state === 'lit'
53
+ ? Text({ color: color(`tier:${name}`), children: tierBars(name) })
54
+ : tierMeter(elements, name, state),
55
+ // A bordered card: a quiet footnote title with its hint and action beside it, then the children.
56
+ section: (title, /** @type {{ hint?: string, action?: object }} */ { hint, action } = {}, children = []) =>
57
+ Box({
58
+ flexDirection: 'column',
59
+ borderStyle: 'round',
60
+ borderColor: color('muted'),
61
+ padding: 'md',
62
+ gap: 'sm',
63
+ flexShrink: 1,
64
+ children: [
65
+ row([
66
+ Text({
67
+ size: 'footnote',
68
+ weight: 'semibold',
69
+ color: color('muted'),
70
+ wrap: 'truncate-end',
71
+ children: title,
72
+ }),
73
+ hint ? caption(hint, { tabular: true, wrap: 'truncate-end' }) : null,
74
+ action ?? null,
75
+ ]),
76
+ ...children,
77
+ ],
78
+ }),
79
+ // A fixed label column, then the parts, with one caption line of help under them in the same column.
80
+ field: (label, parts, /** @type {{ help?: string, dim?: boolean }} */ { help, dim = false } = {}) => {
81
+ const labelCell = Box({
82
+ width: LABEL_WIDTH,
83
+ flexShrink: 0,
84
+ children: [Text({ children: label, wrap: 'truncate-end', ...(dim ? { color: color('muted') } : {}) })],
85
+ });
86
+ const value = row(parts.filter((one) => one !== null && one !== '').map(part));
87
+ return help
88
+ ? Box({
89
+ flexDirection: 'column',
90
+ gap: 'xs',
91
+ children: [row([labelCell, value]), row([Box({ width: LABEL_WIDTH, flexShrink: 0 }), caption(help)])],
92
+ })
93
+ : row([labelCell, value]);
94
+ },
95
+ // A warning or note in its tone's colour with its action beside it.
96
+ notice: (name, message, action) =>
97
+ row([Text({ color: color(name), wrap: 'wrap', children: message }), action ?? null], { flexWrap: 'wrap' }),
98
+ // A segmented row of Buttons, wrapping, the chosen ones primary: see `choice`.
99
+ choice: (spec) => choice({ Button, Text, row }, spec),
100
+ // A header row of muted labels, then a row per record, every row's columns lined up: see `table`.
101
+ table: (columns, rows) => table({ Box, row, caption, part }, columns, rows),
102
+ };
103
+ }
104
+
105
+ // A header row of muted labels, then a row per record, every row's columns lined up: a column with a width keeps it, the
106
+ // others share what is left; a right-aligned column ends flush. A record with `span` is one full-width part under the
107
+ // rows before it, such as an open row's note.
108
+ function table({ Box, row, caption, part }, columns, rows) {
109
+ const cell = (column, child) =>
110
+ Box({
111
+ ...(column.width ? { width: column.width, flexShrink: 0 } : { flexGrow: 1, flexShrink: 1, minWidth: 0 }),
112
+ flexDirection: 'row',
113
+ alignItems: 'center',
114
+ justifyContent: column.align === 'right' ? 'flex-end' : 'flex-start',
115
+ overflow: 'hidden',
116
+ children: [child],
117
+ });
118
+ const line = (children) => row(children, { gap: 'md', flexWrap: 'nowrap' });
119
+ return Box({
120
+ flexDirection: 'column',
121
+ gap: 'xs',
122
+ children: [
123
+ line(columns.map((column) => cell(column, caption(column.label, { wrap: 'truncate-end' })))),
124
+ ...rows.map((record) =>
125
+ record.span ? record.span : line(columns.map((column) => cell(column, part(record[column.key] ?? '')))),
126
+ ),
127
+ ],
128
+ });
129
+ }
130
+
131
+ // A segmented row of Buttons, wrapping, the chosen ones primary. An option's own key and hotkey win over the derived key,
132
+ // for controls that keep the key an earlier build gave them. An option with an icon draws it, its label and its hint
133
+ // (muted) inside the Button; the icon may be a list of Text.
134
+ function choice({ Button, Text, row }, { key, options, selected, onPick, gap = 'xs' }) {
135
+ const chosen = Array.isArray(selected) ? selected : [selected];
136
+ return row(
137
+ options.map((option) =>
138
+ Button({
139
+ key: option.key ?? `${key}-${option.value}`,
140
+ ...(option.icon
141
+ ? {
142
+ children: [
143
+ ...[option.icon].flat(),
144
+ Text({ children: option.label }),
145
+ option.hint ? Text({ color: color('muted'), tabular: true, children: option.hint }) : null,
146
+ ].filter(Boolean),
147
+ }
148
+ : { label: option.label }),
149
+ ...(option.hotkey ? { hotkey: option.hotkey } : {}),
150
+ variant: chosen.includes(option.value) ? 'primary' : 'secondary',
151
+ onPress: () => onPick(option.value),
152
+ }),
153
+ ),
154
+ { gap, flexWrap: 'wrap' },
155
+ );
156
+ }
@@ -0,0 +1,25 @@
1
+ // The tier as signal-strength bars for a graphical surface: four rising bars drawn as an Svg.
2
+ import { TIERS } from '../../config.mjs';
3
+ import { GRAPHICAL_PENDING, GRAPHICAL_UNLIT, toneColor } from '../tokens.mjs';
4
+
5
+ const ALT = { lit: (tier) => `Tier: ${tier}`, pending: () => 'Tier: choosing', off: () => 'Tier: off' };
6
+
7
+ /**
8
+ * @param {{ Svg: Function }} elements
9
+ * @param {import('../tokens.mjs').Tier | null} tier
10
+ * @param {'lit' | 'pending' | 'off'} state
11
+ */
12
+ export function tierMeter(elements, tier, state) {
13
+ const lit = state === 'pending' ? 4 : state === 'lit' && tier ? TIERS.indexOf(tier) + 1 : 0;
14
+ const fill =
15
+ state === 'pending' ? GRAPHICAL_PENDING : tier ? toneColor(`tier:${tier}`, 'graphical') : GRAPHICAL_UNLIT;
16
+ const alt = ALT[state](tier);
17
+ const bars = [0, 1, 2, 3]
18
+ .map((i) => {
19
+ const height = 3 * (i + 1);
20
+ return `<rect x="${i * 4}" y="${12 - height}" width="3" height="${height}" rx="0.5" fill="${i < lit ? fill : GRAPHICAL_UNLIT}"/>`;
21
+ })
22
+ .join('');
23
+ const source = `<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 16 12" width="16" height="12">${bars}</svg>`;
24
+ return elements.Svg({ source, alt, width: 16, height: 12 });
25
+ }