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

package/src/host/vice/text-monitor.ts

@@ -0,0 +1,223 @@
+// VICE remote text monitor client, used only for operations the binary monitor
+// cannot do (warp, file load/attach, checkpoint ignore counts, device switch).
+// Raw monitor syntax never leaves src/host/vice.
+//
+// Framing: every command ends with a prompt
+// such as "(C:$e5cf) ", but a command that makes VICE enter the monitor gets
+// an extra prompt first. So prompts cannot delimit answers. Each command is
+// followed by a sentinel `~ $nnnn` whose distinctive four-line answer marks
+// where the command's own output ends. The sentinel is sent only after a
+// prompt shows the command was taken: VICE drops the rest of an input chunk
+// when the command in it makes VICE enter the monitor. Only idempotent
+// commands go through here (see resendAfterMs).
+//
+// VICE sometimes reads a line but runs it only when more input comes. So a
+// late sentinel is sent again, and stray sentinel answers are removed from
+// output. The second answer of a resent sentinel can arrive in parts, while
+// the next command starts: that command waits until the answer is whole
+// before it drops what is left over, so no part of it is read as output. VICE also prints its step message here when the binary monitor
+// steps, sometimes after the next text command was sent; no command of this
+// client steps, so that message is removed from output too.
+
+import type { Socket } from "node:net";
+
+import { connectWithTimeout } from "./connect.ts";
+
+export class TextMonitorError extends Error {
+  override name = "TextMonitorError";
+}
+
+/** A command got no answer in time, but the connection is open; it may still run later. */
+export class TextMonitorTimeoutError extends TextMonitorError {
+  override name = "TextMonitorTimeoutError";
+}
+
+const PROMPT = /\((?:C|\d+):\$[0-9a-f]{4}\) /g;
+export const DEFAULT_COMMAND_TIMEOUT_MS = 10_000;
+/** The default of TextMonitor.resendAfterMs. */
+const RESEND_AFTER_MS = 3_000;
+/** The default of TextMonitor.overdueTimeoutMs. */
+const OVERDUE_COMMAND_TIMEOUT_MS = 1_000;
+/** The default of TextMonitor.sentinelResendMs. */
+const SENTINEL_RESEND_MS = 1_000;
+/** The longest delay a Node timer takes. */
+const MAX_TIMER_MS = 2_147_483_647;
+const ANY_SENTINEL_ANSWER = /\+\d+\n\$[0-9a-f]{4}\n[0-7]+\n%[01 ]+\n/g;
+const STEP_MESSAGE = /^Stepping through the next \d+ instruction\(s\)\.\n/gm;
+
+function sentinelPattern(nonce: number): RegExp {
+  const hex = nonce.toString(16).padStart(4, "0");
+  return new RegExp(`\\+${nonce}\\n\\$${hex}\\n[0-7]+\\n%[01 ]+\\n\\((?:C|\\d+):\\$[0-9a-f]{4}\\) `);
+}
+
+/** Strips prompts, stray sentinel answers, step messages and surrounding blank space from a command's raw output. */
+export function cleanOutput(raw: string): string {
+  return raw.replace(/\r/g, "").replace(ANY_SENTINEL_ANSWER, "").replace(STEP_MESSAGE, "").replace(PROMPT, "").trim();
+}
+
+export class TextMonitor {
+  readonly closed: Promise<Error | undefined>;
+  readonly #socket: Socket;
+  #buffer = "";
+  #wake: (() => void) | undefined;
+  #queue: Promise<unknown> = Promise.resolve();
+  #nonce = 0x1000 + Math.floor(Math.random() * 0x1000);
+  #closedByUs = false;
+  #failure: Error | undefined;
+  /** The time limit of a command that names none. */
+  defaultTimeoutMs = DEFAULT_COMMAND_TIMEOUT_MS;
+  /**
+   * How long to wait for any answer before sending the command once more.
+   * VICE sometimes holds a command line until more input comes; every
+   * command this client sends is idempotent, so a repeat is harmless. A
+   * command that has printed output but no prompt yet still runs, and is not
+   * sent again.
+   */
+  resendAfterMs = RESEND_AFTER_MS;
+  /** How long to wait for a sentinel's answer before sending the sentinel again. */
+  sentinelResendMs = SENTINEL_RESEND_MS;
+  /** While an earlier command timed out, later ones are waited for only this long (see BinaryMonitor). */
+  overdueTimeoutMs = OVERDUE_COMMAND_TIMEOUT_MS;
+  /** Set when a command timed out; cleared by the next command that is answered. */
+  #overdue = false;
+  /** The answers that a resent sentinel of the last command can still give. */
+  #strays: { nonce: number; count: number } | undefined;
+
+  private constructor(socket: Socket) {
+    this.#socket = socket;
+    socket.setNoDelay(true);
+    socket.on("data", (chunk) => {
+      this.#buffer += chunk.toString("latin1");
+      this.#wake?.();
+    });
+    socket.on("error", (error) => (this.#failure ??= new TextMonitorError(`text monitor connection failed: ${error.message}`)));
+    this.closed = new Promise((resolve) => {
+      socket.on("close", () => {
+        this.#wake?.();
+        resolve(this.#closedByUs ? undefined : (this.#failure ?? new TextMonitorError("VICE closed the text monitor connection")));
+      });
+    });
+  }
+
+  static connect(port: number, host = "127.0.0.1", timeoutMs = 2_000): Promise<TextMonitor> {
+    return connectWithTimeout({
+      port,
+      host,
+      timeoutMs,
+      wrap: (socket) => new TextMonitor(socket),
+      failure: (message) => new TextMonitorError(`text monitor ${message}`),
+    });
+  }
+
+  /**
+   * Runs one idempotent command and returns its output without prompts.
+   * Commands run one at a time. A command makes VICE stop the machine if it
+   * was running. `timeoutMs` Infinity waits with no limit, also after a
+   * command that timed out.
+   */
+  command(line: string, timeoutMs = this.defaultTimeoutMs): Promise<string> {
+    if (/[\r\n]/.test(line)) return Promise.reject(new TypeError("a monitor command must be one line"));
+    const run = this.#queue.then(async () => {
+      try {
+        const limit = this.#overdue && timeoutMs !== Infinity ? Math.min(timeoutMs, this.overdueTimeoutMs) : timeoutMs;
+        const output = await this.#exchange(line, limit);
+        this.#overdue = false;
+        return output;
+      } catch (error) {
+        if (error instanceof TextMonitorTimeoutError) this.#overdue = true;
+        throw error;
+      }
+    });
+    this.#queue = run.catch(() => {});
+    return run;
+  }
+
+  close(): Promise<void> {
+    this.#closedByUs = true;
+    this.#socket.destroy();
+    return this.closed.then(() => {});
+  }
+
+  async #exchange(line: string, timeoutMs: number): Promise<string> {
+    if (this.#socket.destroyed) throw new TextMonitorError("text monitor connection is closed");
+    this.#nonce = this.#nonce >= 0xfffe ? 0x1000 : this.#nonce + 1;
+    const sentinel = sentinelPattern(this.#nonce);
+    const deadline = Date.now() + timeoutMs;
+    await this.#settleStrays(deadline, timeoutMs);
+    // Anything left over belongs to no command; drop it so it cannot be misread.
+    this.#buffer = "";
+    this.#socket.write(`${line}\n`);
+    const prompted = () => new RegExp(PROMPT.source).exec(this.#buffer);
+    const resendAt = Math.min(deadline, Date.now() + this.resendAfterMs);
+    try {
+      await this.#waitFor(prompted, resendAt, timeoutMs);
+    } catch (error) {
+      if (this.#socket.destroyed || Date.now() >= deadline) throw error;
+      // Output without a prompt: VICE runs the command and still prints. A repeat would run it twice.
+      if (cleanOutput(this.#buffer) === "") this.#socket.write(`${line}\n`);
+      await this.#waitFor(prompted, deadline, timeoutMs);
+    }
+    const sentinelLine = `~ $${this.#nonce.toString(16)}\n`;
+    let sends = 0;
+    for (;;) {
+      this.#socket.write(sentinelLine);
+      sends++;
+      let found: RegExpExecArray;
+      try {
+        found = await this.#waitFor(() => sentinel.exec(this.#buffer), Math.min(deadline, Date.now() + this.sentinelResendMs), timeoutMs);
+      } catch (error) {
+        if (this.#socket.destroyed || Date.now() >= deadline) throw error;
+        continue;
+      }
+      const output = this.#buffer.slice(0, found.index);
+      this.#buffer = this.#buffer.slice(found.index + found[0].length);
+      this.#strays = sends > 1 ? { nonce: this.#nonce, count: sends - 1 } : undefined;
+      return cleanOutput(output);
+    }
+  }
+
+  /**
+   * Waits a short time for the answers that a resent sentinel of the last
+   * command can still give, and until an answer that has begun is whole. An
+   * answer that VICE holds until more input comes arrives whole inside the
+   * next command's output, where cleanOutput removes it.
+   */
+  async #settleStrays(deadline: number, timeoutMs: number): Promise<void> {
+    const strays = this.#strays;
+    this.#strays = undefined;
+    if (strays === undefined) return;
+    const whole = new RegExp(sentinelPattern(strays.nonce).source, "g");
+    const begun = new RegExp(`\\+${strays.nonce}\\b|\\+\\d*$`);
+    const complete = () => ((this.#buffer.match(whole)?.length ?? 0) >= strays.count ? true : null);
+    const partial = () => begun.test(this.#buffer.replace(whole, ""));
+    try {
+      await this.#waitFor(complete, Math.min(deadline, Date.now() + this.sentinelResendMs), timeoutMs);
+    } catch (error) {
+      if (!(error instanceof TextMonitorTimeoutError)) throw error;
+      if (partial()) await this.#waitFor(() => (partial() ? null : true), deadline, timeoutMs);
+    }
+  }
+
+  /** Waits until `probe` finds something in the received text, and returns what it found. */
+  async #waitFor<T>(probe: () => T | null, deadline: number, timeoutMs: number): Promise<T> {
+    for (;;) {
+      const found = probe();
+      if (found !== null) return found;
+      if (this.#socket.destroyed) throw new TextMonitorError("text monitor connection closed during a command");
+      const remaining = deadline - Date.now();
+      if (remaining <= 0) {
+        // The raw tail goes to the host log only; it is never shown to the LLM.
+        throw new TextMonitorTimeoutError(`text monitor command got no answer in ${timeoutMs} ms (received: ${JSON.stringify(this.#buffer.slice(-200))})`);
+      }
+      await new Promise<void>((resolve) => {
+        // No timer for a wait with no limit; a timer longer than Node allows would fire at once.
+        const timer = remaining === Infinity ? undefined : setTimeout(resolve, Math.min(remaining, MAX_TIMER_MS));
+        this.#wake = () => {
+          clearTimeout(timer);
+          resolve();
+        };
+      });
+      this.#wake = undefined;
+    }
+  }
+}

package/src/host-client/connect.ts

@@ -0,0 +1,241 @@
+// Deterministic connection to the Host Runtime and the version handshake.
+
+import { connect as connectTcp, type Socket } from "node:net";
+
+import { encodeFrame, MessageReader } from "../protocol/framing.ts";
+import { elapsedMs, trace } from "../trace.ts";
+import { DEFAULT_HOST_PORT, HEARTBEAT_INTERVAL_MS, HEARTBEAT_TIMEOUT_MS, HOST_PROTOCOL_ID, HOST_PROTOCOL_VERSION, parseHostMessage, ProtocolError, WireFailure, type ErrorCode, type Hello, type HostMessage, type Ping, type Request, type Role, type VideoStandard } from "../protocol/messages.ts";
+
+export interface Endpoint {
+  host: string;
+  port: number;
+}
+
+/** How long one endpoint may take to accept a TCP connection. */
+const CONNECT_TIMEOUT_MS = 1_500;
+/**
+ * How long the host may take to answer hello. A VICE session starts its
+ * emulator first, and the host tries the start up to three times.
+ */
+export const DEFAULT_READY_TIMEOUT_MS = 120_000;
+
+/**
+ * The endpoints to try, in order: C64RT_HOST=host:port alone when set,
+ * else loopback, then the Docker and Podman host bridges.
+ */
+export function hostEndpoints(env: NodeJS.ProcessEnv = process.env): Endpoint[] {
+  const override = env.C64RT_HOST;
+  if (override !== undefined && override !== "") {
+    const match = /^(?:\[([^\]]+)\]|([^:]+)):(\d{1,5})$/.exec(override);
+    const port = match === null ? NaN : Number(match[3]);
+    if (match === null || !(port > 0 && port <= 0xffff)) {
+      throw new WireFailure("installation-incomplete", "C64RT_HOST must have the form host:port, for example 127.0.0.1:6464.");
+    }
+    return [{ host: match[1] ?? match[2]!, port }];
+  }
+  return ["127.0.0.1", "host.docker.internal", "host.containers.internal"].map((host) => ({ host, port: DEFAULT_HOST_PORT }));
+}
+
+function unreachable(role: Role): WireFailure {
+  const code: ErrorCode = role === "vice-session" ? "machine-unavailable" : "operation-failed";
+  return new WireFailure(
+    code,
+    "The c64-re-tools host runtime is not running or cannot be reached. Start it on the host (npx -y --package=@henols/c64-re-tools@latest c64-re-tools-host) and try again.",
+  );
+}
+
+function stopped(role: Role): WireFailure {
+  return new WireFailure(
+    role === "vice-session" ? "machine-unavailable" : "operation-failed",
+    "The connection to the c64-re-tools host runtime stopped before the host runtime was ready.",
+  );
+}
+
+/** Resolves undefined when the endpoint refuses, does not answer in time, or `signal` stops the attempt. */
+function tcpConnect(endpoint: Endpoint, signal: AbortSignal | undefined): Promise<Socket | undefined> {
+  return new Promise((resolve) => {
+    const socket = connectTcp({ host: endpoint.host, port: endpoint.port });
+    const fail = () => finish(undefined);
+    const finish = (result: Socket | undefined) => {
+      clearTimeout(timer);
+      signal?.removeEventListener("abort", fail);
+      if (result === undefined) socket.destroy();
+      resolve(result);
+    };
+    const timer = setTimeout(fail, CONNECT_TIMEOUT_MS);
+    signal?.addEventListener("abort", fail, { once: true });
+    socket.once("connect", () => {
+      socket.removeAllListeners("error");
+      finish(socket);
+    });
+    socket.once("error", fail);
+  });
+}
+
+/** A handshaken, framed connection to the Host Runtime. */
+export class HostConnection {
+  /** Settles when the connection is gone; carries the reason unless we closed it. */
+  readonly closed: Promise<Error | undefined>;
+  readonly #socket: Socket;
+  readonly #reader = new MessageReader();
+  #listener: ((message: HostMessage, attachments: Buffer[]) => void) | undefined;
+  #failure: Error | undefined;
+  #closedByUs = false;
+  #pingTimer: NodeJS.Timeout | undefined;
+  #silenceTimer: NodeJS.Timeout | undefined;
+  #heartbeat = false;
+
+  private constructor(socket: Socket) {
+    this.#socket = socket;
+    socket.setNoDelay(true);
+    socket.setKeepAlive(true, 10_000);
+    this.closed = new Promise((resolve) => {
+      socket.on("close", () => {
+        const reason = this.#closedByUs ? undefined : (this.#failure ?? new Error("the host runtime closed the connection"));
+        trace().event("host.closed", { byUs: this.#closedByUs, reason });
+        resolve(reason);
+      });
+    });
+    socket.on("error", (error) => (this.#failure ??= error));
+    socket.on("close", () => {
+      clearInterval(this.#pingTimer);
+      clearTimeout(this.#silenceTimer);
+    });
+    socket.on("data", (chunk) => {
+      this.#restartSilence();
+      try {
+        for (const { message, attachments } of this.#reader.push(chunk)) {
+          const parsed = parseHostMessage(message);
+          if (parsed.type !== "pong") this.#listener?.(parsed, attachments);
+        }
+      } catch (error) {
+        // A broken frame, or a listener that throws, ends the connection with a
+        // reason; nothing escapes the socket handler.
+        this.#failure =
+          error instanceof ProtocolError
+            ? error
+            : new Error(`could not handle a message from the host runtime: ${error instanceof Error ? error.message : String(error)}`);
+        socket.destroy();
+      }
+    });
+  }
+
+  /**
+   * Connects to the first endpoint that accepts, then handshakes. Once an
+   * endpoint accepts, its answer is final: no later endpoint is tried.
+   */
+  static async open(options: {
+    role: Role;
+    videoStandard?: VideoStandard;
+    env?: NodeJS.ProcessEnv;
+    /** Stops the connect and the handshake at once; the open then fails and its socket is closed. */
+    signal?: AbortSignal;
+  }): Promise<HostConnection> {
+    const signal = options.signal;
+    const started = performance.now();
+    let socket: Socket | undefined;
+    for (const endpoint of hostEndpoints(options.env)) {
+      if (signal?.aborted) break;
+      const attempt = performance.now();
+      socket = await tcpConnect(endpoint, signal);
+      trace().event("host.connect", { ...endpoint, role: options.role, accepted: socket !== undefined, ms: elapsedMs(attempt) });
+      if (socket !== undefined) break;
+    }
+    if (signal?.aborted) {
+      socket?.destroy();
+      throw stopped(options.role);
+    }
+    if (socket === undefined) throw unreachable(options.role);
+
+    const connection = new HostConnection(socket);
+    const hello: Hello = { type: "hello", protocol: HOST_PROTOCOL_ID, version: HOST_PROTOCOL_VERSION, role: options.role };
+    if (options.videoStandard !== undefined) hello.videoStandard = options.videoStandard;
+    // A host that listens beyond loopback checks this shared secret.
+    const token = (options.env ?? process.env).C64RT_HOST_TOKEN;
+    if (token !== undefined && token !== "") hello.token = token;
+
+    const stop = () => void connection.close();
+    signal?.addEventListener("abort", stop, { once: true });
+    const answer = await new Promise<HostMessage | Error>((resolve) => {
+      const timer = setTimeout(() => resolve(new Error("no answer to hello in time")), DEFAULT_READY_TIMEOUT_MS);
+      connection.#listener = (message) => {
+        clearTimeout(timer);
+        resolve(message);
+      };
+      void connection.closed.then((reason) => {
+        clearTimeout(timer);
+        resolve(reason ?? new Error("closed"));
+      });
+      connection.#send(hello);
+    });
+    connection.#listener = undefined;
+    signal?.removeEventListener("abort", stop);
+    if (signal?.aborted) {
+      await connection.close();
+      throw stopped(options.role);
+    }
+
+    if (!(answer instanceof Error) && answer.type === "ready") {
+      trace().event("host.ready", { role: options.role, ms: elapsedMs(started) });
+      connection.#startHeartbeat();
+      return connection;
+    }
+    trace().event("host.handshake-failed", { role: options.role, ms: elapsedMs(started), ...(answer instanceof Error ? { error: answer } : answer) });
+    await connection.close();
+    if (answer instanceof Error) {
+      if (answer instanceof ProtocolError) {
+        throw new WireFailure(
+          "installation-incomplete",
+          "The c64-re-tools host runtime is from another release. Stop the host runtime and start it again with npx, then restart the agent session. npx then starts the newest release on both sides.",
+        );
+      }
+      throw new WireFailure(
+        options.role === "vice-session" ? "machine-unavailable" : "operation-failed",
+        "The c64-re-tools host runtime did not finish the handshake. Check that it is running and try again.",
+      );
+    }
+    if (answer.type === "error") throw new WireFailure(answer.error.code, answer.error.message);
+    throw new WireFailure("installation-incomplete", "The c64-re-tools host runtime answered out of turn. Install the same c64-re-tools release on both sides.");
+  }
+
+  /** Receives every message after the handshake, with any attachments. */
+  onMessage(listener: (message: HostMessage, attachments: Buffer[]) => void): void {
+    this.#listener = listener;
+  }
+
+  send(request: Request, attachments: readonly Uint8Array[] = []): void {
+    if (!this.#socket.destroyed) this.#socket.write(encodeFrame(request, attachments));
+  }
+
+  close(): Promise<void> {
+    this.#closedByUs = true;
+    this.#socket.destroy();
+    return this.closed.then(() => {});
+  }
+
+  /**
+   * Pings the host so it knows this client is alive, and closes the connection
+   * when the host has sent nothing for the timeout: a host that vanished
+   * without a close then fails like a closed one. The timers never keep
+   * the process alive.
+   */
+  #startHeartbeat(): void {
+    this.#heartbeat = true;
+    const ping: Ping = { type: "ping" };
+    this.#pingTimer = setInterval(() => this.#send(ping), HEARTBEAT_INTERVAL_MS).unref();
+    this.#restartSilence();
+  }
+
+  #restartSilence(): void {
+    if (!this.#heartbeat || this.#socket.destroyed) return;
+    clearTimeout(this.#silenceTimer);
+    this.#silenceTimer = setTimeout(() => {
+      this.#failure ??= new Error(`the host runtime sent nothing for ${HEARTBEAT_TIMEOUT_MS} ms`);
+      this.#socket.destroy();
+    }, HEARTBEAT_TIMEOUT_MS).unref();
+  }
+
+  #send(message: Hello | Request | Ping): void {
+    if (!this.#socket.destroyed) this.#socket.write(encodeFrame(message));
+  }
+}

package/src/host-client/tools.ts

@@ -0,0 +1,89 @@
+// Short-lived typed requests to the Host Runtime for skill scripts:
+// VICE's own tools (c1541, petcat) and the host tool status. Each request
+// opens its own "tool" connection, sends bytes, and closes. Skill scripts run
+// ACME, DXA and Ghidra themselves through src/native.
+
+import { ProtocolError, WireFailure } from "../protocol/messages.ts";
+import { DISK_IMAGE_TYPES, validateToolResult, type C1541Result, type DiskAction, type DiskImageType, type PetcatResult, type ToolOperation, type ToolOperations, type ToolStatus } from "../protocol/tools.ts";
+import { HostConnection } from "./connect.ts";
+import { readProjectFile } from "./transfer.ts";
+
+export interface ToolCallOptions {
+  env?: NodeJS.ProcessEnv;
+}
+
+/** Sends one tool request and returns its validated result and attachments. */
+export async function callTool<O extends ToolOperation>(
+  op: O,
+  params: ToolOperations[O]["params"],
+  attachments: readonly Uint8Array[],
+  options: ToolCallOptions = {},
+): Promise<{ result: ToolOperations[O]["result"]; attachments: Buffer[] }> {
+  const connection = await HostConnection.open({ role: "tool", ...(options.env === undefined ? {} : { env: options.env }) });
+  try {
+    return await new Promise((resolve, reject) => {
+      connection.onMessage((message, received) => {
+        if (message.type !== "reply" || message.id !== 1) {
+          reject(new WireFailure("installation-incomplete", "The c64-re-tools host runtime answered out of turn. Install the same c64-re-tools release on both sides."));
+          return;
+        }
+        if ("error" in message) {
+          reject(new WireFailure(message.error.code, message.error.message));
+          return;
+        }
+        try {
+          resolve({ result: validateToolResult(op, message.result, received), attachments: received });
+        } catch (error) {
+          reject(
+            new WireFailure(
+              "operation-failed",
+              error instanceof ProtocolError ? "The c64-re-tools host runtime sent an invalid reply." : "The c64-re-tools host-client could not read the reply of the host runtime.",
+            ),
+          );
+        }
+      });
+      void connection.closed.then(() =>
+        reject(new WireFailure("operation-failed", "The connection to the c64-re-tools host runtime was lost during the request. Check that the Host Runtime (c64-re-tools-host) is running.")),
+      );
+      connection.send({ type: "request", id: 1, op, params }, attachments);
+    });
+  } finally {
+    await connection.close();
+  }
+}
+
+export interface InspectDiskRequest {
+  /** Project-relative disk image; its extension gives the image type. */
+  image: string;
+  action: DiskAction;
+  /** entry, chain and read: the file name as the directory shows it. */
+  name?: string;
+}
+
+/** c1541.inspect: a found read also returns the file's bytes. */
+export async function inspectDisk(request: InspectDiskRequest, options: ToolCallOptions = {}): Promise<C1541Result & { data?: Buffer }> {
+  const file = readProjectFile(request.image);
+  if (!(DISK_IMAGE_TYPES as readonly string[]).includes(file.type)) {
+    throw new WireFailure("invalid-input", `${request.image} is not a disk image that this tool reads. Use a .d64, .d71, .d81 or .g64 file.`);
+  }
+  const params: ToolOperations["c1541.inspect"]["params"] = { action: request.action, imageType: file.type as DiskImageType };
+  if (request.name !== undefined) params.name = request.name;
+  const { result, attachments } = await callTool("c1541.inspect", params, [file.bytes], options);
+  return result.action === "read" && result.found ? { ...result, data: attachments[0]! } : result;
+}
+
+/** petcat.decode: the C64 BASIC V2 listing of a project program and its machine-code handoffs. */
+export async function decodeBasic(request: { program: string }, options: ToolCallOptions = {}): Promise<PetcatResult> {
+  const file = readProjectFile(request.program);
+  return (await callTool("petcat.decode", {}, [file.bytes], options)).result;
+}
+
+/** host.status: each native tool on the host, found and run once. */
+export async function hostTools(options: ToolCallOptions = {}): Promise<ToolStatus[]> {
+  return (await callTool("host.status", {}, [], options)).result.tools;
+}
+
+/** Skill scripts see failures and wire limits through the host-client, never the private protocol module. */
+export { WireFailure } from "../protocol/messages.ts";
+export { DISK_ACTIONS } from "../protocol/tools.ts";
+export { JOYSTICK_DIRECTIONS, MAX_BASELINES, MAX_EXECUTION_COUNT, MAX_KEYBOARD_BYTES, MAX_MASK_RECTANGLES, MAX_MEMORY_READ, MAX_MEMORY_WRITE, MAX_TIMEOUT_FRAMES } from "../protocol/vice.ts";

package/src/host-client/transfer.ts

@@ -0,0 +1,100 @@
+// Reads project files on the client side for transfer to the Host Runtime.
+// The host never sees a client path: only bytes and the file's type.
+
+import { readdirSync, readFileSync, realpathSync, statSync } from "node:fs";
+import { extname, join, relative, sep } from "node:path";
+
+import { isInside, projectRoot, resolveProjectFile } from "../project.ts";
+import { MAX_ATTACHMENT_BYTES } from "../protocol/framing.ts";
+import { WireFailure } from "../protocol/messages.ts";
+import { MAX_TREE_FILES, type SourceTree } from "../protocol/tools.ts";
+
+export interface ProjectFile {
+  bytes: Buffer;
+  /** Lowercase extension without the dot; empty when the file has none. */
+  type: string;
+}
+
+/**
+ * Reads one project file. Throws WireFailure: invalid-input for a path the
+ * project rules refuse, not-found when nothing is there, limit-exceeded when
+ * the file is too large to transfer.
+ */
+export function readProjectFile(path: string, options: { root?: string } = {}): ProjectFile {
+  const root = options.root ?? projectRoot();
+  let real: string;
+  try {
+    real = resolveProjectFile(path, root);
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code === "ENOENT") {
+      throw new WireFailure("not-found", `There is no file at ${path} in the project directory.`);
+    }
+    if (error instanceof TypeError) {
+      throw new WireFailure("invalid-input", `${path}: give a path relative to the project directory that stays inside it.`);
+    }
+    throw error;
+  }
+  const stat = statSync(real);
+  if (!stat.isFile()) throw new WireFailure("invalid-input", `${path} is not a file.`);
+  if (stat.size > MAX_ATTACHMENT_BYTES) {
+    throw new WireFailure("limit-exceeded", `${path} has ${stat.size} bytes. The limit is ${MAX_ATTACHMENT_BYTES} bytes.`);
+  }
+  return { bytes: readFileSync(real), type: extname(path).slice(1).toLowerCase() };
+}
+
+/** Directories never staged: version control and the toolkit's own project state. */
+const SKIPPED_DIRECTORIES = new Set([".git", ".hg", ".svn", ".c64-re-tools"]);
+
+/**
+ * Reads a project directory as a source tree for staging: ordinary
+ * files with relative POSIX paths. A symbolic link is followed only when its
+ * target stays inside the source root; otherwise the tree is refused.
+ */
+export function readProjectTree(path: string, options: { root?: string } = {}): { files: SourceTree; contents: Buffer[] } {
+  const projectRootPath = options.root ?? projectRoot();
+  let sourceRoot: string;
+  try {
+    sourceRoot = resolveProjectFile(path, projectRootPath);
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code === "ENOENT") throw new WireFailure("not-found", `There is no directory ${path} in the project directory.`);
+    if (error instanceof TypeError) throw new WireFailure("invalid-input", `${path}: give a directory relative to the project directory that stays inside it.`);
+    throw error;
+  }
+  if (!statSync(sourceRoot).isDirectory()) throw new WireFailure("invalid-input", `${path} is not a directory.`);
+
+  const files: SourceTree = [];
+  const contents: Buffer[] = [];
+  let total = 0;
+  // `realDirectory` is where `directory` really is; `ancestors` holds the real
+  // location of every directory on the walk down to it, so a link to one of
+  // them is a loop.
+  const walk = (directory: string, realDirectory: string, ancestors: Set<string>): void => {
+    for (const entry of readdirSync(directory, { withFileTypes: true }).sort((a, b) => (a.name < b.name ? -1 : a.name > b.name ? 1 : 0))) {
+      const full = join(directory, entry.name);
+      let target = join(realDirectory, entry.name);
+      if (entry.isSymbolicLink()) {
+        target = realpathSync(full);
+        if (!isInside(sourceRoot, target)) {
+          throw new WireFailure("invalid-input", `${relative(projectRootPath, full)} links outside ${path}. Staging refuses a link that goes outside the source directory.`);
+        }
+      }
+      const stat = statSync(target);
+      if (stat.isDirectory()) {
+        if (SKIPPED_DIRECTORIES.has(entry.name)) continue;
+        if (ancestors.has(target)) {
+          throw new WireFailure("invalid-input", `${relative(projectRootPath, full)} points at a directory that contains it. Staging refuses a link loop.`);
+        }
+        walk(full, target, new Set(ancestors).add(target));
+        continue;
+      }
+      if (!stat.isFile()) continue;
+      if (files.length >= MAX_TREE_FILES) throw new WireFailure("limit-exceeded", `${path} has more than ${MAX_TREE_FILES} files.`);
+      total += stat.size;
+      if (total > MAX_ATTACHMENT_BYTES) throw new WireFailure("limit-exceeded", `${path} holds more than ${MAX_ATTACHMENT_BYTES} bytes.`);
+      files.push({ path: relative(sourceRoot, full).split(sep).join("/"), size: stat.size });
+      contents.push(readFileSync(target));
+    }
+  };
+  walk(sourceRoot, sourceRoot, new Set([sourceRoot]));
+  return { files, contents };
+}