chesspal 0.0.1 → 0.2.0

package/dist/commands/ai-say.js

@@ -0,0 +1,58 @@
+import { z } from "zod";
+import { moods } from "../core/index.js";
+import { archivedName, talkLimits } from "../games/index.js";
+import { coachAgent } from "../host-files/index.js";
+import { gameFolder } from "../profiles/index.js";
+import { agentsLine, analystLine, coachOnEnd, reviewedLine, withAnalyst } from "./agents.js";
+import { newGameStep, nextStep, wordLines } from "./answer-lines.js";
+import { summaryOf } from "./game-summary.js";
+import { refuseOtherGame } from "./play-move.js";
+import { defineCommand } from "./registry.js";
+import { give, say, waitingWords } from "./say.js";
+/** The AI's words on the board page without a move, read only there, on the player's time: an answer, or a word it has to say (D-54, D-72). */
+export const aiSay = defineCommand({
+    name: "ai_say",
+    description: "Says a word on the board page without a move, once while the player is to move: an answer to what they wrote or to their draw offer, or "
+        + "something you have to say; when you are to move, speak in ai_move's comment. Between games, and before the first, it speaks freely: about the game just over, or to start another. "
+        + 'Example: ai_say {text: "Sure, I\'ll play faster."}.',
+    input: z.object({
+        text: z.string().trim().min(1, "write what you say").max(talkLimits.aiHelps, `write ${talkLimits.aiHelps} characters at most`).describe(`your words for the player, one or two short sentences, ${talkLimits.ai} characters at most (${talkLimits.aiHelps} with the helps on): pieces and moves in `
+            + `words ("your knight takes on f6"), a move you write with the pieces' figurines, as the tools show it (♞xf6+ for Nxf6+); your plans and threats only with the helps on; **two asterisks** put a word or two in bold on the page`),
+        mood: z.enum(moods).optional().describe("only after the game has ended: the face the board page keeps for its end"),
+    }),
+    run: ({ text, mood }, context) => {
+        // The player's words are read before the AI's line is saved: those written while it thought would fall before it, unread.
+        const folder = gameFolder(context.home());
+        refuseOtherGame(context, folder);
+        const waiting = waitingWords(context);
+        const current = say(folder, "ai", text, context.now(), mood);
+        const words = give(context, waiting);
+        if (!("game" in current)) {
+            return { words };
+        }
+        // The chat woken by the player's ending move on the page may have gone to its words without the coach (Priya).
+        return { game: withAnalyst(summaryOf(current, context.now(), archivedName(folder, current)), context, current), words, ...(coachOnEnd(context, folder, current) ? { coach: true } : {}) };
+    },
+    format: ({ game, words, coach }) => [
+        "Said on the board page, where the player reads it: don't write it again in the chat.",
+        ...wordLines(words),
+        ...(coach === true ? [agentsLine([coachAgent])] : []),
+        afterWords(game, words),
+    ].join("\n"),
+});
+/** The next step once the AI has spoken: the end of a game over has been told already, and the player's draw offer answered in words. */
+function afterWords(game, words) {
+    if (words.length === 0 && game?.end !== undefined) {
+        // The offer to go over the game, made in the AI's words, waits for the player's yes (D-89).
+        if (game.end.analyst === "done") {
+            return `Next: ${reviewedLine(game.end.archive)} When they want another game, ${newGameStep}`;
+        }
+        return game.end.analyst === "offer"
+            ? `Next: when the player wants this game gone over, ${analystLine(game.end.archive)} When they want another game, ${newGameStep}`
+            : `Next: when the player wants another game, ${newGameStep}`;
+    }
+    if (words.length === 0 && game?.drawOffer === "player" && game.turn !== game.ai) {
+        return "Next: accept the draw with end_game draw_agreed, or wait for the player's move.";
+    }
+    return nextStep(game, words);
+}

package/dist/commands/analyse-game.d.ts

