@chessceo/mcp 0.44.0 → 0.46.0

package/dist/analysis/auto.js

@@ -0,0 +1,291 @@
+// auto_evaluate: async background job that walks a prep-file subtree and
+// stores an engine eval on every node via cloud_analyse. Kept as its own
+// module in v0.44 (was 300 LOC in the middle of src/index.ts) — the job
+// lifecycle (start, run, status, cancel) is one self-contained unit.
+//
+// The naive walk-and-await approach held one HTTP request open for the
+// full duration of the walk (200 nodes × ~1.5s serialized on the
+// per-combo engine semaphore = ~5 min). MCP hosts vary in their
+// tolerance for that. Switched to a background-job model:
+//
+//   1. `auto_evaluate` collects targets, spawns an unawaited worker,
+//      returns `{ job_id, target_count }` immediately.
+//   2. `auto_evaluate_status(job_id)` returns live progress; the LLM
+//      can poll while doing other work on the tree.
+//   3. `auto_evaluate_cancel(job_id)` aborts a running job cleanly;
+//      partial progress up to the last checkpoint is preserved.
+//
+// The MCP server is long-lived (chessceo-mcp.service under systemd), so
+// in-memory job state survives across HTTP requests. On process restart
+// jobs disappear — polling returns `not_found` and the LLM re-runs (the
+// `only_missing` default naturally skips already-evaluated nodes).
+//
+// Progress is checkpointed to the prep file every SAVE_EVERY_N nodes so
+// a mid-run crash / cancellation doesn't lose the whole walk.
+import { authedRequest, fetchGame } from "../http.js";
+import { analysisToStoredEval } from "./response.js";
+import { parsePGN } from "../pgn/parser.js";
+import { buildIdIndex, positionKey, resolveNodeId, ROOT_ID } from "../pgn/paths.js";
+const evalJobs = new Map();
+// GC finished jobs after this long so status polling remains useful
+// for a while but the map doesn't grow unbounded across long uptimes.
+const EVAL_JOB_TTL_MS = 15 * 60 * 1000;
+// Checkpoint interval — save progress every N successfully-evaluated
+// nodes so a mid-run kill leaves the tree partially populated. Small
+// enough that <15s of work is at risk per checkpoint on a slow combo,
+// large enough that the save overhead stays a small fraction of the
+// per-node cost.
+const SAVE_EVERY_N = 8;
+function newEvalJobId() {
+    // 12 hex chars, low collision (same 32-bit width as node ids ×1.5).
+    const rand = Math.random().toString(16).slice(2, 8);
+    return `evj_${Date.now().toString(16)}${rand}`;
+}
+// Sweep expired jobs on every start/status call — cheap, doesn't need
+// a background timer, keeps the map bounded to active + recent jobs.
+function reapExpiredEvalJobs() {
+    const now = Date.now();
+    for (const [k, j] of evalJobs) {
+        if (j.finishedAt && now - j.finishedAt > EVAL_JOB_TTL_MS) {
+            evalJobs.delete(k);
+        }
+    }
+}
+// Path->node helper duplicated here so auto.ts doesn't depend on index.ts.
+// Same body as index.ts:getNodeByPath.
+function getNodeByPath(root, path) {
+    let cur = root;
+    for (const idx of path) {
+        if (idx < 0 || idx >= cur.children.length)
+            throw new Error(`invalid node path segment ${idx}`);
+        cur = cur.children[idx];
+    }
+    return cur;
+}
+export async function autoEvaluate(args, applyBatchMutations) {
+    reapExpiredEvalJobs();
+    const id = String(args.id);
+    const startNodeId = typeof args.node_id === "string" && args.node_id.length > 0
+        ? String(args.node_id)
+        : ROOT_ID;
+    const onlyMissing = args.only_missing !== false; // default true
+    const movetimeMs = typeof args.movetime_ms === "number" ? args.movetime_ms : 1500;
+    const g = await fetchGame(id);
+    const file = parsePGN(g.pgnContent);
+    const idIndex = buildIdIndex(file.root);
+    const startPath = resolveNodeId(idIndex, startNodeId);
+    const targets = [];
+    const walk = (node, isStartAndRoot) => {
+        if (!isStartAndRoot) {
+            if (!onlyMissing || !node.ceoEval) {
+                targets.push({ nodeId: node.id, fen: node.fen });
+            }
+        }
+        for (const child of node.children)
+            walk(child, false);
+    };
+    const startNode = getNodeByPath(file.root, startPath);
+    // If the caller anchored at the root, skip evaluating the root itself
+    // (no move); otherwise the anchor node IS a real move and gets evaluated.
+    walk(startNode, startNode.id === ROOT_ID);
+    // Dedup transpositions: if two candidate targets share the same
+    // 3-field FEN key, they're the same position reached by different
+    // move orders. Analyse ONE of them — cloud_analyse auto-propagates
+    // the resulting ceoEval to every other node with a matching key
+    // (see storeEvalOnNode), so the twin ends up with the same eval
+    // without a second engine call. Keep DFS-first (mainline-preferred)
+    // occurrence.
+    let skippedTranspositions = 0;
+    {
+        const seen = new Set();
+        const deduped = [];
+        for (const t of targets) {
+            const key = positionKey(t.fen);
+            if (seen.has(key)) {
+                skippedTranspositions++;
+                continue;
+            }
+            seen.add(key);
+            deduped.push(t);
+        }
+        targets.length = 0;
+        targets.push(...deduped);
+    }
+    // Nothing to do → return a done job synthetically so the caller doesn't
+    // need to special-case the empty response.
+    if (targets.length === 0) {
+        const jobId = newEvalJobId();
+        evalJobs.set(jobId, {
+            id: jobId,
+            fileId: id,
+            status: "done",
+            targetCount: 0,
+            evaluated: 0,
+            errored: 0,
+            failedNodeIds: [],
+            finalVersion: g.version,
+            startedAt: Date.now(),
+            finishedAt: Date.now(),
+            cancelled: false,
+        });
+        return { job_id: jobId, target_count: 0, status: "done", version: g.version };
+    }
+    const jobId = newEvalJobId();
+    const job = {
+        id: jobId,
+        fileId: id,
+        status: "running",
+        targetCount: targets.length,
+        evaluated: 0,
+        errored: 0,
+        failedNodeIds: [],
+        startedAt: Date.now(),
+        cancelled: false,
+    };
+    evalJobs.set(jobId, job);
+    // Unawaited — runs concurrently with the tool response. Any thrown
+    // error gets recorded on the job so the LLM's status poll surfaces
+    // it instead of the process seeing an unhandled rejection.
+    void runEvalJob(job, id, targets, movetimeMs, applyBatchMutations).catch(err => {
+        job.status = "error";
+        job.error = err instanceof Error ? err.message : String(err);
+        job.finishedAt = Date.now();
+    });
+    return {
+        job_id: jobId,
+        target_count: targets.length,
+        // Transpositions inside the walk that we skipped because they'll
+        // pick up the eval via auto-propagation. Zero when there are none.
+        skipped_transpositions: skippedTranspositions,
+        status: "running",
+        // Rough time estimate at the current default movetime. Serialization
+        // on the per-combo semaphore means walltime ≈ target_count × movetime.
+        estimated_seconds: Math.round((targets.length * movetimeMs) / 1000),
+    };
+}
+// Worker body — walks targets sequentially (concurrency > 1 is a lie
+// against the per-combo semaphore in the backend anyway), checkpoints
+// every SAVE_EVERY_N successfully-evaluated nodes so partial progress
+// is durable, and re-anchors the version after each save.
+async function runEvalJob(job, fileId, targets, movetimeMs, applyBatchMutations) {
+    const pending = [];
+    const flush = async () => {
+        if (pending.length === 0)
+            return;
+        // No expected_version — auto_evaluate treats concurrent edits by
+        // the LLM as last-write-wins on the ceoEval field specifically.
+        // Safe because set_ceo_eval is idempotent per node and other
+        // mutations (add_move / set_comment / etc.) don't touch ceoEval.
+        const saved = await applyBatchMutations({
+            id: fileId,
+            mutations: pending,
+        });
+        const sr = saved;
+        if (typeof sr.version === "number")
+            job.finalVersion = sr.version;
+        pending.length = 0;
+    };
+    // Consecutive-failure abort. If N cloud_analyse calls in a row error,
+    // the engine is almost certainly dead (vanished contract, network to
+    // VastAI down) and burning through the rest of the tree just wastes
+    // time. Bail with an explicit reason so a targeted retry is possible.
+    const MAX_CONSECUTIVE_FAILURES = 3;
+    let consecutiveFailures = 0;
+    let aborted = false;
+    for (const t of targets) {
+        if (job.cancelled || aborted)
+            break;
+        try {
+            const analysis = await authedRequest("POST", "/api/agent/cloud-engines/analyse", { fen: t.fen, movetime_ms: movetimeMs, multipv: 1 });
+            const ev = analysisToStoredEval(analysis);
+            if (ev) {
+                pending.push({ op: "set_ceo_eval", node_id: t.nodeId, ceoEval: ev });
+                job.evaluated++;
+                consecutiveFailures = 0;
+            }
+            else {
+                job.errored++;
+                job.failedNodeIds.push(t.nodeId);
+                consecutiveFailures++;
+            }
+        }
+        catch {
+            // Per-node failure — record the node_id so the caller can retry
+            // just those, and count consecutive failures for the abort check.
+            job.errored++;
+            job.failedNodeIds.push(t.nodeId);
+            consecutiveFailures++;
+        }
+        if (consecutiveFailures >= MAX_CONSECUTIVE_FAILURES) {
+            aborted = true;
+            job.abortedReason = `aborted after ${MAX_CONSECUTIVE_FAILURES} consecutive cloud_analyse failures — check that the cloud combo is still running (list_cloud_engines)`;
+            break;
+        }
+        if (pending.length >= SAVE_EVERY_N) {
+            try {
+                await flush();
+            }
+            catch {
+                // Save failure is bad but not fatal — try again on the next
+                // checkpoint or at the end. Progress remains in `pending`
+                // so nothing is lost as long as the process stays alive.
+            }
+        }
+    }
+    // Final flush regardless of cancellation — durably persist whatever
+    // work was completed before the user asked to stop.
+    try {
+        await flush();
+    }
+    catch (err) {
+        job.error = err instanceof Error ? err.message : String(err);
+        job.status = "error";
+        job.finishedAt = Date.now();
+        return;
+    }
+    job.status = job.cancelled ? "cancelled" : "done";
+    job.finishedAt = Date.now();
+}
+export function autoEvaluateStatus(args) {
+    reapExpiredEvalJobs();
+    const jobId = String(args.job_id || "").trim();
+    if (!jobId)
+        throw new Error("`job_id` is required");
+    const job = evalJobs.get(jobId);
+    if (!job) {
+        return {
+            status: "not_found",
+            note: "Job unknown — either expired (kept ~15 min after completion), never existed, or the MCP process restarted since it was created. Re-run auto_evaluate to start over; the `only_missing` default will skip nodes already evaluated in the prep file.",
+        };
+    }
+    return {
+        job_id: job.id,
+        status: job.status,
+        target_count: job.targetCount,
+        evaluated: job.evaluated,
+        errored: job.errored,
+        failed_node_ids: job.failedNodeIds, // exact ids for targeted retry — pass as node_id list or check with list_nodes
+        aborted_reason: job.abortedReason, // present when the job stopped early due to consecutive engine failures
+        remaining: Math.max(0, job.targetCount - job.evaluated - job.errored),
+        done: job.status !== "running",
+        error: job.error,
+        version: job.finalVersion,
+        started_at_ms: job.startedAt,
+        finished_at_ms: job.finishedAt,
+    };
+}
+export function autoEvaluateCancel(args) {
+    const jobId = String(args.job_id || "").trim();
+    if (!jobId)
+        throw new Error("`job_id` is required");
+    const job = evalJobs.get(jobId);
+    if (!job)
+        return { status: "not_found" };
+    if (job.status !== "running") {
+        return { status: job.status, note: "Job already finished; nothing to cancel." };
+    }
+    job.cancelled = true;
+    // status transitions to "cancelled" on the next per-node iteration
+    // inside runEvalJob, after the final flush persists progress.
+    return { status: "cancelling", evaluated_so_far: job.evaluated };
+}

