chesspal 0.0.0-stage → 0.1.0

package/dist/commands/look.d.ts

@@ -0,0 +1,31 @@
+import { z } from "zod";
+import { type Facts, type Side } from "../core/index.ts";
+import { type GameSummary } from "./game-summary.ts";
+/** The game with the facts of its position, whoever is to move. */
+type Viewed = GameSummary & {
+    facts: Facts;
+};
+/** A position of a game studied (D-68): where it stands, and its facts. */
+interface StudyView {
+    where: string;
+    turn: Side;
+    fen: string;
+    facts: Facts;
+}
+/** The whole view (D-26), when the compact one after the player's move is not enough; or the board for the player, where the host does not show it (D-36). */
+export declare const look: import("./registry.ts").Command<z.ZodObject<{
+    game: z.ZodOptional<z.ZodString>;
+    move: z.ZodOptional<z.ZodString>;
+    only: z.ZodOptional<z.ZodEnum<{
+        board: "board";
+    }>>;
+}, z.core.$strip>, {
+    board: string;
+} | {
+    game: Viewed;
+    words: string[];
+} | {
+    study: StudyView;
+    words: string[];
+}>;
+export {};

package/dist/commands/look.js

@@ -0,0 +1,61 @@
+import { z } from "zod";
+import { boardText, materialOf } from "../core/index.js";
+import { gameFolder } from "../profiles/index.js";
+import { gameAt } from "./clock.js";
+import { headLines, summaryOf, wordLines } from "./game-summary.js";
+import { refuseUnseen } from "./levels.js";
+import { defineCommand } from "./registry.js";
+import { newWords } from "./say.js";
+import { gameToStudy, positionAfter, positionLine, studyInput } from "./study.js";
+import { fullView, materialText } from "./view.js";
+/** The whole view (D-26), when the compact one after the player's move is not enough; or the board for the player, where the host does not show it (D-36). */
+export const look = defineCommand({
+    name: "look",
+    description: "Shows the whole view of the position, from the club level up and at every level once the game is over: the FEN and, for every piece, what attacks and defends it, then the pins, the checks and the legal "
+        + "moves of each piece. The views of player_move, status and new_game give attackers and defenders only for the pieces attacked: call look "
+        + 'before you attack or capture a piece that is not attacked yet, or plan an exchange. With only: "board", the board as text for the player, to '
+        + "copy into your message where they do not see it. With move, and game for a game of the archive, the same of any position of a game over, to "
+        + 'analyse it. Example: look {}, look {move: "12..."}.',
+    input: z.object({ only: z.enum(["board"]).optional().describe("board: only the board as text, for the player"), ...studyInput }),
+    // Read only for the host: a flag that has fallen is written, as the time already decided.
+    readOnly: true,
+    idempotent: true,
+    run: ({ only, game, move }, context) => {
+        if (game !== undefined || move !== undefined) {
+            return studyLook(context, only, game, move);
+        }
+        const current = gameAt(gameFolder(context.home()), context.now());
+        if (current === undefined) {
+            throw new Error("There is no game to look at: start one with new_game.");
+        }
+        if (only !== "board") {
+            refuseUnseen(current, "tactics", 'look without only: "board"');
+        }
+        return only === "board" ? { board: boardText(current.game.position.fen) } : { game: { ...summaryOf(current, context.now()), facts: current.game.facts }, words: newWords(context) };
+    },
+    format: (look) => {
+        if ("board" in look) {
+            return look.board;
+        }
+        return [...("game" in look ? [...headLines(look.game), ...fullView(look.game.facts, look.game.turn)] : studyLines(look.study)), ...wordLines(look.words)].join("\n");
+    },
+});
+/** A position of a game over, as the view of the game going on gives it. */
+function studyLook(context, only, name, move) {
+    const studied = gameToStudy(context, name);
+    const at = positionAfter(studied.record, move);
+    const { position } = at.game;
+    if (only === "board") {
+        return { board: boardText(position.fen) };
+    }
+    return { study: { where: positionLine(at, studied.name), turn: position.turn, fen: position.fen, facts: at.game.facts }, words: newWords(context) };
+}
+/** Where the position stands, the material, the FEN, and the whole view. */
+function studyLines({ where, turn, fen, facts }) {
+    return [
+        where,
+        `Material: ${materialText(materialOf(fen))}`,
+        `FEN: ${fen}`,
+        ...fullView(facts, turn),
+    ];
+}

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

