@henols/c64-re-tools 2.0.0-rc.2 → 2.0.0-rc.21

package/src/mcp/tools/input.ts

@@ -7,15 +7,18 @@ import { WireFailure } from "../../protocol/messages.ts";
 import { JOYSTICK_DIRECTIONS, MAX_KEYBOARD_BYTES } from "../../protocol/vice.ts";
 import { defineTool } from "../server.ts";
 
+const EMULATOR_FLAW = z.string().optional().describe("a known flaw of the emulator version that affects input, and the version that fixes it");
+
 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. " +
+    "No command presses one key of the keyboard matrix: for one specific key, ask the user to press it in the window. " +
     '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.",
+    "This does not change the run state of the machine. emulatorFlaw in the result names a known flaw of the emulator version that affects input, and the version that fixes it.",
   inputSchema: z
     .object({
       mode: z.enum(["text", "petscii"]),
@@ -23,7 +26,7 @@ export const c64Keyboard = defineTool({
       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) }),
+  outputSchema: z.object({ queuedBytes: z.number().int().min(1).max(MAX_KEYBOARD_BYTES), emulatorFlaw: EMULATOR_FLAW }),
   readOnly: false,
   async run(input, session) {
     let petscii: Uint8Array;
@@ -51,7 +54,7 @@ export const c64Joystick = defineTool({
   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.",
+    "Most games read port 2. This does not change the run state of the machine. emulatorFlaw in the result names a known flaw of the emulator version that affects input, and the version that fixes it.",
   inputSchema: z
     .object({
       port: z.union([z.literal(1), z.literal(2)]).describe("control port 1 or 2"),
@@ -59,7 +62,7 @@ export const c64Joystick = defineTool({
       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() }),
+  outputSchema: z.object({ port: z.union([z.literal(1), z.literal(2)]), direction: z.enum(JOYSTICK_DIRECTIONS), fire: z.boolean(), emulatorFlaw: EMULATOR_FLAW }),
   readOnly: false,
   async run(input, session) {
     return session.joystick(input);

package/src/mcp/tools/machine.ts

@@ -3,8 +3,9 @@
 import { z } from "zod";
 
 import { formatC64Address } from "../../c64.ts";
+import { PACKAGE } from "../../package.ts";
 import { VIDEO_STANDARDS } from "../../protocol/messages.ts";
-import { RESET_MODES, RUN_STATES, WINDOW_ACTIONS } from "../../protocol/vice.ts";
+import { POINT_STOP_REASONS, RESET_MODES, RUN_STATES, WINDOW_ACTIONS } from "../../protocol/vice.ts";
 import { AddressOutput, defineTool } from "../server.ts";
 
 export const c64Status = defineTool({
@@ -13,7 +14,10 @@ export const c64Status = defineTool({
   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).",
+    "When the CPU has stopped, the result also gives the program counter (pc). " +
+    "When a breakpoint, a watchpoint or a JAM opcode stopped the CPU, stopReason tells which, and pointId gives the id of the breakpoint or watchpoint. " +
+    "cartridge is true while a cartridge from c64_autostart is attached: a reset keeps it, and an autostart of another file detaches it. " +
+    "version is the c64-re-tools version of this MCP server.",
   inputSchema: z.object({}).strict(),
   outputSchema: z.object({
     state: z.enum(RUN_STATES),
@@ -21,6 +25,10 @@ export const c64Status = defineTool({
     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"),
+    stopReason: z.enum(POINT_STOP_REASONS).optional().describe("what stopped the CPU. Only when a breakpoint, a watchpoint or a JAM opcode stopped it"),
+    pointId: z.number().int().min(1).optional().describe("the id of the breakpoint or watchpoint that stopped the CPU"),
+    cartridge: z.boolean().describe("true while a cartridge from c64_autostart is attached"),
+    version: z.string().describe("the c64-re-tools version of this MCP server"),
   }),
   readOnly: true,
   async run(_input, session) {
@@ -30,7 +38,11 @@ export const c64Status = defineTool({
       videoStandard: status.videoStandard,
       warp: status.warp,
       window: status.window,
+      cartridge: status.cartridge,
+      version: PACKAGE.version,
       ...(status.pc === undefined ? {} : { pc: formatC64Address(status.pc) }),
+      ...(status.stopReason === undefined ? {} : { stopReason: status.stopReason }),
+      ...(status.pointId === undefined ? {} : { pointId: status.pointId }),
     };
   },
 });

package/src/mcp/tools/media.ts

@@ -1,14 +1,16 @@
 // 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.
+// c64_snapshot. Paths are relative to the project folder (D68); the host-client
+// reads the file and the Host Runtime receives only its bytes.
 
 import { z } from "zod";
 
 import { formatC64Address } from "../../c64.ts";
+import { projectFolder, readProjectFile } from "../../host-client/transfer.ts";
 import { AUTOSTART_TYPES, DISK_TYPES, MAX_SNAPSHOTS, RUN_STATES } from "../../protocol/vice.ts";
+import { OutInput, ProjectInput, writeOut, WrittenOutput } from "../output.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 ProjectPath = z.string().min(1).describe("path relative to the project folder, for example build/game.prg");
 
 const list = (types: readonly string[]) => types.map((type) => `.${type}`).join(", ");
 
@@ -18,19 +20,28 @@ export const c64Autostart = defineTool({
   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). " +
+    "A cartridge stays in the C64 through every reset, as on a real C64. An autostart of a file that is not a cartridge detaches it first. " +
+    "Both joysticks are centred first: joystick port 1 uses the keyboard lines, and a held direction changes the RUN that the autostart types. " +
+    "Without index, a disk image loads like LOAD\"*\",8,1. index selects one directory entry by its number in the c64-disk directory list (0 is the first entry). " +
+      "The tool refuses an index of a DEL entry, or an index after the last entry. " +
     "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"),
+      project: ProjectInput.optional(),
+      index: z.number().int().min(0).max(0xfffe).optional().describe("directory entry of a disk image, 0 is the first entry. Without it, the first file loads as with LOAD\"*\""),
       run: z.boolean().default(true).describe("true runs the program after it loads"),
     })
     .strict(),
-  outputSchema: z.object({ state: z.enum(RUN_STATES) }),
+  outputSchema: z.object({
+    state: z.enum(RUN_STATES),
+    emulatorFlaw: z.string().optional().describe("for a tape image: a known flaw of this VICE version that stops a tape load"),
+    joysticksCentred: z.array(z.union([z.literal(1), z.literal(2)])).optional().describe("the joystick ports that held a direction or fire and were centred before the reset"),
+  }),
   readOnly: false,
   async run(input, session) {
-    return session.autostart(input);
+    // VICE numbers the directory entries from 1, and its 0 loads "*".
+    return session.autostart({ path: input.path, index: input.index === undefined ? 0 : input.index + 1, run: input.run, root: projectFolder(input.project) });
   },
 });
 
@@ -44,13 +55,15 @@ export const c64ProgramLoad = defineTool({
   inputSchema: z
     .object({
       path: ProjectPath,
+      project: ProjectInput.optional(),
       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 });
+    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 };
   },
 });
@@ -62,11 +75,11 @@ export const c64DiskAttach = defineTool({
     `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(),
+  inputSchema: z.object({ path: ProjectPath, project: ProjectInput.optional() }).strict(),
   outputSchema: z.object({ attached: z.boolean() }),
   readOnly: false,
   async run(input, session) {
-    return session.diskAttach(input);
+    return session.diskAttach({ path: input.path, root: projectFolder(input.project) });
   },
 });
 
@@ -75,12 +88,17 @@ export const c64Snapshot = defineTool({
   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. " +
+    "With out, save also writes it to that project file as a snapshot file (.vsf), so a later session can use it. " +
+    "Action restore puts the machine back in that state and stops the CPU. Give name for a snapshot of this session, or file for a .vsf in the project. " +
+    "A file restores only in the emulator version and with the machine settings that saved it. 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"),
+      name: TransientName.optional().describe("save and discard, and restore without file: 1 to 64 letters, digits, dots, underscores or hyphens"),
+      out: OutInput.optional().describe("save only: also write the snapshot to this project file, for example snapshots/room0.vsf. An existing file is overwritten"),
+      file: ProjectPath.optional().describe("restore only: a .vsf file in the project, in place of name"),
+      project: ProjectInput.optional().describe("save with out, and restore with file: the project folder, relative to the folder where the agent started. Give it when that folder is not in a project and has projects below it"),
     })
     .strict(),
   outputSchema: z.object({
@@ -90,16 +108,26 @@ export const c64Snapshot = defineTool({
     state: z.enum(RUN_STATES).optional(),
     snapshots: z.array(z.string()).optional(),
     discarded: z.boolean().optional(),
+    ...WrittenOutput,
   }),
   readOnly: false,
   async run(input, session) {
-    const { action, name } = input;
+    const { action, ...fields } = input;
     if (action === "list") {
-      requireFields(action, { name }, []);
+      requireFields(action, fields, []);
       return session.snapshot({ action });
     }
-    requireFields(action, { name }, ["name"], ["name"]);
-    return session.snapshot({ action, name: name! });
+    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"]);
+      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) };
+    }
+    requireFields(action, fields, ["name"], ["name"]);
+    return session.snapshot({ action, name: fields.name! });
   },
 });
 

package/src/mcp/tools/memory.ts

@@ -6,28 +6,50 @@ 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 { AddressInput, AddressOutput, Byte, defineTool, HexData, HexDataInput, MemoryViewInput, requireFields, SpaceInput } from "../server.ts";
 
+/** With out, a read or a disassembly can be larger than one answer of the session: it is read in parts (D39). */
+const MAX_MEMORY_READ_OUT = 0x10000;
+const MAX_DISASSEMBLE_OUT = 32768;
+/** A memory byte in a result: two lowercase hex digits, as memory data is. */
+const HexByte = z.string().regex(/^[0-9a-f]{2}$/);
+
 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. " +
+    `With out, it reads up to ${MAX_MEMORY_READ_OUT} bytes and writes them as raw bytes to that project file. The result then gives the file, the number of bytes and a SHA-256 in place of data. ` +
     "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}`),
+      size: z.number().int().min(1).max(MAX_MEMORY_READ_OUT).describe(`number of bytes, 1 to ${MAX_MEMORY_READ}, or to ${MAX_MEMORY_READ_OUT} with out`),
       space: SpaceInput,
       view: MemoryViewInput,
+      out: OutInput.optional(),
+      project: ProjectInput.optional(),
     })
     .strict(),
-  outputSchema: z.object({ address: AddressOutput, size: z.number().int().min(1).max(MAX_MEMORY_READ), data: HexData }),
-  readOnly: true,
+  outputSchema: z.object({ address: AddressOutput, size: z.number().int().min(1).max(MAX_MEMORY_READ_OUT), data: HexData.optional(), ...WrittenOutput }),
+  readOnly: false,
   async run(input, session) {
-    const result = await session.memoryRead(input);
-    return { address: formatC64Address(result.address), size: result.data.length / 2, data: result.data };
+    const { out, project, ...read } = input;
+    if (out === undefined && project !== undefined) throw new WireFailure("invalid-input", "project is used only with out.");
+    if (out === undefined) {
+      if (read.size > MAX_MEMORY_READ) throw new WireFailure("invalid-input", `size can be at most ${MAX_MEMORY_READ} without out.`);
+      const result = await session.memoryRead(read);
+      return { address: formatC64Address(result.address), size: result.data.length / 2, data: result.data };
+    }
+    if (read.address + read.size > 0x10000) throw new WireFailure("invalid-input", "The range must not go past $ffff.");
+    const parts: Buffer[] = [];
+    for (let at = read.address; at < read.address + read.size; at += MAX_MEMORY_READ) {
+      const part = await session.memoryRead({ ...read, address: at, size: Math.min(MAX_MEMORY_READ, read.address + read.size - at) });
+      parts.push(Buffer.from(part.data, "hex"));
+    }
+    return { address: formatC64Address(read.address), size: read.size, ...writeOut(out, Buffer.concat(parts), project) };
   },
 });
 
@@ -162,6 +184,7 @@ export const c64MemoryCompare = defineTool({
   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. ` +
+    "The bytes of a difference are lowercase hex. " +
     "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) })
@@ -169,11 +192,13 @@ export const c64MemoryCompare = defineTool({
   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 })),
+    firstDifferences: z.array(z.object({ offset: z.number().int().min(0), left: HexByte, right: HexByte })),
   }),
   readOnly: true,
   async run(input, session) {
-    return session.memoryCompare(input);
+    const result = await session.memoryCompare(input);
+    const hex = (byte: number) => byte.toString(16).padStart(2, "0");
+    return { ...result, firstDifferences: result.firstDifferences.map((difference) => ({ ...difference, left: hex(difference.left), right: hex(difference.right) })) };
   },
 });
 
@@ -183,21 +208,52 @@ export const c64Disassemble = defineTool({
   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. " +
+    `With out, it disassembles up to ${MAX_DISASSEMBLE_OUT} instructions, or to $ffff, and writes them as a listing to that project file. The result then gives the file in place of the instructions. ` +
     "This does not change the run state of the machine.",
   inputSchema: z
     .object({
       address: AddressInput,
-      count: z.number().int().min(1).max(MAX_DISASSEMBLE),
+      count: z.number().int().min(1).max(MAX_DISASSEMBLE_OUT).describe(`1 to ${MAX_DISASSEMBLE}, or to ${MAX_DISASSEMBLE_OUT} with out`),
       space: SpaceInput,
       view: MemoryViewInput,
+      out: OutInput.optional(),
+      project: ProjectInput.optional(),
     })
     .strict(),
-  outputSchema: z.object({ instructions: z.array(z.object({ address: AddressOutput, bytes: HexData, text: z.string() })) }),
-  readOnly: true,
+  outputSchema: z.object({ instructions: z.array(z.object({ address: AddressOutput, bytes: HexData, text: z.string() })).optional(), count: z.number().int().min(0).optional(), ...WrittenOutput }),
+  readOnly: false,
   async run(input, session) {
-    const result = await session.disassemble(input);
-    return { instructions: result.instructions.map((instruction) => ({ ...instruction, address: formatC64Address(instruction.address) })) };
+    const { out, project, ...request } = input;
+    if (out === undefined && project !== undefined) throw new WireFailure("invalid-input", "project is used only with out.");
+    if (out === undefined) {
+      if (request.count > MAX_DISASSEMBLE) throw new WireFailure("invalid-input", `count can be at most ${MAX_DISASSEMBLE} without out.`);
+      const result = await session.disassemble(request);
+      return { instructions: result.instructions.map((instruction) => ({ ...instruction, address: formatC64Address(instruction.address) })) };
+    }
+    const lines: string[] = [];
+    let address = request.address;
+    // Ends at count, or where the disassembly would wrap past $ffff.
+    let wrapped = false;
+    while (!wrapped && lines.length < request.count && address <= 0xffff) {
+      const { instructions } = await session.disassemble({ ...request, address, count: Math.min(MAX_DISASSEMBLE, request.count - lines.length) });
+      if (instructions.length === 0) break;
+      for (const instruction of instructions) {
+        if (lines.length === request.count) break;
+        if (instruction.address < address) {
+          wrapped = true;
+          break;
+        }
+        lines.push(`${formatC64Address(instruction.address)}  ${spaced(instruction.bytes).padEnd(9)} ${instruction.text}`);
+        address = instruction.address + instruction.bytes.length / 2;
+      }
+    }
+    return { count: lines.length, ...writeOut(out, `${lines.join("\n")}\n`, project) };
   },
 });
 
+/** Hex bytes as pairs with spaces: "a90a" is "a9 0a". */
+export function spaced(hex: string): string {
+  return (hex.match(/../g) ?? []).join(" ");
+}
+
 export const memoryTools = [c64MemoryRead, c64MemoryWrite, c64MemorySearch, c64MemoryCompare, c64Registers, c64Disassemble];

package/src/mcp/tools/video.ts

@@ -3,9 +3,10 @@
 
 import { z } from "zod";
 
-import { formatC64Address } from "../../c64.ts";
+import { formatC64Address, formatSprite, formatVicii } from "../../c64.ts";
 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, AddressOutput, Byte, defineTool, HexData, MemoryViewInput, requireFields, SpaceInput, ToolOutput, TransientName } from "../server.ts";
 
 const Color = z.number().int().min(0).max(15);
@@ -30,8 +31,7 @@ export const c64Vicii = defineTool({
   }),
   readOnly: true,
   async run(_input, session) {
-    const state = await session.vicii();
-    return { ...state, screenAddress: formatC64Address(state.screenAddress), graphicsAddress: formatC64Address(state.graphicsAddress) };
+    return formatVicii(await session.vicii());
   },
 });
 
@@ -61,7 +61,7 @@ export const c64Sprite = defineTool({
   readOnly: true,
   async run(input, session) {
     const result = await session.sprites(input.sprites ?? []);
-    return { sprites: result.sprites.map((sprite) => ({ ...sprite, dataAddress: formatC64Address(sprite.dataAddress) })) };
+    return { sprites: result.sprites.map(formatSprite) };
   },
 });
 
@@ -73,9 +73,12 @@ const CiaOutput = z.object({
   ddrB: Byte,
   timerA: z.number().int().min(0).max(0xffff),
   timerB: z.number().int().min(0).max(0xffff),
+  latchA: z.number().int().min(0).max(0xffff).describe("the value that timer A loads when it underflows"),
+  latchB: z.number().int().min(0).max(0xffff).describe("the value that timer B loads when it underflows"),
   controlA: Byte,
   controlB: Byte,
   interruptStatus: Byte,
+  interruptMask: z.number().int().min(0).max(0x1f).describe("the interrupt sources that are on, as bits 0-4 of the interrupt control register"),
   tod: z.object({ hours: z.number().int(), minutes: z.number().int(), seconds: z.number().int(), tenths: z.number().int() }),
 });
 
@@ -83,8 +86,8 @@ export const c64Cia = defineTool({
   name: "c64_cia",
   title: "CIA state",
   description:
-    "Get the state of CIA 1, CIA 2 or both. The state has the ports, the data direction registers and the current timer values. " +
-    `It also has the control registers, the interrupt flags and the time of day (hours 0 to 23). ${NO_CHANGE}`,
+    "Get the state of CIA 1, CIA 2 or both. The state has the ports, the data direction registers, the current timer values and the timer latches. " +
+    `It also has the control registers, the interrupt flags, the interrupt mask and the time of day (hours 0 to 23). ${NO_CHANGE}`,
   inputSchema: z.object({ cia: z.enum(CIA_SELECTIONS).default("both") }).strict(),
   outputSchema: z.object({ chips: z.array(CiaOutput) }),
   readOnly: true,
@@ -129,8 +132,10 @@ export const c64Screen = defineTool({
   title: "Capture and compare the C64 screen",
   description:
     "Action capture returns the last frame the C64 drew, with its borders, as a PNG image, plus its width and height in pixels. " +
+    "With out, capture writes the PNG to that project file, and compare writes its difference image there. The result then has no image. " +
     "With baseline, the session also keeps that frame under the name. " +
     "Action compare compares the current frame with a baseline, pixel by pixel. mask lists rectangles to ignore. " +
+    "A mask that covers the whole frame is invalid input. comparedPixels is the number of pixels outside the mask. " +
     "match is true when the part of compared pixels that differ is at most maxMismatchRatio (default 0). bounds holds every different pixel. " +
     "With includeDiff, compare also returns an image with the different pixels in magenta. " +
     "Action list gives the baseline names. Action discard removes a baseline. Baselines stay until the session ends. " +
@@ -143,6 +148,8 @@ export const c64Screen = defineTool({
       maxMismatchRatio: z.number().min(0).max(1).optional().describe("compare only: 0 to 1, default 0"),
       mask: z.array(Rectangle).max(MAX_MASK_RECTANGLES).optional().describe("compare only: rectangles to ignore, in frame pixels"),
       includeDiff: z.boolean().optional().describe("compare only: also return a difference image"),
+      out: OutInput.optional(),
+      project: ProjectInput.optional().describe("capture and compare with out only: the project folder, relative to the folder where the agent started. Give it when that folder is not in a project and has projects below it"),
     })
     .strict(),
   outputSchema: z.object({
@@ -151,28 +158,32 @@ export const c64Screen = defineTool({
     baseline: z.string().optional(),
     match: z.boolean().optional(),
     mismatchingPixels: z.number().int().min(0).optional(),
+    comparedPixels: z.number().int().min(1).optional(),
     mismatchRatio: z.number().min(0).max(1).optional(),
     bounds: Rectangle.optional(),
     baselines: z.array(z.string()).optional(),
     discarded: z.boolean().optional(),
+    ...WrittenOutput,
   }),
   readOnly: false,
   async run(input, session) {
     const { action, ...fields } = input;
     if (action === "capture") {
-      requireFields(action, fields, ["baseline"]);
+      requireFields(action, fields, fields.out === undefined ? ["baseline"] : ["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"], ["baseline"]);
+      requireFields(action, fields, ["baseline", "maxMismatchRatio", "mask", "includeDiff", ...(fields.out === undefined ? [] : ["out", "project"])], ["baseline"]);
       const { diffPng, ...result } = await session.screenCompare({
         baseline: fields.baseline!,
         maxMismatchRatio: fields.maxMismatchRatio ?? 0,
         mask: fields.mask ?? [],
-        includeDiff: fields.includeDiff ?? false,
+        includeDiff: (fields.includeDiff ?? false) || fields.out !== undefined,
       });
+      if (fields.out !== undefined && diffPng !== undefined) return { ...result, ...writeOut(fields.out, Buffer.from(diffPng, "base64"), fields.project) };
       return diffPng === undefined ? result : new ToolOutput(result, [{ type: "image", data: diffPng, mimeType: "image/png" }]);
     }
     if (action === "list") {

package/src/native/discover.ts

@@ -7,6 +7,9 @@ import { isAbsolute, join, posix, win32 } from "node:path";
 
 import { WireFailure } from "../protocol/messages.ts";
 
+/** Where the user finds the install steps of the native tools for each system (D38). */
+export const INSTALL_STEPS = "Steps for each system: https://github.com/henols/c64-re-tools/blob/main/docs/install-tools.md";
+
 export interface ToolSpec {
   /** Human name, for messages. */
   name: string;
@@ -25,7 +28,7 @@ export const ACME: ToolSpec = {
   envVar: "C64RT_ACME",
   binaries: ["acme"],
   where: "on this machine",
-  remedy: "Install the ACME cross-assembler on the machine that runs the skill scripts so that acme is on PATH, or set C64RT_ACME to its full path.",
+  remedy: `Install the ACME cross-assembler on the machine that runs the skill scripts so that acme is on PATH, or set C64RT_ACME to its full path. ${INSTALL_STEPS}`,
 };
 
 export const C1541: ToolSpec = {
@@ -49,7 +52,7 @@ export const DXA: ToolSpec = {
   envVar: "C64RT_DXA",
   binaries: ["dxa"],
   where: "on this machine",
-  remedy: "Install dxa (from the xa package, https://www.floodgap.com/retrotech/xa/) on the machine that runs the skill scripts so that dxa is on PATH, or set C64RT_DXA to its full path.",
+  remedy: `Install dxa 0.1.5 on the machine that runs the skill scripts so that dxa is on PATH, or set C64RT_DXA to its full path. ${INSTALL_STEPS}`,
 };
 
 export const VICE: ToolSpec = {
@@ -66,10 +69,45 @@ export const VICE: ToolSpec = {
  */
 export const MIN_VICE = { major: 3, minor: 9 } as const;
 
-/** "x64sc (VICE 3.10)", "c1541 (VICE 3.9)" or "VICE 3.9.0": the major and minor version. */
-export function viceVersionOf(text: string): { major: number; minor: number } | undefined {
-  const match = /VICE (\d+)\.(\d+)/.exec(text);
-  return match === null ? undefined : { major: Number(match[1]), minor: Number(match[2]) };
+/** A VICE version; `revision` is the SVN revision of a build from VICE's source tree (nightly builds), absent for a release. */
+export interface ViceVersion {
+  major: number;
+  minor: number;
+  revision?: number;
+}
+
+/** "x64sc (VICE 3.10)", "c1541 (VICE 3.9)", "VICE 3.9.0" or "x64sc (VICE 3.10 SVN r45999)": the major and minor version, and the SVN revision. */
+export function viceVersionOf(text: string): ViceVersion | undefined {
+  const match = /VICE (\d+)\.(\d+)(?:[.\d]*)(?: SVN r(\d+))?/.exec(text);
+  if (match === null) return undefined;
+  return { major: Number(match[1]), minor: Number(match[2]), ...(match[3] === undefined ? {} : { revision: Number(match[3]) }) };
+}
+
+/**
+ * Known flaws of VICE versions that c64-re-tools still runs on (D56). A flaw
+ * is not worked around: it is named with the VICE version that fixes it.
+ * `upTo` is the last flawed major.minor; `fixedRevision` the first SVN
+ * revision with the fix, for builds from VICE's source tree.
+ */
+const VICE_FLAWS = [
+  {
+    upTo: { major: 3, minor: 10 },
+    fixedRevision: 45971,
+    text:
+      "VICE 3.10 and older hold bits 5-7 of CIA 1 ports A and B low with the joystick device that c64-re-tools uses (VICE bug #2202). " +
+      "$DC00 and $DC01 read $1F with no input. A program that waits for one key of the keyboard matrix (for example LDA $DC01 / CMP #$EF for SPACE) waits forever. " +
+      "A program that compares the full byte of a joystick port also waits forever. " +
+      "A KERNAL tape LOAD of a .tap image stops after FOUND, with no LOADING, and the C64 shows READY. The fix is in the next VICE release, and in VICE nightly builds now (SVN r45971 or later). " +
+      "Install the latest VICE when this matters.",
+  },
+] as const;
+
+/** The known flaws of this VICE version, as text for a person or an agent. */
+export function viceFlaws(version: ViceVersion): string[] {
+  return VICE_FLAWS.filter((flaw) => {
+    const newer = version.major > flaw.upTo.major || (version.major === flaw.upTo.major && version.minor > flaw.upTo.minor);
+    return !newer && (version.revision === undefined || version.revision < flaw.fixedRevision);
+  }).map((flaw) => flaw.text);
 }
 
 export function isOlderThanMinimum(version: { major: number; minor: number }): boolean {

package/src/native/ghidra/analyze.ts

@@ -25,7 +25,7 @@ export async function analyze(
   const base = start;
 
   // Ghidra disassembles and defines data only in the loaded bytes; labels may name any address.
-  const { entryPoints, dataRanges } = seedsInside(params, start, end);
+  const { entryPoints, codeStarts, dataRanges } = seedsInside(params, start, end);
   if (entryPoints.length === 0) {
     throw new WireFailure("invalid-input", "Give at least one entry point inside the program, for example the SYS address of its BASIC loader.");
   }
@@ -33,7 +33,7 @@ export async function analyze(
   const workspace = Workspace.create(context.supervisor);
   try {
     workspace.materialize("input", [{ path: "image.bin", size: body.length }], [body]);
-    writeFileSync(workspace.path("seeds.json"), JSON.stringify({ start, end, entryPoints, dataRanges, labels: params.labels }));
+    writeFileSync(workspace.path("seeds.json"), JSON.stringify({ start, end, entryPoints, codeStarts, dataRanges, labels: params.labels }));
     writeFileSync(
       workspace.path("request.json"),
       JSON.stringify({

package/src/native/ghidra/index.ts

@@ -10,7 +10,7 @@ import { dirname, isAbsolute, join, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 
 import { WireFailure } from "../../protocol/messages.ts";
-import { findOnPath, isExecutableFile } from "../discover.ts";
+import { findOnPath, INSTALL_STEPS, isExecutableFile } from "../discover.ts";
 import type { ProcessSupervisor } from "../processes.ts";
 import type { Workspace } from "../staging.ts";
 import { outputTail, runToolOrFail, type ToolRun } from "../run.ts";
@@ -22,7 +22,7 @@ export const SCRIPT_DIRECTORY = fileURLToPath(new URL("./scripts/", import.meta.
 
 const REMEDY =
   "Install Ghidra on the machine that runs the skill scripts and set C64RT_GHIDRA to its installation directory " +
-  "(the directory that holds support/analyzeHeadless), or put analyzeHeadless on PATH.";
+  `(the directory that holds support/analyzeHeadless), or put analyzeHeadless on PATH. ${INSTALL_STEPS}`;
 
 export interface GhidraInstallation {
   /** The installation directory. */
@@ -31,6 +31,8 @@ export interface GhidraInstallation {
   /** For example ghidra_12.1.3_PUBLIC: the name of Ghidra's settings directory. */
   settingsName: string;
   version: string;
+  /** The lowest Java version this Ghidra runs on (application.java.min), when it names one. */
+  javaMin?: string;
 }
 
 /** Ghidra's launcher is a shell script, and a batch file on Windows. */
@@ -49,7 +51,8 @@ function installationAt(root: string, source: string): GhidraInstallation {
   const version = value("application.version");
   const release = value("application.release.name");
   if (version === undefined || release === undefined) throw new WireFailure("installation-incomplete", `The Ghidra installation at ${source} has no version. ${REMEDY}`);
-  return { root, analyzeHeadless, settingsName: `ghidra_${version}_${release}`, version };
+  const javaMin = value("application.java.min");
+  return { root, analyzeHeadless, settingsName: `ghidra_${version}_${release}`, version, ...(javaMin === undefined || javaMin === "" ? {} : { javaMin }) };
 }
 
 /** The version of a Ghidra installation as a result and the tool status name it, for example "Ghidra 12.1.3". */
@@ -123,6 +126,18 @@ export interface HeadlessOptions {
   env?: NodeJS.ProcessEnv;
 }
 
+/** What Ghidra's launcher (launch.sh, launch.bat) prints when it finds no Java that it can use. */
+export const NO_USABLE_JDK = /The 'java' command could not be found in your PATH or with JAVA_HOME|Unable to prompt user for JDK path, no TTY detected|Failed to find a supported JDK/;
+
+/** A Ghidra without a usable JDK is an incomplete installation that names the Java version it needs (D38). */
+export function noJdk(ghidra: GhidraInstallation): WireFailure {
+  const java = ghidra.javaMin === undefined ? "a JDK" : `JDK ${ghidra.javaMin} or later`;
+  return new WireFailure(
+    "installation-incomplete",
+    `${ghidraVersion(ghidra)} found no Java that it can use. It needs ${java}. Install it on the machine that runs the skill scripts and put its java on PATH, or set JAVA_HOME to it. ${INSTALL_STEPS}`,
+  );
+}
+
 /** Imports one file into a disposable project and runs the scripts. Fails on timeout, abort or a Ghidra error exit. */
 export async function runHeadless(options: HeadlessOptions): Promise<ToolRun> {
   const env = prepareSettings(options.workspace, options.ghidra, options.env);
@@ -148,6 +163,7 @@ export async function runHeadless(options: HeadlessOptions): Promise<ToolRun> {
   for (const script of options.preScripts ?? []) argv.push("-preScript", script.name, ...script.args);
   for (const script of options.postScripts ?? []) argv.push("-postScript", script.name, ...script.args);
   const run = await runToolOrFail("Ghidra", "The Ghidra analysis", { argv, cwd: options.workspace.root, timeoutMs: options.timeoutMs }, { supervisor: options.supervisor, signal: options.signal, env });
+  if (run.code !== 0 && NO_USABLE_JDK.test(run.stdout + run.stderr)) throw noJdk(options.ghidra);
   if (run.code !== 0 || /^ERROR REPORT SCRIPT ERROR|Exception in thread "main"/m.test(run.stdout + run.stderr)) {
     // Ghidra's own error lines tell the user what to fix.
     const tail = outputTail("Ghidra", run, options.workspace.root, /ERROR|Exception|Error:/);