@rcpooley/botyard 0.1.0 → 0.2.0

package/dist/api.js

@@ -36,6 +36,7 @@ export async function call(url, key, method, path, body, retried = false) {
             return call(url, key, method, path, body, true);
         }
     }
+    warnOnce(res);
     const text = await res.text();
     if (!res.ok) {
         let message = `HTTP ${res.status}`;
@@ -49,5 +50,22 @@ export async function call(url, key, method, path, body, retried = false) {
     }
     return (text ? JSON.parse(text) : undefined);
 }
+let warned = false;
+/**
+ * Botyard's Botyard-Warning header says something is wrong with the bot itself
+ * that its owner has to fix (Message Content switched off). Printed once per
+ * run, to stderr, so it never mixes with output a script or agent parses.
+ */
+export function warnOnce(res) {
+    const warning = res.headers.get('botyard-warning');
+    if (warning)
+        warnText(warning);
+}
+export function warnText(warning) {
+    if (warned)
+        return;
+    warned = true;
+    process.stderr.write(`botyard: warning: ${warning}\n`);
+}
 /** A path segment from something a person typed: a name with spaces, a #channel, an emoji. */
 export const seg = (s) => encodeURIComponent(s);

package/dist/botyard.js

@@ -6,6 +6,7 @@ import { ApiFailure, call, seg } from "./api.js";
 import { configPath, DEFAULT_URL, load, pickBot, save } from "./config.js";
 import * as fmt from "./format.js";
 import { installSkill, SKILL, skillDir, skillInstalled } from "./skill.js";
