herdrchat 1.0.0 → 1.1.1

package/lib/chats/telegram/format.mjs

@@ -0,0 +1,83 @@
+// The core's markdown, as Telegram's HTML parse mode shows it (core.telegram.org/bots/api,
+// "Formatting options"): only b, i, code, pre, a and blockquote are used; every other
+// <, > and & is escaped. Text is cut so each piece stays under the 4096 characters a
+// message may hold after parsing.
+const LIMIT = 3800; // room for the tags around a piece
+
+export const escapeHtml = (text) => text.replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;');
+
+// Inline marks on one line of plain text (not inside a code block).
+function inline(line) {
+  const codes = [];
+  let s = line.replace(/`([^`\n]+)`/g, (_, c) => `\u0000${codes.push(c) - 1}\u0000`);
+  s = escapeHtml(s);
+  s = s.replace(/\[([^\]\n]+)\]\((https?:\/\/[^)\s]+)\)/g, (_, text, url) => `<a href="${url.replace(/"/g, '&quot;')}">${text}</a>`);
+  s = s.replace(/\*\*([^*\n]+)\*\*/g, '<b>$1</b>');
+  s = s.replace(/(^|[^\w*])_([^_\n]+)_(?=$|[^\w])/g, '$1<i>$2</i>');
+  s = s.replace(/\\([\\`*_[\]#>~|])/g, '$1'); // the core's escapes: the mark itself
+  return s.replace(/\u0000(\d+)\u0000/g, (_, i) => `<code>${escapeHtml(codes[Number(i)])}</code>`);
+}
+
+export function toHtml(markdown) {
+  const out = [];
+  let fence = null; // lines of the open code block
+  let quote = null; // lines of the open > quote
+  const endQuote = () => {
+    if (quote) out.push(`<blockquote>${quote.join('\n')}</blockquote>`);
+    quote = null;
+  };
+  for (const line of (markdown || '').split('\n')) {
+    if (/^\s*```/.test(line)) {
+      if (fence) {
+        out.push(`<pre>${escapeHtml(fence.join('\n'))}</pre>`);
+        fence = null;
+      } else {
+        endQuote();
+        fence = [];
+      }
+      continue;
+    }
+    if (fence) {
+      fence.push(line);
+      continue;
+    }
+    const q = line.match(/^> ?(.*)$/);
+    if (q) {
+      (quote ||= []).push(inline(q[1]));
+      continue;
+    }
+    endQuote();
+    out.push(inline(line));
+  }
+  if (fence) out.push(`<pre>${escapeHtml(fence.join('\n'))}</pre>`);
+  endQuote();
+  return out.join('\n');
+}
+
+// Markdown cut on line boundaries into pieces of at most `limit` characters; a code
+// block cut in two is closed and opened again, so each piece converts on its own.
+export function split(markdown, limit = LIMIT) {
+  const pieces = [];
+  let current = [];
+  let size = 0;
+  let open = false;
+  const flush = () => {
+    if (!current.length) return;
+    pieces.push(open ? [...current, '```'].join('\n') : current.join('\n'));
+    current = open ? ['```'] : [];
+    size = current.length ? 4 : 0;
+  };
+  for (const raw of (markdown || '').split('\n')) {
+    for (let line = raw; ; ) {
+      const piece = line.length > limit ? line.slice(0, limit) : line;
+      if (size + piece.length + 1 > limit && current.length) flush();
+      current.push(piece);
+      size += piece.length + 1;
+      if (/^\s*```/.test(piece)) open = !open;
+      if (line.length <= limit) break;
+      line = line.slice(limit);
+    }
+  }
+  if (current.length) pieces.push(current.join('\n'));
+  return pieces.length ? pieces : [''];
+}

package/lib/chats/telegram/index.mjs

@@ -0,0 +1,411 @@
+// herdrchat's Telegram side. A bot cannot make groups (no such Bot API method), so each
+// herdr-app tab is a topic in your private chat with the bot (topic mode must be on in
+// @BotFather; getMe says has_topics_enabled), and the chat's main thread is the direct
+// chat: the overview and the commands. Everything the bot posts is silent (a
+// notification without sound); `ring` sends a short reply that does sound, for "needs
+// you" and "done". The core (lib/core/engine.mjs) calls only what is returned here; the
+// contract is lib/chats/contract.mjs.
+//
+// What Telegram does differently, and what stands in:
+//   ended rooms   closeForumTopic is documented for supergroups only, so an ended
+//                 topic's name gets a 🔚 in front, taken off when it is live again
+//   images        a message cannot hold one, so each goes as its own photo after the text
+//   buttons       callback_data holds 64 bytes, so a button carries a short id and the
+//                 dialog it answers is kept here
+//   a free answer no text box on a message: you type the answer in the topic
+//   pin           a topic cannot be pinned; nothing is done
+import fs from 'node:fs';
+import { createClient } from './client.mjs';
+import { escapeHtml, split, toHtml } from './format.mjs';
+
+export const requires = ['TELEGRAM_BOT_TOKEN'];
+
+const POLL_SECONDS = 50;
+const RETRY_MS = 3000;
+const ENDED_MARK = '🔚 ';
+const NAME_MAX = 128;
+const BUTTON_TEXT = 60;
+const BUTTONS_KEPT = 300;
+const WORKING_EMOJI = '👀';
+const DONE_EMOJI = '👌';
+// the topic icon colors Telegram allows (createForumTopic icon_color), one per space
+const ICON_COLORS = [7322096, 16766590, 13338331, 9367192, 16749490, 16478047];
+const STATES = { blocked: '⚠️', error: '🔴', working: '⌛️', done: '✅', idle: '❓' };
+const RANK = { blocked: 0, error: 1, working: 2, done: 3, idle: 4 };
+const COMMANDS = [
+  { command: 'ls', description: 'a new overview of every terminal' },
+  { command: 'new', description: '<session> <space>/<tab> [command]: start a terminal' },
+  { command: 'kill', description: '<session> <address>: end a terminal' },
+  { command: 'screen', description: 'in a topic: its terminal\'s screen' },
+  { command: 'answer', description: 'in a topic: <text> answers what it waits on' },
+  { command: 'esc', description: 'in a topic: press Esc' },
+  { command: 'history', description: 'in a topic: the conversation so far, as a file' },
+];
+
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+const inSpaces = (set, space) => set.all || set.spaces.includes(space);
+const spaceOfName = (name) => (name || '').split(' / ')[0];
+const cut = (text, max) => (text.length > max ? `${text.slice(0, max - 1)}…` : text);
+
+export function create({ cfg, store, log, logWarn, logError }) {
+  const env = cfg.env || {};
+  const owner = String(env.TELEGRAM_OWNER_ID || '').trim();
+  const tg = createClient(env.TELEGRAM_BOT_TOKEN, { log: logWarn });
+  const { read, write } = store;
+  let username = '';
+
+  // ---------- sending ----------
+
+  // Images a post holds (from `image`) are kept here until the post goes out; the text
+  // carries a mark where each was.
+  const images = new Map();
+  let imageN = 0;
+  const IMAGE_MARK = /⁣img(\d+)⁣/g;
+  function takeImages(markdown) {
+    const found = [...(markdown || '').matchAll(IMAGE_MARK)].map((m) => m[1]);
+    return { text: (markdown || '').replace(IMAGE_MARK, '').replace(/\n{3,}/g, '\n\n').trim(), found };
+  }
+  async function sendImages(room, ids) {
+    let last = null;
+    for (const id of ids) {
+      const buffer = images.get(id);
+      if (!buffer) continue;
+      images.delete(id);
+      last = String((await tg.sendPhoto(owner, room, buffer)).message_id);
+    }
+    return last;
+  }
+
+  // HTML that Telegram refuses (an entity it cannot parse) goes again as plain text.
+  async function sendText(chatId, threadId, html, plain, { silent = true, extra = {} } = {}) {
+    const base = { chat_id: chatId, ...(threadId ? { message_thread_id: Number(threadId) } : {}), disable_notification: silent, link_preview_options: { is_disabled: true }, ...extra };
+    try {
+      return await tg.queued('sendMessage', { ...base, text: html || '(empty)', parse_mode: 'HTML' });
+    } catch (err) {
+      if (err.code !== 400 || !/parse|entit/i.test(err.message)) throw err;
+      logWarn(`telegram: HTML refused, sent as text (${err.message})`);
+      return tg.queued('sendMessage', { ...base, text: plain || '(empty)' });
+    }
+  }
+
+  async function post(room, markdown) {
+    const { text, found } = takeImages(markdown);
+    let last = null;
+    if (text) for (const piece of split(text)) last = String((await sendText(owner, room, toHtml(piece), piece)).message_id);
+    return (await sendImages(room, found)) || last;
+  }
+
+  const lookHtml = ({ title, markdown }) => `<b>${escapeHtml(title)}</b>\n\n${toHtml(markdown)}`;
+
+  async function postCard(room, look) {
+    const { text, found } = takeImages(look.markdown);
+    const message = String((await sendText(owner, room, lookHtml({ ...look, markdown: text }), `${look.title}\n\n${text}`)).message_id);
+    await sendImages(room, found);
+    return message;
+  }
+
+  // An edit that changes nothing is refused by Telegram as "not modified": that is fine.
+  async function edit(message, html, extra = {}) {
+    try {
+      await tg.queued('editMessageText', { chat_id: owner, message_id: Number(message), text: html, parse_mode: 'HTML', link_preview_options: { is_disabled: true }, ...extra });
+    } catch (err) {
+      if (!/not modified/i.test(err.message)) throw err;
+    }
+  }
+
+  // The room an edited card is in is not known here, so images added to it go to the
+  // room the card was posted in, kept by message.
+  const cardRoom = new Map();
+  async function editCard(message, look) {
+    const { text, found } = takeImages(look.markdown);
+    await edit(message, lookHtml({ ...look, markdown: text }));
+    if (found.length) await sendImages(cardRoom.get(String(message)) || null, found);
+  }
+
+  // ---------- dialogs ----------
+
+  // A button carries "<id>:<pick>"; the id names the dialog's value, kept here (a click
+  // after a restart finds nothing and is told the dialog is gone).
+  const buttons = new Map();
+  let buttonN = 0;
+  function keyboard(dialog, value) {
+    const id = (buttonN += 1).toString(36);
+    buttons.set(id, { value, labels: Object.fromEntries(dialog.menu.options.map((o) => [o.n, o.label])) });
+    if (buttons.size > BUTTONS_KEPT) buttons.delete(buttons.keys().next().value);
+    const rows = [];
+    for (const o of dialog.menu.options) {
+      if (o === dialog.menu.free) continue;
+      const box = o.checked === null || o.checked === undefined ? '' : o.checked ? '☑ ' : '☐ ';
+      rows.push([{ text: cut(`${o.n}. ${box}${o.label}`, BUTTON_TEXT), callback_data: `${id}:${o.n}` }]);
+    }
+    if (dialog.menu.multi) rows.push([{ text: 'Next ⇥', callback_data: `${id}:tab` }]);
+    rows.push([{ text: 'Esc (cancel)', callback_data: `${id}:esc` }]);
+    return { inline_keyboard: rows };
+  }
+  const dialogHtml = (dialog) => `<b>${escapeHtml(dialog.title)}</b>\n\n${toHtml(dialog.markdown)}${dialog.menu?.free ? `\n\n<i>Or type your answer here (${escapeHtml(dialog.menu.free.label)}).</i>` : ''}`;
+  const doneHtml = (dialog, done) => `<b>${escapeHtml(dialog.doneTitle)}</b>\n\n${toHtml(dialog.markdown)}\n\n<b>${escapeHtml(done)}</b>`;
+
+  async function postDialog(room, dialog, value) {
+    const res = await sendText(owner, room, dialogHtml(dialog), dialog.markdown, { extra: { reply_markup: keyboard(dialog, value) } });
+    return String(res.message_id);
+  }
+
+  async function closeDialog(message, dialog, done) {
+    await edit(message, doneHtml(dialog, done), { reply_markup: { inline_keyboard: [] } });
+  }
+
+  // ---------- rooms ----------
+
+  function iconOf(space) {
+    const state = read();
+    const spaces = state.spaces || {};
+    if (spaces[space]?.icon) return spaces[space].icon;
+    const used = Object.values(spaces).map((x) => x.icon);
+    const icon = ICON_COLORS.find((c) => !used.includes(c)) || ICON_COLORS[used.length % ICON_COLORS.length];
+    state.spaces = { ...spaces, [space]: { icon } };
+    write(state);
+    return icon;
+  }
+
+  async function openRoom({ name }) {
+    const topic = await tg.queued('createForumTopic', { chat_id: owner, name: cut(name, NAME_MAX), icon_color: iconOf(spaceOfName(name)) });
+    return String(topic.message_thread_id);
+  }
+
+  const renameTopic = (room, name) => tg.queued('editForumTopic', { chat_id: owner, message_thread_id: Number(room), name: cut(name, NAME_MAX) });
+
+  async function renameRoom(room, name) {
+    const c = Object.values(read().chats).find((x) => x.chat === room);
+    await renameTopic(room, c?.ended ? ENDED_MARK + name : name);
+  }
+
+  const placeRoom = async () => {}; // a topic's color is set when it is made
+  async function endRoom(k) {
+    const c = read().chats[k];
+    if (c) await renameTopic(c.chat, ENDED_MARK + c.name).catch((err) => logError(`ended mark on ${c.name}: ${err.message}`));
+  }
+  async function reviveRoom(k) {
+    const c = read().chats[k];
+    if (c) await renameTopic(c.chat, c.name).catch((err) => logError(`live again ${c.name}: ${err.message}`));
+  }
+
+  // ---------- attention ----------
+
+  const pins = new Set();
+  const pin = async (k) => { pins.add(k); };
+  const unpin = async (k) => { pins.delete(k); };
+
+  // Posts are silent; this reply sounds. A space in HERDR_SILENT_SPACES never sounds.
+  async function ring(k, message, text) {
+    const c = read().chats[k];
+    if (!message || !c || inSpaces(cfg.silent, spaceOfName(c.name))) return;
+    await sendText(owner, c.chat, escapeHtml(text), text, { silent: false, extra: { reply_parameters: { message_id: Number(message), allow_sending_without_reply: true } } })
+      .catch((err) => logError(`ring: ${err.message}`));
+  }
+
+  const react = (message, emoji) => tg.queued('setMessageReaction', { chat_id: owner, message_id: Number(message), reaction: [{ type: 'emoji', emoji }] });
+  async function markWorking(message) {
+    await react(message, WORKING_EMOJI);
+    return WORKING_EMOJI;
+  }
+  const markDone = async (message) => { await react(message, DONE_EMOJI); }; // one reaction per message: it replaces
+
+  async function image(buffer) {
+    const id = String((imageN += 1));
+    images.set(id, buffer);
+    return `⁣img${id}⁣`;
+  }
+
+  async function postFile(room, { name, data, caption }) {
+    return String((await tg.sendDocument(owner, room, name, data, { caption })).message_id);
+  }
+
+  // An expandable quote: two or three lines shown, the rest on a tap. A quote cannot hold
+  // code blocks or another quote, so the text goes in plain, escaped.
+  async function postFolded(room, { title, markdown }) {
+    const html = `<b>${escapeHtml(title)}</b>\n<blockquote expandable>${escapeHtml(markdown)}</blockquote>`;
+    return String((await sendText(owner, room, html, `${title}\n\n${markdown}`)).message_id);
+  }
+
+  async function download(message, ref, file) {
+    fs.writeFileSync(file, await tg.download(ref));
+  }
+
+  // `where` is "<chat>:<topic>" (topic empty: the main thread)
+  async function reply(where, markdown) {
+    const [chatId, thread] = String(where).split(':');
+    let last = null;
+    for (const piece of split(markdown)) last = String((await sendText(chatId, thread || null, toHtml(piece), piece)).message_id);
+    return last;
+  }
+
+  async function tellOwner(look) {
+    if (!owner) return;
+    await sendText(owner, null, lookHtml(look), `${look.title}\n\n${look.markdown}`, { silent: false });
+  }
+
+  // ---------- the overview, in the main thread ----------
+
+  function overviewHtml(rows) {
+    const sorted = [...rows].sort((a, b) => (RANK[a.state] ?? 5) - (RANK[b.state] ?? 5) || a.name.localeCompare(b.name));
+    const waiting = rows.filter((r) => r.state === 'blocked').length;
+    const head = `<b>${waiting ? `⚠️ ${waiting} needs you · ` : ''}herdrchat · ${rows.length} terminals</b>`;
+    if (!sorted.length) return `${head}\n\nNo terminal is shown in herdr-app.`;
+    const lines = sorted.map((r) => {
+      const name = r.room && username ? `<a href="https://t.me/${username}/${r.room}">${escapeHtml(r.name)}</a>` : escapeHtml(r.name);
+      const word = STATES[r.state] ? `${r.state === 'blocked' ? 'needs you' : r.state}${r.state === 'blocked' && r.kind ? ` (${r.kind})` : ''}` : r.program || 'no status';
+      const at = r.since ? ` · since ${new Date(r.since).toLocaleTimeString('en-GB', { hour: '2-digit', minute: '2-digit' })}` : '';
+      return `${STATES[r.state] || '❓'} <b>${name}</b> · ${escapeHtml(word)}${at} · <code>${escapeHtml(r.address)}</code>`;
+    });
+    return `${head}\n\n${lines.join('\n')}`;
+  }
+
+  // One overview message, edited in place (an edit never sounds); a fresh one (/ls) or
+  // one that cannot be edited is sent again and the old one is deleted.
+  let overviewShown = null;
+  async function showOverview(rows, { fresh = false } = {}) {
+    if (!owner) return;
+    const html = overviewHtml(rows);
+    if (html === overviewShown && !fresh) return;
+    const old = read().overview?.message;
+    if (old && !fresh) {
+      try {
+        await edit(old, html);
+        overviewShown = html;
+        return;
+      } catch (err) {
+        logWarn(`overview ${old} not edited (${err.message}); sending a new one`);
+      }
+    }
+    const res = await sendText(owner, null, html, html.replace(/<[^>]+>/g, ''));
+    const state = read();
+    state.overview = { message: String(res.message_id) };
+    write(state);
+    overviewShown = html;
+    if (old) await tg.queued('deleteMessage', { chat_id: owner, message_id: Number(old) }).catch(() => {});
+  }
+
+  // ---------- in ----------
+
+  function largestPhoto(photo = []) {
+    return [...photo].sort((a, b) => (b.width * b.height) - (a.width * a.height) || (b.file_size || 0) - (a.file_size || 0))[0]?.file_id;
+  }
+
+  async function handleMessage(m, onMessage) {
+    if (m.from?.is_bot) return; // the bot's own service messages (a topic it made)
+    const from = String(m.from?.id || '');
+    const where = `${m.chat.id}:${m.is_topic_message ? m.message_thread_id : ''}`;
+    if (!owner) {
+      log(`owner not set; message from user id ${from}`);
+      if (m.chat.type === 'private') await reply(where, `Owner is not set. Put this in config.env:\n\n\`TELEGRAM_OWNER_ID=${from}\`\n\nthen restart the bot.`);
+      return;
+    }
+    if (from !== owner || String(m.chat.id) !== owner) {
+      logWarn(`ignored message from ${from} in ${m.chat.id}`);
+      return;
+    }
+    const text = String(m.text || m.caption || '').replace(new RegExp(`^(/\\w+)@${username}\\b`, 'i'), '$1').trim();
+    const photo = largestPhoto(m.photo);
+    if (!text && !photo) return; // a service message (a topic made or renamed)
+    await onMessage({ room: m.is_topic_message ? String(m.message_thread_id) : null, where, message: String(m.message_id), text, images: photo ? [photo] : [] });
+  }
+
+  // A click: the button's dialog and pick, the core's answer, then the card as it is now
+  // and the toast.
+  async function handleClick(q, onAction) {
+    const answer = (text) => tg.call('answerCallbackQuery', { callback_query_id: q.id, text: (text || '').slice(0, 200) }).catch(() => {});
+    if (String(q.from?.id) !== owner) return answer('Only the owner can answer.');
+    const [id, pickRaw] = String(q.data || '').split(':');
+    const kept = buttons.get(id);
+    const message = String(q.message?.message_id || '');
+    if (!kept) {
+      await edit(message, `${q.message?.text ? escapeHtml(q.message.text) : ''}\n\n<b>This dialog is gone (the bot restarted); see the newest card.</b>`, { reply_markup: { inline_keyboard: [] } }).catch(() => {});
+      return answer('This dialog is gone.');
+    }
+    const pick = /^\d+$/.test(pickRaw) ? Number(pickRaw) : pickRaw;
+    const out = await onAction({ value: { ...kept.value, pick, label: kept.labels[pick] }, message, answer: '' });
+    if (out.card?.kind === 'done') await edit(message, doneHtml(out.card.dialog, out.card.done), { reply_markup: { inline_keyboard: [] } }).catch((err) => logError(`dialog card: ${err.message}`));
+    if (out.card?.kind === 'dialog') await edit(message, dialogHtml(out.card.dialog), { reply_markup: keyboard(out.card.dialog, out.card.value) }).catch((err) => logError(`dialog card: ${err.message}`));
+    await answer(out.toast.text);
+  }
+
+  // Long polling: getUpdates holds up to POLL_SECONDS for news; a failure waits RETRY_MS
+  // and tries again (409: another copy of the bot polls the same token).
+  function start({ onMessage, onAction, onReady = () => {} }) {
+    let offset = 0;
+    let connected = false;
+    (async () => {
+      for (;;) {
+        try {
+          if (!username) {
+            const me = await tg.call('getMe');
+            username = me.username;
+            if (!me.has_topics_enabled) logWarn(`telegram: topic mode is off for @${username}; turn it on in @BotFather (Bot Settings), or no room can be made`);
+            await tg.call('setMyCommands', { commands: COMMANDS }).catch((err) => logWarn(`telegram commands: ${err.message}`));
+          }
+          // the token works and Telegram answers: in (the first poll may hold for a while)
+          if (!connected) {
+            connected = true;
+            console.log(`[telegram] connected as @${username}`);
+            onReady();
+          }
+          const updates = await tg.call('getUpdates', { offset, timeout: POLL_SECONDS, allowed_updates: ['message', 'callback_query'] }, { timeoutMs: (POLL_SECONDS + 15) * 1000 });
+          for (const u of updates) {
+            offset = u.update_id + 1;
+            try {
+              if (u.message) await handleMessage(u.message, onMessage);
+              if (u.callback_query) await handleClick(u.callback_query, onAction);
+            } catch (err) {
+              logError(`telegram update ${u.update_id}:`, err);
+            }
+          }
+        } catch (err) {
+          logError(`telegram poll: ${err.message}`);
+          await sleep(RETRY_MS);
+        }
+      }
+    })();
+  }
+
+  // the room a card was posted in, for images an edit adds
+  const postCardKept = async (room, look) => {
+    const message = await postCard(room, look);
+    cardRoom.set(message, room);
+    if (cardRoom.size > 500) cardRoom.delete(cardRoom.keys().next().value);
+    return message;
+  };
+
+  return {
+    name: 'telegram',
+    ready: () => Boolean(owner),
+    help: [],
+    liveBytes: 3500, // a message holds 4096 characters after parsing
+    split: (text) => split(text),
+    start,
+    command: async () => false,
+    openRoom,
+    renameRoom,
+    placeRoom,
+    endRoom,
+    reviveRoom,
+    post,
+    postCard: postCardKept,
+    editCard,
+    postDialog,
+    closeDialog,
+    pin,
+    unpin,
+    pinned: () => [...pins],
+    ring,
+    markWorking,
+    markDone,
+    image,
+    postFile,
+    postFolded,
+    foldedBytes: 3500, // a message holds 4096 characters after parsing
+    download,
+    reply,
+    tellOwner,
+    showOverview,
+  };
+}

