@henols/c64-re-tools 2.1.0-rc.1 → 2.1.0

package/src/mcp/inputs.ts

@@ -0,0 +1,105 @@
+// The inputs of the MCP tools that change or wait for the machine. The action
+// steps of the scripts take the same fields, ranges and defaults (host-client/
+// steps.ts, without zod, because the scripts install without packages);
+// inputs.test.ts checks that both take the same inputs.
+
+import { z } from "zod";
+
+import { c64AddressOf } from "../c64.ts";
+import { DEFAULT_TIMEOUT_FRAMES, keyboardBytes, MAX_RASTER_LINE } from "../host-client/steps.ts";
+import { COMPARISONS, CONDITION_REGISTERS, JOYSTICK_DIRECTIONS, MAX_KEYBOARD_BYTES, MAX_MEMORY_WRITE, MAX_TIMEOUT_FRAMES, MEMORY_VIEWS, SPACES } from "../protocol/vice.ts";
+
+export const Byte = z.number().int().min(0).max(255);
+
+/** Input bytes: hex in either case, two digits per byte, at least one byte. Parses to lowercase. */
+export const HexDataInput = z
+  .string()
+  .regex(/^(?:[0-9a-fA-F]{2})+$/, "must be hex bytes, two digits per byte, no separators, for example a9008d20d0")
+  .transform((value) => value.toLowerCase());
+
+export const SpaceInput = z.enum(SPACES).default("c64").describe("c64 is the computer. drive8 is the 1541 disk drive CPU");
+
+export const MemoryViewInput = z
+  .enum(MEMORY_VIEWS)
+  .default("cpu")
+  .describe("cpu reads what the CPU sees now (ROM and I/O where banked in). ram reads the RAM underneath (c64 only)");
+
+/** A tool address: $ and 1 to 4 hex digits, either case. Parses to a number. */
+export const AddressInput = z
+  .string()
+  .refine((value) => c64AddressOf(value) !== undefined, {
+    message: "must be $ and 1 to 4 hex digits, for example $c000 or $fb. A tool takes no names: get the address of a name with knowledge.ts at <name> of the c64-knowledge skill",
+  })
+  .transform((value) => c64AddressOf(value)!)
+  .describe("C64 address: $ and 1 to 4 hex digits, $0000 to $ffff");
+
+const rasterLine = z.number().int().min(0).max(MAX_RASTER_LINE).describe("raster line: PAL 0-311, NTSC 0-262");
+
+const condition = z
+  .discriminatedUnion("kind", [
+    z.object({ kind: z.literal("register"), register: z.enum(CONDITION_REGISTERS), operator: z.enum(COMPARISONS), value: Byte }).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: rasterLine, cycle: z.number().int().min(0).max(64).optional().describe("cycle in the line: PAL 0-62, NTSC 0-64. True from this cycle on") }).strict(),
+  ])
+  .describe("register: a CPU register compared to a byte. memory: a byte in memory compared to a byte. raster: the raster position");
+
+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() });
+
+export const TOOL_INPUTS = {
+  condition,
+
+  runTarget: z.discriminatedUnion("kind", [
+    z.object({ kind: z.literal("address"), address: AddressInput, space: SpaceInput, condition: condition.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: rasterLine, cycle: z.number().int().min(0).max(64).optional().describe("cycle in the line: PAL 0-62, NTSC 0-64. Default 0") }).strict(),
+  ]),
+
+  timeoutFrames: z.number().int().min(1).max(MAX_TIMEOUT_FRAMES).default(DEFAULT_TIMEOUT_FRAMES),
+
+  memoryWrite: z
+    .object({
+      address: AddressInput,
+      data: HexDataInput.describe("bytes as hex, two digits per byte, no separators, for example a9008d20d0"),
+      space: SpaceInput,
+      view: MemoryViewInput,
+    })
+    .strict()
+    .refine((value) => value.data.length / 2 <= MAX_MEMORY_WRITE, { message: `data has at most ${MAX_MEMORY_WRITE} bytes`, path: ["data"] }),
+
+  flags,
+
+  registerValues: 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()
+    .refine((value) => Object.entries(value).some(([name, item]) => item !== undefined && !(name === "flags" && Object.keys(item as object).length === 0)), { message: "name at least one register" }),
+
+  joystick: 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(),
+
+  keyboard: 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()
+    .superRefine((value, context) => {
+      if (value.mode === "text" && (value.text === undefined || value.bytes !== undefined)) return context.addIssue({ code: "custom", message: "mode text takes text and no bytes" });
+      if (value.mode === "petscii" && (value.bytes === undefined || value.text !== undefined)) return context.addIssue({ code: "custom", message: "mode petscii takes bytes and no text" });
+      const keys = keyboardBytes(value);
+      if (typeof keys === "string") context.addIssue({ code: "custom", message: keys, path: ["text"] });
+      else if (keys.length > MAX_KEYBOARD_BYTES) context.addIssue({ code: "custom", message: `the keyboard queue takes at most ${MAX_KEYBOARD_BYTES} keys at once. This input has ${keys.length} keys` });
+    }),
+};

