@henols/c64-re-tools 2.1.0 → 2.1.2

package/src/host/vice/session.ts

@@ -30,6 +30,8 @@ import {
 import { decodeProgramCounter, MonitorConnectionError, MonitorError, MonitorTimeoutError, ResponseType, type MonitorResponse } from "./binary-monitor.ts";
 import { decodeCia, decodeSid, decodeSprite, decodeVicii } from "./chips.ts";
 import { compareFrames, differenceImage } from "./screen.ts";
+import { isRefusal } from "../../errors.ts";
+import { checkMedia } from "../../media.ts";
 import { launchVice, startErrorLines, type ViceMode, type ViceProcess } from "./process.ts";
 import { TextMonitorError, TextMonitorTimeoutError } from "./text-monitor.ts";
 
@@ -187,6 +189,23 @@ export class ViceSession implements ViceSessionHandle {
   #haltCount = 0;
   /** What stopped the machine last, when a user breakpoint or watchpoint or a JAM did; cleared when it runs again. */
   #lastStop: { stopReason: PointStopReason; pointId?: number } | undefined;
+  /**
+   * The pc of the JAM that holds the CPU. A jammed CPU runs again only after a
+   * reset, a snapshot restore or an autostart: VICE 3.10 keeps it jammed after a
+   * pc write, and reports the JAM only once.
+   */
+  #jammed: number | undefined;
+  /**
+   * An autostart can still be loading: VICE goes on with it after a snapshot
+   * restore and writes the program over the restored memory. Only a reset stops it.
+   */
+  #autostarting = false;
+  /** The C64 clock just after the last snapshot restore: VICE keeps the history of before it. */
+  #historySince: bigint | undefined;
+  /** VICE records no CPU history after a JAM until the next reset. */
+  #historyStopped = false;
+  /** The CPU ran again after a JAM without a reset: the CPU history that VICE gives is old. */
+  #historyOld = false;
   #queue: Promise<unknown> = Promise.resolve();
   #closed = false;
   #lost = false;
@@ -386,6 +405,7 @@ export class ViceSession implements ViceSessionHandle {
       case "autostart": {
         const { type, index, run } = params as ViceOperations["autostart"]["params"];
         const bytes = onlyAttachment(attachments);
+        checkMedia(type, bytes);
         if (index > 0 && this.#directory !== undefined && isOneOf(DISK_IMAGE_TYPES, type)) checkDirectoryEntry(await this.#directory(type, bytes), index);
         const file = this.#stage(bytes, type);
         // VICE keeps a cartridge through every reset and autostart, as a real C64 does.
@@ -404,6 +424,8 @@ export class ViceSession implements ViceSessionHandle {
           centred.push(port);
         }
         await this.#runningCommand(() => this.#machine.autostart(file, index, run));
+        this.#clearJam();
+        this.#autostarting = true;
         if (type === "crt") this.#cartridge = true;
         this.#replaceStaged(stagedKind(type), file);
         // A reset sets the CPU clock back, so the stopwatch starts again.
@@ -412,7 +434,9 @@ export class ViceSession implements ViceSessionHandle {
       }
       case "diskAttach": {
         const { type } = params as ViceOperations["diskAttach"]["params"];
-        const file = this.#stage(onlyAttachment(attachments), type);
+        const bytes = onlyAttachment(attachments);
+        checkMedia(type, bytes);
+        const file = this.#stage(bytes, type);
         await this.#observe(() => this.#machine.attachDisk(file));
         this.#replaceStaged("disk", file);
         return { attached: true };
@@ -431,7 +455,7 @@ export class ViceSession implements ViceSessionHandle {
       case "screenCapture": {
         const { baseline } = params as ViceOperations["screenCapture"]["params"];
         if (baseline !== undefined && !this.#baselines.has(baseline) && this.#baselines.size >= MAX_BASELINES) {
-          throw new WireFailure("limit-exceeded", `A session keeps at most ${MAX_BASELINES} baselines. Discard one first.`);
+          throw new WireFailure("limit-exceeded", `A session keeps at most ${MAX_BASELINES} baselines. Remove one first with c64_screen action remove.`);
         }
         const shot = await this.#observe(() => this.#machine.captureFrame(this.#videoStandard));
         if (baseline !== undefined) this.#baselines.set(baseline, shot);
@@ -530,15 +554,25 @@ export class ViceSession implements ViceSessionHandle {
     if (status.state === "stopped") {
       status.pc = await this.#pc();
       // VICE 3.9 sends no JAM event: the opcode at the pc tells.
-      const stop = this.#lastStop ?? ((await this.#jammedAt(status.pc)) ? { stopReason: "jam" as const } : undefined);
+      const stop = this.#lastStop ?? ((await this.#jamAt(status.pc)) ? { stopReason: "jam" as const } : undefined);
       if (stop !== undefined) Object.assign(status, stop);
+      // A point in the drive stopped it: the pc is the drive's, as advance-frames and run-until give it.
+      const point = status.pointId === undefined ? undefined : (status.stopReason === "watchpoint" ? this.#watchpoints : this.#breakpoints).get(status.pointId);
+      status.space = point?.space === "drive8" ? "drive8" : "c64";
+      if (status.space === "drive8") status.pc = (await this.#machine.readRegisters("drive8")).pc;
     }
     return status;
   }
 
   async #execution(params: ExecutionParams): Promise<ExecutionResult> {
+    if (params.space === "drive8" && (params.action === "pause" || params.action === "resume")) {
+      throw new WireFailure("unsupported-in-space", `${params.action} stops or runs the whole machine, the computer and the disk drive together: use space c64.`);
+    }
     if (params.action === "resume") {
-      if (this.#state === "stopped") await this.#resume();
+      if (this.#state === "stopped") {
+        await this.#refuseJammed("resume");
+        await this.#resume();
+      }
       return { state: "running" };
     }
     if (params.action === "pause") {
@@ -546,6 +580,9 @@ export class ViceSession implements ViceSessionHandle {
       // A drive checkpoint can stop the machine just before the pause does.
       return { state: "stopped", pc: (await this.#completeDriveStop()) ?? (await this.#pc()) };
     }
+    if (params.space === "drive8" && params.action === "advance-frames") {
+      throw new WireFailure("unsupported-in-space", "advance-frames counts the video frames of the computer: use space c64. A breakpoint or watchpoint in space drive8 also stops it.");
+    }
     if (params.space === "drive8") {
       // Stock VICE runs the 1541 CPU in batches that catch up with the computer's clock;
       // neither monitor can stop it after exactly one of its instructions.
@@ -565,13 +602,16 @@ export class ViceSession implements ViceSessionHandle {
       const outcome = await this.#runFrames(params.count, undefined, params.anchor);
       return {
         state: "stopped",
-        pc: outcome.pc,
+        // A stop event carries the computer's PC; a stop in the drive reports the drive's.
+        pc: outcome.space === "drive8" ? (await this.#machine.readRegisters("drive8")).pc : outcome.pc,
+        space: outcome.space,
         advancedFrames: outcome.frames,
         stopReason: outcome.end === "target" ? "frames" : outcome.end,
         ...(outcome.pointId === undefined ? {} : { pointId: outcome.pointId }),
       };
     }
     await this.#stop();
+    await this.#refuseJammed(params.action);
     if (params.action === "until-return") {
       const stopped = this.#nextStop(this.#untilReturnLimitMs);
       await this.#resumingCommand(() => this.#machine.untilReturn());
@@ -599,6 +639,7 @@ export class ViceSession implements ViceSessionHandle {
 
   async #reset(params: { mode: "soft" | "hard"; run: boolean }): Promise<{ state: RunState; pc?: number }> {
     await this.#stop();
+    this.#clearJam();
     // A reset sets the CPU clock back, so the stopwatch starts again.
     this.#timingStart = 0n;
     if (params.run) {
@@ -637,11 +678,15 @@ export class ViceSession implements ViceSessionHandle {
     const start = anchor ?? (await this.#machine.rasterPosition());
     const arming = rasterLinesExpression((start.line + Math.floor(lines / 2)) % lines, lines);
     const ending = rasterWindowExpression(start.line, start.cycle, lines);
+    const startPc = await this.#pc();
+    if (await this.#jamAt(startPc)) return { end: "jam", frames: 0, pc: startPc, space: "c64" };
     const clock = await this.#machine.addCheckpoint({ start: 0x0000, end: 0xffff, operation: 0x04, space: "c64" });
     try {
       await this.#machine.setCondition(clock, arming);
       let armingPhase = true;
       let frames = 0;
+      // VICE reports a JAM only once until a reset: a jammed CPU stops the clock at the same pc again and again.
+      let clockPc = startPc;
       for (;;) {
         const next = this.#nextStop(HALF_FRAME_LIMIT_MS);
         await this.#resume();
@@ -652,6 +697,8 @@ export class ViceSession implements ViceSessionHandle {
         }
         const end = this.#stopCause(stop, clock, target?.checkpoint);
         if (end === "clock") {
+          if (stop.pc === clockPc && (await this.#jamAt(stop.pc))) return { end: "jam", frames, pc: stop.pc, space: "c64" };
+          clockPc = stop.pc;
           if (armingPhase) {
             await this.#machine.setCondition(clock, ending);
             if (target?.deferred) {
@@ -667,7 +714,7 @@ export class ViceSession implements ViceSessionHandle {
           continue;
         }
         if (end === "unknown") {
-          if (await this.#jammedAt(stop.pc)) return { end: "jam", frames, pc: stop.pc, space: "c64" };
+          if (await this.#jamAt(stop.pc)) return { end: "jam", frames, pc: stop.pc, space: "c64" };
           throw new WireFailure("operation-failed", "The emulator stopped the machine for a reason outside this run.");
         }
         // A drive stop is completed before the result names the computer's pc; `space` says which CPU stopped.
@@ -699,6 +746,9 @@ export class ViceSession implements ViceSessionHandle {
     const points: number[] = [];
     const hits: TraceHit[] = [];
     let frames = 0;
+    const startPc = await this.#pc();
+    if (await this.#jamAt(startPc)) return { hits, frames, end: "jam", pc: startPc };
+    let clockPc = startPc;
     const clock = await this.#machine.addCheckpoint({ start: 0x0000, end: 0xffff, operation: 0x04, space: "c64" });
     try {
       for (const point of params.points) points.push(await this.#machine.addCheckpoint({ start: point.start, end: point.end, operation: operation[point.kind], space: "c64" }));
@@ -718,6 +768,8 @@ export class ViceSession implements ViceSessionHandle {
           if (hits.length >= params.maxHits) return { hits, frames, end: "hits", pc: stop.pc };
         }
         if (stop.hits.includes(clock)) {
+          if (stop.pc === clockPc && (await this.#jamAt(stop.pc))) return { hits, frames, end: "jam", pc: stop.pc };
+          clockPc = stop.pc;
           if (armingPhase) await this.#machine.setCondition(clock, ending);
           else {
             frames++;
@@ -730,7 +782,7 @@ export class ViceSession implements ViceSessionHandle {
         if (traced.length > 0) continue;
         const point = this.#userPoint(stop.hits);
         if (point !== undefined) return { hits, frames, end: point.stopReason, pc: stop.pc };
-        if (await this.#jammedAt(stop.pc)) return { hits, frames, end: "jam", pc: stop.pc };
+        if (await this.#jamAt(stop.pc)) return { hits, frames, end: "jam", pc: stop.pc };
         throw new WireFailure("operation-failed", "The emulator stopped the machine for a reason outside this trace.");
       }
     } finally {
@@ -844,9 +896,43 @@ export class ViceSession implements ViceSessionHandle {
     return undefined;
   }
 
-  async #jammedAt(pc: number): Promise<boolean> {
+  /**
+   * True when a JAM holds the CPU at `pc`: the session saw a JAM since the last
+   * reset, restore or autostart, or the opcode at `pc` is a JAM. The CPU stops
+   * on such an opcode, so it executes nothing more. The session keeps the JAM.
+   */
+  async #jamAt(pc: number): Promise<boolean> {
+    if (this.#jammed !== undefined) return true;
     const opcode = await this.#machine.readMemory({ address: pc, size: 1, space: "c64", view: "cpu" });
-    return JAM_OPCODES.has(Number.parseInt(opcode, 16));
+    if (!JAM_OPCODES.has(Number.parseInt(opcode, 16))) return false;
+    this.#jam(pc);
+    return true;
+  }
+
+  #jam(pc: number): void {
+    this.#jammed = pc;
+    this.#historyStopped = true;
+  }
+
+  /** A reset or an autostart starts a jammed CPU and the CPU history again. */
+  #clearJam(): void {
+    this.#autostarting = false;
+    // A reset sets the clock back to 0: the history from before it is of this run again.
+    this.#historySince = undefined;
+    this.#jammed = undefined;
+    this.#historyStopped = false;
+    this.#historyOld = false;
+  }
+
+  /** Refuses an action that needs the CPU to execute, while a JAM holds it. */
+  async #refuseJammed(action: string): Promise<void> {
+    const pc = await this.#pc();
+    if (!(await this.#jamAt(pc))) return;
+    throw new WireFailure(
+      "operation-failed",
+      `The CPU is jammed by the JAM opcode at ${formatC64Address(this.#jammed ?? pc)}, so ${action} cannot execute an instruction. ` +
+        "The CPU runs again only after c64_reset, a snapshot restore or c64_autostart.",
+    );
   }
 
   /** Runs until a target is reached or `timeoutFrames` frames pass. */
@@ -1050,10 +1136,18 @@ export class ViceSession implements ViceSessionHandle {
    * stop, whose position is known, mapped back through the frame.
    */
   async #cpuHistory(params: { limit: number; space: "c64" | "drive8" }): Promise<{ entries: HistoryEntry[] }> {
+    if (params.space === "c64" && this.#historyOld) {
+      throw new WireFailure(
+        "operation-failed",
+        "VICE records no CPU history after a JAM until the next reset, and the CPU ran after the JAM. The history would show old instructions. " +
+          "Use c64_reset to record again, or use c64_trace.",
+      );
+    }
     return this.#observe(async () => {
-      const raw = await this.#machine.history(params.limit, params.space);
-      if (params.space === "drive8") return { entries: raw.map(({ clock: _clock, ...entry }) => entry) };
+      const all = await this.#machine.history(params.limit, params.space);
+      if (params.space === "drive8") return { entries: all.map(({ clock: _clock, ...entry }) => entry) };
       const now = await this.#machine.clock();
+      const raw = entriesSince(all, this.#historySince, now);
       const position = await this.#machine.rasterPosition();
       const { lines, cycles } = RASTER[this.#videoStandard];
       const frame = BigInt(lines * cycles);
@@ -1128,7 +1222,7 @@ export class ViceSession implements ViceSessionHandle {
     const existing = this.#snapshots.get(params.name);
     if (params.action === "save") {
       if (existing === undefined && this.#snapshots.size >= MAX_SNAPSHOTS) {
-        throw new WireFailure("limit-exceeded", `A session keeps at most ${MAX_SNAPSHOTS} snapshots. Discard one first.`);
+        throw new WireFailure("limit-exceeded", `A session keeps at most ${MAX_SNAPSHOTS} snapshots. Remove one first with action remove.`);
       }
       const file = existing ?? join(this.#workDir, `snapshot-${++this.#snapshotFiles}.vsf`);
       await this.#observe(() => this.#machine.saveSnapshot(file));
@@ -1148,7 +1242,13 @@ export class ViceSession implements ViceSessionHandle {
   async #restoreFrom(file: string): Promise<{ restored: true; state: "stopped" }> {
     await this.#stop();
     const elapsed = (await this.#machine.clock()) - this.#timingStart;
+    // The restore replaces the whole machine state, so the reset that stops the autostart leaves no trace.
+    if (this.#autostarting) await this.#reset({ mode: "soft", run: false });
     await this.#machine.restoreSnapshot(file);
+    this.#historySince = await this.#machine.clock();
+    // A restore starts a jammed CPU again, but VICE still records no CPU history.
+    this.#jammed = undefined;
+    if (this.#historyStopped) this.#historyOld = true;
     this.#state = "stopped";
     // The cycle clock jumped with the restore; the stopwatch keeps its reading, as a window move does.
     this.#timingStart = (await this.#machine.clock()) - elapsed;
@@ -1168,13 +1268,26 @@ export class ViceSession implements ViceSessionHandle {
     // Checked before the machine stops: VICE gives no reason for a file that is no snapshot.
     if (!bytes.subarray(0, VSF_MAGIC.length).equals(VSF_MAGIC)) throw new WireFailure("invalid-input", "The file is not a VICE snapshot file (.vsf). Give a file that c64_snapshot save wrote.");
     const file = this.#stage(bytes, "vsf");
+    // VICE resets the machine after a snapshot file that it cannot read: a backup keeps the state before the restore.
+    const backup = join(this.#workDir, "before-restore.vsf");
+    await this.#stop();
+    await this.#machine.saveSnapshot(backup);
     try {
       return await this.#restoreFrom(file);
     } catch (error) {
+      const kept = await this.#restoreFrom(backup).then(
+        () => true,
+        () => false,
+      );
+      if (!kept) throw new WireFailure("machine-state-lost", "The emulator did not restore this snapshot file, and the machine state from before the restore is lost. Load the program again.");
       if (error instanceof WireFailure) throw error;
-      throw new WireFailure("invalid-input", "The emulator did not restore this snapshot file. A snapshot file restores only in the emulator version and with the machine settings that saved it.");
+      throw new WireFailure(
+        "invalid-input",
+        "The emulator did not restore this snapshot file. The machine state is as before. A snapshot file restores only in the emulator version and with the machine settings that saved it.",
+      );
     } finally {
       rmSync(file, { force: true });
+      rmSync(backup, { force: true });
     }
   }
 
@@ -1255,6 +1368,8 @@ export class ViceSession implements ViceSessionHandle {
       if (this.#closed) throw new WireFailure("machine-unavailable", "The emulator session is closed.");
       this.#vice = vice;
       this.#adapter = adapter;
+      // A new emulator: no JAM holds its CPU, and it records CPU history.
+      this.#clearJam();
       this.#mode = mode;
       for (const [point, checkpoint] of points) point.checkpoint = checkpoint;
       this.#timingStart = clock - handover.elapsed;
@@ -1446,6 +1561,8 @@ export class ViceSession implements ViceSessionHandle {
 
   async #translate(error: unknown, runningBefore: boolean, halts: number): Promise<unknown> {
     if (error instanceof WireFailure) return error;
+    // A refusal of a shared module (for example the media check) goes on the wire as the host's own.
+    if (isRefusal(error)) return new WireFailure(error.code, error.message);
     if (this.#closed) return new WireFailure("machine-unavailable", "The emulator session is closed.");
     if (error instanceof MonitorConnectionError || error instanceof TextMonitorError || error instanceof StepTimeout) {
       this.#log(error.message);
@@ -1515,6 +1632,7 @@ export class ViceSession implements ViceSessionHandle {
       if (stop.hits.length > 0 || event.type === ResponseType.jam) this.#haltCount++;
       if (stop.hits.some((hit) => this.#adapter?.isDriveCheckpoint(hit))) this.#driveStop = true;
       this.#lastStop = event.type === ResponseType.jam ? { stopReason: "jam" } : this.#userPoint(stop.hits);
+      if (event.type === ResponseType.jam) this.#jam(stop.pc);
       this.#checkpointHits = [];
       this.#state = "stopped";
       this.#stopWaiters = this.#stopWaiters.filter((waiter) => !waiter(stop));
@@ -1525,6 +1643,23 @@ export class ViceSession implements ViceSessionHandle {
   }
 }
 
+/**
+ * The history entries (oldest first) that the CPU executed after a restore at
+ * clock `since`, with the clock at `now`: the last entries, back to the first
+ * one outside since to now or the first one whose clock does not go up to the
+ * next. The others are of before the restore.
+ */
+export function entriesSince<T extends { clock: bigint }>(entries: readonly T[], since: bigint | undefined, now: bigint): T[] {
+  if (since === undefined) return [...entries];
+  let first = entries.length;
+  while (first > 0) {
+    const entry = entries[first - 1]!;
+    if (entry.clock < since || entry.clock > now || (first < entries.length && entry.clock >= entries[first]!.clock)) break;
+    first--;
+  }
+  return entries.slice(first);
+}
+
 /** The one attachment of an operation that takes a file (see attachmentCount); refuses any other count. */
 function onlyAttachment(attachments: Buffer[]): Buffer {
   const [bytes] = attachments;

package/src/host-client/image.ts

@@ -21,18 +21,50 @@ export interface Image {
   stages?: Array<Record<string, unknown>>;
 }
 
-/** Reads an image.json or a PRG, relative to the project folder. */
+/** The kinds of media files that are no PRG, by extension. */
+const MEDIA_KINDS: Record<string, string> = {
+  d64: "a disk image",
+  d71: "a disk image",
+  d81: "a disk image",
+  g64: "a disk image",
+  x64: "a disk image",
+  t64: "a tape file",
+  tap: "a tape file",
+  crt: "a cartridge file",
+};
+
+/** The remedy for a disk, tape or cartridge file where a PRG must be: get the PRG out of it. */
+export const MEDIA_REMEDY = "Get the PRG out of it with disk.ts read (or disk.ts crt for a cartridge) of the c64-disk skill";
+
+/** Refuses a disk, tape or cartridge file by its extension (`type`, lowercase, without the dot): invalid-input with `remedy`. */
+function refuseMedia(path: string, type: string, remedy: string): void {
+  const media = MEDIA_KINDS[type];
+  if (media !== undefined) throw new Refusal("invalid-input", `${path} is ${media} (.${type}), not a PRG. ${remedy}.`);
+}
+
+/**
+ * Reads a PRG of the project: a 2-byte load address, and bytes that end at
+ * $ffff or before. Refuses a disk, tape or cartridge file and any other file
+ * that is no PRG with invalid-input; `remedy` tells what to do in its place.
+ */
+export function readPrg(path: string, remedy = MEDIA_REMEDY): { bytes: Buffer; start: number; end: number; body: Uint8Array } {
+  const { bytes, type } = readProjectFile(path);
+  refuseMedia(path, type, remedy);
+  try {
+    return { bytes, ...prgRange(bytes) };
+  } catch (error) {
+    if (isRefusal(error)) throw new Refusal("invalid-input", `${path} is not a PRG: ${error.message} ${remedy}.`);
+    throw error;
+  }
+}
+
+/** Reads an image.json or a PRG, relative to the project folder. Refuses a disk, tape or cartridge file as readPrg does. */
 export function readImage(path: string): Image {
-  const { bytes } = readProjectFile(path);
   if (!path.endsWith(".json")) {
-    let range: ReturnType<typeof prgRange>;
-    try {
-      range = prgRange(bytes);
-    } catch (error) {
-      throw new Refusal("invalid-input", `${path}: ${(error as Error).message}`);
-    }
+    const range = readPrg(path);
     return { segments: [{ start: range.start, end: range.end }], byteAt: (address) => range.body[address - range.start]! };
   }
+  const { bytes } = readProjectFile(path);
   const fail = (what: string): never => {
     throw new Refusal("invalid-input", `${path} is not an image.json of the c64-unpacker skill: ${what}`);
   };

package/src/host-client/steps.ts

@@ -63,6 +63,8 @@ export type ActionStep =
 
 export const ACTION_STEP_KINDS = ["write", "registers", "joystick", "type", "press", "frames", "runUntil"] as const;
 export type ActionStepKind = (typeof ACTION_STEP_KINDS)[number];
+/** The step kinds that VICE runs: all but press, which only the replay core has. */
+export const VICE_STEP_KINDS = ACTION_STEP_KINDS.filter((kind) => kind !== "press");
 
 /** The fields of each object of the steps: the same as the inputs of the MCP tools. */
 export const STEP_FIELDS = {
@@ -110,6 +112,32 @@ export function keyboardBytes(input: { mode: "text" | "petscii"; text?: string |
   }
 }
 
+/**
+ * One line of JSON with a space after each colon and comma: the form that a
+ * refusal tells the caller to write.
+ */
+export function jsonLine(value: unknown): string {
+  if (Array.isArray(value)) return `[${value.map(jsonLine).join(", ")}]`;
+  if (isObject(value)) return `{${Object.entries(value).filter(([, item]) => item !== undefined).map(([key, item]) => `${JSON.stringify(key)}: ${jsonLine(item)}`).join(", ")}}`;
+  return JSON.stringify(value) ?? "null";
+}
+
+/** Field names of the 2.0 files and what a 2.1 object has in their place, when it has that field. */
+const RENAMED: Record<string, Array<{ field: string; write: string }>> = {
+  at: [
+    { field: "address", write: "address" },
+    { field: "start", write: "start" },
+  ],
+  bytes: [{ field: "data", write: 'data, the bytes as hex text, for example "data": "a900",' }],
+  equals: [{ field: "operator", write: '"operator": "eq" and "value"' }],
+};
+
+/** What to write in place of a field of the 2.0 files, for an object with these fields; undefined when the field has no 2.1 name there. */
+export function renamedField(key: string, fields: readonly string[]): string | undefined {
+  const renamed = RENAMED[key]?.find((item) => fields.includes(item.field));
+  return renamed === undefined ? undefined : `${key} is a 2.0 field. Write ${renamed.write} in place of ${key}`;
+}
+
 /** The checks of one input: `fail` names the field of the problem. */
 class Fields {
   readonly #value: Record<string, unknown>;
@@ -121,7 +149,11 @@ class Fields {
     this.#fail = fail;
     if (!isObject(value)) fail(`${where} must be an object with ${fields.join(", ")}`);
     this.#value = value as Record<string, unknown>;
-    for (const key of Object.keys(this.#value)) if (!fields.includes(key)) fail(`${where} has the field ${key}, which it does not take. Its fields are ${fields.join(", ")}`);
+    for (const key of Object.keys(this.#value)) {
+      if (fields.includes(key)) continue;
+      const renamed = renamedField(key, fields);
+      fail(`${where} has the field ${key}, which it does not take. ${renamed === undefined ? "" : `${renamed}. `}Its fields are ${fields.join(", ")}`);
+    }
   }
 
   fail(field: string, message: string): never {
@@ -256,22 +288,90 @@ function checkInput(kind: ActionStepKind, value: unknown, at: string, fail: (mes
   }
 }
 
+/** A "$xxxx" text of a number, or the value as it is. */
+const asAddress = (value: unknown) => (isInteger(value, 0, 0xffff) ? `$${value.toString(16).padStart(4, "0")}` : value);
+
+/** The hex text of a list of bytes, or the value as it is. */
+const asHex = (value: unknown) => (Array.isArray(value) && value.every((byte) => isInteger(byte, 0, 0xff)) ? Buffer.from(value as number[]).toString("hex") : value);
+
+/** A runUntil target from the 2.0 input: at (with raster), raster, or memory with at and equals. */
+function targetOf(input: Record<string, unknown>): unknown {
+  if ("target" in input) return input.target;
+  if (isObject(input.memory)) return { kind: "memory", address: input.memory.at ?? input.memory.address, operator: "eq", value: input.memory.equals };
+  if ("at" in input) return { kind: "address", address: input.at, ...(input.raster === undefined ? {} : { condition: { kind: "raster", line: input.raster } }) };
+  return { kind: "raster", line: input.raster };
+}
+
+/**
+ * The 2.1 form of a step that has a form of the 2.0 files: the 2.0 fields
+ * that it has and the step to write. Undefined when the step has no 2.0 form.
+ * Keys of the step other than its kind (for example side) stay.
+ */
+export function newStepForm(kind: string, step: Record<string, unknown>): { fields: string[]; step: Record<string, unknown> } | undefined {
+  const input = step[kind];
+  const { [kind]: _input, ...rest } = step;
+  const form = (fields: string[], value: unknown, others = rest) => ({ fields, step: { [kind]: value, ...others } });
+  switch (kind) {
+    case "runUntil": {
+      const { timeoutFrames: beside, ...others } = rest;
+      const old = isObject(input) && !("target" in input) && ("at" in input || "raster" in input || "memory" in input);
+      if (!isObject(input) || (!old && beside === undefined)) return undefined;
+      const fields = [...(old ? ["at", "raster", "memory"].filter((key) => key in input).map((key) => `runUntil.${key}`) : []), ...(beside === undefined ? [] : ["timeoutFrames beside runUntil"])];
+      const timeoutFrames = beside ?? input.timeoutFrames;
+      return form(fields, { target: targetOf(input), ...(timeoutFrames === undefined ? {} : { timeoutFrames }) }, others);
+    }
+    case "type":
+      return typeof input === "string" ? form(["type as text"], { mode: "text", text: input }) : undefined;
+    case "write": {
+      if (!isObject(input) || !("at" in input || "bytes" in input || Array.isArray(input.data))) return undefined;
+      const { at: old, bytes, address, data, ...others } = input;
+      return form(
+        ["at", "bytes"].filter((key) => key in input).map((key) => `write.${key}`).concat(Array.isArray(data) ? ["write.data as a list"] : []),
+        { address: address ?? old, data: asHex(data ?? bytes), ...others },
+      );
+    }
+    case "registers": {
+      if (!isObject(input)) return undefined;
+      const fields = Object.entries(input).flatMap(([name, value]) => ((name === "pc" && typeof value === "number") || (name !== "pc" && name !== "flags" && typeof value === "string" && c64AddressOf(value) !== undefined) ? [`registers.${name} as ${typeof value === "number" ? "a number" : "text"}`] : []));
+      if (fields.length === 0) return undefined;
+      const values = Object.fromEntries(Object.entries(input).map(([name, value]) => [name, name === "pc" ? asAddress(value) : typeof value === "string" ? (c64AddressOf(value) ?? value) : value]));
+      return form(fields, values);
+    }
+    default:
+      return undefined;
+  }
+}
+
+/** Refuses a step in a form of the 2.0 files: the message names its 2.0 fields and gives the step to write. */
+export function refuseOldStep(kind: string, step: Record<string, unknown>, at: string, fail: (message: string) => never): void {
+  const found = newStepForm(kind, step);
+  if (found === undefined) return;
+  const petscii = kind === "type" ? ', or {"type": {"mode": "petscii", "bytes": [...]}} for PETSCII codes' : "";
+  fail(`${at} has the 2.0 form (${found.fields.join(", ")}). Write ${jsonLine(found.step)}${petscii}`);
+}
+
 /**
  * Checks one action step of the given kind and returns it with the defaults
  * filled in. The step has no other key. `press` is refused unless the caller
- * runs the steps on the replay core.
+ * runs the steps on the replay core. A step in a form of the 2.0 files is
+ * refused with the step to write.
  */
 export function checkActionStep(kind: ActionStepKind, step: Record<string, unknown>, at: string, fail: (message: string) => never, options: { press?: boolean } = {}): ActionStep {
+  refuseOldStep(kind, step, at, fail);
   for (const key of Object.keys(step)) if (key !== kind) fail(`${at} has the key ${key}, which a ${kind} step does not have`);
   if (kind === "press" && options.press !== true) fail(`${at}: ${PRESS_REMEDY}`);
   return checkInput(kind, step[kind], at, fail);
 }
 
-/** The kind of a step: its one key from `kinds`. */
-export function stepKind<K extends string>(step: unknown, kinds: readonly K[], at: string, fail: (message: string) => never): K {
+/**
+ * The kind of a step: its one key from `kinds`. A refusal lists `shown`: the
+ * kinds that the caller runs.
+ */
+export function stepKind<K extends string>(step: unknown, kinds: readonly K[], at: string, fail: (message: string) => never, shown: readonly string[] = kinds): K {
   if (!isObject(step)) return fail(`${at} must be an object`);
   const found = Object.keys(step).filter((key) => (kinds as readonly string[]).includes(key));
-  if (found.length !== 1) return fail(`${at} must have exactly one of ${kinds.join(", ")}`);
+  if (found.length > 1) return fail(`${at} has ${found.length} step kinds: ${found.join(", ")}. Give each one its own step`);
+  if (found.length !== 1) return fail(`${at} must have exactly one of ${shown.join(", ")}`);
   return found[0] as K;
 }
 
@@ -280,12 +380,46 @@ export function checkActionSteps(value: unknown, fail: (message: string) => neve
   if (!Array.isArray(value) || value.length === 0) return fail("the steps are a JSON list with at least one step");
   return value.map((step: unknown, index) => {
     const at = `step ${index + 1}`;
-    return checkActionStep(stepKind(step, ACTION_STEP_KINDS, at, fail), step as Record<string, unknown>, at, fail, options);
+    return checkActionStep(stepKind(step, ACTION_STEP_KINDS, at, fail, options.press === true ? ACTION_STEP_KINDS : VICE_STEP_KINDS), step as Record<string, unknown>, at, fail, options);
   });
 }
 
-/** Reads a steps file of the project: a JSON list of action steps. `option` names the option of the file in a refusal. */
-export function readActionSteps(path: string, option: string): ActionStep[] {
+/** The names and addresses of an action step: each location that the step resolves when it runs. */
+export function stepLocations(step: ActionStep): Location[] {
+  if ("write" in step) return [step.write.address];
+  if ("registers" in step) return step.registers.pc === undefined ? [] : [step.registers.pc];
+  if (!("runUntil" in step)) return [];
+  const { target } = step.runUntil;
+  if (target.kind === "raster") return [];
+  if (target.kind === "memory") return [target.address];
+  return [target.address, ...(target.condition?.kind === "memory" ? [target.condition.address] : [])];
+}
+
+/**
+ * Resolves every name of the steps with `at` before the steps run, so that an
+ * unknown name stops the call before the emulator starts. A refusal of `at` becomes
+ * invalid-input that names `where` (for example the option and the file) and the step.
+ * `first` is the number of the first of the steps in the file.
+ */
+export function checkStepNames(steps: readonly ActionStep[], at: (location: Location) => number, where: string, first = 1): void {
+  steps.forEach((step, index) => {
+    for (const location of stepLocations(step)) {
+      try {
+        at(location);
+      } catch (error) {
+        if (isRefusal(error)) throw new Refusal("invalid-input", `${where}: step ${index + first}: ${error.message}`);
+        throw error;
+      }
+    }
+  });
+}
+
+/**
+ * Reads a steps file of the project: a JSON list of action steps. `option`
+ * names the option of the file in a refusal. With `at`, every name of the
+ * steps must resolve (checkStepNames).
+ */
+export function readActionSteps(path: string, option: string, at?: (location: Location) => number): ActionStep[] {
   const fail = (message: string): never => {
     throw new Refusal("invalid-input", `${option} ${path}: ${message}`);
   };
@@ -296,7 +430,9 @@ export function readActionSteps(path: string, option: string): ActionStep[] {
     if (error instanceof SyntaxError) return fail(`it is not JSON: ${error.message}`);
     throw error;
   }
-  return checkActionSteps(value, fail);
+  const steps = checkActionSteps(value, fail);
+  if (at !== undefined) checkStepNames(steps, at, `${option} ${path}`);
+  return steps;
 }
 
 /** Stops the CPU when it runs: a write, a register change or an exact frame count needs it stopped. */

package/src/host-client/tools.ts

@@ -85,6 +85,6 @@ export async function hostTools(options: ToolCallOptions = {}): Promise<{ host:
 
 /** Skill scripts see failures and wire limits through the host-client, never the private protocol module. */
 export { WireFailure } from "../protocol/messages.ts";
-export { DISK_ACTIONS } from "../protocol/tools.ts";
+export { DISK_ACTIONS, DISK_IMAGE_TYPES } from "../protocol/tools.ts";
 export { JOYSTICK_DIRECTIONS, MAX_BASELINES, MAX_EXECUTION_COUNT, MAX_KEYBOARD_BYTES, MAX_MASK_RECTANGLES, MAX_MEMORY_READ, MAX_MEMORY_WRITE, MAX_TIMEOUT_FRAMES, maskCoversFrame } from "../protocol/vice.ts";
 export { MAX_TRACE_FRAMES, MAX_TRACE_HITS, MAX_TRACE_POINTS, TRACE_KINDS, type TraceHit, type TraceKind } from "../protocol/vice.ts";