c64bridge 0.9.3 → 1.0.0

package/dist/c64Client.js

@@ -10,14 +10,26 @@ import { createSocket } from "node:dgram";
 import axios from "axios";
 import { basicToPrg } from "./tools/translation/basicTokenizer.js";
 import { assemblyToPrg } from "./tools/translation/assembler.js";
-import { screenCodesToAscii } from "./petscii.js";
+import { petsciiToAscii, screenCodesToAscii } from "./petscii.js";
 import { resolveAddressSymbol } from "./knowledge.js";
-import { createAllFacades, createFacade } from "./device.js";
+import { createAllFacades, createFacade, } from "./device.js";
 import { Api } from "../generated/c64/index.js";
 import { createLoggingHttpClient } from "./loggingHttpClient.js";
 import { withDiagnosticSpan, writeDiagnosticEvent } from "./diagnostics.js";
 import { C64U_NTSC_AUDIO_SAMPLE_RATE, C64U_PAL_AUDIO_SAMPLE_RATE, collectCompleteVideoFrames, parseAudioPacket, parseVideoPacket, } from "./streamCapture.js";
 import { buildVicBitmapRegisters, resolveVicBitmapMemoryLayout, } from "./vicBitmap.js";
+function menuMatrixIncludes(matrix, expected) {
+    // Firmware supplies the character matrix followed by its colour matrix. The
+    // documented wire format is raw bytes, so only inspect the first 40×25
+    // character cells when that complete layout is present.
+    const characters = matrix.length >= 2000 ? matrix.subarray(0, 1000) : matrix;
+    const normalizedExpected = expected.replace(/\s+/g, " ").toUpperCase();
+    return [screenCodesToAscii(characters), petsciiToAscii(characters)]
+        .some((text) => text.replace(/\s+/g, " ").toUpperCase().includes(normalizedExpected));
+}
+function isMissingEndpoint(error) {
+    return axios.isAxiosError(error) && error.response?.status === 404;
+}
 const TEXT_SCREEN_COLUMNS = 40;
 const TEXT_SCREEN_ROWS = 25;
 const TEXT_SCREEN_SIZE = TEXT_SCREEN_COLUMNS * TEXT_SCREEN_ROWS;
@@ -45,6 +57,7 @@ export class C64Client {
         this.warmupPromises = new Map();
         this.greetingDd00Cache = new Map();
         this.greetingDd00Warmups = new Map();
+        this.machineInputCapabilityProbes = new Map();
         this.c64uVideoCaptureSession = null;
         this.activeType = "c64u";
         this.baseUrl = baseUrl;
@@ -66,13 +79,15 @@ export class C64Client {
             preferredC64uNetworkPassword: options.networkPassword,
         });
         this.facadePromise = allFacadesPromise.then(({ primary }) => primary.facade);
