c64bridge 1.0.6 → 1.1.0

package/dist/numericArg.js

@@ -0,0 +1,55 @@
+/*
+C64 Bridge - An MCP Server for the Commodore 64 Ultimate
+Copyright (C) 2025 Christian Gleissner
+
+Licensed under the GNU General Public License v2.0 or later.
+See <https://www.gnu.org/licenses/> for details.
+*/
+import { ToolValidationError } from "./tools/errors.js";
+/**
+ * Shared parser for memory address and length arguments.
+ *
+ * Accepted forms: `$C000`, `0xC000`, `%1010`, and decimal. Returns undefined
+ * when the text is not a numeric literal at all, so the caller can try a symbol
+ * name next. A decimal with a leading zero (`0400`) is rejected as ambiguous,
+ * because it was previously read as decimal 400 although it looks like hex.
+ */
+export function parseNumericLiteral(raw, path) {
+    const text = raw.trim();
+    if (/^\$[0-9a-f]+$/i.test(text))
+        return Number.parseInt(text.slice(1), 16);
+    if (/^0x[0-9a-f]+$/i.test(text))
+        return Number.parseInt(text.slice(2), 16);
+    if (/^%[01]+$/.test(text))
+        return Number.parseInt(text.slice(1), 2);
+    if (/^[0-9]+$/.test(text)) {
+        if (text.length > 1 && text.startsWith("0")) {
+            throw new ToolValidationError(`Ambiguous number "${text}": a decimal with a leading zero could also be hexadecimal. Write "$${text}" for hex or "${Number.parseInt(text, 10)}" for decimal.`, { path });
+        }
+        return Number.parseInt(text, 10);
+    }
+    return undefined;
+}
+/**
+ * Throws for a bare string of hex digits that contains A-F (`C000`), which
+ * would otherwise be reported as an unknown symbol or an unparsable number.
+ * Call it after symbol lookup so names that happen to be hex digits still work.
+ */
+export function assertNotBareHex(raw, path) {
+    const text = raw.trim();
+    if (/^[0-9a-f]*[a-f][0-9a-f]*$/i.test(text)) {
+        throw new ToolValidationError(`Ambiguous value "${text}": hexadecimal needs a prefix. Write "$${text.toUpperCase()}" or "0x${text.toUpperCase()}".`, { path });
+    }
+}
+export function formatAddressForMessage(value) {
+    return `$${value.toString(16).toUpperCase().padStart(4, "0")}`;
+}
+/** Validates that an address (and optional length) lies within $0000-$FFFF. */
+export function assertAddressRange(address, length, path) {
+    if (!Number.isInteger(address) || address < 0 || address > 0xffff) {
+        throw new ToolValidationError("Address must be in range $0000-$FFFF", { path });
+    }
+    if (length !== undefined && address + length - 1 > 0xffff) {
+        throw new ToolValidationError(`Memory range ${formatAddressForMessage(address)} + ${length} bytes passes $FFFF`, { path });
+    }
+}

package/dist/petscii.js

@@ -63,12 +63,22 @@ function ensureScreenCodeMap() {
     }
     screenCodeMapInitialised = true;
 }
