@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
@@ -0,0 +1,151 @@
1
+ import { appendFileSync, existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
2
+ import { dirname, join, relative, resolve, sep } from "node:path";
3
+ import { NexoError } from "../../telemetry/src/index.js";
4
+ import { copyWorkspaceTree, emptyDir } from "./workspace-copy.js";
5
+ const SUBDIRS = ["artifacts", "context", "workspace", "tool_outputs", "scores", "subagents"];
6
+ /** One trajectory's directory (`~/.nexo/runs/{id}` or `.../subagents/{id}`). Every write is redacted. */
7
+ export class RunDir {
8
+ id;
9
+ root;
10
+ redact;
11
+ constructor(root, id, redact) {
12
+ this.root = root;
13
+ this.id = id;
14
+ this.redact = redact;
15
+ }
16
+ static create(runsRoot, id, redact) {
17
+ const dir = new RunDir(join(runsRoot, id), id, redact);
18
+ dir.init();
19
+ return dir;
20
+ }
21
+ child(childId) {
22
+ const dir = new RunDir(join(this.root, "subagents", childId), childId, this.redact);
23
+ dir.init();
24
+ return dir;
25
+ }
26
+ get workspaceDir() {
27
+ return join(this.root, "workspace");
28
+ }
29
+ get changesDir() {
30
+ return join(this.root, "changes");
31
+ }
32
+ get artifactsDir() {
33
+ return join(this.root, "artifacts");
34
+ }
35
+ get toolOutputsDir() {
36
+ return join(this.root, "tool_outputs");
37
+ }
38
+ get contextDir() {
39
+ return join(this.root, "context");
40
+ }
41
+ init() {
42
+ try {
43
+ for (const sub of SUBDIRS)
44
+ mkdirSync(join(this.root, sub), { recursive: true });
45
+ }
46
+ catch (cause) {
47
+ throw new NexoError({ code: "STORE_IO", message: `Cannot create run directory ${this.root}`, cause });
48
+ }
49
+ }
50
+ /**
51
+ * Copies a previous turn's workspace (`from.dir`, of run `from.runId`) into the empty `workspace/` folder and returns
52
+ * the bytes of regular files copied (see `copyWorkspaceTree`: a clone on macOS APFS and on Linux file systems with
53
+ * reflinks, a plain copy otherwise; symlinks copied as links). On failure or abort the folder is emptied again; a
54
+ * failure throws STORE_IO naming the source, an abort INTERNAL.
55
+ */
56
+ async copyIntoWorkspace(from, options = {}) {
57
+ try {
58
+ return await copyWorkspaceTree(from.dir, this.workspaceDir, options);
59
+ }
60
+ catch (cause) {
61
+ try {
62
+ await emptyDir(this.workspaceDir);
63
+ }
64
+ catch { }
65
+ if (options.signal?.aborted) {
66
+ throw new NexoError({ code: "INTERNAL", message: `The copy of run ${from.runId}'s workspace was aborted`, context: { source: from.dir }, cause });
67
+ }
68
+ throw new NexoError({
69
+ code: "STORE_IO",
70
+ message: `Cannot copy the workspace of the previous turn (run ${from.runId}, ${from.dir}) into ${this.workspaceDir}`,
71
+ hint: `Check that ${from.dir} is readable and the disk has space; remove that folder to start the next turn from the turn before it (or empty)`,
72
+ context: { sourceRunId: from.runId, source: from.dir, workspace: this.workspaceDir },
73
+ cause,
74
+ });
75
+ }
76
+ }
77
+ writeRunJson(run) {
78
+ const target = join(this.root, "run.json");
79
+ const tmp = `${target}.tmp`;
80
+ writeFileSync(tmp, `${JSON.stringify(this.redact(run), null, 2)}\n`);
81
+ renameSync(tmp, target);
82
+ }
83
+ appendTrajectory(span) {
84
+ appendFileSync(join(this.root, "trajectory.jsonl"), `${JSON.stringify(this.redact(span))}\n`);
85
+ }
86
+ writeArtifact(relPath, content) {
87
+ return this.writeConfined(this.artifactsDir, relPath, content);
88
+ }
89
+ writeContext(relPath, content) {
90
+ return this.writeConfined(this.contextDir, relPath, content);
91
+ }
92
+ get scoresDir() {
93
+ return join(this.root, "scores");
94
+ }
95
+ /** Writes a scorer output (judge responses, command logs) under `scores/` and returns its path relative to the run directory. */
96
+ writeScoreFile(relPath, content) {
97
+ this.writeConfined(this.scoresDir, relPath, content);
98
+ return `scores/${relPath}`;
99
+ }
100
+ /** Stores a large tool result and returns its path relative to the run directory. */
101
+ writeToolOutput(spanId, content) {
102
+ this.writeConfined(this.toolOutputsDir, `${spanId}.txt`, content);
103
+ return `tool_outputs/${spanId}.txt`;
104
+ }
105
+ resolveFile(relPath) {
106
+ return confine(this.root, relPath);
107
+ }
108
+ writeConfined(base, relPath, content) {
109
+ const target = confine(base, relPath);
110
+ mkdirSync(dirname(target), { recursive: true });
111
+ writeFileSync(target, this.redact(content));
112
+ return target;
113
+ }
114
+ }
115
+ /**
116
+ * Lexical confinement for names inside a run directory (artifact and tool-output paths that nexo itself chooses).
117
+ * The agent's workspace uses `resolveConfined` in `@nexo/tools`, which resolves through realpath instead.
118
+ */
119
+ function confine(base, relPath) {
120
+ const target = resolve(base, relPath);
121
+ if (target !== base && !target.startsWith(base + sep)) {
122
+ throw new NexoError({
123
+ code: "STORE_IO",
124
+ message: `Path "${relPath}" escapes ${base}`,
125
+ context: { base, relPath, relative: relative(base, target) },
126
+ });
127
+ }
128
+ return target;
129
+ }
130
+ export function readRunJson(dir) {
131
+ return JSON.parse(readFileSync(join(dir, "run.json"), "utf8"));
132
+ }
133
+ /** Reads trajectory.jsonl, skipping unparsable lines (such as a truncated last line); later records for the same span id replace earlier ones, keeping first-seen order. */
134
+ export function readTrajectory(dir) {
135
+ const file = join(dir, "trajectory.jsonl");
136
+ if (!existsSync(file))
137
+ return [];
138
+ const byId = new Map();
139
+ for (const line of readFileSync(file, "utf8").split("\n")) {
140
+ if (!line.trim())
141
+ continue;
142
+ try {
143
+ const span = JSON.parse(line);
144
+ byId.set(span.id, span);
145
+ }
146
+ catch {
147
+ continue;
148
+ }
149
+ }
150
+ return [...byId.values()];
151
+ }
@@ -0,0 +1,310 @@
1
+ import { existsSync, readFileSync, renameSync, writeFileSync } from "node:fs";
2
+ import { join } from "node:path";
3
+ import { checkOffset } from "./cursor.js";
4
+ import { invalidRequest } from "./errors.js";
5
+ import { decodeRunScore, RUN_SCORE_SQL } from "./scores.js";
6
+ import { insertRow, updateById } from "./sql.js";
7
+ const COLUMNS = {
8
+ id: "id",
9
+ parentRunId: "parent_run_id",
10
+ rootRunId: "root_run_id",
11
+ dirPath: "dir_path",
12
+ instruction: "instruction",
13
+ skill: "skill",
14
+ status: "status",
15
+ configSnapshotHash: "config_snapshot_hash",
16
+ artifactSetId: "artifact_set_id",
17
+ modelFinal: "model_final",
18
+ tierFinal: "tier_final",
19
+ escalations: "escalations",
20
+ startedAt: "started_at",
21
+ endedAt: "ended_at",
22
+ costUsd: "cost_usd",
23
+ costUnknown: "cost_unknown",
24
+ tokensIn: "tokens_in",
25
+ tokensOut: "tokens_out",
26
+ pid: "pid",
27
+ error: "error_json",
28
+ sessionId: "session_id",
29
+ turnIndex: "turn_index",
30
+ optimRunId: "optim_run_id",
31
+ };
32
+ function encode(key, value) {
33
+ if (key === "costUnknown")
34
+ return value ? 1 : 0;
35
+ if (key === "error")
36
+ return value === null || value === undefined ? null : JSON.stringify(value);
37
+ return (value ?? null);
38
+ }
39
+ function decode(row) {
40
+ return {
41
+ id: String(row.id),
42
+ parentRunId: row.parent_run_id ?? null,
43
+ rootRunId: String(row.root_run_id),
44
+ dirPath: String(row.dir_path),
45
+ instruction: String(row.instruction),
46
+ skill: row.skill ?? null,
47
+ status: row.status,
48
+ configSnapshotHash: String(row.config_snapshot_hash),
49
+ artifactSetId: row.artifact_set_id ?? null,
50
+ modelFinal: row.model_final ?? null,
51
+ tierFinal: row.tier_final ?? null,
52
+ escalations: Number(row.escalations),
53
+ startedAt: String(row.started_at),
54
+ endedAt: row.ended_at ?? null,
55
+ costUsd: Number(row.cost_usd),
56
+ costUnknown: Number(row.cost_unknown) === 1,
57
+ tokensIn: Number(row.tokens_in),
58
+ tokensOut: Number(row.tokens_out),
59
+ pid: row.pid === null || row.pid === undefined ? null : Number(row.pid),
60
+ error: row.error_json ? JSON.parse(String(row.error_json)) : null,
61
+ sessionId: row.session_id ?? null,
62
+ turnIndex: row.turn_index === null || row.turn_index === undefined ? null : Number(row.turn_index),
63
+ optimRunId: row.optim_run_id ?? null,
64
+ };
65
+ }
66
+ export function insertRun(db, row, replace = false) {
67
+ insertRow(db, "runs", COLUMNS, { ...row }, encode, replace);
68
+ }
69
+ export function updateRun(db, id, patch) {
70
+ updateById(db, "runs", COLUMNS, id, patch, encode);
71
+ }
72
+ export function getRun(db, id) {
73
+ const row = db.prepare("SELECT * FROM runs WHERE id = ?").get(id);
74
+ return row ? decode(row) : undefined;
75
+ }
76
+ export function listRuns(db, filter = {}) {
77
+ const where = [];
78
+ const args = [];
79
+ if (filter.status) {
80
+ where.push("status = ?");
81
+ args.push(filter.status);
82
+ }
83
+ if (filter.rootOnly)
84
+ where.push("parent_run_id IS NULL");
85
+ if (filter.since) {
86
+ where.push("started_at >= ?");
87
+ args.push(filter.since);
88
+ }
89
+ const sql = `SELECT * FROM runs ${where.length ? `WHERE ${where.join(" AND ")}` : ""} ORDER BY started_at DESC, id DESC LIMIT ?`;
90
+ return db
91
+ .prepare(sql)
92
+ .all(...args, filter.limit ?? 100)
93
+ .map(decode);
94
+ }
95
+ export const RUN_STATUSES = ["running", "succeeded", "failed", "aborted", "budget_exceeded"];
96
+ /** Default and maximum page sizes for `queryRuns`. */
97
+ export const DEFAULT_RUN_PAGE = 50;
98
+ export const MAX_RUN_PAGE = 200;
99
+ /** Longest instruction kept in a run summary; the full text stays in run.json. */
100
+ export const SUMMARY_INSTRUCTION_CHARS = 500;
101
+ const SINCE_RE = /^\d{4}-\d{2}-\d{2}(T\d{2}:\d{2}(:\d{2}(\.\d{1,3})?)?Z)?$/;
102
+ /**
103
+ * Canonical `YYYY-MM-DDTHH:MM:SS.mmmZ` form of a `since` filter (`YYYY-MM-DD` or a UTC ISO timestamp), so it compares
104
+ * correctly as a string against `started_at`. Impossible dates such as 2026-02-30 are rejected rather than rolled over.
105
+ */
106
+ export function normalizeSince(since) {
107
+ const ms = SINCE_RE.test(since) ? Date.parse(since) : Number.NaN;
108
+ const iso = Number.isFinite(ms) ? new Date(ms).toISOString() : "";
109
+ if (iso.slice(0, 10) !== since.slice(0, 10)) {
110
+ throw invalidRequest("since must be YYYY-MM-DD or a UTC ISO timestamp such as 2026-10-10T09:30:00Z", { since });
111
+ }
112
+ return iso;
113
+ }
114
+ export function isRunStatus(value) {
115
+ return typeof value === "string" && RUN_STATUSES.includes(value);
116
+ }
117
+ /** Opaque keyset cursor for the (started_at DESC, id DESC) order. */
118
+ export function encodeRunCursor(startedAt, id) {
119
+ return Buffer.from(JSON.stringify([startedAt, id])).toString("base64url");
120
+ }
121
+ export function decodeRunCursor(cursor) {
122
+ try {
123
+ const value = JSON.parse(Buffer.from(cursor, "base64url").toString("utf8"));
124
+ if (Array.isArray(value) && value.length === 2 && typeof value[0] === "string" && typeof value[1] === "string") {
125
+ return { startedAt: value[0], id: value[1] };
126
+ }
127
+ }
128
+ catch {
129
+ // Falls through to the error below.
130
+ }
131
+ throw invalidRequest("cursor is not a cursor returned by this API", { cursor });
132
+ }
133
+ const SUMMARY_SELECT = `SELECT r.*,
134
+ (SELECT COUNT(*) FROM runs c WHERE c.parent_run_id = r.id) AS child_count,
135
+ (SELECT f.verdict FROM feedback f WHERE f.run_id = r.id ORDER BY f.created_at DESC, f.id DESC LIMIT 1) AS verdict,
136
+ (SELECT s.title FROM sessions s WHERE s.id = r.session_id) AS session_title,
137
+ ${RUN_SCORE_SQL} AS score_json
138
+ FROM runs r`;
139
+ function decodeSummary(row) {
140
+ const run = decode(row);
141
+ const instruction = run.instruction.length > SUMMARY_INSTRUCTION_CHARS ? `${run.instruction.slice(0, SUMMARY_INSTRUCTION_CHARS)}…` : run.instruction;
142
+ return {
143
+ id: run.id,
144
+ parentRunId: run.parentRunId,
145
+ rootRunId: run.rootRunId,
146
+ instruction,
147
+ skill: run.skill,
148
+ status: run.status,
149
+ modelFinal: run.modelFinal,
150
+ tierFinal: run.tierFinal,
151
+ startedAt: run.startedAt,
152
+ endedAt: run.endedAt,
153
+ costUsd: run.costUsd,
154
+ costUnknown: run.costUnknown,
155
+ tokensIn: run.tokensIn,
156
+ tokensOut: run.tokensOut,
157
+ childCount: Number(row.child_count ?? 0),
158
+ verdict: row.verdict ?? null,
159
+ error: run.error,
160
+ sessionId: run.sessionId ?? null,
161
+ turnIndex: run.turnIndex ?? null,
162
+ sessionTitle: row.session_title ?? null,
163
+ optimRunId: run.optimRunId ?? null,
164
+ score: decodeRunScore(row.score_json),
165
+ };
166
+ }
167
+ /** Filtered, keyset-paginated run summaries, newest first. Invalid filters throw INVALID_REQUEST. */
168
+ export function queryRuns(db, query = {}) {
169
+ const limit = query.limit ?? DEFAULT_RUN_PAGE;
170
+ if (!Number.isInteger(limit) || limit < 1 || limit > MAX_RUN_PAGE) {
171
+ throw invalidRequest(`limit must be an integer from 1 to ${MAX_RUN_PAGE}`, { limit });
172
+ }
173
+ if (query.status !== undefined && !isRunStatus(query.status)) {
174
+ throw invalidRequest(`status must be one of ${RUN_STATUSES.join(", ")}`, { status: query.status });
175
+ }
176
+ const since = query.since === undefined ? undefined : normalizeSince(query.since);
177
+ const where = [];
178
+ const args = [];
179
+ if (query.rootOnly ?? true)
180
+ where.push("r.parent_run_id IS NULL");
181
+ if (query.status) {
182
+ where.push("r.status = ?");
183
+ args.push(query.status);
184
+ }
185
+ if (query.skill) {
186
+ where.push("r.skill = ?");
187
+ args.push(query.skill);
188
+ }
189
+ if (query.sessionId) {
190
+ where.push("r.session_id = ?");
191
+ args.push(query.sessionId);
192
+ }
193
+ if (query.oneShot)
194
+ where.push("r.session_id IS NULL");
195
+ if (query.optimRunId) {
196
+ where.push("r.optim_run_id = ?");
197
+ args.push(query.optimRunId);
198
+ }
199
+ else {
200
+ where.push("r.optim_run_id IS NULL");
201
+ }
202
+ if (since) {
203
+ where.push("r.started_at >= ?");
204
+ args.push(since);
205
+ }
206
+ if (query.reviewed === true)
207
+ where.push("EXISTS (SELECT 1 FROM feedback f WHERE f.run_id = r.id)");
208
+ if (query.reviewed === false)
209
+ where.push("r.status != 'running' AND NOT EXISTS (SELECT 1 FROM feedback f WHERE f.run_id = r.id)");
210
+ if (query.scored === true)
211
+ where.push("EXISTS (SELECT 1 FROM scores s WHERE s.run_id = r.id)");
212
+ if (query.scored === false)
213
+ where.push("r.status != 'running' AND NOT EXISTS (SELECT 1 FROM scores s WHERE s.run_id = r.id)");
214
+ const offset = checkOffset(query.offset);
215
+ const total = Number(db.prepare(`SELECT COUNT(*) AS n FROM runs r ${where.length ? `WHERE ${where.join(" AND ")}` : ""}`).get(...args).n);
216
+ if (query.cursor !== undefined) {
217
+ const after = decodeRunCursor(query.cursor);
218
+ where.push("(r.started_at < ? OR (r.started_at = ? AND r.id < ?))");
219
+ args.push(after.startedAt, after.startedAt, after.id);
220
+ }
221
+ const sql = `${SUMMARY_SELECT} ${where.length ? `WHERE ${where.join(" AND ")}` : ""} ORDER BY r.started_at DESC, r.id DESC LIMIT ? OFFSET ?`;
222
+ const rows = db.prepare(sql).all(...args, limit + 1, offset);
223
+ const runs = rows.slice(0, limit).map(decodeSummary);
224
+ const last = runs.at(-1);
225
+ return { runs, nextCursor: rows.length > limit && last ? encodeRunCursor(last.startedAt, last.id) : null, total };
226
+ }
227
+ export function getRunSummary(db, id) {
228
+ return getRunWithSummary(db, id)?.summary;
229
+ }
230
+ /** The full row (with `dirPath`) and the summary of one run, read with a single query. */
231
+ export function getRunWithSummary(db, id) {
232
+ const row = db.prepare(`${SUMMARY_SELECT} WHERE r.id = ?`).get(id);
233
+ return row ? { run: decode(row), summary: decodeSummary(row) } : undefined;
234
+ }
235
+ export function listChildSummaries(db, parentRunId) {
236
+ return db.prepare(`${SUMMARY_SELECT} WHERE r.parent_run_id = ? ORDER BY r.started_at, r.id`).all(parentRunId).map(decodeSummary);
237
+ }
238
+ /** Deepest subagent nesting followed by `descendantRunIds`; bounds the walk if the parent links form a loop. */
239
+ export const MAX_RUN_DEPTH = 64;
240
+ /** The run and all of its descendants (subagents at any depth), the run itself first. A parent loop cannot hang it. */
241
+ export function descendantRunIds(db, runId) {
242
+ return db
243
+ .prepare(`WITH RECURSIVE tree(id, depth) AS (
244
+ SELECT id, 0 FROM runs WHERE id = ?
245
+ UNION SELECT r.id, t.depth + 1 FROM runs r JOIN tree t ON r.parent_run_id = t.id WHERE t.depth < ${MAX_RUN_DEPTH}
246
+ ) SELECT id FROM tree GROUP BY id ORDER BY MIN(depth), id`)
247
+ .all(runId)
248
+ .map((row) => String(row.id));
249
+ }
250
+ export function listChildRuns(db, parentRunId) {
251
+ return db.prepare("SELECT * FROM runs WHERE parent_run_id = ? ORDER BY started_at, id").all(parentRunId).map(decode);
252
+ }
253
+ export function isPidAlive(pid) {
254
+ try {
255
+ process.kill(pid, 0);
256
+ return true;
257
+ }
258
+ catch (error) {
259
+ return error.code === "EPERM";
260
+ }
261
+ }
262
+ /**
263
+ * Ends the spans a dead process left running at the run's last recorded activity (the latest span start or end), not when
264
+ * the crash was noticed, which can be hours later. Returns that time, or null when the run has no spans.
265
+ */
266
+ function closeOpenSpans(db, runId) {
267
+ const row = db.prepare("SELECT MAX(COALESCE(ended_at, started_at)) AS t FROM spans WHERE run_id = ?").all(runId)[0];
268
+ const last = row && typeof row.t === "string" ? row.t : null;
269
+ if (last === null)
270
+ return null;
271
+ db.prepare("UPDATE spans SET status = 'error', ended_at = ?, attrs_json = json_set(attrs_json, '$.interrupted', 1) WHERE run_id = ? AND status = 'running'").run(last, runId);
272
+ return last;
273
+ }
274
+ /** Rewrites `<dir>/run.json` as aborted. A missing or unreadable file is left alone; `nexo reindex` reports unreadable ones. */
275
+ function markRunJsonAborted(dir, nowIso, error) {
276
+ const file = join(dir, "run.json");
277
+ if (!existsSync(file))
278
+ return;
279
+ try {
280
+ const json = JSON.parse(readFileSync(file, "utf8"));
281
+ writeFileSync(`${file}.tmp`, `${JSON.stringify({ ...json, status: "aborted", endedAt: nowIso, error }, null, 2)}\n`);
282
+ renameSync(`${file}.tmp`, file);
283
+ }
284
+ catch {
285
+ return;
286
+ }
287
+ }
288
+ /**
289
+ * Marks runs left `running` by processes that no longer exist (runs without a recorded pid are left alone) as `aborted`, in SQLite and in their run.json.
290
+ * Returns the affected ids.
291
+ */
292
+ export function recoverCrashedRuns(db, isAlive, nowIso) {
293
+ const stuck = db.prepare("SELECT id, pid, dir_path FROM runs WHERE status = 'running' AND pid IS NOT NULL").all();
294
+ const ids = [];
295
+ for (const row of stuck) {
296
+ const pid = Number(row.pid);
297
+ if (isAlive(pid))
298
+ continue;
299
+ const error = {
300
+ code: "INTERNAL",
301
+ message: `The nexo process (pid ${pid}) exited while this run was running`,
302
+ retryable: false,
303
+ };
304
+ const endedAt = closeOpenSpans(db, String(row.id)) ?? nowIso;
305
+ updateRun(db, String(row.id), { status: "aborted", endedAt, error });
306
+ markRunJsonAborted(String(row.dir_path), endedAt, error);
307
+ ids.push(String(row.id));
308
+ }
309
+ return ids;
310
+ }
@@ -0,0 +1,92 @@
1
+ import { insertRow } from "./sql.js";
2
+ const COLUMNS = {
3
+ id: "id",
4
+ runId: "run_id",
5
+ round: "round",
6
+ scorerKind: "scorer_kind",
7
+ scorerType: "scorer_type",
8
+ scorerName: "scorer_name",
9
+ status: "status",
10
+ value: "value",
11
+ passed: "passed",
12
+ rationale: "rationale",
13
+ criteria: "criteria_json",
14
+ details: "details_json",
15
+ error: "error_json",
16
+ model: "model",
17
+ costUsd: "cost_usd",
18
+ costUnknown: "cost_unknown",
19
+ createdAt: "created_at",
20
+ };
21
+ function encode(key, value) {
22
+ if (key === "costUnknown")
23
+ return value ? 1 : 0;
24
+ if (key === "passed")
25
+ return value === null || value === undefined ? null : value ? 1 : 0;
26
+ if (key === "details")
27
+ return JSON.stringify(value ?? {});
28
+ if (key === "criteria" || key === "error")
29
+ return value === null || value === undefined ? null : JSON.stringify(value);
30
+ return (value ?? null);
31
+ }
32
+ function decode(row) {
33
+ const json = (v) => (v === null || v === undefined ? null : JSON.parse(String(v)));
34
+ return {
35
+ id: String(row.id),
36
+ runId: String(row.run_id),
37
+ round: Number(row.round),
38
+ scorerKind: row.scorer_kind,
39
+ scorerType: String(row.scorer_type),
40
+ scorerName: String(row.scorer_name),
41
+ status: row.status,
42
+ value: row.value === null || row.value === undefined ? null : Number(row.value),
43
+ passed: row.passed === null || row.passed === undefined ? null : Number(row.passed) === 1,
44
+ rationale: String(row.rationale ?? ""),
45
+ criteria: json(row.criteria_json),
46
+ details: json(row.details_json) ?? {},
47
+ error: json(row.error_json),
48
+ model: row.model ?? null,
49
+ costUsd: Number(row.cost_usd),
50
+ costUnknown: Number(row.cost_unknown) === 1,
51
+ createdAt: String(row.created_at),
52
+ };
53
+ }
54
+ export function insertScore(db, row) {
55
+ insertRow(db, "scores", COLUMNS, { ...row }, encode);
56
+ }
57
+ /** Every score of a run, by round and then in insertion order. */
58
+ export function listScores(db, runId) {
59
+ return db.prepare("SELECT * FROM scores WHERE run_id = ? ORDER BY round, rowid").all(runId).map(decode);
60
+ }
61
+ /** Inserts scores taken from run.json during reindex, unless the run already has scores. */
62
+ export function restoreScores(db, runId, rows) {
63
+ const existing = Number(db.prepare("SELECT COUNT(*) AS n FROM scores WHERE run_id = ?").get(runId)?.n ?? 0);
64
+ if (existing > 0)
65
+ return 0;
66
+ let restored = 0;
67
+ for (const row of rows) {
68
+ if (typeof row?.id !== "string" || typeof row.scorerName !== "string")
69
+ continue;
70
+ insertScore(db, { ...row, runId });
71
+ restored++;
72
+ }
73
+ return restored;
74
+ }
75
+ /** The SQL expression for `RunScore` of the run aliased `r`, as a JSON object; `scorers` and `failedScorers` are 0 when unscored. */
76
+ export const RUN_SCORE_SQL = `(SELECT json_object(
77
+ 'value', AVG(CASE WHEN s.status = 'ok' THEN s.value END),
78
+ 'passed', MIN(CASE WHEN s.status = 'ok' THEN s.passed END),
79
+ 'scorers', SUM(CASE WHEN s.status = 'ok' THEN 1 ELSE 0 END),
80
+ 'failedScorers', SUM(CASE WHEN s.status = 'failed' THEN 1 ELSE 0 END))
81
+ FROM scores s WHERE s.run_id = r.id AND s.round = (SELECT MAX(s2.round) FROM scores s2 WHERE s2.run_id = r.id))`;
82
+ /** Decodes the `RUN_SCORE_SQL` column; null for a run without scores. */
83
+ export function decodeRunScore(value) {
84
+ if (typeof value !== "string")
85
+ return null;
86
+ const raw = JSON.parse(value);
87
+ const scorers = Number(raw.scorers ?? 0);
88
+ const failedScorers = Number(raw.failedScorers ?? 0);
89
+ if (scorers === 0 && failedScorers === 0)
90
+ return null;
91
+ return { value: raw.value === null ? null : Number(raw.value), passed: raw.passed === null ? null : Number(raw.passed) === 1, scorers, failedScorers };
92
+ }