llm-chess-mcp 0.5.0 → 0.6.0

package/README.md

@@ -207,9 +207,10 @@ human-readable summary and must not be parsed as data.
   `best / excellent / good / inaccuracy / mistake / blunder`.
 - `maia3Prob` is a **human-likelihood**, not move quality. A high-probability move
   can still be objectively bad.
-- Analysis continuations return `pv` in UCI and the same legal prefix in
-  `pvSan` as SAN. If an engine line contains an invalid move, `pvSan` stops
-  before it while the original `pv` remains unchanged.
+- Successful analysis continuations return corresponding `pv` and `pvSan`
+  arrays of equal length in UCI and SAN. An invalid engine continuation is
+  rejected at the internal tool boundary instead of returning a truncated
+  `pvSan`.
 
 ## Candidate structure
 

package/dist/chess-copy.js

@@ -10,25 +10,41 @@ const CHESS_STATE_KEYS = Reflect.ownKeys(new Chess());
 function squareColor(square) {
     return ((square.charCodeAt(0) - 97 + Number(square[1])) % 2);
 }
-function minimumPawnCaptures(chess, color) {
-    const pawns = chess
+function minimumPawnCaptures(chess, color, promotedPieces, promotedBishops) {
+    const requirements = chess
         .findPiece({ type: "p", color })
         .map((square) => ({
+        kind: "pawn",
         advances: color === "w" ? Number(square[1]) - 2 : 7 - Number(square[1]),
         file: square.charCodeAt(0) - 97,
-    }))
-        .sort((left, right) => left.file - right.file);
+    }));
+    for (const bishopColor of [0, 1]) {
+        for (let count = 0; count < promotedBishops[bishopColor]; count += 1) {
+            requirements.push({ kind: "bishop", color: bishopColor });
+        }
+    }
+    for (let count = 0; count < promotedPieces; count += 1) {
+        requirements.push({ kind: "promotion" });
+    }
     let costs = new Map([[0, 0]]);
