c64-debug-mcp 1.0.1 → 1.0.6

package/dist/http.js

@@ -368,10 +368,15 @@ function publicMessageFor(error) {
     case "program_file_missing":
     case "program_file_invalid":
       return error.message;
+    case "binary_not_found":
+    case "spawn_failed":
+    case "emulator_crashed_on_startup":
+      return error.message;
     case "port_allocation_failed":
     case "port_in_use":
-    case "monitor_timeout":
       return "The server could not start a usable emulator session. Check the emulator configuration and try again.";
+    case "monitor_timeout":
+      return error.message;
     case "not_connected":
     case "connection_closed":
     case "socket_write_failed":
@@ -402,14 +407,21 @@ function publicMessageFor(error) {
   }
 }
 function publicDetailsFor(error) {
-  switch (error.category) {
-    case "validation":
-    case "session_state":
-    case "unsupported":
-    case "io":
+  switch (error.code) {
+    case "binary_not_found":
+    case "spawn_failed":
+    case "emulator_crashed_on_startup":
       return error.details;
     default:
-      return void 0;
+      switch (error.category) {
+        case "validation":
+        case "session_state":
+        case "unsupported":
+        case "io":
+          return error.details;
+        default:
+          return void 0;
+      }
   }
 }
 function normalizeToolError(error) {
@@ -1347,6 +1359,8 @@ var DEFAULT_INPUT_TAP_MS = 75;
 var DEFAULT_KEYBOARD_REPEAT_MS = 100;
 var VICE_PROCESS_LOG_PATH = path.join(os.tmpdir(), "c64-debug-mcp-x64sc.log");
 var DISPLAY_CAPTURE_DIR = path.resolve(process.cwd(), ".vice-debug-mcp-artifacts");
+var CLEANUP_ENABLED = !/^(0|false|no|off)$/i.test(process.env.C64_CLEANUP_SCREENSHOTS ?? "");
+var CLEANUP_MAX_AGE_MINUTES = Number.parseInt(process.env.C64_CLEANUP_MAX_AGE_MINUTES ?? "20", 10);
 var MIRROR_EMULATOR_LOGS_TO_STDERR = /^(1|true|yes|on)$/i.test(process.env.C64_DEBUG_CONSOLE_LOGS ?? "");
 var EXECUTION_EVENT_WAIT_MS = 1e3;
 var EXECUTION_SETTLE_DELAY_MS = 2e3;
@@ -1495,6 +1509,7 @@ var ViceSession = class {
   #displayOperationLock = null;
   constructor(portAllocator = new PortAllocator()) {
     this.#portAllocator = portAllocator;
+    void this.#cleanupOldScreenshots();
     this.#client.on("response", (response) => {
       this.#lastResponseAt = nowIso();
       this.#writeProcessLogLine(`[monitor-response] type=${response.type} requestId=${response.requestId} errorCode=${response.errorCode}`);
@@ -1524,6 +1539,10 @@ var ViceSession = class {
       this.#syncMonitorRuntimeState();
     });
   }
+  async getSessionState() {
+    await this.#ensureReady();
+    return this.snapshot();
+  }
   snapshot() {
     return {
       transportState: this.#transportState,
@@ -1760,6 +1779,17 @@ var ViceSession = class {
   async continueExecution(waitUntilRunningStable = false) {
     return this.#withExecutionLock(async () => {
       await this.#ensureReady();
+      if (this.#executionState === "running") {
+        const runtime2 = this.#client.runtimeState();
+        const debugState2 = this.#lastRegisters == null ? await this.#readDebugState() : this.#buildDebugState(this.#lastRegisters);
+        return {
+          executionState: "running",
+          lastStopReason: this.#lastStopReason,
+          programCounter: runtime2.programCounter ?? debugState2.programCounter,
+          registers: debugState2.registers,
+          warnings: []
+        };
+      }
       if (this.#executionState !== "stopped") {
         debuggerNotPausedError("execute resume", {
           executionState: this.#executionState,
@@ -1938,7 +1968,6 @@ var ViceSession = class {
   async programLoad(options) {
     const filePath = path.resolve(options.filePath);
     await this.#assertReadableProgramFile(filePath);
-    await this.#ensureRunning("program_load");
     this.#explicitPauseActive = false;
     const result = await this.autostartProgram(filePath, options.autoStart ?? true, options.fileIndex ?? 0);
     return {
@@ -2189,134 +2218,137 @@ var ViceSession = class {
     }
   }
   async writeText(text) {
-    await this.#ensureRunning("write_text");
-    const encoded = decodeWriteTextToPetscii(text);
-    if (encoded.length > MAX_WRITE_TEXT_BYTES) {
-      validationError("write_text exceeds the maximum allowed byte length for one request", {
-        length: encoded.length,
-        max: MAX_WRITE_TEXT_BYTES
-      });
-    }
-    this.#writeProcessLogLine(`[tx] write_text length=${encoded.length} text=${JSON.stringify(text)}`);
-    await this.#client.sendKeys(Buffer.from(encoded).toString("binary"));
-    await this.#settleInputState("write_text", "running");
-    return {
-      sent: true,
-      length: encoded.length
-    };
+    return await this.#withAutoResumeForInput("write_text", async () => {
+      const encoded = decodeWriteTextToPetscii(text);
+      if (encoded.length > MAX_WRITE_TEXT_BYTES) {
+        validationError("write_text exceeds the maximum allowed byte length for one request", {
+          length: encoded.length,
+          max: MAX_WRITE_TEXT_BYTES
+        });
+      }
+      this.#writeProcessLogLine(`[tx] write_text length=${encoded.length} text=${JSON.stringify(text)}`);
+      await this.#client.sendKeys(Buffer.from(encoded).toString("binary"));
+      await this.#settleInputState("write_text", "running");
+      return {
+        sent: true,
+        length: encoded.length
+      };
+    });
   }
   async keyboardInput(action, keys, durationMs) {
-    await this.#ensureRunning("keyboard_input");
-    if (!Array.isArray(keys) || keys.length === 0 || keys.length > 4) {
-      validationError("keyboard_input requires between 1 and 4 keys", { keys });
-    }
-    const resolvedKeys = keys.map((key) => resolveKeyboardInputKey(key));
-    const normalizedKeys = resolvedKeys.map((key) => key.canonical);
-    this.#writeProcessLogLine(
-      `[tx] keyboard_input action=${action} keys=${normalizedKeys.join(",")}${durationMs == null ? "" : ` durationMs=${durationMs}`}`
-    );
-    switch (action) {
-      case "tap": {
-        const duration = clampTapDuration(durationMs);
-        const bytes = Uint8Array.from(resolvedKeys.flatMap((key) => Array.from(key.bytes)));
-        await this.#client.sendKeys(Buffer.from(bytes).toString("binary"));
-        await this.#settleInputState("keyboard_input", "running");
-        await sleep(duration);
-        return {
-          action,
-          keys: normalizedKeys,
-          applied: true,
-          held: false,
-          mode: "buffered_text"
-        };
+    return await this.#withAutoResumeForInput("keyboard_input", async () => {
+      if (!Array.isArray(keys) || keys.length === 0 || keys.length > 4) {
+        validationError("keyboard_input requires between 1 and 4 keys", { keys });
       }
-      case "press": {
-        const singleByteKeys = resolvedKeys.map((key) => {
-          if (key.bytes.length !== 1) {
-            unsupportedError("keyboard_input press/release only supports keys that map to a single PETSCII byte.", {
-              key: key.canonical
-            });
-          }
-          return key.bytes[0];
-        });
-        for (let index = 0; index < normalizedKeys.length; index += 1) {
-          const heldKey = normalizedKeys[index];
-          const byte = singleByteKeys[index];
-          if (!this.#heldKeyboardIntervals.has(heldKey)) {
-            await this.#client.sendKeys(Buffer.from([byte]).toString("binary"));
-            await this.#settleInputState("keyboard_input", "running");
-            const interval = setInterval(() => {
-              void this.#client.sendKeys(Buffer.from([byte]).toString("binary")).then(() => this.#settleInputState("keyboard_input", "running")).catch(() => void 0);
-            }, DEFAULT_KEYBOARD_REPEAT_MS);
-            this.#heldKeyboardIntervals.set(heldKey, interval);
-          }
+      const resolvedKeys = keys.map((key) => resolveKeyboardInputKey(key));
+      const normalizedKeys = resolvedKeys.map((key) => key.canonical);
+      this.#writeProcessLogLine(
+        `[tx] keyboard_input action=${action} keys=${normalizedKeys.join(",")}${durationMs == null ? "" : ` durationMs=${durationMs}`}`
+      );
+      switch (action) {
+        case "tap": {
+          const duration = clampTapDuration(durationMs);
+          const bytes = Uint8Array.from(resolvedKeys.flatMap((key) => Array.from(key.bytes)));
+          await this.#client.sendKeys(Buffer.from(bytes).toString("binary"));
+          await this.#settleInputState("keyboard_input", "running");
+          await sleep(duration);
+          return {
+            action,
+            keys: normalizedKeys,
+            applied: true,
+            held: false,
+            mode: "buffered_text"
+          };
         }
-        return {
-          action,
-          keys: normalizedKeys,
-          applied: true,
-          held: true,
-          mode: "buffered_text_repeat"
-        };
-      }
-      case "release": {
-        for (const key of resolvedKeys) {
-          if (key.bytes.length !== 1) {
-            unsupportedError("keyboard_input press/release only supports keys that map to a single PETSCII byte.", {
-              key: key.canonical
-            });
+        case "press": {
+          const singleByteKeys = resolvedKeys.map((key) => {
+            if (key.bytes.length !== 1) {
+              unsupportedError("keyboard_input press/release only supports keys that map to a single PETSCII byte.", {
+                key: key.canonical
+              });
+            }
+            return key.bytes[0];
+          });
+          for (let index = 0; index < normalizedKeys.length; index += 1) {
+            const heldKey = normalizedKeys[index];
+            const byte = singleByteKeys[index];
+            if (!this.#heldKeyboardIntervals.has(heldKey)) {
+              await this.#client.sendKeys(Buffer.from([byte]).toString("binary"));
+              await this.#settleInputState("keyboard_input", "running");
+              const interval = setInterval(() => {
+                void this.#client.sendKeys(Buffer.from([byte]).toString("binary")).then(() => this.#settleInputState("keyboard_input", "running")).catch(() => void 0);
+              }, DEFAULT_KEYBOARD_REPEAT_MS);
+              this.#heldKeyboardIntervals.set(heldKey, interval);
+            }
           }
+          return {
+            action,
+            keys: normalizedKeys,
+            applied: true,
+            held: true,
+            mode: "buffered_text_repeat"
+          };
         }
-        for (const heldKey of normalizedKeys) {
-          const interval = this.#heldKeyboardIntervals.get(heldKey);
-          if (interval) {
-            clearInterval(interval);
-            this.#heldKeyboardIntervals.delete(heldKey);
+        case "release": {
+          for (const key of resolvedKeys) {
+            if (key.bytes.length !== 1) {
+              unsupportedError("keyboard_input press/release only supports keys that map to a single PETSCII byte.", {
+                key: key.canonical
+              });
+            }
           }
+          for (const heldKey of normalizedKeys) {
+            const interval = this.#heldKeyboardIntervals.get(heldKey);
+            if (interval) {
+              clearInterval(interval);
+              this.#heldKeyboardIntervals.delete(heldKey);
+            }
+          }
+          return {
+            action,
+            keys: normalizedKeys,
+            applied: true,
+            held: false,
+            mode: "buffered_text_repeat"
+          };
         }
-        return {
-          action,
-          keys: normalizedKeys,
-          applied: true,
-          held: false,
-          mode: "buffered_text_repeat"
-        };
       }
-    }
+    });
   }
   async joystickInput(port2, action, control, durationMs) {
-    await this.#ensureRunning("joystick_input");
-    const previousExecutionState = this.#executionState;
-    const bit = JOYSTICK_CONTROL_BITS[control];
-    if (bit == null) {
-      validationError("Unsupported joystick control", { control });
-    }
-    this.#writeProcessLogLine(
-      `[tx] joystick_input port=${port2} action=${action} control=${control}${durationMs == null ? "" : ` durationMs=${durationMs}`}`
-    );
-    switch (action) {
-      case "tap": {
-        const duration = clampTapDuration(durationMs);
-        await this.#applyJoystickMask(port2, this.#getJoystickMask(port2) & ~bit);
-        await sleep(duration);
-        await this.#applyJoystickMask(port2, this.#getJoystickMask(port2) | bit);
-        break;
+    return await this.#withAutoResumeForInput("joystick_input", async () => {
+      const previousExecutionState = this.#executionState;
+      const bit = JOYSTICK_CONTROL_BITS[control];
+      if (bit == null) {
+        validationError("Unsupported joystick control", { control });
       }
-      case "press":
-        await this.#applyJoystickMask(port2, this.#getJoystickMask(port2) & ~bit);
-        break;
-      case "release":
-        await this.#applyJoystickMask(port2, this.#getJoystickMask(port2) | bit);
-        break;
-    }
-    await this.#settleInputState("joystick_input", previousExecutionState);
-    return {
-      port: port2,
-      action,
-      control,
-      applied: true,
-      state: this.#describeJoystickState(port2)
-    };
+      this.#writeProcessLogLine(
+        `[tx] joystick_input port=${port2} action=${action} control=${control}${durationMs == null ? "" : ` durationMs=${durationMs}`}`
+      );
+      switch (action) {
+        case "tap": {
+          const duration = clampTapDuration(durationMs);
+          await this.#applyJoystickMask(port2, this.#getJoystickMask(port2) & ~bit);
+          await sleep(duration);
+          await this.#applyJoystickMask(port2, this.#getJoystickMask(port2) | bit);
+          break;
+        }
+        case "press":
+          await this.#applyJoystickMask(port2, this.#getJoystickMask(port2) & ~bit);
+          break;
+        case "release":
+          await this.#applyJoystickMask(port2, this.#getJoystickMask(port2) | bit);
+          break;
+      }
+      await this.#settleInputState("joystick_input", previousExecutionState);
+      return {
+        port: port2,
+        action,
+        control,
+        applied: true,
+        state: this.#describeJoystickState(port2)
+      };
+    });
   }
   async waitForState(targetState, timeoutMs = 5e3, stableMs = targetState === "running" ? INPUT_RUNNING_STABLE_MS : 0) {
     await this.#ensureReady();
@@ -2379,6 +2411,27 @@ var ViceSession = class {
       });
     }
   }
+  async #withAutoResumeForInput(commandName, operation) {
+    await this.#ensureReady();
+    this.#syncMonitorRuntimeState();
+    const wasRunning = this.#executionState === "running";
+    const wasPaused = this.#explicitPauseActive;
+    if (!wasRunning) {
+      this.#writeProcessLogLine(`[${commandName}] auto-resuming for input operation`);
+      await this.#client.continueExecution();
+      await this.waitForState("running", 5e3, INPUT_RUNNING_STABLE_MS);
+    }
+    try {
+      return await operation();
+    } finally {
+      if (!wasRunning && wasPaused) {
+        this.#writeProcessLogLine(`[${commandName}] restoring paused state after input`);
+        await this.#client.ping();
+        await this.waitForState("stopped", 5e3, 0);
+        this.#explicitPauseActive = true;
+      }
+    }
+  }
   async #ensureHealthyConnection() {
     if (this.#recoveryPromise) {
       await this.#recoveryPromise;
@@ -2427,6 +2480,16 @@ var ViceSession = class {
     const port2 = await this.#portAllocator.allocate();
     await this.#portAllocator.ensureFree(port2, host2);
     const binary = config.binaryPath ?? DEFAULT_C64_BINARY;
+    const binaryCheck = await checkBinaryExists(binary);
+    if (!binaryCheck.exists) {
+      throw new ViceMcpError(
+        "binary_not_found",
+        `VICE emulator binary '${binary}' not found. Please install VICE or configure the correct path using the 'binaryPath' setting.`,
+        "process_launch",
+        false,
+        { binary, searchedPath: process.env.PATH }
+      );
+    }
     const args = ["-autostartprgmode", "1", "-binarymonitor", "-binarymonitoraddress", `${host2}:${port2}`];
     if (config.arguments) {
       args.push(...splitCommandLine(config.arguments));
@@ -2444,11 +2507,15 @@ var ViceSession = class {
     this.#lastRuntimeEventType = "unknown";
     this.#lastRuntimeProgramCounter = null;
     const env = await buildViceLaunchEnv();
+    let spawnError = void 0;
     const child = spawn(binary, args, {
       cwd: config.workingDirectory ? path.resolve(config.workingDirectory) : void 0,
       env,
       stdio: ["ignore", "pipe", "pipe"]
     });
+    child.once("error", (err) => {
+      spawnError = err;
+    });
     this.#process = child;
     this.#attachProcessLogging(child, binary, args);
     this.#bindProcessLifecycle(child);
@@ -2456,6 +2523,16 @@ var ViceSession = class {
     this.#transportState = "waiting_for_monitor";
     try {
       await waitForMonitor(host2, port2, 5e3);
+      if (spawnError !== void 0) {
+        const err = spawnError;
+        throw new ViceMcpError(
+          "spawn_failed",
+          `Failed to start VICE emulator '${binary}': ${err.message}`,
+          "process_launch",
+          false,
+          { binary, error: err.message, resolvedPath: binaryCheck.path }
+        );
+      }
       await this.#client.connect(host2, port2);
       this.#transportState = "connected";
       this.#connectedSince = nowIso();
@@ -2468,6 +2545,19 @@ var ViceSession = class {
     } catch (error) {
       this.#processState = "crashed";
       this.#transportState = "faulted";
+      if (error instanceof ViceMcpError && error.code === "monitor_timeout" && spawnError !== void 0) {
+        const err = spawnError;
+        const enhancedError = new ViceMcpError(
+          "emulator_crashed_on_startup",
+          `VICE emulator '${binary}' crashed during startup: ${err.message}`,
+          "process_launch",
+          false,
+          { binary, error: err.message, resolvedPath: binaryCheck.path }
+        );
+        this.#warnings = [...this.#warnings.filter((warning) => warning.code !== "launch_failed"), makeWarning(enhancedError.message, "launch_failed")];
+        await this.#stopManagedProcess(true);
+        throw enhancedError;
+      }
       this.#warnings = [...this.#warnings.filter((warning) => warning.code !== "launch_failed"), makeWarning(String(error.message ?? error), "launch_failed")];
       await this.#stopManagedProcess(true);
       throw error;
@@ -3137,6 +3227,45 @@ var ViceSession = class {
     }
     this.#syncMonitorRuntimeState();
   }
+  async #cleanupOldScreenshots() {
+    if (!CLEANUP_ENABLED) {
+      return;
+    }
+    try {
+      const maxAgeMinutes = Math.max(1, Math.min(525600, CLEANUP_MAX_AGE_MINUTES));
+      const maxAgeMs = maxAgeMinutes * 60 * 1e3;
+      const cutoffTime = Date.now() - maxAgeMs;
+      this.#writeProcessLogLine(`[cleanup] scanning ${DISPLAY_CAPTURE_DIR} for screenshots older than ${maxAgeMinutes}m`);
+      let entries;
+      try {
+        entries = await fs.readdir(DISPLAY_CAPTURE_DIR);
+      } catch (error) {
+        if (error.code === "ENOENT") {
+          return;
+        }
+        throw error;
+      }
+      const pngFiles = entries.filter((name) => name.endsWith(".png") && name.startsWith("capture-"));
+      let deletedCount = 0;
+      let errorCount = 0;
+      for (const filename of pngFiles) {
+        try {
+          const filePath = path.join(DISPLAY_CAPTURE_DIR, filename);
+          const stats = await fs.stat(filePath);
+          if (stats.mtime.getTime() < cutoffTime) {
+            await fs.unlink(filePath);
+            deletedCount++;
+          }
+        } catch (error) {
+          errorCount++;
+          this.#writeProcessLogLine(`[cleanup] failed to delete ${filename}: ${error instanceof Error ? error.message : String(error)}`);
+        }
+      }
+      this.#writeProcessLogLine(`[cleanup] completed: ${deletedCount} deleted, ${errorCount} errors, ${pngFiles.length - deletedCount - errorCount} retained`);
+    } catch (error) {
+      this.#writeProcessLogLine(`[cleanup] failed: ${error instanceof Error ? error.message : String(error)}`);
+    }
+  }
 };
 function splitCommandLine(input) {
   const result = [];
@@ -3169,6 +3298,27 @@ function splitCommandLine(input) {
   }
   return result;
 }
+async function checkBinaryExists(binaryPath) {
+  if (path.isAbsolute(binaryPath)) {
+    try {
+      await fs.access(binaryPath, fs.constants.X_OK);
+      return { exists: true, path: binaryPath };
+    } catch {
+      return { exists: false };
+    }
+  }
+  const pathEnv = process.env.PATH || "";
+  const pathDirs = pathEnv.split(path.delimiter);
+  for (const dir of pathDirs) {
+    const fullPath = path.join(dir, binaryPath);
+    try {
+      await fs.access(fullPath, fs.constants.X_OK);
+      return { exists: true, path: fullPath };
+    } catch {
+    }
+  }
+  return { exists: false };
+}
 async function waitForMonitor(host2, port2, timeoutMs) {
   const deadline = Date.now() + timeoutMs;
   while (Date.now() < deadline) {
@@ -3177,7 +3327,7 @@ async function waitForMonitor(host2, port2, timeoutMs) {
     }
     await sleep(100);
   }
-  throw new ViceMcpError("monitor_timeout", `Debugger monitor did not open on ${host2}:${port2}`, "timeout", true, {
+  throw new ViceMcpError("monitor_timeout", `Debugger monitor did not open on ${host2}:${port2}. The emulator may have failed to start or crashed during startup.`, "timeout", true, {
     host: host2,
     port: port2
   });
@@ -3242,7 +3392,7 @@ var getSessionStateTool = createViceTool({
   description: "Returns emulator session state including transport/process status, auto-resume state, and the most recent hit checkpoint.",
   inputSchema: noInputSchema,
   dataSchema: sessionStateResultSchema,
-  execute: async () => c64Session.snapshot()
+  execute: async () => await c64Session.getSessionState()
 });
 var getRegistersTool = createViceTool({
   id: "get_registers",
@@ -3308,7 +3458,7 @@ var writeMemoryTool = createViceTool({
 });
 var executeTool = createViceTool({
   id: "execute",
-  description: "Controls execution with pause, resume, step, step_over, step_out, or reset. Resume can optionally wait until running becomes stable.",
+  description: "Controls execution with pause, resume, step, step_over, step_out, or reset. Pause and resume are idempotent (safe to call multiple times).",
   inputSchema: z3.object({
     action: z3.enum(["pause", "resume", "step", "step_over", "step_out", "reset"]),
     count: z3.number().int().positive().default(1).describe("Instruction count for step and step_over actions"),
@@ -3430,7 +3580,7 @@ var getDisplayTextTool = createViceTool({
 });
 var writeTextTool = createViceTool({
   id: "write_text",
-  description: 'Types text into the C64. Requires emulator to be running - call execute(action="resume") first if stopped. Supports escaped characters and PETSCII brace tokens like {RETURN}, {CLR}, {HOME}, {PI}, and color names. Limit 64 bytes per request.',
+  description: "Types text into the C64. Automatically resumes if stopped and restores pause state after. Supports escaped characters and PETSCII brace tokens like {RETURN}, {CLR}, {HOME}, {PI}, and color names. Limit 64 bytes per request.",
   inputSchema: z3.object({
     text: z3.string()
   }),
@@ -3442,7 +3592,7 @@ var writeTextTool = createViceTool({
 });
 var keyboardInputTool = createViceTool({
   id: "keyboard_input",
-  description: 'Sends one to four keys or PETSCII tokens to the C64. Requires emulator to be running - call execute(action="resume") first if stopped. Use for key presses, releases, and taps.',
+  description: "Sends one to four keys or PETSCII tokens to the C64. Automatically resumes if stopped and restores pause state after. Use for key presses, releases, and taps.",
   inputSchema: z3.object({
     action: inputActionSchema.describe("Use tap for a single key event or press/release for repeated buffered input"),
     keys: z3.array(z3.string().min(1)).min(1).max(4).describe("One to four literal keys or PETSCII token names such as RETURN, CLR, HOME, PI, LEFT, RED, or F1"),
@@ -3453,7 +3603,7 @@ var keyboardInputTool = createViceTool({
 });
 var joystickInputTool = createViceTool({
   id: "joystick_input",
-  description: 'Sends joystick input to C64 joystick port 1 or 2. Requires emulator to be running - call execute(action="resume") first if stopped.',
+  description: "Sends joystick input to C64 joystick port 1 or 2. Automatically resumes if stopped and restores pause state after.",
   inputSchema: z3.object({
     port: joystickPortSchema.describe("Joystick port number"),
     action: inputActionSchema.describe("Joystick action to apply"),