@henols/c64-re-tools 1.1.0 → 2.0.0-rc.3

package/src/mcp/tools/input.ts

@@ -0,0 +1,69 @@
+// Input tools: c64_keyboard and c64_joystick.
+
+import { z } from "zod";
+
+import { textToPetscii } from "../../c64.ts";
+import { WireFailure } from "../../protocol/messages.ts";
+import { JOYSTICK_DIRECTIONS, MAX_KEYBOARD_BYTES } from "../../protocol/vice.ts";
+import { defineTool } from "../server.ts";
+
+export const c64Keyboard = defineTool({
+  name: "c64_keyboard",
+  title: "Type on the C64 keyboard",
+  description:
+    `Type up to ${MAX_KEYBOARD_BYTES} keys into the C64 keyboard queue. The C64 reads them while it runs. ` +
+    "Only a program that reads keys through the KERNAL sees them. A program that reads the keyboard hardware directly does not see them. Many games do that. " +
+    'Mode text types text, for example "RUN\\n". Letters of either case type the normal (unshifted) key. A line break types RETURN. ' +
+    "Mode petscii types PETSCII codes 1 to 255 in bytes, for example [147] to clear the screen. " +
+    "This does not change the run state of the machine.",
+  inputSchema: z
+    .object({
+      mode: z.enum(["text", "petscii"]),
+      text: z.string().min(1).optional().describe("mode text: the text to type"),
+      bytes: z.array(z.number().int().min(1).max(255)).min(1).optional().describe("mode petscii: PETSCII codes to type"),
+    })
+    .strict(),
+  outputSchema: z.object({ queuedBytes: z.number().int().min(1).max(MAX_KEYBOARD_BYTES) }),
+  readOnly: false,
+  async run(input, session) {
+    let petscii: Uint8Array;
+    if (input.mode === "text") {
+      if (input.text === undefined || input.bytes !== undefined) throw new WireFailure("invalid-input", "Mode text takes text and no bytes.");
+      try {
+        petscii = textToPetscii(input.text);
+      } catch (error) {
+        throw new WireFailure("invalid-input", `${(error as Error).message}. Use mode petscii for other keys.`);
+      }
+    } else {
+      if (input.bytes === undefined || input.text !== undefined) throw new WireFailure("invalid-input", "Mode petscii takes bytes and no text.");
+      petscii = Uint8Array.from(input.bytes);
+    }
+    if (petscii.length > MAX_KEYBOARD_BYTES) {
+      throw new WireFailure("invalid-input", `The keyboard queue takes at most ${MAX_KEYBOARD_BYTES} keys at once. This input has ${petscii.length} keys.`);
+    }
+    return session.keyboard(petscii);
+  },
+});
+
+export const c64Joystick = defineTool({
+  name: "c64_joystick",
+  title: "Move a joystick",
+  description:
+    "Set the joystick in control port 1 or 2: a direction (or center) and the fire button. " +
+    "The C64 sees this state until you change it. To release the joystick, set direction center and fire false. " +
+    "Most games read port 2. This does not change the run state of the machine.",
+  inputSchema: z
+    .object({
+      port: z.union([z.literal(1), z.literal(2)]).describe("control port 1 or 2"),
+      direction: z.enum(JOYSTICK_DIRECTIONS),
+      fire: z.boolean().default(false),
+    })
+    .strict(),
+  outputSchema: z.object({ port: z.union([z.literal(1), z.literal(2)]), direction: z.enum(JOYSTICK_DIRECTIONS), fire: z.boolean() }),
+  readOnly: false,
+  async run(input, session) {
+    return session.joystick(input);
+  },
+});
+
+export const inputTools = [c64Keyboard, c64Joystick];

package/src/mcp/tools/machine.ts