@@ -0,0 +1,69 @@
+import { z } from "zod";
+import type { Context } from "./context.ts";
+import { type GameSummary, type Speech } from "./game-summary.ts";
+interface NewGame {
+    game: GameSummary;
+    /** Where the game before went: one going on, unfinished; one over, when its archive could not be written at its end. */
+    archived?: {
+        name: string;
+        finished: boolean;
+    };
+    /** The last games played with this player, for a chat that starts clean (D-57). */
+    past: string[];
+    /** Who plays, from the profile in use (D-23), once the player has completed it (D-71). */
+    player?: string;
+    /** The player's language when it is not English. */
+    speech?: Speech;
+    /** The board page's address when no browser has it open: the player needs it first. */
+    closedPage?: string;
+}
+/** The player chooses the game in the board page's window instead: open in a browser, or to be opened first at its address. */
+interface Asked {
+    window: "opened" | "closed";
+    page?: string;
+}
+declare const newGameInput: z.ZodObject<{
+    ai_colour: z.ZodOptional<z.ZodEnum<{
+        white: "white";
+        black: "black";
+        random: "random";
+    }>>;
+    from: z.ZodOptional<z.ZodString>;
+    clock: z.ZodOptional<z.ZodString>;
+    level: z.ZodOptional<z.ZodEnum<{
+        beginner: "beginner";
+        club: "club";
+        strong: "strong";
+        master: "master";
+    }>>;
+    replace: z.ZodDefault<z.ZodBoolean>;
+}, z.core.$strip>;
+/** A new game against the player, from the standard position or from a FEN or PGN; a game going on is never lost (D-41). */
+export declare const newGame: import("./registry.ts").Command<z.ZodObject<{
+    ai_colour: z.ZodOptional<z.ZodEnum<{
+        white: "white";
+        black: "black";
+        random: "random";
+    }>>;
+    from: z.ZodOptional<z.ZodString>;
+    clock: z.ZodOptional<z.ZodString>;
+    level: z.ZodOptional<z.ZodEnum<{
+        beginner: "beginner";
+        club: "club";
+        strong: "strong";
+        master: "master";
+    }>>;
+    replace: z.ZodDefault<z.ZodBoolean>;
+}, z.core.$strip>, NewGame | Asked>;
+/**
+ * Starts the new game with the player's choices: those the AI asked in the chat, or the page's window gave (D-76). Only the chat's is refused on a game
+ * changed since it saw it (D-71): the player who presses New game on the page sees the game there (Federico, round of D-85).
+ */
+export declare function startNewGame({ ai_colour: colour, from, clock, level: chosen, replace }: z.output<typeof newGameInput>, context: Context, by: "chat" | "page"): NewGame;
+/** The refusal of a new game in a chat that still holds the game before (D-57): the board page says it in the player's language. */
+export declare class ChatNotClear extends Error {
+    constructor();
+}
+/** From how many plies a game played in a chat asks for a clean one before the next (D-57): one left after a few moves does not. */
+export declare const pliesBeforeClearing = 20;
+export {};

package/dist/commands/new-game.js

