romdev-mcp 0.1.1

package/src/mcp/tools/watch-memory.js

@@ -0,0 +1,212 @@
+// `watchMemory` — run the emulator forward and report every frame that changed
+// a watched byte range. Cross-platform (no core patches): polls the region
+// before/after each frame, diffs the result, records (frame, offset, before,
+// after, PC).
+//
+// `runUntilWrite` — narrower: step until target address is written, then stop.
+// Returns the same shape minus the full timeline.
+//
+// Granularity: this is frame-level, not instruction-level. If a single frame
+// writes to the same address ten times, we only see the LAST value. For most
+// ROM-hacking workflows this is enough — you usually just want "what code is
+// touching this byte and what does the screen look like after," not a complete
+// CPU trace. Instruction-level tracing would need core-side breakpoint hooks.
+
+import { getHost } from "../state.js";
+import { jsonContent, safeTool } from "../util.js";
+import { getCPUState } from "../../host/cpu-state.js";
+
+const MEMORY_REGIONS = [
+  "system_ram", "save_ram", "video_ram", "rtc",
+  "nes_nametables", "nes_palette", "nes_oam", "nes_chr",
+  "snes_cgram", "snes_oam", "snes_aram", "snes_fillram",
+  "gb_vram", "gb_oam", "gb_io", "gb_hram", "gb_bgpdata", "gb_objpdata",
+  "sms_vram", "sms_cram", "sms_vdp_regs", "sms_z80_regs", "gg_vram", "gg_cram",
+  "md_cram", "md_vsram", "md_vdp_regs", "md_z80_ram", "md_m68k_ram", "md_ym2612", "md_psg", "md_vram",
+  "a26_tia_regs", "a26_cpu_regs", "a78_cpu_regs",
+];
+
+function tryGetPC(host) {
+  try {
+    const platform = host.status?.platform;
+    if (!platform) return null;
+    const cpu = getCPUState(host, platform);
+    if (cpu && typeof cpu.pc === "number") return cpu.pc;
+    return null;
+  } catch {
+    return null;
+  }
+}
+
+function hexPC(pc) {
+  if (pc == null) return null;
+  return "$" + pc.toString(16).toUpperCase().padStart(4, "0");
+}
+
+function snap(host, region, offset, length) {
+  return Array.from(host.readMemory(region, offset, length));
+}
+
+function diffSnapshots(before, after, baseOffset) {
+  const changes = [];
+  for (let i = 0; i < before.length; i++) {
+    if (before[i] !== after[i]) {
+      changes.push({
+        offset: baseOffset + i,
+        offsetHex: "0x" + (baseOffset + i).toString(16).toUpperCase().padStart(4, "0"),
+        before: before[i],
+        after: after[i],
+      });
+    }
+  }
+  return changes;
+}
+
+export function registerWatchMemoryTools(server, z, sessionKey) {
+  server.tool(
+    "watchMemory",
+    "Use this to answer 'what code is touching this RAM byte?' without an instruction tracer: runs N frames " +
+    "and reports every frame that changed a byte in the watched region as {frame, offset, before, after, " +
+    "pc} — the pc tells you which disasm line to patch. Supports `pressDuring` to drive input at specific " +
+    "frames. CAVEAT: frame-level, not instruction-level — if a frame writes the byte several times you only " +
+    "see the last value (enough to find the code path, not for cycle-exact tracing). Cross-platform.",
+    {
+      region: z.enum(MEMORY_REGIONS).describe("Memory region to watch (matches readMemory's region arg)."),
+      offset: z.number().int().min(0).describe("First byte of the watched range."),
+      length: z.number().int().min(1).max(4096).default(1).describe("How many bytes to watch (default 1)."),
+      frames: z.number().int().min(1).max(1_000_000).default(600).describe("How many frames to run (default 600 = ~10s NTSC)."),
+      stopOnFirst: z.boolean().default(false).describe("If true, stop on the first detected change instead of running for the full duration."),
+      maxEvents: z.number().int().min(1).max(10_000).default(256).describe("Cap on returned events; surplus events are dropped with a `truncated` flag."),
+      pressDuring: z.array(z.object({
+        frame: z.number().int().min(0).describe("Frame on which to press."),
+        button: z.string().describe("Button name (see input-layout.js)."),
+        port: z.number().int().min(0).max(3).default(0),
+        holdFrames: z.number().int().min(1).default(2),
+      })).optional().describe("Schedule button presses while watching, so the agent can simulate user input mid-watch."),
+    },
+    safeTool(async ({ region, offset, length, frames, stopOnFirst, maxEvents, pressDuring }) => {
+      const host = getHost(sessionKey);
+      const events = [];
+      let truncated = false;
+      const presses = (pressDuring ?? []).slice().sort((a, b) => a.frame - b.frame);
+
+      let prev = snap(host, region, offset, length);
+      const startFrame = host.status.frameCount;
+
+      for (let i = 0; i < frames; i++) {
+        // Schedule any inputs that fire on this frame.
+        while (presses.length && presses[0].frame === i) {
+          const p = presses.shift();
+          try { host.pressButton(p.port, p.button, p.holdFrames); } catch { /* button name may be unknown */ }
+        }
+        host.stepFrames(1);
+        const cur = snap(host, region, offset, length);
+        const changes = diffSnapshots(prev, cur, offset);
+        if (changes.length > 0) {
+          const pc = tryGetPC(host);
+          const frameAbs = startFrame + i + 1;
+          for (const c of changes) {
+            if (events.length >= maxEvents) { truncated = true; break; }
+            events.push({
+              frame: frameAbs,
+              frameRelative: i + 1,
+              ...c,
+              pc: hexPC(pc),
+              pcRaw: pc,
+            });
+          }
+          if (stopOnFirst) {
+            prev = cur;
+            return jsonContent({
+              region,
+              offset,
+              length,
+              framesStepped: i + 1,
+              eventCount: events.length,
+              events,
+              truncated,
+              stoppedEarly: true,
+              note: tryGetPC(host) == null
+                ? "PC not available for this platform (getCPUState returned no pc field)."
+                : undefined,
+            });
+          }
+          if (truncated) break;
+          prev = cur;
+        } else {
+          prev = cur;
+        }
+      }
+
+      return jsonContent({
+        region,
+        offset,
+        length,
+        framesStepped: frames,
+        eventCount: events.length,
+        events,
+        truncated,
+        stoppedEarly: false,
+        note: events.length === 0
+          ? "No writes observed in the watched window. Try (a) longer `frames`, (b) `pressDuring` to drive the game past the event, (c) a wider `length` or a different region."
+          : undefined,
+      });
+    }),
+  );
+
+  server.tool(
+    "runUntilWrite",
+    "Step the emulator forward until a target byte changes, then stop. Convenience wrapper around watchMemory " +
+    "with stopOnFirst=true. Returns the writing frame + PC + before/after values + a screenshot of the resulting state. " +
+    "Pair this with `disassembleRom` + the returned PC to immediately locate the code line that did the write.",
+    {
+      region: z.enum(MEMORY_REGIONS),
+      offset: z.number().int().min(0),
+      length: z.number().int().min(1).max(4096).default(1),
+      maxFrames: z.number().int().min(1).max(1_000_000).default(600),
+      pressDuring: z.array(z.object({
+        frame: z.number().int().min(0),
+        button: z.string(),
+        port: z.number().int().min(0).max(3).default(0),
+        holdFrames: z.number().int().min(1).default(2),
+      })).optional(),
+    },
+    safeTool(async ({ region, offset, length, maxFrames, pressDuring }) => {
+      const host = getHost(sessionKey);
+      const presses = (pressDuring ?? []).slice().sort((a, b) => a.frame - b.frame);
+      let prev = snap(host, region, offset, length);
+      const startFrame = host.status.frameCount;
+
+      for (let i = 0; i < maxFrames; i++) {
+        while (presses.length && presses[0].frame === i) {
+          const p = presses.shift();
+          try { host.pressButton(p.port, p.button, p.holdFrames); } catch { /* ignore */ }
+        }
+        host.stepFrames(1);
+        const cur = snap(host, region, offset, length);
+        const changes = diffSnapshots(prev, cur, offset);
+        if (changes.length > 0) {
+          const pc = tryGetPC(host);
+          const frameAbs = startFrame + i + 1;
+          return jsonContent({
+            written: true,
+            frame: frameAbs,
+            frameRelative: i + 1,
+            changes,
+            pc: hexPC(pc),
+            pcRaw: pc,
+            hint: pc != null
+              ? `Use disassembleRom near ${hexPC(pc)} on this ROM to find the writing instruction. The mapper-aware @0xNNNN file-offset comment on each line tells you what bytes to patch.`
+              : "PC was not available — check that getCPUState is wired for this platform.",
+          });
+        }
+        prev = cur;
+      }
+      return jsonContent({
+        written: false,
+        framesStepped: maxFrames,
+        note: "Target byte was not written within maxFrames. Try increasing maxFrames or driving the game with pressDuring.",
+      });
+    }),
+  );
+}

