s-app-scoder-agent 0.4.0 → 0.5.0

package/README.md

@@ -80,9 +80,22 @@ You (task) → LLM plans → Tools execute code → Build runs → Success? →
 | `edit_file` | Find-and-replace (unique match required) |
 | `list_files` | Recursive directory listing |
 | `run_command` | Execute any shell command (subject to permission policy) |
+| `web_fetch` | Fetch a public HTTP(S) URL → readable text (HTML→text, JSON pretty-printed) |
 
 File writes (`write_file` / `edit_file`) are symlink-safe: paths are resolved via `realpath` and cannot escape the working directory, even through a malicious symlink. `read_file` refuses files larger than 2MB with guidance to use `grep`/`head`/`tail`.
 
+### Web access (`web_fetch`)
+
+The agent can read the internet through the built-in `web_fetch` tool — it fetches exact URLs (it cannot search) and returns readable plain text: HTML is converted to text (scripts/styles stripped, entities decoded, title extracted), JSON is pretty-printed, binary content is refused. The system prompt instructs the agent *when to fetch* (external/API docs, URLs in error messages, current versions, changelogs) and when not to (answer available locally).
+
+Safety defaults:
+
+- **SSRF protection** — `localhost`, private and link-local addresses (10.x, 172.16/12, 192.168.x, 127.x, 169.254.x, IPv6 ULA/link-local) are blocked. Set `SCODER_WEB_ALLOW_PRIVATE=1` to allow local dev servers.
+- Only `http`/`https`; up to 5 redirects — every hop is re-validated against the private-address block list.
+- 30 s timeout, SIGINT-abortable; body capped at 512 KB; extracted text capped at 20k chars (configurable via `max_chars`).
+- HTML is converted to plain text (no JS execution); images/archives/PDFs are refused.
+- Read-only — the tool never writes locally, so it is allowed even in `readonly` permission mode.
+
 ## Configuration
 
 ### Environment variables
@@ -96,6 +109,9 @@ File writes (`write_file` / `edit_file`) are symlink-safe: paths are resolved vi
 | `SCODER_MAX_STEPS` | `40` | Max loop iterations before giving up |
 | `SCODER_PERMISSION` | `auto` | Permission mode: `auto` \| `ask` \| `readonly` |
 | `SCODER_STREAM` | `1` | `0` to disable streaming LLM output |
+| `SCODER_STREAM` | `1` | `0` to disable streaming LLM output |
+| `SCODER_SERVER_TOKEN` | — | `scoder serve` only: require `Authorization: Bearer <token>` |
+| `SCODER_WEB_ALLOW_PRIVATE` | — | Set to `1` to let `web_fetch` reach localhost/private addresses (local dev) |
 | `SCODER_NO_APIKEY_WARNING` | — | Set to `1` to suppress the apiKey-in-rc warning |
 
 ### Per-project config file (.scoderrc.json)
@@ -225,7 +241,39 @@ Sessions older than 7 days are pruned automatically on the next run. Use `--no-s
 
 ## Streaming
 
-LLM output is streamed token-by-token by default (`SCODER_STREAM=0` to disable). If a provider doesn't support streaming, scoder automatically falls back to non-streaming requests.
+scoder streams everything it can, live, as it happens:
+
+- **LLM tokens** — assistant text renders character-by-character (OpenAI-compatible SSE and native Anthropic streaming). If a provider doesn't support streaming, scoder automatically falls back to non-streaming requests. Disable with `SCODER_STREAM=0`.
+- **Tool output** — `run_command` and build output print live (dimmed block) while the command runs, instead of appearing only after it finishes. Live output is capped at 20k chars; the full output still goes to the LLM.
+- **SIGINT-safe** — Ctrl+C kills the running command immediately; streamed rendering never blocks the event loop.
+- Output honors `NO_COLOR` and degrades to plain text when piped (CI-friendly).
+
+## HTTP Server Mode (`scoder serve`)
+
+Run scoder as a local HTTP service — submit tasks programmatically and consume progress as Server-Sent Events:
+
+```bash
+scoder serve                    # http://127.0.0.1:0 (random port, printed at startup)
+scoder serve --port 4114        # fixed port
+SCODER_SERVER_TOKEN=secret scoder serve --host 127.0.0.1
+```
+
+| Endpoint | Method | Description |
+|----------|--------|-------------|
+| `/api/health` | GET | Liveness: `{ ok, running, runs }` |
+| `/api/runs` | POST | Start a run: `{ "task": "...", "workdir?", "buildCmd?", "model?", "provider?", "maxSteps?", "permission?" }` → `202 { id, eventsUrl }` |
+| `/api/runs` | GET | List runs with status/timing |
+| `/api/runs/<id>` | GET | Run status + final result |
+| `/api/runs/<id>/events` | GET | **SSE stream** — full event replay, then live, closes on finish |
+| `/api/runs/<id>/abort` | POST | Abort a running run (equivalent to SIGINT) |
+
+SSE event types: `run_start`, `step`, `llm_delta` (assistant text), `tool_call`, `tool_output` (live stdout/stderr chunks), `tool_result`, `llm_usage`, `build`, `finish`. The stream replays every event from the beginning, then stays live, and closes after `finish` — safe to (re)connect at any time.
+
+Notes:
+
+- Runs are always non-interactive; `permission: "ask"` is rejected — use `auto` or `readonly`.
+- Binds `127.0.0.1` by default. Set `SCODER_SERVER_TOKEN` to require `Authorization: Bearer <token>` on every request.
+- Max 4 concurrent runs (extra requests get `429`); per-run overrides: `workdir`, `buildCmd`, `model`, `provider`, `maxSteps`, `permission`.
 
 ## Logging
 
@@ -268,6 +316,7 @@ scoder detects the build command automatically:
 ```
 scoder [options] "<task>"     Run a task autonomously until the build passes
 scoder                       Start interactive session
