c64bridge 0.9.0 → 0.9.2

package/dist/tools/memory.js

@@ -1,8 +1,13 @@
 import { Buffer } from "node:buffer";
+import fs from "node:fs";
+import path from "node:path";
 import { defineToolModule, OPERATION_DISCRIMINATOR, } from "./types.js";
 import { booleanSchema, numberSchema, objectSchema, optionalSchema, stringSchema } from "./schema.js";
-import { textResult } from "./responses.js";
+import { jsonResult, textResult } from "./responses.js";
 import { ToolError, ToolExecutionError, ToolValidationError, toolErrorResult, unknownErrorResult, } from "./errors.js";
+import { disassemble, formatDisassembly } from "./translation/disassembler.js";
+import { getViceSymbols } from "./translation/symbolRegistry.js";
+import { resolveAddressSymbol } from "../knowledge.js";
 function toRecord(details) {
     if (details && typeof details === "object") {
         return details;
@@ -34,6 +39,12 @@ function parseHexInternal(value, path) {
     if (cleaned.length === 0) {
         return { bytes: new Uint8Array(), canonical: "$" };
     }
+    if (!/^[0-9A-F]+$/.test(cleaned)) {
+        throw new ToolValidationError("Hex string contains non-hexadecimal characters", {
+            path,
+            details: { value },
+        });
+    }
     const bytes = Uint8Array.from(Buffer.from(cleaned, "hex"));
     return { bytes, canonical: `$${cleaned}` };
 }
@@ -79,6 +90,18 @@ function supportsMachinePause(ctx) {
     const platformId = ctx.platform?.id;
     return platformId !== "vice";
 }
+export const __memoryHelpersForTests = {
+    toRecord,
+    normaliseFailure,
+    cleanHex,
+    parseUserHex,
+    parseFirmwareHex,
+    formatByte,
+    resolveAddressLabel,
+    resolveLength,
+    supportsMachinePause,
+    stripOperationDiscriminator,
+};
 const readScreenArgsSchema = objectSchema({
     description: "No arguments are required for reading the current screen contents.",
     properties: {},
@@ -352,11 +375,313 @@ async function executeWriteMemory(rawArgs, ctx) {
         return unknownErrorResult(error);
     }
 }
+const disassembleArgsSchema = objectSchema({
+    description: "Parameters for disassembling a block of VICE memory into 6502/6510 instructions.",
+    properties: {
+        address: stringSchema({
+            description: "Start address as $HHHH, decimal, or symbol name.",
+            minLength: 1,
+        }),
+        length: numberSchema({
+            description: "Number of bytes to read and disassemble.",
+            integer: true,
+            minimum: 1,
+            maximum: 4096,
+            default: 64,
+        }),
+        instructionCount: optionalSchema(numberSchema({
+            description: "Stop after this many instructions (overrides length as a termination condition).",
+            integer: true,
+            minimum: 1,
+            maximum: 512,
+        })),
+    },
+    required: ["address"],
+    additionalProperties: false,
+});
+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");
+        validateRangeWithinAddressSpace(address, length, "$.address");
+        const bytes = await ctx.client.readMemoryRaw(address, length);
+        const symbols = ctx.platform?.id === "vice" ? getViceSymbols() : undefined;
+        const lines = disassemble(bytes, address, parsed.instructionCount, symbols);
+        const text = formatDisassembly(lines);
+        const addrHex = `$${address.toString(16).toUpperCase().padStart(4, "0")}`;
+        return textResult(`Disassembly of ${lines.length} instructions starting at ${addrHex}:\n\n${text}`, {
+            success: true,
+            address: addrHex,
+            bytesRead: bytes.length,
+            instructionCount: lines.length,
+        });
+    }
+    catch (error) {
+        if (error instanceof ToolError) {
+            return toolErrorResult(error);
+        }
+        return unknownErrorResult(error);
+    }
+}
+// ---------------------------------------------------------------------------
+// Shared address-parsing helper
+// ---------------------------------------------------------------------------
+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 {
+        const resolved = resolveAddressSymbol(trimmed);
+        if (resolved === undefined) {
+            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 });
+    }
+    return addr;
+}
+function fmtAddr(addr) {
+    return `$${addr.toString(16).toUpperCase().padStart(4, "0")}`;
+}
+function validateRangeWithinAddressSpace(start, length, fieldPath) {
+    const end = start + length - 1;
+    if (end > 0xffff) {
+        throw new ToolValidationError(`${fieldPath} range exceeds address space; ${fmtAddr(start)} + ${length} bytes would pass $FFFF.`, { path: fieldPath });
+    }
+}
+// ---------------------------------------------------------------------------
+// copy_memory
+// ---------------------------------------------------------------------------
+const copyMemoryArgsSchema = objectSchema({
+    description: "Copy a region of RAM from one address to another.",
+    properties: {
+        source: stringSchema({ description: "Source start address ($HHHH, decimal, or symbol).", minLength: 1 }),
+        dest: stringSchema({ description: "Destination start address.", minLength: 1 }),
+        length: numberSchema({ description: "Number of bytes to copy (1–16384).", integer: true, minimum: 1, maximum: 16384 }),
+    },
+    required: ["source", "dest", "length"],
+    additionalProperties: false,
+});
+async function executeCopyMemory(rawArgs, ctx) {
+    try {
+        const parsed = copyMemoryArgsSchema.parse(rawArgs ?? {});
+        const src = parseAddressArg(parsed.source, "$.source");
+        const dst = parseAddressArg(parsed.dest, "$.dest");
+        const len = parsed.length;
+        validateRangeWithinAddressSpace(src, len, "$.source");
+        validateRangeWithinAddressSpace(dst, len, "$.dest");
+        ctx.logger.info("Copying memory", { src: fmtAddr(src), dst: fmtAddr(dst), len });
+        const bytes = await ctx.client.readMemoryRaw(src, len);
+        await ctx.client.writeMemoryRaw(dst, bytes);
+        return textResult(`Copied ${bytes.length} bytes from ${fmtAddr(src)} to ${fmtAddr(dst)}.`, {
+            success: true, source: fmtAddr(src), dest: fmtAddr(dst), bytesCopied: bytes.length,
+        });
+    }
+    catch (error) {
+        if (error instanceof ToolError)
+            return toolErrorResult(error);
+        return unknownErrorResult(error);
+    }
+}
+// ---------------------------------------------------------------------------
+// fill_memory
+// ---------------------------------------------------------------------------
+const fillMemoryArgsSchema = objectSchema({
+    description: "Fill a memory region with a repeating byte pattern.",
+    properties: {
+        address: stringSchema({ description: "Start address ($HHHH, decimal, or symbol).", minLength: 1 }),
+        length: numberSchema({ description: "Number of bytes to fill (1–16384).", integer: true, minimum: 1, maximum: 16384 }),
+        pattern: stringSchema({
+            description: "Hex bytes to repeat, e.g. 'FF' or 'AA 55'. Space-separated or run together.",
+            minLength: 2,
+            pattern: /^[\s0-9A-Fa-f$]+$/,
+        }),
+    },
+    required: ["address", "length", "pattern"],
+    additionalProperties: false,
+});
+async function executeFillMemory(rawArgs, ctx) {
+    try {
+        const parsed = fillMemoryArgsSchema.parse(rawArgs ?? {});
+        const addr = parseAddressArg(parsed.address, "$.address");
+        validateRangeWithinAddressSpace(addr, parsed.length, "$.address");
+        const { bytes: patternBytes } = parseUserHex(parsed.pattern, "$.pattern");
+        if (patternBytes.length === 0)
+            throw new ToolValidationError("Pattern must not be empty", { path: "$.pattern" });
+        const buf = new Uint8Array(parsed.length);
+        for (let i = 0; i < parsed.length; i++)
+            buf[i] = patternBytes[i % patternBytes.length];
+        await ctx.client.writeMemoryRaw(addr, buf);
+        ctx.logger.info("Filled memory", { address: fmtAddr(addr), length: parsed.length, pattern: parsed.pattern });
+        return textResult(`Filled ${parsed.length} bytes at ${fmtAddr(addr)} with pattern ${parsed.pattern.trim()}.`, {
+            success: true, address: fmtAddr(addr), length: parsed.length, pattern: parsed.pattern.trim(),
+        });
+    }
+    catch (error) {
+        if (error instanceof ToolError)
+            return toolErrorResult(error);
+        return unknownErrorResult(error);
+    }
+}
+// ---------------------------------------------------------------------------
+// search_memory
+// ---------------------------------------------------------------------------
+const searchMemoryArgsSchema = objectSchema({
+    description: "Search for a byte pattern within a memory range.",
+    properties: {
+        startAddress: stringSchema({ description: "Start of search range ($HHHH, decimal, or symbol).", minLength: 1 }),
+        endAddress: stringSchema({ description: "End of search range (inclusive).", minLength: 1 }),
+        pattern: stringSchema({
+            description: "Hex bytes to find, e.g. 'A9 00' for LDA #$00.",
+            minLength: 2,
+            pattern: /^[\s0-9A-Fa-f$]+$/,
+        }),
+        maxResults: optionalSchema(numberSchema({ description: "Maximum matches to return (default 10).", integer: true, minimum: 1, maximum: 100, default: 10 })),
+    },
+    required: ["startAddress", "endAddress", "pattern"],
+    additionalProperties: false,
+});
+async function executeSearchMemory(rawArgs, ctx) {
+    try {
+        const parsed = searchMemoryArgsSchema.parse(rawArgs ?? {});
+        const start = parseAddressArg(parsed.startAddress, "$.startAddress");
+        const end = parseAddressArg(parsed.endAddress, "$.endAddress");
+        if (end < start)
+            throw new ToolValidationError("endAddress must be ≥ startAddress", { path: "$.endAddress" });
+        const { bytes: needle } = parseUserHex(parsed.pattern, "$.pattern");
+        if (needle.length === 0)
+            throw new ToolValidationError("Pattern must not be empty", { path: "$.pattern" });
+        const maxResults = parsed.maxResults ?? 10;
+        const len = end - start + 1;
+        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++) {
+            for (let j = 0; j < needle.length; j++) {
+                if (haystack[i + j] !== needle[j])
+                    continue outer;
+            }
+            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 });
+    }
+    catch (error) {
+        if (error instanceof ToolError)
+            return toolErrorResult(error);
+        return unknownErrorResult(error);
+    }
+}
+// ---------------------------------------------------------------------------
+// compare_memory
+// ---------------------------------------------------------------------------
+const compareMemoryArgsSchema = objectSchema({
+    description: "Compare two memory regions and report differing bytes.",
+    properties: {
+        address1: stringSchema({ description: "First region start address.", minLength: 1 }),
+        address2: stringSchema({ description: "Second region start address.", minLength: 1 }),
+        length: numberSchema({ description: "Number of bytes to compare (1–16384).", integer: true, minimum: 1, maximum: 16384 }),
+        maxDiffs: optionalSchema(numberSchema({ description: "Max differences to report (default 10).", integer: true, minimum: 1, maximum: 200, default: 10 })),
+    },
+    required: ["address1", "address2", "length"],
+    additionalProperties: false,
+});
+async function executeCompareMemory(rawArgs, ctx) {
+    try {
+        const parsed = compareMemoryArgsSchema.parse(rawArgs ?? {});
+        const a1 = parseAddressArg(parsed.address1, "$.address1");
+        const a2 = parseAddressArg(parsed.address2, "$.address2");
+        const len = parsed.length;
+        const maxDiffs = parsed.maxDiffs ?? 10;
+        validateRangeWithinAddressSpace(a1, len, "$.address1");
+        validateRangeWithinAddressSpace(a2, len, "$.address2");
+        ctx.logger.info("Comparing memory regions", { a1: fmtAddr(a1), a2: fmtAddr(a2), len });
+        const [r1, r2] = await Promise.all([
+            ctx.client.readMemoryRaw(a1, len),
+            ctx.client.readMemoryRaw(a2, len),
+        ]);
+        const diffs = [];
+        for (let i = 0; i < len && diffs.length < maxDiffs; i++) {
+            if (r1[i] !== r2[i]) {
+                diffs.push({
+                    offset: i,
+                    address1: fmtAddr(a1 + i),
+                    address2: fmtAddr(a2 + i),
+                    value1: formatByte(r1[i] ?? 0),
+                    value2: formatByte(r2[i] ?? 0),
+                });
+            }
+        }
+        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 });
+    }
+    catch (error) {
+        if (error instanceof ToolError)
+            return toolErrorResult(error);
+        return unknownErrorResult(error);
+    }
+}
+// ---------------------------------------------------------------------------
+// save_memory
+// ---------------------------------------------------------------------------
+const saveMemoryArgsSchema = objectSchema({
+    description: "Dump a memory region to a local file, optionally with a PRG load-address header.",
+    properties: {
+        startAddress: stringSchema({ description: "Start address of region to save.", minLength: 1 }),
+        endAddress: stringSchema({ description: "End address (inclusive).", minLength: 1 }),
+        filePath: stringSchema({ description: "Absolute or relative path for the output file.", minLength: 1 }),
+        asPrg: optionalSchema(booleanSchema({ description: "Prepend a 2-byte little-endian load-address header (PRG format). Default: true.", default: true })),
+    },
+    required: ["startAddress", "endAddress", "filePath"],
+    additionalProperties: false,
+});
+async function executeSaveMemory(rawArgs, ctx) {
+    try {
+        const parsed = saveMemoryArgsSchema.parse(rawArgs ?? {});
+        const start = parseAddressArg(parsed.startAddress, "$.startAddress");
+        const end = parseAddressArg(parsed.endAddress, "$.endAddress");
+        if (end < start)
+            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);
+        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);
+        await fs.promises.mkdir(path.dirname(resolvedPath), { recursive: true });
+        await fs.promises.writeFile(resolvedPath, Buffer.concat([header, Buffer.from(bytes)]));
+        const fileSize = bytes.length + header.length;
+        return textResult(`Saved ${bytes.length} bytes (${fmtAddr(start)}–${fmtAddr(end)}) to ${resolvedPath}${asPrg ? " (PRG, with load address header)" : ""}.`, { success: true, filePath: resolvedPath, bytesRead: bytes.length, fileSize, asPrg, startAddress: fmtAddr(start), endAddress: fmtAddr(end) });
+    }
+    catch (error) {
+        if (error instanceof ToolError)
+            return toolErrorResult(error);
+        return unknownErrorResult(error);
+    }
+}
 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),
