@chessceo/mcp 0.49.10 → 0.50.0

package/dist/analysis/auto.js

@@ -1,49 +1,35 @@
 // 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:
+// stores engine evals on every node. The job lifecycle (start, run, status,
+// cancel) is one self-contained unit.
 //
 //   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.
+//   2. `auto_evaluate_status(job_id)` returns live progress per engine.
+//   3. `auto_evaluate_cancel(job_id)` stops the job; everything analysed
+//      up to the last saved batch stays in the file.
 //
-// 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).
+// Each node gets only the requested engines it is missing, so re-running
+// with another engine (e.g. adding `human` after a Stockfish pass) analyses
+// just that engine. Transpositions are analysed once and the eval is stamped
+// on every node that reaches the position. Results are saved after every
+// backend batch (up to 10 positions), merged per engine.
 //
-// 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 { analyseRouting } from "./file_handle.js";
+// The MCP server is long-lived (chessceo-mcp.service), so in-memory job
+// state survives across HTTP requests. On restart jobs disappear; re-running
+// skips what is already stored.
+import { fetchGame } from "../http.js";
+import { analysePositions, convertPositionResult, ENGINES, MAX_POSITIONS_PER_CALL, parseEngines, resultToStoredEval, STORED_KEY, } from "./response.js";
+import { storeEvals } from "./file_handle.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) {
@@ -52,8 +38,6 @@ function reapExpiredEvalJobs() {
         }
     }
 }
-// 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) {
@@ -63,187 +47,189 @@ function getNodeByPath(root, path) {
     }
     return cur;
 }
-export async function autoEvaluate(args, applyBatchMutations) {
+export async function autoEvaluate(args) {
     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 engines = parseEngines(args.engines, ["stockfish"]);
+    const movetimeMs = typeof args.movetime_ms === "number" ? args.movetime_ms : 2000;
+    const baseOpts = { engines, movetime_ms: movetimeMs };
+    if (typeof args.contempt === "number")
+        baseOpts.contempt = args.contempt;
+    if (args.rentals && typeof args.rentals === "object")
+        baseOpts.rentals = args.rentals;
     const g = await fetchGame(id);
     const file = parsePGN(g.pgnContent);
     const idIndex = buildIdIndex(file.root);
     const startPath = resolveNodeId(idIndex, startNodeId);
-    const targets = [];
+    const startNode = getNodeByPath(file.root, startPath);
+    // Every node in the subtree (the root itself has no move to evaluate
+    // when the walk starts there). With only_missing, a node needs just the
+    // requested engines it has no stored eval for. One target per position:
+    // transpositions are analysed once and the eval is stamped on every twin
+    // at save time, and a twin's stored engines count for the position.
+    const byKey = new Map();
+    // Stored evals per position, merged across twins, and whether some twin
+    // lacks an engine another twin already has (then we copy, not re-run).
+    const known = new Map();
+    let skippedTranspositions = 0;
+    let alreadyComplete = 0;
     const walk = (node, isStartAndRoot) => {
         if (!isStartAndRoot) {
-            if (!onlyMissing || !node.ceoEval) {
-                targets.push({ nodeId: node.id, fen: node.fen });
+            const key = positionKey(node.fen);
+            const have = (e) => Boolean(node.ceoEval?.[STORED_KEY[e]]);
+            const missing = onlyMissing ? engines.filter(e => !have(e)) : [...engines];
+            const prev = byKey.get(key);
+            if (prev) {
+                skippedTranspositions++;
+                // Only engines missing on every twin need running.
+                prev.engines = prev.engines.filter(e => missing.includes(e));
+            }
+            else {
+                byKey.set(key, { nodeId: node.id, fen: node.fen, engines: missing });
+            }
+            const k = known.get(key) ?? { fen: node.fen, ev: {}, nodes: 0, has: {} };
+            k.nodes++;
+            for (const e of engines) {
+                const mine = node.ceoEval?.[STORED_KEY[e]];
+                if (!mine)
+                    continue;
+                k.has[e] = (k.has[e] ?? 0) + 1;
+                if (!k.ev[STORED_KEY[e]])
+                    k.ev[STORED_KEY[e]] = mine;
             }
+            known.set(key, k);
         }
         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);
+    // Twins that lack an engine another twin has: copy it over now (merge,
+    // no engine time).
+    const copies = onlyMissing
+        ? [...known.values()]
+            .filter(k => engines.some(e => (k.has[e] ?? 0) > 0 && (k.has[e] ?? 0) < k.nodes))
+            .map(k => ({ fen: k.fen, ev: k.ev }))
+        : [];
+    if (copies.length > 0)
+        await storeEvals(id, copies);
+    const targets = [...byKey.values()].filter(t => {
+        if (t.engines.length === 0) {
+            alreadyComplete++;
+            return false;
         }
-        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 };
-    }
+        return true;
+    });
     const jobId = newEvalJobId();
     const job = {
         id: jobId,
         fileId: id,
-        status: "running",
+        status: targets.length === 0 ? "done" : "running",
+        engines,
         targetCount: targets.length,
-        evaluated: 0,
-        errored: 0,
-        failedNodeIds: [],
+        processed: 0,
+        evaluated: {},
+        failed: {},
         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, analyseRouting(args)).catch(err => {
-        job.status = "error";
-        job.error = err instanceof Error ? err.message : String(err);
+    if (targets.length === 0)
         job.finishedAt = Date.now();
-    });
+    evalJobs.set(jobId, job);
+    if (targets.length > 0) {
+        void runEvalJob(job, targets, baseOpts).catch(err => {
+            job.status = "error";
+            job.error = err instanceof Error ? err.message : String(err);
+            job.finishedAt = Date.now();
+        });
+    }
+    // Engines run in parallel per position, positions one after another.
+    const estimatedSeconds = Math.round((targets.length * movetimeMs) / 1000);
     return {
         job_id: jobId,
+        status: job.status,
+        engines,
         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.
+        already_complete: alreadyComplete,
         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),
+        copied_to_transpositions: copies.length,
+        estimated_seconds: estimatedSeconds,
     };
 }