package/dist/analysis/deep.js

@@ -0,0 +1,157 @@
+// 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 { resolveFromNodeOrFen, storeEvalOnNode, } from "./file_handle.js";
+const deepJobs = new Map();
+const DEEP_JOB_TTL_MS = 15 * 60 * 1000;
+function newDeepJobId() {
+    const rand = Math.random().toString(16).slice(2, 8);
+    return `deep_${Date.now().toString(16)}${rand}`;
+}
+function reapExpiredDeepJobs() {
+    const now = Date.now();
+    for (const [k, j] of deepJobs) {
+        if (j.finishedAt && now - j.finishedAt > DEEP_JOB_TTL_MS) {
+            deepJobs.delete(k);
+        }
+    }
+}
+export async function deepAnalyseStart(args) {
+    reapExpiredDeepJobs();
+    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;
+    const jobId = newDeepJobId();
+    const job = {
+        id: jobId,
+        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,
+    };
+}
+async function runDeepJob(job) {
+    const body = {
+        fen: job.fen,
+        movetime_ms: job.movetimeMs,
+        stockfish_multipv: job.multipv,
+        engines: ["stockfish"],
+    };
+    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);
+    }
+    catch (err) {
+        job.status = "error";
+        job.error = err instanceof Error ? err.message : String(err);
+        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 });
+        if (ev) {
+            try {
+                await storeEvalOnNode(job.fileHandle, ev);
+            }
+            catch {
+                // best-effort — the analysis result is what the LLM asked for
+            }
+        }
+    }
+}
+export function deepAnalyseStatus(args) {
+    reapExpiredDeepJobs();
+    const jobId = String(args.job_id || "").trim();
+    if (!jobId)
+        throw new Error("`job_id` is required");
+    const job = deepJobs.get(jobId);
+    if (!job) {
+        return {
+            status: "not_found",
+            note: "Job unknown — expired (kept ~15 min after completion), never existed, or the MCP process restarted.",
+        };
+    }
+    return {
+        job_id: job.id,
+        status: job.status,
+        movetime_ms: job.movetimeMs,
+        elapsed_ms: (job.finishedAt ?? Date.now()) - job.startedAt,
+        fen: job.fen,
+        result: job.result,
+        error: job.error,
+        started_at_ms: job.startedAt,
+        finished_at_ms: job.finishedAt,
+    };
+}
+export function deepAnalyseCancel(args) {
+    const jobId = String(args.job_id || "").trim();
+    if (!jobId)
+        throw new Error("`job_id` is required");
+    const job = deepJobs.get(jobId);
+    if (!job)
+        return { status: "not_found" };
+    if (job.status !== "running") {
+        return { status: job.status, note: "Job already finished; nothing to cancel." };
+    }
+    job.cancelController.abort();
+    // Status flips to "cancelled" when runDeepJob observes the abort on
+    // completion. Backend keeps churning until movetime elapses (mid-
+    // flight abort of the HTTP call is a follow-up).
+    return { status: "cancelling", elapsed_ms: Date.now() - job.startedAt };
+}

