romdev-mcp 0.1.1

package/src/observer/tool-wrap.js

@@ -0,0 +1,115 @@
+// observer/tool-wrap.js — install the observer middleware on an MCP
+// server instance. Monkey-patches `server.tool(name, desc, schema, handler)`
+// so every registered tool's handler is wrapped to emit a `call` event
+// to the observer bus after it completes (success OR error).
+//
+// Idempotent per server instance — installs once, repeats are no-ops.
+
+import { observer, extractImages, summarizeForLog } from "./bus.js";
+
+const INSTALLED = Symbol.for("romdev.observer-installed");
+
+/**
+ * Install tool-call instrumentation on an MCP server.
+ *
+ * @param {object} server  McpServer instance
+ * @param {string} sessionKey  per-session key (already minted upstream)
+ */
+export function installObserverMiddleware(server, sessionKey) {
+  if (server[INSTALLED]) return;
+  server[INSTALLED] = true;
+
+  const originalTool = server.tool.bind(server);
+
+  server.tool = function wrappedTool(name, ...rest) {
+    // Last argument is the handler — replace it with our wrapper.
+    if (rest.length === 0) return originalTool(name, ...rest);
+    const handler = rest[rest.length - 1];
+    if (typeof handler !== "function") return originalTool(name, ...rest);
+
+    const wrappedHandler = async (args, extra) => {
+      const startedAt = Date.now();
+      let result;
+      let thrown;
+      try {
+        result = await handler(args, extra);
+      } catch (err) {
+        thrown = err;
+      }
+      const durationMs = Date.now() - startedAt;
+
+      // Build the event. We summarize args + result so the livestream
+      // log isn't dominated by base64 / huge source strings, but keep
+      // top-level property names intact.
+      const argsSummary = summarizeForLog(args);
+      let event;
+      if (thrown) {
+        event = {
+          type: "call",
+          sessionKey,
+          ts: startedAt,
+          tool: name,
+          args: argsSummary,
+          durationMs,
+          ok: false,
+          error: String(thrown?.message ?? thrown),
+        };
+      } else {
+        // Tool errors come back as { isError: true, content: [{type:'text',...}] }
+        // via safeTool. Capture those as ok:false too.
+        const isError = result?.isError === true;
+        // Tools that write images to disk instead of returning them inline
+        // (e.g. screenshot({path:...})) attach a `_observerImages` sideband
+        // so the livestream still sees the frame. Strip it before the
+        // agent-visible response is serialized.
+        const sidebandImages = Array.isArray(result?._observerImages)
+          ? result._observerImages
+          : [];
+        if (sidebandImages.length > 0 && result && typeof result === "object") {
+          delete result._observerImages;
+        }
+        // Same pattern for ANSI text (screenshotAscii). The livestream
+        // HTML renders it in a side pane so the human can see the
+        // (lossy) view the agent actually got.
+        let sidebandAnsi = null;
+        if (result && typeof result === "object" && typeof result._observerAnsi === "string") {
+          sidebandAnsi = result._observerAnsi;
+          delete result._observerAnsi;
+        }
+        const inlineImages = extractImages(result);
+        const images = inlineImages.length > 0 ? inlineImages : sidebandImages;
+        const resultSummary = summarizeForLog(result);
+        event = {
+          type: "call",
+          sessionKey,
+          ts: startedAt,
+          tool: name,
+          args: argsSummary,
+          durationMs,
+          ok: !isError,
+          result: resultSummary,
+          ...(images.length > 0 ? { images } : {}),
+          ...(sidebandAnsi ? { ansi: sidebandAnsi } : {}),
+          ...(isError ? { error: extractErrorText(result) } : {}),
+        };
+      }
+
+      // Fire-and-forget — emit is synchronous + we don't block the
+      // tool response on observer delivery.
+      try { observer.push(event); } catch { /* never let observer kill the tool */ }
+
+      if (thrown) throw thrown;
+      return result;
+    };
+
+    return originalTool(name, ...rest.slice(0, -1), wrappedHandler);
+  };
+}
+
+function extractErrorText(result) {
+  if (!result?.content) return "(unknown error)";
+  for (const c of result.content) {
+    if (c?.type === "text") return c.text;
+  }
+  return "(unknown error)";
+}