@@ -0,0 +1,65 @@
+import { z } from "zod";
+import { type AiLevel, type MoveReview, type PieceLetter, type Side } from "../core/index.ts";
+/** A move as the analysis gives it: what happened, never how good it was (D-6). */
+interface MoveFacts {
+    /** The move, numbered: 12...Nxe5. */
+    move: string;
+    /** The piece it took. */
+    took?: PieceLetter;
+    /** The time it took and the time left after it, in milliseconds, where the record has the clock. */
+    spent?: number;
+    left?: number;
+    /** Who is ahead in material after it, when it changed: White +1. */
+    material?: string;
+    /** After it, the pieces at risk of either side when they changed from the line before ("none" once no piece is), and the mates the side to move has; none once the board ends the game. */
+    atRisk?: string;
+    mates?: readonly string[];
+    /** The first move the opening book does not know. */
+    outOfBook?: true;
+    drawOffer?: true;
+    /** In a game played here, what the AI said with its move, and the plan it wrote. */
+    said?: string;
+    plan?: string;
+    /** The badge and note the AI gave it with annotate_game (D-69). */
+    review?: MoveReview;
+    /** Who is ahead after it, as the AI estimated it (D-90). */
+    lead?: string;
+}
+/** A game as the analysis gives it. */
+interface Analysis {
+    /** How to analyse, the first time in a chat (D-68). */
+    instructions?: string;
+    /** The player's language, for the analyst's agent, which talks with no one (D-89). */
+    speech?: string;
+    white: string;
+    black: string;
+    /** In a game played here: the side the AI played, and its level. */
+    ai?: Side;
+    level?: AiLevel;
+    /** In a game played elsewhere: the side whose name is the player's profile's. */
+    player?: Side;
+    date?: string;
+    timeControl?: string;
+    result?: string;
+    termination?: string;
+    opening?: string;
+    /** Whether the game stayed in the opening book to its last move. */
+    inBook?: true;
+    /** The last move the opening book knows, the end of the moves with the book's badge. */
+    bookTo?: string;
+    /** The game's name in the archive, a game brought as a PGN too. */
+    name?: string;
+    /** In a game from a position: that position, and what is at risk and the mates in one there. */
+    start?: Omit<MoveFacts, "move"> & {
+        fen: string;
+    };
+    moves: MoveFacts[];
+    /** The AI's word on the whole game, from annotate_game. */
+    review?: string;
+}
+/** A game over move by move, for the analyst (D-68): the current one, one of the archive or kept to study, or one the player brings as a PGN, kept to study. */
+export declare const analyseGame: import("./registry.ts").Command<z.ZodObject<{
+    game: z.ZodOptional<z.ZodString>;
+    pgn: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>, Analysis>;
+export {};

package/dist/commands/analyse-game.js

@@ -0,0 +1,265 @@
+// The analyst's tool (D-21, D-68): a game over, move by move in one call, facts only and never a judgment, with the analyst's instructions once in a chat.
+import { z } from "zod";
+import { clockOfComment, clockText, closingOf, Game, gameReviewOf, isReviewed, leadOf, leadText, levelOf, materialOf, readPgn, reviewed, reviewOf, timeControlOfTag, timeControlText, withGameReview, withLead, } from "../core/index.js";
+import { isGameName, keepToStudy, lastChatStart, planOf, rewriteGame, startAnalysis } from "../games/index.js";
+import { analystAgent, instructions } from "../host-files/index.js";
+import { activeProfile, gameFolder } from "../profiles/index.js";
+import { bookOpening, bookReaches } from "./opening-book.js";
+import { defineCommand } from "./registry.js";
+import { speechLine, speechOf } from "./speech.js";
+import { gameToStudy, knownTag, moveNumbers, namedGame, noGameGoingOn } from "./study.js";
+import { balanceText, colourName, riskLine } from "./view.js";
+// The analyst's instructions, read at the first analysis.
+let analystText;
+/** A game over move by move, for the analyst (D-68): the current one, one of the archive or kept to study, or one the player brings as a PGN, kept to study. */
+export const analyseGame = defineCommand({
+    name: "analyse_game",
+    description: "Gives a game that is over move by move, to comment it with the player: each move with what it took and the time it took, the material "
+        + "when it changes, the pieces at risk and the mates in one after it, where the game left the opening book, and your comments and plans. Facts "
+        + "only: the judgment is yours. Without game or pgn, the game just over, or else the last one played; game: a name as past_games or study_games "
+        + "writes it; pgn: a game the player brings from elsewhere, kept to study in the profile. Never while a game goes on. The first time in a chat "
+        + "it also says how to analyse. annotate_game then keeps your badges and notes for the board page. Example: analyse_game {}.",
+    input: z.object({
+        game: z.string().optional().describe("a game's name, as past_games, study_games or analyse_game writes it"),
+        pgn: z.string().optional().describe("a game played elsewhere, in PGN: its tags and its moves, with their [%clk] and a review exported from the board page if it has them; other comments and evals can go"),
+    }),
+    sharedWith: [analystAgent],
+    run: ({ game, pgn }, context) => {
+        if (game !== undefined && pgn !== undefined) {
+            throw new Error("Give game or pgn, not both: game names a game of the archive, pgn brings one played elsewhere.");
+        }
+        // A game's name given as pgn, as an AI often gives it, is that game (Priya).
+        const named = pgn !== undefined && isGameName(pgn) ? pgn.trim() : game;
+        const studied = pgn === undefined || named !== game ? gameToStudy(context, named) : importedGame(context, pgn);
+        // One analyst a game: the chat goes over the review there is (Stefano).
+        if (context.agent === analystAgent && isReviewed(studied.record)) {
+            throw new Error("Stop now: this game has its review already. End with one line for the AI that started you: go over that review with the player.");
+        }
+        const analysis = analysisOf(studied, activeProfile(context.home()).name);
+        if (studied.name !== undefined) {
+            markBook(context, { record: studied.record, name: studied.name }, analysis.moves);
+            startAnalysis(gameFolder(context.home()), studied.name, context.now());
+        }
+        // The analyst's agent has its instructions in its own file, and the player's language in its prompt or, when Chesspal knows it, here (D-89).
+        if (context.agent === analystAgent) {
+            const speech = speechOf(gameFolder(context.home()), context.language);
+            return speech === undefined ? analysis : { ...analysis, speech: speechLine(speech) };
+        }
+        const told = analystInstructions(context);
+        return told === undefined ? analysis : { instructions: told, ...analysis };
+    },
+    format: (analysis) => [
+        ...(analysis.instructions === undefined ? [] : [analysis.instructions, ""]),
+        ...(analysis.speech === undefined ? [] : [analysis.speech]),
+        ...analysisHead(analysis),
+        ...analysis.moves.map(moveLine),
+    ].join("\n"),
+});
+/** A game the player brings as a PGN, checked move by move and kept to study with its clock and Chesspal's own review: no other comment, no engine's evaluation (D-6). */
+function importedGame(context, pgn) {
+    noGameGoingOn(context);
+    if (/\.pgn\s*$/i.test(pgn)) {
+        throw new Error(`"${pgn.trim()}" is a file's name, not a game: pgn takes a game's text, its tags and its moves. A game played here or kept to study goes in game, by `
+            + "its name, such as games/2026-11-02-153012.pgn.");
+    }
+    const records = readPgn(pgn);
+    if (records.length !== 1) {
+        throw new Error(records.length === 0 ? "The PGN holds no game: give it whole, its tags and its moves." : `The PGN holds ${records.length} games: give one at a time.`);
+    }
+    const [{ tags, moves }] = records;
+    // A game analysed here and exported comes back with its review: Chesspal's own marks stay, as the clock; any other comment goes.
+    const brought = {
+        tags,
+        moves: moves.map(({ san, comment }) => {
+            const clock = /\[%clk [^\]]*\]/.exec(comment ?? "")?.[0];
+            const move = clock === undefined ? { san } : { san, comment: clock };
+            const review = reviewOf(comment);
+            const lead = leadOf(comment);
+            const kept = review === undefined ? move : reviewed(move, review);
+            return lead === undefined ? kept : withLead(kept, lead);
+        }),
+    };
+    const summary = gameReviewOf(records[0]);
+    const closing = closingOf(records[0]);
+    const record = summary === undefined && closing === undefined
+        ? brought
+        : withGameReview(brought, { ...(summary === undefined ? {} : { summary }), ...(closing === undefined ? {} : { closing }) });
+    // A game brought again is the one already kept, with the review written on it since.
+    return namedGame(context, keepToStudy(gameFolder(context.home()), record, context.now()));
+}
+/**
+ * The opening book's moves marked as such in the game kept (D-69): a fact, not a judgment, so Chesspal puts the badge itself on each move from the start to the
+ * last one the book knows, where the AI gave none; a game from another position has none.
+ */
+function markBook(context, { record, name }, moves) {
+    const inBook = bookPliesOfFacts(record, moves);
+    const unmarked = record.moves.slice(0, inBook).some((move) => reviewOf(move.comment)?.badge === undefined);
+    if (!unmarked) {
+        return;
+    }
+    const marked = record.moves.map((move, ply) => {
+        const review = reviewOf(move.comment);
+        return ply < inBook && review?.badge === undefined ? reviewed(move, { ...review, badge: "book" }) : move;
+    });
+    rewriteGame(gameFolder(context.home()), name, { ...record, moves: marked });
+}
+/** How many plies from the start the opening book knows, as opening-book's bookPlies counts them, read from the facts already found: none from another position. */
+function bookPliesOfFacts(record, moves) {
+    const firstOut = moves.findIndex((move) => move.outOfBook);
+    return record.tags.FEN !== undefined ? 0 : firstOut >= 0 ? firstOut : moves.length;
+}
+function analysisOf({ record, name }, playerName) {
+    const { tags } = record;
+    const ai = sideNamed(record, "AI");
+    const control = timeControlOfTag(tags.TimeControl ?? "");
+    const { start, moves, outcome } = movesOf(record, ai);
+    // The board's end before the tags': a record may say what the board does not.
+    const ended = outcome.over ? { result: outcome.result, termination: outcome.ending } : tags.Result !== undefined && tags.Result !== "*" ? { result: tags.Result, termination: tags.Termination } : undefined;
+    const opening = bookOpening(record);
+    return {
+        white: tags.White ?? "?",
+        black: tags.Black ?? "?",
+        ai,
+        level: ai === undefined ? undefined : levelOf(record),
+        player: ai === undefined && playerName !== undefined ? sideNamed(record, playerName) : undefined,
+        date: knownTag(tags.Date),
+        timeControl: control === undefined ? knownTag(tags.TimeControl) : timeControlText(control),
+        result: ended?.result,
+        termination: ended?.termination,
+        opening: opening === undefined ? undefined : `${opening.eco} ${opening.name}`,
+        inBook: opening !== undefined && !moves.some((move) => move.outOfBook) ? true : undefined,
+        bookTo: opening === undefined ? undefined : moves[bookPliesOfFacts(record, moves) - 1]?.move,
+        review: [gameReviewOf(record), closingOf(record)].filter((word) => word !== undefined).join(" ") || undefined,
+        name,
+        start: tags.FEN === undefined ? undefined : { fen: tags.FEN, ...start },
+        moves,
+    };
+}
+/** The facts of every move, from a replay of the game: the facts after each move are those before the next. */
+function movesOf(record, ai) {
+    const numbers = moveNumbers(record);
+    const game = new Game({ tags: record.tags, moves: [] });
+    const increment = timeControlOfTag(record.tags.TimeControl ?? "")?.increment;
+    // The time each side had left after its last move: the first move of each side spends no time it can tell, as the sites start their clocks apart.
+    const left = {};
+    let inBook = record.tags.FEN === undefined && bookReaches(game.position.fen);
+    let before = game.facts;
+    let balance = materialOf(game.position.fen).balance;
+    const start = { atRisk: riskLine(before), mates: matesOf(before) };
+    // What was at risk on the line before: a move tells it only when it changed.
+    let risk = start.atRisk;
+    const moves = record.moves.map(({ san, comment }, ply) => {
+        const side = game.position.turn;
+        const played = game.playRecorded(san);
+        if (!played.played) {
+            throw new Error(`The game's move ${numbers[ply]}${san} cannot be played: ${played.message} Fix the game's PGN.`);
+        }
+        const outOfBook = inBook && !bookReaches(game.position.fen);
+        inBook &&= !outOfBook;
+        const facts = game.facts;
+        const over = game.outcome.over;
+        const now = materialOf(game.position.fen).balance;
+        const clock = clockOfComment(comment ?? "");
+        const previous = left[side];
+        const risks = riskLine(facts);
+        const move = {
+            move: `${numbers[ply]}${san}`,
+            took: before.pieces.find((piece) => piece.square === played.move.to)?.piece ?? (san.includes("x") ? "P" : undefined),
+            spent: clock === undefined || previous === undefined || increment === undefined ? undefined : Math.max(0, previous - clock + increment),
+            left: clock,
+            material: now === balance ? undefined : balanceText(now),
+            atRisk: over || risks === risk ? undefined : (risks ?? "none"),
+            mates: over ? undefined : matesOf(facts),
+            outOfBook: outOfBook ? true : undefined,
+            drawOffer: comment?.includes("(=)") === true ? true : undefined,
+            said: side === ai ? saidIn(comment) : undefined,
+            review: reviewOf(comment),
+            plan: side === ai ? planOf(comment) : undefined,
+            lead: estimateOf(comment),
+        };
+        if (clock !== undefined) {
+            left[side] = clock;
+        }
+        before = facts;
+        balance = now;
+        risk = risks;
+        return move;
+    });
+    return { start, moves, outcome: game.outcome };
+}
+/** The head of the analysis: who played, when and how fast, how it ended, the opening, and the game's name for look and position. */
+function analysisHead(analysis) {
+    const { ai, level, player } = analysis;
+    const named = (side) => `${side === "white" ? analysis.white : analysis.black}${side === player ? " (the player)" : ""}`;
+    const players = ai === undefined
+        ? `White: ${named("white")}; Black: ${named("black")}.`
+        : `You played ${colourName(ai)} at the ${level} level, the player ${colourName(ai === "white" ? "black" : "white")}.`;
+    const when = [analysis.date, analysis.timeControl === undefined ? undefined : `time control ${analysis.timeControl}`].filter((part) => part !== undefined).join(", ");
+    const count = Math.ceil(analysis.moves.length / 2);
+    const result = analysis.result === undefined ? "unknown" : `${analysis.result}${analysis.termination === undefined ? "" : ` (${analysis.termination})`}`;
+    const book = analysis.bookTo === undefined ? "" : analysis.inBook ? ", in the book to the end" : `, in the book to ${analysis.bookTo}`;
+    const badged = analysis.bookTo === undefined || analysis.name === undefined ? "" : ": those moves have the book badge, unless you give another";
+    const opening = analysis.opening === undefined ? [] : [`Opening: ${analysis.opening}${book}${badged}`];
+    const name = analysis.name === undefined ? 'Look and position take a move alone, such as move "12..."' : `Look and position take it as game "${analysis.name}"`;
+    const start = analysis.start === undefined ? [] : [moveLine({ ...analysis.start, move: `Start, ${analysis.start.fen}` })];
+    const head = `${players}${when === "" ? "" : ` ${when[0].toUpperCase()}${when.slice(1)}.`} Result: ${result}, after ${count} ${count === 1 ? "move" : "moves"}.`;
+    const review = analysis.review === undefined ? [] : [`Your review: ${analysis.review}`];
+    return [head, ...opening, ...review, `${name}.`, ...start];
+}
+/** 12...Nxe5: took P; spent 0:12, 4:32 left; material White +1; at risk: undefended Black Nf6; mate in one: Qh7#; out of book; you said "…"; your plan: …; ahead -1.5 */
+function moveLine(move) {
+    const left = move.left === undefined ? undefined : `${clockText(move.left)} left`;
+    const parts = [
+        move.took === undefined ? undefined : `took ${move.took}`,
+        move.spent === undefined ? left : `spent ${clockText(move.spent)}, ${left}`,
+        move.material === undefined ? undefined : `material ${move.material}`,
+        move.atRisk === undefined ? undefined : `at risk: ${move.atRisk}`,
+        move.mates === undefined ? undefined : `mate in one: ${move.mates.join(" ")}`,
+        move.outOfBook ? "out of book" : undefined,
+        move.drawOffer ? "offers a draw" : undefined,
+        move.said === undefined ? undefined : `you said "${move.said}"`,
+        move.plan === undefined ? undefined : `your plan: ${move.plan}`,
+        // The book's badge alone is Chesspal's, not the AI's word: the line says the move left the book where it did.
+        move.review === undefined || (move.review.badge === "book" && move.review.note === undefined) ? undefined : reviewLine(move.review),
+        move.lead === undefined ? undefined : `ahead ${move.lead}`,
+    ].filter((part) => part !== undefined);
+    return parts.length === 0 ? move.move : `${move.move}: ${parts.join("; ")}`;
+}
+/**
+ * The analyst's instructions, the first time in a chat where the MCP server keeps what it told: again in a chat cleared or summarized, since its start
+ * keys them (D-57); never on the command line, where no analyst reads.
+ */
+function analystInstructions(context) {
+    const key = `analyst ${lastChatStart(context.folder)?.at ?? ""}`;
+    if (context.told === undefined || context.told.has(key)) {
+        return undefined;
+    }
+    context.told.add(key);
+    analystText ??= `${instructions("analyst")}\n${instructions("analysis")}`;
+    return analystText;
+}
+/** Who is ahead after a move, as the AI estimated it with annotate_game or the coach during the game (D-90). */
+function estimateOf(comment) {
+    const lead = leadOf(comment);
+    return lead === undefined ? undefined : leadText(lead);
+}
+/** The mates in one the side to move has; none when it has none. */
+function matesOf(facts) {
+    const mates = facts.checks.filter((check) => check.endsWith("#"));
+    return mates.length === 0 ? undefined : mates;
+}
+/** The side a name plays, by the White and Black tags, whatever its case; none when neither is that name. */
+function sideNamed({ tags }, name) {
+    const same = (tag) => tag?.trim().toLowerCase() === name.trim().toLowerCase();
+    return same(tags.White) ? "white" : same(tags.Black) ? "black" : undefined;
+}
+/** The words of a move's comment, without the commands PGN hides in it ([%clk], [%plan]) and the draw offer. */
+function saidIn(comment) {
+    const words = (comment ?? "").replace(/\[%[^\]]*\]/g, "").replace("(=)", "").replace(/\s+/g, " ").trim();
+    return words === "" ? undefined : words;
+}
+/** What the AI kept on a move with annotate_game: you marked blunder: "note", or you noted "note". */
+function reviewLine({ badge, note }) {
+    const quoted = note === undefined ? "" : `"${note}"`;
+    return badge === undefined ? `you noted ${quoted}` : `you marked ${badge}${quoted === "" ? "" : `: ${quoted}`}`;
+}