@@ -0,0 +1,97 @@
+// Machine tools: c64_status, c64_reset, c64_warp and c64_window.
+
+import { z } from "zod";
+
+import { formatC64Address } from "../../c64.ts";
+import { VIDEO_STANDARDS } from "../../protocol/messages.ts";
+import { RESET_MODES, RUN_STATES, WINDOW_ACTIONS } from "../../protocol/vice.ts";
+import { AddressOutput, defineTool } from "../server.ts";
+
+export const c64Status = defineTool({
+  name: "c64_status",
+  title: "C64 status",
+  description:
+    "Get the state of the C64. The result tells if the CPU runs or has stopped, the video standard (pal or ntsc), " +
+    "and if warp mode is on. It also tells if the emulator window is open (window). " +
+    "When the CPU has stopped, the result also gives the program counter (pc).",
+  inputSchema: z.object({}).strict(),
+  outputSchema: z.object({
+    state: z.enum(RUN_STATES),
+    videoStandard: z.enum(VIDEO_STANDARDS),
+    warp: z.boolean(),
+    window: z.boolean().describe("true when the emulator window is open (c64_window)"),
+    pc: AddressOutput.optional().describe("program counter. Only when the CPU is stopped"),
+  }),
+  readOnly: true,
+  async run(_input, session) {
+    const status = await session.status();
+    return {
+      state: status.state,
+      videoStandard: status.videoStandard,
+      warp: status.warp,
+      window: status.window,
+      ...(status.pc === undefined ? {} : { pc: formatC64Address(status.pc) }),
+    };
+  },
+});
+
+export const c64Window = defineTool({
+  name: "c64_window",
+  title: "Emulator window",
+  description:
+    "Show the C64 in a window on the host, or hide it again. The emulator has no window until you open one. " +
+    "Open the window when the user must type, play or look at the C64. Then tell the user. Wait until the user tells you that they finished. " +
+    "Then close the window. The machine, the disk in drive 8, breakpoints, watchpoints, joysticks, warp mode and c64_timing go along. " +
+    "The run state of the machine does not change. The result names the data that does not go along (notCarried). " +
+    "If the user closes the window, the machine goes back to the state of when the window opened.",
+  inputSchema: z.object({ action: z.enum(WINDOW_ACTIONS).describe("open shows the window. close hides it") }).strict(),
+  outputSchema: z.object({
+    window: z.boolean().describe("true when the window is open"),
+    state: z.enum(RUN_STATES),
+    notCarried: z.array(z.string()).describe("emulator data that the move cleared. Empty when nothing moved"),
+  }),
+  readOnly: false,
+  async run(input, session) {
+    return session.window(input.action);
+  },
+});
+
+export const c64Reset = defineTool({
+  name: "c64_reset",
+  title: "Reset the C64",
+  description:
+    "Reset the C64. Mode soft is the reset button. Mode hard is a power cycle that also resets the disk drive. " +
+    "With run false (the default), the CPU stops at the first instruction of the reset routine, and the result gives that program counter (pc). " +
+    "With run true, the C64 starts normally. Breakpoints and watchpoints stay.",
+  inputSchema: z
+    .object({
+      mode: z.enum(RESET_MODES).describe("soft is the reset button. hard is a power cycle"),
+      run: z.boolean().default(false).describe("false stops at the reset routine. true lets the C64 start"),
+    })
+    .strict(),
+  outputSchema: z.object({
+    state: z.enum(RUN_STATES),
+    pc: AddressOutput.optional().describe("program counter. Only when run is false"),
+  }),
+  readOnly: false,
+  async run(input, session) {
+    const result = await session.reset(input);
+    return result.pc === undefined ? { state: result.state } : { state: result.state, pc: formatC64Address(result.pc) };
+  },
+});
+
+export const c64Warp = defineTool({
+  name: "c64_warp",
+  title: "Warp mode",
+  description:
+    "Turn warp mode on or off. In warp mode the C64 runs as fast as the host can run it. " +
+    "Warp mode does not change what the C64 does. This does not change the run state of the machine.",
+  inputSchema: z.object({ enabled: z.boolean().describe("true turns warp mode on") }).strict(),
+  outputSchema: z.object({ enabled: z.boolean() }),
+  readOnly: false,
+  async run(input, session) {
+    return session.warp(input.enabled);
+  },
+});
+
+export const machineTools = [c64Status, c64Reset, c64Warp, c64Window];

package/src/mcp/tools/media.ts

