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

package/src/project.ts

@@ -0,0 +1,39 @@
+import { realpathSync } from "node:fs";
+import { isAbsolute, relative, resolve, sep } from "node:path";
+
+export function projectRoot(): string {
+  return process.cwd();
+}
+
+export function resolveProjectPath(path: string, root = projectRoot()): string {
+  if (path.length === 0) {
+    throw new TypeError("Project path must not be empty");
+  }
+  if (isAbsolute(path)) {
+    throw new TypeError("Project path must be relative");
+  }
+
+  const candidate = resolve(root, path);
+  if (isInside(root, candidate)) return candidate;
+  throw new TypeError("Project path escapes the project root");
+}
+
+/** True when `candidate` is `root` or below it. Both are absolute paths. */
+export function isInside(root: string, candidate: string): boolean {
+  const fromRoot = relative(root, candidate);
+  return fromRoot === "" || (fromRoot !== ".." && !fromRoot.startsWith(`..${sep}`) && !isAbsolute(fromRoot));
+}
+
+/**
+ * Resolves a project-relative path to an existing file system entry whose real
+ * location is inside the project too, so a symbolic link cannot reach outside
+ * it. Throws TypeError for a refused path; lets ENOENT through.
+ */
+export function resolveProjectFile(path: string, root = projectRoot()): string {
+  const candidate = resolveProjectPath(path, root);
+  const real = realpathSync(candidate);
+  if (!isInside(realpathSync(root), real)) {
+    throw new TypeError("Project path escapes the project root through a symbolic link");
+  }
+  return real;
+}

package/src/protocol/framing.ts

