c64-debug-mcp 1.0.2 → 1.0.7

package/dist/http.cjs

@@ -152,9 +152,193 @@ var import_zod3 = require("zod");
 // src/schemas.ts
 var import_zod2 = require("zod");
 var warningSchema = warningItemSchema;
-var address16Schema = import_zod2.z.number().int().min(0).max(65535);
-var byteValueSchema = import_zod2.z.number().int().min(0).max(255).describe("Single raw byte value");
-var byteArraySchema = import_zod2.z.array(byteValueSchema).describe("Raw bytes as a JSON array");
+function parseAddress16(input) {
+  if (typeof input === "number") {
+    if (!Number.isInteger(input) || input < 0 || input > 65535) {
+      throw new import_zod2.z.ZodError([
+        {
+          code: "custom",
+          message: `Address must be an integer between 0 and 65535 (0xFFFF), got ${input}`,
+          path: []
+        }
+      ]);
+    }
+    return input;
+  }
+  if (typeof input !== "string") {
+    throw new import_zod2.z.ZodError([
+      {
+        code: "custom",
+        message: `Address must be a number or string, got ${typeof input}`,
+        path: []
+      }
+    ]);
+  }
+  const trimmed = input.trim();
+  let hexString;
+  let format;
+  if (trimmed.startsWith("$")) {
+    hexString = trimmed.slice(1);
+    format = "C64 hex ($)";
+  } else if (trimmed.toLowerCase().startsWith("0x")) {
+    hexString = trimmed.slice(2);
+    format = "C hex (0x)";
+  } else {
+    throw new import_zod2.z.ZodError([
+      {
+        code: "custom",
+        message: `Invalid address format: "${input}". Expected formats: decimal number (53248), hex with $ ($D000), or hex with 0x (0xD000). Bare hex not supported to avoid ambiguity.`,
+        path: []
+      }
+    ]);
+  }
+  if (!/^[0-9A-Fa-f]{1,4}$/.test(hexString)) {
+    throw new import_zod2.z.ZodError([
+      {
+        code: "custom",
+        message: `Invalid ${format} address: "${input}". Hex portion must be 1-4 hex digits (0-9, A-F)`,
+        path: []
+      }
+    ]);
+  }
+  const parsed = parseInt(hexString, 16);
+  if (isNaN(parsed) || parsed < 0 || parsed > 65535) {
+    throw new import_zod2.z.ZodError([
+      {
+        code: "custom",
+        message: `Address out of range: "${input}" (${parsed}). Must be 0x0000-0xFFFF (0-65535)`,
+        path: []
+      }
+    ]);
+  }
+  return parsed;
+}
+var address16Schema = import_zod2.z.preprocess(parseAddress16, import_zod2.z.number().int().min(0).max(65535)).describe("16-bit C64 address: decimal (53248) or hex string with prefix ($D000, 0xD000)");
+function parseByte(input) {
+  if (typeof input === "number") {
+    if (!Number.isInteger(input) || input < 0 || input > 255) {
+      throw new import_zod2.z.ZodError([
+        {
+          code: "custom",
+          message: `Byte value must be an integer between 0 and 255 (0xFF), got ${input}`,
+          path: []
+        }
+      ]);
+    }
+    return input;
+  }
+  if (typeof input !== "string") {
+    throw new import_zod2.z.ZodError([
+      {
+        code: "custom",
+        message: `Byte value must be a number or string, got ${typeof input}`,
+        path: []
+      }
+    ]);
+  }
+  const trimmed = input.trim();
+  if (trimmed.startsWith("$")) {
+    const hexString = trimmed.slice(1);
+    if (!/^[0-9A-Fa-f]{1,2}$/.test(hexString)) {
+      throw new import_zod2.z.ZodError([
+        {
+          code: "custom",
+          message: `Invalid C64 hex ($) byte value: "${input}". Hex portion must be 1-2 hex digits (0-9, A-F)`,
+          path: []
+        }
+      ]);
+    }
+    const parsed = parseInt(hexString, 16);
+    if (isNaN(parsed) || parsed < 0 || parsed > 255) {
+      throw new import_zod2.z.ZodError([
+        {
+          code: "custom",
+          message: `Byte value out of range: "${input}" (${parsed}). Must be 0x00-0xFF (0-255)`,
+          path: []
+        }
+      ]);
+    }
+    return parsed;
+  }
+  if (trimmed.toLowerCase().startsWith("0x")) {
+    const hexString = trimmed.slice(2);
+    if (!/^[0-9A-Fa-f]{1,2}$/.test(hexString)) {
+      throw new import_zod2.z.ZodError([
+        {
+          code: "custom",
+          message: `Invalid C hex (0x) byte value: "${input}". Hex portion must be 1-2 hex digits (0-9, A-F)`,
+          path: []
+        }
+      ]);
+    }
+    const parsed = parseInt(hexString, 16);
+    if (isNaN(parsed) || parsed < 0 || parsed > 255) {
+      throw new import_zod2.z.ZodError([
+        {
+          code: "custom",
+          message: `Byte value out of range: "${input}" (${parsed}). Must be 0x00-0xFF (0-255)`,
+          path: []
+        }
+      ]);
+    }
+    return parsed;
+  }
+  if (trimmed.startsWith("%")) {
+    const binString = trimmed.slice(1);
+    if (!/^[01]{1,8}$/.test(binString)) {
+      throw new import_zod2.z.ZodError([
+        {
+          code: "custom",
+          message: `Invalid C64 binary (%) byte value: "${input}". Binary portion must be 1-8 binary digits (0-1)`,
+          path: []
+        }
+      ]);
+    }
+    const parsed = parseInt(binString, 2);
+    if (isNaN(parsed) || parsed < 0 || parsed > 255) {
+      throw new import_zod2.z.ZodError([
+        {
+          code: "custom",
+          message: `Byte value out of range: "${input}" (${parsed}). Must be 0b00000000-0b11111111 (0-255)`,
+          path: []
+        }
+      ]);
+    }
+    return parsed;
+  }
+  if (trimmed.toLowerCase().startsWith("0b")) {
+    const binString = trimmed.slice(2);
+    if (!/^[01]{1,8}$/.test(binString)) {
+      throw new import_zod2.z.ZodError([
+        {
+          code: "custom",
+          message: `Invalid C binary (0b) byte value: "${input}". Binary portion must be 1-8 binary digits (0-1)`,
+          path: []
+        }
+      ]);
+    }
+    const parsed = parseInt(binString, 2);
+    if (isNaN(parsed) || parsed < 0 || parsed > 255) {
+      throw new import_zod2.z.ZodError([
+        {
+          code: "custom",
+          message: `Byte value out of range: "${input}" (${parsed}). Must be 0b00000000-0b11111111 (0-255)`,
+          path: []
+        }
+      ]);
+    }
+    return parsed;
+  }
+  throw new import_zod2.z.ZodError([
+    {
+      code: "custom",
+      message: `Invalid byte format: "${input}". Expected formats: decimal (255), hex with prefix ($FF, 0xFF), or binary with prefix (%11111111, 0b11111111). Bare hex/binary not supported to avoid ambiguity.`,
+      path: []
+    }
+  ]);
+}
+var byteValueSchema = import_zod2.z.preprocess(parseByte, import_zod2.z.number().int().min(0).max(255)).describe("8-bit byte value: decimal (255), hex with prefix ($FF, 0xFF), or binary with prefix (%11111111, 0b11111111)");
+var byteArraySchema = import_zod2.z.array(byteValueSchema).describe('Array of byte values in mixed formats: [255, "$FF", "%11111111", 42]');
 var c64RegisterValueSchema = import_zod2.z.object(
   Object.fromEntries(
     C64_REGISTER_DEFINITIONS.map((register) => [
@@ -391,10 +575,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":
@@ -425,14 +614,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) {
@@ -1550,6 +1746,10 @@ var ViceSession = class {
       this.#syncMonitorRuntimeState();
     });
   }
+  async getSessionState() {
+    await this.#ensureReady();
+    return this.snapshot();
+  }
   snapshot() {
     return {
       transportState: this.#transportState,
@@ -1786,6 +1986,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,
@@ -1964,7 +2175,6 @@ var ViceSession = class {
   async programLoad(options) {
     const filePath = import_node_path.default.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 {
@@ -2215,134 +2425,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();
@@ -2405,6 +2618,39 @@ var ViceSession = class {
       });
     }
   }
+  async #withAutoResumeForInput(commandName, operation) {
+    await this.#ensureReady();
+    this.#syncMonitorRuntimeState();
+    if (this.#executionState === "unknown") {
+      throw new ViceMcpError(
+        "emulator_state_unknown",
+        `${commandName} requires a known execution state (running or stopped)`,
+        "session_state",
+        false,
+        {
+          executionState: this.#executionState,
+          lastStopReason: this.#lastStopReason
+        }
+      );
+    }
+    const wasRunning = this.#executionState === "running";
+    const wasPaused = this.#explicitPauseActive;
+    if (this.#executionState === "stopped") {
+      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;
@@ -2453,6 +2699,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));
@@ -2470,11 +2726,15 @@ var ViceSession = class {
     this.#lastRuntimeEventType = "unknown";
     this.#lastRuntimeProgramCounter = null;
     const env = await buildViceLaunchEnv();
+    let spawnError = void 0;
     const child = (0, import_node_child_process.spawn)(binary, args, {
       cwd: config.workingDirectory ? import_node_path.default.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);
@@ -2482,6 +2742,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();
@@ -2494,6 +2764,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;
@@ -3234,6 +3517,27 @@ function splitCommandLine(input) {
   }
   return result;
 }
+async function checkBinaryExists(binaryPath) {
+  if (import_node_path.default.isAbsolute(binaryPath)) {
+    try {
+      await import_promises.default.access(binaryPath, import_promises.default.constants.X_OK);
+      return { exists: true, path: binaryPath };
+    } catch {
+      return { exists: false };
+    }
+  }
+  const pathEnv = process.env.PATH || "";
+  const pathDirs = pathEnv.split(import_node_path.default.delimiter);
+  for (const dir of pathDirs) {
+    const fullPath = import_node_path.default.join(dir, binaryPath);
+    try {
+      await import_promises.default.access(fullPath, import_promises.default.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) {
@@ -3242,7 +3546,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
   });
@@ -3307,7 +3611,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",
@@ -3332,9 +3636,9 @@ var setRegistersTool = createViceTool({
 });
 var readMemoryTool = createViceTool({
   id: "memory_read",
-  description: "Reads a memory chunk by start address and length and returns raw bytes as a JSON array.",
+  description: "Reads a memory chunk by start address and length. Address can be decimal (53248) or hex string with prefix ($D000, 0xD000). Returns byte values as decimal numbers.",
   inputSchema: import_zod4.z.object({
-    address: address16Schema.describe("Start address in the 16-bit C64 address space"),
+    address: address16Schema.describe("Start address: decimal (53248) or hex string with prefix ($D000, 0xD000)"),
     length: import_zod4.z.number().int().positive().max(65535).describe("Size of the data chunk to read in bytes")
   }).refine((input) => input.address + input.length <= 65536, {
     message: "address + length must stay within the 64K address space",
@@ -3356,10 +3660,10 @@ var readMemoryTool = createViceTool({
 });
 var writeMemoryTool = createViceTool({
   id: "memory_write",
-  description: 'Writes raw byte values into the active C64 memory space. Requires emulator to be stopped - call execute(action="pause") first if running.',
+  description: "Writes raw byte values into C64 memory. Address and byte values support decimal, hex ($FF, 0xFF), and binary (%11111111, 0b11111111) formats. Requires emulator to be stopped.",
   inputSchema: import_zod4.z.object({
-    address: address16Schema.describe("Start address in the 16-bit C64 address space"),
-    data: byteArraySchema.min(1).describe("Raw bytes to write into memory")
+    address: address16Schema.describe("Start address: decimal (53248) or hex string with prefix ($D000, 0xD000)"),
+    data: byteArraySchema.min(1).describe("Bytes to write: decimal (255), hex ($FF, 0xFF), or binary (%11111111, 0b11111111). Mixed formats allowed.")
   }).refine((input) => input.address + input.data.length - 1 <= 65535, {
     message: "address + data.length must stay within the 16-bit address space",
     path: ["data"]
@@ -3373,7 +3677,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: import_zod4.z.object({
     action: import_zod4.z.enum(["pause", "resume", "step", "step_over", "step_out", "reset"]),
     count: import_zod4.z.number().int().positive().default(1).describe("Instruction count for step and step_over actions"),
@@ -3415,10 +3719,10 @@ var listBreakpointsTool = createViceTool({
 });
 var breakpointSetTool = createViceTool({
   id: "breakpoint_set",
-  description: "Creates an execution breakpoint or read/write watchpoint.",
+  description: "Creates an execution breakpoint or read/write watchpoint. Address can be decimal (53248) or hex string with prefix ($D000, 0xD000).",
   inputSchema: import_zod4.z.object({
     kind: breakpointKindSchema,
-    address: address16Schema.describe("Start address of the breakpoint range"),
+    address: address16Schema.describe("Start address: decimal (53248) or hex string with prefix ($D000, 0xD000)"),
     length: import_zod4.z.number().int().positive().default(1).describe("Size of the breakpoint range in bytes"),
     condition: import_zod4.z.string().optional(),
     label: import_zod4.z.string().optional(),
@@ -3495,7 +3799,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: import_zod4.z.object({
     text: import_zod4.z.string()
   }),
@@ -3507,7 +3811,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: import_zod4.z.object({
     action: inputActionSchema.describe("Use tap for a single key event or press/release for repeated buffered input"),
     keys: import_zod4.z.array(import_zod4.z.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"),
@@ -3518,7 +3822,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: import_zod4.z.object({
     port: joystickPortSchema.describe("Joystick port number"),
     action: inputActionSchema.describe("Joystick action to apply"),