+scoder serve [--port] [--host]   HTTP server mode (see above)
 scoder --help | --version     Help and version
 ```
 
@@ -283,6 +332,9 @@ scoder --help | --version     Help and version
 | `-y` | Non-interactive mode (denies commands needing confirmation) |
 | `--provider <name>` | `openai` \| `anthropic` (env SCODER_PROVIDER; auto-detected) |
 | `--no-save` | Disable session auto-save to `.scoder/sessions/` |
+| `--log-file` | Write a structured JSONL event log to `.scoder/logs/` |
+| `--port <n>` | (`serve`) TCP port, `0` = random free port |
+| `--host <addr>` | (`serve`) Bind address (default `127.0.0.1`) |
 
 ## Examples
 
@@ -305,6 +357,15 @@ scoder -m claude-sonnet-4-5 "refactor the parser module"
 
 # CI: non-interactive, no session saving
 scoder --no-save -y "run the full migration"
+
+# Run as an HTTP service and consume progress via SSE
+scoder serve --port 4114 &
+curl -s -X POST localhost:4114/api/runs -H 'Content-Type: application/json' \
+  -d '{"task": "add input validation to the CLI"}'
+curl -N http://127.0.0.1:4114/api/runs/<id>/events     # live progress
+
+# Fetch external docs during a task (agent decides when, via web_fetch)
+scoder "upgrade express to v5 — check the official migration guide first"
 ```
 
 ## Architecture
@@ -312,22 +373,26 @@ scoder --no-save -y "run the full migration"
 ```
 ┌─────────────────────────────────────────────┐
 │  CLI (src/index.ts)                         │
-│   arg parsing, REPL, SIGINT handling        │
-└─────────────────┬───────────────────────────┘
-                  │
-┌─────────────────▼───────────────────────────┐
+│   arg parsing, REPL, serve, SIGINT          │
+└───────────────┬─────────────────────────────┘
+                │
+┌───────────────▼─────────────────────────────┐
 │  Agent (src/agent.ts)                       │
-│   Closed-loop orchestrator                  │
-│   history trimming, error injection         │
-└───────┬───────────────────────┬─────────────┘
-        │                       │
-┌───────▼───────┐    ┌─────────▼──────────┐
-│  LLM Client   │    │  Tool Registry       │
-│ (src/llm.ts)  │    │ (src/tools.ts)       │
-│ OpenAI compat │    │ read/write/run/list │
-└───────────────┘    └──────────────────────┘
-        │
-        ▼
+│  Closed-loop orchestrator                   │
+│  history trimming, error injection          │
+│  emits AgentEvent (UI / SSE consumers)      │
+└──────┬─────────────┬───────────────┬────────┘
+       │             │               │
+┌──────▼───────┐  ┌──▼───────────┐  ┌▼──────────────────┐
+│  LLM Client  │  │ Tool Registry│  │ Server            │
+│ (src/llm.ts) │  │(src/tools.ts)│  │ (src/server.ts)   │
+│ OpenAI compat│  │ + web_fetch  │  │ HTTP API + SSE    │
+│ (anthropic:  │  │ (src/        │  │ runs in background│
+│  provider-   │  │  webfetch.ts)│  └───────────────────┘
+│  anthropic)  │  └──────────────┘
+└──────────────┘
+       │
+       ▼
 ┌─────────────────────────────────────────────┐
 │  Build Checker (src/build.ts)               │
 │   run build → exit 0 = stop condition met   │
@@ -337,7 +402,7 @@ scoder --no-save -y "run the full migration"
 ## Integration Testing
 
 ```bash
