@henols/c64-re-tools 2.0.0-rc.3 → 2.0.0-rc.5

package/README.md

@@ -19,7 +19,7 @@ The design is in [`docs/redesign/`](docs/redesign/README.md), and
 
 ## Install
 
-You need Node.js 24 or newer, and VICE 3.9 or later (`x64sc`, `c1541`, `petcat`) with its ROM files. ACME, DXA and Ghidra are needed only for the skills that use them.
+You need Node.js 24 or newer, and VICE 3.9 or later (`x64sc`, `c1541`, `petcat`) with its ROM files; use the latest VICE release. `status` and the host name the known flaws of an older VICE. ACME, DXA and Ghidra are needed only for the skills that use them: [docs/install-tools.md](docs/install-tools.md) has the steps for each system.
 
 Start the Host Runtime and leave it running:
 
@@ -39,6 +39,21 @@ claude
 
 Until 2.0.0 is released, `@latest` is the old 1.1.0. Use the prerelease instead. For the prerelease, a dev container and debugging, see [docs/debug-install.md](docs/debug-install.md).
 
+### Dev container
+
+The agent runs in the container, VICE and the Host Runtime on the host. In `.devcontainer/devcontainer.json`:
+
+```json
+"features": {
+  "https://github.com/henols/c64-re-tools/releases/latest/download/devcontainer-feature-c64-re-tools.tgz": { "target": "claude" }
+},
+"runArgs": ["--add-host=host.docker.internal:host-gateway"]
+```
+
+Until 2.0.0 is released, the `latest` URL has no Feature. Use the prerelease: `https://github.com/henols/c64-re-tools/releases/download/v2.0.0-rc.4/devcontainer-feature-c64-re-tools.tgz` with `{ "target": "claude", "channel": "next" }`.
+
+The Feature installs ACME, dxa, Java 21 and Ghidra, puts the toolkit into the project when the container is created, and updates it at each start. `target` is a harness or a comma list. `channel` is `latest` (default) or `next`. Debian and Ubuntu images only. `runArgs` is for Docker on Linux. Start the Host Runtime on the host as above.
+
 ### Settings
 
 | Variable | Read by | Meaning |
@@ -57,8 +72,6 @@ and settings stay unchanged.
 
 ## Use it with an agent
 
-## Use it with an agent
-
 1. Install for your harness: `--target claude`, `codex`, `pi`, `opencode`, `gemini`, `copilot`, `cursor` or `windsurf`. Without `--target`, `install` installs for all of them.
 2. Start the Host Runtime and leave it running.
 3. Start the harness in the project, for example `claude` or `codex`, or open the project in Cursor or Windsurf. The harness starts the MCP server and finds the skills by itself.
@@ -93,6 +106,7 @@ The agent keeps what it learns about the program in `.c64-re-tools/knowledge.db`
 | c64-unpacker | Packing evidence, and capture of the unpacked program from the emulator. |
 | c64-memory-map | Platform meaning of addresses and register values. |
 | c64-provenance | Byte comparison of releases. |
+| c64-source | ACME source from the image and the knowledge, checked byte by byte, and a loader for the entry state. |
 | c64-assembler | ACME builds with diagnostics and symbols. |
 | c64-testing | Original-against-rebuild scenarios with PASS, FAIL or INCONCLUSIVE. |
 

package/distribution/package.ts

@@ -2,22 +2,7 @@
 // only reads package.json, so a caller that needs the declaration does not
 // build the plugin.
 
-import { readFileSync } from "node:fs";
-import { join } from "node:path";
-
-/**
- * The npm dist-tag that a version is published under: a prerelease
- * (2.0.0-rc.1) goes to "next", a release to "latest".
- */
-export function channelOf(version: string): "latest" | "next" {
-  return version.includes("-") ? "next" : "latest";
-}
-
-/** The name, version and dist-tag of this npm package, from its package.json. */
-export const PACKAGE = (() => {
-  const metadata = JSON.parse(readFileSync(join(import.meta.dirname, "..", "package.json"), "utf8")) as { name: string; version: string };
-  return { name: metadata.name, version: metadata.version, tag: channelOf(metadata.version) };
-})();
+import { PACKAGE } from "../src/package.ts";
 
 /**
  * The agent starts the MCP server through npx with the newest version of the

package/distribution/plugin.ts

@@ -13,7 +13,8 @@ import { dirname, join, relative, resolve, sep } from "node:path";
 
 import { definePlugin, defineSkill, type Skill } from "@jalco/ap-sdk";
 
-import { MCP_SERVER, PACKAGE } from "./package.ts";
+import { PACKAGE } from "../src/package.ts";
+import { MCP_SERVER } from "./package.ts";
 
 const root = resolve(import.meta.dirname, "..");
 const SOURCE = join(root, "src");
@@ -27,9 +28,10 @@ const SPECIFIER = /(?:\bfrom\s*|\bimport\s*\(?\s*|\bnew URL\(\s*)(["'])((?:\.\.?
 
 /**
  * The package.json of an installed skill: ES modules, #src/* resolved inside
- * the skill, and the version of c64-re-tools that the copy comes from.
+ * the skill, and the name and version of c64-re-tools that the copy comes
+ * from, which src/package.ts reads.
  */
