herdrchat 1.1.1 → 1.1.2

package/config.env.example

@@ -17,10 +17,11 @@ TELEGRAM_BOT_TOKEN=
 TELEGRAM_OWNER_ID=
 
 HERDR_SESSIONS=session-a,session-b
-# once /auth is done, spaces whose groups are muted (only an @ rings): `all` (default),
-# empty for none, or spaces, comma-separated
+# spaces whose rooms are quiet, so only "needs you" and "done" ring (Feishu: groups muted
+# once /auth is done; Telegram: silent posts): `all` (default), empty for none, or spaces,
+# comma-separated; elsewhere every post rings
 HERDR_MUTED_SPACES=all
-# spaces that do not even @-mention you (fully quiet): empty (default), `all`, or spaces
+# spaces where nothing rings, not even "needs you": empty (default), `all`, or spaces
 HERDR_SILENT_SPACES=
 # the bot's tags next to group names (tenant tags): on (default) or off
 HERDR_BOT_TAGS=on

package/lib/chats/telegram/index.mjs

@@ -1,9 +1,11 @@
 // 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
+// chat: the overview and the commands. In a space of HERDR_MUTED_SPACES (all, by
+// default) the bot posts silently (a notification without sound) and `ring` sends a short
+// reply that sounds, for "needs you" and "done"; a bot cannot mute a chat for you, so
+// this stands in for Feishu's muted groups. Elsewhere every post sounds. A space of
+// HERDR_SILENT_SPACES never sounds. 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:
@@ -71,11 +73,18 @@ export function create({ cfg, store, log, logWarn, logError }) {
       const buffer = images.get(id);
       if (!buffer) continue;
       images.delete(id);
-      last = String((await tg.sendPhoto(owner, room, buffer)).message_id);
+      last = String((await tg.sendPhoto(owner, room, buffer, { silent: quiet(room) })).message_id);
     }
     return last;
   }
 
+  // Whether a room's posts go silently: its space is in HERDR_MUTED_SPACES.
+  const muted = cfg.muted || { all: true, spaces: [] };
+  function quiet(room) {
+    const c = Object.values(read().chats).find((x) => x.chat === room);
+    return !c || inSpaces(muted, spaceOfName(c.name));
+  }
+
   // 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 };
@@ -91,7 +100,7 @@ export function create({ cfg, store, log, logWarn, logError }) {
   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);
+    if (text) for (const piece of split(text)) last = String((await sendText(owner, room, toHtml(piece), piece, { silent: quiet(room) })).message_id);
     return (await sendImages(room, found)) || last;
   }
 
@@ -99,7 +108,7 @@ export function create({ cfg, store, log, logWarn, logError }) {
 
   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);
+    const message = String((await sendText(owner, room, lookHtml({ ...look, markdown: text }), `${look.title}\n\n${text}`, { silent: quiet(room) })).message_id);
     await sendImages(room, found);
     return message;
   }
@@ -146,7 +155,7 @@ export function create({ cfg, store, log, logWarn, logError }) {
   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) } });
+    const res = await sendText(owner, room, dialogHtml(dialog), dialog.markdown, { silent: quiet(room), extra: { reply_markup: keyboard(dialog, value) } });
     return String(res.message_id);
   }
 
