chesspal 0.1.0 → 0.2.0

package/dist/commands/analyse-game.js

@@ -1,15 +1,16 @@
 // 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 { readFileSync } from "node:fs";
 import { z } from "zod";
-import { clockOfComment, clockText, closingOf, Game, gameReviewOf, levelOf, materialOf, readPgn, reviewed, reviewOf, timeControlOfTag, timeControlText, withGameReview, } from "../core/index.js";
-import { keepToStudy, lastChatStart, planOf, rewriteGame, startAnalysis } from "../games/index.js";
+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 instructions;
+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",
@@ -22,20 +23,37 @@ export const analyseGame = defineCommand({
         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.");
         }
-        const studied = pgn === undefined ? gameToStudy(context, game) : importedGame(context, pgn);
+        // 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, ""]), ...headLines(analysis), ...analysis.moves.map(moveLine)].join("\n"),
+    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) {
@@ -49,14 +67,16 @@ function importedGame(context, pgn) {
         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 (T-106): Chesspal's own marks stay, as the clock; any other comment goes.
+    // 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);
-            return review === undefined ? move : reviewed(move, review);
+            const lead = leadOf(comment);
+            const kept = review === undefined ? move : reviewed(move, review);
+            return lead === undefined ? kept : withLead(kept, lead);
         }),
     };
     const summary = gameReviewOf(records[0]);
@@ -72,7 +92,7 @@ function importedGame(context, pgn) {
  * 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 = bookPlies(record, moves);
+    const inBook = bookPliesOfFacts(record, moves);
     const unmarked = record.moves.slice(0, inBook).some((move) => reviewOf(move.comment)?.badge === undefined);
     if (!unmarked) {
         return;
@@ -83,8 +103,8 @@ function markBook(context, { record, name }, moves) {
     });
     rewriteGame(gameFolder(context.home()), name, { ...record, moves: marked });
 }
