c64bridge 0.8.1 → 0.9.1

package/dist/tools/audio.js

@@ -397,9 +397,9 @@ export const audioModule = defineToolModule({
     domain: "audio",
     summary: "SID composition, playback, and audio analysis workflows.",
     resources: [
-        "c64://specs/sid",
-        "c64://specs/sidwave",
-        "c64://docs/sid/file-structure",
+        "c64://sound/sid/spec",
+        "c64://sound/sidwave/spec",
+        "c64://sound/sid/file-format",
     ],
     prompts: ["sid-music"],
     defaultTags: ["sid", "audio"],
@@ -411,7 +411,7 @@ export const audioModule = defineToolModule({
     tools: [
         {
             name: "sid_volume",
-            description: "Set the SID master volume register at $D418. See c64://specs/sid.",
+            description: "Set the SID master volume register at $D418. See c64://sound/sid/spec.",
             summary: "Clamps the requested volume and writes it to the SID master volume register.",
             inputSchema: sidVolumeArgsSchema.jsonSchema,
             tags: ["sid", "control"],
@@ -496,7 +496,7 @@ export const audioModule = defineToolModule({
         },
         {
             name: "sid_note_on",
-            description: "Trigger a SID voice with configurable waveform, pulse width, and ADSR envelope. See c64://specs/sid.",
+            description: "Trigger a SID voice with configurable waveform, pulse width, and ADSR envelope. See c64://sound/sid/spec.",
             summary: "Resolves note or frequency, clamps parameters, and writes the SID voice registers.",
             inputSchema: sidNoteOnArgsSchema.jsonSchema,
             tags: ["sid", "control", "music", "pal-ntsc"],
@@ -700,7 +700,7 @@ export const audioModule = defineToolModule({
             description: "Play a SID file stored on the Ultimate filesystem via the firmware player.",
             summary: "Instructs the SID player to load the given file and optional song number.",
             inputSchema: sidplayFileArgsSchema.jsonSchema,
-            relatedResources: ["c64://specs/sid"],
+            relatedResources: ["c64://sound/sid/spec"],
             tags: ["sid", "playback"],
             prerequisites: ["drives_list"],
             examples: [
@@ -740,7 +740,7 @@ export const audioModule = defineToolModule({
             description: "Play a MOD tracker module stored on the Ultimate filesystem.",
             summary: "Sends the module to the Ultimate SID player and starts playback.",
             inputSchema: modplayFileArgsSchema.jsonSchema,
-            relatedResources: ["c64://specs/sid"],
+            relatedResources: ["c64://sound/sid/spec"],
             tags: ["sid", "playback"],
             prerequisites: ["drives_list"],
             examples: [
@@ -780,7 +780,7 @@ export const audioModule = defineToolModule({
             summary: "Builds a note timeline from semitone offsets and triggers SID playback asynchronously.",
             lifecycle: "fire-and-forget",
             inputSchema: musicGenerateArgsSchema.jsonSchema,
-            relatedResources: ["c64://specs/sid"],
+            relatedResources: ["c64://sound/sid/spec"],
             relatedPrompts: ["sid-music"],
             tags: ["sid", "music", "generator", "pal-ntsc"],
             prerequisites: ["sid_volume"],
@@ -862,7 +862,7 @@ export const audioModule = defineToolModule({
             description: "Compile a SIDWAVE composition to PRG or SID and optionally play it immediately.",
             summary: "Parses SIDWAVE/CPG input, compiles to a PRG, and plays via PRG or SID attachment.",
             inputSchema: musicCompileArgsSchema.jsonSchema,
-            relatedResources: ["c64://specs/sid", "c64://specs/sidwave", "c64://docs/sid/file-structure"],
+            relatedResources: ["c64://sound/sid/spec", "c64://sound/sidwave/spec", "c64://sound/sid/file-format"],
             relatedPrompts: ["sid-music"],
             tags: ["sid", "music", "compiler"],
             prerequisites: [],
@@ -945,7 +945,7 @@ export const audioModule = defineToolModule({
             description: "Record audio from the default input device and analyze SID playback characteristics.",
             summary: "Captures PCM data, extracts notes, tempo, and deviation metrics for SID verification workflows.",
             inputSchema: recordAndAnalyzeArgsSchema.jsonSchema,
-            relatedResources: ["c64://specs/sid", "c64://docs/sid/file-structure"],
+            relatedResources: ["c64://sound/sid/spec", "c64://sound/sid/file-format"],
             relatedPrompts: ["sid-music"],
             tags: ["sid", "analysis"],
             prerequisites: [],
@@ -985,7 +985,7 @@ export const audioModule = defineToolModule({
             description: "Automatically analyze SID playback when the user requests verification feedback.",
             summary: "Detects verification intent in natural language, records a short clip, and returns musical feedback.",
             inputSchema: analyzeAudioArgsSchema.jsonSchema,
-            relatedResources: ["c64://specs/sid", "c64://docs/sid/file-structure"],
+            relatedResources: ["c64://sound/sid/spec", "c64://sound/sid/file-format"],
             relatedPrompts: ["sid-music"],
             tags: ["sid", "analysis"],
             prerequisites: [],

package/dist/{basicConverter.js → tools/basicTokenizer.js}

@@ -6,7 +6,7 @@ Licensed under the GNU General Public License v2.0 or later.
 See <https://www.gnu.org/licenses/> for details.
 */
 import { Buffer } from "node:buffer";
-import { asciiToPetscii, encodeStringWithNames } from "./petscii.js";
+import { asciiToPetscii, encodeStringWithNames } from "../petscii.js";
 const DEFAULT_START_ADDRESS = 0x0801;
 const REM_TOKEN = 0x8f;
 const TOKEN_TABLE = buildTokenTable();

package/dist/tools/debug.js

@@ -57,6 +57,7 @@ const createCheckpointArgsSchema = objectSchema({
         stopOnHit: optionalSchema(booleanSchema({ description: "Pause execution when hit (default true).", default: true })),
         enabled: optionalSchema(booleanSchema({ description: "Whether the checkpoint is enabled (default true).", default: true })),
         temporary: optionalSchema(booleanSchema({ description: "Automatically remove after first hit.", default: false })),
+        label: optionalSchema(stringSchema({ description: "Optional human-readable label stored in-process.", maxLength: 64 })),
         operations: optionalSchema(objectSchema({
             description: "Checkpoint operation filters.",
             properties: {
@@ -147,6 +148,42 @@ const stepReturnArgsSchema = objectSchema({
     required: ["op"],
     additionalProperties: false,
 });
+const getMonitorStateArgsSchema = objectSchema({
+    description: "Read CPU registers and return the current monitor state.",
+    properties: {
+        op: literalSchema("get_monitor_state"),
+        memspace: memspaceSchema,
+    },
+    required: ["op"],
+    additionalProperties: false,
+});
+const waitForStateArgsSchema = objectSchema({
+    description: "Poll CPU registers until PC equals expectedPC or timeout elapses.",
+    properties: {
+        op: literalSchema("wait_for_state"),
+        expectedPC: optionalSchema(stringSchema({ description: "Target PC address to wait for (e.g. $0810).", minLength: 1 })),
+        timeoutMs: optionalSchema(numberSchema({ description: "Maximum wait time in milliseconds.", integer: true, minimum: 1, maximum: 60000, default: 5000 })),
+        pollMs: optionalSchema(numberSchema({ description: "Poll interval in milliseconds.", integer: true, minimum: 10, maximum: 1000, default: 100 })),
+    },
+    required: ["op"],
+    additionalProperties: false,
+});
+const nuclearResetArgsSchema = objectSchema({
+    description: "Kill and restart the VICE process (managed instances only).",
+    properties: {
+        op: literalSchema("nuclear_reset"),
+    },
+    required: ["op"],
+    additionalProperties: false,
+});
+const continueExecutionArgsSchema = objectSchema({
+    description: "Exit the Binary Monitor and resume CPU execution (BM 0xAA Exit).",
+    properties: {
+        op: literalSchema("continue_execution"),
+    },
+    required: ["op"],
+    additionalProperties: false,
+});
 const debugOperationSchemas = [
     listCheckpointsArgsSchema,
     getCheckpointArgsSchema,
@@ -159,14 +196,19 @@ const debugOperationSchemas = [
     setRegistersArgsSchema,
     stepArgsSchema,
     stepReturnArgsSchema,
+    getMonitorStateArgsSchema,
+    waitForStateArgsSchema,
+    nuclearResetArgsSchema,
+    continueExecutionArgsSchema,
 ];
+const checkpointLabels = new Map();
 const debugOperationHandlers = {
     list_checkpoints: async (_args, ctx) => {
         try {
             listCheckpointsArgsSchema.parse(_args);
             ctx.logger.info("Listing VICE checkpoints");
             const checkpoints = await ctx.client.viceCheckpointList();
-            return jsonResult({ checkpoints: checkpoints.map(formatCheckpoint) }, { success: true, count: checkpoints.length });
+            return jsonResult({ checkpoints: checkpoints.map((cp) => formatCheckpoint(cp, checkpointLabels.get(cp.id))) }, { success: true, count: checkpoints.length });
         }
         catch (error) {
             return handleToolError(error);
@@ -176,7 +218,7 @@ const debugOperationHandlers = {
         try {
             const parsed = getCheckpointArgsSchema.parse(args);
             const checkpoint = await ctx.client.viceCheckpointGet(parsed.id);
-            return jsonResult({ checkpoint: formatCheckpoint(checkpoint) }, { success: true });
+            return jsonResult({ checkpoint: formatCheckpoint(checkpoint, checkpointLabels.get(checkpoint.id)) }, { success: true });
         }
         catch (error) {
             return handleToolError(error);
@@ -201,8 +243,11 @@ const debugOperationHandlers = {
                 },
                 memspace: normaliseMemspace(parsed.memspace),
             });
-            ctx.logger.info("Created VICE checkpoint", { id: created.id, start: formatAddress(created.start) });
-            return jsonResult({ checkpoint: formatCheckpoint(created) }, { success: true, id: created.id });
+            if (parsed.label) {
+                checkpointLabels.set(created.id, parsed.label);
+            }
+            ctx.logger.info("Created VICE checkpoint", { id: created.id, start: formatAddress(created.start), label: parsed.label });
+            return jsonResult({ checkpoint: formatCheckpoint(created, checkpointLabels.get(created.id)) }, { success: true, id: created.id });
         }
         catch (error) {
             return handleToolError(error);
@@ -212,6 +257,7 @@ const debugOperationHandlers = {
         try {
             const parsed = deleteCheckpointArgsSchema.parse(args);
             await ctx.client.viceCheckpointDelete(parsed.id);
+            checkpointLabels.delete(parsed.id);
             ctx.logger.info("Deleted VICE checkpoint", { id: parsed.id });
             return textResult(`Deleted checkpoint ${parsed.id}.`, { success: true, id: parsed.id });
         }
@@ -345,12 +391,93 @@ const debugOperationHandlers = {
             return handleToolError(error);
         }
     },
+    get_monitor_state: async (args, ctx) => {
+        try {
+            const parsed = getMonitorStateArgsSchema.parse(args);
+            const memspace = normaliseMemspace(parsed.memspace);
+            const [metadata, values] = await Promise.all([
+                ctx.client.viceRegistersAvailable(memspace),
+                ctx.client.viceRegistersGet(memspace),
+            ]);
+            const metadataById = new Map(metadata.map((m) => [m.id, m]));
+            const registers = values.map((v) => {
+                const meta = metadataById.get(v.id);
+                return { id: v.id, name: meta?.name, bits: meta?.bits, size: v.size, value: v.value };
+            });
+            const pc = registers.find((r) => r.name?.toUpperCase() === "PC");
+            ctx.logger.info("Read monitor state", { memspace, pc: pc ? formatAddress(pc.value) : "unknown" });
+            return jsonResult({ memspace, registers, pc: pc ? formatAddress(pc.value) : undefined }, { success: true, memspace, count: registers.length });
+        }
+        catch (error) {
+            return handleToolError(error);
+        }
+    },
+    wait_for_state: async (args, ctx) => {
+        try {
+            const parsed = waitForStateArgsSchema.parse(args);
+            const timeoutMs = parsed.timeoutMs ?? 5000;
+            const pollMs = parsed.pollMs ?? 100;
+            const targetPC = parsed.expectedPC ? parseAddress(parsed.expectedPC, "expectedPC") : undefined;
+            const metadata = await ctx.client.viceRegistersAvailable(0);
+            const metadataById = new Map(metadata.map((m) => [m.id, m]));
+            const pcId = metadata.find((m) => m.name.toUpperCase() === "PC")?.id;
+            const deadline = Date.now() + timeoutMs;
+            let values = [];
+            let currentPC;
+            while (Date.now() < deadline) {
+                values = await ctx.client.viceRegistersGet(0);
+                currentPC = pcId !== undefined ? values.find((v) => v.id === pcId)?.value : undefined;
+                if (targetPC === undefined || currentPC === targetPC) {
+                    break;
+                }
+                await new Promise((res) => setTimeout(res, pollMs));
+            }
+            const matched = targetPC === undefined || currentPC === targetPC;
+            const regs = values.map((v) => {
+                const meta = metadataById.get(v.id);
+                return { id: v.id, name: meta?.name, bits: meta?.bits, size: v.size, value: v.value };
+            });
+            ctx.logger.info("wait_for_state settled", { matched, pc: currentPC !== undefined ? formatAddress(currentPC) : "unknown" });
+            return jsonResult({
+                matched,
+                timedOut: !matched,
+                pc: currentPC !== undefined ? formatAddress(currentPC) : undefined,
+                registers: regs,
+            }, { success: true, matched });
+        }
+        catch (error) {
+            return handleToolError(error);
+        }
+    },
+    nuclear_reset: async (args, ctx) => {
+        try {
+            nuclearResetArgsSchema.parse(args);
+            ctx.logger.info("Performing nuclear reset of VICE process");
+            await ctx.client.viceNuclearReset();
+            checkpointLabels.clear();
+            return textResult("VICE process stopped and restarted.", { success: true });
+        }
+        catch (error) {
+            return handleToolError(error);
+        }
+    },
+    continue_execution: async (args, ctx) => {
+        try {
+            continueExecutionArgsSchema.parse(args);
+            await ctx.client.viceExitMonitor();
+            ctx.logger.info("Exited Binary Monitor — CPU resumed");
+            return textResult("Execution resumed.", { success: true });
+        }
+        catch (error) {
+            return handleToolError(error);
+        }
+    },
 };
 const debugOperationDispatcher = createOperationDispatcher("c64_debug", debugOperationHandlers);
 export const debugModuleGroup = defineToolModule({
     domain: "debug",
     summary: "VICE Binary Monitor debugger operations (breakpoints, registers, stepping).",
-    resources: ["c64://specs/assembly", "c64://specs/memory-map"],
+    resources: ["c64://assembly/6510-spec", "c64://memory/map"],
     prompts: ["assembly-program", "memory-debug"],
     defaultTags: ["debug", "vice"],
     workflowHints: [
@@ -384,6 +511,31 @@ export const debugModuleGroup = defineToolModule({
                     description: "Read CPU registers from memspace 0 (default).",
                     arguments: { op: "get_registers" },
                 },
+                {
+                    name: "Create labelled breakpoint",
+                    description: "Set a breakpoint at $0810 with a descriptive label.",
+                    arguments: { op: "create_checkpoint", address: "$0810", label: "entry_point" },
+                },
+                {
+                    name: "Get monitor state",
+                    description: "Read current CPU state including all registers and PC.",
+                    arguments: { op: "get_monitor_state" },
+                },
+                {
+                    name: "Wait for PC",
+                    description: "Poll until PC reaches $0810 or 5 s elapses.",
+                    arguments: { op: "wait_for_state", expectedPC: "$0810", timeoutMs: 5000 },
+                },
+                {
+                    name: "Nuclear reset",
+                    description: "Kill and restart the VICE process, clearing all state.",
+                    arguments: { op: "nuclear_reset" },
+                },
+                {
+                    name: "Continue execution",
+                    description: "Exit the BM monitor and let the CPU run freely.",
+                    arguments: { op: "continue_execution" },
+                },
             ],
             execute: debugOperationDispatcher,
         },
@@ -395,9 +547,10 @@ function handleToolError(error) {
     }
     return unknownErrorResult(error);
 }
-function formatCheckpoint(checkpoint) {
+function formatCheckpoint(checkpoint, label) {
     return {
         id: checkpoint.id,
+        ...(label ? { label } : {}),
         start: formatAddress(checkpoint.start),
         end: formatAddress(checkpoint.end),
         enabled: checkpoint.enabled,

package/dist/tools/developer.js

@@ -123,8 +123,8 @@ export const developerModule = defineToolModule({
     domain: "developer",
     summary: "Configuration management, diagnostics, and helper utilities for advanced workflows.",
     resources: [
-        "c64://context/bootstrap",
-        "c64://docs/index",
+        "c64://guide/bootstrap",
+        "c64://guide/index",
     ],
     prompts: ["memory-debug"],
     defaultTags: ["developer", "config", "debug"],
@@ -138,7 +138,7 @@ export const developerModule = defineToolModule({
             description: "List configuration categories available on the Ultimate firmware.",
             summary: "Fetches the configuration tree and returns firmware-reported categories.",
             inputSchema: noArgsSchema.jsonSchema,
-            relatedResources: ["c64://context/bootstrap"],
+            relatedResources: ["c64://guide/bootstrap"],
             tags: ["config", "list"],
             examples: [
                 { name: "List configs", description: "Enumerate configuration categories", arguments: {} },
@@ -173,7 +173,7 @@ export const developerModule = defineToolModule({
             description: "Read a configuration category or specific item.",
             summary: "Returns firmware configuration data for the selected category (and item).",
             inputSchema: configGetArgsSchema.jsonSchema,
-            relatedResources: ["c64://context/bootstrap"],
+            relatedResources: ["c64://guide/bootstrap"],
             tags: ["config", "read"],
             examples: [
                 { name: "Get audio config", description: "Read audio category", arguments: { category: "Audio" } },
@@ -210,7 +210,7 @@ export const developerModule = defineToolModule({
             description: "Set a configuration value within a category.",
             summary: "Writes a primitive value to a specific configuration item via firmware APIs.",
             inputSchema: configSetArgsSchema.jsonSchema,
-            relatedResources: ["c64://context/bootstrap"],
+            relatedResources: ["c64://guide/bootstrap"],
             tags: ["config", "write"],
             examples: [
                 { name: "Set volume", description: "Adjust audio volume", arguments: { category: "Audio", item: "Volume", value: 75 } },
@@ -254,7 +254,7 @@ export const developerModule = defineToolModule({
             description: "Apply multiple configuration changes in a single request.",
             summary: "Sends a nested object of category/item values to the firmware batch endpoint.",
             inputSchema: configBatchSchema.jsonSchema,
-            relatedResources: ["c64://context/bootstrap"],
+            relatedResources: ["c64://guide/bootstrap"],
             tags: ["config", "write"],
             examples: [
                 { name: "Batch update", description: "Update multiple settings", arguments: { Audio: { Volume: 80, DACMode: "stereo" } } },
@@ -298,7 +298,7 @@ export const developerModule = defineToolModule({
             description: "Load configuration settings from flash storage.",
             summary: "Restores the firmware configuration by reading the persisted flash snapshot.",
             inputSchema: noArgsSchema.jsonSchema,
-            relatedResources: ["c64://context/bootstrap"],
+            relatedResources: ["c64://guide/bootstrap"],
             tags: ["config", "flash"],
             examples: [
                 { name: "Load from flash", description: "Restore saved configuration", arguments: {} },
@@ -334,7 +334,7 @@ export const developerModule = defineToolModule({
             description: "Persist current configuration settings to flash storage.",
             summary: "Saves the active configuration snapshot so it survives power cycles.",
             inputSchema: noArgsSchema.jsonSchema,
-            relatedResources: ["c64://context/bootstrap"],
+            relatedResources: ["c64://guide/bootstrap"],
             tags: ["config", "flash"],
             examples: [
                 { name: "Save to flash", description: "Persist current config", arguments: {} },
@@ -370,7 +370,7 @@ export const developerModule = defineToolModule({
             description: "Reset configuration categories to their factory defaults.",
             summary: "Instructs the firmware to discard overrides and restore default configuration values.",
             inputSchema: noArgsSchema.jsonSchema,
-            relatedResources: ["c64://context/bootstrap"],
+            relatedResources: ["c64://guide/bootstrap"],
             tags: ["config", "reset"],
             examples: [
                 { name: "Reset config", description: "Restore factory defaults", arguments: {} },
@@ -407,7 +407,7 @@ export const developerModule = defineToolModule({
             summary: "Calls the firmware version endpoint (Ultimate) or returns emulator info (VICE).",
             supportedPlatforms: ["c64u", "vice"],
             inputSchema: noArgsSchema.jsonSchema,
-            relatedResources: ["c64://context/bootstrap"],
+            relatedResources: ["c64://guide/bootstrap"],
             tags: ["diagnostics", "version"],
             examples: [
                 { name: "Get version", description: "Check firmware version", arguments: {} },
@@ -439,7 +439,7 @@ export const developerModule = defineToolModule({
             summary: "Returns the diagnostics payload reported by the firmware (Ultimate) or emulator (VICE).",
             supportedPlatforms: ["c64u", "vice"],
             inputSchema: noArgsSchema.jsonSchema,
-            relatedResources: ["c64://context/bootstrap"],
+            relatedResources: ["c64://guide/bootstrap"],
             tags: ["diagnostics", "info"],
             examples: [
                 { name: "Get hardware info", description: "Query hardware status", arguments: {} },
@@ -470,7 +470,7 @@ export const developerModule = defineToolModule({
             description: "Read the Ultimate debug register ($D7FF).",
             summary: "Returns the current hex value stored in the debug register.",
             inputSchema: noArgsSchema.jsonSchema,
-            relatedResources: ["c64://context/bootstrap"],
+            relatedResources: ["c64://guide/bootstrap"],
             tags: ["debug"],
             examples: [
                 { name: "Read debug register", description: "Check $D7FF value", arguments: {} },
@@ -509,7 +509,7 @@ export const developerModule = defineToolModule({
             description: "Write a value into the Ultimate debug register ($D7FF).",
             summary: "Validates the hex input and forwards it to the firmware.",
             inputSchema: debugWriteArgsSchema.jsonSchema,
-            relatedResources: ["c64://context/bootstrap"],
+            relatedResources: ["c64://guide/bootstrap"],
             tags: ["debug"],
             examples: [
                 { name: "Write debug register", description: "Set $D7FF to $42", arguments: { value: "42" } },