@mono-agent/slack-adapter 0.2.2 → 0.4.0

package/README.md

@@ -20,6 +20,17 @@ Adapter settings can be loaded from nested JSON under `slack` or explicit enviro
 
 The adapter is opt-in: `slack.enabled` / `MONO_AGENT_SLACK_ENABLED` defaults to `false`. While disabled the loader skips token validation and the channel reports `disabled` rather than `waiting_for_config`. Set `enabled: true` to turn it on; missing tokens or allowlist then surface as a real `waiting_for_config` reason.
 
+## Activity indicator (assistant status / 👀)
+
+While the agent works, the message stream surfaces progress in the thread. It
+prefers Slack's official assistant-thread status — `assistant.threads.setStatus`
+("App is _thinking…_"), which Slack auto-clears when the next message posts — and
+falls back to a 👀 "seen" reaction on the triggering message. The status path only
+applies inside a Slack **AI-assistant thread** and requires the app to have the
+**Agents & AI Apps** feature enabled plus the **`assistant:write`** scope; in
+regular channels/DMs (or without the scope) the call errors and the adapter uses
+the reaction instead — no configuration needed for the fallback.
+
 ## Public API
 
 - `slackFieldGroup`

package/dist/adapter.d.ts

@@ -1,4 +1,4 @@
-import { type AgentRequestBase, type AgentResponder as SharedAgentResponder, type AgentResponse } from "@mono-agent/agent-contracts";
+import { type AgentAttachment, type AgentRequestBase, type AgentResponder as SharedAgentResponder, type AgentResponse } from "@mono-agent/agent-contracts";
 import { type AgentMessageStream, type SlackMessageStreamLogger } from "./message-stream.js";
 import type { SlackChannelId, SlackEventCallback, SlackMessageTs, SlackUserId, SlackWebApi } from "./types.js";
 export type SlackTriggerKind = "direct" | "app_mention";
@@ -13,11 +13,25 @@ export interface AgentRequest extends AgentRequestBase {
     text: string;
     trigger: SlackTriggerKind;
     abortSignal: AbortSignal;
+    attachments?: readonly AgentAttachment[];
     metadata: {
         slack: SlackRequestMetadata;
         [key: string]: unknown;
     };
 }
