sumo-agents 0.0.0-stage → 0.3.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (66) hide show
  1. package/AGENTS.md +38 -0
  2. package/LICENSE +21 -0
  3. package/README.md +111 -2
  4. package/bin/sumo.mjs +33 -0
  5. package/guides/delegation.md +33 -0
  6. package/guides/feature.md +14 -0
  7. package/guides/fix.md +14 -0
  8. package/guides/memory.md +23 -0
  9. package/guides/projects.md +27 -0
  10. package/guides/review.md +16 -0
  11. package/guides/workflows.md +26 -0
  12. package/logo.txt +19 -0
  13. package/package.json +42 -4
  14. package/prompts/agent.md +7 -0
  15. package/prompts/dream.md +13 -0
  16. package/prompts/scribe.md +21 -0
  17. package/spinner.txt +90 -0
  18. package/src/advisor.mjs +59 -0
  19. package/src/apply.mjs +368 -0
  20. package/src/auth.mjs +80 -0
  21. package/src/card.mjs +72 -0
  22. package/src/catalog.mjs +167 -0
  23. package/src/chat.mjs +1162 -0
  24. package/src/cli.mjs +815 -0
  25. package/src/cost.mjs +128 -0
  26. package/src/db.mjs +384 -0
  27. package/src/dream.mjs +97 -0
  28. package/src/editor.mjs +198 -0
  29. package/src/export.mjs +132 -0
  30. package/src/guard.mjs +121 -0
  31. package/src/guides.mjs +86 -0
  32. package/src/herdr.mjs +117 -0
  33. package/src/hooks.mjs +270 -0
  34. package/src/images.mjs +89 -0
  35. package/src/jobs.mjs +1184 -0
  36. package/src/jobtools.mjs +82 -0
  37. package/src/local-server.mjs +169 -0
  38. package/src/lock.mjs +45 -0
  39. package/src/loop.mjs +838 -0
  40. package/src/mcp.mjs +604 -0
  41. package/src/memory.mjs +400 -0
  42. package/src/model.mjs +270 -0
  43. package/src/page.html +304 -0
  44. package/src/page.mjs +135 -0
  45. package/src/paths.mjs +33 -0
  46. package/src/prime.mjs +177 -0
  47. package/src/projects.mjs +232 -0
  48. package/src/recall.mjs +45 -0
  49. package/src/redact.mjs +173 -0
  50. package/src/render.mjs +45 -0
  51. package/src/route.mjs +287 -0
  52. package/src/sandbox.mjs +173 -0
  53. package/src/scan.mjs +204 -0
  54. package/src/scribe.mjs +349 -0
  55. package/src/sessions.mjs +371 -0
  56. package/src/setup.mjs +528 -0
  57. package/src/sqlite.mjs +66 -0
  58. package/src/text.mjs +97 -0
  59. package/src/tools.mjs +987 -0
  60. package/src/transcript.mjs +106 -0
  61. package/src/tty.mjs +529 -0
  62. package/src/ui.mjs +1363 -0
  63. package/src/verify.mjs +369 -0
  64. package/src/web.mjs +49 -0
  65. package/src/workflows.mjs +270 -0
  66. package/src/worktree.mjs +128 -0