package/src/platforms/atari2600/MENTAL_MODEL.md

@@ -0,0 +1,185 @@
+# Atari 2600 / VCS — mental model
+
+One page. The 2600 is the most architecturally extreme console
+romdev supports. Read this twice before you write code.
+
+## The big idea
+
+**The 2600 has no frame buffer.** There's no VRAM. The TIA chip
+generates video signal one scanline at a time, and you — the
+6502 CPU — must reconfigure the TIA's graphics registers for each
+scanline you want to look different. This is called **"racing the
+beam."**
+
+If you forget to write the TIA for scanline 42, scanline 42 looks
+identical to scanline 41.
+
+## CPU memory map (6507 — a 6502 variant with fewer pins)
+
+```
+$0000-$003F   TIA write registers (graphics, audio, collision)
+$0030-$003D   TIA read registers (collision, input)
+$0080-$00FF   RIOT 128 bytes of RAM — that's ALL the RAM, 128 bytes
+$0280-$0297   RIOT I/O (joysticks, timer, console switches)
+$F000-$FFFF   ROM (4 KB — standard cart size; banks for larger)
+```
+
+**128 bytes of RAM**. Yes. Total. The stack lives here too ($FF
+down). Game state must fit in maybe 80 zero-page bytes.
+
+The 6507 has the same 6502 instruction set but only 13 address
+pins, so it can only address 8 KB. Bigger carts use bank-switching
+hot-spots inside the cart.
+
+## TIA — the graphics object zoo
+
+The TIA has 5 graphics objects and 1 playfield:
+
+```
+P0  player 0       8-pixel-wide bitmap, written to GRP0 ($1B)
+P1  player 1       8-pixel-wide bitmap, written to GRP1 ($1C)
+M0  missile 0      1-8-pixel-wide, shares P0's colour
+M1  missile 1      1-8-pixel-wide, shares P1's colour
+BL  ball           1-8-pixel-wide, shares playfield colour
+PF  playfield      20-pixel-wide pattern, optionally mirrored or
+                   repeated across the 160-pixel-wide screen
+```
+
+Per scanline, you choose which of these are on, what pattern they
+show, what colour they are, and where they're positioned.
+
+## Frame structure (NTSC)
+
+A 2600 NTSC frame is exactly **262 scanlines** in 4 phases:
+
+```
+3 scanlines   VSYNC      tell the TV "new frame coming"
+37 scanlines  VBLANK     game logic runs here — no rendering
+192 scanlines visible    the part the user sees — race the beam
+30 scanlines  overscan   more game logic; off-screen
+```
+
+Each scanline is exactly **76 CPU cycles** wide. You have to fit
+every per-line update into 76 cycles, or you'll be writing the
+TIA after the scanline started rendering — which produces
+mid-line artifacts (sometimes intentionally exploited).
+
+The canonical control flow:
+
+```asm
+MAIN:
+  ; VSYNC
+  LDA #2 ; STA VSYNC ; 3× STA WSYNC ; LDA #0 ; STA VSYNC
+
+  ; VBLANK — game logic
+  LDA #2 ; STA VBLANK
+  LDX #37 ; .vb: STA WSYNC ; DEX ; BNE .vb
+  ; ... move sprites, read input, update state ...
+  LDA #0 ; STA VBLANK
+
+  ; Visible — render scanline-by-scanline
+  LDY #192
+  .draw: STA WSYNC ; <write TIA for this line> ; DEY ; BNE .draw
+
+  ; Overscan
+  LDA #2 ; STA VBLANK
+  LDX #30 ; .os: STA WSYNC ; DEX ; BNE .os
+
+  JMP MAIN
+```
+
+## Positioning objects horizontally
+
+The TIA has NO X register. To set object X, you have to:
+
+1. Hit `WSYNC` (now at start of next scanline)
+2. Burn CPU cycles equal to the desired X position
+3. Write to `RESPx` (reset position 0/1/missile/ball)
+4. `STA HMOVE` later to apply fine adjustment
+
+Common pattern: a busy loop with known cycle count per iteration:
+
+```asm
+  STA WSYNC
+  LDX #15          ; X = X coord / 15 (rough)
+.delay:
+  DEX
+  BNE .delay
+  STA RESP0
+  STA HMOVE
+```
+
+This places P0 at roughly column `X * 15`. Fine X (sub-15 pixels)
+goes through `HMP0/HMP1/HMM0/HMM1/HMBL` followed by `HMOVE`.
+
+## Colour bytes (NTSC palette)
+
+128-entry palette: `HHHHLLLL` where H = hue (0..15) and L =
+luminance (0..15). The same palette as the 7800.
+
+```
+$00  greyscale (black at luma 0, white at luma 15)
+$0E  white
+$48  cyan
+$80  blue
+$C8  green
+$1C  yellow
+$46  orange
+```
+
+## Input
+
+```
+$280  SWCHA  joystick port A (both controllers; high nibble = P1)
+$282  SWCHB  console switches (reset, select, B/W, difficulty)
+$0C   INPT4  P1 fire button (active low, bit 7)
+$0D   INPT5  P2 fire button
+```
+
+Active low — invert after read. For SWCHA, bit 7 = P1 up, bit 6 =
+P1 down, bit 5 = P1 left, bit 4 = P1 right.
+
+## Audio
+
+Two voices, very simple:
+
+```
+$15  AUDC0   channel 0 wave shape (0..15 — 1=square, 6=pulse, etc.)
+$16  AUDC1   channel 1 wave shape
+$17  AUDF0   channel 0 frequency (0..31 — lower = higher pitch)
+$18  AUDF1   channel 1 frequency
+$19  AUDV0   channel 0 volume (0..15)
+$1A  AUDV1   channel 1 volume
+```
+
+Write once at trigger, the TIA holds the tone until you change it.
+
+## Collision detection
+
+The TIA tracks 15 pairwise collision flags in registers `$30-$37`.
+Each bit corresponds to "object A overlapped object B this frame."
+Read them, then write `CXCLR` ($2C) to clear for the next frame.
+
+E.g. P0 vs M1 collision is bit 6 of CXP0FB ($30).
+
+## Cartridge layout
+
+```
+$F000-$FFF9   game code + data
+$FFFA-$FFFB   NMI vector (unused on 2600)
+$FFFC-$FFFD   RESET vector  ← here's where the CPU starts
+$FFFE-$FFFF   IRQ vector (unused)
+```
+
+For 4 KB carts (the default), the cart is mirrored at `$F000-$FFFF`
+and `$1000-$1FFF`. Most games just `org $F000` and let the mirror
+take care of itself.
+
+## Build pipeline
+
+When you call `buildSource({platform:"atari2600", source: ...})`:
+
+1. dasm assembles the .asm directly to a flat 4 KB binary.
+2. The result is `.a26` — loadable in stella (`loadMedia`).
+
+There's no linker — dasm produces a complete cart in one pass.

