c64bridge 0.5.0

package/dist/tools/machineControl.js

@@ -0,0 +1,267 @@
+import { defineToolModule } from "./types.js";
+import { objectSchema } from "./schema.js";
+import { textResult } from "./responses.js";
+import { ToolError, ToolExecutionError, toolErrorResult, unknownErrorResult, } from "./errors.js";
+function createNoArgsSchema(description) {
+    return objectSchema({
+        description,
+        properties: {},
+        additionalProperties: false,
+    });
+}
+function toRecord(details) {
+    if (details && typeof details === "object") {
+        return details;
+    }
+    return undefined;
+}
+function normaliseFailure(details) {
+    if (details === undefined || details === null) {
+        return undefined;
+    }
+    if (typeof details === "object") {
+        return details;
+    }
+    return { value: details };
+}
+const resetArgsSchema = createNoArgsSchema("No arguments required to reset the C64.");
+const rebootArgsSchema = createNoArgsSchema("No arguments required to reboot the C64 firmware.");
+const pauseArgsSchema = createNoArgsSchema("No arguments required to pause the machine via DMA.");
+const resumeArgsSchema = createNoArgsSchema("No arguments required to resume the machine after a pause.");
+const poweroffArgsSchema = createNoArgsSchema("No arguments required to power off the machine.");
+const menuButtonArgsSchema = createNoArgsSchema("No arguments required to toggle the Ultimate menu button.");
+export const machineControlModule = defineToolModule({
+    domain: "machine",
+    summary: "Power, reset, pause/resume, and diagnostic controls for the C64 and Ultimate hardware.",
+    resources: ["c64://context/bootstrap"],
+    prompts: ["memory-debug"],
+    defaultTags: ["machine", "control"],
+    workflowHints: [
+        "Reach for machine controls when the user mentions resets, power states, or DMA pause/resume.",
+        "Explain the operational impact (e.g. soft reset vs firmware reboot) so the user knows what changed.",
+    ],
+    tools: [
+        {
+            name: "reset_c64",
+            description: "Reset the C64 via Ultimate firmware. Review c64://context/bootstrap safety rules.",
+            summary: "Issues a soft reset, equivalent to power cycling without cutting power.",
+            inputSchema: resetArgsSchema.jsonSchema,
+            tags: ["reset"],
+            prerequisites: [],
+            examples: [
+                { name: "Soft reset", description: "Reset machine", arguments: {} },
+            ],
+            workflowHints: [
+                "Use when the user wants a quick restart without losing power; mention that memory contents may persist.",
+            ],
+            async execute(args, ctx) {
+                try {
+                    resetArgsSchema.parse(args ?? {});
+                    ctx.logger.info("Resetting C64");
+                    const result = await ctx.client.reset();
+                    if (!result.success) {
+                        throw new ToolExecutionError("C64 firmware reported failure while resetting", {
+                            details: normaliseFailure(result.details),
+                        });
+                    }
+                    const details = toRecord(result.details) ?? {};
+                    return textResult("C64 reset command issued successfully.", {
+                        success: true,
+                        details,
+                    });
+                }
+                catch (error) {
+                    if (error instanceof ToolError) {
+                        return toolErrorResult(error);
+                    }
+                    return unknownErrorResult(error);
+                }
+            },
+        },
+        {
+            name: "reboot_c64",
+            description: "Reboot the Ultimate firmware and C64. See c64://context/bootstrap.",
+            summary: "Triggers a firmware reboot, useful after configuration changes.",
+            inputSchema: rebootArgsSchema.jsonSchema,
+            tags: ["reboot"],
+            prerequisites: [],
+            examples: [
+                { name: "Firmware reboot", description: "Hard reboot", arguments: {} },
+            ],
+            workflowHints: [
+                "Choose reboot when configuration changed or hardware is stuck; warn that it will interrupt any running program.",
+            ],
+            async execute(args, ctx) {
+                try {
+                    rebootArgsSchema.parse(args ?? {});
+                    ctx.logger.info("Rebooting C64");
+                    const result = await ctx.client.reboot();
+                    if (!result.success) {
+                        throw new ToolExecutionError("C64 firmware reported failure while rebooting", {
+                            details: normaliseFailure(result.details),
+                        });
+                    }
+                    const details = toRecord(result.details) ?? {};
+                    return textResult("C64 reboot command issued successfully.", {
+                        success: true,
+                        details,
+                    });
+                }
+                catch (error) {
+                    if (error instanceof ToolError) {
+                        return toolErrorResult(error);
+                    }
+                    return unknownErrorResult(error);
+                }
+            },
+        },
+        {
+            name: "pause",
+            description: "Pause the machine using DMA halt. See memory safety checklist in c64://context/bootstrap.",
+            summary: "Suspends CPU execution until resumed.",
+            inputSchema: pauseArgsSchema.jsonSchema,
+            tags: ["pause"],
+            prerequisites: [],
+            examples: [
+                { name: "Pause", description: "Halt CPU", arguments: {} },
+            ],
+            workflowHints: [
+                "Pause when the user needs a stable memory snapshot; remind them to resume to continue execution.",
+            ],
+            async execute(args, ctx) {
+                try {
+                    pauseArgsSchema.parse(args ?? {});
+                    ctx.logger.info("Pausing C64 execution");
+                    const result = await ctx.client.pause();
+                    if (!result.success) {
+                        throw new ToolExecutionError("C64 firmware reported failure while pausing", {
+                            details: normaliseFailure(result.details),
+                        });
+                    }
+                    const details = toRecord(result.details) ?? {};
+                    return textResult("C64 execution paused.", {
+                        success: true,
+                        details,
+                    });
+                }
+                catch (error) {
+                    if (error instanceof ToolError) {
+                        return toolErrorResult(error);
+                    }
+                    return unknownErrorResult(error);
+                }
+            },
+        },
+        {
+            name: "resume",
+            description: "Resume the machine after a DMA pause.",
+            summary: "Releases the DMA halt so the CPU can continue.",
+            inputSchema: resumeArgsSchema.jsonSchema,
+            tags: ["resume"],
+            prerequisites: ["pause"],
+            examples: [
+                { name: "Resume", description: "Continue CPU", arguments: {} },
+            ],
+            workflowHints: [
+                "Call after a pause or diagnostic halt and confirm the machine is running again.",
+            ],
+            async execute(args, ctx) {
+                try {
+                    resumeArgsSchema.parse(args ?? {});
+                    ctx.logger.info("Resuming C64 execution");
+                    const result = await ctx.client.resume();
+                    if (!result.success) {
+                        throw new ToolExecutionError("C64 firmware reported failure while resuming", {
+                            details: normaliseFailure(result.details),
+                        });
+                    }
+                    const details = toRecord(result.details) ?? {};
+                    return textResult("C64 execution resumed.", {
+                        success: true,
+                        details,
+                    });
+                }
+                catch (error) {
+                    if (error instanceof ToolError) {
+                        return toolErrorResult(error);
+                    }
+                    return unknownErrorResult(error);
+                }
+            },
+        },
+        {
+            name: "poweroff",
+            description: "Power off the machine via Ultimate firmware. See safety notes in c64://context/bootstrap.",
+            summary: "Attempts a controlled shutdown through the Ultimate control interface.",
+            inputSchema: poweroffArgsSchema.jsonSchema,
+            tags: ["power"],
+            prerequisites: [],
+            examples: [
+                { name: "Power off", description: "Shut down", arguments: {} },
+            ],
+            workflowHints: [
+                "Use when the user explicitly requests power off; remind them to power on manually or via drive controls afterwards.",
+            ],
+            async execute(args, ctx) {
+                try {
+                    poweroffArgsSchema.parse(args ?? {});
+                    ctx.logger.info("Powering off C64");
+                    const result = await ctx.client.poweroff();
+                    if (!result.success) {
+                        throw new ToolExecutionError("C64 firmware reported failure while powering off", {
+                            details: normaliseFailure(result.details),
+                        });
+                    }
+                    const details = toRecord(result.details) ?? {};
+                    return textResult("Power off command acknowledged.", {
+                        success: true,
+                        details,
+                    });
+                }
+                catch (error) {
+                    if (error instanceof ToolError) {
+                        return toolErrorResult(error);
+                    }
+                    return unknownErrorResult(error);
+                }
+            },
+        },
+        {
+            name: "menu_button",
+            description: "Toggle the Ultimate 64 menu button.",
+            summary: "Simulates the on-device menu button for navigation or exit.",
+            inputSchema: menuButtonArgsSchema.jsonSchema,
+            tags: ["menu"],
+            prerequisites: [],
+            examples: [
+                { name: "Menu", description: "Toggle menu", arguments: {} },
+            ],
+            workflowHints: [
+                "Use when the user needs to open or close the Ultimate menu; suggest following up with drive operations if relevant.",
+            ],
+            async execute(args, ctx) {
+                try {
+                    menuButtonArgsSchema.parse(args ?? {});
+                    ctx.logger.info("Toggling Ultimate menu button");
+                    const result = await ctx.client.menuButton();
+                    if (!result.success) {
+                        throw new ToolExecutionError("C64 firmware reported failure while toggling menu button", {
+                            details: normaliseFailure(result.details),
+                        });
+                    }
+                    const details = toRecord(result.details) ?? {};
+                    return textResult("Menu button command sent.", {
+                        success: true,
+                        details,
+                    });
+                }
+                catch (error) {
+                    if (error instanceof ToolError) {
+                        return toolErrorResult(error);
+                    }
+                    return unknownErrorResult(error);
+                }
+            },
+        },
+    ],
+});

