chesspal 0.3.5 → 0.4.0

package/README.md

@@ -87,6 +87,7 @@ Chesspal works with any agent that can use Chesspal's tools (MCP) and the files
 - **To play in a folder of your own**, as with the Claude desktop app, type `chesspal init chess`, then open your agent in the folder `chess` and say hello: the AI answers with the link to the board page. Any name will do; your games are kept [elsewhere](#where-your-games-are).
 - **A move written in the chat** counts too: `e4`, `Nf3`, in the international notation (K Q R B N in every language), or in words.
 - **To update**, when a new version is out the table's page shows an arrow at the top: press it between games, and the table installs it and starts again, with its chat. By hand: close the AI's terminal, run `npm install -g chesspal` again, then `chesspal`. In a folder of your own, run `chesspal init` there too: it updates its own lines and keeps what you wrote there. In Codex, allow the hooks again when it says so.
+- **To uninstall**, run `chesspal icon --remove` first, which takes the icon off your desktop and menu, then `npm uninstall -g chesspal`. Your games stay [where they are](#where-your-games-are).
 
 ## Where your games are
 

package/dist/cli/cli.js

@@ -1,8 +1,7 @@
 #!/usr/bin/env node
-import { runCommandLine } from "./command-line.js";
 const args = process.argv.slice(2);
-// The table's own words (D-104): alone or open, its page; table, icon, play <host>. The host's: mcp, its server; listen, its doorbell; chat, how the chat
-// started. Everything else is a command.
+// The table's own words (D-104): alone or open, its page; table, icon (--remove), play <host>. The host's: mcp, its server; listen, its doorbell; chat, how the chat
+// started; prompt, the move the player wrote alone. Everything else is a command. Each loads only what it needs: prompt runs on every message of the chat.
 if (args.length === 0) {
     await openTableHere(true);
 }
@@ -16,7 +15,15 @@ else if (args.length === 1 && args[0] === "table") {
 else if (args.length === 1 && args[0] === "icon") {
     await putIconHere();
 }
-else if (args.length === 2 && args[0] === "play" && !args[1].startsWith("-")) {
+else if (args.length === 2 && args[0] === "icon" && args[1] === "--remove") {
+    const [{ defaultContext }, { iconsRemoved }] = await Promise.all([import("../commands/index.js"), import("./icon.js")]);
+    console.log(iconsRemoved(defaultContext()));
+}
+else if (args[0] === "play" && (args.length === 2 || (args.length === 4 && args[2] === "--home")) && !args[1].startsWith("-")) {
+    // The data folder of a table started with CHESSPAL_HOME, which a terminal the table opens may not pass on (Terminal.app): the chat and its server read it.
+    if (args[3] !== undefined) {
+        process.env.CHESSPAL_HOME = args[3];
+    }
     await playHere(args[1]);
 }
 else if (args.length === 1 && args[0] === "mcp") {
@@ -32,7 +39,12 @@ else if (args.length === 1 && args[0] === "chat") {
     const { recordChatStart } = await import("./chat-hook.js");
     await recordChatStart();
 }
+else if (args.length === 1 && args[0] === "prompt") {
+    const { answerPrompt } = await import("./prompt-hook.js");
+    await answerPrompt();
+}
 else {
+    const { runCommandLine } = await import("./command-line.js");
     const { output, exitCode } = await runCommandLine(args);
     if (exitCode === 0) {
         console.log(output);
@@ -106,3 +118,4 @@ async function serveTable() {
         process.exitCode = 1;
     }
 }
+export {};

package/dist/cli/command-line.js

@@ -3,17 +3,21 @@ import { parseArgs } from "node:util";
 import { baseType, commandLineFieldProblem, commands, defaultContext, inputProblems, isBoolean, isList, takesNumbers } from "../commands/index.js";
 import { rerunIfChanged } from "../games/index.js";
 import { version } from "../version.js";
-// The commands that exist only on the command line: cli.ts starts the table, opens its page, puts its icon, starts the server, the doorbell or the chat's
-// note, when one comes alone.
+// The commands that exist only on the command line: cli.ts starts the table, opens its page, puts its icon, starts the server, the doorbell, the chat's
+// note or the move written alone, when one comes alone.
 const mcpDescription = "Start the MCP server for an AI host. Through it the host uses these commands as tools; the host starts it, with no options.";
 const listenDescription = "Wait for the player's move on the board page and wake the chat. Claude Code starts it at the end of each turn, and Codex with --codex, as init sets them up.";
 const chatDescription = "Note how the chat started: new, cleared, resumed or compacted. Claude Code and Codex run it when a chat starts, as init sets them up.";
+const promptDescription = "Play the move the player wrote alone in the chat, before the AI reads it, and tell the AI the position. Claude Code runs it on each message, as init sets it up.";
 const tableDescription = "Serve the board page with no chat, until no browser has had it open for five minutes. `chesspal` alone starts it apart and opens the page.";
 const openDescription = "Open the board page as `chesspal` alone does, without asking about the icon: what the icon runs.";
-const iconDescription = "Put Chesspal's icon on the desktop and in the menu: it opens the board page as `chesspal` alone does, with no terminal.";
-const playDescription = "Play at the table in Claude Code or Codex, in this terminal: what the page's buttons open, with the model and effort chosen there; New game on the page starts the chat again, clean.";
+const iconDescription = "Put Chesspal's icon on the desktop and in the menu: it opens the board page as `chesspal` alone does, with no terminal. `chesspal icon --remove` takes it away.";
+const playDescription = "Start the AI in this terminal, in Claude Code or Codex, as the page's buttons do. It plays with the model and effort chosen on the page; New game there starts the chat again, clean.";
+// What init and the icon's removal are to a player, in the general help: the command's own help says the files.
+const initForPlayer = "Set up a folder of your own to play in, from Claude Code, Codex or the Claude desktop app.";
+const iconRemoveForPlayer = "Take Chesspal's icon away, before you uninstall it.";
 // Those of them that take no options, by name.
-const plainCommands = new Map([["mcp", mcpDescription], ["chat", chatDescription], ["table", tableDescription], ["open", openDescription], ["icon", iconDescription]]);
+const plainCommands = new Map([["mcp", mcpDescription], ["chat", chatDescription], ["prompt", promptDescription], ["table", tableDescription], ["open", openDescription], ["icon", iconDescription]]);
 /** The `chesspal` command line: finds the command, validates its input, runs it and renders the result. */
 export async function runCommandLine(argv, context = defaultContext(), list = commands) {
     const [commandName, ...args] = argv;
@@ -149,24 +153,30 @@ function checkRepeatedOptions(command, tokens, options) {
 function inputFields(command) {
     return Object.entries(command.input.shape);
 }
-/** The commands, each with the first sentence of its description. */
+/** The commands, each with the first sentence of its description: the player's first, then those of the AI and of whoever develops Chesspal. */
 function generalHelp(list) {
-    const width = Math.max("listen".length, ...list.map((command) => command.name.length));
+    const width = Math.max("icon --remove".length, ...list.map((command) => command.name.length));
     const line = (name, description) => `  ${name.padEnd(width)} ${firstSentence(description)}`;
+    const init = list.find((command) => command.name === "init");
     return [
         `chesspal ${version}`,
         "",
-        "Run `chesspal` alone to open the board page in your browser.",
+        "To play, type `chesspal` alone: the board opens in your browser, and from there you start the AI.",
         "",
-        "Commands:",
-        ...list.map((command) => line(command.name, command.description)),
+        "For the player:",
+        line("play", playDescription),
+        ...(init === undefined ? [] : [line(init.name, initForPlayer)]),
+        line("icon", iconDescription),
+        line("icon --remove", iconRemoveForPlayer),
+        "",
+        "For the AI, and for whoever develops Chesspal:",
+        ...list.filter((command) => command !== init).map((command) => line(command.name, command.description)),
         line("table", tableDescription),
         line("open", openDescription),
-        line("icon", iconDescription),
-        line("play", playDescription),
         line("mcp", mcpDescription),
         line("listen", listenDescription),
         line("chat", chatDescription),
+        line("prompt", promptDescription),
         "",
         "Run `chesspal <command> --help` for its options.",
     ].join("\n");

package/dist/cli/icon.d.ts

@@ -23,3 +23,5 @@ export declare function iconsMade(context: Context, places?: IconPlaces): Promis
     said: string;
     failed: boolean;
 }>;
+/** Takes the icon off the desktop and the menu, before Chesspal is uninstalled: what to tell the player. */
+export declare function iconsRemoved(context: Context): string;

package/dist/cli/icon.js

@@ -3,7 +3,7 @@
 import { createInterface } from "node:readline/promises";
 import { styleText } from "node:util";
 import { speaksItalian } from "../commands/index.js";
-import { iconAsked, iconCommand, iconToRemake, makeIcons, noteIconAsked, noteIconMade } from "../server/table/index.js";
+import { iconAsked, iconCommand, iconToRemake, makeIcons, noteIconAsked, noteIconMade, removeIcons } from "../server/table/index.js";
 /**
  * Asks once a machine, in a terminal on a screen, whether to put the icon on the desktop and in the menu, and puts it there on a yes: what to tell the
  * player, if anything. Once asked, an icon made by another Node or script is made again, without a word; a playtest's data folder is never asked about.
@@ -46,6 +46,12 @@ export async function iconsMade(context, places) {
         return { said: words.failed(error.message), failed: true };
     }
 }
+/** Takes the icon off the desktop and the menu, before Chesspal is uninstalled: what to tell the player. */
+export function iconsRemoved(context) {
+    const words = wordsFor(context);
+    const removed = removeIcons(context.home());
+    return removed.length === 0 ? words.noneRemoved : `${words.removed}\n${styleText("dim", removed.map((file) => `  ${file}`).join("\n"))}`;
+}
 function processTerminal() {
     return { input: process.stdin, output: process.stdout, env: process.env };
 }
@@ -68,6 +74,8 @@ function wordsFor(context) {
             made: `Fatto: Chesspal è sul desktop e ${where}.`,
             later: "Va bene, niente icona. Se la vuoi più avanti, scrivi chesspal icon.",
             failed: (reason) => `Chesspal non è riuscito a mettere l'icona (${reason}). Riprova con chesspal icon.`,
+            removed: `Fatto: l'icona di Chesspal non è più sul desktop né ${where}. Per togliere Chesspal: npm uninstall -g chesspal. Le tue partite restano dove sono.`,
+            noneRemoved: "Chesspal non ha trovato sue icone su questo computer.",
         };
     }
     const where = { windows: "your Start menu", mac: "Applications", linux: "your applications menu" }[system];
@@ -76,5 +84,7 @@ function wordsFor(context) {
         made: `Done: Chesspal is on your desktop and in ${where}.`,
         later: "All right, no icon. To add it later, type chesspal icon.",
         failed: (reason) => `Chesspal could not add its icon (${reason}). Try again with chesspal icon.`,
+        removed: `Done: Chesspal's icon is gone from your desktop and ${where}. To remove Chesspal: npm uninstall -g chesspal. Your games stay where they are.`,
+        noneRemoved: "Chesspal found no icon of its own on this computer.",
     };
 }

package/dist/cli/prompt-hook.d.ts

@@ -0,0 +1,17 @@
+import type { Context } from "../commands/index.ts";
+/**
+ * Reads the hook's input, tells the chat's page the chat is at work and, when the prompt is a move Chesspal plays, writes what the AI is told; it never
+ * blocks the prompt.
+ */
+export declare function answerPrompt(input?: NodeJS.ReadableStream, sent?: Date): Promise<void>;
+/**
+ * What the hook writes, the JSON Claude Code reads, when the prompt is one move and Chesspal played it; undefined, with nothing changed, for any other
+ * prompt or a move refused. `contextOf` gives what the move is played with, in the chat's folder; it then notes there the position shown to the chat.
+ */
+export declare function promptAnswer(input: string, contextOf: (hook: HookInput) => Promise<Context>): Promise<string | undefined>;
+/** What the hook reads of Claude Code's input: the prompt trimmed, the chat's session and the folder it runs in. */
+export interface HookInput {
+    prompt?: string;
+    session?: string;
+    cwd?: string;
+}

package/dist/cli/prompt-hook.js

@@ -0,0 +1,100 @@
+/**
+ * Reads the hook's input, tells the chat's page the chat is at work and, when the prompt is a move Chesspal plays, writes what the AI is told; it never
+ * blocks the prompt.
+ */
+export async function answerPrompt(input = process.stdin, sent = new Date()) {
+    try {
+        const text = await textOf(input);
+        const [answer] = await Promise.all([promptAnswer(text, (hook) => hookContext(hook, sent)), tellPage(hookInput(text))]);
+        if (answer !== undefined) {
+            process.stdout.write(`${answer}\n`);
+        }
+    }
+    catch (error) {
+        process.stderr.write(`Chesspal could not play the move written in the chat: ${String(error.message ?? error).replace(/\s+/g, " ")}\n`);
+    }
+}
+/**
+ * What the hook writes, the JSON Claude Code reads, when the prompt is one move and Chesspal played it; undefined, with nothing changed, for any other
+ * prompt or a move refused. `contextOf` gives what the move is played with, in the chat's folder; it then notes there the position shown to the chat.
+ */
+export async function promptAnswer(input, contextOf) {
+    const hook = hookInput(input);
+    if (hook.prompt === undefined || !moveShape.test(hook.prompt) || hook.session === undefined) {
+        return undefined;
+    }
+    const [context, { playMoveSentAlone }, { hostProcess, notePositionShown }] = await Promise.all([contextOf(hook), import("../commands/index.js"), import("../games/index.js")]);
+    let played;
+    try {
+        played = playMoveSentAlone(hook.prompt, context);
+    }
+    catch (error) {
+        // Chesspal's refusals end so: the game as it was, the AI reads the prompt and answers it.
+        if (error instanceof Error && error.message.endsWith("Nothing changed.")) {
+            return undefined;
+        }
+        throw error;
+    }
+    try {
+        const { position, stamp, given } = played;
+        const host = hostProcess();
+        notePositionShown(context.folder, {
+            session: hook.session,
+            ...(host === undefined ? {} : { process: host }),
+            ...(stamp === undefined ? {} : { stamp }),
+            ...position,
+            at: context.now().toISOString(),
+            given,
+        });
+    }
+    catch (error) {
+        // The move is played: the AI hears it all the same, and its server asks it for status before its own, which may give the words again.
+        process.stderr.write(`Chesspal could not note the position it showed the chat: ${error.message}\n`);
+    }
+    return JSON.stringify({ hookSpecificOutput: { hookEventName: "UserPromptSubmit", additionalContext: played.answer } });
+}
+// One move and nothing else, as player_move takes it: SAN with K, Q, R, B and N, small or as figurines, or with the letters of other languages that name
+// one piece (Cf3, Tf1, Dd1, e8=D), or as squares, or castling; a check or mate sign.
+const moveShape = /^(?:[KQRBNkqrbnCSAFLTDt♔-♟]?[a-h]?[1-8]?[-x:×–—−]?[a-h][1-8](?:=?[QRBNqrbnCSAFLTD])?|[0Oo]-[0Oo](?:-[0Oo])?)[+#]?$/u;
+/**
+ * Tells the chat's page that the prompt starts its turn: the doorbell lets the hook of the turn before go, and a new game asked on the page waits for
+ * the turn's end. A slash command or a shell line may start no turn, and so no Stop hook to end it: the page is not told.
+ */
+async function tellPage(hook) {
+    if (hook.prompt === undefined || /^[/!]/.test(hook.prompt)) {
+        return;
+    }
+    // A page not told leaves the doorbell as it was: the move, when the prompt is one, is played all the same.
+    await import("../server/ports/index.js").then(({ tellChatAtWork }) => tellChatAtWork(hook), () => false);
+}
+/** The context of the chat's folder: the data folder its server is given, the moment the player sent the move, and Claude Code, which runs this hook. */
+async function hookContext(hook, sent) {
+    const [{ defaultContext }, { chatFolder, serverHome }] = await Promise.all([import("../commands/index.js"), import("../server/ports/index.js")]);
+    const folder = chatFolder(hook);
+    const home = serverHome(folder);
+    // A playtest's data folder, which .mcp.json gives the server and not the hook.
+    if (home !== undefined) {
+        process.env.CHESSPAL_HOME = home;
+    }
+    return { ...defaultContext(), folder, now: () => sent, host: () => "claude-code" };
+}
+async function textOf(input) {
+    let text = "";
+    for await (const chunk of input) {
+        text += String(chunk);
+    }
+    return text;
+}
+function hookInput(text) {
+    try {
+        const { prompt, session_id: session, cwd } = JSON.parse(text);
+        return {
+            ...(typeof prompt === "string" ? { prompt: prompt.trim() } : {}),
+            ...(typeof session === "string" ? { session } : {}),
+            ...(typeof cwd === "string" ? { cwd } : {}),
+        };
+    }
+    catch {
+        return {};
+    }
+}

package/dist/commands/analysis/analyse.d.ts

@@ -2,14 +2,14 @@ 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. */
+    /** The move, numbered, with the pieces' figurines as the other tools write moves (D-86), since the analyst copies them into its notes: 12...♞xe5. */
     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. */
+    /** Who is ahead in material after it, when it changed: White +1 in pawns. */
     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;

package/dist/commands/analysis/analyse.js

@@ -5,7 +5,7 @@ import { gameInAnalysis, isGameName, keepToStudy, lastChatStart, planOf, rewrite
 import { analystAgent, instructionsFile } from "../../host-files/index.js";
 import { activeProfile, gameFolder } from "../../profiles/index.js";
 import { pointsAtSite, siteGameName, siteOfGameName } from "../../sites/index.js";
-import { analystOf, anotherAnalyst, balanceText, bookOpening, bookReaches, colourName, gameToStudy, knownTag, moveNumbers, namedGame, noGameGoingOn, riskLine, speechLine, speechOf, tacticsText } from "../answers/index.js";
+import { analystOf, anotherAnalyst, balanceText, bookOpening, bookPlace, bookPlies, colourName, gameToStudy, knownTag, moveNumbers, namedGame, noGameGoingOn, riskLine, shownMove, speechLine, speechOf, tacticsText, } from "../answers/index.js";
 import { playerLine, siteText } from "../profiles/index.js";
 import { defineCommand } from "../registry/index.js";
 import { profileSiteGames } from "./site-games.js";
@@ -49,7 +49,7 @@ export const analyseGame = defineCommand({
         }
         const analysis = analysisOf(studied, activeProfile(context.home()));
         if (studied.name !== undefined) {
-            markBook(context, { record: studied.record, name: studied.name }, analysis.moves);
+            markBook(context, { record: studied.record, name: studied.name });
             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);
@@ -148,8 +148,8 @@ async function siteGamePgn(context, name) {
  * 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);
+function markBook(context, { record, name }) {
+    const inBook = bookPlies(record);
     const unmarked = record.moves.slice(0, inBook).some((move) => reviewOf(move.comment)?.badge === undefined);
     if (!unmarked) {
         return;
@@ -160,11 +160,6 @@ function markBook(context, { record, name }, moves) {
     });
     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 }, profile) {
     const { tags } = record;
     const ai = sideNamed(record, "AI");
@@ -186,7 +181,7 @@ function analysisOf({ record, name }, profile) {
         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,
+        bookTo: opening === undefined ? undefined : moves[bookPlies(record) - 1]?.move,
         review: [gameReviewOf(record), closingOf(record)].filter((word) => word !== undefined).join(" ") || undefined,
         name,
         start: tags.FEN === undefined ? undefined : { fen: tags.FEN, ...start },
@@ -200,7 +195,8 @@ function movesOf(record, ai) {
     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);
+    // The first move no line of the book reaches is out of book (D-68); a game from another position has no book.
+    const leftBook = bookPlace(record)?.plies;
     let before = game.facts;
     let balance = materialOf(game.position.fen).balance;
     const start = { atRisk: riskLine(before), oneLegal: oneLegalMove(before), mates: matesOf(before), tactics: tacticsText(before, game.possibilities, true) };
@@ -212,8 +208,6 @@ function movesOf(record, ai) {
         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;
@@ -221,7 +215,7 @@ function movesOf(record, ai) {
         const previous = left[side];
         const risks = riskLine(facts);
         const move = {
-            move: `${numbers[ply]}${san}`,
+            move: shownMove(`${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,
@@ -230,7 +224,7 @@ function movesOf(record, ai) {
             oneLegal: over ? undefined : oneLegalMove(facts),
             mates: over ? undefined : matesOf(facts),
             tactics: over ? undefined : tacticsText(facts, game.possibilities, true),
-            outOfBook: outOfBook ? true : undefined,
+            outOfBook: ply === leftBook ? true : undefined,
             drawOffer: comment?.includes("(=)") === true ? true : undefined,
             said: side === ai ? saidIn(comment) : undefined,
             review: reviewOf(comment),
@@ -266,7 +260,7 @@ function analysisHead(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#; tactics: fork Nc7+ (Ke8 Ra8); out of book; you said "…"; your plan: …; ahead -1.5 */
+/** 12...♞xe5: took P; spent 0:12, 4:32 left; material White +1 in pawns; at risk: undefended Black Nf6; mate in one: Qh7#; tactics: fork Nc7+ (Ke8 Ra8); 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 = [

package/dist/commands/analysis/annotate.d.ts

@@ -14,6 +14,14 @@ interface Annotated {
     left: string[];
     /** The chat corrected a note of a review that already has its word on the game. */
     summaryStands: boolean;
+    /** Where this call wrote a move with another language's letters (5., your summary), and the first such move: the page shows them as plain text (D-87). */
+    lettered: {
+        where: string[];
+        first?: {
+            written: string;
+            san: 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/registry.ts").Command<z.ZodObject<{

package/dist/commands/analysis/annotate.js

@@ -1,7 +1,7 @@
 // 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, gameReviewOf, leadOf, reviewed, reviewOf, withAnnotator, withGameReview, withLead } from "../../core/index.js";
+import { annotatorOf, badges, figurinesOf, foreignMovesIn, Game, gameReviewOf, 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";
@@ -105,9 +105,10 @@ export const annotateGame = defineCommand({
             left: [...corrected],
             // A correction after the review's word on the game: that word may now say otherwise (Priya).
             summaryStands: correction && gameReviewOf(studied.record) !== undefined,
+            lettered: letteredIn([...notes.map(({ move, note }) => [move, note]), ["your summary", summary], ["your last word", closing]]),
         };
     },
-    format: ({ game, marked, summary, closing, bookUnnoted, estimated, unestimated, left, summaryStands }) => {
+    format: ({ game, marked, summary, closing, bookUnnoted, estimated, unestimated, left, summaryStands, lettered }) => {
         const kept = [
             marked === 0 ? undefined : `${marked} ${marked === 1 ? "move" : "moves"} marked`,
             estimated === 0 ? undefined : `who is ahead after ${estimated} ${estimated === 1 ? "move" : "moves"}`,
@@ -129,9 +130,24 @@ export const annotateGame = defineCommand({
             : [`${left.join(" ")} ${one ? "keeps the note" : "keep the notes"} the AI wrote with the player: leave ${one ? "it" : "them"}, and don't contradict ${one ? "it" : "them"} in your summary${summary ? "; if this one does, give it again" : ""}.`];
         const head = kept.length === 0 ? `Nothing new kept in ${game}.` : `Kept in ${game}: ${[kept.slice(0, -1).join(", "), kept.at(-1)].filter((part) => part !== "").join(" and ")}. The board page shows them.`;
         const stands = summaryStands ? ["The review's word on the game stays as written: if it says otherwise, give summary again."] : [];
-        return [head, ...stands, ...corrected, ...book, ...ahead].join("\n");
+        const single = lettered.where.length === 1;
+        const letters = lettered.first === undefined
+            ? []
+            : [
+                `${lettered.where.join(", ")} ${single ? "writes" : "write"} moves with another language's letters, which the page shows as plain text: give ${single ? "it" : "them"} `
+                    + `again with the figurines (${figurinesOf(lettered.first.san)} for ${lettered.first.written}).`,
+            ];
+        return [head, ...stands, ...corrected, ...letters, ...book, ...ahead].join("\n");
     },
 });
+/** Where the texts of a call write a move with another language's letters, by the move or the part they were given for, and the first such move. */
+function letteredIn(texts) {
+    const found = texts.flatMap(([where, text]) => {
+        const [first] = foreignMovesIn(text ?? "");
+        return first === undefined ? [] : [{ where, first }];
+    });
+    return { where: [...new Set(found.map(({ where }) => where))], ...(found[0] === undefined ? {} : { first: found[0].first }) };
+}
 /** 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, over) {
     return record.moves.flatMap((move, index) => leadOf(move.comment) !== undefined || (over && index === record.moves.length - 1) ? [] : [numbers[index]]);

package/dist/commands/answers/agents.d.ts

@@ -8,8 +8,16 @@ export declare function analystRuns(context: Context): boolean;
  * its end: once reviewed, or taken by the agent, the chat goes over that review and doesn't start the agent for it (Stefano).
  */
 export declare function withAnalyst(summary: GameSummary, context: Context, over?: CurrentGame): GameSummary;
-/** How the chat has a game over gone over by the analyst agent, on the player's yes or for the game they brought (D-89). */
-export declare function analystLine(game?: string): string;
+/**
+ * How the chat has a game over gone over by the analyst agent, on the player's yes or for the game they brought (D-89); in Codex with spawn_agent by name,
+ * since a chat there called analyse_game itself instead (Priya).
+ */
+export declare function analystLine(game?: string, codex?: boolean): string;
+/**
+ * The analyst's line for the chat that looks at the game in analysis with no review and no analyst at it, as after «Delete the analysis», which rings no
+ * doorbell (Priya): once a change of the analysis, where the server keeps what it told.
+ */
+export declare function analystOnView(context: Context, game: string | undefined): string | undefined;
 /** How the chat goes over a game the analyst agent has reviewed, or is reviewing: from that review, never with another agent (Stefano). */
 export declare function reviewedLine(game?: string): string;
 /** Whether a coach judges the player's moves when the helps are on: in Claude Code or Codex, with its agent in the player's folder (D-80, D-88, D-98). */
@@ -17,15 +25,15 @@ export declare function coachRuns(context: Context): boolean;
 /** Whether one of Chesspal's agents runs beside this chat: in a host that starts agents, with its file in the player's folder. */
 export declare function agentRuns(context: Context, agent: string): boolean;
 /**
- * Whether to start the coach after the player's own move has ended the game on the board, with the helps on: it judges that move too (D-88). Told again
- * until it starts, since a chat woken by the page may lose the line on its way to its words (Priya).
+ * Whether to start the coach once a move has ended the game on the board, with the helps on: it judges the player's last move, their own that ended it too
+ * (D-88). Told again until it starts, since a chat busy telling the end may lose the line on its way to its words (Priya).
  */
 export declare function coachOnEnd(context: Context, folder: string, current: CurrentGame): boolean;
 /**
- * How to start the coach on the player's move that ended the game: whatever the player asks, beside the analyst when the chat starts it too, since a chat on
- * a quick model started only the agent that answered the player (Priya).
+ * How to start the coach once a move ended the game, on the player's last move, theirs that ended it or the one before the AI's: whatever the player asks,
+ * beside the analyst when the chat starts it too, since a chat on a quick model started only the agent that answered the player (Priya).
  */
-export declare const coachOnEndLine: string;
+export declare function coachOnEndLine({ turn, ai }: GameSummary): string;
 /**
  * How to start the agents, in one message, the one that thinks first, since it needs the time (Priya), and that the player sees nothing of
  * them: their end needs no answer either. The end of the last move's agents, told just after, must not take their place (Priya).
@@ -41,5 +49,7 @@ export declare function goneOver(context: Context, game: string): boolean;
  * agent with it, or it has written nothing for half an hour, as one long dead (D-109): a quiet minute proves nothing, since an analyst may think long.
  */
 export declare function analystOf(context: Context, game: string): string | undefined;
+/** When the analyst that holds a game counts as gone if it writes nothing before: none while no analyst holds one. */
+export declare function analystQuietAt(context: Context): Date | undefined;
 /** What stops an analyst agent on a game another analyst has taken: the chat hears of the review from that one (Priya). */
 export declare const anotherAnalyst: string;

package/dist/commands/answers/agents.js

@@ -1,7 +1,7 @@
 // The agents that work beside the chat in Claude Code and Codex (D-98): the analyst that goes over a game over (D-89) and the coach that judges the player's moves (D-88).
 import { isReviewed } from "../../core/index.js";
 import { archivedName, coachStarted, gameInAnalysis, lastChatStart } from "../../games/index.js";
-import { agentHosts, analystAgent, coachAgent, hasAgent } from "../../host-files/index.js";
+import { agentHosts, analystAgent, coachAgent, hasAgent, isCodex } from "../../host-files/index.js";
 import { gameFolder, helpsIn } from "../../profiles/index.js";
 import { namedGame } from "./study.js";
 import { unplayed } from "./summary.js";
@@ -20,13 +20,36 @@ export function withAnalyst(summary, context, over) {
         return summary;
     }
     const archived = over === undefined ? undefined : archivedName(gameFolder(context.home()), over);
-    return { ...summary, end: { ...end, analyst: archived !== undefined && goneOver(context, archived) ? "done" : "offer" } };
+    const analyst = archived !== undefined && goneOver(context, archived) ? "done" : "offer";
+    return { ...summary, end: { ...end, analyst, ...(isCodex(context.host?.()) ? { codex: true } : {}) } };
 }
-/** How the chat has a game over gone over by the analyst agent, on the player's yes or for the game they brought (D-89). */
-export function analystLine(game) {
-    return `start the chesspal-analyst agent in the background with the prompt "Analyse${game === undefined ? "" : ` ${game}`}. The player speaks <their language>.": it writes its review on the board `
-        + "page, which shows it at work; tell the player in a word, talk the game over with them meanwhile whenever they ask, and when it ends go over it with them "
-        + "from what it tells you.";
+/**
+ * How the chat has a game over gone over by the analyst agent, on the player's yes or for the game they brought (D-89); in Codex with spawn_agent by name,
+ * since a chat there called analyse_game itself instead (Priya).
+ */
+export function analystLine(game, codex = false) {
+    const prompt = `Analyse${game === undefined ? "" : ` ${game}`}. The player speaks <their language>.`;
+    const start = codex
+        ? `start the ${analystAgent} agent with spawn_agent {"agent_type": "${analystAgent}", "message": "${prompt}", "fork_turns": "none"}`
+        : `start the ${analystAgent} agent in the background with the prompt "${prompt}"`;
+    return `${start}: it writes its review on the board page, which shows it at work; tell the player in a word, talk the game over with them meanwhile whenever `
+        + "they ask, and when it ends go over it with them from what it tells you.";
+}
+/**
+ * The analyst's line for the chat that looks at the game in analysis with no review and no analyst at it, as after «Delete the analysis», which rings no
+ * doorbell (Priya): once a change of the analysis, where the server keeps what it told.
+ */
+export function analystOnView(context, game) {
+    if (game === undefined || context.agent !== undefined || !analystRuns(context)) {
+        return undefined;
+    }
+    const analysis = gameInAnalysis(gameFolder(context.home()));
+    const key = `analyst on view ${game} ${analysis?.at ?? ""}`;
+    if (analysis?.game !== game || context.told?.has(key) === true || goneOver(context, game)) {
+        return undefined;
+    }
+    context.told?.add(key);
+    return `${game} has no review. When the player wants it gone over, ${analystLine(game, isCodex(context.host?.()))}`;
 }
 /** How the chat goes over a game the analyst agent has reviewed, or is reviewing: from that review, never with another agent (Stefano). */
 export function reviewedLine(game) {
@@ -43,20 +66,22 @@ export function agentRuns(context, agent) {
     return host !== undefined && agentHosts.includes(host) && hasAgent(context.folder, agent, host);
 }
 /**
- * Whether to start the coach after the player's own move has ended the game on the board, with the helps on: it judges that move too (D-88). Told again
- * until it starts, since a chat woken by the page may lose the line on its way to its words (Priya).
+ * Whether to start the coach once a move has ended the game on the board, with the helps on: it judges the player's last move, their own that ended it too
+ * (D-88). Told again until it starts, since a chat busy telling the end may lose the line on its way to its words (Priya).
  */
 export function coachOnEnd(context, folder, current) {
-    const { game, ai } = current;
-    return game.outcome.over && game.position.turn === ai && helpsIn(folder) && coachRuns(context) && !coachStarted(folder, current);
+    return current.game.outcome.over && helpsIn(folder) && coachRuns(context) && !coachStarted(folder, current);
 }
 /**
- * How to start the coach on the player's move that ended the game: whatever the player asks, beside the analyst when the chat starts it too, since a chat on
- * a quick model started only the agent that answered the player (Priya).
+ * How to start the coach once a move ended the game, on the player's last move, theirs that ended it or the one before the AI's: whatever the player asks,
+ * beside the analyst when the chat starts it too, since a chat on a quick model started only the agent that answered the player (Priya).
  */
-export const coachOnEndLine = `Coach the player: start the ${coachAgent} agent in the background with the prompt "Coach.", whatever the player asks: it judges `
-    + "the move that ended the game, apart from the analyst; when you start the analyst too, start both in one message. Start it even when an agent of the move "
-    + "before has just ended, and write nothing about it in the chat, now or when it ends.";
+export function coachOnEndLine({ turn, ai }) {
+    const judged = turn === ai ? "the move that ended the game" : "the player's last move, the one before the end";
+    return `Coach the player: start the ${coachAgent} agent in the background with the prompt "Coach.", whatever the player asks: it judges ${judged}, apart `
+        + "from the analyst; when you start the analyst too, start both in one message. Start it even when an agent of the move before has just ended, and write "
+        + "nothing about it in the chat, now or when it ends.";
+}
 /**
  * How to start the agents, in one message, the one that thinks first, since it needs the time (Priya), and that the player sees nothing of
  * them: their end needs no answer either. The end of the last move's agents, told just after, must not take their place (Priya).
@@ -100,6 +125,11 @@ export function analystOf(context, game) {
     const quiet = analysis !== undefined && context.now().getTime() - Date.parse(analysis.at) > analystQuiet;
     return taken?.game === game && !restarted && !quiet ? taken.run : undefined;
 }
+/** When the analyst that holds a game counts as gone if it writes nothing before: none while no analyst holds one. */
+export function analystQuietAt(context) {
+    const analysis = gameInAnalysis(gameFolder(context.home()));
+    return analysis?.analyst === undefined ? undefined : new Date(Date.parse(analysis.at) + analystQuiet);
+}
 /** How long an analyst may write nothing before it counts as gone. */
 const analystQuiet = 30 * 60 * 1000;
 /** What stops an analyst agent on a game another analyst has taken: the chat hears of the review from that one (Priya). */