package/src/platforms/atari2600/TROUBLESHOOTING.md

@@ -0,0 +1,155 @@
+# Atari 2600 / VCS — troubleshooting
+
+When something's broken. Read MENTAL_MODEL.md first
+(via `getPlatformDoc({platform:"atari2600", name:"mental_model"})`).
+
+## "Screen rolls / shimmers / wrong height"
+
+You wrote the wrong number of scanlines. NTSC is **EXACTLY** 262
+scanlines per frame, broken into 3 VSYNC + 37 VBLANK + 192 visible
++ 30 overscan. Any of those off by 1, and the TV's vertical sync
+drifts.
+
+Check:
+- Did your VSYNC block call `STA WSYNC` exactly 3 times?
+- Is your VBLANK loop `LDX #37` then `STA WSYNC ; DEX ; BNE .vb`?
+  (37 iterations of WSYNC = 37 scanlines.)
+- Same for the visible 192 and overscan 30.
+- Are there any extra `STA WSYNC` instructions hiding in your
+  game-logic code that pushes you past 262?
+
+Use the cycle counter from `stella -trace` (or our `stepFrames` +
+`getCPUState`) to verify your scanline count.
+
+## "Sprites are wider than expected"
+
+Two scanlines = one TIA pixel of vertical resolution at minimum,
+but the GRP0/GRP1 register stays valid until you change it. If you
+write GRP0 once and don't reset to 0 on the next line, the sprite
+"smears down" — extending to the bottom of the screen.
+
+The fix: explicitly write `STA GRP0` with 0 on every line where
+the player isn't drawn. Or write it ONCE for the scanlines you
+want, and zero AFTER:
+
+```asm
+  STA WSYNC
+  ; ... compute Y - P_Y ...
+  CMP #8           ; within sprite height?
+  BCS .blank
+  TAY
+  LDA SPRITE,Y
+  STA GRP0
+  JMP .next
+.blank:
+  LDA #0
+  STA GRP0
+.next:
+```
+
+## "Object X position is off / jittery"
+
+The X-position routine has cycle-count gotchas:
+
+1. **`STA RESP0` itself takes 3 cycles** — the actual reset happens
+   at cycle 3 of the instruction, not cycle 0. Fine X via HMP0 +
+   HMOVE compensates.
+2. **HMOVE itself takes 8 cycles to execute** and triggers a
+   "missing horizontal blank" — if HMOVE runs after pixel 56 of
+   the current scanline, the right-hand side of the next scanline
+   has 8 black pixels.
+3. **Your delay loop has variable cycle count** depending on
+   whether the branch crosses a page boundary.
+
+Use a known-good X-position routine like the one in
+`src/platforms/atari2600/lib/`. Don't roll your own unless you
+need pixel-perfect placement.
+
+## "Joystick reads as 'always pressed'"
+
+`SWCHA` is **active low**. Bit value `0` = pressed, `1` =
+released. You must INVERT before AND-masking:
+
+```asm
+LDA SWCHA
+EOR #$FF       ; or: ASL into carry, BCS = not pressed
+AND #$80       ; P1 up
+BEQ .not_up
+; ... move up ...
+```
+
+The `default.asm` template uses `ASL` + `BCS` which checks the
+high bit directly without explicit inversion — also valid, just
+different idiom.
+
+## "ROM works in stella but wrong on real hardware"
+
+Real 2600s are picky. Common gotchas:
+
+1. **Vector table not at $FFFC.** RESET must point to your code's
+   entry. `org $FFFA ; .word START ; .word START ; .word START`
+   is the canonical setup.
+2. **WSYNC timing assumes 76 cycles per scanline.** If you have
+   a code path that runs > 76 cycles between WSYNCs, that
+   scanline overflows and the next line is short. Real hardware
+   doesn't forgive this; stella sometimes does.
+3. **Page-crossing branches.** A taken branch that crosses a
+   page boundary takes 4 cycles instead of 3. Drift = scanline
+   misalignment.
+
+## "Music plays the wrong notes"
+
+AUDF0/AUDF1 frequency values are NOT Hz. They're divisor values
+where:
+
+```
+freq_hz = 30030 / (audf + 1)
+```
+
+(approx, for AUDC tone shape 4 — pure tone.)
+
+So `AUDF0 = 7` → ~3.75 kHz. Higher AUDF = lower pitch. Most
+tutorials list a lookup table; the bundled `lib/` directory has
+one.
+
+## "Game logic doesn't fit in VBLANK"
+
+37 scanlines × 76 cycles = ~2800 cycles for ALL game logic per
+frame. If you need more, you can:
+
+- Spread logic across vblank + overscan (37 + 30 = 67 lines = 5092
+  cycles).
+- Skip-frame logic that only runs every N frames.
+- Move expensive computation into the kernel's "idle" lines (the
+  ones where no rendering happens because sprites are off-screen).
+
+## "Building a sprite kernel for vertical movement is hard"
+
+It is. The 2600 has no scrolling, no tilemap, no Y register on
+the TIA. To move a sprite down, you must change which scanline
+GRP0 starts being non-zero on. The hello-style approach is:
+
+```asm
+LDY #192
+.draw:
+  STA WSYNC
+  TYA
+  SEC
+  SBC P_Y          ; how many lines past the player's top?
+  CMP #8           ; within sprite height?
+  BCS .blank
+  TAY
+  LDA SPRITE,Y     ; row Y of the sprite shape
+  STA GRP0
+  ...
+```
+
+This costs ~15 cycles per scanline (~20% of the 76-cycle budget).
+For multiple sprites at different Y, the cost multiplies. Real
+games use careful kernel layouts ("the 2600 way") to limit
+sprites to specific Y bands. See the `lib/player_kernel.asm`
+snippet for one approach.
+
+## "First build is slow but later ones are fast"
+
+Expected. dasm cold-load is ~500ms. Steady-state builds < 100ms.

