@hexdecimal16/nexo 0.0.0-stage → 0.2.1

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 (209) 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 +78 -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 +266 -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/cli/src/version.js +19 -0
  20. package/core/src/approval/classifier.js +152 -0
  21. package/core/src/config/load.js +283 -0
  22. package/core/src/config/schema.js +186 -0
  23. package/core/src/cost/admission.js +90 -0
  24. package/core/src/cost/budget.js +67 -0
  25. package/core/src/cost/pricing.js +53 -0
  26. package/core/src/engine/charged-completion.js +79 -0
  27. package/core/src/engine/errors.js +77 -0
  28. package/core/src/engine/mcp.js +11 -0
  29. package/core/src/engine/messages.js +86 -0
  30. package/core/src/engine/prompts.js +32 -0
  31. package/core/src/engine/provider-gate.js +33 -0
  32. package/core/src/engine/recorder.js +61 -0
  33. package/core/src/engine/run.js +1115 -0
  34. package/core/src/engine/semaphore.js +45 -0
  35. package/core/src/engine/spawn-tool.js +119 -0
  36. package/core/src/engine/task-graph.js +153 -0
  37. package/core/src/index.js +32 -0
  38. package/core/src/learn/caller.js +171 -0
  39. package/core/src/learn/context.js +112 -0
  40. package/core/src/learn/embedder.js +216 -0
  41. package/core/src/learn/job.js +196 -0
  42. package/core/src/learn/wiki.js +116 -0
  43. package/core/src/learn/worker.js +141 -0
  44. package/core/src/optimize/adapter.js +250 -0
  45. package/core/src/optimize/climb.js +338 -0
  46. package/core/src/optimize/mine.js +95 -0
  47. package/core/src/optimize/optimize.js +377 -0
  48. package/core/src/optimize/optimizer-run.js +67 -0
  49. package/core/src/optimize/reflect.js +100 -0
  50. package/core/src/optimize/scratchpad-wiki.js +69 -0
  51. package/core/src/providers/claude-p.js +363 -0
  52. package/core/src/providers/kiro-p.js +408 -0
  53. package/core/src/providers/models.js +10 -0
  54. package/core/src/scoring/calibration.js +31 -0
  55. package/core/src/scoring/continuation.js +24 -0
  56. package/core/src/scoring/runner.js +322 -0
  57. package/core/src/scoring/sources.js +88 -0
  58. package/core/src/session/lock.js +88 -0
  59. package/core/src/session/session.js +647 -0
  60. package/core/src/session/shell.js +26 -0
  61. package/core/src/session/transcript.js +86 -0
  62. package/core/src/settings/config-edit.js +472 -0
  63. package/core/src/settings/credentials.js +120 -0
  64. package/core/src/settings/doctor.js +103 -0
  65. package/core/src/settings/settings.js +265 -0
  66. package/mcp/src/hub.js +184 -0
  67. package/mcp/src/index.js +1 -0
  68. package/memory/src/curate.js +121 -0
  69. package/memory/src/index.js +4 -0
  70. package/memory/src/prompts.js +143 -0
  71. package/memory/src/retrieval.js +91 -0
  72. package/memory/src/similarity.js +47 -0
  73. package/optimize/src/engine.js +206 -0
  74. package/optimize/src/index.js +8 -0
  75. package/optimize/src/merge.js +73 -0
  76. package/optimize/src/novelty.js +37 -0
  77. package/optimize/src/pareto.js +83 -0
  78. package/optimize/src/proposer.js +148 -0
  79. package/optimize/src/report.js +107 -0
  80. package/optimize/src/rng.js +34 -0
  81. package/optimize/src/target.js +34 -0
  82. package/package.json +47 -4
  83. package/router/src/effort.js +5 -0
  84. package/router/src/escalation.js +171 -0
  85. package/router/src/index.js +4 -0
  86. package/router/src/registry.js +21 -0
  87. package/router/src/resolve.js +117 -0
  88. package/scorers/src/deterministic.js +194 -0
  89. package/scorers/src/family.js +48 -0
  90. package/scorers/src/index.js +6 -0
  91. package/scorers/src/judge.js +284 -0
  92. package/scorers/src/regex-worker.js +3 -0
  93. package/scorers/src/spec.js +147 -0
  94. package/scorers/src/trajectory.js +22 -0
  95. package/scorers/src/types.js +1 -0
  96. package/sdk/src/index.js +3 -0
  97. package/sdk/src/nexo.js +94 -0
  98. package/sdk/src/runtime.js +39 -0
  99. package/skills/bundled/browser/SKILL.md +57 -0
  100. package/skills/bundled/wiki/SKILL.md +73 -0
  101. package/skills/src/frontmatter.js +25 -0
  102. package/skills/src/index.js +3 -0
  103. package/skills/src/load-skill-tool.js +41 -0
  104. package/skills/src/loader.js +95 -0
  105. package/store/src/artifacts.js +124 -0
  106. package/store/src/budget-ledger.js +18 -0
  107. package/store/src/cost-report.js +46 -0
  108. package/store/src/cursor.js +35 -0
  109. package/store/src/db.js +83 -0
  110. package/store/src/errors.js +9 -0
  111. package/store/src/eval-cases.js +255 -0
  112. package/store/src/feedback.js +154 -0
  113. package/store/src/goldens.js +61 -0
  114. package/store/src/ids.js +6 -0
  115. package/store/src/index.js +25 -0
  116. package/store/src/judge-calibration.js +182 -0
  117. package/store/src/learn-jobs.js +145 -0
  118. package/store/src/memories.js +261 -0
  119. package/store/src/migrations/001_init.sql +81 -0
  120. package/store/src/migrations/002_feedback.sql +9 -0
  121. package/store/src/migrations/003_sessions.sql +19 -0
  122. package/store/src/migrations/004_scoring.sql +22 -0
  123. package/store/src/migrations/005_judge_calibration.sql +27 -0
  124. package/store/src/migrations/006_learning.sql +77 -0
  125. package/store/src/migrations/007_optimize.sql +55 -0
  126. package/store/src/migrations/008_mined_cases_and_climb.sql +46 -0
  127. package/store/src/mine.js +51 -0
  128. package/store/src/optim.js +291 -0
  129. package/store/src/paths.js +22 -0
  130. package/store/src/playbooks.js +199 -0
  131. package/store/src/reindex.js +143 -0
  132. package/store/src/run-dir.js +151 -0
  133. package/store/src/runs.js +310 -0
  134. package/store/src/scores.js +92 -0
  135. package/store/src/sessions.js +304 -0
  136. package/store/src/span-tree.js +98 -0
  137. package/store/src/spans.js +84 -0
  138. package/store/src/sql.js +13 -0
  139. package/store/src/workspace-copy.js +80 -0
  140. package/telemetry/src/errors.js +32 -0
  141. package/telemetry/src/index.js +3 -0
  142. package/telemetry/src/logger.js +39 -0
  143. package/telemetry/src/redact.js +106 -0
  144. package/tools/src/builtin.js +269 -0
  145. package/tools/src/change-tracker.js +57 -0
  146. package/tools/src/confine.js +101 -0
  147. package/tools/src/index.js +7 -0
  148. package/tools/src/leases.js +57 -0
  149. package/tools/src/policy.js +162 -0
  150. package/tools/src/read-only.js +338 -0
  151. package/tools/src/session-rules.js +140 -0
  152. package/tui/src/app.js +965 -0
  153. package/tui/src/approvals.js +96 -0
  154. package/tui/src/commands.js +38 -0
  155. package/tui/src/components.js +248 -0
  156. package/tui/src/index.js +5 -0
  157. package/tui/src/picker.js +78 -0
  158. package/tui/src/session-picker.js +100 -0
  159. package/tui/src/settings-screen.js +346 -0
  160. package/tui/src/text.js +70 -0
  161. package/tui/src/theme.js +44 -0
  162. package/web/public/cost.html +25 -0
  163. package/web/public/fonts/GeistMono-400.woff2 +0 -0
  164. package/web/public/fonts/GeistMono-600.woff2 +0 -0
  165. package/web/public/fonts/InstrumentSans-400.woff2 +0 -0
  166. package/web/public/fonts/InstrumentSans-600.woff2 +0 -0
  167. package/web/public/index.html +39 -0
  168. package/web/public/judge.html +21 -0
  169. package/web/public/learning.html +46 -0
  170. package/web/public/lib/api-types.ts +616 -0
  171. package/web/public/lib/common-view.ts +47 -0
  172. package/web/public/lib/cost-view.ts +35 -0
  173. package/web/public/lib/files-view.ts +90 -0
  174. package/web/public/lib/format.ts +35 -0
  175. package/web/public/lib/html.ts +51 -0
  176. package/web/public/lib/judge-view.ts +62 -0
  177. package/web/public/lib/learning-view.ts +102 -0
  178. package/web/public/lib/optim-view.ts +148 -0
  179. package/web/public/lib/pager.ts +56 -0
  180. package/web/public/lib/poller.ts +79 -0
  181. package/web/public/lib/run-view.ts +61 -0
  182. package/web/public/lib/runs-view.ts +87 -0
  183. package/web/public/lib/score-view.ts +94 -0
  184. package/web/public/lib/sessions-view.ts +28 -0
  185. package/web/public/lib/span-view.ts +90 -0
  186. package/web/public/lib/theme.ts +60 -0
  187. package/web/public/lib/timeline.ts +97 -0
  188. package/web/public/lib/wikis-view.ts +257 -0
  189. package/web/public/optim.html +30 -0
  190. package/web/public/pages/api.ts +60 -0
  191. package/web/public/pages/cost.ts +36 -0
  192. package/web/public/pages/judge.ts +15 -0
  193. package/web/public/pages/learning.ts +92 -0
  194. package/web/public/pages/optim.ts +68 -0
  195. package/web/public/pages/paging.ts +18 -0
  196. package/web/public/pages/run.ts +221 -0
  197. package/web/public/pages/runs.ts +91 -0
  198. package/web/public/pages/sessions.ts +25 -0
  199. package/web/public/pages/wikis.ts +103 -0
  200. package/web/public/run.html +36 -0
  201. package/web/public/sessions.html +28 -0
  202. package/web/public/style.css +288 -0
  203. package/web/public/wikis.html +25 -0
  204. package/web/src/api.js +682 -0
  205. package/web/src/http-errors.js +60 -0
  206. package/web/src/index.js +5 -0
  207. package/web/src/server.js +292 -0
  208. package/web/src/static.js +86 -0
  209. package/web/src/strip.js +22 -0
