feat: Slack and Discord service integrations

[joshupadhyay]

Summary

Adds Slack and Discord as reef service modules — bidirectional messaging, proactive event notifications, and a centralized notifications architecture.

Currently, this creates a new chat in 'reef' for each thread you have with the bot. The bot will start a thread to each message (not each channel). This way, the context from the thread is passed cleanly via a thread id.

@Claude works slightly differently:

Claude Code pulls information contextually, which we can totally adjust to. I just found this as a better MVP. In this implementation, each thread becomes a new chat in the reef. That way the context for the chat -> is the thread.

usage:

message the reef about discord / slack
use the invite code, add the bot
tag the bot @username!
to continue conversations with a certain context, start a thread and keep replying.

• Discord: Gateway WebSocket for receiving @mentions and DMs, reaction acknowledgment (👀→✅/❌), conversation persistence per channel
• Slack: Socket Mode for receiving @mentions and DMs, reaction acknowledgment (eyes→check/x), threaded replies, conversation persistence per channel
• Notifications service: Centralized event filtering and push — subscribes to reef events, applies heuristic (skip <30s tasks, skip bot-originated, always notify errors), emits to all channels
• Shared modules: services/shared/messaging.ts (reef submit, event bus wait, tag stripping, message splitting) and services/shared/config.ts (cached vers-config resolution, shared across all services)
• Event bus architecture: Task completion waiting uses the in-process ServiceEventBus instead of HTTP polling — zero network overhead, no timeout, instant notification

What works today

• Discord bot receives messages via Gateway, submits to reef, replies with full output
• Slack bot receives messages via Socket Mode, submits to reef, replies in-thread
• Both bots acknowledge receipt with emoji reactions, swap to ✅/❌ on completion
• Messages in the same channel continue the same reef conversation (context preserved)
• Smart notification filtering: only notifies for tasks >30s, errors, or file changes
• Notification channel configurable per platform via tools or API
• Bot token resolution: env var (provision time) → vers-config store (runtime)
• No polling — uses ServiceEventBus for task completion (was 240 HTTP requests per message, now 0)
• No timeout — tasks wait as long as they take (reef guarantees task_done/task_error on every task)

What still needs to be done

Official Vers bots

Currently uses BYO tokens — each user creates their own Discord app / Slack app. The target state:

• Discord: Vers creates one bot. Users click an invite link to add it. Token injected at provision time. GET /discord/invite route exists with placeholder DISCORD_APP_ID.
• Slack: Vers creates one Slack app with OAuth distribution. Users click "Add to Slack." Vers backend needs an OAuth callback endpoint (vers.sh/api/slack/oauth/callback) to store per-workspace tokens.

See DISCORD_INTEGRATION_PLAN.md for the full migration plan.

Slack reactions

Slack reactions (👀→✅/❌) require the reactions:write scope. Need to add to required scopes and verify.

Reef agent instructions

When a user asks for Discord or Slack integration, the reef agent should return an invite/install link for the official Vers bot instead of BYO-token instructions.

Architecture

ServiceEventBus (in-process, no network)
  → Notifications service (filter + format + batch)
    → notification:push event
      → Discord service (forward to channel)
      → Slack service (forward to channel)

Task completion flow (event bus, not polling):
  User messages bot
    → submit to reef
    → eventBus.on("reef:event", { taskId }) — waits for matching task_done
    → reef fires event when agent finishes
    → callback resolves instantly, reply posted

Discord Gateway ← WebSocket → reef
  User @mentions → 👀 react → submit to reef → wait → reply + ✅

Slack Socket Mode ← WebSocket → reef
  User @mentions/DMs → 👀 react → submit to reef → wait → reply in-thread + ✅

New files

File	Description
services/discord/index.ts	Discord service — Gateway, routes, tools, notification forwarding
services/discord/SETUP.md	Setup guide for Discord integration
services/discord/DISCORD_BOT.md	Notification heuristic (what to post vs skip)
services/discord/DISCORD_INTEGRATION_PLAN.md	Official Vers bot migration plan
services/slack/index.ts	Slack service — Socket Mode, routes, tools, notification forwarding
services/slack/SETUP.md	Setup guide for Slack integration
services/notifications/index.ts	Centralized notification service — event filtering, batching, history
services/notifications/SETUP.md	Notifications service documentation
services/shared/messaging.ts	Shared helpers — reef submit, event bus wait, tag stripping, message splitting
services/shared/config.ts	Shared config — cached vers-config resolution, escapeHtml

Modified files

File	Change
services/vers-config/index.ts	Allowlist expanded for integration tokens and notification config
src/reef.ts	Emit task_done/task_error on ServiceEventBus (was SSE-only) + enriched payloads with duration/trigger

Environment variables

Discord

Variable	Required	Description
DISCORD_BOT_TOKEN	Yes	Discord Bot Token
DISCORD_APP_ID	No	For invite link generation (placeholder until official bot)
DISCORD_NOTIFICATION_CHANNEL_ID	No	Channel for proactive notifications

Slack

Variable	Required	Description
SLACK_BOT_TOKEN	Yes	Bot User OAuth Token (xoxb-...)
SLACK_APP_TOKEN	Yes (for receiving messages)	App-Level Token with connections:write (xapp-...)
SLACK_NOTIFICATION_CHANNEL	No	Channel for proactive notifications

Notifications

Variable	Description
NOTIFICATION_MUTE	"true" to mute all notifications globally
NOTIFICATION_MIN_DURATION_MS	Minimum task duration to notify (default: 30000)

Slack bot required scopes

chat:write, chat:write.public, channels:read, channels:history, im:history, im:read, im:write, app_mentions:read, reactions:read, reactions:write, users:read

Slack required event subscriptions

app_mention, message.im

Slack required settings

Socket Mode: ON, App Home > Chat Tab: ON, "Allow users to send Slash commands and messages from the chat tab": checked

🤖 Generated with Claude Code

[joshupadhyay]

new ENV vars with varying notif levels, I'm sure we can pare these down but

[joshupadhyay]

chat with bot, tells you about connected discord / slack

[joshupadhyay]

uses threads exclusively, to ensure context is preserved. Will react to messages when tagged!

(it's not called test-bot anymore :) )

[joshupadhyay]

discord, slack bots look good as well.