c64bridge 0.9.3 → 1.0.1

package/dist/tools/input.js

@@ -1,7 +1,16 @@
 import { createOperationDispatcher, defineToolModule, discriminatedUnionSchema, } from "./types.js";
 import { arraySchema, literalSchema, numberSchema, objectSchema, optionalSchema, stringSchema, } from "./schema.js";
-import { textResult } from "./responses.js";
+import { jsonResult, textResult } from "./responses.js";
 import { ToolValidationError, toolErrorResult, unknownErrorResult, } from "./errors.js";
+function isMissingNativeInputEndpoint(error) {
+    return typeof error === "object"
+        && error !== null
+        && "response" in error
+        && error.response?.status === 404;
+}
+function nativeInputUnavailableResult(operation) {
+    return textResult(`Native physical input is unavailable on this firmware, so ${operation} was not sent. Use c64://platform/status before choosing native input; use key or write_text for ordinary C64 input.`, { success: false, code: "native_input_unavailable", fallback: "key_or_write_text" });
+}
 // ---------------------------------------------------------------------------
 // PETSCII token expansion table
 // Maps {TOKEN} placeholders to PETSCII/control-byte values that are queued via
@@ -82,13 +91,9 @@ function expandPetsciiTokens(text) {
 }
 // ---------------------------------------------------------------------------
 // Joystick helpers
-// Port 2 → CIA1 Port A ($DC00), Port 1 → CIA1 Port B ($DC01)
-// Bits 0-4: Up / Down / Left / Right / Fire, active LOW (0 = pressed)
+// Bits 0-4: Up / Down / Left / Right / Fire, active LOW (0 = pressed).
+// VICE must use Binary Monitor Joyport Set; CIA register writes are not input.
 // ---------------------------------------------------------------------------
