romdevtools 0.26.0 → 0.27.0

package/CHANGELOG.md

@@ -4,6 +4,17 @@ All notable changes to `romdevtools`. Dates are release dates.
 (Published as `romdev-mcp` through 0.11.0; renamed to `romdevtools` in 0.13.0 —
 the `romdev-mcp` bin is kept as an alias.)
 
+## 0.27.0
+
+### Added — `breakpoint(on:'pc', captureMemory:[…])` reads named RAM at the hit
+Completes item 2 of the NES Rygar report. 0.26.0 shipped `registersAtHit` (the
+break-instant register file) but not the memory half. Now `breakpoint(on:'pc')`
+takes `captureMemory:[{region,offset,length,label}]` and returns those reads inline
+as `capturedMemory`, so register + RAM inspection at a PC collapses into ONE call —
+no follow-up `cpu`/`memory` round trips. `registersAtHit` is the true break instant
+(core snapshot); `capturedMemory` reflects the routine's RAM side effects for the
+hit frame (stable + what RE needs), documented as such.
+
 ## 0.26.0
 
 ### Fixed — NES `breakpoint(on:'pc')` now returns reliable break-instant registers
@@ -17,9 +28,8 @@ them (the schema's "CPU is FROZEN at this instruction" was wrong for NES).
   SNAPSHOTS A/X/Y/P/S at the hit instant, exposed via `romdev_pcbreak_get`.
 - **`breakpoint(on:'pc')` returns `registersAtHit`** — the reliable break-instant
   register file. The schema + hit note now steer to it and explicitly warn that a
-  live `cpu({op:'read'})` after a hit is end-of-frame state on fceumm. (Item 1+2
-  of the report, collapsed: the snapshot is taken in the same call that detects the
-  hit, so there's no freeze-durability race and no extra round trip.)
+  live `cpu({op:'read'})` after a hit is end-of-frame state on fceumm. (The
+  `captureMemory` companion that reads named RAM inline at the hit landed in 0.27.0.)
 - **NES `cpu({op:'read'})` core-internal fields relabeled** (item 3): `DB`,
   `IRQlow`, `tcount`, `count` are fceumm internals (data-bus latch / IRQ bitmask /
   cycle counters), not 6502 registers — moved out of `registers` into a labeled

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "romdevtools",
-  "version": "0.26.0",
+  "version": "0.27.0",
   "description": "Tool server giving coding agents full control of homebrew ROM development AND reverse-engineering/romhacking across 14 retro platforms (NES, SNES, GB, Genesis, Atari, C64, PC Engine, MSX, ...) via WASM toolchains + emulator cores. Use over plain HTTP, as an Agent Skill, or as an MCP server.",
   "type": "module",
   "main": "src/mcp/server.js",

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

@@ -633,7 +633,7 @@ export function registerWatchMemoryTools(server, z, sessionKey) {
       });
   }
 
-  async function bpRunUntilPC({ address, maxFrames = 600, pressDuring }) {
+  async function bpRunUntilPC({ address, maxFrames = 600, pressDuring, captureMemory }) {
       const host = getHost(sessionKey);
       if (!host.pcBreakSupported || !host.pcBreakSupported()) {
         return jsonContent({
@@ -669,6 +669,29 @@ export function registerWatchMemoryTools(server, z, sessionKey) {
       // Snapshot the registers AT the hit BEFORE clearing (last already holds the
       // hit state; read it without clearing so registersAtHit survives).
       const atHit = last.registersAtHit ?? host.getPCBreak(false).registersAtHit ?? null;
+      // captureMemory: read the requested regions AT the hit (before we clear/step),
+      // returned inline so break→read RAM collapses into ONE call. NOTE: registers
+      // are the true break instant (core snapshot); these RAM reads are taken now —
+      // i.e. after the hit frame finished — so on run-to-frame-end cores (fceumm)
+      // they reflect the routine's RAM SIDE EFFECTS for that frame (which is what
+      // RE wants: "what did this routine touch"), not necessarily the exact byte
+      // mid-instruction. Stable + reliable; that's the property the report leaned on.
+      let capturedMemory = null;
+      if (Array.isArray(captureMemory) && captureMemory.length) {
+        capturedMemory = {};
+        for (const m of captureMemory) {
+          const label = m.label ?? `${m.region}+${m.offset}`;
+          try {
+            const bytes = host.readMemory(m.region, m.offset, m.length ?? 1);
+            capturedMemory[label] = {
+              region: m.region, offset: m.offset, length: m.length ?? 1,
+              hex: Array.from(bytes, (b) => b.toString(16).padStart(2, "0")).join(""),
+            };
+          } catch (e) {
+            capturedMemory[label] = { region: m.region, offset: m.offset, error: String(e?.message ?? e) };
+          }
+        }
+      }
       const fin = host.getPCBreak(true); // clear hit
       // registersAtHit (NES/fceumm and any core that snapshots regs on hit) is the
       // RELIABLE break-instant register file. The LIVE register file (a follow-up
@@ -677,7 +700,7 @@ export function registerWatchMemoryTools(server, z, sessionKey) {
       // end-of-frame state. Prefer registersAtHit; only fall back to a live read on
       // cores that don't snapshot.
       const frozenNote = atHit
-        ? "registersAtHit holds the register file CAPTURED AT this instruction (A/X/Y/P/S) — use THESE, not a follow-up cpu({op:'read'}), which on NES/fceumm returns end-of-frame state, not the break instant. For a source pointer in a 16-bit reg pair, read the two ZP bytes via memory({op:'read'}). frame({op:'stepInstruction'}) to single-step from here."
+        ? "registersAtHit holds the register file CAPTURED AT this instruction (A/X/Y/P/S) — use THESE, not a follow-up cpu({op:'read'}), which on NES/fceumm returns end-of-frame state, not the break instant. For RAM at the hit, pass captureMemory:[{region,offset,length}] to get it inline (capturedMemory) in THIS call instead of a follow-up read. frame({op:'stepInstruction'}) to single-step from here."
         : "This core does not snapshot registers at the hit. cpu({op:'read'}) reflects the CPU state now; on cores that run-to-frame-end (fceumm) that is NOT the break instant — prefer the RAM side effects (memory({op:'read'})) over the live register file.";
       return attachObserverFrame(jsonContent({
         hit: true,
@@ -685,6 +708,7 @@ export function registerWatchMemoryTools(server, z, sessionKey) {
         pc: last.lastPC != null ? "$" + last.lastPC.toString(16).toUpperCase() : null,
         pcRaw: last.lastPC,
         ...(atHit ? { registersAtHit: atHit } : {}),
+        ...(capturedMemory ? { capturedMemory } : {}),
         frame: host.status.frameCount,
         framesRun,
         hits: fin.hits,
@@ -780,6 +804,12 @@ export function registerWatchMemoryTools(server, z, sessionKey) {
         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"),
+        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')"),
+      })).optional().describe("on:'pc' — read these memory regions AT the hit and return them inline as `capturedMemory` (collapses break→read-RAM into ONE call, the token win). Pair with `registersAtHit` to get the routine's register + RAM state in a single round trip (e.g. capture the ZP pointer bytes a decoder just wrote). NOTE: registersAtHit is the true break instant (core snapshot); these RAM reads are taken after the hit frame finishes, so on run-to-frame-end cores (fceumm) they're the routine's RAM side effects for that frame — stable + reliable, which is exactly what RE needs."),
     },
     safeTool(async (args) => {
       switch (args.on) {