herdrchat 1.2.0 → 1.3.0

package/bin/cli.mjs

@@ -52,7 +52,7 @@ const places = placesOf();
 
 const shellQuote = (s) => `'${String(s).replace(/'/g, `'\\''`)}'`;
 const firstSession = () => loadConfig().sessions[0];
-const CONNECT_WAIT_MS = 30000;
+const CONNECT_WAIT_MS = 60000; // a first attempt that times out (15 s) is tried again
 
 // hc's full path, from HERDRCHAT_HC or PATH
 function findHc() {

package/docs/guide.md

@@ -2,9 +2,11 @@
 
 How herdrchat works and every setting, for when the README is not enough.
 
-herdrchat is a chat front-end for hc: every terminal hc runs, followed and answered in a
-chat app. Feishu is the first (one bot); Slack, Discord and Telegram may follow, on the
-same core (hc events, a reader per agent, dialogs, the overview) with an adapter each.
+herdrchat is a chat front-end for hc: every herdr-app tab, followed and answered in a chat
+app, Feishu or Telegram. Both sit on the same core (hc events, a reader per agent,
+dialogs, the overview), each behind one contract (`docs/architecture.md`); Slack and
+Discord may follow the same way. A profile is one chat app (`HERDRCHAT_CHAT`); to use
+both, run a profile each.
 
 ## Feishu
 
@@ -21,6 +23,68 @@ herdr-app, moved into one Feishu bot:
 Everything comes from hc, so it works the same for Claude Code, codex, pi or any program
 hc shows, on this machine or on a machine hc has added. Nothing is installed in the agents.
 
+## Telegram
+
+A Telegram bot cannot make groups, so it uses topics in your private chat with the bot
+(topic mode must be on in @BotFather):
+
+| herdr-app | Telegram |
+|---|---|
+| a tab | a topic named `<space> / <tab>` in the bot's private chat; type there to talk to it |
+| a space | one topic icon color for all of its topics (Telegram offers six) |
+| a terminal that is gone | its topic stays, its name starting with 🔚 (taken off if it comes back) |
+| herdr itself | the chat's main thread: the overview message, edited in place; `/ls`, `/new`, `/kill`; `/` shows the commands |
+
+What differs is in "Feishu and Telegram side by side" below. Telegram takes about one
+message a second in a chat, so the bot queues and waits as Telegram asks. Setting it up:
+`skills/herdrchat/references/telegram.md`.
+
+## Feishu and Telegram side by side
+
+Both do the same things; where an app cannot, something stands in.
+
+| | Feishu | Telegram |
+|---|---|---|
+| a tab | a group | a topic in the bot's private chat |
+| a space | an avatar (its letter, its color) | a topic icon color |
+| an ended terminal | the `ended` tag | 🔚 before the topic's name |
+| the direct chat | the overview card, commands typed or from the bot menu (set in the console) | the main thread: the overview, commands with the `/` list |
+| what it says while working | one live card per turn, edited | one live message per turn, edited |
+| a dialog | a card with buttons, a text box for its own words | a message with buttons; its own words are typed in the topic |
+| needs you | the group pinned (after `/auth`), an @ that rings | the dialog card pinned in its topic, a reply that rings |
+| quiet spaces (`HERDR_MUTED_SPACES`) | groups muted (after `/auth`); only an @ rings | posts silent; only a short reply rings |
+| silent spaces (`HERDR_SILENT_SPACES`) | no @ | no ringing reply |
+| a new room (`HERDR_HISTORY`), `/history` | the conversation as a file, its newest part in a folded panel | the same, the newest part in an expandable quote |
+| images | in the card, both ways | as photos after the text, both ways |
+| your message marked | a reaction, then OK | 👀, then 👌 |
+| tags and labels (`HERDR_BOT_TAGS`, `HERDR_USER_TAGS`) | yes | none in Telegram |
+| messages while the bot is away | looked for and handled when it connects | kept by Telegram for 24 hours, handled when it connects |
+| acting as you (`/auth`) | mute, labels, pins | not needed: posts are silent by themselves |
+
+## Settings
+
+In the profile's `config.env` (`herdrchat status` prints where it is):
+
+| Key | For | Default | What it does |
+|---|---|---|---|
+| `HERDRCHAT_CHAT` | both | `feishu` | the chat app this profile mirrors into: `feishu` or `telegram` |
+| `HERDR_SESSIONS` | both | (required) | the hc sessions to mirror, comma-separated; machines they reach come along |
+| `HERDR_MUTED_SPACES` | both | `all` | spaces whose rooms are quiet: only "needs you" and "done" ring; empty for none |
+| `HERDR_SILENT_SPACES` | both | (none) | spaces where nothing rings, not even "needs you" |
+| `HERDR_HISTORY` | both | `file,folded` | what a new room gets of the conversation before it: `file`, `folded`, both, or empty |
+| `FEISHU_APP_ID`, `FEISHU_APP_SECRET` | Feishu | (required) | the Feishu app |
+| `FEISHU_OWNER_OPEN_ID` | Feishu | (empty) | you; the bot tells you yours when you message it |
+| `HERDR_BOT_TAGS` | Feishu | `on` | the session or machine tag and `ended` next to a group's name |
+| `HERDR_USER_TAGS` | Feishu | `on` | your sidebar labels, once `/auth` is done |
+| `TELEGRAM_BOT_TOKEN` | Telegram | (required) | the bot's token from @BotFather |
+| `TELEGRAM_OWNER_ID` | Telegram | (empty) | you; the bot tells you yours when you message it |
+
+In the environment (not `config.env`): `HERDRCHAT_PROFILE` (or `--profile`) picks the
+profile; `HERDRCHAT_HOME` puts a profile's `config.env` and state in one folder;
+`XDG_CONFIG_HOME` and `XDG_STATE_HOME` move the usual folders. `herdrchat start` and
+`herdrchat install` hand the bot hc's full path as `HERDRCHAT_HC`. A setting changed in
+`config.env` takes effect at the next `herdrchat start`.
+
 ## How it works: hc, plus a reader per agent
 
 **hc is the backbone.** The bot follows `hc events --json` for each session (format:
@@ -36,13 +100,14 @@ each agent a reader reads the agent's own records. The status hc reports names t
 | `status.app` | reader | reads |
 |---|---|---|
 | `claude-code` | `lib/core/readers/claude.mjs` | its transcript: the terminal's foreground pid names the session in `~/.claude/sessions/<pid>.json` |
-| anything else | none (default) | the screen, through `hc read` |
+| anything else | none | nothing by itself; what you type gets its screen in reply |
 
 On another machine, a reader reads the same files through `hc exec --on`. To add an
-agent, write `lib/core/readers/<agent>.mjs` (the contract is at the top of
-`lib/core/readers/index.mjs`) and list it there.
+agent: `docs/architecture.md`, "Adding a harness".
+
+## What a room shows
 
-## What a group shows
+A room is a Feishu group or a Telegram topic.
 
 - A program with a reader:
   - while it works: one "⌛️ Working…" card per turn (then "✅ Worked"), edited every 5
@@ -50,9 +115,12 @@ agent, write `lib/core/readers/<agent>.mjs` (the contract is at the top of
     mid-turn) as **You:**, and each tool it calls as one line (`▸ Bash: Run the tests`).
     It shows the program is alive, as herdr-app does, and since an edit is not a new
     message, the phone does not ring every few seconds;
-  - when the turn ends: its last answer, as a new message. Without `/auth` you are
-    notified when a turn starts and when it is done; with it, groups are muted and only
-    an @ under the answer rings (see "Optional: let the bot act as you").
+  - when the turn ends: its last answer, as a new message. In a space of
+    `HERDR_MUTED_SPACES` (all, by default) only "needs you" and "done" ring: in Feishu
+    the groups are muted (after `/auth`) and an @ under the answer rings; in Telegram
+    the posts go silently and a short reply rings. `HERDR_SILENT_SPACES` rings nothing.
+  - A message another terminal sent with `hc send` shows as **From t7 review**, not as
+    yours (hc wraps it in `<hc from="…">`, for any agent).
   - Images too: ones it looked at (a screenshot, an image file it read) and ones you
     pasted in the terminal, shown in the card.
   - What you sent from the group is not repeated.
@@ -63,15 +131,21 @@ agent, write `lib/core/readers/<agent>.mjs` (the contract is at the top of
   a red "⚠️ Needs you" card. When the screen shows a numbered menu (as Claude Code's
   permission and question dialogs do), the card shows only the dialog, as text, with a
   button per option; a multi-select also has "Next ⇥", a "Type something" option a box to
-  type in, and every card "Esc". Without a menu the card shows the screen and how to
-  answer by typing. Once the dialog is gone the card turns to "✅ Done".
-
-## Answering a dialog from Feishu
-
-A button presses that option's number key in the terminal (Next presses tab, Esc esc).
+  type in (Feishu; in Telegram you type the answer in the topic), and every card "Esc".
+  Without a menu the card shows the last lines of the screen and how to answer by typing.
+  Once the dialog is gone the card turns to "✅ Done". A card is posted only for a dialog
+  that still waits: one answered while its screen was read gets none.
+
+## Answering a dialog from the chat
+
+A button presses that option's number key in the terminal (Esc presses esc). A question
+with previews (a box beside its options) takes no number, so there the button moves with
+the arrows from the cursor to that option and presses Enter. In a multi-select, a box is
+ticked on the card only, at once; Next sends them all: each box that differs from the
+screen is pressed, then tab.
 Before it presses anything, the bot reads the screen again and checks that it still
-shows the same dialog (a hash of it, from its top border to its last option) and the
-same option, so an old card can never answer a newer dialog that looks alike. After the
+shows the same dialog (a hash of it, from its top border to its last option, without the
+cursor, the check marks and the preview box) and the same option, so an old card can never answer a newer dialog that looks alike. After the
 key, the card turns into the dialog's next step (a toggled box, the next question, the
 review) or says what was picked. Text you type in the group while it waits goes into its
 "Type something" box when it has one.
@@ -121,16 +195,21 @@ delivered (the terminal has ended) says so plainly.
 
 - Direct chat: `/ls` (the overview again at the bottom of the chat; the old one is
   recalled), `/new <session> <space>/<tab> [command]` (start one; default `claude`;
-  `--cwd <dir>` first to pick its folder), `/kill <session> <address>`, `/auth` (see
-  below).
-- In a terminal's group: any text goes to it (marked THINKING once typed in, then OK when
-  the turn that took it is over); an image (alone or in a rich text message) is sent
+  `--cwd <dir>` first to pick its folder), `/kill <session> <address>`, `/auth` (Feishu;
+  see below). Telegram lists them when you type `/`; Feishu can have a bot menu for
+  `/ls`, help and `/auth` (set in the developer console:
+  `skills/herdrchat/references/feishu.md`, "The bot menu").
+- In a terminal's room: any text goes to it (marked once typed in, and again when the
+  turn that took it is over); an image (alone or in a rich text message) is sent
   beside the terminal with `hc put`, on its machine, and its path is typed in with your
   text, so an agent like Claude Code opens it; `/screen`, `/answer <text>` (type into the
-  dialog it waits on, as is), `/esc`. Dialog cards have buttons.
+  dialog it waits on, as is), `/esc`, `/history` (the conversation so far, as a file and
+  a folded post). Dialog cards have buttons.
 
 ## Set up
 
+Telegram: `skills/herdrchat/references/telegram.md`. Feishu:
+
 Steps 1, 2, 5 and 6 are in the Feishu developer console; the herdrchat skill
 (`/herdrchat setup`, see "Skills") does them with an agent, or guides you through them.
 
@@ -152,6 +231,26 @@ Steps 1, 2, 5 and 6 are in the Feishu developer console; the herdrchat skill
 7. Open `https://applink.feishu.cn/client/bot/open?appId=<app id>` and send anything.
    The bot answers with your `open_id`; put it in `FEISHU_OWNER_OPEN_ID` and run
    `herdrchat start` again.
