@henols/c64-re-tools 2.1.0 → 2.1.1

package/src/mcp/tools/execution.ts

@@ -3,9 +3,10 @@
 import { z } from "zod";
 
 import { formatC64Address } from "../../c64.ts";
+import { isRefusal } from "../../errors.ts";
 import { EXECUTION_ACTIONS, MAX_EXECUTION_COUNT, MAX_HISTORY, MAX_TIMEOUT_FRAMES, POINT_STOP_REASONS, RUN_STATES, SPACES, STOP_REASONS, type RunTarget } from "../../protocol/vice.ts";
 import { Byte, SpaceInput, TOOL_INPUTS } from "../inputs.ts";
-import { AddressOutput, defineTool, toCondition, ToolOutput } from "../server.ts";
+import { AddressOutput, defineTool, toCondition, ToolOutput, type ViceSessionApi } from "../server.ts";
 import { c64Observe } from "./video.ts";
 
 export const c64Execution = defineTool({
@@ -19,6 +20,8 @@ export const c64Execution = defineTool({
     "advance-frames runs exactly count video frames (count is necessary). It stops at the same raster position, count frames later. " +
     "A breakpoint, a watchpoint or a JAM opcode can stop it before that. advancedFrames tells how many frames ran. " +
     "stopReason tells why it stopped: frames (all frames ran), breakpoint, watchpoint or jam. pointId gives the id of the breakpoint or watchpoint. " +
+    "space tells which CPU stopped: c64, or drive8 for a breakpoint or watchpoint in the disk drive. pc is the address in that space. " +
+    "A CPU that a JAM stopped runs again only after c64_reset, a snapshot restore or c64_autostart. " +
     "To wait for a breakpoint or watchpoint after resume, use advance-frames with a large count. " +
     "step, next, until-return and advance-frames first stop a running CPU. Use count only with step, next and advance-frames. " +
     "step, next and until-return work only in space c64. For the drive, use c64_run_until with an address in space drive8.",
@@ -42,6 +45,7 @@ export const c64Execution = defineTool({
     advancedFrames: z.number().int().min(0).max(MAX_EXECUTION_COUNT).optional().describe("frames advance-frames ran"),
     stopReason: z.enum(["frames", ...POINT_STOP_REASONS]).optional().describe("advance-frames: why it stopped"),
     pointId: z.number().int().min(1).optional().describe("the id of the breakpoint or watchpoint that stopped advance-frames"),
+    space: z.enum(SPACES).optional().describe("advance-frames: the CPU that stopped, c64 or drive8. pc is the address in that space"),
   }),
   readOnly: false,
   async run(input, session) {
@@ -54,6 +58,7 @@ export const c64Execution = defineTool({
       ...(result.advancedFrames === undefined ? {} : { advancedFrames: result.advancedFrames }),
       ...(result.stopReason === undefined ? {} : { stopReason: result.stopReason }),
       ...(result.pointId === undefined ? {} : { pointId: result.pointId }),
+      ...(result.space === undefined ? {} : { space: result.space }),
     };
   },
 });
@@ -93,6 +98,7 @@ export const c64RunUntil = defineTool({
     history: z
       .array(z.object({ address: AddressOutput, bytes: z.string(), text: z.string(), a: Byte, x: Byte, y: Byte, sp: Byte, rasterLine: z.number().int().min(0).optional(), rasterCycle: z.number().int().min(0).optional() }))
       .optional(),
+    historyMissing: z.string().optional().describe("why the result has no history, for example an old history after a JAM"),
   }),
   readOnly: false,
   async run(input, session) {
@@ -108,10 +114,7 @@ export const c64RunUntil = defineTool({
     }
     const result = await session.runUntil({ target, timeoutFrames: input.timeoutFrames });
     const answer = { ...result, pc: formatC64Address(result.pc) };
-    const history =
-      input.history === undefined
-        ? {}
-        : { history: (await session.cpuHistory({ limit: input.history, space: result.space })).entries.map((entry) => ({ ...entry, address: formatC64Address(entry.address) })) };
+    const history = input.history === undefined ? {} : await runHistory(session, input.history, result.space);
     if (input.observe === undefined) return { ...answer, ...history };
     // The observation at the stop: an image of the screen comes with the result as c64_observe gives it.
     const observed = await c64Observe.run(input.observe, session);
@@ -120,4 +123,14 @@ export const c64RunUntil = defineTool({
   },
 });
 
+/** The history at the stop; the run result stays when the session refuses the history. */
+async function runHistory(session: ViceSessionApi, limit: number, space: "c64" | "drive8") {
+  try {
+    return { history: (await session.cpuHistory({ limit, space })).entries.map((entry) => ({ ...entry, address: formatC64Address(entry.address) })) };
+  } catch (error) {
+    if (isRefusal(error) && error.code === "operation-failed") return { historyMissing: error.message };
+    throw error;
+  }
+}
+
 export const executionTools = [c64Execution, c64RunUntil];

package/src/mcp/tools/media.ts

@@ -2,14 +2,17 @@
 // c64_snapshot. Paths are relative to the project folder; the host-client
 // reads the file and the Host Runtime receives only its bytes.
 
+import { extname } from "node:path";
+
 import { z } from "zod";
 
 import { formatC64Address } from "../../c64.ts";
 import { projectFolder, readProjectFile } from "../../host-client/transfer.ts";
+import { WireFailure } from "../../protocol/messages.ts";
 import { AUTOSTART_TYPES, DISK_TYPES, MAX_SNAPSHOTS, RUN_STATES } from "../../protocol/vice.ts";
 import { OutInput, ProjectInput, writeOut, WrittenOutput } from "../output.ts";
 import { AddressInput } from "../inputs.ts";
-import { AddressOutput, defineTool, requireFields, TransientName } from "../server.ts";
+import { AddressOutput, defineTool, requireFields, requireOut, TransientName } from "../server.ts";
 
 const ProjectPath = z.string().min(1).describe("path relative to the project folder, for example build/game.prg");
 
@@ -63,6 +66,10 @@ export const c64ProgramLoad = defineTool({
   outputSchema: z.object({ state: z.enum(RUN_STATES), loadAddress: AddressOutput, size: z.number().int().min(1).max(0x10000) }),
   readOnly: false,
   async run(input, session) {
+    const type = extname(input.path).slice(1).toLowerCase();
+    if (type !== "prg" && (AUTOSTART_TYPES as readonly string[]).includes(type)) {
+      throw new WireFailure("invalid-input", `${input.path} is a .${type} image, not a PRG. Use c64_autostart, or c64_disk_attach for a disk image.`);
+    }
     const root = projectFolder(input.project);
     const result = await session.programLoad(input.address === undefined ? { path: input.path, root } : { path: input.path, address: input.address, root });
     return { state: result.state, loadAddress: formatC64Address(result.loadAddress), size: result.size };
@@ -118,12 +125,17 @@ export const c64Snapshot = defineTool({
       requireFields(action, fields, []);
       return session.snapshot({ action });
     }
+    if (action === "restore") {
+      if (fields.name !== undefined && fields.file !== undefined) throw new WireFailure("invalid-input", "Action restore takes name or file, not both.");
+      if (fields.name === undefined && fields.file === undefined) throw new WireFailure("invalid-input", "Action restore needs name (a snapshot of this session) or file (a .vsf in the project).");
+    }
     if (action === "restore" && fields.file !== undefined) {
       requireFields(action, fields, ["file", "project"], ["file"]);
       return session.snapshotRestore(readProjectFile(fields.file, { root: projectFolder(fields.project) }).bytes);
     }
     if (action === "save") {
-      requireFields(action, fields, fields.out === undefined ? ["name"] : ["name", "out", "project"], ["name"]);
+      requireOut(fields);
+      requireFields(action, fields, ["name", "out", "project"], ["name"]);
       const saved = await session.snapshot({ action, name: fields.name! });
       return fields.out === undefined ? saved : { ...saved, ...writeOut(fields.out, await session.snapshotExport(fields.name!), fields.project) };
     }

package/src/mcp/tools/memory.ts

@@ -6,7 +6,7 @@ import { z } from "zod";
 import { formatC64Address } from "../../c64.ts";
 import { WireFailure } from "../../protocol/messages.ts";
 import { MAX_COMPARE_DIFFERENCES, MAX_COMPARE_SIZE, MAX_DISASSEMBLE, MAX_MEMORY_READ, MAX_MEMORY_WRITE, MAX_SEARCH_PATTERN, MAX_SEARCH_RESULTS, type RegisterValues } from "../../protocol/vice.ts";
-import { OutInput, ProjectInput, writeOut, WrittenOutput } from "../output.ts";
+import { linesText, OutInput, ProjectInput, writeOut, WrittenOutput } from "../output.ts";
 import { AddressInput, Byte, MemoryViewInput, SpaceInput, TOOL_INPUTS } from "../inputs.ts";
 import { AddressOutput, defineTool, HexData, requireFields } from "../server.ts";
 
@@ -142,7 +142,11 @@ export const c64MemorySearch = defineTool({
       throw new WireFailure("invalid-input", `pattern has ${input.pattern.length} bytes. The limit is ${MAX_SEARCH_PATTERN}.`);
     }
     if (input.pattern.every((token) => token === null)) throw new WireFailure("invalid-input", "pattern needs at least one byte that is not ??.");
-    const result = await session.memorySearch({ ...input, end: input.end ?? 0xffff });
+    const end = input.end ?? 0xffff;
+    if (end < input.start) throw new WireFailure("invalid-input", "end is lower than start.");
+    // VICE refuses a range shorter than the pattern. Such a range has no match.
+    if (end - input.start + 1 < input.pattern.length) return { matches: [] };
+    const result = await session.memorySearch({ ...input, end });
     return { matches: result.matches.map(formatC64Address) };
   },
 });
@@ -220,7 +224,7 @@ export const c64Disassemble = defineTool({
         address = instruction.address + instruction.bytes.length / 2;
       }
     }
-    return { count: lines.length, ...writeOut(out, `${lines.join("\n")}\n`, project) };
+    return { count: lines.length, ...writeOut(out, linesText(lines), project) };
   },
 });
 

package/src/mcp/tools/video.ts

@@ -8,7 +8,7 @@ import { WireFailure } from "../../protocol/messages.ts";
 import { CIA_SELECTIONS, MAX_MASK_RECTANGLES, MAX_MEMORY_READ, MAX_OBSERVE_BYTES, MAX_OBSERVE_RANGES, SPACES, VICII_MODES, type ObserveParams } from "../../protocol/vice.ts";
 import { OutInput, ProjectInput, writeOut, WrittenOutput } from "../output.ts";
 import { AddressInput, Byte, MemoryViewInput, SpaceInput } from "../inputs.ts";
-import { AddressOutput, defineTool, HexData, requireFields, ToolOutput, TransientName } from "../server.ts";
+import { AddressOutput, defineTool, HexData, requireFields, requireOut, ToolOutput, TransientName } from "../server.ts";
 
 const Color = z.number().int().min(0).max(15);
 const NO_CHANGE = "This does not change the run state of the machine.";
@@ -170,14 +170,16 @@ export const c64Screen = defineTool({
   async run(input, session) {
     const { action, ...fields } = input;
     if (action === "capture") {
-      requireFields(action, fields, fields.out === undefined ? ["baseline"] : ["baseline", "out", "project"]);
+      requireOut(fields);
+      requireFields(action, fields, ["baseline", "out", "project"]);
       const shot = await session.screenCapture(fields.baseline);
       const result = { width: shot.width, height: shot.height, ...(shot.baseline === undefined ? {} : { baseline: shot.baseline }) };
       if (fields.out !== undefined) return { ...result, ...writeOut(fields.out, Buffer.from(shot.png, "base64"), fields.project) };
       return new ToolOutput(result, [{ type: "image", data: shot.png, mimeType: "image/png" }]);
     }
     if (action === "compare") {
-      requireFields(action, fields, ["baseline", "maxMismatchRatio", "mask", "includeDiff", ...(fields.out === undefined ? [] : ["out", "project"])], ["baseline"]);
+      requireOut(fields);
+      requireFields(action, fields, ["baseline", "maxMismatchRatio", "mask", "includeDiff", "out", "project"], ["baseline"]);
       const { diffPng, ...result } = await session.screenCompare({
         baseline: fields.baseline!,
         maxMismatchRatio: fields.maxMismatchRatio ?? 0,

package/src/project.ts

@@ -119,7 +119,7 @@ export function namedProject(folder: string, cwd: string = process.cwd()): strin
   if (path === homedir()) throw new Refusal("invalid-input", "The home folder is not a project folder.");
   const outer = foldersUpFrom(path).slice(1).find(isProject);
   if (outer !== undefined) {
-    throw new Refusal("invalid-input", `${folder} is inside the project ${relative(cwd, outer) || "."}. Give that project folder.`);
+    throw new Refusal("invalid-input", `${folder} is inside the project ${relative(cwd, outer) || outer}. Give that project folder.`);
   }
   return path;
 }

package/src/protocol/vice.ts

@@ -462,6 +462,8 @@ export interface ExecutionResult {
   stopReason?: "frames" | PointStopReason;
   /** The id of the breakpoint or watchpoint that stopped the run. */
   pointId?: number;
+  /** advance-frames only: the CPU that stopped, and so the space of pc. */
+  space?: "c64" | "drive8";
 }
 
 /** c64_run_until targets. */
@@ -1171,7 +1173,8 @@ export function validateViceResult<O extends ViceOperation>(op: O, value: unknow
         (value.executed === undefined || isInteger(value.executed, 0, MAX_EXECUTION_COUNT)) &&
         (value.advancedFrames === undefined || isInteger(value.advancedFrames, 0, MAX_EXECUTION_COUNT)) &&
         (value.stopReason === undefined || value.stopReason === "frames" || isOneOf(POINT_STOP_REASONS, value.stopReason)) &&
-        (value.pointId === undefined || isInteger(value.pointId, 1, Number.MAX_SAFE_INTEGER));
+        (value.pointId === undefined || isInteger(value.pointId, 1, Number.MAX_SAFE_INTEGER)) &&
+        (value.space === undefined || isOneOf(SPACES, value.space));
       if (!ok) throw new ProtocolError("execution result is malformed");
       break;
     }