@@ -0,0 +1,106 @@
+// Media tools: c64_autostart, c64_program_load, c64_disk_attach and
+// c64_snapshot. Paths are project-relative; the host-client reads the file and
+// the Host Runtime receives only its bytes.
+
+import { z } from "zod";
+
+import { formatC64Address } from "../../c64.ts";
+import { AUTOSTART_TYPES, DISK_TYPES, MAX_SNAPSHOTS, RUN_STATES } from "../../protocol/vice.ts";
+import { AddressInput, AddressOutput, defineTool, requireFields, TransientName } from "../server.ts";
+
+const ProjectPath = z.string().min(1).describe("path relative to the project directory, for example build/game.prg");
+
+const list = (types: readonly string[]) => types.map((type) => `.${type}`).join(", ");
+
+export const c64Autostart = defineTool({
+  name: "c64_autostart",
+  title: "Autostart a program or image",
+  description:
+    `Start a program, or a disk, tape or cartridge image, from the project (${list(AUTOSTART_TYPES)}). ` +
+    "The C64 resets and loads the file. With run true (the default), it also runs the file. A disk image stays in drive 8. " +
+    "index selects a file on a disk image (default 0, the first file). " +
+    "The machine runs when this tool returns, and the load continues.",
+  inputSchema: z
+    .object({
+      path: ProjectPath,
+      index: z.number().int().min(0).max(0xffff).default(0).describe("file number on a disk image. 0 is the first file"),
+      run: z.boolean().default(true).describe("true runs the program after it loads"),
+    })
+    .strict(),
+  outputSchema: z.object({ state: z.enum(RUN_STATES) }),
+  readOnly: false,
+  async run(input, session) {
+    return session.autostart(input);
+  },
+});
+
+export const c64ProgramLoad = defineTool({
+  name: "c64_program_load",
+  title: "Load a PRG into memory",
+  description:
+    "Load a PRG file from the project into memory, with no reset and no start. The CPU stops and stays stopped. " +
+    "The bytes go where the CPU writes them. Without address, the program goes to the load address in its first two bytes. " +
+    "With address, it goes there instead.",
+  inputSchema: z
+    .object({
+      path: ProjectPath,
+      address: AddressInput.optional().describe("load here instead of at the file's own load address"),
+    })
+    .strict(),
+  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 result = await session.programLoad(input.address === undefined ? { path: input.path } : { path: input.path, address: input.address });
+    return { state: result.state, loadAddress: formatC64Address(result.loadAddress), size: result.size };
+  },
+});
+
+export const c64DiskAttach = defineTool({
+  name: "c64_disk_attach",
+  title: "Attach a disk image",
+  description:
+    `Put a disk image from the project into drive 8 (${list(DISK_TYPES)}). ` +
+    "Nothing loads or runs. To load from the disk, type LOAD on the C64 or use c64_autostart. " +
+    "This does not change the run state of the machine.",
+  inputSchema: z.object({ path: ProjectPath }).strict(),
+  outputSchema: z.object({ attached: z.boolean() }),
+  readOnly: false,
+  async run(input, session) {
+    return session.diskAttach(input);
+  },
+});
+
+export const c64Snapshot = defineTool({
+  name: "c64_snapshot",
+  title: "Machine snapshots",
+  description:
+    "Save and restore the whole machine state, attached disks included. Action save keeps a snapshot under a name you choose. " +
+    "Action restore puts the machine back in that state and stops the CPU. The c64_timing stopwatch keeps its reading. " +
+    `Action list gives the names, and action discard removes one. A session keeps at most ${MAX_SNAPSHOTS} snapshots until it ends.`,
+  inputSchema: z
+    .object({
+      action: z.enum(["save", "restore", "list", "discard"]),
+      name: TransientName.optional().describe("save, restore and discard: 1 to 64 letters, digits, dots, underscores or hyphens"),
+    })
+    .strict(),
+  outputSchema: z.object({
+    saved: z.boolean().optional(),
+    name: z.string().optional(),
+    restored: z.boolean().optional(),
+    state: z.enum(RUN_STATES).optional(),
+    snapshots: z.array(z.string()).optional(),
+    discarded: z.boolean().optional(),
+  }),
+  readOnly: false,
+  async run(input, session) {
+    const { action, name } = input;
+    if (action === "list") {
+      requireFields(action, { name }, []);
+      return session.snapshot({ action });
+    }
+    requireFields(action, { name }, ["name"], ["name"]);
+    return session.snapshot({ action, name: name! });
+  },
+});
+
+export const mediaTools = [c64Autostart, c64ProgramLoad, c64DiskAttach, c64Snapshot];

package/src/mcp/tools/memory.ts

