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

package/src/mcp/tools/debug.ts

@@ -0,0 +1,327 @@
+// Debug tools: c64_breakpoint, c64_watchpoint, c64_cpu_history, c64_backtrace,
+// c64_profile, c64_memmap and c64_timing.
+
+import { z } from "zod";
+
+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");
+
+const Id = z.number().int().min(1).describe("the id that action add returned");
+
+const BreakpointOutput = z.object({
+  id: z.number().int().min(1),
+  address: AddressOutput,
+  space: z.enum(SPACES),
+  enabled: z.boolean(),
+  condition: ConditionOutput.optional(),
+});
+const WatchpointOutput = BreakpointOutput.extend({ size: z.number().int().min(1).max(MAX_WATCH_SIZE), access: z.enum(WATCH_ACCESS) });
+
+function showBreakpoint(point: Breakpoint) {
+  const { condition, ...rest } = point;
+  return { ...rest, address: formatC64Address(point.address), ...(condition === undefined ? {} : { condition: showCondition(condition) }) };
+}
+
+function showWatchpoint(point: Watchpoint) {
+  const { condition, ...rest } = point;
+  return { ...rest, address: formatC64Address(point.address), ...(condition === undefined ? {} : { condition: showCondition(condition) }) };
+}
+
+export const c64Breakpoint = defineTool({
+  name: "c64_breakpoint",
+  title: "C64 breakpoints",
+  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. Breakpoints and watchpoints take their ids from one counter, so the ids of one kind can have gaps. " +
+    "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({
+      action: z.enum(CHECKPOINT_ACTIONS),
+      address: AddressInput.optional().describe("add only"),
+      space: OptionalSpace,
+      condition: ConditionInput.optional().describe("add only: stop only when this is true"),
+      id: Id.optional().describe("remove, enable and disable only"),
+    })
+    .strict(),
+  outputSchema: BreakpointOutput.partial().extend({ removed: z.literal(true).optional(), breakpoints: z.array(BreakpointOutput).optional() }),
+  readOnly: false,
+  async run(input, session) {
+    const { action, ...fields } = input;
+    if (action === "list") {
+      requireFields(action, fields, []);
+      const result = await session.breakpoint({ action });
+      return { breakpoints: result.breakpoints.map(showBreakpoint) };
+    }
+    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"]);
+    const added = await session.breakpoint({
+      action,
+      address: fields.address!,
+      space: fields.space ?? "c64",
+      ...(fields.condition === undefined ? {} : { condition: toCondition(fields.condition) }),
+    });
+    return showBreakpoint(added);
+  },
+});
+
+export const c64Watchpoint = defineTool({
+  name: "c64_watchpoint",
+  title: "C64 watchpoints",
+  description:
+    "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. Breakpoints and watchpoints take their ids from one counter, so the ids of one kind can have gaps. " +
+    "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),
+      address: AddressInput.optional().describe("add only"),
+      size: z.number().int().min(1).max(MAX_WATCH_SIZE).optional().describe("add only. Default 1"),
+      access: z.enum(WATCH_ACCESS).optional().describe("add only"),
+      space: OptionalSpace,
+      condition: ConditionInput.optional().describe("add only: stop only when this is true"),
+      id: Id.optional().describe("remove, enable and disable only"),
+    })
+    .strict(),
+  outputSchema: WatchpointOutput.partial().extend({ removed: z.literal(true).optional(), watchpoints: z.array(WatchpointOutput).optional() }),
+  readOnly: false,
+  async run(input, session) {
+    const { action, ...fields } = input;
+    if (action === "list") {
+      requireFields(action, fields, []);
+      const result = await session.watchpoint({ action });
+      return { watchpoints: result.watchpoints.map(showWatchpoint) };
+    }
+    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"]);
+    const added = await session.watchpoint({
+      action,
+      address: fields.address!,
+      size: fields.size ?? 1,
+      access: fields.access!,
+      space: fields.space ?? "c64",
+      ...(fields.condition === undefined ? {} : { condition: toCondition(fields.condition) }),
+    });
+    return showWatchpoint(added);
+  },
+});
+
+export const c64CpuHistory = defineTool({
+  name: "c64_cpu_history",
+  title: "CPU history",
+  description:
+    "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 before the instruction executed. " +
+    "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({
+        address: AddressOutput,
+        bytes: HexData,
+        text: z.string(),
+        a: Byte,
+        x: Byte,
+        y: Byte,
+        sp: Byte,
+        rasterLine: z.number().int().min(0).optional(),
+        rasterCycle: z.number().int().min(0).optional(),
+      }),
+    ).optional(),
+    count: z.number().int().min(0).optional(),
+    ...WrittenOutput,
+  }),
+  readOnly: false,
+  async run(input, session) {
+    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`) };
+  },
+});
+
+export const c64Backtrace = defineTool({
+  name: "c64_backtrace",
+  title: "Call backtrace",
+  description:
+    `Get the chain of subroutine calls that leads to the current instruction, most recent first, at most depth calls (1 to ${MAX_BACKTRACE}, default 16). ` +
+    "Each frame gives the entry address of the routine and the address it returns to. " +
+    "The chain comes from the JSR return addresses on the stack, so it is a best estimate. Interrupts are not in the chain.",
+  inputSchema: z.object({ depth: z.number().int().min(1).max(MAX_BACKTRACE).default(16), space: SpaceInput }).strict(),
+  outputSchema: z.object({ frames: z.array(z.object({ address: AddressOutput, returnAddress: AddressOutput.optional() })) }),
+  readOnly: true,
+  async run(input, session) {
+    const { frames } = await session.backtrace(input);
+    return {
+      frames: frames.map((frame) => ({
+        address: formatC64Address(frame.address),
+        ...(frame.returnAddress === undefined ? {} : { returnAddress: formatC64Address(frame.returnAddress) }),
+      })),
+    };
+  },
+});
+
+export const c64Timing = defineTool({
+  name: "c64_timing",
+  title: "Cycle stopwatch",
+  description:
+    "A stopwatch that counts C64 CPU cycles. Action start sets it to zero. Action read gives the cycles since the last start, " +
+    "or since the session started, as a decimal string. A reset and c64_autostart start it again from the reset. " +
+    "A PAL frame has 19656 cycles and an NTSC frame 17095.",
+  inputSchema: z.object({ action: z.enum(TIMING_ACTIONS) }).strict(),
+  outputSchema: z.object({ started: z.boolean().optional(), cycles: z.string().regex(/^\d+$/).optional() }),
+  readOnly: false,
+  async run(input, session) {
+    return session.timing(input.action);
+  },
+});
+
+export const c64Profile = defineTool({
+  name: "c64_profile",
+  title: "Cycle profile",
+  description:
+    "Get the routines where the C64 CPU spent the most cycles since the session started or since the last c64_window. " +
+    "After c64_window or a snapshot restore, the emulator can give the cycles to a routine that ran before the restore, for example $fd50. Do not trust the routine addresses then. " +
+    `limit is the maximum number of routines (1 to ${MAX_PROFILE}, default 20). ` +
+    "Each entry gives the routine address, its total cycles with the routines it calls, and its own cycles. " +
+    "percent is the part of all cycles that the routine used itself. " +
+    "Cycle counts are decimal strings.",
+  inputSchema: z.object({ limit: z.number().int().min(1).max(MAX_PROFILE).default(20) }).strict(),
+  outputSchema: z.object({
+    entries: z.array(z.object({ address: AddressOutput, totalCycles: z.string(), selfCycles: z.string(), percent: z.number() })),
+  }),
+  readOnly: true,
+  async run(input, session) {
+    const { entries } = await session.profile(input.limit);
+    return { entries: entries.map((entry) => ({ ...entry, address: formatC64Address(entry.address) })) };
+  },
+});
+
+/** 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. 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", "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(), 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) {
+    const { action, ...fields } = input;
+    if (action === "clear") {
+      requireFields("clear", fields, []);
+      return session.memmap({ action: "clear" });
+    }
+    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) };
+  },
+});
+
+export const debugTools = [c64Breakpoint, c64Watchpoint, c64CpuHistory, c64Backtrace, c64Profile, c64Memmap, c64Timing];

package/src/mcp/tools/execution.ts

@@ -0,0 +1,117 @@
+// Execution tools: c64_execution and c64_run_until.
+
+import { z } from "zod";
+
+import { formatC64Address } from "../../c64.ts";
+import { COMPARISONS, EXECUTION_ACTIONS, MAX_EXECUTION_COUNT, MAX_TIMEOUT_FRAMES, RUN_STATES, SPACES, STOP_REASONS, type RunTarget } from "../../protocol/vice.ts";
+import { AddressInput, AddressOutput, Byte, ConditionInput, defineTool, MemoryViewInput, SpaceInput, toCondition } from "../server.ts";
+
+export const c64Execution = defineTool({
+  name: "c64_execution",
+  title: "Control C64 execution",
+  description:
+    "Control the CPU. pause stops the CPU and gives the program counter (pc). resume lets the CPU run. " +
+    "step executes count instructions (default 1) and goes into subroutines. " +
+    "next executes count instructions (default 1) and treats a JSR and its subroutine as one instruction. " +
+    "until-return runs until the current subroutine returns (after the next RTS or RTI). " +
+    "advance-frames runs exactly count video frames (count is necessary). It stops at the same raster position, count frames later. " +
+    "A breakpoint or watchpoint can stop it before that. advancedFrames tells how many frames ran. " +
+    "step, next, until-return and advance-frames first stop a running CPU. Use count only with step, next and advance-frames. " +
+    "step, next and until-return work only in space c64. For the drive, use c64_run_until with an address in space drive8.",
+  inputSchema: z
+    .object({
+      action: z.enum(EXECUTION_ACTIONS),
+      count: z
+        .number()
+        .int()
+        .min(1)
+        .max(MAX_EXECUTION_COUNT)
+        .optional()
+        .describe(`step and next: instructions (default 1). advance-frames: frames (necessary). 1 to ${MAX_EXECUTION_COUNT}`),
+      space: SpaceInput,
+    })
+    .strict(),
+  outputSchema: z.object({
+    state: z.enum(RUN_STATES),
+    pc: AddressOutput.optional(),
+    executed: z.number().int().min(0).max(MAX_EXECUTION_COUNT).optional().describe("instructions executed by step or next"),
+    advancedFrames: z.number().int().min(0).max(MAX_EXECUTION_COUNT).optional().describe("frames advance-frames ran"),
+  }),
+  readOnly: false,
+  async run(input, session) {
+    const params = { action: input.action, space: input.space, ...(input.count === undefined ? {} : { count: input.count }) };
+    const result = await session.execution(params);
+    return {
+      state: result.state,
+      ...(result.pc === undefined ? {} : { pc: formatC64Address(result.pc) }),
+      ...(result.executed === undefined ? {} : { executed: result.executed }),
+      ...(result.advancedFrames === undefined ? {} : { advancedFrames: result.advancedFrames }),
+    };
+  },
+});
+
+const RunTargetInput = z.discriminatedUnion("kind", [
+  z
+    .object({
+      kind: z.literal("address"),
+      address: AddressInput,
+      space: SpaceInput,
+      condition: ConditionInput.optional().describe("stop at the address only when this is true"),
+    })
+    .strict(),
+  z
+    .object({
+      kind: z.literal("memory"),
+      address: AddressInput,
+      operator: z.enum(COMPARISONS),
+      value: Byte,
+      space: SpaceInput,
+      view: MemoryViewInput,
+    })
+    .strict(),
+  z
+    .object({
+      kind: z.literal("raster"),
+      line: z.number().int().min(0).describe("raster line: PAL 0-311, NTSC 0-262"),
+      cycle: z.number().int().min(0).optional().describe("cycle in the line: PAL 0-62, NTSC 0-64. Default 0"),
+    })
+    .strict(),
+]);
+
+export const c64RunUntil = defineTool({
+  name: "c64_run_until",
+  title: "Run the C64 until a target",
+  description:
+    "Run the CPU until a target occurs, then stop. " +
+    "Target kind address stops before the instruction at an address executes. An optional condition must also be true. " +
+    "Kind memory compares the byte at address to value with operator. It stops after a write that makes this comparison true. " +
+    "Kind raster stops at the first instruction at or after a raster line and cycle. If the machine is there now, it stops at the next frame's pass. " +
+    `timeoutFrames (1 to ${MAX_TIMEOUT_FRAMES}, default 3000) limits the run in video frames. ` +
+    "reached tells if the target occurred. stopReason tells why the CPU stopped: target, breakpoint, watchpoint, jam (a JAM opcode) or timeout. " +
+    "space tells which CPU stopped: c64, or drive8 for a stop in the disk drive. pc is the address in that space. " +
+    "The CPU is always stopped after this tool.",
+  inputSchema: z
+    .object({
+      target: RunTargetInput,
+      timeoutFrames: z.number().int().min(1).max(MAX_TIMEOUT_FRAMES).default(3000),
+    })
+    .strict(),
+  outputSchema: z.object({ reached: z.boolean(), stopReason: z.enum(STOP_REASONS), state: z.enum(RUN_STATES), pc: AddressOutput, space: z.enum(SPACES) }),
+  readOnly: false,
+  async run(input, session) {
+    const { target: given } = input;
+    let target: RunTarget;
+    if (given.kind === "address") {
+      target = { kind: "address", address: given.address, space: given.space };
+      if (given.condition !== undefined) target.condition = toCondition(given.condition);
+    } else if (given.kind === "memory") {
+      target = given;
+    } else {
+      target = given.cycle === undefined ? { kind: "raster", line: given.line } : { kind: "raster", line: given.line, cycle: given.cycle };
+    }
+    const result = await session.runUntil({ target, timeoutFrames: input.timeoutFrames });
+    return { ...result, pc: formatC64Address(result.pc) };
+  },
+});
+
+export const executionTools = [c64Execution, c64RunUntil];

package/src/mcp/tools/input.ts

@@ -0,0 +1,72 @@
+// Input tools: c64_keyboard and c64_joystick.
+
+import { z } from "zod";
+
+import { textToPetscii } from "../../c64.ts";
+import { WireFailure } from "../../protocol/messages.ts";
+import { JOYSTICK_DIRECTIONS, MAX_KEYBOARD_BYTES } from "../../protocol/vice.ts";
+import { defineTool } from "../server.ts";
+
+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. 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"]),
+      text: z.string().min(1).optional().describe("mode text: the text to type"),
+      bytes: z.array(z.number().int().min(1).max(255)).min(1).optional().describe("mode petscii: PETSCII codes to type"),
+    })
+    .strict(),
+  outputSchema: z.object({ queuedBytes: z.number().int().min(1).max(MAX_KEYBOARD_BYTES), emulatorFlaw: EMULATOR_FLAW }),
+  readOnly: false,
+  async run(input, session) {
+    let petscii: Uint8Array;
+    if (input.mode === "text") {
+      if (input.text === undefined || input.bytes !== undefined) throw new WireFailure("invalid-input", "Mode text takes text and no bytes.");
+      try {
+        petscii = textToPetscii(input.text);
+      } catch (error) {
+        throw new WireFailure("invalid-input", `${(error as Error).message}. Use mode petscii for other keys.`);
+      }
+    } else {
+      if (input.bytes === undefined || input.text !== undefined) throw new WireFailure("invalid-input", "Mode petscii takes bytes and no text.");
+      petscii = Uint8Array.from(input.bytes);
+    }
+    if (petscii.length > MAX_KEYBOARD_BYTES) {
+      throw new WireFailure("invalid-input", `The keyboard queue takes at most ${MAX_KEYBOARD_BYTES} keys at once. This input has ${petscii.length} keys.`);
+    }
+    return session.keyboard(petscii);
+  },
+});
+
+export const c64Joystick = defineTool({
+  name: "c64_joystick",
+  title: "Move a joystick",
+  description:
+    "Set the joystick in control port 1 or 2: a direction (or center) and the fire button. " +
+    "The C64 sees this state until you change it. To release the joystick, set direction center and fire false. " +
+    "Most games read port 2. This does not change the run state of the machine. 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"),
+      direction: z.enum(JOYSTICK_DIRECTIONS),
+      fire: z.boolean().default(false),
+    })
+    .strict(),
+  outputSchema: z.object({ port: z.union([z.literal(1), z.literal(2)]), direction: z.enum(JOYSTICK_DIRECTIONS), fire: z.boolean(), emulatorFlaw: EMULATOR_FLAW }),
+  readOnly: false,
+  async run(input, session) {
+    return session.joystick(input);
+  },
+});
+
+export const inputTools = [c64Keyboard, c64Joystick];

package/src/mcp/tools/machine.ts

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