herdrchat 1.2.1 → 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

@@ -35,12 +35,56 @@ A Telegram bot cannot make groups, so it uses topics in your private chat with t
 | 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: an image goes as its own photo after the text (a message cannot hold one);
-a dialog's free answer is typed in the topic (a message has no text box); there are no
-tags, labels, pins or `/auth` (a bot cannot act as you). Telegram takes about one message
-a second in a chat, so the bot queues and waits as Telegram asks. Setting it up:
+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:
@@ -151,8 +195,10 @@ 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).
+  `--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
@@ -185,7 +231,9 @@ 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. Once it works: `herdrchat install` (see "Running as a service").
+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
 

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,8 +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.
-// onConnect runs at every connection, the first and each one after a drop.
-export function startEvents(cfg, onMessage, onCardAction, onReady = () => {}, onConnect = () => {}) {
+// 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,
@@ -285,6 +287,13 @@ export function startEvents(cfg, onMessage, onCardAction, onReady = () => {}, on
           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

@@ -487,7 +487,16 @@ export function create({ cfg, store, log, logWarn, logError, stateDir, lane, sco
         }
       }
     };
-    startEvents(cfg, take, handleAction, onReady, () => catchUp().catch((err) => logError(`feishu catch-up: ${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.
@@ -416,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);

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.1",
+  "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

@@ -64,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 |