@henols/c64-re-tools 2.0.0-rc.2 → 2.0.0-rc.20

package/src/mcp/main.ts

@@ -13,25 +13,23 @@ import { machineTools } from "./tools/machine.ts";
 import { mediaTools } from "./tools/media.ts";
 import { memoryTools } from "./tools/memory.ts";
 import { videoTools } from "./tools/video.ts";
+import { PACKAGE } from "../package.ts";
 
 const HELP = `c64-re-tools-mcp
 
 Usage:
-  npx -y --package=@henols/c64-re-tools@latest c64-re-tools-mcp
+  npx -y --package=${PACKAGE.name}@${PACKAGE.tag} c64-re-tools-mcp
   c64-re-tools-mcp --help
 
 Runs the stateful C64 MCP server on stdio. Each c64-re-tools-mcp process owns
 one C64 emulator, started by the Host Runtime (c64-re-tools-host) when this
 server starts and stopped when it exits. c64-re-tools install declares it for
-the agent, through npx with the latest version.
+the agent, through npx with the newest version of its channel.
 
 Environment:
   C64RT_VIDEO  pal (default) or ntsc; fixed for the life of the process.
   C64RT_HOST   host:port of the Host Runtime when it is not on 127.0.0.1:6464,
-               host.docker.internal:6464 or host.containers.internal:6464.
-  C64RT_HOST_TOKEN
-               the shared secret of a Host Runtime that listens on an address
-               that is not loopback. Use the same value as the Host Runtime.`;
+               host.docker.internal:6464 or host.containers.internal:6464.`;
 
 function log(line: string): void {
   process.stderr.write(`c64-re-tools-mcp: ${line}\n`);
@@ -45,32 +43,59 @@ function videoStandard(env: NodeJS.ProcessEnv): VideoStandard {
 }
 
 /**
- * One session for the life of the process (1 MCP = 1 session = 1 VICE).
- * It opens at start; if that fails before a session existed (for example the
- * host was not running yet), the next tool call tries again. Once a session
- * existed, its loss is final and reported by the session itself. Close stops
+ * One session at a time (1 MCP = 1 session = 1 VICE). It opens at start; if
+ * that fails (for example the host was not running yet), the next tool call
+ * tries again. When the host connection is lost, the next call opens a new
+ * session (D57). A lost session that the emulator answered first gives its
+ * machine-state-lost once, unless a pending call got it already. Close stops
  * an open that is still waiting for the host at once.
  */
 function sessionSource(): { get: SessionSource; close(): Promise<void> } {
   let opening: Promise<ViceSessionClient> | undefined;
+  let lostNotice: WireFailure | undefined;
   let closed = false;
   const stop = new AbortController();
   const open = () => {
     const started = performance.now();
-    opening = (async () => ViceSessionClient.open({ videoStandard: videoStandard(process.env), signal: stop.signal }))();
-    void opening.then(() => trace().event("session.opened", { ms: elapsedMs(started) }), () => {});
-    opening.catch((error: unknown) => {
+    const current = (async () => ViceSessionClient.open({ videoStandard: videoStandard(process.env), signal: stop.signal }))();
+    opening = current;
+    void current.then(
+      (client) => {
+        trace().event("session.opened", { ms: elapsedMs(started) });
+        void client.closed.then(() => drop(current, client));
+      },
+      () => {},
+    );
+    current.catch((error: unknown) => {
       log(`session not opened: ${error instanceof Error ? error.message : String(error)}`);
-      opening = undefined;
+      if (opening === current) opening = undefined;
     });
-    return opening;
+    return current;
+  };
+  /** Forgets a lost session, once; the next call opens a new one. */
+  const drop = (current: Promise<ViceSessionClient>, client: ViceSessionClient) => {
+    if (closed || opening !== current) return;
+    log("the connection to the host runtime was lost; the next call opens a new session");
+    opening = undefined;
+    if (client.answered) lostNotice = client.unreportedLoss;
   };
   open();
+  const get = async (): Promise<ViceSessionClient> => {
+    if (closed) throw new WireFailure("machine-unavailable", "The C64 session is shutting down.");
+    if (lostNotice !== undefined) {
+      const notice = lostNotice;
+      lostNotice = undefined;
+      throw notice;
+    }
+    const current = opening ?? open();
+    const client = await current;
+    if (!client.lost) return client;
+    // The loss is known here before the close event reaches drop.
+    drop(current, client);
+    return get();
+  };
   return {
-    get: () => {
-      if (closed) return Promise.reject(new WireFailure("machine-unavailable", "The C64 session is shutting down."));
-      return opening ?? open();
-    },
+    get,
     async close() {
       closed = true;
       stop.abort();

package/src/mcp/output.ts

@@ -0,0 +1,39 @@
+// Tool results written to a project file instead of the context (D39). The
+// MCP server runs on the agent's machine, so it writes the file itself; the
+// host never sees the path. The project is the folder that `project` names,
+// or the one that the D67 rules find from the folder the agent started in (D68).
+
+import { createHash } from "node:crypto";
+
+import { z } from "zod";
+
+import { projectFolder, writeProjectFile } from "../host-client/transfer.ts";
+
+export const OutInput = z.string().min(1).describe("write the result to this file, relative to the project folder, in place of returning it. An existing file is overwritten");
+
+/** The project of a tool with a path (D67, D68). */
+export const ProjectInput = z
+  .string()
+  .min(1)
+  .describe("the project folder, relative to the folder where the agent started. Give it when that folder is not in a project and has projects below it. The paths of this call are relative to the project folder");
+
+/** What a result says in place of the bytes it wrote. */
+export interface Written {
+  out: string;
+  bytes: number;
+  sha256: string;
+}
+
+/** The fields of a result with out, optional in an output schema that also has the inline form. */
+export const WrittenOutput = {
+  out: z.string().optional(),
+  bytes: z.number().int().min(0).optional(),
+  sha256: z.string().regex(/^[0-9a-f]{64}$/).optional(),
+};
+
+/** Writes `data` to the file `path` of the project that `project` names (or the D67 lookup finds), and gives what the result shows in its place. */
+export function writeOut(path: string, data: Uint8Array | string, project: string | undefined): Written {
+  const bytes = typeof data === "string" ? Buffer.from(data, "utf8") : data;
+  writeProjectFile(path, bytes, { what: "out", root: projectFolder(project) });
+  return { out: path, bytes: bytes.length, sha256: createHash("sha256").update(bytes).digest("hex") };
+}

package/src/mcp/server.ts

@@ -8,8 +8,8 @@ import { CallToolRequestSchema, ListToolsRequestSchema, type CallToolResult, typ
 import { z } from "zod";
 
 import { formatC64Address, parseC64Address } from "../c64.ts";
-import type { ViceSessionClient } from "../host-client/vice-session.ts";
-import { WireFailure, type WireError } from "../protocol/messages.ts";
+import { LostBeforeAnswer, type ViceSessionClient } from "../host-client/vice-session.ts";
+import { shownMessage, WireFailure, type WireError } from "../protocol/messages.ts";
 import { COMPARISONS, CONDITION_REGISTERS, MEMORY_VIEWS, SPACES, type Condition } from "../protocol/vice.ts";
 import { elapsedMs, trace, type TraceFields } from "../trace.ts";
 
@@ -38,7 +38,10 @@ export type ViceSessionApi = Pick<
   | "screenBaselines"
   | "screenDiscard"
   | "snapshot"
+  | "snapshotExport"
+  | "snapshotRestore"
   | "cpuHistory"
+  | "trace"
   | "backtrace"
   | "timing"
   | "profile"
@@ -206,7 +209,7 @@ export function toolListing(tool: ToolDefinition): McpTool {
 }
 
 function errorResult(error: WireError): CallToolResult {
-  return { isError: true, content: [{ type: "text", text: JSON.stringify({ code: error.code, message: error.message }) }] };
+  return { isError: true, content: [{ type: "text", text: JSON.stringify({ code: error.code, message: shownMessage(error) }) }] };
 }
 
 /** "address: Invalid string: must match ..." style messages, one sentence per problem. */
@@ -259,7 +262,14 @@ async function runCall(
   const parsed = tool.inputSchema.safeParse(args ?? {});
   if (!parsed.success) return errorResult({ code: "invalid-input", message: describeIssues(parsed.error) });
   try {
-    const output = await tool.run(parsed.data, await session());
+    let output: unknown;
+    try {
+      output = await tool.run(parsed.data, await session());
+    } catch (error) {
+      // A session that the emulator never answered had no machine state: the call goes again on a new session (D57).
+      if (!(error instanceof LostBeforeAnswer)) throw error;
+      output = await tool.run(parsed.data, await session());
+    }
     // The result goes out in the shape that the tool listing advertises: keys
     // that the output schema does not name are removed, and a result that does
     // not fit the schema is an internal failure.
@@ -291,6 +301,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

@@ -3,9 +3,13 @@
 
 import { z } from "zod";
 
-import { formatC64Address } from "../../c64.ts";
-import { CHECKPOINT_ACTIONS, MAX_BACKTRACE, MAX_HISTORY, MAX_MEMMAP_RANGES, MAX_PROFILE, MAX_WATCH_SIZE, SPACES, TIMING_ACTIONS, WATCH_ACCESS, type Breakpoint, type Watchpoint } from "../../protocol/vice.ts";
-import { AddressInput, AddressOutput, Byte, ConditionInput, ConditionOutput, defineTool, HexData, requireFields, showCondition, SpaceInput, toCondition } from "../server.ts";
+import { COVERAGE, executedRamCode, EXECUTE, formatC64Address, READ, WRITE, type CodeRange } from "../../c64.ts";
+import { WireFailure } from "../../protocol/messages.ts";
+import { CHECKPOINT_ACTIONS, MAX_BACKTRACE, MAX_HISTORY, MAX_TRACE_FRAMES, MAX_TRACE_HITS, MAX_TRACE_POINTS, TRACE_KINDS, TRACE_ENDS, MAX_MEMMAP_RANGES, MAX_MEMORY_READ, MAX_PROFILE, MAX_WATCH_SIZE, SPACES, TIMING_ACTIONS, WATCH_ACCESS, type Breakpoint, type Watchpoint } from "../../protocol/vice.ts";
+import { readCoverage } from "../../host-client/coverage.ts";
+import { OutInput, ProjectInput, writeOut, WrittenOutput } from "../output.ts";
+import { AddressInput, AddressOutput, Byte, ConditionInput, ConditionOutput, defineTool, HexData, requireFields, showCondition, SpaceInput, toCondition, type ViceSessionApi } from "../server.ts";
+import { spaced } from "./memory.ts";
 
 /** No default here: a filled-in default would count as a field the other actions refuse. */
 const OptionalSpace = z.enum(SPACES).optional().describe("add only: c64 (default) or drive8, the 1541 disk drive CPU");
@@ -37,7 +41,8 @@ export const c64Breakpoint = defineTool({
   description:
     "Manage breakpoints. A breakpoint stops the CPU when it is about to execute the instruction at an address. " +
     "Action add sets one at address in space c64 or drive8. With a condition, it stops only when the condition is true. " +
-    "add returns the new id. Actions remove, enable and disable take that id. Action list gives all breakpoints. Each breakpoint shows its condition, when it has one. " +
+    "add returns the new id. Breakpoints and watchpoints take their ids from one counter, so the ids of one kind can have gaps. " +
+    "Actions remove, enable and disable take that id. remove returns removed true and the id. Action list gives all breakpoints. Each breakpoint shows its condition, when it has one. " +
     "Breakpoints stay through a reset.",
   inputSchema: z
     .object({
@@ -48,7 +53,7 @@ export const c64Breakpoint = defineTool({
       id: Id.optional().describe("remove, enable and disable only"),
     })
     .strict(),
-  outputSchema: BreakpointOutput.partial().extend({ breakpoints: z.array(BreakpointOutput).optional() }),
+  outputSchema: BreakpointOutput.partial().extend({ removed: z.literal(true).optional(), breakpoints: z.array(BreakpointOutput).optional() }),
   readOnly: false,
   async run(input, session) {
     const { action, ...fields } = input;
@@ -59,6 +64,7 @@ export const c64Breakpoint = defineTool({
     }
     if (action !== "add") {
       requireFields(action, fields, ["id"], ["id"]);
+      if (action === "remove") return session.breakpoint({ action, id: fields.id! });
       return showBreakpoint(await session.breakpoint({ action, id: fields.id! }));
     }
     requireFields(action, fields, ["address", "space", "condition"], ["address"]);
@@ -79,7 +85,8 @@ export const c64Watchpoint = defineTool({
     "Manage watchpoints. A watchpoint stops the CPU when an instruction reads or writes memory in a range. " +
     `Action add sets one at address for size bytes (1 to ${MAX_WATCH_SIZE}, default 1), with access read, write or read-write. ` +
     "With a condition, it stops only when the condition is true. For a write, a memory condition sees the memory after the write. " +
-    "add returns the new id. Actions remove, enable and disable take that id. Action list gives all watchpoints. Each watchpoint shows its condition, when it has one.",
+    "add returns the new id. Breakpoints and watchpoints take their ids from one counter, so the ids of one kind can have gaps. " +
+    "Actions remove, enable and disable take that id. remove returns removed true and the id. Action list gives all watchpoints. Each watchpoint shows its condition, when it has one.",
   inputSchema: z
     .object({
       action: z.enum(CHECKPOINT_ACTIONS),
@@ -91,7 +98,7 @@ export const c64Watchpoint = defineTool({
       id: Id.optional().describe("remove, enable and disable only"),
     })
     .strict(),
-  outputSchema: WatchpointOutput.partial().extend({ watchpoints: z.array(WatchpointOutput).optional() }),
+  outputSchema: WatchpointOutput.partial().extend({ removed: z.literal(true).optional(), watchpoints: z.array(WatchpointOutput).optional() }),
   readOnly: false,
   async run(input, session) {
     const { action, ...fields } = input;
@@ -102,6 +109,7 @@ export const c64Watchpoint = defineTool({
     }
     if (action !== "add") {
       requireFields(action, fields, ["id"], ["id"]);
+      if (action === "remove") return session.watchpoint({ action, id: fields.id! });
       return showWatchpoint(await session.watchpoint({ action, id: fields.id! }));
     }
     requireFields(action, fields, ["address", "size", "access", "space", "condition"], ["address", "access"]);
@@ -123,9 +131,11 @@ export const c64CpuHistory = defineTool({
   description:
     "Get the last instructions that the CPU executed, oldest first. " +
     `limit is the number of instructions (1 to ${MAX_HISTORY}, default 50). ` +
-    "Each entry gives the address, the bytes, the instruction and the registers a, x, y and sp. " +
-    "In space c64, it also gives the raster line and cycle when the instruction started. This does not change the run state of the machine.",
-  inputSchema: z.object({ limit: z.number().int().min(1).max(MAX_HISTORY).default(50), space: SpaceInput }).strict(),
+    "Each entry gives the address, the bytes, the instruction and the registers a, x, y and sp before the instruction executed. " +
+    "In space c64, it also gives the raster line and cycle when the instruction started. " +
+    "With out, it writes the entries as text lines to that project file, and the result gives the file in place of the entries. " +
+    "This does not change the run state of the machine.",
+  inputSchema: z.object({ limit: z.number().int().min(1).max(MAX_HISTORY).default(50), space: SpaceInput, out: OutInput.optional(), project: ProjectInput.optional() }).strict(),
   outputSchema: z.object({
     entries: z.array(
       z.object({
@@ -139,12 +149,86 @@ export const c64CpuHistory = defineTool({
         rasterLine: z.number().int().min(0).optional(),
         rasterCycle: z.number().int().min(0).optional(),
       }),
+    ).optional(),
+    count: z.number().int().min(0).optional(),
+    ...WrittenOutput,
+  }),
+  readOnly: false,
+  async run(input, session) {
+    const { out, project, ...request } = input;
+    if (out === undefined && project !== undefined) throw new WireFailure("invalid-input", "project is used only with out.");
+    const { entries } = await session.cpuHistory(request);
+    if (out === undefined) return { entries: entries.map((entry) => ({ ...entry, address: formatC64Address(entry.address) })) };
+    const byte = (value: number) => value.toString(16).padStart(2, "0");
+    const lines = entries.map((entry) => {
+      const raster = entry.rasterLine === undefined ? "" : `  line ${entry.rasterLine} cycle ${entry.rasterCycle ?? 0}`;
+      return `${formatC64Address(entry.address)}  ${spaced(entry.bytes).padEnd(9)} ${entry.text.padEnd(16)} a=${byte(entry.a)} x=${byte(entry.x)} y=${byte(entry.y)} sp=${byte(entry.sp)}${raster}`;
+    });
+    return { count: entries.length, ...writeOut(out, `${lines.join("\n")}\n`, project) };
+  },
+});
+
+/** The hits that a trace result gives inline; out gives all of them. */
+const TRACE_LISTED = 200;
+
+export const c64Trace = defineTool({
+  name: "c64_trace",
+  title: "Trace accesses and instructions",
+  description:
+    "Run the machine and record each hit of the points. The program does not stop for you. " +
+    "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. " +
+    "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. ` +
+    `The result lists the first ${TRACE_LISTED} hits. With out, it writes all hits as JSON lines to that project file. ` +
+    "Each hit stops the machine for a short time. Thus a point with many hits in each frame makes the trace slow. Use a small range and a maxHits. " +
+    "The machine is stopped after the trace.",
+  inputSchema: z
+    .object({
+      points: z.array(z.object({ kind: z.enum(TRACE_KINDS), start: AddressInput, end: AddressInput.optional() }).strict()).min(1).max(MAX_TRACE_POINTS),
+      frames: z.number().int().min(1).max(MAX_TRACE_FRAMES),
+      maxHits: z.number().int().min(1).max(MAX_TRACE_HITS).default(MAX_TRACE_HITS),
+      out: OutInput.optional(),
+      project: ProjectInput.optional(),
+    })
+    .strict(),
+  outputSchema: z.object({
+    end: z.enum(TRACE_ENDS),
+    frames: z.number().int().min(0),
+    pc: AddressOutput,
+    count: z.number().int().min(0),
+    hits: z.array(
+      z.object({
+        point: z.number().int().min(0),
+        pc: AddressOutput,
+        bytes: HexData,
+        text: z.string(),
+        a: Byte,
+        x: Byte,
+        y: Byte,
+        sp: Byte,
+        frame: z.number().int().min(0),
+        rasterLine: z.number().int().min(0),
+        rasterCycle: z.number().int().min(0),
+        address: AddressOutput.optional(),
+        value: Byte.optional(),
+      }),
     ),
+    ...WrittenOutput,
   }),
