herdrchat 0.0.0-stage → 0.1.0

package/lib/feishu.mjs

@@ -0,0 +1,273 @@
+// Feishu side: one client, markdown cards, dialog cards with buttons, one group per
+// hc terminal.
+import * as Lark from '@larksuiteoapi/node-sdk';
+
+const CHUNK = 6000;
+
+// The SDK would also print every failed request; the bot logs its own failures, with
+// what it was doing, so the SDK's logger says nothing. (Its "fatal" level is 0, which the
+// SDK reads as unset and turns into "info", hence a silent logger instead.)
+const SILENT = { error() {}, warn() {}, info() {}, debug() {}, trace() {} };
+
+export function createClient(cfg) {
+  return new Lark.Client({ appId: cfg.appId, appSecret: cfg.appSecret, logger: SILENT, loggerLevel: Lark.LoggerLevel.error });
+}
+
+// Splits on line boundaries; a code fence cut in two is closed and reopened.
+export function chunk(text, size = CHUNK) {
+  const parts = [];
+  let current = [];
+  let length = 0;
+  let fence = null;
+  const flush = () => {
+    if (!current.length) return;
+    let body = current.join('\n');
+    if (fence !== null) body += '\n```';
+    parts.push(body);
+    current = fence !== null ? [fence] : [];
+    length = current.length ? fence.length : 0;
+  };
+  for (const raw of text.split('\n')) {
+    for (let line = raw; ; ) {
+      const piece = line.length > size ? line.slice(0, size) : line;
+      if (length + piece.length + 1 > size && current.length) flush();
+      current.push(piece);
+      length += piece.length + 1;
+      if (/^\s*```/.test(piece)) fence = fence === null ? piece.trim() : null;
+      if (line.length <= size) break;
+      line = line.slice(size);
+    }
+  }
+  if (current.length) {
+    parts.push(current.join('\n'));
+  }
+  return parts.length ? parts : [''];
+}
+
+function card(markdown) {
+  return JSON.stringify({ schema: '2.0', body: { elements: [{ tag: 'markdown', content: markdown }] } });
+}
+
+// A markdown card that can be edited after it is sent (updateCard needs update_multi
+// on the card both before and after).
+export function textCard(markdown, title, template) {
+  return { schema: '2.0', config: { update_multi: true }, header: { title: { tag: 'plain_text', content: title }, template }, body: { elements: [{ tag: 'markdown', content: markdown }] } };
+}
+
+export async function updateCard(client, messageId, cardJson) {
+  const res = await client.im.v1.message.patch({ path: { message_id: messageId }, data: { content: JSON.stringify(cardJson) } });
+  if (res?.code) throw new Error(`feishu message.patch ${res.code}: ${res.msg}`);
+}
+
+async function createMessage(client, receiveIdType, receiveId, msgType, content) {
+  const res = await client.im.v1.message.create({
+    params: { receive_id_type: receiveIdType },
+    data: { receive_id: receiveId, msg_type: msgType, content },
+  });
+  if (res?.code) throw new Error(`feishu message.create ${res.code}: ${res.msg}`);
+  return res;
+}
+
+// A markdown card per chunk; plain text when the card is refused. Returns the id of the
+// last message sent.
+export async function sendMarkdown(client, chatId, text) {
+  let last = null;
+  for (const part of chunk(text || '(empty)')) {
+    try {
+      last = await createMessage(client, 'chat_id', chatId, 'interactive', card(part));
+    } catch (err) {
+      last = await createMessage(client, 'chat_id', chatId, 'text', JSON.stringify({ text: part }));
+      console.warn(`[feishu] card refused, sent as text: ${err.message}`);
+    }
+  }
+  return last?.data?.message_id || null;
+}
+
+// A one-line reply that @-mentions someone. Feishu notifies a mention in a text message
+// even in a muted group; a mention inside a card is not counted as one.
+export async function replyMention(client, messageId, openId, text) {
+  const res = await client.im.v1.message.reply({ path: { message_id: messageId }, data: { msg_type: 'text', content: JSON.stringify({ text: `<at user_id="${openId}"></at> ${text}` }) } });
+  if (res?.code) throw new Error(`feishu message.reply ${res.code}: ${res.msg}`);
+}
+
+// A card that asks you to pick: the screen, one button per option and, when the program
+// takes your own words, a box to type them. Every button and the box send a callback
+// (card.action.trigger) whose value is `value` plus {pick: <option number>, label} (or
+// {pick: 'tab'} / {pick: 'esc'}); the box's text comes back as form_value.answer.
+const BUTTON_TEXT = 80;
+
+function button(text, value, type = 'default') {
+  const short = text.length > BUTTON_TEXT ? `${text.slice(0, BUTTON_TEXT - 1)}…` : text;
+  return { tag: 'button', type, width: 'fill', text: { tag: 'plain_text', content: short }, behaviors: [{ type: 'callback', value }] };
+}
+
+export function menuCard({ title, markdown, menu, value }) {
+  const elements = [{ tag: 'markdown', content: markdown }];
+  for (const o of menu.options) {
+    if (o === menu.free) continue;
+    const box = o.checked === null ? '' : o.checked ? '☑ ' : '☐ ';
+    elements.push(button(`${o.n}. ${box}${o.label}`, { ...value, pick: o.n, label: o.label }, o.n === 1 && !menu.multi ? 'primary' : 'default'));
+  }
+  if (menu.multi) elements.push(button('Next ⇥', { ...value, pick: 'tab' }, 'primary'));
+  if (menu.free) {
+    elements.push({
+      tag: 'form',
+      name: 'free',
+      elements: [
+        { tag: 'input', name: 'answer', required: true, placeholder: { tag: 'plain_text', content: menu.free.label } },
+        { ...button('Send', { ...value, pick: menu.free.n, label: menu.free.label }, 'primary'), name: 'send', form_action_type: 'submit' },
+      ],
+    });
+  }
+  elements.push(button('Esc (cancel)', { ...value, pick: 'esc' }, 'danger'));
+  return { schema: '2.0', config: { update_multi: true }, header: { title: { tag: 'plain_text', content: title }, template: 'red' }, body: { elements } };
+}
+
+// The card once it is answered: the same text, no buttons, and what was done.
+export function doneCard(title, markdown, done) {
+  return { schema: '2.0', config: { update_multi: true }, header: { title: { tag: 'plain_text', content: title }, template: 'grey' }, body: { elements: [{ tag: 'markdown', content: `${markdown}\n\n**${done}**` }] } };
+}
+
+// Takes back a message the bot sent.
+export async function recallMessage(client, messageId) {
+  const res = await client.im.v1.message.delete({ path: { message_id: messageId } });
+  if (res?.code) throw new Error(`feishu message.delete ${res.code}: ${res.msg}`);
+}
+
+export async function sendCard(client, chatId, cardJson, idType = 'chat_id') {
+  return createMessage(client, idType, chatId, 'interactive', JSON.stringify(cardJson));
+}
+
+// An image for a message (shown in a card's markdown as ![image](<image_key>)) or a group
+// avatar (type 'avatar'). Needs the im:resource scope.
+export async function uploadImage(client, buffer, type = 'message') {
+  const res = await client.im.v1.image.create({ data: { image_type: type, image: buffer } });
+  const key = res?.image_key || res?.data?.image_key;
+  if (!key) throw new Error(`feishu image.create: no image_key (${JSON.stringify(res).slice(0, 200)})`);
+  return key;
+}
+
+// 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' } });
+  await res.writeFile(file);
+}
+
+// What a received message says: its text and the keys of its images, in order, for
+// text, image and rich text (post) messages; null for any other kind.
+export function messageParts(messageType, content) {
+  const c = JSON.parse(content);
+  if (messageType === 'text') return { text: c.text || '', images: [] };
+  if (messageType === 'image') return { text: '', images: [c.image_key] };
+  if (messageType !== 'post') return null;
+  const lines = [];
+  const images = [];
+  if (c.title) lines.push(c.title);
+  for (const paragraph of c.content || []) {
+    let line = '';
+    for (const el of paragraph) {
+      if (el.tag === 'img' && el.image_key) images.push(el.image_key);
+      else if (el.tag === 'a' && el.href) line += `${el.text || ''} (${el.href})`;
+      else if (typeof el.text === 'string') line += el.text; // text, code_block, md, ...
+    }
+    lines.push(line);
+  }
+  return { text: lines.join('\n').trim(), images };
+}
+
+// One group per terminal, with you in it. You can type in it: that text goes to the terminal.
+export async function createChat(client, ownerOpenId, name, description) {
+  const res = await client.im.v1.chat.create({
+    params: { user_id_type: 'open_id' },
+    data: { name: name.slice(0, 60), description, user_id_list: [ownerOpenId], group_message_type: 'chat' },
+  });
+  if (res?.code) throw new Error(`feishu chat.create ${res.code}: ${res.msg}`);
+  return res.data.chat_id;
+}
+
+// Group tags (enterprise custom tags): one tenant tag, bound to a group. Needs
+// im:tag:write and im:biz_entity_tag_relation:write.
+// Feishu refuses a tag name over 16 characters (code 407, found by trying); a longer
+// one is cut at the last "-", "_" or "." that fits: build-agent-server -> build-agent.
+const TAG_MAX = 16;
+
+export function tagName(name) {
+  if (name.length <= TAG_MAX) return name;
+  const cut = Math.max(...['-', '_', '.'].map((c) => name.lastIndexOf(c, TAG_MAX)));
+  return cut > 0 ? name.slice(0, cut) : name.slice(0, TAG_MAX);
+}
+
+export async function createTag(client, name) {
+  const res = await client.im.v2.tag.create({ data: { create_tag: { tag_type: 'tenant', name: tagName(name) } } });
+  if (res?.code || !res?.data?.id) throw new Error(`feishu tag.create ${res?.code}: ${res?.msg}`);
+  return res.data.id;
+}
+
+// Tag calls are limited to 5 a second: they go out one at a time, TAG_GAP_MS apart, so a
+// burst (every group at once) is not refused.
+const TAG_GAP_MS = 250;
+let tagQueue = Promise.resolve();
+function queued(fn) {
+  const run = tagQueue.then(fn);
+  tagQueue = run.catch(() => {}).then(() => new Promise((ok) => setTimeout(ok, TAG_GAP_MS)));
+  return run;
+}
+
+export function bindTag(client, tagId, chatId) {
+  return queued(async () => {
+    const res = await client.im.v2.bizEntityTagRelation.create({ data: { tag_biz_type: 'chat', biz_entity_id: chatId, tag_ids: [tagId] } });
+    if (res?.code) throw new Error(`feishu tag bind ${res.code}: ${res.msg}`);
+  });
+}
+
+export function unbindTag(client, tagId, chatId) {
+  return queued(async () => {
+    const res = await client.im.v2.bizEntityTagRelation.update({ data: { tag_biz_type: 'chat', biz_entity_id: chatId, tag_ids: [tagId] } });
+    if (res?.code) throw new Error(`feishu tag unbind ${res.code}: ${res.msg}`);
+  });
+}
+
+export async function setChatAvatar(client, chatId, imageKey) {
+  const res = await client.im.v1.chat.update({ path: { chat_id: chatId }, data: { avatar: imageKey } });
+  if (res?.code) throw new Error(`feishu chat.update avatar ${res.code}: ${res.msg}`);
+}
+
+export async function renameChat(client, chatId, name) {
+  const res = await client.im.v1.chat.update({ path: { chat_id: chatId }, data: { name: name.slice(0, 60) } });
+  if (res?.code) throw new Error(`feishu chat.update ${res.code}: ${res.msg}`);
+}
+
+// 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) {
+  const ws = new Lark.WSClient({
+    appId: cfg.appId,
+    appSecret: cfg.appSecret,
+    loggerLevel: Lark.LoggerLevel.warn,
+    onReady: () => console.log('[feishu] connected'),
+    onReconnecting: () => console.warn('[feishu] reconnecting'),
+    onReconnected: () => console.log('[feishu] reconnected'),
+    onError: (err) => console.error(`[feishu] connection failed: ${err.message}`),
+  });
+  ws.start({
+    eventDispatcher: new Lark.EventDispatcher({}).register({
+      'im.message.receive_v1': async (data) => {
+        try {
+          await onMessage(data);
+        } catch (err) {
+          console.error(`[feishu] message handler: ${err.stack || err.message}`);
+        }
+      },
+      'card.action.trigger': async (data) => {
+        try {
+          return await onCardAction(data);
+        } catch (err) {
+          console.error(`[feishu] card handler: ${err.stack || err.message}`);
+          return { toast: { type: 'error', content: err.message.slice(0, 200) } };
+        }
+      },
+    }),
+  });
+  return ws;
+}

package/lib/hc.mjs

@@ -0,0 +1,84 @@
+// Thin wrapper over the hc CLI. Every call names its session (HC_SESSION),
+// never the default core.
+import { execFile } from 'node:child_process';
+
+// The bot runs in an hc terminal itself. Called with that terminal's identity, hc would
+// wrap what the bot types in <hc from="tN"> tags, as a note from another agent; without
+// it the text arrives as if you typed it.
+const { HC_TERMINAL_ID, HC_SCOPE, HC_TERMINAL_SOCKET, ...ENV } = process.env;
+
+export function hc(session, args, { timeoutMs = 15000 } = {}) {
+  return new Promise((resolve, reject) => {
+    execFile(
+      'hc',
+      args,
+      { env: { ...ENV, HC_SESSION: session }, timeout: timeoutMs, maxBuffer: 16 * 1024 * 1024 },
+      (err, stdout, stderr) => {
+        if (err) {
+          err.message = `hc ${args.join(' ')}: ${(stderr || stdout || err.message).trim()}`;
+          reject(err);
+          return;
+        }
+        resolve(stdout);
+      },
+    );
+  });
+}
+
+async function json(session, args) {
+  return JSON.parse(await hc(session, [...args, '--json']));
+}
+
+// The machines a session is connected to: [{name, state}], state "connected" when up.
+export async function machines(session) {
+  return (await json(session, ['ls'])).machines || [];
+}
+
+export async function getTerminal(session, address) {
+  return json(session, ['get', address]);
+}
+
+// `where` is "<space> / <tab>", set by herdr-app on every terminal it shows.
+export function splitWhere(where) {
+  const i = (where || '').indexOf(' / ');
+  if (i < 0) return null;
+  return { space: where.slice(0, i), tab: where.slice(i + 3) };
+}
+
+export function run(session, { name, cwd, labels = {}, argv }) {
+  const args = ['run', '--bg', '--no-parent', '--json', ...(name ? ['--name', name] : []), '--cwd', cwd];
+  for (const [k, v] of Object.entries(labels)) args.push('--label', `${k}=${v}`);
+  args.push('--', ...argv);
+  return hc(session, args, { timeoutMs: 30000 });
+}
+
+// force: type even when the program is blocked on a dialog (it answers the dialog).
+export function send(session, address, text, { force = false } = {}) {
+  const args = ['send', ...(force ? ['--force'] : []), address, text];
+  return hc(session, args, { timeoutMs: 60000 });
+}
+
+// Sends a local file beside a terminal, on its machine; returns where it landed there.
+export async function put(session, address, file) {
+  return JSON.parse(await hc(session, ['put', address, file, '--json'], { timeoutMs: 60000 })).path;
+}
+
+export function keys(session, address, names) {
+  return hc(session, ['keys', address, ...names]);
+}
+
+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.
+export async function screenTail(session, address, lines) {
+  const out = await read(session, address, lines);
+  return out.split('\n').slice(-lines).join('\n').trimEnd();
+}
+
+// "machine/tN" for a terminal on a connected machine, "tN" here.
+export function machineOf(address) {
+  const i = address.lastIndexOf('/');
+  return i < 0 ? null : address.slice(0, i);
+}

package/lib/home.mjs

@@ -0,0 +1,26 @@
+// Files under the home folder of the machine a terminal runs on: read here, or through
+// `hc exec --on <machine>` for a terminal on a connected machine (cwd there is home).
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { hc } from './hc.mjs';
+import { itemsAfter } from './cursor.mjs';
+
+const TAIL_LINES = 1500;
+
+export async function homeFile(session, machine, rel, { tail } = {}) {
+  if (!machine) {
+    const text = fs.readFileSync(path.join(os.homedir(), rel), 'utf8');
+    return tail ? text.split('\n').slice(-tail).join('\n') : text;
+  }
+  const argv = tail ? ['tail', '-n', String(tail), rel] : ['cat', rel];
+  return hc(session, ['exec', '--on', machine, ...argv], { timeoutMs: 30000 });
+}
+
+// The items after `cursor` in a .jsonl log: its tail first, the whole file when the tail
+// does not reach back to the cursor.
+export async function logAfter(session, machine, rel, cursor, entryItems) {
+  const tail = itemsAfter((await homeFile(session, machine, rel, { tail: TAIL_LINES })).split('\n'), cursor, entryItems);
+  if (tail.complete) return tail.items;
+  return itemsAfter((await homeFile(session, machine, rel)).split('\n'), cursor, entryItems).items;
+}

package/lib/log.mjs

@@ -0,0 +1,59 @@
+// The bot's log, kept on disk so a problem can be looked into after a restart: every line
+// 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.
+import fs from 'node:fs';
+import path from 'node:path';
+import util from 'node:util';
+
+const KEEP_DAYS = 14;
+
+export function createLog(dir) {
+  fs.mkdirSync(dir, { recursive: true });
+  const out = { log: console.log.bind(console), error: console.error.bind(console) };
+  let pruned = '';
+
+  const prune = (today) => {
+    if (pruned === today) return;
+    pruned = today;
+    const oldest = new Date(Date.now() - KEEP_DAYS * 86400 * 1000).toISOString().slice(0, 10);
+    for (const f of fs.readdirSync(dir)) {
+      if (/^\d{4}-\d{2}-\d{2}\.log$/.test(f) && f.slice(0, 10) < oldest) fs.rmSync(path.join(dir, f), { force: true });
+    }
+  };
+
+  const write = (level, args) => {
+    const now = new Date().toISOString();
+    // one entry per line: a newline in a message (your text) shows as ⏎; a stack keeps its lines
+    const text = args.map((a) => (typeof a === 'string' ? a.replace(/\r?\n/g, ' ⏎ ') : a instanceof Error ? a.stack || a.message : util.inspect(a, { depth: 4, breakLength: Infinity }))).join(' ');
+    const line = `${now} ${level} ${text}`;
+    (level === 'ERROR' ? out.error : out.log)(line);
+    try {
+      fs.appendFileSync(path.join(dir, `${now.slice(0, 10)}.log`), `${line}\n`, { mode: 0o600 }); // it quotes your messages
+      prune(now.slice(0, 10));
+    } catch {
+      // the disk is the last resort; stdout has the line
+    }
+  };
+
+  const log = {
+    info: (...args) => write('INFO', args),
+    warn: (...args) => write('WARN', args),
+    error: (...args) => write('ERROR', args),
+  };
+
+  log.capture = () => {
+    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);
+    });
+    process.on('unhandledRejection', (err) => write('ERROR', ['unhandled rejection:', err]));
+  };
+
+  return log;
+}

package/lib/menu.mjs

@@ -0,0 +1,61 @@
+// The menu a blocked program shows on its screen, as Claude Code draws its permission
+// and question dialogs:
+//   ❯ 1. Yes                      a digit key picks an option
+//     2. [✔] Red                  in a multi-select, a digit toggles it; tab goes on
+//     3. Type something.          picking it lets you type your own answer
+// The last run of options numbered 1, 2, 3, ... on the screen is the menu; lines between
+// them (an option's description) are skipped. null when there is none.
+//
+// `text` is what the dialog says above its options: from its top border (a line of ─),
+// without rules and blank lines; what was on the screen above the dialog is left out.
+// `key` names the dialog: a hash of it from its top border to its last option, without
+// the cursor and the check marks. A card click is pressed only when the
+// screen still shows the dialog with that key, so an old card can never answer a newer
+// dialog that looks alike (two permission prompts both offer "1. Yes").
+import crypto from 'node:crypto';
+
+const OPTION = /^\s*(?:❯\s*)?(\d{1,2})\.\s+(?:\[(.)\]\s+)?(.*\S)\s*$/;
+const RULE = /^[\s─╌━-]*$/;
+const BORDER = /^\s*─{10,}/;
+const FREE = /^Type something/i;
+
+const TEXT_LINES = 15; // a dialog with no border found: this many lines above its options
+
+function topOf(lines, first) {
+  let top = first;
+  while (top > 0 && !BORDER.test(lines[top])) top -= 1;
+  return BORDER.test(lines[top]) ? top : Math.max(0, first - TEXT_LINES);
+}
+
+function keyOf(lines, top, last) {
+  const body = lines.slice(top, last + 1).map((l) => l.replace(/❯/g, '').replace(/^(\s*\d{1,2}\.\s+)\[.\]/, '$1').trim()).join('\n');
+  return crypto.createHash('sha1').update(body).digest('hex').slice(0, 12);
+}
+
+export function menuOf(screen) {
+  const lines = screen.split('\n');
+  let run = null;
+  let menu = null;
+  lines.forEach((line, i) => {
+    const m = line.match(OPTION);
+    if (!m) return;
+    const n = Number(m[1]);
+    if (n === 1) run = { first: i, options: [] };
+    else if (!run || n !== run.options.length + 1) {
+      run = null;
+      return;
+    }
+    run.options.push({ n, label: m[3], checked: m[2] === undefined ? null : m[2] !== ' ' });
+    run.last = i;
+    menu = run;
+  });
+  if (!menu) return null;
+  const top = topOf(lines, menu.first);
+  return {
+    key: keyOf(lines, top, menu.last),
+    text: lines.slice(top, menu.first).filter((l) => !RULE.test(l)).map((l) => l.trim()).join('\n'),
+    options: menu.options,
+    multi: menu.options.some((o) => o.checked !== null),
+    free: menu.options.find((o) => FREE.test(o.label)) || null,
+  };
+}

package/lib/overview.mjs

@@ -0,0 +1,42 @@
+// The overview: one card in the direct chat with the bot, as herdr-app's sidebar shows it.
+// Every terminal is a line: its state, its group (a link that opens it), what it waits on
+// and since when. What waits for you comes first. The card is edited in place, so it
+// never rings.
+const STATES = {
+  blocked: { icon: '⚠️', word: 'needs you', rank: 0 },
+  error: { icon: '🔴', word: 'error', rank: 1 },
+  working: { icon: '⌛️', word: 'working', rank: 2 },
+  done: { icon: '✅', word: 'done', rank: 3 },
+  idle: { icon: '❓', word: 'idle', rank: 4 },
+};
+const OTHER = { icon: '❓', word: '', rank: 5 };
+
+const chatLink = (chat) => `https://applink.feishu.cn/client/chat/open?openChatId=${chat}`;
+const clock = (ms) => new Date(ms).toLocaleTimeString('en-GB', { hour: '2-digit', minute: '2-digit' });
+const escape = (text) => text.replace(/[\\`*_[\]#>~|]/g, '\\$&');
+
+// rows: [{name, address, state, kind, program, since, chat}]; state is the hc status
+// word, or none. The address is what `/kill` takes.
+export function overviewText(rows) {
+  const sorted = [...rows].sort((a, b) => (STATES[a.state] || OTHER).rank - (STATES[b.state] || OTHER).rank || a.name.localeCompare(b.name));
+  if (!sorted.length) return 'No terminal is shown in herdr-app.';
+  return sorted.map((r) => {
+    const s = STATES[r.state] || OTHER;
+    const name = r.chat ? `[${escape(r.name)}](${chatLink(r.chat)})` : escape(r.name);
+    const word = s === OTHER ? r.program || 'no status' : `${s.word}${r.state === 'blocked' && r.kind ? ` (${r.kind})` : ''}`;
+    return `${s.icon} **${name}** · ${escape(word)}${r.since ? ` · since ${clock(r.since)}` : ''} · \`${r.address}\``;
+  }).join('\n');
+}
+
+export function overviewCard(rows, now) {
+  const waiting = rows.filter((r) => r.state === 'blocked').length;
+  const working = rows.filter((r) => r.state === 'working').length;
+  const template = waiting ? 'orange' : working ? 'blue' : 'green';
+  const title = `${waiting ? `⚠️ ${waiting} needs you · ` : ''}herdrchat · ${rows.length} terminals`;
+  return {
+    schema: '2.0',
+    config: { update_multi: true },
+    header: { title: { tag: 'plain_text', content: title }, template },
+    body: { elements: [{ tag: 'markdown', content: `${overviewText(rows)}\n\n<font color='grey'>Updated ${clock(now)}</font>` }] },
+  };
+}

package/lib/readers/claude.mjs

@@ -0,0 +1,119 @@
+// Reader for Claude Code (hc status app "claude-code"): its own transcript.
+//   Where: the terminal's foreground pid names the session in ~/.claude/sessions/<pid>.json
+//     ({sessionId, cwd}); the transcript is
+//     ~/.claude/projects/<cwd with every non-alphanumeric as "-">/<sessionId>.jsonl.
+//   What becomes an item:
+//     you  a prompt you typed (user entry from a human), a message you sent mid-turn
+//          (attachment "queued_command" from a human; the queue also carries Claude
+//          Code's own task notifications, which are left out), or your answers to its
+//          questions (the AskUserQuestion result's `answers`)
+//     ai   the assistant's text; `end` marks the turn's last answer (stop_reason
+//          "end_turn"). Some of what it says while it works is stored only as a
+//          "narration" block: a thinking block whose signature names narration, holding a
+//          condensed version of that text. Those count as text; plain thinking does not.
+//     tool a tool it called, as one line
+//     image an image you pasted (`from: 'you'`) or one a tool showed it (`from: 'ai'`:
+//          a screenshot, an image file it read), as {media, data} (base64)
+import { getTerminal, machineOf } from '../hc.mjs';
+import { homeFile, logAfter } from '../home.mjs';
+import { itemsAfter } from '../cursor.mjs';
+
+function text(content) {
+  if (typeof content === 'string') return content;
+  if (!Array.isArray(content) || content.some((b) => b.type === 'tool_result')) return '';
+  return content.filter((b) => b.type === 'text').map((b) => b.text).join('\n');
+}
+
+function isNarration(block) {
+  if (block.type !== 'thinking' || !block.thinking?.trim() || !block.signature) return false;
+  try {
+    return Buffer.from(block.signature, 'base64').includes('narration');
+  } catch {
+    return false;
+  }
+}
+
+function toolLine(block) {
+  const input = block.input || {};
+  const what = input.description || input.command || input.file_path || input.pattern || input.url || input.prompt || '';
+  const short = String(what).replace(/\s+/g, ' ').trim();
+  return `▸ ${block.name || 'tool'}${short ? `: ${short.length > 120 ? `${short.slice(0, 117)}...` : short}` : ''}`;
+}
+
+// The images in a user entry's content: ones you pasted (top-level blocks) and ones a
+// tool gave the assistant to look at (inside tool results: screenshots, image files).
+function images(content, human) {
+  if (!Array.isArray(content)) return [];
+  const out = [];
+  const add = (b, from) => {
+    if (b?.type === 'image' && b.source?.type === 'base64' && b.source.data) out.push({ role: 'image', from, media: b.source.media_type, data: b.source.data });
+  };
+  for (const b of content) {
+    if (human) add(b, 'you');
+    if (b.type === 'tool_result' && Array.isArray(b.content)) b.content.forEach((x) => add(x, 'ai'));
+  }
+  return out;
+}
+
+// The items one entry holds, in block order (an entry may hold text and tool calls).
+function entryItems(entry) {
+  if (entry.isSidechain) return [];
+  if (entry.type === 'user' && !entry.isMeta && entry.origin?.kind === 'human') {
+    const t = text(entry.message?.content).trim();
+    return [...(t ? [{ role: 'you', text: t }] : []), ...images(entry.message?.content, true)];
+  }
+  const shown = entry.type === 'user' && !entry.isMeta ? images(entry.message?.content, false) : [];
+  if (shown.length) return shown;
+  const answers = entry.type === 'user' && entry.toolUseResult?.answers;
+  if (answers && typeof answers === 'object') {
+    const t = Object.entries(answers).map(([q, a]) => `${q} → ${a}`).join('\n').trim();
+    return t ? [{ role: 'you', text: t }] : [];
+  }
+  const queued = entry.type === 'attachment' && entry.attachment?.type === 'queued_command' && entry.attachment;
+  if (queued) {
+    const t = queued.origin?.kind === 'human' ? text(queued.prompt).trim() : '';
+    return t ? [{ role: 'you', text: t }] : [];
+  }
+  if (entry.type !== 'assistant' || !Array.isArray(entry.message?.content)) return [];
+  const end = entry.message.stop_reason === 'end_turn';
+  const out = [];
+  for (const b of entry.message.content) {
+    const said = b.type === 'text' ? b.text : isNarration(b) ? b.thinking : '';
+    if (said && said.trim()) out.push({ role: 'ai', text: said.trim(), end });
+    else if (b.type === 'tool_use') out.push({ role: 'tool', text: toolLine(b) });
+  }
+  return out;
+}
+
+export function conversationAfter(lines, cursor) {
+  return itemsAfter(lines, cursor, entryItems);
+}
+
+export const app = 'claude-code';
+
+// 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
+// the cursor's old file comes first.
+export async function after(session, address, cursor) {
+  const machine = machineOf(address);
+  const pid = (await getTerminal(session, address)).foreground?.pid;
+  if (!pid) return null;
+  const meta = JSON.parse(await homeFile(session, machine, `.claude/sessions/${pid}.json`));
+  if (!meta.sessionId || !meta.cwd) return null;
+  const file = `.claude/projects/${meta.cwd.replace(/[^A-Za-z0-9]/g, '-')}/${meta.sessionId}.jsonl`;
+  const items = [];
+  if (cursor.file && cursor.file !== file) {
+    try {
+      items.push(...(await logAfter(session, machine, cursor.file, cursor, entryItems)));
+    } catch {
+      // the old transcript is gone; nothing left to read there
+    }
+  }
+  items.push(...(await logAfter(session, machine, file, cursor, entryItems)));
+  return { items, file };
+}
+
+// What the cursor's file still holds once the program is gone.
+export function rest(session, address, cursor) {
+  return logAfter(session, machineOf(address), cursor.file, cursor, entryItems);
+}