hive-am 1.5.0 → 1.6.0

package/server/dist/connections/slack.js

@@ -0,0 +1,488 @@
+import { readFileSync, writeFileSync } from 'node:fs';
+import WebSocket from 'ws';
+import { MAX_FILE_BYTES } from './files.js';
+import { mdToSlackMrkdwn, splitMessage } from './format.js';
+import { threads } from './store.js';
+const MAX_PART = 3500; // Slack takes far more, but long messages are cut in the timeline: keep each part readable
+const MIN_GAP_MS = 1000; // Slack allows about one message per second per channel
+const CALL_TIMEOUT_MS = Number(process.env.HIVE_AM_SLACK_TIMEOUT_MS) || 30_000;
+const UPLOAD_TIMEOUT_MS = 120_000;
+const DOWNLOAD_TIMEOUT_MS = 60_000;
+const HELLO_TIMEOUT_MS = 15_000; // a socket that does not say hello in this long is not going to
+const PING_EVERY_MS = 30_000; // a half-open socket never errors by itself: ping it, and drop it when it does not answer
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+const within = (ms, signal) => (signal ? AbortSignal.any([signal, AbortSignal.timeout(ms)]) : AbortSignal.timeout(ms));
+const timedOut = (e) => e instanceof Error && e.name === 'TimeoutError';
+/**
+ * The emoji the agent may react with on Slack, and the name Slack knows each one by (`reactions.add` takes names, not characters).
+ * Slack accepts any standard emoji; this list is the useful ones, without the rude.
+ */
+export const SLACK_REACTION_NAMES = {
+    '👍': '+1', '👎': '-1', '❤': 'heart', '🔥': 'fire', '👏': 'clap', '😁': 'grin', '😂': 'joy', '🤣': 'rolling_on_the_floor_laughing', '😅': 'sweat_smile',
+    '🤔': 'thinking_face', '🤯': 'exploding_head', '😱': 'scream', '😢': 'cry', '😭': 'sob', '🎉': 'tada', '🤩': 'star-struck', '🙏': 'pray', '👌': 'ok_hand',
+    '😍': 'heart_eyes', '💯': '100', '⚡': 'zap', '🏆': 'trophy', '💔': 'broken_heart', '😐': 'neutral_face', '😴': 'sleeping', '👀': 'eyes', '🙈': 'see_no_evil',
+    '😇': 'innocent', '🤝': 'handshake', '✍': 'writing_hand', '🤗': 'hugging_face', '🫡': 'saluting_face', '😎': 'sunglasses', '🤷': 'shrug', '🤓': 'nerd_face',
+    '✅': 'white_check_mark', '☑': 'ballot_box_with_check', '✔': 'heavy_check_mark', '❌': 'x', '⚠': 'warning', '🚀': 'rocket', '👋': 'wave', '🙌': 'raised_hands',
+    '💪': 'muscle', '⏳': 'hourglass_flowing_sand', '🐛': 'bug', '📌': 'pushpin', '⭐': 'star', '🙂': 'slightly_smiling_face', '😊': 'blush', '😉': 'wink', '🆗': 'ok',
+    '➕': 'heavy_plus_sign', '🧐': 'face_with_monocle', '💡': 'bulb', '📝': 'memo', '🔍': 'mag', '🛠': 'hammer_and_wrench', '🥳': 'partying_face', '😬': 'grimacing',
+    // The rest of Telegram's list, so an agent that learnt that list is never refused on Slack.
+    '🥰': 'smiling_face_with_3_hearts', '🕊': 'dove_of_peace', '🤡': 'clown_face', '🥱': 'yawning_face', '🥴': 'woozy_face', '🐳': 'whale', '❤‍🔥': 'heart_on_fire',
+    '🌚': 'new_moon_with_face', '🌭': 'hotdog', '🍌': 'banana', '🤨': 'face_with_raised_eyebrow', '🍓': 'strawberry', '🍾': 'champagne', '💋': 'kiss', '😈': 'smiling_imp',
+    '👻': 'ghost', '👨‍💻': 'male-technologist', '🎃': 'jack_o_lantern', '😨': 'fearful', '🎅': 'santa', '🎄': 'christmas_tree', '☃': 'snowman', '💅': 'nail_care',
+    '🤪': 'zany_face', '🗿': 'moyai', '🆒': 'cool', '💘': 'cupid', '🙉': 'hear_no_evil', '🦄': 'unicorn_face', '😘': 'kissing_heart', '💊': 'pill', '🙊': 'speak_no_evil',
+    '👾': 'space_invader', '🤷‍♂': 'man-shrugging', '🤷‍♀': 'woman-shrugging',
+};
+export const SLACK_REACTIONS = Object.keys(SLACK_REACTION_NAMES);
+const NAME_OF = new Map(Object.entries(SLACK_REACTION_NAMES).map(([e, n]) => [e.replace(/️/g, ''), n]));
+const KNOWN_NAMES = new Set([...Object.values(SLACK_REACTION_NAMES), 'thumbsup', 'thumbsdown']);
+/** The commands hive-am understands (router.ts). On Slack they may come as their own slash command, as `/hive-status`, or as `/hive status`. */
+const COMMANDS = new Set(['new', 'clear', 'reset', 'stop', 'status', 'mute', 'unmute', 'help', 'id']);
+export function slashToCommand(command, text) {
+    const name = command.replace(/^\//, '').toLowerCase(), args = text.trim();
+    if (COMMANDS.has(name))
+        return { name, args };
+    const suffix = /[-_](\w+)$/.exec(name)?.[1];
+    if (suffix && COMMANDS.has(suffix))
+        return { name: suffix, args };
+    const [first = 'help', ...rest] = args ? args.split(/\s+/) : [];
+    return { name: first.replace(/^\//, '').toLowerCase(), args: rest.join(' ') };
+}
+class SlackError extends Error {
+    code;
+    method;
+    retryAfter;
+    constructor(msg, code, method, retryAfter) {
+        super(msg);
+        this.code = code;
+        this.method = method;
+        this.retryAfter = retryAfter;
+    }
+}
+const AUTH_ERRORS = new Set(['invalid_auth', 'not_authed', 'account_inactive', 'token_revoked', 'token_expired']);
+/** What a Slack API error means to the person setting up the connection. */
+function readable(e, method = e.method) {
+    if (AUTH_ERRORS.has(e.code))
+        return method === 'apps.connections.open' ? 'Invalid app token' : 'Invalid bot token';
+    if (e.code === 'not_allowed_token_type')
+        return method === 'apps.connections.open' ? 'The app token must be an app-level token (xapp-…) with connections:write' : 'The bot token must be a bot token (xoxb-…)';
+    if (e.code === 'missing_scope')
+        return `The Slack app lacks a permission for ${method}: add the scopes from the manual and reinstall it`;
+    if (e.code === 'not_in_channel')
+        return 'The app is not in this channel: invite it with /invite @your-app';
+    if (e.code === 'channel_not_found')
+        return 'Slack does not know this channel (or the app cannot see it)';
+    return e.message;
+}
+/** The files of a Slack message (they come in the event itself, so there is nothing to assemble). The download URL is the attachment's id. */
+function attachmentsOf(ev) {
+    const out = [];
+    for (const f of (Array.isArray(ev.files) ? ev.files : [])) {
+        const url = f.url_private_download ?? f.url_private;
+        if (!url || f.mode === 'tombstone' || f.file_access === 'check_file_info')
+            continue;
+        const mime = String(f.mimetype ?? '');
+        const kind = f.subtype === 'slack_audio' ? 'voice' : mime.startsWith('image/') ? 'image' : mime.startsWith('audio/') ? 'audio' : mime.startsWith('video/') ? 'video' : 'document';
+        out.push({ id: url, name: f.name ?? f.title ?? `file-${f.id}`, kind, mime: mime || undefined, size: f.size });
+    }
+    return out;
+}
+/** Slack Web API over plain `fetch` and Socket Mode over a WebSocket: events come through a socket this machine opens, so no public URL is needed. */
+export class SlackAdapter {
+    conn;
+    kind = 'slack';
+    state = { state: 'connecting' };
+    me = null;
+    stopped = false;
+    abort = new AbortController();
+    ws = null;
+    reconnecting = false;
+    pinger;
+    alive = true;
+    onMessage = null;
+    order = Promise.resolve(); // events are parsed one after another, so they reach the router in the order they came
+    lastSend = new Map();
+    names = new Map(); // user id → display name
+    places = new Map(); // channel id → `#name`
+    constructor(conn) {
+        this.conn = conn;
+    }
+    get base() { return (this.conn.config.api_base || 'https://slack.com/api').replace(/\/$/, ''); }
+    /** One Web API call, form-encoded (every method takes it; objects go as JSON, as Slack expects). */
+    async api(method, params = {}, token = this.conn.config.bot_token) {
+        const body = new URLSearchParams();
+        for (const [k, v] of Object.entries(params))
+            if (v !== undefined && v !== null)
+                body.set(k, typeof v === 'object' ? JSON.stringify(v) : String(v));
+        let res;
+        try {
+            res = await fetch(`${this.base}/${method}`, { method: 'POST', headers: { authorization: `Bearer ${token}`, 'content-type': 'application/x-www-form-urlencoded' }, body, signal: within(CALL_TIMEOUT_MS, this.abort.signal) });
+        }
+        catch (e) {
+            throw timedOut(e) ? new SlackError(`Slack ${method} did not answer in time`, 'timeout', method) : e;
+        }
+        if (res.status === 429)
+            throw new SlackError(`Slack ${method} is rate limited`, 'ratelimited', method, Number(res.headers.get('retry-after')) || 1);
+        const j = await res.json().catch(() => ({}));
+        if (!j.ok)
+            throw new SlackError(j.error ? `Slack ${method}: ${j.error}` : `Slack ${method} failed (${res.status})`, j.error ?? String(res.status), method);
+        return j;
+    }
+    async start(onMessage) {
+        this.stopped = false;
+        this.abort = new AbortController();
+        this.onMessage = onMessage;
+        clearInterval(this.pinger);
+        this.pinger = setInterval(() => {
+            const ws = this.ws;
+            if (!ws || ws.readyState !== WebSocket.OPEN)
+                return;
+            if (!this.alive) {
+                ws.terminate();
+                return;
+            } // `close` follows and reconnects
+            this.alive = false;
+            ws.ping();
+        }, PING_EVERY_MS);
+        this.pinger.unref?.();
+        try {
+            this.me = await this.api('auth.test');
+            await this.connect();
+        }
+        catch (e) {
+            this.state = { state: 'error', detail: e instanceof SlackError ? readable(e) : e.message };
+            if (!(e instanceof SlackError && AUTH_ERRORS.has(e.code)))
+                this.reconnect(); // a network problem at start: keep trying, like Telegram's polling does
+            throw new Error(this.state.detail);
+        }
+    }
+    async stop() {
+        this.stopped = true;
+        this.abort.abort();
+        clearInterval(this.pinger);
+        const ws = this.ws;
+        this.ws = null;
+        ws?.terminate();
+        this.onMessage = null;
+        this.state = { state: 'stopped' };
+    }
+    status() { return this.state; }
+    connected() { return { state: 'connected', detail: `@${this.me?.user} · ${this.me?.team}`, lastEventAt: this.state.lastEventAt }; }
+    /** Opens a socket (`apps.connections.open` gives its URL) and resolves on Slack's `hello`. The previous socket, if any, is closed only then, so a refresh loses nothing. */
+    async connect() {
+        const { url } = await this.api('apps.connections.open', {}, this.conn.config.app_token);
+        if (this.stopped)
+            return;
+        const ws = new WebSocket(url);
+        await new Promise((resolve, reject) => {
+            let hello = false;
+            const timer = setTimeout(() => { ws.terminate(); reject(new Error('Slack did not open the socket in time')); }, HELLO_TIMEOUT_MS);
+            ws.on('message', (data) => {
+                let f;
+                try {
+                    f = JSON.parse(String(data));
+                }
+                catch {
+                    return;
+                }
+                if (f.type === 'hello') {
+                    hello = true;
+                    clearTimeout(timer);
+                    const old = this.ws;
+                    this.ws = ws;
+                    this.alive = true;
+                    this.state = this.connected();
+                    if (old && old !== ws)
+                        old.close();
+                    resolve();
+                    return;
+                }
+                this.frame(ws, f);
+            });
+            ws.on('pong', () => { this.alive = true; });
+            ws.on('error', (e) => { if (!hello) {
+                clearTimeout(timer);
+                reject(e);
+            }
+            else
+                console.warn(`[slack] ${this.conn.name}: socket error: ${e.message}`); });
+            ws.on('close', () => {
+                if (!hello) {
+                    clearTimeout(timer);
+                    reject(new Error('Slack closed the socket before it opened'));
+                    return;
+                }
+                if (this.ws === ws) {
+                    this.ws = null;
+                    this.reconnect();
+                } // a socket replaced by a newer one closes quietly
+            });
+        });
+        if (this.stopped)
+            ws.terminate();
+    }
+    /** Opens a new socket, waiting longer after each failure. A rejected token stops it: retrying will not fix that. */
+    reconnect() {
+        if (this.stopped || this.reconnecting)
+            return;
+        this.reconnecting = true;
+        void (async () => {
+            let wait = 1000;
+            while (!this.stopped) {
+                try {
+                    if (!this.me)
+                        this.me = await this.api('auth.test');
+                    await this.connect();
+                    break;
+                }
+                catch (e) {
+                    if (this.stopped)
+                        break;
+                    this.state = { state: 'error', detail: e instanceof SlackError ? readable(e) : e.message };
+                    if (e instanceof SlackError && AUTH_ERRORS.has(e.code))
+                        break;
+                    await sleep(e instanceof SlackError && e.retryAfter ? e.retryAfter * 1000 : wait);
+                    wait = Math.min(wait * 2, 30_000);
+                }
+            }
+            this.reconnecting = false;
+        })();
+    }
+    /** One frame of the socket. Acknowledged first, so a slow turn never makes Slack send it again. */
+    frame(ws, f) {
+        if (f.envelope_id)
+            ws.send(JSON.stringify({ envelope_id: f.envelope_id }));
+        if (f.type === 'disconnect') {
+            if (this.ws === ws)
+                this.reconnect();
+            return;
+        } // Slack refreshes the socket every few hours
+        const parsed = f.type === 'events_api' ? () => this.parseEvent(f.payload?.event) : f.type === 'slash_commands' ? () => this.parseCommand(f.payload) : null;
+        if (!parsed)
+            return;
+        this.order = this.order.then(async () => {
+            const m = await parsed();
+            if (!m || !this.onMessage)
+                return;
+            this.state = { ...this.state, lastEventAt: Date.now() };
+            void this.onMessage(m).catch((e) => console.error('[slack] handler failed:', e));
+        }).catch((e) => console.error(`[slack] ${this.conn.name}: could not read an event:`, e));
+    }
+    async userName(id) {
+        if (!id)
+            return '';
+        const known = this.names.get(id);
+        if (known)
+            return known;
+        try {
+            const { user } = await this.api('users.info', { user: id });
+            const name = user?.profile?.display_name || user?.real_name || user?.name || id;
+            this.names.set(id, name);
+            return name;
+        }
+        catch {
+            return id;
+        }
+    }
+    async placeOf(channel, type) {
+        if (type === 'im')
+            return 'DM';
+        const known = this.places.get(channel);
+        if (known)
+            return known;
+        let place = type === 'mpim' ? 'group DM' : `#${channel}`;
+        try {
+            const { channel: c } = await this.api('conversations.info', { channel });
+            if (c?.name && type !== 'mpim')
+                place = `#${c.name}`;
+        }
+        catch { /* without channels:read the id has to do */ }
+        this.places.set(channel, place);
+        return place;
+    }
+    /** Slack's markup the agent should read as plain text: `<@U1>` → `@name`, `<#C1|deploys>` → `#deploys`, `<url|label>` → `label (url)`. */
+    async plain(text) {
+        const ids = [...new Set([...text.matchAll(/<@([UW][A-Z0-9]+)(?:\|[^>]*)?>/g)].map((x) => x[1]))];
+        const named = new Map(await Promise.all(ids.map(async (id) => [id, await this.userName(id)])));
+        return text
+            .replace(/<@([UW][A-Z0-9]+)(?:\|[^>]*)?>/g, (_m, id) => `@${named.get(id) ?? id}`)
+            .replace(/<#[CG][A-Z0-9]+\|([^>]*)>/g, '#$1').replace(/<#([CG][A-Z0-9]+)>/g, '#$1')
+            .replace(/<!(here|channel|everyone)(?:\|[^>]*)?>/g, '@$1').replace(/<!subteam\^[A-Z0-9]+\|([^>]*)>/g, '$1')
+            .replace(/<((?:https?|mailto):[^|>]+)\|([^>]+)>/g, '$2 ($1)').replace(/<((?:https?|mailto):[^>]+)>/g, '$1')
+            .replace(/&lt;/g, '<').replace(/&gt;/g, '>').replace(/&amp;/g, '&');
+    }
+    /** A Slack message event → what the router understands; null when it is not for us. */
+    async parseEvent(ev) {
+        if (!ev || !this.me || (ev.type !== 'message' && ev.type !== 'app_mention'))
+            return null;
+        if (ev.bot_id || ev.user === this.me.user_id || !ev.user || ev.hidden)
+            return null;
+        if (ev.subtype && ev.subtype !== 'file_share' && ev.subtype !== 'thread_broadcast')
+            return null; // edits, deletions, joins…
+        const channel = String(ev.channel ?? '');
+        const type = ev.channel_type ?? (channel.startsWith('D') ? 'im' : 'channel');
+        const dm = type === 'im';
+        const raw = ev.text ?? '';
+        const self = new RegExp(`<@${this.me.user_id}(?:\\|[^>]*)?>`, 'g');
+        const mentioned = ev.type === 'app_mention' || self.test(raw);
+        const attachments = attachmentsOf(ev);
+        const text = (await this.plain(raw.replace(self, ''))).trim();
+        if (!text && !attachments.length)
+            return null;
+        // One conversation is one Slack thread: a message in the timeline is the root of its own thread.
+        const root = String(ev.thread_ts ?? ev.ts);
+        const key = dm ? channel : `${channel}:${root}`;
+        const inThread = !!ev.thread_ts && ev.thread_ts !== ev.ts;
+        const cmd = /^\/(\w+)(?:\s+([\s\S]*))?$/.exec(text);
+        const ownThread = inThread && (ev.parent_user_id === this.me.user_id || threads.answered(this.conn.id, key));
+        const addressed = dm || mentioned || !!cmd || ownThread;
+        // Meant for another person of the channel: an @mention of somebody else (and not of the agent).
+        let directedAt;
+        if (!dm && !mentioned) {
+            const other = [...raw.matchAll(/<@([UW][A-Z0-9]+)(?:\|[^>]*)?>/g)].map((x) => x[1]).find((id) => id !== ev.user && id !== this.me.user_id);
+            if (other)
+                directedAt = await this.userName(other);
+        }
+        return {
+            externalId: String(ev.ts),
+            externalKey: key,
+            userId: String(ev.user),
+            userName: await this.userName(String(ev.user)),
+            text,
+            target: dm ? { chat: channel } : { chat: channel, thread: root },
+            place: await this.placeOf(channel, type),
+            command: cmd ? { name: cmd[1].toLowerCase(), args: (cmd[2] ?? '').trim() } : undefined,
+            group: !dm,
+            addressed,
+            ...(directedAt ? { directedAt } : {}),
+            ...(attachments.length ? { attachments } : {}),
+        };
+    }
+    /** A slash command. Slack sends no thread with it, so the answer goes to the channel (or the DM) it was typed in. */
+    async parseCommand(p) {
+        if (!p?.command || !p.channel_id || !p.user_id)
+            return null;
+        const channel = String(p.channel_id), dm = channel.startsWith('D');
+        const type = dm ? 'im' : p.channel_name === 'mpdm' || String(p.channel_name ?? '').startsWith('mpdm-') ? 'mpim' : 'channel';
+        const command = slashToCommand(String(p.command), String(p.text ?? ''));
+        return {
+            externalId: `cmd-${p.trigger_id ?? Date.now()}`,
+            externalKey: channel,
+            userId: String(p.user_id),
+            userName: await this.userName(String(p.user_id)),
+            text: `/${command.name}${command.args ? ` ${command.args}` : ''}`,
+            target: { chat: channel },
+            place: dm ? 'DM' : p.channel_name && p.channel_name !== 'privategroup' && type === 'channel' ? `#${p.channel_name}` : await this.placeOf(channel, type),
+            command,
+            group: !dm,
+            addressed: true,
+        };
+    }
+    /** Keeps one channel's messages spaced out and honours Slack's `Retry-After` when it pushes back. */
+    async withGap(chat, fn) {
+        for (let attempt = 0;; attempt++) {
+            const gap = MIN_GAP_MS - (Date.now() - (this.lastSend.get(chat) ?? 0));
+            if (gap > 0)
+                await sleep(gap);
+            this.lastSend.set(chat, Date.now());
+            try {
+                return await fn();
+            }
+            catch (e) {
+                if (e instanceof SlackError && e.code === 'ratelimited' && attempt < 3) {
+                    await sleep(Math.min(e.retryAfter ?? 1, 30) * 1000);
+                    continue;
+                }
+                throw e instanceof SlackError ? new Error(readable(e)) : e;
+            }
+        }
+    }
+    async send(to, text) {
+        let last = '';
+        for (const part of splitMessage(text, MAX_PART)) {
+            const sent = await this.withGap(to.chat, () => this.api('chat.postMessage', { channel: to.chat, thread_ts: to.thread, text: mdToSlackMrkdwn(part), unfurl_links: false, unfurl_media: false }));
+            last = String(sent.ts);
+        }
+        return { externalId: last };
+    }
+    /** Slack has no «typing…» for bots, and a reaction on every message would be noise: nothing is shown while a turn runs. */
+    async busy() { }
+    /** Scheduled messages and notices go to the channel's timeline, not into the thread they were asked from. A DM has no threads. */
+    proactive(to) { return { chat: to.chat }; }
+    /** `<@U123>` notifies the person. */
+    mention(u) { return `<@${u.id}>`; }
+    /** What the agent may react with on Slack; each emoji goes to `reactions.add` by its name. `:name:` is accepted too. */
+    reactions = SLACK_REACTIONS;
+    async react(to, ref, emoji) {
+        const wanted = emoji.replace(/️/g, '').trim();
+        const byName = /^:?([a-z0-9_+-]+):?$/.exec(wanted)?.[1];
+        const name = byName && KNOWN_NAMES.has(byName) ? byName : NAME_OF.get(wanted);
+        if (!name)
+            throw new Error(`“${emoji}” is not one of the reactions hive-am uses on Slack. The ones you can use: ${SLACK_REACTIONS.join(' ')}`);
+        if (!ref || ref.startsWith('sched-') || ref.startsWith('cmd-'))
+            throw new Error('There is no message to react to.');
+        try {
+            await this.api('reactions.add', { channel: to.chat, timestamp: ref, name });
+        }
+        catch (e) {
+            if (e instanceof SlackError && e.code === 'already_reacted')
+                return;
+            if (e instanceof SlackError && e.code === 'invalid_name')
+                throw new Error(`Slack does not know the emoji “${emoji}”. Try another one, or answer with text.`);
+            throw e instanceof SlackError ? new Error(readable(e)) : e;
+        }
+    }
+    /** Slack's upload in three steps: ask for an upload URL, send the bytes there, then share the file in the channel (and thread) with the caption. */
+    async sendFile(to, file, caption) {
+        const bytes = readFileSync(file.path);
+        try {
+            const up = await this.api('files.getUploadURLExternal', { filename: file.name, length: bytes.length });
+            const res = await fetch(up.upload_url, { method: 'POST', headers: { 'content-type': file.mime || 'application/octet-stream' }, body: bytes, signal: within(UPLOAD_TIMEOUT_MS, this.abort.signal) });
+            if (!res.ok)
+                throw new Error(`Slack did not take the file (${res.status})`);
+            await this.withGap(to.chat, () => this.api('files.completeUploadExternal', {
+                files: [{ id: up.file_id, title: file.name }], channel_id: to.chat, thread_ts: to.thread, initial_comment: caption ? mdToSlackMrkdwn(caption) : undefined,
+            }));
+            return { externalId: up.file_id };
+        }
+        catch (e) {
+            throw e instanceof SlackError ? new Error(readable(e)) : timedOut(e) ? new Error('Slack did not take the file in time') : e;
+        }
+    }
+    /** Files are private: the URL needs the bot token (and the `files:read` scope; without it Slack answers with a login page). */
+    async download(att, dest) {
+        const res = await fetch(att.id, { headers: { authorization: `Bearer ${this.conn.config.bot_token}` }, signal: within(DOWNLOAD_TIMEOUT_MS, this.abort.signal) });
+        if (!res.ok)
+            throw new Error(`download failed (${res.status})`);
+        if (/text\/html/i.test(res.headers.get('content-type') ?? '') && !/html/i.test(att.mime ?? ''))
+            throw new Error('Slack answered with a login page: the app needs the files:read scope');
+        if (Number(res.headers.get('content-length') ?? 0) > MAX_FILE_BYTES)
+            throw new Error('too big (limit 20 MB)');
+        const buf = Buffer.from(await res.arrayBuffer());
+        if (buf.length > MAX_FILE_BYTES)
+            throw new Error('too big (limit 20 MB)');
+        writeFileSync(dest, buf);
+        return buf.length;
+    }
+    /** Checks the bot token and greets each allowed person by DM. */
+    async test(userIds) {
+        let me;
+        try {
+            me = await this.api('auth.test');
+        }
+        catch (e) {
+            throw e instanceof SlackError ? new Error(readable(e)) : e;
+        }
+        const failed = [];
+        for (const id of userIds) {
+            try {
+                const { channel } = await this.api('conversations.open', { users: id });
+                await this.send({ chat: channel.id }, `✅ hive-am is connected as @${me.user} in ${me.team}.`);
+            }
+            catch (e) {
+                failed.push(`${id}: ${e instanceof SlackError ? readable(e) : e.message}`);
+            }
+        }
+        const ok = userIds.length - failed.length;
+        return `@${me.user} · ${me.team} · greeted ${ok} of ${userIds.length}${failed.length ? ` (${failed.join('; ')})` : ''}`;
+    }
+}

package/server/dist/connections/store.js

@@ -46,6 +46,8 @@ export const threads = {
             .run(id, connectionId, externalKey, info.title, JSON.stringify(info.target), info.user, t, t);
         return threads.get(id);
     },
+    /** The agent already wrote in this thread (Slack: people who keep talking in a thread it answered are talking to it). */
+    answered: (connectionId, externalKey) => !!db.prepare("SELECT 1 FROM threads t JOIN thread_messages m ON m.thread_id=t.id WHERE t.connection_id=? AND t.external_key=? AND m.direction='out' LIMIT 1").get(connectionId, externalKey),
     setMuted: (id, muted) => { db.prepare('UPDATE threads SET muted=? WHERE id=?').run(muted ? 1 : 0, id); },
     markSeen: (id, upTo) => { db.prepare('UPDATE threads SET seen_id=MAX(seen_id, ?) WHERE id=?').run(upTo, id); },
 };

package/server/dist/db/migrations.js

@@ -257,6 +257,18 @@ CREATE TABLE IF NOT EXISTS object_agents (
             addColumn(db, 'agent_types', "effort TEXT NOT NULL DEFAULT ''");
         },
     },
+    {
+        version: 9, name: 'dispatch-background',
+        up(db) {
+            // A delegation can run in the background: the orchestrator is told the result where it asked (`origin`, JSON of the chat thread, NULL for
+            // the web conversation) and `notified_at` records that the message was handed over, `read_at` that it read the result itself.
+            // Every existing row was a synchronous one, whose answer went back on the request: none of them is ever announced.
+            addColumn(db, 'dispatches', "mode TEXT NOT NULL DEFAULT 'sync'");
+            addColumn(db, 'dispatches', 'origin TEXT');
+            addColumn(db, 'dispatches', 'notified_at INTEGER');
+            addColumn(db, 'dispatches', 'read_at INTEGER');
+        },
+    },
 ];
 export const SCHEMA_VERSION = MIGRATIONS[MIGRATIONS.length - 1].version;
 /** Brings a database up to the current schema. Returns the versions it applied (empty when it was already current). */

package/server/dist/db.js

@@ -245,16 +245,28 @@ export const agents = {
     allSessions: () => q(`SELECT s.*, a.name agent_name, a.role agent_role, f.name from_name FROM agent_sessions s JOIN agents a ON a.id=s.agent_id LEFT JOIN agents f ON f.id=s.from_id ORDER BY s.last_seen DESC`).all(),
 };
 // ---- dispatch log ----
+// A delegation is `queued` until the worker's turn starts (it waits behind the worker's other turns), then `running`, then `done`, `failed`
+// or `interrupted` (the server stopped while it was queued or running).
 export const dispatches = {
-    start(from, to, task) {
+    start(from, to, task, mode = 'sync', origin = null) {
         const id = uid();
-        q('INSERT INTO dispatches (id, from_id, to_id, task, status, result, created_at, finished_at) VALUES (?,?,?,?,?,NULL,?,NULL)').run(id, from, to, task, 'running', now());
+        q('INSERT INTO dispatches (id, from_id, to_id, task, status, result, created_at, finished_at, mode, origin) VALUES (?,?,?,?,?,NULL,?,NULL,?,?)').run(id, from, to, task, 'queued', now(), mode, origin);
         return id;
     },
+    get: (id) => q('SELECT * FROM dispatches WHERE id=?').get(id),
+    setRunning: (id) => q("UPDATE dispatches SET status='running' WHERE id=? AND status='queued'").run(id),
     setSession: (id, sessionId) => q('UPDATE dispatches SET session_id=? WHERE id=?').run(sessionId, id),
     finish: (id, status, result) => q('UPDATE dispatches SET status=?, result=?, finished_at=? WHERE id=?').run(status, result.slice(0, 20000), now(), id),
+    markNotified: (id) => q('UPDATE dispatches SET notified_at=? WHERE id=? AND notified_at IS NULL').run(now(), id),
+    markRead: (id) => q('UPDATE dispatches SET read_at=? WHERE id=? AND read_at IS NULL').run(now(), id),
+    /** Background tasks of an orchestrator that have not finished yet. */
+    unfinished: (from) => q("SELECT COUNT(*) AS n FROM dispatches WHERE from_id=? AND mode='background' AND status IN ('queued','running')").get(from).n,
+    /** Finished background tasks whose result was not handed to the orchestrator yet. */
+    undelivered: () => q("SELECT * FROM dispatches WHERE mode='background' AND status NOT IN ('queued','running') AND notified_at IS NULL ORDER BY created_at").all(),
+    /** At startup nothing is running any more: what was queued or running is interrupted (a task is never resumed). */
+    interruptLeftovers: () => q("UPDATE dispatches SET status='interrupted', finished_at=? WHERE status IN ('queued','running')").run(now()).changes,
     recent: (limit = 50) => q('SELECT * FROM dispatches ORDER BY created_at DESC LIMIT ?').all(limit),
 };
 // Agents left 'running' by a crash/blackout are simply idle again: their session is intact on disk.
 q("UPDATE agents SET status='idle' WHERE status='running'").run();
-q("UPDATE dispatches SET status='interrupted' WHERE status='running'").run();
+dispatches.interruptLeftovers();