c64bridge 1.0.5 → 1.0.7

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";
@@ -318,6 +318,21 @@ function transposeNote(note, semitones) {
     const newOctave = Math.floor(midi / 12) - 1;
     return `${names[wrapped]}${newOctave}`;
 }
+/** 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) {
@@ -347,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;
@@ -453,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),
                         });
                     }
@@ -496,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),
                         });
                     }
@@ -533,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,
@@ -552,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),
                         });
                     }
@@ -606,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),
                         });
                     }
@@ -646,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),
                         });
                     }
@@ -737,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),
                         });
                     }
@@ -777,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),
                         });
                     }
@@ -824,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;
                     }
@@ -910,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.",
@@ -941,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),
                                 });
                             }
@@ -951,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),
                                 });
                             }
@@ -967,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/developer.js

@@ -1,6 +1,7 @@
 import { defineToolModule } from "./types.js";
-import { objectSchema, optionalSchema, stringSchema, } from "./schema.js";
+import { booleanSchema, objectSchema, optionalSchema, stringSchema, } from "./schema.js";
 import { jsonResult, textResult } from "./responses.js";
+import { redactConfigValue } from "../redact.js";
 import { ToolError, ToolExecutionError, ToolValidationError, toolErrorResult, unknownErrorResult, } from "./errors.js";
 function toRecord(details) {
     if (details === undefined || details === null) {
@@ -61,6 +62,10 @@ const configGetArgsSchema = objectSchema({
     properties: {
         category: categorySchema,
         item: itemSchema,
+        includeSecretValues: optionalSchema(booleanSchema({
+            description: "Return credential values (network password, FTP/Telnet passwords, Wi-Fi keys) in plain text. Default false: those values are replaced with ***.",
+            default: false,
+        }), false),
     },
     required: ["category"],
     additionalProperties: false,
@@ -190,7 +195,10 @@ export const developerModule = defineToolModule({
                         category: parsed.category,
                         item: parsed.item ?? null,
                     });
-                    const details = await ctx.client.configGet(parsed.category, parsed.item);
+                    const raw = await ctx.client.configGet(parsed.category, parsed.item);
+                    const details = parsed.includeSecretValues === true
+                        ? raw
+                        : redactConfigValue(raw, parsed.category, parsed.item);
                     return withStructuredJson({ value: details }, {
                         success: true,
                         category: parsed.category,
@@ -229,7 +237,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 +283,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 +320,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 +356,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 +392,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 +492,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 +532,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

@@ -63,6 +63,13 @@ 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/input.js

@@ -1,7 +1,7 @@
 import { createOperationDispatcher, defineToolModule, discriminatedUnionSchema, } from "./types.js";
 import { arraySchema, literalSchema, numberSchema, objectSchema, optionalSchema, stringSchema, } from "./schema.js";
 import { jsonResult, textResult } from "./responses.js";
-import { ToolValidationError, toolErrorResult, unknownErrorResult, } from "./errors.js";
+import { ToolExecutionError, ToolValidationError, toolErrorResult, unknownErrorResult, } from "./errors.js";
 function isMissingNativeInputEndpoint(error) {
     return typeof error === "object"
         && error !== null
@@ -9,7 +9,7 @@ function isMissingNativeInputEndpoint(error) {
         && error.response?.status === 404;
 }
 function nativeInputUnavailableResult(operation) {
-    return textResult(`Native physical input is unavailable on this firmware, so ${operation} was not sent. Use c64://platform/status before choosing native input; use key or write_text for ordinary C64 input.`, { success: false, code: "native_input_unavailable", fallback: "key_or_write_text" });
+    return toolErrorResult(new ToolExecutionError(`Native physical input is unavailable on this firmware, so ${operation} was not sent. Use c64://platform/status before choosing native input; use key or write_text for ordinary C64 input.`, { code: "native_input_unavailable", details: { fallback: "key_or_write_text" } }));
 }
 // ---------------------------------------------------------------------------
 // PETSCII token expansion table
@@ -57,12 +57,10 @@ 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,
@@ -176,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({
@@ -297,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") {
@@ -315,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),
                         });
                     }
@@ -342,7 +342,7 @@ export const machineControlModule = defineToolModule({
                     if (error instanceof ToolError)
                         return toolErrorResult(error);
                     if (isMissingMenuScreenEndpoint(error)) {
-                        return textResult("No menu matrix is available. Open the Ultimate menu and retry; if it remains unavailable, this firmware does not provide machine:menu_screen. Use REST configuration instead of menu navigation where possible.", { success: false, code: "native_menu_screen_unavailable", fallback: "rest_configuration_or_manual_menu" });
+                        return toolErrorResult(new ToolExecutionError("No menu matrix is available. Open the Ultimate menu and retry; if it remains unavailable, this firmware does not provide machine:menu_screen. Use REST configuration instead of menu navigation where possible.", { code: "native_menu_screen_unavailable", details: { fallback: "rest_configuration_or_manual_menu" }, cause: error }));
                     }
                     return unknownErrorResult(error);
                 }

package/dist/tools/memory.js

@@ -186,7 +186,7 @@ async function executeReadMemory(rawArgs, ctx) {
         ctx.logger.info("Reading C64 memory", { address: parsed.address, length: parsed.length });
         const result = await ctx.client.readMemory(parsed.address, String(parsed.length));
         if (!result.success) {
-            throw new ToolExecutionError("C64 firmware reported failure while reading memory", {
+            throw new ToolExecutionError("C64 backend reported failure while reading memory", {
                 details: normaliseFailure(result.details),
             });
         }
@@ -229,7 +229,7 @@ async function executeWriteMemory(rawArgs, ctx) {
         if (!shouldVerify) {
             const result = await ctx.client.writeMemory(parsed.address, writeInfo.canonical);
             if (!result.success) {
-                throw new ToolExecutionError("C64 firmware reported failure while writing memory", {
+                throw new ToolExecutionError("C64 backend reported failure while writing memory", {
                     details: normaliseFailure(result.details),
                 });
             }
@@ -251,7 +251,7 @@ async function executeWriteMemory(rawArgs, ctx) {
             if (canPause) {
                 const pauseResult = await ctx.client.pause(pinnedFacade);
                 if (!pauseResult.success) {
-                    throw new ToolExecutionError("C64 firmware reported failure while pausing", {
+                    throw new ToolExecutionError("C64 backend reported failure while pausing", {
                         details: normaliseFailure(pauseResult.details),
                     });
                 }
@@ -262,7 +262,7 @@ async function executeWriteMemory(rawArgs, ctx) {
             const readLength = Math.max(1, Math.max(writeInfo.bytes.length, expectedBytes.length));
             const preRead = await ctx.client.readMemory(parsed.address, String(readLength), pinnedFacade);
             if (!preRead.success) {
-                throw new ToolExecutionError("C64 firmware reported failure while reading memory", {
+                throw new ToolExecutionError("C64 backend reported failure while reading memory", {
                     details: normaliseFailure(preRead.details),
                 });
             }
@@ -290,13 +290,13 @@ async function executeWriteMemory(rawArgs, ctx) {
             }
             const writeResult = await ctx.client.writeMemory(parsed.address, writeInfo.canonical, pinnedFacade);
             if (!writeResult.success) {
-                throw new ToolExecutionError("C64 firmware reported failure while writing memory", {
+                throw new ToolExecutionError("C64 backend reported failure while writing memory", {
                     details: normaliseFailure(writeResult.details),
                 });
             }
             const postRead = await ctx.client.readMemory(parsed.address, String(Math.max(1, writeInfo.bytes.length)), pinnedFacade);
             if (!postRead.success) {
-                throw new ToolExecutionError("C64 firmware reported failure while reading back memory", {
+                throw new ToolExecutionError("C64 backend reported failure while reading back memory", {
                     details: normaliseFailure(postRead.details),
                 });
             }

package/dist/tools/meta/audio.js

@@ -267,7 +267,7 @@ export const tools = [
                 const results = [];
                 let restoreError;
                 try {
-                    for (const backend of requestedBackends) {
+                    for (const [backendIndex, backend] of requestedBackends.entries()) {
                         context.client.switchBackend(backend);
                         context.setPlatform(backend);
                         await trySilenceSid(context);
@@ -303,7 +303,11 @@ export const tools = [
                                 analysis,
                             };
                         }
-                        await trySilenceSid(context);
+                        // Stop this backend's playback only before moving on to the next one;
+                        // the last backend keeps playing so the preset can be heard in full.
+                        if (backendIndex < requestedBackends.length - 1) {
+                            await trySilenceSid(context);
+                        }
                         backendResult.verification = verification;
                         backendResult.success = true;
                         results.push(backendResult);
@@ -493,6 +497,8 @@ export const tools = [
                         entryAddress: compiled.entryAddress,
                         prgBytes: compiled.prg.length,
                         title: document.song?.title ?? null,
+                        basicFreeBytes: compiled.basicFreeBytes,
+                        warnings: compiled.warnings,
                     },
                     playback: {
                         method: playbackMethod,

package/dist/tools/meta/config.js

@@ -4,13 +4,14 @@ import { ToolError, ToolUnsupportedPlatformError, ToolExecutionError, ToolValida
 import { getPlatformStatus } from "../../platform.js";
 import { promises as fs } from "node:fs";
 import { dirname, resolve as resolvePath } from "node:path";
-import { captureConfigSnapshot, validateSnapshotCategories } from "./configInventory.js";
+import { captureConfigSnapshot, stripRedactedSecrets, validateSnapshotCategories } from "./configInventory.js";
 import { normalizeErrorDetails } from "./util.js";
 const configSnapshotAndRestoreArgsSchema = objectSchema({
     description: "Snapshot or restore full device configuration. Snapshot writes versioned JSON.",
     properties: {
         action: stringSchema({ description: "One of: snapshot|restore|diff", enum: ["snapshot", "restore", "diff"] }),
         path: stringSchema({ description: "Snapshot file path", minLength: 1 }),
+        includeSecretValues: optionalSchema(booleanSchema({ description: "Snapshot and diff only: store credential values (network password, FTP/Telnet passwords, Wi-Fi keys) in plain text in the snapshot file. Default false: they are written as ***, and restore skips them.", default: false }), false),
         applyToFlash: optionalSchema(booleanSchema({ description: "Save configuration to flash after restore (C64U/U64 and U2 only)", default: false }), false),
     },
     required: ["action", "path"],
@@ -37,7 +38,7 @@ export const tools = [
                     const [version, info, snapshotData] = await Promise.all([
                         ctx.client.version(),
                         ctx.client.info(),
-                        captureConfigSnapshot(ctx.client),
+                        captureConfigSnapshot(ctx.client, { includeSecretValues: parsed.includeSecretValues === true }),
                     ]);
                     const snapshot = {
                         createdAt: new Date().toISOString(),
@@ -61,7 +62,7 @@ export const tools = [
                     }
                     let payload;
                     try {
-                        payload = validateSnapshotCategories(snapshot.categories);
+                        payload = stripRedactedSecrets(validateSnapshotCategories(snapshot.categories));
                     }
                     catch {
                         throw new ToolValidationError("Invalid snapshot file", { path: "$.path" });
@@ -81,7 +82,7 @@ export const tools = [
                 const text = await fs.readFile(path, "utf8");
                 const snapshot = JSON.parse(text);
                 const snapCats = validateSnapshotCategories(snapshot.categories ?? {});
-                const current = (await captureConfigSnapshot(ctx.client)).categories;
+                const current = (await captureConfigSnapshot(ctx.client, { includeSecretValues: parsed.includeSecretValues === true })).categories;
                 const diff = {};
                 for (const [cat, snapVal] of Object.entries(snapCats)) {
                     const curVal = current[cat];