agent-relay 1.1.0 → 1.2.3

package/docs/proposals/slack-bot-integration.md

@@ -1,1457 +0,0 @@
-# Slack Bot Integration Proposal
-
-**Author:** Claude
-**Date:** 2025-12-30
-**Status:** Draft
-**Estimated Effort:** 5-7 days
-
----
-
-## Executive Summary
-
-This proposal outlines a plan to integrate agent-relay messaging with Slack, following the **cloud-first architecture** established in PR #35. The integration enables:
-
-- AI agents to communicate in Slack channels alongside humans
-- Humans to interact with agents via @mentions and slash commands
-- Real-time bidirectional sync between relay daemon and Slack
-- Thread preservation across both systems
-- **Cloud-managed OAuth and credentials** via Nango integration platform
-- **Multi-workspace support** through the daemon orchestrator
-- **Plan-based access** (Pro/Team/Enterprise tiers)
-
----
-
-## Table of Contents
-
-1. [Goals & Non-Goals](#1-goals--non-goals)
-2. [Architecture Overview](#2-architecture-overview)
-3. [Cloud Components](#3-cloud-components)
-4. [Daemon Components](#4-daemon-components)
-5. [Database Schema](#5-database-schema)
-6. [Dashboard UI](#6-dashboard-ui)
-7. [Implementation Phases](#7-implementation-phases)
-8. [API Specifications](#8-api-specifications)
-9. [Security & Plan Limits](#9-security--plan-limits)
-10. [Testing Strategy](#10-testing-strategy)
-11. [Open Questions](#11-open-questions)
-
----
-
-## 1. Goals & Non-Goals
-
-### Goals
-
-| Goal | Description |
-|------|-------------|
-| **Cloud-managed credentials** | Slack OAuth tokens stored in encrypted vault, not local files |
-| **Multi-workspace support** | Each workspace can have its own Slack integration |
-| **Bidirectional messaging** | Messages flow Slack ↔ Relay in real-time |
-| **Thread preservation** | Relay threads map to Slack threads and vice versa |
-| **Plan-gated access** | Slack integration available on Pro+ plans |
-| **Dashboard configuration** | Connect/disconnect Slack via UI |
-| **Self-hosted parity** | Works in cloud-hosted, self-hosted, and hybrid modes |
-
-### Non-Goals (v1)
-
-| Non-Goal | Rationale |
-|----------|-----------|
-| Multi-Slack-workspace per relay workspace | Complexity; one Slack workspace per relay workspace |
-| Slack-only agents | Agents should exist in relay first |
-| Rich Block Kit formatting | Plain text first; enhance later |
-| Slack Enterprise Grid | Requires org-level OAuth; v2 |
-
----
-
-## 2. Architecture Overview
-
-### High-Level Design (Cloud Paradigm)
-
-```
-┌─────────────────────────────────────────────────────────────────────────────┐
-│                              SLACK WORKSPACE                                 │
-│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐                         │
-│  │ #agents     │  │ #alerts     │  │ @agent-bot  │                         │
-│  └──────┬──────┘  └──────┬──────┘  └──────┬──────┘                         │
-│         └────────────────┴────────────────┘                                 │
-│                          │                                                  │
-│                    Slack Events API (Socket Mode)                           │
-└──────────────────────────┼──────────────────────────────────────────────────┘
-                           │
-                           ▼
-┌──────────────────────────────────────────────────────────────────────────────┐
-│                         AGENT RELAY CLOUD                                    │
-│                                                                              │
-│  ┌────────────────────────────────────────────────────────────────────────┐ │
-│  │                        src/cloud/                                      │ │
-│  │  ┌──────────────────┐  ┌──────────────────┐  ┌──────────────────┐    │ │
-│  │  │ api/integrations │  │ services/slack   │  │ Nango            │    │ │
-│  │  │ /slack.ts        │  │ SlackService     │  │ (external)       │    │ │
-│  │  │                  │  │                  │  │                  │    │ │
-│  │  │ • OAuth trigger  │  │ • Token fetch    │  │ • OAuth flow     │    │ │
-│  │  │ • Disconnect     │  │ • Workspace sync │  │ • Token storage  │    │ │
-│  │  │ • Status         │  │ • Health check   │  │ • Auto refresh   │    │ │
-│  │  └──────────────────┘  └──────────────────┘  └──────────────────┘    │ │
-│  │                                                                        │ │
-│  │  ┌──────────────────┐  ┌──────────────────┐                           │ │
-│  │  │ db/schema.ts     │  │ api/middleware/  │                           │ │
-│  │  │                  │  │ planLimits.ts    │                           │ │
-│  │  │ • slack_integrations│ • requirePro()  │                           │ │
-│  │  │ • slack_channels │  │ • checkSlackLimit│                           │ │
-│  │  └──────────────────┘  └──────────────────┘                           │ │
-│  └────────────────────────────────────────────────────────────────────────┘ │
-│                                    │                                        │
-│                              Cloud Sync API                                 │
-│                                    │                                        │
-└────────────────────────────────────┼────────────────────────────────────────┘
-                                     │
-                                     ▼
-┌──────────────────────────────────────────────────────────────────────────────┐
-│                         LOCAL DAEMON                                         │
-│                                                                              │
-│  ┌────────────────────────────────────────────────────────────────────────┐ │
-│  │                        src/daemon/                                     │ │
-│  │  ┌──────────────────┐  ┌──────────────────┐  ┌──────────────────┐    │ │
-│  │  │ orchestrator.ts  │  │ slack-bridge.ts  │  │ cloud-sync.ts    │    │ │
-│  │  │                  │  │ (NEW)            │  │                  │    │ │
-│  │  │ • Manages        │  │                  │  │ • Pulls Slack    │    │ │
-│  │  │   workspaces     │  │ • Slack ↔ Relay  │  │   credentials    │    │ │
-│  │  │ • Starts bridge  │  │ • Thread mapping │  │ • Syncs config   │    │ │
-│  │  │   per workspace  │  │ • Event handling │  │ • Token refresh  │    │ │
-│  │  └──────────────────┘  └──────────────────┘  └──────────────────┘    │ │
-│  │                                                                        │ │
-│  │  ┌──────────────────┐  ┌──────────────────┐                           │ │
-│  │  │ router.ts        │  │ agent-manager.ts │                           │ │
-│  │  │                  │  │                  │                           │ │
-│  │  │ • Routes msgs    │  │ • Agent lifecycle│                           │ │
-│  │  │ • SlackBridge    │  │ • Health monitor │                           │ │
-│  │  │   as agent       │  │                  │                           │ │
-│  │  └──────────────────┘  └──────────────────┘                           │ │
-│  └────────────────────────────────────────────────────────────────────────┘ │
-│                                    │                                        │
-│                            Unix Domain Socket                               │
-│                                    │                                        │
-│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐        │
-│  │   Alice     │  │    Bob      │  │ SlackBridge │  │  Dashboard  │        │
-│  │  (Claude)   │  │  (Claude)   │  │  (daemon)   │  │  (observer) │        │
-│  └─────────────┘  └─────────────┘  └─────────────┘  └─────────────┘        │
-└──────────────────────────────────────────────────────────────────────────────┘
-```
-
-### Deployment Model Alignment
-
-| Mode | How Slack Integration Works |
-|------|----------------------------|
-| **Cloud Hosted** | OAuth via cloud, credentials in vault, daemon bridge runs in cloud workspace |
-| **Self-Hosted** | OAuth via cloud servers, credentials synced to local daemon |
-| **Hybrid/Local** | OAuth via cloud, daemon runs locally with synced credentials |
-
-This follows the same pattern as provider credentials (Claude API keys, etc.) established in PR #35.
-
----
-
-## 3. Cloud Components
-
-### 3.1 Nango Integration
-
-[Nango](https://www.nango.dev/) handles all OAuth complexity:
-- OAuth flow (authorization URL, token exchange)
-- Secure token storage (encrypted at rest)
-- Automatic token refresh before expiry
-- Connection status monitoring
-
-**Nango Setup:**
-```yaml
-# nango.yaml - Integration configuration
-integrations:
-  slack:
-    provider: slack
-    syncs: []
-    actions:
-      - name: post-message
-      - name: list-channels
-    scopes:
-      - app_mentions:read
-      - channels:history
-      - channels:read
-      - chat:write
-      - groups:history
-      - groups:read
-      - im:history
-      - im:read
-      - im:write
-      - users:read
-```
-
-### 3.2 API Routes (`src/cloud/api/integrations/slack.ts`)
-
-```typescript
-// src/cloud/api/integrations/slack.ts
-
-import { Router } from 'express';
-import { Nango } from '@nangohq/node';
-import { requireAuth } from '../middleware/auth';
-import { requirePlan } from '../middleware/planLimits';
-import { SlackService } from '../../services/slack';
-import { db, eq } from '../../db';
-import { slackIntegrations } from '../../db/schema';
-
-const router = Router();
-const nango = new Nango({ secretKey: process.env.NANGO_SECRET_KEY });
-
-// All Slack routes require Pro+ plan
-router.use(requireAuth, requirePlan('pro'));
-
-/**
- * GET /api/integrations/slack/status
- * Get Slack integration status for current workspace
- */
-router.get('/status', async (req, res) => {
-  const { workspaceId } = req.query;
-
-  const integration = await db.query.slackIntegrations.findFirst({
-    where: eq(slackIntegrations.workspaceId, workspaceId),
-  });
-
-  if (!integration) {
-    return res.json({ connected: false });
-  }
-
-  // Check Nango connection status
-  try {
-    const connection = await nango.getConnection('slack', integration.nangoConnectionId);
-
-    res.json({
-      connected: true,
-      valid: connection.credentials?.access_token != null,
-      slackWorkspace: integration.slackWorkspaceName,
-      slackTeamId: integration.slackTeamId,
-      channels: {
-        broadcast: integration.broadcastChannel,
-        alerts: integration.alertsChannel,
-      },
-      connectedAt: integration.createdAt,
-      connectedBy: integration.connectedByUserId,
-    });
-  } catch (error) {
-    res.json({ connected: true, valid: false, error: 'Token expired' });
-  }
-});
-
-/**
- * GET /api/integrations/slack/connect
- * Get Nango connect URL for Slack OAuth
- */
-router.get('/connect', async (req, res) => {
-  const { workspaceId } = req.query;
-
-  // Generate unique connection ID for this workspace
-  const connectionId = `workspace-${workspaceId}-slack`;
-
-  // Nango handles the entire OAuth flow
-  const connectUrl = await nango.auth('slack', connectionId, {
-    detectClosedAuthWindow: true,
-  });
-
-  // Store pending connection
-  await db.insert(slackIntegrations).values({
-    id: generateId(),
-    workspaceId,
-    nangoConnectionId: connectionId,
-    status: 'pending',
-    connectedByUserId: req.user.id,
-  }).onConflictDoUpdate({
-    target: slackIntegrations.workspaceId,
-    set: { status: 'pending', updatedAt: new Date() },
-  });
-
-  res.json({ connectUrl });
-});
-
-/**
- * POST /api/integrations/slack/webhook
- * Nango webhook for connection events
- */
-router.post('/webhook', async (req, res) => {
-  const { type, connectionId, provider } = req.body;
-
-  if (provider !== 'slack') {
-    return res.json({ ok: true });
-  }
-
-  // Extract workspaceId from connectionId
-  const match = connectionId.match(/^workspace-(.+)-slack$/);
-  if (!match) {
-    return res.status(400).json({ error: 'Invalid connection ID' });
-  }
-  const workspaceId = match[1];
-
-  if (type === 'auth') {
-    // OAuth completed - fetch team info
-    const connection = await nango.getConnection('slack', connectionId);
-    const teamInfo = connection.connection_config?.team;
-
-    await db.update(slackIntegrations)
-      .set({
-        status: 'connected',
-        slackTeamId: teamInfo?.id,
-        slackWorkspaceName: teamInfo?.name,
-        updatedAt: new Date(),
-      })
-      .where(eq(slackIntegrations.workspaceId, workspaceId));
-
-    // Notify daemon to connect
-    await SlackService.notifyDaemonConnect(workspaceId);
-  }
-
-  if (type === 'token_refreshed') {
-    // Token was refreshed - notify daemon to reconnect
-    await SlackService.notifyDaemonReconnect(workspaceId);
-  }
-
-  res.json({ ok: true });
-});
-
-/**
- * POST /api/integrations/slack/disconnect
- * Disconnect Slack integration
- */
-router.post('/disconnect', async (req, res) => {
-  const { workspaceId } = req.body;
-
-  const integration = await db.query.slackIntegrations.findFirst({
-    where: eq(slackIntegrations.workspaceId, workspaceId),
-  });
-
-  if (!integration) {
-    return res.status(404).json({ error: 'No Slack integration found' });
-  }
-
-  // Delete connection from Nango (revokes token)
-  await nango.deleteConnection('slack', integration.nangoConnectionId);
-
-  // Delete integration record
-  await db.delete(slackIntegrations)
-    .where(eq(slackIntegrations.id, integration.id));
-
-  // Notify daemon to disconnect
-  await SlackService.notifyDaemonDisconnect(workspaceId);
-
-  res.json({ success: true });
-});
-
-/**
- * PUT /api/integrations/slack/config
- * Update Slack integration configuration
- */
-router.put('/config', async (req, res) => {
-  const { workspaceId, broadcastChannel, alertsChannel, showAgentToAgent, showThinking } = req.body;
-
-  await db.update(slackIntegrations)
-    .set({
-      broadcastChannel,
-      alertsChannel,
-      config: { showAgentToAgent, showThinking },
-      updatedAt: new Date(),
-    })
-    .where(eq(slackIntegrations.workspaceId, workspaceId));
-
-  // Notify daemon to reload config
-  await SlackService.notifyDaemonConfigUpdate(workspaceId);
-
-  res.json({ success: true });
-});
-
-/**
- * GET /api/integrations/slack/channels
- * List available Slack channels for configuration
- */
-router.get('/channels', async (req, res) => {
-  const { workspaceId } = req.query;
-
-  const channels = await SlackService.listChannels(workspaceId);
-  res.json({ channels });
-});
-
-export default router;
-```
-
-### 3.3 Slack Service (`src/cloud/services/slack.ts`)
-
-```typescript
-// src/cloud/services/slack.ts
-
-import { Nango } from '@nangohq/node';
-import { WebClient } from '@slack/web-api';
-import { db, eq } from '../db';
-import { slackIntegrations } from '../db/schema';
-
-const nango = new Nango({ secretKey: process.env.NANGO_SECRET_KEY });
-
-export class SlackService {
-  /**
-   * Get Slack access token from Nango
-   * Nango automatically refreshes expired tokens
-   */
-  static async getAccessToken(workspaceId: string): Promise<string | null> {
-    const integration = await db.query.slackIntegrations.findFirst({
-      where: eq(slackIntegrations.workspaceId, workspaceId),
-    });
-
-    if (!integration?.nangoConnectionId) return null;
-
-    try {
-      const connection = await nango.getConnection('slack', integration.nangoConnectionId);
-      return connection.credentials?.access_token || null;
-    } catch {
-      return null;
-    }
-  }
-
-  /**
-   * List channels the bot can access
-   */
-  static async listChannels(workspaceId: string): Promise<SlackChannel[]> {
-    const token = await this.getAccessToken(workspaceId);
-    if (!token) throw new Error('No Slack connection found');
-
-    const client = new WebClient(token);
-    const result = await client.conversations.list({
-      types: 'public_channel,private_channel',
-      exclude_archived: true,
-    });
-
-    return result.channels?.map(ch => ({
-      id: ch.id!,
-      name: ch.name!,
-      isPrivate: ch.is_private || false,
-      isMember: ch.is_member || false,
-    })) || [];
-  }
-
-  /**
-   * Get credentials for daemon sync
-   * Called by daemon cloud-sync to retrieve Slack config
-   */
-  static async getCredentialsForDaemon(workspaceId: string): Promise<SlackDaemonConfig | null> {
-    const integration = await db.query.slackIntegrations.findFirst({
-      where: eq(slackIntegrations.workspaceId, workspaceId),
-    });
-
-    if (!integration?.nangoConnectionId) return null;
-
-    try {
-      const connection = await nango.getConnection('slack', integration.nangoConnectionId);
-
-      if (!connection.credentials?.access_token) return null;
-
-      return {
-        botToken: connection.credentials.access_token,
-        // App token for Socket Mode - stored in connection metadata or env
-        appToken: process.env.SLACK_APP_TOKEN,
-        teamId: integration.slackTeamId!,
-        teamName: integration.slackWorkspaceName!,
-        broadcastChannel: integration.broadcastChannel,
-        alertsChannel: integration.alertsChannel,
-        config: integration.config || {},
-      };
-    } catch {
-      return null;
-    }
-  }
-
-  /**
-   * Notify daemon of Slack connection changes
-   */
-  static async notifyDaemonConnect(workspaceId: string): Promise<void> {
-    await this.sendDaemonNotification(workspaceId, 'slack:connect');
-  }
-
-  static async notifyDaemonDisconnect(workspaceId: string): Promise<void> {
-    await this.sendDaemonNotification(workspaceId, 'slack:disconnect');
-  }
-
-  static async notifyDaemonConfigUpdate(workspaceId: string): Promise<void> {
-    await this.sendDaemonNotification(workspaceId, 'slack:config-update');
-  }
-
-  static async notifyDaemonReconnect(workspaceId: string): Promise<void> {
-    await this.sendDaemonNotification(workspaceId, 'slack:reconnect');
-  }
-
-  private static async sendDaemonNotification(workspaceId: string, event: string): Promise<void> {
-    // Implementation depends on daemon connection method
-    // Could be WebSocket push, Redis pub/sub, or polling
-  }
-}
-
-interface SlackChannel {
-  id: string;
-  name: string;
-  isPrivate: boolean;
-  isMember: boolean;
-}
-
-interface SlackDaemonConfig {
-  botToken: string;
-  appToken: string;
-  teamId: string;
-  teamName: string;
-  broadcastChannel: string | null;
-  alertsChannel: string | null;
-  config: {
-    showAgentToAgent?: boolean;
-    showThinking?: boolean;
-  };
-}
-```
-
-### 3.4 Why Nango?
-
-| Concern | Without Nango | With Nango |
-|---------|---------------|------------|
-| OAuth flow | Custom implementation | Hosted UI, handles edge cases |
-| Token storage | Custom vault, encryption | Encrypted at rest, compliant |
-| Token refresh | Manual refresh logic | Automatic, before expiry |
-| Multiple providers | Per-provider code | Unified API |
-| Maintenance | Security updates needed | Managed service |
-
-**Dependencies:**
-```json
-{
-  "dependencies": {
-    "@nangohq/node": "^0.40.0"
-  }
-}
-```
-
----
-
-## 4. Daemon Components
-
-### 4.1 Slack Bridge (`src/daemon/slack-bridge.ts`)
-
-```typescript
-// src/daemon/slack-bridge.ts
-
-import { App, LogLevel } from '@slack/bolt';
-import { RelayClient } from '../wrapper/client';
-import { SlackThreadStore } from './slack-thread-store';
-import { SlackMessageFormatter } from './slack-formatter';
-import { logger } from '../resiliency/logger';
-
-export interface SlackBridgeConfig {
-  botToken: string;
-  appToken: string;
-  teamId: string;
-  teamName: string;
-  broadcastChannel: string | null;
-  alertsChannel: string | null;
-  config: {
-    showAgentToAgent?: boolean;
-    showThinking?: boolean;
-  };
-  // Relay connection
-  socketPath: string;
-  workspaceId: string;
-}
-
-export class SlackBridge {
-  private slackApp: App | null = null;
-  private relayClient: RelayClient | null = null;
-  private threadStore: SlackThreadStore;
-  private formatter: SlackMessageFormatter;
-  private config: SlackBridgeConfig;
-  private running = false;
-
-  constructor(config: SlackBridgeConfig) {
-    this.config = config;
-    this.threadStore = new SlackThreadStore();
-    this.formatter = new SlackMessageFormatter();
-  }
-
-  async start(): Promise<void> {
-    if (this.running) return;
-
-    logger.info('Starting Slack bridge', {
-      workspaceId: this.config.workspaceId,
-      slackTeam: this.config.teamName,
-    });
-
-    // 1. Initialize Slack App (Socket Mode)
-    this.slackApp = new App({
-      token: this.config.botToken,
-      appToken: this.config.appToken,
-      socketMode: true,
-      logLevel: LogLevel.WARN,
-    });
-
-    // 2. Register event handlers
-    this.registerSlackHandlers();
-
-    // 3. Connect to local relay daemon
-    this.relayClient = new RelayClient({
-      socketPath: this.config.socketPath,
-      agentName: 'SlackBridge',
-      cli: 'slack',
-      reconnect: true,
-    });
-
-    this.relayClient.onMessage = this.onRelayMessage.bind(this);
-    this.relayClient.onStateChange = this.onRelayStateChange.bind(this);
-
-    await this.relayClient.connect();
-
-    // 4. Subscribe to all messages
-    this.relayClient.subscribe('*');
-
-    // 5. Start Slack app
-    await this.slackApp.start();
-
-    this.running = true;
-    logger.info('Slack bridge started successfully');
-  }
-
-  async stop(): Promise<void> {
-    if (!this.running) return;
-
-    logger.info('Stopping Slack bridge');
-
-    if (this.slackApp) {
-      await this.slackApp.stop();
-      this.slackApp = null;
-    }
-
-    if (this.relayClient) {
-      await this.relayClient.disconnect();
-      this.relayClient = null;
-    }
-
-    this.running = false;
-  }
-
-  async updateConfig(newConfig: Partial<SlackBridgeConfig>): Promise<void> {
-    // Update config without full restart for channel changes
-    this.config = { ...this.config, ...newConfig };
-    logger.info('Slack bridge config updated', { workspaceId: this.config.workspaceId });
-  }
-
-  isRunning(): boolean {
-    return this.running;
-  }
-
-  // ─────────────────────────────────────────────────────────────
-  // Slack → Relay handlers
-  // ─────────────────────────────────────────────────────────────
-
-  private registerSlackHandlers(): void {
-    if (!this.slackApp) return;
-
-    // Handle @mentions
-    this.slackApp.event('app_mention', async ({ event, say }) => {
-      await this.handleMention(event, say);
-    });
-
-    // Handle DMs
-    this.slackApp.event('message', async ({ event, say }) => {
-      if (event.channel_type === 'im' && !event.bot_id) {
-        await this.handleDirectMessage(event, say);
-      }
-    });
-
-    // Handle thread replies
-    this.slackApp.event('message', async ({ event }) => {
-      if (event.thread_ts && event.thread_ts !== event.ts && !event.bot_id) {
-        await this.handleThreadReply(event);
-      }
-    });
-
-    // Slash command
-    this.slackApp.command('/relay', async ({ command, ack, respond }) => {
-      await ack();
-      await this.handleSlashCommand(command, respond);
-    });
-  }
-
-  private async handleMention(event: any, say: Function): Promise<void> {
-    // Extract agent name from message (e.g., "@relay Alice please help")
-    const agentMatch = event.text.match(/<@[A-Z0-9]+>\s*@?(\w+)\s*(.*)/s);
-
-    if (!agentMatch) {
-      await say({
-        text: 'Usage: @AgentRelay AgentName your message',
-        thread_ts: event.ts,
-      });
-      return;
-    }
-
-    const [, agentName, messageBody] = agentMatch;
-    const slackUser = await this.resolveUser(event.user);
-    const thread = this.threadStore.getOrCreate(event.thread_ts || event.ts, event.channel);
-
-    this.relayClient?.sendMessage(
-      agentName,
-      messageBody.trim(),
-      'message',
-      {
-        slack_user: slackUser,
-        slack_channel: event.channel,
-        slack_ts: event.ts,
-        slack_thread_ts: event.thread_ts,
-      },
-      thread
-    );
-
-    logger.debug('Forwarded Slack mention to relay', { agentName, slackUser });
-  }
-
-  private async handleDirectMessage(event: any, say: Function): Promise<void> {
-    // Parse agent target from DM: "Alice: help me" or just broadcast
-    const match = event.text.match(/^@?(\w+):\s*(.+)$/s);
-
-    const agentName = match ? match[1] : '*';
-    const messageBody = match ? match[2] : event.text;
-    const slackUser = await this.resolveUser(event.user);
-
-    this.relayClient?.sendMessage(
-      agentName,
-      messageBody.trim(),
-      'message',
-      {
-        slack_user: slackUser,
-        slack_channel: event.channel,
-        slack_ts: event.ts,
-        slack_dm: true,
-      }
-    );
-  }
-
-  private async handleThreadReply(event: any): Promise<void> {
-    const relayThread = this.threadStore.getRelayThread(event.thread_ts, event.channel);
-    if (!relayThread) return;  // Not a relay thread
-
-    const slackUser = await this.resolveUser(event.user);
-    const threadMeta = this.threadStore.getMeta(event.thread_ts, event.channel);
-
-    this.relayClient?.sendMessage(
-      threadMeta?.targetAgent || '*',
-      event.text,
-      'message',
-      {
-        slack_user: slackUser,
-        slack_thread_ts: event.thread_ts,
-      },
-      relayThread
-    );
-  }
-
-  private async handleSlashCommand(command: any, respond: Function): Promise<void> {
-    const match = command.text.match(/^@?(\w+)\s+(.+)$/s);
-
-    if (!match) {
-      await respond('Usage: /relay @AgentName your message');
-      return;
-    }
-
-    const [, agentName, messageBody] = match;
-    const slackUser = await this.resolveUser(command.user_id);
-
-    this.relayClient?.sendMessage(
-      agentName,
-      messageBody.trim(),
-      'message',
-      {
-        slack_user: slackUser,
-        slack_channel: command.channel_id,
-        slack_command: true,
-      }
-    );
-
-    await respond(`Message sent to ${agentName}`);
-  }
-
-  // ─────────────────────────────────────────────────────────────
-  // Relay → Slack handlers
-  // ─────────────────────────────────────────────────────────────
-
-  private async onRelayMessage(
-    from: string,
-    payload: { kind: string; body: string; data?: Record<string, unknown>; thread?: string },
-    messageId: string,
-    meta?: { importance?: number }
-  ): Promise<void> {
-    // Skip self-messages
-    if (from === 'SlackBridge') return;
-
-    // Skip messages originating from Slack (prevent loop)
-    if (payload.data?.slack_ts) return;
-
-    // Skip thinking unless configured
-    if (payload.kind === 'thinking' && !this.config.config.showThinking) return;
-
-    // Determine channel
-    let channel = this.config.broadcastChannel;
-    let threadTs: string | undefined;
-
-    // Reply to Slack conversation
-    if (payload.data?.slack_channel) {
-      channel = payload.data.slack_channel as string;
-      threadTs = payload.data.slack_thread_ts as string;
-    }
-    // High importance → alerts channel
-    else if (meta?.importance && meta.importance >= 80 && this.config.alertsChannel) {
-      channel = this.config.alertsChannel;
-    }
-    // Map relay thread to Slack thread
-    else if (payload.thread) {
-      const slackThread = this.threadStore.getSlackThread(payload.thread);
-      if (slackThread) {
-        channel = slackThread.channel;
-        threadTs = slackThread.ts;
-      }
-    }
-
-    if (!channel) {
-      logger.warn('No channel configured for Slack message');
-      return;
-    }
-
-    const formatted = this.formatter.format(from, payload);
-
-    try {
-      const result = await this.slackApp?.client.chat.postMessage({
-        channel,
-        text: formatted,
-        thread_ts: threadTs,
-        unfurl_links: false,
-        unfurl_media: false,
-      });
-
-      // Track thread mapping
-      if (result?.ts && payload.thread) {
-        this.threadStore.map(payload.thread, {
-          ts: result.ts,
-          channel,
-          targetAgent: from,
-        });
-      }
-    } catch (error) {
-      logger.error('Failed to post to Slack', { error, channel });
-    }
-  }
-
-  private onRelayStateChange(state: string): void {
-    logger.info('Slack bridge relay connection state', { state });
-  }
-
-  private async resolveUser(userId: string): Promise<string> {
-    try {
-      const result = await this.slackApp?.client.users.info({ user: userId });
-      return result?.user?.real_name || result?.user?.name || userId;
-    } catch {
-      return userId;
-    }
-  }
-}
-```
-
-### 4.2 Integration with Orchestrator (`src/daemon/orchestrator.ts`)
-
-```typescript
-// Addition to src/daemon/orchestrator.ts
-
-import { SlackBridge, SlackBridgeConfig } from './slack-bridge';
-
-export class DaemonOrchestrator {
-  private slackBridges: Map<string, SlackBridge> = new Map();
-
-  // Called during workspace initialization or when Slack is connected
-  async initializeSlackBridge(workspaceId: string): Promise<void> {
-    // Check if already running
-    if (this.slackBridges.has(workspaceId)) {
-      return;
-    }
-
-    // Get Slack config from cloud sync
-    const slackConfig = await this.cloudSync.getSlackConfig(workspaceId);
-    if (!slackConfig) {
-      logger.debug('No Slack integration for workspace', { workspaceId });
-      return;
-    }
-
-    const bridge = new SlackBridge({
-      ...slackConfig,
-      socketPath: this.getSocketPath(workspaceId),
-      workspaceId,
-    });
-
-    try {
-      await bridge.start();
-      this.slackBridges.set(workspaceId, bridge);
-      logger.info('Slack bridge initialized', { workspaceId });
-    } catch (error) {
-      logger.error('Failed to initialize Slack bridge', { workspaceId, error });
-    }
-  }
-
-  async stopSlackBridge(workspaceId: string): Promise<void> {
-    const bridge = this.slackBridges.get(workspaceId);
-    if (bridge) {
-      await bridge.stop();
-      this.slackBridges.delete(workspaceId);
-      logger.info('Slack bridge stopped', { workspaceId });
-    }
-  }
-
-  // Called when cloud sync receives Slack notification
-  async handleSlackNotification(workspaceId: string, event: string): Promise<void> {
-    switch (event) {
-      case 'slack:connect':
-        await this.initializeSlackBridge(workspaceId);
-        break;
-      case 'slack:disconnect':
-        await this.stopSlackBridge(workspaceId);
-        break;
-      case 'slack:config-update':
-        const bridge = this.slackBridges.get(workspaceId);
-        if (bridge) {
-          const newConfig = await this.cloudSync.getSlackConfig(workspaceId);
-          if (newConfig) {
-            await bridge.updateConfig(newConfig);
-          }
-        }
-        break;
-    }
-  }
-
-  // Health check includes Slack bridges
-  getHealth(): DaemonHealth {
-    return {
-      ...this.baseHealth(),
-      slackBridges: Array.from(this.slackBridges.entries()).map(([id, bridge]) => ({
-        workspaceId: id,
-        running: bridge.isRunning(),
-      })),
-    };
-  }
-}
-```
-
-### 4.3 Cloud Sync Extension (`src/daemon/cloud-sync.ts`)
-
-```typescript
-// Addition to src/daemon/cloud-sync.ts
-
-export class CloudSync {
-  /**
-   * Get Slack configuration for a workspace
-   * Called by orchestrator when initializing Slack bridge
-   */
-  async getSlackConfig(workspaceId: string): Promise<SlackBridgeConfig | null> {
-    try {
-      const response = await this.apiClient.get(
-        `/api/integrations/slack/daemon-config?workspaceId=${workspaceId}`
-      );
-
-      if (!response.data.connected) {
-        return null;
-      }
-
-      return response.data.config;
-    } catch (error) {
-      logger.error('Failed to fetch Slack config', { workspaceId, error });
-      return null;
-    }
-  }
-
-  /**
-   * Subscribe to Slack notifications
-   */
-  subscribeToSlackNotifications(callback: (workspaceId: string, event: string) => void): void {
-    // WebSocket subscription or polling
-    this.on('slack:notification', callback);
-  }
-}
-```
-
----
-
-## 5. Database Schema
-
-### 5.1 Drizzle Schema (`src/cloud/db/schema.ts`)
-
-```typescript
-// Addition to src/cloud/db/schema.ts
-
-import { pgTable, text, timestamp, jsonb, boolean } from 'drizzle-orm/pg-core';
-
-export const slackIntegrations = pgTable('slack_integrations', {
-  id: text('id').primaryKey(),
-  workspaceId: text('workspace_id').notNull().references(() => workspaces.id, { onDelete: 'cascade' }),
-
-  // Nango connection (handles OAuth, token storage, refresh)
-  nangoConnectionId: text('nango_connection_id').notNull(),
-  status: text('status').notNull().default('pending'), // pending, connected, error
-
-  // Slack workspace info (populated after OAuth)
-  slackTeamId: text('slack_team_id'),
-  slackWorkspaceName: text('slack_workspace_name'),
-
-  // Channel configuration
-  broadcastChannel: text('broadcast_channel'),
-  alertsChannel: text('alerts_channel'),
-
-  // Behavior configuration
-  config: jsonb('config').$type<{
-    showAgentToAgent?: boolean;
-    showThinking?: boolean;
-    threadTTLHours?: number;
-  }>().default({}),
-
-  // Metadata
-  connectedByUserId: text('connected_by_user_id').references(() => users.id),
-  createdAt: timestamp('created_at').defaultNow().notNull(),
-  updatedAt: timestamp('updated_at').defaultNow().notNull(),
-});
-
-export const slackChannelMappings = pgTable('slack_channel_mappings', {
-  id: text('id').primaryKey(),
-  integrationId: text('integration_id').notNull().references(() => slackIntegrations.id, { onDelete: 'cascade' }),
-
-  // Relay topic → Slack channel mapping
-  relayTopic: text('relay_topic').notNull(),
-  slackChannelId: text('slack_channel_id').notNull(),
-  slackChannelName: text('slack_channel_name'),
-
-  createdAt: timestamp('created_at').defaultNow().notNull(),
-});
-
-// Index for fast lookup
-export const slackIntegrationsWorkspaceIdx = index('slack_integrations_workspace_idx')
-  .on(slackIntegrations.workspaceId);
-```
-
-### 5.2 SQL Migration
-
-```sql
--- deploy/migrations/004_slack_integrations.sql
-
-CREATE TABLE slack_integrations (
-  id TEXT PRIMARY KEY,
-  workspace_id TEXT NOT NULL REFERENCES workspaces(id) ON DELETE CASCADE,
-  nango_connection_id TEXT NOT NULL,
-  status TEXT NOT NULL DEFAULT 'pending',
-  slack_team_id TEXT,
-  slack_workspace_name TEXT,
-  broadcast_channel TEXT,
-  alerts_channel TEXT,
-  config JSONB DEFAULT '{}',
-  connected_by_user_id TEXT REFERENCES users(id),
-  created_at TIMESTAMP DEFAULT NOW() NOT NULL,
-  updated_at TIMESTAMP DEFAULT NOW() NOT NULL
-);
-
-CREATE INDEX slack_integrations_workspace_idx ON slack_integrations(workspace_id);
-
-CREATE TABLE slack_channel_mappings (
-  id TEXT PRIMARY KEY,
-  integration_id TEXT NOT NULL REFERENCES slack_integrations(id) ON DELETE CASCADE,
-  relay_topic TEXT NOT NULL,
-  slack_channel_id TEXT NOT NULL,
-  slack_channel_name TEXT,
-  created_at TIMESTAMP DEFAULT NOW() NOT NULL
-);
-
-CREATE INDEX slack_channel_mappings_integration_idx ON slack_channel_mappings(integration_id);
-```
-
----
-
-## 6. Dashboard UI
-
-### 6.1 Slack Integration Panel (`src/dashboard/react-components/SlackIntegrationPanel.tsx`)
-
-```typescript
-// src/dashboard/react-components/SlackIntegrationPanel.tsx
-
-import React, { useState, useEffect } from 'react';
-import { useSession } from './hooks/useSession';
-import { api } from '../lib/api';
-
-interface SlackStatus {
-  connected: boolean;
-  valid?: boolean;
-  slackWorkspace?: string;
-  channels?: {
-    broadcast: string | null;
-    alerts: string | null;
-  };
-  connectedAt?: string;
-}
-
-export function SlackIntegrationPanel({ workspaceId }: { workspaceId: string }) {
-  const { plan } = useSession();
-  const [status, setStatus] = useState<SlackStatus | null>(null);
-  const [channels, setChannels] = useState<{ id: string; name: string }[]>([]);
-  const [loading, setLoading] = useState(true);
-  const [configuring, setConfiguring] = useState(false);
-
-  // Config form state
-  const [broadcastChannel, setBroadcastChannel] = useState('');
-  const [alertsChannel, setAlertsChannel] = useState('');
-  const [showAgentToAgent, setShowAgentToAgent] = useState(true);
-
-  useEffect(() => {
-    loadStatus();
-  }, [workspaceId]);
-
-  async function loadStatus() {
-    setLoading(true);
-    try {
-      const res = await api.get(`/api/integrations/slack/status?workspaceId=${workspaceId}`);
-      setStatus(res.data);
-      if (res.data.connected) {
-        setBroadcastChannel(res.data.channels?.broadcast || '');
-        setAlertsChannel(res.data.channels?.alerts || '');
-        loadChannels();
-      }
-    } catch (error) {
-      console.error('Failed to load Slack status', error);
-    }
-    setLoading(false);
-  }
-
-  async function loadChannels() {
-    try {
-      const res = await api.get(`/api/integrations/slack/channels?workspaceId=${workspaceId}`);
-      setChannels(res.data.channels);
-    } catch (error) {
-      console.error('Failed to load channels', error);
-    }
-  }
-
-  async function handleConnect() {
-    try {
-      const res = await api.get(`/api/integrations/slack/oauth/start?workspaceId=${workspaceId}`);
-      window.location.href = res.data.authUrl;
-    } catch (error) {
-      console.error('Failed to start OAuth', error);
-    }
-  }
-
-  async function handleDisconnect() {
-    if (!confirm('Disconnect Slack integration?')) return;
-
-    try {
-      await api.post('/api/integrations/slack/disconnect', { workspaceId });
-      setStatus({ connected: false });
-    } catch (error) {
-      console.error('Failed to disconnect', error);
-    }
-  }
-
-  async function handleSaveConfig() {
-    setConfiguring(true);
-    try {
-      await api.put('/api/integrations/slack/config', {
-        workspaceId,
-        broadcastChannel,
-        alertsChannel,
-        showAgentToAgent,
-      });
-      await loadStatus();
-    } catch (error) {
-      console.error('Failed to save config', error);
-    }
-    setConfiguring(false);
-  }
-
-  // Plan check
-  if (plan === 'free') {
-    return (
-      <div className="slack-panel disabled">
-        <h3>Slack Integration</h3>
-        <p>Slack integration is available on Pro plans and above.</p>
-        <a href="/pricing" className="upgrade-btn">Upgrade to Pro</a>
-      </div>
-    );
-  }
-
-  if (loading) {
-    return <div className="slack-panel loading">Loading...</div>;
-  }
-
-  return (
-    <div className="slack-panel">
-      <h3>Slack Integration</h3>
-
-      {!status?.connected ? (
-        <div className="slack-connect">
-          <p>Connect Slack to see agent messages in your workspace.</p>
-          <button onClick={handleConnect} className="connect-btn">
-            <SlackLogo /> Connect to Slack
-          </button>
-        </div>
-      ) : (
-        <div className="slack-connected">
-          <div className="status-row">
-            <span className={`status-dot ${status.valid ? 'green' : 'red'}`} />
-            <span>Connected to <strong>{status.slackWorkspace}</strong></span>
-            <button onClick={handleDisconnect} className="disconnect-btn">Disconnect</button>
-          </div>
-
-          <div className="config-section">
-            <h4>Channel Configuration</h4>
-
-            <label>
-              Broadcast Channel
-              <select value={broadcastChannel} onChange={e => setBroadcastChannel(e.target.value)}>
-                <option value="">Select channel...</option>
-                {channels.map(ch => (
-                  <option key={ch.id} value={ch.id}>#{ch.name}</option>
-                ))}
-              </select>
-            </label>
-
-            <label>
-              Alerts Channel (optional)
-              <select value={alertsChannel} onChange={e => setAlertsChannel(e.target.value)}>
-                <option value="">None</option>
-                {channels.map(ch => (
-                  <option key={ch.id} value={ch.id}>#{ch.name}</option>
-                ))}
-              </select>
-            </label>
-
-            <label className="checkbox">
-              <input
-                type="checkbox"
-                checked={showAgentToAgent}
-                onChange={e => setShowAgentToAgent(e.target.checked)}
-              />
-              Show agent-to-agent messages
-            </label>
-
-            <button onClick={handleSaveConfig} disabled={configuring}>
-              {configuring ? 'Saving...' : 'Save Configuration'}
-            </button>
-          </div>
-        </div>
-      )}
-    </div>
-  );
-}
-```
-
-### 6.2 Integration into Settings Page
-
-```typescript
-// In src/dashboard/app/workspace/[id]/settings/page.tsx
-
-import { SlackIntegrationPanel } from '@/react-components/SlackIntegrationPanel';
-
-export default function WorkspaceSettings({ params }) {
-  return (
-    <div className="settings-page">
-      <h2>Workspace Settings</h2>
-
-      {/* Other settings... */}
-
-      <section className="integrations-section">
-        <h3>Integrations</h3>
-        <SlackIntegrationPanel workspaceId={params.id} />
-        {/* Future: Discord, Teams, etc. */}
-      </section>
-    </div>
-  );
-}
-```
-
----
-
-## 7. Implementation Phases
-
-### Phase 1: Cloud Infrastructure (Days 1-2)
-
-- [ ] Database schema and migration
-- [ ] Slack OAuth API routes
-- [ ] SlackService for token management
-- [ ] Vault integration for credentials
-- [ ] Plan limit middleware
-
-### Phase 2: Daemon Bridge (Days 2-4)
-
-- [ ] SlackBridge class (Slack ↔ Relay)
-- [ ] Thread store for mapping
-- [ ] Message formatter
-- [ ] Orchestrator integration
-- [ ] Cloud sync for credentials
-
-### Phase 3: Dashboard UI (Days 4-5)
-
-- [ ] SlackIntegrationPanel component
-- [ ] OAuth flow UI
-- [ ] Channel configuration
-- [ ] Status display
-
-### Phase 4: Testing & Polish (Days 5-7)
-
-- [ ] Unit tests for services
-- [ ] Integration tests
-- [ ] E2E flow testing
-- [ ] Documentation
-- [ ] Error handling & edge cases
-
----
-
-## 8. API Specifications
-
-### 8.1 Cloud API Endpoints
-
-| Method | Path | Description | Auth |
-|--------|------|-------------|------|
-| GET | `/api/integrations/slack/status` | Get integration status | Pro+ |
-| GET | `/api/integrations/slack/oauth/start` | Start OAuth flow | Pro+ |
-| GET | `/api/integrations/slack/oauth/callback` | OAuth callback | Pro+ |
-| POST | `/api/integrations/slack/disconnect` | Remove integration | Pro+ |
-| PUT | `/api/integrations/slack/config` | Update config | Pro+ |
-| GET | `/api/integrations/slack/channels` | List Slack channels | Pro+ |
-| GET | `/api/integrations/slack/daemon-config` | Get config for daemon | Internal |
-
-### 8.2 Daemon Sync API
-
-```typescript
-// Called by daemon cloud-sync
-GET /api/integrations/slack/daemon-config?workspaceId=xxx
-Authorization: Bearer <daemon-token>
-
-Response:
-{
-  "connected": true,
-  "config": {
-    "botToken": "xoxb-...",
-    "appToken": "xapp-...",
-    "teamId": "T123",
-    "teamName": "My Workspace",
-    "broadcastChannel": "C456",
-    "alertsChannel": null,
-    "config": { "showAgentToAgent": true }
-  }
-}
-```
-
----
-
-## 9. Security & Plan Limits
-
-### 9.1 Plan-Based Access
-
-| Plan | Slack Integration |
-|------|-------------------|
-| Free | ❌ Not available |
-| Pro | ✅ 1 Slack workspace |
-| Team | ✅ 1 Slack workspace per relay workspace |
-| Enterprise | ✅ Multiple + Enterprise Grid |
-
-### 9.2 Credential Security (via Nango)
-
-- **Encrypted storage**: Nango encrypts all tokens at rest (SOC 2 compliant)
-- **Token refresh**: Automatic refresh before expiry, no manual logic needed
-- **Revocation**: `nango.deleteConnection()` revokes and removes tokens
-- **No local storage**: Credentials fetched on-demand, never written to disk
-- **Audit logging**: Nango provides connection activity logs
-
-### 9.3 Plan Limit Middleware
-
-```typescript
-// src/cloud/api/middleware/planLimits.ts
-
-export function requireSlackAccess(req, res, next) {
-  const plan = req.user.plan;
-
-  if (plan === 'free') {
-    return res.status(403).json({
-      error: 'Slack integration requires Pro plan or above',
-      upgrade: '/pricing',
-    });
-  }
-
-  next();
-}
-```
-
----
-
-## 10. Testing Strategy
-
-### 10.1 Unit Tests
-
-```typescript
-// src/cloud/services/__tests__/slack.test.ts
-describe('SlackService', () => {
-  it('builds correct OAuth URL', () => { ... });
-  it('validates tokens correctly', () => { ... });
-  it('handles token revocation', () => { ... });
-});
-
-// src/daemon/__tests__/slack-bridge.test.ts
-describe('SlackBridge', () => {
-  it('forwards relay broadcasts to Slack', () => { ... });
-  it('forwards Slack mentions to relay', () => { ... });
-  it('maps threads bidirectionally', () => { ... });
-  it('prevents message loops', () => { ... });
-});
-```
-
-### 10.2 Integration Tests
-
-```typescript
-describe('Slack Integration E2E', () => {
-  it('completes OAuth flow and stores credentials', async () => { ... });
-  it('daemon receives credentials via cloud sync', async () => { ... });
-  it('messages flow relay → slack → relay', async () => { ... });
-});
-```
-
----
-
-## 11. Open Questions
-
-### Q1: Slack App Distribution?
-
-**Options:**
-1. **Single Anthropic-owned app**: Users install our app
-2. **Per-customer apps**: Customers create their own Slack apps
-3. **Both**: Managed app for cloud, bring-your-own for self-hosted
-
-**Recommendation:** Single managed app for cloud, instructions for self-hosted.
-
-### Q2: Enterprise Grid Support?
-
-Enterprise Grid requires org-level OAuth and cross-workspace routing.
-
-**Recommendation:** Defer to v2, design schema to support it.
-
-### Q3: Rate Limit Handling?
-
-Slack has strict rate limits (1 msg/sec/channel).
-
-**Recommendation:** Implement queue with backoff in SlackBridge.
-
----
-
-## Summary
-
-This revised proposal aligns Slack integration with the **cloud-first architecture** from PR #35:
-
-| Component | Location | Purpose |
-|-----------|----------|---------|
-| OAuth & API | `src/cloud/api/integrations/slack.ts` | Cloud endpoints |
-| Slack Service | `src/cloud/services/slack.ts` | Token retrieval via Nango |
-| Credentials | Nango (external) | OAuth, storage, refresh |
-| Database | `src/cloud/db/schema.ts` | Integration config (channels, settings) |
-| Daemon Bridge | `src/daemon/slack-bridge.ts` | Message routing |
-| Orchestrator | `src/daemon/orchestrator.ts` | Lifecycle management |
-| Cloud Sync | `src/daemon/cloud-sync.ts` | Credential retrieval |
-| Dashboard | `src/dashboard/react-components/` | Configuration UI |
-
-The integration uses Nango for OAuth/credentials (same pattern planned for other providers like Discord, Teams), keeping our code focused on the Slack ↔ Relay bridge logic.