c64bridge 1.0.0 → 1.0.2

package/mcp/schemas/c64_input.schema.json

@@ -57,7 +57,7 @@
     },
     "port": {
       "type": "integer",
-      "description": "Joystick port (1 = $DC01, 2 = $DC00).",
+      "description": "Joystick port (1 or 2).",
       "minimum": 1,
       "maximum": 2
     },
@@ -178,7 +178,7 @@
   "required": [
     "op"
   ],
-  "description": "Input operations: write_text, key, keyboard, joystick, release_all, state.\n\nOperations:\n- write_text: Send a text string to the keyboard buffer, with PETSCII token expansion. Required inputs: text. Optional inputs: delayMs.\n- key: Tap a single key or hold it for a duration. Required inputs: key. Optional inputs: durationMs, count.\n- joystick: Simulate joystick input. On C64U/U64 this uses machine:input (a C64U firmware version that provides it, or U64 3.15+); VICE writes CIA1 registers. Required inputs: port, controls, action. Optional inputs: durationMs.\n- keyboard: Send physical C64 keyboard matrix events through machine:input (a C64U firmware version that provides it, or U64 3.15+). Required inputs: inputs, transition.\n- release_all: Release every key and joystick control injected through machine:input (a C64U firmware version that provides it, or U64 3.15+). Required inputs: none.\n- state: Read the keys and joystick controls held through machine:input (a C64U firmware version that provides it, or U64 3.15+). Required inputs: none.",
+  "description": "Input operations: write_text, key, keyboard, joystick, release_all, state.\n\nOperations:\n- write_text: Send a text string to the keyboard buffer, with PETSCII token expansion. Required inputs: text. Optional inputs: delayMs.\n- key: Tap a single key or hold it for a duration. Required inputs: key. Optional inputs: durationMs, count.\n- joystick: Simulate joystick input. On C64U/U64 this uses machine:input; VICE uses Binary Monitor Joyport Set. Required inputs: port, controls, action. Optional inputs: durationMs.\n- keyboard: Send physical C64 keyboard matrix events through machine:input (a C64U firmware version that provides it, or U64 3.15+). Required inputs: inputs, transition.\n- release_all: Release every key and joystick control injected through machine:input (a C64U firmware version that provides it, or U64 3.15+). Required inputs: none.\n- state: Read the keys and joystick controls held through machine:input (a C64U firmware version that provides it, or U64 3.15+). Required inputs: none.",
   "additionalProperties": false,
   "x-c64bridge-operations": [
     {
@@ -274,7 +274,7 @@
     },
     {
       "op": "joystick",
-      "description": "Simulate joystick input. On C64U/U64 this uses machine:input (a C64U firmware version that provides it, or U64 3.15+); VICE writes CIA1 registers.",
+      "description": "Simulate joystick input. On C64U/U64 this uses machine:input; VICE uses Binary Monitor Joyport Set.",
       "required": [
         "port",
         "controls",
@@ -285,14 +285,14 @@
       ],
       "inputSchema": {
         "type": "object",
-        "description": "Simulate joystick input. On C64U/U64 this uses machine:input (a C64U firmware version that provides it, or U64 3.15+); VICE writes CIA1 registers.",
+        "description": "Simulate joystick input. On C64U/U64 this uses machine:input; VICE uses Binary Monitor Joyport Set.",
         "properties": {
           "op": {
             "const": "joystick"
           },
           "port": {
             "type": "integer",
-            "description": "Joystick port (1 = $DC01, 2 = $DC00).",
+            "description": "Joystick port (1 or 2).",
             "minimum": 1,
             "maximum": 2
           },

package/mcp/server.json

@@ -1,6 +1,6 @@
 {
   "name": "c64bridge",
-  "version": "1.0.0",
+  "version": "1.0.2",
   "description": "Stdio-based Model Context Protocol (MCP) server that bridges Commodore 64 Ultimate hardware with AI agents.",
   "transports": [
     "stdio"

package/mcp/tools.json

@@ -5668,7 +5668,8 @@
           "When defining characters, remind the user to send the BASIC program returned in the payload."
         ],
         "platforms": [
-          "c64u"
+          "c64u",
+          "u2"
         ]
       }
     },
@@ -8255,7 +8256,7 @@
           },
           "port": {
             "type": "integer",
-            "description": "Joystick port (1 = $DC01, 2 = $DC00).",
+            "description": "Joystick port (1 or 2).",
             "minimum": 1,
             "maximum": 2
           },
@@ -8376,7 +8377,7 @@
         "required": [
           "op"
         ],
-        "description": "Input operations: write_text, key, keyboard, joystick, release_all, state.\n\nOperations:\n- write_text: Send a text string to the keyboard buffer, with PETSCII token expansion. Required inputs: text. Optional inputs: delayMs.\n- key: Tap a single key or hold it for a duration. Required inputs: key. Optional inputs: durationMs, count.\n- joystick: Simulate joystick input. On C64U/U64 this uses machine:input (a C64U firmware version that provides it, or U64 3.15+); VICE writes CIA1 registers. Required inputs: port, controls, action. Optional inputs: durationMs.\n- keyboard: Send physical C64 keyboard matrix events through machine:input (a C64U firmware version that provides it, or U64 3.15+). Required inputs: inputs, transition.\n- release_all: Release every key and joystick control injected through machine:input (a C64U firmware version that provides it, or U64 3.15+). Required inputs: none.\n- state: Read the keys and joystick controls held through machine:input (a C64U firmware version that provides it, or U64 3.15+). Required inputs: none.",
+        "description": "Input operations: write_text, key, keyboard, joystick, release_all, state.\n\nOperations:\n- write_text: Send a text string to the keyboard buffer, with PETSCII token expansion. Required inputs: text. Optional inputs: delayMs.\n- key: Tap a single key or hold it for a duration. Required inputs: key. Optional inputs: durationMs, count.\n- joystick: Simulate joystick input. On C64U/U64 this uses machine:input; VICE uses Binary Monitor Joyport Set. Required inputs: port, controls, action. Optional inputs: durationMs.\n- keyboard: Send physical C64 keyboard matrix events through machine:input (a C64U firmware version that provides it, or U64 3.15+). Required inputs: inputs, transition.\n- release_all: Release every key and joystick control injected through machine:input (a C64U firmware version that provides it, or U64 3.15+). Required inputs: none.\n- state: Read the keys and joystick controls held through machine:input (a C64U firmware version that provides it, or U64 3.15+). Required inputs: none.",
         "additionalProperties": false,
         "x-c64bridge-operations": [
           {
@@ -8472,7 +8473,7 @@
           },
           {
             "op": "joystick",
-            "description": "Simulate joystick input. On C64U/U64 this uses machine:input (a C64U firmware version that provides it, or U64 3.15+); VICE writes CIA1 registers.",
+            "description": "Simulate joystick input. On C64U/U64 this uses machine:input; VICE uses Binary Monitor Joyport Set.",
             "required": [
               "port",
               "controls",
@@ -8483,14 +8484,14 @@
             ],
             "inputSchema": {
               "type": "object",
-              "description": "Simulate joystick input. On C64U/U64 this uses machine:input (a C64U firmware version that provides it, or U64 3.15+); VICE writes CIA1 registers.",
+              "description": "Simulate joystick input. On C64U/U64 this uses machine:input; VICE uses Binary Monitor Joyport Set.",
               "properties": {
                 "op": {
                   "const": "joystick"
                 },
                 "port": {
                   "type": "integer",
-                  "description": "Joystick port (1 = $DC01, 2 = $DC00).",
+                  "description": "Joystick port (1 or 2).",
                   "minimum": 1,
                   "maximum": 2
                 },

package/mcp.json

@@ -1,6 +1,6 @@
 {
   "name": "c64bridge",
-  "version": "1.0.0",
+  "version": "1.0.2",
   "description": "Stdio-based Model Context Protocol (MCP) server that bridges Commodore 64 Ultimate hardware with AI agents.",
   "entry": "dist/index.js",
   "type": "stdio",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "c64bridge",
-  "version": "1.0.0",
+  "version": "1.0.2",
   "mcpName": "io.github.chrisgleissner/c64bridge",
   "description": "C64 Bridge MCP server for Commodore 64 Ultimate hardware and VICE emulator control",
   "repository": {
@@ -68,10 +68,10 @@
     "node": ">=24"
   },
   "dependencies": {
-    "@modelcontextprotocol/sdk": "^1.29.0",
-    "axios": "^1.18.1",
+    "@modelcontextprotocol/sdk": "^1.30.0",
+    "axios": "^1.19.0",
     "date-fns": "^4.4.0",
-    "fastify": "^5.10.0",
+    "fastify": "^5.11.2",
     "jimp": "^1.6.1",
     "meyda": "^5.6.3",
     "octokit": "^5.0.5",
@@ -84,7 +84,7 @@
   },
   "devDependencies": {
     "@types/node": "^25.9.5",
-    "tsx": "^4.23.0",
+    "tsx": "^4.23.11",
     "typescript": "^6.0.3"
   },
   "files": [

package/scripts/mockC64Server.mjs

@@ -83,12 +83,18 @@ function sendJson(res, payload = {}, statusCode = 200) {
 function createInitialState() {
   return {
     networkPassword: null,
+    forcedErrors: null,
+    forcedErrorsUrlMatch: null,
+    hangOnMachineInputProbe: false,
     lastPrg: null,
+    lastLoadedPrg: null,
+    loadCount: 0,
     runCount: 0,
     resets: 0,
     reboots: 0,
   poweroffs: 0,
     memory: new Uint8Array(0x10000),
+    heartbeat: null,
     lastWrite: null,
     writeLog: [],
     lastRequest: null,
@@ -156,6 +162,82 @@ function toScreenCode(char) {
   return SCREEN_CODE_LOOKUP.get(char) ?? SCREEN_CODE_LOOKUP.get(" ") ?? 0x20;
 }
 
+const KERNAL_KEYBOARD_NDX_ADDRESS = 0x00c6;
+const KERNAL_KEYBOARD_BUFFER_ADDRESS = 0x0277;
+
+const SYS_COMMAND_PATTERN = /SYS\s*\d+/i;
+const HEARTBEAT_ADDRESS = 0x0400; // Screen-RAM byte the ASM liveness poller watches.
+const HEARTBEAT_GRANULARITY_MS = 10; // Well below the poll interval so consecutive liveness reads always differ.
+const HEARTBEAT_DURATION_MS = 1000; // How long a SYS-triggered program keeps "running".
+
+/**
+ * Nothing in this mock runs 6502 code to drain the KERNAL keyboard buffer
+ * itself, so a client polling NDX ($00C6) waiting for it to return to zero
+ * would otherwise hang forever. Simulate the KERNAL's IRQ-driven drain with
+ * a short delay so injectKeyboardQueue's poll loop behaves realistically.
+ *
+ * When the queued text looks like a typed `SYSnnnnn` command (the trigger
+ * upload_run_asm uses to enter an assembled program), also record a
+ * time-computed "alive" window (consumed by readMemoryWithHeartbeat). This
+ * mock never executes 6502 code, so a liveness poller watching screen RAM
+ * would otherwise see no progression. Recording a descriptor rather than
+ * mutating memory from a background timer is deliberate: nothing advances
+ * asynchronously, so an unrelated later test that merely shares this server
+ * instance can never observe a stray screen-RAM mutation.
+ */
+function simulateKeyboardDrain(state, address) {
+  if (address !== KERNAL_KEYBOARD_NDX_ADDRESS) return;
+  const pending = state.memory[KERNAL_KEYBOARD_NDX_ADDRESS] ?? 0;
+  const queued = pending > 0
+    ? Uint8Array.from(state.memory.subarray(KERNAL_KEYBOARD_BUFFER_ADDRESS, KERNAL_KEYBOARD_BUFFER_ADDRESS + pending))
+    : null;
+  setTimeout(() => {
+    state.memory[KERNAL_KEYBOARD_NDX_ADDRESS] = 0;
+    if (!queued) return;
+    const text = Buffer.from(queued).toString("ascii");
+    if (!SYS_COMMAND_PATTERN.test(text)) return;
+    state.heartbeat = {
+      address: HEARTBEAT_ADDRESS,
+      startedAt: Date.now(),
+      durationMs: HEARTBEAT_DURATION_MS,
+      baseValue: state.memory[HEARTBEAT_ADDRESS] ?? 0,
+    };
+  }, 5);
+}
+
+/**
+ * Serve a screen-RAM read, overlaying a synthetic, monotonically advancing
+ * byte at the heartbeat address while a SYS-triggered "alive" window is open.
+ * The overlay is a pure function of elapsed time applied only to the returned
+ * copy, so it never mutates stored memory and never advances on its own.
+ */
+function readMemoryWithHeartbeat(state, address, length) {
+  const bytes = state.memory.slice(address, address + length);
+  const heartbeat = state.heartbeat;
+  if (!heartbeat) return bytes;
+  const elapsed = Date.now() - heartbeat.startedAt;
+  if (elapsed < 0 || elapsed >= heartbeat.durationMs) return bytes;
+  const offset = heartbeat.address - address;
+  if (offset < 0 || offset >= bytes.length) return bytes;
+  const ticks = Math.floor(elapsed / HEARTBEAT_GRANULARITY_MS);
+  bytes[offset] = (heartbeat.baseValue + ticks) & 0xff;
+  return bytes;
+}
+
+/**
+ * Any explicit write covering the heartbeat address means a client has taken
+ * over screen RAM, so end the simulated "alive" window and let the real stored
+ * bytes show through again. This keeps a lingering heartbeat from corrupting a
+ * later writeMemory/readMemory round-trip in a shared-server test.
+ */
+function cancelHeartbeatOnWrite(state, address, length) {
+  const heartbeat = state.heartbeat;
+  if (!heartbeat) return;
+  if (address <= heartbeat.address && heartbeat.address < address + length) {
+    state.heartbeat = null;
+  }
+}
+
 function seedReadyPrompt(state) {
   const text = "READY.";
   const buffer = new Uint8Array(text.length + 1);
@@ -275,6 +357,20 @@ export async function startMockC64Server(options = {}) {
       return;
     }
 
+    // Test hook: simulate real firmware soft-failures, which answer HTTP 200
+    // with a non-empty `errors` array rather than a non-2xx status. Consumed
+    // once so a single forced failure does not leak into later requests.
+    if (state.forcedErrors && (!state.forcedErrorsUrlMatch || url.includes(state.forcedErrorsUrlMatch))) {
+      const errors = state.forcedErrors;
+      state.forcedErrors = null;
+      state.forcedErrorsUrlMatch = null;
+      // Drain any request body so an unread upload cannot corrupt a reused
+      // keep-alive connection's framing.
+      for await (const _chunk of req) { /* discard */ }
+      sendJson(res, { result: "error", errors });
+      return;
+    }
+
     if (method === "GET" && (url === "/" || url.startsWith("/?"))) {
       sendJson(res, { status: "ok", host: "mock" });
       return;
@@ -297,7 +393,10 @@ export async function startMockC64Server(options = {}) {
           enabled: driveState.power !== "off",
           power: driveState.power,
           mode: driveState.mode,
-          image: driveState.mountedImage,
+          // Mirror the real firmware's DriveInfo shape (image_path is a
+          // plain string), not the internal mount-params object.
+          image_path: driveState.mountedImage?.image ?? null,
+          type: driveState.mountedImage?.type ?? driveState.mode ?? null,
         };
       }
       sendJson(res, { drives });
@@ -340,6 +439,11 @@ export async function startMockC64Server(options = {}) {
     }
 
     if (method === "GET" && url === "/v1/machine:input") {
+      if (state.hangOnMachineInputProbe) {
+        // Test hook: never respond, to prove a caller cannot be blocked on
+        // this probe (HARD01-031). Deliberately does not call res.end().
+        return;
+      }
       sendJson(res, state.inputState);
       return;
     }
@@ -398,6 +502,27 @@ export async function startMockC64Server(options = {}) {
       return;
     }
 
+    if (method === "POST" && url === "/v1/runners:load_prg") {
+      const chunks = [];
+      for await (const chunk of req) {
+        chunks.push(chunk);
+      }
+
+      const prg = Buffer.concat(chunks);
+      state.lastLoadedPrg = prg;
+      state.loadCount += 1;
+
+      // Mirror real firmware: place the PRG body at its embedded load
+      // address without starting it (no RUN, no BASIC pointer changes).
+      if (prg.length >= 2) {
+        const loadAddress = prg.readUInt16LE(0);
+        state.memory.set(prg.subarray(2), loadAddress);
+      }
+
+      sendJson(res, { result: "ok", bytes: prg.length });
+      return;
+    }
+
     if (url.startsWith("/v1/runners:sidplay")) {
       let routeUrl;
       try {
@@ -471,7 +596,7 @@ export async function startMockC64Server(options = {}) {
       const lengthValue = routeUrl.searchParams.get("length") ?? "256";
       const address = parseNumeric(addressValue);
       const length = Math.max(0, parseNumeric(lengthValue, 10));
-      const bytes = state.memory.slice(address, address + length);
+      const bytes = readMemoryWithHeartbeat(state, address, length);
 
       const accept = String(req.headers["accept"] || "");
       if (accept.includes("application/octet-stream")) {
@@ -506,6 +631,8 @@ export async function startMockC64Server(options = {}) {
       state.memory.set(bytes, address);
       state.lastWrite = { address, bytes };
       state.writeLog.push({ address, bytes: Buffer.from(bytes) });
+      cancelHeartbeatOnWrite(state, address, bytes.length);
+      simulateKeyboardDrain(state, address);
 
       sendJson(res, { result: "wrote", address, length: bytes.length });
       return;
@@ -525,6 +652,8 @@ export async function startMockC64Server(options = {}) {
       state.memory.set(bytes, address);
       state.lastWrite = { address, bytes };
       state.writeLog.push({ address, bytes: Buffer.from(bytes) });
+      cancelHeartbeatOnWrite(state, address, bytes.length);
+      simulateKeyboardDrain(state, address);
 
       sendJson(res, { result: "wrote", address, length: bytes.length });
       return;

package/server.json

@@ -8,12 +8,12 @@
     "source": "github"
   },
   "websiteUrl": "https://github.com/chrisgleissner/c64bridge",
-  "version": "1.0.0",
+  "version": "1.0.2",
   "packages": [
     {
       "registryType": "npm",
       "identifier": "c64bridge",
-      "version": "1.0.0",
+      "version": "1.0.2",
       "transport": {
         "type": "stdio"
       },