@@ -0,0 +1,215 @@
+import { z } from "zod";
+import { aiLevels, Game, levelTag, pgnDate, readPgn, startClock, timeControlOf, timeControlTag, withoutMoods } from "../core/index.js";
+import { archivedName, archiveGame, cleanSince, endAnalysis, endOf, endTableTalk, lastChatStart, loadGame, saveGame, startOfNewGame, withoutPlans } from "../games/index.js";
+import { gameFolder, gameFolders } from "../profiles/index.js";
+import { gameAt } from "./clock.js";
+import { nextStep, positionLines, sidesLine, speechLine, speechOf, summaryOf, withThought } from "./game-summary.js";
+import { levelText, levelToPlay } from "./levels.js";
+import { closedPage, pageGiven, pageLine } from "./page-link.js";
+import { pastGameLines } from "./past-games.js";
+import { refuseUnseenPosition } from "./play-move.js";
+import { playerLine } from "./profiles.js";
+import { defineCommand } from "./registry.js";
+const newGameInput = z.object({
+    ai_colour: z.enum(["white", "black", "random"]).optional().describe("the colour you play: random draws it; left out with the rest, the page's window asks"),
+    from: z.string().optional().describe("a FEN or a PGN to go on from, instead of the standard position"),
+    clock: z.string().optional().describe("the time control, minutes each and seconds added after each move, such as 10+5 or 3+0; none, or left out, for a game without a clock"),
+    level: z.enum(aiLevels).optional().describe("the facts you, not the player, get: beginner the board and the legal moves, club also the tactical facts, strong also the positional ones, master "
+        + "also the opening book's moves; left out, the last game's, or for the first game the one that suits the player's profile"),
+    replace: z.boolean().default(false).describe("start even though a game is going on: it goes to the archive unfinished"),
+});
+/** A new game against the player, from the standard position or from a FEN or PGN; a game going on is never lost (D-41). */
+export const newGame = defineCommand({
+    name: "new_game",
+    description: "Starts a new game against the player. Without choices it opens the board page's New game window, where the player chooses the colour, the clock "
+        + "and the level; where there is no board page, it tells you to ask them in the chat. With choices it starts the game: only where there is no board page, "
+        + 'or from a FEN or PGN the player gives. Example: new_game {}; new_game {ai_colour: "black", from: "<FEN or PGN>", level: "club"}.',
+    input: newGameInput,
+    alwaysLoad: true,
+    showsGame: true,
+    positionals: ["ai_colour"],
+    run: (input, context) => {
+        const { ai_colour: colour, from, clock, level } = input;
+        if (colour === undefined && from === undefined && clock === undefined && level === undefined) {
+            return askedOnPage(context);
+        }
+        // The game is played on the board page, and chosen in its window (D-85); a position to go on from is what the window cannot set.
+        if (context.page !== undefined && from === undefined) {
+            throw new Error("The player chooses a new game in the board page's New game window: call new_game without choices, which opens it, or gives you its address "
+                + "when nobody has the page open. Nothing changed.");
+        }
+        return startNewGame(input, context, "chat");
+    },
+    format: (result) => "window" in result ? askedLine(result) : startedLines(result),
+});
+/**
+ * Starts the new game with the player's choices: those the AI asked in the chat, or the page's window gave (D-76). Only the chat's is refused on a game
+ * changed since it saw it (D-71): the player who presses New game on the page sees the game there (Federico, round of D-85).
+ */
+export function startNewGame({ ai_colour: colour, from, clock, level: chosen, replace }, context, by) {
+    if (colour === undefined) {
+        throw new Error(from === undefined
+            ? "ai_colour: say the colour you play, white, black or random, with the other choices; or leave them all out for the page's window. Nothing changed."
+            : "ai_colour: say the colour you play from this position, white, black or random. Nothing changed.");
+    }
+    const control = clock === undefined || /^\s*none\s*$/i.test(clock) ? undefined : timeControlFrom(clock);
+    const now = context.now();
+    const folder = gameFolder(context.home());
+    const before = gameAt(folder, now);
+    const going = before !== undefined && endOf(before.game) === undefined ? before : undefined;
+    if (going !== undefined && !replace) {
+        const { moveNumber } = going.game.position;
+        throw new Error(`A game is going on, at move ${moveNumber}: end it with end_game, or call new_game with replace: true, which archives it unfinished. Nothing changed.`);
+    }
+    if (going !== undefined && by === "chat") {
+        refuseUnseenPosition(context, folder);
+    }
+    if (chatToClear(context)) {
+        throw new ChatNotClear();
+    }
+    const ai = colour === "random" ? (context.random() < 0.5 ? "white" : "black") : colour;
+    const level = chosen ?? levelToPlay(context, before);
+    const started = startOfNewGame(folder, now, before);
+    const game = startingGame(from, { ai, level }, started, control);
+    const current = control === undefined
+        ? { game, ai, started: started.toISOString(), talk: [] }
+        : { game, ai, started: started.toISOString(), talk: [], clock: startClock(control, now, context.pageOpen?.() === true) };
+    const archived = before === undefined || (going === undefined && archivedName(folder, before) !== undefined) ? undefined : archiveBefore(folder, before);
+    saveGame(folder, current);
+    endAnalysis(folder);
+    endTableTalk(folder);
+    const past = pastGameLines(folder, remembered);
+    const closed = closedPage(context);
+    const player = playerLine(context);
+    const speech = speechOf(folder, context.language);
+    if (closed !== undefined) {
+        pageGiven(context, current.started);
+    }
+    return {
+        game: withThought(summaryOf(current, now), folder, current),
+        ...(archived === undefined ? {} : { archived: { name: archived, finished: going === undefined } }),
+        past,
+        ...(player === undefined ? {} : { player }),
+        ...(speech === undefined ? {} : { speech }),
+        ...(closed === undefined ? {} : { closedPage: closed }),
+    };
+}
+/** The new game's lines for the AI. */
+function startedLines({ game, archived, past, player, speech, closedPage: closed }) {
+    return [
+        `New game: ${sidesLine(game.ai)}, ${levelText(game.level)}.`,
+        ...(player === undefined ? [] : [player]),
+        ...(speech === undefined ? [] : [speechLine(speech)]),
+        ...(archived === undefined ? [] : [`The game before is in ${archived.name}${archived.finished ? "" : ", unfinished"}.`]),
+        ...(past.length === 0 ? [] : ["Last games with this player (past_games gives more, and their moves):", ...past]),
+        ...positionLines(game),
+        ...(closed === undefined ? [] : [pageLine(closed, true)]),
+        nextStep(game),
+    ].join("\n");
+}
+/**
+ * The New game window opened on the board page, or its address for the player to open it first; a chat to clear refuses it as a new game does (D-57), and
+ * without the page the player is asked in the chat.
+ */
+function askedOnPage(context) {
+    if (chatToClear(context)) {
+        throw new ChatNotClear();
+    }
+    if (context.askNewGame?.() === true) {
+        return { window: "opened" };
+    }
+    if (context.page !== undefined) {
+        return { window: "closed", page: context.page };
+    }
+    throw new Error("There is no board page here: ask the player which colour they want, whether they want a clock and at which level you play, then call new_game with "
+        + "them. Nothing changed.");
+}
+function askedLine({ window, page }) {
+    return window === "opened"
+        ? "The New game window is open on the board page: the player chooses the game there. Don't ask in the chat; end your turn, the doorbell wakes you when "
+            + "the game starts."
+        : `Nobody has the board page open: give the player its address, ${page}, and tell them to start the game there with its New game button. End your turn.`;
+}
+/** The refusal of a new game in a chat that still holds the game before (D-57): the board page says it in the player's language. */
+export class ChatNotClear extends Error {
+    constructor() {
+        super("The game before was played in this chat: ask the player to write /clear here, which empties the chat and keeps the games on disk, then "
+            + "start the new game. A clean chat plays faster and costs less. Nothing changed.");
+    }
+}
+/** How many of the last games new_game recalls. */
+const remembered = 3;
+/** From how many plies a game played in a chat asks for a clean one before the next (D-57): one left after a few moves does not. */
+export const pliesBeforeClearing = 20;
+// A FEN's board: eight ranks of pieces and empty counts.
+const fenPattern = /^[pnbrqkPNBRQK1-8]+(?:\/[pnbrqkPNBRQK1-8]+){7}(?:\s|$)/;
+/**
+ * Whether the chat must be cleared first: the last game begun, in any profile, was played in it at some length, and the host says how chats start (the hook
+ * of Claude Code and Codex, T-85, T-104). Another profile does not clear the chat (D-66), nor a game another chat played, which this one was never shown (D-71).
+ */
+function chatToClear(context) {
+    const start = lastChatStart(context.folder);
+    if (!hostsNotingChats.has(context.host?.() ?? "") || start === undefined) {
+        return false;
+    }
+    const last = gameFolders(context.home()).flatMap((folder) => loadGame(folder) ?? []).sort((one, other) => Date.parse(other.started) - Date.parse(one.started))[0];
+    return last !== undefined && last.started === context.positionSeen?.started && last.game.record.moves.length >= pliesBeforeClearing && !cleanSince(start, last.started);
+}
+// The hosts whose SessionStart hook, written by init, notes how each chat starts: Claude Code and Codex, by the names they give the server.
+const hostsNotingChats = new Set(["claude-code", "codex-mcp-client"]);
+function archiveBefore(folder, before) {
+    try {
+        return archiveGame(folder, before);
+    }
+    catch (error) {
+        throw new Error(`${error.message} Nothing changed.`, { cause: error });
+    }
+}
+/**
+ * The new game: the standard position, or the one a FEN or PGN gives, which must still be going on. Its tags are Chesspal's, the AI's level among them:
+ * an imported game gives its position only.
+ */
+function startingGame(from, { ai, level }, started, control) {
+    const tags = {
+        Event: "Chesspal",
+        Date: pgnDate(started),
+        White: ai === "white" ? "AI" : "Player",
+        Black: ai === "black" ? "AI" : "Player",
+        [levelTag]: level,
+        ...(control === undefined ? {} : { TimeControl: timeControlTag(control) }),
+    };
+    let game;
+    try {
+        const record = from === undefined ? { tags: {}, moves: [] } : importedRecord(from.trim());
+        const fen = record.tags.FEN === undefined ? {} : { SetUp: "1", FEN: record.tags.FEN };
+        game = new Game({ tags: { ...tags, ...fen }, moves: record.moves });
+    }
+    catch (error) {
+        throw new Error(`from: ${error.message} Nothing changed.`);
+    }
+    const end = endOf(game);
+    if (end !== undefined) {
+        throw new Error(`from holds a game already over (${end.result}): give one still going on, or leave from out for a new game. Nothing changed.`);
+    }
+    return game;
+}
+function timeControlFrom(clock) {
+    try {
+        return timeControlOf(clock);
+    }
+    catch (error) {
+        throw new Error(`clock: ${error.message} Nothing changed.`);
+    }
+}
+function importedRecord(from) {
+    if (fenPattern.test(from)) {
+        return { tags: { SetUp: "1", FEN: from }, moves: [] };
+    }
+    const records = readPgn(from);
+    const [record] = records;
+    if (record === undefined || records.length > 1) {
+        throw new Error(`it holds ${records.length} games: give one, in PGN, or a FEN.`);
+    }
+    // Another game's [%plan] and [%mood] comments are not the AI's.
+    return withoutMoods(withoutPlans(record));
+}

