romdevtools 0.28.0 → 0.30.0

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/rom-id.js

@@ -305,13 +305,17 @@ export async function extractSpriteSheetCore({ platform, path: romPath, offset,
         const path = await import("node:path");
         await mkdir(path.dirname(outputPath), { recursive: true });
         await writeFile(outputPath, png);
-        return jsonContent({
+        // Livestream sideband: show the rendered sheet even though the agent
+        // only gets the path.
+        const out = jsonContent({
           path: outputPath,
           intent: d.intent,
           bytes: png.length,
           paletteSource,
           note,
         });
+        out._observerImages = [{ kind: "image", mimeType: "image/png", base64: png.toString("base64") }];
+        return out;
       }
       return {
         content: [

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

@@ -10,11 +10,18 @@
 
 import { getHost } from "../state.js";
 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(),
@@ -23,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.");
@@ -75,11 +82,12 @@ export function registerRunUntilTools(server, z, sessionKey) {
         }
       }
 
-      return jsonContent({
+      // Livestream: the frame where the condition was met (or where we gave up).
+      return attachObserverFrame(jsonContent({
         conditionMet: met,
         framesStepped,
         finalValue,
-      });
+      }), host, met ? "runUntil: condition met" : "runUntil: gave up");
     }),
   );
 }

package/src/mcp/tools/snippets.js