-  readOnly: true,
+  readOnly: false,
   async run(input, session) {
-    const { entries } = await session.cpuHistory(input);
-    return { entries: entries.map((entry) => ({ ...entry, address: formatC64Address(entry.address) })) };
+    const { out, project, points, ...request } = input;
+    if (out === undefined && project !== undefined) throw new WireFailure("invalid-input", "project is used only with out.");
+    const ranges = points.map((point) => ({ kind: point.kind, start: point.start, end: point.end ?? point.start }));
+    if (ranges.some((point) => point.end < point.start)) throw new WireFailure("invalid-input", "A point end must not be before its start.");
+    const traced = await session.trace({ points: ranges, ...request });
+    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) };
   },
 });
 
@@ -174,7 +258,8 @@ export const c64Timing = defineTool({
   title: "Cycle stopwatch",
   description:
     "A stopwatch that counts C64 CPU cycles. Action start sets it to zero. Action read gives the cycles since the last start, " +
-    "or since the session started, as a decimal string. A PAL frame has 19656 cycles and an NTSC frame 17095.",
+    "or since the session started, as a decimal string. A reset and c64_autostart start it again from the reset. " +
+    "A PAL frame has 19656 cycles and an NTSC frame 17095.",
   inputSchema: z.object({ action: z.enum(TIMING_ACTIONS) }).strict(),
   outputSchema: z.object({ started: z.boolean().optional(), cycles: z.string().regex(/^\d+$/).optional() }),
   readOnly: false,
@@ -187,51 +272,137 @@ 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. " +
-    `limit is the maximum number of routines (1 to ${MAX_PROFILE}, default 20). ` +
+    "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 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) })) };
   },
 });
 
