c64bridge 0.9.3 → 1.0.1

package/dist/mcp-server.js

@@ -1,9 +1,11 @@
 #!/usr/bin/env node
 import "./bootstrap/stdio-logger.js";
+import { createServer } from "node:http";
 import { dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
 import { Server } from "@modelcontextprotocol/sdk/server/index.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
 import { CallToolRequestSchema, ListResourcesRequestSchema, ListToolsRequestSchema, ReadResourceRequestSchema, ListPromptsRequestSchema, GetPromptRequestSchema, } from "@modelcontextprotocol/sdk/types.js";
 import { loadConfig } from "./config.js";
 import { C64Client } from "./c64Client.js";
@@ -32,7 +34,7 @@ function createPromptRegistryGetter() {
         return registry;
     };
 }
-function parseCliOptions(argv) {
+export function parseCliOptions(argv) {
     const httpIndex = argv.indexOf("--http");
     if (httpIndex === -1) {
         return { mode: "stdio" };
@@ -165,7 +167,7 @@ async function main() {
                         {
                             uri: PLATFORM_RESOURCE_URI,
                             mimeType: "text/markdown",
-                            text: renderPlatformStatusMarkdown(client),
+                            text: await renderPlatformStatusMarkdown(client),
                         },
                     ],
                 };
@@ -420,12 +422,34 @@ async function main() {
             throw error;
         }
     });
-    // Connect via stdio
-    const transport = new StdioServerTransport();
-    await server.connect(transport);
-    writeDiagnosticEvent("mcp_transport_connected", { mode: "stdio" });
+    const cli = parseCliOptions(process.argv.slice(2));
+    if (cli.mode === "http") {
+        const transport = new StreamableHTTPServerTransport({ sessionIdGenerator: undefined });
+        await server.connect(transport);
+        const port = cli.port ?? 3000;
+        const httpServer = createServer((request, response) => {
+            if (request.url?.split("?")[0] !== "/mcp") {
+                response.statusCode = 404;
+                response.end("Not found");
+                return;
+            }
+            void transport.handleRequest(request, response).catch((error) => {
+                if (!response.headersSent)
+                    response.statusCode = 500;
+                response.end(error instanceof Error ? error.message : "MCP transport error");
+            });
+        });
+        await new Promise((resolve, reject) => httpServer.listen(port, "127.0.0.1", resolve).once("error", reject));
+        writeDiagnosticEvent("mcp_transport_connected", { mode: "http", port });
+        console.error(`c64bridge MCP server running on HTTP at http://127.0.0.1:${port}/mcp`);
+    }
+    else {
+        const transport = new StdioServerTransport();
+        await server.connect(transport);
+        writeDiagnosticEvent("mcp_transport_connected", { mode: "stdio" });
+        console.error("c64bridge MCP server running on stdio");
+    }
     await logConnectivity(client, baseUrl);
-    console.error("c64bridge MCP server running on stdio");
     writeDiagnosticEvent("server_ready", {
         diagnosticsFile: diagnostics.filePath,
     });
@@ -447,10 +471,18 @@ function createPlatformResourceDescriptor() {
         },
     };
 }
