@henols/c64-re-tools 1.0.0 → 2.0.0-rc.10

package/src/protocol/messages.ts

@@ -0,0 +1,259 @@
+// 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 = 3;
+/** 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. */
+/**
+ * The instruction at the end of a refusal that only the user can fix: a
+ * missing or broken tool, or a Host Runtime that does not run (D37).
+ */
+export const STOP_AND_ASK = "Stop the task. Give this message to the user and wait for the user. Do not make a replacement for the tool or the host runtime.";
+
+/** The message with STOP_AND_ASK at its end, once. */
+export function withStopAndAsk(message: string): string {
+  return message.endsWith(STOP_AND_ASK) ? message : `${message} ${STOP_AND_ASK}`;
+}
+
+/** The message that the agent sees for a refusal: an installation-incomplete one ends with STOP_AND_ASK. */
+export function shownMessage(error: { code: string; message: string }): string {
+  return error.code === "installation-incomplete" ? withStopAndAsk(error.message) : error.message;
+}
+
+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,266 @@
+// 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[] }
+  /** unreferenced: the used sectors that no file, the header, the directory or the BAM holds. */
+  | { action: "bam"; tracks: Array<{ track: number; freeSectors: number[]; usedSectors: number[] }>; unreferenced: DiskSector[] }
+  | { 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 first address that holds no BASIC: after a 00 00 end marker, or at a link whose high byte only is zero. */
+      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;
+  /** Known flaws of this version, each with the version that fixes it (D56). The tool still runs. */
+  flaws?: string[];
+}
+
+/** The Host Runtime itself: its package version and the system it runs on. */
+export interface HostInfo {
+  version: string;
+  /** Node's name of the operating system: linux, darwin or win32. */
+  platform: string;
+  /** The release of the operating system. */
+  release: string;
+  arch: string;
+}
+
+export interface ToolOperations {
+  "host.status": { params: Record<string, never>; result: { host: HostInfo; 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") &&
+        (tool.flaws === undefined || (Array.isArray(tool.flaws) && tool.flaws.every((flaw: unknown) => typeof flaw === "string")));
+      const host = value.host;
+      const isHost = isObject(host) && [host.version, host.platform, host.release, host.arch].every((field) => typeof field === "string");
+      if (!isHost || !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)) &&
+        Array.isArray(value.unreferenced) &&
+        value.unreferenced.every(isTrackSector)
+      );
+    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.computed === true && handoff.address === undefined && typeof handoff.expression === "string") ||
+      (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)
+  );
+}