+/** Letters of the lower-case set; reverse-video codes (+128) show the same letter. */
+function lowerCaseSetChar(code) {
+    const base = code & 0x7f;
+    if (base >= 1 && base <= 26)
+        return String.fromCharCode(0x60 + base);
+    if (base >= 0x41 && base <= 0x5a)
+        return String.fromCharCode(base);
+    return undefined;
+}
 export function screenCodesToAscii(bytes, options) {
     ensureScreenCodeMap();
     const columns = options?.columns && options.columns > 0 ? options.columns : 40;
     const maxRows = options?.rows && options.rows > 0 ? options.rows : undefined;
     const trimSpaces = options?.trimTrailingSpaces !== false;
     const trimEmptyRows = options?.trimTrailingEmptyRows !== false;
+    const lowerCase = options?.charset === "lower";
     const lines = [];
     const totalCells = maxRows ? Math.min(bytes.length, columns * maxRows) : bytes.length;
     for (let index = 0; index < totalCells; index += columns) {
@@ -79,7 +89,9 @@ export function screenCodesToAscii(bytes, options) {
         let line = "";
         for (let idx = index; idx < end; idx += 1) {
             const code = bytes[idx] ?? 0;
-            const char = SCREEN_CODE_TO_ASCII.get(code & 0xff) ?? petsciiByteToChar(code & 0xff);
+            const char = lowerCase
+                ? lowerCaseSetChar(code & 0xff) ?? SCREEN_CODE_TO_ASCII.get(code & 0xff) ?? petsciiByteToChar(code & 0xff)
+                : SCREEN_CODE_TO_ASCII.get(code & 0xff) ?? petsciiByteToChar(code & 0xff);
             line += char;
         }
         if (trimSpaces) {
@@ -137,11 +149,6 @@ const NAMED_CHARS = Object.freeze({
     "leftarrow": 95,
     "pi": 222,
 });
-export function listNamedPetscii() {
-    return Object.entries(NAMED_CHARS)
-        .sort((a, b) => a[0].localeCompare(b[0]))
-        .map(([name, code]) => ({ name, code, hex: `$${code.toString(16).toUpperCase().padStart(2, "0")}` }));
-}
 export function lookupNamedPetscii(name) {
     const key = name.trim().toLowerCase().replace(/\s+/g, "_");
     // Own keys only, so names like "constructor" don't resolve to Object.prototype members.

package/dist/platform.js

@@ -51,15 +51,21 @@ export function isPlatformSupported(platform, supported) {
 }
 export function describePlatformCapabilities(tools) {
     const map = {
-        c64u: { available: [], unsupported: [] },
-        u2: { available: [], unsupported: [] },
-        vice: { available: [], unsupported: [] },
+        c64u: { available: [], unsupported: [], unsupportedOperations: [] },
+        u2: { available: [], unsupported: [], unsupportedOperations: [] },
+        vice: { available: [], unsupported: [], unsupportedOperations: [] },
     };
     for (const tool of tools) {
         const supported = tool.metadata.platforms ?? ["c64u"];
         for (const id of ["c64u", "u2", "vice"]) {
             if (supported.includes(id)) {
                 map[id].available.push(tool.name);
+                // Operations of an available tool that this backend does not provide.
+                for (const [op, platforms] of Object.entries(tool.metadata.operationPlatforms ?? {})) {
+                    if (platforms.length > 0 && !platforms.includes(id)) {
+                        map[id].unsupportedOperations.push(`${tool.name}.${op}`);
+                    }
+                }
             }
             else {
                 map[id].unsupported.push(tool.name);
@@ -73,18 +79,21 @@ export function describePlatformCapabilities(tools) {
                 limited_features: PLATFORM_FEATURES.c64u.limited,
                 tools: map.c64u.available.sort(),
                 unsupported_tools: map.c64u.unsupported.sort(),
+                unsupported_operations: map.c64u.unsupportedOperations.sort(),
             },
             u2: {
                 features: PLATFORM_FEATURES.u2.features,
                 limited_features: PLATFORM_FEATURES.u2.limited,
                 tools: map.u2.available.sort(),
                 unsupported_tools: map.u2.unsupported.sort(),
+                unsupported_operations: map.u2.unsupportedOperations.sort(),
             },
             vice: {
                 features: PLATFORM_FEATURES.vice.features,
                 limited_features: PLATFORM_FEATURES.vice.limited,
                 tools: map.vice.available.sort(),
                 unsupported_tools: map.vice.unsupported.sort(),
+                unsupported_operations: map.vice.unsupportedOperations.sort(),
             },
         },
     };

package/dist/prompts/registry.js

@@ -1,6 +1,7 @@
 import { listKnowledgeResources } from "../rag/knowledgeIndex.js";
 import { RESOURCE_URIS } from "../rag/resourceUris.js";
 import { toolRegistry } from "../tools/registry/index.js";
+import { ToolValidationError } from "../tools/errors.js";
 const ASSEMBLY_HARDWARE_NOTES = {
     sid: [
         "When routing this request, keep SID register usage, voice allocation, and timing side effects in scope.",
@@ -354,7 +355,11 @@ export function createPromptRegistry() {
         resolve(name, args) {
             const definition = definitionByName.get(name);
             if (!definition) {
-                throw new Error(`Unknown prompt: ${name}`);
+                const allowed = Array.from(definitionByName.keys()).sort();
+                throw new ToolValidationError(`Unknown prompt: ${name}. Valid prompts: ${allowed.join(", ")}`, {
+                    path: "$.name",
+                    details: { allowed, received: name },
+                });
             }
             const rawArgs = args ?? {};
             const prepared = definition.prepareArgs ? definition.prepareArgs(rawArgs) : {};

package/dist/redact.js

@@ -0,0 +1,166 @@
+/**
+ * Shared redaction for the Ultimate network password and other credentials.
+ *
+ * The password is meant to leave the process only as the `X-Password` request
+ * header. Every sink that can carry arbitrary values (console logging,
+ * diagnostics files, MCP tool results) passes its content through this module.
+ *
+ * Two mechanisms are combined:
+ * - values registered with `registerSecret` are replaced wherever they appear
+ *   inside a string, including error messages and stack traces;
+ * - properties whose name is a credential header are replaced regardless of value.
+ */
+const REDACTED = "***";
+const SENSITIVE_KEY = /^(x-password|authorization|proxy-authorization|cookie|set-cookie|x-api-key)$/i;
+const MIN_SECRET_LENGTH = 1;
+const secrets = new Set();
+export function registerSecret(value) {
+    if (typeof value === "string" && value.length >= MIN_SECRET_LENGTH) {
+        secrets.add(value);
+    }
+}
+/** Test hook: forget all registered secrets. */
+export function clearRegisteredSecrets() {
+    secrets.clear();
+}
+export function isSensitiveKey(key) {
+    return SENSITIVE_KEY.test(key);
+}
+export function redactText(text) {
+    let result = text;
+    // Longest first, so a secret that contains another one is replaced as a whole.
+    for (const secret of [...secrets].sort((a, b) => b.length - a.length)) {
+        if (result.includes(secret)) {
+            result = result.split(secret).join(REDACTED);
+        }
+    }
+    return result;
+}
+function isPlainObject(value) {
+    const proto = Object.getPrototypeOf(value);
+    return proto === Object.prototype || proto === null;
+}
+/**
+ * Returns a copy of `value` that is safe to log, persist or return to a client.
+ * Errors (including Axios errors) are reduced to name, message, stack, code and
+ * HTTP status, so their request configuration is never copied.
+ */
+export function redactValue(value, seen = new WeakSet()) {
+    if (typeof value === "string") {
+        return redactText(value);
+    }
+    if (value === null || typeof value !== "object") {
+        return value;
+    }
+    if (seen.has(value)) {
+        return "[Circular]";
+    }
+    if (value instanceof Error) {
+        seen.add(value);
+        const extra = value;
+        return {
+            name: value.name,
+            message: redactText(value.message),
+            ...(value.stack ? { stack: redactText(value.stack) } : {}),
+            ...(extra.code !== undefined ? { code: redactValue(extra.code, seen) } : {}),
+            ...(extra.response?.status !== undefined ? { status: extra.response.status } : {}),
+            ...(extra.cause !== undefined ? { cause: redactValue(extra.cause, seen) } : {}),
+        };
+    }
+    if (Array.isArray(value)) {
+        seen.add(value);
+        return value.map((entry) => redactValue(entry, seen));
+    }
+    if (!isPlainObject(value)) {
+        return value;
+    }
+    seen.add(value);
+    return Object.fromEntries(Object.entries(value).map(([key, entry]) => [
+        redactText(key),
+        isSensitiveKey(key) ? REDACTED : redactValue(entry, seen),
+    ]));
+}
+function scrubHeaders(headers) {
+    if (!headers || typeof headers !== "object")
+        return;
+    for (const key of Object.keys(headers)) {
+        if (isSensitiveKey(key)) {
+            headers[key] = REDACTED;
+        }
+    }
+}
+function scrubRequestHolder(holder) {
+    if (!holder || typeof holder !== "object")
+        return;
+    const target = holder;
+    scrubHeaders(target.config?.headers);
+    // The raw ClientRequest keeps the serialized header block, including X-Password.
+    if (target.request !== undefined) {
+        target.request = undefined;
+    }
+}
+/**
+ * Removes credentials from a rejected Axios error in place and returns it, so
+ * callers that inspect, log or serialize the error cannot expose them.
+ * Status, code, message and response data stay available.
+ */
+export function scrubRequestError(error) {
+    if (!error || typeof error !== "object")
+        return error;
+    scrubRequestHolder(error);
+    const response = error.response;
+    scrubRequestHolder(response);
+    // A device that echoes the rejected password in its error body.
+    if (response && typeof response.data === "string") {
+        response.data = redactText(response.data);
+    }
+    return error;
+}
+/**
+ * Firmware configuration items that hold credentials. The Ultimate config API
+ * lists items by display name (for example "Network Password" in the
+ * "Network settings" category), so matching is by item name: passwords,
+ * passphrases and pre-shared keys, plus a bare "key" item in a Wi-Fi category.
+ */
+const SENSITIVE_CONFIG_ITEM = /pass(word|wd|phrase|code)?\b|\bpsk\b|secret/i;
+const WIFI_CATEGORY = /wi-?fi|wlan|wireless/i;
+const BARE_KEY_ITEM = /^(wifi |wlan )?(key|wpa key|network key)$/i;
+export function isSensitiveConfigItem(category, item) {
+    if (!item)
+        return false;
+    if (SENSITIVE_CONFIG_ITEM.test(item))
+        return true;
+    return BARE_KEY_ITEM.test(item.trim()) && (item.toLowerCase().includes("wifi") || WIFI_CATEGORY.test(category ?? ""));
+}
+/**
+ * Returns a copy of a firmware configuration response in which the value of
+ * every credential item is replaced with `***`. Item names stay, so a client can
+ * see that the item exists. `category` and `item` describe the request: when an
+ * item was requested and the response is its bare value, the value is replaced.
+ */
+export function redactConfigValue(value, category, item) {
+    if (item && isSensitiveConfigItem(category, item)) {
+        return value !== null && typeof value === "object" ? redactConfigTree(value, category) : REDACTED;
+    }
+    return redactConfigTree(value, category);
+}
+function redactConfigTree(value, category) {
+    if (Array.isArray(value)) {
+        return value.map((entry) => redactConfigTree(entry, category));
+    }
+    if (value === null || typeof value !== "object") {
+        return value;
+    }
+    const out = {};
+    for (const [key, entry] of Object.entries(value)) {
+        if (isSensitiveConfigItem(category, key) && entry !== null && entry !== undefined) {
+            out[key] = REDACTED;
+        }
+        else {
+            // Keys at the top level of a response are category names.
+            out[key] = redactConfigTree(entry, entry !== null && typeof entry === "object" && !Array.isArray(entry) ? key : category);
+        }
+    }
+    return out;
+}
+export const REDACTED_PLACEHOLDER = REDACTED;

package/dist/tools/access.js

@@ -0,0 +1,66 @@
+import { ToolValidationError } from "./errors.js";
+export const ACCESS_ENV_VAR = "C64BRIDGE_ACCESS";
+const ACCESS_MODES = ["full", "no-destructive", "read-only"];
+const warnedValues = new Set();
+/**
+ * Reads the access mode from the environment at call time. An unset or empty variable means
+ * "full". An unknown value fails closed to "read-only" and logs a warning once per value.
+ */
+export function getAccessMode(env = process.env) {
+    const raw = env[ACCESS_ENV_VAR];
+    if (raw === undefined || raw.trim() === "") {
+        return "full";
+    }
+    const value = raw.trim().toLowerCase();
+    if (ACCESS_MODES.includes(value)) {
+        return value;
+    }
+    if (!warnedValues.has(value)) {
+        warnedValues.add(value);
+        process.stderr.write(`[c64bridge] Unknown ${ACCESS_ENV_VAR} value "${raw}"; using "read-only". Valid values: ${ACCESS_MODES.join(", ")}.\n`);
+    }
+    return "read-only";
+}
+export function isEffectAllowed(mode, effect) {
+    switch (mode) {
+        case "full":
+            return true;
+        case "no-destructive":
+            return effect !== "destructive";
+        default:
+            return effect === "read";
+    }
+}
+/** Throws a validation error when the active access mode does not allow the effect. */
+export function assertAccess(toolName, op, effect) {
+    const mode = getAccessMode();
+    if (isEffectAllowed(mode, effect)) {
+        return;
+    }
+    const subject = op ? `${toolName} operation "${op}"` : toolName;
+    throw new ToolValidationError(`${subject} is blocked: it has effect "${effect}" and the access mode is "${mode}" (${ACCESS_ENV_VAR}=${mode}). `
+        + `${mode === "read-only" ? "Only read operations are allowed." : "Destructive operations are not allowed."}`, {
+        path: "$.op",
+        details: { tool: toolName, op: op ?? null, effect, accessMode: mode, variable: ACCESS_ENV_VAR },
+    });
+}
+/** Effect of a background task operation (read, write, read_screen, menu_button and the *_memory aliases). */
+export function taskOperationEffect(operation) {
+    switch (operation) {
+        case "read":
+        case "read_memory":
+        case "read_screen":
+            return "read";
+        default:
+            // write, write_memory, menu_button and unknown names (rejected later by validation).
+            return "write";
+    }
+}
+export function annotationsForEffects(effects) {
+    return {
+        readOnlyHint: effects.length > 0 && effects.every((effect) => effect === "read"),
+        destructiveHint: effects.includes("destructive"),
+        idempotentHint: false,
+        openWorldHint: false,
+    };
+}

package/dist/tools/debug.js

@@ -494,6 +494,12 @@ export const debugModuleGroup = defineToolModule({
                 description: "Available debugger operations.",
                 variants: debugOperationSchemas.map((schema) => schema.jsonSchema),
             }),
+            operationEffects: {
+                list_checkpoints: "read", get_checkpoint: "read", create_checkpoint: "write", delete_checkpoint: "write",
+                toggle_checkpoint: "write", set_condition: "write", list_registers: "read", get_registers: "read",
+                set_registers: "write", step: "write", step_return: "write", get_monitor_state: "read",
+                wait_for_state: "read", nuclear_reset: "write", continue_execution: "write",
+            },
             tags: ["debug", "breakpoint", "registers", "grouped"],
             examples: [
                 {

package/dist/tools/developer.js

@@ -1,6 +1,7 @@
 import { defineToolModule } from "./types.js";
-import { objectSchema, optionalSchema, stringSchema, } from "./schema.js";
+import { booleanSchema, objectSchema, optionalSchema, stringSchema, } from "./schema.js";
 import { jsonResult, textResult } from "./responses.js";
+import { redactConfigValue } from "../redact.js";
 import { ToolError, ToolExecutionError, ToolValidationError, toolErrorResult, unknownErrorResult, } from "./errors.js";
 function toRecord(details) {
     if (details === undefined || details === null) {
@@ -19,6 +20,16 @@ const noArgsSchema = objectSchema({
     properties: {},
     additionalProperties: false,
 });
+const flashCategoryArgsSchema = objectSchema({
+    description: "Optional configuration category; omit to apply to the whole device configuration.",
+    properties: {
+        category: optionalSchema(stringSchema({
+            description: "Configuration category name (e.g. 'Audio Mixer'). Omit to act on every category.",
+            minLength: 1,
+        })),
+    },
+    additionalProperties: false,
+});
 const categorySchema = stringSchema({
     description: "Configuration category reported by the Ultimate firmware (e.g. 'Audio').",
     minLength: 1,
@@ -61,20 +72,52 @@ const configGetArgsSchema = objectSchema({
     properties: {
         category: categorySchema,
         item: itemSchema,
+        includeSecretValues: optionalSchema(booleanSchema({
+            description: "Return credential values (network password, FTP/Telnet passwords, Wi-Fi keys) in plain text. Default false: those values are replaced with ***.",
+            default: false,
+        }), false),
     },
     required: ["category"],
     additionalProperties: false,
 });
+const BATCH_CATEGORY_SCHEMA = {
+    type: "object",
+    description: "Item/value pairs of one category (primitive values only).",
+    additionalProperties: {
+        type: ["string", "number", "boolean"],
+    },
+};
+function isCategoryMap(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value)
+        && Object.values(value).every((entry) => typeof entry === "object" && entry !== null && !Array.isArray(entry));
+}
+function parseCategoryMap(input, resolvedPath, into) {
+    for (const [category, items] of Object.entries(input)) {
+        if (typeof items !== "object" || items === null || Array.isArray(items)) {
+            throw new ToolValidationError("Each category must map to an object of item values", {
+                path: `${resolvedPath}.${category}`,
+            });
+        }
+        const parsedItems = into[category] ?? {};
+        for (const [item, rawValue] of Object.entries(items)) {
+            parsedItems[item] = primitiveValueSchema.parse(rawValue, `${resolvedPath}.${category}.${item}`);
+        }
+        into[category] = parsedItems;
+    }
+}
 const configBatchSchema = {
     jsonSchema: {
-        description: "Nested object mapping categories to item/value pairs (primitive values only).",
+        description: "Apply configuration changes. Documented form: `updates`, an object mapping categories to item/value pairs. "
+            + "For backward compatibility the runtime also accepts the categories as top-level keys next to `op`.",
         type: "object",
-        additionalProperties: {
-            type: "object",
-            additionalProperties: {
-                type: ["string", "number", "boolean"],
+        properties: {
+            updates: {
+                type: "object",
+                description: "Categories mapped to item/value pairs (primitive values only), for example {\"Audio\": {\"Volume\": 80}}.",
+                additionalProperties: BATCH_CATEGORY_SCHEMA,
             },
         },
+        additionalProperties: BATCH_CATEGORY_SCHEMA,
     },
     parse(value, path) {
         const resolvedPath = path ?? "$";
@@ -83,21 +126,16 @@ const configBatchSchema = {
                 path: resolvedPath,
             });
         }
-        const input = value;
+        const input = { ...value };
         const categories = {};
-        for (const [category, items] of Object.entries(input)) {
-            if (typeof items !== "object" || items === null || Array.isArray(items)) {
-                throw new ToolValidationError("Each category must map to an object of item values", {
-                    path: `${resolvedPath}.${category}`,
-                });
-            }
-            const parsedItems = {};
-            for (const [item, rawValue] of Object.entries(items)) {
-                const parsedValue = primitiveValueSchema.parse(rawValue, `${resolvedPath}.${category}.${item}`);
-                parsedItems[item] = parsedValue;
-            }
-            categories[category] = parsedItems;
+        // `updates` is the documented form. A legacy category literally named "updates"
+        // holds primitive values, so it is not a category map and stays a legacy category.
+        if (Object.prototype.hasOwnProperty.call(input, "updates") && isCategoryMap(input.updates)) {
+            const updates = input.updates;
+            delete input.updates;
+            parseCategoryMap(updates, `${resolvedPath}.updates`, categories);
         }
+        parseCategoryMap(input, resolvedPath, categories);
         if (Object.keys(categories).length === 0) {
             throw new ToolValidationError("Batch payload must contain at least one category", {
                 path: resolvedPath,
@@ -190,7 +228,10 @@ export const developerModule = defineToolModule({
                         category: parsed.category,
                         item: parsed.item ?? null,
                     });
-                    const details = await ctx.client.configGet(parsed.category, parsed.item);
+                    const raw = await ctx.client.configGet(parsed.category, parsed.item);
+                    const details = parsed.includeSecretValues === true
+                        ? raw
+                        : redactConfigValue(raw, parsed.category, parsed.item);
                     return withStructuredJson({ value: details }, {
                         success: true,
                         category: parsed.category,
@@ -257,7 +298,7 @@ export const developerModule = defineToolModule({
             relatedResources: ["c64://guide/bootstrap"],
             tags: ["config", "write"],
             examples: [
-                { name: "Batch update", description: "Update multiple settings", arguments: { Audio: { Volume: 80, DACMode: "stereo" } } },
+                { name: "Batch update", description: "Update multiple settings", arguments: { updates: { Audio: { Volume: 80, DACMode: "stereo" } } } },
             ],
             workflowHints: [
                 "Use when multiple categories must be updated together; remind the user to review validation errors closely.",
@@ -297,7 +338,7 @@ export const developerModule = defineToolModule({
             name: "config_load_from_flash",
             description: "Load configuration settings from flash storage.",
             summary: "Restores the firmware configuration by reading the persisted flash snapshot.",
-            inputSchema: noArgsSchema.jsonSchema,
+            inputSchema: flashCategoryArgsSchema.jsonSchema,
             relatedResources: ["c64://guide/bootstrap"],
             tags: ["config", "flash"],
             examples: [
@@ -308,15 +349,15 @@ export const developerModule = defineToolModule({
             ],
             async execute(args, ctx) {
                 try {
-                    noArgsSchema.parse(args ?? {});
-                    ctx.logger.info("Loading configuration from flash");
-                    const result = await ctx.client.configLoadFromFlash();
+                    const { category } = flashCategoryArgsSchema.parse(args ?? {});
+                    ctx.logger.info("Loading configuration from flash", { category });
+                    const result = await ctx.client.configLoadFromFlash(category);
                     if (!result.success) {
                         throw new ToolExecutionError("C64 backend reported failure while loading from flash", {
                             details: toRecord(result.details),
                         });
                     }
-                    return textResult("Configuration loaded from flash.", {
+                    return textResult(`Configuration${category ? ` category ${category}` : ""} loaded from flash.`, {
                         success: true,
                         details: toRecord(result.details) ?? null,
                     });
@@ -333,7 +374,7 @@ export const developerModule = defineToolModule({
             name: "config_save_to_flash",
             description: "Persist current configuration settings to flash storage.",
             summary: "Saves the active configuration snapshot so it survives power cycles.",
-            inputSchema: noArgsSchema.jsonSchema,
+            inputSchema: flashCategoryArgsSchema.jsonSchema,
             relatedResources: ["c64://guide/bootstrap"],
             tags: ["config", "flash"],
             examples: [
@@ -344,15 +385,15 @@ export const developerModule = defineToolModule({
             ],
             async execute(args, ctx) {
                 try {
-                    noArgsSchema.parse(args ?? {});
-                    ctx.logger.info("Saving configuration to flash");
-                    const result = await ctx.client.configSaveToFlash();
+                    const { category } = flashCategoryArgsSchema.parse(args ?? {});
+                    ctx.logger.info("Saving configuration to flash", { category });
+                    const result = await ctx.client.configSaveToFlash(category);
                     if (!result.success) {
                         throw new ToolExecutionError("C64 backend reported failure while saving to flash", {
                             details: toRecord(result.details),
                         });
                     }
-                    return textResult("Configuration saved to flash.", {
+                    return textResult(`Configuration${category ? ` category ${category}` : ""} saved to flash.`, {
                         success: true,
                         details: toRecord(result.details) ?? null,
                     });
@@ -369,7 +410,7 @@ export const developerModule = defineToolModule({
             name: "config_reset_to_default",
             description: "Reset configuration categories to their factory defaults.",
             summary: "Instructs the firmware to discard overrides and restore default configuration values.",
-            inputSchema: noArgsSchema.jsonSchema,
+            inputSchema: flashCategoryArgsSchema.jsonSchema,
             relatedResources: ["c64://guide/bootstrap"],
             tags: ["config", "reset"],
             examples: [
@@ -380,15 +421,15 @@ export const developerModule = defineToolModule({
             ],
             async execute(args, ctx) {
                 try {
-                    noArgsSchema.parse(args ?? {});
-                    ctx.logger.info("Resetting configuration to defaults");
-                    const result = await ctx.client.configResetToDefault();
+                    const { category } = flashCategoryArgsSchema.parse(args ?? {});
+                    ctx.logger.info("Resetting configuration to defaults", { category });
+                    const result = await ctx.client.configResetToDefault(category);
                     if (!result.success) {
                         throw new ToolExecutionError("C64 backend reported failure while resetting configuration", {
                             details: toRecord(result.details),
                         });
                     }
-                    return textResult("Configuration reset to defaults.", {
+                    return textResult(`Configuration${category ? ` category ${category}` : ""} reset to defaults.`, {
                         success: true,
                         details: toRecord(result.details) ?? null,
                     });