@rcpooley/botyard 0.1.0 → 0.3.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,35 @@ const COMMANDS = [
             return fmt.messages(res.messages, `#${channel.replace(/^#/, '')} in ${server}`, more);
         },
     },
+    {
+        name: 'watch',
+        group: 'Reading',
+        usage: 'watch [--server <server>]... [--channel <server>#<channel>]... [--thread <server>#<thread>]... [--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, channel and thread the bot is in that the key can read.',
+            '--server <server>, --channel <server>#<channel> (the channel and every thread in it) and --thread <server>#<thread> (just that thread) narrow it; repeat any of them, and a message matching any one prints. Ids or names: --channel "My Server#general", --thread "My Server#release plans".',
+            '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 (or server #channel › thread), author, text (newlines shown as ⏎). The bot's own messages are left out unless --include-own. --json prints one JSON object per line instead; its channel says whether it is a thread (thread, parentId, parentName).",
+            '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 ?? [],
+                threads: opts.thread ?? [],
+                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',
@@ -147,6 +177,24 @@ const COMMANDS = [
             return opts.json ? json(m) : `Sent ${m.id}\n${m.url}`;
         },
     },
+    {
+        name: 'thread',
+        group: 'Writing',
+        usage: 'thread <server> <channel> <name> [--from <message id>]',
+        summary: 'start a thread in a channel, from one of its messages with --from',
+        details: [
+            'Prints the new thread\'s id and name. Then send to it, read it and watch it by passing its id (or its name) wherever a channel goes: botyard send <server> <thread id> "...".',
+            'Names are 1-100 characters; words after <channel> are joined, so quotes are optional. Without --from it is a new public thread with no opening message.',
+            'For a new topic: post a short opening message in the channel, then botyard thread <server> <channel> <name> --from <that message id>, and keep the discussion in the thread. The channel then holds one entrance post per topic.',
+            'Threads close themselves after a week without messages; sending to one opens it again.',
+        ],
+        args: 3,
+        rest: true,
+        run: async ([server, channel, name], opts) => {
+            const thread = await api(opts, 'POST', `${where(server, channel)}/threads`, { name, ...(opts.from ? { message: opts.from } : {}) });
+            return opts.json ? json(thread) : `Started thread ${thread.id}  ${thread.name}\nSend to it: botyard send ${quote(server)} ${thread.id} "..."`;
+        },
+    },
     {
         name: 'edit',
         group: 'Writing',
@@ -208,6 +256,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 +269,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 !== '')
@@ -313,7 +364,7 @@ function guide() {
         '',
         ...groups.flatMap((g) => [g, '']),
         'Options: --bot <name|id> picks a bot, --json prints raw API responses, botyard <command> --help explains one command.',
-        'A <server> or <channel> is an id or a name ("general" or "#general"); quote names with spaces.',
+        'A <server> or <channel> is an id or a name ("general" or "#general"); quote names with spaces. A thread is a <channel> too.',
         '',
         'Rules, for agents:',
         `- Never print, copy or store the key. The CLI keeps it (in ${configPath()}) and sends it for you.`,
@@ -321,6 +372,9 @@ 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). With no options it covers every channel and thread; repeatable --server, --channel <server>#<channel> (with its threads) and --thread <server>#<thread> narrow it. Your own messages are left out. Don't poll with read.",
+        '- One topic, one thread: post a short opening message in the channel, then `botyard thread <server> <channel> <name> --from <that message id>`, and keep the discussion in the thread. A thread is used like a channel: pass its id (or name) wherever a <channel> goes.',
         '',
         skillInstalled()
             ? `Claude Code skill: installed (${skillDir()}).`