package/LICENSE ADDED
@@ -0,0 +1,75 @@
1
+ Required Notice: Copyright (c) 2026 dhairya (https://github.com/hexdecimal16/nexo)
2
+
3
+ # PolyForm Noncommercial License 1.0.0
4
+
5
+ <https://polyformproject.org/licenses/noncommercial/1.0.0>
6
+
7
+ ## Acceptance
8
+
9
+ In order to get any license under these terms, you must agree to them as both strict obligations and conditions to all your licenses.
10
+
11
+ ## Copyright License
12
+
13
+ The licensor grants you a copyright license for the software to do everything you might do with the software that would otherwise infringe the licensor's copyright in it for any permitted purpose. However, you may only distribute the software according to [Distribution License](#distribution-license) and make changes or new works based on the software according to [Changes and New Works License](#changes-and-new-works-license).
14
+
15
+ ## Distribution License
16
+
17
+ The licensor grants you an additional copyright license to distribute copies of the software. Your license to distribute covers distributing the software with changes and new works permitted by [Changes and New Works License](#changes-and-new-works-license).
18
+
19
+ ## Notices
20
+
21
+ You must ensure that anyone who gets a copy of any part of the software from you also gets a copy of these terms or the URL for them above, as well as copies of any plain-text lines beginning with `Required Notice:` that the licensor provided with the software. For example:
22
+
23
+ > Required Notice: Copyright Yoyodyne, Inc. (http://example.com)
24
+
25
+ ## Changes and New Works License
26
+
27
+ The licensor grants you an additional copyright license to make changes and new works based on the software for any permitted purpose.
28
+
29
+ ## Patent License
30
+
31
+ The licensor grants you a patent license for the software that covers patent claims the licensor can license, or becomes able to license, that you would infringe by using the software.
32
+
33
+ ## Noncommercial Purposes
34
+
35
+ Any noncommercial purpose is a permitted purpose.
36
+
37
+ ## Personal Uses
38
+
39
+ Personal use for research, experiment, and testing for the benefit of public knowledge, personal study, private entertainment, hobby projects, amateur pursuits, or religious observance, without any anticipated commercial application, is use for a permitted purpose.
40
+
41
+ ## Noncommercial Organizations
42
+
43
+ Use by any charitable organization, educational institution, public research organization, public safety or health organization, environmental protection organization, or government institution is use for a permitted purpose regardless of the source of funding or obligations resulting from the funding.
44
+
45
+ ## Fair Use
46
+
47
+ You may have "fair use" rights for the software under the law. These terms do not limit them.
48
+
49
+ ## No Other Rights
50
+
51
+ These terms do not allow you to sublicense or transfer any of your licenses to anyone else, or prevent the licensor from granting licenses to anyone else. These terms do not imply any other licenses.
52
+
53
+ ## Patent Defense
54
+
55
+ If you make any written claim that the software infringes or contributes to infringement of any patent, your patent license for the software granted under these terms ends immediately. If your company makes such a claim, your patent license ends immediately for work on behalf of your company.
56
+
57
+ ## Violations
58
+
59
+ The first time you are notified in writing that you have violated any of these terms, or done anything with the software not covered by your licenses, your licenses can nonetheless continue if you come into full compliance with these terms, and take practical steps to correct past violations, within 32 days of receiving notice. Otherwise, all your licenses end immediately.
60
+
61
+ ## No Liability
62
+
63
+ ***As far as the law allows, the software comes as is, without any warranty or condition, and the licensor will not be liable to you for any damages arising out of these terms or the use or nature of the software, under any kind of legal claim.***
64
+
65
+ ## Definitions
66
+
67
+ The **licensor** is the individual or entity offering these terms, and the **software** is the software the licensor makes available under these terms.
68
+
69
+ **You** refers to the individual or entity agreeing to these terms.
70
+
71
+ **Your company** is any legal entity, sole proprietorship, or other kind of organization that you work for, plus all organizations that have control over, are under the control of, or are under common control with that organization. **Control** means ownership of substantially all the assets of an entity, or the power to direct its management and policies by vote, contract, or otherwise. Control can be direct or indirect.
72
+
73
+ **Your licenses** are all the licenses granted to you for the software under these terms.
74
+
75
+ **Use** means anything you do with the software requiring one of your licenses.
package/README.md CHANGED
@@ -1,3 +1,76 @@
1
- # Temporary Holding Version
1
+ # nexo
2
2
 
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
3
+ An AI agent engine that runs on your machine. It tracks what each run costs, scores the results, and keeps every run inspectable. Use it from the terminal, from a web run inspector, or from Node code.
4
+
5
+ Requires Node 22.19 or newer.
6
+
7
+ ## Install
8
+
9
+ From npm:
10
+
11
+ ```sh
12
+ npm install -g @hexdecimal16/nexo
13
+ ```
14
+
15
+ From source:
16
+
17
+ ```sh
18
+ git clone https://github.com/hexdecimal16/nexo.git
19
+ cd nexo
20
+ npm ci
21
+ npm run nexo -- init
22
+ ```
23
+
24
+ To install a `nexo` command globally from your checkout:
25
+
26
+ ```sh
27
+ npm run build
28
+ (cd dist && npm pack --pack-destination /tmp) && npm install -g /tmp/nexo-*.tgz
29
+ ```
30
+
31
+ ## First run
32
+
33
+ ```sh
34
+ nexo init # pick models, store API keys, make one small test call
35
+ nexo doctor # check Node, config, keys and the data directory
36
+ nexo # start a chat
37
+ nexo run "summarize this folder" --budget 0.25
38
+ nexo ui # open the run inspector (traces, costs, scores)
39
+ ```
40
+
41
+ For scripts, `nexo init --yes --s1 <provider/id> --s2 <provider/id>` runs without prompts and reads keys from the provider's environment variable. `nexo doctor --json` prints the checks for automation.
42
+
43
+ Data lives in `~/.nexo` (set `NEXO_HOME` to change it).
44
+
45
+ ## Use it from Node
46
+
47
+ ```ts
48
+ import { createNexo } from "@hexdecimal16/nexo/sdk";
49
+
50
+ const nexo = createNexo();
51
+ try {
52
+ const result = await nexo.run({ instruction: "Say hello", budgetUsd: 0.25 });
53
+ console.log(result.output, result.costUsd);
54
+ } finally {
55
+ await nexo.close();
56
+ }
57
+ ```
58
+
59
+ The SDK denies every tool approval by default, so a backend never waits on a person. Always pass `budgetUsd`. `checkSetup()` runs the doctor checks without starting the engine, which suits a start-up pre-flight.
60
+
61
+ ## Security
62
+
63
+ nexo tools run shell commands and edit files. Path confinement is not a sandbox. If you run nexo for other people, give each request its own workspace and use a container for real isolation.
64
+
65
+ ## Develop
66
+
67
+ ```sh
68
+ npm run typecheck
69
+ npm test
70
+ npm run build # release build into dist/
71
+ npm run bump -- minor
72
+ ```
73
+
74
+ ## License
75
+
76
+ [PolyForm Noncommercial 1.0.0](LICENSE). Free for any noncommercial use. Commercial use needs separate permission from the author.
package/cli/src/bin.js ADDED
@@ -0,0 +1,12 @@
1
+ #!/usr/bin/env node
2
+ import { abortOnSignals, EXIT_SIGINT, EXIT_SIGTERM, runCli } from "./main.js";
3
+ // Child processes of tools run in their own process groups and are only killed through the run's abort signal.
4
+ const controller = new AbortController();
5
+ const signals = abortOnSignals(process, controller);
6
+ const exitCodeFor = (code) => (code === EXIT_SIGINT && signals.received() === "SIGTERM" ? EXIT_SIGTERM : code);
7
+ const code = await runCli(process.argv.slice(2), { stdout: process.stdout, stderr: process.stderr }, {
8
+ signal: controller.signal,
9
+ // Interactive mode exits explicitly: a turn that ignored its abort must not keep the process alive.
10
+ exit: (exitCode) => process.exit(exitCodeFor(exitCode)),
11
+ });
12
+ process.exitCode = exitCodeFor(code);
@@ -0,0 +1,78 @@
1
+ import { NexoError } from "../../telemetry/src/index.js";
2
+ export const USAGE = `Usage:
3
+ nexo start an interactive session (needs a terminal)
4
+ nexo --resume [id] resume a session (a picker when no id is given)
5
+ nexo [--workspace <dir>] [--model <s1|s2|provider/id>] [--effort <level>] options for a new session
6
+ without --workspace each turn works in its own run folder (files carried over
7
+ from the previous turn); --workspace . works in the current folder
8
+ nexo sessions [--limit <n>]
9
+ nexo --version print the installed version
10
+ nexo settings open the settings screen (needs a terminal)
11
+ nexo settings get <key>
12
+ nexo settings set <key> <value> keys: models.s1|s2|judge|reflector|embedding, budgets.*, tools.policy.*, tools.autoApprove, tools.nonInteractiveAsk, models.approver, scoring.judge, learning.*, memory.*, optimize.minCases|patience|minJudgeKappa|noveltySimilarity|offspringAlpha
13
+ nexo settings reset <key> remove it from the user config
14
+ nexo settings set-key <provider> reads the key from a hidden prompt, or from stdin when piped
15
+ nexo run <instruction...> [--skill <name>] [--model <s1|s2|provider/id>] [--effort <level>] [--workspace <dir>] [--budget <usd>] [--no-review]
16
+ nexo cost [--by model|tier|day|run|skill] [--since YYYY-MM-DD]
17
+ nexo reindex
18
+ nexo eval judge [--judge <provider/id[+provider/id…]>] judge-vs-human agreement and Cohen's κ
19
+ nexo eval add --target <target> --input <text> [--skill <name>] [--expected <text>] [--feedback <text>]
20
+ nexo eval list --target <target>
21
+ nexo eval mine --target <target> [--days <n>] propose eval cases from unreviewed runs
22
+ nexo eval accept <case-id> [--expected <text>]
23
+ nexo eval dismiss <case-id>
24
+ nexo eval golden revert <case-id>
25
+ nexo optimize --target skill:<name>|system_prompt|planner_prompt|judge_rubric [--budget-usd <n>] [--max-rollouts <n>] [--merge] [--seed <n>]
26
+ nexo optimize climb --target skill:<name>|system_prompt|planner_prompt [--case <id>] [--guards <0-10>] [--budget-usd <n>] [--seed <n>]
27
+ nexo optimize list
28
+ nexo optimize show <id> [--diff]
29
+ nexo optimize approve <id> promote the best candidate (refused on weak evidence)
30
+ nexo optimize rollback <id> reactivate the version an approval replaced
31
+ nexo learn [--retry] run pending learn jobs (--retry: failed ones with attempts left too)
32
+ nexo memory list [--scope user|global|skill:<name>] [--type fact|preference|lesson|workflow] [--all]
33
+ nexo memory add <text...> [--scope …] [--type …] [--importance 0..1]
34
+ nexo memory retire <id>
35
+ nexo playbook show <skill> [--all]
36
+ nexo playbook add <skill> <text...>
37
+ nexo playbook retire <skill> <key>
38
+ nexo init [--yes] [--s1 <provider/id>] [--s2 <provider/id>] [--skip-test] guided first-time setup with a test call
39
+ nexo doctor [--json] check Node, config, keys and the data directory (exit 1 on a failure)
40
+ nexo ui [--port <n>]
41
+ `;
42
+ export const EXIT_SIGINT = 130;
43
+ export const EXIT_SIGTERM = 143;
44
+ export function exitCodeFor(code) {
45
+ switch (code) {
46
+ case undefined:
47
+ return 0;
48
+ case "CONFIG_INVALID":
49
+ return 2;
50
+ case "BUDGET_EXCEEDED":
51
+ return 3;
52
+ case "PROVIDER_AUTH":
53
+ return 4;
54
+ default:
55
+ return 1;
56
+ }
57
+ }
58
+ /** Prints an error; `redact` (the settings' live redactor) is applied to the message and hint so a stored key cannot leak. */
59
+ export function printError(io, error, redact = (text) => text) {
60
+ io.stderr.write(`error [${error.code}]: ${redact(error.message)}\n`);
61
+ if (error.hint)
62
+ io.stderr.write(`hint: ${redact(error.hint)}\n`);
63
+ }
64
+ export function usageError(message) {
65
+ return new NexoError({ code: "CONFIG_INVALID", message, hint: USAGE.trim() });
66
+ }
67
+ export function isTerminalStdio(stdio) {
68
+ return stdio.stdin.isTTY === true && stdio.stdout.isTTY === true && stdio.stderr.isTTY === true;
69
+ }
70
+ export function requireTerminal(stdio, what) {
71
+ if (!isTerminalStdio(stdio)) {
72
+ throw new NexoError({
73
+ code: "CONFIG_INVALID",
74
+ message: `${what} needs an interactive terminal (stdin, stdout and stderr must all be TTYs)`,
75
+ hint: `For scripts use \`nexo run "<instruction>"\`, \`nexo settings get|set|reset|set-key\` or \`nexo sessions\`.\n${USAGE.trim()}`,
76
+ });
77
+ }
78
+ }
@@ -0,0 +1,27 @@
1
+ import { parseArgs } from "node:util";
2
+ import { createSettings, nexoModels, runDoctor } from "../../core/src/index.js";
3
+ import { resolveNexoPaths } from "../../store/src/index.js";
4
+ const MARK = { ok: "ok ", warn: "warn", fail: "FAIL" };
5
+ export function formatDoctor(report) {
6
+ const lines = [];
7
+ for (const check of report.checks) {
8
+ lines.push(`${MARK[check.status]} ${check.message}`);
9
+ if (check.fix && check.status !== "ok")
10
+ lines.push(` fix: ${check.fix}`);
11
+ }
12
+ const failed = report.checks.filter((c) => c.status === "fail").length;
13
+ const warned = report.checks.filter((c) => c.status === "warn").length;
14
+ lines.push("", failed > 0 ? `${failed} check(s) failed, ${warned} warning(s)` : `All required checks passed, ${warned} warning(s)`);
15
+ return `${lines.join("\n")}\n`;
16
+ }
17
+ /** `nexo doctor [--json]`: read-only setup checks. Exit 0 when nothing failed, 1 otherwise. */
18
+ export function doctorCommand(args, io, options) {
19
+ const { values } = parseArgs({ args, options: { json: { type: "boolean" } } });
20
+ const env = options.env ?? process.env;
21
+ const cwd = options.cwd ?? process.cwd();
22
+ const paths = resolveNexoPaths(env);
23
+ const settings = createSettings({ paths, cwd, env, models: options.models ?? nexoModels() });
24
+ const report = runDoctor({ paths, settings, env, cwd });
25
+ io.stdout.write(values.json ? `${JSON.stringify(report, null, 2)}\n` : formatDoctor(report));
26
+ return report.ok ? 0 : 1;
27
+ }
@@ -0,0 +1,65 @@
1
+ import { parseArgs } from "node:util";
2
+ import { mineEvalCases } from "../../core/src/index.js";
3
+ import { parseOptimTarget, reviewProposedCase, revertGolden } from "../../store/src/index.js";
4
+ import { nonInteractivePrompter } from "../../tools/src/index.js";
5
+ import { escapeControl } from "../../tui/src/index.js";
6
+ import { usageError } from "./common.js";
7
+ import { openStore } from "./learn.js";
8
+ import { createRuntime } from "./runtime.js";
9
+ const firstLine = (s) => escapeControl(s.split("\n")[0]?.slice(0, 80) ?? "");
10
+ /** `nexo eval mine --target <t> [--days <n>]`: one mining pass; prints the cases it proposed and the ones waiting. */
11
+ export async function evalMineCommand(args, io, options) {
12
+ const { values } = parseArgs({ args, options: { target: { type: "string" }, days: { type: "string" } } });
13
+ if (!values.target)
14
+ throw usageError("nexo eval mine needs --target");
15
+ const days = values.days === undefined ? undefined : Number(values.days);
16
+ if (days !== undefined && !(Number.isInteger(days) && days > 0))
17
+ throw usageError("--days must be a positive integer");
18
+ const target = parseOptimTarget(values.target);
19
+ const runtime = createRuntime({ env: options.env ?? process.env, cwd: options.cwd ?? process.cwd(), prompter: nonInteractivePrompter, models: options.models });
20
+ try {
21
+ const result = await mineEvalCases(runtime.engine.env, target, days === undefined ? {} : { days });
22
+ io.stdout.write(`Considered ${result.considered} unreviewed runs of ${target.key} (${result.measure}); added ${result.added.length}${result.fallbackReason ? ` — embeddings failed: ${escapeControl(result.fallbackReason)}` : ""}\n`);
23
+ for (const c of result.waiting)
24
+ io.stdout.write(` proposed ${c.id} (${c.minedFrom?.length ?? 0} runs) ${firstLine(c.input)}\n`);
25
+ if (result.waiting.length > 0)
26
+ io.stdout.write("Accept with `nexo eval accept <id> [--expected <text>]`, or `nexo eval dismiss <id>`\n");
27
+ return 0;
28
+ }
29
+ finally {
30
+ await runtime.mcp?.close();
31
+ runtime.db.close();
32
+ }
33
+ }
34
+ /** `nexo eval accept <id> [--expected <text>]` and `nexo eval dismiss <id>`. */
35
+ export function evalReviewCommand(decision, args, io, options) {
36
+ const { values, positionals } = parseArgs({ args, allowPositionals: true, options: decision === "accept" ? { expected: { type: "string" } } : {} });
37
+ const id = positionals[0];
38
+ if (!id)
39
+ throw usageError(`nexo eval ${decision} needs a case id`);
40
+ const store = openStore(options);
41
+ try {
42
+ const expected = values.expected;
43
+ const row = reviewProposedCase(store.db, id, decision, { expected: expected ?? null, redact: store.redact, nowIso: new Date().toISOString() });
44
+ io.stdout.write(`${decision === "accept" ? "Accepted" : "Dismissed"} eval case ${row.id}${row.expected !== null && decision === "accept" ? " with a golden" : ""}\n`);
45
+ return 0;
46
+ }
47
+ finally {
48
+ store.close();
49
+ }
50
+ }
51
+ /** `nexo eval golden revert <id>`: back to the last human-approved golden. */
52
+ export function evalGoldenCommand(args, io, options) {
53
+ const [sub, id] = args;
54
+ if (sub !== "revert" || !id)
55
+ throw usageError("Usage: nexo eval golden revert <case-id>");
56
+ const store = openStore(options);
57
+ try {
58
+ const row = revertGolden(store.db, id, new Date().toISOString());
59
+ io.stdout.write(row.expected === null ? `Eval case ${row.id} has no golden now\n` : `Eval case ${row.id} is back on its ${row.goldenSource} golden\n`);
60
+ return 0;
61
+ }
62
+ finally {
63
+ store.close();
64
+ }
65
+ }
@@ -0,0 +1,67 @@
1
+ import { parseArgs } from "node:util";
2
+ import { calibrateJudge, loadConfig } from "../../core/src/index.js";
3
+ import { ensureNexoDirs, openDb, resolveNexoPaths } from "../../store/src/index.js";
4
+ import { escapeControl } from "../../tui/src/index.js";
5
+ import { usageError } from "./common.js";
6
+ import { evalGoldenCommand, evalMineCommand, evalReviewCommand } from "./eval-cases.js";
7
+ import { evalAddCommand, evalListCommand } from "./optimize.js";
8
+ function pct(value) {
9
+ return value === null ? "–" : `${(value * 100).toFixed(1)}%`;
10
+ }
11
+ /**
12
+ * `nexo eval judge [--judge <provider/id[+provider/id…]>]`: judge-vs-human agreement, stored for the UI.
13
+ * `nexo eval add …` and `nexo eval list …` manage the optimizer's eval cases; `nexo eval mine …` proposes cases from
14
+ * unreviewed runs, `nexo eval accept|dismiss <id>` decides a proposed case and `nexo eval golden revert <id>` undoes a climbed golden.
15
+ */
16
+ export async function evalCommand(args, io, options) {
17
+ const [sub, ...rest] = args;
18
+ if (sub === "add")
19
+ return evalAddCommand(rest, io, options);
20
+ if (sub === "list")
21
+ return evalListCommand(rest, io, options);
22
+ if (sub === "mine")
23
+ return evalMineCommand(rest, io, options);
24
+ if (sub === "accept" || sub === "dismiss")
25
+ return evalReviewCommand(sub, rest, io, options);
26
+ if (sub === "golden")
27
+ return evalGoldenCommand(rest, io, options);
28
+ if (sub !== "judge")
29
+ throw usageError(sub === undefined ? "nexo eval needs a subcommand" : `Unknown eval subcommand "${sub}"`);
30
+ const { values } = parseArgs({ args: rest, options: { judge: { type: "string" } } });
31
+ if (values.judge !== undefined && !values.judge.split("+").every((part) => /^[^/+\s]+\/\S+$/.test(part))) {
32
+ throw usageError("--judge must be provider/id, with several models joined by +");
33
+ }
34
+ const env = options.env ?? process.env;
35
+ const paths = resolveNexoPaths(env);
36
+ ensureNexoDirs(paths);
37
+ const { config } = loadConfig({ paths, cwd: options.cwd ?? process.cwd() });
38
+ const db = openDb(paths.db);
39
+ try {
40
+ const report = calibrateJudge(db, config, { judgeKey: values.judge, nowIso: new Date().toISOString() });
41
+ for (const warning of report.warnings)
42
+ io.stderr.write(`warning: ${escapeControl(warning)}\n`);
43
+ const m = report.matrix;
44
+ const cal = report.calibration;
45
+ io.stdout.write(`Judge ${escapeControl(report.judgeKey)} vs human verdicts\n`);
46
+ if (!cal) {
47
+ io.stdout.write(" No run has both a score from this judge and a human verdict yet.\n Review judged runs (the web UI review queue, or /done and /notdone in a session), then run this again.\n");
48
+ return 0;
49
+ }
50
+ io.stdout.write(` cases ${cal.cases}\n`);
51
+ io.stdout.write(` agreement ${cal.agreements} (${pct(cal.accuracy)})\n`);
52
+ io.stdout.write(` Cohen's κ ${cal.kappa === null ? "– (every verdict is in one class)" : cal.kappa.toFixed(3)}\n`);
53
+ io.stdout.write(` human done human not done\n`);
54
+ io.stdout.write(` judge pass ${String(m.bothPass).padStart(10)} ${String(m.judgePassHumanFail).padStart(14)}\n`);
55
+ io.stdout.write(` judge fail ${String(m.judgeFailHumanPass).padStart(10)} ${String(m.bothFail).padStart(14)}\n`);
56
+ io.stdout.write(` disagreements ${report.disagreements.length} (stored as judge_rubric eval cases)\n`);
57
+ for (const d of report.disagreements.slice(0, 10)) {
58
+ const first = escapeControl(d.instruction.split("\n")[0]?.slice(0, 60) ?? "");
59
+ io.stdout.write(` - ${d.runId} judge ${d.judgePassed ? "pass" : "fail"}, human ${d.verdict === "done" ? "done" : "not done"}: ${first}${d.comment ? ` — "${escapeControl(d.comment.slice(0, 80))}"` : ""}\n`);
60
+ }
61
+ io.stdout.write(`Saved calibration ${cal.id}\n`);
62
+ return 0;
63
+ }
64
+ finally {
65
+ db.close();
66
+ }
67
+ }
@@ -0,0 +1,186 @@
1
+ import { parseArgs } from "node:util";
2
+ import { createSettings, nexoModels } from "../../core/src/index.js";
3
+ import { ensureNexoDirs, resolveNexoPaths } from "../../store/src/index.js";
4
+ import { NexoError } from "../../telemetry/src/index.js";
5
+ import { nonInteractivePrompter } from "../../tools/src/index.js";
6
+ import { EXIT_SIGINT, exitCodeFor, printError, requireTerminal, usageError } from "./common.js";
7
+ import { createTtyLineAsker } from "./review.js";
8
+ import { createRuntime } from "./runtime.js";
9
+ import { readHiddenKey } from "./settings.js";
10
+ /** Thrown when the user presses Ctrl-C or input ends during a prompt. */
11
+ class Cancelled extends Error {
12
+ }
13
+ const TEST_BUDGET_USD = 0.05;
14
+ const CATALOG_LINES = 30;
15
+ const WELCOME = [
16
+ "Welcome to nexo.",
17
+ "nexo runs an AI agent on your machine, tracks what each run costs, and stores its data in your nexo home directory.",
18
+ "This setup picks two models (s1 for most work, s2 as the stronger fallback), stores their API keys, and makes one small test call.",
19
+ ].join("\n");
20
+ const NEXT_STEPS = [
21
+ "",
22
+ "Next steps:",
23
+ " nexo start a chat",
24
+ " nexo run \"<task>\" run one task",
25
+ " nexo ui open the run inspector",
26
+ " nexo doctor check your setup",
27
+ ].join("\n");
28
+ /** Model-influenced text shown on the terminal: control characters removed, length capped. */
29
+ function clean(text, max) {
30
+ const flat = text.replace(/[\u0000-\u001f\u007f-\u009f]+/g, " ").trim();
31
+ return flat.length > max ? `${flat.slice(0, max)}…` : flat;
32
+ }
33
+ async function initBody(args, io, options, stdio) {
34
+ const { values } = parseArgs({
35
+ args,
36
+ options: { yes: { type: "boolean" }, s1: { type: "string" }, s2: { type: "string" }, "skip-test": { type: "boolean" } },
37
+ });
38
+ const yes = values.yes === true;
39
+ const env = options.env ?? process.env;
40
+ const cwd = options.cwd ?? process.cwd();
41
+ const signal = options.signal;
42
+ const paths = resolveNexoPaths(env);
43
+ ensureNexoDirs(paths);
44
+ const settings = createSettings({ paths, cwd, env, models: options.models ?? nexoModels() });
45
+ const say = (text) => {
46
+ io.stderr.write(`${text}\n`);
47
+ };
48
+ let status = settings.setupStatus();
49
+ if (status.error) {
50
+ printError(io, status.error);
51
+ return 1;
52
+ }
53
+ // A finished setup is only reported; nothing is asked or redone.
54
+ if (!status.needed) {
55
+ say("Setup is complete: models s1 and s2 are set.");
56
+ for (const provider of status.providersWithoutKey)
57
+ say(` No API key for ${provider}. Run: nexo settings set-key ${provider}`);
58
+ say(NEXT_STEPS);
59
+ return 0;
60
+ }
61
+ if (yes) {
62
+ for (const role of status.missingModels) {
63
+ if (!values[role])
64
+ throw usageError(`nexo init --yes needs --${role} <provider/id>`);
65
+ }
66
+ }
67
+ else {
68
+ requireTerminal(stdio, "nexo init");
69
+ }
70
+ /** One question per readline interface, so the raw-mode key prompt never shares stdin with it. */
71
+ const ask = async (question) => {
72
+ const asker = createTtyLineAsker(stdio.stdin, process.stderr);
73
+ try {
74
+ const line = await asker.ask(question, signal);
75
+ if (line === null)
76
+ throw new Cancelled();
77
+ return line.trim();
78
+ }
79
+ finally {
80
+ asker.close?.();
81
+ }
82
+ };
83
+ say(WELCOME);
84
+ const catalog = settings.modelCatalog();
85
+ for (const role of status.missingModels) {
86
+ const key = `models.${role}`;
87
+ const given = values[role];
88
+ if (given) {
89
+ settings.setSettingFromString(key, given);
90
+ say(`Set ${key} = ${given}`);
91
+ continue;
92
+ }
93
+ say(`\nChoose the ${role} model (${role === "s1" ? "the default, used for most work" : "the stronger model used when s1 needs help"}).`);
94
+ say(`Providers: ${catalog.map((p) => p.provider).join(", ")}`);
95
+ let chosen = false;
96
+ for (let attempt = 0; attempt < 3 && !chosen; attempt++) {
97
+ const provider = await ask("Provider: ");
98
+ const found = catalog.find((p) => p.provider === provider);
99
+ if (found) {
100
+ say(found.models.slice(0, CATALOG_LINES).map((m) => ` ${m.ref}`).join("\n"));
101
+ if (found.models.length > CATALOG_LINES)
102
+ say(` … ${found.models.length - CATALOG_LINES} more`);
103
+ }
104
+ else {
105
+ say(`Unknown provider "${clean(provider, 40)}"; type one of the names above, or a full provider/id next.`);
106
+ }
107
+ const ref = await ask(`Model ${role} (provider/id): `);
108
+ try {
109
+ settings.setSettingFromString(key, ref);
110
+ say(`Set ${key} = ${ref}`);
111
+ chosen = true;
112
+ }
113
+ catch (error) {
114
+ say(error.message);
115
+ }
116
+ }
117
+ if (!chosen) {
118
+ throw new NexoError({ code: "INVALID_REQUEST", message: `No valid ${role} model chosen`, hint: `Run \`nexo init\` again, or \`nexo settings set ${key} <provider/id>\`` });
119
+ }
120
+ }
121
+ status = settings.setupStatus();
122
+ for (const provider of status.providersWithoutKey) {
123
+ if (yes) {
124
+ say(`warning: no API key for ${provider}; set its environment variable or run: nexo settings set-key ${provider}`);
125
+ continue;
126
+ }
127
+ say(`\nPress Enter at the prompt to skip ${provider} (fine for keyless or local providers).`);
128
+ const key = await readHiddenKey(stdio.stdin, io.stderr, provider, signal);
129
+ if (key === null)
130
+ throw new Cancelled();
131
+ if (key === "") {
132
+ say(`Skipped the ${provider} key`);
133
+ continue;
134
+ }
135
+ try {
136
+ settings.setKey(provider, key);
137
+ say(`Stored the ${provider} key`);
138
+ }
139
+ catch (error) {
140
+ say(error.message);
141
+ }
142
+ }
143
+ if (values["skip-test"]) {
144
+ say("\nSkipped the test call.");
145
+ say(NEXT_STEPS);
146
+ return 0;
147
+ }
148
+ say(`\nTest call on s1 (budget $${TEST_BUDGET_USD.toFixed(2)})…`);
149
+ const runtime = createRuntime({ env, cwd, prompter: nonInteractivePrompter, models: options.models });
150
+ let result;
151
+ try {
152
+ result = await runtime.engine.run({ instruction: "Reply with the single word: ready", model: "s1", budgetUsd: TEST_BUDGET_USD }, signal);
153
+ }
154
+ finally {
155
+ await runtime.mcp?.close();
156
+ }
157
+ if (result.status === "succeeded") {
158
+ say(`✓ s1 answered "${clean(result.output, 80)}" · $${result.costUsd.toFixed(4)}${result.costUnknown ? " (unpriced)" : ""}`);
159
+ say(NEXT_STEPS);
160
+ return 0;
161
+ }
162
+ say(`✗ test call ${result.status}`);
163
+ if (result.error)
164
+ printError(io, result.error, runtime.redact);
165
+ say("Run `nexo doctor` to check keys and config, then `nexo init --skip-test` or fix the cause and retry.");
166
+ if (result.status === "aborted")
167
+ return EXIT_SIGINT;
168
+ return result.error ? exitCodeFor(result.error.code) : 1;
169
+ }
170
+ /**
171
+ * `nexo init [--yes] [--s1 <provider/id>] [--s2 <provider/id>] [--skip-test]`: guided first-time setup on top of
172
+ * `Settings.setupStatus()`. Only missing models are asked; a finished setup is reported and left alone. With `--yes`
173
+ * nothing is prompted: models come from flags and a missing key is a warning, so the test call decides the exit code.
174
+ */
175
+ export async function initCommand(args, io, options, stdio) {
176
+ try {
177
+ return await initBody(args, io, options, stdio);
178
+ }
179
+ catch (error) {
180
+ if (error instanceof Cancelled) {
181
+ io.stderr.write("cancelled\n");
182
+ return EXIT_SIGINT;
183
+ }
184
+ throw error;
185
+ }
186
+ }