romdevtools 0.13.0

package/src/mcp/tools/state.js

@@ -0,0 +1,198 @@
+import { mkdir, writeFile, readFile } from "node:fs/promises";
+import path from "node:path";
+import { getHost } from "../state.js";
+import { jsonContent, safeTool } from "../util.js";
+
+// Per-session state-diff baselines (op:'diff'). Module-local; keyed by sessionKey.
+const _stateDiffSnaps = new Map();
+function stateDiffSnapshots(key) {
+  let m = _stateDiffSnaps.get(key);
+  if (!m) { m = new Map(); _stateDiffSnaps.set(key, m); }
+  return m;
+}
+
+// ── *Core functions: one per state operation. The `state` tool routes to them. ──
+
+/** op:'save' — snapshot to an in-memory slot and/or a disk blob. */
+async function saveStateCore({ name, path: outPath }, sessionKey) {
+      if (!name && !outPath) throw new Error("state({op:'save'}): provide `name` (in-memory slot), `path` (disk), or both.");
+      const host = getHost(sessionKey);
+      const done = [];
+      if (name) { host.saveState(name); done.push(`slot '${name}'`); }
+      if (outPath) {
+        const blob = host.serializeState();
+        await mkdir(path.dirname(outPath), { recursive: true });
+        await writeFile(outPath, blob);
+        done.push(`${blob.length} bytes → ${outPath}`);
+      }
+      return {
+        saved: true,
+        ...(name ? { name } : {}),
+        ...(outPath ? { path: outPath } : {}),
+        platform: host.status.platform,
+        note: `Saved ${done.join(" + ")}.` + (outPath ? " Restore across sessions with state({op:'load', path}) after loading the same ROM." : ""),
+      };
+}
+
+/** op:'export' — copy an EXISTING in-memory slot to disk without touching the host. */
+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);
+      return {
+        exported: true,
+        fromSlot,
+        path: outPath,
+        bytes: blob.length,
+        platform: host.status.platform,
+        note: "Copied the slot to disk; the live host was not touched (no pause/resume needed).",
+      };
+}
+
+/** op:'load' — restore from an in-memory slot OR a disk blob. */
+async function loadStateCore({ name, path: inPath, render = true }, sessionKey) {
+      if (!name && !inPath) throw new Error("state({op:'load'}): provide `name` (in-memory slot) or `path` (disk).");
+      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));
+        cheatsCleared = host.unserializeState(blob) || 0;
+      } else {
+        cheatsCleared = host.loadState(name) || 0;
+      }
+      let rendered = false;
+      if (render) { host.renderOneFrame(); rendered = true; }
+      return {
+        loaded: true,
+        ...(inPath ? { path: inPath } : { name }),
+        platform: host.status.platform,
+        rendered,
+        ...(host.status.paused && rendered ? { renderedWhilePaused: true } : {}),
+        cheatsCleared, // a restore removes active cheats (frontend cheat state isn't in the blob)
+      };
+}
+
+/** op:'list' — named in-memory slots. */
+function listStatesCore(_args, sessionKey) {
+  return { states: getHost(sessionKey).listStates() };
+}
+
+/** 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);
+      const blob = host.serializeState();
+      await mkdir(path.dirname(outPath), { recursive: true });
+      await writeFile(outPath, blob);
+      const result = {
+        path: outPath,
+        bytes: blob.length,
+        platform: host.status.platform,
+        note: "Raw libretro save-state blob. Use `xxd`, `hexdump -C`, or re-call with findHex to inspect. The blob's structure is core-specific — typically a header followed by concatenated subsystem dumps (CPU regs, RAM, VRAM, etc.).",
+      };
+      if (findHex) {
+        const cleaned = findHex.replace(/[\s_]/g, "");
+        if (!/^[0-9a-fA-F]+$/.test(cleaned) || cleaned.length % 2 !== 0) {
+          throw new Error(`findHex must be an even-length hex string, got '${findHex}'`);
+        }
+        const needle = Buffer.from(cleaned, "hex");
+        const offsets = [];
+        let from = 0;
+        while (offsets.length < maxMatches) {
+          const i = Buffer.from(blob.buffer, blob.byteOffset, blob.byteLength).indexOf(needle, from);
+          if (i < 0) break;
+          offsets.push(i);
+          from = i + 1;
+        }
+        result.findHex = cleaned;
+        result.matches = offsets.length;
+        result.offsets = offsets;
+        result.offsetsHex = offsets.map((o) => "0x" + o.toString(16));
+        result.truncated = offsets.length === maxMatches;
+      }
+      return result;
+}
+
+/** op:'diff' — whole-machine save-state diff (snapOrDiff:'snapshot'|'diff'). */
+function diffStateCore({ name = "default", snapOrDiff }, sessionKey) {
+      const host = getHost(sessionKey);
+      const store = stateDiffSnapshots(sessionKey);
+      if (snapOrDiff === "snapshot") {
+        const blob = host.serializeState();
+        store.set(name, Uint8Array.from(blob));
+        return { name, mode: "snapshot", size: blob.length, note: "State baseline captured — trigger your event, then state({op:'diff', name, snapOrDiff:'diff'})." };
+      }
+      const base = store.get(name);
+      if (!base) throw new Error(`state({op:'diff'}): no state snapshot named '${name}'. Call with snapOrDiff:'snapshot' first.`);
+      const now = host.serializeState();
+      let differingBytes = 0;
+      const len = Math.min(base.length, now.length);
+      for (let i = 0; i < len; i++) if (base[i] !== now[i]) differingBytes++;
+      const sizeChanged = base.length !== now.length;
+      return {
+        name, mode: "diff",
+        changed: differingBytes > 0 || sizeChanged,
+        differingBytes,
+        sizeChanged,
+        baselineSize: base.length,
+        currentSize: now.length,
+        note: "State blobs are core-internal — for the actual changed RAM addresses use memory({op:'snapshot'/'diff'}).",
+      };
+}
+
+export function registerStateTools(server, z, sessionKey) {
+  server.tool(
+    "state",
+    "Save-state lifecycle for the emulator. `op`: 'save' | 'load' | 'list' | 'export' | 'dump' | 'diff'.\n" +
+    "'save': `name` = fast in-memory slot (LOST on server restart / new session), `path` = disk blob that SURVIVES " +
+    "across sessions — reload via op:'load'. Multi-session RE: save once at the state you care about, reload it " +
+    "every session instead of re-running loadMedia + hundreds of stepFrames.\n" +
+    "'load': restore from a `name` slot OR a `path` blob. A state captures RAM/CPU/PPU/APU — NOT the ROM — so it's " +
+    "ROM-CONTENT-INDEPENDENT: a state saved on the stock ROM reloads into a rebuilt/patched ROM of the same core → " +
+    "clean A/B patch test. KNOW: (1) `render:true` (default) steps one frame so the next screenshot isn't stale/" +
+    "blank (works even while PAUSED); set false to stay at the exact restored instant. (2) `frameCount` is NOT " +
+    "rewound — it keeps counting. (3) a restore REMOVES active cheats (`cheatsCleared:N`).\n" +
+    "'export': copy an EXISTING slot's bytes to disk WITHOUT touching the host (persist a playtest-hotkey save; no " +
+    "pause/resume). 'dump': raw libretro blob to disk for forensic inspection — the blob often contains internal " +
+    "memory the region API doesn't expose (SPC700 ARAM, Z80 RAM); `findHex` greps it for a sentinel you wrote. " +
+    "'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)."),
+      // 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
+      fromSlot: z.string().min(1).optional().describe("op=export: in-memory slot to copy to disk (required)."),
+      // dump
+      findHex: z.string().optional().describe("op=dump: even-length hex byte-pattern to grep the blob for (ws/underscores ok, no 0x prefix) — returns every offset. Locate sentinel bytes you wrote."),
+      maxMatches: z.number().int().min(1).max(1000).default(32).describe("op=dump: cap on returned offsets when findHex is set."),
+      // diff
+      snapOrDiff: z.enum(["snapshot", "diff"]).optional().describe("op=diff: 'snapshot' captures the current state as baseline; 'diff' compares to it."),
+    },
+    safeTool(async (args) => {
+      switch (args.op) {
+        case "save":   return jsonContent(await saveStateCore(args, sessionKey));
+        case "load":   return jsonContent(await loadStateCore(args, sessionKey));
+        case "list":   return jsonContent(listStatesCore(args, sessionKey));
+        case "export": {
+          if (!args.fromSlot) throw new Error("state({op:'export'}): `fromSlot` is required.");
+          if (!args.path) throw new Error("state({op:'export'}): `path` is required.");
+          return jsonContent(await exportStateCore(args, sessionKey));
+        }
+        case "dump": {
+          if (!args.path) throw new Error("state({op:'dump'}): `path` is required.");
+          return jsonContent(await dumpStateCore(args, sessionKey));
+        }
+        case "diff": {
+          if (!args.snapOrDiff) throw new Error("state({op:'diff'}): `snapOrDiff` ('snapshot' or 'diff') is required.");
+          return jsonContent(diffStateCore(args, sessionKey));
+        }
+        default: throw new Error(`state: unknown op '${args.op}'`);
+      }
+    }),
+  );
+}
+

