@henols/vice-mcp 0.1.12 → 0.2.0

package/stock-connect.ts

@@ -30,7 +30,17 @@
 //     a connect() that silently sits unserviced in the backlog (PROTO-08,
 //     D-13, vice-broker-client.ts's own MonitorOwnershipError header
 //     comment).
-import { ViceMonitorClient, CommandType, ErrorCode, StockProtocolError } from "./stock-protocol.ts";
+import {
+  ViceMonitorClient,
+  CommandType,
+  ErrorCode,
+  StockProtocolError,
+  StockFramingError,
+  StockDesyncError,
+  StockResponseMismatchError,
+  StockConnectionClosedError,
+  StockRequestTimeoutError,
+} from "./stock-protocol.ts";
 import { readCapabilityRecord, writeCapabilityRecord, type CapabilityDeps } from "./backend-detect.mts";
 import { MachineRestartedError, ViceError, readEpoch, type EpochResult } from "./vice.ts";
 import {
@@ -74,9 +84,12 @@ export interface StockCapabilities {
  * request body but VICE stores it internally in a uint16_t
  * (monitor_binary.c:1492) -- any count >= 65536 wraps silently server-side.
  * Clamp client-side rather than ever sending an unclamped value. This
- * handshake only ever probes with count 0 (it wants the capability answer,
- * not any history), but the clamp is a general guard for any future caller
- * of this same request shape. */
+ * handshake now probes with count 1, never 0 -- real VICE
+ * (monitor_binary.c:1491-1497) rejects `requested_count < 1` with
+ * InvalidParameter (0x81), so 0 is a malformed request, not a valid "give me
+ * the newest entry" request (confirmed live, see 07-RESEARCH.md Pitfall 8).
+ * The clamp remains a general guard for any future caller of this same
+ * request shape. */
 const CPU_HISTORY_MAX_COUNT = 65535;
 
 /** WR-02/WR-12: bounded at BOTH ends, and against non-finite input. A bare
@@ -93,26 +106,87 @@ export function clampCpuHistoryCount(count: number): number {
   return Math.min(Math.max(Math.trunc(count), 0), CPU_HISTORY_MAX_COUNT);
 }
 
-/** Sends CPUHISTORY_GET (0x86) with memspace=main and a zero, clamped count,
- * and maps the wire outcome to CpuHistoryCapability's three-way answer --
- * 0x00 OK -> "available", 0x83 INVALID_TYPE -> "absent" (the pre-3.10 case),
- * 0x8f CMD_FAILURE -> "not_compiled_in" (the distinct compiled-without-
- * support case). Any other rejection (a timeout, a closed socket, an
- * unrecognized error code) is not this function's to interpret -- it
- * propagates unchanged. */
-async function probeCpuHistory(client: ViceMonitorClient): Promise<CpuHistoryCapability> {
-  const count = clampCpuHistoryCount(0);
+/** Sends CPUHISTORY_GET (0x86) with memspace=main and a clamped count of 1
+ * (the minimum real VICE accepts -- monitor_binary.c:1491-1497 rejects
+ * `requested_count < 1` with InvalidParameter, confirmed live in
+ * 07-RESEARCH.md Pitfall 8; count=1 is also probe-binmon.mjs's own
+ * already-verified value), and maps the wire outcome to
+ * CpuHistoryCapability's three-way answer -- 0x00 OK -> "available", 0x83
+ * INVALID_TYPE -> "absent" (the pre-3.10 case), 0x8f CMD_FAILURE ->
+ * "not_compiled_in" (the distinct compiled-without-support case), 0x81
+ * INVALID_PARAMETER -> "absent" (with a well-formed count=1 request, this
+ * code can no longer originate from this client's own malformed count -- it
+ * means the connected build's CPUHISTORY_GET rejected a minimal well-formed
+ * request, so the route is unusable on this build; collapsing to "absent"
+ * rather than a fourth capability value matches resolveCapabilities()'s own
+ * cache comment, which already documents "absent" and "not_compiled_in" as
+ * both meaning "never attempt CPUHISTORY_GET again", differing only in
+ * why).
+ *
+ * CR-01 (07-VERIFICATION.md gap 1, live-reproduced against a genuine VICE
+ * >= 3.10 build): a build that DOES support the opcode answers with a real,
+ * well-formed CPUHISTORY_GET frame -- `StockFramingError | response type
+ * 0x86 body is 52 byte(s), needs at least 65` -- that this client's parser
+ * cannot yet decode (the layout fix is a separate plan, 07-12). A decode
+ * failure is not a wire error code, so it is NOT a StockProtocolError, and
+ * before this fix it fell through to the final `throw err` below and killed
+ * the entire handshake. The rule this function now enforces: a *decode*
+ * failure (StockFramingError, StockDesyncError, StockResponseMismatchError
+ * -- the monitor answered with SOME frame, so the opcode demonstrably
+ * exists, but this client could not read the answer) resolves to "absent",
+ * exactly like the pre-3.10 case above, because "absent" already means
+ * "never attempt CPUHISTORY_GET again" to every consumer. A *transport*
+ * failure (StockConnectionClosedError, StockRequestTimeoutError, or any
+ * other unrecognized error) is a different thing entirely -- the connection
+ * itself is unusable, not just this one opcode -- and must still propagate
+ * unchanged so stockConnect()'s own retry/restart posture can see it. Do
+ * NOT widen this into a bare `catch { return "absent"; }`: that would also
+ * swallow a dead socket and hand back a capability answer for a session
+ * nobody could actually establish.
+ *
+ * CR-01 (07-REVIEW.md re-review): the three decode classes above answer a
+ * capability VALUE but they are NOT an observation of the build's
+ * capability -- the server answered, this client could not read the answer.
+ * So the probe now reports its PROVENANCE alongside the value, and
+ * resolveCapabilities() persists only `"wire"`-sourced answers. Persisting a
+ * decode failure wrote `cpuHistoryAvailable: false` to a record whose only
+ * invalidation key was the VICE version quad, so a single transient desync
+ * -- or any parser bug -- permanently disabled Route A for that binary and
+ * no shipped parser fix could ever invalidate it. Keep the two concepts
+ * separate: `capability` is what this process should do next, `source` is
+ * whether anyone actually established it. */
+interface CpuHistoryProbe {
+  /** What this process should do about Route A, right now. */
+  capability: CpuHistoryCapability;
+  /** `"wire"` -- the monitor's own answer, decoded: a fact about this build,
+   * safe to persist. `"decode_failure"` -- the monitor answered with a frame
+   * this client could not decode: usable in-process, NEVER persistable. */
+  source: "wire" | "decode_failure";
+}
+
+async function probeCpuHistory(client: ViceMonitorClient): Promise<CpuHistoryProbe> {
+  const count = clampCpuHistoryCount(1);
   const body = Buffer.alloc(5);
   body[0] = 0x00; // memspace: main
   body.writeUInt32LE(count, 1);
   try {
     await client.send(CommandType.CpuHistoryGet, body);
-    return "available";
+    return { capability: "available", source: "wire" };
   } catch (err) {
     if (err instanceof StockProtocolError) {
-      if (err.errorCode === ErrorCode.InvalidType) return "absent"; // 0x83 -- opcode absent, pre-3.10
-      if (err.errorCode === ErrorCode.CmdFailure) return "not_compiled_in"; // 0x8f -- compiled without support
+      if (err.errorCode === ErrorCode.InvalidType) return { capability: "absent", source: "wire" }; // 0x83 -- opcode absent, pre-3.10
+      if (err.errorCode === ErrorCode.CmdFailure) return { capability: "not_compiled_in", source: "wire" }; // 0x8f -- compiled without support
+      if (err.errorCode === ErrorCode.InvalidParameter) return { capability: "absent", source: "wire" }; // 0x81 -- minimal well-formed request rejected by this build
     }
+    // CR-01: the opcode answered with a real frame this client could not
+    // decode -- the opcode EXISTS, Route A is merely unusable by THIS
+    // client. An in-process "absent" is right; a persisted one is not.
+    if (err instanceof StockFramingError) return { capability: "absent", source: "decode_failure" };
+    if (err instanceof StockDesyncError) return { capability: "absent", source: "decode_failure" };
+    if (err instanceof StockResponseMismatchError) return { capability: "absent", source: "decode_failure" };
+    // Anything else -- notably StockConnectionClosedError and
+    // StockRequestTimeoutError -- is a transport failure, not a capability
+    // answer, and must still fail the handshake.
     throw err;
   }
 }
@@ -145,11 +219,54 @@ async function resolveCapabilities(client: ViceMonitorClient, versionQuad: strin
     }
   }
 
-  const cpuHistory = await probeCpuHistory(client);
-  if (deps.binPath) {
-    writeCap(deps.binPath, { versionQuad, cpuHistoryAvailable: cpuHistory === "available" }, { supervisorDir: deps.supervisorDir });
+  // CR-01: probeCpuHistory() is guarded against decode failures, but this
+  // call site guards against anything ELSE this function is not prepared to
+  // interpret -- so no uninterpreted error can reach stockConnect()'s fatal
+  // catch. Real transport/instance conditions (a closed socket, a timed-out
+  // request, or a proven machine restart) still rethrow, because those mean
+  // the handshake itself must fail, not just this one capability. Anything
+  // unclassifiable degrades to "absent" WITHOUT writing a capability cache
+  // record -- a capability answer nobody could actually establish must
+  // never be persisted for the next connect.
+  //
+  // CR-01 (07-REVIEW.md re-review) narrows this catch in one direction and
+  // fixes the write below. A StockProtocolError this module does not
+  // classify is rethrown rather than laundered into a capability answer:
+  // the set that reaches here includes InvalidApiVersion (0x82), and an
+  // api-version rejection is the one condition step 3 of the handshake
+  // exists to make FATAL -- reporting it as "Route A is absent" hides a
+  // connection that is not actually usable. The residual catch-all below
+  // therefore covers only genuinely untyped failures (a bug in this client,
+  // not a wire answer), which still degrade without persisting.
+  let probe: CpuHistoryProbe;
+  try {
+    probe = await probeCpuHistory(client);
+  } catch (err) {
+    if (err instanceof StockConnectionClosedError || err instanceof StockRequestTimeoutError || err instanceof MachineRestartedError) {
+      throw err;
+    }
+    if (err instanceof StockProtocolError) {
+      // An unclassified WIRE error code. probeCpuHistory() already maps
+      // every code that means "Route A is unusable"; anything else is a
+      // condition this client does not understand, and a handshake that
+      // cannot understand the server's refusal must fail, not guess.
+      throw err;
+    }
+    console.error(`resolveCapabilities: unclassified error resolving CPUHISTORY_GET capability, falling back to "absent": ${String(err)}`);
+    return { cpuHistory: "absent" };
+  }
+  // CR-01: persist ONLY a wire-sourced answer. A decode failure means the
+  // opcode exists and this client could not read the reply -- writing
+  // `cpuHistoryAvailable: false` for it would pin Route A off for this
+  // binary until VICE itself is upgraded, because the record's only other
+  // invalidation key is the version quad. writeCapabilityRecord() stamps
+  // CAPABILITY_SCHEMA_VERSION so a shipped parser change invalidates
+  // records written by the older parser; that is the second half of the
+  // same fix and cannot substitute for this one.
+  if (deps.binPath && probe.source === "wire") {
+    writeCap(deps.binPath, { versionQuad, cpuHistoryAvailable: probe.capability === "available" }, { supervisorDir: deps.supervisorDir });
   }
-  return { cpuHistory };
+  return { cpuHistory: probe.capability };
 }
 
 // ---------------------------------------------------------------------------

package/stock-derived.ts

@@ -18,21 +18,42 @@
 // hazard. There, NOT translating an emulator-side path is the bug -- four
 // tools carry a filename stock VICE opens on the HOST, and stock-paths.ts's
 // whole job is making sure that translation happens. HERE, translating a
-// CLIENT-SIDE-DERIVED path is the bug: rewriteArguments() runs INSIDE the
-// fork-forwarding function at vice-proxy.ts:2773, before call() -- a derived
-// tool sitting behind call() would receive HOST-translated paths and act on
-// them INSIDE THE CONTAINER (ROADMAP Phase 4 Notes, CLAUDE.md). The
-// derived-tool seam this file anchors exists so a derived tool's handler is
-// reached BEFORE that fork-forwarding function ever runs
-// rewriteArguments() at all.
+// CLIENT-SIDE-DERIVED path is the bug: `forwardToVice()` calls
+// `rewriteArguments(args, name)` itself, before it ever delegates to
+// `call()` -- so a derived tool sitting behind `call()` would receive
+// HOST-translated paths and act on them INSIDE THE CONTAINER (ROADMAP Phase 4
+// Notes, CLAUDE.md). The derived-tool seam this file anchors exists so a
+// derived tool's handler is reached BEFORE `forwardToVice()` runs
+// `rewriteArguments()` at all.
 //
-// SECOND CONSUMER, named now so Phase 5's edit is a one-liner:
-// gatherWedgeEvidence() (vice-proxy.ts:1343) calls rewriteArguments() itself
-// at line 1367. On the stock backend, PERFORMING that translation becomes
-// the bug -- its own comment inverts. Phase 5 criterion 5 owns that fix; it
-// is deliberately NOT repointed here (it is currently unreachable on stock
-// anyway: handleRecycle() is backend-aware and refused by name after CR-07,
-// and vice_display_screenshot does not exist on stock until Phase 5).
+// SECOND CONSUMER: `gatherWedgeEvidence()` in vice-proxy.ts calls
+// `rewriteArguments()` itself, for `vice_display_screenshot`. On the stock
+// backend, PERFORMING that translation becomes the bug -- its own comment
+// inverts. Phase 5 criterion 5 owns that fix; it is deliberately NOT
+// repointed here.
+//
+// CITATION STYLE, deliberate (07-REVIEW.md WR-12): the two call sites above
+// are named by SYMBOL (`forwardToVice()`'s own `rewriteArguments(args, name)`
+// call; `gatherWedgeEvidence()`'s own call), never by line number. This header
+// used to cite `vice-proxy.ts:2773`, `:1343` and `:1367`; by the time WR-12 was
+// filed the real lines were 2889, 1344 and 1368 -- 07-16 edited vice-proxy.ts
+// without re-verifying them, and this header is the in-tree statement of
+// CLAUDE.md's derived-tool constraint, so its citations are load-bearing. Line
+// numbers in this file drift every phase; grep for the symbol instead.
+//
+// WHY THE HAZARD IS UNREACHABLE ON STOCK TODAY -- restated in terms of what
+// actually enforces it (WR-12 again; the previous reason had gone stale):
+// `buildBackendAwareTool()` routes EVERY stock tool call to
+// `dispatchStock()`, so `forwardToVice()`, `handleRecycle()` and
+// `gatherWedgeEvidence()` are reachable only on the fork arm. That is a
+// structural property of the registration, not of any tool's name. The reason
+// this header used to give -- "handleRecycle() is backend-aware and refused by
+// name after CR-07, and vice_display_screenshot does not exist on stock until
+// Phase 5" -- is now WRONG on its first clause: Phase 7 implemented
+// `vice_recycle` on stock (`handleRecycleStock`) and registered it in
+// STOCK_DERIVED_TOOLS below. The conclusion held; the stated reason did not,
+// which is worse than no reason for a constraint a future reader will
+// re-derive.
 //
 // WHAT NOT TO DO:
 //   - Never `import` hostpath.ts from this file, or from any module listed
@@ -50,6 +71,11 @@
 //   - Never re-implement session acquisition here -- withDerivedTool() in
 //     stock-dispatch.ts delegates to the one ensureStockSession() the 25
 //     direct tools use.
+//   - Never add a name to STOCK_DERIVED_TOOLS without adding its module to
+//     package.json's files[] in the SAME commit (Phase 3 Rule 2) --
+//     withDerivedTool() refuses on this set, and a declared-but-unshipped
+//     module fails at module load in the published tarball rather than at
+//     dispatch.
 import { ViceError, type ViceErrorOptions } from "./vice.ts";
 import type { StockToolResult } from "./stock-handler.ts";
 import type { StockDispatchDeps } from "./stock-dispatch.ts";
@@ -76,6 +102,18 @@ export class DerivedToolError extends ViceError {
 
 export const STOCK_DERIVED_TOOLS: ReadonlySet<string> = new Set([
   "vice_disassemble", // Phase 4, DERIV-07's first consumer (04-05) -- client-side 6510 disassembler
+  "vice_memory_search", // Phase 5, DERIV-01
+  "vice_memory_compare", // Phase 5, DERIV-01
+  "vice_symbols_load", // Phase 5, DERIV-04
+  "vice_symbols_lookup", // Phase 5, DERIV-04
+  "vice_vicii_get_state", // Phase 5, DERIV-05
+  "vice_cia_get_state", // Phase 5, DERIV-05
+  "vice_sprite_get", // Phase 5, DERIV-06
+  "vice_sprite_inspect", // Phase 5, DERIV-06
+  "vice_cycles_stopwatch", // Phase 7, TIME-01
+  "vice_run_until", // Phase 7, TIME-02
+  "vice_diagnose", // Phase 7, TIME-04
+  "vice_recycle", // Phase 7, TIME-04
 ]);
 
 /**
@@ -85,6 +123,21 @@ export const STOCK_DERIVED_TOOLS: ReadonlySet<string> = new Set([
  * threaded down for anything the handler needs beyond the session (matching
  * StockSessionHandler's own `deps` parameter).
  *
+ * THE ONE DECLARED EXCEPTION (Phase 7, plan 07-09): `vice_diagnose`
+ * (`handleDiagnoseStock`, stock-diagnose.ts) is registered with
+ * `needsSession: false` yet DOES reach the wire -- it calls
+ * `ensureStockSession(deps)` itself, inside its own try/catch, rather than
+ * through withDerivedTool()'s session preamble. This is deliberate, not a
+ * contradiction of the rule above: a thrown MonitorOwnershipError or
+ * MachineRestartedError during acquisition must become one of
+ * vice_diagnose's own five VERDICTS (`monitor_held_elsewhere`, `restarted`)
+ * rather than withDerivedTool()'s generic refusal text -- the exact string
+ * those verdicts exist to replace. Every other `needsSession: false` handler
+ * in STOCK_DERIVED_TOOLS still structurally cannot reach the wire; this is
+ * the one named handler that opts out of that guarantee, and it does so by
+ * calling the SAME ensureStockSession() every session-needing handler
+ * calls, never a lighter-weight variant of it.
+ *
  * `StockDispatchDeps` is imported `type`-only from stock-dispatch.ts -- under
  * verbatimModuleSyntax an `import type` erases completely at compile time,
  * so it creates no runtime cycle even though stock-dispatch.ts imports THIS