package/dist/analysis/file_handle.js

@@ -0,0 +1,156 @@
+// Shared address resolution for engine + DB tools. Every position-taking
+// tool (cloud_analyse, describe_position, predict_human_move,
+// prep_snapshot, get_prep_position, find_position_in_files,
+// find_position_in_courses, deep_analyse, quote_engine_eval) accepts the
+// same set of position inputs — this module normalises them into a FEN
+// (and, when the caller was inside a prep file, a FileHandle that lets
+// the downstream write ceoEval back on the resolved node).
+//
+// Extracted from index.ts in v0.44 as part of the file split.
+import { Chess } from "chess.js";
+import { fetchGame, saveGame } from "../http.js";
+import { parsePGN } from "../pgn/parser.js";
+import { exportPGN } from "../pgn/exporter.js";
+import { buildFenIndex, buildIdIndex, positionKey, resolveNodeId, } from "../pgn/paths.js";
+import { setCeoEvalMany } from "../pgn/mutations.js";
+// Async resolver used by every engine / DB tool. Three paths:
+//
+//   1. file_id + node_id → load file, resolve node, return FEN + handle
+//      to persist ceoEval later. Cheapest, most explicit.
+//
+//   2. file_id + (fen | moves | line) → load file, resolve FEN
+//      client-side, then scan the file's nodes for one matching that
+//      FEN. If found, return the same handle as (1) so cloud_analyse
+//      auto-stores on the matching node. Fixes the previous footgun
+//      where `cloud_analyse({file_id, moves})` silently dropped the
+//      eval because the server didn't try to match the resulting FEN
+//      back to a node.
+//
+//   3. Just fen | moves | line, no file_id → scratch mode, no
+//      persistence. Same as before.
+export async function resolveFromNodeOrFen(args) {
+    const fileId = typeof args.file_id === "string" ? args.file_id.trim() : "";
+    const nodeId = typeof args.node_id === "string" ? args.node_id.trim() : "";
+    if (fileId && nodeId) {
+        const g = await fetchGame(fileId);
+        const parsedFile = parsePGN(g.pgnContent);
+        const idIndex = buildIdIndex(parsedFile.root);
+        const nodePath = resolveNodeId(idIndex, nodeId);
+        const node = getNodeByPath(parsedFile.root, nodePath);
+        return {
+            fen: node.fen,
+            file: { id: fileId, version: g.version ?? 0, parsedFile, idIndex, nodePath, fen: node.fen },
+        };
+    }
+    if (fileId) {
+        // file_id only — resolve FEN from fen/moves/line, then look it up
+        // in the file's nodes. If a node has that FEN, treat this as if
+        // node_id had been supplied (auto-persist on match).
+        const fen = resolveFenFromArgs(args);
+        try {
+            const g = await fetchGame(fileId);
+            const parsedFile = parsePGN(g.pgnContent);
+            const match = findNodeByFen(parsedFile.root, fen);
+            if (match) {
+                const idIndex = buildIdIndex(parsedFile.root);
+                return {
+                    fen,
+                    file: { id: fileId, version: g.version ?? 0, parsedFile, idIndex, nodePath: match.path, fen },
+                };
+            }
+        }
+        catch {
+            // Best-effort: if the file load fails, fall through to scratch mode.
+        }
+        return { fen };
+    }
+    return { fen: resolveFenFromArgs(args) };
+}
+// Normalize the LLM's position inputs into a single FEN. Used both by
+// resolveFromNodeOrFen and directly by tools that don't need a file
+// handle. Accepts three shapes: bare `fen`, `moves` from startpos (SAN
+// space-separated, with optional `1.` / `1...` move-number prefixes
+// stripped), or `fen`+`moves` layered together. `line` is a legacy
+// alias for `moves`.
+export function resolveFenFromArgs(args) {
+    const fenArg = typeof args.fen === "string" ? args.fen.trim() : "";
+    const movesArg = typeof args.moves === "string" ? args.moves.trim() : "";
+    const lineArg = typeof args.line === "string" ? args.line.trim() : "";
+    const sequence = movesArg || lineArg;
+    const board = fenArg ? new Chess(fenArg) : new Chess();
+    if (sequence) {
+        for (const raw of sequence.split(/\s+/)) {
+            const san = raw.replace(/^\d+\.+/, "");
+            if (!san)
+                continue;
+            try {
+                board.move(san);
+            }
+            catch {
+                throw new Error(`bad SAN token '${raw}' in moves`);
+            }
+        }
+    }
+    return board.fen();
+}
+// Search the tree for a node whose FEN matches. Full-tree scan — trees
+// max out ~1000 nodes so this is fine. FEN comparison is exact string
+// match (both come from the same chessops normalisation).
+export function findNodeByFen(root, targetFen) {
+    const stack = [{ node: root, path: [] }];
+    while (stack.length > 0) {
+        const { node, path } = stack.pop();
+        if (node.fen === targetFen)
+            return { node, path };
+        for (let i = 0; i < node.children.length; i++) {
+            stack.push({ node: node.children[i], path: [...path, i] });
+        }
+    }
+    return null;
+}
+// Local wrapper for path→node navigation — kept here so callers of the
+// file_handle module don't have to import pgn/paths.js just for one
+// walk. Body identical to paths.getNode.
+export function getNodeByPath(root, path) {
+    let cur = root;
+    for (const idx of path) {
+        if (idx < 0 || idx >= cur.children.length)
+            throw new Error(`invalid node path segment ${idx}`);
+        cur = cur.children[idx];
+    }
+    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.
+//
+// Return: ids of every node the eval was stamped on (empty on error).
+// The primary node's id is always first (if present).
+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)];
+    }
+    catch {
+        return [];
+    }
+}