@fastagent-sh/fastagent 0.28.0 → 0.30.0

package/dist/channels/slack/slack.js

@@ -1,4 +1,8 @@
-/** First-party Slack HTTP Events API channel: signed ingress, durable turns/context, files, and edited previews. */
+/**
+ * First-party Slack channel: durable turns/context, files, and edited previews, over one runtime, with two ways in: the
+ * Events API's signed HTTP Request URL, and Socket Mode (socket.ts).
+ */
+import { recordReached } from "../webhook-evidence.js";
 import { createHmac } from "node:crypto";
 import { join } from "node:path";
 import { log } from "../../log.js";
@@ -21,6 +25,7 @@ import { createTurnStore } from "../kit/turn-store.js";
 import { discussionBlock } from "../kit/context-buffer.js";
 import { collectFoldedFiles, createSlackPlaceHistory, slackHistoryKey, slackPlaceOf, } from "./history.js";
 import { slackTurnStream } from "./invoke-turn.js";
+import { connectSlackSocket } from "./socket.js";
 import { defaultSlackRoute, isSlackDirectMessage, isSlackGroupMessage, hasSlackMention, isSlackHumanMessage, mentionsSlackUser, stripSlackMentions, slackEnvelope, slackFileIds, slackMessageText, slackTeamId, } from "./parse.js";
 import { defaultErrorMessage, deliverSlackAnswer, settleSlackPreview, slackReply, } from "./preview.js";
 import { completeSlackReaction, resolveReactionEmojis, startSlackReaction } from "./reaction.js";
@@ -109,351 +114,379 @@ function createSlackAuthentication(api, label) {
             }),
     };
 }