@@ -0,0 +1,132 @@
+// The frame codec of the Host Runtime wire: the frame limits, encodeFrame and MessageReader.
+
+import { type ClientMessage, type HostMessage, isInteger, isObject, ProtocolError } from "./messages.ts";
+
+/** Largest frame body either side accepts. */
+export const MAX_FRAME_BYTES = 1024 * 1024;
+
+// ---------------------------------------------------------------------------
+// Framing: 4-byte big-endian body length, then the body. A message body
+// is UTF-8 JSON. A message may announce binary attachments with an
+// `attachments` array of byte sizes; each attachment then follows as raw
+// frames of at most MAX_FRAME_BYTES each, in order.
+
+const HEADER_BYTES = 4;
+/** Total attachment bytes one message may carry. */
+export const MAX_ATTACHMENT_BYTES = 16 * 1024 * 1024;
+
+function frame(body: Uint8Array): Buffer {
+  const header = Buffer.allocUnsafe(HEADER_BYTES);
+  header.writeUInt32BE(body.length, 0);
+  return Buffer.concat([header, body]);
+}
+
+/** Encodes one message and its attachments as one buffer, so writes never interleave. */
+export function encodeFrame(message: ClientMessage | HostMessage, attachments: readonly Uint8Array[] = []): Buffer {
+  const total = attachments.reduce((sum, attachment) => sum + attachment.length, 0);
+  if (total > MAX_ATTACHMENT_BYTES) throw new ProtocolError(`attachments of ${total} bytes exceed ${MAX_ATTACHMENT_BYTES}`);
+  const announced = attachments.length === 0 ? message : { ...message, attachments: attachments.map((attachment) => attachment.length) };
+  const body = Buffer.from(JSON.stringify(announced), "utf8");
+  if (body.length > MAX_FRAME_BYTES) throw new ProtocolError(`frame of ${body.length} bytes exceeds ${MAX_FRAME_BYTES}`);
+  const frames = [frame(body)];
+  for (const attachment of attachments) {
+    for (let offset = 0; offset < attachment.length; offset += MAX_FRAME_BYTES) {
+      frames.push(frame(attachment.subarray(offset, offset + MAX_FRAME_BYTES)));
+    }
+  }
+  return Buffer.concat(frames);
+}
+
+/** Splits a stream into frame bodies. After a ProtocolError the decoder is unusable. */
+class RawFrameDecoder {
+  #pending: Buffer = Buffer.alloc(0);
+
+  push(chunk: Buffer): Buffer[] {
+    this.#pending = this.#pending.length === 0 ? chunk : Buffer.concat([this.#pending, chunk]);
+    const bodies: Buffer[] = [];
+    while (this.#pending.length >= HEADER_BYTES) {
+      const length = this.#pending.readUInt32BE(0);
+      if (length > MAX_FRAME_BYTES) throw new ProtocolError(`frame of ${length} bytes exceeds ${MAX_FRAME_BYTES}`);
+      if (this.#pending.length < HEADER_BYTES + length) break;
+      bodies.push(Buffer.from(this.#pending.subarray(HEADER_BYTES, HEADER_BYTES + length)));
+      this.#pending = this.#pending.subarray(HEADER_BYTES + length);
+    }
+    return bodies;
+  }
+}
+
+export interface ReceivedMessage {
+  /** The parsed JSON body, with any `attachments` announcement removed. */
+  message: unknown;
+  attachments: Buffer[];
+}
+
+/** Reassembles messages and their attachments from stream chunks. Throws ProtocolError. */
+export class MessageReader {
+  readonly #frames = new RawFrameDecoder();
+  readonly #textDecoder = new TextDecoder("utf-8", { fatal: true });
+  #current: { message: unknown; sizes: number[]; done: Buffer[]; parts: Buffer[]; received: number } | undefined;
+
+  push(chunk: Buffer): ReceivedMessage[] {
+    const complete: ReceivedMessage[] = [];
+    for (const body of this.#frames.push(chunk)) {
+      if (this.#current === undefined) this.#start(body);
+      else this.#collect(body);
+      const finished = this.#finish();
+      if (finished !== undefined) complete.push(finished);
+    }
+    return complete;
+  }
+
+  #start(body: Buffer): void {
+    let text: string;
+    try {
+      text = this.#textDecoder.decode(body);
+    } catch {
+      throw new ProtocolError("frame body is not valid UTF-8");
+    }
+    let message: unknown;
+    try {
+      message = JSON.parse(text);
+    } catch {
+      throw new ProtocolError("frame body is not valid JSON");
+    }
+    let sizes: number[] = [];
+    if (isObject(message) && "attachments" in message) {
+      const announced = message.attachments;
+      if (!Array.isArray(announced) || !announced.every((size) => isInteger(size, 0, MAX_ATTACHMENT_BYTES))) {
+        throw new ProtocolError("attachments must be a list of byte sizes");
+      }
+      if (announced.reduce((sum: number, size: number) => sum + size, 0) > MAX_ATTACHMENT_BYTES) {
+        throw new ProtocolError(`attachments exceed ${MAX_ATTACHMENT_BYTES} bytes`);
+      }
+      sizes = announced as number[];
+      const { attachments: _announced, ...rest } = message;
+      message = rest;
+    }
+    this.#current = { message, sizes, done: [], parts: [], received: 0 };
+  }
+
+  #collect(body: Buffer): void {
+    const current = this.#current!;
+    const expected = current.sizes[current.done.length]!;
+    // An attachment of size 0 is complete without a frame, so the pending one needs bytes; an empty frame would only add an empty part.
+    if (body.length === 0) throw new ProtocolError("attachment frame is empty");
+    if (current.received + body.length > expected) throw new ProtocolError("attachment frame runs past its announced size");
+    current.parts.push(body);
+    current.received += body.length;
+  }
+
+  /** Completes attachments whose bytes are all here; returns the message once nothing is missing. */
+  #finish(): ReceivedMessage | undefined {
+    const current = this.#current!;
+    while (current.done.length < current.sizes.length && current.received === current.sizes[current.done.length]) {
+      current.done.push(Buffer.concat(current.parts));
+      current.parts = [];
+      current.received = 0;
+    }
+    if (current.done.length < current.sizes.length) return undefined;
+    this.#current = undefined;
+    return { message: current.message, attachments: current.done };
+  }
+}

package/src/protocol/messages.ts

@@ -0,0 +1,243 @@
+// The message layer of the Host Runtime wire: protocol identity, error codes, the message shapes and
+// their parsers, and the field checks that every validator uses.
+
+import type { ToolOperation, ToolOperations } from "./tools.ts";
+import type { ViceOperation, ViceOperations } from "./vice.ts";
+
+/** Private Host Runtime protocol identifier. */
+export const HOST_PROTOCOL_ID = "c64-re-tools-host" as const;
+/** Bumped on any incompatible change; a mismatch fails the handshake. */
+export const HOST_PROTOCOL_VERSION = 2;
+/** After ready, the client pings this often, on every connection. */
+export const HEARTBEAT_INTERVAL_MS = 10_000;
+/** Either side closes a connection that has sent nothing for this long. */
+export const HEARTBEAT_TIMEOUT_MS = 30_000;
+/** The Host Runtime listens on 127.0.0.1 at this port by default. */
+export const DEFAULT_HOST_PORT = 6464;
+
+// ---------------------------------------------------------------------------
+// Shared vocabulary
+
+export const ERROR_CODES = [
+  "invalid-input",
+  "machine-running",
+  "machine-unavailable",
+  "machine-state-lost",
+  "not-found",
+  "media-error",
+  "limit-exceeded",
+  "unsupported-in-space",
+  "installation-incomplete",
+  "operation-failed",
+] as const;
+export type ErrorCode = (typeof ERROR_CODES)[number];
+
+/** An actionable failure carried on the wire and shown to the LLM unchanged. */
+export interface WireError {
+  code: ErrorCode;
+  message: string;
+}
+
+export const ROLES = ["vice-session", "tool"] as const;
+export type Role = (typeof ROLES)[number];
+
+export const VIDEO_STANDARDS = ["pal", "ntsc"] as const;
+export type VideoStandard = (typeof VIDEO_STANDARDS)[number];
+
+// ---------------------------------------------------------------------------
+// Messages
+
+export interface Hello {
+  type: "hello";
+  protocol: string;
+  version: number;
+  role: Role;
+  /** vice-session only; fixed for the session. */
+  videoStandard?: VideoStandard;
+}
+
+export interface Ready {
+  type: "ready";
+}
+
+/** Sent instead of `ready` when the handshake fails; the host then closes. */
+export interface HandshakeError {
+  type: "error";
+  error: WireError;
+}
+
+export interface Request<O extends ViceOperation | ToolOperation = ViceOperation | ToolOperation> {
+  type: "request";
+  id: number;
+  op: O;
+  params: O extends ViceOperation ? ViceOperations[O]["params"] : O extends ToolOperation ? ToolOperations[O]["params"] : never;
+}
+
+export type Reply =
+  | { type: "reply"; id: number; result: unknown }
+  | { type: "reply"; id: number; error: WireError };
+
+/** Heartbeat: the client pings after ready, the host answers pong. Neither touches the session. */
+export interface Ping {
+  type: "ping";
+}
+export interface Pong {
+  type: "pong";
+}
+
+export type ClientMessage = Hello | Request | Ping;
+
+/** A request as the host receives it: the operation is not checked yet, so the host answers an unknown one with invalid-input. */
+export interface ReceivedRequest {
+  type: "request";
+  id: number;
+  op: string;
+  params: Fields;
+}
+export type ReceivedClientMessage = Hello | ReceivedRequest | Ping;
+export type HostMessage = Ready | HandshakeError | Reply | Pong;
+
+// ---------------------------------------------------------------------------
+// Validation. A ProtocolError means the peer broke the contract; the receiver
+// closes the connection. Bad operation parameters are a WireError instead.
+
+export class ProtocolError extends Error {
+  override name = "ProtocolError";
+}
+
+/** Thrown by parameter/result validators; carries the wire code to answer with. */
+export class WireFailure extends Error implements WireError {
+  override name = "WireFailure";
+  readonly code: ErrorCode;
+
+  constructor(code: ErrorCode, message: string) {
+    super(message);
+    this.code = code;
+  }
+
+  toWire(): WireError {
+    return { code: this.code, message: this.message };
+  }
+}
+
+/** The message of a caught value, which may not be an Error. */
+export function describeError(error: unknown): string {
+  return error instanceof Error ? error.message : String(error);
+}
+
+export type Fields = Record<string, unknown>;
+
+export function isObject(value: unknown): value is Fields {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+/** True when `value` is one of `values`; narrows a string to the union. */
+export function isOneOf<T extends string>(values: readonly T[], value: unknown): value is T {
+  return typeof value === "string" && (values as readonly string[]).includes(value);
+}
+
+export function isInteger(value: unknown, min: number, max: number): value is number {
+  return typeof value === "number" && Number.isInteger(value) && value >= min && value <= max;
+}
+
+function isRequestId(value: unknown): value is number {
+  return isInteger(value, 0, 0xffff_ffff);
+}
+
+function isWireError(value: unknown): value is WireError {
+  return isObject(value) && isOneOf(ERROR_CODES, value.code) && typeof value.message === "string";
+}
+
+/** Validates a message the host received. Throws ProtocolError on any contract break. */
+export function parseClientMessage(value: unknown): ReceivedClientMessage {
+  if (!isObject(value)) throw new ProtocolError("message is not an object");
+  if (value.type === "hello") {
+    // protocol/version are checked by the handshake, which answers a mismatch
+    // with installation-incomplete; here they only need their JSON types.
+    if (typeof value.protocol !== "string" || typeof value.version !== "number") {
+      throw new ProtocolError("hello lacks protocol or version");
+    }
+    if (!isOneOf(ROLES, value.role)) throw new ProtocolError("hello has an unknown role");
+    if (value.videoStandard !== undefined && !isOneOf(VIDEO_STANDARDS, value.videoStandard)) {
+      throw new ProtocolError("hello has an unknown video standard");
+    }
+    const hello: Hello = { type: "hello", protocol: value.protocol, version: value.version, role: value.role };
+    if (value.videoStandard !== undefined) hello.videoStandard = value.videoStandard;
+    return hello;
+  }
+  if (value.type === "request") {
+    if (!isRequestId(value.id)) throw new ProtocolError("request id is not a 32-bit unsigned integer");
+    if (typeof value.op !== "string") throw new ProtocolError("request op is not a string");
+    if (!isObject(value.params)) throw new ProtocolError("request params is not an object");
+    return { type: "request", id: value.id, op: value.op, params: value.params };
+  }
+  if (value.type === "ping") return { type: "ping" };
+  throw new ProtocolError("unknown message type");
+}
+
+/** Validates a message the client received. Throws ProtocolError on any contract break. */
+export function parseHostMessage(value: unknown): HostMessage {
+  if (!isObject(value)) throw new ProtocolError("message is not an object");
+  if (value.type === "ready") return { type: "ready" };
+  if (value.type === "pong") return { type: "pong" };
+  if (value.type === "error") {
+    if (!isWireError(value.error)) throw new ProtocolError("handshake error is malformed");
+    return { type: "error", error: { code: value.error.code, message: value.error.message } };
+  }
+  if (value.type === "reply") {
+    if (!isRequestId(value.id)) throw new ProtocolError("reply id is not a 32-bit unsigned integer");
+    if ("error" in value) {
+      if (!isWireError(value.error)) throw new ProtocolError("reply error is malformed");
+      return { type: "reply", id: value.id, error: { code: value.error.code, message: value.error.message } };
+    }
+    if (!("result" in value)) throw new ProtocolError("reply has neither result nor error");
+    return { type: "reply", id: value.id, result: value.result };
+  }
+  throw new ProtocolError("unknown message type");
+}
+
+/** Checks a hello against this build's protocol. Returns the failure to send, or undefined. */
+/**
+ * Refuses a client of another protocol version, and names the older side and
+ * how to update it. A release that changes the wire increments the protocol
+ * version, so the first client of a new release refuses an older host.
+ */
+export function checkHello(hello: Hello): WireError | undefined {
+  if (hello.protocol !== HOST_PROTOCOL_ID) {
+    return {
+      code: "installation-incomplete",
+      message:
+        "The c64-re-tools host runtime and this client come from different installations. " +
+        "Install the same c64-re-tools release for both and restart the host runtime.",
+    };
+  }
+  if (hello.version > HOST_PROTOCOL_VERSION) {
+    return {
+      code: "installation-incomplete",
+      message:
+        "The c64-re-tools host runtime is from an older release than this client. " +
+        "Stop the host runtime and start it again with the same npx command. npx then starts the newest release.",
+    };
+  }
+  if (hello.version < HOST_PROTOCOL_VERSION) {
+    return {
+      code: "installation-incomplete",
+      message:
+        "This client is from an older release of c64-re-tools than the host runtime. " +
+        "Restart the agent session, so that npx starts the newest MCP server. " +
+        "For the skill scripts, run c64-re-tools update in the project.",
+    };
+  }
+  return undefined;
+}
+
+export function invalid(message: string): never {
+  throw new WireFailure("invalid-input", message);
+}
+
+/** Refuses a field that is not in `allowed`, the same way for every operation. */
+export function onlyFields(value: Fields, allowed: readonly string[], where?: string): void {
+  for (const key of Object.keys(value)) {
+    if (!allowed.includes(key)) invalid(where === undefined ? `unknown field: ${key}` : `unknown field in ${where}: ${key}`);
+  }
+}

package/src/protocol/tools.ts

@@ -0,0 +1,247 @@
+// The native-tool operations of the Host Runtime wire ("tool" connections): their shapes and validators.
+
+import { textToPetsciiName, type BasicHandoff } from "../c64.ts";
+import { type Fields, invalid, isInteger, isObject, isOneOf, onlyFields, ProtocolError } from "./messages.ts";
+
+// ---------------------------------------------------------------------------
+// Native-tool operations. Short-lived requests on "tool" connections; they
+// never touch an emulator or knowledge.db.
+
+/** A transferred source tree: relative POSIX paths, one attachment per file in this order. */
+export type SourceTree = Array<{ path: string; size: number }>;
+export const MAX_TREE_FILES = 4096;
+
+export const DISK_IMAGE_TYPES = ["d64", "d71", "d81", "g64"] as const;
+export type DiskImageType = (typeof DISK_IMAGE_TYPES)[number];
+export const DISK_ACTIONS = ["directory", "bam", "entry", "chain", "read"] as const;
+export type DiskAction = (typeof DISK_ACTIONS)[number];
+export const CBM_FILE_TYPES = ["del", "seq", "prg", "usr", "rel", "unknown"] as const;
+export type CbmFileType = (typeof CBM_FILE_TYPES)[number];
+
+/** c1541.inspect. The image bytes are the request's one attachment. */
+export interface C1541Params {
+  action: DiskAction;
+  imageType: DiskImageType;
+  /** entry, chain and read only: the file name as petsciiNameToText shows it. */
+  name?: string;
+}
+
+export interface DiskFile {
+  name: string;
+  type: CbmFileType;
+  blocks: number;
+  closed: boolean;
+  locked: boolean;
+}
+
+export interface DiskSector {
+  track: number;
+  sector: number;
+}
+
+export type C1541Result =
+  | { action: "directory"; diskName: string; diskId: string; dosType: string; freeBlocks: number; entries: DiskFile[] }
+  | { action: "bam"; tracks: Array<{ track: number; freeSectors: number[]; usedSectors: number[] }> }
+  | { action: "entry"; found: false }
+  | { action: "entry"; found: true; entry: DiskFile & { startTrack: number; startSector: number } }
+  | { action: "chain"; found: false }
+  | { action: "chain"; found: true; sectors: DiskSector[] }
+  | { action: "read"; found: false }
+  /** The file's bytes are the reply's attachment. */
+  | { action: "read"; found: true; name: string; bytes: number };
+
+/** petcat.decode takes no fields: the program bytes are the request's one attachment. */
+export type PetcatParams = Record<string, never>;
+
+/** A machine-code handoff: SYS with a constant address, or SYS/USR whose target is computed at run time. */
+export type { BasicHandoff };
+
+export type PetcatResult =
+  | { decoded: false; reason: string }
+  | {
+      decoded: true;
+      loadAddress: number;
+      /** The address after the BASIC end marker; any bytes from here on are no BASIC. */
+      basicEnd: number;
+      listing: string;
+      lines: Array<{ number: number; text: string }>;
+      handoffs: BasicHandoff[];
+    };
+
+/** One native tool on the host, as host.status found and ran it. */
+export interface ToolStatus {
+  name: string;
+  found: boolean;
+  /** Where it is, when found. */
+  path?: string;
+  /** Its version text, when it ran. */
+  version?: string;
+  runs: boolean;
+  /** What is wrong and what to do, when it is missing or does not run. */
+  problem?: string;
+}
+
+export interface ToolOperations {
+  "host.status": { params: Record<string, never>; result: { tools: ToolStatus[] } };
+  "c1541.inspect": { params: C1541Params; result: C1541Result };
+  "petcat.decode": { params: PetcatParams; result: PetcatResult };
+}
+export type ToolOperation = keyof ToolOperations;
+export const TOOL_OPERATIONS = ["host.status", "c1541.inspect", "petcat.decode"] as const satisfies readonly ToolOperation[];
+
+const RELATIVE_PATH = /^(?!\/)(?!.*(?:^|\/)\.\.?(?:\/|$))[^\0\\]+$/;
+
+/** A relative POSIX path with no empty, "." or ".." segment and no backslash. */
+export function isRelativePath(value: unknown): value is string {
+  return typeof value === "string" && value.length <= 1024 && RELATIVE_PATH.test(value) && !value.includes("//") && !value.endsWith("/");
+}
+
+/** Validates a transferred source tree against its attachments. Throws WireFailure(invalid-input). */
+export function validateSourceTree(value: unknown, attachments: readonly Uint8Array[]): SourceTree {
+  if (!Array.isArray(value) || value.length > MAX_TREE_FILES) invalid(`files must list at most ${MAX_TREE_FILES} files`);
+  if (value.length !== attachments.length) invalid("each listed file needs exactly one attachment");
+  const seen = new Set<string>();
+  return value.map((entry, index) => {
+    if (!isObject(entry) || !isRelativePath(entry.path)) invalid("each file needs a relative path inside the source root");
+    if (seen.has(entry.path)) invalid(`the file ${entry.path} is listed twice`);
+    seen.add(entry.path);
+    if (entry.size !== attachments[index]!.length) invalid(`the size of ${entry.path} does not match its bytes`);
+    return { path: entry.path, size: entry.size as number };
+  });
+}
+
+/** Refuses anything but exactly one attachment with at least one byte, named by what it must hold. */
+function oneFile(attachments: readonly Uint8Array[], what: string): void {
+  if (attachments.length !== 1 || attachments[0]!.length === 0) invalid(`${what} must be the one attachment, and it must not be empty`);
+}
+
+/** Validates tool request parameters on the host. Throws WireFailure(invalid-input). */
+export function validateToolParams<O extends ToolOperation>(op: O, params: unknown, attachments: readonly Uint8Array[]): ToolOperations[O]["params"] {
+  if (!isObject(params)) invalid("parameters must be an object");
+  switch (op) {
+    case "c1541.inspect": {
+      onlyFields(params, ["action", "imageType", "name"]);
+      if (!isOneOf(DISK_ACTIONS, params.action)) invalid(`action must be one of ${DISK_ACTIONS.join(", ")}`);
+      if (!isOneOf(DISK_IMAGE_TYPES, params.imageType)) invalid(`imageType must be one of ${DISK_IMAGE_TYPES.join(", ")}`);
+      oneFile(attachments, "the disk image");
+      const result: C1541Params = { action: params.action, imageType: params.imageType };
+      const named = params.action === "entry" || params.action === "chain" || params.action === "read";
+      if (!named) {
+        if (params.name !== undefined) invalid(`action ${params.action} takes no name`);
+      } else {
+        if (typeof params.name !== "string" || params.name.length === 0) invalid(`action ${params.action} needs a file name`);
+        let bytes: Uint8Array;
+        try {
+          bytes = textToPetsciiName(params.name);
+        } catch (error) {
+          return invalid(`name: ${(error as Error).message}`);
+        }
+        if (bytes.length > 16) invalid("a CBM file name has at most 16 characters");
+        result.name = params.name;
+      }
+      return result as ToolOperations[O]["params"];
+    }
+    case "petcat.decode": {
+      onlyFields(params, []);
+      oneFile(attachments, "the program");
+      return {} as ToolOperations[O]["params"];
+    }
+    case "host.status":
+      onlyFields(params, []);
+      if (attachments.length !== 0) invalid("host.status takes no attachment");
+      return {} as ToolOperations[O]["params"];
+  }
+  return invalid(`unknown tool operation: ${String(op)}`);
+}
+
+/** Validates a tool result on the client. Throws ProtocolError. */
+export function validateToolResult<O extends ToolOperation>(op: O, value: unknown, attachments: readonly Uint8Array[]): ToolOperations[O]["result"] {
+  if (!isObject(value)) throw new ProtocolError(`${op} result is not an object`);
+  switch (op) {
+    case "c1541.inspect": {
+      if (!isC1541Result(value, attachments)) throw new ProtocolError("c1541.inspect result is malformed");
+      return value as unknown as ToolOperations[O]["result"];
+    }
+    case "petcat.decode": {
+      if (!isPetcatResult(value) || attachments.length !== 0) throw new ProtocolError("petcat.decode result is malformed");
+      return value as unknown as ToolOperations[O]["result"];
+    }
+    case "host.status": {
+      const tools = value.tools;
+      const isStatus = (tool: unknown) =>
+        isObject(tool) &&
+        typeof tool.name === "string" &&
+        typeof tool.found === "boolean" &&
+        typeof tool.runs === "boolean" &&
+        [tool.path, tool.version, tool.problem].every((field) => field === undefined || typeof field === "string");
+      if (!Array.isArray(tools) || !tools.every(isStatus) || attachments.length !== 0) throw new ProtocolError("host.status result is malformed");
+      return value as unknown as ToolOperations[O]["result"];
+    }
+  }
+  throw new ProtocolError(`unknown tool operation: ${String(op)}`);
+}
+
+const isTrackSector = (value: unknown): boolean => isObject(value) && isInteger(value.track, 0, 255) && isInteger(value.sector, 0, 255);
+const isSectorList = (value: unknown): boolean => Array.isArray(value) && value.every((item) => isInteger(item, 0, 255));
+
+function isDiskFile(value: unknown): value is DiskFile {
+  return (
+    isObject(value) &&
+    typeof value.name === "string" &&
+    isOneOf(CBM_FILE_TYPES, value.type) &&
+    isInteger(value.blocks, 0, 0xffff) &&
+    typeof value.closed === "boolean" &&
+    typeof value.locked === "boolean"
+  );
+}
+
+function isC1541Result(value: Fields, attachments: readonly Uint8Array[]): boolean {
+  const carries = value.action === "read" && value.found === true ? 1 : 0;
+  if (attachments.length !== carries) return false;
+  switch (value.action) {
+    case "directory":
+      return (
+        typeof value.diskName === "string" &&
+        typeof value.diskId === "string" &&
+        typeof value.dosType === "string" &&
+        isInteger(value.freeBlocks, 0, 0xffff) &&
+        Array.isArray(value.entries) &&
+        value.entries.every(isDiskFile)
+      );
+    case "bam":
+      return (
+        Array.isArray(value.tracks) &&
+        value.tracks.every((track) => isObject(track) && isInteger(track.track, 1, 255) && isSectorList(track.freeSectors) && isSectorList(track.usedSectors))
+      );
+    case "entry":
+      return (
+        value.found === false ||
+        (value.found === true && isObject(value.entry) && isDiskFile(value.entry) && isTrackSector({ track: value.entry.startTrack, sector: value.entry.startSector }))
+      );
+    case "chain":
+      return value.found === false || (value.found === true && Array.isArray(value.sectors) && value.sectors.every(isTrackSector));
+    case "read":
+      return value.found === false || (value.found === true && typeof value.name === "string" && value.bytes === attachments[0]!.length);
+  }
+  return false;
+}
+
+function isPetcatResult(value: Fields): boolean {
+  if (value.decoded === false) return typeof value.reason === "string";
+  const isLine = (line: unknown) => isObject(line) && isInteger(line.number, 0, 0xffff) && typeof line.text === "string";
+  const isHandoff = (handoff: unknown) =>
+    isObject(handoff) &&
+    isInteger(handoff.line, 0, 0xffff) &&
+    ((handoff.kind === "sys" && isInteger(handoff.address, 0, 0xffff) && handoff.computed === undefined) ||
+      ((handoff.kind === "sys" || handoff.kind === "usr") && handoff.computed === true && handoff.address === undefined));
+  return (
+    value.decoded === true &&
+    isInteger(value.loadAddress, 0, 0xffff) &&
+    isInteger(value.basicEnd, 0, 0x10000) &&
+    typeof value.listing === "string" &&
+    Array.isArray(value.lines) &&
+    value.lines.every(isLine) &&
+    Array.isArray(value.handoffs) &&
+    value.handoffs.every(isHandoff)
+  );
+}