chesspal 0.0.1 → 0.1.0

package/dist/server/bell.d.ts

@@ -0,0 +1,60 @@
+import { type IncomingMessage, type ServerResponse } from "node:http";
+/** What the chat hears from the doorbell: one line for whatever the player did, never what, only where to read it. */
+export declare const bellLine = "The player acted on the board page: call status to see it.";
+/**
+ * The doorbell's end on the page's server: the hook of the chat that ended its turn waits here, one at a time, and hears "ring" when the player moves or
+ * writes on the page. A ring no hook heard waits for the next one, while it is still news: the chat, awake, may have read it already.
+ */
+export declare class Bell {
+    private listener;
+    private pending;
+    private busy;
+    private readonly news;
+    private readonly changed;
+    /** `news` says whether a ring no hook heard is still worth waking the chat for; `changed` is told when the chat starts or stops listening. */
+    constructor(news?: () => boolean, changed?: () => void);
+    /** Whether the chat hears the player: in a turn, or waiting for the bell with a hook. */
+    get listening(): boolean;
+    /** The chat calls a tool, so it is in a turn: true when nobody was listening before. */
+    chatCalls(): boolean;
+    /** The player acted on the page: the hook waiting hears it now, or the next one as soon as it comes. */
+    ring(): void;
+    /** A hook waits for the bell, so the chat's turn has ended; the hook before it, of a turn already ended, is let go. */
+    listen(request: IncomingMessage, response: ServerResponse): void;
+    private tellIf;
+}
+/** Whose page answers at a port, for the hook to find its own: the chat's session, the player's folder, and whether a browser has the page open. */
+export declare function bellProbe(folder: string, open?: boolean): BellProbe;
+/** What a page says of itself at `/api/bell?probe`. */
+export interface BellProbe {
+    session: string | null;
+    folder: string;
+    open: boolean;
+}
+/** The ports a folder's page tries first: one in each of a few ranges, by its path, since Windows may reserve a range. The hook looks for it there. */
+export declare function pagePorts(folder: string): number[];
+/** What Codex's Stop hook answers to wake the chat (T-62): its turn goes on with the doorbell's line. */
+export declare const codexBellAnswer: string;
+/**
+ * Reads the hook's input, waits for the bell, and ends the process as the host reads it: for Claude Code's asyncRewake, 2 with the line on stderr; for
+ * Codex's Stop hook, 0 with its answer on stdout, since Windows PowerShell, which runs Codex's hooks, turns an exit code 2 into 1. Else 0, saying nothing.
+ */
+export declare function listen(codex?: boolean): Promise<void>;
+/**
+ * Waits at the page of the hook's chat until the player moves there: true then; false when there is no page to wait at, or another hook takes its place.
+ * The chat's own page is the one with its session; after /clear, which gives the hook a new one, the only page of its folder.
+ */
+export declare function waitForBell(input: string, ports?: number[]): Promise<boolean>;
+/** What the hook heard at the page of its chat, in its folder: the bell, or why not. */
+export type BellHeard = {
+    folder: string;
+    rang: true;
+} | {
+    folder: string;
+    rang: false;
+    why: string;
+};
+/** Waits at the page of the hook's chat, as waitForBell does, and says what it heard. */
+export declare function bellHeard(input: string, ports?: number[]): Promise<BellHeard>;
+/** Adds a line to the log of the hooks that heard no bell, keeping its last lines; a log that cannot be written never stops the hook. */
+export declare function noteSilence(folder: string, why: string, now?: Date): void;

package/dist/server/bell.js