package/src/platforms/atari2600/UPSTREAM_SOURCES.md

@@ -0,0 +1,49 @@
+# Atari 2600 — source you can read
+
+Trust hierarchy:
+
+1. **Bundled examples** (`examples/atari2600/templates/*.asm`).
+2. **Bundled runtime** — `src/platforms/atari2600/lib/*.asm`
+   (kernel_skeleton, player_kernel, playfield_kernel,
+   read_joystick, vectors).
+3. **Bundled cc65 atari2600 libsrc** (R58) at `src/platforms/
+   atari2600/lib/cc65-src/`. (Note: cc65 doesn't generate practical
+   2600 code; we use **dasm** for 2600. The cc65 libsrc here is the
+   small bit cc65 ships for 2600 — mostly reference, since real
+   2600 dev is asm.)
+4. **Upstream**:
+
+   | What | Upstream |
+   |---|---|
+   | dasm | https://dasm-assembler.github.io/ |
+   | stella2014 libretro core | https://github.com/libretro/stella2014-libretro |
+   | stella proper | https://stella-emu.github.io/ |
+
+## 2600 hardware docs
+
+- **Stella Programmer's Guide** (the canonical, by Steve Wright):
+  https://atariage.com/2600/programming/Stella_Programmers_Guide.pdf
+- **AtariAge 2600 programming**: https://atariage.com/forums/forum/50-atari-2600-programming/
+- **TIA reference**: https://www.qotile.net/files/2600_advanced_prog_guide.txt
+- **Atari Compendium**: http://www.cs.cmu.edu/~chuck/infopg/atari/c25.html
+
+## The race-the-beam model
+
+The 2600 has NO framebuffer. Every scanline is composed in real time
+by writing TIA registers as the beam scans. The CPU has ~76 cycles
+per scanline (~3 µs total) to (a) decide what's drawn on that line,
+(b) write the right TIA registers BEFORE the beam reaches each
+pixel column. Miss a cycle window → graphics glitch.
+
+The bundled `kernel_skeleton.asm` is the canonical "NTSC 3 vsync +
+37 vblank + 192 visible + 30 overscan" frame structure. Read it
+before writing anything.
+
+## When to use what
+
+- "How do I draw two sprites at different Y positions?" → Stella
+  Programmer's Guide § "Players" + `player_kernel.asm`
+- "TIA register layout" → `lib/vcs_constants.h` + Stella PG appendix
+- "Why does my joystick read drift?" → `read_joystick.asm` +
+  `SWCHA`/`SWCHB` docs in Stella PG
+- "dasm syntax" → dasm-assembler.github.io

