chesspal 0.0.1 → 0.2.0

package/dist/commands/opening-book.js

@@ -0,0 +1,84 @@
+// The book of the openings the build indexed (D-16), read once at the first lookup; the book's moves, only for a game at the master level (D-60).
+import { readFileSync } from "node:fs";
+import { bookMoves, Game, inOpenings, openingOf, outOfBookMove } from "../core/index.js";
+// The index of the named openings and the book of their moves, each read at its first lookup; null where the build made none.
+let index;
+let book;
+// Each record is looked up once: the live game keeps its record until a move changes it.
+const lines = new WeakMap();
+/** The game's opening as the AI reads it: ECO and name, and the move it left the book at; none outside the book, or where the build made no index. */
+export function openingLine(record) {
+    let line = lines.get(record);
+    if (line === undefined) {
+        line = lineOf(record) ?? null;
+        lines.set(record, line);
+    }
+    return line ?? undefined;
+}
+/** The moves the book knows from a position (D-15), for the AI at the master level; none out of the book, or where the build made no book. */
+export function knownMoves(fen) {
+    const moves = openingBook();
+    return moves === undefined ? [] : bookMoves(fen, moves);
+}
+/** How many plies from the start the book knows, to the last before the game left it (D-69); none from another position. */
+export function bookPlies(record) {
+    if (record.tags.FEN !== undefined) {
+        return 0;
+    }
+    const game = new Game({ tags: record.tags, moves: [] });
+    let plies = 0;
+    for (const { san } of record.moves) {
+        if (!game.playRecorded(san).played || !bookReaches(game.position.fen)) {
+            break;
+        }
+        plies++;
+    }
+    return plies;
+}
+/** Whether a line of Lichess's openings reaches a position, by any order of moves (D-68); never where the build made no book. */
+export function bookReaches(fen) {
+    const named = openingIndex();
+    const moves = openingBook();
+    return named !== undefined && moves !== undefined && inOpenings(fen, named, moves);
+}
+/** The opening a game reached, ECO and name, without where it left the book: for the games in the archive. */
+export function openingName(record) {
+    const opening = bookOpening(record);
+    return opening === undefined ? undefined : `${opening.eco} ${opening.name}`;
+}
+/** The last named opening a game reached, and at which ply; none outside the book, or where the build made no index. */
+export function bookOpening(record) {
+    const named = openingIndex();
+    return named === undefined ? undefined : openingOf(record, named);
+}
+function lineOf(record) {
+    const opening = bookOpening(record);
+    if (opening === undefined) {
+        return undefined;
+    }
+    return `${opening.eco} ${opening.name}${opening.inBook ? "" : ` (out of book since move ${outOfBookMove(opening)})`}`;
+}
+function openingBook() {
+    if (book === undefined) {
+        try {
+            book = JSON.parse(readFileSync(new URL("../../dist/core/book.json", import.meta.url), "utf8"));
+        }
+        catch {
+            // Not built yet: the master goes without the book.
+            book = null;
+        }
+    }
+    return book ?? undefined;
+}
+function openingIndex() {
+    if (index === undefined) {
+        try {
+            index = JSON.parse(readFileSync(new URL("../../dist/core/openings.json", import.meta.url), "utf8"));
+        }
+        catch {
+            // Not built yet: the views go without the opening.
+            index = null;
+        }
+    }
+    return index ?? undefined;
+}

package/dist/commands/page-link.d.ts

@@ -0,0 +1,11 @@
+import type { Context } from "./context.ts";
+/** The board page's address when the chat serves it and no browser has it open; none on the command line, or with the page open. */
+export declare function closedPage(context: Context): string | undefined;
+/** The board page's address once a game, for a move written in the chat while no browser has the page open: the game is played there (D-85). */
+export declare function pageInvite(context: Context, started: string | undefined): string | undefined;
+/** Notes the board page's address given for a game, by status or new_game: a move in the chat does not give it again (Priya, round of D-85). */
+export declare function pageGiven(context: Context, started: string): void;
+/** The line that has the AI invite the player to the board page from the chat. */
+export declare function inviteLine(url: string): string;
+/** The board page's line: its address, and when nobody has it open, that the player needs it first. */
+export declare function pageLine(url: string, closed: boolean): string;

package/dist/commands/page-link.js

