romdevtools 0.41.0 → 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/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

@@ -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);

package/src/mcp/tools/watch-memory.js

@@ -17,11 +17,87 @@ import path from "node:path";
 import { getHost } from "../state.js";
 import { jsonContent, safeTool } from "../util.js";
 import { getCPUState } from "../../host/cpu-state.js";
-import { MemoryRegionToRetro } from "../../host/types.js";
 import { resolveButtonAlias } from "./input.js";
 import { getCPUStateCore } from "./platform-tools.js";
 import { traceVramSourceCore } from "./trace-vram-source.js";
 import { resolveStatePath } from "./state.js";
+import { buildBacktrace } from "../../analysis/backtrace.js";
+import { mapNesAddress } from "./disasm.js";
+import { MemoryRegionToRetro } from "../../host/types.js";
+
+/**
+ * Build the decoded call stack for a breakpoint hit: who called the routine the
+ * PC is in. Uses the captured register snapshot's stack pointer + the stack RAM.
+ * Returns null when unavailable (unsupported ISA / no regs) — never throws.
+ * @param {import("../../host/index.js").LibretroHost} host
+ * @param {Object|null} regs   the `named` register snapshot (has the stack ptr)
+ */
+function backtraceForHit(host, regs) {
+  if (!regs) return null;
+  const platform = host.status?.platform;
+
+  // 6502: validate the $20 (JSR) opcode at each candidate caller PC by mapping the
+  // CPU address to a ROM byte. NES uses the cart image + the mapper.
+  let readByteAt = null;
+  if (platform === "nes") {
+    try {
+      const cart = host.getCartRom();
+      readByteAt = (cpuAddr) => {
+        try {
+          const { bytes } = mapNesAddress(cart.raw, cpuAddr, 1);
+          return bytes && bytes.length ? bytes[0] : null;
+        } catch { return null; }
+      };
+    } catch { /* no cart / mapping — frames stay best-effort */ }
+  }
+
+  // Z80/SM83 + m68k stacks live in WORK RAM at the SP (not a fixed page). Read the
+  // stack via system_ram using the platform's CPU-addr→RAM mask (the same mapping
+  // the callSubroutine watchdog uses). Best-effort: return null on any read miss.
+  const ramMask = platform === "genesis" ? 0xffff
+    : (platform === "gb" || platform === "gbc" || platform === "sms" || platform === "gg" || platform === "msx") ? 0x1fff
+      : 0xffff;
+  const readRamByte = (cpuAddr) => {
+    try {
+      const b = host.readMemory("system_ram", cpuAddr & ramMask, 1);
+      return b && b.length ? b[0] : null;
+    } catch { return null; }
+  };
+  const readCpuWord = (cpuAddr) => {
+    const lo = readRamByte(cpuAddr); const hi = readRamByte(cpuAddr + 1);
+    return (lo == null || hi == null) ? null : (lo | (hi << 8));
+  };
+  const readCpuLongBE = (cpuAddr) => {
+    const b0 = readRamByte(cpuAddr), b1 = readRamByte(cpuAddr + 1), b2 = readRamByte(cpuAddr + 2), b3 = readRamByte(cpuAddr + 3);
+    return (b0 == null || b1 == null || b2 == null || b3 == null) ? null : ((b0 << 24) | (b1 << 16) | (b2 << 8) | b3) >>> 0;
+  };
+
+  const bt = buildBacktrace({
+    platform,
+    regs,
+    readMemory: (region, off, len) => host.readMemory(region, off, len),
+    readByteAt,
+    readCpuWord,
+    readCpuLongBE,
+  });
+  if (!bt || !bt.frames.length) return null;
+  const pad = bt.isa === "m68k" ? 6 : 4; // 24-bit m68k addresses print wider
+  const isaNote = {
+    "6502": "confident=true means the byte before the return target is a JSR ($20).",
+    sm83: "confident=true means the return address lands in a plausible code range (SM83 call frames are 2-byte LE; the call's own length isn't recovered, so callerPc IS the return address).",
+    z80: "confident=true means the return address lands in a plausible code range (Z80 call frames are 2-byte LE; callerPc IS the return address).",
+    m68k: "confident=true means the return longword is even + in-range (m68k jsr/bsr push a 4-byte BE return; callerPc IS the return address).",
+  }[bt.isa] || "";
+  return {
+    isa: bt.isa,
+    frames: bt.frames.map((f) => ({
+      callerPc: "$" + f.callerPc.toString(16).toUpperCase().padStart(pad, "0"),
+      returnAddr: "$" + f.returnAddr.toString(16).toUpperCase().padStart(pad, "0"),
+      confident: f.confident,
+    })),
+    note: `callStack[0] is the immediate caller (the call that reached this routine), decoded from the stack at the break instant. ${isaNote} Generated server-side — no hand stack-walking.`,
+  };
+}
 
 // Restore a savestate (in-memory slot `fromState` OR disk file `fromStatePath`)
 // before a trace, so on:'range'/'pc' run from a known moment. Returns a small