@@ -97,11 +97,11 @@ export function registerSnippetTools(_server, _z) {
       platform, languages, snippets: filtered,
       note: filtered.length === 0
         ? `No snippets matched for '${platform}'${language ? ` (language=${language})` : ""}.`
-        : `Fetch one with starterSnippets({ platform, mode:'get', name${language ? ", language" : ""} }), or all with mode:'getAll'.`,
+        : `Fetch one with examples({ op:'snippets', platform, mode:'get', snippetName${language ? ", language" : ""} }), or all with mode:'getAll'.`,
     });
   }
   async function snippetsGet(platform, name, language) {
-    if (!name) throw new Error("starterSnippets mode:'get' requires `name`.");
+    if (!name) throw new Error("examples({op:'snippets'}) mode:'get' requires `snippetName`.");
     if (name.includes("..") || (name.includes("/") && !/^[a-z]+\/[\w.-]+$/i.test(name))) {
       throw new Error("snippet name must not contain '..' or arbitrary path separators");
     }
@@ -124,7 +124,7 @@ export function registerSnippetTools(_server, _z) {
       return textContent(`No snippets available for '${platform}'${language ? ` (language=${language})` : ""}.`);
     }
     if (!inline && !outputPath) {
-      throw new Error("starterSnippets mode:'getAll': pass outputPath (write the joined snippets to disk, returns {path}) or inline:true (return `combined` in the response). Or use copyStarterSnippets to write each snippet as its own file.");
+      throw new Error("examples({op:'snippets'}) mode:'getAll': pass outputPath (write the joined snippets to disk, returns {path}) or inline:true (return `combined` in the response). Or use examples({op:'copySnippets'}) to write each snippet as its own file.");
     }
     const parts = [];
     for (const s of filtered) {
@@ -161,7 +161,7 @@ export function registerSnippetTools(_server, _z) {
       if (filtered.length === 0) {
         const langPart = language ? ` (language=${language})` : "";
         const includePart = include ? ` (include=${JSON.stringify(include)})` : "";
-        throw new Error(`copyStarterSnippets: no snippets matched for platform '${platform}'${langPart}${includePart}.`);
+        throw new Error(`examples({op:'copySnippets'}): no snippets matched for platform '${platform}'${langPart}${includePart}.`);
       }
       await mkdir(destinationDir, { recursive: true });
       const written = [];
@@ -201,9 +201,9 @@ export function registerSnippetTools(_server, _z) {
   };
 }
 
-// starterSnippets/copyStarterSnippets folded into the `scaffold` tool. The cores
+// starterSnippets/copyStarterSnippets folded into the `examples` tool. The cores
 // are assigned inside registerSnippetTools (they close over the local helpers);
-// scaffold imports these and calls them. registerSnippetTools registers NO tools
+// examples imports these and calls them. registerSnippetTools registers NO tools
 // now — it just wires the cores.
 export let starterSnippetsCore = async () => { throw new Error("snippet cores not initialized — registerSnippetTools must run first"); };
 export let copyStarterSnippetsCore = async () => { throw new Error("snippet cores not initialized — registerSnippetTools must run first"); };

package/src/mcp/tools/sprite-pipeline.js

@@ -143,6 +143,7 @@ async function cropSpriteSheetImpl({ path, tileX, tileY, tileW, tileH, tileSize
   }
   await writeFile(outputPath, outBuf);
   return {
+    _observerImages: [{ kind: "image", mimeType: "image/png", base64: outBuf.toString("base64") }],
     path: outputPath,
     intent: d.intent,
     width: pxW,
@@ -157,6 +158,16 @@ async function cropSpriteSheetImpl({ path, tileX, tileY, tileW, tileH, tileSize
   };
 }
 
+// Lift a plain core result's livestream sideband OUT of the JSON body and
+// onto the MCP result object (it must never serialize into agent-visible text).
+function liftObserverImages(r) {
+  const sideband = r._observerImages;
+  delete r._observerImages;
+  const out = jsonContent(r);
+  if (sideband) out._observerImages = sideband;
+  return out;
+}
+
 // ── quantizePngForPlatform ──────────────────────────────────────────
 
 /**
@@ -247,6 +258,7 @@ async function quantizePngForPlatformImpl({ path, platform, outputPath, intent,
   const outBuf = writeIndexedPng(png.width, png.height, indices, palette);
   await writeFile(outputPath, outBuf);
   return {
+    _observerImages: [{ kind: "image", mimeType: "image/png", base64: outBuf.toString("base64") }],
     path: outputPath,
     intent: d.intent,
     width: png.width,
@@ -596,12 +608,12 @@ export function registerSpritePipelineTools(server, z, _sessionKey) {
         case "quantize": {
           if (!args.platform) throw new Error("encodeArt({stage:'quantize'}): `platform` is required.");
           if (!args.path || !args.outputPath) throw new Error("encodeArt({stage:'quantize'}): `path` and `outputPath` are required.");
-          return jsonContent(await quantizePngForPlatformImpl(args));
+          return liftObserverImages(await quantizePngForPlatformImpl(args));
         }
         case "crop": {
           if (!args.path || !args.outputPath) throw new Error("encodeArt({stage:'crop'}): `path` and `outputPath` are required.");
           if (args.tileX == null || args.tileY == null || args.tileW == null || args.tileH == null) throw new Error("encodeArt({stage:'crop'}): `tileX`, `tileY`, `tileW`, `tileH` are required.");
-          return jsonContent(await cropSpriteSheetImpl(args));
+          return liftObserverImages(await cropSpriteSheetImpl(args));
         }
         case "tiles": {
           if (!args.platform) throw new Error("encodeArt({stage:'tiles'}): `platform` is required.");

package/src/mcp/tools/state.js

@@ -1,6 +1,7 @@
 import { mkdir, writeFile, readFile } from "node:fs/promises";
 import path from "node:path";
 import { getHost } from "../state.js";
+import { attachObserverFrame } from "./watch-memory.js";
 import { jsonContent, safeTool } from "../util.js";
 
 // Resolve a state-file `path`. An ABSOLUTE path is used as-is. A RELATIVE path
@@ -342,7 +343,7 @@ export function registerStateTools(server, z, sessionKey) {
     safeTool(async (args) => {
       switch (args.op) {
         case "save":   return jsonContent(await saveStateCore(args, sessionKey));
-        case "load":   return jsonContent(await loadStateCore(args, sessionKey));
+        case "load":   return attachObserverFrame(jsonContent(await loadStateCore(args, sessionKey)), getHost(sessionKey), `state load ${args.name ?? args.path ?? ""}`.trim());
         case "list":   return jsonContent(listStatesCore(args, sessionKey));
         case "export": {
           if (!args.fromSlot) throw new Error("state({op:'export'}): `fromSlot` is required.");

package/src/mcp/tools/tile-inspect.js

@@ -284,7 +284,14 @@ export function registerTileInspectTools(server, z, sessionKey) {
           if (r.pngBase64) {
             return { content: [imageContent(r.pngBase64), textContent(JSON.stringify({ ...r, pngBase64: undefined }))] };
           }
-          return jsonContent(r);
+          // Lift the livestream sideband OUT of the core's plain result before
+          // it's serialized — it must ride on the MCP result object, never in
+          // the agent-visible JSON text.
+          const sideband = r._observerImages;
+          delete r._observerImages;
+          const out = jsonContent(r);
+          if (sideband) out._observerImages = sideband;
+          return out;
         }
         default: throw new Error(`tiles: unknown op '${args.op}'`);
       }

package/src/mcp/tools/toolchain.js

@@ -703,7 +703,7 @@ export function registerToolchainTools(server, z, sessionKey) {
     "• output:'rom' (default) — assemble or compile `source` (single) / `sources` ({name:contents}) / `sourcePath` / `sourcesPaths`. Returns the ROM (path by default; `inline:true` for binaryBase64) + build log. **`binaryIncludes`/`binaryIncludePaths` (base64/path CHR-ROM, music blobs for `.incbin`) — WITHOUT them no game with external assets builds.** `includes`/`includePaths` for `.include`d text. `linkerConfig` (cc65; NES preset 'chr-ram-runtime' RECOMMENDED). `crt0`/`crt0Path`/`codeLoc`/`dataLoc` (SDCC). `runtime`/`maxmod`/`rebuildSdk` (GBA/Genesis SDK). **`lint:'strict'` fails the build (stage:'lint', no binary) if the pre-flight SDCC crash-pattern scan flags anything (e.g. the uint8 loop-bound trap); 'advisory' (default) just lists hits in issues[].** **`includeSymbols:true` returns the .map text inline on a PLAIN rom build — distinct from output:'romWithDebug' which writes .dbg/.map FILES.** Language is inferred from extension/content — usually OMIT `language`.\n" +
     "• output:'romWithDebug' — like 'rom' but also emits linker debug info for the `symbols` tool: cc65 → `.dbg`, SDCC → sdld `.map`, Genesis m68k → GNU ld map (find where a RAM var landed). DEFAULT writes ROM + debug file + log to disk (`outputPath` required unless `inline:true`). **`resolveSymbols:['grid','score']` folds those names' addresses ({resolvedSymbols:{grid:{address,hex,region?,ramOffset?}}}) straight into the result — the cheap way to a WRAM variable's address without loading the whole map (or round-tripping it through `symbols`).**\n" +
     "• output:'run' — BUILD + LOAD + RUN + SCREENSHOT in one round trip — the fastest iteration loop. Same build args; runs `frames` frames and returns the screenshot INLINE. `holdInputs` holds controller state; `screenshotPath` writes the PNG to disk instead; `projectName` titles the playtest window.\n" +
-    "• output:'project' — build a project DIRECTORY (`path`) without re-passing the file manifest each call. Entry point is `main.c` (C/SGDK Genesis, GBA, cc65/SDCC C) OR `main.s`/`main.asm` (asm). Every `.c`/`.s`/`.asm` in the dir is a translation unit (linked together), every `.h`/`.inc` an include, and `.bin/.chr/.pcm/.brr/.vgm/...` become binaryIncludes (for `.incbin`). Iterate an on-disk project by re-calling with just `{path, platform}`. **This is the no-boilerplate path for a scaffold({op:'project'}) dir: the per-platform recipe auto-supplies the crt0 + load address — GB/GBC default `gb_crt0.s` + `codeLoc:0x150` (don't hand-pass them!), MSX routes `msx_crt0.s` + `codeLoc:0x4010`, SMS/GG auto-inject their bundled crt0, NES applies the chr-ram-runtime preset. PREFER this over re-passing `crt0Path`/`codeLoc` to output:'rom' for a scaffolded project.**",
+    "• output:'project' — build a project DIRECTORY (`path`) without re-passing the file manifest each call. Entry point is `main.c` (C/SGDK Genesis, GBA, cc65/SDCC C) OR `main.s`/`main.asm` (asm). Every `.c`/`.s`/`.asm` in the dir is a translation unit (linked together), every `.h`/`.inc` an include, and `.bin/.chr/.pcm/.brr/.vgm/...` become binaryIncludes (for `.incbin`). Iterate an on-disk project by re-calling with just `{path, platform}`. **This is the no-boilerplate path for an examples({op:'fork'}) dir: the per-platform recipe auto-supplies the crt0 + load address — GB/GBC default `gb_crt0.s` + `codeLoc:0x150` (don't hand-pass them!), MSX routes `msx_crt0.s` + `codeLoc:0x4010`, SMS/GG auto-inject their bundled crt0, NES applies the chr-ram-runtime preset. PREFER this over re-passing `crt0Path`/`codeLoc` to output:'rom' for a forked project.**",
     {
       output: z.enum(["rom", "romWithDebug", "run", "project"])
         .describe("rom=produce a ROM (default); romWithDebug=ROM + .dbg/.map debug files; run=build+load+run+screenshot; project=build a project directory."),
@@ -838,6 +838,17 @@ export function projectBuildRecipe(platform, names) {
     // commercial ROMs boot in the same host; only our scaffolds failed). Routing
     // msx_crt0.s through crt0 makes ITS header + init the cartridge entry.
     if (has("msx_crt0.s")) { r.crt0File = "msx_crt0.s"; r.codeLoc = 0x4010; }
+  } else if (platform === "pce") {
+    // PCE example projects (they ship pce_hw.h) build on the 'rom32k' preset:
+    // a 32KB HuCard with bank 0 (STARTUP/VECTORS) FIRST in the file at $E000
+    // and banks 1-3 (CODE/RODATA) at $8000-$DFFF, where cc65's pce crt0 TAMs
+    // them before main(). cc65's stock pce.cfg is an 8KB boot bank — too small
+    // for a complete example game — and its documented 32K variant places the
+    // vectors in the LAST file bank, which a HuCard never maps at reset
+    // (verified black screen on geargrafx). An 8KB-sized program still links
+    // and boots identically under this preset, so it's safe for every
+    // pce_hw.h-style project. Bare hand-rolled dirs are left alone.
+    if (has("pce_hw.h")) r.linkerConfig = "rom32k";
   } else if (platform === "sms" || platform === "gg") {
     // SMS/GG: route the project's *_crt0.s through the crt0 channel (like
     // GB/MSX), NOT as a plain source TU. The OLD recipe skipped it on the

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

@@ -56,7 +56,7 @@ async function maybeRestoreState(host, fromState, fromStatePath) {
 // observer wrapper encodes it ASYNCHRONOUSLY, after the agent's response has
 // already gone out. The provider is stripped from the agent-visible result. The
 // frame is captured by reference now (correct frozen state) but rasterized later.
-export function attachObserverFrame(json, host) {
+export function attachObserverFrame(json, host, caption) {
   json._observerFrameProvider = () => {
     try {
       const shot = host.screenshot(); // { pngBase64, width, height }
@@ -65,6 +65,7 @@ export function attachObserverFrame(json, host) {
         : null;
     } catch { return null; }
   };
+  if (caption) json._observerFrameCaption = String(caption);
   return json;
 }
 
@@ -138,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
@@ -265,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."),
@@ -509,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({
@@ -518,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
@@ -532,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; }
       }
@@ -583,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). " : "") +
@@ -829,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),
@@ -840,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')"),
@@ -927,7 +970,7 @@ export function registerWatchMemoryTools(server, z, sessionKey) {
             ? `Stopped at ${r.stoppedAtPC} (your stopAtPC) with PARTIAL output — readMemory the dst to see what's been written so far.`
             : "Did not return within maxFrames AND the watchdog didn't trip — this usually means the entry FELL BACK INTO THE GAME (a wrapper PC with a wrong source, so it never reaches the sentinel) and the game is just free-running. finalPC is inside the main loop, not your routine. Re-check the entry PC (use the routine body, not a wrapper) and the source regs; or lower maxInstructions to fail fast while probing. Bump maxFrames/maxInstructions only if you're sure it's a legitimately huge decompress.")
         + frameLogicCaveat;
-      return jsonContent({
+      return attachObserverFrame(jsonContent({
         returned: r.returned, framesRun: r.framesRun, sandbox,
         ...(r.pure ? { pure: true, pureMode: r.pureMode } : {}),
         ...(r.watchdog ? { watchdog: true, reason: r.reason } : {}),
@@ -935,7 +978,7 @@ export function registerWatchMemoryTools(server, z, sessionKey) {
         ...(r.finalPC ? { finalPC: r.finalPC } : {}),
         ...(r.finalRegs ? { finalRegs: r.finalRegs } : {}),
         note,
-      });
+      }), host, "cpu call");
   }
 
   async function cpuDecompress({ entryPC, sourceAddress, destAddress, maxFrames = 600 }) {

package/src/observer/bus.js

@@ -80,6 +80,79 @@ class ObserverBus extends EventEmitter {
 
 export const observer = new ObserverBus();
 
+// ── Throttled deferred-frame emission ───────────────────────────────────────
+// `call_frame` events carry a freshly-rasterized framebuffer PNG for the
+// human's livestream. Tools attach a PROVIDER thunk (attachObserverFrame) and
+// both transports route it here. Two guarantees:
+//   1. The PNG encode NEVER runs on the agent's critical path (deferred via
+//      setImmediate / the trailing timer).
+//   2. Rate-limited to one frame per FRAME_MIN_INTERVAL_MS **per
+//      (session, tool)** — frame({op:'step'}) called 120× in a narrowing loop
+//      emits at most every 2s, but a step followed immediately by a DIFFERENT
+//      tool's frame (input, state load, …) still shows: distinct tools don't
+//      throttle each other. Trailing-edge: the LAST suppressed frame in a
+//      burst always lands when the window reopens (rendered at fire time =
+//      the current screen, which is exactly what the human wants to converge
+//      on).
+let FRAME_MIN_INTERVAL_MS = 2000;
+export function _setFrameThrottleForTest(ms) { FRAME_MIN_INTERVAL_MS = ms; }
+
+/** @type {Map<string, {lastTs: number, timer: any, pending: null | {provider: Function, meta: object}}>} */
+const _frameThrottle = new Map();
+
+function _emitFrame(provider, meta) {
+  try {
+    const img = provider();
+    if (img) {
+      observer.push({
+        type: "call_frame",
+        sessionKey: meta.sessionKey ?? "http",
+        platform: typeof meta.resolvePlatform === "function" ? (meta.resolvePlatform() ?? meta.platform ?? null) : (meta.platform ?? null),
+        ts: meta.ts ?? Date.now(),
+        tool: meta.tool,
+        ...(meta.caption ? { caption: meta.caption } : {}),
+        images: [img],
+      });
+    }
+  } catch { /* livestream is best-effort; never affects the agent */ }
+}
+
+/**
+ * Queue a deferred framebuffer for the livestream, throttled per
+ * (session, tool). `meta`: { sessionKey, tool, ts?, platform?,
+ * resolvePlatform?, caption? } — resolvePlatform (a thunk) is preferred so
+ * the platform label reflects post-call state (loadMedia sets it DURING the
+ * call). `provider` returns {kind:'image', mimeType, base64} or null; it is
+ * invoked OFF the agent's critical path.
+ */
+export function pushObserverFrame(meta, provider) {
+  const key = `${meta.sessionKey ?? "http"}|${meta.tool ?? "?"}`;
+  let st = _frameThrottle.get(key);
+  if (!st) { st = { lastTs: 0, timer: null, pending: null }; _frameThrottle.set(key, st); }
+  const now = Date.now();
+  if (!st.timer && now - st.lastTs >= FRAME_MIN_INTERVAL_MS) {
+    st.lastTs = now;
+    setImmediate(() => _emitFrame(provider, meta));
+    return;
+  }
+  // Inside the window: stash as the pending trailing frame (latest wins) and
+  // arm the trailing timer once.
+  st.pending = { provider, meta };
+  if (!st.timer) {
+    const delay = Math.max(1, st.lastTs + FRAME_MIN_INTERVAL_MS - now);
+    st.timer = setTimeout(() => {
+      st.timer = null;
+      const p = st.pending;
+      st.pending = null;
+      if (p) {
+        st.lastTs = Date.now();
+        _emitFrame(p.provider, p.meta);
+      }
+    }, delay);
+    if (st.timer.unref) st.timer.unref();   // never hold the process open
+  }
+}
+
 /**
  * Extract image payloads from an MCP tool result. MCP tool results have
  * `content: [{type:'text'|'image', ...}]`. We pull out images so the UI

package/src/observer/livestream.html

@@ -305,7 +305,8 @@
           // One latest image per "tool" (kind = tool name); ev.tool
           // identifies which inspect call produced it.
           s.latestByKind[ev.tool] = { ts: ev.ts, base64: img.base64,
-                                      mimeType: img.mimeType, tool: ev.tool, platform: ev.platform ?? null };
+                                      mimeType: img.mimeType, tool: ev.tool, platform: ev.platform ?? null,
+                                      caption: ev.caption ?? null };
         }
       }
       // screenshotAscii pushes both the PNG (above) AND the raw ANSI
@@ -416,7 +417,8 @@
       card.className = "image-card";
       const dt = new Date(img.ts).toLocaleTimeString();
       const platBadge = img.platform ? `<span class="plat">${escapeHtml(img.platform)}</span> ` : "";
-      card.innerHTML = `<div class="meta"><span>${platBadge}${escapeHtml(img.tool)}</span><span>${dt}</span></div>`;
+      const label = img.caption ? `${img.tool} — ${img.caption}` : img.tool;
+      card.innerHTML = `<div class="meta"><span>${platBadge}${escapeHtml(label)}</span><span>${dt}</span></div>`;
       const el = document.createElement("img");
       el.src = `data:${img.mimeType};base64,${img.base64}`;
       el.alt = img.tool;

package/src/observer/tool-wrap.js

@@ -5,7 +5,7 @@
 //
 // Idempotent per server instance — installs once, repeats are no-ops.
 
-import { observer, extractImages, summarizeForLog } from "./bus.js";
+import { observer, extractImages, summarizeForLog, pushObserverFrame } from "./bus.js";
 import { getHostOrNull } from "../mcp/state.js";
 
 const INSTALLED = Symbol.for("romdev.observer-installed");
@@ -54,6 +54,7 @@ export function installObserverMiddleware(server, sessionKey) {
       const platform = sessionPlatform(sessionKey); // which console this call drives
       let event;
       let frameProvider = null; // deferred framebuffer thunk (encoded async below)
+      let frameCaption = null;  // optional human label for the call_frame event
       if (thrown) {
         event = {
           type: "call",
@@ -98,6 +99,10 @@ export function installObserverMiddleware(server, sessionKey) {
           frameProvider = result._observerFrameProvider;
           delete result._observerFrameProvider;
         }
+        if (result && typeof result === "object" && typeof result._observerFrameCaption === "string") {
+          frameCaption = result._observerFrameCaption;
+          delete result._observerFrameCaption;
+        }
         const inlineImages = extractImages(result);
         const images = inlineImages.length > 0 ? inlineImages : sidebandImages;
         const resultSummary = summarizeForLog(result);
@@ -121,20 +126,18 @@ export function installObserverMiddleware(server, sessionKey) {
       // tool response on observer delivery.
       try { observer.push(event); } catch { /* never let observer kill the tool */ }
 
-      // Deferred frame: encode + push the PNG AFTER the agent's response goes
-      // out, so the (expensive) rasterize never delays the tool. setImmediate
-      // yields the response first; a separate `call_frame` event carries the
-      // image for the human's livestream. Best-effort — never throws into the
-      // tool path. (Only breakpoint/watch tools set a provider.)
+      // Deferred frame: encoded + pushed AFTER the agent's response goes out,
+      // throttled to one per 2s PER (session, tool) with a trailing-edge
+      // emit (bus.js pushObserverFrame) — frame-step loops can't flood the
+      // stream, distinct tools never throttle each other, and the last frame
+      // of a burst always lands. Best-effort — never throws into the tool
+      // path.
       if (frameProvider) {
-        setImmediate(() => {
-          try {
-            const img = frameProvider();
-            if (img) {
-              observer.push({ type: "call_frame", sessionKey, platform, ts: startedAt, tool: name, images: [img] });
-            }
-          } catch { /* livestream is best-effort; never affects the agent */ }
-        });
+        pushObserverFrame({
+          sessionKey, tool: name, ts: startedAt, platform,
+          resolvePlatform: () => sessionPlatform(sessionKey),
+          ...(frameCaption ? { caption: frameCaption } : {}),
+        }, frameProvider);
       }
 
       if (thrown) throw thrown;