@desplega.ai/agent-swarm 1.2.0 → 1.9.0

package/src/slack/app.ts

@@ -0,0 +1,73 @@
+import { App, LogLevel } from "@slack/bolt";
+import { startTaskWatcher, stopTaskWatcher } from "./watcher";
+
+let app: App | null = null;
+let initialized = false;
+
+export function getSlackApp(): App | null {
+  return app;
+}
+
+export async function initSlackApp(): Promise<App | null> {
+  // Prevent double initialization
+  if (initialized) {
+    console.log("[Slack] Already initialized, skipping");
+    return app;
+  }
+  initialized = true;
+
+  // Check if Slack is explicitly disabled
+  const slackDisable = process.env.SLACK_DISABLE;
+  if (slackDisable === "true" || slackDisable === "1") {
+    console.log("[Slack] Disabled via SLACK_DISABLE");
+    return null;
+  }
+
+  const botToken = process.env.SLACK_BOT_TOKEN;
+  const appToken = process.env.SLACK_APP_TOKEN;
+
+  if (!botToken || !appToken) {
+    console.log("[Slack] Missing SLACK_BOT_TOKEN or SLACK_APP_TOKEN, Slack integration disabled");
+    return null;
+  }
+
+  app = new App({
+    token: botToken,
+    appToken: appToken,
+    socketMode: true,
+    logLevel: process.env.NODE_ENV === "development" ? LogLevel.DEBUG : LogLevel.INFO,
+  });
+
+  // Register handlers
+  const { registerMessageHandler } = await import("./handlers");
+  const { registerCommandHandler } = await import("./commands");
+
+  registerMessageHandler(app);
+  registerCommandHandler(app);
+
+  return app;
+}
+
+export async function startSlackApp(): Promise<void> {
+  if (!app) {
+    await initSlackApp();
+  }
+
+  if (app) {
+    await app.start();
+    console.log("[Slack] Bot connected via Socket Mode");
+
+    // Start watching for task completions
+    startTaskWatcher();
+  }
+}
+
+export async function stopSlackApp(): Promise<void> {
+  stopTaskWatcher();
+
+  if (app) {
+    await app.stop();
+    app = null;
+    console.log("[Slack] Bot disconnected");
+  }
+}

package/src/slack/commands.ts

@@ -0,0 +1,88 @@
+import type { App } from "@slack/bolt";
+import { getAllAgents, getAllTasks } from "../be/db";
+
+export function registerCommandHandler(app: App): void {
+  app.command("/agent-swarm-status", async ({ ack, respond }) => {
+    await ack();
+
+    const agents = getAllAgents();
+    const tasks = getAllTasks({ status: "in_progress" });
+
+    const statusEmoji: Record<string, string> = {
+      idle: ":white_circle:",
+      busy: ":large_blue_circle:",
+      offline: ":black_circle:",
+    };
+
+    const agentLines = agents.map((agent) => {
+      const emoji = statusEmoji[agent.status] || ":question:";
+      const role = agent.isLead ? " (Lead)" : "";
+      const activeTask = tasks.find((t) => t.agentId === agent.id);
+      const taskInfo = activeTask ? ` - Working on: ${activeTask.task.slice(0, 50)}...` : "";
+      return `${emoji} *${agent.name}*${role}: ${agent.status}${taskInfo}`;
+    });
+
+    const summary = {
+      total: agents.length,
+      idle: agents.filter((a) => a.status === "idle").length,
+      busy: agents.filter((a) => a.status === "busy").length,
+      offline: agents.filter((a) => a.status === "offline").length,
+    };
+
+    await respond({
+      response_type: "ephemeral",
+      blocks: [
+        {
+          type: "header",
+          text: { type: "plain_text", text: "Agent Swarm Status" },
+        },
+        {
+          type: "section",
+          text: {
+            type: "mrkdwn",
+            text: `*Summary:* ${summary.total} agents (${summary.idle} idle, ${summary.busy} busy, ${summary.offline} offline)`,
+          },
+        },
+        {
+          type: "divider",
+        },
+        {
+          type: "section",
+          text: {
+            type: "mrkdwn",
+            text: agentLines.join("\n") || "_No agents registered_",
+          },
+        },
+      ],
+    });
+  });
+
+  app.command("/agent-swarm-help", async ({ ack, respond }) => {
+    await ack();
+
+    await respond({
+      response_type: "ephemeral",
+      blocks: [
+        {
+          type: "header",
+          text: { type: "plain_text", text: "Agent Swarm Help" },
+        },
+        {
+          type: "section",
+          text: {
+            type: "mrkdwn",
+            text: `*How to assign tasks:*
+• Mention an agent by name: \`Hey Alpha, can you review this code?\`
+• Use explicit ID: \`swarm#<uuid> please analyze the logs\`
+• Broadcast to all: \`swarm#all status report please\`
+• Mention the bot: \`@agent-swarm help me\` (routes to lead agent)
+
+*Commands:*
+• \`/agent-swarm-status\` - Show all agents and their current status
+• \`/agent-swarm-help\` - Show this help message`,
+          },
+        },
+      ],
+    });
+  });
+}

