Add Slack Socket Mode support (#162)

* Add slack/socket mode dependency

* Update config types and SlackAdapter class

* Add socket mode methods, extract interactive dispatch

* Update createSlackAdapter factory function

* Write tests for socket mode

* Create slack-socket-mode.md

* Run fix

* Fix polynomial regex issues

* Fix: Floating promises in `routeSocketEvent` for slash commands and interactive payloads can cause unhandled promise rejections that crash the Node.js process.


This commit fixes the issue reported at packages/adapter-slack/src/index.ts:1152

**Bug Analysis:**

In `routeSocketEvent` (line 1150), which is a synchronous `void` method, two async operations produce floating promises:

1.  `this.handleSlashCommand(params)` (line 1165) - `handleSlashCommand` is `async` and always returns a `Promise<Response>`. It calls `await this.lookupUser(userId)` which internally calls `await this.chat.getState().get()` (before the try/catch around the API call), and `this.chat.processSlashCommand()`. Any of these could throw.
    
2.  `this.dispatchInteractivePayload(payload)` (line 1172) - Returns `Response | Promise<Response>`. When the payload type is `view_submission`, it delegates to `async handleViewSubmission()`, which calls `await this.chat.processModalSubmit()` and accesses `payload.view.state.values` (which could throw on malformed payloads).
    

Since `routeSocketEvent` is synchronous (`void` return type) and called from a sync context within the socket mode event handler (after `await ack()` has already completed), these returned promises are fire-and-forget. If any reject, it triggers an unhandled promise rejection, which in Node.js 15+ terminates the process by default.

In contrast, in the webhook code path (`handleWebhook`), these same methods are always `return`-ed from async functions, so their promises are properly chained to the caller.

**Fix:**

Added `.catch()` handlers to both floating promises:

1.  For `handleSlashCommand`: Added `.catch()` that logs the error via `this.logger.error`.
2.  For `dispatchInteractivePayload`: Since it returns `Response | Promise<Response>` (only a Promise for `view_submission`), used `instanceof Promise` to conditionally attach a `.catch()` handler only when the result is a Promise.

This approach was chosen over making `routeSocketEvent` async because: (a) it doesn't change the method signature, (b) the caller doesn't need to await it (the ack has already been sent), and (c) errors are logged rather than silently swallowed.


Co-authored-by: Vercel <vercel[bot]@users.noreply.github.com>
Co-authored-by: haydenbleasel <hello@haydenbleasel.com>

* Add socket mode forwarding support to Slack adapter

- Export SlackForwardedSocketEvent type
- Add x-slack-socket-token check at top of handleWebhook() for forwarded events
- Update routeSocketEvent() to accept WebhookOptions and use waitUntil
- Add startSocketModeListener(), runSocketModeListener(), forwardSocketEvent()

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

* Add tests for socket mode forwarding

- Forwarded event accepted/rejected based on appToken
- Bypasses signature verification for forwarded events
- Options passthrough to handlers
- startSocketModeListener returns 200/500 appropriately

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

* Add socket mode cron route and vercel config

- New /api/slack/socket-mode route using createPersistentListener
- Mirrors Discord gateway pattern (CRON_SECRET auth, Redis coordination)
- Cron runs every 9 min, listener duration 10 min

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

* Fix signingSecret defaulting to empty string in socket mode

Make signingSecret optional (string | undefined) instead of falling
back to "". verifySignature now returns false when no secret is
configured, preventing HMAC with an empty key from silently passing.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

* Wrap event_callback in try-catch in routeSocketEvent

Sync errors from processEventPayload were silently dropped in
socket mode. Wrap with try-catch for parity with slash_commands
and interactive cases.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

* Use dedicated socketForwardingSecret for forwarding auth

Stop using the Slack app-level token (xapp-...) as the bearer token
for HTTP forwarding. Adds socketForwardingSecret config option
(auto-detected from SLACK_SOCKET_FORWARDING_SECRET) with fallback
to appToken for backwards compatibility.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

* Replace double cast with type guard for socket event body

Validate body.event exists and construct a properly typed
SlackWebhookPayload instead of using `as unknown as`.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

* Internalize SlackForwardedSocketEvent type

Remove export — only used internally by the forwarding mechanism.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

* Fix formatting in socketForwardingSecret check

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

* Add socket mode documentation to Slack adapter README

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

* fix(slack): use SDK envelope type for socket mode event routing

* fix(slack): pass interactive response through ack in socket mode

* feat(chat): add clear modal response action to close entire view stack

* chore: update changeset for clear modal action

---------

Co-authored-by: Vercel <vercel[bot]@users.noreply.github.com>
Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>
Co-authored-by: dancer <josh@afterima.ge>

Author: 4 people

.changeset/slack-socket-mode.md

@@ -0,0 +1,6 @@
+---
+"chat": minor
+"@chat-adapter/slack": minor
+---
+
+Add Socket Mode support for environments behind firewalls that can't expose public HTTP endpoints, and add `{ action: "clear" }` modal response to close the entire modal view stack

apps/docs/content/docs/api/chat.mdx

@@ -255,7 +255,8 @@ bot.onModalSubmit("feedback", async (event) => {
 
 Returns `ModalResponse | undefined` to control the modal after submission:
 
-- `{ action: "close" }` — close the modal
+- `{ action: "close" }` — close the current view (goes back one level in the stack)
+- `{ action: "clear" }` — close all views and dismiss the modal entirely
 - `{ action: "errors", errors: { fieldId: "message" } }` — show validation errors
 - `{ action: "update", modal: ModalElement }` — replace the modal content
 - `{ action: "push", modal: ModalElement }` — push a new modal view onto the stack

apps/docs/content/docs/modals.mdx

@@ -142,7 +142,8 @@ bot.onModalSubmit("feedback_form", async (event) => {
 
 | Response | Description |
 |----------|-------------|
-| `undefined` or `{ action: "close" }` | Close the modal |
+| `undefined` or `{ action: "close" }` | Close the current view (goes back one level in the stack) |
+| `{ action: "clear" }` | Close all views and dismiss the modal entirely |
 | `{ action: "errors", errors: { fieldId: "message" } }` | Show validation errors on specific fields |
 | `{ action: "update", modal: ModalElement }` | Replace the modal content |
 | `{ action: "push", modal: ModalElement }` | Push a new modal view onto the stack |

examples/nextjs-chat/src/app/api/slack/socket-mode/route.ts

@@ -0,0 +1,92 @@
+import { after } from "next/server";
+import { bot } from "@/lib/bot";
+import { createPersistentListener } from "@/lib/persistent-listener";
+
+export const maxDuration = 800;
+
+// Default listener duration: 10 minutes
+const DEFAULT_DURATION_MS = 600 * 1000;
+
+/**
+ * Persistent listener for Slack Socket Mode.
+ * Handles cross-instance coordination via Redis pub/sub.
+ */
+const slackSocketMode = createPersistentListener({
+  name: "slack-socket-mode",
+  redisUrl: process.env.REDIS_URL,
+  defaultDurationMs: DEFAULT_DURATION_MS,
+  maxDurationMs: DEFAULT_DURATION_MS,
+});
+
+/**
+ * Start the Slack Socket Mode WebSocket listener.
+ *
+ * This endpoint is invoked by a Vercel cron job every 9 minutes to maintain
+ * continuous Socket Mode connectivity. Events are acked immediately and
+ * forwarded via HTTP POST to the existing webhook endpoint.
+ *
+ * Security: Requires CRON_SECRET validation.
+ *
+ * Usage: GET /api/slack/socket-mode
+ * Optional query param: ?duration=600000 (milliseconds, max 600000)
+ */
+export async function GET(request: Request): Promise<Response> {
+  const cronSecret = process.env.CRON_SECRET;
+  if (!cronSecret) {
+    console.error("[slack-socket-mode] CRON_SECRET not configured");
+    return new Response("CRON_SECRET not configured", { status: 500 });
+  }
+  const authHeader = request.headers.get("authorization");
+  if (authHeader !== `Bearer ${cronSecret}`) {
+    console.log("[slack-socket-mode] Unauthorized: invalid CRON_SECRET");
+    return new Response("Unauthorized", { status: 401 });
+  }
+
+  await bot.initialize();
+
+  const slack = bot.getAdapter("slack");
+  if (!slack) {
+    console.log("[slack-socket-mode] Slack adapter not configured");
+    return new Response("Slack adapter not configured", { status: 404 });
+  }
+
+  // Construct webhook URL for forwarding socket events
+  const baseUrl =
+    process.env.VERCEL_PROJECT_PRODUCTION_URL ||
+    process.env.VERCEL_URL ||
+    process.env.NEXT_PUBLIC_BASE_URL;
+  let webhookUrl: string | undefined;
+  if (baseUrl) {
+    const bypassSecret = process.env.VERCEL_AUTOMATION_BYPASS_SECRET;
+    const queryParam = bypassSecret
+      ? `?x-vercel-protection-bypass=${bypassSecret}`
+      : "";
+    webhookUrl = `https://${baseUrl}/api/webhooks/slack${queryParam}`;
+  }
+
+  return slackSocketMode.start(request, {
+    afterTask: (task) => after(() => task),
+    run: async ({ abortSignal, durationMs, listenerId }) => {
+      console.log(
+        `[slack-socket-mode] Starting Socket Mode listener: ${listenerId}`,
+        {
+          webhookUrl: webhookUrl ? "configured" : "not configured",
+          durationMs,
+        }
+      );
+
+      const response = await slack.startSocketModeListener(
+        { waitUntil: (task: Promise<unknown>) => after(() => task) },
+        durationMs,
+        abortSignal,
+        webhookUrl
+      );
+
+      console.log(
+        `[slack-socket-mode] Socket Mode listener ${listenerId} completed with status: ${response.status}`
+      );
+
+      return response;
+    },
+  });
+}

examples/nextjs-chat/vercel.json

@@ -4,6 +4,10 @@
     {
       "path": "/api/discord/gateway",
       "schedule": "*/9 * * * *"
+    },
+    {
+      "path": "/api/slack/socket-mode",
+      "schedule": "*/9 * * * *"
     }
   ]
 }

packages/adapter-slack/README.md

@@ -102,6 +102,86 @@ openssl rand -base64 32
 
 When `encryptionKey` is set, `setInstallation()` encrypts the token before storing and `getInstallation()` decrypts it transparently.
 
+## Socket mode
+
+For environments behind firewalls that can't expose public HTTP endpoints, the adapter supports [Slack Socket Mode](https://api.slack.com/apis/socket-mode). Instead of receiving webhooks, the adapter connects to Slack over a WebSocket.
+
+```typescript
+import { Chat } from "chat";
+import { createSlackAdapter } from "@chat-adapter/slack";
+
+const bot = new Chat({
+  userName: "mybot",
+  adapters: {
+    slack: createSlackAdapter({
+      mode: "socket",
+      appToken: process.env.SLACK_APP_TOKEN!,
+      botToken: process.env.SLACK_BOT_TOKEN!,
+    }),
+  },
+});
+```
+
+### Slack app setup for socket mode
+
+1. Go to your app's settings at [api.slack.com/apps](https://api.slack.com/apps)
+2. Navigate to **Socket Mode** and enable it
+3. Generate an **App-Level Token** with the `connections:write` scope — this is your `SLACK_APP_TOKEN` (`xapp-...`)
+4. Event subscriptions and interactivity still need to be configured, but no public request URL is required
+
+> Socket mode is not compatible with multi-workspace OAuth (`clientId`/`clientSecret`). It's designed for single-workspace deployments.
+
+### Socket mode on serverless (Vercel)
+
+Socket mode requires a persistent WebSocket connection, which doesn't fit the request/response model of serverless functions. The adapter provides a forwarding mechanism to bridge this gap:
+
+1. A cron job periodically starts a transient socket listener
+2. The listener connects via WebSocket, acks events immediately, and forwards them as HTTP requests to your webhook endpoint
+3. Your existing webhook route processes the forwarded events normally
+
+```typescript
+// api/slack/socket-mode/route.ts
+import { after } from "next/server";
+import { bot } from "@/lib/bot";
+
+export const maxDuration = 800;
+
+export async function GET(request: Request) {
+  const authHeader = request.headers.get("authorization");
+  if (authHeader !== `Bearer ${process.env.CRON_SECRET}`) {
+    return new Response("Unauthorized", { status: 401 });
+  }
+
+  await bot.initialize();
+
+  const slack = bot.getAdapter("slack");
+  const webhookUrl = `https://${process.env.VERCEL_URL}/api/webhooks/slack`;
+
+  return slack.startSocketModeListener(
+    { waitUntil: (task: Promise<unknown>) => after(() => task) },
+    600_000, // 10 minutes
+    undefined,
+    webhookUrl
+  );
+}
+```
+
+Schedule the cron job to run every 9 minutes (overlapping with the 10-minute listener duration) to maintain continuous coverage:
+
+```json
+// vercel.json
+{
+  "crons": [
+    {
+      "path": "/api/slack/socket-mode",
+      "schedule": "*/9 * * * *"
+    }
+  ]
+}
+```
+
+Forwarded events are authenticated using the `socketForwardingSecret` config option (defaults to `SLACK_SOCKET_FORWARDING_SECRET` env var, falling back to `appToken`).
+
 ## Slack app setup
 
 ### 1. Create a Slack app from manifest
@@ -188,19 +268,25 @@ All options are auto-detected from environment variables when not provided. You
 |--------|----------|-------------|
 | `botToken` | No | Bot token (`xoxb-...`). Auto-detected from `SLACK_BOT_TOKEN` |
 | `signingSecret` | No* | Signing secret for webhook verification. Auto-detected from `SLACK_SIGNING_SECRET` |
+| `mode` | No | Connection mode: `"webhook"` (default) or `"socket"` |
+| `appToken` | No** | App-level token (`xapp-...`) for socket mode. Auto-detected from `SLACK_APP_TOKEN` |
+| `socketForwardingSecret` | No | Shared secret for authenticating forwarded socket events. Auto-detected from `SLACK_SOCKET_FORWARDING_SECRET`, falls back to `appToken` |
 | `clientId` | No | App client ID for multi-workspace OAuth. Auto-detected from `SLACK_CLIENT_ID` |
 | `clientSecret` | No | App client secret for multi-workspace OAuth. Auto-detected from `SLACK_CLIENT_SECRET` |
 | `encryptionKey` | No | AES-256-GCM key for encrypting stored tokens. Auto-detected from `SLACK_ENCRYPTION_KEY` |
 | `installationKeyPrefix` | No | Prefix for the state key used to store workspace installations. Defaults to `slack:installation`. The full key is `{prefix}:{teamId}` |
 | `logger` | No | Logger instance (defaults to `ConsoleLogger("info")`) |
 
-*`signingSecret` is required — either via config or `SLACK_SIGNING_SECRET` env var.
+*`signingSecret` is required for webhook mode — either via config or `SLACK_SIGNING_SECRET` env var.
+**`appToken` is required for socket mode — either via config or `SLACK_APP_TOKEN` env var.
 
 ## Environment variables
 
 ```bash
 SLACK_BOT_TOKEN=xoxb-...             # Single-workspace only
-SLACK_SIGNING_SECRET=...
+SLACK_SIGNING_SECRET=...             # Required for webhook mode
+SLACK_APP_TOKEN=xapp-...             # Required for socket mode
+SLACK_SOCKET_FORWARDING_SECRET=...   # Optional, for socket event forwarding auth
 SLACK_CLIENT_ID=...                  # Multi-workspace only
 SLACK_CLIENT_SECRET=...              # Multi-workspace only
 SLACK_ENCRYPTION_KEY=...             # Optional, for token encryption

packages/adapter-slack/package.json

@@ -25,6 +25,7 @@
   },
   "dependencies": {
     "@chat-adapter/shared": "workspace:*",
+    "@slack/socket-mode": "^2.0.5",
     "@slack/web-api": "^7.14.0",
     "chat": "workspace:*"
   },