c64bridge 1.0.2 → 1.0.4

package/dist/tools/audio.js

@@ -4,7 +4,8 @@ import { recordAndAnalyzeAudio } from "../audio/record_and_analyze_audio.js";
 import { defineToolModule } from "./types.js";
 import { booleanSchema, numberSchema, objectSchema, optionalSchema, stringSchema, } from "./schema.js";
 import { jsonResult, textResult } from "./responses.js";
-import { ToolError, ToolExecutionError, ToolValidationError, toolErrorResult, unknownErrorResult, } from "./errors.js";
+import { ToolError, ToolExecutionError, ToolValidationError, ToolUnsupportedPlatformError, toolErrorResult, unknownErrorResult, } from "./errors.js";
+import { getPlatformStatus } from "../platform.js";
 const NOTE_PATTERN = /^([A-Ga-g])([#b]?)(-?\d+)$/;
 const DEFAULT_SILENCE_VERIFY_DURATION_SECONDS = 1.5;
 const DEFAULT_SILENCE_VERIFY_RMS_THRESHOLD = 0.02;
@@ -244,7 +245,7 @@ const musicCompileArgsSchema = objectSchema({
             enum: ["yaml", "json"],
         })),
         output: optionalSchema(stringSchema({
-            description: "Playback target format.",
+            description: "Playback target format. PRG works on all backends; SID playback requires C64U/U64 or U2 (SID export with dryRun works everywhere).",
             enum: ["prg", "sid"],
             default: "prg",
         }), "prg"),
@@ -256,7 +257,7 @@ const musicCompileArgsSchema = objectSchema({
     additionalProperties: false,
 });
 const recordAndAnalyzeArgsSchema = objectSchema({
-    description: "Record audio from the default input and analyze SID playback characteristics.",
+    description: "Record audio and analyze SID playback characteristics. On the c64u backend the audio comes from the Ultimate audio stream; on other backends it is recorded from the host default input device (microphone).",
     properties: {
         durationSeconds: numberSchema({
             description: "Capture duration in seconds (0.5 - 30).",
@@ -902,6 +903,10 @@ export const audioModule = defineToolModule({
                         throw new ToolValidationError("Provide sidwave or cpg source", { path: "$.sidwave" });
                     }
                     const outputFormat = parsed.output ?? "prg";
+                    const platform = ctx.platform?.id ?? getPlatformStatus().id;
+                    if (outputFormat === "sid" && !parsed.dryRun && platform === "vice") {
+                        throw new ToolUnsupportedPlatformError("sidplay_attachment (use output: prg or dryRun: true on VICE)", platform, ["c64u", "u2"]);
+                    }
                     ctx.logger.info("Compiling SIDWAVE composition", {
                         output: outputFormat,
                         dryRun: parsed.dryRun,
@@ -963,7 +968,7 @@ export const audioModule = defineToolModule({
         },
         {
             name: "record_and_analyze_audio",
-            description: "Record audio from the default input device and analyze SID playback characteristics.",
+            description: "Record audio and analyze SID playback characteristics. On the c64u backend the audio comes from the Ultimate audio stream; on other backends it is recorded from the host default input device (microphone).",
             summary: "Captures PCM data, extracts notes, tempo, and deviation metrics for SID verification workflows.",
             inputSchema: recordAndAnalyzeArgsSchema.jsonSchema,
             relatedResources: ["c64://sound/sid/spec", "c64://sound/sid/file-format"],
@@ -981,7 +986,8 @@ export const audioModule = defineToolModule({
                 try {
                     const parsed = recordAndAnalyzeArgsSchema.parse(args ?? {});
                     ctx.logger.info("Recording audio for analysis", { durationSeconds: parsed.durationSeconds });
-                    const result = await recordAndAnalyzeAudio({
+                    const analyzer = resolveAnalyzer(ctx);
+                    const result = await analyzer({
                         durationSeconds: parsed.durationSeconds,
                         expectedSidwave: normaliseSidwaveInput(parsed.expectedSidwave),
                     });

package/dist/tools/meta/artifacts.js

@@ -1,6 +1,7 @@
 import { objectSchema, stringSchema, arraySchema, numberSchema, optionalSchema, booleanSchema } from "../schema.js";
 import { jsonResult } from "../responses.js";
-import { ToolError, ToolValidationError, toolErrorResult, unknownErrorResult } from "../errors.js";
+import { ToolError, ToolValidationError, ToolUnsupportedPlatformError, toolErrorResult, unknownErrorResult } from "../errors.js";
+import { getPlatformStatus } from "../../platform.js";
 import { promises as fs } from "node:fs";
 import { resolve as resolvePath, join as joinPath, relative, sep, isAbsolute } from "node:path";
 const bundleRunArtifactsArgsSchema = objectSchema({
@@ -18,7 +19,7 @@ const bundleRunArtifactsArgsSchema = objectSchema({
             required: ["address", "length"],
             additionalProperties: false,
         }))),
-        captureDebugReg: optionalSchema(booleanSchema({ description: "Capture debugreg state", default: true }), true),
+        captureDebugReg: optionalSchema(booleanSchema({ description: "Capture Ultimate debug registers (C64U/U64 only). Defaults to true on C64U/U64 and false on U2/VICE." })),
     },
     required: ["runId", "outputPath"],
     additionalProperties: false,
@@ -46,7 +47,11 @@ export const tools = [
                 }
                 const outputPath = resolvePath(String(parsed.outputPath));
                 const captureScreen = parsed.captureScreen !== false;
-                const captureDebugReg = parsed.captureDebugReg !== false;
+                const platform = ctx.platform?.id ?? getPlatformStatus().id;
+                const captureDebugReg = parsed.captureDebugReg ?? (platform === "c64u");
+                if (captureDebugReg && platform !== "c64u") {
+                    throw new ToolUnsupportedPlatformError("debugreg_read", platform, ["c64u"]);
+                }
                 const memoryRanges = (parsed.memoryRanges ?? []);
                 await fs.mkdir(outputPath, { recursive: true });
                 const runPath = containedPath(outputPath, runId);

package/dist/tools/meta/audio.js

@@ -2,7 +2,8 @@ import { compileSidwaveToPrg, compileSidwaveToSid } from "../../sidwaveCompiler.
 import { parseSidwave } from "../../sidwave.js";
 import { recordAndAnalyzeAudio } from "../../audio/record_and_analyze_audio.js";
 import { jsonResult } from "../responses.js";
-import { ToolExecutionError, toolErrorResult, unknownErrorResult } from "../errors.js";
+import { ToolExecutionError, ToolUnsupportedPlatformError, toolErrorResult, unknownErrorResult } from "../errors.js";
+import { getPlatformStatus } from "../../platform.js";
 import { sleep } from "./util.js";
 import { arraySchema, booleanSchema, numberSchema, objectSchema, optionalSchema, stringSchema } from "../schema.js";
 const DEFAULT_SILENCE_DURATION_SECONDS = 1.5;
@@ -68,7 +69,7 @@ const musicCompilePlayAnalyzeArgsSchema = objectSchema({
     properties: {
         sidwave: optionalSchema(stringSchema({ description: "SIDWAVE source in YAML or JSON format.", minLength: 1 })),
         cpg: optionalSchema(stringSchema({ description: "Legacy CPG input format.", minLength: 1 })),
-        output: optionalSchema(stringSchema({ description: "Playback artifact format.", enum: ["prg", "sid"], default: "prg" }), "prg"),
+        output: optionalSchema(stringSchema({ description: "Playback artifact format. PRG works on all backends; SID attachment playback requires C64U/U64 or U2.", enum: ["prg", "sid"], default: "prg" }), "prg"),
         waitBeforeCaptureMs: optionalSchema(numberSchema({ description: "Delay between starting playback and beginning analysis capture (milliseconds).", minimum: 0, maximum: 5000 }), DEFAULT_PLAYBACK_WAIT_MS),
         analysisDurationSeconds: optionalSchema(numberSchema({ description: "Audio capture length in seconds.", minimum: 0.5, maximum: 20 }), DEFAULT_ANALYSIS_DURATION_SECONDS),
         expectedSidwave: optionalSchema(stringSchema({ description: "Optional expected SIDWAVE used to refine analysis comparisons.", minLength: 1 })),
@@ -91,11 +92,11 @@ const musicPlayPresetArgsSchema = objectSchema({
         }), "fuer_elise"),
         platforms: optionalSchema(arraySchema(stringSchema({
             description: "Backends to target in sequence.",
-            enum: ["vice", "c64u"],
+            enum: ["vice", "c64u", "u2"],
             minLength: 1,
         }))),
         verify: optionalSchema(booleanSchema({
-            description: "Capture and analyze audio on supported backends after playback starts.",
+            description: "Capture and analyze audio after playback starts: native streaming on C64U/U64, host audio input on U2/VICE (PortAudio required).",
             default: true,
         }), true),
         analysisDurationSeconds: optionalSchema(numberSchema({
@@ -147,7 +148,7 @@ function normalizeSidwaveInput(input) {
     return undefined;
 }
 function canonicalPresetBackends() {
-    return ["vice", "c64u"];
+    return ["vice", "c64u", "u2"];
 }
 function uniquePresetBackends(backends) {
     return backends.filter((backend, index) => backends.indexOf(backend) === index);
@@ -285,30 +286,22 @@ export const tools = [
                         }
                         let verification = null;
                         if (verify) {
-                            if (backend === "c64u") {
-                                if (waitBeforeCaptureMs > 0) {
-                                    await sleep(waitBeforeCaptureMs);
-                                }
-                                const analysis = await analyzer({
-                                    durationSeconds: analysisDurationSeconds,
-                                    expectedSidwave: preset.sidwave,
-                                });
-                                const metrics = extractRmsMetrics((analysis?.analysis?.global_metrics ?? {}));
-                                verification = {
-                                    mode: "audio-analysis",
-                                    durationSeconds: analysis.analysis?.durationSeconds ?? analysisDurationSeconds,
-                                    averageRms: metrics.average,
-                                    maxRms: metrics.max,
-                                    voices: analysis.analysis?.voices ?? [],
-                                    analysis,
-                                };
-                            }
-                            else {
-                                verification = {
-                                    mode: "playback-launch",
-                                    note: "Audio analysis is only available on c64u; verified that playback launched on this backend.",
-                                };
+                            if (waitBeforeCaptureMs > 0) {
+                                await sleep(waitBeforeCaptureMs);
                             }
+                            const analysis = await analyzer({
+                                durationSeconds: analysisDurationSeconds,
+                                expectedSidwave: preset.sidwave,
+                            });
+                            const metrics = extractRmsMetrics((analysis?.analysis?.global_metrics ?? {}));
+                            verification = {
+                                mode: "audio-analysis",
+                                durationSeconds: analysis.analysis?.durationSeconds ?? analysisDurationSeconds,
+                                averageRms: metrics.average,
+                                maxRms: metrics.max,
+                                voices: analysis.analysis?.voices ?? [],
+                                analysis,
+                            };
                         }
                         await trySilenceSid(context);
                         backendResult.verification = verification;
@@ -409,6 +402,10 @@ export const tools = [
                     throw new ToolExecutionError("Provide sidwave or cpg source");
                 }
                 const format = (parsed.output ?? "prg");
+                const platform = context.platform?.id ?? getPlatformStatus().id;
+                if (format === "sid" && platform === "vice") {
+                    throw new ToolUnsupportedPlatformError("sidplay_attachment (use output: prg on VICE)", platform, ["c64u", "u2"]);
+                }
                 const waitBeforeCaptureMs = parsed.waitBeforeCaptureMs ?? DEFAULT_PLAYBACK_WAIT_MS;
                 const analysisDurationSeconds = parsed.analysisDurationSeconds ?? DEFAULT_ANALYSIS_DURATION_SECONDS;
                 const verifySilenceBefore = parsed.verifySilenceBefore ?? true;

package/dist/tools/meta/config.js

@@ -1,6 +1,7 @@
 import { objectSchema, stringSchema, optionalSchema, booleanSchema } from "../schema.js";
 import { jsonResult } from "../responses.js";
-import { ToolError, ToolExecutionError, ToolValidationError, toolErrorResult, unknownErrorResult } from "../errors.js";
+import { ToolError, ToolUnsupportedPlatformError, ToolExecutionError, ToolValidationError, toolErrorResult, unknownErrorResult } from "../errors.js";
+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";
@@ -10,7 +11,7 @@ const configSnapshotAndRestoreArgsSchema = objectSchema({
     properties: {
         action: stringSchema({ description: "One of: snapshot|restore|diff", enum: ["snapshot", "restore", "diff"] }),
         path: stringSchema({ description: "Snapshot file path", minLength: 1 }),
-        applyToFlash: optionalSchema(booleanSchema({ description: "Save configuration to flash after restore", default: false }), false),
+        applyToFlash: optionalSchema(booleanSchema({ description: "Save configuration to flash after restore (C64U/U64 and U2 only)", default: false }), false),
     },
     required: ["action", "path"],
     additionalProperties: false,
@@ -26,9 +27,13 @@ export const tools = [
             try {
                 const parsed = configSnapshotAndRestoreArgsSchema.parse(args ?? {});
                 const action = parsed.action;
+                const platform = ctx.platform?.id ?? getPlatformStatus().id;
+                if (action === "restore" && parsed.applyToFlash && platform === "vice") {
+                    throw new ToolUnsupportedPlatformError("config_save_to_flash", platform, ["c64u", "u2"]);
+                }
                 const path = resolvePath(String(parsed.path));
-                await fs.mkdir(dirname(path), { recursive: true });
                 if (action === "snapshot") {
+                    await fs.mkdir(dirname(path), { recursive: true });
                     const [version, info, snapshotData] = await Promise.all([
                         ctx.client.version(),
                         ctx.client.info(),
@@ -66,7 +71,10 @@ export const tools = [
                         throw new ToolExecutionError("Batch update failed", { details: normalizeErrorDetails(result.details) });
                     }
                     if (parsed.applyToFlash) {
-                        await ctx.client.configSaveToFlash();
+                        const saved = await ctx.client.configSaveToFlash();
+                        if (!saved.success) {
+                            throw new ToolExecutionError("Configuration restored, but saving to flash failed", { details: normalizeErrorDetails(saved.details) });
+                        }
                     }
                     return jsonResult({ restored: true, categories: Object.keys(payload).length }, { success: true });
                 }

package/dist/tools/meta/configInventory.js

@@ -96,7 +96,10 @@ function normalizeSnapshotValue(value, entry) {
     if (value
         && typeof value === "object"
         && !Array.isArray(value)
-        && Object.keys(value).length === 1
+        && (Object.keys(value).length === 1
+            || (value.category === entry.category
+                && value.item === entry.item
+                && ["int", "string"].includes(String(value.type))))
         && Object.prototype.hasOwnProperty.call(value, "value")) {
         return value.value;
     }

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, ToolExecutionError, toolErrorResult, unknownErrorResult } from "../errors.js";
+import { ToolError, ToolUnsupportedPlatformError, ToolExecutionError, toolErrorResult, unknownErrorResult } from "../errors.js";
+import { getPlatformStatus } from "../../platform.js";
 import { promises as fs } from "node:fs";
 import { resolve as resolvePath, join as joinPath } from "node:path";
 import { sleep, formatTimestampSpec } from "./util.js";
@@ -56,7 +57,7 @@ function shouldUseVisibleViceGreetingFastPath(rawArgs, requestedBackends) {
         && !hasOwnProperty(args, "outputPath");
 }
 function canonicalGreetingBackends() {
-    return ["vice", "c64u"];
+    return ["vice", "c64u", "u2"];
 }
 function uniqueGreetingBackends(backends) {
     return backends.filter((backend, index) => backends.indexOf(backend) === index);
@@ -226,9 +227,9 @@ const crossPlatformGreetingArgsSchema = objectSchema({
     properties: {
         platforms: optionalSchema(arraySchema(stringSchema({
             description: "Backends to target in sequence.",
-            enum: ["vice", "c64u"],
+            enum: ["vice", "c64u", "u2"],
             minLength: 1,
-        })), ["vice", "c64u"]),
+        }))),
         messageTemplate: optionalSchema(stringSchema({
             description: "Greeting template. Use {PLATFORM}/{BACKEND} for uppercase or {platform}/{backend} for lowercase substitution.",
             minLength: 1,
@@ -238,7 +239,7 @@ const crossPlatformGreetingArgsSchema = objectSchema({
             default: true,
         }), true),
         captureScreenshot: optionalSchema(booleanSchema({
-            description: "Capture a framebuffer screenshot and save it as a PNG per backend.",
+            description: "Capture a framebuffer screenshot on C64U/U64 or VICE. U2 skips screenshots by default; explicitly requesting one on U2 fails before execution.",
             default: true,
         }), true),
         outputPath: optionalSchema(stringSchema({
@@ -311,11 +312,14 @@ export const tools = [
                         details: { availableBackends },
                     });
                 }
+                if (args?.captureScreenshot === true && requestedBackends.includes("u2")) {
+                    throw new ToolUnsupportedPlatformError("capture_frame", "u2", ["c64u", "vice"]);
+                }
                 const visibleViceFastPath = shouldUseVisibleViceGreetingFastPath(args ?? {}, requestedBackends);
                 const verify = visibleViceFastPath ? false : parsed.verify !== false;
                 const captureScreenshot = visibleViceFastPath ? false : parsed.captureScreenshot !== false;
                 const restoreActiveBackend = parsed.restoreActiveBackend !== false;
-                const outputPath = captureScreenshot || parsed.outputPath
+                const outputPath = (captureScreenshot && requestedBackends.some((backend) => backend !== "u2")) || parsed.outputPath
                     ? resolvePath(String(parsed.outputPath ?? joinPath(process.cwd(), "artifacts", "greetings", `run_${Date.now()}`)))
                     : undefined;
                 const timeoutMs = parsed.timeoutMs ?? 1500;
@@ -330,6 +334,7 @@ export const tools = [
                 }
                 try {
                     for (const backend of requestedBackends) {
+                        const backendCaptureScreenshot = captureScreenshot && backend !== "u2";
                         const expectedText = applyGreetingTemplate(template, backend);
                         const program = buildGreetingProgram(expectedText);
                         const timeline = [];
@@ -358,7 +363,7 @@ export const tools = [
                             ctx.setPlatform(backend);
                         });
                         let prepareCapturePromise;
-                        if (captureScreenshot && backend === "c64u" && typeof client.prepareVideoCapture === "function") {
+                        if (backendCaptureScreenshot && backend === "c64u" && typeof client.prepareVideoCapture === "function") {
                             prepareCapturePromise = timedStep("prepare_capture", async () => {
                                 await client.prepareVideoCapture?.({ keepAliveMs: Math.max(500, timeoutMs) });
                                 preparedCaptureSession = true;
@@ -410,7 +415,7 @@ export const tools = [
                         let screenshotPath;
                         let screenshotAnalysis;
                         let screenshotError;
-                        if (captureScreenshot) {
+                        if (backendCaptureScreenshot) {
                             try {
                                 const capture = await timedStep("capture_screenshot", () => client.captureFrames({
                                     count: 1,
@@ -447,7 +452,7 @@ export const tools = [
                         }
                         backendResult.verification = {
                             screenContainsExpectedText: verify ? screenMatched : undefined,
-                            screenshotCaptured: captureScreenshot ? !screenshotError : undefined,
+                            screenshotCaptured: backendCaptureScreenshot ? !screenshotError : undefined,
                             screenshotAnalysis,
                         };
                         if (screenshotPath) {
@@ -458,7 +463,7 @@ export const tools = [
                         }
                         backendResult.success = runResult.success
                             && (!verify || screenMatched)
-                            && (!captureScreenshot || !screenshotError);
+                            && (!backendCaptureScreenshot || !screenshotError);
                         backendResult.promptToVisibleLatencyMs = timeline
                             .filter((entry) => entry.ok === true && (entry.name === "switch_backend" || entry.name === "render_greeting_screen" || entry.name === "verify_screen"))
                             .reduce((total, entry) => total + Number(entry.latencyMs ?? 0), 0);
@@ -642,6 +647,10 @@ export const tools = [
             try {
                 const parsed = batchRunWithAssertionsArgsSchema.parse(args ?? {});
                 const programs = parsed.programs;
+                const platform = ctx.platform?.id ?? getPlatformStatus().id;
+                if (platform === "vice" && programs.some((program) => program.path.toLowerCase().endsWith(".crt"))) {
+                    throw new ToolUnsupportedPlatformError("run_crt", platform, ["c64u", "u2"]);
+                }
                 const continueOnError = parsed.continueOnError ?? false;
                 const durationMs = parsed.durationMs ?? 2000;
                 const resetDelayMs = parsed.resetDelayMs ?? 100;
@@ -659,10 +668,14 @@ export const tools = [
                         // Run program
                         const ext = program.path.toLowerCase().split(".").pop();
                         if (ext === "prg") {
-                            await ctx.client.runPrgFile(program.path);
+                            const run = await ctx.client.runPrgFile(program.path);
+                            if (!run.success)
+                                throw new ToolExecutionError("PRG playback failed", { details: run.details });
                         }
                         else if (ext === "crt") {
-                            await ctx.client.runCrtFile(program.path);
+                            const run = await ctx.client.runCrtFile(program.path);
+                            if (!run.success)
+                                throw new ToolExecutionError("CRT playback failed", { details: run.details });
                         }
                         await sleep(durationMs);
                         // Check assertions

package/dist/tools/registry/batch.js

@@ -114,10 +114,12 @@ export const batchModuleGroup = defineToolModule({
                         try {
                             const toolResult = await toolRegistry.invoke(toolName, args, {
                                 ...ctx,
-                                platform: getPlatformStatus(),
+                                platform: typeof ctx.client.getActiveBackendType === "function"
+                                    ? { ...(ctx.platform ?? getPlatformStatus()), id: await ctx.client.getActiveBackendType() }
+                                    : ctx.platform ?? getPlatformStatus(),
                             });
                             const elapsedMs = Date.now() - cmdStart;
-                            const isError = toolResult.isError === true;
+                            const isError = toolResult.isError === true || toolResult.metadata?.success === false;
                             const text = toolResult.content.map((c) => c.text).join("\n");
                             const resultPayload = toolResult.structuredContent?.data ?? text;
                             if (isError) {

package/dist/tools/registry/config.js

@@ -24,7 +24,7 @@ const configRestoreArgsSchema = objectSchema({
             minLength: 1,
         }),
         applyToFlash: optionalSchema(booleanSchema({
-            description: "When true, save the restored configuration to flash immediately.",
+            description: "When true, save the restored configuration to flash immediately (C64U/U64 and U2 only).",
             default: false,
         })),
     },

package/dist/tools/registry/disk.js

@@ -161,6 +161,11 @@ const diskOperations = [
             const typedAttachment = attachmentMode;
             const typedDriveMode = driveMode;
             if (verify) {
+                if (typedType || typedAttachment) {
+                    throw new ToolValidationError("type and attachmentMode are not applied by the verified mount workflow; set verify to false to use them", {
+                        path: typedType ? "$.type" : "$.attachmentMode",
+                    });
+                }
                 return metaModule.invoke("drive_mount_and_verify", {
                     drive: parsed.drive,
                     imagePath: parsed.image,

package/dist/tools/registry/extract.js

@@ -32,6 +32,7 @@ const extractOperations = [
 const extractOperationHandlers = createOperationHandlers(extractOperations);
 export const extractModule = defineToolModule({
     domain: "extract",
+    supportedPlatforms: ["c64u", "u2", "vice"],
     summary: "Grouped extraction helpers for sprites, charsets, memory dumps, and diagnostics.",
     resources: ["c64://guide/bootstrap", "c64://basic/spec", "c64://assembly/6510-spec"],
     defaultTags: ["extract", "diagnostics"],
@@ -49,6 +50,8 @@ export const extractModule = defineToolModule({
                 variants: extractOperations.map((operation) => operation.schema),
             }),
             tags: ["extract", "diagnostics", "grouped"],
+            operationPlatforms: { fs_stats: ["c64u", "u2"] },
+            operationToolNames: { fs_stats: "filesystem_stats_by_extension" },
             examples: [
                 {
                     name: "Dump RAM to file",

package/dist/tools/registry/graphics.js

@@ -216,6 +216,7 @@ export const graphicsModuleGroup = defineToolModule({
     tools: [
         {
             name: "c64_graphics",
+            operationPlatforms: { capture_frame: ["c64u", "vice"] },
             description: "Grouped entry point for frame capture and graphics rendering workflows.",
             summary: "Captures frames, renders PETSCII text or art, previews sprites, and displays bitmap images from one tool.",
             inputSchema: discriminatedUnionSchema({

package/dist/tools/registry/program.js

@@ -69,7 +69,7 @@ export const programModule = defineToolModule({
                 variants: programOperations.map((operation) => operation.schema),
             }),
             tags: ["programs", "execution", "grouped"],
-            operationPlatforms: { load_prg: ["c64u", "u2"], run_crt: ["c64u", "u2"], bundle_run: ["c64u", "u2"] },
+            operationPlatforms: { load_prg: ["c64u", "u2"], run_crt: ["c64u", "u2"] },
             operationToolNames: {
                 load_prg: "load_prg",
                 run_crt: "run_crt",

package/dist/tools/registry/sound.js

@@ -131,7 +131,7 @@ const soundOperations = [
     },
     {
         op: "record_analyze",
-        schema: extendSchemaWithOp("record_analyze", ensureDescriptor(audioDescriptorIndex, "record_and_analyze_audio").inputSchema, { description: "Record audio for a fixed duration and return SID analysis metrics." }),
+        schema: extendSchemaWithOp("record_analyze", ensureDescriptor(audioDescriptorIndex, "record_and_analyze_audio").inputSchema, { description: "Record audio for a fixed duration and return SID analysis metrics. Uses the Ultimate audio stream on c64u and the host microphone on other backends." }),
         handler: async (rawArgs, ctx) => invokeModuleTool(audioModule, "record_and_analyze_audio", rawArgs, ctx),
     },
 ];
@@ -161,9 +161,9 @@ export const soundModuleGroup = defineToolModule({
                 capture_samples: ["c64u"],
                 play_sid_file: ["c64u", "u2"],
                 play_mod_file: ["c64u", "u2"],
-                pipeline: ["c64u", "u2"],
-                analyze: ["c64u"],
-                record_analyze: ["c64u"],
+                pipeline: ["c64u", "u2", "vice"],
+                analyze: ["c64u", "u2", "vice"],
+                record_analyze: ["c64u", "u2", "vice"],
             },
             operationToolNames: {
                 play_sid_file: "sidplay_file",

package/dist/tools/registry/system.js

@@ -27,7 +27,7 @@ const systemOperations = [
     },
     {
         op: "poweroff",
-        schema: extendSchemaWithOp("poweroff", ensureDescriptor(machineDescriptorIndex, "poweroff").inputSchema, { description: "Request a controlled shutdown via the Ultimate firmware." }),
+        schema: extendSchemaWithOp("poweroff", ensureDescriptor(machineDescriptorIndex, "poweroff").inputSchema, { description: "Shut down C64U/U64 or quit VICE. U2-family hardware cannot power off." }),
         handler: async (rawArgs, ctx) => invokeModuleTool(machineControlModule, "poweroff", rawArgs, ctx),
     },
     {
@@ -93,8 +93,8 @@ export const systemModuleGroup = defineToolModule({
                 variants: systemOperations.map((operation) => operation.schema),
             }),
             tags: ["system", "control", "grouped"],
-            operationPlatforms: { pause: ["c64u", "u2"], resume: ["c64u", "u2"], menu: ["c64u", "u2"], read_menu_screen: ["c64u", "u2"] },
-            operationToolNames: { pause: "pause", resume: "resume", menu: "menu_button", read_menu_screen: "read_menu_screen" },
+            operationPlatforms: { poweroff: ["c64u", "vice"], pause: ["c64u", "u2"], resume: ["c64u", "u2"], menu: ["c64u", "u2"], read_menu_screen: ["c64u", "u2"] },
+            operationToolNames: { poweroff: "poweroff", pause: "pause", resume: "resume", menu: "menu_button", read_menu_screen: "read_menu_screen" },
             examples: [
                 {
                     name: "Soft reset",

package/dist/tools/storage.js

@@ -39,11 +39,11 @@ const driveMountArgsSchema = objectSchema({
         drive: driveIdentifierSchema,
         image: diskImagePathSchema,
         type: optionalSchema(stringSchema({
-            description: "Override the disk image type when auto-detection is incorrect.",
+            description: "Override the disk image type when auto-detection is incorrect (C64U/U64 and U2 only; VICE uses auto-detection).",
             enum: ["d64", "g64", "d71", "g71", "d81"],
         })),
         mode: optionalSchema(stringSchema({
-            description: "Attachment mode controlling how the firmware treats the mounted image.",
+            description: "Attachment mode controlling how the firmware treats the mounted image (C64U/U64 and U2 only).",
             enum: ["readwrite", "readonly", "unlinked"],
         })),
     },

package/dist/tools/streaming.js

@@ -32,6 +32,15 @@ function toRecord(details) {
     }
     return undefined;
 }
+function withFailureReason(message, details) {
+    const record = toRecord(details);
+    const body = toRecord(record?.data) ?? toRecord(record?.response) ?? record;
+    const errors = body?.errors;
+    const reason = Array.isArray(errors) && errors.length > 0
+        ? errors.map(String).join("; ")
+        : record?.message ?? record?.reason ?? (typeof details === "string" ? details : undefined);
+    return typeof reason === "string" && reason.length > 0 ? `${message}: ${reason}` : message;
+}
 export const streamingModule = defineToolModule({
     domain: "streaming",
     summary: "Long-running or streaming workflows such as audio capture or SID playback monitoring.",
@@ -71,7 +80,7 @@ export const streamingModule = defineToolModule({
                     });
                     const result = await ctx.client.streamStart(parsed.stream, parsed.target);
                     if (!result.success) {
-                        throw new ToolExecutionError("C64 firmware reported failure while starting stream", {
+                        throw new ToolExecutionError(withFailureReason("C64 firmware reported failure while starting stream", result.details), {
                             details: toRecord(result.details),
                         });
                     }
@@ -111,7 +120,7 @@ export const streamingModule = defineToolModule({
                     });
                     const result = await ctx.client.streamStop(parsed.stream);
                     if (!result.success) {
-                        throw new ToolExecutionError("C64 firmware reported failure while stopping stream", {
+                        throw new ToolExecutionError(withFailureReason("C64 firmware reported failure while stopping stream", result.details), {
                             details: toRecord(result.details),
                         });
                     }

package/mcp/schemas/c64_config.schema.json

@@ -53,7 +53,7 @@
         "boolean",
         "null"
       ],
-      "description": "When true, save the restored configuration to flash immediately.",
+      "description": "When true, save the restored configuration to flash immediately (C64U/U64 and U2 only).",
       "default": false
     },
     "root": {
@@ -452,7 +452,7 @@
               "boolean",
               "null"
             ],
-            "description": "When true, save the restored configuration to flash immediately.",
+            "description": "When true, save the restored configuration to flash immediately (C64U/U64 and U2 only).",
             "default": false
           },
           "op": {

package/mcp/schemas/c64_program.schema.json

@@ -185,8 +185,7 @@
         "boolean",
         "null"
       ],
-      "description": "Capture debugreg state",
-      "default": true
+      "description": "Capture Ultimate debug registers (C64U/U64 only). Defaults to true on C64U/U64 and false on U2/VICE."
     },
     "platforms": {
       "type": [
@@ -199,13 +198,10 @@
         "minLength": 1,
         "enum": [
           "vice",
-          "c64u"
+          "c64u",
+          "u2"
         ]
-      },
-      "default": [
-        "vice",
-        "c64u"
-      ]
+      }
     },
     "messageTemplate": {
       "type": [
@@ -221,7 +217,7 @@
         "boolean",
         "null"
       ],
-      "description": "Capture a framebuffer screenshot and save it as a PNG per backend.",
+      "description": "Capture a framebuffer screenshot on C64U/U64 or VICE. U2 skips screenshots by default; explicitly requesting one on U2 fails before execution.",
       "default": true
     },
     "restoreActiveBackend": {
@@ -623,8 +619,7 @@
               "boolean",
               "null"
             ],
-            "description": "Capture debugreg state",
-            "default": true
+            "description": "Capture Ultimate debug registers (C64U/U64 only). Defaults to true on C64U/U64 and false on U2/VICE."
           },
           "op": {
             "const": "bundle_run"
@@ -667,13 +662,10 @@
               "minLength": 1,
               "enum": [
                 "vice",
-                "c64u"
+                "c64u",
+                "u2"
               ]
-            },
-            "default": [
-              "vice",
-              "c64u"
-            ]
+            }
           },
           "messageTemplate": {
             "type": [
@@ -697,7 +689,7 @@
               "boolean",
               "null"
             ],
-            "description": "Capture a framebuffer screenshot and save it as a PNG per backend.",
+            "description": "Capture a framebuffer screenshot on C64U/U64 or VICE. U2 skips screenshots by default; explicitly requesting one on U2 fails before execution.",
             "default": true
           },
           "outputPath": {