@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,106 @@
1
+ import { NexoError } from "./errors.js";
2
+ export const REDACTED = "[REDACTED]";
3
+ const BUILTIN_PATTERNS = [
4
+ /sk-ant-[A-Za-z0-9_-]{16,}/g,
5
+ /sk-[A-Za-z0-9_-]{16,}/g,
6
+ /AIza[0-9A-Za-z_-]{35}/g,
7
+ /gh[pousr]_[A-Za-z0-9]{36,}/g,
8
+ /xox[abprs]-[A-Za-z0-9-]{10,}/g,
9
+ /AKIA[0-9A-Z]{16}/g,
10
+ /Bearer\s+[A-Za-z0-9._~+/-]{16,}=*/g,
11
+ ];
12
+ const SENSITIVE_KEY = /^(api[_-]?key|authorization|password|secret|token|access[_-]?token|refresh[_-]?token|x-api-key)$/i;
13
+ /** Shortest value a SecretSet accepts: shorter values ("none", "ab") would corrupt ordinary text when replaced. */
14
+ export const MIN_SECRET_LENGTH = 8;
15
+ /** True when the text contains a match of a built-in secret pattern (an API key or token). */
16
+ export function containsSecret(text) {
17
+ return BUILTIN_PATTERNS.some((re) => new RegExp(re.source).test(text));
18
+ }
19
+ export function createSecretSet(initial = []) {
20
+ const set = new Set();
21
+ let sorted = [];
22
+ const add = (value) => {
23
+ if (value.length < MIN_SECRET_LENGTH)
24
+ return false;
25
+ if (set.has(value))
26
+ return true;
27
+ set.add(value);
28
+ sorted = [...set].sort((a, b) => b.length - a.length);
29
+ return true;
30
+ };
31
+ for (const value of initial)
32
+ add(value);
33
+ return {
34
+ add,
35
+ has: (value) => set.has(value),
36
+ get size() {
37
+ return set.size;
38
+ },
39
+ values: () => sorted,
40
+ };
41
+ }
42
+ export function createMutableRedactor(initial) {
43
+ let current = initial;
44
+ const redact = ((value) => current(value));
45
+ redact.replace = (next) => {
46
+ current = next;
47
+ };
48
+ return redact;
49
+ }
50
+ /** Returns a pure function that deep-copies a value with secrets replaced by `[REDACTED]`. */
51
+ export function createRedactor(extraPatterns = [], options = {}) {
52
+ const patterns = [...BUILTIN_PATTERNS];
53
+ for (const source of extraPatterns) {
54
+ if (source === "") {
55
+ throw new NexoError({
56
+ code: "CONFIG_INVALID",
57
+ message: "Empty redaction pattern",
58
+ hint: "Remove empty strings from redaction.patterns in your nexo config",
59
+ });
60
+ }
61
+ try {
62
+ patterns.push(new RegExp(source, "g"));
63
+ }
64
+ catch (cause) {
65
+ throw new NexoError({
66
+ code: "CONFIG_INVALID",
67
+ message: `Invalid redaction pattern: ${source}`,
68
+ hint: "Fix redaction.patterns in your nexo config",
69
+ context: { pattern: source },
70
+ cause,
71
+ });
72
+ }
73
+ }
74
+ const secrets = options.secrets;
75
+ const redactString = (text) => {
76
+ let out = text;
77
+ if (secrets)
78
+ for (const secret of secrets.values())
79
+ if (out.includes(secret))
80
+ out = out.split(secret).join(REDACTED);
81
+ return patterns.reduce((acc, re) => acc.replace(re, REDACTED), out);
82
+ };
83
+ /** `ancestors` holds only the objects on the current path, so shared non-circular references are copied, not marked. */
84
+ const walk = (value, ancestors) => {
85
+ if (typeof value === "string")
86
+ return redactString(value);
87
+ if (value === null || typeof value !== "object")
88
+ return value;
89
+ if (ancestors.includes(value))
90
+ return "[Circular]";
91
+ ancestors.push(value);
92
+ try {
93
+ if (Array.isArray(value))
94
+ return value.map((item) => walk(item, ancestors));
95
+ const out = {};
96
+ for (const [key, item] of Object.entries(value)) {
97
+ out[key] = SENSITIVE_KEY.test(key) && item !== null && item !== undefined ? REDACTED : walk(item, ancestors);
98
+ }
99
+ return out;
100
+ }
101
+ finally {
102
+ ancestors.pop();
103
+ }
104
+ };
105
+ return (value) => walk(value, []);
106
+ }
@@ -0,0 +1,269 @@
1
+ import { spawn } from "node:child_process";
2
+ import { existsSync, mkdirSync, readFileSync, realpathSync, writeFileSync } from "node:fs";
3
+ import { dirname, relative, sep } from "node:path";
4
+ import { StringDecoder } from "node:string_decoder";
5
+ import { NexoError } from "../../telemetry/src/index.js";
6
+ import { Type } from "typebox";
7
+ import { canonicalPath, nexoHomeGuard, resolveConfined, SECRET_PATH } from "./confine.js";
8
+ export const MAX_BASH_OUTPUT_BYTES = 1_000_000;
9
+ const MAX_READ_LINES = 2000;
10
+ const MAX_FETCH_CHARS = 100_000;
11
+ const FETCH_TIMEOUT_MS = 30_000;
12
+ const MAX_READ_BATCH = 20;
13
+ /** Paths with this prefix open the run's saved large tool outputs (`tool_outputs/` in the run directory) with `read`. */
14
+ export const TOOL_OUTPUT_PREFIX = "@tool_outputs/";
15
+ const liveBashGroups = new Set();
16
+ let exitHandlerRegistered = false;
17
+ export function killLiveBashGroups() {
18
+ for (const pgid of liveBashGroups) {
19
+ try {
20
+ process.kill(-pgid, "SIGKILL");
21
+ }
22
+ catch {
23
+ // the process group already exited
24
+ }
25
+ }
26
+ liveBashGroups.clear();
27
+ }
28
+ export function trackedBashGroups() {
29
+ return [...liveBashGroups];
30
+ }
31
+ function ensureExitHandler() {
32
+ if (exitHandlerRegistered)
33
+ return;
34
+ exitHandlerRegistered = true;
35
+ process.on("exit", killLiveBashGroups);
36
+ }
37
+ /** Runs `command` with `bash -c` in its own process group, killed on timeout, abort or host exit. Never rejects. */
38
+ export function runBash(run) {
39
+ const { signal } = run;
40
+ return new Promise((resolvePromise) => {
41
+ if (signal?.aborted)
42
+ return resolvePromise({ output: "", exitCode: null, truncated: false, ended: "aborted" });
43
+ const child = spawn("bash", ["-c", run.command], { cwd: run.cwd, env: run.env ?? process.env, detached: true });
44
+ const pgid = child.pid;
45
+ if (pgid !== undefined) {
46
+ ensureExitHandler();
47
+ liveBashGroups.add(pgid);
48
+ }
49
+ const killGroup = () => {
50
+ try {
51
+ if (child.pid !== undefined)
52
+ process.kill(-child.pid, "SIGKILL");
53
+ }
54
+ catch {
55
+ // the process group already exited
56
+ }
57
+ };
58
+ const chunks = [];
59
+ let captured = 0;
60
+ let truncated = false;
61
+ let ended;
62
+ const collect = (chunk) => {
63
+ const room = MAX_BASH_OUTPUT_BYTES - captured;
64
+ if (chunk.length > room)
65
+ truncated = true;
66
+ if (room <= 0)
67
+ return;
68
+ const part = chunk.subarray(0, room);
69
+ chunks.push(part);
70
+ captured += part.length;
71
+ };
72
+ child.stdout.on("data", collect);
73
+ child.stderr.on("data", collect);
74
+ const timer = setTimeout(() => {
75
+ ended = "timeout";
76
+ killGroup();
77
+ }, run.timeoutMs);
78
+ const onAbort = () => {
79
+ ended = "aborted";
80
+ killGroup();
81
+ };
82
+ signal?.addEventListener("abort", onAbort, { once: true });
83
+ child.on("close", (code) => {
84
+ if (pgid !== undefined)
85
+ liveBashGroups.delete(pgid);
86
+ clearTimeout(timer);
87
+ signal?.removeEventListener("abort", onAbort);
88
+ const output = new StringDecoder("utf8").write(Buffer.concat(chunks));
89
+ resolvePromise({ output, exitCode: ended ? null : (code ?? -1), truncated, ended: ended ?? "exited" });
90
+ });
91
+ child.on("error", (error) => {
92
+ if (pgid !== undefined)
93
+ liveBashGroups.delete(pgid);
94
+ clearTimeout(timer);
95
+ signal?.removeEventListener("abort", onAbort);
96
+ resolvePromise({ output: error.message, exitCode: null, truncated: false, ended: "failed" });
97
+ });
98
+ });
99
+ }
100
+ function textResult(text, isError = false) {
101
+ return isError ? { content: [{ type: "text", text }], details: undefined, isError: true } : { content: [{ type: "text", text }], details: undefined };
102
+ }
103
+ const ReadParams = Type.Object({
104
+ path: Type.Optional(Type.String({ description: "File path: relative to the workspace, or absolute" })),
105
+ offset: Type.Optional(Type.Integer({ minimum: 1, description: "1-based first line" })),
106
+ limit: Type.Optional(Type.Integer({ minimum: 1, description: "Maximum number of lines" })),
107
+ paths: Type.Optional(Type.Array(Type.Object({
108
+ path: Type.String(),
109
+ offset: Type.Optional(Type.Integer({ minimum: 1 })),
110
+ limit: Type.Optional(Type.Integer({ minimum: 1 })),
111
+ }), { minItems: 1, maxItems: MAX_READ_BATCH, description: "Several files in one call, each with its own offset and limit; use instead of path" })),
112
+ });
113
+ const WriteParams = Type.Object({ path: Type.String(), content: Type.String() });
114
+ const EditParams = Type.Object({
115
+ path: Type.String(),
116
+ oldText: Type.String({ description: "Exact text to replace; must occur exactly once" }),
117
+ newText: Type.String(),
118
+ });
119
+ const BashParams = Type.Object({
120
+ command: Type.String(),
121
+ timeoutMs: Type.Optional(Type.Integer({ minimum: 1000 })),
122
+ });
123
+ const FetchParams = Type.Object({ url: Type.String({ description: "http(s) URL" }) });
124
+ export function createBuiltinTools(ctx) {
125
+ const root = realpathSync(ctx.workspaceRoot);
126
+ const guard = ctx.nexoHome === undefined ? null : nexoHomeGuard(ctx.nexoHome, root, ctx.runWorkspace, ctx.wikiRoots);
127
+ /** A tool path argument made absolute (relative paths start at the workspace) and resolved through realpath. Not confined to the workspace. */
128
+ const resolvePath = (target) => canonicalPath(target, root);
129
+ /** Reads are not confined to the workspace. Outside it, key, token and credential files are refused: bash reads them through approval. */
130
+ const resolveReadPath = (target) => {
131
+ const abs = canonicalPath(target, root);
132
+ if (abs !== root && !abs.startsWith(root + sep) && SECRET_PATH.test(abs)) {
133
+ throw new NexoError({
134
+ code: "TOOL_DENIED",
135
+ message: `Path "${target}" looks like a key, token or credential file`,
136
+ hint: "Read it with bash, which asks for approval",
137
+ context: { target },
138
+ });
139
+ }
140
+ return abs;
141
+ };
142
+ const writeFile = (abs, content) => {
143
+ ctx.leases.acquire(abs, ctx.holder);
144
+ if (abs === root || abs.startsWith(root + sep))
145
+ ctx.changeTracker?.beforeWrite(abs);
146
+ mkdirSync(dirname(abs), { recursive: true });
147
+ writeFileSync(abs, content);
148
+ };
149
+ /** A saved output path in the run's own directory, else in the first earlier directory that has it. */
150
+ const resolveSavedOutput = (outputs, path) => {
151
+ const name = path.slice(TOOL_OUTPUT_PREFIX.length);
152
+ for (const dir of [outputs, ...(ctx.earlierToolOutputsDirs?.() ?? [])]) {
153
+ if (!existsSync(dir))
154
+ continue;
155
+ const abs = resolveConfined(dir, name);
156
+ if (existsSync(abs))
157
+ return abs;
158
+ }
159
+ throw new Error(`File not found: ${path}`);
160
+ };
161
+ const readOne = (path, offset, limit) => {
162
+ const outputs = ctx.toolOutputsDir;
163
+ const savedOutput = outputs !== undefined && path.startsWith(TOOL_OUTPUT_PREFIX);
164
+ const abs = savedOutput ? resolveSavedOutput(outputs, path) : resolveReadPath(path);
165
+ guard?.checkRead(abs);
166
+ if (!existsSync(abs))
167
+ throw new Error(`File not found: ${path}`);
168
+ const lines = readFileSync(abs, "utf8").split("\n");
169
+ const start = (offset ?? 1) - 1;
170
+ return lines.slice(start, start + (limit ?? MAX_READ_LINES)).join("\n");
171
+ };
172
+ const read = {
173
+ name: "read",
174
+ label: "Read file",
175
+ description: `Read text files. Relative paths start at the workspace; absolute paths are read where they are, except key, token and credential files (use bash for those). Pass paths to read several files in one call. Paths starting with ${TOOL_OUTPUT_PREFIX} open saved large tool outputs.`,
176
+ parameters: ReadParams,
177
+ execute: async (_id, params) => {
178
+ if (params.paths !== undefined) {
179
+ if (params.path !== undefined)
180
+ throw new Error("Give either path or paths, not both");
181
+ const parts = params.paths.map((p) => {
182
+ try {
183
+ return { failed: false, text: `==> ${p.path} <==\n${readOne(p.path, p.offset, p.limit)}` };
184
+ }
185
+ catch (error) {
186
+ return { failed: true, text: `==> ${p.path} <==\n[error] ${error instanceof Error ? error.message : String(error)}` };
187
+ }
188
+ });
189
+ return textResult(parts.map((p) => p.text).join("\n\n"), parts.every((p) => p.failed));
190
+ }
191
+ if (params.path === undefined)
192
+ throw new Error("Give path or paths");
193
+ return textResult(readOne(params.path, params.offset, params.limit));
194
+ },
195
+ };
196
+ const write = {
197
+ name: "write",
198
+ label: "Write file",
199
+ description: "Create or overwrite a file. Relative paths start at the workspace; absolute paths are written where they are.",
200
+ parameters: WriteParams,
201
+ execute: async (_id, params) => {
202
+ const abs = resolvePath(params.path);
203
+ guard?.checkWrite(abs);
204
+ writeFile(abs, params.content);
205
+ return textResult(`Wrote ${Buffer.byteLength(params.content)} bytes to ${relative(root, abs) || params.path}`);
206
+ },
207
+ };
208
+ const edit = {
209
+ name: "edit",
210
+ label: "Edit file",
211
+ description: "Replace one exact, unique occurrence of oldText with newText.",
212
+ parameters: EditParams,
213
+ execute: async (_id, params) => {
214
+ if (params.oldText === "")
215
+ throw new Error("oldText must not be empty");
216
+ const abs = resolvePath(params.path);
217
+ guard?.checkWrite(abs);
218
+ if (!existsSync(abs))
219
+ throw new Error(`File not found: ${params.path}`);
220
+ const content = readFileSync(abs, "utf8");
221
+ const count = content.split(params.oldText).length - 1;
222
+ if (count === 0)
223
+ throw new Error(`oldText not found in ${params.path}`);
224
+ if (count > 1)
225
+ throw new Error(`oldText matches ${count} times in ${params.path}; include more surrounding text`);
226
+ writeFile(abs, content.replace(params.oldText, () => params.newText));
227
+ return textResult(`Edited ${params.path}`);
228
+ },
229
+ };
230
+ const bash = {
231
+ name: "bash",
232
+ label: "Run command",
233
+ description: "Run a bash command in the workspace directory.",
234
+ parameters: BashParams,
235
+ execute: async (_id, params, signal) => {
236
+ const timeoutMs = params.timeoutMs ?? ctx.bashTimeoutMs;
237
+ const r = await runBash({ command: params.command, cwd: root, timeoutMs, signal });
238
+ const body = `${r.output}${r.truncated ? "\n[output truncated]" : ""}`;
239
+ switch (r.ended) {
240
+ case "failed":
241
+ return textResult(`Failed to start bash: ${r.output}`, true);
242
+ case "timeout":
243
+ return textResult(`Command timed out after ${timeoutMs}ms and was killed with its child processes.\nFor a long job, start it in the background (nohup <command> > job.log 2>&1 &) and poll job.log, or pass a larger timeoutMs.\n${body}`, true);
244
+ case "aborted":
245
+ return textResult(`Command aborted\n${body}`, true);
246
+ case "exited":
247
+ return textResult(`exit code: ${r.exitCode ?? -1}\n${body}`, r.exitCode !== 0);
248
+ }
249
+ },
250
+ };
251
+ const webFetch = {
252
+ name: "web_fetch",
253
+ label: "Fetch URL",
254
+ description: "Fetch an http(s) URL and return the response body as text.",
255
+ parameters: FetchParams,
256
+ execute: async (_id, params, signal) => {
257
+ const url = new URL(params.url);
258
+ if (url.protocol !== "http:" && url.protocol !== "https:")
259
+ throw new Error(`Only http and https URLs are allowed: ${params.url}`);
260
+ const signals = [AbortSignal.timeout(FETCH_TIMEOUT_MS), ...(signal ? [signal] : [])];
261
+ const response = await (ctx.fetch ?? fetch)(url.toString(), { signal: AbortSignal.any(signals) });
262
+ const body = (await response.text()).slice(0, MAX_FETCH_CHARS);
263
+ if (!response.ok)
264
+ return textResult(`HTTP ${response.status} for ${params.url}\n${body}`, true);
265
+ return textResult(body);
266
+ },
267
+ };
268
+ return [read, write, edit, bash, webFetch];
269
+ }
@@ -0,0 +1,57 @@
1
+ import { existsSync, mkdirSync, readFileSync, realpathSync, statSync, writeFileSync } from "node:fs";
2
+ import { dirname, join, relative } from "node:path";
3
+ import { NexoError } from "../../telemetry/src/index.js";
4
+ import { createTwoFilesPatch } from "diff";
5
+ import { resolveConfined } from "./confine.js";
6
+ function writeCopy(base, rel, content, redact) {
7
+ const target = join(base, rel);
8
+ mkdirSync(dirname(target), { recursive: true });
9
+ writeFileSync(target, redact(content));
10
+ }
11
+ /**
12
+ * Records the original content of files before the agent first writes them, and diffs them at finalize.
13
+ * Everything written under `changesDir` passes through `redact`. Paths may use any spelling of the workspace (raw tmpdir or realpath); they are resolved through `resolveConfined`.
14
+ */
15
+ export function createChangeTracker(workspaceRoot, changesDir, redact) {
16
+ const rootReal = realpathSync(workspaceRoot);
17
+ const originals = new Map();
18
+ return {
19
+ beforeWrite(path) {
20
+ const absPath = resolveConfined(rootReal, path);
21
+ const rel = relative(rootReal, absPath);
22
+ if (originals.has(rel))
23
+ return;
24
+ if (existsSync(absPath) && statSync(absPath).isDirectory()) {
25
+ throw new NexoError({
26
+ code: "TOOL_DENIED",
27
+ message: `Path "${path}" is a directory; only files can be written`,
28
+ hint: "Write to a file path inside the directory",
29
+ context: { path },
30
+ });
31
+ }
32
+ const original = existsSync(absPath) ? readFileSync(absPath, "utf8") : null;
33
+ originals.set(rel, original);
34
+ if (original !== null)
35
+ writeCopy(join(changesDir, "before"), rel, original, redact);
36
+ },
37
+ finalize() {
38
+ const summaries = [];
39
+ let patch = "";
40
+ for (const rel of [...originals.keys()].sort()) {
41
+ const before = originals.get(rel) ?? null;
42
+ const abs = resolveConfined(rootReal, rel);
43
+ const after = existsSync(abs) ? readFileSync(abs, "utf8") : null;
44
+ const kind = before === after ? "unchanged" : before === null ? "created" : after === null ? "deleted" : "modified";
45
+ summaries.push({ path: rel, kind });
46
+ if (kind === "unchanged")
47
+ continue;
48
+ if (after !== null)
49
+ writeCopy(join(changesDir, "after"), rel, after, redact);
50
+ patch += createTwoFilesPatch(`a/${rel}`, `b/${rel}`, before ?? "", after ?? "");
51
+ }
52
+ mkdirSync(changesDir, { recursive: true });
53
+ writeFileSync(join(changesDir, "changes.diff"), redact(patch));
54
+ return summaries;
55
+ },
56
+ };
57
+ }
@@ -0,0 +1,101 @@
1
+ import { lstatSync, realpathSync } from "node:fs";
2
+ import { dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
3
+ import { NexoError } from "../../telemetry/src/index.js";
4
+ function isMissing(err) {
5
+ const code = err.code;
6
+ return code === "ENOENT" || code === "ENOTDIR";
7
+ }
8
+ /**
9
+ * Absolute form of `target` (relative to `base`) with its deepest existing ancestor resolved through realpath.
10
+ * Ancestors are probed with lstat so a dangling symlink is found rather than walked past; a symlink whose target
11
+ * cannot be resolved is denied with TOOL_DENIED. `realpath` resolves the existing ancestor.
12
+ */
13
+ export function canonicalPath(target, base = process.cwd(), realpath = realpathSync) {
14
+ const absolute = isAbsolute(target) ? resolve(target) : resolve(base, target);
15
+ let probe = absolute;
16
+ for (;;) {
17
+ try {
18
+ lstatSync(probe);
19
+ break;
20
+ }
21
+ catch (err) {
22
+ if (!isMissing(err))
23
+ throw err;
24
+ const parent = dirname(probe);
25
+ if (parent === probe)
26
+ break;
27
+ probe = parent;
28
+ }
29
+ }
30
+ let resolvedProbe;
31
+ try {
32
+ resolvedProbe = realpath(probe);
33
+ }
34
+ catch (cause) {
35
+ if (!isMissing(cause))
36
+ throw cause;
37
+ throw new NexoError({
38
+ code: "TOOL_DENIED",
39
+ message: `Path "${target}" passes through a symlink that cannot be resolved: ${probe}`,
40
+ hint: "Use a path that does not go through dangling symlinks",
41
+ context: { target, link: probe },
42
+ cause,
43
+ });
44
+ }
45
+ return join(resolvedProbe, relative(probe, absolute));
46
+ }
47
+ /**
48
+ * Workspace confinement for agent-supplied paths: resolves `target` against `root` through realpath, so symlinks
49
+ * cannot escape, and denies anything outside `root`. Run-directory names that nexo itself chooses use the lexical
50
+ * `confine` in `@nexo/store`'s run-dir.ts instead.
51
+ */
52
+ export function resolveConfined(root, target) {
53
+ const rootReal = realpathSync(root);
54
+ const full = canonicalPath(target, rootReal);
55
+ if (full !== rootReal && !full.startsWith(rootReal + sep)) {
56
+ throw new NexoError({
57
+ code: "TOOL_DENIED",
58
+ message: `Path "${target}" is outside the workspace ${rootReal}`,
59
+ hint: "Use a path inside the workspace",
60
+ context: { target, workspace: rootReal },
61
+ });
62
+ }
63
+ return full;
64
+ }
65
+ function isWithin(path, dir) {
66
+ return path === dir || path.startsWith(dir + sep);
67
+ }
68
+ /**
69
+ * Guards the nexo home (config, credentials, skills, runs, sessions, the database) against the agent's file tools,
70
+ * whatever the workspace. Paths are compared through the native realpath, which also settles letter case on
71
+ * case-insensitive file systems. Only `runWorkspace`, the run's own `workspace/` folder, stays writable inside it;
72
+ * other runs' folders and everything else under the nexo home are refused, except the `wikiRoots` (the user's wikis).
73
+ */
74
+ export function nexoHomeGuard(nexoHome, workspaceRoot, runWorkspace, wikiRoots = []) {
75
+ const native = realpathSync.native;
76
+ const home = canonicalPath(nexoHome, process.cwd(), native);
77
+ const workspace = canonicalPath(workspaceRoot, process.cwd(), native);
78
+ const credentials = join(home, "credentials.json");
79
+ const own = runWorkspace === undefined ? null : canonicalPath(runWorkspace, process.cwd(), native);
80
+ const exempt = own !== null && isWithin(own, home) && own !== home ? own : null;
81
+ const wikis = wikiRoots.map((wikiRoot) => canonicalPath(wikiRoot, process.cwd(), native));
82
+ const deny = (target, message) => new NexoError({
83
+ code: "TOOL_DENIED",
84
+ message,
85
+ hint: "nexo's own files (config, credentials, skills, runs, sessions) are not changed by the agent; edit them yourself outside the run",
86
+ context: { target, nexoHome: home },
87
+ });
88
+ return {
89
+ checkWrite(path) {
90
+ const full = canonicalPath(path, workspace, native);
91
+ if (isWithin(full, home) && !(exempt !== null && isWithin(full, exempt)) && !wikis.some((wiki) => isWithin(full, wiki)))
92
+ throw deny(path, `Path "${path}" is inside the nexo home ${home}`);
93
+ },
94
+ checkRead(path) {
95
+ if (canonicalPath(path, workspace, native) === credentials)
96
+ throw deny(path, `Path "${path}" is the nexo credentials file`);
97
+ },
98
+ };
99
+ }
100
+ /** Paths the read tool refuses outside the workspace: keys, tokens and credential files. Bash reads them through approval. */
101
+ export const SECRET_PATH = /(^|[/~])\.(ssh|aws|gnupg|kube|docker|netrc|npmrc|pypirc|git-credentials|env)(\b|$)|id_(rsa|dsa|ecdsa|ed25519)|credential|secret|token|passw|service-account|-access\.json$|\.pem$|\.key$|\.p12$|keychain/i;
@@ -0,0 +1,7 @@
1
+ export * from "./builtin.js";
2
+ export * from "./change-tracker.js";
3
+ export * from "./confine.js";
4
+ export * from "./leases.js";
5
+ export * from "./policy.js";
6
+ export * from "./read-only.js";
7
+ export * from "./session-rules.js";
@@ -0,0 +1,57 @@
1
+ import { NexoError } from "../../telemetry/src/index.js";
2
+ import { canonicalPath } from "./confine.js";
3
+ /**
4
+ * Per-file write ownership shared by all runs in one run tree. A holder keeps its leases until releaseAll.
5
+ * Keys are canonical paths, so `/var/...` and `/private/var/...` spellings of one file share a lease.
6
+ *
7
+ * Runs in one ancestor line never execute at the same time in a conflicting way (a parent waits on its children), so
8
+ * a file may be held by several runs at once as long as each pair is ancestor and descendant. Holders that could run
9
+ * concurrently, such as siblings, conflict.
10
+ */
11
+ export class FileLeases {
12
+ holders = new Map();
13
+ parents = new Map();
14
+ /** Records that run `child` was started by run `parent`. */
15
+ link(child, parent) {
16
+ this.parents.set(child, parent);
17
+ }
18
+ acquire(path, holder) {
19
+ const key = canonicalPath(path);
20
+ const current = this.holders.get(key) ?? [];
21
+ const conflicting = current.find((other) => other !== holder && !this.related(other, holder));
22
+ if (conflicting !== undefined) {
23
+ throw new NexoError({
24
+ code: "WRITE_CONFLICT",
25
+ message: `File ${key} is being written by another task (${conflicting})`,
26
+ retryable: true,
27
+ hint: "Retry after the other task finishes, or write to a different file",
28
+ context: { path: key, holder: conflicting },
29
+ });
30
+ }
31
+ if (!current.includes(holder))
32
+ this.holders.set(key, [...current, holder]);
33
+ }
34
+ releaseAll(holder) {
35
+ for (const [path, owners] of this.holders) {
36
+ const rest = owners.filter((owner) => owner !== holder);
37
+ if (rest.length === 0)
38
+ this.holders.delete(path);
39
+ else
40
+ this.holders.set(path, rest);
41
+ }
42
+ }
43
+ /** The first run that acquired the file among those still holding it. */
44
+ holderOf(path) {
45
+ return this.holders.get(canonicalPath(path))?.[0];
46
+ }
47
+ related(a, b) {
48
+ return this.isAncestor(a, b) || this.isAncestor(b, a);
49
+ }
50
+ isAncestor(ancestor, run) {
51
+ for (let current = this.parents.get(run); current !== undefined; current = this.parents.get(current)) {
52
+ if (current === ancestor)
53
+ return true;
54
+ }
55
+ return false;
56
+ }
57
+ }