@@ -0,0 +1,203 @@
+// Memory and CPU tools: c64_memory_read, c64_memory_write, c64_memory_search,
+// c64_memory_compare, c64_registers and c64_disassemble.
+
+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 { AddressInput, AddressOutput, Byte, defineTool, HexData, HexDataInput, MemoryViewInput, requireFields, SpaceInput } from "../server.ts";
+
+export const c64MemoryRead = defineTool({
+  name: "c64_memory_read",
+  title: "Read C64 memory",
+  description:
+    `Read 1 to ${MAX_MEMORY_READ} bytes of memory, starting at an address. ` +
+    "The range must not go past $ffff. Use space drive8 to read the memory of the 1541 disk drive. " +
+    "This does not change the run state of the machine.",
+  inputSchema: z
+    .object({
+      address: AddressInput,
+      size: z.number().int().min(1).max(MAX_MEMORY_READ).describe(`number of bytes, 1 to ${MAX_MEMORY_READ}`),
+      space: SpaceInput,
+      view: MemoryViewInput,
+    })
+    .strict(),
+  outputSchema: z.object({ address: AddressOutput, size: z.number().int().min(1).max(MAX_MEMORY_READ), data: HexData }),
+  readOnly: true,
+  async run(input, session) {
+    const result = await session.memoryRead(input);
+    return { address: formatC64Address(result.address), size: result.data.length / 2, data: result.data };
+  },
+});
+
+export const c64MemoryWrite = defineTool({
+  name: "c64_memory_write",
+  title: "Write C64 memory",
+  description:
+    `Write 1 to ${MAX_MEMORY_WRITE} bytes to memory, starting at an address. First stop the CPU with c64_execution action pause. ` +
+    "The range must not go past $ffff. With view cpu, the write goes where the CPU writes now. " +
+    "A write to a ROM address goes to the RAM under it, and a write to I/O goes to the chip. " +
+    "With view ram, the write goes to RAM (c64 only).",
+  inputSchema: z
+    .object({
+      address: AddressInput,
+      data: HexDataInput.describe("bytes as hex, two digits per byte, no separators, for example a9008d20d0"),
+      space: SpaceInput,
+      view: MemoryViewInput,
+    })
+    .strict(),
+  outputSchema: z.object({ address: AddressOutput, bytesWritten: z.number().int().min(1).max(MAX_MEMORY_WRITE) }),
+  readOnly: false,
+  async run(input, session) {
+    const result = await session.memoryWrite(input);
+    return { address: formatC64Address(result.address), bytesWritten: result.bytesWritten };
+  },
+});
+
+const Flags = z.object({
+  n: z.boolean(),
+  v: z.boolean(),
+  b: z.boolean(),
+  d: z.boolean(),
+  i: z.boolean(),
+  z: z.boolean(),
+  c: z.boolean(),
+});
+
+const RegisterValuesInput = z
+  .object({
+    pc: AddressInput.optional(),
+    a: Byte.optional(),
+    x: Byte.optional(),
+    y: Byte.optional(),
+    sp: Byte.optional(),
+    flags: Flags.partial().strict().optional().describe("any of n, v, b, d, i, z and c. Flags that you do not name keep their value"),
+  })
+  .strict();
+
+export const c64Registers = defineTool({
+  name: "c64_registers",
+  title: "C64 CPU registers",
+  description:
+    "Get or set the CPU registers: pc, a, x, y, sp and the status flags n, v, b, d, i, z and c. " +
+    "Action get reads them. This does not change the run state of the machine. " +
+    "Action set writes the registers that values names and returns all registers. Stop the CPU before you use set. " +
+    "Use space drive8 for the CPU of the 1541 disk drive.",
+  inputSchema: z
+    .object({
+      action: z.enum(["get", "set"]),
+      space: SpaceInput,
+      values: RegisterValuesInput.optional().describe("set only: the registers to write"),
+    })
+    .strict(),
+  outputSchema: z.object({ pc: AddressOutput, a: Byte, x: Byte, y: Byte, sp: Byte, flags: Flags }),
+  readOnly: false,
+  async run(input, session) {
+    let registers;
+    if (input.action === "get") {
+      requireFields(input.action, { values: input.values }, []);
+      registers = await session.registersGet(input.space);
+    } else {
+      requireFields(input.action, { values: input.values }, ["values"], ["values"]);
+      const values: RegisterValues = {};
+      for (const key of ["pc", "a", "x", "y", "sp"] as const) {
+        const value = input.values?.[key];
+        if (value !== undefined) values[key] = value;
+      }
+      const flags = Object.fromEntries(Object.entries(input.values?.flags ?? {}).filter(([, value]) => value !== undefined));
+      if (Object.keys(flags).length > 0) values.flags = flags;
+      if (Object.keys(values).length === 0) {
+        throw new WireFailure("invalid-input", "values must name at least one register for action set.");
+      }
+      registers = await session.registersSet(input.space, values);
+    }
+    return { ...registers, pc: formatC64Address(registers.pc) };
+  },
+});
+
+/** "a9 ?? 8d 20 d0": hex bytes and ?? wildcards, separated by spaces. */
+const SearchPattern = z
+  .string()
+  .regex(/^\s*(?:[0-9a-fA-F]{2}|\?\?)(?:\s+(?:[0-9a-fA-F]{2}|\?\?))*\s*$/, "must be hex bytes and ?? wildcards separated by spaces, for example a9 ?? 8d")
+  .transform((value) => value.trim().split(/\s+/).map((token) => (token === "??" ? null : Number.parseInt(token, 16))))
+  .describe("hex bytes and ?? (any byte), separated by spaces, for example a9 ?? 8d 20 d0");
+
+export const c64MemorySearch = defineTool({
+  name: "c64_memory_search",
+  title: "Search C64 memory",
+  description:
+    `Find a byte pattern of 1 to ${MAX_SEARCH_PATTERN} bytes in memory from start to end. ?? matches any byte. ` +
+    `The result gives the start address of each match, at most maxResults (1 to ${MAX_SEARCH_RESULTS}, default 100). ` +
+    "This does not change the run state of the machine.",
+  inputSchema: z
+    .object({
+      start: AddressInput,
+      end: AddressInput.optional().describe("last address to search. Default $ffff"),
+      pattern: SearchPattern,
+      space: SpaceInput,
+      view: MemoryViewInput,
+      maxResults: z.number().int().min(1).max(MAX_SEARCH_RESULTS).default(100),
+    })
+    .strict(),
+  outputSchema: z.object({ matches: z.array(AddressOutput) }),
+  readOnly: true,
+  async run(input, session) {
+    if (input.pattern.length > MAX_SEARCH_PATTERN) {
+      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 });
+    return { matches: result.matches.map(formatC64Address) };
+  },
+});
+
+const Location = z
+  .object({ address: AddressInput, space: SpaceInput, view: MemoryViewInput })
+  .strict();
+
+export const c64MemoryCompare = defineTool({
+  name: "c64_memory_compare",
+  title: "Compare C64 memory",
+  description:
+    `Compare two memory ranges of size bytes (1 to ${MAX_COMPARE_SIZE}). Each range has its own address, space and view. ` +
+    `The result tells if they are equal, how many bytes differ, and the first ${MAX_COMPARE_DIFFERENCES} differences with their offset. ` +
+    "This does not change the run state of the machine.",
+  inputSchema: z
+    .object({ left: Location, right: Location, size: z.number().int().min(1).max(MAX_COMPARE_SIZE) })
+    .strict(),
+  outputSchema: z.object({
+    equal: z.boolean(),
+    differentBytes: z.number().int().min(0),
+    firstDifferences: z.array(z.object({ offset: z.number().int().min(0), left: Byte, right: Byte })),
+  }),
+  readOnly: true,
+  async run(input, session) {
+    return session.memoryCompare(input);
+  },
+});
+
+export const c64Disassemble = defineTool({
+  name: "c64_disassemble",
+  title: "Disassemble live C64 memory",
+  description:
+    `Disassemble count instructions (1 to ${MAX_DISASSEMBLE}) from an address, as the bytes are in the live machine now. ` +
+    "Use it to read code that a program changed or unpacked at run time. It includes the undocumented opcodes. " +
+    "This does not change the run state of the machine.",
+  inputSchema: z
+    .object({
+      address: AddressInput,
+      count: z.number().int().min(1).max(MAX_DISASSEMBLE),
+      space: SpaceInput,
+      view: MemoryViewInput,
+    })
+    .strict(),
+  outputSchema: z.object({ instructions: z.array(z.object({ address: AddressOutput, bytes: HexData, text: z.string() })) }),
+  readOnly: true,
+  async run(input, session) {
+    const result = await session.disassemble(input);
+    return { instructions: result.instructions.map((instruction) => ({ ...instruction, address: formatC64Address(instruction.address) })) };
+  },
+});
+
+export const memoryTools = [c64MemoryRead, c64MemoryWrite, c64MemorySearch, c64MemoryCompare, c64Registers, c64Disassemble];