@henols/c64-re-tools 2.0.0-rc.13 → 2.0.0-rc.15

package/skills/c64-unpacker/scripts/unpack.ts

@@ -17,10 +17,10 @@ import { readProjectFile, writeProjectFile } from "#src/host-client/transfer.ts"
 import { ViceSessionClient } from "#src/host-client/vice-session.ts";
 import { resolveProjectPath } from "#src/project.ts";
 import { runScript, UsageError } from "#src/script.ts";
-import { basicStart, inspect, PackingError, readMemoryMap, underRom, writtenThenExecuted } from "./evidence.ts";
-import { loads, readLoadSteps } from "./loads.ts";
-import { callReturn, captureSegments, executedIn, inRanges, mergeMaps, stageCandidates, stagePoints, type Range } from "./stages.ts";
-import { entryState, IO_AREAS, json, machineState, readRam, READY_FRAMES, vectorsOf } from "./machine.ts";
+import { basicStart, inspect, PackingError, readMemoryMap, underRom, writtenThenExecuted } from "./lib/evidence.ts";
+import { loads, readLoadSteps } from "./lib/loads.ts";
+import { callReturn, captureSegments, executedIn, inRanges, mergeMaps, stageCandidates, stagePoints, type Range } from "./lib/stages.ts";
+import { entryState, IO_AREAS, json, machineState, readRam, READY_FRAMES, vectorsOf } from "./lib/machine.ts";
 
 const USAGE = `unpack.ts inspect <program.prg>
 unpack.ts trace <program.prg> [--frames <n>] [--entry <address>] [--steps <file>]

package/src/c64.ts

@@ -20,6 +20,16 @@ export function formatC64Address(value: number): string {
   return `$${checkAddress(value).toString(16).padStart(4, "0")}`;
 }
 
+/** VIC-II state with its addresses as $xxxx; the other values stay numbers. */
+export function formatVicii<T extends { screenAddress: number; graphicsAddress: number }>(state: T): Omit<T, "screenAddress" | "graphicsAddress"> & { screenAddress: string; graphicsAddress: string } {
+  return { ...state, screenAddress: formatC64Address(state.screenAddress), graphicsAddress: formatC64Address(state.graphicsAddress) };
+}
+
+/** A sprite with its data address as $xxxx; the other values stay numbers. */
+export function formatSprite<T extends { dataAddress: number }>(sprite: T): Omit<T, "dataAddress"> & { dataAddress: string } {
+  return { ...sprite, dataAddress: formatC64Address(sprite.dataAddress) };
+}
+
 /** A byte as $xx. Throws RangeError outside 0-255. */
 export function formatC64Byte(value: number): string {
   if (!Number.isInteger(value) || value < 0 || value > 0xff) throw new RangeError(`C64 byte out of range: ${value}`);

package/src/cli/cleanup.ts

@@ -29,7 +29,7 @@ interface Manifest {
 }
 
 /** The directory that the manifest and relative item paths belong to. */
-function scopeRoot(scope: Scope, cwd = process.cwd()): string {
+export function scopeRoot(scope: Scope, cwd = process.cwd()): string {
   return scope === "global" ? homedir() : cwd;
 }
 

package/src/cli/main.ts

@@ -14,7 +14,7 @@ import { WireFailure } from "../protocol/messages.ts";
 import { startTrace } from "../trace.ts";
 import { runApSdk } from "./ap-sdk.ts";
 import { installedItems, parseTargets, tidyAfterUninstall, undoWindsurfProjectMcp, windsurfBefore, withoutWindsurfMcp, type Scope } from "./cleanup.ts";
-import { hostStatusLines, toolLines } from "./status.ts";
+import { hostStatusLines, installedLines, toolLines } from "./status.ts";
 
 const HELP = `c64-re-tools: Commodore 64 reverse engineering and development
 
@@ -52,6 +52,7 @@ async function status(): Promise<number> {
   console.log(`c64-re-tools ${PACKAGE.version}`);
   console.log(`Package: ${join(here, "..", "..")}`);
   console.log(`Node: ${process.version} (${process.execPath})`);
+  for (const line of installedLines()) console.log(line);
   // The skill scripts run these tools here, on this machine.
   const local = await localToolStatus(localToolContext());
   for (const line of toolLines("Tools here:", local)) console.log(line);

package/src/cli/status.ts

@@ -1,6 +1,10 @@
-// The status report of the CLI: the tools on this machine and the Host
-// Runtime with its tools.
+// The status report of the CLI: the installed skills and MCP declarations,
+// the tools on this machine and the Host Runtime with its tools.
 
+import { readFileSync } from "node:fs";
+import { isAbsolute, join } from "node:path";
+
+import { installedItems, scopeRoot, type InstallItem, type Scope } from "./cleanup.ts";
 import { hostTools, type ToolCallOptions } from "../host-client/tools.ts";
 import { viceVersionOf } from "../native/discover.ts";
 import { PACKAGE } from "../package.ts";
@@ -59,3 +63,66 @@ export function mixedViceBuilds(tools: readonly ToolStatus[]): string | undefine
   if (new Set(builds).size <= 1) return undefined;
   return `the VICE tools come from different VICE builds: ${running.map((tool) => `${tool.version} (${tool.path})`).join(", ")}. Put x64sc, c1541 and petcat of one VICE first on PATH, or set C64RT_VICE, C64RT_C1541 and C64RT_PETCAT.`;
 }
