c64bridge 0.7.4 → 0.8.0

package/dist/tools/types.js

@@ -1,4 +1,5 @@
 import { getPlatformStatus, isPlatformSupported, setPlatform, } from "../platform.js";
+import { withDiagnosticSpan } from "../diagnostics.js";
 import { ToolUnsupportedPlatformError, ToolValidationError } from "./errors.js";
 export const OPERATION_DISCRIMINATOR = "op";
 export const VERIFY_PROPERTY_NAME = "verify";
@@ -48,7 +49,7 @@ export function createOperationDispatcher(toolName, handlers) {
         const record = args;
         const opValue = record[OPERATION_DISCRIMINATOR];
         if (typeof opValue !== "string" || opValue.length === 0) {
-            throw new ToolValidationError(`${toolName} requires an ${OPERATION_DISCRIMINATOR} string to select an operation`, { path: `$.${OPERATION_DISCRIMINATOR}` });
+            throw new ToolValidationError(`${toolName} is a grouped tool and requires an ${OPERATION_DISCRIMINATOR} string to select an operation`, { path: `$.${OPERATION_DISCRIMINATOR}`, details: { allowed } });
         }
         const opKey = opValue;
         const handler = handlers[opKey];
@@ -90,6 +91,7 @@ export function defineToolModule(config) {
                     ...(workflowHints ? { workflowHints } : {}),
                     ...(prerequisites ? { prerequisites } : {}),
                     ...(platforms ? { platforms } : {}),
+                    ...(tool.operationPlatforms ? { operationPlatforms: tool.operationPlatforms } : {}),
                 };
                 return {
                     name: tool.name,
@@ -104,21 +106,53 @@ export function defineToolModule(config) {
             if (!tool) {
                 throw new Error(`Unknown tool: ${name}`);
             }
-            const platforms = mergePlatforms(defaultPlatforms, tool.supportedPlatforms) ?? defaultPlatforms;
+            const platforms = resolveSupportedPlatforms(tool, args, defaultPlatforms);
             const status = ctx.platform ?? getPlatformStatus();
             const setter = ctx.setPlatform ?? setPlatform;
             if (!isPlatformSupported(status.id, platforms)) {
-                throw new ToolUnsupportedPlatformError(name, status.id, platforms);
+                throw new ToolUnsupportedPlatformError(resolveUnsupportedToolName(name, tool, args), status.id, platforms);
             }
             const enrichedCtx = {
                 ...ctx,
                 platform: status,
                 setPlatform: setter,
             };
-            return tool.execute(args, enrichedCtx);
+            return withDiagnosticSpan("tool", `${config.domain}.${name}`, {
+                domain: config.domain,
+                tool: name,
+                operation: getSelectedOperation(args) ?? null,
+                platform: status.id,
+            }, () => tool.execute(args, enrichedCtx));
         },
     };
 }
