warden-agent 0.4.0 → 0.5.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.
@@ -8,7 +8,7 @@
8
8
  // { role: "assistant", content: string, toolCalls?: [{ id, name, args }] }
9
9
  // { role: "tool", toolCallId, name, content: string }
10
10
 
11
- import { CATALOG } from "./catalog.mjs";
11
+ import { CATALOG, looksLikeImageModel } from "./catalog.mjs";
12
12
  import { savedKey } from "./credentials.mjs";
13
13
  import { textToolsPrompt, toTextProtocol, parseTextToolCalls, ToolTagFilter } from "./texttools.mjs";
14
14
 
@@ -69,8 +69,12 @@ export function toOpenAI(system, messages) {
69
69
  export function toAnthropic(messages) {
70
70
  const out = [];
71
71
  for (const m of messages) {
72
- if (m.role === "user") out.push({ role: "user", content: [{ type: "text", text: m.content }] });
73
- else if (m.role === "assistant") {
72
+ if (m.role === "user") {
73
+ // a message typed while tools ran (or after a failed request) follows another user turn: merge them
74
+ const last = out.at(-1);
75
+ if (last?.role === "user") last.content.push({ type: "text", text: m.content });
76
+ else out.push({ role: "user", content: [{ type: "text", text: m.content }] });
77
+ } else if (m.role === "assistant") {
74
78
  const content = [];
75
79
  if (m.content) content.push({ type: "text", text: m.content });
76
80
  for (const c of m.toolCalls || []) content.push({ type: "tool_use", id: c.id, name: c.name, input: c.args ?? {} });
@@ -96,9 +100,74 @@ const sleep = (ms, signal) => new Promise((res, rej) => {
96
100
  signal?.addEventListener("abort", () => { clearTimeout(t); rej(new DOMException("aborted", "AbortError")); }, { once: true });
97
101
  });
98
102
 
99
- async function postWithRetry(url, headers, body, { signal, onRetry, retries = 4 }) {
103
+ // ---- timeouts ------------------------------------------------------------------
104
+ // A model request must never hang forever. Three limits, all in seconds and changeable in settings:
105
+ // requestTimeoutSec no answer at all (not even headers) after this long: give up on the attempt (retried once)
106
+ // idleTimeoutSec a streaming reply goes completely silent this long: stop
107
+ // stallTimeoutSec only keep-alive pings, no text / reasoning / tool calls, this long: stop
108
+ export const TIMEOUT_DEFAULTS = { requestTimeoutSec: 180, idleTimeoutSec: 120, stallTimeoutSec: 300 };
109
+
110
+ export class ModelTimeoutError extends Error {
111
+ constructor(message) { super(message); this.name = "ModelTimeoutError"; this.timeout = true; }
112
+ }
113
+
114
+ export function timeoutsFrom(cfg = {}) {
115
+ const sec = (k) => { const v = Number(cfg?.[k]); return (Number.isFinite(v) && v > 0 ? v : TIMEOUT_DEFAULTS[k]) * 1000; };
116
+ return { request: sec("requestTimeoutSec"), idle: sec("idleTimeoutSec"), stall: sec("stallTimeoutSec") };
117
+ }
118
+ const secs = (ms) => (ms % 1000 ? (ms / 1000).toFixed(1) : String(ms / 1000));
119
+
120
+ // Reads a fetch body, calling onLine for each line, and stops with ModelTimeoutError when the stream goes quiet.
121
+ // progress() is called by the parser when real content arrives (text, reasoning or tool calls).
122
+ async function readStream(r, { signal, idleMs, stallMs, onLine, label }) {
123
+ const reader = r.body.getReader();
124
+ const dec = new TextDecoder();
125
+ let buf = "", fired = null;
126
+ const stop = (why) => { if (!fired) { fired = why; reader.cancel().catch(() => {}); } };
127
+ let idle = setTimeout(() => stop("idle"), idleMs);
128
+ let stall = setTimeout(() => stop("stall"), stallMs);
129
+ const progress = () => { clearTimeout(stall); stall = setTimeout(() => stop("stall"), stallMs); };
130
+ try {
131
+ for (;;) {
132
+ const { done, value } = await reader.read();
133
+ if (done) break;
134
+ clearTimeout(idle); idle = setTimeout(() => stop("idle"), idleMs);
135
+ buf += dec.decode(value, { stream: true });
136
+ let i;
137
+ while ((i = buf.indexOf("\n")) >= 0) {
138
+ const line = buf.slice(0, i).trim(); buf = buf.slice(i + 1);
139
+ onLine(line, progress);
140
+ }
141
+ }
142
+ if (buf.trim()) onLine(buf.trim(), progress);
143
+ } catch (e) {
144
+ if (!fired || signal?.aborted) { reader.cancel().catch(() => {}); throw e; }
145
+ } finally {
146
+ clearTimeout(idle); clearTimeout(stall);
147
+ }
148
+ if (fired === "idle") throw new ModelTimeoutError(`${label} stopped sending anything for ${secs(idleMs)}s, so Warden stopped waiting. Send your message again, or switch models with /model.`);
149
+ if (fired === "stall") throw new ModelTimeoutError(`${label} kept the connection open for ${secs(stallMs)}s without sending any reply (it may be overloaded), so Warden stopped waiting. Try again, or switch models with /model.`);
150
+ }
151
+
152
+ export async function postWithRetry(url, headers, body, { signal, onRetry, retries = 4, timeoutMs = TIMEOUT_DEFAULTS.requestTimeoutSec * 1000, label = "The model" }) {
153
+ let timeoutRetries = 1;
100
154
  for (let attempt = 0; ; attempt++) {
101
- const r = await fetch(url, { method: "POST", headers: { "content-type": "application/json", ...headers }, body: JSON.stringify(body), signal });
155
+ // each attempt gets its own deadline for the response to start; the user's interrupt still applies throughout
156
+ const deadline = new AbortController();
157
+ const timer = setTimeout(() => deadline.abort(), timeoutMs);
158
+ let r;
159
+ try {
160
+ r = await fetch(url, { method: "POST", headers: { "content-type": "application/json", ...headers }, body: JSON.stringify(body), signal: signal ? AbortSignal.any([signal, deadline.signal]) : deadline.signal });
161
+ } catch (e) {
162
+ if (signal?.aborted || !deadline.signal.aborted) throw e;
163
+ if (timeoutRetries-- > 0) {
164
+ onRetry?.({ status: "no response", waitMs: 0, attempt: attempt + 1, message: `no response after ${secs(timeoutMs)}s` });
165
+ continue;
166
+ }
167
+ throw new ModelTimeoutError(`${label} did not respond within ${secs(timeoutMs)}s (tried twice). It may be overloaded: try again, or switch models with /model.`);
168
+ } finally {
169
+ clearTimeout(timer);
170
+ }
102
171
  if (r.ok) return r;
103
172
  const text = await r.text().catch(() => "");
104
173
  let msg = text, hintedDelay = null;
@@ -116,7 +185,7 @@ async function postWithRetry(url, headers, body, { signal, onRetry, retries = 4
116
185
  const retryable = r.status === 429 || r.status >= 500;
117
186
  if (!retryable || attempt >= retries) throw fail();
118
187
  // A long or daily quota is not worth waiting for: say so now instead of retrying.
119
- if (r.status === 429 && (hintedDelay > 60_000 || (/per ?day|daily|PerDay/i.test(msg) && !hintedDelay))) {
188
+ if (r.status === 429 && (hintedDelay > 60_000 || (/per[ -]?day|daily|PerDay/i.test(msg) && !hintedDelay))) {
120
189
  const e = fail(" [quota used up for now; switch model with /model or try again later]");
121
190
  e.quota = true;
122
191
  throw e;
@@ -132,16 +201,23 @@ async function postWithRetry(url, headers, body, { signal, onRetry, retries = 4
132
201
  /**
133
202
  * One model call. Streams text through onText. Returns { text, toolCalls, usage, stopReason }.
134
203
  */
135
- export async function chat({ spec, system, messages, tools, cfg = {}, signal, onText = () => {}, onRetry, maxOutputTokens = 8192, env = process.env, toolMode = "native" }) {
204
+ export async function chat({ spec, system, messages, tools, cfg = {}, signal, onText = () => {}, onReasoning = () => {}, onToolDelta = () => {}, onRetry, maxOutputTokens = 8192, env = process.env, toolMode = "native", timeouts }) {
136
205
  const { provider, model } = parseModelSpec(spec);
137
206
  const p = resolveProvider(provider, cfg);
138
207
  const key = keyFor(provider, p, env);
139
- const send = (o) => (p.api === "anthropic" ? anthropicChat({ p, key, model, signal, onRetry, maxOutputTokens, ...o }) : openaiChat({ p, key, model, signal, onRetry, maxOutputTokens, ...o }));
208
+ const t = timeoutsFrom(timeouts || cfg);
209
+ const label = `The model (${spec})`;
210
+ const common = { p, key, model, signal, onRetry, maxOutputTokens, t, label, onReasoning, onToolDelta };
211
+ const send = (o) => (p.api === "anthropic" ? anthropicChat({ ...common, ...o }) : openaiChat({ ...common, ...o }));
140
212
 
141
213
  if (toolMode === "text" && tools?.length) {
142
214
  // the model writes <tool_call> blocks; hide them from the stream and parse them afterwards
143
215
  const filter = new ToolTagFilter(onText);
144
- const res = await send({ system: system + textToolsPrompt(tools), messages: toTextProtocol(messages), tools: null, onText: (d) => filter.write(d) });
216
+ let hidden = "";
217
+ const res = await send({ system: system + textToolsPrompt(tools), messages: toTextProtocol(messages), tools: null, onText: (d) => {
218
+ filter.write(d);
219
+ if (filter.inside) { hidden += d; try { onToolDelta(hidden.match(/"name"s*:s*"([w-]+)"/)?.[1] || "", hidden); } catch {} } else hidden = "";
220
+ } });
145
221
  filter.end();
146
222
  const parsed = parseTextToolCalls(res.text);
147
223
  return { ...res, text: parsed.text, toolCalls: parsed.toolCalls };
@@ -153,53 +229,51 @@ export async function chat({ spec, system, messages, tools, cfg = {}, signal, on
153
229
  return send({ system, messages, tools, onText });
154
230
  }
155
231
 
156
- async function openaiChat({ p, key, model, system, messages, tools, signal, onText, onRetry, maxOutputTokens }) {
232
+ async function openaiChat({ p, key, model, system, messages, tools, signal, onText, onReasoning, onToolDelta, onRetry, maxOutputTokens, t, label }) {
157
233
  const body = { model, messages: toOpenAI(system, messages), stream: true, [p.maxTokensParam || "max_tokens"]: maxOutputTokens };
158
234
  if (tools?.length) body.tools = toolsOpenAI(tools);
159
235
  if (p.streamUsage !== false && !p.local) body.stream_options = { include_usage: true };
160
236
  const headers = key ? { authorization: `Bearer ${key}` } : {};
237
+ const post = () => postWithRetry(`${p.baseUrl}/chat/completions`, headers, body, { signal, onRetry, timeoutMs: t.request, label });
161
238
  let r;
162
239
  try {
163
- r = await postWithRetry(`${p.baseUrl}/chat/completions`, headers, body, { signal, onRetry });
240
+ r = await post();
164
241
  } catch (e) {
165
242
  // some compatible servers reject stream_options; retry once without it
166
243
  if (e.status === 400 && body.stream_options && /stream_options|include_usage|unknown/i.test(e.message)) {
167
244
  delete body.stream_options;
168
- r = await postWithRetry(`${p.baseUrl}/chat/completions`, headers, body, { signal, onRetry });
245
+ r = await post();
169
246
  } else throw e;
170
247
  }
171
248
 
172
- let text = "", stopReason = null, usage = null, buf = "";
249
+ let text = "", stopReason = null, usage = null;
173
250
  const calls = new Map(); // index -> {id, name, args}
174
- const dec = new TextDecoder();
175
- const handle = (data) => {
251
+ const handle = (data, progress) => {
176
252
  if (data === "[DONE]") return;
177
253
  let j; try { j = JSON.parse(data); } catch { return; }
178
- if (j.error) throw new Error(j.error.message || JSON.stringify(j.error));
254
+ if (j.error) { const e = new Error(j.error.message || JSON.stringify(j.error)); e.status = Number(j.error.code) || undefined; throw e; }
179
255
  if (j.usage) usage = { input: j.usage.prompt_tokens ?? 0, output: j.usage.completion_tokens ?? 0 };
180
256
  const ch = j.choices?.[0];
181
257
  if (!ch) return;
182
258
  const d = ch.delta || ch.message || {};
183
- if (typeof d.content === "string" && d.content) { text += d.content; onText(d.content); }
259
+ // reasoning models stream their thinking separately (field name differs by server); show activity, keep it out of the reply
260
+ const thought = d.reasoning_content ?? d.reasoning ?? d.thinking;
261
+ if (typeof thought === "string" && thought) { progress(); onReasoning(thought); }
262
+ if (typeof d.content === "string" && d.content) { progress(); text += d.content; onText(d.content); }
184
263
  for (const tc of d.tool_calls || []) {
264
+ progress();
185
265
  const idx = tc.index ?? calls.size;
186
266
  const cur = calls.get(idx) || { id: "", name: "", args: "" };
187
267
  if (tc.id) cur.id = tc.id;
188
268
  if (tc.function?.name) cur.name += tc.function.name;
189
269
  if (tc.function?.arguments) cur.args += typeof tc.function.arguments === "string" ? tc.function.arguments : JSON.stringify(tc.function.arguments);
190
270
  calls.set(idx, cur);
271
+ try { onToolDelta(cur.name, cur.args); } catch {}
191
272
  }
192
273
  if (ch.finish_reason) stopReason = ch.finish_reason;
193
274
  };
194
- for await (const chunk of r.body) {
195
- buf += dec.decode(chunk, { stream: true });
196
- let i;
197
- while ((i = buf.indexOf("\n")) >= 0) {
198
- const line = buf.slice(0, i).trim(); buf = buf.slice(i + 1);
199
- if (line.startsWith("data:")) handle(line.slice(5).trim());
200
- }
201
- }
202
- if (buf.trim().startsWith("data:")) handle(buf.trim().slice(5).trim());
275
+ // lines starting with ":" are keep-alive comments (OpenRouter sends them while a model is queued): not progress
276
+ await readStream(r, { signal, idleMs: t.idle, stallMs: t.stall, label, onLine: (line, progress) => { if (line.startsWith("data:")) handle(line.slice(5).trim(), progress); } });
203
277
 
204
278
  const toolCalls = [...calls.entries()].sort((a, b) => a[0] - b[0]).map(([i, c], n) => {
205
279
  let args = {};
@@ -209,10 +283,11 @@ async function openaiChat({ p, key, model, system, messages, tools, signal, onTe
209
283
  return { text, toolCalls, usage, stopReason };
210
284
  }
211
285
 
212
- async function anthropicChat({ p, key, model, system, messages, tools, signal, onText, onRetry, maxOutputTokens }) {
286
+ async function anthropicChat({ p, key, model, system, messages, tools, signal, onText, onRetry, maxOutputTokens, t, label }) {
213
287
  const body = { model, system, max_tokens: maxOutputTokens, messages: toAnthropic(messages) };
214
288
  if (tools?.length) body.tools = toolsAnthropic(tools);
215
- const r = await postWithRetry(`${p.baseUrl}/messages`, { "x-api-key": key, "anthropic-version": "2023-06-01" }, body, { signal, onRetry });
289
+ // not streamed: the whole reply arrives at once, so allow the request time plus the stall time for it
290
+ const r = await postWithRetry(`${p.baseUrl}/messages`, { "x-api-key": key, "anthropic-version": "2023-06-01" }, body, { signal, onRetry, timeoutMs: t.request + t.stall, label });
216
291
  const j = await r.json();
217
292
  let text = "";
218
293
  const toolCalls = [];
@@ -224,7 +299,7 @@ async function anthropicChat({ p, key, model, system, messages, tools, signal, o
224
299
  return { text, toolCalls, usage: j.usage ? { input: j.usage.input_tokens ?? 0, output: j.usage.output_tokens ?? 0 } : null, stopReason: j.stop_reason };
225
300
  }
226
301
 
227
- // Models a provider offers: [{ id, ctx, free, tools }] (null = unknown). Uses the source's public list when it has one.
302
+ // Models a provider offers: [{ id, ctx, free, tools, image }] (null = unknown). Uses the source's public list when it has one.
228
303
  export async function listModels(name, cfg = {}, env = process.env) {
229
304
  const p = resolveProvider(name, cfg);
230
305
  let key = null;
@@ -240,5 +315,5 @@ export async function listModels(name, cfg = {}, env = process.env) {
240
315
  const j = await fetchJson(`${p.baseUrl}/models`);
241
316
  list = (j.data || j.models || []).map((m) => ({ id: String(m.id || m.name || "").replace(/^models\//, ""), ctx: m.context_length ?? m.context_window ?? null, free: null, tools: null }));
242
317
  } else throw new Error(`listing models is not supported for ${name}; type the model id instead`);
243
- return list.filter((m) => m.id).sort((a, b) => a.id.localeCompare(b.id));
318
+ return list.filter((m) => m.id).map((m) => ({ ...m, image: m.image ?? looksLikeImageModel(m.id) })).sort((a, b) => a.id.localeCompare(b.id));
244
319
  }
@@ -54,10 +54,16 @@ export function parseTextToolCalls(reply, idPrefix = "tc") {
54
54
  toolCalls.push(name ? { id: `${idPrefix}_${Date.now().toString(36)}_${n++}`, name: String(name), args: typeof args === "string" ? safeJson(args) : args }
55
55
  : { id: `${idPrefix}_${Date.now().toString(36)}_${n++}`, name: "__invalid__", args: { __invalid_json: body } });
56
56
  }
57
- const text = reply.replace(re, "").replace(/<tool_call>[\s\S]*$/, "").replace(/\n{3,}/g, "\n\n").trim();
57
+ // a <tool_call> that never closed was cut off (usually by the output limit): report it instead of dropping it silently
58
+ const rest = reply.replace(re, "");
59
+ const open = rest.indexOf("<tool_call>");
60
+ if (open >= 0) toolCalls.push({ id: `${idPrefix}_${Date.now().toString(36)}_${n++}`, name: guessName(rest.slice(open)), args: { __invalid_json: rest.slice(open + 11, open + 211), __truncated: true } });
61
+ const text = rest.replace(/<tool_call>[\s\S]*$/, "").replace(/\n{3,}/g, "\n\n").trim();
58
62
  return { text, toolCalls };
59
63
  }
60
64
 
65
+ const guessName = (s) => s.match(/"name"\s*:\s*"([\w-]+)"/)?.[1] || "__invalid__";
66
+
61
67
  function safeJson(s) { try { return JSON.parse(s); } catch { return { __invalid_json: s }; } }
62
68
 
63
69
  // Streaming filter: hides <tool_call>…</tool_call> from what the user sees while the reply streams in.
@@ -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
  ];