s-app-scoder-agent 0.4.0 → 0.6.0

package/dist/index.js

@@ -8,6 +8,7 @@ import { listSessions, resolveSessionId, pruneSessions } from "./session.js";
 import { JsonlLogger } from "./logger.js";
 import { collectUsage, formatCostReport } from "./cost.js";
 import { getVersion as getPackageVersion } from "./version.js";
+import { formatSlashHelp, parseSlashCommand } from "./tui/commands.js";
 import * as ui from "./ui.js";
 // Single source of truth: read version from package.json (see src/version.ts).
 const VERSION = getPackageVersion();
@@ -16,11 +17,16 @@ const HELP = `scoder — autonomous coding agent CLI
 USAGE
   scoder [options] "<task>"        Run a task autonomously until the build passes
   scoder                           Start interactive session (chat + tools)
+  scoder tui [task]                Full-screen terminal UI (chat pane, live tool feed)
+  scoder init                      First-run wizard: writes .scoderrc.json + tests the connection
   scoder list                      List saved sessions for this directory
   scoder resume <id|last> [task]   Resume a saved session (optionally with a follow-up task)
   scoder logs [id|last] [filter]   Print a session's JSONL log (requires --log-file runs)
   scoder cost [--session <id>] [--last <n>]
                                     Token usage & estimated cost from JSONL logs
+  scoder serve [--port <n>] [--host <addr>]
+                                    Run as an HTTP server: POST tasks, stream
+                                    progress via Server-Sent Events (see below)
   scoder --version | --help
 
 OPTIONS
@@ -120,6 +126,17 @@ function parseArgs(argv) {
                 args.provider = p;
                 break;
             }
+            case "--port": {
+                const n = Number(next());
+                if (!Number.isInteger(n) || n < 0 || n > 65535) {
+                    throw new Error(`Invalid --port value (expected 0-65535): ${n}`);
+                }
+                args.servePort = n;
+                break;
+            }
+            case "--host":
+                args.serveHost = next();
+                break;
             case "-h":
             case "--help":
                 args.help = true;
@@ -155,6 +172,19 @@ function parseArgs(argv) {
         args.subcommand = "cost";
         args.task = null;
     }
+    else if (rest[0] === "serve") {
+        args.subcommand = "serve";
+        args.task = null;
+    }
+    else if (rest[0] === "tui") {
+        // scoder tui [initial-task] — full-screen Ink interface
+        args.subcommand = "tui";
+        args.task = rest.length > 1 ? rest.slice(1).join(" ") : null;
+    }
+    else if (rest[0] === "init") {
+        args.subcommand = "init";
+        args.task = null;
+    }
     return args;
 }
 async function runOnce(cfg, task) {
@@ -175,13 +205,79 @@ async function runOnce(cfg, task) {
         return 2;
     }
 }
+/**
+ * `scoder init` — first-run wizard: asks for the essentials, writes
+ * .scoderrc.json, then offers a live connection test against the provider.
+ */
+export async function runInit() {
+    const { existsSync, writeFileSync } = await import("node:fs");
+    const rcPath = resolve(process.cwd(), ".scoderrc.json");
+    ui.banner("scoder init — configure this project", [
+        ["file", rcPath],
+        ["note", "answers are saved to .scoderrc.json (env vars still override)"],
+    ]);
+    if (existsSync(rcPath)) {
+        const rl0 = createInterface({ input: process.stdin, output: process.stdout });
+        const overwrite = await new Promise((res) => rl0.question(`.scoderrc.json already exists — overwrite? [y/N] `, res));
+        rl0.close();
+        if (!/^y(es)?$/i.test(overwrite.trim())) {
+            ui.info("kept the existing .scoderrc.json");
+            return;
+        }
+    }
+    const rl = createInterface({ input: process.stdin, output: process.stdout });
+    const ask = (q, def) => new Promise((res) => rl.question(`${q}${def ? ` [${def}]` : ""}: `, (a) => res(a.trim() || def)));
+    const baseUrl = await ask("API base URL (OpenAI-compatible)", "https://api.openai.com/v1");
+    const apiKey = await ask("API key (SCODER_API_KEY/OPENAI_API_KEY also work at runtime)", "");
+    const model = await ask("Model", "gpt-4o-mini");
+    const buildCmd = await ask("Build command (empty = auto-detect)", "");
+    const permission = (await ask("Permission mode (auto | ask | readonly)", "auto")).toLowerCase();
+    rl.close();
+    const provider = /api\.anthropic\.com/.test(baseUrl) || /^claude-/i.test(model) ? "anthropic" : "openai";
+    const rc = {
+        model,
+        baseUrl,
+        provider,
+        ...(buildCmd ? { buildCmd } : {}),
+        permissions: { mode: ["auto", "ask", "readonly"].includes(permission) ? permission : "auto" },
+    };
+    writeFileSync(rcPath, JSON.stringify(rc, null, 2) + "\n");
+    ui.success(`wrote ${rcPath} (provider: ${provider})`);
+    const rl2 = createInterface({ input: process.stdin, output: process.stdout });
+    const doTest = await new Promise((res) => rl2.question("Test the connection now? [Y/n] ", res));
+    rl2.close();
+    if (!/^y(es)?$/i.test(doTest.trim()) && doTest.trim() !== "") {
+        ui.info("skipped connection test");
+        return;
+    }
+    if (!apiKey) {
+        ui.warn("no API key provided — set SCODER_API_KEY/OPENAI_API_KEY before running tasks");
+        return;
+    }
+    ui.info(`connecting to ${baseUrl} (${provider}) …`);
+    try {
+        const { LlmClient } = await import("./llm.js");
+        const { AnthropicClient } = await import("./provider-anthropic.js");
+        const client = provider === "anthropic"
+            ? new AnthropicClient({ baseUrl, apiKey, model, maxTokens: 16, temperature: 0 })
+            : new LlmClient({ baseUrl, apiKey, model, maxTokens: 16, temperature: 0 });
+        const res = await client.chat([{ role: "user", content: "Reply with exactly: OK" }], []);
+        const reply = (res.message.content ?? "").trim();
+        ui.success(`connection OK — model replied: ${JSON.stringify(reply)}`);
+    }
+    catch (err) {
+        ui.error(`connection test failed: ${err.message}`);
+        process.exitCode = 2;
+    }
+}
 async function repl(cfg) {
     ui.header(`scoder interactive — model: ${cfg.model}`);
     ui.info('Type a task and press Enter. "exit" or Ctrl+D to quit.');
     const rl = createInterface({ input: process.stdin, output: process.stdout, prompt: "you> " });
     // One shared session for the whole REPL conversation (plan P0.5 §4):
     // every input is a follow-up turn, context carries over, saved continuously.
-    const agent = new Agent(cfg);
+    // /clear swaps in a fresh Agent (the /clear branch reassigns this).
+    let agent = new Agent(cfg);
     process.on("SIGINT", () => {
         ui.warn("\nSIGINT — aborting current task...");
         agent.abort();
@@ -194,6 +290,37 @@ async function repl(cfg) {
             continue;
         if (input === "exit" || input === "quit")
             break;
+        // Slash commands — handled by the UI, never sent to the LLM.
+        const slash = parseSlashCommand(input);
+        if (slash) {
+            if (slash.cmd === "/exit" || slash.cmd === "/quit")
+                break;
+            if (slash.cmd === "/help") {
+                console.log(formatSlashHelp("scoder"));
+                continue;
+            }
+            if (slash.cmd === "/clear") {
+                agent.abort();
+                agent = new Agent(cfg);
+                first = true;
+                ui.info("conversation cleared — context reset");
+                continue;
+            }
+            if (slash.cmd === "/cost") {
+                const u = agent.getUsage();
+                console.log(u.calls > 0
+                    ? `session usage: ${u.calls} LLM calls · tokens in ${u.inputTokens} / out ${u.outputTokens}` +
+                        (u.cachedTokens > 0 ? ` (+${u.cachedTokens} cached)` : "")
+                    : "no LLM calls yet in this session");
+                continue;
+            }
+            if (slash.cmd === "/model") {
+                console.log(`model: ${cfg.model} · provider: ${cfg.provider} · build: ${cfg.buildCmd ?? "auto-detect"}`);
+                continue;
+            }
+            ui.error(`unknown command ${slash.cmd} — try /help`);
+            continue;
+        }
         try {
             const result = first ? await agent.run(input) : await agent.runTurn(input);
             first = false;
@@ -238,6 +365,10 @@ async function main() {
         logFile: args.logFile,
     });
     // Subcommands
+    if (args.subcommand === "init") {
+        await runInit();
+        return;
+    }
     if (args.subcommand === "list") {
         const sessions = listSessions(cfg.workdir);
         if (sessions.length === 0) {
@@ -302,6 +433,45 @@ async function main() {
         console.log(formatCostReport(sessionCosts));
         return;
     }
+    if (args.subcommand === "tui") {
+        if (!process.stdin.isTTY || !process.stdout.isTTY) {
+            ui.warn("TUI requires an interactive terminal (TTY) — falling back to the classic REPL.");
+            await repl(cfg);
+            return;
+        }
+        if (!cfg.apiKey) {
+            ui.warn("No API key configured — tasks will fail until SCODER_API_KEY (or OPENAI_API_KEY) is set.");
+        }
+        const { runTui } = await import("./tui/app.js");
+        await runTui(cfg, args.task);
+        return;
+    }
+    if (args.subcommand === "serve") {
+        const { startServer } = await import("./server.js");
+        if (!cfg.apiKey) {
+            ui.warn("No API key configured — runs will fail until SCODER_API_KEY (or OPENAI_API_KEY) is set.");
+        }
+        const srv = await startServer(cfg, { host: args.serveHost, port: args.servePort });
+        const token = process.env.SCODER_SERVER_TOKEN ? " · token auth" : "";
+        ui.banner(`scoder serve @ http://${args.serveHost ?? "127.0.0.1"}:${srv.port}${token}`, [
+            ["task", `POST /api/runs { "task": "..." } → 202 { id, eventsUrl }`],
+            ["events", `GET /api/runs/<id>/events → SSE stream`],
+            ["list", `GET /api/runs`],
+            ["abort", `POST /api/runs/<id>/abort`],
+            ["workdir", cfg.workdir],
+            ["model", `${cfg.model}  ·  permission ${cfg.permissionMode}`],
+        ]);
+        const shutdown = async () => {
+            ui.info("shutting down server...");
+            await srv.close();
+            process.exit(0);
+        };
+        process.on("SIGINT", () => {
+            ui.warn("\nSIGINT — shutting down server, aborting in-flight runs...");
+            void shutdown();
+        });
+        return;
+    }
     if (args.task) {
         const code = await runOnce(cfg, args.task);
         process.exit(code);

package/dist/llm.js

@@ -76,6 +76,29 @@ function parseSSELine(line) {
 // ---------------------------------------------------------------------------
 // LlmClient
 // ---------------------------------------------------------------------------
+/**
+ * Serialize conversation history to the OpenAI wire format. Internal ToolCall
+ * shape is `{id, name, arguments}`; the API expects
+ * `{id, type: "function", function: {name, arguments}}`. Some providers
+ * (Upstage/solar) reject assistant tool_calls in the internal shape with a
+ * misleading "Invalid function name: ''" error — always normalize here.
+ */
+function toWireMessages(messages) {
+    return messages.map((m) => {
+        if (m.role === "assistant" && m.tool_calls) {
+            return {
+                role: m.role,
+                content: m.content,
+                tool_calls: m.tool_calls.map((tc) => ({
+                    id: tc.id,
+                    type: "function",
+                    function: { name: tc.name, arguments: tc.arguments },
+                })),
+            };
+        }
+        return m;
+    });
+}
 export class LlmClient {
     opts;
     streamEnabled;
@@ -92,7 +115,7 @@ export class LlmClient {
         const { signal, cleanup } = combinedSignal(opts.signal, LLM_REQUEST_TIMEOUT_MS);
         const body = JSON.stringify({
             model: this.opts.model,
-            messages,
+            messages: toWireMessages(messages),
             tools: tools.length > 0 ? tools : undefined,
             temperature: this.opts.temperature,
             max_tokens: this.opts.maxTokens,
@@ -153,7 +176,7 @@ export class LlmClient {
         const { signal, cleanup } = combinedSignal(opts.signal, LLM_REQUEST_TIMEOUT_MS);
         const bodyStr = JSON.stringify({
             model: this.opts.model,
-            messages,
+            messages: toWireMessages(messages),
             tools: tools.length > 0 ? tools : undefined,
             temperature: this.opts.temperature,
             max_tokens: this.opts.maxTokens,

package/dist/server.js

@@ -0,0 +1,256 @@
+import { createServer } from "node:http";
+import { randomUUID } from "node:crypto";
+import { existsSync, statSync } from "node:fs";
+import { resolve } from "node:path";
+import process from "node:process";
+import { Agent } from "./agent.js";
+const MAX_BODY_BYTES = 1024 * 1024;
+function readBody(req, maxBytes = MAX_BODY_BYTES) {
+    return new Promise((resolve, reject) => {
+        let body = "";
+        let size = 0;
+        req.on("data", (c) => {
+            size += c.byteLength;
+            if (size > maxBytes) {
+                reject(new Error(`request body too large (>${maxBytes} bytes)`));
+                req.destroy();
+                return;
+            }
+            body += c.toString("utf8");
+        });
+        req.on("end", () => resolve(body));
+        req.on("error", reject);
+    });
+}
+function sendJson(res, status, payload) {
+    res.writeHead(status, { "Content-Type": "application/json; charset=utf-8" });
+    res.end(JSON.stringify(payload));
+}
+function isAuthorized(req, token) {
+    if (!token)
+        return true;
+    const header = req.headers.authorization ?? "";
+    return header === `Bearer ${token}`;
+}
+export function startServer(baseConfig, opts = {}) {
+    const host = opts.host ?? "127.0.0.1";
+    const maxConcurrent = opts.maxConcurrent ?? 4;
+    const token = process.env.SCODER_SERVER_TOKEN || "";
+    /** id -> run record; Map preserves insertion order (= creation order). */
+    const runs = new Map();
+    const publicRun = (r) => ({
+        id: r.id,
+        task: r.task,
+        workdir: r.workdir,
+        status: r.status,
+        createdAt: r.createdAt,
+        finishedAt: r.finishedAt,
+        eventCount: r.events.length,
+        result: r.result,
+        error: r.error,
+        eventsUrl: `/api/runs/${r.id}/events`,
+    });
+    const runningCount = () => [...runs.values()].filter((r) => r.status === "running").length;
+    /** Launch an agent run in the background, wiring events into the record. */
+    const launchRun = (record, cfg, task) => {
+        const agent = new Agent(cfg);
+        record.agent = agent;
+        agent.onEvent = (ev) => {
+            record.events.push(ev);
+            if (ev.type === "finish") {
+                record.status = ev.success ? "success" : record.abortRequested ? "aborted" : "failed";
+                record.finishedAt = new Date().toISOString();
+            }
+            for (const sub of record.subscribers)
+                sub();
+        };
+        agent
+            .run(task)
+            .then((result) => {
+            record.result = result;
+            if (record.status === "running") {
+                // Should not happen (finish event always arrives first), but be safe.
+                record.status = result.success ? "success" : record.abortRequested ? "aborted" : "failed";
+                record.finishedAt = new Date().toISOString();
+            }
+        })
+            .catch((err) => {
+            record.error = err.message;
+            // Synthetic terminal events so SSE clients always see a stream end.
+            record.events.push({ type: "error", message: record.error });
+            record.events.push({ type: "finish", success: false, steps: 0, summary: `run failed: ${record.error}` });
+            record.status = "error";
+            record.finishedAt = new Date().toISOString();
+            for (const sub of record.subscribers)
+                sub();
+        });
+    };
+    const handleEventsSSE = (req, res, record) => {
+        res.writeHead(200, {
+            "Content-Type": "text/event-stream",
+            "Cache-Control": "no-cache",
+            Connection: "keep-alive",
+        });
+        let sent = 0;
+        const heartbeat = setInterval(() => {
+            if (!res.writableEnded)
+                res.write(": ping\n\n");
+        }, 15_000);
+        heartbeat.unref?.();
+        /** Replay buffered events + live ones; ends the stream on a terminal event. */
+        const flush = () => {
+            while (sent < record.events.length) {
+                const ev = record.events[sent++];
+                res.write(`data: ${JSON.stringify(ev)}\n\n`);
+                if (ev.type === "finish" || ev.type === "error") {
+                    res.end();
+                    record.subscribers.delete(flush);
+                    return;
+                }
+            }
+        };
+        record.subscribers.add(flush);
+        flush(); // replays the buffer, then stays live via the subscription
+        req.on("close", () => {
+            record.subscribers.delete(flush);
+            clearInterval(heartbeat);
+        });
+    };
+    const handle = async (req, res) => {
+        const url = new URL(req.url ?? "/", `http://${req.headers.host ?? "localhost"}`);
+        const path = url.pathname;
+        if (!isAuthorized(req, token)) {
+            sendJson(res, 401, { error: "unauthorized (set Authorization: Bearer <SCODER_SERVER_TOKEN>)" });
+            return;
+        }
+        // ── GET /api/health ──
+        if (path === "/api/health" && req.method === "GET") {
+            sendJson(res, 200, { ok: true, running: runningCount(), runs: runs.size });
+            return;
+        }
+        // ── /api/runs ──
+        if (path === "/api/runs") {
+            if (req.method === "GET") {
+                sendJson(res, 200, { runs: [...runs.values()].map(publicRun) });
+                return;
+            }
+            if (req.method === "POST") {
+                if (runningCount() >= maxConcurrent) {
+                    sendJson(res, 429, { error: `too many concurrent runs (max ${maxConcurrent}) — retry later` });
+                    return;
+                }
+                let body;
+                try {
+                    body = JSON.parse(await readBody(req));
+                }
+                catch (err) {
+                    sendJson(res, 400, { error: err.message });
+                    return;
+                }
+                if (typeof body.task !== "string" || body.task.trim().length === 0) {
+                    sendJson(res, 400, { error: 'field "task" (non-empty string) is required' });
+                    return;
+                }
+                const cfg = { ...baseConfig, yes: true };
+                if (body.workdir) {
+                    const abs = resolve(body.workdir);
+                    if (!existsSync(abs) || !statSync(abs).isDirectory()) {
+                        sendJson(res, 400, { error: `workdir does not exist or is not a directory: ${body.workdir}` });
+                        return;
+                    }
+                    cfg.workdir = abs;
+                }
+                const permission = body.permission ?? cfg.permissionMode;
+                if (permission === "ask") {
+                    sendJson(res, 400, { error: 'permission "ask" is not supported by the server (it cannot prompt). Use "auto" or "readonly".' });
+                    return;
+                }
+                cfg.permissionMode = permission;
+                if (body.buildCmd)
+                    cfg.buildCmd = body.buildCmd;
+                if (body.model)
+                    cfg.model = body.model;
+                if (body.provider)
+                    cfg.provider = body.provider;
+                if (body.maxSteps)
+                    cfg.maxSteps = Math.min(Math.max(body.maxSteps, 1), 500);
+                const record = {
+                    id: randomUUID(),
+                    task: body.task,
+                    workdir: cfg.workdir,
+                    status: "running",
+                    createdAt: new Date().toISOString(),
+                    finishedAt: null,
+                    events: [],
+                    subscribers: new Set(),
+                    agent: null,
+                    abortRequested: false,
+                    result: null,
+                    error: null,
+                };
+                runs.set(record.id, record);
+                launchRun(record, cfg, body.task);
+                sendJson(res, 202, publicRun(record));
+                return;
+            }
+            sendJson(res, 405, { error: "method not allowed" });
+            return;
+        }
+        // ── /api/runs/:id[...] ──
+        const runMatch = path.match(/^\/api\/runs\/([0-9a-f-]{36})(\/events|\/abort)?$/i);
+        if (runMatch) {
+            const record = runs.get(runMatch[1]);
+            if (!record) {
+                sendJson(res, 404, { error: `unknown run id: ${runMatch[1]}` });
+                return;
+            }
+            if (runMatch[2] === "/events" && req.method === "GET") {
+                handleEventsSSE(req, res, record);
+                return;
+            }
+            if (runMatch[2] === "/abort" && req.method === "POST") {
+                if (record.status !== "running" || !record.agent) {
+                    sendJson(res, 409, { error: `run is not running (status: ${record.status})` });
+                    return;
+                }
+                record.abortRequested = true;
+                record.agent.abort();
+                sendJson(res, 200, { ok: true, status: "running (aborting...)" });
+                return;
+            }
+            if (!runMatch[2] && req.method === "GET") {
+                sendJson(res, 200, publicRun(record));
+                return;
+            }
+        }
+        sendJson(res, 404, { error: `not found: ${req.method} ${path}` });
+    };
+    const server = createServer((req, res) => {
+        void handle(req, res).catch(() => {
+            if (!res.writableEnded)
+                sendJson(res, 500, { error: "internal server error" });
+        });
+    });
+    return new Promise((resolve, reject) => {
+        server.once("error", reject);
+        server.listen(opts.port ?? 0, host, () => {
+            const address = server.address();
+            const port = typeof address === "object" && address !== null ? address.port : 0;
+            resolve({
+                server,
+                port,
+                close: () => new Promise((res) => {
+                    // Abort in-flight runs so background work does not keep the loop alive.
+                    for (const r of runs.values()) {
+                        if (r.status === "running") {
+                            r.abortRequested = true;
+                            r.agent?.abort();
+                        }
+                    }
+                    server.close(() => res());
+                    server.closeAllConnections?.();
+                }),
+            });
+        });
+    });
+}

package/dist/tools.js

@@ -3,6 +3,7 @@ import { spawn } from "node:child_process";
 import { resolve, dirname, basename, join, relative, isAbsolute } from "node:path";
 import { unifiedDiff } from "./diff.js";
 import * as ui from "./ui.js";
+import { toolWebFetch } from "./webfetch.js";
 const MAX_OUTPUT_CHARS = 20_000;
 const MAX_FILE_SIZE_BYTES = 2 * 1024 * 1024; // refuse to read files > 2MB
 function clamp(s, max = MAX_OUTPUT_CHARS) {
@@ -88,16 +89,21 @@ function toolReadFile(workdir, args) {
         return { ok: true, output: clamp(numbered) };
     });
 }
+function toToolDiff(path, diff) {
+    if (!diff.text && !diff.truncated)
+        return undefined;
+    return { path, text: diff.text, added: diff.added, removed: diff.removed, truncated: diff.truncated };
+}
 /** Shared permission/diff gate for file writes. Returns null = approved. */
-async function gateWrite(ctx, path, oldContent, newContent) {
+async function gateWrite(ctx, path, diff) {
     const mode = ctx.permissionMode ?? "auto";
-    const diff = unifiedDiff(path, oldContent, newContent);
     if (mode === "readonly") {
         if (diff.text)
             ui.printDiff(diff.text);
         return {
             ok: false,
             output: `ERROR: readonly mode — write to ${path} denied. The diff above is shown for review only; nothing was written.`,
+            diff: toToolDiff(path, diff),
         };
     }
     if (mode === "ask" && ctx.permissions) {
@@ -105,7 +111,11 @@ async function gateWrite(ctx, path, oldContent, newContent) {
             ui.printDiff(diff.text);
         const allowed = await ctx.permissions.confirmEdit(path, diff.text);
         if (!allowed) {
-            return { ok: false, output: `ERROR: user rejected the write to ${path}. Try a different approach or explain why it is needed.` };
+            return {
+                ok: false,
+                output: `ERROR: user rejected the write to ${path}. Try a different approach or explain why it is needed.`,
+                diff: toToolDiff(path, diff),
+            };
         }
     }
     else if (diff.text && !diff.truncated) {
@@ -131,12 +141,17 @@ async function toolWriteFile(ctx, args) {
     catch {
         // new file
     }
-    const gate = await gateWrite(ctx, args.path, oldContent, args.content);
+    const diff = unifiedDiff(args.path, oldContent, args.content);
+    const gate = await gateWrite(ctx, args.path, diff);
     if (gate)
         return gate;
     mkdirSync(dirname(abs), { recursive: true });
     writeFileSync(abs, args.content, "utf8");
-    return { ok: true, output: `Wrote ${args.content.split("\n").length} lines to ${args.path}` };
+    return {
+        ok: true,
+        output: `Wrote ${args.content.split("\n").length} lines to ${args.path}`,
+        diff: toToolDiff(args.path, diff),
+    };
 }
 async function toolEditFile(ctx, args) {
     let abs;
@@ -157,11 +172,16 @@ async function toolEditFile(ctx, args) {
     // Function replacement: avoids JS $-pattern interpolation ($&, $', $`, $1…)
     // which would corrupt literal text like "$&" in the new content.
     const newContent = content.replace(args.old_string, () => args.new_string);
-    const gate = await gateWrite(ctx, args.path, content, newContent);
+    const diff = unifiedDiff(args.path, content, newContent);
+    const gate = await gateWrite(ctx, args.path, diff);
     if (gate)
         return gate;
     writeFileSync(abs, newContent, "utf8");
-    return { ok: true, output: `Edited ${args.path}` };
+    return {
+        ok: true,
+        output: `Edited ${args.path}`,
+        diff: toToolDiff(args.path, diff),
+    };
 }
 function toolListFiles(workdir, args) {
     return toResult(() => {
@@ -211,8 +231,10 @@ function toolListFiles(workdir, args) {
  * Run a shell command asynchronously (async spawn keeps the event loop free,
  * so streaming output renders and SIGINT is handled promptly).
  * Kills the child on timeout or external abort (SIGINT via ctx.signal).
+ * When `onOutput` is provided, stdout/stderr chunks are forwarded live as they
+ * arrive (in addition to being collected into the final ToolResult).
  */
-export async function toolRunCommand(workdir, args, signal) {
+export async function toolRunCommand(workdir, args, signal, onOutput) {
     const timeoutMs = Math.min(Math.max(args.timeout_secs ?? 120, 1), 600) * 1000;
     return new Promise((resolve) => {
         let settled = false;
@@ -252,8 +274,16 @@ export async function toolRunCommand(workdir, args, signal) {
             onAbort();
         else
             signal?.addEventListener("abort", onAbort, { once: true });
-        child.stdout?.on("data", (c) => { stdout += c.toString("utf8"); });
-        child.stderr?.on("data", (c) => { stderr += c.toString("utf8"); });
+        child.stdout?.on("data", (c) => {
+            const s = c.toString("utf8");
+            stdout += s;
+            onOutput?.("stdout", s);
+        });
+        child.stderr?.on("data", (c) => {
+            const s = c.toString("utf8");
+            stderr += s;
+            onOutput?.("stderr", s);
+        });
         child.on("error", (err) => {
             finish({ ok: false, output: clamp(`$ ${args.command}\n(spawn error) ${err.message}`) });
         });
@@ -353,7 +383,28 @@ export const AGENT_TOOLS = [
                 }, ["command"]),
             },
         },
-        run: (ctx, args) => toolRunCommand(ctx.workdir, args, ctx.signal),
+        run: (ctx, args) => toolRunCommand(ctx.workdir, args, ctx.signal, ctx.onToolOutput ? (stream, delta) => ctx.onToolOutput?.("run_command", stream, delta) : undefined),
+    },
+    {
+        spec: {
+            type: "function",
+            function: {
+                name: "web_fetch",
+                description: "Fetch a public HTTP(S) URL and return its content as readable plain text " +
+                    "(HTML converted to text, JSON pretty-printed). WHEN TO USE: the task depends on external, " +
+                    "possibly outdated knowledge — library/API documentation, an error message or comment " +
+                    "containing a URL, current package versions or changelogs, standards/specs. " +
+                    "WHEN NOT TO: the answer is already in the working directory or in the user's request; " +
+                    "you need a search engine (this tool fetches exact URLs only, it cannot search); " +
+                    "the content is a binary file (images, archives, PDFs are refused). " +
+                    "Private/internal addresses (localhost, 10.x, 192.168.x, 127.x) are blocked.",
+                parameters: obj({
+                    url: str("Absolute http(s) URL to fetch"),
+                    max_chars: str("Max characters of extracted content to return (default 20000, max 100000)"),
+                }, ["url"]),
+            },
+        },
+        run: (ctx, args) => toolWebFetch(ctx, args),
     },
 ];
 export function getTool(name) {