package/src/mcp/output.ts

@@ -3,11 +3,9 @@
 // host never sees the path. The project is the folder that `project` names,
 // or the one that the project rules find from the folder the agent started in.
 
-import { createHash } from "node:crypto";
-
 import { z } from "zod";
 
-import { projectFolder, writeProjectFile } from "../host-client/transfer.ts";
+import { projectFolder, writeReported, type Written } from "../host-client/transfer.ts";
 
 export const OutInput = z.string().min(1).describe("write the result to this file, relative to the project folder, in place of returning it. An existing file is overwritten");
 
@@ -17,13 +15,6 @@ export const ProjectInput = z
   .min(1)
   .describe("the project folder, relative to the folder where the agent started. Give it when that folder is not in a project and has projects below it. The paths of this call are relative to the project folder");
 
-/** 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(),
@@ -33,7 +24,5 @@ export const WrittenOutput = {
 
 /** Writes `data` to the file `path` of the project that `project` names (or the project lookup finds), and gives what the result shows in its place. */
 export function writeOut(path: string, data: Uint8Array | string, project: string | undefined): Written {
-  const bytes = typeof data === "string" ? Buffer.from(data, "utf8") : data;
-  writeProjectFile(path, bytes, { what: "out", root: projectFolder(project) });
-  return { out: path, bytes: bytes.length, sha256: createHash("sha256").update(bytes).digest("hex") };
+  return writeReported(path, data, { what: "out", root: projectFolder(project) });
 }

package/src/mcp/server.ts

@@ -7,8 +7,10 @@ import { Server } from "@modelcontextprotocol/sdk/server/index.js";
 import { CallToolRequestSchema, ListToolsRequestSchema, type CallToolResult, type Tool as McpTool } from "@modelcontextprotocol/sdk/types.js";
 import { z } from "zod";
 
-import { formatC64Address, parseC64Address } from "../c64.ts";
+import { formatC64Address } from "../c64.ts";
+import { Byte, TOOL_INPUTS } from "./inputs.ts";
 import { LostBeforeAnswer, type ViceSessionClient } from "../host-client/vice-session.ts";
+import { isRefusal } from "../errors.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";
@@ -62,35 +64,14 @@ export type SessionSource = () => Promise<ViceSessionApi>;
 type JsonObject = Record<string, unknown>;
 
 // ---------------------------------------------------------------------------
-// Public schema primitives shared by the tool groups
-
-/** Input address: "$" and four hex digits, either case. Parses to a number. */
-export const AddressInput = z
-  .string()
-  .regex(/^\$[0-9a-fA-F]{4}$/, "must be $ followed by four hex digits, for example $c000")
-  .transform((value) => parseC64Address(value))
-  .describe("C64 address, $0000 to $ffff");
+// Public schema primitives shared by the tool groups. The inputs that change or
+// wait for the machine are in inputs.ts: the action steps take the same inputs.
 
 /** Output address: "$" and four lowercase hex digits. */
 export const AddressOutput = z.string().regex(/^\$[0-9a-f]{4}$/).describe("C64 address, $0000 to $ffff");
 
-export const Byte = z.number().int().min(0).max(255);
-
 export const HexData = z.string().regex(/^(?:[0-9a-f]{2})*$/).describe("bytes as lowercase hex, two digits per byte, no separators");
 