-npm test          # runs: lint → typecheck → build → 116 unit tests + e2e + MCP smoke
+npm test          # runs: build → unit tests (node --test) → e2e closed-loop → MCP smoke
 npm run lint      # eslint flat config (typescript-eslint + eqeqeq, prefer-const...)
 npm run typecheck # tsc --noEmit
 ```
@@ -345,17 +410,18 @@ npm run typecheck # tsc --noEmit
 Test suites (run with `npm test` — auto-discovers `test/*.test.mjs`):
 - `test/permissions.test.mjs` — catastrophic patterns, mode classification, allowlist word-boundary, timeout-denies
 - `test/permission-prompt.test.mjs` — interactive prompt timeout behavior
-- `test/tools.test.mjs` — safePath traversal, symlink escape, file-size cap, write/edit/list
+- `test/tools.test.mjs` — safePath traversal, symlink escape, file-size cap, write/edit/list, live `run_command` output streaming
+- `test/webfetch.test.mjs` — HTML→text, JSON, redirects, SSRF guard, binary refusal, truncation
+- `test/server.test.mjs` — HTTP API: run lifecycle via SSE, abort, auth, live `tool_output` events
 - `test/core.test.mjs` — unified diff, retry backoff, context trimming
 - `test/config.test.mjs` — env/rc/cli precedence, logFile mapping, permission lists
 - `test/session.test.mjs` — session store, smart prune, resolve
+- `test/cost.test.mjs` — token usage & cost aggregation
 - `test/anthropic.test.mjs` — message translation + native SSE streaming
 - `test/llm.test.mjs` — OpenAI-compatible chat + SSE streaming + redaction
 - `test/run-e2e.mjs` — closed-loop integration (mock LLM server)
 - `test/run-mcp-test.mjs` — MCP smoke (mock stdio server)
 
-Coverage (lines): **90.3%** overall — see `npm run coverage`.
-
 ## Exit Codes
 
 | Code | Meaning |

package/dist/agent.js

@@ -28,7 +28,13 @@ RULES:
 6. Never invent requirements beyond the given task.
 7. IMPORTANT: if a run_command is denied by permission policy, you will receive
    an error message. Use this as a signal to find a safer alternative or to
-   communicate the limitation to the user.`;
+   communicate the limitation to the user.
+8. You have web access ONLY through web_fetch (it fetches exact URLs, it cannot
+   search). Use it when the task depends on external or fast-changing knowledge:
+   library/API documentation, a URL found in an error message or code comment,
+   current package versions, changelogs, release notes, standards. Skip it when
+   the answer is in the working directory or is stable general knowledge. After
+   fetching, ground your edits in what the page actually says.`;
 export class Agent {
     config;
     client;
@@ -48,6 +54,10 @@ export class Agent {
     mcp = null;
     /** Aborted when abort() is called — cancels in-flight LLM requests (SIGINT). */
     runSignal = new AbortController();