-    for (const pawn of pawns) {
+    for (const requirement of requirements) {
         const next = new Map();
         for (const [mask, cost] of costs) {
             for (let original = 0; original < 8; original += 1) {
                 const bit = 1 << original;
                 if (mask & bit)
                     continue;
-                const captures = Math.abs(original - pawn.file);
-                if (captures > pawn.advances)
-                    continue;
+                let captures = 0;
+                if (requirement.kind === "pawn") {
+                    captures = Math.abs(original - requirement.file);
+                    if (captures > requirement.advances)
+                        continue;
+                }
+                else if (requirement.kind === "bishop") {
+                    const promotionRank = color === "w" ? 8 : 1;
+                    const promotionColor = ((original + promotionRank) % 2);
+                    captures = promotionColor === requirement.color ? 0 : 1;
+                }
                 const nextMask = mask | bit;
                 next.set(nextMask, Math.min(next.get(nextMask) ?? Infinity, cost + captures));
             }
@@ -66,6 +82,69 @@ function clonedChess(chess) {
 function exactFen(chess) {
     return chess.fen({ forceEnpassantSquare: true });
 }
+const FILES = "abcdefgh";
+function squareAt(file, rank) {
+    return `${FILES[file]}${rank}`;
+}
+function squareCoordinates(square) {
+    return [square.charCodeAt(0) - 97, Number(square[1])];
+}
+function squaresBetween(from, to) {
+    const [fromFile, fromRank] = squareCoordinates(from);
+    const [toFile, toRank] = squareCoordinates(to);
+    const fileDistance = toFile - fromFile;
+    const rankDistance = toRank - fromRank;
+    if (fileDistance !== 0 &&
+        rankDistance !== 0 &&
+        Math.abs(fileDistance) !== Math.abs(rankDistance)) {
+        return [];
+    }
+    const fileStep = Math.sign(fileDistance);
+    const rankStep = Math.sign(rankDistance);
+    const squares = [];
+    let file = fromFile + fileStep;
+    let rank = fromRank + rankStep;
+    while (file !== toFile || rank !== toRank) {
+        squares.push(squareAt(file, rank));
+        file += fileStep;
+        rank += rankStep;
+    }
+    return squares;
+}
+function priorFullmove(fields, previous) {
+    const fullmove = fields[5] ?? "";
+    if (!isSafeDecimal(fullmove, 1))
+        return null;
+    const value = Number(fullmove) - (previous === "b" ? 1 : 0);
+    return value >= 1 ? value : null;
+}
+function priorChess(setup, previous, castling, enPassant, halfmove, fullmove) {
+    try {
+        return new Chess([
+            setup.fen().split(" ")[0],
+            previous,
+            castling,
+            enPassant,
+            String(halfmove),
+            String(fullmove),
+        ].join(" "));
+    }
+    catch {
+        return null;
+    }
+}
+function reachesPosition(prior, move, currentFen) {
+    if (!prior)
+        return false;
+    try {
+        assertLegalPositionInternal(prior, false);
+        prior.move(move);
+        return exactFen(prior) === currentFen;
+    }
+    catch {
+        return false;
+    }
+}
 function hasPiece(chess, square, type, color) {
     const piece = chess.get(square);
     return piece?.type === type && piece.color === color;
@@ -106,6 +185,35 @@ function assertEnPassantPosition(chess) {
         (turn === "w" && fields[5] === "1")) {
         throw new ChessError("INVALID_FEN", "FEN en passant target does not match a double pawn move");
     }
+    const fullmove = fields[5] ?? "";
+    if (!isSafeDecimal(fullmove, 1)) {
+        throw new ChessError("INVALID_FEN", "FEN fullmove number must be a positive safe decimal integer");
+    }
+    const setup = new Chess(fields.join(" "));
+    setup.remove(pawnSquare);
+    setup.put({ type: "p", color: pawnColor }, originSquare);
+    const priorFullmove = turn === "w" ? Number(fullmove) - 1 : Number(fullmove);
+    const priorFen = [
+        setup.fen().split(" ")[0],
+        pawnColor,
+        fields[2],
+        "-",
+        "0",
+        String(priorFullmove),
+    ].join(" ");
+    const prior = new Chess(priorFen);
+    assertLegalPosition(prior);
+    try {
+        prior.move({ from: originSquare, to: pawnSquare });
+    }
+    catch {
+        throw new ChessError("INVALID_FEN", "FEN en passant target does not follow a legal double pawn move");
+    }
+    const transitioned = exactFen(prior).split(" ");
+    transitioned[3] = target;
+    if (transitioned.join(" ") !== fields.join(" ")) {
+        throw new ChessError("INVALID_FEN", "FEN en passant target does not match the previous position");
+    }
 }
 function moveDescriptor(move) {
     const base = { from: move.from, to: move.to };
@@ -116,6 +224,111 @@ function isSafeDecimal(value, minimum) {
         Number.isSafeInteger(Number(value)) &&
         Number(value) >= minimum);
 }
+const CAPTURED_PIECES = ["p", "n", "b", "r", "q"];
+function ordinaryDoubleCheckPredecessor(chess, king, checkers) {
+    const currentFen = exactFen(chess);
+    const fields = currentFen.split(" ");
+    const previous = chess.turn() === "w" ? "b" : "w";
+    const active = chess.turn();
+    const fullmove = priorFullmove(fields, previous);
+    const currentHalfmove = Number(fields[4]);
+    if (fullmove === null || !Number.isSafeInteger(currentHalfmove))
+        return false;
+    for (let movedIndex = 0; movedIndex < 2; movedIndex += 1) {
+        const to = checkers[movedIndex];
+        const other = checkers[1 - movedIndex];
+        const moved = chess.get(to);
+        const otherType = chess.get(other)?.type;
+        if (!moved ||
+            moved.color !== previous ||
+            (otherType !== "b" && otherType !== "r" && otherType !== "q")) {
+            continue;
+        }
+        for (const from of squaresBetween(other, king)) {
+            if (chess.get(from) !== undefined)
+                continue;
+            for (const captured of [undefined, ...CAPTURED_PIECES]) {
+                if (captured === "p" &&
+                    (to[1] === "1" || to[1] === "8")) {
+                    continue;
+                }
+                const halfmove = moved.type === "p" || captured ? 0 : currentHalfmove - 1;
+                if (halfmove < 0 || (moved.type === "p" || captured) && currentHalfmove !== 0) {
+                    continue;
+                }
+                const setup = new Chess(currentFen);
+                setup.remove(to);
+                setup.put(moved, from);
+                if (captured)
+                    setup.put({ type: captured, color: active }, to);
+                const prior = priorChess(setup, previous, fields[2], "-", halfmove, fullmove);
+                if (reachesPosition(prior, { from, to }, currentFen))
+                    return true;
+                const promotionRank = previous === "w" ? "8" : "1";
+                const pawnRank = previous === "w" ? "7" : "2";
+                if (moved.type !== "p" &&
+                    moved.type !== "k" &&
+                    to[1] === promotionRank &&
+                    from[1] === pawnRank) {
+                    const promotedSetup = new Chess(currentFen);
+                    promotedSetup.remove(to);
+                    promotedSetup.put({ type: "p", color: previous }, from);
+                    if (captured) {
+                        promotedSetup.put({ type: captured, color: active }, to);
+                    }
+                    const promotionPrior = priorChess(promotedSetup, previous, fields[2], "-", 0, fullmove);
+                    if (currentHalfmove === 0 &&
+                        reachesPosition(promotionPrior, { from, to, promotion: moved.type }, currentFen)) {
+                        return true;
+                    }
+                }
+            }
+        }
+    }
+    return false;
+}
+function enPassantDoubleCheckPredecessor(chess) {
+    const currentFen = exactFen(chess);
+    const fields = currentFen.split(" ");
+    if (fields[3] !== "-" || fields[4] !== "0")
+        return false;
+    const previous = chess.turn() === "w" ? "b" : "w";
+    const active = chess.turn();
+    const fullmove = priorFullmove(fields, previous);
+    if (fullmove === null)
+        return false;
+    const destinationRank = previous === "w" ? 6 : 3;
+    const originRank = previous === "w" ? 5 : 4;
+    for (const to of chess.findPiece({ type: "p", color: previous })) {
+        if (Number(to[1]) !== destinationRank)
+            continue;
+        const [toFile] = squareCoordinates(to);
+        const capturedSquare = squareAt(toFile, originRank);
+        if (chess.get(capturedSquare) !== undefined)
+            continue;
+        for (const originFile of [toFile - 1, toFile + 1]) {
+            if (originFile < 0 || originFile > 7)
+                continue;
+            const from = squareAt(originFile, originRank);
+            if (chess.get(from) !== undefined)
+                continue;
+            const setup = new Chess(currentFen);
+            setup.remove(to);
+            setup.put({ type: "p", color: previous }, from);
+            setup.put({ type: "p", color: active }, capturedSquare);
+            const prior = priorChess(setup, previous, fields[2], to, 0, fullmove);
+            if (reachesPosition(prior, { from, to }, currentFen))
+                return true;
+        }
+    }
+    return false;
+}
+function hasDoubleCheckPredecessor(chess, king, checkers) {
+    if (exactFen(chess).split(" ")[3] !== "-")
+        return true;
+    return (ordinaryDoubleCheckPredecessor(chess, king, checkers) ||
+        enPassantDoubleCheckPredecessor(chess));
+}
 export function assertSafeFenCounters(fen) {
     const fields = fen.split(/\s+/);
     if (fields.length >= 5 && !isSafeDecimal(fields[4] ?? "", 0)) {
@@ -126,6 +339,9 @@ export function assertSafeFenCounters(fen) {
     }
 }
 export function assertLegalPosition(chess) {
+    assertLegalPositionInternal(chess, true);
+}
+function assertLegalPositionInternal(chess, validateDoubleCheck) {
     for (const color of ["w", "b"]) {
         if (chess.findPiece({ type: "k", color }).length !== 1) {
             throw new ChessError("INVALID_FEN", "FEN must contain exactly one king per side");
@@ -140,19 +356,18 @@ export function assertLegalPosition(chess) {
         const promotedPieces = Object.entries(ORIGINAL_PIECES).reduce((total, [type, original]) => total +
             Math.max(0, chess.findPiece({ type: type, color }).length -
                 original), 0);
-        const promotedBishops = [0, 1].reduce((total, squareColorValue) => total +
-            Math.max(0, chess
-                .findPiece({ type: "b", color })
-                .filter((square) => squareColor(square) === squareColorValue)
-                .length - 1), 0);
-        const promoted = promotedPieces + promotedBishops;
+        const promotedBishops = [0, 1].map((squareColorValue) => Math.max(0, chess
+            .findPiece({ type: "b", color })
+            .filter((square) => squareColor(square) === squareColorValue)
+            .length - 1));
+        const promoted = promotedPieces + promotedBishops[0] + promotedBishops[1];
         if (promoted > 8 - pawns.length) {
             throw new ChessError("INVALID_FEN", "FEN contains more promoted material than missing pawns allow");
         }
         assertCastlingPosition(chess, color);
         const opponent = color === "w" ? "b" : "w";
         const missingOpponentMaterial = 15 - nonKingMaterial(chess, opponent);
-        if (minimumPawnCaptures(chess, color) > missingOpponentMaterial) {
+        if (minimumPawnCaptures(chess, color, promotedPieces, promotedBishops) > missingOpponentMaterial) {
             throw new ChessError("INVALID_FEN", "FEN pawn files require more captures than opposing material allows");
         }
     }
@@ -173,6 +388,11 @@ export function assertLegalPosition(chess) {
         if (checkers.length > 2 || leapers.length > 1) {
             throw new ChessError("INVALID_FEN", "FEN contains an impossible check topology");
         }
+        if (validateDoubleCheck &&
+            checkers.length === 2 &&
+            !hasDoubleCheckPredecessor(chess, king, checkers)) {
+            throw new ChessError("INVALID_FEN", "FEN double check has no legal previous move");
+        }
     }
 }
 function expectedInitialFen(headers) {

package/dist/domain.d.ts

@@ -13,6 +13,8 @@ export declare const MOVE_EVALUATION_RESULTS: readonly ["ongoing", "checkmate",
 export type MoveEvaluationResult = (typeof MOVE_EVALUATION_RESULTS)[number];
 export declare const ANALYSIS_LEVELS: readonly ["fast", "normal", "deep"];
 export type AnalysisLevel = (typeof ANALYSIS_LEVELS)[number];
+export declare const MAX_HUMAN_MOVES = 20;
+export declare const HUMAN_PROBABILITY_TOLERANCE = 0.00001;
 export declare const MOVE_CLASSIFICATIONS: readonly ["best", "excellent", "good", "inaccuracy", "mistake", "blunder"];
 export type MoveClassification = (typeof MOVE_CLASSIFICATIONS)[number];
 export declare const INTENTS: readonly ["best", "strong", "natural", "balanced", "ease_off", "give_chance"];
@@ -49,13 +51,21 @@ export interface ChessState {
     };
 }
 export type Wdl = [number, number, number];
-export interface SfLine {
+type SfScore = {
+    scoreCp: number;
+    scoreMate: null;
+} | {
+    scoreCp: null;
+    scoreMate: number;
+} | {
+    scoreCp: null;
+    scoreMate: null;
+};
+export type SfLine = {
     multipv: number;
-    scoreCp: number | null;
-    scoreMate: number | null;
     wdl: Wdl | null;
     pv: string[];
-}
+} & SfScore;
 export interface Maia3Move {
     uci: string;
     san: string;

package/dist/domain.js

@@ -25,6 +25,8 @@ export const MOVE_EVALUATION_RESULTS = [
     ...DRAW_RESULTS,
 ];
 export const ANALYSIS_LEVELS = ["fast", "normal", "deep"];
+export const MAX_HUMAN_MOVES = 20;
+export const HUMAN_PROBABILITY_TOLERANCE = 1e-5;
 export const MOVE_CLASSIFICATIONS = [
     "best",
     "excellent",

package/dist/engines/stockfish-info.js

@@ -58,10 +58,16 @@ export function parseAnalysisInfo(line) {
     };
 }
 export function mergeAnalysisInfo(previous, info) {
+    const scoreCp = info.score ? info.score.cp : (previous?.scoreCp ?? null);
+    const scoreMate = info.score ? info.score.mate : (previous?.scoreMate ?? null);
+    const scoreFields = scoreCp !== null
+        ? { scoreCp, scoreMate: null }
+        : scoreMate !== null
+            ? { scoreCp: null, scoreMate }
+            : { scoreCp: null, scoreMate: null };
     return {
         multipv: info.multipv,
-        scoreCp: info.score ? info.score.cp : (previous?.scoreCp ?? null),
-        scoreMate: info.score ? info.score.mate : (previous?.scoreMate ?? null),
+        ...scoreFields,
         wdl: info.wdl ?? previous?.wdl ?? null,
         pv: info.pv ?? previous?.pv ?? [],
     };

package/dist/engines/stockfish.d.ts

@@ -33,12 +33,15 @@ export declare class Stockfish {
     private teardownPending;
     private readonly drainWaiters;
     private readonly terminations;
+    private readonly processListenerCleanups;
     private readonly initEngine;
     private readonly configuredFlavor;
     private readonly maxQueue;
     private readonly timeouts;
     constructor(options?: StockfishOptions);
     private disposeInitEngine;
+    private claimProcessListenerCleanups;
+    private moveProcessListenerCleanups;
     private adoptInitEngine;
     private completeInit;
     private init;