package/lib/{config.mjs → core/config.mjs}

@@ -6,8 +6,11 @@
 //     user-token.json (your token after /auth), logs/
 // HERDRCHAT_HOME puts one profile in one folder of your choice instead: config.env and
 // state/ inside it. The folders are made private (mode 700). The settings in config.env:
+//   HERDRCHAT_CHAT                   the chat app: feishu (default); its keys follow
 //   FEISHU_APP_ID, FEISHU_APP_SECRET  herdrchat's Feishu app
 //   FEISHU_OWNER_OPEN_ID             your open_id for that app; the only person it listens to
+//   TELEGRAM_BOT_TOKEN               herdrchat's Telegram bot (topic mode on, in @BotFather)
+//   TELEGRAM_OWNER_ID                your Telegram user id; the only person it listens to
 //   HERDR_SESSIONS                   hc sessions to mirror, comma-separated
 //   HERDR_MUTED_SPACES               spaces whose groups are muted once /auth is done (only
 //                                    an @ rings there): `all` (default), empty for none, or
@@ -18,6 +21,9 @@
 //                                    names (tenant tags: session or machine, and "ended")
 //   HERDR_USER_TAGS                  `on` (default) or `off`: your sidebar labels, once
 //                                    /auth is done
+//   HERDR_HISTORY                    what a new room gets of the conversation before it:
+//                                    `file,folded` (default: all of it as a file, the newest
+//                                    part in a folded post), `file`, `folded`, or empty / `none`
 import fs from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';