package/src/mcp/tools/which-tiles.js

@@ -0,0 +1,193 @@
+// whichTilesAreRendered — at the current emulator state, walk the BG nametable
+// + OAM and return the set of tile IDs actually being drawn this frame.
+//
+// Replaces the "extract sprite sheet then guess by eye which tiles are which"
+// workflow. Lets an agent sample the same call across game states (title,
+// gameplay, menu) and build their own tile-to-content map.
+
+import { getHost } from "../state.js";
+import { jsonContent, safeTool } from "../util.js";
+
+function resolvePlatform(host, requested) {
+  const p = requested ?? host.status.platform;
+  if (!p) throw new Error("no platform specified and no host loaded");
+  return p;
+}
+
+function summariseTileSet(ids) {
+  if (ids.size === 0) return { count: 0, ids: [], ranges: [] };
+  const sorted = [...ids].sort((a, b) => a - b);
+  // Coalesce contiguous runs of tile IDs into [start, end] ranges.
+  const ranges = [];
+  let runStart = sorted[0];
+  let runEnd = sorted[0];
+  for (let i = 1; i < sorted.length; i++) {
+    if (sorted[i] === runEnd + 1) {
+      runEnd = sorted[i];
+    } else {
+      ranges.push([runStart, runEnd]);
+      runStart = sorted[i];
+      runEnd = sorted[i];
+    }
+  }
+  ranges.push([runStart, runEnd]);
+  return {
+    count: ids.size,
+    ids: sorted,
+    idsHex: sorted.map((n) => "0x" + n.toString(16).toUpperCase().padStart(2, "0")),
+    ranges: ranges.map(([s, e]) => s === e
+      ? "0x" + s.toString(16).toUpperCase().padStart(2, "0")
+      : "0x" + s.toString(16).toUpperCase().padStart(2, "0") + "-0x" + e.toString(16).toUpperCase().padStart(2, "0")),
+  };
+}
+
+export function registerWhichTilesTools(server, z, sessionKey) {
+  server.tool(
+    "whichTilesAreRendered",
+    "Use this to map tile IDs → game assets: walks the current frame's BG nametable + OAM and returns the " +
+    "set of tile IDs actually being drawn ({background, sprite, combined}, each with ids/idsHex/ranges). " +
+    "ROM-hack trick: call it at the title screen, then again in gameplay, and SUBTRACT the sets — what's " +
+    "unique to gameplay is your in-game art. Supported: nes, snes (pass `snesTilemapBaseByte` for BG — " +
+    "snes9x hides the PPU regs), gb, gbc, sms, gg, genesis, c64.",
+    {
+      platform: z.string().optional(),
+      snesTilemapBaseByte: z.number().int().min(0).optional().describe("SNES only: byte offset into VRAM of a BG tilemap (BGxSC base). If set, its referenced tile IDs are added to `background`. snes9x can't auto-detect this."),
+      snesMapWidth: z.union([z.literal(32), z.literal(64)]).default(32).describe("SNES only: tilemap width in tiles (with snesTilemapBaseByte)."),
+      snesMapHeight: z.union([z.literal(32), z.literal(64)]).default(32).describe("SNES only: tilemap height in tiles (with snesTilemapBaseByte)."),
+    },
+    safeTool(async ({ platform, snesTilemapBaseByte, snesMapWidth, snesMapHeight }) => {
+      const host = getHost(sessionKey);
+      const p = resolvePlatform(host, platform);
+      const bg = new Set();
+      const sprite = new Set();
+
+      if (p === "nes") {
+        // BG: read both nametables ($2000 + $2400), first 960 bytes of each
+        // (32×30 tiles; the remaining 64 bytes are the attribute table, not
+        // tile IDs).
+        const nt = host.readMemory("nes_nametables", 0, 2048);
+        for (let i = 0; i < 960; i++) bg.add(nt[i]);
+        for (let i = 1024; i < 1024 + 960; i++) bg.add(nt[i]);
+
+        // OAM: 64 entries, tile is byte 1.
+        const oam = host.readMemory("nes_oam", 0, 256);
+        for (let i = 0; i < 64; i++) {
+          const y = oam[i * 4 + 0];
+          if (y >= 0xF0) continue; // off-screen
+          sprite.add(oam[i * 4 + 1]);
+        }
+      } else if (p === "gb" || p === "gbc") {
+        const vram = host.readMemory("gb_vram", 0, 0x4000);
+        const io = host.readMemory("gb_io", 0, 0x80);
+        // LCDC bit 3 = BG map area ($9800 or $9C00); bit 6 = window map area.
+        const lcdc = io[0x40];
+        const bgMapBase = (lcdc & 0x08) ? 0x1C00 : 0x1800;
+        const windowMapBase = (lcdc & 0x40) ? 0x1C00 : 0x1800;
+        for (let i = 0; i < 1024; i++) bg.add(vram[bgMapBase + i]);
+        for (let i = 0; i < 1024; i++) bg.add(vram[windowMapBase + i]);
+
+        // OAM at $FE00 = gb_oam region; 40 entries × 4 bytes.
+        const oam = host.readMemory("gb_oam", 0, 160);
+        for (let i = 0; i < 40; i++) {
+          const y = oam[i * 4 + 0];
+          if (y === 0 || y >= 160) continue; // off-screen
+          sprite.add(oam[i * 4 + 2]); // byte 2 = tile index
+        }
+      } else if (p === "sms" || p === "gg") {
+        const vram = host.readMemory("video_ram", 0, 0x4000);
+        const regs = host.readMemory("sms_vdp_regs", 0, 16);
+        // VDP reg 2 bits 1-3 = nametable address (× $400)
+        const nameBase = ((regs[2] >> 1) & 0x07) * 0x400;
+        // 32×24 tiles, 2 bytes each (lower = tile id 0-255 lo, upper = id-hi + attrs)
+        for (let row = 0; row < 24; row++) {
+          for (let col = 0; col < 32; col++) {
+            const o = nameBase + (row * 32 + col) * 2;
+            const tile = vram[o] | ((vram[o + 1] & 0x01) << 8);
+            bg.add(tile);
+          }
+        }
+        // SAT base from reg 5; SMS sprites use one byte per entry as tile id
+        // (entries 0x80..0xFF are y-pos terminator).
+        const satBase = (regs[5] & 0x7E) * 0x80;
+        for (let i = 0; i < 64; i++) {
+          const y = vram[satBase + i];
+          if (y === 0xD0) break; // terminator
+          const tile = vram[satBase + 0x80 + i * 2 + 1];
+          sprite.add(tile);
+        }
+      } else if (p === "snes") {
+        // Sprites: always available from OAM. Use live OBSEL so the OBJ size
+        // (and thus renderable classification) is exact.
+        const oam = host.readMemory("snes_oam", 0, 544);
+        const fillram = host.readMemory("snes_fillram", 0, 0x8000);
+        const { decodeOAM, decodePpuRegs, ppuRegsPopulated, snesTilemapUsage } =
+          await import("../../platforms/snes/ppu.js");
+        const ppu = ppuRegsPopulated(fillram) ? decodePpuRegs(fillram) : null;
+        const sprites = decodeOAM(oam, ppu ? {
+          smallSize: ppu.objSize.small, largeSize: ppu.objSize.large,
+          objNameBaseByte: ppu.objNameBaseByte, objGapByte: ppu.objGapByte,
+        } : {});
+        for (const s of sprites) {
+          if (!s.renderable) continue;
+          sprite.add(s.tile);
+        }
+        // BG: use the caller's tilemap base if given, else auto-locate each
+        // enabled layer's BGxSC base from the live PPU registers.
+        const vram = host.readMemory("video_ram", 0, 0x10000);
+        if (snesTilemapBaseByte != null) {
+          const usage = snesTilemapUsage(vram, {
+            tilemapBaseByte: snesTilemapBaseByte,
+            mapWidth: snesMapWidth,
+            mapHeight: snesMapHeight,
+          });
+          for (const t of usage.used) bg.add(t);
+        } else if (ppu) {
+          for (let i = 0; i < 4; i++) {
+            if (!ppu.mainScreen[`bg${i + 1}`] && !ppu.subScreen[`bg${i + 1}`]) continue;
+            const layer = ppu.bg[i];
+            const usage = snesTilemapUsage(vram, {
+              tilemapBaseByte: layer.scBaseByte,
+              mapWidth: layer.mapWidth,
+              mapHeight: layer.mapHeight,
+            });
+            for (const t of usage.used) bg.add(t);
+          }
+        }
+      } else if (p === "genesis") {
+        const { genesisTileUsage } = await import("../../platforms/genesis/vdp.js");
+        const usage = genesisTileUsage(host);
+        for (const t of usage.planeA) bg.add(t);
+        for (const t of usage.planeB) bg.add(t);
+        for (const t of usage.sprites) sprite.add(t);
+      } else if (p === "c64") {
+        // C64 "tiles" are character codes in screen RAM. Resolve the screen
+        // RAM base: VIC bank (CIA2 port A bits 0-1, inverted) × $4000 plus
+        // the screen-RAM pointer in $D018 bits 4-7 (× $400). Then read the
+        // 40×25 = 1000 char codes from system_ram.
+        const { decodeViciiRegs } = await import("../../platforms/c64/vic.js");
+        const regs = host.readMemory("c64_vic_regs", 0, 0x2F);
+        const vic = decodeViciiRegs(regs);
+        const cia2 = host.readMemory("c64_cia2_regs", 0, 16);
+        const vicBank = (~cia2[0]) & 0x03;
+        const screenBase = vicBank * 0x4000 +
+          parseInt(vic.memPointers.screenRamBaseInVicBank.replace("$", ""), 16);
+        const screen = host.readMemory("system_ram", screenBase, 1000);
+        for (let i = 0; i < 1000; i++) bg.add(screen[i]);
+        // C64 sprites are MOBs (pointer-indexed pixel data), not char codes —
+        // they don't share the BG character set, so we leave `sprite` empty
+        // here. Use inspectSprites for the 8 hardware sprites.
+      } else {
+        throw new Error(`whichTilesAreRendered: platform '${p}' not yet supported.`);
+      }
+
+      const combined = new Set([...bg, ...sprite]);
+      return jsonContent({
+        platform: p,
+        background: summariseTileSet(bg),
+        sprite: summariseTileSet(sprite),
+        combined: summariseTileSet(combined),
+        note: "Sample at multiple game states (title / gameplay / menu) and diff the sets to map tile IDs → game assets.",
+      });
+    }),
+  );
+}

