c64bridge 0.9.3 → 1.0.0

package/dist/tools/input.js

@@ -1,7 +1,16 @@
 import { createOperationDispatcher, defineToolModule, discriminatedUnionSchema, } from "./types.js";
 import { arraySchema, literalSchema, numberSchema, objectSchema, optionalSchema, stringSchema, } from "./schema.js";
-import { textResult } from "./responses.js";
+import { jsonResult, textResult } from "./responses.js";
 import { ToolValidationError, toolErrorResult, unknownErrorResult, } from "./errors.js";
+function isMissingNativeInputEndpoint(error) {
+    return typeof error === "object"
+        && error !== null
+        && "response" in error
+        && error.response?.status === 404;
+}
+function nativeInputUnavailableResult(operation) {
+    return textResult(`Native physical input is unavailable on this firmware, so ${operation} was not sent. Use c64://platform/status before choosing native input; use key or write_text for ordinary C64 input.`, { success: false, code: "native_input_unavailable", fallback: "key_or_write_text" });
+}
 // ---------------------------------------------------------------------------
 // PETSCII token expansion table
 // Maps {TOKEN} placeholders to PETSCII/control-byte values that are queued via
@@ -96,6 +105,14 @@ const JOYSTICK_BIT = {
     right: 3,
     fire: 4,
 };
