romdevtools 0.41.0 → 0.42.0

package/src/mcp/tools/frame.js

@@ -3,7 +3,7 @@ import { tmpdir } from "node:os";
 import path from "node:path";
 import { PNG } from "pngjs";
 import { resamplePng } from "../../host/framebuffer.js";
-import { getHost } from "../state.js";
+import { getHost, getHostB } from "../state.js";
 import { imageContent, jsonContent, safeTool } from "../util.js";
 import { decodeOAM, decodePpuRegs, ppuRegsPopulated } from "../../platforms/snes/ppu.js";
 import { stepInstructionCore, attachObserverFrame } from "./watch-memory.js";
@@ -241,6 +241,79 @@ function hsvToRgb(h, s, v) {
   return [Math.round(r * 255), Math.round(g * 255), Math.round(b * 255)];
 }
 
+/**
+ * Lightweight pixel summary of an RGBA framebuffer — the same dominant-color /
+ * distinct-color scan computeVerify uses, factored out so sideBySide can report
+ * a per-pane "is this side alive / how different is it" signal without the full
+ * render-context decode. No host needed; pure pixels. Exported for tests.
+ */
+export function pixelSummary(width, height, rgba) {
+  const counts = new Map();
+  const total = width * height;
+  for (let i = 0; i + 3 < rgba.length; i += 4) {
+    const key = (rgba[i] << 16) | (rgba[i + 1] << 8) | rgba[i + 2];
+    counts.set(key, (counts.get(key) || 0) + 1);
+  }
+  let topColor = 0, topCount = 0;
+  for (const [c, n] of counts) if (n > topCount) { topCount = n; topColor = c; }
+  const dominantFraction = total ? topCount / total : 1;
+  return {
+    width, height,
+    distinctColors: counts.size,
+    dominantColor: "#" + topColor.toString(16).padStart(6, "0"),
+    dominantPct: Math.round(dominantFraction * 1000) / 10,
+  };
+}
+
+/**
+ * Composite two framebuffers into one PNG, A on the left and B on the right,
+ * separated by a vertical divider. Panes are integer-upscaled to a shared
+ * height (the taller of the two) so a small handheld next to a console reads at
+ * a comparable size; the upscale is nearest-neighbor to keep pixels crisp. The
+ * background fills any letterbox gaps. Returns the encoded PNG buffer.
+ *
+ * @param {{width:number,height:number,rgba:Uint8Array|Buffer}} a left pane
+ * @param {{width:number,height:number,rgba:Uint8Array|Buffer}} b right pane
+ * @param {number} gap divider width in px
+ * Exported for tests.
+ */
+export function compositeSideBySide(a, b, gap = 4) {
+  // Integer scale each pane up toward the common (max) height. Integer-only so
+  // pixel art stays sharp; a pane that doesn't divide evenly is centered.
+  const targetH = Math.max(a.height, b.height);
+  const scaleFor = (h) => Math.max(1, Math.floor(targetH / h));
+  const aScale = scaleFor(a.height);
+  const bScale = scaleFor(b.height);
+  const aW = a.width * aScale, aH = a.height * aScale;
+  const bW = b.width * bScale, bH = b.height * bScale;
+  const outH = Math.max(aH, bH);
+  const outW = aW + gap + bW;
+  const out = new PNG({ width: outW, height: outH });
+  // Backdrop: a neutral dark gray so a black game frame is still distinguishable
+  // from the canvas, and the divider reads.
+  for (let i = 0; i < out.data.length; i += 4) {
+    out.data[i] = 0x20; out.data[i + 1] = 0x20; out.data[i + 2] = 0x20; out.data[i + 3] = 0xFF;
+  }
+  const blit = (pane, scale, dstX, dstW, dstH) => {
+    const offY = Math.floor((outH - dstH) / 2); // vertically center a shorter pane
+    for (let y = 0; y < dstH; y++) {
+      const srcY = Math.floor(y / scale);
+      for (let x = 0; x < dstW; x++) {
+        const srcX = Math.floor(x / scale);
+        const s = (srcY * pane.width + srcX) * 4;
+        const d = ((offY + y) * outW + (dstX + x)) * 4;
+        out.data[d] = pane.rgba[s];
+        out.data[d + 1] = pane.rgba[s + 1];
+        out.data[d + 2] = pane.rgba[s + 2];
+        out.data[d + 3] = 0xFF;
+      }
+    }
+  };
+  blit(a, aScale, 0, aW, aH);
+  blit(b, bScale, aW + gap, bW, bH);
+  return { buffer: PNG.sync.write(out), outW, outH, aScale, bScale };
+}
+
 export function registerFrameTools(server, z, sessionKey) {
   async function doStep({ frames }) {
       const host = getHost(sessionKey);
@@ -373,6 +446,334 @@ export function registerFrameTools(server, z, sessionKey) {
     return json;
   }
 
+  // op:'sideBySide' — capture BOTH hosts (slot A + slot B) into one composited
+  // PNG, A left, B right. The two-cores-in-one-call capture for the port-compare
+  // loop: load the original in slot A, the port in slot B, step both the same N
+  // frames, and look at them together. Also returns a per-pane pixel summary so
+  // a no-vision agent gets a structured "both alive? how different?" signal.
+  async function doSideBySide({ frames, path: outPath, inline }) {
+    requireImageTarget(outPath, inline, "frame({op:'sideBySide'})");
+    const hostA = getHost(sessionKey);   // throws with slot-A recovery guidance
+    const hostB = getHostB(sessionKey);  // throws with "load slot B" guidance
+    if (frames && frames > 0) {
+      // Step both the same amount so the comparison is at the same game time.
+      hostA.stepFrames(frames);
+      hostB.stepFrames(frames);
+    }
+    const a = hostA.screenshotRgba();
+    const b = hostB.screenshotRgba();
+    const { buffer, outW, outH, aScale, bScale } = compositeSideBySide(a, b);
+    const pngBase64 = buffer.toString("base64");
+    const panes = {
+      a: { platform: hostA.status.platform, frame: hostA.status.frameCount, scale: aScale, ...pixelSummary(a.width, a.height, a.rgba) },
+      b: { platform: hostB.status.platform, frame: hostB.status.frameCount, scale: bScale, ...pixelSummary(b.width, b.height, b.rgba) },
+    };
+    if (!inline) {
+      await writeFile(outPath, buffer);
+      const json = jsonContent({ path: outPath, width: outW, height: outH, layout: "A|B", panes });
+      // Show the human the composite (not either raw pane) on the livestream.
+      json._observerImages = [{ kind: "image", mimeType: "image/png", base64: pngBase64 }];
+      return json;
+    }
+    const tempPath = path.join(tmpdir(), `romdev-sidebyside-${hostA.status.platform ?? "a"}-vs-${hostB.status.platform ?? "b"}.png`);
+    try { await writeFile(tempPath, buffer); } catch { /* best-effort */ }
+    return {
+      content: [
+        imageContent(pngBase64),
+        { type: "text", text: `side-by-side ${outW}x${outH} — left: ${panes.a.platform} @frame ${panes.a.frame} (${panes.a.distinctColors} colors), right: ${panes.b.platform} @frame ${panes.b.frame} (${panes.b.distinctColors} colors). Also written to ${tempPath}.` },
+      ],
+      _observerImages: [{ kind: "image", mimeType: "image/png", base64: pngBase64 }],
+    };
+  }
+
+  // op:'compareRam' — the RAM-diff oracle. The STATE-level sibling of
+  // sideBySide: instead of comparing pixels, compare the work-RAM of slot A
+  // (the original) and slot B (the port) at the same game-moment. This is how a
+  // logic port is proven correct INDEPENDENT of graphics — if the two machines'
+  // RAM matches, the game logic is running identically even when one renders
+  // blank (no PPU shim yet).
+  //
+  // Designed for a "smart-enough, not frontier" agent: it does the byte-compare
+  // MECHANICALLY and returns a DIGESTED verdict — a match %, the diverging
+  // address RANGES (run-length-encoded, not raw bytes), and plain-language
+  // guidance — so the agent gets "addresses $0300-$0312 differ, likely your
+  // sprite table" instead of two 2KB hex blobs to eyeball.
+  // Core RAM comparison between the two slots for one region. Returns the raw
+  // numbers + RLE ranges; the op wrappers add verdict text. Shared by
+  // compareRam and portStatus. Throws if either slot lacks the region.
+  function computeRamMatch(region) {
+    const hostA = getHost(sessionKey);
+    const hostB = getHostB(sessionKey);
+    const sizeA = hostA.regionSize ? hostA.regionSize(region) : 0;
+    const sizeB = hostB.regionSize ? hostB.regionSize(region) : 0;
+    if (!sizeA || !sizeB) {
+      throw new Error(`region '${region}' not available on ${!sizeA ? "slot A (" + hostA.status.platform + ")" : "slot B (" + hostB.status.platform + ")"}. Both hosts must expose it; 'system_ram' is the portable default.`);
+    }
+    const len = Math.min(sizeA, sizeB);
+    const a = hostA.readMemory(region, 0, len);
+    const b = hostB.readMemory(region, 0, len);
+    const ranges = [];
+    let diffBytes = 0;
+    let runStart = -1;
+    for (let i = 0; i < len; i++) {
+      const differ = a[i] !== b[i];
+      if (differ) {
+        diffBytes++;
+        if (runStart < 0) runStart = i;
+      } else if (runStart >= 0) {
+        ranges.push({ start: runStart, end: i - 1, length: i - runStart });
+        runStart = -1;
+      }
+    }
+    if (runStart >= 0) ranges.push({ start: runStart, end: len - 1, length: len - runStart });
+    const matchPct = len ? Math.round(((len - diffBytes) / len) * 1000) / 10 : 100;
+    return { sizeA, sizeB, len, a, b, ranges, diffBytes, matchPct };
+  }
+
+  function compareRam({ region = "system_ram", frames, maxRanges = 24 }) {
+    const hostA = getHost(sessionKey);
+    const hostB = getHostB(sessionKey);
+    if (frames && frames > 0) { hostA.stepFrames(frames); hostB.stepFrames(frames); }
+
+    let m;
+    try { m = computeRamMatch(region); }
+    catch (e) { throw new Error(`frame({op:'compareRam'}): ${e.message}`); }
+    const { sizeA, sizeB, len, a, b, ranges, diffBytes, matchPct } = m;
+    // Keep the biggest diverging spans (most informative), cap the list.
+    const sorted = [...ranges].sort((x, y) => y.length - x.length);
+    const shown = sorted.slice(0, maxRanges).map((r) => ({
+      range: `$${r.start.toString(16).toUpperCase().padStart(4, "0")}-$${r.end.toString(16).toUpperCase().padStart(4, "0")}`,
+      bytes: r.length,
+      // a tiny sample so the agent can sanity-check WITHOUT a separate read
+      a: Buffer.from(a.subarray(r.start, Math.min(r.start + 4, r.end + 1))).toString("hex"),
+      b: Buffer.from(b.subarray(r.start, Math.min(r.start + 4, r.end + 1))).toString("hex"),
+    }));
+
+    const verdict =
+      diffBytes === 0
+        ? "IDENTICAL — slot A and slot B work-RAM match byte-for-byte. The port's logic is running exactly like the original at this moment."
+        : matchPct >= 95
+          ? `CLOSE (${matchPct}% match) — logic is largely tracking; ${ranges.length} diverging span(s). Inspect the ranges below (often graphics/timing scratch that doesn't affect logic). Read a range with memory({op:'read', region, offset}) on each slot to dig in.`
+          : `DIVERGED (${matchPct}% match) — the port's logic is NOT tracking the original. Step both from a known-identical point (state restore), then compareRam after a few frames to find WHERE they split. The first diverging span is usually the root cause.`;
+
+    return jsonContent({
+      op: "compareRam",
+      region,
+      a: { platform: hostA.status.platform, frame: hostA.status.frameCount, bytes: sizeA },
+      b: { platform: hostB.status.platform, frame: hostB.status.frameCount, bytes: sizeB },
+      comparedBytes: len,
+      matchPct,
+      identical: diffBytes === 0,
+      divergingBytes: diffBytes,
+      divergingSpans: ranges.length,
+      ranges: shown,
+      ...(ranges.length > shown.length ? { rangesOmitted: ranges.length - shown.length } : {}),
+      note: verdict,
+    });
+  }
+
+  // op:'findDiverge' — the ROOT-CAUSE finder. compareRam tells you slot A and
+  // slot B differ; this tells you EXACTLY WHEN and WHERE they first split. It
+  // snapshots both hosts, steps them in lockstep, and reports the first frame at
+  // which the work-RAM diverges + the first diverging byte address. A
+  // smart-enough agent shouldn't binary-search frames by hand — the tool does
+  // the search and hands back "frame 47, $0312 (A=05 B=07): that's where your
+  // port's logic split from the original."
+  //
+  // Both hosts' MACHINE STATE (RAM/CPU/PPU) is restored to the pre-search point
+  // afterward via unserializeState, so the agent keeps working from where it was.
+  // (The frameCount COUNTER keeps climbing — a known core behavior of
+  // unserializeState — but the actual emulated state is rewound.)
+  function findDiverge({ region = "system_ram", maxFrames = 600 }) {
+    const hostA = getHost(sessionKey);
+    const hostB = getHostB(sessionKey);
+    const sizeA = hostA.regionSize ? hostA.regionSize(region) : 0;
+    const sizeB = hostB.regionSize ? hostB.regionSize(region) : 0;
+    if (!sizeA || !sizeB) {
+      throw new Error(`frame({op:'findDiverge'}): region '${region}' not available on ${!sizeA ? "slot A (" + hostA.status.platform + ")" : "slot B (" + hostB.status.platform + ")"}. Both hosts must expose it; 'system_ram' is the portable default.`);
+    }
+    const len = Math.min(sizeA, sizeB);
+    // Save both so the search is non-destructive.
+    const saveA = hostA.serializeState();
+    const saveB = hostB.serializeState();
+    const startFrameA = hostA.status.frameCount;
+
+    const firstDiff = () => {
+      const a = hostA.readMemory(region, 0, len);
+      const b = hostB.readMemory(region, 0, len);
+      for (let i = 0; i < len; i++) if (a[i] !== b[i]) return { offset: i, a: a[i], b: b[i] };
+      return null;
+    };
+
+    let result;
+    // If they already differ at frame 0, that IS the divergence point.
+    let cur = firstDiff();
+    if (cur) {
+      result = { diverged: true, atFrame: 0, framesStepped: 0, offset: cur.offset, a: cur.a, b: cur.b };
+    } else {
+      // Step in lockstep, one frame at a time, until the first split or maxFrames.
+      let stepped = 0;
+      let found = null;
+      for (let f = 1; f <= maxFrames; f++) {
+        hostA.stepFrames(1);
+        hostB.stepFrames(1);
+        stepped = f;
+        cur = firstDiff();
+        if (cur) { found = { atFrame: f, offset: cur.offset, a: cur.a, b: cur.b }; break; }
+      }
+      result = found
+        ? { diverged: true, atFrame: found.atFrame, framesStepped: stepped, offset: found.offset, a: found.a, b: found.b }
+        : { diverged: false, framesStepped: stepped };
+    }
+
+    // Restore both hosts to where they were before the search.
+    try { hostA.unserializeState(saveA); } catch { /* best-effort */ }
+    try { hostB.unserializeState(saveB); } catch { /* best-effort */ }
+
+    const addrHex = result.offset != null ? "$" + result.offset.toString(16).toUpperCase().padStart(4, "0") : null;
+    return jsonContent({
+      op: "findDiverge",
+      region,
+      a: { platform: hostA.status.platform },
+      b: { platform: hostB.status.platform },
+      searchStartedAtFrame: startFrameA,
+      ...result,
+      ...(addrHex ? { address: addrHex } : {}),
+      note: result.diverged
+        ? `First divergence at frame ${result.atFrame} (relative to search start), address ${addrHex}: slot A = $${result.a.toString(16).padStart(2, "0")}, slot B = $${result.b.toString(16).padStart(2, "0")}. This is where the port's logic first split from the original — decompile/disasm around the code that writes ${addrHex} on BOTH sides to find why. Both hosts' machine state (RAM/CPU/PPU) restored to the pre-search point.`
+        : `No divergence in ${result.framesStepped} frames — the port's logic tracks the original across this window. Step further or raise maxFrames if you expect a later split. Both hosts' machine state restored to the pre-search point.`,
+    });
+  }
+
+  // op:'compareRender' — the PRESENTATION oracle. The graphics-side sibling of
+  // compareRam: instead of bytes, compare the decoded RENDERING STATE of slot A
+  // (original) vs slot B (port) — "BG enabled? which tilemap/palette? sprites
+  // on? forced blank?" This is what an agent building/tuning the graphics shim
+  // needs: it says exactly WHAT the port's presentation is missing vs. the
+  // original, in plain terms, without the agent decoding registers by hand.
+  //
+  // Works cross-platform: each side is decoded by its own platform's
+  // rendering-context decoder (NES PPU, SNES PPU, Genesis VDP, ...), then the
+  // human-readable `summary` lines are diffed. Same-platform ports get a literal
+  // line diff; cross-platform ports get both summaries side by side (the agent
+  // maps concepts, since e.g. "BG1 tile base" has no NES equivalent).
+  async function compareRender({ frames }) {
+    const hostA = getHost(sessionKey);
+    const hostB = getHostB(sessionKey);
+    if (frames && frames > 0) { hostA.stepFrames(frames); hostB.stepFrames(frames); }
+    const platA = hostA.status.platform;
+    const platB = hostB.status.platform;
+    let ctxA, ctxB;
+    try { ctxA = await getRenderingContextCore({ platform: platA, area: "all", host: hostA }); }
+    catch (e) { ctxA = { platform: platA, summary: [`(render-context decode unavailable: ${e.message})`] }; }
+    try { ctxB = await getRenderingContextCore({ platform: platB, area: "all", host: hostB }); }
+    catch (e) { ctxB = { platform: platB, summary: [`(render-context decode unavailable: ${e.message})`] }; }
+
+    const sumA = Array.isArray(ctxA.summary) ? ctxA.summary : [];
+    const sumB = Array.isArray(ctxB.summary) ? ctxB.summary : [];
+    const samePlatform = platA === platB;
+
+    let lineDiff = null;
+    if (samePlatform) {
+      // Literal line diff: what the original shows that the port doesn't (and vice versa).
+      const setB = new Set(sumB);
+      const setA = new Set(sumA);
+      lineDiff = {
+        onlyInOriginal: sumA.filter((l) => !setB.has(l)),
+        onlyInPort: sumB.filter((l) => !setA.has(l)),
+        matching: sumA.filter((l) => setB.has(l)).length,
+      };
+    }
+
+    // Per-slot render-enable verdict (reuse the same logic verify uses).
+    const flagsA = pickRenderFlags(ctxA);
+    const flagsB = pickRenderFlags(ctxB);
+
+    const note = samePlatform
+      ? (lineDiff.onlyInOriginal.length === 0 && lineDiff.onlyInPort.length === 0
+          ? "Rendering state MATCHES — same platform, identical decoded render context. The port's presentation tracks the original."
+          : `Rendering differs: ${lineDiff.onlyInOriginal.length} aspect(s) the ORIGINAL has that the port lacks (see onlyInOriginal — that's your shim's TODO list), ${lineDiff.onlyInPort.length} the port has extra. Fix the port until onlyInOriginal is empty.`)
+      : `Cross-platform port (${platA}→${platB}): the two render models differ by hardware, so compare the summaries conceptually. originalRenderEnabled=${flagsA.renderEnabled}, portRenderEnabled=${flagsB.renderEnabled}. If the original renders and the port is forced-blank/disabled, the graphics shim hasn't enabled output yet — that's step one.`;
+
+    return jsonContent({
+      op: "compareRender",
+      a: { platform: platA, renderEnabled: flagsA.renderEnabled, summary: sumA },
+      b: { platform: platB, renderEnabled: flagsB.renderEnabled, summary: sumB },
+      samePlatform,
+      ...(lineDiff ? { diff: lineDiff } : {}),
+      note,
+    });
+  }
+
+  // op:'portStatus' — the CAPSTONE. One call that runs all the compare signals
+  // (logic via RAM, presentation via render state, pixels via the content scan)
+  // and returns a SINGLE digested "state of your port" verdict with the next
+  // concrete action. For a smart-enough agent this collapses "which of the 4
+  // oracles do I run, in what order, and how do I read them together?" into one
+  // answer: "logic matches 100%, but the port renders blank → build the graphics
+  // shim; start by enabling display output."
+  async function portStatus({ frames, region = "system_ram" }) {
+    const hostA = getHost(sessionKey);
+    const hostB = getHostB(sessionKey);
+    if (frames && frames > 0) { hostA.stepFrames(frames); hostB.stepFrames(frames); }
+
+    // 1. Logic (RAM) — only meaningful for a SAME-platform port (cross-platform
+    //    RAM layouts differ, so a byte diff there isn't a logic verdict).
+    const samePlatform = hostA.status.platform === hostB.status.platform;
+    let logic = null;
+    if (samePlatform) {
+      try {
+        const m = computeRamMatch(region);
+        logic = { region, matchPct: m.matchPct, identical: m.diffBytes === 0, divergingBytes: m.diffBytes, divergingSpans: m.ranges.length };
+      } catch (e) { logic = { error: e.message }; }
+    }
+
+    // 2. Presentation (render state) — per-side render-enable.
+    let renderA, renderB;
+    try { renderA = pickRenderFlags(await getRenderingContextCore({ platform: hostA.status.platform, area: "all", host: hostA })); }
+    catch { renderA = { renderEnabled: null }; }
+    try { renderB = pickRenderFlags(await getRenderingContextCore({ platform: hostB.status.platform, area: "all", host: hostB })); }
+    catch { renderB = { renderEnabled: null }; }
+
+    // 3. Pixels — is each side drawing more than a flat color?
+    const pxA = pixelSummary(...rgbaTriple(hostA));
+    const pxB = pixelSummary(...rgbaTriple(hostB));
+    const aliveA = pxA.distinctColors > 2 && pxA.dominantPct < 99;
+    const aliveB = pxB.distinctColors > 2 && pxB.dominantPct < 99;
+
+    // Fuse into a single next-action verdict.
+    let verdict, nextAction;
+    if (samePlatform && logic && logic.identical) {
+      if (aliveB) { verdict = "PORT LOOKS COMPLETE"; nextAction = "Logic matches byte-for-byte AND the port renders. Spot-check with frame({op:'sideBySide'}) and move on."; }
+      else { verdict = "LOGIC DONE, PRESENTATION MISSING"; nextAction = "RAM matches the original exactly — the game logic is correct. The port renders blank: build/finish the graphics shim. Start with frame({op:'compareRender'}) to see what the original enables that the port doesn't."; }
+    } else if (samePlatform && logic && !logic.error) {
+      verdict = `LOGIC DIVERGED (${logic.matchPct}% RAM match)`;
+      nextAction = "The port's logic is NOT tracking the original. Run frame({op:'findDiverge'}) from a known-identical point to get the first frame+address where they split, then breakpoint({on:'write', address}) on each slot to compare the code.";
+    } else {
+      // cross-platform — RAM diff isn't a logic verdict; lean on render + pixels.
+      verdict = "CROSS-PLATFORM PORT";
+      nextAction = aliveB
+        ? "Both sides render — compare visually with frame({op:'sideBySide'}) and the decoded state with frame({op:'compareRender'}). RAM can't be byte-compared across different hardware."
+        : "The port renders blank while the original draws. The graphics shim hasn't enabled output — frame({op:'compareRender'}) shows what to turn on. Verify logic another way (the recompiled CPU should be running even when blank).";
+    }
+
+    return jsonContent({
+      op: "portStatus",
+      a: { platform: hostA.status.platform, frame: hostA.status.frameCount, renderEnabled: renderA.renderEnabled, pixelsAlive: aliveA },
+      b: { platform: hostB.status.platform, frame: hostB.status.frameCount, renderEnabled: renderB.renderEnabled, pixelsAlive: aliveB },
+      samePlatform,
+      ...(logic ? { logic } : {}),
+      verdict,
+      nextAction,
+    });
+  }
+
+  // Small helper: framebuffer RGBA as the (w,h,rgba) triple pixelSummary wants.
+  function rgbaTriple(host) {
+    const s = host.screenshotRgba();
+    return [s.width, s.height, s.rgba];
+  }
+
   async function doStepAndShot({ frames, path: outPath, inline }) {
       requireImageTarget(outPath, inline, "frame({op:'stepAndShot'})");
       const host = getHost(sessionKey);
@@ -395,7 +796,7 @@ export function registerFrameTools(server, z, sessionKey) {
 
   server.tool(
     "frame",
-    "Advance the emulator and capture frames. `op`: 'step' | 'screenshot' | 'stepAndShot' | 'stepInstruction' | 'verify'.\n" +
+    "Advance the emulator and capture frames. `op`: 'step' | 'screenshot' | 'stepAndShot' | 'sideBySide' | 'compareRam' | 'findDiverge' | 'compareRender' | 'portStatus' | 'stepInstruction' | 'verify'.\n" +
     "'step': advance N `frames` as fast as possible — NO pacing/audio/vsync. Cores run at WASM speed, so frames:3600 " +
     "(1 min of game time) finishes in ~5-30ms, cheaper than a screenshot. Don't be timid — skip a title with 300, a " +
     "level with 7200; prefer ONE big call.\n" +
@@ -406,6 +807,33 @@ export function registerFrameTools(server, z, sessionKey) {
     "format:'ascii' — BETTER, read the byte directly: symbols({op:'resolve', name}) → memory({op:'read'}) is a 1-byte " +
     "assertion that costs zero image tokens.**\n" +
     "'stepAndShot': step + screenshot in ONE round-trip — the drive-then-look loop. (No overlayBoxes/scale here — png only.)\n" +
+    "'sideBySide': capture BOTH hosts (slot A + the slot-B comparison host) into ONE composited PNG — A left, B right, " +
+    "divider between. The two-cores-in-one-call capture for the original-vs-port compare loop: loadMedia the original " +
+    "in slot A, loadMedia({slot:'b'}) the port, then frame({op:'sideBySide', frames}) steps BOTH the same N frames and " +
+    "shows them together. Panes are integer-upscaled to a shared height so a handheld next to a console reads at a " +
+    "comparable size. Returns per-pane {platform, frame, distinctColors, dominantColor, dominantPct} so a no-vision " +
+    "agent still gets a structured 'are both alive / how different' signal. Requires a ROM in slot B (loadMedia({slot:'b'})). " +
+    "Same image contract as screenshot (path or inline:true).\n" +
+    "'compareRam': the RAM-diff ORACLE — the STATE-level sibling of sideBySide. Compares the work-RAM (`region`, default " +
+    "'system_ram') of slot A vs slot B at the same game-moment to prove a logic PORT is correct INDEPENDENT of graphics " +
+    "(matching RAM = identical logic even when the port renders blank). Returns a DIGESTED verdict: matchPct, " +
+    "identical, and the diverging address RANGES run-length-encoded with a 4-byte sample of each side (NOT raw byte " +
+    "dumps) so even a small model gets '$0300-$0312 differ' not two hex blobs. Workflow: state-restore both to an " +
+    "identical point, step both N frames, compareRam — the FIRST diverging span is usually the bug. Requires slot B.\n" +
+    "'findDiverge': the ROOT-CAUSE finder built ON compareRam — where compareRam says THAT they differ, this says exactly " +
+    "WHEN and WHERE. Snapshots both slots, steps them in lockstep up to `maxFrames`, and reports the first frame + first " +
+    "byte address at which the work-RAM splits ({atFrame, address, a, b}). Non-destructive: both hosts are RESTORED to " +
+    "their pre-search state. Run it from a known-identical point (state-restore both first) so 'first split' is meaningful. " +
+    "The agent then disasms the code that writes that address on both sides. Requires slot B.\n" +
+    "'compareRender': the PRESENTATION oracle — compare the decoded RENDERING STATE of slot A vs slot B (BG/sprites " +
+    "enabled? which tilemap/palette? forced blank?) instead of bytes. This is what an agent building/tuning the graphics " +
+    "shim needs: it says in plain terms WHAT the port's presentation is missing vs. the original. Same-platform ports get " +
+    "a line diff (onlyInOriginal = your shim's TODO); cross-platform ports get both summaries + each side's renderEnabled " +
+    "verdict. Requires slot B.\n" +
+    "'portStatus': the CAPSTONE — ONE call that fuses logic (RAM), presentation (render state), and pixels into a single " +
+    "'state of your port' verdict + the next concrete action (e.g. 'LOGIC DONE, PRESENTATION MISSING → build the graphics " +
+    "shim, start with compareRender'). Use this FIRST when working a port to know what to do next; drill in with the " +
+    "specific compare ops. Requires slot B.\n" +
     "'stepInstruction': execute exactly ONE CPU instruction and stop (finer than 'step'); freezes the CPU one " +
     "instruction later and returns { pc }. Pair with cpu({op:'read'}) to watch registers change while tracing a routine.\n" +
     "'verify': one-call 'is the game actually rendering / alive?' health check WITHOUT vision — for the spiral where an " +
@@ -419,8 +847,11 @@ export function registerFrameTools(server, z, sessionKey) {
     "IMAGE CONTRACT (screenshot/stepAndShot): the image goes to `path` (default, returns {path}) OR inline:true — " +
     "you MUST pass one. Keeps PNGs out of context unless asked.",
     {
-      op: z.enum(["step", "screenshot", "stepAndShot", "stepInstruction", "verify"]).describe("step frames; capture a screenshot; step+capture in one call; single-step one CPU instruction; or verify the game is actually rendering/alive (no vision needed)."),
-      frames: z.number().int().min(1).max(1_000_000).default(1).describe("op=step/stepAndShot: frames to advance (1-1,000,000). 36000 (10 min) usually completes in <1s — don't be conservative."),
+      op: z.enum(["step", "screenshot", "stepAndShot", "sideBySide", "compareRam", "findDiverge", "compareRender", "portStatus", "stepInstruction", "verify"]).describe("step frames; capture a screenshot; step+capture in one call; capture both hosts side-by-side (A|B); compareRam = diff slot-A vs slot-B work-RAM (the logic-port oracle); findDiverge = find the first frame+byte where the two slots split (root-cause finder); compareRender = diff the decoded rendering state of the two slots (the presentation oracle); portStatus = ONE fused 'state of your port' verdict + next action (the capstone); single-step one CPU instruction; or verify the game is actually rendering/alive (no vision needed)."),
+      frames: z.number().int().min(1).max(1_000_000).default(1).describe("op=step/stepAndShot/sideBySide/compareRam/compareRender: frames to advance (1-1,000,000). For the slot-A/B compare ops, BOTH hosts step the same amount. 36000 (10 min) usually completes in <1s — don't be conservative."),
+      region: z.string().optional().describe("op=compareRam/findDiverge/portStatus: memory region to diff across the two slots (default 'system_ram', the portable work-RAM). Both hosts must expose it."),
+      maxRanges: z.number().int().min(1).max(256).default(24).describe("op=compareRam: cap on the diverging address ranges returned (largest first)."),
+      maxFrames: z.number().int().min(1).max(100000).default(600).describe("op=findDiverge: max frames to step in lockstep looking for the first divergence (default 600 = ~10s)."),
       format: z.enum(["png", "ascii"]).default("png").describe("op=screenshot: 'png' (default, real image) or 'ascii' (lossy text render)."),
       path: z.string().optional().describe("op=screenshot/stepAndShot: absolute path to write to (required unless inline:true)."),
       inline: z.boolean().default(false).describe("op=screenshot/stepAndShot: return the image in the response instead of writing to disk."),
@@ -436,6 +867,11 @@ export function registerFrameTools(server, z, sessionKey) {
         case "step":            return doStep(args);
         case "screenshot":      return doScreenshot(args);
         case "stepAndShot":     return doStepAndShot(args);
+        case "sideBySide":      return await doSideBySide(args);
+        case "compareRam":      return compareRam(args);
+        case "findDiverge":     return findDiverge(args);
+        case "compareRender":   return await compareRender(args);
+        case "portStatus":      return await portStatus(args);
         case "stepInstruction": return await stepInstructionCore(sessionKey);
         case "verify":          return await doVerify(args);
         default: throw new Error(`frame: unknown op '${args.op}'`);

package/src/mcp/tools/index.js

@@ -58,10 +58,39 @@ import { registerCheatTools } from "./cheats.js";
 import { createDisclosure } from "../disclosure.js";
 import { jsonContent, safeTool, withClearToolErrors } from "../util.js";
 import { getHostOrNull, setDisclosure } from "../state.js";
+import { da65Available } from "../../toolchains/cc65/da65.js";
 import { readFileSync } from "node:fs";
 import { fileURLToPath } from "node:url";
 import { dirname, join } from "node:path";
 
+/**
+ * The debug capabilities the LOADED core (and the installed toolchain) actually
+ * implement — so an agent picks a working trace strategy UP FRONT instead of
+ * discovering the gaps through a string of `notSupported` returns (each a wasted
+ * round trip). Capability varies by platform/core build and by whether the
+ * cc65/da65 toolchain is installed, so it can't be assumed. Surfaced in
+ * catalog({op:'status'}). Names are agent-facing (what you'd reach for), mapped
+ * to the host's existing *Supported() probes.
+ * @param {import("../../host/index.js").LibretroHost|null} host
+ */
+function hostCapabilities(host) {
+  const da65 = da65Available();
+  if (!host) return { da65Toolchain: da65 };
+  const has = (m) => { try { return !!host[m]?.(); } catch { return false; } };
+  return {
+    pcBreakpoint: has("pcBreakSupported"),       // breakpoint({on:'pc'})
+    watchpointExact: has("watchpointSupported"), // breakpoint({on:'write', precision:'exact'}) + condition filter
+    readWatch: has("readWatchSupported"),        // breakpoint({on:'read'})
+    rangeWatch: has("vramWatchSupported"),       // watch({on:'range'}) (VRAM-port trace)
+    registerWrite: has("setRegSupported"),       // register write + callSubroutine
+    registerSnapshot: has("regSnapSupported"),   // registersAtHit on a break
+    cheats: has("cheatsSupported"),              // cheats({op:'apply'}) via retro_cheat_set
+    diskImage: has("diskImageSupported"),        // C64 .d64 loadMedia
+    keyboard: has("keyboardSupported"),          // keyboard input (C64/MSX)
+    da65Toolchain: da65,                         // disasm({target:'rom'/'references'/...})
+  };
+}
+
 // Package version — surfaced by catalog({op:'status'}) so an agent can
 // check the running romdev version with a plain TOOL CALL (works over MCP AND the
 // HTTP/skill surface), e.g. to detect a saved skill is stale. (GET /healthz also
@@ -190,7 +219,7 @@ export function registerTools(server, z, sessionKey) {
     "• op:'status' — a snapshot of the current session: which platform's core/ROM is in the running host (if any), current frame count, last-loaded media, loaded categories. Call this when you've lost context across many tool calls and want to re-ground.",
     {
       op: z.enum(["categories", "status"]).default("categories")
-        .describe("categories=tool-category catalog; status=live session snapshot (romdevVersion + host/platform/frameCount/media — call this to check the running version, e.g. is a saved skill stale)."),
+        .describe("categories=tool-category catalog; status=live session snapshot (romdevVersion + host/platform/frameCount/media + a `capabilities` map of which debug ops the loaded core/toolchain implement — call this to check the running version or pick a working trace strategy before probing by failure)."),
     },
     safeTool(async ({ op = "categories" }) => {
       if (op === "status") {
@@ -206,6 +235,10 @@ export function registerTools(server, z, sessionKey) {
         return jsonContent({
           romdevVersion: PKG_VERSION,
           ...base,
+          // Which debug ops the loaded core + installed toolchain implement, so
+          // an agent picks a working trace strategy up front instead of probing
+          // by failure (~4 dead calls/session). v0.41.0 feedback #2 (002129).
+          capabilities: hostCapabilities(host),
           playtestWindowOpen: human.windowOpen,
           ...(human.windowOpen
             ? {