romdev-mcp 0.1.1

package/src/host/types.js

@@ -0,0 +1,280 @@
+// Shared values and small helpers for the libretro host harness.
+// JSDoc typedefs serve as the lingua franca between host / MCP / platform modules.
+
+/** @typedef {"cartridge" | "disk" | "tape" | "program"} MediaKind */
+
+/**
+ * @typedef {"system_ram" | "save_ram" | "video_ram" | "rtc"
+ *   | "nes_nametables" | "nes_palette" | "nes_oam" | "nes_chr"
+ *   | "nes_apu_regs" | "nes_cpu_regs" | "nes_ppu_regs"
+ *   | "snes_oam" | "snes_cgram" | "snes_aram" | "snes_fillram"
+ *   | "genesis_cram" | "genesis_vsram" | "genesis_vdp_regs"
+ *   | "genesis_z80_ram" | "genesis_m68k" | "genesis_ym2612" | "genesis_psg"
+ *   | "sms_vram" | "sms_cram" | "sms_vdp_regs" | "sms_z80_regs"
+ *   | "gg_vram" | "gg_cram"
+ *   | "gb_vram" | "gb_oam" | "gb_io" | "gb_hram"
+ *   | "gb_bgpdata" | "gb_objpdata" | "gb_cpu_regs"
+ *   | "a26_tia_regs" | "a26_cpu_regs"
+ *   | "a78_cpu_regs"
+ *   | "c64_color_ram" | "c64_vic_regs" | "c64_sid_regs"
+ *   | "c64_cia1_regs" | "c64_cia2_regs" | "c64_cpu_regs"
+ * } MemoryRegion
+ */
+
+export const RetroMemory = {
+  SAVE_RAM: 0,
+  RTC: 1,
+  SYSTEM_RAM: 2,
+  VIDEO_RAM: 3,
+  // romdev extensions exposed by our patched cores. These IDs are
+  // honored only by cores we control (fceumm, snes9x, genesis_plus_gx);
+  // other cores return null/0 from retro_get_memory_data.
+  NES_NAMETABLES:     0x100,
+  NES_PALETTE:        0x101,
+  NES_OAM:            0x102,
+  NES_CHR:            0x103,
+  NES_APU_REGS:       0x104,
+  NES_CPU_REGS:       0x105,
+  NES_PPU_REGS:       0x106,
+  SNES_OAM:           0x110,
+  SNES_CGRAM:         0x111,
+  SNES_ARAM:          0x112,
+  SNES_FILLRAM:       0x113,
+  GENESIS_CRAM:       0x120,
+  GENESIS_VSRAM:      0x121,
+  GENESIS_VDP_REGS:   0x122,
+  GENESIS_Z80_RAM:    0x123,
+  GENESIS_M68K:       0x124,
+  GENESIS_YM2612:     0x125,
+  GENESIS_PSG:        0x126,
+  SMS_VRAM:           0x130,
+  SMS_CRAM:           0x131,
+  SMS_VDP_REGS:       0x132,
+  SMS_Z80_REGS:       0x133,
+  GG_VRAM:            0x134,
+  GG_CRAM:            0x135,
+  GB_VRAM:            0x140,
+  GB_OAM:             0x141,
+  GB_IO:              0x142,
+  GB_HRAM:            0x143,
+  GB_BGPDATA:         0x144,
+  GB_OBJPDATA:        0x145,
+  GB_CPU_REGS:        0x146,
+  A78_CPU_REGS:       0x150,
+  A26_TIA_REGS:       0x160,
+  A26_CPU_REGS:       0x161,
+  C64_COLOR_RAM:      0x170,
+  C64_VIC_REGS:       0x171,
+  C64_SID_REGS:       0x172,
+  C64_CIA1_REGS:      0x173,
+  C64_CIA2_REGS:      0x174,
+  C64_CPU_REGS:       0x175,
+};
+
+/** @type {Record<MemoryRegion, number>} */
+export const MemoryRegionToRetro = {
+  save_ram: RetroMemory.SAVE_RAM,
+  rtc: RetroMemory.RTC,
+  system_ram: RetroMemory.SYSTEM_RAM,
+  video_ram: RetroMemory.VIDEO_RAM,
+  nes_nametables: RetroMemory.NES_NAMETABLES,
+  nes_palette: RetroMemory.NES_PALETTE,
+  nes_oam: RetroMemory.NES_OAM,
+  nes_chr: RetroMemory.NES_CHR,
+  nes_apu_regs: RetroMemory.NES_APU_REGS,
+  nes_cpu_regs: RetroMemory.NES_CPU_REGS,
+  nes_ppu_regs: RetroMemory.NES_PPU_REGS,
+  snes_oam: RetroMemory.SNES_OAM,
+  snes_cgram: RetroMemory.SNES_CGRAM,
+  snes_aram: RetroMemory.SNES_ARAM,
+  snes_fillram: RetroMemory.SNES_FILLRAM,
+  genesis_cram: RetroMemory.GENESIS_CRAM,
+  genesis_vsram: RetroMemory.GENESIS_VSRAM,
+  genesis_vdp_regs: RetroMemory.GENESIS_VDP_REGS,
+  genesis_z80_ram: RetroMemory.GENESIS_Z80_RAM,
+  genesis_m68k: RetroMemory.GENESIS_M68K,
+  genesis_ym2612: RetroMemory.GENESIS_YM2612,
+  genesis_psg: RetroMemory.GENESIS_PSG,
+  sms_vram: RetroMemory.SMS_VRAM,
+  sms_cram: RetroMemory.SMS_CRAM,
+  sms_vdp_regs: RetroMemory.SMS_VDP_REGS,
+  sms_z80_regs: RetroMemory.SMS_Z80_REGS,
+  gg_vram: RetroMemory.GG_VRAM,
+  gg_cram: RetroMemory.GG_CRAM,
+  gb_vram: RetroMemory.GB_VRAM,
+  gb_oam: RetroMemory.GB_OAM,
+  gb_io: RetroMemory.GB_IO,
+  gb_hram: RetroMemory.GB_HRAM,
+  gb_bgpdata: RetroMemory.GB_BGPDATA,
+  gb_objpdata: RetroMemory.GB_OBJPDATA,
+  gb_cpu_regs: RetroMemory.GB_CPU_REGS,
+  a78_cpu_regs: RetroMemory.A78_CPU_REGS,
+  a26_tia_regs: RetroMemory.A26_TIA_REGS,
+  a26_cpu_regs: RetroMemory.A26_CPU_REGS,
+  c64_color_ram: RetroMemory.C64_COLOR_RAM,
+  c64_vic_regs:  RetroMemory.C64_VIC_REGS,
+  c64_sid_regs:  RetroMemory.C64_SID_REGS,
+  c64_cia1_regs: RetroMemory.C64_CIA1_REGS,
+  c64_cia2_regs: RetroMemory.C64_CIA2_REGS,
+  c64_cpu_regs:  RetroMemory.C64_CPU_REGS,
+};
+
+/**
+ * Per-port controller state (subset of libretro RETRO_DEVICE_JOYPAD).
+ * @typedef {Object} PortInput
+ * @property {boolean} [up]
+ * @property {boolean} [down]
+ * @property {boolean} [left]
+ * @property {boolean} [right]
+ * @property {boolean} [a]
+ * @property {boolean} [b]
+ * @property {boolean} [x]
+ * @property {boolean} [y]
+ * @property {boolean} [l]
+ * @property {boolean} [r]
+ * @property {boolean} [l2]
+ * @property {boolean} [r2]
+ * @property {boolean} [l3]
+ * @property {boolean} [r3]
+ * @property {boolean} [start]
+ * @property {boolean} [select]
+ */
+
+/**
+ * @typedef {Object} FrameInput
+ * @property {PortInput[]} ports
+ */
+
+/**
+ * @typedef {Object} LoadMediaArgs
+ * @property {string} platform
+ * @property {string} path
+ * @property {MediaKind} [mediaKind]
+ */
+
+/**
+ * @typedef {Object} HostStatus
+ * @property {string | null} platform
+ * @property {string | null} corePath
+ * @property {string | null} mediaPath
+ * @property {MediaKind | null} mediaKind
+ * @property {boolean} loaded
+ * @property {boolean} paused
+ * @property {number} frameCount
+ * @property {number} fbWidth
+ * @property {number} fbHeight
+ */
+
+/**
+ * @typedef {Object} ScreenshotResult
+ * @property {number} width
+ * @property {number} height
+ * @property {string} pngBase64 base64-encoded PNG.
+ */
+
+/**
+ * Default mediaKind for a platform when caller doesn't specify.
+ * Consoles default to cartridge; C64 defaults to program (`.prg`).
+ * @param {string} platform
+ * @returns {MediaKind}
+ */
+export function defaultMediaKind(platform) {
+  switch (platform) {
+    case "c64":
+      return "program";
+    default:
+      return "cartridge";
+  }
+}
+
+/**
+ * Cross-platform face button names. Each platform's diamond is mapped to
+ * compass directions in the physical layout the player sees:
+ *
+ *           north
+ *     west        east
+ *           south
+ *
+ * Per-platform translation to libretro button ids:
+ *
+ *   NES / Game Boy:  east=A, west=B  (north/south have no hardware button)
+ *   SNES:            north=X, east=A, south=B, west=Y
+ *   Genesis 3-btn:   east=C, south=B, west=A  (north has no hardware button)
+ *   Genesis 6-btn:   north=Y, east=C, south=B, west=A
+ *   GBA:             east=A, south=B  (north/west via L/R or none)
+ *
+ * @type {Record<string, { north?: keyof PortInput, east?: keyof PortInput, south?: keyof PortInput, west?: keyof PortInput }>}
+ */
+export const FACE_BUTTON_MAP = {
+  nes:       { east: "a", west: "b" },
+  gb:        { east: "a", west: "b" },
+  gbc:       { east: "a", west: "b" },
+  snes:      { north: "x", east: "a", south: "b", west: "y" },
+  genesis:   { east: "a", south: "b", west: "y" },  // libretro maps Genesis A/B/C onto y/b/a respectively
+  sms:       { east: "a", west: "b" },
+  gg:        { east: "a", west: "b" },
+  gba:       { east: "a", south: "b" },
+  atari2600: { south: "b" },         // 2600 has one button
+  atari7800: { east: "a", south: "b" },
+  lynx:      { east: "a", south: "b" },
+  c64:       { south: "b" },         // C64 joystick fire
+};
+
+/**
+ * Resolve a face-button name (north/east/south/west) for a platform to its
+ * underlying libretro button name. Returns null if the platform doesn't have
+ * a button in that direction.
+ *
+ * @param {string} platform
+ * @param {"north" | "east" | "south" | "west"} face
+ * @returns {string | null}
+ */
+export function faceToButton(platform, face) {
+  const map = FACE_BUTTON_MAP[platform];
+  if (!map) return null;
+  return map[face] ?? null;
+}
+
+/**
+ * Map a PortInput object to a libretro JOYPAD bitmask. Accepts both the raw
+ * libretro names (a/b/x/y/l/r/l2/r2/l3/r3/select/start/up/down/left/right)
+ * and the cross-platform spatial names (north/east/south/west). Spatial names
+ * are resolved through `platform`; if no platform is given, they're ignored.
+ *
+ * @param {PortInput & { north?: boolean, east?: boolean, south?: boolean, west?: boolean }} input
+ * @param {string} [platform] for resolving spatial names
+ * @returns {number}
+ */
+export function portInputToMask(input, platform) {
+  if (!input) return 0;
+  let m = 0;
+
+  // Spatial → libretro name (resolved through platform map).
+  const merged = { ...input };
+  if (platform) {
+    for (const face of ["north", "east", "south", "west"]) {
+      if (input[face]) {
+        const target = faceToButton(platform, face);
+        if (target) merged[target] = true;
+      }
+    }
+  }
+
+  if (merged.b) m |= 1 << 0;
+  if (merged.y) m |= 1 << 1;
+  if (merged.select) m |= 1 << 2;
+  if (merged.start) m |= 1 << 3;
+  if (merged.up) m |= 1 << 4;
+  if (merged.down) m |= 1 << 5;
+  if (merged.left) m |= 1 << 6;
+  if (merged.right) m |= 1 << 7;
+  if (merged.a) m |= 1 << 8;
+  if (merged.x) m |= 1 << 9;
+  if (merged.l) m |= 1 << 10;
+  if (merged.r) m |= 1 << 11;
+  if (merged.l2) m |= 1 << 12;
+  if (merged.r2) m |= 1 << 13;
+  if (merged.l3) m |= 1 << 14;
+  if (merged.r3) m |= 1 << 15;
+  return m;
+}

