tide-commander 1.87.0 → 1.89.0

package/dist/src/packages/server/integrations/slack/slack-instance.js

@@ -0,0 +1,801 @@
+/**
+ * SlackInstance — encapsulates the connection + state for ONE Slack
+ * workspace/account. All slack-client functionality lives here as instance
+ * methods. The single-instance public surface in `slack-client.ts` is a thin
+ * facade that delegates to the `default` instance.
+ *
+ * Why this exists: chunk 1 of the multi-instance Slack rollout. We need state
+ * (WebClient, SocketModeClient, polling loop, caches, listeners, reply
+ * waiters) keyed by instance so two side-by-side connections can run later.
+ * In chunk 1 only the `default` instance is used and behavior is unchanged.
+ */
+import { promises as fs } from 'node:fs';
+import * as os from 'node:os';
+import path from 'node:path';
+import { LogLevel, WebClient } from '@slack/web-api';
+import { SocketModeClient } from '@slack/socket-mode';
+import { instanceSecretKey, loadConfig, resolveAuthMode, updateConfig } from './slack-config.js';
+import { SlackPollingClient, asPollingWebClient } from './slack-polling-client.js';
+import { SlackWatermarkStore } from './slack-watermark-store.js';
+// Subtypes we never want to trigger on. Modern file-share has NO subtype, legacy uses `file_share` — both must pass.
+const SKIP_MESSAGE_SUBTYPES = new Set([
+    'bot_message',
+    'message_changed',
+    'message_deleted',
+    'message_replied',
+    'channel_join',
+    'channel_leave',
+    'channel_topic',
+    'channel_purpose',
+    'channel_name',
+    'channel_archive',
+    'channel_unarchive',
+    'group_join',
+    'group_leave',
+    'group_topic',
+    'group_purpose',
+    'group_name',
+    'group_archive',
+    'group_unarchive',
+    'pinned_item',
+    'unpinned_item',
+]);
+/** The single, well-known instance id used until chunk 2 introduces user-defined ids. */
+export const DEFAULT_INSTANCE_ID = 'default';
+/** Encapsulates one Slack connection + all its caches/listeners/clients. */
+export class SlackInstance {
+    id;
+    webClient = null;
+    socketClient = null;
+    pollingClient = null;
+    ctx = null;
+    userCache = new Map();
+    channelNameCache = new Map();
+    messageListeners = new Set();
+    replyWaiters = new Set();
+    constructor(id) {
+        this.id = id;
+    }
+    setContext(ctx) {
+        this.ctx = ctx;
+    }
+    // ─── Init / Shutdown ───
+    async init() {
+        if (!this.ctx)
+            throw new Error('SlackInstance.init: setContext() must be called first');
+        const botToken = this.getSecret('SLACK_BOT_TOKEN');
+        const appToken = this.getSecret('SLACK_APP_TOKEN');
+        const config = loadConfig(this.id);
+        if (!config.enabled || !botToken) {
+            this.ctx.log.info(`Slack[${this.id}] disabled or missing token, skipping connection`);
+            return;
+        }
+        await this.connect(botToken, appToken);
+    }
+    /** Read a per-instance secret (e.g. SLACK_BOT_TOKEN). Default instance uses the bare key. */
+    getSecret(logicalKey) {
+        if (!this.ctx)
+            return undefined;
+        return this.ctx.secrets.get(instanceSecretKey(logicalKey, this.id));
+    }
+    async shutdown() {
+        await this.disconnect();
+        this.userCache.clear();
+        this.channelNameCache.clear();
+        this.messageListeners.clear();
+        for (const waiter of this.replyWaiters) {
+            clearTimeout(waiter.timer);
+            waiter.resolve(null);
+        }
+        this.replyWaiters.clear();
+    }
+    // ─── Connection Management ───
+    async connect(botToken, appToken) {
+        const config = loadConfig(this.id);
+        const decision = resolveAuthMode({
+            authMode: config.authMode,
+            botToken,
+            appToken,
+        });
+        if ('error' in decision) {
+            updateConfig({ status: 'error', lastError: decision.error, currentMode: 'none' }, this.id);
+            this.ctx?.log.error(`Slack[${this.id}] mode resolution failed: ${decision.error}`);
+            throw new Error(decision.error);
+        }
+        updateConfig({ status: 'connecting', lastError: undefined, currentMode: decision.mode }, this.id);
+        try {
+            // logLevel: ERROR — the library logs every 429 at WARN by default which
+            //   double-reports rate limits we already log via our own polling client.
+            // rejectRateLimitedCalls: true — surface 429s to our caller immediately
+            //   so the polling client's per-channel backoff (which moves on to other
+            //   channels) handles them, instead of the library serially retrying and
+            //   blocking the whole conversations.history call.
+            this.webClient = new WebClient(botToken, {
+                logLevel: LogLevel.ERROR,
+                rejectRateLimitedCalls: true,
+            });
+            // auth.test works for both bot and user tokens. For xoxp- it returns the
+            // user's own id/handle, used for "skip self" filtering.
+            const authResult = await this.webClient.auth.test();
+            const botUserId = authResult.user_id;
+            const botName = authResult.user || 'tide-bot';
+            updateConfig({
+                status: 'connected',
+                botUserId,
+                botName,
+                connectedAt: Date.now(),
+                currentMode: decision.mode,
+            }, this.id);
+            if (decision.mode === 'socket') {
+                this.socketClient = new SocketModeClient({ appToken: appToken });
+                this.setupSocketHandlers();
+                await this.socketClient.start();
+                this.ctx?.log.info(`Slack[${this.id}] connected as @${botName} (${botUserId}) via socket mode`);
+            }
+            else {
+                await this.startPollingMode();
+                this.ctx?.log.info(`Slack[${this.id}] connected as @${botName} (${botUserId}) via polling mode`);
+            }
+        }
+        catch (err) {
+            const errorMsg = err instanceof Error ? err.message : String(err);
+            updateConfig({ status: 'error', lastError: errorMsg, currentMode: 'none' }, this.id);
+            this.ctx?.log.error(`Slack[${this.id}] connection failed: ${errorMsg}`);
+            this.webClient = null;
+            this.socketClient = null;
+            if (this.pollingClient) {
+                await this.pollingClient.stop().catch(() => undefined);
+                this.pollingClient = null;
+            }
+            throw err;
+        }
+    }
+    async startPollingMode() {
+        if (!this.webClient)
+            throw new Error('Polling mode requires an initialized WebClient');
+        const config = loadConfig(this.id);
+        const watermarkStore = new SlackWatermarkStore({
+            filePath: this.getWatermarkPath(),
+        });
+        // Parse the allowlist: split on commas / newlines / whitespace, strip empties.
+        const allowlistChannelIds = (config.pollingChannelAllowlist ?? '')
+            .split(/[\s,]+/)
+            .map((s) => s.trim())
+            .filter(Boolean);
+        this.pollingClient = new SlackPollingClient({
+            webClient: asPollingWebClient(this.webClient),
+            watermarkStore,
+            dispatch: (event) => this.dispatchInboundMessage(event),
+            intervalSec: config.pollingIntervalSec ?? 45,
+            backfillMessageCap: config.pollingBackfillMessageCap ?? 100,
+            backfillSeconds: config.pollingBackfillSeconds ?? 24 * 60 * 60,
+            concurrency: config.pollingConcurrency ?? 4,
+            channelListRefreshEveryNCycles: 10,
+            channelTypes: config.pollingChannelTypes,
+            allowlistChannelIds,
+            keepAllDms: config.pollingDmsAlways !== false,
+            minMsBetweenCalls: config.pollingMinMsBetweenCalls ?? 1500,
+        });
+        this.pollingClient.setOnFatalError((reason) => {
+            updateConfig({ status: 'error', lastError: reason }, this.id);
+            this.ctx?.broadcast({
+                type: 'slack_polling_halted',
+                payload: { instanceId: this.id, reason },
+            });
+        });
+        await this.pollingClient.start();
+    }
+    /**
+     * Backward-compat: the `default` instance keeps the historical filename so
+     * existing users don't need migration. Other instances get suffixed names.
+     */
+    getWatermarkPath() {
+        const dataDir = path.join(process.env.XDG_DATA_HOME || path.join(os.homedir(), '.local', 'share'), 'tide-commander');
+        if (this.id === DEFAULT_INSTANCE_ID) {
+            return path.join(dataDir, 'slack-watermarks.json');
+        }
+        return path.join(dataDir, `slack-watermarks-${this.id}.json`);
+    }
+    async reconnect() {
+        if (!this.ctx)
+            throw new Error('SlackInstance.reconnect: not initialized');
+        await this.disconnect();
+        const botToken = this.getSecret('SLACK_BOT_TOKEN');
+        const appToken = this.getSecret('SLACK_APP_TOKEN');
+        if (!botToken) {
+            throw new Error('Missing Slack token');
+        }
+        await this.connect(botToken, appToken);
+    }
+    async disconnect() {
+        if (this.socketClient) {
+            try {
+                await this.socketClient.disconnect();
+            }
+            catch {
+                // Ignore disconnect errors
+            }
+            this.socketClient = null;
+        }
+        if (this.pollingClient) {
+            await this.pollingClient.stop().catch(() => undefined);
+            this.pollingClient = null;
+        }
+        this.webClient = null;
+        updateConfig({ status: 'disconnected', connectedAt: undefined, currentMode: 'none' }, this.id);
+    }
+    setupSocketHandlers() {
+        if (!this.socketClient)
+            return;
+        this.socketClient.on('message', async ({ event, ack }) => {
+            await ack();
+            if (!event)
+                return;
+            await this.dispatchInboundMessage(event);
+        });
+        this.socketClient.on('disconnect', () => {
+            this.ctx?.log.warn(`Slack[${this.id}] Socket Mode disconnected`);
+            updateConfig({ status: 'disconnected' }, this.id);
+        });
+        this.socketClient.on('unable_to_socket_mode_start', (err) => {
+            this.ctx?.log.error(`Slack[${this.id}] Socket Mode start failed: ${err}`);
+            updateConfig({ status: 'error', lastError: String(err) }, this.id);
+        });
+    }
+    /**
+     * Single dispatcher pipeline shared by Socket Mode and Polling. Filters
+     * subtypes / self / empty messages, logs to SQLite, broadcasts WS, fires
+     * trigger listeners, and resolves reply waiters.
+     */
+    async dispatchInboundMessage(event) {
+        if (event.subtype && SKIP_MESSAGE_SUBTYPES.has(event.subtype))
+            return;
+        const hasFiles = Array.isArray(event.files) && event.files.length > 0;
+        const text = event.text ?? '';
+        if (!text && !hasFiles)
+            return;
+        const config = loadConfig(this.id);
+        const isOwnMessage = !!event.user && event.user === config.botUserId;
+        // Skip own messages unless this instance is configured to mirror them.
+        if (isOwnMessage && !config.mirrorOwnMessages)
+            return;
+        const userId = event.user ?? '';
+        let userName = userId;
+        if (userId) {
+            try {
+                const user = await this.resolveUser(userId);
+                userName = user?.displayName || user?.name || userId;
+            }
+            catch {
+                // Use userId as fallback
+            }
+        }
+        const files = hasFiles
+            ? event.files.map((f) => normalizeSlackFile(f))
+            : undefined;
+        const message = {
+            ts: event.ts,
+            threadTs: event.thread_ts,
+            channel: event.channel,
+            userId,
+            userName,
+            text,
+            timestamp: parseSlackTs(event.ts),
+            files,
+            isOwnMessage,
+        };
+        const direction = isOwnMessage ? 'outbound' : 'inbound';
+        // Heartbeat: one line per dispatched message. PII-safe — only ids, ts,
+        // direction, file count. No message text, no usernames, no emails.
+        this.ctx?.log.info(`Slack[${this.id}] dispatch: channel=${event.channel} user=${userId || '-'} ts=${event.ts} direction=${direction} files=${files?.length ?? 0}${event.thread_ts && event.thread_ts !== event.ts ? ` thread=${event.thread_ts}` : ''}`);
+        this.ctx?.eventDb.logSlackMessage({
+            ts: event.ts,
+            threadTs: event.thread_ts,
+            channelId: event.channel,
+            channelName: this.channelNameCache.get(event.channel),
+            userId,
+            userName,
+            text,
+            direction,
+            rawEvent: event,
+            receivedAt: Date.now(),
+            integrationInstanceId: this.id,
+        });
+        this.ctx?.broadcast({
+            type: 'slack_message_received',
+            payload: {
+                instanceId: this.id,
+                channel: event.channel,
+                userName,
+                text,
+                ts: event.ts,
+                fileCount: files?.length ?? 0,
+                direction,
+            },
+        });
+        // Trigger listeners receive own messages too (tagged with isOwnMessage);
+        // the slack trigger handler decides whether to fire based on trigger config.
+        for (const listener of this.messageListeners) {
+            try {
+                listener(message);
+            }
+            catch (err) {
+                this.ctx?.log.error(`Slack[${this.id}] message listener error: ${err}`);
+            }
+        }
+        // Reply waiters always skip own messages — a wait-for-reply must not
+        // resolve on our own outgoing message.
+        if (isOwnMessage)
+            return;
+        for (const waiter of this.replyWaiters) {
+            if (waiter.channel !== message.channel)
+                continue;
+            if (waiter.threadTs !== message.threadTs && waiter.threadTs !== message.ts)
+                continue;
+            if (waiter.fromUsers?.length && !waiter.fromUsers.includes(message.userId))
+                continue;
+            if (waiter.messagePattern && !new RegExp(waiter.messagePattern).test(message.text))
+                continue;
+            clearTimeout(waiter.timer);
+            this.replyWaiters.delete(waiter);
+            waiter.resolve(message);
+        }
+    }
+    // ─── Sending ───
+    async sendMessage(params) {
+        if (!this.webClient)
+            throw new Error('Slack not connected');
+        const result = await this.webClient.chat.postMessage({
+            channel: params.channel,
+            text: params.text,
+            thread_ts: params.threadTs,
+        });
+        const ts = result.ts;
+        const channel = result.channel;
+        const config = loadConfig(this.id);
+        this.ctx?.eventDb.logSlackMessage({
+            ts,
+            threadTs: params.threadTs,
+            channelId: channel,
+            channelName: this.channelNameCache.get(channel),
+            userId: config.botUserId || '',
+            userName: config.botName || 'tide-bot',
+            text: params.text,
+            direction: 'outbound',
+            agentId: params.agentId,
+            workflowInstanceId: params.workflowInstanceId,
+            receivedAt: Date.now(),
+            integrationInstanceId: this.id,
+        });
+        return { ts, channel };
+    }
+    // ─── Reactions ───
+    async addReaction(params) {
+        if (!this.webClient)
+            throw new Error('Slack not connected');
+        const name = normalizeEmojiName(params.name);
+        try {
+            await this.webClient.reactions.add({
+                channel: params.channel,
+                timestamp: params.ts,
+                name,
+            });
+        }
+        catch (err) {
+            const slackErr = err.data?.error;
+            if (slackErr === 'already_reacted')
+                return;
+            throw err;
+        }
+    }
+    // ─── Reading ───
+    async getChannelMessages(params) {
+        if (!this.webClient)
+            throw new Error('Slack not connected');
+        const result = await this.webClient.conversations.history({
+            channel: params.channel,
+            limit: params.limit || 20,
+            oldest: params.oldest,
+            latest: params.latest,
+        });
+        return Promise.all((result.messages || []).map((msg) => this.slackApiMessageToSlackMessage(msg, params.channel)));
+    }
+    async getThreadReplies(params) {
+        if (!this.webClient)
+            throw new Error('Slack not connected');
+        const result = await this.webClient.conversations.replies({
+            channel: params.channel,
+            ts: params.threadTs,
+            limit: params.limit || 50,
+        });
+        return Promise.all((result.messages || []).map((msg) => this.slackApiMessageToSlackMessage(msg, params.channel)));
+    }
+    // ─── Wait For Reply (Long-Poll) ───
+    waitForReply(params) {
+        const timeout = params.timeoutMs || 300000;
+        return new Promise((resolve) => {
+            const timer = setTimeout(() => {
+                this.replyWaiters.delete(waiter);
+                resolve(null);
+            }, timeout);
+            const waiter = {
+                channel: params.channel,
+                threadTs: params.threadTs,
+                fromUsers: params.fromUsers,
+                messagePattern: params.messagePattern,
+                resolve,
+                timer,
+            };
+            this.replyWaiters.add(waiter);
+        });
+    }
+    // ─── Channel Management ───
+    async joinChannel(channel) {
+        if (!this.webClient)
+            throw new Error('Slack not connected');
+        const result = await this.webClient.conversations.join({ channel });
+        const ch = result.channel;
+        if (!ch)
+            throw new Error(`Failed to join channel ${channel}`);
+        this.channelNameCache.set(ch.id, ch.name);
+        return { id: ch.id, name: ch.name };
+    }
+    async listChannels() {
+        if (!this.webClient)
+            throw new Error('Slack not connected');
+        const channels = [];
+        let cursor;
+        do {
+            const result = await this.webClient.conversations.list({
+                types: 'public_channel,private_channel',
+                limit: 200,
+                cursor,
+            });
+            for (const ch of result.channels || []) {
+                const channel = {
+                    id: ch.id,
+                    name: ch.name,
+                    isPrivate: ch.is_private,
+                    isMember: ch.is_member,
+                    topic: ch.topic?.value,
+                    purpose: ch.purpose?.value,
+                };
+                channels.push(channel);
+                this.channelNameCache.set(channel.id, channel.name);
+            }
+            cursor = result.response_metadata?.next_cursor || undefined;
+        } while (cursor);
+        return channels;
+    }
+    async resolveUser(userId) {
+        const cached = this.userCache.get(userId);
+        if (cached)
+            return cached;
+        if (!this.webClient)
+            throw new Error('Slack not connected');
+        const result = await this.webClient.users.info({ user: userId });
+        const u = result.user;
+        if (!u)
+            throw new Error(`User not found: ${userId}`);
+        const user = {
+            id: u.id,
+            name: u.name,
+            realName: u.real_name || '',
+            displayName: u.profile?.display_name || u.name,
+            email: u.profile?.email,
+            isBot: u.is_bot,
+        };
+        this.userCache.set(userId, user);
+        return user;
+    }
+    async findUserByEmail(email) {
+        if (!this.webClient)
+            throw new Error('Slack not connected');
+        try {
+            const result = await this.webClient.users.lookupByEmail({ email });
+            const u = result.user;
+            if (!u)
+                return null;
+            const user = {
+                id: u.id,
+                name: u.name,
+                realName: u.real_name || '',
+                displayName: u.profile?.display_name || u.name,
+                email: u.profile?.email,
+                isBot: u.is_bot,
+            };
+            this.userCache.set(user.id, user);
+            return user;
+        }
+        catch {
+            return null;
+        }
+    }
+    async findUserByName(displayName) {
+        if (!this.webClient)
+            throw new Error('Slack not connected');
+        const result = await this.webClient.users.list({ limit: 500 });
+        const lower = displayName.toLowerCase();
+        for (const u of result.members || []) {
+            const profile = u.profile;
+            if (u.name?.toLowerCase() === lower ||
+                u.real_name?.toLowerCase() === lower ||
+                profile?.display_name?.toLowerCase() === lower) {
+                const user = {
+                    id: u.id,
+                    name: u.name,
+                    realName: u.real_name || '',
+                    displayName: profile?.display_name || u.name,
+                    email: u.profile?.email,
+                    isBot: u.is_bot,
+                };
+                this.userCache.set(user.id, user);
+                return user;
+            }
+        }
+        return null;
+    }
+    async searchUsers(query) {
+        if (!this.webClient)
+            throw new Error('Slack not connected');
+        const result = await this.webClient.users.list({ limit: 500 });
+        const lower = query.toLowerCase();
+        const matches = [];
+        for (const u of result.members || []) {
+            if (u.deleted || u.is_bot)
+                continue;
+            const profile = u.profile;
+            const name = u.name || '';
+            const realName = u.real_name || '';
+            const dispName = profile?.display_name || '';
+            const email = profile?.email || '';
+            if (name.toLowerCase().includes(lower) ||
+                realName.toLowerCase().includes(lower) ||
+                dispName.toLowerCase().includes(lower) ||
+                email.toLowerCase().includes(lower)) {
+                const user = {
+                    id: u.id,
+                    name,
+                    realName,
+                    displayName: dispName || name,
+                    email,
+                    isBot: false,
+                };
+                this.userCache.set(user.id, user);
+                matches.push(user);
+            }
+        }
+        return matches;
+    }
+    // ─── Direct Messages ───
+    async openDmChannel(userId) {
+        if (!this.webClient)
+            throw new Error('Slack not connected');
+        const result = await this.webClient.conversations.open({ users: userId });
+        const channelId = result.channel?.id;
+        if (!channelId)
+            throw new Error(`Failed to open DM channel with user ${userId}`);
+        return channelId;
+    }
+    async sendDm(params) {
+        const dmChannel = await this.openDmChannel(params.userId);
+        return this.sendMessage({
+            channel: dmChannel,
+            text: params.text,
+            agentId: params.agentId,
+            workflowInstanceId: params.workflowInstanceId,
+        });
+    }
+    // ─── File Upload ───
+    async uploadFile(params) {
+        if (!this.webClient)
+            throw new Error('Slack not connected');
+        const length = params.bytes instanceof Buffer ? params.bytes.length : params.bytes.byteLength;
+        if (!length)
+            throw new Error('uploadFile: bytes is empty');
+        const step1 = await this.webClient.files.getUploadURLExternal({
+            filename: params.filename,
+            length,
+        });
+        if (!step1.ok || !step1.upload_url || !step1.file_id) {
+            throw new Error(`Slack files.getUploadURLExternal failed: ${step1.error ?? 'unknown error'}`);
+        }
+        const bodyBytes = params.bytes instanceof Buffer
+            ? new Uint8Array(params.bytes.buffer, params.bytes.byteOffset, params.bytes.byteLength)
+            : params.bytes;
+        const putResp = await fetch(step1.upload_url, {
+            method: 'POST',
+            headers: { 'Content-Type': 'application/octet-stream' },
+            body: bodyBytes,
+        });
+        if (!putResp.ok) {
+            const detail = await putResp.text().catch(() => '');
+            throw new Error(`Slack upload_url POST failed (${putResp.status}): ${detail}`);
+        }
+        const files = [
+            { id: step1.file_id, title: params.title ?? params.filename },
+        ];
+        const step3 = params.channelId
+            ? await this.webClient.files.completeUploadExternal({
+                files,
+                channel_id: params.channelId,
+                initial_comment: params.initialComment,
+                thread_ts: params.threadTs,
+            })
+            : await this.webClient.files.completeUploadExternal({ files });
+        if (!step3.ok) {
+            throw new Error(`Slack files.completeUploadExternal failed: ${step3.error ?? 'unknown error'}`);
+        }
+        const file = (step3.files?.[0] ?? { id: step1.file_id });
+        return { fileId: step1.file_id, file };
+    }
+    // ─── File Read / Download ───
+    async listFiles(params = {}) {
+        if (!this.webClient)
+            throw new Error('Slack not connected');
+        const result = await this.webClient.files.list({
+            channel: params.channelId,
+            user: params.userId,
+            ts_from: params.tsFrom,
+            ts_to: params.tsTo,
+            types: params.types,
+            count: params.count ?? 50,
+            page: params.page,
+        });
+        return (result.files ?? []).map((f) => normalizeSlackFile(f));
+    }
+    async getFileInfo(fileId) {
+        if (!this.webClient)
+            throw new Error('Slack not connected');
+        const result = await this.webClient.files.info({ file: fileId });
+        if (!result.ok || !result.file) {
+            throw new Error(`Slack files.info failed for ${fileId}: ${result.error ?? 'unknown error'}`);
+        }
+        return normalizeSlackFile(result.file);
+    }
+    async fetchFileBytes(fileId) {
+        const token = this.getSecret('SLACK_BOT_TOKEN');
+        if (!token)
+            throw new Error('Slack bot token is not configured');
+        const info = await this.getFileInfo(fileId);
+        const url = info.url_private_download || info.url_private;
+        if (!url)
+            throw new Error(`Slack file ${fileId} has no url_private`);
+        const response = await fetch(url, {
+            method: 'GET',
+            headers: {
+                Authorization: `Bearer ${token}`,
+                Accept: '*/*',
+            },
+            redirect: 'follow',
+        });
+        if (!response.ok) {
+            const detail = await response.text().catch(() => '');
+            throw new Error(`Slack file download failed for ${fileId} (${response.status}): ${detail}`);
+        }
+        return {
+            buffer: Buffer.from(await response.arrayBuffer()),
+            contentType: response.headers.get('content-type'),
+            contentDisposition: response.headers.get('content-disposition'),
+            contentLength: response.headers.get('content-length'),
+            filename: info.name,
+        };
+    }
+    async downloadFile(file, outputPath) {
+        const fileId = typeof file === 'string' ? file : file.id;
+        const { buffer, filename, contentType } = await this.fetchFileBytes(fileId);
+        await fs.mkdir(path.dirname(path.resolve(outputPath)), { recursive: true });
+        await fs.writeFile(outputPath, buffer);
+        return {
+            path: outputPath,
+            bytes: buffer.byteLength,
+            filename,
+            mimeType: contentType ?? undefined,
+        };
+    }
+    // ─── Event Subscription (for triggers) ───
+    onMessage(callback) {
+        this.messageListeners.add(callback);
+        return () => { this.messageListeners.delete(callback); };
+    }
+    // ─── Status ───
+    getStatus() {
+        const config = loadConfig(this.id);
+        return {
+            connected: config.status === 'connected',
+            lastChecked: Date.now(),
+            error: config.lastError,
+        };
+    }
+    isConnected() {
+        return loadConfig(this.id).status === 'connected' && this.webClient !== null;
+    }
+    // ─── Internal helper ───
+    async slackApiMessageToSlackMessage(msg, channel) {
+        const userId = msg.user || '';
+        let userName = userId;
+        try {
+            if (userId) {
+                const user = await this.resolveUser(userId);
+                userName = user.displayName || user.name;
+            }
+        }
+        catch {
+            // Use userId as fallback
+        }
+        const rawFiles = msg.files;
+        const files = rawFiles?.length ? rawFiles.map(normalizeSlackFile) : undefined;
+        return {
+            ts: msg.ts,
+            threadTs: msg.thread_ts,
+            channel,
+            userId,
+            userName,
+            text: msg.text || '',
+            timestamp: parseSlackTs(msg.ts),
+            files,
+        };
+    }
+}
+// ─── Module-level helpers (stateless) ───
+function parseSlackTs(ts) {
+    return Math.floor(parseFloat(ts) * 1000);
+}
+function normalizeEmojiName(input) {
+    const trimmed = input.trim().replace(/^:|:$/g, '');
+    if (trimmed === '👁' || trimmed === '👁️' || trimmed === '👀')
+        return 'eyes';
+    return trimmed;
+}
+function normalizeSlackFile(f) {
+    return {
+        id: f.id,
+        name: f.name,
+        title: f.title,
+        mimetype: f.mimetype,
+        size: f.size,
+        permalink: f.permalink,
+        permalink_public: f.permalink_public,
+        url_private: f.url_private,
+        url_private_download: f.url_private_download,
+    };
+}
+// ─── Instance Registry ───
+const instances = new Map();
+/**
+ * Get (or lazily create) the instance with the given id. The registry is
+ * seeded from the manifest at boot (slack/index.ts), but unknown ids are
+ * created on demand so individual route handlers don't have to special-case
+ * "instance was just added but registry isn't reloaded yet".
+ */
+export function getInstance(id = DEFAULT_INSTANCE_ID) {
+    let inst = instances.get(id);
+    if (!inst) {
+        inst = new SlackInstance(id);
+        instances.set(id, inst);
+    }
+    return inst;
+}
+/** Like getInstance, but returns undefined instead of creating one. */
+export function getInstanceOrUndefined(id) {
+    return instances.get(id);
+}
+/** Remove a single instance from the registry (used when deleting an instance). */
+export async function removeInstance(id) {
+    if (id === DEFAULT_INSTANCE_ID) {
+        throw new Error('Cannot remove the default Slack instance');
+    }
+    const inst = instances.get(id);
+    if (inst) {
+        await inst.shutdown();
+        instances.delete(id);
+    }
+}
+/** All currently-loaded instances. */
+export function listInstances() {
+    return Array.from(instances.values());
+}
+/** Drop every instance (used by shutdown / tests). */
+export function clearInstances() {
+    instances.clear();
+}