-/** Input bytes: hex in either case, two digits per byte, at least one byte. Parses to lowercase. */
-export const HexDataInput = z
-  .string()
-  .regex(/^(?:[0-9a-fA-F]{2})+$/, "must be hex bytes, two digits per byte, no separators, for example a9008d20d0")
-  .transform((value) => value.toLowerCase());
-
-export const SpaceInput = z.enum(SPACES).default("c64").describe("c64 is the computer. drive8 is the 1541 disk drive CPU");
-
-export const MemoryViewInput = z
-  .enum(MEMORY_VIEWS)
-  .default("cpu")
-  .describe("cpu reads what the CPU sees now (ROM and I/O where banked in). ram reads the RAM underneath (c64 only)");
-
 /** A name the agent gives to something the session keeps, such as a screen baseline or a snapshot. */
 export const TransientName = z
   .string()
@@ -132,37 +113,6 @@ export interface ToolDefinition<I extends z.ZodObject = z.ZodObject, O extends z
   run(input: z.output<I>, session: ViceSessionApi): Promise<z.input<O> | ToolOutput<z.input<O>>>;
 }
 
-/** A typed condition: register, memory or raster. No expression language. */
-export const ConditionInput = z
-  .discriminatedUnion("kind", [
-    z
-      .object({
-        kind: z.literal("register"),
-        register: z.enum(CONDITION_REGISTERS),
-        operator: z.enum(COMPARISONS),
-        value: Byte,
-      })
-      .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. True from this cycle on"),
-      })
-      .strict(),
-  ])
-  .describe("register: a CPU register compared to a byte. memory: a byte in memory compared to a byte. raster: the raster position");
-
 /** A condition as a result shows it: the input form, with the memory address as "$xxxx". */
 export const ConditionOutput = z
   .discriminatedUnion("kind", [
@@ -183,7 +133,7 @@ export function defined<T extends Record<string, unknown>>(value: T): T {
 }
 
 /** A parsed condition input as the protocol type. */
-export function toCondition(input: z.output<typeof ConditionInput>): Condition {
+export function toCondition(input: z.output<typeof TOOL_INPUTS.condition>): Condition {
   return defined(input) as Condition;
 }
 
@@ -208,8 +158,9 @@ export function toolListing(tool: ToolDefinition): McpTool {
   };
 }
 
+/** An error in the one form of the toolkit: {"error":{"code","message"}}, as a script prints it. */
 function errorResult(error: WireError): CallToolResult {
-  return { isError: true, content: [{ type: "text", text: JSON.stringify({ code: error.code, message: shownMessage(error) }) }] };
+  return { isError: true, content: [{ type: "text", text: JSON.stringify({ error: { code: error.code, message: shownMessage(error) } }) }] };
 }
 
 /** "address: Invalid string: must match ..." style messages, one sentence per problem. */
@@ -244,7 +195,7 @@ function outcome(result: CallToolResult): TraceFields {
   const first = result.content[0];
   const text = first?.type === "text" ? first.text : "";
   try {
-    return { ok: false, ...(JSON.parse(text) as WireError) };
+    return { ok: false, ...(JSON.parse(text) as { error: WireError }).error };
   } catch {
     return { ok: false, message: text };
   }
@@ -282,7 +233,7 @@ async function runCall(
     const extra = output instanceof ToolOutput ? output.content : [];
     return { content: [{ type: "text", text: JSON.stringify(result) }, ...extra], structuredContent: result };
   } catch (error) {
-    if (error instanceof WireFailure) return errorResult(error.toWire());
+    if (isRefusal(error)) return errorResult({ code: error.code, message: error.message });
     log(`${name} failed: ${error instanceof Error ? (error.stack ?? error.message) : String(error)}`);
     return errorResult(INTERNAL_FAILURE);
   }
@@ -299,7 +250,8 @@ function packageVersion(): string {
 
 const INSTRUCTIONS =
   "These tools control one live Commodore 64 emulator that belongs to this session. " +
-  "Addresses are four hex digits after a dollar sign, for example $c000. " +
+  "An address is a dollar sign and 1 to 4 hex digits, for example $c000 or $fb. A result gives four hex digits. " +
+  "An error is {\"error\": {\"code\", \"message\"}}. " +
   "Memory data is lowercase hex without separators. " +
   "Other register values and chip values are decimal numbers. " +
   "A read does not change the run state of the machine.";

package/src/mcp/tools/debug.ts

@@ -8,7 +8,8 @@ import { WireFailure } from "../../protocol/messages.ts";
 import { CHECKPOINT_ACTIONS, MAX_BACKTRACE, MAX_HISTORY, MAX_TRACE_FRAMES, MAX_TRACE_HITS, MAX_TRACE_POINTS, TRACE_KINDS, TRACE_ENDS, 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, ProjectInput, writeOut, WrittenOutput } from "../output.ts";
-import { AddressInput, AddressOutput, Byte, ConditionInput, ConditionOutput, defineTool, HexData, requireFields, showCondition, SpaceInput, toCondition } from "../server.ts";
+import { AddressInput, Byte, SpaceInput, TOOL_INPUTS } from "../inputs.ts";
+import { AddressOutput, ConditionOutput, defineTool, HexData, requireFields, showCondition, toCondition } from "../server.ts";
 import { spaced } from "./memory.ts";
 
 /** No default here: a filled-in default would count as a field the other actions refuse. */
@@ -23,7 +24,7 @@ const BreakpointOutput = z.object({
   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) });
+const WatchpointOutput = BreakpointOutput.omit({ address: true }).extend({ start: AddressOutput, end: AddressOutput, access: z.enum(WATCH_ACCESS) });
 
 function showBreakpoint(point: Breakpoint) {
   const { condition, ...rest } = point;
@@ -31,8 +32,8 @@ function showBreakpoint(point: Breakpoint) {
 }
 
 function showWatchpoint(point: Watchpoint) {
-  const { condition, ...rest } = point;
-  return { ...rest, address: formatC64Address(point.address), ...(condition === undefined ? {} : { condition: showCondition(condition) }) };
+  const { condition, address, size, ...rest } = point;
+  return { ...rest, start: formatC64Address(address), end: formatC64Address(address + size - 1), ...(condition === undefined ? {} : { condition: showCondition(condition) }) };
 }
 
 export const c64Breakpoint = defineTool({
@@ -49,7 +50,7 @@ export const c64Breakpoint = defineTool({
       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"),
+      condition: TOOL_INPUTS.condition.optional().describe("add only: stop only when this is true"),
       id: Id.optional().describe("remove, enable and disable only"),
     })
     .strict(),
@@ -83,18 +84,18 @@ export const c64Watchpoint = defineTool({
   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. ` +
+    `Action add sets one from start to end (at most ${MAX_WATCH_SIZE} bytes, end defaults to start), 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"),
+      start: AddressInput.optional().describe("add only: the first address"),
+      end: AddressInput.optional().describe("add only: the last address. Default start"),
       access: z.enum(WATCH_ACCESS).optional().describe("add only"),
       space: OptionalSpace,
-      condition: ConditionInput.optional().describe("add only: stop only when this is true"),
+      condition: TOOL_INPUTS.condition.optional().describe("add only: stop only when this is true"),
       id: Id.optional().describe("remove, enable and disable only"),
     })
     .strict(),
@@ -112,11 +113,15 @@ export const c64Watchpoint = defineTool({
       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"]);
+    requireFields(action, fields, ["start", "end", "access", "space", "condition"], ["start", "access"]);
+    const start = fields.start!;
+    const end = fields.end ?? start;
+    if (end < start) throw new WireFailure("invalid-input", "end must not be before start.");
+    if (end - start + 1 > MAX_WATCH_SIZE) throw new WireFailure("invalid-input", `A watchpoint covers at most ${MAX_WATCH_SIZE} bytes. This one covers ${end - start + 1}.`);
     const added = await session.watchpoint({
       action,
-      address: fields.address!,
-      size: fields.size ?? 1,
+      address: start,
+      size: end - start + 1,
       access: fields.access!,
       space: fields.space ?? "c64",
       ...(fields.condition === undefined ? {} : { condition: toCondition(fields.condition) }),

package/src/mcp/tools/execution.ts

@@ -3,8 +3,9 @@
 import { z } from "zod";
 
 import { formatC64Address } from "../../c64.ts";
-import { COMPARISONS, EXECUTION_ACTIONS, MAX_EXECUTION_COUNT, MAX_HISTORY, MAX_TIMEOUT_FRAMES, POINT_STOP_REASONS, RUN_STATES, SPACES, STOP_REASONS, type RunTarget } from "../../protocol/vice.ts";
-import { AddressInput, AddressOutput, Byte, ConditionInput, defineTool, MemoryViewInput, SpaceInput, toCondition, ToolOutput } from "../server.ts";
+import { EXECUTION_ACTIONS, MAX_EXECUTION_COUNT, MAX_HISTORY, MAX_TIMEOUT_FRAMES, POINT_STOP_REASONS, RUN_STATES, SPACES, STOP_REASONS, type RunTarget } from "../../protocol/vice.ts";
+import { Byte, SpaceInput, TOOL_INPUTS } from "../inputs.ts";
+import { AddressOutput, defineTool, toCondition, ToolOutput } from "../server.ts";
 import { c64Observe } from "./video.ts";
 
 export const c64Execution = defineTool({
@@ -57,34 +58,6 @@ export const c64Execution = defineTool({
   },
 });
 
-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",
@@ -103,8 +76,8 @@ export const c64RunUntil = defineTool({
     "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),
+      target: TOOL_INPUTS.runTarget,
+      timeoutFrames: TOOL_INPUTS.timeoutFrames,
       observe: c64Observe.inputSchema.optional().describe("what to read at the stop, as for c64_observe"),
       history: z.number().int().min(1).max(MAX_HISTORY).optional().describe("the number of instructions before the stop to give"),
     })

package/src/mcp/tools/input.ts

@@ -2,9 +2,9 @@
 
 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 { keyboardBytes } from "../../host-client/steps.ts";
+import { TOOL_INPUTS } from "../inputs.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");
@@ -15,35 +15,16 @@ 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. " +
+    "No tool presses one key of the keyboard matrix. For one specific key, ask the user to press it in the window, or give a press step in a record file of c64-testing. " +
     '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(),
+  inputSchema: TOOL_INPUTS.keyboard,
   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.`);
-    }
+    // The schema checked the keys: keyboardBytes gives bytes here.
+    const petscii = keyboardBytes(input) as Uint8Array;
     return session.keyboard(petscii);
   },
 });
@@ -55,13 +36,7 @@ export const c64Joystick = defineTool({
     "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(),
+  inputSchema: TOOL_INPUTS.joystick,
   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) {

package/src/mcp/tools/media.ts

@@ -8,7 +8,8 @@ import { formatC64Address } from "../../c64.ts";
 import { projectFolder, readProjectFile } from "../../host-client/transfer.ts";
 import { AUTOSTART_TYPES, DISK_TYPES, MAX_SNAPSHOTS, RUN_STATES } from "../../protocol/vice.ts";
 import { OutInput, ProjectInput, writeOut, WrittenOutput } from "../output.ts";
-import { AddressInput, AddressOutput, defineTool, requireFields, TransientName } from "../server.ts";
+import { AddressInput } from "../inputs.ts";
+import { AddressOutput, defineTool, requireFields, TransientName } from "../server.ts";
 
 const ProjectPath = z.string().min(1).describe("path relative to the project folder, for example build/game.prg");
 
@@ -91,11 +92,11 @@ export const c64Snapshot = defineTool({
     "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.`,
+    `Action list gives the names, and action remove 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"),
+      action: z.enum(["save", "restore", "list", "remove"]),
+      name: TransientName.optional().describe("save and remove, and restore without file: 1 to 64 letters, digits, dots, underscores or hyphens"),
       out: OutInput.optional().describe("save only: also write the snapshot to this project file, for example snapshots/room0.vsf. An existing file is overwritten"),
       file: ProjectPath.optional().describe("restore only: a .vsf file in the project, in place of name"),
       project: ProjectInput.optional().describe("save with out, and restore with file: the project folder, relative to the folder where the agent started. Give it when that folder is not in a project and has projects below it"),
@@ -107,7 +108,7 @@ export const c64Snapshot = defineTool({
     restored: z.boolean().optional(),
     state: z.enum(RUN_STATES).optional(),
     snapshots: z.array(z.string()).optional(),
-    discarded: z.boolean().optional(),
+    removed: z.boolean().optional(),
     ...WrittenOutput,
   }),
   readOnly: false,

package/src/mcp/tools/memory.ts

@@ -7,7 +7,8 @@ import { formatC64Address } from "../../c64.ts";
 import { WireFailure } from "../../protocol/messages.ts";
 import { MAX_COMPARE_DIFFERENCES, MAX_COMPARE_SIZE, MAX_DISASSEMBLE, MAX_MEMORY_READ, MAX_MEMORY_WRITE, MAX_SEARCH_PATTERN, MAX_SEARCH_RESULTS, type RegisterValues } from "../../protocol/vice.ts";
 import { OutInput, ProjectInput, writeOut, WrittenOutput } from "../output.ts";
-import { AddressInput, AddressOutput, Byte, defineTool, HexData, HexDataInput, MemoryViewInput, requireFields, SpaceInput } from "../server.ts";
+import { AddressInput, Byte, MemoryViewInput, SpaceInput, TOOL_INPUTS } from "../inputs.ts";
+import { AddressOutput, defineTool, HexData, requireFields } from "../server.ts";
 
 /** With out, a read or a disassembly can be larger than one answer of the session: it is read in parts. */
 const MAX_MEMORY_READ_OUT = 0x10000;
@@ -61,14 +62,7 @@ export const c64MemoryWrite = defineTool({
     "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(),
+  inputSchema: TOOL_INPUTS.memoryWrite,
   outputSchema: z.object({ address: AddressOutput, bytesWritten: z.number().int().min(1).max(MAX_MEMORY_WRITE) }),
   readOnly: false,
   async run(input, session) {
@@ -77,47 +71,26 @@ export const c64MemoryWrite = defineTool({
   },
 });
 
-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. " +
+    "Read or write the CPU registers: pc, a, x, y, sp and the status flags n, v, b, d, i, z and c. " +
+    "Action read reads them. This does not change the run state of the machine. " +
+    "Action write writes the registers that values names and returns all registers. Stop the CPU before you use write. " +
     "Use space drive8 for the CPU of the 1541 disk drive.",
   inputSchema: z
     .object({
-      action: z.enum(["get", "set"]),
+      action: z.enum(["read", "write"]),
       space: SpaceInput,
-      values: RegisterValuesInput.optional().describe("set only: the registers to write"),
+      values: TOOL_INPUTS.registerValues.optional().describe("write only: the registers to write"),
     })
     .strict(),
-  outputSchema: z.object({ pc: AddressOutput, a: Byte, x: Byte, y: Byte, sp: Byte, flags: Flags }),
+  outputSchema: z.object({ pc: AddressOutput, a: Byte, x: Byte, y: Byte, sp: Byte, flags: TOOL_INPUTS.flags }),
   readOnly: false,
   async run(input, session) {
     let registers;
-    if (input.action === "get") {
+    if (input.action === "read") {
       requireFields(input.action, { values: input.values }, []);
       registers = await session.registersGet(input.space);
     } else {
@@ -130,7 +103,7 @@ export const c64Registers = defineTool({
       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.");
+        throw new WireFailure("invalid-input", "values must name at least one register for action write.");
       }
       registers = await session.registersSet(input.space, values);
     }

package/src/mcp/tools/video.ts

@@ -7,7 +7,8 @@ import { formatC64Address, formatSprite, formatVicii } from "../../c64.ts";
 import { WireFailure } from "../../protocol/messages.ts";
 import { CIA_SELECTIONS, MAX_MASK_RECTANGLES, MAX_MEMORY_READ, MAX_OBSERVE_BYTES, MAX_OBSERVE_RANGES, SPACES, VICII_MODES, type ObserveParams } from "../../protocol/vice.ts";
 import { OutInput, ProjectInput, writeOut, WrittenOutput } from "../output.ts";
-import { AddressInput, AddressOutput, Byte, defineTool, HexData, MemoryViewInput, requireFields, SpaceInput, ToolOutput, TransientName } from "../server.ts";
+import { AddressInput, Byte, MemoryViewInput, SpaceInput } from "../inputs.ts";
+import { AddressOutput, defineTool, HexData, requireFields, 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.";
@@ -138,13 +139,13 @@ export const c64Screen = defineTool({
     "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. " +
+    "Action list gives the baseline names. Action remove 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"),
+      action: z.enum(["capture", "compare", "list", "remove"]),
+      baseline: TransientName.optional().describe("capture: keep the frame under this name. compare and remove: 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"),
@@ -162,7 +163,7 @@ export const c64Screen = defineTool({
     mismatchRatio: z.number().min(0).max(1).optional(),
     bounds: Rectangle.optional(),
     baselines: z.array(z.string()).optional(),
-    discarded: z.boolean().optional(),
+    removed: z.boolean().optional(),
     ...WrittenOutput,
   }),
   readOnly: false,