c64bridge 0.9.0 → 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,
@@ -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", {
@@ -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", {
@@ -539,12 +575,15 @@ async function executeRunPrg(rawArgs, ctx) {
             path: parsed.path,
             entryAddress: null,
             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 } };
     }

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/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,6 +171,35 @@ 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({
@@ -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 };

package/dist/tools/registry/memory.js

@@ -1,5 +1,5 @@
 import { createOperationDispatcher, defineToolModule, discriminatedUnionSchema, } from "../types.js";
-import { memoryModule, memoryOperationHandlers as groupedMemoryHandlers } from "../memory.js";
+import { memoryModule, memoryOperationHandlers as groupedMemoryHandlers, disassembleArgsSchema, copyMemoryArgsSchema, fillMemoryArgsSchema, searchMemoryArgsSchema, compareMemoryArgsSchema, saveMemoryArgsSchema, } from "../memory.js";
 import { metaModule } from "../meta/index.js";
 import { buildDescriptorIndex, ensureDescriptor, extendSchemaWithOp, createOperationHandlers, invokeModuleTool, } from "./utils.js";
 const memoryDescriptorIndex = buildDescriptorIndex(memoryModule);
@@ -25,6 +25,36 @@ const memoryOperations = [
         schema: extendSchemaWithOp("wait_for_text", ensureDescriptor(metaDescriptorIndex, "wait_for_screen_text").inputSchema, { description: "Poll the screen until a substring or regex appears, or timeout elapses." }),
         handler: async (rawArgs, ctx) => invokeModuleTool(metaModule, "wait_for_screen_text", rawArgs, ctx),
     },
+    {
+        op: "disassemble",
+        schema: extendSchemaWithOp("disassemble", disassembleArgsSchema.jsonSchema, { description: "Disassemble a memory region into annotated 6502/6510 instructions, including undocumented opcodes with canonical names. Symbol annotations from `.vs` files are applied when available. Works on both C64U and VICE." }),
+        handler: groupedMemoryHandlers.disassemble,
+    },
+    {
+        op: "copy_memory",
+        schema: extendSchemaWithOp("copy_memory", copyMemoryArgsSchema.jsonSchema, { description: "Copy a RAM region to another address." }),
+        handler: groupedMemoryHandlers.copy_memory,
+    },
+    {
+        op: "fill_memory",
+        schema: extendSchemaWithOp("fill_memory", fillMemoryArgsSchema.jsonSchema, { description: "Fill a memory range with a repeating byte pattern." }),
+        handler: groupedMemoryHandlers.fill_memory,
+    },
+    {
+        op: "search_memory",
+        schema: extendSchemaWithOp("search_memory", searchMemoryArgsSchema.jsonSchema, { description: "Search for a byte pattern within a memory range and return matching addresses." }),
+        handler: groupedMemoryHandlers.search_memory,
+    },
+    {
+        op: "compare_memory",
+        schema: extendSchemaWithOp("compare_memory", compareMemoryArgsSchema.jsonSchema, { description: "Compare two memory regions byte-by-byte and report differences." }),
+        handler: groupedMemoryHandlers.compare_memory,
+    },
+    {
+        op: "save_memory",
+        schema: extendSchemaWithOp("save_memory", saveMemoryArgsSchema.jsonSchema, { description: "Dump a memory range to a local file, with an optional PRG load-address header." }),
+        handler: groupedMemoryHandlers.save_memory,
+    },
 ];
 const memoryOperationHandlers = createOperationHandlers(memoryOperations);
 export const memoryModuleGroup = defineToolModule({
@@ -59,6 +89,36 @@ export const memoryModuleGroup = defineToolModule({
                     description: "Poll until the READY. prompt appears",
                     arguments: { op: "wait_for_text", pattern: "READY." },
                 },
+                {
+                    name: "Disassemble entry point",
+                    description: "Disassemble 20 instructions starting at $0810",
+                    arguments: { op: "disassemble", address: "$0810", instructionCount: 20 },
+                },
+                {
+                    name: "Copy screen RAM",
+                    description: "Copy 1000 bytes of screen RAM to a scratch area",
+                    arguments: { op: "copy_memory", source: "$0400", dest: "$C000", length: 1000 },
+                },
+                {
+                    name: "Clear screen RAM",
+                    description: "Fill screen RAM with space character ($20)",
+                    arguments: { op: "fill_memory", address: "$0400", length: 1000, pattern: "20" },
+                },
+                {
+                    name: "Search for RTS",
+                    description: "Find RTS ($60) instructions in BASIC ROM",
+                    arguments: { op: "search_memory", startAddress: "$A000", endAddress: "$BFFF", pattern: "60" },
+                },
+                {
+                    name: "Compare two buffers",
+                    description: "Check whether two 256-byte regions differ",
+                    arguments: { op: "compare_memory", address1: "$C000", address2: "$C100", length: 256 },
+                },
+                {
+                    name: "Save PRG dump",
+                    description: "Save $0801-$CFFF as a PRG file",
+                    arguments: { op: "save_memory", startAddress: "$0801", endAddress: "$CFFF", filePath: "/tmp/dump.prg" },
+                },
             ],
             execute: createOperationDispatcher("c64_memory", memoryOperationHandlers),
         },

package/dist/tools/schema.js

@@ -195,15 +195,14 @@ function isPlainObject(value) {
 }
 export function objectSchema(options) {
     const required = options.required ?? [];
+    const additionalProperties = options.additionalProperties ?? false;
     const propertyEntries = Object.entries(options.properties).map(([key, schema]) => [key, schema.jsonSchema]);
     const jsonSchema = {
         type: "object",
         ...(options.description ? { description: options.description } : {}),
         properties: Object.fromEntries(propertyEntries),
         ...(required.length > 0 ? { required: required.map((key) => key) } : {}),
-        ...(options.additionalProperties !== undefined
-            ? { additionalProperties: options.additionalProperties }
-            : { additionalProperties: false }),
+        additionalProperties,
     };
     return createSchema(jsonSchema, (value, path) => {
         ensureType(isPlainObject(value), "Expected an object", path, {
@@ -234,7 +233,7 @@ export function objectSchema(options) {
                 }
             }
         }
-        if (options.additionalProperties === false) {
+        if (!additionalProperties) {
             for (const key of Object.keys(input)) {
                 if (!hasOwn.call(options.properties, key)) {
                     throw new ToolValidationError("Unexpected property", {
@@ -243,7 +242,7 @@ export function objectSchema(options) {
                 }
             }
         }
-        else if (options.additionalProperties === true) {
+        else {
             for (const key of Object.keys(input)) {
                 if (!hasOwn.call(options.properties, key)) {
                     result[key] = input[key];

package/dist/tools/symbolRegistry.js

@@ -0,0 +1,49 @@
+/**
+ * In-process symbol registry for VICE debug sessions.
+ * Maps addresses to label names so the disassembler can annotate output.
+ * Cleared and repopulated each time a new program is loaded.
+ */
+const viceAddressToLabel = new Map();
+export function setViceSymbols(nameToAddress) {
+    viceAddressToLabel.clear();
+    for (const [name, address] of nameToAddress) {
+        if (address >= 0 && address <= 0xffff) {
+            viceAddressToLabel.set(address, name);
+        }
+    }
+}
+export function getViceSymbol(address) {
+    return viceAddressToLabel.get(address);
+}
+export function clearViceSymbols() {
+    viceAddressToLabel.clear();
+}
+export function getViceSymbols() {
+    return viceAddressToLabel;
+}
+/**
+ * Parse a VICE symbol file (.vs) into a name->address map.
+ *
+ * Supported line formats:
+ *   add_label 0x0810 .main
+ *   add_label C:0810 .main
+ *   al C:0810 .main
+ *   al 0810 .main
+ */
+export function parseViceSymbolFile(content) {
+    const symbols = new Map();
+    for (const rawLine of content.split("\n")) {
+        const line = rawLine.trim();
+        if (!line || line.startsWith(";") || line.startsWith("#"))
+            continue;
+        const match = /^(?:add_label|al)\s+(?:[A-Za-z]+:)?(?:0x|\$)?([0-9A-Fa-f]+)\s+\.?(\S+)/i.exec(line);
+        if (match) {
+            const addr = parseInt(match[1], 16);
+            const name = match[2];
+            if (!isNaN(addr) && addr >= 0 && addr <= 0xffff && name) {
+                symbols.set(name, addr);
+            }
+        }
+    }
+    return symbols;
+}

package/dist/tools/types.js

@@ -36,16 +36,30 @@ export function discriminatedUnionSchema(options) {
     const opValues = [];
     const mergedProperties = {};
     const opDescriptions = [];
+    const operationMetadata = [];
     for (const variant of variants) {
         const variantProps = variant.properties ?? {};
         const discProp = variantProps[discriminator];
         const opValue = discProp?.const;
+        const variantDesc = variant.description ?? discProp?.description ?? "";
+        const requiredInputs = (variant.required ?? []).filter((name) => name !== discriminator);
+        const optionalInputs = Object.keys(variantProps).filter((name) => name !== discriminator && !requiredInputs.includes(name));
         if (opValue) {
             opValues.push(opValue);
-            const variantDesc = variant.description ?? discProp?.description ?? "";
-            if (variantDesc) {
-                opDescriptions.push(`${opValue}: ${variantDesc}`);
-            }
+            const requiredSummary = requiredInputs.length > 0
+                ? ` Required inputs: ${requiredInputs.join(", ")}.`
+                : " Required inputs: none.";
+            const optionalSummary = optionalInputs.length > 0
+                ? ` Optional inputs: ${optionalInputs.join(", ")}.`
+                : "";
+            opDescriptions.push(`${opValue}: ${variantDesc || `Operation ${opValue}`}${requiredSummary}${optionalSummary}`);
+            operationMetadata.push({
+                op: opValue,
+                ...(variantDesc ? { description: variantDesc } : {}),
+                required: requiredInputs,
+                optional: optionalInputs,
+                inputSchema: variant,
+            });
         }
         for (const [key, propSchema] of Object.entries(variantProps)) {
             if (key === discriminator)
@@ -74,6 +88,7 @@ export function discriminatedUnionSchema(options) {
         },
         required: [discriminator],
         additionalProperties: false,
+        ...(operationMetadata.length > 0 ? { "x-c64bridge-operations": operationMetadata } : {}),
     };
     return schema;
 }