c64bridge 0.9.0 → 0.9.1

package/dist/tools/input.js

@@ -0,0 +1,338 @@
+import { createOperationDispatcher, defineToolModule, } from "./types.js";
+import { arraySchema, literalSchema, numberSchema, objectSchema, optionalSchema, stringSchema, } from "./schema.js";
+import { textResult } from "./responses.js";
+import { ToolValidationError, toolErrorResult, unknownErrorResult, } from "./errors.js";
+// ---------------------------------------------------------------------------
+// PETSCII token expansion table
+// Maps {TOKEN} placeholders to PETSCII/control-byte values that are queued via
+// KERNAL keyboard-buffer injection on both C64U and VICE.
+// ---------------------------------------------------------------------------
+const PETSCII_TOKENS = {
+    RETURN: 13,
+    CR: 13,
+    CLR: 147,
+    HOME: 19,
+    DEL: 20,
+    INS: 148,
+    INSERT: 148,
+    STOP: 3,
+    RUN: 131,
+    SHIFT_RETURN: 141,
+    F1: 133,
+    F2: 137,
+    F3: 134,
+    F4: 138,
+    F5: 135,
+    F6: 139,
+    F7: 136,
+    F8: 140,
+    UP: 145,
+    DOWN: 17,
+    LEFT: 157,
+    RIGHT: 29,
+    BLACK: 144,
+    WHITE: 5,
+    RED: 28,
+    CYAN: 159,
+    PURPLE: 156,
+    GREEN: 30,
+    BLUE: 31,
+    YELLOW: 158,
+    ORANGE: 129,
+    BROWN: 149,
+    LIGHT_RED: 150,
+    DARK_GREY: 151,
+    MEDIUM_GREY: 152,
+    LIGHT_GREEN: 153,
+    LIGHT_BLUE: 154,
+    LIGHT_GREY: 155,
+    REVERSE_ON: 18,
+    REVERSE_OFF: 146,
+    FLASH_ON: 130,
+    FLASH_OFF: 148,
+    LOWERCASE: 14,
+    UPPERCASE: 142,
+    ESCAPE: 27,
+    TAB: 9,
+    CURSOR_UP: 145,
+    CURSOR_DOWN: 17,
+    CURSOR_LEFT: 157,
+    CURSOR_RIGHT: 29,
+};
+function expandPetsciiTokens(text) {
+    return text.replace(/\{([^}]+)\}/g, (_match, token) => {
+        const upper = token.trim().toUpperCase();
+        const code = PETSCII_TOKENS[upper];
+        if (code !== undefined) {
+            return String.fromCharCode(code);
+        }
+        // Numeric form: {$1D} or {29}
+        let num;
+        if (upper.startsWith("$")) {
+            num = parseInt(upper.slice(1), 16);
+        }
+        else {
+            num = parseInt(upper, 10);
+        }
+        if (!isNaN(num) && num >= 0 && num <= 255) {
+            return String.fromCharCode(num);
+        }
+        return _match; // leave unrecognised tokens as-is
+    });
+}
+// ---------------------------------------------------------------------------
+// Joystick helpers
+// Port 2 → CIA1 Port A ($DC00), Port 1 → CIA1 Port B ($DC01)
+// Bits 0-4: Up / Down / Left / Right / Fire, active LOW (0 = pressed)
+// ---------------------------------------------------------------------------
+const JOYSTICK_PORT_ADDRESS = {
+    1: 0xDC01,
+    2: 0xDC00,
+};
+const JOYSTICK_BIT = {
+    up: 0,
+    down: 1,
+    left: 2,
+    right: 3,
+    fire: 4,
+};
+function joystickByte(controls) {
+    let mask = 0xff;
+    for (const ctrl of controls) {
+        const bit = JOYSTICK_BIT[ctrl.toLowerCase()];
+        if (bit !== undefined) {
+            mask &= ~(1 << bit);
+        }
+    }
+    return mask & 0xff;
+}
+// ---------------------------------------------------------------------------
+// Schemas
+// ---------------------------------------------------------------------------
+export const writeTextArgsSchema = objectSchema({
+    description: "Send a text string to the keyboard buffer, with PETSCII token expansion.",
+    properties: {
+        op: literalSchema("write_text"),
+        text: stringSchema({
+            description: "Text to type. Use {RETURN}, {CLR}, {F1}…{F8}, {UP/DOWN/LEFT/RIGHT}, colour names, etc.",
+            minLength: 1,
+            maxLength: 512,
+        }),
+        delayMs: optionalSchema(numberSchema({
+            description: "Delay in ms after sending (default 0).",
+            integer: true,
+            minimum: 0,
+            maximum: 10000,
+            default: 0,
+        })),
+    },
+    required: ["op", "text"],
+    additionalProperties: false,
+});
+export const keyArgsSchema = objectSchema({
+    description: "Tap a single key or hold it for a duration.",
+    properties: {
+        op: literalSchema("key"),
+        key: stringSchema({
+            description: "Key to press: a printable character, or a PETSCII token name (RETURN, F1…F8, UP, etc.).",
+            minLength: 1,
+            maxLength: 32,
+        }),
+        durationMs: optionalSchema(numberSchema({
+            description: "Delay in ms after each queued key press before the next press (default 0 = no delay).",
+            integer: true,
+            minimum: 0,
+            maximum: 5000,
+            default: 0,
+        })),
+        count: optionalSchema(numberSchema({
+            description: "Number of times to press the key (default 1).",
+            integer: true,
+            minimum: 1,
+            maximum: 100,
+            default: 1,
+        })),
+    },
+    required: ["op", "key"],
+    additionalProperties: false,
+});
+export const joystickArgsSchema = objectSchema({
+    description: "Simulate joystick input by writing directly to CIA1 Port A/B registers.",
+    properties: {
+        op: literalSchema("joystick"),
+        port: numberSchema({
+            description: "Joystick port (1 = $DC01, 2 = $DC00).",
+            integer: true,
+            minimum: 1,
+            maximum: 2,
+        }),
+        controls: arraySchema(stringSchema({
+            description: "Control to activate.",
+            enum: ["up", "down", "left", "right", "fire"],
+        }), {
+            description: "List of controls to activate simultaneously.",
+            minItems: 0,
+        }),
+        action: stringSchema({
+            description: "press = hold until a release call; release = restore all bits; tap = press then release after durationMs.",
+            enum: ["press", "release", "tap"],
+        }),
+        durationMs: optionalSchema(numberSchema({
+            description: "Duration to hold for tap action in ms (default 80).",
+            integer: true,
+            minimum: 10,
+            maximum: 5000,
+            default: 80,
+        })),
+    },
+    required: ["op", "port", "controls", "action"],
+    additionalProperties: false,
+});
+// ---------------------------------------------------------------------------
+// Handlers
+// ---------------------------------------------------------------------------
+function textToPetsciiBytes(text) {
+    const bytes = [];
+    for (let i = 0; i < text.length; i++) {
+        bytes.push(text.charCodeAt(i) & 0xff);
+    }
+    return Uint8Array.from(bytes);
+}
+const inputOperationHandlers = {
+    write_text: async (args, ctx) => {
+        try {
+            const parsed = writeTextArgsSchema.parse(args);
+            const expanded = expandPetsciiTokens(parsed.text);
+            const petsciiBytes = textToPetsciiBytes(expanded);
+            await ctx.client.injectKeyboardQueue(petsciiBytes);
+            if (parsed.delayMs && parsed.delayMs > 0) {
+                await new Promise((res) => setTimeout(res, parsed.delayMs));
+            }
+            ctx.logger.info("Sent keyboard text", { length: expanded.length });
+            return textResult(`Sent ${expanded.length} character(s) to keyboard buffer.`, { success: true, length: expanded.length });
+        }
+        catch (error) {
+            if (error instanceof ToolValidationError)
+                return toolErrorResult(error);
+            return unknownErrorResult(error);
+        }
+    },
+    key: async (args, ctx) => {
+        try {
+            const parsed = keyArgsSchema.parse(args);
+            const count = parsed.count ?? 1;
+            const durationMs = parsed.durationMs ?? 0;
+            // Resolve key to a character: try token first, then single char
+            const tokenCode = PETSCII_TOKENS[parsed.key.toUpperCase()];
+            const keyByte = tokenCode !== undefined
+                ? tokenCode
+                : parsed.key.length === 1
+                    ? parsed.key.charCodeAt(0) & 0xff
+                    : (() => {
+                        throw new ToolValidationError(`Unrecognised key: ${parsed.key}. Use a single character or a PETSCII token name.`, { path: "$.key" });
+                    })();
+            for (let i = 0; i < count; i++) {
+                await ctx.client.injectKeyboardQueue(Uint8Array.of(keyByte));
+                if (durationMs > 0) {
+                    await new Promise((res) => setTimeout(res, durationMs));
+                }
+            }
+            ctx.logger.info("Pressed key", { key: parsed.key, count, durationMs });
+            return textResult(`Pressed '${parsed.key}' ${count} time${count === 1 ? "" : "s"}.`, { success: true, key: parsed.key, count, durationMs });
+        }
+        catch (error) {
+            if (error instanceof ToolValidationError)
+                return toolErrorResult(error);
+            return unknownErrorResult(error);
+        }
+    },
+    joystick: async (args, ctx) => {
+        try {
+            const parsed = joystickArgsSchema.parse(args);
+            const port = parsed.port;
+            const addr = JOYSTICK_PORT_ADDRESS[port];
+            const durationMs = parsed.durationMs ?? 80;
+            const pressedByte = joystickByte(parsed.controls);
+            const releasedByte = 0xff;
+            if (parsed.action === "release") {
+                await ctx.client.viceMemSet(addr, Uint8Array.of(releasedByte));
+                ctx.logger.info("Released joystick", { port, address: `$${addr.toString(16).toUpperCase()}` });
+                return textResult(`Joystick port ${port} released.`, { success: true, port, action: "release" });
+            }
+            if (parsed.action === "press") {
+                await ctx.client.viceMemSet(addr, Uint8Array.of(pressedByte));
+                ctx.logger.info("Pressed joystick", { port, controls: parsed.controls, byte: pressedByte });
+                return textResult(`Joystick port ${port} pressed: ${parsed.controls.join(", ") || "none"}.`, { success: true, port, action: "press", controls: parsed.controls });
+            }
+            // tap: press → wait → release
+            await ctx.client.viceMemSet(addr, Uint8Array.of(pressedByte));
+            await new Promise((res) => setTimeout(res, durationMs));
+            await ctx.client.viceMemSet(addr, Uint8Array.of(releasedByte));
+            ctx.logger.info("Tapped joystick", { port, controls: parsed.controls, durationMs });
+            return textResult(`Joystick port ${port} tapped: ${parsed.controls.join(", ") || "none"} for ${durationMs}ms.`, { success: true, port, action: "tap", controls: parsed.controls, durationMs });
+        }
+        catch (error) {
+            if (error instanceof ToolValidationError)
+                return toolErrorResult(error);
+            return unknownErrorResult(error);
+        }
+    },
+};
+// ---------------------------------------------------------------------------
+// Module definition
+// ---------------------------------------------------------------------------
+export const inputModule = defineToolModule({
+    domain: "input",
+    summary: "Cross-platform keyboard input plus VICE-only joystick simulation.",
+    supportedPlatforms: ["c64u", "vice"],
+    resources: ["c64://specs/assembly", "c64://specs/memory-map"],
+    prompts: [],
+    defaultTags: ["input"],
+    workflowHints: [
+        "Use write_text with {RETURN} tokens to automate BASIC entry; prefer key for individual control keys.",
+        "write_text and key inject through the KERNAL keyboard queue ($0277/$00C6) so they work on both C64U and VICE.",
+        "Joystick tap is suitable for one-shot moves; use press/release pairs for timed holds. Joystick is VICE-only.",
+    ],
+    tools: [
+        {
+            name: "c64_input",
+            description: "Keyboard buffer injection (cross-platform) and joystick simulation (VICE only).",
+            summary: "Types text, taps keys, and simulates joystick movements.",
+            inputSchema: {
+                type: "object",
+                description: "Input operations: write_text, key, joystick.",
+                oneOf: [
+                    writeTextArgsSchema.jsonSchema,
+                    keyArgsSchema.jsonSchema,
+                    joystickArgsSchema.jsonSchema,
+                ],
+                discriminator: { propertyName: "op" },
+            },
+            operationPlatforms: { joystick: ["vice"] },
+            tags: ["input", "keyboard", "joystick"],
+            examples: [
+                {
+                    name: "Type BASIC line",
+                    description: "Enter a BASIC line and press RETURN",
+                    arguments: { op: "write_text", text: "PRINT \"HELLO\"{RETURN}" },
+                },
+                {
+                    name: "Press F1",
+                    description: "Send the F1 function key",
+                    arguments: { op: "key", key: "F1" },
+                },
+                {
+                    name: "Tap joystick right",
+                    description: "Brief rightward tap on joystick port 2",
+                    arguments: { op: "joystick", port: 2, controls: ["right"], action: "tap", durationMs: 80 },
+                },
+                {
+                    name: "Press fire on port 1",
+                    description: "Hold fire button on joystick port 1",
+                    arguments: { op: "joystick", port: 1, controls: ["fire"], action: "press" },
+                },
+            ],
+            execute: createOperationDispatcher("c64_input", inputOperationHandlers),
+        },
+    ],
+});

