@henols/c64-re-tools 1.1.0 → 2.0.0-rc.3

package/src/mcp/server.ts

@@ -0,0 +1,307 @@
+// MCP server creation, tool registration and the one place where failures
+// become MCP results. Tool groups live in tools/; nothing here knows VICE.
+
+import { createRequire } from "node:module";
+
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { CallToolRequestSchema, ListToolsRequestSchema, type CallToolResult, type Tool as McpTool } from "@modelcontextprotocol/sdk/types.js";
+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 { COMPARISONS, CONDITION_REGISTERS, MEMORY_VIEWS, SPACES, type Condition } from "../protocol/vice.ts";
+import { elapsedMs, trace, type TraceFields } from "../trace.ts";
+
+/** The session operations tools may call. */
+export type ViceSessionApi = Pick<
+  ViceSessionClient,
+  | "status"
+  | "memoryRead"
+  | "registersGet"
+  | "memoryWrite"
+  | "memorySearch"
+  | "memoryCompare"
+  | "disassemble"
+  | "registersSet"
+  | "execution"
+  | "reset"
+  | "warp"
+  | "window"
+  | "programLoad"
+  | "autostart"
+  | "diskAttach"
+  | "keyboard"
+  | "joystick"
+  | "screenCapture"
+  | "screenCompare"
+  | "screenBaselines"
+  | "screenDiscard"
+  | "snapshot"
+  | "cpuHistory"
+  | "backtrace"
+  | "timing"
+  | "profile"
+  | "memmap"
+  | "vicii"
+  | "sprites"
+  | "cia"
+  | "sid"
+  | "observe"
+  | "breakpoint"
+  | "watchpoint"
+  | "runUntil"
+>;
+
+/** Resolves the session, opening it on first use when the start-up attempt failed. */
+export type SessionSource = () => Promise<ViceSessionApi>;
+
+type JsonObject = Record<string, unknown>;
+
+// ---------------------------------------------------------------------------
+// Public schema primitives shared by the tool groups
+
+/** Input address: "$" and four hex digits, either case. Parses to a number. */
+export const AddressInput = z
+  .string()
+  .regex(/^\$[0-9a-fA-F]{4}$/, "must be $ followed by four hex digits, for example $c000")
+  .transform((value) => parseC64Address(value))
+  .describe("C64 address, $0000 to $ffff");
+
+/** Output address: "$" and four lowercase hex digits. */
+export const AddressOutput = z.string().regex(/^\$[0-9a-f]{4}$/).describe("C64 address, $0000 to $ffff");
+
+export const Byte = z.number().int().min(0).max(255);
+
+export const HexData = z.string().regex(/^(?:[0-9a-f]{2})*$/).describe("bytes as lowercase hex, two digits per byte, no separators");
+
+/** Input bytes: hex in either case, two digits per byte, at least one byte. Parses to lowercase. */
+export const HexDataInput = z
+  .string()
+  .regex(/^(?:[0-9a-fA-F]{2})+$/, "must be hex bytes, two digits per byte, no separators, for example a9008d20d0")
+  .transform((value) => value.toLowerCase());
+
+export const SpaceInput = z.enum(SPACES).default("c64").describe("c64 is the computer. drive8 is the 1541 disk drive CPU");
+
+export const MemoryViewInput = z
+  .enum(MEMORY_VIEWS)
+  .default("cpu")
+  .describe("cpu reads what the CPU sees now (ROM and I/O where banked in). ram reads the RAM underneath (c64 only)");
+
+/** A name the agent gives to something the session keeps, such as a screen baseline or a snapshot. */
+export const TransientName = z
+  .string()
+  .regex(/^[A-Za-z0-9._-]{1,64}$/, "must be 1 to 64 letters, digits, dots, underscores or hyphens")
+  .describe("a name you choose: 1 to 64 letters, digits, dots, underscores or hyphens");
+
+/**
+ * Checks the fields of one action of a multi-action tool: a field that the
+ * action does not use, or a missing required field, is an invalid-input error.
+ */
+export function requireFields(action: string, given: Record<string, unknown>, allowed: readonly string[], required: readonly string[] = []): void {
+  for (const [field, value] of Object.entries(given)) {
+    if (value !== undefined && !allowed.includes(field)) throw new WireFailure("invalid-input", `${field} is not used with action ${action}.`);
+  }
+  for (const field of required) {
+    if (given[field] === undefined) throw new WireFailure("invalid-input", `Action ${action} needs ${field}.`);
+  }
+}
+
+/** A tool result that carries content blocks (for example an image) beside its structured result. */
+export class ToolOutput<T> {
+  readonly structured: T;
+  readonly content: CallToolResult["content"];
+
+  constructor(structured: T, content: CallToolResult["content"]) {
+    this.structured = structured;
+    this.content = content;
+  }
+}
+
+export interface ToolDefinition<I extends z.ZodObject = z.ZodObject, O extends z.ZodObject = z.ZodObject> {
+  name: string;
+  title: string;
+  description: string;
+  inputSchema: I;
+  outputSchema: O;
+  /** True for operations that only observe the machine. */
+  readOnly: boolean;
+  run(input: z.output<I>, session: ViceSessionApi): Promise<z.input<O> | ToolOutput<z.input<O>>>;
+}
+
+/** A typed condition: register, memory or raster. No expression language. */
+export const ConditionInput = z
+  .discriminatedUnion("kind", [
+    z
+      .object({
+        kind: z.literal("register"),
+        register: z.enum(CONDITION_REGISTERS),
+        operator: z.enum(COMPARISONS),
+        value: Byte,
+      })
+      .strict(),
+    z
+      .object({
+        kind: z.literal("memory"),
+        address: AddressInput,
+        operator: z.enum(COMPARISONS),
+        value: Byte,
+        space: SpaceInput,
+        view: MemoryViewInput,
+      })
+      .strict(),
+    z
+      .object({
+        kind: z.literal("raster"),
+        line: z.number().int().min(0).describe("raster line: PAL 0-311, NTSC 0-262"),
+        cycle: z.number().int().min(0).optional().describe("cycle in the line: PAL 0-62, NTSC 0-64. True from this cycle on"),
+      })
+      .strict(),
+  ])
+  .describe("register: a CPU register compared to a byte. memory: a byte in memory compared to a byte. raster: the raster position");
+
+/** A condition as a result shows it: the input form, with the memory address as "$xxxx". */
+export const ConditionOutput = z
+  .discriminatedUnion("kind", [
+    z.object({ kind: z.literal("register"), register: z.enum(CONDITION_REGISTERS), operator: z.enum(COMPARISONS), value: Byte }),
+    z.object({ kind: z.literal("memory"), address: AddressOutput, operator: z.enum(COMPARISONS), value: Byte, space: z.enum(SPACES), view: z.enum(MEMORY_VIEWS) }),
+    z.object({ kind: z.literal("raster"), line: z.number().int().min(0), cycle: z.number().int().min(0).optional() }),
+  ])
+  .describe("the condition given at add");
+
+/** A protocol condition in its result form. */
+export function showCondition(condition: Condition): z.input<typeof ConditionOutput> {
+  return condition.kind === "memory" ? { ...condition, address: formatC64Address(condition.address) } : condition;
+}
+
+/** Removes keys whose value is undefined, so optional fields stay absent. */
+export function defined<T extends Record<string, unknown>>(value: T): T {
+  return Object.fromEntries(Object.entries(value).filter(([, entry]) => entry !== undefined)) as T;
+}
+
+/** A parsed condition input as the protocol type. */
+export function toCondition(input: z.output<typeof ConditionInput>): Condition {
+  return defined(input) as Condition;
+}
+
+/** Keeps a tool's handler typed against its own schemas. */
+export function defineTool<I extends z.ZodObject, O extends z.ZodObject>(tool: ToolDefinition<I, O>): ToolDefinition {
+  return tool as unknown as ToolDefinition;
+}
+
+function jsonSchema(schema: z.ZodObject, io: "input" | "output"): McpTool["inputSchema"] {
+  const { $schema: _ignored, ...rest } = z.toJSONSchema(schema, { io }) as JsonObject;
+  return rest as McpTool["inputSchema"];
+}
+
+export function toolListing(tool: ToolDefinition): McpTool {
+  return {
+    name: tool.name,
+    title: tool.title,
+    description: tool.description,
+    inputSchema: jsonSchema(tool.inputSchema, "input"),
+    outputSchema: jsonSchema(tool.outputSchema, "output"),
+    annotations: { title: tool.title, readOnlyHint: tool.readOnly, openWorldHint: false },
+  };
+}
+
+function errorResult(error: WireError): CallToolResult {
+  return { isError: true, content: [{ type: "text", text: JSON.stringify({ code: error.code, message: error.message }) }] };
+}
+
+/** "address: Invalid string: must match ..." style messages, one sentence per problem. */
+function describeIssues(error: z.ZodError): string {
+  return error.issues
+    .map((issue) => {
+      const where = issue.path.length === 0 ? "input" : issue.path.join(".");
+      return `${where}: ${issue.message}`;
+    })
+    .join(". ");
+}
+
+const INTERNAL_FAILURE: WireError = { code: "operation-failed", message: "The operation failed inside the c64-re-tools MCP server." };
+
+/** Runs one tool call and translates every outcome into an MCP result. The trace gets the call, its time and its outcome. */
+export async function callTool(
+  tools: ReadonlyMap<string, ToolDefinition>,
+  name: string,
+  args: unknown,
+  session: SessionSource,
+  log: (line: string) => void = () => {},
+): Promise<CallToolResult> {
+  const started = performance.now();
+  const result = await runCall(tools, name, args, session, log);
+  trace().event("tool.call", { name, args, ms: elapsedMs(started), ...outcome(result) });
+  return result;
+}
+
+/** What the trace records of a result: the structured result, or the code and message of the error. */
+function outcome(result: CallToolResult): TraceFields {
+  if (result.isError !== true) return { ok: true, result: result.structuredContent };
+  const first = result.content[0];
+  const text = first?.type === "text" ? first.text : "";
+  try {
+    return { ok: false, ...(JSON.parse(text) as WireError) };
+  } catch {
+    return { ok: false, message: text };
+  }
+}
+
+async function runCall(
+  tools: ReadonlyMap<string, ToolDefinition>,
+  name: string,
+  args: unknown,
+  session: SessionSource,
+  log: (line: string) => void,
+): Promise<CallToolResult> {
+  const tool = tools.get(name);
+  if (tool === undefined) return errorResult({ code: "invalid-input", message: `There is no tool named ${name}.` });
+  const parsed = tool.inputSchema.safeParse(args ?? {});
+  if (!parsed.success) return errorResult({ code: "invalid-input", message: describeIssues(parsed.error) });
+  try {
+    const 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.
+    const checked = tool.outputSchema.safeParse(output instanceof ToolOutput ? output.structured : output);
+    if (!checked.success) {
+      log(`${name} gave a result outside its output schema: ${describeIssues(checked.error)}`);
+      return errorResult(INTERNAL_FAILURE);
+    }
+    const result = checked.data as JsonObject;
+    const extra = output instanceof ToolOutput ? output.content : [];
+    return { content: [{ type: "text", text: JSON.stringify(result) }, ...extra], structuredContent: result };
+  } catch (error) {
+    if (error instanceof WireFailure) return errorResult(error.toWire());
+    log(`${name} failed: ${error instanceof Error ? (error.stack ?? error.message) : String(error)}`);
+    return errorResult(INTERNAL_FAILURE);
+  }
+}
+
+/** The version of this package. A package.json without a version is a broken installation. */
+function packageVersion(): string {
+  const { version } = createRequire(import.meta.url)("../../package.json") as { version?: unknown };
+  if (typeof version !== "string" || version === "") {
+    throw new Error("The package.json of c64-re-tools has no version. Install c64-re-tools again.");
+  }
+  return version;
+}
+
+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. " +
+  "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 {
+  const tools = new Map(options.tools.map((tool) => [tool.name, tool]));
+  const server = new Server(
+    { name: "c64-re-tools", version: packageVersion() },
+    { capabilities: { tools: {} }, instructions: INSTRUCTIONS },
+  );
+  server.setRequestHandler(ListToolsRequestSchema, async () => ({ tools: options.tools.map(toolListing) }));
+  server.setRequestHandler(CallToolRequestSchema, async (request) =>
+    callTool(tools, request.params.name, request.params.arguments, options.session, options.log),
+  );
+  return server;
+}

