herdrchat 0.1.0 → 1.1.0

package/config.env.example

@@ -1,10 +1,21 @@
 # herdrchat settings, the example of config.env. `herdrchat init` copies it to where the
 # profile reads it (~/.config/herdrchat/default/config.env, ~/.config/herdrchat/<profile>/
 # with --profile, or HERDRCHAT_HOME), private; then fill it in.
+
+# the chat app this profile mirrors into: feishu (default) or telegram. To use both, run
+# one profile each (herdrchat start --profile telegram).
+HERDRCHAT_CHAT=feishu
+
+# feishu
 FEISHU_APP_ID=cli_xxxxxxxxxxxxxxxx
 FEISHU_APP_SECRET=xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
 FEISHU_OWNER_OPEN_ID=
 
+# telegram: the token from @BotFather (turn topic mode on there); your user id, which the
+# bot tells you when you message it
+TELEGRAM_BOT_TOKEN=
+TELEGRAM_OWNER_ID=
+
 HERDR_SESSIONS=session-a,session-b
 # once /auth is done, spaces whose groups are muted (only an @ rings): `all` (default),
 # empty for none, or spaces, comma-separated
@@ -15,3 +26,6 @@ HERDR_SILENT_SPACES=
 HERDR_BOT_TAGS=on
 # your sidebar labels, once /auth is done: on (default) or off
 HERDR_USER_TAGS=on
+# what a new room gets of the conversation before it: file,folded (default: all of it as a
+# file, the newest part in a folded post), file, folded, or empty for nothing
+HERDR_HISTORY=file,folded

package/docs/architecture.md