package/dist/tools/memory.js

@@ -1,8 +1,13 @@
 import { Buffer } from "node:buffer";
+import fs from "node:fs";
+import path from "node:path";
 import { defineToolModule, OPERATION_DISCRIMINATOR, } from "./types.js";
 import { booleanSchema, numberSchema, objectSchema, optionalSchema, stringSchema } from "./schema.js";
-import { textResult } from "./responses.js";
+import { jsonResult, textResult } from "./responses.js";
 import { ToolError, ToolExecutionError, ToolValidationError, toolErrorResult, unknownErrorResult, } from "./errors.js";
+import { disassemble, formatDisassembly } from "./disassembler.js";
+import { getViceSymbols } from "./symbolRegistry.js";
+import { resolveAddressSymbol } from "../knowledge.js";
 function toRecord(details) {
     if (details && typeof details === "object") {
         return details;
@@ -79,6 +84,18 @@ function supportsMachinePause(ctx) {
     const platformId = ctx.platform?.id;
     return platformId !== "vice";
 }
+export const __memoryHelpersForTests = {
+    toRecord,
+    normaliseFailure,
+    cleanHex,
+    parseUserHex,
+    parseFirmwareHex,
+    formatByte,
+    resolveAddressLabel,
+    resolveLength,
+    supportsMachinePause,
+    stripOperationDiscriminator,
+};
 const readScreenArgsSchema = objectSchema({
     description: "No arguments are required for reading the current screen contents.",
     properties: {},
@@ -352,11 +369,310 @@ async function executeWriteMemory(rawArgs, ctx) {
         return unknownErrorResult(error);
     }
 }
+const disassembleArgsSchema = objectSchema({
+    description: "Parameters for disassembling a block of VICE memory into 6502/6510 instructions.",
+    properties: {
+        address: stringSchema({
+            description: "Start address as $HHHH, decimal, or symbol name.",
+            minLength: 1,
+        }),
+        length: numberSchema({
+            description: "Number of bytes to read and disassemble.",
+            integer: true,
+            minimum: 1,
+            maximum: 4096,
+            default: 64,
+        }),
+        instructionCount: optionalSchema(numberSchema({
+            description: "Stop after this many instructions (overrides length as a termination condition).",
+            integer: true,
+            minimum: 1,
+            maximum: 512,
+        })),
+    },
+    required: ["address"],
+    additionalProperties: false,
+});
+async function executeDisassemble(rawArgs, ctx) {
+    try {
+        const parsed = disassembleArgsSchema.parse(rawArgs ?? {});
+        const length = parsed.length ?? 64;
+        ctx.logger.info("Disassembling VICE memory", { address: parsed.address, length });
+        const address = parseAddressArg(parsed.address, "$.address");
+        const bytes = await ctx.client.readMemoryRaw(address, length);
+        const symbols = ctx.platform?.id === "vice" ? getViceSymbols() : undefined;
+        const lines = disassemble(bytes, address, parsed.instructionCount, symbols);
+        const text = formatDisassembly(lines);
+        const addrHex = `$${address.toString(16).toUpperCase().padStart(4, "0")}`;
+        return textResult(`Disassembly of ${lines.length} instructions starting at ${addrHex}:\n\n${text}`, {
+            success: true,
+            address: addrHex,
+            bytesRead: bytes.length,
+            instructionCount: lines.length,
+        });
+    }
+    catch (error) {
+        if (error instanceof ToolError) {
+            return toolErrorResult(error);
+        }
+        return unknownErrorResult(error);
+    }
+}
+// ---------------------------------------------------------------------------
+// Shared address-parsing helper
+// ---------------------------------------------------------------------------
+function parseAddressArg(raw, fieldPath) {
+    const trimmed = raw.trim();
+    let addr;
+    if (/^\$[0-9A-Fa-f]+$/.test(trimmed)) {
+        addr = parseInt(trimmed.slice(1), 16);
+    }
+    else if (/^0[xX][0-9A-Fa-f]+$/.test(trimmed)) {
+        addr = parseInt(trimmed.slice(2), 16);
+    }
+    else if (/^[0-9]+$/.test(trimmed)) {
+        addr = parseInt(trimmed, 10);
+    }
+    else {
+        const resolved = resolveAddressSymbol(trimmed);
+        if (resolved === undefined) {
+            throw new ToolValidationError(`Unknown address or symbol: ${trimmed}`, { path: fieldPath });
+        }
+        addr = resolved;
+    }
+    if (!Number.isInteger(addr) || addr < 0 || addr > 0xffff) {
+        throw new ToolValidationError("Address must be in range $0000-$FFFF", { path: fieldPath });
+    }
+    return addr;
+}
+function fmtAddr(addr) {
+    return `$${addr.toString(16).toUpperCase().padStart(4, "0")}`;
+}
+function validateRangeWithinAddressSpace(start, length, fieldPath) {
+    const end = start + length - 1;
+    if (end > 0xffff) {
+        throw new ToolValidationError(`${fieldPath} range exceeds address space; ${fmtAddr(start)} + ${length} bytes would pass $FFFF.`, { path: fieldPath });
+    }
+}
+// ---------------------------------------------------------------------------
+// copy_memory
+// ---------------------------------------------------------------------------
+const copyMemoryArgsSchema = objectSchema({
+    description: "Copy a region of RAM from one address to another.",
+    properties: {
+        source: stringSchema({ description: "Source start address ($HHHH, decimal, or symbol).", minLength: 1 }),
+        dest: stringSchema({ description: "Destination start address.", minLength: 1 }),
+        length: numberSchema({ description: "Number of bytes to copy (1–16384).", integer: true, minimum: 1, maximum: 16384 }),
+    },
+    required: ["source", "dest", "length"],
+    additionalProperties: false,
+});
+async function executeCopyMemory(rawArgs, ctx) {
+    try {
+        const parsed = copyMemoryArgsSchema.parse(rawArgs ?? {});
+        const src = parseAddressArg(parsed.source, "$.source");
+        const dst = parseAddressArg(parsed.dest, "$.dest");
+        const len = parsed.length;
+        validateRangeWithinAddressSpace(src, len, "$.source");
+        validateRangeWithinAddressSpace(dst, len, "$.dest");
+        ctx.logger.info("Copying memory", { src: fmtAddr(src), dst: fmtAddr(dst), len });
+        const bytes = await ctx.client.readMemoryRaw(src, len);
+        await ctx.client.writeMemoryRaw(dst, bytes);
+        return textResult(`Copied ${bytes.length} bytes from ${fmtAddr(src)} to ${fmtAddr(dst)}.`, {
+            success: true, source: fmtAddr(src), dest: fmtAddr(dst), bytesCopied: bytes.length,
+        });
+    }
+    catch (error) {
+        if (error instanceof ToolError)
+            return toolErrorResult(error);
+        return unknownErrorResult(error);
+    }
+}
+// ---------------------------------------------------------------------------
+// fill_memory
+// ---------------------------------------------------------------------------
+const fillMemoryArgsSchema = objectSchema({
+    description: "Fill a memory region with a repeating byte pattern.",
+    properties: {
+        address: stringSchema({ description: "Start address ($HHHH, decimal, or symbol).", minLength: 1 }),
+        length: numberSchema({ description: "Number of bytes to fill (1–16384).", integer: true, minimum: 1, maximum: 16384 }),
+        pattern: stringSchema({
+            description: "Hex bytes to repeat, e.g. 'FF' or 'AA 55'. Space-separated or run together.",
+            minLength: 2,
+            pattern: /^[\s0-9A-Fa-f$]+$/,
+        }),
+    },
+    required: ["address", "length", "pattern"],
+    additionalProperties: false,
+});
+async function executeFillMemory(rawArgs, ctx) {
+    try {
+        const parsed = fillMemoryArgsSchema.parse(rawArgs ?? {});
+        const addr = parseAddressArg(parsed.address, "$.address");
+        validateRangeWithinAddressSpace(addr, parsed.length, "$.address");
+        const { bytes: patternBytes } = parseUserHex(parsed.pattern, "$.pattern");
+        if (patternBytes.length === 0)
+            throw new ToolValidationError("Pattern must not be empty", { path: "$.pattern" });
+        const buf = new Uint8Array(parsed.length);
+        for (let i = 0; i < parsed.length; i++)
+            buf[i] = patternBytes[i % patternBytes.length];
+        await ctx.client.writeMemoryRaw(addr, buf);
+        ctx.logger.info("Filled memory", { address: fmtAddr(addr), length: parsed.length, pattern: parsed.pattern });
+        return textResult(`Filled ${parsed.length} bytes at ${fmtAddr(addr)} with pattern ${parsed.pattern.trim()}.`, {
+            success: true, address: fmtAddr(addr), length: parsed.length, pattern: parsed.pattern.trim(),
+        });
+    }
+    catch (error) {
+        if (error instanceof ToolError)
+            return toolErrorResult(error);
+        return unknownErrorResult(error);
+    }
+}
+// ---------------------------------------------------------------------------
+// search_memory
+// ---------------------------------------------------------------------------
+const searchMemoryArgsSchema = objectSchema({
+    description: "Search for a byte pattern within a memory range.",
+    properties: {
+        startAddress: stringSchema({ description: "Start of search range ($HHHH, decimal, or symbol).", minLength: 1 }),
+        endAddress: stringSchema({ description: "End of search range (inclusive).", minLength: 1 }),
+        pattern: stringSchema({
+            description: "Hex bytes to find, e.g. 'A9 00' for LDA #$00.",
+            minLength: 2,
+            pattern: /^[\s0-9A-Fa-f$]+$/,
+        }),
+        maxResults: optionalSchema(numberSchema({ description: "Maximum matches to return (default 10).", integer: true, minimum: 1, maximum: 100, default: 10 })),
+    },
+    required: ["startAddress", "endAddress", "pattern"],
+    additionalProperties: false,
+});
+async function executeSearchMemory(rawArgs, ctx) {
+    try {
+        const parsed = searchMemoryArgsSchema.parse(rawArgs ?? {});
+        const start = parseAddressArg(parsed.startAddress, "$.startAddress");
+        const end = parseAddressArg(parsed.endAddress, "$.endAddress");
+        if (end < start)
+            throw new ToolValidationError("endAddress must be ≥ startAddress", { path: "$.endAddress" });
+        const { bytes: needle } = parseUserHex(parsed.pattern, "$.pattern");
+        if (needle.length === 0)
+            throw new ToolValidationError("Pattern must not be empty", { path: "$.pattern" });
+        const maxResults = parsed.maxResults ?? 10;
+        const len = end - start + 1;
+        ctx.logger.info("Searching memory", { start: fmtAddr(start), end: fmtAddr(end), pattern: parsed.pattern });
+        const haystack = await ctx.client.readMemoryRaw(start, len);
+        const matches = [];
+        outer: for (let i = 0; i <= haystack.length - needle.length && matches.length < maxResults; i++) {
+            for (let j = 0; j < needle.length; j++) {
+                if (haystack[i + j] !== needle[j])
+                    continue outer;
+            }
+            matches.push(fmtAddr(start + i));
+        }
+        return jsonResult({ found: matches.length, matches, pattern: parsed.pattern.trim(), range: { start: fmtAddr(start), end: fmtAddr(end) } }, { success: true, found: matches.length });
+    }
+    catch (error) {
+        if (error instanceof ToolError)
+            return toolErrorResult(error);
+        return unknownErrorResult(error);
+    }
+}
+// ---------------------------------------------------------------------------
+// compare_memory
+// ---------------------------------------------------------------------------
+const compareMemoryArgsSchema = objectSchema({
+    description: "Compare two memory regions and report differing bytes.",
+    properties: {
+        address1: stringSchema({ description: "First region start address.", minLength: 1 }),
+        address2: stringSchema({ description: "Second region start address.", minLength: 1 }),
+        length: numberSchema({ description: "Number of bytes to compare (1–16384).", integer: true, minimum: 1, maximum: 16384 }),
+        maxDiffs: optionalSchema(numberSchema({ description: "Max differences to report (default 10).", integer: true, minimum: 1, maximum: 200, default: 10 })),
+    },
+    required: ["address1", "address2", "length"],
+    additionalProperties: false,
+});
+async function executeCompareMemory(rawArgs, ctx) {
+    try {
+        const parsed = compareMemoryArgsSchema.parse(rawArgs ?? {});
+        const a1 = parseAddressArg(parsed.address1, "$.address1");
+        const a2 = parseAddressArg(parsed.address2, "$.address2");
+        const len = parsed.length;
+        const maxDiffs = parsed.maxDiffs ?? 10;
+        ctx.logger.info("Comparing memory regions", { a1: fmtAddr(a1), a2: fmtAddr(a2), len });
+        const [r1, r2] = await Promise.all([
+            ctx.client.readMemoryRaw(a1, len),
+            ctx.client.readMemoryRaw(a2, len),
+        ]);
+        const diffs = [];
+        for (let i = 0; i < len && diffs.length < maxDiffs; i++) {
+            if (r1[i] !== r2[i]) {
+                diffs.push({
+                    offset: i,
+                    address1: fmtAddr(a1 + i),
+                    address2: fmtAddr(a2 + i),
+                    value1: formatByte(r1[i] ?? 0),
+                    value2: formatByte(r2[i] ?? 0),
+                });
+            }
+        }
+        const identical = diffs.length === 0;
+        return jsonResult({ identical, diffCount: diffs.length, diffs, region1: fmtAddr(a1), region2: fmtAddr(a2), length: len }, { success: true, identical, diffCount: diffs.length });
+    }
+    catch (error) {
+        if (error instanceof ToolError)
+            return toolErrorResult(error);
+        return unknownErrorResult(error);
+    }
+}
+// ---------------------------------------------------------------------------
+// save_memory
+// ---------------------------------------------------------------------------
+const saveMemoryArgsSchema = objectSchema({
+    description: "Dump a memory region to a local file, optionally with a PRG load-address header.",
+    properties: {
+        startAddress: stringSchema({ description: "Start address of region to save.", minLength: 1 }),
+        endAddress: stringSchema({ description: "End address (inclusive).", minLength: 1 }),
+        filePath: stringSchema({ description: "Absolute or relative path for the output file.", minLength: 1 }),
+        asPrg: optionalSchema(booleanSchema({ description: "Prepend a 2-byte little-endian load-address header (PRG format). Default: true.", default: true })),
+    },
+    required: ["startAddress", "endAddress", "filePath"],
+    additionalProperties: false,
+});
+async function executeSaveMemory(rawArgs, ctx) {
+    try {
+        const parsed = saveMemoryArgsSchema.parse(rawArgs ?? {});
+        const start = parseAddressArg(parsed.startAddress, "$.startAddress");
+        const end = parseAddressArg(parsed.endAddress, "$.endAddress");
+        if (end < start)
+            throw new ToolValidationError("endAddress must be ≥ startAddress", { path: "$.endAddress" });
+        const asPrg = parsed.asPrg !== false;
+        const len = end - start + 1;
+        const resolvedPath = path.resolve(parsed.filePath);
+        ctx.logger.info("Saving memory to file", { start: fmtAddr(start), end: fmtAddr(end), filePath: resolvedPath, asPrg });
+        const bytes = await ctx.client.readMemoryRaw(start, len);
+        const header = asPrg ? Buffer.from([start & 0xff, (start >> 8) & 0xff]) : Buffer.alloc(0);
+        await fs.promises.mkdir(path.dirname(resolvedPath), { recursive: true });
+        await fs.promises.writeFile(resolvedPath, Buffer.concat([header, Buffer.from(bytes)]));
+        const fileSize = bytes.length + header.length;
+        return textResult(`Saved ${bytes.length} bytes (${fmtAddr(start)}–${fmtAddr(end)}) to ${resolvedPath}${asPrg ? " (PRG, with load address header)" : ""}.`, { success: true, filePath: resolvedPath, bytesRead: bytes.length, fileSize, asPrg, startAddress: fmtAddr(start), endAddress: fmtAddr(end) });
+    }
+    catch (error) {
+        if (error instanceof ToolError)
+            return toolErrorResult(error);
+        return unknownErrorResult(error);
+    }
+}
 export const memoryOperationHandlers = {
     read: async (args, ctx) => executeReadMemory(stripOperationDiscriminator(args), ctx),
     write: async (args, ctx) => executeWriteMemory(stripOperationDiscriminator(args), ctx),
     read_screen: async (args, ctx) => executeReadScreen(stripOperationDiscriminator(args), ctx),
+    disassemble: async (args, ctx) => executeDisassemble(stripOperationDiscriminator(args), ctx),
+    copy_memory: async (args, ctx) => executeCopyMemory(stripOperationDiscriminator(args), ctx),
+    fill_memory: async (args, ctx) => executeFillMemory(stripOperationDiscriminator(args), ctx),
+    search_memory: async (args, ctx) => executeSearchMemory(stripOperationDiscriminator(args), ctx),
+    compare_memory: async (args, ctx) => executeCompareMemory(stripOperationDiscriminator(args), ctx),
+    save_memory: async (args, ctx) => executeSaveMemory(stripOperationDiscriminator(args), ctx),
 };
+export { disassembleArgsSchema, copyMemoryArgsSchema, fillMemoryArgsSchema, searchMemoryArgsSchema, compareMemoryArgsSchema, saveMemoryArgsSchema, };
 export const memoryModule = defineToolModule({
     domain: "memory",
     summary: "Screen, main memory, and low-level inspection utilities.",