chesspal 0.0.1 → 0.1.0

package/README.md

@@ -1,5 +1,139 @@
 # Chesspal
 
-Play chess against an AI with a character, and learn with an AI coach that remembers your games and helps you improve.
+Play chess against an AI, or learn with one.
 
-In development: this is a placeholder for the first release.
+You can already play chess with an AI in a chat, but it forgets the position, plays illegal moves, sees no board and remembers nothing of yesterday's
+game. Chesspal is what it lacks: it **keeps the rules, the board, the clock, the games and the memory**; the AI **plays, reasons, judges and talks**. A
+move is legal because Chesspal checked it, not because the AI says so.
+
+Chesspal does not use a chess engine such as Stockfish, in any way: every judgment of a move or a position is the AI's own. Chesspal hands it facts
+instead, which a program finds in microseconds and an AI only by reasoning at length: the legal moves, the pieces attacked and defended, the pins and
+the checks, the positional facts, the opening's name.
+
+## What you can do
+
+- **Play against the AI** on the board page in your browser, and talk with it there or in the chat.
+- **Choose its level**, from beginner to master: the higher, the more facts of the position the AI sees, and the master knows the opening book.
+- **Play with a clock**, with an AI that knows how much time it has left; offer a draw, resign, export the game as PGN.
+- **Keep a profile** for each player at the same computer, with their games.
+
+Coming later: an AI coach that helps you grow, the discursive analysis of your games, exercises chosen on your weak points, a rating worked out from your
+games, and an opponent with a character and moods of its own.
+
+## Status
+
+Chesspal is in early development: the version on npm is a first one to try, and it may change from one release to the next. It works with any AI agent that uses MCP tools and can work with the files on your computer;
+we develop it with Claude Code, and Codex is connected too. Chesspal never uses an API key: the AI runs on your agent's own plan, or on your computer
+with a local model.
+
+## Play
+
+**What you need**
+
+- [Node.js](https://nodejs.org) 22.13 or newer: download the version marked LTS and install it like any program.
+- An AI agent on your computer: [Claude Code](https://code.claude.com/docs/en/setup), in a terminal or in the Code tab of the Claude desktop app, or
+  [Codex](https://developers.openai.com/codex). The AI runs on what you already pay for your agent, such as your Claude or ChatGPT subscription:
+  Chesspal asks for no API key.
+- A terminal, opened after installing Node.js: on Windows, Command Prompt (press Start, type `cmd`, press Enter), since PowerShell refuses npm's
+  commands until its scripts are allowed (there, `npm.cmd` and `chesspal.cmd` work in their place); on a Mac, Terminal, in Applications › Utilities.
+
+**Your first game**
+
+1. **Install Chesspal**:
+
+   ```bash
+   npm install -g chesspal
+   ```
+
+2. **Make a folder to play in**: this makes the folder `chess`, with the few files that tell your agent where Chesspal is and how to play. Any name
+   will do; your games are not kept there but in [one folder for all](#where-your-games-are).
+
+   ```bash
+   chesspal init chess
+   ```
+
+3. **Open your agent in that folder**: type `cd chess`, which takes the terminal into it, then `claude` or `codex`; in the Claude desktop app, choose
+   the folder in the Code tab. The first time, it asks whether to trust the folder: say yes. In Codex, also type `/hooks` and allow Chesspal's two
+   hooks: small helpers that let it notice your moves on the board page.
+
+4. **Say hello**: the AI gives you the link to the board page, a page on your own computer; open it in your browser. No link? Ask the AI for the
+   board. The first time, the page asks who you are: your name, a picture, how well you play.
+
+5. **Ask for a game**: the New game window opens on the page, where you choose your colour, the clock and the AI's level. Play on the board: that is
+   where the game is. 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.
+
+6. **For the next game**, type `/clear` in the chat, or start a new chat: a long chat makes the AI slower and costs you more.
+
+When a game is over, ask the AI to go over it with you: its notes show on the board page, in Analyses. A game you played on another site comes in
+there too: download it from that site as a PGN file and open it in Analyses.
+
+**To update Chesspal**, close the chat, run `npm install -g chesspal` again, then `chesspal init` in your folder: it updates its own lines and keeps
+what you wrote there. In Codex, when `chesspal init` says so, allow Chesspal's hooks again in `/hooks`.
+
+## How it works
+
+Chesspal is an MCP server, a command line, `chesspal`, and a board page, all made from the same commands. `chesspal init` sets up a folder to play in:
+the few files that tell the AI agent where Chesspal is, and its instructions as an opponent. Your profiles, games and analyses live in one folder for
+every folder you play in ([where your games are](#where-your-games-are)), or in the folder `CHESSPAL_HOME` names, for tests. Only Chesspal's commands
+change them: they check every move with [chess.js](https://github.com/jhlywa/chess.js) and write atomically.
+
+## Where your games are
+
+Your players and their games are in one folder, the same whatever folder you open the chat in:
+
+- on Windows, `Documents › My Games › Chesspal`. Explorer may show Documents in your language, such as Documenti. With OneDrive, it is inside
+  OneDrive, which also keeps a copy online;
+- on macOS, `Documents › Chesspal`; on Linux, `Chesspal` in your Documents folder, whatever its name in your language.
+
+The board page says where it is, on its welcome page and in "Who's playing?", and its **Open the folder** button opens it.
+
+**A backup** is a copy of the whole `Chesspal` folder, on a USB stick for example. **To move to another computer**, install Chesspal there and put the
+copied `Chesspal` folder in the same place, replacing the one Chesspal may have made already: your players, their games and a game left unfinished all
+come with it. Copy it with the chat and the board page closed.
+
+## Development
+
+You need Node.js 22.13 or newer.
+
+```bash
+git clone https://github.com/stefanocaronia/chesspal.git
+cd chesspal
+npm install
+npm run build
+npm test
+```
+
+- `npm run lint` checks the formatting and the types, as CI does; `npm run format` formats the code.
+- `npm run page -- <folder>` serves the board page of a player's folder, with the data of `CHESSPAL_HOME` or Documents, to look at it while it is built.
+- `npm run endings` shows the ends of a game on the board: checkmate, resignation, a flag fallen, the draws.
+- `npm run bench` times the commands against their budgets.
+- `npm run smoke`, after the build, packs the package, installs it in a temporary folder and runs it as a player would: its version, `chesspal init`
+  and its MCP server, as CI does.
+
+[AGENTS.md](AGENTS.md) is the guide for development: the layout, the architecture's rules, performance, the coding guidelines. It is written for AI
+coding agents and people alike.
+
+## Credits
+
+- The rules: [chess.js](https://github.com/jhlywa/chess.js), under the BSD 2-Clause license.
+- The openings' names: Lichess's [chess-openings](https://github.com/lichess-org/chess-openings), under CC0.
+- The pieces: the Torretta and Nitida sets are Chesspal's own; cburnett is by Colin M.L. Burnett, under the BSD 3-Clause license.
+  [The piece sets' credits](src/page/pieces/CREDITS.md) name every author, licence and source.
+
+Chesspal ships only original or open-licensed content, and no GPL dependency.
+
+## License
+
+[MIT](LICENSE).
+
+## Development notes
+
+Developed with the help of AI coding agents. Everything is designed, reviewed and tested by the project's human maintainer.
+
+**We encourage everyone to use AI for their own purposes.**\
+The means of production should belong to the people.\
+Fight corporate control of technology, not our right to use it.
+
+---
+
+© 2026 [Stefano Caronia](https://stefanocaronia.it) · [GitHub](https://github.com/stefanocaronia/chesspal)

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

@@ -0,0 +1,2 @@
+/** Reads the hook's input and writes how the chat started; a failure is told on stderr and never stops the chat. */
+export declare function recordChatStart(input?: NodeJS.ReadableStream, folder?: string, now?: Date): Promise<void>;

package/dist/cli/chat-hook.js

@@ -0,0 +1,33 @@
+// `chesspal chat`, the SessionStart hook of Claude Code and Codex (D-57, T-104): it writes how the chat started, new, cleared, resumed or compacted, for new_game to read.
+import { saveChatStart } from "../games/index.js";
+/** Reads the hook's input and writes how the chat started; a failure is told on stderr and never stops the chat. */
+export async function recordChatStart(input = process.stdin, folder = process.cwd(), now = new Date()) {
+    try {
+        const hook = parsed(await textOf(input));
+        saveChatStart(folder, {
+            source: typeof hook.source === "string" ? hook.source : "startup",
+            at: now.toISOString(),
+            ...(typeof hook.session_id === "string" ? { session: hook.session_id } : {}),
+            ...(typeof hook.transcript_path === "string" ? { transcript: hook.transcript_path } : {}),
+        });
+    }
+    catch (error) {
+        process.stderr.write(`Chesspal could not note how the chat started: ${error.message}\n`);
+    }
+}
+async function textOf(input) {
+    let text = "";
+    for await (const chunk of input) {
+        text += String(chunk);
+    }
+    return text;
+}
+function parsed(text) {
+    try {
+        const value = JSON.parse(text);
+        return typeof value === "object" && value !== null ? value : {};
+    }
+    catch {
+        return {};
+    }
+}

package/dist/cli/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/cli/cli.js

@@ -0,0 +1,28 @@
+#!/usr/bin/env node
+import { runCommandLine } from "./command-line.js";
+const args = process.argv.slice(2);
+// "chesspal mcp" turns the process into a server for an AI host, "chesspal listen" into the doorbell of Claude Code, or of Codex with --codex,
+// "chesspal chat" notes how the chat started; everything else is a command.
+if (args.length === 1 && args[0] === "mcp") {
+    // The server and its SDK load only here: every other command starts faster without them.
+    const { startMcpServer } = await import("../server/mcp.js");
+    await startMcpServer();
+}
+else if (args[0] === "listen" && (args.length === 1 || (args.length === 2 && args[1] === "--codex"))) {
+    const { listen } = await import("../server/bell.js");
+    await listen(args[1] === "--codex");
+}
+else if (args.length === 1 && args[0] === "chat") {
+    const { recordChatStart } = await import("./chat-hook.js");
+    await recordChatStart();
+}
+else {
+    const { output, exitCode } = await runCommandLine(args);
+    if (exitCode === 0) {
+        console.log(output);
+    }
+    else {
+        console.error(output);
+    }
+    process.exitCode = exitCode;
+}

package/dist/cli/command-line.d.ts

@@ -0,0 +1,8 @@
+import { type Context } from "../commands/context.ts";
+import { type AnyCommand } from "../commands/registry.ts";
+export interface CommandLineResult {
+    output: string;
+    exitCode: number;
+}
+/** The `chesspal` command line: finds the command, validates its input, runs it and renders the result. */
+export declare function runCommandLine(argv: string[], context?: Context, list?: AnyCommand[]): Promise<CommandLineResult>;

package/dist/cli/command-line.js

@@ -0,0 +1,178 @@
+import { parseArgs } from "node:util";
+import { defaultContext } from "../commands/context.js";
+import { commands } from "../commands/index.js";
+import { baseType, commandLineFieldProblem, inputProblems, isBoolean, isList, takesNumbers } from "../commands/registry.js";
+import { version } from "../version.js";
+// The commands that exist only on the command line: cli.ts starts the server, the doorbell or the chat's note, 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.";
+/** 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;
+    if (commandName === undefined || commandName === "--help" || commandName === "-h") {
+        return success(generalHelp(list));
+    }
+    if (commandName === "--version" || commandName === "-v") {
+        return success(version);
+    }
+    if (commandName === "mcp") {
+        // A host that adds options to it would get this text instead of the protocol: it must see the failure.
+        const help = `chesspal mcp\n\n${mcpDescription}`;
+        return args.length === 0 || args.includes("--help") || args.includes("-h") ? success(help) : failure(`chesspal mcp takes no options: ${args.join(" ")}.\n\n${help}`);
+    }
+    if (commandName === "listen") {
+        const help = `chesspal listen [--codex]\n\n${listenDescription}`;
+        const known = args.every((arg) => ["--codex", "--help", "-h"].includes(arg));
+        return known ? success(help) : failure(`chesspal listen takes only --codex: ${args.join(" ")}.\n\n${help}`);
+    }
+    if (commandName === "chat") {
+        const help = `chesspal chat\n\n${chatDescription}`;
+        return args.length === 0 || args.includes("--help") || args.includes("-h") ? success(help) : failure(`chesspal chat takes no options: ${args.join(" ")}.\n\n${help}`);
+    }
+    const command = list.find((candidate) => candidate.name === commandName);
+    if (!command) {
+        return failure(`Unknown command "${commandName}".\n\n${generalHelp(list)}`);
+    }
+    if (args.includes("--help") || args.includes("-h")) {
+        return success(commandHelp(command));
+    }
+    try {
+        return success(await runCommand(command, args, context));
+    }
+    catch (error) {
+        return failure(error instanceof Error ? error.message : String(error));
+    }
+}
+async function runCommand(command, args, context) {
+    const { input, asJson } = readArguments(command, args);
+    const parsed = command.input.safeParse(input);
+    if (!parsed.success) {
+        const positionals = command.positionals ?? [];
+        const written = (name) => (positionals.includes(name) ? `<${name}>` : `--${name}`);
+        throw refused(command, inputProblems(command.name, parsed.error.issues, input, written));
+    }
+    const result = await command.run(parsed.data, context);
+    return asJson ? JSON.stringify(result, null, 2) : command.format(result, context);
+}
+/** An input refused, in the words the MCP server uses (inputProblems), with the command's usage. */
+function refused(command, problems) {
+    return new Error(`${problems} Nothing changed.\nUsage: ${usage(command)}\nRun \`chesspal ${command.name} --help\` for its options.`);
+}
+/** The command line's own refusals, from parseArgs, in the same words: an unknown option is a parameter the command does not have. */
+function parsedArguments(command, config) {
+    try {
+        return parseArgs(config);
+    }
+    catch (error) {
+        const { code, message } = error;
+        const option = /'(-[^' ]+)/.exec(message)?.[1] ?? "";
+        if (code === "ERR_PARSE_ARGS_UNKNOWN_OPTION") {
+            // A positional written as an option: the command has it, in another place.
+            const name = option.replace(/^-+/, "");
+            throw refused(command, command.positionals?.includes(name) === true
+                ? `Give ${name} as <${name}>, without ${option}.`
+                : inputProblems(command.name, [{ code: "unrecognized_keys", keys: [option], path: [], message }], {}, (key) => key));
+        }
+        throw refused(command, message.endsWith("argument missing") ? `${option} needs a value.` : `${message}${message.endsWith(".") ? "" : "."}`);
+    }
+}
+function readArguments(command, args) {
+    const positionals = command.positionals ?? [];
+    const options = { json: { type: "boolean" } };
+    for (const [name, field] of inputFields(command)) {
+        const problem = commandLineFieldProblem(command.name, name, positionals.includes(name));
+        if (problem !== undefined) {
+            throw new Error(problem);
+        }
+        if (!positionals.includes(name)) {
+            options[name] = { type: isBoolean(field) ? "boolean" : "string", multiple: isList(field) };
+        }
+    }
+    // A flag is turned off as --no-hidden, as the MCP server takes hidden: false.
+    const parsed = parsedArguments(command, { args, options, allowPositionals: true, allowNegative: true, strict: true, tokens: true });
+    const extra = parsed.positionals.slice(positionals.length);
+    if (extra.length > 0) {
+        // A text given in several words: quote it. A word from a list is not a text.
+        const last = positionals.at(-1);
+        const freeText = last !== undefined && baseType(command.input.shape[last]) === "string";
+        const quoted = parsed.positionals.slice(positionals.length - 1).join(" ");
+        throw refused(command, `Unexpected argument: ${extra.join(" ")}.${freeText ? ` Put a value with spaces in quotes, such as "${quoted}".` : ""}`);
+    }
+    checkRepeatedOptions(command, parsed.tokens, options);
+    const input = {};
+    for (const [name, value] of Object.entries(parsed.values)) {
+        if (name !== "json") {
+            input[name] = value;
+        }
+    }
+    positionals.forEach((name, index) => {
+        if (parsed.positionals[index] !== undefined) {
+            input[name] = parsed.positionals[index];
+        }
+    });
+    // The command line reads every value as text: a field that takes numbers gets them, and a text that is no number stays, for the schema to refuse.
+    for (const [name, field] of inputFields(command)) {
+        const value = input[name];
+        if (value !== undefined && takesNumbers(field)) {
+            input[name] = Array.isArray(value) ? value.map(number) : number(value);
+        }
+    }
+    return { input, asJson: parsed.values.json === true };
+}
+function number(value) {
+    return typeof value === "string" && value.trim() !== "" && Number.isFinite(Number(value)) ? Number(value) : value;
+}
+/** An option that takes one value must not be given twice: the first value would be lost without a word. */
+function checkRepeatedOptions(command, tokens, options) {
+    const given = [];
+    for (const token of tokens) {
+        if (token.kind !== "option" || token.name === undefined || options[token.name]?.multiple === true) {
+            continue;
+        }
+        if (given.includes(token.name)) {
+            throw refused(command, `Give --${token.name} only once.`);
+        }
+        given.push(token.name);
+    }
+}
+function inputFields(command) {
+    return Object.entries(command.input.shape);
+}
+/** The commands, each with the first sentence of its description. */
+function generalHelp(list) {
+    const width = Math.max("listen".length, ...list.map((command) => command.name.length));
+    const line = (name, description) => `  ${name.padEnd(width)} ${firstSentence(description)}`;
+    return [
+        `chesspal ${version}`,
+        "",
+        "Commands:",
+        ...list.map((command) => line(command.name, command.description)),
+        line("mcp", mcpDescription),
+        line("listen", listenDescription),
+        line("chat", chatDescription),
+        "",
+        "Run `chesspal <command> --help` for its options.",
+    ].join("\n");
+}
+function commandHelp(command) {
+    const positionals = command.positionals ?? [];
+    const optionLines = inputFields(command).map(([name, field]) => {
+        const flag = positionals.includes(name) ? `<${name}>` : `--${name}${isBoolean(field) ? "" : " <value>"}${isList(field) ? "..." : ""}`;
+        return `  ${flag.padEnd(20)} ${field.description ?? ""}`;
+    });
+    return [usage(command), "", command.description, "", ...optionLines, `  ${"--json".padEnd(20)} print the result as JSON`].join("\n");
+}
+function usage(command) {
+    return ["chesspal", command.name, ...(command.positionals ?? []).map((name) => `<${name}>`), "[options]"].join(" ");
+}
+function firstSentence(text) {
+    const end = text.search(/[.!?](\s|$)/);
+    return end === -1 ? text : text.slice(0, end + 1);
+}
+function success(output) {
+    return { output, exitCode: 0 };
+}
+function failure(output) {
+    return { output, exitCode: 1 };
+}

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

@@ -0,0 +1,37 @@
+import { z } from "zod";
+import { type MovePlayed } from "./game-summary.ts";
+/** The AI's move, with its plan, kept hidden (D-29), and its comment for the player when it has something to say (D-12, D-54). */
+export declare const aiMove: import("./registry.ts").Command<z.ZodObject<{
+    move: z.ZodString;
+    plan: z.ZodString;
+    comment: z.ZodOptional<z.ZodString>;
+    badge: z.ZodOptional<z.ZodEnum<{
+        brilliant: "brilliant";
+        great: "great";
+        best: "best";
+        excellent: "excellent";
+        good: "good";
+        inaccuracy: "inaccuracy";
+        mistake: "mistake";
+        miss: "miss";
+        blunder: "blunder";
+    }>>;
+    note: z.ZodOptional<z.ZodString>;
+    arrows: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    squares: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    offer_draw: z.ZodOptional<z.ZodBoolean>;
+    mood: z.ZodOptional<z.ZodEnum<{
+        neutral: "neutral";
+        happy: "happy";
+        surprised: "surprised";
+        worried: "worried";
+        thoughtful: "thoughtful";
+        sad: "sad";
+    }>>;
+}, z.core.$strip>, Played>;
+/** The AI's move, the agent that thinks on the player's time when the host runs one (D-72), and whether the player sees no board page, so the AI copies the board (D-85). */
+type Played = MovePlayed & {
+    ponder?: string;
+    board?: true;
+};
+export {};

package/dist/commands/ai-move.js

@@ -0,0 +1,92 @@
+import { z } from "zod";
+import { badges, boardText, drawingsText, moods, moodTag } from "../core/index.js";
+import { commentWithPlan, talkLimits } from "../games/index.js";
+import { hasPonderAgent, ponderAgentFor } from "../host-files/index.js";
+import { gameFolder, helpsIn } from "../profiles/index.js";
+import { arrowsInput, drawingsOf, noteInput, squaresInput } from "./drawings.js";
+import { closingLines, moveLines, shownMove } from "./game-summary.js";
+import { playMove, refuseUnseenPosition } from "./play-move.js";
+import { defineCommand, sentence } from "./registry.js";
+import { give, waitingWords } from "./say.js";
+// The badges the opponent gives: the book's is Chesspal's, never its own judgment (D-69).
+const judgments = badges.filter((badge) => badge !== "book");
+/** The AI's move, with its plan, kept hidden (D-29), and its comment for the player when it has something to say (D-12, D-54). */
+export const aiMove = defineCommand({
+    name: "ai_move",
+    description: "Plays your move, with your plan, hidden from the player, and a comment for them only when there is something to say: a capture, a move of theirs "
+        + "worth a word, words of theirs to answer; as a player at a tournament, never revealing your plans or threats unless the helps are on, and never the "
+        + "player's best move. When no board page is open, it answers with the board for your message. "
+        + 'Example: ai_move {move: "d5", plan: "After exd5 Na5, chase the bishop on c4.", comment: "An old favourite of mine."}.',
+    input: z.object({
+        move: z.string().min(1).describe("your move, in SAN (Nf3, exd5, O-O, e8=Q) or as squares (g1f3, e7e8q)"),
+        plan: sentence(200).describe("your plan, in one sentence: kept for you, hidden from the player"),
+        comment: sentence(talkLimits.aiHelps).optional().describe(`your words for the player, in one sentence of ${talkLimits.ai} characters at most, only when there is something to say: pieces and moves in words ("your `
+            + `knight takes on f6"), a move you write with the pieces' figurines, as the tools show it (♞xf6+ for Nxf6+); your plans and threats only with the helps on, and then as long as a note of ${talkLimits.aiHelps} `
+            + "characters, to teach; **two asterisks** put a word or two in bold on the page"),
+        badge: z.enum(judgments).optional().describe("only with the helps on: your badge on the player's last move, as chess.com names them, only on a move that stands out (a mistake, a miss, a fine find), "
+            + "never on a routine one"),
+        note: noteInput.optional().describe("only with the helps on: why, on the player's last move, in a sentence or two"),
+        arrows: arrowsInput.describe("only with the helps on: arrows on the board after your move, to show what your comment says, never your move itself: Rf2e1; G green: the better move or "
+            + "the good idea; R red: a threat or the mistake; Y yellow: another way; B blue: a plan"),
+        squares: squaresInput.describe("only with the helps on: squares to mark after your move, as PGN's %csl writes them: Rf2; colours as for arrows"),
+        offer_draw: z.boolean().optional().describe("true offers the player a draw with this move: it stands until their move"),
+        mood: z.enum(moods).optional().describe("how you feel, on a move where the game turns for you: your face on the board page shows it for three of your moves, this one included (a surprise for this one "
+            + "only), then turns neutral by itself"),
+    }),
+    alwaysLoad: true,
+    showsGame: true,
+    positionals: ["move"],
+    run: ({ move, plan, comment, offer_draw: offerDraw = false, mood, badge, note, arrows, squares }, context) => {
+        const folder = gameFolder(context.home());
+        refuseUnseenPosition(context, folder);
+        refuseWithoutHelps(folder, { comment, badge, note, arrows, squares });
+        const drawings = drawingsOf(arrows, squares);
+        // The player's words are read before the move, which would count as the answer to them; a move refused leaves them for the next call.
+        const waiting = waitingWords(context);
+        const words = [commentWithPlan(comment, plan), drawingsText(drawings), mood === undefined ? "" : moodTag(mood)].filter((part) => part !== "").join(" ");
+        const played = playMove(folder, context.now(), "ai", move, (message, legal) => `${message} Legal: ${legal.join(" ")}. Nothing changed.`, {
+            comment: words,
+            offerDraw,
+            ...(badge === undefined && note === undefined ? {} : { judged: { ...(badge === undefined ? {} : { badge }), ...(note === undefined ? {} : { note }) } }),
+        });
+        const agent = ponderAgent(context, played);
+        const board = context.pageOpen?.() === true ? {} : { board: true };
+        return { ...played, words: give(context, waiting), ...(agent === undefined ? {} : { ponder: agent }), ...board };
+    },
+    format: (result) => {
+        // The mood the AI has just given is not told back: player_move and status tell it while it lasts (Priya, round of T-107).
+        const game = { ...result.game };
+        delete game.mood;
+        // The board goes before the player's words and the next step, which stays the last line.
+        return [
+            `Played ${shownMove(result.move)}.`,
+            ...moveLines({ ...result, game }),
+            ...(result.board === true ? ["No board page is open: copy this board into your message.", boardText(result.game.fen)] : []),
+            ...(result.ponder === undefined ? [] : [ponderLine(result.ponder)]),
+            ...closingLines(result.game, result.words),
+        ].join("\n");
+    },
+});
+/** A comment as long as a note, a badge, a note and drawings, only with the helps on (D-78): the player who has them off plays as at a tournament. */
+function refuseWithoutHelps(folder, { comment, badge, note, arrows, squares }) {
+    const asked = [
+        badge === undefined && note === undefined ? "" : "without badge and note",
+        arrows === undefined && squares === undefined ? "" : "without arrows and squares",
+        comment === undefined || comment.length <= talkLimits.ai ? "" : `with the comment in ${talkLimits.ai} characters at most`,
+    ].filter((part) => part !== "");
+    if (asked.length > 0 && !helpsIn(folder)) {
+        throw new Error(`The player has the helps off: play ${asked.join(", ")}. Nothing changed.`);
+    }
+}
+/** The agent to start after the move: in Claude Code, in a folder init set up with it, while the game goes on (D-72). */
+function ponderAgent(context, played) {
+    if (context.host?.() !== "claude-code" || played.game.end !== undefined) {
+        return undefined;
+    }
+    const agent = ponderAgentFor(played.game.level);
+    return hasPonderAgent(context.folder, agent) ? agent : undefined;
+}
+/** How to start the agent, and that the player sees nothing of it: its end needs no answer either. */
+function ponderLine(agent) {
+    return `Think on the player's time: start the ${agent} agent in the background with the prompt "Ponder."; write nothing about it in the chat, now or when it ends.`;
+}

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

@@ -0,0 +1,20 @@
+import { z } from "zod";
+import { type GameSummary } from "./game-summary.ts";
+interface Said {
+    /** The game, none when the AI spoke before the first (D-77). */
+    game?: GameSummary;
+    words: string[];
+}
+/** The AI's words on the board page without a move (T-65), read only there, on the player's time: an answer, or a word it has to say (D-54, D-72). */
+export declare const aiSay: import("./registry.ts").Command<z.ZodObject<{
+    text: z.ZodString;
+    mood: z.ZodOptional<z.ZodEnum<{
+        neutral: "neutral";
+        happy: "happy";
+        surprised: "surprised";
+        worried: "worried";
+        thoughtful: "thoughtful";
+        sad: "sad";
+    }>>;
+}, z.core.$strip>, Said>;
+export {};

package/dist/commands/ai-say.js

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