@mono-agent/slack-adapter 0.3.0 → 0.4.1

package/dist/adapter.js

@@ -1,5 +1,17 @@
 import { isAgentResponseCancelledError, } from "@mono-agent/agent-contracts";
 import { SlackMessageStream, } from "./message-stream.js";
+const DEFAULT_ATTACHMENT_MAX_BYTES = 10 * 1024 * 1024;
+const DEFAULT_ALLOWED_MIME_TYPES = [
+    "image/png",
+    "image/jpeg",
+    "image/gif",
+    "image/webp",
+    "application/pdf",
+    "text/plain",
+    "text/markdown",
+    "text/csv",
+    "application/json",
+];
 const DEFAULT_MESSAGES = {
     welcomeText: "Hello! Send me a Slack message and I will pass it to the configured agent.",
     helpText: "Send a Slack DM or mention the app in a channel. Use /cancel in a thread to stop the current response.",
@@ -9,6 +21,66 @@ const DEFAULT_MESSAGES = {
     errorText: "The agent failed while processing your Slack message.",
     unsupportedText: "I can only handle Slack text messages in this adapter for now.",
 };
+// Slack delivers file uploads as subtyped messages (`file_share`), and a message
+// posted to a thread "also sent to channel" arrives as `thread_broadcast`. Both
+// carry real user content (text and/or a `files` array), so they must NOT be
+// rejected alongside genuinely-unsupported subtypes (e.g. message_changed,
+// channel_join). Without this, attachments are silently dropped.
+const FILE_BEARING_MESSAGE_SUBTYPES = new Set([
+    "file_share",
+    "thread_broadcast",
+]);
+// Mirrors the harness LiveSessionManager's DEFAULT_MAX_PENDING_PER_CONVERSATION:
+// the per-conversation admission queue rejects past this depth so a flood of
+// same-conversation messages cannot grow the queue unbounded.
+const DEFAULT_ADMISSION_QUEUE_MAX_DEPTH = 100;
+/**
+ * Thrown synchronously by {@link SerialQueue.run} when the queue is already at
+ * its depth cap. The adapter catches this sentinel to answer with the busy
+ * terminal instead of admitting an unbounded backlog.
+ */
+export class SerialQueueFullError extends Error {
+    code = "serial_queue_full";
+    constructor(maxDepth) {
+        super(`Per-conversation admission queue is full (max ${maxDepth} pending).`);
+        this.name = "SerialQueueFullError";
+    }
+}
+/**
+ * Minimal per-conversation serial queue: each submitted task runs only after the
+ * previous one settles, preserving arrival order. A task's failure does not
+ * poison the queue (the chain swallows it; the caller still sees the rejection).
+ *
+ * The queue is bounded by {@link maxDepth}: once `depth` reaches the cap, `run`
+ * rejects synchronously with a {@link SerialQueueFullError} BEFORE incrementing
+ * or chaining, so an over-cap task never enters the chain (mirroring the harness
+ * LiveSessionManager's maxPendingPerConversation rejection).
+ */
+export class SerialQueue {
+    tail = Promise.resolve();
+    depth = 0;
+    maxDepth;
+    constructor(maxDepth = DEFAULT_ADMISSION_QUEUE_MAX_DEPTH) {
+        this.maxDepth = maxDepth;
+    }
+    run(task) {
+        if (this.depth >= this.maxDepth) {
+            return Promise.reject(new SerialQueueFullError(this.maxDepth));
+        }
+        this.depth += 1;
+        const result = this.tail.then(() => task());
+        this.tail = result.then(() => undefined, () => undefined);
+        void result.then(() => { this.depth -= 1; }, () => { this.depth -= 1; });
+        return result;
+    }
+    /** True when no task is queued or running. */
+    get idle() {
+        return this.depth === 0;
+    }
+}
+function isSerialQueueFullError(error) {
+    return error instanceof SerialQueueFullError;
+}
 export class SlackAdapter {
     api;
     responder;
@@ -20,8 +92,37 @@ export class SlackAdapter {
     stripMentionText;
     streamOptions;
     messages;
+    attachmentMaxBytes;
+    allowedMimeTypes;
+    /** callback_id → shortcut binding for registered Slack shortcuts. */
+    shortcuts;
+    /** action_id → button binding for App Home tab buttons. */
+    homeButtons;
+    /** Ordered Home tab buttons (for rendering the view in config order). */
+    homeButtonOrder;
+    homeTabEnabled;
+    homeTabHeaderText;
+    /** First allowlisted channel (original case), used as a global interaction's default reply destination. */
+    defaultShortcutChannelId;
     logger;
-    activeRuns = new Map();
+    resolvePostIndex;
+    recordPostedMessage;
+    /**
+     * In-flight abort controllers per thread. The harness serializes runs for a
+     * conversation, so several may be queued/active concurrently; /cancel aborts
+     * every controller for the thread (and clears the harness queue via
+     * responder.cancel).
+     */
+    activeControllers = new Map();
+    /**
+     * Per-conversation admission queue. Socket Mode dispatches envelopes
+     * concurrently, and pre-submit work (status + file download) is variable
+     * latency, so without this a later same-thread message could reach
+     * responder.respond() (and the harness FIFO) before an earlier one. We
+     * serialize respondToEvent per conversation to preserve message order.
+     * /cancel stays out-of-band (handled before this queue).
+     */
+    admissionQueues = new Map();
     constructor(options) {
         this.api = options.api;
         this.responder = options.responder;
@@ -34,12 +135,29 @@ export class SlackAdapter {
             options.stripMentionText ?? (this.botUserIds.size > 0 || this.mentionTextAliases.length > 0);
         this.streamOptions = options.stream ?? {};
         this.messages = { ...DEFAULT_MESSAGES, ...options.messages };
+        this.attachmentMaxBytes = options.attachments?.maxBytes ?? DEFAULT_ATTACHMENT_MAX_BYTES;
+        this.allowedMimeTypes = new Set((options.attachments?.allowedMimeTypes ?? DEFAULT_ALLOWED_MIME_TYPES).map((mime) => mime.trim().toLowerCase()));
+        this.shortcuts = new Map((options.shortcuts ?? [])
+            .filter((binding) => binding.callbackId.trim().length > 0)
+            .map((binding) => [binding.callbackId, binding]));
+        this.homeButtonOrder = (options.homeTab?.buttons ?? []).filter((button) => button.actionId.trim().length > 0);
+        this.homeButtons = new Map(this.homeButtonOrder.map((button) => [button.actionId, button]));
+        this.homeTabEnabled = options.homeTab?.enabled === true;
+        this.homeTabHeaderText = options.homeTab?.headerText;
+        this.defaultShortcutChannelId = options.allowedChannelIds?.[0];
         this.logger = options.logger;
+        this.resolvePostIndex = options.resolvePostIndex;
+        this.recordPostedMessage = options.recordPostedMessage;
         if (!this.allowAllChannels && this.allowedChannelIds.size === 0) {
             throw new TypeError("SlackAdapter requires allowedChannelIds or allowAllChannels: true.");
         }
     }
     async handleEventCallback(callback) {
+        // App Home tab opened → (re)publish the button panel. This is an events_api
+        // event with no channel/trigger, so it is handled before the message path.
+        if (callback.event.type === "app_home_opened" && callback.event.tab === "home") {
+            return this.handleAppHomeOpened(callback);
+        }
         const normalized = this.normalizeEventCallback(callback);
         if (normalized.kind === "ignored") {
             return normalized;
@@ -58,7 +176,7 @@ export class SlackAdapter {
             };
         }
         const text = event.text.trim();
-        if (text.length === 0) {
+        if (text.length === 0 && event.files.length === 0) {
             await this.api.chatPostMessage({
                 channel: event.channelId,
                 text: this.messages.unsupportedText,
@@ -103,10 +221,20 @@ export class SlackAdapter {
             };
         }
         const runKey = runKeyFor(event);
-        const activeRun = this.activeRuns.get(runKey);
+        // Resolve once, up front, so /cancel, the admission queue, and the run all use
+        // the SAME conversationId — an in-thread reply to a message we posted resolves
+        // to the producing conversation (so it loads that history), else the default
+        // slack: thread id.
+        const conversationId = await this.resolveConversationId(event);
         if (command?.name === "cancel") {
-            if (activeRun !== undefined) {
-                activeRun.controller.abort(new Error("Cancelled by Slack user."));
+            // Clear any queued follow-ups for the conversation (the harness owns the
+            // queue) and abort every in-flight controller for this thread.
+            this.responder.cancel?.(conversationId, new Error("Cancelled by Slack user."));
+            const controllers = this.activeControllers.get(runKey);
+            if (controllers !== undefined) {
+                for (const controller of controllers) {
+                    controller.abort(new Error("Cancelled by Slack user."));
+                }
             }
             await this.api.chatPostMessage({
                 channel: event.channelId,
@@ -119,28 +247,426 @@ export class SlackAdapter {
                 channelId: event.channelId,
             };
         }
-        if (activeRun !== undefined) {
-            await this.api.chatPostMessage({
-                channel: event.channelId,
-                text: this.messages.busyText,
-                thread_ts: event.threadTs,
+        // No per-thread "busy" rejection: the harness serializes runs for the
+        // conversation, queuing a concurrent message and answering it on the warm
+        // session after the current turn. We admit messages through a per-conversation
+        // serial queue first so they reach the harness in arrival order even when an
+        // earlier message stalls on file download.
+        //
+        // Create and register the controller BEFORE entering the admission queue so a
+        // /cancel can abort a message still parked behind an earlier same-thread run.
+        // respondToEvent's first abort check then makes the queued-then-cancelled run
+        // bail before responder.respond and post only the cancelled terminal.
+        const controller = new AbortController();
+        this.registerController(runKey, controller);
+        let queue = this.admissionQueues.get(conversationId);
+        if (queue === undefined) {
+            queue = new SerialQueue();
+            this.admissionQueues.set(conversationId, queue);
+        }
+        try {
+            return await queue.run(() => this.respondToEvent(event, text, runKey, controller, conversationId));
+        }
+        catch (error) {
+            if (isSerialQueueFullError(error)) {
+                // Over-cap: the task was rejected BEFORE entering the queue, so
+                // respondToEvent (and its finally) never ran. Unregister the eagerly
+                // created controller here so it does not leak in activeControllers, then
+                // answer with the busy terminal instead of admitting an unbounded backlog.
+                this.unregisterController(runKey, controller);
+                await this.api.chatPostMessage({
+                    channel: event.channelId,
+                    text: this.messages.busyText,
+                    thread_ts: event.threadTs,
+                });
+                return { kind: "busy", eventId: event.eventId, channelId: event.channelId };
+            }
+            throw error;
+        }
+        finally {
+            if (queue.idle && this.admissionQueues.get(conversationId) === queue) {
+                this.admissionQueues.delete(conversationId);
+            }
+        }
+    }
+    /**
+     * Deliver a proactive notification to a Slack destination by running it as a
+     * turn on that destination's OWN harness (shared session/history + the same
+     * per-conversation admission queue as inbound messages) and posting the answer
+     * through the normal stream. `threadTs` targets an existing thread (clean
+     * continuity — the user's in-thread replies share the session); omitting it
+     * posts top-level (fire-and-forget: a fresh top-level post has no pre-existing
+     * thread to share continuity with). Used by cron/webhook nudges. Best-effort:
+     * a failed or empty turn posts nothing.
+     */
+    async notify(channelId, threadTs, text, options) {
+        const conversationId = threadTs === undefined ? `slack:${channelId}` : `slack:${channelId}:${threadTs}`;
+        // A threaded proactive run shares the inbound /cancel key so a user's
+        // /cancel in that thread can abort it; a top-level post (no thread) has no
+        // inbound /cancel target, so it keeps its own proactive key.
+        const runKey = threadTs === undefined ? `proactive:${conversationId}` : `${channelId}:${threadTs}`;
+        const controller = new AbortController();
+        this.registerController(runKey, controller);
+        let queue = this.admissionQueues.get(conversationId);
+        if (queue === undefined) {
+            queue = new SerialQueue();
+            this.admissionQueues.set(conversationId, queue);
+        }
+        try {
+            return await queue.run(() => options?.verbatim === true
+                ? this.runVerbatimDelivery(conversationId, channelId, threadTs, text, runKey, controller)
+                : this.runProactiveTurn(conversationId, channelId, threadTs, text, runKey, controller));
+        }
+        catch (error) {
+            if (isSerialQueueFullError(error)) {
+                this.unregisterController(runKey, controller);
+                this.logger?.warn?.("Slack proactive notify dropped: conversation is at its concurrency cap.", {
+                    conversationId,
+                });
+                return { delivered: false, reason: "conversation at concurrency cap" };
+            }
+            throw error;
+        }
+        finally {
+            if (queue.idle && this.admissionQueues.get(conversationId) === queue) {
+                this.admissionQueues.delete(conversationId);
+            }
+        }
+    }
+    /**
+     * Route any interactivity payload to the right handler: a shortcut/message
+     * action by `callback_id`, or a Block Kit button click by `action_id`.
+     */
+    async handleInteraction(payload) {
+        if (payload.type === "block_actions") {
+            return this.handleBlockActions(payload);
+        }
+        return this.handleShortcut(payload);
+    }
+    /**
+     * Route a Slack shortcut payload. When its `callback_id` is bound to a prompt
+     * and the resolved destination channel is authorized, run that prompt as a
+     * proactive turn. The destination is the binding's `channelId`, else the
+     * payload's own channel (message shortcuts), else the first allowlisted channel.
+     */
+    async handleShortcut(payload) {
+        const callbackId = typeof payload.callback_id === "string" ? payload.callback_id : undefined;
+        if (callbackId === undefined || callbackId.length === 0) {
+            return { kind: "ignored", reason: "no_action" };
+        }
+        const binding = this.shortcuts.get(callbackId);
+        if (binding === undefined) {
+            return { kind: "ignored", reason: "unbound", id: callbackId };
+        }
+        // A message shortcut can reply in the source thread; a global shortcut has no
+        // thread, so the run posts top-level in the destination channel.
+        const threadTs = firstNonEmpty(payload.message?.thread_ts, payload.message?.ts);
+        return this.runBoundInteraction(callbackId, binding, payload.channel?.id, threadTs);
+    }
+    /**
+     * Route a Block Kit `block_actions` payload (a clicked button — typically on the
+     * App Home tab). Acts on the first action whose `action_id` is a bound Home
+     * button. A Home-tab click carries no channel, so the reply goes to the button's
+     * `channelId` (or the first allowlisted channel).
+     */
+    async handleBlockActions(payload) {
+        const actions = Array.isArray(payload.actions) ? payload.actions : [];
+        if (actions.length === 0) {
+            return { kind: "ignored", reason: "no_action" };
+        }
+        const action = actions.find((candidate) => typeof candidate.action_id === "string" && this.homeButtons.has(candidate.action_id));
+        if (action === undefined || typeof action.action_id !== "string") {
+            return { kind: "ignored", reason: "unbound" };
+        }
+        const actionId = action.action_id;
+        const binding = this.homeButtons.get(actionId);
+        if (binding === undefined) {
+            return { kind: "ignored", reason: "unbound", id: actionId };
+        }
+        const threadTs = firstNonEmpty(payload.message?.thread_ts, payload.message?.ts);
+        return this.runBoundInteraction(actionId, binding, payload.channel?.id, threadTs);
+    }
+    /**
+     * Shared interaction run path: resolve the destination channel, enforce the
+     * allowlist, post the optional instant ack, then run the bound prompt as a
+     * proactive turn. The returned result is for logging.
+     */
+    async runBoundInteraction(id, binding, payloadChannelId, payloadThreadTs) {
+        const channelId = firstNonEmpty(binding.channelId, payloadChannelId, this.defaultShortcutChannelId);
+        if (channelId === undefined) {
+            this.logger?.warn?.("Slack interaction has no destination channel; set channelId on the binding.", { id });
+            return { kind: "ignored", reason: "missing_channel", id };
+        }
+        if (!this.isAuthorized(channelId)) {
+            this.logger?.warn?.("Slack interaction targets an unauthorized channel; ignored.", { id, channelId });
+            return { kind: "unauthorized", id, channelId };
+        }
+        // A Slack `thread_ts` is channel-scoped, so only thread the reply when the
+        // destination IS the channel the interaction came from. A binding that pins a
+        // different channelId (or a global shortcut / Home-tab click with no source
+        // channel) posts top-level — otherwise a foreign thread_ts 404s the post.
+        const threadTs = channelId === payloadChannelId ? payloadThreadTs : undefined;
+        // Instant feedback: the result lands seconds later (and a global shortcut or a
+        // Home-tab click shows no on-click UI), so post the ack now (best-effort)
+        // before the run. The result follows as its own message in the same channel.
+        if (binding.ackText !== undefined) {
+            try {
+                await this.api.chatPostMessage({
+                    channel: channelId,
+                    text: binding.ackText,
+                    ...(threadTs === undefined ? {} : { thread_ts: threadTs }),
+                });
+            }
+            catch (error) {
+                this.logger?.warn?.("Slack interaction ack message failed (continuing with the run).", {
+                    id,
+                    error: error instanceof Error ? error.message : String(error),
+                });
+            }
+        }
+        const delivery = await this.notify(channelId, threadTs, binding.prompt);
+        const result = {
+            kind: "triggered",
+            id,
+            channelId,
+            delivered: delivery.delivered,
+        };
+        if (delivery.reason !== undefined) {
+            result.reason = delivery.reason;
+        }
+        return result;
+    }
+    /**
+     * Publish the App Home tab for a user when they open it. Best-effort: a publish
+     * failure is logged, not thrown, so opening Home never surfaces an error.
+     */
+    async handleAppHomeOpened(callback) {
+        const userId = callback.event.user;
+        if (!this.homeTabEnabled || typeof userId !== "string" || userId.length === 0) {
+            return { kind: "ignored", reason: "unsupported_event", eventId: callback.event_id };
+        }
+        if (typeof this.api.viewsPublish !== "function") {
+            this.logger?.warn?.("Home tab is enabled but the Slack client cannot publish views.");
+            return { kind: "ignored", reason: "unsupported_event", eventId: callback.event_id };
+        }
+        const blocks = this.buildHomeTabBlocks();
+        if (blocks.length === 0) {
+            // views.publish requires 1–100 blocks; an enabled-but-empty Home tab would
+            // error on every open. Skip the publish instead (config load also rejects
+            // this combination, so it should not happen in practice).
+            this.logger?.warn?.("Skipping App Home publish: the Home view has no blocks.");
+            return { kind: "ignored", reason: "unsupported_event", eventId: callback.event_id };
+        }
+        try {
+            await this.api.viewsPublish({ userId, view: { type: "home", blocks } });
+            return { kind: "home_published", eventId: callback.event_id, userId };
+        }
+        catch (error) {
+            this.logger?.error?.("Failed to publish the Slack App Home tab.", {
+                userId,
+                error: error instanceof Error ? error.message : String(error),
             });
-            return {
-                kind: "busy",
-                eventId: event.eventId,
-                channelId: event.channelId,
+            return { kind: "error", eventId: callback.event_id, error };
+        }
+    }
+    /** Build the App Home tab Block Kit: an optional header plus one button per configured Home button. */
+    buildHomeTabBlocks() {
+        const blocks = [];
+        if (this.homeTabHeaderText !== undefined && this.homeTabHeaderText.trim().length > 0) {
+            blocks.push({ type: "section", text: { type: "mrkdwn", text: this.homeTabHeaderText } });
+        }
+        const elements = this.homeButtonOrder.map((button) => ({
+            type: "button",
+            text: { type: "plain_text", text: button.label, emoji: true },
+            action_id: button.actionId,
+            value: button.actionId,
+        }));
+        if (elements.length > 0) {
+            blocks.push({ type: "actions", block_id: "home_actions", elements });
+        }
+        return blocks;
+    }
+    /**
+     * Build the stream options shared by both proactive delivery paths
+     * ({@link runProactiveTurn} and {@link runVerbatimDelivery}): a threaded post
+     * targets the existing thread; a top-level post records its ts → this
+     * conversation so a user's in-thread reply resolves back here.
+     */
+    buildProactiveStreamOptions(conversationId, channelId, threadTs, controller) {
+        const streamOptions = {
+            api: this.api,
+            channelId,
+            // No reactToTs: a proactive turn has no inbound message to react to.
+            finalOnly: this.streamOptions.finalOnly ?? true,
+            abortSignal: controller.signal,
+        };
+        if (threadTs !== undefined) {
+            streamOptions.threadTs = threadTs;
+        }
+        else if (this.recordPostedMessage !== undefined) {
+            // A top-level proactive post is a fresh thread root with no prior history.
+            // Record its ts → this conversation so a user's in-thread reply resolves
+            // back here (the threaded case already shares the thread's conversationId).
+            const record = this.recordPostedMessage;
+            let recorded = false;
+            streamOptions.onPosted = ({ ts, channel }) => {
+                if (recorded || ts.length === 0) {
+                    return;
+                }
+                recorded = true;
+                record(channel, ts, conversationId);
             };
         }
-        return await this.respondToEvent(event, text, runKey);
+        if (this.streamOptions.maxMessageChars !== undefined) {
+            streamOptions.maxMessageChars = this.streamOptions.maxMessageChars;
+        }
+        if (this.streamOptions.maxSendRetries !== undefined) {
+            streamOptions.maxSendRetries = this.streamOptions.maxSendRetries;
+        }
+        if (this.streamOptions.retryCapMs !== undefined) {
+            streamOptions.retryCapMs = this.streamOptions.retryCapMs;
+        }
+        if (this.streamOptions.retryBaseDelayMs !== undefined) {
+            streamOptions.retryBaseDelayMs = this.streamOptions.retryBaseDelayMs;
+        }
+        if (this.logger !== undefined) {
+            streamOptions.logger = this.logger;
+        }
+        return streamOptions;
     }
-    async respondToEvent(event, text, runKey) {
-        const controller = new AbortController();
-        const activeRun = { controller };
-        this.activeRuns.set(runKey, activeRun);
+    /**
+     * Deliver `text` VERBATIM to a Slack destination: post it unchanged through the
+     * normal stream with NO model call (the producing cron/webhook run already wrote
+     * the message), then record it to the destination's durable history via the
+     * responder so a later reply resumes with it in context. Best-effort: a
+     * history-record failure never fails an already-delivered post.
+     */
+    async runVerbatimDelivery(conversationId, channelId, threadTs, text, runKey, controller) {
+        const stream = new SlackMessageStream(this.buildProactiveStreamOptions(conversationId, channelId, threadTs, controller));
+        try {
+            if (controller.signal.aborted) {
+                return { delivered: false, reason: "cancelled" };
+            }
+            if (text.trim().length === 0) {
+                return { delivered: false, reason: "empty notification" };
+            }
+            try {
+                await stream.finish(text);
+            }
+            catch (error) {
+                if (controller.signal.aborted || isAgentResponseCancelledError(error)) {
+                    return { delivered: false, reason: "cancelled" };
+                }
+                this.logger?.error?.("Slack verbatim notify delivery failed.", {
+                    error: error instanceof Error ? error.message : String(error),
+                });
+                return { delivered: false, reason: "delivery failed" };
+            }
+            try {
+                await this.responder.deliverVerbatim?.(conversationId, text);
+            }
+            catch (error) {
+                this.logger?.warn?.("Slack verbatim notify history record failed.", {
+                    error: error instanceof Error ? error.message : String(error),
+                });
+            }
+            return { delivered: true };
+        }
+        finally {
+            this.unregisterController(runKey, controller);
+        }
+    }
+    async runProactiveTurn(conversationId, channelId, threadTs, text, runKey, controller) {
+        const stream = new SlackMessageStream(this.buildProactiveStreamOptions(conversationId, channelId, threadTs, controller));
+        try {
+            if (controller.signal.aborted) {
+                return { delivered: false, reason: "cancelled" };
+            }
+            const request = {
+                conversationId,
+                channelId,
+                messageTs: threadTs ?? "",
+                threadTs: threadTs ?? "",
+                eventId: "proactive",
+                text,
+                trigger: "direct",
+                abortSignal: controller.signal,
+                metadata: {
+                    slack: {
+                        eventId: "proactive",
+                        channel: { id: channelId },
+                        message: { ts: threadTs ?? "" },
+                        trigger: "direct",
+                    },
+                },
+            };
+            let response;
+            try {
+                response = await this.responder.respond(request, stream);
+            }
+            catch (error) {
+                if (controller.signal.aborted || isAgentResponseCancelledError(error)) {
+                    return { delivered: false, reason: "cancelled" };
+                }
+                this.logger?.error?.("Slack proactive notify failed.", {
+                    error: error instanceof Error ? error.message : String(error),
+                });
+                return { delivered: false, reason: "responder failed" };
+            }
+            const answer = response.text;
+            if (controller.signal.aborted) {
+                return { delivered: false, reason: "cancelled" };
+            }
+            if (answer === undefined || answer.trim().length === 0) {
+                return { delivered: false, reason: "agent produced no answer" };
+            }
+            try {
+                await stream.finish(answer);
+            }
+            catch (error) {
+                if (controller.signal.aborted || isAgentResponseCancelledError(error)) {
+                    return { delivered: false, reason: "cancelled" };
+                }
+                this.logger?.error?.("Slack proactive delivery failed after a successful AI run.", {
+                    error: error instanceof Error ? error.message : String(error),
+                });
+                return { delivered: false, reason: "delivery failed" };
+            }
+            return { delivered: true };
+        }
+        finally {
+            this.unregisterController(runKey, controller);
+        }
+    }
+    /**
+     * The conversation the run should continue. A genuine in-thread reply
+     * (`threadTs !== messageTs`) whose `(channel, threadTs)` matches a message we
+     * posted resolves to that producing conversation; everything else uses the
+     * default `slack:<channel>:<threadTs>`. Best-effort: a lookup error falls back.
+     */
+    async resolveConversationId(event) {
+        const fallback = conversationIdFor(event);
+        if (this.resolvePostIndex === undefined || event.threadTs === event.messageTs) {
+            return fallback;
+        }
+        try {
+            const producing = await this.resolvePostIndex(event.channelId, event.threadTs);
+            return producing !== undefined && producing.length > 0 ? producing : fallback;
+        }
+        catch {
+            return fallback;
+        }
+    }
+    async respondToEvent(event, text, runKey, controller, conversationId) {
         const streamOptions = {
             api: this.api,
             channelId: event.channelId,
             threadTs: event.threadTs,
+            reactToTs: event.messageTs,
+            // Default to a 👀 "seen" reaction + final-answer-only delivery (no streamed
+            // interim edits); a tuning override can restore interim streaming.
+            finalOnly: this.streamOptions.finalOnly ?? true,
+            abortSignal: controller.signal,
         };
         if (this.streamOptions.initialStatusText !== undefined) {
             streamOptions.initialStatusText = this.streamOptions.initialStatusText;
@@ -151,6 +677,18 @@ export class SlackAdapter {
         if (this.streamOptions.maxMessageChars !== undefined) {
             streamOptions.maxMessageChars = this.streamOptions.maxMessageChars;
         }
+        if (this.streamOptions.maxSendRetries !== undefined) {
+            streamOptions.maxSendRetries = this.streamOptions.maxSendRetries;
+        }
+        if (this.streamOptions.retryCapMs !== undefined) {
+            streamOptions.retryCapMs = this.streamOptions.retryCapMs;
+        }
+        if (this.streamOptions.retryBaseDelayMs !== undefined) {
+            streamOptions.retryBaseDelayMs = this.streamOptions.retryBaseDelayMs;
+        }
+        if (this.streamOptions.showHints !== undefined) {
+            streamOptions.showHints = this.streamOptions.showHints;
+        }
         if (this.logger !== undefined) {
             streamOptions.logger = this.logger;
         }
@@ -161,7 +699,20 @@ export class SlackAdapter {
                 await stream.finish(this.messages.cancelledText);
                 return { kind: "cancelled", eventId: event.eventId, channelId: event.channelId };
             }
-            const request = buildAgentRequest(event, text, controller.signal);
+            const attachments = await this.downloadAttachments(event.files, controller.signal);
+            if (controller.signal.aborted) {
+                await stream.finish(this.messages.cancelledText);
+                return { kind: "cancelled", eventId: event.eventId, channelId: event.channelId };
+            }
+            // A file-only message whose files were all skipped (MIME/size/missing
+            // URL/download failure) leaves no text and no attachments. Deliver a
+            // deterministic message instead of submitting an empty request the harness
+            // would reject.
+            if (text.length === 0 && attachments.length === 0) {
+                await stream.finish(this.messages.unsupportedText);
+                return { kind: "ignored", reason: "no_usable_attachments", eventId: event.eventId, channelId: event.channelId };
+            }
+            const request = buildAgentRequest(event, text, controller.signal, attachments, conversationId);
             const response = await this.responder.respond(request, stream);
             if (controller.signal.aborted) {
                 await stream.finish(this.messages.cancelledText);
@@ -192,9 +743,89 @@ export class SlackAdapter {
             return { kind: "error", eventId: event.eventId, channelId: event.channelId, error };
         }
         finally {
-            if (this.activeRuns.get(runKey) === activeRun) {
-                this.activeRuns.delete(runKey);
+            this.unregisterController(runKey, controller);
+        }
+    }
+    /**
+     * Download each inbound Slack file's bytes into an {@link AgentAttachment}.
+     * Files with a missing/disallowed mimetype, no private URL, or an advertised
+     * size over the cap are skipped before any network call. The byte cap is also
+     * enforced during the download. A failed download skips that file and
+     * continues; downloads are tied to the request abort signal.
+     */
+    async downloadAttachments(files, signal) {
+        const attachments = [];
+        // downloadFile is optional on SlackWebApi: a text-only custom client may omit
+        // it. Without it we cannot fetch bytes, so skip attachment download entirely.
+        if (typeof this.api.downloadFile !== "function") {
+            if (files.length > 0) {
+                this.logger?.debug?.("Slack client has no downloadFile; skipping attachments.", { count: files.length });
+            }
+            return attachments;
+        }
+        const downloadFile = this.api.downloadFile.bind(this.api);
+        for (const file of files) {
+            if (signal.aborted) {
+                break;
+            }
+            const mimeType = typeof file.mimetype === "string" ? file.mimetype : "";
+            if (mimeType.length === 0 || !this.allowedMimeTypes.has(mimeType.toLowerCase())) {
+                this.logger?.debug?.("Skipped Slack file with disallowed mimetype.", {
+                    id: file.id,
+                    mimeType,
+                });
+                continue;
+            }
+            if (typeof file.size === "number" && file.size > this.attachmentMaxBytes) {
+                this.logger?.debug?.("Skipped Slack file exceeding the byte cap.", {
+                    id: file.id,
+                    size: file.size,
+                });
+                continue;
+            }
+            const url = file.url_private ?? file.url_private_download;
+            if (typeof url !== "string" || url.length === 0) {
+                this.logger?.debug?.("Skipped Slack file without a private URL.", { id: file.id });
+                continue;
+            }
+            let bytes;
+            try {
+                bytes = await downloadFile({ url, maxBytes: this.attachmentMaxBytes }, { signal });
             }
+            catch (error) {
+                this.logger?.warn?.("Failed to download a Slack file (skipped).", {
+                    id: file.id,
+                    error: error instanceof Error ? error.message : String(error),
+                });
+                continue;
+            }
+            if (bytes.byteLength > this.attachmentMaxBytes) {
+                this.logger?.debug?.("Skipped Slack file exceeding the byte cap.", {
+                    id: file.id,
+                    size: bytes.byteLength,
+                });
+                continue;
+            }
+            attachments.push(buildAttachment(file, mimeType, bytes));
+        }
+        return attachments;
+    }
+    registerController(runKey, controller) {
+        let controllers = this.activeControllers.get(runKey);
+        if (controllers === undefined) {
+            controllers = new Set();
+            this.activeControllers.set(runKey, controllers);
+        }
+        controllers.add(controller);
+    }
+    unregisterController(runKey, controller) {
+        const controllers = this.activeControllers.get(runKey);
+        if (controllers === undefined) {
+            return;
+        }
+        controllers.delete(controller);
+        if (controllers.size === 0) {
+            this.activeControllers.delete(runKey);
         }
     }
     normalizeEventCallback(callback) {
@@ -210,16 +841,19 @@ export class SlackAdapter {
         if (rawEvent.user !== undefined && this.botUserIds.has(normalizeIdForMatch(rawEvent.user))) {
             return ignored("from_self", callback, rawEvent);
         }
-        if (rawEvent.subtype !== undefined) {
+        if (rawEvent.subtype !== undefined && !FILE_BEARING_MESSAGE_SUBTYPES.has(rawEvent.subtype)) {
             return ignored("unsupported_message", callback, rawEvent);
         }
         if (eventType === "message" &&
             rawEvent.channel_type !== "im") {
             return ignored("unsupported_event", callback, rawEvent);
         }
+        // A file upload may arrive with no caption (text absent/empty); accept it as
+        // long as it carries files so the attachment is not dropped.
+        const hasFiles = Array.isArray(rawEvent.files) && rawEvent.files.length > 0;
         if (typeof rawEvent.channel !== "string" ||
             typeof rawEvent.ts !== "string" ||
-            typeof rawEvent.text !== "string") {
+            (typeof rawEvent.text !== "string" && !hasFiles)) {
             return ignored("unsupported_message", callback, rawEvent);
         }
         const threadTs = typeof rawEvent.thread_ts === "string" && rawEvent.thread_ts.trim().length > 0
@@ -228,10 +862,11 @@ export class SlackAdapter {
         const event = {
             eventId: callback.event_id,
             channelId: rawEvent.channel,
-            text: this.prepareText(rawEvent.text),
+            text: this.prepareText(typeof rawEvent.text === "string" ? rawEvent.text : ""),
             messageTs: rawEvent.ts,
             threadTs,
             trigger,
+            files: Array.isArray(rawEvent.files) ? rawEvent.files : [],
         };
         if (callback.team_id !== undefined) {
             event.teamId = callback.team_id;
@@ -293,7 +928,7 @@ function ignored(reason, callback, event) {
     }
     return result;
 }
-function buildAgentRequest(event, text, abortSignal) {
+function buildAgentRequest(event, text, abortSignal, attachments, conversationId) {
     const metadata = {
         eventId: event.eventId,
         channel: {
@@ -326,7 +961,7 @@ function buildAgentRequest(event, text, abortSignal) {
         metadata.user = { id: event.userId };
     }
     const request = {
-        conversationId: `slack:${event.channelId}:${event.threadTs}`,
+        conversationId,
         channelId: event.channelId,
         messageTs: event.messageTs,
         threadTs: event.threadTs,
@@ -342,8 +977,36 @@ function buildAgentRequest(event, text, abortSignal) {
     if (event.userId !== undefined) {
         request.userId = event.userId;
     }
+    if (attachments.length > 0) {
+        request.attachments = attachments;
+    }
     return request;
 }
+const TEXT_MIME_PATTERN = /^text\/|[/+](?:json|xml|csv)$/iu;
+/** Build an {@link AgentAttachment} from downloaded Slack file bytes. */
+function buildAttachment(file, mimeType, bytes) {
+    const attachment = {
+        kind: mimeType.toLowerCase().startsWith("image/") ? "image" : "document",
+        mimeType,
+        data: toBase64(bytes),
+        sizeBytes: bytes.byteLength,
+    };
+    const name = typeof file.name === "string" && file.name.length > 0
+        ? file.name
+        : typeof file.title === "string" && file.title.length > 0
+            ? file.title
+            : undefined;
+    if (name !== undefined) {
+        attachment.name = name;
+    }
+    if (TEXT_MIME_PATTERN.test(mimeType)) {
+        attachment.text = new TextDecoder("utf-8").decode(bytes);
+    }
+    return attachment;
+}
+function toBase64(bytes) {
+    return Buffer.from(bytes.buffer, bytes.byteOffset, bytes.byteLength).toString("base64");
+}
 function parseCommand(text) {
     const match = text.match(/^\/([A-Za-z0-9_]+)(?:\s|$)/u);
     if (match?.[1] === undefined) {
@@ -364,7 +1027,23 @@ async function finishSafely(stream, text, logger) {
 function runKeyFor(event) {
     return `${event.channelId}:${event.threadTs}`;
 }
+/**
+ * The conversation key the harness serializes runs on. /cancel uses the same id
+ * so the responder clears the right conversation's queued follow-ups.
+ */
+function conversationIdFor(event) {
+    return `slack:${event.channelId}:${event.threadTs}`;
+}
 function normalizeIdForMatch(value) {
     return value.trim().toLowerCase();
 }
+/** First argument that is a non-blank string, else undefined. */
+function firstNonEmpty(...values) {
+    for (const value of values) {
+        if (typeof value === "string" && value.trim().length > 0) {
+            return value;
+        }
+    }
+    return undefined;
+}
 //# sourceMappingURL=adapter.js.map