@@ -0,0 +1,76 @@
+# herdrchat architecture
+
+herdrchat has two kinds of plug-ins that grow over time: **chat apps** (Feishu now,
+Telegram next, then Slack and Discord) and **harnesses** (Claude Code now, then codex
+and pi). The core between them knows neither. This page says where everything is and
+how to add one of each.
+
+## The parts
+
+```
+bin/
+  cli.mjs                  herdrchat init|start|stop|status|logs
+  herdrchat.mjs            wires the parts: config, log, the chat app, the core
+lib/
+  core/                    the same for every chat app and every harness
+    engine.mjs             follows hc, keeps one room per herdr-app tab, posts what agents
+                           say, dialogs and clicks, what you type, the overview
+    hc.mjs  events.mjs     hc: commands, and its live event stream
+    views.mjs              which view of a terminal is followed (hc core id + tN)
+    cursor.mjs  home.mjs   what was posted already; reading an agent's log files
+    menu.mjs               a dialog's options, read from the screen
+    config.mjs  log.mjs    config.env, state.json, the daily log
+    readers/               one reader per harness (the contract is in index.mjs)
+  chats/
+    contract.mjs           what a chat app gives the core, and the check for it
+    index.mjs              the list of chat apps
+    feishu/                index.mjs (the contract), client.mjs, overview.mjs, ...
+test/
+  fakes.mjs                a fake chat app, a fake hc and a fake reader
+  engine.test.mjs          the core, run on the fakes
+```
+
+The rules that keep it this way:
+
+- The core never imports from `lib/chats/`, and a chat app never imports from the
+  core's engine. They meet only through the contract in `lib/chats/contract.mjs`.
+- Everything a chat app does is in its own folder, including what only it has (Feishu's
+  tags, avatars and acting as you).
+- The core gets hc, the readers and state.json passed in, so the tests swap them for
+  fakes. A behaviour of the core gets a test in `test/engine.test.mjs`.
+- Words the core uses: a **room** is where one tab is mirrored (a Feishu group, a
+  Telegram topic); `k` is the core's key for a tab's terminal; `room` and `message`
+  are the app's own ids, which the core keeps as given.
+
+## Adding a chat app
+
+1. Read the app's official docs first, for each line of the contract: how a room is
+   made (a group, a topic, a channel), how a message is edited, buttons and their
+   callbacks, reactions, images both ways, how the phone is kept quiet, the rate limits.
+   Write down what it cannot do and what stands in for it.
+2. Make `lib/chats/<app>/index.mjs` that exports `requires` (the config.env keys it
+   cannot start without) and `create(ctx)` returning every member of `CHAT_MEMBERS` in
+   `lib/chats/contract.mjs`. Keep the app's API calls in a `client.mjs` beside it.
+3. List it in `lib/chats/index.mjs`.
+4. Add its keys to `config.env.example` and to the comment at the top of
+   `lib/core/config.mjs`.
+5. Add a test that `checkChat(create(...))` passes (see the Feishu one in
+   `test/engine.test.mjs`), and tests for its own message conversions.
+6. Add `skills/herdrchat/references/<app>.md`: setting the app up, step by step.
+7. Run it in its own profile (`herdrchat start --profile <app>` with
+   `HERDRCHAT_CHAT=<app>` in that profile's config.env), so the running Feishu bot is
+   not touched.
+
+## Adding a harness
+
+1. Read how the agent keeps its conversation on disk, from its docs or its source: where
+   the log is, how to find the one for a running terminal, how a turn's last answer is
+   marked.
+2. Write `lib/core/readers/<agent>.mjs` exporting `app` (the name the agent gives in its
+   hc status, `status.app`), `processes` (the names its process runs under, as hc's
+   `foreground` reports them), `after(session, address, cursor)` and
+   `rest(session, address, cursor)`. The items it returns are described at the top of
+   `lib/core/readers/index.mjs`.
+3. List it in `LISTED` in `lib/core/readers/index.mjs`; `checkReader` checks it there.
+4. Add tests with a sample log in `test/readers.test.mjs`.
+5. Add a row to the readers table in `docs/guide.md`.

package/docs/guide.md

@@ -31,16 +31,16 @@ herdr-app shows them, their status, and when a turn ends (`turn` event: the stat
 **A reader gives the conversation.** hc can show only the screen, and the screen is a
 picture: long output is folded, and you cannot tell your words from the agent's. So for
 each agent a reader reads the agent's own records. The status hc reports names the agent
-(`status.app`), and that name picks the reader (`lib/readers/`):
+(`status.app`), and that name picks the reader (`lib/core/readers/`):
 
 | `status.app` | reader | reads |
 |---|---|---|
-| `claude-code` | `lib/readers/claude.mjs` | its transcript: the terminal's foreground pid names the session in `~/.claude/sessions/<pid>.json` |
+| `claude-code` | `lib/core/readers/claude.mjs` | its transcript: the terminal's foreground pid names the session in `~/.claude/sessions/<pid>.json` |
 | anything else | none (default) | the screen, through `hc read` |
 
 On another machine, a reader reads the same files through `hc exec --on`. To add an
-agent, write `lib/readers/<agent>.mjs` (the contract is at the top of
-`lib/readers/index.mjs`) and list it there.
+agent, write `lib/core/readers/<agent>.mjs` (the contract is at the top of
+`lib/core/readers/index.mjs`) and list it there.
 
 ## What a group shows
 
@@ -56,7 +56,9 @@ agent, write `lib/readers/<agent>.mjs` (the contract is at the top of
   - Images too: ones it looked at (a screenshot, an image file it read) and ones you
     pasted in the terminal, shown in the card.
   - What you sent from the group is not repeated.
-- A program without one: the last 150 lines of its screen when a turn ends.
+- Anything else (a shell, a tool, an agent that has quit): nothing by itself. A terminal
+  counts as an agent only while its foreground process is that agent, so a status left
+  over after it quits posts nothing.
 - A turn that ends on `blocked` (permission, question, auth): what it said first, then
   a red "⚠️ Needs you" card. When the screen shows a numbered menu (as Claude Code's
   permission and question dialogs do), the card shows only the dialog, as text, with a
@@ -103,7 +105,17 @@ from one dialog straight to the next. One dialog gets one card.
   the text shown on screen, the only version on disk.
 
 On the first start the bot posts only what happens from then on, never older history.
-A shell reports no turns, so after you type a command into one, the bot posts its screen.
+A new room is not empty: it gets the conversation before it, all of it as a `.md` file
+and its newest part in one folded post, silent and never repeated (`HERDR_HISTORY` says
+which: `file,folded` by default, `file`, `folded`, or empty for neither). `/history` in a
+room posts both again.
+
+In a terminal that runs no agent, what you type gets one reply: its screen a moment
+later, without blank lines.
+
+A group belongs to its herdr-app tab (by the tab's id): when the tab's terminal is
+replaced, the new terminal carries on in the same group. A message that cannot be
+delivered (the terminal has ended) says so plainly.
 
 ## Commands
 

package/lib/chats/contract.mjs

@@ -0,0 +1,58 @@
+// What a chat app gives the core (lib/core/engine.mjs). Each app is a folder,
+// lib/chats/<app>/, whose index.mjs exports create(ctx) returning an object with every
+// member below, and `requires`: the config.env keys it cannot start without. Register it
+// in lib/chats/index.mjs. `checkChat` runs at start and in the tests, so an app that
+// misses one fails at once, not when a terminal first needs it.
+//
+// The core's words: a "room" is where one herdr-app tab is mirrored (a Feishu group, a
+// Telegram topic); `k` is the core's key for a tab's terminal, stable while the room is
+// that terminal's; `room` and `message` are the app's own ids, kept by the core as given.
+// Markdown is the core's: **bold**, `code`, ``` blocks, > quotes, [text](url); an app
+// turns it into what it can show. A `look` is {title, tone, markdown}; tone is one of
+// 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}
+
+export const CHAT_MEMBERS = {
+  name: 'string: the app, as in HERDRCHAT_CHAT',
+  ready: '() -> boolean: the owner is known (no room is made before)',
+  help: 'string[]: lines it adds to the direct chat\'s help',
+  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',
+  command: '(cmd, args, where) -> boolean: one of its own direct-chat commands, handled',
+  openRoom: '({name, intro}) -> room',
+  renameRoom: '(room, name)',
+  placeRoom: '(k, {space}): what a live room looks like (tags, avatar, quiet)',
+  endRoom: '(k): what a room whose terminal ended looks like',
+  reviveRoom: '(k): live again',
+  post: '(room, markdown) -> message',
+  reply: '(where, markdown) -> message: where a message came from',
+  postCard: '(room, look) -> message: an editable message',
+  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',
+  unpin: '(k)',
+  pinned: '() -> k[]',
+  ring: '(k, message, text): make the phone ring for this message if it would not',
+  markWorking: '(message) -> token: your message reached the terminal',
+  markDone: '(message, token): the turn that took it is over',
+  image: '(buffer) -> markdown: an image to show in a post',
+  postFile: '(room, {name, data: Buffer, caption}) -> message: a file in the room, silent',
+  postFolded: '(room, {title, markdown}) -> message: a post that shows its title and opens on a tap, silent',
+  foldedBytes: 'number: how much text one folded post holds',
+  download: '(message, ref, file): an image you sent, saved to file',
+  tellOwner: '(look): a message in the direct chat',
+  showOverview: '(rows, {fresh}): rows [{name, address, state, kind, program, since, room}]',
+};
+
+const TYPES = { name: 'string', help: 'object', liveBytes: 'number', foldedBytes: 'number' };
+
+// Throws, naming every member that is missing or of the wrong kind.
+export function checkChat(chat) {
+  const wrong = Object.keys(CHAT_MEMBERS).filter((m) => typeof chat?.[m] !== (TYPES[m] || 'function'));
+  if (wrong.length) throw new Error(`chat app ${chat?.name || '?'} does not give: ${wrong.join(', ')} (lib/chats/contract.mjs)`);
+  return chat;
+}

package/lib/{feishu.mjs → chats/feishu/client.mjs}

@@ -147,6 +147,24 @@ export async function uploadImage(client, buffer, type = 'message') {
   return key;
 }
 
+// A file in a chat: uploaded (file_type "stream": any kind; at most 30 MB, never empty;
+// im:resource), then sent by its key as a "file" message. Returns the message id.
+export async function sendFile(client, chatId, name, buffer) {
+  const up = await client.im.v1.file.create({ data: { file_type: 'stream', file_name: name, file: buffer } });
+  const key = up?.file_key || up?.data?.file_key;
+  if (!key) throw new Error(`feishu file.create: no file_key (${JSON.stringify(up).slice(0, 200)})`);
+  const res = await createMessage(client, 'chat_id', chatId, 'file', JSON.stringify({ file_key: key }));
+  return res?.data?.message_id || null;
+}
+
+// A card that shows its title and opens on a tap (card JSON 2.0 collapsible_panel).
+export function foldedCard(title, markdown) {
+  return {
+    schema: '2.0',
+    body: { elements: [{ tag: 'collapsible_panel', expanded: false, header: { title: { tag: 'markdown', content: `**${title}**` } }, border: { color: 'grey', corner_radius: '5px' }, elements: [{ tag: 'markdown', content: markdown }] }] },
+  };
+}
+
 // An image someone sent in a chat the bot is in, saved to `file`. Needs im:message:readonly.
 export async function downloadImage(client, messageId, imageKey, file) {
   const res = await client.im.v1.messageResource.get({ path: { message_id: messageId, file_key: imageKey }, params: { type: 'image' } });
@@ -240,12 +258,15 @@ export async function renameChat(client, chatId, name) {
 // Messages in (im.message.receive_v1) and card clicks (card.action.trigger), both over
 // the long connection. A click must be answered within 3 seconds; what `onCardAction`
 // returns ({toast, card}) is that answer.
-export function startEvents(cfg, onMessage, onCardAction) {
+export function startEvents(cfg, onMessage, onCardAction, onReady = () => {}) {
   const ws = new Lark.WSClient({
     appId: cfg.appId,
     appSecret: cfg.appSecret,
     loggerLevel: Lark.LoggerLevel.warn,
-    onReady: () => console.log('[feishu] connected'),
+    onReady: () => {
+      console.log('[feishu] connected');
+      onReady();
+    },
     onReconnecting: () => console.warn('[feishu] reconnecting'),
     onReconnected: () => console.log('[feishu] reconnected'),
     onError: (err) => console.error(`[feishu] connection failed: ${err.message}`),