package/dist/tools/memory.js

@@ -0,0 +1,224 @@
+import { defineToolModule } from "./types.js";
+import { numberSchema, objectSchema, stringSchema } from "./schema.js";
+import { textResult } from "./responses.js";
+import { ToolError, ToolExecutionError, toolErrorResult, unknownErrorResult } from "./errors.js";
+function toRecord(details) {
+    if (details && typeof details === "object") {
+        return details;
+    }
+    return undefined;
+}
+function normaliseFailure(details) {
+    if (details === undefined || details === null) {
+        return undefined;
+    }
+    if (typeof details === "object") {
+        return details;
+    }
+    return { value: details };
+}
+const readScreenArgsSchema = objectSchema({
+    description: "No arguments are required for reading the current screen contents.",
+    properties: {},
+    additionalProperties: false,
+});
+const readMemoryArgsSchema = objectSchema({
+    description: "Parameters for reading a block of memory from the C64.",
+    properties: {
+        address: stringSchema({
+            description: "Start address expressed as $HHHH, decimal, or a documented symbol name.",
+            minLength: 1,
+        }),
+        length: numberSchema({
+            description: "Number of bytes to read starting from the resolved address.",
+            integer: true,
+            minimum: 1,
+            maximum: 4096,
+            default: 256,
+        }),
+    },
+    required: ["address"],
+    additionalProperties: false,
+});
+const writeMemoryArgsSchema = objectSchema({
+    description: "Parameters for writing hexadecimal bytes into C64 memory.",
+    properties: {
+        address: stringSchema({
+            description: "Destination address expressed as $HHHH, decimal, or a documented symbol name.",
+            minLength: 1,
+        }),
+        bytes: stringSchema({
+            description: "Hex byte sequence like $AABBCC or AA BB CC to write starting at the resolved address.",
+            minLength: 2,
+            pattern: /^[\s_0-9A-Fa-f$]+$/,
+        }),
+    },
+    required: ["address", "bytes"],
+    additionalProperties: false,
+});
+export const memoryModule = defineToolModule({
+    domain: "memory",
+    summary: "Screen, main memory, and low-level inspection utilities.",
+    resources: [
+        "c64://context/bootstrap",
+        "c64://specs/basic",
+        "c64://specs/assembly",
+    ],
+    prompts: ["memory-debug", "basic-program", "assembly-program"],
+    defaultTags: ["memory", "debug"],
+    workflowHints: [
+        "Pair memory operations with documentation snippets so addresses and symbols stay meaningful to the user.",
+        "Confirm intent before mutating RAM and explain how the change affects the running program.",
+    ],
+    tools: [
+        {
+            name: "read_screen",
+            description: "Read the current text screen (40x25) and return its ASCII representation. For PETSCII details, see c64://specs/basic.",
+            summary: "Fetches screen RAM, converts from PETSCII, and returns the printable output.",
+            inputSchema: readScreenArgsSchema.jsonSchema,
+            relatedResources: ["c64://context/bootstrap", "c64://specs/basic"],
+            relatedPrompts: ["memory-debug", "basic-program", "assembly-program"],
+            tags: ["screen", "memory"],
+            prerequisites: ["upload_and_run_basic"],
+            examples: [
+                {
+                    name: "Capture screen",
+                    description: "Read current 40x25 text",
+                    arguments: {},
+                },
+            ],
+            workflowHints: [
+                "Call after running a program when the user asks to see what is on screen; echo the captured text back to them.",
+            ],
+            async execute(args, ctx) {
+                try {
+                    readScreenArgsSchema.parse(args ?? {});
+                    ctx.logger.info("Reading C64 screen contents");
+                    const screen = await ctx.client.readScreen();
+                    return textResult(`Current screen contents:\n${screen}`, {
+                        success: true,
+                        screen,
+                        length: screen.length,
+                    });
+                }
+                catch (error) {
+                    if (error instanceof ToolError) {
+                        return toolErrorResult(error);
+                    }
+                    return unknownErrorResult(error);
+                }
+            },
+        },
+        {
+            name: "read_memory",
+            description: "Read a range of bytes from main memory and return the data as hexadecimal. Consult c64://specs/assembly and docs index.",
+            summary: "Resolves symbols, reads memory, and returns a hex dump with addressing metadata.",
+            inputSchema: readMemoryArgsSchema.jsonSchema,
+            relatedResources: ["c64://context/bootstrap", "c64://specs/assembly", "c64://docs/index"],
+            relatedPrompts: ["memory-debug", "assembly-program"],
+            tags: ["memory", "hex"],
+            prerequisites: ["pause"],
+            examples: [
+                {
+                    name: "Read screen memory",
+                    description: "Read 8 bytes at $0400",
+                    arguments: { address: "$0400", length: 8 },
+                },
+            ],
+            workflowHints: [
+                "Resolve symbol names before calling so you can explain the chosen address in the response.",
+                "Keep reads at or below 4096 bytes; split larger requests into multiple calls if needed.",
+            ],
+            async execute(args, ctx) {
+                try {
+                    const parsed = readMemoryArgsSchema.parse(args ?? {});
+                    ctx.logger.info("Reading C64 memory", { address: parsed.address, length: parsed.length });
+                    const result = await ctx.client.readMemory(parsed.address, String(parsed.length));
+                    if (!result.success) {
+                        throw new ToolExecutionError("C64 firmware reported failure while reading memory", {
+                            details: normaliseFailure(result.details),
+                        });
+                    }
+                    const detailRecord = toRecord(result.details) ?? {};
+                    const resolvedAddress = typeof detailRecord.address === "string" ? detailRecord.address : undefined;
+                    const resolvedLength = typeof detailRecord.length === "number" ? detailRecord.length : undefined;
+                    const addressLabel = resolvedAddress ? `$${resolvedAddress}` : parsed.address;
+                    const lengthLabel = resolvedLength ?? parsed.length;
+                    return textResult(`Read ${lengthLabel} bytes starting at ${addressLabel}.`, {
+                        success: true,
+                        address: addressLabel,
+                        length: lengthLabel,
+                        hexData: result.data ?? null,
+                        details: detailRecord,
+                    });
+                }
+                catch (error) {
+                    if (error instanceof ToolError) {
+                        return toolErrorResult(error);
+                    }
+                    return unknownErrorResult(error);
+                }
+            },
+        },
+        {
+            name: "write_memory",
+            description: "Write a hexadecimal byte sequence into main memory at the specified address. See c64://context/bootstrap for safety rules.",
+            summary: "Resolves symbols, validates hex data, and writes bytes to RAM via Ultimate firmware.",
+            inputSchema: writeMemoryArgsSchema.jsonSchema,
+            relatedResources: ["c64://context/bootstrap", "c64://specs/assembly", "c64://docs/index"],
+            relatedPrompts: ["memory-debug", "assembly-program"],
+            tags: ["memory", "hex", "write"],
+            prerequisites: ["pause", "read_memory"],
+            examples: [
+                {
+                    name: "Write to screen",
+                    description: "Write $AA55 at $0400",
+                    arguments: { address: "$0400", bytes: "$AA55" },
+                },
+            ],
+            workflowHints: [
+                "Double-check with the user before writing memory and describe the exact bytes you applied.",
+                "Consider reading the region first so they can compare before and after states.",
+            ],
+            async execute(args, ctx) {
+                try {
+                    const parsed = writeMemoryArgsSchema.parse(args ?? {});
+                    ctx.logger.info("Writing C64 memory", { address: parsed.address, bytesLength: parsed.bytes.length });
+                    const result = await ctx.client.writeMemory(parsed.address, parsed.bytes);
+                    if (!result.success) {
+                        throw new ToolExecutionError("C64 firmware reported failure while writing memory", {
+                            details: normaliseFailure(result.details),
+                        });
+                    }
+                    const detailRecord = toRecord(result.details) ?? {};
+                    let resolvedAddress;
+                    if (typeof detailRecord.address === "number") {
+                        resolvedAddress = `$${detailRecord.address.toString(16).toUpperCase().padStart(4, "0")}`;
+                    }
+                    else if (typeof detailRecord.address === "string" && detailRecord.address.length > 0) {
+                        resolvedAddress = detailRecord.address.startsWith("$")
+                            ? detailRecord.address
+                            : `$${detailRecord.address.toUpperCase()}`;
+                    }
+                    else {
+                        resolvedAddress = parsed.address.startsWith("$") ? parsed.address : `$${parsed.address}`;
+                    }
+                    const resolvedLength = typeof detailRecord.length === "number" ? detailRecord.length : undefined;
+                    return textResult(`Wrote ${resolvedLength ?? "the provided"} bytes starting at ${resolvedAddress}.`, {
+                        success: true,
+                        address: resolvedAddress,
+                        length: resolvedLength ?? null,
+                        bytes: parsed.bytes,
+                        details: detailRecord,
+                    });
+                }
+                catch (error) {
+                    if (error instanceof ToolError) {
+                        return toolErrorResult(error);
+                    }
+                    return unknownErrorResult(error);
+                }
+            },
+        },
+    ],
+});