romdevtools 0.16.0 → 0.22.0

package/src/host/LibretroHost.js

@@ -43,6 +43,21 @@ const PLATFORM_CORE_OPTIONS = {
   // `… - C-BIOS` machine tree ships in romdev-core-bluemsx/bios and is mirrored
   // into the wasm FS as the system dir (see loadMedia + resolveSystemDir).
   msx: { bluemsx_msxtype: "MSX2+ - C-BIOS" },
+  // VICE mounts a .d64/.tap/.crt but, with autostart off, just sits at the BASIC
+  // `READY.` prompt — the agent would see a blue boot screen, not the game. Force
+  // autostart so a disk/tape image runs the first program automatically (same as
+  // typing LOAD"*",8,1 : RUN). warp-during-autostart skips the slow 1541 load so
+  // the game is up in a fraction of the wall-clock. A bare .prg is injected and
+  // run directly by the core regardless of this; it matters for disk/tape/cart.
+  c64: {
+    vice_autostart: "enabled",
+    vice_autoloadwarp: "enabled",
+    vice_warp_boost: "enabled",
+    // Leave the mounted disk WRITABLE so a save-capable game can write its save
+    // files back into the .d64 (VICE updates the in-FS image in place). Without
+    // this a game's SAVE silently fails / errors — defeating disk-save support.
+    vice_floppy_write_protection: "disabled",
+  },
 };
 
 /**
@@ -188,7 +203,11 @@ export class LibretroHost {
   async loadMedia(args) {
     const mod = this._needMod();
     const { platform } = args;
-    const mediaKind = args.mediaKind ?? defaultMediaKind(platform);
+    // Derive the kind from the file/virtual extension when the caller didn't say
+    // — so a C64 .d64 reports mediaKind:"disk" (writable save target) vs a .prg
+    // "program". For an in-memory load, the virtualName carries the ext.
+    const kindExt = path.extname(args.path || args.virtualName || "");
+    const mediaKind = args.mediaKind ?? defaultMediaKind(platform, kindExt);
 
     // Apply per-platform core option defaults BEFORE retro_load_game.
     // Most cores work with their option defaults; a few need explicit
@@ -282,7 +301,20 @@ export class LibretroHost {
     mod._free(infoPtr);
 
     if (!ok) {
-      throw new Error(`retro_load_game failed for ${mediaPath}`);
+      // This is the failure path for EVERY bad/wrong-platform/corrupt/
+      // unsupported-mapper image — the most common loadMedia failure. The core
+      // returns a bare false, so name the likely causes + the exact checks
+      // rather than leaving the agent with "failed".
+      throw new Error(
+        `The '${platform}' core REFUSED this ${mediaKind || "media"} ` +
+        `(${data.length} bytes${ext ? `, ${ext}` : ""}, path ${mediaPath}). ` +
+        `retro_load_game returned false — the bytes reached the core but it would not accept them. ` +
+        `Common causes: (1) wrong platform for this file (a GB ROM loaded as 'nes', etc.) — ` +
+        `confirm the platform matches the file; (2) a corrupt or TRUNCATED image — re-check the byte length; ` +
+        `(3) an unsupported mapper/board or a missing/!bad header. ` +
+        `Inspect the file with cart({op:'identify'}) to see what platform/mapper it really is, ` +
+        `then load with the matching platform.`,
+      );
     }
 
     this.status.platform = platform;
@@ -417,7 +449,7 @@ export class LibretroHost {
    */
   stepFrames(n) {
     const mod = this._needMod();
-    if (!this.status.loaded) throw new Error("no media loaded");
+    this._needMedia();
     if (this.status.paused) return 0;
     for (let i = 0; i < n; i++) {
       mod._retro_run();
@@ -436,7 +468,7 @@ export class LibretroHost {
    *  Returns the frame count after. */
   renderOneFrame() {
     const mod = this._needMod();
-    if (!this.status.loaded) throw new Error("no media loaded");
+    this._needMedia();
     mod._retro_run();
     this.status.frameCount++;
     if (this.state.lastFrame) {
@@ -575,7 +607,7 @@ export class LibretroHost {
   /** @param {string} name */
   loadState(name) {
     const snapshot = this.namedStates.get(name);
-    if (!snapshot) throw new Error(`no save state named '${name}'`);
+    if (!snapshot) throw new Error(this._noStateError(name));
     return this.unserializeState(snapshot); // returns # cheats cleared
   }
 
@@ -622,10 +654,21 @@ export class LibretroHost {
    *  disturbing the live host). Throws if the slot doesn't exist. */
   getStateBlob(name) {
     const blob = this.namedStates.get(name);
-    if (!blob) throw new Error(`no save state named '${name}'`);
+    if (!blob) throw new Error(this._noStateError(name));
     return blob;
   }
 
+  /** Build a "no save state named X" error that lists the slots that DO exist
+   *  (or says there are none) and names the op to create one. */
+  _noStateError(name) {
+    const names = [...this.namedStates.keys()];
+    return names.length
+      ? `No save state named '${name}'. Existing in-memory slots: ${names.map((n) => `'${n}'`).join(", ")}. ` +
+        `(List them with state({op:'list'}); create one with state({op:'save', name}).)`
+      : `No save state named '${name}' — this session has NO in-memory save slots yet. ` +
+        `Create one with state({op:'save', name:'${name}'}) first (or load from disk with state({op:'load', path})).`;
+  }
+
   /**
    * @param {import("./types.js").MemoryRegion} region
    * @param {number} offset
@@ -648,7 +691,7 @@ export class LibretroHost {
   readMemory(region, offset, length) {
     const mod = this._needMod();
     const id = MemoryRegionToRetro[region];
-    if (id === undefined) throw new Error(`unknown memory region '${region}'`);
+    if (id === undefined) throw new Error(this._unknownRegionError(region));
     const ptr = mod._retro_get_memory_data(id);
     const size = mod._retro_get_memory_size(id);
     if (!ptr || !size) throw new Error(this._emptyRegionError(region));
@@ -666,7 +709,7 @@ export class LibretroHost {
   writeMemory(region, offset, bytes) {
     const mod = this._needMod();
     const id = MemoryRegionToRetro[region];
-    if (id === undefined) throw new Error(`unknown memory region '${region}'`);
+    if (id === undefined) throw new Error(this._unknownRegionError(region));
     const ptr = mod._retro_get_memory_data(id);
     const size = mod._retro_get_memory_size(id);
     if (!ptr || !size) throw new Error(this._emptyRegionError(region));
@@ -676,6 +719,89 @@ export class LibretroHost {
     mod.HEAPU8.set(bytes, ptr + offset);
   }
 
+  // ── C64 disk image read/write (VICE) ───────────────────────────────────────
+  // The VICE WASM core takes content in-memory and exposes no disk memory region,
+  // so these go through dedicated core exports that read/write the LIVE mounted
+  // 1541 disk_image_t directly (see scripts/patches/vice-romdev-memory-regions.patch).
+  // Only the standard 35-track 1541 .d64 (174848 bytes) is supported. unit 8.
+
+  /** True if the loaded core exposes the romdev disk read/write exports. */
+  diskImageSupported() {
+    const mod = this.mod;
+    return !!(mod && typeof mod._romdev_disk_export === "function"
+                  && typeof mod._romdev_disk_import === "function");
+  }
+
+  /**
+   * Read the LIVE mounted disk image out as a flat .d64.
+   * @param {number} [unit] drive unit (default 8)
+   * @returns {Uint8Array} the .d64 bytes (copied out of WASM memory)
+   */
+  exportDiskImage(unit = 8) {
+    const mod = this._needMod();
+    if (typeof mod._romdev_disk_export !== "function") {
+      throw new Error("this core build does not expose disk export (C64/VICE only).");
+    }
+    const len = mod._romdev_disk_export(unit >>> 0, 0) >>> 0;
+    if (!len) {
+      throw new Error("no disk image mounted on this unit, or it is not a 35-track .d64. " +
+        "Load a .d64 with loadMedia({platform:'c64', path}) first.");
+    }
+    const ptr = mod._romdev_disk_ptr();
+    // copy out — the core buffer is reused on the next export
+    return mod.HEAPU8.slice(ptr, ptr + len);
+  }
+
+  /**
+   * Write a flat .d64 back into the LIVE mounted disk image (sector by sector).
+   * @param {Uint8Array} bytes a 174848-byte .d64
+   * @param {number} [unit] drive unit (default 8)
+   * @returns {number} bytes written
+   */
+  importDiskImage(bytes, unit = 8) {
+    const mod = this._needMod();
+    if (typeof mod._romdev_disk_import !== "function") {
+      throw new Error("this core build does not expose disk import (C64/VICE only).");
+    }
+    const data = bytes instanceof Uint8Array ? bytes : new Uint8Array(bytes);
+    const ptr = mod._malloc(data.length);
+    try {
+      mod.HEAPU8.set(data, ptr);
+      const n = mod._romdev_disk_import(ptr, data.length >>> 0, unit >>> 0, 0) >>> 0;
+      if (!n) throw new Error("disk import failed — no writable .d64 mounted on this unit.");
+      return n;
+    } finally {
+      mod._free(ptr);
+    }
+  }
+
+  /**
+   * Write ONE PRG file (name + bytes incl. its 2-byte load address) straight into
+   * the LIVE mounted disk via the vdrive — the "inject a save" primitive.
+   * @param {string} name file name (PETSCII, ≤16 chars)
+   * @param {Uint8Array} bytes the PRG file bytes (load address + body)
+   * @param {number} [unit] drive unit (default 8)
+   */
+  putDiskFile(name, bytes, unit = 8) {
+    const mod = this._needMod();
+    if (typeof mod._romdev_disk_putfile !== "function") {
+      throw new Error("this core build does not expose disk putfile (C64/VICE only).");
+    }
+    const data = bytes instanceof Uint8Array ? bytes : new Uint8Array(bytes);
+    const nameBytes = Buffer.from(String(name) + "\0", "latin1");
+    const namePtr = mod._malloc(nameBytes.length);
+    const dataPtr = mod._malloc(data.length || 1);
+    try {
+      mod.HEAPU8.set(nameBytes, namePtr);
+      mod.HEAPU8.set(data, dataPtr);
+      const rc = mod._romdev_disk_putfile(unit >>> 0, namePtr, dataPtr, data.length >>> 0);
+      if (rc !== 0) throw new Error(`disk putfile failed (rc=${rc}) — no writable .d64 mounted, or the disk is full.`);
+    } finally {
+      mod._free(namePtr);
+      mod._free(dataPtr);
+    }
+  }
+
   reset() {
     const mod = this._needMod();
     mod._retro_reset();
@@ -956,7 +1082,7 @@ export class LibretroHost {
 
   runUntilPC(address, maxFrames = 600) {
     this._needMod();
-    if (!this.status.loaded) throw new Error("no media loaded");
+    this._needMedia();
     if (!this.pcBreakSupported()) {
       throw new Error("PC breakpoint not supported by this core (Genesis today; other cores as patched).");
     }
@@ -988,7 +1114,7 @@ export class LibretroHost {
    */
   runUntilRead(address, maxFrames = 600) {
     this._needMod();
-    if (!this.status.loaded) throw new Error("no media loaded");
+    this._needMedia();
     if (!this.readWatchSupported()) {
       throw new Error("read watchpoint not supported by this core (Genesis today; other cores as patched).");
     }
@@ -1020,7 +1146,7 @@ export class LibretroHost {
    */
   stepInstruction() {
     this._needMod();
-    if (!this.status.loaded) throw new Error("no media loaded");
+    this._needMedia();
     if (!this.pcBreakSupported()) {
       throw new Error("single-step not supported by this core (Genesis today; other cores as patched).");
     }
@@ -1088,8 +1214,8 @@ export class LibretroHost {
    * @param {(host:LibretroHost)=>any} [a.capture] read result from core RAM BEFORE restore
    */
   callSubroutine(a) {
-    const mod = this._needMod();
-    if (!this.status.loaded) throw new Error("no media loaded");
+    this._needMod();
+    this._needMedia();
     if (!this.setRegSupported()) {
       throw new Error("cpu({op:'call'}) not supported by this core (rebuild with romdev_setreg/romdev_getreg).");
     }
@@ -1325,7 +1451,7 @@ export class LibretroHost {
    */
   watchRange(lo, hi, mode, frames) {
     const mod = this._needMod();
-    if (!this.status.loaded) throw new Error("no media loaded");
+    this._needMedia();
     if (!this.rangeWatchSupported()) throw new Error("range watch not supported by this core.");
     const m = mode === "read" ? 1 : mode === "write" ? 2 : 3;
     mod._romdev_range_set(lo >>> 0, hi >>> 0, m, 1);
@@ -1358,7 +1484,7 @@ export class LibretroHost {
    */
   logPCRange(lo, hi, frames) {
     const mod = this._needMod();
-    if (!this.status.loaded) throw new Error("no media loaded");
+    this._needMedia();
     if (!this.rangeWatchSupported()) throw new Error("coverage trace not supported by this core.");
     mod._romdev_cov_set(lo >>> 0, hi >>> 0, 1);
     this._runFramesExclusive(() => false, frames);
@@ -1398,7 +1524,7 @@ export class LibretroHost {
    */
   watchDma(frames) {
     const mod = this._needMod();
-    if (!this.status.loaded) throw new Error("no media loaded");
+    this._needMedia();
     if (!this.dmaWatchSupported()) throw new Error("VDP-DMA watch not supported by this core (Genesis only).");
     mod._romdev_dmawatch_set(1);
     this._runFramesExclusive(() => false, frames);
@@ -1436,6 +1562,21 @@ export class LibretroHost {
     return this.mod;
   }
 
+  // Guard for every op that needs a loaded game. The bare "no media loaded"
+  // left the agent guessing; this names the fix (loadMedia) and the gotcha
+  // (emulator state is in-memory, so a reconnect/restart drops it). The richer
+  // session-aware recovery (echoing the exact prior loadMedia call) lives at the
+  // tool layer in state.js getHost(); this is the host-level twin.
+  _needMedia() {
+    if (!this.status.loaded) {
+      throw new Error(
+        "No media loaded — call loadMedia({platform, path}) before this op. " +
+        "(If you DID load and hit this after a reconnect/restart, the host's in-memory " +
+        "state didn't survive — re-run loadMedia with your ROM to pick back up.)",
+      );
+    }
+  }
+
   /**
    * Build a friendly error message when a memory region is empty (the
    * core didn't expose it). Includes per-platform suggestions when we
@@ -1446,8 +1587,42 @@ export class LibretroHost {
    * "my VRAM writes are being optimized away" spiral — when in fact
    * gambatte exposes VRAM as `gb_vram`, not the generic id.
    */
+  _unknownRegionError(region) {
+    // A bad region name should never leave the agent guessing — list the valid
+    // ones (the single source of truth, MemoryRegionToRetro) so it can pick the
+    // right one. The cross-platform names (system_ram / video_ram / save_ram)
+    // exist everywhere; the rest are platform-specific.
+    const valid = Object.keys(MemoryRegionToRetro).sort();
+    const common = valid.filter((r) => ["system_ram", "video_ram", "save_ram", "rom"].includes(r));
+    return (
+      `Unknown memory region '${region}'. ` +
+      `Common (most platforms): ${common.join(", ")}. ` +
+      `All registered region names: ${valid.join(", ")}. ` +
+      `(Region availability is per platform — some names only resolve on the platform that has that hardware.)`
+    );
+  }
+
   _emptyRegionError(region) {
     const plat = this.status && this.status.platform;
+    // SRAM gets an honest, specific answer: empty save_ram almost always means
+    // "this cart/system has no battery save," NOT "the core is broken."
+    if (region === "save_ram") {
+      if (["atari2600", "atari7800", "lynx"].includes(plat)) {
+        return `'${plat}' has no cartridge battery saves (the hardware never supported them) — ` +
+          `save_ram is always empty here, there's no save file to read/write.`;
+      }
+      if (plat === "c64") {
+        return `C64 has no cartridge battery SRAM — the C64 save medium is the FLOPPY (.d64), ` +
+          `not save_ram (so save_ram is empty, as expected). A game's own KERNAL SAVE writes ` +
+          `into the live disk; capture it with state({op:'exportDisk', path}) (the .d64 then ` +
+          `includes the saved file, re-loadable to resume). Inject an outside save with ` +
+          `state({op:'importDisk', path}) or state({op:'putDiskFile', path}).`;
+      }
+      return `save_ram is empty on platform '${plat}': this CART has no battery save ` +
+        `(check cart({op:'identify'}).saveRam.hasBattery — many ROMs use passwords or no save). ` +
+        `If you expected a save, confirm the cart header marks it battery-backed. ` +
+        `For a full-machine snapshot regardless of SRAM, use state({op:'save'/'load', path}).`;
+    }
     const suggestions = {
       // platform → { generic-region-name: "use this instead" }
       gb:    { video_ram: "gb_vram",  save_ram: "save_ram (likely empty on cartless ROMs — try gb_oam / gb_io / gb_hram for non-VRAM state)" },

package/src/host/callbacks.js

@@ -310,10 +310,18 @@ function handleEnv(mod, state, rawCmd, dataPtr, log) {
         const semi = desc.indexOf("; ");
         if (semi >= 0) {
           const options = desc.substring(semi + 2).split("|");
+          // PRESERVE a value the host already pre-seeded (e.g. via
+          // PLATFORM_CORE_OPTIONS, set before retro_load_game). The core
+          // registering its variables must NOT clobber that override back to
+          // its own default (options[0]) — that silently reset forced options
+          // like bluemsx's machine type / cart mapper. Keep the prior value if
+          // it's still a valid option; otherwise fall back to the default.
+          const prior = state.coreVariables.get(key);
+          const keep = prior && options.includes(prior.value) ? prior.value : options[0];
           state.coreVariables.set(key, {
             description: desc.substring(0, semi),
             options,
-            value: options[0],
+            value: keep,
           });
         }
         ptr += 8;

package/src/host/chafa-render.js

@@ -24,6 +24,7 @@ let lastSettings = "";
 // I had BLOCK=1, ASCII=2; real BLOCK=0x8, ASCII=0x4000. The bad
 // values silently picked an unrelated tag, which is why "ascii"
 // mode was still rendering Unicode block glyphs.
+/* eslint-disable no-unused-vars -- the full chafa tag enum is kept for reference; not all are used. */
 const TAG_SPACE     = 0x1;
 const TAG_SOLID     = 0x2;
 const TAG_STIPPLE   = 0x4;
@@ -35,6 +36,7 @@ const TAG_BRAILLE   = 0x800;
 const TAG_ASCII     = 0x4000;
 const TAG_SEXTANT   = 0x400000;
 const TAG_OCTANT    = 0x4000000;
+/* eslint-enable no-unused-vars */
 
 const SYMBOL_TAGS = {
   // Pure ASCII glyphs (space + printable 7-bit) — most text-shaped,

package/src/host/dsp-state.js

@@ -102,8 +102,8 @@ export function decodeSnes9xDSP(state) {
       bufLastSamples.push(u >= 0x8000 ? u - 0x10000 : u);
     }
     p += 24;
-    const interpPos = state[p] | (state[p + 1] << 8); p += 2;
-    const brrAddr = state[p] | (state[p + 1] << 8); p += 2;
+    p += 2; // interpPos (decoded field, not surfaced)
+    p += 2; // brrAddr (decoded field, not surfaced)
     const env = state[p] | (state[p + 1] << 8); p += 2;
     const hiddenEnvU = state[p] | (state[p + 1] << 8); p += 2;
     const hiddenEnv = hiddenEnvU >= 0x8000 ? hiddenEnvU - 0x10000 : hiddenEnvU;

package/src/host/gpgx-state.js

@@ -17,7 +17,11 @@ const formatCpuState = (s) => s;
 // entry is 5 × 4 = 20 bytes, so memory_map takes 256 × 20 = 5120 bytes.
 // After that come the fields we want.
 const M68K_BASE = 5120; // start of cpu_idle_t poll
+// M68K_POLL / M68K_CYCLES document the struct layout (consumed implicitly by the
+// next offset) — keep them named even though nothing reads them directly.
+// eslint-disable-next-line no-unused-vars
 const M68K_POLL = M68K_BASE + 0;       // 12 bytes
+// eslint-disable-next-line no-unused-vars
 const M68K_CYCLES = M68K_BASE + 12;    // 12 bytes (cycles + refresh_cycles + cycle_end)
 const M68K_DAR = M68K_BASE + 24;       // uint dar[16] — D0..D7 then A0..A7
 const M68K_PC = M68K_DAR + 64;         // uint pc

package/src/host/types.js

@@ -223,18 +223,25 @@ export const MemoryRegionToRetro = {
  */
 
 /**
- * Default mediaKind for a platform when caller doesn't specify.
- * Consoles default to cartridge; C64 defaults to program (`.prg`).
+ * Default mediaKind for a platform when caller doesn't specify. Consoles default
+ * to cartridge; C64 depends on the file kind — a `.d64`/`.g64`/`.d71`/`.d81` is a
+ * disk, a `.tap` is a tape, a `.crt` is a cartridge, and a bare `.prg`/`.p00` is
+ * a program injected directly. The extension is passed when known (loadMedia has
+ * it) so disk/tape images report honestly in status() and the agent knows a
+ * writable disk exists for saves.
  * @param {string} platform
+ * @param {string} [ext] lower- or mixed-case file extension incl. dot, e.g. ".d64"
  * @returns {MediaKind}
  */
-export function defaultMediaKind(platform) {
-  switch (platform) {
-    case "c64":
-      return "program";
-    default:
-      return "cartridge";
+export function defaultMediaKind(platform, ext) {
+  if (platform === "c64") {
+    const e = (ext || "").toLowerCase();
+    if (/\.(d64|g64|d71|d81|d80|d82|nib)$/.test(e)) return "disk";
+    if (/\.(tap|t64)$/.test(e)) return "tape";
+    if (/\.(crt|bin)$/.test(e)) return "cartridge";
+    return "program"; // .prg / .p00 / unknown → injected program
   }
+  return "cartridge";
 }
 
 /**

package/src/http/routes.js

@@ -18,7 +18,7 @@
 // (the app already mounts localhostHostValidation()).
 
 import { buildToolRegistry, runTool, toolJsonSchema } from "./tool-registry.js";
-import { skillPreamble, skillToolReference, buildSkillDoc } from "./skill-doc.js";
+import { buildSkillDoc } from "./skill-doc.js";
 import { swaggerHtml, swaggerAsset } from "./swagger.js";
 import { observer } from "../observer/bus.js";
 import { log } from "../mcp/log.js";

package/src/http/tool-registry.js

@@ -128,7 +128,32 @@ export async function runTool(tool, args, sessionKey) {
       emit({ ok: false, error: text });
       return { ok: false, error: text };
     }
-    const images = extractImages(r);
+    // Observer sidebands — identical to the MCP observer middleware (tool-wrap.js),
+    // because the HTTP path runs handlers directly and would otherwise drop them:
+    //   • _observerImages — a frame the tool wrote to DISK instead of returning
+    //     inline (e.g. screenshot({path:...})); surface it to /livestream anyway.
+    //   • _observerFrameProvider — a DEFERRED framebuffer thunk (frame({op:'verify'}),
+    //     watch/breakpoint tools): the tool advanced/looked at the emulator but
+    //     returns JSON-only to the caller. We encode the PNG ASYNC (setImmediate,
+    //     after the HTTP response goes out) and push it as a `call_frame` event so
+    //     the human's livestream sees the frame at zero cost to the caller.
+    // Strip both from the caller-visible result before it's serialized.
+    let sidebandImages = [];
+    let frameProvider = null;
+    if (r && typeof r === "object") {
+      if (Array.isArray(r._observerImages)) { sidebandImages = r._observerImages; delete r._observerImages; }
+      if (typeof r._observerFrameProvider === "function") { frameProvider = r._observerFrameProvider; delete r._observerFrameProvider; }
+    }
+    if (frameProvider) {
+      setImmediate(() => {
+        try {
+          const img = frameProvider();
+          if (img) observer.push({ type: "call_frame", sessionKey: sessionKey ?? "http", ts: startedAt, tool: tool.name, images: [img] });
+        } catch { /* livestream is best-effort; never affects the caller */ }
+      });
+    }
+    const inlineImages = extractImages(r);
+    const images = inlineImages.length > 0 ? inlineImages : sidebandImages;
     const text = r?.content?.[0]?.text;
     if (typeof text === "string") {
       // most tools return jsonContent(...) → text is JSON; parse it back so the

package/src/mcp/server.js

@@ -140,7 +140,7 @@ async function main() {
     // in verbose mode (log.debug handles that split). This keeps the console
     // quiet in prod while /log stays rich enough to diagnose what an agent did.
     if (req.method === "POST" && req.body) {
-      const { method, id, params } = req.body;
+      const { method, params } = req.body;
       if (method === "tools/call") {
         const argKeys = params?.arguments ? Object.keys(params.arguments) : [];
         const summary = argKeys.map((k) => {

package/src/mcp/state.js

@@ -14,6 +14,24 @@ import { LibretroHost } from "../host/index.js";
 /** @type {Map<string, LibretroHost>} */
 const hosts = new Map();
 
+// What this session last loaded, kept OUTSIDE the host map so it SURVIVES a
+// host eviction (server restart / session reconnect / unload). The host itself
+// is gone in those cases, so the "No ROM loaded" error has nothing to read —
+// this is the breadcrumb that lets the error tell the agent exactly how to
+// recover ("you last loaded <X>; re-run loadMedia to pick back up") instead of
+// a generic wipe. Set by loadMedia on success; never cleared on eviction.
+/** @type {Map<string, {platform?: string, path?: string, fromBase64?: boolean}>} */
+const lastMedia = new Map();
+
+/** Record the media a session last loaded (for recovery hints). @param {string} sessionKey */
+export function rememberLastMedia(sessionKey, info) {
+  lastMedia.set(sessionKey, info);
+}
+/** @param {string} sessionKey */
+export function getLastMedia(sessionKey) {
+  return lastMedia.get(sessionKey) ?? null;
+}
+
 /**
  * @param {string} sessionKey
  * @returns {LibretroHost}
@@ -21,6 +39,24 @@ const hosts = new Map();
 export function getHost(sessionKey) {
   const host = hosts.get(sessionKey);
   if (!host) {
+    // If THIS session loaded media before, the host was evicted (restart /
+    // reconnect / unload) — lead with the exact recovery call instead of the
+    // generic "you're in the wrong session" guidance, which doesn't apply here.
+    const prev = lastMedia.get(sessionKey);
+    if (prev && (prev.path || prev.fromBase64)) {
+      const recall = prev.path
+        ? `loadMedia({ platform: "${prev.platform}", path: "${prev.path}" })`
+        : `loadMedia({ platform: "${prev.platform}", base64: ... })  (your ROM came from base64 — re-supply the bytes)`;
+      throw new Error(
+        "No ROM loaded in this session — the host was evicted (the server restarted, " +
+        "your session reconnected, or the media was unloaded). Emulator state lives in " +
+        "server memory only, so it did not survive. RECOVER by re-running your last load:\n  " +
+        recall +
+        "\nThen replay any boot/navigate steps to get back to where you were. " +
+        "(If instead you expected a DIFFERENT session, you may be sending an inconsistent " +
+        "`x-romdev-session` header — reuse one stable id on every call.)",
+      );
+    }
     throw new Error(
       "No ROM loaded in this session — call loadMedia({path}) first. " +
       "If you DID loadMedia and still see this, your calls are landing in DIFFERENT " +

package/src/mcp/tools/address-to-symbol.js

@@ -18,7 +18,6 @@
 //   - Future: vasm listings, asar symbol tables
 
 import { readFile } from "node:fs/promises";
-import { jsonContent, safeTool } from "../util.js";
 import { parseGnuLdMap, isGnuLdMap } from "../../toolchains/gnu-ld-map.js";
 
 function parseSdldStyle(text) {

package/src/mcp/tools/art-loaders.js

@@ -407,7 +407,7 @@ function aseCelToRgba(cel, colorDepth, palette) {
   return rgba;
 }
 
-async function loadAsepriteSheetImpl({ path: asePath, platform, tile_size = 8, outputDir, slice_strategy = "slices", emit = "raw", emitDefines = false }) {
+async function loadAsepriteSheetImpl({ path: asePath, platform, _tile_size = 8, outputDir, slice_strategy = "slices", emit = "raw", emitDefines = false }) {
   const buf = await readFile(asePath);
   const ase = new Aseprite(buf, path.basename(asePath));
   ase.parse();