+    /** Optional structured-event sink (used by the HTTP/SSE server frontend). */
+    onEvent = null;
+    /** Set while a tool call is executing, for tool_output event correlation. */
+    currentToolCall = null;
     constructor(config) {
         this.config = config;
         const commonOpts = {
@@ -72,6 +82,7 @@ export class Agent {
             workdir: config.workdir,
             permissions: this.permissions,
             permissionMode: config.permissionMode,
+            onToolOutput: this.handleToolOutput,
         };
         this.session = new SessionStore(config.workdir, config.noSave !== true);
         this.logger = JsonlLogger.forSession(config.workdir, this.session.id, config.logFile);
@@ -92,6 +103,27 @@ export class Agent {
         // terminate its child process immediately (long builds must be interruptible).
         this.ctx.signal = this.runSignal.signal;
     }
+    /** Emit one structured run event to the sink (if attached). */
+    emit(ev) {
+        this.onEvent?.(ev);
+    }
+    /**
+     * Live tool-output handler: renders chunks in the terminal (dimmed block) and
+     * forwards them as `tool_output` events. Opens the stream block lazily on the
+     * first chunk; `endToolStream()` closes it after the tool completes.
+     */
+    handleToolOutput = (name, stream, delta) => {
+        if (!ui.isToolStreamOpen()) {
+            ui.toolStreamStart();
+        }
+        ui.toolStreamChunk(delta);
+        this.emit({ type: "tool_output", name, stream, delta });
+    };
+    /** Close the live tool-output block (if open) before printing the next UI element. */
+    endToolStream() {
+        if (ui.isToolStreamOpen())
+            ui.toolStreamEnd();
+    }
     /** Push one tool-result message back into the conversation. */
     pushToolResult(tc, content) {
         this.messages.push({
@@ -108,6 +140,7 @@ export class Agent {
      */
     rejectToolCall(step, tc, output, logExtra) {
         ui.toolResult(tc.name, false, output);
+        this.emit({ type: "tool_result", step, name: tc.name, ok: false, output });
         this.logger.log({ type: "tool", step, tool: tc.name, ok: false, ...logExtra });
         this.pushToolResult(tc, output);
     }
@@ -126,6 +159,10 @@ export class Agent {
         this.usageTotals.outputTokens += output;
         this.usageTotals.cachedTokens += cached;
         ui.info(`tokens: in=${usage.prompt_tokens ?? "?"} out=${usage.completion_tokens ?? "?"}`);
+        this.emit({
+            type: "llm_usage",
+            usage: { input_tokens: input, output_tokens: output, cached_tokens: cached },
+        });
         this.logger.log({
             type: "llm_usage",
             model: this.client.model,
@@ -161,6 +198,7 @@ export class Agent {
                         started = true;
                     }
                     ui.llmStreamChunk(chunk.contentDelta);
+                    this.emit({ type: "llm_delta", delta: chunk.contentDelta });
                     streamedText += chunk.contentDelta;
                 }
                 if (chunk.final)
@@ -217,9 +255,13 @@ export class Agent {
             throw new Error("No API key configured. Set SCODER_API_KEY or OPENAI_API_KEY (or put apiKey in .scoderrc.json).");
         }
         const buildCmd = this.buildCmd;
-        ui.header("TASK");
-        ui.info(task);
-        ui.info(`model=${this.client.model}  workdir=${this.config.workdir}  build="${buildCmd}"  maxSteps=${this.config.maxSteps}`);
+        ui.banner("scoder", [
+            ["task", task],
+            ["model", `${this.client.model} (${this.config.provider}${this.config.stream ? ", stream" : ""})`],
+            ["workdir", this.config.workdir],
+            ["build", buildCmd],
+            ["steps", `max ${this.config.maxSteps}  ·  permission ${this.config.permissionMode}`],
+        ]);
         this.currentTask = task;
         this.resetRunSignal();
         this.resetUsageTotals();
@@ -231,6 +273,14 @@ export class Agent {
             },
             { role: "user", content: task },
         ];
+        this.emit({
+            type: "run_start",
+            task,
+            model: this.client.model,
+            provider: this.config.provider,
+            workdir: this.config.workdir,
+            buildCmd,
+        });
         try {
             await this.connectMcp();
             return await this.runLoop(0, buildCmd, null);
@@ -304,6 +354,7 @@ export class Agent {
         while (steps < this.config.maxSteps && !this.aborted) {
             steps++;
             ui.step(steps, this.config.maxSteps, "thinking...");
+            this.emit({ type: "step", step: steps, maxSteps: this.config.maxSteps });
             const { message, usage } = await this.chatWithStream().catch((err) => {
                 // SIGINT during the LLM call — stop gracefully instead of crashing
                 if (this.aborted) {
@@ -363,6 +414,8 @@ export class Agent {
                     continue;
                 }
                 ui.toolCall(tc.name, args);
+                this.currentToolCall = { step: steps, id: tc.id, name: tc.name };
+                this.emit({ type: "tool_call", step: steps, id: tc.id, name: tc.name, args });
                 if (!tool && !(this.mcp?.hasTool(tc.name))) {
                     this.rejectToolCall(steps, tc, `ERROR: unknown tool "${tc.name}". Available: ${AGENT_TOOLS.map((t) => t.spec.function.name).join(", ")}${this.mcp ? " + MCP tools (mcp__<server>__<tool>)" : ""}`, { error: "unknown tool" });
                     continue;
@@ -426,7 +479,10 @@ export class Agent {
                     this.aborted = true;
                     ui.warn("edit confirmation aborted by user ([q]uit) — stopping the run");
                 }
+                this.endToolStream();
+                this.currentToolCall = null;
                 ui.toolResult(tc.name, result.ok, result.output);
+                this.emit({ type: "tool_result", step: steps, name: tc.name, ok: result.ok, output: result.output });
                 stepToolResults.set(tc.id, { ok: result.ok, output: result.output });
                 this.pushToolResult(tc, summariseOutput(result.output));
             }
@@ -483,8 +539,10 @@ export class Agent {
     }
     /** Explicitly verify the build (independent of what the LLM claims). */
     async checkBuild(buildCmd) {
-        const res = await runBuild(this.config.workdir, buildCmd);
+        const res = await runBuild(this.config.workdir, buildCmd, (stream, delta) => this.handleToolOutput("build", stream, delta));
+        this.endToolStream();
         ui.buildStatus(res.success, res.output);
+        this.emit({ type: "build", success: res.success, command: buildCmd, output: res.output });
         this.logger.log({ type: "build", success: res.success, command: buildCmd, output: res.output.slice(0, 10_000) });
         return res;
     }
@@ -495,6 +553,7 @@ export class Agent {
         else {
             ui.error(`Task NOT complete. ${summary}`);
         }
+        this.emit({ type: "finish", success, steps, summary: summary.slice(0, 2000) });
         this.logger.log({ type: "finish", success, steps });
         return { success, steps, buildCmd, summary: summary.slice(0, 2000) };
     }

package/dist/build.js

@@ -30,9 +30,10 @@ export function detectBuildCommand(workdir) {
 /**
  * Run the build command. This is the agent's stop condition:
  * exit code 0 == task complete.
+ * `onOutput` (optional) receives stdout/stderr chunks live while the build runs.
  */
-export async function runBuild(workdir, command) {
-    const res = await toolRunCommand(workdir, { command, timeout_secs: 600 });
+export async function runBuild(workdir, command, onOutput) {
+    const res = await toolRunCommand(workdir, { command, timeout_secs: 600 }, undefined, onOutput);
     return {
         success: res.ok,
         command,

package/dist/index.js

@@ -21,6 +21,9 @@ USAGE
   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 +123,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 +169,10 @@ function parseArgs(argv) {
         args.subcommand = "cost";
         args.task = null;
     }
+    else if (rest[0] === "serve") {
+        args.subcommand = "serve";
+        args.task = null;
+    }
     return args;
 }
 async function runOnce(cfg, task) {
@@ -302,6 +320,32 @@ async function main() {
         console.log(formatCostReport(sessionCosts));
         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/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) {
@@ -211,8 +212,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 +255,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 +364,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) {

package/dist/ui.js

@@ -1,12 +1,14 @@
 import process from "node:process";
-const RESET = "\x1b[0m";
-const BOLD = "\x1b[1m";
-const DIM = "\x1b[2m";
-const GREEN = "\x1b[32m";
-const YELLOW = "\x1b[33m";
-const RED = "\x1b[31m";
-const CYAN = "\x1b[36m";
-const BLUE = "\x1b[34m";
+// Honor NO_COLOR and non-TTY output: drop ANSI codes so logs/CI stay clean.
+const COLOR = process.env.NO_COLOR === undefined && process.stdout.isTTY === true;
+const RESET = COLOR ? "\x1b[0m" : "";
+const BOLD = COLOR ? "\x1b[1m" : "";
+const DIM = COLOR ? "\x1b[2m" : "";
+const GREEN = COLOR ? "\x1b[32m" : "";
+const YELLOW = COLOR ? "\x1b[33m" : "";
+const RED = COLOR ? "\x1b[31m" : "";
+const CYAN = COLOR ? "\x1b[36m" : "";
+const BLUE = COLOR ? "\x1b[34m" : "";
 function ts() {
     return new Date().toISOString().slice(11, 23);
 }
@@ -14,7 +16,7 @@ export function info(msg) {
     console.log(`${DIM}[${ts()}]${RESET} ${msg}`);
 }
 export function step(stepNum, total, msg) {
-    console.log(`${BLUE}[${stepNum}/${total}]${RESET} ${BOLD}${msg}${RESET}`);
+    console.log(`${BLUE}[${String(stepNum).padStart(2)}/${total}]${RESET} ${BOLD}▸ ${msg}${RESET}`);
 }
 export function success(msg) {
     console.log(`${GREEN}✓${RESET} ${GREEN}${msg}${RESET}`);
@@ -37,7 +39,7 @@ export function toolCall(name, args) {
 export function toolResult(name, ok, output) {
     const preview = output.split("\n")[0]?.slice(0, 120) ?? "";
     const icon = ok ? `${GREEN}✓${RESET}` : `${RED}✗${RESET}`;
-    console.log(`${icon} ${CYAN}${name}${RESET} → ${preview}`);
+    console.log(`${icon} ${CYAN}${name}${RESET} ${DIM}→${RESET} ${preview}`);
 }
 export function buildStatus(success, output) {
     const icon = success ? `${GREEN}✓ BUILD SUCCESS` : `${RED}✗ BUILD FAILED`;
@@ -46,6 +48,25 @@ export function buildStatus(success, output) {
 export function header(msg) {
     console.log(`\n${BOLD}${CYAN}── ${msg} ${"─".repeat(Math.max(2, 60 - msg.length))}${RESET}`);
 }
+/** Startup banner: a clean key/value box (plain-text fallback when piped). */
+export function banner(title, rows) {
+    const keyWidth = Math.max(8, ...rows.map(([k]) => k.length));
+    const inner = Math.max(title.length + 4, ...rows.map(([, v]) => keyWidth + Math.max(...String(v).split("\n").map((l) => l.length)) + 1));
+    console.log(`${BOLD}${CYAN}╭─ ${title} ${"─".repeat(Math.max(1, inner - title.length - 3))}╮${RESET}`);
+    for (const [key, value] of rows) {
+        const lines = String(value).split("\n");
+        for (let i = 0; i < lines.length; i++) {
+            const k = (i === 0 ? key : "").padEnd(keyWidth);
+            let v = lines[i];
+            const maxV = inner - keyWidth - 1;
+            if (v.length > maxV)
+                v = v.slice(0, maxV - 1) + "…";
+            const pad = Math.max(0, inner - 1 - keyWidth - v.length);
+            console.log(`${BOLD}${CYAN}│${RESET} ${DIM}${k}${RESET}${v}${" ".repeat(pad)}${BOLD}${CYAN}│${RESET}`);
+        }
+    }
+    console.log(`${BOLD}${CYAN}╰${"─".repeat(inner)}╯${RESET}`);
+}
 // ── Streaming helpers ────────────────────────────────────────────────────────
 let _streamLine = "";
 let _streamColor = CYAN;
@@ -69,6 +90,51 @@ export function llmStreamEnd(suffix = "") {
     process.stdout.write(`${suffix}\n`);
     return line;
 }
+// ── Tool output streaming (live run_command output) ─────────────────────────
+const TOOL_STREAM_MAX_CHARS = 20_000;
+let _toolStreamOpen = false;
+let _toolStreamLineOpen = false; // last chunk did not end with "\n"
+let _toolStreamChars = 0;
+/** Begin a live tool-output block. Output is printed dimmed, capped at 20k chars. */
+export function toolStreamStart() {
+    if (_toolStreamOpen)
+        return;
+    _toolStreamOpen = true;
+    _toolStreamLineOpen = false;
+    _toolStreamChars = 0;
+    process.stdout.write(`${DIM}┌ output${RESET}`);
+}
+/** Append a tool-output delta to the live block. */
+export function toolStreamChunk(delta) {
+    if (!_toolStreamOpen)
+        return;
+    if (_toolStreamChars >= TOOL_STREAM_MAX_CHARS)
+        return;
+    _toolStreamChars += delta.length;
+    if (_toolStreamChars >= TOOL_STREAM_MAX_CHARS) {
+        // Include the tail of this chunk up to the cap, then stop rendering live.
+        const keep = delta.slice(0, Math.max(0, delta.length - (_toolStreamChars - TOOL_STREAM_MAX_CHARS)));
+        if (keep.length > 0) {
+            process.stdout.write(`${DIM}${keep}${RESET}`);
+            _toolStreamLineOpen = !keep.endsWith("\n");
+        }
+        process.stdout.write(`\n${DIM}│ (live output truncated at ${TOOL_STREAM_MAX_CHARS} chars — full output in the result)${RESET}`);
+        return;
+    }
+    process.stdout.write(`\n${DIM}│ ${delta.replace(/\n/g, `\n${DIM}│ ${RESET}`)}${RESET}`);
+    _toolStreamLineOpen = !delta.endsWith("\n");
+}
+/** Finish the live tool-output block (closes the partial last line). */
+export function toolStreamEnd() {
+    if (!_toolStreamOpen)
+        return;
+    _toolStreamOpen = false;
+    process.stdout.write(_toolStreamLineOpen ? `\n${DIM}└${RESET}\n` : `${DIM}└${RESET}\n`);
+}
+/** True while a live tool-output block is open. */
+export function isToolStreamOpen() {
+    return _toolStreamOpen;
+}
 // ── Diff rendering ───────────────────────────────────────────────────────────
 /** Print a unified diff with colors (+ green, - red, @@ cyan). */
 export function printDiff(diffText) {

package/dist/webfetch.js

@@ -0,0 +1,251 @@
+import { isIP } from "node:net";
+import { lookup } from "node:dns/promises";
+/**
+ * web_fetch — read-only HTTP(S) fetch with SSRF protection.
+ *
+ * - Only http/https; follows up to 5 redirects, validating every hop.
+ * - Private/loopback/link-local addresses are blocked by default
+ *   (env SCODER_WEB_ALLOW_PRIVATE=1 lifts the block for local dev/testing).
+ * - HTML is converted to plain text; JSON is pretty-printed; binary is refused.
+ * - Output is capped so a huge page cannot flood the LLM context.
+ */
+const FETCH_TIMEOUT_MS = 30_000;
+const MAX_BODY_BYTES = 512 * 1024;
+const MAX_REDIRECTS = 5;
+const DEFAULT_MAX_CHARS = 20_000;
+function allowPrivate() {
+    return process.env.SCODER_WEB_ALLOW_PRIVATE === "1";
+}
+/** True if the address is private/loopback/link-local (IPv4 + IPv6). */
+function isPrivateAddress(ip) {
+    const v = isIP(ip);
+    if (v === 4) {
+        const parts = ip.split(".").map(Number);
+        const a = parts[0];
+        const b = parts[1];
+        if (a === 10 || a === 127 || a === 0)
+            return true;
+        if (a === 172 && b >= 16 && b <= 31)
+            return true;
+        if (a === 192 && b === 168)
+            return true;
+        if (a === 169 && b === 254)
+            return true; // link-local
+        if (a === 100 && b >= 64 && b <= 127)
+            return true; // CGNAT
+        return false;
+    }
+    if (v === 6) {
+        const lower = ip.toLowerCase();
+        if (lower === "::1" || lower === "::")
+            return true;
+        if (lower.startsWith("fe80"))
+            return true; // link-local
+        if (/^f[cd][0-9a-f]{2}:/.test(lower))
+            return true; // unique local fc00::/7
+        // IPv4-mapped ::ffff:10.0.0.1
+        const mapped = lower.match(/^::ffff:(\d+\.\d+\.\d+\.\d+)$/);
+        if (mapped)
+            return isPrivateAddress(mapped[1]);
+        return false;
+    }
+    return true; // not parseable -> treat as private (fail closed)
+}
+/** Resolve hostname and refuse private addresses (unless explicitly allowed). */
+async function assertPublicHost(hostname) {
+    if (allowPrivate())
+        return;
+    let addresses;
+    try {
+        addresses = await lookup(hostname, { all: true, verbatim: true });
+    }
+    catch (err) {
+        throw new Error(`DNS lookup failed for "${hostname}": ${err.message}`, { cause: err });
+    }
+    if (addresses.length === 0) {
+        throw new Error(`DNS lookup returned no addresses for "${hostname}"`);
+    }
+    for (const addr of addresses) {
+        if (isPrivateAddress(addr.address)) {
+            throw new Error(`Blocked: "${hostname}" resolves to a private/loopback address (${addr.address}). ` +
+                `web_fetch only reaches public hosts (set SCODER_WEB_ALLOW_PRIVATE=1 to allow local testing).`);
+        }
+    }
+}
+/** Decode the HTML entities that actually appear in practice. */
+function decodeEntities(s) {
+    const named = {
+        amp: "&", lt: "<", gt: ">", quot: '"', apos: "'", nbsp: " ", ndash: "–", mdash: "—",
+        hellip: "…", rsquo: "’", lsquo: "‘", rdquo: "”", ldquo: "“", copy: "©", reg: "®",
+    };
+    return s.replace(/&(#x?[0-9a-fA-F]+|[a-zA-Z]+);/g, (whole, body) => {
+        if (body.startsWith("#x") || body.startsWith("#X")) {
+            const code = parseInt(body.slice(2), 16);
+            return Number.isFinite(code) ? String.fromCodePoint(code) : whole;
+        }
+        if (body.startsWith("#")) {
+            const code = parseInt(body.slice(1), 10);
+            return Number.isFinite(code) ? String.fromCodePoint(code) : whole;
+        }
+        return named[body.toLowerCase()] ?? whole;
+    });
+}
+/** Convert HTML to readable plain text (scripts/styles stripped, block tags → newlines). */
+export function htmlToText(html) {
+    const out = html
+        .replace(/<script[\s\S]*?<\/script\s*>/gi, " ")
+        .replace(/<style[\s\S]*?<\/style\s*>/gi, " ")
+        .replace(/<noscript[\s\S]*?<\/noscript\s*>/gi, " ")
+        .replace(/<!--[\s\S]*?-->/g, " ")
+        .replace(/<(br|\/p|\/div|\/section|\/article|\/header|\/footer|\/h[1-6]|\/li|\/tr|\/pre|\/blockquote)[^>]*>/gi, "\n")
+        .replace(/<[^>]+>/g, " ")
+        .replace(/[ \t]+/g, " ")
+        .replace(/ *\n */g, "\n")
+        .replace(/\n{3,}/g, "\n\n")
+        .trim();
+    return decodeEntities(out);
+}
+/** Extract the <title> of an HTML document, if present. */
+function extractTitle(html) {
+    const m = html.match(/<title[^>]*>([\s\S]*?)<\/title\s*>/i);
+    if (!m)
+        return null;
+    const t = decodeEntities(m[1]).replace(/\s+/g, " ").trim();
+    return t ? t.slice(0, 200) : null;
+}
+/** Read the response body as text, capped at MAX_BODY_BYTES, then cancel the stream. */
+async function readBodyCapped(res) {
+    const reader = res.body?.getReader();
+    if (!reader)
+        return { text: "", truncated: false };
+    const decoder = new TextDecoder("utf-8");
+    let text = "";
+    let received = 0;
+    while (true) {
+        const { done, value } = await reader.read();
+        if (done)
+            break;
+        received += value.byteLength;
+        text += decoder.decode(value, { stream: true });
+        if (received >= MAX_BODY_BYTES) {
+            try {
+                await reader.cancel();
+            }
+            catch { /* already closed */ }
+            return { text: text + decoder.decode(), truncated: true };
+        }
+    }
+    return { text: text + decoder.decode(), truncated: false };
+}
+/** Implementation of the web_fetch tool. Also used by tests via the registry. */
+export async function toolWebFetch(ctx, args) {
+    const maxChars = Math.min(Math.max(args.max_chars ?? DEFAULT_MAX_CHARS, 500), 100_000);
+    let url;
+    try {
+        url = new URL(args.url);
+    }
+    catch {
+        return { ok: false, output: `ERROR: invalid URL: ${args.url}` };
+    }
+    if (url.protocol !== "http:" && url.protocol !== "https:") {
+        return { ok: false, output: `ERROR: only http/https URLs are supported (got ${url.protocol})` };
+    }
+    // Combined timeout + external abort (SIGINT) — manual composition for Node 18 compat
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(new Error(`timeout after ${FETCH_TIMEOUT_MS / 1000}s`)), FETCH_TIMEOUT_MS);
+    const onExternalAbort = () => controller.abort(new Error("interrupted by user"));
+    if (ctx.signal?.aborted)
+        onExternalAbort();
+    else
+        ctx.signal?.addEventListener("abort", onExternalAbort, { once: true });
+    const signal = controller.signal;
+    let current = url;
+    try {
+        // Redirect loop with per-hop SSRF validation
+        for (let hop = 0; hop <= MAX_REDIRECTS; hop++) {
+            if (signal.aborted) {
+                return { ok: false, output: `ERROR: fetch aborted (${signal.reason?.message ?? "aborted"})` };
+            }
+            await assertPublicHost(current.hostname);
+            const res = await fetch(current, {
+                method: "GET",
+                redirect: "manual",
+                headers: {
+                    "User-Agent": "scoder-agent (+https://github.com/nbhson/app-scoder-agent)",
+                    Accept: "text/html, application/json, text/plain;q=0.9, */*;q=0.1",
+                },
+                signal,
+            });
+            // Follow redirects manually so every hop is validated against SSRF
+            if (res.status >= 300 && res.status < 400) {
+                const loc = res.headers.get("location");
+                try {
+                    await res.body?.cancel();
+                }
+                catch { /* ignore */ }
+                if (!loc) {
+                    return { ok: false, output: `ERROR: ${res.status} redirect without Location header at ${current.href}` };
+                }
+                if (hop === MAX_REDIRECTS) {
+                    return { ok: false, output: `ERROR: too many redirects (>${MAX_REDIRECTS}) fetching ${args.url}` };
+                }
+                current = new URL(loc, current);
+                continue;
+            }
+            if (!res.ok) {
+                try {
+                    await res.body?.cancel();
+                }
+                catch { /* ignore */ }
+                return { ok: false, output: `ERROR: HTTP ${res.status} ${res.statusText} for ${current.href}` };
+            }
+            const contentType = res.headers.get("content-type") ?? "";
+            if (/^(image|audio|video|font|application\/(octet-stream|zip|gzip|pdf|wasm))/i.test(contentType)) {
+                try {
+                    await res.body?.cancel();
+                }
+                catch { /* ignore */ }
+                return { ok: false, output: `ERROR: unsupported content-type "${contentType}" — web_fetch returns text only (html/json/plain).` };
+            }
+            const { text: body, truncated } = await readBodyCapped(res);
+            let text;
+            if (/json/i.test(contentType)) {
+                text = prettyJson(body) ?? body;
+            }
+            else if (/html/i.test(contentType) || /^\s*</.test(body)) {
+                text = htmlToText(body);
+            }
+            else {
+                text = body;
+            }
+            const title = /text\/html/i.test(contentType) ? extractTitle(body) : null;
+            const meta = [
+                `HTTP ${res.status} ${res.statusText || ""}`.trimEnd(),
+                contentType || "unknown content-type",
+                truncated ? `body truncated at ${MAX_BODY_BYTES / 1024}KB` : null,
+            ].filter(Boolean).join(", ");
+            const out = `${text.slice(0, maxChars)}${text.length > maxChars ? `\n... [truncated, ${text.length - maxChars} more chars]` : ""}`;
+            return {
+                ok: true,
+                output: `${title ? `Title: ${title}\n` : ""}${current.href}\n(${meta})\n\n${out}`,
+            };
+        }
+        // unreachable
+        return { ok: false, output: "ERROR: redirect loop" };
+    }
+    catch (err) {
+        return { ok: false, output: `ERROR: fetch failed for ${current.href}: ${err.message}` };
+    }
+    finally {
+        clearTimeout(timer);
+        ctx.signal?.removeEventListener("abort", onExternalAbort);
+    }
+}
+function prettyJson(body) {
+    try {
+        return JSON.stringify(JSON.parse(body), null, 2);
+    }
+    catch {
+        return undefined;
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "s-app-scoder-agent",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "description": "Autonomous coding agent CLI - similar to opencode/cline/claude. Runs tasks until build succeeds.",
   "type": "module",
   "main": "dist/index.js",