-export function slackChannel(options) {
-    const { botToken, signingSecret, rendering = "native", aiDisclaimer, welcome = DEFAULT_WELCOME, reactionAck = {}, route, onError, apiBaseUrl = "https://slack.com/api", } = options;
+/** The policy as the runtime reads it: defaults applied and what can be refused refused, at construction. */
+function resolveSlackPolicy(options) {
+    const { rendering = "native", welcome = DEFAULT_WELCOME, reactionAck = {} } = options;
     if (!["native", "classic"].includes(rendering)) {
         throw new Error('slackChannel rendering must be "native" or "classic"');
     }
     if (welcome !== false && typeof welcome !== "string") {
         throw new Error("slackChannel welcome must be a string or false");
     }
-    const reactionEmojis = resolveReactionEmojis(reactionAck);
-    return ({ agent, sessionFor, recordedSession, stateDir: stateHome }) => {
-        if (!botToken)
-            throw new Error("slackChannel requires a non-empty botToken (Bot User OAuth Token)");
-        if (!signingSecret)
-            throw new Error("slackChannel requires a non-empty signingSecret (Basic Information → App Credentials)");
-        const label = "[slack]";
-        const formatError = onError ?? defaultErrorMessage;
-        const api = createSlackApi({ botToken, baseUrl: apiBaseUrl });
-        registerSlackApi(botToken, api); // the send tool delivers through this one (shared-api.ts)
-        const auth = createSlackAuthentication(api, label);
-        // Side tasks (stop feedback, DM welcomes) run off the ACK path but drain in turnsIdle.
-        const sideTasks = createTaskTracker(label);
-        const seen = createSeenRing(join(stateHome, "seen.json"), label);
-        const threadParticipants = createThreadParticipants(join(stateHome, "thread-participants.json"), label);
-        /**
-         * A thread's participation is keyed by the CONVERSATION it describes — "the agent answered here" is a claim about
-         * a memory, so the two must not be re-keyable independently.
-         */
-        const threadKey = (teamId, channelId, threadTs) => `${teamId}:${channelId}:${threadTs}`;
-        const welcomed = createWelcomedUsers(join(stateHome, "welcomed.json"), label);
-        // Every message this channel took as input (a turn, a /stop) is in `seen`. A history read also leaves these out,
-        // to shape the prompt only — what keeps a queued ask out of an earlier turn is the read's bound, not this ring.
-        const history = createSlackPlaceHistory({
-            api,
-            self: () => ({ userId: auth.botUserId(), botId: auth.botId() }),
-            label,
-            path: join(stateHome, "history.json"),
-            isTurnInput: (key, ts) => {
-                const place = slackPlaceOf(key);
-                return seen.has(`${place.teamId}:${place.channelId}:${ts}`);
-            },
-        });
-        // A group turn's room, for the thread-reading tool (`slackThreads`): the channel it was asked in, and its threads.
-        const rooms = createRoomThreads({
-            list: (room) => history.threads(room),
-            read: async (room, threadTs) => {
-                if (!/^\d+\.\d+$/.test(threadTs)) {
-                    throw new Error(`"${threadTs}" is not a Slack thread id: pass a thread's id from the list (like 1712345678.123456)`);
-                }
-                const { teamId, channelId } = slackPlaceOf(room);
-                const key = slackHistoryKey(teamId, { channelId, threadTs });
-                return (await history.snapshot(key)).text || `(thread ${threadTs} shows no messages)`;
-            },
-        });
-        registerRoomThreads("slack", stateHome, rooms);
-        /**
-         * The client a turn posts through: what it posts (answer, queue notice, stop feedback) is in the session already,
-         * so the place it LANDS in records it, and that place's next read leaves it out — an answer to a channel's
-         * top-level ask lands in the thread it opens. The send tool uses the plain client, so what the agent posts itself
-         * stays discussion. A routed turn has no place and reads no history.
-         */
-        const placeApi = (turn) => turn.historyKey === undefined
-            ? api
-            : api.recordingSends((where, ts) => history.recordOutput(slackHistoryKey(turn.teamId, where), ts));
-        const store = createTurnStore(join(stateHome, "turns.json"), {
-            label,
-            isRecord: isStoredSlackTurn,
-            order: (a, b) => a.seq - b.seq,
-        });
-        const decide = route ?? defaultSlackRoute;
-        /** A channel turn under the default routing reads its channel's threads; a DM has none to read. */
-        const enterRoom = (turn) => {
-            if (!turn.group || turn.historyKey === undefined)
-                return {};
-            const { teamId, channelId } = slackPlaceOf(turn.historyKey);
-            const room = slackHistoryKey(teamId, { channelId });
-            return { enter: (sessionId) => rooms.enter(sessionId, room) };
-        };
-        const targetOf = (turn) => ({
-            channelId: turn.channelId,
-            threadTs: turn.threadTs,
-            recipientUserId: turn.requesterUserId,
-            recipientTeamId: turn.teamId,
-        });
-        const notifyDropped = (turn) => {
-            const target = targetOf(turn);
-            if (turn.nativeQueueStatus)
-                void api.setThreadStatus(target, "").catch(() => { });
-            void settleSlackPreview(placeApi(turn), target, turn.previewTs, "⚠️ I couldn’t complete an earlier request — please ask again.").catch((error) => log.warn(`${label} could not notify a dropped turn: ${String(error)}`));
-        };
-        const runner = createTurnRunner({
-            label,
-            store,
-            discussion: history,
-            seen,
-            toStored: ({ previewTs: _preview, nativeQueueStatus: _status, ...intent }) => ({ ...intent, attempts: 0 }),
-            fromStored: ({ attempts: _attempts, ...intent }) => ({ ...intent }),
-            // The read ends at the ask (`messageRefOf`: the ts of the message that asked).
-            discussionKey: (turn) => {
-                const ask = messageRefOf(turn.id);
-                return turn.historyKey === undefined || ask === undefined ? undefined : { key: turn.historyKey, until: ask.ts };
-            },
-            where: (turn) => `channel=${turn.channelId}`,
-            onQueuedBehind(turn) {
-                const nativeDmStatus = rendering === "native" && turn.threadTs && turn.channelId.startsWith("D");
-                if (nativeDmStatus)
-                    turn.nativeQueueStatus = true;
-                return {
-                    done: auth.settled
-                        .then(() => nativeDmStatus
-                        ? api.setThreadStatus(targetOf(turn), "is queued behind an earlier request…")
-                        : placeApi(turn)
-                            .postMessage(targetOf(turn), QUEUED_PLACEHOLDER)
-                            .then((ts) => {
-                            turn.previewTs = ts;
-                        }))
-                        .catch((error) => log.warn(`${label} queue preview failed (the turn stays durable): ${String(error)}`)),
-                };
-            },
-            // Leave the intent untouched when Slack auth failed.
-            beforeRun: async (turn) => {
-                try {
-                    await auth.settled;
-                    return true;
-                }
-                catch (error) {
-                    log.error(`${label} deferring durable turn ${turn.id} because Slack authentication failed: ${String(error)}`);
-                    return false;
-                }
-            },
-            onDeferred: (turn) => {
-                if (turn.nativeQueueStatus) {
-                    void api
-                        .setThreadStatus(targetOf(turn), "is delayed by a temporary system issue and will retry after restart…")
-                        .catch((error) => log.warn(`${label} could not update a deferred Agent status: ${String(error)}`));
-                }
-                else if (turn.previewTs) {
-                    void settleSlackPreview(placeApi(turn), targetOf(turn), turn.previewTs, DEFERRED_PLACEHOLDER).catch((error) => log.warn(`${label} could not update a deferred queue preview: ${String(error)}`));
-                }
-            },
-            notifyDropped,
-            deliverAnswer: (turn, answer) => portJoin(async () => {
-                // A queue notice THIS process put up outlives the run the answer came from, so it is settled here as it
-                // would be by a turn that ran: the status line cleared, the compatibility message taken over.
-                if (turn.nativeQueueStatus) {
-                    await api
-                        .setThreadStatus(targetOf(turn), "")
-                        .catch((error) => log.warn(`${label} could not clear a queued Agent status: ${String(error)}`));
-                }
-                await deliverSlackAnswer(placeApi(turn), targetOf(turn), answer, turn.previewTs);
-                // The 👀 on the asker's message was added by the run that produced this answer, and `execute`'s
-                // acquire/release — the only thing that turns it into ✅ — is not on this path.
-                const messageRef = messageRefOf(turn.id);
-                if (reactionEmojis && messageRef) {
-                    await completeSlackReaction({
-                        api,
-                        channelId: messageRef.channelId,
-                        ts: messageRef.ts,
-                        emojis: reactionEmojis,
-                        label,
-                    });
-                }
-            }),
-            execute: (turn, discussion, onAnswered) => {
-                const messageRef = messageRefOf(turn.id);
-                return Effect.acquireUseRelease(portJoin(async () => reactionEmojis && messageRef
-                    ? startSlackReaction({
-                        api,
-                        channelId: messageRef.channelId,
-                        ts: messageRef.ts,
-                        emojis: reactionEmojis,
-                        label,
-                    })
-                    : undefined), () => Effect.scoped(slackReply(slackTurnStream(agent, {
-                    session: () => sessionFor(turn.conversation),
-                    ...enterRoom(turn),
-                    key: turn.id,
-                    text: `${discussionBlock(discussion.text)}${turn.baseText}`,
-                }, { api, channelId: turn.channelId, filesDir: attachmentsDir(stateHome), label }, {
-                    primaryFileIds: turn.fileIds,
-                    buffered: collectFoldedFiles(discussion.consumed.flatMap((read) => read.folded), new Set(turn.fileIds)),
-                }), placeApi(turn), targetOf(turn), formatError, {
-                    rendering,
-                    initialPreviewTs: turn.previewTs,
-                    threadTitle: turn.threadTitle,
-                    disclaimer: aiDisclaimer,
-                    label,
-                    onAnswered,
-                })), (reaction, exit) => portJoin(async () => {
-                    if (Exit.isSuccess(exit))
-                        await reaction?.complete();
-                    else
-                        await reaction?.remove();
-                }).pipe(
-                // A release does not fail: its defect would make the turn's typed failure one too. Unreachable while
-                // the reaction's `complete` and `remove` catch their own failures (reaction.ts).
-                Effect.catchTag("PortFailure", (error) => Effect.sync(() => log.warn(`${label} could not settle the Slack reaction: ${String(error.cause)}`)))));
-            },
-        });
-        let seq = runner.recover().reduce((maximum, turn) => Math.max(maximum, turn.seq), 0);
-        // Acceptance touches no network, so it stays synchronous inside Slack's ACK window and the delivery dedup ring
-        // alone is enough.
-        const acceptEvent = (envelope) => {
-            const event = envelope.event;
-            if (!isSlackHumanMessage(event))
-                return;
-            const botUserId = auth.botUserId();
-            if (botUserId && event.user === botUserId)
-                return;
-            const teamId = slackTeamId(envelope) ?? auth.teamId();
-            if (!teamId) {
-                log.warn(`${label} ignored message ${event.ts}: event carried no workspace/enterprise identity`);
-                return;
+    return {
+        botToken: options.botToken,
+        rendering,
+        welcome,
+        reactionEmojis: resolveReactionEmojis(reactionAck),
+        aiDisclaimer: options.aiDisclaimer,
+        route: options.route,
+        onError: options.onError,
+        apiBaseUrl: options.apiBaseUrl ?? "https://slack.com/api",
+    };
+}
+function createSlackRuntime(policy, { agent, sessionFor, recordedSession, stateDir: stateHome }) {
+    const { botToken, rendering, welcome, reactionEmojis, aiDisclaimer, route, onError, apiBaseUrl } = policy;
+    if (!botToken)
+        throw new Error("slackChannel requires a non-empty botToken (Bot User OAuth Token)");
+    const label = "[slack]";
+    const formatError = onError ?? defaultErrorMessage;
+    const api = createSlackApi({ botToken, baseUrl: apiBaseUrl });
+    registerSlackApi(botToken, api); // the send tool delivers through this one (shared-api.ts)
+    const auth = createSlackAuthentication(api, label);
+    // Side tasks (stop feedback, DM welcomes) run off the ACK path but drain in turnsIdle.
+    const sideTasks = createTaskTracker(label);
+    const seen = createSeenRing(join(stateHome, "seen.json"), label);
+    const threadParticipants = createThreadParticipants(join(stateHome, "thread-participants.json"), label);
+    /**
+     * A thread's participation is keyed by the CONVERSATION it describes — "the agent answered here" is a claim about
+     * a memory, so the two must not be re-keyable independently.
+     */
+    const threadKey = (teamId, channelId, threadTs) => `${teamId}:${channelId}:${threadTs}`;
+    const welcomed = createWelcomedUsers(join(stateHome, "welcomed.json"), label);
+    // Every message this channel took as input (a turn, a /stop) is in `seen`. A history read also leaves these out,
+    // to shape the prompt only — what keeps a queued ask out of an earlier turn is the read's bound, not this ring.
+    const history = createSlackPlaceHistory({
+        api,
+        self: () => ({ userId: auth.botUserId(), botId: auth.botId() }),
+        label,
+        path: join(stateHome, "history.json"),
+        isTurnInput: (key, ts) => {
+            const place = slackPlaceOf(key);
+            return seen.has(`${place.teamId}:${place.channelId}:${ts}`);
+        },
+    });
+    // A group turn's room, for the thread-reading tool (`slackThreads`): the channel it was asked in, and its threads.
+    const rooms = createRoomThreads({
+        list: (room) => history.threads(room),
+        read: async (room, threadTs) => {
+            if (!/^\d+\.\d+$/.test(threadTs)) {
+                throw new Error(`"${threadTs}" is not a Slack thread id: pass a thread's id from the list (like 1712345678.123456)`);
             }
-            const logicalId = `${teamId}:${event.channel}:${event.ts}`;
-            if (seen.has(logicalId)) {
-                log.debug(`${label} duplicate logical message ${logicalId} — skipping`);
-                return;
+            const { teamId, channelId } = slackPlaceOf(room);
+            const key = slackHistoryKey(teamId, { channelId, threadTs });
+            return (await history.snapshot(key)).text || `(thread ${threadTs} shows no messages)`;
+        },
+    });
+    registerRoomThreads("slack", stateHome, rooms);
+    /**
+     * The client a turn posts through: what it posts (answer, queue notice, stop feedback) is in the session already,
+     * so the place it LANDS in records it, and that place's next read leaves it out — an answer to a channel's
+     * top-level ask lands in the thread it opens. The send tool uses the plain client, so what the agent posts itself
+     * stays discussion. A routed turn has no place and reads no history.
+     */
+    const placeApi = (turn) => turn.historyKey === undefined
+        ? api
+        : api.recordingSends((where, ts) => history.recordOutput(slackHistoryKey(turn.teamId, where), ts));
+    const store = createTurnStore(join(stateHome, "turns.json"), {
+        label,
+        isRecord: isStoredSlackTurn,
+        order: (a, b) => a.seq - b.seq,
+    });
+    const decide = route ?? defaultSlackRoute;
+    /** A channel turn under the default routing reads its channel's threads; a DM has none to read. */
+    const enterRoom = (turn) => {
+        if (!turn.group || turn.historyKey === undefined)
+            return {};
+        const { teamId, channelId } = slackPlaceOf(turn.historyKey);
+        const room = slackHistoryKey(teamId, { channelId });
+        return { enter: (sessionId) => rooms.enter(sessionId, room) };
+    };
+    const targetOf = (turn) => ({
+        channelId: turn.channelId,
+        threadTs: turn.threadTs,
+        recipientUserId: turn.requesterUserId,
+        recipientTeamId: turn.teamId,
+    });
+    const notifyDropped = (turn) => {
+        const target = targetOf(turn);
+        if (turn.nativeQueueStatus)
+            void api.setThreadStatus(target, "").catch(() => { });
+        void settleSlackPreview(placeApi(turn), target, turn.previewTs, "⚠️ I couldn’t complete an earlier request — please ask again.").catch((error) => log.warn(`${label} could not notify a dropped turn: ${String(error)}`));
+    };
+    const runner = createTurnRunner({
+        label,
+        store,
+        discussion: history,
+        seen,
+        toStored: ({ previewTs: _preview, nativeQueueStatus: _status, ...intent }) => ({ ...intent, attempts: 0 }),
+        fromStored: ({ attempts: _attempts, ...intent }) => ({ ...intent }),
+        // The read ends at the ask (`messageRefOf`: the ts of the message that asked).
+        discussionKey: (turn) => {
+            const ask = messageRefOf(turn.id);
+            return turn.historyKey === undefined || ask === undefined ? undefined : { key: turn.historyKey, until: ask.ts };
+        },
+        where: (turn) => `channel=${turn.channelId}`,
+        onQueuedBehind(turn) {
+            const nativeDmStatus = rendering === "native" && turn.threadTs && turn.channelId.startsWith("D");
+            if (nativeDmStatus)
+                turn.nativeQueueStatus = true;
+            return {
+                done: auth.settled
+                    .then(() => nativeDmStatus
+                    ? api.setThreadStatus(targetOf(turn), "is queued behind an earlier request…")
+                    : placeApi(turn)
+                        .postMessage(targetOf(turn), QUEUED_PLACEHOLDER)
+                        .then((ts) => {
+                        turn.previewTs = ts;
+                    }))
+                    .catch((error) => log.warn(`${label} queue preview failed (the turn stays durable): ${String(error)}`)),
+            };
+        },
+        // Leave the intent untouched when Slack auth failed.
+        beforeRun: async (turn) => {
+            try {
+                await auth.settled;
+                return true;
             }
-            const group = isSlackGroupMessage(event);
-            const direct = isSlackDirectMessage(event);
-            const rootTs = event.thread_ts ?? event.ts;
-            // Listening is not speaking: every message the channel can see refines who takes part in its thread, whether or
-            // not it is answered.
-            if (group && event.thread_ts !== undefined) {
-                threadParticipants.merge(threadKey(teamId, event.channel, event.thread_ts), { humans: [event.user] });
+            catch (error) {
+                log.error(`${label} deferring durable turn ${turn.id} because Slack authentication failed: ${String(error)}`);
+                return false;
             }
-            let routed = decide(envelope);
-            const addressesSomeone = hasSlackMention(event.text ?? "");
-            const structurallyMentionsBot = botUserId !== undefined && mentionsSlackUser(event.text ?? "", botUserId);
-            // app_mention and message.* subscriptions can overlap.
-            if (!routed && route === undefined && group && event.type === "message" && structurallyMentionsBot)
-                routed = {};
-            // The participant model's thread rule (§3): a bare message reaches the agent while it takes part and has not
-            // heard a second human.
-            if (!routed &&
-                route === undefined &&
-                group &&
-                event.thread_ts !== undefined &&
-                event.type !== "app_mention" &&
-                // Mentioning only other people is targeted discussion, never an ask (§3) — the same guard Feishu applies with
-                // `hasMentions`.
-                !addressesSomeone &&
-                threadParticipants.admitsBareMessage(threadKey(teamId, event.channel, event.thread_ts))) {
-                routed = {};
+        },
+        onDeferred: (turn) => {
+            if (turn.nativeQueueStatus) {
+                void api
+                    .setThreadStatus(targetOf(turn), "is delayed by a temporary system issue and will retry after restart…")
+                    .catch((error) => log.warn(`${label} could not update a deferred Agent status: ${String(error)}`));
             }
-            if (!routed) {
-                // Not lost: the turn that is summoned here reads it from the place's history.
-                log.debug(`${label} not summoned — message ${logicalId}`);
-                return;
+            else if (turn.previewTs) {
+                void settleSlackPreview(placeApi(turn), targetOf(turn), turn.previewTs, DEFERRED_PLACEHOLDER).catch((error) => log.warn(`${label} could not update a deferred queue preview: ${String(error)}`));
             }
-            const targetChannel = routed.channelId ?? event.channel;
-            const sameChannel = targetChannel === event.channel;
-            // Answer where asked (participant model §4).
-            const defaultThread = event.thread_ts ?? event.ts;
-            const threadTs = routed.threadTs === null ? undefined : (routed.threadTs ?? (sameChannel ? defaultThread : undefined));
-            const defaultConversation = threadKey(teamId, event.channel, rootTs);
-            // Every place's discussion under the default routing, a DM's too (what a send tool posted there is in no session);
-            // a routed session's place is the router's to decide.
-            const historyKey = route === undefined && (group || direct)
-                ? slackHistoryKey(teamId, { channelId: event.channel, threadTs: event.thread_ts })
-                : undefined;
-            // Explicit user stop: a control action, never a turn — it must not queue behind the run it stops.
-            if (isStopText(stripSlackMentions(event.text ?? ""))) {
-                seen.add(logicalId);
-                const target = { channelId: event.channel, threadTs: event.thread_ts };
-                sideTasks.track(dispatchStop(agent, recordedSession(routed.conversation ?? defaultConversation), label)
-                    .then((feedback) => placeApi({ historyKey, teamId })
-                    .postMessage(target, feedback)
-                    .then(() => undefined))
-                    .catch((error) => log.warn(`${label} stop feedback failed: ${String(error)}`)));
-                return;
+        },
+        notifyDropped,
+        deliverAnswer: (turn, answer) => portJoin(async () => {
+            // A queue notice THIS process put up outlives the run the answer came from, so it is settled here as it
+            // would be by a turn that ran: the status line cleared, the compatibility message taken over.
+            if (turn.nativeQueueStatus) {
+                await api
+                    .setThreadStatus(targetOf(turn), "")
+                    .catch((error) => log.warn(`${label} could not clear a queued Agent status: ${String(error)}`));
             }
-            const fileIds = slackFileIds(event);
-            const baseText = routed.text ?? slackEnvelope(envelope);
-            if (!baseText.trim() && fileIds.length === 0)
-                return;
-            const threadTitle = direct && event.thread_ts === undefined
-                ? codePointPrefix(stripSlackMentions(slackMessageText(event), "").replace(/\s+/g, " ").trim(), 80)
-                : undefined;
-            runner.submit({
-                id: logicalId,
-                seq: ++seq,
-                conversation: routed.conversation ?? defaultConversation,
-                baseText,
-                ...(historyKey !== undefined ? { historyKey } : {}),
-                group,
-                teamId,
-                channelId: targetChannel,
-                threadTs,
-                requesterUserId: event.user,
-                threadTitle: threadTitle || undefined,
-                fileIds,
-            }, true);
-            // Answering inside a GROUP thread makes the agent a participant of it, which is what lets the NEXT bare message
-            // address it without a mention.
-            if (group &&
-                threadTs !== undefined &&
-                sameChannel &&
-                routed.conversation === undefined &&
-                routed.threadTs === undefined) {
-                // The ASKER counts as heard in this thread too, and both halves are written together so the record can never
-                // say "the agent takes part and nobody has spoken".
-                threadParticipants.merge(threadKey(teamId, event.channel, threadTs), {
-                    agentSpoke: true,
-                    humans: [event.user],
+            await deliverSlackAnswer(placeApi(turn), targetOf(turn), answer, turn.previewTs);
+            // The 👀 on the asker's message was added by the run that produced this answer, and `execute`'s
+            // acquire/release — the only thing that turns it into ✅ — is not on this path.
+            const messageRef = messageRefOf(turn.id);
+            if (reactionEmojis && messageRef) {
+                await completeSlackReaction({
+                    api,
+                    channelId: messageRef.channelId,
+                    ts: messageRef.ts,
+                    emojis: reactionEmojis,
+                    label,
                 });
             }
-        };
-        // First-run DM welcome: app_home_opened(tab="messages") signals a DM open. Post once per user.
-        const welcomeInFlight = new Set();
-        const maybeWelcome = (envelope) => {
-            if (welcome === false)
-                return;
-            const body = welcome.trim();
-            if (!body)
-                return;
-            const event = envelope.event;
-            if (!event)
-                return;
-            if (event.type !== "app_home_opened" || event.tab !== "messages")
-                return;
-            const userId = event.user;
-            const channelId = event.channel;
-            if (!userId || !channelId)
-                return;
-            const teamId = slackTeamId(envelope) ?? auth.teamId();
-            if (!teamId)
-                return;
-            const id = `${teamId}:${userId}`;
-            if (welcomed.has(teamId, userId) || welcomeInFlight.has(id))
-                return;
-            // Reserve in-memory so rapid re-opens don't double-post; persist to the durable set only on a successful post,
-            // so a failed post simply retries on the next open.
-            welcomeInFlight.add(id);
-            sideTasks.track(api
-                .postMarkdown({ channelId }, body)
-                .then(() => {
-                welcomed.add(teamId, userId);
-                log.info(`${label} sent first-run welcome to ${id}`);
-            })
-                .catch((error) => log.warn(`${label} could not send first-run welcome (retries on next open): ${String(error)}`))
-                .finally(() => {
-                welcomeInFlight.delete(id);
-            }));
-        };
+        }),
+        execute: (turn, discussion, onAnswered) => {
+            const messageRef = messageRefOf(turn.id);
+            return Effect.acquireUseRelease(portJoin(async () => reactionEmojis && messageRef
+                ? startSlackReaction({
+                    api,
+                    channelId: messageRef.channelId,
+                    ts: messageRef.ts,
+                    emojis: reactionEmojis,
+                    label,
+                })
+                : undefined), () => Effect.scoped(slackReply(slackTurnStream(agent, {
+                session: () => sessionFor(turn.conversation),
+                ...enterRoom(turn),
+                key: turn.id,
+                text: `${discussionBlock(discussion.text)}${turn.baseText}`,
+            }, { api, channelId: turn.channelId, filesDir: attachmentsDir(stateHome), label }, {
+                primaryFileIds: turn.fileIds,
+                buffered: collectFoldedFiles(discussion.consumed.flatMap((read) => read.folded), new Set(turn.fileIds)),
+            }), placeApi(turn), targetOf(turn), formatError, {
+                rendering,
+                initialPreviewTs: turn.previewTs,
+                threadTitle: turn.threadTitle,
+                disclaimer: aiDisclaimer,
+                label,
+                onAnswered,
+            })), (reaction, exit) => portJoin(async () => {
+                if (Exit.isSuccess(exit))
+                    await reaction?.complete();
+                else
+                    await reaction?.remove();
+            }).pipe(
+            // A release does not fail: its defect would make the turn's typed failure one too. Unreachable while
+            // the reaction's `complete` and `remove` catch their own failures (reaction.ts).
+            Effect.catchTag("PortFailure", (error) => Effect.sync(() => log.warn(`${label} could not settle the Slack reaction: ${String(error.cause)}`)))));
+        },
+    });
+    let seq = runner.recover().reduce((maximum, turn) => Math.max(maximum, turn.seq), 0);
+    // Acceptance touches no network, so it stays synchronous inside Slack's ACK window and the delivery dedup ring
+    // alone is enough.
+    const acceptEvent = (envelope) => {
+        const event = envelope.event;
+        if (!isSlackHumanMessage(event))
+            return;
+        const botUserId = auth.botUserId();
+        if (botUserId && event.user === botUserId)
+            return;
+        const teamId = slackTeamId(envelope) ?? auth.teamId();
+        if (!teamId) {
+            log.warn(`${label} ignored message ${event.ts}: event carried no workspace/enterprise identity`);
+            return;
+        }
+        const logicalId = `${teamId}:${event.channel}:${event.ts}`;
+        if (seen.has(logicalId)) {
+            log.debug(`${label} duplicate logical message ${logicalId} — skipping`);
+            return;
+        }
+        const group = isSlackGroupMessage(event);
+        const direct = isSlackDirectMessage(event);
+        const rootTs = event.thread_ts ?? event.ts;
+        // Listening is not speaking: every message the channel can see refines who takes part in its thread, whether or
+        // not it is answered.
+        if (group && event.thread_ts !== undefined) {
+            threadParticipants.merge(threadKey(teamId, event.channel, event.thread_ts), { humans: [event.user] });
+        }
+        let routed = decide(envelope);
+        const addressesSomeone = hasSlackMention(event.text ?? "");
+        const structurallyMentionsBot = botUserId !== undefined && mentionsSlackUser(event.text ?? "", botUserId);
+        // app_mention and message.* subscriptions can overlap.
+        if (!routed && route === undefined && group && event.type === "message" && structurallyMentionsBot)
+            routed = {};
+        // The participant model's thread rule (§3): a bare message reaches the agent while it takes part and has not
+        // heard a second human.
+        if (!routed &&
+            route === undefined &&
+            group &&
+            event.thread_ts !== undefined &&
+            event.type !== "app_mention" &&
+            // Mentioning only other people is targeted discussion, never an ask (§3) — the same guard Feishu applies with
+            // `hasMentions`.
+            !addressesSomeone &&
+            threadParticipants.admitsBareMessage(threadKey(teamId, event.channel, event.thread_ts))) {
+            routed = {};
+        }
+        if (!routed) {
+            // Not lost: the turn that is summoned here reads it from the place's history.
+            log.debug(`${label} not summoned — message ${logicalId}`);
+            return;
+        }
+        const targetChannel = routed.channelId ?? event.channel;
+        const sameChannel = targetChannel === event.channel;
+        // Answer where asked (participant model §4).
+        const defaultThread = event.thread_ts ?? event.ts;
+        const threadTs = routed.threadTs === null ? undefined : (routed.threadTs ?? (sameChannel ? defaultThread : undefined));
+        const defaultConversation = threadKey(teamId, event.channel, rootTs);
+        // Every place's discussion under the default routing, a DM's too (what a send tool posted there is in no session);
+        // a routed session's place is the router's to decide.
+        const historyKey = route === undefined && (group || direct)
+            ? slackHistoryKey(teamId, { channelId: event.channel, threadTs: event.thread_ts })
+            : undefined;
+        // Explicit user stop: a control action, never a turn — it must not queue behind the run it stops.
+        if (isStopText(stripSlackMentions(event.text ?? ""))) {
+            seen.add(logicalId);
+            const target = { channelId: event.channel, threadTs: event.thread_ts };
+            sideTasks.track(dispatchStop(agent, recordedSession(routed.conversation ?? defaultConversation), label)
+                .then((feedback) => placeApi({ historyKey, teamId })
+                .postMessage(target, feedback)
+                .then(() => undefined))
+                .catch((error) => log.warn(`${label} stop feedback failed: ${String(error)}`)));
+            return;
+        }
+        const fileIds = slackFileIds(event);
+        const baseText = routed.text ?? slackEnvelope(envelope);
+        if (!baseText.trim() && fileIds.length === 0)
+            return;
+        const threadTitle = direct && event.thread_ts === undefined
+            ? codePointPrefix(stripSlackMentions(slackMessageText(event), "").replace(/\s+/g, " ").trim(), 80)
+            : undefined;
+        runner.submit({
+            id: logicalId,
+            seq: ++seq,
+            conversation: routed.conversation ?? defaultConversation,
+            baseText,
+            ...(historyKey !== undefined ? { historyKey } : {}),
+            group,
+            teamId,
+            channelId: targetChannel,
+            threadTs,
+            requesterUserId: event.user,
+            threadTitle: threadTitle || undefined,
+            fileIds,
+        }, true);
+        // Answering inside a GROUP thread makes the agent a participant of it, which is what lets the NEXT bare message
+        // address it without a mention.
+        if (group &&
+            threadTs !== undefined &&
+            sameChannel &&
+            routed.conversation === undefined &&
+            routed.threadTs === undefined) {
+            // The ASKER counts as heard in this thread too, and both halves are written together so the record can never
+            // say "the agent takes part and nobody has spoken".
+            threadParticipants.merge(threadKey(teamId, event.channel, threadTs), {
+                agentSpoke: true,
+                humans: [event.user],
+            });
+        }
+    };
+    // First-run DM welcome: app_home_opened(tab="messages") signals a DM open. Post once per user.
+    const welcomeInFlight = new Set();
+    const maybeWelcome = (envelope) => {
+        if (welcome === false)
+            return;
+        const body = welcome.trim();
+        if (!body)
+            return;
+        const event = envelope.event;
+        if (!event)
+            return;
+        if (event.type !== "app_home_opened" || event.tab !== "messages")
+            return;
+        const userId = event.user;
+        const channelId = event.channel;
+        if (!userId || !channelId)
+            return;
+        const teamId = slackTeamId(envelope) ?? auth.teamId();
+        if (!teamId)
+            return;
+        const id = `${teamId}:${userId}`;
+        if (welcomed.has(teamId, userId) || welcomeInFlight.has(id))
+            return;
+        // Reserve in-memory so rapid re-opens don't double-post; persist to the durable set only on a successful post,
+        // so a failed post simply retries on the next open.
+        welcomeInFlight.add(id);
+        sideTasks.track(api
+            .postMarkdown({ channelId }, body)
+            .then(() => {
+            welcomed.add(teamId, userId);
+            log.info(`${label} sent first-run welcome to ${id}`);
+        })
+            .catch((error) => log.warn(`${label} could not send first-run welcome (retries on next open): ${String(error)}`))
+            .finally(() => {
+            welcomeInFlight.delete(id);
+        }));
+    };
+    return {
+        ingest: async (envelope) => {
+            await auth.ready();
+            maybeWelcome(envelope);
+            acceptEvent(envelope);
+        },
+        turnsIdle: () => Promise.all([runner.idle(), sideTasks.drain()]).then(() => undefined),
+    };
+}
+/** Build a Slack channel that receives by the Events API's HTTP Request URL: signed requests in, durable turns out. */
+export function slackChannel(options) {
+    const { signingSecret } = options;
+    const policy = resolveSlackPolicy(options);
+    return (ctx) => {
+        if (!signingSecret)
+            throw new Error("slackChannel requires a non-empty signingSecret (Basic Information → App Credentials)");
+        const runtime = createSlackRuntime(policy, ctx);
+        const { stateDir: stateHome } = ctx;
         const handler = async (request) => {
             if (request.method !== "POST")
                 return text("POST only\n", 405);
@@ -463,9 +496,11 @@ export function slackChannel(options) {
             const timestamp = request.headers.get("x-slack-request-timestamp") ?? "";
             const signature = request.headers.get("x-slack-signature") ?? "";
             if (!verifySlackSignature(signingSecret, timestamp, signature, body.text)) {
-                log.warn(`${label} rejected an event with an invalid/stale X-Slack-Signature`);
+                log.warn("[slack] rejected an event with an invalid/stale X-Slack-Signature");
                 return text("invalid signature\n", 401);
             }
+            // Slack signed it: the Request URL a person set reaches this instance, at the address it was sent to.
+            recordReached(stateHome, request);
             let envelope;
             try {
                 envelope = JSON.parse(body.text);
@@ -481,17 +516,42 @@ export function slackChannel(options) {
             if (envelope.type !== "event_callback")
                 return new Response(null, { status: 200 });
             try {
-                await auth.ready();
+                await runtime.ingest(envelope);
             }
             catch (error) {
-                log.error(`${label} refusing to ACK an event because Slack authentication is unavailable: ${String(error)}`);
+                log.error(`[slack] refusing to ACK an event because Slack authentication is unavailable: ${String(error)}`);
                 return text("slack authentication unavailable\n", 503);
             }
-            maybeWelcome(envelope);
-            acceptEvent(envelope);
             return new Response(null, { status: 200 });
         };
-        handler.turnsIdle = () => Promise.all([runner.idle(), sideTasks.drain()]).then(() => undefined);
+        handler.turnsIdle = runtime.turnsIdle;
         return { "POST /slack": handler };
     };
 }
+/**
+ * Build a Slack channel that receives by Socket Mode: the process opens a WebSocket to Slack with the app-level token
+ * and takes its events there, so no public URL and no signing secret are involved. An app in Socket Mode receives over
+ * the socket alone: it has no Request URL to point anywhere else.
+ */
+export function slackSocketChannel(options, 
+/** Internal seam for deterministic tests: the socket the connection opens. */
+deps = {}) {
+    const policy = resolveSlackPolicy(options);
+    const { appToken } = options;
+    return {
+        name: "slack socket mode",
+        connect(ctx, signal) {
+            if (!/^xapp-/.test(appToken)) {
+                throw new Error("slackSocketChannel requires an app-level token (xapp-…, scope connections:write: Basic Information → " +
+                    "App-Level Tokens), not a bot token");
+            }
+            const runtime = createSlackRuntime(policy, ctx);
+            return connectSlackSocket({
+                apiBaseUrl: policy.apiBaseUrl,
+                appToken,
+                ingest: runtime.ingest,
+                ...(deps.openSocket === undefined ? {} : { openSocket: deps.openSocket }),
+            }, signal);
+        },
+    };
+}