c64bridge 1.0.7 → 1.1.0

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)

package/dist/tools/memory.js

@@ -9,6 +9,10 @@ import { disassemble, formatDisassembly } from "./translation/disassembler.js";
 import { getViceSymbols } from "./translation/symbolRegistry.js";
 import { resolveAddressSymbol } from "../knowledge.js";
 import { stripHexByteSeparators } from "./hex.js";
+import { resolveHostPath } from "../hostPaths.js";
+import { petsciiToAscii } from "../petscii.js";
+import { listBasicProgram, MAX_BASIC_IMAGE_BYTES } from "./translation/basicDetokenizer.js";
+import { assertAddressRange, assertNotBareHex, parseNumericLiteral } from "../numericArg.js";
 function toRecord(details) {
     if (details && typeof details === "object") {
         return details;
@@ -120,6 +124,11 @@ const readMemoryArgsSchema = objectSchema({
             maximum: 4096,
             default: 256,
         }),
+        format: optionalSchema(stringSchema({
+            description: "Output layout. hex (default) returns one hex string; dump adds a 16-bytes-per-line listing with addresses and a printable PETSCII column.",
+            enum: ["hex", "dump"],
+            default: "hex",
+        }), "hex"),
     },
     required: ["address"],
     additionalProperties: false,
@@ -166,11 +175,19 @@ async function executeReadScreen(rawArgs, ctx) {
     try {
         readScreenArgsSchema.parse(rawArgs ?? {});
         ctx.logger.info("Reading C64 screen contents");
-        const screen = await ctx.client.readScreen();
+        const client = ctx.client;
+        const detailed = typeof client.readScreenDetailed === "function" ? await client.readScreenDetailed() : undefined;
+        const screen = detailed ? detailed.text : await ctx.client.readScreen();
         return textResult(`Current screen contents:\n${screen}`, {
             success: true,
             screen,
             length: screen.length,
+            ...(detailed
+                ? {
+                    screenBase: `$${detailed.baseAddress.toString(16).toUpperCase().padStart(4, "0")}`,
+                    charset: detailed.charset,
+                }
+                : {}),
         });
     }
     catch (error) {
@@ -180,10 +197,77 @@ async function executeReadScreen(rawArgs, ctx) {
         return unknownErrorResult(error);
     }
 }
+const listBasicArgsSchema = objectSchema({
+    description: "List the BASIC program currently in memory. Reads the start ($2B/$2C) and end ($2D/$2E) pointers and detokenises the program text.",
+    properties: {},
+    additionalProperties: false,
+});
+async function readRange(ctx, start, length) {
+    const chunks = [];
+    for (let offset = 0; offset < length; offset += 4096) {
+        const count = Math.min(4096, length - offset);
+        const address = `$${(start + offset).toString(16).toUpperCase().padStart(4, "0")}`;
+        const result = await ctx.client.readMemory(address, String(count));
+        if (!result.success) {
+            throw new ToolExecutionError("C64 backend reported failure while reading memory", { details: normaliseFailure(result.details) });
+        }
+        const bytes = parseFirmwareHex(result.data, "BASIC program read").bytes;
+        if (bytes.length !== count) {
+            throw new ToolExecutionError("Memory read returned an unexpected number of bytes", { details: { address, expected: count, received: bytes.length } });
+        }
+        chunks.push(bytes);
+    }
+    return Buffer.concat(chunks);
+}
+async function executeListBasic(rawArgs, ctx) {
+    try {
+        listBasicArgsSchema.parse(rawArgs ?? {});
+        const pointers = await readRange(ctx, 0x002b, 4);
+        const start = pointers[0] | (pointers[1] << 8);
+        const end = pointers[2] | (pointers[3] << 8);
+        const fmt = (value) => `$${value.toString(16).toUpperCase().padStart(4, "0")}`;
+        if (end <= start) {
+            return jsonResult({ start: fmt(start), end: fmt(end), lines: [], listing: "" }, { success: true, lineCount: 0 });
+        }
+        const length = end - start;
+        if (length > MAX_BASIC_IMAGE_BYTES) {
+            throw new ToolExecutionError("BASIC end pointer is implausible", { details: { start: fmt(start), end: fmt(end) } });
+        }
+        const image = await readRange(ctx, start, length);
+        const lines = listBasicProgram(image, start);
+        const listing = lines.map((line) => `${line.number} ${line.text}`).join("\n");
+        return jsonResult({ start: fmt(start), end: fmt(end), lines, listing }, { success: true, lineCount: lines.length });
+    }
+    catch (error) {
+        if (error instanceof ToolError)
+            return toolErrorResult(error);
+        return unknownErrorResult(error);
+    }
+}
+/** 16 bytes per line: `$ADDR: HH HH ... |text|`. Bytes with no printable PETSCII glyph show as `.`. */
+export function formatHexDump(start, bytes) {
+    const lines = [];
+    for (let offset = 0; offset < bytes.length; offset += 16) {
+        const row = bytes.subarray(offset, offset + 16);
+        const hex = Array.from(row, (b) => b.toString(16).toUpperCase().padStart(2, "0")).join(" ").padEnd(16 * 3 - 1, " ");
+        const text = Array.from(row, (b) => {
+            if (b === 0x20 || b === 0xa0)
+                return " ";
+            const ch = petsciiToAscii(Uint8Array.of(b));
+            return ch.length === 1 && ch > " " && ch <= "~" ? ch : ".";
+        }).join("");
+        const address = ((start + offset) & 0xffff).toString(16).toUpperCase().padStart(4, "0");
+        lines.push(`$${address}: ${hex}  |${text}|`);
+    }
+    return lines;
+}
 async function executeReadMemory(rawArgs, ctx) {
     try {
         const parsed = readMemoryArgsSchema.parse(rawArgs ?? {});
         ctx.logger.info("Reading C64 memory", { address: parsed.address, length: parsed.length });
+        // Validate before any device call so a bad address is a validation error.
+        const readStart = parseAddressArg(parsed.address, "$.address");
+        assertAddressRange(readStart, parsed.length ?? 256, "$.length");
         const result = await ctx.client.readMemory(parsed.address, String(parsed.length));
         if (!result.success) {
             throw new ToolExecutionError("C64 backend reported failure while reading memory", {
@@ -193,15 +277,21 @@ async function executeReadMemory(rawArgs, ctx) {
         const detailRecord = toRecord(result.details) ?? {};
         const resolvedAddress = resolveAddressLabel(detailRecord, parsed.address);
         const resolvedLength = resolveLength(detailRecord) ?? parsed.length;
+        const dumpLines = parsed.format === "dump" && typeof result.data === "string"
+            ? formatHexDump(readStart, parseFirmwareHex(result.data, "memory read").bytes)
+            : undefined;
         const data = {
             success: true,
             address: resolvedAddress,
             length: resolvedLength,
             hexData: result.data ?? null,
+            ...(dumpLines ? { dump: dumpLines } : {}),
             details: detailRecord,
         };
         // Many clients show only the text content, so it carries the bytes too.
-        const hexSummary = typeof result.data === "string" && result.data.length > 0 ? `\n${result.data}` : "";
+        const hexSummary = dumpLines
+            ? `\n${dumpLines.join("\n")}`
+            : typeof result.data === "string" && result.data.length > 0 ? `\n${result.data}` : "";
         const base = textResult(`Read ${resolvedLength} bytes starting at ${resolvedAddress}.${hexSummary}`, data);
         return {
             ...base,
@@ -226,6 +316,7 @@ async function executeWriteMemory(rawArgs, ctx) {
         const expectedInfo = parsed.expected ? parseUserHex(parsed.expected, "$.expected") : undefined;
         const maskInfo = parsed.mask ? parseUserHex(parsed.mask, "$.mask") : undefined;
         const shouldVerify = parsed.verify || Boolean(expectedInfo) || Boolean(maskInfo);
+        assertAddressRange(parseAddressArg(parsed.address, "$.address"), writeInfo.bytes.length, "$.bytes");
         if (!shouldVerify) {
             const result = await ctx.client.writeMemory(parsed.address, writeInfo.canonical);
             if (!result.success) {
@@ -249,7 +340,7 @@ async function executeWriteMemory(rawArgs, ctx) {
         let paused = false;
         try {
             if (canPause) {
-                const pauseResult = await ctx.client.pause(pinnedFacade);
+                const pauseResult = ctx.client.acquirePause ? await ctx.client.acquirePause(pinnedFacade) : await ctx.client.pause(pinnedFacade);
                 if (!pauseResult.success) {
                     throw new ToolExecutionError("C64 backend reported failure while pausing", {
                         details: normaliseFailure(pauseResult.details),
@@ -339,7 +430,8 @@ async function executeWriteMemory(rawArgs, ctx) {
                 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);
+                const resumeResult = ctx.client.releasePause ? await ctx.client.releasePause(pinnedFacade) : await ctx.client.resume(pinnedFacade);
+                paused = false; // released once, whatever the outcome: the finally block must not release again
                 if (!resumeResult.success) {
                     throw new ToolExecutionError("Write completed but the machine could not be resumed", {
                         details: {
@@ -366,7 +458,7 @@ async function executeWriteMemory(rawArgs, ctx) {
         finally {
             if (paused) {
                 try {
-                    const resumeResult = await ctx.client.resume(pinnedFacade);
+                    const resumeResult = ctx.client.releasePause ? await ctx.client.releasePause(pinnedFacade) : await ctx.client.resume(pinnedFacade);
                     if (!resumeResult.success) {
                         ctx.logger.warn("C64 resume reported failure after write", {
                             details: normaliseFailure(resumeResult.details),
@@ -406,7 +498,7 @@ const disassembleArgsSchema = objectSchema({
             default: 64,
         }),
         instructionCount: optionalSchema(numberSchema({
-            description: "Stop after this many instructions (overrides length as a termination condition).",
+            description: "Stop after this many instructions. When given, it replaces length: 3 x instructionCount bytes are read (fewer near $FFFF).",
             integer: true,
             minimum: 1,
             maximum: 512,
@@ -418,9 +510,13 @@ const disassembleArgsSchema = objectSchema({
 async function executeDisassemble(rawArgs, ctx) {
     try {
         const parsed = disassembleArgsSchema.parse(rawArgs ?? {});
-        const length = parsed.length ?? 64;
-        ctx.logger.info("Disassembling VICE memory", { address: parsed.address, length });
         const address = parseAddressArg(parsed.address, "$.address");
+        // An instruction is at most 3 bytes, so 3 x instructionCount bytes always
+        // cover the requested instructions; clamp at the end of the address space.
+        const length = parsed.instructionCount !== undefined
+            ? Math.min(3 * parsed.instructionCount, 0x10000 - address)
+            : parsed.length ?? 64;
+        ctx.logger.info("Disassembling VICE memory", { address: parsed.address, length });
         validateRangeWithinAddressSpace(address, length, "$.address");
         const bytes = await ctx.client.readMemoryRaw(address, length);
         const symbols = ctx.platform?.id === "vice" ? getViceSymbols() : undefined;
@@ -432,6 +528,14 @@ async function executeDisassemble(rawArgs, ctx) {
             address: addrHex,
             bytesRead: bytes.length,
             instructionCount: lines.length,
+            lines: lines.map((line) => ({
+                address: `$${line.address.toString(16).toUpperCase().padStart(4, "0")}`,
+                bytes: line.bytes.map((value) => value.toString(16).toUpperCase().padStart(2, "0")),
+                ...(line.label ? { label: line.label } : {}),
+                mnemonic: line.mnemonic,
+                operand: line.operand,
+                undocumented: line.undocumented,
+            })),
         });
     }
     catch (error) {
@@ -446,26 +550,16 @@ async function executeDisassemble(rawArgs, ctx) {
 // ---------------------------------------------------------------------------
 function parseAddressArg(raw, fieldPath) {
     const trimmed = raw.trim();
-    let addr;
-    if (/^\$[0-9A-Fa-f]+$/.test(trimmed)) {
-        addr = parseInt(trimmed.slice(1), 16);
-    }
-    else if (/^0[xX][0-9A-Fa-f]+$/.test(trimmed)) {
-        addr = parseInt(trimmed.slice(2), 16);
-    }
-    else if (/^[0-9]+$/.test(trimmed)) {
-        addr = parseInt(trimmed, 10);
-    }
-    else {
+    let addr = parseNumericLiteral(trimmed, fieldPath);
+    if (addr === undefined) {
         const resolved = resolveAddressSymbol(trimmed);
         if (resolved === undefined) {
+            assertNotBareHex(trimmed, fieldPath);
             throw new ToolValidationError(`Unknown address or symbol: ${trimmed}`, { path: fieldPath });
         }
         addr = resolved;
     }
-    if (!Number.isInteger(addr) || addr < 0 || addr > 0xffff) {
-        throw new ToolValidationError("Address must be in range $0000-$FFFF", { path: fieldPath });
-    }
+    assertAddressRange(addr, undefined, fieldPath);
     return addr;
 }
 function fmtAddr(addr) {
@@ -584,14 +678,19 @@ async function executeSearchMemory(rawArgs, ctx) {
         ctx.logger.info("Searching memory", { start: fmtAddr(start), end: fmtAddr(end), pattern: parsed.pattern });
         const haystack = await ctx.client.readMemoryRaw(start, len);
         const matches = [];
-        outer: for (let i = 0; i <= haystack.length - needle.length && matches.length < maxResults; i++) {
+        // The whole range is already read, so counting past maxResults costs no device call.
+        let totalMatches = 0;
+        outer: for (let i = 0; i <= haystack.length - needle.length; i++) {
             for (let j = 0; j < needle.length; j++) {
                 if (haystack[i + j] !== needle[j])
                     continue outer;
             }
-            matches.push(fmtAddr(start + i));
+            totalMatches += 1;
+            if (matches.length < maxResults)
+                matches.push(fmtAddr(start + i));
         }
-        return jsonResult({ found: matches.length, matches, pattern: parsed.pattern.trim(), range: { start: fmtAddr(start), end: fmtAddr(end) } }, { success: true, found: matches.length });
+        const truncated = totalMatches > matches.length;
+        return jsonResult({ found: matches.length, totalMatches, truncated, matches, pattern: parsed.pattern.trim(), range: { start: fmtAddr(start), end: fmtAddr(end) } }, { success: true, found: matches.length, totalMatches, truncated });
     }
     catch (error) {
         if (error instanceof ToolError)
@@ -628,8 +727,12 @@ async function executeCompareMemory(rawArgs, ctx) {
             ctx.client.readMemoryRaw(a2, len),
         ]);
         const diffs = [];
-        for (let i = 0; i < len && diffs.length < maxDiffs; i++) {
+        let totalDiffs = 0;
+        for (let i = 0; i < len; i++) {
             if (r1[i] !== r2[i]) {
+                totalDiffs += 1;
+                if (diffs.length >= maxDiffs)
+                    continue;
                 diffs.push({
                     offset: i,
                     address1: fmtAddr(a1 + i),
@@ -639,8 +742,9 @@ async function executeCompareMemory(rawArgs, ctx) {
                 });
             }
         }
-        const identical = diffs.length === 0;
-        return jsonResult({ identical, diffCount: diffs.length, diffs, region1: fmtAddr(a1), region2: fmtAddr(a2), length: len }, { success: true, identical, diffCount: diffs.length });
+        const identical = totalDiffs === 0;
+        const truncated = totalDiffs > diffs.length;
+        return jsonResult({ identical, diffCount: totalDiffs, returnedDiffs: diffs.length, truncated, diffs, region1: fmtAddr(a1), region2: fmtAddr(a2), length: len }, { success: true, identical, diffCount: totalDiffs, truncated });
     }
     catch (error) {
         if (error instanceof ToolError)
@@ -671,7 +775,7 @@ async function executeSaveMemory(rawArgs, ctx) {
             throw new ToolValidationError("endAddress must be ≥ startAddress", { path: "$.endAddress" });
         const asPrg = parsed.asPrg !== false;
         const len = end - start + 1;
-        const resolvedPath = path.resolve(parsed.filePath);
+        const resolvedPath = resolveHostPath(parsed.filePath, { purpose: "write" });
         ctx.logger.info("Saving memory to file", { start: fmtAddr(start), end: fmtAddr(end), filePath: resolvedPath, asPrg });
         const bytes = await ctx.client.readMemoryRaw(start, len);
         const header = asPrg ? Buffer.from([start & 0xff, (start >> 8) & 0xff]) : Buffer.alloc(0);
@@ -690,6 +794,7 @@ export const memoryOperationHandlers = {
     read: async (args, ctx) => executeReadMemory(stripOperationDiscriminator(args), ctx),
     write: async (args, ctx) => executeWriteMemory(stripOperationDiscriminator(args), ctx),
     read_screen: async (args, ctx) => executeReadScreen(stripOperationDiscriminator(args), ctx),
+    list_basic: async (args, ctx) => executeListBasic(stripOperationDiscriminator(args), ctx),
     disassemble: async (args, ctx) => executeDisassemble(stripOperationDiscriminator(args), ctx),
     copy_memory: async (args, ctx) => executeCopyMemory(stripOperationDiscriminator(args), ctx),
     fill_memory: async (args, ctx) => executeFillMemory(stripOperationDiscriminator(args), ctx),
@@ -697,7 +802,7 @@ export const memoryOperationHandlers = {
     compare_memory: async (args, ctx) => executeCompareMemory(stripOperationDiscriminator(args), ctx),
     save_memory: async (args, ctx) => executeSaveMemory(stripOperationDiscriminator(args), ctx),
 };
-export { disassembleArgsSchema, copyMemoryArgsSchema, fillMemoryArgsSchema, searchMemoryArgsSchema, compareMemoryArgsSchema, saveMemoryArgsSchema, };
+export { listBasicArgsSchema, disassembleArgsSchema, copyMemoryArgsSchema, fillMemoryArgsSchema, searchMemoryArgsSchema, compareMemoryArgsSchema, saveMemoryArgsSchema, };
 export const memoryModule = defineToolModule({
     domain: "memory",
     summary: "Screen, main memory, and low-level inspection utilities.",

package/dist/tools/meta/artifacts.js

@@ -3,7 +3,8 @@ import { jsonResult } from "../responses.js";
 import { ToolError, ToolValidationError, ToolUnsupportedPlatformError, toolErrorResult, unknownErrorResult } from "../errors.js";
 import { getPlatformStatus } from "../../platform.js";
 import { promises as fs } from "node:fs";
-import { resolve as resolvePath, join as joinPath, relative, sep, isAbsolute } from "node:path";
+import { resolve as resolvePath, join as joinPath, isAbsolute } from "node:path";
+import { isWithin, resolveHostChildPath, resolveHostPath } from "../../hostPaths.js";
 const bundleRunArtifactsArgsSchema = objectSchema({
     description: "Gather screen capture, memory snapshot, and debugreg into a structured bundle.",
     properties: {
@@ -45,7 +46,7 @@ export const tools = [
                 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 outputPath = resolveHostPath(String(parsed.outputPath), { purpose: "write" });
                 const captureScreen = parsed.captureScreen !== false;
                 const platform = ctx.platform?.id ?? getPlatformStatus().id;
                 const captureDebugReg = parsed.captureDebugReg ?? (platform === "c64u");
@@ -105,8 +106,7 @@ 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))
+    if (candidate === base || !isWithin(base, candidate))
         throw new ToolValidationError("Artifact path escapes its output directory.");
-    return candidate;
+    return resolveHostChildPath(base, name);
 }