+8. Optional: the bot menu in the direct chat (`skills/herdrchat/references/feishu.md`,
+   "The bot menu").
+9. Once it works: `herdrchat install` (see "Running as a service").
+
+## Running as a service
+
+`herdrchat start` runs the bot in an hc terminal, which ends when that hc core stops,
+and nothing starts it after a reboot. `herdrchat install` makes it a service of the
+system instead: a launchd agent on macOS, a systemd user unit on Linux. It starts at
+login, comes back by itself after a crash, and does not depend on any hc core. It runs
+node and the bot by their full paths with only the variables it needs (hc's path, PATH,
+the profile, the folders), so no agent's variables come along. With it installed,
+`start`, `stop` and `status` go through the service; `herdrchat uninstall` removes it.
+Each profile is its own service (`herdrchat install --profile telegram`).
+
+- After a node upgrade that moves node, run `herdrchat install` again; `herdrchat status`
+  says when the service's node is gone.
+- On Linux, `loginctl enable-linger` keeps it running after you log out.
+- What the process prints before its log is open (a crash at start) goes to
+  `logs/service.out.log` in the state folder.
 
 ## Optional: let the bot act as you
 
@@ -181,9 +280,10 @@ refreshed, the bot says so once and falls back.
 ## Skills
 
 `skills/herdrchat/` is one skill for an agent (Claude Code or another that reads
-`SKILL.md`): `/herdrchat setup`, `status`, `start`, `stop`, `logs`, `auth`, `config`, `fix`
-and `feishu <task>` (the developer console, with Ego Lite from https://lite.ego.app/ or as
-a guided walk-through). Details per part are in `skills/herdrchat/references/`. To use it
+`SKILL.md`): `/herdrchat setup`, `status`, `start`, `stop`, `install`, `logs`, `auth`,
+`config`, `fix`, `feishu <task>` (the developer console, with Ego Lite from
+https://lite.ego.app/ or as a guided walk-through) and `telegram <task>` (the bot, from
+@BotFather to the first topic). Details per part are in `skills/herdrchat/references/`. To use it
 with Claude Code, link it where skills are read, for example
 `ln -s "$PWD/skills/herdrchat" ~/.claude/skills/herdrchat`.
 