@@ -0,0 +1,209 @@
+// The doorbell for the page (D-47): `chesspal listen`, the Stop hook init writes for Claude Code and Codex (T-62), waits at the page of its chat and, when
+// the player moves or writes there (T-65), tells the chat to call status. It never carries the move, the words or the position: status reads them fresh.
+import { createHash } from "node:crypto";
+import { existsSync, readFileSync } from "node:fs";
+import { get } from "node:http";
+import { join, resolve } from "node:path";
+import { writeAtomically } from "../games/index.js";
+/** What the chat hears from the doorbell: one line for whatever the player did, never what, only where to read it. */
+export const bellLine = "The player acted on the board page: call status to see it.";
+/**
+ * The doorbell's end on the page's server: the hook of the chat that ended its turn waits here, one at a time, and hears "ring" when the player moves or
+ * writes on the page. A ring no hook heard waits for the next one, while it is still news: the chat, awake, may have read it already.
+ */
+export class Bell {
+    listener;
+    pending = false;
+    // The chat is in a turn: it called a tool, or a hook woke it, and its turn has not ended yet. A chat never started, or just cleared, is not.
+    busy = false;
+    news;
+    changed;
+    /** `news` says whether a ring no hook heard is still worth waking the chat for; `changed` is told when the chat starts or stops listening. */
+    constructor(news = () => true, changed = () => undefined) {
+        this.news = news;
+        this.changed = changed;
+    }
+    /** Whether the chat hears the player: in a turn, or waiting for the bell with a hook. */
+    get listening() {
+        return this.busy || this.listener !== undefined;
+    }
+    /** The chat calls a tool, so it is in a turn: true when nobody was listening before. */
+    chatCalls() {
+        const asleep = !this.listening;
+        this.busy = true;
+        this.tellIf(asleep);
+        return asleep;
+    }
+    /** The player acted on the page: the hook waiting hears it now, or the next one as soon as it comes. */
+    ring() {
+        if (this.listener === undefined) {
+            this.pending = true;
+            return;
+        }
+        this.listener.end("ring");
+        this.listener = undefined;
+        this.busy = true;
+    }
+    /** A hook waits for the bell, so the chat's turn has ended; the hook before it, of a turn already ended, is let go. */
+    listen(request, response) {
+        response.writeHead(200, { "Content-Type": "text/plain; charset=utf-8", "Cache-Control": "no-store", "X-Content-Type-Options": "nosniff" });
+        const asleep = !this.listening;
+        const missed = this.pending;
+        this.pending = false;
+        if (missed && this.news()) {
+            response.end("ring");
+            this.busy = true;
+            this.tellIf(asleep);
+            return;
+        }
+        this.busy = false;
+        this.listener?.end("dismissed");
+        this.listener = response;
+        this.tellIf(asleep);
+        request.on("close", () => {
+            if (this.listener === response) {
+                // The hook went without the bell (the chat stopped, cleared or closed): nobody hears the player until the chat calls a tool again.
+                this.listener = undefined;
+                this.tellIf(!this.busy);
+            }
+        });
+    }
+    tellIf(changed) {
+        if (changed) {
+            this.changed();
+        }
+    }
+}
+/** Whose page answers at a port, for the hook to find its own: the chat's session, the player's folder, and whether a browser has the page open. */
+export function bellProbe(folder, open = false) {
+    return { session: process.env.CLAUDE_CODE_SESSION_ID ?? null, folder: resolve(folder), open };
+}
+/** The ports a folder's page tries first: one in each of a few ranges, by its path, since Windows may reserve a range. The hook looks for it there. */
+export function pagePorts(folder) {
+    const offset = createHash("sha256").update(resolve(folder).toLowerCase()).digest()[0] % 10;
+    return [5870, 6870, 7870].map((base) => base + offset);
+}
+/** What Codex's Stop hook answers to wake the chat (T-62): its turn goes on with the doorbell's line. */
+export const codexBellAnswer = JSON.stringify({ decision: "block", reason: bellLine });
+/**
+ * Reads the hook's input, waits for the bell, and ends the process as the host reads it: for Claude Code's asyncRewake, 2 with the line on stderr; for
+ * Codex's Stop hook, 0 with its answer on stdout, since Windows PowerShell, which runs Codex's hooks, turns an exit code 2 into 1. Else 0, saying nothing.
+ */
+export async function listen(codex = false) {
+    let input = "";
+    for await (const chunk of process.stdin) {
+        input += String(chunk);
+    }
+    const heard = await bellHeard(input).catch((error) => ({ folder: chatFolder(hookInput(input)), rang: false, why: `failed: ${error.message}` }));
+    // Codex's turn ends with a hook that heard no bell, and the player's next move on the page wakes nobody: the log keeps why (T-62).
+    if (codex && !heard.rang) {
+        noteSilence(heard.folder, heard.why);
+    }
+    // It ends as soon as it knows: the chat hears the hook only once it ends.
+    if (!heard.rang) {
+        process.exit(0);
+    }
+    else if (codex) {
+        process.stdout.write(`${codexBellAnswer}\n`, () => process.exit(0));
+    }
+    else {
+        process.stderr.write(`${bellLine}\n`, () => process.exit(2));
+    }
+}
+/**
+ * Waits at the page of the hook's chat until the player moves there: true then; false when there is no page to wait at, or another hook takes its place.
+ * The chat's own page is the one with its session; after /clear, which gives the hook a new one, the only page of its folder.
+ */
+export async function waitForBell(input, ports) {
+    return (await bellHeard(input, ports)).rang;
+}
+/** Waits at the page of the hook's chat, as waitForBell does, and says what it heard. */
+export async function bellHeard(input, ports) {
+    const hook = hookInput(input);
+    const folder = chatFolder(hook);
+    const tried = ports ?? pagePorts(folder);
+    const probes = await Promise.all(tried.map(async (port) => ({ port, said: probeOf(await body(port, "/api/bell?probe", probeWait)) })));
+    const ours = probes.flatMap(({ port, said }) => (said !== undefined && samePath(said.folder, folder) ? [{ port, said }] : []));
+    const port = chatPage(ours, hook.session)?.port;
+    if (port === undefined) {
+        const others = probes.flatMap((one) => (one.said === undefined ? [] : [`${one.port} is ${one.said.folder}'s`]));
+        const open = ours.filter(({ said }) => said.open).length;
+        const pages = ours.length > 1 ? `${ours.length} pages of it, none of this chat's session, ${open} open in a browser` : "no page of it";
+        return { folder, rang: false, why: `${pages} at ports ${tried.join(", ")}${others.length > 0 ? `; ${others.join(", ")}` : ""}` };
+    }
+    const said = await body(port, "/api/bell");
+    return said === "ring" ? { folder, rang: true } : { folder, rang: false, why: said === undefined ? `the page at port ${port} did not answer` : `the page at port ${port} said "${said}"` };
+}
+// How long a port may take to say whose page it is: one of this computer answers at once.
+const probeWait = 1000;
+// The log of Codex's hooks that heard no bell, in the chat's folder: its last lines only.
+const silenceLog = "listen.log";
+const silenceLines = 100;
+/** The chat's folder, where its server started: Claude Code names it, and the hook's cwd follows the cd's of the chat. */
+function chatFolder(hook) {
+    return resolve(process.env.CLAUDE_PROJECT_DIR ?? hook.cwd ?? process.cwd());
+}
+/** Adds a line to the log of the hooks that heard no bell, keeping its last lines; a log that cannot be written never stops the hook. */
+export function noteSilence(folder, why, now = new Date()) {
+    const path = join(folder, silenceLog);
+    try {
+        const before = existsSync(path) ? readFileSync(path, "utf8").split("\n").filter((line) => line !== "") : [];
+        writeAtomically(path, `${[...before, `${now.toISOString()} ${why}`].slice(-silenceLines).join("\n")}\n`);
+    }
+    catch {
+        // The log only explains; the hook ends the same.
+    }
+}
+function hookInput(input) {
+    try {
+        const parsed = JSON.parse(input);
+        return {
+            ...(typeof parsed.session_id === "string" ? { session: parsed.session_id } : {}),
+            ...(typeof parsed.cwd === "string" ? { cwd: parsed.cwd } : {}),
+        };
+    }
+    catch {
+        return {};
+    }
+}
+/**
+ * The chat's page among those of its folder: the one of its session; else the only one, or the only one a browser has open, where the player plays. Codex
+ * gives the page no session, and a chat closed may leave its page behind for a while.
+ */
+function chatPage(pages, session) {
+    const open = pages.filter(({ said }) => said.open);
+    return pages.find(({ said }) => session !== undefined && said.session === session) ?? (pages.length === 1 ? pages[0] : open.length === 1 ? open[0] : undefined);
+}
+function probeOf(said) {
+    try {
+        const parsed = said === undefined ? undefined : JSON.parse(said);
+        return parsed === undefined || typeof parsed.folder !== "string"
+            ? undefined
+            : { session: typeof parsed.session === "string" ? parsed.session : null, folder: parsed.folder, open: parsed.open === true };
+    }
+    catch {
+        return undefined;
+    }
+}
+function samePath(one, other) {
+    return process.platform === "win32" ? resolve(one).toLowerCase() === resolve(other).toLowerCase() : resolve(one) === resolve(other);
+}
+/** The body a page of this computer answers with, once it ends; undefined when it does not answer, or not with 200. */
+function body(port, path, wait) {
+    return new Promise((done) => {
+        // A connection of its own: Node's shared one ends a request idle for five seconds, and the doorbell waits for hours.
+        const request = get({ host: "127.0.0.1", port, path, agent: false, ...(wait === undefined ? {} : { timeout: wait }) }, (response) => {
+            let text = "";
+            response.setEncoding("utf8");
+            response.on("data", (chunk) => {
+                text += chunk;
+            });
+            response.on("end", () => done(response.statusCode === 200 ? text : undefined));
+            response.on("error", () => done(undefined));
+        });
+        if (wait !== undefined) {
+            request.on("timeout", () => request.destroy());
+        }
+        request.on("error", () => done(undefined));
+    });
+}