package/dist/commands/opening-book.d.ts

@@ -0,0 +1,13 @@
+import { type GameRecord, type Opening } from "../core/index.ts";
+/** 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 declare function openingLine(record: GameRecord): string | 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 declare function knownMoves(fen: string): readonly string[];
+/** How many plies from the start the book knows, to the last before the game left it (D-69); none from another position. */
+export declare function bookPlies(record: GameRecord): number;
+/** 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 declare function bookReaches(fen: string): boolean;
+/** The opening a game reached, ECO and name, without where it left the book: for the games in the archive. */
+export declare function openingName(record: GameRecord): string | undefined;
+/** The last named opening a game reached, and at which ply; none outside the book, or where the build made no index. */
+export declare function bookOpening(record: GameRecord): Opening | undefined;

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,44 @@
+import { type MoveReview } from "../core/index.ts";
+import type { Context } 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 (T-65), 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;
+    /** The AI's badge and note on the player's last move, kept in its comment as the analyst keeps them (D-78). */
+    judged?: MoveReview;
+}
+/**
+ * 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, judged }?: WithMove): MovePlayed;
+/**
+ * Where the game a chat sees stands: the game by its start, none when there is none, and how many plies it has. Not by its folder, which a profile
+ * completed renames (D-71); a game in another profile started at another time.
+ */
+export interface Position {
+    readonly started?: string;
+    readonly plies: number;
+}
+/** 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): Position;
+/**
+ * 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;