package/src/slack/handlers.ts

@@ -0,0 +1,281 @@
+import type { App } from "@slack/bolt";
+import type { WebClient } from "@slack/web-api";
+import { createTask, getAgentById, getTasksByAgentId } from "../be/db";
+import { extractTaskFromMessage, routeMessage } from "./router";
+
+interface MessageEvent {
+  type: string;
+  subtype?: string;
+  text?: string;
+  user?: string;
+  channel: string;
+  ts: string;
+  thread_ts?: string;
+}
+
+interface ThreadMessage {
+  user?: string;
+  text?: string;
+  ts: string;
+}
+
+// Cache for user display names
+const userNameCache = new Map<string, string>();
+
+async function getUserDisplayName(client: WebClient, userId: string): Promise<string> {
+  if (userNameCache.has(userId)) {
+    // biome-ignore lint: This is fine
+    return userNameCache.get(userId)!;
+  }
+  try {
+    const result = await client.users.info({ user: userId });
+    const name = result.user?.profile?.display_name || result.user?.real_name || userId;
+    userNameCache.set(userId, name);
+    return name;
+  } catch {
+    return userId;
+  }
+}
+
+/**
+ * Fetch thread history and format as context for the task.
+ * Returns empty string if not in a thread or no previous messages.
+ */
+async function getThreadContext(
+  client: WebClient,
+  channel: string,
+  threadTs: string | undefined,
+  currentTs: string,
+  botUserId: string,
+): Promise<string> {
+  // Not in a thread - no context needed
+  if (!threadTs) return "";
+
+  try {
+    const result = await client.conversations.replies({
+      channel,
+      ts: threadTs,
+      limit: 20, // Last 20 messages max
+    });
+
+    const messages = (result.messages || []) as ThreadMessage[];
+    // Filter out the current message only (keep bot messages for context)
+    const previousMessages = messages.filter((m) => m.ts !== currentTs && m.text);
+
+    if (previousMessages.length === 0) return "";
+
+    // Format messages with user names or [Agent] for bot messages
+    const formattedMessages: string[] = [];
+    for (const m of previousMessages) {
+      if (m.user === botUserId) {
+        // Bot/agent message - truncate if too long
+        const truncatedText = m.text && m.text.length > 500 ? `${m.text.slice(0, 500)}...` : m.text;
+        formattedMessages.push(`[Agent]: ${truncatedText}`);
+      } else {
+        const userName = m.user ? await getUserDisplayName(client, m.user) : "Unknown";
+        formattedMessages.push(`${userName}: ${m.text}`);
+      }
+    }
+
+    return `<thread_context>\n${formattedMessages.join("\n")}\n</thread_context>\n\n`;
+  } catch (error) {
+    console.error("[Slack] Failed to fetch thread context:", error);
+    return "";
+  }
+}
+
+const appUrl = process.env.APP_URL || "";
+
+/**
+ * Get a link to the task in the dashboard, or just the task ID if no APP_URL.
+ */
+function getTaskLink(taskId: string): string {
+  const shortId = taskId.slice(0, 8);
+  if (appUrl) {
+    return `<${appUrl}?tab=tasks&task=${taskId}&expand=true|\`${shortId}\`>`;
+  }
+  return `\`${shortId}\``;
+}
+
+// Message deduplication (prevents duplicate event processing)
+const processedMessages = new Set<string>();
+const MESSAGE_DEDUP_TTL = 60_000; // 1 minute
+
+function isMessageProcessed(messageKey: string): boolean {
+  if (processedMessages.has(messageKey)) {
+    console.log(`[Slack] Duplicate event detected: ${messageKey}`);
+    return true;
+  }
+  processedMessages.add(messageKey);
+  setTimeout(() => processedMessages.delete(messageKey), MESSAGE_DEDUP_TTL);
+  console.log(`[Slack] Processing new message: ${messageKey}`);
+  return false;
+}
+
+// Rate limiting
+const rateLimitMap = new Map<string, number>();
+const RATE_LIMIT_WINDOW = 60_000; // 1 minute
+const MAX_REQUESTS_PER_WINDOW = 10;
+
+function checkRateLimit(userId: string): boolean {
+  const userRequests = rateLimitMap.get(userId) || 0;
+
+  if (userRequests >= MAX_REQUESTS_PER_WINDOW) {
+    return false;
+  }
+
+  rateLimitMap.set(userId, userRequests + 1);
+
+  // Decrement after window
+  setTimeout(() => {
+    const current = rateLimitMap.get(userId) || 0;
+    if (current > 0) {
+      rateLimitMap.set(userId, current - 1);
+    }
+  }, RATE_LIMIT_WINDOW);
+
+  return true;
+}
+
+export function registerMessageHandler(app: App): void {
+  // Handle all message events
+  app.event("message", async ({ event, client, say }) => {
+    // Ignore bot messages and message_changed events
+    if (
+      "subtype" in event &&
+      (event.subtype === "bot_message" || event.subtype === "message_changed")
+    ) {
+      return;
+    }
+
+    const msg = event as MessageEvent;
+    if (!msg.text || !msg.user) return;
+
+    // Deduplicate events (Slack can send same event twice)
+    const messageKey = `${msg.channel}:${msg.ts}`;
+    if (isMessageProcessed(messageKey)) {
+      return;
+    }
+
+    // Get bot's user ID
+    const authResult = await client.auth.test();
+    const botUserId = authResult.user_id as string;
+
+    // Check if bot was mentioned
+    const botMentioned = msg.text.includes(`<@${botUserId}>`);
+
+    // Build thread context for routing (if we're in a thread)
+    const routingThreadContext = msg.thread_ts
+      ? { channelId: msg.channel, threadTs: msg.thread_ts }
+      : undefined;
+
+    // Route message to agents
+    const matches = routeMessage(msg.text, botUserId, botMentioned, routingThreadContext);
+
+    if (matches.length === 0) {
+      // No agents matched - ignore message unless bot was directly mentioned
+      if (botMentioned) {
+        await say({
+          text: ":satellite: _No agents are currently available. Use `/agent-swarm-status` to check the swarm._",
+          thread_ts: msg.thread_ts || msg.ts,
+        });
+      }
+      return;
+    }
+
+    // Rate limit check
+    if (!checkRateLimit(msg.user)) {
+      await say({
+        text: ":satellite: _You're sending too many requests. Please slow down._",
+        thread_ts: msg.thread_ts || msg.ts,
+      });
+      return;
+    }
+
+    // Extract task description
+    const taskDescription = extractTaskFromMessage(msg.text, botUserId);
+    if (!taskDescription) {
+      await say({
+        text: ":satellite: _Please provide a task description after mentioning an agent._",
+        thread_ts: msg.thread_ts || msg.ts,
+      });
+      return;
+    }
+
+    // Create tasks for each matched agent
+    const threadTs = msg.thread_ts || msg.ts;
+
+    // Fetch thread context if in a thread
+    const threadContext = await getThreadContext(
+      client,
+      msg.channel,
+      msg.thread_ts,
+      msg.ts,
+      botUserId,
+    );
+    const fullTaskDescription = threadContext + taskDescription;
+    const results: { assigned: string[]; queued: string[]; failed: string[] } = {
+      assigned: [],
+      queued: [],
+      failed: [],
+    };
+
+    for (const match of matches) {
+      const agent = getAgentById(match.agent.id);
+
+      if (!agent) {
+        results.failed.push(`\`${match.agent.name}\` (not found)`);
+        continue;
+      }
+
+      try {
+        const task = createTask(agent.id, fullTaskDescription, {
+          source: "slack",
+          slackChannelId: msg.channel,
+          slackThreadTs: threadTs,
+          slackUserId: msg.user,
+        });
+
+        // Check if agent has an in-progress task in this thread (queued follow-up)
+        const agentTasks = getTasksByAgentId(agent.id);
+        const inProgressInThread = agentTasks.find(
+          (t) => t.id !== task.id && t.status === "in_progress" && t.slackThreadTs === threadTs,
+        );
+
+        if (inProgressInThread) {
+          results.queued.push(`*${agent.name}* (${getTaskLink(task.id)})`);
+        } else {
+          results.assigned.push(`*${agent.name}* (${getTaskLink(task.id)})`);
+        }
+      } catch {
+        results.failed.push(`\`${agent.name}\` (error)`);
+      }
+    }
+
+    // Send consolidated summary
+    const parts: string[] = [];
+    if (results.assigned.length > 0) {
+      parts.push(`:satellite: _Task assigned to: ${results.assigned.join(", ")}_`);
+    }
+    if (results.queued.length > 0) {
+      parts.push(`:satellite: _Task queued for: ${results.queued.join(", ")}_`);
+    }
+    if (results.failed.length > 0) {
+      parts.push(`:satellite: _Could not assign to: ${results.failed.join(", ")}_`);
+    }
+
+    if (parts.length > 0) {
+      await say({
+        text: parts.join("\n"),
+        thread_ts: msg.thread_ts || msg.ts,
+      });
+    }
+  });
+
+  // Handle app_mention events specifically
+  app.event("app_mention", async ({ event }) => {
+    // app_mention is already handled by the message event above
+    // but we can add specific behavior here if needed
+    console.log(`[Slack] App mentioned in channel ${event.channel}`);
+  });
+}

