romdevtools 0.15.0 → 0.21.0

package/src/mcp/tools/frame.js

@@ -5,7 +5,140 @@ import { PNG } from "pngjs";
 import { getHost } from "../state.js";
 import { imageContent, jsonContent, safeTool } from "../util.js";
 import { decodeOAM, decodePpuRegs, ppuRegsPopulated } from "../../platforms/snes/ppu.js";
-import { stepInstructionCore } from "./watch-memory.js";
+import { stepInstructionCore, attachObserverFrame } from "./watch-memory.js";
+import { getRenderingContextCore } from "./rendering-context.js";
+
+// Normalize each platform's render-context into a CONSERVATIVE renderEnabled
+// (true | false | null). null = "can't tell from the registers" — verify never
+// asserts renderDisabled on null, so a platform we can't decode just relies on
+// the pixel check. This is the cross-platform contract for frame({op:'verify'}).
+function pickRenderFlags(ctx) {
+  const p = ctx.platform;
+  try {
+    if (p === "nes") {
+      const m = ctx.nes && ctx.nes.ppumask;
+      if (!m) return { renderEnabled: null };
+      return { renderEnabled: !!(m.bgVisible || m.spritesVisible) };
+    }
+    if (p === "snes") {
+      const s = ctx.snes;
+      if (!s || !s.ppuRegistersAvailable) return { renderEnabled: null }; // regs not live yet
+      if (s.forcedBlank) return { renderEnabled: false };
+      if (s.brightness === 0) return { renderEnabled: false };
+      return { renderEnabled: true };
+    }
+    if (p === "genesis" || p === "megadrive" || p === "md") {
+      return { renderEnabled: ctx.displayEnabled == null ? null : !!ctx.displayEnabled };
+    }
+    if (p === "sms" || p === "gg") {
+      return { renderEnabled: ctx.screenEnabled == null ? null : !!ctx.screenEnabled };
+    }
+    if (p === "gb" || p === "gbc") {
+      const l = ctx.gb && ctx.gb.lcdc ? ctx.gb.lcdc : ctx.lcdc;
+      if (!l) return { renderEnabled: null };
+      return { renderEnabled: !!l.lcdEnable };
+    }
+    if (p === "gba") {
+      if (ctx.forcedBlank) return { renderEnabled: false };
+      const anyBg = Array.isArray(ctx.displayBg) && ctx.displayBg.some(Boolean);
+      return { renderEnabled: !!(anyBg || ctx.displayObj) };
+    }
+    if (p === "pce") {
+      return { renderEnabled: ctx.screenEnabled == null ? null : !!ctx.screenEnabled };
+    }
+    if (p === "msx") {
+      return { renderEnabled: ctx.screenEnabled == null ? null : !!ctx.screenEnabled };
+    }
+    // atari2600 / atari7800 / lynx: no single reliable display-enable bit — let
+    // the pixel check carry it; don't false-assert.
+    return { renderEnabled: null };
+  } catch {
+    return { renderEnabled: null };
+  }
+}
+
+/**
+ * Dominant-color fraction at/above which a screen reads as "blank" to a
+ * human even though *something* technically rendered. Set to 0.92 (one color
+ * filling >=92% of the screen) — empirically the perceptual threshold where a
+ * backdrop-with-a-lone-sprite still looks empty. Below this, there's enough
+ * on-screen content that a person sees a populated frame. (Truly one/two-color
+ * frames are caught separately by the distinctColors<=1 blankScreen check.)
+ */
+const NEARLY_BLANK_DOMINANT = 0.92;
+
+/**
+ * The cross-platform render-health computation behind frame({op:'verify'}).
+ * Exported so tests can drive it per platform without the MCP wrapper.
+ * @returns plain object {verified, frame, platform, pixels, render, issues?, note}
+ */
+export async function computeVerify(host, frames, sessionKey) {
+  const platform = host.status.platform;
+  if (frames && frames > 0) host.stepFrames(frames);
+  const frameCount = host.status.frameCount;
+
+  // --- pixel content check (platform-agnostic) ---
+  const { width, height, rgba } = host.screenshotRgba();
+  const counts = new Map();
+  const total = width * height;
+  for (let i = 0; i + 3 < rgba.length; i += 4) {
+    const key = (rgba[i] << 16) | (rgba[i + 1] << 8) | rgba[i + 2];
+    counts.set(key, (counts.get(key) || 0) + 1);
+  }
+  let topColor = 0, topCount = 0;
+  for (const [c, n] of counts) if (n > topCount) { topCount = n; topColor = c; }
+  const distinctColors = counts.size;
+  const dominantFraction = total ? topCount / total : 1;
+  const nonDominant = total - topCount;
+  const pixels = {
+    width, height,
+    distinctColors,
+    dominantColor: "#" + topColor.toString(16).padStart(6, "0"),
+    dominantPct: Math.round(dominantFraction * 1000) / 10,
+    nonDominantPixels: nonDominant,
+  };
+
+  // --- render-enable / NMI verdict (reused, per-platform) ---
+  let render;
+  try {
+    const ctx = await getRenderingContextCore({ platform, area: "all", sessionKey });
+    render = { summary: ctx.summary || [], ...pickRenderFlags(ctx) };
+  } catch (e) {
+    render = { summary: [`(render-context decode unavailable for '${platform}': ${e.message})`], renderEnabled: null };
+  }
+
+  // --- frame-0 guard: report raw, no verdict (never cry wolf on boot) ---
+  if (frameCount === 0) {
+    return {
+      verified: null, unsettled: true, frame: 0, platform,
+      note: "No frame has been stepped yet — render state is the pre-boot default and not meaningful. " +
+        "Step frames first (frame({op:'step'}) or pass `frames`), then verify.",
+      pixels, render,
+    };
+  }
+
+  // --- fuse into a verdict + issues[] ---
+  const issues = [];
+  if (distinctColors <= 1) {
+    issues.push({ check: "blankScreen", detail: `the entire framebuffer is one color (${pixels.dominantColor}) — nothing is being drawn.` });
+  } else if (dominantFraction >= NEARLY_BLANK_DOMINANT) {
+    issues.push({ check: "nearlyBlank", detail: `${pixels.dominantPct}% of the screen is a single color (${pixels.dominantColor}); only ${nonDominant} px differ — a backdrop with almost no content reads as blank to a human even though something rendered. Add visible content (a tilemap/background, more sprites) until <${Math.round(NEARLY_BLANK_DOMINANT * 100)}% is one color.` });
+  }
+  if (render && render.renderEnabled === false) {
+    issues.push({ check: "renderDisabled", detail: `display output is disabled per the ${platform} registers: ${render.summary[0] || "see render.summary"}.` });
+  }
+
+  const ok = issues.length === 0;
+  return {
+    verified: ok,
+    frame: frameCount,
+    platform,
+    ...(ok
+      ? { note: `Frame ${frameCount}: rendering looks alive (${distinctColors} colors, ${Math.round((100 - pixels.dominantPct) * 10) / 10}% of the screen is non-backdrop).` }
+      : { issues, note: "Rendering looks broken — see issues[]. For per-platform thresholds + the full checklist, getPlatformDoc({platform, doc:'mental_model'})." }),
+    pixels, render,
+  };
+}
 
 // Get the platform's visible sprites in the generic shape, or null if
 // not supported. Drives the screenshot overlay AND any future agents
