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

package/src/mcp/main.ts

@@ -28,10 +28,7 @@ the agent, through npx with the latest version.
 Environment:
   C64RT_VIDEO  pal (default) or ntsc; fixed for the life of the process.
   C64RT_HOST   host:port of the Host Runtime when it is not on 127.0.0.1:6464,
-               host.docker.internal:6464 or host.containers.internal:6464.
-  C64RT_HOST_TOKEN
-               the shared secret of a Host Runtime that listens on an address
-               that is not loopback. Use the same value as the Host Runtime.`;
+               host.docker.internal:6464 or host.containers.internal:6464.`;
 
 function log(line: string): void {
   process.stderr.write(`c64-re-tools-mcp: ${line}\n`);

package/src/mcp/output.ts

@@ -0,0 +1,32 @@
+// Tool results written to a project file instead of the context (D39). The
+// MCP server runs on the agent's machine with the project as its working
+// directory, so it writes the file itself; the host never sees the path.
+
+import { createHash } from "node:crypto";
+
+import { z } from "zod";
+
+import { writeProjectFile } from "../host-client/transfer.ts";
+
+export const OutInput = z.string().min(1).describe("write the result to this file, relative to the project directory, in place of returning it. An existing file is overwritten");
+
+/** What a result says in place of the bytes it wrote. */
+export interface Written {
+  out: string;
+  bytes: number;
+  sha256: string;
+}
+
+/** The fields of a result with out, optional in an output schema that also has the inline form. */
+export const WrittenOutput = {
+  out: z.string().optional(),
+  bytes: z.number().int().min(0).optional(),
+  sha256: z.string().regex(/^[0-9a-f]{64}$/).optional(),
+};
+
+/** Writes `data` to the project file `path` and gives what the result shows in its place. */
+export function writeOut(path: string, data: Uint8Array | string, root?: string): Written {
+  const bytes = typeof data === "string" ? Buffer.from(data, "utf8") : data;
+  writeProjectFile(path, bytes, { what: "out", ...(root === undefined ? {} : { root }) });
+  return { out: path, bytes: bytes.length, sha256: createHash("sha256").update(bytes).digest("hex") };
+}

package/src/mcp/server.ts

@@ -9,7 +9,7 @@ import { z } from "zod";
 
 import { formatC64Address, parseC64Address } from "../c64.ts";
 import type { ViceSessionClient } from "../host-client/vice-session.ts";
-import { WireFailure, type WireError } from "../protocol/messages.ts";
+import { shownMessage, WireFailure, type WireError } from "../protocol/messages.ts";
 import { COMPARISONS, CONDITION_REGISTERS, MEMORY_VIEWS, SPACES, type Condition } from "../protocol/vice.ts";
 import { elapsedMs, trace, type TraceFields } from "../trace.ts";
 
@@ -38,6 +38,8 @@ export type ViceSessionApi = Pick<
   | "screenBaselines"
   | "screenDiscard"
   | "snapshot"
+  | "snapshotExport"
+  | "snapshotRestore"
   | "cpuHistory"
   | "backtrace"
   | "timing"
@@ -206,7 +208,7 @@ export function toolListing(tool: ToolDefinition): McpTool {
 }
 
 function errorResult(error: WireError): CallToolResult {
-  return { isError: true, content: [{ type: "text", text: JSON.stringify({ code: error.code, message: error.message }) }] };
+  return { isError: true, content: [{ type: "text", text: JSON.stringify({ code: error.code, message: shownMessage(error) }) }] };
 }
 
 /** "address: Invalid string: must match ..." style messages, one sentence per problem. */

package/src/mcp/tools/debug.ts

@@ -3,9 +3,13 @@
 
 import { z } from "zod";
 
-import { formatC64Address } from "../../c64.ts";
-import { CHECKPOINT_ACTIONS, MAX_BACKTRACE, MAX_HISTORY, MAX_MEMMAP_RANGES, MAX_PROFILE, MAX_WATCH_SIZE, SPACES, TIMING_ACTIONS, WATCH_ACCESS, type Breakpoint, type Watchpoint } from "../../protocol/vice.ts";
-import { AddressInput, AddressOutput, Byte, ConditionInput, ConditionOutput, defineTool, HexData, requireFields, showCondition, SpaceInput, toCondition } from "../server.ts";
+import { COVERAGE, executedRamCode, EXECUTE, formatC64Address, READ, WRITE, type CodeRange } from "../../c64.ts";
+import { WireFailure } from "../../protocol/messages.ts";
+import { CHECKPOINT_ACTIONS, MAX_BACKTRACE, MAX_HISTORY, MAX_MEMMAP_RANGES, MAX_MEMORY_READ, MAX_PROFILE, MAX_WATCH_SIZE, SPACES, TIMING_ACTIONS, WATCH_ACCESS, type Breakpoint, type Watchpoint } from "../../protocol/vice.ts";
+import { readCoverage } from "../../host-client/coverage.ts";
+import { OutInput, writeOut, WrittenOutput } from "../output.ts";
+import { AddressInput, AddressOutput, Byte, ConditionInput, ConditionOutput, defineTool, HexData, requireFields, showCondition, SpaceInput, toCondition, type ViceSessionApi } from "../server.ts";
+import { spaced } from "./memory.ts";
 
 /** No default here: a filled-in default would count as a field the other actions refuse. */
 const OptionalSpace = z.enum(SPACES).optional().describe("add only: c64 (default) or drive8, the 1541 disk drive CPU");
@@ -37,7 +41,7 @@ export const c64Breakpoint = defineTool({
   description:
     "Manage breakpoints. A breakpoint stops the CPU when it is about to execute the instruction at an address. " +
     "Action add sets one at address in space c64 or drive8. With a condition, it stops only when the condition is true. " +
-    "add returns the new id. Actions remove, enable and disable take that id. Action list gives all breakpoints. Each breakpoint shows its condition, when it has one. " +
+    "add returns the new id. Actions remove, enable and disable take that id. remove returns removed true and the id. Action list gives all breakpoints. Each breakpoint shows its condition, when it has one. " +
     "Breakpoints stay through a reset.",
   inputSchema: z
     .object({
@@ -48,7 +52,7 @@ export const c64Breakpoint = defineTool({
       id: Id.optional().describe("remove, enable and disable only"),
     })
     .strict(),
-  outputSchema: BreakpointOutput.partial().extend({ breakpoints: z.array(BreakpointOutput).optional() }),
+  outputSchema: BreakpointOutput.partial().extend({ removed: z.literal(true).optional(), breakpoints: z.array(BreakpointOutput).optional() }),
   readOnly: false,
   async run(input, session) {
     const { action, ...fields } = input;
@@ -59,6 +63,7 @@ export const c64Breakpoint = defineTool({
     }
     if (action !== "add") {
       requireFields(action, fields, ["id"], ["id"]);
+      if (action === "remove") return session.breakpoint({ action, id: fields.id! });
       return showBreakpoint(await session.breakpoint({ action, id: fields.id! }));
     }
     requireFields(action, fields, ["address", "space", "condition"], ["address"]);
@@ -79,7 +84,7 @@ export const c64Watchpoint = defineTool({
     "Manage watchpoints. A watchpoint stops the CPU when an instruction reads or writes memory in a range. " +
     `Action add sets one at address for size bytes (1 to ${MAX_WATCH_SIZE}, default 1), with access read, write or read-write. ` +
     "With a condition, it stops only when the condition is true. For a write, a memory condition sees the memory after the write. " +
-    "add returns the new id. Actions remove, enable and disable take that id. Action list gives all watchpoints. Each watchpoint shows its condition, when it has one.",
+    "add returns the new id. Actions remove, enable and disable take that id. remove returns removed true and the id. Action list gives all watchpoints. Each watchpoint shows its condition, when it has one.",
   inputSchema: z
     .object({
       action: z.enum(CHECKPOINT_ACTIONS),
@@ -91,7 +96,7 @@ export const c64Watchpoint = defineTool({
       id: Id.optional().describe("remove, enable and disable only"),
     })
     .strict(),
-  outputSchema: WatchpointOutput.partial().extend({ watchpoints: z.array(WatchpointOutput).optional() }),
+  outputSchema: WatchpointOutput.partial().extend({ removed: z.literal(true).optional(), watchpoints: z.array(WatchpointOutput).optional() }),
   readOnly: false,
   async run(input, session) {
     const { action, ...fields } = input;
@@ -102,6 +107,7 @@ export const c64Watchpoint = defineTool({
     }
     if (action !== "add") {
       requireFields(action, fields, ["id"], ["id"]);
+      if (action === "remove") return session.watchpoint({ action, id: fields.id! });
       return showWatchpoint(await session.watchpoint({ action, id: fields.id! }));
     }
     requireFields(action, fields, ["address", "size", "access", "space", "condition"], ["address", "access"]);
@@ -124,8 +130,10 @@ export const c64CpuHistory = defineTool({
     "Get the last instructions that the CPU executed, oldest first. " +
     `limit is the number of instructions (1 to ${MAX_HISTORY}, default 50). ` +
     "Each entry gives the address, the bytes, the instruction and the registers a, x, y and sp. " +
-    "In space c64, it also gives the raster line and cycle when the instruction started. This does not change the run state of the machine.",
-  inputSchema: z.object({ limit: z.number().int().min(1).max(MAX_HISTORY).default(50), space: SpaceInput }).strict(),
+    "In space c64, it also gives the raster line and cycle when the instruction started. " +
+    "With out, it writes the entries as text lines to that project file, and the result gives the file in place of the entries. " +
+    "This does not change the run state of the machine.",
+  inputSchema: z.object({ limit: z.number().int().min(1).max(MAX_HISTORY).default(50), space: SpaceInput, out: OutInput.optional() }).strict(),
   outputSchema: z.object({
     entries: z.array(
       z.object({
@@ -139,12 +147,21 @@ export const c64CpuHistory = defineTool({
         rasterLine: z.number().int().min(0).optional(),
         rasterCycle: z.number().int().min(0).optional(),
       }),
-    ),
+    ).optional(),
+    count: z.number().int().min(0).optional(),
+    ...WrittenOutput,
   }),
-  readOnly: true,
+  readOnly: false,
   async run(input, session) {
-    const { entries } = await session.cpuHistory(input);
-    return { entries: entries.map((entry) => ({ ...entry, address: formatC64Address(entry.address) })) };
+    const { out, ...request } = input;
+    const { entries } = await session.cpuHistory(request);
+    if (out === undefined) return { entries: entries.map((entry) => ({ ...entry, address: formatC64Address(entry.address) })) };
+    const byte = (value: number) => value.toString(16).padStart(2, "0");
+    const lines = entries.map((entry) => {
+      const raster = entry.rasterLine === undefined ? "" : `  line ${entry.rasterLine} cycle ${entry.rasterCycle ?? 0}`;
+      return `${formatC64Address(entry.address)}  ${spaced(entry.bytes).padEnd(9)} ${entry.text.padEnd(16)} a=${byte(entry.a)} x=${byte(entry.x)} y=${byte(entry.y)} sp=${byte(entry.sp)}${raster}`;
+    });
+    return { count: entries.length, ...writeOut(out, `${lines.join("\n")}\n`) };
   },
 });
 
@@ -203,34 +220,103 @@ export const c64Profile = defineTool({
   },
 });
 
+/** The most code ranges a memmap summary lists. */
+const MAX_SUMMARY_RANGES = 64;
+
+/** Where an access happened: RAM, ROM or I/O. */
+function sources(flags: number): Array<"ram" | "rom" | "io"> {
+  const where: Array<"ram" | "rom" | "io"> = [];
+  if (flags & (COVERAGE.ramRead | COVERAGE.ramWrite | COVERAGE.ramExecute)) where.push("ram");
+  if (flags & (COVERAGE.romRead | COVERAGE.romExecute)) where.push("rom");
+  if (flags & (COVERAGE.ioRead | COVERAGE.ioWrite | COVERAGE.ioExecute)) where.push("io");
+  return where;
+}
+
+const count = (map: Uint8Array, bit: number) => map.reduce((sum, flags) => sum + ((flags & bit) === 0 ? 0 : 1), 0);
+const RangeOutput = z.object({ start: AddressOutput, end: AddressOutput });
+const showRanges = (ranges: CodeRange[]) => ranges.slice(0, MAX_SUMMARY_RANGES).map((range) => ({ start: formatC64Address(range.start), end: formatC64Address(range.end) }));
+
 export const c64Memmap = defineTool({
   name: "c64_memmap",
   title: "Memory access map",
   description:
-    "Get how the C64 CPU used memory since the session started or since the last clear. " +
-    "Action read gives ranges of addresses with the same access (execute, read, write) from start to end. " +
+    "Get how the C64 CPU used memory since the session started or since the last clear. RAM, ROM and I/O are apart. " +
+    "Action read gives ranges of addresses with the same access (execute, read, write) from start to end. Each range also tells if the access was in RAM, ROM or I/O. " +
     `It gives at most maxRanges ranges (1 to ${MAX_MEMMAP_RANGES}, default 256). Addresses the CPU did not touch are not in the result. ` +
+    "If more ranges follow, the result also gives truncated: true and next. Read again with start set to next. " +
+    "With out, read writes a coverage map to that project file, one byte for each address from start to end. " +
+    "Bits 0 to 2 are RAM read, write and execute. Bits 3 and 4 are ROM read and execute. Bits 5 to 7 are I/O read, write and execute. " +
+    "Execute is set only on the first byte of each executed instruction. " +
+    "Action summary gives the counts for RAM, ROM and I/O. It also gives the executed code in RAM with its operand bytes, and the RAM that was written and executed. " +
+    `Each list has at most ${MAX_SUMMARY_RANGES} ranges. ` +
     "Action clear sets all access records to zero.",
   inputSchema: z
     .object({
-      action: z.enum(["read", "clear"]),
-      start: AddressInput.optional().describe("read only. Default $0000"),
-      end: AddressInput.optional().describe("read only. Default $ffff"),
-      maxRanges: z.number().int().min(1).max(MAX_MEMMAP_RANGES).optional().describe("read only. Default 256"),
+      action: z.enum(["read", "summary", "clear"]),
+      start: AddressInput.optional().describe("read and summary. Default $0000"),
+      end: AddressInput.optional().describe("read and summary. Default $ffff"),
+      maxRanges: z.number().int().min(1).max(MAX_MEMMAP_RANGES).optional().describe("read without out only. Default 256"),
+      out: OutInput.optional().describe("read only: write a coverage map to this project file, one byte for each address. An existing file is overwritten"),
     })
     .strict(),
   outputSchema: z.object({
-    ranges: z.array(z.object({ start: AddressOutput, end: AddressOutput, execute: z.boolean(), read: z.boolean(), write: z.boolean() })).optional(),
+    ranges: z.array(z.object({ start: AddressOutput, end: AddressOutput, execute: z.boolean(), read: z.boolean(), write: z.boolean(), in: z.array(z.enum(["ram", "rom", "io"])) })).optional(),
+    truncated: z.boolean().optional(),
+    next: AddressOutput.optional(),
+    ram: z.object({ executed: z.number().int(), read: z.number().int(), written: z.number().int() }).optional(),
+    rom: z.object({ executed: z.number().int(), read: z.number().int() }).optional(),
+    io: z.object({ executed: z.number().int(), read: z.number().int(), written: z.number().int() }).optional(),
+    code: z.array(RangeOutput).optional(),
+    codeTruncated: z.boolean().optional(),
+    writtenAndExecuted: z.array(RangeOutput).optional(),
+    writtenAndExecutedTruncated: z.boolean().optional(),
     cleared: z.boolean().optional(),
+    ...WrittenOutput,
   }),
   readOnly: false,
   async run(input, session) {
-    if (input.action === "clear") {
-      requireFields("clear", { start: input.start, end: input.end, maxRanges: input.maxRanges }, []);
+    const { action, ...fields } = input;
+    if (action === "clear") {
+      requireFields("clear", fields, []);
       return session.memmap({ action: "clear" });
     }
-    const result = await session.memmap({ action: "read", start: input.start ?? 0x0000, end: input.end ?? 0xffff, maxRanges: input.maxRanges ?? 256 });
-    return { ranges: result.ranges.map((range) => ({ ...range, start: formatC64Address(range.start), end: formatC64Address(range.end) })) };
+    const start = fields.start ?? 0x0000;
+    const end = fields.end ?? 0xffff;
+    if (end < start) throw new WireFailure("invalid-input", "end must not be before start.");
+    if (action === "summary") {
+      requireFields("summary", fields, ["start", "end"]);
+      const map = await readCoverage(session, start, end);
+      // The opcodes give the instruction lengths: RAM as it is now.
+      const parts: Buffer[] = [];
+      for (let at = 0; at < 0x10000; at += MAX_MEMORY_READ) parts.push(Buffer.from((await session.memoryRead({ address: at, size: MAX_MEMORY_READ, space: "c64", view: "ram" })).data, "hex"));
+      const memory = Buffer.concat(parts);
+      const code = executedRamCode(map, start, memory);
+      const written = executedRamCode(map.map((flags) => ((flags & COVERAGE.ramWrite) === 0 ? 0 : flags)), start, memory);
+      return {
+        ram: { executed: count(map, COVERAGE.ramExecute), read: count(map, COVERAGE.ramRead), written: count(map, COVERAGE.ramWrite) },
+        rom: { executed: count(map, COVERAGE.romExecute), read: count(map, COVERAGE.romRead) },
+        io: { executed: count(map, COVERAGE.ioExecute), read: count(map, COVERAGE.ioRead), written: count(map, COVERAGE.ioWrite) },
+        code: showRanges(code),
+        ...(code.length > MAX_SUMMARY_RANGES ? { codeTruncated: true } : {}),
+        writtenAndExecuted: showRanges(written),
+        ...(written.length > MAX_SUMMARY_RANGES ? { writtenAndExecutedTruncated: true } : {}),
+      };
+    }
+    if (fields.out !== undefined) {
+      requireFields("read", fields, ["start", "end", "out"]);
+      return writeOut(fields.out, await readCoverage(session, start, end));
+    }
+    requireFields("read", fields, ["start", "end", "maxRanges"]);
+    const result = await session.memmap({ action: "read", start, end, maxRanges: fields.maxRanges ?? 256 });
+    const ranges = result.ranges.map((range) => ({
+      start: formatC64Address(range.start),
+      end: formatC64Address(range.end),
+      execute: (range.flags & EXECUTE) !== 0,
+      read: (range.flags & READ) !== 0,
+      write: (range.flags & WRITE) !== 0,
+      in: sources(range.flags),
+    }));
+    return result.next === undefined ? { ranges } : { ranges, truncated: true, next: formatC64Address(result.next) };
   },
 });
 

package/src/mcp/tools/input.ts

@@ -13,6 +13,7 @@ export const c64Keyboard = defineTool({
   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.",

package/src/mcp/tools/media.ts

@@ -5,7 +5,9 @@
 import { z } from "zod";
 
 import { formatC64Address } from "../../c64.ts";
+import { readProjectFile } from "../../host-client/transfer.ts";
 import { AUTOSTART_TYPES, DISK_TYPES, MAX_SNAPSHOTS, RUN_STATES } from "../../protocol/vice.ts";
+import { OutInput, 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");
@@ -75,12 +77,16 @@ 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"),
     })
     .strict(),
   outputSchema: z.object({
@@ -90,16 +96,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"], ["file"]);
+      return session.snapshotRestore(readProjectFile(fields.file).bytes);
+    }
+    if (action === "save") {
+      requireFields(action, fields, ["name", "out"], ["name"]);
+      const saved = await session.snapshot({ action, name: fields.name! });
+      return fields.out === undefined ? saved : { ...saved, ...writeOut(fields.out, await session.snapshotExport(fields.name!)) };
+    }
+    requireFields(action, fields, ["name"], ["name"]);
+    return session.snapshot({ action, name: fields.name! });
   },
 });
 

package/src/mcp/tools/memory.ts

@@ -6,28 +6,46 @@ 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, 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;
+
 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(),
     })
     .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, ...read } = input;
+    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)) };
   },
 });
 
@@ -183,21 +201,50 @@ 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(),
     })
     .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, ...request } = input;
+    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`) };
   },
 });
 
+/** 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

@@ -6,6 +6,7 @@ import { z } from "zod";
 import { formatC64Address } 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, 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);
@@ -129,6 +130,7 @@ 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. " +
     "match is true when the part of compared pixels that differ is at most maxMismatchRatio (default 0). bounds holds every different pixel. " +
@@ -143,6 +145,7 @@ 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(),
     })
     .strict(),
   outputSchema: z.object({
@@ -155,24 +158,27 @@ export const c64Screen = defineTool({
     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, ["baseline", "out"]);
       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")) };
       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", "out"], ["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")) };
       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 = {

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:/);