package/dist/commands/annotate-game.d.ts

@@ -0,0 +1,39 @@
+import { z } from "zod";
+/** What the review kept: the game's name, how many moves it marked, and whether it holds a word on the whole game. */
+interface Annotated {
+    game: string;
+    marked: number;
+    summary: boolean;
+    closing: boolean;
+    /** The opening book's moves still without a note of the AI's, as analyse_game numbers them. */
+    bookUnnoted: string[];
+    /** How many moves took who is ahead after them, and those still without it, as analyse_game numbers them (D-90). */
+    estimated: number;
+    unestimated: string[];
+}
+/** The AI's badges and notes on a game over, and its word on the whole game, written into the game's PGN (D-69). */
+export declare const annotateGame: import("./registry.ts").Command<z.ZodObject<{
+    game: z.ZodOptional<z.ZodString>;
+    notes: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        move: z.ZodString;
+        badge: z.ZodOptional<z.ZodEnum<{
+            brilliant: "brilliant";
+            great: "great";
+            best: "best";
+            excellent: "excellent";
+            good: "good";
+            book: "book";
+            inaccuracy: "inaccuracy";
+            mistake: "mistake";
+            miss: "miss";
+            blunder: "blunder";
+        }>>;
+        note: z.ZodOptional<z.ZodString>;
+        arrows: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        squares: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    }, z.core.$strip>>>;
+    ahead: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodNumber, z.ZodString]>>>;
+    summary: z.ZodOptional<z.ZodString>;
+    closing: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>, Annotated>;
+export {};

