@hexdecimal16/nexo 0.0.0-stage → 0.2.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 (208) hide show
  1. package/LICENSE +75 -0
  2. package/README.md +75 -2
  3. package/cli/src/bin.js +12 -0
  4. package/cli/src/common.js +77 -0
  5. package/cli/src/doctor.js +27 -0
  6. package/cli/src/eval-cases.js +65 -0
  7. package/cli/src/eval.js +67 -0
  8. package/cli/src/init.js +186 -0
  9. package/cli/src/interactive.js +171 -0
  10. package/cli/src/learn.js +178 -0
  11. package/cli/src/main.js +261 -0
  12. package/cli/src/optimize.js +289 -0
  13. package/cli/src/prompter.js +47 -0
  14. package/cli/src/review.js +120 -0
  15. package/cli/src/runtime.js +2 -0
  16. package/cli/src/sessions.js +34 -0
  17. package/cli/src/settings.js +169 -0
  18. package/cli/src/ui.js +112 -0
  19. package/core/src/approval/classifier.js +152 -0
  20. package/core/src/config/load.js +283 -0
  21. package/core/src/config/schema.js +186 -0
  22. package/core/src/cost/admission.js +90 -0
  23. package/core/src/cost/budget.js +67 -0
  24. package/core/src/cost/pricing.js +53 -0
  25. package/core/src/engine/charged-completion.js +79 -0
  26. package/core/src/engine/errors.js +77 -0
  27. package/core/src/engine/mcp.js +11 -0
  28. package/core/src/engine/messages.js +86 -0
  29. package/core/src/engine/prompts.js +32 -0
  30. package/core/src/engine/provider-gate.js +33 -0
  31. package/core/src/engine/recorder.js +61 -0
  32. package/core/src/engine/run.js +1115 -0
  33. package/core/src/engine/semaphore.js +45 -0
  34. package/core/src/engine/spawn-tool.js +119 -0
  35. package/core/src/engine/task-graph.js +153 -0
  36. package/core/src/index.js +32 -0
  37. package/core/src/learn/caller.js +171 -0
  38. package/core/src/learn/context.js +112 -0
  39. package/core/src/learn/embedder.js +216 -0
  40. package/core/src/learn/job.js +196 -0
  41. package/core/src/learn/wiki.js +116 -0
  42. package/core/src/learn/worker.js +141 -0
  43. package/core/src/optimize/adapter.js +250 -0
  44. package/core/src/optimize/climb.js +338 -0
  45. package/core/src/optimize/mine.js +95 -0
  46. package/core/src/optimize/optimize.js +377 -0
  47. package/core/src/optimize/optimizer-run.js +67 -0
  48. package/core/src/optimize/reflect.js +100 -0
  49. package/core/src/optimize/scratchpad-wiki.js +69 -0
  50. package/core/src/providers/claude-p.js +363 -0
  51. package/core/src/providers/kiro-p.js +408 -0
  52. package/core/src/providers/models.js +10 -0
  53. package/core/src/scoring/calibration.js +31 -0
  54. package/core/src/scoring/continuation.js +24 -0
  55. package/core/src/scoring/runner.js +322 -0
  56. package/core/src/scoring/sources.js +88 -0
  57. package/core/src/session/lock.js +88 -0
  58. package/core/src/session/session.js +647 -0
  59. package/core/src/session/shell.js +26 -0
  60. package/core/src/session/transcript.js +86 -0
  61. package/core/src/settings/config-edit.js +472 -0
  62. package/core/src/settings/credentials.js +120 -0
  63. package/core/src/settings/doctor.js +103 -0
  64. package/core/src/settings/settings.js +265 -0
  65. package/mcp/src/hub.js +184 -0
  66. package/mcp/src/index.js +1 -0
  67. package/memory/src/curate.js +121 -0
  68. package/memory/src/index.js +4 -0
  69. package/memory/src/prompts.js +143 -0
  70. package/memory/src/retrieval.js +91 -0
  71. package/memory/src/similarity.js +47 -0
  72. package/optimize/src/engine.js +206 -0
  73. package/optimize/src/index.js +8 -0
  74. package/optimize/src/merge.js +73 -0
  75. package/optimize/src/novelty.js +37 -0
  76. package/optimize/src/pareto.js +83 -0
  77. package/optimize/src/proposer.js +148 -0
  78. package/optimize/src/report.js +107 -0
  79. package/optimize/src/rng.js +34 -0
  80. package/optimize/src/target.js +34 -0
  81. package/package.json +47 -4
  82. package/router/src/effort.js +5 -0
  83. package/router/src/escalation.js +171 -0
  84. package/router/src/index.js +4 -0
  85. package/router/src/registry.js +21 -0
  86. package/router/src/resolve.js +117 -0
  87. package/scorers/src/deterministic.js +194 -0
  88. package/scorers/src/family.js +48 -0
  89. package/scorers/src/index.js +6 -0
  90. package/scorers/src/judge.js +284 -0
  91. package/scorers/src/regex-worker.js +3 -0
  92. package/scorers/src/spec.js +147 -0
  93. package/scorers/src/trajectory.js +22 -0
  94. package/scorers/src/types.js +1 -0
  95. package/sdk/src/index.js +3 -0
  96. package/sdk/src/nexo.js +94 -0
  97. package/sdk/src/runtime.js +39 -0
  98. package/skills/bundled/browser/SKILL.md +57 -0
  99. package/skills/bundled/wiki/SKILL.md +73 -0
  100. package/skills/src/frontmatter.js +25 -0
  101. package/skills/src/index.js +3 -0
  102. package/skills/src/load-skill-tool.js +41 -0
  103. package/skills/src/loader.js +95 -0
  104. package/store/src/artifacts.js +124 -0
  105. package/store/src/budget-ledger.js +18 -0
  106. package/store/src/cost-report.js +46 -0
  107. package/store/src/cursor.js +35 -0
  108. package/store/src/db.js +83 -0
  109. package/store/src/errors.js +9 -0
  110. package/store/src/eval-cases.js +255 -0
  111. package/store/src/feedback.js +154 -0
  112. package/store/src/goldens.js +61 -0
  113. package/store/src/ids.js +6 -0
  114. package/store/src/index.js +25 -0
  115. package/store/src/judge-calibration.js +182 -0
  116. package/store/src/learn-jobs.js +145 -0
  117. package/store/src/memories.js +261 -0
  118. package/store/src/migrations/001_init.sql +81 -0
  119. package/store/src/migrations/002_feedback.sql +9 -0
  120. package/store/src/migrations/003_sessions.sql +19 -0
  121. package/store/src/migrations/004_scoring.sql +22 -0
  122. package/store/src/migrations/005_judge_calibration.sql +27 -0
  123. package/store/src/migrations/006_learning.sql +77 -0
  124. package/store/src/migrations/007_optimize.sql +55 -0
  125. package/store/src/migrations/008_mined_cases_and_climb.sql +46 -0
  126. package/store/src/mine.js +51 -0
  127. package/store/src/optim.js +291 -0
  128. package/store/src/paths.js +22 -0
  129. package/store/src/playbooks.js +199 -0
  130. package/store/src/reindex.js +143 -0
  131. package/store/src/run-dir.js +151 -0
  132. package/store/src/runs.js +310 -0
  133. package/store/src/scores.js +92 -0
  134. package/store/src/sessions.js +304 -0
  135. package/store/src/span-tree.js +98 -0
  136. package/store/src/spans.js +84 -0
  137. package/store/src/sql.js +13 -0
  138. package/store/src/workspace-copy.js +80 -0
  139. package/telemetry/src/errors.js +32 -0
  140. package/telemetry/src/index.js +3 -0
  141. package/telemetry/src/logger.js +39 -0
  142. package/telemetry/src/redact.js +106 -0
  143. package/tools/src/builtin.js +269 -0
  144. package/tools/src/change-tracker.js +57 -0
  145. package/tools/src/confine.js +101 -0
  146. package/tools/src/index.js +7 -0
  147. package/tools/src/leases.js +57 -0
  148. package/tools/src/policy.js +162 -0
  149. package/tools/src/read-only.js +338 -0
  150. package/tools/src/session-rules.js +140 -0
  151. package/tui/src/app.js +948 -0
  152. package/tui/src/approvals.js +96 -0
  153. package/tui/src/commands.js +38 -0
  154. package/tui/src/components.js +248 -0
  155. package/tui/src/index.js +5 -0
  156. package/tui/src/picker.js +78 -0
  157. package/tui/src/session-picker.js +100 -0
  158. package/tui/src/settings-screen.js +346 -0
  159. package/tui/src/text.js +70 -0
  160. package/tui/src/theme.js +44 -0
  161. package/web/public/cost.html +25 -0
  162. package/web/public/fonts/GeistMono-400.woff2 +0 -0
  163. package/web/public/fonts/GeistMono-600.woff2 +0 -0
  164. package/web/public/fonts/InstrumentSans-400.woff2 +0 -0
  165. package/web/public/fonts/InstrumentSans-600.woff2 +0 -0
  166. package/web/public/index.html +39 -0
  167. package/web/public/judge.html +21 -0
  168. package/web/public/learning.html +46 -0
  169. package/web/public/lib/api-types.ts +616 -0
  170. package/web/public/lib/common-view.ts +47 -0
  171. package/web/public/lib/cost-view.ts +35 -0
  172. package/web/public/lib/files-view.ts +90 -0
  173. package/web/public/lib/format.ts +35 -0
  174. package/web/public/lib/html.ts +51 -0
  175. package/web/public/lib/judge-view.ts +62 -0
  176. package/web/public/lib/learning-view.ts +102 -0
  177. package/web/public/lib/optim-view.ts +148 -0
  178. package/web/public/lib/pager.ts +56 -0
  179. package/web/public/lib/poller.ts +79 -0
  180. package/web/public/lib/run-view.ts +61 -0
  181. package/web/public/lib/runs-view.ts +87 -0
  182. package/web/public/lib/score-view.ts +94 -0
  183. package/web/public/lib/sessions-view.ts +28 -0
  184. package/web/public/lib/span-view.ts +90 -0
  185. package/web/public/lib/theme.ts +60 -0
  186. package/web/public/lib/timeline.ts +97 -0
  187. package/web/public/lib/wikis-view.ts +257 -0
  188. package/web/public/optim.html +30 -0
  189. package/web/public/pages/api.ts +60 -0
  190. package/web/public/pages/cost.ts +36 -0
  191. package/web/public/pages/judge.ts +15 -0
  192. package/web/public/pages/learning.ts +92 -0
  193. package/web/public/pages/optim.ts +68 -0
  194. package/web/public/pages/paging.ts +18 -0
  195. package/web/public/pages/run.ts +221 -0
  196. package/web/public/pages/runs.ts +91 -0
  197. package/web/public/pages/sessions.ts +25 -0
  198. package/web/public/pages/wikis.ts +103 -0
  199. package/web/public/run.html +36 -0
  200. package/web/public/sessions.html +28 -0
  201. package/web/public/style.css +288 -0
  202. package/web/public/wikis.html +25 -0
  203. package/web/src/api.js +682 -0
  204. package/web/src/http-errors.js +60 -0
  205. package/web/src/index.js +5 -0
  206. package/web/src/server.js +292 -0
  207. package/web/src/static.js +86 -0
  208. package/web/src/strip.js +22 -0