+/** Tunes how inbound Slack file attachments are downloaded. */
+export interface SlackAttachmentOptions {
+    /**
+     * Maximum decoded bytes to accept per file. Files whose advertised size
+     * exceeds this — or whose download exceeds it — are skipped. Default 10 MiB.
+     */
+    maxBytes?: number;
+    /**
+     * Allowed file mimetypes. A file whose mimetype is not listed is skipped.
+     * Defaults to a conservative allowlist of common image and document types.
+     */
+    allowedMimeTypes?: readonly string[];
+}
 export interface SlackRequestMetadata {
     teamId?: string;
     apiAppId?: string;
@@ -52,6 +66,15 @@ export interface SlackAdapterStreamOptions {
     initialStatusText?: string;
     editDebounceMs?: number;
     maxMessageChars?: number;
+    maxSendRetries?: number;
+    retryCapMs?: number;
+    retryBaseDelayMs?: number;
+    showHints?: boolean;
+    /**
+     * Deliver only the final answer with a 👀 "seen" reaction while working,
+     * instead of streaming interim edits. Defaults to true for the Slack adapter.
+     */
+    finalOnly?: boolean;
 }
 export interface SlackAdapterLogger extends SlackMessageStreamLogger {
     debug?(message: string, metadata?: Record<string, unknown>): void;
@@ -67,9 +90,10 @@ export interface SlackAdapterOptions {
     stripMentionText?: boolean;
     stream?: SlackAdapterStreamOptions;
     messages?: SlackAdapterMessages;
+    attachments?: SlackAttachmentOptions;
     logger?: SlackAdapterLogger;
 }
-export type SlackEventIgnoredReason = "unsupported_event" | "unsupported_message" | "empty_text" | "from_bot" | "from_self";
+export type SlackEventIgnoredReason = "unsupported_event" | "unsupported_message" | "empty_text" | "no_usable_attachments" | "from_bot" | "from_self";
 export type SlackEventHandlingResult = {
     kind: "handled";
     eventId: string;
@@ -101,6 +125,34 @@ export type SlackEventHandlingResult = {
     channelId?: SlackChannelId;
     error: unknown;
 };
+/**
+ * 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 declare class SerialQueueFullError extends Error {
+    readonly code: "serial_queue_full";
+    constructor(maxDepth: number);
+}
+/**
+ * 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 declare class SerialQueue {
+    private tail;
+    private depth;
+    private readonly maxDepth;
+    constructor(maxDepth?: number);
+    run<T>(task: () => Promise<T>): Promise<T>;
+    /** True when no task is queued or running. */
+    get idle(): boolean;
+}
 export declare class SlackAdapter {
     private readonly api;
     private readonly responder;
@@ -112,11 +164,38 @@ export declare class SlackAdapter {
     private readonly stripMentionText;
     private readonly streamOptions;
     private readonly messages;
+    private readonly attachmentMaxBytes;
+    private readonly allowedMimeTypes;
     private readonly logger;
-    private readonly activeRuns;
+    /**
+     * 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).
+     */
+    private readonly activeControllers;
+    /**
+     * 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).
+     */
+    private readonly admissionQueues;
     constructor(options: SlackAdapterOptions);
     handleEventCallback(callback: SlackEventCallback): Promise<SlackEventHandlingResult>;
     private respondToEvent;
+    /**
+     * 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.
+     */
+    private downloadAttachments;
+    private registerController;
+    private unregisterController;
     private normalizeEventCallback;
     private prepareText;
     private isAuthorized;

package/dist/adapter.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"adapter.d.ts","sourceRoot":"","sources":["../src/adapter.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"adapter.d.ts","sourceRoot":"","sources":["../src/adapter.ts"],"names":[],"mappings":"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"}

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,25 @@ export class SlackAdapter {
     stripMentionText;
     streamOptions;
     messages;
+    attachmentMaxBytes;
+    allowedMimeTypes;
     logger;
-    activeRuns = new Map();
+    /**
+     * 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,6 +123,8 @@ 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.logger = options.logger;
         if (!this.allowAllChannels && this.allowedChannelIds.size === 0) {
             throw new TypeError("SlackAdapter requires allowedChannelIds or allowAllChannels: true.");
@@ -58,7 +149,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 +194,15 @@ export class SlackAdapter {
             };
         }
         const runKey = runKeyFor(event);
-        const activeRun = this.activeRuns.get(runKey);
         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?.(conversationIdFor(event), 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 +215,58 @@ export class SlackAdapter {
                 channelId: event.channelId,
             };
         }
-        if (activeRun !== undefined) {
-            await this.api.chatPostMessage({
-                channel: event.channelId,
-                text: this.messages.busyText,
-                thread_ts: event.threadTs,
-            });
-            return {
-                kind: "busy",
-                eventId: event.eventId,
-                channelId: event.channelId,
-            };
+        // 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.
+        const conversationId = conversationIdFor(event);
+        // 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));
+        }
+        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);
+            }
         }
-        return await this.respondToEvent(event, text, runKey);
     }
-    async respondToEvent(event, text, runKey) {
-        const controller = new AbortController();
-        const activeRun = { controller };
-        this.activeRuns.set(runKey, activeRun);
+    async respondToEvent(event, text, runKey, controller) {
         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 +277,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 +299,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);
             const response = await this.responder.respond(request, stream);
             if (controller.signal.aborted) {
                 await stream.finish(this.messages.cancelledText);
@@ -192,9 +343,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 +441,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 +462,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 +528,7 @@ function ignored(reason, callback, event) {
     }
     return result;
 }
-function buildAgentRequest(event, text, abortSignal) {
+function buildAgentRequest(event, text, abortSignal, attachments) {
     const metadata = {
         eventId: event.eventId,
         channel: {
@@ -326,7 +561,7 @@ function buildAgentRequest(event, text, abortSignal) {
         metadata.user = { id: event.userId };
     }
     const request = {
-        conversationId: `slack:${event.channelId}:${event.threadTs}`,
+        conversationId: conversationIdFor(event),
         channelId: event.channelId,
         messageTs: event.messageTs,
         threadTs: event.threadTs,
@@ -342,8 +577,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,6 +627,13 @@ 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();
 }