c64bridge 0.7.4 → 0.8.1

package/dist/tools/meta/program.js

@@ -5,6 +5,178 @@ import { promises as fs } from "node:fs";
 import { resolve as resolvePath, join as joinPath } from "node:path";
 import { sleep, formatTimestampSpec } from "./util.js";
 import { getTasksHomeDir } from "./background.js";
+import { Jimp } from "jimp";
+import { withDiagnosticSpan } from "../../diagnostics.js";
+const C64_SCREENSHOT_PALETTE = [
+    0x000000ff,
+    0xffffffff,
+    0x813338ff,
+    0x75cec8ff,
+    0x8e3c97ff,
+    0x56ac4dff,
+    0x2e2c9bff,
+    0xedf171ff,
+    0x8e5029ff,
+    0x553800ff,
+    0xc46c71ff,
+    0x4a4a4aff,
+    0x7b7b7bff,
+    0xa9ff9fff,
+    0x706debff,
+    0xb2b2b2ff,
+];
+function hasOwnProperty(value, key) {
+    return Object.prototype.hasOwnProperty.call(value, key);
+}
+function isVisibleViceSessionPreferred() {
+    const visible = String(process.env.VICE_VISIBLE ?? "true").trim().toLowerCase();
+    const forceXvfb = String(process.env.FORCE_XVFB ?? "0").trim().toLowerCase();
+    const disableXvfb = String(process.env.DISABLE_XVFB ?? "0").trim().toLowerCase();
+    if (forceXvfb === "1" || forceXvfb === "true" || forceXvfb === "yes") {
+        return false;
+    }
+    if (disableXvfb === "1" || disableXvfb === "true" || disableXvfb === "yes") {
+        return visible !== "0" && visible !== "false" && visible !== "no";
+    }
+    return visible !== "0" && visible !== "false" && visible !== "no";
+}
+function shouldUseVisibleViceGreetingFastPath(rawArgs, requestedBackends) {
+    if (!rawArgs || typeof rawArgs !== "object" || Array.isArray(rawArgs)) {
+        return false;
+    }
+    if (requestedBackends.length !== 1 || requestedBackends[0] !== "vice") {
+        return false;
+    }
+    if (!isVisibleViceSessionPreferred()) {
+        return false;
+    }
+    const args = rawArgs;
+    return !hasOwnProperty(args, "verify")
+        && !hasOwnProperty(args, "captureScreenshot")
+        && !hasOwnProperty(args, "outputPath");
+}
+function canonicalGreetingBackends() {
+    return ["vice", "c64u"];
+}
+function uniqueGreetingBackends(backends) {
+    return backends.filter((backend, index) => backends.indexOf(backend) === index);
+}
+function normaliseScreenText(screen) {
+    return screen.replace(/\r\n?/g, "\n").replace(/\s+/g, " ").trim().toUpperCase();
+}
+function screenContainsExpectedText(screen, expectedText) {
+    return normaliseScreenText(screen).includes(normaliseScreenText(expectedText));
+}
+function applyGreetingTemplate(template, backend) {
+    const upper = backend.toUpperCase();
+    const lower = backend.toLowerCase();
+    return template
+        .replace(/\{PLATFORM\}/g, upper)
+        .replace(/\{BACKEND\}/g, upper)
+        .replace(/\{platform\}/g, lower)
+        .replace(/\{backend\}/g, lower);
+}
+function escapeBasicString(value) {
+    return value.replace(/"/g, '""');
+}
+function buildGreetingProgram(message) {
+    return [
+        "10 PRINT CHR$(147)",
+        `20 PRINT \"${escapeBasicString(message)}\"`,
+        "30 END",
+    ].join("\n");
+}
+function analyseCapturedFrame(frame) {
+    const totalPixels = Math.max(1, frame.width * frame.height);
+    let nonBackgroundPixels = 0;
+    const uniqueColors = new Set();
+    if (frame.bitsPerPixel === 4 || frame.bitsPerPixel === 8) {
+        for (let index = 0; index < totalPixels; index += 1) {
+            const value = frame.pixels[index] ?? 0;
+            uniqueColors.add(value);
+            if (value !== 0) {
+                nonBackgroundPixels += 1;
+            }
+        }
+    }
+    else {
+        const bytesPerPixel = frame.bitsPerPixel >= 24 && frame.bitsPerPixel % 8 === 0
+            ? frame.bitsPerPixel / 8
+            : 0;
+        if (bytesPerPixel > 0) {
+            for (let index = 0; index < totalPixels; index += 1) {
+                const offset = index * bytesPerPixel;
+                const red = frame.pixels[offset] ?? 0;
+                const green = frame.pixels[offset + 1] ?? 0;
+                const blue = frame.pixels[offset + 2] ?? 0;
+                const alpha = bytesPerPixel >= 4 ? (frame.pixels[offset + 3] ?? 255) : 255;
+                uniqueColors.add(((red & 0xff) << 24) | ((green & 0xff) << 16) | ((blue & 0xff) << 8) | (alpha & 0xff));
+                if (red !== 0 || green !== 0 || blue !== 0) {
+                    nonBackgroundPixels += 1;
+                }
+            }
+        }
+    }
+    const nonBackgroundRatio = Number((nonBackgroundPixels / totalPixels).toFixed(4));
+    return {
+        width: frame.width,
+        height: frame.height,
+        bitsPerPixel: frame.bitsPerPixel,
+        complete: frame.complete,
+        totalPixels,
+        nonBackgroundPixels,
+        nonBackgroundRatio,
+        uniqueColorCount: uniqueColors.size,
+        looksNonBlank: nonBackgroundPixels >= Math.max(1, Math.floor(totalPixels * 0.005)),
+    };
+}
+function indexedFrameColour(value) {
+    return C64_SCREENSHOT_PALETTE[value & 0x0f] ?? C64_SCREENSHOT_PALETTE[0];
+}
+function rgbaToJimpColour(red, green, blue, alpha = 255) {
+    return (((red & 0xff) << 24) | ((green & 0xff) << 16) | ((blue & 0xff) << 8) | (alpha & 0xff)) >>> 0;
+}
+async function writeCapturedFramePng(frame, filePath) {
+    const image = new Jimp({ width: frame.width, height: frame.height, color: C64_SCREENSHOT_PALETTE[0] });
+    const totalPixels = frame.width * frame.height;
+    if (frame.bitsPerPixel === 4 || frame.bitsPerPixel === 8) {
+        for (let index = 0; index < totalPixels; index += 1) {
+            image.setPixelColor(indexedFrameColour(frame.pixels[index] ?? 0), index % frame.width, Math.floor(index / frame.width));
+        }
+        await image.write(filePath);
+        return;
+    }
+    const bytesPerPixel = frame.bitsPerPixel >= 24 && frame.bitsPerPixel % 8 === 0
+        ? frame.bitsPerPixel / 8
+        : 0;
+    for (let index = 0; index < totalPixels; index += 1) {
+        const x = index % frame.width;
+        const y = Math.floor(index / frame.width);
+        if (bytesPerPixel === 3 || bytesPerPixel === 4) {
+            const offset = index * bytesPerPixel;
+            image.setPixelColor(rgbaToJimpColour(frame.pixels[offset] ?? 0, frame.pixels[offset + 1] ?? 0, frame.pixels[offset + 2] ?? 0, bytesPerPixel === 4 ? (frame.pixels[offset + 3] ?? 255) : 255), x, y);
+            continue;
+        }
+        const value = frame.pixels[index] ?? 0;
+        image.setPixelColor(rgbaToJimpColour(value, value, value), x, y);
+    }
+    await image.write(filePath);
+}
+async function waitForGreetingScreen(ctx, expectedText, timeoutMs, pollIntervalMs) {
+    const deadline = Date.now() + timeoutMs;
+    let lastScreen = "";
+    while (Date.now() <= deadline) {
+        lastScreen = await ctx.client.readScreen();
+        if (screenContainsExpectedText(lastScreen, expectedText)) {
+            return { matched: true, screen: lastScreen };
+        }
+        if (Date.now() + pollIntervalMs > deadline) {
+            break;
+        }
+        await sleep(pollIntervalMs);
+    }
+    return { matched: false, screen: lastScreen };
+}
 const programShuffleArgsSchema = objectSchema({
     description: "Discover PRG/CRT files under root path, run each for a duration, capture screen, then reset.",
     properties: {
@@ -49,7 +221,308 @@ const batchRunWithAssertionsArgsSchema = objectSchema({
     required: ["programs"],
     additionalProperties: false,
 });
+const crossPlatformGreetingArgsSchema = objectSchema({
+    description: "Show a platform-customized greeting on one or more backends, capture screenshots, and verify the result.",
+    properties: {
+        platforms: optionalSchema(arraySchema(stringSchema({
+            description: "Backends to target in sequence.",
+            enum: ["vice", "c64u"],
+            minLength: 1,
+        })), ["vice", "c64u"]),
+        messageTemplate: optionalSchema(stringSchema({
+            description: "Greeting template. Use {PLATFORM}/{BACKEND} for uppercase or {platform}/{backend} for lowercase substitution.",
+            minLength: 1,
+        }), "HAVE A GREAT DAY, {PLATFORM}!"),
+        verify: optionalSchema(booleanSchema({
+            description: "Poll the text screen and require the rendered greeting to appear.",
+            default: true,
+        }), true),
+        captureScreenshot: optionalSchema(booleanSchema({
+            description: "Capture a framebuffer screenshot and save it as a PNG per backend.",
+            default: true,
+        }), true),
+        outputPath: optionalSchema(stringSchema({
+            description: "Directory for screenshots and the workflow summary JSON.",
+            minLength: 1,
+        })),
+        restoreActiveBackend: optionalSchema(booleanSchema({
+            description: "Restore the backend that was active before the workflow started.",
+            default: true,
+        }), true),
+        timeoutMs: optionalSchema(numberSchema({
+            description: "Maximum time to wait for each greeting to appear on screen.",
+            integer: true,
+            minimum: 100,
+            maximum: 5000,
+            default: 1500,
+        }), 1500),
+        pollIntervalMs: optionalSchema(numberSchema({
+            description: "Delay between screen polls while verifying the greeting.",
+            integer: true,
+            minimum: 50,
+            maximum: 1000,
+            default: 100,
+        }), 100),
+    },
+    required: [],
+    additionalProperties: false,
+});
 export const tools = [
+    {
+        name: "cross_platform_greeting",
+        description: "Render a customized greeting on VICE and/or C64U, capture screenshots, and verify both results in one workflow.",
+        summary: "One-call cross-platform greeting demo with backend switching, screenshot capture, and text-screen verification.",
+        inputSchema: crossPlatformGreetingArgsSchema.jsonSchema,
+        tags: ["orchestration", "demo", "screenshots", "verification"],
+        examples: [
+            {
+                name: "Greet both backends",
+                description: "Show a platform-specific greeting on VICE and C64U in one call.",
+                arguments: { op: "cross_platform_greeting" },
+            },
+            {
+                name: "Custom template on VICE",
+                description: "Render a custom greeting only on the emulator.",
+                arguments: {
+                    op: "cross_platform_greeting",
+                    platforms: ["vice"],
+                    messageTemplate: "HELLO FROM {PLATFORM}!",
+                },
+            },
+        ],
+        async execute(args, ctx) {
+            try {
+                const toolStartedAt = Date.now();
+                const parsed = crossPlatformGreetingArgsSchema.parse(args ?? {});
+                const availableBackends = uniqueGreetingBackends(canonicalGreetingBackends().filter((backend) => ctx.client.getAvailableBackends().includes(backend)));
+                const requestedBackends = uniqueGreetingBackends((parsed.platforms ?? availableBackends));
+                const missingBackends = requestedBackends.filter((backend) => !availableBackends.includes(backend));
+                if (missingBackends.length > 0) {
+                    throw new ToolExecutionError("Requested greeting backends are not configured", {
+                        details: {
+                            requestedBackends,
+                            availableBackends,
+                            missingBackends,
+                        },
+                    });
+                }
+                if (requestedBackends.length === 0) {
+                    throw new ToolExecutionError("No configured backends are available for the greeting workflow", {
+                        details: { availableBackends },
+                    });
+                }
+                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
+                    ? resolvePath(String(parsed.outputPath ?? joinPath(process.cwd(), "artifacts", "greetings", `run_${Date.now()}`)))
+                    : undefined;
+                const timeoutMs = parsed.timeoutMs ?? 1500;
+                const pollIntervalMs = parsed.pollIntervalMs ?? 100;
+                const template = parsed.messageTemplate ?? "HAVE A GREAT DAY, {PLATFORM}!";
+                const startingBackend = await ctx.client.getActiveBackendType();
+                const results = [];
+                let restoreError;
+                let restoreBackendLatencyMs = 0;
+                if (outputPath) {
+                    await fs.mkdir(outputPath, { recursive: true });
+                }
+                try {
+                    for (const backend of requestedBackends) {
+                        const expectedText = applyGreetingTemplate(template, backend);
+                        const program = buildGreetingProgram(expectedText);
+                        const timeline = [];
+                        let executionMode = "direct_screen_write";
+                        let preparedCaptureSession = false;
+                        const client = ctx.client;
+                        const timedStep = async (name, fn) => {
+                            const startedAt = Date.now();
+                            try {
+                                const result = await withDiagnosticSpan("greeting", name, { backend }, fn);
+                                timeline.push({ name, latencyMs: Date.now() - startedAt, ok: true });
+                                return result;
+                            }
+                            catch (error) {
+                                timeline.push({
+                                    name,
+                                    latencyMs: Date.now() - startedAt,
+                                    ok: false,
+                                    error: error instanceof Error ? error.message : String(error),
+                                });
+                                throw error;
+                            }
+                        };
+                        await timedStep("switch_backend", async () => {
+                            ctx.client.switchBackend(backend);
+                            ctx.setPlatform(backend);
+                        });
+                        let prepareCapturePromise;
+                        if (captureScreenshot && backend === "c64u" && typeof client.prepareVideoCapture === "function") {
+                            prepareCapturePromise = timedStep("prepare_capture", async () => {
+                                await client.prepareVideoCapture?.({ keepAliveMs: Math.max(500, timeoutMs) });
+                                preparedCaptureSession = true;
+                            }).catch(() => {
+                                preparedCaptureSession = false;
+                            });
+                        }
+                        const runResult = await timedStep("render_greeting_screen", async () => {
+                            if (typeof client.renderGreetingScreen === "function") {
+                                executionMode = "direct_screen_write";
+                                return client.renderGreetingScreen({ message: expectedText });
+                            }
+                            executionMode = "basic_program";
+                            return ctx.client.uploadAndRunBasic(program);
+                        });
+                        if (prepareCapturePromise) {
+                            await prepareCapturePromise;
+                        }
+                        const backendResult = {
+                            backend,
+                            expectedText,
+                            program,
+                            executionMode,
+                            timeline,
+                        };
+                        if (!runResult.success) {
+                            if (preparedCaptureSession && typeof client.releaseVideoCapture === "function") {
+                                try {
+                                    await timedStep("release_capture", () => client.releaseVideoCapture?.());
+                                }
+                                catch {
+                                    // Preserve the original render failure and best-effort cleanup.
+                                }
+                            }
+                            backendResult.success = false;
+                            backendResult.error = "basic_run_failed";
+                            backendResult.details = runResult.details ?? null;
+                            results.push(backendResult);
+                            continue;
+                        }
+                        let screen = "";
+                        let screenMatched = false;
+                        if (verify) {
+                            const waited = await timedStep("verify_screen", () => waitForGreetingScreen(ctx, expectedText, timeoutMs, pollIntervalMs));
+                            screen = waited.screen;
+                            screenMatched = waited.matched;
+                        }
+                        backendResult.screen = screen;
+                        let screenshotPath;
+                        let screenshotAnalysis;
+                        let screenshotError;
+                        if (captureScreenshot) {
+                            try {
+                                const capture = await timedStep("capture_screenshot", () => client.captureFrames({
+                                    count: 1,
+                                    reuseSession: preparedCaptureSession,
+                                    keepAliveMs: preparedCaptureSession ? Math.max(500, timeoutMs) : 0,
+                                }));
+                                const frame = capture.frames[0];
+                                if (!frame) {
+                                    throw new Error("No video frame returned by backend capture");
+                                }
+                                await timedStep("persist_screenshot", async () => {
+                                    screenshotAnalysis = analyseCapturedFrame(frame);
+                                    screenshotPath = outputPath
+                                        ? resolvePath(joinPath(outputPath, `${backend}.png`))
+                                        : undefined;
+                                    if (screenshotPath) {
+                                        await writeCapturedFramePng(frame, screenshotPath);
+                                    }
+                                });
+                            }
+                            catch (error) {
+                                screenshotError = error instanceof Error ? error.message : String(error);
+                            }
+                            finally {
+                                if (preparedCaptureSession && typeof client.releaseVideoCapture === "function") {
+                                    try {
+                                        await timedStep("release_capture", () => client.releaseVideoCapture?.());
+                                    }
+                                    catch {
+                                        // Surface screenshot failures, but do not overwrite a successful capture result.
+                                    }
+                                }
+                            }
+                        }
+                        backendResult.verification = {
+                            screenContainsExpectedText: verify ? screenMatched : undefined,
+                            screenshotCaptured: captureScreenshot ? !screenshotError : undefined,
+                            screenshotAnalysis,
+                        };
+                        if (screenshotPath) {
+                            backendResult.screenshotPath = screenshotPath;
+                        }
+                        if (screenshotError) {
+                            backendResult.screenshotError = screenshotError;
+                        }
+                        backendResult.success = runResult.success
+                            && (!verify || screenMatched)
+                            && (!captureScreenshot || !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);
+                        backendResult.totalLatencyMs = timeline
+                            .filter((entry) => entry.ok === true)
+                            .reduce((total, entry) => total + Number(entry.latencyMs ?? 0), 0);
+                        results.push(backendResult);
+                    }
+                }
+                finally {
+                    if (restoreActiveBackend) {
+                        try {
+                            const restoreStartedAt = Date.now();
+                            await withDiagnosticSpan("greeting", "restore_backend", { backend: startingBackend }, async () => {
+                                ctx.client.switchBackend(startingBackend);
+                                ctx.setPlatform(startingBackend);
+                            });
+                            restoreBackendLatencyMs = Date.now() - restoreStartedAt;
+                        }
+                        catch (error) {
+                            restoreError = error instanceof Error ? error.message : String(error);
+                        }
+                    }
+                }
+                const toolCallLatencyMs = Date.now() - toolStartedAt;
+                const backendTimedLatencyMs = results
+                    .map((result) => Number(result.totalLatencyMs ?? 0))
+                    .reduce((total, latency) => total + latency, 0);
+                const orchestrationOverheadMs = Math.max(0, toolCallLatencyMs - backendTimedLatencyMs - restoreBackendLatencyMs);
+                const success = results.every((result) => result.success === true) && !restoreError;
+                const payload = {
+                    kind: "cross_platform_greeting",
+                    availableBackends,
+                    requestedBackends,
+                    startingBackend,
+                    restoredBackend: restoreActiveBackend ? startingBackend : await ctx.client.getActiveBackendType(),
+                    outputPath: outputPath ?? null,
+                    fastPath: visibleViceFastPath ? "visible_vice_no_probe" : null,
+                    toolCallLatencyMs,
+                    restoreBackendLatencyMs,
+                    orchestrationOverheadMs,
+                    results,
+                    ...(restoreError ? { restoreError } : {}),
+                };
+                if (outputPath) {
+                    const reportPath = resolvePath(joinPath(outputPath, "results.json"));
+                    await fs.writeFile(reportPath, JSON.stringify(payload, null, 2), "utf8");
+                    payload.outputPath = outputPath;
+                    payload.reportPath = reportPath;
+                }
+                const result = jsonResult(payload, {
+                    success,
+                    backends: requestedBackends,
+                    outputPath: outputPath ?? null,
+                });
+                return success ? result : { ...result, isError: true };
+            }
+            catch (error) {
+                if (error instanceof ToolError)
+                    return toolErrorResult(error);
+                return unknownErrorResult(error);
+            }
+        },
+    },
     {
         name: "program_shuffle",
         description: "Discover and run PRG/CRT programs under a root path, capturing screens and resetting between runs.",

package/dist/tools/pollValidator.js

@@ -202,8 +202,10 @@ async function pollAsmOutcome(client, logger, config) {
             const lowMemAndScreen = await client.readMemoryRaw(0x0000, 0x7E8); // $0000-$07E7
             // Extract jiffy clock for separate comparison (at offset $00A0 in the buffer)
             const jiffyClock = lowMemAndScreen.slice(0xA0, 0xA3);
-            // Concatenate all regions and compute signature
-            const combinedBuffer = concatBuffers(ioRegions, lowMemAndScreen);
+            // Exclude the jiffy clock from the broad signature so it can be tracked separately.
+            const lowMemSignatureBuffer = lowMemAndScreen.slice();
+            lowMemSignatureBuffer.fill(0, 0xA0, 0xA3);
+            const combinedBuffer = concatBuffers(ioRegions, lowMemSignatureBuffer);
             const ioSignature = computeCrc32(combinedBuffer);
             // Check for any activity
             if (prevIoSignature !== null && ioSignature !== prevIoSignature) {

package/dist/tools/programRunners.js

@@ -24,6 +24,8 @@ function toRecord(details) {
     return { value: details };
 }
 const BASIC_MAX_LINE = 63999;
+const prgPathDescription = "Path to the PRG image. Use an Ultimate-visible filesystem path on c64u, or a host-local filesystem path on VICE.";
+const crtPathDescription = "Path to the CRT image on Ultimate-visible storage. CRT mounting is only supported on c64u.";
 function stripOperationDiscriminator(value) {
     const { [OPERATION_DISCRIMINATOR]: _ignored, ...rest } = value;
     return rest;
@@ -213,10 +215,10 @@ const uploadAsmArgsSchema = objectSchema({
     additionalProperties: false,
 });
 const prgFileArgsSchema = objectSchema({
-    description: "Arguments for loading or running a PRG that already exists on the Ultimate filesystem.",
+    description: "Arguments for loading or running a PRG file.",
     properties: {
         path: stringSchema({
-            description: "Absolute or Ultimate filesystem path to the PRG file (e.g. //USB0/demo.prg).",
+            description: prgPathDescription,
             minLength: 1,
         }),
     },
@@ -224,10 +226,10 @@ const prgFileArgsSchema = objectSchema({
     additionalProperties: false,
 });
 const crtFileArgsSchema = objectSchema({
-    description: "Arguments for running a CRT image stored on the Ultimate filesystem.",
+    description: "Arguments for running a CRT image stored on Ultimate-visible storage.",
     properties: {
         path: stringSchema({
-            description: "Absolute or Ultimate filesystem path to the CRT file (e.g. //USB0/game.crt).",
+            description: crtPathDescription,
             minLength: 1,
         }),
     },
@@ -676,6 +678,7 @@ export const programRunnersModule = defineToolModule({
                 "Stage PRG files without running when the user wants to inspect memory first.",
                 "Confirm the Ultimate filesystem path (e.g. //USB0/demo.prg) is accessible before invoking.",
             ],
+            supportedPlatforms: ["c64u"],
             async execute(args, ctx) {
                 return executeLoadPrg(args, ctx);
             },
@@ -723,6 +726,7 @@ export const programRunnersModule = defineToolModule({
                     arguments: { path: "//USB0/game.crt" },
                 },
             ],
+            supportedPlatforms: ["c64u"],
             async execute(args, ctx) {
                 try {
                     const parsed = crtFileArgsSchema.parse(args ?? {});

package/dist/tools/registry/config.js

@@ -154,6 +154,7 @@ export const configModuleGroup = defineToolModule({
     resources: ["c64://context/bootstrap", "c64://docs/index"],
     prompts: ["memory-debug"],
     defaultTags: ["config", "diagnostics"],
+    supportedPlatforms: ["c64u", "vice"],
     workflowHints: [
         "List categories before changing values so users can confirm firmware-provided names.",
         "Mention when operations persist to flash or modify debug registers to highlight impacts.",
@@ -169,6 +170,22 @@ export const configModuleGroup = defineToolModule({
                 variants: configOperations.map((operation) => operation.schema),
             }),
             tags: ["config", "diagnostics", "grouped"],
+            operationPlatforms: {
+                load_flash: ["c64u"],
+                save_flash: ["c64u"],
+                reset_defaults: ["c64u"],
+                read_debugreg: ["c64u"],
+                write_debugreg: ["c64u"],
+                shuffle: ["c64u"],
+            },
+            operationToolNames: {
+                load_flash: "config_load_from_flash",
+                save_flash: "config_save_to_flash",
+                reset_defaults: "config_reset_to_default",
+                read_debugreg: "debugreg_read",
+                write_debugreg: "debugreg_write",
+                shuffle: "program_shuffle",
+            },
             examples: [
                 {
                     name: "List categories",

package/dist/tools/registry/disk.js

@@ -251,6 +251,7 @@ const diskOperationHandlers = createOperationHandlers(diskOperations);
 export const diskModuleGroup = defineToolModule({
     domain: "storage",
     summary: "Grouped disk image management, mounting, and discovery tools.",
+    supportedPlatforms: ["c64u", "vice"],
     resources: ["c64://context/bootstrap"],
     prompts: ["drive-management"],
     defaultTags: ["storage", "drive"],
@@ -268,6 +269,12 @@ export const diskModuleGroup = defineToolModule({
                 variants: diskOperations.map((operation) => operation.schema),
             }),
             tags: ["storage", "drive", "grouped"],
+            operationPlatforms: { file_info: ["c64u"], create_image: ["c64u"], find_and_run: ["c64u"] },
+            operationToolNames: {
+                file_info: "file_info",
+                create_image: "create_image",
+                find_and_run: "find_and_run_program_by_name",
+            },
             examples: [
                 {
                     name: "Mount image with verification",

package/dist/tools/registry/drive.js

@@ -33,6 +33,7 @@ const driveOperationHandlers = createOperationHandlers(driveOperations);
 export const driveModuleGroup = defineToolModule({
     domain: "drive",
     summary: "Grouped drive power, reset, ROM, and mode helpers.",
+    supportedPlatforms: ["c64u", "vice"],
     resources: ["c64://context/bootstrap"],
     defaultTags: ["drive", "hardware"],
     workflowHints: [
@@ -49,6 +50,8 @@ export const driveModuleGroup = defineToolModule({
                 variants: driveOperations.map((operation) => operation.schema),
             }),
             tags: ["drive", "hardware", "grouped"],
+            operationPlatforms: { load_rom: ["c64u"] },
+            operationToolNames: { load_rom: "drive_load_rom" },
             examples: [
                 {
                     name: "Power on drive",