c64bridge 0.9.2 → 1.0.0

package/dist/rag/knowledgeIndex.js

@@ -286,7 +286,14 @@ const KNOWLEDGE_BUNDLES = [
                 summary: "Page-by-page breakdown of the 64 KB address space with hardware, ROM, and RAM regions.",
                 prompts: ["memory-debug", "assembly-program"],
                 tools: ["read", "write", "verify_and_write_memory"],
-                relatedResources: [RESOURCE_URIS.assembly.spec6510],
+                relatedResources: [
+                    RESOURCE_URIS.memory.zeroPageAndWorkspace,
+                    RESOURCE_URIS.basic.romRoutines,
+                    RESOURCE_URIS.kernal.romRoutines,
+                    RESOURCE_URIS.io.spec,
+                    RESOURCE_URIS.io.cia.spec,
+                    RESOURCE_URIS.assembly.spec6510,
+                ],
                 tags: ["memory", "hardware"],
             },
             {
@@ -298,19 +305,48 @@ const KNOWLEDGE_BUNDLES = [
                 summary: "Documents zero-page variables, BASIC pointers, and KERNAL workspace addresses.",
                 prompts: ["memory-debug", "assembly-program"],
                 tools: ["read", "write", "verify_and_write_memory"],
-                relatedResources: [RESOURCE_URIS.memory.map, RESOURCE_URIS.assembly.spec6510],
+                relatedResources: [
+                    RESOURCE_URIS.memory.map,
+                    RESOURCE_URIS.basic.romRoutines,
+                    RESOURCE_URIS.kernal.romRoutines,
+                    RESOURCE_URIS.assembly.spec6510,
+                ],
                 tags: ["memory", "zero-page"],
             },
+            {
+                uri: RESOURCE_URIS.basic.romRoutines,
+                name: "BASIC ROM Routines Memory Map",
+                description: "Memory-map-style breakdown of BASIC ROM routines, tables, parser helpers, and entry points.",
+                relativePath: "data/basic/rom-routines.md",
+                priority: "reference",
+                summary: "Maps BASIC ROM landmarks, reusable interpreter routines, numeric helpers, string helpers, and C64-specific BASIC continuation entries.",
+                prompts: ["memory-debug", "assembly-program", "basic-program"],
+                tools: ["read", "verify_and_write_memory"],
+                relatedResources: [
+                    RESOURCE_URIS.memory.map,
+                    RESOURCE_URIS.memory.zeroPageAndWorkspace,
+                    RESOURCE_URIS.kernal.romRoutines,
+                    RESOURCE_URIS.basic.spec,
+                    RESOURCE_URIS.assembly.spec6510,
+                ],
+                tags: ["memory", "basic", "rom"],
+            },
             {
                 uri: RESOURCE_URIS.kernal.romRoutines,
-                name: "KERNAL Memory Map",
-                description: "Detailed breakdown of KERNAL ROM routines and entry points.",
-                relativePath: "data/memory/kernal-memory-map.md",
+                name: "KERNAL ROM Routines Memory Map",
+                description: "Memory-map-style breakdown of KERNAL ROM routines, vectors, tables, and entry points.",
+                relativePath: "data/kernal/rom-routines.md",
                 priority: "reference",
-                summary: "Lists KERNAL ROM vectors and service routines for OS-level functionality.",
+                summary: "Maps KERNAL ROM vectors, jump table entries, internal routines, serial/tape/screen services, and reset handlers.",
                 prompts: ["memory-debug", "assembly-program"],
                 tools: ["read", "verify_and_write_memory"],
-                relatedResources: [RESOURCE_URIS.memory.map, RESOURCE_URIS.assembly.spec6510],
+                relatedResources: [
+                    RESOURCE_URIS.memory.map,
+                    RESOURCE_URIS.memory.zeroPageAndWorkspace,
+                    RESOURCE_URIS.basic.romRoutines,
+                    RESOURCE_URIS.io.spec,
+                    RESOURCE_URIS.assembly.spec6510,
+                ],
                 tags: ["memory", "kernal"],
             },
             {
@@ -322,7 +358,12 @@ const KNOWLEDGE_BUNDLES = [
                 summary: "Covers VIC-II, SID, CIA, and system control registers with address ranges and usage notes.",
                 prompts: ["memory-debug", "assembly-program"],
                 tools: ["read", "write", "verify_and_write_memory", "debugreg_read", "debugreg_write"],
-                relatedResources: [RESOURCE_URIS.memory.map, RESOURCE_URIS.assembly.spec6510],
+                relatedResources: [
+                    RESOURCE_URIS.memory.map,
+                    RESOURCE_URIS.memory.zeroPageAndWorkspace,
+                    RESOURCE_URIS.io.cia.spec,
+                    RESOURCE_URIS.assembly.spec6510,
+                ],
                 tags: ["io", "hardware"],
             },
             {
@@ -334,7 +375,11 @@ const KNOWLEDGE_BUNDLES = [
                 summary: "Details CIA 1/2 registers, timers, interrupts, and keyboard matrix layout.",
                 prompts: ["memory-debug", "assembly-program"],
                 tools: ["read", "write", "verify_and_write_memory", "debugreg_read"],
-                relatedResources: [RESOURCE_URIS.io.spec, RESOURCE_URIS.memory.map],
+                relatedResources: [
+                    RESOURCE_URIS.io.spec,
+                    RESOURCE_URIS.memory.map,
+                    RESOURCE_URIS.memory.zeroPageAndWorkspace,
+                ],
                 tags: ["io", "hardware"],
             },
         ],

package/dist/rag/resourceUris.js

@@ -10,6 +10,7 @@ export const RESOURCE_URIS = {
     basic: {
         spec: "c64://basic/spec",
         pitfalls: "c64://basic/pitfalls",
+        romRoutines: "c64://basic/rom-routines",
     },
     assembly: {
         spec6510: "c64://assembly/6510-spec",
@@ -80,6 +81,7 @@ export const CANONICAL_KNOWLEDGE_RESOURCE_URIS = Object.freeze([
     RESOURCE_URIS.graphics.spriteCharset.bestPractices,
     RESOURCE_URIS.memory.map,
     RESOURCE_URIS.memory.zeroPageAndWorkspace,
+    RESOURCE_URIS.basic.romRoutines,
     RESOURCE_URIS.kernal.romRoutines,
     RESOURCE_URIS.io.spec,
     RESOURCE_URIS.io.cia.spec,

package/dist/tools/audio.js

@@ -403,7 +403,7 @@ export const audioModule = defineToolModule({
     ],
     prompts: ["sid-music"],
     defaultTags: ["sid", "audio"],
-    supportedPlatforms: ["c64u", "vice"],
+    supportedPlatforms: ["c64u", "u2", "vice"],
     workflowHints: [
         "Reach for SID helpers when the user talks about sound design, playback quality, or stuck notes.",
         "After changing playback state, suggest verify-by-ear steps such as analyze_audio so the user gets concrete feedback.",

package/dist/tools/developer.js

@@ -146,7 +146,7 @@ export const developerModule = defineToolModule({
             workflowHints: [
                 "Run first to enumerate categories before reading or writing specific settings; summarise the top-level sections for the user.",
             ],
-            supportedPlatforms: ["c64u", "vice"],
+            supportedPlatforms: ["c64u", "u2", "vice"],
             async execute(args, ctx) {
                 try {
                     noArgsSchema.parse(args ?? {});
@@ -182,7 +182,7 @@ export const developerModule = defineToolModule({
             workflowHints: [
                 "Use after config_list to fetch details; restate category/item so the user can cross-check values before changes.",
             ],
-            supportedPlatforms: ["c64u", "vice"],
+            supportedPlatforms: ["c64u", "u2", "vice"],
             async execute(args, ctx) {
                 try {
                     const parsed = configGetArgsSchema.parse(args ?? {});
@@ -218,7 +218,7 @@ export const developerModule = defineToolModule({
             workflowHints: [
                 "Confirm the user-supplied value before writing; mention whether a reboot is required for the change to take effect.",
             ],
-            supportedPlatforms: ["c64u", "vice"],
+            supportedPlatforms: ["c64u", "u2", "vice"],
             async execute(args, ctx) {
                 try {
                     const parsed = configSetArgsSchema.parse(args ?? {});
@@ -262,7 +262,7 @@ export const developerModule = defineToolModule({
             workflowHints: [
                 "Use when multiple categories must be updated together; remind the user to review validation errors closely.",
             ],
-            supportedPlatforms: ["c64u", "vice"],
+            supportedPlatforms: ["c64u", "u2", "vice"],
             async execute(args, ctx) {
                 try {
                     const payload = configBatchSchema.parse(args ?? {});
@@ -405,7 +405,7 @@ export const developerModule = defineToolModule({
             name: "version",
             description: "Retrieve firmware or emulator version information.",
             summary: "Calls the firmware version endpoint (Ultimate) or returns emulator info (VICE).",
-            supportedPlatforms: ["c64u", "vice"],
+            supportedPlatforms: ["c64u", "u2", "vice"],
             inputSchema: noArgsSchema.jsonSchema,
             relatedResources: ["c64://guide/bootstrap"],
             tags: ["diagnostics", "version"],
@@ -437,7 +437,7 @@ export const developerModule = defineToolModule({
             name: "info",
             description: "Retrieve hardware or emulator information and status.",
             summary: "Returns the diagnostics payload reported by the firmware (Ultimate) or emulator (VICE).",
-            supportedPlatforms: ["c64u", "vice"],
+            supportedPlatforms: ["c64u", "u2", "vice"],
             inputSchema: noArgsSchema.jsonSchema,
             relatedResources: ["c64://guide/bootstrap"],
             tags: ["diagnostics", "info"],

package/dist/tools/graphics.js

@@ -577,7 +577,7 @@ export const graphicsModule = defineToolModule({
                 "Use when the user supplies sprite bytes or asks to preview graphics quickly; describe resulting coordinates and colours.",
                 "Remind the user that sprites live in banked memory so further tweaks may require write_memory calls.",
             ],
-            supportedPlatforms: ["c64u", "vice"],
+            supportedPlatforms: ["c64u", "u2", "vice"],
             async execute(args, ctx) {
                 return executeGenerateSprite(args, ctx);
             },
@@ -594,7 +594,7 @@ export const graphicsModule = defineToolModule({
                 "Use when the user wants to display an external image on screen rather than generate PETSCII art.",
                 "Call out the selected bitmap and screen RAM addresses so follow-up memory inspection or raster work stays grounded.",
             ],
-            supportedPlatforms: ["c64u", "vice"],
+            supportedPlatforms: ["c64u", "u2", "vice"],
             async execute(args, ctx) {
                 return executeGenerateBitmap(args, ctx);
             },
@@ -619,7 +619,7 @@ export const graphicsModule = defineToolModule({
                 "Call after generating PETSCII text or when the user wants border/background colour changes applied.",
                 "Echo the colour indices and mention CLEAR + PRINT so the user knows what ran.",
             ],
-            supportedPlatforms: ["c64u", "vice"],
+            supportedPlatforms: ["c64u", "u2", "vice"],
             async execute(args, ctx) {
                 return executeRenderPetscii(args, ctx);
             },
@@ -645,7 +645,7 @@ export const graphicsModule = defineToolModule({
                 "Response includes petsciiCodes array and glyphs for character-level inspection.",
                 "Provide follow-up suggestions like saving the PRG or capturing the screen after rendering.",
             ],
-            supportedPlatforms: ["c64u", "vice"],
+            supportedPlatforms: ["c64u", "u2", "vice"],
             async execute(args, ctx) {
                 return executeCreatePetscii(args, ctx);
             },

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.",
     ],