herdrchat 1.3.3 → 1.4.1

package/lib/chats/feishu/rooms/groups.mjs

@@ -0,0 +1,111 @@
+// HERDR_ROOMS=tab: one Feishu group per herdr-app tab, with you in it; what you type there
+// goes to its terminal. A room is the group's chat id. The group wears its space's avatar,
+// its tags and, acting as you, its mute and your label (decor.mjs); the group that needs
+// you is pinned. index.mjs calls only what is returned here, and a layout of rooms in
+// another file gives the same members.
+import { createChat, renameChat, replyMention } from '../client.mjs';
+import { inSpaces, spaceOfName } from './decor.mjs';
+
+export function createGroups({ client, cfg, store, logError, lane, scopeOf, userAuth, asYou, decor }) {
+  const { read, write } = store;
+  const entryOf = (k) => ({
+    get: () => read().chats[k],
+    set: (fields) => {
+      const state = read();
+      if (state.chats[k]) state.chats[k] = { ...state.chats[k], ...fields };
+      write(state);
+    },
+  });
+
+  async function openRoom({ name, intro }) {
+    return createChat(client, cfg.ownerOpenId, name, intro);
+  }
+
+  async function renameRoom(room, name) {
+    await renameChat(client, room, name);
+  }
+
+  // Puts a live group where it belongs: its avatar, its bot tag and, acting as you, muted
+  // and in your label. Cheap when nothing is left to do.
+  async function placeRoom(k, { space }) {
+    const entry = entryOf(k);
+    await decor.avatar(entry, space);
+    await decor.botTags(entry, scopeOf(k));
+    if (!(await asYou())) return;
+    await decor.mute(entry, space);
+    await decor.userLabel(entry, scopeOf(k));
+  }
+
+  // A group whose terminal is gone keeps its history, tagged "ended".
+  async function endRoom(k) {
+    const entry = entryOf(k);
+    const c = entry.get();
+    if (!c) return;
+    await decor.botTags(entry, scopeOf(k));
+    if (!c.avatar) await decor.avatar(entry, spaceOfName(c.name));
+    if (!(await asYou())) return;
+    await decor.mute(entry, spaceOfName(c.name));
+    await decor.userLabel(entry, scopeOf(k));
+  }
+
+  async function reviveRoom(k) {
+    const entry = entryOf(k);
+    await decor.botTags(entry, scopeOf(k));
+    await decor.userLabel(entry, scopeOf(k));
+  }
+
+  // Everything at once, when acting as you turns on: live groups to their labels, ended
+  // ones to "ended".
+  function alignAll() {
+    for (const [k, c] of Object.entries(read().chats)) {
+      if (!cfg.sessions.includes(c.session)) continue;
+      lane(k, 'as you', () => (c.ended ? endRoom(k) : placeRoom(k, { space: spaceOfName(c.name) })));
+    }
+  }
+
+  // The group that needs you is pinned while it waits (acting as you), and unpinned when
+  // it no longer does; which ones are pinned is kept in state.json (pinned).
+  async function pin(k, room) {
+    if (!(await asYou())) return;
+    try {
+      await userAuth.pin(room);
+      const state = read();
+      state.pinned = { ...(state.pinned || {}), [k]: room };
+      write(state);
+    } catch (err) {
+      logError(`pin ${room}: ${err.message}`);
+    }
+  }
+
+  async function unpin(k) {
+    const room = read().pinned?.[k];
+    if (!room) return;
+    try {
+      await userAuth.unpin(room);
+    } catch (err) {
+      logError(`unpin ${room}: ${err.message}`);
+    }
+    const state = read();
+    delete state.pinned[k];
+    write(state);
+  }
+
+  const pinned = () => Object.keys(read().pinned || {});
+
+  // In a muted group only a mention rings; a group that is not muted rings anyway. A
+  // space in HERDR_SILENT_SPACES gets no mention at all.
+  async function ring(k, message, text) {
+    const c = read().chats[k];
+    if (!message || !c?.muted || inSpaces(cfg.silent, spaceOfName(c.name)) || !(await asYou())) return;
+    await replyMention(client, message, cfg.ownerOpenId, text).catch((err) => logError(`mention: ${err.message}`));
+  }
+
+  // A message, to the core's words: the room it came from (null: the direct chat).
+  const roomOf = (msg) => (msg.chat_type === 'p2p' ? null : msg.chat_id);
+  // The chats whose messages the bot reads (to look for what it missed), and whether a
+  // chat is one of them rather than the direct chat.
+  const roomChats = () => Object.values(read().chats || {}).filter((c) => !c.ended).map((c) => c.chat);
+  const isRoomChat = (chatId) => Object.values(read().chats || {}).some((c) => c.chat === chatId);
+
+  return { roomWord: 'group', openRoom, renameRoom, placeRoom, endRoom, reviveRoom, alignAll, pin, unpin, pinned, ring, roomOf, roomChats, isRoomChat };
+}