@@ -130,13 +206,11 @@ export function makePressDriver(host, presses) {
   };
 }
 
-// Single source of truth: the same canonical region vocabulary readMemory
-// uses (host/types.js). Previously this was a hand-maintained list that had
-// drifted — it carried DEAD Genesis `md_*` names (which throw on read) and
-// was MISSING nes_apu_regs / genesis_* / c64_*, so you couldn't watch the
-// hardware-register regions readMemory could already read. Deriving from the
-// host map means new regions flow through automatically and the two tools can
-// never disagree again.
+// Single source of truth: the same canonical region vocabulary readMemory uses
+// (host/types.js). Derived from the host map so new regions flow through
+// automatically and the two tools never disagree. Used by the ONE primary
+// `on:'mem'` region enum (kept discoverable on purpose); every SECONDARY region
+// sub-param uses the lean regionStr string instead (0.28.0/0.30.0 feedback #5).
 const MEMORY_REGIONS = /** @type {[string, ...string[]]} */ (Object.keys(MemoryRegionToRetro));
 
 // A region param that does NOT inline the full ~62-value enum into the JSON
@@ -624,6 +698,7 @@ export function registerWatchMemoryTools(server, z, sessionKey) {
         hits: result.hits,
         framesStepped: result.framesStepped,
         ...(wpRegs ? { registersAtHit: wpRegs } : {}),
+        ...((() => { const bt = backtraceForHit(host, wpRegs); return bt ? { callStack: bt } : {}; })()),
         ...(bankInfo ? bankInfo : {}),
         ...(presses.length ? { pressesScheduled: presses.length, pressesApplied: pressDriver.applied() } : {}),
         note: "pc is the EXACT writing instruction (captured in the CPU write path), not a frame sample. " +
@@ -782,6 +857,7 @@ export function registerWatchMemoryTools(server, z, sessionKey) {
         pc: last.lastPC != null ? "$" + last.lastPC.toString(16).toUpperCase() : null,
         pcRaw: last.lastPC,
         ...(atHit ? { registersAtHit: atHit } : {}),
+        ...((() => { const bt = backtraceForHit(host, atHit); return bt ? { callStack: bt } : {}; })()),
         ...(capturedMemory ? { capturedMemory } : {}),
         frame: host.status.frameCount,
         framesRun,
@@ -1292,7 +1368,9 @@ export function registerWatchMemoryTools(server, z, sessionKey) {
     {
       on: z.enum(["mem", "range", "pc", "dma", "copy"])
         .describe("mem=watch a RAM byte/ranges for value changes over frames (the power tool); range=log every read/write PC in [start,end]; pc=coverage trace of distinct PCs executed in [start,end]; dma=Genesis-only mem→VDP DMA source/dest trace; copy=log every write landing in a VRAM address window with the EXECUTING instruction's PC (all 14 platforms — the generic 'where does this graphic come from?')."),
-      // on:'mem'
+      // on:'mem' — the ONE primary region enum kept on purpose (0.30.0 design):
+      // where region IS the choice, the discoverable canonical list stays in the
+      // schema. The secondary region sub-params use the lean regionStr instead.
       region: z.enum(MEMORY_REGIONS).optional().describe("on:'mem' single-range — the region to watch (same canonical set memory uses, incl. nes_apu_regs, genesis_ym2612, c64_sid_regs). Omit when using `ranges`."),
       offset: z.number().int().min(0).default(0).describe("on:'mem' single-range — first byte of the watched range."),
       length: z.number().int().min(1).max(4096).default(1).describe("on:'mem' single-range — bytes to watch (default 1)."),

package/src/mcp/util.js

@@ -212,15 +212,60 @@ export function withClearToolErrors(server, z) {
   return server;
 }
 
+// ── Hex-string coercion on address-like params ─────────────────────
+// JSON forbids `0x…` number literals, so an agent that pastes an address as hex
+// (`{address: 0xC06C}`) gets a HARD parse error, and even valid JSON can't carry
+// hex. We accept the STRING forms `"0x…"`, `"$…"`, and decimal strings on
+// address-like params and coerce them to a number BEFORE validation, so the
+// natural thing an agent reaches for just works. (Reported repeatedly in v0.41.0
+// feedback as the #1 first-try-fail.)
+//
+// Matched by KEY NAME (not schema introspection — robust across zod versions).
+// DELIBERATELY NARROW: only names that are unambiguously a numeric address/offset
+// across the toolset. Names like `start`/`end`/`from`/`to`/`target`/`compare` are
+// EXCLUDED because they're also booleans (the START button) or enums (`compare:'eq'`,
+// `from:'aseprite'`); the coercer passes non-hex strings through, but not wrapping
+// them at all keeps those schemas pristine. Address-suffixed forms (`startAddress`,
+// `endAddress`) DO match and cover the range-bound case.
+const ADDR_KEY_RE = /^(address|cpuAddress|addr|offset|pc|compare|startAddress|endAddress|baseAddress|targetAddress|fromAddress|toAddress|romOffset|prgOffset|vramAddr)$/i;
+
+/** Coerce `"0x1A"` / `"$1A"` / `"26"` → number; pass through numbers/undefined/
+ *  non-hex strings unchanged (so a non-numeric value still hits the real schema
+ *  error). Exported for unit tests. */
+export function coerceHexNumber(v) {
+  if (typeof v !== "string") return v;
+  const s = v.trim();
+  if (/^[$]([0-9a-fA-F]+)$/.test(s)) return parseInt(s.slice(1), 16);
+  if (/^0x[0-9a-fA-F]+$/i.test(s)) return parseInt(s, 16);
+  if (/^-?\d+$/.test(s)) return parseInt(s, 10);
+  return v; // leave anything else for the inner schema to reject
+}
+
 /**
  * Build a `.strict()` z.object from a tool's shape whose validation issues each
  * render as a clear sentence (unknown-key "did you mean", enum options, missing
  * required, wrong type). Used by withClearToolErrors to replace the stored schema.
+ * Also wraps address-like params with hex-string coercion (see coerceHexNumber).
  * @param {any} z
  * @param {Record<string, any>} shape
  * @param {string} toolName
  */
 function strictFriendlyObject(z, shape, toolName) {
+  // Wrap address-like fields with a hex-string→number preprocessor. z.preprocess
+  // runs the coercion first, then the field's own schema (number().int()…)
+  // validates the result — so descriptions, optionality, and ranges are preserved.
+  const coercedShape = {};
+  for (const [key, schema] of Object.entries(shape)) {
+    if (ADDR_KEY_RE.test(key)) {
+      // z.preprocess drops the wrapper's .description (which tools/list needs),
+      // so re-attach the field's own description to the wrapped schema.
+      const wrapped = z.preprocess(coerceHexNumber, schema);
+      coercedShape[key] = schema.description ? wrapped.describe(schema.description) : wrapped;
+    } else {
+      coercedShape[key] = schema;
+    }
+  }
+  shape = coercedShape;
   const validKeys = Object.keys(shape);
   const errorMap = (issue) => {
     switch (issue.code) {