romdevtools 0.40.2 → 0.42.0

package/src/mcp/tools/lifecycle.js

@@ -1,5 +1,8 @@
 import { resolveCore } from "../../cores/registry.js";
-import { clearHost, getHost, getHostOrNull, rememberLastMedia, resetHost } from "../state.js";
+import {
+  clearHost, clearHostB, getHost, getHostB, getHostBOrNull, getHostOrNull,
+  rememberLastMedia, resetHost, resetHostB,
+} from "../state.js";
 import { jsonContent, safeTool, textContent } from "../util.js";
 import { resolveCheatCodeForApply } from "./cheats.js";
 import { attachObserverFrame } from "./watch-memory.js";
@@ -8,12 +11,16 @@ const MEDIA_KINDS = ["cartridge", "disk", "tape", "program"];
 
 export function registerLifecycleTools(server, z, sessionKey) {
   // Shared loader: accepts a file `path` OR base64 `bytes` (exactly one).
-  async function doLoadMedia({ platform, path, base64, mediaKind, virtualName, cheats }) {
+  // slot:'b' targets the secondary comparison host (for frame sideBySide);
+  // it gets its own fresh host and does NOT overwrite slot A's recovery
+  // breadcrumb, since B is transient scratch, not the session's main ROM.
+  async function doLoadMedia({ platform, path, base64, mediaKind, virtualName, cheats, slot }) {
     const resolved = resolveCore(platform);
     if (!resolved) throw new Error(`no core available for platform '${platform}'`);
     if (!path && !base64) throw new Error("loadMedia: provide either `path` (file on disk) or `base64` (ROM bytes).");
     if (path && base64) throw new Error("loadMedia: provide `path` OR `base64`, not both.");
-    const host = resetHost(sessionKey);
+    const slotB = slot === "b";
+    const host = slotB ? resetHostB(sessionKey) : resetHost(sessionKey);
     await host.loadCore(resolved.jsPath, resolved.wasmPath);
     const bytes = base64 ? new Uint8Array(Buffer.from(base64, "base64")) : undefined;
     await host.loadMedia({
@@ -47,10 +54,14 @@ export function registerLifecycleTools(server, z, sessionKey) {
     }
     // Remember what we loaded so a later host eviction (restart/reconnect) can
     // tell the agent the exact loadMedia call to recover with. Survives reset.
-    rememberLastMedia(sessionKey, {
-      platform,
-      ...(bytes ? { fromBase64: true } : { path: host.status.mediaPath ?? path }),
-    });
+    // Only for slot A — the breadcrumb is the primary ROM's recovery anchor;
+    // slot B is disposable comparison scratch and must not clobber it.
+    if (!slotB) {
+      rememberLastMedia(sessionKey, {
+        platform,
+        ...(bytes ? { fromBase64: true } : { path: host.status.mediaPath ?? path }),
+      });
+    }
 
     // Framebuffer dimensions are NOT known until the core has run at least one
     // frame — before that, fbWidth/fbHeight hold a pre-boot default (e.g.
@@ -59,10 +70,10 @@ export function registerLifecycleTools(server, z, sessionKey) {
     // on dimensions, so we omit it until a frame has been stepped and point the
     // caller at stepFrames instead.
     const framebufferKnown = host.status.frameCount > 0;
-    // Livestream: show what just loaded (the boot frame).
-    return attachObserverFrame(jsonContent({
+    const payload = jsonContent({
       loaded: true,
       platform,
+      ...(slotB ? { slot: "b" } : {}),
       core: resolved.coreName,
       mediaKind: host.status.mediaKind,
       ...(bytes ? { bytes: bytes.length } : { path: host.status.mediaPath }),
@@ -70,7 +81,12 @@ export function registerLifecycleTools(server, z, sessionKey) {
         ? { framebuffer: { width: host.status.fbWidth, height: host.status.fbHeight } }
         : { framebufferNote: "Framebuffer dimensions are unknown until the core runs — call stepFrames first, then getStatus (the pre-boot default does not match the real output resolution)." }),
       ...(appliedCheats ? { cheats: appliedCheats } : {}),
-    }), host, `loaded ${host.status.mediaPath ? host.status.mediaPath.split("/").pop() : platform}`);
+    });
+    // Livestream: only slot A drives the human's view (the session's main ROM).
+    // Slot B is comparison scratch — surfacing it would flip the livestream
+    // back and forth between two ROMs. frame({op:'sideBySide'}) is what shows B.
+    if (slotB) return payload;
+    return attachObserverFrame(payload, host, `loaded ${host.status.mediaPath ? host.status.mediaPath.split("/").pop() : platform}`);
   }
 
   server.tool(
@@ -79,6 +95,9 @@ export function registerLifecycleTools(server, z, sessionKey) {
     "Pass `path` (file on disk) OR `base64` (ROM bytes — e.g. straight from buildSource, no disk write, " +
     "for a fast iteration loop). `cheats` apply BEFORE the first frame (one call instead of loadMedia + " +
     "applyCheat), so a boot-time code that changes a value the reset code reads is in effect from frame 0. " +
+    "`slot:'b'` loads into the SECONDARY comparison host (a different platform is fine) so two cores can run " +
+    "at once for frame({op:'sideBySide'}) — the original-vs-port compare loop; slot B does not affect slot A " +
+    "or the livestream. " +
     "NOTE: framebuffer dimensions are omitted until you stepFrames — the pre-boot default does not match the " +
     "real output resolution.",
     {
@@ -88,6 +107,7 @@ export function registerLifecycleTools(server, z, sessionKey) {
       mediaKind: z.enum(MEDIA_KINDS).optional().describe("Default 'cartridge' for consoles, 'program' for C64."),
       virtualName: z.string().optional().describe("With `base64`: virtual filename shown to cores that fopen() the path (default '/rom')."),
       cheats: z.array(z.string()).max(64).optional().describe("Codes applied before the first frame (Game Genie / raw ADDR:VAL[:COMPARE] / native device codes). A raw ROM-address code is re-encoded to a read-intercept so it doesn't silently no-op. Returns a per-code `cheats:[{code, appliedAs, applied}]` report."),
+      slot: z.enum(["a", "b"]).default("a").describe("'a' (default) = the session's primary host (what every other tool uses). 'b' = the secondary comparison host used by frame({op:'sideBySide'}); load the second ROM here. Slot B is independent scratch — it keeps no recovery breadcrumb and never drives the livestream."),
     },
     safeTool(doLoadMedia),
   );
@@ -103,41 +123,50 @@ export function registerLifecycleTools(server, z, sessionKey) {
     "boot-seeded variables PERSIST). Pass `hard:true` for a TRUE power-cycle that reloads the ROM from scratch and " +
     "clears RAM + re-seeds boot state — use it when re-testing boot-time behavior (a soft reset boots the PREVIOUS " +
     "state).\n" +
-    "'pause': halt emulation (stepFrames returns 0 until resume). 'resume': continue.",
+    "'pause': halt emulation (stepFrames returns 0 until resume). 'resume': continue.\n" +
+    "`slot:'b'` targets the secondary comparison host (loaded via loadMedia({slot:'b'})). Slot-B ops never " +
+    "touch the livestream.",
     {
       op: z.enum(["unload", "shutdown", "reset", "pause", "resume"]).describe("unload media; shutdown the host; reset (soft/hard); pause; resume."),
       hard: z.boolean().default(false).describe("op=reset: true = full power-cycle (reload the ROM; clears work RAM + boot-seeded state). false (default) = soft RESET-button reset (RAM persists)."),
+      slot: z.enum(["a", "b"]).default("a").describe("'a' (default) = the primary host. 'b' = the secondary comparison host (frame sideBySide)."),
     },
-    safeTool(async ({ op, hard }) => {
+    safeTool(async ({ op, hard, slot }) => {
+      const slotB = slot === "b";
+      const get = slotB ? getHostB : getHost;
+      const getOrNull = slotB ? getHostBOrNull : getHostOrNull;
+      // Slot B never drives the human's livestream — wrap attachObserverFrame so
+      // slot-A behavior is unchanged but slot B stays silent.
+      const observe = slotB ? (content) => content : attachObserverFrame;
       switch (op) {
         case "unload": {
-          const host = getHostOrNull(sessionKey);
+          const host = getOrNull(sessionKey);
           if (!host || !host.status.loaded) {
             // Don't claim success when there was nothing loaded — that masks a
             // session/state mix-up (the agent thinks it unloaded media it never had).
-            return textContent("nothing to unload — no media is loaded in this session");
+            return textContent(`nothing to unload — no media is loaded in ${slotB ? "comparison slot B" : "this session"}`);
           }
           host.unloadMedia();
-          return textContent("unloaded");
+          return textContent(`unloaded${slotB ? " (slot B)" : ""}`);
         }
         case "shutdown":
-          clearHost(sessionKey);
-          return textContent("shutdown complete");
+          if (slotB) clearHostB(sessionKey); else clearHost(sessionKey);
+          return textContent(`shutdown complete${slotB ? " (slot B)" : ""}`);
         case "reset": {
-          const host = getHost(sessionKey);
+          const host = get(sessionKey);
           if (hard) {
             const reloaded = await host.hardReset();
-            return attachObserverFrame(textContent(reloaded ? "reset (hard / power-cycle — RAM cleared)" : "reset (soft — no cached ROM to reload for a hard reset)"), host, "reset (hard)");
+            return observe(textContent(reloaded ? "reset (hard / power-cycle — RAM cleared)" : "reset (soft — no cached ROM to reload for a hard reset)"), host, "reset (hard)");
           }
           host.reset();
-          return attachObserverFrame(textContent("reset (soft — RESET button; work RAM persists, use hard:true to clear it)"), host, "reset");
+          return observe(textContent("reset (soft — RESET button; work RAM persists, use hard:true to clear it)"), host, "reset");
         }
         case "pause":
-          getHost(sessionKey).pause();
-          return textContent("paused");
+          get(sessionKey).pause();
+          return textContent(`paused${slotB ? " (slot B)" : ""}`);
         case "resume":
-          getHost(sessionKey).resume();
-          return textContent("resumed");
+          get(sessionKey).resume();
+          return textContent(`resumed${slotB ? " (slot B)" : ""}`);
         default:
           throw new Error(`host: unknown op '${op}'`);
       }

package/src/mcp/tools/memory.js

@@ -542,7 +542,7 @@ async function memSearch(sessionKey, { value, size = 1, as = "raw", region = "sy
 // with searchNext compare:'dec'/'inc'/'unchanged'/'changed'/'gt'/'lt'. This is
 // the canonical "find the lives/score/timer address you can't see" loop, which
 // op:'search' (requires a value) can't do. (0.28.0 feedback #1.)
-async function memSearchUnknown(sessionKey, { size = 1, as = "raw", region = "system_ram", name = "default", maxCandidates = 64 }) {
+async function memSearchUnknown(sessionKey, { size = 1, as = "raw", region = "system_ram", name = "default", maxCandidates: _maxCandidates = 64 }) {
       const host = getHost(sessionKey);
       if (as === "digits") throw new Error("memory({op:'searchUnknown'}): as:'digits' needs a value; use as:'raw' or 'bcd' for an unknown-value hunt.");
       const info = REGION_INFO[region] ?? {};

package/src/mcp/tools/platform-tools.js

@@ -6,7 +6,7 @@ import { mkdir, readFile, writeFile } from "node:fs/promises";
 import path from "node:path";
 import { PNG } from "pngjs";
 import { getHost } from "../state.js";
-import { imageContent, jsonContent } from "../util.js";
+import { imageContent, jsonContent, unsupported } from "../util.js";
 
 // Consolidation: several handlers in this big shared file are extracted as
 // *Core functions that the consolidated domain tools (palette/tiles/background/
@@ -338,7 +338,10 @@ export function registerPlatformTools(server, z, sessionKey) {
         }, png);
       }
 
-      throw new Error(`inspectPalette not yet wired for platform '${p}'. Supported: nes, snes, genesis, sms, gg, gb, gbc, atari2600, atari7800, c64, gba, lynx, pce, msx.`);
+      unsupported(p, "inspectPalette", {
+        reason: "no palette decoder for this platform",
+        alternative: "platform({op:'capabilities'}) to see what's wired",
+      });
   };
 
   // getCPUState → cpu({op:'read'}) (router in watch-memory.js). Live-binding core.
@@ -347,7 +350,10 @@ export function registerPlatformTools(server, z, sessionKey) {
       const p = resolvePlatform(host, platform);
       const state = getCPUState(host, p, cpu);
       if (!state) {
-        throw new Error(`getCPUState: no decoder for platform '${p}' cpu '${cpu}'. Main CPU is wired for nes, snes, genesis, sms, gg, gb, gbc, atari2600, atari7800, c64, lynx, gba. Secondary CPUs: snes 'spc700' (genesis 'z80' not yet decoded).`);
+        unsupported(p, "cpuState", {
+          reason: `no ${cpu === "main" ? "main" : `'${cpu}'`}-CPU decoder for this platform`,
+          alternative: "platform({op:'capabilities'}) shows each platform's decoded CPUs (main + secondary); memory({op:'read'}) the raw CPU-register region otherwise",
+        });
       }
       return jsonContent({ platform: p, cpu, ...state });
   };
@@ -694,7 +700,10 @@ export function registerPlatformTools(server, z, sessionKey) {
         });
       }
 
-      throw new Error(`inspectSprites not yet wired for platform '${p}'. Supported: nes, snes, genesis, sms, gg, gb, gbc, atari2600, atari7800, c64, gba, pce, msx. (Lynx returns the SCB list head — it has no fixed OAM.)`);
+      unsupported(p, "inspectSprites", {
+        reason: "no sprite decoder for this platform",
+        alternative: "memory({op:'read'}) the raw OAM/sprite-attribute region, or platform({op:'capabilities'}) to see what's wired",
+      });
   };
 
   // inspectBackgroundMap lives in the `background` tool (rendering-context.js)
@@ -803,7 +812,10 @@ export function registerPlatformTools(server, z, sessionKey) {
         });
         return emitImage(r.png, `SNES BG map composite (${r.width}×${r.height}, ${r.mapWidth}×${r.mapHeight} tiles, ${r.bpp}bpp, tilemap@0x${tilemapBaseByte.toString(16)}, tiles@0x${tileBaseByte.toString(16)}). ${r.note}`);
       }
-      throw new Error(`inspectBackgroundMap not yet implemented for platform '${p}'`);
+      unsupported(p, "inspectBackground", {
+        reason: "no background-map snapshotter for this platform",
+        alternative: "background({view:'renderState'}) for the register-level context, or memory({op:'read'}) the raw VRAM/nametable region",
+      });
   };
 
   // convertImageToTiles → encodeArt({stage:'tiles'}) (router in sprite-pipeline.js).

package/src/mcp/tools/platforms.js

@@ -2,6 +2,7 @@ import { CORES, listAvailableCores, resolveCore } from "../../cores/registry.js"
 import { TOOLCHAINS } from "../../toolchains/registry.js";
 import { getLanguageOptions } from "../../toolchains/index.js";
 import { jsonContent, safeTool } from "../util.js";
+import { CAPABILITIES, CONTRACT_PLATFORMS, capabilitiesFor } from "../../cores/capabilities.js";
 import { listToolchainsCore, installToolchainCore } from "./toolchain.js";
 import { listPlatformDocsCore, getPlatformDocCore } from "./platform-docs.js";
 
@@ -99,11 +100,17 @@ export function resolvePlatformCore({ platform }) {
 export function registerPlatformTools(server, z) {
   server.tool(
     "platform",
-    "Platform/toolchain/docs discovery — what romdev can run and how. `op`: 'list' | 'resolve' | 'toolchains' | " +
-    "'docs' | 'doc'.\n" +
+    "Platform/toolchain/docs discovery — what romdev can run and how. `op`: 'list' | 'capabilities' | 'resolve' | " +
+    "'toolchains' | 'docs' | 'doc'.\n" +
     "'list': every platform with its emulator core, toolchain(s), available languages (+ documented default), and " +
     "platform-specific quirks. Call this FIRST to discover what's possible + check a non-default language is " +
     "available before asking build for it.\n" +
+    "'capabilities': the CAPABILITY CONTRACT — which platform-sensitive ops a platform supports (inspectSprites/" +
+    "Palette/Background, cpuState, audioDebug, renderingContext, cart, disasm, decompile), plus its cpuFamily, " +
+    "renderingKind (tile/framebuffer/3d), introspection depth, CPUs, audio chips, and memory regions. Pass `platform` " +
+    "for one, omit it for the whole matrix. Check this BEFORE calling a platform-sensitive tool to avoid an " +
+    "'unsupported' error — every tool that can't do an op on a platform returns {unsupported:true, platform, op, " +
+    "reason, alternative}.\n" +
     "'resolve': resolved core paths for a platform (debugging aid).\n" +
     "'toolchains': the bundled homebrew toolchains (all Tier-1 = bundled WASM, no install). Pass `id` to confirm a " +
     "specific toolchain's install status (a no-op in v1 — everything's bundled).\n" +
@@ -111,7 +118,7 @@ export function registerPlatformTools(server, z) {
     "troubleshooting / upstream_sources; `platform:'romhacking'` + `name:'playbook'` for the RE decision tree). " +
     "Read MENTAL_MODEL before writing code, and the romhacking playbook before a hack.",
     {
-      op: z.enum(["list", "resolve", "toolchains", "docs", "doc"]).describe("list=platforms; resolve=core paths; toolchains; docs=a platform's doc names; doc=read one doc."),
+      op: z.enum(["list", "capabilities", "resolve", "toolchains", "docs", "doc"]).describe("list=platforms; capabilities=per-platform op support matrix; resolve=core paths; toolchains; docs=a platform's doc names; doc=read one doc."),
       platform: z.string().optional().describe("op=resolve/docs/doc: platform id (e.g. nes, gb, genesis; 'romhacking' for the RE playbook)."),
       id: z.string().optional().describe("op=toolchains: a specific toolchain's install status (e.g. 'cc65')."),
       name: z.string().optional().describe("op=doc: which doc — mental_model | troubleshooting | upstream_sources | playbook."),
@@ -119,6 +126,14 @@ export function registerPlatformTools(server, z) {
     safeTool(async (args) => {
       switch (args.op) {
         case "list":    return jsonContent(listPlatformsCore());
+        case "capabilities": {
+          if (args.platform) {
+            const cap = capabilitiesFor(args.platform);
+            if (!cap) throw new Error(`platform({op:'capabilities'}): unknown platform '${args.platform}'. Known: ${CONTRACT_PLATFORMS.join(", ")}.`);
+            return jsonContent({ platform: args.platform, ...cap });
+          }
+          return jsonContent({ platforms: CONTRACT_PLATFORMS, capabilities: CAPABILITIES });
+        }
         case "resolve": {
           if (!args.platform) throw new Error("platform({op:'resolve'}): `platform` is required.");
           return jsonContent(resolvePlatformCore(args));

package/src/mcp/tools/playtest.js

@@ -5,7 +5,7 @@
 
 import { writeFile } from "node:fs/promises";
 
-import { getHost, getHostOrNull } from "../state.js";
+import { getHost, getHostOrNull, playtestCheckpointPath } from "../state.js";
 import { imageContent, jsonContent, safeTool, textContent } from "../util.js";
 import { log } from "../log.js";
 
@@ -169,6 +169,10 @@ export function registerPlaytestTools(server, z, sessionKey) {
       }
 
       const { playtest, KEYBOARD_BINDINGS_HELP, C64_BINDINGS_HELP } = await import("../../playtest/playtest.js");
+      // Where the rolling auto-checkpoint (eviction survivability) is written.
+      // Next to the ROM when it's a real file (so it's obvious + co-located); for
+      // base64/in-memory loads, a stable per-session file under the OS temp dir.
+      const autoCheckpointPath = playtestCheckpointPath(sessionKey, loadedMediaPath);
       let session;
       try {
         // Pass a live-host accessor so the window FOLLOWS rebuilds: runSource/
@@ -181,7 +185,9 @@ export function registerPlaytestTools(server, z, sessionKey) {
           scale,
           title,
           aspect,
+          autoCheckpointPath,
         });
+        session.autoCheckpointPath = autoCheckpointPath;
         sessions.set(sessionKey, session);
       } catch (e) {
         // Branch on WHY it failed — the cause is either the @kmamal/sdl native
@@ -265,6 +271,10 @@ export function registerPlaytestTools(server, z, sessionKey) {
         scale,
         aspect,
         controllerCount: session.controllerCount,
+        // Eviction survivability: while this window is open we roll a .state to
+        // disk so the human's manual progress survives a session eviction.
+        autoCheckpointPath,
+        autoCheckpointNote: `Progress auto-saves to ${autoCheckpointPath} every ~15s while the window is open (and on F2). If the session is evicted, state({op:'load', path}) it to restore the human's playthrough instead of replaying from boot.`,
         // C64 input is non-obvious (games need keyboard keys to START), so ALWAYS
         // relay the controls — a controller alone IS enough (spare buttons/stick
         // map to F1/Run-Stop/Space/Return), and the keyboard fallback covers the
@@ -345,6 +355,19 @@ export function registerPlaytestTools(server, z, sessionKey) {
             "loadMedia swapped it). frame({op:'screenshot'}) now shows the active host, NOT " +
             "what the human sees. Call playtest({op:'framebuffer'}) to capture the human's window.",
         }),
+        // Eviction survivability: where the human's progress auto-saves, and
+        // whether the last write failed (so an agent can warn + suggest a manual
+        // state({op:'save', path}) if the rolling checkpoint isn't landing).
+        ...((() => {
+          const ck = session.lastCheckpoint?.();
+          if (!ck || !ck.path) return {};
+          return {
+            autoCheckpointPath: ck.path,
+            ...(ck.lastError
+              ? { autoCheckpointError: ck.lastError, autoCheckpointHint: "The rolling auto-checkpoint is FAILING — the human's progress is NOT being saved. Have them pick a writable spot: state({op:'save', path}) manually." }
+              : { autoCheckpointNote: "The human's progress auto-saves here every ~15s (and on F2); survives a session eviction via state({op:'load', path})." }),
+          };
+        })()),
       });
   }
 

package/src/mcp/tools/project.js

@@ -2698,7 +2698,7 @@ ${buildBlock}
   };
 }
 
-async function createGameCore({ platform, genre, name, path: projPath, title, overwrite, verbose = false }) {
+async function _createGameCore({ platform, genre, name, path: projPath, title, overwrite, verbose = false }) {
       // The five canonical genres. A genre is available on a platform iff
       // TEMPLATES[platform] has a matching template entry — we DERIVE
       // availability from TEMPLATES rather than maintain a parallel table,

package/src/mcp/tools/rendering-context.js

@@ -9,7 +9,7 @@
 
 import { readFileSync } from "node:fs";
 import { getHost } from "../state.js";
-import { jsonContent, safeTool } from "../util.js";
+import { jsonContent, safeTool, unsupported } from "../util.js";
 import { inspectBackgroundMapCore } from "./platform-tools.js";
 import { whichTilesAreRenderedCore } from "./which-tiles.js";
 
@@ -507,8 +507,10 @@ async function gbContext(host, area, platform) {
   };
 }
 
-export async function getRenderingContextCore({ platform, area = "all", sessionKey }) {
-  const host = getHost(sessionKey);
+export async function getRenderingContextCore({ platform, area = "all", sessionKey, host: explicitHost }) {
+  // `host` lets a caller (e.g. frame compareRender) decode a SPECIFIC host —
+  // the slot-B comparison host — instead of the session's slot-A default.
+  const host = explicitHost ?? getHost(sessionKey);
   const p = platform ?? host.getStatus().platform;
   switch (p) {
     case "nes": return nesContext(host, area);
@@ -530,9 +532,10 @@ export async function getRenderingContextCore({ platform, area = "all", sessionK
     case "pce":   return pceContext(host, area);
     case "msx":   return msxContext(host, area);
     default:
-      throw new Error(
-        `getRenderingContext: unknown platform '${p}'. Supported: nes, snes, genesis, gb, gbc, sms, gg, atari2600, atari7800, c64, gba, lynx, pce, msx.`
-      );
+      unsupported(p, "renderingContext", {
+        reason: "no rendering-context decoder for this platform",
+        alternative: "platform({op:'capabilities'}) to see what's wired",
+      });
   }
 }