c64bridge 1.0.5 → 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";
@@ -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

@@ -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

@@ -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

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

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/graphics.js

@@ -223,7 +223,7 @@ export const tools = [
                 try {
                     const read = await ctx.client.readMemory(`$${formatAddressHex(startAddress)}`, String(length));
                     if (!read.success || typeof read.data !== "string") {
-                        throw new ToolExecutionError("C64 firmware reported failure while reading memory", { details: normalizeErrorDetails(read.details) });
+                        throw new ToolExecutionError("C64 backend reported failure while reading memory", { details: normalizeErrorDetails(read.details) });
                     }
                     const bytes = hexToBytes(read.data);
                     if (bytes.length < length) {

package/dist/tools/meta/memory.js

@@ -97,7 +97,7 @@ export const tools = [
                 if (canPause) {
                     const pauseResult = await ctx.client.pause();
                     if (!pauseResult.success) {
-                        throw new ToolExecutionError("C64 firmware reported failure while pausing", { details: normalizeErrorDetails(pauseResult.details) });
+                        throw new ToolExecutionError("C64 backend reported failure while pausing", { details: normalizeErrorDetails(pauseResult.details) });
                     }
                     paused = true;
                 }
@@ -105,7 +105,7 @@ export const tools = [
                 try {
                     const pre = await ctx.client.readMemory(parsed.address, String(Math.max(1, readLen)));
                     if (!pre.success) {
-                        throw new ToolExecutionError("C64 firmware reported failure while reading memory", { details: normalizeErrorDetails(pre.details) });
+                        throw new ToolExecutionError("C64 backend reported failure while reading memory", { details: normalizeErrorDetails(pre.details) });
                     }
                     preReadHex = pre.data ?? "$";
                     const preBytes = hexToBytes(preReadHex);
@@ -125,11 +125,11 @@ export const tools = [
                     }
                     const write = await ctx.client.writeMemory(parsed.address, bytesToHex(writeBytes));
                     if (!write.success) {
-                        throw new ToolExecutionError("C64 firmware reported failure while writing memory", { details: normalizeErrorDetails(write.details) });
+                        throw new ToolExecutionError("C64 backend reported failure while writing memory", { details: normalizeErrorDetails(write.details) });
                     }
                     const post = await ctx.client.readMemory(parsed.address, String(Math.max(1, writeBytes.length)));
                     if (!post.success) {
-                        throw new ToolExecutionError("C64 firmware reported failure while reading back memory", { details: normalizeErrorDetails(post.details) });
+                        throw new ToolExecutionError("C64 backend reported failure while reading back memory", { details: normalizeErrorDetails(post.details) });
                     }
                     const postBytes = hexToBytes(post.data ?? "$");
                     const diffs = [];

package/dist/tools/meta/program.js

@@ -1,6 +1,7 @@
 import { objectSchema, stringSchema, arraySchema, numberSchema, optionalSchema, booleanSchema } from "../schema.js";
 import { jsonResult } from "../responses.js";
 import { ToolError, ToolUnsupportedPlatformError, ToolExecutionError, toolErrorResult, unknownErrorResult } from "../errors.js";
+import { measureSidSilence } from "../audio.js";
 import { getPlatformStatus } from "../../platform.js";
 import { promises as fs } from "node:fs";
 import { resolve as resolvePath, join as joinPath } from "node:path";
@@ -206,7 +207,7 @@ const batchRunWithAssertionsArgsSchema = objectSchema({
                 assertions: optionalSchema(arraySchema(objectSchema({
                     description: "Assertion to check after run",
                     properties: {
-                        type: stringSchema({ description: "Assertion type", enum: ["screen_contains", "memory_equals", "sid_silent"] }),
+                        type: stringSchema({ description: "Assertion type; sid_silent needs the C64 Ultimate audio stream (c64u backend).", enum: ["screen_contains", "memory_equals", "sid_silent"] }),
                         pattern: optionalSchema(stringSchema({ description: "Pattern for screen_contains", minLength: 1 })),
                         address: optionalSchema(stringSchema({ description: "Address for memory_equals", minLength: 1 })),
                         expected: optionalSchema(stringSchema({ description: "Expected value (hex)", minLength: 1 })),
@@ -720,17 +721,20 @@ export const tools = [
                                     status = "fail";
                             }
                             else if (assertion.type === "sid_silent") {
-                                // Check SID gate bits are off (simple check)
-                                const result = await ctx.client.readMemory("$D404", "1");
-                                if (!result.success || typeof result.data !== "string") {
-                                    throw new Error("Failed to read SID voice 1 control register for sid_silent assertion");
+                                // SID control registers are write-only (an Ultimate 64 reads $D404 as $00
+                                // whatever was written), so silence is measured from the Ultimate audio
+                                // stream. Other backends would fall back to the host microphone, which
+                                // measures the room rather than the C64, so they report an error instead.
+                                const backend = ctx.platform?.id ?? await ctx.client.getActiveBackendType?.();
+                                if (backend !== undefined && backend !== "c64u") {
+                                    throw new Error(`sid_silent needs the C64 Ultimate audio stream and is not available on ${backend}`);
                                 }
-                                const gate1 = parseInt(result.data.slice(1), 16) & 0x01;
-                                const isSilent = gate1 === 0;
+                                const silence = await measureSidSilence(ctx);
+                                const isSilent = silence.silent;
                                 assertionResults.push({
                                     type: assertion.type,
                                     status: isSilent ? "pass" : "fail",
-                                    message: isSilent ? undefined : "SID voice 1 gate is on",
+                                    message: isSilent ? undefined : `SID output is not silent (peak RMS ${silence.maxRms.toFixed(3)} > ${silence.threshold})`,
                                 });
                                 if (!isSilent)
                                     status = "fail";

package/dist/tools/printer.js

@@ -278,7 +278,7 @@ export const printerModule = defineToolModule({
                         formFeed: parsed.formFeed,
                     });
                     if (!result.success) {
-                        throw new ToolExecutionError("C64 firmware reported failure while printing text", {
+                        throw new ToolExecutionError("C64 backend reported failure while printing text", {
                             details: normaliseFailure(result.details),
                         });
                     }
@@ -337,7 +337,7 @@ export const printerModule = defineToolModule({
                         ensureMsb: parsed.ensureMsb,
                     });
                     if (!result.success) {
-                        throw new ToolExecutionError("C64 firmware reported failure while printing Commodore bitmap", {
+                        throw new ToolExecutionError("C64 backend reported failure while printing Commodore bitmap", {
                             details: normaliseFailure(result.details),
                         });
                     }
@@ -398,7 +398,7 @@ export const printerModule = defineToolModule({
                         timesPerLine: parsed.timesPerLine,
                     });
                     if (!result.success) {
-                        throw new ToolExecutionError("C64 firmware reported failure while printing Epson bitmap", {
+                        throw new ToolExecutionError("C64 backend reported failure while printing Epson bitmap", {
                             details: normaliseFailure(result.details),
                         });
                     }
@@ -458,7 +458,7 @@ export const printerModule = defineToolModule({
                         secondaryAddress: parsed.secondaryAddress,
                     });
                     if (!result.success) {
-                        throw new ToolExecutionError("C64 firmware reported failure while defining DLL characters", {
+                        throw new ToolExecutionError("C64 backend reported failure while defining DLL characters", {
                             details: normaliseFailure(result.details),
                         });
                     }