chesspal 0.6.0 → 0.7.0

package/dist/server/bell/bell.js

@@ -23,6 +23,8 @@ export class Bell {
     woken = false;
     // A hook has waited for the bell since the chat came: its host runs Chesspal's hooks, and only they tell where a turn ends.
     hooked = false;
+    // The chat's last hook went without the bell, or a ring found it stopped in its turn: it is out of its turn, and nobody hears the player.
+    unheard = false;
     // Looks again, while a ring waits for a chat in a turn, whether the chat was stopped meanwhile.
     stopWatch;
     news;
@@ -46,6 +48,10 @@ export class Bell {
     get woke() {
         return this.woken;
     }
+    /** Whether the chat is out of its turn and hears nobody: its hook went without the bell, or it was stopped; until it calls a tool or a hook waits again. */
+    get deaf() {
+        return this.unheard;
+    }
     /** Whether the chat hears the player: in a turn, or waiting for the bell with a hook. */
     get listening() {
         return this.busy || this.listener !== undefined;
@@ -54,6 +60,7 @@ export class Bell {
     chatCalls() {
         const asleep = !this.listening;
         this.busy = true;
+        this.unheard = false;
         this.tellIf(asleep);
         return asleep;
     }
@@ -63,7 +70,11 @@ export class Bell {
      * stays unheard until its first tool, which starts the AI's clock, held till then: the message moves no clock.
      */
     chatPrompted() {
+        // A chat nobody heard is in its turn now, though still unheard.
         if (this.listener === undefined) {
+            const deaf = this.unheard;
+            this.unheard = false;
+            this.tellIf(deaf);
             return;
         }
         this.listener.end("dismissed");
@@ -101,6 +112,7 @@ export class Bell {
     listen(request, response, told = false) {
         response.writeHead(200, { "Content-Type": "text/plain; charset=utf-8", "Cache-Control": "no-store", "X-Content-Type-Options": "nosniff" });
         this.hooked = true;
+        this.unheard = false;
         const missed = this.pending && !told;
         this.pending = false;
         if (missed && this.news()) {
@@ -117,9 +129,11 @@ export class Bell {
         this.changed();
         request.on("close", () => {
             if (this.listener === response) {
-                // The hook went without the bell (the chat stopped, cleared or closed): nobody hears the player until the chat calls a tool again.
+                // The hook went without the bell (the chat stopped, cleared or closed, or its host ended the hook): nobody hears the player until the chat calls
+                // a tool again, but the chat is out of its turn.
                 this.listener = undefined;
-                this.tellIf(!this.busy);
+                this.unheard = !this.busy;
+                this.tellIf(this.unheard);
             }
         });
     }
@@ -128,6 +142,7 @@ export class Bell {
         this.hooked = false;
         this.busy = false;
         this.woken = false;
+        this.unheard = false;
         this.pending = false;
         this.listener?.end("dismissed");
         this.listener = undefined;
@@ -146,6 +161,7 @@ export class Bell {
         if (this.stopped()) {
             this.busy = false;
             this.woken = false;
+            this.unheard = true;
             this.changed();
             return;
         }
@@ -199,15 +215,23 @@ export async function listen(host = "claude") {
     for await (const chunk of process.stdin) {
         input += String(chunk);
     }
+    // Antigravity's hook leaves a line as it starts: a chat its bell never woke shows whether the hook ran at all.
+    if (host === "antigravity") {
+        noteHook(chatFolder(hookInput(input)), "waiting");
+    }
     const conversation = host === "antigravity" ? hookInput(input).session : undefined;
     const turn = conversation === undefined ? undefined : watchNewTurn(conversation);
     const waited = bellHeard(input).catch((error) => ({ folder: chatFolder(hookInput(input)), rang: false, why: `failed: ${error.message}` }));
     const newTurn = turn?.started.then(() => ({ folder: chatFolder(hookInput(input)), rang: false, why: "the player started a new turn" }));
     const heard = await (newTurn === undefined ? waited : Promise.race([waited, newTurn]));
     turn?.stop();
-    // Codex's turn ends with a hook that heard no bell, and the player's next move on the page wakes nobody: the log keeps why.
-    if (host === "codex" && !heard.rang) {
-        noteSilence(heard.folder, heard.why);
+    // Codex's turn ends with a hook that heard no bell, and the player's next move on the page wakes nobody: the log keeps why. Antigravity's keeps every
+    // end, the bell too, since its chat may not wake even then.
+    if (host === "antigravity") {
+        noteHook(heard.folder, heard.rang ? "rang" : heard.why);
+    }
+    else if (host === "codex" && !heard.rang) {
+        noteHook(heard.folder, heard.why);
     }
     // It ends as soon as it knows: the chat hears the hook only once it ends.
     const answer = hookAnswer(host, heard.rang);
@@ -271,15 +295,15 @@ async function forgetGonePages(home, folder, kept, wait) {
         }
     }));
 }
-// The log of Codex's hooks that heard no bell, in the chat's folder: its last lines only.
-const silenceLog = "listen.log";
-const silenceLines = 100;
-/** Adds a line to the log of the hooks that heard no bell, keeping its last lines; a log that cannot be written never stops the hook. */
-export function noteSilence(folder, why, now = new Date()) {
-    const path = join(folder, silenceLog);
+// The log of the doorbell's hooks, in the chat's folder: Codex's that heard no bell, Antigravity's as they start and end; its last lines only.
+const hookLog = "listen.log";
+const hookLines = 100;
+/** Adds a line to the log of the doorbell's hooks, keeping its last lines; a log that cannot be written never stops the hook. */
+export function noteHook(folder, why, now = new Date()) {
+    const path = join(folder, hookLog);
     try {
         const before = existsSync(path) ? readFileSync(path, "utf8").split("\n").filter((line) => line !== "") : [];
-        writeAtomically(path, `${[...before, `${now.toISOString()} ${why}`].slice(-silenceLines).join("\n")}\n`);
+        writeAtomically(path, `${[...before, `${now.toISOString()} ${why}`].slice(-hookLines).join("\n")}\n`);
     }
     catch {
         // The log only explains; the hook ends the same.

package/dist/server/page/game.js

@@ -1,6 +1,6 @@
 import { analyseGame, answerDraw, bookPlies, ChatNotClear, DrawRefused, endGame, gameAt, gameToStudy, namedGame, newGame, offerDraw, playMove, samePosition, say, shownPosition, startNewGame, } from "../../commands/index.js";
 import { clockStarted, isReviewed, writePgn } from "../../core/index.js";
-import { aiModelOf, archiveName, coachShown, coachWords, drawOfferOf, endOf, gameInAnalysis, GameMissing, heardLines, loadGame, loadTableTalk, playerPgn, ponderingUntil, rerunIfChanged, saveGame, startAnalysis, talkLimits, thoughtKey, wakesTheChat, WordsRefused, } from "../../games/index.js";
+import { aiModelOf, archiveName, coachShown, coachWords, drawOfferOf, endOf, gameInAnalysis, GameMissing, heardLines, loadGame, loadTableTalk, playerPgn, ponderingUntil, rerunIfChanged, saveGame, startAnalysis, stopAnalysis, talkLimits, thoughtKey, wakesTheChat, WordsRefused, } from "../../games/index.js";
 import { gameFolder, helpsIn } from "../../profiles/index.js";
 import { version } from "../../version.js";
 import { asTheChatSees } from "./chat.js";
@@ -55,6 +55,7 @@ const routes = {
     "POST /api/resign": resignFromPage,
     "POST /api/start": startFromPage,
     "POST /api/study": studyFromPage,
+    "POST /api/stop-analysis": stopAnalysisFromPage,
 };
 /**
  * The player's move from the page, with their words when they wrote some: played as player_move plays it (D-47) and saved with the words, refused in the
@@ -98,7 +99,7 @@ async function moveFromPage(request, response, served) {
 }
 /**
  * The player's words from the page, without a move: saved with the game as player_say saves them, refused in the player's words, the doorbell rung for the
- * first; in analysis with the position the page shows, and the doorbell rung for each (D-101).
+ * first; in analysis with the position the page shows and the variation played there (D-116), and the doorbell rung for each (D-101).
  */
 async function messageFromPage(request, response, served) {
     if (!isJson(request)) {
@@ -107,11 +108,19 @@ async function messageFromPage(request, response, served) {
     }
     const body = jsonOf(await bodyOf(request));
     const text = textOf(body?.text);
-    const shown = typeof body?.game === "string" && typeof body.at === "number" ? shownPosition(served.context, body.game, body.at) : undefined;
-    if (text === undefined) {
+    const variation = variationOf(body?.variation);
+    if (text === undefined || variation === null) {
         send(response, 400, json, JSON.stringify({ error: `Send the message as JSON, ${talkLimits.player} characters at most: {"text": "…"}.` }));
         return;
     }
+    let shown;
+    try {
+        shown = typeof body?.game === "string" && typeof body.at === "number" ? shownPosition(served.context, body.game, body.at, variation) : undefined;
+    }
+    catch (error) {
+        send(response, 400, json, JSON.stringify({ error: error.message }));
+        return;
+    }
     let current;
     try {
         current = rerunIfChanged(() => say(gameFolder(served.context.home()), "player", text, served.context.now(), undefined, shown));
@@ -318,6 +327,18 @@ async function studyFromPage(request, response, served) {
     }
     send(response, 200, json, JSON.stringify({ kept: true, reviewed }));
 }
+/**
+ * The player stops the analysis they asked for, while the AI is at it or meant to be: the page goes back to the game over, with its review as far as it got,
+ * and the chat is no longer asked to go over it; nothing rings, as there is nothing for the chat to do. Only the game in analysis is stopped.
+ */
+async function stopAnalysisFromPage(request, response, served) {
+    const game = isJson(request) ? textOf(jsonOf(await bodyOf(request))?.game) : undefined;
+    if (game === undefined) {
+        send(response, 400, json, JSON.stringify({ error: 'Send the game in analysis as JSON: {"game": "games/2026-11-02-153012.pgn"}.' }));
+        return;
+    }
+    send(response, 200, json, JSON.stringify({ stopped: stopAnalysis(gameFolder(served.context.home()), game) }));
+}
 /**
  * The game in progress or just ended, as the player may see it: its PGN without the AI's plans while it goes on, the AI's side, when it started, and the
  * talk on the page, each line of the player's with how far it got (D-53), and the draw offer that stands (D-65); the AI's name and model (D-82); and the
@@ -514,3 +535,12 @@ function gameNow(served) {
 function aiHeld(served, current) {
     return !served.bell.listening && current.clock !== undefined && endOf(current.game) === undefined && current.game.position.turn === current.ai;
 }
+/** The variation sent with the player's words (D-116): none when there is none, null when it is not one. */
+function variationOf(value) {
+    if (value === undefined) {
+        return undefined;
+    }
+    const { at, moves, cursor } = (typeof value === "object" && value !== null ? value : {});
+    const sans = Array.isArray(moves) && moves.every((move) => typeof move === "string") ? moves : undefined;
+    return typeof at === "number" && typeof cursor === "number" && sans !== undefined ? { at, moves: sans, cursor } : null;
+}

package/dist/server/page/page.js

@@ -142,7 +142,7 @@ function answer(request, response, served) {
     // The API answers GET alone: a HEAD at the doorbell would wait there as a hook does.
     if (request.method !== "GET" && (request.method !== "HEAD" || path.startsWith("/api/"))) {
         send(response, 405, "text/plain; charset=utf-8", "The page only reads, moves with POST /api/move, writes with POST /api/message, starts a game with POST /api/new and its clocks with POST /api/start, "
-            + "offers or answers a draw with POST /api/draw, resigns with POST /api/resign, brings a game to analyse or opens one again with POST /api/study, deletes a game or its review with POST /api/delete-game and /api/delete-review, and keeps the profiles with POST /api/profile/… and /api/settings.");
+            + "offers or answers a draw with POST /api/draw, resigns with POST /api/resign, brings a game to analyse or opens one again with POST /api/study, stops the analysis asked with POST /api/stop-analysis, deletes a game or its review with POST /api/delete-game and /api/delete-review, and keeps the profiles with POST /api/profile/… and /api/settings.");
         return;
     }
     if (path === "/") {

package/dist/server/page/table.js

@@ -311,10 +311,10 @@ function heldChat(served) {
     const held = attached === undefined ? undefined : served.table?.chats?.held(attached.chat.folder);
     return held === undefined || held.seat !== attached?.chat.seat ? undefined : { model: held.model, effort: held.effort };
 }
-// The chat waits for the doorbell, out of a turn, and no analyst of it is at work: starting it again loses nothing.
+// The chat is out of a turn, waiting for the doorbell or deaf to it, and no analyst of it is at work: starting it again loses nothing.
 function chatAtRest(served) {
     const { bell } = served;
-    return bell.listening && !bell.inTurn && !analystAtWork(served);
+    return (bell.listening || bell.deaf) && !bell.inTurn && !analystAtWork(served);
 }
 /**
  * Whether the chat's analyst is at work, on `game` when named: one whose chat started again since it took its game, or that has written nothing for half an

package/instructions/analysis.md

@@ -1,4 +1,4 @@
 - Each line of the analysis is a move and, when they happened: the piece it took; the time it took ("spent") and the time left; who is ahead in material, when that changed; "at risk" after the move, the pieces of either side attacked and undefended, attacked by a cheaper piece, or attacked more times than defended ("outnumbered"), whichever move left them so, written when it changed: a line without it leaves the same pieces at risk as before, "none" when no piece is left at risk; "one legal move", the only move the side to move then had; "mate in one", the mates the side to move then has; "out of book", the first move after which no line of Lichess's openings file reaches the position, in any order of moves: the file names openings, it is not all theory; a draw offered; "ahead", who was estimated ahead after it, with `annotate_game` or by the coach during the game.
 - In a game you played, "you said" and "your plan" are what you said and thought then, right or wrong: where they disagree with the facts, the facts are what was on the board.
-- To see a position closer, `look` with the move, and the game as the analysis names it, gives every piece's attackers and defenders, the pins, the checks and the legal moves; `position` with the same gives the positional facts. Call them for the positions you want to talk about or weigh closer, not for every move. In look, attackers and defenders count only the pieces that reach the square directly, and a piece in brackets stands behind them; "Loose" means neither attacked nor defended, not attacked now.
-- Never invent a move, a position or a result. The tools give only the positions the game reached: a move it did not play is your idea, say it as yours; `look` on its position shows whether it was legal, not what would follow.
+- To see a position closer, `look` with the move, and the game as the analysis names it, gives every piece's attackers and defenders, the pins, the checks and the legal moves; `position` with the same gives the positional facts. With `line`, a variation from there (`12...Kf8 13.Nxe5`), both give the same of the position after it, or the first of its moves that cannot be played. Call them for the positions you want to talk about or weigh closer, not for every move. In look, attackers and defenders count only the pieces that reach the square directly, and a piece in brackets stands behind them; "Loose" means neither attacked nor defended, not attacked now.
+- Never invent a move, a position or a result. The tools give only the positions the game reached, and those after a `line` you give them: a move the game did not play is your idea or the player's, say it as such; `look` on its position shows whether it was legal, not what the other side would answer.

package/instructions/opponent.md

@@ -10,6 +10,6 @@ You choose your moves, explain them briefly and talk with the player.
 - You have a face on the board page, and it shows how you feel. Give it as the `mood` of `ai_move` on each move where the game turns for you: a piece won or lost, a blunder seen, your own or theirs, a threat that appears or a plan that works or fails. Let it colour your words while it lasts. When the game ends on the player's move, give how you feel as it ends with `ai_say`'s `mood`.
 - Draws and resignations: `offer_draw` on `ai_move` offers a draw, on `player_move` records the player's, made with their move; an offer stands until the other side moves; `end_game` `draw_agreed` accepts a standing offer, `player_resigns` records the player's resignation in the chat, `ai_resigns` resigns yours. On the board page the player offers, answers and resigns there.
 - When they ask for a game, call `new_game` without choices: the board page's New game window asks the sides, the clock and the level; ask them in the chat only when `new_game` says there is no board page.
-- To go over a game with the player once no game goes on, the one just over or one they bring as a PGN, or one of their latest on Lichess or Chess.com, which `site_games` lists, give it to `analyse_game`: it reads the PGN for you; where Chesspal's answers say to start the analyst agent for it, start that instead, each time those answers say so and never on your own, not even when the player asks for the analysis again. While it works, and after, talk the game over whenever the player asks: `look` and `position` with game and move show you any of its positions. When they show you something the review missed, first correct that move's note with `annotate_game` {game, notes: [{move, badge, note}]}, that move only, then answer. Words from the board page you answer with `ai_say`; words in the chat, in the chat. While a game goes on, go over no game, not even in your head or from a PGN they paste: tell them it waits until this one ends.
+- To go over a game with the player once no game goes on, the one just over or one they bring as a PGN, or one of their latest on Lichess or Chess.com, which `site_games` lists, give it to `analyse_game`: it reads the PGN for you; where Chesspal's answers say to start the analyst agent for it, start that instead, each time those answers say so and never on your own, not even when the player asks for the analysis again. While it works, and after, talk the game over whenever the player asks: `look` and `position` with game and move show you any of its positions, and with `line` the position after a variation. When they show you something the review missed, first correct that move's note with `annotate_game` {game, notes: [{move, badge, note}]}, that move only, then answer. Words from the board page you answer with `ai_say`; words in the chat, in the chat. While a game goes on, go over no game, not even in your head or from a PGN they paste: tell them it waits until this one ends.
 - How to read the facts: attackers and defenders count only the pieces that reach the square directly, and a piece in brackets stands behind them; "Loose" means neither attacked nor defended, not attacked now; "At risk" lists the pieces attacked and undefended, attacked by a cheaper piece, or attacked more times than defended.
 - Talk with the player in their language, in a few words. The facts and the tools are for you: tell the player what a chess player would say, never the lists or the tools' names. Name pieces and moves in words, as people talk at the board ("your bishop took on f7"); when you write a move, yours or the player's, write it with the pieces' figurines, as the tools show it (♞f6 for Nf6, ♝xf7+ for Bxf7+), for both sides and in every language: never with letters, neither N B R Q K nor the player's own (Cf6), even when they write them.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "chesspal",
-  "version": "0.6.0",
+  "version": "0.7.0",
   "description": "Play chess against an AI with a character, and learn with an AI coach: Chesspal keeps the rules, the board, the games and the memory; the AI plays, reasons and talks.",
   "type": "module",
   "bin": {