romdevtools 0.13.0

package/src/mcp/tools/toolchain.js

@@ -0,0 +1,720 @@
+import { mkdir, mkdtemp, writeFile, readdir, readFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import path from "node:path";
+import { TOOLCHAINS } from "../../toolchains/registry.js";
+import { buildForPlatform } from "../../toolchains/index.js";
+import { resolveLinkerConfig } from "../../toolchains/cc65/preset-resolver.js";
+import { resolveCore } from "../../cores/registry.js";
+import { resetHost, getDisclosure } from "../state.js";
+import { PLATFORM_VIRTUAL_EXT } from "../../host/LibretroHost.js";
+import { imageContent, jsonContent, safeTool, textContent } from "../util.js";
+import { isPlaytestRunning } from "./playtest.js";
+import { buildSourceWithDebugCore } from "./symbols.js";
+import { log as serverLog } from "../log.js";
+
+// Record a build outcome into the /log ring buffer so a failed build's stage +
+// error tail are diagnosable later (the request was already traced; this adds
+// the RESULT). On failure we keep a chunk of the build log; on success just the
+// shape. Always recorded; only printed to stdout in verbose mode.
+function logBuildResult(verb, platform, result) {
+  if (result?.ok) {
+    serverLog.debug(`[build] ${verb} ${platform} OK ${result.binary ? result.binary.length + "B" : ""}`.trim());
+  } else {
+    const errTail = (result?.log || result?.err || "").slice(-1500);
+    serverLog.debug(`[build] ${verb} ${platform} FAILED stage=${result?.stage ?? "?"}${errTail ? "\n" + errTail : ""}`);
+  }
+}
+
+// One-shot "open playtest" hint state — per MCP session, set after the
+// hint has been delivered once so we don't keep nagging legitimate
+// headless flows (CI, automated tests, batch RE work). Keyed by the
+// opaque sessionKey passed in to registerToolchainTools so two MCP
+// sessions don't share state.
+//
+// Cleared when the module is reloaded (server restart). That's fine —
+// the hint is meant to be a gentle one-time nudge, not durable state.
+/** @type {Set<string>} */
+const playtestHintGiven = new Set();
+
+/**
+ * Make a projectName safe to use as a virtual ROM filename (drives the
+ * playtest window title). Strip path separators / control chars, collapse
+ * whitespace, cap length. Never returns "" — falls back to "game".
+ * @param {string} name
+ * @returns {string}
+ */
+function sanitizeProjectName(name) {
+  const clean = String(name)
+    .replace(/[/\\<>:"|?*\x00-\x1f]/g, " ")
+    .replace(/\s+/g, " ")
+    .trim()
+    .slice(0, 48);
+  return clean || "game";
+}
+import { fileURLToPath } from "node:url";
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+
+// Build-log gating (mirrors symbols.js logField). A failing/verbose build
+// log can be huge and explodes the response. Small logs stay inline; large
+// logs are written to a sibling path (when one exists) and only a tail comes
+// back; inline:true returns the full log regardless.
+const LOG_TAIL = 1200;
+
+// On a SUCCESSFUL build the GCC LTO path (Genesis/GBA m68k/arm) prints
+// interprocedural-optimization phase banners and a per-pass timing table that
+// carry no diagnostic value — they just crowd the linker-map / objcopy
+// confirmation out of the tail. Strip those blocks on success so the signal
+// stays visible. Left intact on failure (timing can matter when diagnosing a
+// hang/OOM). The full untrimmed log is still written to logPath when spilled.
+export function denoiseSuccessLog(log) {
+  const lines = log.split("\n");
+  const kept = [];
+  let inTiming = false;
+  for (const line of lines) {
+    // GCC `-ftime-report` table: starts at a "Time variable" header and runs
+    // through the "TOTAL ... GGC" row. Drop the whole block.
+    if (/^\s*Time variable\b/.test(line)) { inTiming = true; continue; }
+    if (inTiming) {
+      if (/^\s*TOTAL\b/.test(line)) inTiming = false;
+      continue;
+    }
+    // LTO interprocedural-optimization phase dump:
+    //   "Performing interprocedural optimizations"
+    //   " <*free_lang_data> {heap 32M} <visibility> {heap 32M} ..."
+    if (/^\s*Performing interprocedural optimizations\s*$/.test(line)) continue;
+    if (/^\s*<[\w*][^>]*>\s*\{heap\b/.test(line)) continue;
+    kept.push(line);
+  }
+  return kept.join("\n");
+}
+
+/**
+ * Fold the build log into a response payload per the gating rule.
+ * @param {string|undefined|null} log
+ * @param {boolean} inline  caller asked for the full log inline
+ * @param {string|null} siblingPath  where to write a large log (e.g. ROM path + ".build.log"); null = nowhere
+ * @param {boolean} [ok=false]  whether the build succeeded — denoise LTO/timing on success
+ * @returns {object} fields to spread into the response
+ */
+async function logField(log, inline, siblingPath, ok = false) {
+  if (!log) return { log: null };
+  // Always write the FULL untrimmed log to disk (it's the forensic record);
+  // only the inline/tail view is denoised on success.
+  const view = ok ? denoiseSuccessLog(log) : log;
+  if (inline || view.length <= LOG_TAIL) return { log: view };
+  if (siblingPath) {
+    await writeFile(siblingPath, log, "utf8");
+    return { logPath: siblingPath, logTail: view.slice(-LOG_TAIL), logBytes: log.length };
+  }
+  // No place to write — the log is a byproduct, not a primary artifact, so
+  // return the tail + size rather than throwing.
+  return { logTail: view.slice(-LOG_TAIL), logBytes: log.length };
+}
+
+// SDCC platforms whose stock-SDCC crt0 doesn't actually boot the target
+// hardware. We bundle a working crt0 in lib/c/ for each — when the
+// agent calls buildSource without an explicit crt0, auto-inject the
+// bundled one so "createProject + buildSource" Just Works.
+//
+// Paths are relative to src/, resolved against this module's location.
+// GB/GBC also ship gb_crt0.s but require codeLoc:0x150 (cart header
+// reserves $0100-$014F) — keep them opt-in to avoid breaking scripts
+// that don't pass codeLoc.
+const AUTO_CRT0_PLATFORMS = {
+  sms: "platforms/sms/lib/c/sms_crt0.s",
+  gg:  "platforms/gg/lib/c/gg_crt0.s",
+};
+
+async function resolveAutoCrt0(platform) {
+  const rel = AUTO_CRT0_PLATFORMS[platform];
+  if (!rel) return null;
+  const abs = path.resolve(__dirname, "..", "..", rel);
+  return await readFile(abs, "utf-8");
+}
+
+/**
+ * Describe a built ROM's on-disk layout in human terms. Surfaces the
+ * "why is this 40976 bytes when my code is 200 lines?" question so the
+ * agent doesn't have to discover NROM/LoROM padding empirically. Returns
+ * null when the platform/binary doesn't have a recognizable header.
+ *
+ * @param {string} platform
+ * @param {Uint8Array | Buffer | null | undefined} bin
+ * @returns {string | null}
+ */
+function describeRomLayout(platform, bin) {
+  if (!bin || bin.length < 16) return null;
+  const total = bin.length;
+  // NES iNES header: "NES\x1A" + prgBanks(16K) + chrBanks(8K) + flags
+  if (platform === "nes" && bin[0] === 0x4E && bin[1] === 0x45 && bin[2] === 0x53 && bin[3] === 0x1A) {
+    const prgBanks = bin[4];
+    const chrBanks = bin[5];
+    const flags6 = bin[6];
+    const flags7 = bin[7];
+    const mapper = (flags6 >> 4) | (flags7 & 0xF0);
+    const prgK = prgBanks * 16;
+    const chrK = chrBanks * 8;
+    const chrKind = chrBanks === 0 ? "CHR-RAM (no CHR data in ROM)" : `${chrK}KB CHR-ROM`;
+    return `${total}B = 16B iNES header + ${prgK}KB PRG-ROM + ${chrKind}, mapper ${mapper}` +
+      (mapper === 0 ? " (NROM — fixed size; padding is normal)" : "");
+  }
+  // SNES LoROM/HiROM: size is always 32KB-aligned (LoROM banks) or 64KB-aligned (HiROM).
+  if (platform === "snes") {
+    const k = Math.floor(total / 1024);
+    const layout = total % 32768 === 0 ? "LoROM (32KB banks)" : "HiROM (64KB banks)";
+    return `${total}B = ${k}KB, ${layout}`;
+  }
+  // Genesis: flat 68k binary, finalized like SGDK (padded to a 128KB
+  // boundary, min 512KB, with the $18E checksum fixed) so it loads on
+  // strict cores (RetroArch Genesis Plus GX, BlastEm) and flashcarts —
+  // not just gpgx-WASM.
+  if (platform === "genesis") {
+    const k = Math.floor(total / 1024);
+    const aligned = total % 131072 === 0;
+    return `${total}B = ${k}KB 68k ROM (padded to 128KB boundary${aligned ? "" : " — WARN: not aligned"}, $18E checksum fixed; loads on real cores/flashcarts)`;
+  }
+  // GB / GBC: 32KB minimum (one ROM bank).
+  if (platform === "gb" || platform === "gbc") {
+    const k = Math.floor(total / 1024);
+    return `${total}B = ${k}KB Game Boy ROM (${total >= 32768 ? "≥1 ROM bank" : "smaller than min bank — may not boot"})`;
+  }
+  return null;
+}
+
+/** platform({op:'toolchains'}) without an id — list bundled toolchains. */
+export function listToolchainsCore() {
+  return {
+    toolchains: Object.values(TOOLCHAINS).map((t) => ({
+      id: t.id,
+      displayName: t.displayName,
+      platforms: t.platforms,
+      tier: t.tier,
+      installed: t.tier === 1, // Tier-1 is always bundled
+    })),
+  };
+}
+
+/** platform({op:'toolchains', id}) — confirm one toolchain's install status (no-op in v1). */
+export function installToolchainCore({ id }) {
+  const t = TOOLCHAINS[id];
+  if (!t) throw new Error(`unknown toolchain '${id}'. Use platform({op:'toolchains'}) to see available ids.`);
+  if (t.tier === 1) return { id, installed: true, note: `toolchain '${id}' is bundled — nothing to install` };
+  throw new Error(`toolchain '${id}' is tier-2 and not yet implemented in v1`);
+}
+
+export function registerToolchainTools(server, z, sessionKey) {
+  async function buildSourceImpl({ platform, language, source, sourcePath, sources, sourcesPaths, includes, binaryIncludes, binaryIncludePaths, includePaths, crt0, crt0Path, codeLoc, dataLoc, options, linkerConfig, outputPath, inline = false, includeSymbols = false, lint = "advisory", runtime, maxmod, rebuildSdk }) {
+      // Reject conflicting inline vs path args — fail loud, not silent.
+      if (source != null && sourcePath != null) {
+        throw new Error("build({output:'rom'}): pass either `source` OR `sourcePath`, not both.");
+      }
+      if (sources != null && sourcesPaths != null) {
+        throw new Error("build({output:'rom'}): pass either `sources` OR `sourcesPaths`, not both.");
+      }
+      if (crt0 != null && crt0Path != null) {
+        throw new Error("build({output:'rom'}): pass either `crt0` OR `crt0Path`, not both.");
+      }
+      // crt0Path → crt0 source.
+      if (crt0Path) {
+        crt0 = await readFile(crt0Path, "utf-8");
+      }
+      // Auto-inject the bundled crt0 for SMS/GG when caller didn't pass
+      // one. Stock SDCC crt0 doesn't boot these targets; without this,
+      // user main() is never called → black screen. See AUTO_CRT0_PLATFORMS.
+      if (crt0 == null) {
+        crt0 = await resolveAutoCrt0(platform);
+      }
+      // Resolve sourcePath → source.
+      if (sourcePath) {
+        source = await readFile(sourcePath, "utf-8");
+      }
+      // Resolve sourcesPaths → sources.
+      if (sourcesPaths) {
+        sources = {};
+        for (const [name, p] of Object.entries(sourcesPaths)) {
+          sources[name] = await readFile(p, "utf-8");
+        }
+      }
+      // Resolve path-based includes by reading from disk. Lets agents skip
+      // pumping big binary blobs through their own context window.
+      const mergedIncludes = { ...(includes ?? {}) };
+      if (includePaths) {
+        for (const [name, p] of Object.entries(includePaths)) {
+          mergedIncludes[name] = await readFile(p, "utf-8");
+        }
+      }
+      const mergedBinaryIncludes = { ...(binaryIncludes ?? {}) };
+      if (binaryIncludePaths) {
+        for (const [name, p] of Object.entries(binaryIncludePaths)) {
+          const bytes = await readFile(p);
+          mergedBinaryIncludes[name] = bytes.toString("base64");
+        }
+      }
+      const { cfg: resolvedLinkerConfig, supportSources } = await resolveLinkerConfig(platform, linkerConfig);
+      // Splice preset support sources (e.g. custom crt0) into the project.
+      // User sources take precedence — never overwrite a source the agent
+      // explicitly provided.
+      const mergedSources = sources
+        ? { ...supportSources, ...sources }
+        : Object.keys(supportSources).length
+          ? { ...supportSources, ...(source ? { "main.c": source } : {}) }
+          : undefined;
+      const useSource = mergedSources ? undefined : source;
+      // Assemble caller-supplied crt0 (SDCC platforms). sm83 → sdasgb,
+      // everything else → sdasz80.
+      let crt0Rel;
+      if (crt0) {
+        const isSm83 = platform === "gb" || platform === "gbc";
+        const { runSdasgb, runSdasz80 } = await import("../../toolchains/sdcc/sdcc.js");
+        const asm = isSm83 ? await runSdasgb({ source: crt0 }) : await runSdasz80({ source: crt0 });
+        if (!asm.rel) {
+          throw new Error(`crt0 assembly failed:\n${asm.log}`);
+        }
+        crt0Rel = asm.rel;
+      }
+      const result = await buildForPlatform({
+        platform,
+        language,
+        runtime,
+        maxmod,
+        rebuildSdk,
+        source: useSource,
+        // Basename of the on-disk source, when given — lets language inference
+        // route by extension (main.c → C, main.s → asm) so an omitted
+        // `language` doesn't fall to the wrong toolchain (the genesis foot-gun).
+        sourceName: sourcePath ? path.basename(sourcePath) : undefined,
+        sources: mergedSources,
+        includes: Object.keys(mergedIncludes).length ? mergedIncludes : undefined,
+        binaryIncludes: Object.keys(mergedBinaryIncludes).length ? mergedBinaryIncludes : undefined,
+        options,
+        linkerConfig: resolvedLinkerConfig,
+        crt0: crt0Rel,
+        codeLoc,
+        dataLoc,
+      });
+      logBuildResult("buildSource", platform, result);
+      // lint:"strict" — if any lint warning fired, fail the build with
+      // stage:"lint" so the agent must fix patterns before iterating.
+      // We mutate the result rather than re-running because the lint
+      // already ran inside buildForPlatform.
+      if (lint === "strict" && result.issues) {
+        const lintHits = result.issues.filter((x) => x.stage === "lint");
+        if (lintHits.length > 0) {
+          result.ok = false;
+          result.binary = null;          // refuse to ship a binary in strict mode
+          result.stage = "lint";
+          result.exitCode = result.exitCode || 1;
+          result.lintStrictBlocked = lintHits.length;
+        }
+      }
+      let finalPath = null;
+      if (result.binary) {
+        if (outputPath) {
+          await mkdir(path.dirname(outputPath), { recursive: true });
+          await writeFile(outputPath, result.binary);
+          finalPath = outputPath;
+        } else if (!inline) {
+          // Default: write to a temp file so the response stays tiny.
+          const tmpDir = await mkdtemp(path.join(tmpdir(), "romdev-"));
+          finalPath = path.join(tmpDir, "out.bin");
+          await writeFile(finalPath, result.binary);
+        }
+      }
+      // One-shot session hint: nudge the agent toward playtest the first
+      // time a build succeeds, IF the show category isn't already loaded.
+      // Fires once per session so it isn't spam on every iteration.
+      const d = getDisclosure();
+      const showHint = result.ok && d && !d.isLoaded("show")
+        ? d.consumeHint(
+            "show-after-first-build",
+            "Build succeeded — your user can watch the game live by calling " +
+            "loadCategory({category:'show'}) then playtest({}). It returns immediately " +
+            "and the window follows your rebuilds, so the emulator stays available to " +
+            "all other tools (screenshot, readMemory, saveState, pause, stepFrames, ...) " +
+            "while the human plays — screenshot() shows the same frame the human sees. " +
+            "Recommended early in any session where a user is watching."
+          )
+        : null;
+      // Gate the build log: small → inline; large → sibling file next to the
+      // ROM (or its tail when there's nowhere to write); inline:true → full.
+      const logSibling = finalPath ? `${finalPath}.build.log` : null;
+      const payload = {
+        ok: result.ok,
+        toolchain: result.toolchain,
+        exitCode: result.exitCode,
+        binaryBytes: result.binary ? result.binary.length : 0,
+        binaryPath: finalPath,
+        outputPath: outputPath && result.binary ? outputPath : null,
+        romLayout: describeRomLayout(platform, result.binary),
+        ...(result.ramUsage ? { ramUsage: result.ramUsage } : {}),
+        ...(result.stage ? { stage: result.stage } : {}),
+        ...(result.sdkEditIgnored ? { sdkEditIgnored: result.sdkEditIgnored } : {}),
+        ...(await logField(result.log, inline, logSibling, result.ok)),
+        issues: result.issues ?? [],
+        ...(showHint ? { hint: showHint } : {}),
+      };
+      // When a build failed on a specific TU (multi-source SDCC build),
+      // surface that explicitly so the agent doesn't have to grep the
+      // log for "FAILED on TU 'name'". If sourcesPaths was used, also
+      // include the host path so the agent can open the right file.
+      if (result.failedTU) {
+        payload.failedTU = result.failedTU;
+        payload.compiledOK = result.compiledOK ?? [];
+        if (sourcesPaths && sourcesPaths[result.failedTU]) {
+          payload.failedTUHostPath = sourcesPaths[result.failedTU];
+        }
+      }
+      // lint:"strict" — surface the count of lint hits that blocked the
+      // build so the agent immediately knows WHY ok:false (vs. a real
+      // compiler error).
+      if (result.lintStrictBlocked) {
+        payload.lintStrictBlocked = result.lintStrictBlocked;
+        payload.note = `Build failed in lint:"strict" mode — ${result.lintStrictBlocked} pattern(s) flagged. ` +
+                       `Fix the issues[] entries with stage:"lint" and rebuild. Pass lint:"advisory" (default) to treat them as warnings instead.`;
+      }
+      // Only include binaryBase64 when the caller actually wants the
+      // bytes inline. Otherwise it's just a confusing `null` field on
+      // every response.
+      if (inline && result.binary) {
+        payload.binaryBase64 = Buffer.from(result.binary).toString("base64");
+      }
+      // Symbols/map info: only include when the underlying toolchain
+      // produced something. SDCC stuffs the .map file here; cc65 writes
+      // a .sym table; vasm68k emits a listing. Keep it small.
+      if (result.symbols && result.symbols.length > 0) {
+        payload.symbolsBytes = result.symbols.length;
+        // Don't embed the whole map by default — it can be 30+ KB on
+        // bigger games and explodes the response. Caller passes
+        // `includeSymbols:true` to opt in.
+        if (includeSymbols) {
+          payload.symbols = result.symbols;
+        } else {
+          payload.symbolsHint = "Pass `includeSymbols: true` to get the full .map/.sym text inline. Or call `addressToSymbol({pc})` to look up a single address without loading it.";
+        }
+      }
+      return jsonContent(payload);
+  }
+
+  async function runSourceImpl({ platform, language, source, sourcePath, sources, sourcesPaths, includes, binaryIncludes, binaryIncludePaths, includePaths, runtime, maxmod, rebuildSdk, crt0, crt0Path, codeLoc, dataLoc, linkerConfig, frames = 60, holdInputs, screenshotPath, projectName }) {
+      const { buildForPlatform } = await import("../../toolchains/index.js");
+      const resolved = resolveCore(platform);
+      if (!resolved) throw new Error(`no core available for platform '${platform}'`);
+
+      if (source != null && sourcePath != null) {
+        throw new Error("build({output:'run'}): pass either `source` OR `sourcePath`, not both.");
+      }
+      if (sources != null && sourcesPaths != null) {
+        throw new Error("build({output:'run'}): pass either `sources` OR `sourcesPaths`, not both.");
+      }
+      if (crt0 != null && crt0Path != null) {
+        throw new Error("build({output:'run'}): pass either `crt0` OR `crt0Path`, not both.");
+      }
+      if (crt0Path) {
+        crt0 = await readFile(crt0Path, "utf-8");
+      }
+      // Auto-inject bundled crt0 for SMS/GG when caller didn't pass one
+      // (stock SDCC crt0 doesn't boot these targets — see buildSource).
+      if (crt0 == null) {
+        crt0 = await resolveAutoCrt0(platform);
+      }
+      if (sourcePath) {
+        source = await readFile(sourcePath, "utf-8");
+      }
+      if (sourcesPaths) {
+        sources = {};
+        for (const [name, p] of Object.entries(sourcesPaths)) {
+          sources[name] = await readFile(p, "utf-8");
+        }
+      }
+      const mergedIncludes = { ...(includes ?? {}) };
+      if (includePaths) {
+        for (const [name, p] of Object.entries(includePaths)) {
+          mergedIncludes[name] = await readFile(p, "utf-8");
+        }
+      }
+      const mergedBinaryIncludes = { ...(binaryIncludes ?? {}) };
+      if (binaryIncludePaths) {
+        for (const [name, p] of Object.entries(binaryIncludePaths)) {
+          const bytes = await readFile(p);
+          mergedBinaryIncludes[name] = bytes.toString("base64");
+        }
+      }
+      const { cfg: resolvedLinkerConfig2, supportSources: supportSources2 } = await resolveLinkerConfig(platform, linkerConfig);
+      const mergedSources2 = sources
+        ? { ...supportSources2, ...sources }
+        : Object.keys(supportSources2).length
+          ? { ...supportSources2, ...(source ? { "main.c": source } : {}) }
+          : undefined;
+      const useSource2 = mergedSources2 ? undefined : source;
+      // Assemble caller-supplied crt0 (SDCC platforms).
+      let crt0Rel2;
+      if (crt0) {
+        const isSm83 = platform === "gb" || platform === "gbc";
+        const { runSdasgb, runSdasz80 } = await import("../../toolchains/sdcc/sdcc.js");
+        const asm = isSm83 ? await runSdasgb({ source: crt0 }) : await runSdasz80({ source: crt0 });
+        if (!asm.rel) {
+          throw new Error(`crt0 assembly failed:\n${asm.log}`);
+        }
+        crt0Rel2 = asm.rel;
+      }
+      const build = await buildForPlatform({
+        platform,
+        language,
+        runtime,
+        maxmod,
+        rebuildSdk,
+        source: useSource2,
+        sourceName: sourcePath ? path.basename(sourcePath) : undefined,
+        sources: mergedSources2,
+        includes: Object.keys(mergedIncludes).length ? mergedIncludes : undefined,
+        binaryIncludes: Object.keys(mergedBinaryIncludes).length ? mergedBinaryIncludes : undefined,
+        linkerConfig: resolvedLinkerConfig2,
+        crt0: crt0Rel2,
+        codeLoc,
+        dataLoc,
+      });
+      logBuildResult("runSource", platform, build);
+      if (!build.ok || !build.binary) {
+        // runSource builds in-memory (no ROM path), so a large failure log
+        // has nowhere to land — gate it to a tail + size rather than dumping
+        // the whole thing. No `inline` param here; the tail is the contract.
+        return jsonContent({
+          ok: false,
+          stage: "build",
+          toolchain: build.toolchain,
+          exitCode: build.exitCode,
+          ...(await logField(build.log, false, null)),
+          issues: build.issues ?? [],
+        });
+      }
+
+      const host = resetHost(sessionKey);
+      await host.loadCore(resolved.jsPath, resolved.wasmPath);
+      // Pass projectName as a virtualName so the playtest window titles itself
+      // with the game name (the SDL window reads host.status.mediaPath). Keep
+      // a platform-correct extension so shared cores still resolve the system.
+      const virtualName = projectName
+        ? sanitizeProjectName(projectName) + (PLATFORM_VIRTUAL_EXT[platform] ?? "")
+        : undefined;
+      await host.loadMedia({ platform, bytes: build.binary, virtualName });
+      if (holdInputs && holdInputs.length > 0) {
+        host.setInput({ ports: holdInputs });
+      }
+      host.stepFrames(frames);
+      // NES: the NMI handler DMAs shadow OAM → real OAM at the START of each
+      // vblank, so sprites the game staged on frame N only become visible
+      // when frame N+1 renders. Without this, the screenshot looks "one frame
+      // behind" the staged OAM (a real surprise agents hit during debugging).
+      // Step one extra frame on NES so the screenshot matches staged sprites.
+      if (platform === "nes") host.stepFrames(1);
+      const shot = host.screenshot();
+
+      // One-shot "open playtest" hint. Conditions to attach:
+      //   - the run succeeded (we only got here on success)
+      //   - no playtest window is currently open
+      //   - we haven't already delivered the hint in this MCP session
+      // Repeated hints would be annoying for legitimate headless flows
+      // (CI, automated tests, agent working alone). Once is a nudge;
+      // repeated is friction.
+      let hint;
+      if (!isPlaytestRunning(sessionKey) && !playtestHintGiven.has(sessionKey)) {
+        playtestHintGiven.add(sessionKey);
+        hint = "No playtest window is open. If a human is watching, consider " +
+               "`loadCategory({category:\"show\"})` then `playtest()` so they can " +
+               "play this ROM live while you keep iterating with runSource " +
+               "(rebuilds update the live game in place). Skip if this session " +
+               "is headless (CI / batch / automated).";
+      }
+
+      const summary = {
+        ok: true,
+        platform,
+        core: resolved.coreName,
+        toolchain: build.toolchain,
+        binaryBytes: build.binary.length,
+        romLayout: describeRomLayout(platform, build.binary),
+        ...(build.ramUsage ? { ramUsage: build.ramUsage } : {}),
+        ...(build.sdkEditIgnored ? { sdkEditIgnored: build.sdkEditIgnored } : {}),
+        framesRun: frames,
+        framebuffer: { width: shot.width, height: shot.height },
+        // Surface lint/build issues even on successful runs so agents see
+        // linter warnings BEFORE the next iteration (was: runSource silently
+        // ran with warnings, agent missed them, hit the crash 100 functions later).
+        ...((build.issues ?? []).length > 0 ? { issues: build.issues } : {}),
+        ...(hint ? { hint } : {}),
+      };
+
+      // Default: screenshot comes back inline (runSource is the "show me the
+      // result" loop). If screenshotPath is set, write it there instead —
+      // for clients that can't display inline images.
+      if (screenshotPath) {
+        // Create the parent dir if missing so a path like ".../shots/title.png"
+        // doesn't ENOENT when the agent hasn't pre-made the folder.
+        await mkdir(path.dirname(screenshotPath), { recursive: true });
+        await writeFile(screenshotPath, Buffer.from(shot.pngBase64, "base64"));
+        const json = jsonContent({ ...summary, screenshotPath });
+        json._observerImages = [{ kind: "image", mimeType: "image/png", base64: shot.pngBase64 }];
+        return json;
+      }
+      return {
+        content: [
+          imageContent(shot.pngBase64),
+          { type: "text", text: JSON.stringify(summary, null, 2) },
+        ],
+      };
+  }
+
+  // build({output:'project'}) — build a project DIRECTORY (no per-call manifest).
+  // Discovers main.c (C/SGDK/GBA/cc65 C) or main.s/main.asm (asm) and links
+  // every source in the dir. Delegates to the module-scope buildProjectCore.
+  const buildProjectImpl = (args) => buildProjectCore(args);
+
+  // ── the `build` router ──────────────────────────────────────────────────
+  const sourcesShape = z.record(z.string(), z.string());
+  const holdInputShape = z.object({
+    up: z.boolean().optional(), down: z.boolean().optional(),
+    left: z.boolean().optional(), right: z.boolean().optional(),
+    a: z.boolean().optional(), b: z.boolean().optional(),
+    x: z.boolean().optional(), y: z.boolean().optional(),
+    l: z.boolean().optional(), r: z.boolean().optional(),
+    l2: z.boolean().optional(), r2: z.boolean().optional(),
+    l3: z.boolean().optional(), r3: z.boolean().optional(),
+    start: z.boolean().optional(), select: z.boolean().optional(),
+  });
+
+  server.tool(
+    "build",
+    "Compile/assemble source for a target platform; one tool keyed by `output`.\n" +
+    "• output:'rom' (default) — assemble or compile `source` (single) / `sources` ({name:contents}) / `sourcePath` / `sourcesPaths`. Returns the ROM (path by default; `inline:true` for binaryBase64) + build log. **`binaryIncludes`/`binaryIncludePaths` (base64/path CHR-ROM, music blobs for `.incbin`) — WITHOUT them no game with external assets builds.** `includes`/`includePaths` for `.include`d text. `linkerConfig` (cc65; NES preset 'chr-ram-runtime' RECOMMENDED). `crt0`/`crt0Path`/`codeLoc`/`dataLoc` (SDCC). `runtime`/`maxmod`/`rebuildSdk` (GBA/Genesis SDK). **`lint:'strict'` fails the build (stage:'lint', no binary) if the pre-flight SDCC crash-pattern scan flags anything (e.g. the uint8 loop-bound trap); 'advisory' (default) just lists hits in issues[].** **`includeSymbols:true` returns the .map text inline on a PLAIN rom build — distinct from output:'romWithDebug' which writes .dbg/.map FILES.** Language is inferred from extension/content — usually OMIT `language`.\n" +
+    "• output:'romWithDebug' — like 'rom' but also emits linker debug info for the `symbols` tool: cc65 → `.dbg`, SDCC → sdld `.map`, Genesis m68k → GNU ld map (find where a RAM var landed). DEFAULT writes ROM + debug file + log to disk (`outputPath` required unless `inline:true`).\n" +
+    "• output:'run' — BUILD + LOAD + RUN + SCREENSHOT in one round trip — the fastest iteration loop. Same build args; runs `frames` frames and returns the screenshot INLINE. `holdInputs` holds controller state; `screenshotPath` writes the PNG to disk instead; `projectName` titles the playtest window.\n" +
+    "• output:'project' — build a project DIRECTORY (`path`) without re-passing the file manifest each call. Entry point is `main.c` (C/SGDK Genesis, GBA, cc65/SDCC C) OR `main.s`/`main.asm` (asm). Every `.c`/`.s`/`.asm` in the dir is a translation unit (linked together), every `.h`/`.inc` an include, and `.bin/.chr/.pcm/.brr/.vgm/...` become binaryIncludes (for `.incbin`). Iterate an on-disk project by re-calling with just `{path, platform}`.",
+    {
+      output: z.enum(["rom", "romWithDebug", "run", "project"])
+        .describe("rom=produce a ROM (default); romWithDebug=ROM + .dbg/.map debug files; run=build+load+run+screenshot; project=build a project directory."),
+      platform: z.string().describe("Target platform id (e.g. 'nes', 'genesis')."),
+      language: z.string().optional().describe("Language override ('c'/'asm'/'basic'). USUALLY OMIT — inferred from source extension/content; only the ambiguous case falls to the platform default. Ignored by output:'romWithDebug' (C only)."),
+      // source inputs (rom/romWithDebug/run)
+      source: z.string().optional().describe("Single source file contents. PREFER `sourcePath` for on-disk files."),
+      sourcePath: z.string().optional().describe("Absolute path to a single source file (server reads it). Mutually exclusive with `source`. NOT read by output:'romWithDebug' — use `source` there."),
+      sources: sourcesShape.optional().describe("Multi-file project: filename → contents ({'main.s':'...', 'aliens.s':'...'})."),
+      sourcesPaths: sourcesShape.optional().describe("Path-based `sources`: virtual filename → absolute path. Mutually exclusive with `sources`. NOT read by output:'romWithDebug'."),
+      includes: sourcesShape.optional().describe("Virtual filename → contents for `.include`d files (NOT separate translation units)."),
+      includePaths: sourcesShape.optional().describe("Path-based `includes` (text files; server reads them). NOT read by output:'romWithDebug'."),
+      binaryIncludes: sourcesShape.optional().describe("Like `includes` but BINARY blobs (CHR ROM, music) as base64, for `.incbin`. PREFER `binaryIncludePaths`. NOT read by output:'romWithDebug'."),
+      binaryIncludePaths: sourcesShape.optional().describe("Path-based `binaryIncludes`: virtual filename → absolute path (server reads the bytes). NOT read by output:'romWithDebug'."),
+      crt0: z.string().optional().describe("SDCC platforms — custom crt0.s source (assembled via sdasgb/sdasz80, linked instead of the stock crt0). SMS/GG auto-inject the bundled crt0 when omitted; GB/GBC pass gb_crt0 + codeLoc:0x150. (romWithDebug reads `crt0` but NOT `crt0Path`.)"),
+      crt0Path: z.string().optional().describe("Path-based `crt0`. NOT read by output:'romWithDebug' — pass `crt0` there."),
+      codeLoc: z.coerce.number().int().optional().describe("SDCC — _CODE load address (default $0000; GB/GBC bundled crt0 wants 0x150)."),
+      dataLoc: z.coerce.number().int().optional().describe("SDCC — _DATA (WRAM) load address (default $C000 on Z80). NOT read by output:'romWithDebug'."),
+      options: z.array(z.string()).optional().describe("output:'rom' — extra toolchain CLI options."),
+      linkerConfig: z.string().optional().describe("ld65 linker config (cc65). NES preset 'chr-ram-runtime' (RECOMMENDED — full crt0 + iNES header + NMI w/ OAM DMA + `_shadow_oam` at $0200) or 'chr-ram' (bare nmi:rti stub), or full .cfg contents. Preset NAMES only resolve on output:'rom'/'run'; output:'romWithDebug' takes raw .cfg contents only."),
+      runtime: z.string().optional().describe("GBA — runtime: 'libtonc' (default), 'libgba', or 'none'."),
+      maxmod: z.boolean().optional().describe("GBA — link maxmod for music (libmm.a). You still call mmInit/mmStart + hook mmVBlank."),
+      rebuildSdk: z.boolean().optional().describe("GBA + Genesis — rebuild the bundled SDK (libtonc/libgba/maxmod/SGDK) from vendored source instead of the prebuilt seed (~20-40s). Only if you edited SDK source (else an `sdkEditIgnored` warning fires)."),
+      lint: z.enum(["advisory", "strict"]).default("advisory").describe("output:'rom' SDCC — 'advisory' (default, warnings in issues[]) or 'strict' (any lint warning fails the build with stage:'lint' before the compiler runs — the SDCC crash-pattern guard)."),
+      includeSymbols: z.boolean().default(false).describe("output:'rom' — return the toolchain's symbol/map text inline (sdld .map / cc65 .sym). False = only symbolsBytes (call symbols/addressToSymbol to look up a PC). Maps can be 30+ KB."),
+      // run-only
+      frames: z.number().int().min(1).max(100000).default(60).describe("output:'run' — frames to run before the screenshot (default 60)."),
+      holdInputs: z.array(holdInputShape).max(2).optional().describe("output:'run' — per-port input state to hold during the run (index 0 = port 0)."),
+      screenshotPath: z.string().optional().describe("output:'run' — write the screenshot here and return {screenshotPath} instead of the inline image (for clients that can't show inline images)."),
+      projectName: z.string().optional().describe("output:'run' — playtest window title (no effect on the ROM)."),
+      // project-only
+      path: z.string().optional().describe("output:'project' — absolute path to the project directory."),
+      // shared output
+      outputPath: z.string().optional().describe("output:'rom'/'romWithDebug'/'project' — absolute path to write the ROM (romWithDebug writes .dbg/.map/.log alongside; REQUIRED for romWithDebug unless inline:true). output:'rom' omitted → temp-file path returned (or inline:true for base64)."),
+      inline: z.boolean().default(false).describe("output:'rom'/'romWithDebug' — return binaryBase64 (+ debug text for romWithDebug) in the response instead of writing to disk."),
+    },
+    safeTool(async (args) => {
+      switch (args.output) {
+        case "rom":          return await buildSourceImpl(args);
+        case "run":          return await runSourceImpl(args);
+        case "project": {
+          if (!args.path) throw new Error("build({output:'project'}): `path` (the project directory) is required.");
+          return await buildProjectImpl(args);
+        }
+        case "romWithDebug": return await buildSourceWithDebugCore(args);
+        default: throw new Error(`build: unknown output '${args.output}'`);
+      }
+    }),
+  );
+}
+
+/**
+ * build({output:'project'}) — build a project DIRECTORY (no per-call manifest).
+ * Module-scope + exported so it's unit-testable. Discovers main.c (C/SGDK/GBA/
+ * cc65 C) or main.s/main.asm (asm) and links every source in the dir. Returns
+ * a jsonContent payload (the router calls it via safeTool, which turns a throw —
+ * e.g. no entry point — into an {isError:true} result).
+ */
+export async function buildProjectCore({ path: projPath, platform, outputPath }) {
+  const entries = await readdir(projPath, { withFileTypes: true });
+  const files = entries.filter((e) => e.isFile());
+
+  // Entry point: a C project uses main.c (SGDK/Genesis, GBA, cc65/SDCC C); an
+  // asm project uses main.s / main.asm. Pick whichever exists — so the SAME
+  // dir-build works for C/SGDK Genesis projects, not just asm/cc65.
+  const hasC = files.some((f) => f.name === "main.c");
+  const hasAsm = files.some((f) => f.name === "main.s" || f.name === "main.asm");
+  if (!hasC && !hasAsm) {
+    throw new Error(
+      `no entry point in ${projPath}: expected main.c (C/SGDK/GBA/cc65 project) or main.s / main.asm (asm project). ` +
+      `Found: ${files.map((f) => f.name).join(", ") || "(empty)"}.`
+    );
+  }
+
+  // Every .c/.s/.asm is its own translation unit (linked together — cc65 routes
+  // .c→cc65 + .s→ca65; SDCC/SGDK/GBA compile every .c). Every .h/.inc is an
+  // include (NOT a TU). Binary assets become binaryIncludes so .incbin survives.
+  /** @type {Record<string,string>} */ const sources = {};
+  /** @type {Record<string,string>} */ const includes = {};
+  /** @type {Record<string,string>} */ const binaryIncludes = {};
+  for (const f of files) {
+    const n = f.name;
+    if (/\.(c|s|asm)$/i.test(n))    sources[n] = await readFile(path.join(projPath, n), "utf-8");
+    else if (/\.(h|inc)$/i.test(n)) includes[n] = await readFile(path.join(projPath, n), "utf-8");
+    else if (/\.(bin|chr|pcm|brr|vgm|xgm|nsf|raw|pal)$/i.test(n)) {
+      binaryIncludes[n] = (await readFile(path.join(projPath, n))).toString("base64");
+    }
+  }
+
+  // Route through resolveLinkerConfig like build({output:'rom'}) so cc65 presets
+  // + support sources still apply for a dir-built cc65 project.
+  const { cfg: resolvedLinkerConfig, supportSources } = await resolveLinkerConfig(platform, undefined);
+  const mergedSources = Object.keys(supportSources).length ? { ...supportSources, ...sources } : sources;
+
+  // Single-source toolchains (dasm/atari2600, vasm/asm) take `source`, not the
+  // multi-TU `sources` map. When the dir has exactly one source file and no
+  // preset support sources, pass it as `source` so those targets still build
+  // (the original asm-only buildProject behavior).
+  const srcNames = Object.keys(sources);
+  const singleSource = srcNames.length === 1 && Object.keys(supportSources).length === 0;
+  const result = await buildForPlatform({
+    platform,
+    ...(singleSource
+      ? { source: sources[srcNames[0]], sourceName: srcNames[0] }
+      : { sources: mergedSources }),
+    includes: Object.keys(includes).length ? includes : undefined,
+    binaryIncludes: Object.keys(binaryIncludes).length ? binaryIncludes : undefined,
+    linkerConfig: resolvedLinkerConfig,
+  });
+  if (outputPath && result.binary) {
+    await mkdir(path.dirname(outputPath), { recursive: true });
+    await writeFile(outputPath, result.binary);
+  }
+  const logSibling = outputPath && result.binary ? `${outputPath}.build.log` : null;
+  return jsonContent({
+    ok: result.ok,
+    toolchain: result.toolchain,
+    exitCode: result.exitCode,
+    binaryBytes: result.binary ? result.binary.length : 0,
+    outputPath: outputPath && result.binary ? outputPath : null,
+    sourcesBuilt: Object.keys(sources),
+    ...(Object.keys(binaryIncludes).length ? { binaryIncludes: Object.keys(binaryIncludes) } : {}),
+    romLayout: describeRomLayout(platform, result.binary),
+    ...(result.stage ? { stage: result.stage } : {}),
+    ...(await logField(result.log, false, logSibling, result.ok)),
+    issues: result.issues ?? [],
+  });
+}