package/dist/server/caller.d.ts

@@ -0,0 +1,10 @@
+import type { Caller } from "../commands/context.ts";
+/** The host as it names itself to the server. */
+export interface Client {
+    name: string;
+    title?: string | undefined;
+}
+/** Who made the call with these metadata: the model and effort the host ties to it, else the host's name; undefined without a host. */
+export declare function callerOf(meta: Record<string, unknown> | undefined, client: Client | undefined, folder: string, wait?: number): Promise<Caller | undefined>;
+/** The model and effort on the transcript's line of a tool call, in the chat's file or its subagents'; Claude Code writes it a few milliseconds late. */
+export declare function lineOfCall(transcript: string, call: string, wait?: number): Promise<Caller | undefined>;

package/dist/server/caller.js

@@ -0,0 +1,99 @@
+// Who makes a tool call (D-81): only what the host ties to that call, never what the AI says of itself nor a setting the chat may have changed (T-113).
+// Codex sends the model and the effort with each call; Claude Code writes them into the chat's transcript, on the line of the call.
+import { closeSync, openSync, readdirSync, readSync, statSync } from "node:fs";
+import { basename, dirname, join } from "node:path";
+import { lastChatStart } from "../games/index.js";
+/** Who made the call with these metadata: the model and effort the host ties to it, else the host's name; undefined without a host. */
+export async function callerOf(meta, client, folder, wait = 50) {
+    const turn = objectOf(meta?.["x-codex-turn-metadata"]);
+    if (typeof turn?.model === "string") {
+        return withEffort(turn.model, turn.reasoning_effort);
+    }
+    const call = meta?.["claudecode/toolUseId"];
+    const transcript = lastChatStart(folder)?.transcript;
+    if (typeof call === "string" && transcript !== undefined) {
+        const found = await lineOfCall(transcript, call, wait);
+        if (found !== undefined) {
+            return found;
+        }
+    }
+    return client === undefined ? undefined : { annotator: client.title ?? client.name, hostOnly: true };
+}
+/** The model and effort on the transcript's line of a tool call, in the chat's file or its subagents'; Claude Code writes it a few milliseconds late. */
+export async function lineOfCall(transcript, call, wait = 50) {
+    for (let attempt = 0; attempt < attempts; attempt++) {
+        for (const file of [transcript, ...subagentFiles(transcript)]) {
+            const found = callerIn(tailOf(file), call);
+            if (found !== undefined) {
+                return found;
+            }
+        }
+        if (attempt < attempts - 1) {
+            await new Promise((done) => setTimeout(done, wait));
+        }
+    }
+    return undefined;
+}
+// Three seconds at most: the line comes 30 or 40 milliseconds after a short call, but over 300 after annotate_game's long one. Nobody waits for it on the
+// AI's clock: annotate_game runs with no game going on, and the AI's move is read after its answer.
+const attempts = 60;
+// The line of a call just made is near the end of its file.
+const tailBytes = 512 * 1024;
+// A subagent's file is one written in the last minute.
+const recentFiles = 60_000;
+function callerIn(text, call) {
+    const marker = `"id":"${call}"`;
+    for (const line of text.split("\n").reverse()) {
+        if (!line.includes(marker)) {
+            continue;
+        }
+        const entry = objectOf(line);
+        const message = objectOf(entry?.message);
+        if (entry?.type === "assistant" && typeof message?.model === "string" && message.model !== "<synthetic>") {
+            return withEffort(message.model, entry.effort);
+        }
+    }
+    return undefined;
+}
+function withEffort(model, effort) {
+    return typeof effort === "string" && effort !== "" ? { annotator: model, effort } : { annotator: model };
+}
+function subagentFiles(transcript) {
+    const folder = join(dirname(transcript), basename(transcript, ".jsonl"), "subagents");
+    try {
+        const since = Date.now() - recentFiles;
+        return readdirSync(folder).filter((name) => name.endsWith(".jsonl")).map((name) => join(folder, name)).filter((file) => statSync(file).mtimeMs >= since);
+    }
+    catch {
+        return [];
+    }
+}
+function tailOf(file) {
+    try {
+        const descriptor = openSync(file, "r");
+        try {
+            const size = statSync(file).size;
+            const length = Math.min(size, tailBytes);
+            const buffer = Buffer.alloc(length);
+            readSync(descriptor, buffer, 0, length, size - length);
+            return buffer.toString("utf8");
+        }
+        finally {
+            closeSync(descriptor);
+        }
+    }
+    catch {
+        return "";
+    }
+}
+function objectOf(value) {
+    if (typeof value === "string") {
+        try {
+            return objectOf(JSON.parse(value));
+        }
+        catch {
+            return undefined;
+        }
+    }
+    return typeof value === "object" && value !== null && !Array.isArray(value) ? value : undefined;
+}

