rovecode 0.4.0-beta.2 → 0.4.0

package/src/tools/design.ts

@@ -0,0 +1,151 @@
+/** design_audit / design_direction — the agent's half of the design protocol (design/rules.ts).
+ *
+ *  Split like provider_list/provider_edit (and task/task_status) for the same reason: reading must
+ *  never cost a prompt, writing must be visible.
+ *    - design_audit is kind "read" -> policy action file.read, auto-allowed under the gated rules and
+ *      in plan mode. Checking your own work has to be free, or it will not happen.
+ *    - design_direction is kind "custom" -> action tool.design_direction, PROMPT under the gated rules
+ *      (cli/runtime.ts buildCfg), denied in plan mode by the blanket tool.* rule, allowed under yolo.
+ *      It writes the project's design identity, and the approval card is where the human sees exactly
+ *      what is being recorded on their behalf. It is asked ONCE per project, which is the whole design
+ *      of the feature -- so the one prompt is the point, not friction.
+ *
+ *  design_direction deliberately cannot invent a direction: `set` records what the human chose. The
+ *  model is expected to have asked first (the prompt section says so). Nothing here can enforce that
+ *  -- what it can do is keep the record honest and put the write in front of a human once. */
+
+import { isAbsolute, relative, resolve } from "node:path";
+import type { Tool, ToolOutput } from "../core/types.ts";
+import { auditFiles, auditProject, formatFindings, type Finding } from "../design/audit.ts";
+import {
+  designPath, loadDirection, parseDirection, renderDirection, saveDirection,
+  type DesignDirection,
+} from "../design/direction.ts";
+
+/** Resolve a caller-supplied path against the run's cwd and refuse to leave it: an audit is about
+ *  THIS project's files, and a read tool that wanders is a read tool nobody can reason about. */
+function insideCwd(cwd: string, p: string): string | null {
+  const abs = isAbsolute(p) ? resolve(p) : resolve(cwd, p);
+  const rel = relative(resolve(cwd), abs);
+  return rel === "" || rel.startsWith("..") || isAbsolute(rel) ? null : abs;
+}
+
+export function designAuditTool(): Tool {
+  return {
+    schema: {
+      name: "design_audit",
+      description:
+        "Check interface code for the patterns that arrive when nobody decided (a webfont loaded without a choice, amber doing accent duty, the three-up feature grid, a centred full-viewport hero, the violet-to-blue gradient, nothing but square corners) and for drift from the direction this project recorded in .rovecode/design.json. Run it on the SOURCE TREE, not on a fetched page: a built page measures the framework's output, not the design. Pass the page files you touched along with the components they import, because density and centring are scored per page and 'no rounded corner anywhere' is scored per project. It reports evidence, not verdicts: each finding says what it counted, so you can fix it or explain why it is wrong here. Never prompts, never writes.",
+      args: {
+        type: "object",
+        properties: {
+          files: { type: "array", items: { type: "string" }, description: "paths inside the project to audit (html/css/jsx/tsx/vue/svelte)" },
+          source: { type: "string", description: "audit this markup/CSS directly instead of reading files" },
+          ignore: { type: "array", items: { type: "string" }, description: "rule ids to skip (the full table is in docs/design.md): cliche-font, font-deviation, font-named-not-loaded, cliche-accent-amber, accent-deviation, template-grid, template-icons, reflex-hero, cliche-gradient, off-palette, decoration-density, rule-line-density, everything-centered, all-square" },
+        },
+      },
+    },
+    kind: "read",
+    sequential: false,
+    async execute(args, ctx): Promise<ToolOutput> {
+      const a = (args && typeof args === "object" ? args : {}) as { files?: string[]; source?: string; ignore?: string[] };
+      const direction = loadDirection(ctx.cwd);
+      const ignore = a.ignore ?? [];
+      const findings: Finding[] = [];
+
+      // `source` is one pathless page: auditProject treats a lone file as a page so pasted markup still
+      // gets the page-scoped density and centring checks (auditSource alone is file-scope by design).
+      if (typeof a.source === "string" && a.source.length > 0) {
+        findings.push(...auditProject([{ path: "source", text: a.source }], { direction, ignore }));
+      }
+      const paths = a.files ?? [];
+      if (paths.length > 0) {
+        const resolved: string[] = [];
+        const outside: string[] = [];
+        for (const p of paths) {
+          const abs = insideCwd(ctx.cwd, p);
+          if (abs === null) outside.push(p); else resolved.push(abs);
+        }
+        if (outside.length > 0) {
+          return { ok: false, output: `design_audit only reads files inside the project. Outside: ${outside.join(", ")}` };
+        }
+        findings.push(...auditFiles(resolved, { direction, ignore }).map((f) => ({
+          ...f, ...(f.file !== undefined ? { file: relative(resolve(ctx.cwd), f.file) || f.file } : {}),
+        })));
+      }
+      if (paths.length === 0 && (a.source === undefined || a.source.length === 0)) {
+        return { ok: false, output: "design_audit needs `files` (paths inside the project) or `source` (markup/CSS text)." };
+      }
+      return { ok: true, output: formatFindings(findings, direction), data: { findings, direction } };
+    },
+  };
+}
+
+export function designDirectionTool(): Tool {
+  return {
+    schema: {
+      name: "design_direction",
+      description:
+        "Read or record this project's design direction (.rovecode/design.json). `get` returns the recorded direction, or says none is recorded. `set` records the direction THE HUMAN CHOSE after you proposed three — do not call it with a direction you picked yourself. The one exception is a headless run where nothing can ask a human: then build ONE direction and record it with provisional:true and the other two in `alternatives`, so the next interactive session asks before more UI is built. Recording it is what makes the choice a once-per-project question and lets design_audit check later screens for consistency.",
+      args: {
+        type: "object",
+        properties: {
+          action: { type: "string", enum: ["get", "set"] },
+          name: { type: "string", description: "short name of the chosen direction, as presented to the human" },
+          rationale: { type: "string", description: "one line: why it suits this product" },
+          palette: { type: "object", description: "chosen colours, e.g. {\"ink\":\"#0b1a2e\",\"accent\":\"#c2410c\"}" },
+          typeface: { type: "object", description: "{\"display\":\"...\",\"text\":\"...\"}" },
+          corners: { type: "string", enum: ["sharp", "soft", "round"] },
+          layout: { type: "string", enum: ["centered", "left", "asymmetric", "grid"] },
+          density: { type: "string", enum: ["tight", "regular", "airy"] },
+          sectionOrder: { type: "array", items: { type: "string" }, description: "the page's blocks in order, e.g. [\"hero\",\"proof\",\"pricing\",\"faq\"]" },
+          heroPattern: { type: "string", description: "the hero pattern by name, e.g. \"command-first\" or \"product-forward\"" },
+          typeScale: { type: "array", items: { type: "number" }, description: "the chosen type steps, e.g. [14,16,20,28,44]" },
+          motion: { type: "string", description: "the motion rule in the human's words, e.g. \"one entrance per section, no loops\"" },
+          copyRegister: { type: "string", description: "how the copy reads, e.g. \"technical, names and numbers, no marketing verbs\"" },
+          notes: { type: "string", description: "what the audit cannot infer: imagery, what to avoid here" },
+          provisional: { type: "boolean", description: "true ONLY when no human could be asked (a headless run): you built to one direction to get unblocked. Never true when a human answered." },
+          alternatives: { type: "array", items: { type: "string" }, description: "with provisional: the names of the directions you did NOT build, so the next interactive session can offer them" },
+        },
+        required: ["action"],
+      },
+    },
+    kind: "custom",
+    sequential: true,
+    // `get` reads .rovecode/design.json and writes nothing; `set` records the project's design
+    // identity. Only the second is worth a human's attention, so the two get their own policy
+    // resource (types.ts Tool.resource) instead of sharing one rule under the tool name. Anything
+    // that is not the literal "get" is treated as the write: an unknown action must not read as
+    // the safer of the two.
+    resource(args: unknown): string {
+      const a = args && typeof args === "object" ? (args as Record<string, unknown>) : undefined;
+      return a?.["action"] === "get" ? "get" : "set";
+    },
+    async execute(args, ctx): Promise<ToolOutput> {
+      const a = (args && typeof args === "object" ? args : {}) as Record<string, unknown>;
+      if (a["action"] === "get") {
+        const d = loadDirection(ctx.cwd);
+        return d === null
+          ? { ok: true, output: `No design direction recorded for this project (${designPath(ctx.cwd)} does not exist). Propose three distinct directions and let the human choose before writing UI. If nothing here can ask a human, build ONE and record it with provisional: true.` }
+          : { ok: true, output: renderDirection(d), data: d };
+      }
+      if (a["action"] !== "set") return { ok: false, output: "design_direction: action must be \"get\" or \"set\"." };
+
+      const parsed: DesignDirection | null = parseDirection(a);
+      if (parsed === null) {
+        return { ok: false, output: "design_direction set needs at least `name` — the short name of the direction the human chose." };
+      }
+      // Who chose is DERIVED, never taken from the call: `provisional` means the agent picked, its
+      // absence means a human did. Trusting the model with both fields lets one contradict the other,
+      // and the whole point of the field is that it can be believed. Stamped on every write, so a
+      // record always says who — absent is only ever a file written before the field existed.
+      parsed.chosenBy = parsed.provisional === true ? "agent" : "human";
+      const path = saveDirection(ctx.cwd, parsed);
+      if (parsed.provisional === true) {
+        const alts = parsed.alternatives === undefined ? "" : ` The alternatives (${parsed.alternatives.join(", ")}) are recorded with it.`;
+        return { ok: true, output: `Recorded "${parsed.name}" in ${path} as PROVISIONAL — you chose it, not the human.${alts} Build to it and say so in your final summary, naming what you did not build. The next interactive session asks before more UI is written.`, data: parsed };
+      }
+      return { ok: true, output: `Recorded "${parsed.name}" in ${path}. Later UI in this project is built to it, and design_audit checks against it.`, data: parsed };
+    },
+  };
+}

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();
+}