package/dist/commands/annotate-game.js

@@ -0,0 +1,131 @@
+// The AI's review of a game over (D-69): a badge on each move that matters, as chess.com marks them, with a note when it needs one, and its word on the
+// whole game, kept in the game's PGN for the board page. The judgment is the AI's alone: Chesspal gives no criteria (D-6, D-43).
+import { z } from "zod";
+import { annotatorOf, badges, Game, leadOf, reviewed, reviewOf, withAnnotator, withGameReview, withLead } from "../core/index.js";
+import { gameInAnalysis, rewriteGame, startAnalysis } from "../games/index.js";
+import { analystAgent } from "../host-files/index.js";
+import { gameFolder } from "../profiles/index.js";
+import { arrowsInput, drawingsOf, noteInput, squaresInput } from "./drawings.js";
+import { leadFrom, leadInput } from "./lead-input.js";
+import { defineCommand } from "./registry.js";
+import { moveIndex, moveNumbers, namedGame, noGameGoingOn } from "./study.js";
+const summaryLimit = 1500;
+const closingLimit = 400;
+// How many moves still without who is ahead the answer names; the rest it counts.
+const unestimatedShown = 10;
+/** The AI's badges and notes on a game over, and its word on the whole game, written into the game's PGN (D-69). */
+export const annotateGame = defineCommand({
+    name: "annotate_game",
+    description: "Keeps your review of a game that is over for the board page: on each move that matters a badge, as chess.com has them, with a short note "
+        + "when it needs one, or a note alone on a move worth a word without a badge; your word on the whole game; and a last short word on how it ended, "
+        + "its win or loss; and who is ahead after every move as ahead, for the page's bar and chart. The judgment is yours: mark the moves you would point out, not every move. A note can draw arrows and colour squares on the board to show what it says. The opening book's moves have their book badge already: give each a short note too, what it is for, in the player's words; without one the page shows the opening's name from the book, in English. A move marked again takes its new badge and note. Notes in the player's language and in words, as in the chat; **two asterisks** put the few words that matter in bold, a square or a file too (**g7**, the **h** pawn). Without game, the game analyse_game gave last. Never "
+        + 'while a game goes on. Example: annotate_game {notes: [{move: "12...", badge: "blunder", note: "leaves the queen to the knight"}], ahead: {"1.": 0.3, "1...": 0.2, "12...": 3.5, "13.": "#4"}, '
+        + 'summary: "…", closing: "…"}.',
+    input: z.object({
+        game: z.string().optional().describe("the game's name, as analyse_game writes it; without it, the game analysed last"),
+        notes: z.array(z.object({
+            move: z.string().describe("the move, as analyse_game numbers it: 12. for White's, 12... for Black's"),
+            badge: z.enum(badges).optional(),
+            note: noteInput.optional().describe("why, in a few sentences, with the better move when there was one"),
+            arrows: arrowsInput,
+            squares: squaresInput,
+        })).optional().describe("the moves that matter, each with its badge, its note, or both"),
+        ahead: z.record(z.string(), leadInput).optional().describe("who is ahead after each move, by the move as analyse_game numbers it: pawns from White's side as chess.com shows it, 1.5 for White, -3 for Black, 0 for "
+            + 'even, or a mate you see in moves of the side that mates, "#3" for White\'s, "#-3" for Black\'s; every move, in one call or a few; a move given again '
+            + "takes its new figure"),
+        summary: z.string().max(summaryLimit).optional().describe("your word on the whole game: a short paragraph, with a few points as lines starting with - if it helps; the moves have their own notes"),
+        closing: z.string().max(closingLimit).optional().describe("your last word on how the game ended, its win or loss, in a sentence or two: the page shows it at the end"),
+    }),
+    sharedWith: [analystAgent],
+    run: async ({ game, notes = [], ahead = {}, summary, closing }, context) => {
+        noGameGoingOn(context);
+        const estimates = Object.entries(ahead);
+        if (notes.length === 0 && estimates.length === 0 && summary === undefined && closing === undefined) {
+            throw new Error("Give notes on the moves that matter, who is ahead after each move as ahead, your word on the whole game as summary, your last word on the ending as "
+                + "closing, or all of them. Nothing changed.");
+        }
+        // Who reviews it, before the game is read: no wait between reading and writing it, in which the coach's judgment or another review written meanwhile
+        // would be lost (Federico).
+        const caller = await context.caller?.();
+        const studied = game === undefined ? gameAnalysed(context) : namedGame(context, game);
+        // Every move is checked before the game is written: all or nothing.
+        const moves = [...studied.record.moves];
+        for (const { move, badge, note, arrows = [], squares = [] } of notes) {
+            if (badge === undefined && note === undefined) {
+                throw new Error(`Give ${move} a badge, a note, or both: arrows and squares go with them. Nothing changed.`);
+            }
+            const index = indexIn(studied.record, move, "notes");
+            // A note alone on a move of the book keeps its book badge: a fact Chesspal put there, not the AI's judgment.
+            const kept = badge ?? (reviewOf(moves[index].comment)?.badge === "book" ? "book" : undefined);
+            moves[index] = reviewed(moves[index], { ...(kept === undefined ? {} : { badge: kept }), ...(note === undefined ? {} : { note }), ...drawingsOf(arrows, squares) });
+        }
+        for (const [move, lead] of estimates) {
+            const index = indexIn(studied.record, move, "ahead");
+            moves[index] = withLead(moves[index], leadFrom(lead));
+        }
+        // Who reviewed it, as far as the host says it for certain (D-81): on the command line, or by a host that names no model over one that did, as it was.
+        const kept = caller === undefined || (caller.hostOnly === true && annotatorOf(studied.record) !== undefined);
+        const marked = { ...(kept ? studied.record : withAnnotator(studied.record, caller)), moves };
+        rewriteGame(gameFolder(context.home()), studied.name, summary === undefined && closing === undefined ? marked : withGameReview(marked, { ...(summary === undefined ? {} : { summary }), ...(closing === undefined ? {} : { closing }) }));
+        startAnalysis(gameFolder(context.home()), studied.name, context.now());
+        const numbers = moveNumbers(marked);
+        const bookUnnoted = moves.flatMap((move, index) => {
+            const review = reviewOf(move.comment);
+            return review?.badge === "book" && review.note === undefined ? [numbers[index]] : [];
+        });
+        return {
+            game: studied.name,
+            marked: notes.length,
+            summary: summary !== undefined,
+            closing: closing !== undefined,
+            bookUnnoted,
+            estimated: estimates.length,
+            // Asked every time, of an older review too: an analyst whose instructions predate the estimates learns of them here.
+            unestimated: unestimatedMoves(marked, numbers),
+        };
+    },
+    format: ({ game, marked, summary, closing, bookUnnoted, estimated, unestimated }) => {
+        const kept = [
+            marked === 0 ? undefined : `${marked} ${marked === 1 ? "move" : "moves"} marked`,
+            estimated === 0 ? undefined : `who is ahead after ${estimated} ${estimated === 1 ? "move" : "moves"}`,
+            summary ? "your word on the game" : undefined,
+            closing ? "your last word" : undefined,
+        ].filter((part) => part !== undefined);
+        const book = bookUnnoted.length === 0
+            ? []
+            : [
+                `${bookUnnoted.length === 1 ? "The book's move" : "The book's moves"} ${bookUnnoted.join(" ")} ${bookUnnoted.length === 1 ? "has" : "have"} no note of yours: `
+                    + "the page shows the book's English name there. A short note on each, in the player's words, takes its place.",
+            ];
+        const shown = unestimated.slice(0, unestimatedShown).join(" ");
+        const more = unestimated.length > unestimatedShown ? ` and ${unestimated.length - unestimatedShown} more` : "";
+        const ahead = unestimated.length === 0 ? [] : [`Who is ahead is still missing after ${shown}${more}: give it with ahead, for the page's bar and chart.`];
+        return [`Kept in ${game}: ${[kept.slice(0, -1).join(", "), kept.at(-1)].filter((part) => part !== "").join(" and ")}. The board page shows them.`, ...book, ...ahead].join("\n");
+    },
+});
+/** The moves without who is ahead after them, as analyse_game numbers them: all but the last when the board ended the game there, which says it. */
+function unestimatedMoves(record, numbers) {
+    const ended = new Game(record).outcome.over;
+    return record.moves.flatMap((move, index) => leadOf(move.comment) !== undefined || (ended && index === record.moves.length - 1) ? [] : [numbers[index]]);
+}
+/** A move given in notes or in ahead, as analyse_game numbers it, refused with where it was given (Priya). */
+function indexIn(record, move, field) {
+    try {
+        return moveIndex(record, move);
+    }
+    catch (error) {
+        const message = error.message;
+        throw new Error(`In ${field}, ${message.charAt(0).toLowerCase()}${message.slice(1)} Nothing changed.`);
+    }
+}
+function gameAnalysed(context) {
+    // The game in analysis follows the board page, which the player may turn to another game while an agent works (Federico).
+    if (context.agent !== undefined) {
+        throw new Error("Give the game's name as game, as analyse_game named it: the board page may have opened another game since. Nothing changed.");
+    }
+    const analysis = gameInAnalysis(gameFolder(context.home()));
+    if (analysis === undefined) {
+        throw new Error("No game is in analysis: call analyse_game first, or give the game's name as game. Nothing changed.");
+    }
+    return namedGame(context, analysis.game);
+}

