@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,289 @@
1
+ import { existsSync, readFileSync } from "node:fs";
2
+ import { join } from "node:path";
3
+ import { parseArgs } from "node:util";
4
+ import { startClimb, startOptimization } from "../../core/src/index.js";
5
+ import { comparisonWinnerLabel } from "../../optimize/src/index.js";
6
+ import { addEvalCase, approveOptimRun, checkPromotion, getArtifact, getOptimRun, isPidAlive, listEvalCases, listOptimRuns, parseOptimTarget, recoverCrashedOptimRuns, rollbackOptimRun, } from "../../store/src/index.js";
7
+ import { NexoError } from "../../telemetry/src/index.js";
8
+ import { nonInteractivePrompter } from "../../tools/src/index.js";
9
+ import { escapeControl } from "../../tui/src/index.js";
10
+ import { EXIT_SIGINT, usageError } from "./common.js";
11
+ import { openStore } from "./learn.js";
12
+ import { createRuntime } from "./runtime.js";
13
+ const usd = (v) => `$${v.toFixed(4)}`;
14
+ const q = (v) => (v === null || v === undefined ? "–" : v.toFixed(3));
15
+ function versionOf(db, id) {
16
+ if (!id)
17
+ return "–";
18
+ const a = getArtifact(db, id);
19
+ return a ? `v${a.version} (${a.status})` : id;
20
+ }
21
+ /** One line per optimization in `nexo optimize list`. */
22
+ export function optimRunLine(run) {
23
+ const holdout = run.holdoutBefore === null ? "" : ` · holdout ${q(run.holdoutBefore)} → ${q(run.holdoutAfter)}`;
24
+ const promotion = run.promotion ? ` · ${run.promotion.replace("_", " ")}` : "";
25
+ const climb = run.mode === "climb" ? ` · ${run.climbOutcome ?? "no outcome"}` : "";
26
+ const target = `${run.mode === "climb" ? "climb " : ""}${escapeControl(run.target)}`;
27
+ return `${run.id} ${target.padEnd(22)} ${run.status.padEnd(9)} ${(run.stopReason ?? "").padEnd(15)} ${usd(run.spentUsd)} of $${run.budgetUsd.toFixed(2)} · ${run.rollouts} rollouts${holdout}${climb}${promotion}`;
28
+ }
29
+ /** The report summary printed by `nexo optimize` and `nexo optimize show`. */
30
+ export function reportLines(db, run, report, minJudgeKappa, options = {}) {
31
+ const lines = [optimRunLine(run), ` base ${versionOf(db, run.baseArtifactId)} · best ${versionOf(db, run.bestArtifactId)}`];
32
+ if (run.error)
33
+ lines.push(` error [${run.error.code}] ${escapeControl(run.error.message)}`);
34
+ if (!report)
35
+ return lines;
36
+ if (report.climb) {
37
+ const c = report.climb;
38
+ lines.push(` climb on case ${c.caseId} (${c.guardIds.length} guard${c.guardIds.length === 1 ? "" : "s"}) · ${c.outcome}`);
39
+ if (c.critique)
40
+ lines.push(` critique: ${escapeControl(c.critique)}`);
41
+ for (const p of c.comparisons)
42
+ lines.push(` ${escapeControl(p.label).padEnd(20)} ${comparisonWinnerLabel(p)}`);
43
+ }
44
+ const h = report.holdout;
45
+ lines.push(` holdout (${h.cases.length} cases): quality ${q(h.before.quality)} → ${q(h.after.quality)}, cost ${usd(h.before.costUsd)} → ${usd(h.after.costUsd)} per case; ${h.wins} wins, ${h.losses} losses, ${h.ties} ties`);
46
+ for (const c of h.cases)
47
+ lines.push(` ${c.outcome.padEnd(4)} ${q(c.before.quality)} → ${q(c.after.quality)} ${escapeControl(c.input.replace(/\s+/g, " ").slice(0, 80))}`);
48
+ if (!report.climb)
49
+ lines.push(` ${report.iterations} iterations, ${report.lineage.length - 1} candidates, ${report.merges} merges${report.mergeNote ? ` (${escapeControl(report.mergeNote)})` : ""}`);
50
+ const e = report.evidence;
51
+ lines.push(e.humanScored
52
+ ? " evidence: human verdicts"
53
+ : ` evidence: ${e.judgeOnly ? "judge only" : "includes deterministic scorers"} · judge ${escapeControl(e.judgeKey ?? "none")} κ ${e.kappa === null ? "–" : e.kappa.toFixed(2)} (min ${minJudgeKappa})`);
54
+ const check = checkPromotion(db, run, minJudgeKappa);
55
+ if (run.promotion === "approved")
56
+ lines.push(` approved; undo with \`nexo optimize rollback ${run.id}\``);
57
+ else if (check.allowed)
58
+ lines.push(` approve with \`nexo optimize approve ${run.id}\``);
59
+ else
60
+ lines.push(` cannot approve: ${escapeControl(check.error?.message ?? "")}`);
61
+ if (options.diff) {
62
+ lines.push(" diff (base → best):");
63
+ for (const d of report.diff)
64
+ lines.push(` ${d.op === "add" ? "+" : d.op === "del" ? "-" : " "} ${escapeControl(d.text)}`);
65
+ }
66
+ return lines;
67
+ }
68
+ function readReport(run) {
69
+ if (!run.reportRef)
70
+ return null;
71
+ const file = join(run.dirPath, run.reportRef);
72
+ if (!existsSync(file))
73
+ return null;
74
+ return JSON.parse(readFileSync(file, "utf8"));
75
+ }
76
+ function requireRun(db, id) {
77
+ if (!id)
78
+ throw usageError("Pass an optimization id");
79
+ const run = getOptimRun(db, id);
80
+ if (!run)
81
+ throw new NexoError({ code: "NOT_FOUND", message: `Optimization ${id} does not exist`, hint: "List optimizations with `nexo optimize list`" });
82
+ return run;
83
+ }
84
+ /** A progress line for an optimization event, or null. Model-influenced text is control-escaped. */
85
+ export function optimizeEventLine(event) {
86
+ switch (event.type) {
87
+ case "start":
88
+ return `optimizing ${escapeControl(event.target)} (${event.optimRunId}) · $${event.budgetUsd.toFixed(2)} · cases: ${event.cases.feedback} feedback, ${event.cases.pareto} pareto, ${event.cases.holdout} holdout`;
89
+ case "phase":
90
+ return `· ${event.phase === "baseline" ? "evaluating the current version" : event.phase === "loop" ? "searching" : "evaluating the best candidate on the holdout split"}`;
91
+ case "iteration":
92
+ return ` iteration ${event.iteration}: ${event.component}`;
93
+ case "rejected":
94
+ return ` rejected: ${escapeControl(event.reason)}`;
95
+ case "minibatch":
96
+ return ` minibatch ${q(event.parentQuality)} → ${q(event.childQuality)} ${event.accepted ? "✓ accepted" : "✗ not better"}${event.prediction ? ` · predicted fixes ${event.prediction.fixesHit}/${event.prediction.fixesPredicted}, risks ${event.prediction.atRiskHit}/${event.prediction.atRiskPredicted}${event.prediction.unpredictedRegressions > 0 ? `, ${event.prediction.unpredictedRegressions} unpredicted` : ""}` : ""}`;
97
+ case "pareto":
98
+ return ` pareto mean ${q(event.meanQuality)} at ${usd(event.meanCostUsd)}${event.newMember ? " · new Pareto member" : ""}`;
99
+ case "merge":
100
+ return ` merge of ${event.parents.join(" and ")} ${event.accepted ? "kept" : "dropped"}`;
101
+ case "reflection":
102
+ return event.problem ? ` reflection unusable: ${escapeControl(event.problem)}` : null;
103
+ default:
104
+ return null;
105
+ }
106
+ }
107
+ function positiveNumber(flag, raw, integer) {
108
+ if (raw === undefined)
109
+ return undefined;
110
+ const value = Number(raw);
111
+ if (!Number.isFinite(value) || value <= 0 || (integer && !Number.isInteger(value)))
112
+ throw usageError(`${flag} must be a positive ${integer ? "integer" : "number"}`);
113
+ return value;
114
+ }
115
+ /** The notice printed before a foreground optimization: rollouts replay past instructions with the user's allowed tools and MCP servers, side effects included. Null when there are none. */
116
+ function rolloutNotice(config) {
117
+ const allowed = Object.entries(config.tools.policy).filter(([, action]) => action === "allow").map(([tool]) => escapeControl(tool));
118
+ const servers = Object.keys(config.mcp.servers).map((name) => escapeControl(name));
119
+ if (allowed.length === 0 && servers.length === 0)
120
+ return null;
121
+ const parts = [allowed.length > 0 ? `tools set to allow (${allowed.join(", ")})` : null, servers.length > 0 ? `configured MCP servers (${servers.join(", ")})` : null].filter((p) => p !== null);
122
+ return `notice: rollouts replay past instructions under your tool policy, so ${parts.join(" and ")} run once per rollout and their side effects happen each time`;
123
+ }
124
+ /** `nexo optimize --target …`: one optimization in the foreground. */
125
+ async function runOptimize(args, io, options) {
126
+ const { values } = parseArgs({
127
+ args,
128
+ options: { target: { type: "string" }, "budget-usd": { type: "string" }, "max-rollouts": { type: "string" }, merge: { type: "boolean" }, seed: { type: "string" } },
129
+ });
130
+ if (!values.target)
131
+ throw usageError("nexo optimize needs --target skill:<name>|system_prompt|planner_prompt|judge_rubric");
132
+ const seed = values.seed === undefined ? undefined : Number(values.seed);
133
+ if (seed !== undefined && !(Number.isInteger(seed) && seed >= 0))
134
+ throw usageError("--seed must be a non-negative integer");
135
+ const runtime = createRuntime({ env: options.env ?? process.env, cwd: options.cwd ?? process.cwd(), prompter: nonInteractivePrompter, models: options.models });
136
+ try {
137
+ const notice = rolloutNotice(runtime.config);
138
+ if (notice)
139
+ io.stderr.write(`${notice}\n`);
140
+ const { run, report } = await startOptimization(runtime.engine.env, {
141
+ target: values.target,
142
+ budgetUsd: positiveNumber("--budget-usd", values["budget-usd"], false),
143
+ maxRollouts: positiveNumber("--max-rollouts", values["max-rollouts"], true),
144
+ merge: values.merge ?? false,
145
+ ...(seed !== undefined ? { seed } : {}),
146
+ signal: options.signal,
147
+ onEvent: (event) => {
148
+ const line = optimizeEventLine(event);
149
+ if (line)
150
+ io.stderr.write(`${line}\n`);
151
+ },
152
+ });
153
+ for (const line of reportLines(runtime.db, run, report, runtime.config.optimize.minJudgeKappa))
154
+ io.stdout.write(`${line}\n`);
155
+ return run.status === "aborted" ? EXIT_SIGINT : 0;
156
+ }
157
+ finally {
158
+ await runtime.mcp?.close();
159
+ runtime.db.close();
160
+ }
161
+ }
162
+ /** A progress line for a climb event, or null. */
163
+ export function climbEventLine(event) {
164
+ if (event.type === "start")
165
+ return `climbing ${escapeControl(event.target)} (${event.optimRunId}) on case ${event.caseId} with ${event.guardIds.length} guard${event.guardIds.length === 1 ? "" : "s"} · $${event.budgetUsd.toFixed(2)}`;
166
+ if (event.type === "step")
167
+ return ` ${event.step}: ${escapeControl(event.detail)}`;
168
+ return event.type === "reflection" ? optimizeEventLine(event) : null;
169
+ }
170
+ /** `nexo optimize climb --target … [--case] [--guards] [--budget-usd] [--seed]`: one climb in the foreground. */
171
+ async function runClimb(args, io, options) {
172
+ const { values } = parseArgs({ args, options: { target: { type: "string" }, case: { type: "string" }, guards: { type: "string" }, "budget-usd": { type: "string" }, seed: { type: "string" } } });
173
+ if (!values.target)
174
+ throw usageError("nexo optimize climb needs --target skill:<name>|system_prompt|planner_prompt");
175
+ const guards = values.guards === undefined ? undefined : Number(values.guards);
176
+ if (guards !== undefined && !(Number.isInteger(guards) && guards >= 0 && guards <= 10))
177
+ throw usageError("--guards must be an integer from 0 to 10");
178
+ const seed = values.seed === undefined ? undefined : Number(values.seed);
179
+ if (seed !== undefined && !(Number.isInteger(seed) && seed >= 0))
180
+ throw usageError("--seed must be a non-negative integer");
181
+ const budgetUsd = positiveNumber("--budget-usd", values["budget-usd"], false);
182
+ const runtime = createRuntime({ env: options.env ?? process.env, cwd: options.cwd ?? process.cwd(), prompter: nonInteractivePrompter, models: options.models });
183
+ try {
184
+ const notice = rolloutNotice(runtime.config);
185
+ if (notice)
186
+ io.stderr.write(`${notice}\n`);
187
+ const { run, report } = await startClimb(runtime.engine.env, {
188
+ target: values.target,
189
+ ...(values.case ? { caseId: values.case } : {}),
190
+ ...(guards !== undefined ? { guards } : {}),
191
+ ...(budgetUsd !== undefined ? { budgetUsd } : {}),
192
+ ...(seed !== undefined ? { seed } : {}),
193
+ signal: options.signal,
194
+ onEvent: (event) => {
195
+ const line = climbEventLine(event);
196
+ if (line)
197
+ io.stderr.write(`${line}\n`);
198
+ },
199
+ });
200
+ for (const line of reportLines(runtime.db, run, report, runtime.config.optimize.minJudgeKappa))
201
+ io.stdout.write(`${line}\n`);
202
+ return run.status === "aborted" ? EXIT_SIGINT : 0;
203
+ }
204
+ finally {
205
+ await runtime.mcp?.close();
206
+ runtime.db.close();
207
+ }
208
+ }
209
+ /** `nexo optimize …`: run one, or `climb …`, or `list`, `show <id> [--diff]`, `approve <id>`, `rollback <id>`. */
210
+ export async function optimizeCommand(args, io, options) {
211
+ const [sub, ...rest] = args;
212
+ if (sub === undefined || sub.startsWith("-"))
213
+ return runOptimize(args, io, options);
214
+ if (sub === "climb")
215
+ return runClimb(rest, io, options);
216
+ const store = openStore(options);
217
+ try {
218
+ recoverCrashedOptimRuns(store.db, isPidAlive, new Date().toISOString());
219
+ const now = new Date().toISOString();
220
+ switch (sub) {
221
+ case "list": {
222
+ const runs = listOptimRuns(store.db);
223
+ if (runs.length === 0)
224
+ io.stdout.write("No optimizations yet. Start one with `nexo optimize --target <target>`.\n");
225
+ for (const run of runs)
226
+ io.stdout.write(`${optimRunLine(run)}\n`);
227
+ return 0;
228
+ }
229
+ case "show": {
230
+ const { values, positionals } = parseArgs({ args: rest, allowPositionals: true, options: { diff: { type: "boolean" } } });
231
+ const run = requireRun(store.db, positionals[0]);
232
+ for (const line of reportLines(store.db, run, readReport(run), store.config.optimize.minJudgeKappa, { diff: values.diff ?? false }))
233
+ io.stdout.write(`${line}\n`);
234
+ return 0;
235
+ }
236
+ case "approve": {
237
+ const run = requireRun(store.db, rest[0]);
238
+ const { promoted, replaced } = approveOptimRun(store.db, run.id, { minJudgeKappa: store.config.optimize.minJudgeKappa, nowIso: now });
239
+ io.stdout.write(`Promoted ${promoted.kind} ${promoted.name} v${promoted.version}${replaced ? ` (v${replaced.version} retired)` : ""}\n`);
240
+ return 0;
241
+ }
242
+ case "rollback": {
243
+ const run = requireRun(store.db, rest[0]);
244
+ const { active, retired } = rollbackOptimRun(store.db, run.id, now);
245
+ io.stdout.write(`Rolled back ${retired.kind} ${retired.name}: v${retired.version} retired${active ? `, v${active.version} active again` : ""}\n`);
246
+ return 0;
247
+ }
248
+ default:
249
+ throw usageError(`Unknown optimize subcommand "${sub}"`);
250
+ }
251
+ }
252
+ finally {
253
+ store.close();
254
+ }
255
+ }
256
+ /** `nexo eval add --target <t> --input <text> [--skill] [--expected] [--feedback]`: a hand-written eval case. */
257
+ export function evalAddCommand(args, io, options) {
258
+ const { values } = parseArgs({ args, options: { target: { type: "string" }, input: { type: "string" }, skill: { type: "string" }, expected: { type: "string" }, feedback: { type: "string" } } });
259
+ if (!values.target || values.input === undefined)
260
+ throw usageError("nexo eval add needs --target and --input");
261
+ const store = openStore(options);
262
+ try {
263
+ const row = addEvalCase(store.db, { target: values.target, input: values.input, skill: values.skill ?? null, expected: values.expected ?? null, referenceFeedback: values.feedback ?? null }, store.redact, new Date().toISOString());
264
+ io.stdout.write(`Added eval case ${row.id} for ${row.target} (${row.split} split)\n`);
265
+ return 0;
266
+ }
267
+ finally {
268
+ store.close();
269
+ }
270
+ }
271
+ /** `nexo eval list --target <t>`: the target's eval cases with their split and origin. */
272
+ export function evalListCommand(args, io, options) {
273
+ const { values } = parseArgs({ args, options: { target: { type: "string" } } });
274
+ if (!values.target)
275
+ throw usageError("nexo eval list needs --target");
276
+ const target = parseOptimTarget(values.target);
277
+ const store = openStore(options);
278
+ try {
279
+ const cases = listEvalCases(store.db, target.key);
280
+ io.stdout.write(`${cases.length} eval case${cases.length === 1 ? "" : "s"} for ${target.key}\n`);
281
+ for (const c of cases) {
282
+ io.stdout.write(` ${c.id} ${c.split.padEnd(8)} ${c.origin.padEnd(6)} ${c.status.padEnd(9)} ${escapeControl(c.input.replace(/\s+/g, " ").slice(0, 80))}${c.referenceFeedback ? ` — "${escapeControl(c.referenceFeedback.slice(0, 60))}"` : ""}\n`);
283
+ }
284
+ return 0;
285
+ }
286
+ finally {
287
+ store.close();
288
+ }
289
+ }
@@ -0,0 +1,47 @@
1
+ import { createInterface } from "node:readline/promises";
2
+ function isAbortError(error) {
3
+ return error instanceof Error && error.name === "AbortError";
4
+ }
5
+ /**
6
+ * Asks on the terminal. Questions are queued so only one readline owns stdin at a time: concurrent subagents each wait
7
+ * for their own answer instead of sharing one keystroke.
8
+ */
9
+ export function createTtyPrompter(input, output, options = {}) {
10
+ let queue = Promise.resolve();
11
+ const ask = async (request, signal) => {
12
+ if (signal?.aborted)
13
+ return "deny";
14
+ if (request.settled?.())
15
+ return "once";
16
+ const rl = createInterface({ input, output });
17
+ try {
18
+ const lines = [request.question];
19
+ if (request.note)
20
+ lines.push(` ${request.note}`);
21
+ if (request.alwaysLabel)
22
+ lines.push(` a = ${request.alwaysLabel}`);
23
+ const answer = (await rl.question(`${lines.join("\n")} ${request.alwaysLabel ? "[y/a/N]" : "[y/N]"} `, { signal })).trim();
24
+ if (/^y(es)?$/i.test(answer))
25
+ return "once";
26
+ if (request.alwaysLabel && /^a(lways)?$/i.test(answer))
27
+ return "always";
28
+ return "deny";
29
+ }
30
+ catch (error) {
31
+ if (isAbortError(error) && !signal?.aborted)
32
+ options.onInterrupt?.();
33
+ return "deny";
34
+ }
35
+ finally {
36
+ rl.close();
37
+ }
38
+ };
39
+ return {
40
+ interactive: Boolean(input.isTTY),
41
+ approve(request, signal) {
42
+ const turn = queue.then(() => ask(request, signal));
43
+ queue = turn.catch(() => undefined);
44
+ return turn;
45
+ },
46
+ };
47
+ }
@@ -0,0 +1,120 @@
1
+ import { createInterface } from "node:readline/promises";
2
+ import { recordFeedback } from "../../store/src/index.js";
3
+ /** Maps an answer to the `[d]one / [n]ot done / [s]kip` prompt; an empty answer is skip, anything unrecognised is null. */
4
+ export function parseReviewAnswer(answer) {
5
+ const a = answer.trim().toLowerCase();
6
+ if (a === "" || a === "s" || a === "skip")
7
+ return "skip";
8
+ if (a === "d" || a === "done")
9
+ return "done";
10
+ if (a === "n" || a === "not done" || a === "not_done")
11
+ return "not_done";
12
+ return null;
13
+ }
14
+ /**
15
+ * True only when a person can both see and answer the prompt: stdin, stdout and stderr are all terminals. The prompt is
16
+ * written to stderr, so a redirected stderr (`2>log`) must not leave the run waiting on a question nobody sees.
17
+ */
18
+ export function isInteractiveTerminal(stdio) {
19
+ return stdio.stdin.isTTY === true && stdio.stdout.isTTY === true && stdio.stderr.isTTY === true;
20
+ }
21
+ /** One readline interface serves every question, so input typed ahead of a question is kept for the next one. */
22
+ export function createTtyLineAsker(input, output) {
23
+ let rl = null;
24
+ let closed = false;
25
+ const lines = [];
26
+ let waiter = null;
27
+ const finish = (line) => {
28
+ const resolve = waiter;
29
+ waiter = null;
30
+ resolve?.(line);
31
+ };
32
+ const open = () => {
33
+ if (rl)
34
+ return rl;
35
+ rl = createInterface({ input, output });
36
+ rl.on("line", (line) => {
37
+ if (waiter)
38
+ finish(line);
39
+ else
40
+ lines.push(line);
41
+ });
42
+ const end = () => {
43
+ closed = true;
44
+ finish(null);
45
+ };
46
+ rl.on("SIGINT", end);
47
+ rl.on("close", end);
48
+ return rl;
49
+ };
50
+ return {
51
+ ask(question, signal) {
52
+ if (signal?.aborted || closed)
53
+ return Promise.resolve(null);
54
+ const buffered = lines.shift();
55
+ const iface = open();
56
+ if (buffered !== undefined) {
57
+ output.write(question);
58
+ return Promise.resolve(buffered);
59
+ }
60
+ return new Promise((resolve) => {
61
+ const onAbort = () => {
62
+ finish(null);
63
+ iface.close();
64
+ };
65
+ signal?.addEventListener("abort", onAbort, { once: true });
66
+ waiter = (line) => {
67
+ signal?.removeEventListener("abort", onAbort);
68
+ resolve(line);
69
+ };
70
+ iface.setPrompt(question);
71
+ iface.prompt();
72
+ });
73
+ },
74
+ close() {
75
+ closed = true;
76
+ rl?.close();
77
+ },
78
+ };
79
+ }
80
+ /**
81
+ * The post-run review prompt (spec §7.1 step 6). A verdict is written through `recordFeedback`; skip, Ctrl-C, end of
82
+ * input or three unrecognised answers leave the run unreviewed, so it appears in the UI review queue.
83
+ */
84
+ export async function promptReview(options) {
85
+ try {
86
+ return await askAndRecord(options);
87
+ }
88
+ finally {
89
+ options.asker.close?.();
90
+ }
91
+ }
92
+ async function askAndRecord(options) {
93
+ const { asker, io, signal } = options;
94
+ let choice = null;
95
+ for (let attempt = 0; attempt < 3 && choice === null; attempt++) {
96
+ const answer = await asker.ask("Review this run: [d]one / [n]ot done / [s]kip ", signal);
97
+ if (answer === null) {
98
+ choice = "skip";
99
+ break;
100
+ }
101
+ choice = parseReviewAnswer(answer);
102
+ if (choice === null)
103
+ io.stderr.write("Answer d, n or s.\n");
104
+ }
105
+ if (choice === null || choice === "skip") {
106
+ io.stderr.write("Skipped. The run is waiting in the review queue of `nexo ui`.\n");
107
+ return "skip";
108
+ }
109
+ const comment = choice === "not_done" ? ((await asker.ask("What was missing or wrong? (optional) ", signal)) ?? "") : "";
110
+ recordFeedback(options.db, {
111
+ runId: options.runId,
112
+ verdict: choice,
113
+ comment,
114
+ nowIso: (options.now ?? (() => new Date()))().toISOString(),
115
+ redact: options.redact,
116
+ learn: options.learn === true,
117
+ });
118
+ io.stderr.write(`Recorded verdict: ${choice === "done" ? "done" : "not done"}.\n`);
119
+ return choice;
120
+ }
@@ -0,0 +1,2 @@
1
+ // The runtime wiring lives in @nexo/sdk so the CLI and backends share one construction path.
2
+ export { createRuntime, openLogger } from "../../sdk/src/index.js";
@@ -0,0 +1,34 @@
1
+ import { parseArgs } from "node:util";
2
+ import { listSessions } from "../../core/src/index.js";
3
+ import { ensureNexoDirs, openDb, resolveNexoPaths } from "../../store/src/index.js";
4
+ import { escapeControl, oneLine } from "../../tui/src/index.js";
5
+ import { usageError } from "./common.js";
6
+ const TITLE_WIDTH = 50;
7
+ /** `nexo sessions [--limit n]`: id, title, turns, cost and updated time (UTC), newest first. */
8
+ export function sessionsCommand(args, io, options) {
9
+ const { values } = parseArgs({ args, options: { limit: { type: "string" } } });
10
+ let limit;
11
+ if (values.limit !== undefined) {
12
+ limit = /^\d+$/.test(values.limit) ? Number(values.limit) : Number.NaN;
13
+ if (!Number.isInteger(limit) || limit < 1 || limit > 1000)
14
+ throw usageError("--limit must be an integer from 1 to 1000");
15
+ }
16
+ const paths = resolveNexoPaths(options.env ?? process.env);
17
+ ensureNexoDirs(paths);
18
+ const rows = listSessions(openDb(paths.db), { limit });
19
+ if (rows.length === 0) {
20
+ io.stdout.write("No sessions yet. Run `nexo` to start one.\n");
21
+ return 0;
22
+ }
23
+ const cells = rows.map((r) => [r.id, oneLine(escapeControl(r.title), TITLE_WIDTH) || "(untitled)", String(r.turns), `$${r.costUsd.toFixed(4)}`, r.updatedAt.slice(0, 16).replace("T", " ")]);
24
+ const head = ["ID", "TITLE", "TURNS", "COST", "UPDATED"];
25
+ const widths = head.map((h, i) => Math.max(h.length, ...cells.map((c) => c[i].length)));
26
+ const right = new Set([2, 3]);
27
+ const line = (c) => c
28
+ .map((cell, i) => (i === c.length - 1 ? cell : right.has(i) ? cell.padStart(widths[i]) : cell.padEnd(widths[i])))
29
+ .join(" ");
30
+ io.stdout.write(`${line(head)}\n`);
31
+ for (const c of cells)
32
+ io.stdout.write(`${line(c)}\n`);
33
+ return 0;
34
+ }
@@ -0,0 +1,169 @@
1
+ import { createSettings, keyStatusLabel, nexoModels } from "../../core/src/index.js";
2
+ import { ensureNexoDirs, resolveNexoPaths } from "../../store/src/index.js";
3
+ import { NexoError, toErrorPayload } from "../../telemetry/src/index.js";
4
+ import { EXIT_SIGINT, exitCodeFor, printError, usageError } from "./common.js";
5
+ import { openLogger } from "./runtime.js";
6
+ const MAX_PIPED_KEY_BYTES = 64 * 1024;
7
+ /** One line from a piped stdin; the key never passes through argv. Resolves null when `signal` aborts or stdin fails first. */
8
+ function readPipedKey(stdin, signal) {
9
+ return new Promise((resolve) => {
10
+ let text = "";
11
+ let settled = false;
12
+ const finish = (result) => {
13
+ if (settled)
14
+ return;
15
+ settled = true;
16
+ stdin.off("data", onData);
17
+ stdin.off("end", onEnd);
18
+ stdin.off("error", onError);
19
+ signal?.removeEventListener("abort", onAbort);
20
+ stdin.pause();
21
+ resolve(result);
22
+ };
23
+ const line = () => (text.split(/\r?\n/, 1)[0] ?? "").trim();
24
+ const onData = (chunk) => {
25
+ text += typeof chunk === "string" ? chunk : chunk.toString("utf8");
26
+ if (text.includes("\n") || text.length > MAX_PIPED_KEY_BYTES)
27
+ finish(line());
28
+ };
29
+ const onEnd = () => finish(line());
30
+ const onError = () => finish(null);
31
+ const onAbort = () => finish(null);
32
+ if (signal?.aborted)
33
+ return resolve(null);
34
+ stdin.on("data", onData);
35
+ stdin.on("end", onEnd);
36
+ stdin.on("error", onError);
37
+ signal?.addEventListener("abort", onAbort, { once: true });
38
+ stdin.resume();
39
+ });
40
+ }
41
+ /**
42
+ * Reads a line from the terminal in raw mode, so nothing is echoed. Resolves null on Ctrl-C, Ctrl-D at an empty
43
+ * prompt, end of input, an input error or an abort; raw mode is always switched off again.
44
+ */
45
+ export function readHiddenKey(stdin, stderr, provider, signal) {
46
+ return new Promise((resolve) => {
47
+ let value = "";
48
+ let settled = false;
49
+ const finish = (result) => {
50
+ if (settled)
51
+ return;
52
+ settled = true;
53
+ stdin.off("data", onData);
54
+ stdin.off("end", onEnd);
55
+ stdin.off("error", onEnd);
56
+ signal?.removeEventListener("abort", onEnd);
57
+ stdin.setRawMode?.(false);
58
+ stdin.pause();
59
+ stderr.write("\n");
60
+ resolve(result);
61
+ };
62
+ const onEnd = () => finish(null);
63
+ const onData = (chunk) => {
64
+ const text = typeof chunk === "string" ? chunk : chunk.toString("utf8");
65
+ for (let i = 0; i < text.length; i++) {
66
+ const ch = text[i];
67
+ if (ch === "\r" || ch === "\n")
68
+ return finish(value);
69
+ if (ch === "\x03" || (ch === "\x04" && value === ""))
70
+ return finish(null);
71
+ if (ch === "\x7f" || ch === "\b")
72
+ value = value.slice(0, -1);
73
+ else if (ch === "\x1b")
74
+ i = text.length; // an escape sequence (arrow keys): ignore the rest of the chunk
75
+ else if (ch >= " ")
76
+ value += ch;
77
+ }
78
+ };
79
+ if (signal?.aborted)
80
+ return resolve(null);
81
+ stderr.write(`API key for ${provider} (input hidden): `);
82
+ stdin.setRawMode?.(true);
83
+ stdin.on("data", onData);
84
+ stdin.on("end", onEnd);
85
+ stdin.on("error", onEnd);
86
+ signal?.addEventListener("abort", onEnd, { once: true });
87
+ stdin.resume();
88
+ });
89
+ }
90
+ function show(view) {
91
+ return view.value === null ? "unset" : String(view.value);
92
+ }
93
+ /** `nexo settings get|set|reset|set-key`: no TUI, for scripts. Invalid keys and values are usage errors (exit 2). */
94
+ export async function settingsCommand(args, io, options, stdio) {
95
+ const [sub, ...rest] = args;
96
+ const env = options.env ?? process.env;
97
+ const paths = resolveNexoPaths(env);
98
+ ensureNexoDirs(paths);
99
+ const build = () => {
100
+ const settings = createSettings({ paths, cwd: options.cwd ?? process.cwd(), env, models: options.models ?? nexoModels() });
101
+ openLogger(settings, paths, "settings");
102
+ return settings;
103
+ };
104
+ let redact = (text) => text;
105
+ try {
106
+ switch (sub) {
107
+ case "get": {
108
+ if (rest.length !== 1)
109
+ throw usageError("nexo settings get needs exactly one key");
110
+ const view = build().getSetting(rest[0]);
111
+ io.stdout.write(`${show(view)}\n`);
112
+ if (view.notice)
113
+ io.stderr.write(`note: ${view.notice}\n`);
114
+ return 0;
115
+ }
116
+ case "set": {
117
+ if (rest.length !== 2)
118
+ throw usageError("nexo settings set needs a key and a value");
119
+ const view = build().setSettingFromString(rest[0], rest[1]);
120
+ io.stdout.write(`${view.key} = ${show(view)}\n`);
121
+ if (view.notice)
122
+ io.stderr.write(`note: ${view.notice}\n`);
123
+ return 0;
124
+ }
125
+ case "reset": {
126
+ if (rest.length !== 1)
127
+ throw usageError("nexo settings reset needs exactly one key");
128
+ const view = build().resetSetting(rest[0]);
129
+ io.stdout.write(`${view.key} = ${show(view)}\n`);
130
+ if (view.notice)
131
+ io.stderr.write(`note: ${view.notice}\n`);
132
+ return 0;
133
+ }
134
+ case "set-key": {
135
+ if (rest.length > 1) {
136
+ throw new NexoError({
137
+ code: "CONFIG_INVALID",
138
+ message: "nexo settings set-key takes only the provider; a key on the command line would leak into shell history and process lists",
139
+ hint: "Run `nexo settings set-key <provider>` and type the key at the prompt, or pipe it on stdin: `printf %s \"$KEY\" | nexo settings set-key <provider>`",
140
+ });
141
+ }
142
+ if (rest.length === 0)
143
+ throw usageError("nexo settings set-key needs a provider");
144
+ const settings = build();
145
+ redact = settings.redact;
146
+ const provider = rest[0];
147
+ // Checked before the prompt, so a mistyped (or secret-looking) provider is never echoed or asked about.
148
+ settings.validateKeyProvider(provider);
149
+ const key = stdio.stdin.isTTY === true ? await readHiddenKey(stdio.stdin, io.stderr, provider, options.signal) : await readPipedKey(stdio.stdin, options.signal);
150
+ if (key === null) {
151
+ io.stderr.write("cancelled\n");
152
+ return EXIT_SIGINT;
153
+ }
154
+ if (key === "")
155
+ throw new NexoError({ code: "INVALID_REQUEST", message: "No key received", hint: "Type or pipe the API key; an empty line is not a key" });
156
+ const status = settings.setKey(provider, key);
157
+ io.stdout.write(`${status.provider}: ${keyStatusLabel(status)}\n`);
158
+ return 0;
159
+ }
160
+ default:
161
+ throw usageError(sub === undefined ? "nexo settings needs get, set, reset or set-key (or a terminal for the screen)" : `Unknown settings command "${sub}"`);
162
+ }
163
+ }
164
+ catch (error) {
165
+ const payload = toErrorPayload(error);
166
+ printError(io, payload, redact);
167
+ return payload.code === "INVALID_REQUEST" ? 2 : exitCodeFor(payload.code);
168
+ }
169
+ }