@@ -0,0 +1,616 @@
1
+ // JSON shapes of the nexo web API. The server annotates its responses with these types, so a store change that
2
+ // breaks the browser fails `npm run typecheck`. This file holds types only and is shared by browser and server.
3
+
4
+ export type RunStatus = "running" | "succeeded" | "failed" | "aborted" | "budget_exceeded";
5
+ export type Verdict = "done" | "not_done";
6
+ export type SpanStatus = "running" | "ok" | "error";
7
+ export type CostDimension = "model" | "tier" | "day" | "run" | "skill";
8
+
9
+ export interface ApiErrorBody {
10
+ code: string;
11
+ message: string;
12
+ retryable: boolean;
13
+ hint?: string | null;
14
+ context?: Record<string, unknown>;
15
+ }
16
+
17
+ export interface RunSummary {
18
+ id: string;
19
+ parentRunId: string | null;
20
+ rootRunId: string;
21
+ instruction: string;
22
+ skill: string | null;
23
+ status: RunStatus;
24
+ modelFinal: string | null;
25
+ tierFinal: string | null;
26
+ startedAt: string;
27
+ endedAt: string | null;
28
+ costUsd: number;
29
+ costUnknown: boolean;
30
+ tokensIn: number;
31
+ tokensOut: number;
32
+ childCount: number;
33
+ verdict: Verdict | null;
34
+ error: ApiErrorBody | null;
35
+ /** Session link of a session turn; null for other runs. */
36
+ sessionId: string | null;
37
+ turnIndex: number | null;
38
+ sessionTitle: string | null;
39
+ /** The optimization a rollout belongs to; null for ordinary runs (which are the only ones the runs list shows). */
40
+ optimRunId: string | null;
41
+ /** The latest scoring round: mean value and all-passed verdict of the scorers that answered; null when never scored. */
42
+ score: RunScore | null;
43
+ }
44
+
45
+ export interface RunScore {
46
+ value: number | null;
47
+ passed: boolean | null;
48
+ scorers: number;
49
+ failedScorers: number;
50
+ }
51
+
52
+ export interface ScoreCriterion {
53
+ name: string;
54
+ passed: boolean;
55
+ note: string;
56
+ }
57
+
58
+ /** One scorer result of one scoring round (round 0 first; each S2 continuation adds a round). */
59
+ export interface Score {
60
+ id: string;
61
+ runId: string;
62
+ round: number;
63
+ scorerKind: "deterministic" | "judge" | "human";
64
+ scorerType: string;
65
+ scorerName: string;
66
+ status: "ok" | "failed";
67
+ value: number | null;
68
+ passed: boolean | null;
69
+ rationale: string;
70
+ criteria: ScoreCriterion[] | null;
71
+ details: Record<string, unknown>;
72
+ error: ApiErrorBody | null;
73
+ model: string | null;
74
+ costUsd: number;
75
+ costUnknown: boolean;
76
+ createdAt: string;
77
+ }
78
+
79
+ /** An `escalation` span of the run: a trigger that switched to S2, or was suppressed. */
80
+ export interface Escalation {
81
+ spanId: string;
82
+ at: string;
83
+ trigger: string;
84
+ reason: string;
85
+ phase: string;
86
+ applied: boolean;
87
+ blockedBy: string | null;
88
+ /** Why a blocked trigger was suppressed. */
89
+ blockedReason: string | null;
90
+ from: string | null;
91
+ to: string | null;
92
+ /** Set when the S2 continuation failed and the previous answer was kept. */
93
+ continuationError: { code: string; message: string } | null;
94
+ }
95
+
96
+ export interface RunListResponse {
97
+ runs: RunSummary[];
98
+ nextCursor: string | null;
99
+ /** Runs matching the filters across every page. */
100
+ total: number;
101
+ }
102
+
103
+ export interface SessionListItem {
104
+ id: string;
105
+ title: string;
106
+ status: "active" | "closed";
107
+ turns: number;
108
+ costUsd: number;
109
+ budgetUsd: number;
110
+ createdAt: string;
111
+ updatedAt: string;
112
+ /** The newest turn; null before the first one is indexed. */
113
+ lastTurn: { runId: string; status: RunStatus; startedAt: string } | null;
114
+ /** Finished turns without a human verdict. */
115
+ unreviewedTurns: number;
116
+ }
117
+
118
+ export interface SessionListResponse {
119
+ sessions: SessionListItem[];
120
+ /** Cursor of the next page, or null on the last one. */
121
+ nextCursor: string | null;
122
+ total: number;
123
+ }
124
+
125
+ export interface ModelInfo {
126
+ provider: string;
127
+ id: string;
128
+ effort: string;
129
+ source: string;
130
+ role: string | null;
131
+ }
132
+
133
+ export interface HumanVerdict {
134
+ verdict: Verdict;
135
+ comment: string;
136
+ createdAt: string;
137
+ }
138
+
139
+ export interface RunJsonView {
140
+ id: string;
141
+ instruction: string;
142
+ skill: string | null;
143
+ status: RunStatus;
144
+ model: ModelInfo | null;
145
+ startedAt: string;
146
+ endedAt: string | null;
147
+ costUsd: number;
148
+ costUnknown: boolean;
149
+ tokensIn: number;
150
+ tokensOut: number;
151
+ output: string;
152
+ error: ApiErrorBody | null;
153
+ workspace: string;
154
+ humanVerdict?: HumanVerdict | null;
155
+ }
156
+
157
+ export interface Feedback {
158
+ id: string;
159
+ runId: string;
160
+ verdict: Verdict;
161
+ comment: string;
162
+ createdAt: string;
163
+ }
164
+
165
+ export interface RunDetailResponse {
166
+ run: RunSummary;
167
+ runJson: RunJsonView | null;
168
+ dirMissing: boolean;
169
+ children: RunSummary[];
170
+ feedback: Feedback[];
171
+ /** Latest verdict of each child run that has one, keyed by child run id. */
172
+ childFeedback: Record<string, Feedback>;
173
+ /** Every score of the run, by round. */
174
+ scores: Score[];
175
+ escalations: Escalation[];
176
+ /** True when the latest judge verdict and the latest human verdict disagree. */
177
+ judgeDisagrees: boolean;
178
+ }
179
+
180
+ export interface Span {
181
+ id: string;
182
+ runId: string;
183
+ parentSpanId: string | null;
184
+ kind: string;
185
+ name: string;
186
+ status: SpanStatus;
187
+ startedAt: string;
188
+ endedAt: string | null;
189
+ queuedMs: number | null;
190
+ model: string | null;
191
+ provider: string | null;
192
+ tier: string | null;
193
+ effort: string | null;
194
+ modelSource: string | null;
195
+ tokensIn: number;
196
+ tokensOut: number;
197
+ cacheRead: number;
198
+ cacheWrite: number;
199
+ costUsd: number;
200
+ costUnknown: boolean;
201
+ payloadRef: string | null;
202
+ attrs: Record<string, unknown>;
203
+ }
204
+
205
+ export interface SpanNode {
206
+ span: Span;
207
+ attrsTruncated: boolean;
208
+ children: SpanNode[];
209
+ }
210
+
211
+ export interface SpanTreeResponse {
212
+ roots: SpanNode[];
213
+ total: number;
214
+ truncated: boolean;
215
+ }
216
+
217
+ export interface SpanResponse {
218
+ span: Span;
219
+ }
220
+
221
+ /** `symlink` entries are reported without being followed; `other` is a FIFO, socket or device, which is never served. */
222
+ export interface FileEntry {
223
+ name: string;
224
+ path: string;
225
+ kind: "file" | "dir" | "symlink" | "other";
226
+ size: number;
227
+ }
228
+
229
+ export interface DirListing {
230
+ path: string;
231
+ entries: FileEntry[];
232
+ }
233
+
234
+ export interface FeedbackRequest {
235
+ verdict: Verdict;
236
+ comment: string;
237
+ }
238
+
239
+ export interface FeedbackResponse {
240
+ feedback: Feedback;
241
+ }
242
+
243
+ export interface CostRow {
244
+ key: string;
245
+ costUsd: number;
246
+ calls: number;
247
+ unknownCalls: number;
248
+ }
249
+
250
+ export interface CostResponse {
251
+ by: CostDimension;
252
+ since: string;
253
+ rows: CostRow[];
254
+ totalUsd: number;
255
+ unknownCalls: number;
256
+ }
257
+
258
+ /** Set when the server refuses writes because the nexo config could not be loaded. */
259
+ export interface ReadOnlyInfo {
260
+ message: string;
261
+ hint: string | null;
262
+ }
263
+
264
+ export interface MetaResponse {
265
+ runStatuses: RunStatus[];
266
+ costDimensions: CostDimension[];
267
+ readOnly: ReadOnlyInfo | null;
268
+ }
269
+
270
+ export interface ConfusionMatrix {
271
+ bothPass: number;
272
+ judgePassHumanFail: number;
273
+ judgeFailHumanPass: number;
274
+ bothFail: number;
275
+ }
276
+
277
+ export interface Calibration {
278
+ id: string;
279
+ judgeKey: string;
280
+ cases: number;
281
+ agreements: number;
282
+ accuracy: number | null;
283
+ kappa: number | null;
284
+ matrix: ConfusionMatrix;
285
+ createdAt: string;
286
+ }
287
+
288
+ export interface Disagreement {
289
+ runId: string;
290
+ instruction: string;
291
+ judgePassed: boolean;
292
+ verdict: Verdict;
293
+ comment: string;
294
+ }
295
+
296
+ export interface JudgeCalibrationResponse {
297
+ /** The configured judge (`models.judge` keys joined with `+`); null without a judge or a config. */
298
+ judgeKey: string | null;
299
+ /** Same-family warnings for the configured judge. */
300
+ warnings: string[];
301
+ /** Agreement on the current verdicts, computed for this request (not stored). */
302
+ current: { cases: number; agreements: number; accuracy: number | null; kappa: number | null; matrix: ConfusionMatrix } | null;
303
+ /** Stored `nexo eval judge` results for the configured judge (all judges without one), newest first. */
304
+ history: Calibration[];
305
+ disagreements: Disagreement[];
306
+ }
307
+ export type MemoryType = "fact" | "preference" | "lesson" | "workflow";
308
+ export type MemorySource = "ace" | "human" | "user";
309
+
310
+ export interface Memory {
311
+ id: string;
312
+ scope: string;
313
+ type: MemoryType;
314
+ content: string;
315
+ importance: number;
316
+ source: MemorySource;
317
+ sourceRunId: string | null;
318
+ supersededBy: string | null;
319
+ retiredAt: string | null;
320
+ createdAt: string;
321
+ lastUsedAt: string | null;
322
+ }
323
+
324
+ export interface MemoryListResponse {
325
+ memories: Memory[];
326
+ nextCursor: string | null;
327
+ total: number;
328
+ }
329
+
330
+ export interface MemoryDetailResponse {
331
+ memory: Memory;
332
+ /** The memories this one replaced, newest first. */
333
+ history: Memory[];
334
+ }
335
+
336
+ export interface MemoryRetireResponse {
337
+ memory: Memory;
338
+ }
339
+
340
+ export interface PlaybookSummary {
341
+ skill: string;
342
+ activeItems: number;
343
+ version: number | null;
344
+ origin: "manual" | "ace" | "gepa" | null;
345
+ }
346
+
347
+ export interface PlaybookListResponse {
348
+ playbooks: PlaybookSummary[];
349
+ }
350
+
351
+ export interface PlaybookHistoryEntry {
352
+ id: string;
353
+ itemId: string;
354
+ action: "add" | "update" | "retire" | "helpful" | "harmful" | "prune";
355
+ content: string | null;
356
+ actor: "ace" | "human" | "user";
357
+ runId: string | null;
358
+ createdAt: string;
359
+ }
360
+
361
+ export interface PlaybookItem {
362
+ id: string;
363
+ skill: string;
364
+ key: string;
365
+ content: string;
366
+ helpful: number;
367
+ harmful: number;
368
+ source: "ace" | "human";
369
+ status: "active" | "retired";
370
+ sourceRunId: string | null;
371
+ createdAt: string;
372
+ updatedAt: string;
373
+ history: PlaybookHistoryEntry[];
374
+ }
375
+
376
+ export interface PlaybookVersion {
377
+ id: string;
378
+ version: number;
379
+ origin: "manual" | "ace" | "gepa";
380
+ status: "active" | "candidate" | "retired";
381
+ createdAt: string;
382
+ }
383
+
384
+ export interface PlaybookResponse {
385
+ skill: string;
386
+ items: PlaybookItem[];
387
+ /** Every artifact version, newest first. */
388
+ versions: PlaybookVersion[];
389
+ }
390
+
391
+ export interface PlaybookRetireResponse {
392
+ item: PlaybookItem;
393
+ version: PlaybookVersion | null;
394
+ }
395
+
396
+ export type LearnJobStatus = "pending" | "running" | "succeeded" | "failed";
397
+
398
+ export interface LearnJob {
399
+ id: string;
400
+ runId: string;
401
+ kind: string;
402
+ trigger: "run_end" | "feedback";
403
+ status: LearnJobStatus;
404
+ attempts: number;
405
+ lastError: ApiErrorBody | null;
406
+ createdAt: string;
407
+ updatedAt: string;
408
+ }
409
+
410
+ export interface LearnJobsResponse {
411
+ counts: Record<LearnJobStatus, number>;
412
+ jobs: LearnJob[];
413
+ nextCursor: string | null;
414
+ /** Jobs matching the status filter across every page. */
415
+ total: number;
416
+ }
417
+
418
+ export type OptimStatus = "running" | "succeeded" | "failed" | "aborted";
419
+
420
+ /** One candidate's result on one eval case. */
421
+ export interface CaseScore {
422
+ quality: number;
423
+ costUsd: number;
424
+ }
425
+
426
+ export interface OptimRun {
427
+ id: string;
428
+ target: string;
429
+ status: OptimStatus;
430
+ stopReason: string | null;
431
+ budgetUsd: number;
432
+ budgetRollouts: number | null;
433
+ spentUsd: number;
434
+ rollouts: number;
435
+ merge: boolean;
436
+ seed: number;
437
+ baseArtifactId: string;
438
+ bestArtifactId: string | null;
439
+ dirPath: string;
440
+ reportRef: string | null;
441
+ judgeKey: string | null;
442
+ judgeOnly: boolean | null;
443
+ holdoutBefore: number | null;
444
+ holdoutAfter: number | null;
445
+ promotion: "approved" | "rolled_back" | null;
446
+ replacedArtifactId: string | null;
447
+ promotedAt: string | null;
448
+ pid: number | null;
449
+ error: ApiErrorBody | null;
450
+ createdAt: string;
451
+ endedAt: string | null;
452
+ mode: "gepa" | "climb";
453
+ caseId: string | null;
454
+ climbOutcome: "improved" | "golden_raised" | "no_signal" | "not_improved" | "guard_regressed" | null;
455
+ }
456
+
457
+ /** An optimization with the version numbers of its base and best candidate. */
458
+ export interface OptimRunItem extends OptimRun {
459
+ baseVersion: number | null;
460
+ bestVersion: number | null;
461
+ }
462
+
463
+ export interface OptimListResponse {
464
+ runs: OptimRunItem[];
465
+ nextCursor: string | null;
466
+ total: number;
467
+ }
468
+
469
+ /** A reflection's testable claim and how its minibatch rollouts bore it out. */
470
+ export interface OptimPrediction {
471
+ rootCause: string;
472
+ fixes: number[];
473
+ atRisk: number[];
474
+ fixesPredicted: number;
475
+ fixesHit: number;
476
+ atRiskPredicted: number;
477
+ atRiskHit: number;
478
+ unpredictedRegressions: number;
479
+ }
480
+
481
+ export interface OptimCandidate {
482
+ id: string;
483
+ optimRunId: string;
484
+ artifactId: string;
485
+ parentIds: string[];
486
+ iteration: number;
487
+ origin: "seed" | "reflect" | "merge";
488
+ component: string | null;
489
+ minibatch: { caseIds: string[]; parent: CaseScore[]; child: CaseScore[]; rationale?: string; prediction?: OptimPrediction } | null;
490
+ perCase: Record<string, CaseScore>;
491
+ meanScore: number | null;
492
+ meanCostUsd: number | null;
493
+ accepted: boolean;
494
+ createdAt: string;
495
+ /** The candidate's artifact version and status; null when the artifact is missing. */
496
+ version: number | null;
497
+ artifactStatus: "active" | "candidate" | "retired" | null;
498
+ }
499
+
500
+ export interface DiffLine {
501
+ op: "same" | "add" | "del";
502
+ text: string;
503
+ }
504
+
505
+ export interface OptimReportCase {
506
+ caseId: string;
507
+ input: string;
508
+ before: CaseScore;
509
+ after: CaseScore;
510
+ outcome: "win" | "loss" | "tie";
511
+ }
512
+
513
+ /** report.json of an optimization (spec §8.2.5): the holdout split only. */
514
+ export interface OptimReport {
515
+ optimRunId: string;
516
+ target: string;
517
+ baseArtifactId: string;
518
+ bestArtifactId: string;
519
+ improved: boolean;
520
+ holdout: { cases: OptimReportCase[]; before: CaseScore; after: CaseScore; wins: number; losses: number; ties: number };
521
+ diff: DiffLine[];
522
+ lineage: {
523
+ candidateId: string;
524
+ artifactId: string;
525
+ parentIds: string[];
526
+ iteration: number;
527
+ origin: "seed" | "reflect" | "merge";
528
+ component: string | null;
529
+ accepted: boolean;
530
+ meanScore: number | null;
531
+ meanCostUsd: number | null;
532
+ minibatch: { parent: number; child: number; rationale?: string; prediction?: OptimPrediction } | null;
533
+ }[];
534
+ evidence: { judgeOnly: boolean; humanScored: boolean; judgeKey: string | null; kappa: number | null; minJudgeKappa: number };
535
+ stopReason: string;
536
+ spentUsd: number;
537
+ rollouts: number;
538
+ iterations: number;
539
+ merges: number;
540
+ mergeNote: string | null;
541
+ climb?: { caseId: string; guardIds: string[]; outcome: string; critique: string | null; comparisons: { label: string; winner: "A" | "B" | "tie" }[] };
542
+ createdAt: string;
543
+ }
544
+
545
+ /** Whether the best candidate may be approved now, and why not. */
546
+ export interface PromotionState {
547
+ allowed: boolean;
548
+ error: ApiErrorBody | null;
549
+ kappa: number | null;
550
+ }
551
+
552
+ export interface OptimDetailResponse {
553
+ run: OptimRunItem;
554
+ candidates: OptimCandidate[];
555
+ /** null while running, after an abort or failure, or when report.json is missing or unreadable. */
556
+ report: OptimReport | null;
557
+ promotion: PromotionState;
558
+ }
559
+
560
+ export interface OptimApproveResponse {
561
+ promoted: PlaybookVersion;
562
+ replaced: PlaybookVersion | null;
563
+ run: OptimRunItem;
564
+ }
565
+
566
+ export interface EvalCaseItem {
567
+ id: string;
568
+ target: string;
569
+ input: string;
570
+ origin: "run" | "manual" | "mined";
571
+ status: "proposed" | "active" | "dismissed";
572
+ /** Runs in the mined cluster; 0 for cases that were not mined. */
573
+ clusterSize: number;
574
+ createdAt: string;
575
+ }
576
+
577
+ export interface EvalCasesResponse {
578
+ cases: EvalCaseItem[];
579
+ }
580
+
581
+ export interface EvalCaseResponse {
582
+ case: EvalCaseItem;
583
+ }
584
+
585
+ export interface WikiItem {
586
+ name: string;
587
+ pageCount: number;
588
+ modifiedAt: string;
589
+ }
590
+
591
+ export interface WikiListResponse {
592
+ wikis: WikiItem[];
593
+ }
594
+
595
+ export interface WikiPageItem {
596
+ path: string;
597
+ slug: string;
598
+ summary?: string;
599
+ folder?: string;
600
+ size: number;
601
+ modifiedAt: string;
602
+ }
603
+
604
+ export interface WikiPagesResponse {
605
+ wiki: string;
606
+ pages: WikiPageItem[];
607
+ }
608
+
609
+ export interface WikiPageResponse {
610
+ wiki: string;
611
+ path: string;
612
+ content: string;
613
+ summary?: string;
614
+ size: number;
615
+ modifiedAt: string;
616
+ }
@@ -0,0 +1,47 @@
1
+ import type { ApiErrorBody, Verdict } from "./api-types.ts";
2
+ import { html, type SafeHtml } from "./html.ts";
3
+
4
+ export function runLink(id: string): string {
5
+ return `/run.html?id=${encodeURIComponent(id)}`;
6
+ }
7
+
8
+ /** The runs list filtered to one session's turns. */
9
+ export function sessionLink(sessionId: string): string {
10
+ return `/?session=${encodeURIComponent(sessionId)}`;
11
+ }
12
+
13
+ const STATUS_GLYPH = new Map([
14
+ ["succeeded", "✓"],
15
+ ["ok", "✓"],
16
+ ["running", "◌"],
17
+ ["failed", "✕"],
18
+ ["error", "✕"],
19
+ ["aborted", "✕"],
20
+ ["budget_exceeded", "✕"],
21
+ ]);
22
+
23
+ /** A run or span status badge. The class is `status-<status>` for plain lowercase names (style.css colours the known ones) and `status-other` for anything else. */
24
+ export function statusBadge(status: string): SafeHtml {
25
+ const cls = /^[a-z_]{1,32}$/.test(status) ? status : "other";
26
+ const glyph = STATUS_GLYPH.get(cls) ?? "·";
27
+ return html`<span class="badge status-${cls}"><span class="glyph" aria-hidden="true">${glyph}</span> ${status.replace("_", " ")}</span>`;
28
+ }
29
+
30
+ export function verdictBadge(verdict: Verdict | null): SafeHtml {
31
+ if (verdict === null) return html`<span class="badge verdict-none"><span class="glyph" aria-hidden="true">–</span> unreviewed</span>`;
32
+ const glyph = verdict === "done" ? "✓" : "✕";
33
+ return html`<span class="badge verdict-${verdict}"><span class="glyph" aria-hidden="true">${glyph}</span> ${verdict === "done" ? "done" : "not done"}</span>`;
34
+ }
35
+
36
+ /** The API error envelope as a message block (code, message, hint). */
37
+ export function renderError(error: ApiErrorBody): SafeHtml {
38
+ return html`<div class="error" role="alert"><strong>${error.code}</strong> ${error.message}${error.hint ? html`<div class="hint">${error.hint}</div>` : ""}</div>`;
39
+ }
40
+
41
+ /** Spine state of a run row or card; style.css colours the left rail from it. */
42
+ export function stateClass(status: string): string {
43
+ if (status === "succeeded" || status === "ok") return "state-ok";
44
+ if (status === "running") return "state-running";
45
+ if (["failed", "error", "aborted", "budget_exceeded"].includes(status)) return "state-bad";
46
+ return "state-none";
47
+ }
@@ -0,0 +1,35 @@
1
+ import type { CostDimension, CostResponse } from "./api-types.ts";
2
+ import { formatUsd } from "./format.ts";
3
+ import { html, type SafeHtml } from "./html.ts";
4
+
5
+ /** API path for a cost report; an empty `by` or `since` leaves the server default (day, last 30 days). */
6
+ export function costQuery(by: string, since: string): string {
7
+ const params = new URLSearchParams();
8
+ if (by) params.set("by", by);
9
+ if (since) params.set("since", since);
10
+ const query = params.toString();
11
+ return query ? `/api/costs?${query}` : "/api/costs";
12
+ }
13
+
14
+ /** `<option>`s for the group-by select, from the dimensions in `/api/meta`. */
15
+ export function renderDimensionOptions(dimensions: readonly CostDimension[], selected: string): SafeHtml {
16
+ return html`${dimensions.map((d) => html`<option value="${d}"${d === selected ? html` selected` : ""}>${d}</option>`)}`;
17
+ }
18
+
19
+ export function renderCostTable(report: CostResponse): SafeHtml {
20
+ const max = Math.max(0, ...report.rows.map((r) => r.costUsd));
21
+ return html`${report.unknownCalls > 0 ? html`<p class="warn" role="alert">${report.unknownCalls} LLM call${report.unknownCalls === 1 ? " has" : "s have"} no price. Totals leave them out; add pricingOverrides to your nexo config to price them.</p>` : ""}
22
+ <table class="costs">
23
+ <thead><tr><th>${report.by}</th><th class="num">cost</th><th></th><th class="num">calls</th><th class="num">unpriced</th></tr></thead>
24
+ <tbody>${report.rows.length === 0 ? html`<tr><td colspan="5" class="empty">No LLM calls since ${report.since}.</td></tr>` : ""}${report.rows.map(
25
+ (row) => html`<tr${row.unknownCalls ? html` class="warn"` : ""}>
26
+ <td class="mono">${row.key}</td>
27
+ <td class="num">${formatUsd(row.costUsd)}</td>
28
+ <td class="bar-cell"><svg class="cost-bar" viewBox="0 0 100 6" preserveAspectRatio="none" aria-hidden="true"><rect x="0" y="0" height="6" width="${max > 0 ? ((row.costUsd / max) * 100).toFixed(1) : "0"}"></rect></svg></td>
29
+ <td class="num">${row.calls}</td>
30
+ <td class="num">${row.unknownCalls || ""}</td>
31
+ </tr>`,
32
+ )}</tbody>
33
+ <tfoot><tr><th>total since ${report.since}</th><th class="num">${formatUsd(report.totalUsd, report.unknownCalls > 0)}</th><th></th><th></th><th class="num">${report.unknownCalls || ""}</th></tr></tfoot>
34
+ </table>`;
35
+ }