rovecode 0.3.2

package/src/tools/evalcell.ts

@@ -0,0 +1,338 @@
+/**
+ * PORT #18 — persistent eval cell, feature-flagged (ROVECODE_EVAL_CELL=1).
+ *
+ * Concept sources (research/source_snapshots):
+ *   - OMP (can1357-oh-my-pi), MIT — persistent eval cells:
+ *       docs/tools/eval.md:3 ("one tool call is one cell; state survives later calls"),
+ *       :108 ("Persistent worker VM keyed by js:${sessionId}"; reset recreates the VM),
+ *       :179 ("Cancellation is destructive when needed: JS terminates its worker"),
+ *       :185 (output window byte budget), :65 ("(no output)" placeholder).
+ *     packages/coding-agent/src/eval/js/shared/indirect-eval.ts:13-23 — user code runs
+ *       through *indirect* `globalThis.eval` (global scope), deliberately NOT node:vm:
+ *       Bun SIGTRAPs when Worker.terminate() fires mid-vm.runInContext — and terminate
+ *       is exactly our timeout path.
+ *     packages/coding-agent/src/eval/js/worker-core.ts:279-308 — run/result message
+ *       protocol; execution errors become result payloads, never worker throws.
+ *     packages/coding-agent/src/eval/js/shared/rewrite-imports.ts:531-550 — TS strip +
+ *       async wrapping (docs/tools/eval.md:110). Simplified here: Bun.Transpiler with
+ *       deadCodeElimination:false (keeps the trailing expression), thenable completion
+ *       values awaited, and one async-IIFE retry at whichever stage rejects bare
+ *       top-level forms (enables top-level await / bare return; declarations in the
+ *       wrapped path are cell-local):
+ *         - transpile stage: the transpiler parses cells as ES modules, so bare
+ *           `return` is a BuildMessage error there — retry transpiling the ORIGINAL
+ *           source wrapped (types still strip); if that also fails, rethrow the first
+ *           error so diagnostics point at the unwrapped code;
+ *         - eval stage: top-level `await` is module-legal but eval-illegal
+ *           (SyntaxError) — retry evaluating the transpiled js wrapped.
+ *   - prime-agent RLM single-REPL concept: prime-agent-runtime/src/rlm/repl.md:3-5
+ *       (cells execute "in one persistent __main__ namespace" per session), :53-55
+ *       (result = repr of the trailing expression), repl.py. BLUEPRINT rejects the
+ *       Python kernel, so this is the TS-only analog: one Bun Worker per session.
+ *
+ * Ouroboros rule — what cell code CAN see:
+ *   - Standard Bun Worker realm globals: Bun, fetch, process (including the inherited
+ *     process.env — same trust level as the bash tool's child shell), timers, require.
+ *     This is NOT a security sandbox; the "execute" policy gate (deny-default → prompt)
+ *     is the control, exactly like bash.
+ *   - Bootstrap additions to the global scope: the six console methods are replaced
+ *     with capture stubs, and `self.onmessage` holds the (secret-free) runner.
+ *     Everything else lives in the bootstrap IIFE's closure, unreachable from cell
+ *     code, which evaluates via indirect eval in the worker's global scope.
+ *   What is NOT pre-exposed (a non-exposure claim, NOT unreachability): nothing from
+ *   the rovecode module graph is imported into or handed to the worker — it loads only
+ *   this inline bootstrap blob, so the tool registry (v1 deliberately has NO tool
+ *   re-entry bridge — scope note), session stores, permission/approval machinery,
+ *   and the graders under src/eval/* stay live only in the host process, and the
+ *   only traffic across the seam is {id, code} in and {id, ok, stdout, value, error}
+ *   out via postMessage. Cell code CAN still `await import()` or Bun.file-read any
+ *   file on disk (src/** included) exactly like the bash tool can run `bun -e` —
+ *   the execute-kind policy gate is the control there, not the worker boundary.
+ *
+ * Lifecycle: worker per ctx.sessionId, created lazily, unref'd so it never holds the
+ * host process open. Cell errors keep the worker (state survives); timeout/abort/reset
+ * terminate it and the session's cell state is lost (reported in the output). An
+ * uncaught BACKGROUND error (timer throw / unhandled rejection firing the worker
+ * "error" event, possibly with no call in flight) also kills the worker; the reason is
+ * parked in `crashed` and the next call's output is prefixed with a crash note, so a
+ * fresh cell never silently contradicts "state survives". A cell that kills its own
+ * worker cleanly (e.g. process.exit()) fires no error event and surfaces as a timeout
+ * on a later call.
+ */
+
+import type { Tool, ToolContext, ToolOutput } from "../core/types.ts";
+
+export const EVAL_CELL_FLAG = "ROVECODE_EVAL_CELL";
+
+const DEFAULT_TIMEOUT_MS = 10_000;
+const MIN_TIMEOUT_MS = 50;
+const MAX_TIMEOUT_MS = 120_000;
+const DEFAULT_OUTPUT_BYTES = 16_384;
+const MIN_OUTPUT_BYTES = 256;
+const MAX_OUTPUT_BYTES = 65_536;
+
+/** Self-contained worker bootstrap (plain JS, no imports — see ouroboros note above).
+ *  Hard caps inside the worker bound postMessage payloads; the model-facing byte
+ *  budget is enforced host-side by truncateToBudget. */
+const BOOTSTRAP = `
+(() => {
+  "use strict";
+  const MAX_CAPTURE = 1048576;
+  const MAX_VALUE = 262144;
+  const transpiler = new Bun.Transpiler({ loader: "ts", deadCodeElimination: false });
+  let buf = [];
+  let bufLen = 0;
+  let capped = false;
+  const fmt = (v) => (typeof v === "string" ? v : Bun.inspect(v));
+  const capture = (...parts) => {
+    if (capped) return;
+    const line = parts.map(fmt).join(" ") + "\\n";
+    bufLen += line.length;
+    if (bufLen > MAX_CAPTURE) { capped = true; buf.push("[console capture cap reached]\\n"); return; }
+    buf.push(line);
+  };
+  for (const k of ["log", "info", "warn", "error", "debug", "trace"]) console[k] = capture;
+  self.onmessage = async (ev) => {
+    const { id, code } = ev.data;
+    buf = []; bufLen = 0; capped = false;
+    let ok = true; let value = ""; let error = "";
+    try {
+      // Bare top-level return is illegal in a module, so it fails at TRANSPILE time
+      // (BuildMessage), before eval — retry with the original source async-wrapped.
+      // If the wrapped transpile fails too, the code is genuinely broken: rethrow the
+      // FIRST error so diagnostics describe the unwrapped source.
+      let js; let preWrapped = false;
+      try {
+        js = transpiler.transformSync(code);
+      } catch (e1) {
+        try { js = transpiler.transformSync("(async () => {\\n" + code + "\\n})()"); preWrapped = true; }
+        catch { throw e1; }
+      }
+      let v;
+      try {
+        v = (0, eval)(js);
+      } catch (e) {
+        // Top-level await is module-legal but a SyntaxError in plain eval; retry
+        // wrapped (OMP docs/tools/eval.md:110). Declarations in wrapped paths
+        // (either stage) are cell-local.
+        if (!preWrapped && e instanceof SyntaxError) v = (0, eval)("(async () => {\\n" + js + "\\n})()");
+        else throw e;
+      }
+      if (v && (typeof v === "object" || typeof v === "function") && typeof v.then === "function") v = await v;
+      if (v !== undefined) {
+        value = Bun.inspect(v);
+        if (value.length > MAX_VALUE) value = value.slice(0, MAX_VALUE) + "...[value capped]";
+      }
+    } catch (e) {
+      ok = false;
+      error = e instanceof Error ? e.name + ": " + e.message : String(e);
+    }
+    postMessage({ id, ok, stdout: buf.join(""), value, error });
+  };
+  postMessage({ type: "ready" });
+})();
+`;
+
+interface WorkerResult { id: number; ok: boolean; stdout: string; value: string; error: string }
+
+interface CellRuntime {
+  worker: Worker;
+  pending: Map<number, (r: WorkerResult) => void>;
+  ready: Promise<void>;
+}
+
+const cells = new Map<string, CellRuntime>();
+/** Reasons from worker "error" events (background timer throws / unhandled
+ *  rejections), parked per session: with no call in flight destroyCell has nobody
+ *  to tell, so the NEXT call consumes the reason and explains its fresh cell. */
+const crashed = new Map<string, string>();
+let callSeq = 0;
+let bootstrapUrl: string | null = null;
+
+/** Bun's ErrorEvent.message is a multi-line source excerpt + stack; condense to the
+ *  `error: …` line (or a flattened whole) so crash notes stay one line. */
+function crashReason(raw: string): string {
+  const lines = raw.split("\n").map((l) => l.trim()).filter((l) => l !== "");
+  const flat = (lines.find((l) => /^\w*[Ee]rror:/.test(l)) ?? lines.join(" ")).replace(/\s+/g, " ");
+  return flat === "" ? "unknown worker error" : flat.length > 200 ? flat.slice(0, 200) + "…" : flat;
+}
+
+function urlForBootstrap(): string {
+  if (bootstrapUrl === null) {
+    bootstrapUrl = URL.createObjectURL(new Blob([BOOTSTRAP], { type: "application/javascript" }));
+  }
+  return bootstrapUrl;
+}
+
+function spawnCell(sessionId: string): CellRuntime {
+  const worker = new Worker(urlForBootstrap());
+  const pending = new Map<number, (r: WorkerResult) => void>();
+  let readyResolve: () => void = () => {};
+  const ready = new Promise<void>((res) => { readyResolve = res; });
+  const runtime: CellRuntime = { worker, pending, ready };
+  worker.addEventListener("message", (ev: MessageEvent) => {
+    const d = ev.data as { type?: string } & Partial<WorkerResult>;
+    if (d.type === "ready") { readyResolve(); return; }
+    if (typeof d.id !== "number") return;
+    const cb = pending.get(d.id);
+    if (cb) {
+      pending.delete(d.id);
+      cb({ id: d.id, ok: d.ok === true, stdout: d.stdout ?? "", value: d.value ?? "", error: d.error ?? "" });
+    }
+  });
+  worker.addEventListener("error", (ev) => {
+    const msg = crashReason((ev as ErrorEvent).message || "unknown worker error");
+    // Park the reason BEFORE destroying: a background crash (no call in flight)
+    // otherwise leaves the next call a silently-fresh cell, contradicting the
+    // "state survives later calls" contract. (preventDefault() does NOT stop Bun
+    // from tearing the worker down — verified — so report-on-next-call it is.)
+    crashed.set(sessionId, msg);
+    destroyCell(sessionId, runtime, `worker crashed: ${msg}`);
+  });
+  // Never hold the host process open on account of an idle cell.
+  (worker as unknown as { unref?: () => void }).unref?.();
+  return runtime;
+}
+
+/** Terminate a runtime and fail its in-flight runs. Guarded against stale handles:
+ *  only unmaps when this runtime is still the session's current one. */
+function destroyCell(sessionId: string, runtime: CellRuntime, reason: string): void {
+  if (cells.get(sessionId) === runtime) cells.delete(sessionId);
+  for (const [id, cb] of [...runtime.pending]) {
+    runtime.pending.delete(id);
+    cb({ id, ok: false, stdout: "", value: "", error: reason });
+  }
+  try { runtime.worker.terminate(); } catch { /* already dead */ }
+}
+
+/** Kill every session's cell worker (test teardown / host shutdown). */
+export async function disposeEvalCells(): Promise<void> {
+  for (const [sid, rt] of [...cells]) destroyCell(sid, rt, "eval cells disposed");
+  crashed.clear();
+  if (bootstrapUrl !== null) { URL.revokeObjectURL(bootstrapUrl); bootstrapUrl = null; }
+}
+
+/** Byte-budget truncation (OMP output window, docs/tools/eval.md:185). UTF-8 safe:
+ *  a torn trailing multibyte sequence is dropped, and a marker reports kept/total. */
+export function truncateToBudget(text: string, budgetBytes: number): string {
+  const enc = new TextEncoder();
+  const bytes = enc.encode(text);
+  if (bytes.length <= budgetBytes) return text;
+  const kept = new TextDecoder("utf-8", { fatal: false })
+    .decode(bytes.slice(0, budgetBytes))
+    .replace(/�+$/, "");
+  return `${kept}\n[output truncated: sent ${enc.encode(kept).length} of ${bytes.length} bytes]`;
+}
+
+function clampInt(v: unknown, min: number, max: number, dflt: number): number {
+  const n = typeof v === "number" && Number.isFinite(v) ? Math.floor(v) : dflt;
+  return Math.min(max, Math.max(min, n));
+}
+
+async function runCell(
+  sessionId: string, code: string, timeoutMs: number, budgetBytes: number,
+  signal: AbortSignal, reset: boolean,
+): Promise<ToolOutput> {
+  let existing = cells.get(sessionId);
+  if (reset && existing) { destroyCell(sessionId, existing, "cell reset"); existing = undefined; }
+  // A spawn that replaces a crashed worker must SAY so: consume the parked reason
+  // exactly once and prefix this call's output (outside the byte budget, like the
+  // truncation marker — host metadata is never silently truncated away).
+  let note = "";
+  if (!existing) {
+    const reason = crashed.get(sessionId);
+    if (reason !== undefined) {
+      crashed.delete(sessionId);
+      note = `note: previous cell worker crashed (${reason}); state was reset\n`;
+    }
+  }
+  const cell = existing ?? spawnCell(sessionId);
+  if (!existing) cells.set(sessionId, cell);
+
+  const id = ++callSeq;
+  const result = new Promise<WorkerResult>((res) => { cell.pending.set(id, res); });
+  let timer: ReturnType<typeof setTimeout> | undefined;
+  const timedOut = new Promise<"timeout">((res) => { timer = setTimeout(() => res("timeout"), timeoutMs); });
+  let onAbort: (() => void) | undefined;
+  const aborted = new Promise<"aborted">((res) => {
+    if (signal.aborted) { res("aborted"); return; }
+    onAbort = () => res("aborted");
+    signal.addEventListener("abort", onAbort, { once: true });
+  });
+
+  try {
+    const up = await Promise.race([cell.ready.then(() => "ready" as const), timedOut, aborted]);
+    if (up === "ready") cell.worker.postMessage({ id, code });
+    const winner = up === "ready" ? await Promise.race([result, timedOut, aborted]) : up;
+    if (winner === "timeout" || winner === "aborted") {
+      // Destructive cancellation (OMP docs/tools/eval.md:179): a busy synchronous cell
+      // can only be stopped by killing its worker; retained state dies with it.
+      destroyCell(sessionId, cell, winner);
+      return {
+        ok: false,
+        output: note + (winner === "timeout"
+          ? `Error: eval cell timed out after ${timeoutMs}ms — worker killed; this session's cell state was reset`
+          : "Error: eval cell aborted — worker killed; this session's cell state was reset"),
+      };
+    }
+    const parts: string[] = [];
+    if (winner.stdout !== "") parts.push(winner.stdout.replace(/\n$/, ""));
+    if (winner.ok && winner.value !== "") parts.push(`=> ${winner.value}`);
+    if (!winner.ok) parts.push(`Error: ${winner.error}`);
+    const text = parts.length > 0 ? parts.join("\n") : "(no output)";
+    return { ok: winner.ok, output: note + truncateToBudget(text, budgetBytes) };
+  } finally {
+    if (timer !== undefined) clearTimeout(timer);
+    if (onAbort !== undefined) signal.removeEventListener("abort", onAbort);
+    cell.pending.delete(id);
+  }
+}
+
+const evalCellTool: Tool = {
+  schema: {
+    name: "eval_cell",
+    description:
+      "Execute JavaScript/TypeScript in this session's persistent eval cell (a Bun worker). " +
+      "State survives across calls: `var`, function declarations, and `globalThis.*` assignments " +
+      "persist; top-level `let`/`const` are cell-local. Console output is captured and the final " +
+      "expression's value is returned as `=> value`. Cells using top-level `await` or bare `return` " +
+      "run wrapped in an async function — persist state via `globalThis` there. No rovecode tool access " +
+      "from inside the cell (v1 scope). Output is truncated to a byte budget. On timeout — or if a " +
+      "background error crashes the worker between calls — cell state resets, and the next call " +
+      "says so in a `note:` prefix. NOT a sandbox: gated by the same execute policy as bash.",
+    args: {
+      type: "object",
+      properties: {
+        code: { type: "string", description: "JS/TS source of one cell" },
+        timeout_ms: { type: "integer", description: `kill budget in ms (default ${DEFAULT_TIMEOUT_MS}, max ${MAX_TIMEOUT_MS})` },
+        max_output_bytes: { type: "integer", description: `output byte budget (default ${DEFAULT_OUTPUT_BYTES}, max ${MAX_OUTPUT_BYTES})` },
+        reset: { type: "boolean", description: "discard this session's cell state before running (OMP reset semantics)" },
+      },
+      required: ["code"],
+    },
+  },
+  kind: "execute", // → action "shell.exec": deny-default rules prompt for it like bash
+  sequential: true,
+  async execute(args: unknown, ctx: ToolContext): Promise<ToolOutput> {
+    const a = (args ?? {}) as { code?: unknown; timeout_ms?: unknown; max_output_bytes?: unknown; reset?: unknown };
+    if (typeof a.code !== "string" || a.code.trim() === "") {
+      return { ok: false, output: "Error: eval_cell requires a non-empty string `code` argument" };
+    }
+    const timeoutMs = clampInt(a.timeout_ms, MIN_TIMEOUT_MS, MAX_TIMEOUT_MS, DEFAULT_TIMEOUT_MS);
+    const budget = clampInt(a.max_output_bytes, MIN_OUTPUT_BYTES, MAX_OUTPUT_BYTES, DEFAULT_OUTPUT_BYTES);
+    try {
+      return await runCell(ctx.sessionId, a.code, timeoutMs, budget, ctx.signal, a.reset === true);
+    } catch (e) {
+      // Never throw across the tool seam (ADR-005): host failures become typed output.
+      return { ok: false, output: `Error: eval cell host failure: ${e instanceof Error ? e.message : String(e)}` };
+    }
+  },
+};
+
+/** Flag-gated factory: the ONLY door to the tool. Returns null unless ROVECODE_EVAL_CELL=1,
+ *  so flag-off runs register nothing (bar: OFF by default and unregistered when off). */
+export function createEvalCellTool(
+  env: Record<string, string | undefined> = process.env,
+): Tool | null {
+  return env[EVAL_CELL_FLAG] === "1" ? evalCellTool : null;
+}

