c64bridge 0.8.0 → 0.9.0

package/dist/device.js

@@ -18,6 +18,18 @@ const DEFAULT_VICE_PORT = 6502;
 function delay(ms) {
     return new Promise((resolve) => setTimeout(resolve, ms));
 }
+async function resumeViceMonitor(client, timeoutMs = 250) {
+    try {
+        const exitMonitor = client.exitMonitor().catch(() => { });
+        await Promise.race([
+            exitMonitor,
+            delay(timeoutMs),
+        ]);
+    }
+    catch {
+        // Ignore resume failures while tearing down a monitor session.
+    }
+}
 function coalesceMemoryWriteBlocks(blocks) {
     const merged = [];
     for (const block of blocks) {
@@ -215,12 +227,18 @@ export class ViceBackend {
         const configBinary = config.exe !== undefined
             ? configuredString(config.exe) ?? (typeof config.exe === "string" ? config.exe : String(config.exe))
             : undefined;
-        this.exe = resolveViceBinary({ envBinary, configBinary });
+        const resolvedLaunch = resolveViceLaunch({
+            envBinary,
+            configBinary,
+            envDirectory: configuredString(process.env.VICE_DIRECTORY),
+            configDirectory: configuredString(config.directory),
+        });
+        this.exe = resolvedLaunch.binary;
         const envHost = normaliseViceHost(process.env.VICE_HOST);
         const envPort = normaliseVicePort(process.env.VICE_PORT);
         this.host = firstDefined(envHost, normaliseViceHost(config.host)) ?? DEFAULT_VICE_HOST;
         this.port = firstDefined(envPort, normaliseVicePort(config.port)) ?? DEFAULT_VICE_PORT;
-        this.directory = firstDefined(resolveViceDirectory(configuredString(process.env.VICE_DIRECTORY)), resolveViceDirectory(configuredString(config.directory)), findViceResourceDirectory(this.exe));
+        this.directory = resolvedLaunch.directory;
         this.mockMode = (process.env.VICE_TEST_TARGET || "").toLowerCase() === "mock";
         const hostLower = this.host.toLowerCase();
         const isLocal = hostLower === "127.0.0.1" || hostLower === "localhost";
@@ -238,6 +256,10 @@ export class ViceBackend {
                 console.error("[vice-backend] probing existing VICE", this.host, this.port);
             await client.connect(this.port, this.host);
             await client.info();
+            try {
+                await client.exitMonitor();
+            }
+            catch { }
             if (this.debugEnabled)
                 console.error("[vice-backend] existing VICE is reachable");
             return true;
@@ -257,6 +279,10 @@ export class ViceBackend {
             try {
                 await client.connect(this.port, this.host);
                 await client.info();
+                try {
+                    await client.exitMonitor();
+                }
+                catch { }
                 return;
             }
             catch (error) {
@@ -275,6 +301,7 @@ export class ViceBackend {
         const client = new ViceClient();
         try {
             await client.connect(this.port, this.host);
+            await client.reset();
             const readiness = await waitForBasicReady(client, { timeoutMs, ensurePrompt: true });
             if (!readiness.pointersOk || !readiness.promptOk) {
                 throw new Error(`VICE machine at ${this.host}:${this.port} did not reach the BASIC prompt within ${timeoutMs}ms`);
@@ -358,7 +385,7 @@ export class ViceBackend {
             ViceBackend.supervisors.clear();
         });
     }
-    async withClient(fn) {
+    async withClient(fn, options) {
         const previous = this.monitorQueue;
         let releaseQueue = () => { };
         this.monitorQueue = new Promise((resolve) => {
@@ -385,6 +412,9 @@ export class ViceBackend {
                 return await fn(client);
             }
             finally {
+                if (options?.resumeOnClose !== false) {
+                    await resumeViceMonitor(client);
+                }
                 if (this.debugEnabled)
                     console.error("[vice-backend] closing VICE monitor connection");
                 client.close();
@@ -532,7 +562,7 @@ export class ViceBackend {
                 catch {
                     // Ignore transport errors during quit; the emulator will terminate regardless.
                 }
-            });
+            }, { resumeOnClose: false });
             if (managedHandle) {
                 try {
                     await managedHandle.stop();
@@ -775,9 +805,45 @@ function resolveViceBinary(options, findBinary = which) {
     }
     return findBinary("x64sc") ?? findBinary("x64") ?? "x64sc";
 }
+function resolveViceLaunch(options, dependencies = {}) {
+    const findBinary = dependencies.findBinary ?? which;
+    const isResourceDirectory = dependencies.isResourceDirectory ?? isViceResourceDirectory;
+    const explicitBinary = firstDefined(options.envBinary, options.configBinary);
+    const explicitDirectory = firstDefined(resolveViceDirectoryWithValidator(options.envDirectory, isResourceDirectory), resolveViceDirectoryWithValidator(options.configDirectory, isResourceDirectory));
+    let binary = resolveViceBinary({ envBinary: options.envBinary, configBinary: options.configBinary }, findBinary);
+    if (explicitDirectory) {
+        return { binary, directory: explicitDirectory };
+    }
+    const adjacentDirectory = findViceResourceDirectory(binary, {
+        allowGlobalFallback: false,
+        isResourceDirectory,
+    });
+    if (adjacentDirectory) {
+        return { binary, directory: adjacentDirectory };
+    }
+    if (explicitBinary) {
+        return {
+            binary,
+            directory: findViceResourceDirectory(binary, {
+                allowGlobalFallback: true,
+                isResourceDirectory,
+            }),
+        };
+    }
+    return {
+        binary,
+        directory: findViceResourceDirectory(binary, {
+            allowGlobalFallback: true,
+            isResourceDirectory,
+        }),
+    };
+}
 export function __resolveViceBinaryForTests(options, findBinary) {
     return resolveViceBinary(options, findBinary ?? which);
 }
+export function __resolveViceLaunchForTests(options, dependencies) {
+    return resolveViceLaunch(options, dependencies);
+}
 export async function createFacade(logger, options) {
     // Caller-forced preference: use c64u with provided base URL (used by tests and server wiring)
     if (options?.preferredC64uBaseUrl) {
@@ -935,7 +1001,15 @@ function resolveViceDirectory(value) {
     }
     return isViceResourceDirectory(input) ? input : undefined;
 }
-function findViceResourceDirectory(binaryPath) {
+function resolveViceDirectoryWithValidator(value, isResourceDirectory) {
+    const input = configuredString(value);
+    if (!input) {
+        return undefined;
+    }
+    return isResourceDirectory(input) ? input : undefined;
+}
+function findViceResourceDirectory(binaryPath, options = {}) {
+    const isResourceDirectory = options.isResourceDirectory ?? isViceResourceDirectory;
     const candidates = new Set();
     const resolvedBinary = configuredString(binaryPath);
     if (resolvedBinary) {
@@ -943,12 +1017,14 @@ function findViceResourceDirectory(binaryPath) {
         candidates.add(path.resolve(binaryDir, "..", "share", "vice"));
         candidates.add(path.resolve(binaryDir, "..", "..", "share", "vice"));
     }
-    candidates.add("/usr/local/share/vice");
-    candidates.add("/usr/share/vice");
-    candidates.add("/opt/homebrew/share/vice");
-    candidates.add("/opt/local/share/vice");
+    if (options.allowGlobalFallback !== false) {
+        candidates.add("/usr/local/share/vice");
+        candidates.add("/usr/share/vice");
+        candidates.add("/opt/homebrew/share/vice");
+        candidates.add("/opt/local/share/vice");
+    }
     for (const candidate of candidates) {
-        if (isViceResourceDirectory(candidate)) {
+        if (isResourceDirectory(candidate)) {
             return candidate;
         }
     }

package/dist/mcp-server.js

@@ -8,6 +8,7 @@ import { CallToolRequestSchema, ListResourcesRequestSchema, ListToolsRequestSche
 import { loadConfig } from "./config.js";
 import { C64Client } from "./c64Client.js";
 import { listKnowledgeResources, readKnowledgeResource, } from "./rag/knowledgeIndex.js";
+import { PLATFORM_RESOURCE_URI } from "./rag/resourceUris.js";
 import { createLazyRagRetriever, initRag } from "./rag/init.js";
 import { getMcpServerImplementationInfo } from "./mcp/metadata.js";
 import { toolRegistry } from "./tools/registry/index.js";
@@ -417,7 +418,6 @@ async function main() {
         diagnosticsFile: diagnostics.filePath,
     });
 }
-const PLATFORM_RESOURCE_URI = "c64://platform/status";
 function createPlatformResourceDescriptor() {
     return {
         uri: PLATFORM_RESOURCE_URI,

package/dist/prompts/registry.js

@@ -1,4 +1,5 @@
 import { listKnowledgeResources } from "../rag/knowledgeIndex.js";
+import { RESOURCE_URIS } from "../rag/resourceUris.js";
 import { toolRegistry } from "../tools/registry/index.js";
 const ASSEMBLY_HARDWARE_NOTES = {
     sid: [
@@ -34,6 +35,7 @@ const ROUTING_CORE_SEGMENT = {
     content: [
         "Prompts in this repository define intent and routing only.",
         "Execution logic, validation steps, and safety rules live exclusively in `.github/skills/*/SKILL.md`.",
+        `When the request targets the \`vice\` backend, read \`${RESOURCE_URIS.vice.binaryMonitorSpec}\` before executing the skill so Binary Monitor single-client behaviour, trap/resume semantics, and monitor-side side effects stay in scope.`,
         "Use the referenced skill, extract missing inputs from the user request, execute the skill, and summarize the outcome.",
     ].join("\n"),
 };
@@ -115,7 +117,7 @@ export function createPromptRegistry() {
                 name: "hello-world",
                 title: "Hello World Workflow",
                 description: "Route ultra-fast hello-world and smoke-test requests to the canonical greeting skill.",
-                requiredResources: ["c64://context/bootstrap", "c64://context/fast-paths", "c64://docs/index"],
+                requiredResources: [RESOURCE_URIS.guide.bootstrap, RESOURCE_URIS.guide.fastPaths, RESOURCE_URIS.guide.index],
                 optionalResources: [],
                 tools: ["c64_program"],
                 tags: ["hello", "demo", "greeting", "smoke-test"],
@@ -134,8 +136,8 @@ export function createPromptRegistry() {
                 name: "basic-program",
                 title: "BASIC Program Workflow",
                 description: "Route bespoke Commodore BASIC v2 requests to the canonical BASIC skill.",
-                requiredResources: ["c64://specs/basic", "c64://context/bootstrap", "c64://docs/index"],
-                optionalResources: ["c64://context/fast-paths"],
+                requiredResources: [RESOURCE_URIS.basic.spec, RESOURCE_URIS.guide.bootstrap, RESOURCE_URIS.guide.index],
+                optionalResources: [RESOURCE_URIS.guide.fastPaths],
                 tools: ["c64_program", "c64_memory"],
                 tags: ["basic", "program"],
             },
@@ -150,7 +152,7 @@ export function createPromptRegistry() {
                 name: "cross-platform-demo",
                 title: "Cross-Platform Demo Workflow",
                 description: "Route quick visible demo requests to the cross-platform demo skill.",
-                requiredResources: ["c64://context/bootstrap", "c64://context/fast-paths", "c64://docs/index"],
+                requiredResources: [RESOURCE_URIS.guide.bootstrap, RESOURCE_URIS.guide.fastPaths, RESOURCE_URIS.guide.index],
                 optionalResources: [],
                 tools: ["c64_program"],
                 tags: ["demo", "platform", "greeting"],
@@ -166,8 +168,8 @@ export function createPromptRegistry() {
                 name: "preset-music-demo",
                 title: "Preset Music Demo Workflow",
                 description: "Route quick recognizable tune requests to the SID music skill.",
-                requiredResources: ["c64://specs/sid", "c64://specs/sidwave", "c64://context/fast-paths"],
-                optionalResources: ["c64://docs/sid/best-practices"],
+                requiredResources: [RESOURCE_URIS.sound.sid.spec, RESOURCE_URIS.sound.sidwave.spec, RESOURCE_URIS.guide.fastPaths],
+                optionalResources: [RESOURCE_URIS.sound.sid.bestPractices],
                 tools: ["c64_sound"],
                 tags: ["sid", "music", "demo"],
             },
@@ -181,8 +183,8 @@ export function createPromptRegistry() {
                 name: "assembly-program",
                 title: "Assembly Program Workflow",
                 description: "Route 6502/6510 routine requests to the canonical assembly skill.",
-                requiredResources: ["c64://specs/assembly", "c64://specs/vic", "c64://specs/sid", "c64://context/bootstrap"],
-                optionalResources: ["c64://docs/sid/best-practices"],
+                requiredResources: [RESOURCE_URIS.assembly.spec6510, RESOURCE_URIS.graphics.vic.spec, RESOURCE_URIS.sound.sid.spec, RESOURCE_URIS.guide.bootstrap],
+                optionalResources: [RESOURCE_URIS.sound.sid.bestPractices],
                 tools: ["c64_program", "c64_memory"],
                 tags: ["assembly", "program"],
             },
@@ -201,7 +203,7 @@ export function createPromptRegistry() {
             selectOptionalResources: (args) => {
                 const hardware = args.hardware;
                 return hardware === "sid" || hardware === "multi"
-                    ? ["c64://docs/sid/best-practices"]
+                    ? [RESOURCE_URIS.sound.sid.bestPractices]
                     : [];
             },
             renderRoutingNotes: (args) => {
@@ -220,12 +222,12 @@ export function createPromptRegistry() {
                 title: "SID Composition Workflow",
                 description: "Route SID playback and composition work to the canonical SID skill.",
                 requiredResources: [
-                    "c64://specs/sid",
-                    "c64://specs/sidwave",
-                    "c64://docs/sid/file-structure",
-                    "c64://docs/sid/best-practices",
+                    RESOURCE_URIS.sound.sid.spec,
+                    RESOURCE_URIS.sound.sidwave.spec,
+                    RESOURCE_URIS.sound.sid.fileFormat,
+                    RESOURCE_URIS.sound.sid.bestPractices,
                 ],
-                optionalResources: ["c64://context/fast-paths"],
+                optionalResources: [RESOURCE_URIS.guide.fastPaths],
                 tools: ["c64_sound"],
                 tags: ["sid", "music"],
             },
@@ -239,8 +241,8 @@ export function createPromptRegistry() {
                 name: "graphics-demo",
                 title: "Graphics Demo Workflow",
                 description: "Route graphics requests to the canonical graphics skill.",
-                requiredResources: ["c64://specs/vic", "c64://context/bootstrap"],
-                optionalResources: ["c64://specs/assembly", "c64://specs/charset", "c64://docs/petscii-style"],
+                requiredResources: [RESOURCE_URIS.graphics.vic.spec, RESOURCE_URIS.guide.bootstrap],
+                optionalResources: [RESOURCE_URIS.assembly.spec6510, RESOURCE_URIS.graphics.characterSet, RESOURCE_URIS.graphics.petscii.styleGuide],
                 tools: ["c64_program", "c64_memory", "c64_graphics"],
                 tags: ["graphics", "vic"],
             },
@@ -271,12 +273,12 @@ export function createPromptRegistry() {
                 name: "printer-job",
                 title: "Printer Job Workflow",
                 description: "Route printer work to the canonical printer skill.",
-                requiredResources: ["c64://specs/printer", "c64://docs/printer/guide", "c64://docs/printer/prompts"],
+                requiredResources: [RESOURCE_URIS.printer.spec, RESOURCE_URIS.printer.promptGuide],
                 optionalResources: [
-                    "c64://docs/printer/commodore-text",
-                    "c64://docs/printer/commodore-bitmap",
-                    "c64://docs/printer/epson-text",
-                    "c64://docs/printer/epson-bitmap",
+                    RESOURCE_URIS.printer.commodore.text,
+                    RESOURCE_URIS.printer.commodore.bitmap,
+                    RESOURCE_URIS.printer.epson.text,
+                    RESOURCE_URIS.printer.epson.bitmap,
                 ],
                 tools: ["c64_printer"],
                 tags: ["printer"],
@@ -296,10 +298,10 @@ export function createPromptRegistry() {
             selectOptionalResources: (args) => {
                 const printerType = args.printerType;
                 if (printerType === "commodore") {
-                    return ["c64://docs/printer/commodore-text", "c64://docs/printer/commodore-bitmap"];
+                    return [RESOURCE_URIS.printer.commodore.text, RESOURCE_URIS.printer.commodore.bitmap];
                 }
                 if (printerType === "epson") {
-                    return ["c64://docs/printer/epson-text", "c64://docs/printer/epson-bitmap"];
+                    return [RESOURCE_URIS.printer.epson.text, RESOURCE_URIS.printer.epson.bitmap];
                 }
                 return [];
             },
@@ -315,7 +317,7 @@ export function createPromptRegistry() {
                 name: "memory-debug",
                 title: "Memory Debug Workflow",
                 description: "Route reversible memory inspection or patching work to the canonical memory skill.",
-                requiredResources: ["c64://context/bootstrap", "c64://specs/assembly", "c64://docs/index"],
+                requiredResources: [RESOURCE_URIS.guide.bootstrap, RESOURCE_URIS.assembly.spec6510, RESOURCE_URIS.guide.index],
                 optionalResources: [],
                 tools: ["c64_memory", "c64_system"],
                 tags: ["memory", "debug"],
@@ -330,7 +332,7 @@ export function createPromptRegistry() {
                 name: "drive-manager",
                 title: "Drive Manager Workflow",
                 description: "Route disk-image and drive-state requests to the canonical drive skill.",
-                requiredResources: ["c64://context/bootstrap"],
+                requiredResources: [RESOURCE_URIS.guide.bootstrap],
                 optionalResources: [],
                 tools: ["c64_disk", "c64_drive"],
                 tags: ["drive", "storage"],