romdevtools 0.71.0 → 0.84.0

package/src/host/LibretroHost.js

@@ -19,7 +19,7 @@
 import { readFile } from "node:fs/promises";
 import path from "node:path";
 import os from "node:os";
-import { mkdtempSync, readdirSync, statSync, readFileSync, existsSync } from "node:fs";
+import { mkdtempSync, readdirSync, statSync, readFileSync, writeFileSync, existsSync, unlinkSync } from "node:fs";
 import { fileURLToPath } from "node:url";
 import { loadLibretroCore } from "./coreLoader.js";
 import { newCallbackState, registerCallbacks } from "./callbacks.js";
@@ -324,6 +324,10 @@ export class LibretroHost {
     // marks them; the single-threaded GL cores keep the main-thread GL path below.
     this._proxied = !!opts.proxied;
     this.state.proxied = this._proxied;
+    // NODERAWFS cores (flycast): the WASM FS is Node's real fs, so the core fopens the
+    // disc image straight off disk — loadMedia must pass the REAL path and NOT slurp
+    // the (up to ~1GB) file into the WASM heap. See loadMedia.
+    this._noderawfs = !!opts.noderawfs;
 
     let glCanvas = null;
     if (opts.hwRender && !this._proxied) {
@@ -348,6 +352,20 @@ export class LibretroHost {
     const mod = await loadLibretroCore({ jsPath, wasmPath, glCanvas });
     this.mod = mod;
 
+    // AUTO-DETECT NODERAWFS regardless of the caller's opt. A NODERAWFS build replaces
+    // the in-RAM MEMFS with Node's real fs, so `FS.writeFile("/rom.elf", …)` would target
+    // the REAL root path (EACCES → WASM abort). loadMedia must know this even when a
+    // caller (a test, runSource) didn't pass the flag — and the build STILL registers
+    // FS.filesystems, so that's not a tell. The reliable probe: write to a real temp path
+    // via FS and check whether it actually lands on the host disk.
+    if (!this._noderawfs && mod.FS) {
+      try {
+        const probe = path.join(os.tmpdir(), `.romdev-noderawfs-probe-${process.pid}`);
+        mod.FS.writeFile(probe, "");
+        if (existsSync(probe)) { this._noderawfs = true; try { unlinkSync(probe); } catch {} }
+      } catch { /* MEMFS: the temp path isn't real → not NODERAWFS, leave as-is */ }
+    }
+
     if (this._proxied) {
       // Spawn the app thread, then build the whole GL stack on it (native-gles + webgl-node +
       // the Emscripten GL context). 480x272 is PSP native; the readback crops per-frame.
@@ -514,16 +532,35 @@ export class LibretroHost {
       if (!args.virtualName) mediaPath = "<memory" + defaultExt + ">";
     } else if (args.path) {
       mediaPath = args.path;
-      data = await readFile(mediaPath);
       ext = path.extname(mediaPath);
+      // NODERAWFS cores (flycast) fopen the disc straight off Node's real fs — DON'T
+      // read the (up-to-~1GB) image into a JS buffer; libchdr seeks the sectors it
+      // needs on demand. `data` stays null; the real path is passed below. This ONLY
+      // applies to a real disk PATH — an in-memory `bytes` load (a freshly-built ELF in
+      // the tests/runSource) has no file to fopen, so it still mirrors into the FS below.
+      if (!this._noderawfs) data = await readFile(mediaPath);
     } else {
       throw new Error("loadMedia requires either `path` or `bytes`");
     }
+    // NODERAWFS: the WASM FS IS Node's real fs, so a `mod.FS.writeFile("/rom.elf", …)`
+    // would try to write the REAL root path `/rom.elf` (EACCES → WASM abort). For an
+    // in-memory `bytes` load on a NODERAWFS core (a freshly-built ELF in the tests /
+    // runSource), spill the bytes to a REAL temp file and load THAT path — the core
+    // fopens it off disk like any other media.
+    if (this._noderawfs && data != null) {
+      const tmpFile = path.join(mkdtempSync(path.join(os.tmpdir(), "romdev-dc-")), "rom" + (ext || ".bin"));
+      writeFileSync(tmpFile, data);
+      this._noderawfsTmp = tmpFile; // remembered so unloadMedia can clean it up
+      mediaPath = tmpFile;
+      data = null; // now streamed from the temp path, not the heap
+    }
+    // Stream-from-disk is valid for a NODERAWFS core once data is null (a real path OR
+    // the temp file we just wrote). A non-NODERAWFS core always mirrors into the FS.
+    const streamFromDisk = this._noderawfs && data == null;
     const vfsPath = "/rom" + ext;
-    // For proxied cores the core fopen's on the app thread, so the ROM goes to the app-thread
-    // MEMFS below (romdev_app_fs_write) — writing it to the main-thread FS too is wasted work
-    // (and for a 60MB ISO, a needless copy). Non-proxied cores read main's FS directly.
-    if (mod.FS && !this._proxied) {
+    // Mirror the bytes into the (in-RAM) MEMFS for normal cores. NODERAWFS skips this —
+    // it streams from the real path (mediaPath) instead.
+    if (mod.FS && !this._proxied && !streamFromDisk) {
       try {
         mod.FS.writeFile(vfsPath, data);
       } catch (e) {
@@ -531,12 +568,18 @@ export class LibretroHost {
       }
     }
 
-    // Allocate ROM data into the WASM heap (the core may keep this pointer).
-    const dataPtr = mod._malloc(data.length);
-    mod.HEAPU8.set(data, dataPtr);
+    // ROM data → WASM heap (the core may keep this pointer). When streaming off disk
+    // there's no buffer — dataPtr stays 0 and dataLen 0; the core reads from the path.
+    let dataPtr = 0;
+    const dataLen = streamFromDisk ? 0 : data.length;
+    if (!streamFromDisk) {
+      dataPtr = mod._malloc(data.length);
+      mod.HEAPU8.set(data, dataPtr);
+    }
 
-    // Allocate path string.
-    const pathStr = mod.FS ? vfsPath : mediaPath;
+    // Path string. Streaming → the REAL host path (the core fopens it). Otherwise the
+    // in-FS vfs path (or the real path if the core has no FS).
+    const pathStr = streamFromDisk ? mediaPath : (mod.FS ? vfsPath : mediaPath);
     const pathBytes = Buffer.from(pathStr + "\0", "utf-8");
     const pathPtr = mod._malloc(pathBytes.length);
     mod.HEAPU8.set(pathBytes, pathPtr);
@@ -546,14 +589,14 @@ export class LibretroHost {
     // thread, so write the ROM into the app thread's MEMFS too (the bytes are already in shared
     // WASM memory at dataPtr).
     if (this._proxied) {
-      mod._romdev_app_fs_write(pathPtr, dataPtr, data.length);
+      mod._romdev_app_fs_write(pathPtr, dataPtr, dataLen);
     }
 
     // retro_game_info struct (16 bytes on wasm32).
     const infoPtr = mod._malloc(16);
     mod.setValue(infoPtr + 0, pathPtr, "i32");
-    mod.setValue(infoPtr + 4, dataPtr, "i32");
-    mod.setValue(infoPtr + 8, data.length, "i32");
+    mod.setValue(infoPtr + 4, dataPtr, "i32");      // 0 for NODERAWFS (core reads the path)
+    mod.setValue(infoPtr + 8, dataLen, "i32");      // 0 for NODERAWFS
     mod.setValue(infoPtr + 12, 0, "i32"); // meta = null
 
     // Proxied cores: run retro_load_game on the app thread ASYNCHRONOUSLY (it creates the GL
@@ -600,7 +643,7 @@ export class LibretroHost {
       // rather than leaving the agent with "failed".
       throw new Error(
         `The '${platform}' core REFUSED this ${mediaKind || "media"} ` +
-        `(${data.length} bytes${ext ? `, ${ext}` : ""}, path ${mediaPath}). ` +
+        `(${data ? data.length + " bytes" : "streamed from disk"}${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; ` +
@@ -621,8 +664,10 @@ export class LibretroHost {
     // it does NOT clear work RAM on most cores, so boot-seeded state persists.
     // Stash the raw bytes (a copy, so a later free of the caller's buffer can't
     // corrupt it) + the load descriptor; hardReset() replays loadMedia with it.
+    // NODERAWFS streamed from disk — there's no buffer to stash; replay from the path.
     this._loadArgs = {
-      bytes: data instanceof Uint8Array ? data.slice() : new Uint8Array(data),
+      ...(data ? { bytes: data instanceof Uint8Array ? data.slice() : new Uint8Array(data) }
+               : { path: mediaPath }),
       platform,
       mediaKind,
       virtualName: args.virtualName,
@@ -660,6 +705,13 @@ export class LibretroHost {
     this.status.displayAspect = reportedAspect > 0
       ? reportedAspect
       : this.status.fbWidth / this.status.fbHeight;
+    // timing.fps is at offset +24 (double) — the core's NATIVE refresh rate. Most
+    // are ~60, but some games/cores run 50 (PAL) or ~30 (e.g. Sonic Adventure on
+    // flycast). The playtest window paces its tick to THIS, not a hardcoded 60, so a
+    // 30fps title isn't double-ticked (which wasted half the budget + glitched on the
+    // heavy interpreter-only DC core). 0/garbage → fall back to 60.
+    const reportedFps = mod.getValue(avInfoPtr + 24, "double");
+    this.status.coreFps = (reportedFps >= 1 && reportedFps <= 120) ? reportedFps : 60;
     // timing.sample_rate is at offset +32 (double).
     this.status.audioSampleRate = mod.getValue(avInfoPtr + 32, "double");
     // max_width/max_height (+8/+12) bound the FBO for HW-render cores (the core may
@@ -1785,6 +1837,27 @@ export class LibretroHost {
     }
   }
 
+  /** True when the GameTank core exposes the ACP audio-coprocessor state
+   *  (getAudioState chip:'acp'). */
+  acpStateSupported() {
+    return !!(this.mod && typeof this.mod._romdev_acp_get === "function");
+  }
+
+  /** Read the GameTank ACP state as a Uint32Array(10): [0]dacReg [1]irqRate
+   *  [2]irqCounter [3]running [4]resetting [5]muted [6]volume [7]audioPC
+   *  [8]samplesPerFrame [9]clkMult. null if the core doesn't expose it. */
+  getAcpState() {
+    const mod = this.mod;
+    if (!mod || typeof mod._romdev_acp_get !== "function") return null;
+    const ptr = mod._malloc(10 * 4);
+    try {
+      mod._romdev_acp_get(ptr);
+      return new Uint32Array(mod.HEAPU8.buffer, ptr, 10).slice();
+    } finally {
+      mod._free(ptr);
+    }
+  }
+
   /** Read the PS1 SPU's 0x400-word register block as a Uint16Array(1024). null if
    *  the core doesn't expose it. */
   getSpuRegs() {
@@ -2381,7 +2454,7 @@ export class LibretroHost {
         // $FF0000-$FFFFFF → system_ram (& 0xFFFF). Sentinel 0 (vector area).
         // 7.67MHz / ~10 cyc/instr / 60 ≈ 12.8k; use 50k (tight loops are denser).
         return { spReg: 18, pcReg: 16, retBytes: 4, retBigEndian: true, defaultSentinel: 0, ramMask: 0xFFFF, instrPerFrame: 50000 };
-      case "nes": case "atari2600": case "atari7800": case "lynx": case "c64": case "pce":
+      case "nes": case "atari2600": case "atari7800": case "lynx": case "c64": case "pce": case "gametank":
         // 6502/65C02/HuC6280/6510: A=0,X=1,Y=2,P=3,SP=4,PC=16. RTS pops 2 bytes
         // (PCL,PCH) from the $0100 page. system_ram is the low RAM; the stack page
         // $0100-$01FF maps to system_ram offset 0x100-0x1FF on most of these.

package/src/host/callbacks.js

@@ -213,15 +213,33 @@ export function registerCallbacks(args) {
   }, "v");
   mod._retro_set_input_poll(inputPollCb);
 
-  const inputStateCb = mod.addFunction((port, device, _idx, id) => {
+  const inputStateCb = mod.addFunction((port, device, idx, id) => {
     // device 3 = RETRO_DEVICE_KEYBOARD — id is the libretro keycode
     if (device === 3) {
       return state.keysDown.has(id) ? 1 : 0;
     }
-    // Default: JOYPAD (device 1) and unknown devices fall through to bitfield.
     const portBits = state.inputPorts[port];
     if (!portBits) return 0;
     const bits = portBits[0];
+    // device 5 = RETRO_DEVICE_ANALOG. Games with an analog stick (N64, and the
+    // dual-stick consoles) read this INSTEAD of the d-pad for movement — MK64
+    // steers entirely off the stick, so a d-pad-only mask leaves the kart dead.
+    // We have no real axis source (setInput is digital), so SYNTHESIZE a full-
+    // deflection stick from the d-pad bits: left/right → X = -/+32767, up/down →
+    // Y = -/+32767. idx 0 = left stick, id 0 = X, id 1 = Y (libretro convention).
+    if (device === 5) {
+      if (idx === 0) {
+        if (id === 0) { // X axis
+          if (bits & (1 << 6)) return -32767; // JOYPAD_LEFT
+          if (bits & (1 << 7)) return 32767;  // JOYPAD_RIGHT
+        } else if (id === 1) { // Y axis (up = negative)
+          if (bits & (1 << 4)) return -32767; // JOYPAD_UP
+          if (bits & (1 << 5)) return 32767;  // JOYPAD_DOWN
+        }
+      }
+      return 0;
+    }
+    // Default: JOYPAD (device 1) and unknown devices fall through to bitfield.
     if (id === 256) return bits; // RETRO_DEVICE_ID_JOYPAD_MASK
     return bits & (1 << id) ? 1 : 0;
   }, "iiiii");

package/src/host/cpu-state.js

@@ -533,6 +533,23 @@ export function getCPUState(host, platform, cpu = "main") {
         "(PC-8 in ARM, PC-4 in THUMB). Registers are decimal; cpsr/spsr/execPc are hex.",
     };
   }
+  if (platform === "gametank") {
+    // The patched GameTank core exposes the LIVE W65C02S register file via
+    // romdev_getreg (regId: 0=A 1=X 2=Y 3=P 4=SP 16=PC) — no synthesized region
+    // needed, read it directly. (At a watch/break HIT the frozen snapshot also
+    // comes through romdev_regsnap_get like every other core.)
+    const A = host.getReg(0), X = host.getReg(1), Y = host.getReg(2);
+    const P = host.getReg(3), SP = host.getReg(4), pc = host.getReg(16);
+    return {
+      pc, sp: 0x100 | (SP & 0xFF),
+      registers: { A, X, Y, P, SP },
+      cpu: "65c02",
+      flags: {
+        N: !!(P & 0x80), V: !!(P & 0x40), B: !!(P & 0x10), D: !!(P & 0x08),
+        I: !!(P & 0x04), Z: !!(P & 0x02), C: !!(P & 0x01),
+      },
+    };
+  }
   if (platform === "lynx") {
     // Patched handy exposes a 16-byte 65C02 snapshot via lynx_cpu_regs (see
     // the handy memory-regions patch). Layout: [0] PC lo, [1] PC hi, [2] A,

package/src/host/gametank-acp-state.js

@@ -0,0 +1,53 @@
+// GameTank ACP (audio coprocessor) state decoder — the "what is the sound doing
+// this frame?" view that getAudioState gives the other platforms' chips.
+//
+// GameTank has no fixed-register synth (no APU/SID); its "sound chip" is a SECOND
+// 65C02 running an audio program in 4 KB RAM that drives an 8-bit DAC at an IRQ
+// rate. So this decode reports the ACP's STATE rather than per-voice registers:
+// the live DAC output, the IRQ/sample rate, run/mute flags, volume, and which
+// audio-CPU routine is executing. Data source: the romdev_acp_get export
+// (gametank core) — a Uint32Array(10) (see LibretroHost.getAcpState for layout).
+
+/**
+ * @param {Uint32Array|null} a romdev_acp_get block (10 u32) or null
+ * @returns {object} audioDebug-shaped state
+ */
+export function decodeGameTankAcp(a) {
+  if (!a || a.length < 10) return { chip: "acp", playing: false, note: "no ACP data" };
+  const dacReg = a[0] & 0xFF;
+  const irqRate = a[1] & 0xFF;
+  const irqCounter = a[2] & 0xFFFF;
+  const running = !!a[3];
+  const resetting = !!a[4];
+  const muted = !!a[5];
+  const volume = a[6] | 0;
+  const audioPC = a[7] & 0xFFFF;
+  const samplesPerFrame = a[8] >>> 0;
+  const clkMult = a[9] & 0xFF;
+
+  // "playing" = the audio CPU is running, not muted/resetting, and the DAC isn't
+  // parked at the midpoint silence ($80) — a coarse but honest activity signal.
+  const playing = running && !muted && !resetting && dacReg !== 0x80;
+
+  return {
+    chip: "acp",
+    cpu: "65c02",                       // the audio coprocessor is a second 65C02
+    playing,
+    registers: {
+      dac: "$" + dacReg.toString(16).padStart(2, "0").toUpperCase(),
+      irqRate: "$" + irqRate.toString(16).padStart(2, "0").toUpperCase(),
+      audioPC: "$" + audioPC.toString(16).padStart(4, "0").toUpperCase(),
+      volume,
+    },
+    dacOutput: dacReg,                  // 0..255, $80 = silence midpoint
+    irqRate,                            // sets the effective sample rate
+    irqCounter,
+    samplesPerFrame,
+    clkMult,
+    running, resetting, muted,
+    note: muted ? "ACP muted"
+      : resetting ? "ACP in reset"
+      : !running ? "ACP idle (not running)"
+      : "ACP running — driving the DAC from audio RAM",
+  };
+}

package/src/http/skill-doc.js

@@ -17,9 +17,10 @@ import { toolJsonSchema } from "./tool-registry.js";
  * hands instructions to an MCP client. Talks ONLY about MCP tool-calling.
  */
 export const mcpPreamble = [
-  "romdev: homebrew retro game development + reverse-engineering for coding agents.",
+  "romdev: homebrew retro game development + reverse-engineering for coding agents — 18 platforms (NES through GBA, C64, GameTank, + the 3D consoles N64/PlayStation/Dreamcast).",
+  "HARD RULE: NEVER install a host compiler or emulator (no clang/gcc/Xcode/devkitPro/brew/apt, no downloaded emulator). romdev BUNDLES every compiler (cc65, sdcc, gcc, arm/m68k/mips/sh-gcc, tcc, wla, rgbds, vasm, asar, dasm) + every emulator core as WASM and runs them through these tools — build({output:'rom'|'run'}) compiles, loadMedia+frame runs. If you're about to install or call a host toolchain, STOP and use the romdev build tool instead; an install kicking off is a DEFECT to report.",
   "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}), …",
-  "RE engine (all 14 platforms): disasm({target:'functions'}) auto-detects functions, disasm({target:'cfg'}) graphs control flow, disasm({target:'xrefs'}) finds cross-references, disasm({target:'decompile'}) emits Ghidra C pseudocode, symbols({op:'analyze'}) maps a ROM's structure in one call.",
+  "RE engine (all 18 platforms): disasm({target:'functions'}) auto-detects functions, disasm({target:'cfg'}) graphs control flow, disasm({target:'xrefs'}) finds cross-references, disasm({target:'decompile'}) emits Ghidra C pseudocode, symbols({op:'analyze'}) maps a ROM's structure in one call.",
   "catalog({op:'categories'}) maps the tools by purpose (a guide, not a gate); catalog({op:'status'}) is a session re-orient.",
 ].join("\n");
 
@@ -27,11 +28,14 @@ export const mcpPreamble = [
  * Skill-channel preamble — talks ONLY about the HTTP routes. No MCP.
  */
 export const skillPreamble = [
-  "romdev gives you homebrew retro game development + reverse-engineering for ~14 platforms (NES, SNES, Game Boy, Genesis, GBA, Atari, C64, and more) — build, run, screenshot, inspect, patch, disassemble, convert assets, drive emulators.",
-  "It also ships a full RE analysis engine (Rizin + Ghidra, all 14 platforms): control-flow graphs, cross-references, auto-detected functions, a one-shot structural map, and a C-pseudocode decompiler — `disasm({target:'cfg'|'xrefs'|'functions'|'decompile'})` and `symbols({op:'analyze'})`.",
+  "romdev gives you homebrew retro game development + reverse-engineering for 18 platforms (NES, SNES, Game Boy, Genesis, GBA, Atari, C64, GameTank, the 3D consoles N64/PlayStation/Dreamcast, and more) — build, run, screenshot, inspect, patch, disassemble, convert assets, drive emulators.",
+  "It also ships a full RE analysis engine (Rizin + Ghidra, all 18 platforms): control-flow graphs, cross-references, auto-detected functions, a one-shot structural map, and a C-pseudocode decompiler — `disasm({target:'cfg'|'xrefs'|'functions'|'decompile'})` and `symbols({op:'analyze'})`.",
+  "",
+  "## HARD RULE: never install a compiler or emulator — romdev already bundles every one",
+  "Every compiler/assembler/linker (cc65, sdcc, gcc, arm/m68k/mips/sh-gcc, tcc, wla, rgbds, vasm, asar, dasm) and every emulator core ships as WASM INSIDE romdev and runs in-process through these tools — `build({output:'rom'|'run'})` compiles, `loadMedia`+`frame` runs. You do NOT need, and must NOT install, a host `clang`/`gcc`/Xcode/Command-Line-Tools/devkitPro/`brew`/`apt` compiler or any emulator to build or run a ROM here. If you catch yourself about to install or invoke a host compiler/emulator — STOP. That's never the move: use the romdev `build` tool. (`platform({op:'toolchains'})` lists what's bundled for each platform.) A compiler/emulator install kicking off while using romdev is a DEFECT to report, not a step to take.",
   "",
   "## Prerequisite: romdev runs LOCALLY (same machine as you)",
-  "romdev bundles every compiler + emulator as WASM and runs them in-process — that engine lives in the romdev SERVER, started once with `npx romdevtools` (listens on http://localhost:7331; no other install, no host gcc/emulator needed). If a call gets connection-refused, it isn't running — start it.",
+  "The romdev SERVER hosts all that bundled WASM in-process; start it once with `npx romdevtools` (listens on http://localhost:7331 — that single `npx` is the ONLY install, and it pulls the toolchains/cores as bundled WASM, never a host compiler). If a call gets connection-refused, the server isn't running — start it.",
   "**romdev runs on the SAME machine as you, and tools take FILESYSTEM PATHS** (`path`, `outputPath`, `modulePath`, `vgmPath`, …) — those are paths on the local disk romdev shares with you, NOT uploads. Pass an absolute local path; romdev reads/writes it directly. (This is also why it's localhost-only and needs no auth.) Likewise output paths land on the local disk where you can read them back.",
   "",
   "## How to call romdev",
@@ -58,7 +62,7 @@ export function buildSkillDoc({ registry, agentsBody, version }) {
   const frontmatter = [
     "---",
     "name: romdev",
-    "description: Homebrew retro game development and ROM reverse-engineering for ~14 platforms (NES, SNES, Game Boy/Color, Genesis, GBA, Atari 2600/7800, Lynx, C64, SMS, Game Gear, PC Engine, MSX). Use when building, running, debugging, disassembling, asset-converting, or romhacking a retro game — drives bundled emulators and toolchains over HTTP.",
+    "description: Homebrew retro game development and ROM reverse-engineering for 18 platforms (NES, SNES, Game Boy/Color, Genesis, GBA, Atari 2600/7800, Lynx, C64, SMS, Game Gear, PC Engine, MSX, GameTank, N64, PlayStation, Dreamcast). Use when building, running, debugging, disassembling, asset-converting, or romhacking a retro game — drives bundled emulators and toolchains over HTTP. NEVER install a host compiler/emulator; romdev bundles all of them as WASM (use the build tool).",
     `metadata:`,
     `  version: "${version ?? "0.0.0"}"`,
     "---",

package/src/mcp/tools/audio.js

@@ -367,7 +367,7 @@ export function registerAudioTools(server, z, sessionKey) {
     "sampled SFX fire' on Genesis is still record-and-FFT.",
     {
       op: z.enum(["inspect", "record"]).describe("inspect a sound chip's live state (single-frame, or a frames trace); or record audio to a WAV."),
-      chip: z.enum(["nes", "gb", "gba", "dsp", "psg", "ym2612", "sid", "mikey", "pce", "ay8910", "spu", "ai", "aica"]).optional().describe("op=inspect: which sound chip to decode. Tile systems: nes/gb/gba/dsp(SNES)/psg(SN76489)/ym2612(Genesis FM)/sid(C64)/mikey(Lynx)/pce/ay8910(MSX). 3D systems: spu (PS1, 24 ADPCM voices), ai (N64 AI output), aica (Dreamcast, 64 PCM/ADPCM channels)."),
+      chip: z.enum(["nes", "gb", "gba", "dsp", "psg", "ym2612", "sid", "mikey", "pce", "ay8910", "spu", "ai", "aica", "acp"]).optional().describe("op=inspect: which sound chip to decode. Tile systems: nes/gb/gba/dsp(SNES)/psg(SN76489)/ym2612(Genesis FM)/sid(C64)/mikey(Lynx)/pce/ay8910(MSX). 3D systems: spu (PS1, 24 ADPCM voices), ai (N64 AI output), aica (Dreamcast, 64 PCM/ADPCM channels)."),
       frames: z.number().int().min(1).max(60000).optional().describe("op=record: emulator frames to capture (default 180 = 3s NTSC). op=inspect: if set, TRACE the chip over N frames into a per-channel timeline; OMIT for a single-frame snapshot."),
       sampleEvery: z.number().int().min(1).default(1).describe("op=inspect trace: sample the chip only every Nth frame (thins a long trace; the last frame is always sampled). Changes on skipped frames surface at the next sampled frame, so >1 loses fine timing — keep at 1 to catch every transition."),
       path: z.string().optional().describe("op=record: absolute path to write the WAV (required for record)."),

package/src/mcp/tools/cart-parts.js

@@ -296,6 +296,44 @@ function extractAtari7800(data) {
   };
 }
 
+// GameTank .gtr — a flat, headerless cart whose mapper is keyed by SIZE
+// (8 KB EEPROM8K / 32 KB EEPROM32K / 2 MB FLASH2M). For the single-bank 32 KB
+// format the 6502 vector table (NMI/RESET/IRQ) is the last 6 bytes ($FFFA), like
+// the 7800. Split into body + vectors (32 KB) or just rom.bin (other sizes), and
+// decode the vectors. No header to strip.
+function extractGameTank(data) {
+  const n = data.length;
+  const mapper = n === 0x2000 ? "EEPROM8K"
+    : n === 0x8000 ? "EEPROM32K"
+    : n === 0x200000 ? "FLASH2M"
+    : "UNKNOWN";
+  const parts = {};
+  let vectors = null;
+  // The 32 KB single-bank format maps at $8000-$FFFF, so the CPU vector table is
+  // the last 6 bytes. (FLASH2M banks the cart — the live vectors are in bank $FF,
+  // also the last 6 bytes of the 2 MB image; EEPROM8K mirrors up into $FFFA too.)
+  if (n >= 6) {
+    parts["body.bin"] = data.slice(0, n - 6);
+    parts["vectors.bin"] = data.slice(n - 6);
+    const off = n - 6;
+    const w = (lo) => "$" + (((data[off + lo + 1] << 8) | data[off + lo]) & 0xFFFF)
+      .toString(16).toUpperCase().padStart(4, "0");
+    vectors = { nmi: w(0), reset: w(2), irq: w(4) };
+  } else {
+    parts["rom.bin"] = data.slice(0);
+  }
+  return {
+    parts,
+    manifest: {
+      platform: "gametank",
+      bytes: n,
+      mapper,                          // SIZE is the mapper — keep the byte count exact on re-wrap
+      bodyBytes: n >= 6 ? n - 6 : n,
+      vectors,
+    },
+  };
+}
+
 function extractGb(data, platform) {
   return {
     parts: {
@@ -348,6 +386,8 @@ export async function extractCartCore({ path: romPath, platform, outputDir, inli
     case "atari7800":
     case "a7800": result = extractAtari7800(data); break;
     case "c64":   result = extractC64(data); break;
+    case "gametank":
+    case "gtr":   result = extractGameTank(data); break;
     default:
       throw new Error(`extractCart: platform '${resolved}' not supported`);
   }
@@ -619,6 +659,8 @@ export async function wrapRomFromPartsCore(args) {
     case "atari7800":
     case "a7800": return wrapAtari7800(args);
     case "c64":   return wrapC64(args);
+    case "gametank":
+    case "gtr":   return wrapGameTank(args);
     default:
       throw new Error(`wrapRomFromParts: platform '${platform}' not supported`);
   }
@@ -646,6 +688,40 @@ function wrapC64({ loadAddress, bodyPath, romPath }) {
   return { wrapperSource, linkerConfig: null };
 }
 
+/**
+ * Wrap GameTank parts back into a flat .gtr. body.bin + vectors.bin (6 bytes at
+ * the end) → a size-keyed image (default 32 KB EEPROM32K). The mapper IS the
+ * size, so the wrapper PADS to exactly romSize (default $8000) with the vectors
+ * forced to the last 6 bytes. Emits a ca65 source that .incbin's the body, pads,
+ * then .incbin's the vectors at $FFFA — assemble+link with the gametank preset,
+ * or just `cat body.bin <pad> vectors.bin` to the exact size.
+ */
+function wrapGameTank({ bodyPath, vectorsPath, romPath, romSize }) {
+  if (romPath) {
+    // already-flat image — just (re)assert the size by including it verbatim.
+    const wrapperSource =
+`; GameTank .gtr wrapper — a prebuilt flat image (size = mapper).
+        .incbin "${romPath}"
+`;
+    return { wrapperSource, linkerConfig: null };
+  }
+  const size = romSize ?? 0x8000;          // default EEPROM32K
+  const body = bodyPath ?? "body.bin";
+  const vecs = vectorsPath ?? "vectors.bin";
+  // ca65: body at the start of the ROM segment, the 6-byte vector table pinned to
+  // $FFFA. The gametank single-bank linker cfg (or a flat cat) places these so the
+  // final image is exactly `size` bytes with the vectors last.
+  const wrapperSource =
+`; GameTank .gtr wrapper (size-keyed mapper; default EEPROM32K = $${size.toString(16).toUpperCase()} bytes).
+; body.bin = code/data ($8000..), vectors.bin = the 6-byte NMI/RESET/IRQ table at $FFFA.
+.segment "STARTUP"
+        .incbin "${body}"
+.segment "VECTORS"
+        .incbin "${vecs}"
+`;
+  return { wrapperSource, linkerConfig: "single-bank", romSize: size };
+}
+
 // ─── MCP registration ─────────────────────────────────────────────
 
 export function registerCartPartsTools(server, z) {

package/src/mcp/tools/lifecycle.js

@@ -21,7 +21,7 @@ export function registerLifecycleTools(server, z, sessionKey) {
     if (path && base64) throw new Error("loadMedia: provide `path` OR `base64`, not both.");
     const slotB = slot === "b";
     const host = slotB ? resetHostB(sessionKey) : resetHost(sessionKey);
-    await host.loadCore(resolved.jsPath, resolved.wasmPath, { hwRender: resolved.hwRender });
+    await host.loadCore(resolved.jsPath, resolved.wasmPath, { hwRender: resolved.hwRender, noderawfs: resolved.noderawfs });
     const bytes = base64 ? new Uint8Array(Buffer.from(base64, "base64")) : undefined;
     await host.loadMedia({
       platform,

package/src/mcp/tools/platform-tools.js

@@ -42,6 +42,7 @@ import { decodeLynxMikey, decodeLynxPalette } from "../../host/lynx-mikey-state.
 import { getPcePsgState } from "../../host/pce-psg-state.js";
 import { decodePs1Spu } from "../../host/ps1-spu-state.js";
 import { decodeN64Ai } from "../../host/n64-ai-state.js";
+import { decodeGameTankAcp } from "../../host/gametank-acp-state.js";
 import { decodeAica } from "../../host/dc-aica-state.js";
 import { getMsxAyState } from "../../host/msx-ay-state.js";
 import { decodeGbaSprites, decodeGbaPalette } from "../../host/gba-video-state.js";
@@ -448,7 +449,14 @@ export function registerPlatformTools(server, z, sessionKey) {
       if (!regs) throw new Error("getAudioState chip:'aica' — no AICA region (load a Dreamcast program into the rebuilt flycast core).");
       return { platform: "dreamcast", ...decodeAica(regs) };
     }
-    throw new Error(`getAudioState: unknown chip '${chip}'. Use 'nes' (NES 2A03), 'gb' (Game Boy/GBC), 'gba' (GBA), 'dsp' (SNES), 'psg' (Genesis/SMS/GG SN76489), 'ym2612' (Genesis FM), 'sid' (C64), 'mikey' (Lynx), 'pce', 'ay8910' (MSX), 'spu' (PS1), or 'aica' (Dreamcast).`);
+    if (chip === "acp") {
+      // GameTank ACP — a second 65C02 driving a DAC from 4 KB audio RAM (no fixed
+      // synth registers), from the patched core's romdev_acp_get state block.
+      const regs = host.getAcpState?.();
+      if (!regs) throw new Error("getAudioState chip:'acp' — no ACP state (load a GameTank ROM into the patched gametank core).");
+      return { platform: "gametank", ...decodeGameTankAcp(regs) };
+    }
+    throw new Error(`getAudioState: unknown chip '${chip}'. Use 'nes' (NES 2A03), 'gb' (Game Boy/GBC), 'gba' (GBA), 'dsp' (SNES), 'psg' (Genesis/SMS/GG SN76489), 'ym2612' (Genesis FM), 'sid' (C64), 'mikey' (Lynx), 'pce', 'ay8910' (MSX), 'spu' (PS1), 'aica' (Dreamcast), or 'acp' (GameTank).`);
   }
 
   getAudioStateCore = async ({ chip }, callerSessionKey) => jsonContent(readAudioChip(chip, callerSessionKey));

package/src/mcp/tools/platforms.js

@@ -93,9 +93,17 @@ const PLATFORM_QUIRKS = {
 };
 
 /** op:'list' — every platform with core/toolchains/languages/quirks. */
-export function listPlatformsCore() {
+export function listPlatformsCore({ platform, slim } = {}) {
       const available = new Set(listAvailableCores());
-      const platforms = Object.entries(CORES).map(([id, info]) => {
+      let ids = Object.keys(CORES);
+      if (platform) {
+        if (!CORES[platform]) {
+          throw new Error(`platform({op:'list'}): unknown platform '${platform}'. Known: ${ids.join(", ")}.`);
+        }
+        ids = [platform]; // per-platform filter — the big token-sink fix (v0.71.0 fb)
+      }
+      const platforms = ids.map((id) => {
+        const info = CORES[id];
         const toolchains = Object.values(TOOLCHAINS)
           .filter((t) => t.platforms.includes(id))
           .map((t) => ({ id: t.id, displayName: t.displayName, tier: t.tier }));
@@ -107,18 +115,45 @@ export function listPlatformsCore() {
           toolchains,
         };
         const langs = getLanguageOptions(id);
-        if (langs) entry.languages = langs;
-        if (PLATFORM_QUIRKS[id]) entry.quirks = PLATFORM_QUIRKS[id];
+        if (langs) {
+          // `slim` drops the heavy per-language `note` + `quirks` prose (the big
+          // token sink when you only need "which platforms/toolchains/languages
+          // exist"). Detail stays behind platform({op:'doc'}) + op:'capabilities'.
+          entry.languages = slim
+            ? { defaultLanguage: langs.defaultLanguage,
+                languages: (langs.languages || []).map((l) => ({ language: l.language, toolchain: l.toolchain, available: l.available })) }
+            : langs;
+        }
+        if (!slim && PLATFORM_QUIRKS[id]) entry.quirks = PLATFORM_QUIRKS[id];
         return entry;
       });
-      return { platforms };
+      // A single-platform query returns just that row (not wrapped in `platforms[]`).
+      return platform ? platforms[0] : { platforms };
 }
 
-/** op:'resolve' — resolved core paths for a platform (debugging aid). */
+/** op:'resolve' — resolved core paths + the toolchain summary for a platform. */
 export function resolvePlatformCore({ platform }) {
       const r = resolveCore(platform);
       if (!r) throw new Error(`no core available for platform '${platform}'`);
-      return r;
+      // Also surface the toolchain(s) — resolve used to report only the emulator
+      // core, so agents had to spelunk node_modules to learn the build path (v0.71.0
+      // fb #3). We do NOT hand out the WASM/.mjs artifact paths: those tools run ONLY
+      // inside romdev's `build` worker harness (virtual FS), so a node_modules path
+      // invites the wrong mental model (shimming them into an external Makefile —
+      // which does NOT work). The `note` states that plainly (fb #4/#5).
+      const toolchains = Object.values(TOOLCHAINS)
+        .filter((t) => t.platforms.includes(platform))
+        .map((t) => ({ id: t.id, displayName: t.displayName, tier: t.tier }));
+      return {
+        ...r,
+        toolchains,
+        toolchainNote:
+          "Build via the `build` tool (it compiles a source set into one ROM). The toolchain " +
+          "binaries are WASM, run ONLY inside romdev's build worker (virtual FS) — they are NOT " +
+          "host-callable and CANNOT back an external project's Makefile. For an existing decomp/" +
+          "romhack that needs its own legacy compiler (e.g. agbcc) + Makefile, build it on the host " +
+          "and use romdev to run/inspect/debug the resulting ROM.",
+      };
 }
 
 export function registerPlatformTools(server, z) {
@@ -142,14 +177,15 @@ export function registerPlatformTools(server, z) {
     "troubleshooting / upstream_sources; `platform:'romhacking'` + `name:'playbook'` for the RE decision tree). " +
     "Read MENTAL_MODEL before writing code, and the romhacking playbook before a hack.",
     {
-      op: z.enum(["list", "capabilities", "resolve", "toolchains", "docs", "doc"]).describe("list=platforms; capabilities=per-platform op support matrix; resolve=core paths; toolchains; docs=a platform's doc names; doc=read one doc."),
-      platform: z.string().optional().describe("op=resolve/docs/doc: platform id (e.g. nes, gb, genesis; 'romhacking' for the RE playbook)."),
+      op: z.enum(["list", "capabilities", "resolve", "toolchains", "docs", "doc"]).describe("list=platforms (pass `platform` to get just ONE, `slim:true` to drop the verbose notes); capabilities=per-platform op support matrix; resolve=core + toolchain artifact paths; toolchains; docs=a platform's doc names; doc=read one doc."),
+      platform: z.string().optional().describe("op=list/resolve/docs/doc/capabilities: platform id (e.g. nes, gb, genesis; 'romhacking' for the RE playbook). On op=list it filters to that ONE platform's row instead of the whole matrix (big token saver)."),
+      slim: z.boolean().optional().describe("op=list: drop the heavy per-language `note` + `quirks` prose; return just {platform, toolchains[], languages{defaultLanguage,…}}. Detail stays behind op:'doc' / op:'capabilities'."),
       id: z.string().optional().describe("op=toolchains: a specific toolchain's install status (e.g. 'cc65')."),
       name: z.string().optional().describe("op=doc: which doc — mental_model | troubleshooting | upstream_sources | playbook."),
     },
     safeTool(async (args) => {
       switch (args.op) {
-        case "list":    return jsonContent(listPlatformsCore());
+        case "list":    return jsonContent(listPlatformsCore({ platform: args.platform, slim: args.slim }));
         case "capabilities": {
           if (args.platform) {
             const cap = capabilitiesFor(args.platform);