@@ -0,0 +1,28 @@
+/** The board page's address when the chat serves it and no browser has it open; none on the command line, or with the page open. */
+export function closedPage(context) {
+    return context.page !== undefined && context.pageOpen?.() === false ? context.page : undefined;
+}
+/** The board page's address once a game, for a move written in the chat while no browser has the page open: the game is played there (D-85). */
+export function pageInvite(context, started) {
+    const page = closedPage(context);
+    if (page === undefined || context.told === undefined || context.told.has(inviteKey(started))) {
+        return undefined;
+    }
+    context.told.add(inviteKey(started));
+    return page;
+}
+/** Notes the board page's address given for a game, by status or new_game: a move in the chat does not give it again (Priya, round of D-85). */
+export function pageGiven(context, started) {
+    context.told?.add(inviteKey(started));
+}
+/** The line that has the AI invite the player to the board page from the chat. */
+export function inviteLine(url) {
+    return `The board page is open in no browser, and the game is played there: invite the player, in a few words, to open ${url}; their moves in the chat still count.`;
+}
+/** The board page's line: its address, and when nobody has it open, that the player needs it first. */
+export function pageLine(url, closed) {
+    return closed ? `Board page: ${url}, open in no browser: give the player this address before anything else.` : `Board page: ${url}`;
+}
+function inviteKey(started) {
+    return `page invite ${started ?? ""}`;
+}

package/dist/commands/past-games.d.ts