@@ -195,10 +204,11 @@ export function create({ cfg, store, log, logWarn, logError }) {
   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.
+  // In a quiet room this reply is what sounds; in another the post sounded already. 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;
+    if (!message || !c || !quiet(c.chat) || 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}`));
   }

package/lib/core/config.mjs

@@ -12,10 +12,12 @@
 //   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
-//                                    spaces, comma-separated
-//   HERDR_SILENT_SPACES              spaces that do not even @-mention you (fully quiet):
+//   HERDR_MUTED_SPACES               spaces whose rooms are quiet, so only "needs you" and
+//                                    "done" ring (Feishu: groups muted, once /auth is done,
+//                                    and an @; Telegram: silent posts and a reply that
+//                                    rings): `all` (default), empty for none, or spaces,
+//                                    comma-separated; elsewhere every post rings
+//   HERDR_SILENT_SPACES              spaces where nothing rings, not even "needs you":
 //                                    empty (default) for none, `all`, or spaces
 //   HERDR_BOT_TAGS                   `on` (default) or `off`: the bot's tags next to group
 //                                    names (tenant tags: session or machine, and "ended")

package/lib/core/engine.mjs

@@ -595,6 +595,12 @@ export function createEngine({ cfg, chat, hc, readers, store, log, logWarn, logE
       if (steady) break;
     }
     const k = key(session, address);
+    // answered while its screen was being read: nothing waits, so no card
+    const nowStatus = (await hc.getTerminal(session, address).catch(() => null))?.status;
+    if (nowStatus && nowStatus.state !== 'blocked') {
+      log(`<- ${session}/${address}: no card, it no longer waits (${nowStatus.state})`);
+      return;
+    }
     if (!claimDialog(k, dialog, record.status) && !again) return;
     await closeCard(k, 'It moved on; see the next card.');
     if (!dialog.menu) {

package/lib/core/menu.mjs

@@ -13,12 +13,21 @@
 // above a multi-question dialog, which change as you answer: the same dialog keeps its key). A card click is pressed only when the
 // screen still shows the dialog with that key, so an old card can never answer a newer
 // dialog that looks alike (two permission prompts both offer "1. Yes").
+//
+// A question with previews draws a box beside its options, on the same lines, and the
+// box shows the preview of the option under the cursor: what is right of it is cut off
+// (three spaces or more, then a box line), so it is neither part of an option's label
+// nor of the key; a question's own left border (│) goes too.
 import crypto from 'node:crypto';
 
 const OPTION = /^\s*(?:❯\s*)?(\d{1,2})\.\s+(?:\[(.)\]\s+)?(.*\S)\s*$/;
 const RULE = /^[\s─╌━-]*$/;
 const BORDER = /^\s*─{10,}/;
 const FREE = /^Type something/i;
+const BESIDE = /\s{3,}[┌└│├┤┐┘╭╰─┬┴┼║╔╚].*$/u;
+const LEFT_BORDER = /^(\s*)│\s?/u;
+
+const ownPart = (line) => line.replace(BESIDE, '').replace(LEFT_BORDER, '$1');
 
 const TEXT_LINES = 15; // a dialog with no border found: this many lines above its options
 
@@ -36,7 +45,7 @@ function keyOf(lines, top, last) {
 }
 
 export function menuOf(screen) {
-  const lines = screen.split('\n');
+  const lines = screen.split('\n').map(ownPart);
   let run = null;
   let menu = null;
   lines.forEach((line, i) => {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "herdrchat",
-  "version": "1.1.1",
+  "version": "1.1.2",
   "description": "Chat front-ends for hc: every terminal hc runs, in the chat app you use",
   "repository": {
     "type": "git",

package/skills/README.md

@@ -4,6 +4,6 @@
 it to set up, run and look after herdrchat. Its commands are `/herdrchat <command>`.
 
 Each part of the system has one reference under `herdrchat/references/`, named after the
-part: a chat app (`feishu.md`, later `slack.md`, `discord.md`, `telegram.md`) or a part of
+part: a chat app (`feishu.md`, `telegram.md`, later `slack.md`, `discord.md`) or a part of
 the core (`ops.md`, later `reader.md`). New work goes into the reference of its part, or
 a new one for a new part; `SKILL.md` only lists commands and points to references.

package/skills/herdrchat/SKILL.md

@@ -1,23 +1,26 @@
 ---
 name: herdrchat
-description: Set up, run and look after herdrchat, the chat front-end for hc that mirrors every hc terminal into Feishu (one group per terminal, dialog buttons, an overview, quiet phones) - first setup with the Feishu app, start and stop, status and logs, /auth, settings, fixing problems, and the Feishu developer console (with Ego, or guided click by click). Use for anything about herdrchat or its Feishu bot, even when the user only says "set up the Feishu bot", "is it running", "it doesn't post", "mute the workers" or "publish the bot". Trigger with "/herdrchat", "/herdrchat setup", "/herdrchat status", "/herdrchat fix".
+description: Set up, run and look after herdrchat, the chat front-end for hc that mirrors every herdr-app tab into a chat app - Feishu (one group per tab) or Telegram (one topic per tab in the bot's private chat), with dialog buttons, an overview and quiet phones - first setup of either app, running both side by side, start and stop, status and logs, /auth, settings, fixing problems, the Feishu developer console and @BotFather. Use for anything about herdrchat or its Feishu or Telegram bot, even when the user only says "set up the Telegram bot", "is it running", "it doesn't post", "mute the workers" or "publish the bot". Trigger with "/herdrchat", "/herdrchat setup", "/herdrchat status", "/herdrchat fix".
 ---
 
 # herdrchat
 
-herdrchat mirrors every terminal hc runs into a chat app, Feishu first: one group per
-terminal, the conversation as it happens, dialogs as buttons, an overview in the direct
-chat. Its command is `herdrchat` (`node bin/cli.mjs` in a clone): check with
-`command -v herdrchat`; when it is missing, ask before `npm install -g herdrchat`. A
-profile (`--profile`, default `default`) keeps its settings
-in `~/.config/herdrchat/<profile>/config.env` and its state in
+herdrchat mirrors every herdr-app tab into a chat app: a group per tab in Feishu, a topic
+per tab in the bot's private chat in Telegram; the conversation as it happens, dialogs as
+buttons, an overview in the direct chat. One profile is one chat app (`HERDRCHAT_CHAT`);
+to use both, run a profile each (`--profile telegram` beside the default Feishu one).
+
+Its command is `herdrchat` (`node bin/cli.mjs` in a clone): check with `command -v
+herdrchat`; when it is missing, ask before `npm install -g herdrchat`. A profile
+(`--profile`, default `default`) keeps its settings in
+`~/.config/herdrchat/<profile>/config.env` and its state in
 `~/.local/state/herdrchat/<profile>/`; `herdrchat status` prints both.
 
 ## Commands
 
 | Command | Do |
 |---|---|
-| `/herdrchat setup` | First time, in order: `herdrchat init`; make the Feishu app (`references/feishu.md`: create, bot, scopes, events and callbacks); fill `config.env` with the user (app id, secret, `HERDR_SESSIONS`: the hc sessions herdr-app shows on this machine); `herdrchat start`; publish a version; get the user's open_id (they message the bot, it answers with it) into `FEISHU_OWNER_OPEN_ID`; start again. Optional: `/herdrchat auth`. |
+| `/herdrchat setup` | First ask which chat app (Feishu, Telegram, or both: one profile each). Telegram: `/herdrchat telegram setup`. Feishu, in order: `herdrchat init`; make the Feishu app (`references/feishu.md`: create, bot, scopes, events and callbacks); fill `config.env` with the user (app id, secret, `HERDR_SESSIONS`: the hc sessions herdr-app shows on this machine); `herdrchat start`; publish a version; get the user's open_id (they message the bot, it answers with it) into `FEISHU_OWNER_OPEN_ID`; start again. Optional: `/herdrchat auth`. |
 | `/herdrchat status` | `herdrchat status`; explain each line; on errors, `/herdrchat fix`. |
 | `/herdrchat start`, `/herdrchat stop` | Read `config.env` (its `HERDR_SESSIONS`) in one step, then `herdrchat start` / `stop` in the next; never both at once. |
 | `/herdrchat logs` | `herdrchat logs --errors` (or `-n 100`); explain them with `references/ops.md` "Logs". |
@@ -25,6 +28,7 @@ in `~/.config/herdrchat/<profile>/config.env` and its state in
 | `/herdrchat config` | Change a setting in `config.env` with the user (sessions, `HERDR_MUTED_SPACES`, `HERDR_SILENT_SPACES`, `HERDR_BOT_TAGS`, `HERDR_USER_TAGS`, `HERDR_HISTORY`, `HERDRCHAT_CHAT`; each is explained in `config.env.example`), read the file back, then restart. |
 | `/herdrchat fix` | Find the cause from `herdrchat status`, the logs and the live result, then fix it: `references/ops.md`. |
 | `/herdrchat feishu <task>` | Anything in the Feishu developer console: scopes, callbacks, publishing, the icon, deleting an app: `references/feishu.md`. |
+| `/herdrchat telegram <task>` | The Telegram bot, as its own profile: `setup` (@BotFather, topic mode, token, owner id, first start), checking the token, quiet and silent spaces, what Telegram cannot do and what stands in: `references/telegram.md`. |
 
 With no subcommand, run `herdrchat status` and suggest the next step from it.
 
@@ -32,7 +36,8 @@ With no subcommand, run `herdrchat status` and suggest the next step from it.
 
 - Ask before anything outward-facing: publishing a version, applying scopes, deleting or
   disbanding anything, sending to a real group. One yes covers one action.
-- Never print, screenshot or paste `FEISHU_APP_SECRET` or `user-token.json`.
+- Never print, screenshot or paste `FEISHU_APP_SECRET`, `TELEGRAM_BOT_TOKEN` or
+  `user-token.json`; ask the user to paste a token into `config.env` themselves.
 - A check that decides an action runs on its own first (read the config, then start;
   scan, then commit).
 - Say what was checked on the live bot and what was not.
@@ -41,5 +46,7 @@ With no subcommand, run `herdrchat status` and suggest the next step from it.
 
 - `references/feishu.md`: the bot's app in the Feishu developer console, with Ego or as a
   guided walk-through; the scopes this bot uses.
+- `references/telegram.md`: the Telegram bot, from @BotFather to the first topic; what
+  it does differently from Feishu.
 - `references/ops.md`: running and checking the bot, its logs and state, the usual
   problems, trying a Feishu API safely, committing without a leak.

package/skills/herdrchat/references/ops.md

@@ -90,7 +90,7 @@ Say which checks were run and which were not; "the code is there" is not "it wor
 | nothing posts | bot down, or `FEISHU_OWNER_OPEN_ID` unset | check it runs; the log says "owner not set" |
 | a button gives error 200340 | the card callback is not set up | `references/feishu.md`: events and card callbacks |
 | a dialog had no card | answered in the terminal before the card; or no numbered menu on screen | log: `blocked`; the card says `/answer` when it saw no menu |
-| the phone rings too much | not `/auth`ed, or settings | `/auth`; `HERDR_MUTED_SPACES`, `HERDR_SILENT_SPACES` |
+| the phone rings too much | Feishu: not `/auth`ed; either app: settings | Feishu `/auth`; `HERDR_MUTED_SPACES` (quiet but for needs you and done), `HERDR_SILENT_SPACES` (nothing rings), per profile |
 | a ⚠️ warning in the direct chat about acting as you | the token could not be refreshed | send `/auth` again |
 | a group keeps an old name | its terminal is not live | it renames when the terminal is back |
 | a Feishu call fails with 400 in a burst | a rate limit (tags: 5 a second) | space the calls; the bot queues tag calls |

package/skills/herdrchat/references/telegram.md

@@ -1,23 +1,77 @@
-# Telegram: setting up the bot
-
-A Telegram bot cannot make groups, so herdrchat puts each herdr-app tab in a topic of
-your private chat with the bot; the chat's main thread is the overview and the commands
-(`/ls`, `/new`, `/kill`; in a topic `/screen`, `/answer`, `/esc`). Posts are silent;
-"needs you" and "done" ring.
-
-It runs as its own profile, beside a Feishu one:
-
-1. In Telegram, message **@BotFather**: `/newbot`, pick a name and a username, and keep
-   the token it gives. Never paste the token into a chat or a log.
-2. Turn on topics for the bot in @BotFather (its mini app, "Open": the bot's settings,
-   Threaded Mode). Check: `getMe` answers `has_topics_enabled: true`.
-3. Make the profile's config: `herdrchat init --profile telegram`, then in
-   `~/.config/herdrchat/telegram/config.env` set `HERDRCHAT_CHAT=telegram`, the token as
-   `TELEGRAM_BOT_TOKEN`, and `HERDR_SESSIONS`.
-4. `herdrchat start --profile telegram`, then message the bot once: it answers with your
-   `TELEGRAM_OWNER_ID=...`. Put that in the config and start it again. The topics appear,
-   one per tab (Telegram allows about one message a second, so many tabs take a moment).
-
-Check the token without printing it: read `TELEGRAM_BOT_TOKEN` from the config in a short
-`node -e`, call `https://api.telegram.org/bot<token>/getMe`, print only `username` and
-`has_topics_enabled`.
+# Telegram: the bot, from @BotFather to the first topic
+
+A Telegram bot cannot make groups (the Bot API has no such method), so herdrchat puts each
+herdr-app tab in a **topic** of your private chat with the bot: each has its own name,
+icon color (one per space), unread count, and can be muted on its own. The chat's main
+thread holds the overview and the commands. It runs as its **own profile**, beside a
+Feishu one; each bot follows the same hc terminals, so an answer in either reaches the
+terminal, and a dialog answered in one closes its card in the other.
+
+## Setup (`/herdrchat telegram setup`)
+
+Do these in order; the user does the Telegram steps, you check each one.
+
+1. **The bot.** The user messages **@BotFather**: `/newbot`, a name, a username ending in
+   `bot`. BotFather answers with a token. The user keeps it: never ask them to paste it
+   into the chat.
+2. **Topic mode.** It is not in BotFather's `/mybots` → Bot Settings list; it is in
+   BotFather's mini app (the **Open** button at the bottom left of the BotFather chat):
+   pick the bot, turn on Threaded Mode / topics. Check it (step 5): `has_topics_enabled`
+   must be `true`, or no topic can be made.
+3. **The profile's config.** Make `~/.config/herdrchat/telegram/config.env` (folder mode
+   700, file 600) with:
+   ```
+   HERDRCHAT_CHAT=telegram
+   TELEGRAM_BOT_TOKEN=
+   TELEGRAM_OWNER_ID=
+   HERDR_SESSIONS=<the same sessions as the Feishu profile>
+   ```
+   and ask the user to paste the token after `TELEGRAM_BOT_TOKEN=` themselves
+   (`open -e <file>` opens it), no quotes, no spaces.
+4. **First start, to learn the owner.** `herdrchat start --profile telegram`; the user
+   messages the bot anything; it answers `TELEGRAM_OWNER_ID=<digits>`. The user puts that
+   in the config. Until then the bot makes no topic.
+5. **Check, without printing secrets.** In a short `node -e`: read the token from the
+   config, call `https://api.telegram.org/bot<token>/getMe`, print only `username` and
+   `has_topics_enabled`; for the owner, print only whether `TELEGRAM_OWNER_ID` is digits.
+6. **Start again.** Read the config (secrets hidden) in one step, then
+   `herdrchat start --profile telegram` in the next. One topic per tab appears; Telegram
+   takes about one message a second in a chat, so twenty tabs take twenty seconds. A new
+   topic gets the conversation before it (`HERDR_HISTORY`); `/history` in a topic posts it
+   again.
+
+## What rings
+
+The same settings as Feishu, in the Telegram profile's own config.env:
+
+- `HERDR_MUTED_SPACES` (default `all`): in these spaces posts go silently (a notification
+  without sound) and only "⚠️ needs you" and "✅ done" ring, as a short reply. Elsewhere
+  every post rings.
+- `HERDR_SILENT_SPACES` (default none): nothing rings there, not even "needs you".
+
+A bot cannot mute a chat or a topic for the user. A topic the user mutes in Telegram is
+fully quiet, "needs you" included; `HERDR_SILENT_SPACES` does the same for a whole space
+without muting each topic by hand.
+
+## What Telegram does differently
+
+| Feishu | Telegram, and what stands in |
+|---|---|
+| a group per tab | a topic per tab, in the bot's private chat |
+| an ended group gets the "ended" tag | an ended topic's name starts with 🔚 (closing a topic is documented for supergroups only) |
+| an image inside a card | each image as its own photo after the text |
+| a text box on a dialog card | type the answer in the topic |
+| tags, labels, pins, `/auth` | none (a topic cannot be pinned; a bot cannot act as the user) |
+| the overview card | one message in the main thread, edited in place |
+| `/` commands: typed | `/` shows a menu: ls, new, kill, screen, answer, esc, history |
+
+## When something is off
+
+| Seen | Cause | Do |
+|---|---|---|
+| log: `topic mode is off for @<bot>` | step 2 not done | turn it on in BotFather's mini app, check `has_topics_enabled`, start again |
+| the bot answers `Owner is not set` | `TELEGRAM_OWNER_ID` empty | step 4 |
+| `herdrchat start` says it did not reach its chat app | wrong token, or no network | check with getMe (step 5) |
+| log: `telegram poll: ... 409` | another copy polls the same token | `herdrchat stop --profile telegram`, find the other one (another machine?), start once |
+| log: `too fast, waiting N s` | Telegram's flood limit; the bot waits as told | nothing; it catches up |
+| a click answers "This dialog is gone" | the bot restarted after the card was posted (button ids live in memory) | answer the newest card, or in the terminal |