package/dist/server/http.d.ts

@@ -0,0 +1,16 @@
+import type { IncomingMessage, ServerResponse } from "node:http";
+export declare const json = "application/json; charset=utf-8";
+/** Answers a request, with nothing cached, sniffed or referred, and the page's policy unless the headers give another. */
+export declare function send(response: ServerResponse, status: number, type: string, body: string | Buffer, headers?: Record<string, string>): void;
+/** Answers with JSON. */
+export declare function sendJson(response: ServerResponse, status: number, body: unknown): void;
+/** Whether a request sends JSON: a form of another site can post text, never JSON without asking first. */
+export declare function isJson(request: IncomingMessage): boolean;
+/** An object from JSON; undefined for anything else. */
+export declare function jsonOf(text: string | undefined): Record<string, unknown> | undefined;
+/** A text field of a body, trimmed; undefined when it is not text, or empty. */
+export declare function textOf(value: unknown): string | undefined;
+/** A request's body as text, up to a size a move with the player's words never reaches; undefined past it. */
+export declare function bodyOf(request: IncomingMessage): Promise<string | undefined>;
+/** A request's body, up to a limit; undefined past it, or when the request breaks. */
+export declare function bytesOf(request: IncomingMessage, limit: number): Promise<Buffer | undefined>;