package/src/platforms/atari2600/lib/README.md

@@ -0,0 +1,67 @@
+Atari 2600 starter snippets
+===========================
+
+Hand-vetted boilerplate for the dasm assembler (the standard 2600 toolchain).
+All snippets target the `processor 6502` directive and assume the cart is
+4 KB anchored at `$F000` (the most common arrangement; the 2600's "cart"
+mapping puts the file's last 4 KB at $F000-$FFFF and mirrors $1000-$1FFF
+on the address bus).
+
+For larger banked carts (8K F8, 16K F6, 32K F4) the same code can live in
+each bank, but each bank must end with the same vector table at $FFFA-$FFFF
+since only the currently-banked-in region's vectors are visible.
+
+COPY-PASTE templates, not linkable modules
+-------------------------------------------
+
+dasm builds a single flat 4 KB ROM. These snippets are meant to be
+**inlined** into your own source — copy the routines/tables you want
+into your `main.asm`. They do NOT carry `org` directives (except
+`kernel_skeleton.asm`, which IS the top-level ROM layout and owns
+`org $F000` + `org $FFFA`). If you `include` two snippets that each
+had their own `org`, dasm errors with "Origin Reverse-indexed"
+because their fixed addresses overlap your main code. So: treat
+each snippet's labelled routines + data tables as code you paste
+into place, not files you link together.
+
+Files
+-----
+
+- **vcs_constants.h** — TIA + RIOT register names + bit masks. `include` at top.
+- **kernel_skeleton.asm** — vsync + vblank + 192 visible scanline + overscan
+  template. THIS is your ROM's spine: it owns `org $F000` + `org $FFFA`.
+  Drop new logic into the `; --- per-frame logic here ---` slot.
+- **player_kernel.asm** — single-player ("p0") rendered against a solid
+  background. Shows the minimal GRP0 / WSYNC pattern + a real
+  `POS_OBJ_P0` horizontal-positioning macro (SBC-15 technique).
+- **playfield_kernel.asm** — asymmetric playfield drawn from a per-line
+  byte table — the foundation for level/map-style displays.
+- **score_kernel.asm** — 1-2 digit score band via PF1 in SCORE mode
+  (tens digit on the left half in P0 color, ones on the right in P1
+  color). Ships digit shapes 0-9 + SCORE_PREP (pointer build) +
+  SCORE_KERNEL_BAND (single-PF1-write composite render).
+- **read_joystick.asm** — read joystick 0 from SWCHA (RIOT $280) into a
+  zp byte. Top-of-file comment documents the "re-load A between bit
+  checks" pattern (the classic "left works, right doesn't" bug).
+- **vectors.asm** — the 6-byte tail at $FFFA. Reset goes to your `START`
+  label; NMI/IRQ are usually unused on the 2600 (BRK can fire IRQ).
+
+Toolchain
+---------
+
+Build via `buildSource({ platform: "atari2600", source: "..." })`. Server
+spawns `dasm` (bundled WASM) and emits a `.bin` ready for `loadRomFromPath`.
+
+Foot-guns
+---------
+
+1. **TIA register names overlap with RIOT.** `$00-$2C` is TIA; `$280-$297`
+   is RIOT (port I/O + timer). Don't write `$80` and expect SWCHA — use
+   the long form `STA SWCHA` (or `STA $280`).
+2. **WSYNC is a write-only signal**, not a delay loop. `STA WSYNC` blocks
+   the CPU until the next horizontal blank — exactly one scanline.
+3. **No frame buffer.** The TIA renders the screen line-by-line by reading
+   register state as the beam moves. Set a register late in a scanline →
+   it affects that line, not the next. This is "racing the beam."
+4. **Vectors mirror inside the bank.** $FFFC == $1FFC == $3FFC etc. Always
+   reference the absolute address.

