c64bridge 0.8.1 → 0.9.1

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,13 +25,43 @@ 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({
     domain: "memory",
     summary: "Grouped memory, screen, and polling operations.",
     supportedPlatforms: ["c64u", "vice"],
-    resources: ["c64://context/bootstrap", "c64://specs/basic", "c64://specs/assembly"],
+    resources: ["c64://guide/bootstrap", "c64://basic/spec", "c64://assembly/6510-spec"],
     prompts: ["memory-debug", "basic-program", "assembly-program"],
     defaultTags: ["memory", "debug"],
     workflowHints: [
@@ -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/registry/platform.js

@@ -92,7 +92,7 @@ export const platformModuleGroup = defineToolModule({
     domain: "platform",
     summary: "Runtime backend selection and platform-status coordination.",
     supportedPlatforms: ["c64u", "vice"],
-    resources: ["c64://platform/status", "c64://context/bootstrap"],
+    resources: ["c64://platform/status", "c64://guide/bootstrap"],
     prompts: [],
     defaultTags: ["platform", "backend", "grouped"],
     workflowHints: [

package/dist/tools/registry/printer.js

@@ -117,7 +117,7 @@ function invokePrintTool(toolName, rawArgs, ctx) {
 export const printerModuleGroup = defineToolModule({
     domain: "printer",
     summary: "Grouped printer text, bitmap, and character definition helpers.",
-    resources: ["c64://context/bootstrap"],
+    resources: ["c64://guide/bootstrap"],
     defaultTags: ["printer", "device"],
     workflowHints: [
         "Mention device/secondary addresses so the user knows which printer workflow ran.",

package/dist/tools/registry/program.js

@@ -50,7 +50,7 @@ const programOperationHandlers = createOperationHandlers(programOperations);
 export const programModule = defineToolModule({
     domain: "programs",
     summary: "Grouped program upload, run, and orchestration workflows.",
-    resources: ["c64://context/bootstrap", "c64://specs/basic", "c64://specs/assembly"],
+    resources: ["c64://guide/bootstrap", "c64://basic/spec", "c64://assembly/6510-spec"],
     prompts: ["basic-program", "assembly-program"],
     defaultTags: ["programs", "execution"],
     workflowHints: [

package/dist/tools/registry/rag.js

@@ -18,7 +18,7 @@ const ragOperationHandlers = createOperationHandlers(ragOperations);
 export const ragModuleGroup = defineToolModule({
     domain: "rag",
     summary: "Grouped retrieval helpers for BASIC and assembly references.",
-    resources: ["c64://specs/basic", "c64://specs/assembly", "c64://context/bootstrap"],
+    resources: ["c64://basic/spec", "c64://assembly/6510-spec", "c64://guide/bootstrap"],
     prompts: ["basic-program", "assembly-program"],
     defaultTags: ["rag", "search"],
     workflowHints: [

package/dist/tools/registry/sound.js

@@ -140,7 +140,7 @@ export const soundModuleGroup = defineToolModule({
     domain: "audio",
     summary: "Grouped SID control, playback, composition, and analysis operations.",
     supportedPlatforms: ["c64u", "vice"],
-    resources: ["c64://specs/sid", "c64://specs/sidwave", "c64://docs/sid/file-structure"],
+    resources: ["c64://sound/sid/spec", "c64://sound/sidwave/spec", "c64://sound/sid/file-format"],
     prompts: ["sid-music"],
     defaultTags: ["sid", "audio"],
     workflowHints: [

package/dist/tools/registry/stream.js

@@ -18,7 +18,7 @@ const streamOperationHandlers = createOperationHandlers(streamOperations);
 export const streamModule = defineToolModule({
     domain: "stream",
     summary: "Grouped streaming helpers for starting and stopping Ultimate capture sessions.",
-    resources: ["c64://docs/index", "c64://specs/sid"],
+    resources: ["c64://guide/index", "c64://sound/sid/spec"],
     prompts: ["sid-music"],
     defaultTags: ["stream", "monitor"],
     workflowHints: [

package/dist/tools/registry/system.js

@@ -66,7 +66,7 @@ export const systemModuleGroup = defineToolModule({
     domain: "system",
     summary: "Grouped machine control and background task orchestration.",
     supportedPlatforms: ["c64u", "vice"],
-    resources: ["c64://context/bootstrap"],
+    resources: ["c64://guide/bootstrap"],
     prompts: ["memory-debug"],
     defaultTags: ["system", "control"],
     workflowHints: [

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/storage.js

@@ -144,7 +144,7 @@ export const storageModule = defineToolModule({
     domain: "storage",
     summary: "Drive management, disk image creation, and file inspection utilities.",
     supportedPlatforms: ["c64u", "vice"],
-    resources: ["c64://context/bootstrap"],
+    resources: ["c64://guide/bootstrap"],
     prompts: ["memory-debug"],
     defaultTags: ["drive", "storage"],
     workflowHints: [
@@ -154,10 +154,10 @@ export const storageModule = defineToolModule({
     tools: [
         {
             name: "drives_list",
-            description: "List Ultimate drive slots and their currently mounted images. Read c64://context/bootstrap for drive safety.",
+            description: "List Ultimate drive slots and their currently mounted images. Read c64://guide/bootstrap for drive safety.",
             summary: "Fetches firmware drive status including mounted images, power state, and modes.",
             inputSchema: drivesListArgsSchema.jsonSchema,
-            relatedResources: ["c64://context/bootstrap"],
+            relatedResources: ["c64://guide/bootstrap"],
             tags: ["drive", "status"],
             prerequisites: [],
             examples: [
@@ -193,7 +193,7 @@ export const storageModule = defineToolModule({
             description: "Mount a disk image onto a specific Ultimate drive slot.",
             summary: "Validates parameters and instructs the firmware to mount an image with optional type/mode overrides.",
             inputSchema: driveMountArgsSchema.jsonSchema,
-            relatedResources: ["c64://context/bootstrap"],
+            relatedResources: ["c64://guide/bootstrap"],
             tags: ["drive", "mount"],
             prerequisites: ["drives_list"],
             examples: [
@@ -250,7 +250,7 @@ export const storageModule = defineToolModule({
             description: "Remove the currently mounted disk image from an Ultimate drive slot.",
             summary: "Ejects the image and leaves the drive empty without powering it off.",
             inputSchema: driveOnlyArgsSchema.jsonSchema,
-            relatedResources: ["c64://context/bootstrap"],
+            relatedResources: ["c64://guide/bootstrap"],
             tags: ["drive", "unmount"],
             prerequisites: ["drives_list"],
             examples: [
@@ -292,7 +292,7 @@ export const storageModule = defineToolModule({
             description: "Reset the selected Ultimate drive slot.",
             summary: "Issues a IEC reset for the chosen drive without cycling the entire machine.",
             inputSchema: driveOnlyArgsSchema.jsonSchema,
-            relatedResources: ["c64://context/bootstrap"],
+            relatedResources: ["c64://guide/bootstrap"],
             tags: ["drive", "reset"],
             prerequisites: ["drives_list"],
             examples: [
@@ -334,7 +334,7 @@ export const storageModule = defineToolModule({
             description: "Power on a specific Ultimate drive slot.",
             summary: "Ensures the selected drive is reported as powered and ready on the IEC bus.",
             inputSchema: driveOnlyArgsSchema.jsonSchema,
-            relatedResources: ["c64://context/bootstrap"],
+            relatedResources: ["c64://guide/bootstrap"],
             tags: ["drive", "power"],
             prerequisites: ["drives_list"],
             examples: [
@@ -377,7 +377,7 @@ export const storageModule = defineToolModule({
             description: "Power off a specific Ultimate drive slot.",
             summary: "Disables the drive without altering mounted media so it can be re-enabled later.",
             inputSchema: driveOnlyArgsSchema.jsonSchema,
-            relatedResources: ["c64://context/bootstrap"],
+            relatedResources: ["c64://guide/bootstrap"],
             tags: ["drive", "power"],
             prerequisites: ["drives_list"],
             examples: [
@@ -420,7 +420,7 @@ export const storageModule = defineToolModule({
             description: "Temporarily load a custom ROM into an Ultimate drive slot.",
             summary: "Points the drive at an alternative ROM file without flashing permanent storage.",
             inputSchema: driveLoadRomArgsSchema.jsonSchema,
-            relatedResources: ["c64://context/bootstrap"],
+            relatedResources: ["c64://guide/bootstrap"],
             tags: ["drive", "rom"],
             prerequisites: ["drives_list"],
             examples: [
@@ -463,7 +463,7 @@ export const storageModule = defineToolModule({
             description: "Set the emulation mode for an Ultimate drive slot (1541/1571/1581).",
             summary: "Switches the drive hardware profile to match the mounted media and desired behaviour.",
             inputSchema: driveModeArgsSchema.jsonSchema,
-            relatedResources: ["c64://context/bootstrap"],
+            relatedResources: ["c64://guide/bootstrap"],
             tags: ["drive", "mode"],
             prerequisites: ["drives_list"],
             examples: [
@@ -506,7 +506,7 @@ export const storageModule = defineToolModule({
             description: "Inspect metadata for a file on the Ultimate filesystem.",
             summary: "Queries the REST API for file size, type, and other details useful when managing disk images.",
             inputSchema: fileInfoArgsSchema.jsonSchema,
-            relatedResources: ["c64://context/bootstrap"],
+            relatedResources: ["c64://guide/bootstrap"],
             tags: ["storage", "info"],
             prerequisites: [],
             examples: [
@@ -543,7 +543,7 @@ export const storageModule = defineToolModule({
             description: "Create a blank D64 disk image on the Ultimate filesystem.",
             summary: "Allocates a 35 or 40 track D64 image with an optional disk name.",
             inputSchema: createD64ArgsSchema.jsonSchema,
-            relatedResources: ["c64://context/bootstrap"],
+            relatedResources: ["c64://guide/bootstrap"],
             tags: ["disk", "create"],
             prerequisites: ["drives_list"],
             examples: [
@@ -594,7 +594,7 @@ export const storageModule = defineToolModule({
             description: "Create a blank D71 disk image on the Ultimate filesystem.",
             summary: "Allocates a 1571-compatible disk image with optional labelling.",
             inputSchema: createD71ArgsSchema.jsonSchema,
-            relatedResources: ["c64://context/bootstrap"],
+            relatedResources: ["c64://guide/bootstrap"],
             tags: ["disk", "create"],
             prerequisites: ["drives_list"],
             examples: [
@@ -642,7 +642,7 @@ export const storageModule = defineToolModule({
             description: "Create a blank D81 disk image on the Ultimate filesystem.",
             summary: "Allocates a 1581-compatible disk image with optional labelling.",
             inputSchema: createD81ArgsSchema.jsonSchema,
-            relatedResources: ["c64://context/bootstrap"],
+            relatedResources: ["c64://guide/bootstrap"],
             tags: ["disk", "create"],
             prerequisites: ["drives_list"],
             examples: [
@@ -690,7 +690,7 @@ export const storageModule = defineToolModule({
             description: "Create a blank DNP disk image on the Ultimate filesystem.",
             summary: "Allocates a CMD-native DNP image with custom track count and optional label.",
             inputSchema: createDnpArgsSchema.jsonSchema,
-            relatedResources: ["c64://context/bootstrap"],
+            relatedResources: ["c64://guide/bootstrap"],
             tags: ["disk", "create"],
             prerequisites: [
                 "drives_list"

package/dist/tools/streaming.js

@@ -36,8 +36,8 @@ export const streamingModule = defineToolModule({
     domain: "streaming",
     summary: "Long-running or streaming workflows such as audio capture or SID playback monitoring.",
     resources: [
-        "c64://specs/sid",
-        "c64://docs/index",
+        "c64://sound/sid/spec",
+        "c64://guide/index",
     ],
     prompts: ["sid-music"],
     defaultLifecycle: "stream",
@@ -50,7 +50,7 @@ export const streamingModule = defineToolModule({
     tools: [
         {
             name: "stream_start",
-            description: "Start an Ultimate streaming session (video/audio/debug) targeting a host:port destination. See c64://docs/index for usage notes.",
+            description: "Start an Ultimate streaming session (video/audio/debug) targeting a host:port destination. See c64://guide/index for usage notes.",
             summary: "Validates stream arguments and forwards the request to firmware, returning status metadata.",
             inputSchema: streamStartArgsSchema.jsonSchema,
             tags: ["stream", "start"],

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

@@ -30,13 +30,65 @@ export function discriminatedUnionSchema(options) {
     if (!variants || variants.length === 0) {
         throw new Error("Discriminated union schemas require at least one variant.");
     }
+    // Flatten the discriminated union into a single object schema.
+    // Claude's API does not support oneOf/allOf/anyOf at the top level,
+    // so we merge all variant properties and use an enum for the discriminator.
+    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 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)
+                continue;
+            if (!mergedProperties[key]) {
+                mergedProperties[key] = propSchema;
+            }
+        }
+    }
+    const opPropertySchema = opValues.length > 0
+        ? { type: "string", enum: opValues, description: `Selects the operation.` }
+        : { type: "string", description: `Selects the operation.` };
+    const fullDescription = description
+        ? (opDescriptions.length > 0
+            ? `${description}\n\nOperations:\n${opDescriptions.map((d) => `- ${d}`).join("\n")}`
+            : description)
+        : (opDescriptions.length > 0
+            ? `Operations:\n${opDescriptions.map((d) => `- ${d}`).join("\n")}`
+            : undefined);
     const schema = {
         type: "object",
-        ...(description ? { description } : {}),
-        oneOf: [...variants],
-        discriminator: {
-            propertyName: discriminator,
+        ...(fullDescription ? { description: fullDescription } : {}),
+        properties: {
+            [discriminator]: opPropertySchema,
+            ...mergedProperties,
         },
+        required: [discriminator],
+        additionalProperties: false,
+        ...(operationMetadata.length > 0 ? { "x-c64bridge-operations": operationMetadata } : {}),
     };
     return schema;
 }

package/dist/tools/vice.js

@@ -15,11 +15,8 @@ const SAFE_RESOURCE_PREFIXES = [
 ];
 const resourceValueSchema = {
     jsonSchema: {
+        type: ["string", "integer"],
         description: "VICE resource value (string or integer).",
-        oneOf: [
-            { type: "string" },
-            { type: "integer" },
-        ],
     },
     parse(value, path) {
         const resolvedPath = path ?? "$.value";
@@ -110,7 +107,7 @@ const viceOperationDispatcher = createOperationDispatcher("c64_vice", viceOperat
 export const viceModuleGroup = defineToolModule({
     domain: "vice",
     summary: "VICE emulator helpers for safe runtime resource access.",
-    resources: ["c64://specs/memory-map"],
+    resources: ["c64://memory/map"],
     prompts: ["assembly-program", "memory-debug"],
     defaultTags: ["vice", "emulator"],
     workflowHints: [