package/dist/server/http.js

@@ -0,0 +1,57 @@
+export const json = "application/json; charset=utf-8";
+/** Answers a request, with nothing cached, sniffed or referred, and the page's policy unless the headers give another. */
+export function send(response, status, type, body, headers = {}) {
+    response.writeHead(status, {
+        "Content-Type": type,
+        "Cache-Control": "no-store",
+        "X-Content-Type-Options": "nosniff",
+        "Referrer-Policy": "no-referrer",
+        "Content-Security-Policy": "default-src 'self'",
+        ...headers,
+    });
+    response.end(body);
+}
+/** Answers with JSON. */
+export function sendJson(response, status, body) {
+    send(response, status, json, JSON.stringify(body));
+}
+/** Whether a request sends JSON: a form of another site can post text, never JSON without asking first. */
+export function isJson(request) {
+    return (request.headers["content-type"] ?? "").startsWith("application/json");
+}
+/** An object from JSON; undefined for anything else. */
+export function jsonOf(text) {
+    try {
+        const parsed = text === undefined ? undefined : JSON.parse(text);
+        return typeof parsed === "object" && parsed !== null && !Array.isArray(parsed) ? parsed : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+/** A text field of a body, trimmed; undefined when it is not text, or empty. */
+export function textOf(value) {
+    return typeof value === "string" && value.trim() !== "" ? value.trim() : undefined;
+}
+/** A request's body as text, up to a size a move with the player's words never reaches; undefined past it. */
+export async function bodyOf(request) {
+    return (await bytesOf(request, 4096))?.toString("utf8");
+}
+/** A request's body, up to a limit; undefined past it, or when the request breaks. */
+export function bytesOf(request, limit) {
+    return new Promise((done) => {
+        const chunks = [];
+        let size = 0;
+        request.on("data", (chunk) => {
+            size += chunk.length;
+            if (size > limit) {
+                request.destroy();
+                done(undefined);
+                return;
+            }
+            chunks.push(chunk);
+        });
+        request.on("end", () => done(Buffer.concat(chunks)));
+        request.on("error", () => done(undefined));
+    });
+}

package/dist/server/mcp.d.ts

@@ -0,0 +1,14 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { type Context } from "../commands/context.ts";
+import { type AnyCommand } from "../commands/registry.ts";
+/** What the host reads as the server starts, before any tool: where to begin, and the rule of every move (D-27). Short, since hosts may cut it. */
+export declare const serverInstructions: string;
+/** The MCP server for an AI host: every command of the registry as a tool, with its description and parameters (D-5). */
+export declare function createMcpServer(context?: Context, list?: AnyCommand[]): McpServer;
+/**
+ * Serves the tools over standard input and output, as AI hosts expect: stdout carries the protocol alone, so nothing else may print there. It ends when the
+ * host goes and its input closes, once the calls still running have answered: a move half made would be lost.
+ */
+export declare function startMcpServer(context?: Context, list?: AnyCommand[]): Promise<void>;
+/** The opponent's name for the page, from the host's: Claude Code and the desktop app are Claude, Codex is Codex; another host is unnamed. */
+export declare function opponentOf(host: string | undefined): string | undefined;

package/dist/server/mcp.js

@@ -0,0 +1,179 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { z } from "zod";
+import { aiMove } from "../commands/ai-move.js";
+import { defaultContext } from "../commands/context.js";
+import { commands } from "../commands/index.js";
+import { PositionChanged } from "../commands/play-move.js";
+import { inputProblems, isBoolean } from "../commands/registry.js";
+import { noteAiModel } from "../games/index.js";
+import { gameFolder } from "../profiles/index.js";
+import { version } from "../version.js";
+import { pagePorts } from "./bell.js";
+import { callerOf } from "./caller.js";
+import { chatHasRead, startPage } from "./page.js";
+/** What the host reads as the server starts, before any tool: where to begin, and the rule of every move (D-27). Short, since hosts may cut it. */
+export const serverInstructions = "Chesspal keeps the chess for you: the rules, the board, the clock, the games and the player's memory. Call `status` at the start of every "
+    + "chat. Every move goes through Chesspal's tools: never keep the board in your head or invent a position.";
+/** The MCP server for an AI host: every command of the registry as a tool, with its description and parameters (D-5). */
+export function createMcpServer(context = defaultContext(), list = commands) {
+    const server = new McpServer({ name: "chesspal", version }, { instructions: serverInstructions });
+    // The server keeps what it told the chat, the instructions a tool gives once, and the position it showed: none yet (D-71).
+    context.told ??= new Set();
+    context.positionSeen ??= null;
+    const forOneHost = [];
+    for (const command of list.filter((each) => each.cliOnly !== true)) {
+        const tool = server.registerTool(command.name, toolConfig(command), async (input, extra) => {
+            // Each call knows who makes it, for the commands that write it down (D-81).
+            const caller = () => callerOf(extra._meta, server.server.getClientVersion(), context.folder);
+            const result = await track(runTool(command, input, context, caller));
+            if (command === aiMove && result.isError !== true) {
+                noteTheAi(context, caller);
+            }
+            return result;
+        });
+        if (command.host !== undefined) {
+            tool.disable();
+            forOneHost.push({ host: command.host, tool });
+        }
+    }
+    // A tool for one host is offered once the host has said its name, before it lists the tools.
+    server.server.oninitialized = () => {
+        const host = server.server.getClientVersion()?.name;
+        for (const { tool } of forOneHost.filter((each) => each.host === host)) {
+            tool.enable();
+        }
+    };
+    return server;
+}
+/**
+ * Serves the tools over standard input and output, as AI hosts expect: stdout carries the protocol alone, so nothing else may print there. It ends when the
+ * host goes and its input closes, once the calls still running have answered: a move half made would be lost.
+ */
+export async function startMcpServer(context = defaultContext(), list = commands) {
+    const leave = async () => {
+        // A tool stuck on something that never ends must not keep the server alive once the host has gone.
+        await Promise.race([Promise.allSettled(running), new Promise((done) => setTimeout(done, 5_000))]);
+        // The SDK sends the answer a moment after the call ends: it must reach stdout before the process goes.
+        setImmediate(() => process.stdout.write("", () => process.exit(0)));
+    };
+    process.stdin.on("end", leave);
+    process.stdin.on("close", leave);
+    const server = createMcpServer(context, list);
+    context.host = () => server.server.getClientVersion()?.name;
+    context.page = await pageOf(context, () => opponentOf(context.host?.()));
+    await server.connect(new StdioServerTransport());
+}
+/** The opponent's name for the page, from the host's: Claude Code and the desktop app are Claude, Codex is Codex; another host is unnamed. */
+export function opponentOf(host) {
+    return /claude/i.test(host ?? "") ? "Claude" : /codex/i.test(host ?? "") ? "Codex" : undefined;
+}
+/** The board page of the player's folder, served by this process for as long as the chat lasts (D-47); without it the game goes on in the chat. */
+async function pageOf(context, opponent) {
+    try {
+        const { url, heard, chatCalls, open, askNewGame } = await startPage(context, opponent);
+        // Words the AI is given change no file: the pages hear of them from the commands.
+        context.heard = heard;
+        context.calls = chatCalls;
+        context.pageOpen = open;
+        context.askNewGame = askNewGame;
+        if (!pagePorts(context.folder).includes(Number(new URL(url).port))) {
+            process.stderr.write(`The board page is at ${url}, off its usual ports: the doorbell cannot find it, so moves on the page do not wake the chat.\n`);
+        }
+        return url;
+    }
+    catch (error) {
+        // The host keeps what the server writes on stderr in its logs.
+        process.stderr.write(`${error.message}\n`);
+        return undefined;
+    }
+}
+/**
+ * Who played the AI's move, read once the move has gone back to the chat, and kept in memory (D-82): the AI's card on the page shows it, and the game's
+ * PGN once it ends; a change shows from the next move. A host that ties no model to the call leaves the last one known.
+ */
+function noteTheAi(context, caller) {
+    // Claude Code writes the call's line a few milliseconds late: read after the answer, it costs the AI's clock nothing (D-13).
+    setImmediate(() => {
+        // Nothing that fails here may stop the server: the move is played and answered.
+        caller().then((found) => {
+            if (found === undefined || found.hostOnly === true) {
+                return;
+            }
+            if (noteAiModel(gameFolder(context.home()), { model: found.annotator, ...(found.effort === undefined ? {} : { effort: found.effort }) })) {
+                context.heard?.();
+            }
+        }).catch(() => undefined);
+    });
+}
+// The tool calls still running, which the server waits for before it leaves.
+const running = new Set();
+function track(call) {
+    running.add(call);
+    void call.finally(() => running.delete(call));
+    return call;
+}
+/** Every hint stated, since the spec reads a missing one as the worst case: everything is local, so no tool reaches the open world. */
+function toolConfig(command) {
+    const readOnly = command.readOnly === true;
+    const annotations = { readOnlyHint: readOnly, destructiveHint: command.destructive === true, idempotentHint: readOnly || command.idempotent === true, openWorldHint: false };
+    const meta = command.alwaysLoad ? { "anthropic/alwaysLoad": true } : undefined;
+    // The SDK writes the draft's address in every schema: it says nothing to an AI, and costs tokens in every tool.
+    return { description: command.description, inputSchema: z.looseObject({}).meta({ ...shownInput(command), $schema: undefined }), annotations, _meta: meta };
+}
+async function runTool(command, input, context, caller) {
+    let refused = false;
+    try {
+        if (command.byAgent !== true) {
+            context.calls?.();
+        }
+        const result = await command.run(checkedInput(command, input), { ...context, caller });
+        return { content: [{ type: "text", text: command.format(result, context) }] };
+    }
+    catch (error) {
+        refused = error instanceof PositionChanged;
+        return { content: [{ type: "text", text: error instanceof Error ? error.message : String(error) }], isError: true };
+    }
+    finally {
+        // What the tool read or wrote, the chat has seen: the doorbell rings it only for what changes after, and it may move on the game a tool showed it,
+        // unless that tool was refused for a position it had not seen. An agent's call is not the chat's.
+        if (command.byAgent !== true) {
+            chatHasRead(context, command.showsGame === true && !refused);
+        }
+    }
+}
+// The JSON schema of each command's input, as the SDK would write it from the strict schema: the tool takes any object, and the command checks it, so that
+// what is wrong comes back in words an AI can act on.
+const shownInputs = new WeakMap();
+function shownInput(command) {
+    let shown = shownInputs.get(command);
+    if (shown === undefined) {
+        shown = z.toJSONSchema(command.input.strict(), { target: "draft-7", io: "input" });
+        shownInputs.set(command, shown);
+    }
+    return shown;
+}
+/** The command's input, checked as its schema says; what is wrong comes with every parameter the tool takes, for a call made without the schema. */
+function checkedInput(command, input) {
+    const parsed = command.input.strict().safeParse(withFlags(command, input ?? {}));
+    if (parsed.success) {
+        return parsed.data;
+    }
+    const given = typeof input === "object" && input !== null ? input : {};
+    const shown = shownInput(command);
+    const required = shown.required ?? [];
+    const parameters = Object.entries(shown.properties ?? {}).map(([name, field]) => `- ${name}${required.includes(name) ? "" : " (optional)"}${field.description === undefined ? "" : `: ${field.description}`}`);
+    const again = parameters.length === 0 ? "call it again with no parameters." : `call it again with its parameters.\n${command.name} takes:\n${parameters.join("\n")}`;
+    throw new Error(`${inputProblems(command.name, parsed.error.issues, given, (name) => name)} Nothing changed: ${again}`);
+}
+/** The input with "true" and "false" as flags where the command takes one: some hosts send every value as text. */
+function withFlags(command, input) {
+    if (typeof input !== "object" || input === null) {
+        return input;
+    }
+    const { shape } = command.input;
+    return Object.fromEntries(Object.entries(input).map(([name, value]) => {
+        const field = shape[name];
+        return [name, field !== undefined && isBoolean(field) && (value === "true" || value === "false") ? value === "true" : value];
+    }));
+}