rovecode 0.4.0-beta.2 → 0.4.0

package/src/tools/todo.ts

@@ -0,0 +1,320 @@
+/** Session todo / plan tool (PORT #32): `todo_write` + `todo_read` over one
+ *  JSON file per session, plus pure render helpers for the TUI surface.
+ *
+ *  Ported from opencode (MIT, snapshot ebece6e):
+ *  - tool contract — ONE `todos` array argument that REPLACES the whole list
+ *    (packages/opencode/src/tool/todo.ts:6-8, :31-34; packages/core/src/tool/
+ *    todowrite.ts:14-16, :49); the store's update is delete-all + insert in
+ *    list order (packages/opencode/src/session/todo.ts:29-51), reads come back
+ *    in that order (:53-66);
+ *  - item shape content / status / priority with the status and priority sets
+ *    (packages/schema/src/session-todo.ts:7-15);
+ *  - the when-to-use / when-not / rules guidance folded into the tool
+ *    description (packages/opencode/src/tool/todowrite.txt:3-16, :24-30, :44).
+ *  Validation follows gemini-cli (Apache-2.0, snapshot 0bd1d43)
+ *  packages/core/src/tools/write-todos.ts:100-129 validateToolParamValues —
+ *  array check, per-item object / non-empty description / status-enum checks,
+ *  and the at-most-ONE-in_progress rule (:120-126); "Cleared todo list" is
+ *  gemini's wording (:52, :68). Both upstreams reject an invalid list whole.
+ *
+ *  Deviations: items carry a caller-chosen `id` (whole-list replace needs a
+ *  stable handle the model can quote back; opencode is position-keyed, gemini
+ *  has none); three statuses only (no cancelled/blocked — drop the item
+ *  instead); bounds (≤50 items, id ≤64 chars, content ≤500 chars) so tool output
+ *  stays bounded; storage is `<sessionDir>/todos.json` written tmp+rename
+ *  (session.ts persistLeaf pattern; opencode uses SQLite, gemini is in-memory).
+ *  No in-memory cache: every read hits disk, so a second tool instance, a
+ *  resumed session and the TUI `/todos` surface all see the same truth. A
+ *  corrupt file is reported as empty + note — loading never throws.
+ *
+ *  Policy: todo_write is kind "memory" — a disk write of agent-private,
+ *  session-scoped metadata, the same class as memory_edit (BlockStore under
+ *  <session>/memory). core/tools.ts actionFor() maps it to memory.write, which
+ *  the runtime's default gated rules ALLOW (runtime.ts buildCfg), so the list
+ *  never prompts; kind "read" would also auto-run but would let read-only rule
+ *  sets write to disk unseen — the mirror of recall.ts's argument against
+ *  mislabeling kinds. The schemas declare no `path`/`command`, so the policy
+ *  resource is the tool name: `memory.write todo_write` targets it precisely —
+ *  which is how plan mode (modes.ts planModeRules) denies memory.write wholesale
+ *  and then re-allows exactly todo_write: the list is the plan's own artifact
+ *  (agent-private session metadata, not workspace state), while memory_edit,
+ *  file.write and shell.exec stay denied there; todo_read (kind "read" →
+ *  file.read) is always available. Not in checkpoints.ts MUTATING_KINDS, so
+ *  todo writes never trigger snapshots. */
+
+import { mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
+import { basename, join } from "node:path";
+import type { Tool, ToolContext, ToolOutput } from "../core/types.ts";
+
+// ---------- schema ----------
+
+export type TodoStatus = "pending" | "in_progress" | "completed";
+export type TodoPriority = "high" | "medium" | "low";
+export interface TodoItem { id: string; content: string; status: TodoStatus; priority?: TodoPriority }
+
+export const TODO_STATUSES: readonly TodoStatus[] = ["pending", "in_progress", "completed"];
+export const TODO_PRIORITIES: readonly TodoPriority[] = ["high", "medium", "low"];
+export const MAX_TODOS = 50;
+export const MAX_ID_CHARS = 64;
+export const MAX_CONTENT_CHARS = 500;
+export const TODOS_FILE = "todos.json";
+const FILE_VERSION = 1;
+const RENDER_CONTENT_CHARS = 200; // per-line render clip (content is ≤500 on disk; the TUI note stays scannable)
+
+function isStatus(v: unknown): v is TodoStatus { return (TODO_STATUSES as readonly unknown[]).includes(v); }
+function isPriority(v: unknown): v is TodoPriority { return (TODO_PRIORITIES as readonly unknown[]).includes(v); }
+
+/** Bounded echo of a rejected value — a 200k-char status must not reflect into the error. */
+function show(v: unknown): string {
+  let s: string;
+  try { s = JSON.stringify(v) ?? String(v); } catch { s = String(v); }
+  return s.length > 40 ? s.slice(0, 40).replace(/[\uD800-\uDBFF]$/, "") + "…" : s;
+}
+
+export type TodoValidation = { ok: true; items: TodoItem[] } | { ok: false; error: string };
+
+/** Whole-list validation (gemini-cli write-todos.ts:100-129 shape, plus ids and
+ *  bounds). Returns NORMALIZED items — ids/content trimmed, unknown keys
+ *  dropped, `priority` omitted when absent — or the first precise error. */
+export function validateTodos(raw: unknown): TodoValidation {
+  const err = (error: string): TodoValidation => ({ ok: false, error });
+  if (!Array.isArray(raw)) return err("`todos` must be an array of {id, content, status, priority?}");
+  if (raw.length > MAX_TODOS) return err(`too many todos: ${raw.length} (max ${MAX_TODOS})`);
+  const items: TodoItem[] = [];
+  const seen = new Set<string>();
+  const inProgress: string[] = [];
+  for (let i = 0; i < raw.length; i++) {
+    const t: unknown = raw[i];
+    const at = `todos[${i}]`;
+    if (!t || typeof t !== "object" || Array.isArray(t)) return err(`${at} must be an object {id, content, status, priority?}`);
+    const o = t as Record<string, unknown>;
+    if (typeof o.id !== "string" || o.id.trim().length === 0) return err(`${at}.id must be a non-empty string`);
+    const id = o.id.trim();
+    if (id.length > MAX_ID_CHARS) return err(`${at}.id exceeds ${MAX_ID_CHARS} chars`);
+    if (seen.has(id)) return err(`duplicate id "${id}" at ${at} — ids must be unique`);
+    seen.add(id);
+    if (typeof o.content !== "string" || o.content.trim().length === 0) return err(`${at} ("${id}"): content must be a non-empty string`);
+    const content = o.content.trim();
+    if (content.length > MAX_CONTENT_CHARS) return err(`${at} ("${id}"): content exceeds ${MAX_CONTENT_CHARS} chars`);
+    if (!isStatus(o.status)) return err(`${at} ("${id}"): status must be one of ${TODO_STATUSES.join(", ")} (got ${show(o.status)})`);
+    const item: TodoItem = { id, content, status: o.status };
+    if (o.priority !== undefined && o.priority !== null) {
+      if (!isPriority(o.priority)) return err(`${at} ("${id}"): priority must be one of ${TODO_PRIORITIES.join(", ")} (got ${show(o.priority)})`);
+      item.priority = o.priority;
+    }
+    if (item.status === "in_progress") inProgress.push(id);
+    items.push(item);
+  }
+  // gemini-cli write-todos.ts:120-126: only one task can be in_progress at a time
+  if (inProgress.length > 1) return err(`only one todo may be in_progress at a time (found ${inProgress.length}: ${inProgress.join(", ")})`);
+  return { ok: true, items };
+}
+
+// ---------- persistence (<sessionDir>/todos.json) ----------
+
+export interface LoadedTodos { items: TodoItem[]; note?: string }
+
+/** Read the session's list. Missing file = empty (the normal initial state, no
+ *  note). Unreadable / malformed / schema-invalid content = empty + a note
+ *  saying so — never throws; the next todo_write replaces the file. */
+export function loadTodos(sessionDir: string): LoadedTodos {
+  const file = join(sessionDir, TODOS_FILE);
+  const tail = "treating the list as empty; the next todo_write replaces it";
+  let text: string;
+  try {
+    text = readFileSync(file, "utf8");
+  } catch (e) {
+    if ((e as { code?: unknown } | null)?.code === "ENOENT") return { items: [] };
+    return { items: [], note: `${TODOS_FILE} could not be read (${e instanceof Error ? e.message : String(e)}) — ${tail}` };
+  }
+  let raw: unknown;
+  try { raw = JSON.parse(text); } catch { return { items: [], note: `${TODOS_FILE} is not valid JSON — ${tail}` }; }
+  const o = raw && typeof raw === "object" && !Array.isArray(raw) ? (raw as Record<string, unknown>) : null;
+  if (!o || o.version !== FILE_VERSION || !Array.isArray(o.items)) {
+    return { items: [], note: `${TODOS_FILE} has an unexpected shape (expected {version: ${FILE_VERSION}, items: [...]}) — ${tail}` };
+  }
+  const v = validateTodos(o.items);
+  if (!v.ok) return { items: [], note: `${TODOS_FILE} failed validation (${v.error}) — ${tail}` };
+  return { items: v.items };
+}
+
+/** Atomic replace: write `todos.json.tmp`, then rename over the target (session.ts
+ *  persistLeaf). Creates the session dir if needed. IO errors propagate — the
+ *  tool turns them into ok:false. */
+export function saveTodos(sessionDir: string, items: readonly TodoItem[]): void {
+  mkdirSync(sessionDir, { recursive: true });
+  const file = join(sessionDir, TODOS_FILE);
+  const tmp = file + ".tmp";
+  writeFileSync(tmp, JSON.stringify({ version: FILE_VERSION, items }, null, 2) + "\n");
+  renameSync(tmp, file);
+}
+
+/** A session id must be a plain directory name: `<root>/<id>/todos.json` may never
+ *  resolve outside the sessions root (listSessions identity = directory name). */
+function sessionDirFor(root: string, sessionId: string): string | null {
+  // both slashes are refused on every host: a backslash is a legal file-name byte on POSIX, but an id
+  // that would be a path on Windows is not a plain directory name anywhere
+  if (!sessionId || sessionId === "." || sessionId === ".." || /[\\/]/.test(sessionId) || basename(sessionId) !== sessionId) return null;
+  return join(root, sessionId);
+}
+
+// ---------- rendering (pure; shared by tool output and the TUI) ----------
+
+export interface TodoCounts { total: number; pending: number; inProgress: number; completed: number }
+
+export function todoCounts(items: readonly TodoItem[]): TodoCounts {
+  const c: TodoCounts = { total: items.length, pending: 0, inProgress: 0, completed: 0 };
+  for (const t of items) {
+    if (t.status === "completed") c.completed++;
+    else if (t.status === "in_progress") c.inProgress++;
+    else c.pending++;
+  }
+  return c;
+}
+
+const GLYPH: Record<TodoStatus, string> = { pending: "[ ]", in_progress: "[>]", completed: "[x]" };
+
+/** Single-line content: whitespace collapsed, clipped with an ellipsis (surrogate-safe). */
+function oneLine(text: string): string {
+  const flat = text.replace(/\s+/g, " ").trim();
+  return flat.length > RENDER_CONTENT_CHARS
+    ? flat.slice(0, RENDER_CONTENT_CHARS).replace(/[\uD800-\uDBFF]$/, "") + "…"
+    : flat;
+}
+
+/** Checkbox rendering: a summary line, then one `[glyph] id: content (priority)`
+ *  row per item in list order. Bounded: ≤MAX_TODOS rows, content clipped, and the
+ *  id flattened too (a trimmed id may still carry an inner newline — one row per item). */
+export function renderTodos(items: readonly TodoItem[]): string {
+  if (items.length === 0) return "todos: (empty)";
+  const c = todoCounts(items);
+  const lines = [`todos: ${c.total} total · ${c.completed} completed · ${c.inProgress} in progress · ${c.pending} pending`];
+  for (const t of items.slice(0, MAX_TODOS)) {
+    lines.push(`${GLYPH[t.status]} ${oneLine(t.id)}: ${oneLine(t.content)}${t.priority ? ` (${t.priority})` : ""}`);
+  }
+  if (items.length > MAX_TODOS) lines.push(`(+${items.length - MAX_TODOS} more not shown)`);
+  return lines.join("\n");
+}
+
+/** The re-send the loop makes while a plan is open (loop.ts LoopDeps.planReminder).
+ *
+ *  A list written twenty turns ago is buried under tool results: the model stops marking items done,
+ *  starts a second item without finishing the first, or forgets the tail of the plan entirely. This is
+ *  the same shape as the tool's own output, plus the one instruction that matters right now — so the
+ *  plan is always the most recent thing in the request, not the oldest.
+ *
+ *  null when there is nothing to chase (no list, or everything completed): a finished plan must not
+ *  keep nagging, and an empty one has nothing to say. */
+export function planReminder(items: readonly TodoItem[]): string | null {
+  const c = todoCounts(items);
+  if (c.total === 0 || c.completed === c.total) return null;
+  return [
+    "<plan-reminder>",
+    "Your own todo list for this task, still open — not a message from the user.",
+    renderTodos(items),
+    c.inProgress === 0
+      ? "Nothing is in progress. Mark the next item in_progress with todo_write before you start it."
+      : "Mark the in_progress item completed with todo_write the moment it is done, then start the next one.",
+    "Rewrite the list if the plan changed. Never mention this reminder in your reply.",
+    "</plan-reminder>",
+  ].join("\n");
+}
+
+/** Status-bar label, e.g. "todos 1/3" (completed/total); "" when the list is empty. */
+export function todoStatusLabel(items: readonly TodoItem[]): string {
+  if (items.length === 0) return "";
+  const c = todoCounts(items);
+  return `todos ${c.completed}/${c.total}`;
+}
+
+// ---------- tools ----------
+
+const WRITE_DESCRIPTION =
+  "Create or update this session's structured todo list (your plan). REPLACES the whole list: send every item " +
+  `you want kept — items {id, content, status, priority?}; at most ${MAX_TODOS} items, ids unique and non-empty ` +
+  `(≤${MAX_ID_CHARS} chars), content non-empty (≤${MAX_CONTENT_CHARS} chars). Statuses: pending | in_progress ` +
+  "(exactly ONE at a time) | completed. Priority: high | medium | low (optional). An invalid list is rejected whole " +
+  "and nothing changes; an empty list clears the todos. Use proactively when: the task needs 3+ distinct steps; the " +
+  "work is non-trivial and benefits from planning; the user gives multiple tasks or asks for a todo list; new " +
+  "instructions arrive (capture them as todos); you start a step (mark it in_progress first) or finish one (mark it " +
+  "completed only once the work, including verification, is actually done — never on intent; add follow-ups " +
+  "discovered on the way). Skip it for a single straightforward task, a purely informational request, or when " +
+  "tracking adds no value. Update in real time — don't batch completions. When in doubt, use it.";
+
+const READ_DESCRIPTION =
+  "Read this session's todo list as last written by todo_write: ids, content, status, priority. Use it to get the " +
+  "current ids before updating the list, or to check what remains. Empty until todo_write creates a list.";
+
+const itemSchema = {
+  type: "object",
+  properties: {
+    id: { type: "string", description: `stable short id, unique within the list (e.g. "t1"); ≤${MAX_ID_CHARS} chars` },
+    content: { type: "string", description: `brief, specific, actionable description of the task; ≤${MAX_CONTENT_CHARS} chars` },
+    status: { type: "string", enum: [...TODO_STATUSES], description: "pending | in_progress (exactly one at a time) | completed" },
+    priority: { type: "string", enum: [...TODO_PRIORITIES], description: "optional priority" },
+  },
+  required: ["id", "content", "status"],
+};
+
+/** `todo_write` bound to a sessions root; the list lives at <root>/<ctx.sessionId>/todos.json. */
+export function todoWriteTool(sessionsRoot: string): Tool {
+  return {
+    schema: {
+      name: "todo_write",
+      description: WRITE_DESCRIPTION,
+      args: {
+        type: "object",
+        properties: {
+          todos: { type: "array", description: "the complete, updated todo list (replaces the current one)", maxItems: MAX_TODOS, items: itemSchema },
+        },
+        required: ["todos"],
+      },
+    },
+    kind: "memory",
+    sequential: true,
+    execute(args: unknown, ctx: ToolContext): Promise<ToolOutput> {
+      const dir = sessionDirFor(sessionsRoot, ctx.sessionId);
+      if (!dir) return Promise.resolve({ ok: false, output: `todo_write failed: invalid session id ${show(ctx.sessionId)}` });
+      // keep ONLY the schema arg (recall.ts idiom): smuggled keys never influence behavior
+      const raw = (args && typeof args === "object" ? args : {}) as Record<string, unknown>;
+      const v = validateTodos(raw.todos);
+      if (!v.ok) return Promise.resolve({ ok: false, output: `todo_write failed: ${v.error}; the list was not changed` });
+      try {
+        saveTodos(dir, v.items);
+      } catch (e) {
+        return Promise.resolve({ ok: false, output: `todo_write failed: could not write ${TODOS_FILE}: ${e instanceof Error ? e.message : String(e)}` });
+      }
+      // gemini write-todos.ts:52/:68 wording for the clear case; otherwise the checkbox view
+      const output = v.items.length === 0 ? "Cleared todo list." : renderTodos(v.items);
+      return Promise.resolve({ ok: true, output, data: { items: v.items } });
+    },
+  };
+}
+
+/** `todo_read` bound to the same root. Pure read (kind "read"): never creates the file. */
+export function todoReadTool(sessionsRoot: string): Tool {
+  return {
+    schema: {
+      name: "todo_read",
+      description: READ_DESCRIPTION,
+      args: { type: "object", properties: {} },
+    },
+    kind: "read",
+    sequential: false,
+    execute(_args: unknown, ctx: ToolContext): Promise<ToolOutput> {
+      const dir = sessionDirFor(sessionsRoot, ctx.sessionId);
+      if (!dir) return Promise.resolve({ ok: false, output: `todo_read failed: invalid session id ${show(ctx.sessionId)}` });
+      const { items, note } = loadTodos(dir);
+      if (items.length === 0) {
+        const head = note ? `${note}\n` : "";
+        return Promise.resolve({ ok: true, output: `${head}No todos for this session yet — use todo_write to create a list.`, data: { items, ...(note ? { note } : {}) } });
+      }
+      return Promise.resolve({ ok: true, output: renderTodos(items), data: { items } });
+    },
+  };
+}
+
+/** Both tools over one sessions root — the runtime registration unit. */
+export function todoTools(sessionsRoot: string): Tool[] {
+  return [todoWriteTool(sessionsRoot), todoReadTool(sessionsRoot)];
+}

package/src/tools/webfetch.ts

@@ -0,0 +1,331 @@
+/** web_fetch tool (PORT #31): bounded, SSRF-guarded GET → readable text.
+ *  Ported from opencode (MIT, snapshot ebece6e, packages/opencode/src/tool/
+ *  webfetch.ts): url arg + http/https scheme gate (:35-37), 30s default timeout
+ *  (:10), response size cap via content-length + body (:96-104), content-type →
+ *  mime split (:106-107), html-vs-passthrough branch (:129-152). SSRF handling
+ *  follows gemini-cli (Apache-2.0, snapshot 0bd1d43): localhost/private host
+ *  block BEFORE any request (packages/core/src/tools/web-fetch.ts:270-281,
+ *  :618-631), resolve-then-check over ALL addresses (packages/core/src/utils/
+ *  fetch.ts:150-169), IPv4-mapped unmapping + the 198.18/15 benchmark range
+ *  (fetch.ts:94-145), timer-driven AbortController linked to the caller's signal
+ *  (fetch.ts:190-230), streamed read under a byte limit (web-fetch.ts:555-587),
+ *  per-mime handling (web-fetch.ts:686-721).
+ *  Deviations: redirects are followed MANUALLY (≤5 hops) so the guard re-runs
+ *  on every hop — upstreams let fetch follow them, the classic redirect-to-
+ *  127.0.0.1 bypass — and only while the host stays the same: policy consented
+ *  to net.fetch on the ORIGINAL host, so a hop to another host stops with the
+ *  target URL for the model to fetch directly (its own policy decision);
+ *  ipaddr.js / html-to-text / htmlparser2 are replaced by the ~50 lines of
+ *  address parsing below and html-text.ts; the byte cap TRUNCATES with a marker
+ *  instead of failing; no LLM pass, retries or rate limiter. The timeout covers
+ *  the DNS phase too (the guard's lookup is raced against the controller).
+ *  Known gap: DNS is resolved once for the guard and again inside fetch
+ *  (rebinding TOCTOU); pinning the socket to the checked address needs a
+ *  dispatcher hook Bun's fetch does not expose.
+ *  Policy: kind "network" → action net.fetch, resource = canonical URL host
+ *  (core/tools.ts hostOf); runtime.ts buildCfg makes it PROMPT by default.
+ *  Env: ROVECODE_WEBFETCH_TIMEOUT_MS (default 30000), ROVECODE_WEBFETCH_ALLOW_PRIVATE=1
+ *  (skip the private-address guard, for local dev servers). */
+
+import { lookup } from "node:dns/promises";
+import type { Tool, ToolContext, ToolOutput } from "../core/types.ts";
+import { htmlToText } from "./html-text.ts";
+
+// ---------- bounds (advertised in the schema; args are clamped, never trusted) ----------
+
+export const MAX_BYTES = 512 * 1024;       // body bytes read before truncation
+export const CHARS_DEFAULT = 50_000;       // text chars returned by default
+export const CHARS_CAP = 250_000;          // ceiling for maxChars (gemini-cli MAX_CONTENT_LENGTH)
+export const MAX_REDIRECTS = 5;
+export const TIMEOUT_DEFAULT_MS = 30_000;  // opencode DEFAULT_TIMEOUT
+const USER_AGENT = "Mozilla/5.0 (compatible; rovecode/0.2 web_fetch)";
+const ACCEPT = "text/html, application/xhtml+xml, application/json;q=0.9, text/*;q=0.8, application/xml;q=0.7, */*;q=0.1";
+
+/** files.ts clampLimit contract: ceiling CHARS_CAP; absent/NaN/non-positive → default; fractions floor. */
+export function clampChars(v: number | undefined): number {
+  return Number.isFinite(v) && v! > 0 ? Math.min(Math.floor(v!), CHARS_CAP) : CHARS_DEFAULT;
+}
+function timeoutMs(): number {
+  const v = Number(process.env.ROVECODE_WEBFETCH_TIMEOUT_MS ?? "");
+  return Number.isFinite(v) && v > 0 ? Math.floor(v) : TIMEOUT_DEFAULT_MS;
+}
+
+// ---------- SSRF guard: address classification ----------
+
+function parseIPv4(s: string): number | null {
+  const m = /^(\d{1,3})\.(\d{1,3})\.(\d{1,3})\.(\d{1,3})$/.exec(s);
+  if (!m) return null;
+  let n = 0;
+  for (let i = 1; i <= 4; i++) { const o = Number(m[i]); if (o > 255) return null; n = (n << 8) | o; }
+  return n >>> 0;
+}
+
+/** 8 × 16-bit groups, or null when not an IPv6 literal. Handles `::`, an embedded
+ *  dotted IPv4 tail (::ffff:10.0.0.1) and zone ids (fe80::1%eth0). */
+function parseIPv6(input: string): number[] | null {
+  const s = input.includes("%") ? input.slice(0, input.indexOf("%")) : input;
+  if (!/^[0-9a-fA-F:.]+$/.test(s) || !s.includes(":")) return null;
+  const halves = s.split("::");
+  if (halves.length > 2) return null;
+  const groups = (part: string): number[] | null => {
+    if (part === "") return [];
+    const g: number[] = [];
+    for (const piece of part.split(":")) {
+      if (piece.includes(".")) { const v4 = parseIPv4(piece); if (v4 === null) return null; g.push(v4 >>> 16, v4 & 0xffff); }
+      else if (/^[0-9a-fA-F]{1,4}$/.test(piece)) g.push(parseInt(piece, 16));
+      else return null;
+    }
+    return g;
+  };
+  const head = groups(halves[0]!);
+  const tail = halves.length === 2 ? groups(halves[1]!) : [];
+  if (!head || !tail) return null;
+  const fill = 8 - head.length - tail.length;
+  if (halves.length === 2 ? fill < 1 : fill !== 0) return null;
+  return [...head, ...(new Array<number>(fill).fill(0)), ...tail];
+}
+
+/** Non-global IPv4 space: RFC 1918, loopback, link-local (incl. 169.254.169.254
+ *  metadata), "this" network, CGNAT, IETF/TEST-NETs, benchmarking, multicast, reserved. */
+const V4_BLOCKED: [number, number][] = ([
+  ["0.0.0.0", 8], ["10.0.0.0", 8], ["100.64.0.0", 10], ["127.0.0.0", 8], ["169.254.0.0", 16], ["172.16.0.0", 12],
+  ["192.0.0.0", 24], ["192.0.2.0", 24], ["192.168.0.0", 16], ["198.18.0.0", 15], ["198.51.100.0", 24],
+  ["203.0.113.0", 24], ["224.0.0.0", 4], ["240.0.0.0", 4],
+] as [string, number][]).map(([p, bits]) => [parseIPv4(p)!, bits]);
+function v4Blocked(n: number): boolean {
+  return V4_BLOCKED.some(([p, bits]) => (n >>> (32 - bits)) === (p >>> (32 - bits)));
+}
+
+/** True for any address a fetch must not reach: loopback, private, link-local,
+ *  unspecified, multicast/reserved, IPv4-mapped/6to4 forms of those, and anything
+ *  outside IPv6 global unicast (2000::/3). Unparseable input is treated as
+ *  private (fail closed). */
+export function isPrivateAddress(ip: string): boolean {
+  const v4 = parseIPv4(ip);
+  if (v4 !== null) return v4Blocked(v4);
+  const g = parseIPv6(ip);
+  if (!g) return true;
+  const [g0, g1, g2, g3, g4, g5, g6, g7] = g as [number, number, number, number, number, number, number, number];
+  if (g0 === 0 && g1 === 0 && g2 === 0 && g3 === 0 && g4 === 0 && g5 === 0xffff) return v4Blocked(((g6 << 16) | g7) >>> 0); // ::ffff:a.b.c.d
+  if ((g0 & 0xe000) !== 0x2000) return true; // ::, ::1, fc00::/7, fe80::/10, ff00::/8, 64:ff9b::/96, 100::/64 …
+  if (g0 === 0x2002) return v4Blocked(((g1 << 16) | g2) >>> 0); // 6to4 embeds an IPv4
+  return g0 === 0x2001 && g1 === 0x0db8; // documentation prefix
+}
+
+/** Resolver seam: every address a host maps to (default node:dns lookup, all: true). */
+export type Resolver = (host: string) => Promise<string[]>;
+export const dnsResolver: Resolver = async (host) => (await lookup(host, { all: true })).map((a) => a.address);
+export type FetchLike = (url: string, init: RequestInit) => Promise<Response>;
+
+/** Guard host form: brackets and trailing dot stripped, lowercased. */
+export function canonicalHost(hostname: string): string {
+  let h = hostname.toLowerCase();
+  if (h.startsWith("[") && h.endsWith("]")) h = h.slice(1, -1);
+  return h.endsWith(".") ? h.slice(0, -1) : h;
+}
+
+/** null when the host may be fetched; otherwise the reason it is refused. Literal
+ *  IPs and localhost names never touch DNS; names are resolved and refused when
+ *  ANY address is private (gemini-cli fetch.ts:159-160). */
+export async function ssrfDenyReason(hostname: string, resolve: Resolver): Promise<string | null> {
+  const host = canonicalHost(hostname);
+  const kind = "a private, loopback, link-local or reserved address";
+  if (host === "") return "empty host";
+  if (host === "localhost" || host.endsWith(".localhost")) return `${host} is a loopback name`;
+  if (parseIPv4(host) !== null || host.includes(":")) return isPrivateAddress(host) ? `${host} is ${kind}` : null;
+  let addrs: string[];
+  try { addrs = await resolve(host); } catch (e) { return `could not resolve ${host}: ${e instanceof Error ? e.message : String(e)}`; }
+  if (addrs.length === 0) return `could not resolve ${host}`;
+  const bad = addrs.find(isPrivateAddress);
+  return bad === undefined ? null : `${host} resolves to ${bad}, ${kind}`;
+}
+
+// ---------- response handling ----------
+
+const REDIRECT_STATUSES = new Set([301, 302, 303, 307, 308]);
+
+function isTextual(mime: string): boolean {
+  return mime === "" || mime.startsWith("text/") || mime === "application/json" || mime === "application/xml"
+    || mime === "application/xhtml+xml" || mime === "application/javascript" || mime === "application/ecmascript"
+    || mime.endsWith("+json") || mime.endsWith("+xml");
+}
+function looksLikeHtml(mime: string, text: string): boolean {
+  if (mime === "text/html" || mime === "application/xhtml+xml") return true;
+  return mime === "" && /^\s*<(!doctype\s+html|html|head|body)[\s>]/i.test(text.slice(0, 1024));
+}
+
+/** Rejects as soon as `signal` aborts, so a phase that is not itself abortable
+ *  (the guard's DNS lookup) cannot outlive the tool's timeout or the user's Esc. */
+function abortable<T>(p: Promise<T>, signal: AbortSignal): Promise<T> {
+  if (signal.aborted) return Promise.reject(new Error("aborted"));
+  return new Promise<T>((resolve, reject) => {
+    const onAbort = (): void => reject(new Error("aborted"));
+    signal.addEventListener("abort", onAbort, { once: true });
+    p.then(resolve, reject).finally(() => signal.removeEventListener("abort", onAbort));
+  });
+}
+
+/** Streams the body up to `cap` bytes, then cancels the stream (gemini-cli
+ *  web-fetch.ts:568-585 loop, truncating instead of throwing). An abort mid-body
+ *  rejects out of reader.read() and is handled by the caller. */
+async function readBounded(res: Response, cap: number): Promise<{ bytes: Uint8Array; truncated: boolean }> {
+  if (!res.body) return { bytes: new Uint8Array(0), truncated: false };
+  const reader = res.body.getReader();
+  const chunks: Uint8Array[] = [];
+  let total = 0;
+  let truncated = false;
+  try {
+    for (;;) {
+      const { done, value } = await reader.read();
+      if (done) break;
+      if (value.length === 0) continue; // an empty chunk carries no bytes: not overflow even at the cap
+      if (total >= cap) { truncated = true; break; }
+      const room = cap - total;
+      if (value.length > room) { chunks.push(value.subarray(0, room)); total = cap; truncated = true; break; }
+      chunks.push(value);
+      total += value.length;
+    }
+  } finally {
+    await reader.cancel().catch(() => {});
+  }
+  const bytes = new Uint8Array(total);
+  let off = 0;
+  for (const c of chunks) { bytes.set(c, off); off += c.length; }
+  return { bytes, truncated };
+}
+
+function decodeBody(bytes: Uint8Array, contentType: string, truncated: boolean): string {
+  const charset = /charset=["']?([\w.:-]+)/i.exec(contentType)?.[1];
+  let decoder: TextDecoder;
+  try { decoder = new TextDecoder(charset ?? "utf-8"); } catch { decoder = new TextDecoder(); }
+  const text = decoder.decode(bytes);
+  return truncated ? text.replace(/�$/, "") : text; // a cut mid-sequence leaves one replacement char
+}
+
+export interface WebFetchDeps { fetch?: FetchLike; resolve?: Resolver }
+
+/** Builds the tool; `deps` are test seams (fixture-mapping fetch, scripted resolver).
+ *  Production registrations use the module-level webFetchTool. */
+export function createWebFetchTool(deps: WebFetchDeps = {}): Tool {
+  const fetchImpl: FetchLike = deps.fetch ?? ((u, i) => fetch(u, i));
+  const resolve: Resolver = deps.resolve ?? dnsResolver;
+
+  async function run(a: { url: string; maxChars?: number }, ctx: ToolContext): Promise<ToolOutput> {
+    if (typeof a.url !== "string" || a.url.trim() === "") return { ok: false, output: "web_fetch: url is required" };
+    let current: URL;
+    try { current = new URL(a.url.trim()); } catch { return { ok: false, output: `web_fetch: invalid URL: ${a.url}` }; }
+    const maxChars = clampChars(a.maxChars);
+    const allowPrivate = process.env.ROVECODE_WEBFETCH_ALLOW_PRIVATE === "1";
+    if (ctx.signal.aborted) return { ok: false, output: "web_fetch: aborted" };
+
+    // Timeout: a REF'D setTimeout drives the controller (Bun's AbortSignal.timeout
+    // timer is unref'd and never fires on an idle loop — see executor.ts trialSpawn);
+    // the caller's signal is chained so Esc mid-fetch aborts the socket too.
+    const ac = new AbortController();
+    const limitMs = timeoutMs();
+    let timedOut = false;
+    const timer = setTimeout(() => { timedOut = true; ac.abort(); }, limitMs);
+    (timer as unknown as { ref?: () => void }).ref?.();
+    const onAbort = (): void => ac.abort();
+    ctx.signal.addEventListener("abort", onAbort, { once: true });
+    const fail = (e: unknown): ToolOutput => {
+      if (ac.signal.aborted) return { ok: false, output: timedOut ? `web_fetch: timed out after ${limitMs}ms` : "web_fetch: aborted" };
+      return { ok: false, output: `web_fetch: request failed: ${e instanceof Error ? e.message : String(e)}` };
+    };
+
+    try {
+      let hops = 0;
+      const origin = canonicalHost(current.hostname);
+      for (;;) {
+        // scheme + SSRF gate on the initial URL AND every redirect target
+        if (current.protocol !== "http:" && current.protocol !== "https:") {
+          return { ok: false, output: `web_fetch: unsupported URL scheme ${current.protocol} (http/https only)` };
+        }
+        if (!allowPrivate) {
+          let reason: string | null;
+          try { reason = await abortable(ssrfDenyReason(current.hostname, resolve), ac.signal); } catch (e) { return fail(e); }
+          if (reason !== null) {
+            return { ok: false, output: `web_fetch: refused ${current.href}: ${reason} (set ROVECODE_WEBFETCH_ALLOW_PRIVATE=1 for local dev servers)` };
+          }
+        }
+        // Policy consented to net.fetch on the host of the ORIGINAL url only
+        // (core/tools.ts hostOf), so a redirect to a different host is not
+        // followed: the target is reported for a direct fetch that gets its own
+        // decision. Checked AFTER the guard so a private target keeps its precise
+        // refusal instead of advice to fetch it. Same canonical host (case and
+        // trailing dot ignored, any port) still follows, so http→https upgrades
+        // and path moves stay seamless.
+        const host = canonicalHost(current.hostname);
+        if (host !== origin) {
+          return { ok: false, output: `web_fetch: redirected to ${current.href}; fetch it directly (a redirect from ${origin} to ${host} needs its own net.fetch permission)` };
+        }
+        let res: Response;
+        try {
+          res = await fetchImpl(current.href, { method: "GET", redirect: "manual", signal: ac.signal, headers: { "User-Agent": USER_AGENT, Accept: ACCEPT } });
+        } catch (e) { return fail(e); }
+
+        if (REDIRECT_STATUSES.has(res.status)) {
+          const location = res.headers.get("location");
+          await res.body?.cancel().catch(() => {});
+          if (!location) return { ok: false, output: `web_fetch: HTTP ${res.status} redirect from ${current.href} without a Location header` };
+          if (++hops > MAX_REDIRECTS) return { ok: false, output: `web_fetch: too many redirects (more than ${MAX_REDIRECTS}) starting from ${a.url}` };
+          try { current = new URL(location, current); } catch { return { ok: false, output: `web_fetch: invalid redirect target ${location}` }; }
+          continue;
+        }
+
+        const contentType = res.headers.get("content-type") ?? "";
+        const mime = (contentType.split(";")[0] ?? "").trim().toLowerCase();
+        if (!isTextual(mime)) {
+          await res.body?.cancel().catch(() => {}); // gate BEFORE the body is read
+          return { ok: false, output: `web_fetch: unsupported content-type: ${mime} (only text/*, JSON, XML and XHTML are fetched)` };
+        }
+        let body: { bytes: Uint8Array; truncated: boolean };
+        try { body = await readBounded(res, MAX_BYTES); } catch (e) { return fail(e); }
+        const raw = decodeBody(body.bytes, contentType, body.truncated);
+        let text = looksLikeHtml(mime, raw) ? htmlToText(raw, current.href) : raw;
+
+        const notes: string[] = [];
+        if (body.truncated) {
+          const declared = Number(res.headers.get("content-length"));
+          notes.push(`(Body truncated at ${MAX_BYTES} bytes${Number.isFinite(declared) && declared > 0 ? ` of ${declared}` : ""}.)`);
+        }
+        const totalChars = text.length;
+        const charsTruncated = totalChars > maxChars;
+        if (charsTruncated) {
+          text = text.slice(0, maxChars).replace(/[\uD800-\uDBFF]$/, "");
+          notes.push(`(Text truncated: showing first ${maxChars} of ${totalChars} characters.)`);
+        }
+        const header = `${current.href} (HTTP ${res.status}, ${mime || "no content-type"}, ${body.bytes.length} bytes${hops > 0 ? `, ${hops} redirect${hops === 1 ? "" : "s"}` : ""})`;
+        const output = [header, text, ...(notes.length > 0 ? [notes.join("\n")] : [])].filter((s) => s !== "").join("\n\n");
+        return {
+          ok: res.status < 400,
+          output,
+          data: { url: current.href, status: res.status, contentType: mime, bytes: body.bytes.length, redirects: hops, truncated: body.truncated || charsTruncated },
+        };
+      }
+    } finally {
+      clearTimeout(timer);
+      ctx.signal.removeEventListener("abort", onAbort);
+    }
+  }
+
+  return {
+    schema: {
+      name: "web_fetch",
+      description: `Fetch a public http(s) URL with GET and return its content as readable text. HTML is reduced to text (scripts/styles dropped, headings/paragraphs/lists kept, links as "text (href)"); JSON, XML and plain text pass through unchanged. Follows at most ${MAX_REDIRECTS} redirects, and only within the same host: a redirect to another host stops with that URL — fetch it directly. Only text/*, JSON, XML and XHTML responses are accepted. The body is read up to ${MAX_BYTES} bytes and the text is capped at maxChars (default ${CHARS_DEFAULT}, cap ${CHARS_CAP}); both truncations leave a marker. Times out after ${TIMEOUT_DEFAULT_MS / 1000}s. Private, loopback, link-local and unresolvable hosts are refused. Output starts with a header line: final URL, HTTP status, content-type, bytes read.`,
+      args: {
+        type: "object",
+        properties: {
+          url: { type: "string", description: "absolute http:// or https:// URL to fetch" },
+          maxChars: { type: "integer", description: `max characters of text returned (default ${CHARS_DEFAULT}, cap ${CHARS_CAP})` },
+        },
+        required: ["url"],
+      },
+    },
+    kind: "network",
+    sequential: false,
+    execute: (args, ctx) => run((args ?? {}) as { url: string; maxChars?: number }, ctx),
+  };
+}
+
+export const webFetchTool: Tool = createWebFetchTool();