-export const SKILL_PACKAGE = `${JSON.stringify({ type: "module", version: PACKAGE.version, imports: { "#src/*": "./src/*" } }, null, 2)}\n`;
+export const SKILL_PACKAGE = `${JSON.stringify({ name: PACKAGE.name, type: "module", version: PACKAGE.version, imports: { "#src/*": "./src/*" } }, null, 2)}\n`;
 
 /** The scripts that a SKILL.md runs, by file name. */
 export function scriptsOf(skillMarkdown: string): string[] {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@henols/c64-re-tools",
-  "version": "2.0.0-rc.3",
+  "version": "2.0.0-rc.5",
   "description": "Agent-friendly Commodore 64 engineering toolkit for reverse engineering, debugging, development and testing.",
   "license": "MIT",
   "author": "Henrik Olsson",

package/skills/c64-assembler/SKILL.md

@@ -31,6 +31,7 @@ node <skill>/scripts/assemble.ts --source-root src --entry main.a --out build/ga
 | `--include lib` | An include directory, relative to the source root. Use it again for more directories. |
 | `--define DEBUG=1` | An assembler symbol: an integer, also as `$` hex, or `true` or `false`. Use it again for more symbols. |
 | `--set-pc '$0801'` | The start address when the source does not set one. |
+| `--compare unpacked/image.json` | Check the program byte by byte against a reference. The reference is the `image.json` of the c64-unpacker skill, a PRG, or 64 KiB of memory. |
 
 The script copies the full source root. Put all files that the program includes under it. Version control directories stay out.
 
@@ -59,12 +60,14 @@ A symbol from the rebuilt source can give the address of a routine in the rebuil
 
 The PRG in the project at the output path, with its load range and symbols. Or the source diagnostics when the assembly failed.
 
-The exit status is 0 for a PRG. The exit status is 1 for `assembled: false` and for an error. The exit status is 2 for a wrong argument.
+With `--compare`, `compare` gives `identical` and one check for each segment of the reference. A check is `identical`, `different` with the first different address, or `not covered` when the program does not hold the segment.
+
+The exit status is 0 for a PRG. The exit status is 1 for `assembled: false`, for a `--compare` that is not identical, and for an error. The exit status is 2 for a wrong argument.
 
 ## Failure and conflicts
 
 - `assembled: false`: the source has errors. This is a normal result. Correct the source.
-- `installation-incomplete`: ACME is not installed on this machine. Tell the user the message.
+- `installation-incomplete`, or a message that the host runtime does not run: stop the task. Give the message to the user and wait for the user. The message gives the remedy. Do not make a replacement for the tool or the host runtime, for example your own disk parser, disassembler or emulator script.
 - `invalid-input`: an option or a path is wrong. Read the message and correct the call.
 
 ## Handoffs

package/skills/c64-assembler/scripts/assemble.ts

@@ -12,6 +12,7 @@ import { localToolContext } from "#src/native/local.ts";
 import type { AcmeParams } from "#src/native/types.ts";
 import { resolveProjectPath } from "#src/project.ts";
 import { runScript, UsageError } from "#src/script.ts";
+import { compareBuild } from "./compare.ts";
 
 const USAGE = `assemble.ts --source-root <dir> --entry <file> --out <file.prg> [options]
 
@@ -21,6 +22,8 @@ const USAGE = `assemble.ts --source-root <dir> --entry <file> --out <file.prg> [
   --include <dir>          include directory relative to the source root (repeatable)
   --define NAME=VALUE      assembler symbol: an integer ($hex allowed) or true/false (repeatable)
   --set-pc <address>       start address when the source sets none, for example '$0801'
+  --compare <file>         check the program byte by byte against an image.json of the
+                           c64-unpacker skill (each segment), a PRG, or 64 KiB of memory
 
 The result is one JSON object. Addresses are $ and four hex digits.`;
 
@@ -45,6 +48,7 @@ async function run(argv: string[]): Promise<{ output: unknown; failed: boolean }
       include: { type: "string", multiple: true },
       define: { type: "string", multiple: true },
       "set-pc": { type: "string" },
+      compare: { type: "string" },
       help: { type: "boolean" },
     },
   });
@@ -77,6 +81,7 @@ async function run(argv: string[]): Promise<{ output: unknown; failed: boolean }
   mkdirSync(dirname(outPath), { recursive: true });
   writeFileSync(outPath, attachments![0]!);
   const range = result.loadRange!;
+  const compared = values.compare === undefined ? undefined : compareBuild(attachments![0]!, values.compare);
   return {
     output: {
       assembled: true,
@@ -88,8 +93,10 @@ async function run(argv: string[]): Promise<{ output: unknown; failed: boolean }
           : { name: symbol.name, kind: "constant", value: symbol.value, used: symbol.used },
       ),
       diagnostics: result.diagnostics,
+      ...(compared === undefined ? {} : { compare: compared }),
     },
-    failed: false,
+    // A build that differs from its reference is a failed check.
+    failed: compared !== undefined && !compared.identical,
   };
 }
 

package/skills/c64-assembler/scripts/compare.ts

@@ -0,0 +1,84 @@
+// The byte check of a build (D47): the assembled program against the image
+// of the unpacker (image.json with image.bin), a reference PRG, or 64 KiB of
+// memory, segment by segment.
+
+import { posix } from "node:path";
+
+import { formatC64Address, prgRange } from "#src/c64.ts";
+import { readProjectFile } from "#src/host-client/transfer.ts";
+import { UsageError } from "#src/script.ts";
+
+export interface SegmentCheck {
+  start: string;
+  end: string;
+  result: "identical" | "different" | "not covered";
+  /** Bytes of the segment that the build does not hold. */
+  uncovered?: number;
+  differences?: number;
+  firstDifference?: { address: string; built: number; reference: number };
+}
+
+const FULL = 0x10000;
+
+/** The reference as memory and the ranges to check in it. */
+function reference(path: string, built: { start: number; end: number }): { memory: (address: number) => number | undefined; segments: Array<{ start: number; end: number }> } {
+  const { bytes } = readProjectFile(path);
+  if (path.endsWith(".json")) {
+    let manifest: { image?: unknown; segments?: unknown };
+    try {
+      manifest = JSON.parse(bytes.toString("utf8")) as typeof manifest;
+    } catch (error) {
+      throw new UsageError(`--compare ${path} is not JSON: ${(error as Error).message}`);
+    }
+    const segments = manifest.segments;
+    if (typeof manifest.image !== "string" || !Array.isArray(segments) || segments.length === 0) throw new UsageError(`--compare ${path} is not an image.json: it needs image and segments`);
+    const image = readProjectFile(posix.join(posix.dirname(path), manifest.image)).bytes;
+    if (image.length !== FULL) throw new UsageError(`the image of ${path} has ${image.length} bytes, not 65536`);
+    return {
+      memory: (address) => image[address],
+      segments: segments.map((segment: { start?: unknown; end?: unknown }) => {
+        const parse = (value: unknown) => (typeof value === "string" && /^\$[0-9a-f]{4}$/i.test(value) ? Number.parseInt(value.slice(1), 16) : NaN);
+        const range = { start: parse(segment.start), end: parse(segment.end) };
+        if (!(range.start <= range.end)) throw new UsageError(`--compare ${path}: a segment needs start and end as $ addresses`);
+        return range;
+      }),
+    };
+  }
+  if (bytes.length === FULL && !path.endsWith(".prg")) return { memory: (address) => bytes[address], segments: [built] };
+  let range: ReturnType<typeof prgRange>;
+  try {
+    range = prgRange(bytes);
+  } catch (error) {
+    throw new UsageError(`--compare ${path}: ${(error as Error).message}`);
+  }
+  return { memory: (address) => (address >= range.start && address <= range.end ? range.body[address - range.start] : undefined), segments: [{ start: range.start, end: range.end }] };
+}
+
+/** Compares the assembled PRG with the reference, segment by segment. */
+export function compareBuild(prg: Uint8Array, path: string): { against: string; identical: boolean; segments: SegmentCheck[] } {
+  const built = prgRange(prg);
+  const { memory, segments } = reference(path, built);
+  const checks = segments.map((segment): SegmentCheck => {
+    const from = Math.max(segment.start, built.start);
+    const to = Math.min(segment.end, built.end);
+    const shown = { start: formatC64Address(segment.start), end: formatC64Address(segment.end) };
+    if (from > to) return { ...shown, result: "not covered", uncovered: segment.end - segment.start + 1 };
+    let differences = 0;
+    let first: SegmentCheck["firstDifference"];
+    for (let address = from; address <= to; address++) {
+      const builtByte = built.body[address - built.start]!;
+      const referenceByte = memory(address);
+      if (referenceByte === undefined || builtByte === referenceByte) continue;
+      differences++;
+      first ??= { address: formatC64Address(address), built: builtByte, reference: referenceByte };
+    }
+    const uncovered = segment.end - segment.start + 1 - (to - from + 1);
+    return {
+      ...shown,
+      result: differences > 0 ? "different" : uncovered > 0 ? "not covered" : "identical",
+      ...(uncovered > 0 ? { uncovered } : {}),
+      ...(differences > 0 ? { differences, firstDifference: first! } : {}),
+    };
+  });
+  return { against: path, identical: checks.every((check) => check.result === "identical"), segments: checks };
+}

package/skills/c64-basic/SKILL.md

@@ -30,9 +30,9 @@ The script prints one JSON object. Addresses are `$` and four hex digits.
 1. Run the script on the program.
 2. Read `listing`. Each line starts with its BASIC line number. Keywords show in lower case. Control characters in strings show in braces, for example `{clr}`.
 3. Read `handoffs`. Each handoff has a `kind` (`sys` or `usr`) and the BASIC `line`.
-   - A `sys` handoff with an `address`: BASIC calls the machine code at that address.
-   - A handoff with `computed: true`: the address comes from a calculation at run time. Use the c64-emulator skill to find the address.
-4. Compare the address with `loadRange` and `basicEnd`. From `basicEnd` to the end of `loadRange`, the file holds bytes that are not BASIC. Usually this is the machine code that the handoff calls.
+   - A `sys` handoff with an `address`: BASIC calls the machine code at that address. The script calculates a SYS argument with numbers, π, `+`, `-`, `*`, `/` and brackets. For example, `SYS π*656` calls `$080c`.
+   - A handoff with `computed: true`: the address comes from a calculation at run time, for example with `PEEK`. A `sys` handoff gives its argument in `expression`. Use the c64-emulator skill to find the address.
+4. Compare the address with `loadRange` and `basicEnd`. From `basicEnd` to the end of `loadRange`, the file holds bytes that are not BASIC. Usually this is the machine code that the handoff calls. Some programs have no end marker (two zero bytes) after the last line. The machine code starts directly after the last line. Then `basicEnd` is the first byte of that machine code.
 
 The address ranges are for a load to the load address of the file. A load without `,1` puts a BASIC program at `$0801`. Most loaders have `$0801` as their load address.
 
@@ -56,8 +56,7 @@ The exit status is 0 for a listing. The exit status is 1 for `decoded: false` an
 
 - `decoded: false`: the file is not a BASIC program. This is a normal result. Usually the file is machine code. Give it to the c64-static-analysis skill.
 - An empty `handoffs` list: the BASIC does not start machine code with SYS or USR. Do not make up a handoff. Look for a POKE into a vector or a LOAD of another file in the listing.
-- `installation-incomplete`: petcat is not on the host. Tell the user the message.
-- `operation-failed` with a message about the host runtime: the host runtime does not run. Tell the user to start the host runtime with `npx -y --package=@henols/c64-re-tools@latest c64-re-tools-host`.
+- `installation-incomplete`, or a message that the host runtime does not run: stop the task. Give the message to the user and wait for the user. The message gives the remedy. Do not make a replacement for the tool or the host runtime, for example your own disk parser, disassembler or emulator script.
 - `not-found` or `invalid-input`: the path or an argument is wrong. Read the message and correct the call.
 
 ## Handoffs

package/skills/c64-disk/SKILL.md

@@ -1,13 +1,13 @@
 ---
 name: c64-disk
-description: Use this skill to examine a C64 disk image (D64, D71, D81 or G64) and to extract files from it into the project. It shows the directory, the BAM, the directory entry of a file and the sector chain of a file. Do not use it to run a program or to decode BASIC. Give an extracted file to the c64-basic, c64-unpacker or c64-static-analysis skill.
+description: Use this skill to examine a C64 disk image (D64, D71, D81 or G64), a T64 tape file or a CRT cartridge file. It extracts files into the project. It shows the directory, the BAM, the directory entry of a file and the sector chain of a file. It writes each bank of a cartridge as a PRG. Do not use it to run a program or to decode BASIC. Give an extracted file to the c64-basic, c64-unpacker or c64-static-analysis skill.
 ---
 
 # c64-disk
 
 ## Purpose
 
-Examine a C64 disk image. Extract a file from the image into the project.
+Examine a C64 disk image, a T64 tape file or a CRT cartridge file. Extract a file from it into the project.
 
 This skill does not change the disk image and does not change project knowledge.
 
@@ -16,10 +16,11 @@ This skill does not change the disk image and does not change project knowledge.
 - The disk image: a `.d64`, `.d71`, `.d81` or `.g64` file, relative to the project directory.
 - For one file: the file name as the directory shows it.
 - To extract a file: the output path, relative to the project directory.
+- A T64 tape file or a CRT cartridge file, relative to the project directory.
 
 ## Tools / execution path
 
-The script sends the image to the host runtime. The host runs c1541 and sends the result back. The script writes an extracted file into the project.
+The script sends a disk image to the host runtime. The host runs c1541 and sends the result back. The script writes an extracted file into the project. It reads T64 and CRT files itself.
 
 ```
 node <skill>/scripts/disk.ts <action> <image> [name] [--out <file>]
@@ -32,6 +33,10 @@ node <skill>/scripts/disk.ts <action> <image> [name] [--out <file>]
 | The type, size and first block of one file | `entry original/game.d64 GAME` |
 | The track and sector of each block of one file | `chain original/game.d64 GAME` |
 | Extract one file | `read original/game.d64 GAME --out extracted/game.prg` |
+| The files of a tape | `directory original/game.t64` |
+| Extract one file of a tape | `read original/game.t64 GAME --out extracted/game.prg` |
+| The banks of a cartridge | `directory original/game.crt` |
+| Write each bank of a cartridge as a PRG | `crt original/game.crt --out cart` |
 
 The script prints one JSON object.
 
@@ -55,6 +60,15 @@ Do not store:
 
 A downstream skill records the meaning of the extracted content.
 
+## Tapes and cartridges
+
+The script reads T64 and CRT files itself. The host runtime is not necessary for them.
+
+- T64: `directory` and `read`. Many T64 files have a wrong end address. Then the entry has `fixedSize: true`, and the size comes from the position of the next file.
+- CRT: `directory` and `crt`. The script reads hardware types 0 (normal 8K, 16K or Ultimax), 5 (Ocean), 19 (Magic Desk) and 32 (EasyFlash). It refuses other types by name. `crt` writes `crt.json` and one PRG for each CHIP packet, for example `bank3-8000.prg`.
+- A cartridge bank uses the same addresses as other banks. Analyze each bank PRG with c64-static-analysis and `--space bank3`, and record its knowledge in space `bank3`.
+- TAP: a TAP file holds tape signals, and turbo loaders have their own formats. The script does not read it. Start it with the c64-emulator skill, or capture its parts with `loads` of the c64-unpacker skill.
+
 ## Result
 
 The directory, the BAM, an entry or a sector chain as JSON. Or the extracted file in the project at the output path.
@@ -65,8 +79,7 @@ The exit status is 0 for a result with the file. The exit status is 1 for `found
 
 - `found: false`: the image has no file with that name. This is a normal result. Read the directory again and compare the names.
 - `media-error`: the image has a defect or is not a disk image. The message tells the problem, for example a sector chain that loops. Tell the user. Do not change the image.
-- `installation-incomplete`: c1541 is not on the host. Tell the user the message.
-- `operation-failed` with a message about the host runtime: the host runtime does not run. Tell the user to start the host runtime with `npx -y --package=@henols/c64-re-tools@latest c64-re-tools-host`.
+- `installation-incomplete`, or a message that the host runtime does not run: stop the task. Give the message to the user and wait for the user. The message gives the remedy. Do not make a replacement for the tool or the host runtime, for example your own disk parser, disassembler or emulator script.
 - `invalid-input`: an argument or a path is wrong. Read the message and correct the call.
 
 A file that is not `closed` was not written fully. Its data can be incomplete.
@@ -75,5 +88,6 @@ A file that is not `closed` was not written fully. Its data can be incomplete.
 
 - BASIC program → c64-basic
 - Packed program → c64-unpacker
-- Machine code → c64-static-analysis
+- Machine code, also a cartridge bank → c64-static-analysis
+- A TAP file → c64-unpacker
 - Run the program → c64-emulator

package/skills/c64-disk/scripts/containers.ts

@@ -0,0 +1,124 @@
+// Cartridge and tape containers that c64-disk reads locally (D54): no host
+// tool reads them. A CRT file holds CHIP packets, each a bank of ROM at a
+// load address; a T64 file holds a directory of PRG files. TAP files hold
+// raw pulses and go through the emulator only.
+
+import { formatC64Address, petsciiNameToText } from "#src/c64.ts";
+
+/** A refusal of a container file: the caller turns it into a usage error. */
+export class ContainerError extends Error {}
+
+/** The CRT hardware types this toolkit reads, by type number (D54). */
+export const CRT_TYPES: Record<number, string> = { 0: "normal", 5: "Ocean", 19: "Magic Desk", 32: "EasyFlash" };
+
+export interface CrtChip {
+  bank: number;
+  address: number;
+  size: number;
+  /** 0 ROM, 1 RAM, 2 flash. */
+  chipType: number;
+  data: Uint8Array;
+}
+
+export interface Crt {
+  name: string;
+  type: number;
+  typeName: string;
+  /** The EXROM and GAME lines at start: 0 is active. */
+  exrom: number;
+  game: number;
+  /** For type 0: 8K, 16K or Ultimax by the EXROM and GAME lines. */
+  mode?: "8k" | "16k" | "ultimax";
+  chips: CrtChip[];
+}
+
+const SIGNATURE = "C64 CARTRIDGE   ";
+
+export function parseCrt(bytes: Uint8Array): Crt {
+  const buffer = Buffer.from(bytes.buffer, bytes.byteOffset, bytes.byteLength);
+  if (buffer.length < 0x40 || buffer.toString("latin1", 0, 16) !== SIGNATURE) throw new ContainerError("the file is not a CRT: it does not start with C64 CARTRIDGE");
+  const headerLength = buffer.readUInt32BE(0x10);
+  const type = buffer.readUInt16BE(0x16);
+  const exrom = buffer[0x18]!;
+  const game = buffer[0x19]!;
+  const typeName = CRT_TYPES[type];
+  if (typeName === undefined) {
+    throw new ContainerError(`the CRT has hardware type ${type}; this toolkit reads types ${Object.entries(CRT_TYPES).map(([number, name]) => `${number} (${name})`).join(", ")}`);
+  }
+  const name = buffer.toString("latin1", 0x20, 0x40).replace(/\0+$/, "");
+  const chips: CrtChip[] = [];
+  let offset = Math.max(headerLength, 0x40);
+  while (offset + 0x10 <= buffer.length) {
+    if (buffer.toString("latin1", offset, offset + 4) !== "CHIP") throw new ContainerError(`the CRT has no CHIP packet at offset ${offset}`);
+    const packetLength = buffer.readUInt32BE(offset + 4);
+    const chipType = buffer.readUInt16BE(offset + 8);
+    const bank = buffer.readUInt16BE(offset + 10);
+    const address = buffer.readUInt16BE(offset + 12);
+    const size = buffer.readUInt16BE(offset + 14);
+    if (packetLength < 0x10 || offset + packetLength > buffer.length) throw new ContainerError(`the CHIP packet at offset ${offset} runs past the end of the file`);
+    if (bank > 255) throw new ContainerError(`the CHIP packet at offset ${offset} has bank ${bank}; banks go up to 255`);
+    if (size > packetLength - 0x10 || address + size > 0x10000) throw new ContainerError(`the CHIP packet at offset ${offset} has a wrong size ${size} at ${formatC64Address(address)}`);
+    if (size > 0) chips.push({ bank, address, size, chipType, data: buffer.subarray(offset + 0x10, offset + 0x10 + size) });
+    offset += packetLength;
+  }
+  if (chips.length === 0) throw new ContainerError("the CRT has no CHIP packet with data");
+  const crt: Crt = { name, type, typeName, exrom, game, chips };
+  if (type === 0) crt.mode = exrom === 0 && game === 1 ? "8k" : exrom === 0 && game === 0 ? "16k" : "ultimax";
+  return crt;
+}
+
+export interface TapeEntry {
+  name: string;
+  nameBytes: number[];
+  /** The C64 file type byte of the entry. */
+  fileType: number;
+  start: number;
+  end: number;
+  bytes: number;
+  offset: number;
+  /** True when the end address in the directory was wrong and the size comes from the file layout. */
+  fixedSize?: boolean;
+}
+
+export interface Tape {
+  name: string;
+  entries: TapeEntry[];
+}
+
+export function parseT64(bytes: Uint8Array): Tape {
+  const buffer = Buffer.from(bytes.buffer, bytes.byteOffset, bytes.byteLength);
+  if (buffer.length < 0x40 || !buffer.toString("latin1", 0, 32).startsWith("C64")) throw new ContainerError("the file is not a T64: it does not start with C64");
+  const maxEntries = buffer.readUInt16LE(0x22);
+  const name = buffer.toString("latin1", 0x28, 0x40).replace(/[\0 ]+$/, "");
+  const raw: Array<Omit<TapeEntry, "bytes" | "end"> & { end: number }> = [];
+  for (let index = 0; index < maxEntries; index++) {
+    const at = 0x40 + index * 0x20;
+    if (at + 0x20 > buffer.length) break;
+    if (buffer[at] !== 1) continue;
+    const nameField = [...buffer.subarray(at + 0x10, at + 0x20)];
+    while (nameField.length > 0 && (nameField.at(-1) === 0x20 || nameField.at(-1) === 0xa0 || nameField.at(-1) === 0x00)) nameField.pop();
+    raw.push({
+      name: petsciiNameToText(Uint8Array.from(nameField)),
+      nameBytes: nameField,
+      fileType: buffer[at + 1]!,
+      start: buffer.readUInt16LE(at + 2),
+      end: buffer.readUInt16LE(at + 4),
+      offset: buffer.readUInt32LE(at + 8),
+    });
+  }
+  // Many T64 files have a wrong end address: the next file or the end of the file bounds each one.
+  const offsets = [...raw.map((entry) => entry.offset), buffer.length].sort((a, b) => a - b);
+  const entries = raw.map((entry): TapeEntry => {
+    if (entry.offset >= buffer.length) throw new ContainerError(`the T64 entry ${entry.name} starts past the end of the file`);
+    const available = offsets.find((offset) => offset > entry.offset)! - entry.offset;
+    const stated = entry.end - entry.start;
+    const bytes = stated > 0 && stated <= available ? stated : Math.min(available, 0x10000 - entry.start);
+    return { ...entry, end: entry.start + bytes - 1, bytes, ...(bytes === stated ? {} : { fixedSize: true }) };
+  });
+  return { name, entries };
+}
+
+/** The PRG of a tape entry: its start address, then its bytes. */
+export function tapeFile(bytes: Uint8Array, entry: TapeEntry): Buffer {
+  return Buffer.concat([Buffer.from([entry.start & 0xff, entry.start >> 8]), Buffer.from(bytes.subarray(entry.offset, entry.offset + entry.bytes))]);
+}

package/skills/c64-disk/scripts/disk.ts

@@ -1,13 +1,17 @@
 // The c64-disk script: inspects a project disk image with c1541 through the
-// Host Runtime and extracts files into the project.
+// Host Runtime and extracts files into the project. T64 tape files and CRT
+// cartridge files are read locally (D54): no host tool reads them.
 
 import { mkdirSync, writeFileSync } from "node:fs";
 import { dirname } from "node:path";
 import { parseArgs } from "node:util";
 
+import { formatC64Address } from "#src/c64.ts";
 import { inspectDisk } from "#src/host-client/tools.ts";
+import { readProjectFile, writeProjectFile } from "#src/host-client/transfer.ts";
 import { resolveProjectPath } from "#src/project.ts";
 import { runScript, UsageError } from "#src/script.ts";
+import { ContainerError, parseCrt, parseT64, tapeFile } from "./containers.ts";
 
 const USAGE = `disk.ts <action> <image> [name] [--out <file>]
 
@@ -16,12 +20,16 @@ const USAGE = `disk.ts <action> <image> [name] [--out <file>]
   entry <image> <name>              the directory entry of one file
   chain <image> <name>              the track and sector of each block of one file
   read <image> <name> --out <file>  write the bytes of one file into the project
+  crt <file.crt> --out <dir>        write each CHIP packet of a cartridge as a PRG
 
 <image> is a .d64, .d71, .d81 or .g64 file, relative to the project directory.
+directory and read also take a .t64 tape file, and directory a .crt cartridge
+file; the script reads those itself. A CRT can have hardware type 0 (normal
+8K, 16K or Ultimax), 5 (Ocean), 19 (Magic Desk) or 32 (EasyFlash).
 <name> is the file name as the directory shows it. Write a byte that has no
 character as {$xx}, for example {$c1}. The result is one JSON object.`;
 
-const ACTIONS = ["directory", "bam", "entry", "chain", "read"] as const;
+const ACTIONS = ["directory", "bam", "entry", "chain", "read", "crt"] as const;
 type Action = (typeof ACTIONS)[number];
 
 async function run(argv: string[]): Promise<{ output: unknown; failed: boolean }> {
@@ -33,8 +41,8 @@ async function run(argv: string[]): Promise<{ output: unknown; failed: boolean }
   const named = action === "entry" || action === "chain" || action === "read";
   if (named && name === undefined) throw new UsageError(`${action} needs a file name`);
   if ((!named && name !== undefined) || extra.length > 0) throw new UsageError("too many arguments");
-  if (action === "read" && values.out === undefined) throw new UsageError("read needs --out <file>");
-  if (action !== "read" && values.out !== undefined) throw new UsageError("only read takes --out");
+  if ((action === "read" || action === "crt") && values.out === undefined) throw new UsageError(`${action} needs --out`);
+  if (action !== "read" && action !== "crt" && values.out !== undefined) throw new UsageError("only read and crt take --out");
   let outPath: string | undefined;
   if (values.out !== undefined) {
     try {
@@ -44,7 +52,17 @@ async function run(argv: string[]): Promise<{ output: unknown; failed: boolean }
     }
   }
 
-  const result = await inspectDisk({ image, action: action as Action, ...(name === undefined ? {} : { name }) });
+  const kind = image.toLowerCase().endsWith(".t64") ? "t64" : image.toLowerCase().endsWith(".crt") ? "crt" : "disk";
+  if (action === "crt" && kind !== "crt") throw new UsageError("crt needs a .crt file");
+  if (kind !== "disk") {
+    try {
+      return local(kind, action as Action, image, name, values.out);
+    } catch (error) {
+      if (error instanceof ContainerError) throw new UsageError(`${image}: ${error.message}`);
+      throw error;
+    }
+  }
+  const result = await inspectDisk({ image, action: action as Exclude<Action, "crt">, ...(name === undefined ? {} : { name }) });
   if ("found" in result && !result.found) return { output: { found: false }, failed: true };
   if (result.action === "read" && result.found) {
     mkdirSync(dirname(outPath!), { recursive: true });
@@ -55,6 +73,42 @@ async function run(argv: string[]): Promise<{ output: unknown; failed: boolean }
   return { output, failed: false };
 }
 
+/** A tape or cartridge file, read here (D54). */
+function local(kind: "t64" | "crt", action: Action, image: string, name: string | undefined, out: string | undefined): { output: unknown; failed: boolean } {
+  const { bytes } = readProjectFile(image);
+  if (kind === "t64") {
+    if (action !== "directory" && action !== "read") throw new UsageError(`a T64 file has only directory and read, not ${action}`);
+    const tape = parseT64(bytes);
+    const shown = (entry: (typeof tape.entries)[number]) => ({
+      name: entry.name,
+      start: formatC64Address(entry.start),
+      end: formatC64Address(entry.end),
+      bytes: entry.bytes,
+      ...(entry.fixedSize ? { fixedSize: true } : {}),
+    });
+    if (action === "directory") return { output: { name: tape.name, entries: tape.entries.map(shown) }, failed: false };
+    const entry = tape.entries.find((candidate) => candidate.name.toLowerCase() === name!.toLowerCase());
+    if (entry === undefined) return { output: { found: false }, failed: true };
+    const file = tapeFile(bytes, entry);
+    writeProjectFile(out!, file, { what: "--out" });
+    return { output: { found: true, name: entry.name, bytes: file.length, output: out }, failed: false };
+  }
+  if (action !== "directory" && action !== "crt") throw new UsageError(`a CRT file has only directory and crt, not ${action}`);
+  const crt = parseCrt(bytes);
+  const chips = crt.chips.map((chip) => ({
+    bank: chip.bank,
+    address: formatC64Address(chip.address),
+    size: chip.size,
+    space: `bank${chip.bank}`,
+    file: `bank${chip.bank}-${chip.address.toString(16).padStart(4, "0")}.prg`,
+  }));
+  const output = { name: crt.name, type: crt.type, typeName: crt.typeName, exrom: crt.exrom, game: crt.game, ...(crt.mode === undefined ? {} : { mode: crt.mode }), chips };
+  if (action === "directory") return { output: { ...output, chips: chips.map(({ file: _file, ...chip }) => chip) }, failed: false };
+  crt.chips.forEach((chip, index) => writeProjectFile(`${out}/${chips[index]!.file}`, Buffer.concat([Buffer.from([chip.address & 0xff, chip.address >> 8]), chip.data]), { what: "--out" }));
+  writeProjectFile(`${out}/crt.json`, Buffer.from(`${JSON.stringify(output, null, 2)}\n`), { what: "--out" });
+  return { output: { ...output, out }, failed: false };
+}
+
 await runScript(
   async () => {
     const { output, failed } = await run(process.argv.slice(2));

package/skills/c64-emulator/SKILL.md

@@ -44,10 +44,14 @@ Use only the MCP tools. Each MCP session has its own C64. Nothing else can chang
 | Several of these from one moment | `c64_observe` |
 | Keys, joystick | `c64_keyboard`, `c64_joystick` |
 | Program and disk media | `c64_autostart`, `c64_program_load`, `c64_disk_attach` |
-| Machine state to go back to | `c64_snapshot` |
+| Machine state to go back to, also in a later session | `c64_snapshot` (with `out` and `file`) |
 
 Each memory and register tool has a `space`. Use `c64` for the computer. Use `drive8` for the CPU of the 1541 disk drive. The memory `view` is `cpu` or `ram`. With `cpu`, you see what the CPU sees now, with ROM and I/O where the memory configuration puts them. With `ram`, you see the RAM under them.
 
+For a large result, give `out` with a path in the project. `c64_memory_read`, `c64_disassemble`, `c64_cpu_history` and `c64_screen` then write the result to that file. The answer gives only the file, the number of bytes and a SHA-256. Use it for a memory dump of more than a few hundred bytes, a long listing, or a screen that the user wants to keep.
+
+`c64_memmap` keeps RAM, ROM and I/O apart. Use action `summary` to see which code ran. Use action `read` with `out` to keep a coverage run as a file, for example `coverage/attract.bin`. Clear the map before each run that you want to keep apart.
+
 ## Workflow
 
 1. Read the project knowledge for the addresses in the question. Use the c64-knowledge skill.
@@ -64,7 +68,11 @@ Write operations need a stopped CPU. Stop the CPU with `c64_execution` action `p
 
 Step, next and until-return work only in space `c64`. The emulator cannot stop the disk drive CPU after one instruction. To find when the drive executes an address, use `c64_run_until` with an address target in space `drive8`, or a breakpoint in space `drive8`. The drive can execute a few more instructions before it stops. The computer completes its current instruction. The `pc` in the result is the drive address where it stopped.
 
-`c64_keyboard` puts keys in the keyboard queue of the KERNAL. A program that reads the keyboard hardware directly does not see them. Many games do this. For such a program, use `c64_joystick`, or open the window and ask the user to press the key.
+`c64_keyboard` puts keys in the keyboard queue of the KERNAL. A program that reads the keyboard hardware directly does not see them. Many games do this. The emulator has no command that presses one key of the keyboard matrix. For such a program:
+
+- VICE 3.10 and older have a known flaw: bits 5-7 of `$DC00` and `$DC01` are always 0. Then `emulatorFlaw` in the result of `c64_keyboard` and `c64_joystick` gives the flaw. With this flaw, a wait for any key that reads all keyboard columns at one time ends without a key. A wait for one specific key, or a compare of the full byte of a joystick port, never ends. Tell the user about the flaw. The next VICE release and the VICE nightly builds do not have it. Joystick port 1 uses the same lines as the keyboard.
+- For one specific key, for example F1 or RUN/STOP, open the window and ask the user to press the key.
+- Do not change the program to make it accept a key.
 
 Before a risky experiment, save the state with `c64_snapshot`. Restore it to try again from the same point.
 
@@ -106,11 +114,10 @@ If you cannot get the machine into the necessary state, say which state you coul
 
 - `machine-state-lost` and the message says that the VICE window closed: the window closed before `c64_window` action `close`. The emulator has no window again. The machine state is the same as at the time when the window opened. The breakpoints and the watchpoints stay. Do not use results from the window time. Read the machine state again, then continue.
 - `machine-unavailable` and the message says that the VICE window closed: the session starts the emulator again. Wait a few seconds. Then do the operation again.
-- `machine-state-lost` with a different message: the emulator stopped and its state is gone. Do not continue with results from before. Tell the user to restart the MCP server.
+- `machine-state-lost` with a different message: the connection to the host runtime was lost, and the machine state is gone. Do not continue with results from before. The next call starts a new machine when the host runtime runs. Load the program again, and set the breakpoints and the watchpoints again. If the next call gives `machine-unavailable` with a message that the host runtime does not run, obey the rule for that message.
 - `machine-unavailable` and the message names a pause or a dialog in the emulator window: this occurs only while the window is open. Do not send more operations. Tell the user to resume the emulator (Pause, Alt+P) or to close the dialog in the VICE window. Then do the operation again. The machine state does not change.
-- `machine-unavailable` with a different message: the host runtime does not run, or it does not answer. Tell the user to start the host runtime with `npx -y --package=@henols/c64-re-tools@latest c64-re-tools-host`.
 - `machine-running`: stop the CPU first, then try again.
-- `installation-incomplete`: tell the user the message. Do not try to repair the installation.
+- `installation-incomplete`, or `machine-unavailable` with a message that the host runtime does not run: stop the task. Give the message to the user and wait for the user. The message gives the remedy. Do not make a replacement for the tool or the host runtime, for example your own disk parser, disassembler or emulator script. Do not try to repair the installation.
 - `c64_run_until` with `stopReason` `timeout`: the target did not occur in the frame limit. This is evidence too. Report it.
 - `c64_run_until` with `stopReason` `jam`: the CPU executed a JAM opcode and stopped. Report the address.