herdrchat 1.0.0 → 1.1.0

package/lib/{hc.mjs → core/hc.mjs}

@@ -7,10 +7,14 @@ import { execFile } from 'node:child_process';
 // it the text arrives as if you typed it.
 const { HC_TERMINAL_ID, HC_SCOPE, HC_TERMINAL_SOCKET, ...ENV } = process.env;
 
+// `herdrchat start` passes hc's full path: the core that runs the bot may have a PATH
+// without it, and a bot that cannot run hc sees nothing.
+const HC = process.env.HERDRCHAT_HC || 'hc';
+
 export function hc(session, args, { timeoutMs = 15000 } = {}) {
   return new Promise((resolve, reject) => {
     execFile(
-      'hc',
+      HC,
       args,
       { env: { ...ENV, HC_SESSION: session }, timeout: timeoutMs, maxBuffer: 16 * 1024 * 1024 },
       (err, stdout, stderr) => {
@@ -34,6 +38,16 @@ export async function machines(session) {
   return (await json(session, ['ls'])).machines || [];
 }
 
+// The id of a session's own core, and the cores it is connected to as machines:
+// { self, links: [{ name, id, state }] }. A link's id is the id of the core it reaches.
+export async function cores(session) {
+  const [status, list] = await Promise.all([json(session, ['server', 'status']), json(session, ['machine', 'ls'])]);
+  return {
+    self: status.core?.id || null,
+    links: (list.machines || []).map(({ name, id, state }) => ({ name, id, state })),
+  };
+}
+
 export async function getTerminal(session, address) {
   return json(session, ['get', address]);
 }
@@ -71,12 +85,46 @@ function read(session, address, lines = 0) {
   return hc(session, ['read', address, '--lines', String(lines)]);
 }
 
-// The last `lines` lines of a terminal's screen: the default output for a program with no reader.
+// The last `lines` lines of a terminal's screen (dialogs, and replies in a terminal with no agent).
 export async function screenTail(session, address, lines) {
   const out = await read(session, address, lines);
   return out.split('\n').slice(-lines).join('\n').trimEnd();
 }
 
+// hc could not reach the machine a terminal is on (`"kind":"unavailable"`).
+export function isUnavailable(err) {
+  return /"kind":"unavailable"/.test(err?.message || '');
+}
+
+// A failed hc call as a person reads it: hc's own message, without the command line or
+// its JSON wrapping.
+export function plainError(err) {
+  const raw = err?.message || String(err);
+  const json = raw.match(/\{"error":.*\}\s*$/);
+  if (json) {
+    try {
+      const { message, kind } = JSON.parse(json[0]).error;
+      if (kind === 'finished') return 'this terminal has ended.';
+      if (message) return message;
+    } catch {
+      // not hc's JSON
+    }
+  }
+  return raw.replace(/^hc [^:]*: /, '');
+}
+
+// A screen as people read it: no trailing spaces, no blank lines at the ends, never two
+// blank lines in a row; with `last`, only its last `last` lines (a dialog sits at the bottom).
+export function tidyScreen(text, last = Infinity) {
+  const lines = [];
+  for (const line of (text || '').split('\n').map((l) => l.trimEnd())) {
+    if (!line && (!lines.length || !lines[lines.length - 1])) continue;
+    lines.push(line);
+  }
+  while (lines.length && !lines[lines.length - 1]) lines.pop();
+  return lines.slice(-last).join('\n');
+}
+
 // "machine/tN" for a terminal on a connected machine, "tN" here.
 export function machineOf(address) {
   const i = address.lastIndexOf('/');

package/lib/{log.mjs → core/log.mjs}

@@ -2,12 +2,14 @@
 // goes to stdout and to logs/<YYYY-MM-DD>.log in the state folder (KEEP_DAYS kept), as
 // "<time> <LEVEL> <text>". `capture()` sends console output (the SDK, the event stream)
 // through it too, and writes an uncaught error with its stack before the process exits
-// (`herdrchat start` keeps it running). No token or secret is ever passed to it.
+// (`herdrchat start` keeps it running); `onCrash` gets a few seconds first, to say so
+// where you will see it. No token or secret is ever passed to it.
 import fs from 'node:fs';
 import path from 'node:path';
 import util from 'node:util';
 
 const KEEP_DAYS = 14;
+const CRASH_WAIT_MS = 3000;
 
 export function createLog(dir) {
   fs.mkdirSync(dir, { recursive: true });
@@ -43,14 +45,15 @@ export function createLog(dir) {
     error: (...args) => write('ERROR', args),
   };
 
-  log.capture = () => {
+  log.capture = ({ onCrash } = {}) => {
     console.log = (...args) => write('INFO', args);
     console.info = console.log;
     console.warn = (...args) => write('WARN', args);
     console.error = (...args) => write('ERROR', args);
     process.on('uncaughtException', (err) => {
       write('ERROR', ['uncaught:', err]);
-      process.exit(1);
+      const said = onCrash ? Promise.resolve().then(() => onCrash(err)).catch(() => {}) : Promise.resolve();
+      Promise.race([said, new Promise((r) => setTimeout(r, CRASH_WAIT_MS))]).finally(() => process.exit(1));
     });
     process.on('unhandledRejection', (err) => write('ERROR', ['unhandled rejection:', err]));
   };

package/lib/{readers → core/readers}/claude.mjs

@@ -90,6 +90,7 @@ export function conversationAfter(lines, cursor) {
 }
 
 export const app = 'claude-code';
+export const processes = ['claude'];
 
 // What is new since `cursor`: {items, file}, or null when the terminal runs no readable
 // Claude. When the session moved to a new transcript (/clear, resume), what is left in

package/lib/core/readers/index.mjs

@@ -0,0 +1,49 @@
+// Readers: how the bot gets what an agent said from the agent's own records, so nothing
+// is lost and the group shows it while the agent works. hc stays the backbone (which
+// terminals exist, their status, when a turn ends, typing into them); a reader adds the
+// conversation. A terminal with no running agent is not mirrored (see agentOf).
+//
+// A reader is a module that exports:
+//   app                              the name the agent gives in its hc status (`status.app`)
+//   processes                        the names its process runs under (hc's `foreground`)
+//   after(session, address, cursor)  -> {items, file} | null: what is new since `cursor`
+//                                       (null: this terminal is not readable); `file` is
+//                                       the log it read, kept in the cursor
+//   rest(session, address, cursor)   -> items: what `cursor.file` still holds after the
+//                                       program is gone
+// Items are {role: 'you' | 'ai' | 'tool', text, at, id, end?} (`end` marks the turn's last
+// answer) or {role: 'image', from: 'you' | 'ai', media, data (base64), at, id}.
+// Cursors are in ../cursor.mjs.
+//
+// To add an agent: write lib/core/readers/<agent>.mjs and list it in LISTED below
+// (docs/architecture.md, "Adding a harness").
+import path from 'node:path';
+import * as claude from './claude.mjs';
+
+// What every reader exports (see above); checked for each one listed here when this
+// loads, so a reader that misses one fails at start, not when its agent first runs.
+export const READER_MEMBERS = { app: 'string', processes: 'object', after: 'function', rest: 'function' };
+export function checkReader(reader) {
+  const wrong = Object.entries(READER_MEMBERS).filter(([m, type]) => typeof reader?.[m] !== type);
+  if (wrong.length) throw new Error(`reader ${reader?.app || '?'} does not give: ${wrong.map(([m]) => m).join(', ')} (lib/core/readers/index.mjs)`);
+  return reader;
+}
+
+export const LISTED = [claude].map(checkReader);
+const READERS = new Map(LISTED.map((r) => [r.app, r]));
+
+export function readerFor(app) {
+  return READERS.get(app) || null;
+}
+
+// The agent a terminal runs right now, as its reader, or null: a group mirrors agents
+// only, never a shell or another program. hc's status can outlive the agent (it still
+// said "blocked" after Claude quit, and a tool run after it was posted as a dialog), so
+// the foreground process must be that agent too; with no foreground known, the status
+// alone decides, so a terminal is never silenced for missing data.
+export function agentOf(record) {
+  const reader = readerFor(record?.status?.app);
+  const fg = record?.foreground;
+  if (!reader || !fg) return reader;
+  return [fg.name, path.basename(fg.argv?.[0] || '')].some((n) => reader.processes.includes(n)) ? reader : null;
+}

package/lib/core/views.mjs

@@ -0,0 +1,58 @@
+// One terminal can be seen several ways: in its own hc session, and through every
+// followed session that is connected to that session's core as a machine (under any
+// name). What a terminal is comes from hc, never from names: the id of the core it runs
+// on (`hc server status` for a session's own core, `hc machine ls` for the cores it is
+// connected to) plus its tN on that core.
+//
+// The bot follows each terminal through one view: its own session when that session is
+// followed, else the first followed session (config order) with a live connection to
+// its core.
+import { machineOf } from './hc.mjs';
+
+// cores: Map session -> { self: core id, links: [{ name, id, state }] }
+export function coreViews(sessions, cores) {
+  // the core a view's terminal runs on, or null when it cannot be told (unknown session
+  // or machine, or a machine reached through another machine)
+  function coreOf(session, address) {
+    const info = cores.get(session);
+    const machine = machineOf(address);
+    if (!info || machine?.includes('/')) return null;
+    if (!machine) return info.self || null;
+    return info.links.find((l) => l.name === machine)?.id || null;
+  }
+
+  // "<core id>|tN": the same for every view of one terminal
+  function identity(session, address) {
+    const core = coreOf(session, address);
+    return core ? `${core}|${address.slice(address.lastIndexOf('/') + 1)}` : null;
+  }
+
+  // the view that follows a core's terminals: { session, machine } (machine null: directly)
+  function ownerOf(core) {
+    const direct = sessions.find((s) => cores.get(s)?.self === core);
+    if (direct) return { session: direct, machine: null };
+    for (const session of sessions) {
+      const link = cores.get(session)?.links.find((l) => l.id === core && l.state === 'connected');
+      if (link) return { session, machine: link.name };
+    }
+    return null;
+  }
+
+  // true or false, or null when the cores cannot tell (the caller falls back)
+  function owns(session, address) {
+    const core = coreOf(session, address);
+    if (!core) return null;
+    const owner = ownerOf(core);
+    return !!owner && owner.session === session && owner.machine === machineOf(address);
+  }
+
+  // false while the machine a view reaches its terminal through is not connected
+  function reachable(session, address) {
+    const machine = machineOf(address);
+    if (!machine) return true;
+    const link = cores.get(session)?.links.find((l) => l.name === machine.split('/')[0]);
+    return !link || link.state === 'connected';
+  }
+
+  return { identity, owns, reachable };
+}

package/package.json

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

package/skills/herdrchat/SKILL.md

@@ -22,7 +22,7 @@ in `~/.config/herdrchat/<profile>/config.env` and its state in
 | `/herdrchat start`, `/herdrchat stop` | Read `config.env` (its `HERDR_SESSIONS`) in one step, then `herdrchat start` / `stop` in the next; never both at once. |
 | `/herdrchat logs` | `herdrchat logs --errors` (or `-n 100`); explain them with `references/ops.md` "Logs". |
 | `/herdrchat auth` | The user sends `/auth` to the bot and allows it on Feishu's page; the app needs the user scopes in `references/feishu.md`. Then groups are muted, labels and pins follow. |
-| `/herdrchat config` | Change a setting in `config.env` with the user (sessions, `HERDR_MUTED_SPACES`, `HERDR_SILENT_SPACES`, `HERDR_BOT_TAGS`, `HERDR_USER_TAGS`; each is explained in `config.env.example`), read the file back, then restart. |
+| `/herdrchat config` | Change a setting in `config.env` with the user (sessions, `HERDR_MUTED_SPACES`, `HERDR_SILENT_SPACES`, `HERDR_BOT_TAGS`, `HERDR_USER_TAGS`, `HERDR_HISTORY`, `HERDRCHAT_CHAT`; each is explained in `config.env.example`), read the file back, then restart. |
 | `/herdrchat fix` | Find the cause from `herdrchat status`, the logs and the live result, then fix it: `references/ops.md`. |
 | `/herdrchat feishu <task>` | Anything in the Feishu developer console: scopes, callbacks, publishing, the icon, deleting an app: `references/feishu.md`. |
 

package/skills/herdrchat/references/ops.md

@@ -17,12 +17,25 @@ Below, `S` is the first session in `HERDR_SESSIONS`.
 HC_SESSION=S hc get herdrchat --json      # state "live"
 HC_SESSION=S hc read herdrchat --lines 40 # its terminal: start lines, "[feishu] connected"
 herdrchat status                              # running, folders, /auth, errors today
-herdrchat start                               # restart (stops the old one first)
+herdrchat start                               # restart: stops it in every session, waits until it reaches Feishu
 ```
 
 A restart is needed after any code or `config.env` change. It is safe: what was posted
 is in `D/state.json`, so it picks up where it stopped.
 
+While the bot is down the user hears nothing, so:
+
+- Never end with the bot down: `herdrchat start` exits 1 with its errors when the bot
+  does not reach Feishu within 30 s; fix that before anything else.
+- Never stop or restart the hc core (`hc server stop|restart`) of the session the bot
+  runs in without saying so first, and run `herdrchat start` right after.
+- Never start an hc core from an agent's shell: the core passes that shell's variables
+  (`CLAUDECODE`, `CLAUDE_CODE_*`) to every terminal, and an agent started there treats
+  itself as a sub-agent (Claude Code then saves no transcript). Start it with those
+  variables removed (`env -u CLAUDECODE -u CLAUDE_CODE_CHILD_SESSION … hc server start`).
+- A crash posts "🔴 herdrchat is down" in the direct chat (at most every 10 minutes) and
+  the next connection posts "✅ herdrchat is back" with how long it was gone.
+
 ## Logs
 
 `D/logs/<YYYY-MM-DD>.log`, one file a day, 14 kept, lines `<time> <LEVEL> <text>`:
@@ -61,7 +74,7 @@ your token after `/auth`: never print it.
 ## Did the change take effect
 
 Check the live result, not only the code: count what actually happened in Feishu with
-the bot's own client (`lib/feishu.mjs` `createClient` with `loadConfig()`), for example:
+the bot's own client (`lib/chats/feishu/client.mjs` `createClient` with `loadConfig()`), for example:
 
 - mentions in a group since a time: `im.v1.message.list` on the chat, then each item's
   `mentions` (a mention inside a card is not counted by Feishu, so it does not ring);

package/skills/herdrchat/references/telegram.md

@@ -0,0 +1,23 @@
+# Telegram: setting up the bot
+
+A Telegram bot cannot make groups, so herdrchat puts each herdr-app tab in a topic of
+your private chat with the bot; the chat's main thread is the overview and the commands
+(`/ls`, `/new`, `/kill`; in a topic `/screen`, `/answer`, `/esc`). Posts are silent;
+"needs you" and "done" ring.
+
+It runs as its own profile, beside a Feishu one:
+
+1. In Telegram, message **@BotFather**: `/newbot`, pick a name and a username, and keep
+   the token it gives. Never paste the token into a chat or a log.
+2. Turn on topics for the bot in @BotFather (its mini app, "Open": the bot's settings,
+   Threaded Mode). Check: `getMe` answers `has_topics_enabled: true`.
+3. Make the profile's config: `herdrchat init --profile telegram`, then in
+   `~/.config/herdrchat/telegram/config.env` set `HERDRCHAT_CHAT=telegram`, the token as
+   `TELEGRAM_BOT_TOKEN`, and `HERDR_SESSIONS`.
+4. `herdrchat start --profile telegram`, then message the bot once: it answers with your
+   `TELEGRAM_OWNER_ID=...`. Put that in the config and start it again. The topics appear,
+   one per tab (Telegram allows about one message a second, so many tabs take a moment).
+
+Check the token without printing it: read `TELEGRAM_BOT_TOKEN` from the config in a short
+`node -e`, call `https://api.telegram.org/bot<token>/getMe`, print only `username` and
+`has_topics_enabled`.

package/lib/readers/index.mjs

@@ -1,24 +0,0 @@
-// Readers: how the bot gets what an agent said from the agent's own records, so nothing
-// is lost and the group shows it while the agent works. hc stays the backbone (which
-// terminals exist, their status, when a turn ends, typing into them); a reader adds the
-// conversation. A program with no reader gets the default: its screen through `hc read`.
-//
-// A reader is a module that exports:
-//   app                              the name the agent gives in its hc status (`status.app`)
-//   after(session, address, cursor)  -> {items, file} | null: what is new since `cursor`
-//                                       (null: this terminal is not readable); `file` is
-//                                       the log it read, kept in the cursor
-//   rest(session, address, cursor)   -> items: what `cursor.file` still holds after the
-//                                       program is gone
-// Items are {role: 'you' | 'ai' | 'tool', text, at, id, end?} (`end` marks the turn's last
-// answer) or {role: 'image', from: 'you' | 'ai', media, data (base64), at, id}.
-// Cursors are in ../cursor.mjs.
-//
-// To add an agent: write lib/readers/<agent>.mjs and list it here.
-import * as claude from './claude.mjs';
-
-const READERS = new Map([claude].map((r) => [r.app, r]));
-
-export function readerFor(app) {
-  return READERS.get(app) || null;
-}