@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,390 @@
1
+ // The Now tab's model: what runs next and why, what the plan and the session cost, and how full the context is. The
2
+ // model holds the readings as text, numbers and tones; the terminal draws it as rows and the graphical surfaces as cards.
3
+
4
+ import { ACTIVITIES, resolveRoute, sameRoute, TIERS } from '../../config.mjs';
5
+ import { resetText } from '../../costs.mjs';
6
+ import { decisionLines } from '../../decisions.mjs';
7
+ import {
8
+ API_ESTIMATE,
9
+ activityReading,
10
+ baselineName,
11
+ classifierLabel,
12
+ comparedModel,
13
+ costText,
14
+ diffText,
15
+ EARLY_NOTE,
16
+ formatTokens,
17
+ liveUsage,
18
+ modeLever,
19
+ percent,
20
+ percentPair,
21
+ pinCard,
22
+ pinShort,
23
+ reasonActivity,
24
+ repliesText,
25
+ routeLabel,
26
+ routeName,
27
+ routingModeOf,
28
+ sessionCost,
29
+ sessionUsage,
30
+ shortReason,
31
+ shownConfig,
32
+ signedUsd,
33
+ switchesLost,
34
+ uncomparedText,
35
+ usageMetrics,
36
+ usd,
37
+ whyText,
38
+ } from '../../display.mjs';
39
+ import { limitTone, savingTone } from '../tokens.mjs';
40
+ import { plural, sentence, sinceText } from './format.mjs';
41
+
42
+ const dollars = (value) => (Number.isFinite(value) ? usd(value) : 'not reported');
43
+ const contextSuffix = (metrics) =>
44
+ Number.isFinite(metrics.nextContext)
45
+ ? `~${formatTokens(metrics.nextContext)} / ${formatTokens(metrics.window)}`
46
+ : 'no reading yet';
47
+
48
+ // "Jev 93% ≥ 90% · switch ≈ $0.48": the support for the switch the policy weighed against the bar it set, and the switch
49
+ // cost. Null without a reading.
50
+ function supportText(label, estimate) {
51
+ if (!Number.isFinite(estimate?.threshold)) return null;
52
+ const mass = Number.isFinite(estimate.upgradeMass) ? estimate.upgradeMass : estimate.downgradeMass;
53
+ const cost = Number.isFinite(estimate.taxUsd) ? ` · switch ≈ ${usd(estimate.taxUsd)}` : '';
54
+ if (!Number.isFinite(mass)) return `${label} needs ${percent(estimate.threshold)}${cost}`;
55
+ const [gave, needs] = percentPair(mass, estimate.threshold);
56
+ return `${label} ${gave} ${mass >= estimate.threshold ? '≥' : '<'} ${needs}${cost}`;
57
+ }
58
+
59
+ /**
60
+ * @typedef {object} NextPin one per tier, low to high
61
+ * @property {string} tier
62
+ * @property {import('./format.mjs').Words} route the route it runs, as the terminal's grid and a card name it
63
+ * @property {string | null} support the classifier's support on the last turn
64
+ * @property {string | null} reading a card's: `current` on the tier that runs now, then the support
65
+ *
66
+ * @typedef {object} NextOffModel NEXT TURN with routing off or unavailable: only the model, a note and what pinning needs.
67
+ * @property {'off' | 'unavailable'} state
68
+ * @property {string} label the model and effort that run
69
+ * @property {import('./format.mjs').Words} note
70
+ * @property {import('./format.mjs').Words} pin why pinning is not offered
71
+ *
72
+ * @typedef {object} NextRoutedModel NEXT TURN with routing on.
73
+ * @property {'routed'} state
74
+ * @property {string} label the model and effort that run
75
+ * @property {string | null} tier
76
+ * @property {{ choice: string, isActivity: boolean, share: string | null, other: string | null } | null} reading
77
+ * @property {string | null} phase
78
+ * @property {string | null} why
79
+ * @property {string | null} support
80
+ * @property {string | null} override
81
+ * @property {{ name: string, from: import('./format.mjs').Words, clear: string | null } | null} mode
82
+ * @property {NextPin[]} pins
83
+ * @property {string | null} pendingPin
84
+ * @property {string} firstTurn a card's line before the first routed turn
85
+ * @property {(tier: string) => void} pick pins the next turn; the pending pin again unpins
86
+ *
87
+ * @typedef {NextOffModel | NextRoutedModel} NextModel
88
+ *
89
+ * @typedef {object} Against a part's difference against no routing
90
+ * @property {number} usd
91
+ * @property {string} text
92
+ * @property {import('../tokens.mjs').Tone | null} tone null when it is zero
93
+ * @property {string} versus
94
+ *
95
+ * @typedef {object} SessionModel SESSION: one total with the subagents, the difference, the parts on one scale.
96
+ * @property {string} head
97
+ * @property {number} running
98
+ * @property {boolean} bandDetail
99
+ * @property {() => void} toggleDetail
100
+ * @property {import('./format.mjs').Words} detailToggle the band's second row, on and off
101
+ * @property {boolean} priced
102
+ * @property {import('./format.mjs').Words | null} empty
103
+ * @property {any} strip the session's replies as cells by tier
104
+ * @property {number | null} since
105
+ * @property {string} total
106
+ * @property {string} billing
107
+ * @property {() => void} usage
108
+ * @property {{ usd: number, text: string, tone: import('../tokens.mjs').Tone, versus: string, of: string } | null} diff
109
+ * @property {string | null} note
110
+ * @property {number} scale
111
+ * @property {{ name: string, usd: number, amount: string, against: Against | null }[]} parts
112
+ * @property {[string, number][]} effortMix
113
+ * @property {boolean} lost
114
+ * @property {() => void} policy
115
+ *
116
+ * @typedef {object} ContextModel CONTEXT: the window's fill, the cache reuse, and what is behind Details.
117
+ * @property {number | null} fill
118
+ * @property {import('../tokens.mjs').Tone} fillTone
119
+ * @property {string} suffix
120
+ * @property {import('./format.mjs').Words} empty
121
+ * @property {{ tone: import('../tokens.mjs').Tone, last: { figure: string, words: string } | null, session: { figure: string, words: string } | null, empty: import('./format.mjs').Words }} cache
122
+ * @property {{ open: boolean, toggle: () => void, readings: { terminal: string[], graphical: string }, input: import('./format.mjs').Words, history: number[], tiers: string[], chart: { points: number[], labels: string[], alt: string, tone: import('../tokens.mjs').Tone } | null, range: import('./format.mjs').Words | null, empty: import('./format.mjs').Words, estimatesHead: import('./format.mjs').Words, estimates: [string, string][] }} detail
123
+ *
124
+ * @typedef {object} NowModel The Now tab: what runs next, the plan, the session and the context.
125
+ * @property {NextModel} next
126
+ * @property {string[]} decisions
127
+ * @property {{ label: string, percent: number, tone: import('../tokens.mjs').Tone, reset: string | null }[]} plan
128
+ * @property {SessionModel} session
129
+ * @property {ContextModel} context
130
+ */
131
+ /**
132
+ * @param {import('./frame.mjs').PaneContext} ctx
133
+ * @returns {NowModel}
134
+ */
135
+ export function nowOf({ config, view, usage, actions, now }) {
136
+ const cost = sessionCost(config, view, usage, now);
137
+ return {
138
+ next: nextOf(config, view, actions),
139
+ decisions: view.decisionRows?.length ? decisionLines(view.decisionRows, 5) : [],
140
+ plan: cost.limits.map((limit) => ({
141
+ label: limit.label,
142
+ percent: limit.percent,
143
+ tone: limitTone(limit.percent),
144
+ reset: resetText(limit.resetsAt, now),
145
+ })),
146
+ session: sessionOf(config, view, cost, actions, now),
147
+ context: contextOf(config, view, usage, actions, now),
148
+ };
149
+ }
150
+
151
+ // NEXT TURN. With routing off or unavailable only the model applies: no tier, activity or reason from an earlier turn.
152
+ /** @returns {NextModel} */
153
+ function nextOf(config, view, actions) {
154
+ const unavailable = view.phase === 'unavailable';
155
+ const current = view.selectedModel ?? view.nativeModel;
156
+ if (unavailable)
157
+ return {
158
+ state: 'unavailable',
159
+ label: routeLabel(view.nativeModel, view.nativeEffort),
160
+ note: { terminal: 'routing unavailable · Claude’s model', graphical: 'Routing unavailable · Claude’s model' },
161
+ pin: { terminal: 'needs routing', graphical: 'Pinning needs routing' },
162
+ };
163
+ if (view.mode !== 'auto')
164
+ return {
165
+ state: 'off',
166
+ label: routeLabel(current, view.effort),
167
+ note: { terminal: 'routing off · /model choice', graphical: 'Routing off · /model choice' },
168
+ pin: { terminal: 'needs routing on (o)', graphical: 'Pinning needs routing on' },
169
+ };
170
+ const mode = config.activityRouting;
171
+ const reading = mode === 'off' ? null : activityReading(view);
172
+ const shown = shownConfig(config, view);
173
+ const base = view.tier ? resolveRoute(shown, view.tier) : null;
174
+ const override =
175
+ mode === 'on' && view.activity && base && !sameRoute(resolveRoute(shown, view.tier, view.activity), base);
176
+ const { mode: routingMode, source } = routingModeOf(view);
177
+ const lever = modeLever(config, view);
178
+ return {
179
+ state: 'routed',
180
+ label: routeLabel(current, view.effort),
181
+ tier: view.tier ?? null,
182
+ reading: reading && {
183
+ choice: reading.choice,
184
+ isActivity: ACTIVITIES.includes(reading.choice),
185
+ share: reading.share || null,
186
+ other: reading.others[0] ?? null,
187
+ },
188
+ phase: view.taskPhase ? `phase ${view.taskPhase} · route activity ${view.activity ?? 'base'}` : null,
189
+ why: view.reason ? shortReason(view.reason, reasonActivity(config, view)) : null,
190
+ support: supportText(classifierLabel(config), view.estimate),
191
+ override: override ? `${whyText(config, view)} · tier route ${routeName(shown, base)}` : null,
192
+ mode:
193
+ routingMode !== 'balanced' || source === 'session'
194
+ ? {
195
+ name: routingMode,
196
+ from: {
197
+ terminal: `from ${source}${lever ? ` · ${lever} on this tier` : ''}`,
198
+ graphical: `${sentence(routingMode)} mode from ${source}${lever ? ` · ${lever} on this tier` : ''}`,
199
+ },
200
+ clear: source === 'session' ? '/router mode default clears it' : null,
201
+ }
202
+ : null,
203
+ // One per tier, low to high: the route it runs and the classifier's support on the last turn.
204
+ pins: TIERS.map((tier) => {
205
+ const support = view.probabilities?.[tier];
206
+ return {
207
+ tier,
208
+ // A card names the model's family and the effort, as the Routes cards word them.
209
+ route: {
210
+ terminal: pinShort(config, tier),
211
+ graphical: pinCard(config, tier),
212
+ },
213
+ support: Number.isFinite(support) ? percent(support) : null,
214
+ // A graphical pin's reading: `current` on the tier that runs now, then the support; null with neither.
215
+ reading:
216
+ [tier === view.tier ? 'current' : null, Number.isFinite(support) ? percent(support) : null]
217
+ .filter(Boolean)
218
+ .join(' · ') || null,
219
+ };
220
+ }),
221
+ pendingPin: view.pendingPin ?? null,
222
+ // A card's line before the first routed turn, where the terminal shows none.
223
+ firstTurn: 'No routed turn yet — the first reply sets the route.',
224
+ // A press pins the next turn; pressing the pending pin again unpins it.
225
+ pick: (tier) => (view.pendingPin === tier ? actions.unpin() : actions.pin(tier)),
226
+ };
227
+ }
228
+
229
+ // The session's empty states: no reply carries a price, or no reply yet.
230
+ const UNPRICED_SESSION = { terminal: 'no priced replies: cost unknown', graphical: 'No priced replies: cost unknown' };
231
+ const EMPTY_SESSION = { terminal: 'no replies yet', graphical: 'No routed replies yet' };
232
+
233
+ // The estimate's billing product is context, never evidence of an invoice or measured quota use.
234
+ function billingWords(cost) {
235
+ if (cost.billing === 'plan') return `${API_ESTIMATE} · plan quota, not a charge`;
236
+ if (cost.billing === 'mixed') return `${API_ESTIMATE} · credits ${costText(cost.creditsUsd, cost.billing)}`;
237
+ return `${API_ESTIMATE} · configured rates, not an invoice`;
238
+ }
239
+
240
+ // SESSION: one total with the subagents, the difference against no routing, the main thread and the subagents on one
241
+ // scale, then the replies by tier.
242
+ function sessionOf(config, view, cost, actions, now) {
243
+ const since = liveUsage(view, view.usageSession).since;
244
+ const switches = sessionUsage(view, now).switches;
245
+ const switchCount = switches.tier + switches.activity;
246
+ const head = [
247
+ Number.isFinite(since) ? `since ${sinceText(since, now)}` : null,
248
+ cost.replies ? plural(cost.replies, 'reply', 'replies') : null,
249
+ cost.agents ? plural(cost.agents, 'agent') : null,
250
+ switchCount ? plural(switchCount, 'switch', 'switches') : null,
251
+ ].filter(Boolean);
252
+ const compared = cost.diffUsd !== null;
253
+ const r = cost.readout;
254
+ const priced = Boolean(cost.replies || cost.agents);
255
+ // A part's difference against no routing, and what it is measured against.
256
+ const against = (diff, versus) =>
257
+ diff === null ? null : { usd: diff, text: signedUsd(diff), tone: diff ? savingTone(diff) : null, versus };
258
+ return {
259
+ head: head.join(' · '),
260
+ running: view.subagentsRunning ?? 0,
261
+ bandDetail: Boolean(view.bandDetail),
262
+ toggleDetail: actions.toggleDetail,
263
+ // The band's second row, on and off: the terminal's SESSION line names the band's rows, a card the setting.
264
+ detailToggle: view.bandDetail
265
+ ? { terminal: 'band: 1 row', graphical: 'Hide session row in band' }
266
+ : { terminal: 'band: 2 rows', graphical: 'Show session row in band' },
267
+ // Replies without a list price reach the strip but not the usage record: the tiers still show, the cost cannot.
268
+ priced,
269
+ empty: priced ? null : view.strip?.cells?.length ? UNPRICED_SESSION : EMPTY_SESSION,
270
+ strip: view.strip,
271
+ since,
272
+ total: costText(cost.totalUsd, cost.billing),
273
+ billing: billingWords(cost),
274
+ usage: () => actions.usageFor('session'),
275
+ diff: compared
276
+ ? {
277
+ usd: cost.diffUsd,
278
+ text: diffText(cost.diffUsd, cost.baseUsd),
279
+ tone: savingTone(cost.diffUsd),
280
+ versus: baselineName(view, sessionUsage(view, now), cost),
281
+ of: costText(cost.baseUsd, cost.billing),
282
+ }
283
+ : null,
284
+ note: compared
285
+ ? cost.early
286
+ ? `${repliesText(cost)}: ${EARLY_NOTE}`
287
+ : null
288
+ : cost.effortOnly
289
+ ? 'effort routing on one model: no saving is estimated'
290
+ : cost.uncomparedReplies
291
+ ? `${uncomparedText(cost)}: no saving shown`
292
+ : null,
293
+ scale: Math.max(cost.mainUsd, cost.agentUsd),
294
+ parts: [
295
+ {
296
+ name: 'main',
297
+ usd: cost.mainUsd,
298
+ amount: costText(cost.mainUsd, cost.billing),
299
+ against: against(
300
+ compared && cost.replies ? cost.mainDiff : null,
301
+ comparedModel(config, view, sessionUsage(view, now)),
302
+ ),
303
+ },
304
+ ...(cost.agents
305
+ ? [
306
+ {
307
+ name: 'agents',
308
+ usd: cost.agentUsd,
309
+ amount: costText(cost.agentUsd, cost.billing),
310
+ against: against(compared ? cost.agentDiff : null, 'their picks'),
311
+ },
312
+ ]
313
+ : []),
314
+ ],
315
+ effortMix: cost.effortOnly ? cost.effortMix : [],
316
+ lost: Boolean(cost.comparable && !r.early && switchesLost(r)),
317
+ policy: () => actions.tab('policy'),
318
+ };
319
+ }
320
+
321
+ // Behind Context's Details: Claude's readings of the last reply, and the input per reply as a trend from the oldest
322
+ // reply to the latest, with its range.
323
+ function detailOf(observed, view, history, actions, comparison, metrics) {
324
+ const low = formatTokens(Math.min(...history));
325
+ const high = formatTokens(Math.max(...history));
326
+ const replies = `last ${plural(history.length, 'reply', 'replies')}`;
327
+ const tokens = (value) => formatTokens(value);
328
+ return {
329
+ open: Boolean(view.usageDetail),
330
+ toggle: actions.usageDetail,
331
+ readings: {
332
+ terminal: [
333
+ `context observed ${tokens(observed)} · estimated ${tokens(view.contextTokens)}`,
334
+ `cache read ${tokens(view.cacheRead)} · written ${tokens(view.cacheWrite)} tokens`,
335
+ `output ${tokens(view.outputTokens)} tokens on the last reply`,
336
+ ],
337
+ graphical: `Observed ${tokens(observed)} · estimated ${tokens(view.contextTokens)} · cache read ${tokens(view.cacheRead)} · written ${tokens(view.cacheWrite)} · output ${tokens(view.outputTokens)} tokens`,
338
+ },
339
+ input: { terminal: `INPUT PER REPLY · ${replies} · lowest to highest`, graphical: `Input per reply · ${replies}` },
340
+ // The input per reply and the tier each reply ran on, oldest first.
341
+ history,
342
+ tiers: view.tiers ?? [],
343
+ chart: history.length
344
+ ? {
345
+ points: history,
346
+ labels: ['Oldest', 'Latest'],
347
+ alt: `Input per reply over the ${replies}: ${low} to ${high} tokens`,
348
+ tone: /** @type {import('../tokens.mjs').Tone} */ ('accent'),
349
+ }
350
+ : null,
351
+ range: history.length ? { terminal: `${low} … ${high}`, graphical: `${low} lowest · ${high} highest` } : null,
352
+ empty: { terminal: 'no replies yet', graphical: 'No replies yet' },
353
+ estimatesHead: { terminal: 'ESTIMATES · configured API rates', graphical: 'Estimates · configured API rates' },
354
+ // The estimates the last decision weighed, as label and value.
355
+ estimates: /** @type {([string, string] | null)[]} */ ([
356
+ ['Cache hits saved', dollars(metrics.cacheBenefit)],
357
+ Number.isFinite(view.estimate?.taxUsd) ? ['Switch cost', dollars(view.estimate.taxUsd)] : null,
358
+ ...(comparison
359
+ ? [
360
+ ['Compared tiers', `${comparison.incumbent} → ${comparison.candidate}`],
361
+ ['Next-turn difference', `${signedUsd(comparison.minUsd)} to ${signedUsd(comparison.maxUsd)}`],
362
+ ['Payback', comparison.paybackTurns === null ? 'none projected' : `${comparison.paybackTurns} later turns`],
363
+ ]
364
+ : []),
365
+ ]).filter((one) => one !== null),
366
+ };
367
+ }
368
+
369
+ // CONTEXT: the window's fill on the model that runs next, and the cache reuse of the last reply and of the session.
370
+ function contextOf(config, view, usage, actions, now) {
371
+ const metrics = usageMetrics(config, view, usage);
372
+ const session = sessionUsage(view, now).observed;
373
+ const history = view.history ?? [];
374
+ return {
375
+ fill: metrics.contextBar.percent,
376
+ fillTone: metrics.contextBar.tone,
377
+ suffix: contextSuffix(metrics),
378
+ empty: { terminal: 'no reading yet', graphical: 'No reading yet' },
379
+ // The cache reuse of the last reply and of the session, each a figure and its words.
380
+ cache: {
381
+ tone: metrics.cacheBar.tone,
382
+ last: metrics.cacheBar.percent === null ? null : { figure: `${metrics.cacheBar.percent}%`, words: 'last reply' },
383
+ session: session.inputTokens
384
+ ? { figure: percent(session.cacheReadTokens / session.inputTokens), words: 'session' }
385
+ : null,
386
+ empty: { terminal: 'no reply yet', graphical: 'No reply yet' },
387
+ },
388
+ detail: detailOf(metrics.observed, view, history, actions, view.comparison, metrics),
389
+ };
390
+ }
@@ -0,0 +1,194 @@
1
+ // The Policy tab's model: each control inside the sentence it completes, its default named when the value differs. One
2
+ // Save writes it with the Routes draft.
3
+
4
+ import { defaultsFor, ROUTING_MODES, TIERS, tuningOf } from '../../config.mjs';
5
+ import { classifierLabel, percent, routingModeOf, routingModeText } from '../../display.mjs';
6
+ import { POLICY_ROWS, routingChanges } from './draft.mjs';
7
+ import { sentence, tierLabel } from './format.mjs';
8
+ import { ROUTE_MARKS } from './routes.mjs';
9
+
10
+ const TUNING_CHOICES = {
11
+ timeoutMs: [500, 1000, 1500, 3000, 5000],
12
+ downgradeVotes: [1, 2, 3],
13
+ horizon: [1, 3, 5, 10],
14
+ cashCapUsd: [0.5, 1, 2, 5],
15
+ activityMass: [0.5, 0.6, 0.7, 0.8],
16
+ };
17
+ // What `subagentRouting` does, under the router.json path: it is set in the file, not in the pane.
18
+ const SUBAGENT_LINE = {
19
+ off: 'Subagents keep their own model (subagentRouting off).',
20
+ on: 'Subagents: on. Agents that pin no model get one at spawn, kept for every step.',
21
+ };
22
+ // The same on a card, which names no router.json key.
23
+ const SUBAGENT_CARD = {
24
+ off: 'Subagents keep their own model.',
25
+ on: 'Subagents that pin no model get one at spawn, kept for every step.',
26
+ };
27
+
28
+ // A Select's data over TUNING_CHOICES[key], with a saved value outside them kept as the first option; picking that one
29
+ // changes nothing. `text` is what a terminal without Select shows.
30
+ export function choiceOf(key, value, format, pick) {
31
+ const values = TUNING_CHOICES[key].includes(value) ? TUNING_CHOICES[key] : [value, ...TUNING_CHOICES[key]];
32
+ return {
33
+ key,
34
+ value: String(value),
35
+ text: format(value),
36
+ options: values.map((v) => ({ value: String(v), label: format(v) })),
37
+ pick: (picked) => (TUNING_CHOICES[key].includes(Number(picked)) ? pick(Number(picked)) : undefined),
38
+ };
39
+ }
40
+
41
+ // What the profile's routing mode does, under its control on the Policy tab.
42
+ const MODE_HINT = {
43
+ cost: 'a cheaper model or one effort level less where a turn allows',
44
+ balanced: 'each tier runs its route as configured',
45
+ quality: 'one effort level more, or the tier above, where a turn allows',
46
+ };
47
+ // A sentence a card starts with a capital, as the terminal writes it.
48
+ const sayWords = (words) => ({ terminal: words, graphical: sentence(words) });
49
+ // "default 5 turns" beside a changed value in the terminal, "Default 5 turns" on a card.
50
+ const defaultOf = (value) => ({ terminal: `default ${value}`, graphical: `Default ${value}` });
51
+ // The Policy form's cards on a graphical surface, in order. Switching up holds no control, only its derived line.
52
+ const POLICY_GROUPS = ['Routing mode', 'Switching down', 'Switching up', 'Activities', 'Credits'];
53
+ // Each tuning value's card and help line on a graphical surface; the label is POLICY_ROWS'.
54
+ export const POLICY_FORM = {
55
+ downgradeVotes: { group: 'Switching down', help: 'Agreeing turns before a cheaper model runs' },
56
+ horizon: { group: 'Switching down', help: 'A cache write must pay back within this many turns' },
57
+ activityMass: {
58
+ group: 'Activities',
59
+ help: 'Below this certainty a new task runs its tier’s model; a continuation keeps it',
60
+ },
61
+ cashCapUsd: { group: 'Credits', help: 'The most one cold cache write may cost, on a model that bills credits' },
62
+ };
63
+
64
+ /**
65
+ * @typedef {object} Control a Select's data: its value, options, and what a surface without Select shows
66
+ * @property {string} key
67
+ * @property {string} value
68
+ * @property {string} text
69
+ * @property {{ value: string, label: import('./format.mjs').Words }[]} options
70
+ * @property {(value: string) => void} pick
71
+ *
72
+ * @typedef {object} PolicyField
73
+ * @property {string} key
74
+ * @property {string} group a card's group
75
+ * @property {string} label
76
+ * @property {Control} control
77
+ * @property {boolean} [changed]
78
+ * @property {import('./format.mjs').Words | null} [default] its default, where the value differs
79
+ * @property {import('./format.mjs').Words} [hint]
80
+ * @property {string} [help] a card's help line
81
+ * @property {string} [note]
82
+ * @property {import('./format.mjs').Words | null} [session]
83
+ *
84
+ * @typedef {object} PolicyModel The Policy tab: each control with its words, marks and defaults.
85
+ * @property {import('./routes.mjs').RouteMark} unsaved
86
+ * @property {PolicyField} mode
87
+ * @property {PolicyField} baseline
88
+ * @property {Record<import('./draft.mjs').TuneKey, PolicyField>} tune
89
+ * @property {import('./format.mjs').Words} up
90
+ * @property {string} activitiesHint
91
+ * @property {string} creditsHint
92
+ * @property {{ title: string, fields: PolicyField[], notes: string[], warnings: string[] }[]} groups
93
+ * @property {{ label: string, press: () => void }} reset
94
+ * @property {{ path: string, title: string, copy: { label: import('./format.mjs').Words, press: () => void } | null }} file
95
+ * @property {import('./format.mjs').Words} subagents
96
+ */
97
+ /**
98
+ * @param {import('./frame.mjs').PaneContext} ctx
99
+ * @returns {PolicyModel}
100
+ */
101
+ export function policyOf({ config, view, actions }) {
102
+ const changes = routingChanges(config, view);
103
+ const { draft, tuning, policy } = changes;
104
+ const preset = defaultsFor(config.provider);
105
+ const defaults = tuningOf(preset);
106
+ const { upgradeBase, upgradeSlope } = config.policy;
107
+ const credits = Object.values(config.models).some((model) => model.billing === 'credits');
108
+ const active = routingModeOf(view);
109
+ const creditsHelp = credits
110
+ ? 'on a model that bills credits'
111
+ : 'no model in router.json bills credits, so this has no effect';
112
+ const tune = /** @type {Record<import('./draft.mjs').TuneKey, PolicyField>} */ (
113
+ Object.fromEntries(
114
+ POLICY_ROWS.map(([key, label, format]) => {
115
+ const form = POLICY_FORM[key];
116
+ return [
117
+ key,
118
+ {
119
+ key,
120
+ group: form.group,
121
+ label,
122
+ control: choiceOf(key, tuning[key], format, (value) => actions.tune(key, value)),
123
+ changed: policy.includes(key),
124
+ default: tuning[key] === defaults[key] ? null : defaultOf(format(defaults[key])),
125
+ // A setting with no effect says so in its help line.
126
+ help: key === 'cashCapUsd' && !credits ? sentence(creditsHelp) : form.help,
127
+ },
128
+ ];
129
+ }),
130
+ )
131
+ );
132
+ const mode = {
133
+ key: 'routing-mode',
134
+ group: 'Routing mode',
135
+ label: 'Mode',
136
+ control: {
137
+ key: 'routing-mode',
138
+ value: config.mode,
139
+ text: config.mode,
140
+ options: ROUTING_MODES.map((m) => ({ value: m, label: { terminal: m, graphical: sentence(m) } })),
141
+ pick: (m) => actions.routingMode(m),
142
+ },
143
+ note: 'saved at once',
144
+ hint: { terminal: MODE_HINT[config.mode], graphical: `${sentence(MODE_HINT[config.mode])} · saved at once` },
145
+ // A session or project mode runs instead of the profile's.
146
+ session:
147
+ active.source === 'session' || active.source === 'project'
148
+ ? sayWords(`this session runs ${routingModeText(view)}`)
149
+ : null,
150
+ };
151
+ const baseline = {
152
+ key: 'baseline',
153
+ group: 'Routing mode',
154
+ label: 'Start tier',
155
+ control: {
156
+ key: 'baseline',
157
+ value: draft.baselineTier,
158
+ text: draft.baselineTier,
159
+ options: TIERS.map((tier) => ({ value: tier, label: { terminal: tier, graphical: sentence(tier) } })),
160
+ pick: (tier) => actions.baseline(tier),
161
+ },
162
+ changed: changes.baseline,
163
+ default:
164
+ draft.baselineTier === preset.baselineTier
165
+ ? null
166
+ : { terminal: `default ${preset.baselineTier}`, graphical: `Default ${tierLabel(preset.baselineTier)}` },
167
+ hint: sayWords('when the session’s model is no tier’s model'),
168
+ };
169
+ const up = `needs ${classifierLabel(config)} support of ${percent(upgradeBase)}, up to ${percent(upgradeBase + upgradeSlope)} as the switch costs more`;
170
+ const fields = [mode, baseline, ...Object.values(tune)];
171
+ return {
172
+ unsaved: ROUTE_MARKS.edited,
173
+ mode,
174
+ baseline,
175
+ tune,
176
+ up: sayWords(up),
177
+ activitiesHint: 'else a new task runs its tier’s model; a continuation keeps it',
178
+ creditsHint: creditsHelp,
179
+ groups: POLICY_GROUPS.map((title) => ({
180
+ title,
181
+ fields: fields.filter((field) => field.group === title),
182
+ notes: title === 'Switching up' ? [sayWords(up).graphical] : [],
183
+ // A session or project mode runs instead of the profile's.
184
+ warnings: title === 'Routing mode' && mode.session ? [mode.session.graphical] : [],
185
+ })),
186
+ reset: { label: 'Reset policy to defaults', press: actions.resetPolicy },
187
+ file: {
188
+ path: view.configPath ?? 'profile router.json',
189
+ title: 'Settings file',
190
+ copy: view.configPath ? { label: { terminal: 'copy', graphical: 'Copy path' }, press: actions.copyPath } : null,
191
+ },
192
+ subagents: { terminal: SUBAGENT_LINE[config.subagentRouting], graphical: SUBAGENT_CARD[config.subagentRouting] },
193
+ };
194
+ }