-/** How many plies from the start the opening book knows: to the move before the first out of it; none from another position. */
-function bookPlies(record, moves) {
+/** 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;
 }
@@ -108,7 +128,7 @@ function analysisOf({ record, name }, playerName) {
         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[bookPlies(record, moves) - 1]?.move,
+        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 },
@@ -155,6 +175,7 @@ function movesOf(record, ai) {
             said: side === ai ? saidIn(comment) : undefined,
             review: reviewOf(comment),
             plan: side === ai ? planOf(comment) : undefined,
+            lead: estimateOf(comment),
         };
         if (clock !== undefined) {
             left[side] = clock;
@@ -167,7 +188,7 @@ function movesOf(record, ai) {
     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 headLines(analysis) {
+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
@@ -185,7 +206,7 @@ function headLines(analysis) {
     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: … */
+/** 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 = [
@@ -200,6 +221,7 @@ function moveLine(move) {
         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("; ")}`;
 }
@@ -213,8 +235,13 @@ function analystInstructions(context) {
         return undefined;
     }
     context.told.add(key);
-    instructions ??= readFileSync(new URL("../../instructions/analyst.md", import.meta.url), "utf8").trim();
-    return instructions;
+    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) {

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

@@ -7,6 +7,9 @@ interface Annotated {
     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<{
@@ -29,6 +32,7 @@ export declare const annotateGame: import("./registry.ts").Command<z.ZodObject<{
         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>;

package/dist/commands/annotate-game.js

@@ -1,21 +1,26 @@
 // 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, reviewed, reviewOf, withAnnotator, withGameReview } from "../core/index.js";
+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. 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"}], summary: "…", closing: "…"}.',
+        + "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({
@@ -25,14 +30,23 @@ export const annotateGame = defineCommand({
             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"),
     }),
-    run: async ({ game, notes = [], summary, closing }, context) => {
+    sharedWith: [analystAgent],
+    run: async ({ game, notes = [], ahead = {}, summary, closing }, context) => {
         noGameGoingOn(context);
-        if (notes.length === 0 && summary === undefined && closing === undefined) {
-            throw new Error("Give notes on the moves that matter, your word on the whole game as summary, your last word on the ending as closing, or all of them. Nothing changed.");
+        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];
@@ -40,13 +54,16 @@ export const annotateGame = defineCommand({
             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 = moveIndex(studied.record, move);
+            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 caller = await context.caller?.();
         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 }) }));
@@ -56,20 +73,56 @@ export const annotateGame = defineCommand({
             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 };
+        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 }) => {
-        const kept = [marked === 0 ? undefined : `${marked} ${marked === 1 ? "move" : "moves"} marked`, summary ? "your word on the game" : undefined, closing ? "your last word" : undefined].filter((part) => part !== undefined);
+    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.",
             ];
-        return [`Kept in ${game}: ${[kept.slice(0, -1).join(", "), kept.at(-1)].filter((part) => part !== "").join(" and ")}. The board page shows them.`, ...book].join("\n");
+        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.");

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;

package/dist/commands/answer-lines.js

@@ -0,0 +1,144 @@
+// The lines an AI reads in a tool's answer about the current game: where it stands, the move just played, the player's words and what to do next.
+import { figurinesOf, materialOf, sees } from "../core/index.js";
+import { talkLimits } from "../games/index.js";
+import { onQuickModel } from "../host-files/index.js";
+import { analystLine, reviewedLine } from "./agents.js";
+import { clockLine } from "./clock.js";
+import { endText } from "./game-summary.js";
+import { boardView, colourName, compactView, materialText } from "./view.js";
+/** 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 function positionLines(game, withLastMove = true) {
+    if (game.end !== undefined || game.turn !== game.ai) {
+        return [whereLine(game), ...offerLines(game), ...clockLines(game), ...moodLines(game)];
+    }
+    return [
+        ...headLines(game, withLastMove),
+        ...(game.facts === undefined ? [] : (sees(game.level, "tactics") ? compactView : boardView)(game.facts, game.turn)),
+        ...(game.book === undefined ? [] : [`Book moves, most named lines first: ${game.book.join(", ")}`]),
+        ...(game.plan === undefined ? [] : [`Plan: ${game.plan}`]),
+        ...(game.thought === undefined ? [] : [thoughtLine(game.thought, game.level)]),
+        ...moodLines(game),
+        ...(game.helps === "coached" ? [`${helpsLine} ${coachLine}`] : game.helps === "on" ? [helpsLine] : game.helps === "off now" ? [helpsOffLine] : []),
+    ];
+}
+/** The helps turned on: the AI may teach as the analyst does (D-62, D-78), never playing for the player. */
+const helpsLine = "Helps on: the player wants to learn. Tell your intentions, never their best move; draw arrows and squares to show what you say, and write up to "
+    + `${talkLimits.aiHelps} characters.`;
+/**
+ * Where a coach runs, a coach, not the AI, judges the player's moves, and the AI knows it, so that it neither makes up what the coach said nor looks for it
+ * (D-88, Priya); where none runs, nobody judges them before the analyst (D-80).
+ */
+const coachLine = "A coach, not you, judges their moves and gives them hints on the board page; you don't see what it writes.";
+/** The helps turned off during a game: what the AI said and drew before no longer holds (Priya, round of D-78). */
+const helpsOffLine = `Helps off now: play as at a tournament again: no intentions or arrows, comments of ${talkLimits.ai} characters at most.`;
+/** 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 function headLines(game, withLastMove = true) {
+    return [
+        whereLine(game),
+        ...offerLines(game),
+        ...(withLastMove && game.lastMove !== undefined ? [`Last move: ${lastMoveText(game.lastMove)}.`] : []),
+        ...(game.opening === undefined ? [] : [`Opening: ${game.opening}`]),
+        `Material: ${materialText(materialOf(game.fen))}`,
+        ...clockLines(game),
+        `FEN: ${game.fen}`,
+    ];
+}
+/** The last move, as the player is shown it, with its squares: 4.♞g5 (f3-g5). */
+export function lastMoveText({ move, from, to }) {
+    return `${shownMove(move)} (${from}-${to})`;
+}
+/**
+ * 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 function shownMove(move) {
+    const [, number = "", san = move] = /^(\d+\.+)(.+)$/.exec(move) ?? [];
+    return `${number}${figurinesOf(san)}`;
+}
+/** The lines after a move, which the line before named: its note, where the game stands, a warning. closingLines end them. */
+export function moveLines({ note, game, warning }) {
+    return [...(note === undefined ? [] : [`Note: ${note}`]), ...positionLines(game, false), ...(warning === undefined ? [] : [warning])];
+}
+/** 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 function closingLines(game, words = [], pageClosed = false) {
+    return [...wordLines(words), nextStep(game, words, pageClosed)];
+}
+/** 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 function wordLines(words) {
+    return words.map((text) => `Player wrote on the board page: «${text.replace(/\s+/g, " ")}»`);
+}
+/**
+ * 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 function nextStep(game, words = [], pageClosed = false) {
+    const step = pageClosed ? closedPageGameStep : newGameStep;
+    if (game === undefined) {
+        return words.length === 0 ? `Next: when the player wants a game, ${step}` : `Next: answer the player with ai_say. When they want a game, ${step}`;
+    }
+    if (game.end !== undefined) {
+        const analysis = game.end.analyst === "offer"
+            ? ` To go over it, on their yes, ${analystLine(game.end.archive)}`
+            : game.end.analyst === "done"
+                ? ` ${reviewedLine(game.end.archive)}`
+                : "";
+        return words.length === 0
+            ? "Next: tell the player how the game ended, with ai_say and how you feel as its mood if they play on the board page; then offer them, in words, another game or "
+                + `to go over this one${analysis === "" ? " (analyse_game)." : `.${analysis}`} For another, ${step}`
+            : `Next: answer the player with ai_say.${analysis} When they want another game, ${step}`;
+    }
+    if (game.turn === game.ai && game.clock?.waiting === true) {
+        return "Next: don't move yet: the player starts the game with Start on the board page, and the doorbell wakes you then. End your turn.";
+    }
+    if (game.turn === game.ai) {
+        return words.length === 0
+            ? "Next: choose your move, then call ai_move with it, your plan and any comment."
+            : "Next: choose your move, then call ai_move with it, your plan and a comment that answers the player.";
+    }
+    if (game.drawOffer === "player") {
+        return "Next: accept the draw with end_game draw_agreed, or answer with ai_say and wait for the player's move.";
+    }
+    return words.length === 0 ? "Next: wait for the player's move, then call player_move with it." : "Next: answer the player with ai_say, then wait for their move.";
+}
+/** How a new game starts: the player chooses it in the board page's window, which new_game without choices opens (D-85). */
+export 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.";
+// With the page open in no browser the window cannot open: the player opens the page and presses New game.
+const closedPageGameStep = "they start it on the board page with its New game button, where they choose the colour, the clock and the level: tell them so with "
+    + "the page's address, and never offer to set it up in the chat.";
+/** Who plays what, from the AI's side. */
+export function sidesLine(ai) {
+    return `you play ${colourName(ai)}, the player ${colourName(ai === "white" ? "black" : "white")}`;
+}
+/** The draw offer that stands, and how to answer it or what becomes of it (D-65). */
+function offerLines({ drawOffer, turn, ai }) {
+    if (drawOffer === "ai") {
+        return ["Your draw offer stands until the player moves; if they accept it in the chat, end_game draw_agreed ends the game."];
+    }
+    if (drawOffer === "player") {
+        return [turn === ai ? "The player offers a draw: end_game draw_agreed accepts it; your move declines it." : "The player offers a draw before their move; your next move declines it."];
+    }
+    return [];
+}
+/** What the AI thought on the player's time, saying by which model and that Chesspal checked only that it is legal: the facts do not cover every blunder (Anatolij). */
+function thoughtLine({ move, why }, level) {
+    return `Thought on their time ${onQuickModel(level) ? "by a quicker model" : "by your model"} (legal, not checked): ${move}, ${why}`;
+}
+/** The AI's mood while it lasts, and how long its face shows it (D-70). */
+function moodLines({ mood }) {
+    if (mood === undefined) {
+        return [];
+    }
+    const shown = mood.left === 0 ? "until your next move" : `for ${mood.left} more of your moves`;
+    return [`Your mood: ${mood.mood}, on your face ${shown}, then neutral by itself.`];
+}
+/** Who is to move, or how the game ended. */
+function clockLines(game) {
+    return game.clock === undefined ? [] : [clockLine(game.clock, game.ai)];
+}
+function whereLine(game) {
+    if (game.end !== undefined) {
+        const archived = game.end.archive === undefined ? "" : ` Archived in ${game.end.archive}.`;
+        return `Game over: ${endText(game.end)}.${archived}`;
+    }
+    return `${game.turn === game.ai ? "You" : "Player"} (${colourName(game.turn)}) to move, move ${game.moveNumber}.`;
+}

package/dist/commands/coach.d.ts

@@ -0,0 +1,45 @@
+import { z } from "zod";
+/** What coach answers: stop, the moves to work on, the words kept and what comes next, or still the player's move; with the game's key and the position. */
+type Coached = {
+    stop: "moved" | "waited" | "helps" | "started";
+} | {
+    start: string[];
+} | {
+    kept: Place;
+    then: "lead" | "wait" | "moved" | "over";
+    saved: string[];
+    hintLeft: boolean;
+} | {
+    waiting: Place;
+};
+/** The game, by its key, and the position in it the coach works on. */
+interface Place {
+    readonly game: string;
+    readonly position: number;
+}
+/**
+ * The coach (D-80, D-88), for the agent that judges the player's moves and gives them hints with the helps on: every fact, never the opponent's plan; its
+ * words go to the board page alone, never to the opponent. Its calls are not the chat's, and the server refuses them from the chat. Offered to Claude Code alone.
+ */
+export declare const coach: import("./registry.ts").Command<z.ZodObject<{
+    game: z.ZodOptional<z.ZodString>;
+    position: z.ZodOptional<z.ZodInt>;
+    ahead: z.ZodOptional<z.ZodUnion<readonly [z.ZodNumber, z.ZodString]>>;
+    badge: z.ZodOptional<z.ZodEnum<{
+        brilliant: "brilliant";
+        great: "great";
+        best: "best";
+        excellent: "excellent";
+        good: "good";
+        inaccuracy: "inaccuracy";
+        mistake: "mistake";
+        miss: "miss";
+        blunder: "blunder";
+    }>>;
+    note: z.ZodOptional<z.ZodString>;
+    hint: z.ZodOptional<z.ZodString>;
+    arrows: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    squares: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    done: z.ZodOptional<z.ZodBoolean>;
+}, z.core.$strip>, Coached>;
+export {};