@henols/c64-re-tools 2.0.0-rc.9 → 2.0.0

package/src/mcp/main.ts

@@ -46,7 +46,7 @@ function videoStandard(env: NodeJS.ProcessEnv): VideoStandard {
  * 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
+ * session. 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.
  */

package/src/mcp/output.ts

@@ -1,14 +1,21 @@
-// Tool results written to a project file instead of the context (D39). The
-// MCP server runs on the agent's machine with the project as its working
-// directory, so it writes the file itself; the host never sees the path.
+// Tool results written to a project file instead of the context. 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 project rules find from the folder the agent started in.
 
 import { createHash } from "node:crypto";
 
 import { z } from "zod";
 
-import { writeProjectFile } from "../host-client/transfer.ts";
+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 directory, in place of returning it. An existing file is overwritten");
+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. */
+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 {
@@ -24,9 +31,9 @@ export const WrittenOutput = {
   sha256: z.string().regex(/^[0-9a-f]{64}$/).optional(),
 };
 
-/** Writes `data` to the project file `path` and gives what the result shows in its place. */
-export function writeOut(path: string, data: Uint8Array | string, root?: string): Written {
+/** Writes `data` to the file `path` of the project that `project` names (or the project lookup finds), and gives what the result shows in its place. */
+export function writeOut(path: string, data: Uint8Array | string, project: string | undefined): Written {
   const bytes = typeof data === "string" ? Buffer.from(data, "utf8") : data;
-  writeProjectFile(path, bytes, { what: "out", ...(root === undefined ? {} : { root }) });
+  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

@@ -41,6 +41,7 @@ export type ViceSessionApi = Pick<
   | "snapshotExport"
   | "snapshotRestore"
   | "cpuHistory"
+  | "trace"
   | "backtrace"
   | "timing"
   | "profile"
@@ -265,7 +266,7 @@ async function runCall(
     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).
+      // A session that the emulator never answered had no machine state: the call goes again on a new session.
       if (!(error instanceof LostBeforeAnswer)) throw error;
       output = await tool.run(parsed.data, await session());
     }
@@ -300,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

@@ -5,10 +5,10 @@ import { z } from "zod";
 
 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_MEMMAP_RANGES, MAX_MEMORY_READ, MAX_PROFILE, MAX_WATCH_SIZE, SPACES, TIMING_ACTIONS, WATCH_ACCESS, type Breakpoint, type Watchpoint } from "../../protocol/vice.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, writeOut, WrittenOutput } from "../output.ts";
-import { AddressInput, AddressOutput, Byte, ConditionInput, ConditionOutput, defineTool, HexData, requireFields, showCondition, SpaceInput, toCondition, type ViceSessionApi } from "../server.ts";
+import { OutInput, ProjectInput, writeOut, WrittenOutput } from "../output.ts";
+import { AddressInput, AddressOutput, Byte, ConditionInput, ConditionOutput, defineTool, HexData, requireFields, showCondition, SpaceInput, toCondition } from "../server.ts";
 import { spaced } from "./memory.ts";
 
 /** No default here: a filled-in default would count as a field the other actions refuse. */
@@ -135,7 +135,7 @@ export const c64CpuHistory = defineTool({
     "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() }).strict(),
+  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({
@@ -155,7 +155,8 @@ export const c64CpuHistory = defineTool({
   }),
   readOnly: false,
   async run(input, session) {
-    const { out, ...request } = input;
+    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");
@@ -163,7 +164,71 @@ 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`) };
+    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: false,
+  async run(input, session) {
+    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) };
   },
 });
 
@@ -207,19 +272,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) })) };
   },
 });
@@ -250,7 +329,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.",
@@ -261,6 +341,7 @@ export const c64Memmap = defineTool({
       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({
@@ -307,8 +388,8 @@ export const c64Memmap = defineTool({
       };
     }
     if (fields.out !== undefined) {
-      requireFields("read", fields, ["start", "end", "out"]);
-      return writeOut(fields.out, await readCoverage(session, start, end));
+      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 });
@@ -324,4 +405,4 @@ export const c64Memmap = defineTool({
   },
 });
 
-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, SPACES, 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,15 +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, 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"),
+    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;
@@ -110,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: 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 };
   },
 });
 

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

@@ -1,16 +1,16 @@
 // Media tools: c64_autostart, c64_program_load, c64_disk_attach and
-// c64_snapshot. Paths are project-relative; the host-client reads the file and
-// the Host Runtime receives only its bytes.
+// c64_snapshot. Paths are relative to the project folder; the host-client
+// reads the file and the Host Runtime receives only its bytes.
 
 import { z } from "zod";
 
 import { formatC64Address } from "../../c64.ts";
-import { readProjectFile } from "../../host-client/transfer.ts";
+import { projectFolder, readProjectFile } from "../../host-client/transfer.ts";
 import { AUTOSTART_TYPES, DISK_TYPES, MAX_SNAPSHOTS, RUN_STATES } from "../../protocol/vice.ts";
-import { OutInput, writeOut, WrittenOutput } from "../output.ts";
+import { OutInput, ProjectInput, writeOut, WrittenOutput } from "../output.ts";
 import { AddressInput, AddressOutput, defineTool, requireFields, TransientName } from "../server.ts";
 
-const ProjectPath = z.string().min(1).describe("path relative to the project directory, for example build/game.prg");
+const ProjectPath = z.string().min(1).describe("path relative to the project folder, for example build/game.prg");
 
 const list = (types: readonly string[]) => types.map((type) => `.${type}`).join(", ");
 
@@ -23,10 +23,12 @@ 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({
       path: ProjectPath,
+      project: ProjectInput.optional(),
       index: z.number().int().min(0).max(0xfffe).optional().describe("directory entry of a disk image, 0 is the first entry. Without it, the first file loads as with LOAD\"*\""),
       run: z.boolean().default(true).describe("true runs the program after it loads"),
     })
@@ -39,7 +41,7 @@ export const c64Autostart = defineTool({
   readOnly: false,
   async run(input, session) {
     // VICE numbers the directory entries from 1, and its 0 loads "*".
-    return session.autostart({ path: input.path, index: input.index === undefined ? 0 : input.index + 1, run: input.run });
+    return session.autostart({ path: input.path, index: input.index === undefined ? 0 : input.index + 1, run: input.run, root: projectFolder(input.project) });
   },
 });
 
@@ -53,13 +55,15 @@ export const c64ProgramLoad = defineTool({
   inputSchema: z
     .object({
       path: ProjectPath,
+      project: ProjectInput.optional(),
       address: AddressInput.optional().describe("load here instead of at the file's own load address"),
     })
     .strict(),
   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 result = await session.programLoad(input.address === undefined ? { path: input.path } : { path: input.path, address: input.address });
+    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 };
   },
 });
@@ -71,11 +75,11 @@ export const c64DiskAttach = defineTool({
     `Put a disk image from the project into drive 8 (${list(DISK_TYPES)}). ` +
     "Nothing loads or runs. To load from the disk, type LOAD on the C64 or use c64_autostart. " +
     "This does not change the run state of the machine.",
-  inputSchema: z.object({ path: ProjectPath }).strict(),
+  inputSchema: z.object({ path: ProjectPath, project: ProjectInput.optional() }).strict(),
   outputSchema: z.object({ attached: z.boolean() }),
   readOnly: false,
   async run(input, session) {
-    return session.diskAttach(input);
+    return session.diskAttach({ path: input.path, root: projectFolder(input.project) });
   },
 });
 
@@ -94,6 +98,7 @@ export const c64Snapshot = defineTool({
       name: TransientName.optional().describe("save and discard, and restore without file: 1 to 64 letters, digits, dots, underscores or hyphens"),
       out: OutInput.optional().describe("save only: also write the snapshot to this project file, for example snapshots/room0.vsf. An existing file is overwritten"),
       file: ProjectPath.optional().describe("restore only: a .vsf file in the project, in place of name"),
+      project: ProjectInput.optional().describe("save with out, and restore with file: the project folder, relative to the folder where the agent started. Give it when that folder is not in a project and has projects below it"),
     })
     .strict(),
   outputSchema: z.object({
@@ -113,13 +118,13 @@ export const c64Snapshot = defineTool({
       return session.snapshot({ action });
     }
     if (action === "restore" && fields.file !== undefined) {
-      requireFields(action, fields, ["file"], ["file"]);
-      return session.snapshotRestore(readProjectFile(fields.file).bytes);
+      requireFields(action, fields, ["file", "project"], ["file"]);
+      return session.snapshotRestore(readProjectFile(fields.file, { root: projectFolder(fields.project) }).bytes);
     }
     if (action === "save") {
-      requireFields(action, fields, ["name", "out"], ["name"]);
+      requireFields(action, fields, fields.out === undefined ? ["name"] : ["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!)) };
+      return fields.out === undefined ? saved : { ...saved, ...writeOut(fields.out, await session.snapshotExport(fields.name!), fields.project) };
     }
     requireFields(action, fields, ["name"], ["name"]);
     return session.snapshot({ action, name: fields.name! });

package/src/mcp/tools/memory.ts

@@ -6,12 +6,14 @@ 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, writeOut, WrittenOutput } from "../output.ts";
+import { OutInput, ProjectInput, writeOut, WrittenOutput } from "../output.ts";
 import { AddressInput, AddressOutput, Byte, defineTool, HexData, HexDataInput, MemoryViewInput, requireFields, SpaceInput } from "../server.ts";
 
-/** With out, a read or a disassembly can be larger than one answer of the session: it is read in parts (D39). */
+/** With out, a read or a disassembly can be larger than one answer of the session: it is read in parts. */
 const MAX_MEMORY_READ_OUT = 0x10000;
 const MAX_DISASSEMBLE_OUT = 32768;
+/** A memory byte in a result: two lowercase hex digits, as memory data is. */
+const HexByte = z.string().regex(/^[0-9a-f]{2}$/);
 
 export const c64MemoryRead = defineTool({
   name: "c64_memory_read",
@@ -28,12 +30,14 @@ export const c64MemoryRead = defineTool({
       space: SpaceInput,
       view: MemoryViewInput,
       out: OutInput.optional(),
+      project: ProjectInput.optional(),
     })
     .strict(),
   outputSchema: z.object({ address: AddressOutput, size: z.number().int().min(1).max(MAX_MEMORY_READ_OUT), data: HexData.optional(), ...WrittenOutput }),
   readOnly: false,
   async run(input, session) {
-    const { out, ...read } = input;
+    const { out, project, ...read } = input;
+    if (out === undefined && project !== undefined) throw new WireFailure("invalid-input", "project is used only with out.");
     if (out === undefined) {
       if (read.size > MAX_MEMORY_READ) throw new WireFailure("invalid-input", `size can be at most ${MAX_MEMORY_READ} without out.`);
       const result = await session.memoryRead(read);
@@ -45,7 +49,7 @@ export const c64MemoryRead = defineTool({
       const part = await session.memoryRead({ ...read, address: at, size: Math.min(MAX_MEMORY_READ, read.address + read.size - at) });
       parts.push(Buffer.from(part.data, "hex"));
     }
-    return { address: formatC64Address(read.address), size: read.size, ...writeOut(out, Buffer.concat(parts)) };
+    return { address: formatC64Address(read.address), size: read.size, ...writeOut(out, Buffer.concat(parts), project) };
   },
 });
 
@@ -180,6 +184,7 @@ export const c64MemoryCompare = defineTool({
   description:
     `Compare two memory ranges of size bytes (1 to ${MAX_COMPARE_SIZE}). Each range has its own address, space and view. ` +
     `The result tells if they are equal, how many bytes differ, and the first ${MAX_COMPARE_DIFFERENCES} differences with their offset. ` +
+    "The bytes of a difference are lowercase hex. " +
     "This does not change the run state of the machine.",
   inputSchema: z
     .object({ left: Location, right: Location, size: z.number().int().min(1).max(MAX_COMPARE_SIZE) })
@@ -187,11 +192,13 @@ export const c64MemoryCompare = defineTool({
   outputSchema: z.object({
     equal: z.boolean(),
     differentBytes: z.number().int().min(0),
-    firstDifferences: z.array(z.object({ offset: z.number().int().min(0), left: Byte, right: Byte })),
+    firstDifferences: z.array(z.object({ offset: z.number().int().min(0), left: HexByte, right: HexByte })),
   }),
   readOnly: true,
   async run(input, session) {
-    return session.memoryCompare(input);
+    const result = await session.memoryCompare(input);
+    const hex = (byte: number) => byte.toString(16).padStart(2, "0");
+    return { ...result, firstDifferences: result.firstDifferences.map((difference) => ({ ...difference, left: hex(difference.left), right: hex(difference.right) })) };
   },
 });
 
@@ -210,12 +217,14 @@ export const c64Disassemble = defineTool({
       space: SpaceInput,
       view: MemoryViewInput,
       out: OutInput.optional(),
+      project: ProjectInput.optional(),
     })
     .strict(),
   outputSchema: z.object({ instructions: z.array(z.object({ address: AddressOutput, bytes: HexData, text: z.string() })).optional(), count: z.number().int().min(0).optional(), ...WrittenOutput }),
   readOnly: false,
   async run(input, session) {
-    const { out, ...request } = input;
+    const { out, project, ...request } = input;
+    if (out === undefined && project !== undefined) throw new WireFailure("invalid-input", "project is used only with out.");
     if (out === undefined) {
       if (request.count > MAX_DISASSEMBLE) throw new WireFailure("invalid-input", `count can be at most ${MAX_DISASSEMBLE} without out.`);
       const result = await session.disassemble(request);
@@ -238,7 +247,7 @@ export const c64Disassemble = defineTool({
         address = instruction.address + instruction.bytes.length / 2;
       }
     }
-    return { count: lines.length, ...writeOut(out, `${lines.join("\n")}\n`) };
+    return { count: lines.length, ...writeOut(out, `${lines.join("\n")}\n`, project) };
   },
 });