c64bridge 1.0.4 → 1.0.6

package/dist/tools/audio.js

@@ -1,5 +1,5 @@
 import { compileSidwaveToPrg, compileSidwaveToSid } from "../sidwaveCompiler.js";
-import { parseSidwave } from "../sidwave.js";
+import { midiToHz, noteNameToMidi, parseSidwave } from "../sidwave.js";
 import { recordAndAnalyzeAudio } from "../audio/record_and_analyze_audio.js";
 import { defineToolModule } from "./types.js";
 import { booleanSchema, numberSchema, objectSchema, optionalSchema, stringSchema, } from "./schema.js";
@@ -11,6 +11,7 @@ const DEFAULT_SILENCE_VERIFY_DURATION_SECONDS = 1.5;
 const DEFAULT_SILENCE_VERIFY_RMS_THRESHOLD = 0.02;
 const DEFAULT_SILENCE_VERIFY_WAIT_MS = 150;
 const generatedPlaybacks = new Set();
+let lastGeneratedPlayback = Promise.resolve();
 export function cancelGeneratedSidPlayback() {
     for (const controller of generatedPlaybacks)
         controller.abort();
@@ -317,8 +318,35 @@ function transposeNote(note, semitones) {
     const newOctave = Math.floor(midi / 12) - 1;
     return `${names[wrapped]}${newOctave}`;
 }
-function sleep(ms) {
-    return new Promise((resolve) => setTimeout(resolve, ms));
+/** Highest frequency the SID's 16-bit frequency register can produce (about 3848 Hz PAL, 3995 Hz NTSC). */
+function maxSidFrequencyHz(system) {
+    return (0xffff * (system === "PAL" ? 985248 : 1022727)) / 16777216;
+}
+/** Reject a note or frequency the SID cannot play instead of letting playback clamp or skip it. */
+function assertPlayableFrequency(hz, label, system, path) {
+    const max = maxSidFrequencyHz(system);
+    if (hz > max + 0.5) {
+        throw new ToolValidationError(`${label} (${hz.toFixed(1)} Hz) is above the SID's highest ${system} frequency of ${max.toFixed(1)} Hz`, { path });
+    }
+}
+function noteHz(note) {
+    const midi = noteNameToMidi(note);
+    return midi === undefined ? Number.NaN : midiToHz(midi);
+}
+function sleep(ms, signal) {
+    return new Promise((resolve) => {
+        if (signal?.aborted) {
+            resolve();
+            return;
+        }
+        const timer = setTimeout(done, ms);
+        function done() {
+            clearTimeout(timer);
+            signal?.removeEventListener("abort", done);
+            resolve();
+        }
+        signal?.addEventListener("abort", done, { once: true });
+    });
 }
 function shouldAutoAnalyze(request) {
     const lowered = request.toLowerCase();
@@ -334,6 +362,28 @@ function resolveAnalyzer(ctx) {
     }
     return (options) => recordAndAnalyzeAudio(options);
 }
+/**
+ * Measure whether the SID is silent by capturing audio (the Ultimate audio
+ * stream on C64U, otherwise the host microphone). The SID's control registers
+ * are write-only, so reading them back cannot show whether a voice sounds.
+ */
+export async function measureSidSilence(ctx) {
+    if (DEFAULT_SILENCE_VERIFY_WAIT_MS > 0) {
+        await sleep(DEFAULT_SILENCE_VERIFY_WAIT_MS);
+    }
+    const analysis = await resolveAnalyzer(ctx)({ durationSeconds: DEFAULT_SILENCE_VERIFY_DURATION_SECONDS });
+    const { average, max } = extractRmsMetrics((analysis?.analysis?.global_metrics ?? {}));
+    if (average === null && max === null) {
+        throw new ToolExecutionError("Audio analysis did not provide RMS metrics for silence verification");
+    }
+    const maxRms = max ?? average ?? 0;
+    return {
+        silent: maxRms <= DEFAULT_SILENCE_VERIFY_RMS_THRESHOLD,
+        averageRms: average ?? maxRms,
+        maxRms,
+        threshold: DEFAULT_SILENCE_VERIFY_RMS_THRESHOLD,
+    };
+}
 function extractRmsMetrics(globalMetrics) {
     const average = typeof globalMetrics.average_rms === "number" ? globalMetrics.average_rms : null;
     const max = typeof globalMetrics.max_rms === "number" ? globalMetrics.max_rms : null;
@@ -440,7 +490,7 @@ export const audioModule = defineToolModule({
                     });
                     const result = await ctx.client.sidSetVolume(parsed.volume);
                     if (!result.success) {
-                        throw new ToolExecutionError("C64 firmware reported failure while setting SID volume", {
+                        throw new ToolExecutionError("C64 backend reported failure while setting SID volume", {
                             details: normaliseFailure(result.details),
                         });
                     }
@@ -483,7 +533,7 @@ export const audioModule = defineToolModule({
                     cancelGeneratedSidPlayback(); // Reset is the documented way to stop a generated arpeggio.
                     const result = await ctx.client.sidReset(parsed.hard);
                     if (!result.success) {
-                        throw new ToolExecutionError("C64 firmware reported failure while resetting SID", {
+                        throw new ToolExecutionError("C64 backend reported failure while resetting SID", {
                             details: normaliseFailure(result.details),
                         });
                     }
@@ -520,6 +570,13 @@ export const audioModule = defineToolModule({
                 try {
                     const parsed = sidNoteOnArgsSchema.parse(args ?? {});
                     const voice = Math.max(1, Math.min(3, Math.floor(parsed.voice ?? 1)));
+                    const system = (parsed.system ?? "PAL");
+                    if (parsed.note) {
+                        assertPlayableFrequency(noteHz(parsed.note), parsed.note, system, "$.note");
+                    }
+                    else if (parsed.frequencyHz !== undefined) {
+                        assertPlayableFrequency(parsed.frequencyHz, `${parsed.frequencyHz} Hz`, system, "$.frequencyHz");
+                    }
                     ctx.logger.info("Starting SID voice", {
                         voice,
                         note: parsed.note ?? null,
@@ -539,7 +596,7 @@ export const audioModule = defineToolModule({
                         release: parsed.release,
                     });
                     if (!result.success) {
-                        throw new ToolExecutionError("C64 firmware reported failure while starting SID voice", {
+                        throw new ToolExecutionError("C64 backend reported failure while starting SID voice", {
                             details: normaliseFailure(result.details),
                         });
                     }
@@ -593,7 +650,7 @@ export const audioModule = defineToolModule({
                     ctx.logger.info("Stopping SID voice", { voice });
                     const result = await ctx.client.sidNoteOff(voice);
                     if (!result.success) {
-                        throw new ToolExecutionError("C64 firmware reported failure while stopping SID voice", {
+                        throw new ToolExecutionError("C64 backend reported failure while stopping SID voice", {
                             details: normaliseFailure(result.details),
                         });
                     }
@@ -633,7 +690,7 @@ export const audioModule = defineToolModule({
                     cancelGeneratedSidPlayback(); // Otherwise its remaining notes would resume writing right after this silences the chip.
                     const result = await ctx.client.sidSilenceAll();
                     if (!result.success) {
-                        throw new ToolExecutionError("C64 firmware reported failure while silencing SID", {
+                        throw new ToolExecutionError("C64 backend reported failure while silencing SID", {
                             details: normaliseFailure(result.details),
                         });
                     }
@@ -724,7 +781,7 @@ export const audioModule = defineToolModule({
                     ctx.logger.info("Playing SID file", { path: parsed.path, songnr: parsed.songnr ?? null });
                     const result = await ctx.client.sidplayFile(parsed.path, parsed.songnr);
                     if (!result.success) {
-                        throw new ToolExecutionError("C64 firmware reported failure while starting SID playback", {
+                        throw new ToolExecutionError("C64 backend reported failure while starting SID playback", {
                             details: normaliseFailure(result.details),
                         });
                     }
@@ -764,7 +821,7 @@ export const audioModule = defineToolModule({
                     ctx.logger.info("Playing MOD file", { path: parsed.path });
                     const result = await ctx.client.modplayFile(parsed.path);
                     if (!result.success) {
-                        throw new ToolExecutionError("C64 firmware reported failure while starting MOD playback", {
+                        throw new ToolExecutionError("C64 backend reported failure while starting MOD playback", {
                             details: normaliseFailure(result.details),
                         });
                     }
@@ -811,6 +868,8 @@ export const audioModule = defineToolModule({
                         const iv = intervals[i % intervals.length];
                         const note = transposeNote(parsed.root, iv);
                         const durationMs = parsed.preset === "expression" ? expressiveDurations[i % expressiveDurations.length] : parsed.tempoMs;
+                        // Playback runs in the background, so a note the SID cannot play must be rejected here.
+                        assertPlayableFrequency(noteHz(note), note, "PAL", "$.root");
                         timeline.push({ t: timestamp, note, durationMs });
                         timestamp += durationMs;
                     }
@@ -825,8 +884,12 @@ export const audioModule = defineToolModule({
                     const controller = new AbortController();
                     generatedPlaybacks.add(controller);
                     const pinnedFacadePromise = ctx.client.pinFacade ? ctx.client.pinFacade() : Promise.resolve(undefined); // Pin once so a later select_backend can't retarget notes mid-arpeggio (HARD01-030).
-                    void (async () => {
+                    // A replaced sequence sends its final gate-off on voice 1; waiting for it
+                    // keeps that gate-off from cutting off this sequence's first note.
+                    const previousPlayback = lastGeneratedPlayback;
+                    lastGeneratedPlayback = (async () => {
                         try {
+                            await previousPlayback;
                             const pinnedFacade = await pinnedFacadePromise;
                             await ctx.client.sidSetVolume(8, pinnedFacade);
                             for (let i = 0; i < parsed.steps; i += 1) {
@@ -845,10 +908,14 @@ export const audioModule = defineToolModule({
                                     release: 0,
                                 }, pinnedFacade);
                                 const durationMs = parsed.preset === "expression" ? expressiveDurations[i % expressiveDurations.length] : parsed.tempoMs;
-                                await sleep(Math.max(1, Math.min(20, Math.floor(durationMs / 8)))); // Clear GATE between notes so every note retriggers ADSR.
+                                // Hold GATE for most of the note, then clear it for a short gap so the next note retriggers ADSR.
+                                const gateGapMs = Math.max(1, Math.min(20, Math.floor(durationMs / 8)));
+                                // Cancellation ends the sleep at once, so the final gate-off below follows promptly.
+                                await sleep(Math.max(0, durationMs - gateGapMs), controller.signal);
+                                if (controller.signal.aborted)
+                                    break;
                                 await ctx.client.sidNoteOff(1, pinnedFacade);
-                                if (!controller.signal.aborted)
-                                    await sleep(Math.max(0, durationMs - Math.max(1, Math.min(20, Math.floor(durationMs / 8)))));
+                                await sleep(gateGapMs, controller.signal);
                             }
                             await ctx.client.sidNoteOff(1, pinnedFacade);
                         }
@@ -889,7 +956,15 @@ export const audioModule = defineToolModule({
             tags: ["sid", "music", "compiler"],
             prerequisites: [],
             examples: [
-                { name: "Compile PRG", description: "Play compiled PRG", arguments: { sidwave: "song: { title: 'Demo' }", output: "prg", dryRun: false } },
+                {
+                    name: "Compile PRG",
+                    description: "Play compiled PRG",
+                    arguments: {
+                        sidwave: "sidwave: 1.0\ntitle: Demo\ntempo: 120\nmode: PAL\nvoices:\n  - id: 1\n    waveform: triangle\n    patterns: { A: { groove: [C4, E4, G4, C5] } }\ntimeline:\n  - { bars: 2, layers: { v1: A } }\n",
+                        output: "prg",
+                        dryRun: false,
+                    },
+                },
             ],
             workflowHints: [
                 "Use when the user provides SIDWAVE/CPG scores or asks for export to PRG/SID; share any generated download URIs in your response.",
@@ -920,7 +995,7 @@ export const audioModule = defineToolModule({
                             const sid = compileSidwaveToSid(document, compiled.prg, { entryAddress: compiled.entryAddress });
                             const result = await ctx.client.sidplayAttachment(sid.sid);
                             if (!result.success) {
-                                throw new ToolExecutionError("C64 firmware reported failure while playing compiled SID", {
+                                throw new ToolExecutionError("C64 backend reported failure while playing compiled SID", {
                                     details: normaliseFailure(result.details),
                                 });
                             }
@@ -930,7 +1005,7 @@ export const audioModule = defineToolModule({
                         else {
                             const result = await ctx.client.runPrg(compiled.prg);
                             if (!result.success) {
-                                throw new ToolExecutionError("C64 firmware reported failure while running compiled PRG", {
+                                throw new ToolExecutionError("C64 backend reported failure while running compiled PRG", {
                                     details: normaliseFailure(result.details),
                                 });
                             }
@@ -946,13 +1021,17 @@ export const audioModule = defineToolModule({
                         pulse_width: voice.pulse_width,
                         adsr: voice.adsr,
                     }));
-                    return textResult(message, {
+                    // Warnings (for example a PRG that leaves no room for BASIC) go into the text that clients show.
+                    const warningText = compiled.warnings.length > 0 ? `\nWarning: ${compiled.warnings.join("\nWarning: ")}` : "";
+                    return textResult(`${message}${warningText}`, {
                         success: true,
                         ranOnC64,
                         dryRun: parsed.dryRun,
                         format: outputFormat,
                         prgSize: compiled.prg.length,
                         entryAddress: compiled.entryAddress,
+                        basicFreeBytes: compiled.basicFreeBytes,
+                        warnings: compiled.warnings,
                         song: document.song,
                         voices: voiceSummaries,
                         runDetails,

package/dist/tools/debug.js

@@ -572,17 +572,17 @@ function formatAddress(value) {
 }
 function parseAddress(value, label) {
     const trimmed = value.trim();
-    let radix = 10;
-    let literal = trimmed;
-    if (trimmed.startsWith("$")) {
-        radix = 16;
-        literal = trimmed.slice(1);
+    // Anchored patterns: Number.parseInt alone would read "$08G0" as $0008.
+    let parsed = Number.NaN;
+    if (/^\$[0-9a-f]+$/i.test(trimmed)) {
+        parsed = Number.parseInt(trimmed.slice(1), 16);
     }
-    else if (trimmed.toLowerCase().startsWith("0x")) {
-        radix = 16;
-        literal = trimmed.slice(2);
+    else if (/^0x[0-9a-f]+$/i.test(trimmed)) {
+        parsed = Number.parseInt(trimmed.slice(2), 16);
+    }
+    else if (/^[0-9]+$/.test(trimmed)) {
+        parsed = Number.parseInt(trimmed, 10);
     }
-    const parsed = Number.parseInt(literal, radix);
     if (!Number.isInteger(parsed) || parsed < 0 || parsed > 0xffff) {
         throw new ToolValidationError(`Invalid ${label}`, { path: `$.${label}` });
     }

package/dist/tools/developer.js

@@ -229,7 +229,7 @@ export const developerModule = defineToolModule({
                     });
                     const result = await ctx.client.configSet(parsed.category, parsed.item, String(parsed.value));
                     if (!result.success) {
-                        throw new ToolExecutionError("C64 firmware reported failure while updating configuration", {
+                        throw new ToolExecutionError("C64 backend reported failure while updating configuration", {
                             details: toRecord(result.details),
                         });
                     }
@@ -275,7 +275,7 @@ export const developerModule = defineToolModule({
                     ]));
                     const result = await ctx.client.configBatchUpdate(requestPayload);
                     if (!result.success) {
-                        throw new ToolExecutionError("C64 firmware reported failure during batch configuration update", {
+                        throw new ToolExecutionError("C64 backend reported failure during batch configuration update", {
                             details: toRecord(result.details),
                         });
                     }
@@ -312,7 +312,7 @@ export const developerModule = defineToolModule({
                     ctx.logger.info("Loading configuration from flash");
                     const result = await ctx.client.configLoadFromFlash();
                     if (!result.success) {
-                        throw new ToolExecutionError("C64 firmware reported failure while loading from flash", {
+                        throw new ToolExecutionError("C64 backend reported failure while loading from flash", {
                             details: toRecord(result.details),
                         });
                     }
@@ -348,7 +348,7 @@ export const developerModule = defineToolModule({
                     ctx.logger.info("Saving configuration to flash");
                     const result = await ctx.client.configSaveToFlash();
                     if (!result.success) {
-                        throw new ToolExecutionError("C64 firmware reported failure while saving to flash", {
+                        throw new ToolExecutionError("C64 backend reported failure while saving to flash", {
                             details: toRecord(result.details),
                         });
                     }
@@ -384,7 +384,7 @@ export const developerModule = defineToolModule({
                     ctx.logger.info("Resetting configuration to defaults");
                     const result = await ctx.client.configResetToDefault();
                     if (!result.success) {
-                        throw new ToolExecutionError("C64 firmware reported failure while resetting configuration", {
+                        throw new ToolExecutionError("C64 backend reported failure while resetting configuration", {
                             details: toRecord(result.details),
                         });
                     }
@@ -484,7 +484,7 @@ export const developerModule = defineToolModule({
                     ctx.logger.info("Reading debug register");
                     const result = await ctx.client.debugregRead();
                     if (!result.success) {
-                        throw new ToolExecutionError("C64 firmware reported failure while reading debug register", {
+                        throw new ToolExecutionError("C64 backend reported failure while reading debug register", {
                             details: toRecord(result.details),
                         });
                     }
@@ -524,7 +524,7 @@ export const developerModule = defineToolModule({
                     ctx.logger.info("Writing debug register", { value });
                     const result = await ctx.client.debugregWrite(value);
                     if (!result.success) {
-                        throw new ToolExecutionError("C64 firmware reported failure while writing debug register", {
+                        throw new ToolExecutionError("C64 backend reported failure while writing debug register", {
                             details: toRecord(result.details),
                         });
                     }

package/dist/tools/errors.js

@@ -44,14 +44,32 @@ export function toolErrorResult(error) {
         ...(error.code !== undefined ? { code: error.code } : {}),
         ...(error.details !== undefined ? { details: error.details } : {}),
     };
-    const message = error.path ? `${error.message} (at ${error.path})` : error.message;
+    const located = error.path ? `${error.message} (at ${error.path})` : error.message;
+    // Clients often show only the text content, so surface the underlying cause
+    // (for example a range check or firmware error string) next to the summary.
+    const detailMessage = describeDetailMessage(error.details);
+    const message = detailMessage && !located.includes(detailMessage) ? `${located}: ${detailMessage}` : located;
     const base = textResult(message, { error: metadata });
     return { ...base, isError: true };
 }
+function describeDetailMessage(details) {
+    if (!details || typeof details !== "object") {
+        return undefined;
+    }
+    const message = details.message;
+    return typeof message === "string" && message.trim().length > 0 ? message.trim() : undefined;
+}
 export function unknownErrorResult(error) {
     if (error instanceof ToolError) {
         return toolErrorResult(error);
     }
+    // Input documents such as SIDWAVE scores are checked outside the tool schemas;
+    // their errors carry a path and are input errors, not internal failures.
+    if (error instanceof Error && error.name === "SidwaveValidationError") {
+        const path = error.path;
+        const metadata = { kind: "validation", ...(typeof path === "string" ? { path } : {}) };
+        return { ...textResult(error.message, { error: metadata }), isError: true };
+    }
     const metadata = { kind: "unknown" };
     const message = error instanceof Error ? error.message : String(error);
     const base = textResult(message, { error: metadata });

package/dist/tools/graphics.js

@@ -349,7 +349,7 @@ async function executeGenerateSprite(rawArgs, ctx) {
             multicolour: parsed.multicolour,
         });
         if (!result.success) {
-            throw new ToolExecutionError("C64 firmware reported failure while rendering sprite", {
+            throw new ToolExecutionError("C64 backend reported failure while rendering sprite", {
                 details: normaliseFailure(result.details),
             });
         }
@@ -383,7 +383,7 @@ async function executeRenderPetscii(rawArgs, ctx) {
         });
         const result = await ctx.client.renderPetsciiScreenAndRun(parsed);
         if (!result.success) {
-            throw new ToolExecutionError("C64 firmware reported failure while rendering PETSCII text", {
+            throw new ToolExecutionError("C64 backend reported failure while rendering PETSCII text", {
                 details: normaliseFailure(result.details),
             });
         }
@@ -426,7 +426,7 @@ async function executeGenerateBitmap(rawArgs, ctx) {
             screenAddress: parsed.screenAddress,
         });
         if (!result.success) {
-            throw new ToolExecutionError("C64 firmware reported failure while displaying bitmap image", {
+            throw new ToolExecutionError("C64 backend reported failure while displaying bitmap image", {
                 details: normaliseFailure(result.details),
             });
         }
@@ -498,7 +498,7 @@ async function executeCreatePetscii(rawArgs, ctx) {
         if (!parsed.dryRun) {
             runResult = await ctx.client.uploadAndRunBasic(art.program);
             if (!runResult.success) {
-                throw new ToolExecutionError("C64 firmware reported failure while rendering PETSCII art", {
+                throw new ToolExecutionError("C64 backend reported failure while rendering PETSCII art", {
                     details: normaliseFailure(runResult.details),
                 });
             }

package/dist/tools/hex.js

@@ -0,0 +1,9 @@
+/**
+ * Normalise a user-supplied hex byte string such as "$A9 $00", "A9_00" or
+ * "$A900" to bare hex digits. A "$" may prefix the whole string or each
+ * whitespace-separated byte group; whitespace and "_" separators are removed.
+ * The result is not validated, so callers still check length and digits.
+ */
+export function stripHexByteSeparators(input) {
+    return input.trim().replace(/(^|\s)\$/g, "$1").replace(/[\s_]/g, "");
+}

package/dist/tools/input.js

@@ -57,36 +57,40 @@ const PETSCII_TOKENS = {
     LIGHT_GREY: 155,
     REVERSE_ON: 18,
     REVERSE_OFF: 146,
-    FLASH_ON: 130,
-    FLASH_OFF: 148,
+    // FLASH ON/OFF, ESC and TAB are C128 codes: on a C64, 148 is INST (inserts a
+    // space) and 9 re-enables SHIFT+C= case switching, so they are not offered.
     LOWERCASE: 14,
     UPPERCASE: 142,
-    ESCAPE: 27,
-    TAB: 9,
     CURSOR_UP: 145,
     CURSOR_DOWN: 17,
     CURSOR_LEFT: 157,
     CURSOR_RIGHT: 29,
 };
+// ASCII a-z are shifted graphics characters in PETSCII, so typed "print" would
+// reach BASIC as graphics and give ?SYNTAX ERROR. Literal letters are therefore
+// sent as the unshifted PETSCII letters $41-$5A; {tokens} keep their codes.
 function expandPetsciiTokens(text) {
-    return text.replace(/\{([^}]+)\}/g, (_match, token) => {
+    return text.replace(/\{([^}]+)\}|[a-z]/g, (_match, token) => {
+        if (token === undefined) {
+            return _match.toUpperCase();
+        }
         const upper = token.trim().toUpperCase();
         const code = PETSCII_TOKENS[upper];
         if (code !== undefined) {
             return String.fromCharCode(code);
         }
-        // Numeric form: {$1D} or {29}
-        let num;
-        if (upper.startsWith("$")) {
+        // Numeric form: {$1D} or {29}. Anchored, so {12AB} is not read as {12}.
+        let num = NaN;
+        if (/^\$[0-9A-F]{1,2}$/.test(upper)) {
             num = parseInt(upper.slice(1), 16);
         }
-        else {
+        else if (/^\d{1,3}$/.test(upper)) {
             num = parseInt(upper, 10);
         }
         if (!isNaN(num) && num >= 0 && num <= 255) {
             return String.fromCharCode(num);
         }
-        return _match; // leave unrecognised tokens as-is
+        return _match.toUpperCase(); // type unrecognised tokens literally
     });
 }
 // ---------------------------------------------------------------------------
@@ -170,7 +174,7 @@ export const keyArgsSchema = objectSchema({
     additionalProperties: false,
 });
 export const joystickArgsSchema = objectSchema({
-    description: "Simulate joystick input. On C64U/U64 this uses machine:input; VICE uses Binary Monitor Joyport Set.",
+    description: "Simulate joystick input. On C64U/U64 this uses machine:input. On VICE it attaches VICE's I/O simulation joyport device while pressed; that device also pulls CIA lines 5-7 low, so port 1 produces phantom keys (e.g. SHIFT+C=) and port 2 reads $1E for up instead of $7E. Prefer port 2 on VICE and test bits 0-4.",
     properties: {
         op: literalSchema("joystick"),
         port: numberSchema({
@@ -266,7 +270,7 @@ const inputOperationHandlers = {
             const keyByte = tokenCode !== undefined
                 ? tokenCode
                 : parsed.key.length === 1
-                    ? parsed.key.charCodeAt(0) & 0xff
+                    ? parsed.key.toUpperCase().charCodeAt(0) & 0xff
                     : (() => {
                         throw new ToolValidationError(`Unrecognised key: ${parsed.key}. Use a single character or a PETSCII token name.`, { path: "$.key" });
                     })();
@@ -291,7 +295,6 @@ const inputOperationHandlers = {
             const port = parsed.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") {
@@ -309,19 +312,19 @@ const inputOperationHandlers = {
                 throw new ToolValidationError("VICE joystick supports up, down, left, right, and fire only.", { path: "$.controls" });
             }
             if (parsed.action === "release") {
-                await ctx.client.viceJoyportSet(port, releasedByte);
+                await ctx.client.viceJoystickRelease(port);
                 ctx.logger.info("Released joystick", { port });
                 return textResult(`Joystick port ${port} released.`, { success: true, port, action: "release" });
             }
             if (parsed.action === "press") {
-                await ctx.client.viceJoyportSet(port, pressedByte);
+                await ctx.client.viceJoystickPress(port, pressedByte);
                 ctx.logger.info("Pressed joystick", { port, controls: parsed.controls, byte: pressedByte });
-                return textResult(`Joystick port ${port} pressed: ${parsed.controls.join(", ") || "none"}.`, { success: true, port, action: "press", controls: parsed.controls });
+                return textResult(`Joystick port ${port} pressed: ${parsed.controls.join(", ") || "none"}.${port === 1 ? " On VICE, port 1 also shows phantom keys while held." : ""}`, { success: true, port, action: "press", controls: parsed.controls });
             }
             // tap: press → wait → release
-            await ctx.client.viceJoyportSet(port, pressedByte);
+            await ctx.client.viceJoystickPress(port, pressedByte);
             await new Promise((res) => setTimeout(res, durationMs));
-            await ctx.client.viceJoyportSet(port, releasedByte);
+            await ctx.client.viceJoystickRelease(port);
             ctx.logger.info("Tapped joystick", { port, controls: parsed.controls, durationMs });
             return textResult(`Joystick port ${port} tapped: ${parsed.controls.join(", ") || "none"} for ${durationMs}ms.`, { success: true, port, action: "tap", controls: parsed.controls, durationMs });
         }

package/dist/tools/machineControl.js

@@ -70,7 +70,7 @@ export const machineControlModule = defineToolModule({
                     ctx.logger.info("Resetting C64");
                     const result = await ctx.client.reset();
                     if (!result.success) {
-                        throw new ToolExecutionError("C64 firmware reported failure while resetting", {
+                        throw new ToolExecutionError("C64 backend reported failure while resetting", {
                             details: normaliseFailure(result.details),
                         });
                     }
@@ -108,7 +108,7 @@ export const machineControlModule = defineToolModule({
                     ctx.logger.info("Rebooting C64");
                     const result = await ctx.client.reboot();
                     if (!result.success) {
-                        throw new ToolExecutionError("C64 firmware reported failure while rebooting", {
+                        throw new ToolExecutionError("C64 backend reported failure while rebooting", {
                             details: normaliseFailure(result.details),
                         });
                     }
@@ -146,7 +146,7 @@ export const machineControlModule = defineToolModule({
                     ctx.logger.info("Pausing C64 execution");
                     const result = await ctx.client.pause();
                     if (!result.success) {
-                        throw new ToolExecutionError("C64 firmware reported failure while pausing", {
+                        throw new ToolExecutionError("C64 backend reported failure while pausing", {
                             details: normaliseFailure(result.details),
                         });
                     }
@@ -184,7 +184,7 @@ export const machineControlModule = defineToolModule({
                     ctx.logger.info("Resuming C64 execution");
                     const result = await ctx.client.resume();
                     if (!result.success) {
-                        throw new ToolExecutionError("C64 firmware reported failure while resuming", {
+                        throw new ToolExecutionError("C64 backend reported failure while resuming", {
                             details: normaliseFailure(result.details),
                         });
                     }
@@ -222,7 +222,7 @@ export const machineControlModule = defineToolModule({
                     ctx.logger.info("Powering off C64");
                     const result = await ctx.client.poweroff();
                     if (!result.success) {
-                        throw new ToolExecutionError("C64 firmware reported failure while powering off", {
+                        throw new ToolExecutionError("C64 backend reported failure while powering off", {
                             details: normaliseFailure(result.details),
                         });
                     }
@@ -295,7 +295,7 @@ export const machineControlModule = defineToolModule({
                     ctx.logger.info("Toggling Ultimate menu button");
                     const result = await ctx.client.menuButton();
                     if (!result.success) {
-                        throw new ToolExecutionError("C64 firmware reported failure while toggling menu button", {
+                        throw new ToolExecutionError("C64 backend reported failure while toggling menu button", {
                             details: normaliseFailure(result.details),
                         });
                     }