package/src/mcp/util.js

@@ -0,0 +1,85 @@
+// Small helpers for MCP tool responses.
+
+import { mkdirSync, writeFileSync } from "node:fs";
+import { dirname } from "node:path";
+
+// ── Large-output discipline: path-required-unless-inline ──────────
+// Every tool that can produce a large payload (ROM bytes, dumps, asm,
+// tile blobs, PNGs, big logs) follows ONE rule:
+//   • `inline` defaults to FALSE.
+//   • inline:false  → the caller MUST supply an output path. We write the
+//     payload there and return just { path, bytes }. No silent default
+//     location → nothing ever lands somewhere the user can't find / loses.
+//   • inline:true   → the payload comes back in the response, no path.
+// This keeps the common call cheap on context AND prevents the "my ROM
+// went to /tmp and got wiped" footgun — the agent must say where it goes.
+
+/**
+ * Enforce the path-or-inline contract and (when not inline) write to disk.
+ * Throws a clear error if neither `outputPath` nor `inline` was given.
+ * @param {Uint8Array|Buffer|string} data  the payload to persist when not inline
+ * @param {{ outputPath?: string, inline?: boolean, what?: string, encoding?: BufferEncoding }} opts
+ * @returns {{ path: string, bytes: number }} when written to disk
+ */
+export function writeOutput(data, { outputPath, inline = false, what = "output", encoding } = {}) {
+  if (inline) {
+    throw new Error("writeOutput called with inline:true — caller should return the payload inline instead of writing.");
+  }
+  if (!outputPath) {
+    throw new Error(
+      `No output path given for ${what}. Pass outputPath (absolute path / dir where it should be saved — ` +
+      `e.g. your project dir) or inline:true to get it back in the response.`,
+    );
+  }
+  const buf = typeof data === "string" ? Buffer.from(data, encoding ?? "utf8") : Buffer.from(data);
+  mkdirSync(dirname(outputPath), { recursive: true });
+  writeFileSync(outputPath, buf);
+  return { path: outputPath, bytes: buf.length };
+}
+
+/** Wrap a JSON object as an MCP tool text-content result. */
+export function jsonContent(obj) {
+  return {
+    content: [{ type: "text", text: JSON.stringify(obj, null, 2) }],
+  };
+}
+
+/** Wrap a plain string as an MCP tool text-content result. */
+export function textContent(text) {
+  return {
+    content: [{ type: "text", text }],
+  };
+}
+
+/** Build an image content block from a base64-encoded PNG. */
+export function imageContent(pngBase64) {
+  return {
+    type: "image",
+    data: pngBase64,
+    mimeType: "image/png",
+  };
+}
+
+/** Wrap an Error as a tool error result. */
+export function errorContent(err) {
+  return {
+    isError: true,
+    content: [{ type: "text", text: String(err?.message ?? err) }],
+  };
+}
+
+/**
+ * Wrap a tool implementation so any thrown error becomes a structured tool
+ * error rather than a transport-layer exception.
+ * @template T
+ * @param {(args: T) => Promise<any> | any} fn
+ */
+export function safeTool(fn) {
+  return async (args, extra) => {
+    try {
+      return await fn(args, extra);
+    } catch (err) {
+      return errorContent(err);
+    }
+  };
+}

