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

package/src/mcp/tools/media.ts

@@ -0,0 +1,129 @@
+// 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 { 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");
+
+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. " +
+    "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 machine runs when this tool returns, and the load continues.",
+  inputSchema: z
+    .object({
+      path: ProjectPath,
+      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),
+    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) {
+    // 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 });
+  },
+});
+
+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. " +
+    "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 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({
+    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(),
+    ...WrittenOutput,
+  }),
+  readOnly: false,
+  async run(input, session) {
+    const { action, ...fields } = input;
+    if (action === "list") {
+      requireFields(action, fields, []);
+      return session.snapshot({ action });
+    }
+    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! });
+  },
+});
+
+export const mediaTools = [c64Autostart, c64ProgramLoad, c64DiskAttach, c64Snapshot];

package/src/mcp/tools/memory.ts

@@ -0,0 +1,250 @@
+// 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 { 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_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_OUT), data: HexData.optional(), ...WrittenOutput }),
+  readOnly: false,
+  async run(input, session) {
+    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)) };
+  },
+});
+
+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. " +
+    `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_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() })).optional(), count: z.number().int().min(0).optional(), ...WrittenOutput }),
+  readOnly: false,
+  async run(input, session) {
+    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

@@ -0,0 +1,271 @@
+// Video and chip tools: c64_vicii, c64_sprite, c64_cia, c64_sid, c64_screen
+// and c64_observe.
+
+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);
+const NO_CHANGE = "This does not change the run state of the machine.";
+
+export const c64Vicii = defineTool({
+  name: "c64_vicii",
+  title: "VIC-II state",
+  description:
+    "Get the state of the VIC-II video chip: the raster line, the graphics mode, the screen and graphics addresses, " +
+    `the scroll values and the colors. The addresses include the 16 KB video bank that CIA 2 selects. ${NO_CHANGE}`,
+  inputSchema: z.object({}).strict(),
+  outputSchema: z.object({
+    rasterLine: z.number().int().min(0),
+    mode: z.enum(VICII_MODES),
+    screenAddress: AddressOutput,
+    graphicsAddress: AddressOutput.describe("character set in text modes, bitmap in bitmap modes"),
+    scrollX: z.number().int().min(0).max(7),
+    scrollY: z.number().int().min(0).max(7),
+    borderColor: Color,
+    backgroundColors: z.array(Color).length(4),
+  }),
+  readOnly: true,
+  async run(_input, session) {
+    const state = await session.vicii();
+    return { ...state, screenAddress: formatC64Address(state.screenAddress), graphicsAddress: formatC64Address(state.graphicsAddress) };
+  },
+});
+
+const SpriteOutput = z.object({
+  index: z.number().int().min(0).max(7),
+  x: z.number().int().min(0),
+  y: z.number().int().min(0),
+  enabled: z.boolean(),
+  color: Color,
+  multicolor: z.boolean(),
+  expandX: z.boolean(),
+  expandY: z.boolean(),
+  behindBackground: z.boolean(),
+  dataAddress: AddressOutput,
+});
+
+export const c64Sprite = defineTool({
+  name: "c64_sprite",
+  title: "Sprite state",
+  description:
+    "Get the state of sprites 0 to 7: position, enabled, color, multicolor, expansion, priority and the address of the sprite data. " +
+    `sprites selects which sprites to give. Without it, you get all eight. ${NO_CHANGE}`,
+  inputSchema: z
+    .object({ sprites: z.array(z.number().int().min(0).max(7)).min(1).max(8).optional().describe("sprite numbers 0 to 7, each once") })
+    .strict(),
+  outputSchema: z.object({ sprites: z.array(SpriteOutput) }),
+  readOnly: true,
+  async run(input, session) {
+    const result = await session.sprites(input.sprites ?? []);
+    return { sprites: result.sprites.map((sprite) => ({ ...sprite, dataAddress: formatC64Address(sprite.dataAddress) })) };
+  },
+});
+
+const CiaOutput = z.object({
+  id: z.union([z.literal(1), z.literal(2)]),
+  portA: Byte,
+  portB: Byte,
+  ddrA: Byte,
+  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() }),
+});
+
+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, 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,
+  async run(input, session) {
+    return session.cia(input.cia);
+  },
+});
+
+export const c64Sid = defineTool({
+  name: "c64_sid",
+  title: "SID state",
+  description:
+    "Get the SID sound chip registers as the program last wrote them: the three voices, the filter and the volume. " +
+    `This is register state, not an analysis of the sound. ${NO_CHANGE}`,
+  inputSchema: z.object({}).strict(),
+  outputSchema: z.object({
+    voices: z.array(
+      z.object({
+        index: z.number().int().min(1).max(3),
+        frequency: z.number().int(),
+        pulseWidth: z.number().int(),
+        control: Byte,
+        attackDecay: Byte,
+        sustainRelease: Byte,
+      }),
+    ),
+    filter: z.object({ cutoff: z.number().int(), resonance: z.number().int(), routing: z.number().int(), mode: z.number().int() }),
+    volume: z.number().int().min(0).max(15),
+  }),
+  readOnly: true,
+  async run(_input, session) {
+    return session.sid();
+  },
+});
+
+const Rectangle = z
+  .object({ x: z.number().int().min(0), y: z.number().int().min(0), width: z.number().int().min(1), height: z.number().int().min(1) })
+  .strict();
+
+export const c64Screen = defineTool({
+  name: "c64_screen",
+  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. " +
+    "The emulator draws frames while the CPU runs. After the CPU stops, the frame stays the same. " +
+    "This does not change the run state of the machine.",
+  inputSchema: z
+    .object({
+      action: z.enum(["capture", "compare", "list", "discard"]),
+      baseline: TransientName.optional().describe("capture: keep the frame under this name. compare and discard: the baseline to use"),
+      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({
+    width: z.number().int().min(1).optional(),
+    height: z.number().int().min(1).optional(),
+    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", "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", "out"], ["baseline"]);
+      const { diffPng, ...result } = await session.screenCompare({
+        baseline: fields.baseline!,
+        maxMismatchRatio: fields.maxMismatchRatio ?? 0,
+        mask: fields.mask ?? [],
+        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") {
+      requireFields(action, fields, []);
+      return session.screenBaselines();
+    }
+    requireFields(action, fields, ["baseline"], ["baseline"]);
+    return session.screenDiscard(fields.baseline!);
+  },
+});
+
+const FlagsOutput = z.object({ n: z.boolean(), v: z.boolean(), b: z.boolean(), d: z.boolean(), i: z.boolean(), z: z.boolean(), c: z.boolean() });
+
+export const c64Observe = defineTool({
+  name: "c64_observe",
+  title: "Observe several things at one moment",
+  description:
+    "Get several observations from one moment: the CPU stops once, the tool reads all of them, and then the CPU continues if it was running. " +
+    "Ask for any of registers (a space), memory ranges, vicii, sprites, cia, sid, screen and timing (the raster position). " +
+    `Ask for at least one. Use at most ${MAX_OBSERVE_RANGES} memory ranges with at most ${MAX_OBSERVE_BYTES} bytes together. ` +
+    "The result has only the parts you asked for. With screen, an image comes with the result.",
+  inputSchema: z
+    .object({
+      registers: z.enum(SPACES).optional().describe("the space whose CPU registers to read"),
+      memory: z
+        .array(
+          z
+            .object({ address: AddressInput, size: z.number().int().min(1).max(MAX_MEMORY_READ), space: SpaceInput, view: MemoryViewInput })
+            .strict(),
+        )
+        .min(1)
+        .max(MAX_OBSERVE_RANGES)
+        .optional(),
+      vicii: z.boolean().optional(),
+      sprites: z.array(z.number().int().min(0).max(7)).min(1).max(8).optional().describe("sprite numbers 0 to 7, each once"),
+      cia: z.enum(CIA_SELECTIONS).optional(),
+      sid: z.boolean().optional(),
+      screen: z.boolean().optional(),
+      timing: z.boolean().optional(),
+    })
+    .strict(),
+  outputSchema: z.object({
+    registers: z.object({ pc: AddressOutput, a: Byte, x: Byte, y: Byte, sp: Byte, flags: FlagsOutput }).optional(),
+    memory: z.array(z.object({ address: AddressOutput, data: HexData })).optional(),
+    vicii: c64Vicii.outputSchema.optional(),
+    sprites: z.array(SpriteOutput).optional(),
+    cia: z.array(CiaOutput).optional(),
+    sid: c64Sid.outputSchema.optional(),
+    screen: z.object({ width: z.number().int(), height: z.number().int() }).optional(),
+    timing: z.object({ rasterLine: z.number().int(), rasterCycle: z.number().int() }).optional(),
+  }),
+  readOnly: true,
+  async run(input, session) {
+    const params: ObserveParams = {};
+    if (input.registers !== undefined) params.registers = input.registers;
+    if (input.memory !== undefined) params.memory = input.memory;
+    if (input.vicii === true) params.vicii = true;
+    if (input.sprites !== undefined) params.sprites = input.sprites;
+    if (input.cia !== undefined) params.cia = input.cia;
+    if (input.sid === true) params.sid = true;
+    if (input.screen === true) params.screen = true;
+    if (input.timing === true) params.timing = true;
+    if (Object.keys(params).length === 0) throw new WireFailure("invalid-input", "Ask for at least one observation.");
+    const observed = await session.observe(params);
+    const result: Record<string, unknown> = {};
+    if (observed.registers !== undefined) result.registers = { ...observed.registers, pc: formatC64Address(observed.registers.pc) };
+    if (observed.memory !== undefined) result.memory = observed.memory.map((range) => ({ ...range, address: formatC64Address(range.address) }));
+    if (observed.vicii !== undefined) {
+      result.vicii = {
+        ...observed.vicii,
+        screenAddress: formatC64Address(observed.vicii.screenAddress),
+        graphicsAddress: formatC64Address(observed.vicii.graphicsAddress),
+      };
+    }
+    if (observed.sprites !== undefined) result.sprites = observed.sprites.map((sprite) => ({ ...sprite, dataAddress: formatC64Address(sprite.dataAddress) }));
+    if (observed.cia !== undefined) result.cia = observed.cia;
+    if (observed.sid !== undefined) result.sid = observed.sid;
+    if (observed.timing !== undefined) result.timing = observed.timing;
+    if (observed.screen === undefined) return result;
+    result.screen = { width: observed.screen.width, height: observed.screen.height };
+    return new ToolOutput(result, [{ type: "image", data: observed.screen.png, mimeType: "image/png" }]);
+  },
+});
+
+export const videoTools = [c64Vicii, c64Sprite, c64Cia, c64Sid, c64Screen, c64Observe];