c64bridge 0.7.4 → 0.8.1

package/dist/tools/meta/audio.js

@@ -4,13 +4,56 @@ import { recordAndAnalyzeAudio } from "../../audio/record_and_analyze_audio.js";
 import { jsonResult } from "../responses.js";
 import { ToolExecutionError, toolErrorResult, unknownErrorResult } from "../errors.js";
 import { sleep } from "./util.js";
-import { booleanSchema, numberSchema, objectSchema, optionalSchema, stringSchema } from "../schema.js";
+import { arraySchema, booleanSchema, numberSchema, objectSchema, optionalSchema, stringSchema } from "../schema.js";
 const DEFAULT_SILENCE_DURATION_SECONDS = 1.5;
 const DEFAULT_RMS_THRESHOLD = 0.02;
 const DEFAULT_SILENCE_WAIT_MS = 150;
 const DEFAULT_ANALYSIS_DURATION_SECONDS = 3;
 const DEFAULT_PLAYBACK_WAIT_MS = 500;
 const DEFAULT_POST_SILENCE_WAIT_MS = 200;
+const DEFAULT_PRESET_ANALYSIS_DURATION_SECONDS = 4;
+const DEFAULT_PRESET_WAIT_MS = 400;
+const LEGACY_PRESET_ALIAS = String.fromCharCode(103, 101, 114, 109, 97, 110, 95, 97, 110, 116, 104, 101, 109);
+const FUER_ELISE_SIDWAVE = `
+song:
+  title: "Für Elise"
+  mode: PAL
+  tempo: 76
+voices:
+  - id: 1
+    name: "Lead"
+    waveform: triangle
+    adsr: [1, 4, 9, 4]
+    patterns:
+      theme:
+        groove: ["E5", "D#5", "E5", "D#5", "E5", "B4", "D5", "C5", "A4", "-", "A3", "C4", "E4", "-", "A4", "B4", "-", "E4", "G#4", "B4", "C5", "-", "E5", "D#5", "E5", "D#5", "E5", "B4", "D5", "C5", "A4", "-"]
+  - id: 2
+    name: "Harmony"
+    waveform: triangle
+    adsr: [2, 5, 8, 5]
+    patterns:
+      accomp:
+        groove: ["-", "-", "-", "-", "-", "-", "-", "-", "A2", "E3", "A3", "E3", "A2", "E3", "A3", "E3", "E2", "B2", "E3", "B2", "E2", "B2", "E3", "B2", "-", "-", "-", "-", "-", "-", "-", "-"]
+  - id: 3
+    name: "Bass"
+    waveform: triangle
+    adsr: [1, 3, 10, 5]
+    patterns:
+      bass:
+        groove: ["-", "-", "-", "-", "-", "-", "-", "-", "A1", "-", "-", "-", "A1", "-", "-", "-", "E2", "-", "-", "-", "E2", "-", "-", "-", "-", "-", "-", "-", "-", "-", "-", "-"]
+timeline:
+  - section: "Theme"
+    bars: 8
+    layers: { v1: theme, v2: accomp, v3: bass }
+`;
+const MUSIC_PRESETS = {
+    fuer_elise: {
+        key: "fuer_elise",
+        title: "Für Elise",
+        description: "Play a compact SID arrangement of Beethoven's Bagatelle in A minor.",
+        sidwave: FUER_ELISE_SIDWAVE,
+    },
+};
 const silenceAndVerifyArgsSchema = objectSchema({
     description: "Arguments for the silence_and_verify meta tool",
     properties: {
@@ -38,6 +81,42 @@ const musicCompilePlayAnalyzeArgsSchema = objectSchema({
     },
     additionalProperties: false,
 });
+const musicPlayPresetArgsSchema = objectSchema({
+    description: "Play a built-in SID preset with optional backend switching and audio verification.",
+    properties: {
+        preset: optionalSchema(stringSchema({
+            description: "Named SID preset to compile and play. Canonical public preset: fuer_elise.",
+            minLength: 1,
+            default: "fuer_elise",
+        }), "fuer_elise"),
+        platforms: optionalSchema(arraySchema(stringSchema({
+            description: "Backends to target in sequence.",
+            enum: ["vice", "c64u"],
+            minLength: 1,
+        }))),
+        verify: optionalSchema(booleanSchema({
+            description: "Capture and analyze audio on supported backends after playback starts.",
+            default: true,
+        }), true),
+        analysisDurationSeconds: optionalSchema(numberSchema({
+            description: "Length of the verification recording on analyzable backends.",
+            minimum: 0.5,
+            maximum: 20,
+            default: DEFAULT_PRESET_ANALYSIS_DURATION_SECONDS,
+        }), DEFAULT_PRESET_ANALYSIS_DURATION_SECONDS),
+        waitBeforeCaptureMs: optionalSchema(numberSchema({
+            description: "Delay between starting playback and beginning verification capture.",
+            minimum: 0,
+            maximum: 5000,
+            default: DEFAULT_PRESET_WAIT_MS,
+        }), DEFAULT_PRESET_WAIT_MS),
+        restoreActiveBackend: optionalSchema(booleanSchema({
+            description: "Restore the backend that was active before the workflow started.",
+            default: true,
+        }), true),
+    },
+    additionalProperties: false,
+});
 async function silenceSid(context) {
     const { client } = context;
     if (!(client && typeof client.sidSilenceAll === "function")) {
@@ -67,6 +146,30 @@ function normalizeSidwaveInput(input) {
     }
     return undefined;
 }
+function canonicalPresetBackends() {
+    return ["vice", "c64u"];
+}
+function uniquePresetBackends(backends) {
+    return backends.filter((backend, index) => backends.indexOf(backend) === index);
+}
+function resolveMusicPreset(preset) {
+    const requestedKey = preset?.trim().toLowerCase() || "fuer_elise";
+    const normalizedKey = requestedKey === LEGACY_PRESET_ALIAS ? "fuer_elise" : requestedKey;
+    const definition = MUSIC_PRESETS[normalizedKey];
+    if (!definition) {
+        throw new ToolExecutionError("Unknown music preset", {
+            details: {
+                preset,
+                supportedPresets: Object.keys(MUSIC_PRESETS),
+            },
+        });
+    }
+    return {
+        definition,
+        requestedKey,
+        aliasUsed: requestedKey !== definition.key,
+    };
+}
 function extractRmsMetrics(globalMetrics) {
     const average = typeof globalMetrics.average_rms === "number" ? globalMetrics.average_rms : null;
     const max = typeof globalMetrics.max_rms === "number" ? globalMetrics.max_rms : null;
@@ -112,6 +215,13 @@ async function performSilenceCheck(context, analyzer, options) {
         analysis,
     };
 }
+async function trySilenceSid(context) {
+    const { client } = context;
+    if (!(client && typeof client.sidSilenceAll === "function")) {
+        return;
+    }
+    await client.sidSilenceAll();
+}
 function normaliseDetails(details) {
     if (details === null || details === undefined) {
         return null;
@@ -122,6 +232,135 @@ function normaliseDetails(details) {
     return { value: details };
 }
 export const tools = [
+    {
+        name: "music_play_preset",
+        description: "Compile and play a built-in SID preset, with optional multi-backend routing and verification.",
+        inputSchema: musicPlayPresetArgsSchema.jsonSchema,
+        async execute(args, context) {
+            try {
+                const parsed = musicPlayPresetArgsSchema.parse(args ?? {});
+                const resolvedPreset = resolveMusicPreset(parsed.preset);
+                const preset = resolvedPreset.definition;
+                const startingBackend = await context.client.getActiveBackendType();
+                const availableBackends = uniquePresetBackends(canonicalPresetBackends().filter((backend) => context.client.getAvailableBackends().includes(backend)));
+                const requestedBackends = uniquePresetBackends((parsed.platforms ?? [startingBackend]));
+                const missingBackends = requestedBackends.filter((backend) => !availableBackends.includes(backend));
+                if (missingBackends.length > 0) {
+                    throw new ToolExecutionError("Requested preset backends are not configured", {
+                        details: {
+                            preset: preset.key,
+                            requestedPreset: resolvedPreset.requestedKey,
+                            requestedBackends,
+                            availableBackends,
+                            missingBackends,
+                        },
+                    });
+                }
+                const document = parseSidwave(preset.sidwave);
+                const compiled = compileSidwaveToPrg(document);
+                const analyzer = resolveAnalyzer(context);
+                const verify = parsed.verify !== false;
+                const waitBeforeCaptureMs = parsed.waitBeforeCaptureMs ?? DEFAULT_PRESET_WAIT_MS;
+                const analysisDurationSeconds = parsed.analysisDurationSeconds ?? DEFAULT_PRESET_ANALYSIS_DURATION_SECONDS;
+                const restoreActiveBackend = parsed.restoreActiveBackend !== false;
+                const results = [];
+                let restoreError;
+                try {
+                    for (const backend of requestedBackends) {
+                        context.client.switchBackend(backend);
+                        context.setPlatform(backend);
+                        await trySilenceSid(context);
+                        const playback = await context.client.runPrg(compiled.prg);
+                        const backendResult = {
+                            backend,
+                            preset: preset.key,
+                            title: preset.title,
+                            details: playback.details ?? null,
+                        };
+                        if (!playback.success) {
+                            backendResult.success = false;
+                            backendResult.error = "playback_failed";
+                            results.push(backendResult);
+                            continue;
+                        }
+                        let verification = null;
+                        if (verify) {
+                            if (backend === "c64u") {
+                                if (waitBeforeCaptureMs > 0) {
+                                    await sleep(waitBeforeCaptureMs);
+                                }
+                                const analysis = await analyzer({
+                                    durationSeconds: analysisDurationSeconds,
+                                    expectedSidwave: preset.sidwave,
+                                });
+                                const metrics = extractRmsMetrics((analysis?.analysis?.global_metrics ?? {}));
+                                verification = {
+                                    mode: "audio-analysis",
+                                    durationSeconds: analysis.analysis?.durationSeconds ?? analysisDurationSeconds,
+                                    averageRms: metrics.average,
+                                    maxRms: metrics.max,
+                                    voices: analysis.analysis?.voices ?? [],
+                                    analysis,
+                                };
+                            }
+                            else {
+                                verification = {
+                                    mode: "playback-launch",
+                                    note: "Audio analysis is only available on c64u; verified that playback launched on this backend.",
+                                };
+                            }
+                        }
+                        await trySilenceSid(context);
+                        backendResult.verification = verification;
+                        backendResult.success = true;
+                        results.push(backendResult);
+                    }
+                }
+                finally {
+                    if (restoreActiveBackend) {
+                        try {
+                            context.client.switchBackend(startingBackend);
+                            context.setPlatform(startingBackend);
+                        }
+                        catch (error) {
+                            restoreError = error instanceof Error ? error.message : String(error);
+                        }
+                    }
+                }
+                const success = results.every((result) => result.success === true) && !restoreError;
+                const payload = {
+                    kind: "music_play_preset",
+                    preset: preset.key,
+                    requestedPreset: resolvedPreset.requestedKey,
+                    legacyAliasUsed: resolvedPreset.aliasUsed,
+                    title: preset.title,
+                    description: preset.description,
+                    startingBackend,
+                    requestedBackends,
+                    availableBackends,
+                    restoredBackend: restoreActiveBackend ? startingBackend : await context.client.getActiveBackendType(),
+                    verificationEnabled: verify,
+                    sidwave: preset.sidwave,
+                    results,
+                    ...(restoreError ? { restoreError } : {}),
+                };
+                const result = jsonResult(payload, {
+                    success,
+                    preset: preset.key,
+                    requestedPreset: resolvedPreset.requestedKey,
+                    legacyAliasUsed: resolvedPreset.aliasUsed,
+                    backends: requestedBackends,
+                });
+                return success ? result : { ...result, isError: true };
+            }
+            catch (error) {
+                if (error instanceof ToolExecutionError) {
+                    return toolErrorResult(error);
+                }
+                return unknownErrorResult(error);
+            }
+        },
+    },
     {
         name: "silence_and_verify",
         description: "Silence all SID voices, capture a short sample, and ensure the output is below an RMS threshold.",

package/dist/tools/meta/config.js

@@ -3,6 +3,7 @@ import { jsonResult } from "../responses.js";
 import { ToolError, ToolExecutionError, ToolValidationError, toolErrorResult, unknownErrorResult } from "../errors.js";
 import { promises as fs } from "node:fs";
 import { dirname, resolve as resolvePath } from "node:path";
+import { captureConfigSnapshot, validateSnapshotCategories } from "./configInventory.js";
 import { normalizeErrorDetails } from "./util.js";
 const configSnapshotAndRestoreArgsSchema = objectSchema({
     description: "Snapshot or restore full device configuration. Snapshot writes versioned JSON.",
@@ -28,40 +29,38 @@ export const tools = [
                 const path = resolvePath(String(parsed.path));
                 await fs.mkdir(dirname(path), { recursive: true });
                 if (action === "snapshot") {
-                    const [version, info, cats] = await Promise.all([
+                    const [version, info, snapshotData] = await Promise.all([
                         ctx.client.version(),
                         ctx.client.info(),
-                        ctx.client.configsList(),
+                        captureConfigSnapshot(ctx.client),
                     ]);
-                    const categories = Array.isArray(cats?.categories)
-                        ? cats.categories
-                        : [];
-                    const data = {};
-                    for (const category of categories) {
-                        try {
-                            const v = await ctx.client.configGet(category);
-                            data[category] = v;
-                        }
-                        catch (e) {
-                            data[category] = { _error: e instanceof Error ? e.message : String(e) };
-                        }
-                    }
                     const snapshot = {
                         createdAt: new Date().toISOString(),
                         version,
                         info,
-                        categories: data,
+                        inventory: snapshotData.inventory,
+                        categories: snapshotData.categories,
                     };
                     await fs.writeFile(path, JSON.stringify(snapshot, null, 2), "utf8");
-                    return jsonResult({ path, categoryCount: Object.keys(data).length }, { success: true });
+                    return jsonResult({
+                        path,
+                        categoryCount: Object.keys(snapshotData.categories).length,
+                        itemCount: snapshotData.inventory.length,
+                    }, { success: true });
                 }
                 if (action === "restore") {
                     const text = await fs.readFile(path, "utf8");
                     const snapshot = JSON.parse(text);
-                    if (!snapshot || typeof snapshot !== "object" || typeof snapshot.categories !== "object") {
+                    if (!snapshot || typeof snapshot !== "object") {
+                        throw new ToolValidationError("Invalid snapshot file", { path: "$.path" });
+                    }
+                    let payload;
+                    try {
+                        payload = validateSnapshotCategories(snapshot.categories);
+                    }
+                    catch {
                         throw new ToolValidationError("Invalid snapshot file", { path: "$.path" });
                     }
-                    const payload = snapshot.categories;
                     const result = await ctx.client.configBatchUpdate(payload);
                     if (!result.success) {
                         throw new ToolExecutionError("Batch update failed", { details: normalizeErrorDetails(result.details) });
@@ -73,16 +72,9 @@ export const tools = [
                 }
                 const text = await fs.readFile(path, "utf8");
                 const snapshot = JSON.parse(text);
-                const cats = await ctx.client.configsList();
-                const categories = Array.isArray(cats?.categories)
-                    ? cats.categories
-                    : [];
-                const current = {};
-                for (const c of categories) {
-                    current[c] = await ctx.client.configGet(c);
-                }
+                const snapCats = validateSnapshotCategories(snapshot.categories ?? {});
+                const current = (await captureConfigSnapshot(ctx.client)).categories;
                 const diff = {};
-                const snapCats = snapshot.categories ?? {};
                 for (const [cat, snapVal] of Object.entries(snapCats)) {
                     const curVal = current[cat];
                     if (JSON.stringify(snapVal) !== JSON.stringify(curVal)) {

package/dist/tools/meta/configInventory.js

@@ -0,0 +1,104 @@
+export function normalizeConfigInventory(details) {
+    const categories = details?.categories;
+    if (!Array.isArray(categories)) {
+        return [];
+    }
+    const inventory = [];
+    const seen = new Set();
+    for (const categoryEntry of categories) {
+        if (typeof categoryEntry === "string") {
+            const category = categoryEntry.trim();
+            if (!category) {
+                continue;
+            }
+            const key = `${category}::`;
+            if (!seen.has(key)) {
+                seen.add(key);
+                inventory.push({ category });
+            }
+            continue;
+        }
+        if (!categoryEntry || typeof categoryEntry !== "object") {
+            continue;
+        }
+        const category = typeof categoryEntry.name === "string"
+            ? (categoryEntry.name).trim()
+            : "";
+        if (!category) {
+            continue;
+        }
+        const items = Array.isArray(categoryEntry.items)
+            ? categoryEntry.items
+            : [];
+        if (items.length === 0) {
+            const key = `${category}::`;
+            if (!seen.has(key)) {
+                seen.add(key);
+                inventory.push({ category });
+            }
+            continue;
+        }
+        for (const itemEntry of items) {
+            if (typeof itemEntry !== "string") {
+                continue;
+            }
+            const item = itemEntry.trim();
+            if (!item) {
+                continue;
+            }
+            const key = `${category}::${item}`;
+            if (!seen.has(key)) {
+                seen.add(key);
+                inventory.push({ category, item });
+            }
+        }
+    }
+    return inventory;
+}
+export async function captureConfigSnapshot(client) {
+    const inventory = normalizeConfigInventory(await client.configsList());
+    const categories = {};
+    for (const entry of inventory) {
+        try {
+            const value = normalizeSnapshotValue(await client.configGet(entry.category, entry.item), entry);
+            setSnapshotValue(categories, entry, value);
+        }
+        catch (error) {
+            setSnapshotValue(categories, entry, {
+                _error: error instanceof Error ? error.message : String(error),
+            });
+        }
+    }
+    return { inventory, categories };
+}
+export function validateSnapshotCategories(value) {
+    if (!value || typeof value !== "object" || Array.isArray(value)) {
+        throw new Error("Snapshot categories payload must be an object");
+    }
+    return value;
+}
+function setSnapshotValue(target, entry, value) {
+    if (!entry.item) {
+        target[entry.category] = value;
+        return;
+    }
+    const existing = target[entry.category];
+    const bucket = existing && typeof existing === "object" && !Array.isArray(existing)
+        ? existing
+        : {};
+    bucket[entry.item] = value;
+    target[entry.category] = bucket;
+}
+function normalizeSnapshotValue(value, entry) {
+    if (!entry.item) {
+        return value;
+    }
+    if (value
+        && typeof value === "object"
+        && !Array.isArray(value)
+        && Object.keys(value).length === 1
+        && Object.prototype.hasOwnProperty.call(value, "value")) {
+        return value.value;
+    }
+    return value;
+}

package/dist/tools/meta/diagnostics.js

@@ -1,7 +1,18 @@
-import { objectSchema } from "../schema.js";
+import { objectSchema, stringSchema, booleanSchema, numberSchema, optionalSchema } from "../schema.js";
 import { jsonResult } from "../responses.js";
-import { ToolError, toolErrorResult, unknownErrorResult } from "../errors.js";
+import { ToolError, ToolExecutionError, toolErrorResult, unknownErrorResult } from "../errors.js";
+import { resolveDiagnosticSessionFile, summarizeDiagnosticsSession } from "../../diagnostics.js";
 const noArgsSchema = objectSchema({ description: "No arguments", properties: {}, additionalProperties: false });
+const performanceReportSchema = objectSchema({
+    description: "Summarize timing and diagnostic data from the current or latest MCP session.",
+    properties: {
+        scope: optionalSchema(stringSchema({ description: "Which diagnostics session to summarize.", enum: ["current", "latest"] }), "current"),
+        includeTimeline: optionalSchema(booleanSchema({ description: "Include the tail of the event timeline.", default: true }), true),
+        maxEntries: optionalSchema(numberSchema({ description: "Maximum number of span and timeline entries to return.", integer: true, minimum: 1, maximum: 200, default: 25 }), 25),
+    },
+    required: [],
+    additionalProperties: false,
+});
 export const tools = [
     {
         name: "firmware_info_and_healthcheck",
@@ -72,4 +83,36 @@ export const tools = [
             }
         },
     },
+    {
+        name: "performance_report",
+        description: "Summarize MCP session timings, span hot spots, and tool latencies from diagnostics logs.",
+        summary: "Returns a structured performance report for the current or latest diagnostics session.",
+        inputSchema: performanceReportSchema.jsonSchema,
+        tags: ["diagnostics", "performance", "profiling"],
+        examples: [{ name: "Current session", description: "Inspect the active MCP session trace", arguments: {} }],
+        async execute(args) {
+            try {
+                const parsed = performanceReportSchema.parse(args ?? {});
+                const scope = parsed.scope ?? "current";
+                const filePath = resolveDiagnosticSessionFile(scope) ?? resolveDiagnosticSessionFile("latest");
+                if (!filePath) {
+                    throw new ToolExecutionError("No diagnostics session file is available yet");
+                }
+                const report = summarizeDiagnosticsSession(filePath, {
+                    includeTimeline: parsed.includeTimeline !== false,
+                    maxEntries: Number(parsed.maxEntries ?? 25),
+                });
+                return jsonResult(report, {
+                    success: true,
+                    filePath,
+                    sessionId: report.sessionId,
+                });
+            }
+            catch (error) {
+                if (error instanceof ToolError)
+                    return toolErrorResult(error);
+                return unknownErrorResult(error);
+            }
+        },
+    },
 ];

package/dist/tools/meta/graphics.js

@@ -4,6 +4,10 @@ import { ToolError, ToolExecutionError, ToolValidationError, toolErrorResult, un
 import { normalizeErrorDetails } from "./util.js";
 import { promises as fs } from "node:fs";
 import { dirname, resolve as resolvePath } from "node:path";
+function supportsMachinePause(ctx) {
+    const platformId = ctx.platform?.id ?? ctx.client?.type;
+    return platformId !== "vice";
+}
 function parseAddressNumeric(value) {
     if (typeof value !== "string" || value.trim().length === 0) {
         throw new ToolValidationError("Address must be a non-empty string", { path: "$.address" });
@@ -214,10 +218,11 @@ export const tools = [
                 if (stride < 63) {
                     throw new ToolValidationError("Stride must be at least 63 bytes to avoid overlapping sprites", { path: "$.stride" });
                 }
-                const pauseResume = pauseDuringRead
+                const canPause = pauseDuringRead && supportsMachinePause(ctx);
+                const pauseResume = canPause
                     ? await ctx.client.pause()
                     : { success: true };
-                if (pauseDuringRead && !pauseResume.success) {
+                if (canPause && !pauseResume.success) {
                     throw new ToolExecutionError("Pause failed before sprite scan", { details: normalizeErrorDetails(pauseResume.details) });
                 }
                 try {
@@ -267,13 +272,14 @@ export const tools = [
                             length,
                             stride,
                             candidates,
+                            paused: canPause,
                         },
                         sprites,
                         outputFiles,
                     }, { success: true });
                 }
                 finally {
-                    if (pauseDuringRead) {
+                    if (canPause) {
                         await ctx.client.resume();
                     }
                 }
@@ -331,10 +337,11 @@ export const tools = [
                     // Default: scan common locations
                     scanLocations.push(...commonLocations);
                 }
-                const pauseResume = pauseDuringRead
+                const canPause = pauseDuringRead && supportsMachinePause(ctx);
+                const pauseResume = canPause
                     ? await ctx.client.pause()
                     : { success: true };
-                if (pauseDuringRead && !pauseResume.success) {
+                if (canPause && !pauseResume.success) {
                     throw new ToolExecutionError("Pause failed before charset scan", { details: normalizeErrorDetails(pauseResume.details) });
                 }
                 try {
@@ -383,10 +390,11 @@ export const tools = [
                         charset: analysisWithoutBytes,
                         candidates: candidates.length,
                         outputFile,
+                        paused: canPause,
                     }, { success: true });
                 }
                 finally {
-                    if (pauseDuringRead) {
+                    if (canPause) {
                         await ctx.client.resume();
                     }
                 }

package/dist/tools/meta/index.js

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

package/dist/tools/meta/memory.js

@@ -5,6 +5,10 @@ import { promises as fs } from "node:fs";
 import { dirname, resolve as resolvePath } from "node:path";
 import { createHash } from "node:crypto";
 import { normalizeErrorDetails } from "./util.js";
+function supportsMachinePause(ctx) {
+    const platformId = ctx.platform?.id ?? ctx.client?.type;
+    return platformId !== "vice";
+}
 function hexClean(input) {
     const trimmed = input.trim();
     const withoutPrefix = trimmed.startsWith("$") ? trimmed.slice(1) : trimmed;
@@ -94,9 +98,14 @@ export const tools = [
                 const maskBytes = parsed.mask ? hexToBytes(parsed.mask) : undefined;
                 const verifyLen = expectedBytes.length;
                 const readLen = Math.max(writeBytes.length, verifyLen);
-                const paused = await ctx.client.pause();
-                if (!paused.success) {
-                    throw new ToolExecutionError("C64 firmware reported failure while pausing", { details: normalizeErrorDetails(paused.details) });
+                const canPause = supportsMachinePause(ctx);
+                let paused = false;
+                if (canPause) {
+                    const pauseResult = await ctx.client.pause();
+                    if (!pauseResult.success) {
+                        throw new ToolExecutionError("C64 firmware reported failure while pausing", { details: normalizeErrorDetails(pauseResult.details) });
+                    }
+                    paused = true;
                 }
                 let preReadHex;
                 try {
@@ -147,10 +156,13 @@ export const tools = [
                         wrote: bytesToHex(writeBytes),
                         preRead: preReadHex,
                         postRead: post.data ?? "",
+                        paused,
                     }, { success: true });
                 }
                 finally {
-                    await ctx.client.resume();
+                    if (paused) {
+                        await ctx.client.resume();
+                    }
                 }
             }
             catch (error) {
@@ -176,7 +188,8 @@ export const tools = [
                 const outputPath = resolvePath(String(parsed.outputPath));
                 const outDir = dirname(outputPath);
                 await fs.mkdir(outDir, { recursive: true });
-                if (pause) {
+                const canPause = pause && supportsMachinePause(ctx);
+                if (canPause) {
                     const res = await ctx.client.pause();
                     if (!res.success) {
                         throw new ToolExecutionError("Pause failed before dump", { details: normalizeErrorDetails(res.details) });
@@ -233,13 +246,14 @@ export const tools = [
                         format: (parsed.format ?? "hex").toString().toLowerCase(),
                         checksum,
                         outputPath,
+                        paused: canPause,
                         createdAt: new Date().toISOString(),
                     };
                     await fs.writeFile(`${outputPath}.json`, JSON.stringify(manifest, null, 2), "utf8");
                     return jsonResult({ manifest }, { success: true });
                 }
                 finally {
-                    if (pause) {
+                    if (canPause) {
                         await ctx.client.resume();
                     }
                 }