package/src/slack/index.ts

@@ -0,0 +1,3 @@
+export { getSlackApp, initSlackApp, startSlackApp, stopSlackApp } from "./app";
+export { extractTaskFromMessage, routeMessage } from "./router";
+export type { AgentMatch, SlackConfig, SlackMessageContext } from "./types";

package/src/slack/responses.ts

@@ -0,0 +1,175 @@
+import type { WebClient } from "@slack/web-api";
+import { getAgentById } from "../be/db";
+import type { Agent, AgentTask } from "../types";
+import { getSlackApp } from "./app";
+
+const isDev = process.env.ENV === "development";
+const appUrl = process.env.APP_URL || "";
+
+/**
+ * Convert GitHub-flavored markdown to Slack mrkdwn format.
+ */
+function markdownToSlack(text: string): string {
+  return (
+    text
+      // Headers to bold (# Header -> *Header*)
+      .replace(/^#{1,6}\s+(.+)$/gm, "*$1*")
+      // Bold **text** -> *text*
+      .replace(/\*\*(.+?)\*\*/g, "*$1*")
+      // Links [text](url) -> <url|text>
+      .replace(/\[([^\]]+)\]\(([^)]+)\)/g, "<$2|$1>")
+      // Inline code already works the same
+      // Bullet points already work the same
+      // Remove excessive blank lines
+      .replace(/\n{3,}/g, "\n\n")
+  );
+}
+
+/**
+ * Get the display name for an agent, with (dev) prefix if in development mode.
+ */
+function getAgentDisplayName(agent: Agent): string {
+  return isDev ? `(dev) ${agent.name}` : agent.name;
+}
+
+/**
+ * Get a link to the task in the dashboard, or just the task ID if no APP_URL.
+ */
+function getTaskLink(taskId: string): string {
+  const shortId = taskId.slice(0, 8);
+  if (appUrl) {
+    return `<${appUrl}?tab=tasks&task=${taskId}&expand=true|\`${shortId}\`>`;
+  }
+  return `\`${shortId}\``;
+}
+
+/**
+ * Send a task completion message to Slack with the agent's persona.
+ */
+export async function sendTaskResponse(task: AgentTask): Promise<boolean> {
+  const app = getSlackApp();
+  if (!app || !task.slackChannelId || !task.slackThreadTs) {
+    return false;
+  }
+
+  if (!task.agentId) {
+    console.error(`[Slack] Task ${task.id} has no assigned agent`);
+    return false;
+  }
+
+  const agent = getAgentById(task.agentId);
+  if (!agent) {
+    console.error(`[Slack] Agent not found for task ${task.id}`);
+    return false;
+  }
+
+  const client = app.client;
+  const taskLink = getTaskLink(task.id);
+  const footer = `_Check the full logs at ${taskLink}_`;
+
+  try {
+    if (task.status === "completed") {
+      const output = task.output || "_Task completed._";
+      const slackOutput = markdownToSlack(output);
+      await sendWithPersona(client, {
+        channel: task.slackChannelId,
+        thread_ts: task.slackThreadTs,
+        text: `${slackOutput}\n\n${footer}`,
+        username: getAgentDisplayName(agent),
+        icon_emoji: getAgentEmoji(agent),
+      });
+    } else if (task.status === "failed") {
+      const reason = task.failureReason || "Unknown error";
+      await sendWithPersona(client, {
+        channel: task.slackChannelId,
+        thread_ts: task.slackThreadTs,
+        text: `:x: *Task failed*\n\`\`\`${reason}\`\`\`\n${footer}`,
+        username: getAgentDisplayName(agent),
+        icon_emoji: getAgentEmoji(agent),
+      });
+    }
+
+    return true;
+  } catch (error) {
+    console.error(`[Slack] Failed to send response for task ${task.id}:`, error);
+    return false;
+  }
+}
+
+/**
+ * Send a progress update to Slack.
+ */
+export async function sendProgressUpdate(task: AgentTask, progress: string): Promise<boolean> {
+  const app = getSlackApp();
+  if (!app || !task.slackChannelId || !task.slackThreadTs) {
+    return false;
+  }
+
+  if (!task.agentId) return false;
+
+  const agent = getAgentById(task.agentId);
+  if (!agent) return false;
+
+  const taskLink = getTaskLink(task.id);
+  const footer = `_Check progress at ${taskLink}_`;
+
+  try {
+    await sendWithPersona(app.client, {
+      channel: task.slackChannelId,
+      thread_ts: task.slackThreadTs,
+      text: `:hourglass_flowing_sand: _${progress}_\n\n${footer}`,
+      username: getAgentDisplayName(agent),
+      icon_emoji: getAgentEmoji(agent),
+    });
+    return true;
+  } catch (error) {
+    console.error(`[Slack] Failed to send progress update:`, error);
+    return false;
+  }
+}
+
+async function sendWithPersona(
+  client: WebClient,
+  options: {
+    channel: string;
+    thread_ts: string;
+    text: string;
+    username: string;
+    icon_emoji: string;
+  },
+): Promise<void> {
+  await client.chat.postMessage({
+    channel: options.channel,
+    thread_ts: options.thread_ts,
+    text: options.text, // Fallback for notifications
+    username: options.username,
+    icon_emoji: options.icon_emoji,
+    blocks: [
+      {
+        type: "section",
+        text: {
+          type: "mrkdwn",
+          text: options.text,
+        },
+      },
+    ],
+  });
+}
+
+function getAgentEmoji(agent: Agent): string {
+  if (agent.isLead) return ":crown:";
+
+  // Generate consistent emoji based on agent name hash
+  const emojis = [
+    ":robot_face:",
+    ":gear:",
+    ":zap:",
+    ":rocket:",
+    ":star:",
+    ":crystal_ball:",
+    ":bulb:",
+    ":wrench:",
+  ];
+  const hash = agent.name.split("").reduce((acc, char) => acc + char.charCodeAt(0), 0);
+  return emojis[hash % emojis.length] ?? ":robot_face:";
+}