@@ -191,7 +291,7 @@ with Claude Code, link it where skills are read, for example
 
 Everything the bot logs goes to `logs/<YYYY-MM-DD>.log` in the state folder (one file a
 day, the last 14 kept) as `<time> <LEVEL> <text>`, besides its terminal: `grep ERROR
-~/.local/state/herdrchat/default/logs/*.log` finds
+~/.local/state/herdrchat/<profile>/logs/*.log` finds
 what went wrong, a retry that recovered is a `WARN`, and a crash leaves its stack there
 before it is started again. Tokens and secrets are never logged. The
 skill's `references/ops.md` explains the lines.
@@ -199,12 +299,15 @@ skill's `references/ops.md` explains the lines.
 ## Limits
 
 - Narration blocks are a condensed version of the text Claude showed, not the exact words.
-- Only Claude Code has a reader so far. codex, pi and the rest get their screen, at turn
-  end only, until each has a reader.
+- Only Claude Code has a reader so far. codex, pi and the rest post nothing by themselves
+  until each has a reader; what you type to them gets their screen in reply.
 - Only text, images and rich text are passed on; files, stickers and the rest are not.
 - An image that fails to upload three times is not sent; the group says so and why.
 - Feishu takes tag names of at most 16 characters; a longer session or machine name is cut
   at its last `-`, `_` or `.` that fits (`build-agent-server` becomes `build-agent`).
 - Avatars are drawn with `sips`, so only on macOS; elsewhere groups keep Feishu's default.
+- Telegram: a bot cannot mute a topic for you; a topic you mute in Telegram stays fully
+  quiet, "needs you" included. Closing a topic is documented for supergroups only, so an
+  ended topic is marked by its name.
 - Dialog buttons come from the screen's numbered menu; a dialog drawn some other way gets
   the screen and `/answer`, `/esc`.

package/lib/chats/contract.mjs

@@ -33,7 +33,7 @@ export const CHAT_MEMBERS = {
   editCard: '(message, look)',
   postDialog: '(room, dialog, value) -> message: dialog {title, markdown, menu, doneTitle}; each button sends value plus {pick, label}',
   closeDialog: '(message, dialog, done): no buttons any more, says what was done',
-  pin: '(k, room): the room waits for you',
+  pin: '(k, room, message): the room waits for you, on this message (its dialog card)',
   unpin: '(k)',
   pinned: '() -> k[]',
   ring: '(k, message, text): make the phone ring for this message if it would not',

package/lib/chats/feishu/client.mjs

@@ -69,14 +69,15 @@ async function createMessage(client, receiveIdType, receiveId, msgType, content)
 }
 
 // A markdown card per chunk; plain text when the card is refused. Returns the id of the
-// last message sent.
+// last message sent. `chatId` may be "open_id:<id>" for a person's direct chat.
 export async function sendMarkdown(client, chatId, text) {
+  const [idType, id] = chatId.startsWith('open_id:') ? ['open_id', chatId.slice(8)] : ['chat_id', chatId];
   let last = null;
   for (const part of chunk(text || '(empty)')) {
     try {
-      last = await createMessage(client, 'chat_id', chatId, 'interactive', card(part));
+      last = await createMessage(client, idType, id, 'interactive', card(part));
     } catch (err) {
-      last = await createMessage(client, 'chat_id', chatId, 'text', JSON.stringify({ text: part }));
+      last = await createMessage(client, idType, id, 'text', JSON.stringify({ text: part }));
       console.warn(`[feishu] card refused, sent as text: ${err.message}`);
     }
   }
@@ -258,7 +259,9 @@ export async function renameChat(client, chatId, name) {
 // Messages in (im.message.receive_v1) and card clicks (card.action.trigger), both over
 // the long connection. A click must be answered within 3 seconds; what `onCardAction`
 // returns ({toast, card}) is that answer.
-export function startEvents(cfg, onMessage, onCardAction, onReady = () => {}) {
+// onConnect runs at every connection, the first and each one after a drop; onMenu gets a
+// click on the bot's menu (application.bot.menu_v6: its event_key and who clicked).
+export function startEvents(cfg, onMessage, onCardAction, onReady = () => {}, onConnect = () => {}, onMenu = () => {}) {
   const ws = new Lark.WSClient({
     appId: cfg.appId,
     appSecret: cfg.appSecret,
@@ -266,9 +269,13 @@ export function startEvents(cfg, onMessage, onCardAction, onReady = () => {}) {
     onReady: () => {
       console.log('[feishu] connected');
       onReady();
+      onConnect();
     },
     onReconnecting: () => console.warn('[feishu] reconnecting'),
-    onReconnected: () => console.log('[feishu] reconnected'),
+    onReconnected: () => {
+      console.log('[feishu] reconnected');
+      onConnect();
+    },
     onError: (err) => console.error(`[feishu] connection failed: ${err.message}`),
   });
   ws.start({
@@ -280,6 +287,13 @@ export function startEvents(cfg, onMessage, onCardAction, onReady = () => {}) {
           console.error(`[feishu] message handler: ${err.stack || err.message}`);
         }
       },
+      'application.bot.menu_v6': async (data) => {
+        try {
+          await onMenu(data);
+        } catch (err) {
+          console.error(`[feishu] menu handler: ${err.stack || err.message}`);
+        }
+      },
       'card.action.trigger': async (data) => {
         try {
           return await onCardAction(data);

package/lib/chats/feishu/index.mjs

@@ -401,13 +401,40 @@ export function create({ cfg, store, log, logWarn, logError, stateDir, lane, sco
 
   // Messages (deduplicated, the owner's only) and card clicks, turned into the core's
   // shape: {room (null: the direct chat), where, message, text, images}.
+  //
+  // Feishu wants an event handled within 3 seconds or it pushes it again, so a message is
+  // taken at once and then handled in its chat's own queue (in order). Whether Feishu
+  // sends again what came while the bot was offline is not documented, so the bot looks
+  // itself: per chat it keeps the time of the last message it handled (state.json
+  // feishuRead), and at every connection it lists what came after that and handles what
+  // it missed.
   const seen = new Set();
+  const queues = new Map(); // chat -> its last queued message
+  function queued(chatId, fn) {
+    const next = (queues.get(chatId) || Promise.resolve()).then(fn).catch((err) => logError(`feishu message in ${chatId}:`, err));
+    queues.set(chatId, next);
+    next.then(() => { if (queues.get(chatId) === next) queues.delete(chatId); });
+  }
+  function markRead(chatId, at) {
+    const state = read();
+    if ((state.feishuRead?.[chatId] || 0) >= at) return;
+    state.feishuRead = { ...(state.feishuRead || {}), [chatId]: at };
+    write(state);
+  }
+
   function start({ onMessage, onAction, onReady }) {
-    const handleMessage = async (data) => {
+    const take = (data) => {
       const msg = data.message;
       if (seen.has(msg.message_id)) return;
       seen.add(msg.message_id);
-      if (seen.size > 1000) seen.delete(seen.values().next().value);
+      if (seen.size > 2000) seen.delete(seen.values().next().value);
+      queued(msg.chat_id, async () => {
+        await handleMessage(data);
+        markRead(msg.chat_id, Number(msg.create_time) || Date.now());
+      });
+    };
+    const handleMessage = async (data) => {
+      const msg = data.message;
       const openId = data.sender?.sender_id?.open_id;
       if (!cfg.ownerOpenId) {
         log(`owner not set; message from open_id ${openId}`);
@@ -437,7 +464,39 @@ export function create({ cfg, store, log, logWarn, logError, stateDir, lane, sco
       if (out.card?.kind === 'dialog') res.card = { type: 'raw', data: menuCard({ title: out.card.dialog.title, markdown: out.card.dialog.markdown, menu: out.card.dialog.menu, value: out.card.value }) };
       return res;
     };
-    startEvents(cfg, handleMessage, handleAction, onReady);
+    // What came while the bot was away: the owner's messages after the last one handled,
+    // in every chat it reads (a chat with none handled yet starts from now).
+    const catchUp = async () => {
+      if (!cfg.ownerOpenId) return;
+      const state = read();
+      const chats = new Set([...Object.values(state.chats || {}).filter((c) => !c.ended).map((c) => c.chat), ...Object.keys(state.feishuRead || {})]);
+      for (const chatId of chats) {
+        const since = state.feishuRead?.[chatId];
+        if (!since) {
+          markRead(chatId, Date.now());
+          continue;
+        }
+        try {
+          const res = await client.im.v1.message.list({ params: { container_id_type: 'chat', container_id: chatId, start_time: String(Math.floor(since / 1000)), sort_type: 'ByCreateTimeAsc', page_size: 50 } });
+          const missed = (res?.data?.items || []).filter((m) => Number(m.create_time) > since && m.sender?.sender_type === 'user' && m.sender?.id === cfg.ownerOpenId && !seen.has(m.message_id));
+          if (missed.length) log(`feishu: ${missed.length} message(s) in ${chatId} came while the bot was away`);
+          const p2p = !Object.values(state.chats || {}).some((c) => c.chat === chatId);
+          for (const m of missed) take({ message: { message_id: m.message_id, chat_id: chatId, chat_type: p2p ? 'p2p' : 'group', message_type: m.msg_type, content: m.body?.content || '{}', create_time: m.create_time }, sender: { sender_id: { open_id: m.sender.id } } });
+        } catch (err) {
+          logWarn(`feishu: could not look for missed messages in ${chatId}: ${err.message}`);
+        }
+      }
+    };
+    // The bot's menu (set in the developer console; direct chat only): an item that pushes
+    // an event with key "ls", "help" or "auth" works as that command sent in the direct chat.
+    const onMenu = async (data) => {
+      const openId = data.operator?.operator_id?.open_id;
+      const key = String(data.event_key || '').replace(/^\//, '');
+      if (!cfg.ownerOpenId || openId !== cfg.ownerOpenId || !/^[a-z]+$/.test(key)) return;
+      log(`feishu menu: /${key}`);
+      queued('menu', () => onMessage({ room: null, where: `open_id:${openId}`, message: `menu-${data.timestamp || Date.now()}`, text: `/${key}`, images: [] }));
+    };
+    startEvents(cfg, take, handleAction, onReady, () => catchUp().catch((err) => logError(`feishu catch-up: ${err.message}`)), onMenu);
     setInterval(() => asYou().catch((err) => logError(`as you: ${err.message}`)), YOU_CHECK_MS);
     asYou().catch((err) => logError(`as you: ${err.message}`));
   }

package/lib/chats/telegram/index.mjs

@@ -15,7 +15,7 @@
 //   buttons       callback_data holds 64 bytes, so a button carries a short id and the
 //                 dialog it answers is kept in state.json
 //   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
+//   pin           a topic cannot be pinned, so the dialog card is: pinned while it waits
 import crypto from 'node:crypto';
 import fs from 'node:fs';
 import { createClient } from './client.mjs';
@@ -204,9 +204,27 @@ export function create({ cfg, store, log, logWarn, logError }) {
 
   // ---------- attention ----------
 
-  const pins = new Set();
-  const pin = async (k) => { pins.add(k); };
-  const unpin = async (k) => { pins.delete(k); };
+  // A dialog card is pinned while it waits, as Feishu pins its group, and unpinned once
+  // it is answered; which message is pinned for which room is kept in state.json (pinned).
+  async function pin(k, room, message) {
+    if (!message) return;
+    try {
+      await tg.queued('pinChatMessage', { chat_id: owner, message_id: Number(message), disable_notification: true });
+      const state = read();
+      state.pinned = { ...(state.pinned || {}), [k]: String(message) };
+      write(state);
+    } catch (err) {
+      logError(`pin ${message}: ${err.message}`);
+    }
+  }
+  async function unpin(k) {
+    const message = read().pinned?.[k];
+    if (!message) return;
+    await tg.queued('unpinChatMessage', { chat_id: owner, message_id: Number(message) }).catch((err) => logError(`unpin ${message}: ${err.message}`));
+    const state = read();
+    delete state.pinned[k];
+    write(state);
+  }
 
   // In a quiet room this reply is what sounds; in another the post sounded already. A
   // space in HERDR_SILENT_SPACES never sounds.
@@ -344,9 +362,12 @@ export function create({ cfg, store, log, logWarn, logError }) {
   }
 
   // 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).
+  // and tries again (409: another copy of the bot polls the same token). Telegram keeps
+  // what the bot has not confirmed for 24 hours, so nothing sent while it was away is
+  // lost; which update it handled last is kept in state.json (telegramOffset), so after a
+  // restart nothing is handled twice.
   function start({ onMessage, onAction, onReady = () => {} }) {
-    let offset = 0;
+    let offset = read().telegramOffset || 0;
     let connected = false;
     (async () => {
       for (;;) {
@@ -365,13 +386,17 @@ export function create({ cfg, store, log, logWarn, logError }) {
           }
           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);
             }
+            // saved once handled: a crash halfway handles it again, never skips it
+            offset = u.update_id + 1;
+            const state = read();
+            state.telegramOffset = offset;
+            write(state);
           }
         } catch (err) {
           logError(`telegram poll: ${err.message}`);
@@ -409,7 +434,7 @@ export function create({ cfg, store, log, logWarn, logError }) {
     closeDialog,
     pin,
     unpin,
-    pinned: () => [...pins],
+    pinned: () => Object.keys(read().pinned || {}),
     ring,
     markWorking,
     markDone,

package/lib/core/engine.mjs

@@ -17,7 +17,7 @@
 //   post(room, markdown) -> message; reply(where, markdown)
 //   postCard(room, look) -> message; editCard(message, look)   look: {title, tone, markdown}
 //   postDialog(room, dialog, value) -> message; closeDialog(message, dialog, done)
-//   pin(k, room); unpin(k); pinned() -> keys; ring(k, message, text)
+//   pin(k, room, message); unpin(k); pinned() -> keys; ring(k, message, text)
 //   markWorking(message) -> token; markDone(message, token)
 //   image(buffer) -> markdown; download(message, ref, file)
 //   postFile(room, {name, data, caption}); postFolded(room, {title, markdown}); foldedBytes
@@ -623,7 +623,7 @@ export function createEngine({ cfg, chat, hc, readers, store, log, logWarn, logE
     if (!dialog.menu) {
       const sent = await postTo(session, record, `**${dialog.title}**\n\n${dialog.markdown}\n\nReply \`/answer <text>\` to answer it, or \`/esc\` to cancel it.`);
       const room = read().chats[k]?.chat;
-      if (room) await chat.pin(k, room);
+      if (room) await chat.pin(k, room, sent);
       await chat.ring(k, sent, '⚠️ needs you');
     } else {
       const message = await deliver(session, record, (room) => chat.postDialog(room, dialog, dialogValue(session, address, dialog)));
@@ -631,7 +631,7 @@ export function createEngine({ cfg, chat, hc, readers, store, log, logWarn, logE
         remember(message, dialog);
         openCard.set(k, { message, dialog });
         const room = read().chats[k]?.chat;
-        if (room) await chat.pin(k, room);
+        if (room) await chat.pin(k, room, message);
         await chat.ring(k, message, '⚠️ needs you');
         // answered while the card was on its way: nothing will close it later, so now
         const live = views.get(session)?.terminals.get(address);
@@ -797,6 +797,7 @@ export function createEngine({ cfg, chat, hc, readers, store, log, logWarn, logE
     if (now !== was) since.set(k, Date.now());
     if (now !== 'blocked') {
       postedDialog.delete(k);
+      if (now) sendWaiting(k);
       if (chat.pinned().includes(k)) later(session, address, 'unpin', () => chat.unpin(k));
       if (openCard.has(k)) later(session, address, 'dialog', () => closeCard(k, '✔ Answered.'));
       return;
@@ -888,6 +889,23 @@ export function createEngine({ cfg, chat, hc, readers, store, log, logWarn, logE
     }
   }
 
+  // Messages sent while it waited on a dialog with no box to type in, per terminal, kept
+  // in state.json (waiting) so a restart does not lose them; they go in, in order, once it
+  // no longer waits (onStatus, and at start).
+  function hold(k, m) {
+    const state = read();
+    state.waiting = { ...(state.waiting || {}), [k]: [...(state.waiting?.[k] || []), m] };
+    write(state);
+  }
+  function sendWaiting(k) {
+    const state = read();
+    const held = state.waiting?.[k];
+    if (!held?.length) return;
+    delete state.waiting[k];
+    write(state);
+    for (const m of held) laneOf(k, 'held message', () => typeInto(m.where, m.message, m.session, m.address, m.text));
+  }
+
   async function typeInto(where, message, session, address, text) {
     const record = views.get(session)?.terminals.get(address);
     if (!record || record.state !== 'live') {
@@ -908,16 +926,21 @@ export function createEngine({ cfg, chat, hc, readers, store, log, logWarn, logE
       return;
     }
     const answer = text.match(/^\/answer\s+([\s\S]+)$/);
-    if (!answer && agent && record.status?.state === 'blocked') {
+    // whether it waits on a dialog now: asked of hc, since the status followed from its
+    // events can be a moment behind (a dialog just answered still looks blocked)
+    const waits = !answer && agent && (await hc.getTerminal(session, address).catch(() => record))?.status?.state === 'blocked';
+    if (waits) {
       // It waits on a dialog: words go into its "Type something" box when it has one;
-      // otherwise the dialog card comes again, to pick there.
+      // otherwise they wait for the dialog to be answered, then go in (never dropped).
       const menu = menuOf(await hc.screenTail(session, address, SCREEN_LINES));
       if (menu?.free) {
         await answerFree(session, address, menu, text);
         log(`-> ${session}/${address}: answered ${text.slice(0, 80)}`);
         await markWorking(key(session, address), message);
       } else {
-        await postBlocked(session, address, record, { again: true });
+        hold(key(session, address), { where, message, session, address, text });
+        log(`-> ${session}/${address}: held until its dialog is answered: ${text.slice(0, 80)}`);
+        await chat.reply(where, 'It asks something first (the card above). Your message goes in once that is answered.');
       }
       return;
     }
@@ -1057,6 +1080,7 @@ export function createEngine({ cfg, chat, hc, readers, store, log, logWarn, logE
       const target = terminalOfRoom(room);
       if (!target) {
         log(`message in a room this bot did not make: ${room}`);
+        await chat.reply(where, 'Not delivered: this room is not a terminal\'s. Each terminal has its own room; the direct chat takes /ls, /new and /kill.');
         return;
       }
       if (views.get(target.session)?.terminals.get(target.address)?.state !== 'live') {
@@ -1083,6 +1107,11 @@ export function createEngine({ cfg, chat, hc, readers, store, log, logWarn, logE
     for (const session of cfg.sessions) watch(session);
     ready.then(() => setTimeout(async () => {
       await endGone().catch((err) => logError(`end gone rooms: ${err.message}`));
+      // messages held before a restart, for terminals that no longer wait
+      for (const k of Object.keys(read().waiting || {})) {
+        const address = addressOfKey(k);
+        if (!cfg.sessions.some((s) => views.get(s)?.terminals.get(address)?.status?.state === 'blocked')) sendWaiting(k);
+      }
       // pins left from before a restart, for terminals that no longer wait
       for (const k of chat.pinned()) {
         const address = addressOfKey(k);

package/lib/core/log.mjs

@@ -46,7 +46,10 @@ export function createLog(dir) {
   };
 
   log.capture = ({ onCrash } = {}) => {
-    console.log = (...args) => write('INFO', args);
+    // a library that prints its errors as plain log lines ("[error]: ...", as the Feishu
+    // SDK does) gets them logged as WARN, so `herdrchat logs --errors` finds them
+    const levelOf = (args) => (/^\[(error|warn)\]/i.test(String(args[0] ?? '')) ? 'WARN' : 'INFO');
+    console.log = (...args) => write(levelOf(args), args);
     console.info = console.log;
     console.warn = (...args) => write('WARN', args);
     console.error = (...args) => write('ERROR', args);

package/package.json

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

package/skills/herdrchat/references/feishu.md

@@ -107,6 +107,27 @@ Deactivate it first in the tenant admin console,
 `https://<tenant>.feishu.cn/admin/appCenter/manage/<APP_ID>` (needs a tenant admin),
 then delete it in the developer console. Ask before each of the two steps.
 
+### The bot menu (optional)
+
+A menu at the bottom of the direct chat with the bot, so the commands are a tap away as
+Telegram's "/" list is. Feishu sets it only in the developer console (no API), shows it
+in the direct chat only (not in groups), and needs a published version (then about five
+minutes, and a client of 5.27 or later).
+
+1. 应用能力 -> 机器人 -> 机器人自定义菜单: edit, turn it on (开启), pick a style.
+2. Add items whose action is 推送事件 (push an event), with these keys; the bot treats a
+   click as that command in the direct chat:
+   | Item | Event key |
+   |---|---|
+   | Overview | `ls` |
+   | Help | `help` |
+   | Act as me | `auth` |
+3. 事件与回调 -> 事件配置 (long connection mode, as for messages) -> 添加事件:
+   机器人自定义菜单事件 (`application.bot.menu_v6`).
+4. Publish a version. Ask before publishing.
+
+Commands that take words (`/new`, `/kill`) stay typed.
+
 ## Scopes this bot uses
 
 Bot identity (the bot itself) and user identity (only for `/auth`, acting as the user):

package/skills/herdrchat/references/telegram.md

@@ -39,6 +39,9 @@ Do these in order; the user does the Telegram steps, you check each one.
    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.
+7. **Make it a service.** Once it works: `herdrchat install --profile telegram`. It then
+   starts at login and comes back by itself after a crash, whatever happens to the hc
+   cores; `herdrchat status --profile telegram` says it runs as the service.
 
 ## What rings
 
@@ -61,7 +64,8 @@ without muting each topic by hand.
 | 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) |
+| pins the group that needs you | pins the dialog card in its topic until it is answered |
+| tags, labels, `/auth` | none (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 |