@henols/c64-re-tools 2.1.0 → 2.1.2

package/src/knowledge/write.ts

@@ -8,6 +8,7 @@ import { type AddressRange, formatC64Address, instructionLength, SPACE_PATTERN,
 import { isoCet } from "../time.ts";
 import { CONFLICT_RULES, conflicts, conflictTable, type Conflict, type ConflictRow } from "./conflicts.ts";
 import { transaction } from "./database.ts";
+import { labelProblem } from "../opcodes.ts";
 import { checkExpression, evaluate, identifiers, operandText, replaceIdentifiers } from "./expression.ts";
 import {
   COMMENT_COLUMNS,
@@ -32,6 +33,7 @@ import {
   referencesFrom,
   REGION_COLUMNS,
   regionsOverlapping,
+  coverageRuns,
   resolveRevision,
   SUPPRESSION_COLUMNS,
   suppressionsOverlapping,
@@ -49,6 +51,7 @@ import {
   toSuppression,
   toSymbol,
   type CommentRow,
+  type CoverageRun,
   type MacroRow,
   type MacroUseRow,
   type ModuleRow,
@@ -59,7 +62,7 @@ import {
   type SuppressionRow,
   type SymbolRow,
 } from "./read.ts";
-import { COMMENT_PLACEMENTS, EVIDENCE_KINDS, MAX_ELEMENT, MODULE_FILE, DEFAULT_SPACE, GENERATED_FILES, isGeneratedFile, MACRO_NAME, MACRO_PARAM, SWITCH_NAME, NO_ELEMENT_TYPES, OPERAND_SELECTS, POINTER_KIND, REFERENCE_KINDS, REGION_TYPES, SYMBOL_KINDS, type CommentPlacement, type EvidenceKind, type OperandSelect, type Origin, type ReferenceKind, type RegionType, type Space, type SymbolKind } from "./schema.ts";
+import { CODE_REGION_TYPES, COMMENT_PLACEMENTS, EVIDENCE_KINDS, MAX_ELEMENT, MODULE_FILE, DEFAULT_SPACE, GENERATED_FILES, isGeneratedFile, MACRO_NAME, MACRO_PARAM, SWITCH_NAME, NO_ELEMENT_TYPES, OPERAND_SELECTS, POINTER_KIND, REFERENCE_KINDS, REGION_TYPES, SYMBOL_KINDS, type CommentPlacement, type EvidenceKind, type OperandSelect, type Origin, type ReferenceKind, type RegionType, type Space, type SymbolKind } from "./schema.ts";
 import { newRevisionId, rowId, sqlName } from "./text.ts";
 
 /** What a change rests on: a coverage run, a test or another project file with its SHA-256, or a note. */
@@ -136,6 +139,10 @@ export interface ChangeContext {
   inputHash?: string;
   toolVersion?: string;
   evidence?: Evidence[];
+  /** A revert: the revision whose knowledge it restores. */
+  restores?: string;
+  /** A revert of one space: the space whose knowledge it restores. Without it, a revert restores every space. */
+  restoresSpace?: Space;
 }
 
 /**
@@ -177,8 +184,8 @@ export class Change {
     const now = new Date();
     const id = newRevisionId(currentRevision(this.#db), now);
     this.#db
-      .prepare("INSERT INTO revisions (id, created_at, origin, operation, input_hash, tool_version, description) VALUES (?, ?, ?, ?, ?, ?, ?)")
-      .run(id, isoCet(now), this.#context.origin, this.#operation, this.#context.inputHash ?? null, this.#context.toolVersion ?? null, this.#context.description ?? null);
+      .prepare("INSERT INTO revisions (id, created_at, origin, operation, input_hash, tool_version, description, restored_revision, restored_space) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)")
+      .run(id, isoCet(now), this.#context.origin, this.#operation, this.#context.inputHash ?? null, this.#context.toolVersion ?? null, this.#context.description ?? null, this.#context.restores ?? null, this.#context.restoresSpace ?? null);
     this.revision = id;
     const evidence = this.#db.prepare("INSERT INTO evidence (revision, kind, ref, sha256, space) VALUES (?, ?, ?, ?, ?)");
     for (const item of this.#context.evidence ?? []) evidence.run(id, item.kind, item.ref, item.sha256 ?? null, item.space ?? null);
@@ -321,7 +328,7 @@ function checkEvidence(evidence: Evidence[] | undefined): void {
 }
 
 /** Runs semantic writes in one transaction, as one revision. */
-export function write<T>(db: DatabaseSync, context: WriteContext, operation: string, work: (change: Change) => T): { revision: string | null; current: T } {
+export function write<T>(db: DatabaseSync, context: WriteContext & Pick<ChangeContext, "restores">, operation: string, work: (change: Change) => T): { revision: string | null; current: T } {
   if (context.origin !== "user" && context.origin !== "llm") {
     throw new Refusal("invalid-input", "A semantic write comes from the user or the LLM.");
   }
@@ -365,9 +372,8 @@ export function checkSpace(request: InSpace): void {
 function checkSymbol(request: SymbolRequest): void {
   checkSpace(request);
   checkAddress(request.address);
-  if (!SYMBOL_NAME.test(request.name)) {
-    throw new Refusal("invalid-input", "A symbol name is a letter or underscore, then letters, digits or underscores (at most 64), with an optional leading dot.");
-  }
+  const problem = labelProblem(request.name);
+  if (problem !== undefined) throw new Refusal("invalid-input", problem);
   if (request.kind !== undefined) checkOneOf(SYMBOL_KINDS, request.kind, "kind");
 }
 
@@ -572,6 +578,32 @@ function checkOperand(request: OperandRequest): void {
 
 const shown = (value: number, size: number) => (value < 0 ? String(value) : `$${value.toString(16).padStart(size === 0x100 ? 2 : 4, "0")}`);
 
+/**
+ * Refuses an address that is not the start of an instruction. The code
+ * regions of the knowledge give the instructions: they are decoded from the
+ * start of the region, as the listing and the source decode them.
+ */
+function checkInstructionStart(db: DatabaseSync, space: Space, image: OperandImage, address: number): void {
+  const where = formatC64Address(address);
+  const code = regionsOverlapping(db, address, address, space).find((region) => CODE_REGION_TYPES.includes(region.type));
+  if (code === undefined) {
+    throw new Refusal("invalid-input", `${where} is in no code region, so the knowledge does not know an instruction that starts there. Classify the code that holds the instruction first (classify <range> code), then write the operand.`);
+  }
+  let start = code.start;
+  let next = code.start;
+  while (next < address) {
+    const opcode = image.byteAt(next);
+    if (opcode === undefined) {
+      throw new Refusal("invalid-input", `The code region ${formatC64Address(code.start)}-${formatC64Address(code.end)} has no program byte at ${formatC64Address(next)}, so its instructions up to ${where} are not known. Correct the region (classify), then write the operand.`);
+    }
+    start = next;
+    next += instructionLength(opcode);
+  }
+  if (next !== address) {
+    throw new Refusal("invalid-input", `${where} is not the start of an instruction. It is an operand byte of the instruction at ${formatC64Address(start)}, decoded from the start of the code region at ${formatC64Address(code.start)}. Give ${formatC64Address(start)}.`);
+  }
+}
+
 /**
  * Refuses an expression whose value is not the operand in the image, and
  * returns the addresses of its names. Symbols of the knowledge come first, then
@@ -581,6 +613,7 @@ function checkOperandValue(db: DatabaseSync, space: Space, image: OperandImage,
   const where = formatC64Address(request.address);
   const opcode = image.byteAt(request.address);
   if (opcode === undefined) throw new Refusal("invalid-input", `${where} is outside the image.`);
+  checkInstructionStart(db, space, image, request.address);
   const length = instructionLength(opcode);
   if (length === 1) throw new Refusal("invalid-input", `The instruction at ${where} (opcode ${shown(opcode, 0x100)}) has no operand.`);
   if ((opcode & 0x1f) === 0x10) throw new Refusal("invalid-input", `The instruction at ${where} is a branch: its operand is a distance, not a value.`);
@@ -1168,16 +1201,25 @@ const KEYS = {
 
 /**
  * Makes the current knowledge equal to what it was at `revision`, as a new
- * revision. History is never erased; restored rows keep their origin.
+ * revision. With `space`, only the rows of that space change; without it,
+ * every space changes. History is never erased; restored rows keep their origin.
  */
-export function revert(db: DatabaseSync, context: WriteContext, request: { revision: string }): WriteResult<{ restoredRevision: string }> {
-  return write(db, context, "revert", (change) => {
-    const restored = resolveRevision(db, request.revision);
-    const at = "valid_from_revision <= ? AND (valid_to_revision IS NULL OR valid_to_revision > ?)";
+export function revert(db: DatabaseSync, context: WriteContext, request: { revision: string; space?: Space }): WriteResult<{ restoredRevision: string }> {
+  checkSpace(request);
+  const restored = resolveRevision(db, request.revision);
+  const only = request.space;
+  return write(db, { ...context, restores: restored, ...(only === undefined ? {} : { restoresSpace: only }) }, "revert", (change) => {
+    // The coverage maps that the knowledge has follow the revert, also when no coverage range changes.
+    const maps = (runs: CoverageRun[]) => JSON.stringify(runs.filter((run) => only === undefined || run.space === only).map((run) => [run.name, run.sha256, run.space, run.revision]));
+    if (maps(coverageRuns(db, restored)) !== maps(coverageRuns(db))) change.id();
+    const inSpace = only === undefined ? "" : " AND space = ?";
+    const spaceArgs = only === undefined ? [] : [only];
+    const at = `valid_from_revision <= ? AND (valid_to_revision IS NULL OR valid_to_revision > ?)${inSpace}`;
+    const current = `valid_to_revision IS NULL${inSpace}`;
     for (const [table, spec] of Object.entries(KEYS)) {
       const name = table === "references" ? '"references"' : table;
-      const then = db.prepare(`SELECT ${spec.columns}, id FROM ${name} WHERE ${at}`).all(restored, restored) as Array<Record<string, unknown>>;
-      const now = db.prepare(`SELECT ${spec.columns}, id FROM ${name} WHERE valid_to_revision IS NULL`).all() as Array<Record<string, unknown>>;
+      const then = db.prepare(`SELECT ${spec.columns}, id FROM ${name} WHERE ${at}`).all(restored, restored, ...spaceArgs) as Array<Record<string, unknown>>;
+      const now = db.prepare(`SELECT ${spec.columns}, id FROM ${name} WHERE ${current}`).all(...spaceArgs) as Array<Record<string, unknown>>;
       const key = (row: Record<string, unknown>) => (spec.key as (row: unknown) => string)(spec.map(row as never));
       const thenKeys = new Set(then.map(key));
       const nowKeys = new Set(now.map(key));
@@ -1219,8 +1261,8 @@ export function revert(db: DatabaseSync, context: WriteContext, request: { revis
     }
     // The program: a row is the same when all its values are the same.
     for (const [table, columns] of PROGRAM_TABLES) {
-      const then = db.prepare(`SELECT ${columns}, id FROM ${table} WHERE ${at}`).all(restored, restored) as Array<Record<string, unknown>>;
-      const now = db.prepare(`SELECT ${columns}, id FROM ${table} WHERE valid_to_revision IS NULL`).all() as Array<Record<string, unknown>>;
+      const then = db.prepare(`SELECT ${columns}, id FROM ${table} WHERE ${at}`).all(restored, restored, ...spaceArgs) as Array<Record<string, unknown>>;
+      const now = db.prepare(`SELECT ${columns}, id FROM ${table} WHERE ${current}`).all(...spaceArgs) as Array<Record<string, unknown>>;
       const key = (row: Record<string, unknown>) => JSON.stringify(columns.split(", ").map((column) => row[column]));
       const thenKeys = new Set(then.map(key));
       const nowKeys = new Set(now.map(key));

package/src/mcp/inputs.ts

@@ -33,12 +33,15 @@ export const AddressInput = z
   .transform((value) => c64AddressOf(value)!)
   .describe("C64 address: $ and 1 to 4 hex digits, $0000 to $ffff");
 
+/** The space of a memory target or condition: the emulator tests only C64 memory. */
+const MemorySpaceInput = SpaceInput.describe("c64 only: the emulator tests only C64 memory. For the drive, use a watchpoint or an address target in space drive8");
+
 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("memory"), address: AddressInput, operator: z.enum(COMPARISONS), value: Byte, space: MemorySpaceInput, 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");
@@ -50,7 +53,7 @@ export const TOOL_INPUTS = {
 
   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("memory"), address: AddressInput, operator: z.enum(COMPARISONS), value: Byte, space: MemorySpaceInput, 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(),
   ]),
 
@@ -82,7 +85,7 @@ export const TOOL_INPUTS = {
 
   joystick: z
     .object({
-      port: z.union([z.literal(1), z.literal(2)]).describe("control port 1 or 2"),
+      port: z.union([z.literal(1), z.literal(2)], { error: "port must be the number 1 or 2" }).describe("control port 1 or 2"),
       direction: z.enum(JOYSTICK_DIRECTIONS),
       fire: z.boolean().default(false),
     })

package/src/mcp/output.ts

@@ -22,6 +22,11 @@ export const WrittenOutput = {
   sha256: z.string().regex(/^[0-9a-f]{64}$/).optional(),
 };
 
+/** Lines as file text: each line ends with a newline, and no lines give an empty file. */
+export function linesText(lines: readonly string[]): string {
+  return lines.map((line) => `${line}\n`).join("");
+}
+
 /** 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 {
   return writeReported(path, data, { what: "out", root: projectFolder(project) });

package/src/mcp/server.ts

@@ -91,6 +91,17 @@ export function requireFields(action: string, given: Record<string, unknown>, al
   }
 }
 
+/**
+ * Checks the fields that go with out: project only with out, and the
+ * fields of `notWithOut` only without it.
+ */
+export function requireOut(given: { out?: unknown; project?: unknown } & Record<string, unknown>, notWithOut: readonly string[] = []): void {
+  if (given.out === undefined && given.project !== undefined) throw new WireFailure("invalid-input", "project is used only with out.");
+  for (const field of notWithOut) {
+    if (given.out !== undefined && given[field] !== undefined) throw new WireFailure("invalid-input", `${field} is not used with out.`);
+  }
+}
+
 /** A tool result that carries content blocks (for example an image) beside its structured result. */
 export class ToolOutput<T> {
   readonly structured: T;
@@ -163,12 +174,17 @@ function errorResult(error: WireError): CallToolResult {
   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. */
-function describeIssues(error: z.ZodError): string {
+/**
+ * "address: Invalid string: must match ..." style messages, one sentence per problem.
+ * An unknown field of the tool input also gets the fields that the tool takes.
+ */
+function describeIssues(error: z.ZodError, input?: z.ZodObject): string {
   return error.issues
     .map((issue) => {
       const where = issue.path.length === 0 ? "input" : issue.path.join(".");
-      return `${where}: ${issue.message}`;
+      const names = input === undefined ? [] : Object.keys(input.shape);
+      const fields = issue.code !== "unrecognized_keys" || issue.path.length !== 0 || input === undefined ? "" : names.length === 0 ? ". The tool takes no fields" : `. The fields are ${names.join(", ")}`;
+      return `${where}: ${issue.message}${fields}`;
     })
     .join(". ");
 }
@@ -211,7 +227,7 @@ async function runCall(
   const tool = tools.get(name);
   if (tool === undefined) return errorResult({ code: "invalid-input", message: `There is no tool named ${name}.` });
   const parsed = tool.inputSchema.safeParse(args ?? {});
-  if (!parsed.success) return errorResult({ code: "invalid-input", message: describeIssues(parsed.error) });
+  if (!parsed.success) return errorResult({ code: "invalid-input", message: describeIssues(parsed.error, tool.inputSchema) });
   try {
     let output: unknown;
     try {

package/src/mcp/tools/debug.ts

@@ -7,9 +7,9 @@ import { COVERAGE, executedRamCode, EXECUTE, formatC64Address, READ, WRITE, type
 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 { linesText, OutInput, ProjectInput, writeOut, WrittenOutput } from "../output.ts";
 import { AddressInput, Byte, SpaceInput, TOOL_INPUTS } from "../inputs.ts";
-import { AddressOutput, ConditionOutput, defineTool, HexData, requireFields, showCondition, toCondition } from "../server.ts";
+import { AddressOutput, ConditionOutput, defineTool, HexData, requireFields, requireOut, 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. */
@@ -169,7 +169,7 @@ export const c64CpuHistory = defineTool({
       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`, project) };
+    return { count: entries.length, ...writeOut(out, linesText(lines), project) };
   },
 });
 
@@ -184,6 +184,7 @@ export const c64Trace = defineTool({
     "A point is exec (an instruction at an address from start to end), read or write (an access from start to end). " +
     `Give 1 to ${MAX_TRACE_POINTS} points. ` +
     "Each hit gives the instruction (pc, bytes, text) and the registers a, x, y and sp before it. " +
+    "point in a hit is the number of its point in points, 0 for the first. " +
     "It also gives the frame from 0, and the raster line and cycle where the instruction started. " +
     "A read or write hit also gives the address that the instruction used, and the byte there after the access. " +
     `The trace ends after frames frames (1 to ${MAX_TRACE_FRAMES}), at maxHits hits (at most ${MAX_TRACE_HITS}), or at a breakpoint, a watchpoint or a JAM. ` +
@@ -233,7 +234,7 @@ export const c64Trace = defineTool({
     const shown = traced.hits.map(({ address, ...hit }) => ({ ...hit, pc: formatC64Address(hit.pc), ...(address === undefined ? {} : { address: formatC64Address(address) }) }));
     const summary = { end: traced.end, frames: traced.frames, pc: formatC64Address(traced.pc), count: traced.hits.length, hits: shown.slice(0, TRACE_LISTED) };
     if (out === undefined) return summary;
-    return { ...summary, ...writeOut(out, `${shown.map((hit) => JSON.stringify(hit)).join("\n")}\n`, project) };
+    return { ...summary, ...writeOut(out, linesText(shown.map((hit) => JSON.stringify(hit))), project) };
   },
 });
 
@@ -338,7 +339,9 @@ export const c64Memmap = defineTool({
     "A read on a byte right after executed code, or at a return address, can be a dummy read that the CPU does not use. " +
     "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.",
+    "Action clear sets all access records to zero. " +
+    "The emulator decides RAM, ROM or I/O from one bit of $01. At $A000-$BFFF it gives ROM when bit 0 is set, also when bit 1 is clear and the CPU used RAM. " +
+    "Every access at $D000-$DFFF is I/O, also when $01 shows RAM or the character ROM there. emulatorFlaw in the result tells when ROM at $A000-$BFFF can be RAM.",
   inputSchema: z
     .object({
       action: z.enum(["read", "summary", "clear"]),
@@ -361,6 +364,7 @@ export const c64Memmap = defineTool({
     writtenAndExecuted: z.array(RangeOutput).optional(),
     writtenAndExecutedTruncated: z.boolean().optional(),
     cleared: z.boolean().optional(),
+    emulatorFlaw: z.string().optional().describe("a known flaw of VICE that can make the ROM and I/O classes wrong in this result"),
     ...WrittenOutput,
   }),
   readOnly: false,
@@ -390,13 +394,15 @@ export const c64Memmap = defineTool({
         ...(code.length > MAX_SUMMARY_RANGES ? { codeTruncated: true } : {}),
         writtenAndExecuted: showRanges(written),
         ...(written.length > MAX_SUMMARY_RANGES ? { writtenAndExecutedTruncated: true } : {}),
+        ...basicRomFlaw(romInBasicArea(map, start)),
       };
     }
+    requireOut(fields, ["maxRanges"]);
+    requireFields("read", fields, ["start", "end", "maxRanges", "out", "project"]);
     if (fields.out !== undefined) {
-      requireFields("read", fields, ["start", "end", "out", "project"]);
-      return writeOut(fields.out, await readCoverage(session, start, end), fields.project);
+      const map = await readCoverage(session, start, end);
+      return { ...writeOut(fields.out, map, fields.project), ...basicRomFlaw(romInBasicArea(map, start)) };
     }
-    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),
@@ -406,8 +412,29 @@ export const c64Memmap = defineTool({
       write: (range.flags & WRITE) !== 0,
       in: sources(range.flags),
     }));
-    return result.next === undefined ? { ranges } : { ranges, truncated: true, next: formatC64Address(result.next) };
+    const flaw = basicRomFlaw(result.ranges.some((range) => range.start <= 0xbfff && range.end >= 0xa000 && (range.flags & ROM_ACCESS) !== 0));
+    return result.next === undefined ? { ranges, ...flaw } : { ranges, truncated: true, next: formatC64Address(result.next), ...flaw };
   },
 });
 
+const ROM_ACCESS = COVERAGE.romRead | COVERAGE.romExecute;
+
+/** True when the map from `start` has a ROM access at $A000-$BFFF. */
+function romInBasicArea(map: Uint8Array, start: number): boolean {
+  for (let address = Math.max(start, 0xa000); address <= Math.min(start + map.length - 1, 0xbfff); address++) {
+    if ((map[address - start]! & ROM_ACCESS) !== 0) return true;
+  }
+  return false;
+}
+
+/** VICE tests only bit 0 of $01 for $A000-$BFFF; the C64 shows BASIC ROM there only when bits 0 and 1 are set. */
+function basicRomFlaw(present: boolean): { emulatorFlaw?: string } {
+  if (!present) return {};
+  return {
+    emulatorFlaw:
+      "The emulator gives ROM for an access at $A000-$BFFF when bit 0 of $01 is set, also when bit 1 is clear and the CPU used the RAM there. " +
+      "Read $01 of the program at that time before you take rom at $A000-$BFFF as the BASIC ROM.",
+  };
+}
+
 export const debugTools = [c64Breakpoint, c64Watchpoint, c64CpuHistory, c64Trace, c64Backtrace, c64Profile, c64Memmap, c64Timing];

package/src/mcp/tools/execution.ts

@@ -3,9 +3,10 @@
 import { z } from "zod";
 
 import { formatC64Address } from "../../c64.ts";
+import { isRefusal } from "../../errors.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 { AddressOutput, defineTool, toCondition, ToolOutput, type ViceSessionApi } from "../server.ts";
 import { c64Observe } from "./video.ts";
 
 export const c64Execution = defineTool({
@@ -19,6 +20,8 @@ export const c64Execution = defineTool({
     "advance-frames runs exactly count video frames (count is necessary). It stops at the same raster position, count frames later. " +
     "A breakpoint, a watchpoint or a JAM opcode can stop it before that. advancedFrames tells how many frames ran. " +
     "stopReason tells why it stopped: frames (all frames ran), breakpoint, watchpoint or jam. pointId gives the id of the breakpoint or watchpoint. " +
+    "space tells which CPU stopped: c64, or drive8 for a breakpoint or watchpoint in the disk drive. pc is the address in that space. " +
+    "A CPU that a JAM stopped runs again only after c64_reset, a snapshot restore or c64_autostart. " +
     "To wait for a breakpoint or watchpoint after resume, use advance-frames with a large count. " +
     "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.",
@@ -42,6 +45,7 @@ export const c64Execution = defineTool({
     advancedFrames: z.number().int().min(0).max(MAX_EXECUTION_COUNT).optional().describe("frames advance-frames ran"),
     stopReason: z.enum(["frames", ...POINT_STOP_REASONS]).optional().describe("advance-frames: why it stopped"),
     pointId: z.number().int().min(1).optional().describe("the id of the breakpoint or watchpoint that stopped advance-frames"),
+    space: z.enum(SPACES).optional().describe("advance-frames: the CPU that stopped, c64 or drive8. pc is the address in that space"),
   }),
   readOnly: false,
   async run(input, session) {
@@ -54,6 +58,7 @@ export const c64Execution = defineTool({
       ...(result.advancedFrames === undefined ? {} : { advancedFrames: result.advancedFrames }),
       ...(result.stopReason === undefined ? {} : { stopReason: result.stopReason }),
       ...(result.pointId === undefined ? {} : { pointId: result.pointId }),
+      ...(result.space === undefined ? {} : { space: result.space }),
     };
   },
 });
@@ -93,6 +98,7 @@ export const c64RunUntil = defineTool({
     history: z
       .array(z.object({ address: AddressOutput, bytes: z.string(), 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(),
+    historyMissing: z.string().optional().describe("why the result has no history, for example an old history after a JAM"),
   }),
   readOnly: false,
   async run(input, session) {
@@ -108,10 +114,7 @@ export const c64RunUntil = defineTool({
     }
     const result = await session.runUntil({ target, timeoutFrames: input.timeoutFrames });
     const answer = { ...result, pc: formatC64Address(result.pc) };
-    const history =
-      input.history === undefined
-        ? {}
-        : { history: (await session.cpuHistory({ limit: input.history, space: result.space })).entries.map((entry) => ({ ...entry, address: formatC64Address(entry.address) })) };
+    const history = input.history === undefined ? {} : await runHistory(session, input.history, result.space);
     if (input.observe === undefined) return { ...answer, ...history };
     // The observation at the stop: an image of the screen comes with the result as c64_observe gives it.
     const observed = await c64Observe.run(input.observe, session);
@@ -120,4 +123,14 @@ export const c64RunUntil = defineTool({
   },
 });
 
+/** The history at the stop; the run result stays when the session refuses the history. */
+async function runHistory(session: ViceSessionApi, limit: number, space: "c64" | "drive8") {
+  try {
+    return { history: (await session.cpuHistory({ limit, space })).entries.map((entry) => ({ ...entry, address: formatC64Address(entry.address) })) };
+  } catch (error) {
+    if (isRefusal(error) && error.code === "operation-failed") return { historyMissing: error.message };
+    throw error;
+  }
+}
+
 export const executionTools = [c64Execution, c64RunUntil];

package/src/mcp/tools/machine.ts

@@ -5,7 +5,7 @@ import { z } from "zod";
 import { formatC64Address } from "../../c64.ts";
 import { PACKAGE } from "../../package.ts";
 import { VIDEO_STANDARDS } from "../../protocol/messages.ts";
-import { POINT_STOP_REASONS, RESET_MODES, RUN_STATES, WINDOW_ACTIONS } from "../../protocol/vice.ts";
+import { POINT_STOP_REASONS, RESET_MODES, RUN_STATES, SPACES, WINDOW_ACTIONS } from "../../protocol/vice.ts";
 import { AddressOutput, defineTool } from "../server.ts";
 
 export const c64Status = defineTool({
@@ -27,6 +27,7 @@ export const c64Status = defineTool({
     pc: AddressOutput.optional().describe("program counter. Only when the CPU is stopped"),
     stopReason: z.enum(POINT_STOP_REASONS).optional().describe("what stopped the CPU. Only when a breakpoint, a watchpoint or a JAM opcode stopped it"),
     pointId: z.number().int().min(1).optional().describe("the id of the breakpoint or watchpoint that stopped the CPU"),
+    space: z.enum(SPACES).optional().describe("with pc: c64, or drive8 when a breakpoint or watchpoint in the disk drive stopped the CPU. pc is the address in that space"),
     cartridge: z.boolean().describe("true while a cartridge from c64_autostart is attached"),
     version: z.string().describe("the c64-re-tools version of this MCP server"),
   }),
@@ -43,6 +44,7 @@ export const c64Status = defineTool({
       ...(status.pc === undefined ? {} : { pc: formatC64Address(status.pc) }),
       ...(status.stopReason === undefined ? {} : { stopReason: status.stopReason }),
       ...(status.pointId === undefined ? {} : { pointId: status.pointId }),
+      ...(status.space === undefined ? {} : { space: status.space }),
     };
   },
 });

package/src/mcp/tools/media.ts

@@ -2,14 +2,17 @@
 // c64_snapshot. Paths are relative to the project folder; the host-client
 // reads the file and the Host Runtime receives only its bytes.
 
+import { extname } from "node:path";
+
 import { z } from "zod";
 
 import { formatC64Address } from "../../c64.ts";
 import { projectFolder, readProjectFile } from "../../host-client/transfer.ts";
+import { WireFailure } from "../../protocol/messages.ts";
 import { AUTOSTART_TYPES, DISK_TYPES, MAX_SNAPSHOTS, RUN_STATES } from "../../protocol/vice.ts";
 import { OutInput, ProjectInput, writeOut, WrittenOutput } from "../output.ts";
 import { AddressInput } from "../inputs.ts";
-import { AddressOutput, defineTool, requireFields, TransientName } from "../server.ts";
+import { AddressOutput, defineTool, requireFields, requireOut, TransientName } from "../server.ts";
 
 const ProjectPath = z.string().min(1).describe("path relative to the project folder, for example build/game.prg");
 
@@ -63,6 +66,10 @@ export const c64ProgramLoad = defineTool({
   outputSchema: z.object({ state: z.enum(RUN_STATES), loadAddress: AddressOutput, size: z.number().int().min(1).max(0x10000) }),
   readOnly: false,
   async run(input, session) {
+    const type = extname(input.path).slice(1).toLowerCase();
+    if (type !== "prg" && (AUTOSTART_TYPES as readonly string[]).includes(type)) {
+      throw new WireFailure("invalid-input", `${input.path} is a .${type} image, not a PRG. Use c64_autostart, or c64_disk_attach for a disk image.`);
+    }
     const root = projectFolder(input.project);
     const result = await session.programLoad(input.address === undefined ? { path: input.path, root } : { path: input.path, address: input.address, root });
     return { state: result.state, loadAddress: formatC64Address(result.loadAddress), size: result.size };
@@ -118,12 +125,17 @@ export const c64Snapshot = defineTool({
       requireFields(action, fields, []);
       return session.snapshot({ action });
     }
+    if (action === "restore") {
+      if (fields.name !== undefined && fields.file !== undefined) throw new WireFailure("invalid-input", "Action restore takes name or file, not both.");
+      if (fields.name === undefined && fields.file === undefined) throw new WireFailure("invalid-input", "Action restore needs name (a snapshot of this session) or file (a .vsf in the project).");
+    }
     if (action === "restore" && fields.file !== undefined) {
       requireFields(action, fields, ["file", "project"], ["file"]);
       return session.snapshotRestore(readProjectFile(fields.file, { root: projectFolder(fields.project) }).bytes);
     }
     if (action === "save") {
-      requireFields(action, fields, fields.out === undefined ? ["name"] : ["name", "out", "project"], ["name"]);
+      requireOut(fields);
+      requireFields(action, fields, ["name", "out", "project"], ["name"]);
       const saved = await session.snapshot({ action, name: fields.name! });
       return fields.out === undefined ? saved : { ...saved, ...writeOut(fields.out, await session.snapshotExport(fields.name!), fields.project) };
     }

package/src/mcp/tools/memory.ts

@@ -6,7 +6,7 @@ import { z } from "zod";
 import { formatC64Address } from "../../c64.ts";
 import { WireFailure } from "../../protocol/messages.ts";
 import { MAX_COMPARE_DIFFERENCES, MAX_COMPARE_SIZE, MAX_DISASSEMBLE, MAX_MEMORY_READ, MAX_MEMORY_WRITE, MAX_SEARCH_PATTERN, MAX_SEARCH_RESULTS, type RegisterValues } from "../../protocol/vice.ts";
-import { OutInput, ProjectInput, writeOut, WrittenOutput } from "../output.ts";
+import { linesText, OutInput, ProjectInput, writeOut, WrittenOutput } from "../output.ts";
 import { AddressInput, Byte, MemoryViewInput, SpaceInput, TOOL_INPUTS } from "../inputs.ts";
 import { AddressOutput, defineTool, HexData, requireFields } from "../server.ts";
 
@@ -123,7 +123,7 @@ export const c64MemorySearch = defineTool({
   title: "Search C64 memory",
   description:
     `Find a byte pattern of 1 to ${MAX_SEARCH_PATTERN} bytes in memory from start to end. ?? matches any byte. ` +
-    `The result gives the start address of each match, at most maxResults (1 to ${MAX_SEARCH_RESULTS}, default 100). ` +
+    `The result gives the start address of each match, at most maxResults (1 to ${MAX_SEARCH_RESULTS}, default 100). truncated: true tells that more matches can follow. ` +
     "This does not change the run state of the machine.",
   inputSchema: z
     .object({
@@ -135,15 +135,20 @@ export const c64MemorySearch = defineTool({
       maxResults: z.number().int().min(1).max(MAX_SEARCH_RESULTS).default(100),
     })
     .strict(),
-  outputSchema: z.object({ matches: z.array(AddressOutput) }),
+  outputSchema: z.object({ matches: z.array(AddressOutput), truncated: z.boolean().optional().describe("true when the result has maxResults matches: more can follow. Search again from the address after the last match") }),
   readOnly: true,
   async run(input, session) {
     if (input.pattern.length > MAX_SEARCH_PATTERN) {
       throw new WireFailure("invalid-input", `pattern has ${input.pattern.length} bytes. The limit is ${MAX_SEARCH_PATTERN}.`);
     }
     if (input.pattern.every((token) => token === null)) throw new WireFailure("invalid-input", "pattern needs at least one byte that is not ??.");
-    const result = await session.memorySearch({ ...input, end: input.end ?? 0xffff });
-    return { matches: result.matches.map(formatC64Address) };
+    const end = input.end ?? 0xffff;
+    if (end < input.start) throw new WireFailure("invalid-input", "end is lower than start.");
+    // VICE refuses a range shorter than the pattern. Such a range has no match.
+    if (end - input.start + 1 < input.pattern.length) return { matches: [] };
+    const result = await session.memorySearch({ ...input, end });
+    const matches = result.matches.map(formatC64Address);
+    return matches.length >= input.maxResults ? { matches, truncated: true } : { matches };
   },
 });
 
@@ -220,7 +225,7 @@ export const c64Disassemble = defineTool({
         address = instruction.address + instruction.bytes.length / 2;
       }
     }
-    return { count: lines.length, ...writeOut(out, `${lines.join("\n")}\n`, project) };
+    return { count: lines.length, ...writeOut(out, linesText(lines), project) };
   },
 });
 

package/src/mcp/tools/video.ts

@@ -8,7 +8,7 @@ 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, Byte, MemoryViewInput, SpaceInput } from "../inputs.ts";
-import { AddressOutput, defineTool, HexData, requireFields, ToolOutput, TransientName } from "../server.ts";
+import { AddressOutput, defineTool, HexData, requireFields, requireOut, 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.";
@@ -170,14 +170,16 @@ export const c64Screen = defineTool({
   async run(input, session) {
     const { action, ...fields } = input;
     if (action === "capture") {
-      requireFields(action, fields, fields.out === undefined ? ["baseline"] : ["baseline", "out", "project"]);
+      requireOut(fields);
+      requireFields(action, fields, ["baseline", "out", "project"]);
       const shot = await session.screenCapture(fields.baseline);
       const result = { width: shot.width, height: shot.height, ...(shot.baseline === undefined ? {} : { baseline: shot.baseline }) };
       if (fields.out !== undefined) return { ...result, ...writeOut(fields.out, Buffer.from(shot.png, "base64"), fields.project) };
       return new ToolOutput(result, [{ type: "image", data: shot.png, mimeType: "image/png" }]);
     }
     if (action === "compare") {
-      requireFields(action, fields, ["baseline", "maxMismatchRatio", "mask", "includeDiff", ...(fields.out === undefined ? [] : ["out", "project"])], ["baseline"]);
+      requireOut(fields);
+      requireFields(action, fields, ["baseline", "maxMismatchRatio", "mask", "includeDiff", "out", "project"], ["baseline"]);
       const { diffPng, ...result } = await session.screenCompare({
         baseline: fields.baseline!,
         maxMismatchRatio: fields.maxMismatchRatio ?? 0,

package/src/media.ts

@@ -0,0 +1,42 @@
+// Media file signatures and sizes. The host checks a file with them before
+// VICE gets it: VICE takes a file that is not of its type in another way, and
+// a CRT or T64 that it cannot read loads as a PRG with a successful autostart.
+
+import { Refusal } from "./errors.ts";
+
+/** The signature at the start of each media type that has one. */
+const SIGNATURES: Readonly<Record<string, readonly string[]>> = {
+  crt: ["C64 CARTRIDGE   "],
+  t64: ["C64"],
+  tap: ["C64-TAPE-RAW"],
+  g64: ["GCR-1541"],
+  p00: ["C64File"],
+};
+
+/** True when `bytes` start with a signature of `type`, or `type` has none. */
+export function hasSignature(type: string, bytes: Uint8Array): boolean {
+  const buffer = Buffer.from(bytes.buffer, bytes.byteOffset, bytes.byteLength);
+  const signatures = SIGNATURES[type];
+  return signatures === undefined || signatures.some((signature) => buffer.toString("latin1", 0, signature.length) === signature);
+}
+
+/** The file sizes that VICE reads for each disk image type without a signature. */
+const SIZES: Readonly<Record<string, readonly number[]>> = {
+  d64: [174848, 175531, 196608, 197376, 205312, 206114],
+  d71: [349696, 351062],
+  d81: [819200, 822400],
+};
+
+/** The x64 header: 64 bytes that start with these four, then a d64 image. */
+const X64_MAGIC = Buffer.from([0x43, 0x15, 0x41, 0x64]);
+
+/** Refuses a file whose bytes are not of `type` (its extension), with media-error. */
+export function checkMedia(type: string, bytes: Buffer): void {
+  const refuse = (why: string) => {
+    throw new Refusal("media-error", `The file is not a valid .${type} file: ${why}. Give a file of that type.`);
+  };
+  if (!hasSignature(type, bytes)) refuse(`it does not start with ${SIGNATURES[type]!.map((signature) => `"${signature.trimEnd()}"`).join(" or ")}`);
+  const sizes = SIZES[type];
+  if (sizes !== undefined && !sizes.includes(bytes.length)) refuse(`it has ${bytes.length} bytes, and a .${type} image has ${sizes.join(", ")}`);
+  if (type === "x64" && (!bytes.subarray(0, 4).equals(X64_MAGIC) || !SIZES.d64!.includes(bytes.length - 64))) refuse("it has no x64 header before a d64 image");
+}