-const JOYSTICK_PORT_ADDRESS = {
-    1: 0xDC01,
-    2: 0xDC00,
-};
 const JOYSTICK_BIT = {
     up: 0,
     down: 1,
@@ -96,6 +101,14 @@ const JOYSTICK_BIT = {
     right: 3,
     fire: 4,
 };
+const KEYBOARD_INPUTS = [
+    "inst_del", "return", "cursor_left_right", "f7", "f1", "f3", "f5", "cursor_up_down",
+    "0", "1", "2", "3", "4", "5", "6", "7", "8", "9",
+    "a", "b", "c", "d", "e", "f", "g", "h", "i", "j", "k", "l", "m", "n", "o", "p", "q", "r", "s", "t", "u", "v", "w", "x", "y", "z",
+    "left_shift", "right_shift", "plus", "minus", "period", "colon", "at", "comma", "pound", "star", "semicolon", "clr_home", "equals", "arrow_up", "slash", "arrow_left", "ctrl", "space", "commodore", "run_stop", "restore",
+];
+const JOYSTICK_INPUTS = ["up", "down", "left", "right", "fire", "fire2", "fire3"];
+const INPUT_TRANSITIONS = ["press", "release", "tap"];
 function joystickByte(controls) {
     let mask = 0xff;
     for (const ctrl of controls) {
@@ -157,18 +170,18 @@ export const keyArgsSchema = objectSchema({
     additionalProperties: false,
 });
 export const joystickArgsSchema = objectSchema({
-    description: "Simulate joystick input by writing directly to CIA1 Port A/B registers.",
+    description: "Simulate joystick input. On C64U/U64 this uses machine:input; VICE uses Binary Monitor Joyport Set.",
     properties: {
         op: literalSchema("joystick"),
         port: numberSchema({
-            description: "Joystick port (1 = $DC01, 2 = $DC00).",
+            description: "Joystick port (1 or 2).",
             integer: true,
             minimum: 1,
             maximum: 2,
         }),
         controls: arraySchema(stringSchema({
             description: "Control to activate.",
-            enum: ["up", "down", "left", "right", "fire"],
+            enum: JOYSTICK_INPUTS,
         }), {
             description: "List of controls to activate simultaneously.",
             minItems: 0,
@@ -188,6 +201,32 @@ export const joystickArgsSchema = objectSchema({
     required: ["op", "port", "controls", "action"],
     additionalProperties: false,
 });
+export const keyboardArgsSchema = objectSchema({
+    description: "Send physical C64 keyboard matrix events through machine:input (a C64U firmware version that provides it, or U64 3.15+).",
+    properties: {
+        op: literalSchema("keyboard"),
+        inputs: arraySchema(stringSchema({ description: "Physical keyboard input.", enum: KEYBOARD_INPUTS }), {
+            description: "One or more keys to transition together (for example left_shift + a).",
+            minItems: 1,
+            maxItems: 8,
+        }),
+        transition: stringSchema({ description: "press holds, release frees, tap presses and releases.", enum: INPUT_TRANSITIONS }),
+    },
+    required: ["op", "inputs", "transition"],
+    additionalProperties: false,
+});
+const releaseAllArgsSchema = objectSchema({
+    description: "Release every key and joystick control injected through machine:input (a C64U firmware version that provides it, or U64 3.15+).",
+    properties: { op: literalSchema("release_all") },
+    required: ["op"],
+    additionalProperties: false,
+});
+const inputStateArgsSchema = objectSchema({
+    description: "Read the keys and joystick controls held through machine:input (a C64U firmware version that provides it, or U64 3.15+).",
+    properties: { op: literalSchema("state") },
+    required: ["op"],
+    additionalProperties: false,
+});
 // ---------------------------------------------------------------------------
 // Handlers
 // ---------------------------------------------------------------------------
@@ -250,30 +289,92 @@ const inputOperationHandlers = {
         try {
             const parsed = joystickArgsSchema.parse(args);
             const port = parsed.port;
-            const addr = JOYSTICK_PORT_ADDRESS[port];
             const durationMs = parsed.durationMs ?? 80;
             const pressedByte = joystickByte(parsed.controls);
             const releasedByte = 0xff;
+            const platform = await ctx.client.getActiveBackendType();
+            if (platform === "c64u") {
+                if (parsed.controls.length === 0 && parsed.action === "release") {
+                    const state = await ctx.client.sendInputEvents({ events: [{ kind: "release_all" }] });
+                    return textResult("Released all REST-injected keyboard and joystick inputs.", { success: true, action: "release_all", state });
+                }
+                const state = await ctx.client.sendInputEvents({
+                    events: [{ kind: "joystick", port, inputs: [...parsed.controls], transition: parsed.action }],
+                });
+                return textResult(`Joystick port ${port} ${parsed.action}: ${parsed.controls.join(", ")}.`, {
+                    success: true, port, action: parsed.action, controls: parsed.controls, state,
+                });
+            }
+            if (parsed.controls.some((control) => !(control in JOYSTICK_BIT))) {
+                throw new ToolValidationError("VICE joystick supports up, down, left, right, and fire only.", { path: "$.controls" });
+            }
             if (parsed.action === "release") {
-                await ctx.client.viceMemSet(addr, Uint8Array.of(releasedByte));
-                ctx.logger.info("Released joystick", { port, address: `$${addr.toString(16).toUpperCase()}` });
+                await ctx.client.viceJoyportSet(port, releasedByte);
+                ctx.logger.info("Released joystick", { port });
                 return textResult(`Joystick port ${port} released.`, { success: true, port, action: "release" });
             }
             if (parsed.action === "press") {
-                await ctx.client.viceMemSet(addr, Uint8Array.of(pressedByte));
+                await ctx.client.viceJoyportSet(port, pressedByte);
                 ctx.logger.info("Pressed joystick", { port, controls: parsed.controls, byte: pressedByte });
                 return textResult(`Joystick port ${port} pressed: ${parsed.controls.join(", ") || "none"}.`, { success: true, port, action: "press", controls: parsed.controls });
             }
             // tap: press → wait → release
-            await ctx.client.viceMemSet(addr, Uint8Array.of(pressedByte));
+            await ctx.client.viceJoyportSet(port, pressedByte);
             await new Promise((res) => setTimeout(res, durationMs));
-            await ctx.client.viceMemSet(addr, Uint8Array.of(releasedByte));
+            await ctx.client.viceJoyportSet(port, releasedByte);
             ctx.logger.info("Tapped joystick", { port, controls: parsed.controls, durationMs });
             return textResult(`Joystick port ${port} tapped: ${parsed.controls.join(", ") || "none"} for ${durationMs}ms.`, { success: true, port, action: "tap", controls: parsed.controls, durationMs });
         }
         catch (error) {
             if (error instanceof ToolValidationError)
                 return toolErrorResult(error);
+            if (isMissingNativeInputEndpoint(error))
+                return nativeInputUnavailableResult("the joystick event");
+            return unknownErrorResult(error);
+        }
+    },
+    keyboard: async (args, ctx) => {
+        try {
+            const parsed = keyboardArgsSchema.parse(args);
+            const state = await ctx.client.sendInputEvents({
+                events: [{ kind: "keyboard", inputs: [...parsed.inputs], transition: parsed.transition }],
+            });
+            return textResult(`Keyboard ${parsed.transition}: ${parsed.inputs.join(", ")}.`, {
+                success: true, inputs: parsed.inputs, transition: parsed.transition, state,
+            });
+        }
+        catch (error) {
+            if (error instanceof ToolValidationError)
+                return toolErrorResult(error);
+            if (isMissingNativeInputEndpoint(error))
+                return nativeInputUnavailableResult("the keyboard event");
+            return unknownErrorResult(error);
+        }
+    },
+    release_all: async (args, ctx) => {
+        try {
+            releaseAllArgsSchema.parse(args);
+            const state = await ctx.client.sendInputEvents({ events: [{ kind: "release_all" }] });
+            return textResult("Released all REST-injected keyboard and joystick inputs.", { success: true, state });
+        }
+        catch (error) {
+            if (error instanceof ToolValidationError)
+                return toolErrorResult(error);
+            if (isMissingNativeInputEndpoint(error))
+                return nativeInputUnavailableResult("the release request");
+            return unknownErrorResult(error);
+        }
+    },
+    state: async (args, ctx) => {
+        try {
+            inputStateArgsSchema.parse(args);
+            return jsonResult(await ctx.client.getInputState());
+        }
+        catch (error) {
+            if (error instanceof ToolValidationError)
+                return toolErrorResult(error);
+            if (isMissingNativeInputEndpoint(error))
+                return nativeInputUnavailableResult("the input-state query");
             return unknownErrorResult(error);
         }
     },
@@ -283,30 +384,36 @@ const inputOperationHandlers = {
 // ---------------------------------------------------------------------------
 export const inputModule = defineToolModule({
     domain: "input",
-    summary: "Cross-platform keyboard input plus VICE-only joystick simulation.",
-    supportedPlatforms: ["c64u", "vice"],
+    summary: "Keyboard input plus native Ultimate REST keyboard and joystick control.",
+    supportedPlatforms: ["c64u", "u2", "vice"],
     resources: ["c64://guide/bootstrap", "c64://memory/map", "c64://io/cia/spec"],
     prompts: [],
     defaultTags: ["input"],
     workflowHints: [
-        "Use write_text with {RETURN} tokens to automate BASIC entry; prefer key for individual control keys.",
+        "Use write_text with {RETURN} tokens to automate BASIC entry; use key for one PETSCII/KERNAL queue key. Neither is for navigating Ultimate firmware menus.",
         "write_text and key inject through the KERNAL keyboard queue ($0277/$00C6) so they work on both C64U and VICE.",
-        "Joystick tap is suitable for one-shot moves; use press/release pairs for timed holds. Joystick is VICE-only.",
+        "Use keyboard for physical C64 key combinations (including modifiers) on machine:input, and release_all to recover from interrupted holds. It requires a C64U firmware version that provides the endpoint, or U64 3.15+.",
+        "Before native input, read c64://platform/status. If machine:input is unavailable or unknown, use key or write_text for ordinary C64 input instead of attempting physical matrix events.",
+        "Change C64U/U64/U2 configuration through c64_config REST operations, never by keyboard menu navigation. Use keyboard navigation only where REST has no equivalent, such as the machine code monitor, visual SID editor, or Tool Menu.",
+        "Joystick uses machine:input on a C64U firmware version that provides the endpoint or U64 3.15+; VICE supports up/down/left/right/fire through its monitor.",
     ],
     tools: [
         {
             name: "c64_input",
-            description: "Keyboard buffer injection (cross-platform) and joystick simulation (VICE only).",
-            summary: "Types text, taps keys, and simulates joystick movements.",
+            description: "Cross-platform PETSCII typing plus native Ultimate keyboard and joystick events.",
+            summary: "Types text, sends physical key combinations, and controls joysticks.",
             inputSchema: discriminatedUnionSchema({
-                description: "Input operations: write_text, key, joystick.",
+                description: "Input operations: write_text, key, keyboard, joystick, release_all, state.",
                 variants: [
                     writeTextArgsSchema.jsonSchema,
                     keyArgsSchema.jsonSchema,
                     joystickArgsSchema.jsonSchema,
+                    keyboardArgsSchema.jsonSchema,
+                    releaseAllArgsSchema.jsonSchema,
+                    inputStateArgsSchema.jsonSchema,
                 ],
             }),
-            operationPlatforms: { joystick: ["vice"] },
+            operationPlatforms: { joystick: ["c64u", "vice"], keyboard: ["c64u"], release_all: ["c64u"], state: ["c64u"] },
             tags: ["input", "keyboard", "joystick"],
             examples: [
                 {
@@ -324,6 +431,11 @@ export const inputModule = defineToolModule({
                     description: "Brief rightward tap on joystick port 2",
                     arguments: { op: "joystick", port: 2, controls: ["right"], action: "tap", durationMs: 80 },
                 },
+                {
+                    name: "Type an uppercase A",
+                    description: "Tap a physical key chord through Ultimate REST input",
+                    arguments: { op: "keyboard", inputs: ["left_shift", "a"], transition: "tap" },
+                },
                 {
                     name: "Press fire on port 1",
                     description: "Hold fire button on joystick port 1",

package/dist/tools/machineControl.js

@@ -1,6 +1,7 @@
 import { defineToolModule } from "./types.js";
 import { objectSchema } from "./schema.js";
-import { textResult } from "./responses.js";
+import { jsonResult, textResult } from "./responses.js";
+import { Buffer } from "node:buffer";
 import { ToolError, ToolExecutionError, toolErrorResult, unknownErrorResult, } from "./errors.js";
 function createNoArgsSchema(description) {
     return objectSchema({
@@ -24,12 +25,20 @@ function normaliseFailure(details) {
     }
     return { value: details };
 }
+function isMissingMenuScreenEndpoint(error) {
+    return typeof error === "object"
+        && error !== null
+        && "response" in error
+        && error.response?.status === 404;
+}
 const resetArgsSchema = createNoArgsSchema("No arguments required to reset the C64.");
 const rebootArgsSchema = createNoArgsSchema("No arguments required to reboot the C64 firmware.");
 const pauseArgsSchema = createNoArgsSchema("No arguments required to pause the machine.");
 const resumeArgsSchema = createNoArgsSchema("No arguments required to resume the machine after a pause.");
 const poweroffArgsSchema = createNoArgsSchema("No arguments required to power off the machine.");
+const powerCycleArgsSchema = createNoArgsSchema("No arguments required to power cycle the active system.");
 const menuButtonArgsSchema = createNoArgsSchema("No arguments required to toggle the Ultimate menu button.");
+const readMenuScreenArgsSchema = createNoArgsSchema("No arguments required to read the active Ultimate menu screen matrix.");
 export const machineControlModule = defineToolModule({
     domain: "machine",
     summary: "Power, reset, pause/resume, and diagnostic controls for the C64 and Ultimate hardware.",
@@ -54,7 +63,7 @@ export const machineControlModule = defineToolModule({
             workflowHints: [
                 "Use when the user wants a quick restart without losing power; mention that memory contents may persist.",
             ],
-            supportedPlatforms: ["c64u", "vice"],
+            supportedPlatforms: ["c64u", "u2", "vice"],
             async execute(args, ctx) {
                 try {
                     resetArgsSchema.parse(args ?? {});
@@ -92,7 +101,7 @@ export const machineControlModule = defineToolModule({
             workflowHints: [
                 "Choose reboot when configuration changed or hardware is stuck; warn that it will interrupt any running program.",
             ],
-            supportedPlatforms: ["c64u", "vice"],
+            supportedPlatforms: ["c64u", "u2", "vice"],
             async execute(args, ctx) {
                 try {
                     rebootArgsSchema.parse(args ?? {});
@@ -130,7 +139,7 @@ export const machineControlModule = defineToolModule({
             workflowHints: [
                 "Pause when the user needs a stable memory snapshot; remind them to resume to continue execution.",
             ],
-            supportedPlatforms: ["c64u"],
+            supportedPlatforms: ["c64u", "u2"],
             async execute(args, ctx) {
                 try {
                     pauseArgsSchema.parse(args ?? {});
@@ -168,7 +177,7 @@ export const machineControlModule = defineToolModule({
             workflowHints: [
                 "Call after a pause or diagnostic halt and confirm the machine is running again.",
             ],
-            supportedPlatforms: ["c64u"],
+            supportedPlatforms: ["c64u", "u2"],
             async execute(args, ctx) {
                 try {
                     resumeArgsSchema.parse(args ?? {});
@@ -231,6 +240,41 @@ export const machineControlModule = defineToolModule({
                 }
             },
         },
+        {
+            name: "power_cycle",
+            description: "Return the active system to a fresh state: C64U/U64 uses verified Tool Menu navigation, U2-family reboots through REST, and managed VICE restarts.",
+            summary: "Performs the platform-appropriate full power-cycle equivalent and reports the strategy used.",
+            inputSchema: powerCycleArgsSchema.jsonSchema,
+            tags: ["power", "reboot", "fresh-start"],
+            prerequisites: [],
+            examples: [
+                { name: "Fresh start", description: "Power cycle the active system", arguments: {} },
+            ],
+            workflowHints: [
+                "Use only when the user explicitly requests a fresh start or power cycle; it interrupts active work.",
+                "On C64U/U64, verify Tool Menu navigation through machine:menu_screen before selecting Power Cycle.",
+            ],
+            supportedPlatforms: ["c64u", "u2", "vice"],
+            async execute(args, ctx) {
+                try {
+                    powerCycleArgsSchema.parse(args ?? {});
+                    ctx.logger.info("Power cycling active backend");
+                    const result = await ctx.client.powerCycle();
+                    if (!result.success) {
+                        throw new ToolExecutionError("Power cycle did not complete", {
+                            details: normaliseFailure(result.details),
+                        });
+                    }
+                    const details = toRecord(result.details) ?? {};
+                    return textResult("Power-cycle request completed.", { success: true, details });
+                }
+                catch (error) {
+                    if (error instanceof ToolError)
+                        return toolErrorResult(error);
+                    return unknownErrorResult(error);
+                }
+            },
+        },
         {
             name: "menu_button",
             description: "Toggle the Ultimate 64 menu button.",
@@ -244,7 +288,7 @@ export const machineControlModule = defineToolModule({
             workflowHints: [
                 "Use when the user needs to open or close the Ultimate menu; suggest following up with drive operations if relevant.",
             ],
-            supportedPlatforms: ["c64u"],
+            supportedPlatforms: ["c64u", "u2"],
             async execute(args, ctx) {
                 try {
                     menuButtonArgsSchema.parse(args ?? {});
@@ -269,5 +313,40 @@ export const machineControlModule = defineToolModule({
                 }
             },
         },
+        {
+            name: "read_menu_screen",
+            description: "Read the raw character and colour matrix for the currently visible Ultimate menu screen.",
+            summary: "Returns the firmware-defined menu matrix bytes, including text and colour information.",
+            inputSchema: readMenuScreenArgsSchema.jsonSchema,
+            tags: ["menu", "screen", "diagnostic"],
+            prerequisites: ["menu_button"],
+            examples: [
+                { name: "Inspect active menu", description: "Read the currently visible Ultimate menu", arguments: {} },
+            ],
+            workflowHints: [
+                "Read c64://platform/status first. Call after opening the Ultimate menu; if the endpoint is unavailable or no menu is active, the tool returns fallback guidance instead of a transport error.",
+                "The firmware returns an opaque character-and-colour matrix, preserved as base64 without guessing a layout.",
+            ],
+            supportedPlatforms: ["c64u", "u2"],
+            async execute(args, ctx) {
+                try {
+                    readMenuScreenArgsSchema.parse(args ?? {});
+                    const bytes = await ctx.client.readMenuScreen();
+                    return jsonResult({
+                        encoding: "base64",
+                        byteLength: bytes.length,
+                        matrix: Buffer.from(bytes).toString("base64"),
+                    });
+                }
+                catch (error) {
+                    if (error instanceof ToolError)
+                        return toolErrorResult(error);
+                    if (isMissingMenuScreenEndpoint(error)) {
+                        return textResult("No menu matrix is available. Open the Ultimate menu and retry; if it remains unavailable, this firmware does not provide machine:menu_screen. Use REST configuration instead of menu navigation where possible.", { success: false, code: "native_menu_screen_unavailable", fallback: "rest_configuration_or_manual_menu" });
+                    }
+                    return unknownErrorResult(error);
+                }
+            },
+        },
     ],
 });

package/dist/tools/memory.js

@@ -243,11 +243,12 @@ async function executeWriteMemory(rawArgs, ctx) {
                 details: detailRecord,
             });
         }
+        const pinnedFacade = ctx.client.pinFacade ? await ctx.client.pinFacade() : undefined; // Pin for this whole pause/read/write/resume sequence so a concurrent select_backend can't retarget it (HARD01-016).
         const canPause = supportsMachinePause(ctx);
         let paused = false;
         try {
             if (canPause) {
-                const pauseResult = await ctx.client.pause();
+                const pauseResult = await ctx.client.pause(pinnedFacade);
                 if (!pauseResult.success) {
                     throw new ToolExecutionError("C64 firmware reported failure while pausing", {
                         details: normaliseFailure(pauseResult.details),
@@ -258,7 +259,7 @@ async function executeWriteMemory(rawArgs, ctx) {
             const expectedBytes = expectedInfo?.bytes ?? new Uint8Array();
             const maskBytes = maskInfo?.bytes;
             const readLength = Math.max(1, Math.max(writeInfo.bytes.length, expectedBytes.length));
-            const preRead = await ctx.client.readMemory(parsed.address, String(readLength));
+            const preRead = await ctx.client.readMemory(parsed.address, String(readLength), pinnedFacade);
             if (!preRead.success) {
                 throw new ToolExecutionError("C64 firmware reported failure while reading memory", {
                     details: normaliseFailure(preRead.details),
@@ -286,13 +287,13 @@ async function executeWriteMemory(rawArgs, ctx) {
                     });
                 }
             }
-            const writeResult = await ctx.client.writeMemory(parsed.address, writeInfo.canonical);
+            const writeResult = await ctx.client.writeMemory(parsed.address, writeInfo.canonical, pinnedFacade);
             if (!writeResult.success) {
                 throw new ToolExecutionError("C64 firmware reported failure while writing memory", {
                     details: normaliseFailure(writeResult.details),
                 });
             }
-            const postRead = await ctx.client.readMemory(parsed.address, String(Math.max(1, writeInfo.bytes.length)));
+            const postRead = await ctx.client.readMemory(parsed.address, String(Math.max(1, writeInfo.bytes.length)), pinnedFacade);
             if (!postRead.success) {
                 throw new ToolExecutionError("C64 firmware reported failure while reading back memory", {
                     details: normaliseFailure(postRead.details),
@@ -336,6 +337,20 @@ async function executeWriteMemory(rawArgs, ctx) {
             if (preMismatches.length > 0) {
                 verificationMetadata.preReadMismatches = preMismatches;
             }
+            if (paused) { // A failed resume here leaves the machine paused: a recoverable operation failure, not a log.
+                const resumeResult = await ctx.client.resume(pinnedFacade);
+                if (!resumeResult.success) {
+                    throw new ToolExecutionError("Write completed but the machine could not be resumed", {
+                        details: {
+                            machinePaused: true,
+                            resume: normaliseFailure(resumeResult.details),
+                            recovery: "Call c64_system with op 'resume' before further machine operations.",
+                            verification: verificationMetadata,
+                        },
+                    });
+                }
+                paused = false;
+            }
             return textResult(`Wrote ${resolvedLength ?? "the provided"} bytes starting at ${resolvedAddress} (verified).`, {
                 success: true,
                 address: resolvedAddress,
@@ -350,7 +365,7 @@ async function executeWriteMemory(rawArgs, ctx) {
         finally {
             if (paused) {
                 try {
-                    const resumeResult = await ctx.client.resume();
+                    const resumeResult = await ctx.client.resume(pinnedFacade);
                     if (!resumeResult.success) {
                         ctx.logger.warn("C64 resume reported failure after write", {
                             details: normaliseFailure(resumeResult.details),
@@ -685,7 +700,7 @@ export { disassembleArgsSchema, copyMemoryArgsSchema, fillMemoryArgsSchema, sear
 export const memoryModule = defineToolModule({
     domain: "memory",
     summary: "Screen, main memory, and low-level inspection utilities.",
-    supportedPlatforms: ["c64u", "vice"],
+    supportedPlatforms: ["c64u", "u2", "vice"],
     resources: [
         "c64://guide/bootstrap",
         "c64://basic/spec",

package/dist/tools/meta/artifacts.js

@@ -1,8 +1,8 @@
 import { objectSchema, stringSchema, arraySchema, numberSchema, optionalSchema, booleanSchema } from "../schema.js";
 import { jsonResult } from "../responses.js";
-import { ToolError, toolErrorResult, unknownErrorResult } from "../errors.js";
+import { ToolError, ToolValidationError, toolErrorResult, unknownErrorResult } from "../errors.js";
 import { promises as fs } from "node:fs";
-import { resolve as resolvePath, join as joinPath } from "node:path";
+import { resolve as resolvePath, join as joinPath, relative, sep, isAbsolute } from "node:path";
 const bundleRunArtifactsArgsSchema = objectSchema({
     description: "Gather screen capture, memory snapshot, and debugreg into a structured bundle.",
     properties: {
@@ -41,29 +41,32 @@ export const tools = [
             try {
                 const parsed = bundleRunArtifactsArgsSchema.parse(args ?? {});
                 const runId = parsed.runId;
+                if (!/^[A-Za-z0-9][A-Za-z0-9._-]*$/.test(runId) || runId === "." || runId === "..") {
+                    throw new ToolValidationError("runId must be a non-empty safe filename (letters, digits, dot, underscore, and dash only).", { path: "$.runId" });
+                }
                 const outputPath = resolvePath(String(parsed.outputPath));
                 const captureScreen = parsed.captureScreen !== false;
                 const captureDebugReg = parsed.captureDebugReg !== false;
                 const memoryRanges = (parsed.memoryRanges ?? []);
                 await fs.mkdir(outputPath, { recursive: true });
-                const runPath = resolvePath(joinPath(outputPath, runId));
+                const runPath = containedPath(outputPath, runId);
                 await fs.mkdir(runPath, { recursive: true });
                 const artifacts = {};
                 // Capture screen
                 if (captureScreen) {
                     const screen = await ctx.client.readScreen();
-                    const screenPath = resolvePath(joinPath(runPath, "screen.txt"));
+                    const screenPath = containedPath(runPath, "screen.txt");
                     await fs.writeFile(screenPath, screen, "utf8");
                     artifacts.screen = screenPath;
                 }
                 // Capture memory ranges
                 if (memoryRanges.length > 0) {
-                    const memoryPath = resolvePath(joinPath(runPath, "memory"));
+                    const memoryPath = containedPath(runPath, "memory");
                     await fs.mkdir(memoryPath, { recursive: true });
                     for (let i = 0; i < memoryRanges.length; i++) {
                         const range = memoryRanges[i];
                         const result = await ctx.client.readMemory(range.address, String(range.length));
-                        const rangePath = resolvePath(joinPath(memoryPath, `range_${i}_${range.address}.hex`));
+                        const rangePath = containedPath(memoryPath, `range_${i}.hex`);
                         await fs.writeFile(rangePath, result.data ?? "", "utf8");
                         artifacts[`memory_range_${i}`] = rangePath;
                     }
@@ -71,12 +74,12 @@ export const tools = [
                 // Capture debugreg
                 if (captureDebugReg) {
                     const debugreg = await ctx.client.debugregRead();
-                    const debugPath = resolvePath(joinPath(runPath, "debugreg.json"));
+                    const debugPath = containedPath(runPath, "debugreg.json");
                     await fs.writeFile(debugPath, JSON.stringify(debugreg, null, 2), "utf8");
                     artifacts.debugreg = debugPath;
                 }
                 // Write manifest
-                const manifestPath = resolvePath(joinPath(runPath, "manifest.json"));
+                const manifestPath = containedPath(runPath, "manifest.json");
                 const manifest = {
                     runId,
                     createdAt: new Date().toISOString(),
@@ -93,3 +96,12 @@ export const tools = [
         },
     },
 ];
+function containedPath(base, name) {
+    if (!name || isAbsolute(name) || name.includes("/") || name.includes("\\"))
+        throw new ToolValidationError("Unsafe artifact filename.");
+    const candidate = resolvePath(joinPath(base, name));
+    const rel = relative(base, candidate);
+    if (rel === "" || rel === ".." || rel.startsWith(`..${sep}`) || isAbsolute(rel))
+        throw new ToolValidationError("Artifact path escapes its output directory.");
+    return candidate;
+}

package/dist/tools/meta/background.js

@@ -86,6 +86,13 @@ async function ensureTasksLoaded() {
         if (parsed && Array.isArray(parsed.tasks)) {
             for (const pt of parsed.tasks) {
                 const t = fromPersistedTask(pt);
+                if (t.status === "running") {
+                    t.status = "stopped";
+                    t.stoppedAt = new Date();
+                    t.updatedAt = new Date();
+                    t.lastError = "Interrupted by MCP server restart; start the task again to resume monitoring.";
+                    t.nextRunAt = null;
+                }
                 TASKS.set(t.name, t);
             }
         }
@@ -184,7 +191,10 @@ function scheduleNextRun(task, ctx) {
         if (task.status !== "running")
             return;
         try {
-            await runOperation(task.operation, task.args, ctx);
+            const result = await runOperation(task.operation, task.args, ctx);
+            if (result && typeof result === "object" && "success" in result && result.success === false) {
+                throw new Error(`Operation returned failure: ${JSON.stringify(result.details ?? result)}`);
+            }
             task.iterations += 1;
             task.updatedAt = new Date();
             if (task.maxIterations && task.iterations >= task.maxIterations) {

package/dist/tools/meta/index.js

@@ -30,7 +30,7 @@ export const metaModule = defineToolModule({
     summary: "High-level meta tools that orchestrate multiple MCP actions.",
     resources: ["c64://guide/bootstrap", "c64://assembly/6510-spec"],
     defaultTags: ["meta", "orchestration", "experimental"],
-    supportedPlatforms: ["c64u", "vice"],
+    supportedPlatforms: ["c64u", "u2", "vice"],
     workflowHints: [
         "Use meta tools to reduce round-trips by composing several steps into one.",
     ],