@@ -231,6 +364,29 @@ export function registerFrameTools(server, z, sessionKey) {
       return shootPng({ path: outPath, inline, overlayBoxes, scale });
   }
 
+  // op:'verify' — one-call "did the game actually render / is it alive?" health
+  // check for agents debugging WITHOUT vision. Fuses two independent signals:
+  //   1. the render-enable/NMI verdict from getRenderingContext (per-platform
+  //      register decode — already correct, reused not re-derived), and
+  //   2. a pixel-level content check on the live framebuffer (is the screen
+  //      actually showing more than one flat color?).
+  // Frame-0 guard: before any frame is stepped, report the raw condition WITHOUT
+  // an editorial verdict (so the header never "cries wolf" on boot).
+  async function doVerify({ frames }) {
+    const host = getHost(sessionKey);
+    if (!host.status.platform || !host.status.loaded) {
+      throw new Error("frame({op:'verify'}): no media loaded — loadMedia or build({output:'run'}) first.");
+    }
+    const json = jsonContent(await computeVerify(host, frames, sessionKey));
+    // verify's whole job is "look at the screen" — so push the exact frame it
+    // judged to the human's /livestream. Deferred provider: the PNG encode
+    // happens async after the agent's (JSON-only) response goes out, at zero
+    // cost to the agent. computeVerify already stepped the frames, so the
+    // host's current framebuffer IS the verified frame.
+    attachObserverFrame(json, host);
+    return json;
+  }
+
   async function doStepAndShot({ frames, path: outPath, inline }) {
       requireImageTarget(outPath, inline, "frame({op:'stepAndShot'})");
       const host = getHost(sessionKey);
@@ -252,7 +408,7 @@ export function registerFrameTools(server, z, sessionKey) {
 
   server.tool(
     "frame",
-    "Advance the emulator and capture frames. `op`: 'step' | 'screenshot' | 'stepAndShot' | 'stepInstruction'.\n" +
+    "Advance the emulator and capture frames. `op`: 'step' | 'screenshot' | 'stepAndShot' | 'stepInstruction' | 'verify'.\n" +
     "'step': advance N `frames` as fast as possible — NO pacing/audio/vsync. Cores run at WASM speed, so frames:3600 " +
     "(1 min of game time) finishes in ~5-30ms, cheaper than a screenshot. Don't be timid — skip a title with 300, a " +
     "level with 7200; prefer ONE big call.\n" +
@@ -265,10 +421,18 @@ export function registerFrameTools(server, z, sessionKey) {
     "'stepAndShot': step + screenshot in ONE round-trip — the drive-then-look loop. (No overlayBoxes/scale here — png only.)\n" +
     "'stepInstruction': execute exactly ONE CPU instruction and stop (finer than 'step'); freezes the CPU one " +
     "instruction later and returns { pc }. Pair with cpu({op:'read'}) to watch registers change while tracing a routine.\n" +
+    "'verify': one-call 'is the game actually rendering / alive?' health check WITHOUT vision — for the spiral where an " +
+    "agent can't see the screen and doesn't know if a black frame means broken. Pass `frames` to boot-then-check in one " +
+    "call. Fuses (1) a pixel-content scan of the live framebuffer (distinctColors, dominant-color %) and (2) the " +
+    "per-platform render-ENABLE/NMI decode (reused from the rendering-context decoder — works on all 14 platforms). " +
+    "Returns {verified:true|false|null, issues[], pixels, render}. verified:null + unsettled when no frame has been " +
+    "stepped yet (it won't cry wolf on boot — step first). issues[] flags blankScreen/nearlyBlank/renderDisabled. " +
+    "renderDisabled is only raised when the registers SAY so (never on an undecodable platform). Pass/fail with no " +
+    "image tokens; for WHAT to fix, getPlatformDoc({platform, doc:'mental_model'}).\n" +
     "IMAGE CONTRACT (screenshot/stepAndShot): the image goes to `path` (default, returns {path}) OR inline:true — " +
     "you MUST pass one. Keeps PNGs out of context unless asked.",
     {
-      op: z.enum(["step", "screenshot", "stepAndShot", "stepInstruction"]).describe("step frames; capture a screenshot; step+capture in one call; or single-step one CPU instruction."),
+      op: z.enum(["step", "screenshot", "stepAndShot", "stepInstruction", "verify"]).describe("step frames; capture a screenshot; step+capture in one call; single-step one CPU instruction; or verify the game is actually rendering/alive (no vision needed)."),
       frames: z.number().int().min(1).max(1_000_000).default(1).describe("op=step/stepAndShot: frames to advance (1-1,000,000). 36000 (10 min) usually completes in <1s — don't be conservative."),
       format: z.enum(["png", "ascii"]).default("png").describe("op=screenshot: 'png' (default, real image) or 'ascii' (lossy text render)."),
       path: z.string().optional().describe("op=screenshot/stepAndShot: absolute path to write to (required unless inline:true)."),
@@ -286,6 +450,7 @@ export function registerFrameTools(server, z, sessionKey) {
         case "screenshot":      return doScreenshot(args);
         case "stepAndShot":     return doStepAndShot(args);
         case "stepInstruction": return await stepInstructionCore(sessionKey);
+        case "verify":          return await doVerify(args);
         default: throw new Error(`frame: unknown op '${args.op}'`);
       }
     }),

package/src/mcp/tools/index.js

@@ -1,6 +1,6 @@
 // Register MCP tools on the server.
 //
-// The surface is ~34 consolidated domain tools (memory({op}), build({output}),
+// The surface is ~32 consolidated domain tools (memory({op}), build({output}),
 // breakpoint({on}), …) and EVERY one registers at session init. There is no
 // progressive-disclosure / lean mode anymore: the dynamic loadCategory dance
 // never propagated reliably to clients (they don't re-read tools/list after a
@@ -208,7 +208,7 @@ export function registerTools(server, z, sessionKey) {
   if (!sessionKey) sessionKey = randomUUID();
   // Clear validation errors for EVERY tool registered below: turns the SDK's
   // raw JSON validation dump into a plain sentence and catches unknown/misspelled
-  // params (which the SDK otherwise drops silently). One wrap, all 34 tools.
+  // params (which the SDK otherwise drops silently). One wrap, all 32 tools.
   // This is what lets the param descriptions stay terse — the guidance lives in
   // the error (paid only on a bad call), not in every agent's initial context.
   server = withClearToolErrors(server, z);
@@ -259,7 +259,7 @@ export function registerTools(server, z, sessionKey) {
   );
 
   // loadCategory + describeTool DELETED with the progressive-disclosure path:
-  // the whole surface is ~34 tools now and every one registers at session init,
+  // the whole surface is ~32 tools now and every one registers at session init,
   // so the dynamic lean-mode dance (which never worked reliably — clients don't
   // re-read tools/list after list_changed) has no reason to exist. `catalog`
   // still exposes the category map for orientation. (See the consolidation.)
@@ -293,7 +293,7 @@ export function registerTools(server, z, sessionKey) {
   // So by default we register EVERY category at session init. listCategories
   // / loadCategory still exist (idempotent, harmless) for clients that probe
   // Register EVERY category now — there is no lean/deferred mode anymore. The
-  // surface is small enough (~34 tools) that loading it all up front is the
+  // surface is small enough (~32 tools) that loading it all up front is the
   // right call (the dynamic loadCategory dance never propagated reliably to
   // clients). `disclosure.loadCategory("all")` is just the internal "register
   // all categories" helper here, not a user-facing tool.

package/src/mcp/tools/lifecycle.js

@@ -1,5 +1,4 @@
 import { resolveCore } from "../../cores/registry.js";
-import { defaultMediaKind } from "../../host/index.js";
 import { clearHost, getHost, getHostOrNull, resetHost } from "../state.js";
 import { jsonContent, safeTool, textContent } from "../util.js";
 import { resolveCheatCodeForApply } from "./cheats.js";
@@ -19,7 +18,10 @@ export function registerLifecycleTools(server, z, sessionKey) {
     await host.loadMedia({
       platform,
       ...(bytes ? { bytes, virtualName } : { path }),
-      mediaKind: mediaKind ?? defaultMediaKind(platform),
+      // Only force a mediaKind when the caller picked one; otherwise let the host
+      // derive it from the file extension (a C64 .d64 → "disk", .tap → "tape",
+      // .prg → "program") so status reports the kind honestly.
+      ...(mediaKind ? { mediaKind } : {}),
     });
 
     // Pre-seed cheats BEFORE the first frame — so a boot-time cheat (e.g. a Game

package/src/mcp/tools/project.js

@@ -283,6 +283,11 @@ const TEMPLATES = {
       sprite_move: mk("sprite_move", "Joypad-controlled 16x16 sprite over a tiled background. d-pad moves the sprite; verified visible + responsive. Build up an action game from here."),
       music_sfx: mk("music_sfx", "HuC6280 PSG demo: a looping melody plus a button-fired SFX. Shows psg_tone/psg_off across the PSG's wavetable channels."),
       catch_game: mk("catch_game", "A complete tiny game: a paddle catches a falling object with the d-pad; full game loop with waitvsync(), two sprites, collision, scoring."),
+      shmup: mk("shmup", "Vertical shoot-'em-up for PC Engine. Player ship + bullet/enemy object pools, a wave spawner, AABB collisions, score HUD, scrolling-band starfield BG. d-pad flies, button I fires. The base for any action shooter."),
+      platformer: mk("platformer", "Side-scrolling platformer for PC Engine. Gravity + jump + land-on-top platform collision, a multi-screen world streamed via BG X-scroll (BXR), solid platform tiles, sub-pixel physics. d-pad moves, button I jumps."),
+      puzzle: mk("puzzle", "Match-3 / falling-block puzzle for PC Engine. A 6x12 well drawn with BG tiles, a 1x3 active piece you move/rotate/soft-drop/hard-drop, horizontal-triple clears, score. d-pad moves, I rotates, II hard-drops."),
+      sports: mk("sports", "Pong-style sports game for PC Engine. Two paddles + a bouncing ball on a netted court, score to 9, paddle-deflect physics; player 2 falls back to chase-AI when no input. d-pad moves P1."),
+      racing: mk("racing", "Top-down lane racer for PC Engine. Player car at the bottom, obstacle cars spawn from the top and slide down, LEFT/RIGHT switches lanes, speed grows with score, crash freeze + auto-reset. Scrolling road BG."),
     };
   })(),
 
@@ -299,6 +304,11 @@ const TEMPLATES = {
       sprite_move: mk("sprite_move", "Joystick-controlled sprite on a screen-2 background. d-pad moves the sprite; verified visible + responsive. The base for any action game."),
       music_sfx: mk("music_sfx", "AY-3-8910 PSG demo: a looping melody on channel A plus a trigger-fired SFX on channel C, with an on-screen indicator."),
       catch_game: mk("catch_game", "A complete tiny game: a paddle catches falling fruit with the joystick; full game loop with vblank sync, two sprites, collision, scoring."),
+      shmup: mk("shmup", "Vertical-shmup scaffold for MSX (screen 2). Player ship (sprite plane 0) + 4 bullet + 4 enemy object pools, a wave spawner, AABB collision, on-screen SCORE tiles, over a banded starfield filling the whole 32x24 name table. Joystick PORT 1 moves the ship (UP/DOWN/LEFT/RIGHT), trigger A (GTTRIG) fires; PSG blip on fire, noise-ish tone on a kill. Interrupt-free vsync via VDP status S#0. Extend with enemy fire, lives, scrolling stars."),
+      platformer: mk("platformer", "Side-scrolling platformer for MSX (screen 2). Subpixel gravity/jump/land-on-top collision against a table of platforms across a 512-px (64-cell) world, drawn by COLUMN STREAMING into the wrapping screen-2 name table as the camera follows the player; the player sprite draws in screen space. Joystick LEFT/RIGHT walks, trigger A jumps (only when grounded); PSG jump blip. Interrupt-free vsync. Extend with enemies, pickups, goal."),
+      puzzle: mk("puzzle", "Match-3 / falling-block puzzle for MSX (screen 2). A 6-wide x 12-tall well drawn with the BG tilemap (distinct R/G/B cell tiles + grey border + dim field interior so the playfield is always visible). A 1x3 active piece: joystick LEFT/RIGHT shifts, trigger A rotates the colour order, DOWN soft-drops, trigger B hard-drops; horizontal-triple clears score with a PSG chime. Interrupt-free vsync. Extend with vertical/diagonal matches, gravity-collapse, levels."),
+      sports: mk("sports", "Pong-style 2-player sports for MSX (screen 2). Court (green field + white sidelines + dashed centre net) fills the 32x24 name table; two paddles (stacked sprites) + a ball. Player 1 = joystick PORT 1 UP/DOWN; Player 2 = joystick PORT 2 UP/DOWN, falling back to chase-the-ball AI when no second pad is present so it is playable solo. Wall/paddle bounces + scoring with PSG bonks. Interrupt-free vsync. Extend with serve angles, score display, win condition."),
+      racing: mk("racing", "Top-down 3-lane racing for MSX (screen 2). Grey road + green-grass shoulders fill the name table; player car at the bottom, obstacle cars (object pool) spawn at the top and slide down. Joystick LEFT/RIGHT (edge-detected) switches lanes; obstacle speed grows with score; an AABB crash triggers a ~60-frame freeze then auto-reset, with a PSG crash tone. SCORE drawn as tiles. Interrupt-free vsync. Extend with pseudo-3D road, fuel, multiple cars."),
     };
   })(),
 };
@@ -1223,6 +1233,43 @@ TEMPLATES.atari2600 = {
     ext: ".a26",
     describe: "Gallery-shooter (Space-Invaders-shaped) done with the RIGHT TIA objects, not playfield 'barcode' bars: P0 = double-width cannon, P1 + NUSIZ1=%011 = a row of THREE hardware-replicated invaders (one GRP1 write draws all three), M0 = the player shot. Aliens march left/right and drop a step at the edges; fire with the joystick button. The honest 2600-idiomatic way to do this genre — extend by reusing P1 lower for shields or adding M1 as an alien bomb. Verified: marches + renders cannon/aliens/shot.",
   },
+  // ── Genre scaffolds ───────────────────────────────────────────────
+  // The 2600 maps cleanly onto only SOME of the five canonical genres.
+  // shmup + sports are the console's native idioms (Space Invaders /
+  // Pong); racing (top-down) and platformer (single-screen) are honest,
+  // period-correct fits. puzzle (match-3) is deliberately ABSENT — see
+  // the note after this block: a 6x12 multi-colour grid is not
+  // renderable on a tilemap-less, one-COLUPF-per-line, 2-player TIA, so
+  // shipping a "puzzle" key would mean shipping something that isn't a
+  // recognizable match-3. Genre id == template key (createGame maps 1:1).
+  shmup: {
+    main: "templates/shmup.asm",
+    runtime: [],
+    lang: "6507 assembly (dasm)",
+    ext: ".a26",
+    describe: "SHMUP — the 2600's flagship genre (Space Invaders / Galaxian / Demon Attack). Gallery shooter done with the RIGHT TIA objects: P0 = double-width cannon, P1 + NUSIZ1=%011 = a row of THREE hardware-replicated invaders (one GRP1 write draws all three), M0 = the player shot. Aliens march left/right and drop a step at the edges; fire with the joystick button. Same proven body as the `mini_invaders` template. Extend with M1 as an alien bomb or reuse P1 lower for shields.",
+  },
+  sports: {
+    main: "templates/sports.asm",
+    runtime: [],
+    lang: "6507 assembly (dasm)",
+    ext: ".a26",
+    describe: "SPORTS — Pong, the 2600's archetypal sport (Combat / Video Olympics). Two 8-px paddles (P0 left, P1 right), one 2-px ball (BL), top+bottom walls via reflected playfield. Joystick UP/DOWN drives the left paddle; the right paddle is AI (chases the ball's Y). Blip on wall bounce, chime on score. Same proven body as the `paddle` template. Demonstrates multi-object positioning (RESP0/RESP1/RESBL) + the 2-line kernel. Add a real P2 on the second port (SWCHA low nibble) to make it head-to-head.",
+  },
+  racing: {
+    main: "templates/racing.asm",
+    runtime: [],
+    lang: "6507 assembly (dasm)",
+    ext: ".a26",
+    describe: "RACING — top-down vertical-scroll lane racer, the honest 2600 racing idiom (Enduro-style; pseudo-3D road projection needs a per-line table the 4 KB/76-cycle starter budget can't spare). P0 = your car near the bottom (LEFT/RIGHT to weave), reflected playfield draws the two road rails + a dashed centre line that scrolls upward to convey speed, P1 + M0 = descending traffic/hazards you must dodge. Speed (and score) ramps the longer you survive; a TIA-collision crash flashes the screen red and resets your speed. Extend with M1 as a 3rd hazard or NUSIZ1 for two-abreast traffic.",
+  },
+  platformer: {
+    main: "templates/platformer.asm",
+    runtime: [],
+    lang: "6507 assembly (dasm)",
+    ext: ".a26",
+    describe: "PLATFORMER — SINGLE-SCREEN (Pitfall! / Montezuma / Kangaroo idiom). The 2600 has NO hardware scroll, no tilemap, 128 B RAM — a smooth side-scroller is not the honest fit (real games flip whole screens). This ships the genre CORE: fixed-point gravity + a jump arc (FIRE button), and land-on-top collision tested in CODE (not TIA collision, since you must know WHICH surface to stand on) against a 4-entry platform table drawn as horizontal playfield bars (the only TIA object wide enough to be a platform). Joystick walks L/R. Extend with ladders (UP/DOWN over a ladder x-span), an enemy on P1, a thrown rock on M0, or Pitfall-style screen-flipping at the edges. NOT a scroller — single screen by design.",
+  },
 };
 
 // R22: Atari 7800 promoted to multi-template platform. Each template is
