c64bridge 1.0.3 → 1.0.5

package/dist/tools/meta/memory.js

@@ -5,14 +5,13 @@ import { promises as fs } from "node:fs";
 import { dirname, resolve as resolvePath } from "node:path";
 import { createHash } from "node:crypto";
 import { normalizeErrorDetails } from "./util.js";
+import { stripHexByteSeparators } from "../hex.js";
 function supportsMachinePause(ctx) {
     const platformId = ctx.platform?.id ?? ctx.client?.type;
     return platformId !== "vice";
 }
 function hexClean(input) {
-    const trimmed = input.trim();
-    const withoutPrefix = trimmed.startsWith("$") ? trimmed.slice(1) : trimmed;
-    return withoutPrefix.replace(/[\s_]/g, "").toLowerCase();
+    return stripHexByteSeparators(input).toLowerCase();
 }
 function hexToBytes(input) {
     const cleaned = hexClean(input);
@@ -31,21 +30,16 @@ function parseAddressNumeric(value) {
         throw new ToolValidationError("Address must be a non-empty string", { path: "$.address" });
     }
     const lower = value.trim().toLowerCase();
-    let radix = 10;
-    let literal = lower;
-    if (lower.startsWith("$")) {
-        radix = 16;
-        literal = lower.slice(1);
-    }
-    else if (lower.startsWith("0x")) {
-        radix = 16;
-        literal = lower.slice(2);
-    }
-    else if (lower.startsWith("%")) {
-        radix = 2;
-        literal = lower.slice(1);
-    }
-    const parsed = Number.parseInt(literal, radix);
+    // Anchored patterns: Number.parseInt alone would read "$20ZZ" as $0020.
+    let parsed = Number.NaN;
+    if (/^\$[0-9a-f]+$/.test(lower))
+        parsed = Number.parseInt(lower.slice(1), 16);
+    else if (/^0x[0-9a-f]+$/.test(lower))
+        parsed = Number.parseInt(lower.slice(2), 16);
+    else if (/^%[01]+$/.test(lower))
+        parsed = Number.parseInt(lower.slice(1), 2);
+    else if (/^[0-9]+$/.test(lower))
+        parsed = Number.parseInt(lower, 10);
     if (!Number.isFinite(parsed) || Number.isNaN(parsed) || parsed < 0 || parsed > 0xFFFF) {
         throw new ToolValidationError("Invalid address value", { path: "$.address", details: { value } });
     }

package/dist/tools/meta/program.js

@@ -1,12 +1,14 @@
 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";
 import { getTasksHomeDir } from "./background.js";
 import { Jimp } from "jimp";
 import { withDiagnosticSpan } from "../../diagnostics.js";
+import { stripHexByteSeparators } from "../hex.js";
 const C64_SCREENSHOT_PALETTE = [
     0x000000ff,
     0xffffffff,
@@ -56,11 +58,14 @@ 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);
 }
+function normaliseAssertionHex(value) {
+    return stripHexByteSeparators(value).toUpperCase();
+}
 function normaliseScreenText(screen) {
     return screen.replace(/\r\n?/g, "\n").replace(/\s+/g, " ").trim().toUpperCase();
 }