-// 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, routing) {
-    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;
+// Worker: groups targets by which engines they need (so a node that only
+// lacks `human` doesn't re-run Stockfish), sends batches of up to 10
+// positions, and saves each batch's evals right away.
+async function runEvalJob(job, targets, baseOpts) {
+    const groups = new Map();
     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, ...routing });
-            const ev = analysisToStoredEval(analysis);
-            if (ev) {
-                pending.push({ op: "set_ceo_eval", node_id: t.nodeId, ceoEval: ev });
-                job.evaluated++;
+        const sig = t.engines.join(",");
+        groups.set(sig, [...(groups.get(sig) ?? []), t]);
+    }
+    // Two failed batches in a row means the engine or rental is gone; stop
+    // with a reason instead of burning through the rest of the tree.
+    const MAX_CONSECUTIVE_FAILURES = 2;
+    let consecutiveFailures = 0;
+    const markFailed = (t, engine) => {
+        (job.failed[engine] ??= []).push(t.nodeId);
+    };
+    outer: for (const groupTargets of groups.values()) {
+        const engines = groupTargets[0].engines;
+        for (let i = 0; i < groupTargets.length; i += MAX_POSITIONS_PER_CALL) {
+            if (job.cancelled)
+                break outer;
+            const batch = groupTargets.slice(i, i + MAX_POSITIONS_PER_CALL);
+            let results;
+            try {
+                results = await analysePositions(batch.map(t => ({ id: t.nodeId, fen: t.fen })), { ...baseOpts, engines });
                 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 (err) {
+                job.lastError = err instanceof Error ? err.message : String(err);
+                for (const t of batch)
+                    for (const e of engines)
+                        markFailed(t, e);
+                job.processed += batch.length;
+                if (++consecutiveFailures >= MAX_CONSECUTIVE_FAILURES) {
+                    job.abortedReason = `stopped after ${MAX_CONSECUTIVE_FAILURES} failed batches in a row: ${job.lastError}. Check list_cloud_engines.`;
+                    break outer;
+                }
+                continue;
             }
-            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.
+            const entries = [];
+            batch.forEach((t, idx) => {
+                const r = results[idx];
+                const ev = r ? resultToStoredEval(convertPositionResult(r)) : null;
+                for (const e of engines) {
+                    if (ev?.[STORED_KEY[e]])
+                        job.evaluated[e] = (job.evaluated[e] ?? 0) + 1;
+                    else {
+                        markFailed(t, e);
+                        const msg = r?.engines?.[e]?.error;
+                        if (msg)
+                            job.lastError = `${e}: ${msg}`;
+                    }
+                }
+                if (ev)
+                    entries.push({ fen: t.fen, ev });
+            });
+            job.processed += batch.length;
+            if (entries.length > 0) {
+                try {
+                    await storeEvals(job.fileId, entries);
+                }
+                catch (err) {
+                    // The analysis is lost for this batch; record and keep going.
+                    job.lastError = `save failed: ${err instanceof Error ? err.message : String(err)}`;
+                    for (const t of batch)
+                        for (const e of engines)
+                            markFailed(t, e);
+                }
             }
         }
     }
-    // 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();
 }
