@cursor/bdk 0.2.2 → 0.2.4

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

@@ -1,744 +0,0 @@
-/**
- * `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;
-}