@@ -226,9 +231,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 +243,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 +316,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 +338,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 +367,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 +419,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 +456,7 @@ export const tools = [
                         }
                         backendResult.verification = {
                             screenContainsExpectedText: verify ? screenMatched : undefined,
-                            screenshotCaptured: captureScreenshot ? !screenshotError : undefined,
+                            screenshotCaptured: backendCaptureScreenshot ? !screenshotError : undefined,
                             screenshotAnalysis,
                         };
                         if (screenshotPath) {
@@ -458,7 +467,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 +651,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 +672,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
@@ -683,9 +700,17 @@ export const tools = [
                             else if (assertion.type === "memory_equals") {
                                 const addr = assertion.address ?? "$0400";
                                 const expected = assertion.expected ?? "$00";
-                                const result = await ctx.client.readMemory(addr, "1");
-                                const actual = result.data ?? "$00";
-                                const matched = actual.toLowerCase() === expected.toLowerCase();
+                                // Compare every expected byte, and treat a failed read as an error rather than as $00.
+                                const expectedHex = normaliseAssertionHex(expected);
+                                if (expectedHex.length === 0 || expectedHex.length % 2 !== 0 || !/^[0-9A-F]+$/.test(expectedHex)) {
+                                    throw new Error(`memory_equals expected value ${expected} is not a whole number of hex bytes`);
+                                }
+                                const result = await ctx.client.readMemory(addr, String(expectedHex.length / 2));
+                                if (!result.success || typeof result.data !== "string") {
+                                    throw new Error(`Failed to read memory at ${addr} for memory_equals assertion`);
+                                }
+                                const actual = result.data;
+                                const matched = normaliseAssertionHex(actual) === expectedHex;
                                 assertionResults.push({
                                     type: assertion.type,
                                     status: matched ? "pass" : "fail",
@@ -697,7 +722,10 @@ export const tools = [
                             else if (assertion.type === "sid_silent") {
                                 // Check SID gate bits are off (simple check)
                                 const result = await ctx.client.readMemory("$D404", "1");
-                                const gate1 = parseInt((result.data ?? "$00").slice(1), 16) & 0x01;
+                                if (!result.success || typeof result.data !== "string") {
+                                    throw new Error("Failed to read SID voice 1 control register for sid_silent assertion");
+                                }
+                                const gate1 = parseInt(result.data.slice(1), 16) & 0x01;
                                 const isSilent = gate1 === 0;
                                 assertionResults.push({
                                     type: assertion.type,

package/dist/tools/pollValidator.js

@@ -75,7 +75,7 @@ function concatBuffers(...buffers) {
  * Looks for patterns like "?SYNTAX ERROR" or "SYNTAX ERROR IN 120".
  */
 function extractBasicError(screen) {
-    const errorMatch = /(?:^|\n)\s*\?([A-Z\s]+?)\s+ERROR(?:\s+IN\s+(\d+))?(?=\s|$)/im.exec(screen); // A real error has a leading "?"; ordinary output like "0 ERRORS FOUND" must never match.
+    const errorMatch = /(?:^|\n)\s*\?([A-Z'\s]+?)\s+ERROR(?:\s+IN\s+(\d+))?(?=\s|$)/im.exec(screen); // A real error has a leading "?"; ordinary output like "0 ERRORS FOUND" must never match. The apostrophe covers UNDEF'D STATEMENT, REDIM'D ARRAY and CAN'T CONTINUE.
     if (errorMatch) {
         const errorType = errorMatch[1]?.trim().replace(/\s+/g, " ");
         const lineStr = errorMatch[2];
@@ -87,6 +87,19 @@ function extractBasicError(screen) {
     }
     return null;
 }
+/**
+ * True when the most recent typed SYS command is followed by a READY. prompt,
+ * which is how a machine-code routine that ends with RTS hands back to BASIC.
+ */
+function returnedToBasicAfterSys(screen) {
+    const lines = screen.split("\n").map((line) => line.trim().toUpperCase());
+    let sysLine = -1;
+    lines.forEach((line, index) => {
+        if (/^SYS\s*\d+$/.test(line))
+            sysLine = index;
+    });
+    return sysLine >= 0 && lines.slice(sysLine + 1).some((line) => line === "READY.");
+}
 /**
  * Poll for BASIC program outcome by detecting errors on screen.
  * First waits for RUN or ERROR to appear, then continues polling for errors.
@@ -157,7 +170,12 @@ async function pollAsmOutcome(client, logger, config) {
         try {
             const screen = await client.readScreen();
             const upperScreen = screen.toUpperCase();
-            if (upperScreen.includes("RUN") || upperScreen.includes("ERROR")) {
+            if (returnedToBasicAfterSys(screen)) {
+                // The typed SYS line is followed by READY., so the routine ran and returned with RTS.
+                logger.debug("ASM program returned to BASIC", { elapsed: Date.now() - startTime });
+                return { status: "ok", type: "ASM" };
+            }
+            if (upperScreen.includes("RUN") || upperScreen.includes("SYS") || upperScreen.includes("ERROR")) {
                 runDetected = true;
                 logger.debug("RUN detected, starting stabilization window", {
                     elapsed: Date.now() - startTime,
@@ -182,6 +200,16 @@ async function pollAsmOutcome(client, logger, config) {
     const pollDeadline = Date.now() + config.maxMs;
     while (Date.now() < pollDeadline && !alive) {
         pollCount++;
+        try {
+            // A routine that works for a while before RTS shows READY. only after the first screen read.
+            if (returnedToBasicAfterSys(await client.readScreen())) {
+                logger.debug("ASM program returned to BASIC", { pollCount, elapsed: Date.now() - startTime });
+                return { status: "ok", type: "ASM" };
+            }
+        }
+        catch (error) {
+            logger.debug("Failed to read screen during ASM polling", { error, pollCount });
+        }
         try {
             const screenRam = await client.readMemoryRaw(0x0400, 0x03e8);
             const signature = computeCrc32(screenRam);

package/dist/tools/programRunners.js

@@ -1,5 +1,5 @@
 import fs from "node:fs";
-import { assemblyToPrgDetailed, AssemblyError } from "./translation/assembler.js";
+import { assemblyToPrgDetailed, AssemblyError, prgEntryAddress } from "./translation/assembler.js";
 import { basicToPrg } from "./translation/basicTokenizer.js";
 import { defineToolModule, OPERATION_DISCRIMINATOR, } from "./types.js";
 import { booleanSchema, objectSchema, optionalSchema, stringSchema } from "./schema.js";
@@ -52,7 +52,8 @@ function parseBasicRuntimeErrors(screen) {
             continue;
         }
         seen.add(lineNumber);
-        const typeMatch = /\?([A-Z ?]+?)\s+ERROR\s+IN/i.exec(row.toUpperCase());
+        // The apostrophe covers UNDEF'D STATEMENT, REDIM'D ARRAY and UNDEF'D FUNCTION.
+        const typeMatch = /\?([A-Z' ?]+?)\s+ERROR\s+IN/i.exec(row.toUpperCase());
         const type = typeMatch?.[1]?.trim().replace(/\s+/g, " ") || undefined;
         errors.push({
             line: lineNumber,
@@ -441,7 +442,7 @@ async function executeUploadRunAsm(rawArgs, ctx) {
         // Assemble locally to expose structured metadata and capture symbols
         const asmResult = assemblyToPrgDetailed(parsed.program);
         const prg = asmResult.prg;
-        const entryAddress = prg.readUInt16LE(0);
+        const entryAddress = prgEntryAddress(prg);
         if (ctx.platform.id === "vice") {
             setViceSymbols(asmResult.symbols.entries());
         }
@@ -686,7 +687,7 @@ export const programRunnersModule = defineToolModule({
                 {
                     name: "Set screen char",
                     description: "Write 1 to $0400 then RTS",
-                    arguments: { program: ".org $0801\nstart: lda #$01\n sta $0400\n rts" },
+                    arguments: { program: "start: lda #$01\n sta $0400\n rts" },
                 },
             ],
             workflowHints: [

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

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