warden-agent 0.4.0 → 0.4.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.
@@ -3,7 +3,7 @@
3
3
  // run() returns { content: string for the model, display: { title, lines?, diff? } for the terminal }.
4
4
  import fs from "node:fs";
5
5
  import path from "node:path";
6
- import { spawn } from "node:child_process";
6
+ import { spawn, spawnSync } from "node:child_process";
7
7
 
8
8
  const MAX_OUT = 40_000;
9
9
  const SKIP_DIRS = new Set([".git", "node_modules", ".hg", ".svn", "dist", "build", ".next", ".venv", "venv", "__pycache__", ".cache", "target", ".idea"]);
@@ -55,23 +55,157 @@ export function detectShell() {
55
55
  return { cmd: "powershell.exe", args: (c) => ["-NoProfile", "-NonInteractive", "-Command", c], name: "PowerShell (Windows)" };
56
56
  }
57
57
 
58
- function runShell(command, { cwd, timeoutMs, signal }) {
58
+ const UNIX = process.platform !== "win32";
59
+ const shellEnv = () => ({ ...process.env, WARDEN: "1" });
60
+
61
+ // Kill a shell and everything it started. Killing only the shell is not enough: a dev server or watcher it launched
62
+ // keeps running and keeps the output pipe open, so the command would never finish.
63
+ export function killTree(p) {
64
+ if (!p?.pid) return;
65
+ if (!UNIX) {
66
+ try { spawnSync("taskkill", ["/pid", String(p.pid), "/T", "/F"], { windowsHide: true, stdio: "ignore", timeout: 5000 }); } catch {}
67
+ try { p.kill(); } catch {}
68
+ return;
69
+ }
70
+ try { process.kill(-p.pid, "SIGTERM"); } catch { try { p.kill("SIGTERM"); } catch {} }
71
+ const t = setTimeout(() => { try { process.kill(-p.pid, "SIGKILL"); } catch {} }, 1500);
72
+ t.unref?.();
73
+ }
74
+
75
+ const spawnShell = (command, cwd) => {
59
76
  const sh = detectShell();
77
+ // detached on Unix = its own process group, so killTree can stop the whole group
78
+ return spawn(sh.cmd, sh.args(command), { cwd, windowsHide: true, detached: UNIX, env: shellEnv() });
79
+ };
80
+
81
+ // Runs a command to completion. Always returns: on exit, on timeout, on interrupt, and also when the shell exits but
82
+ // something it started in the background still holds the output open.
83
+ function runShell(command, { cwd, timeoutMs, signal, onOutput }) {
60
84
  return new Promise((resolve) => {
61
- const p = spawn(sh.cmd, sh.args(command), { cwd, windowsHide: true, env: { ...process.env, WARDEN: "1" } });
62
- let out = "", killed = null;
63
- const kill = (why) => { killed = why; try { p.kill(); } catch {} };
64
- const t = setTimeout(() => kill("timeout"), timeoutMs);
85
+ let p;
86
+ try { p = spawnShell(command, cwd); } catch (e) { return resolve({ code: -1, out: `failed to start shell: ${e.message}`, killed: null }); }
87
+ let out = "", killed = null, done = false, code = null, lingered = false;
88
+ const timers = [];
89
+ const later = (ms, fn) => { const t = setTimeout(fn, ms); timers.push(t); return t; };
90
+ const finish = () => {
91
+ if (done) return;
92
+ done = true;
93
+ timers.forEach(clearTimeout);
94
+ signal?.removeEventListener("abort", onAbort);
95
+ try { p.stdout.destroy(); p.stderr.destroy(); } catch {}
96
+ resolve({ code, out, killed, lingered });
97
+ };
98
+ const kill = (why) => {
99
+ if (killed || done) return;
100
+ killed = why;
101
+ killTree(p);
102
+ later(4000, finish); // never wait forever, even if the kill did not take
103
+ };
65
104
  const onAbort = () => kill("interrupted");
66
- signal?.addEventListener("abort", onAbort, { once: true });
67
- const add = (d) => { if (out.length < MAX_OUT * 2) out += d; };
105
+ later(timeoutMs, () => kill("timeout"));
106
+ if (signal?.aborted) onAbort(); else signal?.addEventListener("abort", onAbort, { once: true });
107
+ const add = (d) => {
108
+ const s = String(d);
109
+ if (out.length < MAX_OUT * 2) out += s;
110
+ try { onOutput?.(s); } catch {}
111
+ };
68
112
  p.stdout.on("data", add); p.stderr.on("data", add);
69
- p.on("error", (e) => { clearTimeout(t); resolve({ code: -1, out: `failed to start shell: ${e.message}`, killed }); });
70
- p.on("close", (code) => { clearTimeout(t); signal?.removeEventListener("abort", onAbort); resolve({ code, out, killed }); });
113
+ p.on("error", (e) => { out += `failed to start shell: ${e.message}`; code = -1; finish(); });
114
+ p.on("exit", (c) => {
115
+ code = c;
116
+ // the shell is done; if the output stays open, a process it started is still running
117
+ later(500, () => { lingered = !killed; finish(); });
118
+ });
119
+ p.on("close", (c) => { code ??= c; finish(); });
71
120
  p.stdin.end();
72
121
  });
73
122
  }
74
123
 
124
+ // ---- background jobs (dev servers, watchers) ----------------------------------
125
+
126
+ const JOBS = new Map();
127
+ let jobSeq = 0;
128
+ const tail = (s, n = 4000) => (s.length > n ? `[… ${s.length - n} earlier characters]\n` + s.slice(-n) : s);
129
+
130
+ export function startJob(command, cwd) {
131
+ const p = spawnShell(command, cwd);
132
+ const job = { id: ++jobSeq, command, cwd, pid: p.pid, started: Date.now(), out: "", exit: undefined, p };
133
+ const add = (d) => { job.out += d; if (job.out.length > 200_000) job.out = job.out.slice(-100_000); };
134
+ p.stdout.on("data", add); p.stderr.on("data", add);
135
+ p.on("error", (e) => { job.out += `failed to start: ${e.message}\n`; job.exit = -1; });
136
+ p.on("exit", (c, sig) => { job.exit = job.stopped ? "stopped" : c ?? sig ?? "stopped"; });
137
+ p.stdin.end();
138
+ // a running job must not keep `warden -p` alive; Warden stops all jobs when it exits
139
+ p.unref(); p.stdout.unref?.(); p.stderr.unref?.();
140
+ JOBS.set(job.id, job);
141
+ return job;
142
+ }
143
+
144
+ export const listJobs = () => [...JOBS.values()];
145
+ export const jobRunning = (j) => j.exit === undefined;
146
+
147
+ export function stopJob(job) {
148
+ if (!jobRunning(job)) return false;
149
+ job.stopped = true;
150
+ killTree(job.p);
151
+ job.exit = "stopped";
152
+ return true;
153
+ }
154
+
155
+ export function stopAllJobs() { for (const j of JOBS.values()) stopJob(j); }
156
+ process.on("exit", stopAllJobs);
157
+
158
+ export function describeJob(j) {
159
+ const secs = Math.round((Date.now() - j.started) / 1000);
160
+ const state = jobRunning(j) ? `running for ${secs}s` : `exited (${j.exit})`;
161
+ return `job ${j.id} (pid ${j.pid}) ${state}: ${j.command}`;
162
+ }
163
+
164
+ // ---- edit helpers ---------------------------------------------------------------
165
+
166
+ // Finds old_string as whole lines while ignoring trailing spaces (a common reason exact matches fail).
167
+ // Returns [{ start, end, line }] character ranges in `text`.
168
+ function findLooseLines(text, oldS, cmp = (a, b) => a.trimEnd() === b.trimEnd()) {
169
+ const nl = text.includes("\r\n") ? "\r\n" : "\n";
170
+ const lines = text.split(nl);
171
+ const want = oldS.replace(/\r\n/g, "\n").split("\n");
172
+ const endsWithNl = want.length > 1 && want.at(-1) === "";
173
+ if (endsWithNl) want.pop();
174
+ if (!want.some((l) => l.trim())) return [];
175
+ const offs = []; let o = 0;
176
+ for (const l of lines) { offs.push(o); o += l.length + nl.length; }
177
+ const hits = [];
178
+ for (let i = 0; i + want.length <= lines.length; i++) {
179
+ let ok = true;
180
+ for (let k = 0; k < want.length && ok; k++) ok = cmp(lines[i + k], want[k]);
181
+ if (!ok) continue;
182
+ const last = i + want.length - 1;
183
+ let end = offs[last] + lines[last].length;
184
+ if (endsWithNl && last < lines.length - 1) end += nl.length;
185
+ hits.push({ start: offs[i], end, line: i + 1 });
186
+ }
187
+ return hits;
188
+ }
189
+
190
+ const numbered = (text, from, count) => text.replace(/\r\n/g, "\n").split("\n").slice(from - 1, from - 1 + count).map((l, i) => `${from + i}\t${l}`).join("\n");
191
+
192
+ // A useful message when old_string is not in the file: where the closest text is, and what it really says.
193
+ function notFoundHelp(text, oldS) {
194
+ const wantLines = oldS.replace(/\r\n/g, "\n").split("\n");
195
+ const indentHits = findLooseLines(text, oldS, (a, b) => a.trim() === b.trim());
196
+ if (indentHits.length) {
197
+ const h = indentHits[0];
198
+ return `old_string was not found exactly, but the same lines with different indentation are at line ${h.line}. Copy the exact text (from the tab after the line number) and try again:\n${numbered(text, h.line, Math.min(wantLines.length, 30))}`;
199
+ }
200
+ const first = wantLines.find((l) => l.trim())?.trim();
201
+ if (first) {
202
+ const lines = text.replace(/\r\n/g, "\n").split("\n");
203
+ const at = lines.findIndex((l) => l.includes(first));
204
+ if (at >= 0) return `old_string was not found. Its first line matches line ${at + 1}, but the lines after it differ. The file there says:\n${numbered(text, at + 1, Math.min(Math.max(wantLines.length + 2, 5), 30))}\nCopy the exact text and try again.`;
205
+ }
206
+ return "old_string was not found in the file. The file may have changed since you last read it: read it again and copy the exact text, including whitespace.";
207
+ }
208
+
75
209
  // ---- diff for display ------------------------------------------------------
76
210
 
77
211
  function lineDiff(oldText, newText, startLine) {
@@ -104,16 +238,28 @@ export const TOOLS = [
104
238
  },
105
239
  {
106
240
  name: "write_file", kind: "edit",
107
- description: "Create a file or completely replace its contents. Prefer edit_file for changing existing files.",
108
- parameters: { type: "object", properties: { path: { type: "string" }, content: { type: "string" } }, required: ["path", "content"] },
241
+ description: "Create a file or completely replace its contents. Prefer edit_file for changing existing files. For a large file (more than about 300 lines), write it in parts: the first part normally, then each further part with append=true.",
242
+ parameters: { type: "object", properties: { path: { type: "string" }, content: { type: "string" }, append: { type: "boolean", description: "Add content to the end of the file instead of replacing it" } }, required: ["path", "content"] },
109
243
  paths: (a) => [a.path],
110
244
  run(a, { cwd }) {
111
245
  const abs = resolveIn(cwd, a.path);
112
246
  const existed = fs.existsSync(abs);
247
+ const content = String(a.content ?? "");
113
248
  fs.mkdirSync(path.dirname(abs), { recursive: true });
114
- fs.writeFileSync(abs, a.content ?? "");
115
- const n = String(a.content ?? "").split("\n").length;
116
- return { content: `${existed ? "Overwrote" : "Created"} ${relOf(cwd, abs)} (${n} lines)`, display: { title: `${existed ? "Overwrite" : "Create"} ${relOf(cwd, abs)}`, diff: String(a.content ?? "").split("\n").slice(0, 40).map((s, i) => ({ t: "+", n: i + 1, s })), lines: n > 40 ? [`… ${n - 40} more lines`] : [] } };
249
+ let firstLine = 1;
250
+ if (a.append && existed) {
251
+ const prev = fs.readFileSync(abs, "utf8");
252
+ firstLine = prev.split("\n").length; // the appended text starts on the file's last (possibly empty) line
253
+ fs.appendFileSync(abs, content);
254
+ } else fs.writeFileSync(abs, content);
255
+ const n = content.split("\n").length;
256
+ const rel = relOf(cwd, abs);
257
+ const verb = a.append && existed ? "Append to" : existed ? "Overwrite" : "Create";
258
+ const total = a.append && existed ? fs.readFileSync(abs, "utf8").split("\n").length : n;
259
+ return {
260
+ content: a.append && existed ? `Appended ${n} lines to ${rel} (now ${total} lines)` : `${existed ? "Overwrote" : "Created"} ${rel} (${n} lines)`,
261
+ display: { title: `${verb} ${rel}`, diff: content.split("\n").slice(0, 40).map((s, i) => ({ t: "+", n: firstLine + i, s })), lines: n > 40 ? [`… ${n - 40} more lines`] : [] },
262
+ };
117
263
  },
118
264
  },
119
265
  {
@@ -129,14 +275,22 @@ export const TOOLS = [
129
275
  if (!oldS) throw new Error("old_string is empty; use write_file to create or replace a whole file");
130
276
  // Windows files: let the model write \n while the file uses \r\n
131
277
  if (text.includes("\r\n") && !oldS.includes("\r\n")) { oldS = oldS.replace(/\n/g, "\r\n"); newS = newS.replace(/\n/g, "\r\n"); }
132
- const count = text.split(oldS).length - 1;
133
- if (count === 0) throw new Error("old_string was not found in the file. Re-read the file and copy the exact text, including whitespace.");
278
+ let count = text.split(oldS).length - 1;
279
+ let note = "";
280
+ if (count === 0) {
281
+ // Same lines apart from trailing spaces: safe to apply, using the file's real text.
282
+ const loose = findLooseLines(text, oldS);
283
+ if (loose.length !== 1) throw new Error(loose.length > 1 ? `old_string matches ${loose.length} places (ignoring trailing spaces); add more surrounding lines to make it unique` : notFoundHelp(text, oldS));
284
+ oldS = text.slice(loose[0].start, loose[0].end);
285
+ count = 1;
286
+ note = " (matched ignoring trailing spaces)";
287
+ }
134
288
  if (count > 1 && !a.replace_all) throw new Error(`old_string appears ${count} times; add more surrounding context to make it unique, or set replace_all`);
135
289
  const startLine = text.slice(0, text.indexOf(oldS)).split("\n").length;
136
290
  text = a.replace_all ? text.split(oldS).join(newS) : text.replace(oldS, () => newS);
137
291
  fs.writeFileSync(abs, text);
138
292
  const norm = (s) => s.replace(/\r\n/g, "\n");
139
- return { content: `Edited ${relOf(cwd, abs)} (${a.replace_all ? count : 1} replacement${count > 1 && a.replace_all ? "s" : ""})`, display: { title: `Edit ${relOf(cwd, abs)}`, diff: lineDiff(norm(oldS), norm(newS), startLine).slice(0, 60) } };
293
+ return { content: `Edited ${relOf(cwd, abs)} (${a.replace_all ? count : 1} replacement${count > 1 && a.replace_all ? "s" : ""})${note}`, display: { title: `Edit ${relOf(cwd, abs)}`, diff: lineDiff(norm(oldS), norm(newS), startLine).slice(0, 60) } };
140
294
  },
141
295
  },
142
296
  {
@@ -188,17 +342,53 @@ export const TOOLS = [
188
342
  },
189
343
  {
190
344
  name: "bash", kind: "bash",
191
- description: "Run a shell command in the project root and return its combined stdout/stderr and exit code. Use for tests, builds, git, installing packages. Not for reading or editing files (use the file tools).",
192
- parameters: { type: "object", properties: { command: { type: "string" }, timeout_ms: { type: "integer", description: "Default 120000, max 600000" } }, required: ["command"] },
345
+ description: "Run a shell command in the project root and return its combined stdout/stderr and exit code. Use for tests, builds, git, installing packages. Not for reading or editing files (use the file tools). Anything that keeps running (dev servers, `npm run dev`, `npx serve`, `python -m http.server`, watchers) MUST use background=true, otherwise it blocks until the timeout.",
346
+ parameters: { type: "object", properties: { command: { type: "string" }, timeout_ms: { type: "integer", description: "Default 120000, max 600000" }, background: { type: "boolean", description: "Start it and return after a few seconds with its first output; it keeps running. Check on it or stop it with the job tool." } }, required: ["command"] },
193
347
  paths: () => [],
194
- async run(a, { cwd, signal }) {
348
+ async run(a, { cwd, signal, onOutput }) {
349
+ const cmd = String(a.command ?? "");
350
+ const title = `Bash ${cmd.length > 80 ? cmd.slice(0, 80) + "…" : cmd}`;
351
+ const shorten = (lines) => (lines.length > 12 ? [...lines.slice(0, 6), `… ${lines.length - 10} more lines`, ...lines.slice(-4)] : lines);
352
+ if (a.background) {
353
+ const job = startJob(cmd, cwd);
354
+ // give it a moment to print its address or fail fast (port in use, missing command)
355
+ const waitMs = 3000;
356
+ await new Promise((res) => {
357
+ const t0 = Date.now();
358
+ const tick = setInterval(() => { if (!jobRunning(job) || Date.now() - t0 >= waitMs || signal?.aborted) { clearInterval(tick); res(); } }, 100);
359
+ });
360
+ const out = job.out.trim();
361
+ const head = jobRunning(job)
362
+ ? `Started in the background as job ${job.id} (pid ${job.pid}). It keeps running; use the job tool with id ${job.id} to see new output or stop it. Warden stops it when Warden exits.`
363
+ : `Job ${job.id} exited right away (${job.exit}).`;
364
+ return { content: clip(`${head}\nOutput so far:\n${out || "(none yet)"}`), display: { title: `${title} ${jobRunning(job) ? "(background)" : ""}`.trim(), lines: [...shorten(out ? out.split("\n") : []), jobRunning(job) ? `[running in the background as job ${job.id}]` : `[exited: ${job.exit}]`] }, isError: !jobRunning(job) && job.exit !== 0 };
365
+ }
195
366
  const timeoutMs = Math.min(Math.max(a.timeout_ms || 120_000, 1000), 600_000);
196
- const r = await runShell(String(a.command), { cwd, timeoutMs, signal });
197
- const status = r.killed === "timeout" ? `timed out after ${timeoutMs} ms` : r.killed === "interrupted" ? "interrupted by the user" : `exit code ${r.code}`;
367
+ const r = await runShell(cmd, { cwd, timeoutMs, signal, onOutput });
368
+ let status = r.killed === "timeout" ? `timed out after ${Math.round(timeoutMs / 1000)}s and was stopped` : r.killed === "interrupted" ? "interrupted by the user" : `exit code ${r.code}`;
369
+ if (r.killed === "timeout") status += ". If this is a server or watcher, run it again with background=true";
370
+ if (r.lingered) status += ". Note: it left a process running in the background that Warden does not track; next time use background=true for long-running commands";
198
371
  const out = r.out.trim();
199
- const lines = out ? out.split("\n") : [];
200
- const shown = lines.length > 12 ? [...lines.slice(0, 6), `… ${lines.length - 10} more lines`, ...lines.slice(-4)] : lines;
201
- return { content: clip(`${out || "(no output)"}\n[${status}]`), display: { title: `Bash ${a.command.length > 80 ? a.command.slice(0, 80) + "…" : a.command}`, lines: [...shown, `[${status}]`] }, isError: r.code !== 0 };
372
+ return { content: clip(`${out || "(no output)"}\n[${status}]`), display: { title, lines: [...shorten(out ? out.split("\n") : []), `[${status}]`] }, isError: r.code !== 0 || !!r.killed };
373
+ },
374
+ },
375
+ {
376
+ name: "job", kind: "read",
377
+ description: "Check on commands started with bash background=true. With an id: its status and latest output; add stop=true to stop it. Without an id: list all jobs.",
378
+ parameters: { type: "object", properties: { id: { type: "integer" }, stop: { type: "boolean" } } },
379
+ paths: () => [],
380
+ run(a) {
381
+ if (a.id == null) {
382
+ const all = listJobs();
383
+ return { content: all.length ? all.map(describeJob).join("\n") : "No background jobs.", display: { title: "Jobs", lines: [`${all.length} job${all.length === 1 ? "" : "s"}`] } };
384
+ }
385
+ const j = JOBS.get(Number(a.id));
386
+ if (!j) throw new Error(`no job ${a.id}. Jobs: ${listJobs().map((x) => x.id).join(", ") || "none"}`);
387
+ if (a.stop) {
388
+ const was = stopJob(j);
389
+ return { content: was ? `Stopped job ${j.id}.` : `Job ${j.id} had already exited (${j.exit}).`, display: { title: `Stop job ${j.id}`, lines: [j.command] } };
390
+ }
391
+ return { content: `${describeJob(j)}\nLatest output:\n${tail(j.out.trim()) || "(none)"}`, display: { title: `Job ${j.id}`, lines: [describeJob(j)] } };
202
392
  },
203
393
  },
204
394
  ];