@rcpooley/botyard 0.4.3 → 0.5.1

package/dist/api.js

@@ -10,6 +10,18 @@ export class ApiFailure extends Error {
         this.status = status;
     }
 }
+/**
+ * Who is calling, for Botyard's audit log: --actor or BOTYARD_ACTOR, free text
+ * such as an agent's session id. Sent as a header on every call, when set.
+ */
+let actor = null;
+export function setActor(value) {
+    // It goes into a header and the audit log: printable ASCII, and short.
+    actor = value?.replace(/[^\x20-\x7e]/g, '').trim().slice(0, 100) || null;
+}
+export function headers(key) {
+    return { ...(key ? { authorization: `Bearer ${key}` } : {}), ...(actor ? { 'botyard-actor': actor } : {}), 'user-agent': 'botyard-cli' };
+}
 /** A wait Discord or Botyard asks for that is short enough to just sit out, once. */
 const MAX_RETRY_WAIT_S = 10;
 export async function call(url, key, method, path, body, retried = false) {
@@ -17,11 +29,7 @@ export async function call(url, key, method, path, body, retried = false) {
     try {
         res = await fetch(`${url.replace(/\/+$/, '')}/api/v1${path}`, {
             method,
-            headers: {
-                ...(key ? { authorization: `Bearer ${key}` } : {}),
-                ...(body === undefined ? {} : { 'content-type': 'application/json' }),
-                'user-agent': 'botyard-cli',
-            },
+            headers: { ...headers(key), ...(body === undefined ? {} : { 'content-type': 'application/json' }) },
             body: body === undefined ? undefined : JSON.stringify(body),
             signal: AbortSignal.timeout(30_000),
         });

package/dist/botyard.js

@@ -2,7 +2,7 @@
 import { readFileSync } from 'node:fs';
 import { hostname } from 'node:os';
 import { parseArgs } from 'node:util';
-import { ApiFailure, call, seg } from "./api.js";
+import { ApiFailure, call, seg, setActor } 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";
@@ -16,6 +16,35 @@ import { watch } from "./watch.js";
  * none of them can describe a command the others do not know.
  */
 const VERSION = JSON.parse(readFileSync(new URL('../package.json', import.meta.url), 'utf8')).version;
+/**
+ * What the CLI calls itself in usage lines and hints. A tool that wraps it
+ * (Robert's `quiver discord`) sets BOTYARD_PROG so the commands it suggests
+ * are ones its own users can run.
+ */
+const PROG = process.env.BOTYARD_PROG?.trim() || 'botyard';
+/** Options any command takes. */
+const GLOBAL_OPTIONS = {
+    json: { type: 'boolean', description: 'print the raw API response (one JSON object per line for watch)' },
+    bot: { type: 'string', value: 'name|id', description: 'act as this connected bot instead of the default' },
+    actor: { type: 'string', value: 'id', description: 'who is calling (an agent session id), recorded by Botyard; also BOTYARD_ACTOR' },
+    help: { type: 'boolean', description: 'explain the command' },
+};
+/** Options only some commands take: each command lists its own. */
+const OPTIONS = {
+    url: { type: 'string', value: 'site', description: 'the Botyard site to connect to' },
+    limit: { type: 'string', value: 'n', description: 'how many messages, 1-100 (default 50)' },
+    before: { type: 'string', value: 'message id', description: 'page back from this message' },
+    'reply-to': { type: 'string', value: 'message id', description: 'reply to this message in the same channel' },
+    mentions: { type: 'string', value: 'users|none|all', description: 'who the text may ping (default users; all only when asked)' },
+    'include-own': { type: 'boolean', description: "also print the bot's own messages" },
+    server: { type: 'string', multiple: true, value: 'server', description: 'only this server' },
+    channel: { type: 'string', multiple: true, value: 'server#channel', description: 'only this channel and its threads' },
+    thread: { type: 'string', multiple: true, value: 'server#thread', description: 'only this thread' },
+    since: { type: 'string', value: 'message id', description: 'first print what was posted after this message, then go on' },
+    once: { type: 'boolean', description: 'exit after the first message (or the --since catch-up), saying the --since to pass next' },
+    from: { type: 'string', value: 'message id', description: 'start the thread from this message in the channel' },
+    add: { type: 'string', multiple: true, value: 'user id', description: 'add this person to the thread, without a ping (up to 10)' },
+};
 // --- what a command needs --------------------------------------------------
 /** The bot to act as: BOTYARD_KEY wins (for scripts), then --bot, then the default. */
 function target(opts) {
@@ -29,6 +58,9 @@ async function api(opts, method, path, body) {
     return call(url, key, method, path, body);
 }
 const json = (value) => JSON.stringify(value, null, 2);
+/** A mistake in how the command was typed: exit 2, like a bad option. */
+class UsageError extends Error {
+}
 /** Message text: the words given, or stdin when the text is "-". */
 function text(raw) {
     if (raw !== '-')
@@ -81,6 +113,7 @@ const COMMANDS = [
         summary: 'recent messages, oldest first',
         details: ['--limit is 1-100 (default 50). When there are older messages, the output ends with the command for the next page.'],
         args: 2,
+        options: ['limit', 'before'],
         run: async ([server, channel], opts) => {
             const q = new URLSearchParams();
             if (opts.limit)
@@ -90,37 +123,50 @@ const COMMANDS = [
             const res = await api(opts, 'GET', `${where(server, channel)}/messages${q.size ? `?${q}` : ''}`);
             if (opts.json)
                 return json(res);
-            const more = res.older ? `Older: botyard read ${quote(server)} ${quote(channel)} --before ${res.older}` : null;
+            const more = res.older ? `Older: ${PROG} read ${quote(server)} ${quote(channel)} --before ${res.older}` : null;
             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]',
+        usage: 'watch [--server <server>]... [--channel <server>#<channel>]... [--thread <server>#<thread>]... [--since <message id>] [--once] [--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.',
+            'It runs until stopped. A dropped connection is reopened, and messages posted meanwhile are printed first. Stopped (Ctrl-C, a kill), it says the --since to resume from.',
+            '--since <message id> first prints what was posted after that message, oldest first, in everything it watches (only channels with something new are read), then goes on watching.',
+            '--once exits as soon as it has printed something: the --since catch-up if that found anything, else the next message. Its last line (on stderr) is the --since to pass next time. Run that way as a background command that ends on each event, it costs nothing while the channel is quiet and misses nothing between runs.',
             '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,
+        options: ['server', 'channel', 'thread', 'since', 'once', 'include-own'],
+        streams: true,
         run: async (_a, opts) => {
             const { url, key } = target(opts);
-            return watch({
+            if (opts.since !== undefined && !/^\d{17,20}$/.test(opts.since))
+                throw new UsageError(`--since takes a message id, got '${opts.since}'.`);
+            await watch({
                 url,
                 key,
+                prog: PROG,
                 servers: opts.server ?? [],
                 channels: opts.channel ?? [],
                 threads: opts.thread ?? [],
+                since: opts.since === undefined ? null : BigInt(opts.since),
+                once: opts.once === true,
                 includeOwn: opts['include-own'] === true,
                 json: opts.json,
                 out: (l) => process.stdout.write(l + '\n'),
                 log: (l) => process.stderr.write(l + '\n'),
             });
+            // Only --once gets here. Exit now rather than when every socket the
+            // stream used has been let go, which can take a while. Writes to pipes
+            // and files are synchronous, so nothing printed is lost.
+            process.exit(0);
         },
     },
     {
@@ -171,6 +217,8 @@ const COMMANDS = [
         ],
         args: 3,
         rest: true,
+        options: ['reply-to', 'mentions'],
+        writes: true,
         run: async ([server, channel, words], opts) => {
             const body = { content: text(words), replyTo: opts['reply-to'], mentions: opts.mentions };
             const m = await api(opts, 'POST', `${where(server, channel)}/messages`, body);
@@ -191,6 +239,8 @@ const COMMANDS = [
         ],
         args: 3,
         rest: true,
+        options: ['from', 'add'],
+        writes: true,
         run: async ([server, channel, name], opts) => {
             const thread = await api(opts, 'POST', `${where(server, channel)}/threads`, {
                 name,
@@ -202,7 +252,7 @@ const COMMANDS = [
             return [
                 `Started thread ${thread.id}  ${thread.name}`,
                 ...memberLines(thread.added ?? [], thread.failed ?? []),
-                `Send to it: botyard send ${quote(server)} ${thread.id} "..."`,
+                `Send to it: ${PROG} send ${quote(server)} ${thread.id} "..."`,
             ].join('\n');
         },
     },
@@ -218,6 +268,7 @@ const COMMANDS = [
         ],
         args: 3,
         many: true,
+        writes: true,
         run: async ([server, thread, ...users], opts) => {
             const added = [];
             const failed = [];
@@ -248,6 +299,8 @@ const COMMANDS = [
         summary: "replace the text of one of the bot's own messages",
         args: 4,
         rest: true,
+        options: ['mentions'],
+        writes: true,
         run: async ([server, channel, id, words], opts) => {
             const m = await api(opts, 'PATCH', `${where(server, channel)}/messages/${seg(id)}`, { content: text(words), mentions: opts.mentions });
             return opts.json ? json(m) : `Edited ${m.id}\n${m.url}`;
@@ -259,6 +312,7 @@ const COMMANDS = [
         usage: `${name} <server> <channel> <message id>`,
         summary: name === 'pin' ? 'pin a message' : 'unpin a message',
         args: 3,
+        writes: true,
         run: async ([server, channel, id], opts) => {
             await api(opts, name === 'pin' ? 'PUT' : 'DELETE', `${where(server, channel)}/messages/${seg(id)}/pin`);
             return `${name === 'pin' ? 'Pinned' : 'Unpinned'} ${id}`;
@@ -271,6 +325,7 @@ const COMMANDS = [
         summary: name === 'react' ? 'add a reaction' : "remove the bot's own reaction",
         details: ['The emoji itself (👍), or a custom one as <:name:id>. :shortcodes: are a Discord-app feature and do not work.'],
         args: 4,
+        writes: true,
         run: async ([server, channel, id, emoji], opts) => {
             await api(opts, name === 'react' ? 'PUT' : 'DELETE', `${where(server, channel)}/messages/${seg(id)}/reactions/${seg(emoji)}`);
             return `${name === 'react' ? 'Reacted' : 'Removed'} ${emoji} ${name === 'react' ? 'to' : 'from'} ${id}`;
@@ -286,6 +341,7 @@ const COMMANDS = [
             'The key it is exchanged for is stored for you and never printed.',
         ],
         args: 1,
+        options: ['url'],
         run: async ([code], opts) => {
             const url = (opts.url || DEFAULT_URL).replace(/\/+$/, '');
             const res = await call(url, null, 'POST', '/connect', { code, client: `botyard CLI on ${hostname()}` });
@@ -373,6 +429,7 @@ const COMMANDS = [
         summary: 'install the Claude Code skill that tells future sessions about botyard',
         details: [`install writes ${skillDir()}/SKILL.md (set CLAUDE_CONFIG_DIR to change where). show prints it instead.`],
         args: 1,
+        params: ['action'],
         run: async ([action]) => {
             if (action === 'show')
                 return SKILL;
@@ -381,6 +438,18 @@ const COMMANDS = [
             throw new Error("Use 'botyard skill install' or 'botyard skill show'.");
         },
     },
+    {
+        name: 'commands',
+        group: 'Setup',
+        usage: 'commands',
+        summary: 'every command and option as JSON, for tools that wrap this CLI',
+        details: [
+            'One object: version, the options every command takes, and per command its name, group, usage, summary, details, positional arguments (variadic: any number; rest: the remaining words joined into one), options, and whether it writes to Discord or streams until stopped.',
+            'A wrapper can build its own commands from this and pass them straight through, so it follows new CLI versions without changes.',
+        ],
+        args: 0,
+        run: async () => json(commandTable()),
+    },
 ];
 // --- the guide -------------------------------------------------------------
 function botLines(config) {
@@ -401,7 +470,7 @@ function guide() {
         bots.unshift('  (BOTYARD_KEY is set, so commands use that key instead)');
     // Usage on one line, what it does under it: the usages are too long to share
     // a line with anything and still fit a terminal.
-    const groups = ['Reading', 'Writing', 'Bots', 'Setup'].map((g) => [`${g}:`, ...COMMANDS.filter((c) => c.group === g).map((c) => `  botyard ${c.usage}\n      ${c.summary}`)].join('\n'));
+    const groups = ['Reading', 'Writing', 'Bots', 'Setup'].map((g) => [`${g}:`, ...COMMANDS.filter((c) => c.group === g).map((c) => `  ${PROG} ${c.usage}\n      ${c.summary}`)].join('\n'));
     return [
         `botyard ${VERSION}: read and send in Discord through your own bot, hosted by Botyard.`,
         '',
@@ -409,7 +478,7 @@ function guide() {
         ...bots,
         '',
         ...groups.flatMap((g) => [g, '']),
-        'Options: --bot <name|id> picks a bot, --json prints raw API responses, botyard <command> --help explains one command.',
+        `Options: --bot <name|id> picks a bot, --json prints raw API responses, ${PROG} <command> --help explains one command.`,
         '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:',
@@ -419,9 +488,9 @@ function guide() {
         "- 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.',
-        "- Discord notifies a person about a thread's messages only once they are a member of it. When you start a thread for a human's project, add them: `botyard thread ... --add <their user id>` (or `botyard thread-add <server> <thread> <user id>...` later). Adding does not ping them.",
+        `- To hear about new messages as they arrive, run \`${PROG} 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 \`${PROG} 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.`,
+        `- Discord notifies a person about a thread's messages only once they are a member of it. When you start a thread for a human's project, add them: \`${PROG} thread ... --add <their user id>\` (or \`${PROG} thread-add <server> <thread> <user id>...\` later). Adding does not ping them.`,
         '',
         skillInstalled()
             ? `Claude Code skill: installed (${skillDir()}).`
@@ -429,7 +498,44 @@ function guide() {
     ].join('\n');
 }
 function commandHelp(c) {
-    return [`botyard ${c.usage}`, '', `${c.summary[0].toUpperCase()}${c.summary.slice(1)}.`, ...(c.details ? ['', ...c.details] : [])].join('\n');
+    const options = (c.options ?? []).map((n) => `  --${n}${OPTIONS[n].value ? ` <${OPTIONS[n].value}>` : ''}${OPTIONS[n].multiple ? ' (repeatable)' : ''}: ${OPTIONS[n].description}`);
+    return [
+        `${PROG} ${c.usage}`,
+        '',
+        `${c.summary[0].toUpperCase()}${c.summary.slice(1)}.`,
+        ...(c.details ? ['', ...c.details] : []),
+        ...(options.length ? ['', 'Options:', ...options] : []),
+    ].join('\n');
+}
+/**
+ * A command's positional arguments, named from its usage line: the <...> words
+ * before the first option. `<message id>` is message-id; `<text | ->` is text.
+ */
+function positionals(c) {
+    const words = [...c.usage.split(' [')[0].matchAll(/<([^>]+)>(\.\.\.)?/g)].slice(0, c.args);
+    return words.map((w, i) => ({
+        name: c.params?.[i] ?? w[1].split('|')[0].trim().replace(/\s+/g, '-'),
+        variadic: (c.many === true && i === c.args - 1) || w[2] === '...',
+        rest: c.rest === true && i === c.args - 1,
+    }));
+}
+function commandTable() {
+    const option = ([name, o]) => ({ name, type: o.type, multiple: o.multiple === true, ...(o.value ? { value: o.value } : {}), description: o.description });
+    return {
+        version: VERSION,
+        globalOptions: Object.entries(GLOBAL_OPTIONS).map(option),
+        commands: COMMANDS.map((c) => ({
+            name: c.name,
+            group: c.group,
+            usage: c.usage,
+            summary: c.summary,
+            details: c.details ?? [],
+            positionals: positionals(c),
+            options: (c.options ?? []).map((n) => option([n, OPTIONS[n]])),
+            writes: c.writes === true,
+            streams: c.streams === true,
+        })),
+    };
 }
 /** Who a thread's members call added, and who Discord refused. */
 function memberLines(added, failed) {
@@ -447,29 +553,19 @@ async function main(argv) {
             allowPositionals: true,
             strict: true,
             options: {
-                json: { type: 'boolean', default: false },
-                help: { type: 'boolean', short: 'h', default: false },
-                version: { type: 'boolean', short: 'v', default: false },
-                bot: { type: 'string' },
-                url: { type: 'string' },
-                limit: { type: 'string' },
-                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' },
-                add: { type: 'string', multiple: true },
+                ...Object.fromEntries(Object.entries({ ...GLOBAL_OPTIONS, ...OPTIONS }).map(([n, o]) => [n, { type: o.type, ...(o.multiple ? { multiple: true } : {}) }])),
+                help: { type: 'boolean', short: 'h' },
+                version: { type: 'boolean', short: 'v' },
             },
         });
     }
     catch (e) {
-        process.stderr.write(`botyard: ${e instanceof Error ? e.message : String(e)}. Run botyard for usage.\n`);
+        process.stderr.write(`botyard: ${e instanceof Error ? e.message : String(e)}. Run ${PROG} for usage.\n`);
         return 2;
     }
-    const { values, positionals } = parsed;
+    const values = { ...parsed.values, json: parsed.values.json === true };
+    const { positionals } = parsed;
+    setActor(values.actor ?? process.env.BOTYARD_ACTOR);
     if (values.version) {
         process.stdout.write(`${VERSION}\n`);
         return 0;
@@ -485,16 +581,21 @@ async function main(argv) {
             process.stdout.write(guide() + '\n');
             return 0;
         }
-        process.stderr.write(`botyard: no command '${name}'. Run botyard with no arguments for the list.\n`);
+        process.stderr.write(`botyard: no command '${name}'. Run ${PROG} with no arguments for the list.\n`);
         return 2;
     }
     if (values.help) {
         process.stdout.write(commandHelp(command) + '\n');
         return 0;
     }
+    const stray = Object.keys(values).filter((n) => n in OPTIONS && !(command.options ?? []).includes(n));
+    if (stray.length) {
+        process.stderr.write(`botyard: ${command.name} takes no --${stray[0]}. ${PROG} ${command.name} --help lists what it takes.\n`);
+        return 2;
+    }
     const given = command.many ? args : command.rest && args.length > command.args ? [...args.slice(0, command.args - 1), args.slice(command.args - 1).join(' ')] : args;
     if (command.many ? given.length < command.args : given.length !== command.args) {
-        process.stderr.write(`botyard: usage: botyard ${command.usage}\n`);
+        process.stderr.write(`botyard: usage: ${PROG} ${command.usage}\n`);
         return 2;
     }
     try {
@@ -506,6 +607,8 @@ async function main(argv) {
     catch (e) {
         const message = e instanceof Error ? e.message : String(e);
         process.stderr.write(`botyard: ${message}\n`);
+        if (e instanceof UsageError)
+            return 2;
         return e instanceof ApiFailure && e.status === 0 ? 3 : 1;
     }
 }

package/dist/format.js

@@ -12,7 +12,7 @@ function pad(s, n) {
 export function me(m) {
     const servers = m.servers.length ? m.servers.map((s) => `  ${s.id}  ${s.name}`).join('\n') : '  (none)';
     return [
-        `Bot:      ${m.bot.name} (${m.bot.id}), ${m.bot.status}`,
+        `Bot:      ${m.bot.name} (${m.bot.id}), ${m.bot.status}${m.bot.transport === 'rest' ? ' (over REST while its gateway is down; watch lags a few seconds)' : ''}`,
         `Key:      ${m.token.name} (${m.token.keyId})`,
         `Can:      ${m.token.scopes.join(', ')}`,
         `Servers:  ${m.token.allServers ? 'all of the bot\'s servers, now and later' : 'only these'}`,

package/dist/watch.js

@@ -1,4 +1,4 @@
-import { ApiFailure, call, seg, warnOnce, warnText } from "./api.js";
+import { ApiFailure, call, headers, 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
@@ -9,12 +9,18 @@ import { ApiFailure, call, seg, warnOnce, warnText } from "./api.js";
  * 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.
+ * posted meanwhile is read and printed first. Only a refusal (a revoked key, a
+ * server it may not read) ends it -- or --once, after the first thing it
+ * prints. --since <id> starts with a catch-up from that message, so a watch
+ * run once per event (a background command that ends on each one) misses
+ * nothing between runs.
  */
 const RETRY_FIRST_MS = 1_000;
 const RETRY_MAX_MS = 30_000;
+/** How many printed ids to remember, so the stream's copy of a message already caught up on is dropped. */
+const REMEMBER = 2_000;
+/** One page of messages: what a catch-up reads per channel. */
+const PAGE = 100;
 export async function watch(o) {
     for (const c of o.channels) {
         if (c.lastIndexOf('#') <= 0)
@@ -25,6 +31,7 @@ export async function watch(o) {
             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 own = o.includeOwn ? null : me.bot.userId || me.bot.id;
     const query = new URLSearchParams([
         ...o.servers.map((s) => ['server', s]),
         ...o.channels.map((c) => ['channel', c]),
@@ -32,22 +39,42 @@ export async function watch(o) {
         // 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). */
+    /** The newest message printed: the --since to resume from. */
+    let last = o.since ?? 0n;
+    /**
+     * The newest message printed in each channel, where a catch-up there starts.
+     * Per channel, not one number, because messages from different channels can
+     * arrive slightly out of order, and a lower id is still a new message.
+     */
+    const marks = new Map();
+    /** Recently printed ids: a message is printed once however many ways it arrives. */
+    const printed = new Set();
+    /** Channels and threads a message has come from during this run, to catch up on after a drop. */
     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;
+    let opened = false;
+    let caughtUp = false;
     const print = (m) => {
         seen.set(m.channel.id, { server: m.server, channel: m.channel });
+        if (printed.has(m.id))
+            return false;
+        printed.add(m.id);
+        if (printed.size > REMEMBER)
+            printed.delete(printed.values().next().value);
         const id = BigInt(m.id);
-        if (id <= last)
-            return;
-        last = id;
+        if (id > last)
+            last = id;
+        if (id > (marks.get(m.channel.id) ?? 0n))
+            marks.set(m.channel.id, id);
         o.out(o.json ? JSON.stringify(m) : line(m));
+        return true;
     };
+    const stopped = () => {
+        o.log(`botyard: stopped.${last > 0n ? ` Resume with --since ${last}` : ''}`);
+        process.exit(0);
+    };
+    process.once('SIGINT', stopped);
+    process.once('SIGTERM', stopped);
     const backoff = async (why) => {
         o.log(`botyard: ${why}; retrying in ${retry / 1000}s`);
         await sleep(retry);
@@ -57,7 +84,7 @@ export async function watch(o) {
         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' },
+                headers: { ...headers(o.key), accept: 'text/event-stream' },
             });
         }
         catch (e) {
@@ -73,24 +100,36 @@ export async function watch(o) {
             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, o.includeOwn ? null : me.bot.userId || me.bot.id);
-        else {
+        if (!opened) {
+            opened = true;
             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`}.`);
         }
+        // The stream is open, so nothing new can slip past it. Before reading it,
+        // catch up on what was posted before: since --since, or while it was down.
+        // The stream's own copy of any of those is dropped by print().
+        if (last > 0n) {
+            const caught = await catchUp(o, me, { seen, marks, last, own }, print);
+            if (o.since !== null && !caughtUp && caught >= 0)
+                o.log(`botyard: ${caught} message${caught === 1 ? '' : 's'} since ${o.since}.`);
+            caughtUp = true;
+            if (o.once && caught > 0) {
+                // The stream is open but unread: close it, or its socket keeps the process alive.
+                await res.body.cancel().catch(() => { });
+                return next(o, last);
+            }
+        }
         retry = RETRY_FIRST_MS;
         try {
             for await (const event of events(res.body)) {
-                if (event.name === 'message')
-                    print(JSON.parse(event.data));
+                if (event.name === 'message') {
+                    if (print(JSON.parse(event.data)) && o.once)
+                        return next(o, last);
+                }
                 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`);
+                    o.log(`botyard: missed message ${m.id} in ${place(m)}; read it with ${o.prog} message ${m.server.id} ${m.channel.id} ${m.id}`);
                 }
                 else if (event.name === 'warning')
                     warnText(JSON.parse(event.data).warning);
@@ -107,30 +146,102 @@ export async function watch(o) {
         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 } };
+/** --once is done: say where the next run starts. */
+function next(o, last) {
+    o.log(`botyard: next: --since ${last}`);
 }
-/** Read the channels and threads this run has seen and print what is newer than the last message printed, oldest first. */
-// `own` is the bot's user id when its own messages are to be left out: the
-// stream drops them server-side, but catch-up reads history, which has them.
-async function catchUp(o, channels, seen, print, own) {
+/**
+ * Read what was posted after each channel's mark, in everything the watch
+ * covers, and print it oldest first. Returns how many it printed, or -1 if it
+ * could read nothing at all.
+ *
+ * The channel lists say each channel's newest message, so only channels with
+ * something new are read: a --channel catches up on its threads too, and a
+ * --server or an unfiltered watch on every channel, for one list call per
+ * server. Against a Botyard too old to say, every channel is read.
+ */
+async function catchUp(o, me, state, print) {
+    const lists = new Map();
+    const list = (server) => {
+        if (!lists.has(server))
+            lists.set(server, call(o.url, o.key, 'GET', `/servers/${seg(server)}/channels`).catch(() => null));
+        return lists.get(server);
+    };
+    const serverOf = (ref) => me.servers.find((s) => s.id === ref) ?? me.servers.find((s) => s.name.toLowerCase() === ref.toLowerCase()) ?? { id: ref, name: ref };
+    const markOf = (id) => state.marks.get(id) ?? state.last;
+    const targets = new Map();
+    const add = (where, named, lastMessageId) => {
+        if (!targets.has(where.channel.id) || named)
+            targets.set(where.channel.id, { where, named, mark: markOf(where.channel.id), lastMessageId });
+    };
+    const whereIn = (server, c, all) => {
+        const thread = c.kind === 'thread';
+        return {
+            server,
+            channel: { id: c.id, name: c.name, thread, parentId: thread ? c.parentId : null, parentName: thread ? (all.find((p) => p.id === c.parentId)?.name ?? null) : null },
+        };
+    };
+    const readable = (c) => (c.lastMessageId !== undefined ? c.lastMessageId !== null : ['text', 'announcement', 'thread'].includes(c.kind));
+    const everything = o.servers.length + o.channels.length + o.threads.length === 0;
+    for (const ref of everything ? me.servers.map((s) => s.id) : o.servers) {
+        const server = serverOf(ref);
+        const all = await list(server.id);
+        for (const c of (all ?? []).filter(readable))
+            add(whereIn(server, c, all), false, c.lastMessageId);
+    }
+    for (const ref of o.channels) {
+        const split = ref.lastIndexOf('#');
+        const server = serverOf(ref.slice(0, split));
+        const wanted = ref.slice(split + 1).replace(/^#/, '');
+        const all = await list(server.id);
+        const channel = all?.find((c) => c.id === wanted) ?? all?.find((c) => c.name === wanted && c.kind !== 'voice' && c.kind !== 'thread');
+        if (!channel || !all) {
+            add(named(ref, false), true);
+            continue;
+        }
+        add(whereIn(server, channel, all), true, channel.lastMessageId);
+        for (const t of all.filter((c) => c.kind === 'thread' && c.parentId === channel.id))
+            add(whereIn(server, t, all), false, t.lastMessageId);
+    }
+    for (const ref of o.threads)
+        add(named(ref, true), true);
+    // After a drop, everything this run has heard from, wherever it was.
+    for (const where of state.seen.values())
+        add(where, false);
     const missed = [];
-    for (const where of channels) {
+    let read = 0;
+    let failed = 0;
+    for (const { where, named: wasNamed, mark, lastMessageId } of targets.values()) {
+        // Nothing newer than what was printed: no need to read it.
+        if (lastMessageId && BigInt(lastMessageId) <= mark)
+            continue;
         try {
-            const page = await call(o.url, o.key, 'GET', `/servers/${seg(where.server.id)}/channels/${seg(where.channel.id)}/messages?limit=100`);
+            const page = await call(o.url, o.key, 'GET', `/servers/${seg(where.server.id)}/channels/${seg(where.channel.id)}/messages?limit=${PAGE}`);
+            read++;
+            const newer = page.messages.filter((m) => BigInt(m.id) > mark);
+            if (newer.length === PAGE) {
+                o.log(`botyard: more than ${PAGE} new messages in ${place(where)}; the latest ${PAGE} follow. Older: ${o.prog} read ${where.server.id} ${where.channel.id} --before ${newer[0].id}`);
+            }
             // 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.filter((m) => m.author.id !== own).map((m) => ({ ...m, ...(seen.get(m.channelId) ?? where) })));
+            missed.push(...newer.filter((m) => m.author.id !== state.own).map((m) => ({ ...m, ...(state.seen.get(m.channelId) ?? where) })));
         }
         catch (e) {
-            o.log(`botyard: could not catch up on ${place(where)} (${e instanceof Error ? e.message : e})`);
+            failed++;
+            // A channel the bot can't read, found by listing, is not worth a line every run.
+            if (wasNamed)
+                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);
+    if (read === 0 && failed > 0)
+        return -1;
+    return missed.sort((a, b) => (BigInt(a.id) < BigInt(b.id) ? -1 : 1)).filter(print).length;
+}
+/** 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 } };
 }
 /** One message on one line: newlines in the text become ⏎, so each line is exactly one message. */
 export function line(m) {

package/package.json

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