c64bridge 1.0.4 → 1.0.6

package/dist/device.js

@@ -9,10 +9,9 @@ import { Api } from "../generated/c64/index.js";
 import { createLoggingHttpClient } from "./loggingHttpClient.js";
 import { ViceClient } from "./vice/viceClient.js";
 import { waitForBasicReady } from "./vice/readiness.js";
+import { screenCodesToAscii } from "./petscii.js";
 import { startViceProcess } from "./vice/process.js";
-import { loadConfig } from "./config.js";
-const DEFAULT_C64U_HOST = "c64u";
-const DEFAULT_C64U_PORT = 80;
+import { loadConfig, resolveUltimateEndpoint } from "./config.js";
 const DEFAULT_VICE_HOST = "127.0.0.1";
 const DEFAULT_VICE_PORT = 6502;
 function delay(ms) {
@@ -52,28 +51,44 @@ function coalesceMemoryWriteBlocks(blocks) {
     }
     return merged;
 }
+/** All C64U/U2 endpoints come from loadConfig(), so the MCP server and every
+ * backend agree on host, port and password. */
 function readConfigFile() {
-    const sections = loadConfig().backendConfig;
-    return Object.keys(sections).length === 0 ? null : {
-        c64u: sections.c64u,
-        u2: sections.u2,
+    const config = loadConfig();
+    const sections = config.backendConfig;
+    return {
+        c64u: sections.c64u || config.legacyUltimateEndpoint ? config.ultimate.c64u : undefined,
+        u2: sections.u2 ? config.ultimate.u2 : undefined,
         vice: sections.vice,
+        endpoints: config.ultimate,
     };
 }
+/** Firmware drive ids (route_drives.h DriveToSubsys, matched case-insensitively). */
+const FIRMWARE_DRIVE_IDS = new Set(["a", "b", "softiec"]);
+/** GET /v1/drives reports the soft IEC drive under this name; the drive routes call it softiec. */
+const SOFT_IEC_LISTING_ID = "iec drive";
+/** Factory bus numbers of drives a and b, used when the drive listing is unavailable. */
+const DEFAULT_DRIVE_BY_BUS_ID = { 8: "a", 9: "b" };
+/** The firmware reports a mounted image as directory (image_path) plus file name (image_file). */
+function driveImage(info) {
+    const file = typeof info.image_file === "string" ? info.image_file : "";
+    const dir = typeof info.image_path === "string" ? info.image_path : "";
+    if (file)
+        return dir ? `${dir.replace(/\/+$/, "")}/${file}` : file;
+    if (dir)
+        return dir;
+    return typeof info.image === "string" && info.image ? info.image : null;
+}
+function uploadFile(bytes, name) {
+    return new File([Uint8Array.from(bytes)], name, { type: "application/octet-stream" });
+}
 class C64uBackend {
-    constructor(config, type = "c64u") {
+    constructor(endpoint, 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(type === "u2" ? process.env.U2_PASSWORD ?? process.env.C64U_PASSWORD : process.env.C64U_PASSWORD), configuredString(config.networkPassword));
+        this.baseUrl = endpoint.baseUrl;
+        this.networkPassword = endpoint.networkPassword;
         const http = createLoggingHttpClient({
-            baseURL: baseUrl,
+            baseURL: this.baseUrl,
             timeout: 10000,
             headers: buildC64uHeaders(this.networkPassword),
         });
@@ -132,10 +147,15 @@ class C64uBackend {
         return this.actionResult(res.data);
     }
     async sidplayAttachment(sid, options) {
-        const form = { sid: Buffer.isBuffer(sid) ? sid : Buffer.from(sid) };
+        // The generated multipart builder JSON-encodes anything that is not a Blob,
+        // so the bytes must be File parts. The firmware ignores part names and
+        // takes the first file as the SID and the second as song lengths; the spec
+        // names both `file`. The temp file keeps the upload name, and its extension
+        // selects SID versus MUS playback.
+        const file = [uploadFile(sid, "upload.sid")];
         if (options?.songlengths)
-            form.songlengths = Buffer.isBuffer(options.songlengths) ? options.songlengths : Buffer.from(options.songlengths);
-        const res = await this.api.v1.runnersSidplayCreate(":sidplay", form, options?.songnr !== undefined ? { songnr: options.songnr } : undefined);
+            file.push(uploadFile(options.songlengths, "upload.ssl"));
+        const res = await this.api.v1.runnersSidplayCreate(":sidplay", { file }, options?.songnr !== undefined ? { songnr: options.songnr } : undefined);
         return this.actionResult(res.data);
     }
     async readMemory(address, length) {
@@ -196,32 +216,75 @@ class C64uBackend {
     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() {
+    async driveEntries() {
         const res = await this.api.v1.drivesList();
         const raw = res.data;
         const entries = Array.isArray(raw.drives)
             ? raw.drives
             : raw.drives && typeof raw.drives === "object" ? [raw.drives] : [];
-        return entries.flatMap((entry) => Object.entries(entry).map(([id, info]) => ({
+        return entries.flatMap((entry) => Object.entries(entry));
+    }
+    /**
+     * Map a drive id to the firmware's `a`, `b` or `softiec`. Bus numbers such
+     * as `drive8` or `8` are looked up by `bus_id` among drives a and b in
+     * GET /v1/drives, because a drive letter's bus number is configurable; the
+     * factory a=8, b=9 applies only when the listing is unavailable. The soft
+     * IEC drive is reachable only by name, never by bus number.
+     */
+    async resolveDriveId(drive) {
+        const lower = drive.trim().toLowerCase();
+        if (FIRMWARE_DRIVE_IDS.has(lower))
+            return lower;
+        if (lower === SOFT_IEC_LISTING_ID)
+            return "softiec";
+        const match = /^(?:drive)?\s*(\d+)$/.exec(lower);
+        if (!match)
+            return drive;
+        const busId = Number(match[1]);
+        let listed = [];
+        try {
+            listed = (await this.driveEntries()).flatMap(([id, info]) => {
+                const listedBusId = Number(info?.bus_id);
+                return (id === "a" || id === "b") && Number.isInteger(listedBusId) ? [{ id, busId: listedBusId, enabled: info?.enabled !== false }] : [];
+            });
+        }
+        catch {
+            listed = [];
+        }
+        // A disabled drive keeps its bus_id setting, so prefer the enabled drive the C64 actually sees on that bus.
+        const onBus = listed.filter((entry) => entry.busId === busId);
+        const resolved = listed.length > 0 ? (onBus.find((entry) => entry.enabled) ?? onBus[0])?.id : DEFAULT_DRIVE_BY_BUS_ID[busId];
+        if (!resolved) {
+            const known = listed.length > 0 ? listed.map((entry) => `${entry.id}=${entry.busId}`).join(", ") : "a=8, b=9";
+            throw new Error(`No drive found for '${drive}' (bus IDs: ${known})`);
+        }
+        return resolved;
+    }
+    async drivesList() {
+        const entries = await this.driveEntries();
+        return entries.map(([id, info]) => ({
             id,
             power: info.enabled === true || info.enabled === "on" || info.power === "on" ? "on" : "off",
-            image: (info.image_path ?? info.image_file ?? info.image ?? null),
+            image: driveImage(info),
             type: info.type ?? null,
             raw: info,
-        })));
+        }));
     }
-    async driveMount(d, img, options) { const res = await this.api.v1.drivesMountUpdate(d, ":mount", { image: img, type: options?.type, mode: options?.mode }); return this.actionResult(res.data); }
-    async driveRemove(d) { const res = await this.api.v1.drivesRemoveUpdate(d, ":remove"); return this.actionResult(res.data); }
-    async driveReset(d) { const res = await this.api.v1.drivesResetUpdate(d, ":reset"); return this.actionResult(res.data); }
-    async driveOn(d) { const res = await this.api.v1.drivesOnUpdate(d, ":on"); return this.actionResult(res.data); }
-    async driveOff(d) { const res = await this.api.v1.drivesOffUpdate(d, ":off"); return this.actionResult(res.data); }
-    async driveSetMode(d, mode) { const res = await this.api.v1.drivesSetModeUpdate(d, ":set_mode", { mode }); return this.actionResult(res.data); }
-    async driveLoadRom(d, romPath) { const res = await this.api.v1.drivesLoadRomUpdate(d, ":load_rom", { file: romPath }); return this.actionResult(res.data); }
+    async driveMount(d, img, options) { const res = await this.api.v1.drivesMountUpdate(await this.resolveDriveId(d), ":mount", { image: img, type: options?.type, mode: options?.mode }); return this.actionResult(res.data); }
+    async driveRemove(d) { const res = await this.api.v1.drivesRemoveUpdate(await this.resolveDriveId(d), ":remove"); return this.actionResult(res.data); }
+    async driveReset(d) { const res = await this.api.v1.drivesResetUpdate(await this.resolveDriveId(d), ":reset"); return this.actionResult(res.data); }
+    async driveOn(d) { const res = await this.api.v1.drivesOnUpdate(await this.resolveDriveId(d), ":on"); return this.actionResult(res.data); }
+    async driveOff(d) { const res = await this.api.v1.drivesOffUpdate(await this.resolveDriveId(d), ":off"); return this.actionResult(res.data); }
+    async driveSetMode(d, mode) { const res = await this.api.v1.drivesSetModeUpdate(await this.resolveDriveId(d), ":set_mode", { mode }); return this.actionResult(res.data); }
+    async driveLoadRom(d, romPath) { const res = await this.api.v1.drivesLoadRomUpdate(await this.resolveDriveId(d), ":load_rom", { file: romPath }); return this.actionResult(res.data); }
     async streamStart(s, ip) { this.requireC64u("streamStart"); const res = await this.api.v1.streamsStartUpdate(s, ":start", { ip }); return this.actionResult(res.data); }
     async streamStop(s) { this.requireC64u("streamStop"); const res = await this.api.v1.streamsStopUpdate(s, ":stop"); return this.actionResult(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 this.actionResult(res.data); }
+    // The generated client interpolates path parameters unencoded and the firmware
+    // splits the path on "/" before decoding, so names such as "Bus Sharing - I/O1"
+    // must be percent-encoded here.
+    async configGet(cat, item) { const res = item ? await this.api.v1.configsDetail2(encodeURIComponent(cat), encodeURIComponent(item)) : await this.api.v1.configsDetail(encodeURIComponent(cat)); return res.data; }
+    async configSet(cat, item, value) { const res = await this.api.v1.configsUpdate(encodeURIComponent(cat), encodeURIComponent(item), { value }); return this.actionResult(res.data); }
     async configBatchUpdate(payload) { const res = await this.api.v1.configsCreate(payload); return this.actionResult(res.data); }
     async configLoadFromFlash() { const res = await this.api.v1.configsLoadFromFlashUpdate(":load_from_flash"); return this.actionResult(res.data); }
     async configSaveToFlash() { const res = await this.api.v1.configsSaveToFlashUpdate(":save_to_flash"); return this.actionResult(res.data); }
@@ -240,6 +303,12 @@ export class ViceBackend {
         this.startupPromise = null;
         this.monitorQueue = Promise.resolve();
         this.lastProcessStart = 0;
+        // VICE has no "drive enabled" or "attached image" resource. A drive is off
+        // when Drive<n>Type is 0, and images attached through this backend are
+        // remembered here because VICE cannot report them.
+        this.attachedImages = new Map();
+        this.savedDriveTypes = new Map();
+        this.trackedStateProcessStart = 0;
         ViceBackend.ensureCleanupRegistration();
         const envBinary = configuredString(process.env.VICE_BINARY);
         const configBinary = config.exe !== undefined
@@ -672,19 +741,27 @@ export class ViceBackend {
     getEndpoint() {
         return { host: this.host, port: this.port };
     }
+    /** A restarted VICE has no images attached and default drive types, so forget what was tracked before. */
+    syncTrackedState() {
+        if (this.trackedStateProcessStart !== this.lastProcessStart) {
+            this.attachedImages.clear();
+            this.savedDriveTypes.clear();
+            this.trackedStateProcessStart = this.lastProcessStart;
+        }
+    }
     async drivesList() {
+        this.syncTrackedState();
         return await this.withClient(async (client) => {
             const drives = [];
             for (const n of [8, 9, 10, 11]) {
                 try {
-                    const enabled = await client.resourceGet(`Drive${n}CPUEnabled`);
-                    const image = await client.resourceGet(`Drive${n}Image`);
                     const typeRes = await client.resourceGet(`Drive${n}Type`);
+                    const type = typeRes.type === "int" ? typeRes.value : Number(typeRes.value);
                     drives.push({
                         id: `drive${n}`,
-                        power: (typeof enabled.value === "number" ? enabled.value : 0) ? "on" : "off",
-                        image: typeof image.value === "string" && image.value ? image.value : null,
-                        type: typeRes.value,
+                        power: type !== 0 ? "on" : "off",
+                        image: this.attachedImages.get(n) ?? null,
+                        type,
                     });
                 }
                 catch {
@@ -699,44 +776,83 @@ export class ViceBackend {
             throw unsupported("driveMount type/mode overrides; omit these options on VICE");
         }
         const n = parseDriveNumber(drive);
-        await this.withClient(async (client) => {
-            await client.resourceSet(`Drive${n}CPUEnabled`, 1);
-            await client.resourceSet(`Drive${n}Image`, imagePath);
+        if (n !== 8) {
+            // The Binary Monitor's only attach path is autostart, which always uses drive 8.
+            throw unsupported(`driveMount on drive ${n}; VICE can attach images over the Binary Monitor only to drive 8`);
+        }
+        // Autostart falls back to tape, snapshot, cartridge and PRG handling when a
+        // file is not a disk image, so only disk images are passed on.
+        if (!VICE_DISK_IMAGE_EXTENSIONS.has(path.extname(imagePath).toLowerCase())) {
+            throw new Error(`VICE can mount only disk images (${[...VICE_DISK_IMAGE_EXTENSIONS].join(", ")}): ${imagePath}`);
+        }
+        if (!fs.existsSync(imagePath)) {
+            throw new Error(`Disk image not found on the VICE host: ${imagePath}`);
+        }
+        const outcome = await this.withClient(async (client) => {
+            // Sync after withClient has started VICE, or a start here would clear this mount's record.
+            this.syncTrackedState();
+            await this.ensureDriveOn(client, n);
+            await client.memSet(AUTOLOAD_MARKER_ADDRESS, AUTOLOAD_MARKER);
+            await client.autostart(imagePath, { run: false });
+            // Autoload power-cycles the machine after this call returns; wait until
+            // its LOAD has finished so callers do not write into a machine that is
+            // about to be reset.
+            return waitForAutoloadFinished(client, 30000);
         });
-        return { success: true, details: { drive, image: imagePath } };
+        this.attachedImages.set(n, imagePath);
+        return {
+            success: true,
+            details: {
+                drive,
+                image: imagePath,
+                loadedFirstProgram: outcome.loaded,
+                note: outcome.loaded
+                    ? "VICE attaches images through autoload, which resets the machine (clearing RAM) and LOADs the first program without running it."
+                    : "VICE attaches images through autoload, which resets the machine (clearing RAM); the disk has no program to load.",
+            },
+        };
     }
-    async driveRemove(drive) {
-        const n = parseDriveNumber(drive);
-        await this.withClient(async (client) => {
-            await client.resourceSet(`Drive${n}Image`, "");
-        });
-        return { success: true, details: { drive } };
+    async driveRemove(_drive) {
+        throw unsupported("driveRemove; the VICE Binary Monitor has no command to detach a disk image");
     }
     async driveReset(drive) {
         const n = parseDriveNumber(drive);
         await this.withClient(async (client) => {
-            await client.resourceSet(`Drive${n}CPUEnabled`, 0);
-            await client.resourceSet(`Drive${n}CPUEnabled`, 1);
+            await client.resetDrive(n);
         });
         return { success: true, details: { drive } };
     }
     async driveOn(drive) {
         const n = parseDriveNumber(drive);
         await this.withClient(async (client) => {
-            await client.resourceSet(`Drive${n}CPUEnabled`, 1);
+            await this.ensureDriveOn(client, n);
         });
         return { success: true, details: { drive, power: "on" } };
     }
     async driveOff(drive) {
         const n = parseDriveNumber(drive);
+        this.syncTrackedState();
         await this.withClient(async (client) => {
-            await client.resourceSet(`Drive${n}CPUEnabled`, 0);
+            const current = await client.resourceGet(`Drive${n}Type`);
+            const type = current.type === "int" ? current.value : Number(current.value);
+            if (type !== 0)
+                this.savedDriveTypes.set(n, type);
+            await client.resourceSet(`Drive${n}Type`, 0);
         });
         return { success: true, details: { drive, power: "off" } };
     }
+    /** Switch a drive on by giving it a type again: the one it had before driveOff, or a 1541. */
+    async ensureDriveOn(client, n) {
+        const current = await client.resourceGet(`Drive${n}Type`);
+        const type = current.type === "int" ? current.value : Number(current.value);
+        if (type === 0) {
+            await client.resourceSet(`Drive${n}Type`, this.savedDriveTypes.get(n) ?? 1541);
+        }
+    }
     async driveSetMode(drive, mode) {
         const n = parseDriveNumber(drive);
-        const DRIVE_TYPE = { "1541": 2, "1571": 8, "1581": 11 };
+        // Drive<n>Type takes the model number itself (DRIVE_TYPE_1541 = 1541 in VICE's drive.h).
+        const DRIVE_TYPE = { "1541": 1541, "1571": 1571, "1581": 1581 };
         const typeNum = DRIVE_TYPE[mode];
         if (typeNum === undefined)
             throw new Error(`Unknown drive mode: ${mode}`);
@@ -753,10 +869,11 @@ export class ViceBackend {
             categories: [
                 {
                     name: "VICE",
+                    // Only resources that exist in VICE 3.10; checked against a running x64sc.
+                    // VICE has no warp, drive-enable or attached-image resources.
                     items: [
-                        "WarpMode", "SoundVolume", "Drive8CPUEnabled", "Drive9CPUEnabled",
-                        "Drive10CPUEnabled", "Drive11CPUEnabled", "Drive8Image", "Drive9Image",
-                        "Drive8Type", "Drive9Type", "VICIIBorderMode", "VICIIFullscreen",
+                        "SoundVolume", "Drive8Type", "Drive9Type", "Drive10Type", "Drive11Type",
+                        "VICIIBorderMode", "VICIIFullscreen", "MachineVideoStandard", "SidModel",
                     ],
                 },
             ],
@@ -832,13 +949,69 @@ function parseViceConfigValue(value, type, item) {
     }
     return parsed;
 }
-function unsupported(name) { const err = new Error(`Operation '${name}' is not supported by the VICE backend in phase one`); err.code = "UNSUPPORTED"; return err; }
+function unsupported(name) { const err = new Error(`Operation '${name}' is not supported by the VICE backend`); err.code = "UNSUPPORTED"; return err; }
 /** Ultimate file APIs treat slash as a path separator. Encode each name once,
  * preserving leading and nested separators for firmware routing. */
 function encodeDevicePath(value) {
     return value.split("/").map((segment) => encodeURIComponent(segment)).join("/");
 }
+/** Disk image types VICE's drive 8 can attach (autostart would treat anything else as tape, cartridge or PRG). */
+const VICE_DISK_IMAGE_EXTENSIONS = new Set([".d64", ".g64", ".d71", ".g71", ".d81", ".d80", ".d82", ".x64", ".p64", ".d1m", ".d2m", ".d4m"]);
+/**
+ * Bytes written to unused RAM ($02A7-$02AA) before an autoload. The autoload's
+ * power cycle clears them, which shows that the reset has happened.
+ */
+const AUTOLOAD_MARKER_ADDRESS = 0x02a7;
+const AUTOLOAD_MARKER = Buffer.from([0xc6, 0x4b, 0x1d, 0x9e]);
+/**
+ * Wait until VICE's autoload has reset the machine and its LOAD has finished.
+ * Completion is the LOAD"/READY. text on screen, or, when the loaded program
+ * covers screen RAM, BASIC initialised (TXTTAB $0801) with its end-of-program
+ * pointer (VARTAB) moved off the reset value $0803 and an empty keyboard buffer.
+ */
+async function waitForAutoloadFinished(client, timeoutMs) {
+    const deadline = Date.now() + timeoutMs;
+    let loadedEnd = null;
+    while (Date.now() < deadline) {
+        await client.exitMonitor();
+        await delay(250);
+        const marker = await client.memGet(AUTOLOAD_MARKER_ADDRESS, AUTOLOAD_MARKER_ADDRESS + AUTOLOAD_MARKER.length - 1);
+        if (Buffer.from(marker).equals(AUTOLOAD_MARKER))
+            continue; // not reset yet
+        const screen = screenCodesToAscii(await client.memGet(0x0400, 0x0400 + 999));
+        const load = screen.lastIndexOf('LOAD"');
+        if (load >= 0) {
+            const after = screen.slice(load);
+            // An empty disk is still attached; it just has no program for the autoload to load.
+            if (/\?FILE NOT FOUND/.test(after))
+                return { loaded: false };
+            const error = /\?([A-Z ]+ERROR|DEVICE NOT PRESENT)/.exec(after);
+            if (error)
+                throw new Error(`VICE autoload failed: ?${error[1]}`);
+            if (after.includes("READY."))
+                return { loaded: true };
+        }
+        // TXTTAB = $0801 shows BASIC has initialised (right after the power cycle RAM
+        // holds VICE's init pattern); VARTAB off $0803 then shows the LOAD has ended.
+        const pointers = await client.memGet(0x002b, 0x002e);
+        const keyboardQueue = await client.memGet(0x00c6, 0x00c6);
+        const txttab = (pointers[0] ?? 0) | ((pointers[1] ?? 0) << 8);
+        const vartab = (pointers[2] ?? 0) | ((pointers[3] ?? 0) << 8);
+        // BASIC's cold start sets TXTTAB before VARTAB, so require the same end
+        // pointer on two consecutive polls before trusting it.
+        const candidate = txttab === 0x0801 && vartab !== 0x0803 && keyboardQueue[0] === 0 ? vartab : null;
+        if (candidate !== null && candidate === loadedEnd)
+            return { loaded: true };
+        loadedEnd = candidate;
+    }
+    throw new Error("VICE autoload did not finish within the time limit");
+}
+/** C64U drive letters with their factory bus numbers, so one drive id works on both backends. */
+const VICE_DRIVE_LETTERS = { a: 8, b: 9 };
 function parseDriveNumber(drive) {
+    const key = drive.trim().toLowerCase();
+    if (Object.prototype.hasOwnProperty.call(VICE_DRIVE_LETTERS, key))
+        return VICE_DRIVE_LETTERS[key];
     const match = /\d+/.exec(drive);
     const n = match ? parseInt(match[0], 10) : NaN;
     if (isNaN(n) || n < 8 || n > 11)
@@ -971,29 +1144,29 @@ export async function createFacade(logger, options) {
     // 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({
+        const backend = new C64uBackend(resolveUltimateEndpoint(type, {
             baseUrl: options.preferredC64uBaseUrl,
             networkPassword: options.preferredC64uNetworkPassword,
-        }, type);
+        }), 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 hasC64u = Boolean(cfg?.c64u);
-    const hasU2 = Boolean(cfg?.u2);
-    const hasVice = Boolean(cfg?.vice);
+    const hasC64u = Boolean(cfg.c64u);
+    const hasU2 = Boolean(cfg.u2);
+    const hasVice = Boolean(cfg.vice);
     if (envMode === "c64u") {
-        const backend = new C64uBackend(cfg?.c64u ?? {});
+        const backend = new C64uBackend(cfg.endpoints.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");
+        const backend = new C64uBackend(cfg.endpoints.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 ?? {});
+        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 } };
@@ -1015,17 +1188,17 @@ export async function createFacade(logger, options) {
         return { facade: backend, selected: "vice", reason: "config only", details: { host: endpoint.host, port: endpoint.port } };
     }
     // No configuration
-    const probeBase = resolveBaseUrl({});
+    const probeBase = cfg.endpoints.c64u.baseUrl;
     try {
         const res = await axios.get(probeBase, { timeout: 1500 });
         if (res.status >= 200 && res.status < 500) {
-            const backend = new C64uBackend({ baseUrl: probeBase });
+            const backend = new C64uBackend(cfg.endpoints.c64u);
             logger?.info?.("Active backend: c64u (fallback – hardware reachable)");
             return { facade: backend, selected: "c64u", reason: "fallback (reachable)", details: { baseUrl: probeBase } };
         }
     }
     catch { }
-    const backend = new ViceBackend(cfg?.vice ?? {});
+    const backend = new ViceBackend(cfg.vice ?? {});
     logger?.info?.("Active backend: vice (fallback – hardware unavailable)");
     const endpoint = backend.getEndpoint();
     return { facade: backend, selected: "vice", reason: "fallback (hardware unavailable)", details: { host: endpoint.host, port: endpoint.port } };
@@ -1036,49 +1209,31 @@ export async function createAllFacades(logger, options) {
     const primary = await createFacade(logger, process.env.C64_MODE?.toLowerCase().trim() === "u2" ? options : undefined);
     const config = readConfigFile();
     const facades = new Map([[primary.selected, primary.facade]]);
-    if (config?.c64u && primary.selected !== "c64u") {
+    if (config.c64u && primary.selected !== "c64u") {
         facades.set("c64u", new C64uBackend(config.c64u));
     }
-    if (config?.u2 && primary.selected !== "u2") {
+    if (config.u2 && primary.selected !== "u2") {
         facades.set("u2", new C64uBackend(config.u2, "u2"));
     }
-    if (config?.vice && primary.selected !== "vice") {
+    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 }
-                : {}),
-        }));
+    // Reached only without a configured c64u profile, so the caller's endpoint applies.
+    if (!facades.has("c64u") && !config.u2 && shouldProvisionSecondaryC64u(config, options) && primary.selected !== "u2") {
+        facades.set("c64u", new C64uBackend(resolveUltimateEndpoint("c64u", {
+            baseUrl: options?.preferredC64uBaseUrl,
+            networkPassword: options?.preferredC64uNetworkPassword,
+        })));
     }
     return { primary, facades };
 }
 function shouldProvisionSecondaryC64u(config, options) {
-    return Boolean(config?.c64u
+    return Boolean(config.c64u
         || options?.preferredC64uBaseUrl
         || configuredString(process.env.C64U_HOST)
         || configuredPort(process.env.C64U_PORT)
         || configuredString(process.env.C64U_PASSWORD));
 }
-function resolveBaseUrl(config) {
-    const explicit = normaliseBaseUrl(config.baseUrl);
-    if (explicit)
-        return explicit;
-    const hostEntries = [configuredString(config.host), configuredString(config.hostname)];
-    for (const entry of hostEntries) {
-        if (!entry)
-            continue;
-        const parsed = parseEndpoint(entry);
-        if (parsed.hostname) {
-            const port = firstDefined(configuredPort(config.port), parsed.port) ?? DEFAULT_C64U_PORT;
-            return buildBaseUrl(parsed.hostname, port);
-        }
-    }
-    return buildBaseUrl(DEFAULT_C64U_HOST, DEFAULT_C64U_PORT);
-}
 function configuredString(value) {
     if (typeof value === "string") {
         const trimmed = value.trim();
@@ -1188,42 +1343,9 @@ function configuredPort(value) {
     }
     return undefined;
 }
-function normaliseBaseUrl(value) {
-    const input = configuredString(value);
-    if (!input)
-        return undefined;
-    if (!/^[a-z][a-z0-9+.-]*:\/\//i.test(input)) {
-        return `http://${input}`;
-    }
-    return stripTrailingSlash(input);
-}
-function parseEndpoint(value) {
-    try {
-        const hasScheme = /^[a-z][a-z0-9+.-]*:\/\//i.test(value);
-        const url = new URL(hasScheme ? value : `http://${value}`);
-        const hostname = url.hostname || undefined;
-        const port = url.port ? configuredPort(url.port) : undefined;
-        return { hostname, port };
-    }
-    catch {
-        return {};
-    }
-}
-function buildBaseUrl(host, port) {
-    const normalizedPort = Number.isInteger(port) && port > 0 ? port : DEFAULT_C64U_PORT;
-    const hostPart = formatHost(host);
-    const suffix = normalizedPort === DEFAULT_C64U_PORT ? "" : `:${normalizedPort}`;
-    return `http://${hostPart}${suffix}`;
-}
 function buildC64uHeaders(networkPassword) {
     return networkPassword ? { "X-Password": networkPassword } : undefined;
 }
-function formatHost(host) {
-    return host.includes(":") && !host.startsWith("[") ? `[${host}]` : host;
-}
-function stripTrailingSlash(input) {
-    return input.replace(/\/+$/, "");
-}
 function parseArgsList(input) {
     const args = [];
     const pattern = /"([^"\\]*(?:\\.[^"\\]*)*)"|'([^'\\]*(?:\\.[^'\\]*)*)'|(\S+)/g;

package/dist/diagnostics.js

@@ -137,8 +137,16 @@ export function readDiagnosticRecords(filePath) {
     if (!text) {
         return [];
     }
-    return text.split("\n")
-        .map((line) => JSON.parse(line));
+    // The file is appended while the server runs, so a crash or a concurrent
+    // read can leave a partial last line; skip lines that are not whole records.
+    return text.split("\n").flatMap((line) => {
+        try {
+            return [JSON.parse(line)];
+        }
+        catch {
+            return [];
+        }
+    });
 }
 export function summarizeDiagnosticsSession(filePath, options = {}) {
     const records = readDiagnosticRecords(filePath);

package/dist/knowledge.js

@@ -41,7 +41,8 @@ export function formatAddress(address) {
 }
 export function resolveAddressSymbol(input) {
     const key = input.trim().toLowerCase().replace(/\s+/g, "_");
-    return SYMBOLS[key];
+    // Own keys only, so "constructor" or "toString" are not mistaken for symbols.
+    return Object.prototype.hasOwnProperty.call(SYMBOLS, key) ? SYMBOLS[key] : undefined;
 }
 export function listSymbols() {
     return Object.entries(SYMBOLS)

package/dist/mcp-server.js

@@ -449,7 +449,7 @@ async function main() {
         writeDiagnosticEvent("mcp_transport_connected", { mode: "stdio" });
         console.error("c64bridge MCP server running on stdio");
     }
-    await logConnectivity(client, baseUrl);
+    await logConnectivity(client, baseUrl, config.networkPassword);
     writeDiagnosticEvent("server_ready", {
         diagnosticsFile: diagnostics.filePath,
     });
@@ -524,7 +524,11 @@ export async function renderPlatformStatusMarkdown(client) {
     lines.push("> Use `c64_select_backend` to switch to another available backend without restarting the MCP server.");
     return lines.join("\n");
 }
-async function logConnectivity(client, baseUrl) {
+/** URL of the Ultimate's /v1/info route, keeping any path prefix of the base URL (reverse proxy). */
+export function connectivityProbeUrl(baseUrl) {
+    return `${baseUrl.replace(/\/+$/, "")}/v1/info`;
+}
+async function logConnectivity(client, baseUrl, networkPassword) {
     const backendType = await client.getBackendType();
     if (backendType === "vice") {
         writeDiagnosticEvent("connectivity_probe_skipped", { baseUrl, reason: "vice_backend" });
@@ -550,10 +554,14 @@ async function logConnectivity(client, baseUrl) {
     }
     const c64Logger = loggerFor("c64u");
     const startedAt = Date.now();
-    const infoUrl = new URL("/v1/info", baseUrl).toString();
+    const infoUrl = connectivityProbeUrl(baseUrl);
     let response = null;
     try {
-        const probeResponse = await axios.get(infoUrl, { timeout: 2000 });
+        // Send the network password like every other request, or a protected device answers 403.
+        const probeResponse = await axios.get(infoUrl, {
+            timeout: 2000,
+            ...(networkPassword ? { headers: { "X-Password": networkPassword } } : {}),
+        });
         response = probeResponse;
         const latency = Date.now() - startedAt;
         const bytes = payloadByteLength(probeResponse.data);