package/src/mcp/disclosure.js

@@ -0,0 +1,250 @@
+// Progressive disclosure: ship a tiny entry-tier of tools at session init;
+// register the rest on demand via loadCategory.
+//
+// Why: Anthropic's own benchmarks (MCP design research, 2026-05-23 session)
+// show lazy tool loading moves Opus 4 from 49% → 74% on tool-selection
+// accuracy. The benefit is larger for weaker models: a 5-tool surface is
+// navigable; a 65-tool surface induces decision paralysis even before the
+// agent picks the wrong one.
+//
+// Design constraint: "narrow at entry, deep once in."
+// Recipes don't gate primitives; categories don't hide capabilities. Any
+// agent can load any category at any time. The "all" pseudo-category
+// loads everything in one call for power users who don't want the dance.
+//
+// Mitigations for weaker-model failure modes:
+// 1. loadCategory's response includes the FULL SCHEMAS of every tool it
+//    just registered, so the agent can call them immediately without
+//    waiting for tools/list_changed to propagate (which is async).
+// 2. listCategories and per-tool descriptions include a `next_steps`
+//    hint pointing weaker agents at the right load call.
+// 3. Tool-not-found errors include the category to load when the tool
+//    exists but hasn't been loaded yet.
+//
+// Capable agents skip all this by calling loadCategory({category:"all"})
+// as their first call; they then have the full surface unchanged.
+
+/**
+ * @typedef {Object} Category
+ * @property {string} name
+ * @property {string} description user-facing one-liner
+ * @property {string[]} useWhen 1-3 hints about when this category matters
+ * @property {(server: any, z: any) => void} register the original register fn
+ */
+
+/**
+ * Build a per-session disclosure manager. One per McpServer instance.
+ * @param {any} server the McpServer
+ * @param {any} z zod
+ * @param {Category[]} categories all loadable categories
+ * @param {string} sessionKey per-MCP-session host scope key — forwarded
+ *   to each category's register fn so tool handlers can call
+ *   getHost(sessionKey) and friends.
+ */
+export function createDisclosure(server, z, categories, sessionKey) {
+  const byName = new Map(categories.map((c) => [c.name, c]));
+  const loaded = new Set();
+  // Session-scoped one-shot flags used by tool handlers to nudge agents
+  // without spamming every response. Each flag fires at most once per
+  // session, gated by whether the relevant tip is still useful.
+  const shownHints = new Set();
+
+  /** @returns {string[]} names of every tool currently registered. */
+  function listRegistered() {
+    return Object.keys(server._registeredTools ?? {});
+  }
+
+  /**
+   * Crawl a Zod schema node and return {type, optional, description, enum?}.
+   * Handles ZodMiniObject (def.shape), optionals, defaults, enums, and the
+   * basic primitives (string/number/boolean/array/object). Returns "unknown"
+   * for shapes we don't recognize — better than crashing the discovery flow.
+   */
+  function summarizeZod(node) {
+    if (!node) return { type: "unknown" };
+    const def = node.def ?? node._def;
+    if (!def) return { type: "unknown" };
+    let type = def.type ?? "unknown";
+    let optional = false;
+    let description = node.description ?? def.description ?? undefined;
+    let enumValues;
+    // Unwrap optional / default wrappers (zod-mini wraps the inner type in def.innerType).
+    if ((type === "optional" || type === "default") && def.innerType) {
+      const inner = summarizeZod(def.innerType);
+      optional = true;
+      type = inner.type;
+      description = description ?? inner.description;
+      enumValues = inner.enum;
+    }
+    if (type === "enum" && def.entries) {
+      // zod-mini: def.entries is { value: value } object; values are the enum members.
+      enumValues = Array.isArray(def.entries)
+        ? def.entries.map((e) => e.value ?? e)
+        : Object.values(def.entries);
+    } else if (type === "enum" && def.values) {
+      enumValues = Object.values(def.values);
+    }
+    const out = { type };
+    if (optional) out.optional = true;
+    if (description) out.description = description;
+    if (enumValues) out.enum = enumValues;
+    return out;
+  }
+
+  /** Snapshot of one tool's exposed schema for the response. */
+  function describe(name) {
+    const t = server._registeredTools?.[name];
+    if (!t) return null;
+    // ZodMiniObject stores field shape at inputSchema.shape (zod-mini) or
+    // inputSchema._def.shape() (classic zod). Try both. Fall back to an
+    // empty params list rather than the schema's method names.
+    let shape = null;
+    if (t.inputSchema?.shape && typeof t.inputSchema.shape === "object") {
+      shape = t.inputSchema.shape;
+    } else if (typeof t.inputSchema?._def?.shape === "function") {
+      shape = t.inputSchema._def.shape();
+    } else if (t.inputSchema?._def?.shape && typeof t.inputSchema._def.shape === "object") {
+      shape = t.inputSchema._def.shape;
+    }
+    const parameters = shape
+      ? Object.entries(shape).map(([key, schema]) => ({ name: key, ...summarizeZod(schema) }))
+      : [];
+    return {
+      name,
+      description: t.description ?? "",
+      parameters,
+    };
+  }
+
+  /**
+   * Load a category. Idempotent — calling twice is fine. Returns the
+   * tool schemas the agent can now use immediately (no wait for
+   * tools/list_changed).
+   * @param {string} name
+   */
+  // Each category's register() function may include tools whose names
+  // collide with already-registered ones (entry-tier `getStatus`, etc.).
+  // MCP SDK throws "Tool X is already registered" on collision and
+  // aborts further registration in that category. Wrap server.tool/
+  // registerTool with skip-existing semantics so categories register
+  // partially-and-cleanly instead of partially-and-broken.
+  function registerCategorySafely(cat) {
+    const orig = server.tool.bind(server);
+    const origRegister = server.registerTool?.bind(server);
+    let skippedDupes = 0;
+    server.tool = (name, ...rest) => {
+      if (server._registeredTools?.[name]) {
+        skippedDupes++;
+        return null; // silently skip; caller doesn't need the handle
+      }
+      return orig(name, ...rest);
+    };
+    if (origRegister) {
+      server.registerTool = (name, ...rest) => {
+        if (server._registeredTools?.[name]) {
+          skippedDupes++;
+          return null;
+        }
+        return origRegister(name, ...rest);
+      };
+    }
+    try {
+      cat.register(server, z, sessionKey);
+    } finally {
+      server.tool = orig;
+      if (origRegister) server.registerTool = origRegister;
+    }
+    return skippedDupes;
+  }
+
+  /** Like describe() but only returns {name, description} — keeps the
+   * loadCategory response small. Agents pull full schemas via
+   * describeTool on demand. */
+  function describeBrief(name) {
+    const t = server._registeredTools?.[name];
+    if (!t) return null;
+    return {
+      name,
+      // Truncate description to ~200 chars — enough to know what the tool
+      // is for, not enough to blow the response cap when 60+ tools load.
+      description: (t.description ?? "").slice(0, 200),
+    };
+  }
+
+  function loadCategory(name, opts = {}) {
+    const verbose = !!opts.verbose;
+    const describeFn = verbose ? describe : describeBrief;
+    if (name === "all") {
+      const loadedNames = [];
+      let totalSkipped = 0;
+      for (const cat of categories) {
+        if (!loaded.has(cat.name)) {
+          totalSkipped += registerCategorySafely(cat);
+          loaded.add(cat.name);
+          loadedNames.push(cat.name);
+        }
+      }
+      return {
+        loaded: loadedNames,
+        alreadyLoaded: [...loaded].filter((c) => !loadedNames.includes(c)),
+        tools: listRegistered().map(describeFn).filter(Boolean),
+        skippedDuplicates: totalSkipped,
+      };
+    }
+
+    const cat = byName.get(name);
+    if (!cat) {
+      throw new Error(
+        `unknown category '${name}'. Available: ${[...byName.keys()].join(", ")}, or 'all'. ` +
+        `Call listCategories() for descriptions.`
+      );
+    }
+    if (loaded.has(name)) {
+      return {
+        loaded: [],
+        alreadyLoaded: [name],
+        tools: listRegistered().map(describeFn).filter(Boolean),
+      };
+    }
+    // Snapshot what's registered BEFORE this category loads, so we can
+    // return ONLY the newly-added tool schemas (not the entry-tier ones
+    // the agent already has).
+    const before = new Set(listRegistered());
+    const skipped = registerCategorySafely(cat);
+    loaded.add(name);
+    const added = listRegistered().filter((n) => !before.has(n));
+    return {
+      loaded: [name],
+      alreadyLoaded: [],
+      tools: added.map(describeFn).filter(Boolean),
+      skippedDuplicates: skipped,
+    };
+  }
+
+  /** @returns {{name, description, useWhen, loaded}[]} */
+  function listCategories() {
+    return categories.map((c) => ({
+      name: c.name,
+      description: c.description,
+      useWhen: c.useWhen,
+      loaded: loaded.has(c.name),
+    }));
+  }
+
+  function isLoaded(catName) {
+    return loaded.has(catName);
+  }
+
+  /**
+   * One-shot session hint. Returns the message the first time it's called
+   * with a given key, then null thereafter. Lets handlers emit a nudge
+   * without spamming every response.
+   */
+  function consumeHint(key, message) {
+    if (shownHints.has(key)) return null;
+    shownHints.add(key);
+    return message;
+  }
+
+  return { loadCategory, listCategories, describe, isLoaded, consumeHint };
+}