-        this.initPromise = allFacadesPromise.then(({ primary, secondary, secondaryType }) => {
+        this.initPromise = allFacadesPromise.then(({ primary, facades }) => {
             const primaryPromise = Promise.resolve(primary.facade);
             this.activeType = primary.selected;
             this.facadePromise = primaryPromise;
             this.allFacades.set(primary.selected, primaryPromise);
-            if (secondary && secondaryType) {
-                this.allFacades.set(secondaryType, Promise.resolve(secondary));
+            for (const [type, facade] of facades) {
+                if (type !== primary.selected) {
+                    this.allFacades.set(type, Promise.resolve(facade));
+                }
             }
         });
     }
@@ -90,6 +105,28 @@ export class C64Client {
         await this.initPromise;
         return this.activeType;
     }
+    /**
+     * Discover native endpoint availability without changing machine state.
+     * `machine:input` has a safe GET probe; `machine:menu_screen` is only
+     * distinguishable from an inactive menu once a menu is visible.
+     */
+    async getNativeEndpointCapabilities() {
+        const facade = await this.facadePromise;
+        if (facade.type === "vice") {
+            return { machineInput: "unavailable", machineMenuScreen: "unavailable" };
+        }
+        if (facade.type === "u2") {
+            return { machineInput: "unavailable", machineMenuScreen: "unknown" };
+        }
+        let probe = this.machineInputCapabilityProbes.get(facade.type);
+        if (!probe) {
+            probe = facade.getInputState()
+                .then(() => "available")
+                .catch((error) => isMissingEndpoint(error) ? "unavailable" : "unknown");
+            this.machineInputCapabilityProbes.set(facade.type, probe);
+        }
+        return { machineInput: await probe, machineMenuScreen: "unknown" };
+    }
     getAvailableBackends() {
         return Array.from(this.allFacades.keys());
     }
@@ -685,6 +722,79 @@ export class C64Client {
             return { success: false, details: this.normaliseError(error) };
         }
     }
+    /**
+     * Start from a clean machine state. C64U/U64 firmware exposes this only in
+     * the Tool Menu; U2-family firmware uses its equivalent REST reboot and
+     * VICE is restarted when it is managed by c64bridge.
+     */
+    async powerCycle() {
+        try {
+            const facade = await this.facadePromise;
+            if (facade.type === "u2") {
+                const result = await facade.reboot();
+                return { ...result, details: { strategy: "reboot", result: result.details } };
+            }
+            if (facade.type === "vice") {
+                const result = await facade.powerCycle();
+                return { ...result, details: { strategy: "fresh_start", result: result.details } };
+            }
+            const endpoints = await this.getNativeEndpointCapabilities();
+            if (endpoints.machineInput !== "available") {
+                return {
+                    success: false,
+                    details: {
+                        code: "native_input_unavailable",
+                        message: "C64U/U64 Power Cycle requires machine:input and machine:menu_screen, which this firmware does not currently expose.",
+                        fallback: "Use c64_system reboot if a firmware reboot is acceptable, or power cycle from the device itself.",
+                    },
+                };
+            }
+            const menuResult = await facade.menuButton();
+            if (!menuResult.success) {
+                throw new Error("Unable to open the Ultimate menu for power cycling");
+            }
+            const initial = await this.readVerifiedMenuScreen(facade, "open Ultimate menu");
+            await this.requirePowerCycleInput(facade, ["f1"]);
+            await this.readVerifiedMenuScreen(facade, "open Tool Menu", "TOOL MENU", initial);
+            await this.requirePowerCycleInput(facade, ["return"]);
+            let current = await this.readVerifiedMenuScreen(facade, "enter Tool Menu", "POWER CYCLE");
+            for (let index = 0; index < 4; index += 1) {
+                await this.requirePowerCycleInput(facade, ["cursor_up_down"]);
+                current = await this.readVerifiedMenuScreen(facade, `move to Power Cycle (${index + 1}/4)`, "POWER CYCLE", current);
+            }
+            await this.requirePowerCycleInput(facade, ["return"]);
+            return { success: true, details: { strategy: "tool_menu", verifiedMenu: "Tool Menu", selectedItem: "Power Cycle" } };
+        }
+        catch (error) {
+            if (isMissingEndpoint(error)) {
+                return {
+                    success: false,
+                    details: {
+                        code: "native_menu_screen_unavailable",
+                        message: "C64U/U64 Power Cycle could not verify Tool Menu navigation because machine:menu_screen is unavailable.",
+                        fallback: "Use c64_system reboot if a firmware reboot is acceptable, or power cycle from the device itself.",
+                    },
+                };
+            }
+            return { success: false, details: this.normaliseError(error) };
+        }
+    }
+    async requirePowerCycleInput(facade, inputs) {
+        await facade.sendInputEvents({ events: [{ kind: "keyboard", inputs, transition: "tap" }] });
+    }
+    async readVerifiedMenuScreen(facade, phase, requiredText, previous) {
+        const matrix = await facade.readMenuScreen();
+        if (matrix.length === 0) {
+            throw new Error(`Unable to ${phase}: machine:menu_screen returned an empty matrix`);
+        }
+        if (previous && Buffer.compare(Buffer.from(previous), Buffer.from(matrix)) === 0) {
+            throw new Error(`Unable to ${phase}: machine:menu_screen did not change after menu input`);
+        }
+        if (requiredText && !menuMatrixIncludes(matrix, requiredText)) {
+            throw new Error(`Unable to ${phase}: machine:menu_screen did not contain '${requiredText}'`);
+        }
+        return matrix;
+    }
     async menuButton() {
         try {
             if (await this.shouldUseC64uMockBypass()) {
@@ -698,6 +808,18 @@ export class C64Client {
             return { success: false, details: this.normaliseError(error) };
         }
     }
+    async readMenuScreen() {
+        const facade = await this.facadePromise;
+        return facade.readMenuScreen();
+    }
+    async getInputState() {
+        const facade = await this.facadePromise;
+        return facade.getInputState();
+    }
+    async sendInputEvents(batch) {
+        const facade = await this.facadePromise;
+        return facade.sendInputEvents(batch);
+    }
     async debugregRead() {
         try {
             if (await this.shouldUseC64uMockBypass()) {

package/dist/config.js

@@ -34,16 +34,20 @@ export function loadConfig() {
         }
     }
     rawConfig ?? (rawConfig = {});
-    // New schema: prefer c64u.{host,port,baseUrl}; keep legacy fields as fallback
+    // New schema: choose the configured Ultimate hardware profile; retain
+    // c64u and legacy fields as the default when C64_MODE is not set to u2.
     const c64u = rawConfig?.c64u;
+    const u2 = rawConfig?.u2;
+    const useU2 = process.env.C64_MODE?.trim().toLowerCase() === "u2";
+    const hardware = useU2 ? (u2 ?? c64u) : (c64u ?? u2);
     const vice = rawConfig?.vice;
-    const parsedC64uHost = parseEndpoint(configuredString(c64u?.host));
-    const parsedC64uHostname = parseEndpoint(configuredString(c64u?.hostname));
+    const parsedC64uHost = parseEndpoint(configuredString(hardware?.host));
+    const parsedC64uHostname = parseEndpoint(configuredString(hardware?.hostname));
     const parsedLegacyHost = parseEndpoint(configuredString(rawConfig?.c64_host));
     const parsedLegacyIp = parseEndpoint(configuredString(rawConfig?.c64_ip));
-    const parsedEnvHost = parseEndpoint(configuredString(process.env.C64U_HOST));
+    const parsedEnvHost = parseEndpoint(configuredString(useU2 ? process.env.U2_HOST ?? process.env.C64U_HOST : process.env.C64U_HOST));
     const parsedBaseOverrides = [
-        parseEndpoint(normaliseBaseUrl(c64u?.baseUrl)),
+        parseEndpoint(normaliseBaseUrl(hardware?.baseUrl)),
         parseEndpoint(normaliseBaseUrl(rawConfig?.baseUrl)),
     ];
     const hostCandidates = [
@@ -55,9 +59,9 @@ export function loadConfig() {
         ...parsedBaseOverrides.map((entry) => entry.hostname),
     ];
     const portCandidates = [
-        configuredPort(process.env.C64U_PORT),
+        configuredPort(useU2 ? process.env.U2_PORT ?? process.env.C64U_PORT : process.env.C64U_PORT),
         parsedEnvHost.port,
-        configuredPort(c64u?.port),
+        configuredPort(hardware?.port),
         parsedC64uHost.port,
         parsedC64uHostname.port,
         configuredPort(rawConfig?.c64_port),
@@ -74,7 +78,7 @@ export function loadConfig() {
         c64_host: hostWithPort,
         baseUrl,
         c64_port: port,
-        networkPassword: firstDefined(configuredString(process.env.C64U_PASSWORD), configuredString(c64u?.networkPassword), configuredString(rawConfig?.networkPassword)),
+        networkPassword: firstDefined(configuredString(useU2 ? process.env.U2_PASSWORD ?? process.env.C64U_PASSWORD : process.env.C64U_PASSWORD), configuredString(hardware?.networkPassword), configuredString(rawConfig?.networkPassword)),
         vicePrewarm: firstDefined(configuredBoolean(process.env.VICE_PREWARM), configuredBoolean(vice?.prewarm), configuredBoolean(rawConfig?.vicePrewarm)) ?? false,
     };
     cachedConfig = config;

package/dist/device.js

@@ -77,10 +77,13 @@ function readConfigFile() {
                 if (!merged.c64u && json?.c64u && typeof json.c64u === "object" && !Array.isArray(json.c64u)) {
                     merged.c64u = json.c64u;
                 }
+                if (!merged.u2 && json?.u2 && typeof json.u2 === "object" && !Array.isArray(json.u2)) {
+                    merged.u2 = json.u2;
+                }
                 if (!merged.vice && json?.vice && typeof json.vice === "object" && !Array.isArray(json.vice)) {
                     merged.vice = json.vice;
                 }
-                if (merged.c64u && merged.vice) {
+                if ((merged.c64u || merged.u2) && merged.vice) {
                     break;
                 }
             }
@@ -90,17 +93,17 @@ function readConfigFile() {
     return foundCandidate ? merged : null;
 }
 class C64uBackend {
-    constructor(config) {
-        this.type = "c64u";
-        const envHost = configuredString(process.env.C64U_HOST);
-        const envPort = configuredPort(process.env.C64U_PORT);
+    constructor(config, type = "c64u") {
+        this.type = type;
+        const envHost = configuredString(type === "u2" ? process.env.U2_HOST ?? process.env.C64U_HOST : process.env.C64U_HOST);
+        const envPort = configuredPort(type === "u2" ? process.env.U2_PORT ?? process.env.C64U_PORT : process.env.C64U_PORT);
         const configBaseUrl = normaliseBaseUrl(config.baseUrl);
         const parsedConfigBaseUrl = configBaseUrl ? parseEndpoint(configBaseUrl) : {};
         const baseUrl = envHost !== undefined || envPort !== undefined
             ? buildBaseUrl(firstDefined(envHost, configuredString(config.host), configuredString(config.hostname), parsedConfigBaseUrl.hostname) ?? DEFAULT_C64U_HOST, firstDefined(envPort, configuredPort(config.port), parsedConfigBaseUrl.port) ?? DEFAULT_C64U_PORT)
             : resolveBaseUrl(config);
         this.baseUrl = baseUrl;
-        this.networkPassword = firstDefined(configuredString(process.env.C64U_PASSWORD), configuredString(config.networkPassword));
+        this.networkPassword = firstDefined(configuredString(type === "u2" ? process.env.U2_PASSWORD ?? process.env.C64U_PASSWORD : process.env.C64U_PASSWORD), configuredString(config.networkPassword));
         const http = createLoggingHttpClient({
             baseURL: baseUrl,
             timeout: 10000,
@@ -108,6 +111,11 @@ class C64uBackend {
         });
         this.api = new Api(http);
     }
+    requireC64u(feature) {
+        if (this.type === "u2") {
+            throw unsupported(`${feature} is unavailable on U2-family cartridges`);
+        }
+    }
     getBaseUrl() { return this.baseUrl; }
     async ping() {
         try {
@@ -185,10 +193,26 @@ class C64uBackend {
     async reboot() { const res = await this.api.v1.machineRebootUpdate(":reboot"); return { success: true, details: res.data }; }
     async pause() { const res = await this.api.v1.machinePauseUpdate(":pause"); return { success: true, details: res.data }; }
     async resume() { const res = await this.api.v1.machineResumeUpdate(":resume"); return { success: true, details: res.data }; }
-    async poweroff() { const res = await this.api.v1.machinePoweroffUpdate(":poweroff"); return { success: true, details: res.data }; }
+    async poweroff() { this.requireC64u("poweroff"); const res = await this.api.v1.machinePoweroffUpdate(":poweroff"); return { success: true, details: res.data }; }
+    async powerCycle() { this.requireC64u("powerCycle"); throw unsupported("powerCycle must be coordinated by C64Client"); }
     async menuButton() { const res = await this.api.v1.machineMenuButtonUpdate(":menu_button"); return { success: true, details: res.data }; }
-    async debugregRead() { const res = await this.api.v1.machineDebugregList(":debugreg"); return { success: true, value: res.data.value, details: res.data }; }
-    async debugregWrite(value) { const res = await this.api.v1.machineDebugregUpdate(":debugreg", { value }); return { success: true, value: res.data.value, details: res.data }; }
+    async readMenuScreen() {
+        const response = await this.api.v1.machineMenuScreenList(":menu_screen", { format: "arraybuffer", headers: { Accept: "application/octet-stream" } });
+        const body = response.data;
+        return body instanceof ArrayBuffer ? new Uint8Array(body) : extractBytes(body);
+    }
+    async getInputState() {
+        this.requireC64u("getInputState");
+        const response = await this.api.v1.machineInputList(":input");
+        return response.data;
+    }
+    async sendInputEvents(batch) {
+        this.requireC64u("sendInputEvents");
+        const response = await this.api.v1.machineInputCreate(":input", batch);
+        return response.data;
+    }
+    async debugregRead() { this.requireC64u("debugregRead"); const res = await this.api.v1.machineDebugregList(":debugreg"); return { success: true, value: res.data.value, details: res.data }; }
+    async debugregWrite(value) { this.requireC64u("debugregWrite"); const res = await this.api.v1.machineDebugregUpdate(":debugreg", { value }); return { success: true, value: res.data.value, details: res.data }; }
     async version() { const res = await this.api.v1.versionList(); return res.data; }
     async info() { const res = await this.api.v1.infoList(); return res.data; }
     async drivesList() { const res = await this.api.v1.drivesList(); return res.data; }
@@ -199,8 +223,8 @@ class C64uBackend {
     async driveOff(d) { const res = await this.api.v1.drivesOffUpdate(d, ":off"); return { success: true, details: res.data }; }
     async driveSetMode(d, mode) { const res = await this.api.v1.drivesSetModeUpdate(d, ":set_mode", { mode }); return { success: true, details: res.data }; }
     async driveLoadRom(d, romPath) { const res = await this.api.v1.drivesLoadRomUpdate(d, ":load_rom", { file: romPath }); return { success: true, details: res.data }; }
-    async streamStart(s, ip) { const res = await this.api.v1.streamsStartUpdate(s, ":start", { ip }); return { success: true, details: res.data }; }
-    async streamStop(s) { const res = await this.api.v1.streamsStopUpdate(s, ":stop"); return { success: true, details: res.data }; }
+    async streamStart(s, ip) { this.requireC64u("streamStart"); const res = await this.api.v1.streamsStartUpdate(s, ":start", { ip }); return { success: true, details: res.data }; }
+    async streamStop(s) { this.requireC64u("streamStop"); const res = await this.api.v1.streamsStopUpdate(s, ":stop"); return { success: true, details: res.data }; }
     async configsList() { const res = await this.api.v1.configsList(); return res.data; }
     async configGet(cat, item) { const res = item ? await this.api.v1.configsDetail2(cat, item) : await this.api.v1.configsDetail(cat); return res.data; }
     async configSet(cat, item, value) { const res = await this.api.v1.configsUpdate(cat, item, { value }); return { success: true, details: res.data }; }
@@ -580,6 +604,7 @@ export class ViceBackend {
             return { success: false, details };
         }
     }
+    async powerCycle() { return this.nuclearReset(); }
     async nuclearReset() {
         const poweroffResult = await this.poweroff();
         if (!poweroffResult.success) {
@@ -606,6 +631,9 @@ export class ViceBackend {
         }
     }
     async menuButton() { throw unsupported("menuButton"); }
+    async readMenuScreen() { throw unsupported("readMenuScreen"); }
+    async getInputState() { throw unsupported("getInputState"); }
+    async sendInputEvents(_batch) { throw unsupported("sendInputEvents"); }
     async debugregRead() { throw unsupported("debugregRead"); }
     async debugregWrite(_v) { throw unsupported("debugregWrite"); }
     async version() { return { emulator: "vice", host: this.host, port: this.port }; }
@@ -885,46 +913,53 @@ export function __buildViceProcessOptionsForTests(input) {
     return buildManagedViceProcessOptions(input);
 }
 export async function createFacade(logger, options) {
+    const envMode = (process.env.C64_MODE || "").toLowerCase().trim();
     // Caller-forced preference: use c64u with provided base URL (used by tests and server wiring)
     if (options?.preferredC64uBaseUrl) {
+        const type = envMode === "u2" ? "u2" : "c64u";
         const backend = new C64uBackend({
             baseUrl: options.preferredC64uBaseUrl,
             networkPassword: options.preferredC64uNetworkPassword,
-        });
-        logger?.info?.("Active backend: c64u (forced by caller)");
-        return { facade: backend, selected: "c64u", reason: "forced by caller", details: { baseUrl: options.preferredC64uBaseUrl } };
+        }, type);
+        logger?.info?.(`Active backend: ${type} (forced by caller)`);
+        return { facade: backend, selected: type, reason: "forced by caller", details: { baseUrl: options.preferredC64uBaseUrl } };
     }
     const cfg = readConfigFile();
-    const envMode = (process.env.C64_MODE || "").toLowerCase().trim();
     const hasC64u = Boolean(cfg?.c64u);
+    const hasU2 = Boolean(cfg?.u2);
     const hasVice = Boolean(cfg?.vice);
     if (envMode === "c64u") {
         const backend = new C64uBackend(cfg?.c64u ?? {});
         logger?.info?.("Active backend: c64u (from env override)");
         return { facade: backend, selected: "c64u", reason: "env override", details: { baseUrl: backend.getBaseUrl?.() } };
     }
+    if (envMode === "u2") {
+        const backend = new C64uBackend(cfg?.u2 ?? {}, "u2");
+        logger?.info?.("Active backend: u2 (from env override)");
+        return { facade: backend, selected: "u2", reason: "env override", details: { baseUrl: backend.getBaseUrl?.() } };
+    }
     if (envMode === "vice") {
         const backend = new ViceBackend(cfg?.vice ?? {});
         logger?.info?.("Active backend: vice (from env override)");
         const endpoint = backend.getEndpoint();
         return { facade: backend, selected: "vice", reason: "env override", details: { host: endpoint.host, port: endpoint.port } };
     }
-    if (hasC64u && !hasVice) {
+    if (hasC64u) {
         const backend = new C64uBackend(cfg.c64u);
         logger?.info?.("Active backend: c64u (from config)");
-        return { facade: backend, selected: "c64u", reason: "config only", details: { baseUrl: backend.getBaseUrl?.() } };
+        return { facade: backend, selected: "c64u", reason: hasVice ? "both defined (prefer c64u)" : "config only", details: { baseUrl: backend.getBaseUrl?.() } };
+    }
+    if (hasU2) {
+        const backend = new C64uBackend(cfg.u2, "u2");
+        logger?.info?.("Active backend: u2 (from config)");
+        return { facade: backend, selected: "u2", reason: "config only", details: { baseUrl: backend.getBaseUrl?.() } };
     }
-    if (!hasC64u && hasVice) {
+    if (hasVice) {
         const backend = new ViceBackend(cfg.vice);
         logger?.info?.("Active backend: vice (from config)");
         const endpoint = backend.getEndpoint();
         return { facade: backend, selected: "vice", reason: "config only", details: { host: endpoint.host, port: endpoint.port } };
     }
-    if (hasC64u && hasVice) {
-        const backend = new C64uBackend(cfg.c64u);
-        logger?.info?.("Active backend: c64u (both defined; default preference)");
-        return { facade: backend, selected: "c64u", reason: "both defined (prefer c64u)", details: { baseUrl: backend.getBaseUrl?.() } };
-    }
     // No configuration
     const probeBase = resolveBaseUrl({});
     try {
@@ -942,35 +977,30 @@ export async function createFacade(logger, options) {
     return { facade: backend, selected: "vice", reason: "fallback (hardware unavailable)", details: { host: endpoint.host, port: endpoint.port } };
 }
 export async function createAllFacades(logger, options) {
-    const primary = await createFacade(logger);
+    // C64U/VICE preserve config-file selection semantics. U2 needs the
+    // caller-provided endpoint because it is selected through C64_MODE=u2.
+    const primary = await createFacade(logger, process.env.C64_MODE?.toLowerCase().trim() === "u2" ? options : undefined);
     const config = readConfigFile();
-    const secondaryType = primary.selected === "c64u" ? "vice" : "c64u";
-    if (secondaryType === "c64u" && shouldProvisionSecondaryC64u(config, options)) {
-        const secondaryConfig = {
+    const facades = new Map([[primary.selected, primary.facade]]);
+    if (config?.c64u && primary.selected !== "c64u") {
+        facades.set("c64u", new C64uBackend(config.c64u));
+    }
+    if (config?.u2 && primary.selected !== "u2") {
+        facades.set("u2", new C64uBackend(config.u2, "u2"));
+    }
+    if (config?.vice && primary.selected !== "vice") {
+        facades.set("vice", new ViceBackend(config.vice));
+    }
+    if (!facades.has("c64u") && !config?.u2 && shouldProvisionSecondaryC64u(config, options) && primary.selected !== "u2") {
+        facades.set("c64u", new C64uBackend({
             ...(config?.c64u ?? {}),
             ...(!config?.c64u?.baseUrl && options?.preferredC64uBaseUrl ? { baseUrl: options.preferredC64uBaseUrl } : {}),
             ...(!config?.c64u?.networkPassword && options?.preferredC64uNetworkPassword
                 ? { networkPassword: options.preferredC64uNetworkPassword }
                 : {}),
-        };
-        return {
-            primary,
-            secondary: new C64uBackend(secondaryConfig),
-            secondaryType,
-        };
-    }
-    if (secondaryType === "vice" && config?.vice) {
-        return {
-            primary,
-            secondary: new ViceBackend(config.vice),
-            secondaryType,
-        };
+        }));
     }
-    return {
-        primary,
-        secondary: null,
-        secondaryType: null,
-    };
+    return { primary, facades };
 }
 function shouldProvisionSecondaryC64u(config, options) {
     return Boolean(config?.c64u

package/dist/mcp-server.js

@@ -165,7 +165,7 @@ async function main() {
                         {
                             uri: PLATFORM_RESOURCE_URI,
                             mimeType: "text/markdown",
-                            text: renderPlatformStatusMarkdown(client),
+                            text: await renderPlatformStatusMarkdown(client),
                         },
                     ],
                 };
@@ -447,10 +447,11 @@ function createPlatformResourceDescriptor() {
         },
     };
 }
-function renderPlatformStatusMarkdown(client) {
+async function renderPlatformStatusMarkdown(client) {
     const status = getPlatformStatus();
     const availableBackends = client.getAvailableBackends();
     const capabilities = describePlatformCapabilities(toolRegistry.list());
+    const nativeEndpoints = await client.getNativeEndpointCapabilities();
     const lines = [
         "# MCP Platform Status",
         "",
@@ -466,6 +467,13 @@ function renderPlatformStatusMarkdown(client) {
         status.limitedFeatures.length > 0
             ? ["## Limited or Unavailable Features", "", ...status.limitedFeatures.map((feature) => `- ${feature}`)].join("\n")
             : "",
+        "## Native REST Endpoint Availability",
+        "",
+        `- \`machine:input\`: **${nativeEndpoints.machineInput}**`,
+        `- \`machine:menu_screen\`: **${nativeEndpoints.machineMenuScreen}** (it can only be confirmed while an Ultimate menu is visible)`,
+        "",
+        "Use physical-input, menu-screen, and C64U/U64 Tool Menu power-cycle operations only when the required endpoint is available. Prefer `key` or `write_text` for ordinary C64 input when `machine:input` is unavailable.",
+        "",
         "## Tool Compatibility",
         "",
     ].filter(Boolean);
@@ -487,7 +495,7 @@ function renderPlatformStatusMarkdown(client) {
 }
 async function logConnectivity(client, baseUrl) {
     const backendType = await client.getBackendType();
-    if (backendType !== "c64u") {
+    if (backendType === "vice") {
         writeDiagnosticEvent("connectivity_probe_skipped", { baseUrl, reason: "vice_backend" });
         console.error("Skipping direct REST connectivity probe because active backend is VICE");
         try {

package/dist/platform.js

@@ -10,6 +10,10 @@ const PLATFORM_FEATURES = {
         ],
         limited: [],
     },
+    u2: {
+        features: ["ultimate-rest-api", "cartridge-execution", "sid-control", "drive-management", "printer-integration"],
+        limited: ["no-machine-input", "no-debugreg", "no-poweroff", "no-streaming"],
+    },
     vice: {
         features: [
             "software-emulation",
@@ -23,7 +27,7 @@ const PLATFORM_FEATURES = {
         limited: ["no-rest-api", "no-firmware-filesystem", "no-flash-config", "limited-sid"],
     },
 };
-let currentPlatform = process.env.C64_MODE === "vice" ? "vice" : "c64u";
+let currentPlatform = process.env.C64_MODE === "vice" ? "vice" : process.env.C64_MODE === "u2" ? "u2" : "c64u";
 export function getPlatformStatus() {
     const spec = PLATFORM_FEATURES[currentPlatform];
     return {
@@ -48,11 +52,12 @@ export function isPlatformSupported(platform, supported) {
 export function describePlatformCapabilities(tools) {
     const map = {
         c64u: { available: [], unsupported: [] },
+        u2: { available: [], unsupported: [] },
         vice: { available: [], unsupported: [] },
     };
     for (const tool of tools) {
         const supported = tool.metadata.platforms ?? ["c64u"];
-        for (const id of ["c64u", "vice"]) {
+        for (const id of ["c64u", "u2", "vice"]) {
             if (supported.includes(id)) {
                 map[id].available.push(tool.name);
             }
@@ -69,6 +74,12 @@ export function describePlatformCapabilities(tools) {
                 tools: map.c64u.available.sort(),
                 unsupported_tools: map.c64u.unsupported.sort(),
             },
+            u2: {
+                features: PLATFORM_FEATURES.u2.features,
+                limited_features: PLATFORM_FEATURES.u2.limited,
+                tools: map.u2.available.sort(),
+                unsupported_tools: map.u2.unsupported.sort(),
+            },
             vice: {
                 features: PLATFORM_FEATURES.vice.features,
                 limited_features: PLATFORM_FEATURES.vice.limited,

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);
             },