package/src/mcp/tools/symbols.js

@@ -0,0 +1,400 @@
+// MCP tools for cc65 .dbg-based source-aware lookups.
+//
+// The agent supplies the .dbg text it got back from buildSource({debug:true});
+// we parse and answer name → address / address → name queries.
+//
+// Stateless intentionally — each call parses the .dbg fresh. cc65 .dbg files
+// for typical homebrew sizes are <500KB and parse in tens of ms; not worth
+// caching for v1.
+
+import { writeFileSync } from "node:fs";
+import { jsonContent, safeTool, writeOutput } from "../util.js";
+import { addressToSymbolCore } from "./address-to-symbol.js";
+
+// Tail length kept inline when a big log is written to a sibling file.
+const LOG_TAIL = 1200;
+/** Log field. Inline → full log. Not inline + small → keep inline (cheap).
+ *  Not inline + large + we have a sibling path → write it, return tail+path. */
+function logField(log, inline, siblingPath) {
+  if (!log) return { log: null };
+  if (inline || log.length <= LOG_TAIL) return { log };
+  if (siblingPath) {
+    writeFileSync(siblingPath, log, "utf8");
+    return { logPath: siblingPath, logTail: log.slice(-LOG_TAIL), logBytes: log.length };
+  }
+  // No place to write (shouldn't happen — handler requires a path when not inline).
+  return { logTail: log.slice(-LOG_TAIL), logBytes: log.length };
+}
+
+/** Derive sibling output paths (debug file, log) from the ROM outputPath. */
+function siblings(romPath) {
+  const base = romPath.replace(/\.[^./]+$/, "");
+  return { dbg: `${base}.dbg`, map: `${base}.map`, log: `${base}.build.log` };
+}
+
+// build({output:'romWithDebug'}) — the cc65 .dbg / sdld .map / m68k ELF-map
+// build. Exported core; the `build` router (toolchain.js) calls it.
+export async function buildSourceWithDebugCore({ platform, source, sources, includes, linkerConfig, crt0, codeLoc, outputPath, inline = false }) {
+      const CC65_TARGETS = ["nes", "c64", "atari7800", "lynx"];
+      const SDCC_TARGETS = ["gb", "gbc", "sms", "gg"];
+      const M68K_TARGETS = ["genesis"];
+      if (!inline && !outputPath) {
+        throw new Error("buildSourceWithDebug: pass outputPath (where to save the ROM; .dbg/.map/log land alongside it) or inline:true to get everything in the response.");
+      }
+      const sib = outputPath ? siblings(outputPath) : null;
+
+      if (CC65_TARGETS.includes(platform)) {
+        const { buildC, buildAsm } = await import("../../toolchains/cc65/cc65.js");
+        // Choose builder: if any source filename ends in .c/.h, use buildC; else buildAsm.
+        // For single-source we fall back to the content heuristic.
+        let useC;
+        if (sources) {
+          useC = Object.keys(sources).some((n) => /\.(c|h)$/i.test(n));
+        } else {
+          const looksLikeAsm = /^\s*\.(segment|proc|byte|word|repeat|res|setcpu|export|import|zeropage|code|macro|include)\b/m.test(source);
+          useC = !looksLikeAsm && /\b(int|void|return|#include|main\s*\()/.test(source);
+        }
+        const builder = useC ? buildC : buildAsm;
+        const r = await builder({
+          source,
+          sources,
+          target: platform,
+          [useC ? "headers" : "includes"]: includes,
+          linkerConfig,
+          debug: true,
+        });
+        const out = {
+          ok: r.exitCode === 0 && r.binary !== null,
+          toolchain: useC ? "cc65" : "ca65+ld65",
+          exitCode: r.exitCode,
+          binaryBytes: r.binary ? r.binary.length : 0,
+          ...logField(r.log, inline, sib?.log),
+        };
+        if (r.binary) {
+          if (inline) out.binaryBase64 = Buffer.from(r.binary).toString("base64");
+          else out.binaryPath = writeOutput(r.binary, { outputPath, what: "ROM" }).path;
+        }
+        if (r.dbg) {
+          if (inline) out.dbg = r.dbg;
+          else out.dbgPath = writeOutput(r.dbg, { outputPath: sib.dbg, what: ".dbg" }).path;
+        }
+        return jsonContent(out);
+      }
+
+      if (SDCC_TARGETS.includes(platform)) {
+        // Route through buildForPlatform so we get the existing SDCC pipeline
+        // (lint, crt0, codeLoc defaults, ROM padding) for free. The result
+        // shape includes `symbols` which is the sdld .map text.
+        const { buildForPlatform } = await import("../../toolchains/index.js");
+        const r = await buildForPlatform({
+          platform,
+          language: "c",
+          source,
+          sources,
+          includes,
+          crt0,
+          codeLoc,
+        });
+        const out = {
+          ok: r.ok,
+          toolchain: r.toolchain || "sdcc",
+          exitCode: r.exitCode,
+          stage: r.stage,
+          binaryBytes: r.binary ? r.binary.length : 0,
+          issues: r.issues,
+          ...logField(r.log, inline, sib?.log),
+          // sdld .map format: lines like `AAAAAAAA  _symbol_name  _source_unit`.
+          // Regex /^\s*([0-9A-F]+)\s+(_\S+)/ extracts hex address + symbol.
+          // C functions/globals carry a leading underscore; asm symbols don't.
+          mapHint: "sdld .map: lines like `AAAAAAAA  _symbol_name  _source_unit`. Regex /^\\s*([0-9A-F]+)\\s+(_\\S+)/ extracts address + symbol; C symbols carry a leading underscore.",
+        };
+        if (r.binary) {
+          if (inline) out.binaryBase64 = Buffer.from(r.binary).toString("base64");
+          else out.binaryPath = writeOutput(r.binary, { outputPath, what: "ROM" }).path;
+        }
+        if (r.symbols) {
+          if (inline) out.mapText = r.symbols;
+          else out.mapPath = writeOutput(r.symbols, { outputPath: sib.map, what: ".map" }).path;
+        }
+        return jsonContent(out);
+      }
+
+      if (M68K_TARGETS.includes(platform)) {
+        // Genesis (m68k-elf gcc/ld). The linker now emits a GNU ld map
+        // (symbol → final address) which buildForPlatform surfaces as
+        // `symbols`. That's how you find where a RAM variable like `well`
+        // landed, then writeMemory to it.
+        const { buildForPlatform } = await import("../../toolchains/index.js");
+        const r = await buildForPlatform({ platform, language: "c", source, sources, includes });
+        const out = {
+          ok: r.ok,
+          toolchain: r.toolchain || "m68k-elf-gcc",
+          exitCode: r.exitCode,
+          stage: r.stage,
+          binaryBytes: r.binary ? r.binary.length : 0,
+          issues: r.issues,
+          ...logField(r.log, inline, sib?.log, r.ok),
+          mapHint:
+            "GNU ld .map: find your symbol in the 'Linker script and memory map' section — lines " +
+            "like `0xe0ff0048                well`. SGDK links 68k work-RAM through its mirror at " +
+            "0xE0FF0000 (hardware mirrors $FF0000 across the high bus). The work-RAM region is " +
+            "exposed as `system_ram` (64KB); the OFFSET into it is the low 16 bits of the symbol " +
+            "address — e.g. 0xE0FF0048 → writeMemory({region:'system_ram', offset:0x0048, ...}). " +
+            "C symbols have NO leading underscore in the m68k ELF (unlike SDCC's .map).",
+        };
+        if (r.binary) {
+          if (inline) out.binaryBase64 = Buffer.from(r.binary).toString("base64");
+          else out.binaryPath = writeOutput(r.binary, { outputPath, what: "ROM" }).path;
+        }
+        if (r.symbols) {
+          if (inline) out.mapText = r.symbols;
+          else out.mapPath = writeOutput(r.symbols, { outputPath: sib.map, what: ".map" }).path;
+        } else {
+          out.mapNote = "No linker map produced (link likely failed — check exitCode/log).";
+        }
+        return jsonContent(out);
+      }
+
+      throw new Error(
+        `build({output:'romWithDebug'}) supports cc65 targets (${CC65_TARGETS.join(", ")}), ` +
+        `SDCC targets (${SDCC_TARGETS.join(", ")}), and m68k targets (${M68K_TARGETS.join(", ")}); got '${platform}'`
+      );
+}
+
+export function registerSymbolTools(server, z) {
+  // buildSourceWithDebug is now build({output:'romWithDebug'}) — registered by
+  // the `build` router in toolchain.js (imports buildSourceWithDebugCore).
+  registerSymbolsTool(server, z);
+}
+
+// ── *Core functions for the `symbols` tool ──
+
+/**
+ * Load a normalized symbol list from whichever debug format the caller passed:
+ * cc65 `.dbg`, SDCC sdld `.map`, OR GNU ld `.map` (Genesis/m68k). Auto-detects
+ * the map flavor. Returns `{ name, addr, kind, ramOffset? }[]`. This is what
+ * gave Genesis/m68k C globals a name→address path (was cc65-only before).
+ */
+async function loadSymbolList({ dbg, map }) {
+  if (dbg) {
+    const { parseDbg, DbgIndex } = await import("../../toolchains/cc65/dbgparse.js");
+    const idx = new DbgIndex(parseDbg(dbg));
+    return { format: "cc65-dbg", symbols: idx.listSymbols() }; // {name, addr, kind}
+  }
+  if (map) {
+    const { isGnuLdMap, parseGnuLdMap } = await import("../../toolchains/gnu-ld-map.js");
+    if (isGnuLdMap(map)) {
+      // Genesis / m68k-elf. C symbols have NO leading underscore here.
+      const syms = parseGnuLdMap(map).map((s) => ({
+        name: s.name, addr: s.address, kind: "symbol", ramOffset: s.ramOffset,
+      }));
+      return { format: "gnu-ld-map", symbols: syms };
+    }
+    const { parseSdldMap } = await import("../../toolchains/sdcc/sdcc.js");
+    const syms = parseSdldMap(map).map((s) => ({
+      name: s.name.replace(/^_/, ""), addr: s.address, kind: "symbol", file: s.file,
+    }));
+    return { format: "sdld-map", symbols: syms };
+  }
+  throw new Error(
+    "symbols: pass `dbg` (cc65 .dbg — NES/C64/Atari7800/Lynx/PCE) or `map` " +
+    "(sdld .map for GB/GBC/SMS/GG/MSX, OR GNU ld .map for Genesis). " +
+    "build({output:'romWithDebug'}) returns the right one for your platform."
+  );
+}
+
+/** Format an address as `$XXXX` hex (pad to at least 4 digits). */
+function hexAddr(a) {
+  const w = a > 0xffff ? 8 : 4;
+  return "$" + a.toString(16).toUpperCase().padStart(w, "0");
+}
+
+/** Annotate a Genesis work-RAM-mirror symbol with the system_ram read offset. */
+function ramReadHint(sym) {
+  if (sym.ramOffset == null) return {};
+  return {
+    ramOffset: sym.ramOffset,
+    readHint: `Genesis work-RAM mirror — read it with memory({op:'read', region:'system_ram', offset:0x${sym.ramOffset.toString(16)}}) (the low 16 bits of the address).`,
+  };
+}
+
+/** op:'resolve' — symbol name → address. cc65 .dbg, sdld .map, OR GNU ld .map (Genesis). */
+export async function resolveSymbolCore({ dbg, map, name }) {
+      // cc65 .dbg keeps its bespoke index (it understands the '_name' C alias).
+      if (dbg && !map) {
+        const { parseDbg, DbgIndex } = await import("../../toolchains/cc65/dbgparse.js");
+        const idx = new DbgIndex(parseDbg(dbg));
+        let addr = idx.addressOf(name);
+        let resolvedName = name;
+        if (addr === null && !name.startsWith("_")) {
+          const a2 = idx.addressOf("_" + name);
+          if (a2 !== null) { addr = a2; resolvedName = "_" + name; }
+        }
+        if (addr === null) throw new Error(`no symbol named '${name}' in this .dbg`);
+        return {
+          name: resolvedName, address: addr, hex: hexAddr(addr),
+          ...(resolvedName !== name ? { note: `Resolved as cc65 C symbol '${resolvedName}' (you asked for '${name}').` } : {}),
+        };
+      }
+      // sdld / GNU ld map path.
+      const { format, symbols } = await loadSymbolList({ dbg, map });
+      let hit = symbols.find((s) => s.name === name);
+      // SDCC strips the leading underscore on load; a caller passing '_score' still matches.
+      if (!hit && name.startsWith("_")) hit = symbols.find((s) => s.name === name.slice(1));
+      if (!hit) throw new Error(`no symbol named '${name}' in this ${format}.`);
+      return { name: hit.name, address: hit.addr, hex: hexAddr(hit.addr), format, ...ramReadHint(hit) };
+}
+
+/** op:'lookup' — address → the symbol whose value is closest at-or-below it. cc65 .dbg, sdld/GNU .map. */
+export async function lookupAddressCore({ dbg, map, address }) {
+      if (dbg && !map) {
+        const { parseDbg, DbgIndex } = await import("../../toolchains/cc65/dbgparse.js");
+        const idx = new DbgIndex(parseDbg(dbg));
+        const sym = idx.symbolAt(address);
+        if (!sym) throw new Error(`no symbol at-or-below address ${address}`);
+        return {
+          address, hex: hexAddr(address),
+          symbol: sym.name, symbolAddress: sym.addr, offset: address - sym.addr,
+        };
+      }
+      const { format, symbols } = await loadSymbolList({ dbg, map });
+      // Nearest symbol at-or-below `address`.
+      let best = null;
+      for (const s of symbols) {
+        if (s.addr <= address && (!best || s.addr > best.addr)) best = s;
+      }
+      if (!best) throw new Error(`no symbol at-or-below address ${address} in this ${format}.`);
+      return {
+        address, hex: hexAddr(address), format,
+        symbol: best.name, symbolAddress: best.addr, offset: address - best.addr,
+      };
+}
+
+/** op:'map' — categorized layout of where the linker placed code+vars (cc65 .dbg OR sdld .map). */
+export async function getMemoryMapCore({ dbg, map, platform }) {
+      // Per-platform region boundaries (CPU memory map). cc65 6502 targets +
+      // the Z80 family (SDCC) — both keyed the same way.
+      const regionsByPlatform = {
+        nes:       [{name:"zeropage",lo:0,hi:0xff},{name:"stack",lo:0x100,hi:0x1ff},{name:"system_ram",lo:0x200,hi:0x7ff},{name:"ppu_regs",lo:0x2000,hi:0x2007},{name:"apu_input",lo:0x4000,hi:0x401f},{name:"sram",lo:0x6000,hi:0x7fff},{name:"prg_rom",lo:0x8000,hi:0xffff}],
+        c64:       [{name:"zeropage",lo:0,hi:0xff},{name:"stack",lo:0x100,hi:0x1ff},{name:"system_ram",lo:0x200,hi:0x9fff},{name:"basic_rom",lo:0xa000,hi:0xbfff},{name:"io",lo:0xd000,hi:0xdfff},{name:"kernal",lo:0xe000,hi:0xffff}],
+        atari7800: [{name:"zeropage",lo:0,hi:0xff},{name:"stack",lo:0x100,hi:0x1ff},{name:"system_ram",lo:0x1800,hi:0x27ff},{name:"cart_rom",lo:0x4000,hi:0xffff}],
+        lynx:      [{name:"zeropage",lo:0,hi:0xff},{name:"stack",lo:0x100,hi:0x1ff},{name:"system_ram",lo:0x200,hi:0xfbff},{name:"hw_regs",lo:0xfc00,hi:0xffff}],
+        // PC Engine (cc65 pce target): ZP + 8KB work RAM at $2200 (the pce.cfg
+        // MAIN segment), HuCard ROM mapped high. The HuC6280 stack lives in the
+        // $21xx page via the MPR mapping.
+        pce:       [{name:"zeropage",lo:0,hi:0xff},{name:"stack",lo:0x2100,hi:0x21ff},{name:"system_ram",lo:0x2200,hi:0x3fff},{name:"hucard_rom",lo:0xe000,hi:0xffff}],
+        // Z80 family (SDCC + sdld .map). Cartridge ROM in the low half, work RAM high.
+        gb:        [{name:"rom",lo:0,hi:0x7fff},{name:"vram",lo:0x8000,hi:0x9fff},{name:"cart_ram",lo:0xa000,hi:0xbfff},{name:"work_ram",lo:0xc000,hi:0xdfff},{name:"oam",lo:0xfe00,hi:0xfe9f},{name:"io_hram",lo:0xff00,hi:0xffff}],
+        gbc:       [{name:"rom",lo:0,hi:0x7fff},{name:"vram",lo:0x8000,hi:0x9fff},{name:"cart_ram",lo:0xa000,hi:0xbfff},{name:"work_ram",lo:0xc000,hi:0xdfff},{name:"oam",lo:0xfe00,hi:0xfe9f},{name:"io_hram",lo:0xff00,hi:0xffff}],
+        sms:       [{name:"rom",lo:0,hi:0xbfff},{name:"work_ram",lo:0xc000,hi:0xdfff},{name:"ram_mirror",lo:0xe000,hi:0xffff}],
+        gg:        [{name:"rom",lo:0,hi:0xbfff},{name:"work_ram",lo:0xc000,hi:0xdfff},{name:"ram_mirror",lo:0xe000,hi:0xffff}],
+        // MSX cartridge: BIOS low, cart at $4000-$BFFF, work RAM $C000-$FFFF.
+        msx:       [{name:"bios",lo:0,hi:0x3fff},{name:"cart_rom",lo:0x4000,hi:0xbfff},{name:"work_ram",lo:0xc000,hi:0xffff}],
+        // Genesis (m68k-elf GNU ld map): ROM low, work-RAM mirror at $E0FF0000
+        // (= the emulator's `system_ram`, offset = low 16 bits of the symbol addr).
+        genesis:   [{name:"rom",lo:0,hi:0x3fffff},{name:"work_ram_mirror",lo:0xe0ff0000,hi:0xe0ffffff}],
+      };
+
+      // Parse symbols from whichever format was supplied (auto-detects sdld vs GNU ld).
+      const { format, symbols: all } = await loadSymbolList({ dbg, map });
+
+      const regions = (platform && regionsByPlatform[platform]) || [];
+      const labelFor = (addr) => {
+        for (const r of regions) {
+          if (addr >= r.lo && addr <= r.hi) return r.name;
+        }
+        return "other";
+      };
+
+      const grouped = {};
+      for (const s of all) {
+        const region = labelFor(s.addr);
+        if (!grouped[region]) grouped[region] = [];
+        grouped[region].push({
+          name: s.name,
+          address: s.addr,
+          hex: "$" + s.addr.toString(16).padStart(4, "0").toUpperCase(),
+          kind: s.kind,
+        });
+      }
+
+      return {
+        platform: platform ?? null,
+        format,
+        regions: regions.map((r) => ({
+          name: r.name,
+          range: "$" + r.lo.toString(16).padStart(4, "0").toUpperCase() + "-$" + r.hi.toString(16).padStart(4, "0").toUpperCase(),
+        })),
+        symbolsByRegion: grouped,
+        totalSymbols: all.length,
+      };
+}
+
+/** op:'list' — every symbol sorted by address. cc65 .dbg, sdld .map, OR GNU ld .map (Genesis). */
+export async function listSymbolsCore({ dbg, map, max = 200 }) {
+      const { format, symbols } = await loadSymbolList({ dbg, map });
+      const all = symbols.slice().sort((a, b) => a.addr - b.addr);
+      return {
+        format,
+        total: all.length,
+        returned: Math.min(max, all.length),
+        symbols: all.slice(0, max).map((s) => ({
+          name: s.name,
+          address: s.addr,
+          hex: hexAddr(s.addr),
+          kind: s.kind,
+          ...(s.ramOffset != null ? { ramOffset: s.ramOffset } : {}),
+        })),
+      };
+}
+
+function registerSymbolsTool(server, z) {
+  server.tool(
+    "symbols",
+    "Symbol/linker-map lookups for C/asm-built ROMs — resolve names ↔ addresses and see the memory layout. " +
+    "`op`: 'resolve' | 'lookup' | 'map' | 'list' | 'addr'.\n" +
+    "DEBUG SOURCE for resolve/lookup/map/list (pass ONE; build({output:'romWithDebug'}) returns the right one): " +
+    "`dbg` = cc65 `.dbg` (NES/C64/Atari7800/Lynx/PCE); `map` = a linker map — auto-detects sdld `.map` " +
+    "(GB/GBC/SMS/GG/MSX) vs GNU ld `.map` (Genesis/m68k, the `mapText`/`symbols` field). So resolve/lookup/map/list " +
+    "cover 11 platforms (those listed). The 'addr' op is broader — it parses ANY sdld/ld65-VICE/GNU-ld map text, so it " +
+    "also reaches dasm (Atari 2600) and GBA/ARM.\n" +
+    "OP CHEAT-SHEET: resolve {dbg|map, name}; lookup {dbg|map, address}; map {dbg|map, platform?}; list {dbg|map, max?}; " +
+    "addr {pc, symbolsText|symbolsPath}.\n" +
+    "'resolve' (name→address): resolve a C global, then memory({op:'read'}) it for headless assertions. " +
+    "**GENESIS: a work-RAM symbol comes back with `ramOffset` (the low 16 bits) + a `readHint` — read it via " +
+    "memory({op:'read', region:'system_ram', offset:ramOffset}).** cc65 C symbols become '_score' in the .dbg (the " +
+    "underscored spelling is tried automatically).\n" +
+    "'lookup' (address→symbol): which function/variable does this address fall inside?\n" +
+    "'map' (categorized layout): groups symbols by CPU memory region (zeropage / stack / system RAM / ROM / " +
+    "work-RAM mirror / 'other') so you find where variables landed without probing RAM. Pass `platform` for the region " +
+    "labels. NES: cc65 reserves ZP $00-$01, so your first .res var lands at $02.\n" +
+    "'list': every symbol sorted by address.\n" +
+    "'addr' (PC→nearest preceding symbol): answers 'cpu({op:'read'}) gave me $01A7 — which C function?'. " +
+    "Pass `pc` plus `symbolsText` (inline, from build({includeSymbols:true}) or the romWithDebug map) or `symbolsPath`. " +
+    "Auto-detects GNU ld (Genesis/m68k + GBA/ARM), sdld (`XXXX  _name`, GB/GBC/SMS/GG/MSX), and ld65 VICE " +
+    "(`al XXXX .name`, cc65/dasm).",
+    {
+      op: z.enum(["resolve", "lookup", "map", "list", "addr"]).describe("resolve name→addr; lookup addr→sym; map = layout by region; list all; addr = PC→nearest symbol."),
+      dbg: z.string().optional().describe("op=resolve/lookup/list/map: cc65 .dbg text from build({output:'romWithDebug'}) (NES/C64/Atari7800/Lynx/PCE). Pass this OR `map`."),
+      map: z.string().optional().describe("op=resolve/lookup/list/map: .map text (build's `mapText`/`symbols`) — auto-detects sdld (GB/GBC/SMS/GG/MSX) vs GNU ld (Genesis/m68k). Pass this OR `dbg`."),
+      name: z.string().optional().describe("op=resolve: symbol name (C name; no leading underscore needed — both spellings tried)."),
+      address: z.number().int().min(0).optional().describe("op=lookup: address whose enclosing symbol to find."),
+      max: z.number().int().min(1).max(10000).default(200).describe("op=list: max symbols to return (default 200)."),
+      platform: z.string().optional().describe("op=map: platform id — adds per-platform region labels (incl. genesis work-RAM mirror)."),
+      // addr
+      pc: z.number().int().min(0).max(0xFFFFFF).optional().describe("op=addr: CPU address to look up (e.g. 0x01A7)."),
+      symbolsText: z.string().optional().describe("op=addr: inline .map/.sym text (build's `symbols`). Takes precedence over symbolsPath."),
+      symbolsPath: z.string().optional().describe("op=addr: path to a .map/.sym file (used only if symbolsText absent)."),
+    },
+    safeTool(async (args) => {
+      switch (args.op) {
+        case "resolve": return jsonContent(await resolveSymbolCore(args));
+        case "lookup":  return jsonContent(await lookupAddressCore(args));
+        case "map":     return jsonContent(await getMemoryMapCore(args));
+        case "list":    return jsonContent(await listSymbolsCore(args));
+        case "addr":    return jsonContent(await addressToSymbolCore(args));
+        default: throw new Error(`symbols: unknown op '${args.op}'`);
+      }
+    }),
+  );
+}