romdevtools 0.15.0 → 0.21.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
@@ -676,6 +695,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();
@@ -1448,6 +1550,25 @@ export class LibretroHost {
    */
   _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/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/skill-doc.js

@@ -18,7 +18,7 @@ import { toolJsonSchema } from "./tool-registry.js";
  */
 export const mcpPreamble = [
   "romdev: homebrew retro game development + reverse-engineering for coding agents.",
-  "All ~34 tools register at session init — call any by name directly, no loading step. Each is a domain VERB with an operation axis: memory({op}), build({output}), breakpoint({on}), cpu({op}), sprites({op}), tiles({op}), disasm({target}), romPatch({op}), …",
+  "All ~32 tools register at session init — call any by name directly, no loading step. Each is a domain VERB with an operation axis: memory({op}), build({output}), breakpoint({on}), cpu({op}), sprites({op}), tiles({op}), disasm({target}), romPatch({op}), …",
   "catalog({op:'categories'}) maps the tools by purpose (a guide, not a gate); catalog({op:'status'}) is a session re-orient.",
 ].join("\n");
 

package/src/http/tool-registry.js

@@ -1,7 +1,7 @@
 // Tool registry harvester — the single source the HTTP route/skill/OpenAPI
 // surfaces build from.
 //
-// The MCP path registers 34 tools via registerTools(server, z, sessionKey),
+// The MCP path registers 32 tools via registerTools(server, z, sessionKey),
 // where `server` is an McpServer and each handler closes over `sessionKey` for
 // per-session host isolation. The HTTP surfaces (POST /tool/{name},
 // /skills/romdev/SKILL.md, /openapi.json, /documentation) want the EXACT same handlers,
@@ -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/tools/cart-parts.js

@@ -11,6 +11,66 @@ import { readFile, writeFile, mkdir } from "node:fs/promises";
 import path from "node:path";
 import { jsonContent, safeTool } from "../util.js";
 import { identifyRomCore } from "./rom-id.js";
+import { prgToD64, readDirectory as readD64Dir, extractFile as extractD64File } from "../../platforms/c64/d64.js";
+
+// ─── C64 .d64 disk image ──────────────────────────────────────────
+//
+// The C64 world ships and loads games as .d64 disk images (the new Commodore 64
+// Ultimate FPGA hardware + the homebrew/demo scene), not as bare .prg files. A
+// cc65 build emits a .prg; packDisk wraps it into a distributable, autostart-able
+// .d64. Extract on a .d64 lists/pulls its files back out.
+
+/**
+ * Pack a built .prg into a .d64 disk image (the distribution format).
+ * @param {{prgPath?:string, bodyPath?:string, romPath?:string, base64?:string,
+ *          outputPath?:string, name?:string, diskName?:string, inline?:boolean}} args
+ */
+export async function packDiskCore(args) {
+  const src = args.prgPath || args.bodyPath || args.romPath;
+  let prg;
+  if (args.base64) prg = new Uint8Array(Buffer.from(args.base64, "base64"));
+  else if (src) prg = new Uint8Array(await readFile(src));
+  else throw new Error("cart({op:'packDisk'}): provide `prgPath` (the built .prg) or `base64`.");
+
+  const name = (args.name || (src ? path.basename(src).replace(/\.[^.]+$/, "") : "GAME"))
+    .toUpperCase().replace(/[^A-Z0-9 ]/g, "").slice(0, 16) || "GAME";
+  const d64 = prgToD64(prg, { name, diskName: args.diskName || name });
+
+  if (args.inline) {
+    return { packed: true, format: "d64", name, bytes: d64.length, base64: Buffer.from(d64).toString("base64") };
+  }
+  const out = args.outputPath
+    || (src ? src.replace(/\.[^.]+$/, "") + ".d64" : null);
+  if (!out) throw new Error("cart({op:'packDisk'}): `outputPath` required (or pass `prgPath` to derive it, or inline:true).");
+  await writeFile(out, Buffer.from(d64));
+  return {
+    packed: true, format: "d64", name, bytes: d64.length, path: out,
+    note: "Autostart-able 1541 disk image. Load it with loadMedia({platform:'c64', path}) — it boots the program automatically. This is the format the Commodore 64 Ultimate hardware and the homebrew scene load.",
+  };
+}
+
+/** Read a .d64's directory + (optionally) extract a file. */
+export async function extractDiskCore(args) {
+  const data = new Uint8Array(await readFile(args.path));
+  const dir = readD64Dir(data);
+  const result = { format: "d64", path: args.path, files: dir };
+  // If a specific file was named, also return its bytes.
+  const which = args.name;
+  if (which != null) {
+    const bytes = extractD64File(data, which);
+    if (!bytes) throw new Error(`cart({op:'extract'}) .d64: no file '${which}' on the disk (have: ${dir.map((d) => d.name).join(", ") || "none"}).`);
+    if (args.inline) result.file = { name: which, bytes: bytes.length, base64: Buffer.from(bytes).toString("base64") };
+    else {
+      const out = args.outputDir
+        ? path.join(args.outputDir, which.replace(/[^A-Za-z0-9._-]/g, "_") + ".prg")
+        : args.path.replace(/\.d64$/i, "") + "." + which.replace(/[^A-Za-z0-9._-]/g, "_") + ".prg";
+      if (args.outputDir) await mkdir(args.outputDir, { recursive: true });
+      await writeFile(out, Buffer.from(bytes));
+      result.file = { name: which, bytes: bytes.length, path: out };
+    }
+  }
+  return result;
+}
 
 // ─── extractCart ──────────────────────────────────────────────────
 
@@ -590,7 +650,7 @@ function wrapC64({ loadAddress, bodyPath, romPath }) {
 export function registerCartPartsTools(server, z) {
   server.tool(
     "cart",
-    "Cartridge container ops — identify / split / reassemble a ROM file. `op`: 'identify' | 'extract' | 'wrap'.\n" +
+    "Cartridge container ops — identify / split / reassemble a ROM file. `op`: 'identify' | 'extract' | 'wrap' | 'packDisk'.\n" +
     "'identify': sniff an unknown ROM/zip's platform (which core to load). Handles zip-wrapped ROMs; `path` OR " +
     "`base64` (+`hint` ext for headerless). Returns {platform, format, title, mapper, region, sizes, confidence}. " +
     "RE next steps: cheats({op:'lookup'}) is a free labeled memory/code map; disasm is how you change behavior.\n" +
@@ -601,9 +661,13 @@ export function registerCartPartsTools(server, z) {
     "Round-trips with 'wrap' (extract → romPatch a part → wrap → build).\n" +
     "'wrap': generate a build-ready wrapper source (+ NES linker config; null for other platforms) that reassembles " +
     "parts back into a cart. NES auto-generates the iNES header from mapper+mirror (chrPath:null for CHR-RAM; only " +
-    "prgBanks 1/2 = NROM-128/256). Per-platform part paths in the param hints (pass `romPath` for a one-shot whole-body incbin).",
+    "prgBanks 1/2 = NROM-128/256). Per-platform part paths in the param hints (pass `romPath` for a one-shot whole-body incbin).\n" +
+    "'packDisk' (C64): wrap a built `.prg` (`prgPath` or `base64`) into a distributable, autostart-able `.d64` disk " +
+    "image — the format the new Commodore 64 Ultimate hardware and the homebrew/demo scene actually load. " +
+    "Writes `<prg>.d64` (or `outputPath`/`inline`). loadMedia({platform:'c64', path:<.d64>}) boots it directly. " +
+    "(extract on a `.d64` lists its directory; pass `name` to pull one file off the disk.)",
     {
-      op: z.enum(["identify", "extract", "wrap"]).describe("identify the ROM's platform; extract into parts; wrap parts back into a cart."),
+      op: z.enum(["identify", "extract", "wrap", "packDisk"]).describe("identify the ROM's platform; extract into parts (or list/pull files from a C64 .d64); wrap parts back into a cart; packDisk wraps a C64 .prg into a distributable .d64 disk image."),
       // identify
       path: z.string().optional().describe("op=identify/extract: absolute path to the ROM file."),
       base64: z.string().optional().describe("op=identify: base64 ROM bytes (OR path)."),
@@ -631,18 +695,26 @@ export function registerCartPartsTools(server, z) {
       a78HeaderPath: z.string().optional().describe("op=wrap Atari 7800: the 128-byte A78 header (if present)."),
       bodyBytes: z.number().int().min(1).optional().describe("op=wrap Atari 7800: size of the 6502 image body (computes the cart origin; default 0xC000)."),
       loadAddress: z.number().int().min(0).max(0xFFFF).optional().describe("op=wrap C64: load address (default 0x0801)."),
+      // packDisk (C64 .d64)
+      name: z.string().optional().describe("op=packDisk: disk file name (PETSCII, ≤16 chars; default from prgPath). op=extract .d64: a file to pull off the disk."),
+      diskName: z.string().optional().describe("op=packDisk: disk label (≤16 chars; default = name)."),
+      outputPath: z.string().optional().describe("op=extract: dir for parts (+ manifest.json). op=packDisk: .d64 output path (default: prgPath with a .d64 extension). Required unless inline:true."),
     },
     safeTool(async (args) => {
       switch (args.op) {
         case "identify": return await identifyRomCore(args);
         case "extract": {
           if (!args.path) throw new Error("cart({op:'extract'}): `path` is required.");
+          // A .d64 is a disk image (a container of files), not a flat cart —
+          // route it to the disk reader so extract lists/pulls its contents.
+          if (/\.d64$/i.test(args.path)) return jsonContent(await extractDiskCore(args));
           return jsonContent(await extractCartCore(args));
         }
         case "wrap": {
           if (!args.platform) throw new Error("cart({op:'wrap'}): `platform` is required.");
           return jsonContent(await wrapRomFromPartsCore(args));
         }
+        case "packDisk": return jsonContent(await packDiskCore(args));
         default: throw new Error(`cart: unknown op '${args.op}'`);
       }
     }),