+    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),
+    search_memory: async (args, ctx) => executeSearchMemory(stripOperationDiscriminator(args), ctx),
+    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 const memoryModule = defineToolModule({
     domain: "memory",
     summary: "Screen, main memory, and low-level inspection utilities.",

package/dist/tools/programRunners.js

@@ -1,10 +1,12 @@
-import { assemblyToPrg, AssemblyError } from "../assemblyConverter.js";
-import { basicToPrg } from "../basicConverter.js";
+import fs from "node:fs";
+import { assemblyToPrgDetailed, AssemblyError } from "./translation/assembler.js";
+import { basicToPrg } from "./translation/basicTokenizer.js";
 import { defineToolModule, OPERATION_DISCRIMINATOR, } from "./types.js";
-import { booleanSchema, objectSchema, stringSchema } from "./schema.js";
+import { booleanSchema, objectSchema, optionalSchema, stringSchema } from "./schema.js";
 import { textResult } from "./responses.js";
 import { ToolExecutionError, ToolError, ToolValidationError, toolErrorResult, unknownErrorResult, } from "./errors.js";
 import { pollForProgramOutcome } from "./pollValidator.js";
+import { clearViceSymbols, setViceSymbols, parseViceSymbolFile } from "./translation/symbolRegistry.js";
 function extractFailureDetails(details) {
     if (details === undefined || details === null) {
         return undefined;
@@ -163,6 +165,14 @@ function normalizeRuntimeErrors(errors) {
         text: error.raw,
     }));
 }
+export const __programRunnerHelpersForTests = {
+    extractFailureDetails,
+    toRecord,
+    stripOperationDiscriminator,
+    parseBasicRuntimeErrors,
+    attemptAutoFixBasicProgram,
+    normalizeRuntimeErrors,
+};
 function structuredExecutionError(message, data) {
     return {
         content: [
@@ -221,6 +231,10 @@ const prgFileArgsSchema = objectSchema({
             description: prgPathDescription,
             minLength: 1,
         }),
+        symbolsFile: optionalSchema(stringSchema({
+            description: "Path to a VICE symbol file (.vs) to load alongside the PRG. Symbols are used by the disassemble tool when annotating addresses.",
+            minLength: 1,
+        })),
     },
     required: ["path"],
     additionalProperties: false,
@@ -424,9 +438,13 @@ async function executeUploadRunAsm(rawArgs, ctx) {
             sourceLength: parsed.program.length,
             ...(shouldVerify ? { verify: true } : {}),
         });
-        // Assemble locally to expose structured metadata
-        const prg = assemblyToPrg(parsed.program);
+        // Assemble locally to expose structured metadata and capture symbols
+        const asmResult = assemblyToPrgDetailed(parsed.program);
+        const prg = asmResult.prg;
         const entryAddress = prg.readUInt16LE(0);
+        if (ctx.platform.id === "vice") {
+            setViceSymbols(asmResult.symbols.entries());
+        }
         const result = await ctx.client.uploadAndRunAsm(parsed.program);
         if (!result.success) {
             return toolErrorResult(new ToolExecutionError("C64 firmware reported failure while running assembly program", {
@@ -527,6 +545,24 @@ async function executeRunPrg(rawArgs, ctx) {
     try {
         const parsed = prgFileArgsSchema.parse(rawArgs ?? {});
         ctx.logger.info("Running PRG file", { path: parsed.path });
+        let symbolsLoaded = 0;
+        if (ctx.platform.id === "vice") {
+            clearViceSymbols();
+            if (parsed.symbolsFile) {
+                try {
+                    const content = await fs.promises.readFile(parsed.symbolsFile, "utf8");
+                    const syms = parseViceSymbolFile(content);
+                    setViceSymbols(syms.entries());
+                    symbolsLoaded = syms.size;
+                    ctx.logger.info("Loaded VICE symbols from file", { path: parsed.symbolsFile, count: symbolsLoaded });
+                }
+                catch (fileError) {
+                    throw new ToolExecutionError(`Failed to read symbols file: ${parsed.symbolsFile}`, {
+                        details: { message: fileError instanceof Error ? fileError.message : String(fileError) },
+                    });
+                }
+            }
+        }
         const result = await ctx.client.runPrgFile(parsed.path);
         if (!result.success) {
             throw new ToolExecutionError("C64 firmware reported failure while running PRG", {
@@ -539,12 +575,15 @@ async function executeRunPrg(rawArgs, ctx) {
             path: parsed.path,
             entryAddress: null,
             resources: ["c64://guide/bootstrap"],
+            ...(symbolsLoaded > 0 ? { symbolsLoaded } : {}),
         };
-        const base = textResult(`PRG ${parsed.path} loaded and executed.`, {
+        const symbolNote = symbolsLoaded > 0 ? ` Loaded ${symbolsLoaded} debug symbol(s).` : "";
+        const base = textResult(`PRG ${parsed.path} loaded and executed.${symbolNote}`, {
             success: true,
             path: parsed.path,
             entryAddress: null,
             details: toRecord(result.details) ?? null,
+            ...(symbolsLoaded > 0 ? { symbolsLoaded } : {}),
         });
         return { ...base, structuredContent: { type: "json", data } };
     }

package/dist/tools/registry/batch.js

@@ -0,0 +1,167 @@
+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";
+const commandSchema = objectSchema({
+    description: "A single batch command.",
+    properties: {
+        tool: stringSchema({ description: "MCP tool name (e.g. c64_memory, c64_debug).", minLength: 1 }),
+        args: objectSchema({
+            description: "Arguments to pass to the tool (must include 'op' for grouped tools).",
+            properties: {},
+            additionalProperties: true,
+        }),
+        description: optionalSchema(stringSchema({ description: "Optional label for this command in the result.", maxLength: 128 })),
+    },
+    required: ["tool", "args"],
+    additionalProperties: false,
+});
+const executeBatchArgsSchema = objectSchema({
+    description: "Execute multiple tool calls in one request.",
+    properties: {
+        commands: arraySchema(commandSchema, {
+            description: "Ordered list of commands to execute.",
+            minItems: 1,
+        }),
+        stopOnError: optionalSchema(booleanSchema({
+            description: "Halt the batch after the first failure. Default: true.",
+            default: true,
+        })),
+    },
+    required: ["commands"],
+    additionalProperties: false,
+});
+export const batchModuleGroup = defineToolModule({
+    domain: "batch",
+    summary: "Execute multiple tool calls in a single MCP request for reduced round-trip overhead.",
+    supportedPlatforms: ["c64u", "vice"],
+    resources: [],
+    prompts: [],
+    defaultTags: ["batch", "orchestration"],
+    workflowHints: [
+        "Use execute_batch when you need to run 3 or more sequential operations — it eliminates per-call network overhead.",
+        "Each command must include 'tool' and 'args'; grouped tools require 'op' inside args.",
+    ],
+    tools: [
+        {
+            name: "c64_batch",
+            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,
+            tags: ["batch", "orchestration", "grouped"],
+            examples: [
+                {
+                    name: "Read registers then step",
+                    description: "Get registers, step one instruction, get registers again",
+                    arguments: {
+                        commands: [
+                            { tool: "c64_debug", args: { op: "get_registers" }, description: "before" },
+                            { tool: "c64_debug", args: { op: "step", count: 1 }, description: "step" },
+                            { tool: "c64_debug", args: { op: "get_registers" }, description: "after" },
+                        ],
+                    },
+                },
+                {
+                    name: "Clear screen and type text",
+                    description: "Fill screen RAM then feed keyboard",
+                    arguments: {
+                        commands: [
+                            { tool: "c64_memory", args: { op: "fill_memory", address: "$0400", length: 1000, pattern: "20" } },
+                            { tool: "c64_input", args: { op: "write_text", text: "HELLO{RETURN}" } },
+                        ],
+                    },
+                },
+            ],
+            execute: async (rawArgs, ctx) => {
+                try {
+                    const parsed = executeBatchArgsSchema.parse(rawArgs);
+                    const stopOnError = parsed.stopOnError !== false;
+                    // Lazy import to avoid circular dependency at module-init time.
+                    const { toolRegistry } = await import("./index.js");
+                    const results = [];
+                    let succeeded = 0;
+                    let failed = 0;
+                    const batchStart = Date.now();
+                    for (let i = 0; i < parsed.commands.length; i++) {
+                        const cmd = parsed.commands[i];
+                        const toolName = typeof cmd.tool === "string" ? cmd.tool : "";
+                        const args = (typeof cmd.args === "object" && cmd.args !== null) ? cmd.args : {};
+                        const label = typeof cmd.description === "string" ? cmd.description : undefined;
+                        if (!toolName) {
+                            const err = { index: i, tool: String(cmd.tool), description: label, success: false, error: "tool name must be a non-empty string", elapsedMs: 0 };
+                            results.push(err);
+                            failed++;
+                            if (stopOnError)
+                                break;
+                            continue;
+                        }
+                        if (toolName === "c64_batch") {
+                            results.push({
+                                index: i,
+                                tool: toolName,
+                                description: label,
+                                success: false,
+                                error: "Nested c64_batch execution is not supported.",
+                                elapsedMs: 0,
+                            });
+                            failed++;
+                            if (stopOnError)
+                                break;
+                            continue;
+                        }
+                        const cmdStart = Date.now();
+                        try {
+                            const toolResult = await toolRegistry.invoke(toolName, args, {
+                                ...ctx,
+                                platform: getPlatformStatus(),
+                            });
+                            const elapsedMs = Date.now() - cmdStart;
+                            const isError = toolResult.isError === true;
+                            const text = toolResult.content.map((c) => c.text).join("\n");
+                            const resultPayload = toolResult.structuredContent?.data ?? text;
+                            if (isError) {
+                                results.push({ index: i, tool: toolName, description: label, success: false, error: text, elapsedMs });
+                                failed++;
+                                if (stopOnError)
+                                    break;
+                            }
+                            else {
+                                results.push({ index: i, tool: toolName, description: label, success: true, result: resultPayload, elapsedMs });
+                                succeeded++;
+                            }
+                        }
+                        catch (err) {
+                            const elapsedMs = Date.now() - cmdStart;
+                            const message = err instanceof Error ? err.message : String(err);
+                            results.push({ index: i, tool: toolName, description: label, success: false, error: message, elapsedMs });
+                            failed++;
+                            if (stopOnError)
+                                break;
+                        }
+                    }
+                    const totalElapsedMs = Date.now() - batchStart;
+                    const summary = {
+                        total: parsed.commands.length,
+                        executed: results.length,
+                        succeeded,
+                        failed,
+                        elapsedMs: totalElapsedMs,
+                        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 });
+                }
+                catch (error) {
+                    if (error instanceof ToolValidationError) {
+                        return {
+                            content: [{ type: "text", text: error.message }],
+                            isError: true,
+                        };
+                    }
+                    return unknownErrorResult(error);
+                }
+            },
+        },
+    ],
+});