romdevtools 0.29.0 → 0.30.0

package/src/mcp/tools/memory.js

@@ -3,6 +3,7 @@ import { MemoryRegionToRetro } from "../../host/types.js";
 import { jsonContent, safeTool, textContent, writeOutput } from "../util.js";
 import { classifyBytes } from "./classify-region.js";
 import { clusterChanges } from "./diff-cluster.js";
+import { mapNesAddress, mapSnesAddress } from "./disasm.js";
 
 // Small reads stay inline (hex) for ergonomics; large reads must go to disk
 // (raw bytes) unless inline:true. The common case — peeking a few bytes of
@@ -193,9 +194,41 @@ async function memWrite(sessionKey, { region, offset = 0, hex, base64, data, byt
       return textContent(`wrote ${buf.length} bytes to ${region}+${offset}`);
 }
 
-async function memReadCart(sessionKey, { offset = 0, length = 16, outputPath, inline, echo }) {
+async function memReadCart(sessionKey, { offset = 0, length = 16, cpuAddress, bank, mapper, outputPath, inline, echo }) {
       const host = getHost(sessionKey);
       const rom = host.getCartRom();
+
+      // Banked CPU-address read (0.28.0 feedback #2a): map {cpuAddress, bank?} →
+      // PRG bytes, the inverse of the breakpoint result's bank/prgOffset. Saves
+      // the caller the hand-computed `cpuAddr - 0x8000 + bank*0x4000` arithmetic
+      // that bit them twice. NES + SNES today (reuses the disasm mappers).
+      if (cpuAddress != null) {
+        let m;
+        if (rom.platform === "nes") {
+          m = mapNesAddress(rom.raw, cpuAddress >>> 0, length, bank);
+        } else if (rom.platform === "snes") {
+          m = mapSnesAddress(rom.raw, cpuAddress >>> 0, length, mapper);
+        } else {
+          throw new Error(`memory({op:'readCart', cpuAddress}): banked CPU-address mapping is NES/SNES only (got '${rom.platform}'). Use a flat 'offset' for this platform.`);
+        }
+        const hex = Array.from(m.bytes, (b) => b.toString(16).padStart(2, "0")).join("");
+        const meta = {
+          platform: rom.platform,
+          cpuAddress: "0x" + (cpuAddress >>> 0).toString(16).toUpperCase(),
+          ...(bank != null ? { bank } : {}),
+          fileOffset: "0x" + m.fileOffset.toString(16).toUpperCase(),
+          prgOffset: "0x" + (m.fileOffset - (m.prgFileStart ?? 0)).toString(16).toUpperCase(),
+          length: m.bytes.length,
+          note: m.note,
+        };
+        if (outputPath) {
+          const { path, bytes: written } = writeOutput(Uint8Array.from(m.bytes), { outputPath, what: "readCartRom" });
+          if (echo === false) return jsonContent({ ...meta, path, bytes: written });
+          return jsonContent({ ...meta, path, bytes: written, hex });
+        }
+        return jsonContent({ ...meta, hex });
+      }
+
       if (offset >= rom.bytes.length) {
         throw new Error(`readCartRom: offset ${offset} is past the end of the ${rom.platform} ROM (size ${rom.bytes.length}, header skipped ${rom.headerSkipped}).`);
       }
@@ -293,23 +326,38 @@ async function memDiffRuns(sessionKey, { region, frames = 60, portsA, portsB, of
       });
 }
 
-async function memDiff(sessionKey, { region, name = "default", view = "summary", maxChanges = 4096, maxClusters = 64, gap = 4, minDelta }) {
+async function memDiff(sessionKey, { region, name = "default", view = "summary", maxChanges = 4096, maxClusters = 64, gap = 4, minDelta, changeDir, beforeMin, beforeMax, afterMin, afterMax, deltaEq, outputPath, echo = true }) {
       const host = getHost(sessionKey);
       const snap = memSnapshots(sessionKey).get(snapKey(region, name));
       if (!snap) throw new Error(`memory({op:'diff'}): no snapshot named '${name}' for region '${region}'. Call memory({op:'snapshot', region, name}) first.`);
       const now = host.readMemory(region, snap.offset, snap.bytes.length);
 
-      // Collect changed offsets once. minDelta filters OUT small wiggles
-      // (|after - before| < minDelta) so "find the position byte amid OAM/RNG
-      // churn" is one cheap call instead of a raw dump + client-side filtering
-      // (0.27.0 feedback #5).
+      // Collect changed offsets once, applying server-side predicate filters so
+      // the lives/score/ammo hunt is ONE call instead of dumping the whole diff
+      // and filtering client-side (0.28.0 feedback #3). All filters AND together:
+      //   minDelta   — |after-before| >= minDelta (drop small wiggles; 0.27.0 #5)
+      //   changeDir  — 'dec' (after<before) | 'inc' (after>before)
+      //   deltaEq    — after-before === deltaEq EXACTLY (signed; e.g. -1 for "lost one life")
+      //   beforeMin/Max, afterMin/Max — value-range gates on the old/new byte
+      // Example: a 537-byte death diff → the ~3 "decreased by exactly 1 from a
+      // small value" rows with {changeDir:'dec', beforeMax:9, deltaEq:-1}.
       const changedOffsets = [];
       for (let i = 0; i < snap.bytes.length; i++) {
-        if (snap.bytes[i] === now[i]) continue;
-        if (minDelta != null && Math.abs(now[i] - snap.bytes[i]) < minDelta) continue;
+        const b = snap.bytes[i], a = now[i];
+        if (b === a) continue;
+        if (minDelta != null && Math.abs(a - b) < minDelta) continue;
+        if (changeDir === "dec" && !(a < b)) continue;
+        if (changeDir === "inc" && !(a > b)) continue;
+        if (deltaEq != null && (a - b) !== deltaEq) continue;
+        if (beforeMin != null && b < beforeMin) continue;
+        if (beforeMax != null && b > beforeMax) continue;
+        if (afterMin != null && a < afterMin) continue;
+        if (afterMax != null && a > afterMax) continue;
         changedOffsets.push(i);
       }
       const changedCount = changedOffsets.length;
+      const filtered = (changeDir != null || deltaEq != null || beforeMin != null ||
+        beforeMax != null || afterMin != null || afterMax != null);
 
       if (view === "raw") {
         const changes = changedOffsets.slice(0, maxChanges).map((i) => ({
@@ -318,11 +366,13 @@ async function memDiff(sessionKey, { region, name = "default", view = "summary",
           before: snap.bytes[i].toString(16).padStart(2, "0"),
           after: now[i].toString(16).padStart(2, "0"),
         }));
-        return jsonContent({
+        const result = {
           region, name, view, baseOffset: snap.offset, length: snap.bytes.length,
-          changedCount, changes,
-          ...(changedCount > changes.length ? { truncated: true, note: `${changedCount} bytes changed; showing first ${changes.length} (raise maxChanges).` } : {}),
-        });
+          ...(filtered ? { filterMatches: changedCount } : { changedCount }),
+          changes,
+          ...(changedCount > changes.length ? { truncated: true, note: `${changedCount} ${filtered ? "matching " : ""}bytes changed; showing first ${changes.length} (raise maxChanges).` } : {}),
+        };
+        return diffOut(result, { outputPath, echo, region, heavyKey: "changes", count: changedCount });
       }
 
       // SUMMARY: cluster adjacent changes (within `gap`) into ranges + stride.
@@ -353,18 +403,33 @@ async function memDiff(sessionKey, { region, name = "default", view = "summary",
         }
         return entry;
       });
-      return jsonContent({
+      const result = {
         region, name, view, baseOffset: snap.offset, length: snap.bytes.length,
-        changedCount, clusterCount: clusters.length,
+        ...(filtered ? { filterMatches: changedCount } : { changedCount }), clusterCount: clusters.length,
         clusters: out,
         ...(stride !== null ? { stride: "0x" + stride.toString(16), strideHint: strideNote } : {}),
         ...(clusters.length > out.length ? { truncated: true } : {}),
         note: changedCount === 0
-          ? "Nothing changed."
-          : `${changedCount} bytes changed in ${clusters.length} cluster(s). ` +
+          ? (filtered ? "No changed byte matched the filters (try loosening changeDir/deltaEq/before*/after*)." : "Nothing changed.")
+          : `${changedCount} ${filtered ? "matching " : ""}bytes changed in ${clusters.length} cluster(s). ` +
             (stride !== null ? strideNote + " " : "") +
-            "Use view:'raw' for exact before/after bytes (or narrow with a tighter event window). For 'find the address of value X' use memory({op:'search'}), not diff.",
-      });
+            "Use view:'raw' for exact before/after bytes (or narrow with a tighter event window / the changeDir/deltaEq/before*/after* filters). For 'find the address of value X' use memory({op:'search'}), not diff.",
+      };
+      return diffOut(result, { outputPath, echo, region, heavyKey: "clusters", count: changedCount });
+}
+
+// Honor outputPath/echo for diff results, mirroring memRead (0.28.0 feedback
+// #2): write the FULL JSON to outputPath regardless of size; with echo:false
+// return only the slim envelope (counts + path), dropping the heavy array so a
+// large diff never streams through context.
+function diffOut(result, { outputPath, echo, region, heavyKey, count }) {
+  if (!outputPath) return jsonContent(result);
+  const { path, bytes } = writeOutput(JSON.stringify(result, null, 2), { outputPath, what: `diff(${region})` });
+  if (echo === false) {
+    const { [heavyKey]: _omit, ...slim } = result;
+    return jsonContent({ ...slim, path, bytes, echo: false, note: `Full diff written to ${path} (${count} changes); '${heavyKey}' omitted (echo:false).` });
+  }
+  return jsonContent({ ...result, path, bytes });
 }
 
 // diffState lives in the `state` tool (state({op:'diff'})).
@@ -471,6 +536,37 @@ async function memSearch(sessionKey, { value, size = 1, as = "raw", region = "sy
       });
 }
 
+// op:'searchUnknown' — the Cheat-Engine UNKNOWN-INITIAL-VALUE hunt: seed the
+// candidate set to the WHOLE region (every size-aligned offset, baselined to
+// its current value), with NO value filter. Then narrow across in-game events
+// 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 }) {
+      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] ?? {};
+      const little = (info.endianness ?? genericEndianness(host.status.platform)) !== "big";
+      const buf = host.readMemory(region, 0, regionLength(host, region, 0));
+      const s = { region, size, little, as, digitLen: 0 };
+      // Seed EVERY size-aligned offset; baseline each to its current decoded
+      // value so the first searchNext relative compare works immediately.
+      const candidates = [];
+      const prevMap = new Map();
+      for (let i = 0; i + size <= buf.length; i += size) {
+        const cur = decodeAt(buf, i, s);
+        if (cur === null) continue;
+        candidates.push(i);
+        prevMap.set(i, cur);
+      }
+      searchSessions(sessionKey).set(name, { ...s, addrs: Uint32Array.from(candidates), prev: prevMap, kMap: null });
+      return jsonContent({
+        searchId: name, region, size, as, mode: "unknown",
+        count: candidates.length,
+        note: `Seeded ${candidates.length} candidates (the whole region, no value filter). Now cause the value to change in-game, then narrow with memory({op:'searchNext', name:'${name}', compare:'dec'|'inc'|'unchanged'|'changed'|'gt'|'lt'}) — e.g. 'dec' after losing a life, 'unchanged' across a frame where it shouldn't move. Repeat until 1-2 remain, then confirm with op:'write'.`,
+      });
+}
+
 async function memSearchNext(sessionKey, { compare, value, name = "default", maxCandidates = 64 }) {
       const host = getHost(sessionKey);
       const s = searchSessions(sessionKey).get(name);
@@ -542,13 +638,17 @@ export function registerMemoryTools(server, z, sessionKey) {
     "• op:'diff' — compare a region against a snapshot baseline → the CHANGED bytes. DEFAULT `view:'summary'` is a CLUSTERED summary (+ stride detection — '4 islands at stride 0x80' = a struct array) so a churny gameplay diff doesn't flood context; `view:'raw'` = the per-byte before/after list.\n" +
     "• op:'classify' — heuristically classify the bytes at an offset BEFORE you trust a 'found table'. **Kills the classic trap: a run that 'matches' your stats is often ASCII TEXT (bytes 82/79/68 = 'ROD' from a taunt string) or code.** Returns looksLike/printableRatio/entropy/asciiPreview/confidence.\n" +
     "• op:'search' — seed the iterative RAM value search (Cheat Engine / RetroArch style): all addresses currently holding `value` (`size` 1/2/4 bytes, region's endianness). The primitive for 'the screen shows X, find its RAM address' — better than snapshot+diff for this. STORED ≠ DISPLAYED is common — `as:'bcd'` (packed BCD scores) and `as:'digits'` (one byte per on-screen digit at ANY constant tile base, auto-detected per candidate) search those representations directly; for displayed−1 lives or ÷10 scores just seed the transformed number.\n" +
+    "• op:'searchUnknown' — the UNKNOWN-INITIAL-VALUE hunt (Cheat Engine's 'Unknown initial value'): seed the WHOLE region as candidates with NO value, then narrow across in-game events with op:'searchNext' compare 'dec'/'inc'/'unchanged'/'changed'/'gt'/'lt'. THE way to find a value you can't see (lives/timer/ammo not on the HUD): searchUnknown → lose a life → searchNext compare:'dec' → repeat. Use this when you don't know the number; use op:'search' when you do.\n" +
     "• op:'searchNext' — narrow the active candidate list against CURRENT memory. `compare`: 'eq'/'gt'/'lt' (need `value`), 'changed'/'unchanged'/'inc'/'dec' (vs the previous read — usable as the FIRST narrow too; baselines are recorded at seed). Comparisons happen in the seed's `as` representation. Repeat until 1-2 remain, then confirm with op:'write'. (For values an INPUT drives — position, velocity — op:'diffRuns' is usually one call instead of a narrowing loop.)",
     {
-      op: z.enum(["read", "write", "readCart", "snapshot", "diff", "diffRuns", "classify", "search", "searchNext"])
-        .describe("read=bytes→hex; write=hex/base64→region; readCart=loaded cart ROM image; snapshot=capture a baseline; diff=changed bytes vs a baseline; diffRuns=run the SAME start state twice under two different held inputs and return only the DIVERGENT bytes (THE input→RAM mapping primitive — replaces save/run/dump/restore/run/dump/python-diff); classify=what kind of data is here; search=seed a value search; searchNext=narrow it."),
+      op: z.enum(["read", "write", "readCart", "snapshot", "diff", "diffRuns", "classify", "search", "searchUnknown", "searchNext"])
+        .describe("read=bytes→hex; write=hex/base64→region; readCart=loaded cart ROM image; snapshot=capture a baseline; diff=changed bytes vs a baseline; diffRuns=run the SAME start state twice under two different held inputs and return only the DIVERGENT bytes (THE input→RAM mapping primitive — replaces save/run/dump/restore/run/dump/python-diff); classify=what kind of data is here; search=seed a value search (you know the number); searchUnknown=seed the whole region (you DON'T know the number); searchNext=narrow either."),
       region: z.enum(REGIONS).optional().describe("Memory region. Required for read/write/snapshot/diff; defaults to system_ram for classify/search. (readCart targets the cart ROM image, not a region.)"),
       offset: z.number().int().min(0).default(0).describe("Byte offset within the region (read/write/snapshot/classify) or the cart ROM image (readCart)."),
       length: z.number().int().min(1).max(1 << 20).optional().describe("Bytes to read (max 1MB). op:read default 1; op:readCart default 16; op:snapshot default = whole region from offset; op:classify default 256."),
+      cpuAddress: z.number().int().min(0).optional().describe("op:readCart (NES/SNES) — read by a BANKED CPU ADDRESS instead of a flat offset (the inverse of the breakpoint result's bank/prgOffset). e.g. read a jump table at $8654 in bank 6: {op:'readCart', cpuAddress:0x8654, bank:6}. A $C000+ NES address resolves to the fixed top bank. Saves the cpuAddr-0x8000+bank*0x4000 hand-arithmetic."),
+      bank: z.number().int().min(0).optional().describe("op:readCart with cpuAddress — which 16KB PRG bank is mapped into the switchable $8000-$BFFF window (NES). Ignored for $C000+ (fixed top bank) and for non-banked ROMs."),
+      mapper: z.enum(["lorom", "hirom"]).optional().describe("op:readCart with cpuAddress (SNES) — force LoROM/HiROM mapping if auto-detect is wrong."),
       offsets: offsetsShape.optional().describe("op:read BATCH — a list of addresses (each read `length` bytes, default 1) or {offset,length} objects → reads:[{offset,length,hex}]. Takes precedence over offset/length."),
       // write
       hex: z.string().optional().describe("op:write — hex string, e.g. 'deadbeef' (even length)."),
@@ -563,6 +663,12 @@ export function registerMemoryTools(server, z, sessionKey) {
       maxClusters: z.number().int().min(1).max(4096).default(64).describe("op:diff summary view — cap the cluster list (clusterCount is the true total)."),
       gap: z.number().int().min(1).max(256).default(4).describe("op:diff summary view — merge changed bytes within this many bytes into one cluster (default 4)."),
       minDelta: z.number().int().min(1).max(255).optional().describe("op:diff — ignore changes where |after-before| < minDelta (filters RNG/counter wiggle so a position byte that moved by the entity's speed stands out)."),
+      changeDir: z.enum(["inc", "dec"]).optional().describe("op:diff — keep only bytes that went UP ('inc', after>before) or DOWN ('dec', after<before). The lives/score/ammo hunt: a death window's 'dec' bytes are the candidates."),
+      deltaEq: z.number().int().min(-255).max(255).optional().describe("op:diff — keep only bytes whose signed change (after-before) is EXACTLY this. e.g. deltaEq:-1 = 'decreased by one' (lost a life); deltaEq:10 = '+10 score tick'."),
+      beforeMin: z.number().int().min(0).max(255).optional().describe("op:diff — keep only bytes whose BEFORE value was >= this."),
+      beforeMax: z.number().int().min(0).max(255).optional().describe("op:diff — keep only bytes whose BEFORE value was <= this (e.g. beforeMax:9 = a small counter like lives, not a coordinate)."),
+      afterMin: z.number().int().min(0).max(255).optional().describe("op:diff — keep only bytes whose AFTER value was >= this."),
+      afterMax: z.number().int().min(0).max(255).optional().describe("op:diff — keep only bytes whose AFTER value was <= this."),
       frames: z.number().int().min(1).max(100000).default(60).describe("op:diffRuns — frames to run EACH scenario from the same start state."),
       portsA: z.array(z.record(z.string(), z.boolean())).max(2).optional().describe("op:diffRuns — held input for run A (e.g. [{right:true}]). Default released."),
       portsB: z.array(z.record(z.string(), z.boolean())).max(2).optional().describe("op:diffRuns — held input for run B. Default released — A-vs-idle is the classic 'which byte does this input drive?' probe."),
@@ -573,9 +679,9 @@ export function registerMemoryTools(server, z, sessionKey) {
       compare: z.enum(["eq", "changed", "unchanged", "inc", "dec", "gt", "lt"]).optional().describe("op:searchNext — eq=now equals `value`; changed/unchanged vs the last read; inc/dec=went up/down. All of these work as the FIRST narrow too (baselines are recorded at seed). gt/lt=now >/< `value`."),
       maxCandidates: z.number().int().min(1).max(8192).default(64).describe("op:search/searchNext — cap the candidates RETURNED (the full list is kept server-side; `count` is the true total)."),
       // shared output
-      outputPath: z.string().optional().describe(`op:read/readCart — write RAW bytes here. Required for reads >${INLINE_HEX_LIMIT}B unless inline. Small reads honor it too (writes file AND returns hex), so 'dump to disk then diff two files' works at any size. (Ignored with offsets.)`),
+      outputPath: z.string().optional().describe(`op:read/readCart — write RAW bytes here. Required for reads >${INLINE_HEX_LIMIT}B unless inline. Small reads honor it too (writes file AND returns hex), so 'dump to disk then diff two files' works at any size. (Ignored with offsets.) op:diff — write the FULL diff JSON here regardless of size (so a big diff routes to YOUR path, not a harness path).`),
       inline: z.boolean().default(false).describe(`op:read/readCart — for reads >${INLINE_HEX_LIMIT}B, return the hex in the response instead of writing to disk.`),
-      echo: z.boolean().default(true).describe("op:read/readCart with outputPath — false = return only {path, bytes} with NO inline hex (keeps a 2-4KB dump out of context; the raw bytes are in the file)."),
+      echo: z.boolean().default(true).describe("op:read/readCart with outputPath — false = return only {path, bytes} with NO inline hex (keeps a 2-4KB dump out of context; the raw bytes are in the file). op:diff with outputPath — false = return only the slim envelope (counts + path), omitting the changes/clusters array."),
     },
     safeTool(async (args) => {
       switch (args.op) {
@@ -599,9 +705,10 @@ export function registerMemoryTools(server, z, sessionKey) {
         }
         case "classify":   return await memClassify(sessionKey, args);
         case "search": {
-          if (args.value == null) throw new Error("memory({op:'search'}): `value` is required.");
+          if (args.value == null) throw new Error("memory({op:'search'}): `value` is required (use op:'searchUnknown' for an unknown-value hunt).");
           return await memSearch(sessionKey, args);
         }
+        case "searchUnknown": return await memSearchUnknown(sessionKey, args);
         case "searchNext": {
           if (!args.compare) throw new Error("memory({op:'searchNext'}): `compare` is required.");
           return await memSearchNext(sessionKey, args);
@@ -629,7 +736,7 @@ function searchSessions(key) { let m = _searchSessions.get(key); if (!m) { m = n
 /** @type {Map<string, Map<string, {offset:number, bytes:Uint8Array}>>} */
 const _memSnaps = new Map();
 function memSnapshots(key) { let m = _memSnaps.get(key); if (!m) { m = new Map(); _memSnaps.set(key, m); } return m; }
-const snapKey = (region, name) => region + "" + name;
+const snapKey = (region, name) => region + "" + name;
 
 /** Bytes from `offset` to the end of the region — for a whole-region snapshot
  *  when no explicit length is given. Uses the core-reported region size. */

package/src/mcp/tools/record.js

@@ -12,13 +12,12 @@ import { mkdir, writeFile } from "node:fs/promises";
 import path from "node:path";
 import { getHost } from "../state.js";
 import { jsonContent, safeTool } from "../util.js";
-import { MemoryRegionToRetro } from "../../host/types.js";
-
-// Single source of truth for memorySamples regions — the same canonical set
-// readMemory accepts. Previously hardcoded to 8 NES regions, so Genesis and
-// hardware-register regions (nes_apu_regs, etc.) couldn't be batch-sampled.
-const SAMPLE_REGIONS = /** @type {[string, ...string[]]} */ (Object.keys(MemoryRegionToRetro));
 
+// memorySamples regions accept the same canonical set readMemory accepts (incl.
+// hardware-register regions like nes_apu_regs). The region is a runtime-validated
+// string rather than an inlined ~62-value schema enum — the per-sample
+// host.readMemory(region,…) lookup throws on an unknown region with a clear
+// message, so the schema enum was pure deferred-load weight (0.28.0 feedback #5).
 export function registerRecordTools(server, z, sessionKey) {
   const inputShape = z.object({
     up: z.boolean().optional(), down: z.boolean().optional(),
@@ -54,7 +53,7 @@ export function registerRecordTools(server, z, sessionKey) {
         .array(
           z.object({
             label: z.string(),
-            region: z.enum(SAMPLE_REGIONS),
+            region: z.string().describe("memory region (full readMemory set incl. hardware registers; validated at runtime)"),
             offset: z.number().int().min(0),
             length: z.number().int().min(1).max(256),
           }),

package/src/mcp/tools/run-until.js

@@ -13,9 +13,15 @@ import { jsonContent, safeTool } from "../util.js";
 import { attachObserverFrame } from "./watch-memory.js";
 
 export function registerRunUntilTools(server, z, sessionKey) {
+  // Condition `region` is a runtime-validated string, not a schema enum. It was
+  // an inlined 8-value list — which both bloated the schema AND silently rejected
+  // valid non-NES regions (genesis_*, c64_*, *_apu_regs) that host.readMemory
+  // accepts. The readMemory(region,…) call in the handler validates and throws a
+  // clear message on an unknown region (full canonical set, same as `memory`).
+  const regionStr = z.string().describe("memory region (full readMemory set, e.g. system_ram, nes_oam, genesis_vram, c64_color_ram; validated at runtime)");
   const memoryCondition = z.object({
     type: z.literal("memory"),
-    region: z.enum(["system_ram", "save_ram", "video_ram", "rtc", "nes_nametables", "nes_palette", "nes_oam", "nes_chr"]),
+    region: regionStr,
     offset: z.number().int().min(0),
     equals: z.number().int().min(0).max(255).optional(),
     notEquals: z.number().int().min(0).max(255).optional(),
@@ -24,7 +30,7 @@ export function registerRunUntilTools(server, z, sessionKey) {
 
   const memoryChangedCondition = z.object({
     type: z.literal("memoryChanged"),
-    region: z.enum(["system_ram", "save_ram", "video_ram", "rtc", "nes_nametables", "nes_palette", "nes_oam", "nes_chr"]),
+    region: regionStr,
     offset: z.number().int().min(0),
     length: z.number().int().min(1).max(8192).default(1),
   }).describe("Stop when memory[region][offset..offset+length] changes from its initial value.");

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

@@ -139,6 +139,19 @@ export function makePressDriver(host, presses) {
 // never disagree again.
 const MEMORY_REGIONS = /** @type {[string, ...string[]]} */ (Object.keys(MemoryRegionToRetro));
 
+// A region param that does NOT inline the full ~62-value enum into the JSON
+// schema. The enum array is ~214 tokens PER param site; inlining it on every
+// secondary region sub-param across this file was the dominant tool-schema
+// bloat (0.28.0 feedback #5). Used on SECONDARY/sub params; the PRIMARY region
+// inputs keep z.enum so the full list stays discoverable where the region IS
+// the choice. A plain string — validated at RUNTIME by the handler (the
+// host.readMemory / MemoryRegionToRetro lookup throws on an unknown region with
+// a clear message), so dropping the schema enum here costs no safety.
+// NOTE: `z` is passed into registerWatchMemoryTools (not a module import), so
+// this factory takes `z` and is invoked once inside the register fn.
+const makeRegionStr = (z) => (desc) =>
+  z.string().describe(desc + " (validated at runtime against the canonical region set).");
+
 // Abort-guard for input-driven watchpoint runs: sample caller-named bytes each
 // frame; the FIRST one to change stops the run with {label,addr,before,after}.
 // Lets a derailed driven scenario (player died, scene flipped) return immediately
@@ -266,8 +279,9 @@ function downsample(arr, n) {
 }
 
 export function registerWatchMemoryTools(server, z, sessionKey) {
+  const regionStr = makeRegionStr(z);
   const rangeShape = z.object({
-    region: z.enum(MEMORY_REGIONS),
+    region: regionStr("memory region for THIS range (same canonical set `memory` uses)"),
     offset: z.number().int().min(0),
     length: z.number().int().min(1).max(4096).default(1),
     label: z.string().optional().describe("Name echoed on every event from this range — tells disjoint ranges apart in one stream."),
@@ -510,7 +524,7 @@ export function registerWatchMemoryTools(server, z, sessionKey) {
 
   // breakpoint({on:write|read|pc}) STOP-on-first. on:write precision:exact=bpFindWriter
   // (core watchpoint, true PC under IRQ), precision:sampled=bpRunUntilWrite (frame PC).
-  async function bpFindWriter({ address, maxFrames = 600, pressDuring, abortIf }) {
+  async function bpFindWriter({ address, maxFrames = 600, pressDuring, abortIf, condition, conditionValue }) {
       const host = getHost(sessionKey);
       if (!host.watchpointSupported || !host.watchpointSupported()) {
         return jsonContent({
@@ -519,7 +533,18 @@ export function registerWatchMemoryTools(server, z, sessionKey) {
             "Use watchMemory/runUntilWrite here — their pc is frame-sampled, so cross-check the value trace.",
         });
       }
-      host.setWatchpoint(address, true);
+      if (condition === "equals" && conditionValue == null) {
+        throw new Error("breakpoint({on:'write', condition:'equals'}): `conditionValue` (the byte to stop on) is required.");
+      }
+      // Pass the condition to the core's watchpoint so its hook only COUNTS +
+      // records writes that satisfy it (qualifying writes), ignoring restoring/
+      // churn writes — and so the reported PC is a meaningful write, not just the
+      // last write of the frame. Core support is feature-detected; if the loaded
+      // core build predates condition support, we fall back to a host-side
+      // 'equals' filter on the reported value (inc/dec need the core's old byte).
+      const wantCond = condition != null;
+      const coreCond = host.setWatchpoint(address, true, wantCond ? { condition, value: conditionValue } : undefined);
+      const coreHandledCond = wantCond && coreCond && coreCond.conditionApplied === true;
       const presses = (pressDuring ?? []).slice().sort((a, b) => a.frame - b.frame);
       const pressDriver = makePressDriver(host, presses);
       // Abort-guard: sample caller-named "still valid?" bytes each frame; if any
@@ -533,7 +558,17 @@ export function registerWatchMemoryTools(server, z, sessionKey) {
         pressDriver.applyForFrame(i);
         host.stepFrames(1);
         const w = host.getWatchpoint();
-        if (w.hits > 0) { result = { ...w, framesStepped: i + 1 }; break; }
+        if (w.hits > 0) {
+          // Host-side fallback for condition:'equals' on a core that didn't
+          // apply the condition itself: only accept when the reported (last)
+          // written value equals the target; otherwise keep waiting. (inc/dec
+          // can't be faked host-side — they need the core's pre-write byte, so
+          // we only reach here for them when the core DID handle the condition.)
+          if (wantCond && !coreHandledCond && condition === "equals" && (w.lastValue & 0xFF) !== (conditionValue & 0xFF)) {
+            continue;
+          }
+          result = { ...w, framesStepped: i + 1 }; break;
+        }
         const ab = guard.check();
         if (ab) { aborted = { ...ab, framesStepped: i + 1 }; break; }
       }
@@ -584,12 +619,17 @@ export function registerWatchMemoryTools(server, z, sessionKey) {
         // address — a word/long store shows only its byte here, not the operand
         // (a real session read 0x00 as "the move.l wrote zero").
         valueByte: "0x" + result.lastValue.toString(16).toUpperCase().padStart(2, "0"),
+        ...(result.lastOldValue != null ? { oldValueByte: "0x" + (result.lastOldValue & 0xFF).toString(16).toUpperCase().padStart(2, "0") } : {}),
+        ...(condition ? { condition, ...(coreHandledCond ? {} : { conditionAppliedBy: "host" }) } : {}),
         hits: result.hits,
         framesStepped: result.framesStepped,
         ...(wpRegs ? { registersAtHit: wpRegs } : {}),
         ...(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. " +
+          (condition
+            ? `condition:'${condition}' filtered to the MEANINGFUL write — pc/valueByte/hits reflect only qualifying writes${result.lastOldValue != null ? ` (oldValueByte→valueByte = ${"0x" + (result.lastOldValue & 0xFF).toString(16)}→${"0x" + result.lastValue.toString(16)})` : ""}. `
+            : "Without a `condition`, on:'write' runs to END OF FRAME and reports the LAST matching write of the frame (NOT the first) — `hits` is the count of all matching writes that frame. If a restoring/churn write hides the change you want, pass condition:'increase'|'decrease'|'equals'. ") +
           "valueByte is the single byte written to the watched address (a 16/32-bit store shows only its byte here). " +
           "hits counts watched-byte writes during the hit frame — the same instruction looping twice in one frame is hits:2, one event. " +
           (wpRegs ? "registersAtHit is the register file frozen AT the write (the live regs drift for the rest of the frame — don't cpu({op:'read'}) instead). " : "") +
@@ -830,9 +870,11 @@ export function registerWatchMemoryTools(server, z, sessionKey) {
       precision: z.enum(["exact", "sampled"]).default("exact")
         .describe("on:'write' ONLY. exact=core watchpoint, the real writing instruction PC even under interrupts (uses `address`). sampled=cheap frame-boundary PC (uses region/offset/length) — NOT the writer under IRQ. Ignored for on:read/pc (always exact)."),
       address: z.number().int().min(0).optional().describe("on:'write' exact / on:'read' / on:'pc' — CPU address to break on (write target, read target, or instruction boundary). Required for those."),
-      region: z.enum(MEMORY_REGIONS).optional().describe("on:'write' precision:'sampled' — region whose byte to watch for change."),
+      region: regionStr("on:'write' precision:'sampled' — region whose byte to watch for change.").optional(),
       offset: z.number().int().min(0).optional().describe("on:'write' precision:'sampled' — offset within the region."),
       length: z.number().int().min(1).max(4096).default(1).describe("on:'write' precision:'sampled' — bytes to watch from offset."),
+      condition: z.enum(["increase", "decrease", "equals"]).optional().describe("on:'write' precision:'exact' ONLY — stop only on the MEANINGFUL write, ignoring restoring/churn writes. 'decrease'/'increase' = the stored byte actually went down/up (e.g. a real lives−1, not a per-frame pointer-arithmetic restore); 'equals' = the byte became `value` (e.g. $00→$01 respawn re-arm). Without it, on:'write' reports the LAST matching write of the frame, which may be the churn, not the change you want."),
+      conditionValue: z.number().int().min(0).max(255).optional().describe("on:'write' condition:'equals' — the byte value to stop on (the NEW value written)."),
       maxFrames: z.number().int().min(1).max(1_000_000).default(600).describe("Max frames to run while waiting for the condition."),
       pressDuring: z.array(z.object({
         frame: z.number().int().min(0),
@@ -841,12 +883,12 @@ export function registerWatchMemoryTools(server, z, sessionKey) {
         holdFrames: z.number().int().min(1).default(2),
       })).optional().describe("Schedule input while waiting (drive the game to the state that triggers the condition). If OMITTED, this run inherits whatever input({op:'set'}) last held — same as frame({op:'step'}). If GIVEN, the schedule OWNS the pad for the whole run (a prior input({op:'set'}) is ignored); use it to drive the watched window itself. Entries with OVERLAPPING windows on the same port are OR'd into a chord (e.g. b+right held while a fires mid-window), not overwritten."),
       abortIf: z.array(z.object({
-        region: z.enum(MEMORY_REGIONS).optional().describe("memory region (default system_ram)"),
+        region: regionStr("memory region (default system_ram)").optional(),
         offset: z.number().int().min(0).describe("byte offset within the region"),
         label: z.string().optional().describe("human name for this guard byte"),
       })).optional().describe("on:'write' exact — ABORT GUARD for a pressDuring run: caller-named 'is this scenario still valid?' bytes (e.g. the area/scene id, the player object-active flag). If ANY changes mid-run the watchpoint stops IMMEDIATELY and returns {aborted:true, abortedBy, before, after} — so a driven scenario that derailed (player died → title screen) doesn't burn all maxFrames and return a meaningless found:false. Each is sampled once per frame (cheap)."),
       captureMemory: z.array(z.object({
-        region: z.enum(MEMORY_REGIONS).describe("memory region to read"),
+        region: regionStr("memory region to read"),
         offset: z.number().int().min(0).describe("byte offset within the region"),
         length: z.number().int().min(1).max(256).default(1).describe("bytes to read"),
         label: z.string().optional().describe("human name for this read (else 'region+offset')"),

package/src/platforms/_guides/ROMHACKING_PLAYBOOK.md

@@ -65,6 +65,14 @@ thousands of bytes and you'll drown).
 
 This is the Cheat-Engine/RetroArch loop. It is THE bread-and-butter primitive.
 
+**Don't know the value? (lives/timer/ammo not on the HUD)** Use the
+unknown-initial-value hunt: `memory({op:'searchUnknown', region, size})` seeds
+the WHOLE region with no value, then narrow across events with
+`searchNext({compare:'dec'|'inc'|'unchanged'|'changed'|'gt'|'lt'})` — e.g.
+`searchUnknown` → lose a life → `searchNext({compare:'dec'})` → repeat until 1–2
+remain. `op:'search'` needs a value; `op:'searchUnknown'` is for when you can't
+see the number.
+
 **Stored ≠ displayed.** When a correct-looking seed returns 0, the byte usually isn't the
 raw number: seed `as:'bcd'` for packed-BCD scores (2 decimal digits per byte — very common
 on NES), or `as:'digits'` for one byte per ON-SCREEN digit at any constant tile base (HUD
@@ -78,7 +86,13 @@ not for value hunting. `memory({op:'diff'})` defaults to a **clustered summary**
 stride) so it won't flood you — a reported stride (e.g. "islands at 0x80") is
 usually a struct/entity array, each island one record. Small clusters (≤8 bytes) carry
 `before`/`after` hex inline, and `minDelta:N` drops |after−before| < N so RNG/counter
-wiggle disappears from the report.
+wiggle disappears from the report. For the locate-value-via-diff case, predicate
+filters cut a 500-byte death-window diff to the ~3 rows you want in one call:
+`changeDir:'dec'|'inc'` (direction), `deltaEq:N` (signed exact delta — `deltaEq:-1`
+= "lost one life"), and `beforeMin/Max` + `afterMin/Max` (value-range gates, e.g.
+`beforeMax:9` = a small counter, not a coordinate). `outputPath` writes the full
+diff JSON to your path regardless of size (`echo:false` returns just the
+counts+path so a big diff never streams through context).
 
 **"Which byte does this INPUT drive?" → `memory({op:'diffRuns'})`** — runs the same start
 state twice (savestate restore in between) under two different held inputs (`portsA` vs
@@ -136,8 +150,11 @@ a string — find a terminator / font map before treating the bytes as values.
 platforms (Genesis/Mega Drive, GB/GBC, SMS/GG, PCE, Lynx) the **file offset IS
 the CPU ROM address** — `memory({op:'readCart', offset:0x21FF00})` answers "does the
 running ROM have my bytes at 0x21FF00?" in one call. (NES/SNES: bytes are
-correct but mapper-banked — `mapped:true` in the response; map a CPU PC→offset
-via `breakpoint({on:'write'})`'s prgOffset/bank.)
+correct but mapper-banked — `mapped:true` in the response.) For a BANKED CPU
+address, read it directly: `memory({op:'readCart', cpuAddress:0x8654, bank:6})`
+maps the bank→PRG offset for you (NES/SNES) — the inverse of the breakpoint
+result's bank/prgOffset, so you stop hand-computing `cpuAddr−0x8000+bank*0x4000`.
+A NES `$C000+` address resolves to the fixed top bank automatically.
 
 When a write "doesn't show up", check the ROM here before assuming the patch
 failed — it's usually live and the bug is elsewhere (wrong source, see §2/§5).
@@ -170,6 +187,18 @@ can pass `{startAddress, bank}` to `disasm({target:'rom'})`. The lighter
 and returns a frame-boundary PC — a lead, not a guarantee under interrupts; use it for the
 value timeline or when you just want the change history, and cross-check the value trace.
 
+**Stop on the MEANINGFUL write, not the churn.** `breakpoint({on:'write'})` runs
+to END OF FRAME and reports the LAST matching write that frame (with `hits` =
+the count of all matching writes) — so a frequent **restoring** write (a pointer-
+arithmetic `inc`/`dec` that touches the byte every frame, a re-arm) can mask the
+write you actually want. Filter to the real change with `condition` (all 14
+platforms): `condition:'decrease'` / `'increase'` stop only when the stored byte
+actually went down/up (a real lives−1, not a restore), and `condition:'equals',
+conditionValue:N` stops on the byte becoming N (e.g. a $00→$01 respawn re-arm).
+The hit then reports `oldValueByte`→`valueByte` so you see the exact transition.
+This is the difference between pinning a genuine decrement instantly and chasing
+net-zero restoring churn.
+
 ---
 
 ## 5b. To READ a register at an instruction — execution breakpoints (all 14)