-function renderPlatformStatusMarkdown(client) {
+export async function renderPlatformStatusMarkdown(client) {
     const status = getPlatformStatus();
     const availableBackends = client.getAvailableBackends();
     const capabilities = describePlatformCapabilities(toolRegistry.list());
+    // Resource reads must remain responsive while an Ultimate boots or is
+    // unreachable. The probe itself remains retryable (unknown is not cached).
+    const nativeEndpoints = await Promise.race([
+        client.getNativeEndpointCapabilities(),
+        new Promise((resolve) => {
+            setTimeout(() => resolve({ machineInput: "unknown", machineMenuScreen: "unknown" }), 750).unref();
+        }),
+    ]);
     const lines = [
         "# MCP Platform Status",
         "",
@@ -466,6 +498,13 @@ function renderPlatformStatusMarkdown(client) {
         status.limitedFeatures.length > 0
             ? ["## Limited or Unavailable Features", "", ...status.limitedFeatures.map((feature) => `- ${feature}`)].join("\n")
             : "",
+        "## Native REST Endpoint Availability",
+        "",
+        `- \`machine:input\`: **${nativeEndpoints.machineInput}**`,
+        `- \`machine:menu_screen\`: **${nativeEndpoints.machineMenuScreen}** (it can only be confirmed while an Ultimate menu is visible)`,
+        "",
+        "Use physical-input, menu-screen, and C64U/U64 Tool Menu power-cycle operations only when the required endpoint is available. Prefer `key` or `write_text` for ordinary C64 input when `machine:input` is unavailable.",
+        "",
         "## Tool Compatibility",
         "",
     ].filter(Boolean);
@@ -487,7 +526,7 @@ function renderPlatformStatusMarkdown(client) {
 }
 async function logConnectivity(client, baseUrl) {
     const backendType = await client.getBackendType();
-    if (backendType !== "c64u") {
+    if (backendType === "vice") {
         writeDiagnosticEvent("connectivity_probe_skipped", { baseUrl, reason: "vice_backend" });
         console.error("Skipping direct REST connectivity probe because active backend is VICE");
         try {
@@ -582,11 +621,21 @@ function toPromptMessage(segment) {
         },
     };
 }
-main().catch((error) => {
-    writeDiagnosticEvent("server_fatal", {
-        diagnosticsFile: getDiagnosticsSessionInfo()?.filePath,
-        error,
+// The documented entrypoint (src/index.ts / dist/index.js, per package.json
+// "main"/"bin") always imports this module as a side effect rather than
+// invoking it as the process's own script, so process.argv[1] never points
+// here — an entrypoint-identity check would wrongly skip startup in every
+// real deployment. Test code that only needs a pure export (e.g.
+// parseCliOptions, renderPlatformStatusMarkdown) sets this opt-out instead,
+// mirroring the existing C64BRIDGE_START_SKIP_AUTO_LAUNCH convention in
+// scripts/start.mjs.
+if (process.env.C64BRIDGE_SKIP_AUTO_START !== "1") {
+    main().catch((error) => {
+        writeDiagnosticEvent("server_fatal", {
+            diagnosticsFile: getDiagnosticsSessionInfo()?.filePath,
+            error,
+        });
+        console.error("Fatal error in MCP server:", error);
+        process.exit(1);
     });
-    console.error("Fatal error in MCP server:", error);
-    process.exit(1);
-});
+}

package/dist/platform.js

@@ -10,6 +10,10 @@ const PLATFORM_FEATURES = {
         ],
         limited: [],
     },
+    u2: {
+        features: ["ultimate-rest-api", "cartridge-execution", "sid-control", "drive-management", "printer-integration"],
+        limited: ["no-machine-input", "no-debugreg", "no-poweroff", "no-streaming"],
+    },
     vice: {
         features: [
             "software-emulation",
@@ -23,7 +27,7 @@ const PLATFORM_FEATURES = {
         limited: ["no-rest-api", "no-firmware-filesystem", "no-flash-config", "limited-sid"],
     },
 };
-let currentPlatform = process.env.C64_MODE === "vice" ? "vice" : "c64u";
+let currentPlatform = process.env.C64_MODE === "vice" ? "vice" : process.env.C64_MODE === "u2" ? "u2" : "c64u";
 export function getPlatformStatus() {
     const spec = PLATFORM_FEATURES[currentPlatform];
     return {
@@ -48,11 +52,12 @@ export function isPlatformSupported(platform, supported) {
 export function describePlatformCapabilities(tools) {
     const map = {
         c64u: { available: [], unsupported: [] },
+        u2: { available: [], unsupported: [] },
         vice: { available: [], unsupported: [] },
     };
     for (const tool of tools) {
         const supported = tool.metadata.platforms ?? ["c64u"];
-        for (const id of ["c64u", "vice"]) {
+        for (const id of ["c64u", "u2", "vice"]) {
             if (supported.includes(id)) {
                 map[id].available.push(tool.name);
             }
@@ -69,6 +74,12 @@ export function describePlatformCapabilities(tools) {
                 tools: map.c64u.available.sort(),
                 unsupported_tools: map.c64u.unsupported.sort(),
             },
+            u2: {
+                features: PLATFORM_FEATURES.u2.features,
+                limited_features: PLATFORM_FEATURES.u2.limited,
+                tools: map.u2.available.sort(),
+                unsupported_tools: map.u2.unsupported.sort(),
+            },
             vice: {
                 features: PLATFORM_FEATURES.vice.features,
                 limited_features: PLATFORM_FEATURES.vice.limited,

package/dist/rag/indexer.js

@@ -4,16 +4,19 @@ GPL-2.0-only
 */
 import fs from "node:fs/promises";
 import path from "node:path";
+import { fileURLToPath } from "node:url";
 import fsSync from "node:fs";
-const BASIC_DIR = path.resolve("data/basic/examples");
-const ASM_DIR = path.resolve("data/assembly/examples");
-const EXTERNAL_DIR = path.resolve("external");
-const DOC_ROOT = path.resolve("doc");
+const PACKAGE_ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..", "..");
+const ASSET_ROOT = process.env.C64BRIDGE_ASSET_ROOT ? path.resolve(process.env.C64BRIDGE_ASSET_ROOT) : PACKAGE_ROOT;
+const BASIC_DIR = path.join(ASSET_ROOT, "data/basic/examples");
+const ASM_DIR = path.join(ASSET_ROOT, "data/assembly/examples");
+const EXTERNAL_DIR = path.join(ASSET_ROOT, "external");
+const DOC_ROOT = path.join(ASSET_ROOT, "doc");
 const DOC_EXCLUDE_DIRS = new Set(["plans"]);
-const CONTEXT_DIR = path.resolve("data/context");
+const CONTEXT_DIR = path.join(ASSET_ROOT, "data/context");
 const BOOTSTRAP_PATH = path.join(CONTEXT_DIR, "bootstrap.md");
-const AGENTS_PATH = path.resolve("AGENTS.md");
-const PROMPTS_DIR = path.resolve(".github/prompts");
+const AGENTS_PATH = path.join(ASSET_ROOT, "AGENTS.md");
+const PROMPTS_DIR = path.join(ASSET_ROOT, ".github/prompts");
 const CHAT_PATH = path.join(CONTEXT_DIR, "chat.md");
 // RAG_DOC_FILES env var can add extra specific files, comma-separated
 const ENV_DOC_FILES = (process.env.RAG_DOC_FILES ?? "")
@@ -34,7 +37,7 @@ function shouldExcludeDocFile(file) {
     return firstSegment !== undefined && DOC_EXCLUDE_DIRS.has(firstSegment);
 }
 function resolveEmbeddingsDir(override) {
-    return path.resolve(override ?? process.env.RAG_EMBEDDINGS_DIR ?? "data");
+    return path.resolve(override ?? process.env.RAG_EMBEDDINGS_DIR ?? path.join(ASSET_ROOT, "data"));
 }
 function embeddingIndexPaths(dir) {
     return {

package/dist/rag/init.js

@@ -4,22 +4,25 @@ GPL-2.0-only
 */
 import fs from "node:fs/promises";
 import path from "node:path";
+import { fileURLToPath } from "node:url";
 import { setTimeout as delay } from "node:timers/promises";
 import { LocalMiniHashEmbedding } from "./embeddings.js";
 import { buildAllIndexes, loadIndexes } from "./indexer.js";
 import { LocalRagRetriever } from "./retriever.js";
 import { LoggingRagRetriever } from "./loggingRetriever.js";
-const EXTERNAL_DIR = path.resolve("external");
-const BASIC_DATA_DIR = path.resolve("data/basic/examples");
-const ASM_DATA_DIR = path.resolve("data/assembly/examples");
-const DOC_DIR = path.resolve("doc");
-const CONTEXT_DIR = path.resolve("data/context");
+const PACKAGE_ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..", "..");
+const assetRoot = process.env.C64BRIDGE_ASSET_ROOT ? path.resolve(process.env.C64BRIDGE_ASSET_ROOT) : PACKAGE_ROOT;
+const EXTERNAL_DIR = path.join(assetRoot, "external");
+const BASIC_DATA_DIR = path.join(assetRoot, "data/basic/examples");
+const ASM_DATA_DIR = path.join(assetRoot, "data/assembly/examples");
+const DOC_DIR = path.join(assetRoot, "doc");
+const CONTEXT_DIR = path.join(assetRoot, "data/context");
 const BOOTSTRAP_PATH = path.join(CONTEXT_DIR, "bootstrap.md");
-const AGENTS_PATH = path.resolve("AGENTS.md");
-const PROMPTS_DIR = path.resolve(".github/prompts");
+const AGENTS_PATH = path.join(assetRoot, "AGENTS.md");
+const PROMPTS_DIR = path.join(assetRoot, ".github/prompts");
 const CHAT_PATH = path.join(CONTEXT_DIR, "chat.md");
 function resolveEmbeddingsDir() {
-    return path.resolve(process.env.RAG_EMBEDDINGS_DIR ?? "data");
+    return path.resolve(process.env.RAG_EMBEDDINGS_DIR ?? path.join(assetRoot, "data"));
 }
 function embeddingIndexPaths() {
     const dir = resolveEmbeddingsDir();

package/dist/sidwaveCompiler.js

@@ -169,9 +169,9 @@ export function compileSidwaveToSid(doc, prg, options) {
     const body = Buffer.isBuffer(prg) ? prg : Buffer.from(prg);
     return { sid: Buffer.concat([header, body]) };
 }
-function hzToSidFrequency(hz, system) {
+export function hzToSidFrequency(hz, system) {
     const phi2 = system === "PAL" ? 985248 : 1022727;
-    const value = Math.round((hz * 65536) / phi2);
+    const value = Math.round((hz * 16777216) / phi2);
     return Math.max(0, Math.min(0xffff, value));
 }
 function waveformToCtrl(w) {

package/dist/tools/audio.js

@@ -9,6 +9,12 @@ const NOTE_PATTERN = /^([A-Ga-g])([#b]?)(-?\d+)$/;
 const DEFAULT_SILENCE_VERIFY_DURATION_SECONDS = 1.5;
 const DEFAULT_SILENCE_VERIFY_RMS_THRESHOLD = 0.02;
 const DEFAULT_SILENCE_VERIFY_WAIT_MS = 150;
+const generatedPlaybacks = new Set();
+export function cancelGeneratedSidPlayback() {
+    for (const controller of generatedPlaybacks)
+        controller.abort();
+    generatedPlaybacks.clear();
+}
 function toRecord(details) {
     if (details && typeof details === "object") {
         return details;
@@ -403,7 +409,7 @@ export const audioModule = defineToolModule({
     ],
     prompts: ["sid-music"],
     defaultTags: ["sid", "audio"],
-    supportedPlatforms: ["c64u", "vice"],
+    supportedPlatforms: ["c64u", "u2", "vice"],
     workflowHints: [
         "Reach for SID helpers when the user talks about sound design, playback quality, or stuck notes.",
         "After changing playback state, suggest verify-by-ear steps such as analyze_audio so the user gets concrete feedback.",
@@ -473,6 +479,7 @@ export const audioModule = defineToolModule({
                 try {
                     const parsed = sidResetArgsSchema.parse(args ?? {});
                     ctx.logger.info("Resetting SID", { mode: parsed.hard ? "hard" : "soft" });
+                    cancelGeneratedSidPlayback(); // Reset is the documented way to stop a generated arpeggio.
                     const result = await ctx.client.sidReset(parsed.hard);
                     if (!result.success) {
                         throw new ToolExecutionError("C64 firmware reported failure while resetting SID", {
@@ -622,6 +629,7 @@ export const audioModule = defineToolModule({
                     const parsed = sidSilenceArgsSchema.parse(args ?? {});
                     const verify = Boolean(parsed.verify);
                     ctx.logger.info("Silencing all SID voices", { verify });
+                    cancelGeneratedSidPlayback(); // Otherwise its remaining notes would resume writing right after this silences the chip.
                     const result = await ctx.client.sidSilenceAll();
                     if (!result.success) {
                         throw new ToolExecutionError("C64 firmware reported failure while silencing SID", {
@@ -812,10 +820,17 @@ export const audioModule = defineToolModule({
                         tempoMs: parsed.tempoMs,
                         waveform: parsed.waveform,
                     });
+                    cancelGeneratedSidPlayback(); // Replace any prior generated arpeggio rather than letting two run at once.
+                    const controller = new AbortController();
+                    generatedPlaybacks.add(controller);
+                    const pinnedFacadePromise = ctx.client.pinFacade ? ctx.client.pinFacade() : Promise.resolve(undefined); // Pin once so a later select_backend can't retarget notes mid-arpeggio (HARD01-030).
                     void (async () => {
                         try {
-                            await ctx.client.sidSetVolume(8);
+                            const pinnedFacade = await pinnedFacadePromise;
+                            await ctx.client.sidSetVolume(8, pinnedFacade);
                             for (let i = 0; i < parsed.steps; i += 1) {
+                                if (controller.signal.aborted)
+                                    break;
                                 const iv = intervals[i % intervals.length];
                                 const note = transposeNote(parsed.root, iv);
                                 await ctx.client.sidNoteOn({
@@ -827,18 +842,24 @@ export const audioModule = defineToolModule({
                                     decay: 7,
                                     sustain: 15,
                                     release: 0,
-                                });
+                                }, pinnedFacade);
                                 const durationMs = parsed.preset === "expression" ? expressiveDurations[i % expressiveDurations.length] : parsed.tempoMs;
-                                await sleep(durationMs);
+                                await sleep(Math.max(1, Math.min(20, Math.floor(durationMs / 8)))); // Clear GATE between notes so every note retriggers ADSR.
+                                await ctx.client.sidNoteOff(1, pinnedFacade);
+                                if (!controller.signal.aborted)
+                                    await sleep(Math.max(0, durationMs - Math.max(1, Math.min(20, Math.floor(durationMs / 8)))));
                             }
-                            await ctx.client.sidNoteOff(1);
+                            await ctx.client.sidNoteOff(1, pinnedFacade);
                         }
                         catch (playbackError) {
                             const message = playbackError instanceof Error ? playbackError.message : String(playbackError);
                             ctx.logger.warn("music_generate playback failed", { error: message });
                         }
+                        finally {
+                            generatedPlaybacks.delete(controller);
+                        }
                     })();
-                    return textResult(`Scheduled ${parsed.steps} note arpeggio starting on ${parsed.root}.`, {
+                    return textResult(`Scheduled ${parsed.steps} note arpeggio starting on ${parsed.root}. Playback is running and will be replaced by the next generated sequence.`, {
                         success: true,
                         root: parsed.root,
                         intervals,

package/dist/tools/developer.js

@@ -146,7 +146,7 @@ export const developerModule = defineToolModule({
             workflowHints: [
                 "Run first to enumerate categories before reading or writing specific settings; summarise the top-level sections for the user.",
             ],
-            supportedPlatforms: ["c64u", "vice"],
+            supportedPlatforms: ["c64u", "u2", "vice"],
             async execute(args, ctx) {
                 try {
                     noArgsSchema.parse(args ?? {});
@@ -182,7 +182,7 @@ export const developerModule = defineToolModule({
             workflowHints: [
                 "Use after config_list to fetch details; restate category/item so the user can cross-check values before changes.",
             ],
-            supportedPlatforms: ["c64u", "vice"],
+            supportedPlatforms: ["c64u", "u2", "vice"],
             async execute(args, ctx) {
                 try {
                     const parsed = configGetArgsSchema.parse(args ?? {});
@@ -218,7 +218,7 @@ export const developerModule = defineToolModule({
             workflowHints: [
                 "Confirm the user-supplied value before writing; mention whether a reboot is required for the change to take effect.",
             ],
-            supportedPlatforms: ["c64u", "vice"],
+            supportedPlatforms: ["c64u", "u2", "vice"],
             async execute(args, ctx) {
                 try {
                     const parsed = configSetArgsSchema.parse(args ?? {});
@@ -262,7 +262,7 @@ export const developerModule = defineToolModule({
             workflowHints: [
                 "Use when multiple categories must be updated together; remind the user to review validation errors closely.",
             ],
-            supportedPlatforms: ["c64u", "vice"],
+            supportedPlatforms: ["c64u", "u2", "vice"],
             async execute(args, ctx) {
                 try {
                     const payload = configBatchSchema.parse(args ?? {});
@@ -405,7 +405,7 @@ export const developerModule = defineToolModule({
             name: "version",
             description: "Retrieve firmware or emulator version information.",
             summary: "Calls the firmware version endpoint (Ultimate) or returns emulator info (VICE).",
-            supportedPlatforms: ["c64u", "vice"],
+            supportedPlatforms: ["c64u", "u2", "vice"],
             inputSchema: noArgsSchema.jsonSchema,
             relatedResources: ["c64://guide/bootstrap"],
             tags: ["diagnostics", "version"],
@@ -437,7 +437,7 @@ export const developerModule = defineToolModule({
             name: "info",
             description: "Retrieve hardware or emulator information and status.",
             summary: "Returns the diagnostics payload reported by the firmware (Ultimate) or emulator (VICE).",
-            supportedPlatforms: ["c64u", "vice"],
+            supportedPlatforms: ["c64u", "u2", "vice"],
             inputSchema: noArgsSchema.jsonSchema,
             relatedResources: ["c64://guide/bootstrap"],
             tags: ["diagnostics", "info"],

package/dist/tools/graphics.js

@@ -577,7 +577,7 @@ export const graphicsModule = defineToolModule({
                 "Use when the user supplies sprite bytes or asks to preview graphics quickly; describe resulting coordinates and colours.",
                 "Remind the user that sprites live in banked memory so further tweaks may require write_memory calls.",
             ],
-            supportedPlatforms: ["c64u", "vice"],
+            supportedPlatforms: ["c64u", "u2", "vice"],
             async execute(args, ctx) {
                 return executeGenerateSprite(args, ctx);
             },
@@ -594,7 +594,7 @@ export const graphicsModule = defineToolModule({
                 "Use when the user wants to display an external image on screen rather than generate PETSCII art.",
                 "Call out the selected bitmap and screen RAM addresses so follow-up memory inspection or raster work stays grounded.",
             ],
-            supportedPlatforms: ["c64u", "vice"],
+            supportedPlatforms: ["c64u", "u2", "vice"],
             async execute(args, ctx) {
                 return executeGenerateBitmap(args, ctx);
             },
@@ -619,7 +619,7 @@ export const graphicsModule = defineToolModule({
                 "Call after generating PETSCII text or when the user wants border/background colour changes applied.",
                 "Echo the colour indices and mention CLEAR + PRINT so the user knows what ran.",
             ],
-            supportedPlatforms: ["c64u", "vice"],
+            supportedPlatforms: ["c64u", "u2", "vice"],
             async execute(args, ctx) {
                 return executeRenderPetscii(args, ctx);
             },
@@ -645,7 +645,7 @@ export const graphicsModule = defineToolModule({
                 "Response includes petsciiCodes array and glyphs for character-level inspection.",
                 "Provide follow-up suggestions like saving the PRG or capturing the screen after rendering.",
             ],
-            supportedPlatforms: ["c64u", "vice"],
+            supportedPlatforms: ["c64u", "u2", "vice"],
             async execute(args, ctx) {
                 return executeCreatePetscii(args, ctx);
             },