@@ -62,6 +68,16 @@ export function spacesOf(value, fallback) {
   return { all: false, spaces: v.split(',').map((s) => s.trim()).filter(Boolean) };
 }
 
+// Which of `known` a comma-separated list names: {name: true|false}; empty or `none` is
+// none, `fallback` is what an unset variable means. An unknown name is an error.
+export function partsOf(value, fallback, known, key = 'value') {
+  const v = (value ?? fallback).trim();
+  const named = v === '' || v === 'none' ? [] : v.split(',').map((s) => s.trim()).filter(Boolean);
+  const unknown = named.filter((n) => !known.includes(n));
+  if (unknown.length) throw new Error(`${key}: ${unknown.join(', ')} is not one of ${known.join(', ')}`);
+  return Object.fromEntries(known.map((k) => [k, named.includes(k)]));
+}
+
 // on / off (also true, yes, 1 / false, no, 0); `fallback` is what an unset variable means.
 export function onOff(value, fallback) {
   const v = String(value ?? '').trim().toLowerCase();
@@ -70,12 +86,32 @@ export function onOff(value, fallback) {
   return fallback;
 }
 
-export function loadConfig() {
+// `requires`: config keys the chat app cannot start without (its module's `requires`).
+// `env` is everything config.env and the environment hold, for the app's own keys.
+export function loadConfig({ requires = [] } = {}) {
   const env = { ...parseEnv(CONFIG_FILE), ...process.env };
   const sessions = (env.HERDR_SESSIONS || '').split(',').map((s) => s.trim()).filter(Boolean);
-  if (!env.FEISHU_APP_ID || !env.FEISHU_APP_SECRET) throw new Error(`${CONFIG_FILE}: FEISHU_APP_ID and FEISHU_APP_SECRET are required`);
+  const missing = requires.filter((k) => !env[k]);
+  if (missing.length) throw new Error(`${CONFIG_FILE}: ${missing.join(', ')} ${missing.length > 1 ? 'are' : 'is'} required`);
   if (!sessions.length) throw new Error(`${CONFIG_FILE}: HERDR_SESSIONS must list at least one hc session`);
-  return { appId: env.FEISHU_APP_ID, appSecret: env.FEISHU_APP_SECRET, ownerOpenId: env.FEISHU_OWNER_OPEN_ID || '', sessions, muted: spacesOf(env.HERDR_MUTED_SPACES, 'all'), silent: spacesOf(env.HERDR_SILENT_SPACES, ''), botTags: onOff(env.HERDR_BOT_TAGS, true), userTags: onOff(env.HERDR_USER_TAGS, true) };
+  return {
+    chat: env.HERDRCHAT_CHAT || 'feishu',
+    env,
+    sessions,
+    appId: env.FEISHU_APP_ID || '',
+    appSecret: env.FEISHU_APP_SECRET || '',
+    ownerOpenId: env.FEISHU_OWNER_OPEN_ID || '',
+    muted: spacesOf(env.HERDR_MUTED_SPACES, 'all'),
+    silent: spacesOf(env.HERDR_SILENT_SPACES, ''),
+    botTags: onOff(env.HERDR_BOT_TAGS, true),
+    userTags: onOff(env.HERDR_USER_TAGS, true),
+    history: partsOf(env.HERDR_HISTORY, 'file,folded', ['file', 'folded'], 'HERDR_HISTORY'),
+  };
+}
+
+// The chat app config.env names, before its keys are checked.
+export function chatOf() {
+  return ({ ...parseEnv(CONFIG_FILE), ...process.env }).HERDRCHAT_CHAT || 'feishu';
 }
 
 export function readState() {