c64bridge 1.0.6 → 1.1.0

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

@@ -1,7 +1,7 @@
 import { createOperationDispatcher, defineToolModule, discriminatedUnionSchema, } from "./types.js";
 import { arraySchema, literalSchema, numberSchema, objectSchema, optionalSchema, stringSchema, } from "./schema.js";
 import { jsonResult, textResult } from "./responses.js";
-import { ToolValidationError, toolErrorResult, unknownErrorResult, } from "./errors.js";
+import { ToolExecutionError, ToolValidationError, toolErrorResult, unknownErrorResult, } from "./errors.js";
 function isMissingNativeInputEndpoint(error) {
     return typeof error === "object"
         && error !== null
@@ -9,7 +9,7 @@ function isMissingNativeInputEndpoint(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" });
+    return toolErrorResult(new ToolExecutionError(`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.`, { code: "native_input_unavailable", details: { fallback: "key_or_write_text" } }));
 }
 // ---------------------------------------------------------------------------
 // PETSCII token expansion table
@@ -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: [
                 {

package/dist/tools/machineControl.js

@@ -1,5 +1,6 @@
 import { defineToolModule } from "./types.js";
-import { objectSchema } from "./schema.js";
+import { booleanSchema, numberSchema, objectSchema, optionalSchema } from "./schema.js";
+import { waitForScreenText, MAX_WAIT_TIMEOUT_MS } from "./meta/screen.js";
 import { jsonResult, textResult } from "./responses.js";
 import { Buffer } from "node:buffer";
 import { ToolError, ToolExecutionError, toolErrorResult, unknownErrorResult, } from "./errors.js";
@@ -31,14 +32,104 @@ function isMissingMenuScreenEndpoint(error) {
         && "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.");
+function createWaitSchema(description) {
+    return objectSchema({
+        description,
+        properties: {
+            waitForReady: optionalSchema(booleanSchema({
+                description: "Wait until the BASIC READY. prompt is visible before returning. A timeout is reported as ready=false, not as an error.",
+                default: false,
+            }), false),
+            readyTimeoutMs: optionalSchema(numberSchema({
+                description: "Maximum time to wait for READY. when waitForReady is true (1-120000 ms).",
+                integer: true,
+                minimum: 1,
+                maximum: MAX_WAIT_TIMEOUT_MS,
+                default: 15000,
+            }), 15000),
+        },
+        additionalProperties: false,
+    });
+}
+const READY_SETTLE_MS = 300;
+/** After this long, a screen identical to the one before the reset counts as the new boot screen. */
+const READY_UNCHANGED_GRACE_MS = 3000;
+const SNAPSHOT_TIMEOUT_MS = 2000;
+/** Resolves to undefined when the operation does not settle within `ms`; the late result is ignored. */
+async function withinMs(operation, ms) {
+    let timer;
+    const timeout = new Promise((resolve) => { timer = setTimeout(() => resolve(undefined), Math.max(0, ms)); });
+    try {
+        return await Promise.race([operation, timeout]);
+    }
+    finally {
+        if (timer)
+            clearTimeout(timer);
+    }
+}
+/** Screen text before the reset, used to tell a stale READY. from the new one. Best effort: undefined when unreadable. */
+async function screenBeforeReset(ctx, parsed) {
+    if (parsed.waitForReady !== true)
+        return undefined;
+    try {
+        return await withinMs(ctx.client.readScreen(), SNAPSHOT_TIMEOUT_MS);
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * Polls the screen until READY. appears or the timeout elapses. Never throws.
+ * A screen identical to the one read before the reset is ignored for the first
+ * few seconds, so the READY. still visible from before the reset is not taken
+ * for the new one. Each read is bounded by the remaining time.
+ */
+async function waitForReadyPrompt(ctx, timeoutMs, before) {
+    const start = Date.now();
+    await new Promise((resolve) => setTimeout(resolve, Math.min(READY_SETTLE_MS, timeoutMs)));
+    let lastError;
+    const tolerantClient = {
+        async readScreen() {
+            const remaining = timeoutMs - (Date.now() - start);
+            try {
+                const screen = await withinMs(ctx.client.readScreen(), remaining);
+                if (screen === undefined)
+                    return "";
+                lastError = undefined;
+                if (before !== undefined && screen === before && Date.now() - start < READY_UNCHANGED_GRACE_MS)
+                    return "";
+                return screen;
+            }
+            catch (error) {
+                lastError = error instanceof Error ? error.message : String(error);
+                return ""; // device not reachable yet
+            }
+        },
+    };
+    const remaining = Math.max(1, timeoutMs - (Date.now() - start));
+    const outcome = await waitForScreenText(tolerantClient, { pattern: "READY.", timeoutMs: remaining, intervalMs: 250 });
+    return { ready: outcome.matched, readyElapsedMs: Date.now() - start, ...(outcome.matched || !lastError ? {} : { lastError }) };
+}
+async function withReadyResult(ctx, parsed, before, baseMessage, details) {
+    if (parsed.waitForReady !== true) {
+        return textResult(baseMessage, { success: true, details });
+    }
+    const { ready, readyElapsedMs, lastError } = await waitForReadyPrompt(ctx, parsed.readyTimeoutMs ?? 15000, before);
+    const message = ready
+        ? `${baseMessage} READY. prompt reached after ${readyElapsedMs} ms.`
+        : `${baseMessage} The READY. prompt was not seen within ${readyElapsedMs} ms; the machine may still be starting.`
+            + (lastError ? ` The last screen read failed: ${lastError}` : "");
+    return textResult(message, { success: true, details, ready, readyElapsedMs, ...(lastError ? { readyError: lastError } : {}) });
+}
+const resetArgsSchema = createWaitSchema("Reset the C64. Optionally wait for the READY. prompt.");
+const rebootArgsSchema = createWaitSchema("Reboot the C64 firmware. Optionally wait for the READY. prompt.");
 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 powerCycleArgsSchema = createWaitSchema("Power cycle the active system. Optionally wait for the READY. prompt.");
 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.");
+const POWER_RESTORE_NOTE = "The machine cannot be restarted by software afterwards: power must be restored at the outlet, and the machine starts by itself only if automatic startup on power restoration is enabled.";
 export const machineControlModule = defineToolModule({
     domain: "machine",
     summary: "Power, reset, pause/resume, and diagnostic controls for the C64 and Ultimate hardware.",
@@ -66,8 +157,9 @@ export const machineControlModule = defineToolModule({
             supportedPlatforms: ["c64u", "u2", "vice"],
             async execute(args, ctx) {
                 try {
-                    resetArgsSchema.parse(args ?? {});
+                    const parsed = resetArgsSchema.parse(args ?? {});
                     ctx.logger.info("Resetting C64");
+                    const before = await screenBeforeReset(ctx, parsed);
                     const result = await ctx.client.reset();
                     if (!result.success) {
                         throw new ToolExecutionError("C64 backend reported failure while resetting", {
@@ -75,10 +167,7 @@ export const machineControlModule = defineToolModule({
                         });
                     }
                     const details = toRecord(result.details) ?? {};
-                    return textResult("C64 reset command issued successfully.", {
-                        success: true,
-                        details,
-                    });
+                    return await withReadyResult(ctx, parsed, before, "C64 reset command issued successfully.", details);
                 }
                 catch (error) {
                     if (error instanceof ToolError) {
@@ -104,8 +193,9 @@ export const machineControlModule = defineToolModule({
             supportedPlatforms: ["c64u", "u2", "vice"],
             async execute(args, ctx) {
                 try {
-                    rebootArgsSchema.parse(args ?? {});
+                    const parsed = rebootArgsSchema.parse(args ?? {});
                     ctx.logger.info("Rebooting C64");
+                    const before = await screenBeforeReset(ctx, parsed);
                     const result = await ctx.client.reboot();
                     if (!result.success) {
                         throw new ToolExecutionError("C64 backend reported failure while rebooting", {
@@ -113,10 +203,7 @@ export const machineControlModule = defineToolModule({
                         });
                     }
                     const details = toRecord(result.details) ?? {};
-                    return textResult("C64 reboot command issued successfully.", {
-                        success: true,
-                        details,
-                    });
+                    return await withReadyResult(ctx, parsed, before, "C64 reboot command issued successfully.", details);
                 }
                 catch (error) {
                     if (error instanceof ToolError) {
@@ -144,7 +231,8 @@ export const machineControlModule = defineToolModule({
                 try {
                     pauseArgsSchema.parse(args ?? {});
                     ctx.logger.info("Pausing C64 execution");
-                    const result = await ctx.client.pause();
+                    // An explicit pause stays in effect until an explicit resume, even if tool calls pause and resume meanwhile.
+                    const result = ctx.client.explicitPause ? await ctx.client.explicitPause(await ctx.client.pinFacade?.()) : await ctx.client.pause();
                     if (!result.success) {
                         throw new ToolExecutionError("C64 backend reported failure while pausing", {
                             details: normaliseFailure(result.details),
@@ -182,7 +270,7 @@ export const machineControlModule = defineToolModule({
                 try {
                     resumeArgsSchema.parse(args ?? {});
                     ctx.logger.info("Resuming C64 execution");
-                    const result = await ctx.client.resume();
+                    const result = ctx.client.explicitResume ? await ctx.client.explicitResume(await ctx.client.pinFacade?.()) : await ctx.client.resume();
                     if (!result.success) {
                         throw new ToolExecutionError("C64 backend reported failure while resuming", {
                             details: normaliseFailure(result.details),
@@ -204,7 +292,7 @@ export const machineControlModule = defineToolModule({
         },
         {
             name: "poweroff",
-            description: "Power off the machine via Ultimate firmware. See safety notes in c64://guide/bootstrap.",
+            description: `Power off the machine via Ultimate firmware. See safety notes in c64://guide/bootstrap. ${POWER_RESTORE_NOTE}`,
             summary: "Attempts a controlled shutdown through the Ultimate control interface.",
             inputSchema: poweroffArgsSchema.jsonSchema,
             tags: ["power"],
@@ -227,7 +315,10 @@ export const machineControlModule = defineToolModule({
                         });
                     }
                     const details = toRecord(result.details) ?? {};
-                    return textResult("Power off command acknowledged.", {
+                    const message = ctx.platform?.id === "vice"
+                        ? "Power off command acknowledged."
+                        : `Power off command acknowledged. ${POWER_RESTORE_NOTE}`;
+                    return textResult(message, {
                         success: true,
                         details,
                     });
@@ -257,8 +348,9 @@ export const machineControlModule = defineToolModule({
             supportedPlatforms: ["c64u", "u2", "vice"],
             async execute(args, ctx) {
                 try {
-                    powerCycleArgsSchema.parse(args ?? {});
+                    const parsed = powerCycleArgsSchema.parse(args ?? {});
                     ctx.logger.info("Power cycling active backend");
+                    const before = await screenBeforeReset(ctx, parsed);
                     const result = await ctx.client.powerCycle();
                     if (!result.success) {
                         throw new ToolExecutionError("Power cycle did not complete", {
@@ -266,7 +358,7 @@ export const machineControlModule = defineToolModule({
                         });
                     }
                     const details = toRecord(result.details) ?? {};
-                    return textResult("Power-cycle request completed.", { success: true, details });
+                    return await withReadyResult(ctx, parsed, before, "Power-cycle request completed.", details);
                 }
                 catch (error) {
                     if (error instanceof ToolError)
@@ -342,7 +434,7 @@ export const machineControlModule = defineToolModule({
                     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 toolErrorResult(new ToolExecutionError("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.", { code: "native_menu_screen_unavailable", details: { fallback: "rest_configuration_or_manual_menu" }, cause: error }));
                     }
                     return unknownErrorResult(error);
                 }