c64bridge 1.0.7 → 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) {

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/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

@@ -20,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,
@@ -70,16 +80,44 @@ const configGetArgsSchema = objectSchema({
     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 ?? "$";
@@ -88,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,
@@ -265,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.",
@@ -305,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: [
@@ -316,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,
                     });
@@ -341,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: [
@@ -352,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,
                     });
@@ -377,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: [
@@ -388,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,
                     });

package/dist/tools/errors.js

@@ -22,14 +22,39 @@ export class ToolExecutionError extends ToolError {
         super(message, "execution", options);
     }
 }
+function joinBackends(backends) {
+    return backends.join(" or ");
+}
+export function describeUnsupportedPlatform(subject, platform, supported, configured) {
+    const base = supported.length > 0
+        ? `${subject} requires backend ${joinBackends(supported)} (active: ${platform}).`
+        : `${subject} is not available on backend ${platform}.`;
+    if (supported.length === 0) {
+        return base;
+    }
+    if (configured === undefined) {
+        return base;
+    }
+    const switchable = supported.filter((id) => id !== platform && configured.includes(id));
+    if (switchable.length > 0) {
+        return `${base} Use \`c64_select_backend\` to switch to ${joinBackends(switchable)}.`;
+    }
+    return `${base} None of these backends is configured on this server.`;
+}
 export class ToolUnsupportedPlatformError extends ToolExecutionError {
-    constructor(tool, platform, supported) {
-        super(`Tool ${tool} is not available on platform ${platform}`, {
+    constructor(tool, platform, supported, options) {
+        const subject = options?.toolName
+            ? options.op
+                ? `\`${options.toolName}\` op \`${options.op}\``
+                : `\`${options.toolName}\``
+            : tool;
+        super(describeUnsupportedPlatform(subject, platform, supported, options?.configured), {
             code: "unsupported_platform",
             details: {
                 tool,
                 platform,
                 supported,
+                ...(options?.configured ? { configured: options.configured } : {}),
             },
         });
         this.tool = tool;
@@ -48,7 +73,9 @@ export function toolErrorResult(error) {
     // Clients often show only the text content, so surface the underlying cause
     // (for example a range check or firmware error string) next to the summary.
     const detailMessage = describeDetailMessage(error.details);
-    const message = detailMessage && !located.includes(detailMessage) ? `${located}: ${detailMessage}` : located;
+    const withDetail = detailMessage && !located.includes(detailMessage) ? `${located}: ${detailMessage}` : located;
+    const limits = describeLimits(error.details);
+    const message = limits ? `${withDetail} [${limits}]` : withDetail;
     const base = textResult(message, { error: metadata });
     return { ...base, isError: true };
 }
@@ -59,6 +86,30 @@ function describeDetailMessage(details) {
     const message = details.message;
     return typeof message === "string" && message.trim().length > 0 ? message.trim() : undefined;
 }
+const MAX_LISTED_VALUES = 40;
+// Valid values and bounds recorded by validators, so a client sees them without reading the schema.
+function describeLimits(details) {
+    if (!details || typeof details !== "object") {
+        return undefined;
+    }
+    const record = details;
+    const parts = [];
+    if (Array.isArray(record.allowed) && record.allowed.length > 0) {
+        const values = record.allowed.map((value) => String(value));
+        const shown = values.slice(0, MAX_LISTED_VALUES).join(", ");
+        parts.push(values.length > MAX_LISTED_VALUES ? `allowed: ${shown}, ... (${values.length} total)` : `allowed: ${shown}`);
+    }
+    for (const key of ["minimum", "maximum", "minLength", "maxLength", "minItems", "maxItems"]) {
+        const value = record[key];
+        if (typeof value === "number" || typeof value === "string") {
+            parts.push(`${key}: ${value}`);
+        }
+    }
+    if (parts.length > 0 && record.received !== undefined && typeof record.received !== "object") {
+        parts.push(`received: ${JSON.stringify(record.received)}`);
+    }
+    return parts.length > 0 ? parts.join("; ") : undefined;
+}
 export function unknownErrorResult(error) {
     if (error instanceof ToolError) {
         return toolErrorResult(error);

package/dist/tools/input.js

@@ -69,10 +69,26 @@ const PETSCII_TOKENS = {
 // ASCII a-z are shifted graphics characters in PETSCII, so typed "print" would
 // reach BASIC as graphics and give ?SYNTAX ERROR. Literal letters are therefore
 // sent as the unshifted PETSCII letters $41-$5A; {tokens} keep their codes.
+// Newline is RETURN. Any other character without a PETSCII equivalent, and any
+// unknown {TOKEN}, is rejected instead of being typed as something else.
+function describeChar(char) {
+    const codePoint = char.codePointAt(0) ?? 0;
+    return `'${codePoint < 0x20 ? "" : char}' (U+${codePoint.toString(16).toUpperCase().padStart(4, "0")})`;
+}
 function expandPetsciiTokens(text) {
-    return text.replace(/\{([^}]+)\}|[a-z]/g, (_match, token) => {
+    return text.replace(/\{([^}]+)\}|\r\n|[\s\S]/gu, (match, token, offset) => {
         if (token === undefined) {
-            return _match.toUpperCase();
+            if (match === "\n" || match === "\r" || match === "\r\n") {
+                return String.fromCharCode(13);
+            }
+            const code = match.codePointAt(0) ?? 0;
+            if (code >= 0x61 && code <= 0x7a) {
+                return match.toUpperCase();
+            }
+            if (code >= 0x20 && code <= 0x7e) {
+                return match;
+            }
+            throw new ToolValidationError(`Character ${describeChar(match)} at position ${offset + 1} of the text has no PETSCII mapping. Use printable ASCII, \\n for RETURN, or a {TOKEN}.`, { path: "$.text" });
         }
         const upper = token.trim().toUpperCase();
         const code = PETSCII_TOKENS[upper];
@@ -90,7 +106,7 @@ function expandPetsciiTokens(text) {
         if (!isNaN(num) && num >= 0 && num <= 255) {
             return String.fromCharCode(num);
         }
-        return _match.toUpperCase(); // type unrecognised tokens literally
+        throw new ToolValidationError(`Unknown token {${token}} at position ${offset + 1} of the text. Valid tokens: ${Object.keys(PETSCII_TOKENS).map((name) => `{${name}}`).join(", ")}, or a numeric code such as {$1D} or {29} (0-255).`, { path: "$.text" });
     });
 }
 // ---------------------------------------------------------------------------
@@ -131,7 +147,7 @@ export const writeTextArgsSchema = objectSchema({
     properties: {
         op: literalSchema("write_text"),
         text: stringSchema({
-            description: "Text to type. Use {RETURN}, {CLR}, {F1}…{F8}, {UP/DOWN/LEFT/RIGHT}, colour names, etc.",
+            description: "Text to type: printable ASCII (letters are sent as PETSCII upper case), \\n for RETURN, and {TOKEN}s such as {RETURN}, {CLR}, {F1}…{F8}, {UP}, {DOWN}, {LEFT}, {RIGHT}, colour names, or {$1D}/{29} codes. Characters with no PETSCII mapping and unknown tokens are rejected.",
             minLength: 1,
             maxLength: 512,
         }),
@@ -147,7 +163,7 @@ export const writeTextArgsSchema = objectSchema({
     additionalProperties: false,
 });
 export const keyArgsSchema = objectSchema({
-    description: "Tap a single key or hold it for a duration.",
+    description: "Press a single key one or more times, optionally with a delay between presses.",
     properties: {
         op: literalSchema("key"),
         key: stringSchema({
@@ -270,7 +286,7 @@ const inputOperationHandlers = {
             const keyByte = tokenCode !== undefined
                 ? tokenCode
                 : parsed.key.length === 1
-                    ? parsed.key.toUpperCase().charCodeAt(0) & 0xff
+                    ? expandPetsciiTokens(parsed.key).charCodeAt(0)
                     : (() => {
                         throw new ToolValidationError(`Unrecognised key: ${parsed.key}. Use a single character or a PETSCII token name.`, { path: "$.key" });
                     })();
@@ -417,6 +433,7 @@ export const inputModule = defineToolModule({
                 ],
             }),
             operationPlatforms: { joystick: ["c64u", "vice"], keyboard: ["c64u"], release_all: ["c64u"], state: ["c64u"] },
+            operationEffects: { write_text: "write", key: "write", keyboard: "write", joystick: "write", release_all: "write", state: "read" },
             tags: ["input", "keyboard", "joystick"],
             examples: [
                 {