@henols/vice-mcp 0.1.9 → 0.1.11

package/stock-registers.ts

@@ -0,0 +1,324 @@
+#!/usr/bin/env node
+// stock-registers.ts
+//
+// THE ONE place that resolves stock VICE's REGISTERS_AVAILABLE (0x83)
+// enumeration into a per-session register catalog, plus the three
+// vice_registers_* StockSessionHandlers built on it: the stock-only
+// vice_registers_available (enumeration) and the fork-compatible
+// vice_registers_get / vice_registers_set (value read/write).
+//
+// WHY THIS FILE EXISTS: REGISTERS_SET's wire body needs a numeric register
+// id (stock-protocol.ts's registersSetBody()), while the fork's
+// vice_registers_set takes a register NAME (D-03: stock keeps the fork's
+// argument shape). VICE enumerates its own register ids through
+// REGISTERS_AVAILABLE, and those ids are NOT guaranteed identical across
+// builds (docs/phase0-binmon-findings.md) -- so a caller must resolve a
+// name through the CONNECTED build's own answer, never a table this
+// module wrote down in advance. This file is the one seam that performs
+// that resolution, caches it per session (so every call after the first
+// is free), and exposes both the enumeration itself (planner decision,
+// recorded in 03-07-PLAN.md: a stock-only tool, not a field grafted onto
+// vice_registers_get's answer, because enumeration and value-reading are
+// different operations with different callers) and the two value
+// handlers that consume the resulting catalog.
+//
+// WHAT NOT TO DO:
+//   - Never hardcode VICE's internal register ids (PC/A/X/Y/SP/...) --
+//     they are enumerated by the wire, per memspace, and are not
+//     guaranteed identical across builds. A hardcoded table here is
+//     exactly the class of bug this file exists to make unreachable.
+//   - Never construct an ok-answer outside stockAnswer() (D-06) -- every
+//     answer this module returns must carry runState, and stockAnswer()
+//     is the one place that stamps it.
+//   - Never send an EXIT (0xaa) from this module (D-05) -- no handler
+//     here may resume a machine the agent did not ask to resume.
+//   - Never re-fetch the catalog per call. The catalog is cached on the
+//     session object itself (a fresh stockReconnect() hands back a NEW
+//     session object, so it naturally gets a fresh catalog with no
+//     manual invalidation needed) -- a handler that calls
+//     registerCatalogFor() more than once per session for the same
+//     enumeration is re-deriving the cache this function already is.
+//   - Never compare the catalog's `sizeBits` against a byte count (1 or 2).
+//     It is REGISTERS_AVAILABLE's own wire size byte, taken verbatim, and
+//     it is a BIT count (8 or 16 on a 6510) -- live evidence from genuine
+//     stock VICE 3.9 (03-UAT.md test 5): `PC size16`, `A size8`, `LIN
+//     size16`. The original width ladder read this as a byte count and
+//     refused every real register (03-14-PLAN.md); the field is named
+//     `sizeBits` specifically so the unit cannot be misread silently again.
+import { CommandType, memspaceBody, registersSetBody, type RegisterSetItem } from "./stock-protocol.ts";
+import { stockAnswer, convertWireError, isErrorText, type StockSessionHandler } from "./stock-handler.ts";
+import type { StockConnectSession } from "./stock-connect.ts";
+
+// ---------------------------------------------------------------------------
+// The per-session register catalog
+// ---------------------------------------------------------------------------
+
+export interface RegisterCatalog {
+  /** Keyed on the wire's own register NAME, uppercased -- the value keeps
+   * the wire's original spelling (`name`) for reporting, so an answer never
+   * silently re-cases what the emulator itself called the register.
+   * `sizeBits` is REGISTERS_AVAILABLE's own wire size byte, taken verbatim
+   * -- a BIT count (8/16 on a 6510), never a byte count. */
+  byName: Map<string, { id: number; sizeBits: number; name: string }>;
+  /** Keyed on the wire's numeric register id -- REGISTERS_GET/SET's own
+   * per-item identifier. */
+  byId: Map<number, { sizeBits: number; name: string }>;
+}
+
+/** The one module-level catalog map, keyed on the session object itself --
+ * NOT on session.client -- so a fresh stockReconnect() (which returns a
+ * brand-new session) is indistinguishable from "never fetched" and simply
+ * fetches again, with no manual invalidation path required anywhere. */
+// Single-line by design: the ONLY line in this file naming the garbage-
+// collectable, session-keyed map primitive directly (grep-gated -- see
+// this plan's own acceptance criteria). Every other reference goes
+// through this factory, never a second construction call site.
+function freshCatalogMap(): WeakMap<StockConnectSession, RegisterCatalog> { return new WeakMap<StockConnectSession, RegisterCatalog>(); }
+
+let catalogs = freshCatalogMap();
+
+/** Test-only: replaces the module-level catalog map with a fresh one,
+ * matching stock-runstate.ts's resetRunStateTrackersForTest() / this
+ * module tree's own beforeEach()-reset convention. */
+export function resetRegisterCatalogsForTest(): void {
+  catalogs = freshCatalogMap();
+}
+
+/**
+ * Resolves `session`'s register catalog, fetching it through
+ * REGISTERS_AVAILABLE (0x83) exactly once and caching the result on the
+ * session object. Every subsequent call for the SAME session object
+ * returns the cached catalog with no further wire traffic.
+ *
+ * Refuses (throws a plain Error, converted by the caller through
+ * convertWireError()) an empty enumeration rather than caching it: a
+ * build that enumerates zero registers cannot support
+ * vice_registers_set, and that failure must be visible on every call,
+ * never silently cached as "zero registers, nothing to resolve".
+ */
+export async function registerCatalogFor(session: StockConnectSession): Promise<RegisterCatalog> {
+  const existing = catalogs.get(session);
+  if (existing) {
+    return existing;
+  }
+
+  const response = await session.client.send(CommandType.RegistersAvailable, memspaceBody({ memspace: 0x00 }));
+  if (response.type !== "registers_available") {
+    throw new Error(`registerCatalogFor: expected a registers_available reply, got "${response.type}"`);
+  }
+  if (response.registers.length === 0) {
+    throw new Error(
+      "registerCatalogFor: the connected VICE build enumerated zero registers via REGISTERS_AVAILABLE -- " +
+        "it cannot support vice_registers_set, and this failure must be named rather than cached as an empty catalog",
+    );
+  }
+
+  const byName = new Map<string, { id: number; sizeBits: number; name: string }>();
+  const byId = new Map<number, { sizeBits: number; name: string }>();
+  for (const reg of response.registers) {
+    // reg.size is stock-protocol.ts's own field name for the wire's size
+    // byte (its parser is unchanged by this plan); this module renames it
+    // to sizeBits at the point it enters the catalog so every downstream
+    // reader sees the unit named in the type.
+    byName.set(reg.name.toUpperCase(), { id: reg.id, sizeBits: reg.size, name: reg.name });
+    byId.set(reg.id, { sizeBits: reg.size, name: reg.name });
+  }
+  const catalog: RegisterCatalog = { byName, byId };
+  catalogs.set(session, catalog);
+  return catalog;
+}
+
+// ---------------------------------------------------------------------------
+// vice_registers_available -- stock-only, no fork counterpart.
+// ---------------------------------------------------------------------------
+
+export const handleRegistersAvailable: StockSessionHandler = async (args, session) => {
+  const unexpectedKeys = Object.keys(args);
+  if (unexpectedKeys.length > 0) {
+    return isErrorText(`vice_registers_available: unexpected argument(s): ${unexpectedKeys.join(", ")} -- this tool takes no arguments`);
+  }
+
+  let catalog: RegisterCatalog;
+  try {
+    catalog = await registerCatalogFor(session);
+  } catch (err) {
+    return convertWireError("vice_registers_available", err);
+  }
+
+  // catalog.byId preserves insertion order, which is the order registers
+  // were pushed while walking REGISTERS_AVAILABLE's own reply -- i.e. the
+  // wire's own order, never re-sorted.
+  const registers = [...catalog.byId.entries()].map(([id, reg]) => ({ id, name: reg.name, sizeBits: reg.sizeBits }));
+
+  return stockAnswer(session.client, { registers, count: registers.length, memspace: "main" });
+};
+
+// ---------------------------------------------------------------------------
+// vice_registers_get -- fork-compatible, no required arguments.
+// ---------------------------------------------------------------------------
+
+export const handleRegistersGet: StockSessionHandler = async (args, session) => {
+  const unexpectedKeys = Object.keys(args);
+  if (unexpectedKeys.length > 0) {
+    return isErrorText(`vice_registers_get: unexpected argument(s): ${unexpectedKeys.join(", ")} -- this tool takes no arguments`);
+  }
+
+  let catalog: RegisterCatalog;
+  try {
+    catalog = await registerCatalogFor(session);
+  } catch (err) {
+    return convertWireError("vice_registers_get", err);
+  }
+
+  let response;
+  try {
+    response = await session.client.send(CommandType.RegistersGet, memspaceBody({ memspace: 0x00 }));
+  } catch (err) {
+    return convertWireError("vice_registers_get", err);
+  }
+  if (response.type !== "registers") {
+    return isErrorText(`vice_registers_get: expected a registers reply, got "${response.type}"`);
+  }
+
+  // D-01 (stock-native shape): `registers` is name -> value for every id the
+  // catalog resolves. The fork's `register` argument enumerates individual
+  // status-register flag bits (N|V|B|D|I|Z|C) -- those are NOT separate
+  // wire registers; the binary monitor exposes only the whole status
+  // register the catalog itself names (typically "FL" or similar). This
+  // handler reports that register's raw value as a number; it does not
+  // synthesise per-bit fields in Phase 3 (see handleRegistersSet's own
+  // flag-bit refusal for the write-side half of the same limitation).
+  const registers: Record<string, number> = {};
+  const unknownIds: Array<{ id: number; value: number }> = [];
+  for (const reg of response.registers) {
+    const known = catalog.byId.get(reg.id);
+    if (known) {
+      registers[known.name] = reg.value;
+    } else {
+      // Reported, never dropped -- a silently omitted register would be a
+      // wrong answer, not merely an incomplete one.
+      unknownIds.push({ id: reg.id, value: reg.value });
+    }
+  }
+
+  return stockAnswer(session.client, { registers, unknownIds, memspace: "main" });
+};
+
+// ---------------------------------------------------------------------------
+// vice_registers_set -- fork-compatible required arguments (register, value).
+// ---------------------------------------------------------------------------
+
+/** The 6502 status-register flag-bit names the fork's own `register`
+ * argument enumerates alongside the "real" wire registers. None of these
+ * are individually addressable on stock -- REGISTERS_SET can only write
+ * the whole status register the catalog itself names. Bit positions are
+ * the conventional 6502 layout (bit 7 down to bit 0), used only to make
+ * the explanatory refusal concrete, never to perform a read-modify-write. */
+const FLAG_BIT_POSITIONS: Record<string, number> = { N: 7, V: 6, B: 4, D: 3, I: 2, Z: 1, C: 0 };
+
+/** Candidate names a connected build might use for the whole processor
+ * status register -- checked in order against the resolved catalog so the
+ * flag-bit refusal can name the ACTUAL register this build reports,
+ * rather than guessing a name that might not exist on this build. */
+const STATUS_REGISTER_CANDIDATES = ["FL", "SR", "P", "STATUS", "FLAGS"];
+
+function findStatusRegisterName(catalog: RegisterCatalog): string | null {
+  for (const candidate of STATUS_REGISTER_CANDIDATES) {
+    const found = catalog.byName.get(candidate);
+    if (found) {
+      return found.name;
+    }
+  }
+  return null;
+}
+
+export const handleRegistersSet: StockSessionHandler = async (args, session) => {
+  const rawRegister = args.register;
+  const rawValue = args.value;
+
+  if (typeof rawRegister !== "string" || rawRegister.trim().length === 0) {
+    return isErrorText(`vice_registers_set: "register" is required and must be a non-empty string, got ${JSON.stringify(rawRegister)}`);
+  }
+  if (typeof rawValue !== "number" || !Number.isInteger(rawValue)) {
+    return isErrorText(`vice_registers_set: "value" is required and must be an integer, got ${JSON.stringify(rawValue)}`);
+  }
+
+  let catalog: RegisterCatalog;
+  try {
+    catalog = await registerCatalogFor(session);
+  } catch (err) {
+    return convertWireError("vice_registers_set", err);
+  }
+
+  const name = rawRegister.trim().toUpperCase();
+  const resolved = catalog.byName.get(name);
+  if (!resolved) {
+    if (name in FLAG_BIT_POSITIONS) {
+      const statusName = findStatusRegisterName(catalog);
+      const statusDescription = statusName
+        ? `reported by this catalog as "${statusName}"`
+        : "not identifiable by name in this catalog";
+      return isErrorText(
+        `vice_registers_set: "${rawRegister}" names an individual processor-status flag bit, not a wire register -- ` +
+          `the binary monitor exposes only the WHOLE status register (${statusDescription}), never per-bit access. ` +
+          `Read that register's value and test/set bit ${FLAG_BIT_POSITIONS[name]} yourself rather than writing "${rawRegister}" directly ` +
+          `(this is an explanatory refusal, not a silent read-modify-write).`,
+      );
+    }
+    const available = [...catalog.byName.keys()].sort().join(", ");
+    return isErrorText(`vice_registers_set: unknown register "${rawRegister}" -- available registers: ${available}`);
+  }
+
+  const { id, sizeBits } = resolved;
+  // sizeBits is REGISTERS_AVAILABLE's own wire size byte -- a BIT count,
+  // never a byte count (see this file's WHAT NOT TO DO list). The max is
+  // derived from the width itself rather than a two-branch byte-count
+  // ladder; the 16-bit ceiling is not arbitrary -- REGISTERS_SET's wire
+  // item carries the value as a u16 (registersSetBody(), stock-protocol.ts),
+  // so no width wider than 16 bits could ever be written regardless.
+  if (!Number.isInteger(sizeBits) || sizeBits < 1 || sizeBits > 16) {
+    return isErrorText(
+      `vice_registers_set: register "${resolved.name}" has an unexpected declared width (${sizeBits} bit(s)) -- ` +
+        `only registers of 1..16 bits are supported (REGISTERS_SET's wire item carries a u16 value, so 16 bits is the ceiling)`,
+    );
+  }
+  const max = 2 ** sizeBits - 1;
+  if (rawValue < 0 || rawValue > max) {
+    return isErrorText(
+      `vice_registers_set: value ${rawValue} is out of range for register "${resolved.name}" (width ${sizeBits} bit(s), valid range 0..0x${max.toString(16)})`,
+    );
+  }
+
+  const items: RegisterSetItem[] = [{ id, value: rawValue }];
+  let body: Buffer;
+  try {
+    body = registersSetBody({ memspace: 0x00, items });
+  } catch (err) {
+    return convertWireError("vice_registers_set", err);
+  }
+
+  let response;
+  try {
+    response = await session.client.send(CommandType.RegistersSet, body);
+  } catch (err) {
+    return convertWireError("vice_registers_set", err);
+  }
+  if (response.type !== "registers") {
+    return isErrorText(`vice_registers_set: expected a registers reply after REGISTERS_SET, got "${response.type}"`);
+  }
+
+  // VICE answers REGISTERS_SET with a full RegisterInfo dump -- read the
+  // just-written register's value back out of THAT reply, so a write the
+  // emulator silently clamped or otherwise altered is visible rather than
+  // assumed identical to what was requested.
+  const observed = response.registers.find((reg) => reg.id === id);
+  const observedValue = observed ? observed.value : null;
+
+  return stockAnswer(session.client, {
+    register: resolved.name,
+    id,
+    requestedValue: rawValue,
+    observedValue,
+    memspace: "main",
+  });
+};