+
+/**
+ * The skills and MCP declarations that install wrote for this project and
+ * globally (b's R2-01): the c64-re-tools version of each harness's skills,
+ * from their package.json, and the command that starts the MCP server. A
+ * warning names skills of another version than this one.
+ */
+export function installedLines(cwd = process.cwd()): string[] {
+  const lines: string[] = [];
+  for (const scope of ["project", "global"] as const satisfies readonly Scope[]) {
+    const items = installedItems(scope, undefined, cwd);
+    if (items.length === 0) continue;
+    const root = scopeRoot(scope, cwd);
+    lines.push(`Installed ${scope === "project" ? `in this project (${root})` : "globally"}:`);
+    for (const harness of [...new Set(items.map((item) => item.harness))]) {
+      const skills = items.filter((item) => item.harness === harness && item.kind === "skill");
+      const versions = [...new Set(skills.map((item) => skillVersion(item, root)).filter((version) => version !== undefined))];
+      if (skills.length > 0) {
+        lines.push(`  ${harness}: ${skills.length} skills, c64-re-tools ${versions.length === 0 ? "of an unknown version" : versions.join(" and ")}`);
+        const other = versions.filter((version) => version !== PACKAGE.version);
+        if (other.length > 0) lines.push(`  Warning: the ${harness} skills are c64-re-tools ${other.join(" and ")} and this is ${PACKAGE.version}. Run npx -y ${PACKAGE.name}@${PACKAGE.tag} update${scope === "global" ? " --global" : ""} to install this version.`);
+      }
+      for (const item of items.filter((candidate) => candidate.harness === harness && candidate.kind === "mcp")) {
+        lines.push(`  ${harness} MCP server: ${mcpCommand(item, root) ?? `declared in ${item.files.join(", ")}`}`);
+      }
+    }
+  }
+  if (lines.length === 0) return ["Installed: nothing in this project or globally."];
+  lines.push("  The MCP server gives its own version in the result of c64_status.");
+  return lines;
+}
+
+function itemPath(file: string, root: string): string {
+  return isAbsolute(file) ? file : join(root, file);
+}
+
+/** The version in the package.json of an installed skill; a skill without scripts has none. */
+function skillVersion(item: InstallItem, root: string): string | undefined {
+  const file = item.files.find((candidate) => candidate.endsWith("/package.json") || candidate.endsWith("\\package.json"));
+  if (file === undefined) return undefined;
+  try {
+    const { version } = JSON.parse(readFileSync(itemPath(file, root), "utf8")) as { version?: unknown };
+    return typeof version === "string" ? version : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+/** The command of the MCP server in a JSON configuration file, or undefined for another format. */
+function mcpCommand(item: InstallItem, root: string): string | undefined {
+  const key = item.detail?.mergeKey;
+  const [file] = item.files;
+  if (key === undefined || file === undefined) return undefined;
+  try {
+    const servers = (JSON.parse(readFileSync(itemPath(file, root), "utf8")) as Record<string, unknown>)[key] as Record<string, { command?: unknown; args?: unknown }> | undefined;
+    const server = servers?.[item.name];
+    if (typeof server?.command !== "string") return undefined;
+    const args = Array.isArray(server.args) ? server.args.filter((arg): arg is string => typeof arg === "string") : [];
+    return [server.command, ...args].join(" ");
+  } catch {
+    return undefined;
+  }
+}

package/src/host/main.ts

@@ -7,6 +7,7 @@ import { ProcessSupervisor } from "../native/processes.ts";
 import { startTrace, trace } from "../trace.ts";
 import { ListenError, parsePort, startHostServer, stopSignal } from "./server.ts";
 import { viceFlaws, type ViceVersion } from "../native/discover.ts";
+import { inspect } from "./tools/c1541.ts";
 import { createToolDispatcher } from "./tools/index.ts";
 import { checkViceStarts, findVice } from "./vice/process.ts";
 import { viceSessionFactory } from "./vice/session.ts";
@@ -77,6 +78,9 @@ async function main(): Promise<number> {
     return 2;
   }
 
+  // First, so that every start, also a refused one, tells which runtime runs.
+  log(`${PACKAGE.name} ${PACKAGE.version} (Node.js ${process.version}, ${process.platform} ${process.arch})`);
+
   // Without an emulator the runtime is useless: refuse to start, by name and with the remedy.
   try {
     findVice(process.env);
@@ -111,7 +115,16 @@ async function main(): Promise<number> {
       host: "0.0.0.0",
       port,
       log,
-      createViceSession: viceSessionFactory({ supervisor, log, flaws }),
+      createViceSession: viceSessionFactory({
+        supervisor,
+        log,
+        flaws,
+        // c1541 lists the disk, so an autostart index selects a program (R2-08).
+        directory: async (imageType, image) => {
+          const { result } = await inspect({ action: "directory", imageType }, image, { supervisor, signal: new AbortController().signal, log });
+          return result.action === "directory" ? result.entries : [];
+        },
+      }),
       tools: createToolDispatcher({ supervisor, log, vice }),
     });
   } catch (error) {

package/src/host/vice/session.ts

@@ -3,8 +3,9 @@
 // session starts headless and can move the machine into a VICE with a window
 // and back; breakpoints, watchpoints and the rest go along.
 
-import { WireFailure, type VideoStandard } from "../../protocol/messages.ts";
-import { MAX_BASELINES, MAX_SNAPSHOTS, MAX_COMPARE_DIFFERENCES, RASTER, type Breakpoint, type BreakpointParams, type PointRemoved, type Condition, type ExecutionParams, type HistoryEntry, type RunTarget, type RunUntilResult, type ScreenComparison, type CiaSelection, type CiaState, type ObserveParams, type ObserveResult, type SidState, type SpriteState, type ViciiState, type JoystickState, type Watchpoint, type WatchpointParams, type ExecutionResult, type MachineStatus, type RunState, type ViceOperation, type ViceOperations, type WindowResult } from "../../protocol/vice.ts";
+import { isOneOf, WireFailure, type VideoStandard } from "../../protocol/messages.ts";
+import { DISK_IMAGE_TYPES, type DiskFile, type DiskImageType } from "../../protocol/tools.ts";
+import { MAX_BASELINES, MAX_SNAPSHOTS, MAX_COMPARE_DIFFERENCES, RASTER, type Breakpoint, type BreakpointParams, type PointRemoved, type Condition, type ExecutionParams, type HistoryEntry, type RunTarget, type RunUntilResult, type ScreenComparison, type CiaSelection, type CiaState, type ObserveParams, type ObserveResult, type SidState, type SpriteState, type ViciiState, type JoystickState, type Watchpoint, type WatchpointParams, type ExecutionResult, type MachineStatus, type PointStopReason, type RunState, type ViceOperation, type ViceOperations, type WindowResult } from "../../protocol/vice.ts";
 import { mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
@@ -123,8 +124,12 @@ export interface SessionOptions {
   ownPath?: (path: string) => () => void;
   /** The known flaws of this VICE version (D56); keyboard and joystick results name them. */
   flaws?: readonly string[];
+  /** Lists the entries of a disk image, so an autostart index is checked first (R2-08). Without it, VICE gets the index unchecked. */
+  directory?: DiskDirectory;
 }
 
+export type DiskDirectory = (type: DiskImageType, image: Buffer) => Promise<DiskFile[]>;
+
 /**
  * Where VICE keeps a staged file: an autostarted disk stays in drive 8, a tape
  * in the datasette and a cartridge in the port, until the same place gets
@@ -151,6 +156,7 @@ export class ViceSession implements ViceSessionHandle {
   readonly #untilReturnLimitMs: number;
   readonly #stepLimitMs: number;
   readonly #launch: ViceLauncher | undefined;
+  readonly #directory: DiskDirectory | undefined;
   /** Session files that outlive one VICE: snapshots, staged media, handovers. */
   readonly #workDir: string;
   readonly #releaseWorkDir: () => void;
@@ -177,6 +183,8 @@ export class ViceSession implements ViceSessionHandle {
   #driveStop = false;
   /** Counts stops caused by checkpoints or a CPU JAM rather than by a monitor command. */
   #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;
   #queue: Promise<unknown> = Promise.resolve();
   #closed = false;
   #lost = false;
@@ -218,6 +226,7 @@ export class ViceSession implements ViceSessionHandle {
     this.#untilReturnLimitMs = options.untilReturnLimitMs ?? UNTIL_RETURN_LIMIT_MS;
     this.#stepLimitMs = options.stepLimitMs ?? RUNNING_COMMAND_TIMEOUT_MS;
     this.#launch = options.launch;
+    this.#directory = options.directory;
     this.#inputFlaw = options.flaws === undefined || options.flaws.length === 0 ? undefined : options.flaws.join(" ");
     this.#workDir = mkdtempSync(join(tmpdir(), "c64-re-tools-session-"));
     this.#releaseWorkDir = options.ownPath?.(this.#workDir) ?? (() => {});
@@ -374,7 +383,9 @@ export class ViceSession implements ViceSessionHandle {
         return this.#programLoad(params as ViceOperations["programLoad"]["params"], onlyAttachment(attachments));
       case "autostart": {
         const { type, index, run } = params as ViceOperations["autostart"]["params"];
-        const file = this.#stage(onlyAttachment(attachments), type);
+        const bytes = onlyAttachment(attachments);
+        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.
         if (type !== "crt" && this.#cartridge) {
           await this.#observe(() => this.#machine.detachCartridge());
@@ -462,8 +473,12 @@ export class ViceSession implements ViceSessionHandle {
         return { cycles: (now - this.#timingStart).toString() };
       }
       case "profile": {
-        const { limit } = params as ViceOperations["profile"]["params"];
-        return { entries: await this.#observe(() => this.#machine.profile(limit)) };
+        const request = params as ViceOperations["profile"]["params"];
+        if (request.action === "clear") {
+          await this.#observe(() => this.#machine.startProfiler());
+          return { cleared: true };
+        }
+        return { entries: await this.#observe(() => this.#machine.profile(request.limit)) };
       }
       case "memmap": {
         const request = params as ViceOperations["memmap"]["params"];
@@ -508,7 +523,12 @@ export class ViceSession implements ViceSessionHandle {
     const warp = await this.#observe(() => this.#machine.warp());
     // Read after #observe: it resumes a running machine, unless a breakpoint or a JAM stopped it meanwhile.
     const status: MachineStatus = { state: this.#state, videoStandard: this.#videoStandard, warp, window: this.#mode === "window", cartridge: this.#cartridge };
-    if (status.state === "stopped") status.pc = await this.#pc();
+    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);
+      if (stop !== undefined) Object.assign(status, stop);
+    }
     return status;
   }
 
@@ -539,7 +559,13 @@ export class ViceSession implements ViceSessionHandle {
         throw new WireFailure("invalid-input", `The anchor is outside the frame: a ${this.#videoStandard} frame has lines 0-${raster.lines - 1} and cycles 0-${raster.cycles - 1}.`);
       }
       const outcome = await this.#runFrames(params.count, undefined, params.anchor);
-      return { state: "stopped", pc: outcome.pc, advancedFrames: outcome.frames };
+      return {
+        state: "stopped",
+        pc: outcome.pc,
+        advancedFrames: outcome.frames,
+        stopReason: outcome.end === "target" ? "frames" : outcome.end,
+        ...(outcome.pointId === undefined ? {} : { pointId: outcome.pointId }),
+      };
     }
     await this.#stop();
     if (params.action === "until-return") {
@@ -600,7 +626,7 @@ export class ViceSession implements ViceSessionHandle {
    * checkpoint, a user breakpoint or watchpoint, or a JAM ends the run early.
    * The machine is stopped afterwards.
    */
-  async #runFrames(limit: number, target?: { checkpoint: number; deferred: boolean }, anchor?: { line: number; cycle: number }): Promise<{ end: RunEnd; frames: number; pc: number; space: "c64" | "drive8" }> {
+  async #runFrames(limit: number, target?: { checkpoint: number; deferred: boolean }, anchor?: { line: number; cycle: number }): Promise<{ end: RunEnd; frames: number; pc: number; space: "c64" | "drive8"; pointId?: number }> {
     await this.#stop();
     const lines = RASTER[this.#videoStandard].lines;
     // A frame ends where the raster passes the anchor; without one, where this run starts.
@@ -642,7 +668,8 @@ export class ViceSession implements ViceSessionHandle {
         }
         // A drive stop is completed before the result names the computer's pc; `space` says which CPU stopped.
         const driveStop = this.#driveStop;
-        return { end, frames, pc: (await this.#completeDriveStop()) ?? stop.pc, space: driveStop ? "drive8" : "c64" };
+        const pointId = end === "target" ? undefined : this.#userPoint(stop.hits)?.pointId;
+        return { end, frames, pc: (await this.#completeDriveStop()) ?? stop.pc, space: driveStop ? "drive8" : "c64", ...(pointId === undefined ? {} : { pointId }) };
       }
     } finally {
       await this.#machine.deleteCheckpoint(clock);
@@ -659,6 +686,8 @@ export class ViceSession implements ViceSessionHandle {
   async #completeDriveStop(): Promise<number | undefined> {
     if (!this.#driveStop) return undefined;
     this.#driveStop = false;
+    // The drive checkpoint stopped the machine; the stop at the boundary keeps that reason.
+    const reason = this.#lastStop;
     const boundary = await this.#machine.addCheckpoint({ start: 0x0000, end: 0xffff, operation: 0x04, space: "c64" });
     try {
       for (let attempt = 0; attempt < DRIVE_STOP_TRIES; attempt++) {
@@ -669,6 +698,7 @@ export class ViceSession implements ViceSessionHandle {
         // The drive can hit its checkpoint again before the computer gets to the next instruction.
         if (stop.hits.includes(boundary)) {
           this.#driveStop = false;
+          this.#lastStop = reason;
           trace().event("vice.drive-stop", { pc: stop.pc, resumes: attempt + 1 });
           return stop.pc;
         }
@@ -683,14 +713,20 @@ export class ViceSession implements ViceSessionHandle {
   /** Names what caused a stop during a frame-clocked run. */
   #stopCause(stop: Stop, clock: number, target: number | undefined): Exclude<RunEnd, "frames" | "jam"> | "clock" | "unknown" {
     if (target !== undefined && stop.hits.includes(target)) return "target";
-    const isPoint = (registry: Map<number, { checkpoint: number }>) =>
-      [...registry.values()].some((point) => stop.hits.includes(point.checkpoint));
-    if (isPoint(this.#breakpoints)) return "breakpoint";
-    if (isPoint(this.#watchpoints)) return "watchpoint";
+    const point = this.#userPoint(stop.hits);
+    if (point !== undefined) return point.stopReason;
     if (stop.hits.includes(clock)) return "clock";
     return "unknown";
   }
 
+  /** The user breakpoint, else the user watchpoint, among the hit VICE checkpoints. */
+  #userPoint(hits: number[]): { stopReason: "breakpoint" | "watchpoint"; pointId: number } | undefined {
+    for (const [stopReason, registry] of [["breakpoint", this.#breakpoints], ["watchpoint", this.#watchpoints]] as const) {
+      for (const [pointId, point] of registry) if (hits.includes(point.checkpoint)) return { stopReason, pointId };
+    }
+    return undefined;
+  }
+
   async #jammedAt(pc: number): Promise<boolean> {
     const opcode = await this.#machine.readMemory({ address: pc, size: 1, space: "c64", view: "cpu" });
     return JAM_OPCODES.has(Number.parseInt(opcode, 16));
@@ -736,7 +772,7 @@ export class ViceSession implements ViceSessionHandle {
       const stopReason = outcome.end === "frames" ? "timeout" : outcome.end;
       // A stop event carries the computer's PC; a stop in the drive reports the drive's (F-31).
       const pc = outcome.space === "drive8" ? (await this.#machine.readRegisters("drive8")).pc : outcome.pc;
-      return { reached: stopReason === "target", stopReason, state: "stopped", pc, space: outcome.space };
+      return { reached: stopReason === "target", stopReason, state: "stopped", pc, space: outcome.space, ...(outcome.pointId === undefined ? {} : { pointId: outcome.pointId }) };
     } finally {
       await this.#machine.deleteCheckpoint(checkpoint);
     }
@@ -1185,6 +1221,7 @@ export class ViceSession implements ViceSessionHandle {
    */
   async #resumingCommand(send: () => Promise<void>): Promise<void> {
     this.#state = "running";
+    this.#lastStop = undefined;
     try {
       await send();
     } catch (error) {
@@ -1360,10 +1397,12 @@ export class ViceSession implements ViceSessionHandle {
       const stop: Stop = { pc: decodeProgramCounter(event.body), hits: this.#checkpointHits };
       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);
       this.#checkpointHits = [];
       this.#state = "stopped";
       this.#stopWaiters = this.#stopWaiters.filter((waiter) => !waiter(stop));
     } else if (event.type === ResponseType.resumed) {
+      this.#lastStop = undefined;
       this.#state = "running";
     }
   }
@@ -1400,6 +1439,17 @@ async function setPoint(
   return checkpoint;
 }
 
+/**
+ * Refuses an autostart index that selects no program: VICE numbers the
+ * entries from 1, and the caller from 0, as the c64-disk directory list does.
+ * A DEL entry holds no program (R2-08), and an index past the last entry selects nothing.
+ */
+function checkDirectoryEntry(entries: DiskFile[], index: number): void {
+  const entry = entries[index - 1];
+  if (entry === undefined) throw new WireFailure("invalid-input", `The disk has ${entries.length} directory entries, so index ${index - 1} selects no entry. The c64-disk directory list gives the index of each entry.`);
+  if (entry.type === "del") throw new WireFailure("invalid-input", `Directory entry ${index - 1} (${entry.name}) is a DEL entry and holds no program. Give the index of a PRG entry.`);
+}
+
 /** The production factory: launch a headless VICE per session through the host's supervisor. */
 export function viceSessionFactory(options: {
   supervisor: ProcessSupervisor;
@@ -1407,6 +1457,7 @@ export function viceSessionFactory(options: {
   log?: (line: string) => void;
   /** The known flaws of the VICE version that the host checked at start. */
   flaws?: readonly string[];
+  directory?: DiskDirectory;
 }): ViceSessionFactory {
   return async ({ videoStandard, log = options.log ?? (() => {}) }) => {
     const launch: ViceLauncher = (mode, launchLog) =>
@@ -1421,6 +1472,11 @@ export function viceSessionFactory(options: {
         ...(options.env === undefined ? {} : { env: options.env }),
       });
     const vice = await launch("headless", () => {});
-    return ViceSession.start(vice, videoStandard, log, { launch, ownPath: (path) => options.supervisor.ownPath(path), ...(options.flaws === undefined ? {} : { flaws: options.flaws }) });
+    return ViceSession.start(vice, videoStandard, log, {
+      launch,
+      ownPath: (path) => options.supervisor.ownPath(path),
+      ...(options.flaws === undefined ? {} : { flaws: options.flaws }),
+      ...(options.directory === undefined ? {} : { directory: options.directory }),
+    });
   };
 }

package/src/host-client/steps.ts

@@ -90,7 +90,7 @@ export function checkActionStep(kind: string, step: Record<string, unknown>, at:
       return;
     }
     case "frames":
-      if (!isInteger(step.frames, 1, MAX_EXECUTION_COUNT)) fail(`${at} needs a frame count from 1 to ${MAX_EXECUTION_COUNT}`);
+      if (!isInteger(step.frames, 1, MAX_TIMEOUT_FRAMES)) fail(`${at} needs a frame count from 1 to ${MAX_TIMEOUT_FRAMES}`);
       return;
     case "runUntil": {
       const target = step.runUntil;
@@ -154,7 +154,12 @@ export async function runActionStep(client: ViceSessionClient, step: ActionStep,
     await client.keyboard(textToPetscii(step.type));
   } else if ("frames" in step) {
     await stop(client);
-    await client.execution({ action: "advance-frames", count: step.frames, space: "c64" });
+    // One advance-frames runs at most MAX_EXECUTION_COUNT frames. Each part ends at the raster position
+    // where it started, so the parts give the same frames as one run; a breakpoint ends them all.
+    for (let left = step.frames; left > 0; left -= MAX_EXECUTION_COUNT) {
+      const part = await client.execution({ action: "advance-frames", count: Math.min(left, MAX_EXECUTION_COUNT), space: "c64" });
+      if (part.stopReason !== "frames") break;
+    }
   } else {
     const until = step.runUntil;
     const target: RunTarget =

package/src/host-client/vice-session.ts

@@ -2,7 +2,7 @@
 // one VICE. Exposes C64-domain operations only.
 
 import { ProtocolError, WireFailure, type VideoStandard } from "../protocol/messages.ts";
-import { validateViceResult, type Breakpoint, type BreakpointParams, type PointRemoved, type Watchpoint, type WatchpointParams, type ExecutionParams, type ExecutionResult, type JoystickState, type MachineStatus, type MemmapRange, type MemoryWriteParams, type RegisterValues, type ResetMode, type RunState, type RunTarget, type RunUntilResult, type MemoryReadParams, type MemoryReadResult, type Registers, type Space, type ViceOperation, type ViceOperations } from "../protocol/vice.ts";
+import { validateViceResult, type Breakpoint, type BreakpointParams, type PointRemoved, type Watchpoint, type WatchpointParams, type ExecutionParams, type ExecutionResult, type JoystickState, type MachineStatus, type MemmapRange, type MemoryWriteParams, type ProfileEntry, type RegisterValues, type ResetMode, type RunState, type RunTarget, type RunUntilResult, type MemoryReadParams, type MemoryReadResult, type Registers, type Space, type ViceOperation, type ViceOperations } from "../protocol/vice.ts";
 import { HostConnection } from "./connect.ts";
 import { readProjectFile } from "./transfer.ts";
 
@@ -186,8 +186,10 @@ export class ViceSessionClient {
     return this.#request("timing", { action });
   }
 
-  profile(limit: number): Promise<ViceOperations["profile"]["result"]> {
-    return this.#request("profile", { limit });
+  profile(params: { action: "read"; limit: number }): Promise<{ entries: ProfileEntry[] }>;
+  profile(params: { action: "clear" }): Promise<{ cleared: boolean }>;
+  profile(params: ViceOperations["profile"]["params"]): Promise<ViceOperations["profile"]["result"]> {
+    return this.#request("profile", params);
   }
 
   /** Action read gives the ranges; action clear gives cleared. */

package/src/mcp/server.ts

@@ -300,6 +300,7 @@ 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. " +
   "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.";
 
 export function createMcpServer(options: { tools: readonly ToolDefinition[]; session: SessionSource; log?: (line: string) => void }): Server {

package/src/mcp/tools/debug.ts

@@ -208,19 +208,33 @@ export const c64Profile = defineTool({
   name: "c64_profile",
   title: "Cycle profile",
   description:
-    "Get the routines where the C64 CPU spent the most cycles since the session started or since the last c64_window. " +
+    "Action read gets the routines where the C64 CPU spent the most cycles since the session started, the last clear or the last c64_window. " +
+    "Action clear sets all counts to zero, so that the next read measures only what runs after it. " +
+    "The emulator gives the cycles to the routine that a JSR called last. " +
+    "Code that the CPU enters with JMP or a branch counts for that routine. " +
     "After c64_window or a snapshot restore, the emulator can give the cycles to a routine that ran before the restore, for example $fd50. Do not trust the routine addresses then. " +
-    `limit is the maximum number of routines (1 to ${MAX_PROFILE}, default 20). ` +
+    `limit is the maximum number of routines for read (1 to ${MAX_PROFILE}, default 20). ` +
     "Each entry gives the routine address, its total cycles with the routines it calls, and its own cycles. " +
     "percent is the part of all cycles that the routine used itself. " +
     "Cycle counts are decimal strings.",
-  inputSchema: z.object({ limit: z.number().int().min(1).max(MAX_PROFILE).default(20) }).strict(),
+  inputSchema: z
+    .object({
+      action: z.enum(["read", "clear"]).default("read"),
+      limit: z.number().int().min(1).max(MAX_PROFILE).optional().describe("read only. Default 20"),
+    })
+    .strict(),
   outputSchema: z.object({
-    entries: z.array(z.object({ address: AddressOutput, totalCycles: z.string(), selfCycles: z.string(), percent: z.number() })),
+    entries: z.array(z.object({ address: AddressOutput, totalCycles: z.string(), selfCycles: z.string(), percent: z.number() })).optional(),
+    cleared: z.boolean().optional(),
   }),
-  readOnly: true,
+  readOnly: false,
   async run(input, session) {
-    const { entries } = await session.profile(input.limit);
+    const { action, ...fields } = input;
+    if (action === "clear") {
+      requireFields("clear", fields, []);
+      return session.profile({ action: "clear" });
+    }
+    const { entries } = await session.profile({ action: "read", limit: fields.limit ?? 20 });
     return { entries: entries.map((entry) => ({ ...entry, address: formatC64Address(entry.address) })) };
   },
 });
@@ -251,7 +265,8 @@ export const c64Memmap = defineTool({
     "If more ranges follow, the result also gives truncated: true and next. Read again with start set to next. " +
     "With out, read writes a coverage map to that project file, one byte for each address from start to end. " +
     "Bits 0 to 2 are RAM read, write and execute. Bits 3 and 4 are ROM read and execute. Bits 5 to 7 are I/O read, write and execute. " +
-    "Execute is set only on the first byte of each executed instruction. " +
+    "Execute is set only on the first byte of each executed instruction. Thus read gives a new range at each instruction of code. For code, use summary or read with out. " +
+    "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.",

package/src/mcp/tools/execution.ts

@@ -3,7 +3,7 @@
 import { z } from "zod";
 
 import { formatC64Address } from "../../c64.ts";
-import { COMPARISONS, EXECUTION_ACTIONS, MAX_EXECUTION_COUNT, MAX_TIMEOUT_FRAMES, RUN_STATES, SPACES, STOP_REASONS, type RunTarget } from "../../protocol/vice.ts";
+import { COMPARISONS, EXECUTION_ACTIONS, MAX_EXECUTION_COUNT, 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 } from "../server.ts";
 
 export const c64Execution = defineTool({
@@ -15,7 +15,9 @@ export const c64Execution = defineTool({
     "next executes count instructions (default 1) and treats a JSR and its subroutine as one instruction. " +
     "until-return runs until the current subroutine returns (after the next RTS or RTI). " +
     "advance-frames runs exactly count video frames (count is necessary). It stops at the same raster position, count frames later. " +
-    "A breakpoint or watchpoint can stop it before that. advancedFrames tells how many frames ran. " +
+    "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. " +
+    "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.",
   inputSchema: z
@@ -36,6 +38,8 @@ export const c64Execution = defineTool({
     pc: AddressOutput.optional(),
     executed: z.number().int().min(0).max(MAX_EXECUTION_COUNT).optional().describe("instructions executed by step or next"),
     advancedFrames: z.number().int().min(0).max(MAX_EXECUTION_COUNT).optional().describe("frames advance-frames ran"),
+    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"),
   }),
   readOnly: false,
   async run(input, session) {
@@ -46,6 +50,8 @@ export const c64Execution = defineTool({
       ...(result.pc === undefined ? {} : { pc: formatC64Address(result.pc) }),
       ...(result.executed === undefined ? {} : { executed: result.executed }),
       ...(result.advancedFrames === undefined ? {} : { advancedFrames: result.advancedFrames }),
+      ...(result.stopReason === undefined ? {} : { stopReason: result.stopReason }),
+      ...(result.pointId === undefined ? {} : { pointId: result.pointId }),
     };
   },
 });
@@ -88,6 +94,7 @@ export const c64RunUntil = defineTool({
     "Kind raster stops at the first instruction at or after a raster line and cycle. If the machine is there now, it stops at the next frame's pass. " +
     `timeoutFrames (1 to ${MAX_TIMEOUT_FRAMES}, default 3000) limits the run in video frames. ` +
     "reached tells if the target occurred. stopReason tells why the CPU stopped: target, breakpoint, watchpoint, jam (a JAM opcode) or timeout. " +
+    "pointId gives the id of the breakpoint or watchpoint that stopped the CPU. " +
     "space tells which CPU stopped: c64, or drive8 for a stop in the disk drive. pc is the address in that space. " +
     "The CPU is always stopped after this tool.",
   inputSchema: z
@@ -96,7 +103,14 @@ export const c64RunUntil = defineTool({
       timeoutFrames: z.number().int().min(1).max(MAX_TIMEOUT_FRAMES).default(3000),
     })
     .strict(),
-  outputSchema: z.object({ reached: z.boolean(), stopReason: z.enum(STOP_REASONS), state: z.enum(RUN_STATES), pc: AddressOutput, space: z.enum(SPACES) }),
+  outputSchema: z.object({
+    reached: z.boolean(),
+    stopReason: z.enum(STOP_REASONS),
+    state: z.enum(RUN_STATES),
+    pc: AddressOutput,
+    space: z.enum(SPACES),
+    pointId: z.number().int().min(1).optional().describe("the id of the breakpoint or watchpoint that stopped the CPU"),
+  }),
   readOnly: false,
   async run(input, session) {
     const { target: given } = input;

package/src/mcp/tools/machine.ts

@@ -3,8 +3,9 @@
 import { z } from "zod";
 
 import { formatC64Address } from "../../c64.ts";
+import { PACKAGE } from "../../package.ts";
 import { VIDEO_STANDARDS } from "../../protocol/messages.ts";
-import { RESET_MODES, RUN_STATES, WINDOW_ACTIONS } from "../../protocol/vice.ts";
+import { POINT_STOP_REASONS, RESET_MODES, RUN_STATES, WINDOW_ACTIONS } from "../../protocol/vice.ts";
 import { AddressOutput, defineTool } from "../server.ts";
 
 export const c64Status = defineTool({
@@ -14,7 +15,9 @@ export const c64Status = defineTool({
     "Get the state of the C64. The result tells if the CPU runs or has stopped, the video standard (pal or ntsc), " +
     "and if warp mode is on. It also tells if the emulator window is open (window). " +
     "When the CPU has stopped, the result also gives the program counter (pc). " +
-    "cartridge is true while a cartridge from c64_autostart is attached: a reset keeps it, and an autostart of another file detaches it.",
+    "When a breakpoint, a watchpoint or a JAM opcode stopped the CPU, stopReason tells which, and pointId gives the id of the breakpoint or watchpoint. " +
+    "cartridge is true while a cartridge from c64_autostart is attached: a reset keeps it, and an autostart of another file detaches it. " +
+    "version is the c64-re-tools version of this MCP server.",
   inputSchema: z.object({}).strict(),
   outputSchema: z.object({
     state: z.enum(RUN_STATES),
@@ -22,7 +25,10 @@ export const c64Status = defineTool({
     warp: z.boolean(),
     window: z.boolean().describe("true when the emulator window is open (c64_window)"),
     pc: AddressOutput.optional().describe("program counter. Only when the CPU is stopped"),
+    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"),
     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"),
   }),
   readOnly: true,
   async run(_input, session) {
@@ -33,7 +39,10 @@ export const c64Status = defineTool({
       warp: status.warp,
       window: status.window,
       cartridge: status.cartridge,
+      version: PACKAGE.version,
       ...(status.pc === undefined ? {} : { pc: formatC64Address(status.pc) }),
+      ...(status.stopReason === undefined ? {} : { stopReason: status.stopReason }),
+      ...(status.pointId === undefined ? {} : { pointId: status.pointId }),
     };
   },
 });

package/src/mcp/tools/media.ts

@@ -23,6 +23,7 @@ export const c64Autostart = defineTool({
     "A cartridge stays in the C64 through every reset, as on a real C64. An autostart of a file that is not a cartridge detaches it first. " +
     "Both joysticks are centred first: joystick port 1 uses the keyboard lines, and a held direction changes the RUN that the autostart types. " +
     "Without index, a disk image loads like LOAD\"*\",8,1. index selects one directory entry by its number in the c64-disk directory list (0 is the first entry). " +
+      "The tool refuses an index of a DEL entry, or an index after the last entry. " +
     "The machine runs when this tool returns, and the load continues.",
   inputSchema: z
     .object({