package/dist/commands/answer-lines.d.ts

@@ -0,0 +1,28 @@
+import { type Side } from "../core/index.ts";
+import { type GameSummary, type LastMove, type MovePlayed } from "./game-summary.ts";
+/** Where the game stands: the AI's position to decide on, with its last move unless the lines before named it; the player's turn; or how it ended. */
+export declare function positionLines(game: GameSummary, withLastMove?: boolean): string[];
+/** The head of a view: where the game stands, the last move unless the lines before named it, the opening, the material as the player sees it, and the FEN. */
+export declare function headLines(game: GameSummary, withLastMove?: boolean): string[];
+/** The last move, as the player is shown it, with its squares: 4.♞g5 (f3-g5). */
+export declare function lastMoveText({ move, from, to }: LastMove): string;
+/**
+ * A numbered move as the player is shown it, with the pieces' figurines (D-86): the form alone, without the SAN, which the AI copied into its message
+ * (Priya, test of D-86): 4.Ng5 is 4.♞g5.
+ */
+export declare function shownMove(move: string): string;
+/** The lines after a move, which the line before named: its note, where the game stands, a warning. closingLines end them. */
+export declare function moveLines({ note, game, warning }: MovePlayed): string[];
+/** The last lines of a tool's answer: the player's words from the board page, then the next step, which stays the last line. */
+export declare function closingLines(game: GameSummary | undefined, words?: readonly string[], pageClosed?: boolean): string[];
+/** The player's words from the board page, one line each: lines they broke are joined, so no line of theirs reads as one of Chesspal's. */
+export declare function wordLines(words: readonly string[]): string[];
+/**
+ * What the AI does next: the one line every host reads, even where the server's instructions are not shown. Words of the player's ask for an answer. With the
+ * board page open in no browser, a new game starts there, never in the chat.
+ */
+export declare function nextStep(game: GameSummary | undefined, words?: readonly string[], pageClosed?: boolean): string;
+/** How a new game starts: the player chooses it in the board page's window, which new_game without choices opens (D-85). */
+export declare const newGameStep = "call new_game without choices: it opens the board page's New game window, where the player chooses the colour, the clock and the level.";
+/** Who plays what, from the AI's side. */
+export declare function sidesLine(ai: Side): string;