Connect Slack

Wire a Slack workspace to your Mumega agents using the Socket Mode connector. Inbound messages route to the bus; replies route back to Slack.

The Mumega Slack connector is a Socket Mode adapter. Slack events become SOS bus send calls; agent replies route back to Slack. The connector runs as a persistent process on your VPS or laptop.

#How it works

#Inbound path

Slack event (app_mention / DM / /mumega slash command)
  → handle_inbound()
  → normalize to InboundMessage with [request_id:<uuid>]
  → mcp send {to: <mapped-agent>, text: <message + context>}
  → agent inbox on the SOS bus

The connector sends under its own bus identity (CONNECTOR_AGENT_NAME) to the Mumega agent mapped for that Slack channel. Mapping is MUMEGA_AGENT_MAP (JSON env var) with MUMEGA_DEFAULT_AGENT as fallback.

Each inbound message generates a UUID, stored alongside the Slack channel and thread context before the bus send. This lets the reply loop recover the exact thread to reply into.

#Reply path

SOS bus inbox (connector's stream)
  → reply_poller_loop (every POLL_INTERVAL seconds)
  → match {ack_for:<uuid>} to stored Slack context
  → strip ack token + ctx block from reply text
  → post_slack_message(channel, text, thread_ts)

The reply path is correlation-based: the connector prepends [request_id:<uuid>] to every inbound message on the bus and instructs the agent to reply addressed to slack-connector with {ack_for:<uuid>}. When the poller sees a matching ACK, it recovers the stored Slack channel and thread and posts the reply directly.

One honest edge: if an agent replies without {ack_for} and without echoing the fallback <!--mumega-slack-ctx:--> block, that specific reply is skipped. The clean fix — a dedicated reply-context field on the bus envelope — is in progress. Agents that follow the standard bus ACK protocol route correctly every time.

#Create the Slack app

1. Go to api.slack.com/apps → Create New App → From Manifest.
2. Upload or paste connectors/slack/slack-app-manifest.yaml from the repo.
3. Install to your workspace.
4. Under Basic Information → App-Level Tokens: generate a token with connections:write scope. This is SLACK_APP_TOKEN (starts xapp-).
5. Under OAuth & Permissions: copy the Bot User OAuth Token. This is SLACK_BOT_TOKEN (starts xoxb-).
6. Get your MUMEGA_BUS_TOKEN from Kasra (one token per connector instance, registered as agent:slack-connector on the bus).

#Setup and run

cd connectors/slack

# 1. Create and activate a virtualenv
python3 -m venv venv
source venv/bin/activate

# 2. Install deps
pip install -r requirements.txt

# 3. Configure env
cp .env.example .env
# Edit .env with your tokens

# 4. Self-check (validates config, no network connections)
python slack_connector.py --check

# 5. Dry-run (loads config + logs events, no live connections)
DRY_RUN=1 python slack_connector.py

# 6. Start live
python slack_connector.py

Keep the connector in a tmux pane or wrap it in launchd for production.

#Config reference

#Security

• Tokens are never logged. Redaction uses direct string indexing (token[-8:]), never regex.
• .env is gitignored.
• The connector runs fully outbound — no inbound port, no webhook URL.
• Only app_mention, DM, and /mumega slash command events are forwarded. Bot messages and raw channel events are discarded.

#Run tests

source venv/bin/activate
pytest connectors/slack/tests/ -v

Tests are pure-unit — no Slack SDK, no bus, no network.

#Next step: Cloudflare Worker (no persistent process)

Socket Mode is the right choice for a VPS or Mac operator. When you want to run without a persistent process, switch to webhook mode:

• socket_mode_enabled: false in the Slack manifest
• Set a Request URL pointing to a /api/slack/events Cloudflare Worker route
• Handle the event in a Hono handler on the Worker

This path is not built yet — it is the natural next step for the connector.