@@ -1810,15 +1857,13 @@ async function createGameCore({ platform, genre, name, path: projPath, title, ov
         ? CANONICAL_GENRES.filter((g) => platformTemplates[g])
         : [];
       if (availableGenres.length === 0) {
-        // Point at the real, working project templates each genre-less
-        // platform actually ships, so the agent has a concrete next step
-        // instead of a bare "default".
-        const PROJECT_TEMPLATE_HINTS = {
-          msx: "default, sprite_move, music_sfx, catch_game",
-          pce: "default, sprite_move, music_sfx, catch_game",
-          atari2600: "default, single_screen, paddle, mini_invaders, music_demo",
-        };
-        const hint = PROJECT_TEMPLATE_HINTS[platform];
+        // Reached only by a platform that ships NO canonical genre yet (every
+        // tier-1 platform now ships at least one — atari2600 ships 4, the rest
+        // ship all 5 — so in practice this is the bring-up / non-genre tier).
+        // List that platform's real project templates so the agent has a
+        // concrete next step instead of a bare "default".
+        const projTemplates = platformTemplates ? Object.keys(platformTemplates) : [];
+        const hint = projTemplates.length ? projTemplates.join(", ") : null;
         throw new Error(
           `createGame: no genre scaffolds for platform '${platform}' yet. ` +
           `Supported platforms: ${genrePlatforms.join(", ") || "(none)"}. ` +

package/src/mcp/tools/state.js

@@ -3,6 +3,21 @@ import path from "node:path";
 import { getHost } from "../state.js";
 import { jsonContent, safeTool } from "../util.js";
 
+// Resolve a state-file `path`. An ABSOLUTE path is used as-is. A RELATIVE path
+// is resolved against the LOADED ROM's directory (the agent's mental model is
+// "save states live next to my ROM") — NOT the server's CWD, which is opaque to
+// the caller and was a silent ENOENT footgun (v0.15.0 feedback #1). Falls back
+// to CWD only when no ROM path is known (e.g. ROM loaded from base64).
+export function resolveStatePath(p, host) {
+  if (!p || path.isAbsolute(p)) return p;
+  const media = host?.status?.mediaPath;
+  // mediaPath is "<memory…>" for base64 loads — not a real dir; skip those.
+  if (media && !media.startsWith("<") && path.isAbsolute(media)) {
+    return path.resolve(path.dirname(media), p);
+  }
+  return path.resolve(p);
+}
+
 // Per-session state-diff baselines (op:'diff'). Module-local; keyed by sessionKey.
 const _stateDiffSnaps = new Map();
 function stateDiffSnapshots(key) {
@@ -19,16 +34,17 @@ async function saveStateCore({ name, path: outPath }, sessionKey) {
       const host = getHost(sessionKey);
       const done = [];
       if (name) { host.saveState(name); done.push(`slot '${name}'`); }
-      if (outPath) {
+      const resolvedOut = outPath ? resolveStatePath(outPath, host) : null;
+      if (resolvedOut) {
         const blob = host.serializeState();
-        await mkdir(path.dirname(outPath), { recursive: true });
-        await writeFile(outPath, blob);
-        done.push(`${blob.length} bytes → ${outPath}`);
+        await mkdir(path.dirname(resolvedOut), { recursive: true });
+        await writeFile(resolvedOut, blob);
+        done.push(`${blob.length} bytes → ${resolvedOut}`);
       }
       return {
         saved: true,
         ...(name ? { name } : {}),
-        ...(outPath ? { path: outPath } : {}),
+        ...(resolvedOut ? { path: resolvedOut, ...(resolvedOut !== outPath ? { resolvedPath: resolvedOut } : {}) } : {}),
         platform: host.status.platform,
         note: `Saved ${done.join(" + ")}.` + (outPath ? " Restore across sessions with state({op:'load', path}) after loading the same ROM." : ""),
       };
@@ -38,12 +54,14 @@ async function saveStateCore({ name, path: outPath }, sessionKey) {
 async function exportStateCore({ fromSlot, path: outPath }, sessionKey) {
       const host = getHost(sessionKey);
       const blob = host.getStateBlob(fromSlot); // throws if the slot is missing — no host disturbance
-      await mkdir(path.dirname(outPath), { recursive: true });
-      await writeFile(outPath, blob);
+      const resolvedOut = resolveStatePath(outPath, host);
+      await mkdir(path.dirname(resolvedOut), { recursive: true });
+      await writeFile(resolvedOut, blob);
       return {
         exported: true,
         fromSlot,
-        path: outPath,
+        path: resolvedOut,
+        ...(resolvedOut !== outPath ? { resolvedPath: resolvedOut } : {}),
         bytes: blob.length,
         platform: host.status.platform,
         note: "Copied the slot to disk; the live host was not touched (no pause/resume needed).",
@@ -56,8 +74,9 @@ async function loadStateCore({ name, path: inPath, render = true }, sessionKey)
       if (name && inPath) throw new Error("state({op:'load'}): provide `name` OR `path`, not both.");
       const host = getHost(sessionKey);
       let cheatsCleared = 0;
-      if (inPath) {
-        const blob = new Uint8Array(await readFile(inPath));
+      const resolvedIn = inPath ? resolveStatePath(inPath, host) : null;
+      if (resolvedIn) {
+        const blob = new Uint8Array(await readFile(resolvedIn));
         cheatsCleared = host.unserializeState(blob) || 0;
       } else {
         cheatsCleared = host.loadState(name) || 0;
@@ -66,7 +85,7 @@ async function loadStateCore({ name, path: inPath, render = true }, sessionKey)
       if (render) { host.renderOneFrame(); rendered = true; }
       return {
         loaded: true,
-        ...(inPath ? { path: inPath } : { name }),
+        ...(resolvedIn ? { path: resolvedIn, ...(resolvedIn !== inPath ? { resolvedPath: resolvedIn } : {}) } : { name }),
         platform: host.status.platform,
         rendered,
         ...(host.status.paused && rendered ? { renderedWhilePaused: true } : {}),
@@ -79,6 +98,153 @@ function listStatesCore(_args, sessionKey) {
   return { states: getHost(sessionKey).listStates() };
 }
 
+// SRAM presence: the battery-backed cartridge save RAM size for the loaded ROM
+// (0 = this cart/system has no battery save). Used by exportSram/importSram and
+// surfaced so an agent knows whether a save file even exists.
+function sramSize(host) {
+  try { return host.regionSize("save_ram"); } catch { return 0; }
+}
+
+/** op:'exportSram' — write the cartridge's battery SAVE RAM to a .sav file.
+ * This is the actual save-game file (distinct from a whole-machine savestate):
+ * the bytes a real cart keeps on its battery. Empty on a no-battery cart. */
+async function exportSramCore({ path: outPath }, sessionKey) {
+  const host = getHost(sessionKey);
+  const size = sramSize(host);
+  if (!size) {
+    throw new Error(
+      `state({op:'exportSram'}): the loaded ROM has no battery save RAM ` +
+      `(platform '${host.status.platform}', size 0). Either this cart has no battery ` +
+      `save, or this system never had cartridge saves (Atari 2600/7800, Lynx; C64 saves ` +
+      `are disk-based). Use state({op:'save', path}) for a full-machine savestate instead.`);
+  }
+  const blob = host.readMemory("save_ram", 0, size);
+  const resolved = resolveStatePath(outPath, host);
+  await mkdir(path.dirname(resolved), { recursive: true });
+  await writeFile(resolved, Buffer.from(blob));
+  return {
+    exportedSram: true,
+    path: resolved,
+    ...(resolved !== outPath ? { resolvedPath: resolved } : {}),
+    bytes: size,
+    platform: host.status.platform,
+    note: "Wrote the cartridge's battery SAVE RAM (the .sav save-game file). Restore with " +
+      "state({op:'importSram', path}) after loading the same ROM. This is the SAVE FILE, " +
+      "not a savestate — edit it offline (it's raw SRAM) or inject one a player made elsewhere.",
+  };
+}
+
+/** op:'importSram' — load a .sav file back into the cartridge's battery SAVE RAM. */
+async function importSramCore({ path: inPath }, sessionKey) {
+  const host = getHost(sessionKey);
+  const size = sramSize(host);
+  if (!size) {
+    throw new Error(
+      `state({op:'importSram'}): the loaded ROM has no battery save RAM ` +
+      `(platform '${host.status.platform}', size 0) — nowhere to load a .sav into.`);
+  }
+  const resolved = resolveStatePath(inPath, host);
+  const blob = new Uint8Array(await readFile(resolved));
+  if (blob.length !== size) {
+    // Size mismatch is the classic wrong-game/wrong-region footgun — surface it,
+    // but allow a smaller blob (zero-pad) since some dumps trim trailing zeros.
+    if (blob.length > size) {
+      throw new Error(
+        `state({op:'importSram'}): .sav is ${blob.length} bytes but this cart's SAVE RAM is ${size} ` +
+        `— too large (wrong game/region?). Refusing to truncate.`);
+    }
+  }
+  host.writeMemory("save_ram", 0, blob);
+  return {
+    importedSram: true,
+    path: resolved,
+    ...(resolved !== inPath ? { resolvedPath: resolved } : {}),
+    bytes: blob.length,
+    sramSize: size,
+    ...(blob.length < size ? { zeroPadded: size - blob.length } : {}),
+    platform: host.status.platform,
+    note: "Loaded the .sav into the cartridge's battery SAVE RAM. The running game sees it " +
+      "on its next save-RAM read (some games re-read only on a load/menu). " +
+      (blob.length < size ? `Blob was smaller than SRAM (${blob.length}<${size}); the tail kept its prior bytes.` : ""),
+  };
+}
+
+/** op:'exportDisk' — write the LIVE mounted C64 .d64 disk image to a file.
+ * The C64 analogue of exportSram: a game saves by writing files to its disk, and
+ * this snapshots the whole disk (incl. any saves the game wrote). C64/VICE only. */
+async function exportDiskCore({ path: outPath, unit = 8 }, sessionKey) {
+  const host = getHost(sessionKey);
+  if (!host.diskImageSupported || !host.diskImageSupported()) {
+    throw new Error("state({op:'exportDisk'}): disk images are a C64 feature (VICE). " +
+      `The loaded platform is '${host.status.platform}'.`);
+  }
+  const blob = host.exportDiskImage(unit); // throws if no .d64 mounted
+  const resolved = resolveStatePath(outPath, host);
+  await mkdir(path.dirname(resolved), { recursive: true });
+  await writeFile(resolved, Buffer.from(blob));
+  return {
+    exportedDisk: true,
+    path: resolved,
+    ...(resolved !== outPath ? { resolvedPath: resolved } : {}),
+    bytes: blob.length,
+    unit,
+    note: "Wrote the LIVE 1541 disk image (.d64) — the C64 save medium. Re-load it later " +
+      "with loadMedia({platform:'c64', path}) (it autostarts), or push it back into a " +
+      "running session with state({op:'importDisk', path}). This captures any files the " +
+      "game wrote to disk.",
+  };
+}
+
+/** op:'importDisk' — write a .d64 file back into the LIVE mounted C64 disk image. */
+async function importDiskCore({ path: inPath, unit = 8 }, sessionKey) {
+  const host = getHost(sessionKey);
+  if (!host.diskImageSupported || !host.diskImageSupported()) {
+    throw new Error("state({op:'importDisk'}): disk images are a C64 feature (VICE). " +
+      `The loaded platform is '${host.status.platform}'.`);
+  }
+  const resolved = resolveStatePath(inPath, host);
+  const blob = new Uint8Array(await readFile(resolved));
+  if (blob.length !== 174848) {
+    throw new Error(`state({op:'importDisk'}): '${resolved}' is ${blob.length} bytes — not a ` +
+      `standard 174848-byte 35-track .d64. Only that format round-trips through the live drive.`);
+  }
+  const n = host.importDiskImage(blob, unit);
+  return {
+    importedDisk: true,
+    path: resolved,
+    ...(resolved !== inPath ? { resolvedPath: resolved } : {}),
+    bytes: n,
+    unit,
+    note: "Wrote the .d64 into the running C64's mounted disk. The game sees it on its next " +
+      "disk access (a load/menu). Use this to inject a save disk a player made elsewhere.",
+  };
+}
+
+/** op:'putDiskFile' — write ONE PRG file into the LIVE mounted C64 disk (inject a save). */
+async function putDiskFileCore({ path: inPath, name, unit = 8 }, sessionKey) {
+  const host = getHost(sessionKey);
+  if (!host.diskImageSupported || !host.diskImageSupported()) {
+    throw new Error("state({op:'putDiskFile'}): disk files are a C64 feature (VICE). " +
+      `The loaded platform is '${host.status.platform}'.`);
+  }
+  if (!inPath) throw new Error("state({op:'putDiskFile'}): `path` (the file to write) is required.");
+  const resolved = resolveStatePath(inPath, host);
+  const blob = new Uint8Array(await readFile(resolved));
+  // file name on disk: explicit `name`, else the source basename (sans extension), uppercased
+  const fname = (name || path.basename(resolved).replace(/\.[^.]+$/, ""))
+    .toUpperCase().replace(/[^A-Z0-9 ]/g, "").slice(0, 16) || "FILE";
+  host.putDiskFile(fname, blob, unit);
+  return {
+    wroteDiskFile: true,
+    name: fname,
+    path: resolved,
+    bytes: blob.length,
+    unit,
+    note: "Wrote one PRG file into the running C64's mounted disk via the drive. Read the " +
+      "whole disk back with state({op:'exportDisk', path}) or cart({op:'extract'}).",
+  };
+}
+
 /** op:'dump' — raw libretro blob to disk for forensic inspection (+ optional findHex). */
 async function dumpStateCore({ path: outPath, findHex, maxMatches = 32 }, sessionKey) {
       const host = getHost(sessionKey);
@@ -159,9 +325,10 @@ export function registerStateTools(server, z, sessionKey) {
     "'list': named in-memory slots. 'diff': whole-machine 'did ANYTHING change?' (coarser than memory diff) — " +
     "snapOrDiff:'snapshot' captures, 'diff' compares.",
     {
-      op: z.enum(["save", "load", "list", "export", "dump", "diff"]).describe("save/load a state; list slots; export a slot to disk; dump the raw blob; diff the whole machine."),
-      name: z.string().min(1).optional().describe("op=save/load: in-memory slot name. op=diff: snapshot label (default 'default')."),
-      path: z.string().optional().describe("op=save: also write the blob here (survives restarts). op=load: restore from this disk blob. op=export/dump: write the blob here (required)."),
+      op: z.enum(["save", "load", "list", "export", "dump", "diff", "exportSram", "importSram", "exportDisk", "importDisk", "putDiskFile"]).describe("save/load a savestate (whole machine); list slots; export a slot to disk; dump the raw blob; diff the whole machine. SRAM (the cartridge BATTERY SAVE FILE, distinct from a savestate): exportSram writes the .sav, importSram loads one back. C64 DISK (VICE; the C64 save medium is a floppy, not battery SRAM): exportDisk writes the live .d64, importDisk pushes a .d64 back into the running drive, putDiskFile injects one PRG file into the live disk."),
+      name: z.string().min(1).optional().describe("op=save/load: in-memory slot name. op=diff: snapshot label (default 'default'). op=putDiskFile: file name on the disk (≤16 chars; default = source basename)."),
+      unit: z.number().int().min(8).max(11).default(8).describe("op=exportDisk/importDisk/putDiskFile (C64): drive unit (default 8)."),
+      path: z.string().optional().describe("op=save: also write the blob here (survives restarts). op=load: restore from this disk blob. op=export/dump: write the blob here (required). A RELATIVE path resolves against the loaded ROM's directory (NOT the server CWD); an absolute path is used as-is. The result echoes `resolvedPath` when they differ."),
       // load
       render: z.boolean().default(true).describe("op=load: step one frame after restoring so the framebuffer reflects it (fixes the stale-screenshot footgun). false = stay at the exact restored instant."),
       // export
@@ -190,6 +357,26 @@ export function registerStateTools(server, z, sessionKey) {
           if (!args.snapOrDiff) throw new Error("state({op:'diff'}): `snapOrDiff` ('snapshot' or 'diff') is required.");
           return jsonContent(diffStateCore(args, sessionKey));
         }
+        case "exportSram": {
+          if (!args.path) throw new Error("state({op:'exportSram'}): `path` (where to write the .sav) is required.");
+          return jsonContent(await exportSramCore(args, sessionKey));
+        }
+        case "importSram": {
+          if (!args.path) throw new Error("state({op:'importSram'}): `path` (the .sav to load) is required.");
+          return jsonContent(await importSramCore(args, sessionKey));
+        }
+        case "exportDisk": {
+          if (!args.path) throw new Error("state({op:'exportDisk'}): `path` (where to write the .d64) is required.");
+          return jsonContent(await exportDiskCore(args, sessionKey));
+        }
+        case "importDisk": {
+          if (!args.path) throw new Error("state({op:'importDisk'}): `path` (the .d64 to load) is required.");
+          return jsonContent(await importDiskCore(args, sessionKey));
+        }
+        case "putDiskFile": {
+          if (!args.path) throw new Error("state({op:'putDiskFile'}): `path` (the PRG file to inject) is required.");
+          return jsonContent(await putDiskFileCore(args, sessionKey));
+        }
         default: throw new Error(`state: unknown op '${args.op}'`);
       }
     }),