+import { watch } from "./watch.js";
 /**
  * botyard: Discord through Botyard, from a terminal. Made for AI agents first,
  * so the guide (no arguments, or --help) is written to one, and every error is
@@ -93,6 +94,33 @@ const COMMANDS = [
             return fmt.messages(res.messages, `#${channel.replace(/^#/, '')} in ${server}`, more);
         },
     },
+    {
+        name: 'watch',
+        group: 'Reading',
+        usage: 'watch [--server <server>]... [--channel <server>#<channel>]... [--include-own] [--json]',
+        summary: 'stay open and print each new message the moment it is posted, one line each',
+        details: [
+            'With no options it carries every server the bot is in that the key can read. --server <server> and --channel <server>#<channel> narrow it; repeat either, and a message matching any of them prints. Ids or names: --channel "My Server#general".',
+            'Botyard pushes each message as it is posted: no polling, nothing printed while it is quiet.',
+            "Each line is one message: id, time (UTC), server #channel, author, text (newlines shown as ⏎). The bot's own messages are skipped unless --include-own. --json prints one JSON object per line instead.",
+            'It runs until stopped. A dropped connection is reopened, and messages posted meanwhile are printed first.',
+            'In Claude Code, run it with the Monitor tool, so each new message wakes you the moment it arrives; narrow it to what you need, since every line wakes you. Never poll with read in a loop.',
+        ],
+        args: 0,
+        run: async (_a, opts) => {
+            const { url, key } = target(opts);
+            return watch({
+                url,
+                key,
+                servers: opts.server ?? [],
+                channels: opts.channel ?? [],
+                includeOwn: opts['include-own'] === true,
+                json: opts.json,
+                out: (l) => process.stdout.write(l + '\n'),
+                log: (l) => process.stderr.write(l + '\n'),
+            });
+        },
+    },
     {
         name: 'message',
         group: 'Reading',
@@ -208,6 +236,8 @@ const COMMANDS = [
             if (!config.default || !config.bots[config.default])
                 config.default = res.me.bot.id;
             save(config);
+            // So every future Claude Code session on this machine knows botyard is here.
+            const skill = skillInstalled() ? null : installSkill();
             if (opts.json)
                 return json(res.me);
             return [
@@ -219,6 +249,7 @@ const COMMANDS = [
                     ? `This replaces the key you had for this bot (${previous.keyId}). It still works until its owner revokes it on Botyard.\n`
                     : '',
                 config.default === res.me.bot.id ? 'It is your default bot.' : `Your default bot is still ${config.bots[config.default].name}; pass --bot ${quote(res.me.bot.name)} to use this one.`,
+                skill ? `Installed the Claude Code skill (${skill}), so future sessions know about botyard.` : '',
                 'Next: run botyard with no arguments to see what you can do.',
             ]
                 .filter((l) => l !== '')
@@ -321,6 +352,8 @@ function guide() {
         '- Mentions ping people, not @everyone/@here/roles, unless you pass --mentions all. Only do that when asked.',
         "- If something is refused, the error says why. Permissions belong to the bot's owner, on Botyard; ask them.",
         '- Writes are limited to 60 a minute. Never send or react in a loop.',
+        "- If messages from others read as empty, the bot's Message Content intent is off; botyard prints a warning saying how to fix it. Only the bot's owner can, so pass it on to your human.",
+        "- To hear about new messages as they arrive, run `botyard watch` (in Claude Code, with the Monitor tool; repeatable --server and --channel <server>#<channel> narrow it). Don't poll with read.",
         '',
         skillInstalled()
             ? `Claude Code skill: installed (${skillDir()}).`
@@ -351,6 +384,9 @@ async function main(argv) {
                 before: { type: 'string' },
                 'reply-to': { type: 'string' },
                 mentions: { type: 'string' },
+                'include-own': { type: 'boolean', default: false },
+                server: { type: 'string', multiple: true },
+                channel: { type: 'string', multiple: true },
             },
         });
     }

package/dist/skill.js

@@ -15,7 +15,7 @@ export function skillInstalled() {
 }
 export const SKILL = `---
 name: botyard
-description: Read and send Discord messages through the user's own bot, using the botyard CLI. Use whenever the user asks about Discord -- reading a channel, catching up on a server, posting, replying, reacting or pinning -- or mentions Botyard.
+description: Read, send and follow Discord messages through the user's own bot, using the botyard CLI. Use whenever the user asks about Discord -- reading a channel, catching up on a server, posting, replying, reacting, pinning, or watching a channel for new messages -- or mentions Botyard.
 ---
 
 # botyard
@@ -24,6 +24,10 @@ The \`botyard\` CLI is installed and connected to the user's Discord bot (or bot
 
 **Run \`botyard\` with no arguments first.** It lists the connected bots, every command with an example, and the rules for using them. \`botyard <command> --help\` covers one command.
 
+If messages from other people come back empty, the bot's Message Content intent is off. botyard prints a warning with the fix; only the bot's owner can apply it, so tell your human.
+
+To follow a channel, don't poll: run \`botyard watch\` with the Monitor tool (repeatable \`--server <server>\` and \`--channel "<server>#<channel>"\` narrow it to what you care about). Botyard pushes each new message the moment it is posted, as one line.
+
 Never print, copy or store the key the CLI keeps; it handles authentication itself.
 `;
 export function installSkill() {

package/dist/watch.js

@@ -0,0 +1,160 @@
+import { ApiFailure, call, seg, warnOnce, warnText } from "./api.js";
+/**
+ * `botyard watch`: hold the event stream open and print each new message the
+ * moment Botyard pushes it, one line per message, so a tool that wakes on
+ * output (Claude Code's Monitor) reacts in about a second without polling.
+ * With no filters it carries every server the key can read; --server and
+ * --channel <server>#<channel> narrow it, each repeatable.
+ *
+ * It never returns on its own: a dropped stream is reopened, and what was
+ * posted meanwhile is read and printed first -- in every channel a message has
+ * come from during this run, and the one asked for. Only a refusal (a revoked
+ * key, a server it may not read) ends it.
+ */
+const RETRY_FIRST_MS = 1_000;
+const RETRY_MAX_MS = 30_000;
+export async function watch(o) {
+    for (const c of o.channels) {
+        if (c.lastIndexOf('#') <= 0)
+            throw new Error(`--channel '${c}' needs its server: use <server>#<channel>, e.g. --channel "My Server#general".`);
+    }
+    const me = await call(o.url, o.key, 'GET', '/me');
+    const own = me.bot.userId || me.bot.id;
+    const query = new URLSearchParams([...o.servers.map((s) => ['server', s]), ...o.channels.map((c) => ['channel', c])]);
+    // Snowflakes grow with time, across every channel, so "newer than the last
+    // one printed" is a single number comparison.
+    let last = 0n;
+    /** Channels to catch up on after a drop, by server id + channel id. */
+    const seen = new Map();
+    /** The channels asked for by name, caught up on even before a message has come from them. */
+    const asked = o.channels.map((c) => {
+        const split = c.lastIndexOf('#');
+        const server = c.slice(0, split);
+        const channel = c.slice(split + 1);
+        return { server: { id: server, name: server }, channel: { id: channel, name: channel } };
+    });
+    let retry = RETRY_FIRST_MS;
+    const print = (m) => {
+        seen.set(`${m.server.id}/${m.channel.id}`, { server: m.server, channel: m.channel });
+        const id = BigInt(m.id);
+        if (id <= last)
+            return;
+        last = id;
+        if (!o.includeOwn && m.author.id === own)
+            return;
+        o.out(o.json ? JSON.stringify(m) : line(m));
+    };
+    const backoff = async (why) => {
+        o.log(`botyard: ${why}; retrying in ${retry / 1000}s`);
+        await sleep(retry);
+        retry = Math.min(retry * 2, RETRY_MAX_MS);
+    };
+    for (;;) {
+        let res;
+        try {
+            res = await fetch(`${o.url.replace(/\/+$/, '')}/api/v1/events${query.size ? `?${query}` : ''}`, {
+                headers: { authorization: `Bearer ${o.key}`, accept: 'text/event-stream', 'user-agent': 'botyard-cli' },
+            });
+        }
+        catch (e) {
+            await backoff(`could not reach ${o.url} (${e instanceof Error ? e.message : e})`);
+            continue;
+        }
+        warnOnce(res);
+        if (!res.ok || !res.body) {
+            const message = await res.text().then(errorText, () => `HTTP ${res.status}`);
+            // A refusal will not change by retrying; a 5xx (the bot reconnecting, a deploy) will.
+            if (res.status < 500 && res.status !== 429)
+                throw new ApiFailure(res.status, message);
+            await backoff(message);
+            continue;
+        }
+        // The stream is open, so nothing new can slip past it. Before reading it,
+        // catch up on what was posted while it was down; the stream's own copy of
+        // any of those is skipped by the id check in print().
+        if (last > 0n)
+            await catchUp(o, [...asked, ...seen.values()], print);
+        else {
+            const named = [...o.servers.map((s) => `all of ${s}`), ...o.channels];
+            const scope = named.length ? named.join(', ') : 'every server this key can read';
+            o.log(`botyard: watching ${scope}. Each new message prints as one line${o.includeOwn ? '' : `; ${me.bot.name}'s own are skipped`}.`);
+        }
+        retry = RETRY_FIRST_MS;
+        try {
+            for await (const event of events(res.body)) {
+                if (event.name === 'message')
+                    print(JSON.parse(event.data));
+                else if (event.name === 'missed') {
+                    const m = JSON.parse(event.data);
+                    o.log(`botyard: missed message ${m.id} in ${m.server.name} #${m.channel.name}; read it with botyard message`);
+                }
+                else if (event.name === 'warning')
+                    warnText(JSON.parse(event.data).warning);
+                else if (event.name === 'end')
+                    throw new ApiFailure(403, JSON.parse(event.data).error);
+            }
+            o.log('botyard: the stream closed; reopening');
+        }
+        catch (e) {
+            if (e instanceof ApiFailure)
+                throw e;
+            o.log(`botyard: the stream dropped (${e instanceof Error ? e.message : e}); reopening`);
+        }
+        await sleep(RETRY_FIRST_MS);
+    }
+}
+/** Read the channels this run has seen and print what is newer than the last message printed, oldest first. */
+async function catchUp(o, channels, print) {
+    const missed = [];
+    for (const where of channels) {
+        try {
+            const page = await call(o.url, o.key, 'GET', `/servers/${seg(where.server.id)}/channels/${seg(where.channel.id)}/messages?limit=100`);
+            missed.push(...page.messages.map((m) => ({ ...m, ...where })));
+        }
+        catch (e) {
+            o.log(`botyard: could not catch up on ${where.server.name} #${where.channel.name} (${e instanceof Error ? e.message : e})`);
+        }
+    }
+    // A channel both asked for and seen is read twice; print() drops the second copy by id.
+    missed.sort((a, b) => (BigInt(a.id) < BigInt(b.id) ? -1 : 1)).forEach(print);
+}
+/** One message on one line: newlines in the text become ⏎, so each line is exactly one message. */
+export function line(m) {
+    const name = m.author.displayName && m.author.displayName !== m.author.username ? `${m.author.displayName} (${m.author.username})` : m.author.username;
+    const flags = [m.author.bot ? '[bot]' : '', m.replyTo ? `↩ ${m.replyTo}` : ''].filter(Boolean).join(' ');
+    const extras = [...m.attachments.map((a) => `[attachment ${a.name}]`), ...m.embeds.map((e) => `[embed ${e.title ?? e.url ?? ''}]`)];
+    const text = [m.content.replace(/\r?\n/g, ' ⏎ '), ...extras].filter(Boolean).join(' ') || '(no text)';
+    return `${m.id}  ${m.createdAt.slice(11, 19)}  ${m.server.name} #${m.channel.name}  ${name}${flags ? ' ' + flags : ''}: ${text}`;
+}
+/** Server-Sent Events from a fetch body: { name, data } per event; comments are skipped. */
+async function* events(body) {
+    const decoder = new TextDecoder();
+    let buffer = '';
+    for await (const chunk of body) {
+        buffer += decoder.decode(chunk, { stream: true });
+        let end;
+        while ((end = buffer.indexOf('\n\n')) >= 0) {
+            const block = buffer.slice(0, end);
+            buffer = buffer.slice(end + 2);
+            let name = 'message';
+            const data = [];
+            for (const l of block.split('\n')) {
+                if (l.startsWith('event:'))
+                    name = l.slice(6).trim();
+                else if (l.startsWith('data:'))
+                    data.push(l.slice(5).trimStart());
+            }
+            if (data.length)
+                yield { name, data: data.join('\n') };
+        }
+    }
+}
+function errorText(text) {
+    try {
+        return JSON.parse(text).error ?? text;
+    }
+    catch {
+        return text || 'no answer';
+    }
+}
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rcpooley/botyard",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Read and send in Discord through your own bot, hosted by Botyard. Made for AI agents.",
   "type": "module",
   "bin": {