c64bridge 0.8.1 → 0.9.1

package/dist/tools/programRunners.js

@@ -1,10 +1,12 @@
-import { assemblyToPrg, AssemblyError } from "../assemblyConverter.js";
-import { basicToPrg } from "../basicConverter.js";
+import fs from "node:fs";
+import { assemblyToPrgDetailed, AssemblyError } from "./assember.js";
+import { basicToPrg } from "./basicTokenizer.js";
 import { defineToolModule, OPERATION_DISCRIMINATOR, } from "./types.js";
-import { booleanSchema, objectSchema, stringSchema } from "./schema.js";
+import { booleanSchema, objectSchema, optionalSchema, stringSchema } from "./schema.js";
 import { textResult } from "./responses.js";
 import { ToolExecutionError, ToolError, ToolValidationError, toolErrorResult, unknownErrorResult, } from "./errors.js";
 import { pollForProgramOutcome } from "./pollValidator.js";
+import { clearViceSymbols, setViceSymbols, parseViceSymbolFile } from "./symbolRegistry.js";
 function extractFailureDetails(details) {
     if (details === undefined || details === null) {
         return undefined;
@@ -163,6 +165,14 @@ function normalizeRuntimeErrors(errors) {
         text: error.raw,
     }));
 }
+export const __programRunnerHelpersForTests = {
+    extractFailureDetails,
+    toRecord,
+    stripOperationDiscriminator,
+    parseBasicRuntimeErrors,
+    attemptAutoFixBasicProgram,
+    normalizeRuntimeErrors,
+};
 function structuredExecutionError(message, data) {
     return {
         content: [
@@ -221,6 +231,10 @@ const prgFileArgsSchema = objectSchema({
             description: prgPathDescription,
             minLength: 1,
         }),
+        symbolsFile: optionalSchema(stringSchema({
+            description: "Path to a VICE symbol file (.vs) to load alongside the PRG. Symbols are used by the disassemble tool when annotating addresses.",
+            minLength: 1,
+        })),
     },
     required: ["path"],
     additionalProperties: false,
@@ -394,7 +408,7 @@ async function executeUploadRunBasic(rawArgs, ctx) {
             format: "prg",
             entryAddress,
             prgSize: prg.length,
-            resources: ["c64://specs/basic", "c64://context/bootstrap"],
+            resources: ["c64://basic/spec", "c64://guide/bootstrap"],
             ...(screenOutput ? { screen: screenOutput } : {}),
             ...(autoFixInfo
                 ? {
@@ -424,9 +438,13 @@ async function executeUploadRunAsm(rawArgs, ctx) {
             sourceLength: parsed.program.length,
             ...(shouldVerify ? { verify: true } : {}),
         });
-        // Assemble locally to expose structured metadata
-        const prg = assemblyToPrg(parsed.program);
+        // Assemble locally to expose structured metadata and capture symbols
+        const asmResult = assemblyToPrgDetailed(parsed.program);
+        const prg = asmResult.prg;
         const entryAddress = prg.readUInt16LE(0);
+        if (ctx.platform.id === "vice") {
+            setViceSymbols(asmResult.symbols.entries());
+        }
         const result = await ctx.client.uploadAndRunAsm(parsed.program);
         if (!result.success) {
             return toolErrorResult(new ToolExecutionError("C64 firmware reported failure while running assembly program", {
@@ -460,7 +478,7 @@ async function executeUploadRunAsm(rawArgs, ctx) {
             format: "prg",
             entryAddress,
             prgSize: prg.length,
-            resources: ["c64://specs/assembly", "c64://context/bootstrap"],
+            resources: ["c64://assembly/6510-spec", "c64://guide/bootstrap"],
             ...(shouldVerify && verified ? { verified: true } : {}),
         };
         const base = textResult("Assembly program assembled, uploaded, and executed successfully.", {
@@ -506,7 +524,7 @@ async function executeLoadPrg(rawArgs, ctx) {
             format: "prg",
             path: parsed.path,
             entryAddress: null,
-            resources: ["c64://context/bootstrap"],
+            resources: ["c64://guide/bootstrap"],
         };
         const base = textResult(`PRG ${parsed.path} loaded into memory.`, {
             success: true,
@@ -527,6 +545,24 @@ async function executeRunPrg(rawArgs, ctx) {
     try {
         const parsed = prgFileArgsSchema.parse(rawArgs ?? {});
         ctx.logger.info("Running PRG file", { path: parsed.path });
+        let symbolsLoaded = 0;
+        if (ctx.platform.id === "vice") {
+            clearViceSymbols();
+            if (parsed.symbolsFile) {
+                try {
+                    const content = await fs.promises.readFile(parsed.symbolsFile, "utf8");
+                    const syms = parseViceSymbolFile(content);
+                    setViceSymbols(syms.entries());
+                    symbolsLoaded = syms.size;
+                    ctx.logger.info("Loaded VICE symbols from file", { path: parsed.symbolsFile, count: symbolsLoaded });
+                }
+                catch (fileError) {
+                    throw new ToolExecutionError(`Failed to read symbols file: ${parsed.symbolsFile}`, {
+                        details: { message: fileError instanceof Error ? fileError.message : String(fileError) },
+                    });
+                }
+            }
+        }
         const result = await ctx.client.runPrgFile(parsed.path);
         if (!result.success) {
             throw new ToolExecutionError("C64 firmware reported failure while running PRG", {
@@ -538,13 +574,16 @@ async function executeRunPrg(rawArgs, ctx) {
             format: "prg",
             path: parsed.path,
             entryAddress: null,
-            resources: ["c64://context/bootstrap"],
+            resources: ["c64://guide/bootstrap"],
+            ...(symbolsLoaded > 0 ? { symbolsLoaded } : {}),
         };
-        const base = textResult(`PRG ${parsed.path} loaded and executed.`, {
+        const symbolNote = symbolsLoaded > 0 ? ` Loaded ${symbolsLoaded} debug symbol(s).` : "";
+        const base = textResult(`PRG ${parsed.path} loaded and executed.${symbolNote}`, {
             success: true,
             path: parsed.path,
             entryAddress: null,
             details: toRecord(result.details) ?? null,
+            ...(symbolsLoaded > 0 ? { symbolsLoaded } : {}),
         });
         return { ...base, structuredContent: { type: "json", data } };
     }
@@ -570,7 +609,7 @@ async function executeRunCrt(rawArgs, ctx) {
             format: "crt",
             path: parsed.path,
             entryAddress: null,
-            resources: ["c64://context/bootstrap"],
+            resources: ["c64://guide/bootstrap"],
         };
         const base = textResult(`PRG ${parsed.path} loaded and executed.`, {
             success: true,
@@ -598,9 +637,9 @@ export const programRunnersModule = defineToolModule({
     domain: "programs",
     summary: "Program uploaders, runners, and compilation workflows for BASIC, assembly, and PRG files.",
     resources: [
-        "c64://context/bootstrap",
-        "c64://specs/basic",
-        "c64://specs/assembly",
+        "c64://guide/bootstrap",
+        "c64://basic/spec",
+        "c64://assembly/6510-spec",
     ],
     prompts: ["basic-program", "assembly-program"],
     defaultTags: ["programs", "execution"],
@@ -611,10 +650,10 @@ export const programRunnersModule = defineToolModule({
     tools: [
         {
             name: "upload_run_basic",
-            description: "Upload a BASIC program to the C64 and execute it immediately. Refer to c64://specs/basic for syntax and device I/O.",
+            description: "Upload a BASIC program to the C64 and execute it immediately. Refer to c64://basic/spec for syntax and device I/O.",
             summary: "Uploads Commodore BASIC v2 source and runs it via Ultimate 64 firmware.",
             inputSchema: uploadBasicArgsSchema.jsonSchema,
-            relatedResources: ["c64://specs/basic", "c64://docs/basic/pitfalls", "c64://context/bootstrap"],
+            relatedResources: ["c64://basic/spec", "c64://basic/pitfalls", "c64://guide/bootstrap"],
             relatedPrompts: ["basic-program"],
             tags: ["basic", "execution"],
             prerequisites: ["read_screen"],
@@ -636,10 +675,10 @@ export const programRunnersModule = defineToolModule({
         },
         {
             name: "upload_run_asm",
-            description: "Assemble 6502/6510 source code, upload the PRG, and run it immediately. See c64://specs/assembly.",
+            description: "Assemble 6502/6510 source code, upload the PRG, and run it immediately. See c64://assembly/6510-spec.",
             summary: "Compiles assembly to a PRG and executes it on the C64 via Ultimate 64 firmware.",
             inputSchema: uploadAsmArgsSchema.jsonSchema,
-            relatedResources: ["c64://specs/assembly", "c64://context/bootstrap"],
+            relatedResources: ["c64://assembly/6510-spec", "c64://guide/bootstrap"],
             relatedPrompts: ["assembly-program"],
             tags: ["assembly", "execution"],
             prerequisites: ["read_screen"],
@@ -664,7 +703,7 @@ export const programRunnersModule = defineToolModule({
             description: "Load a PRG into C64 memory without executing it.",
             summary: "Instructs the Ultimate firmware to transfer a PRG into memory without RUN.",
             inputSchema: prgFileArgsSchema.jsonSchema,
-            relatedResources: ["c64://context/bootstrap"],
+            relatedResources: ["c64://guide/bootstrap"],
             tags: ["programs", "file"],
             prerequisites: ["drives_list"],
             examples: [
@@ -688,7 +727,7 @@ export const programRunnersModule = defineToolModule({
             description: "Run a PRG located on the Ultimate filesystem without uploading source.",
             summary: "Loads and executes a PRG file residing on attached storage.",
             inputSchema: prgFileArgsSchema.jsonSchema,
-            relatedResources: ["c64://context/bootstrap"],
+            relatedResources: ["c64://guide/bootstrap"],
             tags: ["programs", "execution", "file"],
             workflowHints: [
                 "Call when the user provides a PRG path and expects immediate execution without compiling.",
@@ -712,7 +751,7 @@ export const programRunnersModule = defineToolModule({
             description: "Run a cartridge image stored on the Ultimate filesystem.",
             summary: "Mounts and autostarts the specified CRT file through the firmware.",
             inputSchema: crtFileArgsSchema.jsonSchema,
-            relatedResources: ["c64://context/bootstrap"],
+            relatedResources: ["c64://guide/bootstrap"],
             tags: ["programs", "cartridge"],
             workflowHints: [
                 "Use for cartridge images and remind the user that the machine will reset into the CRT.",
@@ -742,7 +781,7 @@ export const programRunnersModule = defineToolModule({
                         format: "crt",
                         path: parsed.path,
                         entryAddress: null,
-                        resources: ["c64://context/bootstrap"],
+                        resources: ["c64://guide/bootstrap"],
                     };
                     const base = textResult(`CRT ${parsed.path} mounted and started.`, {
                         success: true,

package/dist/tools/rag.js

@@ -23,18 +23,18 @@ const ragRetrieveArgsSchema = objectSchema({
 });
 function createRagTool(language, options) {
     const primaryResourceUris = language === "basic"
-        ? ["c64://specs/basic", "c64://context/bootstrap"]
-        : ["c64://specs/assembly", "c64://context/bootstrap"];
+        ? ["c64://basic/spec", "c64://guide/bootstrap"]
+        : ["c64://assembly/6510-spec", "c64://guide/bootstrap"];
     return {
         name: language === "basic" ? "rag_retrieve_basic" : "rag_retrieve_asm",
         description: language === "basic"
-            ? "Retrieve BASIC references from local knowledge. See c64://specs/basic before coding."
-            : "Retrieve 6502/6510 assembly references from local knowledge. See c64://specs/assembly.",
+            ? "Retrieve BASIC references from local knowledge. See c64://basic/spec before coding."
+            : "Retrieve 6502/6510 assembly references from local knowledge. See c64://assembly/6510-spec.",
         summary: options.summary,
         inputSchema: ragRetrieveArgsSchema.jsonSchema,
         relatedResources: language === "basic"
-            ? ["c64://specs/basic"]
-            : ["c64://specs/assembly"],
+            ? ["c64://basic/spec"]
+            : ["c64://assembly/6510-spec"],
         relatedPrompts: language === "basic"
             ? ["basic-program"]
             : ["assembly-program"],
@@ -175,9 +175,9 @@ export const ragModule = defineToolModule({
     domain: "rag",
     summary: "Retrieval-augmented generation helpers for BASIC and assembly examples.",
     resources: [
-        "c64://specs/basic",
-        "c64://specs/assembly",
-        "c64://docs/index",
+        "c64://basic/spec",
+        "c64://assembly/6510-spec",
+        "c64://guide/index",
     ],
     prompts: ["basic-program", "assembly-program"],
     defaultTags: ["rag", "search"],

package/dist/tools/registry/batch.js

@@ -0,0 +1,167 @@
+import { defineToolModule, } from "../types.js";
+import { getPlatformStatus } from "../../platform.js";
+import { arraySchema, booleanSchema, objectSchema, optionalSchema, stringSchema, } from "../schema.js";
+import { jsonResult } from "../responses.js";
+import { ToolValidationError, unknownErrorResult } from "../errors.js";
+const commandSchema = objectSchema({
+    description: "A single batch command.",
+    properties: {
+        tool: stringSchema({ description: "MCP tool name (e.g. c64_memory, c64_debug).", minLength: 1 }),
+        args: objectSchema({
+            description: "Arguments to pass to the tool (must include 'op' for grouped tools).",
+            properties: {},
+            additionalProperties: true,
+        }),
+        description: optionalSchema(stringSchema({ description: "Optional label for this command in the result.", maxLength: 128 })),
+    },
+    required: ["tool", "args"],
+    additionalProperties: false,
+});
+const executeBatchArgsSchema = objectSchema({
+    description: "Execute multiple tool calls in one request.",
+    properties: {
+        commands: arraySchema(commandSchema, {
+            description: "Ordered list of commands to execute.",
+            minItems: 1,
+        }),
+        stopOnError: optionalSchema(booleanSchema({
+            description: "Halt the batch after the first failure. Default: true.",
+            default: true,
+        })),
+    },
+    required: ["commands"],
+    additionalProperties: false,
+});
+export const batchModuleGroup = defineToolModule({
+    domain: "batch",
+    summary: "Execute multiple tool calls in a single MCP request for reduced round-trip overhead.",
+    supportedPlatforms: ["c64u", "vice"],
+    resources: [],
+    prompts: [],
+    defaultTags: ["batch", "orchestration"],
+    workflowHints: [
+        "Use execute_batch when you need to run 3 or more sequential operations — it eliminates per-call network overhead.",
+        "Each command must include 'tool' and 'args'; grouped tools require 'op' inside args.",
+    ],
+    tools: [
+        {
+            name: "c64_batch",
+            description: "Execute multiple c64bridge tool calls in a single request. Reduces latency for multi-step workflows.",
+            summary: "Runs an ordered list of tool commands and returns all results with per-command timing.",
+            inputSchema: executeBatchArgsSchema.jsonSchema,
+            tags: ["batch", "orchestration", "grouped"],
+            examples: [
+                {
+                    name: "Read registers then step",
+                    description: "Get registers, step one instruction, get registers again",
+                    arguments: {
+                        commands: [
+                            { tool: "c64_debug", args: { op: "get_registers" }, description: "before" },
+                            { tool: "c64_debug", args: { op: "step", count: 1 }, description: "step" },
+                            { tool: "c64_debug", args: { op: "get_registers" }, description: "after" },
+                        ],
+                    },
+                },
+                {
+                    name: "Clear screen and type text",
+                    description: "Fill screen RAM then feed keyboard",
+                    arguments: {
+                        commands: [
+                            { tool: "c64_memory", args: { op: "fill_memory", address: "$0400", length: 1000, pattern: "20" } },
+                            { tool: "c64_input", args: { op: "write_text", text: "HELLO{RETURN}" } },
+                        ],
+                    },
+                },
+            ],
+            execute: async (rawArgs, ctx) => {
+                try {
+                    const parsed = executeBatchArgsSchema.parse(rawArgs);
+                    const stopOnError = parsed.stopOnError !== false;
+                    // Lazy import to avoid circular dependency at module-init time.
+                    const { toolRegistry } = await import("./index.js");
+                    const results = [];
+                    let succeeded = 0;
+                    let failed = 0;
+                    const batchStart = Date.now();
+                    for (let i = 0; i < parsed.commands.length; i++) {
+                        const cmd = parsed.commands[i];
+                        const toolName = typeof cmd.tool === "string" ? cmd.tool : "";
+                        const args = (typeof cmd.args === "object" && cmd.args !== null) ? cmd.args : {};
+                        const label = typeof cmd.description === "string" ? cmd.description : undefined;
+                        if (!toolName) {
+                            const err = { index: i, tool: String(cmd.tool), description: label, success: false, error: "tool name must be a non-empty string", elapsedMs: 0 };
+                            results.push(err);
+                            failed++;
+                            if (stopOnError)
+                                break;
+                            continue;
+                        }
+                        if (toolName === "c64_batch") {
+                            results.push({
+                                index: i,
+                                tool: toolName,
+                                description: label,
+                                success: false,
+                                error: "Nested c64_batch execution is not supported.",
+                                elapsedMs: 0,
+                            });
+                            failed++;
+                            if (stopOnError)
+                                break;
+                            continue;
+                        }
+                        const cmdStart = Date.now();
+                        try {
+                            const toolResult = await toolRegistry.invoke(toolName, args, {
+                                ...ctx,
+                                platform: getPlatformStatus(),
+                            });
+                            const elapsedMs = Date.now() - cmdStart;
+                            const isError = toolResult.isError === true;
+                            const text = toolResult.content.map((c) => c.text).join("\n");
+                            const resultPayload = toolResult.structuredContent?.data ?? text;
+                            if (isError) {
+                                results.push({ index: i, tool: toolName, description: label, success: false, error: text, elapsedMs });
+                                failed++;
+                                if (stopOnError)
+                                    break;
+                            }
+                            else {
+                                results.push({ index: i, tool: toolName, description: label, success: true, result: resultPayload, elapsedMs });
+                                succeeded++;
+                            }
+                        }
+                        catch (err) {
+                            const elapsedMs = Date.now() - cmdStart;
+                            const message = err instanceof Error ? err.message : String(err);
+                            results.push({ index: i, tool: toolName, description: label, success: false, error: message, elapsedMs });
+                            failed++;
+                            if (stopOnError)
+                                break;
+                        }
+                    }
+                    const totalElapsedMs = Date.now() - batchStart;
+                    const summary = {
+                        total: parsed.commands.length,
+                        executed: results.length,
+                        succeeded,
+                        failed,
+                        elapsedMs: totalElapsedMs,
+                        results,
+                    };
+                    ctx.logger.info("Batch complete", { total: parsed.commands.length, succeeded, failed, elapsedMs: totalElapsedMs });
+                    return jsonResult(summary, { success: failed === 0, succeeded, failed, total: parsed.commands.length });
+                }
+                catch (error) {
+                    if (error instanceof ToolValidationError) {
+                        return {
+                            content: [{ type: "text", text: error.message }],
+                            isError: true,
+                        };
+                    }
+                    return unknownErrorResult(error);
+                }
+            },
+        },
+    ],
+});

package/dist/tools/registry/config.js

@@ -151,7 +151,7 @@ const configOperationHandlers = createOperationHandlers(configOperations);
 export const configModuleGroup = defineToolModule({
     domain: "config",
     summary: "Grouped configuration management, diagnostics, and snapshot workflows.",
-    resources: ["c64://context/bootstrap", "c64://docs/index"],
+    resources: ["c64://guide/bootstrap", "c64://guide/index"],
     prompts: ["memory-debug"],
     defaultTags: ["config", "diagnostics"],
     supportedPlatforms: ["c64u", "vice"],

package/dist/tools/registry/disk.js

@@ -252,7 +252,7 @@ export const diskModuleGroup = defineToolModule({
     domain: "storage",
     summary: "Grouped disk image management, mounting, and discovery tools.",
     supportedPlatforms: ["c64u", "vice"],
-    resources: ["c64://context/bootstrap"],
+    resources: ["c64://guide/bootstrap"],
     prompts: ["drive-management"],
     defaultTags: ["storage", "drive"],
     workflowHints: [

package/dist/tools/registry/drive.js

@@ -34,7 +34,7 @@ export const driveModuleGroup = defineToolModule({
     domain: "drive",
     summary: "Grouped drive power, reset, ROM, and mode helpers.",
     supportedPlatforms: ["c64u", "vice"],
-    resources: ["c64://context/bootstrap"],
+    resources: ["c64://guide/bootstrap"],
     defaultTags: ["drive", "hardware"],
     workflowHints: [
         "State the resulting power/mode/ROM so the user can reconcile IEC behaviour.",

package/dist/tools/registry/extract.js

@@ -33,7 +33,7 @@ const extractOperationHandlers = createOperationHandlers(extractOperations);
 export const extractModule = defineToolModule({
     domain: "extract",
     summary: "Grouped extraction helpers for sprites, charsets, memory dumps, and diagnostics.",
-    resources: ["c64://context/bootstrap", "c64://specs/basic", "c64://specs/assembly"],
+    resources: ["c64://guide/bootstrap", "c64://basic/spec", "c64://assembly/6510-spec"],
     defaultTags: ["extract", "diagnostics"],
     workflowHints: [
         "Pause the machine when advised so dumps and sprite scans remain stable.",

package/dist/tools/registry/graphics.js

@@ -3,8 +3,8 @@ import { createOperationDispatcher, defineToolModule, discriminatedUnionSchema,
 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 { ToolError, toolErrorResult, unknownErrorResult, } from "../errors.js";
 import { jsonResult } from "../responses.js";
+import { ToolError, toolErrorResult, unknownErrorResult, } from "../errors.js";
 const graphicsDescriptorIndex = buildDescriptorIndex(graphicsModule);
 const captureFrameArgsSchema = objectSchema({
     description: "Capture one or more complete video frames from the active backend.",
@@ -30,6 +30,72 @@ const captureFrameArgsSchema = objectSchema({
     required: ["op"],
     additionalProperties: false,
 });
+// ---------------------------------------------------------------------------
+// get_display_state helpers — VIC-II register decoding
+// ---------------------------------------------------------------------------
+function parseVicState(d011, d016, d018, dd00, d020, d021) {
+    const bank = (~dd00) & 0x03; // CIA2 Port A bits 0-1 select VIC bank (inverted)
+    const bankBase = bank * 0x4000;
+    const bitmapMode = (d011 & 0x20) !== 0;
+    const extendedColor = (d011 & 0x40) !== 0;
+    const multicolor = (d016 & 0x10) !== 0;
+    const screenVisible = (d011 & 0x10) !== 0;
+    const raster8 = (d011 & 0x80) !== 0;
+    const vertScroll = d011 & 0x07;
+    const horizScroll = d016 & 0x07;
+    const columns40 = (d016 & 0x08) !== 0;
+    const rows25 = (d011 & 0x08) !== 0;
+    // D018 bits 4-7 = screen RAM offset (× $0400); bits 1-3 = char/bitmap pointer (× $0800)
+    const screenRamOffset = ((d018 >> 4) & 0x0f) * 0x0400;
+    const screenRamAddress = bankBase + screenRamOffset;
+    const charOrBitmapPointer = ((d018 >> 1) & 0x07) * 0x0800;
+    const charOrBitmapAddress = bankBase + charOrBitmapPointer;
+    let mode;
+    if (bitmapMode && multicolor)
+        mode = "multicolor_bitmap";
+    else if (bitmapMode)
+        mode = "hires_bitmap";
+    else if (extendedColor)
+        mode = "extended_color_text";
+    else if (multicolor)
+        mode = "multicolor_text";
+    else
+        mode = "standard_text";
+    return {
+        mode,
+        bank,
+        bankBase: `$${bankBase.toString(16).toUpperCase().padStart(4, "0")}`,
+        screenRamAddress: `$${screenRamAddress.toString(16).toUpperCase().padStart(4, "0")}`,
+        charOrBitmapAddress: `$${charOrBitmapAddress.toString(16).toUpperCase().padStart(4, "0")}`,
+        screenVisible,
+        bitmapMode,
+        extendedColor,
+        multicolor,
+        rows25,
+        columns40,
+        vertScroll,
+        horizScroll,
+        raster8,
+        borderColor: d020 & 0x0f,
+        backgroundColor: d021 & 0x0f,
+        registers: {
+            d011: `$${d011.toString(16).toUpperCase().padStart(2, "0")}`,
+            d016: `$${d016.toString(16).toUpperCase().padStart(2, "0")}`,
+            d018: `$${d018.toString(16).toUpperCase().padStart(2, "0")}`,
+            d020: `$${d020.toString(16).toUpperCase().padStart(2, "0")}`,
+            d021: `$${d021.toString(16).toUpperCase().padStart(2, "0")}`,
+            dd00: `$${dd00.toString(16).toUpperCase().padStart(2, "0")}`,
+        },
+    };
+}
+const getDisplayStateArgsSchema = objectSchema({
+    description: "Read VIC-II and CIA2 registers to determine the current graphics mode and memory layout. Works on C64U and VICE; both backends are read through shared memory primitives so the response shape is identical.",
+    properties: {
+        op: literalSchema("get_display_state"),
+    },
+    required: ["op"],
+    additionalProperties: false,
+});
 const graphicsOperations = [
     {
         op: "capture_frame",
@@ -105,12 +171,41 @@ const graphicsOperations = [
         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,
     },
+    {
+        op: "get_display_state",
+        schema: getDisplayStateArgsSchema.jsonSchema,
+        handler: async (_rawArgs, ctx) => {
+            try {
+                // Use cross-platform memory reads so the same handler works on both
+                // C64U and VICE. The VIC-II and CIA2 registers live in machine memory
+                // either way; the underlying facade hides the transport difference.
+                const vicRegs = await ctx.client.readMemoryRaw(0xD011, 8);
+                const colorRegs = await ctx.client.readMemoryRaw(0xD020, 2);
+                const cia2 = await ctx.client.readMemoryRaw(0xDD00, 1);
+                const d011 = vicRegs[0] ?? 0;
+                const d016 = vicRegs[5] ?? 0; // $D016 = $D011 + 5
+                const d018 = vicRegs[7] ?? 0; // $D018 = $D011 + 7
+                const d020 = colorRegs[0] ?? 0;
+                const d021 = colorRegs[1] ?? 0;
+                const dd00 = cia2[0] ?? 0x03;
+                const backend = await ctx.client.getActiveBackendType();
+                const state = { ...parseVicState(d011, d016, d018, dd00, d020, d021), backend };
+                ctx.logger.info("Read VIC-II display state", { mode: state.mode, bank: state.bank, backend });
+                return jsonResult(state, { success: true, mode: state.mode, backend });
+            }
+            catch (error) {
+                if (error instanceof ToolError)
+                    return toolErrorResult(error);
+                return unknownErrorResult(error);
+            }
+        },
+    },
 ];
 const graphicsOperationHandlers = createOperationHandlers(graphicsOperations);
 export const graphicsModuleGroup = defineToolModule({
     domain: "graphics",
     summary: "Grouped frame capture and graphics rendering helpers.",
-    resources: ["c64://specs/vic", "c64://specs/basic", "c64://specs/assembly"],
+    resources: ["c64://graphics/vic/spec", "c64://basic/spec", "c64://assembly/6510-spec"],
     prompts: ["graphics-demo", "basic-program", "assembly-program"],
     defaultTags: ["graphics", "vic"],
     workflowHints: [
@@ -154,6 +249,11 @@ export const graphicsModuleGroup = defineToolModule({
                     description: "Convert a PNG into VIC bitmap memory and display it",
                     arguments: { op: "render_bitmap", imagePath: "./artifacts/sample.png", format: "hires" },
                 },
+                {
+                    name: "Read VIC-II state",
+                    description: "Decode graphics mode, memory layout, and colours from VIC-II registers (cross-platform)",
+                    arguments: { op: "get_display_state" },
+                },
             ],
             execute: createOperationDispatcher("c64_graphics", graphicsOperationHandlers),
         },

package/dist/tools/registry/index.js

@@ -14,6 +14,8 @@ import { extractModule } from "./extract.js";
 import { streamModule } from "./stream.js";
 import { debugModuleGroup as debugModule } from "../debug.js";
 import { viceModuleGroup as viceModule } from "../vice.js";
+import { inputModuleGroup as inputModule } from "./input.js";
+import { batchModuleGroup as batchModule } from "./batch.js";
 const modules = [
     programModule,
     memoryModule,
@@ -30,6 +32,8 @@ const modules = [
     streamModule,
     debugModule,
     viceModule,
+    inputModule,
+    batchModule,
 ];
 const toolMap = new Map();
 for (const module of modules) {

package/dist/tools/registry/input.js

@@ -0,0 +1,2 @@
+import { inputModule } from "../input.js";
+export { inputModule as inputModuleGroup };