@cursor/bdk 0.2.1

package/src/channels/slack/slack-channel.ts

@@ -0,0 +1,744 @@
+/**
+ * `slackChannel()` — platform channel pack for Slack.
+ *
+ * Local / self-hosted transport is Socket Mode: inbound events arrive over
+ * a WebSocket (`SLACK_APP_TOKEN`); no public Request URL or Events HTTP
+ * route is required. When `toolApprovals` is enabled, Approve/Deny buttons
+ * arrive as Socket Mode `interactive` envelopes.
+ *
+ * Hosted v2 transport is the control plane's Events API ingest: the CP
+ * verifies the managed app's signature, fans out on the declared
+ * `slackEventTypes` (`app_mention`, `message`), and delivers the full
+ * `event_callback` body through hosted admission — the attached adapter
+ * routes it through the same inbound dispatch as Socket Mode. Hosted pods
+ * skip Socket Mode entirely, so they never need an app token.
+ */
+
+import { allowAll, defineChannel } from "../../channels.js";
+import { skipped, withPropagatingBackgroundErrors } from "../../internal/channel-dispatch.js";
+import { continuationSource, normalizeIdentity } from "../../internal/continuation-identity.js";
+import { AGENT_SERVE_GENERATION_ENV_VAR } from "../../internal/cursor-relay-core.js";
+import { attachHostedAdmissionAdapter } from "../../internal/hosted-admission-adapter.js";
+import type { HostedAdmissionPlatformHandoff } from "../../internal/hosted-delivery-protocol.js";
+import type {
+  ArtifactsApi,
+  ChannelDefinition,
+  ChannelEventHandlers,
+  ChannelHandlerArgs,
+  HostContext,
+  JsonValue,
+  ReceiveInput,
+  SendMessageFn,
+} from "../../types.js";
+import { slackContinuationKey } from "./api.js";
+import { defaultSlackAuth } from "./auth.js";
+import {
+  normalizeBotMentionAllowlist,
+  SLACK_BOT_MENTION_DEFAULTS,
+  SlackBotMentionGate,
+} from "./bot-mentions.js";
+import {
+  type ChannelPostWatcher,
+  channelPostsWatchEverywhere,
+  createChannelPostWatcher,
+  resolveChannelNames,
+  SlackChannelAllowlist,
+  validateChannelPostsAllow,
+} from "./channel-watch.js";
+import {
+  credentialsFromEnv,
+  slackEnvKeys,
+  tryResolveAppToken,
+  tryResolveBotToken,
+} from "./credentials.js";
+import {
+  buildDefaultEvents,
+  createDefaultOnChannelPost,
+  createDefaultOnInbound,
+  resolveSlackBlockExternals,
+  resolveSlackRespondTo,
+} from "./defaults.js";
+import {
+  dispatchInboundFromEventBody,
+  dispatchInboundMessage,
+  emptySlackChannelState,
+  type SlackInboundDispatchDeps,
+  slackWakeChannelState,
+} from "./dispatch.js";
+import { createEventIdDedupe, type EventIdDedupe } from "./event-id-dedupe.js";
+import { parseChannelMessageEvent, parseEventBodyBotUserId } from "./inbound.js";
+import { dispatchBlockAction, dispatchInteractiveFromPayload } from "./interactive.js";
+import { createSlackLogger, type SlackLog } from "./log.js";
+import { DEFAULT_ACK, resolveSlackReply } from "./reply-options.js";
+import {
+  type SlackSocketModeHandle,
+  type SlackSocketModeOptions,
+  startSlackSocketMode,
+} from "./socket-mode.js";
+import { buildToolApprovalEvents } from "./tool-approval-events.js";
+import type {
+  SlackAccessPolicy,
+  SlackChannelOptions,
+  SlackChannelState,
+  SlackCredentials,
+  SlackMessageHandler,
+} from "./types.js";
+
+/** Options used to construct a slack channel — for host-level credential binding. */
+const slackChannelOptionsByDefinition = new WeakMap<object, SlackChannelOptions>();
+
+/**
+ * Recover the {@link SlackChannelOptions} used to build a channel definition,
+ * if it was created via {@link slackChannel}.
+ */
+export function getSlackChannelOptions(definition: object): SlackChannelOptions | undefined {
+  return slackChannelOptionsByDefinition.get(definition);
+}
+
+/** Dedicated Socket Mode credentials for `ctx.host.slack.getClient()`. */
+export interface SlackChannelHostBinding {
+  credentials: SlackCredentials;
+  envPrefix?: string;
+}
+
+/**
+ * First Slack channel on a project. Used for
+ * {@link HostContext.slack.getClient}.
+ */
+export function resolveDedicatedSlackHostBinding(
+  channels: ReadonlyArray<{ definition: object }>,
+): SlackChannelHostBinding | undefined {
+  for (const channel of channels) {
+    const options = slackChannelOptionsByDefinition.get(channel.definition);
+    if (options === undefined) {
+      continue;
+    }
+    return {
+      credentials: options.credentials ?? credentialsFromEnv(options.envPrefix),
+      envPrefix: options.envPrefix,
+    };
+  }
+  return undefined;
+}
+
+function authOnlyInbound(
+  policy: SlackAccessPolicy | undefined,
+  engagement?: "channel_post",
+): SlackMessageHandler {
+  const respondTo = resolveSlackRespondTo(policy);
+  return async (ctx, message) => {
+    const auth = defaultSlackAuth(message, ctx, { engagement, respondTo });
+    return auth === null ? null : { auth };
+  };
+}
+
+/**
+ * Create a Slack channel. Author as `agent/channels/slack.ts` default export.
+ *
+ * Missing credentials are not an error: without a token pair the channel
+ * mounts idle and logs `channel idle`, so serving an agent never blocks
+ * on Slack setup.
+ */
+export function slackChannel(
+  authored: SlackChannelOptions = {},
+): ChannelDefinition<SlackChannelState> {
+  const options = { ...authored };
+  if (options.continuation !== undefined) {
+    options.continuation = normalizeIdentity(options.continuation, "slack");
+  }
+  const credentials = options.credentials ?? credentialsFromEnv(options.envPrefix);
+  const envKeys = slackEnvKeys(options.envPrefix);
+  const reply = resolveSlackReply(options);
+  const loadingMessages = reply.status.idle;
+  const policy = options.policy;
+  const blockExternals = resolveSlackBlockExternals(policy);
+  const silent = reply.mode === "agentic";
+  const defaultInbound = silent
+    ? authOnlyInbound(policy)
+    : createDefaultOnInbound(loadingMessages, policy);
+  const onAppMention = options.onAppMention ?? defaultInbound;
+  const onDirectMessage = options.onDirectMessage ?? defaultInbound;
+  const onReactionAdded = options.onReactionAdded;
+  const onChannelPost =
+    options.onChannelPost ??
+    (silent
+      ? authOnlyInbound(policy, "channel_post")
+      : createDefaultOnChannelPost(loadingMessages, policy));
+  const engagement = options.engagement ?? {};
+  const mentionsEnabled = engagement.mentions !== false;
+  const directMessagesEnabled = engagement.directMessages !== false;
+  const evalCommandsEnabled = options.evalCommands !== false;
+  const followUpStatus = options.followUpStatus ?? !silent;
+  const channelPosts = engagement.channelPosts;
+  if (channelPosts !== undefined) {
+    const allowError = validateChannelPostsAllow(channelPosts.allow);
+    if (allowError !== undefined) {
+      throw new Error(`slackChannel engagement.channelPosts.allow ${allowError}`);
+    }
+    if (channelPostsWatchEverywhere(channelPosts.allow) && channelPosts.posts !== "replies") {
+      throw new Error(
+        'slackChannel engagement.channelPosts: "*" watches every channel the bot is in, thread replies only. Set posts: "replies".',
+      );
+    }
+  }
+  const botMentions = engagement.botMentions;
+  if (botMentions !== undefined) {
+    normalizeBotMentionAllowlist(botMentions.allowFrom);
+  }
+  const eventIds = createEventIdDedupe();
+  // Hosted v2 event capability, matching what the engagement flags can
+  // dispatch: mentions ride `app_mention`; DMs and watched channel posts
+  // both arrive as `message`. Membership of `slack.thread/v2` admits
+  // exactly these two, so `reaction_added` (hosted follow-up only inside
+  // an existing thread) is deliberately not declared.
+  const slackEventTypes: string[] = [];
+  if (mentionsEnabled) {
+    slackEventTypes.push("app_mention");
+  }
+  if (directMessagesEnabled || channelPosts !== undefined) {
+    slackEventTypes.push("message");
+  }
+  const toolApprovals = options.toolApprovals === true;
+  const interactivity = options.interactivity === true;
+  const onBlockAction = options.onBlockAction;
+  const routeInteractive = toolApprovals || interactivity || onBlockAction !== undefined;
+
+  const runtime: { log: SlackLog } = {
+    log: createSlackLogger(options.logger),
+  };
+  const getLog = (): SlackLog => runtime.log;
+
+  const events: ChannelEventHandlers<SlackChannelState> = {};
+  if (options.deliverDefaults !== false) {
+    Object.assign(
+      events,
+      buildDefaultEvents({
+        credentials,
+        reply: options.reply,
+        toolLabels: options.toolLabels,
+        streaming: options.streaming,
+        thinkingSteps: options.thinkingSteps,
+        loadingMessages: options.loadingMessages,
+        suggestedPrompts: options.suggestedPrompts,
+        suggestedPromptsTitle: options.suggestedPromptsTitle,
+        getLog,
+      }),
+    );
+  }
+  if (toolApprovals) {
+    Object.assign(events, buildToolApprovalEvents({ credentials, getLog, status: !silent }));
+  }
+  Object.assign(events, options.events);
+
+  let socketHandle: SlackSocketModeHandle | null = null;
+  let channelWatch: ChannelPostWatcher | undefined;
+  let botMentionGate: SlackBotMentionGate | undefined;
+
+  // Hosted admission never runs the Socket Mode branch of `onStart`, so the
+  // channel watch is built per delivery there. The allowlist and its `#name`
+  // resolution are shared across the pod; the bot's identity comes from the
+  // verified envelope.
+  let hostedAllowlist: SlackChannelAllowlist | undefined;
+  let hostedAllowlistReady: Promise<void> | undefined;
+
+  async function resolveHostedAllowlistNames(allowlist: SlackChannelAllowlist): Promise<void> {
+    const names = allowlist.unresolvedNames();
+    if (names.length === 0) {
+      return;
+    }
+    try {
+      const botToken = await tryResolveBotToken(credentials);
+      if (botToken === undefined) {
+        getLog().error("channel watch setup degraded", {
+          error: "no bot token; #name entries stay unresolved",
+        });
+        return;
+      }
+      const { WebClient } = await import("@slack/web-api");
+      allowlist.applyResolvedNames(
+        await resolveChannelNames(new WebClient(botToken), names, getLog()),
+      );
+    } catch (error) {
+      getLog().error("channel watch setup degraded", {
+        error: error instanceof Error ? error.message : String(error),
+      });
+    }
+  }
+
+  /**
+   * Only a channel post needs the watcher, so mentions and DMs never wait on
+   * it, and a channel already matched by id never waits on `#name` resolution.
+   */
+  async function hostedChannelWatch(
+    payload: unknown,
+    args: ChannelHandlerArgs,
+    platformHandoff: HostedAdmissionPlatformHandoff | undefined,
+  ): Promise<ChannelPostWatcher | undefined> {
+    if (channelPosts === undefined) {
+      return undefined;
+    }
+    const channelEvent = parseChannelMessageEvent(payload, {
+      includeBotAuthored: true,
+    });
+    if (channelEvent === null || channelEvent.kind === "deleted") {
+      return undefined;
+    }
+    hostedAllowlist ??= new SlackChannelAllowlist(channelPosts.allow);
+    if (
+      !hostedAllowlist.matches(channelEvent.message.channelId) &&
+      hostedAllowlist.unresolvedNames().length > 0
+    ) {
+      hostedAllowlistReady ??= resolveHostedAllowlistNames(hostedAllowlist);
+      await hostedAllowlistReady;
+    }
+    const botUserId = parseEventBodyBotUserId(payload);
+    return createChannelPostWatcher({
+      // Admission answers before a debounce timer could fire; edits arrive
+      // as their own deliveries and the edge drops them.
+      options: { ...channelPosts, debounceMs: 0 },
+      allowlist: hostedAllowlist,
+      getBotUserId: () => botUserId,
+      log: getLog(),
+      dispatch: (message, eventId) => {
+        args.waitUntil(
+          dispatchInboundMessage({
+            kind: "channel_post",
+            message,
+            handler: onChannelPost,
+            propagateHandlerErrors: true,
+            send: args.send,
+            credentials,
+            host: args.host,
+            artifacts: args.artifacts,
+            log: getLog(),
+            evalCommandsEnabled,
+            followUpStatus,
+            ack: reply.ack,
+            blockExternals,
+            continuation: options.continuation,
+            ...(args.hasContinuationSession === undefined
+              ? {}
+              : { hasContinuationSession: args.hasContinuationSession }),
+            ...(args.isContinuationBusy === undefined
+              ? {}
+              : { isContinuationBusy: args.isContinuationBusy }),
+            ...(args.getContinuationLastBotMessageTs === undefined
+              ? {}
+              : {
+                  getContinuationLastBotMessageTs: args.getContinuationLastBotMessageTs,
+                }),
+            ...(args.interruptContinuation === undefined
+              ? {}
+              : { interruptContinuation: args.interruptContinuation }),
+            ...(eventId === undefined ? {} : { eventId }),
+            ...(platformHandoff === undefined ? {} : { platformHandoff }),
+          }),
+        );
+      },
+    });
+  }
+
+  function inboundDeps(args: {
+    send: SendMessageFn;
+    waitUntil: (promise: Promise<unknown>) => void;
+    host: HostContext;
+    artifacts: ArtifactsApi;
+    /** Override the channel-level dedupe (hosted admission passes a fresh one). */
+    eventIds?: EventIdDedupe;
+    propagateHandlerErrors?: boolean;
+    hasContinuationSession?: (continuationToken: string) => Promise<boolean>;
+    isContinuationBusy?: (continuationToken: string) => Promise<boolean>;
+    getContinuationLastBotMessageTs?: (continuationToken: string) => Promise<string | undefined>;
+    interruptContinuation?: (continuationToken: string) => Promise<boolean>;
+    platformHandoff?: SlackInboundDispatchDeps["platformHandoff"];
+    /** Per-delivery watcher (hosted); the Socket Mode watcher otherwise. */
+    channelWatch?: ChannelPostWatcher;
+  }): SlackInboundDispatchDeps {
+    const watch = args.channelWatch ?? channelWatch;
+    return {
+      send: args.send,
+      continuation: options.continuation,
+      waitUntil: args.waitUntil,
+      onAppMention,
+      onDirectMessage,
+      ...(onReactionAdded === undefined ? {} : { onReactionAdded }),
+      credentials,
+      eventIds: args.eventIds ?? eventIds,
+      propagateHandlerErrors: args.propagateHandlerErrors,
+      host: args.host,
+      artifacts: args.artifacts,
+      log: getLog(),
+      mentionsEnabled,
+      directMessagesEnabled,
+      evalCommandsEnabled,
+      followUpStatus,
+      ack: reply.ack,
+      placeholder: reply.placeholder,
+      blockExternals,
+      ...(args.platformHandoff === undefined ? {} : { platformHandoff: args.platformHandoff }),
+      ...(args.hasContinuationSession === undefined
+        ? {}
+        : { hasContinuationSession: args.hasContinuationSession }),
+      ...(args.isContinuationBusy === undefined
+        ? {}
+        : { isContinuationBusy: args.isContinuationBusy }),
+      ...(args.getContinuationLastBotMessageTs === undefined
+        ? {}
+        : {
+            getContinuationLastBotMessageTs: args.getContinuationLastBotMessageTs,
+          }),
+      ...(args.interruptContinuation === undefined
+        ? {}
+        : { interruptContinuation: args.interruptContinuation }),
+      ...(watch === undefined ? {} : { channelWatch: watch }),
+      ...(botMentionGate === undefined ? {} : { botMentionGate }),
+      suggestedPrompts: options.suggestedPrompts,
+      suggestedPromptsTitle: options.suggestedPromptsTitle,
+    };
+  }
+
+  const definition = defineChannel({
+    auth: [allowAll()],
+    state: emptySlackChannelState(),
+    routes: [],
+    meta: {
+      kind: "slack",
+      // Omitted (not empty) when nothing dispatches, so fanout never
+      // materializes a subscription with no event types.
+      slackEventTypes: slackEventTypes.length === 0 ? undefined : slackEventTypes,
+      ...(reply.mode === "agentic"
+        ? {
+            slackReply: {
+              mode: "agentic" as const,
+              ack: reply.ack ?? DEFAULT_ACK,
+              ...(reply.placeholder === undefined
+                ? {}
+                : {
+                    placeholder: reply.placeholder,
+                  }),
+            },
+          }
+        : {}),
+      // A lone "*" stays off the manifest. Hosting already delivers a reply
+      // in a thread a mention started; publishing "*" is what the control
+      // plane rejects.
+      ...(channelPosts === undefined || channelPostsWatchEverywhere(channelPosts.allow)
+        ? {}
+        : { slackChannelPosts: [...channelPosts.allow] }),
+      deprecations: reply.deprecations,
+    },
+    async receive(input: ReceiveInput, { send }) {
+      const target = input.target ?? {};
+      const channelId = typeof target.channelId === "string" ? target.channelId : "";
+      if (channelId === "") {
+        throw new Error("slackChannel().receive requires target.channelId (Slack channel id).");
+      }
+      const threadTs = typeof target.threadTs === "string" ? target.threadTs : "";
+      if (threadTs === "") {
+        throw new Error("slackChannel().receive requires target.threadTs (Slack thread ts).");
+      }
+      const teamId = typeof target.teamId === "string" ? target.teamId : undefined;
+
+      getLog().info("receive handoff", {
+        channel: channelId,
+        thread_ts: threadTs,
+        team: teamId,
+      });
+
+      const state = emptySlackChannelState({
+        channelId,
+        threadTs,
+        teamId: teamId ?? null,
+      }) as unknown as JsonValue;
+      return send(input.message, {
+        auth: input.auth,
+        admission: "coalesce",
+        ...(continuationSource(options.continuation, "slack") === "control-plane"
+          ? {
+              claim: {
+                type: "thread" as const,
+                resource: { channelId, threadTs },
+              },
+            }
+          : {
+              continuationToken: slackContinuationKey(channelId, threadTs),
+            }),
+        state,
+        refreshState: slackWakeChannelState({
+          channelId,
+          threadTs,
+          teamId: teamId ?? null,
+        }),
+      });
+    },
+    events,
+    async onStart(args) {
+      runtime.log = createSlackLogger(args.logger ?? options.logger);
+
+      // Cursor-managed v2 receives inbound events through the control-plane
+      // adapter attached below. Do not also start (or warn about) the local
+      // Socket Mode transport: hosted outbound replies need only the bot token.
+      if (args.architecture === "v2" && process.env[AGENT_SERVE_GENERATION_ENV_VAR] !== undefined) {
+        getLog().info("channel start", { transport: "events-api" });
+        return;
+      }
+
+      getLog().info("channel start", { transport: "socket" });
+
+      const appToken = await tryResolveAppToken(credentials);
+      const botToken = await tryResolveBotToken(credentials);
+      if (appToken === undefined || botToken === undefined) {
+        getLog().info("channel idle", {
+          reason: "missing credentials",
+          need: `${envKeys.bot} and ${envKeys.app}`,
+        });
+        return;
+      }
+
+      let botUserId: string | undefined;
+      let botId: string | undefined;
+      let installTeamId: string | undefined;
+      let webClient: InstanceType<typeof import("@slack/web-api").WebClient> | null = null;
+      if (channelPosts !== undefined || botMentions !== undefined || routeInteractive) {
+        try {
+          const { WebClient } = await import("@slack/web-api");
+          webClient = new WebClient(botToken);
+          const identity = await webClient.auth.test();
+          botUserId = typeof identity.user_id === "string" ? identity.user_id : undefined;
+          botId = typeof identity.bot_id === "string" ? identity.bot_id : undefined;
+          installTeamId = typeof identity.team_id === "string" ? identity.team_id : undefined;
+        } catch (error) {
+          getLog().error("bot identity lookup degraded", {
+            error: error instanceof Error ? error.message : String(error),
+          });
+        }
+      }
+
+      if (botMentions !== undefined) {
+        if (botUserId === undefined && botId === undefined) {
+          getLog().error("bot mentions disabled", {
+            reason: "engagement.botMentions requires bot identity from auth.test (loop safety)",
+          });
+        } else {
+          botMentionGate = new SlackBotMentionGate(
+            botMentions,
+            { botUserId, botId },
+            { log: getLog() },
+          );
+          getLog().info("bot mentions enabled", {
+            allow_from: botMentions.allowFrom.join(","),
+            max_depth: botMentions.maxDepth ?? SLACK_BOT_MENTION_DEFAULTS.maxDepth,
+            max_per_thread_per_hour:
+              botMentions.maxPerThreadPerHour ?? SLACK_BOT_MENTION_DEFAULTS.maxPerThreadPerHour,
+            max_per_thread_total:
+              botMentions.maxPerThreadTotal ?? SLACK_BOT_MENTION_DEFAULTS.maxPerThreadTotal,
+          });
+        }
+      }
+
+      if (channelPosts !== undefined) {
+        const allowlist = new SlackChannelAllowlist(channelPosts.allow);
+        try {
+          const names = allowlist.unresolvedNames();
+          if (names.length > 0 && webClient !== null) {
+            allowlist.applyResolvedNames(await resolveChannelNames(webClient, names, getLog()));
+          }
+        } catch (error) {
+          getLog().error("channel watch setup degraded", {
+            error: error instanceof Error ? error.message : String(error),
+          });
+        }
+        if (
+          channelPosts.includeBotPosts === true &&
+          botUserId === undefined &&
+          botId === undefined
+        ) {
+          getLog().error("channel watch disabled", {
+            reason: "includeBotPosts requires bot identity from auth.test (loop safety)",
+          });
+        } else {
+          channelWatch = createChannelPostWatcher({
+            options: channelPosts,
+            allowlist,
+            getBotUserId: () => botUserId,
+            getBotId: () => botId,
+            log: getLog(),
+            dispatch: (message, eventId) => {
+              args.waitUntil(
+                dispatchInboundMessage({
+                  kind: "channel_post",
+                  message,
+                  handler: onChannelPost,
+                  send: args.send,
+                  credentials,
+                  host: args.host,
+                  artifacts: args.artifacts,
+                  log: getLog(),
+                  evalCommandsEnabled,
+                  followUpStatus,
+                  ack: reply.ack,
+                  blockExternals,
+                  continuation: options.continuation,
+                  ...(args.hasContinuationSession === undefined
+                    ? {}
+                    : {
+                        hasContinuationSession: args.hasContinuationSession,
+                      }),
+                  ...(args.isContinuationBusy === undefined
+                    ? {}
+                    : { isContinuationBusy: args.isContinuationBusy }),
+                  ...(args.getContinuationLastBotMessageTs === undefined
+                    ? {}
+                    : {
+                        getContinuationLastBotMessageTs: args.getContinuationLastBotMessageTs,
+                      }),
+                  ...(args.interruptContinuation === undefined
+                    ? {}
+                    : {
+                        interruptContinuation: args.interruptContinuation,
+                      }),
+                  ...(eventId === undefined ? {} : { eventId }),
+                }),
+              );
+            },
+          });
+          getLog().info("channel watch enabled", {
+            channels: channelPosts.allow.join(","),
+            posts: channelPosts.posts ?? "top-level",
+            debounce_ms: channelPosts.debounceMs ?? 0,
+          });
+        }
+      }
+
+      const socketOptions: SlackSocketModeOptions = {
+        appToken,
+        logger: line => getLog().write(line),
+        onEvent: payload => {
+          dispatchInboundFromEventBody(
+            payload,
+            inboundDeps({
+              send: args.send,
+              waitUntil: args.waitUntil,
+              host: args.host,
+              artifacts: args.artifacts,
+              ...(args.hasContinuationSession === undefined
+                ? {}
+                : { hasContinuationSession: args.hasContinuationSession }),
+              ...(args.isContinuationBusy === undefined
+                ? {}
+                : { isContinuationBusy: args.isContinuationBusy }),
+              ...(args.getContinuationLastBotMessageTs === undefined
+                ? {}
+                : {
+                    getContinuationLastBotMessageTs: args.getContinuationLastBotMessageTs,
+                  }),
+              ...(args.interruptContinuation === undefined
+                ? {}
+                : { interruptContinuation: args.interruptContinuation }),
+            }),
+          );
+        },
+      };
+      if (routeInteractive) {
+        socketOptions.onInteractive = async payload => {
+          // Framework tool-approval Approve/Deny clicks resolve first;
+          // anything else (including approval-shaped clicks whose value
+          // fails to parse) falls through to the author's block-action hook.
+          const handledAsApproval = await dispatchInteractiveFromPayload(payload, {
+            credentials,
+            getSession: args.getSession,
+            resolveApproval: args.resolveApproval,
+            resolveAuth: args.resolveAuth,
+            waitUntil: args.waitUntil,
+            log: getLog(),
+            blockExternals,
+          });
+          if (handledAsApproval || onBlockAction === undefined) {
+            return;
+          }
+          await dispatchBlockAction(payload, {
+            handler: onBlockAction,
+            send: args.send,
+            credentials,
+            host: args.host,
+            artifacts: args.artifacts,
+            log: getLog(),
+            blockExternals,
+            installTeamId,
+            hasContinuationSession: args.hasContinuationSession,
+            isContinuationBusy: args.isContinuationBusy,
+            getContinuationLastBotMessageTs: args.getContinuationLastBotMessageTs,
+            interruptContinuation: args.interruptContinuation,
+            continuation: options.continuation,
+          });
+        };
+      }
+      try {
+        socketHandle = await startSlackSocketMode(socketOptions);
+      } catch (error) {
+        // Bad Vault tokens / revoked apps: Socket Mode fails once with
+        // invalid_auth and does not reconnect. Treat as idle so one bad
+        // Slack pack does not blow up server start with a stack dump.
+        const message = error instanceof Error ? error.message : String(error);
+        if (message.includes("invalid_auth") || message.includes("not_authed")) {
+          getLog().info("channel idle", {
+            reason: "invalid credentials",
+            need: `${envKeys.bot} and ${envKeys.app}`,
+          });
+          return;
+        }
+        throw error;
+      }
+    },
+    onStop: async () => {
+      getLog().info("channel stop");
+      channelWatch?.stop();
+      channelWatch = undefined;
+      botMentionGate = undefined;
+      await socketHandle?.stop();
+      socketHandle = null;
+      await options.onStop?.();
+    },
+  });
+
+  slackChannelOptionsByDefinition.set(definition, options);
+  attachHostedAdmissionAdapter(definition, {
+    kind: "slack",
+    prepareArgs: withPropagatingBackgroundErrors,
+    // The payload is the full `event_callback` body the CP verified — the
+    // same shape Socket Mode unwraps — so it routes through the same
+    // inbound dispatch. Outcomes: a captured `send` overrides the fallback
+    // tag below, so `skipped` surfaces when the engagement rules declined
+    // (`not_engaged`) or no handler takes the shape (`not_dispatchable`);
+    // a throwing handler rejects `waitUntil` (propagateHandlerErrors) and
+    // hosted admission answers a retryable 503, like the PR adapters.
+    // The channel-level event_id dedupe is deliberately bypassed with a
+    // fresh instance per delivery: the control plane's app-scoped ingress
+    // claim already dedupes Slack retries, and on a warm pod the local set
+    // would otherwise swallow the control plane's own retry of a delivery
+    // that failed after the id was marked handled.
+    dispatch: async ({ payload, args, platformHandoff }) => {
+      const hostedWatch = await hostedChannelWatch(payload, args, platformHandoff);
+      const dispatched = dispatchInboundFromEventBody(
+        payload,
+        inboundDeps({
+          send: args.send,
+          waitUntil: args.waitUntil,
+          host: args.host,
+          artifacts: args.artifacts,
+          eventIds: createEventIdDedupe(),
+          propagateHandlerErrors: true,
+          hasContinuationSession: args.hasContinuationSession,
+          isContinuationBusy: args.isContinuationBusy,
+          getContinuationLastBotMessageTs: args.getContinuationLastBotMessageTs,
+          interruptContinuation: args.interruptContinuation,
+          ...(platformHandoff === undefined ? {} : { platformHandoff }),
+          ...(hostedWatch === undefined ? {} : { channelWatch: hostedWatch }),
+        }),
+      );
+      return skipped(dispatched ? "not_engaged" : "not_dispatchable");
+    },
+  });
+
+  return definition;
+}