package/src/mcp/tools/debug.ts

@@ -0,0 +1,237 @@
+// Debug tools: c64_breakpoint, c64_watchpoint, c64_cpu_history, c64_backtrace,
+// c64_profile, c64_memmap and c64_timing.
+
+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";
+
+/** 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");
+
+const Id = z.number().int().min(1).describe("the id that action add returned");
+
+const BreakpointOutput = z.object({
+  id: z.number().int().min(1),
+  address: AddressOutput,
+  space: z.enum(SPACES),
+  enabled: z.boolean(),
+  condition: ConditionOutput.optional(),
+});
+const WatchpointOutput = BreakpointOutput.extend({ size: z.number().int().min(1).max(MAX_WATCH_SIZE), access: z.enum(WATCH_ACCESS) });
+
+function showBreakpoint(point: Breakpoint) {
+  const { condition, ...rest } = point;
+  return { ...rest, address: formatC64Address(point.address), ...(condition === undefined ? {} : { condition: showCondition(condition) }) };
+}
+
+function showWatchpoint(point: Watchpoint) {
+  const { condition, ...rest } = point;
+  return { ...rest, address: formatC64Address(point.address), ...(condition === undefined ? {} : { condition: showCondition(condition) }) };
+}
+
+export const c64Breakpoint = defineTool({
+  name: "c64_breakpoint",
+  title: "C64 breakpoints",
+  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. " +
+    "Breakpoints stay through a reset.",
+  inputSchema: z
+    .object({
+      action: z.enum(CHECKPOINT_ACTIONS),
+      address: AddressInput.optional().describe("add only"),
+      space: OptionalSpace,
+      condition: ConditionInput.optional().describe("add only: stop only when this is true"),
+      id: Id.optional().describe("remove, enable and disable only"),
+    })
+    .strict(),
+  outputSchema: BreakpointOutput.partial().extend({ breakpoints: z.array(BreakpointOutput).optional() }),
+  readOnly: false,
+  async run(input, session) {
+    const { action, ...fields } = input;
+    if (action === "list") {
+      requireFields(action, fields, []);
+      const result = await session.breakpoint({ action });
+      return { breakpoints: result.breakpoints.map(showBreakpoint) };
+    }
+    if (action !== "add") {
+      requireFields(action, fields, ["id"], ["id"]);
+      return showBreakpoint(await session.breakpoint({ action, id: fields.id! }));
+    }
+    requireFields(action, fields, ["address", "space", "condition"], ["address"]);
+    const added = await session.breakpoint({
+      action,
+      address: fields.address!,
+      space: fields.space ?? "c64",
+      ...(fields.condition === undefined ? {} : { condition: toCondition(fields.condition) }),
+    });
+    return showBreakpoint(added);
+  },
+});
+
+export const c64Watchpoint = defineTool({
+  name: "c64_watchpoint",
+  title: "C64 watchpoints",
+  description:
+    "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.",
+  inputSchema: z
+    .object({
+      action: z.enum(CHECKPOINT_ACTIONS),
+      address: AddressInput.optional().describe("add only"),
+      size: z.number().int().min(1).max(MAX_WATCH_SIZE).optional().describe("add only. Default 1"),
+      access: z.enum(WATCH_ACCESS).optional().describe("add only"),
+      space: OptionalSpace,
+      condition: ConditionInput.optional().describe("add only: stop only when this is true"),
+      id: Id.optional().describe("remove, enable and disable only"),
+    })
+    .strict(),
+  outputSchema: WatchpointOutput.partial().extend({ watchpoints: z.array(WatchpointOutput).optional() }),
+  readOnly: false,
+  async run(input, session) {
+    const { action, ...fields } = input;
+    if (action === "list") {
+      requireFields(action, fields, []);
+      const result = await session.watchpoint({ action });
+      return { watchpoints: result.watchpoints.map(showWatchpoint) };
+    }
+    if (action !== "add") {
+      requireFields(action, fields, ["id"], ["id"]);
+      return showWatchpoint(await session.watchpoint({ action, id: fields.id! }));
+    }
+    requireFields(action, fields, ["address", "size", "access", "space", "condition"], ["address", "access"]);
+    const added = await session.watchpoint({
+      action,
+      address: fields.address!,
+      size: fields.size ?? 1,
+      access: fields.access!,
+      space: fields.space ?? "c64",
+      ...(fields.condition === undefined ? {} : { condition: toCondition(fields.condition) }),
+    });
+    return showWatchpoint(added);
+  },
+});
+
+export const c64CpuHistory = defineTool({
+  name: "c64_cpu_history",
+  title: "CPU history",
+  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(),
+  outputSchema: z.object({
+    entries: z.array(
+      z.object({
+        address: AddressOutput,
+        bytes: HexData,
+        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(),
+      }),
+    ),
+  }),
+  readOnly: true,
+  async run(input, session) {
+    const { entries } = await session.cpuHistory(input);
+    return { entries: entries.map((entry) => ({ ...entry, address: formatC64Address(entry.address) })) };
+  },
+});
+
+export const c64Backtrace = defineTool({
+  name: "c64_backtrace",
+  title: "Call backtrace",
+  description:
+    `Get the chain of subroutine calls that leads to the current instruction, most recent first, at most depth calls (1 to ${MAX_BACKTRACE}, default 16). ` +
+    "Each frame gives the entry address of the routine and the address it returns to. " +
+    "The chain comes from the JSR return addresses on the stack, so it is a best estimate. Interrupts are not in the chain.",
+  inputSchema: z.object({ depth: z.number().int().min(1).max(MAX_BACKTRACE).default(16), space: SpaceInput }).strict(),
+  outputSchema: z.object({ frames: z.array(z.object({ address: AddressOutput, returnAddress: AddressOutput.optional() })) }),
+  readOnly: true,
+  async run(input, session) {
+    const { frames } = await session.backtrace(input);
+    return {
+      frames: frames.map((frame) => ({
+        address: formatC64Address(frame.address),
+        ...(frame.returnAddress === undefined ? {} : { returnAddress: formatC64Address(frame.returnAddress) }),
+      })),
+    };
+  },
+});
+
+export const c64Timing = defineTool({
+  name: "c64_timing",
+  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.",
+  inputSchema: z.object({ action: z.enum(TIMING_ACTIONS) }).strict(),
+  outputSchema: z.object({ started: z.boolean().optional(), cycles: z.string().regex(/^\d+$/).optional() }),
+  readOnly: false,
+  async run(input, session) {
+    return session.timing(input.action);
+  },
+});
+
+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). ` +
+    "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(),
+  outputSchema: z.object({
+    entries: z.array(z.object({ address: AddressOutput, totalCycles: z.string(), selfCycles: z.string(), percent: z.number() })),
+  }),
+  readOnly: true,
+  async run(input, session) {
+    const { entries } = await session.profile(input.limit);
+    return { entries: entries.map((entry) => ({ ...entry, address: formatC64Address(entry.address) })) };
+  },
+});
+
+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. " +
+    `It gives at most maxRanges ranges (1 to ${MAX_MEMMAP_RANGES}, default 256). Addresses the CPU did not touch are not in the result. ` +
+    "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"),
+    })
+    .strict(),
+  outputSchema: z.object({
+    ranges: z.array(z.object({ start: AddressOutput, end: AddressOutput, execute: z.boolean(), read: z.boolean(), write: z.boolean() })).optional(),
+    cleared: z.boolean().optional(),
+  }),
+  readOnly: false,
+  async run(input, session) {
+    if (input.action === "clear") {
+      requireFields("clear", { start: input.start, end: input.end, maxRanges: input.maxRanges }, []);
+      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) })) };
+  },
+});
+
+export const debugTools = [c64Breakpoint, c64Watchpoint, c64CpuHistory, c64Backtrace, c64Profile, c64Memmap, c64Timing];

package/src/mcp/tools/execution.ts

@@ -0,0 +1,116 @@
+// Execution tools: c64_execution and c64_run_until.
+
+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";
+
+export const c64Execution = defineTool({
+  name: "c64_execution",
+  title: "Control C64 execution",
+  description:
+    "Control the CPU. pause stops the CPU and gives the program counter (pc). resume lets the CPU run. " +
+    "step executes count instructions (default 1) and goes into subroutines. " +
+    "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. " +
+    "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
+    .object({
+      action: z.enum(EXECUTION_ACTIONS),
+      count: z
+        .number()
+        .int()
+        .min(1)
+        .max(MAX_EXECUTION_COUNT)
+        .optional()
+        .describe(`step and next: instructions (default 1). advance-frames: frames (necessary). 1 to ${MAX_EXECUTION_COUNT}`),
+      space: SpaceInput,
+    })
+    .strict(),
+  outputSchema: z.object({
+    state: z.enum(RUN_STATES),
+    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"),
+  }),
+  readOnly: false,
+  async run(input, session) {
+    const params = { action: input.action, space: input.space, ...(input.count === undefined ? {} : { count: input.count }) };
+    const result = await session.execution(params);
+    return {
+      state: result.state,
+      ...(result.pc === undefined ? {} : { pc: formatC64Address(result.pc) }),
+      ...(result.executed === undefined ? {} : { executed: result.executed }),
+      ...(result.advancedFrames === undefined ? {} : { advancedFrames: result.advancedFrames }),
+    };
+  },
+});
+
+const RunTargetInput = z.discriminatedUnion("kind", [
+  z
+    .object({
+      kind: z.literal("address"),
+      address: AddressInput,
+      space: SpaceInput,
+      condition: ConditionInput.optional().describe("stop at the address only when this is true"),
+    })
+    .strict(),
+  z
+    .object({
+      kind: z.literal("memory"),
+      address: AddressInput,
+      operator: z.enum(COMPARISONS),
+      value: Byte,
+      space: SpaceInput,
+      view: MemoryViewInput,
+    })
+    .strict(),
+  z
+    .object({
+      kind: z.literal("raster"),
+      line: z.number().int().min(0).describe("raster line: PAL 0-311, NTSC 0-262"),
+      cycle: z.number().int().min(0).optional().describe("cycle in the line: PAL 0-62, NTSC 0-64. Default 0"),
+    })
+    .strict(),
+]);
+
+export const c64RunUntil = defineTool({
+  name: "c64_run_until",
+  title: "Run the C64 until a target",
+  description:
+    "Run the CPU until a target occurs, then stop. " +
+    "Target kind address stops before the instruction at an address executes. An optional condition must also be true. " +
+    "Kind memory compares the byte at address to value with operator. It stops after a write that makes this comparison true. " +
+    "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. " +
+    "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),
+    })
+    .strict(),
+  outputSchema: z.object({ reached: z.boolean(), stopReason: z.enum(STOP_REASONS), state: z.enum(RUN_STATES), pc: AddressOutput }),
+  readOnly: false,
+  async run(input, session) {
+    const { target: given } = input;
+    let target: RunTarget;
+    if (given.kind === "address") {
+      target = { kind: "address", address: given.address, space: given.space };
+      if (given.condition !== undefined) target.condition = toCondition(given.condition);
+    } else if (given.kind === "memory") {
+      target = given;
+    } else {
+      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) };
+  },
+});
+
+export const executionTools = [c64Execution, c64RunUntil];