@@ -256,21 +242,27 @@ export function autoEvaluateStatus(args) {
     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.",
+            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; the `only_missing` default skips engines already stored in the prep file.",
         };
     }
+    const failedCount = {};
+    for (const e of ENGINES)
+        if (job.failed[e]?.length)
+            failedCount[e] = job.failed[e].length;
     return {
         job_id: job.id,
         status: job.status,
+        engines: job.engines,
         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),
+        processed: job.processed,
+        remaining: Math.max(0, job.targetCount - job.processed),
+        evaluated: job.evaluated, // positions stored, per engine
+        failed: failedCount, // positions without a result, per engine
+        failed_node_ids: job.failed, // per engine, for a targeted retry with node_id
+        last_error: job.lastError,
+        aborted_reason: job.abortedReason,
         done: job.status !== "running",
         error: job.error,
-        version: job.finalVersion,
         started_at_ms: job.startedAt,
         finished_at_ms: job.finishedAt,
     };
@@ -286,7 +278,6 @@ export function autoEvaluateCancel(args) {
         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 };
+    // status turns "cancelled" once the batch in flight is saved.
+    return { status: "cancelling", processed_so_far: job.processed };
 }

package/dist/analysis/cloud.js

@@ -0,0 +1,182 @@
+// cloud_analyse and ensure_engines: the synchronous analysis tool and the
+// rental planner. cloud_analyse runs up to 10 positions on any engines the
+// caller has running (stockfish, lc0, human), each engine on whichever
+// rental provides it, and stores the evals on matching nodes when a file is
+// given. ensure_engines tells the caller what is running, what it would
+// need to start, and what a job would cost, without starting anything.
+import { Chess } from "chess.js";
+import { authedRequest, fetchGame } from "../http.js";
+import { parsePGN } from "../pgn/parser.js";
+import { buildIdIndex, resolveNodeId } from "../pgn/paths.js";
+import { analyseOptionsFromArgs, analysePositions, convertPositionResult, DEFAULT_MOVETIME_MS, engineFailures, MAX_POSITIONS_PER_CALL, parseEngines, resultToStoredEval, } from "./response.js";
+import { getNodeByPath, resolveFenFromArgs, storeEvals } from "./file_handle.js";
+function stringList(v) {
+    if (!Array.isArray(v))
+        return [];
+    return v.map(x => String(x).trim()).filter(x => x.length > 0);
+}
+// Collect the positions to analyse from the tool args. Accepts lists
+// (`node_ids` with `file_id`, `fens`, `lines`) and the single-position
+// inputs (`node_id`, `fen`, `moves`), in any combination.
+async function collectPositions(args) {
+    const fileId = typeof args.file_id === "string" ? args.file_id.trim() : "";
+    const nodeIds = stringList(args.node_ids);
+    if (typeof args.node_id === "string" && args.node_id.trim())
+        nodeIds.push(args.node_id.trim());
+    const positions = [];
+    if (nodeIds.length > 0) {
+        if (!fileId)
+            throw new Error("node_id / node_ids need file_id");
+        const g = await fetchGame(fileId);
+        const file = parsePGN(g.pgnContent);
+        const idIndex = buildIdIndex(file.root);
+        for (const nid of nodeIds) {
+            const node = getNodeByPath(file.root, resolveNodeId(idIndex, nid));
+            positions.push({ id: nid, node_id: nid, fen: node.fen });
+        }
+    }
+    const checkFen = (fen) => {
+        try {
+            return new Chess(fen).fen();
+        }
+        catch {
+            throw new Error(`invalid FEN: ${fen}`);
+        }
+    };
+    for (const fen of stringList(args.fens)) {
+        positions.push({ id: `p${positions.length + 1}`, fen: checkFen(fen) });
+    }
+    // `lines`: SAN move sequences, each from `fen` (or the start position).
+    for (const line of stringList(args.lines)) {
+        positions.push({ id: `p${positions.length + 1}`, fen: resolveFenFromArgs({ fen: args.fen, moves: line }) });
+    }
+    if (positions.length === 0 && (typeof args.fen === "string" || typeof args.moves === "string")) {
+        positions.push({ id: "p1", fen: resolveFenFromArgs(args) });
+    }
+    if (positions.length === 0) {
+        throw new Error("nothing to analyse: pass fens, lines, fen/moves, or file_id with node_ids");
+    }
+    return { positions, fileId };
+}
+export async function cloudAnalyse(args, evalScale) {
+    const engines = parseEngines(args.engines, ["stockfish"]);
+    const movetimeMs = typeof args.movetime_ms === "number" ? args.movetime_ms : DEFAULT_MOVETIME_MS;
+    // PVs past ~6 plies are speculative and get pasted into add_line as if
+    // they were prep. Raise only to verify a forcing line.
+    const pvMaxPlies = typeof args.pv_max_plies === "number" && args.pv_max_plies > 0
+        ? Math.min(args.pv_max_plies, 40)
+        : 6;
+    const { positions, fileId } = await collectPositions(args);
+    if (positions.length > MAX_POSITIONS_PER_CALL) {
+        throw new Error(`${positions.length} positions; cloud_analyse takes up to ${MAX_POSITIONS_PER_CALL} per call. ` +
+            "Split the list, or use auto_evaluate for a whole file or subtree.");
+    }
+    const results = await analysePositions(positions.map(p => ({ id: p.id, fen: p.fen })), analyseOptionsFromArgs(args, engines, movetimeMs));
+    const out = positions.map((p, i) => {
+        const r = results[i] ? convertPositionResult(results[i], pvMaxPlies) : { fen: p.fen, engines: {} };
+        const failed = engineFailures(r, engines);
+        return {
+            id: p.id,
+            ...(p.node_id ? { node_id: p.node_id } : {}),
+            fen: p.fen,
+            engines: r.engines,
+            ...(Object.keys(failed).length > 0 ? { failed } : {}),
+        };
+    });
+    // Inside a file: merge each eval into every node that reaches the
+    // position (node-addressed or matched by FEN), in one save. This is what
+    // lets quote_engine_eval cite a measurement later.
+    let storeError;
+    if (fileId) {
+        const entries = [];
+        out.forEach((o, idx) => {
+            const r = results[idx];
+            const ev = r ? resultToStoredEval(r) : null;
+            if (ev)
+                entries.push({ fen: positions[idx].fen, ev, idx });
+        });
+        if (entries.length > 0) {
+            try {
+                const stamped = await storeEvals(fileId, entries);
+                entries.forEach((e, k) => {
+                    if (stamped[k]?.length)
+                        out[e.idx].stored_on = stamped[k];
+                });
+            }
+            catch (err) {
+                storeError = `analysis done but saving to the file failed: ${err instanceof Error ? err.message : String(err)}`;
+            }
+        }
+    }
+    return {
+        engines,
+        movetime_ms: movetimeMs,
+        positions: out,
+        ...(storeError ? { store_error: storeError } : {}),
+        notes: "scoreCp/mate are White's point of view. wdl is win/draw/loss percent, White's point of view.",
+        eval_scale: evalScale,
+    };
+}
+// Read-only rental plan: for each requested engine, the running rental(s)
+// that provide it, or the cheapest available SKU to start. With `positions`,
+// adds a time and cost estimate for analysing that many positions.
+export async function ensureEngines(args) {
+    const engines = parseEngines(args.engines, ["stockfish"]);
+    const movetimeMs = typeof args.movetime_ms === "number" ? args.movetime_ms : DEFAULT_MOVETIME_MS;
+    const positions = typeof args.positions === "number" && args.positions > 0 ? Math.floor(args.positions) : 0;
+    const [rentalsRaw, optionsRaw] = await Promise.all([
+        authedRequest("GET", "/api/agent/cloud-engines"),
+        authedRequest("GET", "/api/agent/cloud-engines/options"),
+    ]);
+    const rentals = (Array.isArray(rentalsRaw) ? rentalsRaw : []);
+    const options = (optionsRaw?.options ?? []);
+    // Engines run in parallel per position, so wall time is per position,
+    // not per engine.
+    const minutes = positions > 0 ? (positions * movetimeMs) / 60000 : 0;
+    const plan = {};
+    const toStart = [];
+    let estCost = 0;
+    for (const e of engines) {
+        const running = rentals.filter(r => (r.engines ?? []).includes(e));
+        if (running.length > 0) {
+            plan[e] = {
+                status: running.length === 1 ? "running" : "several running (pass rentals." + e + " to choose)",
+                rentals: running.map(r => ({ contract_id: r.contractId, name: r.displayName || r.instanceType, cost_per_minute: r.costPerMinute, state: r.instanceStatus || "running" })),
+            };
+            estCost += (running[0].costPerMinute ?? 0) * minutes;
+            continue;
+        }
+        const skus = options
+            .filter(o => o.engine === e && o.available !== false)
+            .sort((a, b) => (a.costPerHour ?? Infinity) - (b.costPerHour ?? Infinity));
+        if (skus.length === 0) {
+            plan[e] = { status: "not available on this account right now" };
+            continue;
+        }
+        toStart.push(e);
+        plan[e] = {
+            status: "not running",
+            cheapest: { machine_type: skus[0].machineType, name: skus[0].displayName, cost_per_hour: skus[0].costPerHour },
+            other_skus: skus.slice(1).map(o => ({ machine_type: o.machineType, name: o.displayName, cost_per_hour: o.costPerHour })),
+        };
+        estCost += (skus[0].costPerMinute ?? (skus[0].costPerHour ?? 0) / 60) * minutes;
+    }
+    return {
+        engines,
+        plan,
+        ...(toStart.length > 0
+            ? { next_step: `Show the user the price for ${toStart.join(", ")} and get a yes, then start_cloud_engine with the machine_type. A new rental takes ~1-5 min to become ready.` }
+            : { next_step: "Everything requested is running. Analyse, then stop_cloud_engine when done." }),
+        ...(positions > 0
+            ? {
+                estimate: {
+                    positions,
+                    movetime_ms: movetimeMs,
+                    minutes: Math.round(minutes * 10) / 10,
+                    engine_cost: Math.round(estCost * 100) / 100,
+                    note: "Engine time only. Rentals bill per minute from start to stop, so startup and idle time add to this.",
+                },
+            }
+            : {}),
+    };
+}