package/src/tools/html-text.ts

@@ -0,0 +1,139 @@
+/** Compact HTML → readable text (PORT #31). Stands in for the html-to-text
+ *  dependency gemini-cli uses (Apache-2.0, 0bd1d43, packages/core/src/tools/
+ *  web-fetch.ts:704-709: links keep their href, images are skipped) and for
+ *  opencode's htmlparser2 skip-depth extractor (MIT, ebece6e, packages/opencode/
+ *  src/tool/webfetch.ts:158-180: script/style/noscript/iframe/object subtrees
+ *  dropped; <embed> is void, so unlike opencode it is not depth-tracked). One
+ *  regex tokenizer pass: raw-text elements are jumped over wholesale, dropped
+ *  subtrees are depth-tracked, block elements become line breaks, list items
+ *  get "- ", links render as `text (href)` resolved against the page URL,
+ *  entities are decoded, whitespace collapses except inside <pre>. Not a spec
+ *  parser (no tree, no adoption agency) but the tokenizer follows the HTML5
+ *  tag and attribute states, so quoted attribute values may contain "<" and
+ *  ">". Every scan is bounded (see tagRx) so a hostile body parses in O(n):
+ *  the tool's timeout cannot interrupt a synchronous parse, so the parse must
+ *  never be the slow part. */
+
+/** Elements whose CONTENT is raw text up to the matching close tag. <title> is
+ *  RCDATA and never rendered, so a page that omits <head> still loses its title. */
+const RAW = new Set(["script", "style", "noscript", "template", "title"]);
+/** Elements dropped with their whole (markup) subtree. <head> also ends at the
+ *  first start tag outside HEAD_ONLY: an omitted </head> — even an omitted
+ *  <body> — is legal HTML, common in minified pages. */
+const DROP = new Set(["head", "svg", "iframe", "object", "canvas", "audio", "video", "select"]);
+/** Start tags the HTML5 "in head" insertion mode keeps inside <head>; any other
+ *  start tag implies </head> (and <body>). RAW members are jumped before the
+ *  check ever runs — listed so the set reads as the spec's. */
+const HEAD_ONLY = new Set(["head", "meta", "link", "base", "basefont", "bgsound", "noframes", "title", "style", "script", "noscript", "template"]);
+/** Elements that break lines; PARA members separate with a blank line. */
+const BLOCK = new Set([
+  "address", "article", "aside", "blockquote", "body", "caption", "center", "dd", "details", "dialog", "div", "dl", "dt",
+  "fieldset", "figcaption", "figure", "footer", "form", "h1", "h2", "h3", "h4", "h5", "h6", "header", "hr", "html",
+  "legend", "main", "menu", "nav", "ol", "p", "pre", "section", "summary", "table", "tbody", "tfoot", "thead", "tr", "ul",
+]);
+const PARA = new Set(["p", "h1", "h2", "h3", "h4", "h5", "h6", "blockquote", "pre", "ul", "ol", "table", "figure"]);
+
+const ENTITIES: Record<string, string> = {
+  amp: "&", lt: "<", gt: ">", quot: '"', apos: "'", nbsp: " ", shy: "", copy: "©", reg: "®", trade: "™",
+  hellip: "…", mdash: "—", ndash: "–", lsquo: "‘", rsquo: "’", ldquo: "“", rdquo: "”", laquo: "«", raquo: "»",
+  bull: "•", middot: "·", deg: "°", times: "×", divide: "÷", plusmn: "±", euro: "€", pound: "£", yen: "¥", cent: "¢",
+  sect: "§", para: "¶", larr: "←", rarr: "→", uarr: "↑", darr: "↓", harr: "↔", frac12: "½", frac14: "¼", frac34: "¾",
+  sup2: "²", sup3: "³", micro: "µ", iexcl: "¡", iquest: "¿",
+};
+
+/** Named (common subset), decimal and hex character references; unknown ones are kept verbatim. */
+export function decodeEntities(s: string): string {
+  return s.replace(/&(#[xX][0-9a-fA-F]+|#\d+|[a-zA-Z][a-zA-Z0-9]*);/g, (m, body: string) => {
+    if (body[0] === "#") {
+      const cp = body[1] === "x" || body[1] === "X" ? parseInt(body.slice(2), 16) : parseInt(body.slice(1), 10);
+      return cp > 0 && cp <= 0x10ffff && (cp < 0xd800 || cp > 0xdfff) ? String.fromCodePoint(cp) : m;
+    }
+    return ENTITIES[body] ?? m;
+  });
+}
+
+function attr(attrs: string, key: string): string | undefined {
+  const m = new RegExp(`(?:^|\\s)${key}\\s*=\\s*(?:"([^"]*)"|'([^']*)'|([^\\s"'>]+))`, "i").exec(attrs);
+  return m ? decodeEntities(m[1] ?? m[2] ?? m[3] ?? "").trim() : undefined;
+}
+
+function resolveHref(href: string, baseUrl: string | undefined): string {
+  try { return new URL(href, baseUrl).href; } catch { return href; }
+}
+
+/** Readable text for an HTML document. `baseUrl` resolves relative link hrefs. */
+export function htmlToText(html: string, baseUrl?: string): string {
+  const out: string[] = [];
+  let skip = 0; // depth inside DROP subtrees
+  let pre = 0;  // depth inside <pre>
+  let inHead = false; // between <head> and </head>, explicit or implied
+  let link: { href: string; start: number } | null = null;
+  // Linear-time tokenizer (MED-3): every alternative is deterministic, so each
+  // character is examined once. Comment/CDATA run lazily to their close or EOF
+  // (unterminated swallows the rest, as browsers do). A tag, once opened, never
+  // backs out: the name runs to the next blank, "/" or ">" (HTML5 tag-name state —
+  // `<a<a<a…` is ONE element, as in a browser), the attribute part must START with
+  // a blank or "/" so the name and attribute quantifiers can never trade characters
+  // (that nesting made `<aaaa…` quadratic), and inside it a quoted value consumes
+  // "<" and ">" while an unterminated quote runs to EOF ("eof-in-tag"), so raw-text
+  // jumps and subtree drops engage on legal markup like <script data-x="<">.
+  const tagRx = /<!--[\s\S]*?(?:-->|$)|<!\[CDATA\[[\s\S]*?(?:\]\]>|$)|<[!?][^<>]*>|<\/?([a-zA-Z][^\s/>]*)((?:[\s/](?:[^>"']|"[^"]*(?:"|$)|'[^']*(?:'|$))*)?)(?:>|$)/g;
+  let pos = 0;
+
+  const text = (raw: string): void => {
+    if (skip > 0 || raw === "") return;
+    let s = decodeEntities(raw);
+    if (pre === 0) {
+      s = s.replace(/\s+/g, " ");
+      const last = out.length > 0 ? out[out.length - 1]! : "\n";
+      if (last.endsWith("\n") || last.endsWith("- ")) s = s.trimStart();
+    }
+    if (s) out.push(s);
+  };
+
+  let m: RegExpExecArray | null;
+  while ((m = tagRx.exec(html)) !== null) {
+    text(html.slice(pos, m.index));
+    pos = tagRx.lastIndex;
+    const name = m[1]?.toLowerCase();
+    if (!name) continue; // comment, doctype, CDATA, processing instruction
+    const closing = m[0].startsWith("</");
+    if (RAW.has(name)) {
+      if (closing) continue;
+      const end = html.slice(pos).search(new RegExp(`</${name}\\s*>`, "i"));
+      pos = end < 0 ? html.length : pos + end; // the close tag itself is tokenized next and ignored above
+      tagRx.lastIndex = pos;
+      continue;
+    }
+    // Browser "in head" insertion mode (MED-4): the first start tag that is not a
+    // head-only element — <body>, but also a bare <p> — closes an unclosed <head>.
+    if (inHead && !closing && !HEAD_ONLY.has(name)) { inHead = false; skip = 0; }
+    if (name === "head") inHead = !closing;
+    if (DROP.has(name)) { skip = closing ? Math.max(0, skip - 1) : skip + 1; continue; }
+    if (skip > 0) continue;
+    if (name === "a") {
+      if (!closing) {
+        // same-page fragments are judged on the RAW href: resolved against a base they never start with "#"
+        const href = attr(m[2] ?? "", "href") ?? "";
+        link = { href: href === "" || href.startsWith("#") ? "" : resolveHref(href, baseUrl), start: out.length };
+      } else if (link) {
+        const label = out.slice(link.start).join("").trim();
+        const h = link.href;
+        if (h && label && label !== h && !/^(javascript|data|mailto|tel):/i.test(h)) out.push(` (${h})`);
+        link = null;
+      }
+      continue;
+    }
+    if (name === "br") { out.push("\n"); continue; }
+    if (name === "li") { if (!closing) out.push("\n- "); continue; }
+    const last = out.length > 0 ? out[out.length - 1]! : "\n";
+    if (name === "td" || name === "th") { if (!closing && !last.endsWith("\n")) out.push(" "); continue; }
+    if (name === "pre") pre = Math.max(0, pre + (closing ? -1 : 1));
+    if (BLOCK.has(name)) { const sep = PARA.has(name) ? "\n\n" : "\n"; if (!last.endsWith(sep)) out.push(sep); }
+  }
+  text(html.slice(pos));
+  // Trailing blanks before a newline: the lookbehind anchors each run at its
+  // first blank so a <pre> full of spaces is scanned once (bare `[ \t]+\n`
+  // re-scanned the run from every blank — quadratic, minutes on 512KB).
+  return out.join("").replace(/(?<=^|[^ \t])[ \t]+\n/g, "\n").replace(/\n{3,}/g, "\n\n").trim();
+}

package/src/tools/provider.ts

@@ -0,0 +1,149 @@
+/** provider_list / provider_edit — the agent's window onto the provider registry (providers/registry.ts).
+ *
+ *  Split like task/task_status (port #26): provider_list is kind "read" (policy action file.read →
+ *  auto-allowed under gated rules and in plan mode; it never mutates and never prompts), provider_edit
+ *  is kind "custom" → action tool.provider_edit, PROMPT under gated rules (cli/runtime.ts buildCfg),
+ *  denied in plan mode by the blanket tool.* rule, allowed under yolo. Children (task tool) get neither.
+ *
+ *  Secrets: NEITHER tool accepts, returns or echoes an API key. provider_list prints key SOURCES
+ *  (stored / env NAME / none); provider_edit refuses any key-shaped argument (looksLikeSecret) and
+ *  tells the model how the human sets one — `rovecode auth set <id>` (masked prompt), `/provider key`
+ *  in the TUI, or the env var named by keyEnv. A key the model was given would otherwise sit in the
+ *  transcript and in the provider's logs forever.
+ *
+ *  Effects are live: the registry re-reads its files, so the run that follows an add/use — and the
+ *  TUI, through registry.onChange — sees the new provider without a restart. */
+
+import type { Tool, ToolOutput } from "../core/types.ts";
+import { inferProtocol, isConfigured } from "../providers/provider-config.ts";
+import { formatProviderList, type ProviderRegistry } from "../providers/registry.ts";
+
+const SECRET_FIELD_RE = /^(api[_-]?key|key|secret|token|password|auth(orization)?|bearer)$/i;
+/** common key prefixes — a value that starts like this is a secret whatever the field is called */
+const SECRET_VALUE_RE = /^(sk-|sk_|key-|xai-|gsk_|AKIA|Bearer\s|ghp_)/;
+
+/** The argument name that carries something key-shaped, or null. `keyEnv`/`noKey` are legitimate. */
+export function looksLikeSecret(args: unknown): string | null {
+  if (typeof args !== "object" || args === null) return null;
+  for (const [k, v] of Object.entries(args as Record<string, unknown>)) {
+    if (k === "keyEnv" || k === "noKey") continue;
+    if (typeof v !== "string" || v.trim().length === 0) continue;
+    if (SECRET_FIELD_RE.test(k)) return k;
+    if (SECRET_VALUE_RE.test(v.trim())) return k;
+  }
+  return null;
+}
+
+const refusal = (field: string): string =>
+  `provider_edit never accepts API keys (argument "${field}" looks like one) — nothing was stored. Keys stay with the human: ask them to run \`rovecode auth set <id>\` (masked prompt) or \`/provider key <id> <key>\` in the TUI, or to set the env var you name in keyEnv. Then retry without the key.`;
+
+export function providerListTool(reg: ProviderRegistry): Tool {
+  return {
+    schema: {
+      name: "provider_list",
+      description: "Inspect model providers (never prompts, never mutates, never shows a key). `list` shows the configured providers, the default provider/model and where each key comes from (stored / env NAME / none; `all` adds keyless built-ins); `models` lists the model ids a provider offers (its providers.json entry or its /models endpoint); `test` makes one tiny real call to a provider (optionally a specific model) and reports ok or the error. Use it before switching models, or when a run ends with a `config:` error.",
+      args: {
+        type: "object",
+        properties: {
+          action: { type: "string", enum: ["list", "models", "test"] },
+          id: { type: "string", description: "provider id (models / test)" },
+          model: { type: "string", description: "model id to test (default: the provider's default model)" },
+          all: { type: "boolean", description: "list: include built-in providers that have no key yet" },
+        },
+        required: ["action"],
+      },
+    },
+    kind: "read",
+    sequential: false,
+    async execute(args): Promise<ToolOutput> {
+      const a = (args && typeof args === "object" ? args : {}) as { action?: string; id?: string; model?: string; all?: boolean };
+      switch (a.action) {
+        case "list":
+          return { ok: true, output: formatProviderList(reg, { all: a.all === true }) };
+        case "models": {
+          if (!a.id) return { ok: false, output: "models needs `id`" };
+          const r = await reg.models(a.id);
+          if (!r.ok) return { ok: false, output: r.error };
+          return r.models.length > 0
+            ? { ok: true, output: `${a.id} models (${r.source}, ${r.models.length}):\n${r.models.join("\n")}` }
+            : { ok: true, output: `${a.id}: the endpoint listed no models (it may not implement /models — try a model id directly with test)` };
+        }
+        case "test": {
+          if (!a.id) return { ok: false, output: "test needs `id`" };
+          const r = await reg.probe(a.id, a.model);
+          return { ok: r.ok, output: `${a.id}/${r.model}: ${r.detail}` };
+        }
+        default:
+          return { ok: false, output: "action must be list | models | test" };
+      }
+    },
+  };
+}
+
+export function providerEditTool(reg: ProviderRegistry): Tool {
+  return {
+    schema: {
+      name: "provider_edit",
+      description: "Add, remove or select model providers; the human approves each call. `add` registers an endpoint {id, baseUrl, protocol? (openai|anthropic — inferred from the URL), keyEnv? (env var holding the key), defaultModel?, noKey? (local servers), scope? (user|project)} in providers.json. `remove` deletes a file-defined provider. `use` sets the default provider/model (`selector` = \"provider/model\" or a provider id) and takes effect immediately: the TUI switches now, the next run uses it, no restart. NEVER pass an API key here — the call is refused and nothing is stored. After `add`, tell the user to run `rovecode auth set <id>` (or `/provider key <id> <key>` in the TUI), or to set the keyEnv variable; the key is picked up live.",
+      args: {
+        type: "object",
+        properties: {
+          action: { type: "string", enum: ["add", "remove", "use"] },
+          id: { type: "string" },
+          baseUrl: { type: "string", description: "http(s) endpoint root, e.g. https://llm.example.com/v1" },
+          protocol: { type: "string", enum: ["openai", "anthropic"] },
+          keyEnv: { type: "string", description: "env var that holds the key (default <ID>_API_KEY)" },
+          defaultModel: { type: "string" },
+          noKey: { type: "boolean", description: "local server: no key required" },
+          scope: { type: "string", enum: ["user", "project"], description: "which providers.json: ~/.rovecode (default) or ./.rovecode" },
+          selector: { type: "string", description: "use: provider/model" },
+        },
+        required: ["action"],
+      },
+    },
+    kind: "custom",
+    sequential: true,
+    async execute(args): Promise<ToolOutput> {
+      const leaked = looksLikeSecret(args);
+      if (leaked !== null) return { ok: false, output: refusal(leaked) };
+      const a = (args && typeof args === "object" ? args : {}) as {
+        action?: string; id?: string; baseUrl?: string; protocol?: "openai" | "anthropic"; keyEnv?: string;
+        defaultModel?: string; noKey?: boolean; scope?: "user" | "project"; selector?: string;
+      };
+      const scope = a.scope === "project" ? "project" : "user";
+      switch (a.action) {
+        case "add": {
+          if (!a.id || !a.baseUrl) return { ok: false, output: "add needs `id` and `baseUrl`" };
+          const r = reg.add({
+            id: a.id, baseUrl: a.baseUrl, protocol: a.protocol ?? inferProtocol(a.baseUrl),
+            ...(a.keyEnv !== undefined ? { keyEnv: a.keyEnv } : {}),
+            ...(a.defaultModel !== undefined ? { defaultModel: a.defaultModel } : {}),
+            ...(a.noKey === true ? { noKey: true } : {}),
+          }, scope);
+          if ("error" in r) return { ok: false, output: r.error };
+          const key = !isConfigured(r)
+            ? `key: NOT SET — the user must run \`rovecode auth set ${r.id}\` (or \`/provider key ${r.id} <key>\` in the TUI), or set ${r.keyEnv}; it is picked up immediately, no restart`
+            : r.keySource === "stored" ? "key: stored credential" : r.keySource === "env" ? `key: env ${r.keyEnv} (present)` : "key: not needed";
+          return { ok: true, output: `added provider "${r.id}" (${r.protocol}, ${r.baseUrl}) to the ${scope} providers.json\n${key}${r.defaultModel !== undefined ? `\ndefault model: ${r.defaultModel}` : ""}\nselect it with provider_edit use ${r.id}/<model>` };
+        }
+        case "remove": {
+          if (!a.id) return { ok: false, output: "remove needs `id`" };
+          const r = reg.remove(a.id);
+          if ("error" in r) return { ok: false, output: r.error };
+          return { ok: true, output: r.removed.length > 0 ? `removed provider "${a.id}" from the ${r.removed.join(" and ")} providers.json` : `provider "${a.id}" was not in any providers.json` };
+        }
+        case "use": {
+          const sel = a.selector ?? a.id;
+          if (!sel) return { ok: false, output: "use needs `selector` (provider/model)" };
+          const r = reg.setDefault(sel, scope);
+          if ("error" in r) return { ok: false, output: r.error };
+          const p = reg.get(r.provider);
+          const note = p !== undefined && !isConfigured(p) ? `\nnote: ${reg.keyHint(p)}` : "";
+          return { ok: true, output: `default → ${r.provider}/${r.model} (saved to the ${scope} providers.json; the TUI switches now, headless runs use it from the next run)${note}` };
+        }
+        default:
+          return { ok: false, output: "action must be add | remove | use" };
+      }
+    },
+  };
+}