package/src/mcp/log.js

@@ -0,0 +1,87 @@
+// log.js — tiny leveled logger so the server is QUIET by default in prod.
+//
+// The per-call / per-session trace lines are invaluable while developing but
+// are noise (and IO cost) in a published package. They're gated behind a
+// verbosity switch for STDOUT — but every message is ALSO captured into an
+// in-memory ring buffer regardless of verbosity, so you can pull recent
+// activity as JSON from the /log HTTP endpoint without scraping stdout (or
+// having had --verbose on). The /livestream socket.io stream remains the
+// canonical live monitor; /log is the cheap "what just happened?" poll.
+//
+// Levels (low → high verbosity):
+//   error  — always printed (to stderr)
+//   info   — always printed (to stdout): startup banner, shutdown, fatals
+//   debug  — printed ONLY when verbose: per-call traces, session lifecycle,
+//            playtest/observer chatter
+// All three are always recorded in the ring buffer.
+//
+// Enable debug stdout with any of:
+//   --verbose                 (CLI flag)
+//   ROMDEV_LOG=debug          (env; also accepts "verbose"/"trace")
+//   ROMDEV_VERBOSE=1          (env)
+
+function computeVerbose() {
+  if (process.argv.slice(2).includes("--verbose")) return true;
+  const lvl = (process.env.ROMDEV_LOG ?? "").toLowerCase();
+  if (lvl === "debug" || lvl === "verbose" || lvl === "trace") return true;
+  if (process.env.ROMDEV_VERBOSE && process.env.ROMDEV_VERBOSE !== "0") return true;
+  return false;
+}
+
+// Resolved once at import. Server is a long-lived process; no need to re-check.
+const VERBOSE = computeVerbose();
+
+// Bounded FIFO ring buffer of recent log records. A long-running server emits
+// unbounded log lines over its lifetime, so this MUST drop the oldest records
+// to stay flat in memory — two caps guarantee that:
+//   - RING_CAP   : max number of records kept (oldest evicted on overflow)
+//   - MSG_CAP    : max chars per record (a giant stack/object can't bloat one)
+// Sized so a whole multi-turn agent session — including build error logs, which
+// can be several KB each — fits and stays diagnosable. Worst-case footprint ≈
+// RING_CAP * MSG_CAP ≈ 5000 * 8 KB ≈ 40 MB, fixed. Override with
+// ROMDEV_LOG_RING / ROMDEV_LOG_MSG_CAP if you need more/less.
+const RING_CAP = Number(process.env.ROMDEV_LOG_RING) || 5000;
+const MSG_CAP = Number(process.env.ROMDEV_LOG_MSG_CAP) || 8000;
+/** @type {{t:number, level:string, msg:string}[]} */
+const ring = [];
+
+function record(level, args) {
+  // Join args into one string the way console would, cheaply.
+  let msg;
+  try {
+    msg = args.map((a) => (typeof a === "string" ? a : stringifyArg(a))).join(" ");
+  } catch {
+    msg = String(args[0]);
+  }
+  // Truncate oversized single messages so one record can't leak memory.
+  if (msg.length > MSG_CAP) msg = msg.slice(0, MSG_CAP) + `…(+${msg.length - MSG_CAP} chars)`;
+  ring.push({ t: Date.now(), level, msg });
+  // Drop oldest so the queue length never exceeds the cap.
+  if (ring.length > RING_CAP) ring.splice(0, ring.length - RING_CAP);
+}
+
+function stringifyArg(a) {
+  if (a instanceof Error) return a.stack || `${a.name}: ${a.message}`;
+  try { return JSON.stringify(a); } catch { return String(a); }
+}
+
+export const log = {
+  /** Whether debug-level output is printed to stdout. */
+  verbose: VERBOSE,
+  /** Always printed. Startup banner, shutdown notices, anything a user must see. */
+  info(...args) { record("info", args); console.log(...args); },
+  /** Always printed, on stderr. Real failures. */
+  error(...args) { record("error", args); console.error(...args); },
+  /** Printed only in verbose mode; always recorded in the ring buffer. */
+  debug(...args) { record("debug", args); if (VERBOSE) console.log(...args); },
+  /**
+   * Most-recent log records (oldest → newest), newest-last. Pass a limit to cap
+   * how many you get back (default all in the buffer, max RING_CAP).
+   * @param {number} [limit]
+   * @returns {{t:number, level:string, msg:string}[]}
+   */
+  recent(limit) {
+    if (!limit || limit >= ring.length) return ring.slice();
+    return ring.slice(ring.length - limit);
+  },
+};