c64bridge 1.0.6 → 1.1.0

package/dist/tools/pollValidator.js

@@ -5,6 +5,7 @@ Copyright (C) 2025 Christian Gleissner
 Licensed under the GNU General Public License v2.0 or later.
 See <https://www.gnu.org/licenses/> for details.
 */
+const LOAD_CHECK_BYTES = 16;
 /**
  * Load poll configuration from environment variables with defaults.
  */
@@ -156,7 +157,49 @@ async function pollBasicOutcome(client, logger, config) {
  * to determine if program is alive or crashed.
  * First waits for RUN to appear, then monitors for activity across multiple memory regions.
  */
-async function pollAsmOutcome(client, logger, config) {
+function toHex(bytes) {
+    return Array.from(bytes, (value) => value.toString(16).toUpperCase().padStart(2, "0")).join(" ");
+}
+/**
+ * Reads back up to 16 bytes at the load address and compares them with the
+ * assembled program. A U2-family firmware answers run_prg with success without
+ * loading anything, so this is the evidence that the program reached memory.
+ * Needs confirmation on U2 hardware; it is exercised against mocks only.
+ */
+async function checkProgramLoaded(client, logger, program) {
+    const length = Math.min(LOAD_CHECK_BYTES, program.bytes.length, 0x10000 - program.address);
+    if (length <= 0) {
+        return { loadCheck: "skipped" };
+    }
+    const expected = program.bytes.subarray(0, length);
+    let found;
+    try {
+        found = await client.readMemoryRaw(program.address, length);
+    }
+    catch (error) {
+        logger.debug("Unable to read back the loaded program", { error });
+        return { loadCheck: "unavailable" };
+    }
+    if (!buffersEqual(found.subarray(0, length), expected)) {
+        return { loadCheck: "matched", load: { address: program.address, expected: toHex(expected), found: toHex(found.subarray(0, length)) } };
+    }
+    return { loadCheck: "matched" };
+}
+async function pollAsmOutcome(client, logger, config, program) {
+    let loadCheck = "skipped";
+    if (program) {
+        const check = await checkProgramLoaded(client, logger, program);
+        loadCheck = check.loadCheck;
+        if (check.load) {
+            return {
+                status: "not_loaded",
+                type: "ASM",
+                reason: `memory at $${program.address.toString(16).toUpperCase().padStart(4, "0")} does not contain the assembled program`,
+                loadCheck: "matched",
+                load: check.load,
+            };
+        }
+    }
     const startTime = Date.now();
     let pollCount = 0;
     let runDetected = false;
@@ -173,7 +216,7 @@ async function pollAsmOutcome(client, logger, config) {
             if (returnedToBasicAfterSys(screen)) {
                 // The typed SYS line is followed by READY., so the routine ran and returned with RTS.
                 logger.debug("ASM program returned to BASIC", { elapsed: Date.now() - startTime });
-                return { status: "ok", type: "ASM" };
+                return { status: "ok", type: "ASM", loadCheck };
             }
             if (upperScreen.includes("RUN") || upperScreen.includes("SYS") || upperScreen.includes("ERROR")) {
                 runDetected = true;
@@ -204,7 +247,7 @@ async function pollAsmOutcome(client, logger, config) {
             // A routine that works for a while before RTS shows READY. only after the first screen read.
             if (returnedToBasicAfterSys(await client.readScreen())) {
                 logger.debug("ASM program returned to BASIC", { pollCount, elapsed: Date.now() - startTime });
-                return { status: "ok", type: "ASM" };
+                return { status: "ok", type: "ASM", loadCheck };
             }
         }
         catch (error) {
@@ -235,14 +278,16 @@ async function pollAsmOutcome(client, logger, config) {
         return {
             status: "ok",
             type: "ASM",
+            loadCheck,
         };
     }
-    // No activity detected - consider it crashed
-    logger.debug("ASM program crashed - no VIC/CIA/TI/screen progression", { pollCount, elapsed: Date.now() - startTime });
+    // No screen change: the program may be running silently, so this is not evidence of a crash.
+    logger.debug("ASM program unconfirmed - no screen progression", { pollCount, elapsed: Date.now() - startTime });
     return {
-        status: "crashed",
+        status: "unconfirmed",
         type: "ASM",
         reason: "no program-visible screen progression within window",
+        loadCheck,
     };
 }
 /**
@@ -254,7 +299,7 @@ async function pollAsmOutcome(client, logger, config) {
  * @param config - Optional poll configuration (uses environment defaults if not provided)
  * @returns Promise resolving to poll result
  */
-export async function pollForProgramOutcome(type, client, logger, config) {
+export async function pollForProgramOutcome(type, client, logger, config, program) {
     const defaults = loadPollConfig();
     const pollConfig = {
         maxMs: config?.maxMs ?? defaults.maxMs,
@@ -271,5 +316,5 @@ export async function pollForProgramOutcome(type, client, logger, config) {
     if (type === "BASIC") {
         return pollBasicOutcome(client, logger, pollConfig);
     }
-    return pollAsmOutcome(client, logger, pollConfig);
+    return pollAsmOutcome(client, logger, pollConfig, program);
 }

package/dist/tools/programRunners.js

@@ -1,4 +1,5 @@
 import fs from "node:fs";
+import { resolveHostPath } from "../hostPaths.js";
 import { assemblyToPrgDetailed, AssemblyError } from "./translation/assembler.js";
 import { basicToPrg } from "./translation/basicTokenizer.js";
 import { defineToolModule, OPERATION_DISCRIMINATOR, } from "./types.js";
@@ -117,10 +118,13 @@ function attemptAutoFixBasicProgram(program, errors) {
         }
         if (notes.length > 0) {
             const updated = content.length > 0 ? `${lineNumber} ${content}` : `${lineNumber}`;
+            const before = rawLine.trim();
             lines[index] = updated;
             changes.push({
                 line: lineNumber,
                 notes,
+                before,
+                after: updated,
             });
         }
     }
@@ -206,6 +210,10 @@ const uploadBasicArgsSchema = objectSchema({
             description: "Run post-execution polling to ensure the BASIC program executed without errors.",
             default: false,
         }),
+        autoFix: optionalSchema(booleanSchema({
+            description: "When a BASIC error is detected on screen, append a missing closing quote or parentheses to the failing line and run the program again (default true). The rewritten lines are reported with before and after text. Set false for programs with side effects, which must not run twice.",
+            default: true,
+        })),
     },
     required: ["program"],
     additionalProperties: false,
@@ -218,7 +226,7 @@ const uploadAsmArgsSchema = objectSchema({
             minLength: 1,
         }),
         verify: booleanSchema({
-            description: "Run post-execution polling to confirm the assembly program remained stable.",
+            description: "Treat missing evidence of execution as an error. The bytes read back at the load address must always match the assembled program (a mismatch is an error either way). With verify:true, a program that loaded but changed nothing on screen is an error; with verify:false it returns success with execution:\"unconfirmed\" (SID players, border effects and JMP * loops change no screen RAM).",
             default: false,
         }),
     },
@@ -287,7 +295,7 @@ async function executeUploadRunBasic(rawArgs, ctx) {
                     errors: errors.map((error) => ({ line: error.line, type: error.type })),
                 });
                 const normalizedErrors = normalizeRuntimeErrors(errors);
-                const fixAttempt = attemptAutoFixBasicProgram(activeProgram, errors);
+                const fixAttempt = parsed.autoFix === false ? undefined : attemptAutoFixBasicProgram(activeProgram, errors);
                 if (!fixAttempt) {
                     const data = {
                         kind: "basic_runtime_error",
@@ -296,9 +304,12 @@ async function executeUploadRunBasic(rawArgs, ctx) {
                         ...(screenOutput ? { screen: screenOutput } : {}),
                         autoFix: {
                             attempted: false,
+                            ...(parsed.autoFix === false ? { disabled: true } : {}),
                         },
                     };
-                    return structuredExecutionError("Detected BASIC runtime errors after execution.", data);
+                    return structuredExecutionError(parsed.autoFix === false
+                        ? "Detected BASIC runtime errors after execution. Auto-fix is disabled (autoFix:false), so the program was not rewritten or run again."
+                        : "Detected BASIC runtime errors after execution.", data);
                 }
                 ctx.logger.info("Attempting BASIC auto-fix", {
                     changes: fixAttempt.changes.map((change) => ({
@@ -384,9 +395,14 @@ async function executeUploadRunBasic(rawArgs, ctx) {
                 }));
             }
         }
+        const changedLines = autoFixInfo
+            ? autoFixInfo.changes.map((change) => `line ${change.line}: "${change.before}" -> "${change.after}"`).join("; ")
+            : "";
         const message = autoFixInfo
-            ? "Detected BASIC errors on execution; applied auto-fix and re-ran successfully."
-            : "BASIC program uploaded and executed successfully.";
+            ? `Detected BASIC errors on execution; applied auto-fix and ran the program a second time (changed lines: ${changedLines}). The second run showed no BASIC error on screen.${verified ? "" : " Execution was not verified."}`
+            : verified
+                ? "BASIC program uploaded and executed successfully (verified)."
+                : "BASIC program uploaded and started. No BASIC error was visible on the screen immediately afterwards; pass verify:true to poll for the outcome.";
         const metadata = {
             success: true,
             entryAddress,
@@ -399,6 +415,7 @@ async function executeUploadRunBasic(rawArgs, ctx) {
                         applied: true,
                         changes: autoFixInfo.changes,
                         originalErrors: autoFixInfo.originalErrors,
+                        programSource: activeProgram,
                     },
                 }
                 : {}),
@@ -414,8 +431,10 @@ async function executeUploadRunBasic(rawArgs, ctx) {
             ...(autoFixInfo
                 ? {
                     autoFix: {
+                        applied: true,
                         changes: autoFixInfo.changes,
                         originalErrors: autoFixInfo.originalErrors,
+                        programSource: activeProgram,
                     },
                 }
                 : {}),
@@ -452,18 +471,35 @@ async function executeUploadRunAsm(rawArgs, ctx) {
                 details: extractFailureDetails(result.details),
             }));
         }
-        // Poll for ASM execution outcome
+        // Read back the program bytes (load evidence), then poll for signs of execution.
         let verified = false;
+        let execution;
+        let loadCheck;
+        const loadAddress = prg.length >= 2 ? prg.readUInt16LE(0) : 0;
         try {
-            const outcome = await pollForProgramOutcome("ASM", ctx.client, ctx.logger);
-            if (outcome.status === "crashed") {
-                ctx.logger.warn("Polling detected ASM program crash", { reason: outcome.reason });
-                return toolErrorResult(new ToolExecutionError("Assembly program appears to have crashed (no screen changes detected)", {
-                    details: { reason: outcome.reason },
-                }));
-            }
-            if (shouldVerify) {
-                verified = true;
+            const outcome = await pollForProgramOutcome("ASM", ctx.client, ctx.logger, undefined, {
+                address: loadAddress,
+                bytes: prg.subarray(2),
+            });
+            if (outcome.type === "ASM") {
+                loadCheck = outcome.loadCheck;
+                if (outcome.status === "not_loaded") {
+                    ctx.logger.warn("ASM program was not loaded", { reason: outcome.reason });
+                    return toolErrorResult(new ToolExecutionError(`Assembly program was not loaded: ${outcome.reason}. The backend reported success, but the bytes read back at the load address differ from the assembled program (a program that overwrites its own first bytes also looks like this).`, { details: { reason: outcome.reason, ...(outcome.load ? { loadAddress: outcome.load.address, expected: outcome.load.expected, found: outcome.load.found } : {}) } }));
+                }
+                if (outcome.status === "unconfirmed") {
+                    if (shouldVerify) {
+                        ctx.logger.warn("ASM execution could not be verified", { reason: outcome.reason });
+                        return toolErrorResult(new ToolExecutionError("Assembly program was loaded, but no screen change was observed, so its execution could not be verified", { details: { reason: outcome.reason, loadCheck: outcome.loadCheck, execution: "unconfirmed" } }));
+                    }
+                    execution = "unconfirmed";
+                }
+                else {
+                    execution = "confirmed";
+                    if (shouldVerify) {
+                        verified = true;
+                    }
+                }
             }
         }
         catch (pollError) {
@@ -480,13 +516,20 @@ async function executeUploadRunAsm(rawArgs, ctx) {
             entryAddress,
             prgSize: prg.length,
             resources: ["c64://assembly/6510-spec", "c64://guide/bootstrap"],
+            ...(loadCheck ? { loadCheck } : {}),
+            ...(execution ? { execution } : {}),
             ...(shouldVerify && verified ? { verified: true } : {}),
         };
-        const base = textResult("Assembly program assembled, uploaded, and executed successfully.", {
+        const message = execution === "unconfirmed"
+            ? "Assembly program assembled, uploaded and loaded. No screen change was observed, so it is not confirmed that the program is running (a SID player, a border effect or a JMP * loop looks like this)."
+            : "Assembly program assembled, uploaded, and executed successfully.";
+        const base = textResult(message, {
             success: true,
             entryAddress,
             prgSize: prg.length,
             details: result.details ?? null,
+            ...(loadCheck ? { loadCheck } : {}),
+            ...(execution ? { execution } : {}),
             ...(shouldVerify && verified ? { verified: true } : {}),
         });
         return { ...base, structuredContent: { type: "json", data } };
@@ -550,8 +593,9 @@ async function executeRunPrg(rawArgs, ctx) {
         if (ctx.platform.id === "vice") {
             clearViceSymbols();
             if (parsed.symbolsFile) {
+                const symbolsPath = resolveHostPath(parsed.symbolsFile, { purpose: "read" });
                 try {
-                    const content = await fs.promises.readFile(parsed.symbolsFile, "utf8");
+                    const content = await fs.promises.readFile(symbolsPath, "utf8");
                     const syms = parseViceSymbolFile(content);
                     setViceSymbols(syms.entries());
                     symbolsLoaded = syms.size;
@@ -718,7 +762,7 @@ export const programRunnersModule = defineToolModule({
                 "Stage PRG files without running when the user wants to inspect memory first.",
                 "Confirm the Ultimate filesystem path (e.g. //USB0/demo.prg) is accessible before invoking.",
             ],
-            supportedPlatforms: ["c64u", "u2"],
+            supportedPlatforms: ["c64u", "u2", "vice"],
             async execute(args, ctx) {
                 return executeLoadPrg(args, ctx);
             },

package/dist/tools/registry/batch.js

@@ -2,7 +2,8 @@ import { defineToolModule, } from "../types.js";
 import { getPlatformStatus } from "../../platform.js";
 import { arraySchema, booleanSchema, objectSchema, optionalSchema, stringSchema, } from "../schema.js";
 import { jsonResult } from "../responses.js";
-import { ToolValidationError, unknownErrorResult } from "../errors.js";
+import { unknownErrorResult } from "../errors.js";
+export const MAX_BATCH_COMMANDS = 64;
 const commandSchema = objectSchema({
     description: "A single batch command.",
     properties: {
@@ -23,6 +24,7 @@ const executeBatchArgsSchema = objectSchema({
         commands: arraySchema(commandSchema, {
             description: "Ordered list of commands to execute.",
             minItems: 1,
+            maxItems: MAX_BATCH_COMMANDS,
         }),
         stopOnError: optionalSchema(booleanSchema({
             description: "Halt the batch after the first failure. Default: true.",
@@ -49,6 +51,9 @@ export const batchModuleGroup = defineToolModule({
             description: "Execute multiple c64bridge tool calls in a single request. Reduces latency for multi-step workflows.",
             summary: "Runs an ordered list of tool commands and returns all results with per-command timing.",
             inputSchema: executeBatchArgsSchema.jsonSchema,
+            // Annotated as the worst case; the access check runs per command when it is dispatched.
+            effect: "destructive",
+            effectOf: () => "read",
             tags: ["batch", "orchestration", "grouped"],
             examples: [
                 {
@@ -80,6 +85,7 @@ export const batchModuleGroup = defineToolModule({
                     // Lazy import to avoid circular dependency at module-init time.
                     const { toolRegistry } = await import("./index.js");
                     const results = [];
+                    const imageBlocks = [];
                     let succeeded = 0;
                     let failed = 0;
                     const batchStart = Date.now();
@@ -120,8 +126,11 @@ export const batchModuleGroup = defineToolModule({
                             });
                             const elapsedMs = Date.now() - cmdStart;
                             const isError = toolResult.isError === true || toolResult.metadata?.success === false;
-                            const text = toolResult.content.map((c) => c.text).join("\n");
+                            const text = toolResult.content.flatMap((c) => (c.type === "text" ? [c.text] : [])).join("\n");
                             const resultPayload = toolResult.structuredContent?.data ?? text;
+                            // Image blocks (capture_frame format "png") have no text form, so they are passed through after the summary.
+                            const images = toolResult.content.filter((c) => c.type === "image");
+                            imageBlocks.push(...images);
                             if (isError) {
                                 results.push({ index: i, tool: toolName, description: label, success: false, error: text, elapsedMs });
                                 failed++;
@@ -129,13 +138,14 @@ export const batchModuleGroup = defineToolModule({
                                     break;
                             }
                             else {
-                                results.push({ index: i, tool: toolName, description: label, success: true, result: resultPayload, elapsedMs });
+                                results.push({ index: i, tool: toolName, description: label, success: true, result: resultPayload, elapsedMs, ...(images.length > 0 ? { images: images.length } : {}) });
                                 succeeded++;
                             }
                         }
                         catch (err) {
                             const elapsedMs = Date.now() - cmdStart;
-                            const message = err instanceof Error ? err.message : String(err);
+                            // Keep the validation detail (allowed values, bounds) that the CallTool error path would show.
+                            const message = unknownErrorResult(err).content.flatMap((c) => (c.type === "text" ? [c.text] : [])).join("\n");
                             results.push({ index: i, tool: toolName, description: label, success: false, error: message, elapsedMs });
                             failed++;
                             if (stopOnError)
@@ -152,15 +162,11 @@ export const batchModuleGroup = defineToolModule({
                         results,
                     };
                     ctx.logger.info("Batch complete", { total: parsed.commands.length, succeeded, failed, elapsedMs: totalElapsedMs });
-                    return jsonResult(summary, { success: failed === 0, succeeded, failed, total: parsed.commands.length });
+                    const summaryResult = jsonResult(summary, { success: failed === 0, succeeded, failed, total: parsed.commands.length });
+                    const outcome = imageBlocks.length > 0 ? { ...summaryResult, content: [...summaryResult.content, ...imageBlocks] } : summaryResult;
+                    return failed > 0 ? { ...outcome, isError: true } : outcome;
                 }
                 catch (error) {
-                    if (error instanceof ToolValidationError) {
-                        return {
-                            content: [{ type: "text", text: error.message }],
-                            isError: true,
-                        };
-                    }
                     return unknownErrorResult(error);
                 }
             },

package/dist/tools/registry/config.js

@@ -60,7 +60,7 @@ const configOperations = [
     },
     {
         op: "batch_update",
-        schema: extendSchemaWithOp("batch_update", ensureDescriptor(developerDescriptorIndex, "config_batch_update").inputSchema, { description: "Apply multiple configuration updates in a single request." }),
+        schema: extendSchemaWithOp("batch_update", ensureDescriptor(developerDescriptorIndex, "config_batch_update").inputSchema, { description: "Apply multiple configuration updates in a single request. Pass `updates` as {category: {item: value}}; categories as top-level keys are still accepted at runtime." }),
         handler: async (rawArgs, ctx) => invokeModuleTool(developerModule, "config_batch_update", rawArgs, ctx),
     },
     {
@@ -169,6 +169,13 @@ export const configModuleGroup = defineToolModule({
                 description: "Configuration operations available via the c64_config tool.",
                 variants: configOperations.map((operation) => operation.schema),
             }),
+            operationEffects: {
+                list: "read", get: "read", set: "write", batch_update: "write", load_flash: "destructive",
+                save_flash: "destructive", reset_defaults: "destructive", read_debugreg: "read",
+                write_debugreg: "destructive", info: "read", version: "read", snapshot: "write",
+                restore: "write", diff: "read", shuffle: "write",
+            },
+            effectOf: (op, args) => (op === "restore" && args.applyToFlash === true ? "destructive" : undefined),
             tags: ["config", "diagnostics", "grouped"],
             operationPlatforms: {
                 load_flash: ["c64u", "u2"],
@@ -200,7 +207,7 @@ export const configModuleGroup = defineToolModule({
                 {
                     name: "Snapshot config",
                     description: "Write configuration snapshot to disk",
-                    arguments: { op: "snapshot", path: "./snapshots/c64_json" },
+                    arguments: { op: "snapshot", path: "./snapshots/c64.json" },
                 },
             ],
             execute: createOperationDispatcher("c64_config", configOperationHandlers),

package/dist/tools/registry/disk.js

@@ -251,6 +251,11 @@ const diskOperations = [
         schema: extendSchemaWithOp("find_and_run", ensureDescriptor(metaDescriptorIndex, "find_and_run_program_by_name").inputSchema, { description: "Search for a PRG/CRT by name substring and run the first match." }),
         handler: async (rawArgs, ctx) => invokeModuleTool(metaModule, "find_and_run_program_by_name", rawArgs, ctx),
     },
+    {
+        op: "find_paths",
+        schema: extendSchemaWithOp("find_paths", ensureDescriptor(metaDescriptorIndex, "find_paths_by_name").inputSchema, { description: "Search Ultimate storage for paths whose names contain a substring, without running anything." }),
+        handler: async (rawArgs, ctx) => invokeModuleTool(metaModule, "find_paths_by_name", rawArgs, ctx),
+    },
 ];
 const diskOperationHandlers = createOperationHandlers(diskOperations);
 export const diskModuleGroup = defineToolModule({
@@ -258,7 +263,7 @@ export const diskModuleGroup = defineToolModule({
     summary: "Grouped disk image management, mounting, and discovery tools.",
     supportedPlatforms: ["c64u", "u2", "vice"],
     resources: ["c64://guide/bootstrap"],
-    prompts: ["drive-management"],
+    prompts: ["drive-manager"],
     defaultTags: ["storage", "drive"],
     workflowHints: [
         "Summarise drive state before and after mounts so the user can confirm hardware changes.",
@@ -273,14 +278,19 @@ export const diskModuleGroup = defineToolModule({
                 description: "Disk operations available via the c64_disk tool.",
                 variants: diskOperations.map((operation) => operation.schema),
             }),
+            operationEffects: {
+                list_drives: "read", mount: "write", unmount: "write", file_info: "read",
+                create_image: "destructive", find_and_run: "write", find_paths: "read",
+            },
             tags: ["storage", "drive", "grouped"],
             // The VICE Binary Monitor has no command to detach a disk image, so unmount is Ultimate-only.
-            operationPlatforms: { unmount: ["c64u", "u2"], file_info: ["c64u", "u2"], create_image: ["c64u", "u2"], find_and_run: ["c64u", "u2"] },
+            operationPlatforms: { unmount: ["c64u", "u2"], file_info: ["c64u", "u2"], create_image: ["c64u", "u2"], find_and_run: ["c64u", "u2"], find_paths: ["c64u", "u2"] },
             operationToolNames: {
                 unmount: "drive_remove",
                 file_info: "file_info",
                 create_image: "create_image",
                 find_and_run: "find_and_run_program_by_name",
+                find_paths: "find_paths_by_name",
             },
             examples: [
                 {

package/dist/tools/registry/drive.js

@@ -49,6 +49,9 @@ export const driveModuleGroup = defineToolModule({
                 description: "Drive operations available via the c64_drive tool.",
                 variants: driveOperations.map((operation) => operation.schema),
             }),
+            operationEffects: {
+                reset: "write", power_on: "write", power_off: "write", load_rom: "destructive", set_mode: "write",
+            },
             tags: ["drive", "hardware", "grouped"],
             operationPlatforms: { load_rom: ["c64u", "u2"] },
             operationToolNames: { load_rom: "drive_load_rom" },

package/dist/tools/registry/extract.js

@@ -49,6 +49,9 @@ export const extractModule = defineToolModule({
                 description: "Extraction operations available via the c64_extract tool.",
                 variants: extractOperations.map((operation) => operation.schema),
             }),
+            operationEffects: {
+                sprites: "write", charset: "write", memory_dump: "write", fs_stats: "read", firmware_health: "read",
+            },
             tags: ["extract", "diagnostics", "grouped"],
             operationPlatforms: { fs_stats: ["c64u", "u2"] },
             operationToolNames: { fs_stats: "filesystem_stats_by_extension" },

package/dist/tools/registry/graphics.js

@@ -3,8 +3,10 @@ import { createOperationDispatcher, defineToolModule, discriminatedUnionSchema,
 import { graphicsModule, graphicsOperationHandlers as groupedGraphicsHandlers } from "../graphics.js";
 import { booleanSchema, literalSchema, numberSchema, objectSchema, optionalSchema, stringSchema, } from "../schema.js";
 import { buildDescriptorIndex, ensureDescriptor, extendSchemaWithOp, createOperationHandlers, } from "./utils.js";
+import { Jimp } from "jimp";
 import { jsonResult } from "../responses.js";
-import { ToolError, toolErrorResult, unknownErrorResult, } from "../errors.js";
+import { VIC_PALETTE } from "../../vicBitmap.js";
+import { ToolError, ToolValidationError, toolErrorResult, unknownErrorResult, } from "../errors.js";
 const graphicsDescriptorIndex = buildDescriptorIndex(graphicsModule);
 const captureFrameArgsSchema = objectSchema({
     description: "Capture one or more complete video frames from the active backend.",
@@ -18,9 +20,13 @@ const captureFrameArgsSchema = objectSchema({
             default: 1,
         }), 1),
         includePixels: optionalSchema(booleanSchema({
-            description: "Include pixel payload bytes in the response.",
-            default: true,
-        }), true),
+            description: "Include raw pixel payload bytes in the response. Off by default because a frame is about 100 KB; the response is rejected above 2 MiB, so lower count when it is on.",
+            default: false,
+        }), false),
+        format: optionalSchema(stringSchema({
+            description: "Set to png to receive each frame as an MCP image block (C64 palette). At most 4 frames per call.",
+            enum: ["png"],
+        })),
         encoding: optionalSchema(stringSchema({
             description: "Encoding used for the pixel payload when included.",
             enum: ["base64", "hex"],
@@ -30,6 +36,30 @@ const captureFrameArgsSchema = objectSchema({
     required: ["op"],
     additionalProperties: false,
 });
+/** Largest raw pixel payload (encoded size, all frames) one capture_frame response may carry. */
+export const MAX_CAPTURE_PAYLOAD_BYTES = 2 * 1024 * 1024;
+export const MAX_PNG_FRAMES = 4;
+/** Renders one captured frame (one palette index per byte) as a PNG image content block. */
+export async function frameToPngContent(frame) {
+    const { width, height } = frame;
+    if (frame.bitsPerPixel > 8 || frame.pixels.length < width * height) {
+        throw new ToolValidationError("PNG output needs indexed frames with one byte per pixel; use includePixels for raw data", {
+            path: "$.format",
+            details: { bitsPerPixel: frame.bitsPerPixel, width, height, byteLength: frame.pixels.length },
+        });
+    }
+    const rgba = Buffer.alloc(width * height * 4);
+    for (let i = 0; i < width * height; i += 1) {
+        const [r, g, b] = VIC_PALETTE[frame.pixels[i] & 0x0f];
+        rgba[i * 4] = r;
+        rgba[i * 4 + 1] = g;
+        rgba[i * 4 + 2] = b;
+        rgba[i * 4 + 3] = 0xff;
+    }
+    const image = new Jimp({ width, height, data: rgba });
+    const png = await image.getBuffer("image/png");
+    return { type: "image", data: Buffer.from(png).toString("base64"), mimeType: "image/png" };
+}
 // ---------------------------------------------------------------------------
 // get_display_state helpers — VIC-II register decoding
 // ---------------------------------------------------------------------------
@@ -107,10 +137,27 @@ const graphicsOperations = [
                     count: parsed.count,
                     includePixels: parsed.includePixels,
                     encoding: parsed.encoding,
+                    format: parsed.format,
                 });
+                if (parsed.format === "png" && (parsed.count ?? 1) > MAX_PNG_FRAMES) {
+                    throw new ToolValidationError(`count must be at most ${MAX_PNG_FRAMES} when format is png`, {
+                        path: "$.count",
+                        details: { count: parsed.count, maximum: MAX_PNG_FRAMES },
+                    });
+                }
                 const capture = await ctx.client.captureFrames({ count: parsed.count });
-                const includePixels = parsed.includePixels !== false;
+                const includePixels = parsed.includePixels === true;
                 const encoding = parsed.encoding ?? "base64";
+                if (includePixels) {
+                    const rawBytes = capture.frames.reduce((sum, frame) => sum + frame.pixels.length, 0);
+                    const encodedBytes = encoding === "hex" ? rawBytes * 2 : Math.ceil(rawBytes / 3) * 4;
+                    if (encodedBytes > MAX_CAPTURE_PAYLOAD_BYTES) {
+                        throw new ToolValidationError(`Raw pixel response would be ${encodedBytes} bytes, above the ${MAX_CAPTURE_PAYLOAD_BYTES} byte limit; lower count or use format png`, { path: "$.count", details: { count: parsed.count, encodedBytes, limitBytes: MAX_CAPTURE_PAYLOAD_BYTES } });
+                    }
+                }
+                const images = parsed.format === "png"
+                    ? await Promise.all(capture.frames.map((frame) => frameToPngContent(frame)))
+                    : [];
                 const frames = capture.frames.map((frame, index) => {
                     const pixels = includePixels
                         ? {
@@ -131,7 +178,7 @@ const graphicsOperations = [
                         ...(pixels ? { pixels } : {}),
                     };
                 });
-                return jsonResult({
+                const result = jsonResult({
                     backend: capture.backend,
                     count: frames.length,
                     frames,
@@ -141,7 +188,9 @@ const graphicsOperations = [
                     count: frames.length,
                     includePixels,
                     encoding: includePixels ? encoding : null,
+                    format: parsed.format ?? null,
                 });
+                return images.length > 0 ? { ...result, content: [...result.content, ...images] } : result;
             }
             catch (error) {
                 if (error instanceof ToolError) {
@@ -223,6 +272,10 @@ export const graphicsModuleGroup = defineToolModule({
                 description: "Graphics operations available via the c64_graphics tool.",
                 variants: graphicsOperations.map((operation) => operation.schema),
             }),
+            operationEffects: {
+                capture_frame: "read", render_petscii_art: "write", render_petscii_text: "write",
+                render_sprite: "write", render_bitmap: "write", get_display_state: "read",
+            },
             tags: ["graphics", "vic", "grouped"],
             examples: [
                 {

package/dist/tools/registry/index.js

@@ -1,3 +1,5 @@
+import { ToolValidationError } from "../errors.js";
+import { assertAccess } from "../access.js";
 import { getPlatformStatus, setPlatform } from "../../platform.js";
 import { programModule } from "./program.js";
 import { memoryModuleGroup as memoryModule } from "./memory.js";
@@ -56,11 +58,25 @@ export const toolRegistry = {
         };
         const entry = toolMap.get(name);
         if (!entry) {
-            throw new Error(`Unknown tool: ${name}`);
+            const allowed = Array.from(toolMap.keys()).sort();
+            throw new ToolValidationError(`Unknown tool: ${name}`, {
+                path: "$.name",
+                details: { allowed, received: name },
+            });
+        }
+        // Single enforcement point for C64BRIDGE_ACCESS. Batch commands and background task starts
+        // also arrive here (the batch tool and c64_system start_task declare their effect per call).
+        const effect = entry.module.effectOf ? entry.module.effectOf(name, args) : "destructive";
+        if (effect) {
+            assertAccess(name, getOperation(args), effect);
         }
         return entry.module.invoke(name, args, enrichedCtx);
     },
 };
+function getOperation(args) {
+    const op = typeof args === "object" && args !== null ? args.op : undefined;
+    return typeof op === "string" && op.length > 0 ? op : undefined;
+}
 export function describeToolModules() {
     return modules.map((module) => ({
         domain: module.domain,