package/lib/chats/telegram/index.mjs

@@ -53,7 +53,7 @@ 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 }) {
+export function create({ cfg, store, log, logWarn, logError, claimOwner = () => 'none' }) {
   const env = cfg.env || {};
   const owner = String(env.TELEGRAM_OWNER_ID || '').trim();
   const tg = createClient(env.TELEGRAM_BOT_TOKEN, { log: logWarn });
@@ -331,8 +331,13 @@ export function create({ cfg, store, log, logWarn, logError }) {
     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, `Hello! To make you this bot's owner (the only person it listens to), add this line to ${cfg.configFile || 'config.env'}:\n\n\`TELEGRAM_OWNER_ID=${from}\`\n\nthen run ${startAgain(cfg)}. Your terminals' topics appear then.`);
+      if (m.chat.type !== 'private') return;
+      // Telegram sends /start when someone first opens the bot: a command is never a guess
+      const paired = String(m.text || '').startsWith('/') ? 'none' : claimOwner(m.text, 'TELEGRAM_OWNER_ID', from);
+      log(`owner not set; message from user id ${from} (pairing: ${paired})`);
+      if (paired === 'ok') await reply(where, '✅ Paired: you are this bot\'s owner now. It starts again, and your terminals\' topics appear in a moment.\n\nThen: type in a terminal\'s topic to talk to it; here, /ls shows them all, /new starts one.');
+      else if (paired === 'wrong') await reply(where, 'That is not the code. Send the 6 digits `herdrchat setup` shows.');
+      else await reply(where, `Hello! This bot has no owner yet. Run \`herdrchat setup${cfg.profile && cfg.profile !== 'default' ? ` --profile ${cfg.profile}` : ''}\` and send me the code it shows; or add this line to ${cfg.configFile || 'config.env'} yourself and run ${startAgain(cfg)}:\n\n\`TELEGRAM_OWNER_ID=${from}\``);
       return;
     }
     if (from !== owner || String(m.chat.id) !== owner) {
@@ -394,6 +399,9 @@ export function create({ cfg, store, log, logWarn, logError }) {
               if (u.callback_query) await handleClick(u.callback_query, onAction);
             } catch (err) {
               logError(`telegram update ${u.update_id}:`, err);
+              // a message that could not be handled: you are told, never left guessing
+              const m = u.message;
+              if (m && String(m.from?.id || '') === owner) await reply(`${m.chat.id}:${m.is_topic_message ? m.message_thread_id : ''}`, `⚠️ Not delivered: it could not be handled (${err.message}). Send it again; \`herdrchat logs\` has the details.`).catch(() => {});
             }
             // saved once handled: a crash halfway handles it again, never skips it
             offset = u.update_id + 1;

package/lib/core/config.mjs

@@ -11,7 +11,8 @@
 //   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_SESSIONS                   hc sessions to mirror, comma-separated; empty: `default`,
+//                                    hc's own (with herdr-app it reaches every session it shows)
 //   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
@@ -76,6 +77,20 @@ function parseEnv(file) {
   return env;
 }
 
+// Sets one key in a config.env, keeping every other line (and its comments) as it was:
+// the key's line is replaced, or the key is added at the end. The file stays private.
+export function setConfigValue(file, key, value) {
+  const lines = fs.existsSync(file) ? fs.readFileSync(file, 'utf8').split('\n') : [];
+  const at = lines.findIndex((l) => new RegExp(`^\\s*${key}\\s*=`).test(l));
+  if (at >= 0) lines[at] = `${key}=${value}`;
+  else {
+    if (lines.length && lines[lines.length - 1] === '') lines.pop();
+    lines.push(`${key}=${value}`, '');
+  }
+  fs.writeFileSync(file, lines.join('\n'), { mode: 0o600 });
+  fs.chmodSync(file, 0o600);
+}
+
 // A list of spaces: `all`, empty or `none` for none, or the spaces listed. `fallback` is
 // what an unset variable means.
 export function spacesOf(value, fallback) {
@@ -105,19 +120,23 @@ export function onOff(value, fallback) {
 
 // `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.
-// `sessions: false`: an empty HERDR_SESSIONS is not an error (status shows what is set).
+// An empty HERDR_SESSIONS means hc's own session, `default` (`sessionsSet` says whether
+// it was named). `sessions: false` is kept for callers that only read what is set.
+export const DEFAULT_SESSION = 'default';
 export function loadConfig({ requires = [], sessions: needSessions = true } = {}) {
   const env = { ...parseEnv(CONFIG_FILE), ...process.env };
-  const sessions = (env.HERDR_SESSIONS || '').split(',').map((s) => s.trim()).filter(Boolean);
+  const named = (env.HERDR_SESSIONS || '').split(',').map((s) => s.trim()).filter(Boolean);
+  const sessions = named.length ? named : [DEFAULT_SESSION];
   const missing = requires.filter((k) => !env[k]);
   if (missing.length) throw new Error(`${missing.join(', ')} ${missing.length > 1 ? 'are' : 'is'} empty in ${CONFIG_FILE}: fill ${missing.length > 1 ? 'them' : 'it'} in (the comment above each says where it comes from), then start again.`);
-  if (needSessions && !sessions.length) throw new Error(`HERDR_SESSIONS is empty in ${CONFIG_FILE}: put the hc sessions to mirror there, comma-separated (\`ls ~/.local/state/herdr-core\` lists the sessions on this machine), then start again.`);
+  void needSessions; // an empty list is `default` now: never an error here
   return {
     profile: places.profile,
     configFile: CONFIG_FILE,
     chat: env.HERDRCHAT_CHAT || 'feishu',
     env,
     sessions,
+    sessionsSet: named.length > 0,
     appId: env.FEISHU_APP_ID || '',
     appSecret: env.FEISHU_APP_SECRET || '',
     ownerOpenId: env.FEISHU_OWNER_OPEN_ID || '',

package/lib/core/engine.mjs

@@ -567,7 +567,8 @@ export function createEngine({ cfg, chat, hc, readers, store, log, logWarn, logE
     const markdown = menu ? escapeMarkdown(menu.text) : `\`\`\`\n${tidyScreen(screenText, DIALOG_LINES)}\n\`\`\``;
     return { menu, title, markdown, doneTitle: DONE_TITLE };
   }
-  const dialogValue = (session, address, dialog) => ({ s: session, a: address, k: dialog.menu.key });
+  // c: the terminal's width when the card was made, to tell a resize from a new dialog
+  const dialogValue = (session, address, dialog, cols) => ({ s: session, a: address, k: dialog.menu.key, ...(cols ? { c: cols } : {}) });
 
   // One dialog gets one card. A dialog is named by its menu key (or, with no menu, by its
   // status words); the name is claimed before anything is sent, so the turn event, a
@@ -620,6 +621,16 @@ export function createEngine({ cfg, chat, hc, readers, store, log, logWarn, logE
       return;
     }
     if (!claimDialog(k, dialog, record.status) && !again) return;
+    try {
+      await sendBlocked(session, address, record, k, dialog);
+    } catch (err) {
+      // not posted: let the next event (or a held message) post it, never "posted already"
+      if (postedDialog.get(k) === dialogName(dialog, record.status)) postedDialog.delete(k);
+      throw err;
+    }
+    log(`<- ${session}/${address}: blocked${dialog.menu ? ` (${dialog.menu.options.length} options)` : ''}`);
+  }
+  async function sendBlocked(session, address, record, k, dialog) {
     await closeCard(k, 'It moved on; see the next card.');
     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.`);
@@ -627,7 +638,7 @@ export function createEngine({ cfg, chat, hc, readers, store, log, logWarn, logE
       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)));
+      const message = await deliver(session, record, (room) => chat.postDialog(room, dialog, dialogValue(session, address, dialog, record.cols)));
       if (message) {
         remember(message, dialog);
         openCard.set(k, { message, dialog });
@@ -637,9 +648,10 @@ export function createEngine({ cfg, chat, hc, readers, store, log, logWarn, logE
         // answered while the card was on its way: nothing will close it later, so now
         const live = views.get(session)?.terminals.get(address);
         if (live?.status?.state !== 'blocked' || postedDialog.get(k) !== dialogName(dialog, record.status)) await closeCard(k, '✔ Answered.');
+      } else {
+        throw new Error('the room for its card is gone');
       }
     }
-    log(`<- ${session}/${address}: blocked${dialog.menu ? ` (${dialog.menu.options.length} options)` : ''}`);
   }
 
   // The keys that pick an option: its digit, or, in a question with previews (which takes
@@ -664,7 +676,7 @@ export function createEngine({ cfg, chat, hc, readers, store, log, logWarn, logE
   // unless it still shows the dialog the card was made from (same key) with the same
   // option. After the key, the card turns into the dialog's next step (the next question,
   // the review, a toggled box) or says what was picked.
-  async function onAction({ value: v = {}, message, answer = '' }) {
+  async function onAction({ value: v = {}, message, answer = '', ticks = null }) {
     const started = Date.now();
     const shown = dialogCards.get(message) || { title: NEEDS_TITLE, markdown: '', doneTitle: DONE_TITLE };
     // A box in a multi-select is ticked on the card only, at once; Next sends them all.
@@ -680,25 +692,37 @@ export function createEngine({ cfg, chat, hc, readers, store, log, logWarn, logE
       log(`-> ${v.s}/${v.a}: click on ${message} not pressed: the terminal has ended`);
       return answered(shown, 'The terminal has ended.');
     }
-    const status = (await hc.getTerminal(v.s, v.a)).status;
+    const term = await hc.getTerminal(v.s, v.a);
+    const status = term.status;
     const menu = status?.state === 'blocked' ? menuOf(await hc.screenTail(v.s, v.a, SCREEN_LINES)) : null;
+    const k = key(v.s, v.a);
     if (!menu || menu.key !== v.k) {
-      log(`-> ${v.s}/${v.a}: click on ${message} not pressed: ${menu ? `the dialog changed (card ${v.k}, screen ${menu.key})` : `nothing waits (status ${status?.state || 'none'})`}`);
-      if (menu) later(v.s, v.a, 'dialog', () => postBlocked(v.s, v.a, { ...record, status }));
-      return answered(shown, menu ? 'It now asks something else; see the new card.' : 'It no longer waits on this.');
+      log(`-> ${v.s}/${v.a}: click on ${message} not pressed: ${menu ? `the dialog changed (card ${v.k}, screen ${menu.key}; width then ${v.c || '?'}, now ${term.cols || '?'})` : `nothing waits (status ${status?.state || 'none'})`}`);
+      if (!menu) return answered(shown, 'It no longer waits on this.');
+      // The card in your hand becomes what the screen asks now, to tap again. Never "see the
+      // new card": a new card can be held back as already posted, and then nothing is left
+      // to answer while your messages wait on the dialog.
+      const now = dialogOf(status, await hc.screenTail(v.s, v.a, SCREEN_LINES));
+      if (!now.menu) return answered(shown, 'It no longer waits on this.');
+      if (openCard.get(k) && openCard.get(k).message !== message) await closeCard(k, 'It moved on; see the next card.');
+      postedDialog.set(k, dialogName(now, status));
+      remember(message, now);
+      openCard.set(k, { message, dialog: now });
+      return { ...toast('warning', 'It changed before your tap, so nothing was pressed. The card shows it now: tap again.'), card: { kind: 'dialog', dialog: now, value: dialogValue(v.s, v.a, now, term.cols) } };
     }
-    const k = key(v.s, v.a);
     if (openCard.get(k)?.message === message) openCard.delete(k);
     let picked;
     if (v.pick === 'tab' && shown.menu?.multi) {
-      // the boxes the card shows, made so on the screen: each one that differs is pressed
-      const changed = shown.menu.options.filter((o) => o.checked !== null && o.checked !== menu.options.find((m) => m.n === o.n)?.checked);
+      // the boxes as ticked on the card (sent with Next by a form, or kept per tap), made
+      // so on the screen: each one that differs is pressed
+      const wanted = ticks ? { ...shown.menu, options: shown.menu.options.map((o) => (o.checked === null ? o : { ...o, checked: Boolean(ticks[o.n]) })) } : shown.menu;
+      const changed = wanted.options.filter((o) => o.checked !== null && o.checked !== menu.options.find((m) => m.n === o.n)?.checked);
       for (const o of changed) {
         await hc.keys(v.s, v.a, [String(o.n)]);
         await sleep(BOX_GAP_MS);
       }
       await hc.keys(v.s, v.a, ['tab']);
-      const ticked = shown.menu.options.filter((o) => o.checked).map((o) => o.label);
+      const ticked = wanted.options.filter((o) => o.checked).map((o) => o.label);
       picked = ticked.length ? ticked.join(', ') : 'nothing ticked';
     } else if (v.pick === 'esc' || v.pick === 'tab') {
       await hc.keys(v.s, v.a, [v.pick]);
@@ -738,9 +762,16 @@ export function createEngine({ cfg, chat, hc, readers, store, log, logWarn, logE
       if (next.menu && (next.menu.key === v.k || claimDialog(k, next, nextStatus))) {
         remember(message, next);
         openCard.set(k, { message, dialog: next });
-        return { ...toast('info', `✔ ${picked}`), card: { kind: 'dialog', dialog: next, value: dialogValue(v.s, v.a, next) } };
+        return { ...toast('info', `✔ ${picked}`), card: { kind: 'dialog', dialog: next, value: dialogValue(v.s, v.a, next, term.cols) } };
+      }
+      // its card is out already, unless that card was closed: then this one shows it
+      if (next.menu && openCard.has(k)) return answered(shown, `✔ ${picked}`);
+      if (next.menu) {
+        postedDialog.set(k, dialogName(next, nextStatus));
+        remember(message, next);
+        openCard.set(k, { message, dialog: next });
+        return { ...toast('info', `✔ ${picked}`), card: { kind: 'dialog', dialog: next, value: dialogValue(v.s, v.a, next, term.cols) } };
       }
-      if (next.menu) return answered(shown, `✔ ${picked}`); // its card is out already
       // still waiting, on something with no menu: hc sends no new turn for it, so post it
       later(v.s, v.a, 'dialog', () => postBlocked(v.s, v.a, { ...record, status: nextStatus }));
     }
@@ -939,9 +970,16 @@ export function createEngine({ cfg, chat, hc, readers, store, log, logWarn, logE
         log(`-> ${session}/${address}: answered ${text.slice(0, 80)}`);
         await markWorking(key(session, address), message);
       } else {
-        hold(key(session, address), { where, message, session, address, text });
+        const k = key(session, address);
+        hold(k, { 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.');
+        // "the card above" must be there: with a menu and no open card, post it now
+        const status = (await hc.getTerminal(session, address).catch(() => record))?.status;
+        if (menu && !openCard.has(k)) {
+          logWarn(`${session}/${address}: waits on a dialog with no open card; posting it again`);
+          await postBlocked(session, address, { ...record, status }, { again: true }).catch((err) => logError(`dialog card for ${session}/${address} not posted (${err.message})`));
+        }
+        await chat.reply(where, openCard.has(k) || !menu ? 'It asks something first (the card above). Your message goes in once that is answered.' : 'It asks something first, in herdr-app (its card could not be posted here). Your message goes in once that is answered.');
       }
       return;
     }

package/lib/core/menu.mjs

@@ -39,8 +39,10 @@ function topOf(lines, first) {
 
 const MARKS = /[☐☑☒✔✓✗✘■□●○◉◯]/gu;
 
+// Joined with spaces, not line breaks: the same dialog wraps at other places when the
+// terminal is resized (herdr-app opened on a phone), and it is still the same dialog.
 function keyOf(lines, top, last) {
-  const body = lines.slice(top, last + 1).map((l) => l.replace(/❯/g, '').replace(/^(\s*\d{1,2}\.\s+)\[.\]/, '$1').replace(MARKS, '').replace(/\s+/g, ' ').trim()).join('\n');
+  const body = lines.slice(top, last + 1).map((l) => l.replace(/❯/g, '').replace(/^(\s*\d{1,2}\.\s+)\[.\]/, '$1').replace(MARKS, '')).join(' ').replace(/\s+/g, ' ').trim();
   return crypto.createHash('sha1').update(body).digest('hex').slice(0, 12);
 }
 

package/lib/core/pairing.mjs

@@ -0,0 +1,35 @@
+// Pairing: how the bot learns who its owner is without anyone copying an id. `herdrchat
+// setup` shows a short code and keeps it in state.json; the first person who sends that
+// code to the bot becomes its owner. The code lasts PAIR_MINUTES and allows PAIR_TRIES
+// wrong guesses, so nobody can guess their way in.
+import crypto from 'node:crypto';
+
+export const PAIR_MINUTES = 15;
+export const PAIR_TRIES = 5;
+
+// store: {read, write} of state.json
+export function startPairing(store, now = Date.now()) {
+  const code = String(crypto.randomInt(0, 1000000)).padStart(6, '0');
+  const state = store.read();
+  state.pairing = { code, until: now + PAIR_MINUTES * 60 * 1000, tries: 0 };
+  store.write(state);
+  return code;
+}
+
+// 'ok' (the code, used up), 'wrong' (a guess counted), or 'none' (no pairing running)
+export function tryPairing(store, text, now = Date.now()) {
+  const state = store.read();
+  const p = state.pairing;
+  if (!p || now > p.until) return 'none';
+  if (String(text || '').trim() === p.code) {
+    delete state.pairing;
+    store.write(state);
+    return 'ok';
+  }
+  p.tries = (p.tries || 0) + 1;
+  if (p.tries >= PAIR_TRIES) delete state.pairing;
+  store.write(state);
+  return 'wrong';
+}
+
+export const pairingRunning = (store, now = Date.now()) => Boolean(store.read().pairing && now <= store.read().pairing.until);

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "herdrchat",
-  "version": "1.3.3",
-  "description": "A chat front-end for herdr: every terminal hc runs, in Feishu or Telegram",
+  "version": "1.4.1",
+  "description": "The chat client for hc (herdr): see and answer every hc terminal from Feishu or Telegram",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/zhangxiangliang/herdrchat.git"

package/skills/herdrchat/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: herdrchat
 description: >-
-  Set up, run and look after herdrchat, which mirrors every herdr-app (hc) tab into
+  Set up, run and look after herdrchat, the chat client for hc (herdr), which mirrors every herdr-app tab into
   Feishu (a group per tab) or Telegram (a topic per tab): first setup of either app,
   start, stop, status, logs, running it as a service, settings, fixing problems, the
   Feishu developer console and @BotFather. Use for anything about herdrchat or its
@@ -29,7 +29,7 @@ from the package (`config.env.example`, `docs/guide.md`) are in the installed pa
 
 | Command | Do |
 |---|---|
-| `/herdrchat setup` | First check herdr is there (`command -v hc`): herdrchat is built on herdr and does nothing without it; when it is missing, say so, point to https://herdr.dev, and stop until it is installed. Then ask which chat app (Feishu, Telegram, or both: the second one on its own profile). Telegram: `/herdrchat telegram setup`. Feishu, in this order: create the app, the bot ability and the scopes (`references/feishu.md`); `herdrchat init` and fill `config.env` with the user (App ID, App Secret, `HERDR_SESSIONS`: `ls ~/.local/state/herdr-core` lists the sessions); `herdrchat start` (the console's long-connection check needs it running); events and callbacks; publish a version; the user messages the bot and adds the `FEISHU_OWNER_OPEN_ID` line it answers with; `herdrchat start` again; offer `/herdrchat auth` and `herdrchat install`. |
+| `/herdrchat setup` | First check herdr is there (`command -v hc`): herdrchat is built on herdr and does nothing without it. When it is missing, offer to install it and, on a yes, follow `references/herdr.md` (from herdr's own instructions, read now, each command shown and agreed first). Then ask which chat app (Feishu, Telegram, or both: the second one on its own profile). Telegram: `/herdrchat telegram setup`. Feishu, in this order (with ego-browser the agent clicks the console; without it, offer to install Ego Lite or walk the user through it, `references/feishu.md` "Before anything"): create the app, the bot ability and the scopes; `herdrchat init` and fill `config.env` with the user (App ID, App Secret; `HERDR_SESSIONS` empty means hc's default session, `ls ~/.local/state/herdr-core` lists the sessions); `herdrchat start` (the console's long-connection check needs it running); events and callbacks; publish a version; `herdrchat pair` (in the background: it prints a 6-digit code and waits; the user sends the code to the bot, which writes `FEISHU_OWNER_OPEN_ID` itself and starts again; it also proves the events work); offer `/herdrchat auth` and `herdrchat install`. Never run `herdrchat setup` yourself: it asks questions in a terminal, and this shell has none. It is the same steps for a user without an agent; yours add the Feishu console through ego-browser. When there is no hc session yet, say so and stop until herdr runs one. |
 | `/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. With a service installed they go through it. |
 | `/herdrchat install`, `/herdrchat uninstall` | Run it as a service of the system (launchd on macOS, systemd on Linux): it starts at login and comes back after a crash, whatever happens to the hc cores. Recommended once it works. Read the config first; after a node upgrade, install again (`herdrchat status` says so). |
@@ -55,6 +55,8 @@ 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/herdr.md`: what herdrchat is built on, and installing herdr with the user
+  when hc is missing.
 - `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

package/skills/herdrchat/references/feishu.md

@@ -6,13 +6,20 @@ that with ego-browser, in the user's own logged-in browser.
 
 ## Before anything
 
-1. **ego-browser.** Run `command -v ego-browser`. When it is there, run
+1. **ego-browser, or the guide.** Only Feishu needs this (Telegram's bot is made in a
+   chat, with no browser). Run `command -v ego-browser`. When it is there, run
    `ego-browser skill` and follow its usage guide. When it is missing, do not fall back
    to another browser; ask the user which they want:
-   - install Ego Lite (https://lite.ego.app/), sign in to Feishu in it, and ask again,
-     so the agent does the clicking; or
-   - a guided walk-through instead (see "Guide mode" below): the user clicks, the agent
-     says what to click.
+   - **Install Ego Lite**, so the agent does the clicking. Use Ego's own instructions,
+     read now at https://lite.ego.app/ (not from memory): say what it installs, and
+     install only on a yes. Then check `command -v ego-browser` again (a new folder may
+     need a new shell), and have the user sign in to Feishu in Ego as an admin of the
+     tenant. If any of it fails or the user stops, take the guide below; do not retry
+     other ways.
+   - **The guide** ("Guide mode" below): the user clicks, the agent says what to click.
+   Either way is the same procedures. When Ego stops working in the middle (signed out,
+   a page that does not match), say so and go on in guide mode from that step: what is
+   done stays done.
 2. **Which profile.** Ask which Ego profile is signed in to Feishu as an admin of the
    tenant that owns the app (`await profiles()` lists them); never guess. Create one task
    space for the whole job with that `profileId`, and close it at the end with
@@ -20,7 +27,9 @@ that with ego-browser, in the user's own logged-in browser.
 3. **Which app.** The app id is `FEISHU_APP_ID` in the profile's `config.env`
    (`~/.config/herdrchat/<profile>/config.env`, or in `HERDRCHAT_HOME`). Read only that
    key; never print, screenshot or paste `FEISHU_APP_SECRET`, and never write a real app
-   id, open_id, chat id or tenant name into a file of this repo.
+   id, open_id, chat id or tenant name into a file of this repo. With Ego too, the agent
+   does not read or reveal the secret on the credentials page: the user copies it into
+   `config.env` themselves (the agent says the file and the line).
 4. **Ask first** before anything outward-facing: publishing a version, applying scopes,
    deleting or deactivating an app. One yes covers one action.
 

package/skills/herdrchat/references/herdr.md

@@ -0,0 +1,33 @@
+# herdr: what herdrchat is built on, and putting it in place
+
+herdrchat mirrors the terminals that **hc** (herdr-core) runs; **herdr-app** is herdr's
+desktop and phone app that shows them in spaces and tabs. Without hc on the machine
+herdrchat does nothing. Check: `command -v hc && hc --version`.
+
+When hc is missing, help the user install it. Do it from herdr's own instructions, read
+now, never from memory or a script kept here: install steps change, and a fixed script
+breaks on another system or version.
+
+## Installing it, with the user
+
+1. **Say what and why.** "herdrchat is built on herdr: it mirrors the terminals that hc
+   runs. hc is not on this machine. Shall I install herdr for you?" Wait for a yes.
+2. **Read the official way, now.** Open https://herdr.dev and follow its install or
+   download instructions for this system (macOS or Linux; say so if it is neither). Use
+   only what herdr's own site or its official releases give. If the page does not say
+   how, stop and tell the user where you looked.
+3. **Show before running.** Give the user the exact command or download, where it comes
+   from, where it installs, and what it changes (a folder, the PATH, a login item).
+   When the instructions pipe a script into a shell, download the script first and read
+   it, then say what it does. Run it only after the user says yes to that command.
+4. **Check it worked.** `hc --version` answers. If hc is not found, the new folder may
+   not be on PATH yet in this shell: say which folder, and how the instructions add it.
+5. **A first session.** `hc ls` (or the instructions' own first step) starts the default
+   session; `ls ~/.local/state/herdr-core` then lists it. herdrchat's `HERDR_SESSIONS`
+   names the sessions to mirror. herdr-app is optional for herdrchat but is how terminals
+   get their space and tab names; offer it when the user wants the desktop app too.
+6. **On a failure, stop.** Show the error as it is and what was tried. Do not try other
+   install ways the user did not agree to, and never run anything with sudo without
+   asking for that command.
+
+Then go back to `/herdrchat setup`.

package/skills/herdrchat/references/ops.md

@@ -79,7 +79,7 @@ your token after `/auth`: never print it.
 
 | You see | Likely cause | Do |
 |---|---|---|
-| nothing posts | bot down, or the owner not set (`FEISHU_OWNER_OPEN_ID`, `TELEGRAM_OWNER_ID`) | `herdrchat status`; the log says "owner not set" |
+| nothing posts | bot down, or the owner not set (`FEISHU_OWNER_OPEN_ID`, `TELEGRAM_OWNER_ID`) | `herdrchat status`; the log says "owner not set": `herdrchat pair` |
 | Telegram: no topic appears | topic mode off | log: "topic mode is off"; BotFather's mini app, the bot, Threaded Mode, then start again |
 | Telegram: `telegram poll: ... 409` | another copy polls the same token | stop it (another machine?), then start once |
 | a button gives error 200340 | the card callback is not set up | `references/feishu.md`: events and card callbacks |

package/skills/herdrchat/references/telegram.md

@@ -19,18 +19,20 @@ Do these in order; the user does the Telegram steps, you check each one.
 2. **The config.** `herdrchat init --chat telegram P` makes the profile's `config.env`
    (private) and prints where it is. Ask the user to paste the token after
    `TELEGRAM_BOT_TOKEN=` themselves (`open -e <file>` opens it), no quotes, no spaces, and
-   fill `HERDR_SESSIONS` with them (`ls ~/.local/state/herdr-core` lists the sessions).
+   leave `HERDR_SESSIONS` empty for hc's default session, or name others
+   (`ls ~/.local/state/herdr-core` lists the sessions).
 3. **Topic mode, checked before the first start.** 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. Check it without
    printing the token: a short `node -e` reads the token from the config, calls
    `https://api.telegram.org/bot<token>/getMe` and prints only `username` and
    `has_topics_enabled`, which must be `true`.
-4. **First start, to learn the owner.** `herdrchat start P`; the user messages the bot
-   anything; it answers with the line to add, `TELEGRAM_OWNER_ID=<digits>`, and where the
-   file is. The user adds it. Until then the bot makes no topic.
-5. **Start again.** Read the config (secrets hidden) in one step, then
-   `herdrchat start P` in the next. One topic per tab appears; Telegram takes about one
+4. **Start, then pair the owner.** Read the config (secrets hidden) in one step, then
+   `herdrchat start P` in the next. Then run `herdrchat pair P` in the background: it
+   prints a 6-digit code and waits. Tell the user the code; they open the bot (tap
+   Start), send it, and the bot writes `TELEGRAM_OWNER_ID` itself and starts again as
+   theirs. Until then the bot makes no topic. No id to copy.
+5. **The topics.** 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.
 6. **Make it a service.** Once it works: `herdrchat install P`. It then starts at login
@@ -68,7 +70,7 @@ without muting each topic by hand.
 | Seen | Cause | Do |
 |---|---|---|
 | log: `topic mode is off for @<bot>` | step 3 not done | turn it on in BotFather's mini app, check `has_topics_enabled`, start again |
-| the bot answers "To make you this bot's owner…" | `TELEGRAM_OWNER_ID` empty | step 4 |
+| the bot answers "This bot has no owner yet" | `TELEGRAM_OWNER_ID` empty | step 4: `herdrchat pair P` |
 | `herdrchat start` says it did not reach its chat app | wrong token, or no network | check with getMe (step 3) |
 | log: `telegram poll: ... 409` | another copy polls the same token | `herdrchat stop P`, 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 |