herdrchat 1.3.3 → 1.4.1

package/README.md

@@ -2,7 +2,7 @@
 
 # herdrchat
 
-A chat front-end for [herdr](https://herdr.dev): every terminal it runs, in Feishu or Telegram.
+The chat client for hc ([herdr](https://herdr.dev)): see and answer every hc terminal from Feishu or Telegram.
 
 [English](README.md) · [简体中文](README.zh.md)
 
@@ -12,13 +12,15 @@ A chat front-end for [herdr](https://herdr.dev): every terminal it runs, in Feis
 
 </div>
 
+**herdr-app is hc's desktop and phone client; herdrchat is hc's chat client.**
+
 [herdr](https://herdr.dev) runs your coding agents (Claude Code, codex, pi, …) in
-terminals that stay alive: **hc** (herdr-core) keeps them running, **herdr-app** shows
-them in spaces and tabs. herdr-app has phone and desktop apps, but your phone has to
+terminals that stay alive: **hc** (herdr-core) keeps them running, and herdr-app shows
+them in spaces and tabs. But to use herdr-app away from your desk, your phone has to
 reach the machine that runs hc, so you first need a VPN or a private network, and working
 with an agent on a small phone screen is clumsy.
 
-herdrchat puts them in a chat app instead. It connects out to Feishu or Telegram by
+herdrchat shows the same terminals in a chat app you already have on your phone. It connects out to Feishu or Telegram by
 itself, so there is nothing to set up on your network: no public IP, no VPN. Each
 herdr-app tab gets its own Feishu group, or a topic in your private chat with the
 Telegram bot. You read what the agent says while it works, tap buttons to answer its
@@ -32,8 +34,9 @@ until herdrchat learns to read their conversations too.
 ## You need
 
 - **herdr**: herdrchat is built on it and does nothing without it. Install it from
-  [herdr.dev](https://herdr.dev) first; its **hc** must run on this machine, with at least
-  one session.
+  [herdr.dev](https://herdr.dev) first (or let your coding agent do it with you:
+  `/herdrchat setup` offers to); its **hc** must run on this machine, with at least one
+  session.
 - **Node.js 20** or newer, on **macOS or Linux**.
 - **Feishu**: a Feishu team (not Lark) where you may create a custom app and publish it.
   **Telegram**: a Telegram account. Use one app, or both at once.
@@ -58,17 +61,21 @@ reach the agent.
 **With your agent:** ask it `/herdrchat setup`. It asks which chat app, then walks you
 through everything, clicking in the Feishu console for you when it can.
 
-**By hand:**
+**In the terminal** (the same steps, asked one by one; the agent can also click through
+the Feishu console for you, with the [Ego Lite](https://lite.ego.app/) browser, which the
+terminal cannot; without Ego it tells you what to click):
 
 ```bash
-herdrchat init --chat telegram   # or --chat feishu; it prints where the settings file is
-# fill in that file (each line says where its value comes from), then:
-herdrchat start                  # starts it and waits until it is connected
-herdrchat install                # once it works: start at login, come back after a crash
+herdrchat setup
 ```
 
-The steps for each app (making the Feishu app, or the Telegram bot) are in the
-[guide](docs/guide.md#set-up-telegram).
+It asks which chat app, takes the bot's token (or the Feishu app's keys) and checks them
+at once, picks your hc sessions (`default` unless you say otherwise), starts the bot, and
+shows a 6-digit code: send it to the bot and it knows you are its owner. Last, it offers
+to keep it running as a service. No file to edit, no id to copy.
+
+Making the Telegram bot or the Feishu app, and doing it all by editing the settings file
+instead: the [guide](docs/guide.md#set-up-telegram).
 
 ## Use
 
@@ -86,7 +93,7 @@ start a terminal, `/kill` to end one.
 | `/herdrchat feishu <task>` | Does a task in the Feishu developer console (with the [Ego Lite](https://lite.ego.app/) browser, or step by step). |
 | `/herdrchat telegram <task>` | The Telegram bot, from @BotFather to the first topic. |
 
-On the command line: `herdrchat init`, `start`, `stop`, `status`, `logs`, `install`,
+On the command line: `herdrchat setup`, `pair`, `init`, `start`, `stop`, `status`, `logs`, `install`,
 `uninstall`, `version`; `herdrchat` alone lists them. Add `--profile <name>` to run a
 second chat app beside the first.
 

package/README.zh.md

@@ -2,7 +2,7 @@
 
 # herdrchat
 
-[herdr](https://herdr.dev) 的聊天前端：它跑的每个终端，都能在飞书或 Telegram 里看到和回复。
+hc（[herdr](https://herdr.dev)）的聊天客户端：在飞书或 Telegram 里查看和回复 hc 的每一个终端。
 
 [English](README.md) · [简体中文](README.zh.md)
 
@@ -12,11 +12,13 @@
 
 </div>
 
+**herdr-app 是 hc 的电脑和手机客户端；herdrchat 是 hc 的聊天客户端。**
+
 [herdr](https://herdr.dev) 让你的编程 agent（Claude Code、codex、pi……）跑在不会断的终端里：
-**hc**（herdr-core）让它们一直跑着，**herdr-app** 按空间和标签页把它们展示出来。herdr-app 有手机端和电脑端，
-但手机得能连到跑 hc 的机器，所以要先折腾 VPN 或内网；而且在手机的小屏幕上和 agent 交互，体验并不好。
+**hc**（herdr-core）让它们一直跑着，herdr-app 按空间和标签页把它们展示出来。
+但想在外面用 herdr-app，手机得能连到跑 hc 的机器，所以要先折腾 VPN 或内网；而且在手机的小屏幕上和 agent 交互，体验并不好。
 
-herdrchat 把它们搬进聊天软件。它自己主动连到飞书或 Telegram，网络上什么都不用配：不要公网 IP，也不要 VPN。
+herdrchat 把同样这些终端，放进你手机上本来就有的聊天软件里。它自己主动连到飞书或 Telegram，网络上什么都不用配：不要公网 IP，也不要 VPN。
 herdr-app 的每个标签页，在飞书里是一个群，在 Telegram 里是和 bot 私聊中的一个话题：
 agent 干活时说的话实时可见，它问你的问题点按钮就能回答，图片双向都能传，所有终端汇总在一张总览里。
 新开的群或话题会先补上之前的对话；只有 agent 需要你、或者做完的时候手机才会响
@@ -27,8 +29,8 @@ agent 干活时说的话实时可见，它问你的问题点按钮就能回答
 
 ## 需要什么
 
-- **herdr**：herdrchat 是基于它做的，没有它什么都做不了。请先从 [herdr.dev](https://herdr.dev) 安装；
-  它的 **hc** 要在这台机器上跑着，至少有一个 session。
+- **herdr**：herdrchat 是基于它做的，没有它什么都做不了。请先从 [herdr.dev](https://herdr.dev) 安装
+  （也可以让编程 agent 帮你装：`/herdrchat setup` 会主动问你）；它的 **hc** 要在这台机器上跑着，至少有一个 session。
 - **Node.js 20** 或更新版本，系统是 **macOS 或 Linux**。
 - **飞书**：一个能创建并发布企业自建应用的飞书团队（暂不支持 Lark 国际版）。
   **Telegram**：一个 Telegram 账号。可以只用一个，也可以两个同时用。
@@ -49,18 +51,19 @@ skill 会教你的编程 agent（Claude Code、Codex……）替你配置和照
 ## 配置
 
 **让 agent 帮你：** 对它说 `/herdrchat setup`。它会先问你用哪个聊天软件，然后一步步带你配好，
-能自动点的飞书后台操作它会替你点。
+飞书后台的操作，装了 [Ego Lite](https://lite.ego.app/) 浏览器它会替你点；没装的话，它会问你要不要装，不装就一步步告诉你点哪里。
 
-**自己动手：**
+**在终端里**（步骤和 agent 一样，一个个问你；区别是 agent 还能替你在飞书后台点，终端做不到）：
 
 ```bash
-herdrchat init --chat telegram   # 或者 --chat feishu；它会告诉你配置文件在哪
-# 填好那个文件（每一行上面都写了值从哪来），然后：
-herdrchat start                  # 启动，并等到真的连上
-herdrchat install                # 跑通以后：装成系统服务，开机自动启动，崩溃自动重启
+herdrchat setup
 ```
 
-每个聊天软件的具体步骤（建飞书应用，或者建 Telegram bot）在[详细说明](docs/guide.md#set-up-telegram)里（英文）。
+它会问你用哪个聊天软件，让你粘贴 bot 的 token（或飞书应用的 App ID 和 Secret）并当场检查，
+帮你选好要同步的 hc session（不改就是 `default`），然后启动 bot，并给你一个 6 位数字：
+把它发给 bot，bot 就认出你是主人。最后问你要不要装成系统服务。不用改文件，也不用复制任何 id。
+
+怎么建 Telegram bot 或飞书应用，以及想自己改配置文件的做法，见[详细说明](docs/guide.md#set-up-telegram)（英文）。
 
 ## 使用
 
@@ -77,7 +80,7 @@ herdrchat install                # 跑通以后：装成系统服务，开机自
 | `/herdrchat feishu <任务>` | 替你在飞书开发者后台完成操作（用 [Ego Lite](https://lite.ego.app/) 浏览器，或者一步步带你点）。 |
 | `/herdrchat telegram <任务>` | Telegram bot：从 @BotFather 一直到第一个话题。 |
 
-命令行：`herdrchat init`、`start`、`stop`、`status`、`logs`、`install`、`uninstall`、`version`；
+命令行：`herdrchat setup`、`pair`、`init`、`start`、`stop`、`status`、`logs`、`install`、`uninstall`、`version`；
 只输入 `herdrchat` 会列出全部。加上 `--profile <名字>`，可以再开一个聊天软件。
 
 ## 更新

package/bin/cli.mjs

@@ -2,6 +2,7 @@
 // herdrchat's command line: set up, start, stop and look at one profile.
 //
 //   herdrchat <command> [--profile <name>]
+//     setup      a few questions, and it is set up, started, paired with you and kept running
 //     init       make the profile's config.env from the example when it is missing
 //     install    run it as a service of the system (launchd, systemd): it starts at
 //                login and comes back after a crash; start, stop, status go through it
@@ -21,11 +22,13 @@ import { fileURLToPath } from 'node:url';
 
 const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
 const GUIDE = 'https://github.com/zhangxiangliang/herdrchat/blob/main/docs/guide.md';
-const HERDR = 'herdrchat is built on herdr: it mirrors the terminals that hc (herdr-core) runs.\nIt needs hc on this machine: install herdr first, from https://herdr.dev';
-const USAGE = `herdrchat: herdr's terminals in Feishu or Telegram. Needs herdr (https://herdr.dev).
+const HERDR = 'herdrchat is built on herdr: it mirrors the terminals that hc (herdr-core) runs.\nIt needs hc on this machine: install herdr first, from https://herdr.dev\n(or ask your coding agent `/herdrchat setup`: it can install herdr with you).';
+const USAGE = `herdrchat: the chat client for hc (herdr), in Feishu or Telegram. Needs hc (https://herdr.dev).
 
 herdrchat <command> [--profile <name>]
 
+  setup      set it up by answering a few questions (the easy way in)
+  pair       make you the bot's owner: it shows a code to send to the bot
   init       make the profile's config.env (--chat feishu|telegram picks the app)
   start      start (or restart) it: the service, or else its own hc terminal
   stop       stop it
@@ -36,7 +39,7 @@ herdrchat <command> [--profile <name>]
   run        run in the foreground (what start keeps running)
   version    which herdrchat this is
 
-First time: herdrchat init, fill in the file it names, then herdrchat start.
+First time: herdrchat setup. (Or by hand: herdrchat init, fill in the file, herdrchat start.)
 A second chat app: add --profile <name> to every command.
 Environment: HERDRCHAT_PROFILE (same as --profile), HERDRCHAT_HOME (one folder for a
 profile's settings and state).
@@ -85,7 +88,8 @@ if (helpAsked || !command) {
 if (process.env.HERDRCHAT_PROFILE && !/^[A-Za-z0-9][A-Za-z0-9_-]*$/.test(process.env.HERDRCHAT_PROFILE)) fail(`HERDRCHAT_PROFILE "${process.env.HERDRCHAT_PROFILE}": use letters, digits, - and _ only.`);
 
 // after the profile is set: lib/core/config.mjs reads it when it loads
-const { CONFIG_FILE, STATE_DIR, chatOf, loadConfig, makeDirs, placesOf } = await import('../lib/core/config.mjs');
+const { CONFIG_FILE, STATE_DIR, chatOf, loadConfig, makeDirs, placesOf, readState, setConfigValue, writeState } = await import('../lib/core/config.mjs');
+const { startPairing, PAIR_MINUTES } = await import('../lib/core/pairing.mjs');
 const { chatModule, chatNames } = await import('../lib/chats/index.mjs');
 const { coreUp, hc, sessionsHere } = await import('../lib/core/hc.mjs');
 const { serviceOf } = await import('../lib/core/service.mjs');
@@ -107,7 +111,10 @@ function readyConfig() {
   // a session not on this machine would be made by hc as the bot asks for it: a typo
   const here = sessionsHere();
   const unknown = cfg.sessions.filter((s) => !here.includes(s));
-  if (unknown.length) fail(`HERDR_SESSIONS in ${CONFIG_FILE} names ${unknown.join(', ')}, which ${unknown.length > 1 ? 'are' : 'is'} not an hc session on this machine.\nThe sessions here: ${here.join(', ') || 'none (start hc first)'}.`, 1);
+  if (unknown.length) {
+    const what = cfg.sessionsSet ? `HERDR_SESSIONS in ${CONFIG_FILE} names ${unknown.join(', ')}, which ${unknown.length > 1 ? 'are' : 'is'} not an hc session on this machine` : `HERDR_SESSIONS is empty, so herdrchat follows hc's default session, which is not on this machine`;
+    fail(`${what}.\nThe sessions here: ${here.join(', ') || 'none: install and start herdr first (https://herdr.dev)'}.${here.length ? ` Put the ones to mirror in HERDR_SESSIONS in ${CONFIG_FILE}.` : ''}`, 1);
+  }
   return cfg;
 }
 // a day's log file: the local date, as the log names its files
@@ -181,7 +188,235 @@ async function terminalState(session) {
   }
 }
 
+// ---------- setup: questions instead of a file to fill ----------
+
+async function prompter() {
+  const readline = await import('node:readline/promises');
+  let rl = null;
+  const open = () => { rl ||= readline.createInterface({ input: process.stdin, output: process.stdout, terminal: true }); return rl; };
+  const shut = () => { rl?.close(); rl = null; };
+  const ask = async (q, fallback = '') => (await open().question(fallback ? `${q} [${fallback}] ` : `${q} `)).trim() || fallback;
+  // A token or a secret is typed with nothing shown, not even dots: the terminal is put in
+  // raw mode and each key is read here, so neither the terminal nor readline echoes it.
+  const askSecret = (q) => new Promise((resolve) => {
+    shut();
+    process.stdout.write(`${q} `);
+    const stdin = process.stdin;
+    stdin.setRawMode(true);
+    stdin.resume();
+    let value = '';
+    const onData = (buf) => {
+      for (const ch of buf.toString('utf8')) {
+        if (ch === '\u0003') { // Ctrl+C
+          stdin.setRawMode(false);
+          process.stdout.write('\n');
+          process.exit(130);
+        }
+        if (ch === '\r' || ch === '\n' || ch === '\u0004') {
+          stdin.setRawMode(false);
+          stdin.pause();
+          stdin.off('data', onData);
+          process.stdout.write('\n');
+          resolve(value.trim());
+          return;
+        }
+        if (ch === '\u007f' || ch === '\b') value = value.slice(0, -1);
+        else if (ch >= ' ') value += ch;
+      }
+    };
+    stdin.on('data', onData);
+  });
+  return { ask, askSecret, close: shut };
+}
+
+const ok = (text) => console.log(`✔ ${text}`);
+const bad = (text) => console.log(`✘ ${text}`);
+const tell = (text) => console.log(`  ${text}`);
+
+async function telegramMe(token) {
+  try {
+    const res = await fetch(`https://api.telegram.org/bot${token}/getMe`, { signal: AbortSignal.timeout(15000) });
+    const body = await res.json();
+    return body.ok ? body.result : { error: body.description || `HTTP ${res.status}` };
+  } catch (err) {
+    return { error: err.message };
+  }
+}
+
+async function feishuCheck(appId, appSecret) {
+  try {
+    const res = await fetch('https://open.feishu.cn/open-apis/auth/v3/tenant_access_token/internal', { method: 'POST', headers: { 'content-type': 'application/json' }, body: JSON.stringify({ app_id: appId, app_secret: appSecret }), signal: AbortSignal.timeout(15000) });
+    const body = await res.json();
+    return body.code === 0 ? { ok: true } : { error: body.msg || `code ${body.code}` };
+  } catch (err) {
+    return { error: err.message };
+  }
+}
+
 const commands = {
+  async setup() {
+    if (!process.stdin.isTTY) fail(`herdrchat setup asks questions, so run it in a terminal. Without one: herdrchat init${again}, fill in the file, herdrchat start${again}.`);
+    console.log(`herdrchat setup${again}: a few questions, then it runs.\n`);
+    // 1. herdr
+    const hcPath = findHc();
+    if (!hcPath) {
+      bad(`hc is not on PATH. ${HERDR}`);
+      process.exitCode = 1;
+      return;
+    }
+    const { execFileSync } = await import('node:child_process');
+    ok(`herdr is here (${execFileSync(hcPath, ['--version'], { encoding: 'utf8' }).trim()})`);
+    const p = await prompter();
+    try {
+      // 2. the chat app
+      makeDirs();
+      const had = fs.existsSync(CONFIG_FILE) ? loadConfig() : null;
+      let chatName = chatFlag || had?.chat;
+      if (!chatName || (!had && !chatFlag)) {
+        const pick = await p.ask('Which chat app? 1) Feishu  2) Telegram', had?.chat === 'telegram' ? '2' : '1');
+        chatName = pick === '2' || /^t/i.test(pick) ? 'telegram' : 'feishu';
+      }
+      if (!had) {
+        const example = fs.readFileSync(path.join(ROOT, 'config.env.example'), 'utf8').replace(/^HERDRCHAT_CHAT=.*$/m, `HERDRCHAT_CHAT=${chatName}`);
+        fs.writeFileSync(CONFIG_FILE, example, { mode: 0o600 });
+      } else {
+        setConfigValue(CONFIG_FILE, 'HERDRCHAT_CHAT', chatName);
+      }
+      ok(`${chatName}, settings in ${CONFIG_FILE}`);
+      const env = loadConfig().env;
+      // 3. its keys, checked now
+      if (chatName === 'telegram') {
+        let token = env.TELEGRAM_BOT_TOKEN || '';
+        if (!token) tell('Make a bot first: in Telegram, message @BotFather, send /newbot, pick a name; it gives you a token.');
+        for (;;) {
+          if (!token) token = await p.askSecret('Paste the token (it is not shown):');
+          const me = await telegramMe(token);
+          if (me.error) {
+            bad(`Telegram says: ${me.error}. Check the token and paste it again.`);
+            token = '';
+            continue;
+          }
+          setConfigValue(CONFIG_FILE, 'TELEGRAM_BOT_TOKEN', token);
+          ok(`the token works: @${me.username}`);
+          if (!me.has_topics_enabled) {
+            bad('topic mode is off, and herdrchat makes one topic per terminal.');
+            tell('In the @BotFather chat tap Open (its mini app), pick your bot, turn on Threaded Mode.');
+            await p.ask('Press Enter when it is on.');
+            continue;
+          }
+          ok('topic mode is on');
+          break;
+        }
+      } else {
+        let appId = env.FEISHU_APP_ID || '';
+        let appSecret = env.FEISHU_APP_SECRET || '';
+        if (!appId || !appSecret) {
+          tell('Make the Feishu app first, in https://open.feishu.cn/app: a custom app (企业自建应用) with the bot ability');
+          tell('and the scopes in the guide, "Set up: Feishu": ' + GUIDE + '#set-up-feishu');
+          tell('(your coding agent can click through it for you: /herdrchat feishu create the app)');
+        }
+        for (;;) {
+          if (!appId) appId = await p.ask('App ID (cli_…, on the app\'s 凭证与基础信息 page):');
+          if (!appSecret) appSecret = await p.askSecret('App Secret (it is not shown):');
+          const check = await feishuCheck(appId, appSecret);
+          if (check.error) {
+            bad(`Feishu says: ${check.error}. Check the App ID and Secret and give them again.`);
+            appId = '';
+            appSecret = '';
+            continue;
+          }
+          setConfigValue(CONFIG_FILE, 'FEISHU_APP_ID', appId);
+          setConfigValue(CONFIG_FILE, 'FEISHU_APP_SECRET', appSecret);
+          ok('the App ID and Secret work');
+          break;
+        }
+      }
+      // 4. which sessions
+      const here = sessionsHere();
+      if (!here.length) {
+        bad('herdr is installed but no hc session runs on this machine, so there is nothing to mirror yet.');
+        tell('Open herdr-app, or start hc as herdr\'s docs say (https://herdr.dev), then run herdrchat setup' + again + ' again: what is done so far is kept.');
+        process.exitCode = 1;
+        return;
+      }
+      const named = loadConfig().sessionsSet ? loadConfig().sessions.join(',') : '';
+      const fallback = named || (here.includes('default') ? 'default' : here[0] || 'default');
+      tell(`hc sessions on this machine: ${here.join(', ') || 'none yet'}. "default" with herdr-app reaches all it shows.`);
+      for (;;) {
+        const pick = (await p.ask('Which sessions to mirror (comma-separated)?', fallback)).split(',').map((x) => x.trim()).filter(Boolean);
+        const unknown = pick.filter((x) => !here.includes(x));
+        if (unknown.length) {
+          bad(`not on this machine: ${unknown.join(', ')}`);
+          continue;
+        }
+        setConfigValue(CONFIG_FILE, 'HERDR_SESSIONS', pick.join(',') === 'default' ? '' : pick.join(','));
+        ok(`following ${pick.join(', ')}`);
+        break;
+      }
+      // 5. start
+      console.log('');
+      await commands.start();
+      if (process.exitCode) return;
+      if (chatName === 'feishu') {
+        tell('Now, with the bot running, in the Feishu developer console: 事件与回调 -> long connection (长连接),');
+        tell('add the event im.message.receive_v1 and the callback card.action.trigger, then publish a version.');
+        await p.ask('Press Enter when the version is published.');
+      }
+      // 6. pair: the owner is whoever sends the code (the same step the agent runs)
+      await commands.pair();
+      if (process.exitCode) return;
+      // 7. keep it running
+      const svc = service();
+      if (svc && !svc.installed()) {
+        const yes = await p.ask('Keep it running as a service (starts at login, comes back after a crash)? [Y/n]', 'Y');
+        if (/^y/i.test(yes)) await commands.install();
+      }
+      console.log(`\nDone. herdrchat status${again} shows how it is; herdrchat logs${again} what it did.`);
+      if (chatName === 'feishu') console.log('Send /auth to the bot once to let it mute its groups, so your phone rings only when it should.');
+    } finally {
+      p.close();
+    }
+  },
+
+  // The owner, without copying an id: a 6-digit code sent to the bot. It needs no terminal,
+  // so `herdrchat setup` and the agent's `/herdrchat setup` both use it. Sending the code
+  // also proves the whole path works: the bot runs, the chat app delivers, events are on.
+  async pair() {
+    const cfg = loadConfig();
+    const ownerKey = cfg.chat === 'telegram' ? 'TELEGRAM_OWNER_ID' : 'FEISHU_OWNER_OPEN_ID';
+    if (cfg.env[ownerKey]) {
+      ok(`the owner is set already (${ownerKey} in ${CONFIG_FILE}); to change it, empty that line and pair again`);
+      return;
+    }
+    const svc = service();
+    const running = svc?.installed() ? svc.state().running : (await terminalState(cfg.sessions[0])) === 'live';
+    if (!running) fail(`The bot is not running, and it is the bot that reads the code. Run herdrchat start${again} first.`);
+    let where = 'your chat with the bot';
+    if (cfg.chat === 'telegram') {
+      const me = await telegramMe(cfg.env.TELEGRAM_BOT_TOKEN || '');
+      if (me.username) where = `your chat with @${me.username} (https://t.me/${me.username}), tap Start if Telegram shows it,`;
+    } else {
+      where = 'your chat with the bot (in Feishu, search the app\'s name, open it, and message it)';
+    }
+    const code = startPairing({ read: readState, write: writeState });
+    console.log(`\nOpen ${where} and send it this code:\n\n      ${code}\n`);
+    tell(`It works for ${PAIR_MINUTES} minutes. Waiting…`);
+    const since = new Date().toISOString();
+    const until = Date.now() + PAIR_MINUTES * 60 * 1000;
+    while (Date.now() < until && !loadConfig().env[ownerKey]) await new Promise((r) => setTimeout(r, 2000));
+    if (!loadConfig().env[ownerKey]) {
+      bad(`no code came in ${PAIR_MINUTES} minutes. Run herdrchat pair${again} for a new one.`);
+      if (cfg.chat === 'feishu') tell('When the bot never answered at all: in the developer console, check the event im.message.receive_v1 is added on the long connection, and that a version with it is published.');
+      else tell('When the bot never answered at all: herdrchat logs' + again + ' says why.');
+      process.exitCode = 1;
+      return;
+    }
+    ok('paired: you are the owner. It starts again as yours…');
+    const back = await waitConnected(since);
+    if (!back.ok) return failedToConnect('It paired', back);
+    ok(`connected; your terminals' ${cfg.chat === 'telegram' ? 'topics' : 'groups'} appear in a moment`);
+  },
+
   init() {
     const chatName = chatFlag || 'feishu';
     if (!chatNames().includes(chatName)) fail(`--chat ${chatName}: the chat apps are ${chatNames().join(', ')}`);
@@ -195,7 +430,7 @@ const commands = {
     const example = fs.readFileSync(path.join(ROOT, 'config.env.example'), 'utf8').replace(/^HERDRCHAT_CHAT=.*$/m, `HERDRCHAT_CHAT=${chatName}`);
     fs.writeFileSync(CONFIG_FILE, example, { mode: 0o600 });
     const keys = (chatModule(chatName).requires || []).join(', ');
-    console.log(`Made ${CONFIG_FILE} (only you can read it) for ${chatName}.\nOpen it and fill in ${keys} and HERDR_SESSIONS (the hc sessions to mirror), then run \`herdrchat start${again}\`.\nThe guide walks through it: ${GUIDE}`);
+    console.log(`Made ${CONFIG_FILE} (only you can read it) for ${chatName}.\nOpen it and fill in ${keys} (HERDR_SESSIONS is hc's default session unless you name others), then run \`herdrchat start${again}\`.\nThe guide walks through it: ${GUIDE}`);
   },
 
   // The service file is written again each time (a moved node or hc is picked up), and
@@ -270,7 +505,7 @@ const commands = {
       if (!here.includes(session)) sessionWords.push(`${session} (no such session here; this machine has: ${here.join(', ') || 'none'})`);
       else sessionWords.push(`${session} (${(await coreUp(session)) ? 'core up' : 'core not running'})`);
     }
-    console.log(`sessions  ${sessionWords.join(', ') || 'none yet: set HERDR_SESSIONS (`ls ~/.local/state/herdr-core` lists them)'}`);
+    console.log(`sessions  ${sessionWords.join(', ')}${cfg.sessionsSet ? '' : ' (hc\'s default session: HERDR_SESSIONS is empty)'}`);
     // how it runs: the service, an hc terminal, or not at all
     const svc = hcThere ? service() : null;
     if (!hcThere) {

package/bin/herdrchat.mjs

@@ -5,7 +5,8 @@
 //
 // Usage: node bin/herdrchat.mjs (`herdrchat start` keeps it running)
 import path from 'node:path';
-import { STATE_DIR, chatOf, loadConfig, makeDirs, readState, writeState } from '../lib/core/config.mjs';
+import { STATE_DIR, chatOf, loadConfig, makeDirs, readState, setConfigValue, writeState } from '../lib/core/config.mjs';
+import { tryPairing } from '../lib/core/pairing.mjs';
 import { createEngine } from '../lib/core/engine.mjs';
 import { followEvents } from '../lib/core/events.mjs';
 import { cores, getTerminal, hc, keys, machines, nameTab, put, run, screenTail, send } from '../lib/core/hc.mjs';
@@ -34,6 +35,17 @@ const chat = createChat(cfg.chat, {
   stateDir: STATE_DIR,
   lane: (k, label, fn) => engine.laneOf(k, label, fn),
   scopeOf: (k) => engine.scopeOfKey(k),
+  // the pairing code from `herdrchat setup`: its sender becomes the owner, written to
+  // config.env; the bot then starts again (its service or terminal brings it back) as theirs
+  claimOwner: (text, key, id) => {
+    const result = tryPairing(store, text);
+    if (result === 'ok') {
+      setConfigValue(cfg.configFile, key, id);
+      log(`paired: ${key} set; starting again as the owner's`);
+      setTimeout(() => process.exit(0), 2000);
+    }
+    return result;
+  },
 });
 
 // A bot that is down is a phone that hears nothing, so down time is said in the direct

package/config.env.example

@@ -7,7 +7,8 @@
 # (`herdrchat init --profile telegram --chat telegram`).
 HERDRCHAT_CHAT=feishu
 
-# The hc sessions to mirror, comma-separated (machines they reach come along).
+# The hc sessions to mirror, comma-separated (machines they reach come along). Empty is
+# hc's own session, `default`: with herdr-app it reaches every session herdr-app shows.
 # `ls ~/.local/state/herdr-core` lists the sessions on this machine.
 HERDR_SESSIONS=
 

package/docs/guide.md

@@ -2,8 +2,8 @@
 
 How herdrchat works and every setting, for when the README is not enough.
 
-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,
+herdrchat is hc's chat client, as herdr-app is its desktop and phone client: 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.
@@ -85,7 +85,7 @@ 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_SESSIONS` | both | `default` | the hc sessions to mirror, comma-separated; machines they reach come along. `default` is hc's own session, which with herdr-app reaches every session it shows |
 | `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 |
@@ -228,6 +228,11 @@ delivered (the terminal has ended) says so plainly.
   dialog it waits on, as is), `/esc`, `/history` (the conversation so far, as a file and
   a folded post). Dialog cards have buttons.
 
+`herdrchat setup` does the steps below by asking: it checks the token or the Feishu keys
+at once, picks the sessions, starts the bot and pairs you as its owner with a 6-digit
+code you send to the bot, then offers the service. The steps say what happens, and how
+to do it by hand. When the owner is missing later, `herdrchat pair` shows a new code.
+
 ## Set up: Telegram
 
 1. In Telegram, message **@BotFather**: `/newbot`, give it a name and a username ending
@@ -235,10 +240,10 @@ delivered (the terminal has ended) says so plainly.
 2. Turn on topics for the bot: in the BotFather chat tap **Open** (its mini app), pick the
    bot, turn on **Threaded Mode**. Without it the bot cannot make topics.
 3. `herdrchat init --chat telegram` (with `--profile <name>` too if you also run Feishu)
-   prints where its `config.env` is. Fill in `TELEGRAM_BOT_TOKEN` and `HERDR_SESSIONS`
-   (`ls ~/.local/state/herdr-core` lists your hc sessions).
-4. `herdrchat start`, then message the bot anything. It answers with the line to add,
-   `TELEGRAM_OWNER_ID=<your id>`; add it and run `herdrchat start` again. One topic per
+   prints where its `config.env` is. Fill in `TELEGRAM_BOT_TOKEN`. `HERDR_SESSIONS`
+   can stay empty for hc's default session (`ls ~/.local/state/herdr-core` lists yours).
+4. `herdrchat start`, then `herdrchat pair`: it shows a 6-digit code. Open the bot (tap
+   Start) and send it the code; the bot makes you its owner and starts again. One topic per
    tab appears in your private chat with the bot (Telegram takes about one message a
    second, so many tabs take a moment).
 5. Once it works: `herdrchat install` (see "Running as a service").
@@ -249,8 +254,9 @@ If Telegram is your only app, use the default profile with `--chat telegram`. Us
 ## Set up: Feishu
 
 Feishu only: Lark (the international version) is not supported yet. Steps 1, 2, 5 and 6
-are in the Feishu developer console (`https://open.feishu.cn/app`); the herdrchat skill
-(`/herdrchat setup`) can do them with you.
+are in the Feishu developer console (`https://open.feishu.cn/app`). The herdrchat skill
+(`/herdrchat setup`) clicks them for you with the [Ego Lite](https://lite.ego.app/)
+browser, or tells you what to click without it; or follow the steps here yourself.
 
 1. Create a custom app (企业自建应用) and add the bot ability (机器人).
 2. Permissions: import the scopes listed in `skills/herdrchat/references/feishu.md`,
@@ -258,8 +264,8 @@ are in the Feishu developer console (`https://open.feishu.cn/app`); the herdrcha
    reading the messages sent to it, making and renaming groups, reactions, images both
    ways, and group tags.
 3. `herdrchat init` prints where its `config.env` is. Fill in the app's App ID and App
-   Secret (the app's 凭证与基础信息 page) and `HERDR_SESSIONS` (`ls
-   ~/.local/state/herdr-core` lists your hc sessions).
+   Secret (the app's 凭证与基础信息 page). `HERDR_SESSIONS` can stay empty for hc's
+   default session (`ls ~/.local/state/herdr-core` lists yours).
 4. `herdrchat start`. The bot must be running for the next step: the console checks for
    a live connection.
 5. Events and callbacks (事件与回调): for events, choose the long connection mode (长连接)
@@ -267,9 +273,9 @@ are in the Feishu developer console (`https://open.feishu.cn/app`); the herdrcha
    mode too and add `card.action.trigger` (the dialog buttons).
 6. Publish a version. If the page does not say 本次发布免审核, your team's admin must
    approve it first.
-7. Open `https://applink.feishu.cn/client/bot/open?appId=<app id>` and send anything.
-   The bot answers with the line to add, `FEISHU_OWNER_OPEN_ID=<your open_id>`; add it
-   and run `herdrchat start` again. One group per tab appears.
+7. `herdrchat pair`: it shows a 6-digit code. In Feishu, search the app's name, open the
+   bot and send it the code; the bot makes you its owner and starts again. One group per
+   tab appears. When the code gets no answer, step 5 or 6 is not done.
 8. Optional: send `/auth` to the bot so it can mute its groups for you ("Optional: let
    the bot act as you"), and add the bot menu (`skills/herdrchat/references/feishu.md`,
    "The bot menu").

package/lib/chats/contract.mjs

@@ -12,7 +12,10 @@
 // working | closed | needs | done | good | bad.
 //
 // ctx: {cfg, store: {read, write}, log, logWarn, logError, stateDir,
-//       lane(k, label, fn): run fn in the room's lane, scopeOf(k): its session or machine}
+//       lane(k, label, fn): run fn in the room's lane, scopeOf(k): its session or machine,
+//       claimOwner(text, key, id) -> 'ok' | 'wrong' | 'none': with no owner yet, a message
+//       that may be the pairing code `herdrchat setup` shows; on 'ok' the id is written
+//       to config.env as `key` and the bot starts again as that owner's}
 
 export const CHAT_MEMBERS = {
   name: 'string: the app, as in HERDRCHAT_CHAT',
@@ -21,7 +24,7 @@ export const CHAT_MEMBERS = {
   roomWord: 'string: what the user calls a room in this app (group, topic), for what the bot says',
   liveBytes: 'number: how much text one editable card holds',
   split: '(markdown) -> string[]: one message\'s worth each',
-  start: '({onMessage, onAction, onReady}): connect; onMessage({room|null, where, message, text, images}) for the owner\'s messages (room null: the direct chat), onAction({value, message, answer}) -> {toast: {type, text}, card?: {kind: done|dialog, ...}} for button clicks',
+  start: '({onMessage, onAction, onReady}): connect; onMessage({room|null, where, message, text, images}) for the owner\'s messages (room null: the direct chat), onAction({value, message, answer, ticks?}) -> {toast: {type, text}, card?: {kind: done|dialog, ...}} for button clicks; ticks: {<option n>: true|false}, a multi-select\'s boxes as ticked on the card itself (a form, sent with Next), when the app has them',
   command: '(cmd, args, where) -> boolean: one of its own direct-chat commands, handled',
   openRoom: '({name, intro}) -> room',
   renameRoom: '(room, name)',