chesspal 0.0.1 → 0.2.0

package/dist/profiles/profiles.js

@@ -0,0 +1,254 @@
+// The player's profiles (D-23): profiles/<id>/ in the data folder (D-71), each with its profile.md, its games and its page settings, and the one in use;
+// there is always one, the first made by Chesspal.
+import { existsSync, mkdirSync, readdirSync, readFileSync, rmSync } from "node:fs";
+import { join } from "node:path";
+import { makeFolder, renameOver, writeAtomically } from "../games/index.js";
+import { readFrontMatter, writeFrontMatter } from "./front-matter.js";
+/** How the player says they play, from who has just learned to who plays tournaments. */
+export const levels = ["learning", "casual", "regular", "tournament"];
+/** Where a rating comes from. */
+export const ratingSites = ["lichess", "chess.com", "fide"];
+/** The lowest and highest rating a profile takes. */
+export const ratingLimits = { lowest: 100, highest: 3500 };
+/** The longest name a profile keeps. */
+export const nameLimit = 40;
+/** The avatars Zoe drew, for a player without an image of their own (D-45). */
+export const drawnAvatars = ["short-hair", "bun", "glasses", "beanie", "beard", "curls", "moustache", "silver-bob", "cat", "owl"];
+/** The profiles in the data folder, by their folders' names. */
+export function listProfiles(root) {
+    return profileIds(root).map((id) => readProfile(root, id));
+}
+/**
+ * Makes the first profile when there is none, named after the system's account and new until the player completes it (D-71). Two processes starting
+ * together make one: the second finds its folder taken.
+ */
+export function ensureProfile(root, account) {
+    const id = freeId(root, slugOf(account));
+    if (profileIds(root).length === 0 && claimed(root, id)) {
+        fillProfile(root, id, { name: account }, true);
+    }
+}
+/** The profile in use: the one active.json names, else the first. */
+export function activeProfile(root) {
+    return readProfile(root, activeIdOf(root));
+}
+/** Where the games are: the folder of the profile in use. */
+export function gameFolder(root) {
+    return profileFolder(root, activeIdOf(root));
+}
+/** A profile's folder. */
+export function profileFolder(root, id) {
+    return join(root, folderName, id);
+}
+/**
+ * Makes a profile, its folder named from the player's name, and puts it in use unless told not to; the one Chesspal made, while new, becomes it instead,
+ * with its games, and its folder takes the player's name too (D-71).
+ */
+export function createProfile(root, fields, use = true) {
+    const id = activeId(root);
+    if (id !== undefined && readProfile(root, id).new === true) {
+        const { level, rating, avatar } = fields;
+        const named = renamed(root, id, fields.name);
+        writeProfile(root, named, { name: fields.name, level, rating, avatar, new: false });
+        return readProfile(root, named);
+    }
+    let made = freeId(root, slugOf(fields.name));
+    // Another process may take the same id between the look and the folder: the next free one, then.
+    while (!claimed(root, made)) {
+        made = freeId(root, slugOf(fields.name));
+    }
+    return fillProfile(root, made, fields, false, use);
+}
+/** Every profile's folder, where games may be. */
+export function gameFolders(root) {
+    return profileIds(root).map((id) => profileFolder(root, id));
+}
+/** Puts a profile in use. */
+export function activateProfile(root, id) {
+    const ids = profileIds(root);
+    if (!ids.includes(id)) {
+        throw new Error(ids.length === 0 ? "There is no profile yet: make one first." : `There is no profile ${id}: the profiles are ${ids.join(", ")}.`);
+    }
+    writeActive(root, id);
+    return readProfile(root, id);
+}
+/** Changes what a profile says of the player, keeping the rest of profile.md as it was written: its other fields and the text below them. */
+export function updateProfile(root, id, changes) {
+    writeProfile(root, id, changes);
+    return readProfile(root, id);
+}
+const folderName = "profiles";
+const profileFile = "profile.md";
+const activeFile = "active.json";
+// Names Windows keeps for devices: no folder may take them.
+const reserved = /^(con|prn|aux|nul|com\d|lpt\d)$/;
+function profileIds(root) {
+    try {
+        return readdirSync(join(root, folderName), { withFileTypes: true }).filter((entry) => entry.isDirectory()).map((entry) => entry.name).sort();
+    }
+    catch {
+        return [];
+    }
+}
+function activeId(root) {
+    const named = activeNamed(root);
+    const ids = profileIds(root);
+    return named !== undefined && ids.includes(named) ? named : ids[0];
+}
+function activeIdOf(root) {
+    const id = activeId(root);
+    if (id === undefined) {
+        throw new Error(`There is no profile in ${join(root, folderName)}: run any Chesspal command, and it makes one.`);
+    }
+    return id;
+}
+/** Takes a profile's folder for this call alone: false when another process has made it already. */
+function claimed(root, id) {
+    makeFolder(join(root, folderName));
+    const folder = profileFolder(root, id);
+    try {
+        mkdirSync(folder);
+        return true;
+    }
+    catch (error) {
+        if (error.code === "EEXIST") {
+            return false;
+        }
+        throw new Error(`${folder} could not be made (${error.message}): check that it is a folder, and can be written.`, { cause: error });
+    }
+}
+/** Writes a profile in the folder this call claimed and puts it in use when asked; on a failure the folder goes, which holds nothing of another's. */
+function fillProfile(root, id, fields, made, use = true) {
+    try {
+        writeProfile(root, id, made ? { ...fields, new: true } : fields);
+        if (use) {
+            writeActive(root, id);
+        }
+    }
+    catch (error) {
+        rmSync(profileFolder(root, id), { recursive: true, force: true });
+        throw error;
+    }
+    return readProfile(root, id);
+}
+/**
+ * The folder of the profile Chesspal made, named after the account, moved to the player's name and put in use; it keeps the account's for a name without
+ * letters or digits, and where it cannot move, as with a file held open in it.
+ */
+function renamed(root, id, name) {
+    const plain = plainName(name);
+    if (plain === "" || id === plain || (id.startsWith(`${plain}-`) && /^\d+$/.test(id.slice(plain.length + 1)))) {
+        return id;
+    }
+    const target = freeId(root, plain);
+    // On Linux and macOS a folder another process made between the look and the move would be replaced: two profiles made in the same instant.
+    try {
+        renameOver(profileFolder(root, id), profileFolder(root, target));
+    }
+    catch {
+        return id;
+    }
+    try {
+        writeActive(root, target);
+    }
+    catch (error) {
+        // Moved back, or the first folder would be put in use in its place.
+        renameOver(profileFolder(root, target), profileFolder(root, id));
+        throw error;
+    }
+    return target;
+}
+function activeNamed(root) {
+    try {
+        const { profile } = JSON.parse(readFileSync(join(root, folderName, activeFile), "utf8"));
+        return typeof profile === "string" && /^[^/\\.][^/\\]*$/.test(profile) ? profile : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+function writeActive(root, id) {
+    writeAtomically(join(root, folderName, activeFile), `${JSON.stringify({ profile: id }, null, 2)}\n`);
+}
+function readProfile(root, id) {
+    const { fields } = readFrontMatter(profileText(root, id));
+    const value = Number(fields.rating);
+    const site = oneOf(ratingSites, fields.site);
+    const level = oneOf(levels, fields.level);
+    const avatar = oneOf(drawnAvatars, fields.avatar);
+    const rated = Number.isInteger(value) && value >= ratingLimits.lowest && value <= ratingLimits.highest && site !== undefined;
+    // A name written by hand is cut as the page and the CLI cut it: the AI reads it.
+    return {
+        id,
+        name: fields.name?.trim().slice(0, nameLimit).trim() || id,
+        ...(level === undefined ? {} : { level }),
+        ...(rated ? { rating: { value, site } } : {}),
+        ...(avatar === undefined ? {} : { avatar }),
+        ...(fields.new === "true" ? { new: true } : {}),
+        ...accountsIn(fields),
+    };
+}
+/** The player's names on the sites, from profile.md's lichess and chesscom lines; none without either. */
+function accountsIn(fields) {
+    const named = (site) => fields[site]?.trim().slice(0, nameLimit).trim() || undefined;
+    const lichess = named("lichess");
+    const chesscom = named("chesscom");
+    if (lichess === undefined && chesscom === undefined) {
+        return {};
+    }
+    return { accounts: { ...(lichess === undefined ? {} : { lichess }), ...(chesscom === undefined ? {} : { chesscom }) } };
+}
+// Writes the fields that change, and keeps the others as the file has them, even those this version does not read.
+function writeProfile(root, id, changes) {
+    const { fields, body } = readFrontMatter(profileText(root, id));
+    const written = { ...fields };
+    if (changes.name !== undefined) {
+        written.name = changes.name;
+    }
+    if ("level" in changes) {
+        written.level = changes.level;
+    }
+    if ("rating" in changes) {
+        written.rating = changes.rating?.value;
+        written.site = changes.rating?.site;
+    }
+    if ("avatar" in changes) {
+        written.avatar = changes.avatar;
+    }
+    if ("accounts" in changes) {
+        written.lichess = changes.accounts?.lichess;
+        written.chesscom = changes.accounts?.chesscom;
+    }
+    if ("new" in changes) {
+        written.new = changes.new === true ? "true" : undefined;
+    }
+    writeAtomically(join(profileFolder(root, id), profileFile), writeFrontMatter(written, body));
+}
+function profileText(root, id) {
+    try {
+        return readFileSync(join(profileFolder(root, id), profileFile), "utf8");
+    }
+    catch {
+        return "";
+    }
+}
+/** A folder's name from the player's name: its plain letters and digits, or player for a name without any. */
+function slugOf(name) {
+    return plainName(name) || "player";
+}
+/** A name in plain letters and digits, lower case, words joined by hyphens; empty for a name without any. */
+function plainName(name) {
+    return name.normalize("NFKD").replace(/\p{M}/gu, "").toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+/, "").slice(0, 32).replace(/-+$/, "");
+}
+function freeId(root, slug) {
+    const taken = (id) => reserved.test(id) || existsSync(profileFolder(root, id));
+    let id = slug;
+    for (let number = 2; taken(id); number++) {
+        id = `${slug}-${number}`;
+    }
+    return id;
+}
+// A value of a list, as a hand may write it: in capitals too.
+function oneOf(values, value) {
+    return values.find((one) => one === value?.toLowerCase());
+}

package/dist/profiles/settings.d.ts

@@ -0,0 +1,12 @@
+/** The page's settings, by name: text, numbers and flags. */
+export type PageSettings = Readonly<Record<string, string | number | boolean>>;
+/** A profile's settings, or undefined when it has none yet, or they cannot be read. */
+export declare function profileSettings(root: string, id: string): PageSettings | undefined;
+/** Whether the player has turned the helps on (D-78), in the settings of the profile whose games are in `folder`: off without them. */
+export declare function helpsIn(folder: string): boolean;
+/** The language of the player of the profile whose games are in `folder`: the page's, or the system's when the page follows the browser. */
+export declare function languageIn(folder: string, systemLanguage: string | undefined): string | undefined;
+/** Saves a profile's settings, over the ones before. */
+export declare function saveProfileSettings(root: string, id: string, settings: PageSettings): void;
+/** Settings from what JSON gave: an object of text, numbers and flags, at most a few dozen; undefined for anything else. */
+export declare function settingsOf(value: unknown): PageSettings | undefined;

package/dist/profiles/settings.js

@@ -0,0 +1,46 @@
+// The page's settings of a profile (D-56): settings.json in its folder, kept as the page sends them; the page checks each one as it reads them.
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import { writeAtomically } from "../games/index.js";
+import { profileFolder } from "./profiles.js";
+/** A profile's settings, or undefined when it has none yet, or they cannot be read. */
+export function profileSettings(root, id) {
+    try {
+        return settingsOf(JSON.parse(readFileSync(join(profileFolder(root, id), fileName), "utf8")));
+    }
+    catch {
+        return undefined;
+    }
+}
+/** Whether the player has turned the helps on (D-78), in the settings of the profile whose games are in `folder`: off without them. */
+export function helpsIn(folder) {
+    return settingsIn(folder)?.helps === true;
+}
+/** The language of the player of the profile whose games are in `folder`: the page's, or the system's when the page follows the browser. */
+export function languageIn(folder, systemLanguage) {
+    const language = settingsIn(folder)?.language;
+    return typeof language === "string" && language !== "auto" ? language : systemLanguage;
+}
+/** Saves a profile's settings, over the ones before. */
+export function saveProfileSettings(root, id, settings) {
+    writeAtomically(join(profileFolder(root, id), fileName), `${JSON.stringify(settings, null, 2)}\n`);
+}
+/** Settings from what JSON gave: an object of text, numbers and flags, at most a few dozen; undefined for anything else. */
+export function settingsOf(value) {
+    if (typeof value !== "object" || value === null || Array.isArray(value)) {
+        return undefined;
+    }
+    const entries = Object.entries(value);
+    const plain = entries.every(([, one]) => ["string", "number", "boolean"].includes(typeof one) && (typeof one !== "string" || one.length <= 64));
+    return plain && entries.length <= 40 ? Object.fromEntries(entries) : undefined;
+}
+const fileName = "settings.json";
+/** The settings of the profile whose games are in `folder`; undefined without them. */
+function settingsIn(folder) {
+    try {
+        return settingsOf(JSON.parse(readFileSync(join(folder, fileName), "utf8")));
+    }
+    catch {
+        return undefined;
+    }
+}

package/dist/server/bell.d.ts

@@ -0,0 +1,68 @@
+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 woken;
+    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 what the page shows of the chat may change: it
+     * starts or stops listening, the doorbell wakes it, its turn ends.
+     */
+    constructor(news?: () => boolean, changed?: () => void);
+    /** Whether the chat is in a turn, as far as the doorbell knows: a chat stopped with Esc stays in it until its next tool. */
+    get inTurn(): boolean;
+    /** Whether the doorbell woke the chat in the turn it is in. */
+    get woke(): boolean;
+    /** 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: 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,225 @@
+// The doorbell for the page (D-47): `chesspal listen`, the Stop hook init writes for Claude Code and Codex, waits at the page of its chat and, when
+// the player moves or writes there, 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;
+    // The doorbell woke the chat in this turn: the player acted on the page, and the chat goes to see it.
+    woken = false;
+    news;
+    changed;
+    /**
+     * `news` says whether a ring no hook heard is still worth waking the chat for; `changed` is told when what the page shows of the chat may change: it
+     * starts or stops listening, the doorbell wakes it, its turn ends.
+     */
+    constructor(news = () => true, changed = () => undefined) {
+        this.news = news;
+        this.changed = changed;
+    }
+    /** Whether the chat is in a turn, as far as the doorbell knows: a chat stopped with Esc stays in it until its next tool. */
+    get inTurn() {
+        return this.busy;
+    }
+    /** Whether the doorbell woke the chat in the turn it is in. */
+    get woke() {
+        return this.woken;
+    }
+    /** 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;
+        this.woken = true;
+        this.changed();
+    }
+    /** 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 missed = this.pending;
+        this.pending = false;
+        if (missed && this.news()) {
+            response.end("ring");
+            this.busy = true;
+            this.woken = true;
+            this.changed();
+            return;
+        }
+        this.busy = false;
+        this.woken = false;
+        this.listener?.end("dismissed");
+        this.listener = response;
+        this.changed();
+        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: 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.
+    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;
+/** 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.
+    }
+}
+/** 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());
+}
+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,21 @@
+import type { Caller } from "../commands/index.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>;
+/** Who in Claude Code made a tool call: the chat itself, or one of its agents by its type. */
+export type CallingAgent = {
+    chat: true;
+} | {
+    agent: string;
+};
+/**
+ * Who in Claude Code made a tool call: the chat, when its line is in the chat's transcript, or the agent whose file has it, by the type Claude Code notes
+ * beside that file (Priya). Undefined when it cannot be told: another host, no chat noted, no line, or no type.
+ */
+export declare function callingAgent(meta: Record<string, unknown> | undefined, folder: string, wait?: number): Promise<CallingAgent | undefined>;
+/** Whether an agent's tool may answer this caller: one of its agents, or a caller that cannot be told, since the tool's description is the first guard. */
+export declare function allowedCaller(caller: CallingAgent | undefined, agents: readonly string[]): boolean;