package/src/tools.mjs ADDED
@@ -0,0 +1,987 @@
1
+ import { spawn, spawnSync } from 'node:child_process';
2
+ import { accessSync, closeSync, constants, existsSync, lstatSync, mkdirSync, openSync, readdirSync, readFileSync, readlinkSync, realpathSync, rmSync, statSync, writeFileSync } from 'node:fs';
3
+ import { tmpdir } from 'node:os';
4
+ import { delimiter, dirname, extname, join, resolve, sep } from 'node:path';
5
+ import { CREDENTIAL_NAMES } from './auth.mjs';
6
+ import { guardCommand, guardPath } from './guard.mjs';
7
+ import { redact } from './redact.mjs';
8
+ import { blockedWrite, readOnlyPlaces, sandboxWrap, unsandboxable, writablePlaces } from './sandbox.mjs';
9
+
10
+ /**
11
+ * The two tools a job gets, and the policy every call passes through before it
12
+ * runs: command guards, the editor's path jail, output caps, and redaction.
13
+ * Shell commands read what the user can; on macOS they write only where the sandbox lets them, and command guards match known patterns.
14
+ */
15
+
16
+ /** Anthropic-defined, schema-less on the wire: the API knows their shape, so no schema is sent. */
17
+ export const BASH_TOOL = { type: 'bash_20250124', name: 'bash' };
18
+ export const EDITOR_TOOL = { type: 'text_editor_20250728', name: 'str_replace_based_edit_tool' };
19
+
20
+ /** The chat's own: hands a piece of work to a sub-agent with a fresh context. Its report is the call's answer, or — in the background — comes later. Several in one reply run at once. */
21
+ export const DELEGATE_TOOL = {
22
+ name: 'delegate',
23
+ description:
24
+ 'Hand a piece of work to a sub-agent with a fresh context: scout looks — at the code or on the web (no edits), worker builds, reviewer judges a change it did not write. ' +
25
+ 'It runs on its own route. Its report is this call\'s result — or, when the result says the job is running in the background, it reaches you later ' +
26
+ 'as an automated event. Several calls in one reply run at the same time; one worker per project at a time. ' +
27
+ 'To continue an open job instead (one from an earlier session), give only `job`.',
28
+ input_schema: {
29
+ type: 'object',
30
+ properties: {
31
+ agent: { type: 'string', enum: ['scout', 'worker', 'reviewer'] },
32
+ project: { type: 'string', description: 'the project slug' },
33
+ title: { type: 'string', description: 'a few words' },
34
+ task: { type: 'string', description: 'the brief, a contract: ## Goal, ## Non-goals, ## Must not change, ## Check (the command that proves it, or why none), ## Report' },
35
+ guide: { type: 'string', enum: ['fix', 'feature', 'none'], description: 'carry guides/<guide>.md into the brief; unsaid, a worker gets the one its title and goal ask for, if any' },
36
+ reviews: { type: 'integer', description: 'reviewer only: the worker job whose change to judge; without it, the uncommitted change' },
37
+ tests_may_change: { type: 'boolean', description: 'worker only: existing tests may be edited' },
38
+ attempts: { type: 'integer', description: 'worker only, for a hard task: 2 or 3 attempts in worktrees of their own, the best verified one kept; costs that many times as much' },
39
+ job: { type: 'integer', description: 'continue this open job; nothing else is given' },
40
+ },
41
+ },
42
+ };
43
+
44
+ /** The chat's own: a question only the user can answer, put to them with options to pick from; the pick, or what they typed instead, is the call's answer. */
45
+ export const ASK_TOOL = {
46
+ name: 'ask',
47
+ description:
48
+ 'Put a question to the user and wait for the answer. Use it before building, when the request leaves open what to build — scope, behaviour, ' +
49
+ 'which approach — and neither memory nor the code settles it; never for what you can look up, or decide and cheaply undo. ' +
50
+ 'Give 2–4 options, the one you would pick first; the user picks one, or types an answer of their own. ' +
51
+ 'One question a call; several calls in one reply are put one after another.',
52
+ input_schema: {
53
+ type: 'object',
54
+ properties: {
55
+ question: { type: 'string', description: 'the whole question: the user sees this and the options, nothing else' },
56
+ options: {
57
+ type: 'array',
58
+ items: {
59
+ type: 'object',
60
+ properties: { label: { type: 'string', description: 'a few words' }, detail: { type: 'string', description: 'what choosing it means, in a line' } },
61
+ required: ['label'],
62
+ },
63
+ },
64
+ },
65
+ required: ['question', 'options'],
66
+ },
67
+ };
68
+
69
+ const OUTPUT_CAP_CHARS = 16_000;
70
+ const VIEW_CAP_LINES = 400;
71
+ const COMMAND_TIMEOUT_MS = 540_000; // the same nine minutes a check gets
72
+ /** How long the model's command may print nothing: one waiting on a prompt or a hung server gives the turn back in two minutes, not nine. */
73
+ const IDLE_TIMEOUT_MS = 120_000;
74
+ /** The most a `timeout N` in front of a command can ask for. */
75
+ const ASKED_MAX_S = 1800;
76
+ const MAX_BUFFER_CHARS = 64 * 1024 * 1024;
77
+ /** What is held of a command's output at each end: more than any cap keeps, so the cut is always made by the cap, never here. */
78
+ const KEPT_EACH_END = 64 * 1024;
79
+
80
+ /** A stream's first and last KEPT_EACH_END characters, and how many fell between them — never the whole flood. */
81
+ function keeper() {
82
+ let head = '';
83
+ let tail = '';
84
+ let total = 0;
85
+ return {
86
+ push(chunk) {
87
+ total += chunk.length;
88
+ const room = KEPT_EACH_END - head.length;
89
+ if (room > 0) {
90
+ head += chunk.slice(0, room);
91
+ chunk = chunk.slice(room);
92
+ }
93
+ if (chunk) tail = (tail + chunk).slice(-KEPT_EACH_END);
94
+ },
95
+ get text() {
96
+ return head + tail;
97
+ },
98
+ get omitted() {
99
+ return total - head.length - tail.length;
100
+ },
101
+ };
102
+ }
103
+
104
+ /** The shell a command runs in: bash, which the tool is named for, where there is one. */
105
+ const SHELL = existsSync('/bin/bash') ? '/bin/bash' : true;
106
+ /**
107
+ * What is spawned for a command: the shell, or — under a wrapper, the sandbox — the wrapper, which execs into bash in
108
+ * place, so the pid and its process group are the shell's. The sandbox is only on macOS, where there is always a /bin/bash.
109
+ */
110
+ function spawnShell(command, wrap, options) {
111
+ return wrap ? spawn(wrap[0], [...wrap.slice(1), '/bin/bash', '-c', command], options) : spawn(command, { ...options, shell: SHELL });
112
+ }
113
+ /** Why a command never started: the reason, and a directory that is gone is the usual one. */
114
+ const unstartedWhy = (cause, cwd) => `the command could not be started: ${cause.message}${cwd && !existsSync(cwd) ? ` — ${cwd} does not exist` : ''}`;
115
+ /** How long the pipes are drained once the shell has gone, for output already on its way. */
116
+ const DRAIN_MS = 200;
117
+ /** `sumo job baseline|verify|finish` run the project's checks, each under its own limit. */
118
+ const OWN_LIMITS = /^\s*sumo\s+job\s+(baseline|verify|finish)\b/;
119
+
120
+ /** The process groups of the commands still running: when this process is told to go, they go first. */
121
+ const live = new Set();
122
+ let watching = false;
123
+ export const killGroup = (pid) => {
124
+ // A spawn that failed reports pid 0, and -0 is 0: the caller's own group.
125
+ if (!(pid > 0)) return;
126
+ try {
127
+ process.kill(-pid, 'SIGKILL');
128
+ } catch {
129
+ // Nothing left to kill.
130
+ }
131
+ };
132
+ /** A child of this process whose whole group goes when this process does: a command's, or an MCP server's. */
133
+ export function trackGroup(pid) {
134
+ live.add(pid);
135
+ if (watching) return;
136
+ watching = true;
137
+ process.on('exit', () => {
138
+ for (const group of live) killGroup(group);
139
+ });
140
+ // A terminal closed, or a kill: leave as the signal would, after the commands — exit runs the line above.
141
+ process.on('SIGHUP', () => process.exit(129));
142
+ process.on('SIGTERM', () => process.exit(143));
143
+ }
144
+
145
+ /** What a command's output ends with when the user stopped it. */
146
+ export const INTERRUPTED = 'stopped: interrupted by the user';
147
+
148
+ /**
149
+ * The environment a tool's child process gets: the user's own, without Sumo's credential. The tokens the user exported
150
+ * are theirs to use — a smoke test needs one — while the guard refuses printing the lot, and a secret printed is redacted.
151
+ */
152
+ export function childEnv(env = process.env) {
153
+ return Object.fromEntries(Object.entries(env).filter(([name]) => !CREDENTIAL_NAMES.includes(name)));
154
+ }
155
+
156
+ /** What keeps git and ssh from waiting on somebody at a keyboard: no password asked, no editor, no pager, ssh in batch mode. */
157
+ const NO_PROMPTS = { GIT_TERMINAL_PROMPT: '0', GIT_EDITOR: 'true', GIT_PAGER: 'cat', PAGER: 'cat', GIT_SSH_COMMAND: 'ssh -o BatchMode=yes' };
158
+
159
+ /** Whether git's config where a command runs names an ssh command of its own, asked of git once for each directory. */
160
+ const sshCommands = new Map();
161
+ function hasSshCommand(cwd, env) {
162
+ if (!sshCommands.has(cwd)) {
163
+ const asked = spawnSync('git', ['config', '--get', 'core.sshCommand'], { cwd, env, encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'], timeout: PARSE_TIMEOUT_MS });
164
+ sshCommands.set(cwd, asked.status === 0 && asked.stdout.trim() !== '');
165
+ }
166
+ return sshCommands.get(cwd);
167
+ }
168
+
169
+ /**
170
+ * The environment of a command of the model's, which nobody answers — its stdin is closed — so it never waits on a
171
+ * prompt: each of NO_PROMPTS where the environment has not set it already. An ssh command of the user's own, in the
172
+ * environment or in git's config, is theirs: it stands, and is not replaced by one in batch mode.
173
+ */
174
+ function unprompted(env, cwd) {
175
+ const ownSsh = env.GIT_SSH !== undefined || env.GIT_SSH_COMMAND !== undefined || hasSshCommand(cwd, env);
176
+ const { GIT_SSH_COMMAND, ...rest } = NO_PROMPTS;
177
+ return { ...rest, ...(ownSsh ? {} : { GIT_SSH_COMMAND }), ...env };
178
+ }
179
+
180
+ /**
181
+ * Keeps both ends of a long output. The head says what ran and the tail is
182
+ * where runners put the failures; the middle is the part worth losing, and the
183
+ * marker says how much went and how to get a narrower answer.
184
+ */
185
+ export function cap(text, max = OUTPUT_CAP_CHARS, omitted = 0) {
186
+ if (text.length <= max && omitted === 0) return text;
187
+ const half = Math.floor(max / 2);
188
+ return `${text.slice(0, half)}\n${cutMark(text.length - 2 * half + omitted)}\n${text.slice(-half)}`;
189
+ }
190
+
191
+ /** The cut, and the way to what was cut: the file holding the output when there is one, else a narrower command. */
192
+ const cutMark = (cut, kept = null) =>
193
+ `[cut ${cut} characters from the middle — ${kept ? `the first and last ${KEPT_EACH_END / 1024} KB of the output are in ${kept}: read a range of it, or ` : ''}narrow the command: tail, grep, or a line range]`;
194
+
195
+ /**
196
+ * cap(), with the secrets taken out of what survives it. They are looked for before the cut, in a margin around each
197
+ * end that is kept, so a key the cut would split is still whole when it is found — and a flood of output is never
198
+ * scanned whole. `kept` names the file the whole of it went to, when it went somewhere.
199
+ */
200
+ export function capRedacted(text, max = OUTPUT_CAP_CHARS, omitted = 0, kept = null) {
201
+ // Capped after redacting too: what redaction adds — a marker for each hidden character — counts against the cap.
202
+ if (text.length <= max && omitted === 0) {
203
+ const out = redact(text).text;
204
+ return out.length <= max ? out : cap(out, max);
205
+ }
206
+ return cutBetween(text, text, text.length - 2 * Math.floor(max / 2) + omitted, max, kept);
207
+ }
208
+
209
+ /** The start of `head` and the end of `tail`, half the cap each and without their secrets, and the cut between them said. */
210
+ function cutBetween(head, tail, cut, max, kept) {
211
+ const half = Math.floor(max / 2);
212
+ return `${redact(head.slice(0, half + max)).text.slice(0, half)}\n${cutMark(cut, kept)}\n${redact(tail.slice(-(half + max))).text.slice(-half)}`;
213
+ }
214
+
215
+ /** The longest a line of output or of a viewed file is shown whole: a minified bundle or a line of JSON past it is its start, and how much was cut. */
216
+ const LINE_CAP_CHARS = 2_000;
217
+
218
+ /** A line no longer than LINE_CAP_CHARS. Its secrets go before the cut, which could otherwise leave the start of one that is no longer recognised. */
219
+ function cutLine(line) {
220
+ if (line.length <= LINE_CAP_CHARS) return line;
221
+ const clean = redact(line).text;
222
+ return clean.length <= LINE_CAP_CHARS ? clean : `${clean.slice(0, LINE_CAP_CHARS)}[… ${clean.length - LINE_CAP_CHARS} chars cut]`;
223
+ }
224
+
225
+ /** A line a progress bar rewrote in place with carriage returns, as it was left: its last state that is not blank. One ending in \r\n keeps its ending. */
226
+ function lastState(line) {
227
+ const end = line.endsWith('\r') ? '\r' : '';
228
+ const body = end ? line.slice(0, -1) : line;
229
+ return body.includes('\r') ? `${body.split('\r').findLast((state) => state.trim() !== '') ?? ''}${end}` : line;
230
+ }
231
+
232
+ /**
233
+ * What the model is shown of a command's output, before the cap, so the cap keeps more of what was said: each line a
234
+ * progress bar rewrote as it was left, a run of three or more of the same line as the line and how many more there
235
+ * were — where that is shorter — and a line too long to read cut to its start. `cut` counts the lines cut short: what
236
+ * they held is in the spill file only.
237
+ */
238
+ export function tidy(output) {
239
+ const lines = output.split('\n').map(lastState);
240
+ const shown = [];
241
+ let cut = 0;
242
+ for (let i = 0; i < lines.length; ) {
243
+ let end = i + 1;
244
+ while (end < lines.length && lines[end] === lines[i]) end++;
245
+ const fold = `[… the same line ${end - i - 1} more times]`;
246
+ const folded = end - i >= 3 && fold.length < (end - i - 1) * (lines[i].length + 1);
247
+ const times = folded ? 1 : end - i;
248
+ if (lines[i].length > LINE_CAP_CHARS) cut += times;
249
+ shown.push(...Array(times).fill(cutLine(lines[i])), ...(folded ? [fold] : []));
250
+ i = end;
251
+ }
252
+ return { text: shown.join('\n'), cut };
253
+ }
254
+
255
+ /**
256
+ * A command's output as the model is shown it: tidied, then capped, the cut said and the way to what was cut — `kept`,
257
+ * the spill file, when there is one. Of a flood only the two ends were held: each is tidied on its own, and the cut
258
+ * between them stays where it was. `cut` counts the lines cut short; `capped` is whether the cap cuts too.
259
+ */
260
+ function shownOf(output, omitted) {
261
+ const ends = omitted > 0 ? [tidy(output.slice(0, KEPT_EACH_END)), tidy(output.slice(KEPT_EACH_END))] : [tidy(output)];
262
+ const capped = omitted > 0 || ends[0].text.length > OUTPUT_CAP_CHARS;
263
+ const show = (kept) => {
264
+ if (ends.length === 1) return capRedacted(ends[0].text, OUTPUT_CAP_CHARS, 0, kept) + (kept && !capped ? `\n[a line cut short is whole in ${kept}]` : '');
265
+ const [head, tail] = ends.map((end) => end.text);
266
+ const half = Math.floor(OUTPUT_CAP_CHARS / 2);
267
+ return cutBetween(head, tail, Math.max(0, head.length - half) + omitted + Math.max(0, tail.length - half), OUTPUT_CAP_CHARS, kept);
268
+ };
269
+ return { cut: ends.reduce((n, end) => n + end.cut, 0), capped, show };
270
+ }
271
+
272
+ /** How long a saved output is kept: long enough to be read back by a run picked up tomorrow, not a disk full of old logs. */
273
+ const SPILL_KEEP_MS = 7 * 24 * 3_600_000;
274
+ let spilled = 0;
275
+
276
+ /**
277
+ * What was kept of an output too long to show — its two ends, the gap between them said — written where the model can
278
+ * read a range of it instead of running the command again: the job's folder, or the logs. Without its secrets, like
279
+ * everything that leaves a command; older files there go. Nowhere to write it is no file, and the cut says so.
280
+ */
281
+ function spill(dir, output, omitted) {
282
+ try {
283
+ mkdirSync(dir, { recursive: true, mode: 0o700 });
284
+ for (const name of readdirSync(dir)) {
285
+ const old = join(dir, name);
286
+ if (Date.now() - statSync(old).mtimeMs > SPILL_KEEP_MS) rmSync(old, { force: true });
287
+ }
288
+ const file = join(dir, `${Date.now()}-${process.pid}-${spilled++}.txt`);
289
+ const text = omitted > 0 ? `${output.slice(0, KEPT_EACH_END)}\n[… ${omitted} characters between here and the end were not kept …]\n${output.slice(KEPT_EACH_END)}` : output;
290
+ writeFileSync(file, redact(text).text.toWellFormed(), { mode: 0o600 });
291
+ return file;
292
+ } catch {
293
+ return null;
294
+ }
295
+ }
296
+
297
+ /**
298
+ * The real path of the deepest ancestor that exists, so a symlink cannot point a new file outside the jail. A link
299
+ * whose target does not exist yet is judged by where it points, not by the directory it sits in.
300
+ */
301
+ function realAncestor(path, hops = 0) {
302
+ let probe = path;
303
+ while (!existsSync(probe)) {
304
+ if (hops < 40 && isLink(probe)) return realAncestor(resolve(dirname(probe), readlinkSync(probe)), hops + 1);
305
+ const up = dirname(probe);
306
+ if (up === probe) return probe;
307
+ probe = up;
308
+ }
309
+ return realpathSync(probe);
310
+ }
311
+
312
+ const isLink = (path) => {
313
+ try {
314
+ return lstatSync(path).isSymbolicLink();
315
+ } catch {
316
+ return false;
317
+ }
318
+ };
319
+
320
+ /** An absolute path under one of the roots, or an Error saying which it is outside of. */
321
+ export function jailed(path, { cwd, roots }) {
322
+ if (typeof path !== 'string' || !path) throw new Error('a path is required');
323
+ // resolve() also tidies an absolute path: a .. after a directory that does not exist yet must not climb past the check.
324
+ const absolute = resolve(cwd, path);
325
+ const real = realAncestor(absolute);
326
+ const allowed = roots.map((r) => realpathSync(r)).some((r) => real === r || real.startsWith(`${r}/`));
327
+ if (!allowed) throw new Error(`${path} is outside the project (${roots[0]}) — work only inside it`);
328
+ return absolute;
329
+ }
330
+
331
+ /** What goes back to the model: without secrets, and well-formed — a cut that fell inside an emoji must not leave half of it in every later request. */
332
+ const result = (content, isError = false) => ({ content: redact(String(content)).text.toWellFormed(), isError });
333
+
334
+ /**
335
+ * Runs a shell command beside the process, not in front of it, so the screen
336
+ * keeps drawing while it runs. It ends when the shell does, when `signal`
337
+ * says stop, or when `timeoutMs` is up — whichever is first. The command
338
+ * always gets a process group of its own, so a stop or the time limit reaches
339
+ * everything it started, and so does this process being told to go. A child
340
+ * left in the background does not hold the call: once the shell has gone, the
341
+ * output already on its way is drained and the command is over. `onOutput` is
342
+ * handed each piece as it is printed, for a screen that shows the work.
343
+ * `idleMs` stops a command that has printed nothing for that long; `wrap` is
344
+ * what the shell runs under — the sandbox.
345
+ */
346
+ export function runCommand(command, { cwd, env, signal = null, timeoutMs = null, idleMs = null, onOutput = null, wrap = null }) {
347
+ return new Promise((resolve) => {
348
+ const child = spawnShell(command, wrap, { cwd, env, stdio: ['ignore', 'pipe', 'pipe'], detached: true });
349
+ if (child.pid) trackGroup(child.pid);
350
+ let drain = null;
351
+ // Each stream, and both together in the order they came, so an error stays beside the step that printed it.
352
+ const kept = { stdout: keeper(), stderr: keeper(), output: keeper() };
353
+ let size = 0;
354
+ let stopped = null;
355
+ let unstarted = null;
356
+ let settled = false;
357
+ const interrupt = () => kill('interrupted');
358
+ const timer = timeoutMs === null ? null : setTimeout(() => kill('timeout'), timeoutMs);
359
+ // The silence is counted again from every piece of output.
360
+ let idle = null;
361
+ const heard = () => {
362
+ if (idleMs === null) return;
363
+ clearTimeout(idle);
364
+ idle = setTimeout(() => kill('idle'), idleMs);
365
+ };
366
+ heard();
367
+ const settle = (status, killedBy) => {
368
+ if (settled) return;
369
+ settled = true;
370
+ clearTimeout(timer);
371
+ clearTimeout(idle);
372
+ clearTimeout(drain);
373
+ signal?.removeEventListener('abort', interrupt);
374
+ live.delete(child.pid);
375
+ resolve({ stdout: kept.stdout.text, stderr: kept.stderr.text, output: kept.output.text, omitted: kept.output.omitted, status, signal: killedBy, stopped, error: unstarted });
376
+ };
377
+ // What was stopped is not waited for: a child left in the background can hold the pipes open long after the shell is gone.
378
+ const release = (status, killedBy) => {
379
+ child.stdout.destroy();
380
+ child.stderr.destroy();
381
+ settle(status, killedBy);
382
+ };
383
+ function kill(why) {
384
+ stopped ??= why;
385
+ killGroup(child.pid);
386
+ if (child.exitCode !== null || child.signalCode !== null) release(child.exitCode, child.signalCode);
387
+ }
388
+ for (const name of ['stdout', 'stderr']) {
389
+ child[name].setEncoding('utf8');
390
+ child[name].on('data', (chunk) => {
391
+ size += chunk.length;
392
+ if (size > MAX_BUFFER_CHARS) kill('overflow');
393
+ else {
394
+ heard();
395
+ kept[name].push(chunk);
396
+ kept.output.push(chunk);
397
+ onOutput?.(chunk);
398
+ }
399
+ });
400
+ }
401
+ child.on('error', (cause) => {
402
+ // Never started, so there is no output and no exit to report: the reason is the answer, and a directory that is gone is the usual one.
403
+ unstarted = unstartedWhy(cause, cwd);
404
+ settle(null, null);
405
+ });
406
+ child.on('close', settle);
407
+ child.on('exit', (status, killedBy) => {
408
+ // The shell is gone: what is still draining is not a silence to stop.
409
+ clearTimeout(idle);
410
+ if (stopped) release(status, killedBy);
411
+ else drain = setTimeout(() => release(status, killedBy), DRAIN_MS);
412
+ });
413
+ if (signal?.aborted) interrupt();
414
+ else signal?.addEventListener('abort', interrupt, { once: true });
415
+ });
416
+ }
417
+
418
+ /** Said once in a process whose shell cannot be sandboxed: with the first result that would have been. */
419
+ let toldUnsandboxed = false;
420
+
421
+ /**
422
+ * The sandbox a command of the model's runs under: on unless the context turns it off (`sandbox: false`, from the
423
+ * user's `shell.sandbox off`), where there is one, and with the network past this machine closed when the context says
424
+ * so (`network: false`, from `shell.network off`). `wrap` is null when it runs without; `note` says why, the first time.
425
+ */
426
+ function jailOf(ctx) {
427
+ if (ctx.sandbox === false) return { wrap: null, writable: [], readOnly: [], note: '' };
428
+ const why = unsandboxable();
429
+ if (why) {
430
+ const note = toldUnsandboxed ? '' : `\n(the shell is not sandboxed: ${why} — a command can write wherever the user can)`;
431
+ toldUnsandboxed = true;
432
+ return { wrap: null, writable: [], readOnly: [], note };
433
+ }
434
+ const writable = writablePlaces(ctx.roots);
435
+ const readOnly = readOnlyPlaces(ctx.roots);
436
+ const offline = ctx.network === false;
437
+ return { wrap: sandboxWrap(writable, { readOnly, network: !offline }), writable, readOnly, offline, note: '' };
438
+ }
439
+
440
+ /** What a job's own tools run the project's checks under: the sandbox its shell is in, or nothing where the shell has none. */
441
+ export const checksWrap = (ctx) => (ctx.sandbox === false || unsandboxable() ? null : jailOf(ctx).wrap);
442
+
443
+ /** `timeout <N> ` in front of a command, N in seconds or with a unit, in its plainest spelling only: flags are the binary's business. */
444
+ const ASKED = /^\s*timeout\s+(\d+)([smh]?)\s+(?=\S)/;
445
+ const UNIT_S = { '': 1, s: 1, m: 60, h: 3600 };
446
+
447
+ /**
448
+ * The limit a command asks for with `timeout N` in front, at most half an hour: both how long it may run and how long
449
+ * it may be silent. macOS has no `timeout`: without one on the PATH the prefix is taken off, and the limit is kept here
450
+ * alone. Null for a command that asks for nothing.
451
+ */
452
+ export function askedLimit(command, path) {
453
+ const asked = ASKED.exec(command);
454
+ if (!asked) return null;
455
+ const seconds = Math.min(Number(asked[1]) * UNIT_S[asked[2]] || ASKED_MAX_S, ASKED_MAX_S);
456
+ return { ms: seconds * 1000, command: onPath('timeout', path) ? command : command.slice(asked[0].length) };
457
+ }
458
+
459
+ /** Whether a program is on a PATH, looked for once for each PATH. */
460
+ const found = new Map();
461
+ function onPath(name, path = '') {
462
+ const key = `${name}\0${path}`;
463
+ if (!found.has(key)) {
464
+ const runnable = (file) => {
465
+ try {
466
+ accessSync(file, constants.X_OK);
467
+ return statSync(file).isFile();
468
+ } catch {
469
+ return false;
470
+ }
471
+ };
472
+ found.set(key, path.split(delimiter).some((dir) => dir && runnable(join(dir, name))));
473
+ }
474
+ return found.get(key);
475
+ }
476
+
477
+ /**
478
+ * The command without its last `&`, when it ends in one that stands alone — not `&&`, `|&` or `>&`, and not quoted,
479
+ * escaped or in a comment: the model asking for it to run in the background. Read conservatively — one line, no
480
+ * here-document — so a command that only might mean it runs as it always has. Null otherwise.
481
+ */
482
+ export function backgrounded(command) {
483
+ const text = command.trimEnd();
484
+ if (!text.endsWith('&') || text.includes('\n') || text.includes('<<')) return null;
485
+ let quote = null;
486
+ for (let i = 0; i < text.length - 1; i++) {
487
+ const c = text[i];
488
+ if (quote) {
489
+ if (c === quote) quote = null;
490
+ else if (c === '\\' && quote === '"') i++;
491
+ } else if (c === '\\') i++;
492
+ else if (c === "'" || c === '"') quote = c;
493
+ // A comment runs to the end of the line, and the & with it.
494
+ else if (c === '#' && (i === 0 || /[\s;&|(]/.test(text[i - 1]))) return null;
495
+ }
496
+ const rest = text.slice(0, -1);
497
+ return quote || /[&|<>\\]$/.test(rest) || !rest.trim() ? null : rest.trimEnd();
498
+ }
499
+
500
+ /**
501
+ * A command left to run in the background: in a process group of its own, under the same sandbox, its output to a log
502
+ * beside the outputs kept for reading, and the call answered at once. Its group goes when this process does, and with
503
+ * the job that started it (`ctx.background`); a `timeout N` it asked for still stops it.
504
+ */
505
+ async function runInBackground(command, ctx, { env, jail }) {
506
+ const asked = askedLimit(command, env.PATH);
507
+ const dir = ctx.spill ?? tmpdir();
508
+ let log;
509
+ let fd;
510
+ try {
511
+ mkdirSync(dir, { recursive: true, mode: 0o700 });
512
+ log = join(dir, `${Date.now()}-${process.pid}-${spilled++}.log`);
513
+ fd = openSync(log, 'a', 0o600);
514
+ } catch (cause) {
515
+ return result(`the command could not be started in the background: there is nowhere to write its log (${cause.message})`, true);
516
+ }
517
+ let child;
518
+ try {
519
+ child = spawnShell(asked?.command ?? command, jail.wrap, { cwd: ctx.cwd, env, stdio: ['ignore', fd, fd], detached: true });
520
+ } finally {
521
+ closeSync(fd);
522
+ }
523
+ const unstarted = await new Promise((resolve) => {
524
+ child.once('spawn', () => resolve(null));
525
+ child.once('error', resolve);
526
+ });
527
+ if (unstarted) return result(unstartedWhy(unstarted, ctx.cwd), true);
528
+ const { pid } = child;
529
+ trackGroup(pid);
530
+ ctx.background?.add(pid);
531
+ const timer = asked ? setTimeout(() => killGroup(pid), asked.ms).unref() : null;
532
+ child.on('exit', () => {
533
+ clearTimeout(timer);
534
+ live.delete(pid);
535
+ ctx.background?.delete(pid);
536
+ });
537
+ // Nothing here waits on it: it runs until it ends, is stopped, or what started it goes.
538
+ child.unref();
539
+ return result(`started in the background (pid ${pid}); its output goes to ${log} — read it with \`tail -n 50 ${log}\`. It is stopped when the job or the chat that started it ends.${jail.note}`);
540
+ }
541
+
542
+ /** A limit as it is said: in minutes when it is whole minutes, else in seconds. */
543
+ const span = (ms) => (ms >= 60_000 && ms % 60_000 === 0 ? `${ms / 60_000} minute${ms === 60_000 ? '' : 's'}` : `${ms / 1000} second${ms === 1000 ? '' : 's'}`);
544
+
545
+ /**
546
+ * A shell command, in the project directory, without the secrets, refused when the guard says so, and in the sandbox
547
+ * where there is one. It is stopped when it runs past its limit or prints nothing for two minutes — a `timeout N` in
548
+ * front sets both — and one ending in a lone `&` is left running in the background, with a log.
549
+ */
550
+ export async function runBash({ command, restart }, ctx, { signal = null, timeoutMs = COMMAND_TIMEOUT_MS, idleMs = IDLE_TIMEOUT_MS, onOutput = null } = {}) {
551
+ // The tool is specified as one session the model may restart; here every call is its own shell, so there is nothing to restart.
552
+ if (restart) return result('Bash session restarted: every command already runs in a fresh shell, in the project directory');
553
+ if (typeof command !== 'string' || !command.trim()) return result('bash needs a command', true);
554
+ const refused = guardCommand(command, { cwd: ctx.cwd });
555
+ if (refused) return result(refused, true);
556
+ const env = unprompted(ctx.env ?? childEnv(), ctx.cwd);
557
+ const jail = jailOf(ctx);
558
+ const behind = backgrounded(command);
559
+ if (behind !== null) return runInBackground(behind, ctx, { env, jail });
560
+ // The commands that run the project's checks give each check its own limit; one limit over all of them would cut a verdict off half-way.
561
+ // A check may work for minutes without a word, so they are not held to a silence either.
562
+ const own = OWN_LIMITS.test(command);
563
+ const asked = own ? null : askedLimit(command, env.PATH);
564
+ const limit = own ? null : (asked?.ms ?? timeoutMs);
565
+ // A silence as long as the whole limit can never come first: a command that asked for its limit has only the one.
566
+ const quiet = own || asked ? null : idleMs;
567
+ const run = await runCommand(asked?.command ?? command, { cwd: ctx.cwd, env, signal, timeoutMs: limit, idleMs: quiet, onOutput, wrap: jail.wrap });
568
+ if (run.error) return result(run.error + jail.note, true);
569
+ const failed = run.stopped !== null || run.status !== 0;
570
+ const output = run.output.trimEnd();
571
+ const tail =
572
+ run.stopped === 'timeout' ? `\n(stopped: it ran past ${span(limit)})`
573
+ : run.stopped === 'idle' ? `\n(stopped: it printed nothing for ${span(quiet)} — to wait longer, run it again as \`timeout 600 ${command}\`, or in the background with a trailing \`&\` and read its log)`
574
+ : run.stopped === 'interrupted' ? `\n(${INTERRUPTED})`
575
+ : run.stopped === 'overflow' ? `\n(stopped: it printed more than ${MAX_BUFFER_CHARS / 1024 / 1024} MB — narrow the command: tail, grep, or a line range)`
576
+ : failed ? `\n(exit ${run.status ?? run.signal})` : '';
577
+ // Output the model is shown only the ends of, or with a line cut short, is kept as it was printed — as much as was
578
+ // held — where it can read a range of it.
579
+ const tidied = shownOf(output, run.omitted);
580
+ const kept = ctx.spill && (tidied.capped || tidied.cut > 0) ? spill(ctx.spill, output, run.omitted) : null;
581
+ const shown = tidied.show(kept) + tail;
582
+ if (jail.wrap && run.stopped === null && run.status !== 0 && blockedWrite(output)) return blocked(command, shown, ctx, jail, { signal, timeoutMs, idleMs, onOutput });
583
+ return result(shown + jail.note, failed);
584
+ }
585
+
586
+ /**
587
+ * A command the sandbox kept from writing: what it printed, and where it may write. Somebody there (`ctx.approve`, the
588
+ * question an MCP call off the allow list is put with) may let that exact command run once more, outside the sandbox —
589
+ * the guard has passed it already. With nobody there, the model is told to report it.
590
+ */
591
+ async function blocked(command, shown, ctx, jail, options) {
592
+ const except = jail.readOnly.length > 0 ? `, except git's hooks and config: ${jail.readOnly.join(', ')}` : '';
593
+ const offline = jail.offline ? ' — and nothing past this machine can be reached: the user turned the network off (shell.network)' : '';
594
+ const said = `${shown}\n(the sandbox blocked a write outside the project — only these can be written: ${jail.writable.join(', ')}${except}${offline})`;
595
+ if (!ctx.approve) return result(`${said}\n(nobody is here to allow it outside the sandbox: report it, with the command, so the user can run it themselves)`, true);
596
+ const { signal } = options;
597
+ const stopped = new Promise((resolve) => signal?.addEventListener('abort', () => resolve('no'), { once: true }));
598
+ // Asked as what it is — this one run outside the sandbox, yes or no — never as an MCP call that could be allowed always.
599
+ const answer = signal?.aborted ? 'no' : await Promise.race([ctx.approve({ name: BASH_TOOL.name, server: 'bash', tool: 'outside the sandbox', input: { command }, unsandboxed: true, signal }), stopped]);
600
+ // Always is once here: what is allowed is this one run, never the sandbox off.
601
+ if (answer !== 'once' && answer !== 'always') return result(`${said}\n(the user declined running it outside the sandbox: do not run it again; carry on another way, or ask the user)`, true);
602
+ const again = await runBash({ command }, { ...ctx, sandbox: false }, options);
603
+ return { ...again, content: `(the sandbox blocked a write outside the project; the user let it run again outside the sandbox)\n${again.content}` };
604
+ }
605
+
606
+ /** How much of a file is looked at to tell a binary from text: a NUL byte in its first pages is one. */
607
+ const BINARY_PROBE_BYTES = 8192;
608
+
609
+ function view(path, range) {
610
+ if (statSync(path).isDirectory()) return result(cap(readdirSync(path).join('\n')));
611
+ const bytes = readFileSync(path);
612
+ // A binary shown as text is pages of nonsense, every page billed: say what it is instead.
613
+ if (bytes.subarray(0, BINARY_PROBE_BYTES).includes(0)) return result(`${path} is a binary file (${bytes.length} bytes) — not shown; use a tool that reads its kind, or \`file\` and \`xxd | head\` for a look`, true);
614
+ const lines = bytes.toString('utf8').split('\n');
615
+ let [from, to] = Array.isArray(range) && range.length === 2 ? range : [1, lines.length];
616
+ from = Math.max(1, from);
617
+ to = to === -1 ? lines.length : Math.min(lines.length, to);
618
+ // The window ends at the last whole line that fits the cap a command's output has, so a long file is never shown
619
+ // with a hole in it and the next view carries on from a line. Only a line too long to read — a minified file's — is cut inside.
620
+ const shown = [];
621
+ let size = 0;
622
+ for (const [i, line] of lines.slice(from - 1, Math.min(to, from - 1 + VIEW_CAP_LINES)).entries()) {
623
+ const numbered = `${from + i}\t${cutLine(line)}`;
624
+ if (shown.length > 0 && size + numbered.length + 1 > OUTPUT_CAP_CHARS) break;
625
+ shown.push(numbered);
626
+ size += numbered.length + 1;
627
+ }
628
+ const cut = to - (from - 1 + shown.length);
629
+ const body = shown.join('\n');
630
+ return result(cut > 0 ? `${body}\n[${cut} more lines up to ${to} — view a smaller range]` : body);
631
+ }
632
+
633
+ /**
634
+ * Where old_str is in a file: exactly; else with the file's own line endings; else line by line without trailing spaces;
635
+ * else without the indentation too, in which case the replacement is set in at the file's indentation. One place, with how
636
+ * it was found, or how many places it was found in — a looser match is still held to being the only one. A model that
637
+ * copies a line with a space missing at its end, or at the wrong depth, otherwise spends a turn on "not found".
638
+ */
639
+ function locate(text, oldStr) {
640
+ const exact = (needle, how = null) => {
641
+ const hits = [];
642
+ for (let at = text.indexOf(needle); at !== -1; at = text.indexOf(needle, at + needle.length)) hits.push(at);
643
+ return hits.length === 0 ? null : { hits: hits.length, start: hits[0], end: hits[0] + needle.length, how };
644
+ };
645
+ const found = exact(oldStr) ?? (text.includes('\r\n') && !oldStr.includes('\r') ? exact(oldStr.replaceAll('\n', '\r\n'), "with the file's line endings") : null);
646
+ if (found) return found;
647
+ const lines = text.split('\n');
648
+ const starts = [];
649
+ for (let at = 0, i = 0; i < lines.length; i++) {
650
+ starts.push(at);
651
+ at += lines[i].length + 1;
652
+ }
653
+ const wanted = oldStr.replace(/\r\n/g, '\n').split('\n');
654
+ const byLines = (same, how) => {
655
+ const hits = [];
656
+ for (let i = 0; i + wanted.length <= lines.length; i++) if (wanted.every((w, j) => same(lines[i + j], w))) hits.push(i);
657
+ if (hits.length === 0) return null;
658
+ const [i] = hits;
659
+ const last = i + wanted.length - 1;
660
+ // The span ends before a carriage return the line keeps: the replacement is given the file's line endings itself.
661
+ return { hits: hits.length, start: starts[i], end: starts[last] + lines[last].replace(/\r$/, '').length, how, line: i };
662
+ };
663
+ const trimmed = byLines((a, b) => a.trimEnd() === b.trimEnd(), 'without trailing spaces');
664
+ if (trimmed) return trimmed;
665
+ const loose = byLines((a, b) => a.trim() === b.trim(), 'without its indentation');
666
+ if (!loose) return null;
667
+ // The depth the model wrote at, moved to the depth the file has: every line of the replacement indented like the old one is re-indented.
668
+ const indentOf = (line) => /^[ \t]*/.exec(line)[0];
669
+ const was = indentOf(wanted[0]);
670
+ const is = indentOf(lines[loose.line]);
671
+ if (was !== is) loose.reindent = (replacement) => replacement.split('\n').map((l) => (l.startsWith(was) ? `${is}${l.slice(was.length)}` : l)).join('\n');
672
+ return loose;
673
+ }
674
+
675
+ /**
676
+ * An edit for the screen, which draws it as a diff: the line the change begins on, and the whole lines it touched as
677
+ * the file had them and as it has them now — what was matched and written, not what the model sent. The model is told none of it.
678
+ */
679
+ function changeOf(text, { start, end }, replacement) {
680
+ const from = text.lastIndexOf('\n', start - 1) + 1;
681
+ // A span that ends on a newline took whole lines: the line after it is not part of the change.
682
+ const whole = end > start && text[end - 1] === '\n';
683
+ const to = whole ? end : text.indexOf('\n', end) === -1 ? text.length : text.indexOf('\n', end);
684
+ // For the screen the line endings are plain, whatever the file's are.
685
+ const lines = (t) => redact(t.replace(/\r\n/g, '\n').replace(whole ? /\n$/ : /\r$/, '')).text;
686
+ return { line: text.slice(0, from).split('\n').length, old: lines(text.slice(from, to)), new: lines(`${text.slice(from, start)}${replacement}${text.slice(end, to)}`) };
687
+ }
688
+
689
+ /** A file as it stood when the model last looked: a change on disk since moves one or the other. */
690
+ const stampOf = (path) => {
691
+ const { mtimeMs, size } = statSync(path);
692
+ return { mtimeMs, size };
693
+ };
694
+
695
+ /** What the model has seen of each file in this context — viewed, or written by the editor — kept for as long as the context is. */
696
+ const seenIn = (ctx) => (ctx.seen ??= new Map());
697
+
698
+ /** The line an edit opens with when its file changed on disk since the model saw it: the edit was made against what it remembers. */
699
+ function changedSince(path, ctx) {
700
+ const was = ctx.seen?.get(path);
701
+ if (!was) return null;
702
+ const now = stampOf(path);
703
+ return now.mtimeMs !== was.mtimeMs || now.size !== was.size ? `${path} changed on disk since you last viewed it; view it again if this edit depends on the rest of it.` : null;
704
+ }
705
+
706
+ /** How long a parse check may take before it is let go unanswered. */
707
+ const PARSE_TIMEOUT_MS = 5_000;
708
+ /** How many lines of a parse error are shown: where it is and what it is, not a stack. */
709
+ const PARSE_ERROR_LINES = 5;
710
+ /**
711
+ * Python's own parser, its error without a traceback; isolated, so a file in the project named like a module is not run,
712
+ * and writing no bytecode. The bytes are parsed, so the file's own coding line decides how they read, not the locale.
713
+ */
714
+ const PY_PARSE = 'import ast,sys,traceback\ntry: ast.parse(open(sys.argv[1], "rb").read(), sys.argv[1])\nexcept Exception as e: sys.exit("".join(traceback.format_exception_only(type(e), e)))';
715
+
716
+ /**
717
+ * Why a file does not parse, as its parser says it in a few lines — or null: it parses, it is of no kind checked here,
718
+ * or the parser is missing or too slow to say. `.js .mjs .cjs` by `node --check`, `.json` here, `.py` and `.go` by
719
+ * their own tools when they are on the PATH.
720
+ */
721
+ function parseError(path, ctx) {
722
+ const env = ctx.env ?? childEnv();
723
+ const ext = extname(path);
724
+ let run;
725
+ if (ext === '.json') {
726
+ try {
727
+ JSON.parse(readFileSync(path, 'utf8'));
728
+ return null;
729
+ } catch (cause) {
730
+ return cause.message;
731
+ }
732
+ }
733
+ // The binary Bun builds is no node to check a script with: it asks the node on PATH, if there is one.
734
+ if (['.js', '.mjs', '.cjs'].includes(ext) && (!process.versions.bun || onPath('node', env.PATH))) run = [process.versions.bun ? 'node' : process.execPath, ['--check', path]];
735
+ else if (ext === '.py' && onPath('python3', env.PATH)) run = ['python3', ['-I', '-B', '-c', PY_PARSE, path]];
736
+ else if (ext === '.go' && onPath('gofmt', env.PATH)) run = ['gofmt', ['-e', '-l', path]];
737
+ else return null;
738
+ const out = spawnSync(run[0], run[1], { env, encoding: 'utf8', timeout: PARSE_TIMEOUT_MS, stdio: ['ignore', 'pipe', 'pipe'] });
739
+ if (out.error || out.status === null || out.status === 0) return null;
740
+ const lines = `${out.stderr}\n${out.stdout}`.split('\n').filter((l) => l.trim());
741
+ return lines.length > 0 ? lines.slice(0, PARSE_ERROR_LINES).map((l) => l.slice(0, 200)).join('\n') : `the parser stopped with status ${out.status}`;
742
+ }
743
+
744
+ /** How many of a session's turns /undo can walk back through; older ones are let go as new ones are kept. */
745
+ const UNDO_TURNS = 20;
746
+ /** How long the undo of a session nothing has touched is kept: as long as the session can be resumed. */
747
+ const UNDO_KEEP_MS = 30 * 24 * 3_600_000;
748
+ const MANIFEST = 'manifest.json';
749
+
750
+ /** A session's kept turns, oldest first: folders named by their number. */
751
+ function undoTurns(sessionDir) {
752
+ try {
753
+ return readdirSync(sessionDir).filter((name) => /^\d+$/.test(name)).map(Number).sort((a, b) => a - b);
754
+ } catch {
755
+ return [];
756
+ }
757
+ }
758
+
759
+ /** The folder the coming turn's undo goes in — made only when the editor first changes a file in it. */
760
+ export const nextUndoTurn = (sessionDir) => join(sessionDir, String((undoTurns(sessionDir).at(-1) ?? 0) + 1));
761
+
762
+ const readManifest = (turnDir) => {
763
+ try {
764
+ return JSON.parse(readFileSync(join(turnDir, MANIFEST), 'utf8'));
765
+ } catch {
766
+ return null;
767
+ }
768
+ };
769
+
770
+ /**
771
+ * After the editor's first change to a file in a turn: what the file held before it (`before`, its bytes), or that it
772
+ * was not there (null), kept in the turn's folder for /undo, readable by the user alone. A later change to it in the same
773
+ * turn keeps nothing — /undo goes back to before the turn. The turn that starts a folder lets go of the oldest beyond
774
+ * UNDO_TURNS, and of the undo of sessions long untouched.
775
+ */
776
+ function keepForUndo(turnDir, path, before) {
777
+ const manifest = readManifest(turnDir) ?? [];
778
+ if (manifest.some((entry) => entry.path === path)) return;
779
+ if (manifest.length === 0) {
780
+ const sessionDir = dirname(turnDir);
781
+ mkdirSync(turnDir, { recursive: true, mode: 0o700 });
782
+ for (const old of undoTurns(sessionDir).slice(0, -UNDO_TURNS)) rmSync(join(sessionDir, String(old)), { recursive: true, force: true });
783
+ const home = dirname(sessionDir);
784
+ for (const name of readdirSync(home)) {
785
+ const other = join(home, name);
786
+ if (other !== sessionDir && Date.now() - statSync(other).mtimeMs > UNDO_KEEP_MS) rmSync(other, { recursive: true, force: true });
787
+ }
788
+ }
789
+ const kept = before === null ? null : String(manifest.length);
790
+ if (kept !== null) writeFileSync(join(turnDir, kept), before, { mode: 0o600 });
791
+ manifest.push({ path, kept, mode: kept === null ? null : statSync(path).mode & 0o777 });
792
+ writeFileSync(join(turnDir, MANIFEST), JSON.stringify(manifest), { mode: 0o600 });
793
+ }
794
+
795
+ /**
796
+ * /undo: every file the session's last kept turn changed, put back as it was before that turn — a file it created is
797
+ * deleted — and the turn let go, so the next /undo reaches the one before. Null when there is none to undo.
798
+ */
799
+ export function undoLast(sessionDir) {
800
+ for (const n of undoTurns(sessionDir).reverse()) {
801
+ const turnDir = join(sessionDir, String(n));
802
+ const manifest = readManifest(turnDir);
803
+ if (!manifest) {
804
+ rmSync(turnDir, { recursive: true, force: true });
805
+ continue;
806
+ }
807
+ const done = { restored: [], deleted: [] };
808
+ for (const { path, kept, mode } of manifest) {
809
+ if (kept === null) {
810
+ rmSync(path, { force: true });
811
+ done.deleted.push(path);
812
+ } else {
813
+ mkdirSync(dirname(path), { recursive: true });
814
+ writeFileSync(path, readFileSync(join(turnDir, kept)), { mode: mode ?? 0o644 });
815
+ done.restored.push(path);
816
+ }
817
+ }
818
+ rmSync(turnDir, { recursive: true, force: true });
819
+ return done;
820
+ }
821
+ return null;
822
+ }
823
+
824
+ /**
825
+ * One change to a file by the editor, and what is owed around it: what the file held is kept for /undo (`ctx.undo`, the
826
+ * chat's turn folder), a change on disk since the model saw it is said first, and a parse the change broke — one that held
827
+ * before it — is said after. `created`: the file was not there, so it parsed before as far as anyone is concerned.
828
+ */
829
+ function change(path, ctx, write, { created = false } = {}) {
830
+ const stale = created ? null : changedSince(path, ctx);
831
+ const before = ctx.undo && !created ? readFileSync(path) : null;
832
+ const broken = created ? null : parseError(path, ctx);
833
+ write();
834
+ // Kept once the write has gone through: a change refused — a create of a file already there — has nothing to undo. A keep
835
+ // that fails is said, not thrown: the change is made, and a model told it failed would make it twice.
836
+ let unkept = null;
837
+ try {
838
+ if (ctx.undo) keepForUndo(ctx.undo, path, before);
839
+ } catch (cause) {
840
+ unkept = `(this change could not be kept for /undo: ${cause.message})`;
841
+ }
842
+ if (created || ctx.seen?.has(path)) seenIn(ctx).set(path, stampOf(path));
843
+ const now = broken === null ? parseError(path, ctx) : null;
844
+ return (said) => [stale, said, unkept, now && `The file no longer parses:\n${now}`].filter(Boolean).join('\n');
845
+ }
846
+
847
+ /** A whole line that is one comment — `//`, `#`, `/* *\/`, `<!-- -->`, `--`, JSX's `{/* *\/}` — and what it says. */
848
+ const COMMENT_LINE = /^(?:\/\/+|#+|\/\*+|<!--|--|\{\/\*+)\s*(.*?)\s*(?:\*+\/\}?|-->)?$/;
849
+ /** The block comments that close on their line: only dots in one is a gap left in the code, where `// ...` alone may be a deliberate stub. */
850
+ const CLOSED_COMMENT = /(?:\*\/\}?|-->)$/;
851
+ const DOTS = /\.{3,}|…/g;
852
+ /** That what was left out stays as it was: optional after `rest of the code`; needed after `other methods` with no dots around it, which could be a heading. */
853
+ const STAYS = String.raw`(?:\s+(?:is\s+|are\s+|stays\s+|remains\s+|goes\s+)?(unchanged|the same|as before|as is|omitted|here|goes here|follows|not shown))?`;
854
+ /** What a gap stands for. */
855
+ const STUFF = String.raw`(?:code|file|function|functions|method|methods|class|implementation|component|module|body|content|contents|imports?|tests?|logic|lines?|cases|fields|properties|props|styles)`;
856
+ const REST_OF = new RegExp(String.raw`^(?:(?:the|and|all)\s+)?(?:rest|remainder)\s+of\s+(?:the\s+|this\s+|your\s+)?(?:\w+\s+)?${STUFF}${STAYS}$`);
857
+ const KEPT_AS_IS = new RegExp(String.raw`^(?:(?:the|all)\s+)?(?:existing|previous|original|other|remaining|unchanged|same)\s+(?:\w+\s+)?${STUFF}${STAYS}$`);
858
+ const UNCHANGED = /^(?:unchanged|no changes|as before|same as before)$/;
859
+ /** Files whose text is prose for a reader: an example in one shows code with its gaps on purpose. */
860
+ const PROSE = ['.md', '.mdx', '.markdown', '.txt', '.rst', '.adoc'];
861
+ /** The longest a line that stands for code is: a gap is said in a few words, and a longer line is never read for one. */
862
+ const GAP_MAX_CHARS = 200;
863
+
864
+ /**
865
+ * Whether a line stands for code instead of holding it — `// ... rest of the code unchanged`, `# ... existing code ...`,
866
+ * `/* rest of file *\/`, `// (unchanged)`, `<!-- ... -->` — as a model writes one when it means "keep what is there".
867
+ * Gemini CLI refuses the same; read narrowly here: a whole line, a comment or dots around it, and nothing in it but the gap. A
868
+ * `...` in code or prose, a comment that only mentions the rest of something, and `// ...` alone are never one.
869
+ */
870
+ function standsForCode(line) {
871
+ const trimmed = line.trim();
872
+ if (trimmed.length > GAP_MAX_CHARS) return false;
873
+ const comment = COMMENT_LINE.exec(trimmed);
874
+ const said = comment ? comment[1] : trimmed;
875
+ const dotted = /^(?:\.{3}|…)|(?:\.{3}|…)$/.test(said);
876
+ const words = said.replace(DOTS, ' ').replace(/^[\s([{]+|[\s)\]}.,;:]+$/g, '').replace(/\s+/g, ' ').trim().toLowerCase();
877
+ const kept = KEPT_AS_IS.exec(words);
878
+ // Bare, only dots around the words make it one: `...existing code...`; a spread such as `...rest,` never reads as words.
879
+ if (!comment) return dotted && (REST_OF.test(words) || kept !== null);
880
+ if (words === '') return dotted && CLOSED_COMMENT.test(trimmed);
881
+ return REST_OF.test(words) || UNCHANGED.test(words) || (kept !== null && (dotted || kept[1] !== undefined));
882
+ }
883
+
884
+ /** Why an edit's new text is not written: a line of it stands for code, and the file — `had`, as it is — does not already hold that line. Null when none does. */
885
+ function placeholderIn(path, field, text, had = '') {
886
+ if (PROSE.includes(extname(path).toLowerCase())) return null;
887
+ const lines = String(text ?? '').split('\n').filter(standsForCode);
888
+ if (lines.length === 0) return null;
889
+ const there = new Set(had.split('\n').map((l) => l.trim()));
890
+ const gap = lines.find((l) => !there.has(l.trim()));
891
+ return gap === undefined ? null : `not written: ${field} has a line that stands for code instead of holding it — ${JSON.stringify(gap.trim())} — and the file would hold that line, not the code. Write the code out in full; to leave code as it is, leave it out of the edit.`;
892
+ }
893
+
894
+ /** The text editor's four commands, each inside the jail; secret files are neither shown nor written. */
895
+ export function runEditor(input, ctx) {
896
+ let path;
897
+ try {
898
+ path = jailed(input.path, ctx);
899
+ } catch (cause) {
900
+ return result(cause.message, true);
901
+ }
902
+ try {
903
+ const secret = guardPath(path) ?? guardPath(realAncestor(path));
904
+ // Every root can be read; only the project (the first) can be written. A job's own folder holds what judges it.
905
+ if (input.command !== 'view' && ctx.roots.length > 1) {
906
+ try {
907
+ jailed(input.path, { cwd: ctx.cwd, roots: ctx.roots.slice(0, 1) });
908
+ } catch {
909
+ return result(`${path} can be read, not changed — only files in the project (${ctx.roots[0]}) are edited`, true);
910
+ }
911
+ }
912
+ // What git runs by itself — a hook on the next commit, a command its config names — runs outside the sandbox: the shell cannot write it, nor can this.
913
+ if (input.command !== 'view') {
914
+ const at = realAncestor(path);
915
+ const kept = readOnlyPlaces(ctx.roots).find((place) => path === place || path.startsWith(`${place}${sep}`) || at === place || at.startsWith(`${place}${sep}`));
916
+ if (kept) return result(`${path} is git's own hooks or configuration: not changed here — what git runs by itself would run outside the sandbox. Say in your report what it needs.`, true);
917
+ }
918
+ switch (input.command) {
919
+ case 'view': {
920
+ if (secret) return result(secret, true);
921
+ if (!existsSync(path)) return result(`${path} does not exist`, true);
922
+ const shown = view(path, input.view_range);
923
+ if (!shown.isError && statSync(path).isFile()) seenIn(ctx).set(path, stampOf(path));
924
+ return shown;
925
+ }
926
+ case 'create': {
927
+ if (secret) return result(secret, true);
928
+ const gap = placeholderIn(path, 'file_text', input.file_text);
929
+ if (gap) return result(gap, true);
930
+ // The write below refuses a file that is there anyway; said here in words that tell the model what to do instead.
931
+ if (existsSync(path) && statSync(path).isFile()) {
932
+ const held = readFileSync(path, 'utf8');
933
+ const lines = held.split('\n').length - (held.endsWith('\n') ? 1 : 0);
934
+ return result(`${path} already exists (${lines} line${lines === 1 ? '' : 's'}): change the lines that change with str_replace or insert — a file is never rewritten whole`, true);
935
+ }
936
+ mkdirSync(dirname(path), { recursive: true });
937
+ const said = change(path, ctx, () => writeFileSync(path, String(input.file_text ?? ''), { flag: 'wx' }), { created: true });
938
+ return result(said(`created ${path}`));
939
+ }
940
+ case 'str_replace': {
941
+ if (secret) return result(secret, true);
942
+ if (!input.old_str) return result('str_replace needs old_str', true);
943
+ if (input.new_str !== undefined && input.old_str === input.new_str) return result('old_str and new_str are the same — nothing would change', true);
944
+ const text = readFileSync(path, 'utf8');
945
+ const gap = placeholderIn(path, 'new_str', input.new_str, text);
946
+ if (gap) return result(gap, true);
947
+ const where = locate(text, input.old_str);
948
+ if (!where) return result(`old_str was not found in ${path}`, true);
949
+ if (where.hits !== 1) return result(`old_str appears ${where.hits} times in ${path} — include more context so it is unique`, true);
950
+ let replacement = String(input.new_str ?? '');
951
+ if (where.how) {
952
+ if (text.includes('\r\n')) replacement = replacement.replace(/\r?\n/g, '\r\n');
953
+ if (where.reindent) replacement = where.reindent(replacement);
954
+ }
955
+ const said = change(path, ctx, () => writeFileSync(path, `${text.slice(0, where.start)}${replacement}${text.slice(where.end)}`));
956
+ return { ...result(said(`edited ${path}${where.how ? ` (old_str matched ${where.how})` : ''}`)), edit: changeOf(text, where, replacement) };
957
+ }
958
+ case 'insert': {
959
+ if (secret) return result(secret, true);
960
+ const lines = readFileSync(path, 'utf8').split('\n');
961
+ const line = Number(input.insert_line ?? 0);
962
+ if (!Number.isInteger(line)) return result('insert needs insert_line: the number of the line to insert after, 0 for the top of the file', true);
963
+ // The tool sends the text as insert_text, a line with its newline; new_str is what an earlier version of the tool sent.
964
+ const text = input.insert_text ?? input.new_str;
965
+ if (typeof text !== 'string') return result('insert needs insert_text: the text to insert', true);
966
+ const gap = placeholderIn(path, input.insert_text === undefined ? 'new_str' : 'insert_text', text, lines.join('\n'));
967
+ if (gap) return result(gap, true);
968
+ // A file ending in a newline splits to a last empty piece, which is not a line to insert after.
969
+ const at = Math.max(0, Math.min(lines.at(-1) === '' ? lines.length - 1 : lines.length, line));
970
+ lines.splice(at, 0, text.replace(/\n$/, ''));
971
+ const said = change(path, ctx, () => writeFileSync(path, lines.join('\n')));
972
+ return { ...result(said(`inserted into ${path} after line ${at}`)), edit: { line: at + 1, old: '', new: redact(text.replace(/\n$/, '')).text } };
973
+ }
974
+ default:
975
+ return result(`unknown command ${input.command}`, true);
976
+ }
977
+ } catch (cause) {
978
+ return result(cause.message, true);
979
+ }
980
+ }
981
+
982
+ /** One tool call, whichever tool it names; a name nothing answers to is an error the model can read. */
983
+ export function runTool(block, ctx, { signal = null, onOutput = null } = {}) {
984
+ if (block.name === BASH_TOOL.name) return runBash(block.input ?? {}, ctx, { signal, onOutput });
985
+ if (block.name === EDITOR_TOOL.name) return runEditor(block.input ?? {}, ctx);
986
+ return result(`no tool called ${block.name}`, true);
987
+ }