@chessceo/mcp 0.49.11 → 0.50.1

package/dist/analysis/deep.js

@@ -1,22 +1,11 @@
-// deep_analyse: async background job for a SINGLE long Stockfish think
-// on ONE position (up to 5 min movetime). Same start / status / cancel
-// shape as auto_evaluate, but different intent — the point is to free
-// the tool response path from a 5-minute wait AND to keep the Lc0 slot
-// free on the combo so the LLM can keep calling
-// `cloud_analyse({engines: ["lc0"]})` for other positions while the
-// deep SF think runs.
-//
-// Concretely: the job fires an unawaited authedRequest to the backend
-// with engines=["stockfish"] + long movetime; the backend's per-engine
-// semaphore lets that hold only the SF slot for the duration. The
-// MCP-side promise resolves when the long HTTP call returns (nginx
-// proxy_read_timeout is bumped to 420s on /api/agent/ to cover 5-min
-// movetime + engine bestmove grace).
-//
-// Extracted from index.ts in v0.44 as part of the file split.
-import { authedRequest } from "../http.js";
-import { analysisToStoredEval, convertCloudSnapshotResponse } from "./response.js";
-import { analyseRouting, resolveFromNodeOrFen, storeEvalOnNode, } from "./file_handle.js";
+// deep_analyse: async background job for ONE long think on ONE position
+// (up to 5 min movetime), on any engine (default Stockfish). Same
+// start / status / cancel shape as auto_evaluate. The long call holds only
+// that engine's slot, so the other engines stay usable through
+// cloud_analyse while it runs. nginx proxy_read_timeout on /api/agent/ is
+// 420s to cover a 5-min think plus the bestmove grace.
+import { analysePositions, convertPositionResult, parseEngines, resultToStoredEval } from "./response.js";
+import { resolveFromNodeOrFen, storeEvals } from "./file_handle.js";
 const deepJobs = new Map();
 const DEEP_JOB_TTL_MS = 15 * 60 * 1000;
 function newDeepJobId() {
@@ -33,57 +22,43 @@ function reapExpiredDeepJobs() {
 }
 export async function deepAnalyseStart(args) {
     reapExpiredDeepJobs();
+    const [engine] = parseEngines(args.engine, ["stockfish"]);
     const resolved = await resolveFromNodeOrFen(args);
     const fen = resolved.fen;
     const movetimeMs = typeof args.movetime_ms === "number" ? args.movetime_ms : 60_000;
-    // Default 2 — SF loses meaningful strength at higher multipv, so a
-    // deep think is best spent on a tight candidate list. Matches the
-    // cloud_analyse stockfish_multipv default.
-    const multipv = typeof args.multipv === "number" ? args.multipv : 2;
+    // Default 2 for Stockfish (it loses strength at higher multipv), 8 for
+    // the NN engines (it costs them nothing).
+    const multipv = typeof args.multipv === "number" ? args.multipv : engine === "stockfish" ? 2 : 8;
+    const opts = { engines: [engine], movetime_ms: movetimeMs, multipv: { [engine]: multipv } };
+    if (typeof args.contempt === "number")
+        opts.contempt = args.contempt;
+    if (typeof args.rental === "string" && args.rental.trim())
+        opts.rentals = { [engine]: args.rental.trim() };
     const jobId = newDeepJobId();
     const job = {
         id: jobId,
-        routing: analyseRouting(args),
+        engine,
+        opts,
         status: "running",
         fileHandle: resolved.file,
         fen,
         movetimeMs,
-        multipv,
         startedAt: Date.now(),
         cancelController: new AbortController(),
     };
     deepJobs.set(jobId, job);
-    // Kick off the long HTTP call unawaited — resolves when the backend
-    // returns the SF snapshot. authedRequest is a plain fetch under the
-    // hood; abort signal flows via cancelController.
     void runDeepJob(job).catch(err => {
         job.status = "error";
         job.error = err instanceof Error ? err.message : String(err);
         job.finishedAt = Date.now();
     });
-    return {
-        job_id: jobId,
-        status: "running",
-        movetime_ms: movetimeMs,
-        fen,
-    };
+    return { job_id: jobId, status: "running", engine, movetime_ms: movetimeMs, fen };
 }
 async function runDeepJob(job) {
-    const body = {
-        fen: job.fen,
-        movetime_ms: job.movetimeMs,
-        stockfish_multipv: job.multipv,
-        engines: ["stockfish"],
-        ...job.routing,
-    };
     let raw;
     try {
-        // TODO(future): plumb an AbortSignal through authedRequest for
-        // real mid-flight cancellation. For now, cancel just marks the
-        // job so the caller stops polling; the backend still runs the
-        // engine to completion and the result is stored on the job
-        // record but flagged cancelled.
-        raw = await authedRequest("POST", "/api/agent/cloud-engines/analyse", body);
+        // Cancel only marks the job; the backend runs the think to completion.
+        [raw] = await analysePositions([{ fen: job.fen }], job.opts);
     }
     catch (err) {
         job.status = "error";
@@ -91,31 +66,26 @@ async function runDeepJob(job) {
         job.finishedAt = Date.now();
         return;
     }
-    const converted = convertCloudSnapshotResponse(raw, job.fen);
-    const sf = converted.stockfish;
-    if (job.cancelController.signal.aborted) {
-        job.status = "cancelled";
-    }
-    else {
-        job.status = "done";
-    }
-    job.result = sf ?? null;
-    job.finishedAt = Date.now();
-    // Same node-persistence as cloud_analyse: if the caller anchored on
-    // file_id+node_id, store the SF-only eval as the node's ceoEval so
-    // quote_engine_eval can cite it later. We build a StoredEval that has
-    // only the sf leg — no Lc0 was run.
-    if (job.fileHandle && sf) {
-        const ev = analysisToStoredEval({ stockfish: sf });
+    const converted = raw ? convertPositionResult(raw) : undefined;
+    const block = converted?.engines[job.engine];
+    job.result = block ?? null;
+    if (block?.error)
+        job.error = block.error;
+    // Merge into the node's ceoEval (other engines' stored reads are kept)
+    // and stamp transpositions, same as cloud_analyse.
+    if (job.fileHandle && converted && !job.cancelController.signal.aborted) {
+        const ev = resultToStoredEval(converted);
         if (ev) {
             try {
-                await storeEvalOnNode(job.fileHandle, ev);
+                [job.storedOn] = await storeEvals(job.fileHandle.id, [{ fen: job.fen, ev }]);
             }
-            catch {
-                // best-effort — the analysis result is what the LLM asked for
+            catch (err) {
+                job.storeError = `analysis done but saving to the file failed: ${err instanceof Error ? err.message : String(err)}`;
             }
         }
     }
+    job.status = job.cancelController.signal.aborted ? "cancelled" : block && !block.error ? "done" : "error";
+    job.finishedAt = Date.now();
 }
 export function deepAnalyseStatus(args) {
     reapExpiredDeepJobs();
@@ -134,8 +104,11 @@ export function deepAnalyseStatus(args) {
         status: job.status,
         movetime_ms: job.movetimeMs,
         elapsed_ms: (job.finishedAt ?? Date.now()) - job.startedAt,
+        engine: job.engine,
         fen: job.fen,
         result: job.result,
+        stored_on: job.storedOn,
+        store_error: job.storeError,
         error: job.error,
         started_at_ms: job.startedAt,
         finished_at_ms: job.finishedAt,

package/dist/analysis/eval_cache.js

@@ -0,0 +1,138 @@
+// Per-user memory of cloud-engine results, so analysis is never lost.
+//
+// Claude often analyses loose FENs or move lines first and adds the moves
+// to a file later. Without this, those nodes land with no [%ceo-eval] and
+// the final pass has to analyse them again. Every result that comes back
+// from the analyse endpoint is remembered here, keyed by user id and
+// position (positionKey, same as transpositions), and every file write
+// (add_move, add_line, apply_mutations, ...) fills nodes whose position is
+// remembered and whose stored eval for that engine is missing or shallower.
+//
+// Keyed by the user id from GET /api/agent/me, not by the token: a hosted
+// OAuth access token rotates hourly, the user id doesn't, and one user's
+// analysed positions (their prep) must never land in another user's file.
+// In memory only: a process restart forgets, which costs a re-analysis,
+// never a wrong eval. Every function here is best-effort and never throws
+// into the write path.
+import { createHash } from "node:crypto";
+import { authedRequest, resolveAuthHeader } from "../http.js";
+import { buildIdIndex, positionKey, resolveNodeId } from "../pgn/paths.js";
+import { setCeoEval } from "../pgn/mutations.js";
+import { STORED_EVAL_KEYS } from "../pgn/types.js";
+const TTL_MS = 24 * 60 * 60 * 1000;
+const MAX_POSITIONS_PER_USER = 20_000;
+const MAX_KNOWN_TOKENS = 1_000;
+const cacheByUser = new Map();
+// sha256(Authorization header) → user id. Never the raw token.
+const userByToken = new Map();
+async function currentUserId() {
+    const auth = resolveAuthHeader();
+    if (!auth)
+        return null;
+    const key = createHash("sha256").update(auth).digest("hex");
+    let p = userByToken.get(key);
+    if (!p) {
+        if (userByToken.size >= MAX_KNOWN_TOKENS)
+            userByToken.clear();
+        p = authedRequest("GET", "/api/agent/me")
+            .then(r => {
+            const id = r?.userId;
+            return typeof id === "string" && id ? id : null;
+        })
+            .catch(() => null);
+        userByToken.set(key, p);
+    }
+    const id = await p;
+    // Don't pin a failure (backend blip, old backend): ask again next time.
+    if (!id)
+        userByToken.delete(key);
+    return id;
+}
+const deeper = (a, b) => (a ?? 0) > (b ?? 0);
+// Remember fresh results. Per engine, a deeper result replaces a shallower
+// one; equal depth takes the newer.
+export async function rememberEvals(entries) {
+    try {
+        if (entries.length === 0)
+            return;
+        const user = await currentUserId();
+        if (!user)
+            return;
+        let cache = cacheByUser.get(user);
+        if (!cache) {
+            cache = new Map();
+            cacheByUser.set(user, cache);
+        }
+        const now = Date.now();
+        for (const { fen, ev } of entries) {
+            const key = positionKey(fen);
+            const merged = { ...(cache.get(key) ?? {}) };
+            for (const k of STORED_EVAL_KEYS) {
+                const fresh = ev[k];
+                if (!fresh)
+                    continue;
+                const old = merged[k];
+                const oldLive = old && now - old.at < TTL_MS;
+                if (!oldLive || !deeper(old.ev.depth, fresh.depth))
+                    merged[k] = { ev: fresh, at: now };
+            }
+            // Re-insert so Map order is least-recently-written first.
+            cache.delete(key);
+            cache.set(key, merged);
+        }
+        while (cache.size > MAX_POSITIONS_PER_USER) {
+            const oldest = cache.keys().next().value;
+            if (oldest === undefined)
+                break;
+            cache.delete(oldest);
+        }
+    }
+    catch {
+        // best-effort
+    }
+}
+// Fill remembered evals into the file: every node whose position was
+// analysed gets the engines it lacks, or a deeper read than it holds.
+// Returns the file unchanged (and filled = 0) on any problem. `skipIds`
+// are nodes whose eval the caller set or cleared on purpose in this write.
+export async function fillFromCache(file, skipIds = new Set()) {
+    try {
+        const user = await currentUserId();
+        const cache = user ? cacheByUser.get(user) : undefined;
+        if (!cache || cache.size === 0)
+            return { file, filled: 0 };
+        const now = Date.now();
+        const patches = [];
+        const walk = (node) => {
+            if (!skipIds.has(node.id)) {
+                const hit = cache.get(positionKey(node.fen));
+                if (hit) {
+                    const patch = {};
+                    for (const k of STORED_EVAL_KEYS) {
+                        const c = hit[k];
+                        if (!c || now - c.at >= TTL_MS)
+                            continue;
+                        const stored = node.ceoEval?.[k];
+                        if (!stored || deeper(c.ev.depth, stored.depth))
+                            patch[k] = c.ev;
+                    }
+                    if (patch.sf || patch.lc0 || patch.human)
+                        patches.push({ id: node.id, ev: patch });
+                }
+            }
+            for (const c of node.children)
+                walk(c);
+        };
+        walk(file.root);
+        if (patches.length === 0)
+            return { file, filled: 0 };
+        const idIndex = buildIdIndex(file.root);
+        let out = file;
+        for (const p of patches)
+            out = setCeoEval(out, resolveNodeId(idIndex, p.id), p.ev).file;
+        return { file: out, filled: patches.length };
+    }
+    catch {
+        return { file, filled: 0 };
+    }
+}

package/dist/analysis/file_handle.js

@@ -120,48 +120,55 @@ export function getNodeByPath(root, path) {
     }
     return cur;
 }
-// Persist a fresh ceoEval on the node referenced by the file handle
-// AND on every other node in the same file that transposes to the
-// same position (matches on the frontend's 3-field FEN key: piece
-// placement + side to move + castling). Best-effort — if the file
-// version raced (another agent saved between our GET and our PUT),
-// we silently drop the store rather than fail the analysis the LLM
-// actually asked for. The eval is still returned in the response
-// either way.
+// Merge fresh evals into a file and save once. Each entry is stamped on
+// every node that reaches its position (the frontend's 3-field FEN key:
+// piece placement + side to move + castling), so a transposition is never
+// analysed twice. Merging per engine means a Stockfish-only result keeps a
+// stored human or Lc0 read.
 //
-// Return: ids of every node the eval was stamped on (empty on error).
-// The primary node's id is always first (if present).
+// The file is re-read right before the write, and a version race (someone
+// saved between our GET and PUT) is retried once on a fresh copy; the merge
+// makes re-applying safe. Returns, per entry, the ids it was stamped on
+// (empty if that position is not in the file). Throws if the save fails
+// twice, so callers can report it rather than silently lose evals.
+export async function storeEvals(fileId, entries) {
+    let lastErr;
+    for (let attempt = 0; attempt < 2; attempt++) {
+        const g = await fetchGame(fileId);
+        const parsed = parsePGN(g.pgnContent);
+        const fenIndex = buildFenIndex(parsed.root);
+        const idIndex = buildIdIndex(parsed.root);
+        let file = parsed;
+        const stamped = [];
+        for (const { fen, ev } of entries) {
+            const group = fenIndex.get(positionKey(fen)) ?? [];
+            const paths = group.map(n => resolveNodeId(idIndex, n.id));
+            const step = setCeoEvalMany(file, paths, ev);
+            file = step.file;
+            stamped.push(step.ids);
+        }
+        if (stamped.every(ids => ids.length === 0))
+            return stamped;
+        try {
+            await saveGame(fileId, exportPGN(file), g.version ?? 0);
+            return stamped;
+        }
+        catch (err) {
+            lastErr = err;
+        }
+    }
+    throw lastErr instanceof Error ? lastErr : new Error(String(lastErr));
+}
+// Single-node wrapper: stamp `ev` on the handle's node and its transpositions.
+// Returns the ids, the addressed node first; empty on failure (the analysis
+// result is still returned to the caller either way).
 export async function storeEvalOnNode(handle, ev) {
     try {
         const anchor = getNodeByPath(handle.parsedFile.root, handle.nodePath);
-        const key = positionKey(anchor.fen);
-        const fenIndex = buildFenIndex(handle.parsedFile.root);
-        const group = fenIndex.get(key) ?? [anchor];
-        // Resolve every transposed node back to its path. cloneOnPath
-        // rebuilds the spine so we need paths, not references — the
-        // id index was built against the original tree and every id in
-        // `group` exists there.
-        const idIndex = handle.idIndex ?? buildIdIndex(handle.parsedFile.root);
-        const paths = group.map(n => resolveNodeId(idIndex, n.id));
-        const { file: newFile, ids } = setCeoEvalMany(handle.parsedFile, paths, ev);
-        const newPgn = exportPGN(newFile);
-        await saveGame(handle.id, newPgn, handle.version);
-        // Ensure the primary node (the one the LLM addressed) comes first.
-        const anchorId = anchor.id;
-        return [anchorId, ...ids.filter(x => x !== anchorId)];
+        const [ids] = await storeEvals(handle.id, [{ fen: anchor.fen, ev }]);
+        return [anchor.id, ...(ids ?? []).filter(x => x !== anchor.id)];
     }
     catch {
         return [];
     }
 }
-// Routing fields for POST /api/agent/cloud-engines/analyse: which rental to
-// run on and which engine legs to run. Omitted fields let the backend pick.
-export function analyseRouting(args) {
-    const out = {};
-    if (typeof args.contract_id === "string" && args.contract_id.trim()) {
-        out.contract_id = args.contract_id.trim();
-    }
-    if (Array.isArray(args.engines))
-        out.engines = args.engines;
-    return out;
-}