+/** The most code ranges a memmap summary lists. */
+const MAX_SUMMARY_RANGES = 64;
+
+/** Where an access happened: RAM, ROM or I/O. */
+function sources(flags: number): Array<"ram" | "rom" | "io"> {
+  const where: Array<"ram" | "rom" | "io"> = [];
+  if (flags & (COVERAGE.ramRead | COVERAGE.ramWrite | COVERAGE.ramExecute)) where.push("ram");
+  if (flags & (COVERAGE.romRead | COVERAGE.romExecute)) where.push("rom");
+  if (flags & (COVERAGE.ioRead | COVERAGE.ioWrite | COVERAGE.ioExecute)) where.push("io");
+  return where;
+}
+
+const count = (map: Uint8Array, bit: number) => map.reduce((sum, flags) => sum + ((flags & bit) === 0 ? 0 : 1), 0);
+const RangeOutput = z.object({ start: AddressOutput, end: AddressOutput });
+const showRanges = (ranges: CodeRange[]) => ranges.slice(0, MAX_SUMMARY_RANGES).map((range) => ({ start: formatC64Address(range.start), end: formatC64Address(range.end) }));
+
 export const c64Memmap = defineTool({
   name: "c64_memmap",
   title: "Memory access map",
   description:
-    "Get how the C64 CPU used memory since the session started or since the last clear. " +
-    "Action read gives ranges of addresses with the same access (execute, read, write) from start to end. " +
+    "Get how the C64 CPU used memory since the session started or since the last clear. RAM, ROM and I/O are apart. " +
+    "Action read gives ranges of addresses with the same access (execute, read, write) from start to end. Each range also tells if the access was in RAM, ROM or I/O. " +
     `It gives at most maxRanges ranges (1 to ${MAX_MEMMAP_RANGES}, default 256). Addresses the CPU did not touch are not in the result. ` +
+    "If more ranges follow, the result also gives truncated: true and next. Read again with start set to next. " +
+    "With out, read writes a coverage map to that project file, one byte for each address from start to end. " +
+    "Bits 0 to 2 are RAM read, write and execute. Bits 3 and 4 are ROM read and execute. Bits 5 to 7 are I/O read, write and execute. " +
+    "Execute is set only on the first byte of each executed instruction. 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.",
   inputSchema: z
     .object({
-      action: z.enum(["read", "clear"]),
-      start: AddressInput.optional().describe("read only. Default $0000"),
-      end: AddressInput.optional().describe("read only. Default $ffff"),
-      maxRanges: z.number().int().min(1).max(MAX_MEMMAP_RANGES).optional().describe("read only. Default 256"),
+      action: z.enum(["read", "summary", "clear"]),
+      start: AddressInput.optional().describe("read and summary. Default $0000"),
+      end: AddressInput.optional().describe("read and summary. Default $ffff"),
+      maxRanges: z.number().int().min(1).max(MAX_MEMMAP_RANGES).optional().describe("read without out only. Default 256"),
+      out: OutInput.optional().describe("read only: write a coverage map to this project file, one byte for each address. An existing file is overwritten"),
+      project: ProjectInput.optional().describe("read with out only: the project folder, relative to the folder where the agent started. Give it when that folder is not in a project and has projects below it"),
     })
     .strict(),
   outputSchema: z.object({
-    ranges: z.array(z.object({ start: AddressOutput, end: AddressOutput, execute: z.boolean(), read: z.boolean(), write: z.boolean() })).optional(),
+    ranges: z.array(z.object({ start: AddressOutput, end: AddressOutput, execute: z.boolean(), read: z.boolean(), write: z.boolean(), in: z.array(z.enum(["ram", "rom", "io"])) })).optional(),
+    truncated: z.boolean().optional(),
+    next: AddressOutput.optional(),
+    ram: z.object({ executed: z.number().int(), read: z.number().int(), written: z.number().int() }).optional(),
+    rom: z.object({ executed: z.number().int(), read: z.number().int() }).optional(),
+    io: z.object({ executed: z.number().int(), read: z.number().int(), written: z.number().int() }).optional(),
+    code: z.array(RangeOutput).optional(),
+    codeTruncated: z.boolean().optional(),
+    writtenAndExecuted: z.array(RangeOutput).optional(),
+    writtenAndExecutedTruncated: z.boolean().optional(),
     cleared: z.boolean().optional(),
+    ...WrittenOutput,
   }),
   readOnly: false,
   async run(input, session) {
-    if (input.action === "clear") {
-      requireFields("clear", { start: input.start, end: input.end, maxRanges: input.maxRanges }, []);
+    const { action, ...fields } = input;
+    if (action === "clear") {
+      requireFields("clear", fields, []);
       return session.memmap({ action: "clear" });
     }
-    const result = await session.memmap({ action: "read", start: input.start ?? 0x0000, end: input.end ?? 0xffff, maxRanges: input.maxRanges ?? 256 });
-    return { ranges: result.ranges.map((range) => ({ ...range, start: formatC64Address(range.start), end: formatC64Address(range.end) })) };
+    const start = fields.start ?? 0x0000;
+    const end = fields.end ?? 0xffff;
+    if (end < start) throw new WireFailure("invalid-input", "end must not be before start.");
+    if (action === "summary") {
+      requireFields("summary", fields, ["start", "end"]);
+      const map = await readCoverage(session, start, end);
+      // The opcodes give the instruction lengths: RAM as it is now.
+      const parts: Buffer[] = [];
+      for (let at = 0; at < 0x10000; at += MAX_MEMORY_READ) parts.push(Buffer.from((await session.memoryRead({ address: at, size: MAX_MEMORY_READ, space: "c64", view: "ram" })).data, "hex"));
+      const memory = Buffer.concat(parts);
+      const code = executedRamCode(map, start, memory);
+      const written = executedRamCode(map.map((flags) => ((flags & COVERAGE.ramWrite) === 0 ? 0 : flags)), start, memory);
+      return {
+        ram: { executed: count(map, COVERAGE.ramExecute), read: count(map, COVERAGE.ramRead), written: count(map, COVERAGE.ramWrite) },
+        rom: { executed: count(map, COVERAGE.romExecute), read: count(map, COVERAGE.romRead) },
+        io: { executed: count(map, COVERAGE.ioExecute), read: count(map, COVERAGE.ioRead), written: count(map, COVERAGE.ioWrite) },
+        code: showRanges(code),
+        ...(code.length > MAX_SUMMARY_RANGES ? { codeTruncated: true } : {}),
+        writtenAndExecuted: showRanges(written),
+        ...(written.length > MAX_SUMMARY_RANGES ? { writtenAndExecutedTruncated: true } : {}),
+      };
+    }
+    if (fields.out !== undefined) {
+      requireFields("read", fields, ["start", "end", "out", "project"]);
+      return writeOut(fields.out, await readCoverage(session, start, end), fields.project);
+    }
+    requireFields("read", fields, ["start", "end", "maxRanges"]);
+    const result = await session.memmap({ action: "read", start, end, maxRanges: fields.maxRanges ?? 256 });
+    const ranges = result.ranges.map((range) => ({
+      start: formatC64Address(range.start),
+      end: formatC64Address(range.end),
+      execute: (range.flags & EXECUTE) !== 0,
+      read: (range.flags & READ) !== 0,
+      write: (range.flags & WRITE) !== 0,
+      in: sources(range.flags),
+    }));
+    return result.next === undefined ? { ranges } : { ranges, truncated: true, next: formatC64Address(result.next) };
   },
 });
 
-export const debugTools = [c64Breakpoint, c64Watchpoint, c64CpuHistory, c64Backtrace, c64Profile, c64Memmap, c64Timing];
+export const debugTools = [c64Breakpoint, c64Watchpoint, c64CpuHistory, c64Trace, c64Backtrace, c64Profile, c64Memmap, c64Timing];

package/src/mcp/tools/execution.ts

@@ -3,8 +3,9 @@
 import { z } from "zod";
 
 import { formatC64Address } from "../../c64.ts";
-import { COMPARISONS, EXECUTION_ACTIONS, MAX_EXECUTION_COUNT, MAX_TIMEOUT_FRAMES, RUN_STATES, STOP_REASONS, type RunTarget } from "../../protocol/vice.ts";
-import { AddressInput, AddressOutput, Byte, ConditionInput, defineTool, MemoryViewInput, SpaceInput, toCondition } from "../server.ts";
+import { COMPARISONS, EXECUTION_ACTIONS, MAX_EXECUTION_COUNT, MAX_HISTORY, MAX_TIMEOUT_FRAMES, POINT_STOP_REASONS, RUN_STATES, SPACES, STOP_REASONS, type RunTarget } from "../../protocol/vice.ts";
+import { AddressInput, AddressOutput, Byte, ConditionInput, defineTool, MemoryViewInput, SpaceInput, toCondition, ToolOutput } from "../server.ts";
+import { c64Observe } from "./video.ts";
 
 export const c64Execution = defineTool({
   name: "c64_execution",
@@ -15,7 +16,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 +39,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 +51,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,14 +95,32 @@ 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. " +
+    "With observe, the result also gives what c64_observe gives at the stop, in observed. " +
+    `With history (1 to ${MAX_HISTORY}), it also gives the last instructions before the stop, as c64_cpu_history gives them. ` +
+    "Thus one call runs to a place and reads the machine there. " +
     "The CPU is always stopped after this tool.",
   inputSchema: z
     .object({
       target: RunTargetInput,
       timeoutFrames: z.number().int().min(1).max(MAX_TIMEOUT_FRAMES).default(3000),
+      observe: c64Observe.inputSchema.optional().describe("what to read at the stop, as for c64_observe"),
+      history: z.number().int().min(1).max(MAX_HISTORY).optional().describe("the number of instructions before the stop to give"),
     })
     .strict(),
-  outputSchema: z.object({ reached: z.boolean(), stopReason: z.enum(STOP_REASONS), state: z.enum(RUN_STATES), pc: AddressOutput }),
+  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"),
+    observed: c64Observe.outputSchema.optional(),
+    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(),
+  }),
   readOnly: false,
   async run(input, session) {
     const { target: given } = input;
@@ -109,7 +134,16 @@ export const c64RunUntil = defineTool({
       target = given.cycle === undefined ? { kind: "raster", line: given.line } : { kind: "raster", line: given.line, cycle: given.cycle };
     }
     const result = await session.runUntil({ target, timeoutFrames: input.timeoutFrames });
-    return { ...result, pc: formatC64Address(result.pc) };
+    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) })) };
+    if (input.observe === undefined) return { ...answer, ...history };
+    // The observation at the stop (M23.10): an image of the screen comes with the result as c64_observe gives it.
+    const observed = await c64Observe.run(input.observe, session);
+    if (observed instanceof ToolOutput) return new ToolOutput({ ...answer, ...history, observed: observed.structured }, observed.content);
+    return { ...answer, ...history, observed };
   },
 });