package/stock-runstate.ts

@@ -0,0 +1,104 @@
+#!/usr/bin/env node
+// stock-runstate.ts
+//
+// THE ONE projection of the binary-monitor event stream into a derived run
+// state (D-06). Nothing else in this tree decides whether the emulator is
+// running or stopped -- every stock tool answer reports this exact value,
+// stamped by stock-handler.ts's stockAnswer().
+//
+// WHY THIS FILE EXISTS: D-05 means the client never issues an EXIT the
+// agent did not ask for, so an agent has no round trip that would otherwise
+// tell it what the machine is doing right now. The ONLY honest source for
+// that is the event stream itself -- STOPPED (0x62) / RESUMED (0x63) / JAM
+// (0x61), all arriving at request id 0xffffffff -- never the command the
+// client just sent, and never an assumption made at connect time (D-07).
+// stock-connect.ts's resolveCapabilities() is the closest structural
+// precedent (settle-once, cache-on-session), but that is a one-shot probe;
+// this is a continuously-updated event projection, and the two must not be
+// confused or share a mechanism.
+//
+// WHAT NOT TO DO:
+//   - Never infer run state from a command this client just sent. D-06
+//     requires the projection come ONLY from the wire's own
+//     stopped/resumed/jam events -- never "we just sent EXIT so it must be
+//     running now".
+//   - Never assert "stopped" at connect. stock-connect.ts's own handshake
+//     halts the machine with a bare PING and resumes it with its own EXIT
+//     (CR-02) -- projecting THAT internal pair as the user's own run state
+//     is exactly the dishonesty D-07 forbids. attachRunStateTracker() is
+//     called by a later plan's dispatch seam, never from inside
+//     stockConnect() itself.
+//   - Never attach a second 'event' listener to the same client
+//     (RESEARCH.md Pitfall 4). attachRunStateTracker() is idempotent via a
+//     module-level WeakMap, closing this structurally rather than by
+//     call-site discipline.
+//   - Never call client.send() from inside the listener -- the standing
+//     "never send from inside the event handler" rule. A read-only
+//     projection can never itself cause a state change.
+import type { ParsedResponse, StockFramingError, StockProtocolError, ViceMonitorClient } from "./stock-protocol.ts";
+
+export type RunState = "running" | "stopped" | "unknown";
+
+export interface RunStateTracker {
+  get(): RunState;
+}
+
+let trackers = new WeakMap<ViceMonitorClient, RunStateTracker>();
+
+/** True iff `item` is a parsed response/event shape carrying a `.type`
+ * discriminant -- narrows out the two wire-error classes ViceMonitorClient's
+ * 'event' channel can also carry (a wire error at a broadcast request id),
+ * which have no `.type` field at all. */
+function hasParsedType(item: ParsedResponse | StockProtocolError | StockFramingError): item is ParsedResponse {
+  return "type" in item;
+}
+
+/**
+ * Attaches a run-state tracker to `client`, or returns the existing one if
+ * one is already attached -- idempotent, registers no second listener. The
+ * returned tracker's `get()` starts at "unknown" (D-07) and moves only on
+ * the wire's own stopped/resumed/jam events; there is no setter and no
+ * exported mutator, so the listener is the sole writer (D-06's "projection,
+ * never derived from the commands sent").
+ */
+export function attachRunStateTracker(client: ViceMonitorClient): RunStateTracker {
+  const existing = trackers.get(client);
+  if (existing) {
+    return existing;
+  }
+
+  let state: RunState = "unknown";
+
+  client.on("event", (item: ParsedResponse | StockProtocolError | StockFramingError) => {
+    if (!hasParsedType(item)) {
+      return;
+    }
+    if (item.type === "stopped" || item.type === "jam") {
+      state = "stopped";
+    } else if (item.type === "resumed") {
+      state = "running";
+    }
+    // Every other event type (checkpoint_info, registers, unknown) leaves
+    // state untouched.
+  });
+
+  const tracker: RunStateTracker = { get: () => state };
+  trackers.set(client, tracker);
+  return tracker;
+}
+
+/** Reads the run state for `client` -- "unknown" when nothing is attached,
+ * never a throw: a handler must be able to answer even on a client nothing
+ * has attached a tracker to. Reading is free and side-effect-free (D-08),
+ * so pause/resume can short-circuit on it without sending anything. */
+export function runStateFor(client: ViceMonitorClient): RunState {
+  const tracker = trackers.get(client);
+  return tracker ? tracker.get() : "unknown";
+}
+
+/** Test-only: replaces the module-level WeakMap with a fresh one, matching
+ * clearHeldStockSession()'s role in stock-dispatch.test.ts's beforeEach()
+ * convention. */
+export function resetRunStateTrackersForTest(): void {
+  trackers = new WeakMap<ViceMonitorClient, RunStateTracker>();
+}

package/tools-manifest.json

@@ -997,7 +997,7 @@
         "properties": {
           "name": {
             "type": "string",
-            "description": "Name of the snapshot to load (as provided to snapshot.save). Use snapshot.list to see available snapshots."
+            "description": "Name of the snapshot to load. Must match the name previously given to snapshot.save."
           }
         },
         "required": [
@@ -1005,14 +1005,6 @@
         ]
       }
     },
-    {
-      "name": "vice_snapshot_list",
-      "description": "List all available snapshots with their metadata. Returns snapshot names, descriptions, creation times, and machine types. Use this to find the right snapshot to load for debugging.",
-      "inputSchema": {
-        "type": "object",
-        "additionalProperties": false
-      }
-    },
     {
       "name": "vice_cycles_stopwatch",
       "description": "Measure elapsed CPU cycles for timing-critical code analysis. Use 'reset' to start timing, 'read' to get elapsed cycles, or 'reset_and_read' for atomic read-and-reset. Ideal for measuring raster routine timing.",