c64bridge 0.7.4 → 0.8.1

package/dist/tools/registry/graphics.js

@@ -1,74 +1,158 @@
+import { Buffer } from "node:buffer";
 import { createOperationDispatcher, defineToolModule, discriminatedUnionSchema, } from "../types.js";
 import { graphicsModule, graphicsOperationHandlers as groupedGraphicsHandlers } from "../graphics.js";
+import { booleanSchema, literalSchema, numberSchema, objectSchema, optionalSchema, stringSchema, } from "../schema.js";
 import { buildDescriptorIndex, ensureDescriptor, extendSchemaWithOp, createOperationHandlers, } from "./utils.js";
-import { ToolExecutionError, toolErrorResult } from "../errors.js";
+import { ToolError, toolErrorResult, unknownErrorResult, } from "../errors.js";
+import { jsonResult } from "../responses.js";
 const graphicsDescriptorIndex = buildDescriptorIndex(graphicsModule);
+const captureFrameArgsSchema = objectSchema({
+    description: "Capture one or more complete video frames from the active backend.",
+    properties: {
+        op: literalSchema("capture_frame"),
+        count: optionalSchema(numberSchema({
+            description: "Number of frames to capture.",
+            integer: true,
+            minimum: 1,
+            maximum: 32,
+            default: 1,
+        }), 1),
+        includePixels: optionalSchema(booleanSchema({
+            description: "Include pixel payload bytes in the response.",
+            default: true,
+        }), true),
+        encoding: optionalSchema(stringSchema({
+            description: "Encoding used for the pixel payload when included.",
+            enum: ["base64", "hex"],
+            default: "base64",
+        }), "base64"),
+    },
+    required: ["op"],
+    additionalProperties: false,
+});
 const graphicsOperations = [
     {
-        op: "create_petscii",
-        schema: extendSchemaWithOp("create_petscii", ensureDescriptor(graphicsDescriptorIndex, "create_petscii").inputSchema, { description: "Generate PETSCII art from prompts, text, or explicit bitmap data." }),
-        handler: groupedGraphicsHandlers.create_petscii,
+        op: "capture_frame",
+        schema: captureFrameArgsSchema.jsonSchema,
+        handler: async (rawArgs, ctx) => {
+            try {
+                const parsed = captureFrameArgsSchema.parse(rawArgs);
+                ctx.logger.info("Capturing frame buffer", {
+                    count: parsed.count,
+                    includePixels: parsed.includePixels,
+                    encoding: parsed.encoding,
+                });
+                const capture = await ctx.client.captureFrames({ count: parsed.count });
+                const includePixels = parsed.includePixels !== false;
+                const encoding = parsed.encoding ?? "base64";
+                const frames = capture.frames.map((frame, index) => {
+                    const pixels = includePixels
+                        ? {
+                            encoding,
+                            data: encoding === "hex"
+                                ? Buffer.from(frame.pixels).toString("hex")
+                                : Buffer.from(frame.pixels).toString("base64"),
+                        }
+                        : undefined;
+                    return {
+                        index,
+                        frameNumber: frame.frameNumber,
+                        width: frame.width,
+                        height: frame.height,
+                        bitsPerPixel: frame.bitsPerPixel,
+                        byteLength: frame.pixels.length,
+                        complete: frame.complete,
+                        ...(pixels ? { pixels } : {}),
+                    };
+                });
+                return jsonResult({
+                    backend: capture.backend,
+                    count: frames.length,
+                    frames,
+                }, {
+                    success: true,
+                    backend: capture.backend,
+                    count: frames.length,
+                    includePixels,
+                    encoding: includePixels ? encoding : null,
+                });
+            }
+            catch (error) {
+                if (error instanceof ToolError) {
+                    return toolErrorResult(error);
+                }
+                return unknownErrorResult(error);
+            }
+        },
+    },
+    {
+        op: "render_petscii_art",
+        schema: extendSchemaWithOp("render_petscii_art", ensureDescriptor(graphicsDescriptorIndex, "render_petscii_art").inputSchema, { description: "Create PETSCII art from prompts, text, or explicit bitmap data, and optionally display it on the C64." }),
+        handler: groupedGraphicsHandlers.render_petscii_art,
     },
     {
-        op: "render_petscii",
-        schema: extendSchemaWithOp("render_petscii", ensureDescriptor(graphicsDescriptorIndex, "render_petscii").inputSchema, { description: "Render PETSCII text with optional border/background colours." }),
-        handler: groupedGraphicsHandlers.render_petscii,
+        op: "render_petscii_text",
+        schema: extendSchemaWithOp("render_petscii_text", ensureDescriptor(graphicsDescriptorIndex, "render_petscii_text").inputSchema, { description: "Display PETSCII text with optional border and background colours." }),
+        handler: groupedGraphicsHandlers.render_petscii_text,
     },
     {
-        op: "generate_sprite",
-        schema: extendSchemaWithOp("generate_sprite", ensureDescriptor(graphicsDescriptorIndex, "generate_sprite").inputSchema, { description: "Build and run a sprite PRG from raw 63-byte sprite data." }),
-        handler: groupedGraphicsHandlers.generate_sprite,
+        op: "render_sprite",
+        schema: extendSchemaWithOp("render_sprite", ensureDescriptor(graphicsDescriptorIndex, "render_sprite").inputSchema, { description: "Display supplied 63-byte sprite data at the requested position and colour by writing memory and patching VIC-II registers directly." }),
+        handler: groupedGraphicsHandlers.render_sprite,
     },
     {
-        op: "generate_bitmap",
-        schema: extendSchemaWithOp("generate_bitmap", {
-            description: "Reserved high-resolution bitmap generator (coming soon).",
-            type: "object",
-            properties: {},
-            additionalProperties: false,
-        }, { description: "Reserved high-resolution bitmap generator (coming soon)." }),
-        handler: async () => toolErrorResult(new ToolExecutionError("c64_graphics op generate_bitmap is not yet available", {
-            details: { available: false },
-        })),
+        op: "render_bitmap",
+        schema: extendSchemaWithOp("render_bitmap", ensureDescriptor(graphicsDescriptorIndex, "render_bitmap").inputSchema, { description: "Import an image file, convert it to VIC-II bitmap memory, write it into RAM, and display it." }),
+        handler: groupedGraphicsHandlers.render_bitmap,
     },
 ];
 const graphicsOperationHandlers = createOperationHandlers(graphicsOperations);
 export const graphicsModuleGroup = defineToolModule({
     domain: "graphics",
-    summary: "Grouped PETSCII, sprite, and upcoming bitmap helpers.",
+    summary: "Grouped frame capture and graphics rendering helpers.",
     resources: ["c64://specs/vic", "c64://specs/basic", "c64://specs/assembly"],
     prompts: ["graphics-demo", "basic-program", "assembly-program"],
     defaultTags: ["graphics", "vic"],
     workflowHints: [
-        "Use PETSCII helpers for text art and clarify whether the BASIC program executed or stayed a dry run.",
+        "Use render helpers for PETSCII text, PETSCII art, sprites, and bitmaps; clarify whether PETSCII art executed or stayed a dry run.",
         "Mention sprite positions/colours so follow-up memory inspection stays grounded.",
     ],
     supportedPlatforms: ["c64u", "vice"],
     tools: [
         {
             name: "c64_graphics",
-            description: "Grouped entry point for PETSCII art, sprite previews, and future bitmap generation.",
-            summary: "Generates PETSCII art, renders text screens, or runs sprite demos from one tool.",
+            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({
                 description: "Graphics operations available via the c64_graphics tool.",
                 variants: graphicsOperations.map((operation) => operation.schema),
             }),
             tags: ["graphics", "vic", "grouped"],
             examples: [
+                {
+                    name: "Capture one frame",
+                    description: "Grab the current framebuffer from the active backend",
+                    arguments: { op: "capture_frame" },
+                },
                 {
                     name: "Create PETSCII art (dry run)",
                     description: "Synthesize art without uploading to the C64",
-                    arguments: { op: "create_petscii", prompt: "duck on a pond", dryRun: true },
+                    arguments: { op: "render_petscii_art", prompt: "duck on a pond", dryRun: true },
                 },
                 {
                     name: "Render PETSCII text",
                     description: "Print HELLO with blue border",
-                    arguments: { op: "render_petscii", text: "HELLO", borderColor: 6 },
+                    arguments: { op: "render_petscii_text", text: "HELLO", borderColor: 6 },
                 },
                 {
                     name: "Display sprite",
                     description: "Show sprite data at coordinates",
-                    arguments: { op: "generate_sprite", sprite: "AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA" },
+                    arguments: { op: "render_sprite", sprite: "AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA" },
+                },
+                {
+                    name: "Import bitmap image",
+                    description: "Convert a PNG into VIC bitmap memory and display it",
+                    arguments: { op: "render_bitmap", imagePath: "./artifacts/sample.png", format: "hires" },
                 },
             ],
             execute: createOperationDispatcher("c64_graphics", graphicsOperationHandlers),

package/dist/tools/registry/index.js

@@ -3,6 +3,7 @@ import { programModule } from "./program.js";
 import { memoryModuleGroup as memoryModule } from "./memory.js";
 import { soundModuleGroup as soundModule } from "./sound.js";
 import { systemModuleGroup as systemModule } from "./system.js";
+import { platformModuleGroup } from "./platform.js";
 import { graphicsModuleGroup as graphicsModule } from "./graphics.js";
 import { ragModuleGroup as ragModule } from "./rag.js";
 import { diskModuleGroup as diskModule } from "./disk.js";
@@ -11,11 +12,14 @@ import { printerModuleGroup as printerModule } from "./printer.js";
 import { configModuleGroup as configModule } from "./config.js";
 import { extractModule } from "./extract.js";
 import { streamModule } from "./stream.js";
+import { debugModuleGroup as debugModule } from "../debug.js";
+import { viceModuleGroup as viceModule } from "../vice.js";
 const modules = [
     programModule,
     memoryModule,
     soundModule,
     systemModule,
+    platformModuleGroup,
     graphicsModule,
     ragModule,
     diskModule,
@@ -24,6 +28,8 @@ const modules = [
     configModule,
     extractModule,
     streamModule,
+    debugModule,
+    viceModule,
 ];
 const toolMap = new Map();
 for (const module of modules) {

package/dist/tools/registry/memory.js

@@ -30,6 +30,7 @@ const memoryOperationHandlers = createOperationHandlers(memoryOperations);
 export const memoryModuleGroup = defineToolModule({
     domain: "memory",
     summary: "Grouped memory, screen, and polling operations.",
+    supportedPlatforms: ["c64u", "vice"],
     resources: ["c64://context/bootstrap", "c64://specs/basic", "c64://specs/assembly"],
     prompts: ["memory-debug", "basic-program", "assembly-program"],
     defaultTags: ["memory", "debug"],

package/dist/tools/registry/platform.js

@@ -0,0 +1,121 @@
+import { describePlatformCapabilities } from "../../platform.js";
+import { debugModuleGroup as debugModule } from "../debug.js";
+import { viceModuleGroup as viceModule } from "../vice.js";
+import { jsonResult } from "../responses.js";
+import { createOperationDispatcher, defineToolModule, discriminatedUnionSchema, operationSchema, } from "../types.js";
+import { configModuleGroup as configModule } from "./config.js";
+import { diskModuleGroup as diskModule } from "./disk.js";
+import { driveModuleGroup as driveModule } from "./drive.js";
+import { extractModule } from "./extract.js";
+import { graphicsModuleGroup as graphicsModule } from "./graphics.js";
+import { memoryModuleGroup as memoryModule } from "./memory.js";
+import { printerModuleGroup as printerModule } from "./printer.js";
+import { programModule } from "./program.js";
+import { ragModuleGroup as ragModule } from "./rag.js";
+import { soundModuleGroup as soundModule } from "./sound.js";
+import { streamModule } from "./stream.js";
+import { systemModuleGroup as systemModule } from "./system.js";
+const registryModules = [
+    programModule,
+    memoryModule,
+    soundModule,
+    systemModule,
+    graphicsModule,
+    ragModule,
+    diskModule,
+    driveModule,
+    printerModule,
+    configModule,
+    extractModule,
+    streamModule,
+    debugModule,
+    viceModule,
+];
+function listRegisteredDescriptors() {
+    return [
+        ...registryModules.flatMap((module) => module.describeTools()),
+        ...platformModuleGroup.describeTools(),
+    ];
+}
+function describeTargetPlatform(target) {
+    const capabilities = describePlatformCapabilities(listRegisteredDescriptors());
+    const info = capabilities.platforms[target];
+    return {
+        availableTools: info.tools,
+        unavailableTools: info.unsupported_tools,
+    };
+}
+const selectBackendSchema = operationSchema("select", {
+    description: "Switch the active runtime backend without restarting the MCP server.",
+    properties: {
+        backend: {
+            type: "string",
+            enum: ["c64u", "vice"],
+            description: "Backend to activate for subsequent tool calls.",
+        },
+    },
+    required: ["backend"],
+});
+const platformOperationHandlers = {
+    async select(args, ctx) {
+        const backend = args.backend;
+        const availableBackends = ctx.client.getAvailableBackends().slice().sort();
+        if (!availableBackends.includes(backend)) {
+            const data = {
+                success: false,
+                requestedBackend: backend,
+                configuredBackends: availableBackends,
+                message: `Backend '${backend}' is not configured. Available backends: ${availableBackends.join(", ") || "none"}.`,
+                usageHint: "Use c64_select_backend with one of the configured backends when you want to switch later.",
+            };
+            return {
+                ...jsonResult(data, { success: false }),
+                isError: true,
+            };
+        }
+        ctx.client.switchBackend(backend);
+        ctx.setPlatform(backend);
+        const { availableTools, unavailableTools } = describeTargetPlatform(backend);
+        const switchBackTarget = backend === "c64u" ? "vice" : "c64u";
+        const data = {
+            success: true,
+            activeBackend: backend,
+            configuredBackends: availableBackends,
+            availableTools,
+            unavailableTools,
+            usageHint: `Use c64_select_backend again with backend: "${switchBackTarget}" to switch back.`,
+        };
+        return jsonResult(data, { success: true });
+    },
+};
+export const platformModuleGroup = defineToolModule({
+    domain: "platform",
+    summary: "Runtime backend selection and platform-status coordination.",
+    supportedPlatforms: ["c64u", "vice"],
+    resources: ["c64://platform/status", "c64://context/bootstrap"],
+    prompts: [],
+    defaultTags: ["platform", "backend", "grouped"],
+    workflowHints: [
+        "Switch backends before invoking backend-specific tools so platform gating stays accurate.",
+    ],
+    tools: [
+        {
+            name: "c64_select_backend",
+            description: "Switch the active backend between C64U hardware and the VICE emulator at runtime.",
+            summary: "Changes the active backend without restarting the MCP server and reports resulting tool availability.",
+            inputSchema: discriminatedUnionSchema({
+                description: "Runtime backend selection operations.",
+                variants: [selectBackendSchema],
+            }),
+            tags: ["platform", "backend", "switch"],
+            execute: createOperationDispatcher("c64_select_backend", platformOperationHandlers),
+            examples: [
+                {
+                    name: "Switch to VICE",
+                    description: "Move subsequent tool calls to the emulator backend",
+                    arguments: { op: "select", backend: "vice" },
+                },
+            ],
+        },
+    ],
+});

package/dist/tools/registry/program.js

@@ -1,5 +1,5 @@
 import { createOperationDispatcher, defineToolModule, discriminatedUnionSchema, } from "../types.js";
-import { programRunnersModule, programOperationHandlers as groupedProgramHandlers } from "../programRunners.js";
+import { programRunnersModule } from "../programRunners.js";
 import { metaModule } from "../meta/index.js";
 import { buildDescriptorIndex, ensureDescriptor, extendSchemaWithOp, createOperationHandlers, invokeModuleTool, } from "./utils.js";
 const programDescriptorIndex = buildDescriptorIndex(programRunnersModule);
@@ -8,27 +8,27 @@ const programOperations = [
     {
         op: "load_prg",
         schema: extendSchemaWithOp("load_prg", ensureDescriptor(programDescriptorIndex, "load_prg").inputSchema, { description: "Load a PRG from Ultimate storage without executing it." }),
-        handler: groupedProgramHandlers.load_prg,
+        handler: async (rawArgs, ctx) => invokeModuleTool(programRunnersModule, "load_prg", rawArgs, ctx),
     },
     {
         op: "run_prg",
-        schema: extendSchemaWithOp("run_prg", ensureDescriptor(programDescriptorIndex, "run_prg").inputSchema, { description: "Load and execute a PRG located on the Ultimate filesystem." }),
-        handler: groupedProgramHandlers.run_prg,
+        schema: extendSchemaWithOp("run_prg", ensureDescriptor(programDescriptorIndex, "run_prg").inputSchema, { description: "Load and execute a PRG from Ultimate-visible storage on c64u or a host-local path on VICE." }),
+        handler: async (rawArgs, ctx) => invokeModuleTool(programRunnersModule, "run_prg", rawArgs, ctx),
     },
     {
         op: "run_crt",
         schema: extendSchemaWithOp("run_crt", ensureDescriptor(programDescriptorIndex, "run_crt").inputSchema, { description: "Mount and run a CRT cartridge image." }),
-        handler: groupedProgramHandlers.run_crt,
+        handler: async (rawArgs, ctx) => invokeModuleTool(programRunnersModule, "run_crt", rawArgs, ctx),
     },
     {
         op: "upload_run_basic",
         schema: extendSchemaWithOp("upload_run_basic", ensureDescriptor(programDescriptorIndex, "upload_run_basic").inputSchema, { description: "Upload Commodore BASIC v2 source and execute it immediately." }),
-        handler: groupedProgramHandlers.upload_run_basic,
+        handler: async (rawArgs, ctx) => invokeModuleTool(programRunnersModule, "upload_run_basic", rawArgs, ctx),
     },
     {
         op: "upload_run_asm",
         schema: extendSchemaWithOp("upload_run_asm", ensureDescriptor(programDescriptorIndex, "upload_run_asm").inputSchema, { description: "Assemble 6502/6510 source, upload the PRG, and execute it." }),
-        handler: groupedProgramHandlers.upload_run_asm,
+        handler: async (rawArgs, ctx) => invokeModuleTool(programRunnersModule, "upload_run_asm", rawArgs, ctx),
     },
     {
         op: "batch_run",
@@ -40,6 +40,11 @@ const programOperations = [
         schema: extendSchemaWithOp("bundle_run", ensureDescriptor(metaDescriptorIndex, "bundle_run_artifacts").inputSchema, { description: "Capture screen, memory, and debug registers into an artifact bundle." }),
         handler: async (rawArgs, ctx) => invokeModuleTool(metaModule, "bundle_run_artifacts", rawArgs, ctx),
     },
+    {
+        op: "cross_platform_greeting",
+        schema: extendSchemaWithOp("cross_platform_greeting", ensureDescriptor(metaDescriptorIndex, "cross_platform_greeting").inputSchema, { description: "Show a platform-customized greeting on one or more configured backends, capture screenshots, and verify the results." }),
+        handler: async (rawArgs, ctx) => invokeModuleTool(metaModule, "cross_platform_greeting", rawArgs, ctx),
+    },
 ];
 const programOperationHandlers = createOperationHandlers(programOperations);
 export const programModule = defineToolModule({
@@ -50,7 +55,8 @@ export const programModule = defineToolModule({
     defaultTags: ["programs", "execution"],
     workflowHints: [
         "Choose BASIC or assembly uploaders based on the language you just generated for the user.",
-        "Prefer PRG or CRT runners when the user supplies an Ultimate filesystem path instead of source text.",
+        "Prefer PRG or CRT runners when the user supplies a file path instead of source text; PRG paths are host-local on VICE and Ultimate-visible on c64u.",
+        "For a quick visible confirmation on VICE and/or C64U, prefer cross_platform_greeting instead of composing manual backend switches and BASIC upload steps.",
     ],
     supportedPlatforms: ["c64u", "vice"],
     tools: [
@@ -63,6 +69,13 @@ export const programModule = defineToolModule({
                 variants: programOperations.map((operation) => operation.schema),
             }),
             tags: ["programs", "execution", "grouped"],
+            operationPlatforms: { load_prg: ["c64u"], run_crt: ["c64u"], bundle_run: ["c64u"] },
+            operationToolNames: {
+                load_prg: "load_prg",
+                run_crt: "run_crt",
+                bundle_run: "bundle_run_artifacts",
+                cross_platform_greeting: "cross_platform_greeting",
+            },
             examples: [
                 {
                     name: "Run PRG from storage",
@@ -74,6 +87,11 @@ export const programModule = defineToolModule({
                     description: "Send inline BASIC to the C64 and run it",
                     arguments: { op: "upload_run_basic", program: "10 PRINT \"HELLO\"\n20 GOTO 10" },
                 },
+                {
+                    name: "Show greeting on both backends",
+                    description: "Render a platform-specific greeting on VICE and C64U with screenshot verification",
+                    arguments: { op: "cross_platform_greeting" },
+                },
             ],
             execute: createOperationDispatcher("c64_program", programOperationHandlers),
         },

package/dist/tools/registry/sound.js

@@ -1,10 +1,74 @@
+import { Buffer } from "node:buffer";
 import { createOperationDispatcher, defineToolModule, discriminatedUnionSchema, } from "../types.js";
 import { audioModule } from "../audio.js";
 import { metaModule } from "../meta/index.js";
+import { literalSchema, numberSchema, objectSchema, optionalSchema, stringSchema, } from "../schema.js";
 import { buildDescriptorIndex, ensureDescriptor, extendSchemaWithOp, createOperationHandlers, invokeModuleTool, } from "./utils.js";
+import { ToolError, toolErrorResult, unknownErrorResult, } from "../errors.js";
+import { jsonResult } from "../responses.js";
 const audioDescriptorIndex = buildDescriptorIndex(audioModule);
 const metaDescriptorIndex = buildDescriptorIndex(metaModule);
+const captureSamplesArgsSchema = objectSchema({
+    description: "Capture raw stereo PCM samples from the C64 Ultimate audio UDP stream.",
+    properties: {
+        op: literalSchema("capture_samples"),
+        count: optionalSchema(numberSchema({
+            description: "Number of stereo sample pairs to capture.",
+            integer: true,
+            minimum: 1,
+            maximum: 65536,
+            default: 256,
+        }), 256),
+        encoding: optionalSchema(stringSchema({
+            description: "Encoding used for the PCM sample payload.",
+            enum: ["base64", "hex"],
+            default: "base64",
+        }), "base64"),
+    },
+    required: ["op"],
+    additionalProperties: false,
+});
 const soundOperations = [
+    {
+        op: "capture_samples",
+        schema: captureSamplesArgsSchema.jsonSchema,
+        handler: async (rawArgs, ctx) => {
+            try {
+                const parsed = captureSamplesArgsSchema.parse(rawArgs);
+                ctx.logger.info("Capturing audio samples", {
+                    count: parsed.count,
+                    encoding: parsed.encoding,
+                });
+                const capture = await ctx.client.captureSamples({ count: parsed.count });
+                const samplesBuffer = Buffer.from(capture.samples.buffer, capture.samples.byteOffset, capture.samples.byteLength);
+                return jsonResult({
+                    backend: capture.backend,
+                    channels: capture.channels,
+                    sampleRateHz: capture.sampleRateHz,
+                    samplePairs: capture.samplePairs,
+                    byteLength: samplesBuffer.length,
+                    samples: {
+                        encoding: parsed.encoding,
+                        data: parsed.encoding === "hex"
+                            ? samplesBuffer.toString("hex")
+                            : samplesBuffer.toString("base64"),
+                    },
+                }, {
+                    success: true,
+                    backend: capture.backend,
+                    samplePairs: capture.samplePairs,
+                    sampleRateHz: capture.sampleRateHz,
+                    channels: capture.channels,
+                });
+            }
+            catch (error) {
+                if (error instanceof ToolError) {
+                    return toolErrorResult(error);
+                }
+                return unknownErrorResult(error);
+            }
+        },
+    },
     {
         op: "set_volume",
         schema: extendSchemaWithOp("set_volume", ensureDescriptor(audioDescriptorIndex, "sid_volume").inputSchema, { description: "Set the SID master volume register at $D418 (0-15)." }),
@@ -50,6 +114,11 @@ const soundOperations = [
         schema: extendSchemaWithOp("compile_play", ensureDescriptor(audioDescriptorIndex, "music_compile_and_play").inputSchema, { description: "Compile SIDWAVE or CPG source and optionally play it immediately." }),
         handler: async (rawArgs, ctx) => invokeModuleTool(audioModule, "music_compile_and_play", rawArgs, ctx),
     },
+    {
+        op: "play_preset",
+        schema: extendSchemaWithOp("play_preset", ensureDescriptor(metaDescriptorIndex, "music_play_preset").inputSchema, { description: "Compile and play a built-in SID preset such as Für Elise by Beethoven." }),
+        handler: async (rawArgs, ctx) => invokeModuleTool(metaModule, "music_play_preset", rawArgs, ctx),
+    },
     {
         op: "pipeline",
         schema: extendSchemaWithOp("pipeline", ensureDescriptor(metaDescriptorIndex, "music_compile_play_analyze").inputSchema, { description: "Compile a SIDWAVE score, play it, and analyze the recording." }),
@@ -70,6 +139,7 @@ const soundOperationHandlers = createOperationHandlers(soundOperations);
 export const soundModuleGroup = defineToolModule({
     domain: "audio",
     summary: "Grouped SID control, playback, composition, and analysis operations.",
+    supportedPlatforms: ["c64u", "vice"],
     resources: ["c64://specs/sid", "c64://specs/sidwave", "c64://docs/sid/file-structure"],
     prompts: ["sid-music"],
     defaultTags: ["sid", "audio"],
@@ -87,12 +157,38 @@ export const soundModuleGroup = defineToolModule({
                 variants: soundOperations.map((operation) => operation.schema),
             }),
             tags: ["sid", "audio", "grouped"],
+            operationPlatforms: {
+                capture_samples: ["c64u"],
+                play_sid_file: ["c64u"],
+                play_mod_file: ["c64u"],
+                pipeline: ["c64u"],
+                analyze: ["c64u"],
+                record_analyze: ["c64u"],
+            },
+            operationToolNames: {
+                play_sid_file: "sidplay_file",
+                play_mod_file: "modplay_file",
+                play_preset: "music_play_preset",
+                pipeline: "music_compile_play_analyze",
+                analyze: "analyze_audio",
+                record_analyze: "record_and_analyze_audio",
+            },
             examples: [
+                {
+                    name: "Capture samples",
+                    description: "Grab 256 stereo sample pairs from the Ultimate audio stream",
+                    arguments: { op: "capture_samples" },
+                },
                 {
                     name: "Trigger SID voice",
                     description: "Start voice 1 on C4 with a triangle waveform",
                     arguments: { op: "note_on", voice: 1, note: "C4", waveform: "tri" },
                 },
+                {
+                    name: "Play Für Elise",
+                    description: "Compile and play the built-in Für Elise preset on the active backend",
+                    arguments: { op: "play_preset", preset: "fuer_elise" },
+                },
                 {
                     name: "Verify silence",
                     description: "Stop all voices and confirm the SID output is quiet",

package/dist/tools/registry/system.js

@@ -7,12 +7,12 @@ const metaDescriptorIndex = buildDescriptorIndex(metaModule);
 const systemOperations = [
     {
         op: "pause",
-        schema: extendSchemaWithOp("pause", ensureDescriptor(machineDescriptorIndex, "pause").inputSchema, { description: "Pause the machine using DMA halt until resumed." }),
+        schema: extendSchemaWithOp("pause", ensureDescriptor(machineDescriptorIndex, "pause").inputSchema, { description: "Pause the machine until resumed." }),
         handler: async (rawArgs, ctx) => invokeModuleTool(machineControlModule, "pause", rawArgs, ctx),
     },
     {
         op: "resume",
-        schema: extendSchemaWithOp("resume", ensureDescriptor(machineDescriptorIndex, "resume").inputSchema, { description: "Resume CPU execution after a DMA pause." }),
+        schema: extendSchemaWithOp("resume", ensureDescriptor(machineDescriptorIndex, "resume").inputSchema, { description: "Resume CPU execution after a pause." }),
         handler: async (rawArgs, ctx) => invokeModuleTool(machineControlModule, "resume", rawArgs, ctx),
     },
     {
@@ -55,11 +55,17 @@ const systemOperations = [
         schema: extendSchemaWithOp("list_tasks", ensureDescriptor(metaDescriptorIndex, "list_background_tasks").inputSchema, { description: "List known background tasks with status metadata." }),
         handler: async (rawArgs, ctx) => invokeModuleTool(metaModule, "list_background_tasks", rawArgs, ctx),
     },
+    {
+        op: "performance_report",
+        schema: extendSchemaWithOp("performance_report", ensureDescriptor(metaDescriptorIndex, "performance_report").inputSchema, { description: "Summarize diagnostics spans and tool latencies from the current or latest MCP session." }),
+        handler: async (rawArgs, ctx) => invokeModuleTool(metaModule, "performance_report", rawArgs, ctx),
+    },
 ];
 const systemOperationHandlers = createOperationHandlers(systemOperations);
 export const systemModuleGroup = defineToolModule({
     domain: "system",
     summary: "Grouped machine control and background task orchestration.",
+    supportedPlatforms: ["c64u", "vice"],
     resources: ["c64://context/bootstrap"],
     prompts: ["memory-debug"],
     defaultTags: ["system", "control"],
@@ -77,6 +83,8 @@ export const systemModuleGroup = defineToolModule({
                 variants: systemOperations.map((operation) => operation.schema),
             }),
             tags: ["system", "control", "grouped"],
+            operationPlatforms: { pause: ["c64u"], resume: ["c64u"], menu: ["c64u"] },
+            operationToolNames: { pause: "pause", resume: "resume", menu: "menu_button" },
             examples: [
                 {
                     name: "Soft reset",
@@ -93,6 +101,11 @@ export const systemModuleGroup = defineToolModule({
                         intervalMs: 2000,
                     },
                 },
+                {
+                    name: "Inspect performance trace",
+                    description: "Summarize the current session diagnostics for profiling",
+                    arguments: { op: "performance_report", scope: "current" },
+                },
             ],
             execute: createOperationDispatcher("c64_system", systemOperationHandlers),
         },

package/dist/tools/storage.js

@@ -143,6 +143,7 @@ const createDnpArgsSchema = objectSchema({
 export const storageModule = defineToolModule({
     domain: "storage",
     summary: "Drive management, disk image creation, and file inspection utilities.",
+    supportedPlatforms: ["c64u", "vice"],
     resources: ["c64://context/bootstrap"],
     prompts: ["memory-debug"],
     defaultTags: ["drive", "storage"],

package/dist/tools/streaming.js

@@ -42,6 +42,7 @@ export const streamingModule = defineToolModule({
     prompts: ["sid-music"],
     defaultLifecycle: "stream",
     defaultTags: ["stream", "monitoring"],
+    supportedPlatforms: ["c64u"],
     workflowHints: [
         "Use streaming tools for long-running capture or monitoring workflows such as audio verification.",
         "Clarify that streams keep running until stopped so the user can manage resources.",