+function resolveSupportedPlatforms(tool, args, defaultPlatforms) {
+    const basePlatforms = mergePlatforms(defaultPlatforms, tool.supportedPlatforms) ?? defaultPlatforms;
+    const operation = getSelectedOperation(args);
+    if (!operation) {
+        return basePlatforms;
+    }
+    const operationPlatforms = tool.operationPlatforms?.[operation];
+    return operationPlatforms && operationPlatforms.length > 0 ? operationPlatforms : basePlatforms;
+}
+function resolveUnsupportedToolName(toolName, tool, args) {
+    const operation = getSelectedOperation(args);
+    if (!operation) {
+        return toolName;
+    }
+    const mappedName = tool.operationToolNames?.[operation];
+    if (mappedName) {
+        return mappedName;
+    }
+    return tool.operationPlatforms?.[operation] ? operation : toolName;
+}
+function getSelectedOperation(args) {
+    if (typeof args !== "object" || args === null) {
+        return undefined;
+    }
+    const op = args[OPERATION_DISCRIMINATOR];
+    return typeof op === "string" && op.length > 0 ? op : undefined;
+}
 function mergeUnique(base, extra) {
     if (!extra || extra.length === 0) {
         return base;

package/dist/tools/vice.js

@@ -0,0 +1,160 @@
+import { createOperationDispatcher, defineToolModule, discriminatedUnionSchema, } from "./types.js";
+import { literalSchema, objectSchema, stringSchema, } from "./schema.js";
+import { jsonResult, textResult } from "./responses.js";
+import { ToolError, ToolExecutionError, ToolValidationError, toolErrorResult, unknownErrorResult, } from "./errors.js";
+const RESOURCE_NAME_PATTERN = /^[A-Z][A-Za-z0-9_.-]{0,63}$/;
+const SAFE_RESOURCE_PREFIXES = [
+    "C64",
+    "Machine",
+    "Sid",
+    "VIC",
+    "VICII",
+    "CIA",
+    "Joy",
+    "Sound",
+];
+const resourceValueSchema = {
+    jsonSchema: {
+        description: "VICE resource value (string or integer).",
+        oneOf: [
+            { type: "string" },
+            { type: "integer" },
+        ],
+    },
+    parse(value, path) {
+        const resolvedPath = path ?? "$.value";
+        if (typeof value === "string") {
+            return value;
+        }
+        if (typeof value === "number" && Number.isInteger(value)) {
+            return value;
+        }
+        throw new ToolValidationError("Resource value must be a string or integer", {
+            path: resolvedPath,
+            details: { receivedType: typeof value },
+        });
+    },
+};
+const resourceNameSchema = stringSchema({
+    description: "VICE resource name (example: SidEngine, C64Model).",
+    minLength: 1,
+    maxLength: 64,
+    pattern: RESOURCE_NAME_PATTERN,
+});
+const resourceGetArgsSchema = objectSchema({
+    description: "Read a VICE configuration resource (safe prefixes only).",
+    properties: {
+        op: literalSchema("resource_get"),
+        name: resourceNameSchema,
+    },
+    required: ["op", "name"],
+    additionalProperties: false,
+});
+const resourceSetArgsSchema = objectSchema({
+    description: "Write a VICE configuration resource (safe prefixes only).",
+    properties: {
+        op: literalSchema("resource_set"),
+        name: resourceNameSchema,
+        value: resourceValueSchema,
+    },
+    required: ["op", "name", "value"],
+    additionalProperties: false,
+});
+const viceOperationSchemas = [
+    resourceGetArgsSchema,
+    resourceSetArgsSchema,
+];
+const viceOperationHandlers = {
+    resource_get: async (args, ctx) => {
+        try {
+            const parsed = resourceGetArgsSchema.parse(args);
+            ensureSafeResourceName(parsed.name, "$.name");
+            ctx.logger.info("Reading VICE resource", { name: parsed.name });
+            const value = await ctx.client.viceResourceGet(parsed.name);
+            if (value.type === "string" && value.value.length === 0) {
+                throw new ToolExecutionError(`VICE resource ${parsed.name} is not available or returned an empty value`, {
+                    details: { name: parsed.name },
+                });
+            }
+            return jsonResult({
+                name: parsed.name,
+                type: value.type,
+                value: value.value,
+            }, { success: true, name: parsed.name, type: value.type });
+        }
+        catch (error) {
+            return handleToolError(error);
+        }
+    },
+    resource_set: async (args, ctx) => {
+        try {
+            const parsed = resourceSetArgsSchema.parse(args);
+            ensureSafeResourceName(parsed.name, "$.name");
+            ctx.logger.info("Writing VICE resource", {
+                name: parsed.name,
+                valueType: typeof parsed.value,
+            });
+            await ctx.client.viceResourceSet(parsed.name, parsed.value);
+            return textResult(`Updated VICE resource ${parsed.name}.`, {
+                success: true,
+                name: parsed.name,
+                value: parsed.value,
+            });
+        }
+        catch (error) {
+            return handleToolError(error);
+        }
+    },
+};
+const viceOperationDispatcher = createOperationDispatcher("c64_vice", viceOperationHandlers);
+export const viceModuleGroup = defineToolModule({
+    domain: "vice",
+    summary: "VICE emulator helpers for safe runtime resource access.",
+    resources: ["c64://specs/memory-map"],
+    prompts: ["assembly-program", "memory-debug"],
+    defaultTags: ["vice", "emulator"],
+    workflowHints: [
+        "Use emulator helpers when running on VICE to inspect or tweak safe runtime resources.",
+        "Explain that resource changes only persist for the current emulator session unless saved in VICE manually.",
+    ],
+    supportedPlatforms: ["vice"],
+    tools: [
+        {
+            name: "c64_vice",
+            description: "Grouped entry point for reading and updating selected VICE resources.",
+            summary: "Reads or updates selected VICE resources that are safe to expose through MCP.",
+            inputSchema: discriminatedUnionSchema({
+                description: "VICE emulator operations available via the c64_vice tool.",
+                variants: viceOperationSchemas.map((schema) => schema.jsonSchema),
+            }),
+            tags: ["vice", "resource", "grouped"],
+            examples: [
+                {
+                    name: "Read SID engine",
+                    description: "Inspect the active SID emulation mode.",
+                    arguments: { op: "resource_get", name: "SidEngine" },
+                },
+                {
+                    name: "Set SID engine",
+                    description: "Switch SID emulation to resid-fp (value 2).",
+                    arguments: { op: "resource_set", name: "SidEngine", value: 2 },
+                },
+            ],
+            execute: viceOperationDispatcher,
+        },
+    ],
+});
+function handleToolError(error) {
+    if (error instanceof ToolError) {
+        return toolErrorResult(error);
+    }
+    return unknownErrorResult(error);
+}
+function ensureSafeResourceName(name, path) {
+    if (!RESOURCE_NAME_PATTERN.test(name)) {
+        throw new ToolValidationError("Resource names must start with an uppercase letter and use letters, numbers, dashes, underscores, or periods.", { path, details: { name } });
+    }
+    if (!SAFE_RESOURCE_PREFIXES.some((prefix) => name.startsWith(prefix))) {
+        throw new ToolValidationError(`Resource name must start with one of: ${SAFE_RESOURCE_PREFIXES.join(", ")}`, { path, details: { name } });
+    }
+}

package/dist/vicBitmap.js

@@ -0,0 +1,317 @@
+import { Jimp } from "jimp";
+const VIC_BANK_SIZE = 0x4000;
+const BITMAP_BYTE_LENGTH = 8000;
+const SCREEN_RAM_BYTE_LENGTH = 1000;
+const COLOR_RAM_BYTE_LENGTH = 1000;
+const COLOR_RAM_ADDRESS = 0xD800;
+const VIC_PALETTE = [
+    [0x00, 0x00, 0x00],
+    [0xFF, 0xFF, 0xFF],
+    [0x81, 0x33, 0x38],
+    [0x75, 0xCE, 0xC8],
+    [0x8E, 0x3C, 0x97],
+    [0x56, 0xAC, 0x4D],
+    [0x2E, 0x2C, 0x9B],
+    [0xED, 0xF1, 0x71],
+    [0x8E, 0x50, 0x29],
+    [0x55, 0x38, 0x00],
+    [0xC4, 0x6C, 0x71],
+    [0x4A, 0x4A, 0x4A],
+    [0x7B, 0x7B, 0x7B],
+    [0xA9, 0xFF, 0x9F],
+    [0x70, 0x6D, 0xEB],
+    [0xB2, 0xB2, 0xB2],
+];
+export async function importImageAsVicBitmap(options) {
+    const image = await Jimp.read(options.imagePath);
+    const sourceWidth = image.bitmap.width;
+    const sourceHeight = image.bitmap.height;
+    const logicalWidth = options.mode === "multicolor" ? 160 : 320;
+    const logicalHeight = 200;
+    const backgroundColor = normaliseColorIndex(options.backgroundColor ?? 0);
+    const borderColor = normaliseColorIndex(options.borderColor ?? backgroundColor);
+    const rgba = await renderImageToLogicalCanvas(image, {
+        width: logicalWidth,
+        height: logicalHeight,
+        preserveAspect: options.preserveAspect !== false,
+        backgroundColor,
+    });
+    const prepared = convertRgbaToVicBitmap(rgba, {
+        mode: options.mode,
+        backgroundColor,
+        borderColor,
+    });
+    return {
+        ...prepared,
+        sourceWidth,
+        sourceHeight,
+    };
+}
+export function convertRgbaToVicBitmap(image, options) {
+    if (image.width <= 0 || image.height <= 0) {
+        throw new Error("Bitmap image must have positive dimensions");
+    }
+    if (image.data.length !== image.width * image.height * 4) {
+        throw new Error("RGBA image buffer length must equal width * height * 4");
+    }
+    const backgroundColor = normaliseColorIndex(options.backgroundColor ?? 0);
+    const borderColor = normaliseColorIndex(options.borderColor ?? backgroundColor);
+    const quantized = quantizeRgbaImage(image, backgroundColor);
+    return options.mode === "multicolor"
+        ? convertMulticolorBitmap(quantized, backgroundColor, borderColor)
+        : convertHiresBitmap(quantized, backgroundColor, borderColor);
+}
+export function resolveVicBitmapMemoryLayout(bitmapAddress = 0x2000, screenAddress = 0x0400) {
+    validateAddress(bitmapAddress, BITMAP_BYTE_LENGTH, "bitmapAddress");
+    validateAddress(screenAddress, SCREEN_RAM_BYTE_LENGTH, "screenAddress");
+    const bank = Math.floor(bitmapAddress / VIC_BANK_SIZE);
+    const bankBase = bank * VIC_BANK_SIZE;
+    if (Math.floor(screenAddress / VIC_BANK_SIZE) !== bank) {
+        throw new Error("Bitmap RAM and screen RAM must be within the same 16 KB VIC bank");
+    }
+    const bitmapOffset = bitmapAddress - bankBase;
+    const screenOffset = screenAddress - bankBase;
+    if (bitmapOffset !== 0x0000 && bitmapOffset !== 0x2000) {
+        throw new Error("Bitmap RAM must be aligned to $0000 or $2000 within the selected VIC bank");
+    }
+    if (screenOffset % 0x0400 !== 0) {
+        throw new Error("Screen RAM must be aligned to a 1 KB boundary within the selected VIC bank");
+    }
+    if (screenOffset > 0x3C00) {
+        throw new Error("Screen RAM must fit entirely inside the selected VIC bank");
+    }
+    if (rangesOverlap(bitmapAddress, BITMAP_BYTE_LENGTH, screenAddress, SCREEN_RAM_BYTE_LENGTH)) {
+        throw new Error("Bitmap RAM and screen RAM must not overlap");
+    }
+    const screenNibble = ((screenOffset / 0x0400) & 0x0F) << 4;
+    const bitmapBit = bitmapOffset === 0x2000 ? 0x08 : 0x00;
+    return {
+        bank,
+        bankBase,
+        bitmapAddress,
+        screenAddress,
+        colorRamAddress: COLOR_RAM_ADDRESS,
+        d018: screenNibble | bitmapBit,
+    };
+}
+export function buildVicBitmapRegisters(layout, options) {
+    const backgroundColor = normaliseColorIndex(options.backgroundColor ?? 0);
+    const borderColor = normaliseColorIndex(options.borderColor ?? backgroundColor);
+    const bankBits = (~layout.bank) & 0x03;
+    return {
+        dd00: ((options.currentDd00 ?? 0) & 0xFC) | bankBits,
+        d011: 0x3B,
+        d016: options.mode === "multicolor" ? 0x18 : 0x08,
+        d018: layout.d018,
+        d020: borderColor,
+        d021: backgroundColor,
+    };
+}
+async function renderImageToLogicalCanvas(image, options) {
+    const background = paletteColorToJimp(normaliseColorIndex(options.backgroundColor));
+    if (!options.preserveAspect) {
+        const stretched = image.clone().resize({ w: options.width, h: options.height });
+        return {
+            width: stretched.bitmap.width,
+            height: stretched.bitmap.height,
+            data: Uint8Array.from(stretched.bitmap.data),
+        };
+    }
+    const scale = Math.min(options.width / image.bitmap.width, options.height / image.bitmap.height);
+    const renderWidth = Math.max(1, Math.round(image.bitmap.width * scale));
+    const renderHeight = Math.max(1, Math.round(image.bitmap.height * scale));
+    const resized = image.clone().resize({ w: renderWidth, h: renderHeight });
+    const canvas = new Jimp({ width: options.width, height: options.height, color: background });
+    const offsetX = Math.floor((options.width - renderWidth) / 2);
+    const offsetY = Math.floor((options.height - renderHeight) / 2);
+    canvas.composite(resized, offsetX, offsetY);
+    return {
+        width: canvas.bitmap.width,
+        height: canvas.bitmap.height,
+        data: Uint8Array.from(canvas.bitmap.data),
+    };
+}
+function quantizeRgbaImage(image, transparentColor) {
+    const quantized = new Uint8Array(image.width * image.height);
+    for (let index = 0; index < quantized.length; index += 1) {
+        const offset = index * 4;
+        const r = image.data[offset] ?? 0;
+        const g = image.data[offset + 1] ?? 0;
+        const b = image.data[offset + 2] ?? 0;
+        const a = image.data[offset + 3] ?? 0xFF;
+        quantized[index] = a < 64 ? transparentColor : nearestPaletteIndex(r, g, b);
+    }
+    return quantized;
+}
+function convertHiresBitmap(quantized, backgroundColor, borderColor) {
+    if (quantized.length !== 320 * 200) {
+        throw new Error("Hi-res bitmap conversion requires a 320x200 logical image");
+    }
+    const bitmapData = new Uint8Array(BITMAP_BYTE_LENGTH);
+    const screenRam = new Uint8Array(SCREEN_RAM_BYTE_LENGTH);
+    const colorRam = new Uint8Array(COLOR_RAM_BYTE_LENGTH);
+    for (let cellY = 0; cellY < 25; cellY += 1) {
+        for (let cellX = 0; cellX < 40; cellX += 1) {
+            const cellIndex = (cellY * 40) + cellX;
+            const [background, foreground] = pickDominantColors(quantized, 320, cellX * 8, cellY * 8, 8, 8, 2);
+            screenRam[cellIndex] = ((foreground & 0x0F) << 4) | (background & 0x0F);
+            colorRam[cellIndex] = backgroundColor & 0x0F;
+            for (let row = 0; row < 8; row += 1) {
+                let byte = 0;
+                for (let col = 0; col < 8; col += 1) {
+                    const pixelIndex = ((cellY * 8 + row) * 320) + (cellX * 8 + col);
+                    const pixelColor = quantized[pixelIndex] ?? background;
+                    const bit = chooseNearestCandidate(pixelColor, [background, foreground]) === foreground ? 1 : 0;
+                    byte = (byte << 1) | bit;
+                }
+                bitmapData[(cellIndex * 8) + row] = byte;
+            }
+        }
+    }
+    return {
+        mode: "hires",
+        sourceWidth: 320,
+        sourceHeight: 200,
+        logicalWidth: 320,
+        logicalHeight: 200,
+        displayWidth: 320,
+        displayHeight: 200,
+        backgroundColor,
+        borderColor,
+        bitmapData,
+        screenRam,
+        colorRam,
+    };
+}
+function convertMulticolorBitmap(quantized, backgroundColor, borderColor) {
+    if (quantized.length !== 160 * 200) {
+        throw new Error("Multicolor bitmap conversion requires a 160x200 logical image");
+    }
+    const bitmapData = new Uint8Array(BITMAP_BYTE_LENGTH);
+    const screenRam = new Uint8Array(SCREEN_RAM_BYTE_LENGTH);
+    const colorRam = new Uint8Array(COLOR_RAM_BYTE_LENGTH);
+    for (let cellY = 0; cellY < 25; cellY += 1) {
+        for (let cellX = 0; cellX < 40; cellX += 1) {
+            const cellIndex = (cellY * 40) + cellX;
+            const selected = fillMissingColors(pickDominantColors(quantized, 160, cellX * 4, cellY * 8, 4, 8, 3, backgroundColor), backgroundColor);
+            const color01 = selected[0];
+            const color10 = selected[1];
+            const color11 = selected[2];
+            screenRam[cellIndex] = ((color01 & 0x0F) << 4) | (color10 & 0x0F);
+            colorRam[cellIndex] = color11 & 0x0F;
+            for (let row = 0; row < 8; row += 1) {
+                let byte = 0;
+                for (let col = 0; col < 4; col += 1) {
+                    const pixelIndex = ((cellY * 8 + row) * 160) + (cellX * 4 + col);
+                    const pixelColor = quantized[pixelIndex] ?? backgroundColor;
+                    const nearest = chooseNearestCandidate(pixelColor, [backgroundColor, color01, color10, color11]);
+                    const code = nearest === color01 ? 0x01 : nearest === color10 ? 0x02 : nearest === color11 ? 0x03 : 0x00;
+                    byte = (byte << 2) | code;
+                }
+                bitmapData[(cellIndex * 8) + row] = byte;
+            }
+        }
+    }
+    return {
+        mode: "multicolor",
+        sourceWidth: 160,
+        sourceHeight: 200,
+        logicalWidth: 160,
+        logicalHeight: 200,
+        displayWidth: 320,
+        displayHeight: 200,
+        backgroundColor,
+        borderColor,
+        bitmapData,
+        screenRam,
+        colorRam,
+    };
+}
+function pickDominantColors(quantized, stride, startX, startY, width, height, count, excludedColor) {
+    const counts = new Uint32Array(16);
+    for (let y = 0; y < height; y += 1) {
+        for (let x = 0; x < width; x += 1) {
+            const color = quantized[((startY + y) * stride) + startX + x] ?? 0;
+            if (color === excludedColor) {
+                continue;
+            }
+            counts[color] += 1;
+        }
+    }
+    const ranked = Array.from({ length: 16 }, (_, color) => color)
+        .filter((color) => counts[color] > 0)
+        .sort((left, right) => {
+        const countDiff = counts[right] - counts[left];
+        return countDiff !== 0 ? countDiff : left - right;
+    });
+    if (excludedColor === undefined && ranked.length === 1) {
+        ranked.push(ranked[0]);
+    }
+    return ranked.slice(0, count);
+}
+function fillMissingColors(colors, fallback) {
+    const values = [...colors];
+    while (values.length < 3) {
+        values.push(fallback);
+    }
+    return [values[0] ?? fallback, values[1] ?? fallback, values[2] ?? fallback];
+}
+function chooseNearestCandidate(color, candidates) {
+    let best = candidates[0] ?? 0;
+    let bestDistance = Number.POSITIVE_INFINITY;
+    for (const candidate of candidates) {
+        const distance = paletteDistance(color, candidate);
+        if (distance < bestDistance) {
+            best = candidate;
+            bestDistance = distance;
+        }
+    }
+    return best;
+}
+function nearestPaletteIndex(red, green, blue) {
+    let bestIndex = 0;
+    let bestDistance = Number.POSITIVE_INFINITY;
+    for (let index = 0; index < VIC_PALETTE.length; index += 1) {
+        const [candidateRed, candidateGreen, candidateBlue] = VIC_PALETTE[index];
+        const distance = squaredDistance(red, green, blue, candidateRed, candidateGreen, candidateBlue);
+        if (distance < bestDistance) {
+            bestIndex = index;
+            bestDistance = distance;
+        }
+    }
+    return bestIndex;
+}
+function paletteDistance(left, right) {
+    const [leftRed, leftGreen, leftBlue] = VIC_PALETTE[left] ?? VIC_PALETTE[0];
+    const [rightRed, rightGreen, rightBlue] = VIC_PALETTE[right] ?? VIC_PALETTE[0];
+    return squaredDistance(leftRed, leftGreen, leftBlue, rightRed, rightGreen, rightBlue);
+}
+function squaredDistance(leftRed, leftGreen, leftBlue, rightRed, rightGreen, rightBlue) {
+    const red = leftRed - rightRed;
+    const green = leftGreen - rightGreen;
+    const blue = leftBlue - rightBlue;
+    return (red * red) + (green * green) + (blue * blue);
+}
+function paletteColorToJimp(index) {
+    const [red, green, blue] = VIC_PALETTE[index] ?? VIC_PALETTE[0];
+    return (red << 24) | (green << 16) | (blue << 8) | 0xFF;
+}
+function normaliseColorIndex(value) {
+    if (!Number.isInteger(value) || value < 0 || value > 15) {
+        throw new Error(`VIC colour indices must be integers between 0 and 15 (received ${value})`);
+    }
+    return value;
+}
+function validateAddress(address, length, label) {
+    if (!Number.isInteger(address) || address < 0 || address > 0xFFFF) {
+        throw new Error(`${label} must be an integer address within $0000-$FFFF`);
+    }
+    if (address + length - 1 > 0xFFFF) {
+        throw new Error(`${label} range must fit within 64 KB address space`);
+    }
+}
+function rangesOverlap(leftStart, leftLength, rightStart, rightLength) {
+    const leftEnd = leftStart + leftLength - 1;
+    const rightEnd = rightStart + rightLength - 1;
+    return leftStart <= rightEnd && rightStart <= leftEnd;
+}