@@ -0,0 +1,11 @@
+import { z } from "zod";
+/** The AI's memory of the games played (D-57): how the latest went, one line each, or one game whole from the archive. */
+export declare const pastGames: import("./registry.ts").Command<z.ZodObject<{
+    game: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>, {
+    games: string[];
+} | {
+    pgn: string;
+}>;
+/** The latest games of the archive, one line each as the AI reads them: none when there is no archive. */
+export declare function pastGameLines(folder: string, count: number): string[];

package/dist/commands/past-games.js

@@ -0,0 +1,47 @@
+import { z } from "zod";
+import { writePgn } from "../core/index.js";
+import { archivedGame, archivedGames, archivedWhen } from "../games/index.js";
+import { gameFolder } from "../profiles/index.js";
+import { openingName } from "./opening-book.js";
+import { defineCommand } from "./registry.js";
+/** The AI's memory of the games played (D-57): how the latest went, one line each, or one game whole from the archive. */
+export const pastGames = defineCommand({
+    name: "past_games",
+    description: "Lists the games played with this player, the latest first: when, your colour, the result, the opening, how long, and its name in the "
+        + "archive. With game, that game's PGN with your comments and plans; to comment a game with the player, analyse_game. new_game already gives the "
+        + "last three. Example: past_games {}.",
+    input: z.object({ game: z.string().optional().describe("a game's name, as the list writes it: its PGN") }),
+    readOnly: true,
+    idempotent: true,
+    run: ({ game }, context) => {
+        const folder = gameFolder(context.home());
+        return game === undefined ? { games: pastGameLines(folder, listed) } : { pgn: writePgn(archivedGame(folder, game)) };
+    },
+    format: (past) => ("pgn" in past ? past.pgn : past.games.length === 0 ? "No game played yet." : past.games.join("\n")),
+});
+/** The latest games of the archive, one line each as the AI reads them: none when there is no archive. */
+export function pastGameLines(folder, count) {
+    return archivedGames(folder).slice(0, count).flatMap((name) => {
+        try {
+            return [pastGameLine(name, archivedGame(folder, name))];
+        }
+        catch {
+            // A game the archive cannot read stays out of the memory.
+            return [];
+        }
+    });
+}
+const listed = 20;
+/** 2026-11-03 12:04, you (AI) played Black and won 0-1 (White resigns), B50 Sicilian Defense, 15 moves. games/2026-11-03-120423.pgn */
+function pastGameLine(name, record) {
+    const ai = record.tags.Black === "AI" ? "black" : "white";
+    const result = record.tags.Result ?? "*";
+    const outcome = result === "*" ? ", unfinished" : ` and ${resultFor(result, ai)} ${result}`;
+    const termination = record.tags.Termination === undefined || result === "*" ? "" : ` (${record.tags.Termination})`;
+    const opening = openingName(record);
+    const moves = Math.ceil(record.moves.length / 2);
+    return `${archivedWhen(name)}, you (AI) played ${ai === "white" ? "White" : "Black"}${outcome}${termination}${opening === undefined ? "" : `, ${opening}`}, ${moves} moves. ${name}`;
+}
+function resultFor(result, ai) {
+    return result === "1/2-1/2" ? "drew" : (result === "1-0") === (ai === "white") ? "won" : "lost";
+}

package/dist/commands/play-move.d.ts

@@ -0,0 +1,37 @@
+import type { Context, SeenPosition } from "./context.ts";
+import { type MovePlayed } from "./game-summary.ts";
+/** Who plays a move: the AI, or the player through the AI. */
+export type Mover = "ai" | "player";
+/** What comes with a move: the AI's comment, or the player's words from the board page, saved with it, and a draw offer (D-65). */
+export interface WithMove {
+    comment?: string;
+    offerDraw?: boolean;
+    said?: {
+        text: string;
+        at: Date;
+    };
+    /** Milliseconds of the mover's turn that were not theirs, not taken off their clock (D-36). */
+    allowance?: number;
+    /** A coach judges the player's moves with the helps on (D-88): the AI reads it after the player's move. */
+    coached?: boolean;
+}
+/**
+ * Plays a move for one side `now` and saves the game, with the time it took and the clock after it in its comment ([%clk]). A refused move, or words refused
+ * with it, change nothing: it throws the message `refused` writes from the core's.
+ */
+export declare function playMove(folder: string, now: Date, mover: Mover, text: string, refused: (message: string, legal: readonly string[]) => string, { comment, said, offerDraw, allowance, coached }?: WithMove): MovePlayed;
+/** A chat's move, resignation or game replaced on a position it has not seen (D-71): it was decided on another. */
+export declare class PositionChanged extends Error {
+    constructor();
+}
+/** The position of the profile's game now. */
+export declare function positionIn(folder: string): SeenPosition;
+/**
+ * Refuses a chat's move or ending on a position it has not seen, changed by another chat or on the board page, or before any tool showed it the game
+ * (D-71). Words and the clock change no position; the command line and the page, which have no chat, are never refused.
+ */
+export declare function refuseUnseenPosition(context: Context, folder: string): void;
+/** Refuses a chat's words on a game it has not seen, which another chat or the page started: words on a later move of the same game do no harm. */
+export declare function refuseOtherGame(context: Context, folder: string): void;
+/** Whether two positions a chat may see are the same: the same game, as many plies. */
+export declare function samePosition(one: SeenPosition, other: SeenPosition): boolean;

package/dist/commands/play-move.js

@@ -0,0 +1,94 @@
+// A move of the AI or of the player on the current game: played, timed by the clock, saved, and archived when it ends the game.
+import { clockAfterMove, clockTag } from "../core/index.js";
+import { archiveEnded, endOf, loadGame, saveGame, talkLine } from "../games/index.js";
+import { gameGoingOn, summaryOf, withThought } from "./game-summary.js";
+import { colourName } from "./view.js";
+/**
+ * Plays a move for one side `now` and saves the game, with the time it took and the clock after it in its comment ([%clk]). A refused move, or words refused
+ * with it, change nothing: it throws the message `refused` writes from the core's.
+ */
+export function playMove(folder, now, mover, text, refused, { comment, said, offerDraw = false, allowance = 0, coached = false } = {}) {
+    // A flag falls only past the allowance.
+    const before = gameToMove(folder, mover, new Date(now.getTime() - allowance));
+    const { game } = before;
+    const position = game.position;
+    // The words are checked before the move, which changes the live game; they count as said after it.
+    const line = said === undefined ? undefined : talkLine(before, mover, said.text, said.at, game.record.moves.length + 1);
+    if (mover === "ai" && before.clock?.waiting === true) {
+        throw new Error("The clocks wait for the player to start the game with Start on the board page: don't move yet, the doorbell wakes you then. Nothing changed.");
+    }
+    if (offerDraw && game.record.moves.length === 0) {
+        throw new Error("A draw can be offered once each side has made a move: play the move without offer_draw. Nothing changed.");
+    }
+    const played = game.play(text);
+    if (!played.played) {
+        throw new Error(refused(played.message, played.legal));
+    }
+    const clock = before.clock === undefined ? undefined : clockAfterMove(before.clock, position.turn, now, allowance, mover === "player");
+    // A move declines the other side's draw offer; the mover's own stands, and the move carries it in the record as FIDE writes it, (=) (D-65). A move that
+    // ends the game leaves no offer.
+    const offers = (offerDraw || before.drawOffer === mover) && endOf(game) === undefined;
+    const current = { ...before, drawOffer: offers ? mover : undefined, ...(clock === undefined ? {} : { clock }) };
+    const words = [offers ? "(=)" : undefined, comment, clock === undefined ? undefined : clockTag(clock.left[position.turn])].filter((part) => part !== undefined);
+    if (words.length > 0) {
+        game.annotate(game.record.moves.length, { comment: words.join(" ") });
+    }
+    if (line !== undefined) {
+        current.talk.push(line);
+    }
+    saveGame(folder, current);
+    const { archive, warning } = endOf(game) === undefined ? {} : archiveEnded(folder, current);
+    const result = { move: `${position.moveNumber}${position.turn === "white" ? "." : "..."}${played.move.san}`, game: withThought(summaryOf(current, now, archive), folder, current, coached) };
+    if (played.note !== undefined) {
+        result.note = played.note;
+    }
+    if (warning !== undefined) {
+        result.warning = warning;
+    }
+    return result;
+}
+/** A chat's move, resignation or game replaced on a position it has not seen (D-71): it was decided on another. */
+export class PositionChanged extends Error {
+    constructor() {
+        super("The game may have changed since you last saw it, in another chat or on the board page: call status to see it, then decide. Nothing changed.");
+    }
+}
+/** The position of the profile's game now. */
+export function positionIn(folder) {
+    const current = loadGame(folder);
+    return current === undefined ? { plies: 0 } : { started: current.started, plies: current.game.record.moves.length };
+}
+/**
+ * Refuses a chat's move or ending on a position it has not seen, changed by another chat or on the board page, or before any tool showed it the game
+ * (D-71). Words and the clock change no position; the command line and the page, which have no chat, are never refused.
+ */
+export function refuseUnseenPosition(context, folder) {
+    const seen = context.positionSeen;
+    if (seen === null || (seen !== undefined && !samePosition(seen, positionIn(folder)))) {
+        throw new PositionChanged();
+    }
+}
+/** Refuses a chat's words on a game it has not seen, which another chat or the page started: words on a later move of the same game do no harm. */
+export function refuseOtherGame(context, folder) {
+    const seen = context.positionSeen;
+    const now = positionIn(folder);
+    if (now.started !== undefined && (seen === null || (seen !== undefined && seen.started !== now.started))) {
+        throw new PositionChanged();
+    }
+}
+/** Whether two positions a chat may see are the same: the same game, as many plies. */
+export function samePosition(one, other) {
+    return one.started === other.started && one.plies === other.plies;
+}
+function gameToMove(folder, mover, now) {
+    const current = gameGoingOn(folder, now);
+    const { turn } = current.game.position;
+    const aiToMove = turn === current.ai;
+    if (mover === "player" && aiToMove) {
+        throw new Error(`It is your move (${colourName(turn)}): call ai_move. Nothing changed.`);
+    }
+    if (mover === "ai" && !aiToMove) {
+        throw new Error(`It is the player's move (${colourName(turn)}): wait for it, then call player_move. Nothing changed.`);
+    }
+    return current;
+}

package/dist/commands/player-move.d.ts

@@ -0,0 +1,13 @@
+import { z } from "zod";
+import { type MovePlayed } from "./game-summary.ts";
+/** The player's move, written in the chat and given by the AI: it answers with the position the AI decides on (D-34). */
+export declare const playerMove: import("./registry.ts").Command<z.ZodObject<{
+    move: z.ZodString;
+    offer_draw: z.ZodOptional<z.ZodBoolean>;
+}, z.core.$strip>, PlayerMove>;
+/** The player's move, with the board page's address once a game while no browser has it open (D-85), and the coach to start when it ended the game (D-88). */
+interface PlayerMove extends MovePlayed {
+    invite?: string;
+    coach?: true;
+}
+export {};

package/dist/commands/player-move.js

@@ -0,0 +1,51 @@
+import { z } from "zod";
+import { loadGame } from "../games/index.js";
+import { coachAgent } from "../host-files/index.js";
+import { gameFolder } from "../profiles/index.js";
+import { agentsLine, coachOnEnd, coachRuns, withAnalyst } from "./agents.js";
+import { closingLines, lastMoveText, moveLines, shownMove } from "./answer-lines.js";
+import {} from "./game-summary.js";
+import { inviteLine, pageInvite } from "./page-link.js";
+import { playMove, positionIn, refuseUnseenPosition } from "./play-move.js";
+import { defineCommand } from "./registry.js";
+import { newWords } from "./say.js";
+/** The player's move, written in the chat and given by the AI: it answers with the position the AI decides on (D-34). */
+export const playerMove = defineCommand({
+    name: "player_move",
+    description: "Plays the move the player wrote in the chat, and answers with the position for your reply: the FEN, your legal moves by piece and, from "
+        + "the club level up, the pieces attacked with their defenders, the pins and the checks; look gives the rest. Give the move in SAN or as squares, and never choose for "
+        + 'them: if their words fit two moves, or it is refused, ask them again. Example: player_move {move: "Nf3"}.',
+    input: z.object({
+        move: z.string().min(1).describe("the player's move, in SAN (Nf3, exd5, O-O, e8=Q) or as squares (g1f3, e7e8q)"),
+        offer_draw: z.boolean().optional().describe("true when the player offers a draw with this move: it stands until your move"),
+    }),
+    alwaysLoad: true,
+    showsGame: true,
+    positionals: ["move"],
+    run: ({ move, offer_draw: offerDraw = false }, context) => {
+        const folder = gameFolder(context.home());
+        // A chat that has seen no game yet, new or resumed, plays the player's own move: its answer shows the game the AI decides on (D-71).
+        if (context.positionSeen !== null) {
+            refuseUnseenPosition(context, folder);
+        }
+        const started = context.positionSeen === null ? positionIn(folder).started : context.positionSeen?.started;
+        const played = playMove(folder, context.now(), "player", move, (message) => `${message} Ask the player again. Nothing changed.`, { allowance: chatAllowance, offerDraw, coached: coachRuns(context) });
+        // A game over by this move has no more moves to play there: the next game's window gives the address (Federico, round of D-85).
+        const invite = played.game.end === undefined ? pageInvite(context, started) : undefined;
+        const ended = played.game.end === undefined ? undefined : loadGame(folder);
+        const coach = ended !== undefined && coachOnEnd(context, folder, ended);
+        return { ...played, game: withAnalyst(played.game, context), words: newWords(context), ...(invite === undefined ? {} : { invite }), ...(coach ? { coach } : {}) };
+    },
+    format: (result) => [
+        `Player: ${result.game.lastMove === undefined ? shownMove(result.move) : lastMoveText(result.game.lastMove)}.`,
+        ...moveLines(result),
+        ...(result.invite === undefined ? [] : [inviteLine(result.invite)]),
+        ...(result.coach === true ? [agentsLine([coachAgent])] : []),
+        ...closingLines(result.game, result.words),
+    ].join("\n"),
+});
+/**
+ * The time a move in the chat leaves off the player's clock (D-36): the AI writing after its move and reading the player's, about 10 s as Priya measured.
+ * Claude Code's hooks will time it exactly; the board page's moves need none.
+ */
+const chatAllowance = 10_000;

package/dist/commands/player-say.d.ts

@@ -0,0 +1,5 @@
+import { z } from "zod";
+/** The player's words to the AI, as the board page sends them: on the command line only, since the AI never writes for the player. */
+export declare const playerSay: import("./registry.ts").Command<z.ZodObject<{
+    text: z.ZodString;
+}, z.core.$strip>, string>;

package/dist/commands/player-say.js

@@ -0,0 +1,16 @@
+import { z } from "zod";
+import { talkLimits } from "../games/index.js";
+import { gameFolder } from "../profiles/index.js";
+import { defineCommand } from "./registry.js";
+import { say } from "./say.js";
+/** The player's words to the AI, as the board page sends them: on the command line only, since the AI never writes for the player. */
+export const playerSay = defineCommand({
+    name: "player_say",
+    description: "Writes the player's words to the AI, as the board page does: the AI reads them at its next call. "
+        + 'Example: chesspal player_say "Play faster, please."',
+    input: z.object({ text: z.string().trim().min(1, "write what you say").max(talkLimits.player, `write ${talkLimits.player} characters at most`).describe("what the player says to the AI") }),
+    cliOnly: true,
+    positionals: ["text"],
+    run: ({ text }, context) => say(gameFolder(context.home()), "player", text, context.now()).talk.at(-1).text,
+    format: (text) => `Written for the AI: «${text}». It reads it at its next call.`,
+});

package/dist/commands/ponder.d.ts

@@ -0,0 +1,52 @@
+import { z } from "zod";
+import { type Thought } from "../games/index.ts";
+import { type GameSummary } from "./game-summary.ts";
+/** What ponder answers: stop, the position to think on, the position after a reply, the thoughts kept, its words said, or still the player's move. */
+type Pondered = {
+    stop: "moved" | "waited";
+} | {
+    start: Start;
+} | {
+    after: GameSummary;
+    position: number;
+    reply: string;
+} | {
+    kept: readonly Thought[];
+    position: number;
+} | {
+    waiting: number;
+} | {
+    said: number;
+};
+/** The position the player is to move in, as the AI thinks on it. */
+interface Start {
+    position: number;
+    line: string;
+    plan?: string;
+    mood?: string;
+    comment?: string;
+    talk: string[];
+}
+/**
+ * The AI's thinking on the player's time (D-72), for the agent that does it: the position, the view after a reply, its answer kept for its move, and its
+ * words on the board page. Its calls are not the chat's: the doorbell still wakes the chat for the player's move. Offered to Claude Code alone, which runs the agent.
+ */
+export declare const ponder: import("./registry.ts").Command<z.ZodObject<{
+    position: z.ZodOptional<z.ZodInt>;
+    reply: z.ZodOptional<z.ZodString>;
+    move: z.ZodOptional<z.ZodString>;
+    why: z.ZodOptional<z.ZodString>;
+    say: z.ZodOptional<z.ZodString>;
+    done: z.ZodOptional<z.ZodBoolean>;
+}, z.core.$strip>, Pondered>;
+/**
+ * Waits for the player's move, for an agent that works on their time (D-72, D-88): moved once `gone` says so, waited once the agent has waited long enough in
+ * all since `since`, else still waiting after a while.
+ */
+export declare function waitForPlayer(context: {
+    now: () => Date;
+    pause?: (milliseconds: number) => Promise<void>;
+}, since: Date, gone: () => boolean): Promise<"moved" | "waited" | "waiting">;
+/** The words of the AI's move for the player: its comment without the plan, the mood, the clock and the draw offer it carries. */
+export declare function wordsOf(comment: string | undefined): string | undefined;
+export {};

package/dist/commands/ponder.js

@@ -0,0 +1,179 @@
+import { z } from "zod";
+import { Game, levelOf, moodAt, sees, timeLeft } from "../core/index.js";
+import { currentPlan, endOf, keepThought, loadGame, talkLimits, thoughtKey, waitingSince } from "../games/index.js";
+import { ponderAgents } from "../host-files/index.js";
+import { gameFolder } from "../profiles/index.js";
+import { positionLines } from "./answer-lines.js";
+import { summaryOf } from "./game-summary.js";
+import { levelText } from "./levels.js";
+import { defineCommand, sentence } from "./registry.js";
+import { say as sayWords } from "./say.js";
+import { boardView, colourName, compactView } from "./view.js";
+/**
+ * The AI's thinking on the player's time (D-72), for the agent that does it: the position, the view after a reply, its answer kept for its move, and its
+ * words on the board page. Its calls are not the chat's: the doorbell still wakes the chat for the player's move. Offered to Claude Code alone, which runs the agent.
+ */
+export const ponder = defineCommand({
+    name: "ponder",
+    description: "For the chesspal-ponder agents only, never from the chat: ai_move says when to start one. While the player is to move: ponder {} gives the "
+        + "position to think on; ponder {position, reply} the position after a likely reply, as you will see it; ponder {position, reply, move, why} keeps your "
+        + "answer to it, which you are given when they play it; ponder {position, say} says a word on the board page; ponder {position, done: true} waits for their "
+        + 'move. Whenever it says stop, stop. Example: ponder {position: 24, reply: "Nxe5", move: "d6", why: "The knight has to go back."}.',
+    input: z.object({
+        position: z.int().min(0).optional().describe("the position's number, as ponder {} gives it"),
+        reply: z.string().min(1).optional().describe("a move the player may play, in SAN (Nxe5) or as squares (f3e5)"),
+        move: z.string().min(1).optional().describe("your answer to that reply, in SAN or as squares"),
+        why: sentence(200).optional().describe("why, in one sentence: kept for you, hidden from the player"),
+        say: z.string().trim().min(1).max(talkLimits.ai).optional().describe("your words for the player on the board page, once, in one short sentence, of what has happened: pieces and moves in words, never in notation"),
+        done: z.boolean().optional().describe("true when you have no more replies to think on: it waits for the player's move"),
+    }),
+    byAgents: ponderAgents,
+    host: "claude-code",
+    run: async ({ position, reply, move, why, say, done = false }, context) => {
+        const folder = gameFolder(context.home());
+        const current = toPonder(folder, context.now(), position);
+        if (current === undefined) {
+            return { stop: "moved" };
+        }
+        if (position === undefined) {
+            if (reply !== undefined || move !== undefined || why !== undefined || say !== undefined || done) {
+                throw new Error("Give the position's number with it: call ponder {} first, which gives it. Nothing changed.");
+            }
+            context.ponders?.({ started: current.started, plies: current.game.record.moves.length });
+            return { start: startOf(current) };
+        }
+        if ((say !== undefined || done) && (reply !== undefined || move !== undefined || why !== undefined || (say !== undefined && done))) {
+            throw new Error("One thing a call: say, done, or a reply with its answer. Nothing changed.");
+        }
+        if (say !== undefined) {
+            sayWords(folder, "agent", say, context.now());
+            return { said: position };
+        }
+        if (done) {
+            context.ponders?.(undefined);
+            return await waitForMove(folder, context, current);
+        }
+        if (reply === undefined) {
+            throw new Error(`Name a reply of the player's: ponder {position: ${position}, reply}, or ponder {position: ${position}, done: true} when you have no more. Nothing changed.`);
+        }
+        if (move === undefined && why !== undefined) {
+            throw new Error(`Give your move with its why: ponder {position: ${position}, reply, move, why}. Nothing changed.`);
+        }
+        const after = new Game(current.game.record);
+        const played = after.play(reply);
+        if (!played.played) {
+            throw new Error(`${played.message} The player's legal moves: ${played.legal.join(" ")}. Nothing changed.`);
+        }
+        if (move === undefined) {
+            return { after: summaryOf({ game: after, ai: current.ai, started: current.started, talk: [] }, context.now()), position, reply: played.move.san };
+        }
+        if (why === undefined) {
+            throw new Error(`Say why in one sentence: ponder {position: ${position}, reply, move, why}. Nothing changed.`);
+        }
+        const answer = after.play(move);
+        if (!answer.played) {
+            throw new Error(`${answer.message} Your legal moves after ${played.move.san}: ${answer.legal.join(" ")}. Nothing changed.`);
+        }
+        return { kept: keepThought(folder, thoughtKey(current), { reply: played.move.san, move: answer.move.san, why }), position };
+    },
+    format: (pondered) => {
+        if ("stop" in pondered) {
+            return pondered.stop === "moved"
+                ? "Stop now: the player has moved, or the game is over. End with one word."
+                : "Stop now: you have waited long enough, and your answers are kept. End with one word.";
+        }
+        if ("start" in pondered) {
+            return startLines(pondered.start).join("\n");
+        }
+        if ("after" in pondered) {
+            const { after, position, reply } = pondered;
+            return [`If the player plays ${reply}:`, ...positionLines(after), `Keep your answer: ponder {position: ${position}, reply: "${reply}", move, why}.`].join("\n");
+        }
+        if ("kept" in pondered) {
+            const replies = pondered.kept.map((thought) => thought.reply).join(", ");
+            return `Kept: your answers to ${replies}. Think on another likely reply, or call ponder {position: ${pondered.position}, done: true} when you have no more.`;
+        }
+        if ("said" in pondered) {
+            return "Said on the board page, where the player reads it.";
+        }
+        return `Still the player's move: call ponder {position: ${pondered.waiting}, done: true} again.`;
+    },
+});
+/**
+ * Waits for the player's move, for an agent that works on their time (D-72, D-88): moved once `gone` says so, waited once the agent has waited long enough in
+ * all since `since`, else still waiting after a while.
+ */
+export async function waitForPlayer(context, since, gone) {
+    const pause = context.pause ?? ((milliseconds) => new Promise((done) => setTimeout(done, milliseconds)));
+    const start = context.now().getTime();
+    const end = Math.min(start + playerWait.most, since.getTime() + playerWait.inAll);
+    while (context.now().getTime() < end) {
+        await pause(playerWait.every);
+        if (gone()) {
+            return "moved";
+        }
+    }
+    return end < start + playerWait.most ? "waited" : "waiting";
+}
+/** The words of the AI's move for the player: its comment without the plan, the mood, the clock and the draw offer it carries. */
+export function wordsOf(comment) {
+    const words = comment?.replace(/\[%[^\]]*\]/g, "").replace("(=)", "").replace(/\s+/g, " ").trim();
+    return words === undefined || words === "" ? undefined : words;
+}
+/**
+ * How long one call waits for the player's move at most, under the minute a host may give a tool (Priya), how often it looks, and how long the agent
+ * waits in all before it stops: a player who leaves the game open must not keep it asking (Priya).
+ */
+const playerWait = { most: 50_000, every: 500, inAll: 10 * 60_000 };
+/** The game whose position the AI thinks on, read and never written: none once the player has moved, the game is over or their flag has fallen, or the position given is another. */
+function toPonder(folder, now, position) {
+    const current = loadGame(folder);
+    if (current === undefined || endOf(current.game) !== undefined || current.game.position.turn === current.ai) {
+        return undefined;
+    }
+    // A flag fallen is the page's or the chat's to write, so that the doorbell rings it (Federico).
+    const { turn } = current.game.position;
+    if (current.clock !== undefined && timeLeft(current.clock, turn, now)[turn] <= 0) {
+        return undefined;
+    }
+    return position === undefined || position === current.game.record.moves.length ? current : undefined;
+}
+/** Waits for the player's move: stop once they have moved or the agent has waited long enough in all, else still their move after a while. */
+async function waitForMove(folder, context, current) {
+    const position = current.game.record.moves.length;
+    const waited = await waitForPlayer(context, waitingSince(folder, thoughtKey(current), context.now()), () => toPonder(folder, context.now(), position) === undefined);
+    return waited === "waiting" ? { waiting: position } : { stop: waited };
+}
+function startOf(current) {
+    const { game, ai, talk } = current;
+    const level = levelOf(game.record);
+    const plan = currentPlan(game.record);
+    const player = game.position.turn;
+    const { mood } = moodAt(game.record, ai);
+    const comment = wordsOf(game.record.moves.at(-1)?.comment);
+    const line = [
+        `Position ${game.record.moves.length}: the player (${colourName(player)}) to move, move ${game.position.moveNumber}; you play ${colourName(ai)} ${levelText(level)}.`,
+        `FEN: ${game.position.fen}`,
+        ...(sees(level, "tactics") ? compactView : boardView)(game.facts, player),
+    ].join("\n");
+    const said = talk.slice(-3).map((spoken) => `${spoken.who === "ai" ? "You" : "Player"}: «${spoken.text.replace(/\s+/g, " ")}»`);
+    return {
+        position: game.record.moves.length,
+        line,
+        ...(plan === undefined ? {} : { plan }),
+        ...(mood === "neutral" ? {} : { mood }),
+        ...(comment === undefined ? {} : { comment }),
+        talk: said,
+    };
+}
+function startLines({ position, line, plan, mood, comment, talk }) {
+    return [
+        line,
+        ...(plan === undefined ? [] : [`Your plan: ${plan}`]),
+        ...(mood === undefined ? [] : [`Your mood: ${mood}.`]),
+        comment === undefined ? "You said nothing with your move." : `You said with your move: «${comment}»`,
+        ...(talk.length === 0 ? [] : ["Last words on the board page:", ...talk]),
+        `For each reply you think likely, ponder {position: ${position}, reply} shows the position after it, then ponder {position: ${position}, reply, move, why} keeps `
+            + `your answer; ponder {position: ${position}, done: true} when you have no more.`,
+    ];
+}