package/src/platforms/atari2600/lib/cc65-src/crt0.s

@@ -0,0 +1,49 @@
+; Atari VCS 2600 startup code for cc65
+;
+; Florent Flament (contact@florentflament.com), 2017
+
+        .export         _exit
+        .export         __STARTUP__ : absolute = 1
+
+        .import         __RAM_START__, __RAM_SIZE__
+        .import         copydata
+        .import         _main
+
+        .include        "zeropage.inc"
+
+
+.segment "STARTUP"
+start:
+; Clear decimal mode
+        cld
+
+; Initialization Loop:
+; * Clears Atari 2600 whole memory (128 bytes) including BSS segment
+; * Clears TIA registers
+; * Sets system stack pointer to $ff (i.e top of zero-page)
+        ldx     #0
+        txa
+clearLoop:
+        dex
+        txs
+        pha
+        bne     clearLoop
+
+; Initialize data
+        jsr     copydata
+
+; Initialize C stack pointer
+        lda     #<(__RAM_START__ + __RAM_SIZE__)
+        ldx     #>(__RAM_START__ + __RAM_SIZE__)
+        sta     c_sp
+        stx     c_sp+1
+
+; Call main
+        jsr     _main
+_exit:  jmp     _exit
+
+
+.segment "VECTORS"
+.word   start                   ; NMI
+.word   start                   ; Reset
+.word   start                   ; IRQ

package/src/platforms/atari2600/lib/cc65-src/ctype.s

@@ -0,0 +1,5 @@
+; Character specification table.
+;
+; uses the "common" definition
+
+        .include "ctype_common.inc"