c64-debug-mcp 1.0.0 → 1.0.2

package/dist/http.cjs

@@ -1370,6 +1370,8 @@ var DEFAULT_INPUT_TAP_MS = 75;
 var DEFAULT_KEYBOARD_REPEAT_MS = 100;
 var VICE_PROCESS_LOG_PATH = import_node_path.default.join(import_node_os.default.tmpdir(), "c64-debug-mcp-x64sc.log");
 var DISPLAY_CAPTURE_DIR = import_node_path.default.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;
@@ -1518,6 +1520,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}`);
@@ -1709,7 +1712,7 @@ var ViceSession = class {
     };
   }
   async readMemory(start, end, bank = 0) {
-    await this.#ensurePausedForDebug("memory_read");
+    await this.#ensureReady();
     this.#validateRange(start, end);
     const response = await this.#client.readMemory(start, end, bank);
     return {
@@ -3160,6 +3163,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 import_promises.default.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 = import_node_path.default.join(DISPLAY_CAPTURE_DIR, filename);
+          const stats = await import_promises.default.stat(filePath);
+          if (stats.mtime.getTime() < cutoffTime) {
+            await import_promises.default.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 = [];
@@ -3262,14 +3304,14 @@ var getMonitorStateTool = createViceTool({
 });
 var getSessionStateTool = createViceTool({
   id: "get_session_state",
-  description: "Returns richer emulator session state including transport/process status, auto-resume state, and the most recent hit checkpoint when known.",
+  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()
 });
 var getRegistersTool = createViceTool({
   id: "get_registers",
-  description: "Returns the current C64 register snapshot. This requires the emulator to already be stopped.",
+  description: 'Returns the current C64 register snapshot. Requires emulator to be stopped - call execute(action="pause") first if running.',
   inputSchema: noInputSchema,
   dataSchema: import_zod4.z.object({
     registers: c64RegisterValueSchema
@@ -3278,7 +3320,7 @@ var getRegistersTool = createViceTool({
 });
 var setRegistersTool = createViceTool({
   id: "set_registers",
-  description: "Sets one or more C64 registers by field name.",
+  description: 'Sets one or more C64 registers by field name. Requires emulator to be stopped - call execute(action="pause") first if running.',
   inputSchema: import_zod4.z.object({
     registers: c64PartialRegisterValueSchema
   }),
@@ -3314,7 +3356,7 @@ var readMemoryTool = createViceTool({
 });
 var writeMemoryTool = createViceTool({
   id: "memory_write",
-  description: "Writes raw byte values into the active C64 memory space.",
+  description: 'Writes raw byte values into the active C64 memory space. Requires emulator to be stopped - call execute(action="pause") first if running.',
   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")
@@ -3430,7 +3472,7 @@ var programLoadTool = createViceTool({
 });
 var captureDisplayTool = createViceTool({
   id: "capture_display",
-  description: "Captures the current screen to a PNG file and returns the saved image path. If the emulator was running, the server restores running state before returning, subject to timeout.",
+  description: "Captures the current screen to a PNG file and returns the saved image path.",
   inputSchema: import_zod4.z.object({
     useVic: import_zod4.z.boolean().default(true).describe("Whether to capture the VIC-II display when supported")
   }),
@@ -3439,21 +3481,21 @@ var captureDisplayTool = createViceTool({
 });
 var getDisplayStateTool = createViceTool({
   id: "get_display_state",
-  description: "Returns screen RAM, color RAM, the current graphics mode, screen memory addresses, and the current border and background colors. If the emulator was running, the server restores running state before returning, subject to timeout.",
+  description: "Returns screen RAM, color RAM, the current graphics mode, screen memory addresses, and the current border and background colors.",
   inputSchema: noInputSchema,
   dataSchema: displayStateResultSchema,
   execute: async () => await c64Session.getDisplayState()
 });
 var getDisplayTextTool = createViceTool({
   id: "get_display_text",
-  description: "Returns the current text screen as readable text when the C64 is in a text mode. If the emulator was running, the server restores running state before returning, subject to timeout.",
+  description: "Returns the current text screen as readable text when the C64 is in a text mode.",
   inputSchema: noInputSchema,
   dataSchema: displayTextResultSchema,
   execute: async () => await c64Session.getDisplayText()
 });
 var writeTextTool = createViceTool({
   id: "write_text",
-  description: "Types text into the C64 while it is running. Supports escaped characters and PETSCII brace tokens like {RETURN}, {CLR}, {HOME}, {PI}, and color names; limit each request to 64 bytes.",
+  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.',
   inputSchema: import_zod4.z.object({
     text: import_zod4.z.string()
   }),
@@ -3465,7 +3507,7 @@ var writeTextTool = createViceTool({
 });
 var keyboardInputTool = createViceTool({
   id: "keyboard_input",
-  description: "Sends one to four keys or PETSCII tokens to the C64 while it is running. Use this for key presses, releases, and taps. If the emulator transiently stops, the server restores running state before returning, subject to timeout.",
+  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.',
   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"),
@@ -3476,7 +3518,7 @@ var keyboardInputTool = createViceTool({
 });
 var joystickInputTool = createViceTool({
   id: "joystick_input",
-  description: "Sends joystick input to C64 joystick port 1 or 2 while the C64 is running. If the emulator transiently stops, the server restores running state before returning, subject to timeout.",
+  description: 'Sends joystick input to C64 joystick port 1 or 2. Requires emulator to be running - call execute(action="resume") first if stopped.',
   inputSchema: import_zod4.z.object({
     port: joystickPortSchema.describe("Joystick port number"),
     action: inputActionSchema.describe("Joystick action to apply"),

package/dist/http.js

@@ -1347,6 +1347,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 +1497,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}`);
@@ -1686,7 +1689,7 @@ var ViceSession = class {
     };
   }
   async readMemory(start, end, bank = 0) {
-    await this.#ensurePausedForDebug("memory_read");
+    await this.#ensureReady();
     this.#validateRange(start, end);
     const response = await this.#client.readMemory(start, end, bank);
     return {
@@ -3137,6 +3140,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 = [];
@@ -3239,14 +3281,14 @@ var getMonitorStateTool = createViceTool({
 });
 var getSessionStateTool = createViceTool({
   id: "get_session_state",
-  description: "Returns richer emulator session state including transport/process status, auto-resume state, and the most recent hit checkpoint when known.",
+  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()
 });
 var getRegistersTool = createViceTool({
   id: "get_registers",
-  description: "Returns the current C64 register snapshot. This requires the emulator to already be stopped.",
+  description: 'Returns the current C64 register snapshot. Requires emulator to be stopped - call execute(action="pause") first if running.',
   inputSchema: noInputSchema,
   dataSchema: z3.object({
     registers: c64RegisterValueSchema
@@ -3255,7 +3297,7 @@ var getRegistersTool = createViceTool({
 });
 var setRegistersTool = createViceTool({
   id: "set_registers",
-  description: "Sets one or more C64 registers by field name.",
+  description: 'Sets one or more C64 registers by field name. Requires emulator to be stopped - call execute(action="pause") first if running.',
   inputSchema: z3.object({
     registers: c64PartialRegisterValueSchema
   }),
@@ -3291,7 +3333,7 @@ var readMemoryTool = createViceTool({
 });
 var writeMemoryTool = createViceTool({
   id: "memory_write",
-  description: "Writes raw byte values into the active C64 memory space.",
+  description: 'Writes raw byte values into the active C64 memory space. Requires emulator to be stopped - call execute(action="pause") first if running.',
   inputSchema: z3.object({
     address: address16Schema.describe("Start address in the 16-bit C64 address space"),
     data: byteArraySchema.min(1).describe("Raw bytes to write into memory")
@@ -3407,7 +3449,7 @@ var programLoadTool = createViceTool({
 });
 var captureDisplayTool = createViceTool({
   id: "capture_display",
-  description: "Captures the current screen to a PNG file and returns the saved image path. If the emulator was running, the server restores running state before returning, subject to timeout.",
+  description: "Captures the current screen to a PNG file and returns the saved image path.",
   inputSchema: z3.object({
     useVic: z3.boolean().default(true).describe("Whether to capture the VIC-II display when supported")
   }),
@@ -3416,21 +3458,21 @@ var captureDisplayTool = createViceTool({
 });
 var getDisplayStateTool = createViceTool({
   id: "get_display_state",
-  description: "Returns screen RAM, color RAM, the current graphics mode, screen memory addresses, and the current border and background colors. If the emulator was running, the server restores running state before returning, subject to timeout.",
+  description: "Returns screen RAM, color RAM, the current graphics mode, screen memory addresses, and the current border and background colors.",
   inputSchema: noInputSchema,
   dataSchema: displayStateResultSchema,
   execute: async () => await c64Session.getDisplayState()
 });
 var getDisplayTextTool = createViceTool({
   id: "get_display_text",
-  description: "Returns the current text screen as readable text when the C64 is in a text mode. If the emulator was running, the server restores running state before returning, subject to timeout.",
+  description: "Returns the current text screen as readable text when the C64 is in a text mode.",
   inputSchema: noInputSchema,
   dataSchema: displayTextResultSchema,
   execute: async () => await c64Session.getDisplayText()
 });
 var writeTextTool = createViceTool({
   id: "write_text",
-  description: "Types text into the C64 while it is running. Supports escaped characters and PETSCII brace tokens like {RETURN}, {CLR}, {HOME}, {PI}, and color names; limit each request to 64 bytes.",
+  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.',
   inputSchema: z3.object({
     text: z3.string()
   }),
@@ -3442,7 +3484,7 @@ var writeTextTool = createViceTool({
 });
 var keyboardInputTool = createViceTool({
   id: "keyboard_input",
-  description: "Sends one to four keys or PETSCII tokens to the C64 while it is running. Use this for key presses, releases, and taps. If the emulator transiently stops, the server restores running state before returning, subject to timeout.",
+  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.',
   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 +3495,7 @@ var keyboardInputTool = createViceTool({
 });
 var joystickInputTool = createViceTool({
   id: "joystick_input",
-  description: "Sends joystick input to C64 joystick port 1 or 2 while the C64 is running. If the emulator transiently stops, the server restores running state before returning, subject to timeout.",
+  description: 'Sends joystick input to C64 joystick port 1 or 2. Requires emulator to be running - call execute(action="resume") first if stopped.',
   inputSchema: z3.object({
     port: joystickPortSchema.describe("Joystick port number"),
     action: inputActionSchema.describe("Joystick action to apply"),

package/dist/stdio.cjs

@@ -1367,6 +1367,8 @@ var DEFAULT_INPUT_TAP_MS = 75;
 var DEFAULT_KEYBOARD_REPEAT_MS = 100;
 var VICE_PROCESS_LOG_PATH = import_node_path.default.join(import_node_os.default.tmpdir(), "c64-debug-mcp-x64sc.log");
 var DISPLAY_CAPTURE_DIR = import_node_path.default.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;
@@ -1515,6 +1517,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}`);
@@ -1706,7 +1709,7 @@ var ViceSession = class {
     };
   }
   async readMemory(start, end, bank = 0) {
-    await this.#ensurePausedForDebug("memory_read");
+    await this.#ensureReady();
     this.#validateRange(start, end);
     const response = await this.#client.readMemory(start, end, bank);
     return {
@@ -3157,6 +3160,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 import_promises.default.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 = import_node_path.default.join(DISPLAY_CAPTURE_DIR, filename);
+          const stats = await import_promises.default.stat(filePath);
+          if (stats.mtime.getTime() < cutoffTime) {
+            await import_promises.default.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 = [];
@@ -3259,14 +3301,14 @@ var getMonitorStateTool = createViceTool({
 });
 var getSessionStateTool = createViceTool({
   id: "get_session_state",
-  description: "Returns richer emulator session state including transport/process status, auto-resume state, and the most recent hit checkpoint when known.",
+  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()
 });
 var getRegistersTool = createViceTool({
   id: "get_registers",
-  description: "Returns the current C64 register snapshot. This requires the emulator to already be stopped.",
+  description: 'Returns the current C64 register snapshot. Requires emulator to be stopped - call execute(action="pause") first if running.',
   inputSchema: noInputSchema,
   dataSchema: import_zod4.z.object({
     registers: c64RegisterValueSchema
@@ -3275,7 +3317,7 @@ var getRegistersTool = createViceTool({
 });
 var setRegistersTool = createViceTool({
   id: "set_registers",
-  description: "Sets one or more C64 registers by field name.",
+  description: 'Sets one or more C64 registers by field name. Requires emulator to be stopped - call execute(action="pause") first if running.',
   inputSchema: import_zod4.z.object({
     registers: c64PartialRegisterValueSchema
   }),
@@ -3311,7 +3353,7 @@ var readMemoryTool = createViceTool({
 });
 var writeMemoryTool = createViceTool({
   id: "memory_write",
-  description: "Writes raw byte values into the active C64 memory space.",
+  description: 'Writes raw byte values into the active C64 memory space. Requires emulator to be stopped - call execute(action="pause") first if running.',
   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")
@@ -3427,7 +3469,7 @@ var programLoadTool = createViceTool({
 });
 var captureDisplayTool = createViceTool({
   id: "capture_display",
-  description: "Captures the current screen to a PNG file and returns the saved image path. If the emulator was running, the server restores running state before returning, subject to timeout.",
+  description: "Captures the current screen to a PNG file and returns the saved image path.",
   inputSchema: import_zod4.z.object({
     useVic: import_zod4.z.boolean().default(true).describe("Whether to capture the VIC-II display when supported")
   }),
@@ -3436,21 +3478,21 @@ var captureDisplayTool = createViceTool({
 });
 var getDisplayStateTool = createViceTool({
   id: "get_display_state",
-  description: "Returns screen RAM, color RAM, the current graphics mode, screen memory addresses, and the current border and background colors. If the emulator was running, the server restores running state before returning, subject to timeout.",
+  description: "Returns screen RAM, color RAM, the current graphics mode, screen memory addresses, and the current border and background colors.",
   inputSchema: noInputSchema,
   dataSchema: displayStateResultSchema,
   execute: async () => await c64Session.getDisplayState()
 });
 var getDisplayTextTool = createViceTool({
   id: "get_display_text",
-  description: "Returns the current text screen as readable text when the C64 is in a text mode. If the emulator was running, the server restores running state before returning, subject to timeout.",
+  description: "Returns the current text screen as readable text when the C64 is in a text mode.",
   inputSchema: noInputSchema,
   dataSchema: displayTextResultSchema,
   execute: async () => await c64Session.getDisplayText()
 });
 var writeTextTool = createViceTool({
   id: "write_text",
-  description: "Types text into the C64 while it is running. Supports escaped characters and PETSCII brace tokens like {RETURN}, {CLR}, {HOME}, {PI}, and color names; limit each request to 64 bytes.",
+  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.',
   inputSchema: import_zod4.z.object({
     text: import_zod4.z.string()
   }),
@@ -3462,7 +3504,7 @@ var writeTextTool = createViceTool({
 });
 var keyboardInputTool = createViceTool({
   id: "keyboard_input",
-  description: "Sends one to four keys or PETSCII tokens to the C64 while it is running. Use this for key presses, releases, and taps. If the emulator transiently stops, the server restores running state before returning, subject to timeout.",
+  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.',
   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"),
@@ -3473,7 +3515,7 @@ var keyboardInputTool = createViceTool({
 });
 var joystickInputTool = createViceTool({
   id: "joystick_input",
-  description: "Sends joystick input to C64 joystick port 1 or 2 while the C64 is running. If the emulator transiently stops, the server restores running state before returning, subject to timeout.",
+  description: 'Sends joystick input to C64 joystick port 1 or 2. Requires emulator to be running - call execute(action="resume") first if stopped.',
   inputSchema: import_zod4.z.object({
     port: joystickPortSchema.describe("Joystick port number"),
     action: inputActionSchema.describe("Joystick action to apply"),

package/dist/stdio.js

@@ -1344,6 +1344,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;
@@ -1492,6 +1494,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}`);
@@ -1683,7 +1686,7 @@ var ViceSession = class {
     };
   }
   async readMemory(start, end, bank = 0) {
-    await this.#ensurePausedForDebug("memory_read");
+    await this.#ensureReady();
     this.#validateRange(start, end);
     const response = await this.#client.readMemory(start, end, bank);
     return {
@@ -3134,6 +3137,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 = [];
@@ -3236,14 +3278,14 @@ var getMonitorStateTool = createViceTool({
 });
 var getSessionStateTool = createViceTool({
   id: "get_session_state",
-  description: "Returns richer emulator session state including transport/process status, auto-resume state, and the most recent hit checkpoint when known.",
+  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()
 });
 var getRegistersTool = createViceTool({
   id: "get_registers",
-  description: "Returns the current C64 register snapshot. This requires the emulator to already be stopped.",
+  description: 'Returns the current C64 register snapshot. Requires emulator to be stopped - call execute(action="pause") first if running.',
   inputSchema: noInputSchema,
   dataSchema: z3.object({
     registers: c64RegisterValueSchema
@@ -3252,7 +3294,7 @@ var getRegistersTool = createViceTool({
 });
 var setRegistersTool = createViceTool({
   id: "set_registers",
-  description: "Sets one or more C64 registers by field name.",
+  description: 'Sets one or more C64 registers by field name. Requires emulator to be stopped - call execute(action="pause") first if running.',
   inputSchema: z3.object({
     registers: c64PartialRegisterValueSchema
   }),
@@ -3288,7 +3330,7 @@ var readMemoryTool = createViceTool({
 });
 var writeMemoryTool = createViceTool({
   id: "memory_write",
-  description: "Writes raw byte values into the active C64 memory space.",
+  description: 'Writes raw byte values into the active C64 memory space. Requires emulator to be stopped - call execute(action="pause") first if running.',
   inputSchema: z3.object({
     address: address16Schema.describe("Start address in the 16-bit C64 address space"),
     data: byteArraySchema.min(1).describe("Raw bytes to write into memory")
@@ -3404,7 +3446,7 @@ var programLoadTool = createViceTool({
 });
 var captureDisplayTool = createViceTool({
   id: "capture_display",
-  description: "Captures the current screen to a PNG file and returns the saved image path. If the emulator was running, the server restores running state before returning, subject to timeout.",
+  description: "Captures the current screen to a PNG file and returns the saved image path.",
   inputSchema: z3.object({
     useVic: z3.boolean().default(true).describe("Whether to capture the VIC-II display when supported")
   }),
@@ -3413,21 +3455,21 @@ var captureDisplayTool = createViceTool({
 });
 var getDisplayStateTool = createViceTool({
   id: "get_display_state",
-  description: "Returns screen RAM, color RAM, the current graphics mode, screen memory addresses, and the current border and background colors. If the emulator was running, the server restores running state before returning, subject to timeout.",
+  description: "Returns screen RAM, color RAM, the current graphics mode, screen memory addresses, and the current border and background colors.",
   inputSchema: noInputSchema,
   dataSchema: displayStateResultSchema,
   execute: async () => await c64Session.getDisplayState()
 });
 var getDisplayTextTool = createViceTool({
   id: "get_display_text",
-  description: "Returns the current text screen as readable text when the C64 is in a text mode. If the emulator was running, the server restores running state before returning, subject to timeout.",
+  description: "Returns the current text screen as readable text when the C64 is in a text mode.",
   inputSchema: noInputSchema,
   dataSchema: displayTextResultSchema,
   execute: async () => await c64Session.getDisplayText()
 });
 var writeTextTool = createViceTool({
   id: "write_text",
-  description: "Types text into the C64 while it is running. Supports escaped characters and PETSCII brace tokens like {RETURN}, {CLR}, {HOME}, {PI}, and color names; limit each request to 64 bytes.",
+  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.',
   inputSchema: z3.object({
     text: z3.string()
   }),
@@ -3439,7 +3481,7 @@ var writeTextTool = createViceTool({
 });
 var keyboardInputTool = createViceTool({
   id: "keyboard_input",
-  description: "Sends one to four keys or PETSCII tokens to the C64 while it is running. Use this for key presses, releases, and taps. If the emulator transiently stops, the server restores running state before returning, subject to timeout.",
+  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.',
   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"),
@@ -3450,7 +3492,7 @@ var keyboardInputTool = createViceTool({
 });
 var joystickInputTool = createViceTool({
   id: "joystick_input",
-  description: "Sends joystick input to C64 joystick port 1 or 2 while the C64 is running. If the emulator transiently stops, the server restores running state before returning, subject to timeout.",
+  description: 'Sends joystick input to C64 joystick port 1 or 2. Requires emulator to be running - call execute(action="resume") first if stopped.',
   inputSchema: z3.object({
     port: joystickPortSchema.describe("Joystick port number"),
     action: inputActionSchema.describe("Joystick action to apply"),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "c64-debug-mcp",
-  "version": "1.0.0",
+  "version": "1.0.2",
   "description": "Model Context Protocol server for C64 debugging via VICE emulator",
   "type": "module",
   "keywords": [