@@ -351,6 +405,11 @@ 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 },
+                thread: { type: 'string', multiple: true },
+                from: { type: 'string' },
             },
         });
     }

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,12 @@ 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 Discord, don't poll: run \`botyard watch\` with the Monitor tool. It covers every channel and thread unless narrowed (\`botyard watch --help\`), and pushes each new message the moment it is posted, as one line.
+
+For a new topic, post a short opening message, then start a thread from it with \`botyard thread\` and keep the discussion there.
+
 Never print, copy or store the key the CLI keeps; it handles authentication itself.
 `;
 export function installSkill() {

package/dist/watch.js

@@ -0,0 +1,179 @@
+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, channel and thread the key can
+ * read; --server, --channel <server>#<channel> (with its threads) and
+ * --thread <server>#<thread> narrow it, each repeatable. Botyard leaves the
+ * bot's own messages out of the stream unless --include-own.
+ *
+ * It never returns on its own: a dropped stream is reopened, and what was
+ * posted meanwhile is read and printed first -- in every channel and thread a
+ * message has come from during this run, and the ones 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".`);
+    }
+    for (const c of o.threads) {
+        if (c.lastIndexOf('#') <= 0)
+            throw new Error(`--thread '${c}' needs its server: use <server>#<thread>, e.g. --thread "My Server#release plans".`);
+    }
+    const me = await call(o.url, o.key, 'GET', '/me');
+    const query = new URLSearchParams([
+        ...o.servers.map((s) => ['server', s]),
+        ...o.channels.map((c) => ['channel', c]),
+        ...o.threads.map((c) => ['thread', c]),
+        // Botyard leaves the bot's own messages out unless asked.
+        ...(o.includeOwn ? [['own', '1']] : []),
+    ]);
+    // Snowflakes grow with time, across every channel, so "newer than the last
+    // one printed" is a single number comparison.
+    let last = 0n;
+    /** Channels and threads to catch up on after a drop, by id (Discord's ids are unique across servers). */
+    const seen = new Map();
+    /** The channels and threads asked for by name, caught up on even before a message has come from them. */
+    const asked = [...o.channels.map((c) => named(c, false)), ...o.threads.map((c) => named(c, true))];
+    let retry = RETRY_FIRST_MS;
+    const print = (m) => {
+        seen.set(m.channel.id, { server: m.server, channel: m.channel });
+        const id = BigInt(m.id);
+        if (id <= last)
+            return;
+        last = id;
+        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()], seen, print);
+        else {
+            const named = [...o.servers.map((s) => `all of ${s}`), ...o.channels.map((c) => `${c} and its threads`), ...o.threads.map((c) => `thread ${c}`)];
+            const scope = named.length ? named.join(', ') : 'every server, channel and thread this key can read';
+            o.log(`botyard: watching ${scope}. Each new message prints as one line${o.includeOwn ? '' : `; ${me.bot.name}'s own are left out`}.`);
+        }
+        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 ${place(m)}; 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);
+    }
+}
+/** A --channel or --thread as typed, standing in for where its messages were posted until one arrives. */
+function named(ref, thread) {
+    const split = ref.lastIndexOf('#');
+    const server = ref.slice(0, split);
+    const channel = ref.slice(split + 1);
+    return { server: { id: server, name: server }, channel: { id: channel, name: channel, thread, parentId: null, parentName: null } };
+}
+/** Read the channels and threads this run has seen and print what is newer than the last message printed, oldest first. */
+async function catchUp(o, channels, seen, 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`);
+            // A channel asked for by name prints under its real name once one of its messages has come through the stream.
+            missed.push(...page.messages.map((m) => ({ ...m, ...(seen.get(m.channelId) ?? where) })));
+        }
+        catch (e) {
+            o.log(`botyard: could not catch up on ${place(where)} (${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)}  ${place(m)}  ${name}${flags ? ' ' + flags : ''}: ${text}`;
+}
+/** "Server #channel", or "Server #channel › thread" for a thread ("Server › thread" if its channel is unknown). */
+export function place(w) {
+    const c = w.channel;
+    if (!c.thread)
+        return `${w.server.name} #${c.name}`;
+    return `${w.server.name} ${c.parentName ? `#${c.parentName} ` : ''}› ${c.name}`;
+}
+/** 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.3.0",
   "description": "Read and send in Discord through your own bot, hosted by Botyard. Made for AI agents.",
   "type": "module",
   "bin": {