+const KEYBOARD_INPUTS = [
+    "inst_del", "return", "cursor_left_right", "f7", "f1", "f3", "f5", "cursor_up_down",
+    "0", "1", "2", "3", "4", "5", "6", "7", "8", "9",
+    "a", "b", "c", "d", "e", "f", "g", "h", "i", "j", "k", "l", "m", "n", "o", "p", "q", "r", "s", "t", "u", "v", "w", "x", "y", "z",
+    "left_shift", "right_shift", "plus", "minus", "period", "colon", "at", "comma", "pound", "star", "semicolon", "clr_home", "equals", "arrow_up", "slash", "arrow_left", "ctrl", "space", "commodore", "run_stop", "restore",
+];
+const JOYSTICK_INPUTS = ["up", "down", "left", "right", "fire", "fire2", "fire3"];
+const INPUT_TRANSITIONS = ["press", "release", "tap"];
 function joystickByte(controls) {
     let mask = 0xff;
     for (const ctrl of controls) {
@@ -157,7 +174,7 @@ export const keyArgsSchema = objectSchema({
     additionalProperties: false,
 });
 export const joystickArgsSchema = objectSchema({
-    description: "Simulate joystick input by writing directly to CIA1 Port A/B registers.",
+    description: "Simulate joystick input. On C64U/U64 this uses machine:input (a C64U firmware version that provides it, or U64 3.15+); VICE writes CIA1 registers.",
     properties: {
         op: literalSchema("joystick"),
         port: numberSchema({
@@ -168,7 +185,7 @@ export const joystickArgsSchema = objectSchema({
         }),
         controls: arraySchema(stringSchema({
             description: "Control to activate.",
-            enum: ["up", "down", "left", "right", "fire"],
+            enum: JOYSTICK_INPUTS,
         }), {
             description: "List of controls to activate simultaneously.",
             minItems: 0,
@@ -188,6 +205,32 @@ export const joystickArgsSchema = objectSchema({
     required: ["op", "port", "controls", "action"],
     additionalProperties: false,
 });
+export const keyboardArgsSchema = objectSchema({
+    description: "Send physical C64 keyboard matrix events through machine:input (a C64U firmware version that provides it, or U64 3.15+).",
+    properties: {
+        op: literalSchema("keyboard"),
+        inputs: arraySchema(stringSchema({ description: "Physical keyboard input.", enum: KEYBOARD_INPUTS }), {
+            description: "One or more keys to transition together (for example left_shift + a).",
+            minItems: 1,
+            maxItems: 8,
+        }),
+        transition: stringSchema({ description: "press holds, release frees, tap presses and releases.", enum: INPUT_TRANSITIONS }),
+    },
+    required: ["op", "inputs", "transition"],
+    additionalProperties: false,
+});
+const releaseAllArgsSchema = objectSchema({
+    description: "Release every key and joystick control injected through machine:input (a C64U firmware version that provides it, or U64 3.15+).",
+    properties: { op: literalSchema("release_all") },
+    required: ["op"],
+    additionalProperties: false,
+});
+const inputStateArgsSchema = objectSchema({
+    description: "Read the keys and joystick controls held through machine:input (a C64U firmware version that provides it, or U64 3.15+).",
+    properties: { op: literalSchema("state") },
+    required: ["op"],
+    additionalProperties: false,
+});
 // ---------------------------------------------------------------------------
 // Handlers
 // ---------------------------------------------------------------------------
@@ -250,10 +293,26 @@ const inputOperationHandlers = {
         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;
+            const platform = await ctx.client.getActiveBackendType();
+            if (platform === "c64u") {
+                if (parsed.controls.length === 0 && parsed.action === "release") {
+                    const state = await ctx.client.sendInputEvents({ events: [{ kind: "release_all" }] });
+                    return textResult("Released all REST-injected keyboard and joystick inputs.", { success: true, action: "release_all", state });
+                }
+                const state = await ctx.client.sendInputEvents({
+                    events: [{ kind: "joystick", port, inputs: [...parsed.controls], transition: parsed.action }],
+                });
+                return textResult(`Joystick port ${port} ${parsed.action}: ${parsed.controls.join(", ")}.`, {
+                    success: true, port, action: parsed.action, controls: parsed.controls, state,
+                });
+            }
+            const addr = JOYSTICK_PORT_ADDRESS[port];
+            if (parsed.controls.some((control) => !(control in JOYSTICK_BIT))) {
+                throw new ToolValidationError("VICE joystick supports up, down, left, right, and fire only.", { path: "$.controls" });
+            }
             if (parsed.action === "release") {
                 await ctx.client.viceMemSet(addr, Uint8Array.of(releasedByte));
                 ctx.logger.info("Released joystick", { port, address: `$${addr.toString(16).toUpperCase()}` });
@@ -274,6 +333,53 @@ const inputOperationHandlers = {
         catch (error) {
             if (error instanceof ToolValidationError)
                 return toolErrorResult(error);
+            if (isMissingNativeInputEndpoint(error))
+                return nativeInputUnavailableResult("the joystick event");
+            return unknownErrorResult(error);
+        }
+    },
+    keyboard: async (args, ctx) => {
+        try {
+            const parsed = keyboardArgsSchema.parse(args);
+            const state = await ctx.client.sendInputEvents({
+                events: [{ kind: "keyboard", inputs: [...parsed.inputs], transition: parsed.transition }],
+            });
+            return textResult(`Keyboard ${parsed.transition}: ${parsed.inputs.join(", ")}.`, {
+                success: true, inputs: parsed.inputs, transition: parsed.transition, state,
+            });
+        }
+        catch (error) {
+            if (error instanceof ToolValidationError)
+                return toolErrorResult(error);
+            if (isMissingNativeInputEndpoint(error))
+                return nativeInputUnavailableResult("the keyboard event");
+            return unknownErrorResult(error);
+        }
+    },
+    release_all: async (args, ctx) => {
+        try {
+            releaseAllArgsSchema.parse(args);
+            const state = await ctx.client.sendInputEvents({ events: [{ kind: "release_all" }] });
+            return textResult("Released all REST-injected keyboard and joystick inputs.", { success: true, state });
+        }
+        catch (error) {
+            if (error instanceof ToolValidationError)
+                return toolErrorResult(error);
+            if (isMissingNativeInputEndpoint(error))
+                return nativeInputUnavailableResult("the release request");
+            return unknownErrorResult(error);
+        }
+    },
+    state: async (args, ctx) => {
+        try {
+            inputStateArgsSchema.parse(args);
+            return jsonResult(await ctx.client.getInputState());
+        }
+        catch (error) {
+            if (error instanceof ToolValidationError)
+                return toolErrorResult(error);
+            if (isMissingNativeInputEndpoint(error))
+                return nativeInputUnavailableResult("the input-state query");
             return unknownErrorResult(error);
         }
     },
@@ -283,30 +389,36 @@ const inputOperationHandlers = {
 // ---------------------------------------------------------------------------
 export const inputModule = defineToolModule({
     domain: "input",
-    summary: "Cross-platform keyboard input plus VICE-only joystick simulation.",
-    supportedPlatforms: ["c64u", "vice"],
+    summary: "Keyboard input plus native Ultimate REST keyboard and joystick control.",
+    supportedPlatforms: ["c64u", "u2", "vice"],
     resources: ["c64://guide/bootstrap", "c64://memory/map", "c64://io/cia/spec"],
     prompts: [],
     defaultTags: ["input"],
     workflowHints: [
-        "Use write_text with {RETURN} tokens to automate BASIC entry; prefer key for individual control keys.",
+        "Use write_text with {RETURN} tokens to automate BASIC entry; use key for one PETSCII/KERNAL queue key. Neither is for navigating Ultimate firmware menus.",
         "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.",
+        "Use keyboard for physical C64 key combinations (including modifiers) on machine:input, and release_all to recover from interrupted holds. It requires a C64U firmware version that provides the endpoint, or U64 3.15+.",
+        "Before native input, read c64://platform/status. If machine:input is unavailable or unknown, use key or write_text for ordinary C64 input instead of attempting physical matrix events.",
+        "Change C64U/U64/U2 configuration through c64_config REST operations, never by keyboard menu navigation. Use keyboard navigation only where REST has no equivalent, such as the machine code monitor, visual SID editor, or Tool Menu.",
+        "Joystick uses machine:input on a C64U firmware version that provides the endpoint or U64 3.15+; VICE supports up/down/left/right/fire through its monitor.",
     ],
     tools: [
         {
             name: "c64_input",
-            description: "Keyboard buffer injection (cross-platform) and joystick simulation (VICE only).",
-            summary: "Types text, taps keys, and simulates joystick movements.",
+            description: "Cross-platform PETSCII typing plus native Ultimate keyboard and joystick events.",
+            summary: "Types text, sends physical key combinations, and controls joysticks.",
             inputSchema: discriminatedUnionSchema({
-                description: "Input operations: write_text, key, joystick.",
+                description: "Input operations: write_text, key, keyboard, joystick, release_all, state.",
                 variants: [
                     writeTextArgsSchema.jsonSchema,
                     keyArgsSchema.jsonSchema,
                     joystickArgsSchema.jsonSchema,
+                    keyboardArgsSchema.jsonSchema,
+                    releaseAllArgsSchema.jsonSchema,
+                    inputStateArgsSchema.jsonSchema,
                 ],
             }),
-            operationPlatforms: { joystick: ["vice"] },
+            operationPlatforms: { joystick: ["c64u", "vice"], keyboard: ["c64u"], release_all: ["c64u"], state: ["c64u"] },
             tags: ["input", "keyboard", "joystick"],
             examples: [
                 {
@@ -324,6 +436,11 @@ export const inputModule = defineToolModule({
                     description: "Brief rightward tap on joystick port 2",
                     arguments: { op: "joystick", port: 2, controls: ["right"], action: "tap", durationMs: 80 },
                 },
+                {
+                    name: "Type an uppercase A",
+                    description: "Tap a physical key chord through Ultimate REST input",
+                    arguments: { op: "keyboard", inputs: ["left_shift", "a"], transition: "tap" },
+                },
                 {
                     name: "Press fire on port 1",
                     description: "Hold fire button on joystick port 1",

package/dist/tools/machineControl.js

@@ -1,6 +1,7 @@
 import { defineToolModule } from "./types.js";
 import { objectSchema } from "./schema.js";
-import { textResult } from "./responses.js";
+import { jsonResult, textResult } from "./responses.js";
+import { Buffer } from "node:buffer";
 import { ToolError, ToolExecutionError, toolErrorResult, unknownErrorResult, } from "./errors.js";
 function createNoArgsSchema(description) {
     return objectSchema({
@@ -24,12 +25,20 @@ function normaliseFailure(details) {
     }
     return { value: details };
 }
+function isMissingMenuScreenEndpoint(error) {
+    return typeof error === "object"
+        && error !== null
+        && "response" in error
+        && error.response?.status === 404;
+}
 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.");
 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 powerCycleArgsSchema = createNoArgsSchema("No arguments required to power cycle the active system.");
 const menuButtonArgsSchema = createNoArgsSchema("No arguments required to toggle the Ultimate menu button.");
+const readMenuScreenArgsSchema = createNoArgsSchema("No arguments required to read the active Ultimate menu screen matrix.");
 export const machineControlModule = defineToolModule({
     domain: "machine",
     summary: "Power, reset, pause/resume, and diagnostic controls for the C64 and Ultimate hardware.",
@@ -54,7 +63,7 @@ export const machineControlModule = defineToolModule({
             workflowHints: [
                 "Use when the user wants a quick restart without losing power; mention that memory contents may persist.",
             ],
-            supportedPlatforms: ["c64u", "vice"],
+            supportedPlatforms: ["c64u", "u2", "vice"],
             async execute(args, ctx) {
                 try {
                     resetArgsSchema.parse(args ?? {});
@@ -92,7 +101,7 @@ export const machineControlModule = defineToolModule({
             workflowHints: [
                 "Choose reboot when configuration changed or hardware is stuck; warn that it will interrupt any running program.",
             ],
-            supportedPlatforms: ["c64u", "vice"],
+            supportedPlatforms: ["c64u", "u2", "vice"],
             async execute(args, ctx) {
                 try {
                     rebootArgsSchema.parse(args ?? {});
@@ -130,7 +139,7 @@ export const machineControlModule = defineToolModule({
             workflowHints: [
                 "Pause when the user needs a stable memory snapshot; remind them to resume to continue execution.",
             ],
-            supportedPlatforms: ["c64u"],
+            supportedPlatforms: ["c64u", "u2"],
             async execute(args, ctx) {
                 try {
                     pauseArgsSchema.parse(args ?? {});
@@ -168,7 +177,7 @@ export const machineControlModule = defineToolModule({
             workflowHints: [
                 "Call after a pause or diagnostic halt and confirm the machine is running again.",
             ],
-            supportedPlatforms: ["c64u"],
+            supportedPlatforms: ["c64u", "u2"],
             async execute(args, ctx) {
                 try {
                     resumeArgsSchema.parse(args ?? {});
@@ -231,6 +240,41 @@ export const machineControlModule = defineToolModule({
                 }
             },
         },
+        {
+            name: "power_cycle",
+            description: "Return the active system to a fresh state: C64U/U64 uses verified Tool Menu navigation, U2-family reboots through REST, and managed VICE restarts.",
+            summary: "Performs the platform-appropriate full power-cycle equivalent and reports the strategy used.",
+            inputSchema: powerCycleArgsSchema.jsonSchema,
+            tags: ["power", "reboot", "fresh-start"],
+            prerequisites: [],
+            examples: [
+                { name: "Fresh start", description: "Power cycle the active system", arguments: {} },
+            ],
+            workflowHints: [
+                "Use only when the user explicitly requests a fresh start or power cycle; it interrupts active work.",
+                "On C64U/U64, verify Tool Menu navigation through machine:menu_screen before selecting Power Cycle.",
+            ],
+            supportedPlatforms: ["c64u", "u2", "vice"],
+            async execute(args, ctx) {
+                try {
+                    powerCycleArgsSchema.parse(args ?? {});
+                    ctx.logger.info("Power cycling active backend");
+                    const result = await ctx.client.powerCycle();
+                    if (!result.success) {
+                        throw new ToolExecutionError("Power cycle did not complete", {
+                            details: normaliseFailure(result.details),
+                        });
+                    }
+                    const details = toRecord(result.details) ?? {};
+                    return textResult("Power-cycle request completed.", { 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.",
@@ -244,7 +288,7 @@ export const machineControlModule = defineToolModule({
             workflowHints: [
                 "Use when the user needs to open or close the Ultimate menu; suggest following up with drive operations if relevant.",
             ],
-            supportedPlatforms: ["c64u"],
+            supportedPlatforms: ["c64u", "u2"],
             async execute(args, ctx) {
                 try {
                     menuButtonArgsSchema.parse(args ?? {});
@@ -269,5 +313,40 @@ export const machineControlModule = defineToolModule({
                 }
             },
         },
+        {
+            name: "read_menu_screen",
+            description: "Read the raw character and colour matrix for the currently visible Ultimate menu screen.",
+            summary: "Returns the firmware-defined menu matrix bytes, including text and colour information.",
+            inputSchema: readMenuScreenArgsSchema.jsonSchema,
+            tags: ["menu", "screen", "diagnostic"],
+            prerequisites: ["menu_button"],
+            examples: [
+                { name: "Inspect active menu", description: "Read the currently visible Ultimate menu", arguments: {} },
+            ],
+            workflowHints: [
+                "Read c64://platform/status first. Call after opening the Ultimate menu; if the endpoint is unavailable or no menu is active, the tool returns fallback guidance instead of a transport error.",
+                "The firmware returns an opaque character-and-colour matrix, preserved as base64 without guessing a layout.",
+            ],
+            supportedPlatforms: ["c64u", "u2"],
+            async execute(args, ctx) {
+                try {
+                    readMenuScreenArgsSchema.parse(args ?? {});
+                    const bytes = await ctx.client.readMenuScreen();
+                    return jsonResult({
+                        encoding: "base64",
+                        byteLength: bytes.length,
+                        matrix: Buffer.from(bytes).toString("base64"),
+                    });
+                }
+                catch (error) {
+                    if (error instanceof ToolError)
+                        return toolErrorResult(error);
+                    if (isMissingMenuScreenEndpoint(error)) {
+                        return textResult("No menu matrix is available. Open the Ultimate menu and retry; if it remains unavailable, this firmware does not provide machine:menu_screen. Use REST configuration instead of menu navigation where possible.", { success: false, code: "native_menu_screen_unavailable", fallback: "rest_configuration_or_manual_menu" });
+                    }
+                    return unknownErrorResult(error);
+                }
+            },
+        },
     ],
 });

package/dist/tools/memory.js

@@ -685,7 +685,7 @@ export { disassembleArgsSchema, copyMemoryArgsSchema, fillMemoryArgsSchema, sear
 export const memoryModule = defineToolModule({
     domain: "memory",
     summary: "Screen, main memory, and low-level inspection utilities.",
-    supportedPlatforms: ["c64u", "vice"],
+    supportedPlatforms: ["c64u", "u2", "vice"],
     resources: [
         "c64://guide/bootstrap",
         "c64://basic/spec",

package/dist/tools/meta/index.js

@@ -30,7 +30,7 @@ export const metaModule = defineToolModule({
     summary: "High-level meta tools that orchestrate multiple MCP actions.",
     resources: ["c64://guide/bootstrap", "c64://assembly/6510-spec"],
     defaultTags: ["meta", "orchestration", "experimental"],
-    supportedPlatforms: ["c64u", "vice"],
+    supportedPlatforms: ["c64u", "u2", "vice"],
     workflowHints: [
         "Use meta tools to reduce round-trips by composing several steps into one.",
     ],

package/dist/tools/programRunners.js

@@ -668,7 +668,7 @@ export const programRunnersModule = defineToolModule({
                 "Invoke right after you generate BASIC source so it runs on the C64 without extra user steps.",
                 "Ensure the program includes line numbers and uppercase keywords before calling the tool.",
             ],
-            supportedPlatforms: ["c64u", "vice"],
+            supportedPlatforms: ["c64u", "u2", "vice"],
             async execute(args, ctx) {
                 return executeUploadRunBasic(args, ctx);
             },
@@ -693,7 +693,7 @@ export const programRunnersModule = defineToolModule({
                 "Use when the user requests to run new 6502 code; surface any assembler diagnostics in your reply.",
                 "Mention the entry routine or important addresses after execution so the user can continue debugging.",
             ],
-            supportedPlatforms: ["c64u", "vice"],
+            supportedPlatforms: ["c64u", "u2", "vice"],
             async execute(args, ctx) {
                 return executeUploadRunAsm(args, ctx);
             },
@@ -717,7 +717,7 @@ export const programRunnersModule = defineToolModule({
                 "Stage PRG files without running when the user wants to inspect memory first.",
                 "Confirm the Ultimate filesystem path (e.g. //USB0/demo.prg) is accessible before invoking.",
             ],
-            supportedPlatforms: ["c64u"],
+            supportedPlatforms: ["c64u", "u2"],
             async execute(args, ctx) {
                 return executeLoadPrg(args, ctx);
             },
@@ -733,7 +733,7 @@ export const programRunnersModule = defineToolModule({
                 "Call when the user provides a PRG path and expects immediate execution without compiling.",
                 "Mention that firmware issues a RUN so the user knows the machine state changed.",
             ],
-            supportedPlatforms: ["c64u", "vice"],
+            supportedPlatforms: ["c64u", "u2", "vice"],
             prerequisites: ["drives_list"],
             examples: [
                 {
@@ -765,7 +765,7 @@ export const programRunnersModule = defineToolModule({
                     arguments: { path: "//USB0/game.crt" },
                 },
             ],
-            supportedPlatforms: ["c64u"],
+            supportedPlatforms: ["c64u", "u2"],
             async execute(args, ctx) {
                 try {
                     const parsed = crtFileArgsSchema.parse(args ?? {});

package/dist/tools/rag.js

@@ -181,7 +181,7 @@ export const ragModule = defineToolModule({
     ],
     prompts: ["basic-program", "assembly-program"],
     defaultTags: ["rag", "search"],
-    supportedPlatforms: ["c64u", "vice"],
+    supportedPlatforms: ["c64u", "u2", "vice"],
     workflowHints: [
         "Call RAG tools when the user needs references or examples before generating new code.",
         "Summarise the number of refs returned and suggest follow-up actions like reading specific docs.",

package/dist/tools/registry/batch.js

@@ -35,7 +35,7 @@ const executeBatchArgsSchema = objectSchema({
 export const batchModuleGroup = defineToolModule({
     domain: "batch",
     summary: "Execute multiple tool calls in a single MCP request for reduced round-trip overhead.",
-    supportedPlatforms: ["c64u", "vice"],
+    supportedPlatforms: ["c64u", "u2", "vice"],
     resources: [],
     prompts: [],
     defaultTags: ["batch", "orchestration"],

package/dist/tools/registry/config.js

@@ -154,7 +154,7 @@ export const configModuleGroup = defineToolModule({
     resources: ["c64://guide/bootstrap", "c64://guide/index"],
     prompts: ["memory-debug"],
     defaultTags: ["config", "diagnostics"],
-    supportedPlatforms: ["c64u", "vice"],
+    supportedPlatforms: ["c64u", "u2", "vice"],
     workflowHints: [
         "List categories before changing values so users can confirm firmware-provided names.",
         "Mention when operations persist to flash or modify debug registers to highlight impacts.",
@@ -171,12 +171,12 @@ export const configModuleGroup = defineToolModule({
             }),
             tags: ["config", "diagnostics", "grouped"],
             operationPlatforms: {
-                load_flash: ["c64u"],
-                save_flash: ["c64u"],
-                reset_defaults: ["c64u"],
+                load_flash: ["c64u", "u2"],
+                save_flash: ["c64u", "u2"],
+                reset_defaults: ["c64u", "u2"],
                 read_debugreg: ["c64u"],
                 write_debugreg: ["c64u"],
-                shuffle: ["c64u"],
+                shuffle: ["c64u", "u2"],
             },
             operationToolNames: {
                 load_flash: "config_load_from_flash",

package/dist/tools/registry/disk.js

@@ -251,7 +251,7 @@ const diskOperationHandlers = createOperationHandlers(diskOperations);
 export const diskModuleGroup = defineToolModule({
     domain: "storage",
     summary: "Grouped disk image management, mounting, and discovery tools.",
-    supportedPlatforms: ["c64u", "vice"],
+    supportedPlatforms: ["c64u", "u2", "vice"],
     resources: ["c64://guide/bootstrap"],
     prompts: ["drive-management"],
     defaultTags: ["storage", "drive"],
@@ -269,7 +269,7 @@ export const diskModuleGroup = defineToolModule({
                 variants: diskOperations.map((operation) => operation.schema),
             }),
             tags: ["storage", "drive", "grouped"],
-            operationPlatforms: { file_info: ["c64u"], create_image: ["c64u"], find_and_run: ["c64u"] },
+            operationPlatforms: { file_info: ["c64u", "u2"], create_image: ["c64u", "u2"], find_and_run: ["c64u", "u2"] },
             operationToolNames: {
                 file_info: "file_info",
                 create_image: "create_image",

package/dist/tools/registry/drive.js

@@ -33,7 +33,7 @@ const driveOperationHandlers = createOperationHandlers(driveOperations);
 export const driveModuleGroup = defineToolModule({
     domain: "drive",
     summary: "Grouped drive power, reset, ROM, and mode helpers.",
-    supportedPlatforms: ["c64u", "vice"],
+    supportedPlatforms: ["c64u", "u2", "vice"],
     resources: ["c64://guide/bootstrap"],
     defaultTags: ["drive", "hardware"],
     workflowHints: [
@@ -50,7 +50,7 @@ export const driveModuleGroup = defineToolModule({
                 variants: driveOperations.map((operation) => operation.schema),
             }),
             tags: ["drive", "hardware", "grouped"],
-            operationPlatforms: { load_rom: ["c64u"] },
+            operationPlatforms: { load_rom: ["c64u", "u2"] },
             operationToolNames: { load_rom: "drive_load_rom" },
             examples: [
                 {

package/dist/tools/registry/graphics.js

@@ -89,7 +89,7 @@ function parseVicState(d011, d016, d018, dd00, d020, d021) {
     };
 }
 const getDisplayStateArgsSchema = objectSchema({
-    description: "Read VIC-II and CIA2 registers to determine the current graphics mode and memory layout. Works on C64U and VICE; both backends are read through shared memory primitives so the response shape is identical.",
+    description: "Read VIC-II and CIA2 registers to determine the current graphics mode and memory layout. The same shared-memory path is used on C64U/U64, U2-family hardware, and VICE, so the response shape is identical.",
     properties: {
         op: literalSchema("get_display_state"),
     },
@@ -212,7 +212,7 @@ export const graphicsModuleGroup = defineToolModule({
         "Use render helpers for PETSCII text, PETSCII art, sprites, and bitmaps; clarify whether PETSCII art executed or stayed a dry run.",
         "Mention sprite positions/colours so follow-up memory inspection stays grounded.",
     ],
-    supportedPlatforms: ["c64u", "vice"],
+    supportedPlatforms: ["c64u", "u2", "vice"],
     tools: [
         {
             name: "c64_graphics",

package/dist/tools/registry/memory.js

@@ -27,7 +27,7 @@ const memoryOperations = [
     },
     {
         op: "disassemble",
-        schema: extendSchemaWithOp("disassemble", disassembleArgsSchema.jsonSchema, { description: "Disassemble a memory region into annotated 6502/6510 instructions, including undocumented opcodes with canonical names. Symbol annotations from `.vs` files are applied when available. Works on both C64U and VICE." }),
+        schema: extendSchemaWithOp("disassemble", disassembleArgsSchema.jsonSchema, { description: "Disassemble a memory region into annotated 6502/6510 instructions, including undocumented opcodes with canonical names. Symbol annotations from `.vs` files are applied when available. Works on C64U/U64, U2-family hardware, and VICE." }),
         handler: groupedMemoryHandlers.disassemble,
     },
     {
@@ -60,7 +60,7 @@ const memoryOperationHandlers = createOperationHandlers(memoryOperations);
 export const memoryModuleGroup = defineToolModule({
     domain: "memory",
     summary: "Grouped memory, screen, and polling operations.",
-    supportedPlatforms: ["c64u", "vice"],
+    supportedPlatforms: ["c64u", "u2", "vice"],
     resources: ["c64://guide/bootstrap", "c64://basic/spec", "c64://assembly/6510-spec"],
     prompts: ["memory-debug", "basic-program", "assembly-program"],
     defaultTags: ["memory", "debug"],

package/dist/tools/registry/platform.js

@@ -50,7 +50,7 @@ const selectBackendSchema = operationSchema("select", {
     properties: {
         backend: {
             type: "string",
-            enum: ["c64u", "vice"],
+            enum: ["c64u", "u2", "vice"],
             description: "Backend to activate for subsequent tool calls.",
         },
     },
@@ -76,14 +76,16 @@ const platformOperationHandlers = {
         ctx.client.switchBackend(backend);
         ctx.setPlatform(backend);
         const { availableTools, unavailableTools } = describeTargetPlatform(backend);
-        const switchBackTarget = backend === "c64u" ? "vice" : "c64u";
+        const switchBackTarget = availableBackends.find((candidate) => candidate !== backend);
         const data = {
             success: true,
             activeBackend: backend,
             configuredBackends: availableBackends,
             availableTools,
             unavailableTools,
-            usageHint: `Use c64_select_backend again with backend: "${switchBackTarget}" to switch back.`,
+            usageHint: switchBackTarget
+                ? `Use c64_select_backend again with backend: "${switchBackTarget}" to switch back.`
+                : "No other backend is configured.",
         };
         return jsonResult(data, { success: true });
     },
@@ -91,7 +93,7 @@ const platformOperationHandlers = {
 export const platformModuleGroup = defineToolModule({
     domain: "platform",
     summary: "Runtime backend selection and platform-status coordination.",
-    supportedPlatforms: ["c64u", "vice"],
+    supportedPlatforms: ["c64u", "u2", "vice"],
     resources: ["c64://platform/status", "c64://guide/bootstrap"],
     prompts: [],
     defaultTags: ["platform", "backend", "grouped"],
@@ -101,7 +103,7 @@ export const platformModuleGroup = defineToolModule({
     tools: [
         {
             name: "c64_select_backend",
-            description: "Switch the active backend between C64U hardware and the VICE emulator at runtime.",
+            description: "Switch the active backend between C64U/U64 hardware, U2-family cartridges, and the VICE emulator at runtime.",
             summary: "Changes the active backend without restarting the MCP server and reports resulting tool availability.",
             inputSchema: discriminatedUnionSchema({
                 description: "Runtime backend selection operations.",

package/dist/tools/registry/program.js

@@ -12,7 +12,7 @@ const programOperations = [
     },
     {
         op: "run_prg",
-        schema: extendSchemaWithOp("run_prg", ensureDescriptor(programDescriptorIndex, "run_prg").inputSchema, { description: "Load and execute a PRG from Ultimate-visible storage on c64u or a host-local path on VICE." }),
+        schema: extendSchemaWithOp("run_prg", ensureDescriptor(programDescriptorIndex, "run_prg").inputSchema, { description: "Load and execute a PRG from Ultimate-visible storage on C64U/U64 or U2-family hardware, or from a host-local path on VICE." }),
         handler: async (rawArgs, ctx) => invokeModuleTool(programRunnersModule, "run_prg", rawArgs, ctx),
     },
     {
@@ -55,10 +55,10 @@ export const programModule = defineToolModule({
     defaultTags: ["programs", "execution"],
     workflowHints: [
         "Choose BASIC or assembly uploaders based on the language you just generated for the user.",
-        "Prefer PRG or CRT runners when the user supplies a file path instead of source text; PRG paths are host-local on VICE and Ultimate-visible on c64u.",
-        "For a quick visible confirmation on VICE and/or C64U, prefer cross_platform_greeting instead of composing manual backend switches and BASIC upload steps.",
+        "Prefer PRG or CRT runners when the user supplies a file path instead of source text; PRG paths are host-local on VICE and Ultimate-visible on hardware.",
+        "For a quick visible confirmation on VICE, C64U/U64, or U2-family hardware, prefer cross_platform_greeting instead of composing manual backend switches and BASIC upload steps.",
     ],
-    supportedPlatforms: ["c64u", "vice"],
+    supportedPlatforms: ["c64u", "u2", "vice"],
     tools: [
         {
             name: "c64_program",
@@ -69,7 +69,7 @@ export const programModule = defineToolModule({
                 variants: programOperations.map((operation) => operation.schema),
             }),
             tags: ["programs", "execution", "grouped"],
-            operationPlatforms: { load_prg: ["c64u"], run_crt: ["c64u"], bundle_run: ["c64u"] },
+            operationPlatforms: { load_prg: ["c64u", "u2"], run_crt: ["c64u", "u2"], bundle_run: ["c64u", "u2"] },
             operationToolNames: {
                 load_prg: "load_prg",
                 run_crt: "run_crt",