package/src/observer/bus.js

@@ -0,0 +1,127 @@
+// observer/bus.js — process-singleton event emitter that taps every
+// MCP tool call (args, result, errors, embedded images) and ships them
+// to the /livestream socket.io server.
+//
+// Lazy-singleton pattern: import { observer } from this module wherever
+// you need to emit. Subscribers attach via observer.on('event', fn).
+//
+// Event shapes (always include sessionKey + ts):
+//
+//   {
+//     type: 'call',
+//     sessionKey, ts,
+//     tool: 'loadMedia',
+//     args: {...},
+//     durationMs: 123,
+//     ok: true,
+//     result: {...},        // ← jsonifiable; large strings/buffers summarized
+//     images: [             // ← extracted from result.content[]
+//       { kind: 'screenshot', pngBase64: '...' }
+//     ],
+//   }
+//
+//   {
+//     type: 'call',
+//     sessionKey, ts,
+//     tool: 'loadMedia',
+//     args: {...},
+//     durationMs: 5,
+//     ok: false,
+//     error: 'message',
+//   }
+//
+//   { type: 'session_connect',    sessionKey, ts }
+//   { type: 'session_disconnect', sessionKey, ts }
+//
+// The bus also keeps an in-memory ring buffer of the last N events
+// (across all sessions) so livestream clients connecting mid-session
+// get a replay of recent activity.
+
+import { EventEmitter } from "node:events";
+
+const RING_SIZE = 200;
+
+class ObserverBus extends EventEmitter {
+  constructor() {
+    super();
+    this.setMaxListeners(50);
+    /** @type {Array<object>} */
+    this.ring = [];
+    /** @type {Set<string>} active sessionKeys */
+    this.sessions = new Set();
+  }
+
+  push(event) {
+    this.ring.push(event);
+    if (this.ring.length > RING_SIZE) this.ring.shift();
+    this.emit("event", event);
+  }
+
+  /** Snapshot the ring (newest-last) for replay to a new subscriber. */
+  replay() {
+    return [...this.ring];
+  }
+
+  /** List active session keys. */
+  activeSessions() {
+    return [...this.sessions];
+  }
+
+  sessionConnected(sessionKey) {
+    this.sessions.add(sessionKey);
+    this.push({ type: "session_connect", sessionKey, ts: Date.now() });
+  }
+
+  sessionDisconnected(sessionKey) {
+    this.sessions.delete(sessionKey);
+    this.push({ type: "session_disconnect", sessionKey, ts: Date.now() });
+  }
+}
+
+export const observer = new ObserverBus();
+
+/**
+ * Extract image payloads from an MCP tool result. MCP tool results have
+ * `content: [{type:'text'|'image', ...}]`. We pull out images so the UI
+ * can display them inline without parsing the full result.
+ */
+export function extractImages(result) {
+  if (!result || !Array.isArray(result.content)) return [];
+  const out = [];
+  for (const c of result.content) {
+    if (c && c.type === "image" && typeof c.data === "string") {
+      out.push({
+        kind: "image",
+        mimeType: c.mimeType || "image/png",
+        base64: c.data,
+      });
+    }
+  }
+  return out;
+}
+
+/**
+ * Truncate long string property values inside a JSON-shaped result so the
+ * livestream log doesn't drown in 200 KB binary base64. Top-level
+ * property names always preserved. Strings >threshold are replaced
+ * with `<${size}B str>` placeholders. Recurses one level into objects;
+ * doesn't recurse into arrays of objects (keeps it fast).
+ */
+export function summarizeForLog(value, threshold = 200) {
+  if (value == null) return value;
+  if (typeof value === "string") {
+    return value.length > threshold ? `<${value.length}B str>` : value;
+  }
+  if (Array.isArray(value)) {
+    if (value.length > 50) return `[<${value.length} items>]`;
+    return value.map((v) => summarizeForLog(v, threshold));
+  }
+  if (typeof value === "object") {
+    const out = {};
+    for (const k of Object.keys(value)) {
+      out[k] = summarizeForLog(value[k], threshold);
+    }
+    return out;
+  }
+  return value;
+}